@itookit/dsht 0.3.8 → 0.5.2

package/dist/controller/controller.d.ts

@@ -1,33 +1,211 @@
-/** Application facade: composes the connection, session, catalog and cost domains. */
 import { Client } from '../transport/client.ts';
-import { type Json, type ObjectValue } from '../transport/wire.ts';
+import { type ObjectValue } from '../transport/wire.ts';
+import type { HostEvent } from '../transport/events.ts';
 import { type HistoryLimits } from '../session/memory.ts';
+import { type SessionRender } from '../session/history.ts';
 import { SessionController } from '../session/controller.ts';
 import { CatalogController } from '../catalog/controller.ts';
-import type { Telemetry } from '../session/telemetry.ts';
+import type { TelemetryReader } from '../session/telemetry.ts';
 import type { Transcript } from '../session/transcript.ts';
 import type { CostLedger } from '../cost/ledger.ts';
 import { CostController } from '../cost/controller.ts';
 import { ConnectionController, type ConnectionListener } from './connection.ts';
 import { MemoryLog } from './memory-log.ts';
+import { TraceLog } from './trace-log.ts';
+import { PromptStore } from './prompts.ts';
+import { type LoopLimits, type LoopProtocol } from './loop.ts';
+import type { VerifierPort } from './verifier.ts';
+import type { ClientActivity, ForegroundKind, ForegroundSnapshot, LoopProgress, LoopRecord, OutputSource, PeekSnapshot } from '../contracts.ts';
+import { SessionPeek } from '../session/peek.ts';
 import { type ControllerStore, type State } from '../state.ts';
 import { ShellController } from '../shell/index.ts';
-import type { HistorySearch, RemovalTarget } from '../session/types.ts';
-import type { ComposerState, InteractionState, ModelState, OptionState, PanelState, ReferenceState, ViewState } from '../session/info.ts';
+import type { HistorySearch, AnswerValue, RemovalTarget } from '../session/types.ts';
+import type { SavedPrompt } from '../contracts.ts';
+import type { FileReference } from '../session/references.ts';
+import type { InteractionState, OptionState } from '../session/info.ts';
 import type { Reasoning } from '../session/history.ts';
