@itookit/dsht 0.3.3 → 0.3.7

package/dist/session/controller.d.ts

@@ -3,6 +3,8 @@ import { type Json, type ObjectValue } from '../transport/wire.ts';
 import type { ControllerStore, State } from '../state.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 { Reasoning } from './history.ts';
 import { Transcript } from './transcript.ts';
 import type { ConnectionView } from './connection-view.ts';
 import type { HistorySearch, RemovalTarget } from './types.ts';
@@ -14,7 +16,13 @@ export declare class SessionController {
     private readonly historyLimits;
     private follow;
     private interactions;
-    private historyPinned;
+    /** 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. */
+    private readonly promptCache;
+    /** Prompt index, composer and reading view of the selected session; the instance `State.session` exposes. */
+    private get info();
+    private get prompts();
     private stoppingSession?;
     private interruptTask;
     private admission;
@@ -46,6 +54,15 @@ export declare class SessionController {
      * @returns Retained question and approval frames for that session.
      */
     pendingFor(state: State): ObjectValue[];
+    /** 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
+     * client already retains them to answer later, so the counts are a fact of this generation rather
+     * than a new subscription. They live only as long as the connection: a reconnect clears the map
+     * until the host replays the pending waterfalls.
+     * @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.
@@ -168,11 +185,150 @@ export declare class SessionController {
      * @param allowed - Whether the request is approved once.
      */
     approve(allowed: boolean): Promise<void>;
+    /** Dismiss the whole selected-session question set without answering it.
+     *
+     * The Web client's close button settles the same waterfall the same way — reject with
+     * `ASK_CANCELLED` — so the host records a user cancellation rather than an answer. A question
+     * batch is answered as one request, so dismissals also discard partial local answers.
+     */
+    dismissQuestion(): Promise<void>;
     /** Add a page before the retained window using its fixed opening cut.
+     *
+     * Reclamation is deliberately not pinned here. Every caller that needs the fetched page to
+     * survive is already covered by the view: scrolling back sets a scroll position, `/think` opens a
+     * panel, and a recall page folds its prompts into the index before this resolves. A pin set here
+     * had no clearing edge, so after one recall page the history budget silently stopped applying for
+     * the rest of the session while every following page kept adding records.
      * @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>;
+    /** Recall one step through the session's prompt index; navigation 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;
+    /** 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;
+    /** 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;
+    /** 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, 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. */
+    resetRecall(): void;
+    /** Whether recall is parked on the oldest prompt it retains in memory. */
+    get recallAtOldest(): boolean;
+    /** How many prompts the session retains for recall. */
+    get recallLength(): number;
+    /** Whether an older prompt is reachable at all: shed from the window, or still on the host. */
+    get recallHasOlder(): boolean;
+    /** Recover older prompts from the loaded window before spending a page request.
+     *
+     * The transcript window can still hold prompts the index's budgets evicted, so a backward step
+     * refills from memory first and only then asks the caller to page. That is what keeps recall
+     * complete across submissions, where the previous buffer lost them at the eviction boundary.
+     * @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
+     * paying twice: it hands over pages it already has, and an open that follows reads the cache.
+     * @param sessionId - Session the page belongs to.
+     * @param records - Raw records of one scanned page.
+     */
+    rememberScanPage(sessionId: string, records: readonly Json[]): void;
+    /** Report that the scanned session's history was read to its beginning.
+     * @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.