@rahularya01/pi-essentials 0.1.0

package/src/subagents/types.ts

@@ -0,0 +1,131 @@
+export interface AgentDefinition {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  systemPrompt: string;
+  source: "builtin" | "user" | "project";
+  filePath?: string;
+}
+
+export type AgentScope = "user" | "project" | "both";
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+/** Agent names appear in CLI-visible text and file names, so keep them boring. */
+function sanitizeName(raw: string): string {
+  return raw
+    .trim()
+    .replace(/[^\w.-]+/g, "-")
+    .replace(/[.-]{2,}/g, "-")
+    .replace(/^[.\-]+|[.\-]+$/g, "")
+    .slice(0, 64);
+}
+
+function toStringList(value: unknown): string[] | undefined {
+  const items =
+    typeof value === "string"
+      ? value.split(",")
+      : Array.isArray(value)
+        ? value.map((item) => String(item))
+        : undefined;
+  if (!items) return undefined;
+  const cleaned = items.map((item) => item.trim()).filter(Boolean);
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
+export function parseAgentMarkdown(
+  markdown: string,
+  fallbackName: string,
+  source: AgentDefinition["source"],
+  filePath?: string,
+): AgentDefinition {
+  const match = markdown.match(FRONTMATTER);
+  const body = match ? markdown.slice(match[0].length) : markdown;
+  const fm = match ? parseFrontmatter(match[1]) : {};
+  const name = sanitizeName(String(fm.name ?? fallbackName)) || sanitizeName(fallbackName);
+  return {
+    name,
+    description: String(fm.description ?? "").trim(),
+    tools: toStringList(fm.tools),
+    model: typeof fm.model === "string" && fm.model.trim() ? fm.model.trim() : undefined,
+    systemPrompt: body.trim(),
+    source,
+    filePath,
+  };
+}
+
+/** Minimal YAML subset: `key: value`, inline `[a, b]` lists, and `- item` block lists. */
+function parseFrontmatter(raw: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const lines = raw.split(/\r?\n/);
+  let listKey: string | undefined;
+
+  for (const line of lines) {
+    const blockItem = /^\s*-\s+(.*)$/.exec(line);
+    if (blockItem && listKey) {
+      const items = (out[listKey] as string[]) ?? [];
+      const value = unquote(blockItem[1].trim());
+      if (value) items.push(value);
+      out[listKey] = items;
+      continue;
+    }
+
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const idx = trimmed.indexOf(":");
+    if (idx <= 0) continue;
+    const key = trimmed.slice(0, idx).trim();
+    const value = unquote(trimmed.slice(idx + 1).trim());
+
+    if (!value) {
+      listKey = key;
+      out[key] = [];
+      continue;
+    }
+    listKey = undefined;
+    if (value.startsWith("[") && value.endsWith("]")) {
+      out[key] = value
+        .slice(1, -1)
+        .split(",")
+        .map((item) => unquote(item.trim()))
+        .filter(Boolean);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function unquote(value: string): string {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+export function validateSubagentParams(params: {
+  agent?: string;
+  task?: string;
+  tasks?: Array<{ agent: string; task: string }>;
+  chain?: Array<{ agent: string; task: string }>;
+}): { mode: "single" | "parallel" | "chain" } | { error: string } {
+  const hasChain = (params.chain?.length ?? 0) > 0;
+  const hasTasks = (params.tasks?.length ?? 0) > 0;
+  const hasSingle = Boolean(params.agent?.trim() && params.task?.trim());
+  const modeCount = Number(hasChain) + Number(hasTasks) + Number(hasSingle);
+  if (modeCount === 0) {
+    const partial = params.agent || params.task;
+    return {
+      error: partial
+        ? "Single mode needs both { agent, task }. Otherwise pass { tasks: [...] } or { chain: [...] }."
+        : "Provide exactly one mode: { agent, task }, { tasks: [...] }, or { chain: [...] }.",
+    };
+  }
+  if (modeCount > 1) {
+    return { error: "Provide exactly one mode: { agent, task }, { tasks: [...] }, or { chain: [...] }." };
+  }
+  if (hasSingle) return { mode: "single" };
+  if (hasTasks) return { mode: "parallel" };
+  return { mode: "chain" };
+}

package/src/subagents/worktree.ts

@@ -0,0 +1,131 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type Isolation = "none" | "worktree";
+
+export interface WorktreeMetadata {
+  isolation: "worktree";
+  repoRoot: string;
+  worktreePath: string;
+  baseCommit: string;
+  changedFiles: string[];
+  patchPath?: string;
+  captureError?: string;
+}
+
+export interface TemporaryWorktree {
+  repoRoot: string;
+  path: string;
+  parentDir: string;
+  baseCommit: string;
+}
+
+function gitRaw(cwd: string, args: string[]): string {
+  return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function git(cwd: string, args: string[]): string {
+  return gitRaw(cwd, args).trim();
+}
+
+/** Parse porcelain v1 -z output, including the destination and source of renames. */
+export function parseChangedFiles(porcelain: string): string[] {
+  const records = porcelain.split("\0");
+  const files: string[] = [];
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    if (!record) continue;
+    const status = record.slice(0, 2);
+    const file = record.slice(3);
+    if (file) files.push(file);
+    if (status.includes("R") || status.includes("C")) {
+      const source = records[++i];
+      if (source) files.push(source);
+    }
+  }
+  return [...new Set(files)].sort();
+}
+
+export function createTemporaryWorktree(sourceCwd: string): TemporaryWorktree {
+  let repoRoot: string;
+  try {
+    repoRoot = git(sourceCwd, ["rev-parse", "--show-toplevel"]);
+  } catch {
+    throw new Error(`Worktree isolation requires a git repository: ${sourceCwd}`);
+  }
+  if (git(repoRoot, ["status", "--porcelain", "--untracked-files=all"])) {
+    throw new Error(`Worktree isolation requires a clean source tree: ${repoRoot}`);
+  }
+
+  const baseCommit = git(repoRoot, ["rev-parse", "HEAD"]);
+  const parentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-essentials-worktree-"));
+  const worktreePath = path.join(parentDir, "checkout");
+  try {
+    execFileSync("git", ["-C", repoRoot, "worktree", "add", "--detach", worktreePath, baseCommit], {
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+  } catch (error) {
+    fs.rmSync(parentDir, { recursive: true, force: true });
+    throw new Error(`Could not create temporary git worktree: ${(error as Error).message}`);
+  }
+  return { repoRoot, path: worktreePath, parentDir, baseCommit };
+}
+
+export function remapWorktreeCwd(sourceCwd: string, worktree: TemporaryWorktree): string {
+  const relative = path.relative(worktree.repoRoot, path.resolve(sourceCwd));
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Working directory is outside the isolated repository: ${sourceCwd}`);
+  }
+  return path.join(worktree.path, relative);
+}
+
+/** Capture a --binary patch outside the checkout, then remove the detached worktree. */
+export function finishTemporaryWorktree(worktree: TemporaryWorktree): WorktreeMetadata {
+  let changedFiles: string[] = [];
+  let patchPath: string | undefined;
+  let captureError: string | undefined;
+  try {
+    const porcelain = gitRaw(worktree.path, ["status", "--porcelain", "-z", "--untracked-files=all"]);
+    const statusFiles = parseChangedFiles(porcelain);
+    const committedFiles = gitRaw(worktree.path, ["diff", "--name-only", "-z", worktree.baseCommit])
+      .split("\0")
+      .filter(Boolean);
+    changedFiles = [...new Set([...statusFiles, ...committedFiles])].sort();
+    if (statusFiles.length > 0) {
+      // Intent-to-add makes untracked files visible to diff without changing the source repository's index.
+      execFileSync("git", ["-C", worktree.path, "add", "-N", "--", "."], { stdio: "ignore" });
+    }
+    const patch = execFileSync("git", ["-C", worktree.path, "diff", "--binary", "--no-ext-diff", worktree.baseCommit], {
+      encoding: "buffer",
+      maxBuffer: 100 * 1024 * 1024,
+    });
+    const artifactDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-essentials-subagent-patch-"));
+    patchPath = path.join(artifactDir, "changes.patch");
+    fs.writeFileSync(patchPath, patch, { mode: 0o600 });
+  } catch (error) {
+    // The child already completed; artifact failures must not erase its answer.
+    captureError = `Could not capture isolated changes: ${(error as Error).message}`;
+  } finally {
+    try {
+      execFileSync("git", ["-C", worktree.repoRoot, "worktree", "remove", "--force", worktree.path], { stdio: "ignore" });
+    } catch (error) {
+      captureError ??= `Could not remove temporary worktree: ${(error as Error).message}`;
+    }
+    try {
+      fs.rmSync(worktree.parentDir, { recursive: true, force: true });
+    } catch (error) {
+      captureError ??= `Could not remove temporary worktree directory: ${(error as Error).message}`;
+    }
+  }
+  return {
+    isolation: "worktree",
+    repoRoot: worktree.repoRoot,
+    worktreePath: worktree.path,
+    baseCommit: worktree.baseCommit,
+    changedFiles,
+    patchPath,
+    captureError,
+  };
+}

package/src/todos/index.ts

@@ -0,0 +1,170 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { errorMessage, toolFailure, toolText } from "../errors.ts";
+import { MAX_TODOS } from "../security/limits.ts";
+import { formatTodosGrouped, renderTodoCall, renderTodoResult, todoWidget } from "./render.ts";
+import { applyTodoMutation, cloneState, emptyTodoState, formatTodos, type TodoItem, type TodoState } from "./state.ts";
+
+interface TodoDetails {
+  todos: TodoState["todos"];
+  nextId: number;
+}
+
+/** Rows shown in the editor widget before it collapses into a "+N more" line. */
+const WIDGET_ROWS = 8;
+const TODO_STATE_ENTRY = "pi-essentials-todos";
+
+export function registerTodos(pi: ExtensionAPI): void {
+  const bySession = new Map<string, TodoState>();
+  let collapsed = false;
+
+  const sessionKey = (ctx: ExtensionContext): string =>
+    ctx.sessionManager?.getSessionFile?.() || ctx.sessionManager?.getSessionId?.() || "default";
+
+  /**
+   * Rebuild state from the session branch so todos survive /reload, compaction,
+   * and /tree navigation, which can move to a branch with different history.
+   */
+  const reconstruct = (ctx: ExtensionContext): TodoState => {
+    let state = emptyTodoState();
+    let branch: unknown[] = [];
+    try {
+      branch = ctx.sessionManager?.getBranch?.() ?? [];
+    } catch {
+      branch = [];
+    }
+    for (const entry of branch) {
+      const record = entry as { type?: string; customType?: string; data?: Partial<TodoDetails>; message?: unknown };
+      if (record?.type === "custom" && record.customType === TODO_STATE_ENTRY) {
+        if (Array.isArray(record.data?.todos) && typeof record.data?.nextId === "number") {
+          state = { todos: record.data.todos, nextId: record.data.nextId };
+        }
+        continue;
+      }
+      if (record?.type !== "message") continue;
+      const msg = record.message as { role?: string; toolName?: string; details?: Partial<TodoDetails> };
+      if (msg?.role !== "toolResult" || msg.toolName !== "todo") continue;
+      if (Array.isArray(msg.details?.todos) && typeof msg.details?.nextId === "number") {
+        state = { todos: msg.details.todos, nextId: msg.details.nextId };
+      }
+    }
+    const restored = cloneState(state);
+    bySession.set(sessionKey(ctx), restored);
+    return restored;
+  };
+
+  const current = (ctx: ExtensionContext): TodoState => bySession.get(sessionKey(ctx)) ?? reconstruct(ctx);
+
+  const renderWidget = (ctx: ExtensionContext, state: TodoState) => {
+    if (!ctx.hasUI) return;
+    if (state.todos.length === 0) {
+      ctx.ui.setWidget("pi-essentials-todos", undefined);
+      return;
+    }
+    // A component factory receives the live theme, so the widget picks up
+    // strikethrough, the progress meter, and theme colors.
+    ctx.ui.setWidget(
+      "pi-essentials-todos",
+      (_tui, theme) => new Text(todoWidget(theme, state, { collapsed, maxRows: WIDGET_ROWS }).join("\n"), 0, 0),
+      { placement: "aboveEditor" },
+    );
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    bySession.clear();
+    renderWidget(ctx, reconstruct(ctx));
+  });
+  pi.on("session_tree", async (_event, ctx) => {
+    renderWidget(ctx, reconstruct(ctx));
+  });
+  pi.on("session_shutdown", async () => {
+    bySession.clear();
+  });
+
+  pi.registerShortcut("ctrl+shift+t", {
+    description: "Collapse or expand the pi-essentials todo panel",
+    handler: async (ctx) => {
+      collapsed = !collapsed;
+      renderWidget(ctx, current(ctx));
+    },
+  });
+
+  pi.registerCommand("todos", {
+    description: "Show the current todo list. Usage: /todos [clear]",
+    handler: async (args, ctx) => {
+      if (args.trim().toLowerCase() === "clear") {
+        const applied = applyTodoMutation(current(ctx), { action: "clear" });
+        bySession.set(sessionKey(ctx), applied.state);
+        pi.appendEntry(TODO_STATE_ENTRY, cloneState(applied.state));
+        renderWidget(ctx, applied.state);
+        ctx.ui.notify(applied.message, "info");
+        return;
+      }
+      ctx.ui.notify(formatTodosGrouped(current(ctx).todos), "info");
+    },
+  });
+
+  const StatusSchema = StringEnum(["pending", "in_progress", "completed", "blocked", "abandoned"] as const);
+  const SnapshotTodoSchema = Type.Object({
+    id: Type.Integer({ minimum: 1, description: "Stable numeric todo id" }),
+    content: Type.String(),
+    status: StatusSchema,
+    blockedBy: Type.Optional(Type.Array(Type.Integer({ minimum: 1 }))),
+    phase: Type.Optional(Type.String()),
+    blocker: Type.Optional(Type.String()),
+  });
+
+  pi.registerTool({
+    name: "todo",
+    label: "Todo",
+    description:
+      "Track multi-step coding work. Actions: list, create, update, complete, reopen, block, unblock, abandon, delete, clear, sync. Keep at most one item in_progress.",
+    promptSnippet: "Track multi-step work with a structured todo list",
+    promptGuidelines: [
+      "Use todo to plan and track multi-step coding tasks instead of keeping an informal checklist only in your head.",
+      "Keep at most one todo in_progress. Mark work complete as soon as it is done.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(["list", "create", "update", "complete", "reopen", "block", "unblock", "abandon", "delete", "clear", "sync"] as const),
+      content: Type.Optional(Type.String({ description: "Todo text for create/update" })),
+      id: Type.Optional(Type.Number({ description: "Todo id for update/complete/reopen/block/unblock/abandon/delete" })),
+      status: Type.Optional(StatusSchema),
+      blockedBy: Type.Optional(Type.Array(Type.Number(), { description: `Ids that must finish first (max ${MAX_TODOS})` })),
+      phase: Type.Optional(Type.String({ description: "Optional workflow phase" })),
+      blocker: Type.Optional(Type.String({ description: "Optional reason the todo is blocked" })),
+      todos: Type.Optional(Type.Array(SnapshotTodoSchema, { description: "Complete replacement snapshot for sync" })),
+
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const before = current(ctx);
+      try {
+        const applied = applyTodoMutation(before, {
+          action: params.action,
+          content: params.content,
+          id: params.id,
+          status: params.status,
+          blockedBy: params.blockedBy,
+          phase: params.phase,
+          blocker: params.blocker,
+          todos: params.todos as TodoItem[] | undefined,
+        });
+        bySession.set(sessionKey(ctx), applied.state);
+        renderWidget(ctx, applied.state);
+        const listing = params.action === "list" ? "" : `\n\n${formatTodos(applied.state.todos)}`;
+        return toolText(`${applied.message}${listing}`, {
+          todos: applied.state.todos,
+          nextId: applied.state.nextId,
+          action: params.action,
+        } satisfies TodoDetails & { action: string });
+      } catch (error) {
+        // The state is unchanged on failure, so the last successful result is
+        // still the correct one for branch reconstruction.
+        toolFailure(`${errorMessage(error)}\n\n${formatTodos(before.todos)}`, "TODO_INVALID");
+      }
+    },
+    renderCall: renderTodoCall,
+    renderResult: renderTodoResult,
+  });
+}

package/src/todos/render.ts

@@ -0,0 +1,198 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+  failLine,
+  firstText,
+  GLYPH,
+  headingRule,
+  meta,
+  oneLine,
+  progressBar,
+  safeKeyHint,
+  safeRender,
+  titleLine,
+  type RenderableResult,
+  type RenderSlot,
+} from "../ui/render.ts";
+import type { TodoItem, TodoState } from "./state.ts";
+
+interface TodoDetails {
+  todos?: TodoItem[];
+  nextId?: number;
+  action?: string;
+}
+
+const STATUS_GLYPH: Record<TodoItem["status"], string> = {
+  completed: GLYPH.done,
+  in_progress: GLYPH.running,
+  pending: GLYPH.pending,
+  blocked: "!",
+  abandoned: "–",
+};
+
+const STATUS_COLOR = {
+  completed: "success",
+  in_progress: "accent",
+  pending: "muted",
+  blocked: "warning",
+  abandoned: "dim",
+} as const;
+
+/** One task line: glyph, id, text. Completed work is struck through. */
+export function todoLine(theme: Theme, todo: TodoItem, width = 60): string {
+  const color = STATUS_COLOR[todo.status];
+  const label = oneLine(todo.content, width);
+  const text = todo.status === "completed" || todo.status === "abandoned"
+    ? theme.strikethrough(theme.fg("dim", label))
+    : theme.fg("text", label);
+  const dependencies = todo.blockedBy?.length ? `needs ${todo.blockedBy.map((id) => `#${id}`).join(",")}` : undefined;
+  const details = [todo.phase && `phase ${todo.phase}`, todo.blocker && `blocked: ${todo.blocker}`, dependencies]
+    .filter((part): part is string => Boolean(part));
+  const metadata = details.length > 0 ? theme.fg("dim", ` ${GLYPH.sep} ${details.join(` ${GLYPH.sep} `)}`) : "";
+  return `${theme.fg(color, STATUS_GLYPH[todo.status])} ${theme.fg("dim", `#${todo.id}`)} ${text}${metadata}`;
+}
+
+export function renderTodoCall(
+  args: { action?: string; content?: string; id?: number; status?: string },
+  theme: Theme,
+  context: RenderSlot,
+): Text {
+  return safeRender(
+    () => {
+      const subject = args?.content ? `"${oneLine(args.content, 48)}"` : args?.id !== undefined ? `#${args.id}` : undefined;
+      return (
+        titleLine(theme, "todo") +
+        ` ${theme.fg("accent", args?.action ?? "")}` +
+        (subject ? ` ${theme.fg("text", subject)}` : "") +
+        meta(theme, [args?.status])
+      );
+    },
+    "todo",
+    context,
+  );
+}
+
+export function renderTodoResult(
+  result: RenderableResult<TodoDetails | undefined>,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  context: RenderSlot,
+): Text {
+  return safeRender(
+    () => {
+      if (context.isError) return failLine(theme, oneLine(firstText(result) || "todo update failed", 96));
+
+      const todos = result?.details?.todos ?? [];
+      if (todos.length === 0) {
+        return `${theme.fg("muted", GLYPH.pending)} ${theme.fg("muted", "no todos")}`;
+      }
+
+      const done = todos.filter((todo) => todo.status === "completed").length;
+      const header =
+        `${theme.fg("success", GLYPH.ok)} ${progressBar(theme, done, todos.length)} ` +
+        theme.fg("text", `${done}/${todos.length}`) +
+        meta(theme, [firstMessage(firstText(result))]);
+
+      // Unfinished work is what the reader needs; completed rows fill the rest.
+      const open = todos.filter((todo) => todo.status !== "completed");
+      const closed = todos.filter((todo) => todo.status === "completed");
+      const ordered = [...open, ...closed];
+      const limit = options.expanded ? ordered.length : Math.min(ordered.length, 6);
+      const shown = ordered.slice(0, limit);
+
+      let text = header;
+      for (const todo of shown) text += `\n  ${todoLine(theme, todo)}`;
+
+      const hidden = ordered.length - shown.length;
+      if (hidden > 0) {
+        const hiddenDone = shown.length >= open.length ? hidden : closed.length;
+        text += theme.fg(
+          "dim",
+          `\n  +${hidden} more (${hiddenDone} completed) ${GLYPH.sep} ${safeKeyHint("app.tools.expand", "to expand")}`,
+        );
+      }
+      return text;
+    },
+    oneLine(firstText(result), 120),
+    context,
+  );
+}
+
+/** The mutation message is the first line of the tool text ("Created #3: ..."). */
+function firstMessage(text: string): string | undefined {
+  const line = text.split("\n")[0]?.trim();
+  if (!line || line.startsWith("Todos (")) return undefined;
+  return oneLine(line, 48);
+}
+
+export interface WidgetOptions {
+  collapsed: boolean;
+  maxRows: number;
+}
+
+/**
+ * Editor widget. Unfinished work sorts first, completed rows are struck
+ * through, and anything dropped is accounted for on the overflow line.
+ */
+export function todoWidget(theme: Theme, state: TodoState, options: WidgetOptions): string[] {
+  const todos = state.todos;
+  if (todos.length === 0) return [];
+
+  const done = todos.filter((todo) => todo.status === "completed").length;
+  const active = todos.find((todo) => todo.status === "in_progress");
+  const heading =
+    headingRule(theme, "Todos") +
+    ` ${progressBar(theme, done, todos.length)} ${theme.fg("muted", `${done}/${todos.length}`)}`;
+
+  if (options.collapsed) {
+    const hint = active ? oneLine(active.content, 40) : `${todos.length - done} remaining`;
+    return [`${heading}  ${theme.fg("dim", `${GLYPH.sep} ${hint} ${GLYPH.sep} ${safeKeyHint("app.tools.expand", "expand")}`)}`];
+  }
+
+  const open = todos.filter((todo) => todo.status !== "completed");
+  const closed = todos.filter((todo) => todo.status === "completed");
+  const ordered = [...open, ...closed];
+  const rows = Math.max(1, options.maxRows);
+  const shown = ordered.slice(0, rows);
+
+  const lines = [heading, ...shown.map((todo) => `  ${todoLine(theme, todo, 52)}`)];
+  const hidden = ordered.slice(rows);
+  if (hidden.length > 0) {
+    // Say exactly what was dropped rather than a bare "+N more".
+    const hiddenDone = hidden.filter((todo) => todo.status === "completed").length;
+    const hiddenOpen = hidden.length - hiddenDone;
+    const parts = [hiddenDone > 0 && `${hiddenDone} completed`, hiddenOpen > 0 && `${hiddenOpen} pending`].filter(
+      (part): part is string => Boolean(part),
+    );
+    lines.push(theme.fg("dim", `  +${hidden.length} more (${parts.join(", ")})`));
+  }
+  return lines;
+}
+
+/** `/todos` output, grouped by status. */
+export function formatTodosGrouped(todos: TodoItem[]): string {
+  if (todos.length === 0) return "No todos yet. Ask the agent to plan the work.";
+  const groups: Array<[string, TodoItem["status"]]> = [
+    ["In progress", "in_progress"],
+    ["Blocked", "blocked"],
+    ["Pending", "pending"],
+    ["Completed", "completed"],
+    ["Abandoned", "abandoned"],
+  ];
+  const done = todos.filter((todo) => todo.status === "completed").length;
+  const out: string[] = [`Todos ${done}/${todos.length} completed`];
+  for (const [label, status] of groups) {
+    const rows = todos.filter((todo) => todo.status === status);
+    if (rows.length === 0) continue;
+    out.push("", `${label} (${rows.length})`);
+    for (const todo of rows) {
+      const details = [
+        todo.phase && `phase ${todo.phase}`,
+        todo.blocker && `blocked: ${todo.blocker}`,
+        todo.blockedBy?.length && `needs ${todo.blockedBy.map((id) => `#${id}`).join(",")}`,
+      ].filter((part): part is string => Boolean(part));
+      out.push(`  ${STATUS_GLYPH[todo.status]} #${todo.id} ${todo.content}${details.length ? `  ${details.join("; ")}` : ""}`);
+    }
+  }
+  return out.join("\n");
+}