lark-remote 0.5.3 → 0.5.5

package/dist/runner/dsh/approval.js

@@ -0,0 +1,161 @@
+/**
+ * Correlate DSH's durable approval audit with its live answer waterfall.
+ *
+ * `session/follow` carries `approval/asked` / `approval/decided`; `$events`
+ * carries the answerable `approval/request` waterfall. The audit id is the
+ * stable identity shown on the Feishu card; the waterfall contributes the
+ * ephemeral `eventId` + `clientId` needed to answer it. Both are correlated by
+ * `callId`, with an order-independent pairing so either transport may arrive
+ * first.
+ */
+export class DshApprovalTracker {
+    audits = new Map();
+    waterfallByCallId = new Map();
+    bindings = new Map();
+    approvalIdByEventId = new Map();
+    waiters = new Map();
+    /** Record `approval/asked`; pair immediately when its waterfall is known. */
+    onAuditAsked(audit) {
+        const existing = this.bindings.get(audit.approvalId);
+        if (existing)
+            return existing;
+        this.audits.set(audit.approvalId, audit);
+        if (audit.callId) {
+            const waterfall = this.waterfallByCallId.get(audit.callId);
+            if (waterfall)
+                return this.bind(audit, waterfall);
+        }
+        return undefined;
+    }
+    /** Record an `approval/request` waterfall; pair when its audit is known. */
+    onWaterfall(waterfall) {
+        const existingApprovalId = this.approvalIdByEventId.get(waterfall.eventId);
+        if (existingApprovalId) {
+            // A reconnect re-delivers the same pending event with a new Client
+            // identity. Keep the card binding but refresh the answer channel.
+            const binding = this.bindings.get(existingApprovalId);
+            if (binding) {
+                binding.waterfall.clientId = waterfall.clientId;
+                if (waterfall.reason)
+                    binding.waterfall.reason = waterfall.reason;
+                if (waterfall.callId) {
+                    this.waterfallByCallId.set(waterfall.callId, binding.waterfall);
+                }
+            }
+            return undefined;
+        }
+        if (waterfall.callId)
+            this.waterfallByCallId.set(waterfall.callId, waterfall);
+        if (waterfall.callId) {
+            for (const audit of this.audits.values()) {
+                if (audit.callId === waterfall.callId && !this.bindings.has(audit.approvalId)) {
+                    return this.bind(audit, waterfall);
+                }
+            }
+            // Some approval types omit callId on the durable audit. Pair with the
+            // oldest unbound audit for the same tool before falling back to Web UI.
+            for (const audit of this.audits.values()) {
+                if (!audit.callId &&
+                    !this.bindings.has(audit.approvalId) &&
+                    audit.toolName === waterfall.toolName) {
+                    return this.bind(audit, waterfall);
+                }
+            }
+        }
+        // A missing callId is unusual but not fatal: pair with the oldest unbound
+        // audit for the same tool, preserving the audit id on the card.
+        if (!waterfall.callId) {
+            for (const audit of this.audits.values()) {
+                if (!this.bindings.has(audit.approvalId) && audit.toolName === waterfall.toolName) {
+                    return this.bind(audit, waterfall);
+                }
+            }
+        }
+        return undefined;
+    }
+    /** Mark an audit resolved (local response or an external decision). */
+    onDecided(approvalId) {
+        const binding = this.bindings.get(approvalId);
+        this.audits.delete(approvalId);
+        this.bindings.delete(approvalId);
+        if (binding) {
+            this.approvalIdByEventId.delete(binding.waterfall.eventId);
+            if (binding.waterfall.callId) {
+                const stored = this.waterfallByCallId.get(binding.waterfall.callId);
+                if (stored?.eventId === binding.waterfall.eventId) {
+                    this.waterfallByCallId.delete(binding.waterfall.callId);
+                }
+            }
+            this.resolveWaiters(approvalId, undefined);
+        }
+        return binding;
+    }
+    /** Mark a waterfall cancelled by the Host (another client answered it). */
+    onCancelled(eventId) {
+        const approvalId = this.approvalIdByEventId.get(eventId);
+        if (!approvalId)
+            return undefined;
+        return this.onDecided(approvalId);
+    }
+    getBinding(approvalId) {
+        return this.bindings.get(approvalId);
+    }
+    /**
+     * Wait for a waterfall to arrive after the audit card was rendered. The
+     * audit is appended before the waterfall is dispatched, so this window is
+     * normally tiny; the bound keeps a fast button click from failing.
+     */
+    async waitForBinding(approvalId, timeoutMs, signal) {
+        const current = this.bindings.get(approvalId);
+        if (current)
+            return current;
+        if (signal?.aborted)
+            return undefined;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (binding) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                const set = this.waiters.get(approvalId);
+                set?.delete(finish);
+                if (set && set.size === 0)
+                    this.waiters.delete(approvalId);
+                resolve(binding);
+            };
+            const onAbort = () => finish(undefined);
+            const timer = setTimeout(() => finish(undefined), timeoutMs);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            const set = this.waiters.get(approvalId) ?? new Set();
+            set.add(finish);
+            this.waiters.set(approvalId, set);
+        });
+    }
+    /** Drop all in-flight state when a run ends. */
+    clear() {
+        for (const approvalId of [...this.waiters.keys()])
+            this.resolveWaiters(approvalId, undefined);
+        this.audits.clear();
+        this.waterfallByCallId.clear();
+        this.bindings.clear();
+        this.approvalIdByEventId.clear();
+    }
+    bind(audit, waterfall) {
+        const binding = { audit, waterfall };
+        this.bindings.set(audit.approvalId, binding);
+        this.approvalIdByEventId.set(waterfall.eventId, audit.approvalId);
+        this.resolveWaiters(audit.approvalId, binding);
+        return binding;
+    }
+    resolveWaiters(approvalId, binding) {
+        const set = this.waiters.get(approvalId);
+        if (!set)
+            return;
+        this.waiters.delete(approvalId);
+        for (const waiter of [...set])
+            waiter(binding);
+    }
+}
+//# sourceMappingURL=approval.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Persistent DSH browser authentication.
+ *
+ * `dsh web` rotates its process launch token on every restart. The signed
+ * browser cookie is different: it is verified with the durable
+ * `client-connection/browser-session` secret in `$DSH_HOME/.credentials.yaml`
+ * and does not identify a process-local operator peer. DSH accepts that cookie
+ * for both `/api/*` and `/api/remote.mux`, so minting a fresh v1 cookie from
+ * the persisted secret survives a DSH restart without copying a new token.
+ */
+/** Credential record that owns the browser-cookie signing secret. */
+export declare const DSH_BROWSER_CREDENTIAL_KEY = "client-connection/browser-session";
+/** Short lifetime keeps every request safely inside DSH's configurable max age. */
+export declare const DSH_COOKIE_LIFETIME_MS: number;
+/**
+ * Resolve DSH's credentials file using the same `$DSH_HOME` convention.
+ * A configured home (agents.dsh.dshHome) wins over the environment so the
+ * file matches the `DSH_HOME` lark-remote passes to a process it starts.
+ */
+export declare function resolveDshCredentialsFile(env?: NodeJS.ProcessEnv, configuredHome?: string): string;
+/** Whether a filesystem error means the credentials file is absent. */
+export declare function isDshCredentialsNotFound(error: unknown): boolean;
+/** Read and validate the browser-cookie signing secret synchronously. */
+export declare function readDshBrowserSecretSync(file: string): Buffer;
+/** Read and validate the browser-cookie signing secret asynchronously. */
+export declare function readDshBrowserSecret(file: string): Promise<Buffer>;
+/** Cookie name binds the signed value to one host:port authority. */
+export declare function dshCookieName(authority: string): string;
+/**
+ * Mint a v1 browser cookie accepted by DSH's `/api` admission path.
+ *
+ * DSH verifies `v1.<base64url(payload)>.<base64url(hmac-sha256(body))>` with
+ * the durable browser-session secret. The short default lifetime is refreshed
+ * on the next request, so no cookie is persisted by lark-remote.
+ */
+export declare function mintDshBrowserCookie(baseUrl: string, secret: Buffer, issuedAt?: number, lifetimeMs?: number): string;

