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

package/dist/extension/recall.js

@@ -0,0 +1,187 @@
+/**
+ * Ambient judgment recall (spec §4, M1 — degraded-tolerant).
+ *
+ * After the `read` tool returns, fetch the compact recorded judgment for that
+ * path (`GET /recall`) and append a `⟦YAGNI recall⟧ …` block to the tool result
+ * so the agent sees the decisions/corrections already banked for this file —
+ * zero extra turns, no model call.
+ *
+ * pi-recall-surface finding (verified against pi 0.80.2
+ * `dist/core/extensions/types.d.ts`): the interactive `tool_result` event is
+ * documented "Fired after a tool executes. Can modify result." and its handler
+ * result `ToolResultEventResult` exposes `content?: (TextContent | ImageContent)[]`.
+ * So RESULT MODIFICATION is supported: we return the original content plus the
+ * recall block. (The documented `before_agent_start` brief-injection fallback is
+ * therefore NOT needed here.)
+ *
+ * Everything is fail-soft and bounded:
+ *  - `AbortSignal.timeout` + a hard deadline race cap the fetch at 1500ms, so
+ *    recall NEVER blocks a read beyond the timeout — even if the shared
+ *    authed-fetch seam attempts a 401 refresh underneath.
+ *  - per-path session cache (a path is fetched at most once per session).
+ *  - skipped entirely when the corpus is thin (<3 active decisions) or eval mode.
+ *  - any failure degrades to no injection.
+ */
+import { isAbsolute, relative } from "node:path";
+import { composeAbortSignal } from "./pipeline/resilience.js";
+/** Recall must never block a read beyond this (spec §4). */
+export const RECALL_TIMEOUT_MS = 1500;
+/** Below this many active decisions, recall is skipped entirely (spec: <3). */
+export const RECALL_MIN_DECISIONS = 3;
+/** Client-side caps mirror the backend (compact by construction). */
+export const RECALL_MAX_DECISIONS = 5;
+export const RECALL_MAX_CORRECTIONS = 3;
+function isRecallDecision(v) {
+    const d = v;
+    return !!d && typeof d.id === "string" && typeof d.question === "string" && typeof d.decision === "string";
+}
+function isRecallCorrection(v) {
+    const c = v;
+    return !!c && typeof c.summary === "string";
+}
+/** Defensive parse of a /recall response into a {@link RecallResult}, or null. */
+export function normalizeRecall(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const d = data;
+    const decisions = Array.isArray(d.decisions)
+        ? d.decisions.filter(isRecallDecision).slice(0, RECALL_MAX_DECISIONS)
+        : [];
+    const corrections = Array.isArray(d.corrections)
+        ? d.corrections.filter(isRecallCorrection).slice(0, RECALL_MAX_CORRECTIONS)
+        : [];
+    return { decisions, corrections, thin: d.thin === true };
+}
+/**
+ * Pure: derive the repo-relative path the backend expects from a read tool's
+ * `path` argument and the session cwd. Rebases an absolute path INSIDE the tree
+ * to a relative one (an outside path stays absolute), and strips a leading `./`.
+ */
+export function toRepoRelativePath(readPath, cwd) {
+    let p = readPath.trim();
+    if (isAbsolute(p)) {
+        const rel = relative(cwd, p);
+        if (rel && !rel.startsWith("..") && !isAbsolute(rel))
+            p = rel;
+    }
+    return p.replace(/^\.\//, "");
+}
+/**
+ * Pure: render the compact `⟦YAGNI recall⟧` block, or null when there is
+ * nothing to inject (missing result, thin corpus, or empty). No em-dashes.
+ */
+export function formatRecallBlock(result) {
+    if (!result || result.thin)
+        return null;
+    const parts = [];
+    for (const d of result.decisions)
+        parts.push(`- ${d.question} => ${d.decision}`);
+    for (const c of result.corrections)
+        parts.push(`- correction: ${c.summary}`);
+    if (parts.length === 0)
+        return null;
+    return `⟦YAGNI recall⟧ recorded judgment for this path:\n${parts.join("\n")}`;
+}
+/**
+ * Run `work` bounded by a hard `timeoutMs` deadline: resolves the work's value
+ * on settle, or `null` when the deadline fires first (the deadline signal is
+ * aborted so the outstanding fetch tears down). Guarantees a return within
+ * `timeoutMs` regardless of what the fetch impl does underneath.
+ */
+function withDeadline(timeoutMs, work) {
+    const controller = new AbortController();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            controller.abort();
+            resolve(null);
+        }, timeoutMs);
+        timer.unref?.();
+        work(controller.signal).then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+    });
+}
+/**
+ * GET /recall for a repo-relative path, bounded at {@link RECALL_TIMEOUT_MS}.
+ * Uses the shared authed fetch (inherits the 401 refresh-retry), but the hard
+ * deadline still caps the total wait. Returns null on any non-2xx, timeout, or
+ * error (fail-soft).
+ */
+export async function fetchRecall(opts, path, signal) {
+    const timeoutMs = opts.timeoutMs ?? RECALL_TIMEOUT_MS;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const query = new URLSearchParams({ path });
+    if (opts.repo)
+        query.set("repo", opts.repo);
+    const url = `${opts.baseUrl}/api/yagni-code/recall?${query.toString()}`;
+    return withDeadline(timeoutMs, async (deadlineSignal) => {
+        const composed = composeAbortSignal(signal, deadlineSignal);
+        try {
+            const res = await fetchImpl(url, {
+                method: "GET",
+                headers: { authorization: `Bearer ${opts.getToken() ?? ""}` },
+                signal: composed,
+            });
+            if (!res.ok)
+                return null;
+            return normalizeRecall((await res.json()));
+        }
+        catch {
+            return null;
+        }
+    });
+}
+/**
+ * Wire the `tool_result` handler that appends recall to a `read` result. No-op
+ * (nothing registered) when the corpus is thin (<3 decisions) or in eval mode,
+ * so there is zero overhead in those cases.
+ */
+export function registerAmbientRecall(pi, deps) {
+    if (deps.evalMode)
+        return;
+    if ((deps.decisionsCount ?? 0) < RECALL_MIN_DECISIONS)
+        return;
+    const doFetch = deps.fetchRecallImpl ?? fetchRecall;
+    // Per-path session cache: a path is fetched at most once. Only real results
+    // (success, including a thin/empty payload) are cached; a transient failure
+    // (null) is NOT cached, so a later read of the same path can retry.
+    const cache = new Map();
+    const clientOpts = {
+        baseUrl: deps.baseUrl,
+        getToken: deps.getToken,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        repo: deps.repo,
+    };
+    pi.on("tool_result", async (event, ctx) => {
+        try {
+            if (event.toolName !== "read" || event.isError)
+                return;
+            const rawPath = event.input.path;
+            if (typeof rawPath !== "string" || rawPath.trim().length === 0)
+                return;
+            const relPath = toRepoRelativePath(rawPath, ctx.cwd);
+            let result;
+            if (cache.has(relPath)) {
+                result = cache.get(relPath) ?? null;
+            }
+            else {
+                result = await doFetch(clientOpts, relPath, ctx.signal);
+                if (result !== null)
+                    cache.set(relPath, result);
+            }
+            const block = formatRecallBlock(result);
+            if (!block)
+                return;
+            return { content: [...event.content, { type: "text", text: `\n\n${block}` }] };
+        }
+        catch {
+            return; // fail-soft: recall never breaks a read
+        }
+    });
+}
+//# sourceMappingURL=recall.js.map

