@yagni-app/code 0.1.0 → 0.2.1

package/dist/extension/pipeline/runSession.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The `/go` run-session adapter.
+ *
+ * Wraps the device-token `/api/yagni-code/runs*` endpoints so a YAGNI Code
+ * pipeline run becomes a tracked `runs` row visible on the Work page: open the
+ * run (`start`), stream each pipeline stage (`stage`), bank an in-loop
+ * correction (`correction`), and close it with an honest outcome (`finish`).
+ *
+ * CRITICAL invariant: recording must NEVER break the pipeline. Every call is
+ * fail-soft — it never throws. `start` resolves to a typed outcome that
+ * distinguishes a tracked run from an untracked one (flag off, unauthorized, or
+ * the backend unreachable/erroring) so the caller can surface a notice instead
+ * of failing silently; the post-start verbs (`stage`/`correction`/`finish`) stay
+ * silent no-ops. `/go` runs to completion regardless of the recording outcome.
+ *
+ * Mirrors the fetch-seam shape of {@link makeRecordEngineeringContextTool}
+ * (`baseUrl` + injectable `getToken` + `fetchImpl`) so it is unit-testable
+ * without a network and reuses the same auth convention.
+ */
+/** Options for {@link makeRunSession}. */
+export interface RunSessionOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    /**
+     * Backoff sleep + jitter seams, threaded into {@link resilientFetch} so the
+     * retry path is deterministic and instant under test. Default to the real
+     * timer / Math.random in production.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    /**
+     * Opt-in debug sink for diagnosing a recording failure (the fail-soft path
+     * otherwise collapses 402/5xx/2xx-bad-body/unreachable into one silent
+     * "error"). Only ever receives a token-free line: the path, the numeric HTTP
+     * status, a capped slice of the SERVER response body, or a network error
+     * message. NEVER the request headers (the bearer token) or the request body.
+     * Injected for deterministic tests; defaults to an env-gated stderr writer.
+     */
+    debug?: (line: string) => void;
+    /**
+     * Environment seam for the debug gate, matching `config.ts`/`verify.ts`. The
+     * debug sink only fires when `YAGNI_CODE_DEBUG` is set here (default
+     * `process.env`), so existing callers that inject neither `debug` nor `env`
+     * stay silent unless the operator opts in.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/** The handle returned by a successful `start` (or supplied via `bind`). */
+export interface RunSessionHandle {
+    runId: string;
+    workItemId: string;
+}
+/**
+ * The result of a successful `start`: the handle plus the server's governance
+ * verdict (`gated` = the work item needs approval in the app before it shows as
+ * executing, so /go should warn rather than silently proceed).
+ */
+export interface RunStartResult extends RunSessionHandle {
+    gated: boolean;
+    gatedReason?: string;
+}
+/**
+ * Why a run could not be recorded, derived from the endpoint's HTTP status so
+ * the caller can show an actionable notice:
+ *  - `disabled`     — 404: the `yagni_code.work_tracking` flag is off for this
+ *                     workspace (the write endpoints 404 to hide themselves).
+ *  - `unauthorized` — 401/403: the device token is missing/expired or lacks the
+ *                     `yagni_code:write` scope (re-run `yagni login`).
+ *  - `error`        — anything else: an over-budget 402, a 5xx, a 2xx with an
+ *                     unrecognized body, or an unreachable backend / thrown
+ *                     network error.
+ */
+export type RunTrackingFailure = "disabled" | "unauthorized" | "error";
+/**
+ * The outcome of opening a run. `tracked: true` carries the handle + gate
+ * verdict; `tracked: false` carries the reason so `/go` can warn that this run
+ * won't appear on the Work page. `start` never returns null and never throws.
+ */
+export type RunStartOutcome = ({
+    tracked: true;
+} & RunStartResult) | {
+    tracked: false;
+    reason: RunTrackingFailure;
+};
+/** Arguments to open a run. */
+export interface StartArgs {
+    arg: string;
+    repo?: string;
+    branch?: string;
+}
+/** A pipeline stage boundary event. */
+export interface StageArgs {
+    stage: string;
+    phase: "start" | "finish";
+    round?: number;
+    findings?: number;
+}
+/** An in-loop correction captured during the run. */
+export interface CorrectionArgs {
+    stage?: string;
+    question: string;
+    decision: string;
+    rationale?: string;
+}
+/**
+ * The /go PLAN, recorded onto the work item (a `plan_recorded` activity beat) so
+ * it is clear what the run set out to do. `body` is the plan markdown; the server
+ * scrubs secrets + caps it before persisting.
+ */
+export interface RecordPlanArgs {
+    stage: string;
+    body: string;
+}
+/** How a run ended; maps to the run-status enum server-side. */
+export interface FinishArgs {
+    outcome: "completed" | "stopped" | "failed";
+    stopReason?: string;
+    prUrl?: string;
+    prNumber?: number;
+    branch?: string;
+    commitSha?: string;
+    rounds?: number;
+    /**
+     * Short "what was done" recap; the server records it as a `run_outcome`
+     * activity (the end-of-run beat on the Work-page timeline). Optional + additive:
+     * `finish` already spreads the whole args object, so it flows through untouched.
+     */
+    outcomeSummary?: string;
+}
+/** The run-session object returned by {@link makeRunSession}. */
+export interface RunSession {
+    /** Adopt an externally-known handle (used by tests + cloud callers). */
+    bind(h: RunSessionHandle): void;
+    /** Open the run; resolves to a tracked outcome (handle + gate verdict) or an untracked reason. Never throws. */
+    start(b: StartArgs): Promise<RunStartOutcome>;
+    /** Stream a stage boundary; no-op until a handle exists. */
+    stage(b: StageArgs): Promise<void>;
+    /** Bank an in-loop correction; no-op until a handle exists. */
+    correction(b: CorrectionArgs): Promise<void>;
+    /** Record the /go plan onto the work item; no-op until a handle exists. */
+    recordPlan(b: RecordPlanArgs): Promise<void>;
+    /**
+     * Bump the run's server-side last-activity heartbeat so a long-but-alive run is
+     * not reaped as stale. No-op until a handle exists; never throws.
+     */
+    heartbeat(): Promise<void>;
+    /** Close the run with an outcome; no-op until a handle exists. */
+    finish(b: FinishArgs): Promise<void>;
+}
+export declare function makeRunSession(opts: RunSessionOptions): RunSession;
+//# sourceMappingURL=runSession.d.ts.map

