@linxiraos/pi-tui 1.2.1 → 1.3.0

package/dist/types/terminal.d.ts

@@ -117,7 +117,7 @@ export type GlyphProtocolReportHandler = (supported: boolean) => void;
 /**
  * Outcome of the Tern Surface Protocol `hello` probe: the terminal's reply,
  * or null when it answered the DA1 sentinel first (no TSP) or the probe was
- * skipped (`PI_TUI_NATIVE=0`, multiplexers).
+ * skipped (`PI_TUI_NATIVE=0`, multiplexers, devenv's reloading shell).
  */
 export type TspHelloHandler = (hello: TspHello | null) => void;
 /**
@@ -181,6 +181,7 @@ export interface Terminal {
     get kittyEnableSequence(): string | null;
     readonly keyboardEnhancementEnterSequence?: string | null;
     readonly keyboardEnhancementExitSequence?: string | null;
+    readonly keyboardEnhancementRestoreSequence?: string | null;
     moveBy(lines: number): void;
     hideCursor(force?: boolean): void;
     showCursor(force?: boolean): void;
@@ -283,9 +284,11 @@ export interface ProcessTerminalOptions {
     conpty?: boolean;
     /**
      * Whether stdin is a native Windows console handle (win32, not WSL), whose
-     * console host answers `CSI ? 9001 h` with win32-input-mode key records.
-     * Defaults to `process.platform === "win32"`; only consulted when `conpty`
-     * is also true.
+     * console host is certain to answer `CSI ? 9001 h` with win32-input-mode key
+     * records. When false (WSL), the keyboard fallback requests modifyOtherKeys
+     * alongside win32-input-mode, since a WSL pty may not be relayed by a console
+     * host. Defaults to `process.platform === "win32"`; only consulted when
+     * `conpty` is also true.
      */
     nativeWindowsConsole?: boolean;
 }
@@ -298,6 +301,7 @@ export declare class ProcessTerminal implements Terminal {
     get kittyProtocolActive(): boolean;
     get kittyEnableSequence(): string | null;
     get keyboardEnhancementEnterSequence(): string | null;
+    get keyboardEnhancementRestoreSequence(): string | null;
     get keyboardEnhancementExitSequence(): string | null;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): void;

package/dist/types/theme/symbols.d.ts

@@ -9,7 +9,7 @@ export type SymbolMap = Record<SymbolKey, string>;
  * resolves through `Theme.cmd` to either a dedicated `cmd.*` symbol or an
  * existing `icon.*` symbol shared with the rest of the UI.
  */
-export type SlashCommandIconName = "action" | "prompt" | "extension" | "settings" | "gear" | "shield" | "wave" | "compass" | "inbox" | "swap" | "expand" | "computer" | "eye" | "todo" | "stats" | "news" | "keyboard" | "export" | "clipboard" | "share" | "broadcast" | "globe" | "copy" | "plus" | "restart" | "eraser" | "trash" | "compress" | "vibrate" | "handoff" | "history" | "question" | "rocket" | "stethoscope" | "redo" | "bug" | "memory" | "pencil" | "folderMove" | "folderPlus" | "folderMinus" | "hammer" | "power" | "cart" | "model" | "plan" | "prewalk" | "goal" | "pause" | "loop" | "session" | "jobs" | "gauge" | "context" | "agents" | "branch" | "tree" | "signIn" | "signOut" | "advisor" | "host" | "package" | "fast" | "voice" | "tools" | "rule" | "skill" | "mcp" | "pin";
+export type SlashCommandIconName = "action" | "prompt" | "extension" | "settings" | "gear" | "shield" | "wave" | "compass" | "inbox" | "swap" | "expand" | "computer" | "eye" | "todo" | "stats" | "news" | "keyboard" | "export" | "clipboard" | "share" | "broadcast" | "globe" | "copy" | "plus" | "restart" | "eraser" | "trash" | "compress" | "vibrate" | "handoff" | "history" | "question" | "rocket" | "stethoscope" | "redo" | "bug" | "memory" | "pencil" | "folderMove" | "folderPlus" | "folderMinus" | "hammer" | "power" | "cart" | "model" | "plan" | "prewalk" | "goal" | "pause" | "loop" | "session" | "jobs" | "gauge" | "context" | "ghost" | "agents" | "branch" | "tree" | "signIn" | "signOut" | "advisor" | "host" | "package" | "fast" | "voice" | "tools" | "rule" | "skill" | "mcp" | "pin";
 export declare const SYMBOL_PRESETS: Record<SymbolPreset, SymbolMap>;
 export type SpinnerType = "status" | "activity";
 export declare const SPINNER_FRAMES: Record<SymbolPreset, Record<SpinnerType, string[]>>;

