[stevepridemore]

Requested by Steve

What

An opt-in runner that executes the dream prompts through the Messages API with an Anthropic API key, so scheduled graph work bills the key instead of a claude.ai plan. The Claude Code scheduled tasks stay the default.

• src/dream-runner/index.ts: manual tool-use loop on client.beta.messages.create. Spawns the MCP server over stdio (same pattern as .mcp.json.example) for the graph tools, so it runs as LOCAL_TENANT_ID with no network auth. Two jobs: nightly (default) and --job weekly.
• pending.ts: the runner does the nightly prompt's discovery itself and passes the exact pending list (session id, path, new/delta, previous processed_at) in the first message. No pending work means no API call. Sessions modified in the last 30 minutes are left for the next run.
• transcript-tools.ts: read_transcript pages through a session with the canonical parser and applies the delta filter before anything reaches the model (replaces graph_read_transcript, which returns a whole session). update_manifest merges one manifest entry on disk with the watermark captured at read time.
• file-tools.ts: list_dir, stat_file, read_file, write_file, move_file, delete_file, confined to ~/graph-memory (rw) and ~/.claude/projects (ro), symlink-aware. No shell. dream.lock can't be touched through them.
• api-key.ts: key from ANTHROPIC_API_KEY or ANTHROPIC_API_KEY_FILE (bare key, KEY=value line, or a folder with one file). Never logged, stripped from the MCP child's env.
• The runner holds dream.lock itself (api-runner / api-runner-weekly) and releases it in finally.
• Cost controls: prompt caching, clear_tool_uses context editing, per-run budget (wrap-up at 80%, hard stop at 1.5x), DREAM_MAX_TURNS, results over 40k chars spilled to a file with a pointer.
• Per-job tool lists: the nightly hides graph_cypher, graph_prune, graph_export, graph_reembed, graph_ingest, graph_unmerge, graph_read_transcript; the weekly gets export/cypher/prune and hides graph_merge.
• notify.ts: email from the runner after a run (never a model tool). Weekly runs that complete send the report; any run that errors, stops on budget or turns, is refused, or finds the lock held sends an alert with the log tail; a normal nightly sends nothing. Sent through gws-mcp's send-only notify listener (stevepridemore/gws-mcp#1) with a token file, so the runner holds no Gmail credential. Off unless DREAM_NOTIFY_TOKEN_HOST_FILE is set.
• Defaults: claude-opus-5-5, effort medium, server-side fallbacks: "default".

Scheduling

• graph-dream compose service under the dream profile (off unless COMPOSE_PROFILES=dream): nightly at DREAM_SCHEDULE, weekly at DREAM_WEEKLY_SCHEDULE (off by default), in DREAM_TZ. Key file mounted read-only from ANTHROPIC_API_KEY_HOST_FILE. Joins the shared mcp-notify network to reach gws-mcp.
• Or scripts/register-dream-task.ps1 [-Job weekly] for Task Scheduler.

Notes

• The published :latest image won't have the runner until a new v* tag; until then use the dev override (docker-compose.dev.yml covers graph-dream).
• The cloud-session collector still runs in a Projects thread on the subscription; it only queues text.
• New dependency: @anthropic-ai/sdk.

Testing

• src/dream-runner/dream-runner.test.ts (20 tests): nightly loop against a fake model and MCP server, weekly job tool list and prompt, no-API-call when nothing is pending, pending list and active-session hold-back, transcript paging, delta filter and manifest merge, path confinement (.., symlink), key parsing, daily and weekly schedule math, cost estimate, which mail goes out per outcome, and the notify POST.
• Live nightly runs on the home machine (dev image from this branch):
  • First commit: worked end to end but spent the whole $3 budget on discovery (listing the projects folder, paging the 500 KB manifest), with nothing extracted. Fixed in a194029.
  • a194029: completed, 18 turns, ~$0.79, 6 transcripts processed (5 entities, 15 edges), no tool errors, all graph_validate calls clean, the 180 MB transcript handled in one empty-delta page.
• Weekly job: unit-tested only; not run live yet (it prunes).

🤖 Generated with Claude Code