lark-remote 0.5.19 → 0.5.21

package/dist/runner/dsh/runner.js

@@ -192,6 +192,88 @@ function interruptedResult(sessionId) {
         errorMessage: 'run stopped',
     };
 }
+/** goal/change：权威变更，不等投影直接按事件更新（create/edit/pause/...）。 */
+function goalChangeEvents(_runner, event, ctx) {
+    const parsed = goalFromChange(event.data);
+    if (parsed !== undefined && !sameGoal(parsed, ctx.goal.last)) {
+        ctx.goal.last = parsed;
+        return [goalStateEvent(parsed, true)];
+    }
+    return [];
+}
+/** approval/decided：审批回流，清审批卡。 */
+function approvalDecidedEvents(runner, event) {
+    const data = event.data;
+    if (!data.id)
+        return [];
+    runner.approvalTracker.onDecided(data.id);
+    return [runner.approvalResolved(data.id)];
+}
+/** 终态分支查表：命中即返回（不再落到 translator）。 */
+const SESSION_EVENT_TERMINAL_HANDLERS = new Map([
+    ['goal/change', goalChangeEvents],
+    ['approval/decided', approvalDecidedEvents],
+]);
+/** tool/call：先记账（审批卡命令展示用），随后仍落到 translator 出工具行。 */
+function recordToolCall(toolCalls, event) {
+    const data = event.data;
+    if (data.callId && data.name) {
+        toolCalls.set(data.callId, {
+            name: data.name,
+            arguments: data.arguments ?? '',
+            ...(data.turn === undefined ? {} : { turn: data.turn }),
+        });
+        if (toolCalls.size > 100) {
+            const oldest = toolCalls.keys().next().value;
+            if (oldest !== undefined)
+                toolCalls.delete(oldest);
+        }
+    }
+}
+/** result 收尾：后台任务名单 + goal 收尾复核；返回要插到 result 前的事件。 */
+async function resultFinalizeEvents(runner, ctx) {
+    const events = [];
+    for (const jobsEvent of await runner.collectBackgroundJobs(ctx.sessionId, ctx.abort.signal)) {
+        events.push(jobsEvent);
+    }
+    // 收尾复核：这一轮结束时 goal 是否仍 active，决定卡片能不能收尾。
+    // 必须现读宿主，不能沿用过程中的最后一次观测——goal 可能在本轮
+    // 最后一个 step 才被 complete，也可能刚被 driver 置为 blocked。
+    const finalGoal = await runner.client.goalState(ctx.sessionId, {
+        signal: ctx.signal,
+        timeoutMs: GOAL_PROBE_TIMEOUT_MS,
+    });
+    if (!finalGoal.known) {
+        // 收尾读不到：seed 已报过 unknown 就不重复发，否则把状态降级
+        // 交给卡片（卡片据此不再宣布完成）。
+        if (ctx.goal.known) {
+            ctx.goal.known = false;
+            events.push(goalStateEvent(null, false));
+        }
+    }
+    else if (!ctx.goal.known || !sameGoal(finalGoal.goal, ctx.goal.last)) {
+        ctx.goal.known = true;
+        ctx.goal.last = finalGoal.goal;
+        events.push(goalStateEvent(finalGoal.goal, true));
+    }
+    return events;
+}
+/** translator 循环：result 事件插入收尾事件并提前返回。 */
+async function collectAgentEvents(runner, event, ctx) {
+    const events = [];
+    for (const ev of ctx.translator.eventToAgentEvents(event, ctx.sessionId)) {
+        if (ev.type === 'result') {
+            if (!ctx.abort.signal.aborted) {
+                for (const finalized of await resultFinalizeEvents(runner, ctx))
+                    events.push(finalized);
+            }
+            events.push(attachContextLimit(ev, ctx.live.contextLimit));
+            return events;
+        }
+        events.push(ev);
+    }
+    return events;
+}
 export class DshRunner {
     kind = 'dsh';
     /**
@@ -432,41 +514,6 @@ export class DshRunner {
                 yield interruptedResult(sessionId);
                 return;
             }
-            // provider/模型/推理强度对齐：会话首次 run 时 selectModel 一次
-            // （该调用同时写服务端全局默认，故不重复写）；同一 session 后续 run
-            // 跳过。显式配置 provider 时失败必须 fail closed：静默回退到其他
-            // provider 会让用户以为切换成功，实际模型与账单都错。
-            if ((this.configuredModel || this.configuredProvider) &&
-                !this.alignedSessions.has(sessionId)) {
-                try {
-                    const selection = await this.resolveModelSelection(abort.signal);
-                    await this.client.selectModel({ sessionId, ...selection }, { signal: abort.signal });
-                    this.alignedSessions.add(sessionId);
-                }
-                catch (err) {
-                    if (abort.signal.aborted) {
-                        getLogger().info(`[dsh] run stopped during selectModel session=${sessionId}`);
-                        terminalEmitted = true;
-                        yield interruptedResult(sessionId);
-                        return;
-                    }
-                    if (this.configuredProvider) {
-                        throw new Error(`Provider "${this.configuredProvider}" 的模型对齐失败：${err.message}。` +
-                            '请在 DSH Web UI → 设置 → Models 检查该 Provider 的凭据与模型目录', { cause: err });
-                    }
-                    getLogger().warn(`[dsh] selectModel failed for session ${sessionId} (run continues): ${err.message}`);
-                }
-            }
-            // 权限预设对齐：与模型对齐同语义，同一 session 只执行一次
-            // `/permission <preset>`。失败必须 fail closed——用户明确选了安全策略，
-            // 不能在错误的权限下继续跑 prompt。
-            await this.alignPermissionPreset(sessionId, abort.signal);
-            // Abort 可能在上述 unary 完成与检查之间到达：不进入 prompt/turn。
-            if (abort.signal.aborted) {
-                terminalEmitted = true;
-                yield interruptedResult(sessionId);
-                return;
-            }
             yield {
                 type: 'system',
                 subtype: 'init',
@@ -474,24 +521,18 @@ export class DshRunner {
                 cwd: opts.cwd,
                 model: this.configuredModel ?? 'DSH',
             };
-            // Goal seed：卡片从第一帧就知道这个会话有没有长期目标。放在 init 之后、
-            // prompt 之前——用户发消息时若是 queued，卡片会长时间停在「运行中」，
-            // 这期间"目标是什么、第几轮"是唯一能解释"为什么还不停"的信息。
-            const seedGoal = await this.client.goalState(sessionId, {
-                signal: abort.signal,
-                timeoutMs: GOAL_PROBE_TIMEOUT_MS,
-            });
-            const lastGoal = seedGoal.known ? seedGoal.goal : undefined;
-            if (seedGoal.known) {
-                // 只有确实存在 goal 才产事件：没有 goal 的会话保持事件序列不变（少一次
-                // 渲染，也不让"读不到"变成一张多出来的卡片事件）。
-                if (seedGoal.goal)
-                    yield goalStateEvent(seedGoal.goal, true);
+            // 准备阶段（模型对齐 + 权限预设对齐 + goal seed + abort 检查）抽到
+            // prepareTurn：对齐失败 fail closed（显式 provider 时 throw，由外层 catch
+            // 转 error result）；被 stop 时返回 interrupted 形态，这里统一 yield
+            // interrupted result 收尾。
+            const prepared = await this.prepareTurn(sessionId, abort);
+            if (!prepared.ok) {
+                terminalEmitted = true;
+                yield interruptedResult(sessionId);
+                return;
             }
-            else {
-                // 读不到 ≠ 没有目标。必须显式把 unknown 交给卡片，否则收尾只能按
-                // 「没有 goal」写成「已完成」——正是 GoalStateEvent 契约禁止的推断。
-                yield goalStateEvent(null, false);
+            for (const goalEvent of prepared.goalEvents) {
+                yield goalEvent;
             }
             try {
                 const submitted = await this.submitPrompt(sessionId, opts.cwd, message, abort.signal);
@@ -504,7 +545,7 @@ export class DshRunner {
                     return;
                 }
                 try {
-                    for await (const ev of this.runTurn(sessionId, opts.cwd, submitted.prePromptSeq, promptRequestId, abort, { last: lastGoal, known: seedGoal.known })) {
+                    for await (const ev of this.runTurn(sessionId, opts.cwd, submitted.prePromptSeq, promptRequestId, abort, { last: prepared.lastGoal, known: prepared.goalKnown })) {
                         yield ev;
                         if (ev.type === 'result') {
                             terminalEmitted = true;
@@ -573,10 +614,80 @@ export class DshRunner {
             };
         }
     }
+    /**
+     * 准备一个 turn（run() 的准备阶段）：模型对齐 + 权限预设对齐 + goal seed 探测。
+     *
+     * 红线（逐条保留）：
+     * - 对齐失败 fail closed：显式配置 provider 时 selectModel 失败必须 throw
+     *   （静默回退到其他 provider 会让用户以为切换成功，实际模型与账单都错）；
+     *   权限预设失败由 alignPermissionPreset throw（用户明确选了安全策略，不能在
+     *   错误的权限下继续跑 prompt）。
+     * - 准备期间被 stop（abort）→ 返回 { ok:false }，由调用方 yield interrupted
+     *   result 收尾。
+     * - goal seed 只探测不推断：读不到按 unknown 上报，不冒充「没有 goal」。
+     */
+    async prepareTurn(sessionId, abort) {
+        // provider/模型/推理强度对齐：会话首次 run 时 selectModel 一次
+        // （该调用同时写服务端全局默认，故不重复写）；同一 session 后续 run
+        // 跳过。显式配置 provider 时失败必须 fail closed：静默回退到其他
+        // provider 会让用户以为切换成功，实际模型与账单都错。
+        if ((this.configuredModel || this.configuredProvider) && !this.alignedSessions.has(sessionId)) {
+            try {
+                const selection = await this.resolveModelSelection(abort.signal);
+                await this.client.selectModel({ sessionId, ...selection }, { signal: abort.signal });
+                this.alignedSessions.add(sessionId);
+            }
+            catch (err) {
+                if (abort.signal.aborted) {
+                    getLogger().info(`[dsh] run stopped during selectModel session=${sessionId}`);
+                    return { ok: false };
+                }
+                if (this.configuredProvider) {
+                    throw new Error(`Provider "${this.configuredProvider}" 的模型对齐失败：${err.message}。` +
+                        '请在 DSH Web UI → 设置 → Models 检查该 Provider 的凭据与模型目录', { cause: err });
+                }
+                getLogger().warn(`[dsh] selectModel failed for session ${sessionId} (run continues): ${err.message}`);
+            }
+        }
+        // 权限预设对齐：与模型对齐同语义，同一 session 只执行一次
+        // `/permission <preset>`。失败必须 fail closed——用户明确选了安全策略，
+        // 不能在错误的权限下继续跑 prompt。
+        await this.alignPermissionPreset(sessionId, abort.signal);
+        // Abort 可能在上述 unary 完成与检查之间到达：不进入 prompt/turn。
+        if (abort.signal.aborted) {
+            return { ok: false };
+        }
+        // Goal seed：卡片从第一帧就知道这个会话有没有长期目标。放在 init 之后、
+        // prompt 之前——用户发消息时若是 queued，卡片会长时间停在「运行中」，
+        // 这期间"目标是什么、第几轮"是唯一能解释"为什么还不停"的信息。
+        const seedGoal = await this.client.goalState(sessionId, {
+            signal: abort.signal,
+            timeoutMs: GOAL_PROBE_TIMEOUT_MS,
+        });
+        const lastGoal = seedGoal.known ? seedGoal.goal : undefined;
+        const goalEvents = [];
+        if (seedGoal.known) {
+            // 只有确实存在 goal 才产事件：没有 goal 的会话保持事件序列不变（少一次
+            // 渲染，也不让"读不到"变成一张多出来的卡片事件）。
+            if (seedGoal.goal)
+                goalEvents.push(goalStateEvent(seedGoal.goal, true));
+        }
+        else {
+            // 读不到 ≠ 没有目标。必须显式把 unknown 交给卡片，否则收尾只能按
+            // 「没有 goal」写成「已完成」——正是 GoalStateEvent 契约禁止的推断。
+            goalEvents.push(goalStateEvent(null, false));
+        }
+        return { ok: true, lastGoal, goalKnown: seedGoal.known, goalEvents };
+    }
     /**
      * Consume one turn from both transports. `session/follow` owns transcript
      * events; `$events` owns the answerable approval waterfall. The merged
      * stream keeps either transport from starving the other.
+     *
+     * 事件源分派：projection（goal + 状态条）→ handleProjectionItem；
+     * $events waterfall（审批/提问）→ handleApprovalWaterfallItem；
+     * assistant-stream 直转发（translator 持有本 turn 的 usage 累计状态）；
+     * session/follow 事件 → handleSessionEvent（含 result 收尾的 jobs + goal 复核）。
      */
     async *runTurn(sessionId, cwd, prePromptSeq, promptRequestId, abort, goal) {
         const streamAbort = new AbortController();
@@ -600,165 +711,41 @@ export class DshRunner {
             for await (const item of mergeAsync(sources)) {
                 if (abort.signal.aborted)
                     return;
+                // 事件源 1：Host-wide 投影（goal + 状态条）。
                 if (item.kind === 'projection') {
-                    // 全 Host 流：只认本 session。未知 key 直接忽略（投影是能力发现式
-                    // 扩展的，不能因为多了个 key 就报错）。
-                    if (item.sessionId !== sessionId)
-                        continue;
-                    // goal 是会话级长期目标，单独成事件：卡片要在 agent 创建目标的当下
-                    // 就显示它（否则用户只会在一小时后看到「完成」才发现有个 40 轮任务）。
-                    if (item.key === 'goal') {
-                        const parsed = goalFromProjection(item.value);
-                        if (parsed !== undefined && !sameGoal(parsed, goal.last)) {
-                            goal.last = parsed;
-                            yield goalStateEvent(parsed, true);
-                        }
-                        continue;
-                    }
-                    // 只在消费字段真的变了时才产出事件：投影帧本身按 key 去重推送，
-                    // 这里再挡掉"值没变"的重复帧。不需要时间节流——卡片更新本来就有
-                    // 100ms 合批窗口，与正文 delta 共用同一条节流路径。
-                    if (!applyProjection(live, item.key, item.value))
-                        continue;
-                    yield statusEventOf(live);
-                    continue;
-                }
-                if (item.kind === 'ready') {
-                    this.approvalChannelAvailable = true;
-                    continue;
-                }
-                if (item.kind === 'unavailable') {
-                    this.approvalChannelAvailable = false;
-                    getLogger().warn(`[dsh] approval channel unavailable: ${item.message}`);
-                    continue;
-                }
-                if (item.kind === 'request') {
-                    this.approvalTracker.onWaterfall({
-                        eventId: item.eventId,
-                        clientId: item.clientId,
-                        ...(item.callId ? { callId: item.callId } : {}),
-                        toolName: item.toolName,
-                        ...(item.reason ? { reason: item.reason } : {}),
-                    });
-                    continue;
-                }
-                if (item.kind === 'question') {
-                    // 同一 waterfall 在重连后会带新的 clientId 重投：覆盖写回，卡片的
-                    // requestId（eventId）不变，coordinator 按重投语义刷新视图。
-                    this.pendingQuestions.set(item.eventId, {
-                        clientId: item.clientId,
-                        questions: item.questions,
-                    });
-                    getLogger().info(`[dsh] user question surfaced eventId=${item.eventId} questions=${item.questions.length}`);
-                    yield this.buildQuestionRequested(sessionId, item.eventId, item.questions);
-                    continue;
-                }
-                if (item.kind === 'cancelled') {
-                    // 提问与审批共用 cancel 帧：提问在别处（DSH Web UI）被回答或超时后
-                    // 也要清掉飞书卡片，否则上面还留着可点但已无 responder 的问题区。
-                    if (this.pendingQuestions.delete(item.eventId)) {
-                        getLogger().info(`[dsh] user question resolved elsewhere eventId=${item.eventId}`);
-                        yield this.approvalResolved(item.eventId);
-                        continue;
+                    for (const ev of this.handleProjectionItem(item, sessionId, goal, live)) {
+                        yield ev;
                     }
-                    const binding = this.approvalTracker.onCancelled(item.eventId);
-                    if (binding)
-                        yield this.approvalResolved(binding.audit.approvalId);
                     continue;
                 }
-                if (item.kind === 'approval') {
-                    const audit = {
-                        approvalId: item.approvalId,
-                        toolName: item.toolName,
-                        ...(item.callId ? { callId: item.callId } : {}),
-                        ...(item.reason ? { reason: item.reason } : {}),
-                    };
-                    const binding = this.approvalTracker.onAuditAsked(audit);
-                    if (!this.approvalChannelAvailable) {
-                        getLogger().warn(`[dsh] approval requested approvalId=${item.approvalId} tool=${item.toolName}; live channel unavailable — falling back to Web UI`);
-                        yield this.approvalFallbackText(item.toolName);
-                        continue;
+                // 事件源 2：$events 审批/提问 waterfall。
+                if (item.kind === 'ready' ||
+                    item.kind === 'unavailable' ||
+                    item.kind === 'request' ||
+                    item.kind === 'question' ||
+                    item.kind === 'cancelled' ||
+                    item.kind === 'approval') {
+                    for (const ev of this.handleApprovalWaterfallItem(item, sessionId, cwd, emittedApprovals)) {
+                        yield ev;
                     }
-                    if (emittedApprovals.has(item.approvalId))
-                        continue;
-                    emittedApprovals.add(item.approvalId);
-                    yield this.buildApprovalRequested(sessionId, audit, binding, cwd);
                     continue;
                 }
+                // 事件源 3a：assistant 流式帧（translator 持有本 turn 的 usage 累计状态，
+                // 必须与 3b 共用同一实例）。
                 if (item.kind === 'assistant-stream') {
                     for (const ev of translator.streamFrameToAgentEvents(item.frame, sessionId)) {
                         yield ev;
                     }
                     continue;
                 }
-                const event = item.event;
-                if (event.type === 'goal/change') {
-                    // 权威变更（create/edit/pause/resume/complete/block/clear）：不等投影
-                    // 推送，直接按事件更新——agent 刚 create 的那一刻卡片就该显示目标。
-                    const parsed = goalFromChange(event.data);
-                    if (parsed !== undefined && !sameGoal(parsed, goal.last)) {
-                        goal.last = parsed;
-                        yield goalStateEvent(parsed, true);
-                    }
-                    continue;
-                }
-                if (event.type === 'tool/call') {
-                    const data = event.data;
-                    if (data.callId && data.name) {
-                        this.toolCalls.set(data.callId, {
-                            name: data.name,
-                            arguments: data.arguments ?? '',
-                            ...(data.turn === undefined ? {} : { turn: data.turn }),
-                        });
-                        if (this.toolCalls.size > 100) {
-                            const oldest = this.toolCalls.keys().next().value;
-                            if (oldest !== undefined)
-                                this.toolCalls.delete(oldest);
-                        }
-                    }
-                    // 记账后继续往下走：tool/call 同时是卡片工具行的来源（translator 翻
-                    // 译成 assistant.tool_use）。早期版本在这里 `continue`，把调用轨迹整个
-                    // 吞掉——卡片因此只有正文、没有任何工具行。
-                }
-                if (event.type === 'approval/decided') {
-                    const data = event.data;
-                    if (!data.id)
-                        continue;
-                    this.approvalTracker.onDecided(data.id);
-                    yield this.approvalResolved(data.id);
-                    continue;
-                }
-                for (const ev of translator.eventToAgentEvents(event, sessionId)) {
-                    if (ev.type === 'result') {
-                        if (!abort.signal.aborted) {
-                            for (const jobsEvent of await this.collectBackgroundJobs(sessionId, abort.signal)) {
-                                yield jobsEvent;
-                            }
-                            // 收尾复核：这一轮结束时 goal 是否仍 active，决定卡片能不能收尾。
-                            // 必须现读宿主，不能沿用过程中的最后一次观测——goal 可能在本轮
-                            // 最后一个 step 才被 complete，也可能刚被 driver 置为 blocked。
-                            const finalGoal = await this.client.goalState(sessionId, {
-                                signal,
-                                timeoutMs: GOAL_PROBE_TIMEOUT_MS,
-                            });
-                            if (!finalGoal.known) {
-                                // 收尾读不到：seed 已报过 unknown 就不重复发，否则把状态降级
-                                // 交给卡片（卡片据此不再宣布完成）。
-                                if (goal.known) {
-                                    goal.known = false;
-                                    yield goalStateEvent(null, false);
-                                }
-                            }
-                            else if (!goal.known || !sameGoal(finalGoal.goal, goal.last)) {
-                                goal.known = true;
-                                goal.last = finalGoal.goal;
-                                yield goalStateEvent(finalGoal.goal, true);
-                            }
-                        }
-                        yield attachContextLimit(ev, live.contextLimit);
-                        return;
-                    }
+                // 事件源 3b：session/follow 事件（正文/工具行/result 收尾，含 jobs +
+                // goal 复核）。result 之后的收尾事件由 handler 按序返回，见到 result
+                // 即结束本 turn（与原 yield-then-return 逐字等价）。
+                const eventEvents = await this.handleSessionEvent(item.event, sessionId, translator, goal, live, abort, signal);
+                for (const ev of eventEvents) {
                     yield ev;
+                    if (ev.type === 'result')
+                        return;
                 }
             }
         }
@@ -769,6 +756,116 @@ export class DshRunner {
             this.toolCalls.clear();
         }
     }
+    /**
+     * 事件源 handler：Host-wide 投影（goal + 状态条）。
+     * 返回要回放的事件（可能为空——未变化/非本 session 的帧不产事件）。
+     */
+    handleProjectionItem(item, sessionId, goal, live) {
+        // 全 Host 流：只认本 session。未知 key 直接忽略（投影是能力发现式
+        // 扩展的，不能因为多了个 key 就报错）。
+        if (item.sessionId !== sessionId)
+            return [];
+        // goal 是会话级长期目标，单独成事件：卡片要在 agent 创建目标的当下
+        // 就显示它（否则用户只会在一小时后看到「完成」才发现有个 40 轮任务）。
+        if (item.key === 'goal') {
+            const parsed = goalFromProjection(item.value);
+            if (parsed !== undefined && !sameGoal(parsed, goal.last)) {
+                goal.last = parsed;
+                return [goalStateEvent(parsed, true)];
+            }
+            return [];
+        }
+        // 只在消费字段真的变了时才产出事件：投影帧本身按 key 去重推送，
+        // 这里再挡掉"值没变"的重复帧。不需要时间节流——卡片更新本来就有
+        // 100ms 合批窗口，与正文 delta 共用同一条节流路径。
+        if (!applyProjection(live, item.key, item.value))
+            return [];
+        return [statusEventOf(live)];
+    }
+    /**
+     * 事件源 handler：$events 审批/提问 waterfall（channel 状态、审批 waterfall
+     * 登记、提问卡、cancel 回流、审批卡）。
+     * 返回要回放的事件；channel 状态类帧（ready/unavailable/request）只改内部
+     * 状态、不产事件。
+     */
+    handleApprovalWaterfallItem(item, sessionId, cwd, emittedApprovals) {
+        switch (item.kind) {
+            case 'ready':
+                this.approvalChannelAvailable = true;
+                return [];
+            case 'unavailable':
+                this.approvalChannelAvailable = false;
+                getLogger().warn(`[dsh] approval channel unavailable: ${item.message}`);
+                return [];
+            case 'request':
+                this.approvalTracker.onWaterfall({
+                    eventId: item.eventId,
+                    clientId: item.clientId,
+                    ...(item.callId ? { callId: item.callId } : {}),
+                    toolName: item.toolName,
+                    ...(item.reason ? { reason: item.reason } : {}),
+                });
+                return [];
+            case 'question': {
+                // 同一 waterfall 在重连后会带新的 clientId 重投：覆盖写回，卡片的
+                // requestId（eventId）不变，coordinator 按重投语义刷新视图。
+                this.pendingQuestions.set(item.eventId, {
+                    clientId: item.clientId,
+                    questions: item.questions,
+                });
+                getLogger().info(`[dsh] user question surfaced eventId=${item.eventId} questions=${item.questions.length}`);
+                return [this.buildQuestionRequested(sessionId, item.eventId, item.questions)];
+            }
+            case 'cancelled': {
+                // 提问与审批共用 cancel 帧：提问在别处（DSH Web UI）被回答或超时后
+                // 也要清掉飞书卡片，否则上面还留着可点但已无 responder 的问题区。
+                if (this.pendingQuestions.delete(item.eventId)) {
+                    getLogger().info(`[dsh] user question resolved elsewhere eventId=${item.eventId}`);
+                    return [this.approvalResolved(item.eventId)];
+                }
+                const binding = this.approvalTracker.onCancelled(item.eventId);
+                return binding ? [this.approvalResolved(binding.audit.approvalId)] : [];
+            }
+            case 'approval': {
+                const audit = {
+                    approvalId: item.approvalId,
+                    toolName: item.toolName,
+                    ...(item.callId ? { callId: item.callId } : {}),
+                    ...(item.reason ? { reason: item.reason } : {}),
+                };
+                const binding = this.approvalTracker.onAuditAsked(audit);
+                if (!this.approvalChannelAvailable) {
+                    getLogger().warn(`[dsh] approval requested approvalId=${item.approvalId} tool=${item.toolName}; live channel unavailable — falling back to Web UI`);
+                    return [this.approvalFallbackText(item.toolName)];
+                }
+                if (emittedApprovals.has(item.approvalId))
+                    return [];
+                emittedApprovals.add(item.approvalId);
+                return [this.buildApprovalRequested(sessionId, audit, binding, cwd)];
+            }
+        }
+    }
+    /**
+     * 事件源 handler：`session/follow` 会话事件。
+     * - goal/change：权威变更，不等投影直接更新；
+     * - tool/call：先记账（审批卡命令展示用）再落入 translator（卡片工具行来源）；
+     * - approval/decided：审批回流，清审批卡；
+     * - 其余事件经 translator 翻译；result 事件先做收尾（后台任务名单 + goal
+     *   复核）再随 result 一起返回。
+     */
+    async handleSessionEvent(event, sessionId, translator, goal, live, abort, signal) {
+        const ctx = { sessionId, translator, goal, live, abort, signal };
+        const terminal = SESSION_EVENT_TERMINAL_HANDLERS.get(event.type);
+        if (terminal)
+            return terminal(this, event, ctx);
+        if (event.type === 'tool/call') {
+            // 记账后继续往下走：tool/call 同时是卡片工具行的来源（translator 翻
+            // 译成 assistant.tool_use）。早期版本在这里 `continue`，把调用轨迹整个
+            // 吞掉——卡片因此只有正文、没有任何工具行。
+            recordToolCall(this.toolCalls, event);
+        }
+        return collectAgentEvents(this, event, ctx);
+    }
     /**
      * 收尾时仍在跑的后台任务。
      *
@@ -1409,7 +1506,7 @@ export class DshRunner {
      *
      * turn 跑在常驻共享的 `dsh web` host 里，不在本进程的子进程树上；所以
      * "杀自己的子进程"这套退出清理对它无效，桥接一退出，turn 继续无人接收地跑
-     * （2026-10-19 实测：一个孤儿 turn 在桥接死后又跑了 2h21m / 345 个 step）。
+     * （孤儿 turn 在桥接死后可能再跑数小时）。
      * 这里复用进程级退出分发器，用同步 curl 发一次 `session/cancel`。
      */
     registerExitHandlers() {

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

@@ -26,39 +26,9 @@
 import type { AgentEvent, ResultEvent } from '../types.js';
 import type { DshAssistantStreamFrame, DshSessionEvent, DshTokenUsage } from '../../dsh/types.js';
 export declare class DshTranslator {
-    /** 本 turn 累计用量：DSH 每次模型调用（step）一条 usage，工具往返 = 多条。 */
-    private turnUsage;
-    /** 末次采样的 usage：上下文水位，或只有 live chunk 时的兜底值。 */
-    private lastUsage?;
-    /** 是否收到过 durable assistant/message.usage（唯一累加来源）。 */
-    private hasMessageUsage;
-    /** 是否只收到过 live usage chunk（无 durable message usage 时的兜底）。 */
-    private hasStreamUsage;
-    /** 当前 attempt 的 id（start 帧携带，chunk 帧也带；断开重连重放时不变）。 */
-    private attemptId;
-    /**
-     * 本 turn 末条 durable assistant 消息的正文（**完整**、未截断）。
-     *
-     * live chunk 是逐 delta 拼接、会被状态层的 MAX_TEXT_CHARS 窗口截断；
-     * durable `assistant/message` 一次就到齐全文。收 turn 时把它挂在 result 上，
-     * 卡片才能渲染完整回答（2026-11-01 输出块被截断缺陷）。
-     */
-    private lastMessageText?;
+    private readonly state;
     /** Translate one live assistant-stream chunk into AgentEvents. */
     streamFrameToAgentEvents(frame: DshAssistantStreamFrame, _sessionId: string): AgentEvent[];
-    /**
-     * Record durable per-step usage — the accumulation source. assistant/message
-     * carries exactly one usage per model call and is seq-deduped by the client,
-     * so summing it gives the turn total without double counting.
-     */
-    private recordMessageUsage;
-    /**
-     * Record a live usage chunk. Never summed: the same step also arrives as a
-     * durable assistant/message.usage, so summing both would double count. It only
-     * refreshes the watermark and covers a turn whose messages never persisted.
-     */
-    private recordStreamUsage;
-    private chunkToAgentEvents;
     /** Translate one session event into AgentEvents (may be empty). */
     eventToAgentEvents(ev: DshSessionEvent, sessionId: string): AgentEvent[];
 }