copperhead 0.9.0 → 0.11.0

package/src/agent/recovery.ts

@@ -2,11 +2,25 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import type { Msg, Provider } from './types.js';
+import { resolveLibrarySymbol, searchInstalledSymbols, symbolSearchDirs, listInstalledLibraries } from '../kicad/symlib.js';
 
-/** Thrown when a single provider turn blows past its watchdog deadline. */
+/**
+ * How many times a hung provider turn is retried before the run gives up. One
+ * policy, two turn loops: the main agent loop and the nested skill sub-run.
+ */
+export const MAX_TURN_TIMEOUTS = 3;
+
+/**
+ * Thrown when a provider turn trips its watchdog. `idle`: no response or
+ * progress for `ms`, so the call looks hung. `max`: still running at the hard
+ * cap however much progress it reported, so the turn is too large, not hung.
+ */
 export class TurnTimeoutError extends Error {
-  constructor(public readonly ms: number) {
-    super(`turn exceeded ${ms}ms without responding`);
+  constructor(
+    public readonly ms: number,
+    public readonly kind: 'idle' | 'max' = 'idle',
+  ) {
+    super(kind === 'max' ? `turn still running after ${ms}ms (hard cap)` : `turn exceeded ${ms}ms without responding`);
     this.name = 'TurnTimeoutError';
   }
 }
@@ -23,18 +37,81 @@ export async function withTimeout<T>(
   ms: number,
   onTimeout?: () => void | Promise<void>,
 ): Promise<T> {
-  if (!Number.isFinite(ms) || ms <= 0) return fn();
-  let timer: ReturnType<typeof setTimeout> | undefined;
+  return withWatchdog(() => fn(), { idleMs: ms, ...(onTimeout ? { onTimeout } : {}) });
+}
+
+/**
+ * The turn watchdog: `withTimeout` with the deadline measured from the last sign
+ * of progress instead of from the start. `fn` receives an `activity` callback and
+ * each call restarts the `idleMs` deadline, so a long turn that keeps producing
+ * output is never mistaken for a hung one, while a call that reports nothing gets
+ * `idleMs` as a plain whole-call deadline (unchanged for providers that cannot
+ * stream). `maxMs` is a hard cap activity does not extend, so a turn that streams
+ * forever still ends. The cap bounds a call that is producing output, so it only
+ * trips once `fn` has reported progress (a silent call is judged by `idleMs`
+ * alone, exactly as before the cap existed), and it is never shorter than
+ * `idleMs` (a lower cap would cut off a turn the idle deadline alone allows).
+ * `<= 0` (or non-finite) disables either limit; with both disabled this just
+ * awaits `fn`.
+ */
+export async function withWatchdog<T>(
+  fn: (activity: () => void) => Promise<T>,
+  opts: { idleMs: number; maxMs?: number; onTimeout?: () => void | Promise<void> },
+): Promise<T> {
+  const idleOn = Number.isFinite(opts.idleMs) && opts.idleMs > 0;
+  const maxMs = opts.maxMs ?? 0;
+  const maxOn = Number.isFinite(maxMs) && maxMs > 0;
+  if (!idleOn && !maxOn) return fn(() => {});
+  const capMs = idleOn ? Math.max(maxMs, opts.idleMs) : maxMs;
+  let idleTimer: ReturnType<typeof setTimeout> | undefined;
+  let maxTimer: ReturnType<typeof setTimeout> | undefined;
+  // Set once the race is decided either way, so a late activity() from an
+  // abandoned call cannot re-arm a timer after the watchdog is done.
+  let settled = false;
+  // Whether fn has reported progress yet, and whether the cap came due while it
+  // had not (see the cap timer below).
+  let progressed = false;
+  let capPassed = false;
+  let trip!: (err: TurnTimeoutError) => void;
   const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      void Promise.resolve(onTimeout?.()).catch(() => {});
-      reject(new TurnTimeoutError(ms));
-    }, ms);
+    trip = (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(idleTimer);
+      clearTimeout(maxTimer);
+      // Reject before tearing down: onTimeout (provider.close()) may reject the
+      // in-flight call synchronously, and the race must settle on the timeout,
+      // not on that teardown error, or the caller never sees TurnTimeoutError.
+      reject(err);
+      void Promise.resolve(opts.onTimeout?.()).catch(() => {});
+    };
   });
