copperhead 0.3.0

package/src/agent/filetools.ts

@@ -0,0 +1,136 @@
+import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { resolveInRepo, isKicadFile } from '../util/paths.js';
+
+export async function toolReadFile(
+  repoRoot: string,
+  p: string,
+  startLine?: number,
+  endLine?: number,
+): Promise<string> {
+  const abs = resolveInRepo(repoRoot, p);
+  const text = await readFile(abs, 'utf8');
+  if (startLine === undefined) return text;
+  const lines = text.split('\n');
+  const from = Math.max(1, startLine);
+  const to = Math.min(lines.length, endLine ?? lines.length);
+  return lines
+    .slice(from - 1, to)
+    .map((l, i) => `${from + i}: ${l}`)
+    .join('\n');
+}
+
+/** New files only; refuses to overwrite anything and to create KiCad files (SPEC §4.2). */
+export async function toolWriteFile(repoRoot: string, p: string, content: string): Promise<string> {
+  const abs = resolveInRepo(repoRoot, p);
+  if (isKicadFile(abs)) {
+    throw new Error(`write_file refuses KiCad files (${p}); use edit_file with anchors instead`);
+  }
+  if (existsSync(abs)) {
+    throw new Error(`write_file refuses to overwrite existing file ${p}; use edit_file`);
+  }
+  await mkdir(path.dirname(abs), { recursive: true });
+  await writeFile(abs, content, 'utf8');
+  return `wrote ${p}`;
+}
+
+/**
+ * Exact-match anchored replace; fails with an actionable error unless unique.
+ * `replaceAll` replaces every occurrence (the rename case, AC-3.1) while still
+ * being a surgical text edit on the s-expression source.
+ */
+export async function toolEditFile(
+  repoRoot: string,
+  p: string,
+  oldString: string,
+  newString: string,
+  replaceAll = false,
+): Promise<string> {
+  const abs = resolveInRepo(repoRoot, p);
+  const text = await readFile(abs, 'utf8');
+  const first = text.indexOf(oldString);
+  if (first === -1) {
+    throw new Error(`edit_file: anchor not found in ${p}; re-read the file and use an exact excerpt`);
+  }
+  const count = text.split(oldString).length - 1;
+  if (replaceAll) {
+    await writeFile(abs, text.split(oldString).join(newString), 'utf8');
+    return `edited ${p} (${count} occurrence(s) replaced)`;
+  }
+  if (count > 1) {
+    throw new Error(
+      `edit_file: anchor matched ${count} times in ${p}; widen the anchor with surrounding lines until it is unique, or pass replace_all: true to replace every occurrence`,
+    );
+  }
+  await writeFile(abs, text.slice(0, first) + newString + text.slice(first + oldString.length), 'utf8');
+  return `edited ${p}`;
+}
+
+export interface SearchMatch {
+  file: string;
+  line: number;
+  text: string;
+}
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', '.copperhead']);
+
+export function globToRegex(glob: string): RegExp {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    if (glob.startsWith('**/', i)) {
+      out += '(?:.*/)?'; // zero or more directories
+      i += 2;
+    } else if (glob.startsWith('**', i)) {
+      out += '.*';
+      i += 1;
+    } else if (glob[i] === '*') {
+      out += '[^/]*';
+    } else if (glob[i] === '?') {
+      out += '.';
+    } else {
+      out += glob[i]!.replace(/[.+^${}()|[\]\\]/, '\\$&');
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+
+/** ripgrep-style regex search implemented natively (no rg dependency). */
+export async function toolSearch(
+  repoRoot: string,
+  pattern: string,
+  glob?: string,
+  maxMatches = 200,
+): Promise<SearchMatch[]> {
+  const re = new RegExp(pattern);
+  const globRe = glob ? globToRegex(glob) : null;
+  const matches: SearchMatch[] = [];
+  async function walk(dir: string): Promise<void> {
+    if (matches.length >= maxMatches) return;
+    for (const entry of await readdir(dir)) {
+      if (SKIP_DIRS.has(entry)) continue;
+      const abs = path.join(dir, entry);
+      const rel = path.relative(repoRoot, abs);
+      const st = await stat(abs);
+      if (st.isDirectory()) {
+        await walk(abs);
+      } else if (st.size < 5_000_000 && (!globRe || globRe.test(rel))) {
+        let text: string;
+        try {
+          text = await readFile(abs, 'utf8');
+        } catch {
+          continue;
+        }
+        if (text.includes('\u0000')) continue; // binary
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length && matches.length < maxMatches; i++) {
+          if (re.test(lines[i]!)) matches.push({ file: rel, line: i + 1, text: lines[i]!.trim() });
+        }
+      }
+      if (matches.length >= maxMatches) return;
+    }
+  }
+  await walk(repoRoot);
+  return matches;
+}

package/src/agent/ledger.ts

@@ -0,0 +1,71 @@
+/**
+ * Sync-obligations ledger (design D13). Deterministic post-tool-call hooks
+ * record obligations; the commit gate refuses while any is open. This is what
+ * turns "keep everything in sync" into a mechanical gate instead of a prompt.
+ */
+export type ObligationKind =
+  | 'erc'
+  | 'drc'
+  | 'drift'
+  | 'changelog'
+  | 'decision-log'
+  | 'constraint-dual-write'
+  | 'affects-revisit';
+
+export interface Obligation {
+  kind: ObligationKind;
+  detail: string;
+  openedBy: string;
+}
+
+export class ObligationsLedger {
+  private open: Obligation[] = [];
+
+  add(kind: ObligationKind, detail: string, openedBy: string): void {
+    if (!this.open.some((o) => o.kind === kind && o.detail === detail)) {
+      this.open.push({ kind, detail, openedBy });
+    }
+  }
+
+  clear(kind: ObligationKind, detail?: string): void {
+    this.open = this.open.filter(
+      (o) => !(o.kind === kind && (detail === undefined || o.detail === detail)),
+    );
+  }
+
+  /** A KiCad edit re-opens verification obligations even if previously cleared. */
+  onKicadEdit(file: string): void {
+    this.add('erc', 'ERC must pass after schematic edits', file);
+    if (file.endsWith('.kicad_pcb')) this.add('drc', 'DRC must pass after board edits', file);
+    this.add('drift', 'check_drift must run clean after KiCad edits', file);
+    this.add('changelog', 'CHANGELOG.md entry for this run', file);
+  }
+
+  onDocEdit(file: string): void {
+    this.add('drift', 'check_drift must run clean after doc edits', file);
+  }
+
+  onConstraintChange(constraintKey: string, affects: string[]): void {
+    this.add('constraint-dual-write', constraintKey, constraintKey);
+    for (const item of affects) {
+      this.add('affects-revisit', `${constraintKey} affects ${item}`, constraintKey);
+    }
+  }
+
+  onDecision(summary: string): void {
+    this.add('decision-log', summary, 'decision');
+  }
+
+  get openObligations(): readonly Obligation[] {
+    return this.open;
+  }
+
+  get isClear(): boolean {
+    return this.open.length === 0;
+  }
+
+  describe(): string {
+    if (this.isClear) return 'all sync obligations satisfied';
+    return this.open.map((o) => `- [${o.kind}] ${o.detail} (opened by ${o.openedBy})`).join('\n');
+  }
+}

package/src/agent/loop.ts

@@ -0,0 +1,320 @@
+import path from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+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 { loadConfig, type CopperheadConfig } from '../config.js';
+import { Transcript } from './transcript.js';
+import { ObligationsLedger } from './ledger.js';
+import { isDirty, isGitRepo, snapshot, restore, commitAll, changedFiles } 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';
+
+export interface RunOptions {
+  repoRoot: string;
+  request: string;
+  model: string;
+  maxTurns?: number;
+  allowDirty?: boolean;
+  dryRun?: boolean;
+  interactive?: boolean;
+  confirm?: (q: string) => Promise<boolean>;
+  /** Extra prompt appended for pipeline stages (Mode A). */
+  stagePrompt?: string;
+  log?: (line: string) => void;
+}
+
+export interface RunResult {
+  outcome: 'success' | 'refused' | 'failure';
+  summary: string;
+  transcriptDir: string;
+  filesTouched: string[];
+  commit: string | null;
+}
+
+export function makeProvider(model: string): Provider {
+  if (model === 'claude' || model.startsWith('claude')) {
+    return new AnthropicProvider(model === 'claude' ? undefined : model);
+  }
+  return new OpenAIProvider(model === 'gpt-5' ? undefined : model);
+}
+
+function otherProvider(current: Provider): Provider | null {
+  if (current.name === 'openai' && process.env.ANTHROPIC_API_KEY) return new AnthropicProvider();
+  if (current.name === 'anthropic' && process.env.OPENAI_API_KEY) return new OpenAIProvider();
+  return null;
+}
+
+async function appendChangelog(
+  repoRoot: string,
+  config: CopperheadConfig,
+  entry: { changeId: string | null; request: string; files: string[]; verification: string },
+): Promise<void> {
+  const p = path.join(repoRoot, config.docs, 'CHANGELOG.md');
+  const date = new Date().toISOString().slice(0, 10);
+  const block = [
+    ``,
+    `## ${date} — ${entry.request}`,
+    ``,
+    `- Change: ${entry.changeId ?? 'n/a'}`,
+    `- Files: ${entry.files.join(', ') || '(none)'}`,
+    `- Verification: ${entry.verification}`,
+  ].join('\n');
+  let text: string;
+  try {
+    text = await readFile(p, 'utf8');
+  } catch {
+    text = '# Design changelog\n\nAppend-only, newest first. One entry per committed copperhead run.\n';
+  }
+  // newest first: insert right after the header block (first blank line after content start)
+  const lines = text.split('\n');
+  let insertAt = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i]!.startsWith('## ')) {
+      insertAt = i;
+      break;
+    }
+  }
+  lines.splice(insertAt, 0, ...block.split('\n').slice(1), '');
+  await writeFile(p, lines.join('\n'), 'utf8');
+}
+
+export async function runAgentLoop(opts: RunOptions): Promise<RunResult> {
+  const log = opts.log ?? ((l: string) => console.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)');
+  }
+  const snap = await snapshot(repoRoot);
+
+  const transcript = new Transcript(repoRoot);
+  await transcript.init();
+  const ctx: RunContext = {
+    repoRoot,
+    config,
+    transcript,
+    ledger: new ObligationsLedger(),
+    runId: path.basename(transcript.dir),
+    interactive: opts.interactive ?? false,
+    confirm: opts.confirm ?? (async () => true),
+    editsUnlocked: false,
+    changeId: null,
+    proposalValidated: false,
+    filesTouched: new Set(),
+    decisions: [],
+    lastErc: null,
+    lastDrc: null,
+    repairCycles: 0,
+    finishRequest: null,
+  };
+
+  let provider = makeProvider(opts.model);
+  const constraints = await loadConstraints(repoRoot);
+  const system = await buildSystemPrompt(repoRoot, config, constraints);
+  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 });
+
+  let tokensIn = 0;
+  let tokensOut = 0;
+  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 summaryPath = await transcript.writeSummary({
+      request: opts.request,
+      changeId: ctx.changeId,
+      plan,
+      filesTouched: [...ctx.filesTouched],
+      ercResult: ctx.lastErc ? (ctx.lastErc.ok ? 'clean' : `${ctx.lastErc.violations.length} violations`) : null,
+      drcResult: ctx.lastDrc ? (ctx.lastDrc.ok ? 'clean' : `${ctx.lastDrc.violations.length} violations`) : null,
+      decisions: ctx.decisions,
+      tokensIn,
+      tokensOut,
+      outcome: 'failure',
+      openObligations: ctx.ledger.isClear ? null : ctx.ledger.describe(),
+      detail: reason,
+    });
+    log(`run failed: ${reason}`);
+    log(`working tree restored to pre-run snapshot`);
+    log(`transcript: ${transcript.jsonlPath}`);
+    log(`summary: ${summaryPath}`);
+    return {
+      outcome: 'failure',
+      summary: reason,
+      transcriptDir: transcript.dir,
+      filesTouched: [],
+      commit: null,
+    };
+  };
+
+  for (let turn = 0; turn < maxTurns; turn++) {
+    const tools = availableTools(ctx).map((t) => t.schema);
+    let res: Turn;
+    try {
+      res = await withRetry(() => provider.chat(messages, tools), {
+        onRetry: (attempt) => log(`rate limited; retry ${attempt}`),
+      });
+    } catch (err) {
+      if (isRateLimit(err)) {
+        const fallback = otherProvider(provider);
+        if (fallback) {
+          log(`failing over ${provider.name} → ${fallback.name}`);
+          await transcript.event('provider-failover', { from: provider.name, to: fallback.name });
+          provider = fallback;
+          turn--;
+          continue;
+        }
+      }
+      return fail(`provider error: ${(err as Error).message}`);
+    }
+    tokensIn += res.usage.inputTokens;
+    tokensOut += res.usage.outputTokens;
+    await transcript.event('assistant', { text: res.text, toolCalls: res.toolCalls });
+
+    if (res.text) {
+      if (!plan) plan = res.text;
+      log(res.text);
+    }
+    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');
+      messages.push({
+        role: 'user',
+        content: 'Continue using tools, or call finish({outcome, summary}) to end the run.',
+      });
+      continue;
+    }
+
+    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]}`);
+      messages.push({ role: 'tool', toolCallId: call.id, content: result });
+    }
+
+    if (ctx.repairCycles > config.maxRepairCycles) {
+      return fail(`repair cycles exhausted (${config.maxRepairCycles}); violations persist`);
+    }
+
+    const remaining = maxTurns - 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.',
+      });
+    }
+
+    if (ctx.finishRequest) {
+      const { outcome, summary } = ctx.finishRequest;
+      const files = [...ctx.filesTouched];
+      if (outcome === 'refuse') {
+        await restore(repoRoot, snap);
+        await transcript.event('run-refused', { summary });
+        await transcript.writeSummary({
+          request: opts.request,
+          changeId: ctx.changeId,
+          plan,
+          filesTouched: [],
+          ercResult: null,
+          drcResult: null,
+          decisions: ctx.decisions,
+          tokensIn,
+          tokensOut,
+          outcome: 'aborted',
+          openObligations: null,
+          detail: `REFUSED: ${summary}`,
+        });
+        log(`refused: ${summary}`);
+        return { outcome: 'refused', summary, transcriptDir: transcript.dir, filesTouched: [], commit: null };
+      }
+
+      const verification = [
+        ctx.lastErc ? `ERC ${ctx.lastErc.ok ? 'clean' : 'FAILING'}` : 'ERC not required',
+        ctx.lastDrc ? `DRC ${ctx.lastDrc.ok ? 'clean' : 'FAILING'}` : null,
+      ]
+        .filter(Boolean)
+        .join(', ');
+
+      if (opts.dryRun) {
+        const { stdout: diff } = await execa('git', ['diff'], { cwd: repoRoot });
+        const { stdout: untracked } = await execa('git', ['ls-files', '--others', '--exclude-standard'], {
+          cwd: repoRoot,
+        });
+        log('--- dry run: proposed diff ---');
+        log(diff || '(no diff)');
+        if (untracked) log(`new files:\n${untracked}`);
+        await restore(repoRoot, snap);
+        await transcript.writeSummary({
+          request: opts.request,
+          changeId: ctx.changeId,
+          plan,
+          filesTouched: files,
+          ercResult: verification,
+          drcResult: null,
+          decisions: ctx.decisions,
+          tokensIn,
+          tokensOut,
+          outcome: 'success',
+          openObligations: null,
+          detail: 'dry run: changes reverted',
+        });
+        return { outcome: 'success', summary, transcriptDir: transcript.dir, filesTouched: files, commit: null };
+      }
+
+      await appendChangelog(repoRoot, config, {
+        changeId: ctx.changeId,
+        request: opts.request,
+        files,
+        verification,
+      });
+      ctx.ledger.clear('changelog');
+
+      const commitMsg = `copperhead: ${opts.request}\n\n${summary}\n\nVerification: ${verification}`;
+      const commit = await commitAll(repoRoot, commitMsg);
+      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}`);
+        }
+      }
+      await transcript.event('run-committed', { commit, files });
+      await transcript.writeSummary({
+        request: opts.request,
+        changeId: ctx.changeId,
+        plan,
+        filesTouched: files,
+        ercResult: ctx.lastErc ? (ctx.lastErc.ok ? 'clean' : 'FAILING') : 'not run',
+        drcResult: ctx.lastDrc ? (ctx.lastDrc.ok ? 'clean' : 'FAILING') : 'not run',
+        decisions: ctx.decisions,
+        tokensIn,
+        tokensOut,
+        outcome: 'success',
+        openObligations: null,
+      });
+      log(`committed ${commit.slice(0, 10)} (${files.length} file(s))`);
+      return { outcome: 'success', 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)`);
+}

package/src/agent/prompts.ts

@@ -0,0 +1,58 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import type { CopperheadConfig } from '../config.js';
+import type { ConstraintRegistry } from '../memory/constraints.js';
+
+/** SPEC §4.3 — verbatim requirements. */
+const SYSTEM_RULES = `You are a hardware design agent working on real KiCad source files. Edit s-expressions surgically; never regenerate a whole file.
+You cannot edit any file until your change proposal validates. Write the proposal first; the edit tools appear only after it passes.
+The design docs are the memory. Read them before proposing anything; update them with everything you change.
+Hold ALL constraints simultaneously: electrical budgets (e.g. sleep current), voltage ranges, package availability, strapping pins, RTC-capability, antenna keepouts. A part that satisfies the obvious constraint but violates a budget is a bug.
+Check the MCU strapping table before assigning any pin. Check quiescent/leakage current of every part against the power budget in SPEC.md.
+Nothing is done until ERC (and DRC when applicable) passes. Read the violation report; do not guess.
+Write a one-line rationale next to every decision. If you remove a part, record why the absence is intentional (a missing pullup can look like a mistake).
+If a request would violate a documented budget or constraint, stop and say so — do not silently comply.`;
+
+const WORKFLOW = `Workflow for every run:
+1. The design docs are already loaded below. Plan: state in one short block what will change, which files are affected, which constraints are at risk.
+2. Call propose_change with a change id (kebab-case), why, what changes, and tasks. Then call validate_change. Edit tools (edit_file, write_file) unlock only after validation passes.
+3. Make the edits. Use the exact same net names and refdes everywhere. For .kicad_sch/.kicad_pcb use edit_file with unique anchors from the actual file text (read the file first). For renaming a net or refdes across a file, one edit_file call with replace_all: true beats many small edits.
+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.`;
+
+export async function buildSystemPrompt(
+  repoRoot: string,
+  config: CopperheadConfig,
+  constraints: ConstraintRegistry,
+): Promise<string> {
+  const parts = [SYSTEM_RULES, '', WORKFLOW];
+
+  if (Object.keys(config.budgets).length) {
+    parts.push('', '## Hard budgets (from .copperhead/config.json — treat as constraints)', '');
+    for (const [k, v] of Object.entries(config.budgets)) parts.push(`- ${k}: ${v}`);
+  }
+
+  if (Object.keys(constraints).length) {
+    parts.push('', '## Constraint registry (.copperhead/constraints.json)', '', '```json');
+    parts.push(JSON.stringify(constraints, null, 2), '```');
+  }
+
+  const docsDir = path.join(repoRoot, config.docs);
+  if (existsSync(docsDir)) {
+    const files = (await readdir(docsDir)).filter((f) => f.endsWith('.md')).sort();
+    for (const f of files) {
+      const text = await readFile(path.join(docsDir, f), 'utf8');
+      parts.push('', `## docs/${f}`, '', text);
+    }
+  }
+
+  if (config.schematic) {
+    parts.push('', `## KiCad files`, '', `- schematic: ${config.schematic}`);
+    if (config.board) parts.push(`- board: ${config.board}`);
+  }
+
+  return parts.join('\n');
+}

