@oh-my-pi/pi-tui 18.2.4 → 18.2.6

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

@@ -0,0 +1,120 @@
+import type { Component } from "../tui.js";
+import type { Theme } from "../theme/theme.js";
+import type { RenderResultOptions } 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. */
+export interface VibeToolDetails {
+    op: VibeOp;
+    /** Live TV-wall snapshot of the owner's worker sessions at (or during) the call. */
+    screens: VibeScreenSnapshot[];
+    spawned?: {
+        id: string;
+        cli: VibeCli;
+        jobId: string;
+    };
+    send?: VibeSendOutcome;
+    wait?: {
+        settled: Array<{
+            id: string;
+            jobId: string;
+            status: "completed" | "failed" | "cancelled";
+        }>;
+        stillRunning: string[];
+        timedOut: boolean;
+        /** True on interim progress emissions while the wait is still blocking. */
+        waiting?: boolean;
+    };
+    killed?: VibeKillOutcome;
+}
+/** Worker session lifecycle as shown to the director. */
+export type VibeSessionState = "starting" | "running" | "idle" | "dead";
+/**
+ * Live per-session "screen" for rich rendering: what the worker is doing right
+ * now (tool trace, current tool, streamed text tail) plus roster metadata.
+ * Every string is already one-line sanitized.
+ */
+export interface VibeScreenSnapshot {
+    id: string;
+    cli: VibeCli;
+    state: VibeSessionState;
+    model?: string;
+    turns: number;
+    queued: number;
+    /** Start of the in-flight turn, when running. */
+    turnStartedAt?: number;
+    /** Gist of the message that started the in-flight turn. */
+    turnMessage?: string;
+    currentTool?: string;
+    currentToolArgs?: string;
+    lastIntent?: string;
+    /** Completed tool calls of the in-flight turn, oldest first (tail). */
+    trace: string[];
+    /** Latest streamed worker text lines, oldest first. */
+    outputTail: string[];
+    lastActivity?: string;
+    lastActivityAt: number;
+}
+/** Worker identity and job handle returned by a spawn. */
+export interface VibeSpawnOutcome {
+    id: string;
+    jobId: string;
+}
+/** Delivery mode and optional turn job for a worker message. */
+export interface VibeSendOutcome {
+    id: string;
+    /**
+     * - `turn`: a new background turn was started (`jobId` set).
+     * - `steered`: worker was mid-turn and streaming; delivered as steering.
+     * - `queued`: worker was mid-turn but not steerable; drained into the next turn.
+     */
+    mode: "turn" | "steered" | "queued";
+    jobId?: string;
+}
+/** Worker shutdown outcome including any cancelled turn. */
+export interface VibeKillOutcome {
+    id: string;
+    /** True when an in-flight turn job was cancelled along the way. */
+    cancelledTurn: boolean;
+}
+/** Settled and still-running worker turns observed by a wait. */
+export interface VibeWaitOutcome {
+    /** Watched sessions whose snapshotted turn settled during (or before) the wait.
+     * May overlap `stillRunning` when a queued follow-up turn already started. */
+    settled: Array<{
+        id: string;
+        jobId: string;
+        status: "completed" | "failed" | "cancelled";
+        resultText: string;
+    }>;
+    /** Watched sessions with a turn in flight when the wait returned. */
+    stillRunning: string[];
+    timedOut: boolean;
+}
+/** The two worker CLI flavors the director drives. */
+export type VibeCli = "fast" | "good";
+interface VibeRenderArgs {
+    cli?: VibeCli;
+    prompt?: string;
+    name?: string;
+    session?: string;
+    message?: string;
+    sessions?: string[];
+}
+/** Build the shared vibe renderer for one tool name. */
+export declare function createVibeToolRenderer(op: VibeOp): {
+    inline: true;
+    mergeCallAndResult: true;
+    animatedPendingPreview: boolean;
+    animatedPartialResult: boolean;
+    renderCall(args: VibeRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: VibeToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: VibeRenderArgs): Component;
+};
+export {};

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

