@itookit/dsht 0.2.4 → 0.3.2

package/dist/controller/controller.d.ts

@@ -0,0 +1,260 @@
+/** 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 HistoryLimits } from '../session/memory.ts';
+import { SessionController } from '../session/controller.ts';
+import { CatalogController } from '../catalog/controller.ts';
+import type { Telemetry } 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 { type ControllerStore, type State } from '../state.ts';
+import type { HistorySearch, RemovalTarget } from '../session/types.ts';
+/** 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;
+    state: State;
+    /** Physical connection, retry loop and projection store. */
+    readonly connection: ConnectionController;
+    /** Selected session, follow stream, history and interactions. */
+    readonly session: SessionController;
+    /** Model routes and agent-preset metadata. */
+    readonly catalog: CatalogController;
+    /** Background billing scan; present only when a ledger was supplied. */
+    readonly cost: CostController | undefined;
+    /** Bounded runtime memory samples; present only when a log path was supplied. */
+    readonly memoryLog: MemoryLog | undefined;
+    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);
+    /** 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;
+    /** @returns The current selector generation. */
+    selection(): number;
+    /** Advance the selector generation when the selected workspace or session changes. */
+    bumpSelection(): void;
+    /** Publish a state patch, re-deriving the visible pending interactions.
+     * @param patch - Fields to replace on the current state.
+     */
+    update(patch: Partial<State>): void;
+    /** 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. */
+    stop(): Promise<void>;
+    /** 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.
+     * @param operation - Operation to run while the client is busy.
+     * @returns Whether the operation completed.
+     */
+    perform(operation: () => Promise<void>): Promise<boolean>;
+    /** 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
+     * structures that grow with rendered content — the layout row cache and the bounded math and
+     * diagram cache — and the work the last cost scan re-read, which is the only timer here whose
+     * per-pass work scales with history. With a runtime that exposes `gc`, the sample also reports
+     * the heap after a forced collection, so retained state and uncollected garbage stay distinct.
+     */
+    private memorySample;
+    /** Collect before reading the heap when the runtime exposes a collection.
+     * @returns Heap in use after the collection and how long it took, or undefined without `global.gc`.
+     */
+    private forcedGc;
+    /** A new generation starts; drop generation-scoped domain state. */
+    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. */
+    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;
+    /** @returns Host running state of the selected session. */
+    get running(): boolean;
+    /** @returns Current session title, falling back to the list title and then the ID. */
+    get sessionName(): string | undefined;
+    /** @returns Current agent-preset label. */
+    get sessionMode(): string | undefined;
+    /** @returns Epoch start of the active turn, when known. */
+    get workingSince(): number | undefined;
+    /** @returns Sessions accounted to the selected workspace, minus archived identities. */
+    get visibleSessions(): ObjectValue[];
+    /** 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>;
+    /** 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>;
+    /** 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;
+    /** Refresh all HTTP-visible sessions without changing the selected conversation.
+     * @param signal - Optional cancellation for an explicit /cost refresh.
+     */
+    refreshCosts(signal?: AbortSignal): 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.
+     * @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>;
+    /** 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>;
+    /** 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 target.
+     * @param query - Workspace target, if any.
+     */
+    switchWorkspace(query?: string): Promise<void>;
+    /** 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>;
+    /** Prompt for a host path without starting a local agent. */
+    enterPath(): void;
+    /** 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 in the selected workspace. */
+    createSession(): Promise<void>;
+    /** Replace the selected transcript and follow the session.
+     * @param sessionId - Session to follow.
+     */
+    selectSession(sessionId: string): Promise<void>;
+    /** Wait for the selected follow snapshot.
+     * @param signal - Cancels waiting without closing the session.
+     */
+    waitForHistory(signal: AbortSignal): Promise<void>;
+    /** 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;
+    }>;
+    /** 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[]>;
+    /** 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.
+     * @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 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>;
+    /** Admit text once as steering while running, or a new turn while idle.
+     * @param text - Composed prompt text.
+     */
+    prompt(text: string): Promise<void>;
+    /** Cancel the active turn; pending queue items remain host-owned. */
+    cancelTurn(): Promise<void>;
+    /** 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>;
+    /** 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>;
+    /** 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>;
+    /** Answer the oldest selected-session interaction, after explicit user action.
+     * @param value - Structured answer value or approval outcome.
+     */
+    answer(value: Json): Promise<void>;
+    /** Approve or reject the pending approval request.
+     * @param allowed - Whether the request is approved once.
+     */
+    approve(allowed: boolean): Promise<void>;
+}
+export type { HistorySearch, RemovalTarget } from '../session/types.ts';
+export type { State } from '../state.ts';

