lark-remote 0.5.18 → 0.5.20

package/dist/runner/dsh/runner.js

@@ -432,41 +432,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 +439,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 +463,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 +532,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 +629,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 +674,174 @@ 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) {
+        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;
+                return [goalStateEvent(parsed, true)];
+            }
+            return [];
+        }
+        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`，把调用轨迹整个
+            // 吞掉——卡片因此只有正文、没有任何工具行。
+        }
+        else if (event.type === 'approval/decided') {
+            const data = event.data;
+            if (!data.id)
+                return [];
+            this.approvalTracker.onDecided(data.id);
+            return [this.approvalResolved(data.id)];
+        }
+        const events = [];
+        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)) {
+                        events.push(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;
+                            events.push(goalStateEvent(null, false));
+                        }
+                    }
+                    else if (!goal.known || !sameGoal(finalGoal.goal, goal.last)) {
+                        goal.known = true;
+                        goal.last = finalGoal.goal;
+                        events.push(goalStateEvent(finalGoal.goal, true));
+                    }
+                }
+                events.push(attachContextLimit(ev, live.contextLimit));
+                return events;
+            }
+            events.push(ev);
+        }
+        return events;
+    }
     /**
      * 收尾时仍在跑的后台任务。
      *
@@ -796,6 +869,22 @@ export class DshRunner {
             },
         ];
     }
+    /**
+     * 订阅本 session 的后台任务名单（跨 turn 生命周期）。
+     *
+     * 卡片收尾后仍要靠它把「任务结束了」推给用户：run 的事件流在 result 就关了，
+     * 而后台任务可能再跑半小时。名单是整份替换，消费方自己做 diff。
+     */
+    async *watchJobs(sessionId, signal) {
+        for await (const rows of this.client.watchJobs(sessionId, signal)) {
+            yield rows.map((job) => ({
+                id: job.id,
+                label: job.label ?? job.id,
+                ...(job.status === undefined ? {} : { status: job.status }),
+                ...(job.progress === undefined ? {} : { progress: job.progress }),
+            }));
+        }
+    }
     /** Kill one background job of this runner's session (card button path). */
     async killJob(sessionId, jobId) {
         return await this.client.jobKill(sessionId, jobId);
@@ -1393,7 +1482,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

@@ -41,7 +41,7 @@ export declare class DshTranslator {
      *
      * live chunk 是逐 delta 拼接、会被状态层的 MAX_TEXT_CHARS 窗口截断；
      * durable `assistant/message` 一次就到齐全文。收 turn 时把它挂在 result 上，
-     * 卡片才能渲染完整回答（2026-11-01 输出块被截断缺陷）。
+     * 卡片才能渲染完整回答。
      */
     private lastMessageText?;
     /** Translate one live assistant-stream chunk into AgentEvents. */

package/dist/runner/dsh/translator.js

@@ -39,7 +39,7 @@ export class DshTranslator {
      *
      * live chunk 是逐 delta 拼接、会被状态层的 MAX_TEXT_CHARS 窗口截断；
      * durable `assistant/message` 一次就到齐全文。收 turn 时把它挂在 result 上，
-     * 卡片才能渲染完整回答（2026-11-01 输出块被截断缺陷）。
+     * 卡片才能渲染完整回答。
      */
     lastMessageText;
     /** Translate one live assistant-stream chunk into AgentEvents. */

package/dist/runner/index.d.ts

@@ -15,6 +15,6 @@ export { KimiAcpRunner } from './kimi/index.js';
 export { DshRunner } from './dsh/index.js';
 export { BashProcessRunner, type BashRunner } from './bash/index.js';
 export { AgentRegistry } from './registry.js';
-export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentRunner, TurnStartedEvent, TurnDiffEvent, FinalAnswerEvent, NoticeEvent, SessionInfoEvent, ToolHint, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, GoalView, GoalStateEvent, } from './types.js';
+export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentRunner, TurnStartedEvent, TurnDiffEvent, FinalAnswerEvent, NoticeEvent, SessionInfoEvent, ToolHint, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, BackgroundJobRoster, BackgroundJobsEvent, AssistantEvent, RunStatusEvent, UserEvent, GoalView, GoalStateEvent, } from './types.js';
 export { resolveAgentChoices } from './resolve-agent-choices.js';
 export { syncAgentChoices } from './sync-agent-choices.js';

package/dist/runner/kimi/acp/runner.d.ts

@@ -109,8 +109,7 @@ export declare class KimiAcpRunner extends BaseAcpRunner<KimiAcpTranslator> {
      * before producing the result. There is NO total timeout — silence beyond
      * compactIdleTimeoutMs yields 'unknown' (never a fake success). Keeps the
      * connection alive while the background compaction finishes — otherwise
-     * dispose/exit kills it and the record never lands (打回复现 /
-     * 2026-08-31 事故).
+     * dispose/exit kills it and the record never lands.
      */
     protected compactBaseline(sessionId: string, opts: SpawnOptions): number;
     protected onCompactPromptFired(promptPromise: Promise<SessionPromptResult>, translator: KimiAcpTranslator, sessionId: string, opts: SpawnOptions, baselineTotalCount: number): void;

package/dist/runner/kimi/acp/runner.js

@@ -292,8 +292,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
      * before producing the result. There is NO total timeout — silence beyond
      * compactIdleTimeoutMs yields 'unknown' (never a fake success). Keeps the
      * connection alive while the background compaction finishes — otherwise
-     * dispose/exit kills it and the record never lands (打回复现 /
-     * 2026-08-31 事故).
+     * dispose/exit kills it and the record never lands.
      */
     compactBaseline(sessionId, opts) {
         const compactionReader = this.sessionReader.readCompactionRecords;

package/dist/runner/kimi/acp/translator.d.ts

@@ -9,7 +9,7 @@
  * assistant deltas — see handleAgentMessageChunk), plus question elicitation.
  *
  * Wire envelope (source: kimi-code packages/acp-server/src/events-map.ts,
- * verified live 2026-08-15/16 against kimi 0.36.0):
+ * verified against kimi 0.36.0):
  *   session/update params = {sessionId, update: {sessionUpdate: '<kind>', ...}}
  *   — the discriminator is `update.sessionUpdate`, NOT a nested `event.type`.
  *

package/dist/runner/kimi/acp/translator.js

@@ -9,7 +9,7 @@
  * assistant deltas — see handleAgentMessageChunk), plus question elicitation.
  *
  * Wire envelope (source: kimi-code packages/acp-server/src/events-map.ts,
- * verified live 2026-08-15/16 against kimi 0.36.0):
+ * verified against kimi 0.36.0):
  *   session/update params = {sessionId, update: {sessionUpdate: '<kind>', ...}}
  *   — the discriminator is `update.sessionUpdate`, NOT a nested `event.type`.
  *
@@ -69,8 +69,7 @@ export class KimiAcpTranslator extends BaseAcpTranslator {
         // snapshot and emit it as turn_diff. The card reducer's turn_diff path
         // REPLACES the block in place (snapshot semantics). Emitting the full
         // text as assistant/text (delta semantics) made the reducer append the
-        // full text to itself on every chunk — duplicated card output
-        // (2026-08-17 live regression, reproduced with 3 chunks).
+        // full text to itself on every chunk — duplicated card output.
         const key = 'text';
         const prev = this.textByItem.get(key) ?? '';
         const next = prev + event.content.text;
@@ -130,7 +129,7 @@ export class KimiAcpTranslator extends BaseAcpTranslator {
             getLogger().info(`[kimi-acp-translator] permission request without toolCall, auto-responding cancelled (requestId=${requestId})`);
             return [];
         }
-        // 命令恢复（2026-09-13 对 kimi 0.42.0 实测）：审批门在 tool.call.started
+        // 命令恢复（kimi 0.42.0）：审批门在 tool.call.started
         // 之前触发，request_permission 的 toolCall 只有 title（"Bash"）+ content
         // 里一句截断摘要（"Requesting approval to Running: <cmd>…"），无 rawInput；
         // 完整命令只从审批前的 tool_call/tool_call_update 流式 args 累积文本拿到