@adhd/agent-mcp 2.0.1 → 2.1.0

package/docs/architecture-and-security.md

@@ -0,0 +1,405 @@
+# Architecture and Security — @adhd/agent-mcp
+
+This document explains the system design, process model, state management, and security properties of the agent-mcp runtime.
+
+## System Boundaries
+
+```
+MCP Client (e.g., Claude Desktop)
+    |
+    | JSON-RPC (stdio)
+    v
+Agent MCP Server
+    |
+    +-- State Store (SQLite)
+    |   +-- agents
+    |   +-- sessions
+    |   +-- messages
+    |   +-- task_usage
+    |
+    +-- Policy Engine
+    |   +-- Delegation depth limits
+    |   +-- Token/cost budgets
+    |   +-- Filesystem scopes
+    |   +-- Tool filters
+    |
+    +-- Agent Supervisor
+    |   +-- Spawn management
+    |   +-- Lifecycle (running, completed, failed, cancelled)
+    |   +-- Execution traces
+    |
+    +-- Provider Adapters
+    |   +-- Anthropic (claude-opus, claude-sonnet, etc.)
+    |   +-- OpenAI (gpt-4-turbo, gpt-4o, etc.)
+    |   +-- DeepSeek (deepseek-v4-flash, deepseek-v4-pro)
+    |   +-- Gemini (gemini-2.5-pro, etc.)
+    |
+    +-- Tool Gateway
+    |   +-- Filesystem MCP tools
+    |   +-- Shell execution
+    |   +-- Network requests
+    |   +-- External MCP servers
+```
+
+The agent-mcp server is a **stateful process** that:
+1. Exposes MCP tools to create, control, and inspect agents
+2. Manages a SQLite database of agents, conversations, and execution history
+3. Enforces runtime policies before each tool call
+4. Translates between MCP and provider APIs
+5. Handles retries, cancellation, and error recovery
+
+## Process Model
+
+### Single Agent Execution
+
+```
+agent_create(name, config, provider, model, budget)
+    ↓ (validates agent name, policy, budget)
+    ↓ (creates row in agents table)
+
+task(agentName, prompt)          # optionally background: true
+    ↓ (fetches agent config and session history)
+    ↓ (constructs message list with system prompt + tools)
+    ↓ (calls provider.chat())
+    ↓ (checks if model returned tool calls)
+    ↓ if tool calls:
+    |   ├─ [for each tool]
+    |   |   ├─ policy.canCallTool(agentName, tool)? (enforced)
+    |   |   ├─ execute tool (may call external MCP servers)
+    |   |   └─ append tool result to message history
+    |   └─ goto model call (max 50 loops by default)
+    ↓
+    ├─ store all messages in sessions table
+    ├─ record usage (tokens, cost) in task_usage
+    └─ return {taskId, status, result, usage} to MCP client
+
+result(taskId)
+    ├─ fetch a task's current state and result (poll a background task to completion)
+    └─ return final result and usage
+
+task_cancel(taskId)
+    └─ mark the task as cancelled; clean up active tool calls
+```
+
+### Delegation (Parent → Child Agent)
+
+If a parent agent calls a tool that spawns a child agent:
+
+```
+parent agent (depth=0, budget=token_limit) →
+    checks child policy (subset of parent) →
+    spawns child with (depth=1, reduced budget) →
+        child runs with enforced tool/file/network restrictions →
+        child completes or hits policy limit →
+    parent receives tool result from child
+```
+
+A child agent:
+- Cannot escalate tools beyond what parent has access to
+- Cannot expand filesystem scope beyond parent's allowed paths
+- Cannot exceed its allocated token budget without failing the task
+- Cannot delegate further if `max_depth` is reached
+
+## State Model
+
+### Primary Tables (SQLite)
+
+```sql
+-- Registered agents and their configs
+agents (
+  name TEXT PRIMARY KEY,
+  provider TEXT,
+  model TEXT,
+  createdAt TIMESTAMP,
+  config JSON,           -- tool allowlist, filesystem paths, env vars, etc.
+  policy JSON            -- delegation depth, budgets, network, etc.
+);
+
+-- Sessions (conversation instances)
+sessions (
+  id TEXT PRIMARY KEY,
+  agent_name TEXT,       -- FK to agents (ON DELETE CASCADE as of 2.0.2)
+  createdAt TIMESTAMP,
+  metadata JSON
+);
+
+-- Messages (conversation history)
+messages (
+  id TEXT PRIMARY KEY,
+  session_id TEXT,       -- FK to sessions
+  role TEXT,             -- "system", "user", "assistant", "tool"
+  content TEXT,
+  toolCalls JSON,        -- [{name, arguments}] if assistant
+  toolResults JSON,      -- [{id, result}] if tool
+  createdAt TIMESTAMP
+);
+
+-- Task execution usage (tokens, cost)
+task_usage (
+  task_id TEXT PRIMARY KEY,
+  root_task_id TEXT,
+  agent_name TEXT,            -- agent that owns this task
+  provider_type TEXT,         -- provider name (e.g. "anthropic", "openai")
+  model TEXT,                 -- model identifier
+  input_tokens INTEGER,       -- cumulative across all model calls in this task (SUM, not MAX)
+  output_tokens INTEGER,      -- cumulative across all model calls (SUM)
+  tool_call_count INTEGER,    -- total tool invocations in this task
+  model_calls INTEGER,        -- total model API calls made
+  latency_ms INTEGER,         -- wall-clock time from task start to completion
+  is_complete INTEGER,        -- 0/1 flag: task reached terminal state
+  stop_reason TEXT,           -- "tool_calls", "end_turn", "error", etc.
+  max_tokens INTEGER,         -- configured max_tokens for this model
+  cache_read_input_tokens INTEGER,       -- cache-hit tokens (2.0.2+; Anthropic: cache_read, DeepSeek: prompt_cache_hit)
+  cache_creation_input_tokens INTEGER,   -- cache-write surcharge (2.0.2+; Anthropic only; DeepSeek/OpenAI: 0 or null)
+  uncached_input_tokens INTEGER,         -- full-price tokens (cache-miss rate; 2.0.2+)
+  reasoning_tokens INTEGER,              -- inference tokens from reasoning models (2.0.2+)
+  peak_context_tokens INTEGER,           -- MAX single-call prompt size across all calls (2.0.2+; THE number for "am I near the ceiling?")
+  peak_context_at INTEGER,               -- which model-call number (1-based) hit the peak (2.0.2+)
+  created_at TEXT                        -- task creation timestamp
+);
+```
+
+### Message Windowing (2.0.2+)
+
+The system keeps conversation history **append-only** by default:
+
+1. **Cold start** (first model call): system prompt + user message
+2. **Subsequent calls**: all prior messages + new user message
+3. **When context approaches limit** (via provider's exact `prompt_tokens`):
+   - Summarize middle messages into one synthetic assistant message
+   - Keep leading messages (system + early context) unchanged
+   - Keep trailing messages (recent turns) unchanged
+   - Never evict from the front again for this task
+
+**Why:** Providers cache the leading prefix; evicting from the front breaks the cache and makes subsequent calls much more expensive. Collapsing the middle exactly once preserves the cache while reducing history size.
+
+## Provider Abstraction
+
+All providers implement a common interface:
+
+```typescript
+interface ProviderAdapter {
+  chat(request: ChatRequest): Promise<ChatResponse>;
+  // ChatRequest: {model, messages, tools, temperature, max_tokens, ...}
+  // ChatResponse: {content, tool_calls, usage: {inputTokens, outputTokens, ...}, stopReason}
+}
+```
+
+### Provider-Specific Differences
+
+| Aspect | Anthropic | OpenAI | DeepSeek | Gemini |
+|---|---|---|---|---|
+| **Token accounting** | `inputTokens` excludes cache tokens; must sum `cache_read_input_tokens` + `cache_creation_input_tokens` | `prompt_tokens` includes cached tokens (subset field) | `prompt_tokens` includes cached tokens; provides `prompt_cache_hit_tokens` + `prompt_cache_miss_tokens` | `promptTokenCount` includes cached tokens |
+| **Cache pricing** | Write: 1.25x (5m) / 2x (1h); Read: 0.1x | Write: 1.25x (GPT-5.6+); Read: standard cached rate | Write: none; Read: $0.0028/M cache-hit vs $0.14/M miss | Write: standard; Read: 90% discount + hourly storage rent |
+| **Tool definitions** | Always JSON-schema function-calling (native) | Always JSON-schema (native) | Always JSON-schema (native) | Supports both `function_declarations` (native) and custom descriptions |
+| **Cancellation** | Partial (can cancel in-flight requests; doesn't stop model thinking if already started) | Partial | Partial | Yes |
+| **Streaming** | Yes (native) | Yes (native) | Yes (native) | Yes |
+| **Per-call tool restriction** | None; any tool-set change busts cache | `allowed_tools` filter (cache-safe) | None; any tool-set change busts cache | None; any tool-set change busts cache |
+
+## Permission Model
+
+### Agent Policy Structure
+
+```typescript
+type AgentPolicy = {
+  // Delegation
+  maxDepth: number;              // 0 = leaf only; 1 = can spawn 1 level; etc.
+  maxChildren: number;           // max agents spawned by this one
+  
+  // Budgets
+  maxTokensPerTask: number;      // fail if cumulative tokens exceeded
+  maxCostUsdPerTask: number;     // fail if cumulative cost exceeded
+  wallClockTimeoutMs: number;    // hard timeout
+  
+  // Tool access
+  tools: {
+    allow: string[];             // tool names agent can call
+    deny: string[];              // explicit deny (takes precedence)
+    requireApproval: string[];    // ask user before calling
+  };
+  
+  // Filesystem
+  filesystem: {
+    read: string[];              // absolute paths or glob patterns
+    write: string[];             // (recommended: empty; writes require approval)
+  };
+  
+  // Network
+  network: {
+    enabled: boolean;
+    allowedHosts?: string[];      // allowlist; if present, ONLY these hosts
+  };
+  
+  // Environment
+  environment: {
+    allow: string[];             // env var names agent can read (must be ADHD_AGENT_* prefixed)
+  };
+};
+```
+
+### Permission Inheritance
+
+Child agents inherit a **subset** of parent permissions:
+
+```typescript
+function isValidChildPolicy(parentPolicy, childPolicy) {
+  // Tools: child.allow must be subset of parent.allow
+  return childPolicy.tools.allow.every(tool => 
+    parentPolicy.tools.allow.includes(tool)
+  );
+  
+  // Budget: child must have stricter or equal budget
+  // Path: child paths must be subset of parent paths
+  // Network: if parent disables network, child can't enable it
+}
+```
+
+**Enforcement points:**
+
+| Control | Enforced by | Check point |
+|---|---|---|
+| Tool allowlist | Runtime | `pre:tool_call` hook before model response |
+| Filesystem read | Runtime | MCP tool adapter (filesystem__read_text_file, etc.) |
+| Filesystem write | Runtime | MCP tool adapter (filesystem__write_text_file, etc.) |
+| Network request | Runtime | Network tool wrapper |
+| Token budget | Runtime | After every model call; fail if exceeded |
+| Cost budget | Runtime | After every model call; fail if exceeded |
+| Delegation depth | Runtime | In `agent_create` hook |
+| Environment variables | Runtime | In provider credential resolution (ADHD_AGENT_* prefix check) |
+| Tool approval | Runtime | Human interaction hook (if requireApproval includes tool) |
+
+## Failure Recovery
+
+### Hard Failures (Task terminates immediately)
+
+- `MAX_DEPTH_EXCEEDED` — tried to spawn agent deeper than max_depth
+- `MAX_TOOL_LOOPS_EXCEEDED` — exceeded 50 (configurable) tool-call rounds
+- `TOKEN_BUDGET_EXCEEDED` — cumulative tokens > budget
+- `COST_BUDGET_EXCEEDED` — estimated cost > budget
+- `CONTEXT_WINDOW_EXCEEDED` — provider rejected: prompt too long (shouldn't happen with 2.0.2+)
+- `POLICY_VIOLATION` — tool call denied by policy
+
+### Soft Failures (Retry with backoff)
+
+- Transient provider errors (rate limits, timeouts < configured limit)
+- Network errors with deterministic retry logic
+
+### Crash Recovery
+
+If the agent-mcp server process crashes:
+
+- Completed tasks are persisted; results are intact
+- Running tasks are marked `cancelled` on next server start
+- The MCP client must decide whether to retry or inspect partial results
+
+## Cancellation Semantics
+
+```
+task_cancel(taskId)
+    ↓
+    └─ if task is running:
+        ├─ cancel in-flight provider request (if provider supports it)
+        ├─ don't process any tool results from that request
+        ├─ mark task as cancelled
+        └─ don't attempt retry
+```
+
+Cancellation is **best-effort**:
+- If the model is already generating output, the cancellation may arrive too late
+- In-flight tool calls that started before cancellation may complete
+- Results are marked as cancelled; the task does not resume
+
+## Trust Boundaries
+
+### Things agent-mcp Can Control
+
+- Which tools the model sees and is allowed to call
+- Which filesystem paths are readable/writable
+- Which environment variables are accessible
+- Which hosts can be contacted
+- When the agent is allowed to delegate
+- Token and cost limits
+- Timeouts
+
+### Things agent-mcp Cannot Control (Prompt-Level Only)
+
+- Whether the model attempts to escape its tool restrictions via prompt injection
+- Whether the model makes up fake tool calls or results
+- Whether the model's reasoning matches its declared intent
+- The content of model outputs (can only reject, not redact)
+
+**Important:** Tool filtering, filesystem restrictions, and network allowlists are **policy enforcement, not security sandboxes**. A model that understands or breaks its constraints can circumvent them. These are *behavioral controls*, not *OS-level isolation*.
+
+### Things agent-mcp Cannot Control (Architecture Limitation)
+
+- Access by the host process itself (agent-mcp runs with the same OS permissions as its parent)
+- Indirect attacks via side-channels or timing
+- Modifications to the state database by other processes
+- Secret leakage via inference-time data (e.g., the model reasoning about secrets in prompts)
+
+## Current Limitations
+
+### 1. No OS-Level Sandboxing
+
+Agent-mcp enforces policies in code, not via OS mechanisms. A buggy or malicious agent can still:
+- Read any file the host process can read
+- Execute any command the host process can execute
+- Contact any host the network allows
+
+Mitigation: Run agent-mcp in a container, VM, or isolated user account if you need OS-level isolation.
+
+### 2. No External Security Audit
+
+This is research-grade software. There has been no formal security review by external auditors. Treat it as experimental.
+
+### 3. Prompt Injection is Not Mitigated
+
+A model can sometimes escape tool restrictions by creative prompting. For example:
+
+```
+User: Read the .env file
+Agent: [Denied: .env not in allowed paths]
+Agent's reasoning: "The user asked for .env, but my policy forbids it. 
+                    However, if I call read_dir('/'), I can see all files, 
+                    including .env, and the user can parse the directory listing."
+```
+
+Tool filtering is a **guidance mechanism**, not a security boundary.
+
+### 4. Single-User Isolation Only
+
+The SQLite database is shared by all MCP clients. There is no per-user access control:
+- One MCP client can inspect any agent created by another
+- One MCP client can cancel another's tasks
+- All clients see all agents in `agent_list`
+
+Mitigation: Run separate agent-mcp instances if you need user isolation, or put them behind a per-user authentication proxy.
+
+### 5. Experimental State Recovery
+
+Agent state recovery after a crash is partially implemented. Assume potential data loss on ungraceful shutdown.
+
+## Security Assumptions
+
+1. **Hosting process is trusted** — the agent-mcp server process itself has not been compromised
+2. **Model outputs are partially trusted** — we assume the model generally follows instructions, though creative prompt injection may bypass restrictions
+3. **Filesystem permissions are set correctly** — the host OS permissions are the outer boundary
+4. **Secrets in the environment are protected** — environment variables passed to agents are not logged or persisted in plaintext in messages
+5. **Network connectivity is configured safely** — the network allowlist is the primary control; no external proxy or WAF is assumed
+
+## Related Documentation
+
+- **Provider Prompt Caching**: See `docs/ideas/provider-caching-research.md` in the monorepo for multi-provider cache analysis and the 2.0.2 context-management fix
+- **Context Management Strategy**: See `docs/ideas/context-and-cache-strategy.md` in the monorepo for design rationale and wire-trace evidence
+- **BACKLOG**: Bugs, findings, and regressions are logged in the monorepo's `BACKLOG.md`
+
+## Recommendations for Production Use
+
+As of 2.0.2:
+
+- **No**. This is experimental, research-grade software.
+- **For research/local development**: Reasonable with the limitations above understood.
+- **For production serving untrusted users**: Not recommended until external security audit is completed and OS-level sandboxing is added.
+- **For production serving only trusted internal agents**: Acceptable if you own the host and the network.
+
+See also: `agent-mcp-recommendation-evidence-requirements.md` in the monorepo `docs/agent-mcp/` directory for a checklist of evidence/features needed before this software is recommended for broader use.

package/docs/marketing/.catalog/capabilities.md

@@ -0,0 +1,143 @@
+# @adhd/agent-mcp — Shipped Capabilities (v2.0.0)
+
+## Summary
+
+- **Total shipped capabilities:** 33
+- **MCP Tools (RPC endpoints):** 17 tools (agent mgmt, session mgmt, task execution, usage querying, guide)
+- **HTTP Endpoints:** 2 (/v1/chat/completions, /v1/models) — OpenAI-compatible
+- **Storage & Config:** SQLite schema, env config hierarchy, logging, registry compiler integration
+- **Provider Support:** 4 providers (OpenAI, Anthropic, DeepSeek, Claude CLI)
+- **Advanced:** Agent delegation (recursive multi-agent DAG), HITL suspension, background task execution, tool advertisement (name-only vs full)
+
+**Last verified:** 2026-07-12, commit 7c400a7
+**Test coverage:** 19 passed (5 wiring unit tests + 14 tool-advertisement tests); 4 live e2e tests skipped (gated behind AGENT_MCP_LIVE=1)
+
+---
+
+## Agent Management
+
+| Capability | Status | Tested | Substance | Notes |
+|-----------|--------|--------|-----------|-------|
+| Agent Create | ✅ shipped | ✓ wiring.test | moderate | Validates ADHD_AGENT_* env-var prefix; version:1 initial |
+| Agent Read | ✅ shipped | ✓ wiring.test | trivial | Fetches by name |
+| Agent Update | ✅ shipped | ✓ wiring.test | moderate | Session isolation: new sessions only; bumps version |
+| Agent Delete | ✅ shipped | ✓ wiring.test | moderate | force:true for cleanup; BUG-ORCH-012: FK cascade missing |
+| Agent List | ✅ shipped | ✓ wiring.test | trivial | Returns all stored definitions |
+
+## Session Management
+
+| Capability | Status | Tested | Substance | Notes |
+|-----------|--------|--------|-----------|-------|
+| Instantiate Agent | ✅ shipped | ✓ wiring.test | moderate | Creates session; snapshots agent at creation time |
+| Session List | ✅ shipped | ✓ wiring.test | trivial | Filter by agent_name, status |
+| Session Close | ✅ shipped | ✓ wiring.test | trivial | Marks closed; persists final state |
+| Session Clear | ✅ shipped | ✓ wiring.test | moderate | Deletes message history; preserves session + agent snapshot |
+
+## Task Execution
+
+| Capability | Status | Tested | Substance | Notes |
+|-----------|--------|--------|-----------|-------|
+| Task Run (MCP) | ✅ shipped | ✓ wiring.test | substantial | Dual-mode: session-stateful (sync/async) or agent-ephemeral (sync); tool calling loop, delegation, provider switching, caching |
+| Task List | ✅ shipped | ✓ wiring.test | trivial | Filter by session_id, status, agent_name |
+| Task Cancel | ✅ shipped | ✓ wiring.test | moderate | Guard: only pending/running |
+| Task Resume | ✅ shipped | ✓ wiring.test | moderate | Resumes HITL-suspended task; validates resumeToken |
+| Result Read | ✅ shipped | ✓ wiring.test | trivial | Polls task status + result |
+
+## Querying & Introspection
+
+| Capability | Status | Tested | Substance | Notes |
+|-----------|--------|--------|-----------|-------|
+| Usage Query | ✅ shipped | ✓ wiring.test | moderate | Filters: task_id (recursive), agent_name, since; group_by (agent\|model\|provider) |
+| Guide | ✅ shipped | ✓ wiring.test | trivial | Built-in help: 5 workflows, provider table, error codes |
+
+## HTTP Endpoints (OpenAI-Compatible)
+
+| Endpoint | Status | Tested | Substance | Notes |
+|----------|--------|--------|-----------|-------|
+| POST /v1/chat/completions | ✅ shipped | ❌ no test | substantial | Streaming (SSE); stateless HTTP→stateful session bridging |
+| GET /v1/models | ✅ shipped | ❌ no test | trivial | Lists available models |
+
+## Providers
+
+| Provider | Status | Tested | Substance | Notes |
+|----------|--------|--------|-----------|-------|
+| OpenAI (+ compatible) | ✅ shipped | ✓ config.test | substantial | Prompt caching, base_url override for LM Studio/DeepSeek/Ollama |
+| Anthropic (Claude) | ✅ shipped | ✓ config.test | substantial | Prompt caching + compaction, 5m/1h breakpoints |
+| DeepSeek (OpenAI-compatible API) | ✅ shipped | ✓ config.test | substantial | Prefix-based cache, no write premium |
+| Claude CLI (local) | ✅ shipped | ❌ no test | substantial | Always full tool schema; requires local `claude` binary |
+
+## Advanced Features
+
+| Feature | Status | Tested | Substance | Notes |
+|---------|--------|--------|-----------|-------|
+| Agent Delegation (Recursive Multi-Agent) | ✅ shipped | ❌ live-dag.e2e skipped | substantial | In-process agent__* tool dispatch; DAG cycle detection; max depth/tool loops policies |
+| HITL (Human-in-the-Loop) Suspension | ✅ shipped | ❌ no test | substantial | awaiting_input status, resumeToken, task_resume |
+| Background Task Execution | ✅ shipped | ✓ wiring.test | moderate | Async + polling; orphaned-task recovery at startup |
+| Tool Advertisement (name-only vs full) | ✅ shipped | ✓ tool-advertisement.test (14 tests) | substantial | Default 'names' (~1600 tokens/turn savings via caching), per-agent override |
+| MCP Server Bindings | ✅ shipped | ❌ live-dag.e2e skipped | substantial | Stdio-based external MCP servers; tool name prefixing; allowedTools filtering |
+| Environment Security (Prefix Guard) | ✅ shipped | ✓ config.test | substantial | ADHD_AGENT_* enforcement; BUG-ORCH-011: guard restored at create time |
+| Registry Compiler Integration | ✅ shipped | ✓ config.test | moderate | Optional; graceful fallback to flat prompts |
+
+## Storage & Configuration
+
+| Feature | Status | Tested | Substance | Notes |
+|---------|--------|--------|-----------|-------|
+| Persistent Storage (SQLite) | ✅ shipped | ✓ wiring.test | moderate | agents, sessions, tasks, task_events, task_usage; WAL mode; BUG-ORCH-012: FK cascade missing |
+| Environment Config (Hierarchical .env) | ✅ shipped | ✓ config.test | moderate | .adhd/.env, .env, system; ADHD_AGENT_* prefixed |
+| Structured Logging (Pino) | ✅ shipped | ✓ config.test | trivial | Configurable via ADHD_AGENT_LOG_LEVEL |
+| SSE Task Streaming | ✅ shipped | ❌ no test | substantial | Real-time task/completed notifications on separate port |
+
+---
+
+## Test Coverage by File
+
+**Unit Tests (19 passed):**
+- `wiring.test.ts` (5 tests): Config load, agent CRUD, session CRUD, task CRUD, logger init
+- `tool-advertisement.test.ts` (14 tests): Name-only rendering, no SECRET leakage, full schema fallback, etc.
+
+**Live E2E Tests (4 skipped, gated AGENT_MCP_LIVE=1):**
+- `live-dag.e2e.test.ts`: Recursive multi-agent coordinator→fanout→workers with real model
+- `live-oauth.e2e.test.ts`: OAuth flow (provider integration)
+- `live-budget.e2e.test.ts`: Budget plugin (token limit enforcement)
+- (Other integration fixtures: `fixtures/calc-server.mjs` — stdio MCP server for recursion testing)
+
+---
+
+## Known Issues & Blockers
+
+**Security (HIGH):**
+- **BUG-ORCH-011:** Env-var-name allowlist guard dropped in schema refactor → re-added only at create time (defense-in-depth weakened but not fully broken)
+
+**Data Integrity (HIGH):**
+- **BUG-ORCH-012:** Missing agents→sessions FK cascade on delete → agent_delete leaves sessions orphaned forever
+
+**Behavior (MEDIUM):**
+- **BUG-ORCH-013:** toolAdvertisement default changed from 'full' to 'names' for non-claudecli agents → 100% of existing agents silently switch wire format on upgrade (intentional default-value choice, but silent)
+
+**Configuration (LOW-MEDIUM):**
+- **BUG-ORCH-014:** Global plugin config path renamed ~/.agent-mcp/config.json → ~/.adhd/agent-mcp/config.json; old path never checked → users with existing global config silently get zero plugins
+
+---
+
+## Unverified (No Test)
+
+Capabilities shipped but lacking a default-running test:
+
+1. `http-openai-chat-gateway` — needs HTTP smoke test (curl/client)
+2. `http-models-endpoint` — needs HTTP GET test
+3. `provider-claudecli` — needs claude CLI installed
+4. `mcp-server-bindings` — verified live-dag.e2e exists but skipped (AGENT_MCP_LIVE=1 only)
+5. `agent-delegation` — verified live-dag.e2e exists but skipped
+6. `hitl-suspension` — no integration test exists
+7. `stream-sse-task-events` — needs SSE client + server smoke test
+
+→ **Action:** These 7 capabilities need test coverage written and integrated into default CI runs (or explicitly documented as intentionally live-only with approval).
+
+---
+
+## Version & Distribution
+
+- **Package:** @adhd/agent-mcp v2.0.0 (unpublished; 2.0.1 is published on npm)
+- **Bin:** `agent-mcp` (Node entry) + `agent-mcp-tail` (log streaming)
+- **Main:** src/index.ts (MCP server + HTTP gateway wiring)
+- **Built to:** dist/entrypoint/agent-mcp (Nx build output)

package/docs/marketing/.catalog/consumer.md

@@ -0,0 +1,111 @@
+# Doc Consumer Test — @adhd/agent-mcp 2.0.2
+
+**Test Date:** 2026-07-12  
+**Tester:** doc-consumer agent  
+**Scope:** README.md, CHANGELOG.md, AGENTS.md, llms.txt, architecture-and-security.md
+
+**Summary:** 3/3 canonical tasks PASSED using documentation alone (no source code access).
+
+---
+
+## Task 1: Quick-Start Installation & First Agent
+
+**Intent:** A developer with OpenAI API key installs the package, starts the MCP server, creates agents (Anthropic + OpenAI), sends tasks, and retrieves results.
+
+**Documentation sections consulted:**
+- README.md: Installation, quick-start example, environment variables
+- AGENTS.md: MCP tool list (agent_create, task, result signatures)
+- llms.txt: Configuration reference
+
+**Deliverable test:**
+```bash
+npm install -g @adhd/agent-mcp
+ADHD_AGENT_PROVIDER=anthropic ADHD_AGENT_MODEL=claude-opus-4-1 ANTHROPIC_API_KEY=<key> agent-mcp
+```
+
+Then (via MCP client):
+1. `agent_create(name: "research", config: {...provider: "anthropic", model: "claude-opus-4-1", ...})`
+2. `agent_create(name: "coder", config: {...provider: "openai", model: "gpt-4-turbo", ...})`
+3. `task(agentName: "research", prompt: "Analyze this paper")` → taskId
+4. `result(taskId: "...")` → {status, result, usage}
+
+**Result:** ✅ **PASS**
+
+All commands documented with correct syntax. Field names (e.g., `cacheReadTokens`) match AGENTS.md and CHANGELOG.md. Real JSON-RPC example in README.md shows exact call syntax. No invented tools (agent_message/agent_wait removed in 2.0.2 corrections). Configuration env vars clearly listed.
+
+---
+
+## Task 2: Provider Migration (Anthropic → DeepSeek)
+
+**Intent:** A user switches from Anthropic to DeepSeek; needs to know configuration changes and behavioral differences in token accounting/caching.
+
+**Documentation sections consulted:**
+- llms.txt: Supported providers table
+- README.md: Environment variables (ADHD_AGENT_PROVIDER, ADHD_AGENT_MODEL)
+- CHANGELOG.md: BUG-ORCH-009/010 (provider-neutral token accounting changes)
+- AGENTS.md: New token fields (cacheReadTokens, uncachedInputTokens, cacheCreationTokens)
+
+**Deliverable test:**
+```bash
+# Before:
+ADHD_AGENT_PROVIDER=anthropic ADHD_AGENT_MODEL=claude-opus-4-1 ANTHROPIC_API_KEY=<key>
+
+# After:
+ADHD_AGENT_PROVIDER=openai ADHD_AGENT_MODEL=deepseek-v4-flash DEEPSEEK_API_KEY=<key> OPENAI_API_BASE_URL=https://api.deepseek.com/v1
+```
+
+Expected behavioral differences:
+- Token accounting: `cacheReadTokens` (DeepSeek: prompt_cache_hit) vs. `cacheCreationTokens` (none for DeepSeek)
+- Caching: DeepSeek automatic prefix-cache (50x hit:miss price difference per provider-caching-research.md)
+- Context management: 2.0.2 append-only history (vs 2.0.1's front-eviction that busted cache)
+
+**Result:** ✅ **PASS**
+
+README and AGENTS.md document provider table. CHANGELOG 2.0.2 section clearly explains normalized token fields and their provider-dependent meanings. DeepSeek's cache behavior mentioned in architecture-and-security.md with link to provider-caching-research.md. User can make the switch without source reading.
+
+---
+
+## Task 3: Debugging Token Usage (Advanced)
+
+**Intent:** User sees usage report with `inputTokens: 715316`, `peakContextTokens: 43187`, `cacheReadTokens: 525056`, `uncachedInputTokens: 190260`. Needs to understand: which number is for "am I close to the context window?" and what each means.
+
+**Documentation sections consulted:**
+- AGENTS.md: Token Accounting section (2.0.2 Changes)
+- CHANGELOG.md: BUG-ORCH-008 (3.3x cost inflation from cache busting) and BUG-ORCH-009/010 (new token fields)
+- architecture-and-security.md: task_usage schema with field descriptions
+- llms.txt: 2.0.2 highlights
+
+**Deliverable test:**
+
+Role of each field:
+- `inputTokens` (715316): **Cumulative billed input** across all model calls (FINDING-ORCH-007: NOT a context size)
+- `peakContextTokens` (43187): **MAX prompt size in any single call** — the number for "am I close to the 1M-token DeepSeek ceiling?" (this is the answer)
+- `cacheReadTokens` (525056): **Cache-hit tokens** (discounted; 50x cheaper than cache-miss)
+- `uncachedInputTokens` (190260): **Full-price tokens** (cache-miss; the expensive ones)
+- `cacheCreationTokens`: Anthropic surcharge (0 for DeepSeek)
+
+**Result:** ✅ **PASS**
+
+CHANGELOG BUG-ORCH-008 explicitly explains the distinction (cumulative != context size). CHANGELOG BUG-ORCH-009/010 documents each new field. AGENTS.md provides the table with field meanings. Architecture doc schema block shows DB columns + comments. User can distinguish what `peakContextTokens` is for without guessing. The old bug's lesson (measuring cost as context) is corrected in the 2.0.2 release notes.
+
+---
+
+## Summary
+
+| Task | Outcome | Notes |
+|------|---------|-------|
+| Quick-Start | ✅ PASS | Exact install/config/tool-call examples; no invented tools |
+| Provider Migration | ✅ PASS | Configuration env vars clear; token-accounting differences explained |
+| Token Usage Debugging | ✅ PASS | New 2.0.2 fields documented; cumulative vs. peak distinction clear |
+
+**All canonical tasks completed using ONLY documentation. No source code required.**
+
+---
+
+## Notes
+
+- The 2.0.2 corrections (16 real tools, correct field names, real quickstart JSON-RPC, 3-path plugin fallback chain, accurate schema) eliminated all gaps that would have forced source code reading.
+- Remaining gap (SSE streaming endpoint undocumented) is acceptable for this release; flagged in metrics.md as ACTION ITEM for post-2.0.2 phase.
+- Link integrity verified except for non-existent LICENSE file (noted in metrics.md as separate issue).
+
+**Verdict: Consumer usability PASS. Documentation is sufficient for independent agent or developer use.**