lark-remote 0.5.3 → 0.5.5

package/dist/runner/dsh/client.js

@@ -1,23 +1,37 @@
 /**
- * DshClient — HTTP client for the DSH Web Host proxy.
+ * DshClient — HTTP/WebSocket client for the DSH Web Host.
  *
- * 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`.
+ * DSH 0.2.x guardrails:
+ *  1. `/api/*` and `/api/remote.mux` require a signed `dsh-auth-*` cookie.
+ *     We mint the v1 cookie from DSH's durable browser-session secret; the
+ *     launch token remains a fallback via `GET /?token=<launch token>`.
+ *  2. Unary calls are POST `/api/<namespace>/<method>` envelopes whose
+ *     `payload` is `{args:<request>}`.
+ *  3. Live session data is a logical stream over `/api/remote.mux`:
+ *     `{type:'open',streamId,endpoint:'session/follow',payload}` →
+ *     `{type:'item',streamId,value}` / `{type:'end',streamId}`.
+ *     The Gateway-owned `$events` stream carries answerable
+ *     `approval/request` waterfalls; answers go back through
+ *     `$events/result`.
  *
- * 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).
+ * The client is stateless apart from the base URL and auth cookie: each
+ * `run()` opens its own remote mux subscription and closes it on terminal.
+ * `sessionEvents()` adds per-session filtering, reconnect + follow-snapshot
+ * replay, and seq-based dedup.
  */
+import { randomUUID } from 'node:crypto';
+import WebSocket from 'ws';
 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);
+import { DSH_COOKIE_LIFETIME_MS, isDshCredentialsNotFound, mintDshBrowserCookie, readDshBrowserSecret, resolveDshCredentialsFile, } from './auth.js';
+function defaultWebSocketFactory(url, options) {
+    const socket = new WebSocket(url, {
+        ...(options?.headers ? { headers: options.headers } : {}),
+    });
+    const raw = socket;
+    raw.on('unexpected-response', (_request, response) => {
+        socket.onunexpectedresponse?.({ statusCode: response.statusCode });
+    });
+    return socket;
 }
 export class DshError extends Error {
     code;
@@ -29,172 +43,340 @@ export class DshError extends Error {
         this.details = details;
     }
 }
+function isDshAuthError(error) {
+    return (error instanceof DshError &&
+        error.code === 'http' &&
+        (error.details.status === 401 || error.details.status === 403));
+}
 /** Backoff between mux reconnects to avoid a hot loop on a dropping server. */
 const RECONNECT_BACKOFF_MS = 200;