package/dist/types/theme/theme.d.ts

@@ -7,6 +7,17 @@ export { isValidThemeColor, type ThemeBg, type ThemeColor } from "./schema.js";
 export { getAvailableSymbolPresets, isValidSymbolPreset, type SpinnerType, type SymbolKey, type SymbolPreset, } from "./symbols.js";
 export { Theme } from "./theme-class.js";
 export { createHighlightStream, getEditorTheme, getMarkdownTheme, getMarkdownThemeWithLinkTargets, getSelectListTheme, getSettingsListTheme, getSymbolTheme, highlightCode, setMarkdownMermaidRendering, warmHighlighter, } from "./tui-adapters.js";
+/**
+ * Subscribe to native fallback appearance changes independently of theme changes.
+ * Consumers must re-check the effective background: COLORFGBG can override it.
+ */
+export declare function onTerminalBackgroundFallbackChange(callback: () => void): () => void;
+/**
+ * Detect appearance from trusted OSC 11 reports, then COLORFGBG, then native
+ * macOS appearance only on known-broken multiplexer background-query paths.
+ * Defaults to dark when none of those signals is available.
+ */
+export declare function detectTerminalBackground(): "dark" | "light";
 /** Active theme; imports remain live across initialization, previews, and theme switches. */
 export declare var theme: Theme;
 type ThemeBinding = (value: Theme) => void;

package/dist/types/thinking.d.ts

@@ -37,6 +37,11 @@ export declare function shouldDisableReasoning(level: ThinkingLevel | undefined)
  * Resolves a selector against the current model while preserving explicit "off".
  */
 export declare function resolveThinkingLevelForModel(model: Model | undefined, level: ThinkingLevel | undefined): ResolvedThinkingLevel | undefined;
