@yagni-app/code 0.1.0 → 0.2.0

package/dist/extension/subagents.js

@@ -0,0 +1,326 @@
+/**
+ * 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 * as fs from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { sanitizeCallerSegment } from "./config.js";
+import { runStage } from "./pipeline/runner.js";
+/**
+ * YAG-471 attribution: the `x-yagni-caller` prefix for a subagent invocation.
+ * The sanitized agent name is capped so the WHOLE label (prefix + name) stays
+ * within the model proxy's 64-char caller-label limit.
+ */
+const SUBAGENT_CALLER_PREFIX = "subagent:";
+export const SUBAGENT_TOOL_NAME = "subagent";
+export const GENERAL_AGENT_NAME = "general";
+export 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 const DEFAULT_SUBAGENT_TOOLS = [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "ask_yagni",
+];
+/**
+ * Claude Code plugin `agents/` dirs, delimiter-joined by the yagni launcher
+ * (see yagni-code-cli claudeCompat.ts — trust gating happens there).
+ */
+export const CLAUDE_AGENT_DIRS_ENV = "YAGNI_CLAUDE_AGENT_DIRS";
+const CLAUDE_COMPAT_DISABLE_ENV = "YAGNI_DISABLE_CLAUDE_COMPAT";
+function pluginAgentDirs(env) {
+    const disabled = env[CLAUDE_COMPAT_DISABLE_ENV];
+    if (disabled !== undefined && disabled !== "" && disabled !== "0")
+        return [];
+    const raw = env[CLAUDE_AGENT_DIRS_ENV];
+    if (!raw)
+        return [];
+    return raw.split(delimiter).filter(Boolean);
+}
+const GENERAL_BODY = `You are a capable software-engineering subagent with a fresh context window. Complete the task you are given end to end, autonomously.
+
+You are grounded in how THIS company works: call ask_yagni before inferring a convention, an ownership rule, or anything organization-specific.
+
+Your final message is your report back to the driving agent, which has NOT seen what you read or did. Make it compressed and complete: what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
+const GENERAL_AGENT = {
+    name: GENERAL_AGENT_NAME,
+    description: "General-purpose agent for research, multi-file changes, and self-contained tasks.",
+    model: "standard",
+    body: GENERAL_BODY,
+    source: "builtin",
+};
+// Concrete tiers a subagent can actually run on. `balanced` is deliberately NOT
+// a member here even though it is a member of `ModelTier`: a subagent needs
+// ONE model for its whole run, and balanced is a session-level routing policy,
+// not a rung — see mapModelTier's explicit branch below.
+const TIER_VALUES = ["peak", "advanced", "standard", "efficient"];
+/** Claude Code model names → YAGNI tiers; YAGNI tiers pass through. */
+export function mapModelTier(model) {
+    if (!model)
+        return "standard";
+    const normalized = model.trim().toLowerCase();
+    if (TIER_VALUES.includes(normalized))
+        return normalized;
+    // `balanced` names a SESSION routing policy, not a tier a subagent can run
+    // on. Handled explicitly rather than falling through to the catch-all
+    // below, so frontmatter that names the policy reads as an intentional
+    // "router-decide" choice, not an unrecognized string: it lands on the
+    // built-in default lane (standard) — the session-level policy (driver
+    // turns) owns balanced's resolution; this is just a safe landing spot for
+    // frontmatter that names it.
+    if (normalized === "balanced")
+        return "standard";
+    if (normalized.includes("opus"))
+        return "advanced";
+    if (normalized.includes("sonnet"))
+        return "standard";
+    if (normalized.includes("haiku"))
+        return "efficient";
+    return "standard";
+}
+/**
+ * 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 function parseAgentMarkdown(content, fallbackName, source) {
+    const { frontmatter, body } = parseFrontmatter(content);
+    const description = frontmatter.description?.trim();
+    if (!description)
+        return null;
+    const tools = frontmatter.tools
+        ?.split(",")
+        .map((t) => t.trim())
+        .filter(Boolean);
+    return {
+        name: (frontmatter.name?.trim() || fallbackName).toLowerCase(),
+        description,
+        tools: tools && tools.length > 0 ? tools : undefined,
+        model: mapModelTier(frontmatter.model),
+        body: body.trim() || GENERAL_BODY,
+        source,
+    };
+}
+function loadAgentsFromDir(dir, source) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const agents = [];
+    for (const entry of entries) {
+        if (!entry.name.endsWith(".md"))
+            continue;
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            continue;
+        try {
+            const content = fs.readFileSync(join(dir, entry.name), "utf8");
+            const def = parseAgentMarkdown(content, entry.name.replace(/\.md$/, ""), source);
+            if (def)
+                agents.push(def);
+        }
+        catch {
+            continue;
+        }
+    }
+    return agents;
+}
+/**
+ * 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 function discoverSubagents(deps) {
+    const home = deps.homeDir ?? homedir();
+    const layers = [
+        [GENERAL_AGENT],
+        ...pluginAgentDirs(deps.env ?? process.env).map((dir) => loadAgentsFromDir(dir, "plugin")),
+        loadAgentsFromDir(join(home, ".claude", "agents"), "user-claude"),
+        loadAgentsFromDir(join(deps.cwd, ".pi", "agents"), "project-pi"),
+        loadAgentsFromDir(join(deps.cwd, ".claude", "agents"), "project-claude"),
+    ];
+    const byName = new Map();
+    for (const layer of layers) {
+        for (const agent of layer)
+            byName.set(agent.name, agent);
+    }
+    return [...byName.values()];
+}
+const SOURCE_LABEL = {
+    builtin: "built-in",
+    plugin: "claude plugin",
+    "user-claude": "~/.claude/agents",
+    "project-pi": ".pi/agents",
+    "project-claude": ".claude/agents",
+};
+export function formatAgentList(agents) {
+    return agents
+        .map((a) => `${a.name} (${SOURCE_LABEL[a.source]}): ${a.description}`)
+        .join("\n");
+}
+/**
+ * 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 function buildSubagentStage(def, task) {
+    return {
+        stage: {
+            id: "implement",
+            agent: def.name,
+            model: def.model,
+            tools: def.tools ?? DEFAULT_SUBAGENT_TOOLS,
+            taskTemplate: "{ticket}",
+        },
+        ctx: { ticket: task, grounded: true },
+    };
+}
+const parameters = Type.Object({
+    task: Type.Optional(Type.String({
+        description: "The self-contained task. Include everything needed: the subagent shares none of your context.",
+    })),
+    agent: Type.Optional(Type.String({ description: "Agent name (see /agents). Defaults to general." })),
+    tasks: Type.Optional(Type.Array(Type.Object({
+        task: Type.String(),
+        agent: Type.Optional(Type.String()),
+    }), {
+        description: `Run several independent tasks in parallel (max ${MAX_PARALLEL_SUBAGENTS}). Use INSTEAD of task.`,
+    })),
+});
+export function makeSubagentTool(deps = {}) {
+    const run = deps.runStageImpl ?? runStage;
+    const discover = deps.discover ?? discoverSubagents;
+    return {
+        name: SUBAGENT_TOOL_NAME,
+        label: "Subagent",
+        description: "Delegate a self-contained task to a subagent with its own fresh context window, and get back " +
+            "a compressed report. Use it for context-heavy exploration you don't need blow-by-blow, or to " +
+            "run independent tasks in parallel via `tasks`. The subagent shares NONE of your conversation: " +
+            "spell out the task completely. Agents come from this repo's .claude/agents and .pi/agents " +
+            "(list them with /agents); omit `agent` for the general-purpose one.",
+        promptSnippet: "subagent: delegate a self-contained task (or parallel tasks) to a fresh-context agent; returns its report.",
+        parameters,
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            const fail = (text) => ({
+                content: [{ type: "text", text }],
+                details: {},
+                isError: true,
+            });
+            const requested = params.tasks && params.tasks.length > 0
+                ? params.tasks
+                : params.task
+                    ? [{ task: params.task, agent: params.agent }]
+                    : [];
+            if (requested.length === 0) {
+                return fail("Error: pass `task` (or a `tasks` array) describing what to do.");
+            }
+            if (requested.length > MAX_PARALLEL_SUBAGENTS) {
+                return fail(`Error: at most ${MAX_PARALLEL_SUBAGENTS} parallel tasks per call.`);
+            }
+            const cwd = ctx?.cwd ?? process.cwd();
+            const agents = discover({ cwd, homeDir: deps.homeDir });
+            const resolved = [];
+            for (const req of requested) {
+                const name = (req.agent ?? GENERAL_AGENT_NAME).toLowerCase();
+                const def = agents.find((a) => a.name === name);
+                if (!def) {
+                    return fail(`Error: unknown agent "${name}". Available agents:\n${formatAgentList(agents)}`);
+                }
+                resolved.push({ def, task: req.task });
+            }
+            onUpdate?.({
+                content: [
+                    {
+                        type: "text",
+                        text: resolved.length === 1
+                            ? `Running ${resolved[0].def.name} subagent…`
+                            : `Running ${resolved.length} subagents in parallel…`,
+                    },
+                ],
+                details: {},
+            });
+            const outcomes = await Promise.all(resolved.map(async ({ def, task }) => {
+                const { stage, ctx: stageCtx } = buildSubagentStage(def, task);
+                const result = await run(stage, stageCtx, {
+                    cwd,
+                    signal,
+                    personaBody: () => def.body,
+                    // YAG-471: attribute this child's completions to the specific
+                    // subagent, not the generic /go stage label the runner would
+                    // otherwise derive from stage.id ("implement", reused as the
+                    // synthetic subagent stage — see buildSubagentStage).
+                    callerLabel: `${SUBAGENT_CALLER_PREFIX}${sanitizeCallerSegment(def.name, 64 - SUBAGENT_CALLER_PREFIX.length)}`,
+                });
+                return { agent: def.name, task, result };
+            }));
+            const allFailed = outcomes.every((o) => o.result.exitCode !== 0);
+            const sections = outcomes.map((o) => {
+                const output = o.result.finalOutput.trim();
+                const failedNote = o.result.exitCode !== 0
+                    ? `\n\n(subagent failed, exit ${o.result.exitCode}${o.result.stderr.trim() ? `: ${o.result.stderr.trim().slice(-500)}` : ""})`
+                    : "";
+                const bodyText = output || (o.result.exitCode === 0 ? "(no output)" : "");
+                return outcomes.length === 1
+                    ? `${bodyText}${failedNote}`
+                    : `## ${o.agent}: ${o.task}\n\n${bodyText}${failedNote}`;
+            });
+            return {
+                content: [{ type: "text", text: sections.join("\n\n") }],
+                details: {
+                    tasks: outcomes.map((o) => ({
+                        agent: o.agent,
+                        task: o.task,
+                        exitCode: o.result.exitCode,
+                        usage: o.result.usage,
+                        toolCalls: o.result.toolCalls,
+                    })),
+                },
+                ...(allFailed ? { isError: true } : {}),
+            };
+        },
+    };
+}
+/** Wire the subagent tool and the /agents listing command. */
+export function registerSubagents(pi, deps = {}) {
+    const discover = deps.discover ?? discoverSubagents;
+    pi.registerTool(makeSubagentTool(deps));
+    pi.registerCommand("agents", {
+        description: "List the subagents available in this repo (.claude/agents, .pi/agents).",
+        handler: async (_args, ctx) => {
+            if (!ctx.hasUI)
+                return;
+            const agents = discover({ cwd: ctx.cwd ?? process.cwd(), homeDir: deps.homeDir });
+            ctx.ui.notify(`Available subagents:\n${formatAgentList(agents)}`, "info");
+        },
+    });
+}
+//# sourceMappingURL=subagents.js.map

