Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

13.9 KB
Raw Blame
/**
 * The repair detector (design 4.12, research v3): a call that failed on a
 * known wall, and the retry of the same command within 10 calls that worked
 * because of what changed around it. The change (the fix delta) is an env
 * variable set, a flag added, a wrapper from a fixed list put in front, or a
 * step of another program that ran between them (`colima start`).
 *
 * Some failures never count (`ignoredFailure`): a hook or host deny, a CI
 * log read (the log is a failure), SQL and GraphQL query errors (data, not
 * tooling), a flake, a chain whose failing tail was dropped, and look-only
 * calls.
 *
 * A delta's text can become a lesson the agent reads as "what fixed it", and
 * an agent chooses the retry, so every delta passes the rules a skill step
 * passes (R26): no secret, nothing on the never-save list, nothing gated.
 * Any delta that fails them drops the whole repair.
 *
 * Pure: reads only the run's calls (commands already secret-checked by the
 * fold). Never throws.
 */
import { homedir } from 'node:os';
import { secretReason } from '../notes/secrets.js';
import { gatedKind } from '../skills/risk.js';
import { neverSave } from '../skills/never-save.js';
import { OWN_FILES, RISKY_STEP, riskyDelta } from '../skills/risk-delta.js';
import { callText } from './checks.js';
import { commandKind, leadingCds, normalizeCommand, relativizePaths, splitTop, stripLeadingSleep, stripOutputFilters, stripTrailingEcho } from './shell.js';
import { afterTimeout, programOfText } from './shell-words.js';
import { ASSIGN, base, unquote, words } from './shell-scan.js';
import type { FixDelta, RepairEvent, RunCall, RunState } from './types.js';

/** Where relativized delta text points: `$HOME` for home, `./` for the repo root (4.12 step 5). */
export interface RepairOpts { home?: string; root?: string }

/** The retry is one of the next 10 calls (4.12 step 3). */
const WINDOW = 10;
/** At most 5 repairs a run (RunState.repairs). */
const MAX_REPAIRS = 5;

/* ------------------------------------------------------------ ignored rows */