package/dist/extension/pipeline/runSession.js

@@ -0,0 +1,167 @@
+/**
+ * The `/go` run-session adapter.
+ *
+ * Wraps the device-token `/api/yagni-code/runs*` endpoints so a YAGNI Code
+ * pipeline run becomes a tracked `runs` row visible on the Work page: open the
+ * run (`start`), stream each pipeline stage (`stage`), bank an in-loop
+ * correction (`correction`), and close it with an honest outcome (`finish`).
+ *
+ * CRITICAL invariant: recording must NEVER break the pipeline. Every call is
+ * fail-soft — it never throws. `start` resolves to a typed outcome that
+ * distinguishes a tracked run from an untracked one (flag off, unauthorized, or
+ * the backend unreachable/erroring) so the caller can surface a notice instead
+ * of failing silently; the post-start verbs (`stage`/`correction`/`finish`) stay
+ * silent no-ops. `/go` runs to completion regardless of the recording outcome.
+ *
+ * Mirrors the fetch-seam shape of {@link makeRecordEngineeringContextTool}
+ * (`baseUrl` + injectable `getToken` + `fetchImpl`) so it is unit-testable
+ * without a network and reuses the same auth convention.
+ */
+import { randomUUID } from "node:crypto";
+import { DEFAULT_FETCH_POLICY, METERED_POST_FETCH_POLICY, resilientFetch, } from "../resilientFetch.js";
+/** Map a failed POST's HTTP status onto a user-facing tracking-failure reason. */
+function failureReason(status) {
+    if (status === 404)
+        return "disabled";
+    if (status === 401 || status === 403)
+        return "unauthorized";
+    return "error";
+}
+/** Cap a debug body excerpt so a giant HTML/JSON error never floods the channel. */
+const MAX_DEBUG_BODY = 200;
+/**
+ * A token-free, capped `: <body>` suffix for a failed-response debug line. Reads
+ * the body only on the `!res.ok` branch (where `post` never reads it otherwise,
+ * so there is no double-consume with the ok-path `res.json()`), and swallows any
+ * read error so observability never breaks the fail-soft contract.
+ */
+async function bodyTail(res) {
+    try {
+        const t = (await res.text()).trim();
+        if (!t)
+            return "";
+        return `: ${t.length > MAX_DEBUG_BODY ? `${t.slice(0, MAX_DEBUG_BODY)} ...` : t}`;
+    }
+    catch {
+        return "";
+    }
+}
+export function makeRunSession(opts) {
+    const f = opts.fetchImpl ?? fetch;
+    let handle = null;
+    // Opt-in observability: the default sink writes to stderr, and the `YAGNI_CODE_DEBUG`
+    // gate governs an injected sink too, so callers that pass neither stay silent. The
+    // resolved sink is wrapped so it can NEVER throw out of `debug`: an injected sink
+    // that throws must not breach the fail-soft never-throw contract (in the `!res.ok`
+    // branch an unguarded throw would land in the surrounding catch and re-fire debug,
+    // escaping `post` and rejecting the recording call).
+    const sink = opts.debug ??
+        ((line) => {
+            try {
+                process.stderr.write(`${line}\n`);
+            }
+            catch {
+                /* never break recording */
+            }
+        });
+    const debug = (line) => {
+        try {
+            sink(line);
+        }
+        catch {
+            /* observability never breaks recording */
+        }
+    };
+    const debugOn = !!(opts.env ?? process.env).YAGNI_CODE_DEBUG;
+    // A run-open (`start`) is the one recording call worth retrying: if it is lost,
+    // the WHOLE run goes untracked. It is made replay-safe by an idempotency key (the
+    // server dedups a re-sent create), so it uses the retrying policy. Every other
+    // verb is append-only / terminal and stays single-attempt (METERED) so a recorded
+    // judgment (a correction) is never duplicated by a client replay.
+    const post = async (path, body, postOpts = {}) => {
+        try {
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/${path}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.getToken() ?? ""}`,
+                },
+                body: JSON.stringify(body),
+            }, {
+                fetchImpl: f,
+                policy: postOpts.retry ? DEFAULT_FETCH_POLICY : METERED_POST_FETCH_POLICY,
+                ...(opts.sleep ? { sleep: opts.sleep } : {}),
+                ...(opts.random ? { random: opts.random } : {}),
+            });
+            if (!res.ok) {
+                if (debugOn)
+                    debug(`[yagni-code] run-record ${path} -> HTTP ${res.status}${await bodyTail(res)}`);
+                return { ok: false, status: res.status };
+            }
+            return { ok: true, data: (await res.json()) };
+        }
+        catch (err) {
+            // fail-soft: recording must never break the pipeline (no status = unreachable
+            // after retries).
+            if (debugOn) {
+                debug(`[yagni-code] run-record ${path} unreachable: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return { ok: false };
+        }
+    };
+    return {
+        bind(h) {
+            handle = h;
+        },
+        async start(b) {
+            // One idempotency key per open attempt: resilientFetch replays the SAME
+            // request body across retries, so a create whose 201 was lost to a blip is
+            // deduped by the server (startCodeRun.findRunByIdempotencyKey) instead of
+            // opening a second run + a second free-text work item.
+            const r = await post("runs", { ...b, idempotencyKey: randomUUID() }, { retry: true });
+            if (!r.ok)
+                return { tracked: false, reason: failureReason(r.status) };
+            const data = r.data;
+            if (typeof data.runId === "string" && typeof data.workItemId === "string") {
+                handle = { runId: data.runId, workItemId: data.workItemId };
+                return {
+                    tracked: true,
+                    runId: handle.runId,
+                    workItemId: handle.workItemId,
+                    gated: data.gated === true,
+                    gatedReason: typeof data.gatedReason === "string" ? data.gatedReason : undefined,
+                };
+            }
+            // A 2xx with an unrecognized body: we can't bind a handle, so it's untracked.
+            if (debugOn)
+                debug("[yagni-code] run-record runs -> 2xx but body had no runId/workItemId");
+            return { tracked: false, reason: "error" };
+        },
+        async stage(b) {
+            if (!handle)
+                return;
+            await post(`runs/${handle.runId}/stages`, { ...b, workItemId: handle.workItemId });
+        },
+        async correction(b) {
+            if (!handle)
+                return;
+            await post(`runs/${handle.runId}/correction`, { ...b, workItemId: handle.workItemId });
+        },
+        async recordPlan(b) {
+            if (!handle)
+                return;
+            await post(`runs/${handle.runId}/plan`, { ...b, workItemId: handle.workItemId });
+        },
+        async heartbeat() {
+            if (!handle)
+                return;
+            await post(`runs/${handle.runId}/heartbeat`, { workItemId: handle.workItemId });
+        },
+        async finish(b) {
+            if (!handle)
+                return;
+            await post(`runs/${handle.runId}/finish`, { ...b, workItemId: handle.workItemId });
+        },
+    };
+}
+//# sourceMappingURL=runSession.js.map