package/dist/runner/dsh/auth.js

@@ -0,0 +1,118 @@
+/**
+ * Persistent DSH browser authentication.
+ *
+ * `dsh web` rotates its process launch token on every restart. The signed
+ * browser cookie is different: it is verified with the durable
+ * `client-connection/browser-session` secret in `$DSH_HOME/.credentials.yaml`
+ * and does not identify a process-local operator peer. DSH accepts that cookie
+ * for both `/api/*` and `/api/remote.mux`, so minting a fresh v1 cookie from
+ * the persisted secret survives a DSH restart without copying a new token.
+ */
+import { createHash, createHmac } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import YAML from 'yaml';
+/** Credential record that owns the browser-cookie signing secret. */
+export const DSH_BROWSER_CREDENTIAL_KEY = 'client-connection/browser-session';
+/** Short lifetime keeps every request safely inside DSH's configurable max age. */
+export const DSH_COOKIE_LIFETIME_MS = 60 * 60 * 1000;
+const SECRET_BYTES = 32;
+const COOKIE_PREFIX = 'dsh-auth-';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Resolve DSH's credentials file using the same `$DSH_HOME` convention.
+ * A configured home (agents.dsh.dshHome) wins over the environment so the
+ * file matches the `DSH_HOME` lark-remote passes to a process it starts.
+ */
+export function resolveDshCredentialsFile(env = process.env, configuredHome) {
+    const home = configuredHome?.trim() || env.DSH_HOME?.trim();
+    return path.join(home && home.length > 0 ? home : path.join(os.homedir(), '.dsh'), '.credentials.yaml');
+}
+/** Whether a filesystem error means the credentials file is absent. */
+export function isDshCredentialsNotFound(error) {
+    return error?.code === 'ENOENT';
+}
+function assertOwnerOnly(file, stats) {
+    if (!stats.isFile()) {
+        throw new Error(`DSH credentials file ${file} is not a regular file`);
+    }
+    // Windows has no POSIX mode bits; DSH itself skips the same check there.
+    if (process.platform === 'win32')
+        return;
+    if ((stats.mode & 0o077) !== 0) {
+        throw new Error(`DSH credentials file ${file} is readable beyond its owner ` +
+            `(mode ${(stats.mode & 0o777).toString(8)}); run "chmod 600 ${file}"`);
+    }
+}
+function parseBrowserSecret(text, file) {
+    let document;
+    try {
+        document = YAML.parse(text);
+    }
+    catch {
+        // The parser's message quotes the offending source line, which is secret.
+        throw new Error(`DSH credentials file ${file} is not valid YAML`);
+    }
+    if (!isRecord(document) || document.version !== 1 || !isRecord(document.records)) {
+        throw new Error(`DSH credentials file ${file} has an unsupported format`);
+    }
+    const record = document.records[DSH_BROWSER_CREDENTIAL_KEY];
+    if (!isRecord(record) ||
+        record.kind !== 'grant' ||
+        !isRecord(record.payload) ||
+        record.payload.version !== 1 ||
+        typeof record.payload.secret !== 'string') {
+        throw new Error(`DSH credentials file ${file} does not contain ${DSH_BROWSER_CREDENTIAL_KEY}`);
+    }
+    const secret = Buffer.from(record.payload.secret, 'base64url');
+    if (secret.byteLength !== SECRET_BYTES ||
+        secret.toString('base64url') !== record.payload.secret) {
+        throw new Error(`DSH credentials file ${file} contains an invalid ${DSH_BROWSER_CREDENTIAL_KEY} secret`);
+    }
+    return secret;
+}
+/** Read and validate the browser-cookie signing secret synchronously. */
+export function readDshBrowserSecretSync(file) {
+    assertOwnerOnly(file, fs.statSync(file));
+    return parseBrowserSecret(fs.readFileSync(file, 'utf-8'), file);
+}
+/** Read and validate the browser-cookie signing secret asynchronously. */
+export async function readDshBrowserSecret(file) {
+    const stats = await fs.promises.stat(file);
+    assertOwnerOnly(file, stats);
+    const text = await fs.promises.readFile(file, 'utf-8');
+    return parseBrowserSecret(text, file);
+}
+/** Cookie name binds the signed value to one host:port authority. */
+export function dshCookieName(authority) {
+    return COOKIE_PREFIX + createHash('sha256').update(authority).digest('base64url');
+}
+/**
+ * Mint a v1 browser cookie accepted by DSH's `/api` admission path.
+ *
+ * DSH verifies `v1.<base64url(payload)>.<base64url(hmac-sha256(body))>` with
+ * the durable browser-session secret. The short default lifetime is refreshed
+ * on the next request, so no cookie is persisted by lark-remote.
+ */
+export function mintDshBrowserCookie(baseUrl, secret, issuedAt = Date.now(), lifetimeMs = DSH_COOKIE_LIFETIME_MS) {
+    if (secret.byteLength !== SECRET_BYTES) {
+        throw new Error('DSH browser-session secret must be 32 bytes');
+    }
+    if (!Number.isSafeInteger(issuedAt) || !Number.isSafeInteger(lifetimeMs) || lifetimeMs <= 0) {
+        throw new Error('DSH browser cookie lifetime must be a positive safe integer');
+    }
+    const authority = new URL(baseUrl).host;
+    if (!authority)
+        throw new Error(`DSH host ${baseUrl} has no authority`);
+    const expiresAt = issuedAt + lifetimeMs;
+    if (!Number.isSafeInteger(expiresAt)) {
+        throw new Error('DSH browser cookie expiry exceeds the safe integer range');
+    }
+    const body = Buffer.from(JSON.stringify({ version: 1, authority, issuedAt, expiresAt }), 'utf-8').toString('base64url');
+    const signature = createHmac('sha256', secret).update(body).digest('base64url');
+    return `${dshCookieName(authority)}=v1.${body}.${signature}`;
+}
+//# sourceMappingURL=auth.js.map

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

