@sema-agent/client-core 0.3.0 → 0.5.0

package/dist/adapter/downstream/terminalToSdkResult.js

@@ -0,0 +1,370 @@
+import { stamp } from '../types.js';
+/** Flatten TaskStats → the CC NonNullableUsage placeholder (z.unknown()). */
+function flattenUsage(stats) {
+    return {
+        inputTokens: stats?.promptTokens ?? 0,
+        outputTokens: stats?.outputTokens ?? 0,
+        cacheReadInputTokens: stats?.cachedTokens ?? 0,
+        cacheCreationInputTokens: 0,
+        webSearchRequests: 0,
+    };
+}
+/**
+ * MF-25 — map the wire's per-model usage split (`stats.modelUsage`, an open `{ <modelId>: usage }` map;
+ * e.g. `{ "deepseek-v4-pro": {...} }`) into the CC `SDKResult.modelUsage` record (model-id → CC ModelUsage).
+ * The wire usage names (`cacheReadTokens`/`cacheWriteTokens`/`costMicroUsd`) are re-pinned to the CC names
+ * (`cacheReadInputTokens`/`cacheCreationInputTokens`/`costUSD`, costMicroUsd/1e6 → USD), matching
+ * turnUsageToModelUsage. `contextWindow`/`maxOutputTokens` are not on the wire → 0. Returns `{}` when absent.
+ */
+/** P1-5 — real elapsed ms since the stream opened (runStream stamps startedAtMs); 0 only pre-stamp. */
+function elapsedMs(ctx) {
+    return typeof ctx.startedAtMs === 'number' ? Math.max(0, Date.now() - ctx.startedAtMs) : 0;
+}
+/**
+ * P1-5 — `total_cost_usd` truthfulness: `costUsd === 0` is AMBIGUOUS (free vs. no MODEL_COST_* configured
+ * on the worker — the local TOC engine ships unconfigured, so `-p --output-format json` was reporting a
+ * fake `0`). Emit the number only when it is a REAL positive cost; otherwise `null` (JSON consumers see
+ * "unknown", never a fabricated zero). CC's schema field is numeric — number-guarded readers
+ * (replEntry cost fold) already treat non-number as absent.
+ */
+function costOrNull(costUsd) {
+    return typeof costUsd === 'number' && costUsd > 0 ? costUsd : null;
+}
+// 件2a(中断事故修复批 G,2026-07-15,症状2 第一环):参数放宽 TaskStats | undefined + 全链守卫。
+// 409 active-run 拒绝时引擎的 done 帧本体是 {status:'failed', errorMessage, activeTaskId} —— NO stats
+// (ai-agent-service server.ts:1526 同型),此前 :59 裸读 (stats).modelUsage 直接 TypeError,炸穿
+// runStream → seamQuery catch → 误诊 "engine is unreachable"(件2c)。缺 stats 时产出合法空 usage
+// 形状(flattenUsage 本就守卫;这里返回 {},调用方 :98 再按 r.model 合成当前行)。
+function mapModelUsage(stats) {
+    const raw = stats?.modelUsage;
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const out = {};
+    for (const [modelId, u] of Object.entries(raw)) {
+        if (!u || typeof u !== 'object')
+            continue;
+        const m = u;
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+        out[modelId] = {
+            inputTokens: num(m.inputTokens),
+            outputTokens: num(m.outputTokens),
+            cacheReadInputTokens: num(m.cacheReadTokens),
+            cacheCreationInputTokens: num(m.cacheWriteTokens),
+            webSearchRequests: 0,
+            costUSD: num(m.costMicroUsd) / 1e6,
+            contextWindow: 0,
+            maxOutputTokens: 0,
+        };
+    }
+    return out;
+}
+/** `done` → SDKResultSuccess (contract 02 §2.10 / 08 CS-10). */
+export function doneToSdkResult(ev, ctx) {
+    const r = ev.result;
+    // 件2a:409/failed 形态的 done 帧不带 stats —— 本函数全链按 undefined 守卫(:97/:121/:145)。
+    const stats = r.stats;
+    // P1-5 — the terminal frame's session_id must be the ENGINE-AUTHORITATIVE id (done.result.sessionId):
+    // on the headless `-p` path ctx was seeded from the REQUEST (historically the mock constant
+    // "sema-mock-session-0001" leaked to stdout, so `sema -r <session_id>` on the JSON output could never
+    // resume). The engine echo is the id its session store actually keyed — adopt it for the result stamp.
+    const echoedSid = r.sessionId;
+    if (typeof echoedSid === 'string' && echoedSid.length > 0)
+        ctx.sessionId = echoedSid;
+    // P1-5 — modelUsage: prefer the wire's per-model split; when absent (local engine pre-MF-25 stats or a
+    // split-less done), synthesize the CURRENT model's row from the flat TaskStats so JSON consumers always
+    // see which model produced the run's usage.
+    const usage = flattenUsage(stats);
+    let modelUsage = mapModelUsage(stats);
+    if (Object.keys(modelUsage).length === 0 && typeof r.model === 'string' && r.model.length > 0) {
+        modelUsage = {
+            [r.model]: {
+                ...usage,
+                costUSD: typeof stats?.costUsd === 'number' ? stats.costUsd : 0,
+                contextWindow: 0,
+                maxOutputTokens: 0,
+            },
+        };
+    }
+    // clay P0 壳半场(黑板 [450],2026-07-05):上游 4xx(如无 vision 模型收到 image)时
+    // 引擎的 done 帧本体带 result.status='failed' + errorMessage —— 传播链没吞,断点在这:
+    // 此前无条件投影 subtype:'success'/is_error:false,把失败洗成"成功空回复"= 用户看到的
+    // 静默卡死。status failed → 走 SDKResultError 形态(errors[] 渲染线现成)。
+    // TS2367 note: `TaskResult & { status?: string }` does NOT actually widen `status` — TS
+    // intersects the pre-existing required `RunStatus` with the added optional `string`, and
+    // `RunStatus & string` stays `RunStatus` (the narrower member wins). That's exactly why the
+    // `rr.status === 'timeout'` / `'blocked'` branches below (real @sema-agent/sdk RunStatus is
+    // still a 5-word closed union — core's actual TaskStatus vocab is 6 words, see file header)
+    // used to type-error as "no overlap": the cast looked like a widening but wasn't one. `Omit`
+    // the narrow key first so the added wider `status?: string` actually applies.
+    const rr = r;
+    const durationMs = elapsedMs(ctx);
+    // [909]B1 — errorCode 透传(additive seam 字段;CC schema 无此键,与 success 臂 `model` 同款超集
+    // 姿势):引擎值原样,绝不铸造。所有 error 臂共用。
+    const errorCodeField = typeof rr.errorCode === 'string' && rr.errorCode.length > 0 ? { errorCode: rr.errorCode } : {};
+    if (rr.status === 'failed') {
+        // [909]B1 — failed 臂 subtype 语义化(见文件头对表):budget.* → error_max_budget_usd(与
+        // failedToSdkResult 事件臂同款分流,此前 done{failed} 恒 error_during_execution);
+        // limit.max_turns → error_max_turns;output.invalid → error_max_structured_output_retries
+        // (assemble-result.js:58 该 code 的语义字面就是 CC 这词:「did not produce a valid structured
+        // output within the retry limit」);其余(cancelled/conflict/provider 错…)维持
+        // error_during_execution。
+        const failedSubtype = rr.errorCode === 'budget.exceeded' || rr.errorCode === 'budget.precall'
+            ? 'error_max_budget_usd'
+            : rr.errorCode === 'limit.max_turns'
+                ? 'error_max_turns'
+                : rr.errorCode === 'output.invalid'
+                    ? 'error_max_structured_output_retries'
+                    : 'error_during_execution';
+        return stamp(ctx, {
+            // Explicit (always-undefined) uuid/session_id: stamp() always overwrites session_id from
+            // ctx and falls back to a fresh uuid when body.uuid is nullish, so this is a pure type-level
+            // nudge (zero runtime effect) — without at least one property name in common with stamp's
+            // all-optional constraint, TS's "weak type" detection rejects the call (TS2559/TS2345/TS2353).
+            uuid: undefined,
+            session_id: undefined,
+            type: 'result',
+            subtype: failedSubtype,
+            duration_ms: durationMs, // P1-5 real elapsed (stream-open → terminal)
+            duration_api_ms: durationMs, // engine run == the API call from the shell's view
+            is_error: true,
+            num_turns: stats?.turns ?? 0,
+            stop_reason: null,
+            total_cost_usd: costOrNull(stats?.costUsd), // P1-5: null when unknown, never a fake 0
+            usage,
+            modelUsage,
+            permission_denials: [],
+            // rewind 族错误码透传(server 1.192 [838]③ 实测:stream 腿把 resume_at.before_* /
+            // rewind_snapshot.unresolvable 骑在 done{status:"failed"} 帧的 errorCode 上,非 `failed` 帧)——
+            // 与 failedToSdkResult 的同款 append 对齐,message 后附 code 便于对账。
+            errors: [
+                typeof rr.errorCode === 'string' &&
+                    (rr.errorCode.startsWith('resume_at.') || rr.errorCode.startsWith('rewind_snapshot.')) &&
+                    rr.errorMessage
+                    ? `${rr.errorMessage} (${rr.errorCode})`
+                    : (rr.errorMessage ?? 'run failed'),
+            ],
+            ...errorCodeField,
+        });
+    }
+    // [909]B1 — timeout 终态:--deadline 配速的受控截止收尾(assemble-result.js:69/88
+    // errorCode=limit.timeout,"walltime cutoff … preserve a write-out window")。此前落 success 臂
+    // = TB 的「4 个引擎已记 timeout 的 trial 全 subtype:success」+ deadline 收尾路径缺 timeout 语义
+    // 收尾帧([909]B2 关联半场;帧完整落地由 stdout drain 半场保证)。subtype 选型见文件头对表:
+    // CC 词表无 wall-clock 词,唯一 run-limit 族词 = error_max_turns;精确语义靠 errors[] 文案 +
+    // errorCode:"limit.timeout" 透传。rc 语义顺出:print.ts gracefulShutdownSync(is_error ? 1 : 0)。
+    // TaskResult 五键最小消费批([1543] SDK-M,2026-07-23):additive seam 字段——
+    //  · degraded = 模型降级链实录(from/to/reason/atTurn;多模型网关部署的关键可观测面)——
+    //    success/timeout/blocked/unknown 各终态都可能带,恒 additive 附上;
+    //  · structuredOutput = outputSchema 任务的结构化产出(success 臂);
+    //  · salvagedOutput = degenerate/timeout 抢救出的最后模型文本(timeout 臂 salvage 回落源)。
+    const degradedField = (() => {
+        const d = r.degraded;
+        return d !== undefined && d !== null && typeof d === 'object' ? { degraded: d } : {};
+    })();
+    if (rr.status === 'timeout') {
+        const salvagedOutput = r.salvagedOutput;
+        const salvaged = typeof r.result === 'string' && r.result.trim().length > 0
+            ? r.result
+            : typeof salvagedOutput === 'string' && salvagedOutput.trim().length > 0
+                ? salvagedOutput
+                : undefined;
+        return stamp(ctx, {
+            uuid: undefined,
+            session_id: undefined,
+            type: 'result',
+            subtype: 'error_max_turns',
+            duration_ms: durationMs,
+            duration_api_ms: durationMs,
+            is_error: true,
+            num_turns: stats?.turns ?? 0,
+            stop_reason: null,
+            total_cost_usd: costOrNull(stats?.costUsd),
+            usage,
+            modelUsage,
+            permission_denials: [],
+            errors: [
+                `${rr.errorMessage ?? 'run hit its wall-clock deadline and was finalized by the engine'} (${rr.errorCode ?? 'limit.timeout'})`,
+            ],
+            ...errorCodeField,
+            // 写出窗 salvage(additive seam 字段):deadline 前引擎救回的最终文本非空时随帧带出——
+            // CC error 帧无 result 键,但静默丢弃已救回的答案对 -p 集成面是净损失(TB qe** 实证)。
+            ...(salvaged !== undefined ? { result: salvaged } : {}),
+            ...degradedField,
+        });
+    }
+    // [909]B1 — blocked 终态:agent 自报无法推进(assemble-result.js:99,只带 blockedReason 无
+    // errorCode)。此前落 success 臂(TB db-wal-recovery__uuH5cAg 实证:引擎终态 blocked、帧却
+    // subtype:success)。≠空成功 → SDKResultError,blockedReason 如实进 errors[]。
+    if (rr.status === 'blocked') {
+        const blockedReason = r.blockedReason;
+        return stamp(ctx, {
+            uuid: undefined,
+            session_id: undefined,
+            type: 'result',
+            subtype: 'error_during_execution',
+            duration_ms: durationMs,
+            duration_api_ms: durationMs,
+            is_error: true,
+            num_turns: stats?.turns ?? 0,
+            stop_reason: null,
+            total_cost_usd: costOrNull(stats?.costUsd),
+            usage,
+            modelUsage,
+            permission_denials: [],
+            errors: [
+                typeof blockedReason === 'string' && blockedReason.length > 0
+                    ? `Run blocked: ${blockedReason}`
+                    : 'Run blocked (the agent reported it cannot proceed)',
+            ],
+            ...errorCodeField,
+        });
+    }
+    // [884]A1(TB 公平 P0,2026-07-16):suspended/needs_review park 终帧不许洗成空成功。
+    // `-p` 恒 DURABLE_APPROVAL=true 起引擎;模型调 AskUserQuestion(或 plan-mode ExitPlanMode)时
+    // 引擎 park 吐 done{status:'suspended'|'needs_review'}(+ taskId/checkpointGate)。交互 REPL 有
+    // liveHitlAskWire/planReviewWire 把 park 接成对话框;print/非 REPL 无 overlay → 桥 fail-soft
+    // 原样吐终帧落到这里,此前落 success 臂 = subtype:'success'/is_error:false/result:'' →
+    // **exit 0 空成功**(评测 harness 判 0 分且零错误信号,比死等更隐蔽)。分流 SDKResultError:
+    // 三 output 形态经既有消费面各自正确(json 单文档 is_error、stream-json result 帧 is_error、
+    // text errors[0]→stderr formatTextModeExecutionError),rc≠0 由 print.ts
+    // gracefulShutdownSync(is_error ? 1 : 0) 顺出。文案带 run/session id 指路(交互 REPL resume 或
+    // approvals decide),与批 G 件2 的 409 active-run 文案同源指引——那是 409 拒的
+    // done{status:'failed', activeTaskId} 帧(上方 failed 臂),这是 park 终帧,两帧互不冲突。
+    // CC 对照:CC 2.1.207 AskUserQuestion.isEnabled 在非交互且无 SDK permissionPromptTool 时
+    // return false = 模型源头看不到该工具;core [884] 自领 1.296 加同款非交互闸(roster 源头不进)。
+    // 本分流是闸到货后的防御纵深:即便引擎吐了 suspended,壳也不许洗成空成功。
+    if (rr.status === 'suspended' || rr.status === 'needs_review') {
+        const parked = r;
+        const runId = typeof parked.taskId === 'string' && parked.taskId.length > 0 ? parked.taskId : undefined;
+        const gateTool = typeof parked.checkpointGate?.toolName === 'string' && parked.checkpointGate.toolName.length > 0
+            ? parked.checkpointGate.toolName
+            : undefined;
+        const sid = typeof ctx.sessionId === 'string' && ctx.sessionId.length > 0 ? ctx.sessionId : undefined;
+        const awaiting = rr.status === 'needs_review'
+            ? 'a plan review'
+            : `an interactive answer${gateTool ? ` (${gateTool})` : ''}`;
+        const wayOut = rr.status === 'needs_review'
+            ? `Review the plan in the interactive REPL${sid ? ` (sema --resume ${sid})` : ''}.`
+            : `Answer it in the interactive REPL${sid ? ` (sema --resume ${sid})` : ''}, or decide the pending approval via the engine approvals API${sid ? ` (POST /v1/approvals/${sid}/decide)` : ''}.`;
+        return stamp(ctx, {
+            uuid: undefined,
+            session_id: undefined,
+            type: 'result',
+            subtype: 'error_during_execution',
+            duration_ms: durationMs,
+            duration_api_ms: durationMs,
+            is_error: true,
+            num_turns: stats?.turns ?? 0, // 件2a 同款守卫 —— park 帧多数不带 stats,不炸
+            stop_reason: null,
+            total_cost_usd: costOrNull(stats?.costUsd),
+            usage,
+            modelUsage,
+            permission_denials: [],
+            errors: [
+                `Turn suspended awaiting ${awaiting} that no one can provide in -p (non-interactive) mode${runId ? ` (run ${runId})` : ''}. ${wayOut}`,
+            ],
+            ...errorCodeField, // [909]B1 — needs_review 帧带 review.pending,原样透传
+        });
+    }
+    // [909]B1 — 防御臂:词表外的未知非 completed 终态(core 未来加词/未知 wire 变形)绝不洗成
+    // 空成功——error_during_execution + errors[] 如实报出该 status 字面。absent status(mock 车道 /
+    // 旧引擎 done 帧不带 status)维持 success 臂,零行为变化。
+    if (typeof rr.status === 'string' && rr.status.length > 0 && rr.status !== 'completed') {
+        return stamp(ctx, {
+            uuid: undefined,
+            session_id: undefined,
+            type: 'result',
+            subtype: 'error_during_execution',
+            duration_ms: durationMs,
+            duration_api_ms: durationMs,
+            is_error: true,
+            num_turns: stats?.turns ?? 0,
+            stop_reason: null,
+            total_cost_usd: costOrNull(stats?.costUsd),
+            usage,
+            modelUsage,
+            permission_denials: [],
+            errors: [
+                rr.errorMessage ??
+                    `run ended with terminal status "${rr.status}" (not a success; this CLI predates that status word)`,
+            ],
+            ...errorCodeField,
+        });
+    }
+    return stamp(ctx, {
+        uuid: undefined,
+        session_id: undefined,
+        type: 'result',
+        subtype: 'success',
+        duration_ms: durationMs, // P1-5 real elapsed (stream-open → terminal); the wire carries none
+        duration_api_ms: durationMs, // engine run == the API call from the shell's view
+        is_error: false,
+        num_turns: stats?.turns ?? 0, // 件2a:同 :121 —— 缺 stats 不炸
+        result: r.result ?? '',
+        // TaskResult 五键(additive):outputSchema 任务的结构化产出 + 降级实录(见上方共享注)。
+        ...(() => {
+            const so = r.structuredOutput;
+            return so !== undefined ? { structuredOutput: so } : {};
+        })(),
+        ...degradedField,
+        stop_reason: null, // dropped (contract 02 §2.10)
+        total_cost_usd: costOrNull(stats?.costUsd), // P1-5: costUsd===0 is "unconfigured pricing" → null, never a fake 0
+        usage,
+        // MF-25/P1-5 — the per-model usage split (wire `stats.modelUsage`, or the synthesized current-model row).
+        modelUsage,
+        permission_denials: [],
+        // MF-25 — the effective served model id (`done.result.model`, e.g. "deepseek-v4-pro"). The CC
+        // SDKResultSuccess schema has no `model` field, so this rides as an additive seam field a cost/overview
+        // consumer reads (it is ALSO surfaced as the `modelUsage` key). Omitted when the wire didn't carry it.
+        ...(typeof r.model === 'string' ? { model: r.model } : {}),
+    });
+}
+/** `failed` → SDKResultError (contract 02 §2.11 / 08 CS-11). */
+export function failedToSdkResult(ev, ctx) {
+    // Flatten the 4 CC error subtypes onto the single neutral errorCode.
+    // error_max_budget_usd is a non-error "budget exceeded" notice, not a crash
+    // (contract 02 §2.11) — the renderer branches on subtype.
+    const subtype = ev.errorCode === 'budget.exceeded' || ev.errorCode === 'budget.precall'
+        ? 'error_max_budget_usd'
+        : 'error_during_execution';
+    const durationMs = elapsedMs(ctx);
+    return stamp(ctx, {
+        uuid: undefined,
+        session_id: undefined,
+        type: 'result',
+        subtype,
+        duration_ms: durationMs, // P1-5 real elapsed (stream-open → terminal)
+        duration_api_ms: durationMs,
+        is_error: true,
+        num_turns: 0,
+        stop_reason: null,
+        total_cost_usd: null, // P1-5: a failed run has no known cost — never a fake 0
+        usage: {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadInputTokens: 0,
+            cacheCreationInputTokens: 0,
+            webSearchRequests: 0,
+        },
+        modelUsage: {},
+        permission_denials: [],
+        // errorCode + errorMessage flattened into the single CC errors[] string.
+        // Rewind-family codes(core 1.292 [833]:resume_at.before_target_not_user /
+        // resume_at.before_root_unsupported / rewind_snapshot.unresolvable)透传给用户 —— 这些是
+        // 用户可自解的操作性错误(选错目标/回退过根/快照缺失),code 附在 message 后便于对账。
+        errors: [
+            typeof ev.errorCode === 'string' &&
+                (ev.errorCode.startsWith('resume_at.') || ev.errorCode.startsWith('rewind_snapshot.')) &&
+                ev.errorMessage
+                ? `${ev.errorMessage} (${ev.errorCode})`
+                : (ev.errorMessage ?? ev.errorCode ?? 'run failed'),
+        ],
+        // [909]B1 — errorCode 透传(additive seam 字段;done 臂同款):`failed` 事件的 cancelled/
+        // budget.* 等引擎值原样给集成面。
+        ...(typeof ev.errorCode === 'string' && ev.errorCode.length > 0 ? { errorCode: ev.errorCode } : {}),
+    });
+}
+/** Dispatch a terminal AgentEvent to its SDKResult arm. */
+export function terminalToSdkResult(ev, ctx) {
+    return ev.type === 'done' ? doneToSdkResult(ev, ctx) : failedToSdkResult(ev, ctx);
+}