+/** Mutating operations: foreground work, local edits, and control cancellation with its own admission. */
+export interface Actions {
+    /** Claim the single foreground slot for work the front end orchestrates itself (paging, loading).
+     *
+     * The controller owns the slot, the abort controller and the identity; the front end only supplies
+     * the work and renders `queries.foreground`. Returns undefined when the client is busy with another
+     * operation or the client has stopped. Admitted work keeps its result/error on cancellation.
+     */
+    foreground<T>(kind: ForegroundKind, label: string, work: (signal: AbortSignal) => Promise<T>, wait?: boolean): Promise<T | undefined>;
+    /** Cancel the operation that owns the slot; false when none is running. */
+    cancelForeground(): boolean;
+    /** Open one output source read-only, at full screen; unknown ids are ignored. */
+    openPeek(id: string): void;
+    /** Close the read-only view and release whatever it was following. */
+    closePeek(): void;
+    switchWorkspace(workspaceId?: string): Promise<boolean>;
+    switchSession(query?: string): Promise<boolean>;
+    selectSession(sessionId: string): Promise<boolean>;
+    createWorkspace(path: string): Promise<boolean>;
+    createSession(): Promise<boolean>;
+    /** Create a named session without selecting it; used by a forked verifier. */
+    createVerifierSession(title: string): Promise<string | undefined>;
+    /** Stop a verifier session's turn on the host without selecting it. */
+    cancelVerifierSession(sessionId: string): Promise<boolean>;
+    showPicker(screen: 'workspaces' | 'sessions'): Promise<boolean>;
+    removeTarget(target: RemovalTarget): Promise<boolean>;
+    removalTarget(kind: 'workspace' | 'session', query: string): Promise<RemovalTarget | undefined>;
+    waitForHistory(signal: AbortSignal): Promise<boolean>;
+    searchSessions(query: string, workspaceOnly: boolean, signal: AbortSignal): Promise<{
+        items: ObjectValue[];
+        hasMore: boolean;
+    } | undefined>;
+    searchHistory(query: string, signal: AbortSignal): Promise<HistorySearch | undefined>;
+    prompt(text: string): Promise<boolean>;
+    /** Clear this client's HANDOFF.md, then ask the agent to write a fresh handoff there. */
+    handoff(): Promise<boolean>;
+    /** Start any client-driven scored loop and send its first step. */
+    startLoop(protocol: LoopProtocol, limits: LoopLimits): Promise<boolean>;
+    /** Stop a running loop; the terminal progress stays visible for the reader. */
+    stopLoop(): void;
+    /** Drop a finished run's progress line; a run that is still active is left alone. */
+    clearLoopResult(): void;
+    /** Answer a paused run: re-judge the current artifact with what the operator supplied. */
+    answerLoop(text: string): Promise<boolean>;
+    cancelTurn(): Promise<boolean>;
+    answer(value: AnswerValue): Promise<boolean>;
+    /** Answer the current sub-question of the pending set, advancing the waterfall or sending it. */
+    answerQuestion(input?: {
+        selected?: readonly string[];
+        custom?: string;
+    }): Promise<boolean>;
+    approve(allowed: boolean): Promise<boolean>;
+    dismissQuestion(): Promise<boolean>;
+    /** Repeated keys share one cancellation; it reports exit eligibility itself. */
+    interrupt(force?: boolean): Promise<boolean>;
+    older(signal?: AbortSignal, transcript?: Transcript): Promise<boolean>;
+    openHistory(target: number, signal: AbortSignal): Promise<boolean>;
+    historyThrough(target: number | 'first', signal: AbortSignal): Promise<boolean>;
+    removeQueued(itemId: string): Promise<boolean>;
+    /** Local shortcut prompts: no connection and no busy envelope, since they never reach the host. */
+    savePrompt(text: string): Promise<boolean>;
+    updatePrompt(id: string, text: string): Promise<boolean>;
+    deletePrompt(id: string): Promise<boolean>;
+    command(line: string, signal: AbortSignal): Promise<string | undefined>;
+    exportLog(path: string | undefined, signal: AbortSignal): Promise<string | undefined>;
+    exportHtml(path: string | undefined, signal: AbortSignal): Promise<string | undefined>;
+    selectModel(provider: string, model: string, reasoningEffort?: string): Promise<boolean>;
+    modelCatalog(): Promise<ObjectValue | undefined>;
+    refreshCosts(signal?: AbortSignal): Promise<boolean>;
+    /** Local, immediate setters: no request, so they keep the synchronous contract. */
+    loadPresetNames(): void;
+    /** Drop the internal last failure, once the fact has been reported elsewhere. */
+    clearFailure(): void;
+    enterPath(): void;
+    pickWorkspace(workspaceId?: string): void;
+    /** Leave a picker and return to the selected conversation; false when none is selected. */
+    showChat(): boolean;
+    showLatest(): void;
+    pinHistory(pinned: boolean): void;
+    setAnswers(answers: Record<string, AnswerValue['answers']>): void;
+    setOption(option?: OptionState): void;
+    setApproval(approval?: InteractionState['approval']): void;
+    recordRecall(value: string): void;
+    resetRecall(): void;
+    refillRecall(): boolean;
+    heapSnapshot(tag?: string): string;
+}
+/** Read-only operations the UI drives; none of them changes observable state. */
+export interface Queries {
+    readonly running: boolean;
+    /** Turns the selected session has finished since this client connected. */
+    readonly turnsCompleted: number;
+    /** Whether a forked verifier is available to score rounds. */
+    readonly forkedVerification: boolean;
+    /** Whether this client's own reply block may decide an attempt: no verifier, or the fallback is on. */
+    readonly selfScoring: boolean;
+    /** Whether this connection generation finished its startup work and is safe to drive. */
+    readonly connectionSettled: boolean;
+    readonly sessionName: string | undefined;
+    readonly sessionMode: string | undefined;
+    readonly workingSince: number | undefined;
+    readonly visibleSessions: ObjectValue[];
+    readonly record: Transcript;
+    readonly window: Transcript | undefined;
+    readonly interaction: InteractionState;
+    readonly telemetry: TelemetryReader;
+    readonly recallAtOldest: boolean;
+    readonly recallLength: number;
+    readonly recallHasOlder: boolean;
+    /** Shortcut prompts the operator saved, oldest first. */
+    readonly prompts: readonly SavedPrompt[];
+    /** Live progress of the selected session's design review, when one has run. */
+    readonly loop: LoopProgress | undefined;
+    /** What the client is working on now, already merged across the host turn and any running loop. */
+    readonly activity: ClientActivity | undefined;
+    /** The one operation that owns the client, when one does; the view renders its label and clock. */
+    readonly foreground: ForegroundSnapshot | undefined;
+    /** Every readable output source this client knows: verifier sessions, `!` runs, host children. */
+    readonly sources: readonly OutputSource[];
+    /** The read-only view's content, when one is open; undefined while it is closed. */
+    readonly peek: PeekSnapshot | undefined;
+    /** Every `loop.yaml` record, so the picker can offer names and their defaults without a lookup. */
+    readonly loopRecords: readonly LoopRecord[];
+    /** Why the saved prompts could not be read, when the file was malformed. */
+    readonly promptsError: string | undefined;
+    pendingCounts(): ReadonlyMap<string, number>;
+    recall(direction: -1 | 1, current: string): string;
+    references(query: string, signal: AbortSignal): Promise<FileReference[]>;
+    /** Plain rows and offsets for one laid-out record. */
+    render(input: {
+        transcript: Transcript;
+        width: number;
+        folds: ReadonlySet<number>;
+        liveReasoning: Reasoning;
+    }): SessionRender;
+}
+/** Everything one `Controller` needs, named so a new capability never shifts an argument position.
+ *
+ * `base` is the only required field: a local or offline client still has an address to show, while
+ * every other capability — authentication, billing, budgets, local shell, shortcut prompts — is
+ * opted into by supplying its own field.
+ */
+export interface ControllerOptions {
+    /** Host base URL. */
+    base: string;
+    /** Token for the first authentication; absent when a saved cookie already authenticates. */
+    token?: string;
+    /** Session to open once connected, instead of starting on the picker. */
+    initialSession?: string;
+    /** Builds one connection client; defaults to a plain `Client` for `base`. */
+    makeClient?: () => Client;
+    /** Authenticates one connection client; defaults to the supplied token. */
+    authenticate?: (client: Client) => Promise<void>;
+    /** Billing ledger; absent disables every cost feature. */
+    costs?: CostLedger;
+    /** History retention budgets. */
+    historyLimits?: HistoryLimits;
+    /** Runtime memory log path; absent disables the log. */
+    memoryLogPath?: string;
+    /** Connection, screen and selection trace path; absent disables the log. */
+    tracePath?: string;
+    /** Directory this client runs in, offered as a workspace the host has not registered. */
+    localDirectory?: string;
+    /** Whether `!` may run local commands; the CLI disables it with `--no-shell`. */
+    shellEnabled?: boolean;
+    /** File holding the operator's shortcut prompts; absent keeps them in memory for this run. */
+    promptsPath?: string;
+    /** Independent verifier for scored rounds; absent keeps verification inside the reviewed session. */
+    verifier?: VerifierPort;
+    /** Allow a reply block to decide when the verifier is unavailable; the progress line says so. */
+    allowSelfFallback?: boolean;
+    /** Client-side root for verdict files; defaults to the workspace this client runs in. */
+    verdictRoot?: string;
+    /** Whole-run budget in milliseconds; when it expires the run stops as `deadline`. */
+    deadlineMs?: number;
+}
 /** Application facade over the domain controllers; the UI owns only this object.
  *
  * State lives here, connection generations live in `connection`, the selected session and its
  * history live in `session`, model metadata lives in `catalog`, and billing lives in `cost`.
  */
 export declare class Controller implements ControllerStore, ConnectionListener {
-    readonly base: string;
-    private readonly initialSession?;
-    readonly costs?: CostLedger | undefined;
-    readonly historyLimits: HistoryLimits;
-    readonly memoryLogPath?: string | undefined;
-    /** Directory this client runs in, offered as a workspace when the host has not registered it. */
-    readonly localDirectory: string;
     state: State;
     /** Physical connection, retry loop and projection store. */
     readonly connection: ConnectionController;
@@ -39,23 +217,58 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     readonly cost: CostController | undefined;
     /** Bounded runtime memory samples; present only when a log path was supplied. */
     readonly memoryLog: MemoryLog | undefined;
+    /** Bounded connection, screen and selection trace; present only when a path was supplied. */
+    readonly trace: TraceLog | undefined;
+    /** Shortcut prompts the operator saved; in memory for this run when no path was supplied. */
+    readonly promptStore: PromptStore;
+    /** Finished turns of the selected session, so a waiter never has to sample a cached flag. */
+    private completedTurns;
+    /** Sessions the host reported busy, so a lone idle frame cannot claim a finished turn. */
+    private readonly busySessions;
+    /** Loop execution owns all verifier, settling and deadline state. */
+    private readonly loops;
     /** Local `!` commands, run on this machine and shown inline in the transcript. */
     readonly shell: ShellController;
+    /** Mutating surface the UI drives. */
+    readonly actions: Actions;
+    /** Read-only surface the UI drives. */
+    readonly queries: Queries;
+    /** Host base URL this client talks to. */
+    readonly base: string;
+    /** Billing ledger supplied at construction, when any. */
+    readonly costs: CostLedger | undefined;
+    /** History retention budgets in force. */
+    readonly historyLimits: HistoryLimits;
+    /** Runtime memory log path, when one was configured. */
+    readonly memoryLogPath: string | undefined;
+    /** Directory this client runs in. */
+    readonly localDirectory: string;
+    /** Session opened at startup, when one was named. */
+    private readonly initialSession;
     private readonly observers;
     private selector;
-    constructor(base: string, token: string | undefined, initialSession?: string | undefined, makeClient?: () => Client, authenticate?: (client: Client) => Promise<void>, costs?: CostLedger | undefined, historyLimits?: HistoryLimits, memoryLogPath?: string | undefined, 
-    /** Directory this client runs in, offered as a workspace when the host has not registered it. */
-    localDirectory?: string, 
-    /** Whether `!` may run local commands; the CLI disables it with `--no-shell`. */
-    shellEnabled?: boolean);
+    private connectionSettled;
+    /** Startup defaults apply once; subsequent generations restore the operator's selection. */
+    private initialized;
+    /** Counter behind `commandId`, so every executed line has one identifier in begin and end. */
+    private commandSeq;
+    /** Scheduling and cancellation are owned independently of domain operations. */
+    private readonly foregroundSlot;
+    /** Read-only follower for the full-screen view; it borrows the connection and never selects. */
+    readonly peek: SessionPeek;
+    /** Sources this client created, keyed by session id; the host cannot record that lineage itself. */
+    private readonly createdSources;
+    /** The source the read-only view is showing, when one is open. */
+    private peekId;
+    constructor(options: ControllerOptions);
     /** React-compatible state subscription. */
     subscribe: (listener: () => void) => (() => void);
     /** Snapshot identity changes only when the controller publishes. */
     snapshot: () => State;
     /** Current projection store; replaced at each connection generation. */
-    get telemetry(): Telemetry;
+    private get telemetry();
     /** Record of the selected session; the one strong owner lives in `State.session`. */
-    get record(): Transcript;
+    private get record();
     /** @returns The current selector generation. */
     selection(): number;
     /** Advance the selector generation when the selected workspace or session changes. */
@@ -63,7 +276,46 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     /** Publish a state patch, re-deriving the visible pending interactions.
      * @param patch - Fields to replace on the current state.
      */
+    /** Whether an operation owns the client's foreground slot right now.
+     * @returns True while an operation is running.
+     */
+    busy(): boolean;
     update(patch: Partial<State>): void;
+    /** Record one diagnostic event; a no-op when no trace path was configured. */
+    private traceEvent;
+    /** Record one diagnostic event from outside the controller, such as a UI-only decision.
+     *
+     * The composition root knows things this class cannot see — which record the operator highlighted,
+     * that a form was refused a name — and a start that never reaches `startLoop` is otherwise invisible
+     * in every log. Same no-op contract as the internal call.
+     * @param event - Event name, e.g. `loop-ui`.
+     * @param detail - Identifiers only; never prompt or session text.
+     */
+    traceNote(event: string, detail?: ObjectValue): void;
+    /** Mint the identifier one executed line carries through its `begin` and `end` events.
+     *
+     * Short and process-local on purpose: it exists to pair two lines of one file, not to identify a
+     * line across runs, so a monotonic counter beats a random id a reader would have to match by eye.
+     * @returns The next command id, such as `C17`.
+     */
+    nextCommandId(): string;
+    /** Record the state fields that decide which screen the reader is looking at.
+     *
+     * Every non-user transition is written here as well as at its cause, so a screen that moved
+     * without an expected reason is still visible in the trace rather than silently skipped.
+     * @param previous - State before the patch.
+     * @param next - State after the patch.
+     */
+    private traceTransition;
+    /** Bind every mutating entry point to its private implementation.
+     *
+     * Each one names the kind and label of the operation it performs, because that is now the single
+     * answer to "what owns the client right now" (§6.2): the front end renders it and cancels it, and
+     * nothing else has to know which layer started the work.
+     */
+    private buildActions;
+    /** Bind every read-only entry point; getters stay live because the values move between renders. */
+    private buildQueries;
     /** Start one retry loop, with a fresh snapshot generation after every disconnect. */
     start(): void;
     /** Cancel retries and HTTP, close the socket, and release session and catalog work. */
@@ -72,11 +324,24 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * An idle session stays untouched, and an in-flight cancellation is awaited rather than repeated.
      */
     shutdown(): Promise<void>;
-    /** Run a UI operation and expose errors without destroying the current input.
+    /** Run one mutating operation inside the client's single foreground slot.
+     *
+     * Private on purpose: the application owns the slot, so a caller never hands the controller a
+     * closure to orchestrate. Every entry of `actions` uses it, and `actions.foreground` is the one
+     * door left open for work the front end orchestrates itself.
+     * @param kind - What the operation is, for the label and the trace.
+     * @param label - Human label shown while it runs.
      * @param operation - Operation to run while the client is busy.
-     * @returns Whether the operation completed.
+     * @returns Whether the operation ran to completion.
      */
-    perform(operation: () => Promise<void>): Promise<boolean>;
+    private runAction;
+    /** Same slot, for an operation that produces a value the caller needs. */
+    private runActionValue;
+    /** Run outside the foreground slot, with the same application failure reporting.
+     * Local prompt edits need no connection; verifier cancellation uses the session control lane and
+     * must reach the host even while the foreground is busy or closed for shutdown.
+     */
+    private runImmediateAction;
     /** Read the counters one memory sample records; content never leaves as text.
      *
      * The retained transcript and the ledger are small in practice, so a sample also reads the two
@@ -98,292 +363,261 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     begin(): void;
     /** The event stream is ready and the control baseline is applied. */
     ready(): Promise<void>;
-    /** The generation ended; invalidate session work and stop the scan. */
+    /** The generation ended; invalidate session work and stop the scan.
+     *
+     * A running loop is deliberately left alone: the host keeps running the review, and the client
+     * re-selects the same session after reconnecting, so only a switch to another session ends it.
+     */
     ended(): Promise<void>;
-    /** Deliver a host waterfall to the session domain.
-     * @param frame - One decoded waterfall frame.
-     * @returns Whether the session domain retained it.
-     */
-    waterfall(frame: ObjectValue): boolean;
-    /** Drop a waterfall the host cancelled.
-     * @param eventId - Correlation id previously retained.
-     */
-    cancelled(eventId: string): void;
-    /** Apply one host running-state notification.
-     * @param sessionId - Session whose state changed.
-     * @param running - Whether the host still runs that session.
-     */
-    status(sessionId: string, running: boolean): void;
-    /** Surface a host-reported session error.
-     * @param sessionId - Session the host reported on.
-     * @param error - Error payload as delivered by the host.
-     */
-    error(sessionId: unknown, error: unknown): void;
-    /** Reload the model catalog after a host settings, credential or adapter change. */
-    invalidated(): void;
-    /** Refresh billing after a turn finished. */
-    idle(): void;
+    /** Route one normalized host event to the domain that owns it.
+     *
+     * This is the composition point: the connection knows only that an event arrived, so a feature
+     * never has to hold another feature. `false` means the host's waterfall is still unsettled.
+     * @param event - Normalized host event.
+     * @returns Whether a retained waterfall was consumed.
+     */
+    event(event: HostEvent): boolean;
     /** @returns Host running state of the selected session. */
-    get running(): boolean;
+    private get running();
     /** @returns Current session title, falling back to the list title and then the ID. */
-    get sessionName(): string | undefined;
+    private get sessionName();
     /** @returns Current agent-preset label. */
-    get sessionMode(): string | undefined;
+    private get sessionMode();
     /** @returns Epoch start of the active turn, when known. */
-    get workingSince(): number | undefined;
+    private get workingSince();
+    /** What the client is doing right now, merged across the host turn and any running loop.
+     *
+     * This is the controller's answer, not a view's guess: a turn speaks for the session while it runs,
+     * otherwise a live loop speaks for itself with its own sub-state and clock, and neither means idle.
+     * @returns The activity, or undefined when nothing is in flight.
+     */
+    private get activity();
     /** @returns Sessions accounted to the selected workspace, minus archived identities. */
-    get visibleSessions(): ObjectValue[];
+    private get visibleSessions();
+    /** Every readable output source, newest activity first.
+     *
+     * Three origins feed one list, because a reader asking "what is that session" does not care which
+     * layer knows about it: sessions this client created (the host cannot record that link), local `!`
+     * runs it already holds, and host-created subagent children, whose only lineage is their list row.
+     * A client-created source wins over the list row for the same session, since it says more.
+     * @returns Sources to offer, running ones first.
+     */
+    private outputSources;
+    /** Register a session this client created for a verifier, so the list can explain it. */
+    private createVerifierSession;
+    /** Mark a source this client created as finished, keeping it readable. */
+    private endSource;
+    /** Open one source read-only at full screen; a session source starts following it. */
+    private openPeek;
+    /** Close the read-only view and release whatever it followed. */
+    private closePeek;
+    /** Release the view without publishing; the caller is already inside an update. */
+    private dropPeek;
+    /** What the read-only view renders, or undefined while it is closed. */
+    private peekSnapshot;
     /** @returns Unanswered interactions by session, for the state each list row reports. */
-    pendingCounts(): ReadonlyMap<string, number>;
+    private pendingCounts;
     /** Load the optional preset roster once per connection. */
-    loadPresetNames(): void;
-    /** @returns Host model routes and adapter-owned reasoning choices. */
-    modelCatalog(): Promise<ObjectValue>;
-    /** Select the next request's model.
-     * @param provider - Host provider route ID.
-     * @param model - Exact model ID.
-     * @param reasoningEffort - Optional adapter-owned effort ID.
-     */
-    selectModel(provider: string, model: string, reasoningEffort?: string): Promise<void>;
+    private loadPresetNames;
     /** Stop the selected turn, or allow exit only while idle.
      * @param force - Send an explicit cancellation even when the cached running flag is idle.
      * @returns True when the caller may exit.
      */
-    interrupt(force?: boolean): Promise<boolean>;
+    private interrupt;
     /** One-line estimate of the selected session's cost, or `?` while the ledger has no entry for it. */
-    get sessionCostText(): string;
     /** Keep history stable while the user reads, searches, or expands it.
      * @param pinned - Whether the main transcript is being read away from its tail.
      */
-    pinHistory(pinned: boolean): void;
+    private pinHistory;
+    /** @returns The detached history window the reader opened, if any. */
+    private get window();
+    /** Show a detached history window, releasing the one it replaces.
+     * @param window - Record to display, or undefined to return to the live transcript.
+     */
     /** Recall one step through the selected session's prompt index; never touches the network.
      * @param direction - Negative for older input, positive for newer input.
      * @param current - Composer content before recall began, restored at the newest position.
      * @returns The recalled prompt, or the unsent draft.
      */
-    recall(direction: -1 | 1, current: string): string;
+    private recall;
     /** Remember a locally submitted command, which never becomes a durable session record.
      * @param value - Submitted command text.
      */
-    recordRecall(value: string): void;
+    private recordRecall;
     /** Leave recall navigation because the composer was edited or replaced. */
-    resetRecall(): void;
+    private resetRecall;
     /** Whether recall is parked on the oldest prompt the session retains. */
-    get recallAtOldest(): boolean;
+    private get recallAtOldest();
     /** How many prompts the selected session retains for recall. */
-    get recallLength(): number;
+    private get recallLength();
     /** Whether an older prompt is reachable, in the loaded window or on the host. */
-    get recallHasOlder(): boolean;
+    private get recallHasOlder();
     /** Recover older prompts from the loaded window before spending a page request.
      * @returns Whether any older prompt was recovered.
      */
-    refillRecall(): boolean;
-    /** Composer draft, caret and parked draft of the selected session. */
-    get composer(): ComposerState;
-    /** Replace the composer text and caret.
-     * @param draft - New text.
-     * @param cursor - Caret column; defaults to the end of the text.
-     */
-    setComposer(draft: string, cursor?: number): void;
-    /** Move the caret without changing the text.
-     * @param cursor - Caret column.
-     */
-    setComposerCursor(cursor: number): void;
-    /** Move a non-empty draft aside while a dialog owns the keyboard. */
-    parkComposer(): void;
-    /** Give a parked draft back once no dialog needs the keyboard. */
-    restoreComposer(): void;
-    /** How the selected session's record is being read right now. */
-    get view(): ViewState;
-    /** Show a detached history window, releasing the one it replaces.
-     * @param window - Record to display, or undefined to return to the live transcript.
-     */
-    setViewWindow(window?: Transcript): void;
-    /** Move the reader's position inside the displayed record.
-     * @param scroll - Rows scrolled back from the live end.
-     */
-    setScroll(scroll: number): void;
-    /** Replace the set of expanded reasoning blocks.
-     * @param folds - Sequences to expand beyond the default fold.
-     */
-    setFolds(folds: ReadonlySet<number>): void;
-    /** Set the fold mode of the live attempt's completed reasoning.
-     * @param reasoning - `row` to fold, `full` to keep the streamed text.
-     */
-    setLiveReasoning(reasoning: Reasoning): void;
+    private refillRecall;
     /** Local answer state for the selected session's pending waterfalls. */
-    get interaction(): InteractionState;
+    private get interaction();
     /** Replace the partly collected answers, keyed by waterfall event id.
      * @param answers - Answers collected so far, by event id.
      */
-    setAnswers(answers: Record<string, ObjectValue[]>): void;
+    private setAnswers;
+    /** Clear the internal last failure; a no-op when there is none. */
+    private clearFailure;
     /** Replace the pending question's option keyboard state.
      * @param option - Highlighted option, toggled labels and free-text mode; undefined clears it.
      */
-    setOption(option?: OptionState): void;
+    private setOption;
     /** Replace the pending approval's selected row.
      * @param approval - Selected approval row; undefined clears the highlight.
      */
-    setApproval(approval?: InteractionState['approval']): void;
-    /** Composer-adjacent `@` reference menu state. */
-    get reference(): ReferenceState;
-    /** Highlight one row of the open reference menu.
-     * @param index - Row index into the current matches.
-     */
-    setReferenceIndex(index: number): void;
-    /** Remember the draft that dismissed the reference menu.
-     * @param draft - Composer text at dismissal, or undefined to allow the menu again.
-     */
-    setReferenceDismissed(draft?: string): void;
-    /** Panels the selected session has open. */
-    get panels(): PanelState;
-    /** Show or hide the reasoning panel.
-     * @param open - Whether `/think` is open.
-     */
-    openThoughts(open: boolean): void;
-    /** Show or hide the pending-input panel.
-     * @param open - Whether `/queue` is open.
-     */
-    openQueue(open: boolean): void;
-    /** Show the model dialog at one step, or close it.
-     * @param model - Catalog plus the provider or model being inspected; undefined closes the dialog.
-     */
-    setModelPanel(model?: ModelState): void;
-    /** Show the history or content-search dialog, or close it.
-     * @param history - Query, content-search mode and matches; undefined closes the dialog.
-     */
-    setHistoryPanel(history?: PanelState['history']): void;
-    /** Show the host session-search results, or close them.
-     * @param search - Query, results and truncation flag; undefined closes the dialog.
-     */
-    setSearchPanel(search?: PanelState['search']): void;
+    private setApproval;
     /** Refresh all HTTP-visible sessions without changing the selected conversation.
      * @param signal - Optional cancellation for an explicit /cost refresh.
      */
-    refreshCosts(signal?: AbortSignal): Promise<void>;
+    private refreshCosts;
     /** Refresh both lists from the host, then show the requested picker.
      * @param screen - Picker to display after the refresh.
      */
-    showPicker(screen: 'workspaces' | 'sessions'): Promise<void>;
+    private showPicker;
     /** Resolve a removal command to one reviewable object.
      * @param kind - Workspace registration removal or session archival.
      * @param query - Exact name, ID, or unambiguous ID prefix.
      * @returns The fixed identity and display details for confirmation.
      */
-    removalTarget(kind: 'workspace' | 'session', query: string): Promise<RemovalTarget>;
+    private removalTarget;
     /** Apply a confirmed removal or verified empty-session archival.
      * @param target - Exact workspace or session identity reviewed by the user.
      */
-    removeTarget(target: RemovalTarget): Promise<void>;
+    private removeTarget;
     /** Pick a workspace, or use all sessions when the identity is omitted.
      * @param workspaceId - Workspace to select, if any.
      */
-    pickWorkspace(workspaceId?: string): void;
+    private pickWorkspace;
+    /** Leave a picker and return to the selected conversation, without reloading it.
+     * @returns Whether there was a selected conversation to return to.
+     */
+    private showChat;
     /** Open a workspace picker, or resolve a workspace target.
      * @param query - Workspace target, if any.
      */
-    switchWorkspace(query?: string): Promise<void>;
+    private switchWorkspace;
     /** Guide session selection, list all sessions with `all`, or resolve a target.
      * @param query - Session target, `all`, or nothing for the guided picker.
      */
-    switchSession(query?: string): Promise<void>;
+    private switchSession;
     /** Prompt for a host path without starting a local agent. */
-    enterPath(): void;
+    private enterPath;
     /** Register a host directory and move to its session picker.
      * @param path - Absolute directory path on the host.
      */
-    createWorkspace(path: string): Promise<void>;
+    private createWorkspace;
     /** Create a session in the selected workspace. */
-    createSession(): Promise<void>;
+    private createSession;
     /** Replace the selected transcript and follow the session.
      * @param sessionId - Session to follow.
      */
-    selectSession(sessionId: string): Promise<void>;
+    private selectSession;
     /** Wait for the selected follow snapshot.
      * @param signal - Cancels waiting without closing the session.
      */
-    waitForHistory(signal: AbortSignal): Promise<void>;
+    private waitForHistory;
     /** Search host session results.
      * @param query - Literal message text.
      * @param workspaceOnly - Restrict hits to the selected workspace.
      * @param signal - Cancels the HTTP search.
      * @returns Session snippets and the global truncation flag.
      */
-    searchSessions(query: string, workspaceOnly: boolean, signal: AbortSignal): Promise<{
-        items: ObjectValue[];
-        hasMore: boolean;
-    }>;
+    private searchSessions;
     /** Search host paths for the composer's `@` completion.
      * @param query - Path text after @.
      * @param signal - Cancels an obsolete lookup.
      * @returns Validated candidates in host order.
      */
-    references(query: string, signal: AbortSignal): Promise<import("../session/references.ts").FileReference[]>;
+    private references;
     /** Execute a human command directly, outside the model prompt queue.
      * @param line - Complete slash command, including arguments.
      * @param signal - Cancels the request while the host performs compaction.
      * @returns The host's successful command result text.
      */
-    command(line: string, signal: AbortSignal): Promise<string>;
+    private command;
     /** Remove one host-owned pending input.
      * @param itemId - Queue occurrence identity from session/control.
      */
-    removeQueued(itemId: string): Promise<void>;
+    private removeQueued;
     /** Export the selected host log to a new local ZIP file.
      * @param path - Optional local destination; existing files are never overwritten.
      * @param signal - Cancels the download and removes an incomplete file.
      * @returns Absolute saved filename.
      */
-    exportLog(path: string | undefined, signal: AbortSignal): Promise<string>;
+    private exportLog;
     /** Save loaded Markdown, diagrams and math as offline HTML.
      * @param path - Optional filename; existing files are not replaced.
      * @param signal - Cancels the write.
      * @returns Absolute saved filename.
      */
-    exportHtml(path: string | undefined, signal: AbortSignal): Promise<string>;
+    private exportHtml;
     /** Write a V8 heap snapshot into this client's working directory; the write pauses the client.
      * @param tag - Sampling-point label naming the file, such as `after-stress`.
      * @returns Absolute path of the written snapshot.
      */
-    heapSnapshot(tag?: string): string;
+    private heapSnapshot;
     /** Admit text once as steering while running, or a new turn while idle.
+     *
+     * Text the operator typed ends an automated review: the loop must not race a human for the turn,
+     * and the reply it would parse is no longer the reply to its own prompt.
      * @param text - Composed prompt text.
      */
-    prompt(text: string): Promise<void>;
+    private prompt;
+    /** Clear this client's stale handoff file, then ask the agent to write a new one.
+     *
+     * The deletion happens first and on this machine, so a handoff that never gets written cannot be
+     * mistaken for the previous one. The request itself is an ordinary turn: it steers a running
+     * agent and starts an idle one, exactly like submitted text.
+     */
+    private handoff;
     /** Cancel the active turn; pending queue items remain host-owned. */
-    cancelTurn(): Promise<void>;
+    private cancelTurn;
     /** Add a page before the retained window.
      * @param signal - Cancels local paging without interrupting the remote agent.
      * @param transcript - Transcript to extend; defaults to the live one.
      */
-    older(signal?: AbortSignal, transcript?: Transcript): Promise<void>;
+    private older;
     /** Search the loaded history page by page.
      * @param query - Literal, case-insensitive text including folded reasoning.
      * @param signal - Cancels HTTP and processing without cancelling the agent.
      * @returns Newest-first bounded summaries and an explicit truncation flag.
      */
-    searchHistory(query: string, signal: AbortSignal): Promise<HistorySearch>;
-    /** Load a separate small window ending at a search target.
-     * @param target - Durable message sequence to display.
-     * @param signal - Cancels the target-page request.
-     * @returns A caller-owned historical window that must be disposed when closed.
-     */
-    historyAt(target: number, signal: AbortSignal): Promise<Transcript>;
+    private searchHistory;
+    /** Plain rows and offsets for one laid-out record; the projection stays in the session domain. */
+    private render;
     /** Load the prefix required for an explicit history jump.
      * @param target - Visible record sequence, or first for the oldest available history.
      * @param signal - Cancels local paging without interrupting the remote agent.
      */
-    historyThrough(target: number | 'first', signal: AbortSignal): Promise<void>;
+    private historyThrough;
     /** Answer the oldest selected-session interaction, after explicit user action.
-     * @param value - Structured answer value or approval outcome.
+     * @param value - Structured answer collected by the UI.
      */
-    answer(value: Json): Promise<void>;
+    private answer;
+    /** Answer the current sub-question of the pending set, advancing the waterfall or sending it.
+     *
+     * The waterfall is interaction state of the session — which sub-question is current follows from the
+     * answers collected so far, and the ticked labels live in the option state — so it belongs here
+     * rather than in a front end. Both entry points then complete a question the same way: a line the
+     * operator typed as an answer, and the option keys.
+     * @param input - Labels chosen for this sub-question, or free text the operator typed.
+     * @returns True once the answer was recorded or sent; a host refusal throws, leaving the collected
+     *   answers in place so the same submission can be retried.
+     */
+    private answerQuestion;
     /** Approve or reject the pending approval request.
      * @param allowed - Whether the request is approved once.
      */
-    approve(allowed: boolean): Promise<void>;
+    private approve;
     /** Dismiss the whole pending question set without answering it, as the Web close button does. */
-    dismissQuestion(): Promise<void>;
+    private dismissQuestion;
 }
-export type { HistorySearch, RemovalTarget } from '../session/types.ts';
+export type { HistorySearch, RemovalTarget, AnswerValue, PendingInteraction } from '../session/types.ts';
+export type { SavedPrompt } from '../contracts.ts';
 export type { State } from '../state.ts';