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

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

@@ -0,0 +1,42 @@
+import type { Component } from "../tui.js";
+import type { Theme } from "../theme/theme.js";
+import type { RenderResultOptions } from "./renderer.js";
+/** Lifecycle state of a tracked goal. */
+export type GoalStatus = "active" | "paused" | "budget-limited" | "complete" | "dropped";
+/** Serializable goal progress and resource budget. */
+export interface Goal {
+    id: string;
+    objective: string;
+    status: GoalStatus;
+    tokenBudget?: number;
+    tokensUsed: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Goal operation outcome displayed in the transcript. */
+export interface GoalToolDetails {
+    op: "create" | "get" | "complete" | "resume" | "drop";
+    goal?: Goal | null;
+    remainingTokens?: number | null;
+    completionBudgetReport?: string | null;
+}
+interface GoalRenderArgs {
+    op?: GoalToolDetails["op"];
+    objective?: string;
+    token_budget?: number;
+}
+/** Renders goal creation, status, and lifecycle results. */
+export declare const goalToolRenderer: {
+    renderCall(args: GoalRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: GoalToolDetails;
+        isError?: boolean;
+    }, _options: RenderResultOptions, uiTheme: Theme, args?: GoalRenderArgs): Component;
+    mergeCallAndResult: true;
+};
+export {};

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