package/dist/extension/pipeline/runState.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The headless model behind every `/go` progress display.
+ *
+ * `RunState` folds the structured `PipelineProgress` signals, curated
+ * `ActivityLine`s and raw assistant `JsonEvent` usage into one small model that
+ * both surfaces render from: the terminal's boxed ANSI panel (via
+ * `ActivityFeed`, which is now a pure renderer over this) and the desktop's
+ * Agents tab (via `toJSON()`, pushed as one line over `setWidget`).
+ *
+ * It owns no I/O and no clock — the caller injects `at` — so it is fully
+ * deterministic in tests, exactly like the feed it replaces.
+ *
+ * Two properties are load-bearing:
+ *
+ *  1. **Lens events never touch their parent stage.** A `stage_start` /
+ *     `stage_done` carrying a `lens` mutates only that lens's agent. Without
+ *     this the per-lens signals would mark the terminal's `review` row done
+ *     while two lenses were still running.
+ *
+ *  2. **Per-agent action lists only.** The terminal's flat, arrival-ordered ring
+ *     buffer stays in `ActivityFeed`: it exists to fit pi's widget cap, which is
+ *     a property of that renderer rather than of the run. Keeping it there means
+ *     the panel's cross-lens interleaving is preserved by code that never moved.
+ */
+import type { ActivityLine, FeedStageId, JsonEvent, PipelineProgress, ReviewLens, StageTag, StopReason } from "./types.js";
+/** The fixed stage order shown by both surfaces (v1 stages + the post-loop FINISH row). */
+export declare const STAGE_ORDER: FeedStageId[];
+/**
+ * Per-agent action cap. Generous compared to the terminal's `MAX_VISIBLE_ACTIONS`
+ * because the desktop pane scrolls: the TUI's 4-row ceiling is a widget-height
+ * constraint, not a truth about how much happened.
+ */
+export declare const AGENT_ACTION_WINDOW = 40;
+export type AgentStatus = "pending" | "active" | "done" | "failed";
+export interface AgentAction {
+    toolCallId?: string;
+    text: string;
+    state: "running" | "done" | "error";
+}
+export interface AgentUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    turns: number;
+}
+export interface AgentNode {
+    /**
+     * Stable across paints: the stage id, `review:<lens>:r<round>` for a lens
+     * child, or `fix:r<round>` for a per-round fix execution.
+     */
+    id: string;
+    stageId: FeedStageId;
+    lens?: ReviewLens;
+    round?: number;
+    status: AgentStatus;
+    summary: string;
+    startedAt?: number;
+    endedAt?: number;
+    actions: AgentAction[];
+    usage: AgentUsage;
+    /** Per-lens finding counts, attached when the round's parse loop resolves this lens. */
+    findings?: number;
+    blocking?: number;
+    /** Why this lens could not fully carry the round (spec §3e). */
+    degraded?: "failed" | "unparseable";
+}
+/**
+ * One completed round's finding tally, kept as history rather than overwritten:
+ * the trajectory (blocking 6 → 5 → 5) is what tells whether the loop converged.
+ */
+export interface RoundTally {
+    round: number;
+    findings: number;
+    blocking: number;
+}
+/**
+ * The wire record. Deliberately carries NO local-only fields — no worktree paths,
+ * no pids, no absolute paths — so it stays portable to a non-local executor at
+ * zero cost. The tab does not need them.
+ */
+export interface GoRunState {
+    v: 1;
+    runId: string;
+    ticket: string;
+    round: number;
+    findingsTotal: number;
+    findingsBlocking: number;
+    rounds: RoundTally[];
+    startedAt: number;
+    endedAt?: number;
+    stopReason?: StopReason;
+    agents: AgentNode[];
+    /**
+     * The backend's run UUID (`handle.runId` from `POST /runs`, goCommand.ts's
+     * `openFreshRun`) — NOT `runId` above, which is the local 8-char short id
+     * (`runId.slice(0, 8)`) used for widget/status keys. `/api/yagni-code/spend`
+     * joins on the server UUID, so the desktop needs this to ever widen its
+     * spend query with a /go run's own dispatches. Absent until `openFreshRun`
+     * resolves (a beat after the run starts), and absent for good on an
+     * untracked run (flag off, unauthorized, or unreachable — see
+     * `UNTRACKED_NOTICE` in goCommand.ts): there is no server id to give it.
+     */
+    serverRunId?: string;
+}
+/**
+ * Stable agent id: a lens child is keyed by its lens AND round, and fix — the
+ * only lens-less stage that re-executes per round — by its round, so each
+ * round's fix keeps its own clock and usage instead of accumulating tokens on a
+ * timer that resets (the "181k tok in 59s" artifact). Review stage-level events
+ * stay on the bare `review` node: they mark the round boundary, and the lens
+ * children carry the round's real work.
+ */
+export declare function agentId(stageId: FeedStageId, lens?: ReviewLens, round?: number): string;
+export interface RunStateInit {
+    runId: string;
+    ticket: string;
+    startedAt: number;
+}
+export declare class RunState {
+    private readonly runId;
+    private readonly ticket;
+    private readonly startedAt;
+    private endedAt;
+    private stopReason;
+    private serverRunId;
+    private round;
+    private findingsTotal;
+    private findingsBlocking;
+    private readonly rounds;
+    private readonly agents;
+    constructor(init: RunStateInit);
+    /** The lens-less stage agent, or undefined for an unknown stage. */
+    private stageAgent;
+    /**
+     * The agent for a tag, created on demand. Lens children are inserted directly
+     * after their parent stage and any existing siblings, so the array order still
+     * reads top-to-bottom for the desktop and the lens-less filter still yields
+     * STAGE_ORDER for the terminal.
+     */
+    private ensureAgent;
+    /** Fold a structured progress signal. `at` is only read by the desktop surface. */
+    applyProgress(p: PipelineProgress, at?: number): void;
+    /**
+     * Fold one curated line. Narration becomes the emitting agent's summary;
+     * actions ride BOTH the agent's own list and the terminal's flat ring buffer.
+     */
+    applyLine(line: ActivityLine, tag: StageTag, at?: number): void;
+    /** Fold an assistant turn's usage into the emitting agent. Ignores everything else. */
+    applyUsage(ev: JsonEvent, tag: StageTag, at?: number): void;
+    /** Stamp the run's end. Separate from `done` because FINISH runs after the pipeline returns. */
+    markEnded(at: number): void;
+    /**
+     * Record the backend's run UUID once `openFreshRun` resolves (goCommand.ts,
+     * a beat after the run starts — never known at construction). The caller is
+     * responsible for repainting immediately after this so the desktop learns
+     * it as soon as possible rather than on the next debounced paint.
+     */
+    setServerRunId(id: string): void;
+    /**
+     * Stage rows for the panel: one row per stage, in order. Lens children are the
+     * desktop's business alone, and a looped stage that re-executes per round
+     * (fix) paints its LATEST round's node so the row shows the live execution,
+     * not a stale bare placeholder.
+     */
+    stageAgents(): AgentNode[];
+    header(): {
+        ticket: string;
+        round: number;
+        findingsTotal: number;
+        findingsBlocking: number;
+    };
+    /** Named `toJSON` so `JSON.stringify(run)` yields the wire shape directly. */
+    toJSON(): GoRunState;
+}
+//# sourceMappingURL=runState.d.ts.map