@steerable/agent-shell 0.6.15

package/dist/local-backend/coreloop-stream.js

@@ -0,0 +1,277 @@
+/**
+ * A4: drive one chat turn through the sidecar-hosted Python CoreLoop.
+ *
+ * This is the default chat path (since 2026-08-26): the sidecar owns
+ * think→act→observe, and tool calls come back over the reverse channel
+ * (`tool.invoke`, registered in `main.ts`). This module only translates the
+ * wire notifications into the existing SSE contract — the renderer, preload
+ * and IPC layers are untouched.
+ *
+ * This is the only chat path (the TS loop was deleted 2026-08-26). If the
+ * sidecar failed to start, the router fails loud with a 503 — there is no
+ * in-process fallback loop anymore. `STEERABLE_USE_SIDECAR=0` still
+ * disables the sidecar process itself (auxiliary LLM calls then fall back
+ * to the in-proc providers), but chat requires the sidecar.
+ */
+/**
+ * Active CoreLoop turns by chatId — lets the main process route a mid-turn
+ * steer (user typed while the turn runs) to the right sidecar stream without
+ * threading the sidecar streamId up through the router's call chain.
+ */
+const activeCoreLoopStreams = new Map();
+// How long to wait for the sidecar's cancelled stream.done (carries the
+// traceId) after a user abort before settling with a bare AbortError.
+const CANCEL_GRACE_MS = 10_000;
+/** Sidecar streamId of the chat's running CoreLoop turn, if any. */
+export function getActiveCoreLoopStreamId(chatId) {
+    return activeCoreLoopStreams.get(chatId);
+}
+const WEEKDAYS_ZH = ['周日', '周一', '周二', '周三', '周四', '周五', '周六'];
+/**
+ * 构建本轮的 world-state 节(Wave 2 起;W6-7b 从只有 time 扩到多节)。
+ *
+ * time 节分钟精度是刻意的:模型不需要秒,而快照在同一分钟内稳定,sidecar
+ * 的 merge-patch diff 对连续轮次就是零 token 空转;跨分钟只追加一个几
+ * token 的尾部补丁,系统提示词前缀保持字节稳定(cache 净收益)。其余各节
+ * (mode/permissions/skills)同理——慢变,变了才补一个小补丁。
+ */
+export function buildWorldState(input = {}) {
+    const now = input.now ?? new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    const local = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}` +
+        `T${pad(now.getHours())}:${pad(now.getMinutes())}`;
+    const state = {
+        time: {
+            local,
+            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            weekday: WEEKDAYS_ZH[now.getDay()],
+        },
+    };
+    if (input.mode) {
+        state.mode = { name: input.mode };
+    }
+    if (input.permissions) {
+        state.permissions = {
+            approval: input.permissions.approval,
+            sandbox: {
+                enabled: input.permissions.sandbox.enabled,
+                writableRoots: input.permissions.sandbox.writableRoots,
+                network: input.permissions.sandbox.network,
+            },
+        };
+    }
+    if (input.skills) {
+        state.skills = {
+            conditions: input.skills.conditions,
+            exclude: input.skills.exclude,
+        };
+    }
+    if (input.extra) {
+        Object.assign(state, input.extra);
+    }
+    return state;
+}
+export async function streamCoreLoopTurn(options) {
+    const { supervisor, signal } = options;
+    if (signal?.aborted) {
+        throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+    const request = {
+        provider: options.provider,
+        model: options.model,
+        baseUrl: options.baseUrl,
+        apiKey: options.apiKey,
+        temperature: options.temperature,
+        systemPrompt: options.systemPrompt,
+        compat: options.compat,
+        presets: options.presets,
+        ...(options.reasoningEffort ? { reasoningEffort: options.reasoningEffort } : {}),
+        chatId: options.chatId,
+        recordId: options.recordId,
+        resume: options.resume,
+        useCoreLoop: true,
+        // Stream every CoreLoop round's display text so the UI can interleave
+        // reasoning, tool cards, and replies in call order. Retry drafts still
+        // live in the durable record/trace; the renderer places each round's
+        // narration next to the tools that followed it.
+        contentMode: 'all',
+        toolsViaHost: true,
+        streamRawChunks: options.streamRawChunks,
+        // W8: advertise the sidecar-hosted ask_user tool; the desktop answers
+        // `ask_user.request` reverse calls with the renderer question card
+        // (AskUserModalHost). Under toolsViaHost the sidecar intercepts
+        // ask_user locally, so it never reaches the host's tool.invoke.
+        // 4.6a: background task streams opt out (options.askUser === false).
+        askUser: options.askUser ?? true,
+        toolContext: options.toolContext,
+        // Parity with the TS loop: the four anti-hallucination guards (data-need
+        // routing, deferred/claimed retry, grounding judge, narration round) run
+        // as CoreLoop hooks on the sidecar side.
+        antiHallucination: true,
+        skills: options.skills,
+        worldState: options.worldState,
+        execSandbox: options.execSandbox,
+        approval: options.approval,
+        orchestration: options.orchestration,
+        subagent: options.subagent,
+        budgetTokens: options.budgetTokens,
+        messages: options.messages.map((m) => {
+            // W6-3: a message carrying images is sent as structured `parts` (the
+            // sidecar treats `parts` as authoritative, `content` as its text
+            // projection). Text-only messages keep the legacy `content` shorthand.
+            const base = {
+                role: m.role,
+                content: m.content,
+                name: m.name,
+                toolCallId: m.toolCallId,
+            };
+            if (m.images && m.images.length > 0) {
+                return {
+                    ...base,
+                    parts: [
+                        { type: 'text', text: m.content },
+                        ...m.images.map((img) => ({
+                            type: 'image',
+                            data: img.data,
+                            mediaType: img.mediaType,
+                        })),
+                    ],
+                };
+            }
+            return base;
+        }),
+        tools: options.tools.map((t) => ({
+            type: 'function',
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: t.inputSchema ?? { type: 'object', properties: {} },
+            },
+        })),
+    };
+    // Track in-flight tool calls so results can be paired with their arguments
+    // (the start notification carries them, the result notification does not).
+    const pendingCalls = new Map();
+    return await new Promise((resolve, reject) => {
+        let streamIdRef = null;
+        let settled = false;
+        let cancelling = false;
+        let abortGraceTimer = null;
+        const onAbort = () => {
+            if (settled || cancelling)
+                return;
+            cancelling = true;
+            if (streamIdRef) {
+                void supervisor.cancelChat(streamIdRef);
+            }
+            // Don't reject yet: the sidecar answers the cancel with a stream.done
+            // carrying status 'cancelled' AND the traceId — resolving on it lets
+            // the router persist the partial trace (cancelled turns are dogfood
+            // signal too). Only if the done never arrives do we settle bare.
+            abortGraceTimer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(new DOMException('The operation was aborted.', 'AbortError'));
+            }, CANCEL_GRACE_MS);
+        };
+        signal?.addEventListener('abort', onAbort);
+        const cleanup = () => {
+            signal?.removeEventListener('abort', onAbort);
+            if (abortGraceTimer)
+                clearTimeout(abortGraceTimer);
+            activeCoreLoopStreams.delete(options.chatId);
+        };
+        void supervisor
+            .streamChat(request, {
+            onChunk: (chunk) => {
+                // The user cancelled — swallow any in-flight deltas while we wait
+                // for the sidecar's cancelled done.
+                if (cancelling)
+                    return;
+                if (chunk.delta) {
+                    options.onText(chunk.delta);
+                }
+                if (chunk.reasoningDelta) {
+                    options.onReasoning?.(chunk.reasoningDelta);
+                }
+                if (chunk.toolCall) {
+                    pendingCalls.set(chunk.toolCall.id, {
+                        name: chunk.toolCall.name,
+                        arguments: chunk.toolCall.arguments ?? {},
+                    });
+                    options.onToolStart?.({
+                        id: chunk.toolCall.id,
+                        tool: chunk.toolCall.name,
+                        arguments: chunk.toolCall.arguments ?? {},
+                    });
+                }
+                if (chunk.toolResult) {
+                    const started = pendingCalls.get(chunk.toolResult.id);
+                    pendingCalls.delete(chunk.toolResult.id);
+                    options.onToolAction?.({
+                        id: chunk.toolResult.id,
+                        tool: chunk.toolResult.name,
+                        arguments: started?.arguments ?? {},
+                        success: chunk.toolResult.success,
+                        result: chunk.toolResult.resultPreview,
+                        error: chunk.toolResult.error,
+                        durationMs: chunk.toolResult.durationMs,
+                        sandbox: chunk.toolResult.sandbox,
+                    });
+                }
+                if (chunk.notice) {
+                    options.onNotice?.(chunk.notice.kind, chunk.notice);
+                }
+                if (chunk.rawChunk) {
+                    options.onRawChunk?.(chunk.rawChunk);
+                }
+            },
+            onDone: (done) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve({
+                    status: done.status ?? (done.cancelled ? 'cancelled' : done.ok ? 'completed' : 'failed'),
+                    reason: done.reason ?? (done.cancelled ? 'aborted_by_user' : undefined),
+                    traceId: done.traceId,
+                    usage: done.usage,
+                });
+            },
+            onChildEvent: (event) => {
+                if (settled || cancelling)
+                    return;
+                options.onChildEvent?.(event);
+            },
+            onError: (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                // Carry the sidecar trace id on the rejection so the router can
+                // persist the partial trace — failed turns are the ones dogfooding
+                // most needs to inspect.
+                const failure = new Error(`coreloop stream failed: ${err.kind}: ${err.message}`);
+                if (err.traceId)
+                    failure.traceId = err.traceId;
+                reject(failure);
+            },
+        })
+            .then((streamId) => {
+            streamIdRef = streamId;
+            activeCoreLoopStreams.set(options.chatId, streamId);
+            options.onStreamId?.(streamId);
+            if (signal?.aborted && !settled)
+                onAbort();
+        })
+            .catch((err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(err);
+        });
+    });
+}

package/dist/local-backend/deferred-detector.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Detects "deferred-execution hallucination" — the failure mode where the LLM
+ * narrates an upcoming action (e.g. "现在轮询结果。" / "I'll now poll…") but
+ * does NOT actually emit the corresponding tool_call, leaving the stream
+ * dangling.
+ *
+ * The in-turn retry machinery that used to act on this signal moved to the
+ * sidecar's Python AntiHallucinationHooks (2026-08-26, TS loop deleted). The
+ * surviving caller is `detectToolDenialInHistory` in the router: deferred-
+ * execution residue in *history* counts as prompt pollution and triggers the
+ * tool reality-check preamble on later turns.
+ *
+ * Pure function (no `this`, no I/O) for unit-testability.
+ */
+export declare function detectDeferredExecution(text: string): boolean;

package/dist/local-backend/deferred-detector.js

@@ -0,0 +1,124 @@
+/**
+ * Detects "deferred-execution hallucination" — the failure mode where the LLM
+ * narrates an upcoming action (e.g. "现在轮询结果。" / "I'll now poll…") but
+ * does NOT actually emit the corresponding tool_call, leaving the stream
+ * dangling.
+ *
+ * The in-turn retry machinery that used to act on this signal moved to the
+ * sidecar's Python AntiHallucinationHooks (2026-08-26, TS loop deleted). The
+ * surviving caller is `detectToolDenialInHistory` in the router: deferred-
+ * execution residue in *history* counts as prompt pollution and triggers the
+ * tool reality-check preamble on later turns.
+ *
+ * Pure function (no `this`, no I/O) for unit-testability.
+ */
+const INTENT_VERBS = [
+    // 行动类
+    '执行', '调用', '运行', '发起', '开始', '继续',
+    // 读类
+    '搜索', '查找', '查询', '检查', '获取', '读取', '查看', '列出',
+    // 探查类
+    '探查', '探测', '处理', '试一下', '试试',
+    // 异步 follow-up 类（看到这些词意味着模型答应了"再调一次工具"）
+    '轮询', '等待', '等结果', '等待结果', '查看结果', '看结果',
+    '跟进', '跟踪', '监控', '确认结果',
+];
+const VERB_ALT = INTENT_VERBS.join('|');
+// 宽松主语（用于初筛 hasIntent）。允许 '然后' / '下一步' 这些过渡词；rule ③
+// 用更严格的子集避免误伤过去时陈述。
+const LOOSE_SUBJECTS = [
+    '现在', '接下来', '下一步', '然后',
+    // '我' 必须带未来时态修饰词。
+    '我(将|会|要|马上|立刻|想|想要|准备|现在|即将)', '我来', '我去',
+    '马上', '即将', '正要', '正在', '正',
+    '准备', '即刻',
+];
+const LOOSE_SUBJECT_ALT = LOOSE_SUBJECTS.join('|');
+const CN_INTENT_LOOSE = new RegExp(`(${LOOSE_SUBJECT_ALT})[^\\n。！？]{0,10}(${VERB_ALT})`);
+// 严格主语集合：只接受真正暗示"未来 / 马上"语态的词。
+//   - 不含 '然后' / '下一步'：这些既可能是计划也可能是回顾，rule ③ 会过紧。
+//   - 不含 '正' / '继续'：歧义太大。
+const STRICT_FUTURE_SUBJECTS = [
+    '现在', '接下来', '马上', '即将', '正要', '正在', '准备', '即刻',
+    '我(将|会|要|马上|立刻|想|想要|准备|现在|即将)', '我来', '我去',
+];
+const STRICT_SUBJECT_ALT = STRICT_FUTURE_SUBJECTS.join('|');
+// rule ③ 专用：subject ─ {0~10 字非句号}（**不含**了/过/完，否则中间夹个
+// 过去时标记就该放过）─ verb ─ **lookahead**：verb 后面不能立刻接 了/过/完/毕
+const CN_INTENT_STRICT = new RegExp(`(${STRICT_SUBJECT_ALT})[^\\n。！？了过完]{0,10}(${VERB_ALT})(?![了过完毕])`);
+// 英文：把动词的词干提出来，允许 -ing / -ed / -s 后缀；也允许 modal 和 verb
+// 之间夹一个 adverb（"I'll now poll" / "I'll just go and poll" 这种）。
+const EN_VERB_STEM = '(?:execute|call|run|invoke|search|query|fetch|read|list|poll|wait|follow\\s*up)';
+const EN_VERB = `${EN_VERB_STEM}(?:ing|ed|s)?`;
+const EN_ADVERB = '(?:now|just|then|first|go ahead and|now please)';
+const EN_PATTERNS = [
+    new RegExp(`now\\s+${EN_VERB}\\b`, 'i'),
+    new RegExp(`let me\\s+(?:${EN_ADVERB}\\s+)?${EN_VERB}\\b`, 'i'),
+    new RegExp(`(?:i'?ll|i will|i'?m going to|i'?m about to)\\s+(?:${EN_ADVERB}\\s+)?${EN_VERB}\\b`, 'i'),
+    new RegExp(`(?:preparing|about)\\s+to\\s+${EN_VERB}\\b`, 'i'),
+];
+// ─── 澄清 / 条件式承诺收尾 ──────────────────────────────────────────────
+// 真实误判 case（2026-07-05 日志）：模型收尾写
+//   "告诉我你现在想做什么，我来帮你执行。"
+//   "告诉我文件路径和需求，我立刻执行。"
+// 这是在向用户征询输入、承诺"拿到信息后再执行"——合法的对话终点（等用户），
+// 不是 deferred-execution。旧规则 ③ 命中"我来…执行"强制重试，模型换个说法
+// 还是澄清式收尾，再次误判，两轮重试直接把 token 预算烧爆。
+//
+// 判定：征询/条件标记出现在意图动词**之前**（"告诉我 X，我就执行"），或整句
+// 只有征询没有意图动词（"你可以告诉我："）。标记在动词之后不豁免——
+// "我现在执行，如果失败会重试。"仍然算 deferred。
+const CONDITIONAL_OFFER_MARKER = new RegExp('(告诉我|告知我|请提供|请给出|请发|发给我|你可以|您可以|如果|若(你|您)|只要|一旦|' +
+    '等(你|您)|需要(你|您)|你(想|要|希望|确认)|您(想|要|希望|确认)|' +
+    'let me know|tell me|if you|once you|provide|send me|share)', 'i');
+function isConditionalOffer(sentence) {
+    if (!sentence)
+        return false;
+    const marker = CONDITIONAL_OFFER_MARKER.exec(sentence);
+    if (!marker)
+        return false;
+    const verb = new RegExp(VERB_ALT).exec(sentence);
+    if (!verb)
+        return true;
+    return marker.index < verb.index;
+}
+export function detectDeferredExecution(text) {
+    if (!text)
+        return false;
+    const trimmed = text.trim();
+    // 6 字符门槛：避免极端短句（"好的"）触发，又能放过"现在轮询" 4 字 + 标点。
+    if (trimmed.length < 6)
+        return false;
+    const hasIntent = CN_INTENT_LOOSE.test(trimmed) || EN_PATTERNS.some((p) => p.test(trimmed));
+    // 收尾标点：省略号 / 半角省略号 / 全角省略号 / 冒号 — 都意味着话没说完
+    const trailingEllipsis = /(\.{3,}|…|……)\s*$/.test(trimmed);
+    const trailingColon = /[:：]\s*$/.test(trimmed);
+    const lastSentence = trimmed.split(/[\n。！？!?]/).filter(Boolean).pop()?.trim() ?? '';
+    const lastEllipsis = /(\.{3,}|…|……)\s*$/.test(lastSentence);
+    const lastColon = /[:：]\s*$/.test(lastSentence);
+    const lastIntentLoose = CN_INTENT_LOOSE.test(lastSentence) ||
+        EN_PATTERNS.some((p) => p.test(lastSentence));
+    const lastIntentStrict = CN_INTENT_STRICT.test(lastSentence) ||
+        EN_PATTERNS.some((p) => p.test(lastSentence));
+    const looksOpenEnded = trailingEllipsis || trailingColon || lastEllipsis || lastColon;
+    // 澄清式收尾豁免：最后一句是"给我信息 → 我再执行"的条件承诺，
+    // 模型在等用户输入，不是把执行"说"完就跑。
+    const lastConditionalOffer = isConditionalOffer(lastSentence);
+    // ① 意图词 + 任一开放式收尾：高置信，直接判 deferred
+    if (hasIntent && looksOpenEnded && !lastConditionalOffer)
+        return true;
+    // ② 最后一句既有意图词又有省略号 / 冒号：高置信
+    if (lastIntentLoose && (lastEllipsis || lastColon) && !lastConditionalOffer)
+        return true;
+    // ③ **最后一句**用**严格**未来主语 + 意图动词、且 verb 后不接过去时
+    //    标记 (了/过/完/毕) → 即使尾巴是句号也算 deferred。
+    //    历史 bug 复现："任务已排队……现在轮询结果。" 用句号收尾骗过旧规则。
+    //    严格主语保证不误伤 "然后调用了 X" 这种回顾叙述。
+    if (lastIntentStrict && !lastConditionalOffer)
+        return true;
+    // ④ 纯省略号收尾且整段很短（< 400 字）：保守兜底；防止"很长的最终结论 …
+    //    末尾哲学省略号"被误判
+    if ((trailingEllipsis || lastEllipsis) && trimmed.length < 400)
+        return true;
+    return false;
+}