+/**
+ * Level applied to `model` when the user has not picked one for it (carried,
+ * global default, auto). Unverified thinking stays unset until the user picks.
+ */
+export declare function automaticThinkingLevel<T>(model: Model | undefined, fallback: T): T | undefined;
 /**
  * Sentinel selector for the coding-agent "auto" thinking mode. Kept entirely
  * inside the coding-agent layer: it is never an {@link Effort} or

package/dist/types/tmux.d.ts

@@ -1,6 +1,14 @@
 export { wrapTmuxPassthrough } from "./multiplexers/tmux.js";
 /** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
 export declare function wrapTmuxPassthroughIfNeeded(payload: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Emulator name candidates from a `#{client_termtype}<TAB>#{client_termname}`
+ * line, best first: the terminal-type reply (tmux 3.4+, XTVERSION), then the
+ * emulator the client's `TERM` names when it ships its own terminfo entry. Both
+ * are kept because the reply can name an unrecognized program (a nested tmux
+ * answers `tmux 3.4`) while `TERM` still identifies the emulator.
+ */
+export declare function tmuxClientProgramsFromReport(report: string): string[];
 /**
  * Whether the terminal hosting this tmux session draws TSP programs natively:
  * it sets the session user option `@tern-tsp` while it watches the session.
@@ -12,10 +20,37 @@ export declare function tmuxSessionSpeaksTsp(env?: NodeJS.ProcessEnv): boolean;
  */
 export declare function setTmuxPaneApcTitles(on: boolean, env?: NodeJS.ProcessEnv): void;
 /**
- * Resolve the terminal emulator name recorded for this tmux client.
+ * Resolve the terminal emulator names recorded for this tmux client, best first.
  *
  * tmux overwrites pane identity variables with its own values, but retains the
- * attached client's terminal-type reply in `#{client_termtype}`. The local IPC
- * query runs once per process and degrades to `null` when unavailable.
+ * attached client's terminal-type reply in `#{client_termtype}` and its `TERM`
+ * in `#{client_termname}` (see {@link tmuxClientProgramsFromReport}). The local
+ * IPC query runs once per process and degrades to `[]` when unavailable.
+ */
+export declare function resolveTmuxClientTerminalNames(env?: NodeJS.ProcessEnv): readonly string[];
+/**
+ * Whether tmux draws SIXEL to the client attached to this session: its
+ * effective terminal description for that client carries `Sxl`.
+ *
+ * A tmux built with SIXEL answers every pane's DA1 with attribute 4 and draws a
+ * `SIXEL IMAGE (WxH)` text placeholder for clients without SIXEL, so the pane's
+ * DA1 says nothing about the outer terminal. tmux itself renders SIXEL only
+ * when the client's terminal has `Sxl`, whether from terminfo,
+ * `terminal-overrides`, or the `sixel` feature (DA1 or `terminal-features`),
+ * and `show-messages -T` reports that merged description. The TUI consults
+ * this before trusting the pane's DA1 attribute. Queried once per tmux
+ * session; `false` outside tmux, with no attached client, or when the query
+ * fails. Nested tmux usually reports no `Sxl`: the inner client's terminal is
+ * the outer tmux, whose DA1 starts with level 1, which tmux does not parse
+ * for features.
+ */
+export declare function tmuxClientRendersSixel(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether tmux forwards this pane's `\x1bPtmux;…\x1b\\` passthrough envelopes
+ * to the attached client. tmux 3.3+ defaults `allow-passthrough` to `off` and
+ * then silently drops every wrapped sequence, so Kitty graphics sent through
+ * the envelope never reach a Kitty-capable outer terminal. Resolves the
+ * effective pane value (pane → window → global). Queried once per pane;
+ * `false` outside tmux or when the query fails.
  */
-export declare function resolveTmuxClientTerminalName(env?: NodeJS.ProcessEnv): string | null;
+export declare function tmuxPaneAllowsPassthrough(env?: NodeJS.ProcessEnv): boolean;

package/dist/types/tools/ast-edit.d.ts

@@ -1,7 +1,7 @@
 import type { Component } from "../tui.js";
 import type { Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
-import type { NativeToolView, RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultContextOptions, RenderResultOptions } from "./renderer.js";
 /** Display metadata returned by ast-edit. */
 export interface AstEditToolDetails {
     totalReplacements: number;
@@ -47,7 +47,7 @@ export declare const astEditToolRenderer: {
         }>;
         details?: AstEditToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, uiTheme: Theme, args?: AstEditRenderArgs): Component;
+    }, options: RenderResultContextOptions, uiTheme: Theme, args?: AstEditRenderArgs): Component;
     describeCall(args: AstEditRenderArgs): NativeToolView;
     describeResult(result: {
         content: Array<{

package/dist/types/tools/ast-grep.d.ts

@@ -1,7 +1,7 @@
 import type { Component } from "../tui.js";
 import type { Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
-import type { RenderResultOptions, NativeToolView } from "./renderer.js";
+import type { NativeToolView, RenderResultContextOptions, RenderResultOptions } from "./renderer.js";
 /** Display metadata returned by ast-grep. */
 export interface AstGrepToolDetails {
     matchCount: number;
@@ -46,7 +46,7 @@ export declare const astGrepToolRenderer: {
         }>;
         details?: AstGrepToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, uiTheme: Theme, args?: AstGrepRenderArgs): Component;
+    }, options: RenderResultContextOptions, uiTheme: Theme, args?: AstGrepRenderArgs): Component;
     describeCall(args: AstGrepRenderArgs): NativeToolView;
     describeResult(result: {
         content: Array<{

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

@@ -18,6 +18,8 @@ export interface BashToolDetails {
     requestedTimeoutSeconds?: number;
     timeoutDisabled?: boolean;
     wallTimeMs?: number;
+    /** False when no wall-time footer was emitted; absent on older results. */
+    wallTimeNoticeEmitted?: boolean;
     /** Exit code of a command that ran to completion but failed (non-zero). */
     exitCode?: number;
     /** True when the command was killed by its timeout deadline (not a failure). */
@@ -31,12 +33,15 @@ export interface BashToolDetails {
         timedOut: boolean;
         pid?: number;
     };
+    /** Background job behind the call; `cancelled`: killed (`proc://<id>/kill`) before it finished. */
     async?: {
-        state: "running" | "completed" | "failed";
+        state: "running" | "completed" | "failed" | "cancelled";
         jobId: string;
         type: "bash";
     };
 }
+/** Minimum duration for a model-facing wall-time notice; shorter runs keep timing only in details. */
+export declare const WALL_TIME_NOTICE_MIN_MS = 1000;
 /** Formats the model-facing command duration notice. */
 export declare function formatWallTimeNotice(wallTimeMs: number): string;
 /** Formats the model-facing command exit status notice. */

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

@@ -133,6 +133,8 @@ export interface EditRenderContext {
     renderDiff?: (diffText: string, options?: {
         filePath?: string;
     }) => string;
+    /** Unsanitized result metadata, used only for filesystem link targets. */
+    rawDetails?: unknown;
 }
 /** Render replacement text until a computed diff preview is available. */
 export declare function renderStreamingFallback(editMode: EditMode, args: unknown, theme: Theme): string;

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

@@ -13,25 +13,60 @@ export interface EvalStatusEvent {
     resolvedThinkingLevel?: ConfiguredThinkingLevel;
     [key: string]: unknown;
 }
+/** One column of a table view. */
+export interface EvalTableColumn {
+    head: string;
+    /** Numeric values: renderers right-align the column. */
+    numeric?: boolean;
+}
+/**
+ * A pretty rendering of something a cell printed, shown to the user in place
+ * of its text; the model only ever sees the text.
+ * - `table`: a data frame or `console.table`; leading index columns are plain
+ *   columns, and a truncated frame's elided rows/columns are `…` cells.
+ * - `json`: a structured value (dict/list, object/array) as a collapsible tree.
+ * - `markdown`: an object's Markdown representation.
+ */
+export type EvalView = {
+    kind: "table";
+    columns: EvalTableColumn[];
+    rows: string[][];
+} | {
+    kind: "json";
+    value: unknown;
+} | {
+    kind: "markdown";
+    text: string;
+};
+/**
+ * A view and the exact printed text it stands for. Renderers locate `text` in
+ * the cell's `output` (entries in print order) and show the view there; an
+ * entry whose text is no longer in the output (truncated) is skipped.
+ */
+export interface EvalViewEntry {
+    text: string;
+    view: EvalView;
+}
 /** Per-cell execution result for transcript rendering. */
 export interface EvalCellResult {
     index: number;
     title?: string;
     code: string;
     language?: EvalLanguage;
+    /** What the model saw: the cell's printed text plus image notes. */
     output: string;
+    /** Pretty views of spans of `output`, in print order. */
+    views?: EvalViewEntry[];
     status: "pending" | "running" | "complete" | "error";
     durationMs?: number;
     exitCode?: number;
     statusEvents?: EvalStatusEvent[];
     /** Discrete events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
     statusEventsElided?: number;
-    hasMarkdown?: boolean;
 }
 /** Tool result detail object surfaced to the UI/transcript. */
 export interface EvalToolDetails {
     cells?: EvalCellResult[];
-    jsonOutputs?: unknown[];
     images?: ImageContent[];
     statusEvents?: EvalStatusEvent[];
     /** Discrete events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
@@ -44,9 +79,9 @@ export interface EvalToolDetails {
     languages?: EvalLanguage[];
     /** Optional human-readable notice (e.g. fallback explanation). */
     notice?: string;
-    /** Present when the cell was auto-backgrounded as an async job. */
+    /** Present when the cell was auto-backgrounded as an async job; `cancelled`: killed before it finished. */
     async?: {
-        state: "running" | "completed" | "failed";
+        state: "running" | "completed" | "failed" | "cancelled";
         jobId: string;
         type: "eval";
     };
@@ -100,6 +135,20 @@ export declare function upsertStatusEvent(events: EvalStatusEvent[], event: Eval
  * events behind an "… N earlier" row.
  */
 export declare function recordStatusEvent(log: StatusEventLog, event: EvalStatusEvent): void;
+/** One ordered piece of a cell's output: printed text, or a view shown in place of the text it matched. */
+export type EvalOutputPart = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "view";
+    view: EvalView;
+};
+/**
+ * Split `output` around its views, in order: each view's `text` is searched
+ * from the end of the previous match, unmatched entries are skipped, and
+ * blank text between views is dropped (newlines bordering a view trimmed).
+ */
+export declare function splitEvalOutput(output: string, views: readonly EvalViewEntry[] | undefined): EvalOutputPart[];
 /** Render eval code cells, structured display output, and progress events. */
 export declare const evalToolRenderer: {
     animatedPendingPreview: true;

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

@@ -1,7 +1,7 @@
 import type { Theme } from "../theme/theme.js";
 import type { Component } from "../tui.js";
 import type { OutputMeta } from "./output-meta.js";
-import type { NativeToolView, RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultContextOptions, RenderResultOptions } from "./renderer.js";
 /** A verified line range with its yes-probability and a one-line preview. */
 export interface FindRange {
     start: number;
@@ -22,12 +22,21 @@ export interface FindHit {
     linesSeen: number;
     truncated: boolean;
 }
+/**
+ * How much of a search the judge actually covered. `unavailable`: every judge
+ * request failed, so an empty result is not evidence of absence. `partial`:
+ * some requests failed. `complete`: none failed (or none were needed).
+ */
+export type FindCoverage = "complete" | "partial" | "unavailable";
 /** Search accounting reported alongside the hits. */
 export interface FindStats {
     /** Eligible files under the root. */
     listed: number;
     requests: number;
-    errors: number;
+    /** Judge requests that failed outright; decides {@link FindCoverage}. */
+    failed: number;
+    /** Questions a successful response left without a usable answer. */
+    unanswered: number;
     /** Entries judged by name. */
     judged: number;
     /** Files whose content was read and sent. */
@@ -51,6 +60,7 @@ export interface FindToolDetails {
     /** Verified-passage probability at or above which a file is a hit. */
     threshold: number;
     hits: FindHit[];
+    coverage: FindCoverage;
     stats: FindStats;
     elapsedMs: number;
     /** Session cwd; hit paths are relative to it. */
@@ -74,7 +84,7 @@ export declare const findToolRenderer: {
         }>;
         details?: FindToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, uiTheme: Theme, args?: FindRenderArgs): Component;
+    }, options: RenderResultContextOptions, uiTheme: Theme, args?: FindRenderArgs): Component;
     describeCall(args: FindRenderArgs): NativeToolView;
     /**
      * Inline (§7.3 find): `Find “query”  2 hits · 8 files`, then per hit its
@@ -88,7 +98,7 @@ export declare const findToolRenderer: {
         }>;
         details?: FindToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, args?: FindRenderArgs): NativeToolView;
+    }, options: RenderResultContextOptions, args?: FindRenderArgs): NativeToolView;
     mergeCallAndResult: true;
     animatedPendingPreview: true;
     animatedPartialResult: true;

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

@@ -1,5 +1,5 @@
 import type { Component } from "../tui.js";
-import type { NativeToolView, RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultContextOptions, RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
 import type { TruncationResult } from "./streaming-output.js";
@@ -42,7 +42,7 @@ export declare const globToolRenderer: {
         }>;
         details?: GlobToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, uiTheme: Theme, args?: GlobRenderArgs): Component;
+    }, options: RenderResultContextOptions, uiTheme: Theme, args?: GlobRenderArgs): Component;
     describeCall(args: GlobRenderArgs): NativeToolView;
     /**
      * Inline (§7.3 glob): `Glob “pattern”  5 files`, then the files as rows
@@ -55,7 +55,7 @@ export declare const globToolRenderer: {
         }>;
         details?: GlobToolDetails;
         isError?: boolean;
-    }, _options: RenderResultOptions, args?: GlobRenderArgs): NativeToolView;
+    }, options: RenderResultContextOptions, args?: GlobRenderArgs): NativeToolView;
     mergeCallAndResult: true;
 };
 export {};

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

@@ -1,5 +1,5 @@
 import type { Component } from "../tui.js";
-import type { NativeToolView, RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultContextOptions, RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
 import type { TruncationResult } from "./streaming-output.js";
@@ -58,7 +58,7 @@ export declare const grepToolRenderer: {
         }>;
         details?: GrepToolDetails;
         isError?: boolean;
-    }, options: RenderResultOptions, uiTheme: Theme, args?: GrepRenderArgs): Component;
+    }, options: RenderResultContextOptions, uiTheme: Theme, args?: GrepRenderArgs): Component;
     describeCall(args: GrepRenderArgs): NativeToolView;
     /**
      * Inline (§7.3 grep): `Grep “pattern”  5 matches · 2 files  in src`, then

package/dist/types/tools/grouped-file-output.d.ts

@@ -110,10 +110,13 @@ export interface NumberedLine {
  * Numbered `code` for possibly non-contiguous source lines: one block per run
  * of consecutive line numbers (`start` = the run's first line, match lines
  * `mark`ed), with a `…` row wherever the numbers jump or an elision marker
- * (`n: null`) sits. No path header: the row or head above names the file.
+ * (`n: null`) sits. `path` is the file the lines come from: Tern picks their
+ * grammar from it and draws no header (the row or head above names the file).
+ * `wrap` soft-wraps long lines instead of scrolling the block sideways.
  */
 export declare function numberedCode(lines: readonly NumberedLine[], opts?: {
-    lang?: string;
+    path?: string;
+    wrap?: boolean;
 }): NativeNode[];
 /**
  * Describe grouped search output (grep / ast-grep / ast-edit display content)
@@ -121,9 +124,11 @@ export declare function numberedCode(lines: readonly NumberedLine[], opts?: {
  * header's suffix or the match count as a chip), then its lines as
  * {@link numberedCode} with match lines marked and `…` between non-adjacent
  * runs. Unnumbered body lines stay plain `code`. `maxFiles` keeps only the
- * first files (the caller says how many were left out).
+ * first files (the caller says how many were left out). `file` owns the lines
+ * before any header: a single-file search prints none, yet its lines get the
+ * same file row as a directory search's.
  */
 export declare function describeGroupedOutput(lines: readonly string[], options?: {
-    lang?: (path: string) => string | undefined;
     maxFiles?: number;
+    file?: string;
 }): NativeNode[];

package/dist/types/tools/native-view.d.ts

@@ -85,7 +85,7 @@ export interface RunFootInput {
     readonly state: RunState;
     /** Exit code of a `failed` run; a non-zero code names the state `exit N`. */
     readonly exitCode?: number;
-    /** Milliseconds run so far (`running`) or in total; the time is omitted when undefined. */
+    /** Milliseconds run so far (`running`, a live `background` job) or in total; omitted when undefined. */
     readonly elapsedMs?: number;
     /** Quiet facts (job id, service state, artifact), muted and ` · `-joined. */
     readonly facts?: readonly string[];

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/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: {