lark-remote 0.1.7 → 0.1.9

package/dist/runner/dsh/client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * DshClient — HTTP client for the DSH Web Host proxy.
+ *
+ * Two transports:
+ *  1. unary POST /api/<method> (client-request → server-response).
+ *  2. SSE GET /api/events.mux (all-session aggregated stream). Frames are
+ *     ServerRequest envelopes; `method` equals the MuxFrame's `type`.
+ *
+ * The client is stateless apart from the base URL: each `run()` opens its own
+ * mux subscription and closes it on terminal. `sessionEvents()` wraps the raw
+ * mux with per-session filtering plus reconnect + history-replay dedup
+ * (DSH v1 has no `since` resume — reconnection = reopen stream + refetch
+ * history, dedup by event seq).
+ */
+import type { DshModelCatalogValue, DshModelSelection, DshPresetListValue, DshServerRequest, DshSessionModelsValue, DshStreamItem, DshTokenUsage } from './types.js';
+interface WebSocketMessageEvent {
+    data: unknown;
+}
+interface WebSocketLike {
+    onmessage: ((event: WebSocketMessageEvent) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    close(): void;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export declare class DshError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare class DshClient {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly webSocketImpl;
+    constructor(baseUrl: string, fetchImpl?: typeof fetch, webSocketImpl?: WebSocketFactory);
+    /** Perform a unary POST and return the ok value; throws DshError on failure. */
+    unary(method: string, payload: unknown): Promise<unknown>;
+    /** Create a session. Pass `agentPreset` to pin the session's preset (fixed at
+     *  creation). */
+    createSession(payload: {
+        cwd: string;
+        agentPreset?: string;
+    }): Promise<{
+        sessionId: string;
+        agentPreset?: string;
+    }>;
+    /** Align the session's model/reasoningEffort (also persists as global default
+     *  server-side). Failures are surfaced as DshError for the caller to downgrade. */
+    selectModel(payload: DshModelSelection & {
+        sessionId: string;
+    }): Promise<DshModelSelection>;
+    /** Read the session's current model selection + full model catalog. */
+    sessionModels(sessionId: string): Promise<DshSessionModelsValue>;
+    /** Read the model catalog (session-independent, llm.models). */
+    listModels(): Promise<DshModelCatalogValue>;
+    /** Read the preset catalog (agentPreset.list). */
+    listPresets(): Promise<DshPresetListValue>;
+    /**
+     * Return the highest event `seq` currently persisted in session.history.
+     *
+     * The caller snapshots this before `session.prompt`. `session.history` is a
+     * full-session replay rather than a delta, so this high-water mark is what
+     * lets a subsequent replay skip every already-completed turn.
+     */
+    latestEventSeq(sessionId: string): Promise<number>;
+    /**
+     * Raw SSE mux stream: yields ServerRequest envelopes until the stream ends,
+     * errors, or `signal` aborts. Does NOT reconnect (the caller owns retry).
+     */
+    mux(signal: AbortSignal): AsyncGenerator<DshServerRequest>;
+    /**
+     * WebSocket mux stream. The real DSH `/api/events.mux` endpoint is a
+     * WebSocket upgrade, not HTTP SSE: each text message is already a
+     * `DshServerRequest` JSON envelope. This yields those envelopes and ends on
+     * close/abort, letting `sessionEvents()` reconnect through the same
+     * history-replay loop.
+     */
+    muxWebSocket(signal: AbortSignal): AsyncGenerator<DshServerRequest>;
+    /**
+     * Replay session.history events that are newer than `state.lastSeq`, updating
+     * `state.lastSeq` as it goes. Yields each non-duplicate SessionEvent. Used for
+     * both the initial baseline (first subscription) and reconnect gap-fill.
+     */
+    private replayHistory;
+    /**
+     * Per-session subscription: yields session events (and approval notices) for
+     * `sessionId`, auto-reconnecting on stream drop/error and replaying
+     * `session.history` to fill the gap (dedup by seq). Terminates on turn/end
+     * or `signal` abort.
+     */
+    sessionEvents(sessionId: string, cwd: string, signal: AbortSignal, initialSeq?: number): AsyncGenerator<DshStreamItem>;
+    /** Extract TokenUsage from an assistant/message data payload (absent → undefined). */
+    static usageOf(data: Record<string, unknown>): DshTokenUsage | undefined;
+}
+export {};

package/dist/runner/dsh/client.js

@@ -0,0 +1,418 @@
+/**
+ * DshClient — HTTP client for the DSH Web Host proxy.
+ *
+ * Two transports:
+ *  1. unary POST /api/<method> (client-request → server-response).
+ *  2. SSE GET /api/events.mux (all-session aggregated stream). Frames are
+ *     ServerRequest envelopes; `method` equals the MuxFrame's `type`.
+ *
+ * The client is stateless apart from the base URL: each `run()` opens its own
+ * mux subscription and closes it on terminal. `sessionEvents()` wraps the raw
+ * mux with per-session filtering plus reconnect + history-replay dedup
+ * (DSH v1 has no `since` resume — reconnection = reopen stream + refetch
+ * history, dedup by event seq).
+ */
+import { getLogger } from '../../logger/index.js';
+function defaultWebSocketFactory(url) {
+    const Ctor = globalThis.WebSocket;
+    if (!Ctor)
+        throw new Error('DSH WebSocket is unavailable');
+    return new Ctor(url);
+}
+export class DshError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'DshError';
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Backoff between mux reconnects to avoid a hot loop on a dropping server. */
+const RECONNECT_BACKOFF_MS = 200;
+export class DshClient {
+    baseUrl;
+    fetchImpl;
+    webSocketImpl;
+    constructor(baseUrl, fetchImpl = fetch, webSocketImpl = defaultWebSocketFactory) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.fetchImpl = fetchImpl;
+        this.webSocketImpl = webSocketImpl;
+    }
+    /** Perform a unary POST and return the ok value; throws DshError on failure. */
+    async unary(method, payload) {
+        const rpcId = `rpc-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/api/${method}`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ type: 'client-request', rpcId, method, payload }),
+            });
+        }
+        catch (err) {
+            throw new DshError('transport', `DSH unary ${method} transport error: ${err.message}`);
+        }
+        if (!res.ok) {
+            throw new DshError('http', `DSH HTTP ${res.status} for ${method}`);
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch (err) {
+            throw new DshError('protocol', `DSH ${method} returned non-JSON: ${err.message}`);
+        }
+        if (body.result?.ok !== true) {
+            const err = body.result?.error;
+            throw new DshError(err?.code ?? 'error', err?.message ?? `DSH ${method} failed`, err?.details ?? {});
+        }
+        return body.result.value;
+    }
+    /** Create a session. Pass `agentPreset` to pin the session's preset (fixed at
+     *  creation). */
+    async createSession(payload) {
+        return (await this.unary('session.create', payload));
+    }
+    /** Align the session's model/reasoningEffort (also persists as global default
+     *  server-side). Failures are surfaced as DshError for the caller to downgrade. */
+    async selectModel(payload) {
+        const value = (await this.unary('session.selectModel', payload));
+        return value.selected;
+    }
+    /** Read the session's current model selection + full model catalog. */
+    async sessionModels(sessionId) {
+        return (await this.unary('session.models', { sessionId }));
+    }
+    /** Read the model catalog (session-independent, llm.models). */
+    async listModels() {
+        return (await this.unary('llm.models', {}));
+    }
+    /** Read the preset catalog (agentPreset.list). */
+    async listPresets() {
+        return (await this.unary('agentPreset.list', {}));
+    }
+    /**
+     * Return the highest event `seq` currently persisted in session.history.
+     *
+     * The caller snapshots this before `session.prompt`. `session.history` is a
+     * full-session replay rather than a delta, so this high-water mark is what
+     * lets a subsequent replay skip every already-completed turn.
+     */
+    async latestEventSeq(sessionId) {
+        const value = (await this.unary('session.history', {
+            sessionId,
+            maxMessages: 1,
+        }));
+        let max = -1;
+        for (const entry of value.events ?? []) {
+            const seq = entry.event?.seq;
+            if (typeof seq === 'number' && seq > max)
+                max = seq;
+        }
+        return max;
+    }
+    /**
+     * Raw SSE mux stream: yields ServerRequest envelopes until the stream ends,
+     * errors, or `signal` aborts. Does NOT reconnect (the caller owns retry).
+     */
+    async *mux(signal) {
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/api/events.mux`, {
+                method: 'GET',
+                headers: { accept: 'text/event-stream' },
+                signal,
+            });
+        }
+        catch (err) {
+            if (signal.aborted)
+                return;
+            throw new DshError('transport', `DSH mux open error: ${err.message}`);
+        }
+        if (!res.ok || !res.body) {
+            throw new DshError('http', `DSH mux HTTP ${res.status}`, { status: res.status });
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            for (;;) {
+                if (signal.aborted)
+                    break;
+                let result;
+                try {
+                    result = await reader.read();
+                }
+                catch (err) {
+                    if (signal.aborted)
+                        break;
+                    throw new DshError('transport', `DSH mux read error: ${err.message}`);
+                }
+                if (result.done)
+                    break;
+                buffer += decoder.decode(result.value, { stream: true });
+                let idx;
+                while ((idx = buffer.indexOf('\n\n')) !== -1) {
+                    const chunk = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx + 2);
+                    const dataLine = chunk.split('\n').find((l) => l.startsWith('data:'));
+                    if (!dataLine)
+                        continue;
+                    const json = dataLine.slice(5).trim();
+                    if (!json)
+                        continue;
+                    try {
+                        const frame = JSON.parse(json);
+                        if (frame?.type === 'server-request')
+                            yield frame;
+                    }
+                    catch {
+                        getLogger().warn('[dsh] dropped malformed mux frame');
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+            try {
+                await res.body.cancel();
+            }
+            catch {
+                /* ignore cancel error */
+            }
+        }
+    }
+    /**
+     * WebSocket mux stream. The real DSH `/api/events.mux` endpoint is a
+     * WebSocket upgrade, not HTTP SSE: each text message is already a
+     * `DshServerRequest` JSON envelope. This yields those envelopes and ends on
+     * close/abort, letting `sessionEvents()` reconnect through the same
+     * history-replay loop.
+     */
+    async *muxWebSocket(signal) {
+        let socket;
+        try {
+            socket = this.webSocketImpl(`${this.baseUrl.replace(/^http/, 'ws')}/api/events.mux`);
+        }
+        catch (err) {
+            throw new DshError('transport', `DSH mux WebSocket open error: ${err.message}`);
+        }
+        const queue = [];
+        let waiter = null;
+        let ended = false;
+        let failure;
+        const settle = (frame) => {
+            if (waiter) {
+                const resolve = waiter;
+                waiter = null;
+                resolve(frame);
+                return;
+            }
+            if (frame)
+                queue.push(frame);
+            else
+                ended = true;
+        };
+        socket.onmessage = (event) => {
+            if (ended)
+                return;
+            if (typeof event.data !== 'string')
+                return;
+            try {
+                const frame = JSON.parse(event.data);
+                if (frame?.type === 'server-request')
+                    settle(frame);
+            }
+            catch {
+                getLogger().warn('[dsh] dropped malformed WebSocket mux frame');
+            }
+        };
+        socket.onerror = () => {
+            if (ended)
+                return;
+            failure = new DshError('transport', 'DSH mux WebSocket error');
+            ended = true;
+            settle(undefined);
+        };
+        socket.onclose = () => {
+            if (ended)
+                return;
+            ended = true;
+            settle(undefined);
+        };
+        const onAbort = () => {
+            if (ended)
+                return;
+            ended = true;
+            settle(undefined);
+            try {
+                socket.close();
+            }
+            catch {
+                /* ignore close error */
+            }
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        const next = () => new Promise((resolve) => {
+            if (queue.length > 0) {
+                resolve(queue.shift());
+                return;
+            }
+            if (ended) {
+                resolve(undefined);
+                return;
+            }
+            waiter = resolve;
+        });
+        try {
+            while (!signal.aborted) {
+                const frame = await next();
+                if (frame === undefined) {
+                    if (failure && !signal.aborted)
+                        throw failure;
+                    return;
+                }
+                yield frame;
+            }
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+            try {
+                socket.close();
+            }
+            catch {
+                /* ignore close error */
+            }
+        }
+    }
+    /**
+     * Replay session.history events that are newer than `state.lastSeq`, updating
+     * `state.lastSeq` as it goes. Yields each non-duplicate SessionEvent. Used for
+     * both the initial baseline (first subscription) and reconnect gap-fill.
+     */
+    async *replayHistory(sessionId, signal, state, logTag) {
+        try {
+            const value = (await this.unary('session.history', {
+                sessionId,
+                maxMessages: 100,
+            }));
+            for (const entry of value.events ?? []) {
+                if (signal.aborted)
+                    return;
+                const ev = entry.event;
+                if (!ev)
+                    continue;
+                const seq = ev.seq;
+                if (typeof seq === 'number' && seq <= state.lastSeq)
+                    continue;
+                if (typeof seq === 'number')
+                    state.lastSeq = seq;
+                yield ev;
+            }
+        }
+        catch (err) {
+            if (signal.aborted)
+                return;
+            getLogger().warn(`[dsh] ${logTag} failed for session ${sessionId}: ${err.message}`);
+        }
+    }
+    /**
+     * Per-session subscription: yields session events (and approval notices) for
+     * `sessionId`, auto-reconnecting on stream drop/error and replaying
+     * `session.history` to fill the gap (dedup by seq). Terminates on turn/end
+     * or `signal` abort.
+     */
+    async *sessionEvents(sessionId, cwd, signal, initialSeq = -1) {
+        const state = { lastSeq: initialSeq };
+        // Initial baseline: before opening the first live mux subscription, replay
+        // history once so events produced between prompt-accept and the mux opening
+        // (e.g. a fast turn that already ended) are not lost. Dedup by seq keeps the
+        // replay and the live stream convergent.
+        for await (const ev of this.replayHistory(sessionId, signal, state, 'initial history baseline')) {
+            if (signal.aborted)
+                return;
+            yield { kind: 'event', sessionId, event: ev };
+            if (ev.type === 'turn/end')
+                return;
+        }
+        let muxMode = 'fetch';
+        while (!signal.aborted) {
+            let dropped = false;
+            try {
+                const frames = muxMode === 'websocket' ? this.muxWebSocket(signal) : this.mux(signal);
+                for await (const frame of frames) {
+                    if (signal.aborted)
+                        return;
+                    if (frame.method === 'stream/error') {
+                        dropped = true;
+                        break;
+                    }
+                    if (frame.method === 'approval/requested') {
+                        const p = frame.payload;
+                        if (p?.sessionId === sessionId && p.approvalId) {
+                            yield {
+                                kind: 'approval',
+                                sessionId,
+                                approvalId: p.approvalId,
+                                toolName: p.toolName ?? '',
+                                reason: p.reason,
+                            };
+                        }
+                        continue;
+                    }
+                    if (frame.method !== 'session/event')
+                        continue;
+                    const payload = frame.payload;
+                    if (!payload || payload.sessionId !== sessionId || !payload.event)
+                        continue;
+                    const seq = payload.event.seq;
+                    if (typeof seq === 'number' && seq <= state.lastSeq)
+                        continue; // dedup
+                    if (typeof seq === 'number')
+                        state.lastSeq = seq;
+                    yield { kind: 'event', sessionId, event: payload.event };
+                    if (payload.event.type === 'turn/end')
+                        return;
+                }
+                dropped = true; // stream closed normally → treat as drop, replay history
+            }
+            catch (err) {
+                if (signal.aborted)
+                    return;
+                if (muxMode === 'fetch' &&
+                    err instanceof DshError &&
+                    err.code === 'http' &&
+                    err.details.status === 426) {
+                    getLogger().info(`[dsh] mux endpoint requires WebSocket upgrade; switching transports for session ${sessionId}`);
+                    muxMode = 'websocket';
+                    dropped = true;
+                    continue;
+                }
+                getLogger().warn(`[dsh] mux disconnected for session ${sessionId}: ${err.message}; replaying history`);
+                dropped = true;
+            }
+            if (signal.aborted)
+                return;
+            if (!dropped)
+                break;
+            // Reconnect baseline: replay history events after lastSeq (dedup keeps
+            // the live stream and the replay convergent).
+            for await (const ev of this.replayHistory(sessionId, signal, state, 'history replay')) {
+                if (signal.aborted)
+                    return;
+                yield { kind: 'event', sessionId, event: ev };
+                if (ev.type === 'turn/end')
+                    return;
+            }
+            // Bound reconnect frequency.
+            await new Promise((resolve) => setTimeout(resolve, RECONNECT_BACKOFF_MS));
+        }
+    }
+    /** Extract TokenUsage from an assistant/message data payload (absent → undefined). */
+    static usageOf(data) {
+        return data.usage ?? undefined;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/runner/dsh/fake-dsh-server.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Fake DSH Web Host HTTP server for agent-dsh tests.
+ *
+ * Mimics the real DSH wire protocol (deepseek-harness apiproxy handler.ts):
+ *   - POST /api/<method>: body {type:'client-request',rpcId,method,payload},
+ *     response {type:'server-response',rpcId,result:{ok:true,value}|{ok:false,error}}.
+ *   - SSE GET /api/events.mux: frames `data: {type:'server-request',rpcId,
+ *     method:<frame.type>, payload:<frame>}\n\n`.
+ *
+ * The mux frame queue is consumed ACROSS connections (shared pointer): the
+ * first connection drains a prefix then closes; a reconnect drains the rest —
+ * which is exactly how a server that drops mid-turn is modelled. Unary
+ * handlers and the history value are registered by the test.
+ */
+import { type Server } from 'node:http';
+export interface FakeRpcResult {
+    ok: true;
+    value: unknown;
+}
+export interface FakeRpcError {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+export type FakeUnaryHandler = (payload: unknown, rpcId: string) => FakeRpcResult | FakeRpcError;
+export interface DshServerRequestRecord {
+    method: string;
+    rpcId: string;
+    payload: unknown;
+}
+export declare class FakeDshServer {
+    readonly server: Server;
+    private readonly unaryHandlers;
+    private muxFrames;
+    private historyValue;
+    private port;
+    private closedConnections;
+    readonly requests: DshServerRequestRecord[];
+    constructor();
+    get baseUrl(): string;
+    get connectionCount(): number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    register(method: string, handler: FakeUnaryHandler): void;
+    setMuxFrames(frames: Array<object | {
+        close: true;
+    }>): void;
+    setHistoryValue(value: unknown): void;
+    /** Synchronous unary dispatch (no HTTP) — used by tests that inject the
+     *  reader's sync transport to avoid the spawnSync-in-process deadlock. */
+    dispatchSync(method: string, payload: unknown, rpcId?: string): {
+        type: string;
+        rpcId: string;
+        result: FakeRpcResult | FakeRpcError;
+    };
+    private handleMux;
+}