+  const armIdle = (): void => {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => trip(new TurnTimeoutError(opts.idleMs, 'idle')), opts.idleMs);
+  };
+  const activity = (): void => {
+    if (settled) return;
+    progressed = true;
+    if (capPassed) return trip(new TurnTimeoutError(capMs, 'max'));
+    if (idleOn) armIdle();
+  };
+  if (idleOn) armIdle();
+  if (maxOn) {
+    maxTimer = setTimeout(() => {
+      // The cap bounds a turn that is producing output. A call that has reported
+      // nothing yet stays under the idle deadline alone; if it starts reporting
+      // progress later, the cap applies at that moment.
+      if (progressed) trip(new TurnTimeoutError(capMs, 'max'));
+      else capPassed = true;
+    }, capMs);
+  }
   try {
-    return await Promise.race([fn(), timeout]);
+    return await Promise.race([fn(activity), timeout]);
   } finally {
-    if (timer) clearTimeout(timer);
+    settled = true;
+    clearTimeout(idleTimer);
+    clearTimeout(maxTimer);
   }
 }
 
@@ -116,6 +193,91 @@ export async function transcriptExcerpt(transcriptDir: string, maxChars = 4000):
   return joined.length > maxChars ? joined.slice(joined.length - maxChars) : joined;
 }
 