package/dist/extension/surface.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Which surface this process is painting for. The desktop driver sets
+ * YAGNI_SURFACE=desktop; the terminal CLI sets nothing. The two renderers are
+ * mutually exclusive: a desktop session never receives ANSI, which is why the
+ * escape-code leak is fixed by construction rather than stripped downstream.
+ * Desktop-facing widgets are structured single-line JSON records the app
+ * parses, not themed terminal lines.
+ */
+export declare function isDesktopSurface(): boolean;
+//# sourceMappingURL=surface.d.ts.map

package/dist/extension/surface.js

@@ -0,0 +1,12 @@
+/**
+ * Which surface this process is painting for. The desktop driver sets
+ * YAGNI_SURFACE=desktop; the terminal CLI sets nothing. The two renderers are
+ * mutually exclusive: a desktop session never receives ANSI, which is why the
+ * escape-code leak is fixed by construction rather than stripped downstream.
+ * Desktop-facing widgets are structured single-line JSON records the app
+ * parses, not themed terminal lines.
+ */
+export function isDesktopSurface() {
+    return process.env.YAGNI_SURFACE === "desktop";
+}
+//# sourceMappingURL=surface.js.map

package/dist/extension/todos.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The session todo list — the visible checklist for multi-step work.
+ *
+ * A `todo_write` tool the model calls with the FULL list every time (replace,
+ * not patch: replacement is idempotent under retries and always renders a
+ * coherent board), a persistent above-editor widget while steps remain open,
+ * and a `/todos` command to pull the list on demand.
+ *
+ * State follows pi's branching model the same way the session does: the
+ * canonical list is the LAST `todo_write` tool result on the current branch,
+ * reconstructed on session_start/session_tree, so forking or rewinding a
+ * session automatically shows the list as it stood at that point. The
+ * in-memory copy is just a cache of that.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+export declare const TODO_TOOL_NAME = "todo_write";
+export declare const MAX_TODOS = 50;
+export declare const MAX_TODO_TEXT = 300;
+/**
+ * The desktop's structured state record rides its own widget key, like the
+ * `/go` run state: one JSON line the app parses and renders itself, never
+ * themed terminal lines. The desktop shell hand-declares the matching parser
+ * (`parseTodoState` in its piProtocol.ts); a key-set assertion in
+ * todos.test.ts guards the two against drift.
+ */
+export declare const TODO_STATE_KEY = "yagni-todos:state";
+export type TodoStatus = "pending" | "in_progress" | "completed";
+export interface TodoItem {
+    text: string;
+    status: TodoStatus;
+}
+/**
+ * Validate a full replacement list. Strict: this is model input rendered
+ * straight into the terminal. An empty list is valid (it clears the board).
+ */
+export declare function normalizeTodos(raw: unknown): {
+    ok: true;
+    todos: TodoItem[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function todoSummary(todos: TodoItem[]): {
+    done: number;
+    total: number;
+    active: string | null;
+};
+/** Plain-text checklist (tool results, /todos in headless contexts). */
+export declare function formatTodoList(todos: TodoItem[]): string;
+/** The slice of pi's Theme the widget styles with (matches the feed's pattern). */
+export interface TodoTheme {
+    fg(color: string, s: string): string;
+    strikethrough?(s: string): string;
+}
+/**
+ * The above-editor checklist. Empty (paint nothing) when there is no list or
+ * every step is completed — a finished board should leave the screen. Capped
+ * so header + items + overflow stays under pi's 10-line widget truncation.
+ */
+export declare function renderTodoWidget(todos: TodoItem[], theme: TodoTheme): string[];
+/** The desktop state record: exactly one JSON line under TODO_STATE_KEY. */
+export declare function todoStateLine(todos: TodoItem[]): string;
+/** Replay the branch: the last todo_write result is the canonical list. */
+export declare function reconstructTodos(entries: unknown[]): TodoItem[];
+type TodoParams = {
+    todos: Array<{
+        text: string;
+        status: string;
+    }>;
+};
+/**
+ * Build the todo_write tool definition around a shared store. Separated from
+ * registration so tests can drive execute directly.
+ */
+export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoItem[]) => void): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    parameters: Type.TObject<{
+        todos: Type.TArray<Type.TObject<{
+            text: Type.TString;
+            status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">]>;
+        }>>;
+    }>;
+    execute(_toolCallId: string, params: TodoParams, _signal?: AbortSignal, _onUpdate?: unknown, ctx?: ExtensionContext): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            todos: TodoItem[];
+        };
+        isError: boolean;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            todos: TodoItem[];
+        };
+        isError?: undefined;
+    }>;
+};
+/** Wire the tool, the branch-replay events, and the /todos command. */
+export declare function registerTodos(pi: ExtensionAPI): void;
+export {};
+//# sourceMappingURL=todos.d.ts.map

