@sema-agent/client-core 0.3.0 → 0.5.0

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

@@ -0,0 +1,81 @@
+/**
+ * ⇄ B3 批搬迁(2026-07-27,多端改造设计稿 §3 B3):cli src/seam/adapter/downstream/eventToSdkMessage.ts
+ * **逐字整搬**(闭包实测 5 文件 / 零 Node 内建 / 零 react —— 本来就可移植,一个 import 都不用改)。
+ */
+/**
+ * DOWNSTREAM projector (T22): `AgentEvent` → CC `SDKMessage` arms, the contract
+ * 02 §6 translation table run FORWARD, for the thin slice.
+ *
+ * Handled arms (contract 02 §2 / 08 CS-1..CS-7, CS-10, CS-11):
+ *   reasoning      → assistant (thinking block)            §2.1 / CS-3
+ *   text           → assistant (text block)               §2.2 / CS-1
+ *   reasoning_delta→ stream_event (thinking_delta)         §2.3 / CS-4
+ *   text_delta     → stream_event (text_delta)             §2.4 / CS-2
+ *   tool_start     → assistant (tool_use block)            §2.5 / CS-5
+ *   tool_end       → (internal) tool_use_result arm carrying the §E1 wire output  §2.6 / CS-6
+ *   turn_end       → (folded into the terminal/usage rollup; no standalone arm)
+ *   compacted      → system / compact_boundary             §2.8 / CS-8
+ *   status         → (internal) retry_status arm (BrainStatus liveness → spinner row)  §E3/§E10
+ *   done           → result / success                      §2.10 / CS-10
+ *   failed         → result / error                        §2.11 / CS-11
+ *
+ * Leak guards (contract 02 §5): the `message`/`event` fields are CC's opaque
+ * `z.unknown()` placeholders. We populate them with NEUTRAL, CC-native content
+ * blocks the renderer reads — NEVER the raw Anthropic `APIAssistantMessage`
+ * block array or `RawMessageStreamEvent` wire, never `signature`/
+ * `redacted_thinking`/`signature_delta`.
+ *
+ * §E1 update (was STALE): `tool_end` DOES carry the model-facing `output` (the
+ * action-card BODY) on the wire now (events.d.ts:75-86). We carry it through —
+ * but NOT as a raw Anthropic `tool_result` wire block: a NEUTRAL internal arm
+ * `{type:'tool_end_result', toolCallId, isError, output, truncated, eventId}` the
+ * upstream bridge correlates to the open card by `toolCallId`. The output is
+ * 🔴 UNTRUSTED / OBSERVABILITY-ONLY (events.d.ts:80-85): render it, never re-feed
+ * a truncated body to a model.
+ */
+import type { AgentEvent, CheckpointGate } from '@sema-agent/sdk';
+import { type SDKMessage, type EmitContext, type ModelUsage } from '../types.js';
+/**
+ * Project one durable/live `AgentEvent` into zero-or-one renderable `SDKMessage`.
+ *
+ * `tool_end` projects to a NEUTRAL internal `tool_end_result` arm (NOT a CC
+ * SDKMessage the renderer reads) carrying the §E1 wire `output` so the bridge can
+ * close the open card with the real body.
+ *
+ * Returns `null` for arms that carry no standalone renderable message in this
+ * slice:
+ *  - `turn_end` → usage rollup only, surfaced via `turnEndUsage` below;
+ *  - `suspended` → HITL registration is the run driver's job (out of slice).
+ *
+ * Terminal `done`/`failed` are delegated to `terminalToSdkResult`.
+ */
+export declare function eventToSdkMessage(ev: AgentEvent, ctx: EmitContext): SDKMessage | null;
+/**
+ * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
+ * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no
+ * standalone usage SDKMessage arm; the run driver folds it into the footer /
+ * terminal rollup. Returns `undefined` when the optional `usage` is absent.
+ */
+export declare function turnEndUsage(ev: Extract<AgentEvent, {
+    type: 'turn_end';
+}>): ModelUsage | undefined;
+/**
+ * Defensive open-set read of a `suspended` gate kind for the run driver's HITL
+ * branch — known kinds plus a generic fallback (contract 02 §2.9 / §3: never
+ * crash on an unknown kind). Kept here so the §6 mapping lives in one file.
+ *
+ * ⚠️ DEAD CODE — 不是「HITL 分支漏接」(2026-07-26 全树核查,task #81 顺带件):
+ *   · 全树(src/ + mock/ + build/ + 测试)**零调用点**,adapter facade(src/seam/adapter/index.ts)
+ *     也没把它再导出去 —— 没有任何一处「本该调它却没调」。
+ *   · 它想服务的那条 HITL 分支**已经接好了**,只是没走这个函数:
+ *       - `suspended` 事件臂 → `src/seam/adapter/upstream/hitlBridge.ts:162-168` 的 `observe()`
+ *         就地做了**同款**防御回落(`ev.gate ? ev.gate : { kind: 'human' }`),而且 latch 的是整个
+ *         CheckpointGate 对象,壳侧 `currentGate()` 自己 branch `gate.kind`;
+ *       - `done{status:'suspended', checkpointGate}` 终帧 → `liveHitlAskWire.ts:89-118` /
+ *         `terminalToSdkResult.ts:296-311` 各自读 `checkpointGate.kind` **和** `.toolName`。
+ *   · 关键:每个真实消费方都同时需要 `toolName`(挑 Ask overlay vs fs 写门三选卡),而本函数只吐
+ *     一个 kind 字符串 —— 签名比任何真实需求都窄,接进去反而要再读一次 gate。
+ *   结论 = 可删的死码(留档不擅删,按 task #81 口径只标记);真要收,连同 `CheckpointGate` 的
+ *   type-only import 一起摘。
+ */
+export declare function gateKind(gate: CheckpointGate | null | undefined): string;

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -0,0 +1,330 @@
+import { stamp, } from '../types.js';
+import { turnUsageToModelUsage } from './turnUsageToModelUsage.js';
+// #51: `stamp<T extends { uuid?: string; session_id?: string }>` — passing an
+// arm-body object literal straight to `stamp` triggers a TS quirk: the
+// literal gets excess-property-checked against the CONSTRAINT (which only
+// knows uuid/session_id) before T is fully inferred, so every other field
+// (`type`, `taskId`, …) reads as "unknown property". Routing the literal
+// through this identity helper first breaks that early check without
+// touching runtime behavior (pure pass-through; `stamp` still assigns
+// uuid/session_id exactly as before).
+function armBody(body) {
+    return body;
+}
+/** Wrap neutral content blocks in the CC `assistant` message envelope. */
+function assistantArm(ctx, content) {
+    return stamp(ctx, armBody({
+        type: 'assistant',
+        // `message` is coreSchemas APIAssistantMessagePlaceholder = z.unknown(): we
+        // hand the renderer a neutral { role, content } it can read, not the raw wire.
+        message: { role: 'assistant', content },
+        parent_tool_use_id: null,
+    }));
+}
+/** Wrap a neutral delta in the CC `stream_event` (partial assistant) envelope. */
+function streamEventArm(ctx, event) {
+    return stamp(ctx, armBody({
+        type: 'stream_event',
+        // `event` is RawMessageStreamEventPlaceholder = z.unknown(): a neutral
+        // fragment descriptor, NOT a `content_block_delta` wire frame.
+        event,
+        parent_tool_use_id: null,
+    }));
+}
+/**
+ * Project one durable/live `AgentEvent` into zero-or-one renderable `SDKMessage`.
+ *
+ * `tool_end` projects to a NEUTRAL internal `tool_end_result` arm (NOT a CC
+ * SDKMessage the renderer reads) carrying the §E1 wire `output` so the bridge can
+ * close the open card with the real body.
+ *
+ * Returns `null` for arms that carry no standalone renderable message in this
+ * slice:
+ *  - `turn_end` → usage rollup only, surfaced via `turnEndUsage` below;
+ *  - `suspended` → HITL registration is the run driver's job (out of slice).
+ *
+ * Terminal `done`/`failed` are delegated to `terminalToSdkResult`.
+ */
+export function eventToSdkMessage(ev, ctx) {
+    // service 1.75 — `workflow_complete`: an out-of-band background-workflow completion push, ridden onto
+    // the session's next stream open (BEFORE the run's own events). SDK ≥0.0.108 已入 union(注记过时
+    // 已修;G8 的收敛方向候 P1-3);raw 读形保留待 B4 帧分派批统一 typed 化。 Projects to a
+    // NEUTRAL internal arm; the upstream bridge turns it into CC's `<task-notification>` injection.
+    const raw = ev;
+    if (raw.type === 'workflow_complete') {
+        if (typeof raw.runId !== 'string')
+            return null;
+        return stamp(ctx, armBody({
+            type: 'workflow_complete',
+            runId: raw.runId,
+            status: raw.status === 'failed' ? 'failed' : 'completed',
+            summary: typeof raw.summary === 'string' ? raw.summary : '',
+        }));
+    }
+    // core 1.204 G2b — `task_notification` (background-bash/workflow completion, TaskNotificationPayload
+    // rides on `notification`). SDK ≥0.0.108 已入 union(注记过时已修);raw 读形保留待 B4 帧分派批统一 typed 化. Projects to a NEUTRAL
+    // internal arm: the REPL bridge drops it (the ENGINE already steer-injects the model-facing XML), the
+    // print-mode `ask` converts it to CC's `system/task_notification` SDK frame.
+    if (raw.type === 'task_notification') {
+        const n = (raw.notification ?? raw);
+        if (typeof n.task_id !== 'string')
+            return null;
+        return stamp(ctx, armBody({
+            type: 'task_notification',
+            notification: n,
+        }));
+    }
+    // core 1.220 design/121 — engine LSP `diagnostics` frame ({files:[{uri,diagnostics}], isNew}, service
+    // §E1 redacted, TOC host lane default ON). SDK ≥0.0.108 已入 union(注记过时已修);raw 读形保留待 B4 帧分派批统一 typed 化. Projects to
+    // a NEUTRAL internal arm; the REPL bridge maps it into the CC `diagnostics` attachment row
+    // (DiagnosticsDisplay renders it, zero new UI). parentToolCallId rides through so the bridge can keep
+    // a sub-flow's diagnostics off the leader transcript.
+    if (raw.type === 'diagnostics') {
+        if (!Array.isArray(raw.files) || raw.files.length === 0)
+            return null;
+        return stamp(ctx, armBody({
+            type: 'diagnostics',
+            files: raw.files,
+            isNew: raw.isNew === true,
+            ...(typeof raw.parentToolCallId === 'string' ? { parentToolCallId: raw.parentToolCallId } : {}),
+        }));
+    }
+    // core 1.251 design/133 ([479] ask-1) + 1.253 G1 ([482]/[487]②) — `steering_injected`: the engine
+    // echoed a SYSTEM steering injection ({source, preview:first-220-chars}, echo-only — the model-facing
+    // message is server-side). Sources are an OPEN SET (deadline_nudge/finalize + todo_reminder/
+    // task_reminder/changed_files/plan_mode + background_tasks/tools_delta today; core may extend). Not in
+    // the SDK union yet — raw defensive read; projects to a NEUTRAL internal arm the REPL bridge maps into
+    // renderable attachments (steeringAttachments.ts). parentToolCallId rides through so a sub-flow's echo
+    // stays off the leader transcript (same rule as diagnostics).
+    if (raw.type === 'steering_injected') {
+        if (typeof raw.source !== 'string' || raw.source.length === 0)
+            return null;
+        return stamp(ctx, armBody({
+            type: 'steering_injected',
+            source: raw.source,
+            preview: typeof raw.preview === 'string' ? raw.preview : '',
+            ...(typeof raw.parentToolCallId === 'string' ? { parentToolCallId: raw.parentToolCallId } : {}),
+        }));
+    }
+    // core design/99 §E13([1559]二/[1564]4 提货)— `workspace_changed`: the engine moved its logical
+    // cwd (bash `cd` / EnterWorktree), frame carries the NEW cwd (RAW form). Display-only echo — the
+    // engine already runs against the new cwd. NOT persistent state: resets to the session root across
+    // suspend/resume(core 口径,勿当持久态渲染)。SDK ≥0.0.108 已入 union(注记过时已修);raw 读形保留待 B4 帧分派批统一 typed 化;
+    // projects to a NEUTRAL arm the REPL bridge maps into a dim transcript row. server 透传候班车
+    // ([1557]三处置),帧到即亮。
+    if (raw.type === 'workspace_changed') {
+        if (typeof raw.cwd !== 'string' || raw.cwd.length === 0)
+            return null;
+        return stamp(ctx, armBody({
+            type: 'workspace_changed',
+            cwd: raw.cwd,
+            ...(typeof raw.parentToolCallId === 'string' ? { parentToolCallId: raw.parentToolCallId } : {}),
+        }));
+    }
+    switch (ev.type) {
+        // CS-1 §2.2 — turn-aggregated answer text (durable). Drop raw block array.
+        case 'text':
+            return assistantArm(ctx, [{ type: 'text', text: ev.text }]);
+        // CS-3 §2.1 — turn-aggregated thinking (durable). Distinct collapsible block.
+        case 'reasoning':
+            return assistantArm(ctx, [{ type: 'thinking', thinking: ev.text }]);
+        // CS-2 §2.4 — per-token answer fragment (live only). Typewriter append.
+        case 'text_delta':
+            return streamEventArm(ctx, { type: 'text_delta', delta: ev.delta });
+        // CS-4 §2.3 — per-token thinking fragment (live only). Drop signature_delta.
+        // §E2 identity (service 1.78 unblanked parentToolCallId on the wire, blackboard dogfood #2): thread it
+        // so the bridge can EXCLUDE a sub-flow's reasoning (orchestration/subagent) from the LEADER's spinner
+        // counter + thinking preview — the "134k tokens" overcount root cause (upstreamBridge TODO #9).
+        case 'reasoning_delta':
+            return streamEventArm(ctx, {
+                type: 'thinking_delta',
+                delta: ev.delta,
+                ...(ev.parentToolCallId !== undefined ? { parentToolCallId: ev.parentToolCallId } : {}),
+            });
+        // CS-5 §2.5 — action-card open. args is `unknown`: render generically.
+        // §E2 — thread the wire eventId (+ parentToolCallId) so the bridge stamps it (SB-2).
+        case 'tool_start':
+            return assistantArm(ctx, [
+                {
+                    type: 'tool_use',
+                    id: ev.toolCallId,
+                    name: ev.toolName,
+                    input: ev.args,
+                    // P0-2 — core 展示名(见 NeutralBlock.label 的完整对照记录)。防御读:SDK 0.0.103 已定型
+                    // `label?: string`,但旧引擎/旧 server 缺席 ⇒ 键不出现,形状与修前逐字相同。
+                    ...(typeof ev.label === 'string' && ev.label.length > 0 ? { label: ev.label } : {}),
+                    ...(ev.eventId !== undefined ? { eventId: ev.eventId } : {}),
+                    ...(ev.parentToolCallId !== undefined
+                        ? { parentToolCallId: ev.parentToolCallId }
+                        : {}),
+                },
+            ]);
+        // CS-8 §2.8 — compaction divider. tokensBefore ⇐ pre_tokens. trigger rides through when the
+        // engine sends it (core 1.156 manual verb → "manual"; absent ⇒ 'auto'). core 1.219
+        // (attachWorkingFiles default ON): `attachedFiles:[{path,chars,truncated}]` rides through raw so
+        // the bridge can project the CC post-compact "Read {path}" attachment rows (blackboard ask ②).
+        case 'compacted': {
+            const attachedFiles = ev.attachedFiles;
+            return stamp(ctx, armBody({
+                type: 'system',
+                subtype: 'compact_boundary',
+                compact_metadata: {
+                    trigger: (ev.trigger === 'manual' ? 'manual' : 'auto'),
+                    pre_tokens: ev.tokensBefore ?? 0,
+                },
+                ...(Array.isArray(attachedFiles) && attachedFiles.length > 0 ? { attachedFiles } : {}),
+            }));
+        }
+        // CS-6 §2.6 — tool_end now carries the §E1 model-facing `output` (the action-card
+        // BODY) + isError + the §E2 eventId. Emit a NEUTRAL internal arm the bridge correlates
+        // to the open card by `toolCallId`; `output`/`truncated` ride through as-is (UNTRUSTED,
+        // observability-only). `output === undefined` ⇒ the tool produced no body → the bridge
+        // falls back to the mock synthesizer (events.d.ts:79). Not a renderable CC SDKMessage —
+        // a side-channel arm `sdkMessagesToCcEvents` reads; CC's own renderer never sees it.
+        case 'tool_end': {
+            // design/64 [363] — `structured` is the engine's opt-in CC-shaped details field (core 1.199+
+            // AgentToolResult.details on the wire; not yet in the SDK tool_end arm — raw defensive read).
+            // Rides the neutral arm so the bridge can render the REAL rich card (diff / stdout panels).
+            const structured = ev.structured;
+            return stamp(ctx, armBody({
+                type: 'tool_end_result',
+                toolCallId: ev.toolCallId,
+                toolName: ev.toolName,
+                isError: ev.isError,
+                // P0-2([1725] 清单A)— `tool_end.label` 同 tool_start 待遇(server trace/project.js:61 白名单
+                // 本体产出)。此臂是壳内部侧信道(不进 transcript),所以这里带着无 provider 风险;
+                // tool_start 先到时 bridge 已登记过,这条是补位(只有 tool_end 带 label 的场景)。
+                ...(typeof ev.label === 'string' && ev.label.length > 0 ? { label: ev.label } : {}),
+                ...(ev.output !== undefined ? { output: ev.output } : {}),
+                ...(structured !== undefined ? { structured } : {}),
+                ...(ev.truncated !== undefined ? { truncated: ev.truncated } : {}),
+                ...(ev.eventId !== undefined ? { eventId: ev.eventId } : {}),
+                ...(ev.parentToolCallId !== undefined
+                    ? { parentToolCallId: ev.parentToolCallId }
+                    : {}),
+            }));
+        }
+        // §E3/§E10 — BrainStatus liveness (events.d.ts:44/:80 — rate_limited/retrying/reconnecting/
+        // circuit_open). LIVE-only + EPHEMERAL (never persisted/replayed). Project to a NEUTRAL internal
+        // `retry_status` arm forwarding the provider-neutral fields verbatim (phase/detail/retryInSec) —
+        // NOT a renderable CC SDKMessage. The upstream bridge (sema layer) maps phase→SpinnerRetryStatus +
+        // publishes to the sema retry-status store the spinner override reads (187's per-agent
+        // `afa(agentId).retryStatus` app-state analog, ui-modules/0157_036_ui_Klo.js:31). The seam stays a
+        // dumb forwarder: the provider-neutral→UI-shape mapping is the renderer layer's job (retryStatusStore).
+        case 'status':
+            return stamp(ctx, armBody({
+                type: 'retry_status',
+                phase: ev.phase,
+                ...(ev.detail !== undefined ? { detail: ev.detail } : {}),
+                ...(ev.retryInSec !== undefined ? { retryInSec: ev.retryInSec } : {}),
+            }));
+        // MF-10 (design/99, events.d.ts task_progress) — a SUBAGENT PROGRESS TICK: the delegated sub-run's
+        // CUMULATIVE usage at each turn boundary (LIVE/EPHEMERAL, never persisted/replayed). Project to a
+        // NEUTRAL internal `task_progress` arm — NOT a renderable CC SDKMessage. The upstream bridge binds it
+        // to the open Task/Agent tool_use card and synthesizes CC-native `progress` messages so CC's own
+        // Task-card rollup (tool uses / tokens climbing) animates for an ENGINE-side subagent exactly like a
+        // local AgentTool one. Fields are read DEFENSIVELY: the service wire whitelist (server.ts:1334-1342)
+        // strips `status` + EventIdentity and may omit `name` — mirror what actually rides the wire, not the
+        // richer core-side arm.
+        case 'task_progress': {
+            if (typeof ev.taskId !== 'string')
+                return null;
+            // core 1.262.0 [558]B / service 1.154.0 [579] — `currentAction`: the child's most recent tool
+            // intent as ONE human line ("Bash npm test"), derived from the child's tool_start (tool name +
+            // argument head) and service-redacted. SDK ≥0.0.108 已定型(events.d.ts task_progress 臂),
+            // cast 已退;runtime 门保留(旧 server 缺席 ⇒ 键不 stamp)。
+            const currentAction = ev.currentAction;
+            // W1 段1([1616]/[1617]②,frame-lane-matrix #2)— core 1.401 起前台 workflow 子代 tick 带
+            // `workflowRunId`/`workflowAgentLabel`(lane 归属自描述位)。此前这层 spread 白名单把两键剥掉,
+            // bridge 想判 lane 也判不了(「送到了但没人读」的精确坐标其实是「没转」)。additive 透传,
+            // 防御读(旧 core/server 缺席 ⇒ 形状不变)。注意 server 侧 project.ts 投影白名单在 1.272.0
+            // 仍剥这两键(server a76bd77 才修,黑板 [1619])——真 wire 于 1.273+ 才带,此处先备好通路。
+            const workflowRunId = ev.workflowRunId;
+            const workflowAgentLabel = ev.workflowAgentLabel;
+            return stamp(ctx, armBody({
+                type: 'task_progress',
+                taskId: ev.taskId,
+                ...(ev.name !== undefined ? { name: ev.name } : {}),
+                ...(ev.usage !== undefined ? { usage: ev.usage } : {}),
+                ...(typeof currentAction === 'string' && currentAction.length > 0
+                    ? { currentAction }
+                    : {}),
+                ...(typeof workflowRunId === 'string' && workflowRunId.length > 0
+                    ? { workflowRunId }
+                    : {}),
+                ...(typeof workflowAgentLabel === 'string' && workflowAgentLabel.length > 0
+                    ? { workflowAgentLabel }
+                    : {}),
+                ...(ev.parentToolCallId !== undefined
+                    ? { parentToolCallId: ev.parentToolCallId }
+                    : {}),
+            }));
+        }
+        // P0-1([1725] 清单A)— E12 `suggestions`:run 跑完(status:"completed")后 core 一次 LLM pass 产的
+        // 「下一步可问什么」建议**批**。此前这个臂掉进 `default: return null` ⇒ 全链死信。
+        // 🔴 语义(别按 CC 的单条模型套):CC 的 `prompt_suggestion` 是**每轮一条** `suggestion: string`;
+        // 引擎这条是**完成后一批** `string[]`(events.d.ts:132-135)——按批渲染/按批投影。
+        // 🔴 UNTRUSTED 模型文本(service 已 redact)、仅 UI、**绝不回喂模型** —— 所以投成 NEUTRAL 内部臂
+        // (不是可渲染的 CC SDKMessage):TUI 由 upstreamBridge 推给 chips store,print 由 seamQueryEngine
+        // 折成 CC 原生 `prompt_suggestion` 帧(coreSchemas.ts:1905 契约既有)。
+        // 🔴 产出面实测(2026-07-26,钉版 server 1.277.1 / core 1.416 直连):**只有 durable
+        // `/v1/runs` 腿产**(server runs.js:300-303 `spec.suggestNextPrompts && done && completed`);
+        // `/v1/tasks/stream` 带 `suggestNextPrompts:true` 也一帧不发(已真跑证伪)。壳的交互 turn 走
+        // tasks/stream ⇒ 这条通路今天只在 durable 车道(runs.create + runs.events:Ctrl+B/`/background`/
+        // ControlRouter)活。防御性上界:批量截 8 条、单条截 200 字(UI 面,不是模型面)。
+        case 'suggestions': {
+            const list = (Array.isArray(ev.suggestions) ? ev.suggestions : [])
+                .filter((s) => typeof s === 'string' && s.trim().length > 0)
+                .slice(0, 8)
+                .map((s) => (s.length > 200 ? `${s.slice(0, 200)}…` : s));
+            if (list.length === 0)
+                return null;
+            return stamp(ctx, armBody({
+                type: 'prompt_suggestions',
+                suggestions: list,
+            }));
+        }
+        // §2.7 — turn_end is usage-only. §2.9 — suspended is HITL registration.
+        case 'turn_end':
+        case 'suspended':
+            return null;
+        // CS-10 / CS-11 — terminals are projected by terminalToSdkResult.
+        case 'done':
+        case 'failed':
+            return null;
+        default:
+            // Forward-compat: log+skip an arm this slice predates (contract 02 §3).
+            return null;
+    }
+}
+/**
+ * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
+ * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no
+ * standalone usage SDKMessage arm; the run driver folds it into the footer /
+ * terminal rollup. Returns `undefined` when the optional `usage` is absent.
+ */
+export function turnEndUsage(ev) {
+    return ev.usage ? turnUsageToModelUsage(ev.usage) : undefined;
+}
+/**
+ * Defensive open-set read of a `suspended` gate kind for the run driver's HITL
+ * branch — known kinds plus a generic fallback (contract 02 §2.9 / §3: never
+ * crash on an unknown kind). Kept here so the §6 mapping lives in one file.
+ *
+ * ⚠️ DEAD CODE — 不是「HITL 分支漏接」(2026-07-26 全树核查,task #81 顺带件):
+ *   · 全树(src/ + mock/ + build/ + 测试)**零调用点**,adapter facade(src/seam/adapter/index.ts)
+ *     也没把它再导出去 —— 没有任何一处「本该调它却没调」。
+ *   · 它想服务的那条 HITL 分支**已经接好了**,只是没走这个函数:
+ *       - `suspended` 事件臂 → `src/seam/adapter/upstream/hitlBridge.ts:162-168` 的 `observe()`
+ *         就地做了**同款**防御回落(`ev.gate ? ev.gate : { kind: 'human' }`),而且 latch 的是整个
+ *         CheckpointGate 对象,壳侧 `currentGate()` 自己 branch `gate.kind`;
+ *       - `done{status:'suspended', checkpointGate}` 终帧 → `liveHitlAskWire.ts:89-118` /
+ *         `terminalToSdkResult.ts:296-311` 各自读 `checkpointGate.kind` **和** `.toolName`。
+ *   · 关键:每个真实消费方都同时需要 `toolName`(挑 Ask overlay vs fs 写门三选卡),而本函数只吐
+ *     一个 kind 字符串 —— 签名比任何真实需求都窄,接进去反而要再读一次 gate。
+ *   结论 = 可删的死码(留档不擅删,按 task #81 口径只标记);真要收,连同 `CheckpointGate` 的
+ *   type-only import 一起摘。
+ */
+export function gateKind(gate) {
+    return gate?.kind ?? 'human';
+}

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

