@sema-agent/client-core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -4,7 +4,17 @@
  * seam 设计对签:[1651]/[1652]/[1653];依赖方向:sdk(wire)+agent-types(词汇表)→ 本包,永不反向。
  * 沿革:@sema-agent/wire-cc-adapter 0.1.0 = seam 类型 + id 确定性派生 + 首批踩坑纯函数;
  * 0.1.2(#52a)= adapt() 管线首批(纯投影臂全落 + 壳态耦合臂投影成 ChromeEvent + 差分守卫);
- * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包)。
+ * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包);
+ * 0.3.0 = **B1 批**(多端改造设计稿 §3 批次表第二批):纯函数/台账 11 文件 + 1 纯类型文件搬入
+ *   (壳侧 shim 替换随后批)。B1 只搬现行为、零收编、零行为改动;唯一的形状订正是 workflow.ts
+ *   补齐 `agent_runs[].errorCode` 类型位(0.2.0 抄件漏项)。
+ *
+ * 🔴 **单实例纪律**(B1 起本包不再只有纯函数):下列模块持 module 级可变状态,写方与读方必须解析到
+ * **同一个包实例** —— 壳侧本地旧副本与 npm 包同时进 bundle = 状态分裂(台账写进一份、读另一份,
+ * 症状是「台账恒空」的静默失效,不报错)。清单见各文件头 🔴 段:
+ *   workflow.ts(workflowAgentTaskIds)· subagentContentStore.ts · engineAgentPanelStore.ts ·
+ *   fleetAgentPanelProjection.ts · liveQuestionStore.ts · engineInlineTaskStats.ts ·
+ *   engineCapsCache.ts · engineToolLabelStore.ts
  */
 export * from './seam.js';
 export * from './workflow.js';
@@ -13,3 +23,13 @@ export * from './steering.js';
 export * from './diagnostics.js';
 export * from './retryStatus.js';
 export * from './adapt.js';
+export * from './subagentContentStore.js';
+export * from './engineAgentPanelStore.js';
+export * from './fleetAgentPanelProjection.js';
+export * from './liveQuestionStore.js';
+export * from './engineInlineTaskStats.js';
+export * from './printToolResultFrame.js';
+export * from './engineCapsCache.js';
+export * from './engineToolLabelStore.js';
+export * from './fleetTaskDesc.js';
+export type * from './types/engineState.js';

package/dist/index.js

@@ -4,7 +4,17 @@
  * seam 设计对签:[1651]/[1652]/[1653];依赖方向:sdk(wire)+agent-types(词汇表)→ 本包,永不反向。
  * 沿革:@sema-agent/wire-cc-adapter 0.1.0 = seam 类型 + id 确定性派生 + 首批踩坑纯函数;
  * 0.1.2(#52a)= adapt() 管线首批(纯投影臂全落 + 壳态耦合臂投影成 ChromeEvent + 差分守卫);
- * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包)。
+ * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包);
+ * 0.3.0 = **B1 批**(多端改造设计稿 §3 批次表第二批):纯函数/台账 11 文件 + 1 纯类型文件搬入
+ *   (壳侧 shim 替换随后批)。B1 只搬现行为、零收编、零行为改动;唯一的形状订正是 workflow.ts
+ *   补齐 `agent_runs[].errorCode` 类型位(0.2.0 抄件漏项)。
+ *
+ * 🔴 **单实例纪律**(B1 起本包不再只有纯函数):下列模块持 module 级可变状态,写方与读方必须解析到
+ * **同一个包实例** —— 壳侧本地旧副本与 npm 包同时进 bundle = 状态分裂(台账写进一份、读另一份,
+ * 症状是「台账恒空」的静默失效,不报错)。清单见各文件头 🔴 段:
+ *   workflow.ts(workflowAgentTaskIds)· subagentContentStore.ts · engineAgentPanelStore.ts ·
+ *   fleetAgentPanelProjection.ts · liveQuestionStore.ts · engineInlineTaskStats.ts ·
+ *   engineCapsCache.ts · engineToolLabelStore.ts
  */
 export * from './seam.js';
 export * from './workflow.js';
@@ -13,3 +23,13 @@ export * from './steering.js';
 export * from './diagnostics.js';
 export * from './retryStatus.js';
 export * from './adapt.js';
