@oh-my-pi/pi-tui 18.4.2 → 18.4.4

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

@@ -3,6 +3,8 @@
  * transcript components. Built-in renderers live beside this file; the
  * coding-agent tools implement the matching `*Details` payloads.
  */
+import type { TspPreview, TspText, TspTone, TspToolProps } from "@oh-my-pi/pi-wire";
+import type { NativeChild } from "../native/node.js";
 import type { Component } from "../tui.js";
 import type { Theme } from "../theme/theme.js";
 /** Display state handed to `renderCall`/`renderResult`. */
@@ -58,6 +60,54 @@ export interface ToolActivityContext {
     /** Tool-specific render context (same shape `renderCall` receives), when available. */
     readonly renderContext?: Record<string, unknown>;
 }
+/**
+ * The data head of a tool call (NATIVE_REDESIGN §7.2): what the terminal
+ * draws in the `tool` kind's head. Each fact appears once — a target named
+ * here is never repeated in the body.
+ */
+export interface NativeToolHead {
+    /** The verb ("Bash", "Edit"); defaults to the tool's label. */
+    readonly title?: TspText;
+    /** The primary argument, shown once: command, path, pattern, query. */
+    readonly target?: TspText;
+    readonly targetKind?: TspToolProps["targetKind"];
+    /** Language for `command` targets. */
+    readonly lang?: string;
+    /** `file://` link for path targets. */
+    readonly href?: string;
+    /** Short facts after the target (`+8 −1`, `5 matches · 2 files`). */
+    readonly meta?: readonly TspText[];
+    readonly badges?: TspToolProps["badges"];
+    /** A one-word state note ("timed out", "partial"). */
+    readonly note?: TspText;
+    /** A non-zero exit code (error chip). */
+    readonly exit?: number | null;
+}
+/**
+ * A tool's semantic presentation for Tern Surface Protocol terminals.
+ * `ToolExecutionComponent` wraps it in a `tool` node (terminals that list
+ * the kind) or, as the fallback, a `card` (role `omp.tool.<name>`, status,
+ * elapsed timer, collapse): the renderer supplies only the head data and the
+ * body nodes, never frames, padding or width math.
+ */
+export interface NativeToolView {
+    /** The data head; the fallback card's head spans derive from it when {@link head} is absent. */
+    readonly tool?: NativeToolHead;
+    /** Header spans for the fallback card (and the `tool` title when {@link tool} is absent). */
+    readonly head?: TspText;
+    /** Body: sections, never frames. */
+    readonly body?: readonly NativeChild[];
+    /** Tone override; the frame otherwise derives it from the call status. */
+    readonly tone?: TspTone;
+    /** Body clamp while collapsed; `{tail}` keeps the end (terminal output). Defaults to the transcript's preview size. */
+    readonly preview?: TspPreview | {
+        readonly tail: number;
+    } | "none";
+    /** Render frameless (`frame:"inline"`): a head line plus a disclosed body. */
+    readonly inline?: boolean;
+    /** Head actions offered on hover (`copy`, `retry`). */
+    readonly tools?: TspToolProps["tools"];
+}
 /**
  * A tool's transcript presentation: call preview, result view, and repaint/animation hints.
  * Method signatures are intentionally bivariant so a renderer typed over its own
@@ -67,6 +117,13 @@ export interface ToolActivityContext {
 export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
     renderCall(args: TArgs, options: RenderResultOptions, theme: Theme): Component | undefined;
     renderResult(result: ToolRenderResult<TDetails>, options: RenderResultContextOptions, theme: Theme, args?: TArgs): Component | undefined;
+    /**
+     * Semantic call preview for TSP terminals. When a renderer implements the
+     * describe hooks, the native backend never calls `renderCall`/`renderResult`.
+     */
+    describeCall?(args: TArgs, options: RenderResultOptions): NativeToolView | undefined;
+    /** Semantic result view for TSP terminals; merged with the call view when {@link mergeCallAndResult}. */
+    describeResult?(result: ToolRenderResult<TDetails>, options: RenderResultContextOptions, args?: TArgs): NativeToolView | undefined;
     mergeCallAndResult?: boolean;
     /** Describes current activity without coupling a renderer to terminal layout. */
     activitySummary?(args: TArgs, context: ToolActivityContext): ToolActivitySummary;

