copperhead 0.6.0 → 0.8.0

package/src/agent/theme.ts

@@ -0,0 +1,91 @@
+/**
+ * Subtle interactive-TTY chrome: muted hierarchy with a copper accent.
+ * Plain / --json / piped output must stay free of SGR (AC-8.9), so helpers
+ * no-op unless color has been explicitly enabled for this process.
+ */
+
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+
+/** True after makeRenderer selects the interactive path. */
+let colorEnabled = false;
+
+export function setColorEnabled(on: boolean): void {
+  colorEnabled = on;
+}
+
+export function isColorEnabled(): boolean {
+  return colorEnabled;
+}
+
+function paint(code: string, s: string): string {
+  if (!colorEnabled || s === '') return s;
+  return `${ESC}${code}m${s}${RESET}`;
+}
+
+const TRUECOLOR = /truecolor|24bit/i.test(process.env.COLORTERM ?? '');
+
+/** Secondary metadata — soft gray #999999 (truecolor), SGR 90 fallback. */
+export const dim = (s: string): string => paint(TRUECOLOR ? '38;2;153;153;153' : '90', s);
+/** Rules/separators — one step darker than dim: #888888. */
+export const ruleDim = (s: string): string => paint(TRUECOLOR ? '38;2;136;136;136' : '90', s);
+/** Primary content — bright white (typed input, key values). */
+export const bright = (s: string): string => paint('97', s);
+
+/** Exact brand copper #b87333 where truecolor is available; warm 256 fallback. */
+const COPPER_SGR = TRUECOLOR ? '38;2;184;115;51' : '38;5;173';
+/** Light copper tint (brand accent-high #eec9a5) — menu hover. */
+export const copperLight = (s: string): string =>
+  paint(TRUECOLOR ? '38;2;238;201;165' : '38;5;223', s);
+/** Title emphasis — bold in the terminal's default foreground (theme-adaptive). */
+export const bold = (s: string): string => paint('1', s);
+/** Brand / active accent — exact copper #b87333 (truecolor), 256-color 173 fallback. */
+export const copper = (s: string): string => paint(COPPER_SGR, s);
+/** Success — PCB green. */
+export const ok = (s: string): string => paint('32', s);
+/** Busy / caution — amber. */
+export const warn = (s: string): string => paint('33', s);
+/** Failure. */
+export const err = (s: string): string => paint('31', s);
+
+/**
+ * Style a create-pipeline stage line. Keeps the `stage <name>:` prefix so
+ * existing log greps and operator muscle memory still work.
+ */
+export function stageLine(name: string, detail: string, kind: 'info' | 'ok' | 'warn' | 'err' = 'info'): string {
+  const label = dim(`stage ${name}:`);
+  const body =
+    kind === 'ok' ? ok(detail) : kind === 'warn' ? warn(detail) : kind === 'err' ? err(detail) : detail;
+  return `${label} ${body}`;
+}
+
+/** Tool-result scrollback line: short glyph + name + first line of result. */
+export function toolLine(name: string, firstLine: string): string {
+  const clean = /\b(clean|ok|pass(?:ed)?|success|done)\b/i.test(firstLine) && !/\b(fail|error|violat)/i.test(firstLine);
+  const glyph = clean ? ok('✓') : copper('▸');
+  return `  ${glyph} ${dim(name)}  ${firstLine}`;
+}
+
+/** Color the final outcome line from its exit-path token. */
+export function styleOutcome(line: string): string {
+  if (!colorEnabled) return line;
+  const head = line.split(' · ')[0] ?? line;
+  const rest = line.slice(head.length);
+  if (head === 'done') return ok(head) + dim(rest);
+  if (/refus|fail|error|exhaust|stall/i.test(head)) return err(head) + dim(rest);
+  return copper(head) + dim(rest);
+}
+
+/** Dim secondary segments of the two-line CLI header (brand stays copper). */
+export function styleHeaderLines(lines: string[]): string[] {
+  if (!colorEnabled) return lines;
+  return lines.map((line, i) => {
+    if (i === 0) {
+      // copperhead vX · rest…
+      const m = line.match(/^(copperhead v\S+)(.*)$/);
+      if (!m) return dim(line);
+      return copper(m[1]!) + dim(m[2]!);
+    }
+    return dim(line);
+  });
+}

package/src/agent/tools.ts

@@ -6,6 +6,7 @@ import { resolveInRepo, isKicadFile } from '../util/paths.js';
 import { runErc, runDrc, exportSvg, exportFab, kicadLoadError, isProbeableKicadFile } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
 import { listSymbols, listNets } from '../kicad/sexp.js';