+// ── B1 批:纯函数 / 侧信道台账 / 投影闸(2026-07-27)──────────────────────────────────────────
+export * from './subagentContentStore.js';
+export * from './engineAgentPanelStore.js';
+export * from './fleetAgentPanelProjection.js';
+export * from './liveQuestionStore.js';
+export * from './engineInlineTaskStats.js';
+export * from './printToolResultFrame.js';
+export * from './engineCapsCache.js';
+export * from './engineToolLabelStore.js';
+export * from './fleetTaskDesc.js';

package/dist/liveQuestionStore.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/liveQuestionStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 本模块自持 AskUserQuestion 的 wire 词汇(SDK 0.0.44 删掉了 questions 资源导出),搬入后这套
+ * 类型随包发布 —— web/桌面端的 HITL 覆盖层与 TUI 共用同一份 QuestionFrame/QuestionAnswer 形。
+ */
+/**
+ * src/sema/liveQuestionStore.ts — the SIDE-CHANNEL for §4④ live-stream AskUserQuestion (the conversation-seam
+ * twin of liveSessionStore.ts).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * In TOC (two-process) the MODEL runs in the engine; its `AskUserQuestion` tool fires on core's
+ * `RunnerDeps.onQuestion` seam and the service (question.ts, 1.61.0) emits a NAMED SSE frame
+ * (`event: question` / `event: question_complete`) that INTERLEAVES on the same live token stream as the
+ * AgentEvents. That frame is NOT an AgentEvent arm (it is a DISTINCT vocabulary, exactly like elicitation) —
+ * so it must be DEMUXED out of the transcript-render pipeline and routed to an interactive DIALOG overlay
+ * instead. This tiny, dependency-FREE module is that route: liveClient WRITES the demuxed frame here (on each
+ * `question`/`question_complete`) and publishes its `client.questions.respond` binding; the UI overlay
+ * (main.tsx / REPL) READS the frames and answers via `respondToQuestion`. Same shape as liveSessionStore /
+ * rewindAnchorStore — the overlay stays testable (no @sema-ai/sdk graph) and seamQuery/normalizeToolNames are
+ * untouched.
+ *
+ * 🔴 LIVE-ONLY + SAME-REPLICA (the `steer()`-class of HITL): the service parks the answer promise in-memory,
+ * so a respond that lands after the TTL (5 min) / after answer / on another replica → 404. No durable resume
+ * anchor — a mid-question disconnect just lets the run proceed with the headless default (the model never
+ * hangs). The overlay must therefore treat `respondToQuestion` as best-effort (a 404 = "already released",
+ * dismiss the dialog, never retry).
+ *
+ * 🔴 UNTRUSTED: the `questions` payload is model-authored (service secret-redacted, but still UNTRUSTED for
+ * display). The overlay RENDERS it; it must NEVER be re-fed to a model. The answer the overlay sends back is
+ * fenced by CORE (`selected ⊆ options`, `note` untrusted-fenced) — the overlay must echo the EXACT option
+ * labels the user saw, never fabricate one.
+ */
+/** One option of an AskUserQuestion question (CC AskUserQuestionTool option shape). */
+export interface AskQuestionOption {
+    /** EXACT display label — the answer echoes labels verbatim (core fences `selected ⊆ options`). */
+    label: string;
+    description?: string;
+}
+/** One model-authored question (UNTRUSTED: render-only, never re-fed to a model). */
+export interface AskQuestion {
+    /** The question text (the CC dialog keys its answers Record by this). */
+    question: string;
+    /** Short header — the WIRE answer is keyed by this (see {@link QuestionAnswer}). */
+    header: string;
+    options: AskQuestionOption[];
+    multiSelect: boolean;
+}
+/** A demuxed/synthetic live question frame (legacy 1.61 wire payload `{type,questionId,questions?,outcome?}`;
+ *  today also synthesized locally by liveHitlAskWire (`hitl-ask:*`) and planReviewWire (`plan-review:*`)).
+ *  `question` opens the dialog overlay; `question_complete` dismisses a still-open one. */
+export interface QuestionFrame {
+    type: 'question' | 'question_complete';
+    questionId: string;
+    /** Present on `question` frames; may be absent when the service dropped an over-cap payload. */
+    questions?: AskQuestion[];
+    /** `question_complete` only (legacy wire): why the ask was released (answered/expired/aborted). */
+    outcome?: string;
+}
+/** The answer the overlay sends back — keyed by HEADER; `selected` echoes exact option labels
+ *  (`selected ⊆ options`, core's fence); off-list / free-text input rides `note` (untrusted-fenced).
+ *  Entry shape === hitlBridge's AskAnswer (the T23 ApprovalDecision.answer leg consumes it as-is). */
+export interface QuestionAnswer {
+    answers: Array<{
+        header: string;
+        selected: string[];
+        note?: string;
+    }>;
+}
+type QuestionFrameHandler = (frame: QuestionFrame) => void;
+type RespondFn = (id: string, answer: QuestionAnswer, opts?: {
+    signal?: AbortSignal;
+}) => Promise<unknown>;
+/** Register a one-shot local responder for a SYNTHETIC question frame (e.g. `plan-review:<taskId>`).
+ *  Returns an unregister fn (dialog dismissed without answering ⇒ caller cleans up). */
+export declare function registerLocalQuestionResponder(id: string, fn: RespondFn): () => void;
+/**
+ * Publish a demuxed live question frame (called from liveClient's demuxQuestionFrames on each
+ * `question`/`question_complete`). Best-effort: a UI handler error is swallowed so a broken overlay can NEVER
+ * break the live stream drain (the run must keep flowing; a lost frame just headless-defaults the ask).
+ */
+export declare function publishQuestionFrame(frame: QuestionFrame): void;
+/** Whether a UI overlay is currently subscribed (liveHitlAskWire gates on this: print/non-REPL mode has no
+ *  dialog to park on, so the suspended terminal must fall through honestly instead of hanging the stream). */
+export declare function hasQuestionOverlay(): boolean;
+/** Subscribe the UI overlay to live question frames. Returns an unsubscribe. Last writer wins (one overlay). */
+export declare function onQuestionFrame(handler: QuestionFrameHandler): () => void;
+/** Publish the live client's `questions.respond` binding (called from createLiveConversationClient). `null`
+ *  clears it (offline/mock → respondToQuestion rejects cleanly). */
+export declare function setQuestionRespond(fn: RespondFn | null): void;
+/**
+ * Answer a parked live question (POST /v1/questions/:id/respond via the live client). Rejects when no live
+ * client is wired (offline/mock) so the overlay can fall back / dismiss. The 404 (answered/expired/wrong
+ * replica) surfaces as a thrown ApiError — the overlay treats it as "already released", never a retry.
+ */
+export declare function respondToQuestion(id: string, answer: QuestionAnswer, opts?: {
+    signal?: AbortSignal;
+}): Promise<unknown>;
+/** Test-only reset. */
+export declare function _resetLiveQuestionStore(): void;
+export {};