package/dist/types/tools/report-tool-issue.d.ts

@@ -1,7 +1,10 @@
 import type { Component } from "../index.js";
 import type { Theme } from "../theme/theme.js";
+import type { NativeToolView } from "./renderer.js";
 /** Call preview for an `xd://report_issue` write. */
 export declare function renderReportIssueDeviceCall(content: unknown, uiTheme: Theme): Component;
+/** Native call preview for an `xd://report_issue` write. */
+export declare function describeReportIssueDeviceCall(content: unknown): NativeToolView;
 /** Device name for automatic tool issue reports. */
 export declare const REPORT_ISSUE_DEVICE_NAME = "report_issue";
 /** Internal device URL for automatic tool issue reports. */

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

@@ -1,5 +1,5 @@
 import type { Component } from "../index.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions } from "./renderer.js";
 import type { Theme } from "../theme/theme.js";
 import { Ellipsis } from "../render/index.js";
 /** Device name for applying a staged action. */
@@ -27,6 +27,10 @@ export interface ResolveInvocation {
 }
 /** Streaming-safe call preview for a resolution-device write: `Resolve/Reject/Propose: <text>`. */
 export declare function renderResolutionDeviceCall(device: ResolutionDeviceName, content: unknown, uiTheme: Theme): Component;
+/** Native form of {@link renderResolutionDeviceCall}: `Resolve/Reject/Propose` head with the first content line. */
+export declare function describeResolutionDeviceCall(device: ResolutionDeviceName, content: unknown): NativeToolView;
+/** Native form of {@link renderDeviceCallPreview}: title head plus the first content line of a pending device write. */
+export declare function describeDeviceCallPreview(title: string, content: unknown): NativeToolView;
 /** Render the first content line of a pending device write. */
 export declare function renderDeviceCallPreview(title: string, content: unknown, uiTheme: Theme, ellipsis?: Ellipsis): Component;
 /** Render staged-action acceptance or rejection. */
@@ -40,6 +44,15 @@ export declare const resolveRenderer: {
         details?: ResolveDetails;
         isError?: boolean;
     }, _options: RenderResultOptions, uiTheme: Theme): Component;
+    describeCall(args: Partial<ResolveInvocation>): NativeToolView;
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: ResolveDetails;
+        isError?: boolean;
+    }): NativeToolView | undefined;
     inline: true;
     mergeCallAndResult: true;
 };

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