package/dist/extension/todos.js

@@ -0,0 +1,217 @@
+/**
+ * The session todo list — the visible checklist for multi-step work.
+ *
+ * A `todo_write` tool the model calls with the FULL list every time (replace,
+ * not patch: replacement is idempotent under retries and always renders a
+ * coherent board), a persistent above-editor widget while steps remain open,
+ * and a `/todos` command to pull the list on demand.
+ *
+ * State follows pi's branching model the same way the session does: the
+ * canonical list is the LAST `todo_write` tool result on the current branch,
+ * reconstructed on session_start/session_tree, so forking or rewinding a
+ * session automatically shows the list as it stood at that point. The
+ * in-memory copy is just a cache of that.
+ */
+import { Type } from "typebox";
+import { isDesktopSurface } from "./surface.js";
+export const TODO_TOOL_NAME = "todo_write";
+export const MAX_TODOS = 50;
+export const MAX_TODO_TEXT = 300;
+const WIDGET_KEY = "yagni-todos";
+/**
+ * The desktop's structured state record rides its own widget key, like the
+ * `/go` run state: one JSON line the app parses and renders itself, never
+ * themed terminal lines. The desktop shell hand-declares the matching parser
+ * (`parseTodoState` in its piProtocol.ts); a key-set assertion in
+ * todos.test.ts guards the two against drift.
+ */
+export const TODO_STATE_KEY = "yagni-todos:state";
+/** Header + items + overflow line must stay under pi's 10-line widget cap. */
+const MAX_WIDGET_ITEMS = 7;
+const STATUSES = ["pending", "in_progress", "completed"];
+/**
+ * Validate a full replacement list. Strict: this is model input rendered
+ * straight into the terminal. An empty list is valid (it clears the board).
+ */
+export function normalizeTodos(raw) {
+    if (!Array.isArray(raw))
+        return { ok: false, error: "todos must be an array" };
+    if (raw.length > MAX_TODOS)
+        return { ok: false, error: `todos is capped at ${MAX_TODOS} items` };
+    const todos = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            return { ok: false, error: "each todo must be an object" };
+        const { text, status } = item;
+        if (typeof text !== "string" || text.trim().length === 0) {
+            return { ok: false, error: "each todo needs non-empty text" };
+        }
+        if (typeof status !== "string" || !STATUSES.includes(status)) {
+            return { ok: false, error: `status must be one of ${STATUSES.join(", ")}` };
+        }
+        todos.push({ text: text.trim().slice(0, MAX_TODO_TEXT), status: status });
+    }
+    return { ok: true, todos };
+}
+export function todoSummary(todos) {
+    return {
+        done: todos.filter((t) => t.status === "completed").length,
+        total: todos.length,
+        active: todos.find((t) => t.status === "in_progress")?.text ?? null,
+    };
+}
+const GLYPH = { pending: "[ ]", in_progress: "[>]", completed: "[x]" };
+/** Plain-text checklist (tool results, /todos in headless contexts). */
+export function formatTodoList(todos) {
+    if (todos.length === 0)
+        return "No todos.";
+    const { done, total } = todoSummary(todos);
+    const lines = todos.map((t) => `${GLYPH[t.status]} ${t.text}`);
+    return [`${done}/${total} done`, ...lines].join("\n");
+}
+/**
+ * The above-editor checklist. Empty (paint nothing) when there is no list or
+ * every step is completed — a finished board should leave the screen. Capped
+ * so header + items + overflow stays under pi's 10-line widget truncation.
+ */
+export function renderTodoWidget(todos, theme) {
+    const { done, total } = todoSummary(todos);
+    if (total === 0 || done === total)
+        return [];
+    const lines = [theme.fg("muted", `Todos ${done}/${total}`)];
+    const visible = todos.slice(0, MAX_WIDGET_ITEMS);
+    for (const todo of visible) {
+        if (todo.status === "completed") {
+            const text = theme.strikethrough ? theme.strikethrough(todo.text) : todo.text;
+            lines.push(`${theme.fg("success", "☑ ")}${theme.fg("dim", text)}`);
+        }
+        else if (todo.status === "in_progress") {
+            lines.push(`${theme.fg("accent", "▶ ")}${theme.fg("text", todo.text)}`);
+        }
+        else {
+            lines.push(`${theme.fg("dim", "☐ ")}${theme.fg("muted", todo.text)}`);
+        }
+    }
+    if (todos.length > visible.length) {
+        lines.push(theme.fg("dim", `…and ${todos.length - visible.length} more`));
+    }
+    return lines;
+}
+/** The desktop state record: exactly one JSON line under TODO_STATE_KEY. */
+export function todoStateLine(todos) {
+    return JSON.stringify({ v: 1, todos });
+}
+/** Replay the branch: the last todo_write result is the canonical list. */
+export function reconstructTodos(entries) {
+    let todos = [];
+    for (const entry of entries) {
+        const e = entry;
+        if (e?.type !== "message")
+            continue;
+        const msg = e.message;
+        if (msg?.role !== "toolResult" || msg.toolName !== TODO_TOOL_NAME)
+            continue;
+        const details = msg.details;
+        const normalized = normalizeTodos(details?.todos);
+        if (normalized.ok)
+            todos = normalized.todos;
+    }
+    return todos;
+}
+const parameters = Type.Object({
+    todos: Type.Array(Type.Object({
+        text: Type.String({ description: "The step, short and imperative." }),
+        status: Type.Union([
+            Type.Literal("pending"),
+            Type.Literal("in_progress"),
+            Type.Literal("completed"),
+        ]),
+    }), { description: "The FULL list; it replaces the previous one." }),
+});
+function paintWidget(ctx, todos) {
+    if (!ctx?.hasUI)
+        return;
+    try {
+        if (isDesktopSurface()) {
+            // The desktop renders the checklist itself, so it gets the structured
+            // record instead of themed lines (RPC mode forwards widgetLines
+            // verbatim, and ANSI would land in the DOM). Painted on EVERY change —
+            // including an empty or finished list — so the app can clear its board,
+            // and on branch replay so resume/fork restores the list. The "todos
+            // n/m" status chip would be redundant next to the app's own rendering.
+            ctx.ui.setWidget?.(TODO_STATE_KEY, [todoStateLine(todos)], { placement: "aboveEditor" });
+            return;
+        }
+        const theme = ctx.ui.theme;
+        const lines = renderTodoWidget(todos, theme);
+        ctx.ui.setWidget?.(WIDGET_KEY, lines.length > 0 ? lines : undefined, {
+            placement: "aboveEditor",
+        });
+        const { done, total } = todoSummary(todos);
+        ctx.ui.setStatus?.(WIDGET_KEY, total > 0 && done < total ? `todos ${done}/${total}` : undefined);
+    }
+    catch {
+        // Painting is chrome; it must never break the tool call.
+    }
+}
+/**
+ * Build the todo_write tool definition around a shared store. Separated from
+ * registration so tests can drive execute directly.
+ */
+export function makeTodoTool(get, set) {
+    return {
+        name: TODO_TOOL_NAME,
+        label: "Todos",
+        description: "Track your plan for multi-step work as a checklist the user can see. " +
+            "Pass the FULL list every time — it replaces the previous list. Keep exactly one item " +
+            "in_progress at a time, mark items completed the moment they are done, and add newly " +
+            "discovered steps as pending. Use it for any task with three or more steps, updating as you go.",
+        promptSnippet: "todo_write: keep a user-visible checklist for multi-step work (full-list replacement).",
+        parameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const normalized = normalizeTodos(params.todos);
+            if (!normalized.ok) {
+                return {
+                    content: [{ type: "text", text: `Error: ${normalized.error}` }],
+                    details: { todos: get() },
+                    isError: true,
+                };
+            }
+            set(normalized.todos);
+            paintWidget(ctx, normalized.todos);
+            return {
+                content: [{ type: "text", text: formatTodoList(normalized.todos) }],
+                details: { todos: normalized.todos },
+            };
+        },
+    };
+}
+/** Wire the tool, the branch-replay events, and the /todos command. */
+export function registerTodos(pi) {
+    let todos = [];
+    const reconstruct = (ctx) => {
+        try {
+            todos = reconstructTodos(ctx.sessionManager.getBranch());
+        }
+        catch {
+            todos = [];
+        }
+        paintWidget(ctx, todos);
+    };
+    pi.on("session_start", async (_event, ctx) => reconstruct(ctx));
+    pi.on("session_tree", async (_event, ctx) => reconstruct(ctx));
+    pi.registerTool(makeTodoTool(() => todos, (next) => {
+        todos = next;
+    }));
+    pi.registerCommand("todos", {
+        description: "Show the agent's current task list for this session.",
+        handler: async (_args, ctx) => {
+            if (!ctx.hasUI)
+                return;
+            ctx.ui.notify(todos.length === 0
+                ? "No todos. The agent keeps a checklist here when a task takes multiple steps."
+                : formatTodoList(todos), "info");
+        },
+    });
+}
+//# sourceMappingURL=todos.js.map