@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/dist/types/thinking.d.ts

@@ -0,0 +1,165 @@
+import type { ResolvedThinkingLevel } from "@oh-my-pi/pi-agent-core/thinking";
+import type { ConfiguredThinkingLevel } from "./render/render-utils.js";
+import { ThinkingLevel } from "@oh-my-pi/pi-agent-core/thinking";
+import { Effort } from "@oh-my-pi/pi-catalog/effort";
+import type { Model } from "@oh-my-pi/pi-catalog/types";
+/** Thinking selectors accepted by CLI inputs, in display order. */
+export declare const CLI_THINKING_LEVELS: readonly string[];
+/**
+ * Metadata used to render thinking selector values in the coding-agent UI.
+ */
+export interface ThinkingLevelMetadata {
+    value: ThinkingLevel;
+    label: string;
+    description: string;
+}
+/**
+ * Parses a provider-facing effort value. Accepts unambiguous abbreviations.
+ */
+export declare function parseEffort(value: string | null | undefined): Effort | undefined;
+/**
+ * Parses an agent-local thinking selector. Accepts unambiguous abbreviations.
+ */
+export declare function parseThinkingLevel(value: string | null | undefined): ThinkingLevel | undefined;
+/**
+ * Returns display metadata for a thinking selector.
+ */
+export declare function getThinkingLevelMetadata(level: ThinkingLevel): ThinkingLevelMetadata;
+/**
+ * Converts an agent-local selector into the effort sent to providers.
+ */
+export declare function toReasoningEffort(level: ThinkingLevel | undefined): Effort | undefined;
+/**
+ * True when a selector explicitly requests provider-side reasoning disablement.
+ */
+export declare function shouldDisableReasoning(level: ThinkingLevel | undefined): boolean;
+/**
+ * Resolves a selector against the current model while preserving explicit "off".
+ */
+export declare function resolveThinkingLevelForModel(model: Model | undefined, level: ThinkingLevel | undefined): ResolvedThinkingLevel | undefined;
+/**
+ * Sentinel selector for the coding-agent "auto" thinking mode. Kept entirely
+ * inside the coding-agent layer: it is never an {@link Effort} or
+ * {@link ThinkingLevel}, so provider mapping/clamping keeps seeing concrete
+ * efforts. The session resolves `auto` to a concrete effort each turn.
+ */
+export declare const AUTO_THINKING: "auto";
+/** A thinking selector as configured by the user — a concrete level or `auto`. */
+export type { ConfiguredThinkingLevel } from "./render/render-utils.js";
+/** Maps the session-level `auto` sentinel to `undefined`; concrete levels pass through. */
+export declare function concreteThinkingLevel(level: ConfiguredThinkingLevel | undefined): ThinkingLevel | undefined;
+/**
+ * True when a prewalk hand-off from `current`/`currentLevel` to
+ * `target`/`targetLevel` would change nothing observable: same model id, same
+ * auto/fixed mode, and the same model-clamped effective effort. Prewalk arms and
+ * switches only when this is false.
+ *
+ * An effort-only delta on the same model id is a legitimate cheapening hand-off
+ * — on a reasoning model the effort is the bulk of the cost — so it is NOT a
+ * no-op and must still switch. A `targetLevel` of `undefined` means the prewalk
+ * pattern carried no explicit `:level` suffix (no effort change requested),
+ * which on the same model is a no-op.
+ *
+ * `auto` mode is compared before efforts: `auto` and a fixed selector that both
+ * resolve to `undefined` effort (e.g. `:inherit`) are NOT interchangeable —
+ * applying the fixed selector clears per-turn classification, so switching
+ * auto↔fixed is always a real change even when the clamped efforts match.
+ *
+ * Efforts are otherwise compared AFTER model clamping, so a target the model
+ * cannot honor (e.g. `:xhigh` on a model capped at `high`) — which
+ * `setThinkingLevel` would clamp straight back to the active effort — is
+ * recognized as a no-op instead of triggering an ephemeral reset and the
+ * plan/checklist nudges for nothing.
+ */
+export declare function prewalkWouldBeNoop(current: Model | undefined, currentLevel: ConfiguredThinkingLevel | undefined, target: Model, targetLevel: ConfiguredThinkingLevel | undefined): boolean;
+/** Metadata used to render the `auto` selector value alongside concrete levels. */
+export interface ConfiguredThinkingLevelMetadata {
+    value: ConfiguredThinkingLevel;
+    label: string;
+    description: string;
+}
+/**
+ * Parses a configured thinking selector, accepting `auto` in addition to every
+ * value {@link parseThinkingLevel} accepts. {@link parseThinkingLevel} itself
+ * stays strict so model-suffix parsing (`model:high`) keeps rejecting `auto`.
+ */
+export declare function parseConfiguredThinkingLevel(value: string | null | undefined): ConfiguredThinkingLevel | undefined;
+/** Returns display metadata for a configured selector, including `auto`. */
+export declare function getConfiguredThinkingLevelMetadata(level: ConfiguredThinkingLevel): ConfiguredThinkingLevelMetadata;
+/**
+ * Parses a `--thinking` CLI value. Accepts every {@link parseConfiguredThinkingLevel}
+ * selector (`off`, `auto`, `minimal`..`max`) but rejects
+ * `inherit`: an explicit `inherit` on the command line would suppress the
+ * settings/scoped-model fallback during startup resolution only to resolve back
+ * to the provider default, which is never what the user means.
+ */
+export declare function parseCliThinkingLevel(value: string | null | undefined): ConfiguredThinkingLevel | undefined;
+/**
+ * Resolves an auto-classified effort against the active model's supported
+ * range. Unlike {@link clampThinkingLevelForModel}, `auto` never resolves below
+ * {@link Effort.Low}: the eligible pool is the model's supported efforts at or
+ * above Low (falling back to the full supported set only when the model maxes
+ * out below Low). Within that pool the request snaps to the highest level not
+ * exceeding it, or the pool minimum when the request is below the pool.
+ * `ceiling` bounds the pool from above, so a policy ceiling survives the model
+ * clamp: a sparse ladder such as `["max"]` must not snap an `xhigh` request up
+ * to `max`. The Low floor is resolved against the model's own ladder *before*
+ * the ceiling applies — a ceiling that hides every tier at or above Low means
+ * there is nothing legal to pick (`undefined`), not a licence to fall through
+ * to a sub-Low tier the model happens to expose.
+ *
+ * Returns `undefined` for reasoning-capable models without a controllable
+ * effort surface (`thinking.efforts` empty — e.g. devin-agent models, where
+ * Cascade selects effort by routing to sibling model ids). Matches
+ * {@link clampThinkingLevelForModel}: with no effort to pick, `auto` must not
+ * forward a concrete effort that would then trip {@link requireSupportedEffort}
+ * downstream.
+ */
+export declare function clampAutoThinkingEffort(model: Model | undefined, effort: Effort, ceiling?: Effort): Effort | undefined;
+/** Coarse per-spawn effort selectors accepted by the task tool. */
+export declare const TASK_EFFORTS: readonly ["lo", "med", "hi"];
+/** Coarse task-spawn effort: the lowest, middle, or highest thinking level the target model supports. */
+export type TaskEffort = (typeof TASK_EFFORTS)[number];
+/**
+ * Maps a coarse task effort onto the model's supported thinking range:
+ * `lo` = lowest supported level, `hi` = highest (whatever the model tops out
+ * at — high, xhigh, or max), `med` = the middle (lower of the two middles for
+ * an even-sized range). Without a model, maps over the full canonical range.
+ * Returns `undefined` when the model has no controllable effort surface, so
+ * callers fall back to their default selector (e.g. `auto`). Throws when the
+ * configured ceiling is below the model's lowest supported effort.
+ */
+export declare function resolveTaskEffortLevel(model: Model | undefined, effort: TaskEffort, maxEffort?: Effort): Effort | undefined;
+/**
+ * Clamps a concrete thinking selector to a per-session effort ceiling (e.g. a
+ * task spawn's `task.maxEffort`-capped effort hint). `off`/`inherit`/
+ * `undefined` pass through, as do levels already at or below the ceiling.
+ * Levels above it snap to the highest model-supported effort at or below the
+ * ceiling. A model whose floor exceeds the ceiling has nothing valid to snap
+ * to; the requested level is returned unchanged and the caller is responsible
+ * for rejecting or skipping such models (see {@link modelSupportsEffortCeiling}).
+ */
+export declare function clampThinkingLevelToCeiling(model: Model | undefined, level: Effort | undefined, ceiling: Effort | undefined): Effort | undefined;
+export declare function clampThinkingLevelToCeiling(model: Model | undefined, level: ThinkingLevel | undefined, ceiling: Effort | undefined): ThinkingLevel | undefined;
+/**
+ * True when `model` can honor a thinking-effort ceiling: it either has no
+ * controllable effort surface (nothing to cap) or supports at least one effort
+ * at or below the ceiling. Retry-fallback candidate filtering uses this to
+ * skip models whose floor would force the session above the ceiling.
+ */
+export declare function modelSupportsEffortCeiling(model: Model, ceiling: Effort): boolean;
+/**
+ * The provisional concrete level shown while `auto` is configured but before a
+ * turn has been classified, and the fallback when classification fails. Prefers
+ * the model's `defaultLevel`, otherwise High, clamped into the auto range.
+ *
+ * Deliberately stays below {@link Effort.Max}: the placeholder must not bill the
+ * top tier for a turn nobody classified, so XHigh is passed as a hard ceiling
+ * rather than only capping the preferred level — otherwise a sparse `["max"]`
+ * ladder would snap straight back up. A model whose ladder offers nothing at or
+ * below XHigh therefore has no provisional level, and `auto` leaves the current
+ * one in place. Classification itself may still resolve Max on models that
+ * expose the tier when the user opts in. Returns `undefined` for non-reasoning
+ * models.
+ */
+export declare function resolveProvisionalAutoLevel(model: Model | undefined): Effort | undefined;