@@ -4,6 +4,7 @@ import type { ConfiguredThinkingLevel } from "../render/render-utils.js";
 import { type Component } from "../tui.js";
 import type { RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
+import type { NativeToolView, ToolRenderResult } from "./renderer.js";
 /** Render context threaded in from `ToolExecutionComponent.#buildRenderContext`. */
 interface TaskRenderContext {
     hasResult?: boolean;
@@ -61,6 +62,8 @@ export declare function renderNestedTaskResults(detailsList: TaskToolDetails[],
 export declare const taskToolRenderer: {
     renderCall: typeof renderCall;
     renderResult: typeof renderResult;
+    describeCall(args: TaskParams, options: RenderResultOptions): NativeToolView | undefined;
+    describeResult(result: ToolRenderResult<TaskToolDetails>, options: TaskRenderOptions, args?: TaskParams): NativeToolView | undefined;
     mergeCallAndResult: true;
 };
 /** Source of an agent definition */

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

@@ -1,3 +1,4 @@
+import type { NativeToolView } from "./renderer.js";
 import { type Component } from "../index.js";
 import type { RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
@@ -10,4 +11,6 @@ export declare const thinkToolRenderer: {
     inline: true;
     renderCall(args: ThinkRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
     renderResult(): undefined;
+    describeCall(args: ThinkRenderArgs, options: RenderResultOptions): NativeToolView;
+    describeResult(): undefined;
 };

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

@@ -1,6 +1,8 @@
 import type { Component } from "../index.js";
 import type { RenderResultOptions } from "./renderer.js";
 import type { Theme } from "../theme/theme.js";
+import type { TspChecklistPhase } from "@oh-my-pi/pi-wire";
+import type { NativeToolView, ToolRenderResult } from "./renderer.js";
 /** Lifecycle state of a todo item. */
 export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
 /** Operation names accepted by the todo tool and echoed in successful result details. */
@@ -102,6 +104,14 @@ export declare const TODO_STRIKE_REVEAL_FRAMES = 12;
 export declare const TODO_STRIKE_TOTAL_FRAMES: number;
 /** Wire the live-subagent description source for {@link todoToolRenderer}. */
 export declare function setActiveTodoDescriptionsProvider(provider: () => readonly string[]): void;
+/**
+ * Checklist phases for native terminals: plain phase titles (no roman
+ * numerals — the terminal numbers nothing), completed phases folded.
+ */
+export declare function todoChecklistPhases(phases: readonly {
+    name: string;
+    tasks: readonly TodoItem[];
+}[], isMatched?: (task: TodoItem) => boolean): TspChecklistPhase[];
 /** Render todo operations and phased task snapshots. */
 export declare const todoToolRenderer: {
     renderCall(args: TodoRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
@@ -113,6 +123,8 @@ export declare const todoToolRenderer: {
         details?: TodoToolDetails;
         isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: TodoRenderArgs): Component;
+    describeCall(args: TodoRenderArgs): NativeToolView;
+    describeResult(result: ToolRenderResult<TodoToolDetails>, options: RenderResultOptions): NativeToolView | undefined;
     mergeCallAndResult: true;
 };
 export {};

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

@@ -1,6 +1,6 @@
 import type { Component } from "../tui.js";
 import type { Theme } from "../theme/theme.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions, ToolRenderResult } from "./renderer.js";
 /** Operation represented by a worker-session tool result. */
 export type VibeOp = "spawn" | "send" | "wait" | "kill" | "list";
 /** Details payload shared by every vibe tool for TUI rendering. */
@@ -120,5 +120,7 @@ export declare function createVibeToolRenderer(op: VibeOp): {
         details?: VibeToolDetails;
         isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: VibeRenderArgs): Component;
+    describeCall(args: VibeRenderArgs): NativeToolView | undefined;
+    describeResult(result: ToolRenderResult<VibeToolDetails>, _options: RenderResultOptions, args?: VibeRenderArgs): NativeToolView | undefined;
 };
 export {};

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

@@ -5,6 +5,7 @@ import { type ConfiguredThinkingLevel } from "../render/render-utils.js";
 import type { StructuredSubagentOutput } from "./task.js";
 import type { RenderResultOptions, ToolActivitySummary } from "./renderer.js";
 import type { IrcDeliveryReceipt, IrcMessage } from "./irc.js";
+import type { NativeToolView, ToolRenderResult } from "./renderer.js";
 /** Whether a wait snapshot contains only running jobs and no cancellations. */
 export declare function isWaitingPollDetails(details: unknown): boolean;
 /** Coordination details retained by wait and background job operations. */
@@ -119,6 +120,8 @@ export declare const waitToolRenderer: {
     mergeCallAndResult: true;
     activitySummary(): ToolActivitySummary;
     renderCall: typeof waitRenderCall;
+    describeCall(): NativeToolView;
+    describeResult(result: ToolRenderResult<CoordinationDetails>, options: RenderResultOptions): NativeToolView | undefined;
     renderResult(result: {
         content: Array<{
             type: string;

package/dist/types/tools/web-search-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Web search response types shared by the coding agent's search providers and
+ * the transcript renderer in {@link ./web-search}. Render-free, so provider code
+ * can import it without loading UI components.
+ */
+/**
+ * Display label for every search implementation: `web/*` engines and the
+ * chat-model groundings. Keys are the ids providers report in
+ * {@link SearchResponse.provider} and search errors.
+ */
+export declare const SEARCH_PROVIDER_LABELS: {
+    readonly parallel: "Parallel";
+    readonly perplexity: "Perplexity";
+    readonly gemini: "Gemini";
+    readonly anthropic: "Anthropic";
+    readonly codex: "OpenAI Codex";
+    readonly openai: "OpenAI API";
+    readonly xai: "xAI";
+    readonly openrouter: "OpenRouter";
+    readonly zai: "Z.AI";
+    readonly exa: "Exa";
+    readonly tinyfish: "TinyFish";
+    readonly jina: "Jina";
+    readonly kagi: "Kagi";
+    readonly tavily: "Tavily";
+    readonly firecrawl: "Firecrawl";
+    readonly brave: "Brave";
+    readonly kimi: "Kimi";
+    readonly synthetic: "Synthetic";
+    readonly ollama: "Ollama";
+    readonly searxng: "SearXNG";
+    readonly startpage: "Startpage";
+    readonly duckduckgo: "DuckDuckGo";
+    readonly ecosia: "Ecosia";
+    readonly google: "Google";
+    readonly mojeek: "Mojeek";
+    readonly public: "Public Web";
+};
+/** Id of a search implementation; see {@link SEARCH_PROVIDER_LABELS}. */
+export type SearchProviderId = keyof typeof SEARCH_PROVIDER_LABELS;
+/** Label for a provider id; ids from older transcripts fall back to the raw id. */
+export declare function getSearchProviderLabel(id: SearchProviderId): string;
+/** Source returned by search (all providers) */
+export interface SearchSource {
+    title: string;
+    url: string;
+    snippet?: string;
+    /** ISO date string or relative ("2d ago") */
+    publishedDate?: string;
+    /** Age in seconds for consistent formatting */
+    ageSeconds?: number;
+    author?: string;
+}
+/** Citation with text reference (LLM-mediated providers) */
+export interface SearchCitation {
+    url: string;
+    title: string;
+    citedText?: string;
+}
+/** Usage metrics */
+export interface SearchUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Anthropic: number of web search requests made */
+    searchRequests?: number;
+    /** Perplexity: combined token count */
+    totalTokens?: number;
+}
+/** Unified response across providers */
+export interface SearchResponse {
+    provider: SearchProviderId | "none";
+    /** Synthesized answer text (LLM-mediated providers) */
+    answer?: string;
+    /** Search result sources */
+    sources: SearchSource[];
+    /** Text citations with context */
+    citations?: SearchCitation[];
+    /** Intermediate search queries (anthropic) */
+    searchQueries?: string[];
+    /** Follow-up question suggestions (provider-dependent) */
+    relatedQuestions?: string[];
+    /** Token usage metrics */
+    usage?: SearchUsage;
+    /** Model used */
+    model?: string;
+    /** Request ID for debugging */
+    requestId?: string;
+    /** Authentication mode used by the provider (e.g. oauth, api-key) */
+    authMode?: string;
+}

package/dist/types/tools/web-search.d.ts

@@ -1,3 +1,4 @@
+import type { NativeToolView, ToolRenderResult } from "./renderer.js";
 /**
  * Web Search TUI Rendering
  *
@@ -6,6 +7,7 @@
 import type { Component } from "../index.js";
 import type { RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
+import { type SearchResponse } from "./web-search-types.js";
 /** Search response and optional failure shown in the transcript. */
 export interface SearchRenderDetails {
     response: SearchResponse;
@@ -27,177 +29,16 @@ export declare function renderSearchCall(args: {
     query?: string;
     [key: string]: unknown;
 }, _options: RenderResultOptions, theme: Theme): Component;
+type SearchRenderArgs = {
+    query?: string;
+    [key: string]: unknown;
+};
 /** Render web search queries, answers, and cited sources. */
 export declare const webSearchToolRenderer: {
     renderCall: typeof renderSearchCall;
     renderResult: typeof renderSearchResult;
+    describeCall(args: SearchRenderArgs): NativeToolView;
+    describeResult(result: ToolRenderResult<SearchRenderDetails>, _options: RenderResultOptions, args?: SearchRenderArgs): NativeToolView | undefined;
     mergeCallAndResult: true;
 };
-/**
- * Web Search Types
- *
- * Unified types for web search responses across supported providers.
- */
-export declare const SEARCH_PROVIDER_OPTIONS: readonly [{
-    readonly value: "auto";
-    readonly label: "Auto";
-    readonly description: "Automatically uses the first configured web-search provider";
-}, {
-    readonly value: "parallel";
-    readonly label: "Parallel";
-    readonly description: "Uses API auth when configured; otherwise searches through the keyless public MCP";
-}, {
-    readonly value: "perplexity";
-    readonly label: "Perplexity";
-    readonly description: "Uses auth when configured; explicit selection falls back to anonymous search";
-}, {
-    readonly value: "gemini";
-    readonly label: "Gemini";
-    readonly description: "Google Search grounding via Gemini (uses google-gemini-cli or google-antigravity OAuth)";
-}, {
-    readonly value: "anthropic";
-    readonly label: "Anthropic";
-    readonly description: "Claude's native web_search tool (uses Anthropic OAuth or ANTHROPIC_API_KEY)";
-}, {
-    readonly value: "codex";
-    readonly label: "OpenAI Codex";
-    readonly description: "OpenAI's native web_search (uses ChatGPT OAuth via /login openai-codex)";
-}, {
-    readonly value: "openai";
-    readonly label: "OpenAI API";
-    readonly description: "OpenAI hosted web_search via OPENAI_API_KEY or OpenAI API-key registry credentials; billed by API usage";
-}, {
-    readonly value: "xai";
-    readonly label: "xAI";
-    readonly description: "Grok web search via xAI Responses API (uses SuperGrok/X Premium+ OAuth via /login xai-oauth, or XAI_API_KEY)";
-}, {
-    readonly value: "openrouter";
-    readonly label: "OpenRouter";
-    readonly description: "OpenRouter plugins-based web search with model-selected grounding";
-}, {
-    readonly value: "zai";
-    readonly label: "Z.AI";
-    readonly description: "Calls Z.AI webSearchPrime MCP";
-}, {
-    readonly value: "exa";
-    readonly label: "Exa";
-    readonly description: "API via /login exa or EXA_API_KEY; explicit keyless fallback via MCP";
-}, {
-    readonly value: "tinyfish";
-    readonly label: "TinyFish";
-    readonly description: "Requires TINYFISH_API_KEY";
-}, {
-    readonly value: "jina";
-    readonly label: "Jina";
-    readonly description: "Requires JINA_API_KEY";
-}, {
-    readonly value: "kagi";
-    readonly label: "Kagi";
-    readonly description: "Requires KAGI_API_KEY and Kagi Search API beta access";
-}, {
-    readonly value: "tavily";
-    readonly label: "Tavily";
-    readonly description: "Requires TAVILY_API_KEY";
-}, {
-    readonly value: "firecrawl";
-    readonly label: "Firecrawl";
-    readonly description: "Uses Firecrawl API when FIRECRAWL_API_KEY is set; falls back to keyless mode";
-}, {
-    readonly value: "brave";
-    readonly label: "Brave";
-    readonly description: "Requires BRAVE_API_KEY";
-}, {
-    readonly value: "kimi";
-    readonly label: "Kimi";
-    readonly description: "Kimi Code search (requires a Kimi Code Console key via KIMI_SEARCH_API_KEY/MOONSHOT_SEARCH_API_KEY or /login kimi-code; not MOONSHOT_API_KEY)";
-}, {
-    readonly value: "synthetic";
-    readonly label: "Synthetic";
-    readonly description: "Requires SYNTHETIC_API_KEY";
-}, {
-    readonly value: "ollama";
-    readonly label: "Ollama";
-    readonly description: "Requires OLLAMA_CLOUD_API_KEY";
-}, {
-    readonly value: "searxng";
-    readonly label: "SearXNG";
-    readonly description: "Requires SEARXNG_ENDPOINT or searxng.endpoint";
-}, {
-    readonly value: "startpage";
-    readonly label: "Startpage";
-    readonly description: "Credential-free scrape of Startpage (Google-backed) results; may be bot-challenged";
-}, {
-    readonly value: "duckduckgo";
-    readonly label: "DuckDuckGo";
-    readonly description: "Credential-free best-effort fallback; may be bot-challenged on datacenter/shared-egress IPs";
-}, {
-    readonly value: "ecosia";
-    readonly label: "Ecosia";
-    readonly description: "Credential-free browser-backed scrape of Ecosia (Google-backed) results";
-}, {
-    readonly value: "google";
-    readonly label: "Google";
-    readonly description: "Credential-free browser-backed fallback; slower and may be bot-challenged";
-}, {
-    readonly value: "mojeek";
-    readonly label: "Mojeek";
-    readonly description: "Credential-free browser-backed scrape of Mojeek's independent index";
-}, {
-    readonly value: "public";
-    readonly label: "Public Web";
-    readonly description: "Queries every credential-free engine in parallel and consolidates deduplicated results";
-}];
-/** Supported web search providers (every option except `auto`). */
-export type SearchProviderId = Exclude<(typeof SEARCH_PROVIDER_OPTIONS)[number]["value"], "auto">;
-/** Display labels, derived from {@link SEARCH_PROVIDER_OPTIONS}. */
-export declare const SEARCH_PROVIDER_LABELS: Record<SearchProviderId, string>;
-/** Source returned by search (all providers) */
-export interface SearchSource {
-    title: string;
-    url: string;
-    snippet?: string;
-    /** ISO date string or relative ("2d ago") */
-    publishedDate?: string;
-    /** Age in seconds for consistent formatting */
-    ageSeconds?: number;
-    author?: string;
-}
-/** Citation with text reference (LLM-mediated providers) */
-export interface SearchCitation {
-    url: string;
-    title: string;
-    citedText?: string;
-}
-/** Usage metrics */
-export interface SearchUsage {
-    inputTokens?: number;
-    outputTokens?: number;
-    /** Anthropic: number of web search requests made */
-    searchRequests?: number;
-    /** Perplexity: combined token count */
-    totalTokens?: number;
-}
-/** Unified response across providers */
-export interface SearchResponse {
-    provider: SearchProviderId | "none";
-    /** Synthesized answer text (LLM-mediated providers) */
-    answer?: string;
-    /** Search result sources */
-    sources: SearchSource[];
-    /** Text citations with context */
-    citations?: SearchCitation[];
-    /** Intermediate search queries (anthropic) */
-    searchQueries?: string[];
-    /** Follow-up question suggestions (provider-dependent) */
-    relatedQuestions?: string[];
-    /** Token usage metrics */
-    usage?: SearchUsage;
-    /** Model used */
-    model?: string;
-    /** Request ID for debugging */
-    requestId?: string;
-    /** Authentication mode used by the provider (e.g. oauth, api-key) */
-    authMode?: string;
-}
-/** Cheap, sync metadata accessor — never triggers a provider load. */
-export declare function getSearchProviderLabel(id: SearchProviderId): string;
+export {};

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

@@ -6,7 +6,7 @@ import { type ProcWriteDetails } from "./proc-render.js";
 import { type CfgWriteDetails } from "./cfg-render.js";
 import type { FileDiagnosticsResult } from "./lsp.js";
 import type { OutputMeta } from "./output-meta.js";
-import type { RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer.js";
 import { type XdevRenderDispatch, type XdevMountedRenderer } from "./xdev.js";
 /** Details returned by the write tool for transcript rendering. */
 export interface WriteToolDetails {
@@ -76,6 +76,19 @@ export declare const writeToolRenderer: {
     }, options: RenderResultOptions & {
         renderContext?: WriteRenderContext;
     }, uiTheme: Theme, args?: WriteRenderArgs): Component;
+    describeCall(args: WriteRenderArgs, options: RenderResultOptions & {
+        renderContext?: WriteRenderContext;
+    }): NativeToolView | undefined;
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: WriteToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: WriteRenderContext;
+    }, args?: WriteRenderArgs): NativeToolView | undefined;
     mergeCallAndResult: true;
     forceFirstResultViewportRepaint: (args: unknown, options: RenderResultOptions) => boolean;
 };

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

@@ -2,9 +2,12 @@ import type { ToolTier } from "@oh-my-pi/pi-agent-core";
 import { type Component } from "../index.js";
 import type { Theme } from "../theme/theme.js";
 import type { RenderResultOptions, ToolActivitySummary, ToolRenderer } from "./renderer.js";
+import type { NativeToolView } from "./renderer.js";
 /** Mounted device display callbacks, independent of tool execution state. */
 export interface XdevMountedRenderer {
     label?: string;
+    describeCall?: ToolRenderer["describeCall"];
+    describeResult?: ToolRenderer["describeResult"];
     renderCall?(...args: Parameters<ToolRenderer["renderCall"]>): unknown;
     renderResult?(...args: Parameters<ToolRenderer["renderResult"]>): unknown;
     mergeCallAndResult?: boolean;
@@ -50,6 +53,16 @@ export declare function xdevActivitySummary(name: string, content: unknown, reso
  * nothing) when no renderer produces output.
  */
 export declare function renderXdevCall(name: string, content: unknown, options: RenderResultOptions, theme: Theme, resolveMounted?: (name: string) => XdevMountedRenderer | undefined): Component | undefined;
+/** TSP call view for an `xd://` write: queued card until execution, then the device renderer's own view. */
+export declare function describeXdevCall(name: string, content: unknown, options: RenderResultOptions, resolveMounted?: (name: string) => XdevMountedRenderer | undefined): NativeToolView | undefined;
+/** TSP result view for an `xd://` dispatch, forwarded to the device renderer. */
+export declare function describeXdevResult(dispatch: XdevRenderDispatch, result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+}, options: RenderResultOptions, resolveMounted?: (name: string) => XdevMountedRenderer | undefined): NativeToolView | undefined;
 /** Forward an `xd://` dispatch result to the mounted tool's renderer. */
 export declare function renderXdevResult(dispatch: XdevRenderDispatch, result: {
     content: Array<{

package/dist/types/tui.d.ts

@@ -1,4 +1,6 @@
+import type { TspFrame, TspNode, TspText } from "@oh-my-pi/pi-wire";
 import { ImageBudget } from "./components/image.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "./native/node.js";
 import { type Terminal } from "./terminal.js";
 import { visibleWidth } from "./utils.js";
 /** Full-attribute reset terminating each rendered content row. */
@@ -109,6 +111,35 @@ export interface Component {
      * last time.
      */
     render(width: number): readonly string[];
+    /**
+     * Describe the component semantically for a Tern Surface Protocol
+     * terminal (see `native/node.ts`). Called instead of `render()` when the
+     * native backend is active. Return the same node object while nothing
+     * changed; return null to fall back to `render()` rows.
+     */
+    describe?(cx: DescribeContext): NativeNode | null;
+    /**
+     * Props for the native `overlay` wrapper when this component is shown as
+     * an overlay: the sheet's `role` (Tern styles `omp.overlay.*` roles as
+     * glass sheets, so the component's own root must not draw a second frame),
+     * `head` spans for the sheet's title row, and `size`/`anchor` overriding
+     * the ones derived from the overlay options.
+     */
+    nativeOverlay?: {
+        role?: string;
+        head?: TspText;
+        size?: "sm" | "md" | "lg" | "full";
+        anchor?: "center" | "top" | "bottom";
+    };
+    /**
+     * True when this component, shown as an overlay, describes a data-first
+     * sheet (`picker`, `prefs`) that is its own frame: the backend puts it
+     * directly in `layer` with no `overlay` wrapper. Usually
+     * `cx.supports("picker")`, so older terminals keep the wrapped fallback.
+     */
+    nativeSheet?(cx: DescribeContext): boolean;
+    /** User actions on nodes this component described (toggle, select, activate, custom). */
+    handleNativeEvent?(event: NativeUiEvent): void;
     /**
      * Optional handler for keyboard input when component has focus
      */
@@ -269,6 +300,7 @@ export declare class Container implements Component {
      */
     dispose(): void;
     render(width: number): readonly string[];
+    describe(_cx: DescribeContext): NativeNode | null;
 }
 /**
  * Merge runs of byte-adjacent SGR sequences (`CSI [0-9;:]* m`) into one. Only
@@ -382,6 +414,23 @@ export declare class TUI extends Container {
     setInlineMouseTrackingProvider(provider: (() => boolean) | undefined): void;
     invalidate(): void;
     start(options?: TUIStartOptions): void;
+    /** Whether frames go to a Tern Surface Protocol surface instead of the row renderer. */
+    get nativeRendering(): boolean;
+    /**
+     * Close the TSP surfaces ahead of {@link stop}, before the exit drains
+     * input: the terminal answers nothing once they are closed, and whatever it
+     * already sent (acks, events) is read and dropped here instead of reaching
+     * the shell as typed text. A render already requested (the exit's status
+     * line) goes out first; none is forced, and nothing renders from now until
+     * `stop()`.
+     */
+    closeNative(): void;
+    /** Reference document the TSP terminal should hold (debug mirror only). */
+    getNativeDocument(): TspNode | undefined;
+    /** Most recent TSP frames sent (debug mirror only). */
+    getNativeFrames(count?: number): readonly TspFrame[];
+    /** `rows` fallback nodes in the last native frame. */
+    get nativeFallbackCount(): number;
     /**
      * Take ownership of stdin after a `deferInput` start: raw mode, input
      * handlers, and the response-eliciting capability probes start() skipped.