package/dist/controller/controller.js

@@ -0,0 +1,362 @@
+/** Application facade: composes the connection, session, catalog and cost domains. */
+import { Client } from "../transport/client.js";
+import { errorText } from "../transport/wire.js";
+import { DEFAULT_HISTORY_LIMITS } from "../session/memory.js";
+import { layoutStats } from "../session/history.js";
+import { markdownCacheStats } from "../session/markdown.js";
+import { SessionController } from "../session/controller.js";
+import { CatalogController } from "../catalog/controller.js";
+import { CostController } from "../cost/controller.js";
+import { ConnectionController } from "./connection.js";
+import { MemoryLog } from "./memory-log.js";
+import { initialState } from "../state.js";
+/** 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 class Controller {
+    base;
+    initialSession;
+    costs;
+    historyLimits;
+    memoryLogPath;
+    state = initialState();
+    /** Physical connection, retry loop and projection store. */
+    connection;
+    /** Selected session, follow stream, history and interactions. */
+    session;
+    /** Model routes and agent-preset metadata. */
+    catalog;
+    /** Background billing scan; present only when a ledger was supplied. */
+    cost;
+    /** Bounded runtime memory samples; present only when a log path was supplied. */
+    memoryLog;
+    observers = new Set();
+    selector = 0;
+    constructor(base, token, initialSession, makeClient = () => new Client(base), authenticate = client => client.authenticate(token ?? ''), costs, historyLimits = DEFAULT_HISTORY_LIMITS, memoryLogPath) {
+        this.base = base;
+        this.initialSession = initialSession;
+        this.costs = costs;
+        this.historyLimits = historyLimits;
+        this.memoryLogPath = memoryLogPath;
+        const options = { base, token, initialSession, makeClient, authenticate };
+        this.connection = new ConnectionController(this, options, this);
+        this.session = new SessionController(this, this.connection, this.connection, historyLimits);
+        this.catalog = new CatalogController(this, this.connection);
+        if (costs)
+            this.cost = new CostController(costs, {
+                client: () => this.connection.client(),
+                online: () => this.state.online,
+                signal: () => this.connection.signal(),
+                publish: () => this.update({}),
+            });
+        if (memoryLogPath !== undefined)
+            this.memoryLog = new MemoryLog(memoryLogPath, () => this.memorySample());
+    }
+    /** React-compatible state subscription. */
+    subscribe = (listener) => {
+        this.observers.add(listener);
+        return () => this.observers.delete(listener);
+    };
+    /** Snapshot identity changes only when the controller publishes. */
+    snapshot = () => this.state;
+    /** Current projection store; replaced at each connection generation. */
+    get telemetry() { return this.connection.telemetry; }
+    /** @returns The current selector generation. */
+    selection() { return this.selector; }
+    /** Advance the selector generation when the selected workspace or session changes. */
+    bumpSelection() { this.selector++; }
+    /** Publish a state patch, re-deriving the visible pending interactions.
+     * @param patch - Fields to replace on the current state.
+     */
+    update(patch) {
+        const next = { ...this.state, ...patch, version: this.state.version + 1 };
+        next.pending = next.online && next.screen === 'chat' && this.session
+            ? this.session.pendingFor(next) : [];
+        this.state = next;
+        for (const observer of this.observers)
+            observer();
+    }
+    /** Start one retry loop, with a fresh snapshot generation after every disconnect. */
+    start() { this.connection.start(); this.memoryLog?.start(); }
+    /** Cancel retries and HTTP, close the socket, and release session and catalog work. */
+    async stop() {
+        await this.connection.stop();
+        await this.session.settle();
+        await this.catalog.settle();
+        await this.cost?.stop();
+        await this.memoryLog?.stop();
+        this.session.release();
+    }
+    /** 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.
+     */
+    async shutdown() {
+        if (this.session.active)
+            await this.session.interrupt(true);
+        await this.stop();
+    }
+    /** Run a UI operation and expose errors without destroying the current input.
+     * @param operation - Operation to run while the client is busy.
+     * @returns Whether the operation completed.
+     */
+    async perform(operation) {
+        if (this.state.busy || !this.state.online)
+            return false;
+        this.update({ busy: true, error: '' });
+        try {
+            await operation();
+            return true;
+        }
+        catch (error) {
+            this.update({ error: errorText(error) });
+            return false;
+        }
+        finally {
+            this.update({ busy: false });
+        }
+    }
+    /** 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
+     * structures that grow with rendered content — the layout row cache and the bounded math and
+     * diagram cache — and the work the last cost scan re-read, which is the only timer here whose
+     * per-pass work scales with history. With a runtime that exposes `gc`, the sample also reports
+     * the heap after a forced collection, so retained state and uncollected garbage stay distinct.
+     */
+    memorySample() {
+        const memory = process.memoryUsage();
+        const transcript = this.state.transcript;
+        const ledger = this.costs?.summary();
+        const layout = layoutStats(transcript);
+        const markdown = markdownCacheStats();
+        const gc = this.forcedGc();
+        return {
+            time: new Date().toISOString(),
+            rss: memory.rss, heapTotal: memory.heapTotal, heapUsed: memory.heapUsed,
+            external: memory.external, arrayBuffers: memory.arrayBuffers,
+            ...(gc === undefined ? {} : { heapUsedAfterGc: gc.used, gcMs: gc.ms }),
+            online: this.state.online, screen: this.state.screen,
+            session: this.state.sessionId ?? null,
+            pinned: this.session.pinned,
+            records: transcript.retainedRecordCount, retainedBytes: transcript.retainedBytes,
+            beforeSeq: transcript.beforeSeq ?? null, hasMore: transcript.hasMore,
+            live: transcript.hasLiveContent, liveChars: transcript.liveText.length, pending: this.state.pending.length,
+            thoughts: transcript.thoughts.length,
+            ...(layout === undefined ? {} : { layoutRows: layout.rows, layoutCacheBytes: layout.cacheBytes, layoutSpans: layout.spans,
+                layoutSpanChars: layout.spanChars, layoutLiveWraps: layout.liveWraps, layoutLiveMarkdown: layout.liveMarkdown }),
+            markdownEntries: markdown.entries, markdownChars: markdown.chars, markdownHits: markdown.hits, markdownMisses: markdown.misses,
+            scanning: this.costs?.scanning ?? false,
+            ...(this.costs?.lastScan === undefined ? {} : { scanSessions: this.costs.lastScan.sessions,
+                scanPages: this.costs.lastScan.pages, scanEvents: this.costs.lastScan.events }),
+            ...(ledger === undefined ? {} : { ledgerSessions: ledger.sessions, ledgerCharges: ledger.charges, ledgerUnpriced: ledger.unpriced }),
+        };
+    }
+    /** Collect before reading the heap when the runtime exposes a collection.
+     * @returns Heap in use after the collection and how long it took, or undefined without `global.gc`.
+     */
+    forcedGc() {
+        const collect = globalThis.gc;
+        if (typeof collect !== 'function')
+            return undefined;
+        const start = Date.now();
+        collect();
+        return { used: process.memoryUsage().heapUsed, ms: Date.now() - start };
+    }
+    /** A new generation starts; drop generation-scoped domain state. */
+    begin() {
+        this.session.beginGeneration();
+        this.catalog.reset();
+        this.update({ controlError: undefined });
+    }
+    /** The event stream is ready and the control baseline is applied. */
+    async ready() {
+        this.catalog.refresh();
+        this.update({ online: true, status: 'Connected', error: '', pending: [] });
+        const screen = this.state.screen;
+        await this.session.showPicker(screen === 'sessions' ? 'sessions' : 'workspaces');
+        const sessionId = this.state.sessionId ?? this.initialSession;
+        if (sessionId && (screen === 'chat' || this.initialSession && !this.state.sessionId))
+            await this.session.selectSession(sessionId);
+        this.cost?.start();
+    }
+    /** The generation ended; invalidate session work and stop the scan. */
+    async ended() {
+        this.session.endGeneration();
+        await this.cost?.stop();
+    }
+    /** Deliver a host waterfall to the session domain.
+     * @param frame - One decoded waterfall frame.
+     * @returns Whether the session domain retained it.
+     */
+    waterfall(frame) { return this.session.waterfall(frame); }
+    /** Drop a waterfall the host cancelled.
+     * @param eventId - Correlation id previously retained.
+     */
+    cancelled(eventId) { this.session.cancelled(eventId); }
+    /** Apply one host running-state notification.
+     * @param sessionId - Session whose state changed.
+     * @param running - Whether the host still runs that session.
+     */
+    status(sessionId, running) { this.session.status(sessionId, running); }
+    /** Surface a host-reported session error.
+     * @param sessionId - Session the host reported on.
+     * @param error - Error payload as delivered by the host.
+     */
+    error(sessionId, error) { this.session.reportError(sessionId, error); }
+    /** Reload the model catalog after a host settings, credential or adapter change. */
+    invalidated() { this.catalog.refresh(); }
+    /** Refresh billing after a turn finished. */
+    idle() { this.cost?.onTurnIdle(); }
+    /** @returns Host running state of the selected session. */
+    get running() { return this.session.running; }
+    /** @returns Current session title, falling back to the list title and then the ID. */
+    get sessionName() { return this.session.sessionName; }
+    /** @returns Current agent-preset label. */
+    get sessionMode() { return this.session.sessionMode; }
+    /** @returns Epoch start of the active turn, when known. */
+    get workingSince() { return this.session.workingSince; }
+    /** @returns Sessions accounted to the selected workspace, minus archived identities. */
+    get visibleSessions() { return this.session.visibleSessions; }
+    /** Load the optional preset roster once per connection. */
+    loadPresetNames() { this.catalog.loadPresetNames(); }
+    /** @returns Host model routes and adapter-owned reasoning choices. */
+    async modelCatalog() { return this.catalog.modelCatalog(); }
+    /** Select the next request's model.
+     * @param provider - Host provider route ID.
+     * @param model - Exact model ID.
+     * @param reasoningEffort - Optional adapter-owned effort ID.
+     */
+    async selectModel(provider, model, reasoningEffort) {
+        await this.catalog.selectModel(provider, model, reasoningEffort);
+    }
+    /** 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 = false) { return this.session.interrupt(force); }
+    /** 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) { this.session.pinHistory(pinned); }
+    /** Refresh all HTTP-visible sessions without changing the selected conversation.
+     * @param signal - Optional cancellation for an explicit /cost refresh.
+     */
+    async refreshCosts(signal = this.connection.signal()) { await this.cost?.refresh(signal); }
+    /** Refresh both lists from the host, then show the requested picker.
+     * @param screen - Picker to display after the refresh.
+     */
+    async showPicker(screen) { await this.session.showPicker(screen); }
+    /** 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.
+     */
+    async removalTarget(kind, query) { return this.session.removalTarget(kind, query); }
+    /** Apply a confirmed removal or verified empty-session archival.
+     * @param target - Exact workspace or session identity reviewed by the user.
+     */
+    async removeTarget(target) { await this.session.removeTarget(target); }
+    /** Pick a workspace, or use all sessions when the identity is omitted.
+     * @param workspaceId - Workspace to select, if any.
+     */
+    pickWorkspace(workspaceId) { this.session.pickWorkspace(workspaceId); }
+    /** Open a workspace picker, or resolve a workspace target.
+     * @param query - Workspace target, if any.
+     */
+    async switchWorkspace(query) { await this.session.switchWorkspace(query); }
+    /** Guide session selection, list all sessions with `all`, or resolve a target.
+     * @param query - Session target, `all`, or nothing for the guided picker.
+     */
+    async switchSession(query) { await this.session.switchSession(query); }
+    /** Prompt for a host path without starting a local agent. */
+    enterPath() { this.session.enterPath(); }
+    /** Register a host directory and move to its session picker.
+     * @param path - Absolute directory path on the host.
+     */
+    async createWorkspace(path) { await this.session.createWorkspace(path); }
+    /** Create a session in the selected workspace. */
+    async createSession() { await this.session.createSession(); }
+    /** Replace the selected transcript and follow the session.
+     * @param sessionId - Session to follow.
+     */
+    async selectSession(sessionId) { await this.session.selectSession(sessionId); }
+    /** Wait for the selected follow snapshot.
+     * @param signal - Cancels waiting without closing the session.
+     */
+    async waitForHistory(signal) { await this.session.waitForHistory(signal); }
+    /** 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.
+     */
+    async searchSessions(query, workspaceOnly, signal) {
+        return this.session.searchSessions(query, workspaceOnly, signal);
+    }
+    /** 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.
+     */
+    async references(query, signal) { return this.session.references(query, signal); }
+    /** 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.
+     */
+    async command(line, signal) { return this.session.command(line, signal); }
+    /** Remove one host-owned pending input.
+     * @param itemId - Queue occurrence identity from session/control.
+     */
+    async removeQueued(itemId) { await this.session.removeQueued(itemId); }
+    /** 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.
+     */
+    async exportLog(path, signal) { return this.session.exportLog(path, signal); }
+    /** 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.
+     */
+    async exportHtml(path, signal) { return this.session.exportHtml(path, signal); }
+    /** Admit text once as steering while running, or a new turn while idle.
+     * @param text - Composed prompt text.
+     */
+    async prompt(text) { await this.session.prompt(text); }
+    /** Cancel the active turn; pending queue items remain host-owned. */
+    async cancelTurn() { await this.session.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.
+     */
+    async older(signal, transcript) { await this.session.older(signal, transcript); }
+    /** 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.
+     */
+    async searchHistory(query, signal) { return this.session.searchHistory(query, signal); }
+    /** 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.
+     */
+    async historyAt(target, signal) { return this.session.historyAt(target, signal); }
+    /** 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.
+     */
+    async historyThrough(target, signal) { await this.session.historyThrough(target, signal); }
+    /** Answer the oldest selected-session interaction, after explicit user action.
+     * @param value - Structured answer value or approval outcome.
+     */
+    async answer(value) { await this.session.answer(value); }
+    /** Approve or reject the pending approval request.
+     * @param allowed - Whether the request is approved once.
+     */
+    async approve(allowed) { await this.session.approve(allowed); }
+}