@@ -0,0 +1,195 @@
+/**
+ * Web Search TUI Rendering
+ *
+ * Tree-based rendering with collapsed/expanded states for web search results.
+ */
+import type { Component } from "../index.js";
+import type { RenderResultOptions } from "./renderer.js";
+import { type Theme } from "../theme/theme.js";
+/** Search response and optional failure shown in the transcript. */
+export interface SearchRenderDetails {
+    response: SearchResponse;
+    error?: string;
+}
+/** Render web search result with tree-based layout */
+export declare function renderSearchResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: SearchRenderDetails;
+}, options: RenderResultOptions, theme: Theme, args?: {
+    query?: string;
+    maxAnswerLines?: number;
+}): Component;
+/** Render web search call (query preview) */
+export declare function renderSearchCall(args: {
+    query?: string;
+    [key: string]: unknown;
+}, _options: RenderResultOptions, theme: Theme): Component;
+/** Render web search queries, answers, and cited sources. */
+export declare const webSearchToolRenderer: {
+    renderCall: typeof renderSearchCall;
+    renderResult: typeof renderSearchResult;
+    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";
+    readonly description: "OpenAI's native web_search (uses ChatGPT OAuth via /login openai-codex)";
+}, {
+    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: "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;

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

@@ -0,0 +1,76 @@
+import type { HighlightStream } from "@oh-my-pi/pi-natives";
+import type { Component } from "../tui.js";
+import { type Theme } from "../theme/theme.js";
+import type { FileDiagnosticsResult } from "./lsp.js";
+import type { OutputMeta } from "./output-meta.js";
+import type { 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 {
+    diagnostics?: FileDiagnosticsResult;
+    meta?: OutputMeta;
+    /** Set when the file was auto-chmod'd because content begins with a `#!` shebang. */
+    madeExecutable?: boolean;
+    /** Absolute filesystem path the write resolved to. Used by the renderer to wrap
+     * the (possibly cwd-relative) header path in an OSC 8 `file://` hyperlink. */
+    resolvedPath?: string;
+    /** Set when the write dispatched an `xd://` tool device; drives renderer delegation. */
+    xdev?: XdevRenderDispatch;
+}
+interface WriteRenderArgs {
+    path?: unknown;
+    file_path?: unknown;
+    content?: unknown;
+}
+declare const writeStreamingPreviewStateKey: unique symbol;
+/**
+ * Per-component state for incrementally rendering a streamed write.
+ * The ToolExecutionComponent's persistent render options carry the state, so
+ * it lives exactly as long as the component and cannot leak across tool calls.
+ */
+interface WriteStreamingPreviewState {
+    /** Prior full content; append-only growth is validated with an exact prefix check. */
+    previous: string;
+    /** `1 + count("\n")` over the scanned content. */
+    lineCount: number;
+    /** Raw offset immediately after the last newline consumed by `highlighter`. */
+    completeLength: number;
+    /** Highlighted, complete logical lines; the unfinished trailing line is rendered plain. */
+    highlightedLines: string[];
+    /** Stateful parser carrying syntax scopes across appended complete lines. */
+    highlighter: HighlightStream | null;
+    language: string | undefined;
+    uiTheme: Theme;
+    /** Content length for which the trailing line was flushed as final (`argsComplete`); -1 when none. */
+    finalFlushedLength: number;
+    /** Highlighted trailing line from the final flush; rendered in place of the plain tail. */
+    finalTrailing: string;
+}
+interface WriteStreamingPreviewStateCarrier {
+    [writeStreamingPreviewStateKey]?: WriteStreamingPreviewState;
+}
+/** Render context for the write tool: resolves an `xd://`-mounted tool so its live renderer drives device dispatch previews. */
+export interface WriteRenderContext {
+    resolveXdevMounted?: (name: string) => XdevMountedRenderer | undefined;
+}
+/** Render file writes and delegated tool-device calls. */
+export declare const writeToolRenderer: {
+    /** Compact one-line activity: device writes read as the mounted tool (`LSP · references foo`), file writes as `Write · <path>`. */
+    activitySummary(args: unknown, context: ToolActivityContext): ToolActivitySummary;
+    renderCall(args: WriteRenderArgs, options: RenderResultOptions & WriteStreamingPreviewStateCarrier & {
+        renderContext?: WriteRenderContext;
+    }, uiTheme: Theme): Component | undefined;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: WriteToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: WriteRenderContext;
+    }, uiTheme: Theme, args?: WriteRenderArgs): Component;
+    mergeCallAndResult: true;
+    forceFirstResultViewportRepaint: (args: unknown, options: RenderResultOptions) => boolean;
+};
+export {};