package/dist/extension/recordContextTool.d.ts

@@ -0,0 +1,38 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+/** Options for {@link makeRecordEngineeringContextTool}. */
+export interface MakeRecordContextToolOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    /** Idempotency-key source (default: crypto.randomUUID); injected in tests. */
+    makeIdempotencyKey?: () => string;
+    /**
+     * How to resolve the agent's pushed head SHA when a PR is being handed off.
+     * Injectable so the unit test is deterministic; defaults to `git rev-parse
+     * HEAD` in `ctx.cwd` (best-effort — resolves to undefined on any failure, so
+     * the server simply records no head SHA). Mirrors {@link reviewTool}'s
+     * `getDiff` exec seam since pi's ExtensionContext exposes no exec.
+     */
+    resolveHeadSha?: (cwd: string | undefined, signal?: AbortSignal) => Promise<string | undefined>;
+}
+declare const parameters: Type.TObject<{
+    ticket: Type.TString;
+    body: Type.TString;
+    prUrl: Type.TOptional<Type.TString>;
+    repo: Type.TOptional<Type.TString>;
+    prNumber: Type.TOptional<Type.TNumber>;
+}>;
+/**
+ * Build the `record_engineering_context` tool.
+ *
+ * Writes the engineering rationale ("why it was done", the tradeoffs/decisions)
+ * back onto the originating YAGNI work-item, closing the loop so the ticket
+ * carries the decision context. Reversible internal write.
+ */
+export declare function makeRecordEngineeringContextTool(opts: MakeRecordContextToolOptions): ToolDefinition<typeof parameters, {
+    workItemId: string | null;
+    spooled?: boolean;
+}>;
+export {};
+//# sourceMappingURL=recordContextTool.d.ts.map

