@oh-my-pi/pi-coding-agent 15.1.1 → 15.1.3

package/dist/types/tools/sqlite-reader.d.ts

@@ -0,0 +1,93 @@
+import type { Database } from "bun:sqlite";
+export interface SqlitePathCandidate {
+    sqlitePath: string;
+    subPath: string;
+    queryString: string;
+}
+export type SqliteSelector = {
+    kind: "list";
+} | {
+    kind: "schema";
+    table: string;
+    sampleLimit: number;
+} | {
+    kind: "row";
+    table: string;
+    key: string;
+} | {
+    kind: "query";
+    table: string;
+    limit: number;
+    offset: number;
+    order?: string;
+    where?: string;
+} | {
+    kind: "raw";
+    sql: string;
+};
+export type SqliteRowLookup = {
+    kind: "pk";
+    column: string;
+    type: string;
+} | {
+    kind: "rowid";
+};
+export declare function parseSqlitePathCandidates(filePath: string): SqlitePathCandidate[];
+export declare function isSqliteFile(absolutePath: string): Promise<boolean>;
+export declare function parseSqliteSelector(subPath: string, queryString: string): SqliteSelector;
+export declare function listTables(db: Database): {
+    name: string;
+    rowCount: number;
+}[];
+export declare function getTableSchema(db: Database, table: string): string;
+export declare function getTablePrimaryKey(db: Database, table: string): {
+    column: string;
+    type: string;
+} | null;
+export declare function resolveTableRowLookup(db: Database, table: string): SqliteRowLookup;
+export declare function queryRows(db: Database, table: string, opts: {
+    limit: number;
+    offset: number;
+    order?: string;
+    where?: string;
+}): {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    totalCount: number;
+};
+export declare function getRowByKey(db: Database, table: string, pk: {
+    column: string;
+    type?: string;
+}, key: string): Record<string, unknown> | null;
+export declare function getRowByRowId(db: Database, table: string, key: string): Record<string, unknown> | null;
+export declare function executeReadQuery(db: Database, sql: string): {
+    columns: string[];
+    rows: Record<string, unknown>[];
+};
+export declare function insertRow(db: Database, table: string, data: Record<string, unknown>): void;
+export declare function updateRowByKey(db: Database, table: string, pk: {
+    column: string;
+    type?: string;
+}, key: string, data: Record<string, unknown>): number;
+export declare function updateRowByRowId(db: Database, table: string, key: string, data: Record<string, unknown>): number;
+export declare function deleteRowByKey(db: Database, table: string, pk: {
+    column: string;
+    type?: string;
+}, key: string): number;
+export declare function deleteRowByRowId(db: Database, table: string, key: string): number;
+export declare function renderTableList(tables: {
+    name: string;
+    rowCount: number;
+}[]): string;
+export declare function renderSchema(createSql: string, sampleRows: {
+    columns: string[];
+    rows: Record<string, unknown>[];
+}): string;
+export declare function renderRow(row: Record<string, unknown>): string;
+export declare function renderTable(columns: string[], rows: Record<string, unknown>[], meta: {
+    totalCount: number;
+    offset: number;
+    limit: number;
+    table: string;
+    dbPath: string;
+}): string;

package/dist/types/tools/ssh.d.ts