package/dist/types/tools/xd-url.d.ts

@@ -0,0 +1,13 @@
+/** Canonical prefix for virtual tool-device URLs. */
+export declare const XD_URL_PREFIX = "xd://";
+/** Returns the canonical tool name from a bare or `xd://`-prefixed spelling. */
+export declare function stripXdUrlPrefix(name: string): string;
+/**
+ * Parse an `xd://` URL into its device target.
+ * Returns `null` for other or malformed URLs and `name: null` for the root.
+ */
+export declare function parseXdUrl(input: string): {
+    name: string | null;
+} | null;
+/** Whether a streaming path prefix could still become an `xd://` URL. */
+export declare function couldBecomeXdUrl(partialPath: string): boolean;

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

@@ -0,0 +1,52 @@
+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";
+/** Mounted device display callbacks, independent of tool execution state. */
+export interface XdevMountedRenderer {
+    label?: string;
+    renderCall?(...args: Parameters<ToolRenderer["renderCall"]>): unknown;
+    renderResult?(...args: Parameters<ToolRenderer["renderResult"]>): unknown;
+    mergeCallAndResult?: boolean;
+}
+/** Mounted tool presentation state supplied by the host's canonical tool map. */
+export interface XdevMountedState {
+    readonly mountedNames: ReadonlySet<string>;
+    readonly tools: ReadonlyMap<string, XdevMountedRenderer>;
+}
+/** Result metadata consumed by delegated device rendering. */
+export interface XdevRenderDispatch {
+    tool: string;
+    mode: "help" | "execute";
+    args?: Record<string, unknown>;
+    tier?: ToolTier;
+    inner?: unknown;
+}
+/** Wire the wrapped-renderer lookup. Called once by `renderers.ts`. */
+export declare function setXdevRendererLookup(lookup: (name: string) => ToolRenderer | undefined): void;
+/**
+ * Compact `label · verb object` activity summary for a device write, so a
+ * squeezed transcript row reads `LSP · references foo` instead of
+ * `Write · xd://lsp`. Prose payloads (resolution devices, report_issue)
+ * surface their first line instead.
+ */
+export declare function xdevActivitySummary(name: string, content: unknown, resolveMounted?: (name: string) => XdevMountedRenderer | undefined): ToolActivitySummary;
+/**
+ * Streaming-safe call preview for an `xd://` write. Until the write actually
+ * executes (`executionStarted` / `tool_execution_start`), show a queued/planning
+ * card so Grok-style think-after-toolcall stalls do not look like a hung
+ * inner tool. `argsComplete` alone is not enough: exclusive writes can sit
+ * complete at `message_end` while an earlier call still runs. Once execution
+ * starts, forward the decoded inner args to the mounted tool's renderer
+ * (session instance first, then the static map). Returns `undefined` (render
+ * 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;
+/** Forward an `xd://` dispatch result to the mounted tool's renderer. */
+export declare function renderXdevResult(dispatch: XdevRenderDispatch, result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+}, options: RenderResultOptions, theme: Theme, resolveMounted?: (name: string) => XdevMountedRenderer | undefined): Component | undefined;

package/dist/types/tui.d.ts

@@ -1,6 +1,8 @@
 import { ImageBudget } from "./components/image.js";
 import { type Terminal } from "./terminal.js";
 import { visibleWidth } from "./utils.js";
