@itookit/dsht 0.3.0 → 0.3.3

package/dist/cost/scanner.js

@@ -0,0 +1,95 @@
+/** Address and page one session's complete billing history over the host connection. */
+import { RemoteError } from "../transport/client.js";
+import { array, errorText, object, string } from "../transport/wire.js";
+import { costRecords } from "./records.js";
+/** Wire addresses for one `session/list` row, in the order the cost scan should try them.
+ *
+ * A subagent child is reachable only under its durable parent, and the list row omits the delivery
+ * mode, so both modes are offered with the continuable form first.
+ * @param session - One row from the host session list.
+ * @returns One plain-session address, or both subagent forms when the row is a child.
+ */
+export function costAddresses(session) {
+    const sessionId = string(session.sessionId);
+    const parentSessionId = typeof session.parentSessionId === 'string' ? session.parentSessionId : '';
+    if (session.origin !== 'subagent' || parentSessionId === '')
+        return [{ kind: 'session', sessionId }];
+    return [
+        { kind: 'subagent', parentSessionId, childSessionId: sessionId, mode: 'continuable' },
+        { kind: 'subagent', parentSessionId, childSessionId: sessionId, mode: 'one-shot' },
+    ];
+}
+/** Read one session's complete cost history, retrying a subagent child with its other delivery mode.
+ * @param client - Authenticated host transport.
+ * @param session - One row from the host session list.
+ * @param signal - Cancels paging without cancelling any agent work.
+ * @param onPage - Counts each history request, so a scan can report how much it re-read.
+ * @returns Opening cursor and the minimal billing events behind it.
+ */
+export async function sessionCostHistory(client, session, signal, onPage) {
+    let lastError;
+    for (const address of costAddresses(session)) {
+        try {
+            return await readCostHistory(client, address, signal, onPage);
+        }
+        catch (error) {
+            lastError = error;
+            // Only a delivery-mode mismatch justifies the other form; every other failure is final here.
+            if (!(error instanceof RemoteError && error.code === 'subagent/unauthorized'))
+                throw error;
+        }
+    }
+    throw lastError;
+}
+/** Page one addressed session's history into the billing events the ledger folds. */
+async function readCostHistory(client, address, signal, onPage) {
+    onPage?.();
+    const snapshot = await new Promise((resolve, reject) => {
+        let sub;
+        const timeout = setTimeout(() => finish(new Error('Cost history snapshot timed out')), client.timeoutMs);
+        const onAbort = () => finish(new Error('Cost refresh cancelled'));
+        const finish = (error, frame) => {
+            clearTimeout(timeout);
+            signal.removeEventListener('abort', onAbort);
+            sub?.cancel();
+            if (error)
+                reject(error);
+            else
+                resolve(frame);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            sub = client.subscribe('session/follow', { request: { address, maxMessages: 80, assistantStream: true } }, {
+                item: value => { const frame = object(value); if (frame.type === 'snapshot')
+                    finish(undefined, frame); },
+                end: error => finish(error ?? new Error('Cost history stream ended')),
+            });
+        }
+        catch (error) {
+            finish(error instanceof Error ? error : new Error(errorText(error)));
+        }
+    });
+    const cursor = snapshot.cursor;
+    if (typeof cursor !== 'number' || !Number.isSafeInteger(cursor))
+        throw new Error('Invalid cost history cursor');
+    let page = snapshot;
+    const events = [];
+    while (true) {
+        signal.throwIfAborted();
+        const records = array(page.records);
+        events.push(...costRecords(records));
+        if (!page.hasMore)
+            break;
+        const seqs = records.map(r => object(object(r).event).seq);
+        if (!seqs.length || seqs.some(n => typeof n !== 'number' || !Number.isSafeInteger(n)))
+            throw new Error('Invalid cost history page');
+        const beforeSeq = Math.min(...seqs);
+        onPage?.();
+        page = object(await client.call('session/page', { request: { address, throughSeq: cursor, beforeSeq, maxMessages: 80 } }, signal));
+        if (page.hasMore && array(page.records).every(r => Number(object(object(r).event).seq) >= beforeSeq))
+            throw new Error('Cost history page did not advance');
+    }
+    if (object(snapshot.header).isSeeded === true && !events.some(e => e.type === 'session/end-seed' && object(e.data).inherited === true))
+        throw new Error('Cannot attribute inherited session usage');
+    return { cursor, events };
+}

package/dist/cost/types.d.ts