@@ -0,0 +1,64 @@
+import type { Component } from "../tui.js";
+import type { 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";
+/** Display metadata for grep tool results. */
+export interface GrepToolDetails {
+    truncation?: TruncationResult;
+    fileLimitReached?: number;
+    perFileLimitReached?: number;
+    linesTruncated?: boolean;
+    meta?: OutputMeta;
+    scopePath?: string;
+    matchCount?: number;
+    fileCount?: number;
+    files?: string[];
+    fileMatches?: Array<{
+        path: string;
+        count: number;
+    }>;
+    truncated?: boolean;
+    error?: string;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors the model-facing
+     * `result.text` lines but uses a `│` gutter and `*` to mark match lines (vs space for
+     * context). The TUI uses this directly so it never parses model-facing hashline anchors. */
+    displayContent?: string;
+    /** Filesystem hyperlink targets resolved for internal URL headers at execution time. */
+    displayTargets?: Record<string, 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. The renderer resolves the display-relative
+     * (cwd-relative) header/match paths against this for OSC 8 hyperlinks;
+     * `searchPath` is the scope label target, not the display-path base. */
+    cwd?: string;
+    /** User-supplied paths whose base directory was missing on disk. The tool
+     * skipped these and continued with the surviving entries; surfaced as a
+     * non-fatal warning in the renderer and in the model-facing text. */
+    missingPaths?: string[];
+}
+interface GrepRenderArgs {
+    pattern: string;
+    path?: string | string[];
+    /** Legacy pre-`path` argument name; kept so historical transcripts still render a scope. */
+    paths?: string | string[];
+    case?: boolean;
+    gitignore?: boolean;
+    skip?: number;
+}
+/** Render grep calls and results in the transcript. */
+export declare const grepToolRenderer: {
+    inline: true;
+    renderCall(args: GrepRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: GrepToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: GrepRenderArgs): Component;
+    mergeCallAndResult: true;
+};
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * One file's contribution to a grouped file output. The header itself is generated
+ * by `formatGroupedFiles` (one `#` per nesting level); use `headerSuffix` to tack
+ * on extras like ` (1 replacement)`.
+ */
+export interface GroupedFileSection {
+    /** Optional suffix appended to the file header. */
+    headerSuffix?: string;
+    /** Body lines emitted into the textual model output. */
+    modelLines: string[];
+    /** Body lines emitted into the display output. Defaults to `modelLines`. */
+    displayLines?: string[];
+    /** When true, the file (and its header) is omitted entirely. */
+    skip?: boolean;
+}
+/** Parallel model-facing and display-facing lines for grouped files. */
+export interface GroupedFilesOutput {
+    model: string[];
+    display: string[];
+}
+/**
+ * Render a list of files as a multi-level, prefix-folded directory tree shared by
+ * grep, ast-grep, ast-edit, and the LSP diagnostic formatter.
+ *
+ * Layout (one `#` per level; the shared prefix folds into the top header):
+ *   # packages/pkg/src/
+ *   ## root.ts
+ *   …body…
+ *   ## nested/
+ *   ### child.ts
+ *   …body…
+ *
+ * Files in the (folded) project root become single-`#` headers with no parent
+ * directory line. A blank line precedes every directory header and every
+ * root-level file so the renderers can split the output into collapsible groups.
+ */
+export declare function formatGroupedFiles(files: string[], renderFile: (filePath: string) => GroupedFileSection): GroupedFilesOutput;
+/** Per-line classification of grouped output, used by renderers for hyperlinks. */
+export interface GroupedLineContext {
+    /** Directory header, file header, or any non-header body/content line. */
+    kind: "dir" | "file" | "content";
+    /** Number of leading `#` for headers; 0 for content lines. */
+    depth: number;
+    /** Resolved absolute path of the dir/file a header points at (when resolvable). */
+    headerPath?: string;
+    /** For content lines, the absolute path of the owning file (line hyperlinks). */
+    filePath?: string;
+    /** Header is an internal/url-like target the caller resolves itself. */
+    isUrl?: boolean;
+}
+/**
+ * Walk grouped output lines, tracking a directory stack keyed by header depth, so
+ * each header and body line can be linked back to its absolute filesystem path.
+ * Reconstruction is stack-based (not per-blank-group) so nested directory headers
+ * resolve correctly across the whole output.
+ *
+ * `headerBase` is the directory the displayed (folded) header paths are relative
+ * to — for grep/ast tools that is the session cwd, since display paths are
+ * formatted relative to cwd regardless of the (sub)directory the search was
+ * scoped to. `fileScope` is the initial owning file for body lines that appear
+ * before any header (single-file scopes have no `#` headers); it defaults to
+ * `headerBase` and should be passed the scoped file's absolute path.
+ */
+export declare function classifyGroupedLines(lines: readonly string[], headerBase: string | undefined, fileScope?: string | undefined): GroupedLineContext[];
+/**
+ * Split line indices into blank-line-separated groups, mirroring
+ * `splitGroupsByBlankLine`: when any blank line is present, break on runs of
+ * blanks; otherwise return a single group of the non-empty lines. Returning
+ * indices lets callers slice parallel arrays (raw lines, styled lines, contexts).
+ */
+export declare function groupLineIndicesByBlank(rawLines: readonly string[]): number[][];

package/dist/types/tools/hashline-format.d.ts

@@ -0,0 +1,28 @@
+/** Opening delimiter of a hashline file header. */
+export declare const HL_FILE_PREFIX = "[";
+/** Closing delimiter of a hashline file header. */
+export declare const HL_FILE_SUFFIX = "]";
+/** Separator between the file path and content hash. */
+export declare const HL_FILE_HASH_SEP = "#";
+/** Number of characters in a displayed file hash. */
+export declare const HL_FILE_HASH_LENGTH = 4;
+/** Keyword identifying a file move operation. */
+export declare const HL_MOVE_KEYWORD = "MV";
+/** Keyword identifying a file removal operation. */
+export declare const HL_REM_KEYWORD = "REM";
+/** Separator between a line number and its body. */
+export declare const HL_LINE_BODY_SEP = ":";
+/** Format a file path and content hash as a hashline header. */
+export declare function formatHashlineHeader(path: string, tag: string): string;
+/** Prefix each addressable line with its file line number. */
+export declare function formatNumberedLines(text: string, startLine?: number): string;
+/** Prefix one line with its file line number. */
+export declare function formatNumberedLine(lineNumber: number, line: string): string;
+/** Split file lines without treating a trailing newline as an empty address. */
+export declare function splitAddressableFileLines(text: string): string[];
+/** Remove model-facing hashline anchors from copied file content. */
+export declare function stripHashlinePrefixes(lines: string[]): string[];
+/** Whether a row is a truncation notice emitted by `read`. */
+export declare function isReadTruncationNotice(line: string): boolean;
+/** Compute the native hashline content fingerprint. */
+export declare function computeFileHash(text: string): string;

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

@@ -0,0 +1,340 @@
+import type { Component } from "../tui.js";
+import type { Theme } from "../theme/theme.js";
+import { type OutputMeta } from "./output-meta.js";
+import { type ConfiguredThinkingLevel } from "../render/render-utils.js";
+import type { StructuredSubagentOutput } from "./task.js";
+import type { RenderResultOptions, ToolActivitySummary } from "./renderer.js";
+/** Whether a wait snapshot contains only running jobs and no cancellations. */
+export declare function isWaitingPollDetails(details: unknown): boolean;
+/**
+ * Hub operations: messaging (`send`/`wait`/`inbox`/`list`), jobs
+ * (`wait`/`cancel`/`jobs`), and process supervision (`start`/`ps`/`logs`/
+ * `stop`/`restart`/`describe`, plus `send`/`wait` when they carry `name`).
+ */
+export type HubOp = "send" | "wait" | "inbox" | "list" | "jobs" | "cancel" | "start" | "ps" | "logs" | "stop" | "restart" | "describe";
+/** Peer row surfaced by `op:"list"`. */
+export interface HubPeerInfo {
+    id: string;
+    displayName: string;
+    kind: string;
+    status: string;
+    parentId?: string;
+    unread: number;
+    lastActivity: number;
+    activity?: string;
+}
+/** Status values `op:"list"` can filter on. Advisor is a kind, not a status. */
+export type HubListStatus = "running" | "idle" | "parked";
+/** Model-facing roster bounds shared by the hub schema and executor. */
+export declare const DEFAULT_HUB_LIST_LIMIT = 32;
+/** Maximum number of peers in a hub roster page. */
+export declare const MAX_HUB_LIST_LIMIT = 100;
+/** Addressable roster tallies always returned by `op:"list"`. */
+export interface HubRosterCounts {
+    running: number;
+    idle: number;
+    parked: number;
+    shown: number;
+    truncated: number;
+}
+/** Background-job row surfaced by `wait`/`cancel`/`jobs` results. */
+export interface JobSnapshot {
+    id: string;
+    type: "bash" | "task" | "eval";
+    status: "running" | "completed" | "failed" | "cancelled";
+    label: string;
+    durationMs: number;
+    /** Effective task model selector, including an explicit reasoning suffix when configured. */
+    resolvedModel?: string;
+    /** Provider/id including routing, with no added thinking suffix. */
+    resolvedModelIdentity?: string;
+    /** Explicit thinking metadata, independent of the model identity. */
+    resolvedThinkingLevel?: ConfiguredThinkingLevel;
+    /** True when the task progress reports an attached live advisor. */
+    advisor?: boolean;
+    resultText?: string;
+    errorText?: string;
+    /** Source-output metadata retained for per-job warnings and persisted row rendering. */
+    meta?: OutputMeta;
+    /** Capture error in historical snapshots; new snapshots store source metadata in `meta`. */
+    artifactError?: OutputMeta["artifactError"];
+    structured?: StructuredSubagentOutput;
+    /**
+     * `agent://<id>` handle backing this job's artifacts — the job-row's
+     * registry `agentId` when the manager disambiguated a requested job id
+     * on collision, else the job id itself. See {@link AsyncJob.agentId}.
+     */
+    agentUrlId?: string;
+}
+/** Outcome of cancelling one background job. */
+export type CancelStatus = "cancelled" | "not_found" | "already_completed";
+/** Cancellation outcome and its model-facing explanation. */
+export interface CancelOutcome {
+    id: string;
+    status: CancelStatus;
+    message: string;
+}
+/**
+ * A live subagent from the AgentRegistry that has no backing job in the
+ * AsyncJobManager — e.g. an idle agent woken (or a parked agent revived) via
+ * a hub message, or a spawn owned by another agent. Surfaced by `jobs` and
+ * empty-wait snapshots so the hub's picture matches the UI's running-agent
+ * count.
+ */
+export interface AgentActivitySnapshot {
+    id: string;
+    parentId?: string;
+    /** Latest activity gist recorded by the registry (display-only). */
+    activity?: string;
+    /** Time since the agent was registered. */
+    ageMs: number;
+    /**
+     * Whether an attached session corroborates the `running` claim. False marks
+     * a ref that says `running` with no turn in flight — either a spawn still
+     * wiring up or a stale registration that `hub cancel <id>` clears (#8634).
+     */
+    live: boolean;
+    /**
+     * Acceptance time of the agent's final result, when the registry recorded
+     * one. With `live: false` this is an accepted run the parent may cancel
+     * instead of waiting on (#11079).
+     */
+    acceptedAt?: number;
+}
+/** Result details for messaging and job ops; fields are disjoint per op. */
+export interface CoordinationDetails {
+    meta?: OutputMeta;
+    op: HubOp;
+    from?: string;
+    to?: string;
+    receipts?: IrcDeliveryReceipt[];
+    /** Message consumed by `wait` / `send await:true`; null when the wait timed out. */
+    waited?: IrcMessage | null;
+    inbox?: IrcMessage[];
+    peers?: HubPeerInfo[];
+    /** Present on `op:"list"`: addressable running/idle/parked plus page size. */
+    counts?: HubRosterCounts;
+    jobs?: JobSnapshot[];
+    cancelled?: {
+        id: string;
+        status: CancelStatus;
+    }[];
+    /** Running subagents not represented by a job row in this result. */
+    agents?: AgentActivitySnapshot[];
+}
+/** Hub result details: coordination snapshots or launch (process) state. */
+export type HubDetails = CoordinationDetails | LaunchToolDetails;
+/** Partially-streamed hub call arguments, as seen by the renderers. */
+export type HubRenderArgs = {
+    op?: string;
+    to?: string;
+    message?: string;
+    replyTo?: string;
+    await?: boolean;
+    from?: string;
+    peek?: boolean;
+    ids?: string[];
+} & Partial<Omit<LaunchParams, "op">>;
+/** Stable lifecycle states exposed by the launch tool. */
+export type DaemonState = "starting" | "running" | "ready" | "restarting" | "stopping" | "exited" | "failed";
+/** Restart behavior applied after an unexpected daemon exit. */
+export type DaemonRestartPolicy = "no" | "on-failure" | "always";
+/** Readiness conditions; every configured condition must pass. */
+export interface DaemonReadySpec {
+    log?: string;
+    port?: number;
+    host?: string;
+    timeoutMs: number;
+}
+/** Immutable launch specification retained for restart and inspection. */
+export interface DaemonSpec {
+    name: string;
+    application: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+    pty: boolean;
+    ready?: DaemonReadySpec;
+    restart: DaemonRestartPolicy;
+    persist: boolean;
+    detached: boolean;
+}
+/** Serializable daemon state visible to every client in one broker scope. */
+export interface DaemonSnapshot {
+    name: string;
+    id: string;
+    state: DaemonState;
+    pid?: number;
+    createdAt: number;
+    startedAt: number;
+    readyAt?: number;
+    exitedAt?: number;
+    exitCode?: number;
+    exitReason?: string;
+    restartCount: number;
+    outputBytes: number;
+    owner?: string;
+    readyMatch?: string;
+    /** Readiness conditions still unmet while `state` is `starting`; absent once ready or without a ready spec. */
+    readyPending?: ("log" | "port")[];
+    persist: boolean;
+    detached: boolean;
+}
+/** Serializable peer message retained in hub result snapshots. */
+export interface IrcMessage {
+    id: string;
+    /** Sender agent id. */
+    from: string;
+    /** Recipient agent id (resolved; "all" is expanded by the tool, not stored). */
+    to: string;
+    body: string;
+    ts: number;
+    /** Message id being answered. */
+    replyTo?: string;
+    /**
+     * Automated wake-turn relay of a woken subagent's stop output (task executor
+     * `relayWakeTurnOutput`). Relays are answers, never wake sources: the
+     * recipient's own wake-turn relay must skip them or two idle peers
+     * ping-pong forever.
+     */
+    wakeRelay?: boolean;
+}
+/** Delivery outcome for one peer recipient. */
+export interface IrcDeliveryReceipt {
+    to: string;
+    outcome: "injected" | "woken" | "revived" | "failed";
+    error?: string;
+}
+/** Broker-facing launch parameters; the hub adapts its `ps` op to `list` before calling in. */
+export interface LaunchParams {
+    op: "start" | "list" | "logs" | "wait" | "send" | "stop" | "restart" | "describe";
+    name?: string;
+    application?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    pty?: boolean;
+    ready?: {
+        log?: string;
+        port?: number;
+        host?: string;
+        timeout?: number;
+    };
+    restart?: "no" | "on-failure" | "always";
+    persist?: boolean;
+    detached?: boolean;
+    lines?: number;
+    head?: boolean;
+    grep?: string;
+    follow?: boolean;
+    cursor?: number;
+    for?: "ready" | "exit";
+    pattern?: string;
+    text?: string;
+    enter?: boolean;
+    keys?: string[];
+    signal?: "SIGINT" | "SIGTERM" | "SIGHUP" | "SIGQUIT" | "SIGKILL";
+    timeout?: number;
+}
+/** Structured launch state retained for compact TUI rendering. */
+export interface LaunchToolDetails {
+    op: LaunchParams["op"];
+    daemon?: DaemonSnapshot;
+    daemons?: DaemonSnapshot[];
+    cursor?: number;
+    timedOut?: boolean;
+    /** logs: daemon lifecycle state at read time. */
+    state?: DaemonState;
+    /** logs: virtual terminal rows for display; model-facing content remains sanitized text. */
+    terminalRows?: string[];
+    /** wait: output line that satisfied the pattern. */
+    matched?: string;
+    /** describe: immutable launch spec backing the command/cwd detail lines. */
+    spec?: DaemonSpec;
+}
+/**
+ * Human sentences for the readiness conditions still unmet, e.g.
+ * `port 5173 on 127.0.0.1 never accepted connections`. `ready` (from the start
+ * params) adds the concrete pattern/port; absent it falls back to generic labels.
+ */
+export declare function readyPendingSummary(daemon: DaemonSnapshot, ready?: LaunchParams["ready"]): string[];
+/**
+ * What a timed-out `wait` was actually blocked on: the output `pattern`, the
+ * process exiting (`for: "exit"`, the default), or the unmet readiness
+ * conditions (`for: "ready"`). Never reports readiness for an exit/pattern
+ * wait — the process may well be ready and simply still running.
+ */
+export declare function waitPendingSummary(daemon: DaemonSnapshot, params: Pick<LaunchParams, "for" | "pattern">): string[];
+/** Hub roster ordering (running before idle before parked) shared with the child prompt's live-row cap. */
+export declare const LIST_STATUS_ORDER: Record<string, number>;
+/** Pending-call frame for job ops (wait/cancel/jobs). */
+export declare function jobsRenderCall(args: HubRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+/** Result frame for job snapshots (wait/cancel/jobs and the agents roster). */
+export declare function jobsRenderResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: CoordinationDetails;
+    isError?: boolean;
+}, options: RenderResultOptions, uiTheme: Theme, hubArgs?: HubRenderArgs): Component;
+/** Args shape visible to the renderer, possibly mid-stream (every field optional). */
+export type LaunchRenderArgs = Partial<Omit<LaunchParams, "op">> & {
+    op?: string;
+};
+/** Pending-call frame for launch ops; consumes the spinner while the broker call is live. */
+export declare function launchRenderCall(args: LaunchRenderArgs, options: RenderResultOptions, theme: Theme): Component;
+/** Result frame: one status header per op, meta from structured details, capped body lines. */
+export declare function launchRenderResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: LaunchToolDetails;
+    isError?: boolean;
+}, options: RenderResultOptions, theme: Theme, args?: LaunchRenderArgs): Component;
+/**
+ * Display-only transcript card for live IRC traffic: `irc:incoming` DMs
+ * delivered to this session, `irc:autoreply` side-channel replies sent on
+ * this session's behalf, and `irc:relay` observations of agent↔agent
+ * traffic. Shares the tool renderer's glyph + quote-border conventions so
+ * cards and hub messaging output look identical in the transcript.
+ */
+export declare function createIrcMessageCard(card: {
+    kind: "incoming" | "autoreply" | "relay" | "workpool";
+    from?: string;
+    to?: string;
+    body?: string;
+    replyTo?: string;
+    timestamp?: number;
+    pool?: string;
+    mode?: string;
+}, getExpanded: () => boolean, uiTheme: Theme): Component;
+/** Pending-call frame for messaging ops (send/wait-from/inbox/list). */
+export declare function messagingRenderCall(args: HubRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+/** Result frame for messaging ops and message-carrying `wait` results. */
+export declare function messagingRenderResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: CoordinationDetails;
+    isError?: boolean;
+}, options: RenderResultOptions, uiTheme: Theme, args?: HubRenderArgs): Component;
+/** Renders hub messaging, jobs, and supervised processes. */
+export declare const hubToolRenderer: {
+    inline: true;
+    mergeCallAndResult: true;
+    /** Compact one-line activity: op plus its peer, process, or job target. */
+    activitySummary(args: unknown): ToolActivitySummary;
+    animatedPendingPreview: (args: unknown) => boolean;
+    renderCall(args: HubRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: HubDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: HubRenderArgs): Component;
+};

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