package/dist/local-backend/history-helper.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure helper for the conversation-history assembly in `router.ts`.
+ *
+ * The send path inserts the current user message into the store *before*
+ * building the model context, so the history window must drop that copy to
+ * avoid the model seeing it twice (it is appended explicitly as the final
+ * user message). The drop must be by id, not by tail position: the previous
+ * assistant reply persists asynchronously at stream end (createdAt = write
+ * time), so a fast follow-up message lands *before* it and the tail becomes
+ * `[..., u_new, a_prev]` — a positional pop then misses the duplicate
+ * (observed in the 2026-08-28 E2E request recording: every multi-turn user
+ * message was injected twice).
+ *
+ * The regenerate path inserts nothing; its truncation guarantees the
+ * triggering user message is the tail, so it keeps the positional pop.
+ *
+ * This module is pure so it can be unit-tested under plain Node/vitest —
+ * `router.ts` itself imports `better-sqlite3` via `storage`, which is
+ * compiled against Electron's ABI and can't load outside Electron.
+ */
+export interface HistoryMessageLike {
+    id: string;
+    role: string;
+}
+/**
+ * @param historyAsc Chat history, chronologically ascending (oldest first).
+ * @param currentUserMessageId Id of the just-inserted user message on the
+ *   send path; `undefined` on the regenerate path.
+ */
+export declare function dropCurrentUserMessage<T extends HistoryMessageLike>(historyAsc: T[], currentUserMessageId: string | undefined): T[];

