@itookit/dsht 0.5.1 → 0.5.2

package/dist/session/prompt-backfill.js

@@ -0,0 +1,88 @@
+/** Bounded background recall indexing, owned by one selected record and connection lifetime. */
+import { setTimeout as delay } from 'node:timers/promises';
+import { object } from "../json.js";
+import { Transcript } from "./transcript.js";
+const PAGE_LIMIT = 200;
+export class PromptBackfill {
+    host;
+    cache;
+    tasks = new Set();
+    constructor(host, cache) {
+        this.host = host;
+        this.cache = cache;
+    }
+    cancel() { for (const task of this.tasks)
+        task.abort.abort(); }
+    async settle() { await Promise.allSettled([...this.tasks].map(task => task.promise)); }
+    start(selection) {
+        this.cancel();
+        const abort = new AbortController();
+        const signal = AbortSignal.any([abort.signal, this.host.signal()]);
+        const task = { abort, promise: Promise.resolve() };
+        // Register before dispatch, including before any reentrant host callback.
+        this.tasks.add(task);
+        task.promise = Promise.resolve().then(async () => {
+            const check = () => {
+                signal.throwIfAborted();
+                if (!this.host.online() || !this.host.current(selection))
+                    throw new Error('Session changed while indexing prompts');
+            };
+            check();
+            const client = this.host.require();
+            const deadline = Date.now() + client.timeoutMs;
+            const { record, prompts, sessionId } = selection;
+            while (!record.ready) {
+                check();
+                if (Date.now() >= deadline)
+                    throw new Error('Session snapshot timed out');
+                await delay(20, undefined, { signal });
+            }
+            check();
+            const adopt = () => {
+                const cached = this.cache.get(sessionId);
+                if (!cached?.complete)
+                    return false;
+                prompts.prepend(cached.prompts);
+                prompts.settle();
+                prompts.markComplete();
+                this.host.changed();
+                return true;
+            };
+            if (adopt())
+                return;
+            const throughSeq = record.readThrough;
+            let beforeSeq = record.beforeSeq, hasMore = record.hasMore;
+            for (let page = 0; hasMore && beforeSeq !== undefined && page < PAGE_LIMIT; page++) {
+                check();
+                const result = object(await client.call('session/page', { request: {
+                        address: { kind: 'session', sessionId }, throughSeq, beforeSeq, maxMessages: 80,
+                    } }, signal));
+                check();
+                const temporary = new Transcript();
+                try {
+                    temporary.accept({ type: 'snapshot', cursor: throughSeq, assistantStream: { revision: 0 }, records: result.records, hasMore: result.hasMore });
+                    const next = temporary.beforeSeq;
+                    if (temporary.hasMore && (next === undefined || next >= beforeSeq))
+                        throw new Error('Host history page did not advance');
+                    prompts.prepend(temporary.promptsSince(-1).prompts);
+                    // Bound each admitted page, even when the next request fails or never returns.
+                    prompts.settle();
+                    beforeSeq = next;
+                    hasMore = temporary.hasMore;
+                }
+                finally {
+                    temporary.dispose();
+                }
+                if (adopt())
+                    return;
+            }
+            if (!hasMore) {
+                prompts.markComplete();
+                this.cache.put(sessionId, { prompts: prompts.durableItems, complete: prompts.exhausted });
+            }
+            this.host.changed();
+        }).catch(() => {
+            // Cancellation or unavailable history leaves older prompts reachable through lazy paging.
+        }).finally(() => { this.tasks.delete(task); });
+    }
+}

package/dist/session/state.d.ts