@@ -0,0 +1,4 @@
+import type { ToolRenderer } from "./renderer.js";
+export * from "./renderer.js";
+/** Renderers keyed by tool name (plus `apply_patch`/`reject` aliases that share a renderer). */
+export declare const toolRenderers: Record<string, ToolRenderer>;

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

@@ -0,0 +1,59 @@
+import type { Theme } from "../theme/theme.js";
+/** Max depth for JSON tree rendering */
+export declare const JSON_TREE_MAX_DEPTH_COLLAPSED = 2;
+/** Maximum expanded JSON tree depth. */
+export declare const JSON_TREE_MAX_DEPTH_EXPANDED = 6;
+/** Maximum collapsed JSON tree rows. */
+export declare const JSON_TREE_MAX_LINES_COLLAPSED = 6;
+/** Maximum expanded JSON tree rows. */
+export declare const JSON_TREE_MAX_LINES_EXPANDED = 200;
+/** Maximum collapsed JSON scalar width. */
+export declare const JSON_TREE_SCALAR_LEN_COLLAPSED = 60;
+/** Maximum expanded JSON scalar width. */
+export declare const JSON_TREE_SCALAR_LEN_EXPANDED = 2000;
+/** Sanitization, string summary, and budgeting policy for inline JSON. */
+export interface InlineFormatOptions {
+    sanitizeText?: (text: string) => string;
+    multilineSummary?: boolean;
+    /** Character-count output budget, retaining the first pair even when oversized. */
+    characterBudget?: boolean;
+}
+/** Format a scalar with optional sanitized multiline summaries. */
+export declare function formatScalar(value: unknown, maxLen: number, options?: InlineFormatOptions): string;
+/** Format args inline with either display-cell or legacy output character budgeting. */
+export declare function formatArgsInline(args: Record<string, unknown>, maxWidth: number, options?: InlineFormatOptions): string;
+/** Summarize a task's structured output without expanding its JSON tree. */
+export declare function formatOutputInline(data: unknown, maxWidth?: number): string;
+/** JSON hierarchy policy accepted by {@link renderJsonTreeLines}. */
+export interface JsonTreeRenderOptions {
+    maxDepth: number;
+    maxLines: number;
+    maxScalarLen: number;
+    /** Sanitize object keys and string/scalar text before styling. */
+    sanitizeText?: (text: string) => string;
+    /** Root object keys omitted from display. Defaults to internal tool argument metadata. */
+    hiddenRootKeys?: readonly string[];
+    /** Preserve embedded newlines as continuation rows. Defaults to true. */
+    multilineStrings?: boolean;
+    /** Escape inline tabs/newlines as JSON-style sequences. Defaults to true. */
+    escapeStringWhitespace?: boolean;
+    /**
+     * Root row gutter. `hooked` (default) attaches the tree to the block above:
+     * the first root draws `└ •`, the rest ` •`, and nested rows branch from
+     * under the bullet. `siblings` draws standard `├─`/`└─` root connectors.
+     */
+    rootConnectors?: "hooked" | "siblings";
+}
+/**
+ * Render a JSON value as bounded tree lines. The positional form remains the
+ * public tool-renderer contract; the options form exposes sanitization and root
+ * connector policy for specialized adapters such as nested task output.
+ */
+export declare function renderJsonTreeLines(value: unknown, theme: Theme, maxDepth: number, maxLines: number, maxScalarLen: number): {
+    lines: string[];
+    truncated: boolean;
+};
+export declare function renderJsonTreeLines(value: unknown, theme: Theme, options: JsonTreeRenderOptions): {
+    lines: string[];
+    truncated: boolean;
+};

