@yagni-app/code 0.1.0 → 0.2.0

package/dist/extension/sessionRuns.d.ts

@@ -0,0 +1,45 @@
+/**
+ * YAG-383: tracks the `/go` run ids a driver session has launched, so /cost's
+ * server-authoritative spend fetch can widen its query to include them.
+ *
+ * The backend writes a run-attributed dispatch's `llm_usage.session_id` as
+ * the RUN id, not the driver session id (see attributionHeaders in
+ * config.ts: a `/go` child's completions carry `x-yagni-run-id`, and the
+ * proxy stores THAT in `session_id` — the run id wins, by design, so a
+ * per-run query works on its own). A plain `GET /api/yagni-code/spend?
+ * sessionId=<driver>` therefore never sees a single `/go` run's spend: it is
+ * real spend, billed under this session's work, but invisible to that query.
+ * `/cost` (index.ts's `fetchSpend`) closes that gap by also asking for every
+ * run id this process has launched, via `runIds=`.
+ *
+ * Module-level state is the right shape here: one CLI process IS one driver
+ * session, so "run ids this process has launched" and "run ids this session
+ * has launched" are the same list. Capped at the most recent
+ * `MAX_TRACKED_RUN_IDS` so an extremely long-lived session's /cost call never
+ * grows an unbounded query string (the backend independently caps `runIds` at
+ * the same number — see MAX_SPEND_RUN_IDS in routes/yagniCode.ts — capping
+ * symmetrically here keeps a stable, useful most-recent set instead of
+ * trailing off into a 400 from the server).
+ */
+/**
+ * Record a `/go` run id once it is known (the goCommand.ts seam right after
+ * `runSession.start()` resolves). Ignores anything that is not UUID-shaped
+ * and de-dupes a repeat call for the same run (a resumed/re-adopted run can
+ * report the same id twice) — both defensive, since a malformed value here
+ * must never corrupt /cost's query string.
+ */
+export declare function recordSessionRun(runId: string): void;
+/** The run ids recorded so far this process, oldest first, capped. */
+export declare function sessionRunIds(): string[];
+/**
+ * How many run ids this session has ever dropped off the front of the
+ * `MAX_TRACKED_RUN_IDS` cap. Zero for the overwhelming majority of sessions
+ * (20 `/go` runs in one process is a lot); /cost's server rendering
+ * (costHud.ts's `formatServerCostLines`) surfaces this as an "Excludes N
+ * earlier /go runs." note when it is nonzero, so a long session's spend total
+ * is never silently missing runs with no explanation.
+ */
+export declare function droppedSessionRuns(): number;
+/** Test-only reset: module-level state otherwise leaks across test files/cases. */
+export declare function _resetSessionRunsForTest(): void;
+//# sourceMappingURL=sessionRuns.d.ts.map

package/dist/extension/sessionRuns.js

