@cohortapp/agent-sdk 2.3.0

package/docs/guides/agents-observe-setup.md

@@ -0,0 +1,64 @@
+# Agents Observe — Multi-Agent Observability Dashboard
+
+Real-time dashboard for monitoring Claude Code agent teams. Captures tool calls, agent hierarchy, and session state via background hooks with SQLite storage.
+
+## Why It Matters
+
+Maestro agents run parallel backlog execution with multiple subagents. Currently debugging relies on post-hoc JSONL log scanning. Agents Observe provides real-time visibility into:
+
+- **Live tool calls** across all active agents
+- **Agent hierarchy trees** showing parent/child relationships
+- **Search and filter** across sessions and tool invocations
+- **WebSocket-streamed UI** with 3-5ms latency
+
+## Installation
+
+### Via install-dev-tools (recommended)
+
+```bash
+./scripts/setup/install-dev-tools.sh --tool agents-observe
+```
+
+### Manual
+
+```bash
+# As Claude Code plugin
+claude plugin install agents-observe
+
+# Or global npm
+npm install -g agents-observe
+```
+
+## Usage
+
+### Start the dashboard
+
+```bash
+agents-observe serve
+# Opens dashboard at http://localhost:3847
+```
+
+### View active agent sessions
+
+Navigate to the dashboard URL. Active sessions appear automatically when Claude Code agents run with the plugin enabled.
+
+### Query session history
+
+```bash
+agents-observe query --session <id>
+agents-observe query --tool Write --last 1h
+```
+
+## Integration with Maestro
+
+Best used during:
+- **Backlog executor cycles** — monitor parallel agent performance
+- **Debugging agent failures** — trace tool call sequences leading to errors
+- **Performance profiling** — identify slow or redundant tool calls
+
+Not recommended as always-on in production (SQLite write overhead). Enable on-demand for debugging and profiling sessions.
+
+## Repository
+
+- GitHub: https://github.com/simple10/agents-observe
+- License: MIT

package/docs/guides/billing-console-keys.md

