@itookit/dsht 0.1.0

package/dist/client.js

@@ -0,0 +1,230 @@
+/** Cookie-authenticated HTTP RPC and one multiplexed WebSocket; imports no Harness code. */
+import { randomUUID } from 'node:crypto';
+import { once } from 'node:events';
+import WebSocket from 'ws';
+import { array, object, string } from "./wire.js";
+/** HTTP failure remains distinct from host business errors. */
+export class HttpError extends Error {
+    status;
+    constructor(status, endpoint) {
+        super(`${endpoint}: HTTP ${status}`);
+        this.status = status;
+    }
+}
+/** Host business failure, including the original machine-readable details. */
+export class RemoteError extends Error {
+    code;
+    details;
+    constructor(value) {
+        const error = object(value);
+        super(`${string(error.code)}: ${string(error.message)}`);
+        this.code = string(error.code);
+        this.details = error.details;
+    }
+}
+/** A single authenticated host connection; close before reconnecting or exiting. */
+export class Client {
+    timeoutMs;
+    base;
+    cookie = '';
+    expiresAt;
+    socket;
+    listeners = new Map();
+    lifetime = new AbortController();
+    constructor(base, timeoutMs = 15_000) {
+        this.timeoutMs = timeoutMs;
+        this.base = new URL(base);
+        if (!['http:', 'https:'].includes(this.base.protocol) || this.base.username || this.base.password
+            || this.base.pathname !== '/' || this.base.search || this.base.hash) {
+            throw new Error('Server URL must be an HTTP(S) origin without a path, query, or credentials');
+        }
+    }
+    /** Exchange a startup token only at GET / and retain the server's cookie expiration. */
+    async authenticate(token) {
+        const url = new URL('/', this.base);
+        url.searchParams.set('token', token);
+        const response = await fetch(url, { redirect: 'manual', signal: this.signal() });
+        if (response.status !== 303) {
+            await response.body?.cancel();
+            throw new HttpError(response.status, 'Authentication failed');
+        }
+        const header = response.headers.getSetCookie().find(value => value.startsWith('dsh-auth-'));
+        await response.body?.cancel();
+        if (!header)
+            throw new Error('Authentication response omitted the dsh-auth cookie');
+        this.restoreCookie(header.split(';')[0]);
+        const maxAge = /;\s*max-age=(-?\d+)(?:;|$)/i.exec(header)?.[1];
+        const expires = /;\s*expires=([^;]+)/i.exec(header)?.[1];
+        const expiration = maxAge === undefined ? Date.parse(expires ?? '') : Date.now() + Number(maxAge) * 1000;
+        this.expiresAt = Number.isSafeInteger(expiration) ? expiration : undefined;
+    }
+    /** Restore one origin-scoped cookie read by the caller's credential store. */
+    restoreCookie(cookie) {
+        if (!/^dsh-auth-[\w-]+=[A-Za-z0-9._-]+$/.test(cookie))
+            throw new Error('Invalid saved authentication cookie');
+        this.cookie = cookie;
+        this.expiresAt = undefined;
+    }
+    /** Session-only cookies are not eligible for persistent storage. */
+    get persistentCookie() {
+        return this.expiresAt === undefined ? undefined : { cookie: this.cookie, expiresAt: this.expiresAt };
+    }
+    /** Invoke an exact endpoint once. Mutations are never automatically retried.
+     * @param endpoint - Namespace/method endpoint.
+     * @param args - Host parameter names and JSON values.
+     * @param signal - Optional caller cancellation, combined with client close and timeout.
+     * @returns The decoded result value; HTTP, remote, and cancellation errors reject.
+     */
+    async call(endpoint, args = {}, signal) {
+        if (!/^[\w$-]+\/[\w$-]+$/.test(endpoint))
+            throw new Error('Invalid RPC endpoint');
+        const rpcId = randomUUID();
+        const response = await fetch(new URL(`/api/${endpoint}`, this.base), {
+            method: 'POST', redirect: 'error', signal: signal ? AbortSignal.any([this.signal(), signal]) : this.signal(),
+            headers: { 'content-type': 'application/json', cookie: this.cookie },
+            body: JSON.stringify({ type: 'client-request', rpcId, method: endpoint, payload: { args } }),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new HttpError(response.status, endpoint);
+        }
+        const body = object(await response.json());
+        if (body.type !== 'server-response' || body.rpcId !== rpcId)
+            throw new Error('RPC response identity mismatch');
+        const result = object(body.result);
+        if (result.ok === false)
+            throw new RemoteError(result.error);
+        if (result.ok !== true)
+            throw new Error('Malformed RPC result');
+        return result.value;
+    }
+    /** Connect the physical mux. A disconnected instance may reconnect with its cookie. */
+    async connect() {
+        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;
+        socket.on('message', (raw, binary) => {
+            try {
+                if (binary)
+                    throw new Error('Unexpected binary mux frame');
+                const frame = object(JSON.parse(raw.toString()));
+                const id = string(frame.streamId);
+                if (!['item', 'end', 'error'].includes(string(frame.type)))
+                    throw new Error('Invalid mux frame type');
+                const listener = this.listeners.get(id);
+                if (!listener)
+                    return;
+                if (frame.type === 'item') {
+                    try {
+                        listener.item(frame.value);
+                    }
+                    catch (error) {
+                        this.listeners.delete(id);
+                        socket.send(JSON.stringify({ type: 'cancel', streamId: id }));
+                        this.finish(listener, error instanceof Error ? error : new Error('Stream callback failed'));
+                    }
+                }
+                else {
+                    this.listeners.delete(id);
+                    this.finish(listener, frame.type === 'error' ? new RemoteError(frame.error) : undefined);
+                }
+            }
+            catch (error) {
+                this.fail(error instanceof Error ? error : new Error('Invalid mux frame'));
+                socket.terminate();
+            }
+        });
+        socket.on('error', error => this.fail(error));
+        socket.on('close', () => {
+            if (this.socket === socket)
+                this.socket = undefined;
+            this.fail(new Error('Connection closed'));
+        });
+        await once(socket, 'open');
+    }
+    /** Subscribe on the existing mux; each subscription has a fresh stream identity. */
+    subscribe(endpoint, args, listener) {
+        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 } }));
+        return { cancel: () => {
+                if (!this.listeners.delete(streamId))
+                    return;
+                if (socket.readyState === WebSocket.OPEN)
+                    socket.send(JSON.stringify({ type: 'cancel', streamId }));
+            } };
+    }
+    /** List workspaces by consuming and cancelling the authoritative opening baseline. */
+    async listWorkspaces() {
+        return new Promise((resolve, reject) => {
+            let sub;
+            const timer = setTimeout(() => { sub.cancel(); reject(new Error('Workspace baseline timed out')); }, this.timeoutMs);
+            try {
+                sub = this.subscribe('workspace/follow', {}, {
+                    item: value => {
+                        clearTimeout(timer);
+                        sub.cancel();
+                        try {
+                            const frame = object(value);
+                            if (frame.type !== 'baseline')
+                                throw new Error('Workspace stream omitted its baseline');
+                            resolve(array(object(frame.value).items).map(object));
+                        }
+                        catch (error) {
+                            reject(error);
+                        }
+                    },
+                    end: error => { clearTimeout(timer); reject(error ?? new Error('Workspace stream ended before baseline')); },
+                });
+            }
+            catch (error) {
+                clearTimeout(timer);
+                reject(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);
+        if (!workspaceId)
+            return sessions;
+        const workspace = (await this.listWorkspaces()).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();
+        const socket = this.socket;
+        this.socket = undefined;
+        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;
+        }
+    }
+    signal() {
+        return AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.timeoutMs)]);
+    }
+    fail(error) {
+        const listeners = [...this.listeners.values()];
+        this.listeners.clear();
+        for (const listener of listeners)
+            this.finish(listener, error);
+    }
+    finish(listener, error) {
+        try {
+            listener.end(error);
+        }
+        catch { /* Termination callbacks cannot prevent other streams from closing. */ }
+    }
+}