package/dist/local-backend/history-helper.js

@@ -0,0 +1,34 @@
+/**
+ * Pure helper for the conversation-history assembly in `router.ts`.
+ *
+ * The send path inserts the current user message into the store *before*
+ * building the model context, so the history window must drop that copy to
+ * avoid the model seeing it twice (it is appended explicitly as the final
+ * user message). The drop must be by id, not by tail position: the previous
+ * assistant reply persists asynchronously at stream end (createdAt = write
+ * time), so a fast follow-up message lands *before* it and the tail becomes
+ * `[..., u_new, a_prev]` — a positional pop then misses the duplicate
+ * (observed in the 2026-08-28 E2E request recording: every multi-turn user
+ * message was injected twice).
+ *
+ * The regenerate path inserts nothing; its truncation guarantees the
+ * triggering user message is the tail, so it keeps the positional pop.
+ *
+ * This module is pure so it can be unit-tested under plain Node/vitest —
+ * `router.ts` itself imports `better-sqlite3` via `storage`, which is
+ * compiled against Electron's ABI and can't load outside Electron.
+ */
+/**
+ * @param historyAsc Chat history, chronologically ascending (oldest first).
+ * @param currentUserMessageId Id of the just-inserted user message on the
+ *   send path; `undefined` on the regenerate path.
+ */
+export function dropCurrentUserMessage(historyAsc, currentUserMessageId) {
+    if (currentUserMessageId) {
+        return historyAsc.filter((item) => item.id !== currentUserMessageId);
+    }
+    if (historyAsc.length > 0 && historyAsc[historyAsc.length - 1].role === 'user') {
+        return historyAsc.slice(0, -1);
+    }
+    return historyAsc;
+}