@@ -0,0 +1,88 @@
+# Billing: per-agent Console API keys in capped workspaces
+
+Status: **action required by 2026-06-15** — verify against the current Anthropic
+support article before acting (see step 0). This guide is the Phase-0 (item 0.1)
+operator runbook pulled forward from Router Phase 1 of the enterprise roadmap.
+
+## Why this exists
+
+A maestro fleet runs one headless Claude Code instance per agent. Two billing
+rails are possible today (`.env.example`):
+
+- **API key** — `ANTHROPIC_API_KEY` set; pay-per-token, billed to the org's
+  Console account.
+- **Subscription OAuth** — `MAESTRO_PREFER_SUBSCRIPTION_AUTH=1` with the key left
+  empty; each Mac mini's Claude Code Pro/Max seat authorizes its sessions via the
+  Keychain OAuth token.
+
+The subscription rail is attractive at a few agents but does not scale to a
+40–60-agent fleet: it ties spend to per-seat plans with no per-agent ceiling, no
+central spend visibility, and no programmatic budget enforcement — and an
+Anthropic Agent-SDK credit change (the "June 15 cutover") removes its economic
+advantage for headless traffic. The enterprise rail is **per-agent Console API
+keys, each scoped to a workspace with a hard spend cap**, which gives the org a
+spend ceiling per agent that survives local-state corruption or a budget-guard
+bug, plus a single place (the Admin Cost API) to reconcile fleet spend.
+
+## Step 0 — verify the cutover (do this first)
+
+The exact terms and date of the Agent-SDK credit change are sourced from a single
+Anthropic support article and must be re-confirmed before you migrate:
+<https://support.anthropic.com/> (search "Agent SDK credits" / "Claude Code
+billing"). If the article's terms differ from the assumptions here, adjust the
+plan — do not migrate blind. Record what you confirmed and when.
+
+## Step 1 — workspaces with spend caps (Console, human-only)
+
+In the Anthropic Console (<https://console.anthropic.com/>), for each agent (or
+each cost-center grouping of agents):
+
+1. Create a **workspace** named for the agent or team.
+2. Set a **monthly spend limit** on the workspace (this is the hard ceiling that
+   does not depend on any maestro-side guard).
+3. Create an **API key inside that workspace** — this key's usage counts against
+   the workspace cap.
+
+Keep a separate, low-cap **break-glass workspace** holding each agent's
+terminal-fallback key (≈$25/day), so the safety-net path can never run away.
+
+## Step 2 — put the key on the agent's Mac mini
+
+On each agent machine, set the workspace key and turn the subscription rail off:
+
+```sh
+# ~/<agent>-ai/.env
+ANTHROPIC_API_KEY=sk-ant-api03-<this-agent's-workspace-key>
+# remove or unset the subscription preference:
+# MAESTRO_PREFER_SUBSCRIPTION_AUTH=
+```
+
+`.env` must be `chmod 600` (doctor enforces this — see roadmap item 0.11). Never
+commit keys; never reuse one workspace key across agents (per-agent keys are what
+make per-agent spend attribution and revocation possible).
+
+## Step 3 — verify
+
+```sh
+maestro doctor      # validates ANTHROPIC_API_KEY against api.anthropic.com
+```
+
+After the cost-telemetry work (roadmap item 0.3) lands, `maestro doctor` also
+turns RED when sessions have run but recorded spend is $0, and a nightly digest
+reconciles the local ledger against the Admin Cost API. Until then, confirm spend
+is accruing in the Console workspace view for a canary agent.
+
+## What is automated vs human
+
+maestro cannot create Console workspaces or keys for you — that requires a human
+with Console access (steps 0–1). maestro's side of this rail is: reading
+`ANTHROPIC_API_KEY` per agent (already wired), the doctor key/`.env`-mode checks,
+and the cost ledger + reconcile that make the workspace caps observable. Those
+land in Router Phases 1–4; this runbook is the credential rail they sit on.
+
+## Related
+
+- `docs/guides/model-routing.md` — how sessions choose a backend.
+- `docs/audit/2026-06-10-enterprise/synthesis/SPEC-llm-router.md` — full router
+  spec; §11 Phase 1 covers billing, ledger v2, and the break-glass workspace.
+- `docs/audit/2026-06-10-enterprise/synthesis/ROADMAP.md` — item 0.1 and WS-R.

package/docs/guides/ccxray-diagnostics.md

@@ -0,0 +1,65 @@
+# ccxray Diagnostics Guide
+
+ccxray provides X-ray vision into Claude Code sessions via a transparent HTTP proxy and live dashboard. It intercepts all API calls between Claude Code and Anthropic, giving you detailed token/cost analysis, timing breakdowns, and system prompt visibility.
+
+## When to Use
+
+- Debugging expensive sessions (high token burn, unexpectedly long runs)
+- Understanding which tool calls consumed the most tokens
+- Comparing system prompts across main agent and sub-agents
+- Investigating context window utilisation and heatmaps
+- Post-incident analysis of failed or timed-out sessions
+
+## What It Shows
+
+- Real-time timeline of agent turns with thinking durations
+- Per-turn token and cost breakdown with burn rate tracking
+- Context window heatmaps showing what's consuming space
+- System prompt diffs across main agent and sub-agents
+- Multi-project hub: multiple terminals share one dashboard
+- Full JSON logging of every request/response to `~/.ccxray/logs/`
+
+## Technical Details
+
+- Zero-config transparent HTTP proxy
+- Launches Claude Code through the proxy automatically
+- Web dashboard for live monitoring
+- JSON log files for post-hoc analysis
+- npx-based — no permanent installation required
+
+## Usage
+
+### Quick start
+
+```bash
+# Launch Claude Code through the ccxray proxy
+npx ccxray claude
+```
+
+This starts the proxy, opens the dashboard, and launches Claude Code. All API traffic flows through ccxray for inspection.
+
+### With an existing session
+
+```bash
+# Start the proxy on a specific port
+npx ccxray --port 8080
+```
+
+### Viewing logs
+
+Logs are stored at `~/.ccxray/logs/` as JSON files, one per session. These can be analysed post-hoc for cost attribution.
+
+## Repository
+
+- GitHub: https://github.com/lis186/ccxray
+- License: MIT
+
+## Integration with Maestro
+
+ccxray is a diagnostic tool, not a runtime dependency. It is not installed by default via `init-agent.sh` but is available on-demand via npx.
+
+Use cases for Maestro operators:
+- **Token budget audit**: Run a backlog cycle through ccxray to see per-task token costs
+- **Sub-agent analysis**: Compare token usage across spawned background agents
+- **Prompt debugging**: Inspect what system prompts sub-agents actually receive
+- **Cost optimisation**: Identify which tool calls are disproportionately expensive