package/dist/controller.d.ts

@@ -0,0 +1,140 @@
+import { Client } from './client.ts';
+import { CostLedger } from './cost.ts';
+import { Telemetry } from './telemetry.ts';
+import { Transcript } from './transcript.ts';
+import { type FileReference } from './references.ts';
+import { type Json, type ObjectValue } from './wire.ts';
+/** 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;
+    defaultModel?: ObjectValue;
+    transcript: Transcript;
+}
+/** 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;
+    state: State;
+    private observers;
+    private abort;
+    private client;
+    private clientId;
+    private follow;
+    private runTask;
+    private generationFailed;
+    private selection;
+    telemetry: Telemetry;
+    private observedRunningAt;
+    private catalogRevision;
+    private catalogTasks;
+    private runningUpdates;
+    private stoppingSession?;
+    private interruptTask;
+    private admission;
+    private costUpdates;
+    private costAbort?;
+    private costTask;
+    private costTimer;
+    /** 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;
+    /** Epoch start from the retained turn log, or when this client first observed the run. */
+    get workingSince(): number | undefined;
+    /** 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);
+    /** 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>;
+    /** 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>;
+    /** Refresh both lists from the host, then show the requested picker. */
+    showPicker(screen: 'workspaces' | 'sessions'): Promise<void>;
+    /** Pick a workspace, or use all sessions when the identity is omitted. */
+    pickWorkspace(workspaceId?: string): void;
+    /** Open a workspace picker, or resolve a workspace by ID, exact title/path, or unique ID prefix. */
+    switchWorkspace(query?: string): Promise<void>;
+    /** Guide workspace selection, list all sessions with `all`, or resolve an exact session target. */
+    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. */
+    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. */
+    selectSession(sessionId: string): Promise<void>;
+    /** Wait for the selected follow snapshot, failing on disconnect or cancellation.
+     * @param signal - Cancels waiting without closing the session.
+     */
+    waitForHistory(signal: AbortSignal): Promise<void>;
+    /** Search the host's bounded global results, optionally retaining workspace members.
+     * @param query - Literal message text.
+     * @param workspaceOnly - Restrict returned hits to the selected workspace's session IDs.
+     * @param signal - Cancels the HTTP search.
+     * @returns Session snippets and the global truncation flag, preserved after filtering.
+     */
+    searchSessions(query: string, workspaceOnly: boolean, signal: AbortSignal): Promise<{
+        items: ObjectValue[];
+        hasMore: boolean;
+    }>;
+    /** Search paths on the host; does not read or upload file contents.
+     * @param query - Path text after @, relative to the selected session cwd.
+     * @param signal - Cancels an obsolete composer lookup.
+     * @returns Validated candidates in host order.
+     */
+    references(query: string, signal: AbortSignal): Promise<FileReference[]>;
+    /** Admit a prompt once; a failed response can have an uncertain delivery outcome. */
+    prompt(text: string, mode?: 'queue' | 'steer'): 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. */
+    older(signal?: AbortSignal): Promise<void>;
+    /** Load the prefix required for an explicit history jump; never loop on an unadvancing page.
+     * @param target - Visible record sequence, or first for the oldest available history.
+     * @param signal - Cancels local paging without interrupting the remote agent.
+     */
+    historyThrough(target: number | 'first', signal: AbortSignal): Promise<void>;
+    /** Answer the oldest selected-session interaction, after explicit user action. */
+    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();
+    private get sessionId();
+    private update;
+    private reply;
+    private releasePending;
+    private refreshCatalog;
+    private run;
+}