+/** Follow snapshot budget. `session/follow` also stays live after the snapshot. */
+const FOLLOW_MAX_MESSAGES = 200;
+/** Default unary timeout: long prompts are unbounded on the server side. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+/** Extract the `token` query parameter from a pasted `dsh web` URL. */
+export function extractDshToken(raw) {
+    const value = (raw ?? '').trim();
+    if (!value)
+        return '';
+    if (!value.includes('token=') && !value.includes('://'))
+        return value;
+    try {
+        const url = new URL(value.startsWith('?') ? `http://dsh.invalid/${value}` : value);
+        return url.searchParams.get('token') ?? value;
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Remote methods take named parameters. Most session methods call their single
+ * argument `request`; `session/list` reserves `_request`; catalog methods take
+ * no arguments. `commands/*` address the receiving agent by its wire field
+ * `agentId`, so their payload is already in wire shape (pass-through).
+ * The gateway rejects any other `args` shape.
+ */
+const DSH_ARGS_KEY = {
+    'session/list': '_request',
+    'session/create': 'request',
+    'session/prompt': 'request',
+    'session/cancel': 'request',
+    'session/selectModel': 'request',
+    'session/projections': 'request',
+    'session/page': 'request',
+    'session/follow': 'request',
+    'session/modelCatalog': null,
+    'agentPresets/list': null,
+    'permissionPresets/catalog': null,
+};
+export function dshArgs(method, payload) {
+    const key = DSH_ARGS_KEY[method];
+    if (key === null)
+        return {};
+    if (key === undefined)
+        return payload;
+    return { [key]: payload };
+}
 export class DshClient {
     baseUrl;
+    token;
+    credentialsFile;
+    readCredentials;
+    now;
+    cookieLifetimeMs;
     fetchImpl;
     webSocketImpl;
-    constructor(baseUrl, fetchImpl = fetch, webSocketImpl = defaultWebSocketFactory) {
+    requestTimeoutMs;
+    cookiePromise;
+    constructor(baseUrl, options = {}) {
         this.baseUrl = baseUrl.replace(/\/$/, '');
-        this.fetchImpl = fetchImpl;
-        this.webSocketImpl = webSocketImpl;
+        this.token = extractDshToken(options.token);
+        this.credentialsFile =
+            options.credentialsFile?.trim() || resolveDshCredentialsFile(process.env, options.dshHome);
+        this.readCredentials = options.readCredentials ?? readDshBrowserSecret;
+        this.now = options.now ?? Date.now;
+        this.cookieLifetimeMs = options.cookieLifetimeMs ?? DSH_COOKIE_LIFETIME_MS;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.webSocketImpl = options.webSocketImpl ?? defaultWebSocketFactory;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     }
-    /** 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 }),
+    /**
+     * Resolve a DSH browser cookie. The durable credentials file is read on every
+     * call so a rotated signing secret is picked up without restarting
+     * lark-remote. Token bootstrap remains a fallback for hosts without that
+     * file; unlike `/connect`, the index handshake mints a v1 cookie that DSH
+     * accepts for API and WebSocket requests across its own restarts.
+     */
+    async authCookie(force = false, signal) {
+        const fromCredentials = await this.cookieFromCredentials();
+        if (fromCredentials)
+            return fromCredentials;
+        if (!this.token)
+            return undefined;
+        if (force)
+            this.cookiePromise = undefined;
+        if (!this.cookiePromise) {
+            this.cookiePromise = (async () => {
+                const url = `${this.baseUrl}/?token=${encodeURIComponent(this.token)}`;
+                let res;
+                try {
+                    res = await this.fetchImpl(url, {
+                        method: 'GET',
+                        redirect: 'manual',
+                        ...(signal ? { signal } : {}),
+                    });
+                }
+                catch (err) {
+                    if (signal?.aborted)
+                        throw err;
+                    throw new DshError('transport', `DSH auth transport error: ${err.message}`);
+                }
+                if (res.status !== 303 && !res.ok) {
+                    throw new DshError('http', `DSH auth HTTP ${res.status}: 凭据文件不可用，且 dsh web 启动 token 无效`, { status: res.status });
+                }
+                const setCookies = typeof res.headers.getSetCookie === 'function'
+                    ? res.headers.getSetCookie()
+                    : [res.headers.get('set-cookie')].filter((v) => !!v);
+                const cookie = setCookies
+                    .map((value) => value.split(';')[0]?.trim())
+                    .filter((value) => !!value)
+                    .join('; ');
+                if (!cookie) {
+                    throw new DshError('auth', 'DSH index handshake did not return a session cookie');
+                }
+                return cookie;
+            })();
+            // A failed handshake must not poison later retries (e.g. after the user
+            // updates agents.dsh.token in config.yaml and the runner is rebuilt).
+            this.cookiePromise.catch(() => {
+                this.cookiePromise = undefined;
             });
         }
-        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;
+        return this.cookiePromise;
+    }
+    /** Mint a v1 browser cookie from DSH's durable signing secret. */
+    async cookieFromCredentials() {
         try {
-            body = (await res.json());
+            const secret = await this.readCredentials(this.credentialsFile);
+            return mintDshBrowserCookie(this.baseUrl, secret, this.now(), this.cookieLifetimeMs);
         }
         catch (err) {
-            throw new DshError('protocol', `DSH ${method} returned non-JSON: ${err.message}`);
+            if (isDshCredentialsNotFound(err))
+                return undefined;
+            if (this.token) {
+                getLogger().warn(`[dsh] cannot use DSH credentials file ${this.credentialsFile}: ${err.message}; ` +
+                    'falling back to the launch token');
+                return undefined;
+            }
+            throw new DshError('auth', `DSH auth credentials file ${this.credentialsFile}: ${err.message}`);
+        }
+    }
+    /**
+     * Perform a unary POST and return the ok value; throws DshError on failure.
+     *
+     * `signal` aborts the request when the run is stopped; a timeout (default
+     * `requestTimeoutMs`) guards against a server that accepted the connection
+     * but never answers. Both are composed into the request's AbortSignal.
+     */
+    async unary(method, payload, opts = {}) {
+        const _timeoutMs = opts.timeoutMs ?? this.requestTimeoutMs;
+        // 0/负数 = 不设超时（兼容「长请求不取消」的配置），其余走 AbortSignal.timeout。
+        const timeoutSignal = _timeoutMs > 0 ? AbortSignal.timeout(_timeoutMs) : undefined;
+        const signal = opts.signal && timeoutSignal
+            ? AbortSignal.any([opts.signal, timeoutSignal])
+            : (opts.signal ?? timeoutSignal);
+        const rpcId = `rpc-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (opts.signal?.aborted) {
+                throw new DshError('aborted', `DSH unary ${method} aborted before send`);
+            }
+            let cookie;
+            try {
+                cookie = await this.authCookie(attempt > 0, signal);
+            }
+            catch (err) {
+                if (opts.signal?.aborted || signal?.aborted) {
+                    throw this.abortError(method, err, opts.signal, timeoutSignal, _timeoutMs);
+                }
+                // A token bootstrap can race a DSH restart; retry once with a fresh
+                // credentials read before surfacing the deterministic auth failure.
+                if (attempt === 0 &&
+                    err instanceof DshError &&
+                    err.code === 'http' &&
+                    err.details.status === 401) {
+                    continue;
+                }
+                throw err;
+            }
+            const headers = { 'content-type': 'application/json' };
+            if (cookie)
+                headers.cookie = cookie;
+            let res;
+            try {
+                res = await this.fetchImpl(`${this.baseUrl}/api/${method}`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        type: 'client-request',
+                        rpcId,
+                        method,
+                        payload: { args: dshArgs(method, payload) },
+                    }),
+                    ...(signal ? { signal } : {}),
+                });
+            }
+            catch (err) {
+                if (opts.signal?.aborted || signal?.aborted) {
+                    throw this.abortError(method, err, opts.signal, timeoutSignal, _timeoutMs);
+                }
+                throw new DshError('transport', `DSH unary ${method} transport error: ${err.message}`);
+            }
+            if (opts.signal?.aborted) {
+                throw new DshError('aborted', `DSH unary ${method} aborted`);
+            }
+            if (res.status === 401 && attempt === 0) {
+                this.cookiePromise = undefined;
+                continue;
+            }
+            if (res.status === 401) {
+                throw new DshError('http', `DSH HTTP 401 for ${method}: 认证失败；请确认 ${this.credentialsFile} 可读，` +
+                    '或在 config.yaml 的 agents.dsh.token 填入当前 dsh web 启动 token。' +
+                    '若凭据文件可读且格式正确，可能是 DSH 版本改变了 cookie 认证格式', { status: 401 });
+            }
+            if (!res.ok) {
+                throw new DshError('http', `DSH HTTP ${res.status} for ${method}`, {
+                    status: res.status,
+                });
+            }
+            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;
         }
-        if (body.result?.ok !== true) {
-            const err = body.result?.error;
-            throw new DshError(err?.code ?? 'error', err?.message ?? `DSH ${method} failed`, err?.details ?? {});
+        throw new DshError('auth', `DSH ${method} authentication failed after refresh`);
+    }
+    /** Distinguish "run stopped" (abort) from "server did not answer" (timeout). */
+    abortError(method, err, runSignal, timeoutSignal, timeoutMs) {
+        if (runSignal?.aborted) {
+            return new DshError('aborted', `DSH unary ${method} aborted`, { cause: err });
+        }
+        if (timeoutSignal?.aborted) {
+            return new DshError('timeout', `DSH unary ${method} timed out after ${timeoutMs}ms`, {
+                cause: err,
+            });
         }
-        return body.result.value;
+        return new DshError('aborted', `DSH unary ${method} aborted: ${err.message}`);
     }
     /** Create a session. Pass `agentPreset` to pin the session's preset (fixed at
      *  creation). */
-    async createSession(payload) {
-        return (await this.unary('session.create', payload));
+    async createSession(payload, opts) {
+        return (await this.unary('session/create', payload, opts));
     }
     /** 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));
+    async selectModel(payload, opts) {
+        const value = (await this.unary('session/selectModel', payload, opts));
         return value.selected;
     }
-    /** 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', {}));
+    /** Read the model catalog (session/modelCatalog). */
+    async listModels(opts) {
+        return (await this.unary('session/modelCatalog', {}, opts));
     }
     /**
-     * Return the highest event `seq` currently persisted in session.history.
+     * Execute one slash command against a session (commands/execute).
+     *
+     * This is the only way to run a DSH command: `session/prompt` turns the text
+     * into an ordinary user message and never routes it through the command
+     * registry, so `/compact` sent as a prompt would just be model input.
      *
-     * 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.
+     * The RPC settles when the handler settles, not when it is accepted: DSH's
+     * `/compact` waits for the compaction to finish. Callers therefore must pass
+     * an explicit `timeoutMs` (0 = no unary budget) and rely on their own
+     * cancellation/watchdog instead of the 60s default.
      */
-    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;
+    async executeCommand(sessionId, line, opts) {
+        const value = (await this.unary('commands/execute', { agentId: sessionId, line, submittedAttachments: [] }, opts));
+        if (!value || typeof value !== 'object')
+            return undefined;
+        const result = value.result && typeof value.result === 'object' ? value.result : value;
+        return {
+            ...(typeof value.commandId === 'string' ? { commandId: value.commandId } : {}),
+            ...(result.kind === 'success' || result.kind === 'error' ? { kind: result.kind } : {}),
+            ...(typeof result.text === 'string' ? { text: result.text } : {}),
+            ...(typeof result.sourceEventSeq === 'number'
+                ? { sourceEventSeq: result.sourceEventSeq }
+                : {}),
+        };
+    }
+    /** Read the preset catalog (agentPresets/list). */
+    async listPresets() {
+        return (await this.unary('agentPresets/list', {}));
+    }
+    /** Read the permission preset catalog (permissionPresets/catalog). */
+    async listPermissionPresets() {
+        return (await this.unary('permissionPresets/catalog', {}));
+    }
+    /** Answer one forwarded approval waterfall ($events/result). */
+    async answerRemoteEvent(clientId, eventId, outcome, opts) {
+        await this.unary('$events/result', { clientId, eventId, outcome }, opts);
     }
     /**
-     * Raw SSE mux stream: yields ServerRequest envelopes until the stream ends,
-     * errors, or `signal` aborts. Does NOT reconnect (the caller owns retry).
+     * Return the highest event `seq` currently persisted for the session.
+     *
+     * `session/projections` is the unary watermark (the old `session.history`
+     * high-water scan is gone in 0.2.x). The caller snapshots this before
+     * `session/prompt` so a follow snapshot can skip already-completed turns.
      */
-    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 */
-            }
-        }
+    async latestEventSeq(sessionId, opts) {
+        const value = (await this.unary('session/projections', { sessionId }, opts));
+        return typeof value?.asOfSeq === 'number' ? value.asOfSeq : -1;
+    }
+    /** Read one cold history page. `throughSeq` normally comes from
+     *  `latestEventSeq()`; `session/page` needs an inclusive cursor. */
+    async page(sessionId, throughSeq, maxMessages, opts) {
+        return (await this.unary('session/page', {
+            address: { kind: 'session', sessionId },
+            throughSeq,
+            maxMessages,
+        }, opts));
     }
     /**
-     * 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.
+     * One logical stream over `/api/remote.mux`. The WebSocket must carry the
+     * same auth cookie as unary calls. Ends on the server's `end` frame, socket
+     * close, error, or `signal` abort.
      */
-    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}`);
-        }
+    async *muxStream(endpoint, payload, signal) {
+        const cookie = await this.authCookie();
+        const socket = this.webSocketImpl(`${this.baseUrl.replace(/^http/, 'ws')}/api/remote.mux`, cookie ? { headers: { cookie } } : undefined);
+        const streamId = `lr-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
         const queue = [];
         let waiter = null;
         let ended = false;
@@ -211,24 +393,68 @@ export class DshClient {
             else
                 ended = true;
         };
-        socket.onmessage = (event) => {
+        socket.onopen = () => {
             if (ended)
                 return;
-            if (typeof event.data !== 'string')
+            try {
+                socket.send(JSON.stringify({
+                    type: 'open',
+                    streamId,
+                    endpoint,
+                    payload,
+                }));
+            }
+            catch (err) {
+                failure = new DshError('transport', `DSH remote mux send error: ${err.message}`);
+                ended = true;
+                settle(undefined);
+            }
+        };
+        socket.onmessage = (event) => {
+            if (ended)
                 return;
+            const text = typeof event.data === 'string'
+                ? event.data
+                : Buffer.isBuffer(event.data)
+                    ? event.data.toString('utf8')
+                    : String(event.data);
+            let message;
             try {
-                const frame = JSON.parse(event.data);
-                if (frame?.type === 'server-request')
-                    settle(frame);
+                message = JSON.parse(text);
             }
             catch {
-                getLogger().warn('[dsh] dropped malformed WebSocket mux frame');
+                getLogger().warn('[dsh] dropped malformed remote mux frame');
+                return;
+            }
+            if (message.streamId !== streamId)
+                return;
+            if (message.type === 'item' && message.value) {
+                settle(message.value);
+                return;
+            }
+            if (message.type === 'end') {
+                ended = true;
+                settle(undefined);
+                return;
+            }
+            if (message.type === 'error') {
+                failure = new DshError(message.error?.code ?? 'stream', message.error?.message ?? 'DSH remote stream failed', message.error?.details ?? {});
+                ended = true;
+                settle(undefined);
             }
         };
         socket.onerror = () => {
             if (ended)
                 return;
-            failure = new DshError('transport', 'DSH mux WebSocket error');
+            failure = new DshError('transport', 'DSH remote mux WebSocket error');
+            ended = true;
+            settle(undefined);
+        };
+        socket.onunexpectedresponse = (event) => {
+            if (ended)
+                return;
+            const status = event.statusCode;
+            failure = new DshError('http', `DSH remote mux WebSocket HTTP ${status === undefined ? 'error' : status}`, status === undefined ? {} : { status });
             ended = true;
             settle(undefined);
         };
@@ -283,126 +509,203 @@ export class DshClient {
             }
         }
     }
+    /** One logical `session/follow` stream. */
+    async *followStream(sessionId, signal) {
+        const payload = {
+            args: dshArgs('session/follow', {
+                address: { kind: 'session', sessionId },
+                assistantStream: true,
+                maxMessages: FOLLOW_MAX_MESSAGES,
+            }),
+        };
+        for await (const frame of this.muxStream('session/follow', payload, signal)) {
+            yield frame;
+        }
+    }
     /**
-     * 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.
+     * Consume the Gateway-owned `$events` stream. The stream is owner-only and
+     * answer-capable; each waterfall for another session is delegated with
+     * `next` so a different lark-remote workspace cannot park it.
      */
-    async *replayHistory(sessionId, signal, state, logTag) {
-        try {
-            const value = (await this.unary('session.history', {
-                sessionId,
-                maxMessages: 100,
-            }));
-            for (const entry of value.events ?? []) {
+    async *approvalEvents(sessionId, signal) {
+        let authRefreshAttempted = false;
+        let reconnectAttempts = 0;
+        while (!signal.aborted) {
+            let streamClientId;
+            let sawReady = false;
+            try {
+                for await (const raw of this.muxStream('$events', { args: {} }, signal)) {
+                    if (signal.aborted)
+                        return;
+                    const frame = raw;
+                    if (frame.type === 'ready') {
+                        authRefreshAttempted = false;
+                        sawReady = true;
+                        streamClientId = frame.clientId;
+                        yield { kind: 'ready', clientId: streamClientId };
+                        continue;
+                    }
+                    if (frame.type === 'waterfall') {
+                        if (!streamClientId) {
+                            yield {
+                                kind: 'unavailable',
+                                message: 'DSH approval stream sent a waterfall before ready',
+                            };
+                            return;
+                        }
+                        if (frame.event !== 'approval/request' || frame.agentId !== sessionId) {
+                            // Every owner answerer receives the waterfall. A non-owner of
+                            // the session must explicitly delegate, otherwise DSH waits.
+                            void this.answerRemoteEvent(streamClientId, frame.eventId, { kind: 'next' }, { signal }).catch((err) => {
+                                if (!signal.aborted) {
+                                    getLogger().warn(`[dsh] approval waterfall delegation failed eventId=${frame.eventId}: ${err.message}`);
+                                }
+                            });
+                            continue;
+                        }
+                        const data = frame.request;
+                        const toolName = typeof data.toolName === 'string' ? data.toolName : '';
+                        const callId = typeof data.callId === 'string' ? data.callId : undefined;
+                        const reason = typeof data.reason === 'string' ? data.reason : undefined;
+                        yield {
+                            kind: 'request',
+                            eventId: frame.eventId,
+                            clientId: streamClientId,
+                            toolName,
+                            ...(callId ? { callId } : {}),
+                            ...(reason ? { reason } : {}),
+                        };
+                        continue;
+                    }
+                    if (frame.type === 'cancel') {
+                        yield { kind: 'cancelled', eventId: frame.eventId };
+                    }
+                }
+            }
+            catch (err) {
                 if (signal.aborted)
                     return;
-                const ev = entry.event;
-                if (!ev)
+                if (err instanceof DshError &&
+                    err.code === 'http' &&
+                    err.details.status === 401 &&
+                    !authRefreshAttempted) {
+                    authRefreshAttempted = true;
+                    this.cookiePromise = undefined;
+                    getLogger().warn(`[dsh] approval event stream authentication expired; refreshing credentials and reconnecting once`);
                     continue;
-                const seq = ev.seq;
-                if (typeof seq === 'number' && seq <= state.lastSeq)
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                const forbidden = (err instanceof DshError &&
+                    (err.code === 'gateway/interactions-forbidden' ||
+                        (err.code === 'http' && err.details.status === 403))) ||
+                    message.includes('interactions-forbidden');
+                if (!forbidden && reconnectAttempts < 3) {
+                    reconnectAttempts += 1;
+                    getLogger().warn(`[dsh] approval event stream dropped (attempt ${reconnectAttempts}/3); reconnecting`);
+                    await new Promise((resolve) => setTimeout(resolve, 200));
                     continue;
-                if (typeof seq === 'number')
-                    state.lastSeq = seq;
-                yield ev;
+                }
+                getLogger().warn(`[dsh] approval event stream unavailable: ${message}`);
+                yield { kind: 'unavailable', message };
+                return;
             }
-        }
-        catch (err) {
-            if (signal.aborted)
+            if (!signal.aborted) {
+                if (sawReady && reconnectAttempts < 3) {
+                    reconnectAttempts += 1;
+                    getLogger().warn(`[dsh] approval event stream ended (attempt ${reconnectAttempts}/3); reconnecting`);
+                    await new Promise((resolve) => setTimeout(resolve, 200));
+                    continue;
+                }
+                // A clean end before ready means the Host does not expose `$events`;
+                // fall back to the Web UI prompt instead of retrying forever.
+                yield { kind: 'unavailable', message: 'DSH approval event stream ended' };
                 return;
-            getLogger().warn(`[dsh] ${logTag} failed for session ${sessionId}: ${err.message}`);
+            }
+        }
+    }
+    /** Translate one durable event into a stream item (approvals are surfaced
+     *  separately; everything else is forwarded to the runner). */
+    eventItem(sessionId, event) {
+        if (event.type === 'approval/asked') {
+            const data = event.data;
+            if (!data.id)
+                return undefined;
+            return {
+                kind: 'approval',
+                sessionId,
+                approvalId: data.id,
+                toolName: data.toolName ?? '',
+                ...(data.callId ? { callId: data.callId } : {}),
+                ...(data.reason ? { reason: data.reason } : {}),
+            };
         }
+        return { kind: 'event', sessionId, event };
     }
     /**
-     * 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.
+     * Per-session subscription: yields session events, assistant stream chunks
+     * and approval notices for `sessionId`, auto-reconnecting on stream
+     * drop/error and replaying the follow snapshot (dedup by seq). Terminates on
+     * turn/end or `signal` abort.
      */
     async *sessionEvents(sessionId, 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';
+        let authRefreshAttempted = false;
         while (!signal.aborted) {
-            let dropped = false;
             try {
-                const frames = muxMode === 'websocket' ? this.muxWebSocket(signal) : this.mux(signal);
-                for await (const frame of frames) {
+                for await (const frame of this.followStream(sessionId, signal)) {
                     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,
-                            };
+                    authRefreshAttempted = false;
+                    if (frame.type === 'snapshot') {
+                        for (const record of frame.records ?? []) {
+                            const ev = record.event;
+                            if (!ev || ev.seq <= state.lastSeq)
+                                continue;
+                            state.lastSeq = ev.seq;
+                            const item = this.eventItem(sessionId, ev);
+                            if (item)
+                                yield item;
+                            if (ev.type === 'turn/end')
+                                return;
                         }
                         continue;
                     }
-                    if (frame.method !== 'session/event')
-                        continue;
-                    const payload = frame.payload;
-                    if (!payload || payload.sessionId !== sessionId || !payload.event)
+                    if (frame.type === 'event') {
+                        const ev = frame.event;
+                        if (ev.seq <= state.lastSeq)
+                            continue;
+                        state.lastSeq = ev.seq;
+                        const item = this.eventItem(sessionId, ev);
+                        if (item)
+                            yield item;
+                        if (ev.type === 'turn/end')
+                            return;
                         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;
+                    }
+                    if (frame.type === 'assistant-stream') {
+                        yield { kind: 'assistant-stream', sessionId, frame: frame.frame };
+                    }
                 }
-                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;
+                // A DSH restart invalidates the process-local v2 operator cookie. A
+                // fresh credentials read mints a new v1 cookie, so retry once; a
+                // second auth failure is deterministic and belongs on the run card.
+                if (isDshAuthError(err)) {
+                    if (!authRefreshAttempted) {
+                        authRefreshAttempted = true;
+                        this.cookiePromise = undefined;
+                        getLogger().warn(`[dsh] remote mux authentication expired for session ${sessionId}; refreshing credentials and reconnecting once`);
+                        continue;
+                    }
+                    throw err;
                 }
-                getLogger().warn(`[dsh] mux disconnected for session ${sessionId}: ${err.message}; replaying history`);
-                dropped = true;
+                getLogger().warn(`[dsh] remote mux disconnected for session ${sessionId}: ${err.message}; reconnecting`);
             }
             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));
         }
     }
@@ -411,4 +714,8 @@ export class DshClient {
         return data.usage ?? undefined;
     }
 }
+/** Stable client-side prompt identity persisted on the accepted user message. */
+export function newPromptRequestId() {
+    return `lark-remote-${randomUUID()}`;
+}
 //# sourceMappingURL=client.js.map