package/docs/guides/channel-bus.md

@@ -0,0 +1,127 @@
+# Channel bus — unified Slack / Gmail / WhatsApp / SMS / Voice abstraction
+
+The channel bus lets every communication channel speak through one
+interface. It's **additive** — existing pollers and senders continue to
+work; the bus sits alongside them and is the recommended entry point
+for new channels (voice, future iMessage/Telegram/Discord plugins).
+
+## When to use it
+
+- You want to send to channel X but don't want to hard-code which
+  script handles channel X.
+- You're adding a new channel and need it to slot into the existing
+  inbox / classifier / dispatcher flow without modifying them.
+- You need cross-channel conversation tracking — e.g. a Gmail thread
+  and a Slack DM that are really the same conversation should share
+  a session lock.
+
+## Pieces
+
+| File | Role |
+|------|------|
+| `lib/channels/channel.mjs` | Interface definition + capability constants |
+| `lib/channels/conversation-resolver.mjs` | Pure mapper from inbound message → conversation key |
+| `lib/channels/registry.mjs` | In-process channel registry |
+| `lib/channels/<service>/adapter.mjs` | Concrete adapter per channel |
+| `lib/channels/index.mjs` | `createChannel(name, opts)` lazy factory |
+
+## The Channel interface
+
+```ts
+interface Channel {
+  name: string;
+  capabilities: CHANNEL_CAPABILITIES[];
+  start(opts: { onInbound: (msg: ChannelMessage) => void, signal?: AbortSignal }): Promise<void>;
+  send(msg: OutboundMessage): Promise<{ message_id: string }>;
+  react?(opts: { messageRef: string, emoji: string }): Promise<void>;
+  fetchAttachment?(opts: { url: string }): Promise<Buffer>;
+  healthCheck(): Promise<{ ok: boolean, detail?: string }>;
+  stop(): Promise<void>;
+}
+```
+
+Capabilities are advertised so callers can ask, "which channel can
+send a voice note?" via
+`findChannelsWithCapability(CHANNEL_CAPABILITIES.VOICE_NOTE)`.
+
+## Adapters today
+
+| Channel | Adapter | Transport options |
+|---------|---------|--------------------|
+| Slack   | `lib/channels/slack/adapter.mjs` | Socket Mode (reactions, thread context, opt-in channel CC) + state/inbox/slack/ |
+| Gmail   | `lib/channels/gmail/adapter.mjs` | Wraps `scripts/send-email.sh` + threaded Python helper |
+| WhatsApp| `lib/channels/whatsapp/adapter-twilio.mjs` | Twilio API (production) |
+|         | `lib/channels/whatsapp/adapter-baileys.mjs` | Baileys / WhatsApp Web (personal, full media) |
+| SMS     | `lib/channels/sms/adapter.mjs` | Twilio |
+| Voice   | `lib/channels/voice/adapter.mjs` | OpenAI Realtime + Twilio SIP |
+| Telegram| `lib/channels/telegram/adapter.mjs` | grammY long-poll, **in-daemon** (no relay/tunnel); gated by `config/telegram.yaml` |
+
+**WS2 unified contract.** Every adapter now speaks one type — `MessageEvent`
+(`lib/channels/contract.mjs`, with `kind = message|reaction|channel_cc|
+voice_note|call`, `source`, and `thread_context`) — serialized to/from the
+legacy poller inbox-item by `lib/channels/inbox-item.mjs`, so the daemon,
+classifier, and dispatcher are unchanged. Cross-cutting logic (session-keying,
+concurrency guard, typing heartbeat, and **default-deny DM pairing/allowlist**
+via `lib/channels/pairing.mjs` + `config/allowlist.yaml`) lives in
+`lib/channels/base-adapter.mjs`; a concrete adapter implements only
+`_connect/_toEvent/_send/_react/_setTyping`.
+
+Future plugins: Discord, iMessage, Matrix, Signal — drop in
+`lib/channels/<service>/adapter.mjs` extending `BaseAdapter` and
+register it via `definePlatform(...)`.
+
+## Conversation resolver
+
+`resolveConversation(msg)` returns `{ channel, sessionKey, threadId,
+peerId }`. The `sessionKey` is the canonical handle the daemon's
+session-lock layer uses to deduplicate concurrent work on the same
+conversation. Resolution per channel:
+
+| Channel | threadId |
+|---------|----------|
+| Slack   | `thread_ts` if present, else `dm:<channel_id>` |
+| Gmail   | `thread_id` → `in_reply_to` → `message_id` |
+| WhatsApp| `thread_id` → `in_reply_to` → `peer:<phone>` |
+| SMS     | `peer:<phone>` |
+| Voice   | `call:<call_id>` |
+| Calendar| `event:<event_id>` |
+
+## Code example
+
+```js
+import { createChannel, registerChannel, startAllChannels } from "@cohortapp/agent-sdk/channels";
+
+const slack = await createChannel("slack");
+const gmail = await createChannel("gmail");
+const wa    = await createChannel("whatsapp-baileys", { agentRoot: process.env.AGENT_DIR });
+
+registerChannel("slack", slack);
+registerChannel("gmail", gmail);
+registerChannel("whatsapp", wa);
+
+const stopAll = await startAllChannels((msg) => {
+  // msg is a ChannelMessage — normalise + push into the cadence bus
+  enqueueInbox(msg);
+});
+
+// Sending — uniform across channels:
+await wa.send({ to: "+1555...", text: "Alex, your 2pm is moved to 4pm." });
+await slack.send({ to: "D099...", text: "Standup at 11.", thread_ref: "1700.100" });
+```
+
+## Roadmap
+
+- `scripts/daemon/channel-bus.mjs` worker that mounts every registered
+  channel's inbound listener and routes through cadence-bus instead of
+  state/inbox/<service>/ files. Backward-compatible: existing pollers
+  keep working; the bus is an additional path.
+- Channel-level rate limits and circuit breakers in the registry.
+- Conversation merging across channels (Slack ↔ Gmail) via fuzzy peer
+  identification (email ↔ Slack user_id ↔ phone).
+
+## See also
+
+- `lib/channels/channel.mjs` — interface
+- `lib/channels/channels.test.mjs` — behaviour reference
+- `scripts/setup/init-channel-bus.mjs` — wizard
+- `docs/guides/voice-mode.md` — voice channel deep-dive