+/**
+ * Deterministically re-probe every lib_id named in a failure narrative against
+ * the installed libraries, so the diagnostician judges symbol-availability
+ * claims from machine facts instead of the agent's prose. An agent that has
+ * been dead-ended by wrong library nicknames concludes — and records — that
+ * whole libraries are absent when they are installed; a refusal built on that
+ * premise reads exactly like a genuine environmental gap, and the one thing
+ * that distinguishes them is re-checking the named lib_ids, which costs no
+ * LLM turn. Never throws; on any probe error it reports what it could.
+ */
+export async function symbolAvailabilityFacts(text: string, dirs?: string[], cap = 8): Promise<string> {
+  const ids: string[] = [];
+  // A library nickname is its `.kicad_sym` filename stem, so it can carry `-`
+  // and `.` as well as `_` (`Custom-Parts`, `MyCorp.RF`) — a nickname the regex
+  // truncates is probed as the wrong lib_id and reported absent, which is the
+  // false negative this whole fact block exists to prevent. Separators are
+  // interior only, so a trailing sentence period is not swallowed.
+  for (const m of text.matchAll(/\b([A-Za-z0-9_](?:[A-Za-z0-9_.-]*[A-Za-z0-9_])?):([A-Za-z0-9][A-Za-z0-9_.+-]*)/g)) {
+    const lib = m[1]!;
+    const name = m[2]!;
+    // Require letters on both sides: drops file:line refs ("create.ts:311"),
+    // times and bare numbers. Engine-generated power symbols are not library
+    // facts.
+    if (!/[A-Za-z]/.test(lib) || !/[A-Za-z]/.test(name) || lib === 'copperhead_power') continue;
+    const libId = `${lib}:${name}`;
+    if (!ids.includes(libId)) ids.push(libId);
+  }
+  if (!ids.length) return '';
+  // Collection is unbounded but probing is capped, so a probe-heavy transcript
+  // stays cheap. The overflow is named rather than dropped: the supervisor is
+  // told these facts are ground truth, and silently probing 8 of 30 lib_ids
+  // would let it read "unprobed" as "absent".
+  const probed = ids.slice(0, cap);
+  const unprobed = ids.slice(cap);
+  let searchDirs: string[];
+  try {
+    searchDirs = dirs ?? (await symbolSearchDirs());
+  } catch {
+    return '';
+  }
+  if (!searchDirs.length) return '';
+  // A directory with no readable library means nothing was checked: emitting
+  // "not installed" lines as ground truth from that state is the exact false
+  // absence this block exists to prevent (same guard as bomSymbolDossier).
+  if (!(await listInstalledLibraries(searchDirs)).size) return '';
+  const lines: string[] = [];
+  for (const libId of probed) {
+    const name = libId.slice(libId.indexOf(':') + 1);
+    try {
+      const r = await resolveLibrarySymbol(libId, searchDirs);
+      if (r.status === 'ok') {
+        lines.push(`- ${libId}: RESOLVES on this machine (${r.pins.length} pins)`);
+      } else if (r.status === 'found-elsewhere') {
+        // The resolver already located the part under another lib_id; saying
+        // "not installed" here would be the exact false absence claim this
+        // block exists to prevent.
+        lines.push(`- ${libId}: not at that lib_id, but installed as: ${r.libIds.slice(0, 4).join(', ')}`);
+      } else {
+        const elsewhere = await searchInstalledSymbols(name, searchDirs, 4);
+        const inThat =
+          r.status === 'no-symbol' && r.candidates.length
+            ? ` (closest in that library: ${r.candidates.slice(0, 4).join(', ')})`
+            : '';
+        const where = elsewhere.length
+          ? `; installed as: ${elsewhere.join(', ')}`
+          : `; no installed symbol matches "${name}" in any library`;
+        lines.push(
+          r.status === 'no-symbol'
+            ? `- ${libId}: not in that library${inThat}${where}`
+            : `- ${libId}: no library of that nickname is installed${where}`,
+        );
+      }
+    } catch {
+      // a single unreadable library must not sink the fact block
+    }
+  }
+  if (!lines.length) return '';
+  if (unprobed.length) {
+    lines.push(
+      `- NOT RE-PROBED (probe limit ${cap}): ${unprobed.join(', ')} — these were named in the text but not checked, so nothing above says whether they exist.`,
+    );
+  }
+  return lines.join('\n');
+}
+
 /**
  * Ask the model whether a failed/incomplete stage is worth retrying, and if so
  * how. Uses a fresh, tool-less provider turn (the same saved-login backend the
@@ -132,6 +294,9 @@ export async function diagnoseStageFailure(
     excerpt: string;
     attempt: number;
     maxAttempts: number;
+    /** Deterministic re-probe results for lib_ids named in the failure/excerpt
+     *  (`symbolAvailabilityFacts`); authoritative over the transcript's claims. */
+    symbolFacts?: string;
   },
 ): Promise<StageDiagnosis> {
   const system =
@@ -145,10 +310,15 @@ export async function diagnoseStageFailure(
     `Failure: ${input.failure}\n` +
     `This was attempt ${input.attempt} of ${input.maxAttempts}.\n\n` +
     `Recent transcript (most recent last):\n${input.excerpt}\n\n` +
+    (input.symbolFacts
+      ? `Machine-verified symbol facts — a deterministic re-probe of the lib_ids named above, run just now against this machine's installed KiCad libraries. Each line reported below is ground truth and overrides anything the transcript claims about that symbol's availability. Coverage may be partial: a lib_id listed as NOT RE-PROBED, or absent from this block entirely, is unknown, never confirmed absent.\n${input.symbolFacts}\n\n`
+      : '') +
     'Reply with ONLY a JSON object, no prose:\n' +
     '{"verdict":"retry"|"abort","reason":"<one sentence>","guidance":"<if retry: concrete, specific instructions to prepend to the next attempt so it avoids this failure; otherwise empty>"}\n' +
-    '- "retry" if the failure looks transient or fixable with clearer instructions (a dropped or locked tool call, an empty/no-op edit, a skipped step, a timeout, a formatting slip).\n' +
-    '- "abort" if repeating the same attempt will not help and a human should look (missing inputs, a genuine dead-end, or the same failure already seen on a prior attempt).';
+    '- "retry" if the failure looks transient or fixable with clearer instructions (a dropped or locked tool call, an empty/no-op edit, a skipped step, a hung provider call that timed out, a formatting slip).\n' +
+    '- a turn stopped at the hard time cap while still producing output (turnMaxMs, "too large, not hung") is NOT transient: repeating it hits the cap again. Retry only with guidance that splits that work into several smaller edits (e.g. one part or one sheet section per edit).\n' +
+    '- "abort" if repeating the same attempt will not help and a human should look (missing inputs, a genuine dead-end, or the same failure already seen on a prior attempt).\n' +
+    '- an agent\'s claim that a symbol or library is absent is NOT evidence: agents dead-ended by wrong library nicknames routinely conclude whole libraries are missing. If the machine-verified facts contradict the failure\'s premise (a cited-absent lib_id RESOLVES, or the part is installed under another library), the verdict is "retry", with guidance quoting the correct lib_ids.';
   const messages: Msg[] = [
     { role: 'system', content: system },
     { role: 'user', content: user },

package/src/agent/registry.ts

@@ -0,0 +1,58 @@
+import { catalog } from '../capabilities/index.js';
+import type { CatalogEntry, CatalogSkill } from '../capabilities/define.js';
+import type { RunContext } from './context.js';
+import { PROTOCOL_VERSION } from './envelope.js';
+
+export { PROTOCOL_VERSION };
+
+export class ToolRegistry {
+  private readonly byName = new Map<string, CatalogEntry>();
+
+  constructor(entries: CatalogEntry[]) {
+    for (const source of entries) {
+      const e: CatalogEntry = { ...source };
+      if (this.byName.has(e.name)) throw new Error(`duplicate catalog name "${e.name}"`);
+      this.byName.set(e.name, e);
+    }
+    for (const e of this.byName.values()) {
+      if (e.kind === 'skill' && !e.gateProvided) {
+        const conj = (ctx: RunContext) => this.conjunction(e.tools, ctx);
+        e.gate = conj;
+      }
+    }
+  }
+
+  get protocolVersion(): number {
+    return PROTOCOL_VERSION;
+  }
+
+  get(name: string): CatalogEntry | undefined {
+    return this.byName.get(name);
+  }
+
+  all(): CatalogEntry[] {
+    return [...this.byName.values()];
+  }
+
+  skills(): CatalogSkill[] {
+    return this.all().filter((e): e is CatalogSkill => e.kind === 'skill');
+  }
+
+  /** True when every named tool exists and its gate is open. */
+  conjunction(toolNames: string[], ctx: RunContext): boolean {
+    return toolNames.every((n) => {
+      const t = this.byName.get(n);
+      return t?.kind === 'tool' && t.gate(ctx);
+    });
+  }
+
+  /** Entries whose gate is open. Skills also require every declared tool's gate (D3). */
+  list(ctx: RunContext): CatalogEntry[] {
+    return this.all().filter((e) => {
+      if (e.kind === 'skill' && (e.tools.includes('finish') || !this.conjunction(e.tools, ctx))) return false;
+      return e.gate(ctx);
+    });
+  }
+}
+
+export const registry = new ToolRegistry(catalog);

package/src/agent/render.ts

@@ -9,12 +9,13 @@
  */
 
 import { copper, dim, setColorEnabled, styleOutcome, toolLine, warn } from './theme.js';
+import type { ViewHint } from './envelope.js';
 
 export interface ProgressRenderer {
   log(line: string): void;
   /** Called at the start of each turn with cumulative token totals so far. */
   turnStart(turn: number, maxTurns: number, tokensIn: number, tokensOut: number): void;
-  toolResult(name: string, firstLine: string): void;
+  toolResult(name: string, firstLine: string, ok?: boolean, viewHint?: ViewHint): void;
   /** Busy text while a provider call is in flight; null when idle. */
   status(text: string | null): void;
   /**
@@ -175,8 +176,8 @@ export class InteractiveRenderer implements ProgressRenderer {
     this.redraw();
   }
 
-  toolResult(name: string, firstLine: string): void {
-    this.log(toolLine(name, firstLine));
+  toolResult(name: string, firstLine: string, ok?: boolean, viewHint?: ViewHint): void {
+    this.log(toolLine(name, firstLine, ok, viewHint));
   }
 
   status(text: string | null): void {

package/src/agent/theme.ts

@@ -59,11 +59,21 @@ export function stageLine(name: string, detail: string, kind: 'info' | 'ok' | 'w
   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}`;
+/**
+ * Tool-result scrollback line: glyph from envelope `ok`, not a regex on prose.
+ * The envelope `viewHint` styles the name: mutations (they changed the repo)
+ * read copper, exports light copper, queries/diagnostics stay dim. Plain mode
+ * is unaffected: every painter no-ops while color is off.
+ */
+export function toolLine(
+  name: string,
+  firstLine: string,
+  succeeded = false,
+  viewHint?: 'diagnostic' | 'mutation' | 'query' | 'export',
+): string {
+  const glyph = succeeded ? ok('✓') : copper('▸');
+  const label = viewHint === 'mutation' ? copper(name) : viewHint === 'export' ? copperLight(name) : dim(name);
+  return `  ${glyph} ${label}  ${firstLine}`;
 }
 
 /** Color the final outcome line from its exit-path token. */