@@ -0,0 +1,71 @@
+/**
+ * ⇄ B3 批搬迁(2026-07-27,多端改造设计稿 §3 B3):cli src/seam/adapter/downstream/terminalToSdkResult.ts
+ * **逐字整搬**(闭包实测 4 文件 / 零 Node 内建)。`Date.now()`(elapsedMs)是浏览器原生,原样保留。
+ */
+/**
+ * Terminal projector (T22): `done` → CC `SDKResultSuccess`, `failed` →
+ * `SDKResultError` (contract 02 §2.10/§2.11; 08 CS-10/CS-11/UC-2).
+ *
+ *  done   : result.result ⇐ TaskResult.result; result.model ⇐ TaskResult.model
+ *           (MF-25 — the served model id, e.g. "deepseek-v4-pro"); stats ⇐
+ *           flatten(TaskStats); modelUsage ⇐ stats.modelUsage (per-model split).
+ *           DROP CC stop_reason / duration_api_ms / structured_output /
+ *           fast_mode_state (contract 02 §2.10).
+ *           Budget gate is a RESULT branch, not a throw: a `done` whose
+ *           status/errorCode signals a budget cap still settles as a result
+ *           (08 CS-10) — surfaced via TaskResult.errorCode upstream, not here.
+ *  failed : flatten CC's 4 SDKResultError subtypes + errors[] into the single
+ *           {errorCode, errorMessage} pair. A user-cancelled run settles here
+ *           with errorCode:"cancelled" (08 CS-11).
+ *  park   : done{status:'suspended'|'needs_review'}(HITL/plan-review park)在无
+ *           overlay 消费面(-p / 非 REPL)也走 SDKResultError 臂 —— 绝不投影成
+ *           空成功([884]A1,见下方分支注释)。
+ *
+ * ── 终态词表全枚举分流([909]B1,2026-07-16)────────────────────────────────────────────
+ * 引擎终态 = core 1.298 TaskStatus(dist/core/types.d.ts:315)全集,共 6 词;done 帧
+ * result.status 原样骑该词表(server runs.js append("done",{result:safe}) 透传)。此前只分流
+ * failed/suspended/needs_review,timeout/blocked 落 success 臂 = TB 实锤「result 帧恒
+ * success/is_error 恒 false,含 4 个引擎已记 timeout 的 trial」。CC 2.1.207 SDKResultError
+ * subtype 词表(真源 pretty.js:765781-765786 zod enum)只有 4 词。对表:
+ *
+ *   TaskStatus      errorCode(assemble-result.js) → subtype                      is_error
+ *   ─────────────────────────────────────────────────────────────────────────────────────
+ *   completed       —                             → 'success'                     false
+ *   failed          budget.exceeded|budget.precall→ 'error_max_budget_usd'        true
+ *   failed          limit.max_turns               → 'error_max_turns'             true
+ *   failed          output.invalid                → 'error_max_structured_output_retries' true
+ *   failed          其余(含 cancelled/conflict…) → 'error_during_execution'      true
+ *   timeout         limit.timeout                 → 'error_max_turns'             true
+ *                   (CC 无 wall-clock deadline 概念;词表内最贴 = 唯一 run-limit 族词
+ *                    error_max_turns。真实语义靠 errors[] 文案 + errorCode 透传辨认。)
+ *   blocked         —(engine 只给 blockedReason)→ 'error_during_execution'      true
+ *   suspended       —                             → 'error_during_execution'      true([884]A1)
+ *   needs_review    review.pending                → 'error_during_execution'      true([884]A1)
+ *   〈未知新词〉    —                             → 'error_during_execution'      true(防御:
+ *                    非 completed 的终态一律≠空成功;errors[] 里如实报出该 status 字面)
+ *
+ * errorCode 透传:引擎 errorCode 骑 additive seam 字段 `errorCode`(CC schema 无此字段——
+ * 与 success 臂的 `model` 同款超集姿势),集成面可精确分流(limit.timeout vs cancelled …)。
+ * timeout salvage:写出窗兑现的 r.result(非空)骑 additive `result` 字段——CC error 帧无
+ * result,但把引擎已救回的最终文本静默丢弃对 -p 消费者是净损失。
+ *
+ * costUsd === 0 is AMBIGUOUS (free vs. no MODEL_COST_* configured): disambiguate
+ * upstream via Capabilities.pricingConfigured (contract 02 §2.10 VERIFY); this
+ * projector passes the number through verbatim.
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+import { type SDKMessage, type EmitContext } from '../types.js';
+/** `done` → SDKResultSuccess (contract 02 §2.10 / 08 CS-10). */
+export declare function doneToSdkResult(ev: Extract<AgentEvent, {
+    type: 'done';
+}>, ctx: EmitContext): SDKMessage;
+/** `failed` → SDKResultError (contract 02 §2.11 / 08 CS-11). */
+export declare function failedToSdkResult(ev: Extract<AgentEvent, {
+    type: 'failed';
+}>, ctx: EmitContext): SDKMessage;
+/** Dispatch a terminal AgentEvent to its SDKResult arm. */
+export declare function terminalToSdkResult(ev: Extract<AgentEvent, {
+    type: 'done';
+} | {
+    type: 'failed';
+}>, ctx: EmitContext): SDKMessage;