package/docs/guides/claude-mem-setup.md

@@ -0,0 +1,79 @@
+# Claude-Mem Setup Guide
+
+Claude-Mem is a persistent session memory plugin for Claude Code. It automatically captures tool usage, generates semantic summaries, and injects relevant context into future sessions — giving your agent continuity of knowledge across session boundaries.
+
+## What Claude-Mem Does
+
+- **Automatic capture**: 6 lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd, PreCompact) record agent activity without manual intervention
+- **AI-powered compression**: Captured actions are summarised via Claude's agent-sdk into semantic memory
+- **Vector search**: Relevant past context is retrieved and injected at session start using Chroma vector search
+- **Local storage**: All data stays on-machine in `~/.claude-mem/` (SQLite + Chroma)
+
+## Installation
+
+### Via init-agent (recommended)
+
+If you ran `scripts/setup/init-agent.sh`, Claude-Mem was installed automatically. Verify:
+
+```bash
+npx claude-mem status
+```
+
+### Manual installation
+
+```bash
+npx claude-mem install
+```
+
+This registers the plugin hooks and starts the worker service (port 37777).
+
+### Via Claude Code plugin commands
+
+```bash
+claude plugin marketplace add thedotmack/claude-mem
+claude plugin install claude-mem
+# Restart Claude Code
+```
+
+## Configuration
+
+Settings live at `~/.claude-mem/settings.json` (auto-created with defaults on first run):
+
+- **AI model**: Which model compresses captured data
+- **Worker port**: Default 37777
+- **Data directory**: Where SQLite and vector indices are stored
+- **Context injection**: How much past context to inject per session
+- **Log level**: Verbosity of worker logs
+
+## Verification
+
+```bash
+# Check worker is running
+npx claude-mem status
+
+# View captured sessions
+npx claude-mem sessions list
+
+# View memory stats
+npx claude-mem stats
+```
+
+## How It Complements Maestro's Memory
+
+Maestro already has:
+- **Interaction memory** (`memory/interactions/`) — conversation transcripts by channel/date
+- **User profiles** (`memory/profiles/`) — per-person preferences and standing instructions
+- **Knowledge base** (`knowledge/`) — entities, decisions, syntheses
+
+Claude-Mem adds:
+- **Session-level recall** — what tools were used, what worked, what failed
+- **Semantic search across sessions** — find past sessions where similar tasks were done
+- **Automatic context injection** — no manual "read the last session" needed
+
+Together they provide comprehensive memory: Maestro handles *what was communicated*, Claude-Mem handles *what was done*.
+
+## Troubleshooting
+
+- **Worker not starting**: Check `~/.claude-mem/logs/` for errors. Ensure port 37777 is free.
+- **No context injected**: Verify hooks are registered: check `~/.claude/settings.json` for claude-mem entries
+- **High memory usage**: Claude-Mem's Chroma index grows over time. Run `npx claude-mem compact` to optimise.

