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

package/dist/extension/config.js

@@ -0,0 +1,108 @@
+/**
+ * Configuration + catalog-fetch helpers for the YAGNI pi extension.
+ *
+ * `YAGNI_BASE_URL` and `YAGNI_TOKEN` are read from the process environment,
+ * which the `yagni` launcher is responsible for populating. `YAGNI_CODE_DEBUG`
+ * (any truthy value) is an optional operator switch that surfaces fail-soft
+ * diagnostics on stderr, e.g. why a /go run could not be recorded (HTTP status +
+ * a token-free body excerpt); off by default and never required.
+ */
+import { resilientFetch } from "./resilientFetch.js";
+const DEFAULT_BASE_URL = "https://yagni.app";
+/**
+ * Resolve the YAGNI backend base URL from the environment.
+ *
+ * Falls back to {@link DEFAULT_BASE_URL}, trims whitespace, and strips a single
+ * trailing slash so callers can safely append paths.
+ */
+export function resolveBaseUrl(env = process.env) {
+    return (env.YAGNI_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+/** Read the bearer token used to authenticate with the YAGNI backend. */
+export function getToken(env = process.env) {
+    return env.YAGNI_TOKEN;
+}
+/**
+ * Read the workspace id the token is bound to, forwarded by the launcher as
+ * `YAGNI_WORKSPACE_ID` (from the stored credentials). Used to key the one-time
+ * init-pass marker ({@link initDone}). Absent on older logins (treated as
+ * unknown → the marker gate degrades to freshness-only, still fail-closed).
+ */
+export function getWorkspaceId(env = process.env) {
+    return env.YAGNI_WORKSPACE_ID?.trim() || undefined;
+}
+/**
+ * Read the token's ISO expiry, forwarded by the launcher as
+ * `YAGNI_TOKEN_EXPIRES_AT`. Absent on older logins (treated as unknown).
+ */
+export function getTokenExpiresAt(env = process.env) {
+    return env.YAGNI_TOKEN_EXPIRES_AT;
+}
+/**
+ * How close to expiry the token can be before the session-start notice fires.
+ * A long session can outlive its token, so a single heads-up lets the user
+ * re-login before completions and grounding tools start 401-ing mid-flight.
+ */
+export const EXPIRY_NOTICE_THRESHOLD_MS = 30 * 60 * 1000;
+/**
+ * Pure helper: given the token's ISO expiry and the current time, return the
+ * notice to surface at session start, or null when there is nothing to say
+ * (missing/unparseable expiry, or comfortably valid). Never throws. This only
+ * reads the expiry; it never refreshes the token (no new auth surface).
+ */
+export function tokenExpiryNotice(expiresAt, nowMs, thresholdMs = EXPIRY_NOTICE_THRESHOLD_MS) {
+    if (!expiresAt)
+        return null;
+    const expiryMs = Date.parse(expiresAt);
+    if (Number.isNaN(expiryMs))
+        return null;
+    const remaining = expiryMs - nowMs;
+    if (remaining <= 0) {
+        return {
+            message: "Your YAGNI Code session has expired. Run `yagni login` to re-authenticate.",
+            type: "error",
+        };
+    }
+    if (remaining <= thresholdMs) {
+        const minutes = Math.max(1, Math.ceil(remaining / 60_000));
+        return {
+            message: `Your YAGNI Code session expires in about ${minutes} minute${minutes === 1 ? "" : "s"}. ` +
+                "Run `yagni login` to refresh it before it lapses.",
+            type: "warning",
+        };
+    }
+    return null;
+}
+/**
+ * Fetch the YAGNI model catalog at startup.
+ *
+ * @throws an actionable Error (mentioning `yagni login`) on any non-2xx
+ * response so the launcher can surface a clear re-authentication prompt.
+ */
+export async function fetchCatalog(opts) {
+    const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/models`, { method: "GET", headers: { authorization: `Bearer ${opts.getToken() ?? ""}` } }, { fetchImpl: opts.fetchImpl });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch YAGNI model catalog (HTTP ${res.status}). Run \`yagni login\` to re-authenticate.`);
+    }
+    const data = (await res.json());
+    return data.models;
+}
+/**
+ * Fetch the workspace company brief at startup.
+ *
+ * Unlike {@link fetchCatalog}, this is BEST-EFFORT: a missing or failed brief
+ * must never block the agent (it still works, just without boot-time grounding).
+ * Returns `null` on any non-2xx response or network error.
+ */
+export async function fetchContextBrief(opts) {
+    try {
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, { method: "GET", headers: { authorization: `Bearer ${opts.getToken() ?? ""}` } }, { fetchImpl: opts.fetchImpl });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/extension/costHud.d.ts

@@ -0,0 +1,73 @@
+/**
+ * P2 - /cost command + a session usage accumulator.
+ *
+ * pi already shows model + usage in its footer, so this does not rebuild a live
+ * counter. The net-new value is a pull `/cost` command backed by a pure,
+ * session-scoped accumulator and an optional, fail-soft credits-headroom fetch, so
+ * invisible enforcement becomes visible trust.
+ *
+ * Feasibility correction (verified against pi 0.80.2): the interactive
+ * `after_provider_response` event carries only { status, headers }, NOT usage. The
+ * usage-bearing seam is `turn_end`, whose `message: AgentMessage` carries `usage`
+ * (the same shape events.ts already reads off the NDJSON stream). So the
+ * accumulator hangs off `turn_end`, not `after_provider_response`.
+ *
+ * The accumulator + formatter are PURE; the headroom fetch is injectable and
+ * fail-soft, so /cost always reports session usage even when the backend is down.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** A single turn's usage delta, normalized from pi's message.usage shape. */
+export interface UsageDelta {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+/** Running session totals (turns = number of assistant turns accumulated). */
+export interface CostSnapshot extends UsageDelta {
+    turns: number;
+}
+export interface CostAccumulator {
+    add(delta: UsageDelta): void;
+    snapshot(): CostSnapshot;
+    reset(): void;
+}
+/** A pure, session-scoped usage accumulator. */
+export declare function makeCostAccumulator(): CostAccumulator;
+/** Extract a normalized {@link UsageDelta} from a turn_end message, defensively. */
+export declare function usageFromMessage(message: unknown): UsageDelta;
+/** Credit headroom returned by the backend (fail-soft; null when unavailable). */
+export interface Headroom {
+    remaining: number;
+    unit: string;
+}
+/**
+ * Render the /cost line. Pure, no em-dashes. `headroom` null means it was
+ * unavailable. `advisorLine` is the ask_advisor subtotal (empty when the session
+ * never escalated).
+ *
+ * HONESTY NOTE: this counter can only see the DRIVER session, because it is fed
+ * by pi's `turn_end`. Work that runs in a child process — every /go stage, and
+ * every advisor consult — never emits a parent `turn_end`, so it is invisible
+ * here. The advisor subtotal is threaded in explicitly for exactly that reason.
+ * /go's spend is still missing; the server-authoritative fix is YAG-383.
+ */
+export declare function formatCostLine(snap: CostSnapshot, headroom?: Headroom | null, advisorLine?: string): string;
+export interface RegisterCostDeps {
+    /** Fetch remaining credit headroom; return null when unavailable. Fail-soft. */
+    fetchHeadroom?: (signal?: AbortSignal) => Promise<Headroom | null>;
+    /**
+     * Render the ask_advisor subtotal for this session, or "" when it never
+     * escalated. Threaded in because advisor consults run in a child process and
+     * so never reach the `turn_end` accumulator.
+     */
+    advisorSubtotal?: () => string;
+}
+/**
+ * Wire the turn_end accumulator + the /cost command. /cost reports the session
+ * totals plus headroom (when the fetch resolves); a failing or absent fetch still
+ * reports session usage. `/cost reset` zeroes the session counter.
+ */
+export declare function registerCostCommand(pi: ExtensionAPI, deps?: RegisterCostDeps): void;
+//# sourceMappingURL=costHud.d.ts.map

package/dist/extension/costHud.js

@@ -0,0 +1,123 @@
+/**
+ * P2 - /cost command + a session usage accumulator.
+ *
+ * pi already shows model + usage in its footer, so this does not rebuild a live
+ * counter. The net-new value is a pull `/cost` command backed by a pure,
+ * session-scoped accumulator and an optional, fail-soft credits-headroom fetch, so
+ * invisible enforcement becomes visible trust.
+ *
+ * Feasibility correction (verified against pi 0.80.2): the interactive
+ * `after_provider_response` event carries only { status, headers }, NOT usage. The
+ * usage-bearing seam is `turn_end`, whose `message: AgentMessage` carries `usage`
+ * (the same shape events.ts already reads off the NDJSON stream). So the
+ * accumulator hangs off `turn_end`, not `after_provider_response`.
+ *
+ * The accumulator + formatter are PURE; the headroom fetch is injectable and
+ * fail-soft, so /cost always reports session usage even when the backend is down.
+ */
+/** A pure, session-scoped usage accumulator. */
+export function makeCostAccumulator() {
+    let s = { turns: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+    return {
+        add(d) {
+            s = {
+                turns: s.turns + 1,
+                input: s.input + d.input,
+                output: s.output + d.output,
+                cacheRead: s.cacheRead + d.cacheRead,
+                cacheWrite: s.cacheWrite + d.cacheWrite,
+                cost: s.cost + d.cost,
+            };
+        },
+        snapshot() {
+            return { ...s };
+        },
+        reset() {
+            s = { turns: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+        },
+    };
+}
+/** Extract a normalized {@link UsageDelta} from a turn_end message, defensively. */
+export function usageFromMessage(message) {
+    const u = message?.usage;
+    if (!u)
+        return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+    const cost = typeof u.cost === "number" ? u.cost : (u.cost?.total ?? 0);
+    return {
+        input: u.input ?? 0,
+        output: u.output ?? 0,
+        cacheRead: u.cacheRead ?? 0,
+        cacheWrite: u.cacheWrite ?? 0,
+        cost,
+    };
+}
+const fmt = (n) => n.toLocaleString("en-US");
+/**
+ * Render the /cost line. Pure, no em-dashes. `headroom` null means it was
+ * unavailable. `advisorLine` is the ask_advisor subtotal (empty when the session
+ * never escalated).
+ *
+ * HONESTY NOTE: this counter can only see the DRIVER session, because it is fed
+ * by pi's `turn_end`. Work that runs in a child process — every /go stage, and
+ * every advisor consult — never emits a parent `turn_end`, so it is invisible
+ * here. The advisor subtotal is threaded in explicitly for exactly that reason.
+ * /go's spend is still missing; the server-authoritative fix is YAG-383.
+ */
+export function formatCostLine(snap, headroom, advisorLine) {
+    const turns = `${snap.turns} turn${snap.turns === 1 ? "" : "s"}`;
+    const cached = snap.cacheRead > 0 ? ` (${fmt(snap.cacheRead)} cached)` : "";
+    const base = `Session usage: ${turns}, ${fmt(snap.input)} in / ${fmt(snap.output)} out tokens${cached}, ` +
+        `$${snap.cost.toFixed(2)} this session.`;
+    const advisor = advisorLine?.trim() ? ` ${advisorLine.trim()}` : "";
+    if (headroom)
+        return `${base}${advisor} Credit headroom: ${headroom.remaining} ${headroom.unit}.`;
+    if (headroom === null)
+        return `${base}${advisor} Credit headroom unavailable right now.`;
+    return `${base}${advisor}`;
+}
+/**
+ * Wire the turn_end accumulator + the /cost command. /cost reports the session
+ * totals plus headroom (when the fetch resolves); a failing or absent fetch still
+ * reports session usage. `/cost reset` zeroes the session counter.
+ */
+export function registerCostCommand(pi, deps = {}) {
+    const acc = makeCostAccumulator();
+    const fetchHeadroom = deps.fetchHeadroom;
+    pi.on("turn_end", (event) => {
+        try {
+            acc.add(usageFromMessage(event.message));
+        }
+        catch {
+            /* usage accounting must never disrupt a turn */
+        }
+    });
+    pi.registerCommand("cost", {
+        description: "Show this session's token + cost usage, and remaining credit headroom. /cost reset to zero it.",
+        handler: async (args, ctx) => {
+            if (args.trim().toLowerCase() === "reset") {
+                acc.reset();
+                if (ctx.hasUI)
+                    ctx.ui.notify("Session usage counter reset.", "info");
+                return;
+            }
+            let headroom = undefined;
+            if (fetchHeadroom) {
+                try {
+                    headroom = await fetchHeadroom(ctx.signal);
+                }
+                catch {
+                    headroom = null; // fail-soft: still report session usage
+                }
+            }
+            let advisorLine = "";
+            try {
+                advisorLine = deps.advisorSubtotal?.() ?? "";
+            }
+            catch {
+                /* usage accounting must never break /cost */
+            }
+            await pi.sendUserMessage(formatCostLine(acc.snapshot(), headroom, advisorLine));
+        },
+    });
+}
+//# sourceMappingURL=costHud.js.map

package/dist/extension/decisionCapture.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Decision capture at the human gate (spec §4, M3 — conservative).
+ *
+ * When the user picks "Yes, and don't ask again for <tool> in <dir>" at the
+ * review gate, that is a piece of durable judgment worth banking so YAGNI
+ * answers the same question next time instead of interrupting a human. Capture
+ * is deliberately conservative:
+ *
+ *  - HEADLESS never auto-banks (no consent surface; review-mode bless is itself
+ *    fail-closed headless, but this guards regardless).
+ *  - TUI ALWAYS confirms via `ctx.ui.confirm` before banking.
+ *  - DEBOUNCED to at most one capture PROMPT per 10 minutes, so a burst of
+ *    blesses never nags.
+ *
+ * The bank goes through {@link bankDecision} (source `cli_correction`,
+ * idempotency-keyed, spool-durable). Everything is fail-soft: a capture problem
+ * never affects the tool call that triggered it.
+ */
+import { type DecisionClientOpts } from "./decisions.js";
+import type { JudgmentWriteOutcome } from "./spool.js";
+/** At most one capture prompt per this window (spec: 10 minutes). */
+export declare const CAPTURE_DEBOUNCE_MS: number;
+/** The minimal context the capture needs (a subset of pi's ExtensionContext). */
+export interface CaptureCtx {
+    hasUI: boolean;
+    signal?: AbortSignal;
+    ui: {
+        confirm(title: string, message: string): Promise<boolean>;
+        notify(message: string, type?: "info" | "warning" | "error"): void;
+    };
+}
+/** What was blessed: the tool and a human-readable directory label. */
+export interface BlessCaptureInfo {
+    tool: string;
+    dir: string;
+}
+export interface DecisionCapture {
+    /** On a bless-with-remember: debounced, TUI-confirmed decision capture. */
+    captureFromBless(ctx: CaptureCtx, info: BlessCaptureInfo): Promise<void>;
+}
+/** Injectable seams for {@link makeDecisionCapture}. */
+export interface DecisionCaptureDeps extends DecisionClientOpts {
+    now?: () => number;
+    /** Bank implementation (default: {@link bankDecision}); injected in tests. */
+    bank?: (opts: DecisionClientOpts, params: {
+        question: string;
+        decision: string;
+    }, signal?: AbortSignal) => Promise<JudgmentWriteOutcome>;
+}
+/** Build a session-scoped decision capture (holds the debounce timestamp). */
+export declare function makeDecisionCapture(deps: DecisionCaptureDeps): DecisionCapture;
+//# sourceMappingURL=decisionCapture.d.ts.map

package/dist/extension/decisionCapture.js

@@ -0,0 +1,66 @@
+/**
+ * Decision capture at the human gate (spec §4, M3 — conservative).
+ *
+ * When the user picks "Yes, and don't ask again for <tool> in <dir>" at the
+ * review gate, that is a piece of durable judgment worth banking so YAGNI
+ * answers the same question next time instead of interrupting a human. Capture
+ * is deliberately conservative:
+ *
+ *  - HEADLESS never auto-banks (no consent surface; review-mode bless is itself
+ *    fail-closed headless, but this guards regardless).
+ *  - TUI ALWAYS confirms via `ctx.ui.confirm` before banking.
+ *  - DEBOUNCED to at most one capture PROMPT per 10 minutes, so a burst of
+ *    blesses never nags.
+ *
+ * The bank goes through {@link bankDecision} (source `cli_correction`,
+ * idempotency-keyed, spool-durable). Everything is fail-soft: a capture problem
+ * never affects the tool call that triggered it.
+ */
+import { bankDecision } from "./decisions.js";
+/** At most one capture prompt per this window (spec: 10 minutes). */
+export const CAPTURE_DEBOUNCE_MS = 10 * 60 * 1000;
+/** Build a session-scoped decision capture (holds the debounce timestamp). */
+export function makeDecisionCapture(deps) {
+    const now = deps.now ?? (() => Date.now());
+    const bank = deps.bank ?? bankDecision;
+    let lastPromptAt = Number.NEGATIVE_INFINITY;
+    return {
+        async captureFromBless(ctx, info) {
+            // Headless never auto-banks: there is no consent surface.
+            if (!ctx.hasUI)
+                return;
+            // Debounce: hold if we prompted within the window (whatever the answer).
+            const t = now();
+            if (t - lastPromptAt < CAPTURE_DEBOUNCE_MS)
+                return;
+            lastPromptAt = t;
+            const question = `Can the agent run ${info.tool} within ${info.dir} without asking each time?`;
+            const decision = `Yes, ${info.tool} within ${info.dir} is approved for this repository.`;
+            let ok = false;
+            try {
+                ok = await ctx.ui.confirm("Record this as a YAGNI decision?", `You approved ${info.tool} in ${info.dir}. Record it so YAGNI answers the same question next time instead of asking a human?`);
+            }
+            catch {
+                return; // a failed prompt never banks
+            }
+            if (!ok)
+                return;
+            try {
+                const outcome = await bank(deps, { question, decision }, ctx.signal);
+                if (outcome.kind === "ok") {
+                    ctx.ui.notify("Recorded the decision in YAGNI.", "info");
+                }
+                else if (outcome.kind === "spooled") {
+                    ctx.ui.notify("Saved the decision locally; it will sync automatically.", "info");
+                }
+                else {
+                    ctx.ui.notify(outcome.message, "error");
+                }
+            }
+            catch {
+                /* fail-soft: a capture failure never affects the tool call */
+            }
+        },
+    };
+}
+//# sourceMappingURL=decisionCapture.js.map

package/dist/extension/decisions.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The client-side decisions surface (spec §4, W4): the `/decide` and
+ * `/decisions` commands plus the shared write helper the bless-capture flow
+ * reuses.
+ *
+ *  - `bankDecision` POSTs a `source: 'cli_correction'` decision with a generated
+ *    idempotencyKey through the durable write-spool (part A), so a transport
+ *    failure or 5xx spools it for replay instead of losing it, and a replay can
+ *    never double-bank (server dedups on the key).
+ *  - `fetchDecisions` / `supersedeDecision` reuse the shared authed-fetch seam,
+ *    so a GET/PATCH inherits the one 401-refresh-then-retry-once behaviour.
+ *  - `/decide <question> => <decision>` records ONE decision directly (the user
+ *    typed it — explicit intent, no extra confirm or debounce).
+ *  - `/decisions` lists recent decisions (id-prefixed, compact); `/decisions
+ *    supersede <id>` flips one to superseded.
+ *
+ * Formatters and the arg parser are pure; the network calls are injectable via
+ * the shared `SpoolClientOpts` so tests never touch disk or the network.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type JudgmentWriteOutcome, type SpoolClientOpts } from "./spool.js";
+/** Transport + idempotency seams for the decisions surface. */
+export interface DecisionClientOpts extends SpoolClientOpts {
+    /** Idempotency-key source (default: crypto.randomUUID); injected in tests. */
+    makeIdempotencyKey?: () => string;
+}
+/** The durable fields banked by `/decide` or a bless-with-remember capture. */
+export interface BankDecisionParams {
+    question: string;
+    decision: string;
+    rationale?: string;
+    repo?: string;
+}
+/**
+ * Bank a `cli_correction` decision durably. Every logical write carries a
+ * generated idempotencyKey; the backend dedups on it, so a spool replay or a
+ * 401 retry can never bank the same decision twice. Transport failures and 5xx
+ * are spooled for replay instead of lost (R4 write half). Never throws.
+ */
+export declare function bankDecision(opts: DecisionClientOpts, params: BankDecisionParams, signal?: AbortSignal): Promise<JudgmentWriteOutcome>;
+/** One row from GET /decisions (mirrors the backend DecisionListItem). */
+export interface DecisionListItem {
+    id: string;
+    question: string;
+    decision: string;
+    rationale: string | null;
+    repoFullName: string | null;
+    source: string;
+    status: string;
+    createdAt: string;
+    citedCount: number;
+}
+/** Options for {@link fetchDecisions}. */
+export interface FetchDecisionsOpts {
+    limit?: number;
+    repo?: string;
+}
+export declare const DEFAULT_LIST_LIMIT = 20;
+/** GET recent decisions (any read scope). Throws a friendly error on non-2xx. */
+export declare function fetchDecisions(opts: DecisionClientOpts, list?: FetchDecisionsOpts, signal?: AbortSignal): Promise<DecisionListItem[]>;
+/**
+ * PATCH one decision to `superseded` (scope yagni_code:write). Idempotent flip,
+ * so a single attempt is enough — no client retry (invariant §0.8). Throws a
+ * friendly error on non-2xx.
+ */
+export declare function supersedeDecision(opts: DecisionClientOpts, id: string, supersededBy?: string, signal?: AbortSignal): Promise<void>;
+/** The parsed `/decide` argument: `<question> => <decision>`. */
+export interface DecideArgs {
+    question: string;
+    decision: string;
+}
+/** Pure: parse `<question> => <decision>`; null when either half is missing. */
+export declare function parseDecideArgs(raw: string): DecideArgs | null;
+/** Pure: a short id prefix for compact display. */
+export declare function shortId(id: string): string;
+/** Pure: render the compact, id-prefixed decisions list (no em-dashes). */
+export declare function formatDecisionsList(items: DecisionListItem[]): string;
+/**
+ * Wire the `/decide` and `/decisions` commands. Both are fail-soft: any
+ * transport error surfaces as an honest notice, never a thrown command.
+ */
+export declare function registerDecisionCommands(pi: ExtensionAPI, opts: DecisionClientOpts): void;
+//# sourceMappingURL=decisions.d.ts.map