-agents|cleveragents [--data-dir <DATA_PATH>] [--config-path <CONFIG_PATH>]
- [--format (rich|color|table|plain|json|yaml)]
- [--help|-h] [--version]
- [--install-completion [<INST_SHELL>]] [--show-completion [<SHOW_SHELL>]]
- [-v...] <COMMAND> [<ARGS>...]
-
-agents version
-agents info
-agents diagnostics
-agents init [--yes|-y]
-
-agents session create [--actor <ACTOR>]
-agents session list
-agents session show <SESSION_ID>
-agents session delete [--yes|-y] <SESSION_ID>
-agents session export [(--output|-o) <FILE>] <SESSION_ID>
-agents session import (--input|-i) <FILE>
-agents session tell --session <SESSION_ID> [--actor <ACTOR>] [--stream] <PROMPT>
-
-agents project create [(--description|-d) <DESC>] [--resource <RESOURCE>]...
- [--invariant <INVARIANT>]... [--invariant-actor <ACTOR>] <NAME>
-agents project link-resource [--read-only] <PROJECT> <RESOURCE>
-agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE_NAME>
-agents project list [(--namespace|-n) NS] [<REGEX>]
-agents project show <PROJECT>
-agents project delete [--force|-f] [--yes|-y] <NAME>
-agents project context set[--view (strategize|execute|apply|default)]
- [--include-resource <INCLUDE_RESOURCE>]...
- [--exclude-resource <EXCLUDE_RESOURCE>]...
- [--include-path <INCLUDE_GLOB>]...
- [--exclude-path <EXCLUDE_GLOB>]...
- [--hot-max-tokens <N>]
- [--warm-max-decisions <N_WARM_MAX>]
- [--cold-max-decisions <N_COLD_MAX>]
- [--query-limit <N>]
- [--max-file-size <MAX_FILE_BYTES>]
- [--max-total-size <MAX_TOTAL_BYTES>]
- [--summarize|--no-summarize]
- [--summary-max-tokens <N>]
- [--strategy <STRATEGY>]...
- [--default-breadth <N>]
- [--default-depth <INT_OR_NAME>]
- [--depth-gradient <HOP:INT_OR_NAME>]...
- [--skeleton-ratio <FLOAT>]
- [--temporal-scope (current|recent|all)]
- [--auto-refresh|--no-auto-refresh]
- [--execution-environment <RESOURCE_NAME>]
- [--execution-env-priority (fallback|override)]
- [--clear] <PROJECT>
-agents project context show [--view (strategize|execute|apply|default)]
- <PROJECT>
-agents project context inspect [--view (strategize|execute|apply|default)]
- [--strategy <STRATEGY>]
- [--focus <UKO_URI>]...
- [--breadth <N>] [--depth <INT_OR_NAME>]
- <PROJECT>
-agents project context simulate [--view (strategize|execute|apply|default)]
- [--budget <TOKENS>]
- [--focus <UKO_URI>]...
- [--strategy <STRATEGY>]...
- <PROJECT>
-
-agents validation add --config|-c <FILE> [--update]
-agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
- <RESOURCE> <VALIDATION> [<ARGS>...]
-agents validation detach [--yes|-y] <ATTACHMENT_ID>
-
-agents actor run [(--output|-o) <OUTPUT_FILE>]
- [-v...] [--unsafe|-u] [--context <CONTEXT_NAME>]
- [--context-dir <CONTEXT_PATH>] [--load-context <LOAD_CONTEXT_NAME>]
- [(--temperature|-t) <TEMP>] [--allow-rxpy-in-run-mode]
- [--skill <SKILL>]... <NAME> <PROMPT>
-agents actor add --config|-c <FILE> [--update]
-agents actor remove <NAME>
-agents actor list
-agents actor show <NAME>
-agents actor context remove [--yes|-y] (--all|-a|<NAME>)
-agents actor context list [<REGEX>]
-agents actor context show <NAME>
-agents actor context export (--output|-o) <FILE> <NAME>
-agents actor context import [--update] (--input|-i) <FILE> [<NAME>]
-agents actor context clear [--yes|-y] (--all|-a|<NAME>)
-
-agents skill add --config|-c <FILE> [--update]
-agents skill remove [--yes|-y] <NAME>
-agents skill list [(--namespace|-n) <NS>] [--source <SOURCE>]
-agents skill show <NAME>
-agents skill tools <NAME>
-
-agents tool add --config|-c <FILE> [--update]
-agents tool remove [--yes|-y] <NAME>
-agents tool list [(--namespace|-n) <NS>] [--source <SOURCE>] [--type (tool|validation)] [<REGEX>]
-agents tool show <NAME>
-
-agents lsp add --config|-c <FILE> [--update]
-agents lsp remove [--yes|-y] <NAME>
-agents lsp list [(--namespace|-n) <NS>] [--language <LANG>]
-agents lsp show <NAME>
-agents lsp serve [--log-level <LEVEL>]
-
-agents resource type add --config|-c <FILE> [--update]
-agents resource type remove [--yes|-y] <NAME>
-agents resource type list [<REGEX>]
-agents resource type show <NAME>
-
-agents resource add [(--description|-d) <DESC>] [--update] <TYPE> <NAME> [type-specific-flags...]
-agents resource remove [--yes|-y] <NAME>
-agents resource list [--all] [(--type|-t) <TYPE>]
-agents resource show <RESOURCE>
-agents resource inspect [--tree] [--file <PATH>] <RESOURCE>
-agents resource tree [(--depth|-d) <N>] [(--type|-t) <TYPE>] <RESOURCE>
-agents resource link-child <PARENT> <CHILD>
-agents resource unlink-child [--yes|-y] <PARENT> <CHILD>
-agents resource stop <NAME>
-agents resource rebuild <NAME>
-
-agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
- [--action <ACTION>] [<REGEX>]
-agents plan use [--automation-profile <PROFILE>]
- [--invariant <INVARIANT>]...
- [--strategy-actor <STRATEGY_ACTOR>]
- [--execution-actor <EXEC_ACTOR>]
- [--estimation-actor <EST_ACTOR>]
- [--invariant-actor <INV_ACTOR>]
- [--execution-environment <RESOURCE_NAME>]
- [--execution-env-priority (fallback|override)]
- [--arg/-a name=value]...
- <ACTION> <PROJECT>...
-agents plan execute <PLAN_ID>
-agents plan apply [--yes|-y] <PLAN_ID>
-agents plan status <PLAN_ID>
-agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>
-agents plan tree [--show-superseded] <PLAN_ID>
-agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>
-agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE>
- [--dry-run] [--yes|-y] <DECISION_ID>
-agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>)
-agents plan artifacts <PLAN_ID>
-agents plan prompt <PLAN_ID> <GUIDANCE>
-agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>
-agents plan errors <PLAN_ID>
-
-agents action create --config|-c <CFG_FILE>
-agents action list [(--namespace|-n) <NS>] [(--state|-s) <STATE>] [<REGEX>]
-agents action show <ACTION_NAME>
-agents action archive <ACTION_NAME>
-
-agents automation-profile add --config|-c <FILE> [--update]
-agents automation-profile remove [--yes|-y] <NAME>
-agents automation-profile list [<REGEX>]
-agents automation-profile show <NAME>
-
-agents config set <key> <value>
-agents config get <key>
-agents config list [--filter-values <REGEX>] [<REGEX>]
-
-agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]...
- [--action ACTION]... <INVARIANT_TEXT>
-agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID] [--action ACTION]
- [--effective] [<REGEX>]
-agents invariant remove [--yes|-y] <INVARIANT_ID>
-
- $ agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info
-
- ╭─ System Snapshot ─────────────────╮
- │ CleverAgents 1.0.0 │
- │ Mode: local │
- │ Automation: review │
- │ Status: ready │
- ╰───────────────────────────────────╯
-
- ╭─ Paths ───────────────────────────────╮
- │ Data Dir: /srv/cleveragents │
- │ Config: /srv/cleveragents/config.toml │
- │ Logs: /srv/cleveragents/logs │
- │ Cache: /srv/cleveragents/cache │
- │ Database: /srv/cleveragents/agents.db │
- ╰───────────────────────────────────────╯
-
- ╭─ Runtime ──────────╮
- │ PID: 4127 │
- │ Uptime: 00:14:32 │
- │ Python: 3.13.1 │
- │ Host: devbox.local │
- │ Platform: linux │
- ╰────────────────────╯
-
- ╭─ Projects & Sessions ─╮
- │ Projects: 2 │
- │ Sessions: 1 active │
- │ Active Plans: 0 │
- │ Actors: 3 │
- ╰───────────────────────╯
-
- ✓ OK Environment loaded
- agents version
- $ agents version
-
- ╭─ CLI Version ────╮
- │ CleverAgents CLI │
- │ Version: 1.0.0 │
- │ Channel: stable │
- │ Python: 3.13 │
- ╰──────────────────╯
-
- ╭─ Build ────────────────╮
- │ Build Date: 2026-02-08 │
- │ Commit: a17c3f9 │
- │ Schema: v3 │
- │ Platform: linux-x86_64 │
- ╰────────────────────────╯
-
- ╭─ Dependencies ─────────────────╮
- │ LangGraph: 0.2.60 │
- │ LangChain: 0.3.18 │
- │ MCP SDK: 1.4.0 │
- │ Pydantic: 2.10.4 │
- ╰────────────────────────────────╯
-
- ✓ OK Version reported
- agents info
- $ agents info
-
- ╭─ Environment ───────────────────────────────────────────────╮
- │ Data Dir: /home/alex/.cleveragents │
- │ Config: /home/alex/.cleveragents/config.toml │
- │ Database: sqlite:///home/alex/.cleveragents/cleveragents.db │
- │ Server Mode: disabled │
- │ Platform: Linux 6.8.0 (x86_64) │
- ╰─────────────────────────────────────────────────────────────╯
-
- ╭─ Runtime ─────────────────────────╮
- │ Automation: review │
- │ Providers: 3 configured │
- │ Sessions: 2 active │
- │ Active Plans: 1 │
- ╰───────────────────────────────────╯
-
- ╭─ Storage ─────╮
- │ Cache: 118 MB │
- │ Logs: 42 MB │
- │ Backups: 3 │
- │ DB Size: 8 MB │
- ╰───────────────╯
-
- ╭─ Indexing ─────────────╮
- │ Text Index: ready │
- │ Vector Index: ready │
- │ Graph Store: disabled │
- │ Indexed Files: 1,247 │
- ╰────────────────────────╯
-
- ✓ OK Environment details ready
- agents diagnostics
- $ agents diagnostics
-
- ╭─ Checks ──────────────────────────────────────────────────╮
- │ Check Status Details │
- │ ─────────────────────────── ────── ───────────────────── │
- │ Config file OK readable │
- │ Database OK writable │
- │ OpenAI key WARN missing │
- │ Anthropic key OK configured │
- │ Google key WARN missing │
- │ Gemini key WARN missing │
- │ Azure OpenAI key WARN missing │
- │ OpenRouter key WARN missing │
- │ Cohere key WARN missing │
- │ Groq key WARN missing │
- │ Together key WARN missing │
- │ Disk space OK 2.1 GB free │
- │ Text index OK tantivy 0.22 │
- │ Vector index OK faiss (CPU) │
- │ Graph store WARN not configured │
- │ File permissions OK data dir r/w │
- │ Git OK git 2.43.0 │
- ╰───────────────────────────────────────────────────────────╯
-
- ╭─ Summary ─────────╮
- │ Checks: 17 total │
- │ Warnings: 9 │
- │ Errors: 0 │
- │ Duration: 0.6s │
- ╰───────────────────╯
-
- ╭─ Recommendations ──────────────────────────────────────────────╮
- │ - Set OPENAI_API_KEY to enable OpenAI models │
- │ - Set GOOGLE_API_KEY to enable Google models │
- │ - Set GEMINI_API_KEY to enable Gemini models │
- │ - Set AZURE_OPENAI_API_KEY to enable Azure OpenAI models │
- │ - Set OPENROUTER_API_KEY to enable OpenRouter models │
- │ - Set COHERE_API_KEY to enable Cohere models │
- │ - Set GROQ_API_KEY to enable Groq models │
- │ - Set TOGETHER_API_KEY to enable Together models │
- │ - Configure a graph store backend for structural code queries │
- ╰────────────────────────────────────────────────────────────────╯
-
- ⚠ WARN 9 warnings require attention
-
- $ agents diagnostics
-
- ╭─ Checks ──────────────────────────────────────────────────╮
- │ Check Status Details │
- │ ─────────────────────────── ─────── ───────────────────────────── │
- │ Config file OK readable │
- │ Database ERROR locked by another process │
- │ OpenAI key ERROR invalid key format │
- │ Anthropic key OK configured │
- │ Google key WARN missing │
- │ Gemini key WARN missing │
- │ Azure OpenAI key WARN missing │
- │ OpenRouter key WARN missing │
- │ Cohere key WARN missing │
- │ Groq key WARN missing │
- │ Together key WARN missing │
- │ Disk space WARN 312 MB free (low) │
- │ Text index OK tantivy 0.22 │
- │ Vector index ERROR FAISS library not found │
- │ Graph store OK neo4j 5.15 │
- │ File permissions OK data dir r/w │
- │ Git OK git 2.43.0 │
- ╰───────────────────────────────────────────────────────────╯
-
- ╭─ Summary ─────────╮
- │ Checks: 17 total │
- │ Warnings: 8 │
- │ Errors: 3 │
- │ Duration: 1.2s │
- ╰───────────────────╯
-
- ╭─ Errors (must fix) ─────────────────────────────────────────────────╮
- │ 1. Database is locked by PID 12847 — stop the other process or │
- │ delete the lock file at ~/.cleveragents/agents.db-lock │
- │ 2. OpenAI key starts with "pk-" — expected "sk-" prefix │
- │ Run: agents config set provider.openai.api-key │
- │ 3. FAISS library not installed — vector search will not work │
- │ Run: pip install faiss-cpu │
- ╰─────────────────────────────────────────────────────────────────────╯
-
- ✗ ERROR 3 errors must be resolved before CleverAgents can operate
- agents init [--yes|-y]
- $ agents init
-
- Warning: This will remove all data in /home/alex/.cleveragents
- Continue? [y/N]: y
-
- ╭─ Environment Reset ────────────────────────────────╮
- │ Config: /home/alex/.cleveragents/config.toml │
- │ Database: /home/alex/.cleveragents/cleveragents.db │
- │ Backup: /home/alex/.cleveragents.backup-2026-02-08 │
- │ Status: ready │
- ╰────────────────────────────────────────────────────╯
-
- ╭─ Defaults ──────────────────────────────────╮
- │ Automation Profile: supervised │
- │ Built-in Profiles: 8 loaded │
- ╰─────────────────────────────────────────────╯
-
- ╭─ Created ─────────────────╮
- │ Config: config.toml │
- │ Database: cleveragents.db │
- │ Logs: logs/ │
- │ Cache: cache/ │
- │ Backups: backups/ │
- ╰───────────────────────────╯
-
- ╭─ Schema ───────────────────────╮
- │ Version: v3 │
- │ Tables: 12 created │
- │ Migrations: up to date │
- ╰────────────────────────────────╯
-
- ✓ OK Environment initialized
-
- $ agents init --yes
-
- ╭─ Initialized ──────────────────────────────────────────╮
- │ Data Dir: /home/alex/.cleveragents (created) │
- │ Config: /home/alex/.cleveragents/config.toml │
- │ Database: initialized (schema v3) │
- │ Directories: logs, cache, sessions, contexts │
- ╰────────────────────────────────────────────────────────╯
-
- ✓ OK Initialized (non-interactive)
- agents session create [--actor <ACTOR>]
- $ agents session create --actor local/orchestrator
-
- ╭─ Session ───────────────────────╮
- │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
- │ Actor: local/orchestrator │
- │ Created: 2026-02-08 12:44 │
- │ Namespace: local │
- ╰─────────────────────────────────╯
-
- ╭─ Settings ─────────────╮
- │ Automation: review │
- │ Streaming: off │
- │ Context: default │
- │ Memory: enabled │
- │ Max History: 50 turns │
- ╰────────────────────────╯
-
- ╭─ Actor Details ───────────────────╮
- │ Provider: anthropic │
- │ Model: claude-3.5 │
- │ Temperature: 0.7 │
- │ Context Window: 200K tokens │
- ╰───────────────────────────────────╯
-
- ✓ OK Session created
- agents session list
- $ agents --format table session list
-
- ╭─ Sessions ───────────────────────────────────────────────────────────────────╮
- │ ID Name Actor Messages Updated │
- │ ──────── ─────────────── ────────────────── ──────── ──────────────── │
- │ 01HXM2A6 weekly-planning local/orchestrator 6 2026-02-08 12:44 │
- │ 01HXM1F2 refactor-sprint local/orchestrator 14 2026-02-07 18:11 │
- ╰──────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ────────────────────╮
- │ Total: 2 │
- │ Most Recent: weekly-planning │
- │ Oldest: refactor-sprint │
- │ Total Messages: 20 │
- │ Storage: 42 KB │
- ╰──────────────────────────────╯
-
- ✓ OK 2 sessions listed
- agents session show <SESSION_ID>
- $ agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
-
- ╭─ Session Summary ───────────────╮
- │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
- │ Actor: local/orchestrator │
- │ Messages: 6 │
- │ Created: 2026-02-08 12:30 │
- │ Updated: 2026-02-08 12:44 │
- │ Automation: review │
- ╰─────────────────────────────────╯
-
- ╭─ Recent Messages ──────────────────────────────────╮
- │ user Create an action to refresh dependency locks │
- │ assistant Plan created, running commands... │
- │ assistant Completed 2 commands │
- ╰────────────────────────────────────────────────────╯
-
- ╭─ Linked Plans ────────────────────────────────╮
- │ Plan ID Phase State │
- │ ────────────────────────── ────── ──────── │
- │ 01HXM8C2ZK4Q7C2B3F2R4VYV6J execute complete │
- ╰───────────────────────────────────────────────╯
-
- ╭─ Token Usage ──────────────╮
- │ Input Tokens: 3,420 │
- │ Output Tokens: 1,185 │
- │ Estimated Cost: $0.0184 │
- ╰────────────────────────────╯
-
- ✓ OK Session details loaded
- agents session delete [--yes|-y] <SESSION_ID>
- $ agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
-
- Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
-
- ╭─ Deletion Summary ──────────────────╮
- │ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
- │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
- │ Messages: 6 removed │
- │ Storage: 18 KB freed │
- │ Plans Orphaned: 0 │
- ╰─────────────────────────────────────╯
-
- ╭─ Cleanup ───────────╮
- │ Backups: none │
- │ Logs: preserved │
- │ Context: cleared │
- │ Checkpoints: none │
- ╰─────────────────────╯
-
- ✓ OK Session deleted
- agents session export [(--output|-o) <FILE>] <SESSION_ID>
- $ agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
-
- ╭─ Session Export ────────────────────╮
- │ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
- │ Output: /tmp/weekly-planning.json │
- │ Messages: 6 │
- │ Size: 24 KB │
- │ Format: JSON │
- ╰─────────────────────────────────────╯
-
- ╭─ Contents ─────────────────╮
- │ Messages: 6 │
- │ Plan References: 1 │
- │ Metadata Keys: 2 │
- │ Actor Config: included │
- │ Schema Version: v3 │
- ╰────────────────────────────╯
-
- ╭─ Integrity ──────────────────╮
- │ Checksum: sha256:7a9b...42c1 │
- │ Encrypted: no │
- ╰──────────────────────────────╯
-
- ✓ OK Export completed
- agents session import (--input|-i) <FILE>
- $ agents session import --input /tmp/weekly-planning.json
-
- ╭─ Session Import ────────────────────────╮
- │ Input: /tmp/weekly-planning.json │
- │ Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1 │
- │ Messages: 6 │
- │ Schema: v3 │
- ╰─────────────────────────────────────────╯
-
- ╭─ Validation ────────────╮
- │ Checksum: verified │
- │ Schema: compatible │
- │ Actor Ref: resolved │
- ╰─────────────────────────╯
-
- ╭─ Merge ──────────────╮
- │ Existing: none │
- │ Strategy: create new │
- ╰──────────────────────╯
-
- ✓ OK Import completed
- agents session tell --session <SESSION_ID> [--actor <ACTOR>] [--stream] <PROMPT>
- $ agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
- --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
-
- ╭─ Plan Request ──────────────────────────────────────────╮
- │ Actor: local/orchestrator │
- │ Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
- │ Automation: review │
- │ Prompt: Create an action to refresh dependency locks... │
- ╰─────────────────────────────────────────────────────────╯
-
- ╭─ Commands Executed ─────────────────────────────────────────────────────────────────────────────────────────╮
- │ - agents action create --config ./actions/refresh-locks.yaml │
- │ - agents resource add git-checkout local/platform-repo --path /repos/platform │
- │ - agents project link-resource local/platform local/platform-repo │
- ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Result ──────────────────────────╮
- │ Action: local/refresh-locks │
- │ Project: local/platform │
- │ Resource: local/platform-repo │
- ╰───────────────────────────────────╯
-
- ╭─ Usage ─────────────────────╮
- │ Input Tokens: 1,842 │
- │ Output Tokens: 624 │
- │ Cost: $0.0094 │
- │ Duration: 3.2s │
- │ Tool Calls: 3 │
- ╰─────────────────────────────╯
-
- ✓ OK Orchestrator completed 3 commands
-
- $ agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?"
-
- ╭─ Session ──────────────────────────╮
- │ ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
- │ Actor: local/orchestrator │
- │ Mode: streaming │
- ╰────────────────────────────────────╯
-
- ▍ The last plan (01HXM8C2ZK) modified 6 files in the auth module:
-
- 1. `src/auth/session.py` — refactored session validation
- 2. `src/auth/tokens.py` — updated token expiry to 7200s
- 3. `src/auth/__init__.py` — updated exports
- 4. `tests/test_auth.py` — added 12 new test cases
- 5. `tests/test_session.py` — updated session fixtures
- 6. `docs/auth.md` — updated API documentation
-
- All changes passed validation (24/24 tests, lint clean).
-
- ╭─ Usage ──────────────────╮
- │ Tokens: 1,240 (stream) │
- │ Duration: 3.1s │
- │ Tool Calls: 2 │
- ╰──────────────────────────╯
-
- ✓ OK Stream complete
- agents project create [(--description|-d) <DESC>] [--resource <RESOURCE>]...
- [--invariant <INVARIANT>]... [--invariant-actor <ACTOR>] <NAME>
- $ agents project create --description "Backend API" local/api-service
-
- ╭─ Project ──────────────────────╮
- │ Name: local/api-service │
- │ Description: Backend API │
- │ Type: local │
- │ Created: 2026-02-08 12:46 │
- ╰────────────────────────────────╯
-
- ╭─ Paths ────────────────────────────────────╮
- │ Root: /repos/api-service │
- │ Data Dir: /repos/api-service/.cleveragents │
- ╰────────────────────────────────────────────╯
-
- ╭─ Defaults ──────────────────────────────╮
- │ Sandbox: git_worktree │
- │ Validations: 0 │
- │ Context Filters: none │
- │ Automation Profile: (inherits global) │
- ╰─────────────────────────────────────────╯
-
- ╭─ Resources ──────╮
- │ Total: 0 │
- │ Indexed: 0 │
- │ Sandboxable: 0 │
- ╰──────────────────╯
-
- ✓ OK Project created
-
- $ agents project create -d "Frontend web application" \
- --resource local/web-repo --resource local/web-db \
- --invariant "All components must have unit tests" \
- --invariant "CSS must pass stylelint checks" \
- --invariant-actor local/invariant-resolver \
- local/web-app
-
- ╭─ Project Created ─────────────────────╮
- │ Name: local/web-app │
- │ Description: Frontend web app │
- │ Remote: no │
- ╰───────────────────────────────────────╯
-
- ╭─ Linked Resources ───────────────────────────────────────╮
- │ Name Type Read-Only │
- │ ───────────────── ────────────── ───────── │
- │ local/web-repo git-checkout no │
- │ local/web-db local/database no │
- ╰──────────────────────────────────────────────────────────╯
-
- ╭─ Invariants ────────────────────────────────────╮
- │ 1. All components must have unit tests │
- │ 2. CSS must pass stylelint checks │
- │ Reconciliation Actor: local/invariant-resolver │
- ╰─────────────────────────────────────────────────╯
-
- ✓ OK Project created
- agents project link-resource [--read-only] <PROJECT> <RESOURCE>
- $ agents resource add git-checkout local/api-repo --path /repos/api --branch main
- $ agents project link-resource local/api-service local/api-repo
-
- ╭─ Resource Linked ───────────────────────╮
- │ Project: local/api-service │
- │ Resource: local/api-repo │
- │ Type: git-checkout │
- │ Read-Only: no │
- ╰─────────────────────────────────────────╯
-
- ╭─ Access ─────────────────╮
- │ Read: allowed │
- │ Write: allowed │
- │ Apply: requires approval │
- ╰──────────────────────────╯
-
- ╭─ Indexing ─────────────────────╮
- │ Status: indexing... │
- │ Files Found: 347 │
- │ Language: Python (primary) │
- │ Estimated Time: ~20 seconds │
- ╰────────────────────────────────╯
-
- ✓ OK Resource linked to project
- agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE_NAME>
- $ agents project unlink-resource local/api-service local/api-repo
-
- Unlink local/api-repo from local/api-service? [y/N]: y
-
- ╭─ Resource Unlinked ─────────────────────────────────╮
- │ Project: local/api-service │
- │ Resource: local/api-repo │
- │ Type: git-checkout │
- ╰─────────────────────────────────────────────────────╯
-
- ╭─ Index Cleanup ──────────╮
- │ Text Index: 347 removed │
- │ Vectors: 892 removed │
- │ Graph Triples: cleared │
- │ Duration: 0.3s │
- ╰──────────────────────────╯
-
- ╭─ Project Summary ──────────────╮
- │ Linked Resources: 1 remaining │
- │ Last Updated: 2026-02-09 10:30 │
- │ Active Plans: 0 │
- ╰────────────────────────────────╯
-
- ✓ OK Resource unlinked from project
- agents project list [(--namespace|-n) NS] [<REGEX>]
- $ agents --format table project list
-
- ╭─ Projects ────────────────────────────────────────────────────╮
- │ Name Resources Remote Active Plans │
- │ ───────────────── ───────── ────── ──────────── │
- │ local/api-service 2 No 1 │
- │ local/docs 1 No 0 │
- ╰───────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ──────────────────╮
- │ Total: 2 │
- │ With Resources: 2 │
- │ Remote: 0 │
- │ Total Resources: 3 │
- │ Indexed Files: 1,247 │
- │ Active Plans: 1 │
- ╰────────────────────────────╯
-
- ✓ OK 2 projects listed
- agents project show <PROJECT>
- $ agents project show local/api-service
-
- ╭─ Project Details ──────────────╮
- │ Name: local/api-service │
- │ Description: Backend API │
- │ Resources: 2 │
- │ Remote: no │
- │ Created: 2026-02-08 12:46 │
- ╰────────────────────────────────╯
-
- ╭─ Linked Resources ──────────────────────────────────────────────────────╮
- │ Resource Type Sandbox Read-Only │
- │ ──────────────── ────────────── ──────────────────── ───────── │
- │ local/api-repo git-checkout git_worktree no │
- │ local/staging-db local/database transaction_rollback yes │
- ╰─────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Validations (3) ──────────────────────────────────────────────────────────────────╮
- │ local/run-tests Run unit tests with coverage required │
- │ resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7…) │
- │ local/lint-check Lint check required │
- │ resource: local/api-repo scope: direct (always active) (attachment: 01HXM5…) │
- │ local/check-bundle-size Check bundle size (advisory) informational │
- │ resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9…) │
- ╰────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Context ───────────────────╮
- │ Include: repo │
- │ Exclude: **/node_modules/** │
- │ Max File Size: 1 MB │
- ╰─────────────────────────────╯
-
- ╭─ Indexing Status ──────────╮
- │ Text Index: ready │
- │ Vector Index: ready │
- │ Graph Store: disabled │
- │ Indexed Files: 347 │
- │ Last Indexed: 12:48 │
- ╰────────────────────────────╯
-
- ╭─ Active Plans ──────────────────────────╮
- │ Plan ID Action Phase │
- │ ──────── ─────────────────── ─────── │
- │ 01HXM7A9 local/code-coverage execute │
- ╰─────────────────────────────────────────╯
-
- ✓ OK Project loaded
- agents project delete [--force|-f] [--yes|-y] <NAME>
- $ agents project delete local/docs
-
- Delete project local/docs? This cannot be undone. [y/N]: y
-
- ╭─ Deletion Summary ──────────────────╮
- │ Project: local/docs │
- │ Resources: 1 unlinked │
- │ Data Dir: /repos/docs/.cleveragents │
- ╰─────────────────────────────────────╯
-
- ╭─ Index Cleanup ────────╮
- │ Text Index: cleared │
- │ Vectors: 240 removed │
- │ Graph Triples: none │
- │ Storage Freed: 12 MB │
- ╰────────────────────────╯
-
- ╭─ Backups ────────────────────────────────────╮
- │ Snapshot: /backups/local-docs-2026-02-08.tgz │
- │ Retention: 7 days │
- ╰──────────────────────────────────────────────╯
-
- ✓ OK Project deleted
-
- $ agents project delete local/api-service
-
- Delete project local/api-service? [y/N]: y
-
- ╭─ Delete Blocked ──────────────────────────────────────────╮
- │ Cannot delete: project has active plans │
- │ Active Plans: 2 │
- │ 01HXM7A9 — execute/processing (local/code-coverage) │
- │ 01HXM4J1 — strategize/processing (local/refactor-api) │
- ╰───────────────────────────────────────────────────────────╯
-
- ╭─ Resolution ──────────────────────────────────────────────────────╮
- │ - Cancel or complete active plans first, or │
- │ - Use --force to cancel all active plans and delete the project │
- ╰───────────────────────────────────────────────────────────────────╯
-
- ✗ ERROR Delete blocked — 2 active plans
-
- $ agents project delete --force --yes local/api-service
-
- ╭─ Force Delete ─────────────────────────────────────────╮
- │ Cancelling: 2 active plans │
- │ 01HXM7A9 — cancelled (was execute/processing) │
- │ 01HXM4J1 — cancelled (was strategize/processing) │
- ╰────────────────────────────────────────────────────────╯
-
- ╭─ Deleted ────────────────────╮
- │ Project: local/api-service │
- │ Resources Unlinked: 2 │
- │ Validations Detached: 3 │
- │ Plans Cancelled: 2 │
- │ Context Policies: cleared │
- ╰──────────────────────────────╯
-
- ✓ OK Project force-deleted
- agents project context set[--view (strategize|execute|apply|default)]
- [--include-resource <INCLUDE_RESOURCE>]...
- [--exclude-resource <EXCLUDE_RESOURCE>]...
- [--include-path <INCLUDE_GLOB>]...
- [--exclude-path <EXCLUDE_GLOB>]...
- [--hot-max-tokens <N>]
- [--warm-max-decisions <N_WARM_MAX>]
- [--cold-max-decisions <N_COLD_MAX>]
- [--query-limit <N>]
- [--max-file-size <MAX_FILE_BYTES>]
- [--max-total-size <MAX_TOTAL_BYTES>]
- [--summarize|--no-summarize]
- [--summary-max-tokens <N>]
- [--strategy <STRATEGY>]...
- [--default-breadth <N>]
- [--default-depth <INT_OR_NAME>]
- [--depth-gradient <HOP:INT_OR_NAME>]...
- [--skeleton-ratio <FLOAT>]
- [--temporal-scope (current|recent|all)]
- [--auto-refresh|--no-auto-refresh]
- [--execution-environment <RESOURCE_NAME>]
- [--execution-env-priority (fallback|override)]
- [--clear] <PROJECT>
- $ agents project context set --view strategize \
- --include-resource repo --exclude-path "**/node_modules/**" \
- --hot-max-tokens 12000 --warm-max-decisions 50 --cold-max-decisions 200 \
- --summarize --summary-max-tokens 800 local/api-service
-
- ╭─ Context Policy ────────────╮
- │ Project: local/api-service │
- │ View: strategize │
- │ Include: repo │
- │ Exclude: **/node_modules/** │
- ╰─────────────────────────────╯
-
- ╭─ Limits ─────────────────────╮
- │ Hot Tokens: 12000 (soft cap) │
- │ Warm Decisions: 50 │
- │ Cold Decisions: 200 │
- │ Query Limit: 20 │
- │ Max File Size: 1 MB │
- │ Max Total Size: 50 MB │
- ╰──────────────────────────────╯
-
- ╭─ Summarization ─╮
- │ Enabled: yes │
- │ Max Tokens: 800 │
- ╰─────────────────╯
-
- ╭─ Other Views ────────╮
- │ execute: (default) │
- │ apply: (default) │
- │ default: (unset) │
- ╰──────────────────────╯
-
- ✓ OK Context policy updated
- agents project context show [--view (strategize|execute|apply|default)]
- <PROJECT>
- $ agents project context show --view strategize local/api-service
-
- ╭─ Context Policy ────────────╮
- │ Project: local/api-service │
- │ View: strategize │
- │ Include: repo │
- │ Exclude: **/node_modules/** │
- ╰─────────────────────────────╯
-
- ╭─ Limits ─────────────────────╮
- │ Hot Tokens: 12000 (soft cap) │
- │ Warm Decisions: 50 │
- │ Cold Decisions: 200 │
- │ Query Limit: 20 │
- │ Max File Size: 1 MB │
- │ Max Total Size: 50 MB │
- ╰──────────────────────────────╯
-
- ╭─ Summarization ─╮
- │ Enabled: yes │
- │ Max Tokens: 800 │
- ╰─────────────────╯
-
- ╭─ Current Usage ──────────────╮
- │ Hot Context: 8,420 / 12,000 │
- │ Warm Entries: 12 / 50 │
- │ Cold Entries: 47 / 200 │
- │ Indexed Resources: 1 │
- ╰──────────────────────────────╯
-
- ✓ OK Context policy loaded
- agents project context inspect [--view (strategize|execute|apply|default)]
- [--strategy <STRATEGY>]
- [--focus <UKO_URI>]...
- [--breadth <N>] [--depth <INT_OR_NAME>]
- <PROJECT>
- $ agents project context inspect --view execute --focus uko-py:module/src.auth --breadth 2 local/api-service
-
- ╭─ ACMS Context Inspection ────────────────────────────────────────╮
- │ Project: local/api-service │
- │ View: execute │
- │ Focus: uko-py:module/src.auth │
- │ Breadth: 2 hops │ Depth: 3 (MEMBER_SUMMARY) │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ UKO Graph (2-hop neighborhood) ─────────────────────────────────╮
- │ uko-py:module/src.auth (depth 9/FULL_SOURCE, 1,240 tokens) │
- │ ├─ contains → uko-py:class/AuthHandler (depth 3, 320 tokens) │
- │ ├─ contains → uko-py:class/TokenValidator (depth 3, 280 tok) │
- │ ├─ imports → uko-py:module/src.db (depth 0, 90 tokens) │
- │ └─ imports → uko-py:module/src.config (depth 0, 60 tok) │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Active Strategies ──────────────────────────────────────────────╮
- │ breadth-depth-navigator quality=0.85 budget=45% 4 fragments │
- │ semantic-embedding quality=0.60 budget=35% 6 fragments │
- │ simple-keyword quality=0.30 budget=20% 3 fragments │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Budget ─────────────────────────────╮
- │ Model Window: 128,000 tokens │
- │ Response Reserve: 4,096 tokens │
- │ Tool Definitions: 2,400 tokens │
- │ System Prompt: 1,200 tokens │
- │ Skeleton Reserve: 18,046 (15%) │
- │ Available Budget: 102,258 tokens │
- │ Used: 1,990 / 102,258 (1.9%) │
- ╰──────────────────────────────────────╯
-
- ✓ OK Context inspection complete
- agents project context simulate [--view (strategize|execute|apply|default)]
- [--budget <TOKENS>]
- [--focus <UKO_URI>]...
- [--strategy <STRATEGY>]...
- <PROJECT>
- $ agents project context simulate --view strategize --budget 16000 \
- --focus uko-py:module/src.auth --focus uko-py:module/src.db \
- local/api-service
-
- ╭─ ACMS Simulation ────────────────────────────────────────────────╮
- │ Project: local/api-service │
- │ View: strategize │
- │ Budget: 16,000 tokens (override) │
- │ Focus: uko-py:module/src.auth, uko-py:module/src.db │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Strategy Results ───────────────────────────────────────────────╮
- │ breadth-depth-navigator │
- │ Confidence: 0.85 │ Budget: 7,200 tokens │ 12 fragments │
- │ Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95) │
- │ src/db/models.py (depth 3, 480t, score=0.88) │
- │ │
- │ semantic-embedding │
- │ Confidence: 0.60 │ Budget: 5,600 tokens │ 8 fragments │
- │ Top: src/auth/jwt.py (depth 3, 380t, score=0.82) │
- │ src/middleware/auth_check.py (depth 3, 290t, score=0.79) │
- │ │
- │ simple-keyword │
- │ Confidence: 0.30 │ Budget: 3,200 tokens │ 5 fragments │
- │ Top: src/auth/utils.py (depth 6, 210t, score=0.71) │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Fusion Result ──────────────────────────────────────────────────╮
- │ Included: 18 fragments (14,820 tokens, 92.6% of budget) │
- │ Excluded: 7 fragments (3,200 tokens, below budget cutoff) │
- │ Deduplicated: 4 fragments merged │
- │ Skeleton: 2,400 tokens (15% reserve) │
- │ Preamble: 180 tokens │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ✓ OK Simulation complete (dry run — no context was assembled)
- agents actor run [(--output|-o) <OUTPUT_FILE>]
- [-v...] [--unsafe|-u] [--context <CONTEXT_NAME>]
- [--context-dir <CONTEXT_PATH>] [--load-context <LOAD_CONTEXT_NAME>]
- [(--temperature|-t) <TEMP>] [--allow-rxpy-in-run-mode]
- [--skill <SKILL>]... <NAME> <PROMPT>
- $ agents actor run --context docs local/code_reader "Summarize the README"
-
- ╭─ Run Summary ─────────────────╮
- │ Actor: local/code_reader │
- │ Context: docs │
- │ Temperature: 0.2 │
- │ Provider: anthropic │
- │ Model: claude-3.5 │
- ╰───────────────────────────────╯
-
- ╭─ Inputs ─────────────────────╮
- │ Prompt: Summarize the README │
- │ Context Files: 3 │
- │ Context Size: 12.4 KB │
- ╰──────────────────────────────╯
-
- ╭─ Result Metrics ───────╮
- │ Output: stdout │
- │ Input Tokens: 1,524 │
- │ Output Tokens: 842 │
- │ Duration: 1.8s │
- │ Cost: $0.0021 │
- │ Tool Calls: 0 │
- ╰────────────────────────╯
-
- ✓ OK Summary generated
-
- $ agents actor run --temperature 0.2 --skill local/code-analysis \
- local/reviewer "Review the auth module for security issues"
-
- ╭─ Actor Run ─────────────────────────╮
- │ Actor: local/reviewer │
- │ Type: agent │
- │ Temperature: 0.2 │
- │ Skill: local/code-analysis │
- ╰─────────────────────────────────────╯
-
- ╭─ Response ────────────────────────────────────────────────────────╮
- │ I identified 3 potential security concerns in the auth module: │
- │ │
- │ 1. Token expiry not validated in `validate_session()` at │
- │ src/auth/session.py:42. The JWT expiry claim is decoded but │
- │ not checked against current time. │
- │ │
- │ 2. Missing rate limiting on the `/auth/refresh` endpoint. │
- │ An attacker could brute-force refresh tokens. │
- │ │
- │ 3. Low severity: Password hashing uses bcrypt with cost=10. │
- │ Consider cost=12 for production deployments. │
- ╰───────────────────────────────────────────────────────────────────╯
-
- ╭─ Usage ──────────────╮
- │ Tokens: 2,840 │
- │ Duration: 4.2s │
- │ Cost: $0.009 │
- │ Tool Calls: 6 │
- ╰──────────────────────╯
-
- ✓ OK Actor run completed
-
- $ agents actor run --output review.md local/reviewer "Write a code review report"
-
- ╭─ Actor Run ───────────────╮
- │ Actor: local/reviewer │
- │ Output: review.md │
- │ Tokens: 4,120 │
- │ Duration: 6.8s │
- ╰───────────────────────────╯
-
- ✓ OK Output written to review.md (2.4 KB)
- agents actor add --config|-c <FILE> [--update]
- $ agents actor add --config ./actors/reviewer.yaml
-
- ╭─ Actor Added ────────╮
- │ Name: local/reviewer │
- │ Provider: openai │
- │ Model: gpt-4 │
- │ Default: yes │
- │ Unsafe: no │
- │ Type: graph │
- ╰──────────────────────╯
-
- ╭─ Config ─────────────────────╮
- │ Path: ./actors/reviewer.yaml │
- │ Hash: 8b3f3d2 │
- │ Options: 4 │
- │ Nodes: 3 │
- │ Edges: 4 │
- ╰──────────────────────────────╯
-
- ╭─ Capabilities ───────╮
- │ - code review │
- │ - diff summarization │
- │ - lint guidance │
- ╰──────────────────────╯
-
- ╭─ Tools ────────────────────────╮
- │ Tool Read-Only Safe │
- │ ──────────── ───────── ──── │
- │ read_file yes yes │
- │ search_files yes yes │
- │ git_diff yes yes │
- ╰────────────────────────────────╯
-
- ✓ OK Actor added
-
- $ agents actor add --config ./actors/reviewer.yaml
-
- ╭─ Error ─────────────────────────────────────────────────╮
- │ Actor already exists: local/reviewer │
- │ Registered: 2026-02-07 14:22 │
- │ Use --update to replace the existing actor definition. │
- ╰─────────────────────────────────────────────────────────╯
-
- ✗ ERROR Actor already registered — use --update to replace
-
- $ agents actor add --config ./actors/reviewer.yaml --update
-
- ╭─ Actor Updated ─────────────────────╮
- │ Name: local/reviewer │
- │ Type: agent │
- │ Status: updated │
- ╰─────────────────────────────────────╯
-
- ╭─ Changes ────────────────────────────╮
- │ Skills: +1 (local/code-analysis) │
- │ Model: unchanged │
- │ Graph: updated │
- ╰──────────────────────────────────────╯
-
- ✓ OK Actor updated
- agents actor remove <NAME>
- $ agents actor remove local/reviewer
-
- ╭─ Actor Removed ──────╮
- │ Name: local/reviewer │
- │ Provider: openai │
- │ Model: gpt-4 │
- ╰──────────────────────╯
-
- ╭─ Impact ───────────────────────────────────╮
- │ Sessions: 0 affected │
- │ Active Plans: 0 affected │
- │ Actions Referencing: 0 │
- ╰────────────────────────────────────────────╯
-
- ╭─ Cleanup ──────────────╮
- │ Config: kept on disk │
- │ Contexts: 1 orphaned │
- ╰────────────────────────╯
-
- ✓ OK Actor removed
- agents actor list
- $ agents actor list
-
- ╭─ Actors ──────────────────────────────────────────────────────────────╮
- │ Name Provider Model Default Built-in Unsafe │
- │ ────────────── ───────── ────────── ─────── ──────── ────── │
- │ local/reviewer openai gpt-4 ✓ no │
- │ openai/gpt-4 openai gpt-4 ✓ no │
- │ anthropic/3.5 anthropic claude-3.5 ✓ no │
- ╰───────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ──────────────╮
- │ Total: 3 │
- │ Built-in: 2 │
- │ Custom: 1 │
- │ Unsafe: 0 │
- │ Providers Used: 2 │
- ╰────────────────────────╯
-
- ✓ OK 3 actors listed
- agents actor show <NAME>
- $ agents actor show local/reviewer
-
- ╭─ Actor Details ────────────────────╮
- │ Name: local/reviewer │
- │ Provider: openai │
- │ Model: gpt-4 │
- │ Default: yes │
- │ Built-in: no │
- │ Unsafe: no │
- │ Type: graph │
- │ Created: 2026-02-08 12:35 │
- │ Updated: 2026-02-08 12:40 │
- │ Config: ./actors/reviewer.yaml │
- │ Config Hash: 9c4e2a1 │
- ╰────────────────────────────────────╯
-
- ╭─ Options ──────────╮
- │ - temperature: 0.2 │
- │ - max_tokens: 2048 │
- │ - top_p: 1.0 │
- ╰────────────────────╯
-
- ╭─ Graph Structure ─╮
- │ Nodes: 3 │
- │ Edges: 4 │
- │ Entry: analyze │
- │ Exit: report │
- ╰───────────────────╯
-
- ╭─ Tools ────────────────────────╮
- │ Tool Read-Only Safe │
- │ ──────────── ───────── ──── │
- │ read_file yes yes │
- │ search_files yes yes │
- │ git_diff yes yes │
- ╰────────────────────────────────╯
-
- ╭─ Access ────────────╮
- │ Unsafe: no │
- │ Filesystem: allowed │
- │ Network: restricted │
- ╰─────────────────────╯
-
- ╭─ Usage ─────────────────────────────────────────╮
- │ Referenced by Actions: 1 (local/code-coverage) │
- │ Active in Sessions: 0 │
- │ Total Runs: 14 │
- │ Avg Cost/Run: $0.0032 │
- ╰─────────────────────────────────────────────────╯
-
- ✓ OK Actor loaded
- agents actor context remove [--yes|-y] (--all|-a|<NAME>)
- $ agents actor context remove docs
-
- ╭─ Context Removed ───────────╮
- │ Context: docs │
- │ Status: removed │
- ╰─────────────────────────────╯
-
- ╭─ Stats ───────────────────╮
- │ Remaining Size: 48 KB │
- │ Updated: 2026-02-08 13:06 │
- ╰───────────────────────────╯
-
- ✓ OK Context updated
- agents actor context list [<REGEX>]
- $ agents actor context list docs
-
- ╭─ Context Files ──────────────────────────────╮
- │ Name Type Size Added │
- │ ──────────────── ──── ─────── ────────── │
- │ README.md file 4.2 KB 02-08 12:10 │
- │ docs/overview.md file 12.8 KB 02-08 12:10 │
- │ docs/cli.md file 9.5 KB 02-08 12:10 │
- ╰──────────────────────────────────────────────╯
-
- ╭─ Stats ───────────────────────╮
- │ Total Files: 3 │
- │ Total Size: 26.5 KB │
- │ Estimated Tokens: ~6,600 │
- │ Languages: Markdown │
- ╰───────────────────────────────╯
-
- ✓ OK 3 files listed
- agents actor context show <NAME>
- $ agents actor context show docs
-
- ╭─ Context Summary ───────────╮
- │ Context: docs │
- │ Files: 3 │
- │ Total Size: 26.5 KB │
- │ Estimated Tokens: ~6,600 │
- │ Created: 2026-02-08 12:10 │
- ╰─────────────────────────────╯
-
- ✓ OK Context displayed
- agents actor context export (--output|-o) <FILE> <NAME>
- $ agents actor context export --output /tmp/docs-context.json docs
-
- ╭─ Context Export ───────────────╮
- │ Context: docs │
- │ Output: /tmp/docs-context.json │
- │ Items: 12 │
- │ Size: 48 KB │
- ╰────────────────────────────────╯
-
- ╭─ Integrity ──────────────────╮
- │ Checksum: sha256:19b2...a7d0 │
- │ Compressed: no │
- ╰──────────────────────────────╯
-
- ✓ OK Export completed
- agents actor context import [--update] (--input|-i) <FILE> [<NAME>]
- $ agents actor context import --input /tmp/docs-context.json docs
-
- ╭─ Context Import ──────────────╮
- │ Context: docs │
- │ Input: /tmp/docs-context.json │
- │ Items: 12 │
- ╰───────────────────────────────╯
-
- ╭─ Merge ───────────╮
- │ Strategy: replace │
- │ Conflicts: 0 │
- ╰───────────────────╯
-
- ✓ OK Import completed
- agents actor context clear [--yes|-y] (--all|-a|<NAME>)
- $ agents actor context clear docs
-
- Clear context docs? [y/N]: y
-
- ╭─ Context Cleared ────╮
- │ Context: docs │
- │ Items: 12 removed │
- │ Storage: 48 KB freed │
- ╰──────────────────────╯
-
- ╭─ Retention ────────╮
- │ Context: preserved │
- │ Files: removed │
- ╰────────────────────╯
-
- ✓ OK Context cleared
- agents skill add --config|-c <FILE> [--update]
- $ agents skill add --config ./skills/devops-toolkit.yaml
-
- ╭─ Skill Registered ────────────────────────╮
- │ Name: local/devops-toolkit │
- │ Description: Full-stack development tools │
- │ Config: ./skills/devops-toolkit.yaml │
- │ Created: 2026-02-08 13:10 │
- ╰───────────────────────────────────────────╯
-
- ╭─ Includes ────────────────────╮
- │ local/file-ops (registered) │
- │ local/git-ops (registered) │
- │ local/github (registered) │
- ╰───────────────────────────────╯
-
- ╭─ Tool Sources ────────────────────────────────╮
- │ Source Count Details │
- │ ───────────── ───── ─────────────────── │
- │ builtin 14 file, dir, git, shell │
- │ mcp 6 github (4), linear (2) │
- │ agent_skill 2 deploy, code-review │
- │ custom 1 run_migrations │
- │ ───────────── ───── ─────────────────── │
- │ Total: 23 │
- ╰───────────────────────────────────────────────╯
-
- ╭─ MCP Servers ────────────────────╮
- │ linear: validated (2 tools) │
- ╰──────────────────────────────────╯
-
- ✓ OK Skill registered with 23 tools
-
- $ agents skill add --config ./skills/devops-toolkit-v2.yaml
-
- ✗ Error: Skill 'local/devops-toolkit' is already registered.
-
- To overwrite the existing configuration, re-run with --update:
-
- agents skill add --config ./skills/devops-toolkit-v2.yaml --update
-
- $ agents skill add --config ./skills/devops-toolkit-v2.yaml --update
-
- ╭─ Skill Updated ───────────────────────────╮
- │ Name: local/devops-toolkit │
- │ Description: Full-stack development tools │
- │ Updated: 2026-02-08 14:22 │
- ╰───────────────────────────────────────────╯
-
- ╭─ Changes ─────────────────────╮
- │ Tools Added: 2 │
- │ Tools Removed: 0 │
- │ Tools Modified: 1 │
- │ Includes Changed: no │
- │ MCP Servers Changed: no │
- ╰───────────────────────────────╯
-
- ╭─ Affected Actors ─────────────────────────────╮
- │ Warning: 2 actors reference this skill: │
- │ - local/code-assistant │
- │ - local/full-stack-assistant │
- │ These actors will pick up changes on next use │
- ╰───────────────────────────────────────────────╯
-
- ✓ OK Skill updated (23 → 25 tools)
- agents skill remove [--yes|-y] <NAME>
- $ agents skill remove local/devops-toolkit
-
- Remove skill local/devops-toolkit? [y/N]: y
-
- ╭─ Skill Removed ──────────────────────╮
- │ Name: local/devops-toolkit │
- │ Tools: 23 removed from registry │
- │ MCP Servers: 1 connection closed │
- ╰──────────────────────────────────────╯
-
- ╭─ Dependency Check ─────────────────────────────────╮
- │ Warning: 1 skill includes this skill: │
- │ - local/full-stack-dev (will lose devops tools) │
- │ Warning: 2 actors reference this skill: │
- │ - local/code-assistant │
- │ - local/full-stack-assistant │
- ╰────────────────────────────────────────────────────╯
-
- ✓ OK Skill removed
- agents skill list [(--namespace|-n) <NS>] [--source <SOURCE>]
- $ agents skill list
-
- ╭─ Skills ────────────────────────────────────────────────────────────╮
- │ Name Tools Includes Sources │
- │ ────────────────────── ───── ──────── ────────────────────── │
- │ local/file-ops 9 0 builtin │
- │ local/git-ops 4 0 builtin │
- │ local/github 4 0 mcp │
- │ local/devops-toolkit 23 3 builtin, mcp, custom │
- │ local/full-stack-dev 25 4 builtin, mcp, custom │
- ╰─────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ─────────╮
- │ Total: 5 │
- │ Local: 5 │
- │ Server: 0 │
- │ Total Tools: 28 │
- ╰───────────────────╯
-
- ✓ OK 5 skills listed
- agents skill show <NAME>
- $ agents skill show local/devops-toolkit
-
- ╭─ Skill Details ──────────────────────────────╮
- │ Name: local/devops-toolkit │
- │ Description: Full-stack development tools │
- │ Config: ./skills/devops-toolkit.yaml │
- │ Created: 2026-02-08 13:10 │
- │ Updated: 2026-02-08 14:22 │
- ╰──────────────────────────────────────────────╯
-
- ╭─ Includes (3) ────────────────────────────╮
- │ local/file-ops → 9 tools (builtin) │
- │ local/git-ops → 4 tools (builtin) │
- │ local/github → 4 tools (mcp) │
- ╰───────────────────────────────────────────╯
-
- ╭─ Direct Tools (6) ────────────────────────────────────────╮
- │ Name Source Writes Checkpoint │
- │ ──────────────── ─────────── ────── ────────── │
- │ create_issue mcp:linear yes no │
- │ list_issues mcp:linear no — │
- │ deploy-to-staging agent_skill yes composite │
- │ code-review agent_skill no — │
- │ run_migrations custom yes transaction │
- │ shell_execute builtin yes snapshot │
- ╰───────────────────────────────────────────────────────────╯
-
- ╭─ MCP Servers (1) ───────────────────╮
- │ linear: stdio, 2 tools, connected │
- ╰─────────────────────────────────────╯
-
- ╭─ Capability Summary ──────────╮
- │ Total Tools: 23 │
- │ Read-Only: 10 │
- │ Writes: 13 │
- │ Checkpointable: 10 │
- │ Has Side Effects: 3 │
- │ Requires Approval: 1 │
- ╰───────────────────────────────╯
-
- ╭─ Referenced By ───────────────────╮
- │ Actors: local/code-assistant │
- │ Skills: local/full-stack-dev │
- ╰───────────────────────────────────╯
-
- ✓ OK Skill loaded
- agents skill tools <NAME>
- $ agents skill tools local/devops-toolkit
-
- ╭─ Tools for local/devops-toolkit ─────────────────────────────────────────────────────────╮
- │ Tool Source From Skill Read-Only Writes Checkpoint │
- │ ───────────────── ─────────── ────────────── ───────── ────── ────────── │
- │ read_file builtin local/file-ops ✓ — — │
- │ write_file builtin local/file-ops — ✓ file │
- │ edit_file builtin local/file-ops — ✓ file │
- │ delete_file builtin local/file-ops — ✓ file │
- │ move_file builtin local/file-ops — ✓ file │
- │ copy_file builtin local/file-ops — ✓ file │
- │ create_directory builtin local/file-ops — ✓ file │
- │ list_directory builtin local/file-ops ✓ — — │
- │ delete_directory builtin local/file-ops — ✓ file │
- │ git_status builtin local/git-ops ✓ — — │
- │ git_diff builtin local/git-ops ✓ — — │
- │ git_log builtin local/git-ops ✓ — — │
- │ git_blame builtin local/git-ops ✓ — — │
- │ create_issue mcp:github local/github — ✓ no │
- │ create_pr mcp:github local/github — ✓ no │
- │ list_repos mcp:github local/github ✓ — — │
- │ get_file_contents mcp:github local/github ✓ — — │
- │ create_issue mcp:linear (direct) — ✓ no │
- │ list_issues mcp:linear (direct) ✓ — — │
- │ run_migrations custom (direct) — ✓ transaction │
- │ deploy-to-staging agent_skill (direct) — ✓ composite │
- │ code-review agent_skill (direct) ✓ — — │
- │ shell_execute builtin (direct) — ✓ snapshot │
- ╰──────────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ──────────────────╮
- │ Total: 23 │
- │ From Includes: 17 │
- │ Direct: 6 │
- │ Read-Only: 10 │
- │ Writes: 13 │
- │ Checkpointable: 10 │
- ╰────────────────────────────╯
-
- ✓ OK 23 tools listed
- agents tool add --config|-c <FILE> [--update]
- $ agents tool add --config ./tools/run-migrations.yaml
-
- ╭─ Tool Registered ────────────────────────────╮
- │ Name: local/run-migrations │
- │ Description: Run database migrations │
- │ Source: custom │
- │ Config: ./tools/run-migrations.yaml │
- │ Created: 2026-02-09 10:15 │
- ╰──────────────────────────────────────────────╯
-
- ╭─ Capability ─────────────────────╮
- │ Writes: true │
- │ Write Scope: database:migrations │
- │ Checkpointable: true │
- │ Checkpoint Scope: transaction │
- │ Side Effects: schema_mutation │
- ╰──────────────────────────────────╯
-
- ✓ OK Tool registered
-
- $ agents tool add --config ./tools/run-migrations-v2.yaml
-
- ✗ Error: Tool 'local/run-migrations' is already registered.
-
- To overwrite the existing configuration, re-run with --update:
-
- agents tool add --config ./tools/run-migrations-v2.yaml --update
-
- $ agents tool add --config ./tools/db-migrate.yaml --update
-
- ╭─ Tool Updated ─────────────────────────────╮
- │ Name: local/db-migrate │
- │ Source: custom (Python) │
- │ Status: updated (was version 1 → now 2) │
- ╰────────────────────────────────────────────╯
-
- ╭─ Changes ─────────────────────────────────────╮
- │ Input Schema: modified (added batch_size) │
- │ Capabilities: unchanged (writes, checkpoint) │
- │ Description: updated │
- ╰───────────────────────────────────────────────╯
-
- ╭─ References ──────────────────╮
- │ Skills: 1 (local/db-tools) │
- │ Actors: 0 │
- │ Referencing skills will use │
- │ the updated definition. │
- ╰───────────────────────────────╯
-
- ✓ OK Tool updated
- agents tool remove [--yes|-y] <NAME>
- $ agents tool remove local/run-migrations
-
- Remove tool local/run-migrations? [y/N]: y
-
- ╭─ Tool Removed ────────────────────╮
- │ Name: local/run-migrations │
- │ Source: custom │
- ╰───────────────────────────────────╯
-
- ╭─ References ──────────────────────────────────────╮
- │ Warning: This tool is referenced by: │
- │ - Skill: local/devops-toolkit │
- │ - Actor graph node: code_executor.run_db_migrate │
- │ These references will break until resolved. │
- ╰───────────────────────────────────────────────────╯
-
- ✓ OK Tool removed
-
- $ agents tool remove local/check-bundle-size
-
- Remove validation local/check-bundle-size? [y/N]: y
-
- ╭─ Validation Removed ─────────────────────────────╮
- │ Name: local/check-bundle-size │
- │ Description: Check bundle size (advisory) │
- ╰──────────────────────────────────────────────────╯
-
- ╭─ Detached From ────────────────────────────────────────────╮
- │ Warning: This validation had 2 attachments: │
- │ - local/api-repo (scope: project local/api-service) │
- │ - local/api-repo (direct) │
- │ These attachments have been removed. │
- ╰────────────────────────────────────────────────────────────╯
-
- ✓ OK Validation removed─
- agents tool list [(--namespace|-n) <NS>] [--source <SOURCE>] [--type (tool|validation)] [<REGEX>]
- $ agents tool list --namespace local
-
- ╭─ Tools ─────────────────────────────────────────────────────────────────╮
- │ Name Type Source Read-Only Writes │
- │ ───────────────────────── ────────── ─────── ───────── ────── │
- │ local/run-migrations tool custom — ✓ │
- │ local/validate-api-compat tool custom — ✓ │
- │ local/create-subplan tool custom — ✓ │
- │ local/deploy-staging tool agent — ✓ │
- │ local/run-tests validation custom ✓ — │
- │ local/lint-check validation custom ✓ — │
- │ local/check-bundle-size validation custom ✓ — │
- │ local/type-check validation custom ✓ — │
- ╰─────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ────────────────╮
- │ Total: 8 │
- │ Tools: 4 │
- │ Validations: 4 │
- │ Read-Only: 4 │
- │ Writes: 4 │
- ╰──────────────────────────╯
-
- ✓ OK 8 tools listed
-
- $ agents tool list --type validation --namespace local
-
- ╭─ Validations ─────────────────────────────────────────────────────────────────╮
- │ Name Source Mode Attachments │
- │ ───────────────────────── ─────── ──────────── ──────────────────────── │
- │ local/run-tests custom required 2 (1 direct, 1 project) │
- │ local/lint-check custom required 1 (1 direct) │
- │ local/check-bundle-size custom informational 1 (1 project) │
- │ local/type-check custom required 2 (2 project) │
- ╰───────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ──────────────╮
- │ Total: 4 │
- │ Required: 3 │
- │ Informational: 1 │
- ╰────────────────────────╯
-
- ✓ OK 4 validations listed
- agents tool show <NAME>
- $ agents tool show local/run-migrations
-
- ╭─ Tool Details ───────────────────────────────╮
- │ Name: local/run-migrations │
- │ Description: Run database migrations │
- │ Source: custom │
- │ Config: ./tools/run-migrations.yaml │
- │ Registered: 2026-02-09 10:15 │
- ╰──────────────────────────────────────────────╯
-
- ╭─ Input Schema ─────────────────────────────────╮
- │ direction: string (required) enum: [up, down] │
- │ count: integer (default: 1) │
- ╰────────────────────────────────────────────────╯
-
- ╭─ Capability ──────────────────────╮
- │ Read-Only: false │
- │ Writes: true │
- │ Write Scope: database:migrations │
- │ Checkpointable: true │
- │ Checkpoint Scope: transaction │
- │ Side Effects: schema_mutation │
- │ Idempotent: false │
- ╰───────────────────────────────────╯
-
- ╭─ Referenced By ───────────────────────╮
- │ Skills: │
- │ - local/devops-toolkit │
- │ Actor Graph Nodes: │
- │ - code_executor.run_db_migrate │
- ╰───────────────────────────────────────╯
-
- ✓ OK Tool details loaded
-
- $ agents tool show local/run-tests
-
- ╭─ Validation Details ──────────────────────────────╮
- │ Name: local/run-tests │
- │ Type: validation │
- │ Description: Run unit tests with coverage │
- │ Source: custom │
- │ Mode: required │
- │ Config: ./validations/run-tests.yaml │
- │ Registered: 2026-02-09 10:15 │
- ╰───────────────────────────────────────────────────╯
-
- ╭─ Input Schema ─────────────────────────────────────╮
- │ coverage_threshold: integer (default: 80) │
- ╰────────────────────────────────────────────────────╯
-
- ╭─ Output Schema (Validation Return Format) ─────────╮
- │ passed: boolean (required) │
- │ message: string (optional) │
- │ data: object (optional, arbitrary structure) │
- ╰────────────────────────────────────────────────────╯
-
- ╭─ Capability ──────────────────────╮
- │ Read-Only: true (enforced) │
- │ Checkpointable: false (enforced) │
- │ Timeout: 600s │
- ╰───────────────────────────────────╯
-
- ╭─ Attached To ─────────────────────────────────────────────────────╮
- │ local/api-repo (direct, always active) │
- │ (attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1) │
- │ local/api-repo (scope: project local/api-service) │
- │ (attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0) │
- ╰───────────────────────────────────────────────────────────────────╯
-
- ✓ OK Validation details loaded
- agents lsp add [--update|-u] (--config|-c) <FILE>
- $ agents lsp add --config lsp/pyright.yaml
-
- ╭─ LSP Server Registered ──────────────────────────────────╮
- │ Name: local/pyright │
- │ Languages: python │
- │ Command: pyright-langserver --stdio │
- │ Capabilities: diagnostics, hover, completions, │
- │ references, definitions, symbols, │
- │ rename, code_actions │
- ╰──────────────────────────────────────────────────────────╯
-
- ✓ OK LSP server registered
-
- $ agents lsp add --config lsp/pyright.yaml
-
- ✗ ERROR LSP server 'local/pyright' already exists
-
- Hint: Use --update to overwrite: agents lsp add --update --config lsp/pyright.yaml
- agents lsp remove [--yes|-y] <NAME>
- $ agents lsp remove local/pyright
-
- Remove LSP server local/pyright? [y/N]: y
-
- ╭─ LSP Server Removed ─────────────────────╮
- │ Name: local/pyright │
- │ Languages: python │
- ╰──────────────────────────────────────────╯
-
- ╭─ References ──────────────────────────────────────────────────╮
- │ Warning: This LSP server is referenced by: │
- │ - Actor: local/code-reviewer (lsp: [local/pyright]) │
- │ - Actor: local/refactor-agent (lsp: [local/pyright]) │
- │ These actor LSP bindings will fail until resolved. │
- ╰───────────────────────────────────────────────────────────────╯
-
- ✓ OK LSP server removed
- agents lsp list [(--namespace|-n) <NS>] [--language <LANG>] [<REGEX>]
- $ agents lsp list
-
- ╭─ LSP Registry (3 servers) ───────────────────────────────────────────────────────────╮
- │ Name │ Languages │ Command │ Bound │
- │─────────────────────────│──────────────────────│─────────────────────────────│───────│
- │ local/pyright │ python │ pyright-langserver --stdio │ 3 │
- │ local/ts-server │ typescript, jsx, tsx │ typescript-language-server │ 2 │
- │ local/gopls │ go │ gopls serve │ 1 │
- ╰──────────────────────────────────────────────────────────────────────────────────────╯
-
- $ agents lsp list --language python
-
- ╭─ LSP Registry (1 server, filtered: language=python) ─────────────────────────────╮
- │ Name │ Languages │ Command │ Bound │
- │─────────────────────────│────────────│───────────────────────────────────│───────│
- │ local/pyright │ python │ pyright-langserver --stdio │ 3 │
- ╰──────────────────────────────────────────────────────────────────────────────────╯
- agents lsp show <NAME>
- $ agents lsp show local/pyright
-
- ╭─ LSP Server Details ──────────────────────────────────────────╮
- │ Name: local/pyright │
- │ Languages: python │
- │ Command: pyright-langserver --stdio │
- │ Root path: {{ project.root }} │
- │ Init options: │
- │ python.analysis.typeCheckingMode: standard │
- │ python.analysis.autoSearchPaths: true │
- ╰───────────────────────────────────────────────────────────────╯
-
- ╭─ Capabilities ────────────────────────────────────────────────╮
- │ diagnostics, hover, completions, references, definitions, │
- │ symbols, rename, code_actions │
- ╰───────────────────────────────────────────────────────────────╯
-
- ╭─ Bound Actors ────────────────────────────────────────────────╮
- │ local/code-reviewer (explicit binding) │
- │ local/refactor-agent (language-based: python) │
- │ local/polyglot-planner (auto-discovery) │
- ╰───────────────────────────────────────────────────────────────╯
- agents lsp serve [--log-level <LEVEL>]
- $ agents lsp serve
-
- CleverAgents LSP Server (stub) starting — PID 7412
- Log level: info
- Transport: stdin/stdout (JSON-RPC, Content-Length framing)
- Supported methods: initialize, shutdown, exit
- All other methods → MethodNotFound (-32601)
- agents validation add --config|-c <FILE> [--required | --informational] [--update]
- $ agents validation add --config ./validations/run-tests.yaml
-
- ╭─ Validation Registered ────────────────────────────────╮
- │ Name: local/run-tests │
- │ Description: Run unit tests with coverage │
- │ Source: custom │
- │ Mode: required │
- │ Config: ./validations/run-tests.yaml │
- │ Created: 2026-02-09 10:15 │
- ╰────────────────────────────────────────────────────────╯
-
- ╭─ Capability ────────────────────────╮
- │ Read-Only: true (enforced) │
- │ Checkpointable: false (enforced) │
- │ Timeout: 600s │
- ╰─────────────────────────────────────╯
-
- ✓ OK Validation registered
-
- $ agents validation add --config ./validations/lint-check.yaml
-
- ╭─ Validation Registered ──────────────╮
- │ Name: local/lint-check │
- │ Description: Lint check │
- │ Source: custom │
- │ Mode: required │
- │ Timeout: 300s │
- ╰──────────────────────────────────────╯
-
- ✓ OK Validation registered
-
- $ agents validation add --config ./validations/check-bundle-size.yaml
-
- ╭─ Validation Registered ───────────────────────────╮
- │ Name: local/check-bundle-size │
- │ Description: Check bundle size (advisory) │
- │ Source: custom │
- │ Mode: informational │
- │ Timeout: 300s │
- ╰───────────────────────────────────────────────────╯
-
- ✓ OK Validation registered
- agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
- <RESOURCE> <VALIDATION> [<ARGS>...]
- $ agents validation attach --project local/api-service local/api-repo local/run-tests
-
- ╭─ Validation Attached ──────────────────────────────────────╮
- │ Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0 │
- │ Validation: local/run-tests │
- │ Mode: required │
- │ Resource: local/api-repo │
- │ Scope: project local/api-service │
- ╰────────────────────────────────────────────────────────────╯
-
- ✓ OK Validation attached
-
- $ agents validation attach local/api-repo local/lint-check
-
- ╭─ Validation Attached ──────────────────────────────────────╮
- │ Attachment ID: 01HXM5B2C3D4E5F6G7H8J9K0L1 │
- │ Validation: local/lint-check │
- │ Mode: required │
- │ Resource: local/api-repo │
- │ Scope: direct (always active) │
- │ This validation will run for ALL plans/projects │
- │ that access this resource. │
- ╰────────────────────────────────────────────────────────────╯
-
- ✓ OK Validation attached
-
- $ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90
-
- ╭─ Validation Attached ──────────────────────────────────────╮
- │ Attachment ID: 01HXM5C3D4E5F6G7H8J9K0L1M2 │
- │ Validation: local/run-tests │
- │ Mode: required │
- │ Resource: local/api-repo │
- │ Scope: project local/api-service │
- │ Args: coverage_threshold=90 │
- ╰────────────────────────────────────────────────────────────╯
-
- ✓ OK Validation attached
- agents validation detach [--yes|-y] <ATTACHMENT_ID>
- $ agents validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0
-
- Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y
-
- ╭─ Validation Detached ───────────────────────────────────────╮
- │ Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0 │
- │ Validation: local/run-tests │
- │ Resource: local/api-repo │
- │ Scope: project local/api-service │
- ╰─────────────────────────────────────────────────────────────╯
-
- ✓ OK Validation detached
- agents resource type add --config|-c <FILE> [--update]
- $ agents resource type add --config ./resource-types/svn.yaml
-
- ╭─ Resource Type ────────────────────╮
- │ Name: local/svn │
- │ Physical/Virtual: physical │
- │ User Addable: yes │
- │ Registered: 2026-02-09 10:15 │
- ╰────────────────────────────────────╯
-
- ╭─ CLI Arguments ────────────────────────╮
- │ Argument Required Description │
- │ ──────────── ──────── ───────────── │
- │ --url yes Repository URL │
- │ --checkout no Local checkout │
- ╰────────────────────────────────────────╯
-
- ╭─ Child Types ──────────────────────────╮
- │ Auto-discover: svn-revision, svn-file │
- │ Manual link: fs-mount │
- ╰────────────────────────────────────────╯
-
- ╭─ Sandbox ──────────────────────╮
- │ Strategy: copy_on_write │
- │ Handler: SVNHandler (custom) │
- ╰────────────────────────────────╯
-
- ✓ OK Resource type registered
- ℹ New subcommand available: agents resource add local/svn
- agents resource type remove [--yes|-y] <NAME>
- $ agents resource type remove local/svn
-
- Remove resource type local/svn? [y/N]: y
-
- ╭─ Resource Type Removed ───────╮
- │ Name: local/svn │
- │ Resources Using: 0 │
- │ Subcommand Removed: yes │
- ╰───────────────────────────────╯
-
- ✓ OK Resource type removed
- agents resource type list [<REGEX>]
- $ agents resource type list
-
- ╭─ Resource Types ──────────────────────────────────────────────────────────────────────────────────╮
- │ Name Source Phys/Virt Addable Auto-children │
- │ ─────────────────── ──────── ───────── ─────── ────────────────────────────────────── │
- │ git-checkout built-in physical yes git, fs-directory │
- │ git built-in physical yes git-remote, git-branch, git-tag, │
- │ git-commit, git-stash, git-submodule │
- │ git-remote built-in physical no (none) │
- │ git-branch built-in physical no git-commit │
- │ git-tag built-in physical no (none) │
- │ git-commit built-in physical no git-tree │
- │ git-tree built-in physical no git-tree-entry │
- │ git-tree-entry built-in physical no (none) │
- │ git-stash built-in physical no (none) │
- │ git-submodule built-in physical no (none) │
- │ fs-mount built-in physical yes fs-directory │
- │ fs-directory built-in physical yes fs-file, fs-directory, │
- │ fs-symlink, fs-hardlink │
- │ fs-file built-in physical no (none) │
- │ fs-symlink built-in physical no (none) │
- │ fs-hardlink built-in physical no (none) │
- │ file built-in virtual no (none) │
- │ directory built-in virtual no (none) │
- │ symlink built-in virtual no (none) │
- │ commit built-in virtual no (none) │
- │ branch built-in virtual no (none) │
- │ tag built-in virtual no (none) │
- │ remote built-in virtual no (none) │
- │ submodule built-in virtual no (none) │
- │ tree built-in virtual no (none) │
- │ local/svn custom physical yes svn-revision, svn-file │
- ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ─────────────────╮
- │ Built-in: 24 │
- │ Custom: 1 │
- │ User Addable: 4 │
- ╰───────────────────────────╯
-
- ✓ OK 25 resource types listed
- agents resource type show <NAME>
- $ agents resource type show git-checkout
-
- ╭─ Resource Type ──────────────────────────────────────────────────────╮
- │ Name: git-checkout │
- │ Source: built-in │
- │ Description: A locally checked-out git repository with worktree │
- │ Physical/Virtual: physical │
- │ User Addable: yes │
- ╰──────────────────────────────────────────────────────────────────────╯
-
- ╭─ CLI Arguments (agents resource add git-checkout) ─────────────────╮
- │ Argument Required Type Description │
- │ ────────── ──────── ────── ────────────────────────────── │
- │ --path yes path Local checkout directory │
- │ --branch no string Default branch (default: main) │
- ╰────────────────────────────────────────────────────────────────────╯
-
- ╭─ Parent Types ───────────────╮
- │ Allowed: (any, top-level OK) │
- ╰──────────────────────────────╯
-
- ╭─ Child Types ────────────────────────────────────────────────────╮
- │ Type Auto Manual Link Description │
- │ ───────────── ──── ─────────── ────────────────────────── │
- │ git yes no Repo object DB and history │
- │ fs-directory yes no Worktree root directory │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Sandbox ──────────────────────╮
- │ Strategy: git_worktree │
- │ Checkpointable: yes │
- │ Handler: GitCheckoutHandler │
- ╰────────────────────────────────╯
-
- ✓ OK Resource type details loaded
- agents resource add [(--description|-d) <DESC>] [--update] <TYPE> <NAME> [type-specific-flags...]
- $ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
-
- ╭─ Resource ──────────────────────────────────────╮
- │ Name: local/api-repo │
- │ ID: 01HXR1A1B2C3D4E5F6G7H8J9K0 │
- │ Type: git-checkout │
- │ Physical/Virtual: physical │
- │ Path: /home/user/projects/api-service │
- │ Branch: main │
- │ Created: 2026-02-09 10:20 │
- ╰─────────────────────────────────────────────────╯
-
- ╭─ Auto-discovered Children ─────────────────────────────────────────╮
- │ ID Type Status │
- │ ─────────────── ────────────── ───────────────── │
- │ 01HXR1A1B2C3… git created │
- │ 01HXR1A1B2C4… git-remote created │
- │ 01HXR1A1B2C5… git-branch created │
- │ 01HXR1A1B2C6… git-branch created │
- │ 01HXR1A1B2C7… fs-directory created │
- │ + 47 git-commit resources │
- │ + 312 git-tree-entry resources │
- │ + 3 fs-directory + 28 fs-file │
- ╰────────────────────────────────────────────────────────────────────╯
-
- ╭─ Capabilities ─────────────────╮
- │ Readable: yes │
- │ Writable: yes │
- │ Sandboxable: yes │
- │ Checkpointable: yes │
- │ Sandbox Strategy: git_worktree │
- ╰────────────────────────────────╯
-
- ✓ OK Resource registered (395 child resources discovered)
-
- $ agents resource add fs-mount local/docs --mount-path /docs/api-reference
-
- ╭─ Resource ──────────────────────────────────────╮
- │ Name: local/docs │
- │ ID: 01HXR2B3C4D5E6F7G8H9J0K1L2 │
- │ Type: fs-mount │
- │ Physical/Virtual: physical │
- │ Mount Path: /docs/api-reference │
- │ Created: 2026-02-09 10:22 │
- ╰─────────────────────────────────────────────────╯
-
- ╭─ Auto-discovered Children ────────────────────╮
- │ + 1 fs-directory (root) │
- │ + 3 fs-directory resources │
- │ + 28 fs-file resources │
- ╰───────────────────────────────────────────────╯
-
- ╭─ Capabilities ──────────────────────╮
- │ Readable: yes │
- │ Writable: yes │
- │ Sandboxable: yes │
- │ Checkpointable: yes │
- │ Sandbox Strategy: copy_on_write │
- ╰─────────────────────────────────────╯
-
- ✓ OK Resource registered (31 child resources discovered)
-
- $ agents resource add container-instance local/api-dev --mount local/api-repo:/workspace --mount /home/user/.config/nvim:/home/dev/.config/nvim
-
- ╭─ Resource ──────────────────────────────────────╮
- │ Name: local/api-dev │
- │ ID: 01HXR3C4D5E6F7G8H9J0K1L2M3 │
- │ Type: container-instance │
- │ Physical/Virtual: physical │
- │ State: created (not started) │
- │ Created: 2026-02-09 10:25 │
- ╰─────────────────────────────────────────────────╯
-
- ╭─ Mounts ──────────────────────────────────────────────────────────╮
- │ Source Container Path Kind │
- │ ──────────────────────────────── ─────────────── ─────────── │
- │ local/api-repo /workspace resource-ref │
- │ /home/user/.config/nvim /home/dev/… host-path │
- ╰───────────────────────────────────────────────────────────────────╯
-
- ✓ OK Container resource registered (container will start on first access)
-
- $ agents resource add container-instance cloud/ci-runner --clone-into https://github.com/acme/api.git:/workspace
-
- ╭─ Resource ──────────────────────────────────────╮
- │ Name: cloud/ci-runner │
- │ ID: 01HXR4D5E6F7G8H9J0K1L2M3N4 │
- │ Type: container-instance │
- │ Physical/Virtual: physical │
- │ State: created (not started) │
- │ Clone: https://github.com/acme/api.git │
- │ Clone Target: /workspace │
- │ Created: 2026-02-09 10:27 │
- ╰─────────────────────────────────────────────────╯
-
- ✓ OK Container resource registered (repo will be cloned on first start)
-
- $ agents resource add git-checkout local/webapp --path /home/user/projects/webapp
-
- ╭─ Resource ──────────────────────────────────────────╮
- │ Name: local/webapp │
- │ ID: 01HXR5E6F7G8H9J0K1L2M3N4O5 │
- │ Type: git-checkout │
- │ Physical/Virtual: physical │
- │ Path: /home/user/projects/webapp │
- │ Branch: main │
- │ Created: 2026-02-09 10:30 │
- ╰─────────────────────────────────────────────────────╯
-
- ╭─ Auto-discovered Children ─────────────────────────────────────────╮
- │ ID Type Status │
- │ ─────────────── ────────────────────── ─────────────────── │
- │ 01HXR5E6F7G9… git created │
- │ 01HXR5E6F7GA… devcontainer-instance detected (not built) │
- │ 01HXR5E6F7GB… fs-directory created │
- │ + 52 git-commit resources │
- │ + 189 git-tree-entry resources │
- ╰────────────────────────────────────────────────────────────────────╯
-
- ⚠ Devcontainer detected at .devcontainer/devcontainer.json
- Container will be built lazily on first access.
- Use agents resource show 01HXR5E6F7GA… to inspect.
-
- ✓ OK Resource registered (245 child resources discovered)
- agents resource remove [--yes|-y] <NAME>
- $ agents resource remove local/api-repo
-
- Remove resource local/api-repo and 395 child resources? [y/N]: y
-
- ╭─ Resource Removed ──────────────────────────────────╮
- │ Name: local/api-repo │
- │ Type: git-checkout │
- │ Children Removed: 395 │
- │ Projects Unlinked: 0 │
- ╰─────────────────────────────────────────────────────╯
-
- ✓ OK Resource removed
- agents resource list [--all] [(--type|-t) <TYPE>]
- $ agents resource list
-
- ╭─ Resources ──────────────────────────────────────────────────────────────────────────────────────────────╮
- │ Name ID Type Phys/Virt Children Projects │
- │ ───────────────── ──────────────────────────── ─────────── ───────── ──────── ──────────────── │
- │ local/api-repo 01HXR1A1B2C3D4E5F6G7H8J9K0 git-checkout physical 395 local/api-service │
- │ local/docs 01HXR2B2C3D4E5F6G7H8J9K0L1 fs-mount physical 32 local/api-service │
- │ local/staging-db 01HXR3C3D4E5F6G7H8J9K0L1M2 database physical 12 local/api-service, │
- │ local/staging │
- ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ───────────╮
- │ Total: 3 │
- │ Physical: 3 │
- │ Virtual: 0 │
- │ Total Children: 405 │
- ╰─────────────────────╯
-
- ✓ OK 3 resources listed
- agents resource show <RESOURCE>
- $ agents resource show local/api-repo
-
- ╭─ Resource ─────────────────────────────────────────╮
- │ Name: local/api-repo │
- │ ID: 01HXR1A1B2C3D4E5F6G7H8J9K0 │
- │ Type: git-checkout │
- │ Physical/Virtual: physical │
- │ Path: /home/user/projects/api-service │
- │ Branch: main │
- │ Created: 2026-02-09 10:20 │
- ╰────────────────────────────────────────────────────╯
-
- ╭─ Capabilities ────────────────────╮
- │ Readable: yes │
- │ Writable: yes │
- │ Sandboxable: yes │
- │ Checkpointable: yes │
- │ Sandbox Strategy: git_worktree │
- ╰───────────────────────────────────╯
-
- ╭─ Parents ────╮
- │ (top-level) │
- ╰──────────────╯
-
- ╭─ Direct Children ──────────────────────────────────────────────────────╮
- │ ID Type Auto Children │
- │ ──────────────────────────── ──────────── ──── ──────── │
- │ 01HXR4D4E5F6G7H8J9K0L1M2N3 git yes 363 │
- │ 01HXR5E5F6G7H8J9K0L1M2N3P4 fs-directory yes 32 │
- ╰────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Linked Projects ─────────────╮
- │ - local/api-service (r/w) │
- ╰───────────────────────────────╯
-
- ╭─ Tool Bindings ────────────────────────────────╮
- │ Tool Slot Access │
- │ ──────────────────────── ───── ─────────── │
- │ (builtin) git_status repo read_only │
- │ (builtin) git_diff repo read_only │
- │ (builtin) git_log repo read_only │
- │ local/run-migrations db (not bound) │
- ╰────────────────────────────────────────────────╯
-
- ✓ OK Resource details loaded
- agents resource inspect [--tree] [--file <PATH>] <RESOURCE>
- $ agents resource inspect local/api-repo --tree
-
- ╭─ Resource Tree: local/api-repo ──────────────────────────────────────╮
- │ │
- │ /home/user/projects/api-service │
- │ ├── src/ │
- │ │ ├── api/ │
- │ │ │ ├── __init__.py │
- │ │ │ ├── auth/ │
- │ │ │ │ ├── auth_middleware.py │
- │ │ │ │ ├── token_service.py │
- │ │ │ │ └── rbac.py │
- │ │ │ ├── routes/ │
- │ │ │ └── models/ │
- │ │ └── utils/ │
- │ ├── tests/ │
- │ ├── README.md │
- │ └── pyproject.toml │
- │ │
- ╰──────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ──────────────╮
- │ Directories: 8 │
- │ Files: 41 │
- │ Total Size: 284 KB │
- ╰────────────────────────╯
-
- ✓ OK Resource tree displayed
-
- $ agents resource inspect local/api-repo --file src/api/auth/auth_middleware.py
-
- ╭─ File: src/api/auth/auth_middleware.py ──────────────────╮
- │ Resource: local/api-repo │
- │ Size: 2.4 KB │
- │ Language: Python │
- │ Last Modified: 2026-02-10 14:32 │
- ╰──────────────────────────────────────────────────────────╯
-
- 1 │ from fastapi import Request, HTTPException
- 2 │ from .token_service import validate_token
- 3 │
- 4 │ async def auth_middleware(request: Request):
- 5 │ token = request.headers.get("Authorization")
- 6 │ if not token:
- 7 │ raise HTTPException(status_code=401)
- 8 │ user = await validate_token(token)
- 9 │ request.state.user = user
- 10 │ return user
- │ ... (24 more lines)
-
- ✓ OK File displayed
- agents resource tree [(--depth|-d) <N>] [(--type|-t) <TYPE>] <RESOURCE>
- $ agents resource tree local/api-repo --depth 2
-
- ╭─ Resource Tree: local/api-repo ─────────────────────────────────────╮
- │ │
- │ git-checkout 01HXR1A1..J9K0 (physical) │
- │ ├── git 01HXR4D4..M2N3 (physical) │
- │ │ ├── git-remote 01HXR6F6..P4Q5 │
- │ │ ├── git-branch 01HXR7G7..Q5R6 │
- │ │ │ ├── git-commit 01HXR8H8..R6S7 │
- │ │ │ └── ... 22 more git-commit resources │
- │ │ └── git-branch 01HXR9J9..S7T8 │
- │ │ └── ... 26 git-commit resources │
- │ └── fs-directory 01HXR5E5..N3P4 (physical) │
- │ ├── fs-directory 01HXRAK1..T8U9 │
- │ ├── fs-directory 01HXRBL2..U9V0 │
- │ └── ... 28 more fs-file resources │
- │ │
- ╰─────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ──────────────╮
- │ Total shown: 14 │
- │ Total in subtree: 395 │
- │ Max depth: 2 │
- ╰────────────────────────╯
-
- ✓ OK Resource tree displayed
- agents resource link-child <PARENT> <CHILD>
- $ agents resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
-
- ╭─ Child Linked ──────────────────────────────────────╮
- │ Parent: local/api-repo │
- │ Child: 01HXR2B2C3D4E5F6G7H8J9K0L1 │
- │ Child Type: fs-mount │
- │ Status: linked │
- ╰─────────────────────────────────────────────────────╯
-
- ✓ OK Child resource linked
- agents resource unlink-child [--yes|-y] <PARENT> <CHILD>
- $ agents resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
-
- Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y
-
- ╭─ Child Unlinked ────────────────────────────────────╮
- │ Parent: local/api-repo │
- │ Child: 01HXR2B2C3D4E5F6G7H8J9K0L1 │
- │ Status: unlinked │
- ╰─────────────────────────────────────────────────────╯
-
- ✓ OK Child resource unlinked
- agents resource stop <NAME> [--yes | -y]
- $ agents resource stop local/my-dc
-
- Stopping container local/my-dc (state: running)...
- Stopped: local/my-dc
- agents resource rebuild <NAME> [--yes | -y]
- $ agents resource rebuild local/my-dc
-
- Rebuilding local/my-dc...
- Rebuilt: local/my-dc
- agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
- [--action <ACTION>] [<REGEX>]
- $ agents --format table plan list --phase execute
-
- ╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
- │ ID Phase State Action Project Elapsed │
- │ ──────── ─────── ────────── ─────────────────── ───────────────── ───────── │
- │ 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12 │
- ╰──────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Filters ──────╮
- │ Phase: execute │
- │ State: (any) │
- │ Project: (any) │
- │ Action: (any) │
- ╰────────────────╯
-
- ╭─ Summary ─────────╮
- │ Total: 1 │
- │ Processing: 1 │
- │ Completed: 0 │
- │ Errored: 0 │
- ╰───────────────────╯
-
- ✓ OK 1 plan listed
-
- $ agents plan list
-
- ╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────╮
- │ ID Phase State Action Project Elapsed │
- │ ──────── ────────── ────────── ─────────────────── ───────────────── ───────── │
- │ 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12 │
- │ 01HXM6R3 apply applied local/add-auth local/api-service 00:07:14 │
- │ 01HXM5K2 execute errored local/migrate-db local/api-service 00:04:33 │
- │ 01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45 │
- │ 01HXM3H8 cancelled cancelled local/add-logging local/api-service 00:02:10 │
- ╰──────────────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ─────────────╮
- │ Total: 5 │
- │ Processing: 2 │
- │ Completed: 1 │
- │ Errored: 1 │
- │ Cancelled: 1 │
- ╰───────────────────────╯
-
- ✓ OK 5 plans listed
-
- $ agents plan list --project local/web-app
-
- ╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
- │ ID Phase State Action Project Elapsed │
- │ ──────── ────────── ────────── ─────────────────── ───────────── ───────── │
- │ 01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45 │
- ╰──────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Filters ─────────────────╮
- │ Phase: (any) │
- │ State: (any) │
- │ Project: local/web-app │
- │ Action: (any) │
- ╰───────────────────────────╯
-
- ✓ OK 1 plan listed
- agents plan use [--automation-profile <PROFILE>]
- [--invariant <INVARIANT>]...
- [--strategy-actor <STRATEGY_ACTOR>]
- [--execution-actor <EXEC_ACTOR>]
- [--estimation-actor <EST_ACTOR>]
- [--invariant-actor <INV_ACTOR>]
- [--execution-environment <RESOURCE_NAME>]
- [--execution-env-priority (fallback|override)]
- [--arg/-a name=value]...
- <ACTION> <PROJECT>...
- $ agents plan use local/code-coverage local/api-service \
- --arg target_coverage_percent=85 --automation-profile trusted
-
- ╭─ Plan Created ──────────────────────╮
- │ Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: strategize │
- │ Action: local/code-coverage │
- │ Project: local/api-service │
- │ Automation: trusted │
- │ Attempt: 1 │
- ╰─────────────────────────────────────╯
-
- ╭─ Inputs ──────────────────────╮
- │ - target_coverage_percent=85 │
- │ - automation_profile=trusted │
- ╰───────────────────────────────╯
-
- ╭─ Actors ────────────────────────╮
- │ Strategy: local/strategist │
- │ Execution: local/executor │
- │ Estimation: (none) │
- ╰─────────────────────────────────╯
-
- ╭─ Automation ─────────────────────────╮
- │ Profile: trusted │
- │ Source: CLI flag │
- │ Read-Only: no │
- ╰──────────────────────────────────────╯
-
- ╭─ Context ───────────────────────╮
- │ Resources: 2 (repo, db) │
- │ Indexed Files: 347 │
- │ View: strategize │
- │ Hot Token Budget: 12,000 │
- ╰─────────────────────────────────╯
-
- ╭─ Next Steps ─────────────────────────────────────╮
- │ - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- ╰──────────────────────────────────────────────────╯
-
- ✓ OK Plan created
-
- $ agents plan use local/security-audit local/api-service local/web-app \
- --invariant "Never modify production database schemas" \
- --invariant "All changes must include test coverage" \
- --automation-profile supervised
-
- ╭─ Plan Created ──────────────────────────────────────╮
- │ Plan: 01HXM9D2ZK4Q7C2B3F2R4VYV6J │
- │ Action: local/security-audit │
- │ Phase: strategize (running) │
- │ Automation: supervised │
- ╰─────────────────────────────────────────────────────╯
-
- ╭─ Target Projects ───────────────────╮
- │ 1. local/api-service (3 resources) │
- │ 2. local/web-app (2 resources) │
- ╰─────────────────────────────────────╯
-
- ╭─ Plan Invariants ──────────────────────────────────────────╮
- │ Scope Source Invariant │
- │ ──────── ─────── ────────────────────────────────── │
- │ plan CLI Never modify production DB schemas │
- │ plan CLI All changes must include test coverage │
- │ project config API responses must be backward-compat │
- │ global config Follow Python PEP 8 style guide │
- ╰────────────────────────────────────────────────────────────╯
-
- ✓ OK Plan created — strategize in progress
-
- $ agents plan use local/code-coverage local/api-service \
- --strategy-actor local/senior-planner \
- --execution-actor local/fast-executor \
- --arg target_coverage_percent=95
-
- ╭─ Plan Created ──────────────────────────────────────╮
- │ Plan: 01HXM9E3ZK4Q7C2B3F2R4VYV6J │
- │ Action: local/code-coverage │
- │ Phase: strategize (running) │
- │ Automation: trusted │
- ╰─────────────────────────────────────────────────────╯
-
- ╭─ Actor Overrides ────────────────────╮
- │ Strategy: local/senior-planner │
- │ Execution: local/fast-executor │
- │ (Estimation: action default) │
- ╰──────────────────────────────────────╯
-
- ╭─ Arguments ─────────────────╮
- │ target_coverage_percent: 95 │
- ╰─────────────────────────────╯
-
- ✓ OK Plan created — strategize in progress
- agents plan execute <PLAN_ID>
- $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Execution ──────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: execute │
- │ Sandbox: git_worktree │
- │ Worker: local/executor │
- │ Started: 12:58:10 │
- │ Attempt: 1 │
- ╰──────────────────────────────────╯
-
- ╭─ Sandbox ──────────────────────────────────╮
- │ Strategy: git_worktree │
- │ Path: /repos/api/.worktrees/plan-01HXM8 │
- │ Branch: cleveragents/plan-01HXM8C2 │
- │ Status: active │
- ╰────────────────────────────────────────────╯
-
- ╭─ Strategy Summary ─────────────────────╮
- │ Decisions: 8 │
- │ Invariants: 2 │
- │ Planned Child Plans: 2+ │
- │ Estimated Files: ~12 │
- │ Risk: low │
- ╰────────────────────────────────────────╯
-
- ╭─ Progress ─────────╮
- │ ⏳ Collect context │
- │ • Run tools │
- │ • Build changeset │
- │ • Validate │
- ╰────────────────────╯
-
- ✓ OK Execution started
-
- $ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Execution Resumed ─────────────────╮
- │ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: execute (resumed) │
- │ Sandbox: git_worktree │
- │ Worker: local/executor │
- │ Checkpoint: cp_01HXM8C2 (loaded) │
- │ Resumed From: step 4 of 6 │
- ╰─────────────────────────────────────╯
-
- ╭─ Previous Progress ──────────────────────╮
- │ ✓ Step 1: Collect context (0.8s) │
- │ ✓ Step 2: Analyze codebase (4.2s) │
- │ ✓ Step 3: Generate migrations (6.1s) │
- │ ✗ Step 4: Apply migrations (errored) │
- │ ○ Step 5: Update models (pending) │
- │ ○ Step 6: Run validations (pending) │
- ╰──────────────────────────────────────────╯
-
- ╭─ Guidance Applied ──────────────────────────────────────────────╮
- │ "Use smaller batch sizes for the migration to avoid timeouts" │
- ╰─────────────────────────────────────────────────────────────────╯
-
- ✓ OK Execution resumed from checkpoint cp_01HXM8C2
- agents plan apply [--yes|-y] <PLAN_ID>
- $ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
-
- ╭─ Apply Summary ─────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Artifacts: 6 files updated │
- │ Changes: 42 insertions, 9 deletions │
- │ Project: local/api-service │
- │ Applied At: 2026-02-08 13:04 │
- ╰─────────────────────────────────────╯
-
- ╭─ Validation (from Execute) ────╮
- │ Tests: passed (24/24) │
- │ Lint: passed (0 warnings) │
- │ Type Check: passed (0 errors) │
- │ Duration: 12.4s │
- ╰────────────────────────────────╯
-
- ╭─ Sandbox Cleanup ─────────╮
- │ Worktree: removed │
- │ Branch: merged to main │
- │ Checkpoint: archived │
- ╰───────────────────────────╯
-
- ╭─ Plan Lifecycle ────────────────────────╮
- │ Phase: apply │
- │ State: applied │
- │ Total Duration: 00:06:14 │
- │ Total Cost: $0.0847 │
- │ Decisions Made: 8 │
- │ Child Plans: 2 (completed) │
- ╰─────────────────────────────────────────╯
-
- ╭─ Next Steps ──────╮
- │ - Review git diff │
- │ - Commit changes │
- ╰───────────────────╯
-
- ✓ OK Changes applied
-
- $ agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Apply Summary ─────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Artifacts: 6 files updated │
- │ Changes: 42 insertions, 9 deletions │
- │ Project: local/api-service │
- ╰─────────────────────────────────────╯
-
- ╭─ Validation ───────────────────────────────────────────────╮
- │ ✗ Tests: FAILED (22/24 passed, 2 failed) │
- │ FAIL test_auth.py::test_session_refresh — AssertionError │
- │ FAIL test_auth.py::test_token_expiry — TimeoutError │
- │ ✓ Lint: passed (0 warnings) │
- │ ✓ Type Check: passed (0 errors) │
- │ Duration: 14.8s │
- ╰────────────────────────────────────────────────────────────╯
-
- ╭─ Sandbox Status ─────────────────────────────────────────────╮
- │ Worktree: preserved (changes NOT committed) │
- │ Checkpoint: cp_01HXM8C2 (pre-apply state available) │
- │ The sandbox is preserved for correction or manual review. │
- ╰──────────────────────────────────────────────────────────────╯
-
- ╭─ Recovery Options ──────────────────────────────────────────────────╮
- │ - agents plan prompt — provide guidance to fix test failures │
- │ - agents plan correct — revert and re-execute with guidance │
- │ - agents plan rollback — restore to a previous checkpoint │
- │ - agents plan cancel — abort the plan entirely │
- ╰─────────────────────────────────────────────────────────────────────╯
-
- ✗ ERROR Apply refused — 2 required Execute-phase validations did not pass
- agents plan status <PLAN_ID>
- $ agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Plan Status ────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: execute │
- │ State: processing │
- │ Action: local/code-coverage │
- │ Project: local/api-service │
- │ Automation: review │
- │ Attempt: 1 │
- ╰──────────────────────────────────╯
-
- ╭─ Progress ───────╮
- │ ✓ Strategize │
- │ ⏳ Execute │
- │ • Apply (queued) │
- ╰──────────────────╯
-
- ╭─ Timing ──────────╮
- │ Started: 12:57:01 │
- │ Elapsed: 00:01:12 │
- │ ETA: 00:03:45 │
- ╰───────────────────╯
-
- ╭─ Execution Detail ──────────╮
- │ Sandbox: git_worktree │
- │ Tool Calls: 8 │
- │ Files Modified: 3 │
- │ Child Plans: 1/2 complete │
- │ Checkpoints: 2 created │
- ╰─────────────────────────────╯
-
- ╭─ Cost ───────────────╮
- │ Tokens Used: 12,420 │
- │ Cost So Far: $0.041 │
- │ Estimated: $0.085 │
- ╰──────────────────────╯
-
- ✓ OK Status refreshed
-
- $ agents plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Plan Status ─────────────────────╮
- │ Plan: 01HXM6R3ZK4Q7C2B3F2R4VYV6J │
- │ Phase: apply │
- │ State: applied │
- │ Action: local/add-auth │
- │ Project: local/api-service │
- │ Automation: trusted │
- │ Attempt: 1 │
- ╰───────────────────────────────────╯
-
- ╭─ Progress ───────────╮
- │ ✓ Strategize │
- │ ✓ Execute │
- │ ✓ Apply (committed) │
- ╰──────────────────────╯
-
- ╭─ Timing ─────────────────────────╮
- │ Started: 2026-02-08 12:57:01 │
- │ Finished: 2026-02-08 13:04:15 │
- │ Total Duration: 00:07:14 │
- ╰──────────────────────────────────╯
-
- ╭─ Result ────────────────────────────╮
- │ Decisions Made: 8 │
- │ Child Plans: 2/2 complete │
- │ Artifacts: 6 files updated │
- │ Validations: 3/3 passed │
- │ Total Cost: $0.085 │
- ╰─────────────────────────────────────╯
-
- ✓ OK Plan completed successfully
-
- $ agents plan status 01HXM9F2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Plan Status ────────────────────╮
- │ Plan: 01HXM9F2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: strategize │
- │ State: processing │
- │ Action: local/refactor-auth │
- │ Project: local/api-service │
- │ Automation: supervised │
- ╰──────────────────────────────────╯
-
- ╭─ Progress ───────────────╮
- │ ⏳ Strategize (running) │
- │ ○ Execute (waiting) │
- │ ○ Apply (waiting) │
- ╰──────────────────────────╯
-
- ╭─ Strategy Progress ────────╮
- │ Decisions Made: 4 │
- │ Invariants Enforced: 2 │
- │ Child Plans Planned: 3 │
- │ Elapsed: 00:00:28 │
- ╰────────────────────────────╯
-
- ✓ OK Strategize in progress
-
- $ agents plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Plan Status ────────────────────╮
- │ Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: execute │
- │ State: errored │
- │ Action: local/migrate-db │
- │ Project: local/api-service │
- │ Automation: supervised │
- │ Attempt: 1 │
- ╰──────────────────────────────────╯
-
- ╭─ Progress ───────────╮
- │ ✓ Strategize │
- │ ✗ Execute │
- │ ○ Apply (skipped) │
- ╰──────────────────────╯
-
- ╭─ Error Detail ──────────────────────────────────────────────────╮
- │ Error: Tool invocation failed: connection refused │
- │ Tool: local/db-migrate │
- │ Step: 4 of 6 │
- │ Checkpoint: cp_01HXM8C2 (sandbox state preserved) │
- │ Recoverable: yes — use "agents plan prompt" to provide guidance │
- ╰─────────────────────────────────────────────────────────────────╯
-
- ╭─ Cost ───────────────╮
- │ Tokens Used: 8,340 │
- │ Cost So Far: $0.028 │
- ╰──────────────────────╯
-
- ✗ ERROR Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort
- agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>
- $ agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
-
- ╭─ Plan Cancelled ─────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: execute │
- │ Reason: blocked on credentials │
- │ State: cancelled │
- │ Cancelled At: 13:02:15 │
- ╰──────────────────────────────────╯
-
- ╭─ Sandbox ────────────────╮
- │ Status: preserved │
- │ Files Modified: 3 │
- │ Checkpoints: 2 │
- ╰──────────────────────────╯
-
- ╭─ Child Plans ─────────────╮
- │ Completed: 1 │
- │ Cancelled: 1 │
- │ Artifacts Preserved: yes │
- ╰───────────────────────────╯
-
- ╭─ Recovery ───────────────────────────────────────────╮
- │ - Resolve credentials │
- │ - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- ╰──────────────────────────────────────────────────────╯
-
- ✓ OK Plan cancelled
- agents plan tree [--show-superseded] <PLAN_ID>
- $ agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Decision Tree ──────────────────────────────────────────────────────────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ ├─ [prompt_definition] "Increase test coverage to 85%" │
- │ ├─ [invariant_enforced] "Prioritize financial transaction and user mgmt code" │
- │ ├─ [invariant_enforced] "All API calls over TCP must be mocked" │
- │ ├─ [strategy_choice] "Prioritize auth and payments" (confidence: 0.82) │
- │ ├─ [subplan_parallel_spawn] "Implement auth and payment modules, in parallel" │
- │ │ ├─ [subplan_spawn] "Write auth tests" → Plan: 01HXM9F1A │
- │ │ └─ [subplan_spawn] "Write payment tests" → Plan: 01HXM9F2B │
- │ └─ [subplan_parallel_spawn] "Write tests for remaining modules" │
- │ └─ ... │
- ╰──────────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Tree Summary ─────────────╮
- │ Nodes: 9 │
- │ Depth: 3 │
- │ Child Plans: 2+ │
- │ Invariants: 2 │
- │ Superseded: 0 (hidden) │
- ╰────────────────────────────╯
-
- ╭─ Child Plans ──────────────────────────────────────╮
- │ ID Phase State │
- │ ────────── ─────── ───────── │
- │ 01HXM9F1A execute processing │
- │ 01HXM9F2B execute queued │
- ╰────────────────────────────────────────────────────╯
-
- ╭─ Decision IDs (for correction) ──────────────────╮
- │ Root: 01HXM9A0B1Q2W3R5G8Z0P4Q1X8 │
- │ Invariant 1: 01HXM9A0C1R3X4S6G9Z1P5Q2Y9 │
- │ Invariant 2: 01HXM9A0D2S4Y5T7H0Z2P6Q3Z0 │
- │ Strategy: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
- │ Parallel 1: 01HXM9A1D3R8X5S7H1Z2P5Q2Y0 │
- │ Spawn Auth: 01HXM9A2D3Q8W4R6H9Z1P5Q2X0 │
- │ Spawn Payment: 01HXM9A3E4Q9W5R7I0Z2P6Q3X1 │
- │ Parallel 2: 01HXM9A4F5Q0W6R8J1Z3P7Q4X2 │
- ╰──────────────────────────────────────────────────╯
-
- ✓ OK Decision tree rendered
- agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>
- $ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --show-context
-
- ╭─ Decision ─────────────────────────────────────╮
- │ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
- │ Type: strategy_choice │
- │ Question: Which modules should be prioritized? │
- │ Chosen: Auth and payments │
- │ Confidence: 0.82 │
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Sequence: 2 of 5 │
- │ Created: 2026-02-08 12:58 │
- ╰────────────────────────────────────────────────╯
-
- ╭─ Alternatives Considered ──────────────────────╮
- │ 1. Auth and payments (chosen) │
- │ 2. User module first (coverage 71%, med risk) │
- │ 3. All modules equally (spread thin) │
- ╰────────────────────────────────────────────────╯
-
- ╭─ Impact ──────────────────────╮
- │ Downstream Decisions: 3 │
- │ Downstream Child Plans: 2 │
- │ Artifacts Produced: 5 │
- │ Correction Impact: medium │
- ╰───────────────────────────────╯
-
- ╭─ Context Snapshot ───────────────╮
- │ - Coverage < 70% in auth │
- │ - Payments failures last release │
- │ - Auth: 12 files, 45% coverage │
- │ - Payments: 8 files, 52% cover. │
- │ Hot Context Hash: sha256:4b2e... │
- ╰──────────────────────────────────╯
-
- ╭─ Rationale ───────────────────────────────────────╮
- │ Auth and payment modules have the lowest coverage │
- │ and highest business risk. Auth handles security │
- │ tokens, payments handles money. Both had bugs in │
- │ the last release traceable to missing tests. │
- ╰───────────────────────────────────────────────────╯
-
- ╭─ Correction ──────────────────────────────────────────────╮
- │ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
- │ --mode revert --guidance "Prioritize payments first..." │
- ╰───────────────────────────────────────────────────────────╯
-
- ✓ OK Decision explained
-
- $ agents plan explain --show-reasoning 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
-
- ╭─ Decision ──────────────────────────────╮
- │ ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
- │ Type: strategy_choice │
- │ Choice: Convert to async/await │
- │ Alternatives: 3 │
- ╰─────────────────────────────────────────╯
-
- ╭─ Alternatives Considered ────────────────────────────────────╮
- │ 1. Convert to async/await patterns (chosen) │
- │ 2. Keep synchronous with thread pool │
- │ 3. Use callback-based approach │
- ╰──────────────────────────────────────────────────────────────╯
-
- ╭─ Rationale ──────────────────────────────────────────────────╮
- │ Async/await is the modern Python standard for I/O-bound │
- │ operations. The project already uses asyncio in 3 modules. │
- │ Thread pools would add complexity without native support. │
- ╰──────────────────────────────────────────────────────────────╯
-
- ╭─ Model Reasoning (raw) ───────────────────────────────────────╮
- │ I need to decide on the concurrency pattern for the payment │
- │ processing module. Let me analyze the current codebase: │
- │ │
- │ 1. src/payments/api.py uses synchronous requests. │
- │ 2. src/core/scheduler.py already uses asyncio. │
- │ 3. The database driver (asyncpg) supports async natively. │
- │ 4. Project invariant says "prefer modern Python patterns". │
- │ │
- │ Given that 3/5 core modules already use asyncio, and the │
- │ database driver supports it, converting to async/await is │
- │ the most consistent choice. Thread pools would work but │
- │ add unnecessary complexity and don't integrate well with │
- │ the existing asyncio event loop in scheduler.py. │
- ╰───────────────────────────────────────────────────────────────╯
-
- ✓ OK Decision explained
- agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE>
- [--dry-run] [--yes|-y] <DECISION_ID>
- $ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert \
- --guidance "Prioritize payments first" --yes
-
- ╭─ Correction ────────────────────────────────────────╮
- │ Mode: revert │
- │ Impact: 3 decisions, 2 child plans, 5 artifacts │
- │ New Decision: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 │
- │ Corrects: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
- │ Attempt: 2 │
- ╰─────────────────────────────────────────────────────╯
-
- ╭─ Affected Subtree ──────────────╮
- │ Decisions Invalidated: 3 │
- │ Child Plans Rolled Back: 2 │
- │ Artifacts Archived: 5 │
- │ Unaffected Decisions: 2 │
- ╰─────────────────────────────────╯
-
- ╭─ Sandbox Rollback ─────────────╮
- │ Checkpoint: cp_01HXM8C2 │
- │ Files Reverted: 5 │
- │ Status: restored │
- ╰────────────────────────────────╯
-
- ╭─ Recompute ──────────────╮
- │ Queued: 2 child plans │
- │ ETA: 4m │
- ╰──────────────────────────╯
-
- ╭─ History ───────────────────────────────────────────╮
- │ - Original decision superseded │
- │ - Prior artifacts archived for comparison │
- │ - agents plan diff --correction 01HXM9B7Z3Q1Q8K2.. │
- ╰─────────────────────────────────────────────────────╯
-
- ✓ OK Correction applied
-
- $ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode append \
- --guidance "Also add rate limiting to the auth endpoints"
-
- ╭─ Correction ─────────────────────────────────────╮
- │ Mode: append │
- │ Impact: adds to existing subtree, no rollback │
- │ New Decision: 01HXM9C3Z5T2Q8K2E9H7K3W2M8 │
- │ Appended After: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
- │ Attempt: 2 │
- ╰──────────────────────────────────────────────────╯
-
- ╭─ Append Detail ─────────────────────────────────────────────────╮
- │ Original decision preserved: yes │
- │ Existing artifacts kept: yes │
- │ Additional work: appended as new child plan │
- │ The original 5 artifacts remain; a new child plan will add │
- │ rate-limiting code on top of the existing auth changes. │
- ╰─────────────────────────────────────────────────────────────────╯
-
- ╭─ Queued ──────────╮
- │ New child: 1 │
- │ ETA: 2m │
- ╰───────────────────╯
-
- ✓ OK Append correction queued
-
- $ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert \
- --guidance "Use async/await pattern instead" --dry-run
-
- ╭─ Dry Run — Correction Preview ─────────────────────────────────────╮
- │ ⚠ This is a preview only. No changes will be made. │
- ╰────────────────────────────────────────────────────────────────────╯
-
- ╭─ Would Revert ───────────────────────────────────────╮
- │ Decisions to invalidate: 3 │
- │ 01HXM9A1.. strategy_choice "sync pattern" │
- │ 01HXM9A2.. implementation_choice "requests" │
- │ 01HXM9A3.. tool_invocation write_file ×4 │
- │ Child plans to roll back: 2 │
- │ Artifacts to archive: 5 files │
- │ Unaffected decisions: 2 (will be kept) │
- ╰──────────────────────────────────────────────────────╯
-
- ╭─ Estimated Cost ──────────╮
- │ Re-strategize: ~$0.012 │
- │ Re-execute: ~$0.035 │
- │ Total: ~$0.047 │
- │ ETA: ~4 minutes │
- ╰───────────────────────────╯
-
- To execute this correction, remove --dry-run and add --yes
- agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>)
- $ agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Diff Summary ─────────────────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Project: local/api-service │
- │ Files Changed: 2 │
- │ Insertions: 12 │
- │ Deletions: 4 │
- │ Net Change: +8 lines │
- ╰────────────────────────────────────────────────╯
-
- ╭─ Files ───────────────────────────────╮
- │ Path Change Status │
- │ ─────────────────── ────── ──────── │
- │ src/auth/session.py +8 -2 modified │
- │ src/auth/tokens.py +4 -2 modified │
- ╰───────────────────────────────────────╯
-
- ╭─ Patch Preview ──────────────────────────╮
- │ --- a/src/auth/session.py │
- │ +++ b/src/auth/session.py │
- │ @@ -12,4 +12,10 @@ │
- │ - import jwt │
- │ + import sessionlib │
- │ - def validate_token(...) │
- │ + def validate_session(...) │
- │ --- a/src/auth/tokens.py │
- │ +++ b/src/auth/tokens.py │
- │ @@ -5,3 +5,7 @@ │
- │ - TOKEN_EXPIRY = 3600 │
- │ + TOKEN_EXPIRY = 7200 │
- ╰──────────────────────────────────────────╯
-
- ╭─ Risk Assessment ────────────────╮
- │ API Compatibility: preserved │
- │ Test Coverage: maintained │
- │ Breaking Changes: none detected │
- ╰──────────────────────────────────╯
-
- ✓ OK Diff generated
-
- $ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
-
- ╭─ Correction Diff ───────────────────────────────╮
- │ Correction: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 │
- │ Original Decision: 01HXM9A1C2Q7W3R5.. │
- │ Mode: revert │
- │ Files Changed: 3 │
- │ New Insertions: 18 │
- │ New Deletions: 6 │
- ╰─────────────────────────────────────────────────╯
-
- ╭─ Comparison ─────────────────────────────────────────────────────╮
- │ File Before (original) After (corrected) │
- │ ──────────────────── ──────────────── ──────────────────── │
- │ src/payments/api.py +12 -4 +18 -6 (expanded) │
- │ src/auth/tokens.py +8 -2 (unchanged) │
- │ tests/test_payments.py (new file) (new file, larger) │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Patch Preview (corrected vs original) ───────────╮
- │ --- a/src/payments/api.py (original) │
- │ +++ b/src/payments/api.py (corrected) │
- │ @@ -1,12 +1,18 @@ │
- │ - # sync payment processing │
- │ + # async payment processing (corrected) │
- │ + import asyncio │
- │ + from aiohttp import ClientSession │
- │ ... │
- ╰───────────────────────────────────────────────────╯
-
- ✓ OK Correction diff generated
- agents plan artifacts <PLAN_ID>
- $ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Artifacts ─────────────────────────────────────────────────╮
- │ Path Type Size Change Child Plan │
- │ ───────────────────── ───── ────── ───────── ─────── │
- │ src/auth/session.py write 2.1 KB +8 -2 root │
- │ tests/test_session.py write 4.7 KB +47 -0 root │
- │ src/auth/tokens.py edit 1.8 KB +4 -2 root │
- │ tests/test_tokens.py write 3.2 KB +32 -0 auth │
- ╰─────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ───────────╮
- │ Total: 4 │
- │ Writes: 2 (new) │
- │ Edits: 2 (modified) │
- │ Deletes: 0 │
- │ Total Size: 11.8 KB │
- ╰─────────────────────╯
-
- ╭─ By Plan ─────────────────╮
- │ Root Plan: 3 artifacts │
- │ auth-tests: 1 artifact │
- │ payment-tests: (pending) │
- ╰───────────────────────────╯
-
- ✓ OK 4 artifacts listed
- agents plan errors <PLAN_ID>
- $ agents plan errors 01HXM8C2ZK4Q7C2B3F2R4VYV6J
-
- ╭─ Plan Errors ──────────────────────────────────────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Phase: execute │
- │ State: errored │
- │ Error: Tool execution failed: write_file permission denied │
- │ │
- │ Error Category: tool_execution │
- │ Error Phase: execute │
- │ Retry Count: 2/3 │
- │ Retriable: true │
- │ │
- │ Recovery Suggestions: │
- │ → Check sandbox permissions and retry execution │
- │ $ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ → Revert to Strategize phase to adjust the plan │
- │ $ agents plan correct --mode revert -g "..." <DECISION_ID> │
- ╰────────────────────────────────────────────────────────────────────╯
-
- ✓ OK
- agents plan prompt <PLAN_ID> <GUIDANCE>
- $ agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
-
- ╭─ Guidance Added ────────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Guidance: Use mocks for database tests │
- │ Scope: next execution step │
- │ Phase: execute │
- │ State: errored → processing │
- ╰─────────────────────────────────────────╯
-
- ╭─ Decision Created ────────────────────────╮
- │ Type: user_intervention │
- │ ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3 │
- │ Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
- ╰───────────────────────────────────────────╯
-
- ╭─ Queue ────╮
- │ Pending: 1 │
- │ Applied: 0 │
- ╰────────────╯
-
- ✓ OK Guidance queued
- agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>
- $ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
-
- Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
-
- ╭─ Rollback Summary ───────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Checkpoint: cp_01HXM8C2 │
- │ Label: before auth refactor │
- │ Files: 6 reverted │
- ╰──────────────────────────────────╯
-
- ╭─ Changes Reverted ──────────────────╮
- │ File Action │
- │ ────────────────────── ────────── │
- │ src/auth/session.py restored │
- │ src/auth/tokens.py restored │
- │ tests/test_session.py removed │
- │ tests/test_tokens.py removed │
- │ src/auth/fixtures.py restored │
- │ src/auth/__init__.py restored │
- ╰─────────────────────────────────────╯
-
- ╭─ Impact ──────────────────────────────╮
- │ Child Plans Invalidated: 2 │
- │ Sandbox: restored to cp_01HXM8C2 │
- │ Decisions After CP: 2 discarded │
- │ Tool Calls After CP: 5 undone │
- ╰───────────────────────────────────────╯
-
- ╭─ Post-Rollback State ──────────╮
- │ Phase: execute │
- │ State: queued (awaiting input) │
- │ Checkpoints Remaining: 2 │
- ╰────────────────────────────────╯
-
- ✓ OK Rollback complete
- agents action create --config|-c <CFG_FILE>
- $ agents action create --config ./actions/code-coverage.yaml
-
- ╭─ Action Created ────────────────────────╮
- │ Name: local/code-coverage │
- │ State: available │
- │ Strategy Actor: local/strategist │
- │ Execution Actor: local/executor │
- │ Reusable: yes │
- │ Read Only: no │
- │ Config: ./actions/code-coverage.yaml │
- │ Created: 2026-02-08 12:20 │
- ╰─────────────────────────────────────────╯
-
- ╭─ Definition of Done ─╮
- │ Coverage reaches 85% │
- ╰──────────────────────╯
-
- ╭─ Arguments ──────────────────────────────────────────────────────╮
- │ Name Type Required Description │
- │ ─────────────────────── ────── ──────── ───────────────────── │
- │ target_coverage_percent int yes Target coverage % │
- │ test_command string no Test framework to use │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Automation ──────────────────────────╮
- │ Profile: supervised │
- │ Source: default │
- ╰───────────────────────────────────────╯
-
- ✓ OK Action created
- agents action list [(--namespace|-n) <NS>] [(--state|-s) <STATE>] [<REGEX>]
- $ agents action list
-
- ╭─ Actions ──────────────────────────────────────────────────────────────────────────────────╮
- │ Name State Strategy Actor Execution Actor Reusable Plans │
- │ ─────────────────── ───────── ──────────────── ─────────────── ──────── ───── │
- │ local/code-coverage available local/strategist local/executor ✓ 3 │
- ╰────────────────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Filters ────────╮
- │ State: available │
- │ Namespace: (any) │
- ╰──────────────────╯
-
- ╭─ Summary ──────────────╮
- │ Total: 1 │
- │ Available: 1 │
- │ Archived: 0 │
- │ Total Plans Created: 3 │
- ╰────────────────────────╯
-
- ✓ OK 1 action listed
- agents action show <ACTION_NAME>
- $ agents action show local/code-coverage
-
- ╭─ Action Details ──────────────────────╮
- │ Name: local/code-coverage │
- │ State: available │
- │ Strategy Actor: local/strategist │
- │ Execution Actor: local/executor │
- │ Reusable: yes │
- │ Read Only: no │
- │ Created: 2026-02-08 12:20 │
- ╰───────────────────────────────────────╯
-
- ╭─ Definition of Done ─╮
- │ Coverage reaches 85% │
- ╰──────────────────────╯
-
- ╭─ Arguments ──────────────────────────────────────────────────────╮
- │ Name Type Required Description │
- │ ─────────────────────── ────── ──────── ───────────────────── │
- │ target_coverage_percent int yes Target coverage % │
- │ test_command string no Test framework to use │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Automation ──────────────────────────╮
- │ Profile: supervised │
- │ Source: default │
- ╰───────────────────────────────────────╯
-
- ╭─ History ────────────────────╮
- │ Plans Created: 3 │
- │ Plans Completed: 2 │
- │ Plans Failed: 0 │
- │ Avg Duration: 00:04:30 │
- │ Avg Cost: $0.072 │
- ╰──────────────────────────────╯
-
- ╭─ Usage ───────────────────────────────────────────────────────────╮
- │ - agents plan use local/code-coverage local/api-service │
- │ --arg target_coverage_percent=85 │
- ╰───────────────────────────────────────────────────────────────────╯
-
- ✓ OK Action loaded
- agents action archive <ACTION_NAME>
- $ agents action archive local/old-action
-
- ╭─ Action Archived ───────────╮
- │ Name: local/old-action │
- │ State: available → archived │
- │ Archived: 2026-02-08 12:22 │
- ╰─────────────────────────────╯
-
- ╭─ Impact ───────────────────────╮
- │ Availability: hidden from list │
- │ Existing Plans: unchanged │
- │ Active Plans: 0 affected │
- ╰────────────────────────────────╯
-
- ╭─ History ─────────────────╮
- │ Total Plans: 5 │
- │ Completed: 4 │
- │ Failed: 1 │
- │ Last Used: 2026-02-06 │
- ╰───────────────────────────╯
-
- ✓ OK Action archived
- agents automation-profile add --config|-c <FILE> [--update]
- $ agents automation-profile add --config ./profiles/careful-auto.yaml
-
- ╭─ Profile Registered ─────────────────────────────────────────────╮
- │ Name: local/careful-auto │
- │ Description: Autonomous execution with mandatory sandbox │
- │ and manual apply │
- │ Created: 2026-02-08 14:30 │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ╭─ Confidence Thresholds ────────────────╮
- │ decompose_task: 0.0 │
- │ create_tool: 0.0 │
- │ select_tool: 1.0 │
- │ edit_code: 0.0 │
- │ execute_command: 0.0 │
- │ create_file: 0.0 │
- │ delete_content: 1.0 │
- │ access_network: 1.0 │
- │ install_dependency: 0.0 │
- │ modify_config: 0.0 │
- │ approve_plan: 0.0 │
- │ require_sandbox: true │
- │ require_checkpoints: true │
- │ allow_unsafe_tools: false │
- ╰────────────────────────────────────────╯
-
- ✓ OK Profile registered
- agents automation-profile remove [--yes|-y] <NAME>
- $ agents automation-profile remove local/careful-auto
-
- Remove automation profile local/careful-auto? [y/N]: y
-
- ╭─ Profile Removed ──────────╮
- │ Name: local/careful-auto │
- ╰────────────────────────────╯
-
- ✓ OK Profile removed
- agents automation-profile list [<REGEX>]
- $ agents automation-profile list
-
- ╭─ Automation Profiles ──────────────────────────────────────────────────────────╮
- │ Name Source Auto-Apply Sandbox Description │
- │ ────────────────── ──────── ────────── ─────── ──────────────────────── │
- │ manual built-in 1.0 yes Human-driven (default) │
- │ review built-in 1.0 yes Auto-phase, manual decisions │
- │ supervised built-in 1.0 yes Auto-plan, manual exec │
- │ cautious built-in 1.0 yes Confidence-gated automation │
- │ trusted built-in 1.0 yes Auto-exec, manual apply │
- │ auto built-in 1.0 yes Full auto except apply │
- │ ci built-in 0.0 yes Full auto, safe CI/CD │
- │ full-auto built-in 0.0 no Complete automation │
- │ local/careful-auto custom 0.8 yes Custom careful profile │
- ╰────────────────────────────────────────────────────────────────────────────────╯
-
- ╭─ Summary ───────────╮
- │ Built-in: 8 │
- │ Custom: 1 │
- │ Total: 9 │
- ╰─────────────────────╯
-
- ✓ OK 9 profiles listed
- agents automation-profile show <NAME>
- $ agents automation-profile show trusted
-
- ╭─ Automation Profile ───────────────────────────────────────────╮
- │ Name: trusted │
- │ Source: built-in │
- │ Description: Auto-exec, manual apply. Day-to-day development │
- ╰────────────────────────────────────────────────────────────────╯
-
- ╭─ Phase Transitions (thresholds) ─────╮
- │ decompose_task: 0.0 │
- │ create_tool: 0.0 │
- │ select_tool: 1.0 │
- ╰──────────────────────────────────────╯
-
- ╭─ Decision Automation (thresholds) ───╮
- │ edit_code: 0.0 │
- │ execute_command: 0.0 │
- ╰──────────────────────────────────────╯
-
- ╭─ Self-Repair (thresholds) ───────────╮
- │ create_file: 0.0 │
- │ delete_content: 1.0 │
- │ access_network: 1.0 │
- │ modify_config: 0.0 │
- │ approve_plan: 1.0 │
- ╰──────────────────────────────────────╯
-
- ╭─ Execution Controls (thresholds) ────╮
- │ install_dependency: 0.0 │
- │ require_sandbox: true │
- │ require_checkpoints: true │
- │ allow_unsafe_tools: false │
- ╰──────────────────────────────────────╯
-
- ✓ OK Profile loaded
- agents config set <key> <value>
- $ agents config set core.automation-profile trusted
-
- ╭─ Config Updated ──────────────────────╮
- │ Key: core.automation-profile │
- │ Value: trusted │
- │ Previous: manual │
- │ Source: config │
- │ Scope: global │
- ╰───────────────────────────────────────╯
-
- ╭─ Effective ────────────────────────╮
- │ Sessions: new sessions │
- │ Plans: future plans (unless set) │
- │ Existing: unchanged │
- ╰────────────────────────────────────╯
-
- ╭─ Saved To ──────────────────────────╮
- │ File: ~/.cleveragents/config.toml │
- │ Line: 8 │
- ╰─────────────────────────────────────╯
-
- ✓ OK Config updated
-
- $ agents config set core.format table
-
- ╭─ Config Updated ─────────────────╮
- │ Key: core.format │
- │ Previous: rich │
- │ New Value: table │
- │ Scope: user (~/.cleveragents) │
- ╰──────────────────────────────────╯
-
- ✓ OK Set core.format = table
-
- $ agents config set actor.default.invariant local/invariant-resolver
-
- ╭─ Config Updated ──────────────────────────────────╮
- │ Key: actor.default.invariant │
- │ Previous: (not set) │
- │ New Value: local/invariant-resolver │
- │ Scope: user (~/.cleveragents) │
- ╰───────────────────────────────────────────────────╯
-
- ✓ OK Set actor.default.invariant = local/invariant-resolver
- agents config get <key>
- $ agents config get core.automation-profile
-
- ╭─ Config ──────────────────────────╮
- │ Key: core.automation-profile │
- │ Value: trusted │
- │ Source: config │
- │ Overridden: no │
- │ Type: string │
- ╰───────────────────────────────────╯
-
- ╭─ Origin ──────────────────────────╮
- │ File: ~/.cleveragents/config.toml │
- │ Line: 8 │
- │ Default: supervised │
- ╰───────────────────────────────────╯
-
- ╭─ Resolution Chain ──────────────╮
- │ 1. CLI flag: (not set) │
- │ 2. Env var: (not set) │
- │ 3. Config file: trusted │
- │ 4. Default: supervised │
- │ Winner: config file (level 3) │
- ╰─────────────────────────────────╯
-
- ✓ OK Config read
- agents config list [--filter-values <REGEX>] [<REGEX>]
- $ agents config list
-
- ╭─ Config ───────────────────────────────────────────────────╮
- │ Key Value Source Modified │
- │ ──────────────── ────────────────── ─────── ──────── │
- │ core.automation-profile trusted config yes │
- │ actor.default.invariant local/reconciler config yes │
- │ core.log.level FATAL default no │
- ╰────────────────────────────────────────────────────────────╯
-
- ╭─ Overrides ─────╮
- │ Env: none │
- │ CLI Flags: none │
- ╰─────────────────╯
-
- ╭─ Config File ───────────────────────╮
- │ Path: ~/.cleveragents/config.toml │
- │ Size: 284 bytes │
- │ Valid: yes │
- ╰─────────────────────────────────────╯
-
- ✓ OK 6 settings listed
- agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]...
- [--action ACTION]... <INVARIANT_TEXT>
- $ agents invariant add --global "All public APIs must maintain backward compatibility"
-
- ╭─ Invariant Added ──────────────────────────────────────────────────────╮
- │ Invariant: All public APIs must maintain backward compatibility │
- │ Scope: global │
- │ ID: inv_01HXM9A1B │
- ╰────────────────────────────────────────────────────────────────────────╯
-
- ✓ OK Invariant added
-
- $ agents invariant add --project local/api-service "All endpoints must validate auth tokens"
-
- ╭─ Invariant Added ──────────────────────────────────────────────╮
- │ Project: local/api-service │
- │ Invariant: All endpoints must validate auth tokens │
- │ Scope: project │
- │ ID: inv_01HXM9A2C │
- ╰────────────────────────────────────────────────────────────────╯
-
- ✓ OK Invariant added
-
- $ agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
-
- ╭─ Invariant Added ─────────────────────────────────────────────────────╮
- │ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
- │ Invariant: All database queries must use parameterized statements │
- │ Scope: plan │
- │ ID: inv_01HXM9G3A │
- ╰───────────────────────────────────────────────────────────────────────╯
-
- ✓ OK Invariant added
-
- $ agents invariant add --action local/code-coverage "Test files must not import production secrets"
-
- ╭─ Invariant Added ──────────────────────────────────────────────────────╮
- │ Action: local/code-coverage │
- │ Invariant: Test files must not import production secrets │
- │ Scope: action │
- │ ID: inv_01HXM9H4B │
- ╰────────────────────────────────────────────────────────────────────────╯
-
- ✓ OK Invariant added
- agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID] [--action ACTION]
- [--effective] [<REGEX>]
- $ agents invariant list --global
-
- ╭─ Global Invariants ──────────────────────────────────────────────────────╮
- │ ID Text │
- │ ────────────── ──────────────────────────────────────────────────── │
- │ inv_01HXM9A1B All public APIs must maintain backward compatibility │
- │ inv_01HXM9A1C Payment processing must be idempotent │
- ╰──────────────────────────────────────────────────────────────────────────╯
-
- ✓ OK 2 invariants
-
- $ agents invariant list --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J --effective
-
- ╭─ Effective Invariants (Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J) ──────────────────────────────────╮
- │ ID Source Text │
- │ ────────────── ─────── ────────────────────────────────────────────────────── │
- │ inv_01HXM9A1B global All public APIs must maintain backward compatibility │
- │ inv_01HXM9A2C project All endpoints must validate auth tokens │
- │ inv_01HXM9G3A plan All database queries must use parameterized statements │
- ╰───────────────────────────────────────────────────────────────────────────────────────────╯
-
- │ Conflicts Resolved: 1 │
- │ Global "Use shared DB pool" overridden by plan "All database queries must use │
- │ parameterized statements" │
-
- ✓ OK 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
- agents invariant remove [--yes|-y] <INVARIANT_ID>
- $ agents invariant remove inv_01HXM9A1C
-
- Remove invariant inv_01HXM9A1C ("Payment processing must be idempotent", scope: global)? [y/N]: y
-
- ╭─ Invariant Removed ──────────────────────────────────────────────╮
- │ Removed: Payment processing must be idempotent │
- │ Scope: global │
- │ ID: inv_01HXM9A1C │
- ╰──────────────────────────────────────────────────────────────────╯
-
- ✓ OK Invariant removed
-
-# Example: Execution actor with subplan spawning capability.
-# The graph uses a tool node referencing a named registered tool.
-actors:
- code_executor:
- type: graph
- config:
- actor: anthropic/claude-3-opus
- skills:
- - local/plan-tools # Skill containing create_subplan for LLM tool-calling
- - local/file-ops
- routes:
- execute_workflow:
- nodes:
- - name: spawn_test_subplan
- type: tool
- tool: local/create-subplan # Named tool from Tool Registry
-
-# File: tools/create-subplan.yaml
-cleveragents:
- version: "3.0"
-
-tool:
- name: local/create-subplan
- description: "Spawn a subplan for a given action"
- source: custom
-
- input_schema:
- type: object
- properties:
- action: { type: string }
- target_files: { type: array, items: { type: string } }
- required: [action]
-
- capability:
- writes: true
- checkpointable: false
- side_effects: [spawn_subplan]
-
- code: |
- subplan = ctx.spawn_subplan(
- action=params["action"],
- target_files=params.get("target_files", [])
- )
- return {"subplan_id": subplan.id}
-
-# File: skills/plan-tools.yaml
-skill:
- name: local/plan-tools
- description: "Tools for spawning and managing subplans"
- tools:
- - local/create-subplan
-
-SELECT * FROM decisions
-WHERE plan_id = :plan_id
- AND superseded_by IS NULL
-ORDER BY sequence_number;
-
-Decision required: Which modules should be prioritized for test coverage?
-
-Options identified by the strategy actor:
- 1. auth module (currently 45% coverage, high risk)
- 2. payment module (currently 52% coverage, high risk)
- 3. user module (currently 71% coverage, medium risk)
-
-Your choice (or provide custom guidance): _
-
-Plan: 01KH29QDEE6DZTXKWNKCV8VP0F
-├── [prompt_definition] "Increase test coverage to 85% for the whole project."
-├── [invariant_enforced] "Prioritize all functionality related to financial transactions and user management"
-├── [invariant_enforced] "All API calls over TCP must be mocked"
-├── [strategy_choice] "Prioritize auth and payment modules, implement them in parallel before the rest"
-├── [subplan_parallel_spawn] "Implement auth and payment modules, in parallel"
-│ ├── [subplan_spawn] "Write tests for auth module"
-│ │ └── Plan: 01KH29R8WPKPBHRY7Q0NA9XW86
-│ │ ├── [prompt_definition] "Write unit tests for auth module using mocks for the remote API calls"
-│ │ ├── [implementation_choice] "Test login flow first"
-│ │ └── ...
-│ └── [subplan_spawn] "Write tests for payment module"
-│ └── Plan: 01KH29RN2YKSXMTBDG82AKRHRA
-│ ├── [prompt_definition] "Write unit tests for payment module using"
-│ └── ...
-└── [subplan_parallel_spawn] "Write tests for all modules except the auth and payment modules"
- └── ...
-
-agents plan correct <decision_id> --mode=<mode> --guidance "<corrected decision text>"
-
-# Correct a strategy choice
-agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=revert \
- --guidance "Prioritize the payment module first, not auth, due to upcoming deadline"
-
-# Correct the root prompt to be more specific
-agents plan tree <plan_id>
-# Shows: [prompt_definition] id=01ARZ3NDEKTSV4RRFFQ69G5FAV "Increase test coverage to 85%"
-
-agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=revert \
- --guidance "Increase test coverage to 85%, prioritizing auth and payment modules. Use mocks for database tests, not integration tests."
-
-# Correct a subplan's prompt (originally created by parent plan)
-agents plan correct 01BRZ4PDFLUTW5SSGR70H6GBW --mode=revert \
- --guidance "Write unit tests for auth module, focusing on edge cases for token expiration"
-
-# Append a fix rather than rewriting history
-agents plan correct 01ARZ3NDEKTSV4RRFFQ69G5FAV --mode=append \
- --guidance "The previous approach missed error handling tests - add comprehensive error path coverage"
-
-# Remove an invariant that shouldn't apply
-agents plan correct 01CRZ5QEHMVUX6TTHR81I7HCX --mode=revert \
- --guidance "Remove this invariant - TCP mocking is not needed for this module since it has no network calls"
-
-# Add a missing invariant to the plan
-agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
-
-# Pseudocode: Strategy actor decision recording loop
-while unresolved_ambiguities_remain(plan, context):
- choice_point = analyze_context_for_ambiguity(context)
- options = generate_and_evaluate_options(choice_point, context, invariants)
-
- # Record via tool call — system auto-captures context snapshot
- decision_id = record_decision(
- decision_type = choice_point.type,
- question = choice_point.question,
- chosen_option = best_option.description,
- alternatives_considered = [o.description for o in rejected_options],
- confidence_score = best_option.confidence,
- rationale = best_option.reasoning
- )
-
- context.add_decision(decision_id) # Decision informs subsequent reasoning
-
-Decision:
- # Identity
- decision_id: ULID # Unique identifier
- plan_id: ULID # Parent plan this decision belongs to
- parent_decision_id: ULID | null # Parent decision (for tree structure)
- sequence_number: int # Order within the plan's decisions
-
- # Classification
- decision_type: enum
- - prompt_definition # The prompt/description for this plan (root decision)
- - invariant_enforced # An invariant (from global, project, action, or plan scope) applicable to this plan, added as a constraint
- - strategy_choice # High-level approach decision during Strategize
- - implementation_choice # How to implement a specific task
- - resource_selection # Which resources to read/modify
- - subplan_spawn # Decision to create a child plan (spawned later in Execute)
- - subplan_parallel_spawn # Decision to spawn a group of child plans in parallel (contains subplan_spawn children)
- - tool_invocation # Which skill/tool to use
- - error_recovery # How to handle a failure
- - validation_response # Response to validation failure
- - user_intervention # User provided guidance/correction
-
- # The Decision Itself
- question: str # What question was being answered
- chosen_option: str # What was decided
- alternatives_considered: list[str] # Other options that were evaluated
- confidence_score: float | null # 0.0-1.0 if the actor provided confidence
-
- # Context Snapshot (for replay)
- context_snapshot:
- hot_context_hash: str # Cryptographic hash of the exact context
- hot_context_ref: str # Pointer to the full stored snapshot
- relevant_resources: list[ResourceRef] # Every file/symbol that influenced this decision
- actor_state_ref: str # Complete LangGraph checkpoint
-
- # When the system decides "refactor the authentication module to use async patterns,"
- # it permanently records:
- # - Which files were examined to make that decision
- # - What symbols and dependencies were traced
- # - The exact code state that was analyzed
- # - The reasoning chain that led to this choice
- # - Alternative approaches that were considered but rejected
-
- # Rationale
- rationale: str # Why this option was chosen
- actor_reasoning: str | null # Raw LLM reasoning if available
-
- # Downstream Impact (populated during Execute phase)
- downstream_decision_ids: list[ULID] # Decisions that depend on this one
- downstream_plan_ids: list[ULID] # Child plans spawned because of this decision
- artifacts_produced: list[ArtifactRef] # Files/outputs created under this decision
-
- # Timestamps
- created_at: datetime
-
- # Correction Metadata
- is_correction: bool # Was this decision a correction of another?
- corrects_decision_id: ULID | null # If correction, which decision was replaced
- correction_reason: str | null # Why the correction was made
- superseded_by: ULID | null # If this decision was later corrected
-
--- Core decision table
-CREATE TABLE decisions (
- decision_id TEXT PRIMARY KEY, -- ULID
- plan_id TEXT NOT NULL,
- parent_decision_id TEXT,
- sequence_number INTEGER NOT NULL,
- decision_type TEXT NOT NULL, -- prompt_definition, invariant_enforced, strategy_choice,
- -- implementation_choice, resource_selection, subplan_spawn,
- -- subplan_parallel_spawn, tool_invocation, error_recovery,
- -- validation_response, user_intervention
- question TEXT,
- chosen_option TEXT NOT NULL,
- alternatives_considered TEXT, -- JSON array
- confidence_score REAL,
- rationale TEXT,
- actor_reasoning TEXT,
- context_snapshot TEXT NOT NULL, -- JSON blob
- is_correction BOOLEAN DEFAULT FALSE,
- corrects_decision_id TEXT,
- correction_reason TEXT,
- superseded_by TEXT,
- created_at TEXT NOT NULL,
-
- FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
- FOREIGN KEY (parent_decision_id) REFERENCES decisions(decision_id),
- FOREIGN KEY (corrects_decision_id) REFERENCES decisions(decision_id),
- FOREIGN KEY (superseded_by) REFERENCES decisions(decision_id)
-);
-
--- Downstream relationships (many-to-many for DAG)
-CREATE TABLE decision_dependencies (
- upstream_decision_id TEXT NOT NULL,
- downstream_decision_id TEXT NOT NULL,
- dependency_type TEXT NOT NULL, -- 'decision', 'plan', 'artifact'
- downstream_ref TEXT NOT NULL, -- The actual ID of decision/plan/artifact
-
- PRIMARY KEY (upstream_decision_id, downstream_decision_id, downstream_ref),
- FOREIGN KEY (upstream_decision_id) REFERENCES decisions(decision_id)
-);
-
--- Correction history
-CREATE TABLE correction_attempts (
- attempt_id TEXT PRIMARY KEY, -- ULID
- plan_id TEXT NOT NULL,
- original_decision_id TEXT NOT NULL,
- new_decision_id TEXT,
- original_subtree_snapshot TEXT, -- Reference to archived state
- correction_reason TEXT,
- status TEXT NOT NULL, -- 'pending', 'executing', 'completed', 'failed'
- created_at TEXT NOT NULL,
- completed_at TEXT,
-
- FOREIGN KEY (plan_id) REFERENCES plans(plan_id),
- FOREIGN KEY (original_decision_id) REFERENCES decisions(decision_id),
- FOREIGN KEY (new_decision_id) REFERENCES decisions(decision_id)
-);
-
-agents action create --config ./actions/code-coverage.yaml
-
-# Basic usage
-agents plan use local/code-coverage my-api-service
-
-# Multiple projects
-agents plan use local/schema-update \
- api-service \
- web-frontend \
- mobile-app
-
-# With action arguments
-agents plan use local/code-coverage \
- my-api-service \
- --arg target_coverage_percent=85 \
- --arg test_framework=pytest
-
-# With explicit automation profile
-agents plan use local/deploy-action \
- staging-env \
- --automation-profile manual
-
-# With invariants attached at use time
-agents plan use local/code-coverage \
- my-api-service \
- --arg target_coverage_percent=85 \
- --invariant "All API calls over TCP must be mocked" \
- --invariant "Do not modify the payments module"
-
-# Pseudocode of what happens inside a strategy actor
-def compute_closure_for_refactoring(target_module):
- closure = ResourceClosure()
-
- # Direct file dependencies
- closure.add_files(find_imports(target_module))
- closure.add_files(find_includes(target_module))
-
- # Symbol dependencies
- for symbol in extract_exported_symbols(target_module):
- closure.add_files(find_symbol_usage(symbol, scope='project'))
-
- # Test dependencies
- closure.add_files(find_tests_for_module(target_module))
-
- # Build system dependencies
- closure.add_files(find_build_references(target_module))
-
- return closure
-
-# Example: Action with estimation actor (defined in the YAML config file)
-agents action create --config ./actions/expensive-refactor.yaml
-
-Plan A (refactoring auth module):
-- Sandbox A1: Contains only auth/*.cpp, auth_tests/*.cpp
-- Cannot see Plan B's intermediate states
-- Cannot accidentally depend on Plan B's half-done work
-
-Plan B (updating API endpoints):
-- Sandbox B1: Contains only api/*.cpp, api_tests/*.cpp
-- Makes changes assuming current auth interface
-- Protected from Plan A's intermediate refactoring
-
-def merge_subplan_results(subplan_results):
- # Group by resource type
- by_resource = group_by_resource_type(subplan_results)
-
- # Apply resource-specific merge strategies
- for resource_type, changes in by_resource:
- if resource_type == 'git-checkout':
- merge_git_changes(changes) # Three-way merge
- elif resource_type == 'fs-mount':
- merge_fs_changes(changes) # Copy-on-write reconciliation
- elif resource_type.startswith('database'):
- merge_db_changes(changes) # Sequential application
-
- # Validate merged state
- run_integration_tests()
-
-Decision: Refactor payment module to async
-alternatives_considered:
- - "Convert to async/await patterns" (chosen)
- - "Use thread pool with channels" (rejected: doesn't integrate with async ecosystem)
- - "Keep synchronous with timeout" (rejected: doesn't solve core latency issue)
-confidence_score: 0.85
-validation_performed:
- - Checked all payment API consumers can handle async
- - Verified database driver supports async operations
- - Confirmed no regulatory requirement for sync processing
-
-# Actor graph uses a named tool node for semantic validation
-actors:
- code_executor:
- type: graph
- skills:
- - local/semantic-validators # Skill containing validation tools for LLM tool-calling
- nodes:
- - name: semantic_validator
- type: tool
- tool: local/validate-api-compat # Named tool from Tool Registry
-
-# File: tools/validate-api-compat.yaml
-cleveragents:
- version: "3.0"
-
-tool:
- name: local/validate-api-compat
- description: "Check for breaking API changes and attempt auto-migration"
- source: custom
-
- capability:
- writes: true
- checkpointable: true
-
- code: |
- # Not just syntax checking - semantic validation
- old_api = extract_api_signature(previous_version)
- new_api = extract_api_signature(current_version)
-
- breaking_changes = find_breaking_changes(old_api, new_api)
- if breaking_changes:
- affected_consumers = find_api_consumers(breaking_changes)
- migration_plan = generate_migration(breaking_changes)
-
- if can_auto_migrate(affected_consumers, migration_plan):
- apply_migration(migration_plan)
- else:
- raise SemanticError(
- "Breaking API changes require manual review",
- changes=breaking_changes,
- affected=affected_consumers
- )
-
-# File: skills/semantic-validators.yaml
-skill:
- name: local/semantic-validators
- description: "Semantic validation tools for API compatibility and code invariants"
- tools:
- - local/validate-api-compat
-
-# Add invariants at different scopes
-agents invariant add --global "All public APIs must maintain backward compatibility"
-agents invariant add --global "Payment processing must be idempotent"
-agents invariant add --project local/api-service \
- "Database transactions must complete within 5 seconds"
-agents invariant add --project local/api-service \
- "Authentication must always use OAuth2"
-agents invariant add --plan <PLAN_ID> "All API calls over TCP must be mocked"
-agents invariant add --action local/code-coverage "Test files must not import production secrets"
-
-# List invariants
-agents invariant list --global
-agents invariant list --project local/api-service
-agents invariant list --plan <PLAN_ID> --effective # Shows reconciled view
-
-# Remove an invariant
-agents invariant remove <INVARIANT_ID>
-
-# Attach invariants at creation time (convenience)
-agents project create --invariant "All endpoints must validate auth tokens" local/api-service
-agents action create --config ./actions/code-coverage.yaml
-agents plan use local/code-coverage local/api-service --invariant "Mock all network calls"
-
-# Correct an invariant decision (remove or replace via standard correction)
-agents plan correct <DECISION_ID> --mode=revert \
- --guidance "Remove this invariant - it does not apply to this module"
-
-class InvariantEnforcer:
- def compute_effective_invariants(self, plan):
- """Compute the effective invariant view for a plan using the Invariant Reconciliation Actor."""
- # 1. Collect raw invariants from all scopes
- raw = self.collect_all_invariants(plan)
-
- # 2. Find the Invariant Reconciliation Actor (plan -> project -> global config)
- reconciler = (
- self.get_plan_invariant_actor(plan)
- or self.get_project_invariant_actor(plan)
- or self.get_global_invariant_actor()
- )
-
- # 3. Reconcile: apply precedence (plan > project > global), resolve conflicts
- effective = reconciler.reconcile(raw, precedence=['plan', 'project', 'global'])
- return effective
-
- def collect_all_invariants(self, plan):
- """Collect invariants from all scopes accessible to this plan."""
- invariants = []
- invariants.extend(self.get_global_invariants())
- for project in plan.projects:
- invariants.extend(self.get_project_invariants(project))
- invariants.extend(self.get_action_invariants(plan.action))
- invariants.extend(self.get_plan_invariants(plan))
- return invariants
-
- def check_invariant_preservation(self, changes, enforced_invariants):
- """Check that changes respect all enforced invariants."""
- for invariant in enforced_invariants:
- if not self.verify_invariant(invariant, changes):
- return InvariantViolation(invariant, changes)
- return Success()
-
-Error Pattern Database:
- - pattern: "Async conversion in payment module"
- historical_failures:
- - "Race condition in payment confirmation"
- - "Timeout handling breaks idempotency"
- preventive_checks:
- - "Add explicit transaction boundaries"
- - "Verify idempotency keys are preserved"
- - "Check distributed lock acquisition"
-
-# Step 1: Register resources independently
-agents resource add git-checkout local/api-repo \
- --path /repos/api-service \
- --branch main
-
-agents resource add local/database local/staging-db \
- --connection-string "postgresql://staging.example.com/mydb" \
- --read-only
-
-# Step 2: Create the project
-agents project create "my-api-service"
-
-# Step 3: Link resources to the project
-agents project link-resource "my-api-service" local/api-repo
-
-agents project link-resource "my-api-service" local/staging-db --read-only
-
-execution_environment:
- default: local/dev-container # Resource name of the default container
- priority: fallback # fallback | override
-
-name: local/my-workflow
-
-cleveragents:
- version: "3.0"
- default_actor: workflow_controller
-
-actors:
- # Simple LLM actor with skills referenced by name
- my_assistant:
- type: llm
- config:
- actor: openai/gpt-4 # Reference to built-in actor
- temperature: 0.7
- system_prompt: |
- You are a helpful assistant.
- Current task: {{ context.task_description }}
- skills:
- - local/file-ops # Grants access to all tools in this skill
- - local/git-ops
-
- # LLM actor with a composite skill (includes many sub-skills)
- data_processor:
- type: llm
- config:
- actor: anthropic/claude-3-opus
- system_prompt: |
- You are a data processing assistant.
- skills:
- - local/data-toolkit # A skill containing analysis + transformation tools
-
- # Actor referencing another actor
- reviewer:
- type: llm
- config:
- actor: local/code-reviewer # Reference to another custom actor
- memory_enabled: true
- max_history: 20
- skills:
- - local/file-ops
- - local/git-ops
-
-routes:
- main_workflow:
- type: graph
- entry_point: start
- nodes:
- - name: analyze
- type: agent
- agent: my_assistant
- - name: process
- type: agent
- agent: data_processor
- edges:
- - source: start
- target: analyze
- - source: analyze
- target: process
- - source: process
- target: end
-
-context:
- global:
- task_description: "Default task"
-
-nodes:
- - name: run_db_migrate
- type: tool
- tool: local/run-migrations # Named tool from Tool Registry
- override: # Optional metadata override
- capability:
- human_approval_required: true
-
- - name: spawn_tests
- type: tool
- tool: local/create-subplan # Another named tool
-
-nodes:
- - name: custom_validation
- type: tool
- anonymous: true
- description: "Validate output format before proceeding"
- input_schema:
- type: object
- properties:
- data: { type: object }
- capability:
- read_only: true
- code: |
- # Inline Python — same format as a named tool YAML body
- if not params["data"].get("status"):
- raise ValueError("Missing status field")
- return {"valid": True}
-
-name: local/pyright
-description: "Pyright language server for Python type checking and intelligence"
-
-command: pyright-langserver
-args: ["--stdio"]
-transport: stdio
-
-languages:
- - python
-
-capabilities:
- - diagnostics
- - hover
- - completions
- - definitions
- - references
- - rename
- - code_actions
- - formatting
- - signature_help
- - document_symbols
- - workspace_symbols
-
-initialization:
- python:
- pythonPath: "${PYTHON_PATH:/usr/bin/python3}"
- analysis:
- typeCheckingMode: "basic"
- autoSearchPaths: true
-
-actors:
- code_analyst:
- type: llm
- config:
- actor: anthropic/claude-3-opus
- system_prompt: |
- You are a Python code analyst. Use LSP tools to understand
- type information and identify issues in the codebase.
- skills:
- - local/file-ops
- lsp:
- - local/pyright
- - local/ruff-lsp
-
-actors:
- polyglot_reviewer:
- type: llm
- config:
- actor: openai/gpt-4
- lsp:
- languages:
- - python
- - typescript
- - rust
-
-actors:
- universal_developer:
- type: llm
- config:
- actor: anthropic/claude-3-opus
- system_prompt: |
- You are a software developer.
- lsp:
- auto: true
-
-actors:
- dynamic_analyst:
- type: llm
- config:
- actor: openai/gpt-4
- lsp:
- {% for lang in context.project_languages %}
- - {{ lsp_registry.for_language(lang) | first }}
- {% endfor %}
-
-actors:
- strategy_planner:
- type: llm
- config:
- actor: openai/gpt-4
- system_prompt: |
- Plan the implementation strategy. Use LSP diagnostics
- to assess codebase health before proposing changes.
- lsp:
- - local/pyright
- lsp_capabilities: # Restrict to read-only
- - diagnostics
- - hover
- - definitions
- - references
-
- code_implementer:
- type: llm
- config:
- actor: anthropic/claude-3-opus
- system_prompt: |
- Implement code changes. Use full LSP capabilities
- for navigation, diagnostics, and refactoring.
- lsp:
- auto: true
- lsp_capabilities: all # Full capabilities (default)
-
-routes:
- dev_workflow:
- type: graph
- entry_point: plan
- nodes:
- - name: plan
- type: agent
- agent: strategy_planner
- - name: implement
- type: agent
- agent: code_implementer
- edges:
- - source: plan
- target: implement
- - source: implement
- target: end
-
-actors:
- enriched_reviewer:
- type: llm
- config:
- actor: openai/gpt-4
- lsp:
- auto: true
- lsp_context_enrichment:
- diagnostics: true # Auto-inject diagnostics (default: true)
- type_annotations: false # Auto-inject type info (default: false)
- max_diagnostics_per_file: 50 # Limit to avoid context bloat
-
-# File: tools/run-migrations.yaml
-cleveragents:
- version: "3.0"
-
-tool:
- name: local/run-migrations
- description: "Run database migrations for the API service"
-
- source: custom # mcp | agent_skill | builtin | custom
-
- # Resource bindings — what resources this tool needs access to
- resources:
- db:
- type: local/database
- access: read_write
- required: true
- description: "Target database for migrations"
-
- input_schema:
- type: object
- properties:
- direction:
- type: string
- enum: [up, down]
- count:
- type: integer
- default: 1
- required: [direction]
-
- capability:
- writes: true
- write_scope:
- resource_slots: [db] # References the "db" resource slot
- checkpointable: true
- checkpoint_scope: transaction
- side_effects: [schema_mutation]
-
- code: |
- import subprocess
- direction = params["direction"]
- count = params.get("count", 1)
- db = ctx.resources["db"] # Access the bound database resource
- result = subprocess.run(
- ["alembic", direction, str(count)],
- capture_output=True, text=True, cwd=db.sandbox.root
- )
- return {"stdout": result.stdout, "returncode": result.returncode}
-
-# File: tools/create-github-issue.yaml
-cleveragents:
- version: "3.0"
-
-tool:
- name: local/create-github-issue
- description: "Create a GitHub issue via MCP"
-
- source: mcp
- mcp_server:
- command: "npx @anthropic/mcp-github"
- env:
- GITHUB_TOKEN: "${GITHUB_TOKEN}"
- tool_name: create_issue # The tool name as exposed by the MCP server
-
- capability:
- writes: true
- write_scope: [github:issues]
- checkpointable: false
-
-# File: tools/deploy-staging.yaml
-cleveragents:
- version: "3.0"
-
-tool:
- name: local/deploy-staging
- description: "Deploy the current branch to the staging environment"
-
- source: agent_skill
- agent_skill:
- path: ./skills/deploy-to-staging
- sandbox_policy: container
- allowed_tools: ["Bash(docker:*)", "Bash(kubectl:*)", "Read"]
-
- capability:
- writes: true
- checkpointable: false
- side_effects: [deploy, infrastructure]
-
-# Register a new tool from its YAML configuration
-agents tool add --config ./tools/run-migrations.yaml
-
-# Update an existing tool (re-reads the config file, overwrites registration)
-agents tool add --config ./tools/run-migrations.yaml --update
-
-# List all registered tools
-agents tool list
-
-# Show details for a tool (schema, capability, references)
-agents tool show local/run-migrations
-
-# Remove a tool
-agents tool remove local/run-migrations
-
-skill:
- name: local/my-skill
- tools:
- - local/run-migrations # Named tool reference
- - local/validate-api-compat # Named tool reference
-
- anonymous_tools: # Inline definitions, same format as tool YAML
- - description: "One-off data cleanup for this project"
- input_schema:
- type: object
- properties:
- table: { type: string }
- capability:
- writes: true
- checkpointable: true
- code: |
- # ... Python code ...
- return {"cleaned": count}
-
-nodes:
- - name: custom_step
- type: tool
- anonymous: true
- description: "Inline validation specific to this workflow"
- input_schema:
- type: object
- properties:
- data: { type: object }
- capability:
- read_only: true
- code: |
- # ... Python code ...
- return {"valid": True}
-
-skill:
- name: local/strict-devops
- tools:
- - name: local/run-migrations
- override:
- capability:
- human_approval_required: true # Override: require approval in this skill
- write_scope: [database:staging] # Override: restrict scope for this context
-
- - local/validate-api-compat # No overrides, use as registered
-
-nodes:
- - name: safe_migrate
- type: tool
- tool: local/run-migrations
- override:
- capability:
- human_approval_required: true
-
-skill:
- name: local/production-ops
- includes:
- - name: local/devops-toolkit
- tool_overrides:
- - tool: local/run-migrations
- override:
- capability:
- human_approval_required: true # In this context, require human approval
- write_scope: [database:production]
-
- - tool: local/create-github-issue
- override:
- capability:
- human_approval_required: true # Require approval in this context
-
-tool:
- name: local/run-migrations
- description: "Run database migrations"
- source: custom
-
- resources:
- db:
- type: local/database
- access: read_write
- required: true
- description: "Target database for migrations"
-
- capability:
- writes: true
- write_scope: [db:migrations] # References the "db" slot
- checkpointable: true
-
- code: |
- direction = params["direction"]
- db_resource = ctx.resources["db"] # Access the bound resource
- result = db_resource.handler.execute_migration(direction, db_resource.sandbox)
- return {"status": "ok"}
-
-tool:
- name: local/cross-repo-diff
- description: "Compare files across two git repositories"
- source: custom
-
- resources:
- source_repo:
- type: git-checkout
- access: read_only
- required: true
- description: "Source repository to compare from"
- target_repo:
- type: git-checkout
- access: read_only
- required: true
- description: "Target repository to compare against"
-
- capability:
- read_only: true
-
- code: |
- source = ctx.resources["source_repo"]
- target = ctx.resources["target_repo"]
- # ... compare files across repos ...
-
-resources:
- repo:
- type: git-checkout
- access: read_write
- # No `bind` field → contextual binding
-
-resources:
- docs:
- type: fs-mount
- access: read_only
- bind: local/company-docs # Static: always this resource
- description: "Company documentation corpus"
-
-resources:
- target:
- type: git-checkout
- access: read_only
- from_param: repository # Bound from the "repository" input parameter
- description: "Repository to analyze"
-
-input_schema:
- type: object
- properties:
- repository:
- type: string
- description: "Name of the registered resource to analyze"
- required: [repository]
-
- <style="color: cyan; font-weight: 600;">available_agent_skills>
- <style="color: cyan; font-weight: 600;">agent_skill>
- <style="color: cyan; font-weight: 600;">name>deploy-to-staging</style="color: cyan; font-weight: 600;">name>
- <style="color: cyan; font-weight: 600;">description>Deploy the current branch to the staging environment.</style="color: cyan; font-weight: 600;">description>
- <style="color: cyan; font-weight: 600;">tool>local/deploy-staging</style="color: cyan; font-weight: 600;">tool>
- </style="color: cyan; font-weight: 600;">agent_skill>
- </style="color: cyan; font-weight: 600;">available_agent_skills>
-
-read_file(path: str) -> str
-write_file(path: str, content: str) -> None
-edit_file(path: str, edits: list[Edit]) -> None
-delete_file(path: str) -> None
-move_file(source: str, destination: str) -> None
-copy_file(source: str, destination: str) -> None
-
-create_directory(path: str) -> None
-list_directory(path: str, pattern: str = "*") -> list[str]
-delete_directory(path: str, recursive: bool = False) -> None
-
-search_files(pattern: str, content_pattern: str = None) -> list[Match]
-find_definition(symbol: str) -> list[Location]
-find_references(symbol: str) -> list[Location]
-
-git_status() -> GitStatus
-git_diff(path: str = None) -> str
-git_log(count: int = 10) -> list[Commit]
-git_blame(path: str) -> list[BlameLine]
-
-capability:
- read_only: bool # Whether tool only performs read operations
- writes: bool # Whether tool can modify resources
- write_scope: # What the tool is allowed to mutate
- - file_paths: ["src/**", "tests/**"] # Path patterns within bound resources
- - resource_slots: ["repo", "db"] # Resource slot names (from resource bindings)
- - environment: # Execution environment compatibility
- required: container | host | any # Where the tool CAN run (default: any)
- preferred: container | host # Where the tool PREFERS to run (optional)
- specific: <resource-name> # A specific container required (optional)
- idempotent: bool # Whether repeated calls produce same result
- checkpointable: bool # Whether tool supports checkpoint/rollback
- checkpoint_scope: str # What can be rolled back (file, transaction, commit, snapshot)
- side_effects: # Non-reversible effects
- - install_packages
- - mutate_infra
- - send_email
- cost_profile: # Usage constraints
- rate_limit: "10/min"
- estimated_cost: "$0.01/call"
- human_approval_required: bool # Whether a human must approve invocation
-
-1. LLM generates tool call
- e.g., edit_file(path="src/main.py", changes=[...])
- or: local/github.create_issue(title="Bug fix", body="...")
- or: (activates Agent Skill "deploy-to-staging" via instructions)
- ↓
-2. Tool Router receives call
- - Resolves tool by name from the Tool Registry or actor's skill tool sets
- - Validates parameters against inputSchema
- - Checks capability metadata against plan's access policy:
- • Is this tool in allowed skill categories?
- • Does the plan allow writes?
- • Is human approval required?
- - If denied → return AccessDeniedError to LLM
- ↓
-3. Resource Binding Resolution & Sandbox Context
- - Resolve resource bindings for this tool:
- • Static bindings: already resolved at registration
- • Contextual bindings: resolve from plan's project resources
- • Parameter bindings: resolve from invocation arguments
- - Validate resource type compatibility for each slot
- - Validate access mode (e.g., read_write tool on read_only resource → error)
- - Ensure sandbox exists for each bound resource (lazy sandboxing)
- - Maps logical paths to sandbox-relative paths via bound resource handlers
- - Inject bound resources into ctx.resources[slot_name]
- - If tool is checkpointable → create pre-execution checkpoint
- ↓
-4. Adapter-Specific Execution
- - MCP: sends tools/call JSON-RPC to server process
- - Agent Skill: agent follows loaded SKILL.md instructions,
- running scripts and tools in sandboxed shell
- - Built-in: calls native Python implementation directly
- - Custom: executes inline code with sandboxed context
- ↓
-5. Change Recording
- - If tool modified resources → create Change record(s)
- - Append Change(s) to plan's ChangeSet
- - Update sandbox state
- - If checkpointable → record checkpoint for rollback
- ↓
-6. Result Return
- - Normalize result to uniform Result type
- - Return to LLM agent for continued reasoning
-
-class ToolExecutionContext:
- """Context provided to every tool execution, regardless of source."""
-
- def __init__(self, plan: Plan, sandbox: Sandbox,
- resources: dict[str, BoundResource]):
- self.plan = plan
- self.sandbox = sandbox
- self.resources = resources # slot_name → BoundResource
- self.changes: list[Change] = []
-
- def record_change(self, change: Change) -> None:
- """Record a change made by a tool."""
- self.changes.append(change)
- self.plan.changeset.add_change(change)
-
-
-class WriteFileTool:
- """Example: built-in tool for writing files."""
-
- def execute(self, path: str, content: str, ctx: ToolExecutionContext) -> None:
- handler = ctx.sandbox.get_handler(path)
- change = handler.write(path, content, ctx.sandbox)
- ctx.record_change(change)
-
-# Before sending to MCP server:
-# Logical path: "src/main.py"
-# Sandbox path: "/tmp/sandbox-01HXM/worktree/src/main.py"
-# The adapter rewrites the tool arguments so the MCP server
-# operates on sandboxed state without knowing about the sandbox.
-
-Agent Skill Tool: "local/deploy-staging"
- SKILL.md instructions:
- 1. Run tests using the built-in shell tool
- 2. Create a PR using the GitHub MCP tool (create_pull_request)
- 3. Wait for CI using the GitHub MCP tool (get_check_runs)
- 4. Deploy using the AWS MCP tool (ecs_update_service)
- 5. Verify deployment using the HTTP MCP tool (fetch_url)
-{
- "passed": true,
- "message": "All 247 tests passed, 94% coverage",
- "data": {
- "tests_run": 247,
- "tests_passed": 247,
- "tests_failed": 0,
- "coverage_percent": 94.2,
- "coverage_threshold": 80,
- "duration_seconds": 12.4
- }
-}
-
-$ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90
-$ agents validation attach --project local/staging-api local/api-repo local/run-tests --coverage-threshold 70
-
- agents plan prompt <plan_id> "Try using mock objects for the database tests"
-
-validate → fail → fix → re-validate → fail → fix → re-validate → ... → retry limit
- → request strategy revision → re-strategize → re-execute → validate
- → still failing → escalate to user → user provides guidance → resume
- → still failing → plan fails
-
-# Actor graph with explicit validation nodes
-graph:
- nodes:
- - name: implement
- type: agent
- actor: local/code-writer
- - name: run_tests
- type: tool
- tool: local/run-tests # This is a Validation (subtype of Tool)
- - name: lint_check
- type: tool
- tool: local/lint-check # Also a Validation
- - name: fix_issues
- type: agent
- actor: local/code-fixer
- edges:
- - [implement, run_tests]
- - [implement, lint_check]
- - condition: "not run_tests.passed or not lint_check.passed"
- from: [run_tests, lint_check]
- to: fix_issues
- - [fix_issues, run_tests] # Retry loop
- - [fix_issues, lint_check]
-
-# Skill: local/python-quality
-skill:
- name: local/python-quality
- description: "Python code quality tools and validations"
- tools:
- - local/run-tests # Validation (required)
- - local/lint-check # Validation (required)
- - local/type-check # Validation (required)
- - local/format-code # Plain Tool (writes)
- - local/run-benchmarks # Validation (informational)
-
-# validations/tests-pass.yaml
-# Wraps the existing local/run-tests tool — no test logic duplicated
-
-name: local/tests-pass
-description: "Validate that all unit tests pass (wraps local/run-tests)"
-
-wraps: local/run-tests
-
-transform: |
- def transform(tool_output):
- passed = tool_output.get("returncode") == 0
- return {
- "passed": passed,
- "message": "All tests passed" if passed else f"Tests failed (exit {tool_output.get('returncode')})",
- "data": tool_output
- }
-
-validation:
- mode: required
-
-timeout: 600
-
-def transform(tool_output) -> dict:
- """
- Args:
- tool_output: The wrapped Tool's return value. The type depends on the
- Tool's implementation — typically a dict (for JSON-returning
- tools) but may be a string or other type.
- Returns:
- A dict with at minimum {"passed": bool}. May also include
- "message" (str) and "data" (any).
- """
-
-# Example: Validation wraps local/run-tests but renames arguments
-name: local/tests-pass
-wraps: local/run-tests
-
-argument_mapping:
- test_directory: source_dir # Forward Validation's "source_dir" → Tool's "test_directory"
- coverage_enabled: true # Always pass true for coverage_enabled
- verbose: false # Always pass false for verbose
-
-transform: |
- def transform(tool_output):
- return {"passed": tool_output.get("returncode") == 0, "message": "Tests completed"}
-
-validation:
- mode: required
-
-# The base tool runs tests and produces a comprehensive report
-# Tool: local/run-tests (already registered)
-
-# Validation 1: All tests must pass (required)
-# validations/tests-pass.yaml
-name: local/tests-pass
-description: "All unit tests must pass"
-wraps: local/run-tests
-transform: |
- def transform(tool_output):
- return {
- "passed": tool_output.get("returncode") == 0,
- "message": f"{tool_output.get('tests_passed', 0)}/{tool_output.get('tests_run', 0)} tests passed",
- "data": tool_output
- }
-validation:
- mode: required
-
-# Validation 2: Coverage must exceed threshold (informational for now)
-# validations/coverage-check.yaml
-name: local/coverage-check
-description: "Coverage must exceed threshold (advisory)"
-wraps: local/run-tests
-transform: |
- def transform(tool_output):
- coverage = tool_output.get("coverage_percent", 0)
- threshold = 80
- return {
- "passed": coverage >= threshold,
- "message": f"Coverage: {coverage}% (threshold: {threshold}%)",
- "data": {"coverage_percent": coverage, "threshold": threshold}
- }
-validation:
- mode: informational
-
-{
- "validation": "local/run-tests",
- "mode": "required",
- "passed": true,
- "message": "All 247 tests passed, 94% coverage",
- "data": {
- "tests_run": 247,
- "tests_passed": 247,
- "coverage_percent": 94.2
- },
- "duration_ms": 12400,
- "attempt": 2,
- "attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0",
- "attachment_resource": "local/api-repo",
- "attachment_scope": "project",
- "attachment_scope_target": "local/api-service"
-}
-
-# 1. Define validation YAML files
-# (see Configuration > Validation Configuration Files for schema and examples)
-
-# 2. Register validations
-agents validation add --config ./validations/run-tests.yaml
-agents validation add --config ./validations/lint-check.yaml
-agents validation add --config ./validations/type-check.yaml
-agents validation add --config ./validations/check-bundle-size.yaml
-
-# 3. Attach to resource through a project (active only when this resource is accessed through this project)
-agents validation attach --project local/api-service local/api-repo local/run-tests
-agents validation attach --project local/api-service local/api-repo local/type-check
-agents validation attach --project local/api-service local/api-repo local/check-bundle-size
-
-# 4. Attach directly to a resource (always active for any plan accessing this resource)
-agents validation attach local/api-repo local/lint-check
-
-# 5. Verify setup
-agents tool list --type validation --namespace local
-agents tool show local/run-tests
-
-# 6. Run a plan — validations execute automatically at end of Execute phase
-agents plan use local/implement-feature local/api-service
-
-# File: skills/devops-toolkit.yaml
-cleveragents:
- version: "3.0"
-
-skill:
- name: local/devops-toolkit
- description: "Full-stack development tools for file ops, git, GitHub, and deployment"
-
- # ── Named Tool References ───────────────────────────────
- # Reference independently registered tools by name.
- # These tools must already be registered via `agents tool add`.
- # Optional metadata overrides can be applied per tool.
- tools:
- - local/run-migrations # Simple reference, use as registered
- - name: local/deploy-staging # Reference with metadata override
- override:
- capability:
- human_approval_required: true # Require approval in this skill context
-
- # ── Include other skills ─────────────────────────────────
- # All tools from included skills become part of this skill.
- # Included skills must already be registered in the system.
- # Individual tools from included skills can have metadata overridden.
- includes:
- - local/file-ops # built-in file + directory + search tools
- - local/git-ops # built-in git tools
- - name: local/github # MCP-based GitHub tools, with per-tool overrides
- tool_overrides:
- - tool: local/create-github-issue
- override:
- capability:
- write_scope: [github:issues:org-only]
-
- # ── MCP Server Tools ─────────────────────────────────────
- # Connect to MCP servers and expose their tools.
- # Tools discovered from MCP servers are auto-registered in the
- # Tool Registry if not already present.
- mcp_servers:
- - name: linear
- command: "npx @anthropic/mcp-linear"
- env:
- LINEAR_API_KEY: "${LINEAR_API_KEY}"
- # Optional: override inferred capability metadata per tool
- overrides:
- - tool: create_issue
- writes: true
- write_scope: [linear:issues]
- - tool: list_issues
- read_only: true
-
- # ── Agent Skills (SKILL.md folders) ──────────────────────
- # Each Agent Skill folder is loaded as a composite tool.
- # The agent discovers it via metadata, activates it by
- # loading SKILL.md instructions, and follows them.
- agent_skills:
- - path: ./skills/code-review-checklist
- sandbox_policy: none
-
- # ── Built-in Tool Groups ─────────────────────────────────
- # Opt-in to built-in tool groups provided by CleverAgents.
- builtins:
- - group: shell_operations
-
- # ── Anonymous Tools ──────────────────────────────────────
- # Inline tool definitions for one-off, skill-specific operations.
- # Same format as a named tool YAML body but without a name.
- # These are NOT registered in the Tool Registry and are NOT reusable.
- anonymous_tools:
- - description: "One-off cleanup for legacy migration artifacts"
- input_schema:
- type: object
- properties:
- directory: { type: string }
- capability:
- writes: true
- checkpointable: true
- checkpoint_scope: file
- code: |
- import os, glob
- directory = params["directory"]
- removed = []
- for f in glob.glob(os.path.join(ctx.sandbox.root, directory, "*.legacy")):
- os.remove(f)
- removed.append(f)
- return {"removed": removed, "count": len(removed)}
-
-# File: skills/file-ops.yaml
-cleveragents:
- version: "3.0"
-
-skill:
- name: local/file-ops
- description: "File and directory operations"
-
- builtins:
- - group: file_operations # read, write, edit, delete, move, copy
- - group: directory_operations # create, list, delete dirs
-
-# File: skills/github.yaml
-cleveragents:
- version: "3.0"
-
-skill:
- name: local/github
- description: "GitHub operations via MCP"
-
- mcp_servers:
- - name: github
- command: "npx @anthropic/mcp-github"
- env:
- GITHUB_TOKEN: "${GITHUB_TOKEN}"
- overrides:
- - tool: create_issue
- writes: true
- write_scope: [github:issues]
- checkpointable: false
- - tool: create_pull_request
- writes: true
- write_scope: [github:pulls]
- checkpointable: false
- - tool: list_repos
- read_only: true
- - tool: get_file_contents
- read_only: true
-
-local/full-stack-dev
- ├── includes: local/file-ops
- │ └── builtins: file_operations, directory_operations
- ├── includes: local/git-ops
- │ └── builtins: git_operations
- ├── includes: local/github
- │ └── mcp_servers: github (create_issue, create_pr, list_repos, ...)
- ├── agent_skills: code-review-checklist
- └── tools: local/run-migrations, local/deploy-staging (named tool refs)
-
- Flattened tool set available to actors referencing local/full-stack-dev:
- read_file, write_file, edit_file, delete_file, move_file, copy_file,
- create_directory, list_directory, delete_directory,
- git_status, git_diff, git_log, git_blame,
- create_issue, create_pr, list_repos, get_file_contents,
- code-review-checklist (agent skill),
- local/run-migrations, local/deploy-staging (named tools)
-
-# First, register any named tools the skill will reference
-agents tool add --config ./tools/run-migrations.yaml
-agents tool add --config ./tools/deploy-staging.yaml
-
-# Then register the skill (which references those tools by name)
-agents skill add --config ./skills/devops-toolkit.yaml
-
-# Update an existing skill (re-reads the config file, overwrites registration)
-agents skill add --config ./skills/devops-toolkit.yaml --update
-
-# List all registered skills
-agents skill list
-
-# Show details for a skill (tools, includes, metadata)
-agents skill show local/devops-toolkit
-
-# List all tools provided by a skill (flattened, including from child skills)
-agents skill tools local/devops-toolkit
-
-# Remove a skill
-agents skill remove local/devops-toolkit
-
-# File: actors/code-assistant.yaml
-cleveragents:
- version: "3.0"
- default_actor: code_assistant
-
-actors:
- code_assistant:
- type: llm
- config:
- actor: anthropic/claude-3-opus
- temperature: 0.3
- system_prompt: |
- You are a code assistant with access to file, git, and GitHub tools.
- Current task: {{ context.task_description }}
-
- # Reference skills by fully-qualified name.
- # All tools from these skills become available to this actor.
- skills:
- - local/file-ops
- - local/git-ops
- - local/github
-
- # Or reference a single composite skill that includes all of the above
- full_stack_assistant:
- type: llm
- config:
- actor: anthropic/claude-3-opus
- system_prompt: |
- You are a full-stack development assistant.
-
- skills:
- - local/full-stack-dev # includes file-ops, git-ops, github, etc.
-
-skills:
- - dev:freemo/custom-analysis # from dev server, personal namespace
- - prod:cleverthis/deploy-tools # from prod server, org namespace
- - local/file-ops # local skill
-
-# A subtype that inherits from container-instance
-name: devcontainer-instance
-inherits: container-instance
-description: "A container provisioned from a devcontainer.json configuration"
-
-# Only fields that differ from or extend container-instance need to be declared.
-# All other fields (capabilities, sandbox_strategy, child_types, etc.) are inherited.
-cli_args:
- # Inherited args from container-instance remain available.
- # Additional args specific to devcontainer:
- - name: config-path
- type: path
- required: false
- description: "Path to .devcontainer/devcontainer.json or .devcontainer/ directory"
-
-handler:
- class: DevcontainerHandler
- module: cleveragents.resource.handlers.devcontainer
-
-# 1) Checked-out git repo (has local files on disk)
-agents resource add git-checkout local/acme-app \
- --path /home/alice/projects/acme-dashboard --branch main
-
-# 2) Git repo via remote URL (no local checkout — metadata only)
-agents resource add git local/acme-upstream \
- --url git@github.com:acmecorp/dashboard.git
-
-# 3) Standalone directory (not a git repo — just files on disk)
-agents resource add fs-directory local/acme-deploy \
- --path /opt/deploy/acme-dashboard
-
-# File: resource-types/database.yaml
-cleveragents:
- version: "3.0"
-
-resource_type:
- name: local/database
- description: "A SQL database (PostgreSQL, MySQL, SQLite, etc.)"
- physical_or_virtual: physical
- user_addable: true
-
- # CLI arguments for `agents resource add local/database`
- cli_arguments:
- - name: connection-string
- type: string
- required: true
- description: "Database connection string (e.g., postgresql://host/dbname)"
- validation:
- pattern: "^(postgresql|mysql|sqlite)://"
- - name: schema
- type: string
- required: false
- description: "Default schema to use"
- - name: read-only
- type: boolean
- required: false
- default: false
- description: "Whether the database should be treated as read-only"
-
- # Sandbox and handler
- sandbox_strategy: transaction_rollback
- handler: DatabaseHandler
- checkpointable: true
-
- # Allowed parent types (empty means can be top-level)
- allowed_parent_types: []
-
- # Child types
- child_types:
- - type: local/db-schema
- auto_discover: true
- manual_link: false
- description: "Discovered database schemas"
- - type: local/db-table
- auto_discover: true
- manual_link: false
- description: "Discovered tables within schemas"
-
- # Capabilities
- capabilities:
- readable: true
- writable: true
- sandboxable: true
- checkpointable: true
-
-agents resource type add --config ./resource-types/database.yaml
-# Now available: agents resource add local/database <NAME> --connection-string CONN [--schema SCHEMA] [--read-only]
-
-# Register a checked-out git repository (most common)
-agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
-# Auto-discovers: git child (repo metadata, remotes, branches, commits, tree entries)
-# + fs-directory child (worktree root directory, subdirectories, files)
-
-# Register a git repo via remote URL (no local checkout — exists on remote server)
-agents resource add git local/upstream --url git@github.com:org/upstream.git
-# Auto-discovers: remotes, branches, tags, commits, trees, tree entries, stashes, submodules
-# (no fs-directory — not checked out locally)
-
-# Register a standalone directory (not a git repo — just files on disk)
-agents resource add fs-directory local/docs --path /opt/docs/api-reference
-# Auto-discovers: subdirectories, files, symlinks, hardlinks
-
-# Register a standalone filesystem mount (entire volume)
-agents resource add fs-mount local/data-volume --mount-path /mnt/data
-# Auto-discovers: root fs-directory, subdirectories, files, symlinks, hardlinks
-
-# Link resources to projects (resources must be registered first)
-agents project link-resource local/api-service local/api-repo
-agents project link-resource local/api-service local/docs --read-only
-
-class ResourceHandler(Protocol):
- """Handler for a specific resource type."""
-
- def read(self, path: str, sandbox: Sandbox) -> Content:
- """Read content from the sandboxed resource."""
- ...
-
- def write(self, path: str, content: Content, sandbox: Sandbox) -> Change:
- """Write content and return the Change record."""
- ...
-
- def delete(self, path: str, sandbox: Sandbox) -> Change:
- """Delete resource and return the Change record."""
- ...
-
- def list(self, pattern: str, sandbox: Sandbox) -> list[str]:
- """List paths matching pattern."""
- ...
-
- def diff(self, path: str, sandbox: Sandbox) -> str:
- """Generate diff between sandbox and original state."""
- ...
-
- def supports_operation(self, operation: OperationType) -> bool:
- """Check if this resource supports the given operation."""
- ...
-
- def discover_children(self, resource: ResourceRecord) -> list[ResourceRecord]:
- """Auto-discover child resources (called at registration and refresh)."""
- ...
-
- def content_hash(self, path: str, sandbox: Sandbox) -> str:
- """Compute content hash for identity tracking."""
- ...
-
- def create_sandbox(self, resource: ResourceRecord) -> Sandbox:
- """Create a sandbox for this resource using its type's strategy."""
- ...
-
- def create_checkpoint(self, sandbox: Sandbox) -> Checkpoint:
- """Create a checkpoint within the sandbox."""
- ...
-
- def rollback_to(self, sandbox: Sandbox, checkpoint: Checkpoint) -> None:
- """Roll back sandbox state to a checkpoint."""
- ...
-
- def project_access(
- self,
- binding_resource: ResourceRecord,
- target_resource: ResourceRecord,
- containment_path: list[ResourceRecord],
- sandbox: Sandbox | None,
- ) -> AccessProjection | None:
- """Compute how to reach target_resource from binding_resource.
-
- Returns an AccessProjection with access_path, protocol,
- crosses_sandbox flag, and read_richness score. Returns None
- if this handler cannot project access to the target type.
- Used by the tool reachability and read/write routing system.
- """
- ...
-
-# Explicit slot reference
-path://repo/src/main.py → routes to the "repo" slot's bound resource
-path://docs/api/readme.md → routes to the "docs" slot's bound resource
-
-# Default: unqualified paths route to the tool's primary resource slot
-src/main.py → routes to the first (or only) resource slot
-
-DetailDepth = int # Non-negative integer, 0 = most minimal, no upper bound
-
-@dataclass
-class DetailLevelMap:
- """Maps named detail levels to integer depths for a UKO domain.
- Inherited: a child map includes all entries from its parent map,
- and may insert additional levels at any integer position."""
- domain: str # UKO namespace (e.g., "uko-code:", "uko-py:")
- parent: DetailLevelMap | None # Parent map to inherit from
- levels: dict[str, int] # Named level -> integer depth
- max_depth: int # Maximum meaningful depth for this domain
-
- def resolve(self, depth: int | str) -> int:
- """Resolve a named level or integer to an integer depth."""
- if isinstance(depth, int):
- return min(depth, self.max_depth)
- # Look up named level in this map, then parent maps
- if depth in self.levels:
- return self.levels[depth]
- if self.parent:
- return self.parent.resolve(depth)
- raise ValueError(f"Unknown detail level: {depth}")
-
-@dataclass
-class ContextRequest:
- """A structured request for context, issued by an actor or skill."""
-
- # === What to find ===
- query: str | None = None # Natural language query
- entities: list[str] = field(default_factory=list) # Named entities to focus on
- uko_types: list[str] = field(default_factory=list) # UKO types to filter
-
- # === Scope control ===
- focus: list[str] = field(default_factory=list)
- # URIs or identifiers of specific items to focus on
-
- breadth: int = 2
- # How many hops outward in the dependency/reference graph.
-
- depth: int | str = 3
- # How much detail to include for each item found.
- # May be a raw integer (0-N) or a named level string (e.g., "SIGNATURES")
- # resolved via the active DetailLevelMap for the target node's UKO type.
-
- # === Focus depth gradient ===
- depth_gradient: bool = True
- # When True, items closer to the focus get more detail.
-
- # === Temporal scope ===
- temporal: TemporalScope = TemporalScope.CURRENT
-
- # === Budget ===
- max_tokens: int | None = None
-
- # === Strategy hints ===
- preferred_strategies: list[str] = field(default_factory=list)
- required_backends: list[str] = field(default_factory=list)
-
- # === Priority and purpose ===
- priority: float = 0.5 # 0.0 = background, 1.0 = critical
- purpose: str = "" # Why is this context needed?
-
-@dataclass
-class ContextFragment:
- """A single piece of context assembled by a strategy."""
- uko_node: str # UKO URI of the source node
- content: str # Rendered text content
- detail_depth: int # Resolved integer depth of this fragment
- token_count: int # Token count of content
- relevance_score: float # 0.0-1.0 relevance to the request
- provenance: FragmentProvenance # Trace back to resource + location
- metadata: dict = field(default_factory=dict)
-
-@dataclass
-class AssembledContext:
- """The fused, budget-respecting context payload."""
- fragments: list[ContextFragment] # Ordered context fragments
- total_tokens: int # Total token count
- budget_used: float # Fraction of budget consumed (0.0-1.0)
- strategies_used: list[str] # Which strategies contributed
- context_hash: str # Cryptographic hash for snapshot
- preamble: str | None # Optional structure summary
- provenance_map: dict # Fragment -> resource/location mapping
- skeleton_fragments: tuple[ContextFragment, ...] = () # Compressed parent context for child plan inheritance
-# Built-in skill, always available
-skill:
- name: builtin/context
- description: "Request additional context during reasoning"
-
- anonymous_tools:
- - name: request_context
- description: "Request specific context to be added to the conversation"
- input_schema:
- type: object
- properties:
- query: { type: string, description: "What information do you need?" }
- focus: { type: array, items: { type: string },
- description: "Specific files, classes, or functions to focus on" }
- breadth: { type: integer, default: 2,
- description: "How many dependency hops outward (0-5)" }
- depth: { oneOf: [{ type: integer, minimum: 0 }, { type: string }],
- default: 3,
- description: "Detail depth — integer (0-N) or named level from the active DetailLevelMap (e.g., 'SIGNATURES', 'FULL_SOURCE')" }
- purpose: { type: string, description: "Why do you need this context?" }
- required: [purpose]
-
- - name: query_history
- description: "Query historical context about past decisions and changes"
- input_schema:
- type: object
- properties:
- query: { type: string }
- scope: { type: string, enum: ["current_plan", "plan_tree", "all_plans"],
- default: "plan_tree" }
- required: [query]
-
- - name: get_context_budget
- description: "Check remaining context token budget"
- input_schema:
- type: object
- properties: {}
-@runtime_checkable
-class ContextStrategy(Protocol):
- """A pluggable context assembly strategy."""
-
- @property
- def name(self) -> str: ...
-
- @property
- def capabilities(self) -> StrategyCapabilities: ...
-
- def can_handle(self, request: ContextRequest,
- backends: BackendSet) -> float:
- """Returns 0.0-1.0 confidence that this strategy can usefully
- contribute to this request."""
- ...
-
- def assemble(self, request: ContextRequest,
- backends: BackendSet,
- budget: int,
- plan_context: PlanContext) -> list[ContextFragment]:
- """Execute the strategy. Must respect the budget."""
- ...
-
- def explain(self) -> str: ...
-@dataclass
-class StrategyCapabilities:
- """Declares what a strategy is capable of."""
- uses_text: bool = False
- uses_vector: bool = False
- uses_graph: bool = False
- uses_temporal: bool = False
- uko_levels: list[str] = field(default_factory=list)
- resource_types: list[str] = field(default_factory=list)
- supports_depth_breadth: bool = False
- supports_plan_hierarchy: bool = False
- supports_temporal: bool = False
- quality_score: float = 0.5
-[context.strategies]
-enabled = ["simple-keyword", "semantic-embedding", "arce", "breadth-depth-navigator"]
-
-[context.strategies.custom]
-"my-domain-strategy" = "my_package.strategies.DomainStrategy"
-
-# Pipeline component overrides (see Architecture > ACMS > Context Assembly Pipeline)
-[context.pipeline]
-strategy-selector = "builtin:ConfidenceWeightedSelector" # default
-budget-allocator = "builtin:ProportionalBudgetAllocator" # default
-fragment-scorer = "my_extensions.scorers:DomainAwareScorer" # custom override
-
-Request: focus=["class://AuthManager"], breadth=2, depth=9 (FULL_SOURCE), gradient=True
-
-Result (token costs approximate):
-
-Distance 0 — depth 9 (FULL_SOURCE):
- class AuthManager: # 800 tokens
- """Manages user authentication..."""
- def authenticate(self, username, password):
- ...full body...
- def validate_token(self, token):
- ...full body...
-
-Distance 1 — depth 4 (SIGNATURES):
- class BaseManager: # 120 tokens
- def connect(self) -> Connection: ...
- def disconnect(self) -> None: ...
- class CryptoUtils: # 80 tokens
- def hash_password(pwd: str) -> str: ...
- def verify_hash(pwd: str, hash: str) -> bool: ...
- class UserDB: # 100 tokens
- def find_user(username: str) -> User | None: ...
- def create_user(user: User) -> None: ...
-
-Distance 2 — depth 0 (MODULE_LISTING):
- class Connection # 20 tokens
- class User # 15 tokens
- class DatabasePool # 15 tokens
-
-Total: ~1,150 tokens (vs ~15,000 if everything were depth 9)
-
-Request: focus=["uko-doc:section/security-architecture"], breadth=2, depth=10 (FULL_CONTENT), gradient=True
-
-Result (token costs approximate):
-
-Distance 0 — depth 10 (FULL_CONTENT):
- ## 5. Security Architecture # 2,400 tokens
- Complete section text including all paragraphs,
- code examples, diagrams, and subsections:
- 5.1 Authentication Flow
- 5.2 Authorization Model
- 5.3 Token Management
-
-Distance 1 — depth 6 (TOPIC_SENTENCES — sections that discuss security topics):
- ## 3. API Design # 180 tokens
- Section headings + first sentence of each paragraph:
- "The API uses JWT tokens for authentication..."
- "Rate limiting is enforced per-client..."
- ## 8. Deployment # 120 tokens
- "TLS termination occurs at the load balancer..."
- "Secrets are injected via Vault..."
-
-Distance 2 — depth 0 (TITLE_ONLY — sections referenced by distance-1 sections):
- ## 2. System Overview # 30 tokens
- ## 9. Monitoring # 25 tokens
- ## Appendix A: Threat Model # 20 tokens
-
-Total: ~2,775 tokens (vs ~18,000 if the entire document were depth 10)
-
-Request: focus=["uko-data:table/auth.users"], breadth=2, depth=11 (FULL_CATALOG), gradient=True
-
-Result (token costs approximate):
-
-Distance 0 — depth 11 (FULL_CATALOG):
- CREATE TABLE auth.users ( # 650 tokens
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
- email VARCHAR(255) UNIQUE NOT NULL,
- password_hash VARCHAR(60) NOT NULL,
- ...complete DDL + triggers + sample rows + statistics...
- );
-
-Distance 1 — depth 7 (DDL — tables with foreign keys to/from users):
- CREATE TABLE auth.sessions ( # 180 tokens
- id UUID PRIMARY KEY,
- user_id UUID REFERENCES auth.users(id),
- ...DDL with constraints...
- );
- CREATE TABLE auth.roles ( # 120 tokens
- ...DDL with constraints...
- );
- CREATE VIEW auth.active_users AS ... # 90 tokens
-
-Distance 2 — depth 1 (TABLE_LISTING — tables referenced by distance-1 tables):
- auth.permissions # 20 tokens
- auth.audit_log # 15 tokens
- public.organizations # 15 tokens
-
-Total: ~1,090 tokens (vs ~8,500 if the entire schema were depth 11)
-
-Plan Lifecycle ACMS Actions
-───────────────── ────────────────────────────
-Plan created (agents plan use) ResourceScope resolved.
- ScopedBackendViews created.
-
-Strategize phase begins InitialContextAssembler runs:
- - Inherits parent context (if subplan)
- - Runs Context Assembly Pipeline
- - Produces AssembledContext
- - Injects into actor's system prompt
-
-Strategy actor reasons Actor may issue ContextRequests via
- builtin/context skill.
- Each request triggers re-assembly
- with remaining budget.
-
-Strategy actor produces decisions Each Decision's context_snapshot
- captures AssembledContext hash +
- provenance map.
-
-Execute phase begins New InitialContextAssembler run
- with execute-phase view.
- Decisions from Strategize are in
- warm tier.
-
-Execution actor works Dynamic ContextRequests as needed.
-
-Subplan spawned PlanContextInheritance computes
- child context from parent.
- SkeletonCompressor propagates parent
- context as skeleton.
- New ResourceScope (possibly narrower).
-
-Apply phase Minimal context assembly
- (validation results, diff summary).
-
-Plan completes Hot context archived to warm.
- Warm context ages to cold based
- on retention policy.
-
-class OutputSession:
- """A live output document that coordinates element production and materialization.
-
- The session manages the lifecycle of all output elements for a single command
- invocation. It is the bridge between format-agnostic producer code and the
- format-specific materialization strategy.
-
- Thread Safety:
- The session is thread-safe. Multiple producers may create and write to
- handles concurrently. The session serializes event delivery to the
- materialization strategy using an internal event queue.
-
- Lifecycle:
- session = OutputSession.open(command, strategy)
- handle_a = session.panel("Title") # create handles
- handle_b = session.table("Results", ...)
- handle_a.set_entry(...) # write to handles (concurrent OK)
- handle_b.add_row(...)
- handle_a.close() # close handles when done
- handle_b.close()
- session.close() # finalize the session
- """
-
- # --- Session lifecycle ---
-
- command: str # The command that owns this session
- session_id: str # Unique session identifier (ULID)
- created_at: datetime # Session creation timestamp
-
- _strategy: MaterializationStrategy # The active materialization strategy
- _handles: OrderedDict[str, ElementHandle] # handle_id → handle, in declaration order
- _event_queue: asyncio.Queue[ElementEvent] # Internal event queue for serialization
- _state: SessionState # "open" | "closing" | "closed"
- _lock: threading.Lock # Protects handle creation/removal
-
- @classmethod
- def open(cls, command: str, strategy: MaterializationStrategy,
- metadata: dict | None = None) -> "OutputSession":
- """Open a new output session.
-
- Called by the CLI framework before command execution. The strategy is
- selected based on the resolved format (see Format Resolution).
-
- Args:
- command: The command string (e.g., "project show").
- strategy: The materialization strategy for the active format.
- metadata: Optional command metadata (user, timestamp, etc.).
-
- Returns:
- A new OutputSession ready for element creation.
- """
- ...
-
- # --- Element handle factories ---
- # Each factory creates a typed handle, registers it with the session in
- # declaration order, and emits an ElementCreated event to the strategy.
-
- def panel(self, title: str, *,
- border_style: str = "rounded",
- priority: str = "normal",
- collapse_hint: str = "auto",
- metadata: dict | None = None) -> "PanelHandle":
- """Create a panel element handle for key-value pair output."""
- ...
-
- def table(self, title: str | None, *,
- columns: list["ColumnDef"],
- summary: dict | None = None,
- max_rows_hint: int | None = None,
- sort_key: str | None = None,
- priority: str = "normal",
- collapse_hint: str = "auto",
- metadata: dict | None = None) -> "TableHandle":
- """Create a table element handle for tabular data."""
- ...
-
- def tree(self, root_label: str, *,
- root_style: str | None = None,
- max_depth_hint: int | None = None,
- show_guides: bool = True,
- priority: str = "normal",
- collapse_hint: str = "auto",
- metadata: dict | None = None) -> "TreeHandle":
- """Create a tree element handle for hierarchical data."""
- ...
-
- def progress(self, label: str, *,
- total: int | None = None,
- indeterminate: bool = False,
- steps: list[str] | None = None,
- priority: str = "normal",
- metadata: dict | None = None) -> "ProgressHandle":
- """Create a progress indicator handle.
-
- Args:
- label: Display label for the progress indicator.
- total: Total units of work (None for indeterminate).
- indeterminate: If True, show a spinner instead of a progress bar.
- steps: Named steps to track (creates ProgressStep objects with
- initial status "pending").
- """
- ...
-
- def status(self, message: str, *,
- level: str = "info",
- detail: str | None = None,
- priority: str = "normal",
- metadata: dict | None = None) -> "StatusHandle":
- """Create a status message handle."""
- ...
-
- def text(self, content: str = "", *,
- wrap: bool = True,
- indent: int = 0,
- priority: str = "normal",
- metadata: dict | None = None) -> "TextHandle":
- """Create a text block handle."""
- ...
-
- def code(self, content: str = "", *,
- language: str | None = None,
- line_numbers: bool = False,
- highlight_lines: list[int] | None = None,
- priority: str = "normal",
- metadata: dict | None = None) -> "CodeHandle":
- """Create a code block handle."""
- ...
-
- def diff(self, *,
- file_a: str | None = None,
- file_b: str | None = None,
- priority: str = "normal",
- metadata: dict | None = None) -> "DiffHandle":
- """Create a diff block handle."""
- ...
-
- def separator(self, style: str = "line") -> "SeparatorHandle":
- """Create a visual separator. Separators are auto-closed on creation."""
- ...
-
- def action_hint(self, commands: list[str],
- description: str | None = None) -> "ActionHintHandle":
- """Create an action hint. Action hints are auto-closed on creation."""
- ...
-
- # --- Session operations ---
-
- def snapshot(self) -> "StructuredOutput":
- """Return a static snapshot of all elements accumulated so far.
-
- The snapshot captures the current state of every handle (open or closed)
- as a StructuredOutput object. This is used by accumulate-mode strategies
- (json/yaml) at session end, and is available at any time for logging,
- debugging, or programmatic inspection.
- """
- ...
-
- def close(self, *, exit_code: int = 0) -> "StructuredOutput":
- """Close the session and finalize all output.
-
- Any handles still open are force-closed (with a warning logged).
- Emits a SessionEnd event to the strategy. Returns the final
- StructuredOutput snapshot.
-
- Args:
- exit_code: The command's exit code (included in the snapshot).
-
- Returns:
- The final StructuredOutput snapshot.
- """
- ...
-
- # --- Context manager support ---
-
- def __enter__(self) -> "OutputSession":
- return self
-
- def __exit__(self, exc_type, exc_val, exc_tb) -> None:
- """Auto-close session on context exit.
-
- If exiting due to an exception, sets exit_code to 1 and emits an
- error status element before closing.
- """
- ...
-
-class ElementHandle(Generic[E]):
- """Base class for all element handles.
-
- An element handle is a write-only view of an output element. Producers use
- handles to incrementally build element content without knowledge of the
- active format or materialization strategy.
-
- Type Parameter:
- E: The OutputElement subclass this handle wraps (e.g., Panel, Table).
-
- Thread Safety:
- Individual handle methods are thread-safe. Multiple threads may call
- methods on *different* handles concurrently. Concurrent writes to the
- *same* handle are serialized via an internal lock.
-
- Lifecycle:
- handle = session.table(...) # Created by session factory
- handle.add_row(...) # Write operations (zero or more)
- handle.close() # Finalize (required unless auto-closed)
-
- Closed Handle Behavior:
- Calling any write method on a closed handle raises ElementClosedError.
- """
-
- handle_id: str # Unique handle identifier (ULID)
- element_type: str # Semantic type ("panel", "table", etc.)
- declaration_index: int # Position in session's declaration order
-
- _session: OutputSession # Owning session (for event emission)
- _element: E # The accumulated element state
- _state: HandleState # "open" | "closed"
- _lock: threading.Lock # Serializes writes to this handle
-
- def close(self) -> None:
- """Close this handle, signaling that no more data will be written.
-
- Emits an ElementClosed event to the materialization strategy.
- For buffered strategies, this triggers rendering of the element.
- """
- ...
-
- @property
- def is_open(self) -> bool:
- """Whether this handle is still accepting writes."""
- ...
-
- @property
- def element(self) -> E:
- """The accumulated element state (read-only snapshot)."""
- ...
-
- def __enter__(self) -> Self:
- return self
-
- def __exit__(self, exc_type, exc_val, exc_tb) -> None:
- """Auto-close handle on context exit."""
- if self.is_open:
- self.close()
-
-
-class PanelHandle(ElementHandle[Panel]):
- """Handle for building a Panel element incrementally.
-
- Panels are titled groups of key-value pairs. Entries can be added,
- updated, or removed after creation.
- """
-
- def set_entry(self, key: str, value: str, *,
- style_hint: str | None = None,
- icon: str | None = None) -> None:
- """Set or update a key-value entry in the panel.
-
- If an entry with the given key already exists, it is updated.
- Otherwise, a new entry is appended.
-
- Emits an ElementUpdated event.
- """
- ...
-
- def set_entries(self, entries: dict[str, str], *,
- style_hints: dict[str, str] | None = None) -> None:
- """Set multiple entries at once (batch update). Emits a single event."""
- ...
-
- def remove_entry(self, key: str) -> None:
- """Remove an entry by key. Emits an ElementUpdated event."""
- ...
-
-
-class TableHandle(ElementHandle[Table]):
- """Handle for building a Table element incrementally.
-
- Tables are the primary element for streamed data. Rows can be added
- one at a time or in batches as data becomes available from queries,
- API calls, or concurrent operations.
- """
-
- def add_row(self, row: dict) -> None:
- """Append a single row to the table.
-
- The row dict maps column names to cell values. Missing columns
- are filled with None. Extra columns not in the schema are ignored.
-
- Emits an ElementUpdated event (type=row_added).
- """
- ...
-
- def add_rows(self, rows: list[dict]) -> None:
- """Append multiple rows in a batch. Emits a single ElementUpdated event."""
- ...
-
- def set_summary(self, summary: dict) -> None:
- """Set or update the summary/aggregation row. Emits an ElementUpdated event."""
- ...
-
- def set_sort_key(self, column: str, *, descending: bool = False) -> None:
- """Change the sort key. Emits an ElementUpdated event."""
- ...
-
-
-class TreeHandle(ElementHandle[Tree]):
- """Handle for building a Tree element incrementally.
-
- Trees are built by adding child nodes to existing nodes. The root node
- is created with the handle. Subtrees can be constructed incrementally
- as hierarchical data is discovered.
- """
-
- def add_child(self, parent_path: str | None, label: str, *,
- style_hint: str | None = None,
- collapsed: bool = False,
- metadata: dict | None = None) -> str:
- """Add a child node to the tree.
-
- Args:
- parent_path: Slash-separated path to the parent node (None = root).
- label: Display label for the new node.
- style_hint: Optional color/style hint.
- collapsed: Whether this node starts collapsed in interactive renderers.
- metadata: Arbitrary data attached to the node.
-
- Returns:
- The full path to the newly created node (for use as parent_path
- in subsequent add_child calls).
-
- Emits an ElementUpdated event.
- """
- ...
-
- def set_node_style(self, path: str, style_hint: str) -> None:
- """Update the style of an existing node. Emits an ElementUpdated event."""
- ...
-
-
-class ProgressHandle(ElementHandle[ProgressIndicator]):
- """Handle for updating a ProgressIndicator element.
-
- Progress handles are unique in that they are expected to receive many
- rapid updates. The materialization strategy may throttle update events
- to avoid overwhelming the terminal (e.g., limiting redraws to 10/sec).
- """
-
- def set_progress(self, current: int, total: int | None = None) -> None:
- """Update the progress counter.
-
- Args:
- current: Current progress value.
- total: Total value (can change, e.g., when total is discovered late).
-
- Emits an ElementUpdated event (may be throttled by the strategy).
- """
- ...
-
- def set_step_status(self, step_label: str, status: str) -> None:
- """Update the status of a named step.
-
- Args:
- step_label: The label of the step to update.
- status: New status — "pending" | "active" | "done" | "error" | "skipped".
-
- Emits an ElementUpdated event.
- """
- ...
-
- def set_label(self, label: str) -> None:
- """Update the progress label text. Emits an ElementUpdated event."""
- ...
-
- def increment(self, delta: int = 1) -> None:
- """Increment progress by delta. Convenience wrapper around set_progress."""
- ...
-
-
-class StatusHandle(ElementHandle[StatusMessage]):
- """Handle for a status message.
-
- Status handles are typically created and immediately closed (fire-and-forget
- messages). However, they can be kept open for messages that may be revised
- (e.g., a "Working..." status that becomes "Done" or "Failed").
- """
-
- def set_message(self, message: str) -> None:
- """Update the status message text. Emits an ElementUpdated event."""
- ...
-
- def set_level(self, level: str) -> None:
- """Change the status level. Emits an ElementUpdated event."""
- ...
-
- def set_detail(self, detail: str | None) -> None:
- """Set or clear the detail text. Emits an ElementUpdated event."""
- ...
-
-
-class TextHandle(ElementHandle[TextBlock]):
- """Handle for a text block. Supports appending text incrementally."""
-
- def append(self, text: str) -> None:
- """Append text to the block. Emits an ElementUpdated event."""
- ...
-
- def set_content(self, content: str) -> None:
- """Replace the entire content. Emits an ElementUpdated event."""
- ...
-
-
-class CodeHandle(ElementHandle[CodeBlock]):
- """Handle for a code block."""
-
- def set_content(self, content: str) -> None:
- """Set the code content. Emits an ElementUpdated event."""
- ...
-
- def set_language(self, language: str) -> None:
- """Set the language for syntax highlighting. Emits an ElementUpdated event."""
- ...
-
- def set_highlight_lines(self, lines: list[int]) -> None:
- """Set lines to highlight. Emits an ElementUpdated event."""
- ...
-
-
-class DiffHandle(ElementHandle[DiffBlock]):
- """Handle for a diff block. Hunks can be added incrementally."""
-
- def add_hunk(self, header: str, lines: list["DiffLine"]) -> None:
- """Add a diff hunk. Emits an ElementUpdated event."""
- ...
-
- def set_stats(self, insertions: int, deletions: int, **extra: int) -> None:
- """Set diff statistics. Emits an ElementUpdated event."""
- ...
-
-class ElementEvent:
- """Base class for all events emitted by element handles."""
- event_type: str # "created" | "updated" | "closed"
- handle_id: str # The handle that emitted this event
- element_type: str # The element kind ("panel", "table", etc.)
- timestamp: datetime # When the event occurred
- session_id: str # The owning session
-
-
-class ElementCreated(ElementEvent):
- """Emitted when a new element handle is created via a session factory."""
- event_type = "created"
- declaration_index: int # Position in session declaration order
- initial_state: OutputElement # The element's initial state
-
-
-class ElementUpdated(ElementEvent):
- """Emitted when data is written to an element handle."""
- event_type = "updated"
- update_type: str # Kind-specific: "entry_set", "row_added",
- # "progress_changed", "step_status_changed", etc.
- delta: dict # The change payload (what was added/modified)
- element_snapshot: OutputElement # The full element state after this update
-
-
-class ElementClosed(ElementEvent):
- """Emitted when an element handle is closed (no more data will arrive)."""
- event_type = "closed"
- final_state: OutputElement # The element's final accumulated state
-
-
-class SessionEnd(ElementEvent):
- """Emitted when the session itself is closed."""
- event_type = "session_end"
- exit_code: int
- snapshot: "StructuredOutput" # The complete accumulated output
-
-class OutputElement:
- """Base class for all output element snapshot types."""
- element_type: str # Semantic type identifier
- metadata: dict # Arbitrary metadata (timestamps, IDs, etc.)
- priority: str = "normal" # "critical" | "normal" | "supplementary"
- collapse_hint: str = "auto" # "always" | "auto" | "never" — guidance for renderers
- # on whether this element can be collapsed/hidden
-
-class Panel(OutputElement):
- """A titled group of key-value pairs."""
- element_type = "panel"
- title: str
- entries: list[PanelEntry] # Each entry: key, value, style_hint (color, icon, etc.)
- border_style: str = "rounded" # "rounded" | "square" | "heavy" | "none"
-
-class PanelEntry:
- """A single key-value pair within a Panel."""
- key: str
- value: str
- style_hint: str | None = None # Color/style for the value (e.g., "success", "warning")
- icon: str | None = None # Optional icon/prefix character
-
-class Table(OutputElement):
- """A tabular data set with typed columns."""
- element_type = "table"
- title: str | None
- columns: list[ColumnDef] # name, type, alignment, width_hint, sortable
- rows: list[dict] # Column name → cell value
- summary: dict | None # Optional aggregation row (totals, counts)
- max_rows_hint: int | None # Suggest truncation for large datasets
- sort_key: str | None # Default sort column
-
-class ColumnDef:
- """Schema for a single table column."""
- name: str # Column display name
- type: str = "string" # "string" | "number" | "boolean" | "datetime" | "id"
- alignment: str = "left" # "left" | "right" | "center"
- width_hint: int | None = None # Suggested character width (None = auto)
- sortable: bool = False # Whether this column can be sorted
- style_hint: str | None = None # Default style for cells in this column
-
-class Tree(OutputElement):
- """A hierarchical tree structure."""
- element_type = "tree"
- root: TreeNode # Recursive node structure
- max_depth_hint: int | None # Suggest depth truncation
- show_guides: bool = True # Whether to show tree guide lines
-
-class TreeNode:
- """A node in a tree structure."""
- label: str
- style_hint: str | None # Color/style for this node
- children: list["TreeNode"]
- collapsed: bool = False # Hint: start collapsed in interactive renderers
- metadata: dict # Arbitrary data attached to the node
-
-class StatusMessage(OutputElement):
- """A status line (success, warning, error, info)."""
- element_type = "status"
- level: str # "ok" | "warn" | "error" | "info"
- message: str
- detail: str | None # Optional detail text
-
-class ProgressIndicator(OutputElement):
- """A progress bar or spinner for long-running operations."""
- element_type = "progress"
- label: str
- current: int | None
- total: int | None
- indeterminate: bool = False # Spinner mode vs. progress bar mode
- steps: list[ProgressStep] | None # Named steps with status (pending/active/done)
-
-class ProgressStep:
- """A named step within a progress indicator."""
- label: str
- status: str # "pending" | "active" | "done" | "error" | "skipped"
-
-class CodeBlock(OutputElement):
- """A block of source code with optional syntax highlighting."""
- element_type = "code"
- content: str
- language: str | None # For syntax highlighting
- line_numbers: bool = False
- highlight_lines: list[int] | None # Lines to emphasize
-
-class DiffBlock(OutputElement):
- """A unified diff display."""
- element_type = "diff"
- hunks: list[DiffHunk]
- file_a: str | None
- file_b: str | None
- stats: dict | None # insertions, deletions, etc.
-
-class DiffHunk:
- """A single hunk within a diff."""
- header: str # @@ line range @@
- lines: list[DiffLine]
-
-class DiffLine:
- """A single line in a diff hunk."""
- type: str # "context" | "add" | "remove"
- content: str
- line_number_old: int | None
- line_number_new: int | None
-
-class TextBlock(OutputElement):
- """A free-form text block (descriptions, rationale, etc.)."""
- element_type = "text"
- content: str
- wrap: bool = True
- indent: int = 0
-
-class Separator(OutputElement):
- """A visual separator between logical groups."""
- element_type = "separator"
- style: str = "line" # "line" | "blank" | "double"
-
-class ActionHint(OutputElement):
- """A suggested next-step action for the user."""
- element_type = "action_hint"
- commands: list[str] # Suggested CLI commands
- description: str | None
-
-class StructuredOutput:
- """Static snapshot of a complete command output.
-
- This is the accumulated state of all elements at a point in time.
- It is produced by OutputSession.snapshot() and OutputSession.close().
-
- Uses:
- - Final serialization for json/yaml formats
- - Logging and audit trails
- - Programmatic inspection and testing
- - TUI widget data binding (initial state)
- """
- command: str # The command that produced this output
- session_id: str # The session that produced this output
- elements: list[OutputElement] # Ordered list of element snapshots
- exit_code: int = 0
- timing: dict | None # start_time, end_time, duration
- metadata: dict # command-specific metadata
-
-class MaterializationStrategy(Protocol):
- """Interface for format-driven output materialization.
-
- A materialization strategy receives element lifecycle events from the
- OutputSession and decides when to render element content to the output
- stream. Strategies do not render elements themselves — they delegate
- to a paired ElementRenderer at the appropriate time.
-
- The strategy is the mechanism by which format-agnostic producer code
- produces correct output regardless of format. The producer writes to
- handles; the strategy decides what reaches the terminal and when.
- """
-
- strategy_name: str # "live" | "sequential_buffer" | "accumulate"
-
- def bind(self, renderer: "ElementRenderer",
- terminal_caps: "TerminalCapabilities") -> None:
- """Bind this strategy to a renderer and terminal capabilities.
-
- Called once during format resolution, before the session opens.
- The strategy retains a reference to the renderer for use during
- event handling. The output stream is provided separately via
- on_session_begin, since the session owns the stream.
- """
- ...
-
- def on_session_begin(self, session: OutputSession, stream: IO) -> None:
- """Called when the session opens. The strategy receives the output
- stream and may write preamble (e.g., opening JSON bracket)."""
- ...
-
- def on_element_created(self, event: ElementCreated) -> None:
- """Called when a new element handle is created."""
- ...
-
- def on_element_updated(self, event: ElementUpdated) -> None:
- """Called when data is written to an element handle."""
- ...
-
- def on_element_closed(self, event: ElementClosed) -> None:
- """Called when an element handle is closed."""
- ...
-
- def on_session_end(self, event: SessionEnd) -> None:
- """Called when the session closes. The strategy may write epilogue."""
- ...
-
-
-class LiveMaterializer(MaterializationStrategy):
- """Materialization strategy for the `rich` format.
-
- Renders element updates in real-time using terminal cursor movement.
- Multiple elements can be visually active and updating simultaneously.
- The terminal display is a live document that is rewritten in place.
-
- Behavior:
- - on_element_created: Allocates screen region for the element, renders
- initial (possibly empty) visual state.
- - on_element_updated: Re-renders the element in place using cursor
- movement. For progress indicators, updates may be throttled to a
- maximum refresh rate (default: 15 fps) to avoid terminal flooding.
- - on_element_closed: Renders the final state and freezes the screen
- region (no further updates). May apply a visual transition (e.g.,
- spinner resolves to a checkmark).
- - on_session_end: Finalizes the display, moves cursor to end, and
- restores normal terminal scrolling.
-
- Screen Layout:
- Elements are arranged vertically in declaration order. Each element
- occupies a contiguous block of terminal lines. The materializer tracks
- the line offset and height of each element's region. When an element's
- height changes (e.g., a table gains rows), subsequent elements are
- shifted down.
-
- Concurrent Updates:
- Updates from multiple handles are coalesced into a single frame refresh
- at the target frame rate. The materializer maintains a dirty-element set
- and redraws all dirty elements in a single pass per frame.
- """
- strategy_name = "live"
-
- _frame_rate: float = 15.0 # Maximum redraws per second
- _element_regions: OrderedDict[str, ScreenRegion] # handle_id → screen region
- _dirty_set: set[str] # handle_ids that need redraw
- _frame_timer: asyncio.TimerHandle # Coalescing timer for frame redraws
-
-
-class SequentialBufferMaterializer(MaterializationStrategy):
- """Materialization strategy for `plain`, `color`, and `table` formats.
-
- Buffers element content and renders elements sequentially in declaration
- order. An element's content is rendered to the output stream only when
- its handle is closed. If handles are closed out of declaration order,
- the out-of-order element's rendered content is held in a buffer until
- all preceding elements have been rendered.
-
- This strategy ensures that static, scrolling output formats produce
- coherent sequential output even when producers write to handles
- concurrently and close them in arbitrary order.
-
- Behavior:
- - on_element_created: Records the element's declaration index. No output.
- - on_element_updated: Buffers the update internally. No output.
- - on_element_closed: If this element is the next in declaration order,
- renders it immediately (and any buffered subsequent elements that are
- also closed). Otherwise, buffers the rendered content.
- - on_session_end: Force-renders any remaining buffered elements (handles
- that were never closed, in declaration order).
-
- Example (two tables populated concurrently):
- 1. Handle A (index 0) created — table "Resources"
- 2. Handle B (index 1) created — table "Validations"
- 3. Handle B receives rows, Handle A receives rows (interleaved)
- 4. Handle B closes (index 1) — rendered content buffered (waiting for A)
- 5. Handle A closes (index 0) — A is rendered to stream, then buffered B
- is rendered to stream
-
- Result: Output shows table A followed by table B, regardless of the
- order in which data arrived or handles closed.
- """
- strategy_name = "sequential_buffer"
-
- _next_render_index: int = 0 # The declaration index to render next
- _rendered_buffers: dict[int, str] # index → pre-rendered content (waiting)
- _closed_set: set[int] # Declaration indices of closed elements
-
-
-class AccumulateMaterializer(MaterializationStrategy):
- """Materialization strategy for `json` and `yaml` formats.
-
- Accumulates all element data silently until the session ends, then
- serializes the complete StructuredOutput as a single JSON or YAML
- document.
-
- Behavior:
- - on_element_created: No output.
- - on_element_updated: No output.
- - on_element_closed: No output.
- - on_session_end: Calls session.snapshot() to get the final
- StructuredOutput, then delegates to the ElementRenderer's
- serialize() method for complete document serialization.
-
- This strategy is the simplest — it ignores all intermediate events and
- only acts on session_end. It exists as a distinct strategy (rather than
- a special case) to maintain the uniform strategy interface.
- """
- strategy_name = "accumulate"
-
-class ElementRenderer(Protocol):
- """Interface for format-specific element rendering.
-
- An ElementRenderer knows how to paint each element type for a specific
- output format. It is called by the MaterializationStrategy when it is
- time to render an element.
-
- Implementations:
- - PlainElementRenderer: ASCII text, no escapes
- - ColorElementRenderer: ANSI-colored text, same layout as plain
- - TableElementRenderer: Unicode box-drawing with color
- - RichElementRenderer: Advanced terminal features (cursor, animation)
- - JsonElementRenderer: JSON serialization
- - YamlElementRenderer: YAML serialization
- """
-
- format_name: str # "plain", "color", "table", "rich", "json", "yaml"
-
- def render_panel(self, panel: Panel, stream: IO) -> None:
- """Render a panel element to the stream."""
- ...
-
- def render_table(self, table: Table, stream: IO) -> None:
- """Render a table element to the stream."""
- ...
-
- def render_tree(self, tree: Tree, stream: IO) -> None:
- """Render a tree element to the stream."""
- ...
-
- def render_status(self, status: StatusMessage, stream: IO) -> None:
- """Render a status message to the stream."""
- ...
-
- def render_progress(self, progress: ProgressIndicator, stream: IO) -> None:
- """Render a progress indicator to the stream."""
- ...
-
- def render_code(self, code: CodeBlock, stream: IO) -> None:
- """Render a code block to the stream."""
- ...
-
- def render_diff(self, diff: DiffBlock, stream: IO) -> None:
- """Render a diff block to the stream."""
- ...
-
- def render_text(self, text: TextBlock, stream: IO) -> None:
- """Render a text block to the stream."""
- ...
-
- def render_separator(self, separator: Separator, stream: IO) -> None:
- """Render a visual separator to the stream."""
- ...
-
- def render_action_hint(self, hint: ActionHint, stream: IO) -> None:
- """Render an action hint to the stream."""
- ...
-
- def render_element(self, element: OutputElement, stream: IO) -> None:
- """Dispatch to the appropriate render method based on element type.
-
- This is the primary entry point used by materialization strategies.
- It uses a dispatch table to route to the correct typed method.
- """
- dispatch = {
- "panel": self.render_panel,
- "table": self.render_table,
- "tree": self.render_tree,
- "status": self.render_status,
- "progress": self.render_progress,
- "code": self.render_code,
- "diff": self.render_diff,
- "text": self.render_text,
- "separator": self.render_separator,
- "action_hint": self.render_action_hint,
- }
- handler = dispatch.get(element.element_type)
- if handler:
- handler(element, stream)
-
- def serialize(self, output: StructuredOutput, stream: IO) -> None:
- """Serialize a complete StructuredOutput to the stream.
-
- Used by AccumulateMaterializer for json/yaml formats. For visual
- formats (plain/color/table/rich), this method iterates over
- output.elements and calls render_element for each.
- """
- ...
-
- def can_render(self, terminal_caps: "TerminalCapabilities") -> bool:
- """Whether this renderer can operate in the given terminal environment."""
- ...
-
-$ agents --format plain project show local/api-service
-
-Project Details
- Name: local/api-service
- Description: Backend API
- Resources: 2
- Remote: no
- Created: 2026-02-08 12:46
-
-Linked Resources
- Resource Type Sandbox Read-Only
- ---------------- -------------- -------------------- ---------
- local/api-repo git-checkout git_worktree no
- local/staging-db local/database transaction_rollback yes
-
-Validations (3)
- local/run-tests pytest --cov=src --cov-fail-under=80 required
- local/lint-check ruff check . required
- local/check-bundle-size node scripts/check-bundle-size.js informational
-
-Context
- Include: repo
- Exclude: **/node_modules/**
- Max File Size: 1 MB
-
-Indexing Status
- Text Index: ready
- Vector Index: ready
- Graph Store: disabled
- Indexed Files: 347
- Last Indexed: 12:48
-
-Active Plans
- Plan ID Action Phase
- -------- ------------------- -------
- 01HXM7A9 local/code-coverage execute
-
-[OK] Project loaded
-
-$ agents --format plain plan list --phase execute
-
-Plans
- ID Phase State Action Project Elapsed
- -------- ------- ---------- ------------------- ----------------- ---------
- 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12
-
-Filters
- Phase: execute
- State: (any)
- Project: (any)
- Action: (any)
-
-Summary
- Total: 1
- Processing: 1
- Completed: 0
- Errored: 0
-
-[OK] 1 plan listed
-
-$ agents --format color project show local/api-service
-
-Project Details
- Name: local/api-service
- Description: Backend API
- Resources: 2
- Remote: no
- Created: 2026-02-08 12:46
-
-Linked Resources
- Resource Type Sandbox Read-Only
- ---------------- -------------- -------------------- ---------
- local/api-repo git-checkout git_worktree no
- local/staging-db local/database transaction_rollback yes
-
-Validations (3)
- local/run-tests pytest --cov=src --cov-fail-under=80 required
- local/lint-check ruff check . required
- local/check-bundle-size node scripts/check-bundle-size.js info
-
-Context
- Include: repo
- Exclude: **/node_modules/**
- Max File Size: 1 MB
-
-Indexing Status
- Text Index: ready
- Vector Index: ready
- Graph Store: disabled
- Indexed Files: 347
- Last Indexed: 12:48
-
-Active Plans
- Plan ID Action Phase
- -------- ------------------- -------
- 01HXM7A9 local/code-coverage execute
-
-[OK] Project loaded
-
-$ agents --format table project show local/api-service
-
-╭─ Project Details ──────────────╮
-│ Name: local/api-service │
-│ Description: Backend API │
-│ Resources: 2 │
-│ Remote: no │
-│ Created: 2026-02-08 12:46 │
-╰────────────────────────────────╯
-
-╭─ Linked Resources ──────────────────────────────────────────────────────╮
-│ Resource Type Sandbox Read-Only │
-│ ──────────────── ────────────── ──────────────────── ───────── │
-│ local/api-repo git-checkout git_worktree no │
-│ local/staging-db local/database transaction_rollback yes │
-╰─────────────────────────────────────────────────────────────────────────╯
-
-╭─ Validations (3) ───────────────────────────────────────────────────────────────╮
-│ local/run-tests pytest --cov=src --cov-fail-under=80 required │
-│ local/lint-check ruff check . required │
-│ local/check-bundle-size node scripts/check-bundle-size.js informational │
-╰─────────────────────────────────────────────────────────────────────────────────╯
-
-╭─ Context ───────────────────╮
-│ Include: repo │
-│ Exclude: **/node_modules/** │
-│ Max File Size: 1 MB │
-╰─────────────────────────────╯
-
-╭─ Indexing Status ──────────╮
-│ Text Index: ready │
-│ Vector Index: ready │
-│ Graph Store: disabled │
-│ Indexed Files: 347 │
-│ Last Indexed: 12:48 │
-╰────────────────────────────╯
-
-╭─ Active Plans ──────────────────────────╮
-│ Plan ID Action Phase │
-│ ──────── ─────────────────── ─────── │
-│ 01HXM7A9 local/code-coverage execute │
-╰─────────────────────────────────────────╯
-
-✓ OK Project loaded
-
-$ agents --format table plan execute 01HXM8C2ZK
-
-╭─ Execution ──────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: execute │
-│ Sandbox: git_worktree │
-│ Worker: local/executor │
-│ Started: 12:58:10 │
-│ Attempt: 1 │
-╰──────────────────────────────────╯
-
-╭─ Strategy Summary ─────────────────────╮
-│ Decisions: 8 │
-│ Invariants: 2 │
-│ Planned Child Plans: 2+ │
-│ Estimated Files: ~12 │
-│ Risk: low │
-╰────────────────────────────────────────╯
-
-╭─ Progress ─────────╮
-│ ✓ Collect context │
-│ ✓ Run tools │
-│ ⏳ Build changeset │
-│ • Validate │
-╰────────────────────╯
-
-✓ OK Execution started
-
-$ agents --format rich plan execute 01HXM8C2ZK
-
-╭─ Execution ──────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: execute │
-│ Sandbox: git_worktree │
-│ Worker: local/executor │
-│ Started: 12:58:10 │
-╰──────────────────────────────────╯
-
-⠋ Collecting context... (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ animates in place)
- ├── repo: local/api-repo ✓
- └── db: local/staging-db ✓
-
-╭─ Strategy Summary ──────────────────────────────────────────────────────╮
-│ 8 decisions │ 2 invariants │ 2+ child plans │ ~12 files │ risk: low │
-╰─────────────────────────────────────────────────────────────────────────╯
-
-Progress ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 42% elapsed 0:01:12 ETA 0:01:40
- ✓ Collect context .................. 0.8s
- ✓ Run tools (8 calls) ............. 12.4s
- ⠙ Build changeset ................. (running) (animates in place)
- ○ Validate ........................ (pending)
-
-╭─ Live Tool Calls ───────────────────────────────────────╮
-│ #6 read_file src/auth/__init__.py ✓ 0.1s │
-│ #7 write_file tests/test_auth.py ✓ 0.2s │
-│ #8 edit_file src/auth/session.py ⠙ ... │
-╰─────────────────────────────────────────────────────────╯
-
-$ agents --format rich version
-
-╭─────────────────────────────────────╮
-│ CleverAgents CLI v1.0.0 │
-│ channel: stable │
-╰─────────────────────────────────────╯
-
-╭─ Build ─────────────────────────────╮
-│ Build Date: 2026-02-08 │
-│ Commit: a17c3f9 │
-│ Schema: v3 │
-│ Platform: linux-x86_64 │
-│ Python: 3.13.1 │
-╰─────────────────────────────────────╯
-
-╭─ Dependencies ─────────────────────────────────────────────────────────╮
-│ LangGraph 0.2.60 │ LangChain 0.3.18 │ MCP SDK 1.4.0 │ Pydantic 2.10.4 │
-╰────────────────────────────────────────────────────────────────────────╯
-
-✓ OK Version reported
-
- {
- "command": "project show",
- "status": "ok",
- "exit_code": 0,
- "data": { ... },
- "timing": { "duration_ms": 42 },
- "metadata": { ... }
- }
-
-{
- "command": "project show",
- "status": "ok",
- "exit_code": 0,
- "data": {
- "project": {
- "name": "local/api-service",
- "description": "Backend API",
- "type": "local",
- "remote": false,
- "created_at": "2026-02-08T12:46:00Z"
- },
- "linked_resources": [
- {
- "name": "local/api-repo",
- "type": "git-checkout",
- "sandbox_strategy": "git_worktree",
- "read_only": false
- },
- {
- "name": "local/staging-db",
- "type": "local/database",
- "sandbox_strategy": "transaction_rollback",
- "read_only": true
- }
- ],
- "validations": [
- {
- "name": "local/run-tests",
- "command": "pytest --cov=src --cov-fail-under=80",
- "mode": "required",
- "timeout": 600,
- "resource": "repo"
- },
- {
- "name": "local/lint-check",
- "command": "ruff check .",
- "mode": "required",
- "timeout": 300,
- "resource": null
- },
- {
- "name": "local/check-bundle-size",
- "command": "node scripts/check-bundle-size.js",
- "mode": "informational",
- "timeout": 300,
- "resource": null
- }
- ],
- "context": {
- "include_resources": ["repo"],
- "exclude_paths": ["**/node_modules/**"],
- "max_file_size_bytes": 1048576
- },
- "indexing": {
- "text_index": "ready",
- "vector_index": "ready",
- "graph_store": "disabled",
- "indexed_files": 347,
- "last_indexed_at": "2026-02-08T12:48:00Z"
- },
- "active_plans": [
- {
- "plan_id": "01HXM7A9",
- "action": "local/code-coverage",
- "phase": "execute"
- }
- ]
- },
- "timing": {
- "duration_ms": 42
- },
- "messages": [
- { "level": "ok", "text": "Project loaded" }
- ]
-}
-
-{
- "command": "plan list",
- "status": "ok",
- "exit_code": 0,
- "data": {
- "plans": [
- {
- "id": "01HXM7A9",
- "phase": "execute",
- "state": "processing",
- "action": "local/code-coverage",
- "project": "local/api-service",
- "elapsed": "00:01:12"
- }
- ],
- "filters": {
- "phase": "execute",
- "state": null,
- "project": null,
- "action": null
- },
- "summary": {
- "total": 1,
- "processing": 1,
- "completed": 0,
- "errored": 0
- }
- },
- "timing": {
- "duration_ms": 18
- },
- "messages": [
- { "level": "ok", "text": "1 plan listed" }
- ]
-}
-
-command: project show
-status: ok
-exit_code: 0
-data:
- project:
- name: local/api-service
- description: Backend API
- type: local
- remote: false
- created_at: "2026-02-08T12:46:00Z"
- linked_resources:
- - name: local/api-repo
- type: git-checkout
- sandbox_strategy: git_worktree
- read_only: false
- - name: local/staging-db
- type: local/database
- sandbox_strategy: transaction_rollback
- read_only: true
- validations:
- - name: local/run-tests
- command: "pytest --cov=src --cov-fail-under=80"
- mode: required
- timeout: 600
- resource: repo
- - name: local/lint-check
- command: "ruff check ."
- mode: required
- timeout: 300
- resource: null
- - name: local/check-bundle-size
- command: "node scripts/check-bundle-size.js"
- mode: informational
- timeout: 300
- resource: null
- context:
- include_resources:
- - repo
- exclude_paths:
- - "**/node_modules/**"
- max_file_size_bytes: 1048576
- indexing:
- text_index: ready
- vector_index: ready
- graph_store: disabled
- indexed_files: 347
- last_indexed_at: "2026-02-08T12:48:00Z"
- active_plans:
- - plan_id: 01HXM7A9
- action: local/code-coverage
- phase: execute
-timing:
- duration_ms: 42
-messages:
- - level: ok
- text: Project loaded
-
-@dataclass
-class FormatRegistration:
- """A registered format: its strategy factory, renderer factory, and fallback."""
- strategy_factory: Callable[[TerminalCapabilities], MaterializationStrategy]
- renderer_factory: Callable[[TerminalCapabilities], ElementRenderer]
- fallback: str | None # Format name to fall back to, or None
-
-
-class RendererRegistry:
- """Central registry for format (strategy, renderer) pairs.
-
- Formats are registered by name and resolved at runtime based on the
- active format and terminal capabilities. The registry supports dynamic
- registration, enabling plugins to add custom formats (e.g., 'html',
- 'csv', 'markdown').
-
- Built-in registrations:
- "rich" → (LiveMaterializer, RichElementRenderer), fallback="table"
- "table" → (SequentialBufferMaterializer, TableElementRenderer), fallback="color"
- "color" → (SequentialBufferMaterializer, ColorElementRenderer), fallback="plain"
- "plain" → (SequentialBufferMaterializer, PlainElementRenderer), fallback=None
- "json" → (AccumulateMaterializer, JsonElementRenderer), fallback=None
- "yaml" → (AccumulateMaterializer, YamlElementRenderer), fallback=None
- """
-
- _formats: dict[str, FormatRegistration] = {}
-
- @classmethod
- def register(cls, format_name: str,
- strategy_factory: Callable[[TerminalCapabilities], MaterializationStrategy],
- renderer_factory: Callable[[TerminalCapabilities], ElementRenderer],
- fallback: str | None = None) -> None:
- """Register a format.
-
- Args:
- format_name: The format identifier (e.g., 'rich', 'json').
- strategy_factory: Callable that creates a MaterializationStrategy,
- given terminal capabilities.
- renderer_factory: Callable that creates an ElementRenderer,
- given terminal capabilities.
- fallback: Optional fallback format name if this format cannot
- operate in the current terminal environment.
- """
- cls._formats[format_name] = FormatRegistration(
- strategy_factory=strategy_factory,
- renderer_factory=renderer_factory,
- fallback=fallback,
- )
-
- @classmethod
- def resolve(cls, format_name: str,
- terminal_caps: TerminalCapabilities
- ) -> tuple[MaterializationStrategy, ElementRenderer]:
- """Resolve the best (strategy, renderer) pair for the given format.
-
- Walks the fallback chain if the requested format's renderer cannot
- operate in the current terminal environment. Returns the first pair
- where the renderer reports can_render(terminal_caps) == True.
-
- Raises:
- ValueError: If no usable format is found (should never happen
- since 'plain' has no fallback and always works).
- """
- current = format_name
- visited: set[str] = set()
-
- while current and current not in visited:
- visited.add(current)
- registration = cls._formats.get(current)
- if registration is None:
- break
-
- renderer = registration.renderer_factory(terminal_caps)
- if renderer.can_render(terminal_caps):
- strategy = registration.strategy_factory(terminal_caps)
- strategy.bind(renderer, terminal_caps=terminal_caps)
- return strategy, renderer
-
- current = registration.fallback
-
- # Ultimate fallback is always plain
- plain = cls._formats["plain"]
- renderer = plain.renderer_factory(terminal_caps)
- strategy = plain.strategy_factory(terminal_caps)
- strategy.bind(renderer, terminal_caps=terminal_caps)
- return strategy, renderer
-
- @classmethod
- def available_formats(cls) -> list[str]:
- """Return all registered format names."""
- return sorted(cls._formats.keys())
-
- @classmethod
- def is_registered(cls, format_name: str) -> bool:
- """Check if a format is registered."""
- return format_name in cls._formats
-
-@dataclass
-class TerminalCapabilities:
- """Detected capabilities of the output terminal.
-
- This dataclass is populated once at CLI startup and passed to the
- RendererRegistry for format resolution. It is also available to
- individual strategies and renderers for fine-grained adaptation
- (e.g., adjusting column widths to terminal width, choosing between
- 256-color and truecolor palettes).
- """
- is_tty: bool # Is stdout a TTY?
- width: int # Terminal width in columns
- height: int # Terminal height in rows
- supports_ansi: bool # Supports basic ANSI escape codes?
- supports_256_color: bool # Supports 256-color palette?
- supports_truecolor: bool # Supports 24-bit truecolor?
- supports_unicode: bool # Supports Unicode (box-drawing, etc.)?
- supports_cursor_movement: bool # Supports cursor repositioning?
- supports_alternate_screen: bool # Supports alternate screen buffer?
- no_color: bool # Is NO_COLOR environment variable set?
- term_program: str | None # TERM_PROGRAM value (e.g., "iTerm2", "vscode")
-
- @classmethod
- def detect(cls) -> "TerminalCapabilities":
- """Auto-detect terminal capabilities from the environment.
-
- Detection logic:
- - is_tty: os.isatty(sys.stdout.fileno())
- - width/height: os.get_terminal_size() with fallback to (80, 24)
- - supports_ansi: True if is_tty and not Windows legacy console
- - supports_256_color: True if TERM contains "256color" or COLORTERM is set
- - supports_truecolor: True if COLORTERM is "truecolor" or "24bit"
- - supports_unicode: True if locale encoding is UTF-8
- - supports_cursor_movement: True if is_tty and TERM is not "dumb"
- - supports_alternate_screen: True if supports_cursor_movement
- - no_color: True if NO_COLOR environment variable is set (any value)
- - term_program: Value of TERM_PROGRAM environment variable
- """
- ...
-
-# Example: Registering a custom 'csv' format plugin
-from cleveragents.output import RendererRegistry, SequentialBufferMaterializer
-
-class CsvElementRenderer(ElementRenderer):
- """Renders tables as CSV, other elements as plain text."""
- format_name = "csv"
-
- def render_table(self, table: Table, stream: IO) -> None:
- writer = csv.writer(stream)
- writer.writerow([col.name for col in table.columns])
- for row in table.rows:
- writer.writerow([row.get(col.name, "") for col in table.columns])
-
- def can_render(self, terminal_caps: TerminalCapabilities) -> bool:
- return True # CSV works everywhere
-
-# Register at plugin load time
-RendererRegistry.register(
- format_name="csv",
- strategy_factory=lambda caps: SequentialBufferMaterializer(),
- renderer_factory=lambda caps: CsvElementRenderer(),
- fallback="plain",
-)
-
-{
- "command": "project show",
- "status": "error",
- "exit_code": 1,
- "error": {
- "code": "NOT_FOUND",
- "message": "Project 'local/nonexistent' not found",
- "detail": "No project with name 'local/nonexistent' exists. Run 'agents project list' to see available projects.",
- "suggestions": [
- "agents project list",
- "agents project create local/nonexistent"
- ]
- },
- "timing": { "duration_ms": 5 }
-}
-
-async def list_resources(session: OutputSession, client: ApiClient) -> None:
- table = session.table("Resources", columns=[
- ColumnDef(name="Name"), ColumnDef(name="Type"), ColumnDef(name="Status"),
- ])
-
- try:
- async for resource in client.list_resources():
- table.add_row({
- "Name": resource.name,
- "Type": resource.type,
- "Status": resource.status,
- })
- except ApiError as e:
- table.close() # Close with partial data
- session.status(f"Error fetching resources: {e}", level="error")
- return
-
- table.close()
- session.status(f"{table.element.row_count} resources listed", level="ok")
-
-async def cmd_project_show(session: OutputSession, project_name: str) -> None:
- """Implementation of 'agents project show <project>'."""
- project = await api.get_project(project_name)
- resources = await api.list_project_resources(project.name)
- validations = await api.list_project_validations(project.name)
-
- # --- Build output elements ---
-
- # Panel: Project details
- with session.panel("Project Details") as panel:
- panel.set_entries({
- "Name": project.name,
- "Description": project.description,
- "Resources": str(len(resources)),
- "Remote": "yes" if project.remote else "no",
- "Created": project.created_at.strftime("%Y-%m-%d %H:%M"),
- }, style_hints={
- "Name": "identifier",
- "Resources": "number",
- "Remote": "success" if not project.remote else "info",
- "Created": "success",
- })
-
- # Table: Linked resources
- with session.table("Linked Resources", columns=[
- ColumnDef(name="Resource", type="string", style_hint="identifier"),
- ColumnDef(name="Type"),
- ColumnDef(name="Sandbox"),
- ColumnDef(name="Read-Only"),
- ]) as table:
- for r in resources:
- table.add_row({
- "Resource": r.name,
- "Type": r.type,
- "Sandbox": r.sandbox_strategy,
- "Read-Only": "yes" if r.read_only else "no",
- })
-
- # Table: Validations
- with session.table(f"Validations ({len(validations)})", columns=[
- ColumnDef(name="ID", type="id", style_hint="identifier"),
- ColumnDef(name="Command"),
- ColumnDef(name="Mode"),
- ]) as table:
- for v in validations:
- table.add_row({
- "ID": v.id,
- "Command": v.command,
- "Mode": v.mode,
- })
-
- # Status: Final message
- session.status("Project loaded", level="ok")
-
-Project Details
- Name: local/api-service
- Description: Backend API
- Resources: 2
- Remote: no
- Created: 2026-02-08 12:46
-
-Linked Resources
- Resource Type Sandbox Read-Only
- ---------------- -------------- -------------------- ---------
- local/api-repo git-checkout git_worktree no
- local/staging-db local/database transaction_rollback yes
-
-Validations (3)
- Name Command Mode
- ----------------------- ------------------------------------- -----------
- local/run-tests pytest --cov=src --cov-fail-under=80 required
- local/lint-check ruff check . required
- local/check-bundle-size node scripts/check-bundle-size.js informational
-
-[OK] Project loaded
-
-╭─ Project Details ──────────────╮
-│ Name: local/api-service │
-│ Description: Backend API │
-│ Resources: 2 │
-│ Remote: no │
-│ Created: 2026-02-08 12:46 │
-╰────────────────────────────────╯
-
-╭─ Linked Resources ──────────────────────────────────────────────────────╮
-│ Resource Type Sandbox Read-Only │
-│ ──────────────── ────────────── ──────────────────── ───────── │
-│ local/api-repo git-checkout git_worktree no │
-│ local/staging-db local/database transaction_rollback yes │
-╰─────────────────────────────────────────────────────────────────────────╯
-
-╭─ Validations (3) ──────────────────────────────────────────────────────────────╮
-│ Name Command Mode │
-│ ─────────────────────── ───────────────────────────────────── ─────────── │
-│ local/run-tests pytest --cov=src --cov-fail-under=80 required │
-│ local/lint-check ruff check . required │
-│ local/check-bundle-size node scripts/check-bundle-size.js informational │
-╰────────────────────────────────────────────────────────────────────────────────╯
-
-✓ OK Project loaded
-
-{
- "command": "project show",
- "status": "ok",
- "exit_code": 0,
- "data": {
- "project_details": {
- "Name": "local/api-service",
- "Description": "Backend API",
- "Resources": "2",
- "Remote": "no",
- "Created": "2026-02-08 12:46"
- },
- "linked_resources": [
- {
- "Resource": "local/api-repo",
- "Type": "git-checkout",
- "Sandbox": "git_worktree",
- "Read-Only": "no"
- },
- {
- "Resource": "local/staging-db",
- "Type": "local/database",
- "Sandbox": "transaction_rollback",
- "Read-Only": "yes"
- }
- ],
- "validations": [
- {
- "Name": "local/run-tests",
- "Command": "pytest --cov=src --cov-fail-under=80",
- "Mode": "required"
- },
- {
- "Name": "local/lint-check",
- "Command": "ruff check .",
- "Mode": "required"
- },
- {
- "Name": "local/check-bundle-size",
- "Command": "node scripts/check-bundle-size.js",
- "Mode": "informational"
- }
- ]
- },
- "timing": { "duration_ms": 42 },
- "messages": [
- { "level": "ok", "text": "Project loaded" }
- ]
-}
-
-async def cmd_resource_list(session: OutputSession, project: str | None) -> None:
- """Implementation of 'agents resource list'."""
-
- # Create the table handle — it will accumulate rows as we stream them
- table = session.table("Resources", columns=[
- ColumnDef(name="Name", type="string", style_hint="identifier"),
- ColumnDef(name="Type"),
- ColumnDef(name="Project"),
- ColumnDef(name="Sandbox"),
- ColumnDef(name="Status"),
- ], sort_key="Name")
-
- # Create a progress indicator for the fetch operation
- progress = session.progress("Fetching resources...", indeterminate=True)
-
- # Stream pages from the API
- count = 0
- async for page in api.list_resources_paginated(project=project):
- for resource in page.items:
- table.add_row({
- "Name": resource.name,
- "Type": resource.type,
- "Project": resource.project,
- "Sandbox": resource.sandbox_strategy,
- "Status": resource.status,
- })
- count += 1
-
- # Update progress label with count so far
- progress.set_label(f"Fetching resources... ({count} found)")
-
- # Close the progress indicator (it has served its purpose)
- progress.close()
-
- # Set summary and close the table
- table.set_summary({"total": count})
- table.close()
-
- # Final status
- session.status(f"{count} resources listed", level="ok")
-
-Fetching resources... (47 found) [done]
-
-Resources
- Name Type Project Sandbox Status
- -------------------- -------------- ----------------- -------------------- --------
- local/api-repo git-checkout local/api-service git_worktree active
- local/staging-db local/database local/api-service transaction_rollback active
- local/docs-repo git-checkout local/docs-site git_worktree active
- ... (44 more rows)
-
- Total: 47
-
-[OK] 47 resources listed
-
-⠙ Fetching resources... (23 found)
-
-╭─ Resources ────────────────────────────────────────────────────────────────────────────╮
-│ Name Type Project Sandbox Status │
-│ ──────────────────── ────────────── ───────────────── ──────────────────── ────── │
-│ local/api-repo git-checkout local/api-service git_worktree active │
-│ local/staging-db local/database local/api-service transaction_rollback active │
-│ local/docs-repo git-checkout local/docs-site git_worktree active │
-│ ... │
-│ local/test-fixtures git-checkout local/api-service git_worktree active │
-│ │
-│ Showing 1-23 of 23 (fetching...) │
-╰────────────────────────────────────────────────────────────────────────────────────────╯
-
-async def cmd_plan_status(session: OutputSession, plan_id: str) -> None:
- """Implementation of 'agents plan status <plan_id>'.
-
- This command fetches plan metadata, then concurrently streams two data
- sources: resource statuses and active tool call logs. Both data sources
- are long-running — they produce results over several seconds as the
- backend resolves each item.
- """
- plan = await api.get_plan(plan_id)
-
- # Panel: Plan metadata (created and closed synchronously)
- with session.panel("Plan") as panel:
- panel.set_entries({
- "Plan ID": plan.id,
- "Phase": plan.phase,
- "State": plan.state,
- "Action": plan.action,
- "Project": plan.project,
- "Started": plan.started_at.strftime("%H:%M:%S"),
- }, style_hints={
- "Plan ID": "identifier",
- "Phase": "info",
- "State": "warning" if plan.state == "processing" else "success",
- })
-
- # Create both table handles BEFORE starting concurrent producers.
- # Declaration order determines rendering order in sequential formats.
- resource_table = session.table("Resource Status", columns=[
- ColumnDef(name="Resource", style_hint="identifier"),
- ColumnDef(name="Type"),
- ColumnDef(name="Status"),
- ColumnDef(name="Latency", type="string", alignment="right"),
- ])
-
- tool_table = session.table("Tool Call Log", columns=[
- ColumnDef(name="#", type="number", alignment="right"),
- ColumnDef(name="Tool"),
- ColumnDef(name="Target"),
- ColumnDef(name="Result"),
- ColumnDef(name="Duration", type="string", alignment="right"),
- ])
-
- # --- Run two producers concurrently ---
- # Each producer writes to its own handle. Neither producer knows
- # which format is active. The materialization strategy handles
- # the coordination.
-
- async def stream_resources():
- """Producer A: streams resource status checks."""
- async for status in api.stream_resource_statuses(plan.id):
- resource_table.add_row({
- "Resource": status.resource_name,
- "Type": status.resource_type,
- "Status": status.status,
- "Latency": f"{status.latency_ms}ms",
- })
- resource_table.close()
-
- async def stream_tool_calls():
- """Producer B: streams tool call results."""
- async for call in api.stream_tool_calls(plan.id):
- tool_table.add_row({
- "#": call.sequence_number,
- "Tool": call.tool_name,
- "Target": call.target,
- "Result": call.result_summary,
- "Duration": f"{call.duration_ms}ms",
- })
- tool_table.close()
-
- # Launch both producers concurrently
- await asyncio.gather(stream_resources(), stream_tool_calls())
-
- # Final status
- session.status(f"Plan {plan_id} status retrieved", level="ok")
-
-Plan
- Plan ID: 01HXM7A9
- Phase: execute
- State: processing
- Action: local/code-coverage
- Project: local/api-service
- Started: 12:58:10
-
-Resource Status
- Resource Type Status Latency
- ---------------- -------------- ------- -------
- local/api-repo git-checkout ready 42ms
- local/staging-db local/database ready 128ms
-
-Tool Call Log
- # Tool Target Result Duration
- -- ---------- ---------------------- ------------- --------
- 1 read_file src/auth/__init__.py 200 lines 0.1s
- 2 read_file src/auth/session.py 340 lines 0.1s
- 3 write_file tests/test_auth.py created 0.2s
- 4 edit_file src/auth/session.py 12 lines +/- 0.3s
- 5 run_tests pytest tests/test_auth 3 passed 2.1s
-
-[OK] Plan 01HXM7A9 status retrieved
-
-╭─ Plan ──────────────────────────────╮
-│ Plan ID: 01HXM7A9 │
-│ Phase: execute │
-│ State: processing │
-│ Action: local/code-coverage │
-│ Project: local/api-service │
-│ Started: 12:58:10 │
-╰─────────────────────────────────────╯
-
-╭─ Resource Status ⠙ ───────────────────────────────────────────╮
-│ Resource Type Status Latency │
-│ ──────────────── ────────────── ─────── ─────── │
-│ local/api-repo git-checkout ready 42ms │
-│ local/staging-db local/database ready 128ms │
-│ │
-│ 2 resources (streaming...) │
-╰───────────────────────────────────────────────────────────────╯
-
-╭─ Tool Call Log ⠙ ────────────────────────────────────────────────────╮
-│ # Tool Target Result Duration │
-│ ── ────────── ────────────────────── ───────────── ──────── │
-│ 1 read_file src/auth/__init__.py 200 lines 0.1s │
-│ 2 read_file src/auth/session.py 340 lines 0.1s │
-│ 3 write_file tests/test_auth.py created 0.2s │
-│ │
-│ 3 calls (streaming...) │
-╰──────────────────────────────────────────────────────────────────────╯
-
-{
- "command": "plan status",
- "status": "ok",
- "exit_code": 0,
- "data": {
- "plan": {
- "Plan ID": "01HXM7A9",
- "Phase": "execute",
- "State": "processing",
- "Action": "local/code-coverage",
- "Project": "local/api-service",
- "Started": "12:58:10"
- },
- "resource_status": [
- { "Resource": "local/api-repo", "Type": "git-checkout", "Status": "ready", "Latency": "42ms" },
- { "Resource": "local/staging-db", "Type": "local/database", "Status": "ready", "Latency": "128ms" }
- ],
- "tool_call_log": [
- { "#": 1, "Tool": "read_file", "Target": "src/auth/__init__.py", "Result": "200 lines", "Duration": "0.1s" },
- { "#": 2, "Tool": "read_file", "Target": "src/auth/session.py", "Result": "340 lines", "Duration": "0.1s" },
- { "#": 3, "Tool": "write_file", "Target": "tests/test_auth.py", "Result": "created", "Duration": "0.2s" },
- { "#": 4, "Tool": "edit_file", "Target": "src/auth/session.py", "Result": "12 lines +/-", "Duration": "0.3s" },
- { "#": 5, "Tool": "run_tests", "Target": "pytest tests/test_auth", "Result": "3 passed", "Duration": "2.1s" }
- ]
- },
- "timing": { "duration_ms": 3200 },
- "messages": [
- { "level": "ok", "text": "Plan 01HXM7A9 status retrieved" }
- ]
-}
-
-async def cmd_plan_execute(session: OutputSession, plan_id: str) -> None:
- """Implementation of 'agents plan execute <plan_id>'."""
- plan = await api.get_plan(plan_id)
-
- # Panel: Execution metadata
- with session.panel("Execution") as panel:
- panel.set_entries({
- "Plan": plan.id,
- "Phase": "execute",
- "Sandbox": plan.sandbox_strategy,
- "Worker": plan.worker,
- "Started": datetime.now().strftime("%H:%M:%S"),
- })
-
- # Progress indicator with named steps
- progress = session.progress("Executing plan", total=4, steps=[
- "Collect context",
- "Run tools",
- "Build changeset",
- "Validate",
- ])
-
- # Step 1: Collect context
- progress.set_step_status("Collect context", "active")
- context = await api.collect_context(plan.id)
- progress.set_step_status("Collect context", "done")
- progress.set_progress(1, 4)
-
- # Step 2: Run tools (parallel sub-operations)
- progress.set_step_status("Run tools", "active")
- tool_results = await api.run_tools(plan.id, context)
- progress.set_step_status("Run tools", "done")
- progress.set_progress(2, 4)
-
- # Step 3: Build changeset
- progress.set_step_status("Build changeset", "active")
- changeset = await api.build_changeset(plan.id, tool_results)
- progress.set_step_status("Build changeset", "done")
- progress.set_progress(3, 4)
-
- # Step 4: Validate
- progress.set_step_status("Validate", "active")
- validation = await api.validate_changeset(plan.id, changeset)
- progress.set_step_status("Validate", "done")
- progress.set_progress(4, 4)
-
- progress.close()
-
- # Summary panel
- with session.panel("Strategy Summary") as panel:
- panel.set_entries({
- "Decisions": str(changeset.decision_count),
- "Invariants": str(changeset.invariant_count),
- "Planned Child Plans": f"{changeset.child_plan_count}+",
- "Estimated Files": f"~{changeset.file_count}",
- "Risk": changeset.risk_level,
- })
-
- # Final status
- if validation.passed:
- session.status("Execution complete — all validations passed", level="ok")
- else:
- session.status(
- f"Execution complete — {validation.failure_count} validation(s) failed",
- level="warn",
- detail=validation.summary,
- )
-
-Execution
- Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
- Phase: execute
- Sandbox: git_worktree
- Worker: local/executor
- Started: 12:58:10
-
-Executing plan [4/4]
- [x] Collect context
- [x] Run tools
- [x] Build changeset
- [x] Validate
-
-Strategy Summary
- Decisions: 8
- Invariants: 2
- Planned Child Plans: 2+
- Estimated Files: ~12
- Risk: low
-
-[OK] Execution complete — all validations passed
-
-╭─ Execution ──────────────────────╮
-│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
-│ Phase: execute │
-│ Sandbox: git_worktree │
-│ Worker: local/executor │
-│ Started: 12:58:10 │
-╰──────────────────────────────────╯
-
-Executing plan ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 50% elapsed 0:00:13
- ✓ Collect context .................. 0.8s
- ✓ Run tools ...................... 12.4s
- ⠙ Build changeset ................. (running)
- ○ Validate ........................ (pending)
-
-async def cmd_resource_verify(session: OutputSession, project: str) -> None:
- """Verify all resources in a project. Some verifications may fail."""
- resources = await api.list_project_resources(project)
-
- # Create a table that will be populated concurrently
- results_table = session.table("Verification Results", columns=[
- ColumnDef(name="Resource", style_hint="identifier"),
- ColumnDef(name="Type"),
- ColumnDef(name="Check"),
- ColumnDef(name="Status"),
- ColumnDef(name="Detail"),
- ])
-
- # Progress indicator
- progress = session.progress(
- "Verifying resources",
- total=len(resources),
- steps=[r.name for r in resources],
- )
-
- # Verify each resource concurrently
- async def verify_one(resource):
- progress.set_step_status(resource.name, "active")
- try:
- result = await api.verify_resource(resource.id)
- results_table.add_row({
- "Resource": resource.name,
- "Type": resource.type,
- "Check": result.check_name,
- "Status": "pass" if result.passed else "fail",
- "Detail": result.detail,
- })
- progress.set_step_status(
- resource.name,
- "done" if result.passed else "error",
- )
- except ApiError as e:
- results_table.add_row({
- "Resource": resource.name,
- "Type": resource.type,
- "Check": "connection",
- "Status": "error",
- "Detail": str(e),
- })
- progress.set_step_status(resource.name, "error")
- progress.increment()
-
- # Launch all verifications concurrently
- await asyncio.gather(
- *[verify_one(r) for r in resources],
- return_exceptions=True, # Don't fail fast — collect all results
- )
-
- progress.close()
- results_table.close()
-
- # Summarize
- snapshot = results_table.element
- pass_count = sum(1 for r in snapshot.rows if r["Status"] == "pass")
- fail_count = sum(1 for r in snapshot.rows if r["Status"] in ("fail", "error"))
-
- if fail_count == 0:
- session.status(f"All {pass_count} resources verified", level="ok")
- else:
- session.status(
- f"{fail_count} of {pass_count + fail_count} resources failed verification",
- level="error",
- )
-
-Verifying resources [3/3]
- [x] local/api-repo
- [!] local/staging-db
- [x] local/docs-repo
-
-Verification Results
- Resource Type Check Status Detail
- ---------------- -------------- ---------- ------ ----------------------------------
- local/api-repo git-checkout integrity pass All refs valid
- local/staging-db local/database connection error Connection refused (port 5432)
- local/docs-repo git-checkout integrity pass All refs valid
-
-[ERROR] 1 of 3 resources failed verification
-
-Verifying resources [3/3]
- [x] local/api-repo
- [!] local/staging-db
- [x] local/docs-repo
-
-Verification Results
- Resource Type Check Status Detail
- ---------------- -------------- ---------- ------ ----------------------------------
- local/api-repo git-checkout integrity pass All refs valid
- local/staging-db local/database connection error Connection refused (port 5432)
- local/docs-repo git-checkout integrity pass All refs valid
-
-[ERROR] 1 of 3 resources failed verification
-
-command: resource verify
-status: error
-exit_code: 1
-data:
- verification_results:
- - Resource: local/api-repo
- Type: git-checkout
- Check: integrity
- Status: pass
- Detail: All refs valid
- - Resource: local/staging-db
- Type: local/database
- Check: connection
- Status: error
- Detail: "Connection refused (port 5432)"
- - Resource: local/docs-repo
- Type: git-checkout
- Check: integrity
- Status: pass
- Detail: All refs valid
-timing:
- duration_ms: 2840
-messages:
- - level: error
- text: "1 of 3 resources failed verification"
-
-# File: profiles/careful-auto.yaml
-name: local/careful-auto
-description: "Autonomous execution with mandatory sandbox and manual apply"
-
-# Confidence thresholds (0.0 = always auto, 1.0 = always manual)
-decompose_task: 0.0
-create_tool: 0.0
-select_tool: 1.0
-edit_code: 0.0
-execute_command: 0.0
-create_file: 0.0
-delete_content: 1.0
-access_network: 1.0
-install_dependency: 0.0
-modify_config: 0.0
-approve_plan: 0.0
-
-# Safety profile (composed sub-model)
-safety:
- require_sandbox: true
- require_checkpoints: true
- allow_unsafe_tools: false
-
-# File: profiles/nuanced-auto.yaml
-name: local/nuanced-auto
-description: "Nuanced automation with graduated confidence thresholds"
-
-decompose_task: 0.0 # Always auto-strategize
-create_tool: 0.5 # Auto-execute when confidence >= 0.5
-select_tool: 1.0 # Always require manual apply
-edit_code: 0.3 # Low bar for strategy decisions
-execute_command: 0.7 # Higher bar for execution decisions
-create_file: 0.5 # Auto-fix when reasonably confident
-delete_content: 0.8 # High confidence needed for auto-revision
-access_network: 0.9 # Very high bar for late-stage reversion
-install_dependency: 0.5 # Auto-spawn when moderately confident
-modify_config: 0.0 # Always auto-retry transient errors
-approve_plan: 0.6 # Auto-restore when fairly confident
-
-# Safety profile (composed sub-model)
-safety:
- require_sandbox: true
- require_checkpoints: true
- allow_unsafe_tools: false
-
-agents automation-profile add --config ./profiles/careful-auto.yaml
-
-class AutonomyController:
- def should_proceed_automatically(self, decision, context, profile):
- """Determine whether to proceed automatically or escalate to user."""
- factors = {
- 'past_success_rate': self.get_historical_success(decision.type),
- 'codebase_familiarity': self.get_familiarity_score(context.project),
- 'risk_assessment': self.evaluate_risk(decision),
- 'invariant_complexity': self.analyze_invariants(decision)
- }
-
- confidence = self.compute_confidence(factors) # Returns 0.0–1.0
- threshold = profile.get_threshold(decision.flag) # e.g., execute_command
-
- if confidence >= threshold:
- # Confidence meets or exceeds the profile threshold — proceed
- return ProceedAutonomously(decision, confidence)
- else:
- # Confidence below threshold — escalate to human
- return RequestHumanGuidance(decision, confidence, threshold, factors)
-
-def compute_affected_subtree(target_decision_id):
- affected_decisions = {target_decision_id}
- affected_plans = set()
- queue = [target_decision_id]
-
- while queue:
- current = queue.pop(0)
-
- # Follow structural tree children
- children = query("SELECT decision_id FROM decisions "
- "WHERE parent_decision_id = :current AND superseded_by IS NULL")
-
- # Follow influence DAG dependents
- dependents = query("SELECT downstream_ref FROM decision_dependencies "
- "WHERE upstream_decision_id = :current AND dependency_type = 'decision'")
-
- for d in children | dependents:
- if d not in affected_decisions:
- affected_decisions.add(d)
- queue.append(d)
-
- # Collect affected child plans
- child_plans = query("SELECT downstream_ref FROM decision_dependencies "
- "WHERE upstream_decision_id = :current AND dependency_type = 'plan'")
- affected_plans.update(child_plans)
-
- return affected_decisions, affected_plans
-
-# View decision tree
-agents plan tree <plan_id>
-agents --format=json plan tree <plan_id> # For visualization tools
-
-# View decision tree including superseded branches
-agents plan tree --show-superseded <plan_id>
-
-# Inspect a specific decision
-agents plan explain <decision_id>
-# Shows: question, chosen option, alternatives, rationale, downstream impact
-
-# Correct via revert-and-replay
-agents plan correct <decision_id> --mode=revert --guidance "<what the decision should be>"
-# Re-executes from that point with the new guidance
-
-# Correct via append (add fix at end)
-agents plan correct <decision_id> --mode=append --guidance "<description of the fix>"
-# Creates a new child plan to fix the outcome without rewriting history
-
-# Compare old vs new after correction
-agents plan diff --correction <correction_attempt_id>
-┌──────────────────────────────────────────────────────────────────────────────────────────────┐ -│═══════════════════════════════════════════ ◆ ═══════════════════════════════════════════ │ -│ Session 1 ┃ Session 2 ┃ Session 3 │ -│ ┗━━━━━━━━━━━━┛ │ -├──────────────────────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┃ You 14:01 │ -│ ┃ Can you review the auth module in the │ -│ ┃ API service? │ -│ ┃ @project:api-service:src/auth/handler.py │ -│ ┃ │ -│ │ │ -│ │ Actor 14:02 │ -│ │ I'll review the authentication handler. │ -│ │ Let me analyze the code structure and │ -│ │ identify potential issues. │ -│ │ │ -│ │ 🔧 local/code-analysis ✔ ▶ │ -│ │ │ -│ │ Found 3 issues in the auth module: │ -│ │ │ -│ │ 1. **Missing rate limiting** │ -│ │ 2. **JWT token** not validated │ -│ │ 3. **Session cleanup** missing │ -│ │ │ -│ │ 🔧 local/file-read ✔ ▼ │ -│ │ ┌─ src/auth/handler.py ─────────────┐ │ -│ │ │ 45 │ def login(self, req): │ │ -│ │ │ 46 │ creds = extract(req) │ │ -│ │ │ 47 │ return auth(creds) │ │ -│ │ └──────────────────────────────────┘ │ -│ │ -│──────────────────────────────────────────────────────────────────────────────────────────────│ -│ Agent connected │ -│──────────────────────────────────────────────────────────────────────────────────────────────│ -│ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ ❯ What would you like to do? │ │ -│ │ ▌@▐ refs ▌/▐ commands ▌!▐ shell │ │ -│ └─────────────────────────────────────────────────────────────────────────────────────┘ │ -│ feature-dev │ claude-4-sonnet │ think: high │ 2 projects │ $0.12 │ -├──────────────────────────────────────────────────────────────────────────────────────────────┤ -│ F1 Help │ shift+tab Sidebar │ tab Persona │ ctrl+tab Preset │ ctrl+s Sessions │ ctrl+q Quit │ -└──────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────────────────────┐ -│═══════════════════════════════════════════ ◆ ═══════════════════════════════════════════ │ -│ Session 1 ┃ Session 2 ┃ Session 3 │ -│ ┗━━━━━━━━━━━━┛ │ -├─────────────────────────────────────────────────────────────┬────────────────────────────────┤ -│ │ ▼ PLANS │ -│ ┃ You 14:01 │ ┌────────────────────────────┐ │ -│ ┃ Can you review the auth module in the │ │ ► fix-auth-bug │ │ -│ ┃ API service? │ │ Phase: Execute ●●●○ │ │ -│ ┃ @project:api-service:src/auth/handler.py │ │ Profile: trusted │ │ -│ ┃ │ │ Actor: claude-4-sonnet │ │ -│ │ │ │ Cost: $0.08 │ │ -│ │ Actor 14:02 │ │ │ │ -│ │ I'll review the authentication handler. │ │ ► refactor-models │ │ -│ │ Let me analyze the code structure and │ │ Phase: Strategize ●○○○ │ │ -│ │ identify potential issues. │ │ Profile: cautious │ │ -│ │ │ │ Depth: 2 (3 subplans) │ │ -│ │ 🔧 local/code-analysis ✔ ▶ │ │ Actor: gpt-4o │ │ -│ │ │ │ ├─ users (execute) │ │ -│ │ Found 3 issues in the auth module: │ │ ├─ orders (strategize) │ │ -│ │ │ │ └─ auth (pending) │ │ -│ │ 1. **Missing rate limiting** │ │ │ │ -│ │ 2. **JWT token** not validated │ │ ◌ update-deps │ │ -│ │ 3. **Session cleanup** missing │ │ Phase: Idle │ │ -│ │ │ │ Profile: auto │ │ -│ │ 🔧 local/file-read ✔ ▼ │ └────────────────────────────┘ │ -│ │ ┌─ src/auth/handler.py ─────────────┐ │ │ -│ │ │ 45 │ def login(self, req): │ │ ▼ PROJECTS │ -│ │ │ 46 │ creds = extract(req) │ │ ┌────────────────────────────┐ │ -│ │ │ 47 │ return auth(creds) │ │ │ ◆ cleveragents [2p] │ │ -│ │ └───────────────────────────────────┘ │ │ ◆ api-service [1p] │ │ -│ │ │ frontend-app [0p] │ │ -│─────────────────────────────────────────────────────────────│ │ infra-terraform [0p] │ │ -│ Agent connected │ └────────────────────────────┘ │ -│─────────────────────────────────────────────────────────────│ │ -│ ┌────────────────────────────────────────────────────────┐ │ │ -│ │ ❯ What would you like to do? │ │ │ -│ │ ▌@▐ refs ▌/▐ commands ▌!▐ shell │ │ │ -│ └────────────────────────────────────────────────────────┘ │ │ -│ feature-dev │ claude-4-sonnet │ think: med │ 2 proj │ $0.12 │ │ -├─────────────────────────────────────────────────────────────┴────────────────────────────────┤ -│ F1 Help │ shift+tab Sidebar │ tab Persona │ ctrl+tab Preset │ ctrl+s Sessions │ ctrl+q Quit │ -└──────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────────────────────┐ -│ PLANS & PROJECTS BROWSER │ -│──────────────────────────────────────────────────────────────────────────────────────────────│ -│ PLANS │ PROJECTS │ -│ ┌───────────────────────────────────────────┐ │ ┌──────────────────────────────────────────┐ │ -│ │ │ │ │ │ │ -│ │ [x] ► fix-auth-bug │ │ │ [x] cleveragents │ │ -│ │ Phase: Execute ●●●○ │ │ │ Namespace: local/ │ │ -│ │ State: in_progress │ │ │ Resources: 5 │ │ -│ │ Profile: trusted │ │ │ Plans: 2 active │ │ -│ │ Actor: anthropic/claude-4-sonnet │ │ │ Invariants: 3 │ │ -│ │ Started: 2m ago Cost: $0.08 │ │ │ Validations: 2 │ │ -│ │ Decisions: 6 (4 done, 2 pending) │ │ │ │ │ -│ │ │ │ │ [ ] api-service │ │ -│ │ [ ] refactor-models │ │ │ Namespace: local/ │ │ -│ │ Phase: Strategize ●○○○ │ │ │ Resources: 3 │ │ -│ │ State: in_progress │ │ │ Plans: 1 active │ │ -│ │ Profile: cautious │ │ │ Invariants: 1 │ │ -│ │ Actor: openai/gpt-4o │ │ │ Validations: 4 │ │ -│ │ Started: 5m ago Cost: $0.03 │ │ │ │ │ -│ │ Decisions: 3 (2 done, 1 active) │ │ │ [ ] frontend-app │ │ -│ │ Subplans: 3 (depth 2) │ │ │ Namespace: local/ │ │ -│ │ ├─ users Execute ●●●○ │ │ │ Resources: 2 │ │ -│ │ ├─ orders Strategize ●○○○ │ │ │ Plans: 0 │ │ -│ │ └─ auth Pending │ │ │ │ │ -│ │ │ │ │ [ ] infra-terraform │ │ -│ │ [ ] update-deps │ │ │ Namespace: local/ │ │ -│ │ Phase: Idle │ │ │ Resources: 8 │ │ -│ │ Profile: auto │ │ │ Plans: 0 │ │ -│ │ │ │ │ │ │ -│ └───────────────────────────────────────────┘ │ └──────────────────────────────────────────┘ │ -│──────────────────────────────────────────────────────────────────────────────────────────────│ -│ PERSONA CYCLE LIST (tab order) │ -│ ┌──────────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ 1. feature-dev (claude-4-sonnet, 2 projects) │ │ -│ │ 2. reviewer (gpt-4o, 1 project) │ │ -│ │ 3. infra-admin (claude-4-opus, 1 project) │ │ -│ │ [+] Add current selection as persona... │ │ -│ └──────────────────────────────────────────────────────────────────────────────────────┘ │ -│──────────────────────────────────────────────────────────────────────────────────────────────│ -│ Selected: 1 plan, 1 project │ -│ space Select │ enter Details │ ctrl+p Create Persona │ / Search │ d Delete │ esc Back │ -└──────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐ -│ ❯ What would you like to do? │ -│ ▌@▐ refs ▌/▐ commands ▌!▐ shell │ -└──────────────────────────────────────────────────────────────────────┘ - feature-dev │ claude-4-sonnet │ think: high │ 2 projects │ $0.12 - ─────────── ─ ─────────────── ─ ─────────── ─ ──────────────── ─ ───── - persona actor preset scope cost
┌──────────────────────────────────────────────────────────────────────┐ -│ Welcome to CleverAgents │ -│ │ -│ Select an actor to get started: │ -│ │ -│ ❯ anthropic/claude-4-sonnet (recommended) │ -│ anthropic/claude-4-opus │ -│ openai/gpt-4o │ -│ openai/o3 │ -│ google/gemini-2 │ -│ / to search... │ -│ │ -│ A default persona will be created with this actor. │ -│ You can add more actors and personas later. │ -│ │ -│──────────────────────────────────────────────────────────────────────│ -│ enter Select │ j/k Navigate │ / Search │ -└──────────────────────────────────────────────────────────────────────┘
┌─ Reference Picker ───────────────────────────────────────────────────┐ -│ @hand │ -│ ──────────────────────────────────────────────────────────────────── │ -│ PROJECT api-service:src/auth/handler.py │ -│ local/api-service • Python • 245 lines │ -│ │ -│ PROJECT cleveragents:git_dir/src/cli/commands/handler.py │ -│ local/cleveragents • Python • 189 lines │ -│ │ -│ PROJECT api-service:src/auth/middleware/handler_base.py │ -│ local/api-service • Python • 67 lines │ -│ │ -│ PLAN fix-auth-handler (01HXM8C2...) │ -│ Phase: Execute • Actor: claude-4-sonnet │ -│ │ -│ ──────────────────────────────────────────────────────────────────── │ -│ enter Select │ tab Tree │ ctrl+p Projects │ ctrl+l Plans │ -└──────────────────────────────────────────────────────────────────────┘
┌─ Reference Picker (Tree) ────────────────────────────────────────────┐ -│ │ -│ ▼ Projects │ -│ ▼ local/cleveragents │ -│ ▼ git_dir (git-checkout) │ -│ ▸ src/ │ -│ ▸ tests/ │ -│ ▸ docs/ │ -│ ─ pyproject.toml │ -│ ─ README.md │ -│ ▸ database (sqlite-db) │ -│ ▸ local/api-service │ -│ ▸ local/frontend-app │ -│ ▼ Plans │ -│ ▸ fix-auth-bug (01HXM8C2) │ -│ ▸ refactor-models (01HXM9D3) │ -│ │ -│ enter Select │ tab Search │ space Expand │ / Filter │ -└──────────────────────────────────────────────────────────────────────┘
┌─ Commands ─────────────────────────────────────────────────────────────┐ -│ /se │ -│ ───────────────────────────────────────────────────────────────────────│ -│ /session:create Create a new session tab │ -│ /session:list Show all sessions │ -│ /session:show Show session details │ -│ /session:switch Switch to session by ID │ -│ /session:close Close current session │ -│ /session:delete Delete a saved session │ -│ /session:rename Rename current session │ -│ /session:export Export session to file │ -│ /session:import Import session from file │ -│ /settings Open settings screen │ -│ │ -│ enter Execute │ tab Complete │ escape Dismiss │ -└────────────────────────────────────────────────────────────────────────┘