@alisio/alisio-code 0.1.0-alpha.9 → 0.1.0

package/dist/tui/state.js

@@ -1,3 +1,8 @@
+/**
+ * Pure presentation logic for the TUI: formatting, command parsing and the reduction of
+ * versioned runner events into a view model. No terminal or pi-tui imports here.
+ */
+import { CommandCatalog, describeOutputLimitSource } from "@alisio/core";
 const trimZero = (value) => value.replace(/\.0$/, "");
 export function formatTokens(n) {
     if (!Number.isFinite(n) || n < 0)
@@ -24,6 +29,55 @@ export function providerModelItems(provider, models, current) {
 }
 /** Text markers remain meaningful without color: [x] active, [ ] inactive, [!] failed, [*] pending. */
 /** Group headings are derived from the primary category (or "General") of each plugin. */
+/**
+ * Reserved value prefix marking a non-selectable group-header row in picker item lists. It can
+ * never collide with real entry ids (plugin ids, server names), which never start with "_".
+ */
+export const GROUP_HEADER_PREFIX = "__group:";
+/** True when the item is a group header emitted under GROUP_HEADER_PREFIX (never selectable). */
+export const isGroupHeader = (item) => item.value.startsWith(GROUP_HEADER_PREFIX);
+/**
+ * Nearest non-header index from `index` stepping `dir` (1 = down, -1 = up), wrapping at the
+ * edges exactly like a plain list would, so navigation skips header rows in both directions and
+ * never stops on one. Returns -1 for an empty list and `index` unchanged when every item is a
+ * header (callers then treat it as "no move").
+ */
+export function skipGroupHeaders(items, index, dir) {
+    const count = items.length;
+    if (!count)
+        return -1;
+    let next = (index + dir + count) % count;
+    for (let steps = 0; steps < count && next !== index; steps++) {
+        if (!isGroupHeader(items[next]))
+            return next;
+        next = (next + dir + count) % count;
+    }
+    return index;
+}
+/**
+ * The display sequence a picker should render for a filter: rows matching SelectList's own
+ * prefix semantics, plus the group header of every group that still has at least one visible
+ * row, in original order. Groups with no match emit no header.
+ */
+export function visibleGroupedItems(items, filter) {
+    const query = filter.toLowerCase();
+    const visible = [];
+    let header;
+    for (const item of items) {
+        if (isGroupHeader(item)) {
+            header = item;
+            continue;
+        }
+        if (item.value.toLowerCase().startsWith(query)) {
+            if (header) {
+                visible.push(header);
+                header = undefined;
+            }
+            visible.push(item);
+        }
+    }
+    return visible;
+}
 export function pluginCatalogItems(entries) {
     const marker = (entry) => entry.status === "active"
         ? "[x]"
@@ -37,11 +91,15 @@ export function pluginCatalogItems(entries) {
         const primary = entry.categories[0] ?? "General";
         grouped.set(primary, [...(grouped.get(primary) ?? []), entry]);
     }
-    return [...grouped].flatMap(([title, group]) => group.map((entry, index) => ({
-        value: entry.id,
-        label: `${index === 0 ? `${title} · ` : ""}${marker(entry)} ${entry.name} · ${entry.builtin ? "built-in" : entry.source}`,
-        description: `${entry.status}${entry.categories.length ? ` · ${entry.categories.join(", ")}` : ""} · ${entry.description}`,
-    })));
+    // Every group opens with its own non-selectable header row; plugin rows are indented under it.
+    return [...grouped].flatMap(([title, group]) => [
+        { value: `${GROUP_HEADER_PREFIX}${title}`, label: `${title} ›` },
+        ...group.map((entry) => ({
+            value: entry.id,
+            label: `  ${marker(entry)} ${entry.name} · ${entry.builtin ? "built-in" : entry.source}`,
+            description: `${entry.status}${entry.categories.length ? ` · ${entry.categories.join(", ")}` : ""} · ${entry.description}`,
+        })),
+    ]);
 }
 export const pluginToggleNeedsConfirmation = (entry) => !entry.builtin;
 const mcpSourceTitle = (kind) => ({
@@ -198,46 +256,27 @@ export function fitSegments(segments, width, separator) {
         kept[0] = { ...only, text: truncatePlain(only.text, width) };
     return kept;
 }
-export const COMMANDS = [
-    { name: "help", description: "Show commands and keys" },
-    { name: "connect", description: "Configure a provider and choose its active model" },
-    {
-        name: "model",
-        description: "Switch provider and model",
-        aliases: ["models"],
-    },
-    { name: "compact", description: "Summarize older history", argumentHint: "[focus]" },
-    { name: "stats", description: "Session statistics" },
-    { name: "clear", description: "Start a new session", aliases: ["new"] },
-    { name: "sessions", description: "List recent sessions" },
-    { name: "resume", description: "Resume a session by ID or prefix", argumentHint: "<id>" },
-    { name: "tools", description: "List tools and permission state" },
-    {
-        name: "plugins",
-        description: "Browse and manage project plugins",
-        aliases: ["plugin"],
-    },
-    {
-        name: "skills",
-        description: "Browse and manage effective skills",
-        aliases: ["skill"],
-    },
-    { name: "mcp", description: "Browse and manage MCP servers" },
-    { name: "copy", description: "Copy the last assistant response to the clipboard" },
-    {
-        name: "ask",
-        description: "Ask the agent to turn your question into a multiple-choice ask_user_question",
-        argumentHint: "<question>",
-    },
-    { name: "exit", description: "Exit Alisio", aliases: ["quit"] },
-];
+/** Built-ins only: plugin, template and skill commands are resolved against the live app. */
+const BUILTIN_CATALOG = new CommandCatalog();
+/**
+ * Built-in slash commands the TUI offers, derived from the core `CommandCatalog` (the TUI
+ * surface of `BUILTIN_COMMANDS`). Kept as `COMMANDS` for compatibility.
+ */
+export const COMMANDS = BUILTIN_CATALOG.list("tui")
+    .filter((c) => c.source === "builtin")
+    .map((c) => ({
+    name: c.name,
+    description: c.description,
+    ...(c.argumentHint ? { argumentHint: c.argumentHint } : {}),
+    ...(c.aliases ? { aliases: c.aliases } : {}),
+}));
 /** Every TUI slash name (commands, aliases and routing prefixes); templates cannot take them. */
 export function reservedCommandNames() {
     return [...COMMANDS.flatMap((c) => [c.name, ...(c.aliases ?? [])]), "command"];
 }
 export function resolveCommand(name) {
-    const lower = name.toLowerCase();
-    return COMMANDS.find((c) => c.name === lower || c.aliases?.includes(lower))?.name;
+    const found = BUILTIN_CATALOG.resolve(name);
+    return found?.source === "builtin" && found.surfaces.includes("tui") ? found.name : undefined;
 }
 export function parseCommand(input) {
     const match = /^\/([A-Za-z][\w:.-]*)(?:\s+([\s\S]*))?$/.exec(input.trim());
@@ -245,6 +284,151 @@ export function parseCommand(input) {
         return undefined;
     return { name: match[1], args: (match[2] ?? "").trim() };
 }
+/**
+ * The effective reasoning effort to send for a model: the persisted level when the model
+ * supports it, otherwise the model's default level (silent fallback), and nothing when the
+ * model advertises no effort levels at all.
+ */
+export function effectiveEffort(persisted, capability) {
+    if (!capability?.supportedLevels?.length)
+        return undefined;
+    if (persisted && capability.supportedLevels.includes(persisted))
+        return persisted;
+    return capability.defaultLevel;
+}
+/** Validates a `/effort <level>` argument against the active model; returns an error or nothing. */
+export function validateEffortLevel(level, capability) {
+    if (!capability?.supportedLevels?.length)
+        return "This model does not advertise reasoning effort levels, so no effort is sent to it.";
+    if (!capability.supportedLevels.includes(level))
+        return `Unsupported effort level "${level}". Supported levels: ${capability.supportedLevels.join(", ")}.`;
+    return undefined;
+}
+export function effortPickerItems(capability, active) {
+    const items = capability.supportedLevels.map((level) => ({
+        value: level,
+        label: [
+            level,
+            level === active ? "(current)" : undefined,
+            level === capability.defaultLevel ? "(default)" : undefined,
+        ]
+            .filter(Boolean)
+            .join(" · "),
+        ...(level === capability.defaultLevel ? { description: "The model's own default" } : {}),
+    }));
+    return [
+        ...items,
+        {
+            value: "!clear",
+            label: "Auto · provider default",
+            description: "Clear the saved effort; the provider uses its own default",
+        },
+    ];
+}
+/**
+ * The ordered identity parts for the status line below the editor:
+ * `agent: <name> · <model> · <provider> · <effort>`, with the effort part omitted when the
+ * active model advertises no supported levels (`effort === undefined`). Colors are applied by
+ * the renderer per role; this module stays terminal-free and testable.
+ */
+export function identityParts(input) {
+    const parts = [
+        { text: `agent: ${input.agent}`, priority: 10, role: "agent" },
+        // Between the agent and the model: it drops after the effort and the provider, before the model.
+        ...(input.mode ? [{ text: `mode: ${input.mode}`, priority: 8.5, role: "mode" }] : []),
+        { text: input.model || "not connected", priority: 9, role: "model" },
+    ];
+    if (input.provider)
+        parts.push({ text: input.provider, priority: 8, role: "provider" });
+    if (input.effort)
+        parts.push({ text: input.effort, priority: 7, role: "effort" });
+    return parts;
+}
+/** Drops the lowest-priority identity parts until the line fits `width`; truncates the survivor. */
+export function fitIdentityParts(input, width) {
+    return fitSegments(identityParts(input), width, " · ");
+}
+export const SKILL_COMPLETION_DESCRIPTION_LIMIT = 80;
+/** Status hint prefixes (no color): shadowed < disabled < locked states shown by /skills. */
+const skillStatus = (skill) => !skill.effective
+    ? "shadowed"
+    : !skill.enabled
+        ? "disabled"
+        : skill.locked
+            ? "locked by plugin"
+            : undefined;
+/**
+ * OpenCode-style scope marker for a skill's slash entry, mirroring the catalog scopes the /skills
+ * manager shows: user, project, config and plugin (plugin skills are locked by their owner plugin).
+ */
+export const skillScopeMarker = (skill) => {
+    const marker = { user: "[u]", project: "[p]", config: "[c]", plugin: "[l]" }[skill.scope];
+    return marker ?? (skill.scope ? `[${skill.scope}]` : undefined);
+};
+/**
+ * Description for a skill's first-class `skill:<id>` slash entry: scope marker, status hint, then
+ * the skill description truncated to the shared limit. The marker and status are prepended before
+ * truncating, so they survive the cap just like the /skills argument completions.
+ */
+export function skillSlashDescription(skill) {
+    const marker = skillScopeMarker(skill);
+    const status = skillStatus(skill);
+    if (!marker && !status)
+        return truncatePlain(skill.description, SKILL_COMPLETION_DESCRIPTION_LIMIT);
+    return truncatePlain(`${[marker, status].filter(Boolean).join(" ")}${status ? " · " : " "}${skill.description}`, SKILL_COMPLETION_DESCRIPTION_LIMIT);
+}
+/**
+ * Suggested completions for `/skills <prefix>`: every entry the /skills manager shows, filtered by
+ * prefix (case-insensitive) on name or description. Selecting a suggestion only fills the argument;
+ * submitting still opens the skills manager.
+ */
+export function skillCompletions(catalog, prefix, limit = 20) {
+    const query = prefix.trim().toLowerCase();
+    const items = query
+        ? catalog.filter((skill) => [skill.displayId, skill.name, skill.description].join(" ").toLowerCase().includes(query))
+        : catalog;
+    return items.slice(0, limit).map((skill) => {
+        const status = skillStatus(skill);
+        return {
+            value: skill.id,
+            label: skill.displayId,
+            description: truncatePlain(status ? `${status} · ${skill.description}` : skill.description, SKILL_COMPLETION_DESCRIPTION_LIMIT),
+        };
+    });
+}
+function argumentCompletionsFor(source, context) {
+    const sessions = context.sessions;
+    if (source.name === "resume" && sessions)
+        return {
+            getArgumentCompletions: (prefix) => sessions(prefix).slice(0, 20),
+        };
+    if (source.name === "skills")
+        return {
+            getArgumentCompletions: (prefix) => skillCompletions(context.skills, prefix, 20),
+        };
+    return {};
+}
+export function slashCompletionCommands(sources, context, options = {}) {
+    const entries = sources.flatMap((source) => {
+        const entry = (name) => ({
+            name,
+            description: source.description,
+            ...(source.argumentHint ? { argumentHint: source.argumentHint } : {}),
+            ...argumentCompletionsFor(source, context),
+        });
+        return [
+            entry(source.name),
+            ...(source.aliases ?? []).filter((a) => a !== source.name).map(entry),
+        ];
+    });
+    if (options.skillEntries !== false)
+        for (const skill of context.skills)
+            entries.push({
+                name: `skill:${skill.id}`,
+                description: skillSlashDescription(skill),
+            });
+    return entries;
+}
 function parseArgs(args) {
     try {
         const value = JSON.parse(args);
@@ -350,19 +534,40 @@ export function addItem(state, item) {
 const withModel = (stats, model) => typeof model === "string" && model && !stats.models.includes(model)
     ? { ...stats, models: [...stats.models, model] }
     : stats;
-function appendAssistant(state, field, delta) {
+/**
+ * Streaming assistant items stamp the thinking interval: the first reasoning delta records
+ * `reasoningStartedAt` and every later one refreshes `reasoningDoneAt`, so a completed thought
+ * section can show a `Thought · 2.9s` duration. The stamp stops once text arrives (the model
+ * moved on to the answer), so the duration measures the visible reasoning span, never the turn.
+ */
+const withReasoningStamp = (item, field, at) => {
+    if (field !== "reasoning" || item.text)
+        return item;
+    return { ...item, reasoningStartedAt: item.reasoningStartedAt ?? at, reasoningDoneAt: at };
+};
+function appendAssistant(state, field, delta, at = Date.now()) {
     const last = state.items.at(-1);
     if (last?.kind === "assistant" && !last.done)
         return {
             ...state,
-            items: [...state.items.slice(0, -1), { ...last, [field]: last[field] + delta }],
+            items: [
+                ...state.items.slice(0, -1),
+                withReasoningStamp({ ...last, [field]: last[field] + delta }, field, at),
+            ],
         };
-    return addItem(state, {
+    return addItem(state, withReasoningStamp({
         kind: "assistant",
         text: field === "text" ? delta : "",
         reasoning: field === "reasoning" ? delta : "",
         done: false,
-    });
+    }, field, at));
+}
+/** Approximated thinking interval of a completed reasoning section, when the events carried timestamps. */
+export function reasoningDurationMs(item) {
+    const { reasoningStartedAt, reasoningDoneAt } = item;
+    if (reasoningStartedAt === undefined || reasoningDoneAt === undefined)
+        return undefined;
+    return Math.max(0, reasoningDoneAt - reasoningStartedAt);
 }
 function updateTool(state, id, update) {
     const index = state.items.findLastIndex((i) => i.kind === "tool" && i.id === id);
@@ -374,6 +579,98 @@ function updateTool(state, id, update) {
     return { ...state, items };
 }
 export function reduceEvent(state, event) {
+    const next = reduceEventItems(state, event);
+    const terminal = event.type === "run_completed" ||
+        event.type === "run_failed" ||
+        event.type === "run_cancelled" ||
+        event.type === "run_turns_exceeded";
+    if (terminal) {
+        const { lastEventAt: _ended, retry: _retry, recovery: _recovery, ...rest } = next;
+        return rest;
+    }
+    return { ...next, lastEventAt: Date.parse(event.timestamp) || Date.now() };
+}
+/** No event for this long: the footer says how long the run has been quiet. */
+export const QUIET_MS = 15_000;
+/** No event for this long: the footer marks the run as possibly stuck. */
+export const STALLED_MS = 60_000;
+/** A short, safe label from tool arguments: a title or a file name, never commands or URLs. */
+function shortArg(args) {
+    const input = parseArgs(args);
+    if (!input)
+        return "";
+    const first = Array.isArray(input.inputs) ? input.inputs[0] : {};
+    const value = [input.title, input.fileName, input.path, input.file_path, first?.path].find((v) => typeof v === "string" && v.trim() !== "");
+    if (!value)
+        return "";
+    return truncatePlain(oneLine(value.replace(/\\/g, "/").split("/").filter(Boolean).pop() ?? ""), 40);
+}
+/** What the live run is doing, from the transcript items and flags the events already update. */
+export function runPhase(view) {
+    if (view.compacting)
+        return { label: "compacting context", silentByDesign: false };
+    if (view.retry)
+        return {
+            label: `the model did not respond; retrying (${view.retry.attempt}/${view.retry.of})`,
+            silentByDesign: false,
+        };
+    if (view.recovery)
+        return {
+            label: `the response was cut off; retrying in smaller steps (${view.recovery.attempt}/${view.recovery.of})`,
+            silentByDesign: false,
+        };
+    const tool = view.items.findLast((i) => i.kind === "tool" && i.status !== "ok" && i.status !== "error");
+    if (tool?.kind === "tool") {
+        const name = tool.name.replace(/^p_[0-9a-f]{10}_/, "");
+        const arg = shortArg(tool.args);
+        const detail = arg ? ` (${arg})` : "";
+        if (tool.status === "approval")
+            return {
+                label: `waiting for your approval: ${humanizeToolName(name)}`,
+                silentByDesign: true,
+            };
+        if (name === "ask_user_question")
+            return { label: "waiting for your answer", silentByDesign: true };
+        if (name === "exit_plan")
+            return { label: "waiting for your plan decision", silentByDesign: true };
+        if (name === "task" || name === "task_wait")
+            return { label: "a sub-agent is working", silentByDesign: true };
+        if (name === "python_run")
+            return { label: `running Python${detail}`, silentByDesign: false };
+        if (name === "data_inspect" || name === "data_query")
+            return { label: `reading your data${detail}`, silentByDesign: false };
+        if (name === "artifact_create")
+            return { label: `publishing the artifact${detail}`, silentByDesign: false };
+        return { label: `running ${humanizeToolName(name)}${detail}`, silentByDesign: false };
+    }
+    const last = view.items.at(-1);
+    if (last?.kind === "assistant" && !last.done)
+        return {
+            label: last.text ? "writing the answer" : "thinking",
+            silentByDesign: false,
+        };
+    return { label: "waiting for the model", silentByDesign: false };
+}
+/** Milliseconds of silence worth reporting (0 when the run is busy, or silent by design). */
+export function quietFor(view, now) {
+    if (view.lastEventAt === undefined || runPhase(view).silentByDesign)
+        return 0;
+    const idle = Math.max(0, now - view.lastEventAt);
+    return idle >= QUIET_MS ? idle : 0;
+}
+/** What the retried request produced (or the end of the turn) ends the retry label. */
+const RETRY_ENDERS = new Set([
+    "text_delta",
+    "reasoning_delta",
+    "turn_completed",
+    "tool_started",
+    "compaction_started",
+]);
+function reduceEventItems(state, event) {
+    if ((state.retry || state.recovery) && RETRY_ENDERS.has(event.type)) {
+        const { retry: _retry, recovery: _recovery, ...rest } = state;
+        return reduceEventItems(rest, event);
+    }
     const d = (event.data ?? {});
     const at = Date.parse(event.timestamp);
     switch (event.type) {
@@ -385,9 +682,9 @@ export function reduceEvent(state, event) {
                 stats: withModel({ ...state.stats, runs: state.stats.runs + 1 }, d.model),
             };
         case "text_delta":
-            return appendAssistant(state, "text", String(d.delta ?? ""));
+            return appendAssistant(state, "text", String(d.delta ?? ""), at);
         case "reasoning_delta":
-            return appendAssistant(state, "reasoning", String(d.delta ?? ""));
+            return appendAssistant(state, "reasoning", String(d.delta ?? ""), at);
         case "turn_completed": {
             const usage = d.usage;
             const last = state.items.at(-1);
@@ -409,15 +706,18 @@ export function reduceEvent(state, event) {
                 },
             };
         }
-        case "tool_started":
+        case "tool_started": {
+            const name = String(d.name ?? "tool");
             return addItem(state, {
                 kind: "tool",
                 id: String(d.id ?? ""),
-                name: String(d.name ?? "tool"),
+                name,
                 args: typeof d.arguments === "string" ? d.arguments : "",
                 summary: summarizeToolArgs(String(d.name ?? ""), typeof d.arguments === "string" ? d.arguments : ""),
                 status: "running",
+                toolKind: toolKindOf(name, typeof d.effect === "string" ? d.effect : undefined),
             });
+        }
         case "approval_requested":
             return updateTool(state, d.id, { status: "approval" });
         case "approval_resolved":
@@ -429,6 +729,9 @@ export function reduceEvent(state, event) {
                 status: d.isError ? "error" : "ok",
                 ...(typeof d.durationMs === "number" ? { durationMs: d.durationMs } : {}),
                 ...(typeof d.preview === "string" ? { preview: d.preview } : {}),
+                ...exitCodePart(d.preview),
+                ...(isUiBlock(d.ui) ? { ui: d.ui } : {}),
+                ...(isImagePart(d.image) ? { image: d.image } : {}),
             });
             return {
                 ...next,
@@ -443,7 +746,8 @@ export function reduceEvent(state, event) {
         }
         case "run_completed":
         case "run_failed":
-        case "run_cancelled": {
+        case "run_cancelled":
+        case "run_turns_exceeded": {
             const ended = {
                 ...state,
                 streaming: false,
@@ -455,6 +759,11 @@ export function reduceEvent(state, event) {
             };
             if (event.type === "run_failed")
                 return addItem(ended, { kind: "error", text: String(d.error ?? "Run failed") });
+            if (event.type === "run_turns_exceeded")
+                return addItem(ended, {
+                    kind: "notice",
+                    text: "Turn limit reached — the answer may be incomplete. Continue with another prompt or raise limits.maxTurns (/settings → Max turns).",
+                });
             if (event.type === "run_cancelled") {
                 const reason = String(d.error ?? "cancelled");
                 return addItem(ended, {
@@ -464,6 +773,10 @@ export function reduceEvent(state, event) {
             }
             return ended;
         }
+        case "truncation_recovery":
+            return { ...state, recovery: { attempt: Number(d.attempt) || 1, of: Number(d.of) || 1 } };
+        case "request_retry":
+            return { ...state, retry: { attempt: Number(d.attempt) || 1, of: Number(d.of) || 1 } };
         case "compaction_started":
             return { ...state, compacting: true };
         case "compaction_completed": {
@@ -505,7 +818,9 @@ export function reduceEvent(state, event) {
         case "response_truncated":
             return addItem(state, {
                 kind: "notice",
-                text: "Response cut by max output tokens — the answer may be incomplete. Raise limits.maxOutputTokens to allow longer answers.",
+                text: `Response cut by max output tokens${typeof d.maxOutputTokens === "number"
+                    ? ` (${d.maxOutputTokens} tokens, ${describeOutputLimitSource(d.source)})`
+                    : ""} — the answer may be incomplete. Raise limits.maxOutputTokens (/settings → Agent max output tokens) to allow longer answers.`,
             });
         case "model_changed":
             return {
@@ -532,6 +847,455 @@ export function lastAssistantText(items) {
     }
     return undefined;
 }
+/**
+ * True when a printable key should copy the last assistant response instead of typing: bound to
+ * `c`/`y` (and uppercase) on an EMPTY editor line, while no autocomplete is showing and no turn
+ * is running — the same "empty input" convention Enter and Ctrl+D already use. A non-empty input
+ * never triggers, so typing `c` or `y` mid-message is unaffected.
+ */
+export function editorCopyKey(data, input) {
+    return ((data === "c" || data === "C" || data === "y" || data === "Y") &&
+        input.text === "" &&
+        !input.autocomplete &&
+        !input.busy);
+}
+/** True when an unknown event value is a `Node` of a tree UI block. */
+export function isTreeNode(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    if (typeof record.label !== "string")
+        return false;
+    if (record.meta !== undefined && typeof record.meta !== "string")
+        return false;
+    if (record.children !== undefined && !Array.isArray(record.children))
+        return false;
+    return record.children === undefined || record.children.every(isTreeNode);
+}
+/** True when an unknown event value is an Alisio `UiBlock` (validated defensively). */
+export function isUiBlock(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const block = value;
+    switch (block.kind) {
+        case "artifact": {
+            const a = block.artifact;
+            return (!!a &&
+                typeof a === "object" &&
+                typeof a.id === "string" &&
+                typeof a.fileName === "string" &&
+                typeof a.kind === "string" &&
+                typeof a.bytes === "number" &&
+                typeof a.status === "string");
+        }
+        case "table":
+            return (Array.isArray(block.columns) &&
+                block.columns.every((c) => typeof c === "string") &&
+                Array.isArray(block.rows) &&
+                block.rows.every((r) => Array.isArray(r) && r.every((c) => typeof c === "string")) &&
+                (block.caption === undefined || typeof block.caption === "string"));
+        case "key-value":
+            return (Array.isArray(block.entries) &&
+                block.entries.every((e) => Array.isArray(e) &&
+                    e.length === 2 &&
+                    typeof e[0] === "string" &&
+                    typeof e[1] === "string") &&
+                (block.caption === undefined || typeof block.caption === "string"));
+        case "tree":
+            return Array.isArray(block.nodes) && block.nodes.every(isTreeNode);
+        case "code":
+            return (typeof block.code === "string" &&
+                (block.lang === undefined || typeof block.lang === "string") &&
+                (block.caption === undefined || typeof block.caption === "string"));
+        case "markdown":
+            return typeof block.text === "string";
+        case "diff":
+            return optionalStrings(block, ["path", "patch", "before", "after", "lang", "caption"]);
+        case "terminal":
+            return (typeof block.output === "string" &&
+                optionalStrings(block, ["command", "cwd"]) &&
+                optionalNumbers(block, ["exitCode", "durationMs"]) &&
+                (block.truncated === undefined || typeof block.truncated === "boolean"));
+        case "mermaid":
+            return typeof block.source === "string" && optionalStrings(block, ["title"]);
+        case "math":
+            return (typeof block.latex === "string" &&
+                (block.display === undefined || typeof block.display === "boolean"));
+        case "json":
+            return ("value" in block &&
+                optionalNumbers(block, ["collapsedDepth"]) &&
+                optionalStrings(block, ["caption"]));
+        case "test-results":
+            return (optionalStrings(block, ["framework"]) &&
+                optionalNumbers(block, ["durationMs"]) &&
+                Array.isArray(block.suites) &&
+                block.suites.every((suite) => isRecord(suite) &&
+                    typeof suite.name === "string" &&
+                    optionalStrings(suite, ["file"]) &&
+                    Array.isArray(suite.cases) &&
+                    suite.cases.every((c) => isRecord(c) &&
+                        typeof c.name === "string" &&
+                        TEST_STATUSES.has(c.status) &&
+                        optionalStrings(c, ["error"]) &&
+                        optionalNumbers(c, ["durationMs", "line"]))));
+        case "progress":
+            return (optionalStrings(block, ["title"]) &&
+                Array.isArray(block.steps) &&
+                block.steps.every((step) => isRecord(step) &&
+                    typeof step.label === "string" &&
+                    PROGRESS_STATUSES.has(step.status) &&
+                    optionalStrings(step, ["detail"])));
+        default:
+            return false;
+    }
+}
+const TEST_STATUSES = new Set(["passed", "failed", "skipped", "todo"]);
+const PROGRESS_STATUSES = new Set(["pending", "running", "completed", "failed", "cancelled"]);
+const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const optionalStrings = (record, keys) => keys.every((key) => record[key] === undefined || typeof record[key] === "string");
+const optionalNumbers = (record, keys) => keys.every((key) => record[key] === undefined || typeof record[key] === "number");
+/** True when an unknown event value is a `{type:"image"}`-style part (mime + base64 data). */
+export function isImagePart(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.mimeType === "string" && typeof record.data === "string";
+}
+/**
+ * Display blocks the standard tools attach for the web UI only (spec §8.6): the TUI already
+ * shows the same content from the text (output rows, exit line), so rendering them would repeat it.
+ */
+const WEB_ONLY_UI = {
+    write_file: "diff",
+    edit_file: "diff",
+    shell: "terminal",
+    run_process: "terminal",
+};
+/** Rich (ui/image) parts of a persisted tool result, if any. */
+export function richPartsOf(result, toolName) {
+    if (!result)
+        return {};
+    const skip = toolName !== undefined && Object.hasOwn(WEB_ONLY_UI, toolName)
+        ? WEB_ONLY_UI[toolName]
+        : undefined;
+    const ui = result.content.find((part) => part.type === "ui" && part.block.kind !== skip);
+    const image = result.content.find((part) => part.type === "image");
+    return {
+        ...(ui?.type === "ui" ? { ui: ui.block } : {}),
+        ...(image?.type === "image" ? { image: { mimeType: image.mimeType, data: image.data } } : {}),
+    };
+}
+// ============================================================================
+// Tool presentation model — the pure extension point for transcript display.
+// Everything the TUI renders beyond a plain `TranscriptItem` is a
+// `TranscriptEntry`, and anything collapsible declares a `FoldCandidate` here,
+// so the renderer, the keybinding and (optionally) mouse clicks stay consistent
+// without importing pi-tui. Future block kinds hook in by extending these
+// shapes, never by special-casing components.
+// ============================================================================
+/** Words keyed by their canonical upper-case spelling that stay acronyms when humanized. */
+const ACRONYM_WORDS = new Set([
+    "MCP",
+    "HTTP",
+    "HTTPS",
+    "URL",
+    "API",
+    "CLI",
+    "JSON",
+    "CSV",
+    "XML",
+    "HTML",
+    "SQL",
+    "SQLITE",
+    "DNS",
+    "SSH",
+    "IP",
+    "ID",
+    "DB",
+    "UI",
+    "OS",
+    "IDE",
+    "TUI",
+    "PNG",
+    "SVG",
+    "PDF",
+    "YAML",
+    "TOML",
+    "2FA",
+    "V2",
+]);
+/**
+ * `read_file` → `Read File`, `search_text` → `Search Text`, `mcp_devforge_time_diff` →
+ * `MCP · Devforge Time Diff`. Splits on `_`/`-`/`.`/spaces, keeps known acronyms (MCP, HTTP…)
+ * and bare numeric suffixes (`read_file_2` → `Read File 2`). The machine name stays available
+ * dimmed in grouped detail rows and in the `/tools` and `/stats` reports.
+ */
+export function humanizeToolName(name) {
+    const trimmed = name.trim();
+    let rest = trimmed;
+    let prefix = "";
+    const mcp = /^mcp_/i.exec(rest);
+    if (mcp) {
+        prefix = "MCP · ";
+        rest = rest.slice(mcp[0].length);
+    }
+    const words = rest
+        .split(/[_\-. /]+/)
+        .filter(Boolean)
+        .map((word) => {
+        const upper = word.toUpperCase();
+        if (ACRONYM_WORDS.has(upper))
+            return upper;
+        if (/^\d+$/.test(upper))
+            return upper;
+        return `${word[0]?.toUpperCase() ?? ""}${word.slice(1).toLowerCase()}`;
+    });
+    return words.length ? `${prefix}${words.join(" ")}` : trimmed;
+}
+/** Verb and count noun used by grouped batch rows per tool kind. */
+export const TOOL_KIND_VERB = {
+    read: "Explored",
+    write: "Edited",
+    process: "Ran",
+    mcp: "Queried",
+    internal: "Ran",
+    other: "Called",
+};
+export const TOOL_KIND_WORD = {
+    read: "reads",
+    write: "files",
+    process: "commands",
+    mcp: "calls",
+    internal: "tasks",
+    other: "calls",
+};
+/**
+ * Capability kind of a tool call. Live events carry the registry `effect` (exact); replayed
+ * history falls back to conservative name heuristics. `mcp_*` is always the mcp kind.
+ */
+export function toolKindOf(name, effect) {
+    if (name.startsWith("mcp_"))
+        return "mcp";
+    switch (effect) {
+        case "read":
+        case "write":
+        case "process":
+        case "internal":
+            return effect;
+        default:
+            break;
+    }
+    if (/^(read|search|list|git|context|ask|web|fetch)_/.test(name))
+        return "read";
+    if (/^(write|edit|append|delete|rename|move|mkdir|patch)_/.test(name))
+        return "write";
+    if (/^(run|shell|execute)/.test(name))
+        return "process";
+    if (name === "task" || name.startsWith("task_"))
+        return "internal";
+    return "other";
+}
+/** Terminal-preview caps for collapsed rows (same values the renderer always used). */
+export const OUTPUT_PREVIEW_LINES_OK = 3;
+export const OUTPUT_PREVIEW_LINES_ERROR = 6;
+export const previewLinesFor = (status) => status === "error" ? OUTPUT_PREVIEW_LINES_ERROR : OUTPUT_PREVIEW_LINES_OK;
+/** Preview rows as the renderer shows them: blank lines dropped, tabs kept for the caller to expand. */
+export const previewRows = (preview) => preview.split("\n").filter((line) => line.trim());
+/** True when the preview exceeds the collapsed cap (the row becomes a collapsible "output"). */
+export function previewTruncated(preview, status) {
+    return !!preview && previewRows(preview).length > previewLinesFor(status);
+}
+/**
+ * Exit code derived safely from a text preview. `run_process`/`shell`/`search_text` return
+ * `{stdout, stderr, exitCode, truncated}` JSON; read-effect tools may carry an appended
+ * `\n<instructions>…` block, retried on the JSON prefix. Any other shape yields nothing.
+ */
+export function exitCodeOf(preview) {
+    if (!preview)
+        return undefined;
+    const codeOf = (text) => {
+        try {
+            const value = JSON.parse(text);
+            const code = value && typeof value === "object" && !Array.isArray(value)
+                ? value.exitCode
+                : undefined;
+            return typeof code === "number" ? code : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const direct = codeOf(preview);
+    if (direct !== undefined)
+        return direct;
+    const cut = preview.indexOf("\n<instructions>");
+    if (cut > 0)
+        return codeOf(preview.slice(0, cut));
+    return undefined;
+}
+const exitCodePart = (preview) => {
+    if (typeof preview !== "string")
+        return {};
+    const code = exitCodeOf(preview);
+    return code === undefined ? {} : { exitCode: code };
+};
+export function toolItemView(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        humanName: humanizeToolName(item.name),
+        kind: item.toolKind ?? toolKindOf(item.name),
+        summary: item.summary,
+        status: item.status,
+        ...(item.durationMs !== undefined ? { durationMs: item.durationMs } : {}),
+        ...(item.preview !== undefined ? { preview: item.preview } : {}),
+        ...(item.ui ? { ui: item.ui } : {}),
+        ...(item.image ? { image: item.image } : {}),
+        ...(item.exitCode !== undefined ? { exitCode: item.exitCode } : {}),
+    };
+}
+/**
+ * Consecutive tool calls of the same kind whose statuses are ALL terminal (ok/error) merge into
+ * one `group` entry; running/approval calls always stay singleton so their spinner and live state
+ * stay visible. A kind change splits the run (`read` never merges with `shell`). Order is
+ * preserved; every entry carries its index within `items` (fold keys for assistant items need
+ * it). One linear pass — called on state changes only, never per frame.
+ */
+export function groupToolEntries(items) {
+    const out = [];
+    let run = [];
+    let runKind;
+    const flush = () => {
+        if (!run.length)
+            return;
+        const views = run.map((r) => toolItemView(r.item));
+        const first = views[0];
+        const groupable = views.length > 1 &&
+            first !== undefined &&
+            views.every((v) => v.kind === runKind) &&
+            views.every((v) => v.status === "ok" || v.status === "error");
+        if (groupable) {
+            const sameName = views.every((v) => v.name === first.name);
+            out.push({
+                entry: {
+                    kind: "group",
+                    group: {
+                        id: first.id,
+                        members: views,
+                        kind: first.kind,
+                        status: views.some((v) => v.status === "error") ? "error" : "ok",
+                        totalMs: views.reduce((sum, v) => sum + (v.durationMs ?? 0), 0),
+                        label: sameName ? first.humanName : TOOL_KIND_VERB[first.kind],
+                        word: TOOL_KIND_WORD[first.kind],
+                    },
+                },
+                at: run[0]?.at ?? 0,
+            });
+        }
+        else {
+            for (const r of run)
+                out.push({ entry: r.item, at: r.at });
+        }
+        run = [];
+        runKind = undefined;
+    };
+    items.forEach((item, at) => {
+        if (item.kind === "tool") {
+            const kind = item.toolKind ?? toolKindOf(item.name);
+            if (runKind === undefined) {
+                runKind = kind;
+                run.push({ item, at });
+            }
+            else if (runKind === kind) {
+                run.push({ item, at });
+            }
+            else {
+                flush();
+                runKind = kind;
+                run.push({ item, at });
+            }
+        }
+        else {
+            flush();
+            out.push({ entry: item, at });
+        }
+    });
+    flush();
+    return out;
+}
+/** Content identity of a group (fold/diff purposes): member ids, statuses and durations. */
+export function groupIdentity(group) {
+    return `${group.id}|${group.members.length}|${group.members
+        .map((m) => `${m.id}:${m.status}:${m.durationMs ?? ""}`)
+        .join(",")}`;
+}
+/** Cap for the reasoning text when expanded; longer sections show a truncation note. */
+export const REASONING_EXPAND_MAX_LINES = 40;
+/**
+ * The fold contract of one transcript entry: nothing (not collapsible), or a candidate with its
+ * default state. `at` is the entry's index within the ORIGINAL items array (assistant fold keys
+ * are stable because transcript items are append-only).
+ */
+export function foldCandidateOf(entry, at) {
+    if (entry.kind === "assistant") {
+        const reasoning = entry.reasoning.trim();
+        if (!reasoning || !(entry.done || entry.text))
+            return undefined;
+        return { key: `a:${at}`, kind: "reasoning", defaultExpanded: false };
+    }
+    if (entry.kind === "group")
+        return { key: `g:${entry.group.id}`, kind: "group", defaultExpanded: false };
+    if (entry.kind === "tool") {
+        if (entry.status === "running" || entry.status === "approval")
+            return undefined;
+        // Rich blocks keep their native rendering (tables/trees/images are already bounded);
+        // only plain text output folds when it exceeds the collapsed cap.
+        if (entry.ui || entry.image)
+            return undefined;
+        if (previewTruncated(entry.preview, entry.status))
+            return { key: `t:${entry.id}`, kind: "output", defaultExpanded: false };
+        return undefined;
+    }
+    return undefined;
+}
+/** Stable key of a transcript entry (used by the component sync to reuse row instances). */
+export function entryKeyOf(entry, at) {
+    switch (entry.kind) {
+        case "assistant":
+            return `a:${at}`;
+        case "group":
+            return `g:${entry.group.id}`;
+        case "tool":
+            return `t:${entry.id}`;
+        case "user":
+            return `u:${at}`;
+        case "notice":
+            return `n:${at}`;
+        case "info":
+            return `i:${at}`;
+        case "error":
+            return `e:${at}`;
+    }
+}
+/** Every fold candidate of the transcript in display order; the keybinding targets the last one. */
+export function foldCandidates(items) {
+    const candidates = [];
+    for (const { entry, at } of groupToolEntries(items)) {
+        const candidate = foldCandidateOf(entry, at);
+        if (candidate)
+            candidates.push(candidate);
+    }
+    return candidates;
+}
+/**
+ * True when a printable key should toggle the nearest collapsible transcript row instead of
+ * typing: bound to `x`/`X` on an EMPTY editor line (no autocomplete), the same "empty input"
+ * convention Enter, Ctrl+D and `c`/`y` already use. Unlike copy, it also works while a turn runs
+ * (the nearest candidate may still exist mid-stream). A non-empty input never triggers.
+ */
+export function foldToggleKey(data, input) {
+    return (data === "x" || data === "X") && input.text === "" && !input.autocomplete;
+}
 /** Rebuilds transcript items from persisted history (used by /resume). */
 export function itemsFromHistory(messages) {
     const items = [];
@@ -547,6 +1311,11 @@ export function itemsFromHistory(messages) {
                 items.push({ kind: "assistant", text: m.text, reasoning: "", done: true });
             for (const c of m.calls) {
                 const r = results.get(c.id);
+                const preview = r?.result.content
+                    .filter((p) => p.type === "text")
+                    .map((x) => x.text)
+                    .join("\n")
+                    .slice(0, 2_000);
                 items.push({
                     kind: "tool",
                     id: c.id,
@@ -554,10 +1323,10 @@ export function itemsFromHistory(messages) {
                     args: c.arguments,
                     summary: summarizeToolArgs(c.name, c.arguments),
                     status: r?.result.isError ? "error" : "ok",
-                    preview: r?.result.content
-                        .map((x) => x.text)
-                        .join("\n")
-                        .slice(0, 2_000),
+                    preview,
+                    toolKind: toolKindOf(c.name),
+                    ...exitCodePart(preview),
+                    ...richPartsOf(r?.result, c.name),
                 });
             }
         }