package/dist/local-backend/interrupted-helper.d.ts

@@ -0,0 +1,29 @@
+/**
+ * W7-1: pure helper for the interrupted-turn contract in `router.ts`.
+ *
+ * A turn whose process died mid-stream (crash / kill / lost stream) never
+ * reaches the code that persists `completionStatus`, so the crash signature
+ * is the surviving `turn_active:{chatId}` marker in `settings_kv` — written
+ * before the stream starts, cleared only after the terminal assistant
+ * message persists. User-cancelled and failed turns are settled states the
+ * live process DID record: their marker is cleared and their assistant
+ * message carries an explicit `completionStatus`, so neither is reported
+ * here. Pure so it is unit-testable — `storage/index.ts` can't load under
+ * plain Node/vitest (`better-sqlite3` is compiled against Electron's ABI).
+ */
+export interface InterruptedTurnInput {
+    /** The `turn_active` marker survived — a turn began and never settled. */
+    turnActive: boolean;
+    /** A stream for this chat is live in THIS process right now. */
+    streamActive: boolean;
+    /** Role of the chat's newest persisted message, or null on an empty chat. */
+    lastMessageRole: string | null;
+}
+/**
+ * Interrupted ⟺ marker present, no live stream, and the store does not
+ * already end on an assistant reply. The role check dismisses the stale
+ * marker left by a crash between the assistant write and the marker clear
+ * (adjacent statements, but the clear is deliberately last): the reply's
+ * presence proves the turn settled.
+ */
+export declare function detectInterruptedTurn(input: InterruptedTurnInput): boolean;

