@itookit/dsht 0.3.0 → 0.3.2

package/dist/{cli.js → cli/index.js}

@@ -1,21 +1,19 @@
 #!/usr/bin/env node
-import { jsx as _jsx } from "react/jsx-runtime";
 /** Standalone executable entry; connects to an existing host and never launches Harness. */
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { CostLedger, DEFAULT_PRICES, pricesFrom } from "./cost.js";
+import { CostLedger, DEFAULT_PRICES, pricesFrom } from "../cost/index.js";
 import { parseArgs } from 'node:util';
-import { render } from 'ink';
-import { App } from "./app.js";
-import { sessionLabel } from "./navigation.js";
-import { CookieStore, login } from "./auth.js";
-import { Client } from "./client.js";
-import { historyLimits } from "./memory.js";
-import { Controller } from "./controller.js";
-import { endpoint } from "./endpoint.js";
-import { errorText, safeText, string } from "./wire.js";
+import { mount } from "../ui/mount.js";
+import { createPrivateFile, ensureDirectory, readText } from "../storage/index.js";
+import { sessionLabel } from "../session/navigation.js";
+import { CookieStore, login } from "../transport/auth.js";
+import { Client } from "../transport/client.js";
+import { historyLimits } from "../session/memory.js";
+import { Controller } from "../controller/controller.js";
+import { endpoint } from "../transport/endpoint.js";
+import { errorText, safeText, string } from "../transport/wire.js";
 const HELP = `Usage: dsht [options] [list workspaces|list sessions]
 
 With no command, choose a workspace and session interactively.
@@ -26,6 +24,8 @@ With no command, choose a workspace and session interactively.
   --auth-dir <path>     Private cookie directory (or DSHT_AUTH_DIR)
   --history-records <n> Soft history record limit (default 2000)
   --history-mb <n>      Soft history payload budget in MiB (default 16)
+  --memory-log <path>   Append runtime memory samples; a failing log stops itself
+  --no-memory-log       Disable the runtime memory log (default: enabled)
   --json               Print machine-readable list output
   --help               Show this help
 
@@ -34,6 +34,7 @@ First login: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web.
 Cookies are saved per server origin and reused on later starts. Tokens are never saved.
 /cost shows session, today and three-day CNY estimates.
 DSHT_CONFIG_DIR overrides the prices.json directory; DSHT_STATE_DIR overrides usage storage.
+The memory log defaults to <state>/memory.log; DSHT_MEMORY_LOG sets another path or 'off'.
 Examples:
   npx @itookit/dsht
   dsht list workspaces --json
@@ -44,6 +45,7 @@ async function main() {
             url: { type: 'string', default: process.env.DSH_URL ?? 'http://127.0.0.1:3080' },
             'history-records': { type: 'string' }, 'history-mb': { type: 'string' },
             workspace: { type: 'string' }, session: { type: 'string' }, 'auth-dir': { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean' },
+            'memory-log': { type: 'string' }, 'no-memory-log': { type: 'boolean' },
         } });
     if (values.help) {
         process.stdout.write(HELP);
@@ -83,21 +85,19 @@ async function main() {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         throw new Error('Interactive mode requires a terminal. Use list workspaces or list sessions for scripts.');
     const config = process.env.DSHT_CONFIG_DIR ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'dsht');
-    await mkdir(config, { recursive: true, mode: 0o700 });
+    await ensureDirectory(config);
     const pricePath = join(config, 'prices.json');
-    try {
-        await writeFile(pricePath, JSON.stringify(DEFAULT_PRICES, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
-    }
-    catch (error) {
-        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
-            throw error;
-    }
-    const prices = pricesFrom(JSON.parse(await readFile(pricePath, 'utf8')));
-    const costDirectory = join(process.env.DSHT_STATE_DIR ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht'), 'cost', createHash('sha256').update(new URL(url).origin).digest('hex'));
+    await createPrivateFile(pricePath, JSON.stringify(DEFAULT_PRICES, null, 2) + '\n');
+    const raw = await readText(pricePath);
+    if (raw === undefined)
+        throw new Error(`Price configuration disappeared: ${pricePath}`);
+    const prices = pricesFrom(JSON.parse(raw));
+    const stateRoot = process.env.DSHT_STATE_DIR ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht');
+    const costDirectory = join(stateRoot, 'cost', createHash('sha256').update(new URL(url).origin).digest('hex'));
     const costs = new CostLedger(prices, costDirectory);
     await costs.load();
-    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits);
-    const app = render(_jsx(App, { controller: controller }), { exitOnCtrlC: false });
+    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits, memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']));
+    const app = mount(controller);
     const terminate = () => app.unmount();
     process.once('SIGTERM', terminate);
     controller.start();
@@ -109,4 +109,20 @@ async function main() {
         await controller.shutdown();
     }
 }
+/** Resolve the runtime memory log path: an explicit flag wins, then the environment, then the default.
+ * @param stateRoot - Application state root used for the default path.
+ * @param requested - `--memory-log` value, when given.
+ * @param disabled - `--no-memory-log` flag.
+ * @returns Absolute log path, or undefined when the log is disabled.
+ */
+function memoryLogPath(stateRoot, requested, disabled) {
+    if (requested !== undefined && requested.trim() === '')
+        throw new Error('--memory-log requires a path');
+    if (disabled)
+        return undefined;
+    const chosen = (requested ?? process.env.DSHT_MEMORY_LOG)?.trim();
+    if (chosen === undefined || chosen === '')
+        return join(stateRoot, 'memory.log');
+    return chosen === 'off' ? undefined : chosen;
+}
 main().catch(error => { process.stderr.write(`${errorText(error)}\n`); process.exitCode = 1; });

package/dist/controller/connection.d.ts

@@ -0,0 +1,80 @@
+import { Client } from '../transport/client.ts';
+import { type ObjectValue } from '../transport/wire.ts';
+import type { HostAccess } from '../transport/host.ts';
+import { Telemetry } from '../session/telemetry.ts';
+import type { ConnectionView } from '../session/connection-view.ts';
+import type { ControllerStore } from '../state.ts';
+/** Connection inputs resolved by the CLI or a library consumer. */
+export interface ConnectionOptions {
+    base: string;
+    token: string | undefined;
+    initialSession: string | undefined;
+    /** Factory for one generation's client; replaced in tests. */
+    makeClient: () => Client;
+    /** Authentication used by every generation, including reconnects. */
+    authenticate: (client: Client) => Promise<void>;
+}
+/** Reactions the controller facade owes to connection lifecycle and host events. */
+export interface ConnectionListener {
+    /** A new generation starts; domains drop generation-scoped state. */
+    begin(): void;
+    /** The event stream is ready and the control baseline is applied. */
+    ready(): Promise<void>;
+    /** The generation ended and its socket is closed. */
+    ended(): Promise<void>;
+    /** Deliver a host waterfall; return true when a domain retained it for an answer. */
+    waterfall(frame: ObjectValue): boolean;
+    /** The host cancelled a waterfall a domain retained. */
+    cancelled(eventId: string): void;
+    /** The host reported one session's running state. */
+    status(sessionId: string, running: boolean): void;
+    /** The host reported one session's error. */
+    error(sessionId: unknown, error: unknown): void;
+    /** Model catalogs may have changed. */
+    invalidated(): void;
+    /** A turn finished, so billing may refresh. */
+    idle(): void;
+}
+/** Owns reconnects, subscriptions and the telemetry generation. User commands remain single-attempt operations. */
+export declare class ConnectionController implements HostAccess, ConnectionView {
+    private readonly store;
+    private readonly options;
+    private readonly listener;
+    telemetry: Telemetry;
+    clientId: string;
+    private readonly runningUpdates;
+    private readonly observedRunningAt;
+    private current;
+    private readonly abort;
+    private runTask;
+    private generationFailed;
+    constructor(store: ControllerStore, options: ConnectionOptions, listener: ConnectionListener);
+    /** 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>;
+    /** @returns The connected client, or undefined while offline. */
+    client(): Client | undefined;
+    /** @returns The connected client, or throws while offline. */
+    require(): Client;
+    /** @returns Whether the current generation applied its host baseline. */
+    online(): boolean;
+    /** @returns The client lifetime signal. */
+    signal(): AbortSignal;
+    /** @returns The projection store of the current generation. */
+    telemetryView(): Telemetry;
+    /** @returns Cached host running state, or undefined when never reported. */
+    runningFor(sessionId: string): boolean | undefined;
+    /** @returns When this client first observed the session, for the elapsed-time fallback. */
+    observedAt(sessionId: string): number | undefined;
+    /** Record an observation start for a session this client just opened. */
+    observe(sessionId: string): void;
+    /** Fail the current generation, so the controller reopens a snapshot. */
+    fail(error: Error): void;
+    /** Answer one retained host waterfall through the event-result endpoint. */
+    reply(frame: ObjectValue, outcome: ObjectValue): Promise<void>;
+    /** Run one generation, then retry with bounded jittered backoff until stopped. */
+    private run;
+    /** Apply one `api-session/status` notification to the running maps and the session view. */
+    private acceptStatus;
+}

package/dist/controller/connection.js

@@ -0,0 +1,190 @@
+/** Owns the physical connection, its generations, and the host event subscriptions. */
+import { setTimeout as delay } from 'node:timers/promises';
+import { AuthenticationRequired } from "../transport/auth.js";
+import { HttpError, RemoteError } from "../transport/client.js";
+import { array, errorText, object, string } from "../transport/wire.js";
+import { Telemetry } from "../session/telemetry.js";
+/** Projection keys this client consumes; the host retains every other capability. */
+const RETAINED_PROJECTIONS = new Set(['title', 'modelSelection', 'contextPressure', 'tokenUsage', 'sessionStats', 'agentPreset']);
+/** Host events that invalidate the model catalog. */
+const CATALOG_EVENTS = ['llm/adapters-updated', 'settings/document-updated', 'credentials/reference-updated'];
+/** Owns reconnects, subscriptions and the telemetry generation. User commands remain single-attempt operations. */
+export class ConnectionController {
+    store;
+    options;
+    listener;
+    telemetry = new Telemetry(RETAINED_PROJECTIONS);
+    clientId = '';
+    runningUpdates = new Map();
+    observedRunningAt = new Map();
+    current;
+    abort = new AbortController();
+    runTask;
+    generationFailed;
+    constructor(store, options, listener) {
+        this.store = store;
+        this.options = options;
+        this.listener = listener;
+    }
+    /** Start one retry loop, with a fresh snapshot generation after every disconnect. */
+    start() { this.runTask ??= this.run(); }
+    /** Cancel retries and HTTP, close the socket, and wait for the loop to settle. */
+    async stop() {
+        this.abort.abort();
+        this.generationFailed?.(new Error('Client stopped'));
+        await this.current?.close();
+        await this.runTask;
+    }
+    /** @returns The connected client, or undefined while offline. */
+    client() { return this.current; }
+    /** @returns The connected client, or throws while offline. */
+    require() {
+        if (!this.current || !this.store.state.online)
+            throw new Error('Not connected');
+        return this.current;
+    }
+    /** @returns Whether the current generation applied its host baseline. */
+    online() { return this.store.state.online; }
+    /** @returns The client lifetime signal. */
+    signal() { return this.abort.signal; }
+    /** @returns The projection store of the current generation. */
+    telemetryView() { return this.telemetry; }
+    /** @returns Cached host running state, or undefined when never reported. */
+    runningFor(sessionId) { return this.runningUpdates.get(sessionId); }
+    /** @returns When this client first observed the session, for the elapsed-time fallback. */
+    observedAt(sessionId) { return this.observedRunningAt.get(sessionId); }
+    /** Record an observation start for a session this client just opened. */
+    observe(sessionId) { if (!this.observedRunningAt.has(sessionId))
+        this.observedRunningAt.set(sessionId, Date.now()); }
+    /** Fail the current generation, so the controller reopens a snapshot. */
+    fail(error) { this.generationFailed?.(error); }
+    /** Answer one retained host waterfall through the event-result endpoint. */
+    async reply(frame, outcome) {
+        await this.require().call('$events/result', { clientId: this.clientId, eventId: string(frame.eventId), outcome });
+    }
+    /** Run one generation, then retry with bounded jittered backoff until stopped. */
+    async run() {
+        let attempt = 0;
+        while (!this.abort.signal.aborted) {
+            this.runningUpdates.clear();
+            this.observedRunningAt.clear();
+            this.telemetry = new Telemetry(RETAINED_PROJECTIONS);
+            this.listener.begin();
+            const client = this.options.makeClient();
+            this.current = client;
+            try {
+                await this.options.authenticate(client);
+                await client.connect();
+                let fail;
+                const disconnected = new Promise(resolve => { fail = resolve; });
+                this.generationFailed = fail;
+                const ready = new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error('Host ready timed out')), client.timeoutMs);
+                    client.subscribe('$events', {}, {
+                        item: value => {
+                            const frame = object(value);
+                            if (frame.type === 'ready') {
+                                this.clientId = string(frame.clientId);
+                                clearTimeout(timer);
+                                resolve();
+                            }
+                            else if (frame.type === 'waterfall') {
+                                if (this.listener.waterfall(frame))
+                                    return;
+                                void client.call('$events/result', { clientId: this.clientId,
+                                    eventId: string(frame.eventId), outcome: { kind: 'next' } }).catch(error => fail(new Error(errorText(error))));
+                            }
+                            else if (frame.type === 'cancel') {
+                                this.listener.cancelled(string(frame.eventId));
+                            }
+                            else if (frame.type === 'emit' && frame.event === 'api-session/status') {
+                                this.acceptStatus(array(frame.args));
+                            }
+                            else if (frame.type === 'emit' && CATALOG_EVENTS.includes(String(frame.event))) {
+                                this.listener.invalidated();
+                            }
+                            else if (frame.type === 'emit' && frame.event === 'api-session/error') {
+                                const args = array(frame.args);
+                                this.listener.error(args[0], args[1]);
+                            }
+                        },
+                        end: error => { clearTimeout(timer); const reason = error ?? new Error('Event stream ended'); reject(reason); fail(reason); },
+                    });
+                });
+                await ready;
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error('Session control baseline timed out')), client.timeoutMs);
+                    client.subscribe('session/control', {}, {
+                        item: value => {
+                            try {
+                                this.telemetry.accept(value);
+                                this.store.update({});
+                                clearTimeout(timer);
+                                resolve();
+                            }
+                            catch (error) {
+                                clearTimeout(timer);
+                                reject(error);
+                                fail(new Error(errorText(error)));
+                            }
+                        },
+                        end: error => {
+                            clearTimeout(timer);
+                            if (error instanceof RemoteError && error.code === 'gateway/method-unavailable') {
+                                this.store.update({ controlError: 'Live metrics unavailable on this host' });
+                                resolve();
+                            }
+                            else {
+                                const reason = error ?? new Error('Session control stream ended');
+                                reject(reason);
+                                fail(reason);
+                            }
+                        },
+                    });
+                });
+                await this.listener.ready();
+                attempt = 0;
+                const error = await disconnected;
+                if (!this.abort.signal.aborted)
+                    throw error;
+            }
+            catch (error) {
+                if (error instanceof AuthenticationRequired || error instanceof HttpError && [401, 403].includes(error.status)) {
+                    this.store.update({ error: `${errorText(error)}. Set DSH_TOKEN and restart to log in.`, status: 'Login required' });
+                    return;
+                }
+                if (!this.abort.signal.aborted)
+                    this.store.update({ error: errorText(error), status: 'Reconnecting…' });
+            }
+            finally {
+                this.generationFailed = undefined;
+                this.store.update({ online: false, pending: [] });
+                await client.close();
+                await this.listener.ended();
+            }
+            if (!this.abort.signal.aborted) {
+                try {
+                    await delay(Math.min(500 * 2 ** attempt++, 10_000) * (0.8 + Math.random() * 0.4), undefined, { signal: this.abort.signal });
+                }
+                catch (error) {
+                    if (!this.abort.signal.aborted)
+                        throw error;
+                }
+            }
+        }
+    }
+    /** Apply one `api-session/status` notification to the running maps and the session view. */
+    acceptStatus(args) {
+        const sessionId = string(args[0]);
+        if (typeof args[1] !== 'boolean')
+            throw new Error('Invalid session running state');
+        if (args[1] && !this.runningUpdates.get(sessionId))
+            this.observedRunningAt.set(sessionId, Date.now());
+        if (!args[1])
+            this.observedRunningAt.delete(sessionId);
+        this.runningUpdates.set(sessionId, args[1]);
+        this.listener.status(sessionId, args[1]);
+        if (!args[1])
+            this.listener.idle();
+    }
+}

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';