package/dist/adapter/downstream/turnUsageToModelUsage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ⇄ B3 批搬迁(2026-07-27,多端改造设计稿 §3 B3):cli src/seam/adapter/downstream/turnUsageToModelUsage.ts
+ * **逐字整搬**(闭包 2 文件)。名字映射是 load-bearing 的,一个字节都别动。
+ */
+/**
+ * CS-7 §2.7 (08 CS-7 / UC-1): `turn_end.usage` → CC `ModelUsage`, with the
+ * PINNED, load-bearing name mapping. Micro-USD is the wire unit.
+ *
+ *   inputTokens       → inputTokens
+ *   outputTokens      → outputTokens
+ *   cacheReadTokens   → cacheReadInputTokens      (rename is load-bearing)
+ *   cacheWriteTokens  → cacheCreationInputTokens  (rename is load-bearing)
+ *   costMicroUsd      → costUSD  (= costMicroUsd / 1_000_000)
+ *
+ * DROPPED (no wire datum): `webSearchRequests`, `contextWindow`,
+ * `maxOutputTokens` — the missing `contextWindow` denominator is mock-fill from
+ * a static per-model table (contract 02 §2.7 VERIFY). Defaulted to 0 to satisfy
+ * the CC `ModelUsage` shape without inventing a number.
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+import type { ModelUsage } from '../types.js';
+type TurnUsage = NonNullable<Extract<AgentEvent, {
+    type: 'turn_end';
+}>['usage']>;
+export declare function turnUsageToModelUsage(usage: TurnUsage): ModelUsage;
+export {};

package/dist/adapter/downstream/turnUsageToModelUsage.js

@@ -0,0 +1,12 @@
+export function turnUsageToModelUsage(usage) {
+    return {
+        inputTokens: usage.inputTokens ?? 0,
+        outputTokens: usage.outputTokens ?? 0,
+        cacheReadInputTokens: usage.cacheReadTokens ?? 0,
+        cacheCreationInputTokens: usage.cacheWriteTokens ?? 0,
+        webSearchRequests: 0, // dropped on the wire
+        costUSD: usage.costMicroUsd !== undefined ? usage.costMicroUsd / 1_000_000 : 0,
+        contextWindow: 0, // dropped on the wire → mock-fill (static per-model table)
+        maxOutputTokens: 0, // dropped on the wire → mock-fill
+    };
+}

package/dist/adapter/runStream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ⇄ B3 批搬迁(2026-07-27,多端改造设计稿 §3 B3 / §2.5 末行):cli `src/seam/adapter/runStream.ts`
+ * 整文件搬入。**这个文件是本批的主角** —— 搬迁前它的传递闭包是 **1,571 个文件 / 26 种 Node 内建 /
+ * 412 个 react 文件**(实测,设计稿 §5.2 表),整棵 CC 树都在里面;搬迁后是 5 个文件、零 Node
+ * 内建、零 react。根因链只有三跳,两条外向边:
+ *   · `:215 await import('../../sema/planReviewWire.js')` → `planReviewWire.ts:26 utils/debug` → 整棵树;
+ *   · `:140 void import('../../sema/lastTurnUsageStore.js')`(闭包本身干净,但同样是壳内向的边)。
+ * 本批把这两条边改成 **chrome 事件**(`plan_review_park` / `last_turn_usage`,见 seam.ts 臂注释),
+ * 由宿主注入 `ctx.emitChrome` 消费 —— 库侧再也不 import 壳。
+ *
+ * 🔴 **时序逐点对齐**(搬迁不许顺手改语义):cli 原本 `await` 的那一处(plan_review park,终帧
+ * 之前)这里照样 `await`;原本 fire-and-forget 的那一处(last turn usage)照样不 await。
+ *
+ * ── 以下为原文件头(逐字保留)────────────────────────────────────────────────────────────────
+ * Stream driver (T24, slice): consume an `AgentEvent` async-iterable (the SDK's
+ * `runs.events` durable generator OR `tasks.stream` live generator — both yield
+ * `AsyncIterable<AgentEvent>`) and re-emit the renderable CC `SDKMessage`
+ * sequence (contract 02 §1.1/§7; 08 CS-12/IH-3).
+ *
+ * Responsibilities for the slice:
+ *  - event-id idempotency: a replayed durable `id:` (resume / 416 full-sync)
+ *    is deduped so no SDKMessage is double-rendered (contract 02 §1.1, sse.ts:5-6);
+ *  - pipe each non-terminal arm through `eventToSdkMessage`;
+ *  - fold `turn_end.usage` into the latest-usage handle (no standalone arm);
+ *  - project the terminal `done`/`failed` via `terminalToSdkResult`, then END
+ *    the generator (mirrors sse.ts:62 / tasks.ts:52).
+ *
+ * The SDK owns resume/416 INTERNALLY (sse.ts) — this driver only consumes the
+ * already-normalized AgentEvent iterable and guards against re-seen ids.
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+import { type SDKMessage, type EmitContext, type ModelUsage } from './types.js';
+export interface RunStreamHandle {
+    /** The latest folded turn usage (footer counters); updated on each turn_end. */
+    latestUsage?: ModelUsage;
+}
+export declare function isRunStreamActive(): boolean;
+export declare function runStream(events: AsyncIterable<AgentEvent>, ctx: EmitContext, handle?: RunStreamHandle): AsyncGenerator<SDKMessage>;