package/docs/guides/claude-pace-setup.md

@@ -0,0 +1,56 @@
+# Claude-Pace Setup Guide
+
+Claude-Pace is a real-time rate limit tracker for Claude Code. It displays a status line showing your 5-hour and 7-day quota usage, reset countdowns, and a pace delta indicator (green = headroom, red = burning too fast).
+
+## Why It Matters
+
+Maestro agents run continuously on 10-minute backlog cycles. Without rate limit visibility, sessions hit quota walls mid-task — the backlog executor stalls, scheduled workflows fail silently, and recovery requires manual intervention. Claude-Pace makes quota state visible so agents (and operators) can pace work intelligently.
+
+## What It Shows
+
+- 5-hour and 7-day quota usage percentages
+- Reset countdown timers
+- Pace delta: whether current burn rate will exhaust quota before reset
+- Current model, effort level, git branch, diff stats
+
+## Technical Details
+
+- Pure Bash + jq — no npm, no Node, no network calls
+- ~10ms runtime per status line refresh
+- Single file: `claude-pace.sh`
+- Reads Claude Code's local quota cache
+
+## Installation
+
+### Via init-agent (recommended)
+
+If you ran `scripts/setup/init-agent.sh`, Claude-Pace was installed automatically. Verify:
+
+```bash
+# Check if the plugin is installed
+claude plugin list | grep claude-pace
+```
+
+### Via Claude Code plugin system
+
+```bash
+claude plugin marketplace add Astro-Han/claude-pace
+claude plugin install claude-pace
+# Restart Claude Code or run /reload-plugins
+claude-pace:setup
+```
+
+### Manual installation
+
+Download `claude-pace.sh` from the repository and add to `~/.claude/settings.json` under `statusLine`.
+
+## Repository
+
+- GitHub: https://github.com/Astro-Han/claude-pace
+- License: MIT
+
+## Integration with Maestro
+
+Claude-Pace complements Maestro's existing rate-limit detection (see `project_rate_limit_detection` memory). While Maestro detects rate limits reactively via workflow log analysis ("started" without "completed"), Claude-Pace provides proactive visibility — operators see quota state before it becomes a problem.
+
+For agents running heavy backlog cycles, the pace delta indicator is the key signal: if it's red, defer non-urgent queue items to the next cycle rather than risk a mid-task stall.

