lark-remote 0.5.20 → 0.5.21

package/dist/runner/dsh/client.js

@@ -44,6 +44,49 @@ function isDshAuthError(error) {
         error.code === 'http' &&
         (error.details.status === 401 || error.details.status === 403));
 }
+/** 组合 abort/timeout signal 并生成本次 unary 的 rpcId（循环外一次算好）。 */
+function prepareUnary(opts, requestTimeoutMs) {
+    const timeoutMs = opts.timeoutMs ?? 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)}`;
+    return { signal, timeoutSignal, timeoutMs, rpcId };
+}
+/** Distinguish "run stopped" (abort) from "server did not answer" (timeout). */
+function abortErrorOf(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 new DshError('aborted', `DSH unary ${method} aborted: ${err.message}`);
+}
+/** 校验 ok 响应并取 `result.value`；非 ok / 非 JSON / result 失败都抛 DshError。 */
+async function readUnaryBody(method, res) {
+    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;
+}
 /** Backoff between mux reconnects to avoid a hot loop on a dropping server. */
 const RECONNECT_BACKOFF_MS = 200;
 /**
@@ -112,6 +155,192 @@ function inboxItemsOf(values) {
     }
     return out;
 }
+/** Hand one waterfall delivery back with `next` (another answerer owns it). */
+function delegateWaterfall(client, clientId, eventId, signal) {
+    void client
+        .answerRemoteEvent(clientId, eventId, { kind: 'next' }, { signal })
+        .catch((err) => {
+        if (!signal.aborted) {
+            getLogger().warn(`[dsh] waterfall delegation failed eventId=${eventId}: ${err.message}`);
+        }
+    });
+}
+/** 一个 waterfall 帧 → 要 yield 的 items（含 question/request 委托）。 */
+function waterfallToItems(client, clientId, frame, sessionId, signal) {
+    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}`);
+            delegateWaterfall(client, clientId, frame.eventId, signal);
+            return { items: [], stop: false };
+        }
+        const questions = dshQuestionsOf(frame.request);
+        if (questions) {
+            return {
+                items: [{ kind: 'question', eventId: frame.eventId, clientId, questions }],
+                stop: false,
+            };
+        }
+        // The Feishu card cannot answer this batch safely (malformed, or duplicate
+        // texts — the coordinator keys answers by text).
+        getLogger().warn(`[dsh] user-questions/request not relayable; delegating eventId=${frame.eventId}`);
+        delegateWaterfall(client, clientId, frame.eventId, signal);
+        return { items: [], stop: false };
+    }
+    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.
+        delegateWaterfall(client, clientId, frame.eventId, signal);
+        return { items: [], stop: false };
+    }
+    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;
+    return {
+        items: [
+            {
+                kind: 'request',
+                eventId: frame.eventId,
+                clientId,
+                toolName,
+                ...(callId ? { callId } : {}),
+                ...(reason ? { reason } : {}),
+            },
+        ],
+        stop: false,
+    };
+}
+/** 一个 `$events` 帧 → items（并按需更新 state）。 */
+function processApprovalFrame(state, frame, sessionId, signal, client) {
+    if (frame.type === 'ready') {
+        state.authRefreshAttempted = false;
+        // 成功建连后补充重连预算：goal 驱动的 turn 可跑数小时，DSH 重启 + 网络抖动
+        // 累计掉线超过 3 次后旧实现会让 $events 永久 unavailable。
+        state.reconnectAttempts = 0;
+        state.sawReady = true;
+        state.streamClientId = frame.clientId;
+        return { items: [{ kind: 'ready', clientId: frame.clientId }], stop: false };
+    }
+    if (frame.type === 'waterfall') {
+        if (!state.streamClientId) {
+            return {
+                items: [
+                    { kind: 'unavailable', message: 'DSH approval stream sent a waterfall before ready' },
+                ],
+                stop: true,
+            };
+        }
+        return waterfallToItems(client, state.streamClientId, frame, sessionId, signal);
+    }
+    if (frame.type === 'cancel') {
+        return { items: [{ kind: 'cancelled', eventId: frame.eventId }], stop: false };
+    }
+    return { items: [], stop: false };
+}
+/** 把 `$events` 流异常分类成 4 种动作（不改变重试/超时语义）。 */
+function classifyApprovalStreamError(err, state, signal) {
+    if (signal.aborted)
+        return { kind: 'return' };
+    if (err instanceof DshError &&
+        err.code === 'http' &&
+        err.details.status === 401 &&
+        !state.authRefreshAttempted) {
+        return { kind: 'refresh-auth' };
+    }
+    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 && state.reconnectAttempts < 3) {
+        return { kind: 'reconnect', attempt: state.reconnectAttempts + 1 };
+    }
+    return { kind: 'unavailable', message };
+}
+/** 一次流正常结束（无异常）后的收尾决策。 */
+function approvalStreamTail(state, signal) {
+    if (signal.aborted)
+        return 'aborted';
+    if (state.sawReady && state.reconnectAttempts < 3) {
+        state.reconnectAttempts += 1;
+        return 'reconnect';
+    }
+    return 'ended';
+}
+function reconnectBackoff() {
+    return new Promise((resolve) => setTimeout(resolve, 200));
+}
+/** Mark this run as the owner once its own prompt message is recorded. */
+function ownsSessionEvent(state, ev) {
+    if (state.owns)
+        return true;
+    if (ev.type !== 'user/message')
+        return false;
+    const source = ev.data?.source;
+    if (source?.kind === 'user' && source.rpcId === state.promptRequestId) {
+        state.owns = true;
+        return true;
+    }
+    return false;
+}
+function admitSessionEvent(state, ev) {
+    if (ownsSessionEvent(state, ev))
+        return true;
+    if (!state.foreignTailReported) {
+        state.foreignTailReported = true;
+        getLogger().info(`[dsh] prompt ${state.promptRequestId ?? '(none)'} is queued behind a running turn for session ${state.sessionId}; holding the card open until its own turn starts`);
+    }
+    return false;
+}
+/** Translate one durable event into a stream item (approvals are surfaced
+ *  separately; everything else is forwarded to the runner). */
+function sessionEventItem(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 };
+}
+/** 单条事件的 seq 去重 / admit / item / turn-end 早退；undefined 表示跳过。 */
+function advanceSessionEvent(state, ev) {
+    if (ev.seq <= state.lastSeq)
+        return undefined;
+    state.lastSeq = ev.seq;
+    if (!admitSessionEvent(state, ev))
+        return undefined;
+    return { item: sessionEventItem(state.sessionId, ev), done: ev.type === 'turn/end' };
+}
+/** 一帧 follow → 待回放的 durable 事件（assistant-stream 不带 durable 事件）。 */
+async function sessionFrameEvents(client, state, frame, signal) {
+    if (frame.type === 'snapshot') {
+        return client.replaySnapshotGap(state.sessionId, signal, state.lastSeq, frame);
+    }
+    if (frame.type === 'event')
+        return [frame.event];
+    return [];
+}
+/** 把 follow 流异常分类成 4 种动作（不改变重试/超时语义）。 */
+function classifySessionStreamError(err, state, signal) {
+    if (signal.aborted)
+        return { kind: 'return' };
+    if (isDshAuthError(err)) {
+        if (!state.authRefreshAttempted)
+            return { kind: 'refresh-auth' };
+        return { kind: 'rethrow' };
+    }
+    return { kind: 'reconnect' };
+}
 export class DshClient {
     baseUrl;
     token;
@@ -214,103 +443,83 @@ export class DshClient {
      * 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)}`;
+        const ctx = prepareUnary(opts, this.requestTimeoutMs);
         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) {
-                    getLogger().warn(`[dsh] 401 while authenticating ${method}, re-minting cookie once`);
-                    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;
-                getLogger().warn(`[dsh] 401 for ${method}, re-minting cookie once`);
-                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;
+            const result = await this.attemptUnary(method, payload, opts, ctx, attempt);
+            if (result.kind === 'done')
+                return result.value;
         }
         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 });
+    /** One unary POST attempt: obtain cookie, then post; both stages may ask to
+     *  retry once (401 → re-mint cookie); all other failures throw DshError. */
+    async attemptUnary(method, payload, opts, ctx, attempt) {
+        const cookieResult = await this.obtainUnaryCookie(method, opts, ctx, attempt);
+        if (cookieResult.kind === 'retry')
+            return { kind: 'retry' };
+        return this.postUnary(method, payload, opts, ctx, cookieResult.cookie, attempt);
+    }
+    async obtainUnaryCookie(method, opts, ctx, attempt) {
+        if (opts.signal?.aborted) {
+            throw new DshError('aborted', `DSH unary ${method} aborted before send`);
         }
-        if (timeoutSignal?.aborted) {
-            return new DshError('timeout', `DSH unary ${method} timed out after ${timeoutMs}ms`, {
-                cause: err,
+        try {
+            return { kind: 'cookie', cookie: await this.authCookie(attempt > 0, ctx.signal) };
+        }
+        catch (err) {
+            if (opts.signal?.aborted || ctx.signal?.aborted) {
+                throw abortErrorOf(method, err, opts.signal, ctx.timeoutSignal, ctx.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) {
+                getLogger().warn(`[dsh] 401 while authenticating ${method}, re-minting cookie once`);
+                return { kind: 'retry' };
+            }
+            throw err;
+        }
+    }
+    async postUnary(method, payload, opts, ctx, cookie, attempt) {
+        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: ctx.rpcId,
+                    method,
+                    payload: { args: dshArgs(method, payload) },
+                }),
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
             });
         }
-        return new DshError('aborted', `DSH unary ${method} aborted: ${err.message}`);
+        catch (err) {
+            if (opts.signal?.aborted || ctx.signal?.aborted) {
+                throw abortErrorOf(method, err, opts.signal, ctx.timeoutSignal, ctx.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;
+            getLogger().warn(`[dsh] 401 for ${method}, re-minting cookie once`);
+            return { kind: 'retry' };
+        }
+        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 });
+        }
+        return { kind: 'done', value: await readUnaryBody(method, res) };
     }
     /** Create a session. Pass `agentPreset` to pin the session's preset (fixed at
      *  creation). */
@@ -365,14 +574,6 @@ 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.
      *
@@ -578,147 +779,60 @@ export class DshClient {
      * `next` so a different lark-remote workspace cannot park it.
      */
     async *approvalEvents(sessionId, signal) {
-        let authRefreshAttempted = false;
-        let reconnectAttempts = 0;
+        const state = {
+            authRefreshAttempted: false,
+            reconnectAttempts: 0,
+            sawReady: false,
+        };
         while (!signal.aborted) {
-            let streamClientId;
-            let sawReady = false;
+            // 每次重连重置本次连接的 ready 身份；auth 刷新与重连预算跨连接保留。
+            state.sawReady = false;
+            state.streamClientId = undefined;
             try {
                 for await (const raw of this.muxStream('$events', { args: {} }, signal)) {
                     if (signal.aborted)
                         return;
-                    const frame = raw;
-                    if (frame.type === 'ready') {
-                        authRefreshAttempted = false;
-                        // 成功建连后补充重连预算：goal 驱动的 turn 可跑数小时，DSH 重启 +
-                        // 网络抖动累计掉线超过 3 次后，旧实现会让 $events 永久 unavailable
-                        // ——已渲染的提问卡持有过期 clientId（点答案必失败）、Host 的 cancel
-                        // 帧也收不到，违反「同一 waterfall 在 $events 重连后会被重投」的
-                        // 不变量。预算语义是「单次断连窗口内的连续失败上限」，不是终身配额。
-                        reconnectAttempts = 0;
-                        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 === '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.
-                            this.delegateWaterfall(streamClientId, frame.eventId, signal);
-                            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 };
-                    }
+                    const result = processApprovalFrame(state, raw, sessionId, signal, this);
+                    for (const item of result.items)
+                        yield item;
+                    if (result.stop)
+                        return;
                 }
             }
             catch (err) {
-                if (signal.aborted)
+                const action = classifyApprovalStreamError(err, state, signal);
+                if (action.kind === 'return')
                     return;
-                if (err instanceof DshError &&
-                    err.code === 'http' &&
-                    err.details.status === 401 &&
-                    !authRefreshAttempted) {
-                    authRefreshAttempted = true;
+                if (action.kind === 'refresh-auth') {
+                    state.authRefreshAttempted = true;
                     this.cookiePromise = undefined;
                     getLogger().warn(`[dsh] approval event stream authentication expired; refreshing credentials and reconnecting once`);
                     continue;
                 }
-                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));
+                if (action.kind === 'reconnect') {
+                    state.reconnectAttempts = action.attempt;
+                    getLogger().warn(`[dsh] approval event stream dropped (attempt ${action.attempt}/3); reconnecting`);
+                    await reconnectBackoff();
                     continue;
                 }
-                getLogger().warn(`[dsh] approval event stream unavailable: ${message}`);
-                yield { kind: 'unavailable', message };
+                getLogger().warn(`[dsh] approval event stream unavailable: ${action.message}`);
+                yield { kind: 'unavailable', message: action.message };
                 return;
             }
-            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' };
+            const tail = approvalStreamTail(state, signal);
+            if (tail === 'aborted')
                 return;
+            if (tail === 'reconnect') {
+                getLogger().warn(`[dsh] approval event stream ended (attempt ${state.reconnectAttempts}/3); reconnecting`);
+                await reconnectBackoff();
+                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;
         }
     }
-    /** 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, assistant stream chunks
      * and approval notices for `sessionId`, auto-reconnecting on stream
@@ -733,92 +847,47 @@ export class DshClient {
      * keeps the card "running" until this run's turn actually finishes.
      */
     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 state = {
+            lastSeq: initialSeq,
+            owns: promptRequestId === undefined,
+            foreignTailReported: false,
+            sessionId,
+            promptRequestId,
+            authRefreshAttempted: 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 {
                 for await (const frame of this.followStream(sessionId, signal)) {
                     if (signal.aborted)
                         return;
-                    authRefreshAttempted = false;
-                    if (frame.type === 'snapshot') {
-                        // 快照可能只覆盖尾部窗口（见 replaySnapshotGap）：先补缺口再回放，
-                        // 回放循环与原逻辑逐条相同（去重 / admit / turn/end 早退）。
-                        for (const ev of await this.replaySnapshotGap(sessionId, signal, state.lastSeq, frame)) {
-                            if (ev.seq <= state.lastSeq)
-                                continue;
-                            state.lastSeq = ev.seq;
-                            if (!admit(ev))
-                                continue;
-                            const item = this.eventItem(sessionId, ev);
-                            if (item)
-                                yield item;
-                            if (ev.type === 'turn/end')
-                                return;
-                        }
-                        continue;
-                    }
-                    if (frame.type === 'event') {
-                        const ev = frame.event;
-                        if (ev.seq <= state.lastSeq)
-                            continue;
-                        state.lastSeq = ev.seq;
-                        if (!admit(ev))
+                    state.authRefreshAttempted = false;
+                    for (const ev of await sessionFrameEvents(this, state, frame, signal)) {
+                        const step = advanceSessionEvent(state, ev);
+                        if (!step)
                             continue;
-                        const item = this.eventItem(sessionId, ev);
-                        if (item)
-                            yield item;
-                        if (ev.type === 'turn/end')
+                        if (step.item)
+                            yield step.item;
+                        if (step.done)
                             return;
-                        continue;
                     }
-                    if (frame.type === 'assistant-stream') {
+                    if (frame.type === 'assistant-stream' && state.owns) {
                         // Mid-turn deltas of the turn this prompt is queued behind.
-                        if (!state.owns)
-                            continue;
                         yield { kind: 'assistant-stream', sessionId, frame: frame.frame };
                     }
                 }
             }
             catch (err) {
-                if (signal.aborted)
+                const action = classifySessionStreamError(err, state, signal);
+                if (action.kind === 'return')
                     return;
-                // 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;
+                if (action.kind === 'refresh-auth') {
+                    state.authRefreshAttempted = true;
+                    this.cookiePromise = undefined;
+                    getLogger().warn(`[dsh] remote mux authentication expired for session ${sessionId}; refreshing credentials and reconnecting once`);
+                    continue;
                 }
+                if (action.kind === 'rethrow')
+                    throw err;
                 getLogger().warn(`[dsh] remote mux disconnected for session ${sessionId}: ${err.message}; reconnecting`);
             }
             if (signal.aborted)