@@ -0,0 +1,85 @@
+/** Cost-domain types shared by pricing, record folding, storage and the in-memory ledger. */
+/** Per-million-token rates for one peak or off-peak bucket. */
+export interface Rates {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
+/** An explicit validity interval and weekday peak windows in the named time zone. */
+export interface PriceVersion {
+    id: string;
+    provider: string;
+    model: string;
+    /** Further model names this version prices; a trailing `*` matches a prefix. Never a guess. */
+    aliases?: string[];
+    from: string;
+    until?: string;
+    currency: 'CNY';
+    source: string;
+    timezone: string;
+    peak: Rates;
+    offPeak: Rates;
+    weekdays: number[];
+    windows: [number, number][];
+}
+/** Disjoint token buckets reported for one model request. */
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** One folded request sample: the attempt identity and the facts a price decision needs. */
+export interface ChargeSample {
+    key: string;
+    time?: number;
+    provider: string;
+    model: string;
+    usage?: Usage;
+}
+/** What the table decides for one request sample: an amount, or the reason it has none. */
+export interface PriceDecision {
+    amount?: number;
+    reason?: string;
+}
+/** Summary retains the known subtotal and the records it could not price.
+ * `unknown` counts records with no amount; `records` counts every request the range covers, so a
+ * subtotal is never read as complete without them.
+ */
+export interface CostTotal {
+    amount: number;
+    unknown: number;
+    records: number;
+}
+/** One Beijing calendar day's requests, kept only for the day a scan ran on. */
+export interface DayTotal extends CostTotal {
+    day: string;
+}
+/** One session's persisted ledger slice.
+ *
+ * The host log and the loaded price table are the only inputs, so the slice stores the totals one
+ * scan folded them into and no per-request detail: the next scan reads the session's history again
+ * and decides every sample with the table loaded then. `engine` and `catalog` name the decision
+ * rules and the table behind these totals, so a process holding an older one cannot overwrite them.
+ */
+export interface SavedCost {
+    version: 3;
+    sessionId: string;
+    /** Durable sequence the fold reached; a scan that opened an older cut may not replace this slice. */
+    cut: number;
+    engine: number;
+    catalog: string;
+    total: CostTotal;
+    day: DayTotal;
+    /** Distinct reasons an amount is missing, bounded, so a panel can say what makes a total inexact. */
+    unpriced: string[];
+}
+/** How much of the visible history the cached ledger currently covers. */
+export type Coverage = 'complete' | 'scanning' | 'partial';
+/** Reason recorded when a sample carries no usable token counts. */
+export declare const MISSING_USAGE = "missing usage";
+/** Reason recorded when the host reported a cache-write bucket the published table does not price. */
+export declare const UNSUPPORTED_USAGE = "unsupported usage";
+/** Reason recorded when the request has no settlement time to place it in a peak band or a day. */
+export declare const MISSING_TIME = "missing time";

package/dist/cost/types.js

@@ -0,0 +1,7 @@
+/** Cost-domain types shared by pricing, record folding, storage and the in-memory ledger. */
+/** Reason recorded when a sample carries no usable token counts. */
+export const MISSING_USAGE = 'missing usage';
+/** Reason recorded when the host reported a cache-write bucket the published table does not price. */
+export const UNSUPPORTED_USAGE = 'unsupported usage';
+/** Reason recorded when the request has no settlement time to place it in a peak band or a day. */
+export const MISSING_TIME = 'missing time';

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** Published library entry: the reusable host client and its error types. */
+export { Client, HttpError, RemoteError } from './transport/client.ts';
+export type { Subscription } from './transport/client.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+/** Published library entry: the reusable host client and its error types. */
+export { Client, HttpError, RemoteError } from "./transport/client.js";

package/dist/session/connection-view.d.ts

@@ -0,0 +1,18 @@
+/** What the session domain reads from the connection the controller owns. */
+import type { Telemetry } from './telemetry.ts';
+import type { ObjectValue } from '../transport/wire.ts';
+/** Read-only connection facts and actions the session controller needs. */
+export interface ConnectionView {
+    /** Projection store of the current generation. */
+    telemetryView(): Telemetry;
+    /** Cached host running flag for one session, or undefined when never reported. */
+    runningFor(sessionId: string): boolean | undefined;
+    /** 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>;
+}

package/dist/session/connection-view.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,143 +1,84 @@
-import { Client } from './client.ts';
-import { CostLedger } from './cost.ts';
-import { Telemetry } from './telemetry.ts';
-import { Transcript } from './transcript.ts';
-import { type HistoryLimits } from './memory.ts';
+import type { HostAccess } from '../transport/host.ts';
+import { type Json, type ObjectValue } from '../transport/wire.ts';
+import type { ControllerStore, State } from '../state.ts';
+import type { HistoryLimits } from './memory.ts';
 import { type FileReference } from './references.ts';
-import { type Json, type ObjectValue } from './wire.ts';
-/** Resolved navigation-removal identity; empty marks a fresh blank, idle session eligible for immediate archival. */
-export interface RemovalTarget {
-    kind: 'workspace' | 'session';
-    id: string;
-    name: string;
-    path?: string;
-    empty?: boolean;
-}
-/** State shared by the picker and conversation view. */
-export interface State {
-    version: number;
-    online: boolean;
-    busy: boolean;
-    screen: 'workspaces' | 'sessions' | 'chat' | 'path';
-    status: string;
-    error: string;
-    workspaces: ObjectValue[];
-    sessions: ObjectValue[];
-    showAllSessions: boolean;
-    workspaceId?: string;
-    sessionId?: string;
-    pending: ObjectValue[];
-    controlError?: string;
-    modelError?: string;
-    presetError?: string;
-    presets?: ObjectValue[];
-    defaultModel?: ObjectValue;
-    transcript: Transcript;
-}
-/** Bounded search results contain navigation summaries, never complete message bodies. */
-export interface HistorySearch {
-    items: {
-        seq: number;
-        role: string;
-        preview: string;
-    }[];
-    truncated: boolean;
-}
-/** Wire addresses for one `session/list` row, in the order the cost scan should try them.
- *
- * A subagent child is reachable only under its durable parent, and the list row omits the delivery
- * mode, so both modes are offered with the continuable form first.
- * @param session - One row from the host session list.
- * @returns One plain-session address, or both subagent forms when the row is a child.
- */
-export declare function costAddresses(session: ObjectValue): ObjectValue[];
-/** Owns reconnects and subscriptions. User commands remain single-attempt operations. */
-export declare class Controller {
-    readonly base: string;
-    readonly initialSession?: string | undefined;
-    private makeClient;
-    private authenticate;
-    readonly costs?: CostLedger | undefined;
-    readonly historyLimits: HistoryLimits;
-    state: State;
-    private observers;
-    private interactions;
-    private abort;
-    private client;
-    private clientId;
+import { Transcript } from './transcript.ts';
+import type { ConnectionView } from './connection-view.ts';
+import type { HistorySearch, RemovalTarget } from './types.ts';
+/** Owns the selected session: its follow stream, transcript, history window and interactions. */
+export declare class SessionController {
+    private readonly store;
+    private readonly host;
+    private readonly connection;
+    private readonly historyLimits;
     private follow;
-    private runTask;
-    private generationFailed;
-    private selection;
+    private interactions;
     private historyPinned;
-    telemetry: Telemetry;
-    private observedRunningAt;
-    private presetClient?;
-    private catalogRevision;
-    private catalogTasks;
-    private runningUpdates;
     private stoppingSession?;
     private interruptTask;
     private admission;
-    private costUpdates;
-    private costAbort?;
-    private costTask;
-    private costTimer;
+    constructor(store: ControllerStore, host: HostAccess, connection: ConnectionView, historyLimits: HistoryLimits);
     /** Host running state covers model generation, tools, and waits between assistant attempts. */
     get running(): boolean;
     /** Current title projection, falling back to the list title and then the session ID. */
     get sessionName(): string | undefined;
     /** Current agent-preset name, matching the web header's built-in labels and custom metadata. */
     get sessionMode(): string | undefined;
-    /** Load the optional preset roster once per connection, only when a session names a preset. */
-    loadPresetNames(): void;
-    /** Fetch current model routes and adapter-owned reasoning choices for the selected session.
-     * @returns Host catalog; provider failures remain available to the selector.
-     */
-    modelCatalog(): Promise<ObjectValue>;
-    /** Select the next request's model; the host also attempts to save its deployment default.
-     * @param provider - Host provider route ID.
-     * @param model - Exact model ID.
-     * @param reasoningEffort - Optional adapter-owned effort ID; omission uses its default.
-     */
-    selectModel(provider: string, model: string, reasoningEffort?: string): Promise<void>;
     /** Epoch start from the retained turn log, or when this client first observed the run. */
     get workingSince(): number | undefined;
+    /** Present only sessions explicitly accounted to the selected workspace. */
+    get visibleSessions(): ObjectValue[];
+    /** Whether a turn, cancellation or prompt admission is still in flight. */
+    get active(): boolean;
+    /** Whether reading protects the loaded window, suspending history reclamation. */
+    get pinned(): boolean;
+    /** Drop generation-scoped state before a new connection generation begins. */
+    beginGeneration(): void;
+    /** Invalidate in-flight work and drop transient interactions when a generation ends. */
+    endGeneration(): void;
+    /** Wait for an in-flight cancellation so shutdown leaves nothing running. */
+    settle(): Promise<void>;
+    /** Release the selected transcript and its layout caches. */
+    release(): void;
+    /** Pending interactions for the selected chat session, derived independently of frame order.
+     * @param state - State being published.
+     * @returns Retained question and approval frames for that session.
+     */
+    pendingFor(state: State): ObjectValue[];
+    /** Retain a recognized host waterfall; unknown events stay with the connection to delegate.
+     * @param frame - One decoded waterfall frame.
+     * @returns Whether this domain retained the frame for an answer.
+     */
+    waterfall(frame: ObjectValue): boolean;
+    /** Drop a waterfall the host cancelled.
+     * @param eventId - Correlation id previously retained.
+     */
+    cancelled(eventId: string): void;
+    /** Apply one host running-state notification to the session list and status line.
+     * @param sessionId - Session whose state changed.
+     * @param running - Whether the host still runs that session.
+     */
+    status(sessionId: string, running: boolean): void;
+    /** Surface a host-reported error for the selected session.
+     * @param sessionId - Session the host reported on.
+     * @param error - Error payload as delivered by the host.
+     */
+    reportError(sessionId: unknown, error: unknown): void;
     /** Stop the selected turn, or allow exit only while idle. Repeated keys share one request.
      * @param force - Send an explicit cancellation even when the cached running flag is idle.
      * @returns True when the caller may exit; cancellation failures retain the client.
      */
     interrupt(force?: boolean): Promise<boolean>;
-    constructor(base: string, token: string | undefined, initialSession?: string | undefined, makeClient?: () => Client, authenticate?: (client: Client) => Promise<void>, costs?: CostLedger | undefined, historyLimits?: HistoryLimits);
-    /** React-compatible state subscription. */
-    subscribe: (listener: () => void) => (() => void);
-    /** Snapshot identity changes only when the controller publishes. */
-    snapshot: () => State;
-    /** Start one retry loop, with a fresh snapshot generation after every disconnect. */
-    start(): void;
-    /** Cancel retries and HTTP, close the socket, and wait for the loop to settle. */
-    stop(): Promise<void>;
     /** Keep history stable while the user reads, searches, or expands it; trim again at the live tail.
      * @param pinned - Whether the main transcript is actively being read away from its tail.
      */
     pinHistory(pinned: boolean): void;
-    private reclaimHistory;
-    private releaseTranscript;
-    /** Stop the selected turn and then close, so quitting does not leave host work running.
-     * An idle session stays untouched, and an in-flight cancellation is awaited rather than repeated.
-     */
-    shutdown(): Promise<void>;
-    /** Run a UI operation and expose errors without destroying the current input. */
-    perform(operation: () => Promise<void>): Promise<boolean>;
-    /** Refresh all HTTP-visible sessions without changing the selected conversation.
-     * @param signal - Optional cancellation for an explicit /cost refresh.
-     */
-    refreshCosts(signal?: AbortSignal): Promise<void>;
-    /** Read one session's complete cost history, retrying a subagent child with its other delivery mode. */
-    private sessionCostHistory;
-    /** Page one addressed session's history into the billing events the ledger folds. */
-    private readCostHistory;
-    /** Refresh both lists from the host, then show the requested picker. */
+    /** Cancel the active turn; pending queue items remain host-owned. */
+    cancelTurn(): Promise<void>;
+    /** Refresh both lists from the host, then show the requested picker.
+     * @param screen - Picker to display after the refresh.
+     */
     showPicker(screen: 'workspaces' | 'sessions'): Promise<void>;
     /** Resolve a removal command to one reviewable object without changing the selection.
      * @param kind - Workspace registration removal or session archival.
@@ -149,19 +90,29 @@ export declare class Controller {
      * @param target - Exact workspace or session identity reviewed by the user.
      */
     removeTarget(target: RemovalTarget): Promise<void>;
-    /** Pick a workspace, or use all sessions when the identity is omitted. */
+    /** Pick a workspace, or use all sessions when the identity is omitted.
+     * @param workspaceId - Workspace to select, if any.
+     */
     pickWorkspace(workspaceId?: string): void;
-    /** Open a workspace picker, or resolve a workspace by ID, exact title/path, or unique ID prefix. */
+    /** Open a workspace picker, or resolve a workspace by ID, exact title/path, or unique ID prefix.
+     * @param query - Workspace target, if any.
+     */
     switchWorkspace(query?: string): Promise<void>;
-    /** Guide workspace selection, list all sessions with `all`, or resolve an exact session target. */
+    /** Guide workspace selection, list all sessions with `all`, or resolve an exact session target.
+     * @param query - Session target, `all`, or nothing for the guided picker.
+     */
     switchSession(query?: string): Promise<void>;
     /** Prompt for a host path without starting a local agent. */
     enterPath(): void;
-    /** Register a host directory and move to its session picker. */
+    /** Register a host directory and move to its session picker.
+     * @param path - Absolute directory path on the host.
+     */
     createWorkspace(path: string): Promise<void>;
     /** Create a session only after the user explicitly selects New session. */
     createSession(): Promise<void>;
-    /** Replace the selected transcript and cancel its preceding follow stream. */
+    /** Replace the selected transcript and cancel its preceding follow stream.
+     * @param sessionId - Session to follow.
+     */
     selectSession(sessionId: string): Promise<void>;
     /** Wait for the selected follow snapshot, failing on disconnect or cancellation.
      * @param signal - Cancels waiting without closing the session.
@@ -199,11 +150,28 @@ export declare class Controller {
      * @returns Absolute saved filename.
      */
     exportLog(path: string | undefined, signal: AbortSignal): Promise<string>;
-    /** Admit text once as steering while running, or a new turn while idle; a lost response can leave delivery uncertain. */
+    /** Save the retained conversation with offline Markdown, diagrams and math.
+     * @param path - Optional destination; existing files are never overwritten.
+     * @param signal - Cancels the write.
+     * @returns Absolute saved filename.
+     */
+    exportHtml(path: string | undefined, signal: AbortSignal): Promise<string>;
+    /** Admit text once as steering while running, or a new turn while idle; a lost response can leave delivery uncertain.
+     * @param text - Composed prompt text.
+     */
     prompt(text: string): Promise<void>;
-    /** Cancel the active turn; pending queue items remain host-owned. */
-    cancelTurn(): Promise<void>;
-    /** Add a page before the retained window using its fixed opening cut. */
+    /** Answer the oldest selected-session interaction, after explicit user action.
+     * @param value - Structured answer value or approval outcome.
+     */
+    answer(value: Json): Promise<void>;
+    /** Restrict an approval command to an approval request.
+     * @param allowed - Whether the request is approved once.
+     */
+    approve(allowed: boolean): Promise<void>;
+    /** Add a page before the retained window using its fixed opening cut.
+     * @param signal - Cancels local paging without interrupting the remote agent.
+     * @param transcript - Transcript to extend; defaults to the live one.
+     */
     older(signal?: AbortSignal, transcript?: Transcript): Promise<void>;
     /** Search one page at a time, preserving only the first 200 matches and releasing temporary content.
      * @param query - Literal, case-insensitive text including folded reasoning.
@@ -222,16 +190,14 @@ export declare class Controller {
      * @param signal - Cancels local paging without interrupting the remote agent.
      */
     historyThrough(target: number | 'first', signal: AbortSignal): Promise<void>;
-    /** Answer the oldest selected-session interaction, after explicit user action. */
-    answer(value: Json): Promise<void>;
-    /** Restrict an approval command to an approval request. */
-    approve(allowed: boolean): Promise<void>;
-    /** Present only sessions explicitly accounted to the selected workspace. */
-    get visibleSessions(): ObjectValue[];
-    private get host();
+    /** Reclaim reloadable history unless the user is reading away from the tail.
+     * @returns Number of removed records.
+     */
+    private reclaimHistory;
+    /** Release the selected transcript and its layout caches. */
+    private releaseTranscript;
+    /** @returns The selected session identity, or a `Select a session first` failure. */
     private get sessionId();
-    private update;
+    /** Answer one retained waterfall through the connection's event-result endpoint. */
     private reply;
-    private refreshCatalog;
-    private run;
 }