package/dist/types/tools/agent-tree.d.ts

@@ -0,0 +1,36 @@
+import { type ConfiguredThinkingLevel } from "../render/render-utils.js";
+import type { Theme } from "../theme/theme.js";
+/** Counters displayed alongside an agent name. */
+export interface AgentStats {
+    toolCount?: number;
+    requests?: number;
+    contextTokens?: number;
+    contextWindow?: number;
+    cost?: number;
+}
+/** Format the shared tool-count, request, context, and cost stat run. */
+export declare function formatAgentStatRun(stats: AgentStats, theme: Theme): string;
+/** Tool-specific presentation layered onto a bounded agent progress row. */
+export interface AgentTreeRowOptions {
+    status: "pending" | "running" | "completed" | "failed" | "aborted";
+    presentation: "task" | "eval";
+    prefix: string;
+    id: string;
+    width: number;
+    model?: string;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    advisor?: boolean;
+    spinnerFrame?: number;
+    frozen?: boolean;
+    roleBadge?: string;
+    statusBadge?: string;
+    description?: string;
+    preview?: string;
+    stats?: AgentStats;
+    durationMs?: number;
+}
+/** Render an agent row while reserving its identifier and required status badges. */
+export declare function renderAgentTreeRow(options: AgentTreeRowOptions, theme: Theme): {
+    line: string;
+    descriptionShown: boolean;
+};

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

