lark-remote 0.5.5 → 0.5.7

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

@@ -10,16 +10,16 @@
  *  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 Gateway-owned `$events` stream carries answerable waterfalls:
+ *     `approval/request` (tool permissions) and `user-questions/request`
+ *     (`ask_user_question`); answers go back through `$events/result`.
  *
  * 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 { DshApprovalStreamItem, DshModelCatalogValue, DshModelSelection, DshPermissionCatalogValue, DshPresetListValue, DshRemoteEventOutcome, DshSessionPageValue, DshStreamItem, DshTokenUsage, DshCommandResult } from './types.js';
+import type { DshApprovalStreamItem, DshCommandResult, DshModelCatalogValue, DshModelSelection, DshOpenTurnState, DshPermissionCatalogValue, DshJobView, DshPresetListValue, DshProjectionItem, DshProjectionSnapshot, DshQuestion, DshRemoteEventOutcome, DshSessionPageValue, DshStreamItem, DshTokenUsage } from './types.js';
 interface WebSocketMessageEvent {
     data: unknown;
 }
@@ -163,6 +163,8 @@ export declare class DshClient {
         signal?: AbortSignal;
         timeoutMs?: number;
     }): Promise<void>;
+    /** Hand one waterfall delivery back with `next` (another answerer owns it). */
+    private delegateWaterfall;
     /**
      * Return the highest event `seq` currently persisted for the session.
      *
@@ -180,6 +182,68 @@ export declare class DshClient {
         signal?: AbortSignal;
         timeoutMs?: number;
     }): Promise<DshSessionPageValue>;
+    /**
+     * Read the session's exact projection values.
+     *
+     * Returns `null` when the host has no projections for the session (e.g. it was
+     * deleted). A failed unary still throws — callers that only need a
+     * best-effort probe catch it themselves.
+     */
+    projectionSnapshot(sessionId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<DshProjectionSnapshot | null>;
+    /**
+     * Find this run's prompt if it is still sitting in the host's inbox.
+     *
+     * DSH 的 prompt 受理后先进入 inbox，被 turn 取走（claim）就不再出现；停止
+     * 时用它区分“还没开始 → 可以从队列里撤掉”和“已经在跑 → 只能 cancel”。
+     * `source.rpcId` 是 `session/prompt` 的 requestId，归属不会认错。
+     */
+    findPendingPrompt(sessionId: string, requestId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<string | undefined>;
+    /**
+     * Remove one not-yet-claimed inbox occurrence (`session/updateQueue`).
+     *
+     * @returns true when the host removed it; false when it was claimed between
+     *   the projection read and this call (`session/queue-item-not-found`).
+     */
+    removeQueuedPrompt(sessionId: string, itemId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /**
+     * Whether the session still has a running turn.
+     *
+     * 主信号是 `session/list` 的 `running` 字段：服务端权威（会话列表页"运行中"
+     * 用的就是它），一次 unary，投票不受桥接进程内存影响。名单里没有该会话或
+     * 服务端不返回 `running` 时，回退到事件探测（{@link probeOpenTurnByEvents}），
+     * 两者都判不出来就返回 false（fail open，仍由 DSH 自己拒绝）。
+     */
+    hasOpenTurn(sessionId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /**
+     * Tri-state version of {@link hasOpenTurn}.
+     *
+     * Stop verification must distinguish "the host says idle" from "the probe
+     * could not tell" — reporting `closed` on a failed probe would let a still
+     * running turn be reported as stopped. `unknown` is the honest answer there.
+     */
+    openTurnState(sessionId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<DshOpenTurnState>;
+    /**
+     * Fallback probe: the newest durable event's type tells whether a turn is open.
+     *
+     * 只在拿不到 `running` 时用。名单刻意保守——`job/*`（后台任务可在 turn 外
+     * 结算）、`user/message`、`turn/end` 都不算，判不出来就报告 `unknown`。
+     */
+    private probeOpenTurnByEvents;
     /**
      * 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
@@ -201,12 +265,66 @@ export declare class DshClient {
      * 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.
+     * the run's own turn/end or `signal` abort.
+     *
+     * `promptRequestId` binds the stream to this run's prompt. `mode:'queue'`
+     * prompts are accepted while the agent is mid-turn and start a turn only
+     * later, so the first `turn/end` after `initialSeq` can belong to that OTHER
+     * turn. Everything recorded before the prompt's own durable `user/message`
+     * (whose source echoes the request id as `rpcId`) is foreign: dropping it
+     * keeps the card "running" until this run's turn actually finishes.
      */
-    sessionEvents(sessionId: string, signal: AbortSignal, initialSeq?: number): AsyncGenerator<DshStreamItem>;
+    sessionEvents(sessionId: string, signal: AbortSignal, initialSeq?: number, promptRequestId?: string): AsyncGenerator<DshStreamItem>;
+    /**
+     * Host-wide live projection stream (`session/control`).
+     *
+     * 一份 baseline（当前所有活跃 session 的完整投影值）+ 之后每个投影的变化帧。
+     * 调用方按 sessionId 过滤：这是 DSH 上唯一"服务端变一次推一次"的通道，
+     * 不需要轮询 `session/projections`。
+     *
+     * 失败必须降级为"没有状态条"，不能影响 run：控制流是增强通道，断了运行
+     * 照常（异常在此吞掉并记日志，不向 merge 抛）。
+     */
+    controlFrames(signal: AbortSignal): AsyncGenerator<DshProjectionItem>;
+    /**
+     * One session's current background-job roster.
+     *
+     * `job/list` 是流（生命周期变化时推整份名单），但"此刻有哪些任务在跑"只需
+     * 要第一帧：文档明确首帧就是当前真相（whole-set replacement）。取到即断开，
+     * 不长期持有连接——任务列表只用于收尾时的一句话与停止按钮。
+     *
+     * 失败返回 undefined（与"没有任务"区分）：拿不到就别在卡片上写"0 个后台任务"。
+     */
+    jobRows(sessionId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<DshJobView[] | undefined>;
+    /** Kill one background job on the user's behalf (`job/kill`). */
+    jobKill(sessionId: string, jobId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
     /** 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;
+/**
+ * Read the questions of one `user-questions/request` waterfall.
+ *
+ * Returns undefined when the batch cannot be answered through the Feishu card:
+ * malformed fields, or duplicate question texts — the approval coordinator
+ * keys answers by question text, so duplicates would answer the wrong one.
+ * The caller delegates such a batch back to the DSH Web UI.
+ */
+export declare function dshQuestionsOf(request: Record<string, unknown>): DshQuestion[] | undefined;
+/**
+ * True for a timed (`askTimed`) request — `wait.timed` in the projected payload.
+ *
+ * Timed asks settle at their own foreground deadline and then close the
+ * waterfall, so an answer sent outside that window can never land. Such a
+ * request belongs to the client that claims the wait (`attachWait`) and renders
+ * its countdown, i.e. the DSH Web UI; the card must not offer answers that expire
+ * silently on the server side.
+ */
+export declare function isTimedQuestionRequest(request: Record<string, unknown>): boolean;
 export {};

package/dist/runner/dsh/client.js

@@ -10,9 +10,9 @@
  *  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 Gateway-owned `$events` stream carries answerable waterfalls:
+ *     `approval/request` (tool permissions) and `user-questions/request`
+ *     (`ask_user_question`); answers go back through `$events/result`.
  *
  * 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.
@@ -52,6 +52,59 @@ function isDshAuthError(error) {
 const RECONNECT_BACKOFF_MS = 200;
 /** Follow snapshot budget. `session/follow` also stays live after the snapshot. */
 const FOLLOW_MAX_MESSAGES = 200;
+/**
+ * 只在 turn 内部落盘的会话事件类型：看到它们说明 turn 还没结束。
+ * 名单刻意保守——`user/message`（压缩 checkpoint 会以 turn:null 落盘）、
+ * `job/*`（后台任务可在 turn 外结算）、`turn/end`、`command/*` 等都不算，
+ * 判不出来时宁可放行，让 DSH 自己拒绝。
+ */
+const IN_TURN_EVENT_TYPES = new Set([
+    'step/start',
+    'step/end',
+    'assistant/chunk',
+    'assistant/message',
+    'assistant/attempt',
+    'tool/call',
+    'tool/result',
+    'request/header',
+]);
+/**
+ * Parse the `inbox` projection into the pending items this repo consumes.
+ *
+ * The projection's items are wire data (typed `{}` by the server schema); keep
+ * this defensive: one malformed row must not hide the others.
+ */
+function inboxItemsOf(values) {
+    const inbox = values.inbox;
+    if (!inbox || typeof inbox !== 'object' || Array.isArray(inbox))
+        return [];
+    const out = [];
+    for (const target of ['next-turn', 'next-step']) {
+        const list = inbox[target];
+        if (!Array.isArray(list))
+            continue;
+        for (const raw of list) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                continue;
+            const item = raw;
+            if (typeof item.id !== 'string' || item.id.length === 0)
+                continue;
+            const source = item.source;
+            const parsedSource = source && typeof source === 'object' && !Array.isArray(source)
+                ? {
+                    ...(typeof source.kind === 'string'
+                        ? { kind: source.kind }
+                        : {}),
+                    ...(typeof source.rpcId === 'string'
+                        ? { rpcId: source.rpcId }
+                        : {}),
+                }
+                : undefined;
+            out.push({ id: item.id, ...(parsedSource ? { source: parsedSource } : {}) });
+        }
+    }
+    return out;
+}
 /** 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. */
@@ -85,6 +138,9 @@ const DSH_ARGS_KEY = {
     'session/projections': 'request',
     'session/page': 'request',
     'session/follow': 'request',
+    'session/updateQueue': 'request',
+    'job/list': 'request',
+    'job/kill': 'request',
     'session/modelCatalog': null,
     'agentPresets/list': null,
     'permissionPresets/catalog': null,
@@ -348,6 +404,14 @@ export class DshClient {
     async answerRemoteEvent(clientId, eventId, outcome, opts) {
         await this.unary('$events/result', { clientId, eventId, outcome }, opts);
     }
+    /** Hand one waterfall delivery back with `next` (another answerer owns it). */
+    delegateWaterfall(clientId, eventId, signal) {
+        void this.answerRemoteEvent(clientId, eventId, { kind: 'next' }, { signal }).catch((err) => {
+            if (!signal.aborted) {
+                getLogger().warn(`[dsh] waterfall delegation failed eventId=${eventId}: ${err.message}`);
+            }
+        });
+    }
     /**
      * Return the highest event `seq` currently persisted for the session.
      *
@@ -356,7 +420,7 @@ export class DshClient {
      * `session/prompt` so a follow snapshot can skip already-completed turns.
      */
     async latestEventSeq(sessionId, opts) {
-        const value = (await this.unary('session/projections', { sessionId }, opts));
+        const value = await this.projectionSnapshot(sessionId, opts);
         return typeof value?.asOfSeq === 'number' ? value.asOfSeq : -1;
     }
     /** Read one cold history page. `throughSeq` normally comes from
@@ -368,6 +432,110 @@ export class DshClient {
             maxMessages,
         }, opts));
     }
+    /**
+     * Read the session's exact projection values.
+     *
+     * Returns `null` when the host has no projections for the session (e.g. it was
+     * deleted). A failed unary still throws — callers that only need a
+     * best-effort probe catch it themselves.
+     */
+    async projectionSnapshot(sessionId, opts) {
+        const value = (await this.unary('session/projections', { sessionId }, opts));
+        if (!value || typeof value !== 'object')
+            return null;
+        return {
+            ...(typeof value.asOfSeq === 'number' ? { asOfSeq: value.asOfSeq } : {}),
+            values: value.values && typeof value.values === 'object' && !Array.isArray(value.values)
+                ? value.values
+                : {},
+        };
+    }
+    /**
+     * Find this run's prompt if it is still sitting in the host's inbox.
+     *
+     * DSH 的 prompt 受理后先进入 inbox，被 turn 取走（claim）就不再出现；停止
+     * 时用它区分“还没开始 → 可以从队列里撤掉”和“已经在跑 → 只能 cancel”。
+     * `source.rpcId` 是 `session/prompt` 的 requestId，归属不会认错。
+     */
+    async findPendingPrompt(sessionId, requestId, opts) {
+        const snapshot = await this.projectionSnapshot(sessionId, opts);
+        if (!snapshot)
+            return undefined;
+        return inboxItemsOf(snapshot.values).find((item) => item.source?.kind === 'user' && item.source.rpcId === requestId)?.id;
+    }
+    /**
+     * Remove one not-yet-claimed inbox occurrence (`session/updateQueue`).
+     *
+     * @returns true when the host removed it; false when it was claimed between
+     *   the projection read and this call (`session/queue-item-not-found`).
+     */
+    async removeQueuedPrompt(sessionId, itemId, opts) {
+        try {
+            await this.unary('session/updateQueue', { sessionId, itemId, action: { kind: 'remove' } }, opts);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof DshError && err.code === 'session/queue-item-not-found')
+                return false;
+            throw err;
+        }
+    }
+    /**
+     * Whether the session still has a running turn.
+     *
+     * 主信号是 `session/list` 的 `running` 字段：服务端权威（会话列表页"运行中"
+     * 用的就是它），一次 unary，投票不受桥接进程内存影响。名单里没有该会话或
+     * 服务端不返回 `running` 时，回退到事件探测（{@link probeOpenTurnByEvents}），
+     * 两者都判不出来就返回 false（fail open，仍由 DSH 自己拒绝）。
+     */
+    async hasOpenTurn(sessionId, opts) {
+        return (await this.openTurnState(sessionId, opts)) === 'open';
+    }
+    /**
+     * Tri-state version of {@link hasOpenTurn}.
+     *
+     * Stop verification must distinguish "the host says idle" from "the probe
+     * could not tell" — reporting `closed` on a failed probe would let a still
+     * running turn be reported as stopped. `unknown` is the honest answer there.
+     */
+    async openTurnState(sessionId, opts) {
+        try {
+            const list = (await this.unary('session/list', {}, opts));
+            const row = list?.items?.find((item) => String(item.sessionId) === sessionId);
+            if (row && typeof row.running === 'boolean')
+                return row.running ? 'open' : 'closed';
+        }
+        catch (err) {
+            getLogger().warn(`[dsh] open-turn probe: session/list failed for ${sessionId}: ${err.message}`);
+        }
+        return this.probeOpenTurnByEvents(sessionId, opts);
+    }
+    /**
+     * Fallback probe: the newest durable event's type tells whether a turn is open.
+     *
+     * 只在拿不到 `running` 时用。名单刻意保守——`job/*`（后台任务可在 turn 外
+     * 结算）、`user/message`、`turn/end` 都不算，判不出来就报告 `unknown`。
+     */
+    async probeOpenTurnByEvents(sessionId, opts) {
+        try {
+            // A missing projection snapshot is not "idle": the host simply cannot
+            // tell us. Only a known watermark with no events (or a closed tail) is
+            // evidence that no turn is open.
+            const snapshot = await this.projectionSnapshot(sessionId, opts);
+            if (!snapshot || typeof snapshot.asOfSeq !== 'number' || snapshot.asOfSeq < 0) {
+                return 'unknown';
+            }
+            const value = await this.page(sessionId, snapshot.asOfSeq, 1, opts);
+            const last = value.records.at(-1)?.event;
+            if (last === undefined)
+                return 'closed';
+            return last.type === 'turn/start' || IN_TURN_EVENT_TYPES.has(last.type) ? 'open' : 'closed';
+        }
+        catch (err) {
+            getLogger().warn(`[dsh] open-turn probe failed for session ${sessionId}: ${err.message}`);
+            return 'unknown';
+        }
+    }
     /**
      * 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
@@ -553,14 +721,36 @@ export class DshClient {
                             };
                             return;
                         }
+                        if (frame.event === 'user-questions/request' && frame.agentId === sessionId) {
+                            if (isTimedQuestionRequest(frame.request)) {
+                                // The timed wait owns its own deadline (and the Web UI renders
+                                // the countdown); a card answer outside that window is lost.
+                                getLogger().info(`[dsh] timed user-questions/request delegated to the Web UI eventId=${frame.eventId}`);
+                                this.delegateWaterfall(streamClientId, frame.eventId, signal);
+                                continue;
+                            }
+                            const questions = dshQuestionsOf(frame.request);
+                            if (questions) {
+                                yield {
+                                    kind: 'question',
+                                    eventId: frame.eventId,
+                                    clientId: streamClientId,
+                                    questions,
+                                };
+                            }
+                            else {
+                                // The Feishu card cannot answer this batch safely (malformed,
+                                // or duplicate texts — the coordinator keys answers by text).
+                                // Hand the one-shot answer back so the DSH Web UI stays in charge.
+                                getLogger().warn(`[dsh] user-questions/request not relayable; delegating eventId=${frame.eventId}`);
+                                this.delegateWaterfall(streamClientId, frame.eventId, signal);
+                            }
+                            continue;
+                        }
                         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}`);
-                                }
-                            });
+                            this.delegateWaterfall(streamClientId, frame.eventId, signal);
                             continue;
                         }
                         const data = frame.request;
@@ -645,10 +835,41 @@ export class DshClient {
      * 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.
+     * the run's own turn/end or `signal` abort.
+     *
+     * `promptRequestId` binds the stream to this run's prompt. `mode:'queue'`
+     * prompts are accepted while the agent is mid-turn and start a turn only
+     * later, so the first `turn/end` after `initialSeq` can belong to that OTHER
+     * turn. Everything recorded before the prompt's own durable `user/message`
+     * (whose source echoes the request id as `rpcId`) is foreign: dropping it
+     * keeps the card "running" until this run's turn actually finishes.
      */
-    async *sessionEvents(sessionId, signal, initialSeq = -1) {
-        const state = { lastSeq: initialSeq };
+    async *sessionEvents(sessionId, signal, initialSeq = -1, promptRequestId) {
+        const state = { lastSeq: initialSeq, owns: promptRequestId === undefined };
+        let foreignTailReported = false;
+        /** Mark this run as the owner once its own prompt message is recorded. */
+        const ownsEvent = (ev) => {
+            if (state.owns)
+                return true;
+            if (ev.type !== 'user/message')
+                return false;
+            const source = ev.data
+                ?.source;
+            if (source?.kind === 'user' && source.rpcId === promptRequestId) {
+                state.owns = true;
+                return true;
+            }
+            return false;
+        };
+        const admit = (ev) => {
+            if (ownsEvent(ev))
+                return true;
+            if (!foreignTailReported) {
+                foreignTailReported = true;
+                getLogger().info(`[dsh] prompt ${promptRequestId ?? '(none)'} is queued behind a running turn for session ${sessionId}; holding the card open until its own turn starts`);
+            }
+            return false;
+        };
         let authRefreshAttempted = false;
         while (!signal.aborted) {
             try {
@@ -662,6 +883,8 @@ export class DshClient {
                             if (!ev || ev.seq <= state.lastSeq)
                                 continue;
                             state.lastSeq = ev.seq;
+                            if (!admit(ev))
+                                continue;
                             const item = this.eventItem(sessionId, ev);
                             if (item)
                                 yield item;
@@ -675,6 +898,8 @@ export class DshClient {
                         if (ev.seq <= state.lastSeq)
                             continue;
                         state.lastSeq = ev.seq;
+                        if (!admit(ev))
+                            continue;
                         const item = this.eventItem(sessionId, ev);
                         if (item)
                             yield item;
@@ -683,6 +908,9 @@ export class DshClient {
                         continue;
                     }
                     if (frame.type === 'assistant-stream') {
+                        // Mid-turn deltas of the turn this prompt is queued behind.
+                        if (!state.owns)
+                            continue;
                         yield { kind: 'assistant-stream', sessionId, frame: frame.frame };
                     }
                 }
@@ -709,6 +937,93 @@ export class DshClient {
             await new Promise((resolve) => setTimeout(resolve, RECONNECT_BACKOFF_MS));
         }
     }
+    /**
+     * Host-wide live projection stream (`session/control`).
+     *
+     * 一份 baseline（当前所有活跃 session 的完整投影值）+ 之后每个投影的变化帧。
+     * 调用方按 sessionId 过滤：这是 DSH 上唯一"服务端变一次推一次"的通道，
+     * 不需要轮询 `session/projections`。
+     *
+     * 失败必须降级为"没有状态条"，不能影响 run：控制流是增强通道，断了运行
+     * 照常（异常在此吞掉并记日志，不向 merge 抛）。
+     */
+    async *controlFrames(signal) {
+        try {
+            // mux 的 payload 与 unary 同信封：`{args:{...}}`。control 无参数，故空 args；
+            // 少了这层包装网关直接拒绝（live 实测 0 帧，测试用假服务端不会发现）。
+            for await (const raw of this.muxStream('session/control', { args: {} }, signal)) {
+                const frame = raw;
+                if (!frame || typeof frame !== 'object')
+                    continue;
+                if (frame.type === 'baseline') {
+                    const projections = frame.value?.projections ??
+                        {};
+                    for (const [sessionId, snapshot] of Object.entries(projections)) {
+                        const values = snapshot?.values ?? {};
+                        for (const [key, value] of Object.entries(values)) {
+                            yield { kind: 'projection', sessionId, key, value };
+                        }
+                    }
+                    continue;
+                }
+                if (frame.type === 'projection' && frame.sessionId && frame.key) {
+                    yield {
+                        kind: 'projection',
+                        sessionId: frame.sessionId,
+                        key: frame.key,
+                        value: frame.value,
+                    };
+                }
+            }
+        }
+        catch (err) {
+            if (signal.aborted)
+                return;
+            getLogger().warn(`[dsh] session/control stream unavailable (${err.message}); run continues without live status`);
+        }
+    }
+    /**
+     * One session's current background-job roster.
+     *
+     * `job/list` 是流（生命周期变化时推整份名单），但"此刻有哪些任务在跑"只需
+     * 要第一帧：文档明确首帧就是当前真相（whole-set replacement）。取到即断开，
+     * 不长期持有连接——任务列表只用于收尾时的一句话与停止按钮。
+     *
+     * 失败返回 undefined（与"没有任务"区分）：拿不到就别在卡片上写"0 个后台任务"。
+     */
+    async jobRows(sessionId, opts = {}) {
+        const timer = new AbortController();
+        const timeout = setTimeout(() => timer.abort(), opts.timeoutMs ?? 2_000);
+        const signal = opts.signal ? AbortSignal.any([opts.signal, timer.signal]) : timer.signal;
+        try {
+            for await (const frame of this.muxStream('job/list', { args: dshArgs('job/list', { sessionId }) }, signal)) {
+                const rows = frame;
+                if (rows?.type === 'rows') {
+                    return Array.isArray(rows.jobs) ? rows.jobs : [];
+                }
+            }
+            return undefined;
+        }
+        catch (err) {
+            getLogger().debug(`[dsh] job/list unavailable: ${err.message}`);
+            return undefined;
+        }
+        finally {
+            clearTimeout(timeout);
+            timer.abort();
+        }
+    }
+    /** Kill one background job on the user's behalf (`job/kill`). */
+    async jobKill(sessionId, jobId, opts = {}) {
+        try {
+            await this.unary('job/kill', { sessionId, jobId }, opts);
+            return true;
+        }
+        catch (err) {
+            getLogger().warn(`[dsh] job/kill failed job=${jobId}: ${err.message}`);
+            return false;
+        }
+    }
     /** Extract TokenUsage from an assistant/message data payload (absent → undefined). */
     static usageOf(data) {
         return data.usage ?? undefined;
@@ -718,4 +1033,75 @@ export class DshClient {
 export function newPromptRequestId() {
     return `lark-remote-${randomUUID()}`;
 }
+/**
+ * Read the questions of one `user-questions/request` waterfall.
+ *
+ * Returns undefined when the batch cannot be answered through the Feishu card:
+ * malformed fields, or duplicate question texts — the approval coordinator
+ * keys answers by question text, so duplicates would answer the wrong one.
+ * The caller delegates such a batch back to the DSH Web UI.
+ */
+export function dshQuestionsOf(request) {
+    const raw = request.questions;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const questions = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item))
+            return undefined;
+        const record = item;
+        const id = typeof record.id === 'string' ? record.id : '';
+        const text = typeof record.question === 'string' ? record.question : '';
+        if (!id || !text)
+            return undefined;
+        if (seen.has(text))
+            return undefined;
+        seen.add(text);
+        const options = [];
+        if (record.options !== undefined) {
+            if (!Array.isArray(record.options))
+                return undefined;
+            for (const rawOption of record.options) {
+                if (rawOption === null || typeof rawOption !== 'object' || Array.isArray(rawOption)) {
+                    return undefined;
+                }
+                const option = rawOption;
+                const label = typeof option.label === 'string' ? option.label : '';
+                if (!label)
+                    return undefined;
+                options.push({
+                    label,
+                    ...(typeof option.description === 'string' && option.description
+                        ? { description: option.description }
+                        : {}),
+                });
+            }
+        }
+        questions.push({
+            id,
+            question: text,
+            ...(typeof record.detail === 'string' && record.detail ? { detail: record.detail } : {}),
+            ...(typeof record.header === 'string' && record.header ? { header: record.header } : {}),
+            ...(options.length > 0 ? { options } : {}),
+            ...(record.multiSelect === true ? { multiSelect: true } : {}),
+        });
+    }
+    return questions;
+}
+/**
+ * True for a timed (`askTimed`) request — `wait.timed` in the projected payload.
+ *
+ * Timed asks settle at their own foreground deadline and then close the
+ * waterfall, so an answer sent outside that window can never land. Such a
+ * request belongs to the client that claims the wait (`attachWait`) and renders
+ * its countdown, i.e. the DSH Web UI; the card must not offer answers that expire
+ * silently on the server side.
+ */
+export function isTimedQuestionRequest(request) {
+    const wait = request.wait;
+    if (wait === null || typeof wait !== 'object' || Array.isArray(wait))
+        return false;
+    return wait.timed === true;
+}
 //# sourceMappingURL=client.js.map