@hheei/pi-ext-ui 0.5.2 → 0.7.0

package/dist/message-view.js

@@ -1,4 +1,5 @@
-import { truncateToWidth, wrapTextWithAnsi, } from "@earendil-works/pi-tui";
+import { Box, truncateToWidth, wrapTextWithAnsi, } from "@earendil-works/pi-tui";
+import { backgroundFill } from "./background.js";
 import { toContentRows, toSingleRow } from "./tool-view.js";
 /**
  * A transcript notice, not a tool execution.
@@ -59,10 +60,22 @@ export class MessageView {
     #localExpanded;
     #lastWidth = 80;
     #lastHeight = 0;
+    /** The final rows the host draws: the background shell's output, not the pre-shell lines. */
     #cache;
+    /** The rows the shell currently fills; replaced on every layout. */
+    #shellRows = [];
+    /**
+     * The block background a standalone message owns. Pi's custom-message shell only draws its own
+     * `customMessageBg` box when no renderer is installed, so this view supplies the same block
+     * itself. Inside an activity group the rows come from `previewRows`/`bodyRows` and keep the
+     * group's background instead.
+     */
+    #shell = new Box(0, 0);
     constructor(spec) {
         this.#spec = spec;
         this.#localExpanded = remembered(spec.stateHolder, spec.defaultExpanded === true);
+        this.#shell.addChild({ render: () => this.#shellRows, invalidate() { } });
+        this.#shell.setBgFn(backgroundFill(spec.theme, "customMessageBg"));
     }
     get expandable() {
         return hasRows(this.#spec.body);
@@ -91,27 +104,26 @@ export class MessageView {
         const safeWidth = Math.max(1, width - pad * 2);
         this.#lastWidth = width;
         const leftPad = pad > 0 ? " ".repeat(pad) : "";
-        const lines = [
+        this.#shellRows = [
             this.#header(safeWidth, expanded),
             ...layRows(this.#spec.preview, safeWidth),
             ...(expanded ? layRows(this.#spec.body, safeWidth) : []),
         ].map((line) => (leftPad === "" ? line : `${leftPad}${line}`));
-        this.#lastHeight = lines.length;
+        this.#lastHeight = this.#shellRows.length;
+        // Cache the shell's output: a cached hit must return the same filled, padded rows.
+        const lines = this.#shell.render(width);
         this.#cache = { width, expanded, lines };
         return lines;
     }
     invalidate() {
         this.#cache = undefined;
+        this.#shell.invalidate();
         invalidateRows(this.#spec.preview);
         invalidateRows(this.#spec.body);
     }
     handleMouse(event) {
-        if (!this.expandable ||
-            event.type === "wheel" ||
-            event.type !== "click" ||
-            event.button !== "left") {
+        if (!this.expandable || event.type !== "click" || event.button !== "left")
             return undefined;
-        }
         const effectiveWidth = event.width > 0 ? event.width : this.#lastWidth;
         const pad = Math.max(0, this.#spec.outputPad ?? 0);
         const innerX = event.x - pad;
@@ -125,6 +137,24 @@ export class MessageView {
         this.toggle();
         return { handled: true, render: true };
     }
+    /** Provider-declared notice type, used to group notices without reading their text. */
+    get kind() {
+        return this.#spec.header.kind;
+    }
+    /** Preview rows inside an activity group: visible content below the summary, folded or not. */
+    previewRows(width) {
+        return this.#rows(this.#spec.preview, width);
+    }
+    /** Body rows inside an activity group: what opening this notice reveals. */
+    bodyRows(width) {
+        return this.#rows(this.#spec.body, width);
+    }
+    #rows(source, width) {
+        const pad = Math.max(0, this.#spec.outputPad ?? 0);
+        const safeWidth = Math.max(1, width - pad * 2);
+        const leftPad = pad > 0 ? " ".repeat(pad) : "";
+        return layRows(source, safeWidth).map((line) => (leftPad === "" ? line : `${leftPad}${line}`));
+    }
     /** Single-row label used when this notice sits inside an activity group. */
     get activitySummary() {
         const { theme, header } = this.#spec;

package/dist/native-tools.d.ts

@@ -0,0 +1,69 @@
+import { type AgentToolResult, type Theme } from "@earendil-works/pi-coding-agent";
+import { type NestedCallRecord } from "./payload-parser.js";
+import type { ToolStatusKind } from "./tool-view.js";
+import type { CapturedToolCall } from "./tracker.js";
+/**
+ * The single owner of Pi's own tool vocabulary in this UI. Concrete tool packages state their own
+ * semantics through ext-core's presentation point; this module is the explicit adapter for the tools
+ * Pi itself ships (read, write, edit, bash, grep, find, codemode, python_eval and the background and
+ * subagent helpers), so a top-level row, a nested row and a restored row read the same facts.
+ */
+export declare const EDIT_TOOL_NAME = "edit";
+export declare const WRITE_TOOL_NAME = "write";
+export declare const CODEMODE_OPTIONS_PREFIX = "// @options:";
+export declare function toolPath(args: unknown): string;
+/**
+ * A native tool's header summary. read states its own tokens, bash keeps its command as the row's
+ * content, and the rest state their argument vocabulary; undefined means the frame falls back to the
+ * generic argument line.
+ */
+export interface NativeHeaderSummary {
+    readonly summary: string;
+    /** Whether the summary already carries the tool's own colors. */
+    readonly styled: boolean;
+    /** Whether secondary facts stay in the summary or move to the dim meta slot. */
+    readonly factsInSummary: boolean;
+}
+export declare function nativeHeaderSummary(toolName: string, args: unknown, theme: Theme, cwd: string): NativeHeaderSummary | undefined;
+/** The syntax a tool's request is written in, for display only. */
+export declare function nativeCodeLanguage(toolName: string): string | undefined;
+/** The language a tool's own output is written in, when the tool states it through its arguments. */
+export declare function nativeOutputLanguage(toolName: string, args: unknown): string | undefined;
+/** A deadline is a secondary fact about a call, not part of what the tool was asked to do. */
+export declare function nativeTimeoutFact(toolName: string, args: unknown): string | undefined;
+/** The request block a call is drawn from: its bytes, its syntax, and whether it is a shell command. */
+export interface NativeRequestBlock {
+    readonly text: string;
+    readonly language: string | undefined;
+    readonly shell: boolean;
+}
+export declare function nativeRequestBlock(toolName: string, args: unknown): NativeRequestBlock | undefined;
+/**
+ * The request a heavy-input tool received, byte for byte: a copy of it must not trim or sanitize
+ * model-controlled text. Only an all-whitespace request has no body, so it reads as no request.
+ */
+export declare function nativeHeavyRequest(toolName: string, args: unknown): string | undefined;
+export declare function nativeSummaryArg(toolName: string, args: unknown): string;
+/** The one-row result text a native tool reports, plus the wall time codemode states in its header. */
+export declare function nativeResultText(toolName: string, result: AgentToolResult<unknown>): {
+    readonly outputText: string;
+    readonly wallTimeSeconds: number | undefined;
+};
+/** Compact nested-row result: a one-line summary plus the status it reports. */
+export interface InlinePresentation {
+    readonly summary: string;
+    readonly status: ToolStatusKind;
+}
+/**
+ * One compact nested summary for a tool call. Adopts the tool's standard collapsed
+ * single-line format when recognized, degrading to undefined so callers can use
+ * the default argument rendering.
+ */
+export declare function inlinePresentation(toolName: string, args: unknown, details: unknown, isError: boolean): InlinePresentation | undefined;
+/**
+ * The request bytes one call carries. A record whose request the session truncated has none: copying
+ * the size-limited preview or the summary would present a partial request as the full one.
+ */
+export declare function nativeRequestCopy(call: CapturedToolCall | NestedCallRecord): string | undefined;
+/** What a child row copies: its own request when it has one, otherwise the result it produced. */
+export declare function extractChildToolCopyText(call: CapturedToolCall | NestedCallRecord, full?: boolean): string;

package/dist/native-tools.js

@@ -0,0 +1,414 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getLanguageFromPath, } from "@earendil-works/pi-coding-agent";
+import { getCapabilities, hyperlink, stripTerminalSequences } from "@earendil-works/pi-tui";
+import { diffStats } from "./diff-view.js";
+import { formatTimeoutFact, isRecord, parseCallArgs, } from "./payload-parser.js";
+/**
+ * The single owner of Pi's own tool vocabulary in this UI. Concrete tool packages state their own
+ * semantics through ext-core's presentation point; this module is the explicit adapter for the tools
+ * Pi itself ships (read, write, edit, bash, grep, find, codemode, python_eval and the background and
+ * subagent helpers), so a top-level row, a nested row and a restored row read the same facts.
+ */
+export const EDIT_TOOL_NAME = "edit";
+export const WRITE_TOOL_NAME = "write";
+export const CODEMODE_OPTIONS_PREFIX = "// @options:";
+const CODEMODE_SCRIPT_HEADER = /^Script (?:completed|failed)\r?\nWall time ([\d.]+) seconds\r?\nOutput:\r?\n/;
+// Pi <1.3 has no exported read-range formatter. Keep this UI summary independent of that export.
+function readLineNumber(value) {
+    const parsed = typeof value === "number"
+        ? value
+        : typeof value === "string" && value.trim() !== ""
+            ? Number(value)
+            : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** The read line range as the native row draws it (`:12`, `:12-40`), or empty. */
+function readLineRange(args) {
+    const parsed = parseCallArgs(args);
+    const offset = parsed?.offset;
+    const limit = parsed?.limit;
+    if (offset == null && limit == null)
+        return "";
+    const start = offset == null ? 1 : readLineNumber(offset);
+    if (start === undefined)
+        return "";
+    if (limit == null)
+        return `:${start}`;
+    const count = readLineNumber(limit);
+    if (count === undefined)
+        return "";
+    const end = start + count - 1;
+    return `:${start}${end ? `-${end}` : ""}`;
+}
+function shortenHome(path) {
+    const home = homedir();
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+export function toolPath(args) {
+    const parsed = parseCallArgs(args);
+    if (!parsed)
+        return "";
+    const val = parsed.path ?? parsed.file_path;
+    return typeof val === "string" ? val.trim() : "";
+}
+/**
+ * read's header summary with the tokens the native read row uses: the accent path, linked to the
+ * file when the terminal draws OSC 8 links, followed by its warning line range.
+ */
+function readHeaderSummary(args, theme, cwd) {
+    const path = toolPath(args);
+    if (path === "")
+        return "";
+    const label = theme.fg("accent", shortenHome(path));
+    const linked = getCapabilities().hyperlinks
+        ? hyperlink(label, pathToFileURL(resolve(cwd, path)).href)
+        : label;
+    const range = readLineRange(args);
+    return `${linked}${range === "" ? "" : theme.fg("warning", range)}`;
+}
+export function nativeHeaderSummary(toolName, args, theme, cwd) {
+    if (toolName === "read") {
+        const semantic = readHeaderSummary(args, theme, cwd);
+        return semantic === "" ? undefined : { summary: semantic, styled: true, factsInSummary: false };
+    }
+    if (toolName === "bash") {
+        return { summary: nativeSummaryArg(toolName, args), styled: false, factsInSummary: false };
+    }
+    const summary = nativeSummaryArg(toolName, args);
+    return summary === "" ? undefined : { summary, styled: false, factsInSummary: true };
+}
+/** The syntax a tool's request is written in, for display only. */
+export function nativeCodeLanguage(toolName) {
+    if (toolName === "bash")
+        return "bash";
+    if (toolName === "codemode")
+        return "javascript";
+    if (toolName === "python_eval")
+        return "python";
+    return undefined;
+}
+/** The language a tool's own output is written in, when the tool states it through its arguments. */
+export function nativeOutputLanguage(toolName, args) {
+    if (toolName !== "read")
+        return undefined;
+    const path = toolPath(args);
+    return path === "" ? undefined : getLanguageFromPath(path);
+}
+/** A deadline is a secondary fact about a call, not part of what the tool was asked to do. */
+export function nativeTimeoutFact(toolName, args) {
+    if (toolName !== "bash")
+        return undefined;
+    const timeout = isRecord(args) ? args.timeout : undefined;
+    if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)
+        return undefined;
+    return formatTimeoutFact(timeout * 1000);
+}
+export function nativeRequestBlock(toolName, args) {
+    const text = nativeHeavyRequest(toolName, args);
+    if (text === undefined)
+        return undefined;
+    return { text, language: nativeCodeLanguage(toolName), shell: toolName === "bash" };
+}
+/**
+ * The request a heavy-input tool received, byte for byte: a copy of it must not trim or sanitize
+ * model-controlled text. Only an all-whitespace request has no body, so it reads as no request.
+ */
+export function nativeHeavyRequest(toolName, args) {
+    if (!isRecord(args))
+        return undefined;
+    const raw = toolName === "bash" && typeof args.command === "string"
+        ? args.command
+        : toolName === "python_eval" && typeof args.code === "string"
+            ? args.code
+            : toolName === "codemode" && typeof args.code === "string"
+                ? args.code
+                : undefined;
+    return raw === undefined || raw.trim() === "" ? undefined : raw;
+}
+export function nativeSummaryArg(toolName, args) {
+    if (toolName === "codemode") {
+        return extractCodemodeHeaderFacts(args);
+    }
+    const parsed = parseCallArgs(args);
+    if (!parsed)
+        return "";
+    const firstLine = (val) => {
+        if (typeof val !== "string" || val.trim() === "")
+            return "";
+        const clean = stripTerminalSequences(val.trim());
+        return clean.split("\n")[0]?.trim() ?? clean;
+    };
+    switch (toolName) {
+        case "bash":
+        case "bg_bash_spawn":
+            return firstLine(parsed.command);
+        case "read":
+        case "edit":
+        case "write":
+        case "ls": {
+            const path = typeof parsed.path === "string"
+                ? parsed.path.trim()
+                : typeof parsed.file_path === "string"
+                    ? parsed.file_path.trim()
+                    : "";
+            return stripTerminalSequences(path);
+        }
+        case "grep":
+        case "find": {
+            const pattern = typeof parsed.pattern === "string" ? parsed.pattern.trim() : "";
+            const path = typeof parsed.path === "string" ? parsed.path.trim() : "";
+            if (!pattern)
+                return path ? stripTerminalSequences(path) : "";
+            const target = path && path !== "." ? ` ${path}` : "";
+            return `${pattern}${target}`;
+        }
+        case "python_eval":
+            return firstLine(parsed.code);
+        case "bg_bash_get":
+        case "bg_bash_stop":
+        case "agents_get":
+        case "agents_stop":
+            return typeof parsed.id === "string" ? parsed.id.trim() : "";
+        case "agents_delegate": {
+            const agent = typeof parsed.agent === "string" ? parsed.agent.trim() : "";
+            const id = typeof parsed.id === "string" ? parsed.id.trim() : "";
+            const task = firstLine(parsed.task);
+            if (agent && task)
+                return `${agent}: ${task}`;
+            return agent || id || task;
+        }
+        case "tool_search":
+            return typeof parsed.query === "string" ? parsed.query.trim() : "";
+        default:
+            return "";
+    }
+}
+/** codemode states its own options in the request's first line; they are header facts, not content. */
+function extractCodemodeHeaderFacts(args) {
+    if (!isRecord(args))
+        return "";
+    const options = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (key !== "code" && value !== undefined && value !== null) {
+            options[key] = value;
+        }
+    }
+    if (typeof args.code === "string") {
+        const firstLine = args.code.split(/\r?\n/, 1)[0]?.trim() ?? "";
+        if (firstLine.startsWith(CODEMODE_OPTIONS_PREFIX)) {
+            try {
+                const parsed = JSON.parse(firstLine.slice(CODEMODE_OPTIONS_PREFIX.length).trim());
+                if (isRecord(parsed)) {
+                    Object.assign(options, parsed);
+                }
+            }
+            catch { }
+        }
+    }
+    const facts = [];
+    const timeoutMs = typeof options.timeout_ms === "number" ? options.timeout_ms : undefined;
+    if (timeoutMs !== undefined)
+        facts.push(formatTimeoutFact(timeoutMs));
+    if (typeof options.max_output_tokens === "number") {
+        facts.push(`(tokens ${String(options.max_output_tokens)})`);
+    }
+    if (typeof options.target === "string" && options.target !== "local") {
+        facts.push(`(${options.target})`);
+    }
+    return facts.join(" ");
+}
+/** The one-row result text a native tool reports, plus the wall time codemode states in its header. */
+export function nativeResultText(toolName, result) {
+    const parts = [];
+    for (const block of result.content) {
+        if (block.type === "text" && block.text.trim() !== "") {
+            parts.push(block.text);
+        }
+    }
+    const joined = parts.join("\n");
+    if (toolName === "codemode") {
+        const stripped = stripTerminalSequences(joined);
+        const match = CODEMODE_SCRIPT_HEADER.exec(stripped);
+        const wallTimeSeconds = match?.[1] !== undefined ? Number.parseFloat(match[1]) : undefined;
+        const cleaned = joined.replace(CODEMODE_SCRIPT_HEADER, "").trim();
+        return { outputText: cleaned, wallTimeSeconds };
+    }
+    return { outputText: joined, wallTimeSeconds: undefined };
+}
+function fileToolPresentation(toolName, args, _details, isError) {
+    const path = toolPath(args);
+    if (toolName === "read") {
+        if (path === "")
+            return undefined;
+        return { summary: `${path}${readLineRange(args)}`, status: isError ? "error" : "ok" };
+    }
+    if (toolName === WRITE_TOOL_NAME) {
+        return path === "" ? undefined : { summary: path, status: isError ? "error" : "ok" };
+    }
+    return undefined;
+}
+/** Pi native edit persists a unified patch plus the same change as a numbered display diff. */
+function nativeDiffSource(details) {
+    if (!isRecord(details))
+        return undefined;
+    if (typeof details.patch === "string" && details.patch.trim() !== "") {
+        return { kind: "unifiedPatch", text: details.patch };
+    }
+    if (typeof details.diff === "string" && details.diff.trim() !== "") {
+        return displayDiffSource(details.diff);
+    }
+    return undefined;
+}
+function displayDiffSource(diff) {
+    const hunks = [];
+    let current = [];
+    let pendingBreak = false;
+    for (const raw of diff.split(/\r?\n/)) {
+        if (raw === "")
+            continue;
+        const sign = raw.charAt(0);
+        const match = /^ *(\d+)? ?(.*)$/.exec(raw.slice(1));
+        const lineNumber = match?.[1];
+        if (lineNumber === undefined) {
+            pendingBreak = true;
+            continue;
+        }
+        if (pendingBreak && current.length > 0) {
+            hunks.push(current);
+            current = [];
+        }
+        pendingBreak = false;
+        const kind = sign === "+" ? "add" : sign === "-" ? "del" : "ctx";
+        current.push({ kind, line: Number(lineNumber), text: match?.[2] ?? "" });
+    }
+    if (current.length === 0)
+        return undefined;
+    hunks.push(current);
+    return { kind: "hunks", hunks: hunks.map((lines) => ({ lines })) };
+}
+/**
+ * The name-free part of a summary for tools whose call arguments read well on their own. The tool
+ * name is the row's title, so repeating it here would print it twice.
+ */
+function formatArgumentSummary(toolName, parsed) {
+    const path = typeof parsed.path === "string"
+        ? parsed.path.trim()
+        : typeof parsed.file_path === "string"
+            ? parsed.file_path.trim()
+            : "";
+    switch (toolName) {
+        case "bash": {
+            // The row states model-controlled text: strip before cutting so no half sequence survives.
+            const cmd = typeof parsed.command === "string" ? stripTerminalSequences(parsed.command.trim()) : "";
+            if (!cmd)
+                return undefined;
+            return cmd.length > 70 ? `${cmd.slice(0, 67)}…` : cmd;
+        }
+        case "grep":
+        case "find": {
+            const pattern = typeof parsed.pattern === "string" ? parsed.pattern.trim() : "";
+            if (!pattern)
+                return undefined;
+            const target = path && path !== "." ? ` ${path}` : "";
+            return `${pattern}${target}`;
+        }
+        default: {
+            const keyArg = nativeSummaryArg(toolName, parsed);
+            return keyArg ? keyArg : undefined;
+        }
+    }
+}
+/**
+ * One compact nested summary for a tool call. Adopts the tool's standard collapsed
+ * single-line format when recognized, degrading to undefined so callers can use
+ * the default argument rendering.
+ */
+export function inlinePresentation(toolName, args, details, isError) {
+    const fileTool = fileToolPresentation(toolName, args, details, isError);
+    if (fileTool !== undefined)
+        return fileTool;
+    const parsed = parseCallArgs(args);
+    if (parsed === undefined)
+        return undefined;
+    if (toolName === EDIT_TOOL_NAME) {
+        const path = toolPath(parsed);
+        const source = isError ? undefined : nativeDiffSource(details);
+        const stats = source === undefined ? undefined : diffStats(source);
+        if (path === "" && stats === undefined)
+            return undefined;
+        return {
+            summary: stats === undefined
+                ? path
+                : `${path} (+${String(stats.added)} -${String(stats.removed)})`.trim(),
+            status: isError ? "error" : "ok",
+        };
+    }
+    const baseSummary = formatArgumentSummary(toolName, parsed);
+    if (baseSummary === undefined)
+        return undefined;
+    return {
+        summary: baseSummary,
+        status: isError ? "error" : "ok",
+    };
+}
+/**
+ * The request bytes one call carries. A record whose request the session truncated has none: copying
+ * the size-limited preview or the summary would present a partial request as the full one.
+ */
+export function nativeRequestCopy(call) {
+    if ("argsTruncated" in call && call.argsTruncated === true)
+        return undefined;
+    const args = "args" in call ? call.args : undefined;
+    if (!isRecord(args))
+        return undefined;
+    const toolName = "toolName" in call ? call.toolName : call.name;
+    if (toolName === "write" && typeof args.content === "string")
+        return args.content;
+    if (toolName === "bash" && typeof args.command === "string")
+        return args.command;
+    if ((toolName === "codemode" || toolName === "python_eval") && typeof args.code === "string") {
+        return args.code;
+    }
+    return undefined;
+}
+function resultText(result) {
+    if (result === undefined || !Array.isArray(result.content))
+        return undefined;
+    const texts = result.content
+        .filter((c) => isRecord(c) && c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text);
+    return texts.length === 0 ? undefined : texts.join("\n");
+}
+/** What a child row copies: its own request when it has one, otherwise the result it produced. */
+export function extractChildToolCopyText(call, full) {
+    const toolName = "toolName" in call ? call.toolName : call.name;
+    const result = "result" in call ? call.result : undefined;
+    const args = "args" in call ? call.args : undefined;
+    const request = nativeRequestCopy(call);
+    if (request !== undefined) {
+        // write's request is the whole file: its result only confirms the write.
+        if (full !== true || toolName === WRITE_TOOL_NAME)
+            return request;
+        const output = resultText(result);
+        return output === undefined ? request : `${request}\n---\n${output}`;
+    }
+    if (result !== undefined) {
+        const text = resultText(result);
+        if (text !== undefined)
+            return text;
+    }
+    if (args !== undefined) {
+        if (typeof args === "string")
+            return args;
+        try {
+            return JSON.stringify(args, null, 2);
+        }
+        catch {
+            return String(args);
+        }
+    }
+    // A summary is a summary: without arguments or a result there is no request to copy.
+    return "";
+}

package/dist/nested-calls-view.d.ts

@@ -1,16 +1,20 @@
 import { type Theme, type ToolRenderers } from "@earendil-works/pi-coding-agent";
 import { type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import type { ToolPresentationProvider } from "@hheei/pi-ext-core";
-import { type NestedCallRecord, type ToolRenderContext } from "./renderer.js";
+import type { NestedCallRecord, ToolRenderContext } from "./renderer.js";
 import { type Collapsible } from "./tool-view.js";
 import type { CapturedToolCall } from "./tracker.js";
-export declare function extractChildToolCopyText(call: CapturedToolCall | NestedCallRecord, full?: boolean): string;
 export interface NestedCallsViewProps {
     readonly resolvePresentation?: ((toolName: string) => ToolPresentationProvider | undefined) | undefined;
     readonly calls: readonly (CapturedToolCall | NestedCallRecord)[];
     readonly theme: Theme;
     readonly context: ToolRenderContext;
     readonly resolveChildRenderer?: ((toolName: string) => ToolRenderers | undefined) | undefined;
+    /**
+     * The owning layer's themed summary for a child call. A board cannot recover a child's semantic
+     * tokens from text, so the layer that owns that tool states them here.
+     */
+    readonly headerSummary?: ((toolName: string, args: unknown, theme: Theme) => string | undefined) | undefined;
     readonly copyToClipboard?: ((text: string) => Promise<void>) | undefined;
     readonly stateHolder?: Record<string, unknown> | undefined;
     readonly invalidate?: (() => void) | undefined;