@steerable/agent-shell 0.6.15

package/dist/local-backend/prompt-builder.js

@@ -0,0 +1,246 @@
+/**
+ * SystemPromptBuilder for the local desktop agent.
+ *
+ * Assembles a system prompt by loading skill modules from
+ * `src/local-backend/skills/<dir>/SKILL.md` and concatenating their bodies
+ * in directory-name order. Skills can be filtered by runtime conditions
+ * (e.g. `tool:<tool_name>`) and trimmed by character budget when too
+ * large (lowest-priority skills are dropped first).
+ *
+ * This is the TS counterpart of
+ * 上游 Python 服务的 SystemPromptBuilder。
+ */
+import path from 'node:path';
+import { loadSkills } from './skill-loader.js';
+import { isSkillPinned } from './agent-capability.js';
+import { getBrand } from '../brand.js';
+const FALLBACK_PROMPT = (() => {
+    const brand = getBrand();
+    return [
+        '# 角色',
+        '',
+        `你是 ${brand.agentName}，${brand.tagline}，运行在用户自己的 Windows / macOS / Linux 机器上。`,
+        '通过工具直接操作用户的本地环境（shell、文件、当前产品安装的场景工具等）。用中文回复。',
+        '不要凭空编造任何工具返回值。',
+    ].join('\n');
+})();
+const DEFAULT_CHAR_BUDGET = 60_000;
+/**
+ * Derive condition strings from the set of tool names available this turn.
+ *
+ *   ['some_pack_tool', 'local_exec_shell']
+ *   →  ['tool:some_pack_tool', 'tool:local_exec_shell']
+ */
+export function conditionsFromTools(toolNames, autoHasTools = true) {
+    const out = new Set();
+    let hasAny = false;
+    for (const name of toolNames) {
+        if (!name)
+            continue;
+        out.add(`tool:${name}`);
+        hasAny = true;
+    }
+    if (autoHasTools && hasAny)
+        out.add('has-tools');
+    return out;
+}
+/**
+ * Assemble the final system prompt:
+ *
+ *   [persona preamble]?       (agent role / DSL)
+ *   [chat-level prompt]?      (per-chat custom override)
+ *   [skill 1 body]
+ *   ...
+ *   [skill N body]
+ *   [reality check]?          (turn-specific tool list / pollution warning)
+ */
+export async function buildSystemPrompt(options = {}) {
+    const conditions = new Set(options.conditions ?? []);
+    if (options.toolNames) {
+        for (const c of conditionsFromTools(options.toolNames, options.autoHasTools ?? true)) {
+            conditions.add(c);
+        }
+    }
+    let modules = await loadSkills({
+        conditions,
+        ignoreConditions: options.ignoreConditions,
+        excludeSkillNames: options.excludeSkillNames,
+        skillsDir: options.skillsDir,
+    });
+    const droppedModules = [];
+    // 智能体勾选的技能:再取一次全量(无视条件)捞出勾选项并并入。追加在条件
+    // 命中的模块之后——recency 更强,且这些是用户明确为该智能体选的。
+    const pinnedAliases = Array.from(options.pinnedSkillNames ?? []);
+    const pinnedDirNames = new Set();
+    if (pinnedAliases.length > 0) {
+        const all = await loadSkills({
+            ignoreConditions: true,
+            excludeSkillNames: options.excludeSkillNames,
+            skillsDir: options.skillsDir,
+        });
+        const present = new Set(modules.map((m) => m.dirName));
+        for (const module of all) {
+            if (!isSkillPinned(module, pinnedAliases))
+                continue;
+            pinnedDirNames.add(module.dirName);
+            if (!present.has(module.dirName))
+                modules.push(module);
+        }
+    }
+    // A6 分层披露:catalog 层技能的正文不再进系统提示词——sidecar 注入目录
+    // 清单,模型调 `skill` 工具按需加载(用户显式 "/技能名" 走 router 的一次性
+    // 消息注入,也不经过这里)。勾选的技能是例外:用户为这个智能体点名了,正文
+    // 直接常驻,不必等模型自己去目录里找。
+    if (options.eagerOnly) {
+        modules = modules.filter((m) => m.layer === 'eager' || pinnedDirNames.has(m.dirName));
+    }
+    if (modules.length === 0) {
+        return {
+            prompt: assembleFinal({
+                personaPreamble: options.personaPreamble ?? '',
+                chatSystemPrompt: options.chatSystemPrompt ?? '',
+                body: FALLBACK_PROMPT,
+                realityCheckSuffix: options.realityCheckSuffix ?? '',
+            }),
+            modules,
+            droppedModules,
+            conditions: Array.from(conditions),
+        };
+    }
+    const charBudget = options.charBudget ?? DEFAULT_CHAR_BUDGET;
+    modules = applyBudget(modules, charBudget, droppedModules);
+    // 用户显式指定的 MCP 工具（"/mcp__srv__tool" 触发）：合成一个指令模块放到
+    // 最末尾（recency 最强）。在 applyBudget 之后追加，天然免疫预算裁剪。与
+    // tool-router 的动态工具命名 mcp__<serverKey>__<toolName> 一致，首轮
+    // tool_choice='required' 由 router 的回合路由负责施加。
+    if (options.forcedMcpTool) {
+        modules.push(buildForcedMcpToolModule(options.forcedMcpTool));
+    }
+    // 品牌占位符（{agentName} 等）由产品注入的品牌渲染——shell 技能正文
+    // 保持产品中立（3.2 中性化，见 skills/00-identity）。
+    const body = modules.map((m) => renderSkillContent(m, brandSkillVars())).join('\n\n');
+    return {
+        prompt: assembleFinal({
+            personaPreamble: options.personaPreamble ?? '',
+            chatSystemPrompt: options.chatSystemPrompt ?? '',
+            body,
+            realityCheckSuffix: options.realityCheckSuffix ?? '',
+        }),
+        modules,
+        droppedModules,
+        conditions: Array.from(conditions),
+    };
+}
+/** 显式指定 MCP 工具的末尾指令模块（合成 SkillModule，不来自 skill-loader）。 */
+function buildForcedMcpToolModule(t) {
+    const content = t.available
+        ? [
+            `# ⚡ 本轮指定 MCP 工具（最高优先级）`,
+            ``,
+            `用户通过 \`/${t.token}\` 显式指定了 MCP 工具 \`${t.toolName}\`` +
+                `${t.serverName ? `（来自服务「${t.serverName}」）` : ''}` +
+                `${t.description ? `，功能：${t.description}` : ''}。本轮规则：`,
+            `1. 第一步必须调用工具 \`${t.token}\`（发起 tool_call），参数根据用户问题构造；`,
+            `2. 回答必须以该工具本次返回的数据为准——不得编造结果，也不得用历史/缓存数据冒充本次调用；`,
+            `3. 若工具调用失败，如实报告错误信息，不要假装执行成功；`,
+            `4. 用户问题中超出该工具能力的部分，可用其他工具或知识补充，但要明确区分来源。`,
+        ].join('\n')
+        : [
+            `# ⚡ 本轮指定 MCP 工具（当前不可用）`,
+            ``,
+            `用户通过 \`/${t.token}\` 显式指定的 MCP 工具当前不可用（服务未启用、未连接成功或工具不存在）。本轮规则：`,
+            `1. **不要**假装调用该工具，也不要编造它的返回结果；`,
+            `2. 直接告知用户该工具不可用，建议其在「设置 → MCP 服务」中检查该服务的启用状态并重试「测试连接」；`,
+            `3. 其余可回答的部分用中文正常回答。`,
+        ].join('\n');
+    return {
+        name: `forced-mcp-tool`,
+        displayName: '',
+        description: t.description,
+        priority: 999,
+        tags: [],
+        conditions: [],
+        match: 'any',
+        layer: 'eager',
+        modelInvocable: true,
+        content,
+        dirName: `forced-mcp:${t.token}`,
+        skillsDir: '',
+    };
+}
+/**
+ * 品牌占位符变量：技能正文里的 `{agentName}` / `{brandDisplayName}` /
+ * `{brandTagline}` 渲染为当前产品注入的品牌（brand.ts；未注入 = shell
+ * 中性默认）。eager 系统提示词路径统一注入；包技能同理可用。
+ */
+export function brandSkillVars() {
+    const brand = getBrand();
+    return {
+        agentName: brand.agentName,
+        brandDisplayName: brand.displayName,
+        brandTagline: brand.tagline,
+    };
+}
+/** 技能正文渲染:把 `{scripts}` 及额外占位符解析为绝对路径。 */
+export function renderSkillContent(m, vars) {
+    const scriptsPath = path.join(m.skillsDir, m.dirName, 'scripts');
+    // Replace {scripts}/ or {scripts}\ with the correct path to ensure uniform slashes
+    let content = m.content;
+    content = content.replace(/\{scripts\}[\/\\]/g, scriptsPath + path.sep);
+    content = content.replace(/\{scripts\}/g, scriptsPath);
+    if (vars) {
+        for (const [key, value] of Object.entries(vars)) {
+            content = content.replaceAll(`{${key}}`, value);
+        }
+    }
+    return content;
+}
+/** 用户显式指定技能的优先级指令头，渲染在该技能内容之前。 */
+export function buildForcedSkillHeader(m) {
+    const label = m.displayName || m.name;
+    return [
+        `# ⚡ 本轮指定技能（最高优先级）`,
+        ``,
+        `用户通过 \`/${label}\` 显式指定了本技能。本轮规则：`,
+        `1. 必须优先、严格地遵循本技能的流程、约束与工具选择来完成任务；`,
+        `2. 本技能与其他内嵌技能冲突时，**一律以本技能为准**；`,
+        `3. 除非本技能明确要求，**不要**改用其他工具来完成本技能已覆盖的任务；`,
+        `4. 只有本技能未覆盖的辅助步骤，才允许使用其他工具补充。`,
+    ].join('\n');
+}
+/**
+ * "/技能名" 触发的一次性注入文本(A6):指令头 + 技能正文,由 router 并入
+ * 本轮最后一条用户消息——不再塞系统提示词尾部(系统提示词保持稳定,是
+ * prompt cache 的净收益;历史消息里也不会残留技能正文)。
+ */
+export function buildForcedSkillMessage(m, vars) {
+    return `${buildForcedSkillHeader(m)}\n\n${renderSkillContent(m, vars)}`;
+}
+function applyBudget(modules, charBudget, droppedModules) {
+    const total = modules.reduce((sum, m) => sum + m.content.length, 0);
+    if (total <= charBudget)
+        return modules;
+    const byPriorityAsc = [...modules].sort((a, b) => a.priority - b.priority);
+    const dropped = new Set();
+    let excess = total - charBudget;
+    for (const m of byPriorityAsc) {
+        if (excess <= 0)
+            break;
+        dropped.add(m.name);
+        excess -= m.content.length;
+        droppedModules.push(m.name);
+    }
+    return modules.filter((m) => !dropped.has(m.name));
+}
+function assembleFinal(parts) {
+    const sections = [];
+    if (parts.personaPreamble.trim())
+        sections.push(parts.personaPreamble.trim());
+    if (parts.chatSystemPrompt.trim()) {
+        sections.push(`# 本次对话补充设定\n\n${parts.chatSystemPrompt.trim()}`);
+    }
+    sections.push(parts.body.trim());
+    if (parts.realityCheckSuffix.trim())
+        sections.push(parts.realityCheckSuffix.trim());
+    return sections.join('\n\n');
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Pure helper for the `/regenerate` route in `router.ts`.
+ *
+ * Regenerating an assistant reply means: find the user turn that prompted it,
+ * delete that assistant message and everything after it, then rerun as if
+ * that user turn just happened. This module only computes *which* text to
+ * re-run with — the actual deletion is DB I/O and stays in `router.ts` /
+ * `storage/index.ts` (which can't be unit-tested here: `better-sqlite3` is
+ * compiled against Electron's ABI and can't load under plain Node/vitest).
+ */
+export interface RegenerateMessageLike {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+}
+export type RegenerateResolution = {
+    ok: true;
+    userMessageText: string;
+} | {
+    ok: false;
+    reason: 'not_found' | 'not_assistant';
+};
+/**
+ * @param messagesAsc Full chat history, chronologically ascending (oldest first).
+ * @param targetMessageId The assistant message being regenerated.
+ */
+export declare function resolveRegenerateContext(messagesAsc: RegenerateMessageLike[], targetMessageId: string): RegenerateResolution;
+/**
+ * W5-2: the fork-point address for a non-destructive regenerate, as a
+ * user-message ordinal — the prompting user turn is the last user message
+ * before the target, i.e. (count of user messages before the target) - 1.
+ * The sidecar's `resolve_fork_seq(user_index=…)` resolves the same ordinal
+ * against the durable record (steer injections are a separate record kind,
+ * so user ordinals align between the two stores). Returns -1 when no user
+ * message precedes the target (the FALLBACK_TEXT case) — not addressable,
+ * the caller falls back to legacy truncate-and-rerun.
+ */
+export declare function resolveRegenerateForkOrdinal(messagesAsc: RegenerateMessageLike[], targetMessageId: string): number;
+export type RegenerateTruncatePlan = {
+    proceed: true;
+} | {
+    proceed: false;
+    message: string;
+};
+/**
+ * Whether regenerate may delete the target reply, given the fork attempt that
+ * was supposed to preserve it as a branch.
+ *
+ * A declined address is the protocol's documented fallback and proceeds. A fork
+ * that failed instead of answering revokes the permission to delete: the control
+ * offers regenerate as non-destructive, and truncating anyway would drop the
+ * reply's row and interleave the new one into the same record, with no branch and
+ * no notice. Refusing leaves the reply where the user can still see it and lets
+ * them retry once the sidecar answers again.
+ *
+ * @param fork `null` when no sidecar was attached, so no record existed to fork.
+ */
+export declare function planRegenerateTruncate(fork: {
+    ok: boolean;
+    declined?: boolean;
+    reason?: string;
+} | null): RegenerateTruncatePlan;

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

@@ -0,0 +1,75 @@
+/**
+ * Pure helper for the `/regenerate` route in `router.ts`.
+ *
+ * Regenerating an assistant reply means: find the user turn that prompted it,
+ * delete that assistant message and everything after it, then rerun as if
+ * that user turn just happened. This module only computes *which* text to
+ * re-run with — the actual deletion is DB I/O and stays in `router.ts` /
+ * `storage/index.ts` (which can't be unit-tested here: `better-sqlite3` is
+ * compiled against Electron's ABI and can't load under plain Node/vitest).
+ */
+const FALLBACK_TEXT = '请基于上一轮内容重新生成回复。';
+/**
+ * @param messagesAsc Full chat history, chronologically ascending (oldest first).
+ * @param targetMessageId The assistant message being regenerated.
+ */
+export function resolveRegenerateContext(messagesAsc, targetMessageId) {
+    const targetIdx = messagesAsc.findIndex((m) => m.id === targetMessageId);
+    if (targetIdx === -1) {
+        return { ok: false, reason: 'not_found' };
+    }
+    if (messagesAsc[targetIdx].role !== 'assistant') {
+        return { ok: false, reason: 'not_assistant' };
+    }
+    let precedingUserText = null;
+    for (let i = targetIdx - 1; i >= 0; i -= 1) {
+        if (messagesAsc[i].role === 'user') {
+            precedingUserText = messagesAsc[i].content.trim();
+            break;
+        }
+    }
+    return { ok: true, userMessageText: precedingUserText || FALLBACK_TEXT };
+}
+/**
+ * W5-2: the fork-point address for a non-destructive regenerate, as a
+ * user-message ordinal — the prompting user turn is the last user message
+ * before the target, i.e. (count of user messages before the target) - 1.
+ * The sidecar's `resolve_fork_seq(user_index=…)` resolves the same ordinal
+ * against the durable record (steer injections are a separate record kind,
+ * so user ordinals align between the two stores). Returns -1 when no user
+ * message precedes the target (the FALLBACK_TEXT case) — not addressable,
+ * the caller falls back to legacy truncate-and-rerun.
+ */
+export function resolveRegenerateForkOrdinal(messagesAsc, targetMessageId) {
+    const targetIdx = messagesAsc.findIndex((m) => m.id === targetMessageId);
+    if (targetIdx === -1)
+        return -1;
+    let ordinal = -1;
+    for (let i = 0; i < targetIdx; i += 1) {
+        if (messagesAsc[i].role === 'user')
+            ordinal += 1;
+    }
+    return ordinal;
+}
+/**
+ * Whether regenerate may delete the target reply, given the fork attempt that
+ * was supposed to preserve it as a branch.
+ *
+ * A declined address is the protocol's documented fallback and proceeds. A fork
+ * that failed instead of answering revokes the permission to delete: the control
+ * offers regenerate as non-destructive, and truncating anyway would drop the
+ * reply's row and interleave the new one into the same record, with no branch and
+ * no notice. Refusing leaves the reply where the user can still see it and lets
+ * them retry once the sidecar answers again.
+ *
+ * @param fork `null` when no sidecar was attached, so no record existed to fork.
+ */
+export function planRegenerateTruncate(fork) {
+    if (!fork || fork.ok || fork.declined)
+        return { proceed: true };
+    return {
+        proceed: false,
+        message: '无法重新生成：旧回复未能保留为分支，' +
+            `已放弃改动以免丢失它（${fork.reason ?? '未知原因'}）。请稍后重试。`,
+    };
+}

package/dist/local-backend/router.d.ts

@@ -0,0 +1,175 @@
+import { ToolRouter } from '../tool-router.js';
+import type { TaskService } from './task-service.js';
+export interface LocalBackendRequest {
+    method: string;
+    path: string;
+    body?: unknown;
+}
+export interface LocalBackendResponse<T = unknown> {
+    status: number;
+    data: T;
+}
+/**
+ * 流式响应中每条 SSE chunk 的 emit 回调。
+ * router 在生成过程中每收到一个新片段就立刻调用一次，
+ * 由 main 进程把它通过 IPC 事件推到渲染端，避免"齐了再吐"。
+ */
+export type StreamEmit = (sseChunk: string) => void;
+export interface StreamResult {
+    status: number;
+}
+/**
+ * 把 CoreLoop/LLM 的底层错误翻译成适合直接显示在助手消息里的中文提示。
+ * 原始错误仍保存在 messageMetadata.completionReason 里，便于排查。
+ */
+export declare function userFacingCoreLoopFailure(reason: string): string;
+export interface StreamOptions {
+    /**
+     * 取消信号。renderer 主动 Stop、窗口被销毁、应用退出时由 main 进程 abort。
+     * router 在每个 turn 开始前和每个 tool call 执行前检查；一旦 aborted 就
+     * 立刻停止调用 LLM / 工具，把已产出的内容落库后结束流。
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Out-of-band 事件推送回调。用于把"在请求生命周期之外"才出结果的事件（例如
+ * 后台 AI 标题生成）异步广播到所有 renderer。main.ts 注入 `webContents.send`
+ * 实现；未注入时事件被静默丢弃（CLI/test 场景下 router 仍可独立工作）。
+ */
+export type LocalBackendBroadcast = (eventName: string, payload: unknown) => void;
+export declare class LocalBackendRouter {
+    private readonly toolRouter;
+    private readonly broadcast;
+    /** 4.6a/4.6c：任务面板的路由入口（列表 + 合并/丢弃）。未注入时任务路由 503。 */
+    private readonly taskService;
+    constructor(toolRouter: ToolRouter, options?: {
+        broadcast?: LocalBackendBroadcast;
+        taskService?: TaskService;
+    });
+    handle(request: LocalBackendRequest): Promise<LocalBackendResponse>;
+    /**
+     * 对未显式实现的路由做"温柔降级"：GET 返回空集合/空对象，不让 UI 因 404 抛错跳到
+     * not-found；其他方法返回 success:true 让前端流程继续。所有兜底都在主进程终端
+     * 打印一条日志，方便后续按需补真实实现。
+     */
+    private fallbackResponse;
+    /**
+     * 真正流式：每个 SSE chunk 立刻通过 `emit` 推到 IPC 通道，避免"齐了再吐"。
+     * 不再返回 chunks 数组，main 进程只需关心最终 status。
+     *
+     * SSE 协议约定（与 web UI 现有 SSEParser/parseSSEData 对齐）：
+     * - 正文文本片段：`data: {"content":"..."}` 不带 event 行，前端在
+     *   `accumulatedContent += parsedData.content` 一行追加渲染。
+     * - 同步真实 messageId：`data: {"type":"message_id","messageId":"..."}`
+     * - 工具执行结果（无需用户确认）：`data: {"type":"executed_actions","actions":[...]}`
+     * - 错误：保留 `event:error` + `data: {"message":"..."}`（前端会忽略，但日志/未来 UI 用）
+     * - 结束：标准 SSE `[DONE]` 串。
+     */
+    handleStream(request: LocalBackendRequest, emit: StreamEmit, options?: StreamOptions): Promise<StreamResult>;
+    /**
+     * 后台异步生成 chat 标题。**完全 fire-and-forget**——不阻塞 `[DONE]`，
+     * 调用方只要 `void this.runTitleGenInBackground(...)` 就行。
+     *
+     * 设计取舍：
+     *   - 主对话的 LLM 调用没有 per-call 超时，也没有总时间预算——结束完全由模型
+     *     自己判断（不再 emit tool_calls = completed）。之前 title-gen 给 6-12s
+     *     单次超时，慢机器 / 冷模型经常拿不到结果就被掐。改成后台跑，**没有时间
+     *     压力**：60s 都能等，反正用户已经看到 [DONE]。
+     *   - 结果通过 `this.broadcast('chat-title-updated', ...)` 推到 renderer。main.ts
+     *     把它接到 `mainWindow.webContents.send()`，preload 暴露 `onChatTitleUpdated`。
+     *   - 写库前再 `getChat()` 校验，避免覆盖用户/其它窗口手改过的标题。
+     *   - 任何异常都吞掉记日志：title 是 nice-to-have，不该污染日志/影响主流程。
+     */
+    private runTitleGenInBackground;
+    /**
+     * 解析当前对话绑定的项目（项目模式）。chat 没绑项目、项目已被删除、或
+     * 注册表未注入时都返回 null（= 不沙箱，行为同旧版本）。
+     *
+     * Public: main.ts 的反向通道（reverse-tools.ts）经它给 CoreLoop 路径的
+     * 工具调用补上 projectRoot 围栏。
+     */
+    resolveChatProject(chatId: string): {
+        name: string;
+        folderPath: string;
+    } | null;
+    /**
+     * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。
+     *
+     * 优先级：payload.mentionedAgentId（@提及）> mentionedAgentIds >
+     * payload.agentId > chat.agentId > 无。@提及多个时按提及顺序合并——
+     * rolePrompt 逐段拼装（第一个为主角色），能力面取最宽松
+     * （见 {@link mergeAgentCapabilities}）。
+     *
+     * 必须在拼装工具列表之前调用：`toolPolicy` 决定每轮 `turnTools`，
+     * 而工具列表又反过来决定技能的触发条件。
+     *
+     * @param chatId 当前对话 id。
+     * @param payload 前端提交的流请求体。
+     * @returns 本轮的智能体顺序、人设智能体，以及合并后的能力面。
+     */
+    private resolveTurnAgents;
+    private buildConversationMessages;
+    /**
+     * 消费前端 @历史对话 引用（LocalChatPanel 发送的 payload.referencedChatIds）。
+     *
+     * 每个被引用的对话生成一条 user 消息注入上下文：
+     * - 附最近若干条 user/assistant 消息的摘录（tool 消息跳过，assistant
+     *   文本复用 stripToolSummaryMarkdownForLlm 清理）；
+     * - 整体截断封顶，防止一次 @ 多个长对话把上下文挤爆。
+     *
+     * 以 user 角色注入（部分 OpenAI 兼容服务器不接受多条 system 消息）。
+     */
+    private buildReferencedChatContextMessages;
+    private stripToolSummaryMarkdownForLlm;
+    private appendExecutedActionsForLlm;
+    /**
+     * 检测"deferred-execution 幻觉"——LLM 用文字预告自己即将调用工具但实际没发
+     * tool_call。常见于中小尺寸模型：描述完工具参数后写一段
+     * "参数：... 现在执行..." 就停笔。
+     *
+     * 命中条件需要**同时**满足：
+     * 1) 包含"意图陈述"句式（现在执行 / 接下来 / 我将 / 准备运行 / now executing 等）
+     * 2) 文本以省略号 `...` / `…` 收尾，或以":"/中文冒号收尾
+     * 3) 长度 > 20 字符（避免误判极短的"好的，执行..."）
+     *
+     * 调用方负责再加一层"本轮 toolCalls 为空 && usedTool"的语境判断。
+     */
+    /**
+     * @deprecated Inline helper kept as a thin wrapper for backward compat;
+     * real implementation lives in `./deferred-detector.ts` so it's testable.
+     */
+    private detectDeferredExecution;
+    private detectToolDenialInHistory;
+    private buildModePreamble;
+    private isLocalSystemInfoRequest;
+    private buildRuntimeEnvironmentContext;
+    private buildToolRealityCheck;
+    /**
+     * 把整轮已发生的工具调用浓缩成 narration round 用的纯文本报告。
+     * 一条 = 一次工具调用，明显标注 ✅/❌，并尽量保留 error / hint 字段原文。
+     */
+    private briefResult;
+    private briefScalar;
+    private sse;
+    /**
+     * A4 CoreLoop turn: the sidecar runs the whole agent loop; this method
+     * translates its wire notifications into the existing SSE contract and
+     * persists the outcome. Tool execution happens back in this process via
+     * the reverse-channel handler registered in main.ts.
+     */
+    private handleCoreLoopTurn;
+    /**
+     * 标准"匿名事件" SSE：不带 event 行，前端 SSEParser 会落到默认 onMessage 分支，
+     * 用 parseSSEData 把 data 反序列化为 JSON 后用 type/content 字段路由。
+     */
+    private sseData;
+    private toRecord;
+    private safeJson;
+    private notFound;
+    private badRequest;
+    private cleanUserMessage;
+    /** 已安装技能的全部可触发别名（name/dirName/displayName，小写）。
+     *  除英文 name / dirName 外，也接受 SKILL.md 里 displayName 声明的可读
+     *  中文名（如「数据处理链」），这样 "/数据处理链" 同样能触发。 */
+    private knownSkillNameSet;
+}