package/dist/liveQuestionStore.js

@@ -0,0 +1,109 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/liveQuestionStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 本模块自持 AskUserQuestion 的 wire 词汇(SDK 0.0.44 删掉了 questions 资源导出),搬入后这套
+ * 类型随包发布 —— web/桌面端的 HITL 覆盖层与 TUI 共用同一份 QuestionFrame/QuestionAnswer 形。
+ */
+/**
+ * src/sema/liveQuestionStore.ts — the SIDE-CHANNEL for §4④ live-stream AskUserQuestion (the conversation-seam
+ * twin of liveSessionStore.ts).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * In TOC (two-process) the MODEL runs in the engine; its `AskUserQuestion` tool fires on core's
+ * `RunnerDeps.onQuestion` seam and the service (question.ts, 1.61.0) emits a NAMED SSE frame
+ * (`event: question` / `event: question_complete`) that INTERLEAVES on the same live token stream as the
+ * AgentEvents. That frame is NOT an AgentEvent arm (it is a DISTINCT vocabulary, exactly like elicitation) —
+ * so it must be DEMUXED out of the transcript-render pipeline and routed to an interactive DIALOG overlay
+ * instead. This tiny, dependency-FREE module is that route: liveClient WRITES the demuxed frame here (on each
+ * `question`/`question_complete`) and publishes its `client.questions.respond` binding; the UI overlay
+ * (main.tsx / REPL) READS the frames and answers via `respondToQuestion`. Same shape as liveSessionStore /
+ * rewindAnchorStore — the overlay stays testable (no @sema-ai/sdk graph) and seamQuery/normalizeToolNames are
+ * untouched.
+ *
+ * 🔴 LIVE-ONLY + SAME-REPLICA (the `steer()`-class of HITL): the service parks the answer promise in-memory,
+ * so a respond that lands after the TTL (5 min) / after answer / on another replica → 404. No durable resume
+ * anchor — a mid-question disconnect just lets the run proceed with the headless default (the model never
+ * hangs). The overlay must therefore treat `respondToQuestion` as best-effort (a 404 = "already released",
+ * dismiss the dialog, never retry).
+ *
+ * 🔴 UNTRUSTED: the `questions` payload is model-authored (service secret-redacted, but still UNTRUSTED for
+ * display). The overlay RENDERS it; it must NEVER be re-fed to a model. The answer the overlay sends back is
+ * fenced by CORE (`selected ⊆ options`, `note` untrusted-fenced) — the overlay must echo the EXACT option
+ * labels the user saw, never fabricate one.
+ */
+/* ── LOCAL wire types (owned HERE, not @sema-ai/sdk) ─────────────────────────────────────────────
+ * SDK 0.0.44 DELETED the `questions` resource (engine 1.163 parks the run `suspended` instead of
+ * emitting `question` SSE frames — see liveHitlAskWire.ts), and with it the QuestionFrame /
+ * QuestionAnswer / AskQuestion exports. The shell still speaks this vocabulary INTERNALLY (synthetic
+ * frames from liveHitlAskWire / planReviewWire + the legacy 1.61-era SSE demux in liveClient), so the
+ * types now live in THIS dependency-free module — the store this whole seam already routes through.
+ * Shapes are the ones the shell actually produces/consumes (askq-wire-probe + overlay usage), byte-
+ * compatible with the old wire payload `{type,questionId,questions?,outcome?}`. */
+let frameHandler = null;
+let respondFn = null;
+/** SHELL-LOCAL question responders (plan-review approval cards etc. — synthetic frames whose id does
+ *  NOT exist engine-side, so POST /v1/questions/:id/respond would 404). Registered per-questionId by
+ *  the frame's publisher; consumed once (respond removes the entry). Checked BEFORE the live respond. */
+const localResponders = new Map();
+/** Register a one-shot local responder for a SYNTHETIC question frame (e.g. `plan-review:<taskId>`).
+ *  Returns an unregister fn (dialog dismissed without answering ⇒ caller cleans up). */
+export function registerLocalQuestionResponder(id, fn) {
+    localResponders.set(id, fn);
+    return () => {
+        localResponders.delete(id);
+    };
+}
+/**
+ * Publish a demuxed live question frame (called from liveClient's demuxQuestionFrames on each
+ * `question`/`question_complete`). Best-effort: a UI handler error is swallowed so a broken overlay can NEVER
+ * break the live stream drain (the run must keep flowing; a lost frame just headless-defaults the ask).
+ */
+export function publishQuestionFrame(frame) {
+    if (!frameHandler)
+        return;
+    try {
+        frameHandler(frame);
+    }
+    catch {
+        /* a UI handler throw must never propagate into the AgentEvent drain */
+    }
+}
+/** Whether a UI overlay is currently subscribed (liveHitlAskWire gates on this: print/non-REPL mode has no
+ *  dialog to park on, so the suspended terminal must fall through honestly instead of hanging the stream). */
+export function hasQuestionOverlay() {
+    return frameHandler !== null;
+}
+/** Subscribe the UI overlay to live question frames. Returns an unsubscribe. Last writer wins (one overlay). */
+export function onQuestionFrame(handler) {
+    frameHandler = handler;
+    return () => {
+        if (frameHandler === handler)
+            frameHandler = null;
+    };
+}
+/** Publish the live client's `questions.respond` binding (called from createLiveConversationClient). `null`
+ *  clears it (offline/mock → respondToQuestion rejects cleanly). */
+export function setQuestionRespond(fn) {
+    respondFn = fn;
+}
+/**
+ * Answer a parked live question (POST /v1/questions/:id/respond via the live client). Rejects when no live
+ * client is wired (offline/mock) so the overlay can fall back / dismiss. The 404 (answered/expired/wrong
+ * replica) surfaces as a thrown ApiError — the overlay treats it as "already released", never a retry.
+ */
+export function respondToQuestion(id, answer, opts) {
+    const local = localResponders.get(id);
+    if (local) {
+        localResponders.delete(id); // one-shot — a second respond on the same card must not double-fire
+        return local(id, answer, opts);
+    }
+    if (!respondFn) {
+        return Promise.reject(new Error('no live question respond wired (offline/mock path)'));
+    }
+    return respondFn(id, answer, opts);
+}
+/** Test-only reset. */
+export function _resetLiveQuestionStore() {
+    frameHandler = null;
+    respondFn = null;
+}

