@yagni-app/code 0.1.0 → 0.2.1

package/dist/extension/costHud.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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`.
+ *
+ * YAG-383: the backend now serves `GET /api/yagni-code/spend?sessionId=`, a
+ * server-authoritative figure invisible to `turn_end` (subagents and advisor
+ * consults bill under this same session id, so a plain `sessionId=` query
+ * already sees them). `/go`'s children are the one exception: they bill under
+ * their OWN run id (`llm_usage.session_id` holds the run id, not the driver's
+ * session id, for a run-attributed dispatch), so the fetch also widens with
+ * `&runIds=` for every run this session has launched (see sessionRuns.ts and
+ * the goCommand.ts seam that records one as soon as it is known). `/cost`
+ * PREFERS that combined number. The local `turn_end` accumulator remains as
+ * the fail-soft fallback: it only ever sees the driver's own turns, so
+ * whenever it is shown it is explicitly labeled "(local, driver only)" rather
+ * than presented as the whole session's spend.
+ */
+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;
+}
+export declare function formatCostLine(snap: CostSnapshot, headroom?: Headroom | null, advisorLine?: string, source?: string, boosted?: boolean): string;
+/**
+ * One row of `GET /api/yagni-code/spend`'s per-caller x rate-tier breakdown.
+ * Mirrored locally rather than importing `@yagni/shared`, since this extension
+ * has no dependency on the shared package (see `YagniCodeSpendRow` in
+ * `packages/shared/src/types.ts` for the canonical, fuller-commented
+ * definition this must stay shape-compatible with).
+ */
+export interface SpendRow {
+    caller: string;
+    rateTier: string;
+    boost: boolean;
+    dispatches: number;
+    promptTokens: number;
+    completionTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    sellMillicents: number;
+    counterfactualMillicents: number | null;
+}
+/** `GET /api/yagni-code/spend`'s response shape (mirrors `YagniCodeSpendResponse`). */
+export interface SpendResponse {
+    rows: SpendRow[];
+    totalSellMillicents: number;
+    unbilledSellMillicents: number;
+    totalCounterfactualMillicents: number;
+    savingsMillicents: number;
+    savingsPercent: number | null;
+    counterfactualIncomplete: boolean;
+}
+/**
+ * Millicents (1/1000 of a cent) -> dollars, 2 decimals. Guards against a
+ * malformed response field (NaN/Infinity) rendering as literal "NaN"/"Infinity"
+ * in a dollar amount: render $0.00 instead, since a network response is
+ * untyped at runtime and every other guard in this module is best-effort.
+ *
+ * Exported so `/go`'s per-stage cost table (runCostTable.ts, Task 8) reuses
+ * this exact money formatting instead of duplicating it.
+ */
+export declare const usd: (millicents: number) => string;
+/**
+ * Render the server-authoritative /cost lines: PREFERRED over
+ * {@link formatCostLine}'s local accumulator whenever the spend fetch succeeds
+ * (see `registerCostCommand`'s empty-response guard for the one exception),
+ * because it covers children the local accumulator cannot see (subagents,
+ * advisor consults, and every /go run this session launched, widened in via
+ * `runIds` before the fetch even runs). Pure, no em-dashes, multi-line
+ * (joined with "\n").
+ *
+ * Line order: total spend, one line per rate tier (aggregated across callers,
+ * sorted by spend descending), a boosted-spend subtotal per tier that has any
+ * boosted rows, a live-toggle boost line (see below), the savings line (only
+ * when a counterfactual total resolved), an incomplete-counterfactual note,
+ * an unbilled note, a dropped-run-ids note (carry-over from the /cost
+ * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.
+ *
+ * `droppedRunCount` defaults to 0 (no note) so every existing direct caller
+ * of this pure function keeps behaving identically without passing it.
+ *
+ * `boosted` (default false) is the LIVE client-side toggle from
+ * `boostCommand.ts`'s `isBoosted()`, threaded in exactly like `advisorLine`
+ * is for {@link formatCostLine}. It is independent of the per-tier "Boosted
+ * (tier) spend" subtotal above: that subtotal only reflects server rows
+ * carrying `x-yagni-boost`, which only `/go` children (and other spawned
+ * processes) ever send — the driver's own turns never do (see
+ * boostCommand.ts's KNOWN-asymmetry docblock). Without this flag, a session
+ * that only chats while boosted would show no boost line at all.
+ */
+export declare function formatServerCostLines(spend: SpendResponse, headroom?: Headroom | null, droppedRunCount?: number, boosted?: boolean): 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. Only used in the local fallback
+     * line: the server-authoritative line already includes advisor spend as an
+     * ordinary caller row.
+     */
+    advisorSubtotal?: () => string;
+    /**
+     * Whether the session is currently boosted to Peak (boostCommand.ts's
+     * `isBoosted()`, threaded in the same way as `advisorSubtotal`). Unlike
+     * `advisorSubtotal`, this is read on BOTH the server-authoritative and the
+     * local-fallback branch: the driver's own turns never carry a server-side
+     * boost marker (see boostCommand.ts's KNOWN-asymmetry docblock), so this is
+     * the only signal that would otherwise be missing from the server branch.
+     */
+    isBoosted?: () => boolean;
+    /**
+     * Fetch the server-authoritative session spend (YAG-383). Absent, throwing,
+     * or resolving null all fall back to the local `turn_end` accumulator, with
+     * its source explicitly labeled so it is never mistaken for the full total.
+     */
+    fetchSpend?: (signal?: AbortSignal) => Promise<SpendResponse | null>;
+    /**
+     * Quiet diagnostic hook: fired when the server's DRIVER-scoped spend (the
+     * `spend.rows` entries with `caller === "driver"` — the same scope the
+     * local `turn_end` accumulator can see) and the local accumulator disagree
+     * by more than {@link DIVERGENCE_THRESHOLD} (relative to the larger), so
+     * long as both are available. NEVER user-facing: the caller decides
+     * whether/where to log it. Defaults to a no-op.
+     *
+     * Carry-over fix from the /cost re-review: this used to compare against
+     * `spend.totalSellMillicents`, which (since YAG-383's `runIds` widening)
+     * includes every `/go` run this session launched — spend the LOCAL
+     * accumulator can never see (every /go stage runs in a child process). That
+     * made the two totals disagree by construction on any session with a /go
+     * run behind it, firing on effectively every post-run /cost rather than on
+     * a genuine drift between the two driver-scoped measurements.
+     */
+    onDivergence?: (driverServerUsd: number, localUsd: number) => void;
+    /**
+     * Count of `/go` run ids this session has ever dropped off the
+     * `MAX_TRACKED_RUN_IDS` cap (sessionRuns.ts's `droppedSessionRuns`).
+     * Carry-over from the /cost re-review: surfaced as an honest "Excludes N
+     * earlier /go runs." note on the server-authoritative line so a very
+     * long-lived session's total is never silently missing runs. Absent (or
+     * returning 0) omits the note entirely.
+     */
+    droppedSessionRuns?: () => number;
+}
+/**
+ * Wire the turn_end accumulator + the /cost command. /cost prefers the
+ * server-authoritative spend (fetched fresh on every call); a failing, absent,
+ * or null-resolving fetch falls back to the local session accumulator, labeled
+ * "(local, driver only)" so it is never mistaken for the whole session's spend.
+ * `/cost reset` zeroes only the local counter. The server figure is
+ * unaffected, and the reset notice says so.
+ */
+export declare function registerCostCommand(pi: ExtensionAPI, deps?: RegisterCostDeps): void;
+//# sourceMappingURL=costHud.d.ts.map

package/dist/extension/costHud.js

@@ -0,0 +1,293 @@
+/**
+ * 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`.
+ *
+ * YAG-383: the backend now serves `GET /api/yagni-code/spend?sessionId=`, a
+ * server-authoritative figure invisible to `turn_end` (subagents and advisor
+ * consults bill under this same session id, so a plain `sessionId=` query
+ * already sees them). `/go`'s children are the one exception: they bill under
+ * their OWN run id (`llm_usage.session_id` holds the run id, not the driver's
+ * session id, for a run-attributed dispatch), so the fetch also widens with
+ * `&runIds=` for every run this session has launched (see sessionRuns.ts and
+ * the goCommand.ts seam that records one as soon as it is known). `/cost`
+ * PREFERS that combined number. The local `turn_end` accumulator remains as
+ * the fail-soft fallback: it only ever sees the driver's own turns, so
+ * whenever it is shown it is explicitly labeled "(local, driver only)" rather
+ * than presented as the whole session's spend.
+ */
+/** 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). `source`, when given, is parenthesized right after "Session
+ * usage", used to explicitly label this as the LOCAL, driver-only fallback when
+ * the server-authoritative spend fetch is unavailable (see
+ * {@link formatServerCostLines}, the preferred path).
+ *
+ * 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.
+ */
+/** The boost-active line appended to /cost, both branches (see boostCommand.ts's docblock for why). */
+const BOOST_LINE = "Boost is on. Driver turns bill at the peak tier.";
+export function formatCostLine(snap, headroom, advisorLine, source, boosted = false) {
+    const turns = `${snap.turns} turn${snap.turns === 1 ? "" : "s"}`;
+    const cached = snap.cacheRead > 0 ? ` (${fmt(snap.cacheRead)} cached)` : "";
+    const label = source ? `Session usage (${source})` : "Session usage";
+    const base = `${label}: ${turns}, ${fmt(snap.input)} in / ${fmt(snap.output)} out tokens${cached}, ` +
+        `$${snap.cost.toFixed(2)} this session.`;
+    const advisor = advisorLine?.trim() ? ` ${advisorLine.trim()}` : "";
+    const boost = boosted ? ` ${BOOST_LINE}` : "";
+    if (headroom)
+        return `${base}${advisor}${boost} Credit headroom: ${headroom.remaining} ${headroom.unit}.`;
+    if (headroom === null)
+        return `${base}${advisor}${boost} Credit headroom unavailable right now.`;
+    return `${base}${advisor}${boost}`;
+}
+/**
+ * Millicents (1/1000 of a cent) -> dollars, 2 decimals. Guards against a
+ * malformed response field (NaN/Infinity) rendering as literal "NaN"/"Infinity"
+ * in a dollar amount: render $0.00 instead, since a network response is
+ * untyped at runtime and every other guard in this module is best-effort.
+ *
+ * Exported so `/go`'s per-stage cost table (runCostTable.ts, Task 8) reuses
+ * this exact money formatting instead of duplicating it.
+ */
+export const usd = (millicents) => {
+    if (!Number.isFinite(millicents))
+        return "0.00";
+    return (millicents / 100_000).toFixed(2);
+};
+/**
+ * Render the server-authoritative /cost lines: PREFERRED over
+ * {@link formatCostLine}'s local accumulator whenever the spend fetch succeeds
+ * (see `registerCostCommand`'s empty-response guard for the one exception),
+ * because it covers children the local accumulator cannot see (subagents,
+ * advisor consults, and every /go run this session launched, widened in via
+ * `runIds` before the fetch even runs). Pure, no em-dashes, multi-line
+ * (joined with "\n").
+ *
+ * Line order: total spend, one line per rate tier (aggregated across callers,
+ * sorted by spend descending), a boosted-spend subtotal per tier that has any
+ * boosted rows, a live-toggle boost line (see below), the savings line (only
+ * when a counterfactual total resolved), an incomplete-counterfactual note,
+ * an unbilled note, a dropped-run-ids note (carry-over from the /cost
+ * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.
+ *
+ * `droppedRunCount` defaults to 0 (no note) so every existing direct caller
+ * of this pure function keeps behaving identically without passing it.
+ *
+ * `boosted` (default false) is the LIVE client-side toggle from
+ * `boostCommand.ts`'s `isBoosted()`, threaded in exactly like `advisorLine`
+ * is for {@link formatCostLine}. It is independent of the per-tier "Boosted
+ * (tier) spend" subtotal above: that subtotal only reflects server rows
+ * carrying `x-yagni-boost`, which only `/go` children (and other spawned
+ * processes) ever send — the driver's own turns never do (see
+ * boostCommand.ts's KNOWN-asymmetry docblock). Without this flag, a session
+ * that only chats while boosted would show no boost line at all.
+ */
+export function formatServerCostLines(spend, headroom, droppedRunCount = 0, boosted = false) {
+    const lines = [`Session spend: $${usd(spend.totalSellMillicents)} (server).`];
+    const tierTotals = new Map();
+    for (const row of spend.rows) {
+        const agg = tierTotals.get(row.rateTier) ?? { sellMillicents: 0, dispatches: 0 };
+        agg.sellMillicents += row.sellMillicents;
+        agg.dispatches += row.dispatches;
+        tierTotals.set(row.rateTier, agg);
+    }
+    const tiersSorted = [...tierTotals.entries()].sort((a, b) => b[1].sellMillicents - a[1].sellMillicents);
+    for (const [tier, agg] of tiersSorted) {
+        const calls = `${fmt(agg.dispatches)} call${agg.dispatches === 1 ? "" : "s"}`;
+        lines.push(`  ${tier}: $${usd(agg.sellMillicents)} over ${calls}.`);
+    }
+    const boostTotals = new Map();
+    for (const row of spend.rows) {
+        if (!row.boost)
+            continue;
+        boostTotals.set(row.rateTier, (boostTotals.get(row.rateTier) ?? 0) + row.sellMillicents);
+    }
+    if (boostTotals.size > 0) {
+        for (const [tier] of tiersSorted) {
+            const tierBoosted = boostTotals.get(tier);
+            if (tierBoosted === undefined)
+                continue;
+            lines.push(`  Boosted (${tier}) spend: $${usd(tierBoosted)}.`);
+        }
+    }
+    if (boosted) {
+        lines.push(BOOST_LINE);
+    }
+    // typeof guard (not just !== null): a network response is untyped at
+    // runtime, and a stray string/boolean here must never sneak "NN%" into the
+    // rendered line.
+    if (typeof spend.savingsPercent === "number") {
+        lines.push(`Saved $${usd(spend.savingsMillicents)} (${spend.savingsPercent}%) vs frontier list prices.`);
+    }
+    if (spend.counterfactualIncomplete) {
+        lines.push("Savings shown for priced tiers only.");
+    }
+    if (spend.unbilledSellMillicents > 0) {
+        // Matches YagniCodeUsageView.tsx's wording for the same figure.
+        lines.push(`Includes $${usd(spend.unbilledSellMillicents)} not yet billed (insufficient credits or a billing error).`);
+    }
+    if (droppedRunCount > 0) {
+        lines.push(`Excludes ${fmt(droppedRunCount)} earlier /go run${droppedRunCount === 1 ? "" : "s"}.`);
+    }
+    if (headroom) {
+        lines.push(`Credit headroom: ${headroom.remaining} ${headroom.unit}.`);
+    }
+    else if (headroom === null) {
+        lines.push("Credit headroom unavailable right now.");
+    }
+    return lines.join("\n");
+}
+/** A server/local total pair diverges enough to be worth a quiet debug note. */
+const DIVERGENCE_THRESHOLD = 0.1; // 10%, relative to the larger of the two
+/**
+ * Wire the turn_end accumulator + the /cost command. /cost prefers the
+ * server-authoritative spend (fetched fresh on every call); a failing, absent,
+ * or null-resolving fetch falls back to the local session accumulator, labeled
+ * "(local, driver only)" so it is never mistaken for the whole session's spend.
+ * `/cost reset` zeroes only the local counter. The server figure is
+ * unaffected, and the reset notice says so.
+ */
+export function registerCostCommand(pi, deps = {}) {
+    const acc = makeCostAccumulator();
+    const fetchHeadroom = deps.fetchHeadroom;
+    const fetchSpend = deps.fetchSpend;
+    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. Server totals are unaffected.", "info");
+                }
+                return;
+            }
+            // Run headroom + spend concurrently: two SEQUENTIAL fail-soft fetches
+            // would each burn their own timeout on a slow/unreachable backend
+            // (worst case double the silence before /cost says anything at all).
+            // Promise.all bounds the wait to whichever is slower, not their sum.
+            const [headroom, spend] = await Promise.all([
+                fetchHeadroom
+                    ? fetchHeadroom(ctx.signal).catch(() => null) // fail-soft: still report session usage
+                    : Promise.resolve(undefined),
+                fetchSpend
+                    ? fetchSpend(ctx.signal).catch(() => null) // fail-soft: fall back to the local accumulator
+                    : Promise.resolve(null),
+            ]);
+            const localSnap = acc.snapshot();
+            // Read fresh on every /cost call, both branches (see RegisterCostDeps's
+            // isBoosted doc comment for why the local fallback needs it too).
+            let boosted = false;
+            try {
+                boosted = deps.isBoosted?.() ?? false;
+            }
+            catch {
+                /* a diagnostic must never break /cost */
+            }
+            // Quiet divergence check: both totals must be available, and it never
+            // affects what the user sees. Scoped to `caller === "driver"` rows only
+            // (like-for-like with the local `turn_end` accumulator, which can only
+            // ever see the driver's own turns) — NOT spend.totalSellMillicents,
+            // which includes every /go run this session launched and would
+            // otherwise disagree with the local total by construction. See the
+            // onDivergence doc comment above for the full story.
+            if (spend) {
+                try {
+                    const driverServerUsd = spend.rows.filter((r) => r.caller === "driver").reduce((sum, r) => sum + r.sellMillicents, 0) / 100_000;
+                    const localUsd = localSnap.cost;
+                    const larger = Math.max(driverServerUsd, localUsd);
+                    if (larger > 0 && Math.abs(driverServerUsd - localUsd) / larger > DIVERGENCE_THRESHOLD) {
+                        deps.onDivergence?.(driverServerUsd, localUsd);
+                    }
+                }
+                catch {
+                    /* a diagnostic must never break /cost */
+                }
+            }
+            // An empty server response (no rows at all) alongside a NONZERO local
+            // accumulator is more likely billing lag (the row has not landed yet)
+            // than an honestly-zero session: showing "$0.00 (server)" over real,
+            // already-observed local spend would read as a regression, not a fix.
+            // Prefer the labeled local line in exactly this state.
+            const serverLooksStale = spend !== null && spend.rows.length === 0 && localSnap.turns > 0;
+            if (spend && !serverLooksStale) {
+                let dropped = 0;
+                try {
+                    dropped = deps.droppedSessionRuns?.() ?? 0;
+                }
+                catch {
+                    /* a diagnostic must never break /cost */
+                }
+                await pi.sendUserMessage(formatServerCostLines(spend, headroom, dropped, boosted));
+                return;
+            }
+            let advisorLine = "";
+            try {
+                advisorLine = deps.advisorSubtotal?.() ?? "";
+            }
+            catch {
+                /* usage accounting must never break /cost */
+            }
+            await pi.sendUserMessage(formatCostLine(localSnap, headroom, advisorLine, "local, driver only", boosted));
+        },
+    });
+}
+//# sourceMappingURL=costHud.js.map