@@ -0,0 +1,67 @@
+import { type Component } from "../index.js";
+import type { RenderResultOptions } from "./renderer.js";
+import { type Theme } from "../theme/theme.js";
+/** Result for a single question */
+export interface QuestionResult {
+    id: string;
+    question: string;
+    options: string[];
+    multi: boolean;
+    selectedOptions: string[];
+    customInput?: string;
+    /** Optional note attached to the selected answer in the rich ask dialog. */
+    note?: string;
+    /** True when the answer was auto-selected because the dialog timed out. */
+    timedOut?: boolean;
+}
+/** Answers and redirect metadata displayed for an ask tool result. */
+export interface AskToolDetails {
+    question?: string;
+    options?: string[];
+    multi?: boolean;
+    selectedOptions?: string[];
+    customInput?: string;
+    /** Optional note attached to the selected answer in the rich ask dialog. */
+    note?: string;
+    /** True when the answer was auto-selected because the dialog timed out. */
+    timedOut?: boolean;
+    /** Multi-part question mode */
+    results?: QuestionResult[];
+    /** Chat redirect: the user chose "Chat about this" instead of answering. */
+    chatRedirect?: boolean;
+    /** Questions surfaced when chatRedirect is true. */
+    questions?: string[];
+}
+interface AskRenderOption {
+    label: string;
+    description?: string;
+}
+interface AskRenderArgs {
+    question?: string;
+    options?: AskRenderOption[];
+    multi?: boolean;
+    questions?: Array<{
+        id: string;
+        question: string;
+        options: AskRenderOption[];
+        multi?: boolean;
+    }>;
+}
+/**
+ * Marker glyph for a question option. Single-choice questions render circular radio
+ * buttons (pick one); multi-select questions render rectangular checkboxes (pick many).
+ */
+export declare function optionMarker(uiTheme: Theme, multi: boolean | undefined, selected: boolean): string;
+/** Render question forms and their recorded answers. */
+export declare const askToolRenderer: {
+    mergeCallAndResult: true;
+    renderCall(args: AskRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: AskToolDetails;
+    }, _options: RenderResultOptions, uiTheme: Theme): Component;
+};
+export {};

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