@@ -0,0 +1,77 @@
+/**
+ * YAG-383: tracks the `/go` run ids a driver session has launched, so /cost's
+ * server-authoritative spend fetch can widen its query to include them.
+ *
+ * The backend writes a run-attributed dispatch's `llm_usage.session_id` as
+ * the RUN id, not the driver session id (see attributionHeaders in
+ * config.ts: a `/go` child's completions carry `x-yagni-run-id`, and the
+ * proxy stores THAT in `session_id` — the run id wins, by design, so a
+ * per-run query works on its own). A plain `GET /api/yagni-code/spend?
+ * sessionId=<driver>` therefore never sees a single `/go` run's spend: it is
+ * real spend, billed under this session's work, but invisible to that query.
+ * `/cost` (index.ts's `fetchSpend`) closes that gap by also asking for every
+ * run id this process has launched, via `runIds=`.
+ *
+ * Module-level state is the right shape here: one CLI process IS one driver
+ * session, so "run ids this process has launched" and "run ids this session
+ * has launched" are the same list. Capped at the most recent
+ * `MAX_TRACKED_RUN_IDS` so an extremely long-lived session's /cost call never
+ * grows an unbounded query string (the backend independently caps `runIds` at
+ * the same number — see MAX_SPEND_RUN_IDS in routes/yagniCode.ts — capping
+ * symmetrically here keeps a stable, useful most-recent set instead of
+ * trailing off into a 400 from the server).
+ */
+const MAX_TRACKED_RUN_IDS = 20;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+let runIds = [];
+/**
+ * Count of run ids ever pushed off the front of `runIds` by the
+ * `MAX_TRACKED_RUN_IDS` cap below. Carry-over from the /cost re-review: a
+ * long-lived session that launches more than 20 `/go` runs silently lost the
+ * oldest ones from /cost's `runIds=` widening, with no indication that
+ * anything was left out — an honesty gap identical in spirit to
+ * `counterfactualIncomplete` / `unbilledSellMillicents` elsewhere in this
+ * surface. Tracked here (not derived) because the dropped ids themselves are
+ * gone — only the count survives.
+ */
+let dropped = 0;
+/**
+ * Record a `/go` run id once it is known (the goCommand.ts seam right after
+ * `runSession.start()` resolves). Ignores anything that is not UUID-shaped
+ * and de-dupes a repeat call for the same run (a resumed/re-adopted run can
+ * report the same id twice) — both defensive, since a malformed value here
+ * must never corrupt /cost's query string.
+ */
+export function recordSessionRun(runId) {
+    if (!UUID_RE.test(runId))
+        return;
+    if (runIds.includes(runId))
+        return;
+    runIds.push(runId);
+    if (runIds.length > MAX_TRACKED_RUN_IDS) {
+        const overflow = runIds.length - MAX_TRACKED_RUN_IDS;
+        dropped += overflow;
+        runIds = runIds.slice(overflow);
+    }
+}
+/** The run ids recorded so far this process, oldest first, capped. */
+export function sessionRunIds() {
+    return [...runIds];
+}
+/**
+ * How many run ids this session has ever dropped off the front of the
+ * `MAX_TRACKED_RUN_IDS` cap. Zero for the overwhelming majority of sessions
+ * (20 `/go` runs in one process is a lot); /cost's server rendering
+ * (costHud.ts's `formatServerCostLines`) surfaces this as an "Excludes N
+ * earlier /go runs." note when it is nonzero, so a long session's spend total
+ * is never silently missing runs with no explanation.
+ */
+export function droppedSessionRuns() {
+    return dropped;
+}
+/** Test-only reset: module-level state otherwise leaks across test files/cases. */
+export function _resetSessionRunsForTest() {
+    runIds = [];
+    dropped = 0;
+}
+//# sourceMappingURL=sessionRuns.js.map

package/dist/extension/spool.d.ts

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

package/dist/extension/spool.js

