@itookit/dsht 0.3.8 → 0.5.1

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 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;
@@ -16,6 +20,10 @@ export declare class SessionController {
     private readonly historyLimits;
     private follow;
     private interactions;
+    /** 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?;
     /** Prompts of sessions this process has already read, so re-opening one costs no page request. */
@@ -26,7 +34,9 @@ export declare class SessionController {
     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: ControllerStore, 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. */
@@ -39,6 +49,27 @@ export declare class SessionController {
     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. */
@@ -53,7 +84,7 @@ export declare class SessionController {
      * @param state - State being published.
      * @returns Retained question and approval frames for that session.
      */
-    pendingFor(state: State): ObjectValue[];
+    pendingFor(state: State): 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 +94,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 +110,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.
@@ -97,6 +128,13 @@ export declare class SessionController {
      * @param screen - Picker to display after the refresh.
      */
     showPicker(screen: 'workspaces' | 'sessions'): 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.
@@ -136,6 +174,21 @@ export declare class SessionController {
     createWorkspace(path: string): Promise<void>;
     /** Create a session only after the user explicitly selects New session. */
     createSession(): 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.
      */
@@ -186,10 +239,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 +279,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 +293,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. */