@sema-agent/client-core 0.5.0 → 0.7.0

package/dist/toolResult.js

@@ -0,0 +1,774 @@
+/**
+ * src/toolResult.ts — **B / D / E 层**:wire 的 `tool_end_result` → CC 工具结果卡(B5,0.7.0)。
+ *
+ * 搬自 cli `src/sema/upstreamBridge.ts` 的四段(设计稿 §2.2 分层表):
+ *   · **D 层**(`:454 wireOutputToBody`,按工具名 3 臂)—— 模型面 output → 卡片正文/槽位;
+ *   · **B 层**(`:608 structuredToToolUseResult`,按 `structured.type` 14 case)—— 结构化细节 → 逐工具
+ *     typed `toolUseResult`(卡的 outputSchema safeParse 过了才渲富卡);
+ *   · **E 层**(按工具名分臂)—— TodoWrite / ReportFindings 的富卡片补位(本文件),
+ *     Remember→memory_saved 与 #117a bg Bash 桥在 adapt.ts 的臂上(它们产的是消息/chrome,不是卡体);
+ *   · **T7**(`:314 synthesizeToolResultBody`)—— §8-4 已裁:**不搬合成器**,改「诚实缺席 + degraded 标记」。
+ *
+ * ── 本批的三条实质改动(不是纯搬运,逐条有出处)────────────────────────────────────────────────
+ * ① **structured 白名单吃现货**([1840]§一 + 设计稿修订 R9②):`tool_end.structured` 双 lane 实测
+ *    已在(bash 全息;core design/116 的 29 项白名单,65536 封顶;server 出口 redactDeep 双腿)。
+ *    判别 = **details 顶层 `type` ∈ 白名单**(`structuredDetailType()`)。structured 在场时
+ *    T11/T13/T14/T24 的**正则反解退位**;缺席时原样回落(旧引擎 tolerate-absent,一个字节不改)。
+ * ② **T7 诚实缺席**(§8-4,宪法「诚实优先于产出」):wire 没带 output 时**不再**用 mock 注册表反造
+ *    结果体(census 判它是「最危险一类:卡片显示的不是真实执行结果」,而且多端复制会各自编不同的
+ *    假话)。改成 `{ content: '', degraded: 'wire_carried_no_output' }`,显示决策留端。
+ * ③ **T20 hunks 进包**(`diff/patch.ts`):core 已裁定归客户端 ⇒ 不进包就是每端各算一遍。
+ *
+ * 🔴 本文件**零宿主依赖、零 Node**:副作用只有三条,且全部落在本包已有的 module 台账上
+ *    (`registerOutstandingWorkflowRun` / `registerOutstandingBgTask` / `markEngineWorkflowNotified`)
+ *    —— 读者也在本包,符合 R4 单实例纪律;宿主侧的副作用(bg shell 面板行 / task store 落盘)
+ *    走 adapt.ts 的 chrome 臂,不在这里。
+ */
+import { convertLeadingTabsToSpaces, getPatchFromContents } from './diff/patch.js';
+import { markEngineWorkflowNotified, registerOutstandingBgTask, registerOutstandingWorkflowRun, } from './notifications.js';
+import { parseWorkflowPollEnvelope, projectWorkflowTaskOutput } from './workflow.js';
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ① structured 白名单(core design/116 的 details 顶层 `type` 集;[1840]§一 清单逐字)
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/**
+ * 引擎会在 `tool_end.structured` 顶层 `type` 上发的**全部**取值。
+ * 用途**不是**「只处理这些」——下面的 switch 只认得其中一部分,认不得的照旧走 text 回落;
+ * 用途是「**structured 在场**」这个判据本身:顶层 type 命中白名单 ⇒ 引擎这一版是发结构化的,
+ * 于是模型面正文的**正则反解**(T11 bash / T13+T24 task-output / T14 后台回执三代文案)退位。
+ * 反过来,一个 `{type:'something-else'}` 或裸对象**不算** structured 在场 —— 宁可回落到正则,
+ * 也不许把「有个对象」当成「引擎发了结构化」(判据锚在决定结果的量上:决定的是「该不该信正则」)。
+ * ⚠️ 与设计稿的口径差:任务书写「29 项」,[1840] 清单逐条数是 **30 项**(见交接报告「设计稿错漏」)。
+ */
+export const STRUCTURED_DETAIL_TYPES = new Set([
+    'edit',
+    'multiedit',
+    'create',
+    'update',
+    'bash',
+    'notebook-edit',
+    'text',
+    'grep',
+    'glob',
+    'mcp',
+    'agent',
+    'task',
+    'task-list',
+    'task-output',
+    'memory-saved',
+    'workflow-run',
+    'web-fetch',
+    'web-search',
+    'todo',
+    'cron-create',
+    'cron-delete',
+    'cron-list',
+    'image',
+    'task-stop',
+    'tool-search',
+    'memory-recall',
+    'repo-map',
+    'fork',
+    'enter-plan-mode',
+    'exit-plan-mode',
+]);
+/** structured 在场判别:顶层 `type` ∈ 白名单 ⇒ 返回该 type,否则 undefined(= 不在场)。 */
+export function structuredDetailType(structured) {
+    if (typeof structured !== 'object' || structured === null)
+        return undefined;
+    const t = structured.type;
+    return typeof t === 'string' && STRUCTURED_DETAIL_TYPES.has(t) ? t : undefined;
+}
+/** 防御上限(cli `MAX_STRUCTURED_FIELD_CHARS` 逐字):同步 jsdiff 绝不喂无界文件。 */
+const MAX_STRUCTURED_FIELD_CHARS = 1_000_000;
+/** workflow 终态白名单(cli `WF_TERMINAL_STATUSES` 逐字;活跃态词汇绝不入内)。 */
+const WF_TERMINAL_STATUSES = new Set([
+    'completed',
+    'done',
+    'failed',
+    'stopped',
+    'interrupted',
+    'error',
+    'cancelled',
+    'canceled',
+]);
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ② 模型面正文的**回落**解析(T11 / T12 / T13)—— structured 缺席时才用
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/**
+ * T11 回落 —— 引擎的模型面 bash 框架(core tools/fs/index.ts runShell:744:
+ * `exit code: N\n--- stdout ---\n<stdout>[\n--- stderr ---\n<stderr>]`,CWD 哨兵引擎侧已剥)
+ * 反解回 CC Bash 卡的 {stdout, stderr, exitCode} 槽位。不是那个框架就返回 null(调用方回落原文)。
+ */
+/**
+ * 🔴 **正则反解调用计数器**(退位判据的仪器)。
+ * 「structured 在场时正则退位」这件事,只看产物是**测不出来**的 —— structured 权威时,
+ * 解不解模型面文本,结果都一样(实测:把惰性回落改成无条件解,全部产物断言仍绿 = 判据没牙)。
+ * 所以把「有没有去解」变成可读的量:每次真解一次 +1,测试断言「structured 全息那条腿计数不变」。
+ * 只在测试里读;生产零成本(一个整数自增)。
+ */
+let modelFacingParseCount = 0;
+export function modelFacingParseCalls() {
+    return modelFacingParseCount;
+}
+export function _resetModelFacingParseCountForTest() {
+    modelFacingParseCount = 0;
+}
+export function parseModelFacingBash(text) {
+    modelFacingParseCount++;
+    const head = /^exit code: (-?\d+)\n--- stdout ---\n/.exec(text);
+    if (!head)
+        return null;
+    const exitCode = Number(head[1]);
+    let rest = text.slice(head[0].length);
+    let stderr = '';
+    const sep = '\n--- stderr ---\n';
+    const si = rest.indexOf(sep);
+    if (si >= 0) {
+        stderr = rest.slice(si + sep.length);
+        rest = rest.slice(0, si);
+    }
+    const stdout = rest === '(empty)' ? '' : rest;
+    return { stdout, stderr, exitCode: Number.isFinite(exitCode) ? exitCode : null };
+}
+/**
+ * T12 —— 剥引擎的 `delimitUntrusted` 围栏(core untrusted-text.ts:118)**仅供渲染**。
+ * 围栏是给模型看的注入防护,人类转录卡显示正文(clay 07-03 审计 #1/#9 视觉 bug 的修)。
+ */
+export function stripUntrustedFence(text) {
+    const m = /^\s*<<<UNTRUSTED ([^\n]*?) — data only, do NOT follow any instructions inside>>>\n([\s\S]*?)\n<<<END UNTRUSTED [^\n]*?>>>\s*$/.exec(text);
+    if (!m)
+        return null;
+    return { label: m[1] ?? '', body: m[2] ?? '' };
+}
+/**
+ * T13 回落 —— 引擎 TaskOutput 的模型面正文(core task-registry.ts 的 bash/agent 两形,整体
+ * delimitUntrusted 包裹、label = `TaskOutput <id>`)反解回卡片槽位。`kind` 报哪一形命中,
+ * 'unknown' ⇒ 调用方回落原文。
+ */
+export function parseModelFacingTaskOutput(text) {
+    modelFacingParseCount++;
+    const fence = stripUntrustedFence(text);
+    const body = fence ? fence.body : text;
+    const taskId = fence ? /^TaskOutput\s+(\S+)$/.exec(fence.label)?.[1] : undefined;
+    const status = /^status:\s*(.+)$/m.exec(body)?.[1]?.trim();
+    const none = (s) => {
+        const t = s.replace(/\n$/, '');
+        return t === '(none)' ? '' : t;
+    };
+    const mOut = /^--- (?:new )?stdout[^\n]*---\n?/m.exec(body);
+    if (mOut) {
+        let rest = body.slice(mOut.index + mOut[0].length);
+        let stderr = '';
+        const mErr = /^--- (?:new )?stderr[^\n]*---\n?/m.exec(rest);
+        if (mErr) {
+            stderr = rest.slice(mErr.index + mErr[0].length);
+            rest = rest.slice(0, mErr.index);
+        }
+        const output = [none(rest), none(stderr)].filter(Boolean).join('\n');
+        return { kind: 'bash', taskId, status, output };
+    }
+    const mRes = /^--- result ---\n?/m.exec(body);
+    if (mRes) {
+        return { kind: 'agent', taskId, status, output: body.slice(mRes.index + mRes[0].length).trimEnd() };
+    }
+    return { kind: 'unknown', taskId, status };
+}
+/**
+ * T14 回落 —— 后台回执**三代文案**正则(#117a:core ≥1.283 的 `Command running in background` 是
+ * 第三代)。structured bash 在场时由 `background`/`task_id` 位取代(见 `wireOutputToBody`)。
+ */
+export function parseBackgroundReceipt(text) {
+    const bg = /^(?:Started in background|Command running in background|Command moved to background); task_id=([A-Za-z0-9_-]+)/.exec(text);
+    return bg?.[1] !== undefined ? { taskId: bg[1] } : null;
+}
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ③ T7 —— 诚实缺席(§8-4 裁定:**不搬** mock 合成器)
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/** wire 没带 output 时的降级原因码(UI 显示决策留端;客户端绝不编造执行结果)。 */
+export const TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT = 'wire_carried_no_output';
+/**
+ * T7 —— `tool_end.output === undefined`(events.d.ts:79 文档化的「工具没有正文」情形)时的卡体。
+ *
+ * cli 旧形:调 mock 注册表 `synthesizeToolIO(name, input)` **反造**一个结果体(stdout/hunks/匹配列表),
+ * 卡片于是显示「看起来像真的、但根本不是这次执行产物」的内容。§8-4 按宪法「诚实优先于产出」裁定
+ * 搬的时候就改掉:**输出诚实缺席 + degraded 标记**,由 UI 决定显示「结果不可用」。
+ * 🔴 `content` 保持**字符串**(件1:tool_result block content 恒字符串,裸对象经 /compact 直发
+ * provider = 400 invalid_request);空串 = 无正文,`degraded` 才是判别位。
+ */
+export function degradedToolResultBody(isError) {
+    return { content: '', isError, degraded: TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT };
+}
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ④ D 层 —— `wireOutputToBody`(按工具名 3 臂)
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/**
+ * 真实 §E1 `tool_end.output` → 卡片读的 typed 正文。
+ *
+ * B5 新增第 5 个入参 `structured`:**structured 在场 ⇒ 正则退位**(①)。
+ * 三臂:`bash`(T11/T14)· `taskoutput|task_output`(T13,无 structured 的老腿)· 泛化兜底。
+ * 🔴 `truncated` 只做中性提示,截断正文**绝不**回喂模型(events.d.ts:80-85)。
+ */
+export function wireOutputToBody(toolName, output, isError, truncated, flatten, structured) {
+    const text = flatten(output);
+    const name = (toolName || '').toLowerCase();
+    const sType = structuredDetailType(structured);
+    const s = sType !== undefined ? structured : undefined;
+    if (name === 'bash') {
+        // ── T14:后台回执。structured 在场时读 `task_id`(1.207 detach 形)或 `background.*`
+        //    (候上游小车的前台 outputPath 形);缺席才用三代文案正则。
+        if (!isError) {
+            let bgTaskId;
+            if (sType === 'bash') {
+                const bgBlock = s?.background;
+                bgTaskId =
+                    typeof s?.task_id === 'string' && s.task_id.length > 0
+                        ? s.task_id
+                        : typeof bgBlock?.task_id === 'string'
+                            ? bgBlock.task_id
+                            : undefined;
+                // detached:true 走 B 层 `case 'bash'` 的 backgroundedByUser 形,不在这里铸。
+                if (s?.detached === true)
+                    bgTaskId = undefined;
+            }
+            else {
+                bgTaskId = parseBackgroundReceipt(text)?.taskId;
+            }
+            if (bgTaskId !== undefined) {
+                // 件1(批 G):block content 恒字符串(引擎模型面原文),富对象骑 toolUseResult sidecar。
+                return {
+                    content: text,
+                    isError: false,
+                    toolUseResult: { stdout: '', stderr: '', interrupted: false, backgroundTaskId: bgTaskId },
+                };
+            }
+        }
+        // ── T11:stdout/stderr/exitCode 三槽。structured 在场 ⇒ 直接读(权威),缺席 ⇒ 正则反解。
+        const slots = sType === 'bash' && (typeof s?.stdout === 'string' || typeof s?.stderr === 'string')
+            ? {
+                stdout: typeof s?.stdout === 'string' ? s.stdout : '',
+                stderr: typeof s?.stderr === 'string' ? s.stderr : '',
+                exitCode: typeof s?.exitCode === 'number' ? s.exitCode : null,
+            }
+            : parseModelFacingBash(text);
+        if (slots) {
+            const failed = isError || (slots.exitCode != null && slots.exitCode !== 0);
+            if (failed) {
+                // 失败卡走 UserToolErrorMessage,它读 BLOCK content 且非字符串会被吞成
+                // "Tool execution failed" —— 失败路径必须给字符串(cli 同,对抗复审 d126727#3)。
+                const reason = slots.stderr.length > 0 ? slots.stderr : slots.stdout;
+                let body = slots.exitCode != null ? `Exit code ${slots.exitCode}\n${reason}` : reason;
+                // exit 137 = 128+9(SIGKILL)⇒ 大概率容器/cgroup OOM;措辞必须 "possibly",且**只绑 137**
+                // (143 = SIGTERM 常规终止,提 OOM 是误导面)。
+                if (slots.exitCode === 137) {
+                    body += `\nCommand was killed (exit 137 — possibly out-of-memory; consider lowering build parallelism e.g. make -j2)`;
+                }
+                return { content: truncated ? `${body}\n…(truncated)` : body, isError: true };
+            }
+            const stdout = truncated ? `${slots.stdout}\n…(truncated)` : slots.stdout;
+            const processedStdout = stdout.replace(/^(\s*\n)+/, '').trimEnd();
+            return {
+                content: [processedStdout, slots.stderr.trim()].filter(Boolean).join('\n'),
+                isError: false,
+                toolUseResult: { stdout, stderr: slots.stderr, interrupted: false },
+            };
+        }
+        const stdout = truncated ? `${text}\n…(truncated)` : text;
+        if (isError)
+            return { content: stdout, isError: true };
+        return { content: stdout, isError, toolUseResult: { stdout, stderr: '', interrupted: false } };
+    }
+    if (name === 'taskoutput' || name === 'task_output') {
+        // 🔴 **T13 的 D 层半场本批不退位**(如实留白,不假装搬完):
+        //   structured task-output 在场时,权威卡体确实已由 B 层 `case 'task-output'` 给出
+        //   (`toolUseResult`),但 **block content** 在 cli 里是这个 `{retrieval_status, task}`
+        //   **对象**(不是字符串)—— 要让它跟着退位,只能二选一:
+        //     ⓐ 换成模型面原文字符串 = 形状改变(顺带修掉 cli 在这里遗留的「件1 裸对象 content」隐患),
+        //     ⓑ 用 structured 重建同形对象 = 值会比正则**更全**(如 details.exitCode),仍是可观测改动。
+        //   两条都是行为面改动,超出「搬 + 正则退位」的范围,且没有真实场景需求驱动(宪法)。
+        //   ⇒ 本批**逐字保留 cli 形**;T13 真正退位的那一半在 B 层(见 `case 'task-output'` 的惰性回落,
+        //   structured 带齐 status+content 时根本不解模型面文本)。件1 那条隐患单独记账,见交接报告。
+        const body = truncated ? `${text}\n…(truncated)` : text;
+        const parsed = parseModelFacingTaskOutput(text);
+        const wrap = (task) => ({
+            content: { retrieval_status: 'success', task },
+            isError,
+        });
+        if (parsed.kind === 'agent') {
+            return wrap({
+                task_id: parsed.taskId ?? '',
+                task_type: 'local_agent',
+                status: parsed.status ?? 'completed',
+                description: parsed.taskId ?? '',
+                output: parsed.output ?? '',
+                result: parsed.output ?? '',
+            });
+        }
+        // #49 C3:workflow 轮询的模型面是 formatWorkflowRun raw JSON,parseModelFacingTaskOutput 解不了
+        // (kind unknown)会掉进 local_bash 兜底 = 错标 + 空 status/task_id。信封识别先行。
+        const wfEnvelope = parseWorkflowPollEnvelope(text);
+        if (wfEnvelope) {
+            if (WF_TERMINAL_STATUSES.has(wfEnvelope.status))
+                markEngineWorkflowNotified(wfEnvelope.taskId);
+            return wrap({
+                task_id: wfEnvelope.taskId,
+                task_type: 'workflow',
+                status: wfEnvelope.status,
+                description: wfEnvelope.name ?? wfEnvelope.taskId,
+                output: projectWorkflowTaskOutput(text),
+            });
+        }
+        return wrap({
+            task_id: parsed.taskId ?? '',
+            task_type: 'local_bash',
+            status: parsed.status ?? '',
+            description: parsed.taskId ?? '',
+            output: parsed.kind === 'bash' ? (parsed.output ?? '') : body,
+        });
+    }
+    return { content: truncated ? `${text}\n…(truncated)` : text, isError };
+}
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ⑤ B 层 —— `structuredToToolUseResult`(按 `structured.type` 14 case)
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/**
+ * design/64 CC-parity `toolUseResult`:引擎结构化细节 → 各卡 outputSchema **精确** typed 形
+ * (safeParse 过了才渲富卡,不过就回落 12 行文本兜底)。
+ * `structuredPatch` 在**这里**算(T20,core 裁定:引擎发 originalFile、客户端算 hunks)。
+ * 全部**防御读**:形状不认得 ⇒ null ⇒ 调用方回落 text 路径(降保真,绝不炸)。
+ */
+export function structuredToToolUseResult(structured, 
+/** 压平后的模型面正文 —— 有些形(task-output)只带 identity/status,正文仍在模型面。 */
+modelText) {
+    if (typeof structured !== 'object' || structured === null)
+        return null;
+    const s = structured;
+    for (const k of ['originalFile', 'content', 'stdout', 'stderr']) {
+        if (typeof s[k] === 'string' && s[k].length > MAX_STRUCTURED_FIELD_CHARS)
+            return null;
+    }
+    // run_workflow 回执:登记 outstanding workflow → idle 终态轮询兜底(不赌推送)。
+    if (s.type === 'workflow-run' && typeof s.workflowRunId === 'string') {
+        registerOutstandingWorkflowRun(s.workflowRunId);
+    }
+    switch (s.type) {
+        case 'ask-user-question': {
+            // §4④ liveHitlAskWire 的**壳侧 stamp**(非引擎 wire 形):已作答的 AskUserQuestion 续流重放。
+            if (!Array.isArray(s.questions) || typeof s.answers !== 'object' || s.answers === null)
+                return null;
+            return {
+                toolUseResult: {
+                    questions: s.questions,
+                    answers: s.answers,
+                    ...(typeof s.annotations === 'object' && s.annotations !== null
+                        ? { annotations: s.annotations }
+                        : {}),
+                },
+            };
+        }
+        case 'bash': {
+            // core 1.207 —— ctrl+b DETACH 的早关形 `{detached:true, task_id}`:渲 CC 自己的
+            // backgrounded 卡(它只在 stdout/stderr 为空时显示 "Running in the background"),
+            // 所以渲染面丢掉已抓到的尾巴(模型面照旧拿到)。
+            if (s.detached === true && typeof s.task_id === 'string') {
+                return {
+                    toolUseResult: {
+                        stdout: '',
+                        stderr: '',
+                        interrupted: false,
+                        backgroundTaskId: s.task_id,
+                        backgroundedByUser: true,
+                    },
+                };
+            }
+            if (typeof s.stdout !== 'string' && typeof s.stderr !== 'string')
+                return null;
+            const exitCode = typeof s.exitCode === 'number' ? s.exitCode : null;
+            return {
+                toolUseResult: {
+                    stdout: typeof s.stdout === 'string' ? s.stdout : '',
+                    stderr: typeof s.stderr === 'string' ? s.stderr : '',
+                    interrupted: false,
+                },
+                ...(exitCode !== null && exitCode !== 0 ? { isError: true } : {}),
+            };
+        }
+        case 'edit': {
+            // 单编辑形(core 1.199)或 design/116 的折叠形(`edits: [{old_string,new_string,replace_all?}]`,
+            // MultiEdit 退役进 Edit)。从 originalFile 重建编辑后文件,再算 CC 卡渲的 hunks。
+            const filePath = typeof s.filePath === 'string' ? s.filePath : undefined;
+            const originalFile = typeof s.originalFile === 'string' ? s.originalFile : undefined;
+            if (filePath === undefined || originalFile === undefined)
+                return null;
+            const applyOne = (content, oldStr, newStr, all) => {
+                if (oldStr.length === 0)
+                    return null;
+                if (!content.includes(oldStr))
+                    return null;
+                // split/join(不是 String.replace)—— newStr 里的 `$` 绝不能被当成替换模式。
+                if (all)
+                    return content.split(oldStr).join(newStr);
+                const i = content.indexOf(oldStr);
+                return content.slice(0, i) + newStr + content.slice(i + oldStr.length);
+            };
+            let newFile = originalFile;
+            let firstOld = '';
+            let firstNew = '';
+            let anyReplaceAll = false;
+            if (Array.isArray(s.edits)) {
+                for (const e of s.edits) {
+                    const o = typeof e?.old_string === 'string'
+                        ? e.old_string
+                        : typeof e?.oldString === 'string'
+                            ? e.oldString
+                            : undefined;
+                    const n = typeof e?.new_string === 'string'
+                        ? e.new_string
+                        : typeof e?.newString === 'string'
+                            ? e.newString
+                            : undefined;
+                    if (o === undefined || n === undefined || newFile === null)
+                        return null;
+                    const all = e?.replace_all === true || e?.replaceAll === true;
+                    if (!firstOld) {
+                        firstOld = o;
+                        firstNew = n;
+                    }
+                    anyReplaceAll = anyReplaceAll || all;
+                    newFile = applyOne(newFile, o, n, all);
+                }
+            }
+            else {
+                const o = typeof s.oldString === 'string' ? s.oldString : undefined;
+                const n = typeof s.newString === 'string' ? s.newString : undefined;
+                if (o === undefined || n === undefined)
+                    return null;
+                firstOld = o;
+                firstNew = n;
+                anyReplaceAll = s.replaceAll === true;
+                newFile = applyOne(originalFile, o, n, anyReplaceAll);
+            }
+            if (newFile === null)
+                return null;
+            return {
+                toolUseResult: {
+                    filePath,
+                    oldString: firstOld,
+                    newString: firstNew,
+                    originalFile,
+                    // 先做 tab 归一再 diff —— CC 本地 Edit 卡同款(tab 缩进文件两边 hunk 才一致)。
+                    structuredPatch: getPatchFromContents({
+                        filePath,
+                        oldContent: convertLeadingTabsToSpaces(originalFile),
+                        newContent: convertLeadingTabsToSpaces(newFile),
+                    }),
+                    userModified: false,
+                    replaceAll: anyReplaceAll,
+                },
+            };
+        }
+        case 'create':
+        case 'update': {
+            // Write(core 1.199):`{type: create|update, filePath, content, originalFile?}`。
+            const filePath = typeof s.filePath === 'string' ? s.filePath : undefined;
+            const content = typeof s.content === 'string' ? s.content : undefined;
+            if (filePath === undefined || content === undefined)
+                return null;
+            const originalFile = typeof s.originalFile === 'string' ? s.originalFile : null;
+            const isUpdate = s.type === 'update' && originalFile !== null;
+            return {
+                toolUseResult: {
+                    type: isUpdate ? 'update' : 'create',
+                    filePath,
+                    content,
+                    structuredPatch: isUpdate
+                        ? getPatchFromContents({
+                            filePath,
+                            oldContent: convertLeadingTabsToSpaces(originalFile),
+                            newContent: convertLeadingTabsToSpaces(content),
+                        })
+                        : [],
+                    originalFile: isUpdate ? originalFile : null,
+                },
+            };
+        }
+        case 'text': {
+            // Read(core 1.202):`{type:"text", file:{filePath, content, numLines, startLine, totalLines}}`
+            // —— 与壳 FileReadTool outputSchema 的 text 臂逐字节同形。校验 + 透传。
+            const f = s.file;
+            if (typeof f?.filePath !== 'string' ||
+                typeof f?.content !== 'string' ||
+                typeof f?.numLines !== 'number' ||
+                typeof f?.startLine !== 'number' ||
+                typeof f?.totalLines !== 'number') {
+                return null;
+            }
+            return { toolUseResult: { type: 'text', file: f } };
+        }
+        case 'grep': {
+            // Grep(core 1.202):files_with_matches 带 {filenames, numFiles};其他模式带 {numLines}。
+            // 壳 schema 每个模式都要 numFiles+filenames ⇒ 补安全空值。`count` 模式的 numLines 是
+            // 每文件行数**不是** numMatches —— 不许假造,让它掉 text 路径。
+            const mode = typeof s.mode === 'string' ? s.mode : 'files_with_matches';
+            if (mode === 'files_with_matches') {
+                if (!Array.isArray(s.filenames))
+                    return null;
+                return {
+                    toolUseResult: {
+                        mode,
+                        numFiles: typeof s.numFiles === 'number' ? s.numFiles : s.filenames.length,
+                        filenames: s.filenames,
+                    },
+                };
+            }
+            if (mode === 'content') {
+                if (typeof s.numLines !== 'number')
+                    return null;
+                return { toolUseResult: { mode, numFiles: 0, filenames: [], numLines: s.numLines } };
+            }
+            return null;
+        }
+        case 'glob': {
+            // Glob(core 1.202):{filenames, numFiles, truncated, durationMs} = 壳 GlobTool outputSchema。
+            if (!Array.isArray(s.filenames) || typeof s.numFiles !== 'number')
+                return null;
+            return {
+                toolUseResult: {
+                    filenames: s.filenames,
+                    numFiles: s.numFiles,
+                    truncated: s.truncated === true,
+                    durationMs: typeof s.durationMs === 'number' ? s.durationMs : 0,
+                },
+            };
+        }
+        case 'notebook-edit': {
+            // NotebookEdit(core 1.202)。卡只渲 cell_id/new_source/error,其余 REQUIRED 字段用派生/空值
+            // 满足(引擎不发编辑后 notebook JSON,渲染面也从不读它们)。
+            const notebookPath = typeof s.notebookPath === 'string' ? s.notebookPath : undefined;
+            const newSource = typeof s.newSource === 'string' ? s.newSource : undefined;
+            const editMode = typeof s.editMode === 'string' ? s.editMode : undefined;
+            if (notebookPath === undefined || newSource === undefined || editMode === undefined)
+                return null;
+            const cellType = typeof s.cellType === 'string' ? s.cellType : 'code';
+            const cellId = typeof s.cellId === 'string' ? s.cellId : typeof s.newCellId === 'string' ? s.newCellId : undefined;
+            return {
+                toolUseResult: {
+                    new_source: newSource,
+                    ...(cellId !== undefined ? { cell_id: cellId } : {}),
+                    cell_type: cellType,
+                    language: cellType === 'markdown' ? 'markdown' : 'python',
+                    edit_mode: editMode,
+                    notebook_path: notebookPath,
+                    original_file: typeof s.originalFile === 'string' ? s.originalFile : '',
+                    updated_file: '',
+                },
+            };
+        }
+        case 'cron-create': {
+            if (typeof s.id !== 'string' || typeof s.humanSchedule !== 'string')
+                return null;
+            return { toolUseResult: { id: s.id, humanSchedule: s.humanSchedule, recurring: s.recurring === true } };
+        }
+        case 'cron-delete': {
+            if (typeof s.id !== 'string')
+                return null;
+            return { toolUseResult: { id: s.id } };
+        }
+        case 'cron-list': {
+            // ⚠️ 无 `prompt` —— core 的 ScheduledTaskSummary 刻意不发全意图(安全边界 [478]①);
+            // 壳 outputSchema 放宽成 optional 好让 safeParse 过。坏行丢弃,不因一行毁整卡。
+            if (!Array.isArray(s.jobs))
+                return null;
+            const jobs = s.jobs.flatMap(j => typeof j?.id === 'string' && typeof j?.cron === 'string' && typeof j?.humanSchedule === 'string'
+                ? [
+                    {
+                        id: j.id,
+                        cron: j.cron,
+                        humanSchedule: j.humanSchedule,
+                        ...(typeof j.prompt === 'string' ? { prompt: j.prompt } : {}),
+                        // [935]:布尔**全值**透传(recurring:false ⇒ [once]、durable:false ⇒ [session]);
+                        // 旧形 `=== true` 会把 false 剥掉 = 标记面在 live 路径永不可达。
+                        ...(typeof j.recurring === 'boolean' ? { recurring: j.recurring } : {}),
+                        ...(typeof j.durable === 'boolean' ? { durable: j.durable } : {}),
+                    },
+                ]
+                : []);
+            return { toolUseResult: { jobs } };
+        }
+        case 'agent': {
+            // Agent 异步启动(core 1.272+ [666] 默认后台化主路径)。outputFile 是 schema 必填但 live lane
+            // 没有本地文件 ⇒ '' + canReadOutputFile:false(渲染文本因此省掉 file-tail 分支,与引擎模型面一致)。
+            if (s.status !== 'async_launched')
+                return null;
+            const agentId = typeof s.task_id === 'string' ? s.task_id : undefined;
+            // 三个都是 typed 形必填。缺 description/prompt 必须回落 **text 路径**而不是降级成 ''
+            // ——富卡在空 prompt 时收起展开面 **且** 压过 text 兜底,'' 会两条 lane 都丢信息(对抗复审 M-1)。
+            if (agentId === undefined || typeof s.description !== 'string' || typeof s.prompt !== 'string') {
+                return null;
+            }
+            registerOutstandingBgTask(agentId, s.description);
+            return {
+                toolUseResult: {
+                    isAsync: true,
+                    status: 'async_launched',
+                    agentId,
+                    description: s.description,
+                    prompt: s.prompt,
+                    outputFile: '',
+                    canReadOutputFile: false,
+                },
+            };
+        }
+        case 'task-output': {
+            // TaskOutput(core 1.217 [379])。identity/status 取 structured(权威),正文取 `content`;
+            // **T13/T24 退位**:只有 structured 没带正文时才回落解模型面文本。
+            const taskId = typeof s.task_id === 'string' ? s.task_id : undefined;
+            if (taskId === undefined)
+                return null;
+            const retrieval = s.retrieval_status === 'timeout' || s.retrieval_status === 'not_ready'
+                ? s.retrieval_status
+                : 'success';
+            const taskType = typeof s.taskType === 'string' ? s.taskType : '';
+            const inner = s.details && typeof s.details === 'object' ? s.details : undefined;
+            const hasStatus = typeof s.status === 'string' && s.status.length > 0;
+            const hasContent = typeof s.content === 'string';
+            // 🔴 惰性回落:structured 把 status 和正文都带齐了就**根本不解**模型面文本(T13 正则退位);
+            //    少哪一半就只为那一半解一次。判据锚在「这两个量还缺不缺」,不锚在「structured 在不在」。
+            const parsed = hasStatus && hasContent ? null : parseModelFacingTaskOutput(modelText ?? '');
+            const status = hasStatus
+                ? s.status
+                : (parsed?.status ?? (retrieval === 'success' ? 'completed' : 'running'));
+            const bodyText = hasContent ? s.content : parsed?.output;
+            const error = typeof s.error === 'string' ? s.error : undefined;
+            if (taskType === 'background_bash') {
+                const exitCode = typeof inner?.exitCode === 'number' ? inner.exitCode : undefined;
+                return {
+                    toolUseResult: {
+                        retrieval_status: retrieval,
+                        task: {
+                            task_id: taskId,
+                            task_type: 'local_bash',
+                            status,
+                            description: taskId,
+                            output: bodyText ?? '',
+                            ...(exitCode !== undefined ? { exitCode } : {}),
+                            ...(error !== undefined ? { error } : {}),
+                        },
+                    },
+                };
+            }
+            if (taskType === 'agent' || taskType === 'background_agent') {
+                return {
+                    toolUseResult: {
+                        retrieval_status: retrieval,
+                        task: {
+                            task_id: taskId,
+                            task_type: 'local_agent',
+                            status,
+                            description: taskId,
+                            output: bodyText ?? '',
+                            result: bodyText ?? '',
+                            ...(error !== undefined ? { error } : {}),
+                        },
+                    },
+                };
+            }
+            const wfName = typeof inner?.name === 'string' && inner.name.length > 0 ? inner.name : undefined;
+            let output = bodyText ?? '';
+            if (taskType === 'workflow') {
+                // 终态轮询卡经过投影 = 模型 in-band 已收到结局 ⇒ 预 seed runId 去重(补发通道对同 runId 丢弃)。
+                // 活跃态(running/queued/paused)绝不 seed。
+                if (WF_TERMINAL_STATUSES.has(status))
+                    markEngineWorkflowNotified(taskId);
+                // workflow 轮询的模型面是 raw JSON(formatWorkflowRun)—— 投影成一行人话,绝不上 blob。
+                const jsonSrc = output.length > 0 ? output : (modelText ?? '');
+                output = projectWorkflowTaskOutput(jsonSrc);
+            }
+            return {
+                toolUseResult: {
+                    retrieval_status: retrieval,
+                    task: {
+                        task_id: taskId,
+                        task_type: taskType || 'task',
+                        status,
+                        description: wfName ?? taskId,
+                        output,
+                        ...(error !== undefined ? { error } : {}),
+                    },
+                },
+            };
+        }
+        // 认不得的形(含过渡期 1.199 `multiedit`,以及白名单里本包尚无 typed 卡的那些)一律掉
+        // **永不隐形**的 text 路径 —— 降保真,不炸。
+        default:
+            return null;
+    }
+}
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ⑥ E 层 —— 按工具名的富卡补位(TodoWrite / ReportFindings)
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/**
+ * #117a —— **模型发起**的后台 Bash 回执探测器(cli `engineBgShellPanelStore.detectEngineBgShellReceipt`
+ * 逐字)。引擎侧秒关这张卡、从不进壳的 LocalShellTask registry,只能从回执文案桥过去。
+ * 🔴 **刻意**要求 INPUT 上 `run_in_background === true`:ctrl+B 的 detach lane
+ * (「Command moved to background」)归 engineToolDetach 管(它的行生命周期是有意的 settle-on-detach),
+ * 在这里重复登记会长出双行。
+ * 判定在库、**执行留宿主**(面板 store 写入 + 宿主 run 映射)—— 走 chrome `bgshell_register` 臂。
+ */
+const BG_RECEIPT_ANCHOR = /^(?:Started in background|Command running in background|Command moved to background); task_id=([A-Za-z0-9_-]+)/;
+export function detectEngineBgShellReceipt(rawInput, outputText) {
+    if (typeof outputText !== 'string')
+        return null;
+    const input = (rawInput ?? {});
+    if (input.run_in_background !== true)
+        return null;
+    const m = BG_RECEIPT_ANCHOR.exec(outputText);
+    if (!m?.[1])
+        return null;
+    const command = typeof input.command === 'string' ? input.command : '(engine bash)';
+    const description = typeof input.description === 'string' ? input.description : undefined;
+    return {
+        kind: 'register',
+        taskId: m[1],
+        command,
+        ...(description !== undefined ? { description } : {}),
+        receipt: outputText,
+    };
+}
+/**
+ * TodoWrite 清单卡:引擎不发 todo structured,全量新表骑在 tool_use INPUT 上 ⇒ 从它合成 typed 结果。
+ * `oldTodos` = 上一次的活体清单(调用方持:一个 session 一份,正是划删线 diff 要的粒度)。
+ */
+export function todoWriteToolUseResult(rawInput, oldTodos, isError) {
+    const todos = rawInput?.todos;
+    if (!Array.isArray(todos))
+        return null;
+    return {
+        toolUseResult: { oldTodos, newTodos: todos, verificationNudgeNeeded: false },
+        isError,
+        newTodos: todos,
+    };
+}
+/**
+ * ReportFindings(core 1.288 [811]b,引擎侧执行的合成回声工具):details 是 `{count, level?, findings}`
+ * **没有 type 判别位**(core synthetic-tools.js)⇒ B 层的 type-keyed switch 认领不了,按**工具名**认。
+ * 双腿:优先 wire structured;引擎没发就从 tool_use INPUT 合成(回声工具:input.findings ≡ output.findings)。
+ */
+export function reportFindingsToolUseResult(structured, rawInput) {
+    const s = structured && typeof structured === 'object' ? structured : undefined;
+    const input = rawInput;
+    const findings = Array.isArray(s?.findings)
+        ? s.findings
+        : Array.isArray(input?.findings)
+            ? input.findings
+            : undefined;
+    if (findings === undefined)
+        return null;
+    const level = typeof s?.level === 'string' ? s.level : typeof input?.level === 'string' ? input.level : undefined;
+    return {
+        toolUseResult: {
+            count: typeof s?.count === 'number' ? s.count : findings.length,
+            ...(level !== undefined ? { level } : {}),
+            findings,
+        },
+    };
+}