+import { verifySchematicSymbols } from '../kicad/symlib.js';
 import { checkDrift } from '../memory/drift.js';
 import { saveConstraint, classifyAffectsTarget, affectsTargetExists } from '../memory/constraints.js';
 import { openspecValidate } from '../openspec/cli.js';
@@ -52,6 +53,24 @@ const str = (args: Record<string, unknown>, key: string): string => {
   return v;
 };
 
+// U+FFFD (the Unicode replacement character) is what a byte sequence becomes
+// when UTF-8 decoding fails — most often a multibyte glyph (Ω, µ, ±, °) split
+// across a streaming chunk boundary and decoded per-chunk upstream in the
+// provider SDK (I2). It never appears in a legitimately authored PCB doc, so
+// its presence in a content-bearing tool arg means the value arrived corrupted.
+// Reject the call before it lands on disk so the model re-emits; the corruption
+// is nondeterministic (it depends on where a chunk boundary fell), so the retry
+// almost always comes through clean — far cheaper than shipping a mangled value
+// like "5.1kΩ" → "5.1k�" into DECISIONS.md and only noticing on review.
+const REPLACEMENT_CHAR = '�';
+export function corruptionError(fields: Record<string, unknown>): string | null {
+  const bad = Object.entries(fields)
+    .filter(([, v]) => typeof v === 'string' && v.includes(REPLACEMENT_CHAR))
+    .map(([k]) => k);
+  if (!bad.length) return null;
+  return `rejected: the ${bad.join(', ')} value contains U+FFFD (�), the replacement character that signals a UTF-8 decoding error — a special character (e.g. Ω, µ, ±, °) was likely mangled in transit. Re-send this exact call with the intended character written correctly, or spell it in ASCII (e.g. "ohm", "uF", "+/-", "deg").`;
+}
+
 function markTouched(ctx: RunContext, rel: string): void {
   ctx.filesTouched.add(rel);
   if (isKicadFile(rel)) {
@@ -202,7 +221,7 @@ export const TOOLS: ToolDef[] = [
     schema: {
       name: 'edit_file',
       description:
-        'Exact-match anchored replace in an existing file. The anchor must be unique; widen it with surrounding lines if not. For renames, pass replace_all: true to replace every occurrence in one call.',
+        'Exact-match anchored replace in an existing file. Requires a validated change proposal first (call propose_change then validate_change to unlock edits; both may be in the same reply, before this call). The anchor must be unique; widen it with surrounding lines if not. For renames, pass replace_all: true to replace every occurrence in one call.',
       parameters: {
         type: 'object',
         properties: {
@@ -216,6 +235,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
+      const corrupt = corruptionError({ new_string: args.new_string });
+      if (corrupt) return corrupt;
       const rel = str(args, 'path');
       const abs = resolveInRepo(ctx.repoRoot, rel);
       // Text edits can corrupt an s-expression file in ways the editor cannot
@@ -256,7 +277,8 @@ export const TOOLS: ToolDef[] = [
   {
     schema: {
       name: 'write_file',
-      description: 'Create a new file (docs, outputs). Refuses to overwrite anything or to create KiCad files.',
+      description:
+        'Create a new file (docs, outputs). Requires a validated change proposal first (propose_change then validate_change to unlock edits). Refuses to overwrite anything or to create KiCad files.',
       parameters: {
         type: 'object',
         properties: { path: { type: 'string' }, content: { type: 'string' } },
@@ -265,6 +287,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
+      const corrupt = corruptionError({ content: args.content });
+      if (corrupt) return corrupt;
       const rel = str(args, 'path');
       const res = await toolWriteFile(ctx.repoRoot, rel, args.content as string);
       markTouched(ctx, rel);
@@ -281,11 +305,43 @@ export const TOOLS: ToolDef[] = [
     handler: async (ctx) => {
       if (!ctx.config.schematic)
         return 'no schematic configured; ERC does not apply yet — skip it until a schematic exists and is set in .copperhead/config.json';
-      const report = await runErc(path.join(ctx.repoRoot, ctx.config.schematic));
+      const schPath = path.join(ctx.repoRoot, ctx.config.schematic);
+      const report = await runErc(schPath);
       ctx.lastErc = report;
       if (report.ok) ctx.ledger.clear('erc');
       else ctx.repairCycles++;
-      return formatViolations(report);
+      const out = formatViolations(report);
+      // A zero-symbol schematic passes ERC with 0 violations — a false green
+      // (3.2) that lets a premature finish look verified (an empty sheet also
+      // passes drift). The stage contract already requires symbols>0, but a bare
+      // "ERC clean" on the empty starting sheet still misleads the model, so warn
+      // here too: no gate should read as satisfied by the empty starting state.
+      if (report.ok && !(await listSymbols(schPath)).length) {
+        return `${out}\nwarning: ERC is clean but the schematic has ZERO symbols — an empty sheet always passes ERC, so this is NOT a verified design. Capture the parts from BOM.md (and re-run run_erc) before calling finish.`;
+      }
+      return out;
+    },
+  },
+  {
+    schema: {
+      name: 'verify_symbols',
+      description:
+        "Cross-check every lib_symbols entry in the schematic against the KiCad symbol library installed on this machine. Reports pins that diverge from the real part (wrong count, name, or electrical type) and lib_ids that do not exist in the current KiCad version (with the closest real names). ERC cannot catch these — a symbol whose lib_id claims to be a canonical part but whose pins are wrong passes ERC while being wrong. Run this after capturing symbols and reconcile every finding.",
+      parameters: { type: 'object', properties: {}, required: [] },
+    },
+    requiresUnlock: false,
+    handler: async (ctx) => {
+      if (!ctx.config.schematic)
+        return 'no schematic configured; verify_symbols does not apply yet';
+      const { findings, checked, skipped } = await verifySchematicSymbols(
+        path.join(ctx.repoRoot, ctx.config.schematic),
+      );
+      if (!findings.length) {
+        return `verify_symbols: ${checked} symbol(s) match the installed KiCad library. No divergences.`;
+      }
+      const lines = findings.map((f) => `  - [${f.kind}] ${f.detail}`);
+      const mismatches = findings.filter((f) => f.kind !== 'no-library').length;
+      return `verify_symbols: ${checked} verified, ${skipped} unverifiable (library not installed), ${mismatches} issue(s) to reconcile:\n${lines.join('\n')}`;
     },
   },
   {
@@ -514,6 +570,8 @@ export const TOOLS: ToolDef[] = [
     },
     requiresUnlock: true,
     handler: async (ctx, args) => {
+      const corrupt = corruptionError({ decision: args.decision, rationale: args.rationale, affects: args.affects });
+      if (corrupt) return corrupt;
       const decision = str(args, 'decision');
       const rationale = str(args, 'rationale');
       const affects = (args.affects as string | undefined) ?? '';

package/src/agent/transcript.ts

@@ -12,6 +12,7 @@ export type ExitPath =
   | 'repair-cycles-exhausted'
   | 'commit-failed'
   | 'provider-error'
+  | 'session-limit'
   | 'stalled';
 
 /** Post-run addenda recorded at every terminal branch (AC-8.5). */

package/src/agent/types.ts

@@ -21,10 +21,27 @@ export interface Turn {
   text: string | null;
   toolCalls: ToolCall[];
   usage: { inputTokens: number; outputTokens: number };
+  /**
+   * A one-line steer for a turn that produced NO tool call but clearly *intended*
+   * one — e.g. a fenced ```json block that names a real tool yet fails to parse
+   * (unbalanced braces). The loop surfaces it in place of the generic
+   * "continue using tools" nudge so the model fixes the malformed call instead of
+   * misreading the silence as a broken tool (#I10). Providers that can't detect
+   * a near-miss simply never set it.
+   */
+  nudge?: string;
 }
 
 export interface ChatOpts {
   maxTokens?: number;
+  /**
+   * Liveness callback for the loop's heartbeat (5.1). A streaming provider calls
+   * it as output arrives, passing the cumulative streamed-output length in chars,
+   * so a slow turn can be told apart from a hung one. Providers that don't stream
+   * simply never call it (the heartbeat still reports elapsed time). Never used
+   * for billing — real token usage is reported once, on the returned Turn.
+   */
+  onStream?: (streamedChars: number) => void;
 }
 
 export interface Provider {

package/src/cli.ts

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import path from 'node:path';
 import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
-import { loadConfig, resolveModel } from './config.js';
+import { loadConfig, resolveModel, type ModelSource } from './config.js';
+import { pickModel } from './util/select.js';
 import { runInit, InitError } from './memory/scaffold.js';
 import { runCheck } from './commands/check.js';
+import { runDoctor, formatDoctor } from './commands/doctor.js';
 import { syncVerify, syncResolve, formatSyncReport } from './commands/sync.js';
 import { runCreate } from './commands/create.js';
+import { runDemo, demoTourText } from './commands/demo.js';
+import { runRepl } from './commands/repl.js';
 import {
   runExportBom,
   parseSupplier,
@@ -20,6 +23,7 @@ import { runAgentLoop, type BudgetExhaustedStats } from './agent/loop.js';
 import { makeRenderer } from './agent/render.js';
 import { kicadCliVersion } from './kicad/cli.js';
 import { loadEnvFile } from './util/env.js';
+import { budgetExtraTurns, budgetPromptText, parseMaxTurns, repoOf } from './util/cli-args.js';
 
 // Read .env from the working directory before any command resolves a model or a
 // provider. Loaded here rather than per-command so `check` behaves identically,
@@ -35,8 +39,6 @@ const { version } = createRequire(import.meta.url)('../package.json') as { versi
 
 const program = new Command();
 
-const repoOf = (opts: { repo?: string }): string => path.resolve(opts.repo ?? process.cwd());
-
 async function confirmTty(question: string): Promise<boolean> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const answer = await rl.question(`${question} [y/N] `);
@@ -50,14 +52,8 @@ async function confirmTty(question: string): Promise<boolean> {
  */
 function budgetContinuePrompt(): ((stats: BudgetExhaustedStats) => Promise<number>) | undefined {
   if (!process.stdin.isTTY || !process.stdout.isTTY) return undefined;
-  return async (stats) => {
-    // ceil of the ORIGINAL budget (design D1), so repeat extensions offer the
-    // same increment instead of escalating with the extended turn count.
-    const extra = Math.ceil(stats.maxTurns / 2);
-    const k = (n: number) => `${(n / 1000).toFixed(1)}k`;
-    const q = `Turn budget exhausted (${stats.turnsUsed} turns, ${k(stats.tokensIn)} in / ${k(stats.tokensOut)} out, ${stats.filesTouched.length} file(s) touched, ${stats.openObligations} open obligation(s)). Continue with ${extra} more turns?`;
-    return (await confirmTty(q)) ? extra : 0;
-  };
+  return async (stats) =>
+    (await confirmTty(budgetPromptText(stats))) ? budgetExtraTurns(stats) : 0;
 }
 
 program
@@ -71,6 +67,68 @@ program
 const rendererOf = () =>
   makeRenderer({ json: Boolean(program.opts().json), plain: Boolean(program.opts().plain) });
 
+program
+  .command('repl', { isDefault: true })
+  .description('interactive agent shell (default when no command is given)')
+  .argument('[request...]', 'optional first change request before the prompt loop')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--max-turns <n>', 'turn budget per request')
+  .option('--allow-dirty', 'let turns run on a dirty working tree')
+  .option('--interactive', 'pause for approval after each proposal validates')
+  .action(
+    async (
+      requestParts: string[],
+      opts: { model?: string; maxTurns?: string; allowDirty?: boolean; interactive?: boolean },
+    ) => {
+      const repo = repoOf(program.opts());
+      if (program.opts().json) {
+        console.error(
+          'copperhead: --json is not supported with the interactive shell. Use `copperhead do "<request>" --json`.',
+        );
+        process.exit(1);
+      }
+      try {
+        const kicadVer = await kicadCliVersion();
+        const config = await loadConfig(repo);
+        const renderer = rendererOf();
+        let model: string;
+        let source: ModelSource;
+        try {
+          ({ model, source } = resolveModel(opts.model, config));
+        } catch (err) {
+          // No model anywhere (flag, COPPERHEAD_MODEL, config, .env keys):
+          // on a TTY, offer an interactive pick instead of refusing to start.
+          if (!process.stdin.isTTY || !process.stdout.isTTY) throw err;
+          console.log('No model configured for this session, pick one:');
+          const chosen = await pickModel();
+          if (!chosen) throw err;
+          model = chosen;
+          source = 'picker';
+        }
+        const continuePrompt = budgetContinuePrompt();
+        const seed = requestParts.length ? requestParts.join(' ') : undefined;
+        const res = await runRepl({
+          repoRoot: repo,
+          model,
+          modelSource: source,
+          version,
+          kicadCliVersion: kicadVer,
+          ...(opts.maxTurns ? { maxTurns: parseMaxTurns(opts.maxTurns) } : {}),
+          allowDirty: opts.allowDirty ?? false,
+          interactive: opts.interactive ?? false,
+          ...(seed ? { seed } : {}),
+          confirm: confirmTty,
+          ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
+          renderer,
+        });
+        process.exit(res.ok ? 0 : 1);
+      } catch (err) {
+        console.error((err as Error).message);
+        process.exit(1);
+      }
+    },
+  );
+
 program
   .command('init')
   .description('scaffold docs/ from an existing schematic; idempotent')
@@ -121,11 +179,30 @@ program
   .description('ERC + DRC + doc-drift + spec validation; no LLM calls; CI-safe')
   .action(checkAction);
 
+program
+  .command('doctor')
+  .description('env preflight: kicad-cli, git, node, and the model provider credential; no LLM, no network')
+  .option('--model <model>', 'model to check the provider credential for (default: resolved like a run)')
+  .action(async (opts: { model?: string }) => {
+    const repo = repoOf(program.opts());
+    // Unlike other commands, doctor never gates on kicad-cli being present:
+    // runDoctor probes it and reports a failure instead of throwing, so a user
+    // with a missing tool still gets the full report.
+    const report = await runDoctor({ repoRoot: repo, model: opts.model });
+    if (program.opts().json) console.log(JSON.stringify(report, null, 2));
+    else {
+      const color = process.stdout.isTTY === true && !process.env.NO_COLOR;
+      // || not ??: some non-interactive ptys report columns as 0.
+      for (const line of formatDoctor(report, process.stdout.columns || 80, color)) console.log(line);
+    }
+    process.exit(report.ok ? 0 : 1);
+  });
+
 program
   .command('do')
   .description('the core loop: propose, edit, verify, propagate, commit')
   .argument('<request>', 'the change request in natural language')
-  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--max-turns <n>', 'turn budget for this run')
   .option('--allow-dirty', 'allow a dirty tree (snapshot via git stash create)')
   .option('--dry-run', 'propose the diff, write nothing')
@@ -145,7 +222,7 @@ program
           repoRoot: repo,
           request,
           model,
-          ...(opts.maxTurns ? { maxTurns: parseInt(opts.maxTurns, 10) } : {}),
+          ...(opts.maxTurns ? { maxTurns: parseMaxTurns(opts.maxTurns) } : {}),
           allowDirty: opts.allowDirty ?? false,
           dryRun: opts.dryRun ?? false,
           interactive: opts.interactive ?? false,
@@ -199,11 +276,58 @@ program
     }
   });
 
+program
+  .command('demo')
+  .description('tour of what copperhead does, or run the USB-C breakout create pipeline')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--interactive', 're-enable the human gates (spec approval, pre-export)')
+  .option('--dir <path>', 'demo repo directory (default: demo-runs/usb-c-breakout)')
+  .option('--tour', 'print the overview only; do not run the pipeline')
+  .action(async (opts: { model?: string; interactive?: boolean; dir?: string; tour?: boolean }) => {
+    if (opts.tour) {
+      const { setColorEnabled } = await import('./agent/theme.js');
+      if (program.opts().json) {
+        // --json is a contract, not a suggestion: a script that passes it
+        // unconditionally must never get prose back. Plain lines, no SGR.
+        setColorEnabled(false);
+        console.log(JSON.stringify({ tour: demoTourText().split('\n') }, null, 2));
+        process.exit(0);
+      }
+      // Color on for attended TTY tours even without a renderer.
+      setColorEnabled(Boolean(process.stdout.isTTY) && !program.opts().plain && !process.env.NO_COLOR);
+      console.log(demoTourText());
+      process.exit(0);
+    }
+    try {
+      const kicadVer = await kicadCliVersion();
+      // Resolve model from the caller's cwd config / env / flag; the demo repo
+      // is scaffolded next and typically has no model of its own yet.
+      const config = await loadConfig(repoOf(program.opts()));
+      const { model, source } = resolveModel(opts.model, config);
+      const continuePrompt = budgetContinuePrompt();
+      const res = await runDemo({
+        model,
+        modelSource: source,
+        version,
+        kicadCliVersion: kicadVer,
+        interactive: opts.interactive ?? false,
+        ...(opts.dir ? { demoDir: opts.dir } : {}),
+        ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
+        log: (s) => console.log(s),
+        renderer: rendererOf(),
+      });
+      process.exit(res.ok ? 0 : 1);
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('create')
   .description('Mode A: full pipeline from a product brief to the output package')
   .requiredOption('--brief <file>', 'product brief (markdown)')
-  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--interactive', 're-enable the human gates (spec approval, pre-export)')
   .action(async (opts: { brief: string; model?: string; interactive?: boolean }) => {
     const repo = repoOf(program.opts());