@hheei/pi-ext-ui 0.1.0 → 0.2.0

package/dist/tool-view.d.ts

@@ -12,28 +12,69 @@ export interface ToolViewHeaderSpec {
     readonly title: string;
     readonly status?: ToolStatusKind | undefined;
     readonly summary?: string | undefined;
+    readonly unstyledSummary?: boolean | undefined;
 }
 export interface ToolViewCopySpec {
     readonly primary: string;
     readonly full?: string | undefined;
 }
+/** Micro-contract for child views that can reset their internal expansion. */
+export interface Collapsible {
+    collapseAll(): void;
+}
+export declare function isCollapsible(value: unknown): value is Collapsible;
 export interface ToolViewSpec {
     readonly theme: Theme;
     readonly header: ToolViewHeaderSpec;
-    readonly collapsedRows?: readonly string[] | Component | undefined;
+    readonly collapsedRows?: readonly string[] | Component | (Component & Collapsible) | undefined;
     readonly sections?: readonly RailSection[] | undefined;
+    readonly collapsibleChildren?: readonly Collapsible[] | undefined;
     readonly copy?: ToolViewCopySpec | undefined;
     readonly stateHolder?: unknown;
     readonly outputPad?: number | undefined;
     readonly defaultLevel?: FoldLevel | undefined;
+    readonly controlledLevel?: FoldLevel | undefined;
     readonly globalExpanded?: boolean | undefined;
     readonly invalidate?: (() => void) | undefined;
     readonly copyToClipboard?: ((text: string) => Promise<void>) | undefined;
     readonly copyFeedbackDurationMs?: number | undefined;
+    readonly noRail?: boolean | undefined;
+    readonly railToken?: RailColorToken | undefined;
 }
 /** Public composition entry point for extensions that need the shared view behavior. */
 export declare function createToolView(spec: ToolViewSpec): ToolView;
 export declare function transitionFoldLevel(current: FoldLevel, ctrlKey: boolean): FoldLevel;