package/dist/printToolResultFrame.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/printToolResultFrame.ts 逐字搬入,
+ * 唯一改动 = `SDKMessage` 的 type-only import 从壳内 `../seam/adapter/index.js` 改指
+ * `@sema-agent/agent-types`(type-only,零运行时边)。
+ *
+ * 🔴 **这两个 SDKMessage 不是同一个 symbol**(实测,别沿用「re-export」的想当然):壳侧
+ * `src/seam/adapter/types.ts:35` 是 `z.infer<ReturnType<typeof SDKMessageSchema>>` —— CC 自己
+ * `src/entrypoints/sdk/coreSchemas.ts` 里 zod schema 的推断型;本包用的是 agent-types 手写 `.d.ts`
+ * 的同名镜像联合。两者都镜像 CC 的同一个 union,但**是两条独立的类型来源**。
+ * 本函数返回值本来就走 `as unknown as SDKMessage`(见文件末),所以搬迁没有改变任何运行时字节;
+ * ⚠️ 但**壳侧 shim 时要过一道 tsc**:`seamQueryEngine.ask` 那个消费点期望的是 zod 推断型,
+ * 换成 agent-types 型后若不结构兼容,tsc 会在 shim 那一刻报——那是真信号,不要用 any 压掉。
+ *
+ * ⚠️ 设计稿 §8-5 把 print lane 的归属列为未决裁量点 —— 本文件是纯投影(tool_end arm → CC user 帧),
+ * 任何端的「工具失败」判据都要它,故按 B1 清单搬入;`-p` 车道的**消费方**仍在壳侧。
+ */
+/**
+ * src/sema/printToolResultFrame.ts — headless `-p` 车道的 CC `user`/tool_result 帧合成
+ * ([909]B1「工具错误置 is_error」半句勘察定案,2026-07-16)。
+ *
+ * 勘察结论(真行为实证,dist 自 spawn 引擎 + 失败 Bash 调用):`-p --output-format stream-json
+ * --verbose` 的 stdout 里【零】tool_result 帧——既不是壳写死 is_error:false,也不是引擎帧失真:
+ * 引擎 tool_end.isError 一路如实到壳(eventToSdkMessage.ts tool_end 臂 → 内部 tool_end_result arm),
+ * 但 seamQueryEngine.ask 的消费循环把该 arm 整帧吞掉(此前 :506 `continue`,swallow 注释自证)。
+ * TB「~4000 个 Bash 调用 is_error:true 零次」= 语料里只有 assistant/tool_use 帧,工具结果面整体缺席。
+ *
+ * CC 2.1.207 对表:`-p --verbose` 的 stream-json 在每个工具收尾后发
+ *   {type:'user', message:{role:'user', content:[{type:'tool_result', tool_use_id, content,
+ *    is_error}]}, parent_tool_use_id, uuid, session_id}
+ * (SDKUserMessage 信封;交互 REPL 侧 upstreamBridge.ts:1323-1343 已按同款形状合成给渲染面)。
+ * 本模块把内部 arm 投影成该形状,`-p` 集成面从此能从流里辨认工具失败(is_error 如实透传)。
+ *
+ * 车道纪律:只被 seamQueryEngine.ask(headless `-p`)消费;交互 REPL 走 upstreamBridge 的
+ * deferred-close 管线,一根毛不动。
+ */
+import type { SDKMessage } from '@sema-agent/agent-types';
+/**
+ * Flatten the §E1 wire `output`(NON-UNIFORM: `string` | `(TextContent|ImageContent)[]`)into one
+ * plain-text blob(upstreamBridge.flattenWireOutput 同款语义的轻量副本——避免把重量级 REPL 桥
+ * 拖进 `-p` 车道的 import 图)。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ */
+export declare function flattenToolOutput(output: unknown): string;
+/** 内部 tool_end_result arm(eventToSdkMessage.ts:213-231 铸造)的防御性读形。 */
+export interface ToolEndResultArmLike {
+    type?: unknown;
+    toolCallId?: unknown;
+    toolName?: unknown;
+    isError?: unknown;
+    output?: unknown;
+    truncated?: unknown;
+    parentToolCallId?: unknown;
+    uuid?: unknown;
+    session_id?: unknown;
+}
+/**
+ * tool_end_result arm → CC `user`/tool_result SDK 帧。toolCallId 缺失(防御:未来 wire 变形)
+ * 返回 null,调用方维持原 swallow 行为(绝不发无法对账的孤儿 tool_result)。
+ */
+export declare function toolEndResultToUserFrame(arm: ToolEndResultArmLike): SDKMessage | null;