package/dist/adapter/runStream.js

@@ -0,0 +1,177 @@
+import { eventSeq, } from './types.js';
+import { eventToSdkMessage, turnEndUsage } from './downstream/eventToSdkMessage.js';
+import { terminalToSdkResult } from './downstream/terminalToSdkResult.js';
+import { publishSubagentContentEvent } from '../subagentContentStore.js';
+/** 本文件发的 chrome 事件全在 leader lane(子代内容在上面就被 divert 走了)。 */
+const MAIN = { lane: 'main' };
+/**
+ * Drive one AgentEvent source into a CC SDKMessage stream.
+ *
+ * @param events  the SDK AgentEvent iterable (durable or live).
+ * @param ctx     identity context (sessionId threaded onto every emitted arm).
+ * @param handle  optional out-param updated with the latest folded usage.
+ */
+// In-flight turn counter (module-level: every interactive turn flows through
+// runStream). Consumed by the engine versionDrift rolling-upgrade gate — the
+// engine must NEVER be hot-swapped mid-turn (it would sever this stream), so
+// the lifecycle loop defers the swap until this reads false (clay 2026-07-05
+// 滚动升级/一体化继承).
+let inFlightTurns = 0;
+export function isRunStreamActive() {
+    return inFlightTurns > 0;
+}
+export async function* runStream(events, ctx, handle = {}) {
+    inFlightTurns++;
+    try {
+        yield* runStreamInner(events, ctx, handle);
+    }
+    finally {
+        inFlightTurns--;
+    }
+}
+async function* runStreamInner(events, ctx, handle = {}) {
+    const seen = new Set();
+    // P1-5 (print `--output-format json` 元数据失真): stamp the stream-open instant once so the terminal
+    // projector can emit a REAL `duration_ms` (the wire carries no duration; the old hardcoded 0 was fake).
+    if (ctx.startedAtMs === undefined)
+        ctx.startedAtMs = Date.now();
+    for await (const ev of events) {
+        // event-id idempotency — drop a re-seen durable seq (contract 02 §1.1).
+        const seq = eventSeq(ev);
+        if (seq !== undefined) {
+            if (seen.has(seq))
+                continue;
+            seen.add(seq);
+        }
+        // C1 — SUBAGENT content divert (service 1.89 forwardSubagentEvents): a CONTENT event stamped with
+        // parentToolCallId belongs to a SUBAGENT run (EventIdentity contract: present ONLY on sub-agent
+        // events) — side-channel it to the 查看态 transcript store and keep it OFF the main pipeline
+        // (a child's tokens rendering as the leader's text is the pollution failure mode). turn_end's
+        // sub-flow guard below stays as-is (usage rollup only).
+        if ((ev.type === 'text_delta' ||
+            ev.type === 'reasoning_delta' ||
+            ev.type === 'tool_start' ||
+            ev.type === 'tool_end') &&
+            typeof ev.parentToolCallId === 'string') {
+            const sub = ev;
+            publishSubagentContentEvent({
+                type: sub.type,
+                // taskId is on every subagent event (EventIdentity); parentToolCallId keys the fallback
+                taskId: sub.taskId ?? sub.parentToolCallId,
+                parentToolCallId: sub.parentToolCallId,
+                delta: sub.delta,
+                toolCallId: sub.toolCallId,
+                toolName: sub.toolName,
+                args: sub.args,
+                output: typeof sub.output === 'string' ? sub.output : undefined,
+                isError: sub.isError,
+            });
+            continue;
+        }
+        // Fold usage (footer counters), AND surface the per-turn `outputTokens` as a NEUTRAL `turn_usage` arm so
+        // the upstream bridge can drive 187's C1a `end` arm (responseLength reconciles to REAL output_tokens×4 —
+        // the spinner-token feeder, verify/TOKEN-187-PORT.md step 3). `turn_end` carries no renderable content, so
+        // this arm is metrics-only; the bridge converts it to a `message_delta{usage.output_tokens}` StreamEvent.
+        if (ev.type === 'turn_end') {
+            const usage = turnEndUsage(ev);
+            // §E2 identity (service 1.78) — a SUB-FLOW's turn_end (orchestration/subagent round, carries
+            // parentToolCallId) must NOT drive the leader's C1a `end` reconcile: its outputTokens are the
+            // child's, and reconciling the leader's responseLength against them is the token-jump bug
+            // (blackboard dogfood #2 / upstreamBridge TODO #9). Fold its usage into the rollup only.
+            const isSubFlow = ev.parentToolCallId !== undefined;
+            if (usage) {
+                handle.latestUsage = usage;
+                // plugins 专项 G1(2026-07-21):同一折叠点多发一份给 lastTurnUsageStore——StatusLine
+                // 的 statusline 命令 stdin(context_window.current_usage)在消息面无 usage(seam 合成
+                // 消息不带)时回落到这里,claude-hud 类插件的 Context 条才有真值。sub-flow 的 turn_end
+                // 不发(§E2 同判据):statusline 显示的是主会话窗口,子 agent 的 usage 会把 Context%
+                // 打成孩子的窗口占用(自查+对抗复审确认)。
+                // B3 切边:此前是 `void import('../../sema/lastTurnUsageStore.js').then(publishLastTurnUsage)`
+                // ——壳内向的动态边。改成 chrome 事件(宿主消费义务见 seam.ts `last_turn_usage` 臂);
+                // 与原式同样**不 await**(fire-and-forget),sink 抛错不影响流(fail-soft 原语义)。
+                if (!isSubFlow && ctx.emitChrome) {
+                    try {
+                        void ctx.emitChrome({ kind: 'last_turn_usage', laneProof: MAIN, usage });
+                    }
+                    catch { /* fail-soft — statusline 退回 null,原语义 */ }
+                }
+            }
+            const outputTokens = ev.usage?.outputTokens;
+            if (typeof outputTokens === 'number' && !isSubFlow) {
+                yield { type: 'turn_usage', outputTokens };
+            }
+            continue;
+        }
+        // Terminals: project then END (the SDK generator also ends here).
+        if (ev.type === 'done' || ev.type === 'failed') {
+            // clay P0 报错体系(2026-07-06,402 实测定谳):failed 终态此前只投影成 SDKResult
+            // (interactive REPL 不渲染 result 帧)= 上游 4xx/欠费/超限对用户完全静默。这里
+            // 额外合成一条 assistant 错误消息(CC 的 isApiErrorMessage 红字渲染线现成),
+            // 用户永远能看到 turn 为什么失败。
+            const failedResult = ev.type === 'done' ? ev.result : null;
+            // [909]B1 — timeout/blocked 终态同享可见性行(此前只 status:'failed' 有行,timeout/blocked
+            // 在 REPL 面完全静默)。park(suspended/needs_review)不进此行:有各自 overlay/文案线,
+            // 非 provider 故障([884]A1 断言零 assistant 行)。
+            const errText = ev.type === 'failed'
+                ? (ev.errorMessage ?? ev.errorCode ?? 'run failed')
+                : failedResult?.status === 'failed'
+                    ? (failedResult.errorMessage ?? failedResult.errorCode ?? 'run failed')
+                    : failedResult?.status === 'timeout'
+                        ? (failedResult.errorMessage ?? 'run hit its wall-clock deadline and was finalized by the engine')
+                        : failedResult?.status === 'blocked'
+                            ? (failedResult.blockedReason
+                                ? `Run blocked: ${failedResult.blockedReason}`
+                                : 'Run blocked (the agent reported it cannot proceed)')
+                            : null;
+            if (errText) {
+                // 件2b(中断事故修复批 G,2026-07-15,症状2 第二环):409 active-run 拒绝的专属人话。引擎在
+                // session 已有挂起 run(上一 turn 的 AskUserQuestion park 未解锁等)时把
+                // errorMessage 'session already has an active run'(+ result.activeTaskId)骑在
+                // done{status:'failed'} 帧上(ai-agent-service server.ts:1526 同型)——裸 "API Error:" 行看着
+                // 像 provider 故障,是误导。识别该终帧 → 一行专属文案(告知在等什么 + 出路);其它错误保持
+                // 原 API Error 行(未知错误 fallback 不变)。引擎侧解锁腿([866] server cancel suspended 改
+                // 语义 + reapSuspended TTL)到货前,这是壳侧最诚实的呈现。
+                const activeTaskId = failedResult?.activeTaskId ??
+                    (ev.type === 'failed' ? ev.activeTaskId : undefined);
+                const isActiveRunBusy = errText === 'session already has an active run' || typeof activeTaskId === 'string';
+                // 件14 rev2 (2026-07-14): provider max_tokens cap rejection (e.g. glm-5.2 preset 131072 >
+                // a third-party gateway's 128000) → append the way out. Keyword match on the upstream text,
+                // supplement never mask (raw provider words stay on the row).
+                const maxTokHint = /max_tokens/i.test(errText)
+                    ? '\nyour provider caps max_tokens lower — lower it in /model (press m, or M to type a value)'
+                    : '';
+                const rowText = isActiveRunBusy
+                    ? `Previous turn is still pending an answer${typeof activeTaskId === 'string' && activeTaskId.length > 0
+                        ? ` (run ${activeTaskId})`
+                        : ''}. Press Esc to cancel it, or retry shortly.`
+                    : `API Error: ${errText}${maxTokHint}`;
+                yield {
+                    session_id: ctx.sessionId ?? '',
+                    uuid: `err-${Date.now().toString(36)}`,
+                    type: 'assistant',
+                    message: { role: 'assistant', content: [{ type: 'text', text: rowText }] },
+                    parent_tool_use_id: null,
+                    isApiErrorMessage: true,
+                };
+            }
+            // plan_review park(core [508]③ 拍板形状):done `status:"needs_review"` + gate plan_review 不是
+            // 普通完成——壳弹审批卡(planReviewWire 合成 question 借 AskUserQuestion overlay;决断走
+            // /v1/assistant/tasks/:id/plan_review resume verb)。
+            // B3 切边:此前是 `await import('../../sema/planReviewWire.js')` —— **整棵 CC 树进闭包的
+            // 那一行**(设计稿 §5.2 根因链)。改成 chrome 事件;`await` 保留(cli 原本就在终帧**之前**
+            // 同步等 arm 完成,卡片先于完成行出现),sink 失败 fail-soft 照常投影终帧。
+            if (ev.type === 'done' && failedResult?.status === 'needs_review' && ctx.emitChrome) {
+                try {
+                    await ctx.emitChrome({ kind: 'plan_review_park', laneProof: MAIN, result: ev.result });
+                }
+                catch { /* fail-soft — the terminal frame below still renders */ }
+            }
+            yield terminalToSdkResult(ev, ctx);
+            return;
+        }
+        // Every other arm → zero-or-one renderable SDKMessage.
+        const msg = eventToSdkMessage(ev, ctx);
+        if (msg)
+            yield msg;
+    }
+}