@@ -0,0 +1,53 @@
+import type { Component } from "../tui.js";
+import type { Theme } from "../theme/theme.js";
+import type { OutputMeta } from "./output-meta.js";
+import type { RenderResultOptions } from "./renderer.js";
+/** Display metadata returned by ast-edit. */
+export interface AstEditToolDetails {
+    totalReplacements: number;
+    filesTouched: number;
+    filesSearched: number;
+    applied: boolean;
+    limitReached: boolean;
+    parseErrors?: string[];
+    /** Total parse error count before {@link PARSE_ERRORS_LIMIT} capping. Omitted when no errors. */
+    parseErrorsTotal?: number;
+    scopePath?: string;
+    files?: string[];
+    fileReplacements?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter (no model-only hashline anchors). The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+    /** Absolute base directory used during the edit. Used by the renderer to resolve
+     * display-relative paths to absolute paths for OSC 8 hyperlinks. */
+    searchPath?: string;
+    /** Session cwd at edit time. Display header paths are cwd-relative, so the
+     * renderer resolves them against this; `searchPath` is the scope target. */
+    cwd?: string;
+}
+interface AstEditRenderArgs {
+    ops?: Array<{
+        pat?: string;
+        out?: string;
+    }>;
+    paths?: string[];
+}
+/** Render AST edit calls and results. */
+export declare const astEditToolRenderer: {
+    inline: true;
+    renderCall(args: AstEditRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: AstEditToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: AstEditRenderArgs): Component;
+    mergeCallAndResult: true;
+};
+export {};

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