@@ -1,45 +1,126 @@
 /**
- * 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 type { DshModelCatalogValue, DshModelSelection, DshPresetListValue, DshServerRequest, DshStreamItem, DshTokenUsage } from './types.js';
+import type { DshApprovalStreamItem, DshModelCatalogValue, DshModelSelection, DshPermissionCatalogValue, DshPresetListValue, DshRemoteEventOutcome, DshSessionPageValue, DshStreamItem, DshTokenUsage, DshCommandResult } from './types.js';
 interface WebSocketMessageEvent {
     data: unknown;
 }
-interface WebSocketLike {
+export interface WebSocketOptions {
+    headers?: Record<string, string>;
+}
+export interface WebSocketLike {
+    onopen: ((event: unknown) => void) | null;
     onmessage: ((event: WebSocketMessageEvent) => void) | null;
     onerror: ((event: unknown) => void) | null;
     onclose: ((event: unknown) => void) | null;
+    /** Set by transports that expose an HTTP rejection before the handshake. */
+    onunexpectedresponse?: ((event: {
+        statusCode?: number;
+    }) => void) | null;
+    send(data: string): void;
     close(): void;
 }
-export type WebSocketFactory = (url: string) => WebSocketLike;
+export type WebSocketFactory = (url: string, options?: WebSocketOptions) => 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 interface DshClientOptions {
+    /** Configured DSH home; selects `.credentials.yaml` when no explicit file is given. */
+    dshHome?: string;
+    /**
+     * Optional DSH Web launch token. Accepts either the bare token or the full
+     * URL printed by `dsh web` (the `token` query parameter is extracted).
+     */
+    token?: string;
+    /**
+     * DSH credentials file containing the durable browser-session signing
+     * secret. Defaults to `$DSH_HOME/.credentials.yaml` or
+     * `~/.dsh/.credentials.yaml`. When readable, this is preferred over the
+     * per-process launch token and survives `dsh web` restarts.
+     */
+    credentialsFile?: string;
+    /** Injectable credentials reader (tests). */
+    readCredentials?: (file: string) => Promise<Buffer>;
+    /** Injectable clock (tests). */
+    now?: () => number;
+    /** Lifetime of minted browser cookies. */
+    cookieLifetimeMs?: number;
+    fetchImpl?: typeof fetch;
+    webSocketImpl?: WebSocketFactory;
+    /**
+     * Unary request timeout. DSH accepts the HTTP connection but may never answer
+     * (e.g. a stuck `session/prompt`); without a timeout the run generator stays
+     * parked in `await unary()` forever, so /stop and the idle watchdog cannot
+     * release the bridge's workspace queue.
+     */
+    requestTimeoutMs?: number;
+}
+/** Extract the `token` query parameter from a pasted `dsh web` URL. */
+export declare function extractDshToken(raw: string | undefined): string;
+export declare function dshArgs(method: string, payload: unknown): Record<string, unknown>;
 export declare class DshClient {
     readonly baseUrl: string;
+    private readonly token;
+    private readonly credentialsFile;
+    private readonly readCredentials;
+    private readonly now;
+    private readonly cookieLifetimeMs;
     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>;
+    private readonly requestTimeoutMs;
+    private cookiePromise?;
+    constructor(baseUrl: string, options?: DshClientOptions);
+    /**
+     * 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.
+     */
+    private authCookie;
+    /** Mint a v1 browser cookie from DSH's durable signing secret. */
+    private cookieFromCredentials;
+    /**
+     * 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.
+     */
+    unary(method: string, payload: unknown, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    /** Distinguish "run stopped" (abort) from "server did not answer" (timeout). */
+    private abortError;
     /** Create a session. Pass `agentPreset` to pin the session's preset (fixed at
      *  creation). */
     createSession(payload: {
         cwd: string;
         agentPreset?: string;
+    }, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
     }): Promise<{
         sessionId: string;
         agentPreset?: string;
@@ -48,46 +129,84 @@ export declare class DshClient {
      *  server-side). Failures are surfaced as DshError for the caller to downgrade. */
     selectModel(payload: DshModelSelection & {
         sessionId: string;
+    }, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
     }): Promise<DshModelSelection>;
-    /** Read the model catalog (session-independent, llm.models). */
-    listModels(): Promise<DshModelCatalogValue>;
-    /** Read the preset catalog (agentPreset.list). */
-    listPresets(): Promise<DshPresetListValue>;
+    /** Read the model catalog (session/modelCatalog). */
+    listModels(opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<DshModelCatalogValue>;
     /**
-     * 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.
      */
-    latestEventSeq(sessionId: string): Promise<number>;
+    executeCommand(sessionId: string, line: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<DshCommandResult | undefined>;
+    /** Read the preset catalog (agentPresets/list). */
+    listPresets(): Promise<DshPresetListValue>;
+    /** Read the permission preset catalog (permissionPresets/catalog). */
+    listPermissionPresets(): Promise<DshPermissionCatalogValue>;
+    /** Answer one forwarded approval waterfall ($events/result). */
+    answerRemoteEvent(clientId: string, eventId: string, outcome: DshRemoteEventOutcome, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<void>;
     /**
-     * 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.
      */
-    mux(signal: AbortSignal): AsyncGenerator<DshServerRequest>;
+    latestEventSeq(sessionId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<number>;
+    /** Read one cold history page. `throughSeq` normally comes from
+     *  `latestEventSeq()`; `session/page` needs an inclusive cursor. */
+    page(sessionId: string, throughSeq: number, maxMessages: number, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<DshSessionPageValue>;
     /**
-     * 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.
      */
-    muxWebSocket(signal: AbortSignal): AsyncGenerator<DshServerRequest>;
+    private muxStream;
+    /** One logical `session/follow` stream. */
+    private followStream;
     /**
-     * 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.
      */
-    private replayHistory;
+    approvalEvents(sessionId: string, signal: AbortSignal): AsyncGenerator<DshApprovalStreamItem>;
+    /** Translate one durable event into a stream item (approvals are surfaced
+     *  separately; everything else is forwarded to the runner). */
+    private eventItem;
     /**
-     * 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.
      */
     sessionEvents(sessionId: 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;
 }
+/** Stable client-side prompt identity persisted on the accepted user message. */
+export declare function newPromptRequestId(): string;
 export {};