@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/terminal-ui.d.ts

@@ -0,0 +1,744 @@
+import { EventEmitter } from 'node:events';
+import type { ReadStream, WriteStream } from 'node:tty';
+import type { Graph } from './graphs.js';
+import type { RuntimeEvent } from './types.js';
+import type { BrowserApprovalDetails, BrowserPending } from './browser-bridge.js';
+import type { TodoItem } from './todos.js';
+import type { AccountPresentation } from './account-presentation.js';
+import { type ToolCallStamp } from './tool-call-clock.js';
+import { type PanelChanges, type PanelTerminal } from './side-panel.js';
+import { type PendingAttachment } from './attachments.js';
+export interface TerminalStatus {
+    provider: string;
+    model: string;
+    branch?: string;
+    yolo: boolean;
+    permissions?: string;
+    session?: string;
+    activity?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    requests?: number;
+    contextWindow?: number;
+    /** Input tokens reported for the most recent model request; live context-window use. */
+    contextUsed?: number;
+    reasoningEffort?: string;
+    graph?: Graph;
+    providerModels?: Record<string, string>;
+    graphSelection?: string;
+    /**
+     * The selected graph names providers this machine cannot bind, so it cannot run as it stands.
+     *
+     * Only the refresh that resolves the selected graph sets this, so the hint it drives is never
+     * shown for a graph the session is not actually on. A successful load, or a selection that
+     * loads, clears it.
+     */
+    graphNeedsOverride?: boolean;
+    codeIntel?: string;
+    account?: AccountPresentation;
+    jevEnabled?: boolean;
+    /**
+     * Working-tree summary the side panel's Git section reports.
+     *
+     * Owned by the CLI rather than the render pass: reading it spawns `git`, so the CLI
+     * refreshes it at run boundaries and on write-shaped tool completions instead of once
+     * per frame.
+     */
+    changes?: PanelChanges;
+    /** Background terminal sessions the side panel lists; likewise refreshed by the CLI. */
+    terminals?: readonly PanelTerminal[];
+}
+export interface TerminalOptions extends TerminalStatus {
+    input?: ReadStream;
+    output?: WriteStream;
+    workspace: string;
+    version: string;
+    appName?: string;
+    /**
+     * Clock backing the view's time readings - the footer's token speed and the side panel's
+     * terminal ages; defaults to `Date.now`.
+     *
+     * The meter compares request windows and the panel ages background sessions, so a caller that
+     * needs a deterministic reading (a test, or an embedder driving the UI from its own clock)
+     * supplies this instead of patching the global clock.
+     */
+    tokenClock?: () => number;
+    /**
+     * Reads an image from the system clipboard for the composer's Ctrl+V binding.
+     *
+     * Terminals cannot paste an image as text, so the binding asks the platform; the CLI
+     * supplies the probe and tests supply a stub, keeping this module free of child processes.
+     */
+    clipboardImageProbe?: () => Promise<Buffer | undefined>;
+    /**
+     * Writes text to the system clipboard for Ctrl+C / Ctrl+X over a composer selection.
+     *
+     * A rejection, or no writer at all, falls back to an OSC 52 clipboard sequence, which most
+     * terminals honor and which also reaches the local clipboard over SSH.
+     */
+    clipboardTextWriter?: (text: string) => Promise<void>;
+}
+export interface TerminalChoice {
+    id: string;
+    label: string;
+    description?: string;
+    bold?: boolean;
+    separator?: boolean;
+}
+export interface ScreenOptions {
+    description?: string;
+    signal?: AbortSignal;
+    editPrefix?: string;
+    footer?: string;
+}
+/** Full-screen terminal presentation; provider/runtime behavior remains owned by the CLI. */
+export declare class TerminalUI extends EventEmitter {
+    private readonly input;
+    private readonly output;
+    private readonly workspace;
+    private readonly version;
+    private readonly appName;
+    private readonly keys;
+    private readonly decoder;
+    private status;
+    /**
+     * Graph nodes the user currently has running, in the order they started.
+     *
+     * `provider` and `model` are what each node's own executor reported, not what the graph file
+     * configured, so a retry that falls back to another profile moves the footer with it.
+     *
+     * `resolved` carries the reasoning effort and context window of that same resolution. It stays
+     * absent until a run reports them, and an absent `resolved` keeps the session's own numbers on
+     * the footer; a present one whose fields are undefined means that node's model has no effort or
+     * window of its own, which the footer shows as `provider default` and as no window at all
+     * rather than falling back to the session's unrelated values.
+     */
+    private activeNodes;
+    /**
+     * Node ids the current run has finished, in visit order.
+     *
+     * The side panel's zoom marks the run's trail with it, so it survives the run's end - a
+     * reader looking at a finished run can still see where it went - and is cleared only when
+     * the next run starts, which is the point the trail stops describing what is on screen.
+     */
+    /** Whether the last frame drew without the panel, so its return can be announced once. */
+    private panelWasHidden;
+    private visitedNodes;
+    /** The node a stopped run ended on, kept as the panel's position until the next run starts. */
+    private stoppedNode?;
+    private readonly toolClock;
+    private toolClockTimer?;
+    private updateToolClock;
+    private dashboard;
+    private readonly dashboardMetrics;
+    private dashboardModel;
+    private dashboardGraphOffset;
+    private dashboardNotices;
+    private nodeModels;
+    toggleDashboard(): void;
+    /** Start of a run: open the dashboard's run window. */
+    startTask(): void;
+    /** End of a run: close the dashboard's run window. */
+    finishTask(): void;
+    resetDashboardSession(usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        requests: number;
+    }): void;
+    /** Clock backing the per-node speed meters; see {@link TerminalOptions.tokenClock}. */
+    private readonly tokenClock;
+    /**
+     * One cumulative speed meter per generating identity, each stamped with the provider, model
+     * and reasoning effort its requests were measured under.
+     *
+     * Parallel nodes interleave model calls (`src/graph-runner.ts` runs branch workers side by
+     * side), so a single shared meter would have one node's first request discard the other's
+     * in-flight window and both nodes' totals alternate between wipes. Keys extend the nodeId
+     * with the parallel `copy` number the modifier stamps on every forwarded event, because two
+     * copies of one node can resolve different models and retry independently. Keeping the
+     * accumulation per identity means a switch simply displays the new identity's own average,
+     * and returning to an earlier one resumes the average it built.
+     */
+    private speedMeters;
+    /** The executor's `invocationId` → the meter key whose marker opened that request's window. */
+    private speedInvocations;
+    /** The node whose requests the readout currently follows: the most recent to open a call. */
+    private activeSpeedNode;
+    /** The parallel copy of {@link activeSpeedNode} the readout follows, when one is named. */
+    private activeSpeedCopy;
+    /** The exact meter key the readout displays - a node, a node's copy, or a distillation. */
+    private activeSpeedKey;
+    handleRuntimeEvent(event: RuntimeEvent): void;
+    private nodeProgress;
+    /**
+     * The columns the chat column actually draws in, panel and gutter excluded.
+     *
+     * Everything that measures chat content outside the render pass - input navigation, the
+     * echoed-prompt frame, the docked selection card, the command popup's own visibility gate -
+     * has to measure against this rather than the terminal width, or a draft that the composer
+     * wrapped onto two rows is treated as one by the arrow keys, and a stored card is built
+     * wider than the transcript that must re-wrap it.
+     */
+    private chatColumns;
+    /**
+     * Columns the transcript itself would have with the panel drawn.
+     *
+     * A prompt echo is stored in the transcript and re-wrapped there, so its frame has to be built for
+     * that column rather than for whatever surface is on screen when the text is submitted: a task sent
+     * from the Ctrl+B dashboard (or from a modal) would otherwise freeze a full-width box whose rows the
+     * transcript splits as soon as the panel returns. This is `chatColumns()` with the two full-screen
+     * surfaces ignored.
+     */
+    private transcriptColumns;
+    /**
+     * Columns the side panel occupies this frame, or 0 when it is not drawn.
+     *
+     * The panel is a second column of the same frame, so its width has to be known before the
+     * chat column renders: below {@link PANEL_MIN_COLUMNS} the chat column would be squeezed
+     * past the point where its own wrapping and the command popup still read well, and the two
+     * full-screen surfaces - the dashboard (which already reports the same state) and a modal
+     * screen (which is a focused flow) - keep the frame to themselves.
+     */
+    /**
+     * Whether the side panel is on screen for the current terminal and surface.
+     *
+     * Exposed because the panel is the only consumer of the CLI's Git summary: a caller that would
+     * spawn processes to fill it can ask first, and skip the work while nothing can display it.
+     */
+    panelVisible(): boolean;
+    private panelColumns;
+    /**
+     * The side panel's rows for this frame.
+     *
+     * Assembled per render rather than cached: the rows carry a clock (how long a background
+     * terminal has been running) and follow the node set the run is publishing, and the packing
+     * only ever walks a handful of sections.
+     * @param columns - total columns the panel occupies, divider and gutter included.
+     * @param height - rows the panel may use, the whole frame height.
+     */
+    private panelRows;
+    /**
+     * Compose the chat column's rows with the panel's into the frame's rows.
+     *
+     * Each row is padded to the chat width so the divider column stays unbroken, then carries
+     * the panel cell for that row. A painted row is measured with `stringWidth`, which ignores
+     * escape sequences, so padding cannot be confused by the color the chat row already holds.
+     */
+    private composePanel;
+    /**
+     * The model currently answering, as its footer label plus the thinking effort and context window
+     * that belong to it.
+     *
+     * While a graph node is active this names the node the user is watching - the one whose
+     * requests the speed readout follows, or the first-started one when no speed identity is
+     * named - followed by the provider and model that node actually resolved and by the effort
+     * and window of that same resolution, so the whole line describes one model. With no active
+     * node it is the session's own selection, and no node is named for an idle prompt or for a
+     * plain run that never started a graph node.
+     */
+    private activeModel;
+    private started;
+    private closed;
+    private wasRaw;
+    private wasPaused;
+    private scheduled;
+    private pending?;
+    private value;
+    private cursor;
+    private transcript;
+    private expandedTranscript;
+    private todos;
+    private expandedTodos;
+    private todoOffset;
+    private todoPageSize;
+    private scroll;
+    /** Whether a run is streaming: with no prompt pending, the wheel may scroll the transcript. */
+    private runActive;
+    /**
+     * Whether alternate scroll mode (?1007) is currently armed.
+     *
+     * The app never takes mouse reporting, so the terminal keeps drag-to-select and its
+     * clipboard in every state. In the alternate screen a terminal instead turns the wheel
+     * into Up/Down sequences when alternate scroll is on — byte-identical to the arrow keys,
+     * and on by default in Windows Terminal, VTE and iTerm2 — so the app arms that mode only
+     * where Up/Down cannot recall history: while a screen is open, or while a run streams with
+     * no question pending. At the resting prompt it is switched off and the wheel is inert.
+     */
+    private alternateScroll;
+    /**
+     * Live reasoning preview state. `thinkingActive` marks a stream in progress; the text
+     * is the bounded tail the preview renders from.
+     */
+    private thinking;
+    private thinkingActive;
+    /** The preview opens expanded on every stream; Ctrl+Y collapses the current one. */
+    private thinkingExpanded;
+    private expandedPromptIds;
+    /** Prompts the reader explicitly collapsed; an explicit toggle wins over Ctrl+O (see promptExpanded). */
+    private collapsedPromptIds;
+    /** Every prompt box the transcript currently holds, so Ctrl+O can invert each one on screen. */
+    private promptBoxIds;
+    private expandedPromptVisible;
+    private nextPromptId;
+    private thinkingPaintedAt;
+    private thinkingFlush?;
+    /**
+     * The rows currently on screen, so a repaint can rewrite only what changed.
+     *
+     * See {@link writeFrame}: a terminal drops an in-progress drag selection when the app
+     * rewrites the cells under it, and a run repaints eight times a second for its animation.
+     */
+    private drawn;
+    /** Terminal size `drawn` was produced at; a resize invalidates the comparison. */
+    private drawnSize;
+    /** The caret sequence last emitted, so an unmoved caret costs no extra write. */
+    private drawnCursor;
+    private history;
+    private historyIndex;
+    private draft;
+    private completion?;
+    private dismissedCompletion?;
+    private incoming;
+    private pasting;
+    private paste;
+    private pasteQuestion?;
+    private plainTimer?;
+    private pendingBreak;
+    private plainPaste;
+    private plainTrailingCR;
+    private plainQuestion?;
+    private modal?;
+    private modalInput;
+    /**
+     * The last selection screen that was answered.
+     *
+     * Setup closes a selection screen and then asks for a value, which used to leave the home
+     * card where the list had been: the reader lost both the list and the entry it led to the
+     * moment they started typing. The card is kept here so a typed field can be answered with
+     * the list still on screen (see selectionCard).
+     */
+    private lastSelection?;
+    private escapeTimer?;
+    private workingTimer?;
+    /** The panel's one-second age clock; see render(). */
+    private panelTimer?;
+    private workingSince?;
+    private workingElapsed;
+    /**
+     * Whether the composer accepts input while a run is active.
+     *
+     * Enabled for the duration of an interactive run so the user can steer it. Text
+     * submitted in this mode is queued rather than resolved as a question answer.
+     */
+    private steering;
+    private runInputHandler?;
+    private localCommandHandler?;
+    private commandInput;
+    /** Handle active commands and resumed direction synchronously; true consumes the input. */
+    setRunInputHandler(handler?: (text: string) => boolean): void;
+    /** Observe slash commands consumed by the view without submitting them to the run. */
+    setLocalCommandHandler(handler?: (input: string, mode: 'interactive' | 'in-run', durationMs: number) => void): void;
+    /** Settle the current approval after an explicit session permission change. */
+    resolveQuestion(value: string): void;
+    /** Submit from the browser only while the terminal is accepting a conversation prompt. */
+    acceptConversationPrompt(value: string): boolean;
+    /** Current runtime question for connected GUI surfaces. Conversation prompts stay in the composer. */
+    private browserPendingIdentity?;
+    private browserQuestionNumber;
+    browserQuestion(): BrowserPending | undefined;
+    private steered;
+    /**
+     * Attachments queued in the composer draft — large pastes spooled to text, dropped file
+     * paths, clipboard images. Each sits in the draft as an inline token (its `marker` code
+     * point), drawn as an amber label and edited as one character. They ride the next submitted
+     * task (or the next queued steer) and are drained by the CLI, mirroring how `steered` is
+     * drained at turn boundaries.
+     */
+    private attachments;
+    private attachmentSeq;
+    /**
+     * Generation of the composer's attachment surface. Advanced by every draft clear and steer
+     * submission: an asynchronous clipboard probe that started before one of those lands nowhere,
+     * because the composer it was reading for is gone (steering keeps the same owner all run).
+     */
+    private clipboardProbe;
+    private readonly clipboardImageProbe?;
+    private readonly clipboardTextWriter?;
+    /**
+     * Where the composer's Shift+Arrow selection started; it runs from here to the cursor.
+     * `selectionValue` is the draft it was made in: replacing the draft (a submission, history
+     * recall, a completion) swaps the array, which drops the selection without bookkeeping.
+     */
+    private selectionAnchor;
+    private selectionValue;
+    /**
+     * A half-typed steer parked while a question temporarily takes the composer.
+     *
+     * Questions and steering share `value`; without this a partially typed steer would be
+     * wiped the moment the runtime asks for an approval or clarification.
+     */
+    private steerDraft?;
+    private steerCursor;
+    constructor(options: TerminalOptions);
+    start(): void;
+    question(prompt?: string, options?: {
+        kind?: 'question' | 'approval';
+        title?: string;
+        signal?: AbortSignal;
+        cancelOnEscape?: boolean;
+        conversationPrompt?: boolean;
+        history?: boolean;
+        secret?: boolean;
+    }): Promise<string>;
+    chooseQuestion(prompt: string, items: TerminalChoice[], options?: {
+        kind?: 'question' | 'approval';
+        approvalDetails?: BrowserApprovalDetails;
+        signal?: AbortSignal;
+        printPrompt?: boolean;
+    }): Promise<string | undefined>;
+    select(title: string, items: readonly TerminalChoice[], options?: ScreenOptions & {
+        selectedId?: string;
+    }): Promise<string | undefined>;
+    /** Move the select highlight, carrying the movement past separator rows: separators are visual line breaks, never choices. */
+    private moveSelection;
+    showScreen(title: string, lines: readonly string[], options?: ScreenOptions): Promise<void>;
+    loadScreen<T>(title: string, load: (signal: AbortSignal) => Promise<T>, options?: ScreenOptions): Promise<T | undefined>;
+    private openModal;
+    private finishModal;
+    print(text: string, detail?: string, toolCall?: ToolCallStamp, conversation?: boolean, notice?: boolean, alignRight?: boolean): void;
+    /**
+     * Echo submitted text as its own bordered box.
+     *
+     * The box mirrors the live input field's frame and color so the text reads as the
+     * same surface the user typed into, rather than a `You >` transcript prefix. The
+     * frame itself identifies the text as user input, so a submitted prompt is left
+     * untitled; only a surface that is genuinely something other than a task prompt —
+     * a clarification answer — passes a title. The frame is sized to the terminal at
+     * echo time; a later resize re-wraps the body but keeps the original box, which is
+     * an accepted trade for not rewriting history on resize. The finished box is drawn right-aligned against the transcript's right margin (see wrapTranscript), so a submission reads as the user's speech bubble and re-aligns when the window is resized.
+     * @param text - the submitted text to echo.
+     * @param title - optional top-border label; omitted draws a plain frame.
+     */
+    printPrompt(text: string, title?: string): void;
+    /**
+     * Stream one reasoning delta into the live preview line.
+     *
+     * The preview always shows the tail of what has arrived, so each call only has to grow
+     * the bounded buffer; rendering stays on the working clock's repaint cadence, with a
+     * small throttle so a token firehose cannot trigger a full-frame render per network
+     * chunk.
+     * @param delta - the reasoning fragment that just arrived; empty fragments are ignored.
+     */
+    appendThinking(delta: string): void;
+    /**
+     * Wipe the on-screen conversation so the display reads as a freshly started session.
+     *
+     * Only the transcript entries, the scroll position and the live reasoning preview are dropped:
+     * the welcome card is rebuilt as the scrollback prefix on the next render, so the frame returns
+     * to its startup shape without re-emitting a banner or a terminal clear escape. The composer's
+     * prompt-recall history is deliberately kept — it is input history, not chat output.
+     */
+    clearConversation(): void;
+    /** Retract the preview: the stream ended, was retried, or the whole run finished. */
+    clearThinking(): void;
+    setStatus(partial: Partial<TerminalStatus>): void;
+    /**
+     * Feed the footer's token-speed readout with one finished model request.
+     *
+     * Providers report a request's tokens only when it completes. A streamed request carries its
+     * measured decode window, which is the time the tokens are credited with; otherwise the
+     * number is measured over the window opened by the call's `agent.iteration.started` event
+     * rather than credited to the instant it arrived, which would leave the readout no duration
+     * to divide by. The completion also replaces the live estimate {@link noteStreamedOutput}
+     * kept for the same request. `invocationId` - the id the executor stamps on both the start
+     * event and the usage delta - selects that window and, through the marker that opened it,
+     * the node whose average the measurement belongs to, so a completion from a concurrent request cannot
+     * borrow another request's window or another node's average. The measurement folds into
+     * that node's cumulative average, which only a changed selection or a changed model
+     * resolution for the node resets. Deltas that carry no tokens (the adapter's per-attempt
+     * request counting, retries included) are not completions and are passed through to the
+     * meter, which ignores them for window pairing. A final delta without tokens - a provider
+     * that omits usage - still closes its request's window but leaves the average untouched:
+     * it describes the requests that did report.
+     * @param tokens - output tokens the provider reported for that single request.
+     * @param invocationId - request identity from the executor, when one is known.
+     * @param final - true when the delta closes its request, per the runtime's origin flag.
+     * @param decodeMs - the adapter's measured decode window for the request, when it has one.
+     */
+    noteGeneratedTokens(tokens: number, invocationId?: string, final?: boolean, decodeMs?: number): void;
+    /**
+     * Feed the footer's token-speed readout with a fragment a request is still streaming.
+     *
+     * A thinking model can stream for minutes before its usage arrives, and a readout that moved
+     * only on completions sat on the previous number the whole time. The fragment is estimated
+     * into the same meter the completion will report to, and repaints only when the number on
+     * screen changes - a stream from a node the footer does not follow costs nothing.
+     * @param text - the streamed reasoning or answer fragment.
+     * @param invocationId - request identity from the executor, when one is known.
+     */
+    noteStreamedOutput(text: string, invocationId?: string): void;
+    /** Drop a request's live estimate: the attempt failed, is about to be retried, or was aborted. */
+    noteStreamEnded(invocationId?: string): void;
+    /** The meter a request's measurements belong to: the one its start marker named, else the followed one. */
+    private speedRoute;
+    /** The meter key for a node's requests: parallel copies each keep their own meter. */
+    private speedKey;
+    /** The meter's speed entry, created on first sight so no measurement is ever dropped. */
+    private ensureSpeedMeter;
+    /**
+     * Stamp a meter with the resolution its generating identity announced.
+     *
+     * A resolution different from the one the meter already measured under rebuilds the meter:
+     * its average described the previous model or reasoning effort, which is exactly the
+     * whole-agent-fallback case. Learning the identity for a meter that had none (the session
+     * event merely arrives before the meter was stamped) never discards measurements.
+     */
+    private stampSpeedMeter;
+    /**
+     * The footer's token speed: the cumulative average of the generating identity the readout
+     * currently follows, unchanged between completions.
+     *
+     * Exposed for callers and tests that need the exact number the readout is based on. The
+     * footer draws {@link displayRate}, which adds the model-identity check.
+     */
+    tokenSpeed(): number;
+    /**
+     * The node whose resolution the model row and the speed readout describe.
+     *
+     * This is the identity the readout follows - the most recent node or parallel copy to open
+     * a model call - so the row names the same node whose average is drawn, not whichever node
+     * happened to start first. Without a followed identity it falls back to the first active
+     * node, and with no active node at all the session's own selection answers.
+     */
+    private displayNode;
+    /**
+     * The speed the footer shows: the followed identity's cumulative average, but only while
+     * the model row names the resolution the average was measured under.
+     *
+     * After a run ends the row reverts to the session's own selection, so an average measured
+     * on a node with a provider, model or effort override would otherwise sit beside a
+     * different resolution's name; the segment disappears instead of misdescribing it.
+     */
+    private displayRate;
+    /**
+     * Let the composer accept steering input for the duration of a run.
+     *
+     * Called with `true` when an interactive run starts and `false` when it ends, so the
+     * normal question flow owns the composer outside a run.
+     * @param enabled - whether submitted text should be queued as a steer.
+     * @returns when disabling, any queued steers that can no longer be injected. The
+     *   executor's last poll happens before finalization, so a steer submitted in that
+     *   window is visibly accepted but has nowhere to go; returning it lets the caller say
+     *   so instead of dropping it silently.
+     */
+    setSteering(enabled: boolean): string[];
+    /** The surface that currently owns the composer, if any. */
+    private composerOwner;
+    /**
+     * Whether a captured composer owner is still the owner.
+     *
+     * Deferred input (a paste, or an Enter held back by the input-burst window) is only
+     * delivered when the surface that armed it still owns the composer. Steering is an
+     * owner too, so a pasted steer must not be discarded just because no question is
+     * pending.
+     * @param token - the owner captured when the input arrived.
+     * @returns whether that owner may still accept the deferred input.
+     */
+    private ownsComposer;
+    /**
+     * Take every queued steer message, without blocking.
+     *
+     * The hardened executor polls this at turn boundaries; returning immediately with an
+     * empty array is what lets a run continue when the user has typed nothing.
+     * @returns the queued messages, oldest first.
+     */
+    takeSteering(): string[];
+    /** The queued steers with their attachments, oldest first; each turn is one injected user message. */
+    takeSteeringTurns(): {
+        text: string;
+        attachments: PendingAttachment[];
+    }[];
+    setTodos(todos: readonly TodoItem[]): void;
+    private todoLines;
+    /**
+     * Rows for the live reasoning preview, standing in for the plain working line.
+     *
+     * Collapsed it keeps the latest reasoning on one row and pins elapsed time plus the
+     * expand control on the row directly beneath it, so a growing reasoning tail cannot push
+     * the control off to the right. Expanded, the default for every new stream, it opens a
+     * fixed {@link THINKING_ROWS}-row window on the tail, padded at the top with the marker on
+     * the first reasoning row, with the same control row beneath it. `maxRows`
+     * is the room the terminal offers once the transcript keeps at least its last row; a
+     * one-row budget still shows the reasoning row.
+     */
+    private thinkingLines;
+    /** The last nonempty line of the retained reasoning, flattened for one row. */
+    private thinkingTail;
+    private updateWorkingClock;
+    /**
+     * Recompute whether the wheel may act: alternate scroll mode is armed while a screen is
+     * open, or while a run streams with no question pending, and off everywhere else.
+     *
+     * Only transitions write anything. Entering the alternate screen resets the flag first
+     * (`start`), because that screen begins with the mode explicitly switched off.
+     */
+    private updateAlternateScroll;
+    close(): void;
+    private finishQuestion;
+    private onEnd;
+    private onResize;
+    private onData;
+    /** Drain the decoded stream: paste markers and ordinary keys. */
+    private consumeIncoming;
+    /**
+     * The effective disclosure state of one prompt box.
+     *
+     * An explicit per-prompt toggle wins over the Ctrl+O default, and Ctrl+O clears those
+     * toggles when it is pressed (see onKey), so the keyboard always remains a way out of
+     * either state.
+     */
+    private promptExpanded;
+    /**
+     * Scroll the transcript (or the active screen). Positive `direction` scrolls up (toward
+     * older output), which is what an Up key means — typed, or sent by the wheel under
+     * alternate scroll mode.
+     */
+    private scrollBy;
+    private normalData;
+    private insertPlain;
+    private clearPlainInput;
+    private armPlainInput;
+    private insert;
+    /** Whether the surface that owns the composer accepts task input — the only place attachments mean anything. */
+    private conversationComposer;
+    /**
+     * Land a completed bracketed paste. Terminal drag-and-drop arrives as one or more existing
+     * filesystem paths, which become file references; a paste past the inline threshold becomes a
+     * spooled text attachment instead of flooding the composer; everything else inlines as before.
+     */
+    private landPaste;
+    /**
+     * Queue one attachment as an inline token at the composer cursor; false means the per-turn cap
+     * refused it. Outside the conversation composer the token waits, and `adoptTokens` appends it
+     * to the draft once that composer is armed again.
+     */
+    addAttachment(pending: PendingAttachment): boolean;
+    /** Take every queued attachment in draft order, without blocking — the CLI drains this when a task is submitted. */
+    takeAttachments(): PendingAttachment[];
+    /** The amber label a token draws as in the composer. */
+    private tokenLabel;
+    /** The draft as display elements: each token replaced by its label, clipped to the composer. */
+    private visibleDraft;
+    /**
+     * The draft as submitted text. Tokens become `[name]` references the model can match against
+     * the attachment block, and the queue is put in the order the tokens appear. A draft that is
+     * only tokens submits empty, so the CLI keeps its attachment-only task text, and a slash
+     * command submits without them, so the command runs and the attachments stay queued.
+     */
+    private submittedDraft;
+    /** A parked draft brought back into the composer, keeping only tokens whose attachment is still queued. */
+    private restoredDraft;
+    /** Remove draft elements, dropping the attachment behind every token they held. */
+    private removeDraft;
+    /**
+     * Put every queued token that is missing from the armed conversation draft back at its end. A
+     * submitted prompt clears the composer before the CLI drains the queue, and `/attach` queues a
+     * file between prompts, so a token can be queued while no draft holds it.
+     */
+    private adoptTokens;
+    /** Whether attachments are queued, without draining them (the CLI decides whether a submission carries them). */
+    hasQueuedAttachments(): boolean;
+    /** Read the system clipboard for an image and attach it (Ctrl+V; terminals cannot paste images as text). */
+    private pasteClipboardImage;
+    private clearDraft;
+    private onKey;
+    private modalKey;
+    private navigate;
+    /** Move the caret one wrapped row up or down inside the draft; false on the first/last row. */
+    private moveRow;
+    /** The composer's selected grapheme range, or undefined when nothing is selected. */
+    private selectionRange;
+    private deleteSelection;
+    /**
+     * Selection keys for the prompt and steering editors. Shift with an arrow, Home or End
+     * extends the selection from where it started (Shift+Up/Down past the first or last row runs
+     * to that end of the draft, never into history). Over a selection a plain Left/Right
+     * collapses it to that edge and Backspace/Delete remove it; typed or pasted text replaces it
+     * in `insert`. Any other key drops it. True when the key was consumed.
+     */
+    private selectionKey;
+    /**
+     * Copy the composer selection to the clipboard; a cut also removes it from the draft.
+     *
+     * The system writer is preferred; without one, or when it fails, an OSC 52 sequence asks
+     * the terminal to set the clipboard instead.
+     */
+    private copySelection;
+    private complete;
+    /** Put `command ` in the composer and open its argument list, without submitting anything. */
+    private awaitArgument;
+    /**
+     * The command Enter must not run yet: the draft is only the name of a command that needs an
+     * argument, so it is completed to `command ` and the argument list opens. Applies wherever the
+     * popup does — the conversation prompt and the live-run composer — and never to a question,
+     * a secret, or a modal.
+     */
+    private argumentPending;
+    /**
+     * The popup entry Enter should run, or undefined when there is nothing runnable.
+     *
+     * Re-derived from the composer text on every call rather than read from the cached
+     * completion: that cache is shared with the renderer, and a resize or an edit outside the
+     * popup's own key handling can leave it stale, which would let Enter run a row that is no
+     * longer highlighted or no longer drawn. `commandMatches(true)` applies the same visibility
+     * gate the renderer uses, so a candidate that is off-screen on a short terminal reports
+     * nothing, and an entry identical to the draft is not a completion at all.
+     */
+    private selectedCompletion;
+    private commandMatches;
+    private scheduleRender;
+    /**
+     * Paint a frame, rewriting only the rows whose content actually changed.
+     *
+     * The app never takes the mouse (`start`), so the terminal keeps drag-to-select and the
+     * clipboard in every state. What defeated those selections was output churn: a run repaints eight times a second for the working animation alone, and an
+     * emulator abandons the cells under a drag as soon as the app rewrites them. Diffing
+     * against what is already drawn means an unchanged screen writes nothing at all, and every
+     * *contiguous run* of changed rows gets its own write: when two separated rows change (the
+     * animated working row and the footer counters after a request completes, say) the
+     * unchanged rows between them are left alone, so a selection over the transcript, the
+     * composer or the model line survives a footer update. The composed picture is identical
+     * either way - the row diff is a delivery detail, never a change in what is drawn.
+     * @param lines - the frame's rows, top to bottom, exactly as they should read.
+     * @param cursor - optional caret sequence; re-emitted after any painted row, because painting
+     *   hides the caret and only this sequence brings it back. A frame that paints nothing and
+     *   leaves the caret where it was still writes zero bytes, so the caret can ride along with
+     *   the frame without breaking the settled-frame contract.
+     */
+    private writeFrame;
+    /** A quiet startup identity, never a full-width alert-colored diagnostics panel. */
+    private welcome;
+    /**
+     * The selection screen to dock above the composer while a typed field is being answered.
+     *
+     * A plain question that follows a selection screen is a field belonging to that screen, so
+     * the card is drawn where the home card would otherwise be. Run-time questions (approvals,
+     * clarifications) keep their own surface, and the card is windowed around the highlighted
+     * entry so a long list cannot eat the composer's rows on a short terminal.
+     * @param rows - the transcript rows the render pass left for this card.
+     * @returns the card's lines, or undefined when the home card belongs there instead.
+     */
+    private selectionCard;
+    private renderModal;
+    /**
+     * Wrap transcript text into drawn rows.
+     * @param alignRight - pad each stored row that fits the transcript allowance onto its right margin,
+     *   which is what makes a user submission read as a speech bubble. The decision is made on the
+     *   stored row rather than on the fragments: wrapping a row that does not fit leaves short tails
+     *   (the last cells of a split border) that would otherwise be pushed into the margin, smearing
+     *   the frame across the screen, so no fragment of an over-wide row is padded.
+     */
+    private wrapTranscript;
+    private transcriptRows;
+    private render;
+}