mirror of
https://github.com/anomalyco/opencode.git
synced 2026-07-24 20:25:36 -04:00
chore: cleanup unused and debug files
Removed: - packages/enterprise/test-debug.ts (debug script) - packages/agent-core/src/util/scrap.ts (unused utility) - .agent-core/tool/*.txt (tool outputs) Added: - docs/ALPHA_ROLLBACK_PLAN.md (launch documentation) - docs/ENVIRONMENT_VARIABLES.md (configuration docs) - docs/LOGGING.md (logging documentation) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Artur Do Lago
@@ -1,10 +0,0 @@
|
||||
Use this tool to search GitHub pull requests by title and description.
|
||||
|
||||
This tool searches PRs in the sst/opencode repository and returns LLM-friendly results including:
|
||||
- PR number and title
|
||||
- Author
|
||||
- State (open/closed/merged)
|
||||
- Labels
|
||||
- Description snippet
|
||||
|
||||
Use the query parameter to search for keywords that might appear in PR titles or descriptions.
|
||||
@@ -1,88 +0,0 @@
|
||||
Use this tool to assign and/or label a Github issue.
|
||||
|
||||
You can assign the following users:
|
||||
- thdxr
|
||||
- adamdotdevin
|
||||
- fwang
|
||||
- jayair
|
||||
- kommander
|
||||
- rekram1-node
|
||||
|
||||
|
||||
You can use the following labels:
|
||||
- nix
|
||||
- opentui
|
||||
- perf
|
||||
- web
|
||||
- zen
|
||||
- docs
|
||||
|
||||
Always try to assign an issue, if in doubt, assign rekram1-node to it.
|
||||
|
||||
## Breakdown of responsibilities:
|
||||
|
||||
### thdxr
|
||||
|
||||
Dax is responsible for managing core parts of the application, for large feature requests, api changes, or things that require significant changes to the codebase assign him.
|
||||
|
||||
This relates to OpenCode server primarily but has overlap with just about anything
|
||||
|
||||
### adamdotdevin
|
||||
|
||||
Adam is responsible for managing the Desktop/Web app. If there is an issue relating to the desktop app or `opencode web` command. Assign him.
|
||||
|
||||
|
||||
### fwang
|
||||
|
||||
Frank is responsible for managing Zen, if you see complaints about OpenCode Zen, maybe it's the dashboard, the model quality, billing issues, etc. Assign him to the issue.
|
||||
|
||||
### jayair
|
||||
|
||||
Jay is responsible for documentation. If there is an issue relating to documentation assign him.
|
||||
|
||||
### kommander
|
||||
|
||||
Sebastian is responsible for managing an OpenTUI (a library for building terminal user interfaces). OpenCode's TUI is built with OpenTUI. If there are issues about:
|
||||
- random characters on screen
|
||||
- keybinds not working on different terminals
|
||||
- general terminal stuff
|
||||
Then assign the issue to Him.
|
||||
|
||||
### rekram1-node
|
||||
|
||||
ALL BUGS SHOULD BE assigned to rekram1-node unless they have the `opentui` label.
|
||||
|
||||
Assign Aiden to an issue as a catch all, if you can't assign anyone else. Most of the time this will be bugs/polish things.
|
||||
If no one else makes sense to assign, assign rekram1-node to it.
|
||||
|
||||
Always assign to aiden if the issue mentions "acp", "zed", or model performance issues
|
||||
|
||||
## Breakdown of Labels:
|
||||
|
||||
### nix
|
||||
|
||||
Any issue that mentions nix, or nixos should have a nix label
|
||||
|
||||
### opentui
|
||||
|
||||
Anything relating to the TUI itself should have an opentui label
|
||||
|
||||
### perf
|
||||
|
||||
Anything related to slow performance, high ram, high cpu usage, or any other performance related issue should have a perf label
|
||||
|
||||
### desktop
|
||||
|
||||
Anything related to `opencode web` command or the desktop app should have a desktop label. Never add this label for anything terminal/tui related
|
||||
|
||||
### zen
|
||||
|
||||
Anything related to OpenCode Zen, billing, or model quality from Zen should have a zen label
|
||||
|
||||
### docs
|
||||
|
||||
Anything related to the documentation should have a docs label
|
||||
|
||||
### windows
|
||||
|
||||
Use for any issue that involves the windows OS
|
||||
@@ -0,0 +1,523 @@
|
||||
# Alpha Launch Rollback Plan
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Created:** 2026-01-12
|
||||
**Last Updated:** 2026-01-12
|
||||
|
||||
This document outlines the rollback procedures for the agent-core alpha launch. Use this plan if critical issues are discovered that require reverting to a known-good state.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Pre-Launch Checklist](#1-pre-launch-checklist)
|
||||
2. [Known Working Versions](#2-known-working-versions)
|
||||
3. [Rollback Procedures](#3-rollback-procedures)
|
||||
4. [Data Backup](#4-data-backup)
|
||||
5. [Monitoring](#5-monitoring)
|
||||
6. [Emergency Contacts/Resources](#6-emergency-contactsresources)
|
||||
7. [Go/No-Go Criteria](#7-gono-go-criteria)
|
||||
|
||||
---
|
||||
|
||||
## 1. Pre-Launch Checklist
|
||||
|
||||
### Core Services
|
||||
|
||||
- [ ] agent-core daemon starts without errors
|
||||
- [ ] All three personas load correctly (Zee, Stanley, Johny)
|
||||
- [ ] Qdrant is running and accessible at `localhost:6333`
|
||||
- [ ] Memory operations (read/write) work correctly
|
||||
|
||||
### Messaging Gateway
|
||||
|
||||
- [ ] Zee gateway starts without errors
|
||||
- [ ] WhatsApp connection established (if configured)
|
||||
- [ ] Telegram bot responding (if configured)
|
||||
- [ ] Persona routing works (`@stanley`, `@johny` mentions)
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- [ ] `bun test` passes in agent-core
|
||||
- [ ] Skills load from `.claude/skills/`
|
||||
- [ ] Domain tools register correctly
|
||||
- [ ] Daemon HTTP API responds at `http://127.0.0.1:3210`
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- [ ] All git repos are clean (no uncommitted changes needed for launch)
|
||||
- [ ] Binary built and installed: `~/bin/agent-core`
|
||||
- [ ] Config directories exist: `~/.config/agent-core/`, `~/.zee/`
|
||||
- [ ] Credentials are in place: `~/.zee/credentials/`
|
||||
|
||||
### Backups Completed
|
||||
|
||||
- [ ] Qdrant collections backed up
|
||||
- [ ] Config files backed up
|
||||
- [ ] Credentials backed up (encrypted)
|
||||
|
||||
---
|
||||
|
||||
## 2. Known Working Versions
|
||||
|
||||
### Git Commit Hashes (Alpha Baseline)
|
||||
|
||||
| Repository | Location | Commit Hash | Branch |
|
||||
|------------|----------|-------------|--------|
|
||||
| **agent-core** | `~/.local/src/agent-core` | `e02d967acd080f48b26b88a060d5e27c65e77513` | main |
|
||||
| **tiara** | `~/.local/src/agent-core/vendor/tiara` | `3b82d0f65e8bef971826898dc8f475d7ed469c7e` | - |
|
||||
| **zee** | `~/Repositories/personas/zee` | `44c73109fb9373f211c813d07d94863f12142330` | - |
|
||||
| **stanley** | `~/Repositories/personas/stanley` | `0ff523b9daafb8846f24585a76f74013bece709f` | - |
|
||||
| **johny** | `~/Repositories/personas/johny` | `8fdfa0277f3952e34cd435dcc92c92574abc3e4c` | - |
|
||||
|
||||
### Recent Commit Context
|
||||
|
||||
**agent-core:**
|
||||
- `e02d967ac` - chore: update tiara submodule
|
||||
- `35a6c16ae` - security: comprehensive pre-alpha and beta security fixes
|
||||
- `979ef345a` - feat(stanley): add GUI launcher script
|
||||
|
||||
**tiara:**
|
||||
- `3b82d0f6` - fix: deprecate legacy CLI spawn, update version references
|
||||
- `8cf3f219` - refactor: integrate with agent-core daemon, prune dead code
|
||||
- `7bb83d94` - fix: pre-alpha security and reliability improvements
|
||||
|
||||
**zee:**
|
||||
- `44c73109` - docs: add external gateway mode documentation
|
||||
- `72d62e1f` - refactor: rename opencode to agent-core naming
|
||||
- `04d84644` - fix: improve gateway reliability and error handling
|
||||
|
||||
**stanley:**
|
||||
- `0ff523b` - fix(gui): resolve GPUI API compatibility issues
|
||||
- `4594cb9` - feat(gui): add agent-core daemon client, replace Python agent API
|
||||
- `949c6b5` - fix(api): use environment variable for API base URL
|
||||
|
||||
**johny:**
|
||||
- `8fdfa02` - Cap mastery history size in memory
|
||||
- `aa05a80` - feat: implement MathAcademy-inspired learning system
|
||||
- `2ccade3` - feat: initial Johny structure with learning skills
|
||||
|
||||
---
|
||||
|
||||
## 3. Rollback Procedures
|
||||
|
||||
### 3.1 Stop All Services
|
||||
|
||||
```bash
|
||||
# Stop agent-core daemon
|
||||
pkill -f "agent-core daemon" || true
|
||||
|
||||
# Stop zee gateway
|
||||
pkill -f "pnpm zee gateway" || true
|
||||
pkill -f "node.*zee.*gateway" || true
|
||||
|
||||
# Verify nothing is running
|
||||
pgrep -af agent-core
|
||||
pgrep -af zee
|
||||
```
|
||||
|
||||
### 3.2 Rollback agent-core
|
||||
|
||||
```bash
|
||||
cd ~/.local/src/agent-core
|
||||
|
||||
# Stash any local changes
|
||||
git stash
|
||||
|
||||
# Reset to known-good commit
|
||||
git checkout e02d967acd080f48b26b88a060d5e27c65e77513
|
||||
|
||||
# Update submodule
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Rebuild
|
||||
cd packages/agent-core && bun install && bun run build
|
||||
|
||||
# Reinstall binary
|
||||
cp dist/agent-core-linux-x64/bin/agent-core ~/bin/agent-core
|
||||
```
|
||||
|
||||
### 3.3 Rollback tiara (Submodule)
|
||||
|
||||
```bash
|
||||
cd ~/.local/src/agent-core/vendor/tiara
|
||||
|
||||
# Reset to known-good commit
|
||||
git checkout 3b82d0f65e8bef971826898dc8f475d7ed469c7e
|
||||
|
||||
# Return to parent and update reference
|
||||
cd ../..
|
||||
git add vendor/tiara
|
||||
```
|
||||
|
||||
### 3.4 Rollback zee
|
||||
|
||||
```bash
|
||||
cd ~/Repositories/personas/zee
|
||||
|
||||
# Stash any local changes
|
||||
git stash
|
||||
|
||||
# Reset to known-good commit
|
||||
git checkout 44c73109fb9373f211c813d07d94863f12142330
|
||||
|
||||
# Reinstall dependencies
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 3.5 Rollback stanley
|
||||
|
||||
```bash
|
||||
cd ~/Repositories/personas/stanley
|
||||
|
||||
# Stash any local changes
|
||||
git stash
|
||||
|
||||
# Reset to known-good commit
|
||||
git checkout 0ff523b9daafb8846f24585a76f74013bece709f
|
||||
|
||||
# Rebuild if necessary
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
### 3.6 Rollback johny
|
||||
|
||||
```bash
|
||||
cd ~/Repositories/personas/johny
|
||||
|
||||
# Stash any local changes
|
||||
git stash
|
||||
|
||||
# Reset to known-good commit
|
||||
git checkout 8fdfa0277f3952e34cd435dcc92c92574abc3e4c
|
||||
|
||||
# Reinstall dependencies if needed
|
||||
bun install || npm install
|
||||
```
|
||||
|
||||
### 3.7 Restore Services
|
||||
|
||||
```bash
|
||||
# Start agent-core daemon
|
||||
agent-core daemon --external-gateway --hostname 127.0.0.1 --port 3210 &
|
||||
|
||||
# Wait for daemon to initialize
|
||||
sleep 5
|
||||
|
||||
# Start zee gateway
|
||||
cd ~/Repositories/personas/zee && pnpm zee gateway &
|
||||
|
||||
# Verify services are running
|
||||
curl -s http://127.0.0.1:3210/health || echo "Daemon not responding"
|
||||
```
|
||||
|
||||
### 3.8 Emergency Full Reset Script
|
||||
|
||||
Save this as `~/bin/alpha-rollback.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "=== Alpha Rollback Script ==="
|
||||
echo "This will reset all persona repos to known-good alpha versions"
|
||||
read -p "Are you sure? (yes/no): " confirm
|
||||
if [ "$confirm" != "yes" ]; then
|
||||
echo "Aborted."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Stopping services..."
|
||||
pkill -f "agent-core" || true
|
||||
pkill -f "zee.*gateway" || true
|
||||
sleep 2
|
||||
|
||||
echo "Rolling back agent-core..."
|
||||
cd ~/.local/src/agent-core
|
||||
git stash || true
|
||||
git checkout e02d967acd080f48b26b88a060d5e27c65e77513
|
||||
git submodule update --init --recursive
|
||||
|
||||
echo "Rolling back zee..."
|
||||
cd ~/Repositories/personas/zee
|
||||
git stash || true
|
||||
git checkout 44c73109fb9373f211c813d07d94863f12142330
|
||||
|
||||
echo "Rolling back stanley..."
|
||||
cd ~/Repositories/personas/stanley
|
||||
git stash || true
|
||||
git checkout 0ff523b9daafb8846f24585a76f74013bece709f
|
||||
|
||||
echo "Rolling back johny..."
|
||||
cd ~/Repositories/personas/johny
|
||||
git stash || true
|
||||
git checkout 8fdfa0277f3952e34cd435dcc92c92574abc3e4c
|
||||
|
||||
echo "Rebuilding agent-core..."
|
||||
cd ~/.local/src/agent-core/packages/agent-core
|
||||
bun install
|
||||
bun run build
|
||||
cp dist/agent-core-linux-x64/bin/agent-core ~/bin/agent-core
|
||||
|
||||
echo "=== Rollback Complete ==="
|
||||
echo "Start services with:"
|
||||
echo " agent-core daemon --external-gateway --hostname 127.0.0.1 --port 3210"
|
||||
echo " cd ~/Repositories/personas/zee && pnpm zee gateway"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Backup
|
||||
|
||||
### 4.1 Qdrant Collections
|
||||
|
||||
**Location:** Qdrant stores data in its configured storage directory (default: `~/.local/share/qdrant/` or Docker volume).
|
||||
|
||||
**Backup procedure:**
|
||||
|
||||
```bash
|
||||
# Create backup directory
|
||||
mkdir -p ~/.zee/backups/qdrant/$(date +%Y%m%d)
|
||||
|
||||
# Using Qdrant snapshots API
|
||||
curl -X POST "http://localhost:6333/collections/memories/snapshots" \
|
||||
-o ~/.zee/backups/qdrant/$(date +%Y%m%d)/memories-snapshot.json
|
||||
|
||||
# Or if using Docker, stop and copy volume
|
||||
docker stop qdrant
|
||||
cp -r /var/lib/docker/volumes/qdrant_storage ~/.zee/backups/qdrant/$(date +%Y%m%d)/
|
||||
docker start qdrant
|
||||
```
|
||||
|
||||
**Restore procedure:**
|
||||
|
||||
```bash
|
||||
# Using Qdrant snapshots API
|
||||
curl -X PUT "http://localhost:6333/collections/memories/snapshots/recover" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"location": "file:///path/to/snapshot"}'
|
||||
```
|
||||
|
||||
### 4.2 Configuration Files
|
||||
|
||||
**Backup:**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.zee/backups/config/$(date +%Y%m%d)
|
||||
|
||||
# agent-core config
|
||||
cp -r ~/.config/agent-core ~/.zee/backups/config/$(date +%Y%m%d)/agent-core
|
||||
|
||||
# Persona state
|
||||
cp -r ~/.zee/johny ~/.zee/backups/config/$(date +%Y%m%d)/johny
|
||||
cp -r ~/.zee/stanley ~/.zee/backups/config/$(date +%Y%m%d)/stanley
|
||||
cp -r ~/.zee/zee ~/.zee/backups/config/$(date +%Y%m%d)/zee-state
|
||||
```
|
||||
|
||||
**Restore:**
|
||||
|
||||
```bash
|
||||
BACKUP_DATE=20260112 # Set to backup date
|
||||
|
||||
cp -r ~/.zee/backups/config/$BACKUP_DATE/agent-core ~/.config/agent-core
|
||||
cp -r ~/.zee/backups/config/$BACKUP_DATE/johny ~/.zee/johny
|
||||
cp -r ~/.zee/backups/config/$BACKUP_DATE/stanley ~/.zee/stanley
|
||||
cp -r ~/.zee/backups/config/$BACKUP_DATE/zee-state ~/.zee/zee
|
||||
```
|
||||
|
||||
### 4.3 Credentials (Handle with Care)
|
||||
|
||||
**Location:** `~/.zee/credentials/`
|
||||
|
||||
**Backup (encrypted):**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.zee/backups/credentials/$(date +%Y%m%d)
|
||||
|
||||
# Encrypt with GPG
|
||||
tar czf - ~/.zee/credentials | \
|
||||
gpg --symmetric --cipher-algo AES256 \
|
||||
> ~/.zee/backups/credentials/$(date +%Y%m%d)/credentials.tar.gz.gpg
|
||||
```
|
||||
|
||||
**Restore:**
|
||||
|
||||
```bash
|
||||
BACKUP_DATE=20260112
|
||||
|
||||
gpg --decrypt ~/.zee/backups/credentials/$BACKUP_DATE/credentials.tar.gz.gpg | \
|
||||
tar xzf - -C /
|
||||
```
|
||||
|
||||
### 4.4 What NOT to Backup
|
||||
|
||||
- Build artifacts (`dist/`, `node_modules/`, `target/`)
|
||||
- Temporary files (`.wwebjs_cache/`)
|
||||
- Log files (can regenerate)
|
||||
|
||||
---
|
||||
|
||||
## 5. Monitoring
|
||||
|
||||
### 5.1 Health Checks
|
||||
|
||||
**agent-core daemon:**
|
||||
|
||||
```bash
|
||||
# Check if daemon is responding
|
||||
curl -s http://127.0.0.1:3210/health
|
||||
|
||||
# Check daemon logs
|
||||
journalctl -u agent-core -f # if running as systemd service
|
||||
# OR
|
||||
tail -f ~/.local/state/agent-core/daemon.log
|
||||
```
|
||||
|
||||
**Qdrant:**
|
||||
|
||||
```bash
|
||||
# Check Qdrant health
|
||||
curl -s http://localhost:6333/health
|
||||
|
||||
# Check collection stats
|
||||
curl -s http://localhost:6333/collections/memories
|
||||
```
|
||||
|
||||
### 5.2 Key Metrics to Watch
|
||||
|
||||
| Metric | Normal Range | Alert Threshold |
|
||||
|--------|--------------|-----------------|
|
||||
| Daemon response time | < 100ms | > 500ms |
|
||||
| Memory usage | < 2GB | > 4GB |
|
||||
| Qdrant query time | < 50ms | > 200ms |
|
||||
| Error rate in logs | 0 | > 5/minute |
|
||||
|
||||
### 5.3 Log Locations
|
||||
|
||||
| Component | Log Location |
|
||||
|-----------|--------------|
|
||||
| agent-core daemon | `~/.local/state/agent-core/daemon.log` |
|
||||
| agent-core TUI | `~/.local/state/agent-core/` (session logs) |
|
||||
| zee gateway | stdout/stderr (run in tmux/screen) |
|
||||
| Qdrant | Docker logs or `~/.local/share/qdrant/logs` |
|
||||
|
||||
### 5.4 Warning Signs
|
||||
|
||||
**Immediate rollback triggers:**
|
||||
|
||||
- Daemon crashes repeatedly (> 3 times in 10 minutes)
|
||||
- Memory corruption errors in logs
|
||||
- Qdrant connection failures
|
||||
- Authentication/credential issues affecting all users
|
||||
|
||||
**Investigation needed (not immediate rollback):**
|
||||
|
||||
- Slow response times (but still functional)
|
||||
- Occasional timeouts (< 5% of requests)
|
||||
- Non-critical feature failures
|
||||
|
||||
---
|
||||
|
||||
## 6. Emergency Contacts/Resources
|
||||
|
||||
### 6.1 Documentation
|
||||
|
||||
| Resource | Location |
|
||||
|----------|----------|
|
||||
| agent-core CLAUDE.md | `~/.local/src/agent-core/CLAUDE.md` |
|
||||
| Tiara documentation | `~/.local/src/agent-core/vendor/tiara/docs/` |
|
||||
| Skills documentation | `~/.local/src/agent-core/docs/SKILLS.md` |
|
||||
| Architecture docs | `~/.local/src/agent-core/docs/architecture/` |
|
||||
|
||||
### 6.2 External Resources
|
||||
|
||||
| Resource | URL |
|
||||
|----------|-----|
|
||||
| Qdrant documentation | https://qdrant.tech/documentation/ |
|
||||
| OpenCode upstream | https://github.com/opencode/opencode |
|
||||
| Bun documentation | https://bun.sh/docs |
|
||||
|
||||
### 6.3 Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Check all service status
|
||||
pgrep -af "agent-core\|qdrant\|zee"
|
||||
|
||||
# View recent errors
|
||||
grep -i error ~/.local/state/agent-core/*.log | tail -20
|
||||
|
||||
# Restart everything
|
||||
pkill -f agent-core; sleep 2; agent-core daemon --external-gateway &
|
||||
cd ~/Repositories/personas/zee && pnpm zee gateway &
|
||||
|
||||
# Check disk space
|
||||
df -h ~/.local ~/.config ~/.zee
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Go/No-Go Criteria
|
||||
|
||||
### 7.1 Launch Go Criteria
|
||||
|
||||
All of the following must be true:
|
||||
|
||||
- [ ] All pre-launch checklist items completed
|
||||
- [ ] Backups verified and restorable
|
||||
- [ ] No critical errors in last 24 hours of testing
|
||||
- [ ] All three personas responding correctly
|
||||
- [ ] Memory operations (read/write/search) working
|
||||
- [ ] At least one messaging gateway functional
|
||||
|
||||
### 7.2 Rollback Triggers (No-Go / Abort)
|
||||
|
||||
**Immediate rollback if ANY of these occur:**
|
||||
|
||||
1. **Data loss** - Any indication of memory corruption or lost data
|
||||
2. **Security breach** - Unauthorized access or credential exposure
|
||||
3. **Service unavailability** - Daemon down for > 5 minutes
|
||||
4. **Cascade failures** - One component failure causing others to fail
|
||||
5. **Critical persona failure** - Zee (primary) persona non-functional
|
||||
|
||||
**Consider rollback if:**
|
||||
|
||||
1. Error rate exceeds 10% of requests
|
||||
2. Response times consistently > 5 seconds
|
||||
3. Multiple non-critical features broken
|
||||
4. User reports of data inconsistency
|
||||
|
||||
### 7.3 Rollback Decision Matrix
|
||||
|
||||
| Issue Severity | User Impact | Action |
|
||||
|----------------|-------------|--------|
|
||||
| Critical | All users affected | Immediate rollback |
|
||||
| High | > 50% users affected | Rollback within 1 hour |
|
||||
| Medium | < 50% users affected | Investigate, rollback if no fix in 4 hours |
|
||||
| Low | Cosmetic/minor | Continue, fix forward |
|
||||
|
||||
### 7.4 Post-Rollback Actions
|
||||
|
||||
After executing a rollback:
|
||||
|
||||
1. Document what went wrong
|
||||
2. Identify root cause
|
||||
3. Create fix in development environment
|
||||
4. Test fix thoroughly before re-launch
|
||||
5. Update this rollback plan with lessons learned
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Quick Rollback Checklist
|
||||
|
||||
For rapid response, use this abbreviated checklist:
|
||||
|
||||
- [ ] Stop all services: `pkill -f agent-core; pkill -f zee`
|
||||
- [ ] Run rollback script: `~/bin/alpha-rollback.sh`
|
||||
- [ ] Verify services start: `curl http://127.0.0.1:3210/health`
|
||||
- [ ] Test persona response: Send test message
|
||||
- [ ] Notify stakeholders of rollback
|
||||
- [ ] Begin incident documentation
|
||||
|
||||
---
|
||||
|
||||
*End of Alpha Launch Rollback Plan*
|
||||
@@ -0,0 +1,383 @@
|
||||
# Environment Variables Reference
|
||||
|
||||
Complete reference for environment variables across the agent-core ecosystem.
|
||||
|
||||
---
|
||||
|
||||
## Agent-Core (Engine)
|
||||
|
||||
### Core Runtime
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `AGENT_CORE` | Set to `1` | Automatically set when agent-core is running |
|
||||
| `AGENT` | Set to `1` | Indicates agent mode is active |
|
||||
| `OPENCODE` | Set to `1` | Backwards compatibility flag |
|
||||
| `AGENT_CORE_ROOT` | - | Override the agent-core installation root directory |
|
||||
| `AGENT_CORE_TEST_HOME` | - | Override home directory for testing |
|
||||
| `AGENT_CORE_ORIGINAL_PWD` | - | Original working directory before agent-core started |
|
||||
|
||||
### Daemon & IPC
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `AGENT_CORE_DAEMON_PORT` | `3456` | HTTP port for the daemon API |
|
||||
| `AGENT_CORE_IPC_SOCKET` | `/tmp/agent-core.sock` | Unix socket path for IPC |
|
||||
| `AGENT_CORE_URL` | `http://127.0.0.1:3210` | Full URL to daemon |
|
||||
| `AGENT_CORE_WEZTERM_ENABLED` | - | Enable WezTerm integration (`true`/`false`) |
|
||||
| `PERSONAS_WEZTERM_ENABLED` | - | Alias for WezTerm integration |
|
||||
| `PERSONAS_LEAD_PERSONA` | `zee` | Default persona when none specified |
|
||||
|
||||
### Shell & Terminal
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `SHELL` | - | User's default shell (used for bash tool) |
|
||||
| `COMSPEC` | `cmd.exe` | Windows command interpreter |
|
||||
| `DISPLAY` | - | X11 display (Linux, checked for WezTerm) |
|
||||
| `WAYLAND_DISPLAY` | - | Wayland display (Linux, checked for WezTerm) |
|
||||
| `TMUX` | - | Indicates running inside tmux |
|
||||
| `WEZTERM_PANE` | - | WezTerm pane ID when running in WezTerm |
|
||||
| `WEZTERM_EXECUTABLE` | - | Path to WezTerm executable |
|
||||
| `CANVAS_TERMINAL` | - | Preferred terminal: `wezterm`, `tmux`, or auto-detect |
|
||||
|
||||
### Network & Proxy
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `HTTP_PROXY` | - | HTTP proxy URL |
|
||||
| `HTTPS_PROXY` | - | HTTPS proxy URL |
|
||||
| `http_proxy` | - | HTTP proxy URL (lowercase variant) |
|
||||
| `https_proxy` | - | HTTPS proxy URL (lowercase variant) |
|
||||
|
||||
### XDG Directories
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `XDG_CONFIG_HOME` | `~/.config` | Config directory |
|
||||
| `XDG_DATA_HOME` | `~/.local/share` | Data directory |
|
||||
| `XDG_STATE_HOME` | `~/.local/state` | State directory |
|
||||
| `XDG_CACHE_HOME` | `~/.cache` | Cache directory |
|
||||
|
||||
---
|
||||
|
||||
## Memory & Embeddings
|
||||
|
||||
### Qdrant Vector Database
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `QDRANT_URL` | `http://localhost:6333` | Qdrant server URL |
|
||||
|
||||
### Embedding Providers
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `OPENAI_API_KEY` | - | OpenAI API key for embeddings (text-embedding-3-small) |
|
||||
| `VOYAGE_API_KEY` | - | Voyage AI API key for embeddings (alternative) |
|
||||
|
||||
---
|
||||
|
||||
## LLM Providers
|
||||
|
||||
### Anthropic
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ANTHROPIC_API_KEY` | - | Anthropic API key for Claude models |
|
||||
|
||||
### OpenAI
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `OPENAI_API_KEY` | - | OpenAI API key for GPT models and embeddings |
|
||||
|
||||
### OpenRouter
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `OPENROUTER_API_KEY` | - | OpenRouter API key for multi-model routing |
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `GITHUB_TOKEN` | - | GitHub token for Copilot authentication |
|
||||
| `GH_TOKEN` | - | Alternative GitHub token |
|
||||
|
||||
---
|
||||
|
||||
## Zee (Personal Assistant)
|
||||
|
||||
### Gateway Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ZEE_GATEWAY_PORT` | - | Gateway HTTP port |
|
||||
| `ZEE_GATEWAY_LOCK` | - | Lock file path for gateway |
|
||||
| `ZEE_GATEWAY_PASSWORD` | - | Gateway authentication password |
|
||||
| `ZEE_SKIP_PROVIDERS` | - | Skip specific messaging providers |
|
||||
| `ZEE_SKIP_GMAIL_WATCHER` | - | Disable Gmail watcher |
|
||||
| `ZEE_TEST_HOME` | - | Override home for testing |
|
||||
| `ZEE_CONTROL_UI_BASE_PATH` | - | Base path for control UI |
|
||||
|
||||
### Messaging Providers
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `WHATSAPP_TOKEN` | - | WhatsApp Business API token |
|
||||
| `WHATSAPP_PHONE_ID` | - | WhatsApp phone ID |
|
||||
| `TELEGRAM_BOT_TOKEN` | - | Telegram bot token |
|
||||
|
||||
### Search
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `BRAVE_API_KEY` | - | Brave Search API key |
|
||||
|
||||
---
|
||||
|
||||
## Stanley (Financial Platform)
|
||||
|
||||
### API Server
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `STANLEY_API_URL` | `http://localhost:8000` | Stanley API base URL |
|
||||
| `STANLEY_DEV_MODE` | `false` | Enable development mode (relaxed auth) |
|
||||
| `STANLEY_REDIS_URL` | - | Redis URL for caching |
|
||||
| `REDIS_URL` | - | Alternative Redis URL |
|
||||
| `DEBUG` | - | Enable debug mode (exposes error details) |
|
||||
|
||||
### Authentication (JWT)
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `STANLEY_AUTH_JWT_SECRET_KEY` | - | JWT signing key (production) |
|
||||
| `JWT_SECRET_KEY` | - | Alternative JWT signing key |
|
||||
| `JWT_ALGORITHM` | `HS256` | JWT signing algorithm |
|
||||
| `JWT_ISSUER` | `stanley-api` | JWT issuer claim |
|
||||
| `JWT_AUDIENCE` | `stanley-client` | JWT audience claim |
|
||||
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `15` | Access token TTL |
|
||||
| `REFRESH_TOKEN_EXPIRE_DAYS` | `7` | Refresh token TTL |
|
||||
| `STANLEY_AUTH_RATE_LIMIT_ENABLED` | `true` | Enable auth rate limiting |
|
||||
|
||||
### Wide Events (Observability)
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `STANLEY_WIDE_EVENTS_ENABLED` | `1` | Enable wide event logging |
|
||||
| `STANLEY_WIDE_EVENTS_SAMPLE_RATE` | `0.02` | Sample rate (2%) |
|
||||
| `STANLEY_WIDE_EVENTS_SLOW_MS` | `2000` | Slow request threshold (ms) |
|
||||
| `STANLEY_WIDE_EVENTS_PAYLOADS` | `debug` | Payload logging level |
|
||||
| `STANLEY_WIDE_EVENTS_DIR` | - | Custom events directory |
|
||||
| `STANLEY_WIDE_EVENTS_FILE` | - | Custom events file |
|
||||
|
||||
### Financial Data Providers
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `OPENBB_API_KEY` | - | OpenBB API key |
|
||||
| `OPENBB_PAT` | - | OpenBB personal access token |
|
||||
| `OPENBB_TOKEN` | - | Alternative OpenBB token |
|
||||
| `STANLEY_OPENBB_PROVIDER` | `yfinance` | Default OpenBB data provider |
|
||||
| `ALPHA_VANTAGE_API_KEY` | - | Alpha Vantage API key |
|
||||
| `YAHOO_FINANCE_KEY` | - | Yahoo Finance API key |
|
||||
| `PLAID_CLIENT_ID` | - | Plaid client ID |
|
||||
| `PLAID_SECRET` | - | Plaid secret |
|
||||
| `TERRAPIN_API_KEY` | - | Terrapin bonds API key |
|
||||
|
||||
### Prediction Markets
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `DOME_API_KEY` | - | Dome prediction markets API key |
|
||||
| `DOME_API_TOKEN` | - | Alternative Dome token |
|
||||
| `DOME_API_BASE_URL` | `https://api.domeapi.io/v1` | Dome API base URL |
|
||||
| `DOME_API_TIMEOUT` | `20` | Request timeout (seconds) |
|
||||
|
||||
### SEC Filings
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `SEC_IDENTITY` | `stanley-research@example.com` | SEC EDGAR identity |
|
||||
|
||||
### Portfolio
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `STANLEY_PORTFOLIO_FILE` | `~/.zee/stanley/portfolio.json` | Portfolio file path |
|
||||
| `STANLEY_REPO` | `~/Repositories/personas/stanley` | Stanley repo path |
|
||||
| `STANLEY_CLI` | `$STANLEY_REPO/scripts/stanley_cli.py` | CLI script path |
|
||||
| `STANLEY_PYTHON` | Auto-detect venv or `python3` | Python interpreter |
|
||||
|
||||
---
|
||||
|
||||
## Johny (Learning System)
|
||||
|
||||
### Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `JOHNY_REPO` | `~/Repositories/personas/johny` | Johny repo path |
|
||||
| `JOHNY_CLI` | `$JOHNY_REPO/scripts/johny_cli.py` | CLI script path |
|
||||
| `JOHNY_PYTHON` | Auto-detect venv or `python3` | Python interpreter |
|
||||
|
||||
---
|
||||
|
||||
## Tiara (Orchestration - vendor/tiara)
|
||||
|
||||
### Debug & Logging
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `CLAUDE_FLOW_DEBUG` | `false` | Enable debug logging |
|
||||
| `LOG_LEVEL` | `info` | Log level: `error`, `warn`, `info`, `debug` |
|
||||
| `NODE_ENV` | `development` | Environment: `development`, `production`, `test` |
|
||||
|
||||
### Database
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `CLAUDE_FLOW_DB_PATH` | `.swarm/memory.db` | SQLite database path |
|
||||
| `AGENTDB_PATH` | - | AgentDB database path |
|
||||
|
||||
### Features
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `FEATURE_AGENTDB` | `false` | Enable AgentDB feature |
|
||||
| `CLAUDE_FLOW_SEMANTIC_SEARCH` | `false` | Enable semantic search |
|
||||
| `FORCE_TRANSFORMERS` | `false` | Force transformer initialization |
|
||||
| `REASONINGBANK_ENABLED` | - | Enable reasoning bank |
|
||||
|
||||
### MCP Registry
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `MCP_REGISTRY_ENABLED` | `false` | Enable MCP registry |
|
||||
| `MCP_REGISTRY_URL` | - | MCP registry URL |
|
||||
| `MCP_REGISTRY_API_KEY` | - | MCP registry API key |
|
||||
|
||||
### API Keys (Tiara context)
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `CLAUDE_API_KEY` | - | Alternative Anthropic key name |
|
||||
| `CLAUDE_FLOW_API_KEY` | - | Claude Flow specific API key |
|
||||
|
||||
---
|
||||
|
||||
## Peekaboo (Zee submodule - macOS screenshots)
|
||||
|
||||
### Runner Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `RUNNER_DEBUG` | `0` | Enable debug logs (`1` to enable) |
|
||||
| `RUNNER_SUMMARY_STYLE` | - | Summary output style |
|
||||
| `RUNNER_THE_USER_GAVE_ME_CONSENT` | `0` | Consent override |
|
||||
| `RUNNER_SWIFT_PACKAGE` | - | Custom Swift package path |
|
||||
| `RUNNER_TMUX` | - | Force/disable tmux mode |
|
||||
| `PEEKABOO_REQUIRE_UNIVERSAL` | `0` | Require universal binary |
|
||||
| `HOMEBREW_PREFIX` | `/opt/homebrew` | Homebrew installation prefix |
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Minimal Production Setup
|
||||
|
||||
```bash
|
||||
# Required for LLM functionality
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
|
||||
# Required for memory/embeddings
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
export QDRANT_URL="http://localhost:6333"
|
||||
|
||||
# Start daemon
|
||||
agent-core daemon --external-gateway
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
```bash
|
||||
# LLM providers
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
|
||||
# Local services
|
||||
export QDRANT_URL="http://localhost:6333"
|
||||
|
||||
# Debug mode
|
||||
export CLAUDE_FLOW_DEBUG=true
|
||||
export LOG_LEVEL=debug
|
||||
|
||||
# Persona routing
|
||||
export PERSONAS_LEAD_PERSONA=zee
|
||||
```
|
||||
|
||||
### Stanley Financial API
|
||||
|
||||
```bash
|
||||
# Core auth
|
||||
export STANLEY_AUTH_JWT_SECRET_KEY="your-32-char-secret-key"
|
||||
export JWT_ALGORITHM="HS256"
|
||||
|
||||
# Data providers
|
||||
export OPENBB_API_KEY="..."
|
||||
export ALPHA_VANTAGE_API_KEY="..."
|
||||
|
||||
# Optional caching
|
||||
export STANLEY_REDIS_URL="redis://localhost:6379"
|
||||
```
|
||||
|
||||
### Zee Gateway
|
||||
|
||||
```bash
|
||||
# Messaging
|
||||
export TELEGRAM_BOT_TOKEN="..."
|
||||
export WHATSAPP_TOKEN="..."
|
||||
export WHATSAPP_PHONE_ID="..."
|
||||
|
||||
# Search
|
||||
export BRAVE_API_KEY="..."
|
||||
|
||||
# Gateway config
|
||||
export ZEE_GATEWAY_PASSWORD="secure-password"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
1. **Never commit API keys** - Use environment variables or `.env` files
|
||||
2. **JWT secrets** must be at least 32 characters for HS256
|
||||
3. **Production** should set `NODE_ENV=production` and `STANLEY_DEV_MODE=false`
|
||||
4. **.env files** are blocked from agent reading by default (security feature)
|
||||
5. **Rate limiting** is enabled by default for auth endpoints
|
||||
|
||||
---
|
||||
|
||||
## Configuration Architecture Notes
|
||||
|
||||
### Port Assignments
|
||||
|
||||
The system uses distinct ports for different services:
|
||||
|
||||
| Port | Service | Location |
|
||||
|------|---------|----------|
|
||||
| 3210 | TUI/Web Server | `packages/agent-core/src/server/server.ts` |
|
||||
| 3456 | Daemon API | `src/config/constants.ts` |
|
||||
| 6333 | Qdrant (default) | External service |
|
||||
|
||||
### Constants Organization
|
||||
|
||||
- **Centralized constants**: `src/config/constants.ts` - Infrastructure constants for the daemon
|
||||
- **Package constants**: `packages/agent-core/src/` - OpenCode fork maintains its own constants
|
||||
- **Both read from environment variables** ensuring runtime configurability
|
||||
|
||||
---
|
||||
|
||||
*Generated: 2026-01-12*
|
||||
+209
@@ -0,0 +1,209 @@
|
||||
# Logging Architecture
|
||||
|
||||
This document describes the structured logging system used across agent-core.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Agent-core uses a centralized structured logging system based on the `Log` utility. This provides:
|
||||
|
||||
- Consistent log formatting across all modules
|
||||
- Configurable log levels
|
||||
- Structured metadata for debugging
|
||||
- Integration with wide events for observability
|
||||
|
||||
---
|
||||
|
||||
## Log Utility
|
||||
|
||||
### Location
|
||||
|
||||
`packages/agent-core/src/util/log.ts`
|
||||
|
||||
### Usage
|
||||
|
||||
```typescript
|
||||
import { Log } from "../util/log"
|
||||
|
||||
// Create a logger for your module
|
||||
const log = Log.create({ service: "my-service" })
|
||||
|
||||
// Use structured logging
|
||||
log.debug("processing request", { requestId: "abc123", size: 1024 })
|
||||
log.info("operation complete", { duration: 150 })
|
||||
log.warn("rate limit approaching", { remaining: 10 })
|
||||
log.error("operation failed", { error: err.message, code: err.code })
|
||||
```
|
||||
|
||||
### Log Levels
|
||||
|
||||
| Level | Use Case |
|
||||
|-------|----------|
|
||||
| `debug` | Detailed debugging information |
|
||||
| `info` | Normal operational messages |
|
||||
| `warn` | Potential issues that don't stop execution |
|
||||
| `error` | Errors that affect functionality |
|
||||
|
||||
---
|
||||
|
||||
## Module-Specific Logging
|
||||
|
||||
### Personas (`src/personas/`)
|
||||
|
||||
```typescript
|
||||
import { Log } from "../util/log"
|
||||
|
||||
const log = Log.create({ service: "personas.tiara" })
|
||||
// Or subsystem-specific:
|
||||
const log = Log.create({ service: "personas.fact-extractor" })
|
||||
```
|
||||
|
||||
### Memory (`src/memory/`)
|
||||
|
||||
```typescript
|
||||
const log = Log.create({ service: "memory.qdrant" })
|
||||
```
|
||||
|
||||
### MCP Servers (`src/mcp/`)
|
||||
|
||||
```typescript
|
||||
const log = Log.create({ service: "mcp.server" })
|
||||
```
|
||||
|
||||
### Domain Tools (`src/domain/`)
|
||||
|
||||
```typescript
|
||||
const log = Log.create({ service: "domain.zee" })
|
||||
const log = Log.create({ service: "domain.stanley" })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Zee Gateway Logging
|
||||
|
||||
The zee gateway uses `createSubsystemLogger` for consistent logging:
|
||||
|
||||
```typescript
|
||||
import { createSubsystemLogger } from "./logging"
|
||||
|
||||
const log = createSubsystemLogger("gateway")
|
||||
log.info("server started", { port: 3210 })
|
||||
```
|
||||
|
||||
### Subsystems
|
||||
|
||||
| Subsystem | Purpose |
|
||||
|-----------|---------|
|
||||
| `gateway` | HTTP/WebSocket server |
|
||||
| `hooks` | Webhook processing |
|
||||
| `whatsapp` | WhatsApp bridge |
|
||||
| `telegram` | Telegram bot |
|
||||
| `discord` | Discord integration |
|
||||
|
||||
---
|
||||
|
||||
## Acceptable Console Usage
|
||||
|
||||
The following `console.log` usage patterns are acceptable:
|
||||
|
||||
### Test Files
|
||||
|
||||
Test output is expected to use console for immediate feedback:
|
||||
|
||||
```typescript
|
||||
// integration.test.ts
|
||||
console.log(`[TEST] ${msg}`)
|
||||
console.log(`[✓] ${msg}`)
|
||||
```
|
||||
|
||||
### MCP Servers (stdio protocol)
|
||||
|
||||
MCP servers running on stdio use `console.error` for startup messages:
|
||||
|
||||
```typescript
|
||||
// Standard MCP server startup
|
||||
console.error("Portfolio MCP server running on stdio")
|
||||
```
|
||||
|
||||
### Plugin Fallbacks
|
||||
|
||||
Plugin system provides fallback logging when structured logger unavailable:
|
||||
|
||||
```typescript
|
||||
warn: (message, data) => console.warn(`[plugin] ${message}`, data || '')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Wide Events
|
||||
|
||||
For observability, agent-core integrates wide events:
|
||||
|
||||
### Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"wideEvents": {
|
||||
"enabled": true,
|
||||
"sampleRate": 0.02,
|
||||
"slowMs": 2000,
|
||||
"payloads": "summary"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Event Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `timestamp` | ISO timestamp |
|
||||
| `service` | Service name |
|
||||
| `operation` | Operation being performed |
|
||||
| `duration_ms` | Operation duration |
|
||||
| `status` | `success` or `error` |
|
||||
| `metadata` | Additional context |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always use structured logging** in production code
|
||||
2. **Include relevant context** as metadata, not in the message string
|
||||
3. **Use appropriate log levels** - debug for development, info for operations
|
||||
4. **Create service-specific loggers** for easier filtering
|
||||
5. **Avoid logging sensitive data** (API keys, passwords, tokens)
|
||||
|
||||
### Good
|
||||
|
||||
```typescript
|
||||
log.info("user authenticated", { userId: "123", method: "oauth" })
|
||||
```
|
||||
|
||||
### Bad
|
||||
|
||||
```typescript
|
||||
log.info(`user 123 authenticated via oauth`) // Unstructured
|
||||
console.log("user authenticated") // Not structured
|
||||
log.info("auth", { token: "secret123" }) // Sensitive data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Audit Summary
|
||||
|
||||
| Component | Logging Method | Status |
|
||||
|-----------|----------------|--------|
|
||||
| `packages/agent-core/` | `Log` utility | ✓ Structured |
|
||||
| `src/personas/` | `Log` utility | ✓ Structured |
|
||||
| `src/memory/` | `Log` utility | ✓ Structured |
|
||||
| `src/mcp/` | `Log` utility | ✓ Structured |
|
||||
| `src/domain/` | `Log` utility | ✓ Structured |
|
||||
| `src/daemon/` | Custom wrapper | ✓ Timestamped |
|
||||
| `zee/src/` | `createSubsystemLogger` | ✓ Structured |
|
||||
| Test files | `console.log` | ✓ Acceptable |
|
||||
| MCP stdio servers | `console.error` | ✓ Protocol standard |
|
||||
|
||||
---
|
||||
|
||||
*Generated: 2026-01-12*
|
||||
@@ -1,10 +0,0 @@
|
||||
export const foo: string = "42"
|
||||
export const bar: number = 123
|
||||
|
||||
export function dummyFunction(): void {
|
||||
console.log("This is a dummy function")
|
||||
}
|
||||
|
||||
export function randomHelper(): boolean {
|
||||
return Math.random() > 0.5
|
||||
}
|
||||
@@ -1,40 +0,0 @@
|
||||
import { Share } from "./src/core/share"
|
||||
import { Storage } from "./src/core/storage"
|
||||
|
||||
async function test() {
|
||||
const shareInfo = await Share.create({ sessionID: "test-debug-" + Date.now() })
|
||||
|
||||
const batch1: Share.Data[] = [
|
||||
{ type: "part", data: { id: "part1", sessionID: "session1", messageID: "msg1", type: "text", text: "Hello" } },
|
||||
]
|
||||
|
||||
const batch2: Share.Data[] = [
|
||||
{
|
||||
type: "part",
|
||||
data: { id: "part1", sessionID: "session1", messageID: "msg1", type: "text", text: "Hello Updated" },
|
||||
},
|
||||
]
|
||||
|
||||
await Share.sync({
|
||||
share: { id: shareInfo.id, secret: shareInfo.secret },
|
||||
data: batch1,
|
||||
})
|
||||
|
||||
await Share.sync({
|
||||
share: { id: shareInfo.id, secret: shareInfo.secret },
|
||||
data: batch2,
|
||||
})
|
||||
|
||||
const events = await Storage.list({ prefix: ["share_event", shareInfo.id] })
|
||||
console.log("Events (raw):", events)
|
||||
console.log("Events (reversed):", events.toReversed())
|
||||
|
||||
for (const event of events.toReversed()) {
|
||||
const data = await Storage.read(event)
|
||||
console.log("Event data (reversed order):", event, data)
|
||||
}
|
||||
|
||||
await Share.remove({ id: shareInfo.id, secret: shareInfo.secret })
|
||||
}
|
||||
|
||||
test()
|
||||
Reference in New Issue
Block a user