package/src/agent/providers/anthropic.ts

@@ -0,0 +1,81 @@
+import type { ChatOpts, Msg, Provider, ToolSchema, Turn } from '../types.js';
+
+type AnthropicContent =
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: unknown }
+  | { type: 'tool_result'; tool_use_id: string; content: string };
+
+export class AnthropicProvider implements Provider {
+  readonly name = 'anthropic';
+
+  constructor(
+    private readonly model = 'claude-sonnet-5',
+    private readonly apiKey = process.env.ANTHROPIC_API_KEY,
+  ) {
+    if (!this.apiKey) throw new Error('ANTHROPIC_API_KEY is not set');
+  }
+
+  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 });
+
+    const system = messages
+      .filter((m) => m.role === 'system')
+      .map((m) => m.content)
+      .join('\n\n');
+
+    const conv: { role: 'user' | 'assistant'; content: AnthropicContent[] | string }[] = [];
+    for (const m of messages) {
+      if (m.role === 'system') continue;
+      if (m.role === 'user') {
+        conv.push({ role: 'user', content: m.content });
+      } else if (m.role === 'assistant') {
+        const content: AnthropicContent[] = [];
+        if (m.content) content.push({ type: 'text', text: m.content });
+        for (const t of m.toolCalls ?? []) {
+          content.push({ type: 'tool_use', id: t.id, name: t.name, input: t.args });
+        }
+        if (content.length) conv.push({ role: 'assistant', content });
+      } else {
+        // 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)) {
+          prev.content.push(block);
+        } else {
+          conv.push({ role: 'user', content: [block] });
+        }
+      }
+    }
+
+    const res = await client.messages.create({
+      model: this.model,
+      max_tokens: opts.maxTokens ?? 8192,
+      ...(system ? { system } : {}),
+      messages: conv as never,
+      ...(tools.length
+        ? {
+            tools: tools.map((t) => ({
+              name: t.name,
+              description: t.description,
+              input_schema: t.parameters as never,
+            })),
+          }
+        : {}),
+    });
+
+    let text: string | null = null;
+    const toolCalls = [];
+    for (const block of res.content) {
+      if (block.type === 'text') text = (text ?? '') + block.text;
+      if (block.type === 'tool_use') {
+        toolCalls.push({ id: block.id, name: block.name, args: block.input as Record<string, unknown> });
+      }
+    }
+    return {
+      text,
+      toolCalls,
+      usage: { inputTokens: res.usage.input_tokens, outputTokens: res.usage.output_tokens },
+    };
+  }
+}