@@ -0,0 +1,266 @@
+/**
+ * Durable write-spool for the judgment-capture tools (spec §4, R4 write half).
+ *
+ * `record_decision` and `record_engineering_context` are metered writes that
+ * must never be blindly retried (invariant §0.8) — but losing a captured
+ * decision because the laptop lost Wi-Fi is worse. The backend now dedups on
+ * an `idempotencyKey` (§2), so the safe shape is:
+ *
+ *  - every logical write carries a generated idempotencyKey,
+ *  - a transport failure or 5xx appends `{endpoint, body, idempotencyKey, ts}`
+ *    to `~/.yagni-code/spool/pending.ndjson` (dir 0700, file 0600,
+ *    torn-line-tolerant — the same self-healing NDJSON pattern as
+ *    pipeline/checkpoint.ts),
+ *  - the spool is flushed at session_start and after any successful write,
+ *    replaying with the SAME idempotencyKey (the server replays the stored
+ *    response, so a duplicate flush is harmless),
+ *  - entries older than 14 days are dropped with an honest notice (stale
+ *    judgment silently landing weeks later would be worse than losing it).
+ *
+ * Everything here is FAIL-SOFT: a spool problem must never break a tool call
+ * or session start. Eval mode never reaches this module (the capture tools are
+ * not registered there).
+ */
+import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+import { codeStateHome } from "./stateHome.js";
+/** Spooled entries older than this are dropped at flush (with a notice). */
+export const MAX_SPOOL_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+/**
+ * Test seam mirroring checkpoint.ts `_setCheckpointHomeForTest`: when set, the
+ * spool roots here instead of `~/.yagni-code`. Pass `null` to restore.
+ */
+let homeOverride = null;
+export function _setSpoolHomeForTest(dir) {
+    homeOverride = dir;
+}
+function spoolHome() {
+    return codeStateHome(homeOverride);
+}
+function spoolDir() {
+    return join(spoolHome(), "spool");
+}
+/** The on-disk pending file (exported so tests can inspect it directly). */
+export function spoolFile() {
+    return join(spoolDir(), "pending.ndjson");
+}
+/** Append one pending write. NEVER throws (fail-soft: memory loss beats a crash). */
+export function appendToSpool(entry) {
+    try {
+        mkdirSync(spoolDir(), { recursive: true, mode: 0o700 });
+        const file = spoolFile();
+        // Self-heal a torn previous write (crash mid-append): if the file ends
+        // mid-line, prefix a newline so OUR record lands on its own line instead of
+        // gluing onto the fragment and losing both (mirrors checkpoint.ts).
+        let prefix = "";
+        try {
+            const existing = readFileSync(file);
+            if (existing.length > 0 && existing[existing.length - 1] !== 0x0a)
+                prefix = "\n";
+        }
+        catch {
+            /* no file yet — nothing to heal */
+        }
+        appendFileSync(file, `${prefix}${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    }
+    catch {
+        /* fail-soft: a spool write must never break the tool call */
+    }
+}
+function isSpoolEntry(value) {
+    const e = value;
+    return (!!e &&
+        typeof e === "object" &&
+        typeof e.endpoint === "string" &&
+        e.endpoint.startsWith("/") &&
+        !!e.body &&
+        typeof e.body === "object" &&
+        typeof e.idempotencyKey === "string" &&
+        typeof e.ts === "number");
+}
+/** Load pending entries, dropping torn/garbage lines. Never throws. */
+export function loadSpool() {
+    try {
+        const raw = readFileSync(spoolFile(), "utf8");
+        const out = [];
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                if (isSpoolEntry(obj))
+                    out.push(obj);
+            }
+            catch {
+                /* unparseable (torn final write) — drop this line, keep the rest */
+            }
+        }
+        return out;
+    }
+    catch {
+        return []; // missing/unreadable → nothing pending
+    }
+}
+/** Atomically rewrite the pending file with the surviving entries (0600). */
+function rewriteSpool(entries) {
+    try {
+        const file = spoolFile();
+        if (entries.length === 0) {
+            rmSync(file, { force: true });
+            return;
+        }
+        mkdirSync(spoolDir(), { recursive: true, mode: 0o700 });
+        const tmp = join(spoolDir(), `.pending-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}.tmp`);
+        writeFileSync(tmp, entries.map((e) => JSON.stringify(e)).join("\n") + "\n", { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    catch {
+        /* fail-soft: worst case the next flush replays an already-deduped key */
+    }
+}
+const EMPTY_FLUSH = {
+    replayed: 0,
+    droppedExpired: 0,
+    droppedRejected: 0,
+    remaining: 0,
+    notices: [],
+};
+function plural(n) {
+    return n === 1 ? "" : "s";
+}
+let flushInFlight = null;
+/**
+ * Replay every pending write with its ORIGINAL idempotencyKey (server-side
+ * dedup makes a double replay a no-op). Serialized: concurrent flushes (a
+ * session_start racing a post-write flush) coalesce onto one pass.
+ *
+ * Per entry: expired (>14d) → dropped with a notice; 2xx → replayed; a
+ * permanent 4xx (not auth/rate) → dropped with a notice (the backend will
+ * never accept it); transport error, 5xx, 401/403/408/429 → kept, and the
+ * rest of the flush stops (the backend is unreachable or the token is bad —
+ * hammering the remaining entries would not help). Never throws.
+ */
+export function flushSpool(opts) {
+    if (!flushInFlight) {
+        flushInFlight = doFlush(opts)
+            .catch(() => EMPTY_FLUSH)
+            .finally(() => {
+            flushInFlight = null;
+        });
+    }
+    return flushInFlight;
+}
+/** Statuses that mean "try again later", not "the backend rejected this body". */
+const KEEP_STATUSES = new Set([401, 403, 408, 429]);
+async function doFlush(opts) {
+    const entries = loadSpool();
+    if (entries.length === 0)
+        return EMPTY_FLUSH;
+    const nowMs = (opts.now ?? Date.now)();
+    // Keys we have RESOLVED this pass (replayed OK, or permanently dropped). We do
+    // NOT rewrite from this stale snapshot — instead we re-read the current spool
+    // just before writing and drop only these resolved keys, so a write appended
+    // mid-flush (a tool that failed while we were replaying) is never clobbered.
+    const resolved = new Set();
+    let replayed = 0;
+    let droppedExpired = 0;
+    let droppedRejected = 0;
+    let stopped = false;
+    for (const entry of entries) {
+        if (nowMs - entry.ts > MAX_SPOOL_AGE_MS) {
+            droppedExpired += 1;
+            resolved.add(entry.idempotencyKey);
+            continue;
+        }
+        if (stopped)
+            continue;
+        try {
+            const res = await resilientFetch(`${opts.baseUrl}${entry.endpoint}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${opts.getToken() ?? ""}`,
+                },
+                // Replay verbatim; re-assert the key in case an old entry predates it.
+                body: JSON.stringify({ ...entry.body, idempotencyKey: entry.idempotencyKey }),
+            }, { fetchImpl: opts.fetchImpl, policy: METERED_POST_FETCH_POLICY });
+            if (res.ok) {
+                replayed += 1;
+                resolved.add(entry.idempotencyKey);
+            }
+            else if (res.status >= 500 || KEEP_STATUSES.has(res.status)) {
+                stopped = true;
+            }
+            else {
+                droppedRejected += 1;
+                resolved.add(entry.idempotencyKey);
+            }
+        }
+        catch {
+            stopped = true;
+        }
+    }
+    // Re-read + filter + rewrite are back-to-back synchronous calls with no await
+    // between them, so no append can interleave in that window (single-threaded).
+    // Everything not resolved this pass — kept entries AND any mid-flush append —
+    // survives. A re-appended duplicate of a replayed key is harmless (the server
+    // dedups on idempotencyKey; it just replays next pass).
+    const keep = loadSpool().filter((e) => !resolved.has(e.idempotencyKey));
+    rewriteSpool(keep);
+    const notices = [];
+    if (replayed > 0) {
+        notices.push(`Replayed ${replayed} locally spooled YAGNI record${plural(replayed)}.`);
+    }
+    if (droppedExpired > 0) {
+        notices.push(`Dropped ${droppedExpired} unsent YAGNI record${plural(droppedExpired)} older than 14 days from the local spool.`);
+    }
+    if (droppedRejected > 0) {
+        notices.push(`Discarded ${droppedRejected} spooled YAGNI record${plural(droppedRejected)} the backend rejected.`);
+    }
+    return { replayed, droppedExpired, droppedRejected, remaining: keep.length, notices };
+    // (keep.length reflects the post-rewrite spool, including any mid-flush append.)
+}
+/**
+ * POST one judgment write with its idempotencyKey; on transport failure or a
+ * 5xx, durably spool it for replay instead of losing it. A successful write
+ * also kicks a background flush (fail-soft, fire-and-forget) so earlier
+ * stranded entries drain as soon as the backend is healthy again.
+ */
+export async function sendOrSpool(opts, label, endpoint, body, idempotencyKey, signal) {
+    const posted = { ...body, idempotencyKey };
+    let res;
+    try {
+        res = await resilientFetch(`${opts.baseUrl}${endpoint}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+            },
+            body: JSON.stringify(posted),
+        }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        appendToSpool({ endpoint, body: posted, idempotencyKey, ts: (opts.now ?? Date.now)() });
+        return { kind: "spooled", reason };
+    }
+    if (res.ok) {
+        // Success proves the backend is reachable: drain anything stranded earlier.
+        void flushSpool(opts).catch(() => { });
+        let json = null;
+        try {
+            json = await res.json();
+        }
+        catch {
+            /* a 2xx with a non-JSON body still counts as recorded */
+        }
+        return { kind: "ok", json };
+    }
+    if (res.status >= 500) {
+        appendToSpool({ endpoint, body: posted, idempotencyKey, ts: (opts.now ?? Date.now)() });
+        return { kind: "spooled", reason: `the YAGNI backend returned HTTP ${res.status}` };
+    }
+    return { kind: "rejected", message: await friendlyFetchError(label, res) };
+}
+//# sourceMappingURL=spool.js.map

