@linxiraos/pi-tui 1.2.1 → 1.3.1

package/dist/types/components/markdown.d.ts

@@ -2,6 +2,51 @@ import { type TokensList } from "@linxiraos/pi-utils/marked";
 import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { SymbolTheme } from "../symbols.js";
 import type { Component } from "../tui.js";
+/**
+ * `text` as the streaming renderer lexes it: OSC 8 terminators unified and
+ * tabs expanded. {@link Markdown.getLastRenderStableText} is a prefix of this
+ * form, not of the raw source, so append-only publishers that mix settled
+ * prefixes with whole blocks must compare both in this form. Rendering it is
+ * byte-identical to rendering `text`.
+ */
+export declare function streamingMarkdownSource(text: string): string;
+/**
+ * Streaming `md` source for a native terminal, minus a still-growing table row:
+ * the unterminated last line when a GFM table (a run of pipe lines holding a
+ * header and its delimiter row, outer pipes optional) sits right above it,
+ * outside any open code fence. GFM continues a table on any non-blank line, so
+ * that line is a row whatever it holds so far. The terminal sizes columns by
+ * every row it gets, so a half-streamed row (an unclosed link shows its whole
+ * URL) would rewrap the table each frame, and TSP cannot ask it to skip one.
+ * The result keeps the newline before the held line, so it is a prefix of
+ * `text` and of the result for every append to it: streaming stays
+ * append-only. Pass untrimmed source: trimming first drops the newline that
+ * marks the last row finished, so that row would be held too.
+ */
+export declare function holdPartialTableRow(text: string): string;
+/**
+ * `text`, one inline run whose end is still streaming, with a trailing open
+ * link or math span closed the way the finished text most likely closes it,
+ * or `undefined` when nothing at its end is open. A link gains its missing
+ * `)` (one per open parenthesis in its destination), so it renders as the
+ * link it becomes instead of literal brackets and URL. A math body is cut back
+ * to its last valid form (a half-typed command, dangling `^`/`_`, or the first
+ * `$` of a `$$` closer dropped, open braces closed) and closed, so the
+ * rendered math grows in place instead of raw LaTeX turning into symbols at
+ * the closer. A `$` body needs a LaTeX character, so a price (`$5 per`) is
+ * never speculated. Only prose is: escaped openers and anything inside a code
+ * span, closed or still being written, stay literal.
+ */
+export declare function speculativeInlineClose(text: string): string | undefined;
+/**
+ * Streaming `md` source for a native terminal with the open link or math span
+ * at its end speculatively closed ({@link speculativeInlineClose}), as the TUI
+ * renders it. Only the last block is read (a span cannot cross a blank line),
+ * and source inside an open code fence is left as it is. Each frame rewrites
+ * only the guessed closers at the end, which the reconciler sends as a small
+ * `splice`.
+ */
+export declare function speculativeStreamingSource(text: string): string;
 /** @internal exported for tests — the grown-line block-kind gate. */
 export declare function fastLineStartHazard(grownLine: string): boolean;
 /**
@@ -140,9 +185,10 @@ export declare class Markdown implements Component {
      */
     describe(_cx: DescribeContext): NativeNode;
     /**
-     * Width-independent source prefix of the last render ending at a frozen
-     * Markdown block boundary that no append can move: it stops in front of a
-     * display-math opener whose block an append could still close. Only
+     * Width-independent source prefix of the last render that no append can
+     * change: up to a frozen Markdown block boundary, stopping in front of a
+     * display-math opener whose block an append could still close, or, while a
+     * list streams as the last block, up to its newest top-level item. Only
      * meaningful while streaming (transient render cache on); grows
      * monotonically under append-only `setText`.
      */

package/dist/types/components/text.d.ts