/** A hook or the host refused the call; Trail's own sure-fail deny is one. errorLine is flatLine'd, so `[trail]` may be gone. */
const DENIED: readonly RegExp[] = [
  /^\w+:\w+ hook (?:error|returned blocking error)/,
  /^(?:\[trail\]\s*)?Trail, the tool this person installed, stopped this command\b/,
  /^trail(?::| ·) /, // Trail's gated-step deny and the save gate's refusals (b2 review)
  /^Permission (?:for this (?:action|command)|to use \S+(?: with command .*?)?) (?:was|has been) denied/,
  /^The user doesn't want to proceed with this tool use/,
  /^<tool_use_error>/,
];
/** Bounded between `view` and `--log`, so a long run of `gh run view` words can't make it quadratic (b2 review). */
const CI_LOG = /\bgh\s+run\s+view\b[^;&|\n]{0,400}?\s--log(?:-failed)?(?=\s|$|[;&|)])/;
/** A query client (also through `docker exec`), or GraphQL through gh. */
const QUERY_CLIENT = /(?:^|[\s;&|(/])(?:psql|mysql|mariadb|sqlite3|duckdb|clickhouse(?:-client)?|snowsql|cqlsh|mongosh)(?=\s|$)|\bbq\s+query\b|\bcockroach\s+sql\b|\bgh\s+api\s+graphql\b/;
/** What a query error says first: Postgres, MySQL, SQLite, GraphQL. */
const QUERY_ERROR = /^(?:ERROR|error):\s+(?:syntax error|relation|column|function|operator|permission denied for|duplicate key|invalid input syntax|null value)\b|^ERROR \d{4} \(\w+\)|^(?:Parse|Runtime) error near\b|^Error: (?:near|no such (?:table|column))\b|^GraphQL(?:Error)?:|\bdoesn't exist on type\b|"errors":\s*\[/i;

const collapse = (s: string) => s.trim().replace(/\s+/g, ' ');

/** How far a dropped tail is looked for: the retry's own length plus this, and at most this many pieces (linear, b2 review). */
const TAIL_SLACK = 2048;
const TAIL_PIECES = 64;

/** `A && B` failed and `A` alone then passed: the failure was the dropped tail's (4.12 step 1). */
function droppedTail(cmd: string, next: string): boolean {
  const want = normalizeCommand(next);
  const segs = splitTop(cmd);
  let head = '';
  for (let k = 0; k < segs.length - 1 && k < TAIL_PIECES; k++) {
    const seg = segs[k]!;
    if (seg.sep !== '&&' && seg.sep !== ';') return false;
    head = head ? `${head} ${seg.text}` : seg.text;
    if (head.length > next.length + TAIL_SLACK) return false;
    if (normalizeCommand(head) === want) return true;
    head = `${head} ${seg.sep}`;
  }
  return false;
}

/**
 * A failure that never counts as a wall or a repair (4.12 step 1). `next` is the call right after it (or the
 * retry), for the two rows about what followed: an identical retry that passed (a flake), and the same chain
 * with its failing `&&` tail dropped. The other rows read the call alone, and also hold for an exit-0 call: a
 * CI log read or a query is never a wall, failed or not.
 */
export function ignoredFailure(call: RunCall, next: RunCall | null): boolean {
  try {
    if (call.kind === 'look' || call.kind === 'plumbing') return true;
    const cmd = callText(call);
    if (CI_LOG.test(cmd) || QUERY_CLIENT.test(cmd)) return true;
    const line = typeof call.errorLine === 'string' ? call.errorLine : '';
    if (DENIED.some((re) => re.test(line)) || QUERY_ERROR.test(line)) return true;
    if (!call.failed || !next || next.failed || typeof next.cmd !== 'string') return false;
    return collapse(cmd) === collapse(next.cmd) || droppedTail(cmd, next.cmd);
  } catch {
    return true;
  }
}

/* -------------------------------------------------------------- the core */

interface Part { name: string; text: string }
/** A command with its leading cds, sleeps, output filters and trailing echo gone, then its env and wrappers taken off. */
interface Core { env: Part[]; wrappers: Part[]; words: string[]; text: string }

const PLACEHOLDER = /\$\{[A-Za-z_]\w*:\?set /;
/** Wrappers that only change how the same command runs; any of these added in a retry drops the repair unless it is on ALLOWED. */
const WRAPPERS = new Set(['sudo', 'doas', 'nice', 'nohup', 'time', 'exec', 'command', 'caffeinate', 'stdbuf', 'ionice', 'chrt']);
const TWO_WORD_FLAG = /^-[nuCgDhprtUTwc]$/;

function strip(cmd: string): string {
  let s = String(cmd ?? '').trim();
  for (let n = 0; n < 20; n++) {
    const next = stripLeadingSleep(leadingCds(stripTrailingEcho(stripOutputFilters(s))).rest);
    if (next === s) break;
    s = next;
  }
  return s;
}

function envPart(word: string): Part | null {
  const w = unquote(word);
  return ASSIGN.test(w) ? { name: w.slice(0, w.indexOf('=')), text: w } : null;
}

function coreOf(cmd: string): Core | null {
  const s = strip(cmd);
  let w = words(s);
  const env: Part[] = [];
  const wrappers: Part[] = [];
  for (let n = 0; n < 24 && w.length; n++) {
    while (w.length && ASSIGN.test(w[0]!)) env.push(envPart(w.shift()!)!);
    const p = w[0] ?? '';
    if (p === 'env') {
      let i = 1;
      for (; i < w.length; i++) {
        const e = envPart(w[i]!);
        if (e) env.push(e);
        else if (/^(?:-u|--unset|-C|--chdir|-S|--split-string)$/.test(w[i]!)) i++;
        else if (!w[i]!.startsWith('-')) break;
      }
      w = w.slice(i);
    } else if (p === 'noglob') {
      wrappers.push({ name: p, text: p });
      w = w.slice(1);
    } else if (p === 'timeout' || p === 'gtimeout') {
      const rest = afterTimeout(w);
      if (!rest) break;
      wrappers.push({ name: p, text: w.slice(0, w.length - rest.length).join(' ') });
      w = rest;
    } else if (p === 'colima' && w[1] === 'ssh' && w[2] === '--') {
      wrappers.push({ name: 'colima ssh --', text: 'colima ssh --' });
      w = w.slice(3);
    } else if (WRAPPERS.has(base(p)) && !(p === 'command' && /^-[vV]$/.test(w[1] ?? ''))) {
      let i = 1;
      while (i < w.length && w[i]!.startsWith('-')) i += TWO_WORD_FLAG.test(w[i]!) ? 2 : 1;
      wrappers.push({ name: base(p), text: w.slice(0, i).join(' ') });
      w = w.slice(i);
    } else break;
  }
  if (!w.length) return null;
  return { env, wrappers, words: w.map(unquote), text: w.join(' ') };
}

const isFlag = (w: string) => w.length > 1 && w.startsWith('-') && w !== '--';

/** The flags the retry added, when the retry is the failed command once they, its env and its wrappers are off; else null. */
function addedFlags(failed: Core, retry: Core): string[] | null {
  const had = new Set(failed.words);
  const added = retry.words.filter((w) => isFlag(w) && !had.has(w));
  const rest = retry.words.filter((w) => !(isFlag(w) && !had.has(w)));
  if (rest.length !== failed.words.length || rest.some((w, i) => w !== failed.words[i])) return null;
  return added;
}

const programOf = (c: Core) => programOfText(c.text).prog ?? base(c.words[0] ?? '');

/** A wrapper a retry may add: noglob, `colima ssh --`, and gtimeout where timeout failed (4.12 step 4). */
function allowedWrapper(name: string, failed: Core): boolean {
  if (name === 'noglob' || name === 'colima ssh --') return true;
  return name === 'gtimeout' && failed.wrappers.some((w) => w.name === 'timeout');
}

/** No secret, nothing never-save, nothing gated (4.12 steps 5, 6; R26). */
const safe = (text: string) => secretReason(text) === null && !PLACEHOLDER.test(text) && neverSave(text) === null && gatedKind(text) === null;

/** A call with a whole command whose outcome is known: a result in the transcript, or a PostToolUse mark (an open call reads as not failed); a background call's result says only that it started. */
const usable = (c: RunCall) => typeof c.cmd === 'string' && !c.truncated && c.bg !== true && (c.src?.result != null || c.fromMark === true);

/**
 * The delta between a failing call and its retry (4.12 step 4), with the enabling calls between them: enabling
 * steps first (in the order they ran), then wrappers, env and flags. [] when there is none, when `retry` is not
 * a passing retry of the same command, or when any part fails the secret or risk rules: [] means no repair.
 */
export function fixDelta(failed: RunCall, retry: RunCall, between: RunCall[], opts: RepairOpts = {}): FixDelta[] {
  try {
    if (!usable(failed) || !usable(retry) || retry.failed) return [];
    // An edit, or a call that changed files, between them may be the fix: the delta alone isn't (b2 review).
    if ((retry.editsBefore ?? 0) !== (failed.editsBefore ?? 0)) return [];
    if ((Array.isArray(between) ? between : []).some((c) => c.kind === 'work')) return [];
    const f = coreOf(failed.cmd!);
    const r = coreOf(retry.cmd!);
    if (!f || !r) return [];
    const flags = addedFlags(f, r);
    if (!flags) return [];
    const home = opts.home ?? homedir();
    const root = opts.root ?? '';
    const rel = (t: string) => relativizePaths(t, root, home);
    const out: FixDelta[] = [];
    const prog = programOf(f);
    for (const c of Array.isArray(between) ? between : []) {
      if (c.failed || !usable(c) || c.kind !== 'step' || commandKind(c.cmd!) !== 'step') continue;
      const core = coreOf(c.cmd!);
      if (!core || programOf(core) === prog) continue;
      out.push({ kind: 'enable-step', name: programOf(core), text: rel(strip(c.cmd!)), callId: c.id });
    }
    const hadWrap = new Set(f.wrappers.map((w) => w.name));
    for (const w of r.wrappers) {
      if (hadWrap.has(w.name)) continue;
      if (!allowedWrapper(w.name, f)) return [];
      out.push({ kind: 'wrapper', name: w.name, text: w.text, callId: retry.id });
    }
    const hadEnv = new Set(f.env.map((e) => e.name));
    for (const e of r.env) if (!hadEnv.has(e.name)) out.push({ kind: 'env', name: e.name, text: rel(e.text), callId: retry.id });
    for (const flag of flags) out.push({ kind: 'flag', name: flag.split('=')[0]!, text: rel(flag), callId: retry.id });
    if (!out.length) return [];
    // The retry as it ran (its cds, filters and echo included) and each delta's own text. The step rules read it
    // relativized, as the deltas are: a path inside a checkout that sits in /tmp (Linux CI, a scratch clone) is `./`.
    const whole = rel(retry.cmd!);
    if (!safe(retry.cmd!) || RISKY_STEP.test(whole) || OWN_FILES.test(whole) || out.some((d) => !safe(d.text) || riskyDelta(d))) return [];
    return out;
  } catch {
    return [];
  }
}

/**
 * A wall hit that failed: the call failed, or its wall's words came out of a top-level pipe (`go test 2>&1 | tail`),
 * whose exit code is the filter's, so 0 says nothing (fix-lab5). matchWall already drops planted and log-read text.
 */
function wallFailed(c: RunCall): boolean {
  if (c.failed) return true;
  return !!c.wall && typeof c.cmd === 'string' && splitTop(c.cmd).some((s) => s.sep === '|');
}

/**
 * Every failed call with a `wall` in the run that a later call (within 10) of the same command fixed with a
 * delta (4.12). One repair per retry, the earliest failure's; at most 5, oldest first.
 */
export function detectRepairs(run: RunState, opts: RepairOpts = {}): RepairEvent[] {
  const out: RepairEvent[] = [];
  try {
    const calls = Array.isArray(run?.calls) ? run.calls : [];
    const used = new Set<string>();
    for (let i = 0; i < calls.length && out.length < MAX_REPAIRS; i++) {
      const f = calls[i]!;
      if (!f.wall || !wallFailed(f) || !usable(f) || ignoredFailure(f, calls[i + 1] ?? null)) continue;
      const fc = coreOf(f.cmd!);
      if (!fc) continue;
      for (let j = i + 1; j <= i + WINDOW && j < calls.length; j++) {
        const r = calls[j]!;
        if (r.failed || r.wall || !usable(r) || used.has(r.id)) continue;
        const rc = coreOf(r.cmd!);
        if (!rc || !addedFlags(fc, rc)) continue;
        const delta = fixDelta(f, r, calls.slice(i + 1, j), opts);
        if (delta.length) {
          used.add(r.id);
          out.push({ cls: f.wall, program: programOf(fc), failCallId: f.id, fixCallId: r.id, delta, epoch: run.epoch, runId: run.id ?? null, at: r.at });
        }
        break;
      }
    }
  } catch {
    /* fail open: what was found so far */
  }
  return out;
}

/** At run close (runs.ts): `run.repairs` from its calls, while it still has them; left alone once they are emptied. */
export function noteRepairs(run: RunState, opts: RepairOpts = {}): void {
  if (!Array.isArray(run?.calls) || !run.calls.length) return;
  const found = detectRepairs(run, opts);
  if (found.length) run.repairs = found;
  else delete run.repairs;
}