package/dist/local-backend/interrupted-helper.js

@@ -0,0 +1,25 @@
+/**
+ * W7-1: pure helper for the interrupted-turn contract in `router.ts`.
+ *
+ * A turn whose process died mid-stream (crash / kill / lost stream) never
+ * reaches the code that persists `completionStatus`, so the crash signature
+ * is the surviving `turn_active:{chatId}` marker in `settings_kv` — written
+ * before the stream starts, cleared only after the terminal assistant
+ * message persists. User-cancelled and failed turns are settled states the
+ * live process DID record: their marker is cleared and their assistant
+ * message carries an explicit `completionStatus`, so neither is reported
+ * here. Pure so it is unit-testable — `storage/index.ts` can't load under
+ * plain Node/vitest (`better-sqlite3` is compiled against Electron's ABI).
+ */
+/**
+ * Interrupted ⟺ marker present, no live stream, and the store does not
+ * already end on an assistant reply. The role check dismisses the stale
+ * marker left by a crash between the assistant write and the marker clear
+ * (adjacent statements, but the clear is deliberately last): the reply's
+ * presence proves the turn settled.
+ */
+export function detectInterruptedTurn(input) {
+    if (!input.turnActive || input.streamActive)
+        return false;
+    return input.lastMessageRole !== 'assistant';
+}

