@itookit/dsht 0.2.4 → 0.3.2

package/dist/{controller.d.ts → session/controller.d.ts}

@@ -1,143 +1,84 @@
-import { Client } from './client.ts';
-import { CostLedger } from './cost.ts';
-import { Telemetry } from './telemetry.ts';
-import { Transcript } from './transcript.ts';
-import { type HistoryLimits } from './memory.ts';
+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 { HistoryLimits } from './memory.ts';
 import { type FileReference } from './references.ts';
-import { type Json, type ObjectValue } from './wire.ts';
-/** Resolved navigation-removal identity; empty marks a fresh blank, idle session eligible for immediate archival. */
-export interface RemovalTarget {
-    kind: 'workspace' | 'session';
-    id: string;
-    name: string;
-    path?: string;
-    empty?: boolean;
-}
-/** State shared by the picker and conversation view. */
-export interface State {
-    version: number;
-    online: boolean;
-    busy: boolean;
-    screen: 'workspaces' | 'sessions' | 'chat' | 'path';
-    status: string;
-    error: string;
-    workspaces: ObjectValue[];
-    sessions: ObjectValue[];
-    showAllSessions: boolean;
-    workspaceId?: string;
-    sessionId?: string;
-    pending: ObjectValue[];
-    controlError?: string;
-    modelError?: string;
-    presetError?: string;
-    presets?: ObjectValue[];
-    defaultModel?: ObjectValue;
-    transcript: Transcript;
-}
-/** Bounded search results contain navigation summaries, never complete message bodies. */
-export interface HistorySearch {
-    items: {
-        seq: number;
-        role: string;
-        preview: string;
-    }[];
-    truncated: boolean;
-}
-/** Wire addresses for one `session/list` row, in the order the cost scan should try them.
- *
- * A subagent child is reachable only under its durable parent, and the list row omits the delivery
- * mode, so both modes are offered with the continuable form first.
- * @param session - One row from the host session list.
- * @returns One plain-session address, or both subagent forms when the row is a child.
- */
-export declare function costAddresses(session: ObjectValue): ObjectValue[];
-/** Owns reconnects and subscriptions. User commands remain single-attempt operations. */
-export declare class Controller {
-    readonly base: string;
-    readonly initialSession?: string | undefined;
-    private makeClient;
-    private authenticate;
-    readonly costs?: CostLedger | undefined;
-    readonly historyLimits: HistoryLimits;
-    state: State;
-    private observers;
-    private interactions;
-    private abort;
-    private client;
-    private clientId;
+import { Transcript } from './transcript.ts';
+import type { ConnectionView } from './connection-view.ts';
+import type { HistorySearch, RemovalTarget } from './types.ts';
+/** Owns the selected session: its follow stream, transcript, history window and interactions. */
+export declare class SessionController {
+    private readonly store;
+    private readonly host;
+    private readonly connection;
+    private readonly historyLimits;
     private follow;
-    private runTask;
-    private generationFailed;
-    private selection;
+    private interactions;
     private historyPinned;
-    telemetry: Telemetry;
-    private observedRunningAt;
-    private presetClient?;
-    private catalogRevision;
-    private catalogTasks;
-    private runningUpdates;
     private stoppingSession?;
     private interruptTask;
     private admission;
-    private costUpdates;
-    private costAbort?;
-    private costTask;
-    private costTimer;
+    constructor(store: ControllerStore, host: HostAccess, connection: ConnectionView, historyLimits: HistoryLimits);
     /** 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;
-    /** Load the optional preset roster once per connection, only when a session names a preset. */
-    loadPresetNames(): void;
-    /** Fetch current model routes and adapter-owned reasoning choices for the selected session.
-     * @returns Host catalog; provider failures remain available to the selector.
-     */
-    modelCatalog(): Promise<ObjectValue>;
-    /** Select the next request's model; the host also attempts to save its deployment default.
-     * @param provider - Host provider route ID.
-     * @param model - Exact model ID.
-     * @param reasoningEffort - Optional adapter-owned effort ID; omission uses its default.
-     */
-    selectModel(provider: string, model: string, reasoningEffort?: string): Promise<void>;
     /** 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;
+    /** 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. */
+    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.
+     * @returns Retained question and approval frames for that session.
+     */
+    pendingFor(state: State): ObjectValue[];
+    /** 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.
+     */
+    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 to the session list and status line.
+     * @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 error for the selected session.
+     * @param sessionId - Session the host reported on.
+     * @param error - Error payload as delivered by the host.
+     */
+    reportError(sessionId: unknown, error: unknown): 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.
      */
     interrupt(force?: boolean): Promise<boolean>;
-    constructor(base: string, token: string | undefined, initialSession?: string | undefined, makeClient?: () => Client, authenticate?: (client: Client) => Promise<void>, costs?: CostLedger | undefined, historyLimits?: HistoryLimits);
-    /** React-compatible state subscription. */
-    subscribe: (listener: () => void) => (() => void);
-    /** Snapshot identity changes only when the controller publishes. */
-    snapshot: () => State;
-    /** Start one retry loop, with a fresh snapshot generation after every disconnect. */
-    start(): void;
-    /** Cancel retries and HTTP, close the socket, and wait for the loop to settle. */
-    stop(): Promise<void>;
     /** Keep history stable while the user reads, searches, or expands it; trim again at the live tail.
      * @param pinned - Whether the main transcript is actively being read away from its tail.
      */
     pinHistory(pinned: boolean): void;
-    private reclaimHistory;
-    private releaseTranscript;
-    /** Stop the selected turn and then close, so quitting does not leave host work running.
-     * 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. */
-    perform(operation: () => Promise<void>): Promise<boolean>;
-    /** Refresh all HTTP-visible sessions without changing the selected conversation.
-     * @param signal - Optional cancellation for an explicit /cost refresh.
-     */
-    refreshCosts(signal?: AbortSignal): Promise<void>;
-    /** Read one session's complete cost history, retrying a subagent child with its other delivery mode. */
-    private sessionCostHistory;
-    /** Page one addressed session's history into the billing events the ledger folds. */
-    private readCostHistory;
-    /** Refresh both lists from the host, then show the requested picker. */
+    /** Cancel the active turn; pending queue items remain host-owned. */
+    cancelTurn(): Promise<void>;
+    /** 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>;
     /** Resolve a removal command to one reviewable object without changing the selection.
      * @param kind - Workspace registration removal or session archival.
@@ -149,19 +90,29 @@ export declare class Controller {
      * @param target - Exact workspace or session identity reviewed by the user.
      */
     removeTarget(target: RemovalTarget): Promise<void>;
-    /** Pick a workspace, or use all sessions when the identity is omitted. */
+    /** Pick a workspace, or use all sessions when the identity is omitted.
+     * @param workspaceId - Workspace to select, if any.
+     */
     pickWorkspace(workspaceId?: string): void;
-    /** Open a workspace picker, or resolve a workspace by ID, exact title/path, or unique ID prefix. */
+    /** 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>;
-    /** Guide workspace selection, list all sessions with `all`, or resolve an exact session target. */
+    /** 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>;
     /** Prompt for a host path without starting a local agent. */
     enterPath(): void;
-    /** Register a host directory and move to its session picker. */
+    /** Register a host directory and move to its session picker.
+     * @param path - Absolute directory path on the host.
+     */
     createWorkspace(path: string): Promise<void>;
     /** Create a session only after the user explicitly selects New session. */
     createSession(): Promise<void>;
-    /** Replace the selected transcript and cancel its preceding follow stream. */
+    /** Replace the selected transcript and cancel its preceding follow stream.
+     * @param sessionId - Session to follow.
+     */
     selectSession(sessionId: string): Promise<void>;
     /** Wait for the selected follow snapshot, failing on disconnect or cancellation.
      * @param signal - Cancels waiting without closing the session.
@@ -183,11 +134,44 @@ export declare class Controller {
      * @returns Validated candidates in host order.
      */
     references(query: string, signal: AbortSignal): Promise<FileReference[]>;
-    /** Admit a prompt once; a failed response can have an uncertain delivery outcome. */
-    prompt(text: string, mode?: 'queue' | 'steer'): Promise<void>;
-    /** Cancel the active turn; pending queue items remain host-owned. */
-    cancelTurn(): Promise<void>;
-    /** Add a page before the retained window using its fixed opening cut. */
+    /** 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>;
+    /** Remove one host-owned pending input; an already claimed item reports a host error.
+     * @param itemId - Queue occurrence identity from session/control.
+     */
+    removeQueued(itemId: string): Promise<void>;
+    /** 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>;
+    /** Save the retained conversation with offline Markdown, diagrams and math.
+     * @param path - Optional destination; existing files are never overwritten.
+     * @param signal - Cancels the write.
+     * @returns Absolute saved filename.
+     */
+    exportHtml(path: string | undefined, signal: AbortSignal): Promise<string>;
+    /** Admit text once as steering while running, or a new turn while idle; a lost response can leave delivery uncertain.
+     * @param text - Composed prompt text.
+     */
+    prompt(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>;
+    /** Restrict an approval command to an approval request.
+     * @param allowed - Whether the request is approved once.
+     */
+    approve(allowed: boolean): Promise<void>;
+    /** Add a page before the retained window using its fixed opening cut.
+     * @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>;
     /** 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.
@@ -206,16 +190,14 @@ export declare class Controller {
      * @param signal - Cancels local paging without interrupting the remote agent.
      */
     historyThrough(target: number | 'first', signal: AbortSignal): Promise<void>;
-    /** Answer the oldest selected-session interaction, after explicit user action. */
-    answer(value: Json): Promise<void>;
-    /** Restrict an approval command to an approval request. */
-    approve(allowed: boolean): Promise<void>;
-    /** Present only sessions explicitly accounted to the selected workspace. */
-    get visibleSessions(): ObjectValue[];
-    private get host();
+    /** Reclaim reloadable history unless the user is reading away from the tail.
+     * @returns Number of removed records.
+     */
+    private reclaimHistory;
+    /** Release the selected transcript and its layout caches. */
+    private releaseTranscript;
+    /** @returns The selected session identity, or a `Select a session first` failure. */
     private get sessionId();
-    private update;
+    /** Answer one retained waterfall through the connection's event-result endpoint. */
     private reply;
-    private refreshCatalog;
-    private run;
 }