@@ -0,0 +1,20 @@
+/** State and publication capabilities owned by the session domain. */
+import type { NavigationState } from './navigator.ts';
+import type { SessionInfo } from './info.ts';
+import type { PendingInteraction } from './types.ts';
+export interface SessionState extends NavigationState {
+    online: boolean;
+    status: string;
+    lastFailure: string;
+    pending: PendingInteraction[];
+    session: SessionInfo;
+}
+/** The connection and application derive online/pending; session actions cannot overwrite them. */
+export type SessionUpdate = Partial<Omit<SessionState, 'online' | 'pending' | 'session'>>;
+export interface SessionStore {
+    readonly state: Readonly<SessionState>;
+    update(patch: SessionUpdate): void;
+    selection(): number;
+    bumpSelection(): void;
+    busy(): boolean;
+}

package/dist/session/state.js

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

package/dist/session/telemetry.d.ts

@@ -5,11 +5,24 @@
  */
 import type { ControlFrame, ProjectionSnapshot, ProjectionValue, QueuedInput } from '../transport/events.ts';
 export type { QueuedInput } from '../transport/events.ts';
+export interface TelemetrySnapshot {
+    readonly values: Readonly<Record<string, ProjectionValue>>;
+    readonly queued?: number;
+    readonly jobs?: number;
+}
+/** The public reader has no projection acceptance or baseline replacement capability. */
+export interface TelemetryReader {
+    readonly ready: boolean;
+    view(id?: string): TelemetrySnapshot;
+    pending(id?: string): readonly Readonly<QueuedInput>[];
+}
 /** Generation-local projection, inbox and background-job data for every session. */
 export declare class Telemetry {
     private readonly retainedKeys?;
     private entries;
     private queues;
+    private readonly views;
+    readonly reader: TelemetryReader;
     private jobs;
     ready: boolean;
     /** Optionally retain only projection capabilities consumed by this client. */
@@ -27,15 +40,11 @@ export declare class Telemetry {
      * @param id - Selected session identity, if any.
      * @returns Projection values and known queue/job counts.
      */
-    view(id?: string): {
-        values: Readonly<Record<string, ProjectionValue>>;
-        queued?: number;
-        jobs?: number;
-    };
+    view(id?: string): TelemetrySnapshot;
     /** Read the selected session's authoritative pending inputs; absence means no observed queue.
      * @param id - Session identity.
      * @returns Pending inputs in host order.
      */
-    pending(id?: string): readonly QueuedInput[];
+    pending(id?: string): readonly Readonly<QueuedInput>[];
     private entry;
 }

package/dist/session/telemetry.js

@@ -1,13 +1,40 @@
+const EMPTY_VALUES = Object.freeze({});
+const EMPTY_QUEUE = Object.freeze([]);
+const EMPTY_VIEW = Object.freeze({ values: EMPTY_VALUES, queued: undefined, jobs: undefined });
+/** Copy on admission, not on render; no published nested object aliases a wire frame. */
+function retain(value) {
+    const copy = structuredClone(value);
+    const pending = [copy];
+    while (pending.length) {
+        const item = pending.pop();
+        if (item === null || typeof item !== 'object' || Object.isFrozen(item))
+            continue;
+        Object.freeze(item);
+        for (const child of Object.values(item))
+            pending.push(child);
+    }
+    return copy;
+}
+function retainQueue(items) {
+    return Object.freeze(items.map(item => Object.freeze({ ...item })));
+}
 /** Generation-local projection, inbox and background-job data for every session. */
 export class Telemetry {
     retainedKeys;
     entries = new Map();
     queues = new Map();
+    views = new Map();
+    reader;
     jobs = new Map();
     ready = false;
     /** Optionally retain only projection capabilities consumed by this client. */
     constructor(retainedKeys) {
         this.retainedKeys = retainedKeys;
+        const telemetry = this;
+        this.reader = Object.freeze({
+            get ready() { return telemetry.ready; },
+            view: (id) => this.view(id), pending: (id) => this.pending(id),
+        });
     }
     /** Replace all control state on a new stream baseline, then accept replacement frames.
      * @param frame - One normalized session/control frame.
@@ -17,10 +44,11 @@ export class Telemetry {
             this.entries.clear();
             this.queues.clear();
             this.jobs.clear();
+            this.views.clear();
             for (const [id, snapshot] of frame.projections)
                 this.snapshot(id, snapshot);
             for (const [id, items] of frame.queues)
-                this.queues.set(id, [...items]);
+                this.queues.set(id, retainQueue(items));
             for (const [id, count] of frame.jobs)
                 this.jobs.set(id, count);
             this.ready = true;
@@ -34,13 +62,14 @@ export class Telemetry {
                 return;
             if (this.retainedKeys && !this.retainedKeys.has(frame.key))
                 return;
-            entry.values[frame.key] = frame.value;
+            entry.values[frame.key] = retain(frame.value);
             entry.revisions.set(frame.key, frame.seq);
         }
         else if (frame.kind === 'queue')
-            this.queues.set(frame.sessionId, [...frame.items]);
+            this.queues.set(frame.sessionId, retainQueue(frame.items));
         else
             this.jobs.set(frame.sessionId, frame.count);
+        this.views.delete(frame.sessionId);
     }
     /** Merge a complete follow snapshot without restoring absent or older projection values.
      * @param id - Session identity.
@@ -58,26 +87,34 @@ export class Telemetry {
             if ((entry.revisions.get(key) ?? -1) > baseline.asOfSeq)
                 continue;
             if (Object.hasOwn(baseline.values, key))
-                entry.values[key] = baseline.values[key];
+                entry.values[key] = retain(baseline.values[key]);
             else
                 delete entry.values[key];
             entry.revisions.delete(key);
         }
         entry.baseline = baseline.asOfSeq;
+        this.views.delete(id);
     }
     /** Read current values for one session; missing capabilities remain absent.
      * @param id - Selected session identity, if any.
      * @returns Projection values and known queue/job counts.
      */
     view(id) {
-        return { values: id ? this.entries.get(id)?.values ?? {} : {},
-            queued: id ? this.queues.get(id)?.length : undefined, jobs: id ? this.jobs.get(id) : undefined };
+        if (!id || !this.entries.has(id) && !this.queues.has(id) && !this.jobs.has(id))
+            return EMPTY_VIEW;
+        let view = this.views.get(id);
+        if (!view) {
+            view = Object.freeze({ values: Object.freeze({ ...this.entries.get(id)?.values }),
+                queued: this.queues.get(id)?.length, jobs: this.jobs.get(id) });
+            this.views.set(id, view);
+        }
+        return view;
     }
     /** Read the selected session's authoritative pending inputs; absence means no observed queue.
      * @param id - Session identity.
      * @returns Pending inputs in host order.
      */
-    pending(id) { return id ? this.queues.get(id) ?? [] : []; }
+    pending(id) { return id ? this.queues.get(id) ?? EMPTY_QUEUE : EMPTY_QUEUE; }
     entry(id) {
         let entry = this.entries.get(id);
         if (!entry) {

package/dist/session/transcript.d.ts

@@ -1,6 +1,10 @@
 import type { HistoryLimits } from './memory.ts';
-import type { PromptRecord } from './info.ts';
 import { type Json, type ObjectValue } from '../transport/wire.ts';
+/** A durable user prompt projected from the transcript, before recall retention. */
+export interface PromptRecord {
+    seq: number;
+    text: string;
+}
 interface ToolSummary {
     name: string;
     operation?: string;

package/dist/slash/index.d.ts

@@ -5,6 +5,6 @@
 export { COMMAND_HINTS, COMMAND_LABELS, COMMAND_LABEL_WIDTH, COMMANDS, COMMAND_POLICY, argumentHint, commandMatches, commonPrefix, completeCommand, resolveCommand, suggestedCommands } from './registry.ts';
 export type { CommandHint, CommandPolicy } from './registry.ts';
 export { parseCommand, loopNameQuery, validLoopOption, LOOP_ABORT_USAGE, LOOP_ANSWER_USAGE, LOOP_STOP_USAGE, LOOP_USAGE } from './parse.ts';
-export type { Command, LoopOptions } from './parse.ts';
+export type { Command, LoopOptions } from './types.ts';
 export { interpret, normalize, authorize } from './pipeline.ts';
 export type { AuthorizeFacts, DeferReason, ExecutableSubmission, InterpretFacts, LineCommand, NormalizeFacts, Submission, UiAction, Verdict } from './pipeline.ts';

package/dist/slash/parse.d.ts

@@ -1,128 +1,5 @@
-/** One parsed command; every side effect stays with the caller. */
-export type Command = {
-    kind: 'ignore';
-} | {
-    kind: 'copy';
-} | {
-    kind: 'quit';
-} | {
-    kind: 'panel';
-    panel: 'cost' | 'status' | 'help';
-} | {
-    kind: 'remove';
-    target: 'workspace' | 'session';
-    query: string;
-} | {
-    kind: 'navigate';
-    target: 'workspace' | 'session';
-    query?: string;
-} | {
-    kind: 'latest';
-} | {
-    kind: 'models';
-    args: string[];
-} | {
-    kind: 'queue';
-} | {
-    kind: 'newSession';
-}
-/** Open the saved-prompt picker, or save the following text as a shortcut prompt. */
- | {
-    kind: 'prompts';
-} | {
-    kind: 'savePrompt';
-    text: string;
-} | {
-    kind: 'history';
-    query: string;
-} | {
-    kind: 'sessionSearch';
-    command: '/ssearch' | '/wsearch';
-    query: string;
-} | {
-    kind: 'historySearch';
-    query: string;
-} | {
-    kind: 'think';
-    target: string;
-} | {
-    kind: 'older';
-} | {
-    kind: 'compact';
-}
-/** Clear the client's own HANDOFF.md, then ask the agent to write a fresh session handoff. */
- | {
-    kind: 'handoff';
-}
-/** Start the client-driven scored loop for one `loop.yaml` record. */
- | {
-    kind: 'loop';
-    name: string;
-    options: LoopOptions;
-}
-/** Offer the `loop.yaml` records so one can be chosen instead of typed. */
- | {
-    kind: 'loops';
-}
-/** Stop the running loop, running or paused. */
- | {
-    kind: 'loopStop';
-}
-/** Answer a paused run, so the current artifact is judged again with the operator's addition. */
- | {
-    kind: 'loopAnswer';
-    text: string;
-} | {
-    kind: 'cancel';
-} | {
-    kind: 'approval';
-    allowed: boolean;
-} | {
-    kind: 'hostCommand';
-    line: string;
-}
-/** A local `!` command, run on this machine rather than the host. */
- | {
-    kind: 'shell';
-    command: string;
-} | {
-    kind: 'export';
-    destination?: string;
-} | {
-    kind: 'exportHtml';
-    destination?: string;
-} | {
-    kind: 'coredump';
-    tag?: string;
-} | {
-    kind: 'error';
-    message: string;
-} | {
-    kind: 'prompt';
-    text: string;
-};
-/** Options carried by `/loop`.
- *
- * Only the fields the operator actually typed are present, so the syntax layer validates each value
- * it sees and the application owns the defaults — command line first, then the record's `defaults`,
- * then the global ones.
- */
-export interface LoopOptions {
-    /** First step to run; default 1. */
-    from?: number;
-    /** Last step to run; default the record's last step. */
-    to?: number;
-    /** Passing score per step, 0-10 and possibly fractional; default the record's, else 8. */
-    score?: number;
-    /** Attempts allowed per step; default the record's, else 10. */
-    tries?: number;
-    /** Values that replace the record's own `vars` for this run, such as the document under review.
-     *
-     * The interactive form fills this in; the command line has no syntax for it, because the record —
-     * not the syntax layer — is what knows which names exist.
-     */
-    vars?: Readonly<Record<string, string>>;
-}
+import type { Command } from './types.ts';
+export type { Command, LoopOptions } from './types.ts';
 /** The numeric options a flag can carry; `vars` is not one, so it stays out of the flag table. */
 type LoopNumberOption = 'from' | 'to' | 'score' | 'tries';
 /** Whether one numeric value is acceptable for one loop option.
@@ -163,4 +40,3 @@ export declare const LOOP_ABORT_USAGE = "Use /loop abort (no arguments)";
  * @returns The parsed command.
  */
 export declare function parseCommand(line: string): Command;
-export {};

package/dist/slash/registry.d.ts

@@ -1,5 +1,5 @@
 /** Slash-command catalog shared by completion, `/help` and the submission router. */
-import type { Command } from './parse.ts';
+import type { Command } from './types.ts';
 /** One slash command advertised by completion and `/help`. */
 export interface CommandHint {
     /** Slash command as typed without arguments. */

package/dist/slash/types.d.ts

@@ -0,0 +1,126 @@
+/** Command values shared by syntax, discovery and admission; no parser dependency. */
+/** One parsed command; every side effect stays with the caller. */
+export type Command = {
+    kind: 'ignore';
+} | {
+    kind: 'copy';
+} | {
+    kind: 'quit';
+} | {
+    kind: 'panel';
+    panel: 'cost' | 'status' | 'help';
+} | {
+    kind: 'remove';
+    target: 'workspace' | 'session';
+    query: string;
+} | {
+    kind: 'navigate';
+    target: 'workspace' | 'session';
+    query?: string;
+} | {
+    kind: 'latest';
+} | {
+    kind: 'models';
+    args: string[];
+} | {
+    kind: 'queue';
+} | {
+    kind: 'newSession';
+}
+/** Open the saved-prompt picker, or save the following text as a shortcut prompt. */
+ | {
+    kind: 'prompts';
+} | {
+    kind: 'savePrompt';
+    text: string;
+} | {
+    kind: 'history';
+    query: string;
+} | {
+    kind: 'sessionSearch';
+    command: '/ssearch' | '/wsearch';
+    query: string;
+} | {
+    kind: 'historySearch';
+    query: string;
+} | {
+    kind: 'think';
+    target: string;
+} | {
+    kind: 'older';
+} | {
+    kind: 'compact';
+}
+/** Clear the client's own HANDOFF.md, then ask the agent to write a fresh session handoff. */
+ | {
+    kind: 'handoff';
+}
+/** Start the client-driven scored loop for one `loop.yaml` record. */
+ | {
+    kind: 'loop';
+    name: string;
+    options: LoopOptions;
+}
+/** Offer the `loop.yaml` records so one can be chosen instead of typed. */
+ | {
+    kind: 'loops';
+}
+/** Stop the running loop, running or paused. */
+ | {
+    kind: 'loopStop';
+}
+/** Answer a paused run, so the current artifact is judged again with the operator's addition. */
+ | {
+    kind: 'loopAnswer';
+    text: string;
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'approval';
+    allowed: boolean;
+} | {
+    kind: 'hostCommand';
+    line: string;
+}
+/** A local `!` command, run on this machine rather than the host. */
+ | {
+    kind: 'shell';
+    command: string;
+} | {
+    kind: 'export';
+    destination?: string;
+} | {
+    kind: 'exportHtml';
+    destination?: string;
+} | {
+    kind: 'coredump';
+    tag?: string;
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'prompt';
+    text: string;
+};
+/** Options carried by `/loop`.
+ *
+ * Only the fields the operator actually typed are present, so the syntax layer validates each value
+ * it sees and the application owns the defaults — command line first, then the record's `defaults`,
+ * then the global ones.
+ */
+export interface LoopOptions {
+    /** First step to run; default 1. */
+    from?: number;
+    /** Last step to run; default the record's last step. */
+    to?: number;
+    /** Passing score per step, 0-10 and possibly fractional; default the record's, else 8. */
+    score?: number;
+    /** Attempts allowed per step; default the record's, else 10. */
+    tries?: number;
+    /** Values that replace the record's own `vars` for this run, such as the document under review.
+     *
+     * The interactive form fills this in; the command line has no syntax for it, because the record —
+     * not the syntax layer — is what knows which names exist.
+     */
+    vars?: Readonly<Record<string, string>>;
+}

package/dist/slash/types.js

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

package/dist/state.d.ts

@@ -1,10 +1,9 @@
-/** Application state shared by the controller facade and every domain controller. */
-import { SessionInfo } from './session/info.ts';
-import type { HistorySearch, PendingInteraction, RemovalTarget } from './session/types.ts';
+import type { HistorySearch, RemovalTarget } from './session/types.ts';
+import type { SessionState } from './session/state.ts';
 import type { ShellSnapshot } from './shell/index.ts';
 import type { ObjectValue } from './transport/wire.ts';
 /** State shared by the picker and conversation view. */
-export interface State {
+export interface State extends SessionState {
     version: number;
     /** The last failure the application recorded, for a diagnostic line and a refusal's reason.
      *
@@ -13,15 +12,6 @@ export interface State {
      * Whether an operation is running is not stored here — that is `queries.foreground`.
      */
     lastFailure: string;
-    online: boolean;
-    screen: 'workspaces' | 'sessions' | 'chat' | 'path';
-    status: string;
-    workspaces: ObjectValue[];
-    sessions: ObjectValue[];
-    showAllSessions: boolean;
-    workspaceId?: string;
-    sessionId?: string;
-    pending: PendingInteraction[];
     controlError?: string;
     modelError?: string;
     presetError?: string;
@@ -29,12 +19,10 @@ export interface State {
     defaultModel?: ObjectValue;
     /** Local `!` runs, published so the UI never reads the shell service object. */
     shell: ShellSnapshot;
-    /** Record, prompt index, composer, view and interaction state of the selected session. */
-    session: SessionInfo;
 }
-/** The state contract every domain controller writes through. */
+/** Application state access used by connection orchestration. Feature domains use their own ports. */
 export interface ControllerStore {
-    /** Current immutable state snapshot. */
+    /** Current application snapshot; nested session data remains owned by the session domain. */
     readonly state: State;
     /** Publish a state patch and notify observers. */
     update(patch: Partial<State>): void;

package/dist/state.js

@@ -1,4 +1,4 @@
-/** Application state shared by the controller facade and every domain controller. */
+/** Application composition of session state and the other domains' published snapshots. */
 import { SessionInfo } from "./session/info.js";
 /** Build the initial state before any connection exists.
  * @returns A fresh state whose transcript is empty and disconnected.

package/dist/transport/client.d.ts

@@ -18,7 +18,7 @@ interface Listener {
     item(value: Json | undefined): void;
     end(error?: Error): void;
 }
-/** A single authenticated host connection; close before reconnecting or exiting. */
+/** One client lifetime. Peer disconnects allow reconnect; close permanently ends the lifetime. */
 export declare class Client {
     readonly timeoutMs: number;
     readonly base: URL;
@@ -27,6 +27,7 @@ export declare class Client {
     private socket;
     private listeners;
     private lifetime;
+    private closeTask?;
     constructor(base: string, timeoutMs?: number);
     /** Exchange a startup token only at GET / and retain the server's cookie expiration. */
     authenticate(token: string): Promise<void>;
@@ -58,9 +59,9 @@ export declare class Client {
     /** Archived session IDs from the latest authoritative workspace baseline. */
     archivedSessionIds: ReadonlySet<string>;
     /** List workspaces by consuming and cancelling the authoritative opening baseline. */
-    listWorkspaces(): Promise<ObjectValue[]>;
+    listWorkspaces(signal?: AbortSignal): Promise<ObjectValue[]>;
     /** List visible sessions, optionally filtering by the workspace's accounted IDs. */
-    listSessions(workspaceId?: string): Promise<ObjectValue[]>;
+    listSessions(workspaceId?: string, signal?: AbortSignal): Promise<ObjectValue[]>;
     /** Close all streams, abort in-flight HTTP, and await the physical socket's closure. */
     close(): Promise<void>;
     private signal;