@itookit/dsht 0.3.8 → 0.5.2

package/dist/session/controller.d.ts

@@ -1,13 +1,17 @@
 import type { HostAccess } from '../transport/host.ts';
 import { type Json, type ObjectValue } from '../transport/wire.ts';
-import type { ControllerStore, State } from '../state.ts';
+import type { SessionStore } from './state.ts';
+import { type SessionRender } from './history.ts';
 import type { HistoryLimits } from './memory.ts';
 import { type FileReference } from './references.ts';
-import { type ComposerState, type InteractionState, type ModelState, type OptionState, type PanelState, type ReferenceState, type ViewState } from './info.ts';
+import type { Telemetry } from './telemetry.ts';
+import { type InteractionState, type OptionState } from './info.ts';
+import type { MutationAdmission } from './mutation-gate.ts';
 import type { Reasoning } from './history.ts';
 import { Transcript } from './transcript.ts';
 import type { ConnectionView } from './connection-view.ts';
-import type { HistorySearch, RemovalTarget } from './types.ts';
+import type { HistorySearch, AnswerValue, PendingInteraction, RemovalTarget } from './types.ts';
+import { type ControlFrame, type HostEvent } from '../transport/events.ts';
 /** Owns the selected session: its follow stream, transcript, history window and interactions. */
 export declare class SessionController {
     private readonly store;
@@ -15,45 +19,74 @@ export declare class SessionController {
     private readonly connection;
     private readonly historyLimits;
     private follow;
-    private interactions;
+    private readonly history;
+    private readonly interactions;
+    private readonly navigation;
+    /** Reading protection: reclamation pauses while the reader is away from the live end. */
+    private historyPinned;
+    /** Host runtime mirrors for every session this connection has seen. */
+    private readonly runtime;
     /** Cancels the background prompt backfill of the previous selection. */
-    private promptBackfill?;
+    private readonly promptBackfill;
     /** Prompts of sessions this process has already read, so re-opening one costs no page request. */
     private readonly promptCache;
-    /** Prompt index, composer and reading view of the selected session; the instance `State.session` exposes. */
+    /** Prompt index, record, history window and interaction state of the selected session. */
     private get info();
     private get prompts();
     private stoppingSession?;
     private interruptTask;
     private admission;
-    constructor(store: ControllerStore, host: HostAccess, connection: ConnectionView, historyLimits: HistoryLimits);
+    /** Admission order of this session's writes, so two concurrent decisions cannot interleave. */
+    private readonly mutations;
+    constructor(store: SessionStore, host: HostAccess, connection: ConnectionView, historyLimits: HistoryLimits, report?: (admission: MutationAdmission) => void);
     /** Host running state covers model generation, tools, and waits between assistant attempts. */
     get running(): boolean;
     /** Current title projection, falling back to the list title and then the session ID. */
     get sessionName(): string | undefined;
     /** Current agent-preset name, matching the web header's built-in labels and custom metadata. */
-    get sessionMode(): string | undefined;
+    sessionMode(presets?: readonly ObjectValue[]): string | undefined;
     /** Epoch start from the retained turn log, or when this client first observed the run. */
     get workingSince(): number | undefined;
     /** Present only sessions explicitly accounted to the selected workspace. */
     get visibleSessions(): ObjectValue[];
     /** Whether a turn, cancellation or prompt admission is still in flight. */
     get active(): boolean;
+    /** @returns The detached history window the reader opened, if any. */
+    get window(): Transcript | undefined;
+    /** 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;
+    /** @returns Host projection store of the current generation, owned by this session's runtime. */
+    get telemetry(): Telemetry;
+    /** Lay out one record for a terminal width.
+     *
+     * The projection engine stays in this domain; the UI receives plain rows and offsets instead of
+     * importing it, and `Reasoning` for committed messages is always the folded default.
+     */
+    render(input: {
+        transcript: Transcript;
+        width: number;
+        folds: ReadonlySet<number>;
+        liveReasoning: Reasoning;
+    }): SessionRender;
+    /** Apply one normalized control frame to this session's runtime. */
+    acceptControl(frame: ControlFrame): void;
     /** Whether reading protects the loaded window, suspending history reclamation. */
     get pinned(): boolean;
     /** Drop generation-scoped state before a new connection generation begins. */
     beginGeneration(): void;
     /** Invalidate in-flight work and drop transient interactions when a generation ends. */
     endGeneration(): void;
-    /** Wait for an in-flight cancellation so shutdown leaves nothing running. */
+    /** Wait for cancellation and foreground history tasks before releasing their records. */
     settle(): Promise<void>;
     /** Release the selected transcript and its layout caches. */
     release(): void;
     /** Pending interactions for the selected chat session, derived independently of frame order.
-     * @param state - State being published.
+     * @param sessionId - Session whose pending interactions are being published.
      * @returns Retained question and approval frames for that session.
      */
-    pendingFor(state: State): ObjectValue[];
+    pendingFor(sessionId: string | undefined): PendingInteraction[];
     /** Unanswered interactions by session, so a list can show who is waiting without opening them.
      *
      * The host delivers approval and question waterfalls for every session on one stream, and this
@@ -63,11 +96,11 @@ export declare class SessionController {
      * @returns One count per session holding at least one unanswered interaction.
      */
     pendingCounts(): ReadonlyMap<string, number>;
-    /** Retain a recognized host waterfall; unknown events stay with the connection to delegate.
-     * @param frame - One decoded waterfall frame.
-     * @returns Whether this domain retained the frame for an answer.
+    /** Retain a recognized host interaction; anything else belongs to the connection to delegate.
+     * @param event - One normalized host event.
+     * @returns Whether this domain retained the event for an answer.
      */
-    waterfall(frame: ObjectValue): boolean;
+    accept(event: HostEvent): boolean;
     /** Drop a waterfall the host cancelled.
      * @param eventId - Correlation id previously retained.
      */
@@ -79,9 +112,9 @@ export declare class SessionController {
     status(sessionId: string, running: boolean): void;
     /** Surface a host-reported error for the selected session.
      * @param sessionId - Session the host reported on.
-     * @param error - Error payload as delivered by the host.
+     * @param error - Already-normalized error text.
      */
-    reportError(sessionId: unknown, error: unknown): void;
+    reportError(sessionId: string, error: string): void;
     /** Stop the selected turn, or allow exit only while idle. Repeated keys share one request.
      * @param force - Send an explicit cancellation even when the cached running flag is idle.
      * @returns True when the caller may exit; cancellation failures retain the client.
@@ -96,7 +129,16 @@ export declare class SessionController {
     /** 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>;
+    showPicker(screen: 'workspaces' | 'sessions', signal?: AbortSignal): Promise<void>;
+    /** Refresh navigation data without taking the reader to another screen. */
+    refreshLists(): Promise<void>;
+    /** Return to the selected conversation without re-selecting it.
+     *
+     * A picker opened over a conversation is a detour: leaving it must not re-subscribe, reload the
+     * transcript or lose the reading position, so this only changes which screen is shown.
+     * @returns Whether there was a selected conversation to return to.
+     */
+    showChat(): boolean;
     /** Resolve a removal command to one reviewable object without changing the selection.
      * @param kind - Workspace registration removal or session archival.
      * @param query - Exact name, ID, or unambiguous ID prefix.
@@ -114,11 +156,11 @@ export declare class SessionController {
     /** Open a workspace picker, or resolve a workspace by ID, exact title/path, or unique ID prefix.
      * @param query - Workspace target, if any.
      */
-    switchWorkspace(query?: string): Promise<void>;
+    switchWorkspace(query?: string, signal?: AbortSignal): Promise<void>;
     /** Guide workspace selection, list all sessions with `all`, or resolve an exact session target.
      * @param query - Session target, `all`, or nothing for the guided picker.
      */
-    switchSession(query?: string): Promise<void>;
+    switchSession(query?: string, signal?: AbortSignal): Promise<void>;
     /** Prompt for a host path without starting a local agent. */
     enterPath(): void;
     /** Adopt the workspace whose registered path contains the directory this client runs in.
@@ -133,13 +175,31 @@ export declare class SessionController {
     /** Register a host directory and move to its session picker.
      * @param path - Absolute directory path on the host.
      */
-    createWorkspace(path: string): Promise<void>;
+    createWorkspace(path: string, signal?: AbortSignal): Promise<void>;
     /** Create a session only after the user explicitly selects New session. */
-    createSession(): Promise<void>;
+    createSession(signal?: AbortSignal): Promise<void>;
+    /** Create a session for another purpose without selecting it, named so a reader can tell it apart.
+     *
+     * A verifier runs in its own session while the reviewed session stays selected, so this never
+     * follows the new session and never touches the reader's transcript.
+     * @param title - Session title to apply; hosts without a title service keep the default.
+     * @returns The new session's id, or undefined when its identity could not be read.
+     */
+    createNamedSession(title: string): Promise<string | undefined>;
+    /** Stop a session this client owns but has not selected, such as a verifier's.
+     *
+     * Killing the child client leaves the host's agent generation running, so the turn has to be
+     * cancelled on the host itself.
+     * @param sessionId - Session whose turn should stop.
+     */
+    cancelNamedSession(sessionId: string): Promise<void>;
     /** Replace the selected transcript and cancel its preceding follow stream.
      * @param sessionId - Session to follow.
      */
     selectSession(sessionId: string): Promise<void>;
+    /** Reattach the selected conversation after reconnect, keeping the current navigation context. */
+    restoreSelectedSession(): void;
+    private followSession;
     /** Wait for the selected follow snapshot, failing on disconnect or cancellation.
      * @param signal - Cancels waiting without closing the session.
      */
@@ -186,10 +246,18 @@ export declare class SessionController {
      * @param text - Composed prompt text.
      */
     prompt(text: string): Promise<void>;
+    /** Send one prompt the client assembled, keeping its durable echo out of composer recall.
+     *
+     * The host records every prompt as a user message, so an agent loop that submits a turn per
+     * attempt would otherwise crowd out the prompts the operator actually typed. Suppressing the text
+     * before sending is what makes the later echo invisible to ↑/↓.
+     * @param text - Prompt the client assembled, not text the operator typed.
+     */
+    promptInternal(text: string): Promise<void>;
     /** Answer the oldest selected-session interaction, after explicit user action.
      * @param value - Structured answer value or approval outcome.
      */
-    answer(value: Json): Promise<void>;
+    answer(value: AnswerValue): Promise<void>;
     /** Restrict an approval command to an approval request.
      * @param allowed - Whether the request is approved once.
      */
@@ -218,40 +286,12 @@ export declare class SessionController {
      * @returns The recalled prompt, or the unsent draft.
      */
     recall(direction: -1 | 1, current: string): string;
-    /** Composer draft, caret and parked draft, as the selected session holds them. */
-    get composer(): ComposerState;
-    /** Replace the composer text and caret, publishing only when either actually changed. */
-    setComposer(draft: string, cursor?: number): void;
-    /** Move the caret without changing the text. */
-    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, keyed by message sequence.
-     * @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;
     /** Local answer state for the selected session's pending waterfalls. */
     get interaction(): InteractionState;
     /** Replace the partly collected answers, keyed by the waterfall event id.
      * @param answers - Answers collected so far, by event id.
      */
-    setAnswers(answers: Record<string, ObjectValue[]>): void;
+    setAnswers(answers: Record<string, AnswerValue['answers']>): void;
     /** Replace the pending question's option keyboard state.
      * @param option - Highlighted option, toggled labels and free-text mode; undefined clears it.
      */
@@ -260,38 +300,6 @@ export declare class SessionController {
      * @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, so it does not reopen while it stands.
-     * @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;
     /** Remember a locally submitted command, which never becomes a durable session record. */
     recordRecall(value: string): void;
     /** Leave recall navigation because the composer was edited or replaced. */
@@ -310,11 +318,6 @@ export declare class SessionController {
      * @returns Whether any older prompt was recovered.
      */
     refillRecall(): boolean;
-    /** Seed recall from a complete cached entry, so an open that follows a scan costs no request.
-     * @param sessionId - Session being opened.
-     * @returns Whether the cache covered this session.
-     */
-    private adoptCachedPrompts;
     /** Fold one history page the cost scan already read into the prompt cache.
      *
      * The scan reads every session's whole history on connect, so this is where two readers stop
@@ -327,29 +330,17 @@ export declare class SessionController {
      * @param sessionId - Session the scan finished.
      */
     rememberScanDone(sessionId: string): void;
-    /** Fold every prompt the host still holds into the recall index, in the background.
-     *
-     * Session start delivers only the newest window, so without this the arrows could reach older
-     * prompts but not show them without paging first. Each page is parsed into a temporary transcript
-     * and only its prompts are kept, so the live record, its memory window and the row cache never
-     * grow. The walk is bounded and the next selection cancels it; anything past the bound is still
-     * reachable through the lazy backward step.
-     * @param sessionId - Session being opened.
-     * @param selection - Selector generation that must still be current.
-     */
-    private backfillPrompts;
     /** Search one page at a time, preserving only the first 200 matches and releasing temporary content.
      * @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; the live transcript keeps following.
+    /** Select a readable window by sequence; temporary records never escape to the UI.
      * @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>;
+    openHistory(target: number, signal: AbortSignal): Promise<void>;
     /** Load the prefix required for an explicit history jump; never loop on an unadvancing page.
      * @param target - Visible record sequence, or first for the oldest available history.
      * @param signal - Cancels local paging without interrupting the remote agent.
@@ -363,6 +354,4 @@ export declare class SessionController {
     private releaseTranscript;
     /** @returns The selected session identity, or a `Select a session first` failure. */
     private get sessionId();
-    /** Answer one retained waterfall through the connection's event-result endpoint. */
-    private reply;
 }