@yagni-app/code-staging 0.0.0 → 0.1.0-staging.997.1

package/dist/extension/repoDocs.js

@@ -0,0 +1,260 @@
+/**
+ * Repo-doc grounding collector for ask_yagni (the retrieval coverage fix from
+ * the 2026-07 grounding-gate eval): coding agents ask codebase/architecture
+ * questions — ADRs, schema, conventions — that the workspace corpus (Vision,
+ * Library, decisions, corrections) structurally cannot answer, because that
+ * knowledge lives in the repo. This module gathers the few most relevant repo
+ * docs from the CALLER'S working tree so the backend can fold them into the
+ * numbered source catalog.
+ *
+ * Reading from the checkout (not a server-side index) is load-bearing: the docs
+ * are always exactly as old as the checkout being edited, so an agent working
+ * on an old base sees that era's conventions, never today's.
+ *
+ * BASELINE, not working tree (echo-chamber guard): docs are enumerated and read
+ * at git HEAD, never from the live working tree. A /go run edits the tree
+ * without committing until FINISH, so mid-run ask_yagni calls from the review
+ * and fix stages would otherwise retrieve the candidate's OWN in-flight edits
+ * to a doc and have the backend present that self-authored text as
+ * source-of-truth context. HEAD is the pre-run baseline in both the /go
+ * pipeline and the eval driver (which commits the exported tree before the
+ * agent starts). A non-git directory falls back to the working-tree walk —
+ * there is no baseline to prefer.
+ *
+ * Pure-ish and bounded: a small fixed set of root docs plus a capped doc list,
+ * lexical scoring against the question (no model call, no network), hard caps
+ * on file count, bytes read, and excerpt size. All fs/git access sits behind
+ * injectable seams so tests never touch a real repo.
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Root-level docs worth checking by name in any repo. */
+const ROOT_DOC_NAMES = [
+    "CONTEXT.md",
+    "AGENTS.md",
+    "README.md",
+    "ARCHITECTURE.md",
+    "GLOSSARY.md",
+    "CONTRIBUTING.md",
+];
+/** Directories under docs/ never worth descending into. */
+const SKIP_DIR_RE = /^(node_modules|\.[^/]*|dist|build|out)$/;
+/** Tokens too generic to signal relevance on their own. */
+const STOPWORDS = new Set([
+    "the", "and", "for", "with", "this", "that", "what", "how", "does", "are",
+    "was", "were", "have", "has", "had", "not", "but", "can", "should", "would",
+    "our", "its", "any", "all", "one", "two", "use", "used", "using", "when",
+    "where", "which", "who", "why", "there", "here", "into", "from", "about",
+    "file", "files", "code", "codebase", "repo", "repository",
+]);
+/** Lowercased, deduped, stopword-free query tokens (length >= 3). */
+export function tokenizeQuery(query) {
+    const tokens = new Set();
+    for (const raw of query.toLowerCase().split(/[^a-z0-9_-]+/)) {
+        const t = raw.replace(/^[-_]+|[-_]+$/g, "");
+        if (t.length >= 3 && !STOPWORDS.has(t))
+            tokens.add(t);
+    }
+    return [...tokens];
+}
+const defaultFs = {
+    readFileSync: (p) => fs.readFileSync(p, "utf8"),
+    readdirSync: (p) => fs.readdirSync(p, { withFileTypes: true }),
+    statSize: (p) => fs.statSync(p).size,
+};
+const GIT_OPTS = {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"],
+};
+const defaultGit = {
+    listDocsAtHead: (cwd) => {
+        try {
+            const out = execFileSync("git", ["ls-tree", "-r", "--name-only", "HEAD"], { cwd, ...GIT_OPTS });
+            return out.split("\n").filter(Boolean);
+        }
+        catch {
+            return null;
+        }
+    },
+    readAtHead: (cwd, rel) => {
+        try {
+            return execFileSync("git", ["show", `HEAD:${rel}`], { cwd, ...GIT_OPTS });
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/** Is this HEAD-tracked path a doc we consider? (root doc names + docs/**.md) */
+function isDocCandidate(rel) {
+    if (ROOT_DOC_NAMES.includes(rel))
+        return true;
+    return /^docs\//.test(rel) && /\.(md|markdown)$/i.test(rel);
+}
+/** Enumerate candidate doc paths: fixed root names + a bounded docs/ walk. */
+function candidatePaths(cwd, maxFiles, fsImpl) {
+    const found = [];
+    for (const name of ROOT_DOC_NAMES) {
+        try {
+            if (fsImpl.statSize(path.join(cwd, name)) >= 0)
+                found.push(name);
+        }
+        catch {
+            /* absent */
+        }
+    }
+    // Breadth-first bounded walk of docs/ so shallow (usually more general) docs
+    // win the scan cap over deeply nested ones.
+    const queue = ["docs"];
+    let scanned = 0;
+    while (queue.length > 0 && scanned < maxFiles) {
+        const rel = queue.shift();
+        let entries;
+        try {
+            entries = fsImpl.readdirSync(path.join(cwd, rel));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (scanned >= maxFiles)
+                break;
+            const relPath = path.join(rel, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIR_RE.test(entry.name))
+                    queue.push(relPath);
+                continue;
+            }
+            if (entry.isFile() && /\.(md|markdown)$/i.test(entry.name)) {
+                scanned += 1;
+                found.push(relPath);
+            }
+        }
+    }
+    return found;
+}
+/** Occurrence count of `needle` in `hay`, capped (both already lowercased). */
+function cappedCount(hay, needle, cap) {
+    let count = 0;
+    let i = 0;
+    while (count < cap) {
+        i = hay.indexOf(needle, i);
+        if (i === -1)
+            break;
+        count += 1;
+        i += needle.length;
+    }
+    return count;
+}
+/**
+ * Build a bounded excerpt: the lines around each token match, merged into
+ * windows, joined with ellipses. A path-only hit (no body match) takes the head
+ * of the file instead — the title/intro is the most general summary.
+ */
+export function buildExcerpt(body, tokens, maxChars) {
+    const lines = body.split("\n");
+    const lower = lines.map((l) => l.toLowerCase());
+    const matched = [];
+    for (let i = 0; i < lower.length; i++) {
+        if (tokens.some((t) => lower[i].includes(t)))
+            matched.push(i);
+    }
+    if (matched.length === 0) {
+        return body.slice(0, maxChars);
+    }
+    // Merge +/-5-line windows around the matches, preserving order.
+    const CONTEXT = 5;
+    const ranges = [];
+    for (const m of matched) {
+        const start = Math.max(0, m - CONTEXT);
+        const end = Math.min(lines.length - 1, m + CONTEXT);
+        const last = ranges[ranges.length - 1];
+        if (last && start <= last[1] + 1)
+            last[1] = Math.max(last[1], end);
+        else
+            ranges.push([start, end]);
+    }
+    const parts = [];
+    let total = 0;
+    for (const [start, end] of ranges) {
+        const chunk = lines.slice(start, end + 1).join("\n").trim();
+        if (!chunk)
+            continue;
+        if (total + chunk.length > maxChars) {
+            const room = maxChars - total;
+            if (room > 80)
+                parts.push(chunk.slice(0, room));
+            break;
+        }
+        parts.push(chunk);
+        total += chunk.length;
+    }
+    return parts.join("\n[...]\n");
+}
+/**
+ * Collect the repo docs most relevant to `query` from the working tree at
+ * `cwd`. Returns [] on any repo without matching docs (or without docs at all)
+ * — the caller then sends nothing and the backend behaves exactly as before.
+ * Never throws: grounding must not be able to break the ask itself.
+ */
+export function collectRepoDocs(cwd, query, opts = {}) {
+    const maxDocs = opts.maxDocs ?? 3;
+    const maxExcerptChars = opts.maxExcerptChars ?? 2_000;
+    const maxFiles = opts.maxFiles ?? 400;
+    const maxFileBytes = opts.maxFileBytes ?? 512 * 1024;
+    const fsImpl = opts.fsImpl ?? defaultFs;
+    const gitImpl = opts.gitImpl === undefined ? defaultGit : opts.gitImpl;
+    try {
+        const tokens = tokenizeQuery(query);
+        if (tokens.length === 0)
+            return [];
+        // Prefer the git-HEAD baseline (echo-chamber guard, see module doc); fall
+        // back to the working-tree walk only when cwd is not a usable git tree.
+        const headDocs = gitImpl ? gitImpl.listDocsAtHead(cwd) : null;
+        const candidates = headDocs
+            ? headDocs.filter(isDocCandidate).slice(0, maxFiles)
+            : candidatePaths(cwd, maxFiles, fsImpl);
+        const readBody = (rel) => {
+            if (headDocs)
+                return gitImpl.readAtHead(cwd, rel);
+            const abs = path.join(cwd, rel);
+            try {
+                if (fsImpl.statSize(abs) > maxFileBytes)
+                    return null;
+                return fsImpl.readFileSync(abs);
+            }
+            catch {
+                return null;
+            }
+        };
+        const scored = [];
+        for (const rel of candidates) {
+            const body = readBody(rel);
+            if (body === null || body.length > maxFileBytes)
+                continue;
+            const lowerBody = body.toLowerCase();
+            const lowerPath = rel.toLowerCase();
+            let score = 0;
+            for (const t of tokens) {
+                if (lowerPath.includes(t))
+                    score += 10;
+                score += cappedCount(lowerBody, t, 5);
+            }
+            if (score >= 2)
+                scored.push({ rel, score, body });
+        }
+        scored.sort((a, b) => b.score - a.score || a.rel.length - b.rel.length || (a.rel < b.rel ? -1 : 1));
+        return scored.slice(0, maxDocs).map((s) => ({
+            // Repo-relative with forward slashes so the citation reads the same on
+            // every platform.
+            path: s.rel.split(path.sep).join("/"),
+            excerpt: buildExcerpt(s.body, tokenizeQuery(query), maxExcerptChars),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=repoDocs.js.map

package/dist/extension/resilientFetch.d.ts

@@ -0,0 +1,60 @@
+/**
+ * R4a - resilientFetch for the read-path grounding tools and boot fetches.
+ *
+ * All five grounding tools and both boot fetches single-shot `fetch` and throw raw
+ * on the first blip, so a transient 429/5xx/socket reset stops grounding answering
+ * mid-session. `resilientFetch` wraps any `fetch` impl with bounded,
+ * transient-only retry (honoring `Retry-After`), a per-attempt timeout composed
+ * with the caller's signal (reusing R1's `composeAbortSignal`), and a friendly
+ * error on network exhaustion. `friendlyFetchError` maps a non-ok response to an
+ * actionable, body-truncated message for the tools' own `!res.ok` throw.
+ *
+ * Metered/write POSTs use `METERED_POST_FETCH_POLICY` (one attempt): server-side
+ * idempotency is the right place for replay, and retrying billed or capture
+ * requests client-side can duplicate spend or recorded judgment.
+ *
+ * Pure-ish: backoff sleep + jitter are injectable so the unit tests never wait.
+ */
+/** Tuning surface for {@link resilientFetch}. */
+export interface ResilientFetchPolicy {
+    /** Total attempts including the first (1 = no retry). */
+    maxAttempts: number;
+    backoffBaseMs: number;
+    backoffMaxMs: number;
+    /** Per-attempt wall-clock timeout (composed with the caller signal). */
+    timeoutMs: number;
+    /** Jitter as a fraction of the computed delay (+/-). */
+    jitterRatio: number;
+}
+/** Generous defaults: a few quick retries, a 30s per-attempt cap. */
+export declare const DEFAULT_FETCH_POLICY: ResilientFetchPolicy;
+/**
+ * POSTs that trigger LLM work or write YAGNI records must not be replayed by the
+ * client. Server-side idempotency is the right fix for retries; until then, make
+ * one attempt and surface the response.
+ */
+export declare const METERED_POST_FETCH_POLICY: ResilientFetchPolicy;
+export interface ResilientFetchOpts {
+    policy?: ResilientFetchPolicy;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    /** Backoff sleep (default: real timer); injected in tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Jitter source in [0, 1) (default: Math.random). */
+    random?: () => number;
+}
+/**
+ * Fetch with bounded, transient-only retry. Returns the Response for any success
+ * or non-retryable status (the caller still inspects `res.ok`); returns the LAST
+ * retryable response when attempts are exhausted; throws a friendly Error only on
+ * network exhaustion. Never retries once the caller signal has aborted.
+ */
+export declare function resilientFetch(url: string, init: RequestInit, opts?: ResilientFetchOpts): Promise<Response>;
+/**
+ * Map a non-ok response to a friendly, body-truncated message for a tool's throw.
+ * Auth statuses get an actionable re-login hint; everything else carries the
+ * status plus a capped slice of the body so a giant HTML error never floods the
+ * agent. No em-dashes (house copy rule).
+ */
+export declare function friendlyFetchError(label: string, res: Response): Promise<string>;
+//# sourceMappingURL=resilientFetch.d.ts.map

package/dist/extension/resilientFetch.js

@@ -0,0 +1,133 @@
+/**
+ * R4a - resilientFetch for the read-path grounding tools and boot fetches.
+ *
+ * All five grounding tools and both boot fetches single-shot `fetch` and throw raw
+ * on the first blip, so a transient 429/5xx/socket reset stops grounding answering
+ * mid-session. `resilientFetch` wraps any `fetch` impl with bounded,
+ * transient-only retry (honoring `Retry-After`), a per-attempt timeout composed
+ * with the caller's signal (reusing R1's `composeAbortSignal`), and a friendly
+ * error on network exhaustion. `friendlyFetchError` maps a non-ok response to an
+ * actionable, body-truncated message for the tools' own `!res.ok` throw.
+ *
+ * Metered/write POSTs use `METERED_POST_FETCH_POLICY` (one attempt): server-side
+ * idempotency is the right place for replay, and retrying billed or capture
+ * requests client-side can duplicate spend or recorded judgment.
+ *
+ * Pure-ish: backoff sleep + jitter are injectable so the unit tests never wait.
+ */
+import { composeAbortSignal } from "./pipeline/resilience.js";
+/** Generous defaults: a few quick retries, a 30s per-attempt cap. */
+export const DEFAULT_FETCH_POLICY = {
+    maxAttempts: 3,
+    backoffBaseMs: 300,
+    backoffMaxMs: 5_000,
+    timeoutMs: 30_000,
+    jitterRatio: 0.25,
+};
+/**
+ * POSTs that trigger LLM work or write YAGNI records must not be replayed by the
+ * client. Server-side idempotency is the right fix for retries; until then, make
+ * one attempt and surface the response.
+ */
+export const METERED_POST_FETCH_POLICY = {
+    ...DEFAULT_FETCH_POLICY,
+    maxAttempts: 1,
+};
+/** Statuses worth retrying: request timeout, too-early, rate limit, and 5xx. */
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+const MAX_ERROR_BODY = 800;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Parse a `Retry-After` header (delta seconds; HTTP-date is ignored) into ms, or null. */
+function retryAfterMs(res) {
+    const raw = res.headers.get("retry-after");
+    if (!raw)
+        return null;
+    const secs = Number(raw.trim());
+    if (Number.isFinite(secs) && secs >= 0)
+        return Math.round(secs * 1000);
+    return null;
+}
+function backoff(policy, attempt, random) {
+    const raw = Math.min(policy.backoffMaxMs, policy.backoffBaseMs * 2 ** (attempt - 1));
+    const jitter = raw * policy.jitterRatio * (random() * 2 - 1);
+    return Math.max(0, Math.round(raw + jitter));
+}
+/**
+ * Fetch with bounded, transient-only retry. Returns the Response for any success
+ * or non-retryable status (the caller still inspects `res.ok`); returns the LAST
+ * retryable response when attempts are exhausted; throws a friendly Error only on
+ * network exhaustion. Never retries once the caller signal has aborted.
+ */
+export async function resilientFetch(url, init, opts = {}) {
+    const policy = opts.policy ?? DEFAULT_FETCH_POLICY;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? defaultSleep;
+    const random = opts.random ?? Math.random;
+    const callerSignal = opts.signal;
+    let lastError;
+    let lastResponse;
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+        if (callerSignal?.aborted)
+            break;
+        // Per-attempt timeout via a manual controller so the timer is always cleared
+        // on settle (AbortSignal.timeout would leak a ref'd timer past a fast success).
+        const timeoutController = new AbortController();
+        const timer = setTimeout(() => timeoutController.abort(), policy.timeoutMs);
+        timer.unref?.();
+        const signal = composeAbortSignal(callerSignal, timeoutController.signal);
+        try {
+            const res = await fetchImpl(url, { ...init, signal });
+            if (res.ok || !RETRYABLE_STATUS.has(res.status))
+                return res;
+            lastResponse = res;
+            if (attempt >= policy.maxAttempts)
+                return res;
+            const wait = retryAfterMs(res) ?? backoff(policy, attempt, random);
+            await sleep(wait);
+        }
+        catch (err) {
+            lastError = err;
+            // A genuine caller cancel must not be retried; a timeout abort is retryable.
+            if (callerSignal?.aborted)
+                throw err;
+            if (attempt >= policy.maxAttempts)
+                break;
+            await sleep(backoff(policy, attempt, random));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    if (lastResponse)
+        return lastResponse;
+    const reason = lastError instanceof Error ? lastError.message : String(lastError ?? "unknown error");
+    throw new Error(`could not reach the YAGNI backend after ${policy.maxAttempts} attempts (network): ${reason}`);
+}
+/**
+ * Map a non-ok response to a friendly, body-truncated message for a tool's throw.
+ * Auth statuses get an actionable re-login hint; everything else carries the
+ * status plus a capped slice of the body so a giant HTML error never floods the
+ * agent. No em-dashes (house copy rule).
+ */
+export async function friendlyFetchError(label, res) {
+    let body = "";
+    try {
+        body = (await res.text()).trim();
+    }
+    catch {
+        /* body unreadable */
+    }
+    if (body.length > MAX_ERROR_BODY)
+        body = `${body.slice(0, MAX_ERROR_BODY)} ...`;
+    if (res.status === 401 || res.status === 403) {
+        return `${label} is not authorized (HTTP ${res.status}). Run \`yagni login\` to re-authenticate.`;
+    }
+    if (res.status === 429) {
+        return `${label} was rate limited (HTTP 429). Try again in a moment.`;
+    }
+    if (res.status >= 500) {
+        return `${label} failed: the YAGNI backend returned HTTP ${res.status}.${body ? ` ${body}` : ""}`;
+    }
+    return `${label} failed: HTTP ${res.status}.${body ? ` ${body}` : ""}`;
+}
+//# sourceMappingURL=resilientFetch.js.map

package/dist/extension/reviewTool.d.ts

@@ -0,0 +1,34 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Citation } from "./askYagniTool.js";
+/** Options for {@link makeReviewBusinessMatchTool}. */
+export interface MakeReviewToolOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    /**
+     * How to obtain the diff when the agent doesn't pass one. Injectable so the
+     * unit test is deterministic; defaults to reading the repo's staged (then
+     * unstaged) changes via git. pi's ExtensionContext exposes no exec, so the
+     * tool shells out itself.
+     */
+    getDiff?: (cwd: string | undefined, signal: AbortSignal | undefined) => Promise<string>;
+}
+declare const parameters: Type.TObject<{
+    summary: Type.TOptional<Type.TString>;
+    diff: Type.TOptional<Type.TString>;
+    ticket: Type.TOptional<Type.TString>;
+}>;
+/**
+ * Build the `review_business_match` tool.
+ *
+ * Reviews a code change for BUSINESS fit — whether it matches how THIS company
+ * works and its current priorities — grounded in the YAGNI app, with citations.
+ * Distinct from a correctness/bug review: it catches "right code, wrong thing"
+ * (contradicts a decision, solves a narrower thing than the customer needs).
+ */
+export declare function makeReviewBusinessMatchTool(opts: MakeReviewToolOptions): ToolDefinition<typeof parameters, {
+    citations: Citation[];
+}>;
+export {};
+//# sourceMappingURL=reviewTool.d.ts.map

package/dist/extension/reviewTool.js

@@ -0,0 +1,81 @@
+import { execFile } from "node:child_process";
+import { Type } from "typebox";
+import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+const parameters = Type.Object({
+    summary: Type.Optional(Type.String()),
+    diff: Type.Optional(Type.String()),
+    ticket: Type.Optional(Type.String()),
+});
+function runGit(args, cwd, signal) {
+    return new Promise((resolve) => {
+        execFile("git", args, { cwd, signal, maxBuffer: 32 * 1024 * 1024 }, (err, stdout) => resolve(err ? "" : stdout));
+    });
+}
+async function defaultGetDiff(cwd, signal) {
+    const staged = await runGit(["diff", "--staged"], cwd, signal);
+    if (staged.trim().length > 0)
+        return staged;
+    return runGit(["diff"], cwd, signal);
+}
+/**
+ * Build the `review_business_match` tool.
+ *
+ * Reviews a code change for BUSINESS fit — whether it matches how THIS company
+ * works and its current priorities — grounded in the YAGNI app, with citations.
+ * Distinct from a correctness/bug review: it catches "right code, wrong thing"
+ * (contradicts a decision, solves a narrower thing than the customer needs).
+ */
+export function makeReviewBusinessMatchTool(opts) {
+    return {
+        name: "review_business_match",
+        label: "Review (business fit)",
+        description: "Review a code change for BUSINESS fit (not bugs/style): does it match how this " +
+            "company works and its current priorities, and does it conflict with any decision " +
+            "or convention? Grounded in the YAGNI app, returns a verdict plus citations. Pass " +
+            "a `diff` (and a `summary` of intent); if omitted, the repo's staged/unstaged diff " +
+            "is used. Run this before opening a PR.",
+        promptSnippet: "review_business_match: check a diff against how the company works + its priorities (cited).",
+        promptGuidelines: [
+            "Run review_business_match before finishing a change, especially anything product- or policy-adjacent.",
+            "Pass a one-line `summary` of what the change is for and the `ticket` it serves, so the review can judge fit.",
+            "Treat flagged conflicts as real: reconcile with the cited decision/convention or ask the user.",
+        ],
+        parameters,
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: "Reviewing for business fit with YAGNI…" }],
+                details: { citations: [] },
+            });
+            const getDiff = opts.getDiff ?? defaultGetDiff;
+            let diff = params.diff?.trim() ?? "";
+            if (!diff) {
+                diff = (await getDiff(ctx?.cwd, signal)).trim();
+            }
+            if (!diff) {
+                throw new Error("review_business_match: no diff provided and no staged/unstaged git changes were found in the repo.");
+            }
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/review`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.getToken() ?? ""}`,
+                },
+                body: JSON.stringify({
+                    diff,
+                    summary: params.summary,
+                    ticket: params.ticket,
+                    cwd: ctx?.cwd,
+                }),
+            }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok) {
+                throw new Error(await friendlyFetchError("review_business_match", res));
+            }
+            const data = (await res.json());
+            return {
+                content: [{ type: "text", text: data.review }],
+                details: { citations: data.citations ?? [] },
+            };
+        },
+    };
+}
+//# sourceMappingURL=reviewTool.js.map