package/dist/printToolResultFrame.js

@@ -0,0 +1,65 @@
+/**
+ * Flatten the §E1 wire `output`(NON-UNIFORM: `string` | `(TextContent|ImageContent)[]`)into one
+ * plain-text blob(upstreamBridge.flattenWireOutput 同款语义的轻量副本——避免把重量级 REPL 桥
+ * 拖进 `-p` 车道的 import 图)。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ */
+export function flattenToolOutput(output) {
+    if (typeof output === 'string')
+        return output;
+    if (Array.isArray(output)) {
+        const parts = [];
+        for (const block of output) {
+            if (block && typeof block === 'object') {
+                const b = block;
+                if (b.type === 'text' && typeof b.text === 'string')
+                    parts.push(b.text);
+                else if (b.type === 'image')
+                    parts.push('[image]');
+            }
+        }
+        return parts.join('');
+    }
+    return '';
+}
+/**
+ * Bash 臂的 is_error 派生(真行为实证,2026-07-16):引擎 tool_end.isError 语义 = 「工具本身
+ * 是否执行失败」——命令非零退出时工具照常返回模型面框架文本(core runShell `exit code: N\n---
+ * stdout ---…`)且 isError:false。CC 2.1.207 的 Bash tool_result 对非零退出置 is_error:true;
+ * 交互 REPL 桥已按同款派生(upstreamBridge.ts:384 `failed = isError || exitCode !== 0`)。
+ * 这里对 Bash 输出的框架头做同源轻量嗅探(不拖 REPL 桥的重 import 图)。
+ */
+function bashExitCodeFailed(toolName, text) {
+    if (typeof toolName !== 'string' || toolName.toLowerCase() !== 'bash')
+        return false;
+    const m = /^exit code: (\d+)\b/.exec(text);
+    return m !== null && m[1] !== '0';
+}
+/**
+ * tool_end_result arm → CC `user`/tool_result SDK 帧。toolCallId 缺失(防御:未来 wire 变形)
+ * 返回 null,调用方维持原 swallow 行为(绝不发无法对账的孤儿 tool_result)。
+ */
+export function toolEndResultToUserFrame(arm) {
+    if (typeof arm.toolCallId !== 'string' || arm.toolCallId.length === 0)
+        return null;
+    const text = flattenToolOutput(arm.output);
+    return {
+        type: 'user',
+        message: {
+            role: 'user',
+            content: [
+                {
+                    type: 'tool_result',
+                    tool_use_id: arm.toolCallId,
+                    // truncated 输出如实标注(观察面注记;截断体绝不回喂模型——upstreamBridge 同款)。
+                    content: arm.truncated === true ? `${text}\n…(truncated)` : text,
+                    is_error: arm.isError === true || bashExitCodeFailed(arm.toolName, text),
+                },
+            ],
+        },
+        parent_tool_use_id: typeof arm.parentToolCallId === 'string' ? arm.parentToolCallId : null,
+        // eventToSdkMessage 已 stamp 的 uuid/session_id 原样骑帧(uuid = core-minted eventId 优先级
+        // 在 stamp 里已定);缺失时留 undefined,print 面容忍(CC 消费者按可选读)。
+        uuid: arm.uuid,
+        session_id: arm.session_id,
+    };
+}

