copperhead 0.3.0 → 0.5.0

package/src/agent/loop.ts

@@ -4,16 +4,31 @@ import { execa } from 'execa';
 import type { Msg, Provider, Turn } from './types.js';
 import { availableTools, dispatchTool, type RunContext } from './tools.js';
 import { buildSystemPrompt } from './prompts.js';
-import { loadConstraints } from '../memory/constraints.js';
+import { loadConstraints, reopenDeferredAffects } from '../memory/constraints.js';
 import { loadConfig, type CopperheadConfig } from '../config.js';
-import { Transcript } from './transcript.js';
+import { Transcript, type ExitPath, type RunStats } from './transcript.js';
+import { collectRunMeta, renderCliHeader, type RunMeta, type RunMetaInput } from './runmeta.js';
+import { plainRenderer, fmtDuration, fmtTokens, type ProgressRenderer } from './render.js';
 import { ObligationsLedger } from './ledger.js';
-import { isDirty, isGitRepo, snapshot, restore, commitAll, changedFiles } from '../util/git.js';
+import { gitPreflight, isDirty, snapshot, restore, commitAll, changedFiles, preserveFailedRun } from '../util/git.js';
 import { withRetry, isRateLimit } from '../util/retry.js';
 import { openspecArchive } from '../openspec/cli.js';
 import { existsSync } from 'node:fs';
 import { OpenAIProvider } from './providers/openai.js';
 import { AnthropicProvider } from './providers/anthropic.js';