+/** Full-attribute reset terminating each rendered content row. */
+export declare const SEGMENT_RESET = "\u001B[0m";
 type InputListenerResult = {
     consume?: boolean;
     data?: string;
@@ -15,8 +17,22 @@ export interface RenderScheduler {
     scheduleImmediate(callback: () => void): void;
     scheduleRender(callback: () => void, delayMs: number): RenderTimer;
 }
+/** Rows painted by one TUI frame, observed through `TUIOptions.onPaint`. */
+export interface TuiPaint {
+    /** Rows committed above the viewport by this paint (native scrollback). Empty on diff paints and alt-screen paints. */
+    readonly history: readonly string[];
+    /** Complete live viewport after this paint: one prepared (normalized, width-truncated, SGR-coalesced) ANSI string per row. */
+    readonly viewport: readonly string[];
+    /** True when this paint erased scrollback and repainted from row zero (destructive reset or history replay): consumers drop their history copy before applying `history`. */
+    readonly reset: boolean;
+    /** True when `viewport` is an alternate-screen overlay; history is untouched. */
+    readonly alt: boolean;
+    readonly columns: number;
+    readonly rows: number;
+}
 export interface TUIOptions {
     renderScheduler?: RenderScheduler;
+    onPaint?: (paint: TuiPaint) => void;
 }
 /** Physical terminal dimensions supplied to a frame provider. */
 export interface ViewportSize {
@@ -274,6 +290,8 @@ export declare class TUI extends Container {
         hidden: boolean;
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
+    /** Install a listener for completed terminal paints. */
+    setPaintListener(listener: ((paint: TuiPaint) => void) | null): void;
     /** Install the product-owned bounded frame provider. */
     setFrameProvider(provider: TerminalFrameProvider | undefined): void;
     get fullRedraws(): number;

package/dist/types/utils.d.ts

@@ -34,6 +34,8 @@ export declare function replaceTabs(text: string): string;
  * Returns a string of n spaces. Uses a pre-allocated buffer for efficiency.
  */
 export declare function padding(n: number): string;
+/** Center a line in a field of `width` columns, truncating when too wide. */
+export declare function centerLine(line: string, width: number): string;
 /**
  * Get the shared grapheme segmenter instance.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.2.4",
+	"version": "18.2.6",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,8 +37,14 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.2.4",
-		"@oh-my-pi/pi-utils": "18.2.4"
+		"@oh-my-pi/omptype": "18.2.6",
+		"@oh-my-pi/pi-agent-core": "18.2.6",
+		"@oh-my-pi/pi-ai": "18.2.6",
+		"@oh-my-pi/pi-catalog": "18.2.6",
+		"@oh-my-pi/pi-natives": "18.2.6",
+		"@oh-my-pi/pi-utils": "18.2.6",
+		"@oh-my-pi/pi-wire": "18.2.6",
+		"@oh-my-pi/snapcompact": "18.2.6"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"
@@ -59,6 +65,34 @@
 			"types": "./dist/types/index.d.ts",
 			"import": "./src/index.ts"
 		},
+		"./theme": {
+			"types": "./dist/types/theme/index.d.ts",
+			"import": "./src/theme/index.ts"
+		},
+		"./theme/defaults": {
+			"types": "./dist/types/theme/defaults/index.d.ts",
+			"import": "./src/theme/defaults/index.ts"
+		},
+		"./theme/*": {
+			"types": "./dist/types/theme/*.d.ts",
+			"import": "./src/theme/*.ts"
+		},
+		"./render": {
+			"types": "./dist/types/render/index.d.ts",
+			"import": "./src/render/index.ts"
+		},
+		"./chrome": {
+			"types": "./dist/types/chrome/index.d.ts",
+			"import": "./src/chrome/index.ts"
+		},
+		"./tools": {
+			"types": "./dist/types/tools/index.d.ts",
+			"import": "./src/tools/index.ts"
+		},
+		"./status-line": {
+			"types": "./dist/types/status-line/index.d.ts",
+			"import": "./src/status-line/index.ts"
+		},
 		"./*": {
 			"types": "./dist/types/*.d.ts",
 			"import": "./src/*.ts"