@linxiraos/pi-tui 1.2.1 → 1.3.1

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

@@ -1,6 +1,6 @@
 import type { SummaryResult } from "@linxiraos/pi-natives";
 import type { Component } from "../tui.js";
-import type { NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer.js";
+import type { RenderResultContextOptions, NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer.js";
 import type { NativeNode } from "../native/node.js";
 import type { Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
@@ -20,6 +20,12 @@ export interface ReadToolDetails {
     truncation?: ReadTruncationStats;
     isDirectory?: boolean;
     resolvedPath?: string;
+    /**
+     * Absolute path of the disk file whose image this read returned. A native TSP host that
+     * supports `media` shows the file by path instead of the uploaded image bytes. Unset for
+     * screenshots, URL reads and other images not backed by a file. Display-only.
+     */
+    mediaPath?: string;
     suffixResolution?: {
         from: string;
         to: string;
@@ -34,6 +40,11 @@ export interface ReadToolDetails {
     fileSize?: number;
     /** Full source line count when the read reached EOF and the count is exact. */
     totalLines?: number;
+    /**
+     * Whether the text's rows carry line-number prefixes (`N:` hashline, `N|` line numbers). Set where a
+     * file read is formatted; a raw read sets `false`. Snapcompact reads it to tell a `12:` prefix from content.
+     */
+    rowPrefixes?: boolean;
     /** Raw text + start line for user-visible TUI rendering, set when content is text-like.
      * Mirrors the same lines the model receives but without hashline/line-number prefixes,
      * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
@@ -49,7 +60,10 @@ export interface ReadToolDetails {
     };
     /** Number of unresolved git conflicts surfaced by this read (TUI uses for inline `⚠ N` badge). */
     conflictCount?: number;
-    /** Paths recovered from a delimited read argument; used only by the TUI to render one call as multiple read rows. */
+    /**
+     * Paths recovered from a delimited read argument. The TUI renders one call as multiple read rows; snapcompact
+     * keeps such a composite result as text.
+     */
     displayReadTargets?: string[];
     /**
      * Resolved filesystem link target for each {@link displayReadTargets} entry, aligned by index; `null` when a
@@ -107,14 +121,22 @@ export declare function pendingFileLinkPath(inputPath: string): string;
  * target when the structured `resolvedPath` isn't set (the common plain-file and
  * image reads only record the path in `meta.source`). URL/internal sources are
  * not fs paths, so only `type: "path"` qualifies. */
-export declare function readSourceFsPath(details: ReadToolDetails | undefined): string | undefined;
+export declare function readSourceFsPath(details: unknown): string | undefined;
+/**
+ * Whether a read result renders as a Markdown preview rather than numbered source:
+ * the read tool tagged it `text/markdown` (`read.renderMarkdown`, or a protocol
+ * resource) and the call did not ask for `:raw` source. Shared by the standalone
+ * read card and the read group's content previews so both honor the setting.
+ */
+export declare function readResultIsMarkdown(details: ReadToolDetails | undefined, args: ReadRenderArgs | undefined): boolean;
 /**
- * Read content as numbered `code` (no path header: the head names the file).
- * Numbers come from `lineNumbers` (`displayContent`'s per-line numbers,
- * `null` for an elided block; runs split with `…` between) when they cover
- * every line, else count up from `start`.
+ * Read content as numbered, wrapped `code` (no path header: the head names
+ * the file), matching the ANSI preview's hanging wrap. Numbers come from
+ * `lineNumbers` (`displayContent`'s per-line numbers, `null` for an elided
+ * block; runs split with `…` between) when they cover every line, else count
+ * up from `start`.
  */
-export declare function readContentCode(content: string, start: number, numbers: readonly (number | null)[] | undefined, lang: string | undefined): NativeNode[];
+export declare function readContentCode(content: string, start: number, numbers: readonly (number | null)[] | undefined, path: string | undefined): NativeNode[];
 /** Render file, image, and URL reads in the transcript. */
 export declare const readToolRenderer: {
     activitySummary(args: unknown, _context: ToolActivityContext): ToolActivitySummary;
@@ -126,7 +148,7 @@ export declare const readToolRenderer: {
         }>;
         details?: ReadToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, uiTheme: Theme, args?: ReadRenderArgs): Component;
+    }, options: RenderResultContextOptions, uiTheme: Theme, args?: ReadRenderArgs): Component;
     describeCall(args: ReadRenderArgs): NativeToolView;
     /**
      * Inline (§7.3 read): the head names the file and range; the content
@@ -140,7 +162,7 @@ export declare const readToolRenderer: {
         }>;
         details?: ReadToolDetails;
         isError?: boolean;
-    }, _options: RenderResultOptions, args?: ReadRenderArgs): NativeToolView;
+    }, options: RenderResultContextOptions, args?: ReadRenderArgs): NativeToolView;
     mergeCallAndResult: true;
 };
 /** Inclusive line range describing one elided span in a structural summary. */

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

@@ -33,6 +33,8 @@ export interface RenderResultOptions {
     elapsedMs?: number;
     /** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
     cancelled?: boolean;
+    /** The native host shows files by path (`cx.supports("media")`). Native describe hooks only. */
+    media?: boolean;
 }
 /** Render options for a result, plus the tool-specific context the transcript threads through. */
 export type RenderResultContextOptions = RenderResultOptions & {

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

@@ -101,6 +101,10 @@ export interface TaskItem {
     name?: string;
     /** Agent type to run this item (e.g. "scout"). Defaults to the spawn policy's default agent. */
     agent?: string;
+    /** Historical source session selected by the bundled consult agent. */
+    sourceSession?: string;
+    /** Optional model selector override for the historical source session. */
+    model?: string | string[];
     /** The work; required by the schema. */
     task?: string;
     /** How open-ended the work is; required by the schema and the child's sole `auto` thinking classification input. */
@@ -127,6 +131,10 @@ export interface TaskParams {
     name?: string;
     /** Agent type to spawn (flat form); omitted values resolve from the session spawn policy. */
     agent?: string;
+    /** Historical source session selected by the bundled consult agent. */
+    sourceSession?: string;
+    /** Optional model selector override for the historical source session. */
+    model?: string | string[];
     /** The work (flat form). */
     task?: string;
     /** How open-ended the work is (flat form); see {@link TaskItem.solutionSpace}. */
@@ -383,6 +391,29 @@ export interface SingleResult {
         attempt: number;
         errorMessage: string;
     };
+    /**
+     * Coarse category of a non-zero exit — `usage-limit`, `auth`,
+     * `account-policy`, `context-overflow`, `transient`, `aborted`, or
+     * `unknown`. A parent agent reads this to tell "swap the model" (the first
+     * three) from "fix the request" instead of parsing provider prose.
+     */
+    failureClass?: "usage-limit" | "auth" | "account-policy" | "context-overflow" | "transient" | "aborted" | "unknown";
+    /**
+     * Other models this session could run instead (selectors accepted by the
+     * task `model` parameter, including `@role` aliases). Empty when nothing
+     * else is configured or every alternative is already in cooldown.
+     */
+    fallbackCandidates?: string[];
+    /**
+     * Set when a caller-supplied `model` replaced the model this run would
+     * otherwise have used — the audit trail of an agent-driven switch.
+     */
+    modelChange?: {
+        source: "spawn-param" | "wake-param";
+        /** The model the run would have used without the override, when resolvable. */
+        from?: string;
+        to: string;
+    };
     /** Output metadata for agent:// URL integration */
     outputMeta?: {
         lineCount: number;

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

@@ -25,6 +25,7 @@ export declare const SEARCH_PROVIDER_LABELS: {
     readonly tavily: "Tavily";
     readonly firecrawl: "Firecrawl";
     readonly brave: "Brave";
+    readonly deepseek: "DeepSeek";
     readonly kimi: "Kimi";
     readonly synthetic: "Synthetic";
     readonly ollama: "Ollama";

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

@@ -73,6 +73,8 @@ interface WriteStreamingPreviewStateCarrier {
 /** 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;
+    /** Original result metadata used only for filesystem link targets. */
+    rawDetails?: unknown;
 }
 /** Render file writes and delegated tool-device calls. */
 export declare const writeToolRenderer: {

package/dist/types/tui.d.ts

@@ -115,9 +115,6 @@ export interface Component {
      * last time.
      */
     render(width: number): readonly string[];
-    /** Inline decision panels must keep displaced settled transcript rows in
-     * native scrollback even when mounted inside a transient editor container. */
-    readonly retireDisplacedTranscript?: boolean;
     /**
      * Describe the component semantically for a Tern Surface Protocol
      * terminal (see `native/node.ts`). Called instead of `render()` when the
@@ -351,6 +348,7 @@ export declare class TUI extends Container {
     overlayStack: {
         component: Component;
         options?: OverlayOptions;
+        /** Focus restored after closing; tracks live focus changes beneath an input-less key holder. */
         preFocus: Component | null;
         hidden: boolean;
         /**
@@ -458,6 +456,16 @@ export declare class TUI extends Container {
         top: number;
         length: number;
     };
+    /**
+     * Rows of native history the last paint left on screen above a mutable
+     * viewport that reached the bottom row, or `undefined` when that paint left
+     * rows free below it (or none happened, or a destructive reset will repaint
+     * from row zero). Rows above a bottom-reaching viewport may already sit in
+     * native scrollback, which a later shrink cannot pull back down.
+     */
+    getFilledHistoryRows(): number | undefined;
+    /** Whether native history holds rows the frame provider committed since the last destructive reset. */
+    hasProviderHistory(): boolean;
     /**
      * Probe for opt-in normal-buffer click capture. The provider is read every
      * frame; while it returns true (and no fullscreen overlay owns the
@@ -507,6 +515,13 @@ export declare class TUI extends Container {
      * overtaking them. No-op unless `previous` owns the held keys.
      */
     replaceHeldFocus(previous: Component, next: Component): void;
+    /**
+     * Register a hook that re-enables terminal modes on every start(). A hook
+     * added while the TUI is already running (a prepaint composer starts it
+     * before the interactive mode wires its controllers) missed that start, so
+     * it runs immediately instead of waiting for a stop/start cycle that may
+     * never come.
+     */
     addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
@@ -519,6 +534,8 @@ export declare class TUI extends Container {
      */
     resetDisplay(): void;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
+    /** Run `callback` after `delayMs` on the render scheduler's clock, unless the TUI has stopped. */
+    scheduleAfter(delayMs: number, callback: () => void): RenderTimer;
     /**
      * Paint a forced frame synchronously when startup must hand off an already
      * visible component tree before further async initialization. Same as

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-tui",
-	"version": "1.2.1",
+	"version": "1.3.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Linxira-OS",
@@ -30,7 +30,7 @@
 	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "tsc -p tsconfig.json --noEmit",
 		"lint": "oxlint .",
 		"test": "bun test --parallel test/*.test.ts",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
@@ -38,14 +38,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@linxiraos/pi-omptype": "1.2.1",
-		"@linxiraos/pi-agent-core": "1.2.1",
-		"@linxiraos/pi-ai": "1.2.1",
-		"@linxiraos/pi-catalog": "1.2.1",
-		"@linxiraos/pi-natives": "1.2.1",
-		"@linxiraos/pi-utils": "1.2.1",
-		"@linxiraos/pi-wire": "1.2.1",
-		"@linxiraos/pi-snapcompact": "1.2.1"
+		"@linxiraos/pi-omptype": "1.3.1",
+		"@linxiraos/pi-agent-core": "1.3.1",
+		"@linxiraos/pi-ai": "1.3.1",
+		"@linxiraos/pi-catalog": "1.3.1",
+		"@linxiraos/pi-natives": "1.3.1",
+		"@linxiraos/pi-utils": "1.3.1",
+		"@linxiraos/pi-wire": "1.3.1",
+		"@linxiraos/pi-snapcompact": "1.3.1"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/app-keybindings.d.ts

@@ -17,6 +17,8 @@ interface AppKeybindings {
     "app.model.selectTemporary": true;
     "app.tools.expand": true;
     "app.tools.toggleVisibility": true;
+    "app.ask.hide": true;
+    "app.approval.approve": true;
     "app.editor.external": true;
     "app.message.followUp": true;
     "app.retry": true;
@@ -36,8 +38,8 @@ interface AppKeybindings {
     "app.session.rename": true;
     "app.session.delete": true;
     "app.session.deleteNoninvasive": true;
-    "app.tree.foldOrUp": true;
-    "app.tree.unfoldOrDown": true;
+    "app.tree.previousBranch": true;
+    "app.tree.nextBranch": true;
     "app.plan.toggle": true;
     "app.history.search": true;
     "app.stt.pushToTalk": true;
@@ -238,6 +240,14 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: "ctrl+shift+o";
         readonly description: "Show or hide tool activity";
     };
+    readonly "app.ask.hide": {
+        readonly defaultKeys: "alt+h";
+        readonly description: "Hide or show a pending ask dialog";
+    };
+    readonly "app.approval.approve": {
+        readonly defaultKeys: ["ctrl+enter", "ctrl+q"];
+        readonly description: "Approve a pending tool call";
+    };
     readonly "app.editor.external": {
         readonly defaultKeys: "ctrl+g";
         readonly description: "Open external editor";
@@ -314,13 +324,13 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: "ctrl+backspace";
         readonly description: "Delete session (non-invasive)";
     };
-    readonly "app.tree.foldOrUp": {
-        readonly defaultKeys: ["ctrl+left", "alt+left"];
-        readonly description: "Fold or move up";
+    readonly "app.tree.previousBranch": {
+        readonly defaultKeys: [];
+        readonly description: "Jump to the previous branch in /tree";
     };
-    readonly "app.tree.unfoldOrDown": {
-        readonly defaultKeys: ["ctrl+right", "alt+right"];
-        readonly description: "Unfold or move down";
+    readonly "app.tree.nextBranch": {
+        readonly defaultKeys: [];
+        readonly description: "Jump to the next branch in /tree";
     };
     readonly "app.plan.toggle": {
         readonly defaultKeys: "alt+shift+p";

package/src/app-keybindings.ts

@@ -37,6 +37,8 @@ interface AppKeybindings {
 	"app.model.selectTemporary": true;
 	"app.tools.expand": true;
 	"app.tools.toggleVisibility": true;
+	"app.ask.hide": true;
+	"app.approval.approve": true;
 	"app.editor.external": true;
 	"app.message.followUp": true;
 	"app.retry": true;
@@ -56,8 +58,8 @@ interface AppKeybindings {
 	"app.session.rename": true;
 	"app.session.delete": true;
 	"app.session.deleteNoninvasive": true;
-	"app.tree.foldOrUp": true;
-	"app.tree.unfoldOrDown": true;
+	"app.tree.previousBranch": true;
+	"app.tree.nextBranch": true;
 	"app.plan.toggle": true;
 	"app.history.search": true;
 	"app.stt.pushToTalk": true;
@@ -138,6 +140,16 @@ export const KEYBINDINGS = {
 		defaultKeys: "ctrl+shift+o",
 		description: "Show or hide tool activity",
 	},
+	"app.ask.hide": {
+		defaultKeys: "alt+h",
+		description: "Hide or show a pending ask dialog",
+	},
+	"app.approval.approve": {
+		// A chord, not Enter: an Enter typed for the composer as the prompt appears must not approve.
+		// Ctrl+Q backs up Ctrl+Enter, which Windows Terminal cannot deliver (#1903).
+		defaultKeys: ["ctrl+enter", "ctrl+q"],
+		description: "Approve a pending tool call",
+	},
 	"app.editor.external": {
 		defaultKeys: "ctrl+g",
 		description: "Open external editor",
@@ -222,13 +234,13 @@ export const KEYBINDINGS = {
 		defaultKeys: "ctrl+backspace",
 		description: "Delete session (non-invasive)",
 	},
-	"app.tree.foldOrUp": {
-		defaultKeys: ["ctrl+left", "alt+left"],
-		description: "Fold or move up",
+	"app.tree.previousBranch": {
+		defaultKeys: [],
+		description: "Jump to the previous branch in /tree",
 	},
-	"app.tree.unfoldOrDown": {
-		defaultKeys: ["ctrl+right", "alt+right"],
-		description: "Unfold or move down",
+	"app.tree.nextBranch": {
+		defaultKeys: [],
+		description: "Jump to the next branch in /tree",
 	},
 	"app.plan.toggle": {
 		defaultKeys: "alt+shift+p",