package/dist/steering.d.ts

@@ -2,6 +2,10 @@
  * steering.ts — `steering_injected` → renderable attachment projection (PURE)。
  * cli src/sema/steeringAttachments.ts 的逐字搬运(#52a;差分守卫钉两侧等价)。
  *
+ * B1 批(2026-07-27):本文件正文与 cli `steeringAttachments.ts` 实测**逐字节相同**(`diff` 空),
+ * 按设计稿 §2.4.1-A 裁决「不留两份实现」⇒ 本文件即唯一实现,壳侧文件改成本包的 re-export。
+ * 双份消解方式是「壳侧让位」而非合并 —— 无需改动本文件任何一行行为码。
+ *
  * core 1.251 (design/133, board [479] ask-1) echoes every engine-side SYSTEM steering injection as a
  * `steering_injected` wire event `{source, preview}` — `preview` = the injected body's first 220 chars
  * (runtask.ts:2320), echo-only (the model-facing message is unchanged). Sources today:

package/dist/steering.js

@@ -2,6 +2,10 @@
  * steering.ts — `steering_injected` → renderable attachment projection (PURE)。
  * cli src/sema/steeringAttachments.ts 的逐字搬运(#52a;差分守卫钉两侧等价)。
  *
+ * B1 批(2026-07-27):本文件正文与 cli `steeringAttachments.ts` 实测**逐字节相同**(`diff` 空),
+ * 按设计稿 §2.4.1-A 裁决「不留两份实现」⇒ 本文件即唯一实现,壳侧文件改成本包的 re-export。
+ * 双份消解方式是「壳侧让位」而非合并 —— 无需改动本文件任何一行行为码。
+ *
  * core 1.251 (design/133, board [479] ask-1) echoes every engine-side SYSTEM steering injection as a
  * `steering_injected` wire event `{source, preview}` — `preview` = the injected body's first 220 chars
  * (runtask.ts:2320), echo-only (the model-facing message is unchanged). Sources today:

package/dist/subagentContentStore.d.ts

@@ -0,0 +1,131 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/subagentContentStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 module 级台账(tasks/parentToTask/ownEngineRuns/bgFacts)= 单实例语义:写方(seam adapter
+ * runStream 的子代内容分流 + liveClient 的 run_started own 台账)与读方(查看态/帧级 own 判别)
+ * 必须走**同一个模块实例**,否则 own 判别恒 false(帧级校验静默失效)。
+ */
+/**
+ * subagentContentStore — dep-free side-channel store for ENGINE subagent CONTENT events (C1 consumption,
+ * service 1.89 `forwardSubagentEvents` + core 1.219; blackboard [381]⑤/[383]③).
+ *
+ * WIRE FACTS: with `forwardSubagentEvents: true` on the task request, the live stream carries the
+ * subagent's text_delta / reasoning_delta / tool_start / tool_end stamped with EventIdentity
+ * {taskId, parentToolCallId} (§E1 redact upstream; §E2 identity). The seam adapter (runStream.ts)
+ * DIVERTS those events here — they must never reach the main-transcript pipeline (a subagent's tokens
+ * rendering as the leader's text is the pollution failure mode).
+ *
+ * WHAT IT KEEPS (bounded, per task):
+ *   - a NEUTRAL item log: {kind:'text'|'thinking',text} | {kind:'tool',name,input,output,isError,id}
+ *     (ring-capped) — the 查看态 transcript backlog, so entering a running agent mid-flight still shows
+ *     history. Message SHAPES are built by the consumers (engineAgentView/chrome-agentprogress own the
+ *     CC message creators; this store stays dep-free like engineAgentPanelStore).
+ *   - live accumulation buffers (streaming text/thinking not yet segment-closed).
+ *   - taskId → parentToolCallId (the C2 steer target — service routes subagent steer by parentToolCallId).
+ *
+ * NOTIFY: coalesced (~250ms) per-task notify so a per-token delta storm never turns into per-token
+ * AppState writes; consumers pull a snapshot on notify.
+ */
+export type SubagentContentItem = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'thinking';
+    text: string;
+} | {
+    kind: 'tool';
+    id: string;
+    name: string;
+    input: unknown;
+    output?: string;
+    isError?: boolean;
+}
+/** local user echo (查看态 composer 插话) — rides in the item log so a full rebuild keeps it in order */
+ | {
+    kind: 'echo';
+    text: string;
+};
+export interface SubagentContentEvent {
+    type: 'text_delta' | 'reasoning_delta' | 'tool_start' | 'tool_end';
+    taskId: string;
+    parentToolCallId: string;
+    delta?: string;
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+    output?: string;
+    isError?: boolean;
+}
+/** Register the parentToolCallId ↔ engine-taskId pair (from task_progress, which carries both).
+ *  Content parked under the parent key migrates to the canonical task key. */
+export declare function registerSubagentAlias(parentToolCallId: string, taskId: string): void;
+export declare function publishSubagentContentEvent(ev: SubagentContentEvent): void;
+/** 查看态 composer echo (C2 steer optimistic display) — segment-closes the buffers first so the echo
+ *  lands AFTER the text streamed before it. taskId may be unseen (row entered before any content):
+ *  parentToolCallId may then be unknown — pass '' and the steer path resolves the target separately. */
+export declare function pushSubagentLocalEcho(taskId: string, text: string): void;
+export interface SubagentContentSnapshot {
+    items: SubagentContentItem[];
+    /** streaming tails not yet segment-closed (render as the live trailing message) */
+    textBuf: string;
+    thinkBuf: string;
+}
+export declare function getSubagentContentSnapshot(taskId: string): SubagentContentSnapshot | null;
+/**
+ * 一个查看态转录槽位。`slot` = 稳定 key(消费端拿去当 message uuid —— 250ms 一次的重组不换 key);
+ * `live: true` = 尚未段闭合的流式尾巴(下一次段闭合后由同内容的真 item 接位)。
+ */
+export type SubagentViewSlot = {
+    kind: 'text';
+    slot: string;
+    text: string;
+    live?: true;
+} | {
+    kind: 'thinking';
+    slot: string;
+    text: string;
+    live?: true;
+} | {
+    kind: 'echo';
+    slot: string;
+    text: string;
+} | {
+    kind: 'tool';
+    slot: string;
+    id: string;
+    name: string;
+    input: unknown;
+    /** undefined = tool_start 已到、tool_end 未到(在飞工具:卡先上屏,结果就地补) */
+    output?: string;
+    isError?: boolean;
+};
+/**
+ * 把一个子代的内容账本投影成查看态渲染计划。
+ *
+ * [1568] 之前的形(壳侧 engineAgentView 里)有两处「等段闭合」:①遇到第一个未闭合工具就 break;
+ * ②textBuf/thinkBuf 完全不投影。实测(engine 1.275.0 真跑):数据面 ~23 帧/s 的 delta 连续到壳,
+ * 查看态却只在 tool 边界更新(进查看态后 6.0s 全空,之后每 5–15s 才动一次)。现形:在飞工具照投,
+ * 流式尾巴作为 live 槽投 —— 屏面粒度 = wire 粒度(store notify 已按 250ms 合并)。
+ */
+export declare function planSubagentViewSlots(taskId: string): SubagentViewSlot[];
+/** C2 steer target: the service routes subagent steer by the delegating tool call's id. */
+export declare function parentToolCallIdOf(taskId: string): string | undefined;
+/** Settle a task's streaming buffers (turn ended / run settled) so the snapshot is complete. */
+export declare function settleSubagentContent(taskId: string): void;
+export declare function clearSubagentContent(taskId: string): void;
+export interface BgTerminalFacts {
+    status: string;
+    summary?: string;
+    recentSteps?: Array<{
+        tool?: string;
+        target?: string;
+        outcome?: string;
+    }>;
+}
+export declare function recordBgTerminalFacts(taskId: string, facts: BgTerminalFacts): void;
+export declare function getBgTerminalFacts(taskId: string): BgTerminalFacts | undefined;
+export declare function recordBgParentRun(taskId: string, runId: string): void;
+export declare function getBgParentRun(taskId: string): string | undefined;
+export declare function recordOwnEngineRun(runId: string): void;
+export declare function isOwnEngineRun(runId: string): boolean;
+/** Single consumer (the panel hook). Returns an unsubscribe. */
+export declare function subscribeSubagentContent(fn: (taskId: string) => void): () => void;