@hheei/pi-ext-ui 0.6.0 → 0.7.0

package/dist/tool-view.d.ts

@@ -11,8 +11,12 @@ export interface RailSection {
 export interface ToolViewHeaderSpec {
     readonly title: string;
     readonly status?: ToolStatusKind | undefined;
+    /** The call's own text. Plain unless `summaryStyled` says the tool layer themed it already. */
     readonly summary?: string | undefined;
-    readonly unstyledSummary?: boolean | undefined;
+    /** The summary already carries its semantic tokens; the frame must not recolor it. */
+    readonly summaryStyled?: boolean | undefined;
+    /** Secondary facts after the summary: duration, timeout. Always dim. */
+    readonly meta?: string | undefined;
 }
 export interface ToolViewCopySpec {
     readonly primary: string;
@@ -23,13 +27,12 @@ export interface Collapsible {
     collapseAll(): void;
 }
 export declare function isCollapsible(value: unknown): value is Collapsible;
-/** One nested call inside a container, reduced to what a row and its detail need. */
+/** One nested call inside a container, reduced to what a summary row and its count need. */
 export interface ToolViewChild {
     readonly title: string;
     readonly summary?: string | undefined;
     readonly status?: ToolStatusKind | undefined;
     readonly durationMs?: number | undefined;
-    readonly detail?: string | undefined;
 }
 export interface ToolViewSpec {
     readonly theme: Theme;
@@ -51,14 +54,24 @@ export interface ToolViewSpec {
     readonly copyFeedbackDurationMs?: number | undefined;
     readonly noRail?: boolean | undefined;
     readonly railToken?: RailColorToken | undefined;
+    /**
+     * Pi-native surface: success/error fill plus one padding row, and no leading rail. Read per render,
+     * so a settings change reaches a view the host already holds.
+     */
+    readonly background?: (() => boolean) | undefined;
 }
 /** Public composition entry point for extensions that need the shared view behavior. */
 export declare function createToolView(spec: ToolViewSpec): ToolView;
 export declare const MAX_LEVEL2_SECTION_LINES = 500;
 export declare const MAX_LEVEL2_BYTES: number;
-/** Internal transcript composition: original components keep their layout and interactions. */
-export declare function renderWithoutToolRails(component: Component, width: number): string[];
 export declare function transitionFoldLevel(current: FoldLevel, ctrlKey: boolean): FoldLevel;
+export declare const TOOL_SPINNER_FRAMES: readonly ["·", "✢", "✳", "✶", "✻", "✽", "✻", "✶", "✳", "✢"];
+export declare const TOOL_SPINNER_INTERVAL_MS = 100;
+/**
+ * One clock for every live tool, so the phase is shared and never restarts: streaming args and a
+ * running execution draw the same frame and differ only in color.
+ */
+export declare function toolSpinnerFrame(now?: number): string;
 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.
@@ -73,7 +86,8 @@ export declare function formatToolHeaderText(parts: {
     readonly status?: ToolStatusKind | undefined;
     readonly title: string;
     readonly summary?: string | undefined;
-    readonly unstyledSummary?: boolean | undefined;
+    readonly summaryStyled?: boolean | undefined;
+    readonly meta?: string | undefined;
 }, theme: Theme): string;
 /**
  * Collapses text that must occupy one row: header titles and summaries, board rows, and inline

package/dist/tool-view.js

@@ -1,6 +1,15 @@
 import { Buffer } from "node:buffer";
 import { copyToClipboard as copyToSystemClipboard, } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "@earendil-works/pi-tui";
+import { backgroundFill } from "./background.js";
+/** Pi native tool surfaces: a failure outranks work in progress, which outranks a settled tool. */
+function nativeSurface(status) {
+    if (status === "error")
+        return "toolErrorBg";
+    if (status === "running" || status === "streaming")
+        return "toolPendingBg";
+    return "toolSuccessBg";
+}
 export function isCollapsible(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -19,17 +28,6 @@ const DEFAULT_MAX_SECTION_LINES = 9;
 export const MAX_LEVEL2_SECTION_LINES = 500;
 export const MAX_LEVEL2_BYTES = 64 * 1024;
 const DEFAULT_COPY_FEEDBACK_MS = 1200;
-let outerRailDepth = 0;
-/** Internal transcript composition: original components keep their layout and interactions. */
-export function renderWithoutToolRails(component, width) {
-    outerRailDepth++;
-    try {
-        return component.render(width);
-    }
-    finally {
-        outerRailDepth--;
-    }
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -68,12 +66,22 @@ function isCopyFailed(stateHolder, localFailed) {
         return true;
     return isRecord(stateHolder) && stateHolder[COPY_FAILED_STATE_KEY] === true;
 }
+export const TOOL_SPINNER_FRAMES = ["·", "✢", "✳", "✶", "✻", "✽", "✻", "✶", "✳", "✢"];
+export const TOOL_SPINNER_INTERVAL_MS = 100;
+/**
+ * One clock for every live tool, so the phase is shared and never restarts: streaming args and a
+ * running execution draw the same frame and differ only in color.
+ */
+export function toolSpinnerFrame(now = performance.now()) {
+    const at = Math.floor(now / TOOL_SPINNER_INTERVAL_MS) % TOOL_SPINNER_FRAMES.length;
+    return TOOL_SPINNER_FRAMES[at] ?? "·";
+}
 export function formatStatusGlyph(status, theme) {
     switch (status ?? "ok") {
         case "streaming":
-            return theme.fg("muted", "⋯");
+            return theme.fg("muted", toolSpinnerFrame());
         case "running":
-            return theme.fg("accent", "◐");
+            return theme.fg("accent", toolSpinnerFrame());
         case "ok":
             return theme.fg("success", "✓");
         case "warn":
@@ -98,9 +106,20 @@ export function formatToolHeaderText(parts, 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}`;
+    // A command is the row's content, not its caption: bash states it the way the native shell row
+    // does. A summary the tool layer already themed keeps its own tokens.
+    const summaryPart = summaryRaw === ""
+        ? ""
+        : parts.summaryStyled === true
+            ? ` ${summaryRaw}`
+            : title === "bash"
+                ? ` ${theme.fg("toolTitle", theme.bold(summaryRaw))}`
+                : ` ${theme.fg("dim", summaryRaw)}`;
+    const metaRaw = parts.meta === undefined ? "" : toSingleRow(parts.meta);
+    const metaPart = metaRaw === ""
+        ? ""
+        : `${summaryPart === "" ? " " : theme.fg("dim", " · ")}${theme.fg("dim", metaRaw)}`;
+    return `${statusPart === "" ? "" : `${statusPart} `}${titlePart}${summaryPart}${metaPart}`;
 }
 const truncate = (text, width) => truncateToWidth(text, width, "…");
 /**
@@ -229,6 +248,8 @@ export class ToolView {
     #lastWidth = 80;
     #lastHeight = 0;
     #lastNoRail = false;
+    /** Rows the native surface adds above the header. */
+    #lastTopPad = 0;
     #cache;
     constructor(spec) {
         this.#spec = spec;
@@ -408,7 +429,7 @@ export class ToolView {
         const safeWidth = Math.max(1, width - pad * 2);
         const level = this.effectiveLevel;
         const { theme, collapsedRows, sections } = this.#spec;
-        const noRail = options?.noRail ?? (outerRailDepth > 0 || this.#spec.noRail === true);
+        const noRail = options?.noRail ?? (this.#spec.noRail === true || this.#spec.background?.() === true);
         const innerWidth = noRail ? safeWidth : Math.max(1, safeWidth - 2);
         const output = [];
         if (level === 0) {
@@ -426,11 +447,14 @@ export class ToolView {
             return output;
         }
         for (const section of sections) {
+            const sectionOutput = [];
             const rail = noRail ? "" : `${theme.fg(section.railToken, "▎")} `;
             const { rows: rawLines, isByteTruncated, totalBytes, } = resolveRows(section.content, innerWidth, toContentRows);
             const cap = level === 1 ? (section.maxLines ?? DEFAULT_MAX_SECTION_LINES) : MAX_LEVEL2_SECTION_LINES;
             const sectionRows = [];
             let logicalLinesCount = 0;
+            // Wrapped rows the last shown line still has: a single long line is not "1 more line".
+            let cutChunks = 0;
             for (const line of rawLines) {
                 const wrapped = wrapTextWithAnsi(line, innerWidth);
                 const chunks = wrapped.length > 0 ? wrapped : [""];
@@ -442,21 +466,36 @@ export class ToolView {
                             sectionRows.push(chunk);
                         }
                     }
+                    // Only a line that started showing is "continues"; a fully omitted one is a whole line.
+                    cutChunks = canTake > 0 ? chunks.length - canTake : 0;
                     break;
                 }
                 sectionRows.push(...chunks);
                 logicalLinesCount++;
             }
-            const omittedCount = rawLines.length - logicalLinesCount;
+            // The line that broke the cap is not an omitted whole line: its hidden part is `cutChunks`.
+            const omittedCount = rawLines.length - logicalLinesCount - (cutChunks > 0 ? 1 : 0);
+            // The hint names the real way to the hidden text; without a copy it must not promise one.
+            const copyHint = this.#spec.copy?.full !== undefined && this.#spec.copy.full !== ""
+                ? ", shift+click copies all"
+                : "";
             for (const row of sectionRows) {
-                output.push(truncate(rail + row, safeWidth));
+                sectionOutput.push(truncate(rail + row, safeWidth));
             }
-            if (omittedCount > 0 || isByteTruncated) {
-                const hint = isByteTruncated
-                    ? theme.fg("dim", `… [Output truncated: showing 64KB of ${Math.round(totalBytes / 1024)}KB]`)
-                    : theme.fg("dim", `… (${String(omittedCount)} more lines)`);
-                output.push(truncate(rail + hint, safeWidth));
+            if (omittedCount > 0 || cutChunks > 0 || isByteTruncated) {
+                let text;
+                if (isByteTruncated) {
+                    text = `… [Output truncated: showing 64KB of ${Math.round(totalBytes / 1024)}KB${copyHint}]`;
+                }
+                else if (omittedCount > 0) {
+                    text = `… (${String(omittedCount)} more lines${cutChunks > 0 ? ", current line continues" : ""}${copyHint})`;
+                }
+                else {
+                    text = `… (current line continues${copyHint})`;
+                }
+                sectionOutput.push(truncate(rail + theme.fg("dim", text), safeWidth));
             }
+            output.push(...sectionOutput);
         }
         return output;
     }
@@ -465,11 +504,14 @@ export class ToolView {
             return [];
         const level = this.effectiveLevel;
         const copied = isCopiedActive(this.#spec.stateHolder, this.#localCopiedUntil);
-        const noRail = outerRailDepth > 0 || this.#spec.noRail === true;
+        const native = this.#spec.background?.() === true;
+        const surface = native ? nativeSurface(this.#spec.header.status) : undefined;
+        const noRail = this.#spec.noRail === true || native;
         if (this.#cache !== undefined &&
             this.#cache.width === width &&
             this.#cache.level === level &&
             this.#cache.noRail === noRail &&
+            this.#cache.surface === surface &&
             this.#cache.copied === copied) {
             return this.#cache.lines;
         }
@@ -494,9 +536,13 @@ export class ToolView {
                 safeLines.push(leftPad !== "" ? `${leftPad}${rawLine}` : rawLine);
             }
         }
-        this.#lastHeight = safeLines.length;
-        this.#cache = { width, level, copied, noRail, lines: safeLines };
-        return safeLines;
+        this.#lastTopPad = surface === undefined ? 0 : 1;
+        const lines = surface === undefined
+            ? safeLines
+            : ["", ...safeLines, ""].map((line) => backgroundFill(this.#spec.theme, surface)(line + " ".repeat(Math.max(0, width - visibleWidth(line)))));
+        this.#lastHeight = lines.length;
+        this.#cache = { width, level, copied, noRail, surface, lines };
+        return lines;
     }
     handleMouse(event) {
         if (event.type === "wheel" || this.#hidden) {
@@ -517,7 +563,8 @@ export class ToolView {
         if (this.#lastHeight > 0 && (event.y < 0 || event.y >= this.#lastHeight)) {
             return undefined;
         }
-        if (event.y === 0) {
+        const row = event.y - this.#lastTopPad;
+        if (row === 0) {
             if (this.#spec.copy !== undefined &&
                 innerWidth >= 6 &&
                 innerX >= innerWidth - 3 &&
@@ -539,7 +586,7 @@ export class ToolView {
                 const railOffset = this.#lastNoRail ? 0 : 2;
                 const subEvent = {
                     ...event,
-                    y: event.y - 1,
+                    y: row - 1,
                     x: Math.max(0, innerX - railOffset),
                     width: Math.max(1, innerWidth - railOffset),
                 };

package/dist/tracker.d.ts

@@ -1,8 +1,15 @@
-import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** The public read-only session view the lifecycle context hands an extension. */
+type SessionReadSource = ExtensionContext["sessionManager"];
 export interface CapturedToolCall {
     readonly id: string;
     readonly toolName: string;
+    /** Positive resolution fact, when the host's `tool_call` hook reported this call. */
+    readonly resolved?: boolean | undefined;
     readonly args?: unknown;
+    /** The request existed but was too large to keep; the bytes are not recorded. */
+    readonly argsTruncated?: boolean | undefined;
+    readonly argsBytes?: number | undefined;
     readonly result?: AgentToolResult<unknown> | undefined;
     readonly isError?: boolean | undefined;
     readonly durationMs?: number | undefined;
@@ -25,21 +32,33 @@ export declare class ToolExecutionTracker {
         parentToolCallId?: string | undefined;
     }): void;
     getCaptured(parentToolCallId: string | undefined): readonly CapturedToolCall[] | undefined;
+    /**
+     * The host's `tool_call` hook runs after the tool resolved and its arguments validated, so a
+     * recorded id is a positive fact. Nothing is recorded for a call the hook never saw: an unknown
+     * tool, an invalid argument set, a blocked or cancelled call all stay unknown.
+     */
+    recordResolved(event: {
+        toolCallId: string;
+        parentToolCallId?: string | undefined;
+    }): void;
+    getResolved(parentToolCallId: string | undefined): ReadonlySet<string> | undefined;
     clear(): void;
 }
-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;
+/** What the session branch says about one nested call's request. */
+export interface NestedCallArgsFact {
+    readonly args: unknown;
+    /** The host kept the size but not the arguments, so the request is not recoverable. */
+    readonly truncated: boolean;
+    readonly bytes?: number | undefined;
+}
+/**
+ * The arguments a resumed session saved for its nested calls. One index belongs to one runtime: it
+ * follows that runtime's session, and shutting the runtime down or switching sessions drops it.
+ */
+export declare class NestedCallArgsIndex {
+    #private;
+    /** The session owns the index: switching, reloading or shutting down replaces it. */
+    setSource(manager: SessionReadSource | undefined): void;
+    args(toolCallId: string | undefined): NestedCallArgsFact | undefined;
+}
+export {};

package/dist/tracker.js

@@ -1,15 +1,30 @@
 const MAX_STORED_PARENTS = 200;
+/** A live capture keeps the request whole or not at all; a partial request would be a lie. */
 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;
+/** Host records at most this many nested calls per model-issued call. */
+const MAX_RESOLVED_CALLS = 256;
+/** Recovered arguments for at most this many calls; beyond it a row says it is not recorded. */
+const MAX_INDEXED_CALLS = 512;
+/**
+ * The captured request, or the fact that it was too large to keep. Nothing is rewritten: a caller
+ * either has the bytes the model sent or knows they are not recorded.
+ */
+function capturedArgs(args) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(args);
     }
-    return val;
+    catch {
+        // A value the host could not serialize is kept as-is; its size is unknown, not zero.
+        return { args };
+    }
+    if (serialized === undefined || serialized.length <= MAX_CAPTURED_PAYLOAD_CHARS)
+        return { args };
+    return { argsTruncated: true, argsBytes: serialized.length };
 }
 export class ToolExecutionTracker {
     #capturedByParentId = new Map();
+    #resolvedByParentId = new Map();
     recordStart(event) {
         if (!event.parentToolCallId)
             return;
@@ -27,7 +42,7 @@ export class ToolExecutionTracker {
         const entry = {
             id: event.toolCallId,
             toolName: event.toolName,
-            args: boundCapturedValue(event.args),
+            ...capturedArgs(event.args),
         };
         if (idx >= 0) {
             list[idx] = { ...list[idx], ...entry };
@@ -77,20 +92,143 @@ export class ToolExecutionTracker {
             return undefined;
         return this.#capturedByParentId.get(parentToolCallId);
     }
+    /**
+     * The host's `tool_call` hook runs after the tool resolved and its arguments validated, so a
+     * recorded id is a positive fact. Nothing is recorded for a call the hook never saw: an unknown
+     * tool, an invalid argument set, a blocked or cancelled call all stay unknown.
+     */
+    recordResolved(event) {
+        const parent = event.parentToolCallId;
+        if (!parent)
+            return;
+        let ids = this.#resolvedByParentId.get(parent);
+        if (!ids) {
+            if (this.#resolvedByParentId.size >= MAX_STORED_PARENTS) {
+                const firstKey = this.#resolvedByParentId.keys().next().value;
+                if (firstKey !== undefined)
+                    this.#resolvedByParentId.delete(firstKey);
+            }
+            ids = new Set();
+            this.#resolvedByParentId.set(parent, ids);
+        }
+        if (ids.size >= MAX_RESOLVED_CALLS)
+            return;
+        ids.add(event.toolCallId);
+    }
+    getResolved(parentToolCallId) {
+        if (!parentToolCallId)
+            return undefined;
+        return this.#resolvedByParentId.get(parentToolCallId);
+    }
     clear() {
         this.#capturedByParentId.clear();
+        this.#resolvedByParentId.clear();
     }
 }
-const defaultTracker = new ToolExecutionTracker();
-export function recordToolExecutionStart(event) {
-    defaultTracker.recordStart(event);
-}
-export function recordToolExecutionEnd(event) {
-    defaultTracker.recordEnd(event);
-}
-export function getCapturedNestedCalls(parentToolCallId) {
-    return defaultTracker.getCaptured(parentToolCallId);
-}
-export function clearCapturedNestedCalls() {
-    defaultTracker.clear();
+/**
+ * The arguments a resumed session saved for its nested calls. One index belongs to one runtime: it
+ * follows that runtime's session, and shutting the runtime down or switching sessions drops it.
+ */
+export class NestedCallArgsIndex {
+    #source;
+    /** The leaf the index is complete up to; undefined means no index exists yet. */
+    #indexedLeaf;
+    #argsById = new Map();
+    /** The session owns the index: switching, reloading or shutting down replaces it. */
+    setSource(manager) {
+        this.#source = manager;
+        this.#reset();
+    }
+    args(toolCallId) {
+        const manager = this.#source;
+        if (manager === undefined || toolCallId === undefined)
+            return undefined;
+        try {
+            this.#refresh(manager);
+        }
+        catch {
+            this.#reset();
+            return undefined;
+        }
+        return this.#argsById.get(toolCallId);
+    }
+    #reset() {
+        this.#argsById.clear();
+        this.#indexedLeaf = undefined;
+    }
+    #remember(id, fact) {
+        if (!this.#argsById.has(id) && this.#argsById.size >= MAX_INDEXED_CALLS) {
+            const firstKey = this.#argsById.keys().next().value;
+            if (firstKey !== undefined)
+                this.#argsById.delete(firstKey);
+        }
+        this.#argsById.set(id, fact);
+    }
+    /** The host saves a bounded record on the parent's tool result; this reads it back by call id. */
+    #scan(entry) {
+        if (typeof entry !== "object" || entry === null)
+            return;
+        const record = entry;
+        if (record.type !== "message")
+            return;
+        const message = record.message;
+        if (typeof message !== "object" || message === null)
+            return;
+        const toolResult = message;
+        if (toolResult.role !== "toolResult")
+            return;
+        const nested = toolResult.nestedCalls;
+        if (typeof nested !== "object" || nested === null)
+            return;
+        const calls = nested.calls;
+        if (!Array.isArray(calls))
+            return;
+        for (const call of calls) {
+            if (typeof call !== "object" || call === null)
+                continue;
+            const saved = call;
+            if (typeof saved.id !== "string")
+                continue;
+            if (saved.arguments !== undefined) {
+                this.#remember(saved.id, { args: saved.arguments, truncated: false });
+            }
+            else if (typeof saved.argumentsBytes === "number") {
+                this.#remember(saved.id, {
+                    args: undefined,
+                    truncated: true,
+                    bytes: saved.argumentsBytes,
+                });
+            }
+        }
+    }
+    /**
+     * Extend the index to the current leaf. An append walks only the new entries up to the previous
+     * leaf; a fork, branch switch or reload has no such chain and rebuilds. A render never scans the
+     * whole branch once the index is current, and a read failure is not cached as an empty answer.
+     */
+    #refresh(manager) {
+        const leaf = manager.getLeafId();
+        if (leaf === this.#indexedLeaf)
+            return;
+        if (leaf !== null && this.#indexedLeaf !== undefined) {
+            const chain = [];
+            let current = leaf;
+            while (current !== null &&
+                current !== this.#indexedLeaf &&
+                chain.length <= MAX_INDEXED_CALLS) {
+                chain.push(current);
+                current = manager.getEntry(current)?.parentId ?? null;
+            }
+            if (current === this.#indexedLeaf) {
+                for (const id of chain.reverse())
+                    this.#scan(manager.getEntry(id));
+                this.#indexedLeaf = leaf;
+                return;
+            }
+        }
+        this.#argsById.clear();
+        for (const entry of manager.getBranch())
+            this.#scan(entry);
+        this.#indexedLeaf = leaf;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hheei/pi-ext-ui",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Collapsible tool rendering frame and tool renderer pilot for Pi.",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@hheei/pi-ext-core": "^0.7.0"
+    "@hheei/pi-ext-core": "^0.7.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=1.0.1",