package/dist/extension/spool.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Durable write-spool for the judgment-capture tools (spec §4, R4 write half).
+ *
+ * `record_decision` and `record_engineering_context` are metered writes that
+ * must never be blindly retried (invariant §0.8) — but losing a captured
+ * decision because the laptop lost Wi-Fi is worse. The backend now dedups on
+ * an `idempotencyKey` (§2), so the safe shape is:
+ *
+ *  - every logical write carries a generated idempotencyKey,
+ *  - a transport failure or 5xx appends `{endpoint, body, idempotencyKey, ts}`
+ *    to `~/.yagni-code/spool/pending.ndjson` (dir 0700, file 0600,
+ *    torn-line-tolerant — the same self-healing NDJSON pattern as
+ *    pipeline/checkpoint.ts),
+ *  - the spool is flushed at session_start and after any successful write,
+ *    replaying with the SAME idempotencyKey (the server replays the stored
+ *    response, so a duplicate flush is harmless),
+ *  - entries older than 14 days are dropped with an honest notice (stale
+ *    judgment silently landing weeks later would be worse than losing it).
+ *
+ * Everything here is FAIL-SOFT: a spool problem must never break a tool call
+ * or session start. Eval mode never reaches this module (the capture tools are
+ * not registered there).
+ */
+/** Spooled entries older than this are dropped at flush (with a notice). */
+export declare const MAX_SPOOL_AGE_MS: number;
+/** One durable pending write: replayed verbatim with the same idempotencyKey. */
+export interface SpoolEntry {
+    /** Repo-relative endpoint path, e.g. `/api/yagni-code/decisions`. */
+    endpoint: string;
+    /** The JSON body as originally posted (already carrying the idempotencyKey). */
+    body: Record<string, unknown>;
+    idempotencyKey: string;
+    /** Epoch ms when the write first failed (drives the 14-day expiry). */
+    ts: number;
+}
+export declare function _setSpoolHomeForTest(dir: string | null): void;
+/** The on-disk pending file (exported so tests can inspect it directly). */
+export declare function spoolFile(): string;
+/** Append one pending write. NEVER throws (fail-soft: memory loss beats a crash). */
+export declare function appendToSpool(entry: SpoolEntry): void;
+/** Load pending entries, dropping torn/garbage lines. Never throws. */
+export declare function loadSpool(): SpoolEntry[];
+/** The transport/auth surface a flush or a spooling write posts through. */
+export interface SpoolClientOpts {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/** What one flush did — `notices` are honest, user-showable one-liners. */
+export interface FlushOutcome {
+    replayed: number;
+    droppedExpired: number;
+    droppedRejected: number;
+    remaining: number;
+    notices: string[];
+}
+/**
+ * Replay every pending write with its ORIGINAL idempotencyKey (server-side
+ * dedup makes a double replay a no-op). Serialized: concurrent flushes (a
+ * session_start racing a post-write flush) coalesce onto one pass.
+ *
+ * Per entry: expired (>14d) → dropped with a notice; 2xx → replayed; a
+ * permanent 4xx (not auth/rate) → dropped with a notice (the backend will
+ * never accept it); transport error, 5xx, 401/403/408/429 → kept, and the
+ * rest of the flush stops (the backend is unreachable or the token is bad —
+ * hammering the remaining entries would not help). Never throws.
+ */
+export declare function flushSpool(opts: SpoolClientOpts): Promise<FlushOutcome>;
+/** The outcome of one spool-backed judgment write. */
+export type JudgmentWriteOutcome = {
+    kind: "ok";
+    json: unknown;
+}
+/** Transport failure or 5xx: the write is durably spooled for replay. */
+ | {
+    kind: "spooled";
+    reason: string;
+}
+/** A non-retryable client error: the caller should throw this message. */
+ | {
+    kind: "rejected";
+    message: string;
+};
+/**
+ * POST one judgment write with its idempotencyKey; on transport failure or a
+ * 5xx, durably spool it for replay instead of losing it. A successful write
+ * also kicks a background flush (fail-soft, fire-and-forget) so earlier
+ * stranded entries drain as soon as the backend is healthy again.
+ */
+export declare function sendOrSpool(opts: SpoolClientOpts, label: string, endpoint: string, body: Record<string, unknown>, idempotencyKey: string, signal?: AbortSignal): Promise<JudgmentWriteOutcome>;
+//# sourceMappingURL=spool.d.ts.map