@@ -12,6 +12,8 @@ import type { Component } from "../tui.js";
 export declare class Text implements Component {
     #private;
     setIgnoreTight(ignore: boolean): this;
+    /** Override row wrapping when the source carries structural prefixes. */
+    setWrapLine(wrapLine: (line: string, width: number) => string[]): this;
     constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
     /** Return bounded text and layout state for debug inspection. */
     debugState(): Record<string, unknown>;

package/dist/types/debug-server.d.ts

@@ -22,6 +22,8 @@ export interface TuiDebugTree {
 export declare class TuiDebugServer {
     #private;
     constructor(tui: TUI, path: string);
+    /** Resolves true once the socket accepts connections, false if listen failed or the server stopped first. */
+    get ready(): Promise<boolean>;
     start(): void;
     stop(): void;
 }

package/dist/types/keybinding-matchers.d.ts

@@ -9,6 +9,8 @@ import type { KeyId } from "./app-keybindings.js";
 export declare function matchesAppInterrupt(data: string): boolean;
 /** Match `app.tools.expand`, falling back to Ctrl+O when the action is unbound. */
 export declare function matchesAppToolsExpand(data: string): boolean;
+/** Effective tools-expand key: the first bound key, or Ctrl+O when unbound. */
+export declare function appToolsExpandKey(): KeyId;
 /** Match the generic selector cancel keybinding. */
 export declare function matchesSelectCancel(data: string): boolean;
 /** Match the generic selector up-navigation keybinding. */
@@ -36,3 +38,7 @@ export declare function matchesAppExternalEditor(data: string): boolean;
  * effective follow-up binding.
  */
 export declare function matchesAppFollowUp(data: string): boolean;
+/** Effective tool-approval keys: the `app.approval.approve` bindings, or Ctrl+Enter/Ctrl+Q when unbound. */
+export declare function appApproveKeys(): readonly KeyId[];
+/** Match the tool-approval key, recognizing modifier-tagged LF as Ctrl+Enter like {@link matchesAppFollowUp}. */
+export declare function matchesAppApprove(data: string): boolean;

package/dist/types/multiplexers/tmux.d.ts

@@ -22,6 +22,7 @@ export declare const tmuxMultiplexer: {
         readonly passthrough: typeof wrapTmuxPassthrough;
         readonly settleMs: 100;
     };
+    readonly gatesBracketedPaste: true;
     readonly expandsRepPadding: true;
     readonly expiresSynchronizedOutput: true;
     readonly altRestoreEndsSynchronizedOutput: true;

package/dist/types/multiplexers/types.d.ts

@@ -73,6 +73,12 @@ export interface TerminalMultiplexerModule<Id extends string = string> {
      * session, and an unrecognized report does not turn it off.
      */
     readonly honorsSynchronizedOutput?: boolean;
+    /**
+     * Tracks DEC 2004 per pane and forwards paste markers only while it is set,
+     * yet may leave DECRQM 2004 unanswered, so bracketed paste is reasserted
+     * without waiting for a DECRPM confirmation.
+     */
+    readonly gatesBracketedPaste?: boolean;
     /**
      * The session does not reveal whether its client renders graphics while
      * outer-terminal identity variables leak in, so images and Kitty

package/dist/types/native/backend.d.ts

@@ -47,10 +47,11 @@ export interface NativeBackendOptions {
 }
 /**
  * The reply a v1 terminal is assumed to give before its real `hello` arrives
- * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary, the
- * default APC limit and credits, the terminal's width, the appearance omp
- * already detected, full motion, and `blobs`, so a resumed session's images
- * are asked about rather than resent before the reply comes.
+ * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary except
+ * {@link UNASSUMED_KINDS}, the default APC limit and credits, the terminal's
+ * width, the appearance omp already detected, full motion, and `blobs`, so a
+ * resumed session's images are asked about rather than resent before the
+ * reply comes.
  */
 export declare function assumedTspHello(terminal: Terminal): TspHello;
 export declare class NativeBackend {

package/dist/types/native/blobs.d.ts

@@ -1,14 +1,5 @@
-/**
- * Content-addressed binary blobs (images) for `image` nodes.
- *
- * `describe()` registers the bytes and puts the returned id in `image.p.blob`;
- * the native backend delivers each referenced blob once per terminal
- * connection (asking the terminal first which it holds, or through its blob
- * cache), else uploads it with verb `b` before the frame that first
- * references it.
- */
 import type { TspProps } from "@linxiraos/pi-wire";
-import type { NativeNode } from "./node.js";
+import type { NativeChild, NativeNode } from "./node.js";
 export interface NativeBlob {
     readonly id: string;
     readonly mime: string;
@@ -26,8 +17,29 @@ export declare function nativeImageNode(bytes: Uint8Array, mime: string, p?: Omi
  * so callers cache the node per payload ({@link NativeImageCache}).
  */
 export declare function base64ImageNode(data: string, mimeType: string, p?: Omit<TspProps<"image">, "blob" | "builtin" | "w" | "h">, key?: string): NativeNode;
-/** `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload changes. */
+/**
+ * Props that make an `image` node open the file at `filePath` (as a `file://` URL, the TSP
+ * open-target form): a click zooms the image in the terminal, and the file opens from its
+ * context menu. Empty without a file.
+ */
+export declare function openableImageProps(filePath: string | undefined): Pick<TspProps<"image">, "href" | "actions">;
+/**
+ * `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload
+ * or the link policy changes. Each opens its file (`sourcePath`, else a blob copy).
+ */
 export declare class NativeImageCache {
     #private;
-    get(key: string, data: string, mimeType: string): NativeNode;
+    get(key: string, data: string, mimeType: string, sourcePath?: string): NativeNode;
 }
+/** The disk file a tool result's image was read from (`read` details `mediaPath`), when it has one. */
+export declare function readMediaPath(details: unknown): string | undefined;
+/**
+ * A `media` node the host loads by path, capped at the inline image preview
+ * height. Callers check `cx.supports("media")` first.
+ */
+export declare function nativeMediaNode(path: string, key: string): NativeNode;
+/** Blob ids of the `image` nodes and paths of the `media` nodes under `children` (described nodes only). */
+export declare function shownMedia(children: readonly NativeChild[] | undefined): {
+    blobs: Set<string>;
+    paths: Set<string>;
+};

package/dist/types/overlays/agent-hub-projection.d.ts

@@ -1,6 +1,9 @@
 import type { AgentMetricsSummary, AgentRecordLike, AgentStatus } from "./agent-hub-types.js";
 import type { ObservableSession } from "./session-observer-registry.js";
 export type AgentMetrics = AgentMetricsSummary;
+export interface AgentCostSnapshot {
+    cost: number | undefined;
+}
 export interface AggregateMetrics extends AgentMetrics {
     reportedAgents: number;
     /** Rows whose duration is an observer-measured active runtime. */
@@ -17,14 +20,16 @@ export declare const STATUS_ORDER: Record<AgentStatus, number>;
 export declare function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined;
 /** Live session used to cache a row's direct assistant usage, including with observer progress. */
 export declare function hubFallbackStatsSession<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined): NonNullable<TRecord["session"]> | undefined;
-/**
- * Preserve progress/history for non-cost metrics, overlaying cumulative direct-session cost.
- * Persisted `history.metrics.cost` is a leaf-scoped snapshot, so it never overrides live
- * progress; only the cumulative direct-cost sources do.
- */
+/** Full Agent Hub row metrics; see {@link projectRowMetrics} for source precedence. */
 export declare function hubRowMetrics<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined, sessionMetrics: WeakMap<object, {
     metrics: AgentMetrics | undefined;
 }>): AgentMetrics | undefined;
+/** Cost-only projection for frequent status updates; full roster metrics keep their own cache. */
+export declare function aggregateCost<TRecord extends AgentRecordLike>(args: {
+    rows: readonly TRecord[];
+    observedById: ReadonlyMap<string, ObservableSession>;
+    sessionCosts: WeakMap<object, AgentCostSnapshot>;
+}): number;
 export declare function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
     rows: readonly TRecord[];
     observedById: ReadonlyMap<string, ObservableSession>;

package/dist/types/overlays/annotation-overlay.d.ts

@@ -2,6 +2,7 @@ import { type Focusable, type TUI } from "../index.js";
 import { type KeybindingsManager } from "../app-keybindings.js";
 import { type Theme } from "../theme/theme.js";
 import type { CodeReviewAnnotation, CodeReviewOverlayResult, ReviewDiffFile, TextReviewAnnotation, TextReviewOverlayResult, TextReviewSource } from "./annotation-types.js";
+import type { TspSpan } from "@linxiraos/pi-wire";
 import { type NativeNode, type NativeUiEvent } from "../native/node.js";
 export declare const CONTINUE_CODE_REVIEW_ACTION = "Continue with LLM review";
 export declare const PASTE_CODE_REVIEW_ACTION = "Paste annotations into prompt";
@@ -21,6 +22,12 @@ export interface TextReviewOverlayCallbacks extends AnnotationOverlayCallbacks {
 }
 /** Splits a text source into the overlay's 1-based annotatable lines. */
 export declare function splitTextLines(text: string): string[];
+/** The native sheet: full-pane glass, titled by the review kind with what is under review after it. */
+interface NativeSheet {
+    readonly role: "zeta.overlay.codeReview" | "zeta.overlay.annotateText";
+    readonly size: "full";
+    readonly head: TspSpan[];
+}
 /** A fullscreen, annotated diff picker that only relies on public OMP APIs. */
 export declare class AnnotationOverlay implements Focusable {
     #private;
@@ -44,7 +51,19 @@ export declare class AnnotationOverlay implements Focusable {
      */
     replaceTextSource(text: string): number;
     handleInput(data: string): void;
+    /**
+     * The terminal draws the frame: a full-pane glass sheet titled `Code review`
+     * (or `Annotate text`), then what is under review as a quieter subtitle.
+     */
+    get nativeOverlay(): NativeSheet;
+    /**
+     * The sheet's body: the file rail (totals over the changed files) beside
+     * the current file's diff (text: its numbered lines), the note composer
+     * docked under the lines while a note is open, and a footer of key hints
+     * and the actions.
+     */
     describe(): NativeNode;
     handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];
 }
+export {};

package/dist/types/overlays/approval-dialog.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Tool-approval prompt in the composer's place, presented like the ask
+ * dialog: the approval title and its details over a list of choices —
+ * Approve, an optional "approve for this session", and Deny — and an action
+ * bar. The arrows move between the choices and Enter takes the highlighted
+ * one; `app.approval.approve` (Ctrl+Enter by default) approves this call
+ * outright and Esc denies. Enter and the approve chord only arm
+ * {@link APPROVE_ARM_MS} after mount, so a key meant for the composer (Enter,
+ * or the follow-up chord pressed mid-run) as the prompt appears never answers
+ * it. With an {@link ApprovalDialogDraft}, every other key edits the composer
+ * mounted beneath the dialog, so a message can deny the call and steer the
+ * turn instead: while the composer holds a draft, the arrows and Enter edit and
+ * send it, and the highlight sits on Deny, relabeled to say Enter sends.
+ * The prompt stays a few rows so the composer keeps its room; Page Up/Down
+ * scroll the details, and with a full prompt the expand key
+ * (`app.tools.expand`) swaps it in, wrapped.
+ */
+import { type Component, type TUI } from "../index.js";
+import { type NativeNode, type NativeUiEvent } from "../native/node.js";
+/** Enter and the approve key are ignored this long after mount, so a key sent as the prompt appears cannot answer it. */
+export declare const APPROVE_ARM_MS = 500;
+interface ApprovalDialogCallbacks {
+    onApprove(): void;
+    onDeny(): void;
+}
+/** The composer mounted beneath the dialog: it receives every key the dialog does not own. */
+export interface ApprovalDialogDraft {
+    /** True while the composer holds a draft — text, attachments, or a paste still landing: keys then edit and send it. */
+    hasDraft(): boolean;
+    handleInput(keyData: string): void;
+}
+interface ApprovalDialogOptions {
+    tui?: TUI;
+    /** The prompt with every detail in full, which the expand key swaps in (wrapped) for the summarized one. */
+    fullPrompt?: string;
+    /** Deny once this many ms pass without input (any key restarts the countdown). */
+    timeout?: number;
+    /** Called when {@link timeout} expires, before the dialog denies. */
+    onTimeout?: () => void;
+    /** Called when the countdown starts, as the dialog mounts. */
+    onTimeoutStart?: () => void;
+    /** Called each time a key restarts the countdown. */
+    onTimeoutReset?: () => void;
+    /** Route typing to the composer instead of dropping it. */
+    draft?: ApprovalDialogDraft;
+    /** Offer to approve this and later like calls for the rest of the session, as the row between Approve and Deny. */
+    session?: {
+        label: string;
+        onApprove(): void;
+    };
+}
+export declare class ApprovalDialogComponent implements Component {
+    #private;
+    private readonly callbacks;
+    private readonly options;
+    /** `prompt`: the approval title on its first line, the details after it. */
+    constructor(prompt: string, callbacks: ApprovalDialogCallbacks, options?: ApprovalDialogOptions);
+    invalidate(): void;
+    dispose(): void;
+    handleInput(keyData: string): void;
+    /**
+     * Swap the summarized prompt for every detail, wrapped, or back, as the expand key does here;
+     * for hosts that intercept that key first. Restarts the countdown like any key. False (nothing
+     * changes) without a full prompt, so the host's own expand handling (tool previews) can run.
+     */
+    toggleDetails(): boolean;
+    render(width: number): readonly string[];
+    /**
+     * In the dock, in the composer's place and framed as the composer is (an
+     * `zeta.editor.*` root role), like the ask dialog, rather than a card over
+     * the transcript: the title, the details, the choices with the keyboard's
+     * highlight (a click takes one), then Details (with a full prompt), Deny,
+     * and the primary Approve, whose keys show in their tooltips.
+     */
+    describe(): NativeNode;
+    /** Deny, Approve, and Details run exactly what Esc, the approve key, and the expand key run; a click on a choice takes it. */
+    handleNativeEvent(event: NativeUiEvent): void;
+}
+export {};

package/dist/types/overlays/ask-dialog.d.ts

@@ -88,7 +88,6 @@ export declare class AskDialogComponent implements Component {
     #private;
     private readonly callbacks;
     private readonly options;
-    readonly retireDisplacedTranscript = true;
     constructor(questions: ExtensionAskDialogQuestion[], callbacks: AskDialogCallbacks, options?: AskDialogOptions);
     invalidate(): void;
     dispose(): void;
@@ -102,17 +101,23 @@ export declare class AskDialogComponent implements Component {
     render(width: number): readonly string[];
     /**
      * In the dock, in the composer's place and framed as the composer is: a
-     * `col` with the prompt editor's root role (`zeta.editor`), so the terminal
-     * gives it the composer's insets and spacing. Not a modal `overlay` sheet:
-     * one anchored at the bottom covered the transcript rows that explain the
-     * question and blocked scrolling until the question was answered.
+     * `col` with an `zeta.editor.*` root role (`zeta.editor.ask`, collapsed
+     * `zeta.editor.ask.hidden`), so the terminal draws the composer's shell
+     * around it. Not a modal `overlay` sheet: one anchored at the bottom
+     * covered the transcript rows that explain the question and blocked
+     * scrolling until the question was answered.
+     *
+     * Anatomy: the question tabs (several questions), the question, its
+     * answers as radio/check rows, and the action bar as the footer (the
+     * countdown, Hide, then Note, Skip and the primary Submit/Next).
      */
     describe(cx: DescribeContext): NativeNode;
     /**
      * Pointer actions: a tab click switches to it; a click on an answer row is
      * Enter on it (Space for a multi-select option, so it toggles; its
      * double-click `activate` is Enter); the action bar's Submit, Note and Skip
-     * run exactly what Enter, `n` and Esc run on the highlighted row.
+     * run exactly what Enter, `n` and Esc run on the highlighted row; Hide/Show
+     * collapse and restore the dialog.
      */
     handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/overlays/btw-history-panel.d.ts

@@ -40,12 +40,8 @@ export declare class BtwHistoryPanel implements Component, Focusable {
     /** Enhanced clipboard pastes belong only to the active composer. */
     pasteText(text: string): void;
     handleInput(data: string): void;
-    /** A large glass sheet titled "BTW history". */
-    readonly nativeOverlay: {
-        readonly role: "zeta.overlay.btwHistory";
-        readonly size: "lg";
-        readonly head: "BTW history";
-    };
+    /** A large glass sheet (the list beside the reader), palette-sized while there is nothing to list. */
+    get nativeOverlay(): NonNullable<Component["nativeOverlay"]>;
     describe(): NativeNode;
     handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];

package/dist/types/overlays/hook-editor.d.ts

@@ -10,7 +10,7 @@
 import type { ImageContent } from "@linxiraos/pi-ai";
 import { type Focusable, type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
-import type { DescribeContext, NativeNode } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /**
  * `prefix` and `question` flattened onto one line, wrapped to the terminal's width and cut to
  * {@link MAX_PROMPT_TITLE_ROWS} rows (the last ends in `…` when cut). For terminal rendering only:
@@ -58,8 +58,13 @@ export declare class HookEditorComponent extends OverlayPanel implements Focusab
     /** Focus state mirrored to the nested editor during rendering. */
     focused: boolean;
     constructor(tui: TUI, title: string, prefill: string | undefined, onSubmit: (value: string, images?: ImageContent[]) => void, onCancel: () => void, options?: HookEditorOptions);
-    /** The editor (which describes itself) under the title and detail lines, with the key hints below. */
+    /**
+     * A sheet in the composer's place: the title (or, answering a question, the question under the
+     * prompt's name) over a hairline, the editor, and Open in editor · Cancel · Submit.
+     */
     describe(_cx: DescribeContext): NativeNode;
+    /** The action bar's buttons run what their keys run. */
+    handleNativeEvent(event: NativeUiEvent): void;
     /** Keep the nested editor's software/hardware cursor mode aligned with the dialog focus target. */
     setUseTerminalCursor(useTerminalCursor: boolean): void;
     /** Render the dialog after forwarding its focus state to the nested editor. */

package/dist/types/overlays/hook-input.d.ts

@@ -1,9 +1,9 @@
 /**
- * Simple text input component for hooks.
+ * One-line text prompt an extension (hook) asks the user.
  */
 import { type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
-import type { DescribeContext, NativeNode } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 export interface HookInputOptions {
     tui?: TUI;
     timeout?: number;
@@ -11,13 +11,21 @@ export interface HookInputOptions {
 }
 export declare class HookInputComponent extends OverlayPanel {
     #private;
-    constructor(title: string, _placeholder: string | undefined, onSubmit: (value: string) => void, onCancel: () => void, opts?: HookInputOptions);
+    constructor(title: string, placeholder: string | undefined, onSubmit: (value: string) => void, onCancel: () => void, opts?: HookInputOptions);
     handleInput(keyData: string): void;
     /** Route non-bracketed paste transports (e.g. kitty's OSC 5522 enhanced clipboard)
      *  into the inner field, mirroring bracketed-paste semantics. Pasting counts as
      *  interaction, so the timeout countdown resets like any keystroke. */
     pasteText(text: string): void;
+    /** Submit and Cancel run what Enter and the interrupt key run. */
+    handleNativeEvent(event: NativeUiEvent): void;
     dispose(): void;
-    /** A card over the form, headed by the title plus the countdown `elapsed` while a timeout runs. */
+    /**
+     * A sheet in the composer's place, built like the extension editor's: the
+     * title's first line (the countdown at its end while a timeout runs) over
+     * any further lines as detail, the field written on the sheet (tinted, the
+     * reason under it, while a submit was refused), and Cancel · Submit, whose
+     * keys live in their tooltips.
+     */
     describe(_cx: DescribeContext): NativeNode;
 }

package/dist/types/overlays/job-tree.d.ts

@@ -0,0 +1,50 @@
+import type { Theme } from "../theme/theme.js";
+/** What the tree reads off a job. */
+export interface JobTreeJob {
+    readonly id: string;
+    readonly status: "running" | "completed" | "failed" | "cancelled";
+    readonly startTime: number;
+    /** Registry id of the agent that owns the job; absent or the root id: a top-level job. */
+    readonly ownerId?: string;
+    /** Registry id of the subagent a task job runs: the job heads that agent's subtree. */
+    readonly agentId?: string;
+}
+/** A subagent in the tree, by registry id: an owner of listed jobs, or an ancestor linking one to the root. */
+export interface JobTreeAgent {
+    readonly id: string;
+    readonly parentId?: string;
+}
+/** Where a row sits: its depth and the rails drawn left of it. */
+export interface JobTreePlace {
+    /** 0 for the top level. */
+    readonly depth: number;
+    /** Per enclosing level below the top, whether that level's rail continues past this row. */
+    readonly rails: readonly boolean[];
+    /** Whether this row is the last of its siblings. */
+    readonly last: boolean;
+    /** Whether rows nest under this one. */
+    readonly parent: boolean;
+}
+/** One tree row: a job (a task job also heads its subagent), or a header for a subagent with no listed task job. */
+export type JobTreeRow<J extends JobTreeJob> = (JobTreePlace & {
+    readonly kind: "job";
+    readonly job: J;
+    readonly agent?: JobTreeAgent;
+}) | (JobTreePlace & {
+    readonly kind: "agent";
+    readonly agent: JobTreeAgent;
+});
+/**
+ * `jobs` as tree rows in display order. `rootId` is the viewing agent: its
+ * jobs, ownerless jobs and jobs of owners outside `agents` sit at the top
+ * level, as do agents whose parent is the root or unknown.
+ */
+export declare function buildJobTree<J extends JobTreeJob>(jobs: readonly J[], agents: readonly JobTreeAgent[], rootId: string | undefined): JobTreeRow<J>[];
+/** The connector drawn before a row's head: nothing at the top level, else rails then a branch. */
+export declare function jobTreeGuide(row: JobTreePlace, theme: Theme): string;
+/**
+ * The prefix of lines under a row's head (its label, a wrapped command): the
+ * rails that continue past it, then the rail down to its children or blank,
+ * two columns wide so a top-level leaf's lines indent by two.
+ */
+export declare function jobTreeIndent(row: JobTreePlace, theme: Theme): string;

package/dist/types/overlays/jobs-panel.d.ts

@@ -1,5 +1,6 @@
 import type { Component } from "../tui.js";
 import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
+import { type JobTreeAgent } from "./job-tree.js";
 /** One async job as the session snapshots it. */
 export interface JobsPanelJob {
     readonly id: string;
@@ -8,13 +9,19 @@ export interface JobsPanelJob {
     readonly label: string;
     readonly startTime: number;
     readonly endTime?: number;
+    /** Registry id of the agent that owns the job. */
+    readonly ownerId?: string;
     /** Registry id of the subagent a task job runs. */
     readonly agentId?: string;
 }
-/** Running and recently settled jobs. */
+/** Running and recently settled jobs of an agent and its subagents. */
 export interface JobsPanelSnapshot {
     readonly running: readonly JobsPanelJob[];
     readonly recent: readonly JobsPanelJob[];
+    /** The agent the sheet is for: its jobs sit at the top level, and only they can be cancelled. */
+    readonly rootId?: string;
+    /** Subagents owning listed jobs, with the ancestors linking them to the root. */
+    readonly agents?: readonly JobTreeAgent[];
 }
 /** What the sheet shows about the selected job beyond its row. */
 export interface JobsPanelDetail {
@@ -35,19 +42,26 @@ export interface JobsSheetSource {
     load(): JobsPanelSnapshot;
     /** The selected job's detail; runs once per frame, undefined once the job is gone. */
     inspect(id: string): JobsPanelDetail | undefined;
-    /** Cancel a running job. */
-    cancel(id: string): void;
+    /**
+     * Cancel a running job. Omitted by a read-only sheet (a focused subagent
+     * view, which only watches that agent): it lists the jobs and offers no way
+     * to stop them.
+     */
+    cancel?(id: string): void;
     /** Dismiss the sheet. */
     close(): void;
 }
 /**
  * The jobs pill's sheet: a centred `lg` glass sheet titled Background jobs.
- * A selectable list of every job (running first) sits over the selected
- * job's detail: status and live elapsed (a task job's `agent` node), cwd,
- * live pids, exit code, the full command and a tail-following output pane.
- * It re-reads the session every frame, so the caller re-renders it on a
- * timer while it is open. ↑/↓ select, X cancels the selected running job,
- * Esc or Close dismisses; nothing enters the transcript.
+ * A master–detail split (it stacks in a narrow pane): the selectable job tree
+ * beside the selected job's detail — a status pill with live elapsed and
+ * Cancel job, its command or task, facts (agent, cwd, live pids, exit code,
+ * artifact) and a tail-following output pane. With no jobs it shows an empty
+ * state. It re-reads the session every frame, so the caller re-renders it on
+ * a timer while it is open. ↑/↓ select, X cancels the selected running job,
+ * Esc or Close dismisses; nothing enters the transcript. A source without
+ * `cancel` renders read-only, and a subagent's job never offers Cancel: only
+ * the root's own jobs can be stopped here.
  */
 export declare class JobsSheet implements Component {
     #private;
@@ -58,8 +72,8 @@ export declare class JobsSheet implements Component {
         readonly head: "Background jobs";
     };
     constructor(source: JobsSheetSource);
-    describe(cx: DescribeContext): NativeNode;
-    /** Rows for a terminal without the native surface: one per job, then the selected job's facts and output tail. */
+    describe(_cx: DescribeContext): NativeNode;
+    /** Rows for a terminal without the native surface: the job tree, then the selected job's facts and output tail. */
     render(width: number): readonly string[];
     invalidate(): void;
     handleInput(data: string): void;

package/dist/types/overlays/login-dialog.d.ts

@@ -40,9 +40,14 @@ export declare class LoginDialogComponent extends OverlayPanel {
     showProgress(message: string): void;
     /**
      * A glass sheet over the composer (the dialog replaces the editor in the
-     * dock; the `overlay` hoists into the terminal's layer): numbered steps —
-     * open or copy the sign-in link, the device code, the live wait, the paste
-     * field — and Cancel.
+     * dock; the `overlay` hoists into the terminal's layer). Top to bottom: one
+     * sentence saying what to do, the device code as a large click-to-copy
+     * well, the sign-in link as a read-only field with Copy, the questions
+     * (answered ones as label/value lines, the live one as a field), and the
+     * flow's status — finished stages checked, the current one spinning. The
+     * footer holds Cancel and one primary action: Continue while a field waits
+     * for an answer (Open sign-in page then leads the footer as a plain
+     * button), else Open sign-in page.
      */
     describe(): NativeNode;
     /** Cancel and Continue run what Esc and Enter run. */

package/dist/types/overlays/mcp-add-wizard.d.ts

@@ -83,8 +83,16 @@ interface MCPAddWizardOAuthOptions {
 export declare class MCPAddWizard extends OverlayPanel {
     #private;
     constructor(deps: MCPAddWizardDeps, onComplete: (name: string, config: MCPAddWizardConfig, scope: Scope) => void, onCancel: () => void, onOAuth?: (authUrl: string, tokenUrl: string, clientId: string, clientSecret: string, scopes: string, options?: MCPAddWizardOAuthOptions) => Promise<MCPAddWizardOAuthResult>, onTestConnection?: (config: MCPAddWizardConfig) => Promise<void>, onRender?: () => void, initialName?: string);
+    /**
+     * The sheet: the phase strip, the step's title and lead, its body (field,
+     * status, summary), its choices, and a footer whose buttons run what
+     * Escape, Enter and Ctrl+C run.
+     */
     describe(_cx: DescribeContext): NativeNode;
-    /** A click on a choice is Enter on it, exactly as highlighting it with the arrows and pressing Enter. */
+    /**
+     * A click on a choice is Enter on it, exactly as highlighting it with the
+     * arrows and pressing Enter; the footer's buttons run what their keys run.
+     */
     handleNativeEvent(event: NativeUiEvent): void;
     handleInput(keyData: string): void;
 }