package/dist/extension/recordContextTool.js

@@ -0,0 +1,85 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import { sendOrSpool } from "./spool.js";
+const parameters = Type.Object({
+    ticket: Type.String(),
+    body: Type.String(),
+    prUrl: Type.Optional(Type.String()),
+    repo: Type.Optional(Type.String()),
+    prNumber: Type.Optional(Type.Number()),
+});
+/** Best-effort `git rev-parse HEAD` in `cwd`; resolves to undefined on failure. */
+function defaultResolveHeadSha(cwd, signal) {
+    return new Promise((resolve) => {
+        execFile("git", ["rev-parse", "HEAD"], { cwd, signal, maxBuffer: 1024 * 1024 }, (err, stdout) => resolve(err ? undefined : stdout.trim() || undefined));
+    });
+}
+/**
+ * Build the `record_engineering_context` tool.
+ *
+ * Writes the engineering rationale ("why it was done", the tradeoffs/decisions)
+ * back onto the originating YAGNI work-item, closing the loop so the ticket
+ * carries the decision context. Reversible internal write.
+ */
+export function makeRecordEngineeringContextTool(opts) {
+    return {
+        name: "record_engineering_context",
+        label: "Record engineering context",
+        description: "Record the engineering rationale for a change back onto its work-item/ticket so " +
+            "the team has the decision context: WHY it was done, the tradeoffs, and what was " +
+            "considered — not just what changed. Pass the ticket identifier (e.g. YAG-42), the " +
+            "rationale `body`, and optionally the `prUrl`. Use after finishing work tied to a ticket.",
+        promptSnippet: "record_engineering_context: write WHY a change was made back onto its ticket.",
+        promptGuidelines: [
+            "After finishing work tied to a ticket, record the rationale (the decision and tradeoffs), not just a restatement of the diff.",
+            "Pass the ticket identifier exactly as the user/work-item gives it (e.g. YAG-42).",
+            "Keep it the durable 'why' a teammate would want months later, concise and specific.",
+            "If you opened a PR for this work, pass `repo` (owner/name) and `prNumber` so the change can be matched and learned from after merge.",
+        ],
+        parameters,
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: `Recording context on ${params.ticket}…` }],
+                details: { workItemId: null },
+            });
+            const headSha = await (opts.resolveHeadSha ?? defaultResolveHeadSha)(ctx?.cwd, signal);
+            // Every logical write carries a generated idempotencyKey (the backend
+            // dedups on it), so transport failures and 5xx are durably spooled and
+            // replayed later instead of lost or double-recorded (R4 write half).
+            const idempotencyKey = (opts.makeIdempotencyKey ?? randomUUID)();
+            const outcome = await sendOrSpool(opts, "record_engineering_context", "/api/yagni-code/record", {
+                ticket: params.ticket,
+                body: params.body,
+                prUrl: params.prUrl,
+                repo: params.repo,
+                prNumber: params.prNumber,
+                headSha,
+                cwd: ctx?.cwd,
+            }, idempotencyKey, signal);
+            if (outcome.kind === "rejected") {
+                throw new Error(outcome.message);
+            }
+            if (outcome.kind === "spooled") {
+                // Honest: not recorded YET, but durably saved and replayed with the
+                // same idempotencyKey at the next session start or successful write.
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Could not reach YAGNI (${outcome.reason}). ` +
+                                `Saved the context for ${params.ticket} locally; it will sync automatically once the backend is reachable.`,
+                        },
+                    ],
+                    details: { workItemId: null, spooled: true },
+                };
+            }
+            const data = outcome.json;
+            return {
+                content: [{ type: "text", text: `Recorded engineering context on ${params.ticket}.` }],
+                details: { workItemId: data?.workItemId ?? null, spooled: false },
+            };
+        },
+    };
+}
+//# sourceMappingURL=recordContextTool.js.map

package/dist/extension/recordDecisionTool.d.ts

@@ -0,0 +1,52 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+/** Options for {@link makeRecordDecisionTool}. */
+export interface MakeRecordDecisionToolOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    /** Idempotency-key source (default: crypto.randomUUID); injected in tests. */
+    makeIdempotencyKey?: () => string;
+}
+/** The durable fields of a recorded product-intent decision. */
+export interface RecordDecisionParams {
+    question: string;
+    decision: string;
+    rationale?: string;
+    repo?: string;
+    workItemId?: string;
+}
+export interface RecordDecisionResult {
+    id: string | null;
+    spooled?: boolean;
+    reason?: string;
+}
+/**
+ * POST a single decision to the token-scoped grounding endpoint and return its
+ * new id. Extracted so the CLI init pass (repo intake) can seed the corpus
+ * through the SAME `/api/yagni-code/decisions` write the tool uses — no new
+ * backend transport. Throws a friendly error on any non-2xx; callers that must
+ * stay fail-soft (the init pass) wrap the call in try/catch.
+ */
+export declare function recordDecision(opts: MakeRecordDecisionToolOptions, params: RecordDecisionParams, signal?: AbortSignal): Promise<RecordDecisionResult>;
+declare const parameters: Type.TObject<{
+    question: Type.TString;
+    decision: Type.TString;
+    rationale: Type.TOptional<Type.TString>;
+    repo: Type.TOptional<Type.TString>;
+    workItemId: Type.TOptional<Type.TString>;
+}>;
+/**
+ * Build the `record_decision` tool.
+ *
+ * Banks a product-intent decision ("what should this do / what does the user
+ * want here") into the YAGNI app so the SAME question is answered by `ask_yagni`
+ * next time instead of interrupting a human. This is the capture half of the
+ * judgment loop; `ask_yagni` is the read-back half. Reversible internal write.
+ */
+export declare function makeRecordDecisionTool(opts: MakeRecordDecisionToolOptions): ToolDefinition<typeof parameters, {
+    id: string | null;
+    spooled?: boolean;
+}>;
+export {};
+//# sourceMappingURL=recordDecisionTool.d.ts.map

package/dist/extension/recordDecisionTool.js

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import { sendOrSpool } from "./spool.js";
+/**
+ * POST a single decision to the token-scoped grounding endpoint and return its
+ * new id. Extracted so the CLI init pass (repo intake) can seed the corpus
+ * through the SAME `/api/yagni-code/decisions` write the tool uses — no new
+ * backend transport. Throws a friendly error on any non-2xx; callers that must
+ * stay fail-soft (the init pass) wrap the call in try/catch.
+ */
+export async function recordDecision(opts, params, signal) {
+    const idempotencyKey = (opts.makeIdempotencyKey ?? randomUUID)();
+    const outcome = await sendOrSpool(opts, "record_decision", "/api/yagni-code/decisions", {
+        question: params.question,
+        decision: params.decision,
+        rationale: params.rationale,
+        repo: params.repo,
+        workItemId: params.workItemId,
+    }, idempotencyKey, signal);
+    if (outcome.kind === "rejected") {
+        throw new Error(outcome.message);
+    }
+    if (outcome.kind === "spooled") {
+        return { id: null, spooled: true, reason: outcome.reason };
+    }
+    const data = outcome.json;
+    return { id: data?.id ?? null, spooled: false };
+}
+const parameters = Type.Object({
+    question: Type.String(),
+    decision: Type.String(),
+    rationale: Type.Optional(Type.String()),
+    repo: Type.Optional(Type.String()),
+    workItemId: Type.Optional(Type.String()),
+});
+/**
+ * Build the `record_decision` tool.
+ *
+ * Banks a product-intent decision ("what should this do / what does the user
+ * want here") into the YAGNI app so the SAME question is answered by `ask_yagni`
+ * next time instead of interrupting a human. This is the capture half of the
+ * judgment loop; `ask_yagni` is the read-back half. Reversible internal write.
+ */
+export function makeRecordDecisionTool(opts) {
+    return {
+        name: "record_decision",
+        label: "Record decision",
+        description: "Record a product-intent decision ('what should this do', 'what does the user want here') so " +
+            "YAGNI can answer the same question next time instead of interrupting a human. Pass the " +
+            "`question` that was decided, the `decision` (the answer/direction taken), and optionally the " +
+            "`rationale` (why). Use right after a product-intent call is resolved — especially one you had " +
+            "to ask the user about.",
+        promptSnippet: "record_decision: bank a 'what should this do' decision so YAGNI answers it next time.",
+        promptGuidelines: [
+            "Before asking the USER a product-intent question, call ask_yagni first — the decision may already be recorded.",
+            "When a product-intent decision IS resolved (especially one you had to ask the user about), call record_decision so the next similar question is answered without interrupting a human.",
+            "Record the durable decision and its 'why', not a restatement of the code change.",
+        ],
+        parameters,
+        async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: "Recording decision in YAGNI…" }],
+                details: { id: null },
+            });
+            // Every logical write carries a generated idempotencyKey; the backend
+            // dedups on it, so a spool replay (or an authed-fetch 401 retry) can
+            // never bank the same decision twice. Transport failures and 5xx are
+            // spooled durably instead of lost (R4 write half).
+            const idempotencyKey = (opts.makeIdempotencyKey ?? randomUUID)();
+            const outcome = await sendOrSpool(opts, "record_decision", "/api/yagni-code/decisions", {
+                question: params.question,
+                decision: params.decision,
+                rationale: params.rationale,
+                repo: params.repo,
+                workItemId: params.workItemId,
+            }, idempotencyKey, signal);
+            if (outcome.kind === "rejected") {
+                throw new Error(outcome.message);
+            }
+            if (outcome.kind === "spooled") {
+                // Honest: not recorded YET, but durably saved and replayed with the
+                // same idempotencyKey at the next session start or successful write.
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Could not reach YAGNI (${outcome.reason}). ` +
+                                "Saved the decision locally; it will sync automatically once the backend is reachable.",
+                        },
+                    ],
+                    details: { id: null, spooled: true },
+                };
+            }
+            const data = outcome.json;
+            return {
+                content: [{ type: "text", text: "Recorded the decision in YAGNI." }],
+                details: { id: data?.id ?? null, spooled: false },
+            };
+        },
+    };
+}
+//# sourceMappingURL=recordDecisionTool.js.map