package/dist/local-backend/live-stream.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 运行中回合的「实时快照」注册表 —— 让 renderer 在切走再切回时能把正在
+ * 流式的回合重新接上（显示运行状态 + 已产出的部分内容 / 工具卡片 / 时间线）。
+ *
+ * 背景：AgentChatView 卸载时不再取消回合（回合不因切页而暂停），但该回合
+ * 的 SSE 事件只会流向当初发起 fetch 的那个组件；切回后的新组件拿不到这些
+ * 事件，只能靠轮询本注册表把「运行中 + 部分产出」恢复出来。
+ *
+ * 设计：注册表只存「正在运行」的回合。router 的 handleCoreLoopTurn 在
+ * 流开始前 register、每个产出点更新 content、结束（落库后）立即 remove。
+ * executedActions / timeline / children 三个字段存的是 router 里同名的
+ * 活数组引用（appendTimelineDelta / syncTimelineTools / onToolAction 都
+ * 原地 mutate），因此 GET 序列化时自然读到最新状态，无需逐事件拷贝。
+ */
+import type { PersistedTurnBlock } from './turn-timeline.js';
+export interface LiveStreamState {
+    chatId: string;
+    status: 'running' | 'completed' | 'cancelled' | 'failed';
+    /** 已产出的助手文本（部分）。 */
+    content: string;
+    /** 已产出的工具调用卡片（原地 mutate 的活数组）。 */
+    executedActions: Array<Record<string, unknown>>;
+    /** 调用顺序时间线（原地 mutate 的活数组）。 */
+    timeline: PersistedTurnBlock[];
+    /** 编排子代理生命周期事件（按到达顺序累积）。 */
+    children: Array<Record<string, unknown>>;
+}
+export declare function registerLiveStream(chatId: string, refs: {
+    executedActions: Array<Record<string, unknown>>;
+    timeline: PersistedTurnBlock[];
+    children: Array<Record<string, unknown>>;
+}): LiveStreamState;
+export declare function getLiveStream(chatId: string): LiveStreamState | undefined;
+export declare function removeLiveStream(chatId: string): void;
+/** 供测试 / 诊断使用。 */
+export declare function liveStreamCount(): number;

