@itookit/dsht 0.3.0 → 0.3.2

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;
+}

package/dist/controller/memory-log.js

@@ -0,0 +1,95 @@
+/** Runtime memory samples appended to one bounded local file for diagnosing growth over a long run. */
+import { appendPrivateFile, createPrivateFile, writePrivateFile } from "../storage/index.js";
+import { errorText } from "../transport/wire.js";
+/** Time between automatic samples. */
+const SAMPLE_INTERVAL_MS = 30_000;
+/** Samples kept; reaching the cap rewrites the file with just these lines. */
+const KEEP_SAMPLES = 1000;
+/** First line of the file, so an empty or rewritten log still explains itself. */
+const HEADER = '# dsht memory samples: one JSON object per line, oldest first\n';
+/** 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 class MemoryLog {
+    path;
+    sampleSource;
+    timer;
+    appended = [];
+    writing = false;
+    /** Last write failure, when the log stopped itself. */
+    error;
+    constructor(path, sampleSource) {
+        this.path = path;
+        this.sampleSource = sampleSource;
+    }
+    /** Write the header into a new file, then sample once; a missing or unwritable path is reported
+     * by that first sample instead of here.
+     */
+    async begin() {
+        if (this.path === undefined)
+            return;
+        try {
+            await createPrivateFile(this.path, HEADER);
+        }
+        catch { /* the sample below reports it */ }
+        await this.sample();
+    }
+    /** Sample once now and then every `SAMPLE_INTERVAL_MS`; absent when no path was configured. */
+    start() {
+        if (this.path === undefined || this.timer !== undefined)
+            return;
+        void this.begin();
+        this.timer = setInterval(() => { void this.sample(); }, SAMPLE_INTERVAL_MS);
+    }
+    /** Stop sampling and rewrite the file with its retained window. */
+    async stop() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+        await this.compact();
+    }
+    /** 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.
+     */
+    async sample() {
+        if (this.path === undefined || this.writing)
+            return;
+        this.writing = true;
+        try {
+            const line = `${JSON.stringify(this.sampleSource())}\n`;
+            await appendPrivateFile(this.path, line);
+            this.appended.push(line);
+            this.error = undefined;
+            if (this.appended.length >= KEEP_SAMPLES)
+                await this.compact();
+        }
+        catch (error) {
+            this.error = errorText(error);
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    /** Rewrite the file with the header and the newest kept lines, bounding its size. */
+    async compact() {
+        if (this.path === undefined || this.appended.length === 0)
+            return;
+        const lines = this.appended.slice(-KEEP_SAMPLES);
+        try {
+            await writePrivateFile(this.path, HEADER + lines.join(''));
+            this.appended = lines;
+        }
+        catch (error) {
+            // Appending continues to the existing file, so a failed rewrite only delays the bound.
+            this.error = errorText(error);
+        }
+    }
+}

package/dist/cost/controller.d.ts

@@ -0,0 +1,34 @@
+/** Periodic billing scans; the ledger outlives any single connection generation. */
+import type { Client } from '../transport/client.ts';
+import type { CostLedger } from './ledger.ts';
+/** Host access a scan needs; supplied by the controller facade. */
+export interface CostHost {
+    /** Connected client, or undefined while offline. */
+    client(): Client | undefined;
+    /** Whether the current connection generation is online. */
+    online(): boolean;
+    /** Client lifetime signal, aborted when the process closes the connection. */
+    signal(): AbortSignal;
+    /** Re-publish controller state after the ledger changes. */
+    publish(): void;
+}
+/** Owns the background scan: startup, the minute timer, turn-completion refresh, and `/cost`. */
+export declare class CostController {
+    readonly ledger: CostLedger;
+    private readonly host;
+    private task;
+    private abort;
+    private timer;
+    private updates;
+    constructor(ledger: CostLedger, host: CostHost);
+    /** Scan immediately, then once a minute while online. */
+    start(): void;
+    /** Stop the timer and wait for an in-flight scan; the ledger keeps its cached charges. */
+    stop(): Promise<void>;
+    /** Refresh after the host reports a turn complete. */
+    onTurnIdle(): void;
+    /** Refresh all HTTP-visible sessions without changing the selected conversation.
+     * @param signal - Optional cancellation for an explicit `/cost` refresh.
+     */
+    refresh(signal?: AbortSignal): Promise<void>;
+}

package/dist/cost/controller.js

@@ -0,0 +1,107 @@
+import { array, errorText, object, string } from "../transport/wire.js";
+import { sessionCostHistory } from "./scanner.js";
+/** Refresh interval for the background cost scan. */
+const REFRESH_INTERVAL_MS = 60_000;
+/** Owns the background scan: startup, the minute timer, turn-completion refresh, and `/cost`. */
+export class CostController {
+    ledger;
+    host;
+    task;
+    abort;
+    timer;
+    updates = new Map();
+    constructor(ledger, host) {
+        this.ledger = ledger;
+        this.host = host;
+    }
+    /** Scan immediately, then once a minute while online. */
+    start() {
+        if (this.timer)
+            return;
+        void this.refresh().catch(() => undefined);
+        this.timer = setInterval(() => { if (this.host.online())
+            void this.refresh().catch(() => undefined); }, REFRESH_INTERVAL_MS);
+    }
+    /** Stop the timer and wait for an in-flight scan; the ledger keeps its cached charges. */
+    async stop() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+        await this.task;
+    }
+    /** Refresh after the host reports a turn complete. */
+    onTurnIdle() {
+        if (this.host.online())
+            void this.refresh().catch(() => undefined);
+    }
+    /** Refresh all HTTP-visible sessions without changing the selected conversation.
+     * @param signal - Optional cancellation for an explicit `/cost` refresh.
+     */
+    async refresh(signal = this.host.signal()) {
+        if (this.task) {
+            const cancel = () => this.abort?.abort();
+            signal.addEventListener('abort', cancel, { once: true });
+            try {
+                await this.task;
+            }
+            finally {
+                signal.removeEventListener('abort', cancel);
+            }
+            return;
+        }
+        const client = this.host.client();
+        if (!client)
+            throw new Error('Not connected');
+        this.abort = new AbortController();
+        const combined = AbortSignal.any([signal, this.host.signal(), this.abort.signal]);
+        const ledger = this.ledger;
+        ledger.scanning = true;
+        ledger.error = '';
+        this.host.publish();
+        const task = (async () => {
+            try {
+                const sessions = array(object(await client.call('session/list', { _request: {} }, combined)).items).map(object);
+                combined.throwIfAborted();
+                const failures = [];
+                let scanned = 0, pages = 0, events = 0;
+                for (const session of sessions) {
+                    combined.throwIfAborted();
+                    const sessionId = string(session.sessionId);
+                    if (!session.running && typeof session.updatedAt === 'number' && this.updates.get(sessionId) === session.updatedAt)
+                        continue;
+                    try {
+                        const history = await sessionCostHistory(client, session, combined, () => { pages++; });
+                        scanned++;
+                        events += history.events.length;
+                        await ledger.replace(sessionId, history.cursor, history.events);
+                        if (!session.running && typeof session.updatedAt === 'number')
+                            this.updates.set(sessionId, session.updatedAt);
+                        this.host.publish();
+                    }
+                    catch (error) {
+                        // One unreachable or rejected session must not freeze every other session's rates.
+                        combined.throwIfAborted();
+                        failures.push(`${sessionId}: ${errorText(error)}`);
+                    }
+                }
+                ledger.error = failures.length === 0 ? '' : `${failures.length} of ${sessions.length} sessions failed: ${failures[0]}`;
+                ledger.lastScan = { sessions: scanned, pages, events };
+                ledger.scannedAt = Date.now();
+            }
+            catch (error) {
+                ledger.error = errorText(error);
+            }
+            finally {
+                ledger.scanning = false;
+                this.host.publish();
+            }
+        })();
+        this.task = task;
+        try {
+            await task;
+        }
+        finally {
+            this.task = undefined;
+            this.abort = undefined;
+        }
+    }
+}