@@ -0,0 +1,52 @@
+import type { Component } from "../tui.js";
+import type { Theme } from "../theme/theme.js";
+import type { OutputMeta } from "./output-meta.js";
+import type { RenderResultOptions } from "./renderer.js";
+/** Display metadata returned by ast-grep. */
+export interface AstGrepToolDetails {
+    matchCount: number;
+    fileCount: number;
+    filesSearched: number;
+    limitReached: boolean;
+    parseErrors?: string[];
+    /** Total parse error count before {@link PARSE_ERRORS_LIMIT} capping. Omitted when no errors. */
+    parseErrorsTotal?: number;
+    scopePath?: string;
+    files?: string[];
+    fileMatches?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter and `*` to mark match lines. The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+    /** Absolute base directory used during search. Used by the renderer to resolve
+     * display-relative paths to absolute paths for OSC 8 hyperlinks. */
+    searchPath?: string;
+    /** Session cwd at search time. Display header/match paths are cwd-relative, so
+     * the renderer resolves them against this; `searchPath` is the scope target. */
+    cwd?: string;
+}
+interface AstGrepRenderArgs {
+    pat?: string;
+    path?: string | string[];
+    /** Legacy pre-`path` argument name; kept so historical transcripts still render a scope. */
+    paths?: string[];
+    skip?: number;
+}
+/** Render AST grep calls and results. */
+export declare const astGrepToolRenderer: {
+    inline: true;
+    renderCall(args: AstGrepRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: AstGrepToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: AstGrepRenderArgs): Component;
+    mergeCallAndResult: true;
+};
+export {};

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

@@ -0,0 +1,156 @@
+import { Text } from "../components/text.js";
+import type { Theme } from "../theme/theme.js";
+import type { TruncationResult } from "./streaming-output.js";
+/** Whether a lower or higher metric is better. */
+export type MetricDirection = "lower" | "higher";
+/** Disposition of a completed experiment. */
+export type ExperimentStatus = "keep" | "discard" | "crash" | "checks_failed";
+/** JSON-compatible additional structured experiment information. */
+export type ASIValue = string | number | boolean | null | ASIValue[] | {
+    [key: string]: ASIValue;
+};
+/** Named structured experiment observations. */
+export interface ASIData {
+    [key: string]: ASIValue;
+}
+/** Numeric metrics indexed by name. */
+export interface NumericMetricMap {
+    [key: string]: number;
+}
+/** Name and unit of an experiment metric. */
+export interface MetricDef {
+    name: string;
+    unit: string;
+}
+/** Recorded metric and disposition of an experiment run. */
+export interface ExperimentResult {
+    runNumber: number | null;
+    commit: string;
+    metric: number;
+    metrics: NumericMetricMap;
+    status: ExperimentStatus;
+    description: string;
+    timestamp: number;
+    segment: number;
+    confidence: number | null;
+    asi?: ASIData;
+    modifiedPaths: string[];
+    scopeDeviations: string[];
+    justification: string | null;
+    flagged: boolean;
+    flaggedReason: string | null;
+}
+/** Current experiment baseline, history, and scope. */
+export interface ExperimentState {
+    results: ExperimentResult[];
+    bestMetric: number | null;
+    bestDirection: MetricDirection;
+    metricName: string;
+    metricUnit: string;
+    secondaryMetrics: MetricDef[];
+    name: string | null;
+    goal: string | null;
+    currentSegment: number;
+    maxExperiments: number | null;
+    confidence: number | null;
+    scopePaths: string[];
+    offLimits: string[];
+    constraints: string[];
+    notes: string;
+    branch: string | null;
+    baselineCommit: string | null;
+    sessionId: number | null;
+}
+/** Live elapsed time and output metadata of a benchmark. */
+export interface RunExperimentProgressDetails {
+    phase: "running";
+    elapsed: string;
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+    runDirectory?: string;
+}
+/** Completed benchmark measurements, status, and output. */
+export interface RunDetails {
+    runNumber: number;
+    runDirectory: string;
+    benchmarkLogPath: string;
+    command: string;
+    exitCode: number | null;
+    durationSeconds: number;
+    passed: boolean;
+    crashed: boolean;
+    timedOut: boolean;
+    tailOutput: string;
+    parsedMetrics: NumericMetricMap | null;
+    parsedPrimary: number | null;
+    parsedAsi: ASIData | null;
+    metricName: string;
+    metricUnit: string;
+    preRunDirtyPaths: string[];
+    abandonedPriorRun: number | null;
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+}
+/** Logged experiment result and updated baseline state. */
+export interface LogDetails {
+    experiment: ExperimentResult;
+    state: ExperimentState;
+    wallClockSeconds: number | null;
+    scopeDeviations: string[];
+    justification: string | null;
+    flaggedRuns: Array<{
+        runId: number;
+        reason: string;
+    }>;
+}
+/** Format an integer with comma-separated digit groups. */
+export declare function commas(value: number): string;
+/** Format a number with grouped digits and optional decimals. */
+export declare function fmtNum(value: number, decimals?: number): string;
+/** Format an optional metric value with its unit. */
+export declare function formatNum(value: number | null, unit: string): string;
+/** Filename of the benchmark harness. */
+export declare const HARNESS_FILENAME = "autoresearch.sh";
+/** Default command that executes the benchmark harness. */
+export declare const DEFAULT_HARNESS_COMMAND = "bash autoresearch.sh";
+/** Initialization outcome and experiment state. */
+export interface InitExperimentDetails {
+    state: ExperimentState;
+    createdSession: boolean;
+    bumpedSegment: boolean;
+    abandonedRuns: number;
+    harnessCommitted: boolean;
+    baselineCommit: string | null;
+}
+/** Render init-experiment tool calls and results. */
+export declare const initExperimentToolRenderer: {
+    renderCall(args: {
+        name: string;
+    }, _options: import("./renderer.js").RenderResultOptions, theme: Theme): Text;
+    renderResult(result: import("./renderer.js").ToolRenderResult<InitExperimentDetails>): Text;
+};
+/** Render log-experiment tool calls and results. */
+export declare const logExperimentToolRenderer: {
+    renderCall(args: {
+        status: ExperimentStatus;
+        description: string;
+    }, _options: import("./renderer.js").RenderResultOptions, theme: Theme): Text;
+    renderResult(result: import("./renderer.js").ToolRenderResult<LogDetails>, _options: import("./renderer.js").RenderResultContextOptions, theme: Theme): Text;
+};
+/** Render run-experiment tool calls and results. */
+export declare const runExperimentToolRenderer: {
+    renderCall(_args: unknown, _options: import("./renderer.js").RenderResultOptions, theme: Theme): Text;
+    renderResult(result: import("./renderer.js").ToolRenderResult<RunDetails | RunExperimentProgressDetails>, options: import("./renderer.js").RenderResultContextOptions, theme: Theme): Text;
+};
+/** Persisted experiment notes after an update. */
+export interface UpdateNotesDetails {
+    notes: string;
+}
+/** Render update-notes tool calls and results. */
+export declare const updateNotesToolRenderer: {
+    renderCall(args: {
+        body: string;
+        append_idea?: string;
+    }, _options: import("./renderer.js").RenderResultOptions, theme: Theme): Text;
+    renderResult(result: import("./renderer.js").ToolRenderResult<UpdateNotesDetails>, _options: import("./renderer.js").RenderResultContextOptions, theme: Theme): Text;
+};

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