package/dist/extension/crashReport.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Crash reporting for the pi extension: a sanitized, fire-and-forget POST to
+ * the YAGNI backend's /api/yagni-code/crash. No third-party telemetry SDK —
+ * crash reports are the only thing that phones home, they contain no code and
+ * no prompts, and `YAGNI_DISABLE_CRASH_REPORTS=1` turns them off.
+ *
+ * Two report paths use this module:
+ *   - `uncaughtExceptionMonitor` (installed by index.ts): the MONITOR hook is
+ *     chosen deliberately — unlike an `uncaughtException` listener it never
+ *     changes crash semantics in pi's process (which YAGNI does not own); it
+ *     only observes the crash that is already happening. This is also the
+ *     "tool error that indicates a crash, not a user error" discriminator:
+ *     a user-visible tool failure is caught and rendered by pi, while
+ *     anything reaching the monitor was about to kill the session.
+ *   - the /go pipeline's terminal catch (goCommand.ts), where a thrown error
+ *     — not a verdict-shaped failure — ends the run.
+ *
+ * Everything is fail-soft: never throws, never retries, single short-timeout
+ * attempt, and reporting can never affect the user's session.
+ *
+ * The sanitizer (env-value redaction + path collapse + caps around the shared
+ * scrubSecrets patterns) is kept in sync with
+ * `yagni-code-cli/src/crashReport.ts`; the backend re-runs its own copy in
+ * `backend/src/yagniCode/crashReports.ts`. Spec:
+ * docs/superpowers/specs/2026-08-08-crash-reporting-design.md
+ */
+export declare const CRASH_REPORT_DISABLE_ENV = "YAGNI_DISABLE_CRASH_REPORTS";
+export declare const CRASH_REPORT_TIMEOUT_MS = 1500;
+export declare const MAX_CRASH_MESSAGE = 512;
+export declare const MAX_CRASH_ERROR_CLASS = 128;
+export declare const MAX_CRASH_STACK = 8000;
+export declare const MAX_CRASH_STACK_FRAMES = 40;
+export declare const MAX_CRASH_PAYLOAD_BYTES = 16384;
+/** Same truthiness rule as the CLI's YAGNI_DISABLE_* family. */
+export declare function crashReportsDisabled(env?: NodeJS.ProcessEnv): boolean;
+export interface SanitizeCrashOptions {
+    env?: NodeJS.ProcessEnv;
+    repoRoot?: string;
+}
+/** Env values → [ENV:NAME], scrubSecrets patterns, ~-collapse, repo-relative, basename. */
+export declare function sanitizeCrashText(text: string, opts?: SanitizeCrashOptions): string;
+export interface SanitizedCrash {
+    errorClass: string;
+    message: string;
+    stack?: string;
+}
+/** Reads ONLY name/message/stack; custom error fields are never touched. */
+export declare function sanitizeCrashError(err: unknown, opts?: SanitizeCrashOptions): SanitizedCrash;
+export interface CrashReporterOpts {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+export type CrashReporter = (error: unknown, context?: string, repoRoot?: string) => Promise<void>;
+/**
+ * Build the fail-soft reporter. The extension runs inside pi's process, so
+ * the client label follows the surface: `desktop` under the desktop shell
+ * (YAGNI_SURFACE=desktop), `cli` in the terminal. Version comes from
+ * `YAGNI_CODE_VERSION` (forwarded by the launcher; the bundled extension has
+ * no package.json on disk). Resolves on every outcome; never throws.
+ */
+export declare function makeCrashReporter(opts: CrashReporterOpts): CrashReporter;
+export type SpawnLike = (command: string, args: string[], options: {
+    detached: boolean;
+    stdio: "ignore";
+    env: Record<string, string | undefined>;
+}) => {
+    unref: () => void;
+};
+export interface FatalCrashOpts extends CrashReporterOpts {
+    /** Spawn seam for tests (defaults to node:child_process spawn). */
+    spawnImpl?: SpawnLike;
+}
+/**
+ * Deliver a crash report from a process that is about to die: build the
+ * sanitized payload in-process (cheap, synchronous), then spawn a detached
+ * one-shot sender that outlives the crash. Never throws.
+ */
+export declare function reportFatalCrash(error: unknown, opts: FatalCrashOpts, context?: string): void;
+/**
+ * Observe (never alter) a fatal crash in pi's process. Uses
+ * `uncaughtExceptionMonitor`, which fires before the process dies without
+ * installing a handler that would change node's default crash behavior —
+ * YAGNI does not own pi's process, so crash semantics must stay untouched.
+ */
+export declare function installUncaughtExceptionMonitor(opts: FatalCrashOpts, proc?: Pick<NodeJS.Process, "on">): void;
+//# sourceMappingURL=crashReport.d.ts.map