package/dist/extension/stateHome.d.ts

@@ -0,0 +1,2 @@
+export declare function codeStateHome(override: string | null, env?: NodeJS.ProcessEnv, userHome?: string): string;
+//# sourceMappingURL=stateHome.d.ts.map

package/dist/extension/stateHome.js

@@ -0,0 +1,6 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function codeStateHome(override, env = process.env, userHome = homedir()) {
+    return override ?? env.YAGNI_CODE_HOME ?? join(userHome, ".yagni-code");
+}
+//# sourceMappingURL=stateHome.js.map

package/dist/extension/subagents.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The general `subagent` tool — delegate a self-contained task to an agent
+ * with its own fresh context window, optionally in parallel.
+ *
+ * Reuses the /go pipeline's battle-tested child runner (`runStage`: NDJSON
+ * stream folding, output caps, abort escalation) through its `personaBody`
+ * seam, so a subagent is exactly a grounded pi child whose system prompt is
+ * the agent definition's body instead of a /go persona.
+ *
+ * Agent definitions are the Claude Code format — markdown with
+ * name/description/tools/model frontmatter — discovered from the repo's
+ * `.claude/agents/` and `.pi/agents/`, the user's `~/.claude/agents/`, and
+ * any Claude Code plugin `agents/` dirs the launcher passed via
+ * `YAGNI_CLAUDE_AGENT_DIRS` (project beats user beats plugin on a name
+ * collision). A built-in `general` agent is always available, so the tool
+ * works in a repo with no definitions at all.
+ * Claude model names map onto YAGNI tiers (opus→advanced, sonnet→standard,
+ * haiku→efficient); unknown models run on standard.
+ */
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { runStage } from "./pipeline/runner.js";
+import type { ModelTier, PipelineStage } from "./pipeline/types.js";
+export declare const SUBAGENT_TOOL_NAME = "subagent";
+export declare const GENERAL_AGENT_NAME = "general";
+export declare const MAX_PARALLEL_SUBAGENTS = 4;
+/**
+ * The default tool surface a subagent gets when its definition declares none:
+ * the full working set plus grounded answers, mirroring what a Claude Code
+ * subagent would inherit.
+ */
+export declare const DEFAULT_SUBAGENT_TOOLS: string[];
+export type SubagentSource = "project-claude" | "project-pi" | "user-claude" | "plugin" | "builtin";
+/**
+ * Claude Code plugin `agents/` dirs, delimiter-joined by the yagni launcher
+ * (see yagni-code-cli claudeCompat.ts — trust gating happens there).
+ */
+export declare const CLAUDE_AGENT_DIRS_ENV = "YAGNI_CLAUDE_AGENT_DIRS";
+export interface SubagentDef {
+    name: string;
+    description: string;
+    tools?: string[];
+    model: ModelTier;
+    /** The agent's system prompt (the markdown body). */
+    body: string;
+    source: SubagentSource;
+}
+/** Claude Code model names → YAGNI tiers; YAGNI tiers pass through. */
+export declare function mapModelTier(model: string | undefined): ModelTier;
+/**
+ * Parse one Claude Code-format agent file. Returns null when the file has no
+ * description — the one field the tool cannot do without (the model picks
+ * agents by it).
+ */
+export declare function parseAgentMarkdown(content: string, fallbackName: string, source: SubagentSource): SubagentDef | null;
+export interface DiscoverDeps {
+    cwd: string;
+    homeDir?: string;
+    /** Env seam for the plugin agent dirs (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * All available agents: built-in general, then Claude Code plugin `agents/`
+ * dirs (launcher-provided), then user `~/.claude/agents`, then the repo's
+ * `.pi/agents` and `.claude/agents` — later wins on a name collision, so a
+ * project definition beats a user one beats a plugin one beats the built-in.
+ */
+export declare function discoverSubagents(deps: DiscoverDeps): SubagentDef[];
+export declare function formatAgentList(agents: SubagentDef[]): string;
+/**
+ * A subagent invocation is a synthetic pipeline stage: the task rides in as
+ * `{ticket}` verbatim, and the agent's body replaces the /go persona through
+ * the runner's personaBody seam.
+ */
+export declare function buildSubagentStage(def: SubagentDef, task: string): {
+    stage: PipelineStage;
+    ctx: {
+        ticket: string;
+        grounded: boolean;
+    };
+};
+type SubagentParams = {
+    task?: string;
+    agent?: string;
+    tasks?: Array<{
+        task: string;
+        agent?: string;
+    }>;
+};
+export interface MakeSubagentToolDeps {
+    runStageImpl?: typeof runStage;
+    discover?: (deps: DiscoverDeps) => SubagentDef[];
+    homeDir?: string;
+}
+export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    parameters: Type.TObject<{
+        task: Type.TOptional<Type.TString>;
+        agent: Type.TOptional<Type.TString>;
+        tasks: Type.TOptional<Type.TArray<Type.TObject<{
+            task: Type.TString;
+            agent: Type.TOptional<Type.TString>;
+        }>>>;
+    }>;
+    execute(_toolCallId: string, params: SubagentParams, signal?: AbortSignal, onUpdate?: (update: {
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: unknown;
+    }) => void, ctx?: ExtensionContext): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {};
+        isError: boolean;
+    } | {
+        isError?: boolean | undefined;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            tasks: {
+                agent: string;
+                task: string;
+                exitCode: number;
+                usage: import("./pipeline/types.js").StageUsage;
+                toolCalls: number;
+            }[];
+        };
+    }>;
+};
+export interface RegisterSubagentsDeps {
+    discover?: (deps: DiscoverDeps) => SubagentDef[];
+    homeDir?: string;
+}
+/** Wire the subagent tool and the /agents listing command. */
+export declare function registerSubagents(pi: ExtensionAPI, deps?: RegisterSubagentsDeps): void;
+export {};
+//# sourceMappingURL=subagents.d.ts.map