@@ -0,0 +1,28 @@
+import type * as XtermModule from "@oh-my-pi/pi-utils/vterm";
+import type { Component } from "../tui.js";
+import type { Theme } from "../theme/theme.js";
+/** Resize-only backend exposed by an interactive PTY controller. */
+export interface BashInteractiveTerminalBackend {
+    resize(columns: number, rows: number): void;
+}
+/** Interactive terminal overlay driven by an external PTY controller. */
+export declare class BashInteractiveOverlayComponent implements Component {
+    #private;
+    constructor(command: string, uiTheme: Theme, getTerminalRows: () => number, terminalCtor: typeof XtermModule.Terminal, backend: BashInteractiveTerminalBackend);
+    /** Connects normalized keyboard input and overlay lifecycle events to the controller. */
+    setHandlers(onInput: (data: string) => void, onDismiss: () => void, onDispose: () => void): void;
+    /** Queues a raw terminal output chunk for virtual-terminal rendering. */
+    appendOutput(chunk: string): void;
+    /** Resolves when the virtual terminal has processed all queued output. */
+    flushOutput(): Promise<void>;
+    /** Records process completion and stops forwarding keyboard input. */
+    setComplete(result: {
+        exitCode: number | undefined;
+        cancelled: boolean;
+        timedOut: boolean;
+    }): void;
+    handleInput(data: string): void;
+    render(width: number): readonly string[];
+    invalidate(): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,103 @@
+import type { Component } from "../tui.js";
+import { type Theme } from "../theme/theme.js";
+import { type OutputMeta } from "./output-meta.js";
+import type { RenderResultOptions } from "./renderer.js";
+/** Default collapsed shell output preview height. */
+export declare const BASH_DEFAULT_PREVIEW_LINES = 10;
+/** LLM-facing footer appended when a tool call becomes a background job. */
+export declare function formatBackgroundNotice(jobId: string): string;
+/** Shell execution metadata used by transcript rendering. */
+export interface BashToolDetails {
+    meta?: OutputMeta;
+    timeoutSeconds?: number;
+    requestedTimeoutSeconds?: number;
+    timeoutDisabled?: boolean;
+    wallTimeMs?: number;
+    /** 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). */
+    timedOut?: boolean;
+    /** Live ACP update only; completed results refer to released terminals. */
+    terminalId?: string;
+    async?: {
+        state: "running" | "completed" | "failed";
+        jobId: string;
+        type: "bash";
+    };
+}
+/** Formats the model-facing command duration notice. */
+export declare function formatWallTimeNotice(wallTimeMs: number): string;
+/** Formats the model-facing command exit status notice. */
+export declare function formatExitCodeNotice(exitCode: number): string;
+/** Shell arguments used to build a command preview. */
+export interface BashRenderArgs {
+    command?: string;
+    env?: Record<string, unknown>;
+    timeout?: number;
+    cwd?: string;
+    __partialJson?: string;
+    [key: string]: unknown;
+}
+/** Mutable transcript viewport state for shell output. */
+export interface BashRenderContext {
+    /** Raw output text */
+    output?: string;
+    /** Whether output came from artifact storage */
+    isFullOutput?: boolean;
+    /** Whether output is expanded */
+    expanded?: boolean;
+    /** Number of preview lines when collapsed */
+    previewLines?: number;
+    /** Timeout in seconds */
+    timeout?: number;
+}
+/** Caller-supplied shell labels and argument projections. */
+export interface ShellRendererConfig<TArgs> {
+    resolveTitle: (args: TArgs | undefined, options: RenderResultOptions) => string;
+    resolveCommand?: (args: TArgs | undefined) => string | undefined;
+    resolveCwd?: (args: TArgs | undefined) => string | undefined;
+    resolveEnv?: (args: TArgs | undefined) => Record<string, unknown> | undefined;
+    showHeader?: boolean;
+}
+/** Combines parsed and partially streamed environment assignments. */
+export declare function getBashEnvForDisplay(args: BashRenderArgs): Record<string, unknown> | undefined;
+/**
+ * Returns the bash command formatted for the result body: the dim `$ cd … &&`
+ * prefix joined with syntax-highlighted command lines. The prefix is applied
+ * only to the first line so multi-line commands display cleanly — terminals
+ * reset SGR state at line boundaries, which made the previous single-string
+ * `theme.fg("dim", ...)` form render only the first line as dim.
+ */
+export declare function formatBashCommandLines(args: BashRenderArgs, uiTheme: Theme): string[];
+/** Builds a shell transcript renderer with caller-supplied command labels. */
+export declare function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>): {
+    renderCall(args: TArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: BashToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: BashRenderContext;
+    }, uiTheme: Theme, args?: TArgs): Component;
+    mergeCallAndResult: true;
+    inline: true;
+};
+/** Renders bash command previews and output. */
+export declare const bashToolRenderer: {
+    renderCall(args: BashRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: {
+            type: string;
+            text?: string;
+        }[];
+        details?: BashToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: BashRenderContext;
+    }, uiTheme: Theme, args?: BashRenderArgs | undefined): Component;
+    mergeCallAndResult: true;
+    inline: true;
+};