package/dist/local-backend/live-stream.js

@@ -0,0 +1,23 @@
+const liveStreams = new Map();
+export function registerLiveStream(chatId, refs) {
+    const state = {
+        chatId,
+        status: 'running',
+        content: '',
+        executedActions: refs.executedActions,
+        timeline: refs.timeline,
+        children: refs.children,
+    };
+    liveStreams.set(chatId, state);
+    return state;
+}
+export function getLiveStream(chatId) {
+    return liveStreams.get(chatId);
+}
+export function removeLiveStream(chatId) {
+    liveStreams.delete(chatId);
+}
+/** 供测试 / 诊断使用。 */
+export function liveStreamCount() {
+    return liveStreams.size;
+}

package/dist/local-backend/llm-diagnose.d.ts

@@ -0,0 +1,37 @@
+/**
+ * W-llm-diagnose: LLM link diagnosis orchestration.
+ *
+ * The settings page's "诊断" button runs a battery of probes against the
+ * configured provider: DNS resolution, TCP connect, TLS handshake, HTTP
+ * GET /models, and a minimal chat completion. Each probe is timed and
+ * classified so the UI can render a per-step verdict.
+ *
+ * The diagnosis runs in the host process (not the sidecar) because it
+ * needs to observe the *host's* network path — the sidecar's sandboxed
+ * view would hide proxy misconfigurations that the user needs to see.
+ */
+export interface DiagnoseStep {
+    name: string;
+    ok: boolean;
+    durationMs: number;
+    detail: string;
+}
+export interface DiagnoseResult {
+    ok: boolean;
+    steps: DiagnoseStep[];
+    /** Ambient proxy endpoints detected on the host (env + system). */
+    ambientProxies: string[];
+    /** User-facing hint when a step fails, translated from the raw error. */
+    hint: string | null;
+}
+/**
+ * Run the full diagnosis battery against `baseUrl` with `apiKey`.
+ * `model` is used for the chat-completion probe; when omitted the
+ * battery stops after the HTTP probe.
+ */
+export declare function diagnoseLlmConnection(options: {
+    baseUrl: string;
+    apiKey?: string;
+    model?: string;
+    timeoutMs?: number;
+}): Promise<DiagnoseResult>;