package/dist/cost/index.d.ts

@@ -0,0 +1,9 @@
+/** Cost domain: price tables, record folding, the immutable ledger, the scanner and its controller. */
+export { CostController } from './controller.ts';
+export type { CostHost } from './controller.ts';
+export { CostLedger, costText } from './ledger.ts';
+export { chargeFor, costDay, DEFAULT_PRICES, lowestPrice, priceAt, pricesFrom } from './pricing.ts';
+export { costRecords, foldSamples } from './records.ts';
+export { costAddresses, sessionCostHistory } from './scanner.ts';
+export { MISSING_USAGE } from './types.ts';
+export type { Charge, ChargeSample, CostTotal, Coverage, PriceDecision, PriceVersion, Rates, SavedCost, Usage } from './types.ts';

package/dist/cost/index.js

@@ -0,0 +1,7 @@
+/** Cost domain: price tables, record folding, the immutable ledger, the scanner and its controller. */
+export { CostController } from "./controller.js";
+export { CostLedger, costText } from "./ledger.js";
+export { chargeFor, costDay, DEFAULT_PRICES, lowestPrice, priceAt, pricesFrom } from "./pricing.js";
+export { costRecords, foldSamples } from "./records.js";
+export { costAddresses, sessionCostHistory } from "./scanner.js";
+export { MISSING_USAGE } from "./types.js";