@sema-agent/client-core 0.2.0

package/dist/adapt.js

@@ -0,0 +1,773 @@
+import { deriveTranscriptId } from './seam.js';
+import { normalizeTaskNotification, renderTaskNotificationXml, taskNotificationDedupKey } from './notifications.js';
+import { mapBrainStatusToRetry } from './retryStatus.js';
+import { steeringInjectedToAttachments } from './steering.js';
+import { projectDiagnosticsFrame } from './diagnostics.js';
+/** 主车道证明——本批实现的臂全在 leader lane(子代/workflow lane 的 tick 面留 #52b)。 */
+const MAIN = { lane: 'main' };
+/** cli COALESCER 节流(207 口径;187 时代是 16ms)。宿主无关,时钟从 ctx.now() 取。 */
+export const FLUSH_INTERVAL_MS = 100;
+/** cli SUBAGENT_TOOL_NAMES / WORKFLOW_TOOL_NAMES 同源(判别资产,别各自重写)。 */
+export const SUBAGENT_TOOL_NAMES = new Set(['Task', 'Agent', 'Fork']);
+export const WORKFLOW_TOOL_NAMES = new Set(['Workflow', 'RunWorkflow', 'run_workflow']);
+/** 引擎侧 task 族工具(ctrl+t 面板台账同步的侧信道触发名;cli handleEngineTaskToolUse 受理的三名:
+ *  TodoWrite 全量表 upsert + TaskCreate/TaskUpdate;其余工具该函数直接 return)。 */
+const TASK_TOOL_NAMES = new Set(['TodoWrite', 'TaskCreate', 'TaskUpdate']);
+/**
+ * CC 自己的 reject/cancel 哨兵串(**数据**,非 CC 逻辑;cli src/utils/messages.ts:210-212 逐字)。
+ * CC 的 UserToolResultMessage 按 content 串前缀路由到 reject/cancel 卡,不看 is_error 位。
+ */
+export const REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
+export const CANCEL_MESSAGE = "The user doesn't want to take this action right now. STOP what you are doing and wait for the user to tell you how to proceed.";
+/** CJK 加权 token 估算(cli estimateCjkTokens 逐字:CJK≈0.6,其余≈0.25 tok/char)。 */
+export function estimateCjkTokens(s) {
+    let t = 0;
+    for (const c of s) {
+        const cp = c.codePointAt(0) ?? 0;
+        t +=
+            (cp >= 0x2e80 && cp <= 0x9fff) ||
+                (cp >= 0x3000 && cp <= 0x30ff) ||
+                (cp >= 0xac00 && cp <= 0xd7a3) ||
+                (cp >= 0xf900 && cp <= 0xfaff) ||
+                (cp >= 0xff00 && cp <= 0xffef) ||
+                (cp >= 0x20000 && cp <= 0x3ffff)
+                ? 0.6
+                : 0.25;
+    }
+    return Math.round(t);
+}
+/** 引擎 subagent 卡的短标签(cli shortTaskLabel 逐字)。 */
+export function shortTaskLabel(task) {
+    const firstLine = (task.split('\n').find(l => l.trim()) ?? task).trim();
+    const words = firstLine.split(/\s+/).slice(0, 6).join(' ');
+    const label = words.length > 48 ? words.slice(0, 47) + '…' : words;
+    return label || 'subagent';
+}
+/**
+ * tool_use 块的渲染面消毒(cli assistant 臂逐条搬运,**纯函数**,不改入参):
+ *  ① 摘 §E2 wire 身份(eventId/parentToolCallId)并从渲染块剥掉;
+ *  ② 剥所有 `_sema_*` 保留哨兵(CC 的 per-tool 渲染器 safeParse strictObject,多一个键就降级成通用卡);
+ *  ③ 引擎 subagent 参数名 {agent,task,taskName} → CC 名 {subagent_type,description,prompt}
+ *     (strict schema 拒绝多余键 ⇒ REPLACE 不 merge;taskName 缺席时从 task 派生短标签);
+ *  ④ 件8 类型标签诚实化:引擎通道兑现不了的 subagent_type 值一律删(只留 fork/general-purpose/worker),
+ *     否则卡头会显示 `Plan(…)` 而实跑 general-purpose。
+ */
+export function sanitizeToolUseBlock(block) {
+    const out = { ...block };
+    const rawInput = out.input;
+    const eventId = typeof out.eventId === 'string' ? out.eventId : undefined;
+    const parentToolCallId = typeof out.parentToolCallId === 'string' ? out.parentToolCallId : undefined;
+    delete out.eventId;
+    delete out.parentToolCallId;
+    if (out.input && typeof out.input === 'object') {
+        const cleaned = {};
+        for (const [k, val] of Object.entries(out.input)) {
+            if (!k.startsWith('_sema_'))
+                cleaned[k] = val;
+        }
+        out.input = cleaned;
+    }
+    if (out.input && typeof out.input === 'object') {
+        const inp = out.input;
+        const looksEngineSubagent = typeof inp.task === 'string' && inp.prompt === undefined && inp.description === undefined;
+        if (looksEngineSubagent) {
+            const task = inp.task;
+            const taskName = typeof inp.taskName === 'string' ? inp.taskName.trim() : '';
+            const label = taskName || shortTaskLabel(task);
+            const remapped = { description: label, prompt: task };
+            if (typeof inp.agent === 'string')
+                remapped.subagent_type = inp.agent;
+            if (typeof inp.model === 'string')
+                remapped.model = inp.model;
+            out.input = remapped;
+        }
+    }
+    if (SUBAGENT_TOOL_NAMES.has(out.name) && out.input && typeof out.input === 'object') {
+        const inp = out.input;
+        if (typeof inp.subagent_type === 'string' &&
+            !['fork', 'general-purpose', 'worker'].includes(inp.subagent_type)) {
+            delete inp.subagent_type;
+        }
+    }
+    return { block: out, rawInput, ...(eventId !== undefined ? { eventId } : {}), ...(parentToolCallId !== undefined ? { parentToolCallId } : {}) };
+}
+/** seam 的 reserved decision 哨兵(cli decisionOf 逐字)。 */
+function decisionOf(block) {
+    const input = block.input;
+    const d = input?._sema_decision;
+    return d === 'reject' || d === 'cancel' || d === 'error' ? d : undefined;
+}
+/** 本批覆盖清单——差分守卫按它区分「已覆盖臂必须逐字段等价」与「已声明未覆盖臂」。 */
+export const ADAPTER_COVERAGE = {
+    /** 已落码的帧臂。 */
+    frames: [
+        'assistant',
+        'user',
+        'stream_event',
+        'turn_usage',
+        'result',
+        'system',
+        'task_notification',
+        'workflow_complete',
+        'diagnostics',
+        'steering_injected',
+        'workspace_changed',
+        'retry_status',
+        'tool_end_result(仅 response-id 复位 + 开卡台账出栈,不铸 tool_result)',
+    ],
+    /** 已落码臂产出的 transcript 消息类目(差分守卫的比对域)。 */
+    transcriptKinds: [
+        'assistant_text',
+        'assistant_thinking',
+        'assistant_tool_use',
+        'user_tool_result_decision',
+        'user_task_notification',
+        'system_passthrough',
+    ],
+    /** 如实留白——写不动/依赖未搬运资产的臂,#52b 起分批接。 */
+    todo: [
+        'tool_end_result → user tool_result 正常路径(需搬 wireOutputToBody/structuredToToolUseResult/mock 合成器 + TodoWrite/ReportFindings 富卡片,约 600 行;workflow 轮询信封的人话投影已在 workflow.ts 就位,等这条接线)',
+        'tool_end_result 的两个侧产物:Remember → memory_saved 系统消息、task/task-list structured → 面板台账全量同步',
+        'result/turn 末的开卡兜底关闭(同上,依赖合成器)',
+        'task_progress → 面板行绑定(bindTaskCard FIFO/显式父、inline stats、alias、resident 台账、SubagentStart hook、workflow lane 三级门)',
+        'settlePanelTasks 三处 sweep(依赖上面的行台账)',
+        '#117a bg Bash 回执探测(detectEngineBgShellReceipt 文案锚定探测器)',
+        'abort/Esc 半场(AdapterContext 无 signal 位——见 SEAM-GAP-4)',
+        'IDLE_FLUSH 1.5s 竞速(件1 大 Write 静默窗;需 ctx 侧定时器能力)',
+        'macrotask 让渡(cli 在提交前让出宏任务给 Ink;宿主渲染策略,不进库)',
+    ],
+};
+/** 本批**已知的、有意的**行为分歧(差分守卫显式登记,绝不当等价) */
+export const ADAPTER_DIVERGENCES = [
+    'DIVERGENCE-1:`user` 帧透传——cli 的 switch 无 user 臂(default 丢弃),adapt 原样透传。' +
+        '现役 wire 不产 user 帧(eventToSdkMessage 无该出口),故对真流是惰性的;保留是为了 desktop 重放存量转录。',
+    'DIVERGENCE-2:transcript uuid 取值形——cli 铸随机 v4 / 原样透传帧 uuid,adapt 一律走 ' +
+        'deriveTranscriptId(稳定键前缀形 `wid_*`)。差分守卫按「别名结构」比对(同一侧内的复用/区分关系),不比字面值。',
+    'DIVERGENCE-3:合并节流的**分片边界**不比对——cli 用 Date.now() 真时钟,adapt 用 ctx.now()。' +
+        '守卫比对的是 chrome 增量按 channel 拼接后的全文与顺序(语义不变量),不是 chunk 切分。',
+];
+const TASK_NOTIFICATION_TAG = 'task-notification';
+const TASK_ID_TAG = 'task-id';
+const STATUS_TAG = 'status';
+/**
+ * 适配器实例 —— **台账**(通知去重/跨通道记账)挂实例,`adapt()` 每 turn 调一次,turn 级状态在
+ * 调用内。跨 turn 语义(进程级去重)因此靠「同一个实例贯穿 session」保证,重启靠 import/export。
+ */
+class WireToCcAdapterImpl {
+    renderedNotifications = new Set();
+    notifiedRuns = new Set();
+    cardEnqueuedRuns = new Set();
+    /** W1 三级判据素材:本壳见过的 Workflow 工具 tool_use id(module 级台账的实例化)。 */
+    seenWorkflowToolCallIds = new Set();
+    exportLedger() {
+        return {
+            version: 1,
+            renderedNotifications: [...this.renderedNotifications],
+            notifiedRuns: [...this.notifiedRuns],
+            cardEnqueuedRuns: [...this.cardEnqueuedRuns],
+        };
+    }
+    importLedger(state) {
+        let n = 0;
+        const take = (v, into) => {
+            if (!Array.isArray(v))
+                return;
+            for (const k of v) {
+                if (typeof k === 'string' && k.length > 0 && !into.has(k)) {
+                    into.add(k);
+                    n++;
+                }
+            }
+        };
+        const s = state;
+        take(s.renderedNotifications, this.renderedNotifications);
+        take(s.notifiedRuns, this.notifiedRuns);
+        take(s.cardEnqueuedRuns, this.cardEnqueuedRuns);
+        return n;
+    }
+    /**
+     * #63 —— completion inbox 是 at-least-once 而去重面纯内存,重启即蒸发;「通知 user-turn 已落盘、
+     * ack 未落」的 crash 窗口重放 = 同一完成二次喂模型。落盘转录里的 `<task-notification>` 块携
+     * task-id/status/type="external",恰可重建**无 seq 键形**;Monitor 的 `:seq` 批键形不同,绝不误伤。
+     */
+    importLedgerFromTranscript(messages) {
+        const unescape = (s) => s
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'")
+            .replace(/&amp;/g, '&');
+        let seeded = 0;
+        for (const m of messages) {
+            const rec = m;
+            if (rec?.type !== 'user')
+                continue;
+            const content = rec.message?.content;
+            const texts = [];
+            if (typeof content === 'string')
+                texts.push(content);
+            else if (Array.isArray(content)) {
+                for (const b of content) {
+                    const bb = b;
+                    if (bb?.type === 'text' && typeof bb.text === 'string')
+                        texts.push(bb.text);
+                }
+            }
+            for (const text of texts) {
+                if (!text.includes(`<${TASK_NOTIFICATION_TAG}`))
+                    continue;
+                const blockRe = new RegExp(`<${TASK_NOTIFICATION_TAG}(\\s[^>]*)?>([\\s\\S]*?)</${TASK_NOTIFICATION_TAG}>`, 'g');
+                for (const bm of text.matchAll(blockRe)) {
+                    const attrs = bm[1] ?? '';
+                    const body = bm[2] ?? '';
+                    const idM = body.match(new RegExp(`<${TASK_ID_TAG}>([\\s\\S]*?)</${TASK_ID_TAG}>`));
+                    const stM = body.match(new RegExp(`<${STATUS_TAG}>([\\s\\S]*?)</${STATUS_TAG}>`));
+                    if (!idM || !stM)
+                        continue;
+                    const taskId = unescape(idM[1] ?? '');
+                    const status = unescape(stM[1] ?? '');
+                    if (taskId.length === 0 || status.length === 0)
+                        continue;
+                    const external = /\btype="external"/.test(attrs);
+                    this.renderedNotifications.add(`${external ? 'external:' : ''}${taskId}:${status}`);
+                    if (!external && (status === 'completed' || status === 'failed' || status === 'killed')) {
+                        this.notifiedRuns.add(taskId);
+                    }
+                    seeded++;
+                }
+            }
+        }
+        return seeded;
+    }
+    noteCardEnqueued(runId) {
+        this.cardEnqueuedRuns.add(runId);
+    }
+    async *adapt(frames, ctx) {
+        const turnStartAt = ctx.now();
+        // ── id 派生 ────────────────────────────────────────────────────────────────────────────────
+        // [1653]:稳定键优先序 = 帧 id > seq > toolCallId,全缺才 ctx.uuid()。现役 wire 的稳定键落在
+        // `uuid` 字段(§E2 core 铸的 eventId / stamp 铸的帧 id),故映到 `id` 位喂进去(见 SEAM-GAP-1)。
+        // `suffix` = 同一帧派生多条消息时的去撞位(如 tool_use 卡 + 同帧的 reject 结果)。
+        const idOf = (frame, suffix) => {
+            const base = typeof frame.id === 'string' && frame.id.length > 0
+                ? frame.id
+                : typeof frame.uuid === 'string' && frame.uuid.length > 0
+                    ? frame.uuid
+                    : undefined;
+            return deriveTranscriptId({
+                ...(base !== undefined ? { id: suffix !== undefined ? `${base}#${suffix}` : base } : {}),
+                ...(typeof frame.seq === 'number' ? { seq: frame.seq } : {}),
+                ...(typeof frame.toolCallId === 'string' ? { toolCallId: frame.toolCallId } : {}),
+            }, ctx);
+        };
+        // ── turn 级状态(cli generator 局部变量的等价) ──────────────────────────────────────────────
+        let answer = '';
+        let answerSegment = '';
+        let thinking = '';
+        let emittedAssistantText = false;
+        let textPending = '';
+        let thinkingPending = '';
+        let textBlockOpen = false;
+        let thinkingBlockOpen = false;
+        let lastFlushAt = 0;
+        let messageStartEmitted = false;
+        let endEmitted = false;
+        let assistantResponseId = null;
+        /** committed 消息的 id 锚 —— 该段/该思考块的**第一帧**(重放确定性:同流同 id)。 */
+        let segmentAnchor = null;
+        let thinkingAnchor = null;
+        const pending = new Map();
+        const chrome = (event) => ({ plane: 'chrome', event });
+        const transcript = (message) => ({
+            plane: 'transcript',
+            message: message,
+        });
+        const mintResponseId = (frame) => (assistantResponseId ??= `msg_sema_${idOf(frame, 'resp')}`);
+        /** 提交累积的思考块(cli takeThinking:committed 形 + 关活体块 + 收活动行)。 */
+        function* takeThinking() {
+            if (thinking.length === 0)
+                return;
+            const anchor = thinkingAnchor ?? {};
+            const msg = {
+                type: 'assistant',
+                message: { role: 'assistant', content: [{ type: 'thinking', thinking }] },
+                uuid: idOf(anchor, 'thinking'),
+                session_id: ctx.sessionId,
+                parent_tool_use_id: null,
+            };
+            thinking = '';
+            thinkingAnchor = null;
+            thinkingBlockOpen = false;
+            // P2d:活体 "∴ Thinking…" 行在 committed 块落地的**同一刻**收掉(先收行再上消息,cli 同序)
+            yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: false });
+            yield transcript(msg);
+        }
+        /** 提交累积的文本段(cli takeAnswerSegment:#27 段序铁律——工具卡前/turn 末各 flush 一次)。 */
+        function* takeAnswerSegment() {
+            if (answerSegment.length === 0)
+                return;
+            const anchor = segmentAnchor ?? {};
+            const msg = {
+                type: 'assistant',
+                message: { role: 'assistant', content: [{ type: 'text', text: answerSegment }] },
+                uuid: idOf(anchor, 'text'),
+                session_id: ctx.sessionId,
+                parent_tool_use_id: null,
+            };
+            answerSegment = '';
+            segmentAnchor = null;
+            emittedAssistantText = true;
+            textBlockOpen = false;
+            yield transcript(msg);
+        }
+        /** 合并后的活体增量下泄(cli drainLive:思考先于文本 = 持久臂序)。 */
+        function* drainLive() {
+            if (thinkingPending.length > 0) {
+                const opening = !thinkingBlockOpen;
+                thinkingBlockOpen = true;
+                yield chrome({
+                    kind: 'stream_delta',
+                    laneProof: MAIN,
+                    channel: 'thinking',
+                    text: thinkingPending,
+                    estimatedTokens: estimateCjkTokens(thinkingPending),
+                    opening,
+                });
+                thinkingPending = '';
+            }
+            if (textPending.length > 0) {
+                const opening = !textBlockOpen;
+                textBlockOpen = true;
+                yield chrome({
+                    kind: 'stream_delta',
+                    laneProof: MAIN,
+                    channel: 'text',
+                    text: textPending,
+                    estimatedTokens: estimateCjkTokens(textPending),
+                    opening,
+                });
+                textPending = '';
+            }
+        }
+        // turn 开场卫生(cli:清上一 turn 的 retry 覆盖层 + 思考活动行,再发 request-start)。
+        yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
+        yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: false });
+        yield chrome({ kind: 'request_start', laneProof: MAIN });
+        for await (const rawFrame of frames) {
+            const m = rawFrame;
+            if (m === null || typeof m !== 'object')
+                continue;
+            if (m.type === 'stream_event' && !messageStartEmitted) {
+                messageStartEmitted = true;
+                yield chrome({
+                    kind: 'response_metrics',
+                    laneProof: MAIN,
+                    phase: 'start',
+                    ttftMs: ctx.now() - turnStartAt,
+                });
+            }
+            // 持久臂之前先把活体增量泄干净(活体预览恒先于它 settle 成的 committed 消息)。
+            if (m.type !== 'stream_event')
+                yield* drainLive();
+            switch (m.type) {
+                case 'assistant': {
+                    const message = m.message;
+                    const blocks = Array.isArray(message?.content)
+                        ? message.content
+                        : [];
+                    const toolUseIdx = blocks.findIndex(b => b?.type === 'tool_use');
+                    if (toolUseIdx >= 0) {
+                        const original = blocks[toolUseIdx];
+                        const decision = decisionOf(original);
+                        const san = sanitizeToolUseBlock(original);
+                        const renderBlocks = blocks.map((b, i) => (i === toolUseIdx ? san.block : b));
+                        const toolUseId = String(san.block.id);
+                        const toolName = typeof san.block.name === 'string' ? san.block.name : 'unknown';
+                        // 引擎模式下壳工具 call() 从不执行 —— ctrl+t 面板台账只能靠这条侧信道(宿主义务)。
+                        if (TASK_TOOL_NAMES.has(toolName)) {
+                            yield chrome({
+                                kind: 'task_ledger_sync',
+                                laneProof: MAIN,
+                                source: 'tool_use',
+                                toolName,
+                                toolUseId,
+                                input: san.block.input,
+                            });
+                        }
+                        // #27 段序:先把这张卡之前的散文提交,再提交它之前的思考(思考恒在卡上方)。
+                        yield* takeAnswerSegment();
+                        yield* takeThinking();
+                        yield transcript({
+                            type: 'assistant',
+                            // S1:per-RESPONSE 铸 id —— CC 的 grouped-agent 渲染按 `${message.id}:${toolName}`
+                            // 分组;id-less 帧会把整个 session 的 Agent 卡塌成一张。tool_use 帧才盖章。
+                            message: { id: mintResponseId(m), role: 'assistant', content: renderBlocks },
+                            uuid: idOf(m),
+                            session_id: ctx.sessionId,
+                            parent_tool_use_id: null,
+                        });
+                        if (decision === 'reject' || decision === 'cancel') {
+                            yield transcript({
+                                type: 'user',
+                                message: {
+                                    role: 'user',
+                                    content: [
+                                        {
+                                            type: 'tool_result',
+                                            tool_use_id: san.block.id,
+                                            content: decision === 'reject' ? REJECT_MESSAGE : CANCEL_MESSAGE,
+                                            is_error: false,
+                                        },
+                                    ],
+                                },
+                                uuid: idOf(m, decision),
+                                session_id: ctx.sessionId,
+                            });
+                            assistantResponseId = null; // 一个结果关闭该 model response
+                            break;
+                        }
+                        if (decision === 'error') {
+                            yield transcript({
+                                type: 'user',
+                                message: {
+                                    role: 'user',
+                                    content: [
+                                        {
+                                            type: 'tool_result',
+                                            tool_use_id: san.block.id,
+                                            content: 'The tool failed to execute.',
+                                            is_error: true,
+                                        },
+                                    ],
+                                },
+                                uuid: idOf(m, 'error'),
+                                session_id: ctx.sessionId,
+                            });
+                            assistantResponseId = null;
+                            break;
+                        }
+                        pending.set(toolUseId, {
+                            id: toolUseId,
+                            name: toolName,
+                            rawInput: san.rawInput,
+                            ...(san.eventId !== undefined ? { eventId: san.eventId } : {}),
+                            ...(san.parentToolCallId !== undefined ? { parentToolCallId: san.parentToolCallId } : {}),
+                        });
+                        if (WORKFLOW_TOOL_NAMES.has(toolName))
+                            this.seenWorkflowToolCallIds.add(toolUseId);
+                        break;
+                    }
+                    const textBlock = blocks.find(b => b?.type === 'text');
+                    if (textBlock && typeof textBlock.text === 'string' && textBlock.text.length > 0) {
+                        answer += textBlock.text;
+                        yield* takeThinking();
+                        yield transcript({
+                            type: 'assistant',
+                            message: { role: 'assistant', content: [{ type: 'text', text: textBlock.text }] },
+                            uuid: idOf(m),
+                            session_id: ctx.sessionId,
+                            parent_tool_use_id: null,
+                        });
+                        emittedAssistantText = true;
+                    }
+                    const thinkingBlock = blocks.find(b => b?.type === 'thinking');
+                    if (thinkingBlock && typeof thinkingBlock.thinking === 'string') {
+                        yield transcript({
+                            type: 'assistant',
+                            message: { role: 'assistant', content: [thinkingBlock] },
+                            uuid: idOf(m, 'durable-thinking'),
+                            session_id: ctx.sessionId,
+                            parent_tool_use_id: null,
+                        });
+                    }
+                    break;
+                }
+                // DIVERGENCE-1 —— 现役 wire 不产 user 帧;透传是给 desktop 重放存量转录留的门。
+                case 'user': {
+                    if (m.message === undefined)
+                        break;
+                    yield transcript({ ...m, uuid: idOf(m), session_id: ctx.sessionId });
+                    break;
+                }
+                case 'tool_end_result': {
+                    // 本批只做**卡台账出栈 + response-id 复位**(S1:一个结果关闭该 response,后续 tool_use
+                    // 必须换新 id 才不会被 CC 分组塌成一张卡)。tool_result 消息本体见 ADAPTER_COVERAGE.todo。
+                    const callId = typeof m.toolCallId === 'string' ? m.toolCallId : undefined;
+                    if (callId !== undefined && pending.has(callId)) {
+                        pending.delete(callId);
+                        assistantResponseId = null;
+                    }
+                    break;
+                }
+                case 'stream_event': {
+                    const ev = m.event;
+                    if (ev && ev.type === 'text_delta' && typeof ev.delta === 'string') {
+                        // MOD-1 思考→回答边界:回答一起头就把思考块 committed 上屏(它推理的内容之前)。
+                        if (thinking.length > 0 || thinkingPending.length > 0) {
+                            yield* drainLive();
+                            yield* takeThinking();
+                        }
+                        if (answerSegment.length === 0)
+                            segmentAnchor = m;
+                        answer += ev.delta;
+                        answerSegment += ev.delta;
+                        textPending += ev.delta;
+                    }
+                    else if (ev && ev.type === 'thinking_delta' && typeof ev.delta === 'string') {
+                        // 子流(parentToolCallId)的推理绝不喂 leader 的计数与预览(#9 的壳侧半场)。
+                        if (ev.parentToolCallId !== undefined)
+                            break;
+                        if (thinking.length === 0) {
+                            thinkingAnchor = m;
+                            // P2d:elapsed 锚在**首条** leader 推理增量(token 累计由 stream_delta.estimatedTokens
+                            // 承载,宿主自加;>30s 无增量的 stall 提示同样由宿主按增量时间戳判)。
+                            yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: true });
+                        }
+                        thinking += ev.delta;
+                        thinkingPending += ev.delta;
+                    }
+                    break;
+                }
+                case 'turn_usage': {
+                    const ot = typeof m.outputTokens === 'number' ? m.outputTokens : undefined;
+                    if (ot != null) {
+                        yield* drainLive();
+                        yield chrome({ kind: 'response_metrics', laneProof: MAIN, phase: 'end', outputTokens: ot });
+                        endEmitted = true;
+                        messageStartEmitted = false; // 下一 model round 重新压基线
+                    }
+                    break;
+                }
+                case 'result': {
+                    yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
+                    yield* takeThinking();
+                    if (!endEmitted) {
+                        const u = m.usage;
+                        if (typeof u?.outputTokens === 'number') {
+                            yield chrome({
+                                kind: 'response_metrics',
+                                laneProof: MAIN,
+                                phase: 'end',
+                                outputTokens: u.outputTokens,
+                            });
+                            endEmitted = true;
+                        }
+                    }
+                    yield* takeAnswerSegment();
+                    if (!emittedAssistantText) {
+                        const text = typeof m.result === 'string' ? m.result : '';
+                        if (text.length > 0) {
+                            yield transcript({
+                                type: 'assistant',
+                                message: { role: 'assistant', content: [{ type: 'text', text }] },
+                                uuid: idOf(m, 'terminal-text'),
+                                session_id: ctx.sessionId,
+                                parent_tool_use_id: null,
+                            });
+                            emittedAssistantText = true;
+                        }
+                    }
+                    break;
+                }
+                case 'system': {
+                    yield transcript(m);
+                    // core 1.219 attachWorkingFiles:compact_boundary 可携 attachedFiles → CC 的
+                    // "Referenced file {path}" 行(post-compact attachment,零新 UI)。
+                    const attachedFiles = m.attachedFiles;
+                    if (Array.isArray(attachedFiles)) {
+                        let i = 0;
+                        for (const f of attachedFiles) {
+                            if (typeof f?.path !== 'string' || f.path.length === 0)
+                                continue;
+                            yield chrome({
+                                kind: 'attachment',
+                                laneProof: MAIN,
+                                id: idOf(m, `attached-file-${i++}`),
+                                attachment: {
+                                    type: 'compact_file_reference',
+                                    filename: f.path,
+                                    displayPath: f.path,
+                                },
+                            });
+                        }
+                    }
+                    break;
+                }
+                case 'task_notification': {
+                    const n = (m.notification ?? {});
+                    const fields = normalizeTaskNotification(n);
+                    if (fields === null)
+                        break; // 空/缺 task_id:RB-75 同族,丢弃
+                    const taskId = fields.taskId;
+                    const rawStatus = fields.status;
+                    const terminal = rawStatus === 'completed' || rawStatus === 'failed' || rawStatus === 'killed';
+                    // #117a settle 半场 —— **故意在渲染去重之前**:settle 幂等,重放帧仍须 settle 一条
+                    // 首投之后才注册的行。#47 矩阵 #7:只有 bash 行(或老引擎无 task_type)能被 settle。
+                    const settleAllowed = n.task_type === undefined || n.task_type === 'background_bash';
+                    if (settleAllowed && terminal) {
+                        yield chrome({
+                            kind: 'bgshell_settle',
+                            laneProof: MAIN,
+                            taskId,
+                            status: rawStatus,
+                            ...(typeof n.output_file === 'string' && n.output_file.length > 0
+                                ? { outputPath: n.output_file }
+                                : {}),
+                        });
+                    }
+                    const dedupKey = taskNotificationDedupKey({
+                        taskId,
+                        status: rawStatus,
+                        ...(typeof n.seq === 'number' || typeof n.seq === 'string' ? { seq: n.seq } : {}),
+                        ...(typeof n.task_type === 'string' ? { taskType: n.task_type } : {}),
+                    });
+                    if (this.renderedNotifications.has(dedupKey))
+                        break;
+                    this.renderedNotifications.add(dedupKey);
+                    // B1 + #6 —— 必须在 cardEnqueued 早退**之前**:probe 合成先入队的场景恰是双投主形。
+                    if (n.task_type !== 'external' && terminal) {
+                        yield chrome({
+                            kind: 'notification_terminal',
+                            laneProof: MAIN,
+                            taskId,
+                            status: rawStatus,
+                            ...(typeof n.task_type === 'string' ? { taskType: n.task_type } : {}),
+                        });
+                        if (n.task_type !== 'background_bash') {
+                            yield chrome({
+                                kind: 'panel_task',
+                                laneProof: MAIN,
+                                event: { kind: 'end', taskId, isError: rawStatus !== 'completed' },
+                            });
+                            yield chrome({
+                                kind: 'subagent_lifecycle',
+                                laneProof: MAIN,
+                                phase: 'stop',
+                                taskId,
+                                guard: 'if-started',
+                            });
+                        }
+                    }
+                    // 双通道反向去重:probe 合成的完成卡已入队 ⇒ 后到的推送帧只做上面的记账,不渲第二条。
+                    if (n.task_type !== 'external' && this.cardEnqueuedRuns.has(taskId))
+                        break;
+                    // 跨通道记账(cli markEngineWorkflowNotified 同位、同条件:非 external,不看终态):
+                    // 这帧到达 = 引擎已 server-side steer-inject 过,补发通道(workflow_complete)不得再注入。
+                    // external 豁免([769] 对抗复审收紧:external 从不经补发通道,mark 只会缴械 probe 兜底)。
+                    if (n.task_type !== 'external')
+                        this.notifiedRuns.add(taskId);
+                    yield transcript({
+                        type: 'user',
+                        message: { role: 'user', content: [{ type: 'text', text: renderTaskNotificationXml(fields) }] },
+                        uuid: idOf(m),
+                        session_id: ctx.sessionId,
+                    });
+                    break;
+                }
+                case 'workflow_complete': {
+                    const runId = typeof m.runId === 'string' ? m.runId : undefined;
+                    if (runId === undefined)
+                        break;
+                    // 跨通道去重(cli enqueueEngineWorkflowNotification 首行):该 run 已由推送帧记账过
+                    // (引擎 server-side 注入过)⇒ Path B 绝不再喂模型一遍。适配器自持,不摊给宿主。
+                    if (this.notifiedRuns.has(runId))
+                        break;
+                    this.notifiedRuns.add(runId);
+                    const wfStatus = m.status === 'failed' ? 'failed' : 'completed';
+                    const wfSummary = typeof m.summary === 'string' ? m.summary : '';
+                    yield chrome({
+                        kind: 'workflow_notification_enqueue',
+                        laneProof: MAIN,
+                        runId,
+                        status: wfStatus,
+                        summary: wfSummary,
+                        // 模型面正文照铸(宿主直接入队即可,不必各自拼 XML;与 core 的 tag/段序同形)
+                        message: renderTaskNotificationXml({ taskId: runId, status: wfStatus, summary: wfSummary }),
+                    });
+                    this.cardEnqueuedRuns.add(runId);
+                    break;
+                }
+                case 'diagnostics': {
+                    if (typeof m.parentToolCallId === 'string')
+                        break; // 子流帧不上 leader 面
+                    const att = projectDiagnosticsFrame(m);
+                    if (att === null)
+                        break;
+                    yield chrome({ kind: 'attachment', laneProof: MAIN, id: idOf(m), attachment: att });
+                    break;
+                }
+                case 'steering_injected': {
+                    if (typeof m.parentToolCallId === 'string')
+                        break;
+                    const source = typeof m.source === 'string' ? m.source : '';
+                    if (source.length === 0)
+                        break;
+                    const preview = typeof m.preview === 'string' ? m.preview : '';
+                    let i = 0;
+                    for (const att of steeringInjectedToAttachments(source, preview)) {
+                        yield chrome({
+                            kind: 'attachment',
+                            laneProof: MAIN,
+                            id: idOf(m, `steering-${i++}`),
+                            attachment: att,
+                        });
+                    }
+                    break;
+                }
+                case 'workspace_changed': {
+                    if (typeof m.parentToolCallId === 'string')
+                        break;
+                    const cwd = typeof m.cwd === 'string' ? m.cwd : '';
+                    if (cwd.length === 0)
+                        break;
+                    yield chrome({
+                        kind: 'attachment',
+                        laneProof: MAIN,
+                        id: idOf(m),
+                        attachment: { type: 'workspace_changed', cwd },
+                    });
+                    break;
+                }
+                case 'retry_status': {
+                    // #47 矩阵 #5:子代 lane 帧绝不骑主 spinner(无判别守卫的无条件 store 写=默认可疑)。
+                    if (typeof m.parentToolCallId === 'string')
+                        break;
+                    yield chrome({
+                        kind: 'retry_status',
+                        laneProof: MAIN,
+                        status: mapBrainStatusToRetry({
+                            phase: typeof m.phase === 'string' ? m.phase : '',
+                            ...(typeof m.detail === 'string' ? { detail: m.detail } : {}),
+                            ...(typeof m.retryInSec === 'number' ? { retryInSec: m.retryInSec } : {}),
+                        }, ctx.now()),
+                    });
+                    break;
+                }
+                default:
+                    break;
+            }
+            // COALESCER 节拍:一个间隔至多一次 flush(同步 SSE 突发先攒着,过闸再一次泄干)。
+            if (m.type === 'stream_event') {
+                const now = ctx.now();
+                if ((textPending.length > 0 || thinkingPending.length > 0) && now - lastFlushAt >= FLUSH_INTERVAL_MS) {
+                    yield* drainLive();
+                    lastFlushAt = now;
+                }
+            }
+        }
+        // turn 收口(cli 尾部同序):泄尾增量 → 清 liveness → 提交尾思考 → 提交尾文本段。
+        yield* drainLive();
+        yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
+        yield* takeThinking();
+        yield* takeAnswerSegment();
+        void answer; // 全流无 text 臂时的兜底源(result 臂已消费);保留供调试/后续批
+    }
+}
+/** 造一个带台账的适配器实例(**一个 session 一个**——跨 turn 去重靠实例存活,重启靠 import/export)。 */
+export function createWireToCcAdapter() {
+    return new WireToCcAdapterImpl();
+}
+/** 一次性(无跨 turn 台账)投影:`frames → AdapterOutput`。多 turn 请用 createWireToCcAdapter()。 */
+export function adapt(frames, ctx) {
+    return createWireToCcAdapter().adapt(frames, ctx);
+}