package/docs/guides/claudraband-sessions.md

@@ -0,0 +1,98 @@
+# Claudraband Persistent Sessions Guide
+
+Claudraband wraps Claude Code to add persistent sessions, daemon mode with an HTTP API, and programmatic session control. It turns Claude Code from an interactive TUI into a controllable backend service.
+
+## Why It Matters
+
+Maestro agents spawn background sessions via `scripts/spawn-session.sh` for complex tasks. The current spawner uses `claude -p` with a timeout — fire-and-forget, no resumption, no mid-flight control. Claudraband adds:
+
+- **Persistent sessions**: Run headless, disconnect, reconnect later
+- **Daemon mode**: HTTP API for spawning and managing sessions programmatically
+- **Prompt injection**: Send follow-up prompts to running sessions without restarting
+- **Session lifecycle management**: List, pause, resume, and terminate sessions
+
+This is particularly valuable for the backlog executor pattern, where long-running tasks may need mid-flight adjustments.
+
+## Technical Details
+
+- TypeScript wrapper around Claude Code
+- HTTP API in daemon mode (default port 7842)
+- ACP server for editor integration
+- Exposes a TypeScript library for custom tooling
+- npx-based — zero permanent installation
+
+## Installation
+
+### Via init-agent (recommended)
+
+If you ran `scripts/setup/init-agent.sh`, claudraband is pre-installed globally. Verify:
+
+```bash
+npx @halfwhey/claudraband --version
+```
+
+### Manual
+
+```bash
+# One-shot usage
+npx @halfwhey/claudraband "your prompt here"
+
+# Start daemon
+npx @halfwhey/claudraband serve --port 7842
+```
+
+## Usage Patterns
+
+### Daemon mode (recommended for Maestro)
+
+```bash
+# Start the daemon
+npx @halfwhey/claudraband serve --port 7842
+
+# Create a session
+curl -X POST http://localhost:7842/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Research competitor X and write a brief"}'
+
+# List active sessions
+curl http://localhost:7842/sessions
+
+# Inject a follow-up prompt
+npx @halfwhey/claudraband prompt --session <id> "also check their latest SEC filing"
+
+# Terminate a session
+curl -X DELETE http://localhost:7842/sessions/<id>
+```
+
+### Direct usage (quick tasks)
+
+```bash
+npx @halfwhey/claudraband "Draft an email to the board about Q1 results"
+```
+
+### Integration with spawn-session.sh
+
+`scripts/spawn-session.sh` supports an optional `MAESTRO_SESSION_BACKEND` environment variable:
+
+- `MAESTRO_SESSION_BACKEND=claude` (default) — uses `claude -p` directly
+- `MAESTRO_SESSION_BACKEND=claudraband` — uses claudraband for persistent, resumable sessions
+
+When using the claudraband backend, sessions are registered with the daemon and can be listed, inspected, and controlled via the HTTP API.
+
+## Repository
+
+- GitHub: https://github.com/halfwhey/claudraband
+- License: MIT
+
+## Integration with Maestro
+
+Claudraband is installed as an optional session backend. The default behaviour (`claude -p`) is unchanged. To enable claudraband:
+
+1. Set `MAESTRO_SESSION_BACKEND=claudraband` in your `.env`
+2. Ensure the claudraband daemon is running (started automatically by launchd if configured via init-agent)
+3. Sessions spawned by the backlog executor will use claudraband automatically
+
+Benefits for the backlog executor:
+- **Resumable tasks**: If a session times out, it can be resumed rather than restarted
+- **Mid-flight control**: The orchestrator can inject follow-up prompts into running sessions
+- **Session inventory**: HTTP API provides visibility into all active sessions