+export declare function formatStatusGlyph(status: ToolStatusKind | undefined, theme: Theme): string;
+/**
+ * The glyph, name, and summary of one tool execution, colored the way every tool row colors them.
+ *
+ * A container tool draws one of these per child call, and so does the row of a tool that ran on its
+ * own. Both must agree, so the token assignment lives here rather than in each board: a board that
+ * assembled its own row painted the child's summary as a title, which read as one bright run and
+ * made a nested call look unlike the same call at top level. The caller owns the fold pin, the
+ * right-aligned action, and the width budget, which are the parts that actually differ.
+ */
+export declare function formatToolHeaderText(parts: {
+    readonly status?: ToolStatusKind | undefined;
+    readonly title: string;
+    readonly summary?: string | undefined;
+    readonly unstyledSummary?: boolean | undefined;
+}, theme: Theme): string;
+/**
+ * Collapses text that must occupy one row: header titles and summaries, board rows, and inline
+ * labels. A break inside one of them is a contract violation, because Pi writes one array element
+ * as one terminal row: `\n` moves to the next row without clearing it, and a lone `\r` returns to
+ * column 0 so later text overwrites the row's start. `visibleWidth` counts both as zero-width, so
+ * the host's per-row width guard cannot catch either, and the frame would silently grow taller
+ * than the rows it reports.
+ */
+export declare function toSingleRow(text: string): string;
+/**
+ * Splits multi-line content into rows. A lone `\r` is dropped rather than treated as a break so
+ * CRLF and progress-style output stay cell-safe, and tabs expand to two spaces so indentation does
+ * not depend on the terminal's tab stops.
+ */
+export declare function toContentRows(text: string): readonly string[];
 export declare class ToolView implements Component {
     #private;
     constructor(spec: ToolViewSpec);
@@ -45,9 +86,15 @@ export declare class ToolView implements Component {
     toggle(ctrlKey?: boolean): void;
     /** The result renderer of the same tool execution hides this row in place. */
     hide(): void;
+    /**
+     * Renders only the interior content of the view without the header row.
+     * When `noRail: true` is specified, outer rail glyphs are omitted, allowing
+     * clean embedding inside composite parent components without regex text scraping.
+     */
+    renderBody(width: number, options?: {
+        noRail?: boolean;
+    }): string[];
     render(width: number): string[];
     handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
     invalidate(): void;
 }
-export type { ToolViewSpec as CollapsibleToolFrameOptions };
-export { ToolView as CollapsibleToolFrame };

package/dist/tool-view.js

@@ -1,5 +1,11 @@
 import { copyToClipboard as copyToSystemClipboard, } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+export function isCollapsible(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "collapseAll" in value &&
+        typeof value.collapseAll === "function");
+}
 /** Public composition entry point for extensions that need the shared view behavior. */
 export function createToolView(spec) {
     return new ToolView(spec);
@@ -8,7 +14,6 @@ const FOLD_LEVEL_STATE_KEY = "__piExtUiFoldLevel";
 const COPIED_UNTIL_STATE_KEY = "__piExtUiCopiedUntil";
 const COPY_FEEDBACK_TIMER_KEY = "__piExtUiCopyTimer";
 const DEFAULT_MAX_SECTION_LINES = 9;
-const DEFAULT_MAX_COLLAPSED_ROWS = 6;
 const DEFAULT_COPY_FEEDBACK_MS = 1200;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -42,31 +47,80 @@ function isCopiedActive(stateHolder, localCopiedUntil) {
     const until = stateHolder[COPIED_UNTIL_STATE_KEY];
     return typeof until === "number" && until > now;
 }
-function formatStatusGlyph(status, theme) {
+export function formatStatusGlyph(status, theme) {
     switch (status ?? "ok") {
         case "streaming":
-            return `${theme.fg("muted", "⋯")} `;
+            return theme.fg("muted", "⋯");
         case "running":
-            return `${theme.fg("accent", "◐")} `;
+            return theme.fg("accent", "◐");
         case "ok":
-            return `${theme.fg("success", "✓")} `;
+            return theme.fg("success", "✓");
         case "warn":
-            return `${theme.fg("warning", "!")} `;
+            return theme.fg("warning", "!");
         case "error":
-            return `${theme.fg("error", "✗")} `;
+            return theme.fg("error", "✗");
         case "none":
             return "";
     }
 }
+/**
+ * The glyph, name, and summary of one tool execution, colored the way every tool row colors them.
+ *
+ * A container tool draws one of these per child call, and so does the row of a tool that ran on its
+ * own. Both must agree, so the token assignment lives here rather than in each board: a board that
+ * assembled its own row painted the child's summary as a title, which read as one bright run and
+ * made a nested call look unlike the same call at top level. The caller owns the fold pin, the
+ * right-aligned action, and the width budget, which are the parts that actually differ.
+ */
+export function formatToolHeaderText(parts, theme) {
+    const statusPart = formatStatusGlyph(parts.status, theme);
+    const title = toSingleRow(parts.title);
+    const titlePart = theme.fg("toolTitle", theme.bold(title));
+    const summaryRaw = parts.summary === undefined ? "" : toSingleRow(parts.summary);
+    const isUnstyled = parts.unstyledSummary === true || title === "bash";
+    const summaryPart = summaryRaw === "" ? "" : isUnstyled ? ` ${summaryRaw}` : ` ${theme.fg("dim", summaryRaw)}`;
+    return `${statusPart === "" ? "" : `${statusPart} `}${titlePart}${summaryPart}`;
+}
 const truncate = (text, width) => truncateToWidth(text, width, "…");
-function resolveLines(source, width) {
+/**
+ * Collapses text that must occupy one row: header titles and summaries, board rows, and inline
+ * labels. A break inside one of them is a contract violation, because Pi writes one array element
+ * as one terminal row: `\n` moves to the next row without clearing it, and a lone `\r` returns to
+ * column 0 so later text overwrites the row's start. `visibleWidth` counts both as zero-width, so
+ * the host's per-row width guard cannot catch either, and the frame would silently grow taller
+ * than the rows it reports.
+ */
+export function toSingleRow(text) {
+    if (!text.includes("\r") && !text.includes("\n") && !text.includes("\t")) {
+        return text.trim();
+    }
+    return text.replace(/[\r\n\t]+/g, " ").trim();
+}
+/**
+ * Splits multi-line content into rows. A lone `\r` is dropped rather than treated as a break so
+ * CRLF and progress-style output stay cell-safe, and tabs expand to two spaces so indentation does
+ * not depend on the terminal's tab stops.
+ */
+export function toContentRows(text) {
+    if (!text.includes("\r") && !text.includes("\t") && !text.includes("\n")) {
+        return [text];
+    }
+    return text.replace(/\r/g, "").replace(/\t/g, "  ").split("\n");
+}
+/**
+ * Resolves a row source into rows that are safe to hand to the host. A string element is one
+ * caller-provided label, so `normalize` decides whether it stays a single row or becomes several. A
+ * component returns rows it already laid out, so only its breaks are removed and its indentation is
+ * preserved.
+ */
+function resolveRows(source, width, normalize) {
     if (typeof source === "string") {
-        return source === "" ? [] : source.replace(/\r/g, "").replace(/\t/g, "  ").split("\n");
+        return source === "" ? [] : normalize(source);
     }
     if (Array.isArray(source)) {
-        return source.flatMap((item) => typeof item === "string" ? item.replace(/\r/g, "").replace(/\t/g, "  ").split("\n") : []);
+        return source.flatMap((item) => (typeof item === "string" ? normalize(item) : []));
     }
-    return source.render(width);
+    return source.render(width).flatMap((row) => toContentRows(row));
 }
 export class ToolView {
     #spec;
@@ -74,12 +128,42 @@ export class ToolView {
     #localCopiedUntil = 0;
     #localTimer;
     #lastWidth = 80;
+    #lastHeight = 0;
+    #cache;
     constructor(spec) {
         this.#spec = spec;
-        const initial = spec.defaultLevel ?? 0;
-        this.#localLevel = readFoldLevel(spec.stateHolder, initial);
+        const initial = spec.controlledLevel ?? spec.defaultLevel ?? 0;
+        this.#localLevel =
+            spec.controlledLevel !== undefined
+                ? spec.controlledLevel
+                : readFoldLevel(spec.stateHolder, initial);
+        if (isRecord(spec.stateHolder)) {
+            const until = spec.stateHolder[COPIED_UNTIL_STATE_KEY];
+            if (typeof until === "number" && until > Date.now()) {
+                this.#localCopiedUntil = until;
+                const remaining = until - Date.now();
+                if (!spec.stateHolder[COPY_FEEDBACK_TIMER_KEY]) {
+                    const timer = setTimeout(() => {
+                        this.#localCopiedUntil = 0;
+                        if (isRecord(this.#spec.stateHolder)) {
+                            this.#spec.stateHolder[COPIED_UNTIL_STATE_KEY] = 0;
+                            this.#spec.stateHolder[COPY_FEEDBACK_TIMER_KEY] = undefined;
+                        }
+                        this.#localTimer = undefined;
+                        this.#cache = undefined;
+                        this.#spec.invalidate?.();
+                    }, remaining);
+                    timer.unref?.();
+                    this.#localTimer = timer;
+                    spec.stateHolder[COPY_FEEDBACK_TIMER_KEY] = timer;
+                }
+            }
+        }
     }
     get foldLevel() {
+        if (this.#spec.controlledLevel !== undefined) {
+            return this.#spec.controlledLevel;
+        }
         return readFoldLevel(this.#spec.stateHolder, this.#localLevel);
     }
     get effectiveLevel() {
@@ -93,11 +177,26 @@ export class ToolView {
     get collapsed() {
         return this.foldLevel === 0;
     }
+    #collapseChildren() {
+        const { collapsedRows, collapsibleChildren } = this.#spec;
+        if (collapsibleChildren !== undefined) {
+            for (const child of collapsibleChildren) {
+                child.collapseAll();
+            }
+        }
+        if (isCollapsible(collapsedRows)) {
+            collapsedRows.collapseAll();
+        }
+    }
     setFoldLevel(next) {
         const prev = this.foldLevel;
         this.#localLevel = next;
-        writeFoldLevel(this.#spec.stateHolder, next);
+        if (this.#spec.controlledLevel === undefined) {
+            writeFoldLevel(this.#spec.stateHolder, next);
+        }
         if (prev !== next) {
+            this.#cache = undefined;
+            this.#collapseChildren();
             this.#spec.invalidate?.();
         }
     }
@@ -137,6 +236,7 @@ export class ToolView {
                 this.#spec.stateHolder[COPY_FEEDBACK_TIMER_KEY] = undefined;
             }
             this.#localTimer = undefined;
+            this.#cache = undefined;
             this.#spec.invalidate?.();
         }, durationMs);
         timer.unref?.();
@@ -150,11 +250,7 @@ export class ToolView {
         const safeWidth = Math.max(1, width);
         const pinGlyph = level === 0 ? "▸" : "▾";
         const pin = theme.fg("dim", pinGlyph);
-        const statusPart = formatStatusGlyph(header.status, theme);
-        const titlePart = theme.fg("toolTitle", theme.bold(header.title));
-        const summaryRaw = header.summary?.trim() ?? "";
-        const summaryPart = summaryRaw === "" ? "" : ` ${theme.fg("dim", summaryRaw)}`;
-        const leftContent = `${pin} ${statusPart}${titlePart}${summaryPart}`;
+        const leftContent = `${pin} ${formatToolHeaderText(header, theme)}`;
         if (copy === undefined || safeWidth < 6) {
             return truncate(leftContent, safeWidth);
         }
@@ -173,47 +269,40 @@ export class ToolView {
     /** The result renderer of the same tool execution hides this row in place. */
     hide() {
         this.#hidden = true;
+        this.#cache = undefined;
     }
-    render(width) {
+    /**
+     * Renders only the interior content of the view without the header row.
+     * When `noRail: true` is specified, outer rail glyphs are omitted, allowing
+     * clean embedding inside composite parent components without regex text scraping.
+     */
+    renderBody(width, options) {
         if (this.#hidden)
             return [];
         const pad = Math.max(0, this.#spec.outputPad ?? 0);
         const safeWidth = Math.max(1, width - pad * 2);
-        this.#lastWidth = width;
         const level = this.effectiveLevel;
         const { theme, collapsedRows, sections } = this.#spec;
-        const output = [this.#renderHeader(safeWidth, level)];
-        const finalize = (lines) => {
-            if (pad > 0) {
-                const leftPad = " ".repeat(pad);
-                return lines.map((line) => `${leftPad}${line}`);
-            }
-            return lines;
-        };
-        const innerWidth = Math.max(1, safeWidth - 2);
+        const noRail = options?.noRail ?? this.#spec.noRail ?? false;
+        const innerWidth = noRail ? safeWidth : Math.max(1, safeWidth - 2);
+        const output = [];
         if (level === 0) {
             if (collapsedRows !== undefined) {
-                const rail = `${theme.fg("dim", "▎")} `;
-                const rows = resolveLines(collapsedRows, innerWidth);
-                const visibleRows = rows.length > DEFAULT_MAX_COLLAPSED_ROWS
-                    ? rows.slice(0, DEFAULT_MAX_COLLAPSED_ROWS)
-                    : rows;
-                for (const row of visibleRows) {
+                const railColor = this.#spec.header.status === "error" ? "error" : "dim";
+                const rail = noRail ? "" : `${theme.fg(railColor, "▎")} `;
+                const rows = resolveRows(collapsedRows, innerWidth, (row) => [toSingleRow(row)]);
+                for (const row of rows) {
                     output.push(truncate(rail + row, safeWidth));
                 }
-                if (rows.length > visibleRows.length) {
-                    const hint = theme.fg("dim", `… (${String(rows.length - visibleRows.length)} more)`);
-                    output.push(truncate(rail + hint, safeWidth));
-                }
             }
-            return finalize(output);
+            return output;
         }
         if (sections === undefined || sections.length === 0) {
-            return finalize(output);
+            return output;
         }
         for (const section of sections) {
-            const rail = `${theme.fg(section.railToken, "▎")} `;
-            const rawLines = resolveLines(section.content, innerWidth);
+            const rail = noRail ? "" : `${theme.fg(section.railToken, "▎")} `;
+            const rawLines = resolveRows(section.content, innerWidth, toContentRows);
             const cap = level === 1 ? (section.maxLines ?? DEFAULT_MAX_SECTION_LINES) : Number.POSITIVE_INFINITY;
             const visibleLines = Number.isFinite(cap) && rawLines.length > cap ? rawLines.slice(0, cap) : rawLines;
             const omittedCount = rawLines.length - visibleLines.length;
@@ -225,13 +314,48 @@ export class ToolView {
                 output.push(truncate(rail + hint, safeWidth));
             }
         }
-        return finalize(output);
+        return output;
+    }
+    render(width) {
+        if (this.#hidden)
+            return [];
+        const level = this.effectiveLevel;
+        const copied = isCopiedActive(this.#spec.stateHolder, this.#localCopiedUntil);
+        if (this.#cache !== undefined &&
+            this.#cache.width === width &&
+            this.#cache.level === level &&
+            this.#cache.copied === copied) {
+            return this.#cache.lines;
+        }
+        const pad = Math.max(0, this.#spec.outputPad ?? 0);
+        const safeWidth = Math.max(1, width - pad * 2);
+        this.#lastWidth = width;
+        if (level !== 0) {
+            this.#collapseChildren();
+        }
+        const rawLines = [this.#renderHeader(safeWidth, level), ...this.renderBody(width)];
+        const safeLines = [];
+        const leftPad = pad > 0 ? " ".repeat(pad) : "";
+        for (const rawLine of rawLines) {
+            if (rawLine.includes("\r") || rawLine.includes("\n")) {
+                for (const line of toContentRows(rawLine)) {
+                    const truncated = truncate(line, safeWidth);
+                    safeLines.push(leftPad !== "" ? `${leftPad}${truncated}` : truncated);
+                }
+            }
+            else {
+                safeLines.push(leftPad !== "" ? `${leftPad}${rawLine}` : rawLine);
+            }
+        }
+        this.#lastHeight = safeLines.length;
+        this.#cache = { width, level, copied, lines: safeLines };
+        return safeLines;
     }
     handleMouse(event) {
-        if (event.type === "wheel") {
+        if (event.type === "wheel" || this.#hidden) {
             return undefined;
         }
-        if (event.type !== "click" || event.button !== "left" || event.y !== 0) {
+        if (event.type !== "click" || event.button !== "left") {
             return undefined;
         }
         const effectiveWidth = event.width > 0 ? event.width : this.#lastWidth;
@@ -241,17 +365,48 @@ export class ToolView {
         if (innerX < 0 || innerX >= innerWidth) {
             return undefined;
         }
-        if (this.#spec.copy !== undefined &&
-            innerWidth >= 6 &&
-            innerX >= innerWidth - 3 &&
-            innerX < innerWidth - 1) {
-            this.#triggerCopy(event.shift === true);
+        // The last render's row count bounds the clickable area; a view that has not rendered yet has no
+        // extent to test against, and Pi always renders before it dispatches a mouse event.
+        if (this.#lastHeight > 0 && (event.y < 0 || event.y >= this.#lastHeight)) {
+            return undefined;
+        }
+        if (event.y === 0) {
+            if (this.#spec.copy !== undefined &&
+                innerWidth >= 6 &&
+                innerX >= innerWidth - 3 &&
+                innerX < innerWidth) {
+                this.#triggerCopy(event.shift === true);
+                return { handled: true, render: true };
+            }
+            this.toggle(event.ctrl === true);
             return { handled: true, render: true };
         }
-        this.toggle(event.ctrl === true);
-        return { handled: true, render: true };
+        const level = this.effectiveLevel;
+        if (level === 0 && this.#spec.collapsedRows !== undefined) {
+            const rows = this.#spec.collapsedRows;
+            if (typeof rows === "object" &&
+                rows !== null &&
+                "handleMouse" in rows &&
+                typeof rows.handleMouse === "function") {
+                const handler = rows.handleMouse;
+                const railOffset = this.#spec.noRail ? 0 : 2;
+                const subEvent = {
+                    ...event,
+                    y: event.y - 1,
+                    x: Math.max(0, innerX - railOffset),
+                    width: Math.max(1, innerWidth - railOffset),
+                };
+                const res = handler.call(rows, subEvent);
+                if (res?.handled) {
+                    this.#cache = undefined;
+                    return res;
+                }
+            }
+        }
+        return { handled: true };
     }
     invalidate() {
+        this.#cache = undefined;
         const { collapsedRows, sections } = this.#spec;
         if (collapsedRows !== undefined &&
             typeof collapsedRows === "object" &&
@@ -267,4 +422,3 @@ export class ToolView {
         }
     }
 }
-export { ToolView as CollapsibleToolFrame };

package/dist/tracker.d.ts

@@ -0,0 +1,26 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+export interface CapturedToolCall {
+    readonly id: string;
+    readonly toolName: string;
+    readonly args?: unknown;
+    readonly result?: AgentToolResult<unknown> | undefined;
+    readonly isError?: boolean | undefined;
+    readonly durationMs?: number | undefined;
+    readonly cost?: number | undefined;
+}
+export declare function recordToolExecutionStart(event: {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    parentToolCallId?: string | undefined;
+}): void;
+export declare function recordToolExecutionEnd(event: {
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    isError: boolean;
+    durationMs?: number | undefined;
+    parentToolCallId?: string | undefined;
+}): void;
+export declare function getCapturedNestedCalls(parentToolCallId: string | undefined): readonly CapturedToolCall[] | undefined;
+export declare function clearCapturedNestedCalls(): void;

package/dist/tracker.js

@@ -0,0 +1,81 @@
+const capturedByParentId = new Map();
+const MAX_STORED_PARENTS = 200;
+const MAX_CAPTURED_PAYLOAD_CHARS = 32_768;
+function boundCapturedValue(val) {
+    if (typeof val === "string") {
+        return val.length > MAX_CAPTURED_PAYLOAD_CHARS
+            ? `${val.slice(0, MAX_CAPTURED_PAYLOAD_CHARS)}… (truncated)`
+            : val;
+    }
+    return val;
+}
+export function recordToolExecutionStart(event) {
+    if (!event.parentToolCallId)
+        return;
+    let list = capturedByParentId.get(event.parentToolCallId);
+    if (!list) {
+        if (capturedByParentId.size >= MAX_STORED_PARENTS) {
+            const firstKey = capturedByParentId.keys().next().value;
+            if (firstKey !== undefined)
+                capturedByParentId.delete(firstKey);
+        }
+        list = [];
+        capturedByParentId.set(event.parentToolCallId, list);
+    }
+    const idx = list.findIndex((c) => c.id === event.toolCallId);
+    const entry = {
+        id: event.toolCallId,
+        toolName: event.toolName,
+        args: boundCapturedValue(event.args),
+    };
+    if (idx >= 0) {
+        list[idx] = { ...list[idx], ...entry };
+    }
+    else {
+        list.push(entry);
+    }
+}
+export function recordToolExecutionEnd(event) {
+    if (!event.parentToolCallId)
+        return;
+    let list = capturedByParentId.get(event.parentToolCallId);
+    if (!list) {
+        if (capturedByParentId.size >= MAX_STORED_PARENTS) {
+            const firstKey = capturedByParentId.keys().next().value;
+            if (firstKey !== undefined)
+                capturedByParentId.delete(firstKey);
+        }
+        list = [];
+        capturedByParentId.set(event.parentToolCallId, list);
+    }
+    const idx = list.findIndex((c) => c.id === event.toolCallId);
+    const typedResult = event.result;
+    if (idx >= 0) {
+        const prev = list[idx];
+        if (!prev)
+            return;
+        list[idx] = {
+            ...prev,
+            result: typedResult,
+            isError: event.isError,
+            durationMs: event.durationMs,
+        };
+    }
+    else {
+        list.push({
+            id: event.toolCallId,
+            toolName: event.toolName,
+            result: typedResult,
+            isError: event.isError,
+            durationMs: event.durationMs,
+        });
+    }
+}
+export function getCapturedNestedCalls(parentToolCallId) {
+    if (!parentToolCallId)
+        return undefined;
+    return capturedByParentId.get(parentToolCallId);
+}
+export function clearCapturedNestedCalls() {
+    capturedByParentId.clear();
+}