package/dist/controller/index.d.ts

@@ -0,0 +1,5 @@
+/** Controller domain: the application facade and the connection it owns. */
+export { Controller } from './controller.ts';
+export type { HistorySearch, RemovalTarget, State } from './controller.ts';
+export { ConnectionController } from './connection.ts';
+export type { ConnectionListener, ConnectionOptions } from './connection.ts';

package/dist/controller/index.js

@@ -0,0 +1,3 @@
+/** Controller domain: the application facade and the connection it owns. */
+export { Controller } from "./controller.js";
+export { ConnectionController } from "./connection.js";

package/dist/controller/memory-log.d.ts

@@ -0,0 +1,35 @@
+import { type ObjectValue } from '../transport/wire.ts';
+/** Append-only memory log; the file never exceeds twice `KEEP_SAMPLES` lines.
+ *
+ * The log exists to answer "is retained content growing, or is this just V8's high-water mark",
+ * so each sample records the process counters next to the client's retained window and the
+ * controller state that decides whether that window is being reclaimed. Samples contain counts
+ * and sizes only, never prompt, tool, or session text. A failing log stops itself instead of
+ * breaking the client.
+ */
+export declare class MemoryLog {
+    readonly path: string | undefined;
+    private readonly sampleSource;
+    private timer;
+    private appended;
+    private writing;
+    /** Last write failure, when the log stopped itself. */
+    error: string | undefined;
+    constructor(path: string | undefined, sampleSource: () => ObjectValue);
+    /** Write the header into a new file, then sample once; a missing or unwritable path is reported
+     * by that first sample instead of here.
+     */
+    private begin;
+    /** Sample once now and then every `SAMPLE_INTERVAL_MS`; absent when no path was configured. */
+    start(): void;
+    /** Stop sampling and rewrite the file with its retained window. */
+    stop(): Promise<void>;
+    /** Append one sample line, skipping overlapping calls.
+     *
+     * A repeated failure would be noise, so the first one stops the timer and leaves the client
+     * running; the log is diagnostics, not a feature the terminal depends on.
+     */
+    sample(): Promise<void>;
+    /** Rewrite the file with the header and the newest kept lines, bounding its size. */
+    private compact;
+}