@davesheffer/hunch 0.1.0

package/dist/synthesis/provider.js

@@ -0,0 +1,488 @@
+/**
+ * Pluggable synthesis provider for the WRITE path (DESIGN.md §4 / §7).
+ *
+ * LLM synthesis is driven by the user's Claude **subscription** via the `claude`
+ * CLI — never the pay-per-token Anthropic API. We try, in order:
+ * claude-cli → deterministic-fallback. The fallback always works (no creds, no
+ * network) and emits a LOW-confidence draft, honoring the design rule that
+ * auto-captured memory is advisory and cheap to discard.
+ *
+ * Subscription, not API: Claude Code's auth precedence puts `ANTHROPIC_API_KEY`
+ * (and `ANTHROPIC_AUTH_TOKEN`) ABOVE subscription OAuth, and in headless `-p`
+ * mode the API key is *always* used when present. So we strip those vars from
+ * the child env (see ClaudeCliProvider.run) to force the CLI down to subscription
+ * OAuth / CLAUDE_CODE_OAUTH_TOKEN. There is intentionally NO API-key provider.
+ *
+ * Every provider returns the same shape so the rest of the system never knows
+ * (or cares) which one ran.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { tmpdir } from "node:os";
+import { summarizeDiff } from "../extractors/diff.js";
+const pexec = promisify(execFile);
+const SYSTEM = `You are the synthesis engine of an Engineering Memory OS. You turn raw
+developer activity (a git commit diff, or a test failure) into a single structured
+"why" record. Be precise and evidence-grounded; never invent facts not supported by
+the input. Prefer short, concrete statements. If intent is unclear, say so plainly
+rather than guessing.`;
+const DECISION_TOOL = {
+    name: "emit_decision",
+    description: "Emit the structured Decision (ADR) distilled from this commit.",
+    input_schema: {
+        type: "object",
+        properties: {
+            title: { type: "string", description: "Imperative, specific (<=80 chars)." },
+            context: { type: "string", description: "Why this change was needed." },
+            decision: { type: "string", description: "What was actually decided/changed." },
+            consequences: { type: "array", items: { type: "string" } },
+            alternatives_rejected: { type: "array", items: { type: "string" } },
+            nontrivial: { type: "boolean", description: "Is this a real design decision worth remembering?" },
+        },
+        required: ["title", "context", "decision", "consequences", "alternatives_rejected", "nontrivial"],
+    },
+};
+const BUG_TOOL = {
+    name: "emit_bug",
+    description: "Emit the structured Bug distilled from this test failure.",
+    input_schema: {
+        type: "object",
+        properties: {
+            title: { type: "string" },
+            symptom: { type: "string" },
+            root_cause: { type: "string", description: "Best hypothesis; mark uncertainty." },
+            severity: { type: "string", enum: ["low", "medium", "high", "critical"] },
+        },
+        required: ["title", "symptom", "root_cause", "severity"],
+    },
+};
+// --------------------------------------------------------------------------
+// Provider A: headless `claude -p` CLI — billed to the user's Claude subscription
+// --------------------------------------------------------------------------
+class ClaudeCliProvider {
+    name = "claude-cli";
+    // Default to the `haiku` alias (cheap/fast, and survives model retirements)
+    // rather than a pinned dated id; override with HUNCH_SYNTH_MODEL if needed.
+    model = process.env.HUNCH_SYNTH_MODEL || "haiku";
+    async available() {
+        try {
+            await pexec("claude", ["--version"], { timeout: 8000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async run(prompt) {
+        // Force SUBSCRIPTION auth: ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN outrank
+        // subscription OAuth in Claude Code's precedence and are *always* used in
+        // headless `-p` mode when present. Strip them so the CLI falls through to
+        // CLAUDE_CODE_OAUTH_TOKEN / `/login` subscription credentials. (We never
+        // bill the pay-per-token API — that's the whole point of this provider.)
+        const childEnv = { ...process.env };
+        delete childEnv.ANTHROPIC_API_KEY;
+        delete childEnv.ANTHROPIC_AUTH_TOKEN;
+        // Single-shot text synthesis: no tools, no agentic loop. The prompt carries
+        // all needed context inline, so run from a neutral cwd to avoid loading this
+        // repo's own hunch MCP server / CLAUDE.md on every commit (cheaper, and no
+        // risk of the synthesis call recursing through the Hunch). Auth lives in the
+        // user's home config, not cwd, so this doesn't affect subscription billing.
+        const args = ["-p", prompt, "--output-format", "json", "--model", this.model, "--max-turns", "1"];
+        const { stdout } = await pexec("claude", args, {
+            env: childEnv,
+            cwd: tmpdir(),
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: 120_000,
+        });
+        // Headless JSON envelope: { result, is_error, subtype, ... }. Keep the
+        // parse-failure fallback (non-JSON stdout → hand it to the mapper) SEPARATE
+        // from the error signal: an error envelope (max-turns/budget/exec error, which
+        // also OMITS `result`) must THROW so the safe wrapper falls back — not be
+        // returned as if it were assistant text. (The old single try/catch swallowed
+        // its own `throw`, making the is_error guard dead code.)
+        let envelope;
+        try {
+            envelope = JSON.parse(stdout);
+        }
+        catch {
+            return stdout; // not the JSON envelope — let the mapper attempt extraction
+        }
+        if (envelope.is_error || (envelope.subtype && envelope.subtype !== "success")) {
+            throw new Error(`claude -p reported an error${envelope.subtype ? `: ${envelope.subtype}` : ""}`);
+        }
+        return envelope.result ?? stdout;
+    }
+    async draftDecision(input) {
+        const text = await this.run(`${SYSTEM}\n\n${commitPrompt(input)}\n\n${jsonInstruction(DECISION_TOOL.input_schema)}`);
+        const draft = decisionDraftFromText(text, input.subject);
+        // No usable LLM JSON (truncation, refusal, prose-only) → THROW so the safe
+        // wrapper falls back to the deterministic provider, whose diff-structured
+        // draft is both more useful AND honestly labeled ("inferred", low confidence)
+        // than a hollow record mislabeled as an LLM draft.
+        if (!draft)
+            throw new Error("claude-cli: no usable decision JSON in output");
+        // For a LARGE diff the model only saw the structured summary + a sample, not
+        // the full patch (commitPrompt → renderDiff). The "why" is therefore lower-
+        // fidelity than a draft made from the whole diff, so haircut the confidence
+        // and tag the source — keeping provenance honest (a summary-sourced draft must
+        // not masquerade as a full-fidelity llm_draft at 0.65).
+        if (input.diff.length > LARGE_DIFF_CHARS) {
+            return { ...draft, confidence: Math.min(draft.confidence, 0.5), source: `${draft.source}+summary` };
+        }
+        return draft;
+    }
+    async draftBug(input) {
+        const text = await this.run(`${SYSTEM}\n\n${failurePrompt(input)}\n\n${jsonInstruction(BUG_TOOL.input_schema)}`);
+        const draft = bugDraftFromText(text, input.test, input.message);
+        if (!draft)
+            throw new Error("claude-cli: no usable bug JSON in output");
+        return draft;
+    }
+}
+// --------------------------------------------------------------------------
+// Provider C: deterministic fallback (no LLM, always available)
+// --------------------------------------------------------------------------
+export class DeterministicProvider {
+    name = "deterministic";
+    async available() {
+        return true;
+    }
+    async draftDecision(input) {
+        const dirs = topDirs(input.files);
+        const a = input.analysis;
+        const summary = a ? summarizeDiff(a) : "";
+        const verb = /^(add|introduce|create|feat)/i.test(input.subject) ? "introduced"
+            : /^(remove|delete|drop)/i.test(input.subject) ? "removed"
+                : /^(refactor|rework|restructure)/i.test(input.subject) ? "refactored"
+                    : "changed";
+        const consequences = [];
+        if (a?.addedDeps.length)
+            consequences.push(`Adds dependency: ${a.addedDeps.join(", ")}.`);
+        if (a?.removedDeps.length)
+            consequences.push(`Drops dependency: ${a.removedDeps.join(", ")}.`);
+        if (a?.removedSymbols.length)
+            consequences.push(`Removes ${a.removedSymbols.map((s) => s.name).join(", ")} — potential breaking change for callers.`);
+        if (a?.changedSymbols.length)
+            consequences.push(`Changes ${a.changedSymbols.map((s) => s.name).join(", ")} (signature/behavior).`);
+        // We extracted real structure → a bit more trustworthy than a blind heuristic.
+        const informative = !!(a && (a.addedSymbols.length || a.removedSymbols.length || a.changedSymbols.length || a.addedDeps.length || a.removedDeps.length));
+        return {
+            title: input.subject || "Code change",
+            context: [input.body, summary && `What changed: ${summary}.`].filter(Boolean).join(" ").slice(0, 500)
+                || `Touched ${input.files.length} file(s) across ${dirs.join(", ") || "the repo"}.`,
+            decision: summary
+                ? `${cap(verb)} ${dirs.join(", ") || "the repo"}: ${summary}.`
+                : `${cap(verb)} code in ${dirs.join(", ") || "the repo"} (${input.files.length} file(s)).`,
+            consequences,
+            alternatives_rejected: [],
+            // advisory either way, but real extraction earns a touch more confidence
+            confidence: informative ? 0.45 : 0.3,
+            source: "inferred",
+        };
+    }
+    async draftBug(input) {
+        return {
+            title: `Test failure: ${input.test}`,
+            symptom: input.message.slice(0, 300),
+            root_cause: input.suspects.length ? `Suspected in: ${input.suspects.join(", ")}` : "Unknown (no LLM available).",
+            severity: "medium",
+            confidence: 0.25,
+            source: "test_failure",
+        };
+    }
+}
+const PROVIDERS = [new ClaudeCliProvider(), new DeterministicProvider()];
+/** Choose the first available provider, honoring HUNCH_SYNTH_PROVIDER override. */
+export async function selectProvider() {
+    const forced = process.env.HUNCH_SYNTH_PROVIDER;
+    if (forced) {
+        const p = PROVIDERS.find((x) => x.name === forced);
+        if (p && (await p.available()))
+            return p;
+    }
+    for (const p of PROVIDERS) {
+        try {
+            if (await p.available())
+                return p;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return new DeterministicProvider();
+}
+// ---- prompt + parsing helpers --------------------------------------------
+// Above this size we stop shipping the raw patch and lean on the deterministic
+// STRUCTURED CHANGES summary + a small sample. A truncated head-slice of a giant
+// diff is an arbitrary fragment; the summary describes the WHOLE change for far
+// fewer tokens. (Draft confidence is haircut when this path is taken — see
+// ClaudeCliProvider.draftDecision.)
+const LARGE_DIFF_CHARS = 20_000;
+const DIFF_SAMPLE_CHARS = 6_000;
+/** The DIFF section of the commit prompt: the full patch for normal commits, or
+ *  (for a large diff) a small sample with a pointer to STRUCTURED CHANGES. */
+function renderDiff(input) {
+    if (input.diff.length <= LARGE_DIFF_CHARS)
+        return `DIFF:\n${input.diff}`;
+    return `DIFF (large patch — first ${DIFF_SAMPLE_CHARS} of ${input.diff.length} chars; rely on STRUCTURED CHANGES above for the rest):\n${input.diff.slice(0, DIFF_SAMPLE_CHARS)}`;
+}
+function commitPrompt(input) {
+    return [
+        `COMMIT SUBJECT: ${input.subject}`,
+        input.body ? `COMMIT BODY:\n${input.body}` : "",
+        input.analysis ? `STRUCTURED CHANGES: ${summarizeDiff(input.analysis)}` : "",
+        `FILES CHANGED (${input.files.length}):\n${input.files.slice(0, 40).join("\n")}`,
+        renderDiff(input),
+        `\nDistill the single most important design decision this commit represents.`,
+    ].filter(Boolean).join("\n\n");
+}
+function failurePrompt(input) {
+    return [
+        `FAILING TEST: ${input.test}`,
+        `FAILURE MESSAGE:\n${input.message.slice(0, 2000)}`,
+        input.suspects.length ? `SUSPECT SYMBOLS (ranked by churn×recency×fan-in):\n${input.suspects.join("\n")}` : "",
+        input.recentDiff ? `RECENT DIFF:\n${input.recentDiff.slice(0, 8000)}` : "",
+        `\nDraft a Bug record: symptom, best-hypothesis root cause (mark uncertainty), severity.`,
+    ].filter(Boolean).join("\n\n");
+}
+function jsonInstruction(schema) {
+    return `Respond with ONLY a single JSON object matching this schema (no prose, no code fence):\n${JSON.stringify(schema)}`;
+}
+/** Index of the `}` that closes the balanced object opened at `start`, or -1.
+ *  String-aware: braces and quotes INSIDE a JSON string literal don't count, so
+ *  `{"context":"closes the } brace"}` balances whole (a naive depth counter
+ *  closes early on the inner `}`). */
+function balancedEnd(text, start) {
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (ch === "\\")
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"')
+            inStr = true;
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}" && --depth === 0)
+            return i;
+    }
+    return -1; // never balanced (e.g. truncated output)
+}
+/** True if the `{` at `start` begins something that looks like a JSON object —
+ *  the next non-space char is a `"` (a quoted key) or `}` (empty object). Lets us
+ *  tell a real, possibly-truncated JSON object from a stray PROSE brace such as
+ *  `interface Foo {`, `() => {`, or `{set}` (whose next char is a letter). */
+function looksLikeJsonObject(text, start) {
+    let j = start + 1;
+    while (j < text.length && /\s/.test(text[j]))
+        j++;
+    return j < text.length && (text[j] === '"' || text[j] === "}");
+}
+/** Every balanced top-level `{...}` slice in `text`, in order. A brace that does
+ *  NOT look like a JSON opener (a prose brace) is SKIPPED and the scan continues,
+ *  so junk before the answer never hides the object that follows. But a brace that
+ *  looks like JSON yet never closes is a TRUNCATED object — we stop there rather
+ *  than descend into it, which would surface a nested child as a fake top-level
+ *  answer (`{"decision":"REAL","meta":{...}` must not leak the inner `meta`). */
+function topLevelJsonSlices(text) {
+    const slices = [];
+    let i = 0;
+    for (;;) {
+        const start = text.indexOf("{", i);
+        if (start < 0)
+            break;
+        if (!looksLikeJsonObject(text, start)) {
+            i = start + 1; // prose brace (`interface Foo {`, `{set}`) — skip, keep scanning
+            continue;
+        }
+        const end = balancedEnd(text, start);
+        if (end < 0)
+            break; // a JSON-looking object that never closes → truncated tail
+        slices.push(text.slice(start, end + 1));
+        i = end + 1;
+    }
+    return slices;
+}
+/** Strip trailing commas (`,}` / `,]`) WITHOUT touching string contents — the
+ *  single most common reason a model's near-valid JSON fails strict parse. A
+ *  blanket regex would also eat a comma that legitimately lives inside a string
+ *  value (e.g. "see {a, b, }"), silently corrupting the captured text, so this
+ *  reuses the same in-string/escape state machine as the slicer. */
+function stripTrailingCommas(s) {
+    let out = "";
+    let inStr = false;
+    let esc = false;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (inStr) {
+            out += ch;
+            if (esc)
+                esc = false;
+            else if (ch === "\\")
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"') {
+            inStr = true;
+            out += ch;
+            continue;
+        }
+        if (ch === ",") {
+            let k = i + 1;
+            while (k < s.length && /\s/.test(s[k]))
+                k++;
+            if (k < s.length && (s[k] === "}" || s[k] === "]"))
+                continue; // drop the comma
+        }
+        out += ch;
+    }
+    return out;
+}
+function tryParseObject(s) {
+    try {
+        const v = JSON.parse(s);
+        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Strict JSON first, then one string-aware lenient pass (trailing commas). */
+function parseObjectLoose(slice) {
+    return tryParseObject(slice) ?? tryParseObject(stripTrailingCommas(slice));
+}
+/** Every parseable top-level JSON object in arbitrary model text, in order. */
+export function extractJsonObjects(text) {
+    return topLevelJsonSlices(text)
+        .map(parseObjectLoose)
+        .filter((o) => o !== null);
+}
+/** Convenience: the FIRST parseable top-level object, or null. (The mappers below
+ *  do their own content-based selection; this is just a generic accessor.) */
+export function extractJson(text) {
+    return extractJsonObjects(text)[0] ?? null;
+}
+const SEVERITIES = ["low", "medium", "high", "critical"];
+const SEV_RANK = { low: 1, medium: 2, high: 3, critical: 4 };
+function asSeverity(v) {
+    return typeof v === "string" && SEVERITIES.includes(v) ? v : null;
+}
+/** Values a model emits as a fill-in TEMPLATE rather than a real answer. We can't
+ *  use position (a template/recap may lead OR trail the answer), so we recognize
+ *  placeholder-shaped values and treat the field as empty. Kept deliberately narrow
+ *  so a terse REAL answer isn't mistaken for a template: an angle-bracket value only
+ *  counts if it's a short metavariable (≤2 words, e.g. `<what>`, `<best hypothesis>`)
+ *  — not a bracketed sentence — and the word list holds only unambiguous markers. */
+function isPlaceholder(s) {
+    const t = s.trim();
+    if (!t)
+        return true;
+    if (/^\.{2,}$/.test(t))
+        return true; // "..", "..."
+    const meta = /^<(.+)>$/.exec(t);
+    if (meta && meta[1].trim().split(/\s+/).length <= 2)
+        return true; // <what>, <best hypothesis>
+    return ["see above", "recap", "placeholder"].includes(t.toLowerCase());
+}
+/** A string field, blanked when empty OR a template placeholder. */
+function realStr(v) {
+    const s = str(v, "");
+    return s && !isPlaceholder(s) ? s : "";
+}
+/** Map model text → DecisionDraft, or null when there's nothing usable to keep.
+ *  Null (not a hollow draft) is the signal for the caller to fall back to the
+ *  deterministic provider — we only claim "llm_draft" when the LLM actually
+ *  produced substance. The model is asked for ONE object; if it emits several (a
+ *  template/example plus the answer), take the FIRST with real (non-placeholder)
+ *  substance — robust whether the junk leads or trails the answer. */
+export function decisionDraftFromText(text, fallbackTitle) {
+    const candidates = [];
+    for (const obj of extractJsonObjects(text)) {
+        const decision = realStr(obj.decision);
+        const context = realStr(obj.context);
+        if (!decision && !context)
+            continue; // template / placeholder / unrelated object
+        // Coerce explicitly: a model may emit the boolean as the string "false",
+        // which is JS-truthy — keying confidence off raw truthiness would invert it.
+        const nontrivial = obj.nontrivial === true || obj.nontrivial === "true";
+        candidates.push({ obj, decision, context, nontrivial });
+    }
+    if (!candidates.length)
+        return null;
+    // Prefer the object the model FLAGGED as a real decision over a generic worked
+    // example that may precede it; else the first substantive object.
+    const pick = candidates.find((c) => c.nontrivial) ?? candidates[0];
+    return {
+        title: realStr(pick.obj.title) || fallbackTitle,
+        context: pick.context,
+        decision: pick.decision,
+        consequences: asStrArr(pick.obj.consequences),
+        alternatives_rejected: asStrArr(pick.obj.alternatives_rejected),
+        confidence: pick.nontrivial ? 0.65 : 0.4,
+        source: "llm_draft",
+    };
+}
+/** Map model text → BugDraft, or null. A root_cause is the LLM's full value-add;
+ *  a deliberate non-"medium" severity is worth keeping on its own (it carries the
+ *  LLM's classification into the bug record rather than the deterministic "medium").
+ *  Pick the BEST candidate object — most substantiated (root-caused) then most
+ *  severe — NOT the positionally first/last, so a trailing low-severity recap can't
+ *  downgrade a real critical finding. Without a root_cause the draft is labeled
+ *  honestly as partial at lower confidence; constraint promotion is gated on a real
+ *  root_cause downstream (see shouldPromoteConstraint), so a bare severity label
+ *  preserves its signal in the record without auto-minting an invariant. */
+export function bugDraftFromText(text, fallbackTitle, fallbackSymptom) {
+    let best = null;
+    let bestScore = -1;
+    for (const obj of extractJsonObjects(text)) {
+        const root_cause = realStr(obj.root_cause);
+        const severity = asSeverity(obj.severity);
+        const deliberate = severity !== null && severity !== "medium";
+        if (!root_cause && !deliberate)
+            continue; // only echoes the input → not a candidate
+        const score = (root_cause ? 100 : 0) + (severity ? SEV_RANK[severity] : 0);
+        if (score > bestScore) {
+            bestScore = score;
+            best = { obj, root_cause, severity };
+        }
+    }
+    if (!best)
+        return null;
+    const full = !!best.root_cause;
+    return {
+        title: realStr(best.obj.title) || fallbackTitle,
+        symptom: realStr(best.obj.symptom) || fallbackSymptom,
+        root_cause: best.root_cause,
+        severity: best.severity ?? "medium",
+        confidence: full ? 0.55 : 0.4,
+        source: full ? "test_failure+llm" : "test_failure+llm_partial",
+    };
+}
+function asStrArr(v) {
+    return Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : [];
+}
+function str(v, fallback) {
+    return typeof v === "string" && v.trim() ? v : fallback;
+}
+function topDirs(files) {
+    const set = new Set();
+    for (const f of files) {
+        const parts = f.split("/");
+        set.add(parts.length > 1 ? parts.slice(0, 2).join("/") : parts[0] ?? f);
+    }
+    return [...set].slice(0, 6);
+}
+function cap(s) {
+    return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+//# sourceMappingURL=provider.js.map