@@ -0,0 +1,67 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-tui";
+import * as z from "zod/v4";
+import type { SSHHost } from "../capability/ssh";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import type { ToolSession } from ".";
+import { type OutputMeta } from "./output-meta";
+declare const sshSchema: z.ZodObject<{
+    host: z.ZodString;
+    command: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export interface SSHToolDetails {
+    meta?: OutputMeta;
+}
+type SshToolParams = z.infer<typeof sshSchema>;
+export declare class SshTool implements AgentTool<typeof sshSchema, SSHToolDetails> {
+    #private;
+    private readonly session;
+    private readonly hostNames;
+    private readonly hostsByName;
+    readonly description: string;
+    readonly name = "ssh";
+    readonly summary = "Execute a command on a remote host over SSH";
+    readonly loadMode = "discoverable";
+    readonly label = "SSH";
+    readonly parameters: z.ZodObject<{
+        host: z.ZodString;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>;
+    readonly concurrency = "exclusive";
+    readonly strict = true;
+    constructor(session: ToolSession, hostNames: string[], hostsByName: Map<string, SSHHost>, description: string);
+    execute(_toolCallId: string, { host, command, cwd, timeout: rawTimeout }: SshToolParams, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<SSHToolDetails>, _ctx?: AgentToolContext): Promise<AgentToolResult<SSHToolDetails>>;
+}
+export declare function loadSshTool(session: ToolSession): Promise<SshTool | null>;
+interface SshRenderArgs {
+    host?: string;
+    command?: string;
+    timeout?: number;
+}
+interface SshRenderContext {
+    /** Visual lines for truncated output (pre-computed by tool-execution) */
+    visualLines?: string[];
+    /** Number of lines skipped */
+    skippedCount?: number;
+    /** Total visual lines */
+    totalVisualLines?: number;
+}
+export declare const sshToolRenderer: {
+    renderCall(args: SshRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: SSHToolDetails;
+    }, options: RenderResultOptions & {
+        renderContext?: SshRenderContext;
+    }, uiTheme: Theme, args?: SshRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

package/dist/types/tools/todo-write.d.ts

@@ -0,0 +1,120 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-tui";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import type { ToolSession } from "../sdk";
+import type { SessionEntry } from "../session/session-manager";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+export interface TodoItem {
+    content: string;
+    status: TodoStatus;
+    /**
+     * Append-only list of freeform notes attached by `op: "note"`.
+     * Each element is one note and may itself be multi-line.
+     * Rendered as text only when the task is in_progress; otherwise shown as a
+     * dim marker indicating the task has notes.
+     */
+    notes?: string[];
+}
+export interface TodoPhase {
+    name: string;
+    tasks: TodoItem[];
+}
+export interface TodoWriteToolDetails {
+    phases: TodoPhase[];
+    storage: "session" | "memory";
+}
+declare const todoWriteSchema: z.ZodObject<{
+    ops: z.ZodArray<z.ZodObject<{
+        op: z.ZodEnum<{
+            append: "append";
+            done: "done";
+            drop: "drop";
+            init: "init";
+            note: "note";
+            rm: "rm";
+            start: "start";
+        }>;
+        list: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            phase: z.ZodString;
+            items: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>;
+        task: z.ZodOptional<z.ZodString>;
+        phase: z.ZodOptional<z.ZodString>;
+        items: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type TodoWriteParams = z.infer<typeof todoWriteSchema>;
+export declare const USER_TODO_EDIT_CUSTOM_TYPE = "user_todo_edit";
+export declare function getLatestTodoPhasesFromEntries(entries: SessionEntry[]): TodoPhase[];
+/** Apply an array of `todo_write`-style ops to existing phases. Used by /todo slash command. */
+export declare function applyOpsToPhases(currentPhases: TodoPhase[], ops: TodoWriteParams["ops"]): {
+    phases: TodoPhase[];
+    errors: string[];
+};
+/** Render todo phases as a Markdown checklist suitable for editing/copying. */
+export declare function phasesToMarkdown(phases: TodoPhase[]): string;
+/** Parse a Markdown checklist back into todo phases. */
+export declare function markdownToPhases(md: string): {
+    phases: TodoPhase[];
+    errors: string[];
+};
+export declare class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWriteToolDetails> {
+    private readonly session;
+    readonly name = "todo_write";
+    readonly label = "Todo Write";
+    readonly summary = "Write a structured todo list to track progress within a session";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        ops: z.ZodArray<z.ZodObject<{
+            op: z.ZodEnum<{
+                append: "append";
+                done: "done";
+                drop: "drop";
+                init: "init";
+                note: "note";
+                rm: "rm";
+                start: "start";
+            }>;
+            list: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                phase: z.ZodString;
+                items: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>>;
+            task: z.ZodOptional<z.ZodString>;
+            phase: z.ZodOptional<z.ZodString>;
+            items: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    readonly concurrency = "exclusive";
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: TodoWriteParams, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<TodoWriteToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<TodoWriteToolDetails>>;
+}
+type TodoWriteRenderArgs = {
+    ops?: Array<{
+        op?: string;
+        task?: string;
+        phase?: string;
+        items?: string[];
+    }>;
+};
+/** One-based ASCII roman numeral for display (I, II, III, IV, …). */
+export declare function phaseRomanNumeral(oneBasedIndex: number): string;
+/** Display-only phase header: `I. Foundation`. State and prompts never see this. */
+export declare function formatPhaseDisplayName(name: string, oneBasedIndex: number): string;
+export declare const todoWriteToolRenderer: {
+    renderCall(args: TodoWriteRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: TodoWriteToolDetails;
+    }, options: RenderResultOptions, uiTheme: Theme, _args?: TodoWriteRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

package/dist/types/tools/tool-errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Standardized error types for tool execution.
+ *
+ * Tools should throw these instead of returning error text.
+ * The agent loop catches and renders them appropriately.
+ */
+/**
+ * Base error for tool execution failures.
+ * Override render() for custom LLM-facing formatting.
+ */
+export declare class ToolError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+    /** Render error for LLM consumption. Override for custom formatting. */
+    render(): string;
+}
+/**
+ * Error thrown when a tool operation is aborted (e.g., via AbortSignal).
+ */
+export declare class ToolAbortError extends Error {
+    static readonly MESSAGE = "Operation aborted";
+    constructor(message?: string);
+}
+/**
+ * Throw ToolAbortError if the signal is aborted.
+ * Use this instead of signal?.throwIfAborted() to get consistent error types.
+ */
+export declare function throwIfAborted(signal?: AbortSignal): void;
+/**
+ * Render an error for LLM consumption.
+ * Handles ToolError.render() and falls back to message/string.
+ */
+export declare function renderError(e: unknown): string;

package/dist/types/tools/tool-result.d.ts

@@ -0,0 +1,30 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
+import type { OutputSummary, TruncationResult } from "../session/streaming-output";
+import type { OutputMeta, TruncationOptions, TruncationSummaryOptions, TruncationTextOptions } from "./output-meta";
+type ToolContent = Array<TextContent | ImageContent>;
+type DetailsWithMeta = {
+    meta?: OutputMeta;
+};
+export declare class ToolResultBuilder<TDetails extends DetailsWithMeta> {
+    #private;
+    constructor(details?: TDetails);
+    text(text: string): this;
+    content(content: ToolContent): this;
+    truncation(result: TruncationResult, options: TruncationOptions): this;
+    truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this;
+    truncationFromText(text: string, options: TruncationTextOptions): this;
+    limits(limits: {
+        matchLimit?: number;
+        resultLimit?: number;
+        headLimit?: number;
+        columnMax?: number;
+    }): this;
+    sourceUrl(value: string): this;
+    sourcePath(value: string): this;
+    sourceInternal(value: string): this;
+    diagnostics(summary: string, messages: string[]): this;
+    done(): AgentToolResult<TDetails>;
+}
+export declare function toolResult<TDetails extends DetailsWithMeta>(details?: TDetails): ToolResultBuilder<TDetails>;
+export {};

package/dist/types/tools/tool-timeouts.d.ts

@@ -0,0 +1,51 @@
+export interface ToolTimeoutConfig {
+    /** Default timeout in seconds when agent omits the field */
+    default: number;
+    /** Minimum allowed timeout in seconds */
+    min: number;
+    /** Maximum allowed timeout in seconds (per-tool ceiling) */
+    max: number;
+}
+export declare const TOOL_TIMEOUTS: {
+    readonly bash: {
+        readonly default: 300;
+        readonly min: 1;
+        readonly max: 3600;
+    };
+    readonly eval: {
+        readonly default: 30;
+        readonly min: 1;
+        readonly max: 600;
+    };
+    readonly browser: {
+        readonly default: 30;
+        readonly min: 1;
+        readonly max: 30;
+    };
+    readonly ssh: {
+        readonly default: 60;
+        readonly min: 1;
+        readonly max: 3600;
+    };
+    readonly fetch: {
+        readonly default: 20;
+        readonly min: 1;
+        readonly max: 45;
+    };
+    readonly lsp: {
+        readonly default: 20;
+        readonly min: 5;
+        readonly max: 60;
+    };
+    readonly debug: {
+        readonly default: 30;
+        readonly min: 5;
+        readonly max: 300;
+    };
+};
+export type ToolWithTimeout = keyof typeof TOOL_TIMEOUTS;
+/**
+ * Clamp a raw timeout to the allowed range for a tool.
+ * If rawTimeout is undefined, returns the tool's default.
+ */
+export declare function clampTimeout(tool: ToolWithTimeout, rawTimeout?: number): number;

package/dist/types/tools/vim.d.ts

@@ -0,0 +1,58 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-tui";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type Theme } from "../modes/theme/theme";
+import type { VimToolDetails } from "../vim/types";
+import type { ToolSession } from ".";
+declare const vimSchema: z.ZodObject<{
+    file: z.ZodString;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kbd: z.ZodArray<z.ZodString>;
+        insert: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    pause: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type VimParams = z.infer<typeof vimSchema>;
+interface VimRenderStep {
+    kbd?: string[];
+    insert?: string;
+}
+export interface VimRenderArgs {
+    file?: string;
+    steps?: VimRenderStep[];
+    pause?: boolean;
+    __partialJson?: string;
+}
+export declare class VimTool implements AgentTool<typeof vimSchema, VimToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "vim";
+    readonly label = "Vim";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        file: z.ZodString;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kbd: z.ZodArray<z.ZodString>;
+            insert: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        pause: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly concurrency = "exclusive";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: VimParams, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<VimToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<VimToolDetails>>;
+}
+export declare function resetVimRendererStateForTest(): void;
+export declare const vimToolRenderer: {
+    renderCall(args: VimRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: VimToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme): Component;
+    mergeCallAndResult: boolean;
+};
+export { vimSchema };

package/dist/types/tools/write.d.ts

@@ -0,0 +1,59 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-tui";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type FileDiagnosticsResult } from "../lsp";
+import { type Theme } from "../modes/theme/theme";
+import type { ToolSession } from "../sdk";
+import { type OutputMeta } from "./output-meta";
+declare const writeSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type WriteToolInput = z.infer<typeof writeSchema>;
+/** Details returned by the write tool for TUI rendering */
+export interface WriteToolDetails {
+    diagnostics?: FileDiagnosticsResult;
+    meta?: OutputMeta;
+}
+type WriteParams = WriteToolInput;
+/**
+ * Write tool implementation.
+ *
+ * Creates or overwrites files with optional LSP formatting and diagnostics.
+ */
+export declare class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "write";
+    readonly label = "Write";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>;
+    readonly nonAbortable = true;
+    readonly strict = true;
+    readonly concurrency = "exclusive";
+    readonly loadMode = "discoverable";
+    readonly summary = "Write content to a file (creates or overwrites)";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, { path, content }: WriteParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<WriteToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<WriteToolDetails>>;
+}
+interface WriteRenderArgs {
+    path?: string;
+    file_path?: string;
+    content?: string;
+}
+export declare const writeToolRenderer: {
+    renderCall(args: WriteRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: WriteToolDetails;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: WriteRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

package/dist/types/tools/yield.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Submit result tool for structured subagent output.
+ *
+ * Subagents must call this tool to finish and return structured JSON output.
+ */
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { TSchema } from "@oh-my-pi/pi-ai/types";
+import type { ToolSession } from ".";
+export interface YieldDetails {
+    data: unknown;
+    status: "success" | "aborted";
+    error?: string;
+}
+export declare class YieldTool implements AgentTool<TSchema, YieldDetails> {
+    #private;
+    readonly name = "yield";
+    readonly label = "Submit Result";
+    readonly description: string;
+    readonly parameters: TSchema;
+    strict: boolean;
+    readonly intent: "omit";
+    lenientArgValidation: boolean;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: unknown, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<YieldDetails>, _context?: AgentToolContext): Promise<AgentToolResult<YieldDetails>>;
+}

package/dist/types/tui/code-cell.d.ts

@@ -0,0 +1,32 @@
+import { type Theme } from "../modes/theme/theme";
+export interface CodeCellOptions {
+    code: string;
+    language?: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    codeMaxLines?: number;
+    expanded?: boolean;
+    width: number;
+}
+export declare function renderCodeCell(options: CodeCellOptions, theme: Theme): string[];
+export interface MarkdownCellOptions {
+    content: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    contentMaxLines?: number;
+    expanded?: boolean;
+    width: number;
+}
+export declare function renderMarkdownCell(options: MarkdownCellOptions, theme: Theme): string[];

package/dist/types/tui/file-list.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Render file listings with optional icons and metadata.
+ */
+import type { Theme } from "../modes/theme/theme";
+export interface FileEntry {
+    path: string;
+    isDirectory?: boolean;
+    meta?: string;
+}
+export interface FileListOptions {
+    files: FileEntry[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    showIcons?: boolean;
+}
+export declare function renderFileList(options: FileListOptions, theme: Theme): string[];

package/dist/types/tui/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public exports for shared TUI components.
+ */
+export * from "./code-cell";
+export * from "./file-list";
+export * from "./output-block";
+export * from "./status-line";
+export * from "./tree-list";
+export * from "./types";
+export * from "./utils";

package/dist/types/tui/output-block.d.ts

@@ -0,0 +1,28 @@
+import type { Theme } from "../modes/theme/theme";
+import type { State } from "./types";
+export interface OutputBlockOptions {
+    header?: string;
+    headerMeta?: string;
+    state?: State;
+    sections?: Array<{
+        label?: string;
+        lines: string[];
+    }>;
+    width: number;
+    applyBg?: boolean;
+}
+export declare function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[];
+/**
+ * Cached wrapper around `renderOutputBlock`.
+ *
+ * Since output blocks are re-rendered on every frame (via `render(width)` closures),
+ * but their content rarely changes, this cache avoids redundant `visibleWidth()` and
+ * `padding()` computations on ~99% of render calls.
+ */
+export declare class CachedOutputBlock {
+    #private;
+    /** Render with caching. Returns cached result if options haven't changed. */
+    render(options: OutputBlockOptions, theme: Theme): string[];
+    /** Invalidate the cache, forcing a rebuild on next render. */
+    invalidate(): void;
+}

package/dist/types/tui/status-line.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Standardized status header rendering for tool output.
+ */
+import type { Theme, ThemeColor } from "../modes/theme/theme";
+import type { ToolUIStatus } from "../tools/render-utils";
+export interface StatusLineOptions {
+    icon?: ToolUIStatus;
+    spinnerFrame?: number;
+    title: string;
+    titleColor?: ThemeColor;
+    description?: string;
+    badge?: {
+        label: string;
+        color: ThemeColor;
+    };
+    meta?: string[];
+}
+export declare function renderStatusLine(options: StatusLineOptions, theme: Theme): string;

package/dist/types/tui/tree-list.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hierarchical tree list rendering helper.
+ */
+import type { Theme } from "../modes/theme/theme";
+import type { TreeContext } from "./types";
+export interface TreeListOptions<T> {
+    items: T[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    /** Strict total-line budget for collapsed mode. When set (and not expanded),
+     *  rendered item lines plus the trailing summary line must fit within this budget.
+     */
+    maxCollapsedLines?: number;
+    itemType?: string;
+    /** Called once per item with `isLast: false` during budget calculation;
+     *  line count MUST NOT vary based on `isLast`. */
+    renderItem: (item: T, context: TreeContext) => string | string[];
+}
+export declare function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): string[];