package/dist/extension/repoDocs.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+/** One repo doc offered to the backend as grounding. `path` is repo-relative. */
+export interface RepoDocSnippet {
+    path: string;
+    excerpt: string;
+}
+/** Injectable fs seam (default: node:fs sync calls). */
+export interface RepoDocsFs {
+    readFileSync: (p: string) => string;
+    readdirSync: (p: string) => Array<{
+        name: string;
+        isDirectory(): boolean;
+        isFile(): boolean;
+    }>;
+    statSize: (p: string) => number;
+}
+/**
+ * Injectable git seam. `listDocsAtHead` returns every tracked path at HEAD (or
+ * null when cwd is not a usable git tree — the fs fallback then applies);
+ * `readAtHead` returns one file's baseline content (null when unreadable).
+ */
+export interface RepoDocsGit {
+    listDocsAtHead: (cwd: string) => string[] | null;
+    readAtHead: (cwd: string, rel: string) => string | null;
+}
+export interface CollectRepoDocsOptions {
+    /** Max docs returned (default 3). */
+    maxDocs?: number;
+    /** Max chars per doc excerpt (default 2000). */
+    maxExcerptChars?: number;
+    /** Cap on files scanned during the docs/ walk (default 400). */
+    maxFiles?: number;
+    /** Skip files larger than this many bytes (default 512 KiB). */
+    maxFileBytes?: number;
+    fsImpl?: RepoDocsFs;
+    /** Git seam; `null` disables git entirely (forces the working-tree fallback). */
+    gitImpl?: RepoDocsGit | null;
+}
+/** Lowercased, deduped, stopword-free query tokens (length >= 3). */
+export declare function tokenizeQuery(query: string): string[];
+/**
+ * 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 declare function buildExcerpt(body: string, tokens: string[], maxChars: number): string;
+/**
+ * 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 declare function collectRepoDocs(cwd: string, query: string, opts?: CollectRepoDocsOptions): RepoDocSnippet[];
+//# sourceMappingURL=repoDocs.d.ts.map