@itookit/dsht 0.3.8 → 0.5.2

package/dist/transport/client.js

@@ -22,7 +22,7 @@ export class RemoteError extends Error {
         this.details = error.details;
     }
 }
-/** A single authenticated host connection; close before reconnecting or exiting. */
+/** One client lifetime. Peer disconnects allow reconnect; close permanently ends the lifetime. */
 export class Client {
     timeoutMs;
     base;
@@ -31,6 +31,7 @@ export class Client {
     socket;
     listeners = new Map();
     lifetime = new AbortController();
+    closeTask;
     constructor(base, timeoutMs = 15_000) {
         this.timeoutMs = timeoutMs;
         this.base = new URL(base);
@@ -117,13 +118,17 @@ export class Client {
     }
     /** Connect the physical mux. A disconnected instance may reconnect with its cookie. */
     async connect() {
+        this.lifetime.signal.throwIfAborted();
         if (this.socket)
             throw new Error('Mux is already connected');
         const url = new URL('/api/remote.mux', this.base);
         url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
         const socket = new WebSocket(url, { headers: { cookie: this.cookie }, handshakeTimeout: this.timeoutMs });
         this.socket = socket;
+        const closed = new Promise(resolve => socket.once('close', () => resolve()));
         socket.on('message', (raw, binary) => {
+            if (this.socket !== socket || this.lifetime.signal.aborted)
+                return;
             try {
                 if (binary)
                     throw new Error('Unexpected binary mux frame');
@@ -154,22 +159,40 @@ export class Client {
                 socket.terminate();
             }
         });
-        socket.on('error', error => this.fail(error));
+        socket.on('error', error => { if (this.socket === socket)
+            this.fail(error); });
         socket.on('close', () => {
-            if (this.socket === socket)
-                this.socket = undefined;
+            if (this.socket !== socket)
+                return;
+            this.socket = undefined;
             this.fail(new Error('Connection closed'));
         });
-        await once(socket, 'open');
+        try {
+            await once(socket, 'open', { signal: this.lifetime.signal });
+            this.lifetime.signal.throwIfAborted();
+        }
+        catch (error) {
+            if (socket.readyState !== WebSocket.CLOSED)
+                socket.terminate();
+            await closed;
+            throw error;
+        }
     }
     /** Subscribe on the existing mux; each subscription has a fresh stream identity. */
     subscribe(endpoint, args, listener) {
+        this.lifetime.signal.throwIfAborted();
         const socket = this.socket;
         if (socket?.readyState !== WebSocket.OPEN)
             throw new Error('Mux is not connected');
         const streamId = randomUUID();
         this.listeners.set(streamId, listener);
-        socket.send(JSON.stringify({ type: 'open', streamId, endpoint, payload: { args } }));
+        try {
+            socket.send(JSON.stringify({ type: 'open', streamId, endpoint, payload: { args } }));
+        }
+        catch (error) {
+            this.listeners.delete(streamId);
+            throw error;
+        }
         return { cancel: () => {
                 if (!this.listeners.delete(streamId))
                     return;
@@ -180,57 +203,80 @@ export class Client {
     /** Archived session IDs from the latest authoritative workspace baseline. */
     archivedSessionIds = new Set();
     /** List workspaces by consuming and cancelling the authoritative opening baseline. */
-    async listWorkspaces() {
+    async listWorkspaces(signal) {
+        signal?.throwIfAborted();
         return new Promise((resolve, reject) => {
             let sub;
-            const timer = setTimeout(() => { sub.cancel(); reject(new Error('Workspace baseline timed out')); }, this.timeoutMs);
+            let settled = false;
+            const finish = (error, items) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', cancel);
+                sub?.cancel();
+                if (error !== undefined)
+                    reject(error);
+                else
+                    resolve(items);
+            };
+            const cancel = () => finish(signal.reason);
+            const timer = setTimeout(() => finish(new Error('Workspace baseline timed out')), this.timeoutMs);
+            signal?.addEventListener('abort', cancel, { once: true });
             try {
                 sub = this.subscribe('workspace/follow', {}, {
                     item: value => {
-                        clearTimeout(timer);
-                        sub.cancel();
+                        if (settled)
+                            return;
                         try {
                             const frame = object(value);
                             if (frame.type !== 'baseline')
                                 throw new Error('Workspace stream omitted its baseline');
                             this.archivedSessionIds = new Set(array(object(frame.value).archivedSessionIds).map(string));
-                            resolve(array(object(frame.value).items).map(object));
+                            finish(undefined, array(object(frame.value).items).map(object));
                         }
                         catch (error) {
-                            reject(error);
+                            finish(error);
                         }
                     },
-                    end: error => { clearTimeout(timer); reject(error ?? new Error('Workspace stream ended before baseline')); },
+                    end: error => finish(error ?? new Error('Workspace stream ended before baseline')),
                 });
+                if (settled)
+                    sub.cancel();
             }
             catch (error) {
-                clearTimeout(timer);
-                reject(error);
+                finish(error);
             }
         });
     }
     /** List visible sessions, optionally filtering by the workspace's accounted IDs. */
-    async listSessions(workspaceId) {
-        const sessions = array(object(await this.call('session/list', { _request: {} })).items).map(object);
+    async listSessions(workspaceId, signal) {
+        const sessions = array(object(await this.call('session/list', { _request: {} }, signal)).items).map(object);
         if (!workspaceId)
             return sessions;
-        const workspace = (await this.listWorkspaces()).find(item => item.workspaceId === workspaceId);
+        const workspace = (await this.listWorkspaces(signal)).find(item => item.workspaceId === workspaceId);
         if (!workspace)
             throw new Error(`Workspace not found: ${workspaceId}`);
         const ids = new Set(array(workspace.sessionIds).map(string));
         return sessions.filter(item => ids.has(string(item.sessionId)));
     }
     /** Close all streams, abort in-flight HTTP, and await the physical socket's closure. */
-    async close() {
-        this.lifetime.abort();
+    close() {
+        if (this.closeTask)
+            return this.closeTask;
         const socket = this.socket;
         this.socket = undefined;
+        // Reserve before publishing cancellation: termination callbacks may themselves call close.
+        this.closeTask = Promise.resolve().then(async () => {
+            if (socket && socket.readyState !== WebSocket.CLOSED) {
+                const closed = new Promise(resolve => socket.once('close', () => resolve()));
+                socket.terminate();
+                await closed;
+            }
+        });
+        this.lifetime.abort();
         this.fail(new Error('Client closed'));
-        if (socket && socket.readyState !== WebSocket.CLOSED) {
-            const closed = new Promise(resolve => socket.once('close', () => resolve()));
-            socket.terminate();
-            await closed;
-        }
+        return this.closeTask;
     }
     signal(timeoutMs = this.timeoutMs) {
         return timeoutMs === null ? this.lifetime.signal : AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(timeoutMs)]);

package/dist/transport/events.d.ts

@@ -0,0 +1,104 @@
+/** One place that reads DSH event field names and turns them into semantic host events.
+ *
+ * Raw wire stops here: no `Json`/`ObjectValue` payload survives into a `HostEvent`, so `connection/`,
+ * `session/` and the UI never learn how the host names its fields. Replying `{kind:'next'}` to an
+ * unrecognized waterfall is a wire-level obligation of the host's event chain, so it is modelled as
+ * `waterfall-delegate` rather than silently dropped.
+ */
+import { type Json, type ObjectValue } from './wire.ts';
+/** One selectable answer of a host question, already flattened out of the raw request. */
+export interface QuestionOption {
+    label: string;
+    description?: string;
+}
+/** One question of an `user-questions/request` waterfall. */
+export interface QuestionItem {
+    id: string;
+    header?: string;
+    question: string;
+    detail?: string;
+    multiSelect: boolean;
+    options: readonly QuestionOption[];
+}
+/** A decoded host event with protocol field names already resolved into domain meaning. */
+export type HostEvent = {
+    kind: 'approval-request';
+    eventId: string;
+    sessionId: string;
+    description: string;
+} | {
+    kind: 'question-request';
+    eventId: string;
+    sessionId: string;
+    questions: readonly QuestionItem[];
+}
+/** A waterfall this client does not answer; the caller must reply `next` to keep the host chain moving. */
+ | {
+    kind: 'waterfall-delegate';
+    eventId: string;
+} | {
+    kind: 'cancel';
+    eventId: string;
+} | {
+    kind: 'agent-status';
+    sessionId: string;
+    running: boolean;
+} | {
+    kind: 'catalog-invalidated';
+} | {
+    kind: 'session-error';
+    sessionId: string;
+    error: string;
+} | {
+    kind: 'control';
+    frame: ControlFrame;
+};
+/** One host-owned pending input, flattened to the text the UI shows. */
+export interface QueuedInput {
+    id: string;
+    placement: 'queued' | 'steering' | 'context';
+    text: string;
+}
+/** A capability value the host owns. Individual keys are typed incrementally as they are consumed. */
+export type ProjectionValue = Json;
+/** One session's projection values and the sequence they describe. */
+export interface ProjectionSnapshot {
+    asOfSeq: number;
+    values: Readonly<Record<string, ProjectionValue>>;
+}
+/** One decoded `session/control` frame with protocol field names already resolved. */
+export type ControlFrame = {
+    kind: 'baseline';
+    projections: ReadonlyMap<string, ProjectionSnapshot>;
+    queues: ReadonlyMap<string, readonly QueuedInput[]>;
+    jobs: ReadonlyMap<string, number>;
+} | {
+    kind: 'projection';
+    sessionId: string;
+    key: string;
+    seq: number;
+    value: ProjectionValue;
+} | {
+    kind: 'queue';
+    sessionId: string;
+    items: readonly QueuedInput[];
+} | {
+    kind: 'jobs';
+    sessionId: string;
+    count: number;
+};
+/** Decode one projection baseline, as carried by a `session/control` baseline or a follow snapshot. */
+export declare function projectionSnapshot(value: unknown): ProjectionSnapshot | undefined;
+/** Turn one decoded `session/control` frame into a semantic control frame.
+ * @param value - One decoded `session/control` frame.
+ * @returns The normalized frame.
+ */
+export declare function controlFrame(value: unknown): ControlFrame;
+/** Turn one decoded `$events` frame into a semantic host event.
+ *
+ * Returns `undefined` for anything this client does not act on, including the `ready` handshake,
+ * which belongs to the connection lifecycle rather than to a domain.
+ * @param frame - One decoded `$events` frame.
+ * @returns The normalized event, or undefined when it is not one this client consumes.
+ */
+export declare function hostEvent(frame: ObjectValue): HostEvent | undefined;

package/dist/transport/events.js

@@ -0,0 +1,149 @@
+/** One place that reads DSH event field names and turns them into semantic host events.
+ *
+ * Raw wire stops here: no `Json`/`ObjectValue` payload survives into a `HostEvent`, so `connection/`,
+ * `session/` and the UI never learn how the host names its fields. Replying `{kind:'next'}` to an
+ * unrecognized waterfall is a wire-level obligation of the host's event chain, so it is modelled as
+ * `waterfall-delegate` rather than silently dropped.
+ */
+import { array, errorText, object, string } from "./wire.js";
+/** Host notifications that invalidate the model catalog. */
+const CATALOG_EVENTS = new Set(['llm/adapters-updated', 'settings/document-updated', 'credentials/reference-updated']);
+/** Require a projection watermark rather than accepting a rolled-back value. */
+function sequence(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < -1)
+        throw new Error('Invalid projection watermark');
+    return value;
+}
+/** Flatten one session's pending-input list. */
+function queuedInputs(value) {
+    return array(value).map(raw => {
+        const item = object(raw);
+        if (!['queued', 'steering', 'context'].includes(string(item.placement)))
+            throw new Error('Invalid queue placement');
+        return { id: string(item.id), placement: item.placement,
+            text: array(object(item.message).content).map(object)
+                .map(block => block.type === 'text' ? string(block.text) : `[${string(block.type)}]`).join(' ') };
+    });
+}
+/** Count the jobs the host still considers active. */
+function activeJobs(value) {
+    return array(value).filter(item => ['running', 'stopping'].includes(string(object(item).status))).length;
+}
+/** Decode one projection baseline, as carried by a `session/control` baseline or a follow snapshot. */
+export function projectionSnapshot(value) {
+    if (value === undefined)
+        return undefined;
+    const baseline = object(value);
+    return { asOfSeq: sequence(baseline.asOfSeq), values: object(baseline.values) };
+}
+/** Turn one decoded `session/control` frame into a semantic control frame.
+ * @param value - One decoded `session/control` frame.
+ * @returns The normalized frame.
+ */
+export function controlFrame(value) {
+    const frame = object(value);
+    if (frame.type === 'baseline') {
+        const baseline = object(frame.value);
+        const projections = Object.entries(object(baseline.projections))
+            .map(([id, snapshot]) => [id, projectionSnapshot(snapshot)]);
+        const queues = Object.entries(object(baseline.queues)).map(([id, items]) => [id, queuedInputs(items)]);
+        const jobs = Object.entries(object(baseline.jobs)).map(([id, items]) => [id, activeJobs(items)]);
+        return { kind: 'baseline', projections: new Map(projections), queues: new Map(queues), jobs: new Map(jobs) };
+    }
+    if (frame.type === 'projection' || frame.type === 'queue' || frame.type === 'jobs') {
+        const sessionId = string(frame.sessionId);
+        if (frame.type === 'projection') {
+            if (frame.value === undefined)
+                throw new Error('Missing projection value');
+            return { kind: 'projection', sessionId, key: string(frame.key), seq: sequence(frame.seq), value: frame.value };
+        }
+        if (frame.type === 'queue')
+            return { kind: 'queue', sessionId, items: queuedInputs(frame.items) };
+        // The host names the job rows `jobs`; the loopback fixtures used `items`, so accept either.
+        return { kind: 'jobs', sessionId, count: activeJobs(frame.jobs ?? frame.items) };
+    }
+    throw new Error('Unknown session control frame');
+}
+/** Read a possibly-absent string field without turning protocol drift into a throw. */
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** Flatten one raw question into the semantic shape the session domain retains. */
+function questionItem(value) {
+    const item = object(value);
+    const options = array(item.options ?? []).map(raw => {
+        const option = object(raw);
+        const description = optionalString(option.description);
+        return { label: string(option.label), ...(description === undefined ? {} : { description }) };
+    });
+    const header = optionalString(item.header);
+    const detail = optionalString(item.detail);
+    return {
+        id: string(item.id),
+        ...(header === undefined ? {} : { header }),
+        question: string(item.question),
+        ...(detail === undefined ? {} : { detail }),
+        multiSelect: item.multiSelect === true,
+        options,
+    };
+}
+/** Decode one `$events` waterfall frame. */
+function waterfallEvent(frame) {
+    const eventId = string(frame.eventId);
+    const sessionId = optionalString(frame.agentId) ?? '';
+    if (frame.event === 'approval/request') {
+        // The approval body is host-defined and currently rendered verbatim; formatting it here keeps
+        // the terminal output byte-identical while removing the raw object from the boundary.
+        return { kind: 'approval-request', eventId, sessionId, description: JSON.stringify(frame.request ?? null, null, 2) };
+    }
+    if (frame.event === 'user-questions/request') {
+        try {
+            const request = object(frame.request);
+            return { kind: 'question-request', eventId, sessionId, questions: array(request.questions ?? []).map(questionItem) };
+        }
+        catch {
+            // A malformed question still has to be settled, or the host's event chain blocks on it.
+            return { kind: 'waterfall-delegate', eventId };
+        }
+    }
+    return { kind: 'waterfall-delegate', eventId };
+}
+/** Decode one `$events` emit frame this client reacts to. */
+function emitEvent(frame) {
+    const name = frame.event;
+    if (name === 'api-session/status') {
+        const args = array(frame.args);
+        if (typeof args[1] !== 'boolean')
+            throw new Error('Invalid session running state');
+        return { kind: 'agent-status', sessionId: string(args[0]), running: args[1] };
+    }
+    if (name === 'api-session/error') {
+        const args = array(frame.args);
+        return { kind: 'session-error', sessionId: optionalString(args[0]) ?? '', error: errorText(args[1]) };
+    }
+    if (typeof name === 'string' && CATALOG_EVENTS.has(name))
+        return { kind: 'catalog-invalidated' };
+    return undefined;
+}
+/** Turn one decoded `$events` frame into a semantic host event.
+ *
+ * Returns `undefined` for anything this client does not act on, including the `ready` handshake,
+ * which belongs to the connection lifecycle rather than to a domain.
+ * @param frame - One decoded `$events` frame.
+ * @returns The normalized event, or undefined when it is not one this client consumes.
+ */
+export function hostEvent(frame) {
+    try {
+        if (frame.type === 'waterfall')
+            return waterfallEvent(frame);
+        if (frame.type === 'cancel')
+            return { kind: 'cancel', eventId: string(frame.eventId) };
+        if (frame.type === 'emit')
+            return emitEvent(frame);
+    }
+    catch {
+        // A frame this client cannot decode is not allowed to fail the whole subscription.
+        return undefined;
+    }
+    return undefined;
+}

package/dist/transport/wire.d.ts

@@ -1,17 +1,9 @@
-/** JSON validation and terminal-safe presentation at the remote boundary. */
-export type Json = null | boolean | number | string | Json[] | {
-    [key: string]: Json;
-};
-export type ObjectValue = {
-    [key: string]: Json;
-};
-/** Require an object from a decoded wire message. */
-export declare function object(value: unknown): ObjectValue;
-/** Require a string field rather than silently accepting protocol drift. */
-export declare function string(value: unknown): string;
-/** Require an array field from the server. */
-export declare function array(value: unknown): Json[];
-/** Remove terminal controls from remote text while retaining line breaks and tabs. */
-export declare function safeText(value: string): string;
-/** Return a displayable error without serializing request headers or credentials. */
-export declare function errorText(error: unknown): string;
+/** The wire's decoding surface.
+ *
+ * The JSON shapes, their strict readers and the displayable error text are dependency-free leaves
+ * (`src/json.ts`, `src/text.ts`), so the UI can name the same types without importing the transport
+ * domain. This module re-exports them as the wire-facing API the features already use.
+ */
+export type { Json, ObjectValue } from '../json.ts';
+export { array, object, string } from '../json.ts';
+export { errorText, safeText } from '../text.ts';

package/dist/transport/wire.js

@@ -1,27 +1,2 @@
-/** Require an object from a decoded wire message. */
-export function object(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error('Expected a JSON object from the server');
-    }
-    return value;
-}
-/** Require a string field rather than silently accepting protocol drift. */
-export function string(value) {
-    if (typeof value !== 'string')
-        throw new Error('Expected a string from the server');
-    return value;
-}
-/** Require an array field from the server. */
-export function array(value) {
-    if (!Array.isArray(value))
-        throw new Error('Expected an array from the server');
-    return value;
-}
-/** Remove terminal controls from remote text while retaining line breaks and tabs. */
-export function safeText(value) {
-    return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, '');
-}
-/** Return a displayable error without serializing request headers or credentials. */
-export function errorText(error) {
-    return safeText(error instanceof Error ? error.message : String(error));
-}
+export { array, object, string } from "../json.js";
+export { errorText, safeText } from "../text.js";