From ab9e90fceaee10320614059eb91cc27833caf49d Mon Sep 17 00:00:00 2001 From: Artur Do Lago Date: Mon, 12 Jan 2026 16:27:49 +0100 Subject: [PATCH] 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 --- .agent-core/tool/github-pr-search.txt | 10 - .agent-core/tool/github-triage.txt | 88 ----- docs/ALPHA_ROLLBACK_PLAN.md | 523 ++++++++++++++++++++++++++ docs/ENVIRONMENT_VARIABLES.md | 383 +++++++++++++++++++ docs/LOGGING.md | 209 ++++++++++ packages/agent-core/src/util/scrap.ts | 10 - packages/enterprise/test-debug.ts | 40 -- 7 files changed, 1115 insertions(+), 148 deletions(-) delete mode 100644 .agent-core/tool/github-pr-search.txt delete mode 100644 .agent-core/tool/github-triage.txt create mode 100644 docs/ALPHA_ROLLBACK_PLAN.md create mode 100644 docs/ENVIRONMENT_VARIABLES.md create mode 100644 docs/LOGGING.md delete mode 100644 packages/agent-core/src/util/scrap.ts delete mode 100644 packages/enterprise/test-debug.ts diff --git a/.agent-core/tool/github-pr-search.txt b/.agent-core/tool/github-pr-search.txt deleted file mode 100644 index 28d8643f13c..00000000000 --- a/.agent-core/tool/github-pr-search.txt +++ /dev/null @@ -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. diff --git a/.agent-core/tool/github-triage.txt b/.agent-core/tool/github-triage.txt deleted file mode 100644 index 4c46a72c162..00000000000 --- a/.agent-core/tool/github-triage.txt +++ /dev/null @@ -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 diff --git a/docs/ALPHA_ROLLBACK_PLAN.md b/docs/ALPHA_ROLLBACK_PLAN.md new file mode 100644 index 00000000000..fdd6648df79 --- /dev/null +++ b/docs/ALPHA_ROLLBACK_PLAN.md @@ -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* diff --git a/docs/ENVIRONMENT_VARIABLES.md b/docs/ENVIRONMENT_VARIABLES.md new file mode 100644 index 00000000000..2a4d12731cb --- /dev/null +++ b/docs/ENVIRONMENT_VARIABLES.md @@ -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* diff --git a/docs/LOGGING.md b/docs/LOGGING.md new file mode 100644 index 00000000000..0daee9c5b22 --- /dev/null +++ b/docs/LOGGING.md @@ -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* diff --git a/packages/agent-core/src/util/scrap.ts b/packages/agent-core/src/util/scrap.ts deleted file mode 100644 index 554dba1c54a..00000000000 --- a/packages/agent-core/src/util/scrap.ts +++ /dev/null @@ -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 -} diff --git a/packages/enterprise/test-debug.ts b/packages/enterprise/test-debug.ts deleted file mode 100644 index a2ec4d8cdf3..00000000000 --- a/packages/enterprise/test-debug.ts +++ /dev/null @@ -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()