+import { CodexProvider } from './providers/codex.js';
+import { openSynapMemory, type RunRecord, type SynapMemory } from '../memory/synap.js';
+
+/** What the user sees at the moment they decide whether to keep going. */
+export interface BudgetExhaustedStats {
+  /** The run's original turn budget, before any extensions. */
+  maxTurns: number;
+  turnsUsed: number;
+  tokensIn: number;
+  tokensOut: number;
+  filesTouched: string[];
+  openObligations: number;
+}
 
 export interface RunOptions {
   repoRoot: string;
@@ -24,20 +39,49 @@ export interface RunOptions {
   dryRun?: boolean;
   interactive?: boolean;
   confirm?: (q: string) => Promise<boolean>;
+  /**
+   * Called when the turn budget runs out. Returns the number of extra turns to
+   * grant (0 fails the run as before). Absent means non-interactive: fail.
+   */
+  onBudgetExhausted?: (stats: BudgetExhaustedStats) => Promise<number>;
   /** Extra prompt appended for pipeline stages (Mode A). */
   stagePrompt?: string;
+  /** Test seam: bypass makeProvider. */
+  provider?: Provider;
   log?: (line: string) => void;
+  /** Progress renderer; defaults to a plain line renderer over `log`. */
+  renderer?: ProgressRenderer;
+  /** Caller-known run identity for the metadata block (design D2). */
+  meta?: RunMetaInput;
 }
 
 export interface RunResult {
   outcome: 'success' | 'refused' | 'failure';
+  exitPath: ExitPath;
   summary: string;
   transcriptDir: string;
   filesTouched: string[];
   commit: string | null;
 }
 
-export function makeProvider(model: string): Provider {
+export async function makeProvider(model: string): Promise<Provider> {
+  if (model === 'codex' || model.startsWith('codex:')) {
+    const codexModel = model.startsWith('codex:') ? model.slice('codex:'.length) : undefined;
+    if (codexModel === '') throw new Error('codex model override cannot be empty; use "codex" or "codex:<model-id>"');
+    const { Codex } = await import('@openai/codex-sdk').catch((err: unknown) => {
+      throw new Error(
+        'Codex provider requires the optional @openai/codex-sdk package; install it alongside Copperhead before using --model codex',
+        { cause: err },
+      );
+    });
+    return new CodexProvider({
+      ...(codexModel ? { model: codexModel } : {}),
+      client: new Codex({
+        // Use the user's installed CLI and its saved login rather than a model API key.
+        codexPathOverride: process.env.COPPERHEAD_CODEX_PATH || 'codex',
+      }),
+    });
+  }
   if (model === 'claude' || model.startsWith('claude')) {
     return new AnthropicProvider(model === 'claude' ? undefined : model);
   }
@@ -84,18 +128,40 @@ async function appendChangelog(
   await writeFile(p, lines.join('\n'), 'utf8');
 }
 
+/**
+ * Owns the Synap session for one run. The bridge is a subprocess, so the
+ * shutdown in `finally` is what lets the CLI exit; without it the process
+ * hangs after a successful run.
+ */
 export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
-  const log = opts.log ?? ((l: string) => console.log(l));
+  const memory = await openSynapMemory({ repoRoot: opts.repoRoot, log: opts.log });
+  const providers = new Set<Provider>();
+  try {
+    return await runWithMemory(opts, memory, providers);
+  } finally {
+    for (const provider of providers) {
+      try {
+        await provider.close?.();
+      } catch (err) {
+        opts.log?.(`warning: ${provider.name} provider cleanup failed (${(err as Error).message})`);
+      }
+    }
+    await memory?.close();
+  }
+}
+
+async function runWithMemory(
+  opts: RunOptions,
+  memory: SynapMemory | null,
+  providers: Set<Provider>,
+): Promise<RunResult> {
+  const r = opts.renderer ?? plainRenderer(opts.log ?? ((l: string) => console.log(l)));
+  const log = (l: string): void => r.log(l);
   const repoRoot = opts.repoRoot;
   const config = await loadConfig(repoRoot);
   const maxTurns = opts.maxTurns ?? config.maxTurns;
 
-  if (!(await isGitRepo(repoRoot))) {
-    throw new Error('not a git repository; copperhead requires git for snapshots and rollback');
-  }
-  if ((await isDirty(repoRoot)) && !opts.allowDirty) {
-    throw new Error('working tree is dirty; commit your changes or pass --allow-dirty (snapshots via git stash create)');
-  }
+  await gitPreflight(repoRoot, { allowDirty: opts.allowDirty ?? false });
   const snap = await snapshot(repoRoot);
 
   const transcript = new Transcript(repoRoot);
@@ -119,23 +185,127 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
     finishRequest: null,
   };
 
-  let provider = makeProvider(opts.model);
+  let provider = opts.provider ?? (await makeProvider(opts.model));
+  providers.add(provider);
+
+  // Deterministic, LLM-free metadata block: collected once, rendered onto all
+  // three surfaces (run-start event, summary ## Environment, CLI header) so
+  // they can never disagree (design D1, AC-8.1/8.4).
+  const startMs = Date.now();
+  const meta: RunMeta = await collectRunMeta({
+    repoRoot,
+    config,
+    maxTurns,
+    runId: path.basename(transcript.dir),
+    request: opts.request,
+    model: opts.model,
+    provider: provider.name,
+    interactive: opts.interactive ?? false,
+    input: opts.meta,
+  });
+  for (const line of renderCliHeader(meta)) log(line);
+  // Revisit obligations deferred while their artifact didn't exist re-open now
+  // if it does (must run before loadConstraints so the prompt sees the updated
+  // registry). They land in this run's fresh ledger, so finish gates on them.
+  const reopened = await reopenDeferredAffects(repoRoot, config, (key, item) =>
+    ctx.ledger.add('affects-revisit', `${key} affects ${item}`, key),
+  );
+  if (reopened.length) {
+    await transcript.event('deferred-affects-reopened', { reopened });
+    log(`re-opened ${reopened.length} deferred constraint revisit obligation(s)`);
+  }
   const constraints = await loadConstraints(repoRoot);
-  const system = await buildSystemPrompt(repoRoot, config, constraints);
+  let basePrompt = await buildSystemPrompt(repoRoot, config, constraints);
+  if (reopened.length) {
+    basePrompt += [
+      '',
+      '',
+      '## Reopened constraint revisits',
+      '',
+      'These constraints were recorded before their target artifact existed; the artifact now exists.',
+      'Revisit each against the design and close it with resolve_affected (batch the calls):',
+      ...reopened.map((r) => `- ${r.key} affects ${r.item}`),
+    ].join('\n');
+  }
+  // Cross-run memory is appended after the repo's own docs and constraints so
+  // that the in-repo sources of truth are what the model reads first.
+  const recalled = memory ? await memory.recall(opts.request) : null;
+  if (recalled) {
+    await transcript.event('synap-recall', { chars: recalled.length });
+    log('recalled prior context from Synap memory');
+  }
+  const system = recalled ? `${basePrompt}\n\n${recalled}` : basePrompt;
   const messages: Msg[] = [
     { role: 'system', content: system },
     { role: 'user', content: opts.stagePrompt ? `${opts.stagePrompt}\n\nRequest: ${opts.request}` : opts.request },
   ];
-  await transcript.event('run-start', { request: opts.request, model: opts.model, provider: provider.name });
+  await transcript.event('run-start', meta);
+
+  /**
+   * A memory write that fails is reported rather than swallowed, but it does
+   * not change the run's outcome: discarding a verified commit because a
+   * third-party write failed would be the worse trade.
+   */
+  const remember = async (run: RunRecord): Promise<void> => {
+    if (!memory) return;
+    try {
+      await memory.record(run);
+      await transcript.event('synap-record', { outcome: run.outcome });
+    } catch (err) {
+      const message = (err as Error).message;
+      log(`warning: Synap memory write failed (${message}); this run was not recorded`);
+      await transcript.event('synap-record-failed', { error: message });
+    }
+  };
 
   let tokensIn = 0;
   let tokensOut = 0;
+  let turnsUsed = 0;
+  const perTurn: { turn: number; in: number; out: number }[] = [];
   let plan: string | null = null;
   let nudges = 0;
 
-  const fail = async (reason: string): Promise<RunResult> => {
-    await transcript.event('run-failed', { reason });
-    await restore(repoRoot, snap);
+  const stats = (exitPath: ExitPath): RunStats => ({
+    exitPath,
+    turnsUsed,
+    maxTurns,
+    repairCyclesUsed: ctx.repairCycles,
+    maxRepairCycles: config.maxRepairCycles,
+    tokensIn,
+    tokensOut,
+    perTurn,
+    durationMs: Date.now() - startMs,
+  });
+
+  /** One outcome line, printed last at every terminal branch (AC-8.5). */
+  const outcomeLine = (s: RunStats, extra?: string | null): string =>
+    [
+      s.exitPath,
+      ctx.lastErc ? `ERC ${ctx.lastErc.ok ? 'clean' : 'failing'}` : 'ERC not run',
+      ...(ctx.lastDrc ? [`DRC ${ctx.lastDrc.ok ? 'clean' : 'failing'}`] : []),
+      ...(extra ? [extra] : []),
+      fmtDuration(s.durationMs),
+      `${fmtTokens(s.tokensIn)} in / ${fmtTokens(s.tokensOut)} out`,
+    ].join(' · ');
+
+  const fail = async (reason: string, exitPath: ExitPath): Promise<RunResult> => {
+    await transcript.event('run-failed', { reason, exitPath });
+    // Preserve the touched work as a stash entry before the rollback destroys
+    // it, so a budget-exhaustion (or any) failure is recoverable (issue #15).
+    const preserved = await preserveFailedRun(repoRoot, ctx.runId);
+    if (preserved) await transcript.event('work-preserved', { stash: preserved });
+    // The rollback itself can fail (git in a bad state). That must not become
+    // an unhandled throw that skips run-end and summary.md — the summary is
+    // most valuable exactly when the tree is left in an unknown state.
+    let restoreError: string | null = null;
+    try {
+      await restore(repoRoot, snap);
+    } catch (err) {
+      restoreError = (err as Error).message;
+      await transcript.event('restore-failed', { error: restoreError });
+    }
+    const runStats = stats(exitPath);
+    await transcript.event('run-end', runStats);
     const summaryPath = await transcript.writeSummary({
       request: opts.request,
       changeId: ctx.changeId,
@@ -148,14 +318,27 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
       tokensOut,
       outcome: 'failure',
       openObligations: ctx.ledger.isClear ? null : ctx.ledger.describe(),
-      detail: reason,
+      detail: restoreError ? `${reason}\n\nROLLBACK FAILED: ${restoreError} — the working tree may be in a partial state; inspect it with git status/git diff before rerunning` : reason,
+      env: meta,
+      stats: runStats,
     });
     log(`run failed: ${reason}`);
-    log(`working tree restored to pre-run snapshot`);
+    if (restoreError) {
+      log(`WARNING: rollback failed (${restoreError}); the working tree may be in a partial state`);
+    } else {
+      log(`working tree restored to pre-run snapshot`);
+    }
+    if (preserved) {
+      log(
+        `failed work preserved: git stash entry "copperhead failed run ${ctx.runId}" (${preserved.slice(0, 10)}); recover with \`git stash apply\`, discard with \`git stash drop\``,
+      );
+    }
     log(`transcript: ${transcript.jsonlPath}`);
     log(`summary: ${summaryPath}`);
+    r.finish(outcomeLine(runStats));
     return {
       outcome: 'failure',
+      exitPath,
       summary: reason,
       transcriptDir: transcript.dir,
       filesTouched: [],
@@ -163,8 +346,38 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
     };
   };
 
-  for (let turn = 0; turn < maxTurns; turn++) {
+  let budget = maxTurns;
+  for (let turn = 0; ; turn++) {
+    if (turn >= budget) {
+      // Budget exhausted. In an attended run this is a user decision made with
+      // the cost visible, not an unconditional rollback (issue #15).
+      const exhaustStats: BudgetExhaustedStats = {
+        maxTurns,
+        turnsUsed: turn,
+        tokensIn,
+        tokensOut,
+        filesTouched: [...ctx.filesTouched],
+        openObligations: ctx.ledger.openObligations.length,
+      };
+      let extra = 0;
+      if (opts.onBudgetExhausted) {
+        try {
+          extra = Math.floor(await opts.onBudgetExhausted(exhaustStats));
+        } catch {
+          // A broken prompt (stdin closed mid-question, dying terminal) must
+          // read as "declined" and take the preserve-and-restore path below,
+          // not propagate past it and skip the rollback entirely.
+          extra = 0;
+        }
+      }
+      if (!Number.isFinite(extra) || extra <= 0) break;
+      budget += extra;
+      await transcript.event('budget-extended', { extraTurns: extra, budget, ...exhaustStats });
+      log(`turn budget extended by ${extra} (now ${budget})`);
+    }
     const tools = availableTools(ctx).map((t) => t.schema);
+    r.turnStart(turn + 1, maxTurns, tokensIn, tokensOut);
+    r.status('thinking');
     let res: Turn;
     try {
       res = await withRetry(() => provider.chat(messages, tools), {
@@ -177,14 +390,19 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
           log(`failing over ${provider.name} → ${fallback.name}`);
           await transcript.event('provider-failover', { from: provider.name, to: fallback.name });
           provider = fallback;
+          providers.add(provider);
           turn--;
           continue;
         }
       }
-      return fail(`provider error: ${(err as Error).message}`);
+      return fail(`provider error: ${(err as Error).message}`, 'provider-error');
+    } finally {
+      r.status(null);
     }
+    turnsUsed = turn + 1;
     tokensIn += res.usage.inputTokens;
     tokensOut += res.usage.outputTokens;
+    perTurn.push({ turn: turn + 1, in: res.usage.inputTokens, out: res.usage.outputTokens });
     await transcript.event('assistant', { text: res.text, toolCalls: res.toolCalls });
 
     if (res.text) {
@@ -194,31 +412,36 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
     messages.push({ role: 'assistant', content: res.text, toolCalls: res.toolCalls });
 
     if (!res.toolCalls.length) {
-      if (nudges++ >= 2) return fail('model stopped calling tools without finishing');
+      // Only *consecutive* tool-less turns are a stall. Providers emit the
+      // occasional empty completion mid-run (observed live: three empties
+      // spread across 31 productive turns); a cumulative counter turns those
+      // into a full rollback of an otherwise-converging run.
+      if (nudges++ >= 2) return fail('model stopped calling tools without finishing', 'stalled');
       messages.push({
         role: 'user',
         content: 'Continue using tools, or call finish({outcome, summary}) to end the run.',
       });
       continue;
     }
+    nudges = 0;
 
     for (const call of res.toolCalls) {
       const result = await dispatchTool(ctx, call.name, call.args);
       await transcript.event('tool', { name: call.name, args: call.args, result });
-      log(`  [${call.name}] ${result.split('\n')[0]}`);
+      r.toolResult(call.name, result.split('\n')[0] ?? '');
       messages.push({ role: 'tool', toolCallId: call.id, content: result });
     }
 
     if (ctx.repairCycles > config.maxRepairCycles) {
-      return fail(`repair cycles exhausted (${config.maxRepairCycles}); violations persist`);
+      return fail(`repair cycles exhausted (${config.maxRepairCycles}); violations persist`, 'repair-cycles-exhausted');
     }
 
-    const remaining = maxTurns - turn - 1;
+    const remaining = budget - turn - 1;
     if (remaining === 5 && !ctx.finishRequest) {
       messages.push({
         role: 'user',
         content:
-          'Only 5 turns remain. Converge now: finish the minimal correct edit set, run run_erc (and run_drc if the board changed), run check_drift, then call finish.',
+          'Only 5 turns remain. Converge now: finish the minimal correct edit set, run run_erc (and run_drc if the board changed), run check_drift, then call finish. Batch independent tool calls in a single response (e.g. all resolve_affected calls at once) instead of one per turn.',
       });
     }
 
@@ -228,6 +451,8 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
       if (outcome === 'refuse') {
         await restore(repoRoot, snap);
         await transcript.event('run-refused', { summary });
+        const runStats = stats('refused');
+        await transcript.event('run-end', runStats);
         await transcript.writeSummary({
           request: opts.request,
           changeId: ctx.changeId,
@@ -241,9 +466,30 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
           outcome: 'aborted',
           openObligations: null,
           detail: `REFUSED: ${summary}`,
+          env: meta,
+          stats: runStats,
+        });
+        // Refusals are the most valuable thing to remember: they encode a budget
+        // or constraint that this user's designs keep running into.
+        await remember({
+          request: opts.request,
+          outcome: 'refused',
+          summary,
+          changeId: ctx.changeId,
+          filesTouched: [],
+          decisions: ctx.decisions,
+          verification: 'n/a (refused before verification)',
         });
         log(`refused: ${summary}`);
-        return { outcome: 'refused', summary, transcriptDir: transcript.dir, filesTouched: [], commit: null };
+        r.finish(outcomeLine(runStats));
+        return {
+          outcome: 'refused',
+          exitPath: 'refused',
+          summary,
+          transcriptDir: transcript.dir,
+          filesTouched: [],
+          commit: null,
+        };
       }
 
       const verification = [
@@ -262,6 +508,8 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
         log(diff || '(no diff)');
         if (untracked) log(`new files:\n${untracked}`);
         await restore(repoRoot, snap);
+        const runStats = stats('done');
+        await transcript.event('run-end', runStats);
         await transcript.writeSummary({
           request: opts.request,
           changeId: ctx.changeId,
@@ -275,8 +523,18 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
           outcome: 'success',
           openObligations: null,
           detail: 'dry run: changes reverted',
+          env: meta,
+          stats: runStats,
         });
-        return { outcome: 'success', summary, transcriptDir: transcript.dir, filesTouched: files, commit: null };
+        r.finish(outcomeLine(runStats, 'dry run: changes reverted'));
+        return {
+          outcome: 'success',
+          exitPath: 'done',
+          summary,
+          transcriptDir: transcript.dir,
+          filesTouched: files,
+          commit: null,
+        };
       }
 
       await appendChangelog(repoRoot, config, {
@@ -288,15 +546,33 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
       ctx.ledger.clear('changelog');
 
       const commitMsg = `copperhead: ${opts.request}\n\n${summary}\n\nVerification: ${verification}`;
-      const commit = await commitAll(repoRoot, commitMsg);
+      // A git failure here (e.g. `git add -A` exiting 128 on an embedded repo)
+      // must land in summary.md as an outcome, not escape as a stack trace
+      // (AC-8.6): roll back per the snapshot contract and report commit-failed.
+      let commit: string;
+      try {
+        commit = await commitAll(repoRoot, commitMsg);
+      } catch (err) {
+        return fail(`commit failed: ${(err as Error).message}`, 'commit-failed');
+      }
       if (ctx.changeId && existsSync(path.join(repoRoot, 'openspec', 'config.yaml'))) {
-        const arch = await openspecArchive(repoRoot, ctx.changeId);
-        await transcript.event('openspec-archive', { changeId: ctx.changeId, ok: arch.ok });
-        if (arch.ok && (await isDirty(repoRoot))) {
-          await commitAll(repoRoot, `copperhead: archive change ${ctx.changeId}`);
+        // The verified commit already exists; discarding it because archive
+        // housekeeping failed would be the worse trade, so this is a warning.
+        try {
+          const arch = await openspecArchive(repoRoot, ctx.changeId);
+          await transcript.event('openspec-archive', { changeId: ctx.changeId, ok: arch.ok });
+          if (arch.ok && (await isDirty(repoRoot))) {
+            await commitAll(repoRoot, `copperhead: archive change ${ctx.changeId}`);
+          }
+        } catch (err) {
+          const message = (err as Error).message;
+          log(`warning: openspec archive failed (${message}); the run commit itself succeeded`);
+          await transcript.event('openspec-archive-failed', { changeId: ctx.changeId, error: message });
         }
       }
       await transcript.event('run-committed', { commit, files });
+      const runStats = stats('done');
+      await transcript.event('run-end', runStats);
       await transcript.writeSummary({
         request: opts.request,
         changeId: ctx.changeId,
@@ -309,12 +585,34 @@ export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
         tokensOut,
         outcome: 'success',
         openObligations: null,
+        env: meta,
+        stats: runStats,
+      });
+      await remember({
+        request: opts.request,
+        outcome: 'success',
+        summary,
+        changeId: ctx.changeId,
+        filesTouched: files,
+        decisions: ctx.decisions,
+        verification,
       });
       log(`committed ${commit.slice(0, 10)} (${files.length} file(s))`);
-      return { outcome: 'success', summary, transcriptDir: transcript.dir, filesTouched: files, commit };
+      r.finish(outcomeLine(runStats, `committed ${commit.slice(0, 10)}`));
+      return {
+        outcome: 'success',
+        exitPath: 'done',
+        summary,
+        transcriptDir: transcript.dir,
+        filesTouched: files,
+        commit,
+      };
     }
   }
 
   const filesAfter = await changedFiles(repoRoot, snap.head);
-  return fail(`turn budget exhausted (${maxTurns} turns, ${filesAfter.length} files touched but unverified)`);
+  return fail(
+    `turn budget exhausted (${budget} turns, ${filesAfter.length} files touched but unverified)`,
+    'turn-budget-exhausted',
+  );
 }

package/src/agent/prompts.ts

@@ -21,7 +21,9 @@ const WORKFLOW = `Workflow for every run:
 4. Run run_erc after schematic edits (and run_drc after board edits). If violations: read them, fix, re-run.
 5. Run check_drift; update any doc that references a changed value/part/pin in the same run.
 6. Record every non-trivial decision with record_decision, and every stated/assumed/discovered constraint with record_constraint.
-7. Call finish with outcome "done" when everything is verified, or outcome "refuse" (citing the violated budget/constraint) if the request should not be done. finish will list any unmet obligations; resolve them and call it again.`;
+7. Call finish with outcome "done" when everything is verified, or outcome "refuse" (citing the violated budget/constraint) if the request should not be done. finish will list any unmet obligations; resolve them and call it again.
+
+Turns are the scarce resource, not tool calls: the run has a hard turn budget, and every tool call in one reply executes in the same turn. When calls are independent — multiple record_constraint or resolve_affected calls (use resolutions: [...] to clear a backlog in one call), several read_file calls — issue them together in a single reply instead of one per turn.`;
 
 export async function buildSystemPrompt(
   repoRoot: string,

package/src/agent/providers/anthropic.ts

@@ -1,9 +1,12 @@
 import type { ChatOpts, Msg, Provider, ToolSchema, Turn } from '../types.js';
 
-type AnthropicContent =
+type CacheControl = { cache_control?: { type: 'ephemeral' } };
+type AnthropicContent = (
   | { type: 'text'; text: string }
   | { type: 'tool_use'; id: string; name: string; input: unknown }
-  | { type: 'tool_result'; tool_use_id: string; content: string };
+  | { type: 'tool_result'; tool_use_id: string; content: string }
+) &
+  CacheControl;
 
 export class AnthropicProvider implements Provider {
   readonly name = 'anthropic';
@@ -15,6 +18,13 @@ export class AnthropicProvider implements Provider {
     if (!this.apiKey) throw new Error('ANTHROPIC_API_KEY is not set');
   }
 
+  /**
+   * The loop resends the full conversation every turn, which is quadratic in
+   * input tokens. Three ephemeral cache_control breakpoints (system prompt,
+   * last tool definition, last block of the final message) cache the stable
+   * prefix plus the conversation up to the previous turn, cutting repeated
+   * input cost by roughly an order of magnitude on multi-turn runs.
+   */
   async chat(messages: Msg[], tools: ToolSchema[], opts: ChatOpts = {}): Promise<Turn> {
     const { default: Anthropic } = await import('@anthropic-ai/sdk');
     const client = new Anthropic({ apiKey: this.apiKey });
@@ -24,11 +34,11 @@ export class AnthropicProvider implements Provider {
       .map((m) => m.content)
       .join('\n\n');
 
-    const conv: { role: 'user' | 'assistant'; content: AnthropicContent[] | string }[] = [];
+    const conv: { role: 'user' | 'assistant'; content: AnthropicContent[] }[] = [];
     for (const m of messages) {
       if (m.role === 'system') continue;
       if (m.role === 'user') {
-        conv.push({ role: 'user', content: m.content });
+        conv.push({ role: 'user', content: [{ type: 'text', text: m.content }] });
       } else if (m.role === 'assistant') {
         const content: AnthropicContent[] = [];
         if (m.content) content.push({ type: 'text', text: m.content });
@@ -40,7 +50,7 @@ export class AnthropicProvider implements Provider {
         // tool results are user-role content blocks in the Anthropic API
         const prev = conv[conv.length - 1];
         const block: AnthropicContent = { type: 'tool_result', tool_use_id: m.toolCallId, content: m.content };
-        if (prev && prev.role === 'user' && Array.isArray(prev.content)) {
+        if (prev && prev.role === 'user') {
           prev.content.push(block);
         } else {
           conv.push({ role: 'user', content: [block] });
@@ -48,20 +58,23 @@ export class AnthropicProvider implements Provider {
       }
     }
 
+    const lastMsg = conv[conv.length - 1];
+    const lastBlock = lastMsg?.content[lastMsg.content.length - 1];
+    if (lastBlock) lastBlock.cache_control = { type: 'ephemeral' };
+
+    const toolDefs = tools.map((t, i) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters as never,
+      ...(i === tools.length - 1 ? { cache_control: { type: 'ephemeral' as const } } : {}),
+    }));
+
     const res = await client.messages.create({
       model: this.model,
       max_tokens: opts.maxTokens ?? 8192,
-      ...(system ? { system } : {}),
+      ...(system ? { system: [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }] } : {}),
       messages: conv as never,
-      ...(tools.length
-        ? {
-            tools: tools.map((t) => ({
-              name: t.name,
-              description: t.description,
-              input_schema: t.parameters as never,
-            })),
-          }
-        : {}),
+      ...(tools.length ? { tools: toolDefs as never } : {}),
     });
 
     let text: string | null = null;
@@ -72,10 +85,21 @@ export class AnthropicProvider implements Provider {
         toolCalls.push({ id: block.id, name: block.name, args: block.input as Record<string, unknown> });
       }
     }
+    // input_tokens excludes cached tokens; sum them so the run summary stays
+    // honest about volume (the discount shows up on the bill, not here).
+    const usage = res.usage as {
+      input_tokens: number;
+      output_tokens: number;
+      cache_read_input_tokens?: number | null;
+      cache_creation_input_tokens?: number | null;
+    };
     return {
       text,
       toolCalls,
-      usage: { inputTokens: res.usage.input_tokens, outputTokens: res.usage.output_tokens },
+      usage: {
+        inputTokens: usage.input_tokens + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0),
+        outputTokens: usage.output_tokens,
+      },
     };
   }
 }