package/dist/types/tools/line-ranges.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Inclusive line range describing one selector segment (e.g. `50-100`,
+ * `301-`, or `50+10`). `endLine` is `undefined` for open-ended ranges.
+ */
+export interface LineRange {
+    startLine: number;
+    endLine: number | undefined;
+}
+/** Shared line-range grammar for selector recognition and parsing. */
+export declare const LINE_RANGE_CHUNK_SOURCE: string;
+/** Parse a single `N`, `N-M`, `N-`, `N+K`, or `..`-aliased (`N..M`, `N..`) chunk. Throws via {@link ToolError} on invalid bounds. */
+export declare function parseLineRangeChunk(sel: string): LineRange | null;
+/**
+ * Parse a comma-separated list of line ranges (e.g. `5-16,960-973`). Returns
+ * the ranges in ascending order with overlapping/adjacent ranges merged so
+ * downstream consumers can stream the file in a single forward pass per range.
+ */
+export declare function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null;
+/**
+ * Extract the line-range component from a read-tool selector that may also
+ * carry a verbatim/index display mode (`raw`, `conflicts`) — alone or compounded
+ * with a range (`raw:50-100`, `50-100:raw`). Returns the parsed ranges when the
+ * selector names any, otherwise `undefined` (pure `raw`/`conflicts`/none).
+ *
+ * Used by content search, which honors line ranges as a match filter but has no
+ * use for verbatim/conflict display modes — so those selectors are accepted and
+ * treated as an unfiltered, whole-resource search rather than rejected.
+ */
+export declare function selectorLineRanges(sel: string | undefined): [LineRange, ...LineRange[]] | undefined;

package/dist/types/tools/list-limit.d.ts

@@ -0,0 +1,15 @@
+import type { LimitsMeta } from "./output-meta.js";
+/** Items retained after applying output limits and their metadata. */
+export interface ListLimitResult<T> {
+    items: T[];
+    limitReached?: number;
+    meta: Partial<LimitsMeta>;
+}
+/** Limits applied to result lists and display previews. */
+export interface ListLimitOptions {
+    limit?: number;
+    headLimit?: number;
+    limitType?: "match" | "result";
+}
+/** Apply result and preview limits while retaining truncation metadata. */
+export declare function applyListLimit<T>(items: T[], options: ListLimitOptions): ListLimitResult<T>;