@sema-agent/client-core 0.2.0

package/dist/diagnostics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * diagnostics.ts — 引擎 LSP `diagnostics` 帧 → CC `diagnostics` attachment 载荷(PURE)。
+ * cli upstreamBridge case 'diagnostics' 的等价搬运(design/121):
+ *  · wire severity 是 LSP 数字(1=Error 2=Warning 3=Info 4=Hint)→ CC 字符串枚举;
+ *    缺席/越界 → 'Error'(可见胜过隐身);
+ *  · range 缺席 → 零 range 占位(渲染器必读字段);source/code 存在才铸(且一律 String 化);
+ *  · 只留 `file://` 前缀且有诊断项的文件;全滤光 ⇒ 返回 null(宿主不渲空行)。
+ */
+declare const SEV: readonly ["Error", "Warning", "Info", "Hint"];
+export interface DiagnosticsAttachment {
+    type: 'diagnostics';
+    files: Array<{
+        uri: string;
+        diagnostics: Array<{
+            message: string;
+            severity: (typeof SEV)[number];
+            range: {
+                start: {
+                    line: number;
+                    character: number;
+                };
+                end: {
+                    line: number;
+                    character: number;
+                };
+            };
+            source?: string;
+            code?: string;
+        }>;
+    }>;
+    isNew: boolean;
+}
+export declare function projectDiagnosticsFrame(frame: {
+    files?: unknown;
+    isNew?: unknown;
+}): DiagnosticsAttachment | null;
+export {};

package/dist/diagnostics.js

@@ -0,0 +1,29 @@
+/**
+ * diagnostics.ts — 引擎 LSP `diagnostics` 帧 → CC `diagnostics` attachment 载荷(PURE)。
+ * cli upstreamBridge case 'diagnostics' 的等价搬运(design/121):
+ *  · wire severity 是 LSP 数字(1=Error 2=Warning 3=Info 4=Hint)→ CC 字符串枚举;
+ *    缺席/越界 → 'Error'(可见胜过隐身);
+ *  · range 缺席 → 零 range 占位(渲染器必读字段);source/code 存在才铸(且一律 String 化);
+ *  · 只留 `file://` 前缀且有诊断项的文件;全滤光 ⇒ 返回 null(宿主不渲空行)。
+ */
+const SEV = ['Error', 'Warning', 'Info', 'Hint'];
+export function projectDiagnosticsFrame(frame) {
+    const zeroRange = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
+    const files = (Array.isArray(frame.files) ? frame.files : [])
+        .map(f => ({
+        uri: typeof f?.uri === 'string' ? f.uri : '',
+        diagnostics: (Array.isArray(f?.diagnostics)
+            ? f.diagnostics
+            : []).map(d => ({
+            message: typeof d?.message === 'string' ? d.message : '',
+            severity: SEV[(typeof d?.severity === 'number' ? d.severity : 1) - 1] ?? 'Error',
+            range: (d?.range ?? zeroRange),
+            ...(d?.source !== undefined ? { source: String(d.source) } : {}),
+            ...(d?.code !== undefined ? { code: String(d.code) } : {}),
+        })),
+    }))
+        .filter(f => f.uri.startsWith('file://') && f.diagnostics.length > 0);
+    if (files.length === 0)
+        return null;
+    return { type: 'diagnostics', files, isNew: frame.isNew === true };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @sema-agent/client-core — 客户端会话运行时(sema wire → CC 会话词汇表 + 端无关会话逻辑)。
+ * 定位公理:黑板 [1832](CC 皮肤形状全收本包、wire 保持中性;TUI/web/桌面共用同一个包)。
+ * 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 指本包)。
+ */
+export * from './seam.js';
+export * from './workflow.js';
+export * from './notifications.js';
+export * from './steering.js';
+export * from './diagnostics.js';
+export * from './retryStatus.js';
+export * from './adapt.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @sema-agent/client-core — 客户端会话运行时(sema wire → CC 会话词汇表 + 端无关会话逻辑)。
+ * 定位公理:黑板 [1832](CC 皮肤形状全收本包、wire 保持中性;TUI/web/桌面共用同一个包)。
+ * 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 指本包)。
+ */
+export * from './seam.js';
+export * from './workflow.js';
+export * from './notifications.js';
+export * from './steering.js';
+export * from './diagnostics.js';
+export * from './retryStatus.js';
+export * from './adapt.js';

package/dist/notifications.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 通知投影纯函数(抽自 sema-cli engineTaskNotification/upstreamBridge 通知臂;
+ * result 段纪律=cli #49 C1:帧带 result 必入 XML,core renderTaskNotificationXml 同名 tag 同段序)。
+ */
+/**
+ * ⚠️ 调用方契约(交叉复审 [MED] 登记):cli 原版在渲染前有两条默认值回填——
+ *   summary 缺省 ⇒ `Background task "${taskId}" ${status}`;status 非串 ⇒ 'completed'。
+ * 本纯函数不做回填(职责在 adapt() 输入侧),直接透传引擎原始 JSON 会渲出空 <summary>。
+ * 落 adapt() 时必须先补齐这两个字段再调本函数。
+ * 另注:<status> 段转义为**有意统一变更**(cli 原版曾不转义;2026-07-25 双侧统一为转义,
+ * status 为受控枚举零实际影响,顺手关闭注入面)。
+ */
+export interface TaskNotificationFields {
+    taskId: string;
+    status: string;
+    summary: string;
+    taskType?: string;
+    toolUseId?: string;
+    outputFile?: string;
+    diagnostics?: string;
+    result?: string;
+    stoppedBy?: string;
+    partial?: boolean;
+    exitCode?: number;
+    lines?: string[];
+    recentSteps?: string[];
+    resumable?: boolean;
+    externalSource?: string;
+}
+/** 通知 user-turn XML 渲染(core task-notification 同形;external 帧开标签带 from= 属性)。 */
+export declare function renderTaskNotificationXml(n: TaskNotificationFields): string;
+/**
+ * core 1.262.0 残局包([558]A/D)— 从 task_notification 帧派生残局显示行,与 core 进程内
+ * renderResidual(core/task-notification.ts:75-86)**逐字节对齐**:先 `- tool target → outcome`
+ * 步骤行,再 ONE `edited: path (×N), …` 行(editedFiles 折进 recent-steps,core 不铸独立
+ * <edited-files> tag——别自创)。字段是 additive 的,老引擎没有 ⇒ []。返回裸串,转义由调用方按
+ * 自己的面做(XML/Ink 行)。cli deriveNotificationResidualLines 的等价搬运。
+ */
+export declare function deriveNotificationResidualLines(n: Record<string, unknown>): string[];
+/**
+ * 引擎 task_notification 原始 payload → renderTaskNotificationXml 的入参(**含上面注释里那两条
+ * 回填**:summary 缺省 ⇒ `Background task "<id>" <status>`;status 非串 ⇒ 'completed')。
+ * task_id 空串/缺失 ⇒ null(RB-75 同族:空 id 会塌成 ':status' 共享桶互吞,无 id 的通知本就无意义)。
+ * 字段名映射按 wire 真形:task_id/output_file/task_type/source 是 snake/wire 名,其余同名。
+ */
+export declare function normalizeTaskNotification(n: Record<string, unknown>): TaskNotificationFields | null;
+/** 通知去重键——cli engineTaskNotificationDedupKey **逐字等价**(codex 对抗复审抓的
+ *  等价性破坏,0.1.1 修):无 seq 不追加段(与 seq:1 是不同键);仅 external 用
+ *  `external:` 前缀;seq 收 number|string。格式:`[external:]taskId:status[:seq]`。 */
+export declare function taskNotificationDedupKey(n: {
+    taskId: string;
+    status: string;
+    seq?: number | string;
+    taskType?: string;
+}): string;

package/dist/notifications.js

@@ -0,0 +1,97 @@
+/**
+ * 通知投影纯函数(抽自 sema-cli engineTaskNotification/upstreamBridge 通知臂;
+ * result 段纪律=cli #49 C1:帧带 result 必入 XML,core renderTaskNotificationXml 同名 tag 同段序)。
+ */
+function escapeXml(v) {
+    return v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** 通知 user-turn XML 渲染(core task-notification 同形;external 帧开标签带 from= 属性)。 */
+export function renderTaskNotificationXml(n) {
+    const openTag = n.taskType === 'external' && n.externalSource
+        ? `<task-notification type="external" from="${escapeXml(n.externalSource.replace(/\s+/g, ' ').slice(0, 120)).replace(/"/g, '&quot;')}">`
+        : '<task-notification>';
+    const seg = (tag, v) => (v !== undefined && v.length > 0 ? `\n<${tag}>${escapeXml(v)}</${tag}>` : '');
+    const linesBlock = n.lines && n.lines.length > 0 ? `\n<output-lines>\n${n.lines.map(escapeXml).join('\n')}\n</output-lines>` : '';
+    const stepsBlock = n.recentSteps && n.recentSteps.length > 0 ? `\n<recent-steps>${n.recentSteps.map(escapeXml).join('\n')}</recent-steps>` : '';
+    return `${openTag}
+<task-id>${escapeXml(n.taskId)}</task-id>${seg('tool-use-id', n.toolUseId)}${seg('output-file', n.outputFile)}${seg('diagnostics', n.diagnostics)}
+<status>${escapeXml(n.status)}</status>${seg('stopped-by', n.stoppedBy)}${n.partial === true ? '\n<partial>true</partial>' : ''}${typeof n.exitCode === 'number' ? `\n<exit-code>${n.exitCode}</exit-code>` : ''}
+<summary>${escapeXml(n.summary)}</summary>${seg('result', n.result)}${linesBlock}${stepsBlock}${typeof n.resumable === 'boolean' ? `\n<resumable>${n.resumable}</resumable>` : ''}
+</task-notification>`;
+}
+/**
+ * core 1.262.0 残局包([558]A/D)— 从 task_notification 帧派生残局显示行,与 core 进程内
+ * renderResidual(core/task-notification.ts:75-86)**逐字节对齐**:先 `- tool target → outcome`
+ * 步骤行,再 ONE `edited: path (×N), …` 行(editedFiles 折进 recent-steps,core 不铸独立
+ * <edited-files> tag——别自创)。字段是 additive 的,老引擎没有 ⇒ []。返回裸串,转义由调用方按
+ * 自己的面做(XML/Ink 行)。cli deriveNotificationResidualLines 的等价搬运。
+ */
+export function deriveNotificationResidualLines(n) {
+    const out = [];
+    if (Array.isArray(n.recentSteps)) {
+        for (const s of n.recentSteps) {
+            const step = (s ?? {});
+            if (typeof step.tool !== 'string' || step.tool.length === 0)
+                continue;
+            const target = typeof step.target === 'string' && step.target.length > 0 ? ` ${step.target}` : '';
+            const outcome = typeof step.outcome === 'string' && step.outcome.length > 0 ? ` → ${step.outcome}` : '';
+            out.push(`- ${step.tool}${target}${outcome}`);
+        }
+    }
+    if (Array.isArray(n.editedFiles)) {
+        const edited = n.editedFiles
+            .map(f => (f ?? {}))
+            .filter((f) => typeof f.path === 'string' && f.path.length > 0)
+            .map(f => `${f.path}${typeof f.edits === 'number' && f.edits > 1 ? ` (×${f.edits})` : ''}`);
+        if (edited.length > 0)
+            out.push(`edited: ${edited.join(', ')}`);
+    }
+    return out;
+}
+/**
+ * 引擎 task_notification 原始 payload → renderTaskNotificationXml 的入参(**含上面注释里那两条
+ * 回填**:summary 缺省 ⇒ `Background task "<id>" <status>`;status 非串 ⇒ 'completed')。
+ * task_id 空串/缺失 ⇒ null(RB-75 同族:空 id 会塌成 ':status' 共享桶互吞,无 id 的通知本就无意义)。
+ * 字段名映射按 wire 真形:task_id/output_file/task_type/source 是 snake/wire 名,其余同名。
+ */
+export function normalizeTaskNotification(n) {
+    const taskId = typeof n.task_id === 'string' && n.task_id.length > 0 ? n.task_id : undefined;
+    if (taskId === undefined)
+        return null;
+    const status = typeof n.status === 'string' ? n.status : 'completed';
+    const lines = Array.isArray(n.lines)
+        ? n.lines.filter((l) => typeof l === 'string')
+        : [];
+    const recentSteps = deriveNotificationResidualLines(n);
+    return {
+        taskId,
+        status,
+        summary: typeof n.summary === 'string' && n.summary.length > 0
+            ? n.summary
+            : `Background task "${taskId}" ${status}`,
+        ...(typeof n.task_type === 'string' ? { taskType: n.task_type } : {}),
+        ...(typeof n.toolUseId === 'string' && n.toolUseId.length > 0 ? { toolUseId: n.toolUseId } : {}),
+        ...(typeof n.output_file === 'string' && n.output_file.length > 0
+            ? { outputFile: n.output_file }
+            : {}),
+        ...(typeof n.diagnostics === 'string' && n.diagnostics.length > 0
+            ? { diagnostics: n.diagnostics }
+            : {}),
+        ...(typeof n.result === 'string' && n.result.length > 0 ? { result: n.result } : {}),
+        ...(typeof n.stoppedBy === 'string' && n.stoppedBy.length > 0 ? { stoppedBy: n.stoppedBy } : {}),
+        ...(n.partial === true ? { partial: true } : {}),
+        ...(typeof n.exitCode === 'number' ? { exitCode: n.exitCode } : {}),
+        ...(lines.length > 0 ? { lines } : {}),
+        ...(recentSteps.length > 0 ? { recentSteps } : {}),
+        ...(typeof n.resumable === 'boolean' ? { resumable: n.resumable } : {}),
+        ...(typeof n.source === 'string' && n.source.length > 0 ? { externalSource: n.source } : {}),
+    };
+}
+/** 通知去重键——cli engineTaskNotificationDedupKey **逐字等价**(codex 对抗复审抓的
+ *  等价性破坏,0.1.1 修):无 seq 不追加段(与 seq:1 是不同键);仅 external 用
+ *  `external:` 前缀;seq 收 number|string。格式:`[external:]taskId:status[:seq]`。 */
+export function taskNotificationDedupKey(n) {
+    const seq = typeof n.seq === 'number' || typeof n.seq === 'string' ? String(n.seq) : '';
+    const lane = n.taskType === 'external' ? 'external:' : '';
+    return `${lane}${n.taskId}:${n.status}${seq ? `:${seq}` : ''}`;
+}

package/dist/retryStatus.d.ts

@@ -0,0 +1,36 @@
+/**
+ * retryStatus.ts — BrainStatus liveness(§E3/§E10 `status` 臂)→ spinner retry 行状态(PURE)。
+ * cli src/sema/retryStatusStore.ts 的 mapBrainStatusToRetry 逐字搬运,唯一改动 = **时钟注入**
+ * (原版读 Date.now(),库里由调用方给 nowMs,跨端确定性 + 可测)。187 语义对位:
+ *   reconnecting → stalled  → '✻ Waiting for API response · will retry in Ns · check your network'
+ *   retrying     → error    → '✻ API error · Retrying in Ns'(非终态;187 硬编码 'API error')
+ *   rate_limited → error    → '✻ Usage limit reached · Retrying in Ns'(rateLimits 真 ⇒ 终态)
+ *   circuit_open → error    → '✻ <detail|Service temporarily unavailable> · Retrying in Ns'
+ * 绝不捏造 attempt 计数——只用引擎真给的 phase/detail/retryInSec。
+ */
+export type RetryStatus = {
+    kind: 'stalled';
+    deadline: number;
+} | {
+    kind: 'error';
+    deadline: number;
+    attempt?: number;
+    maxRetries?: number;
+    error: {
+        formatted: string;
+        isNetworkDown?: boolean;
+        connection?: {
+            isSSLError?: boolean;
+        };
+        rateLimits?: {
+            resetsAt?: number;
+            rateLimitType?: string;
+        } | null;
+    };
+};
+export interface BrainStatusPayload {
+    phase: string;
+    detail?: string;
+    retryInSec?: number;
+}
+export declare function mapBrainStatusToRetry(p: BrainStatusPayload, nowMs: number): RetryStatus;

package/dist/retryStatus.js

@@ -0,0 +1,28 @@
+/**
+ * retryStatus.ts — BrainStatus liveness(§E3/§E10 `status` 臂)→ spinner retry 行状态(PURE)。
+ * cli src/sema/retryStatusStore.ts 的 mapBrainStatusToRetry 逐字搬运,唯一改动 = **时钟注入**
+ * (原版读 Date.now(),库里由调用方给 nowMs,跨端确定性 + 可测)。187 语义对位:
+ *   reconnecting → stalled  → '✻ Waiting for API response · will retry in Ns · check your network'
+ *   retrying     → error    → '✻ API error · Retrying in Ns'(非终态;187 硬编码 'API error')
+ *   rate_limited → error    → '✻ Usage limit reached · Retrying in Ns'(rateLimits 真 ⇒ 终态)
+ *   circuit_open → error    → '✻ <detail|Service temporarily unavailable> · Retrying in Ns'
+ * 绝不捏造 attempt 计数——只用引擎真给的 phase/detail/retryInSec。
+ */
+export function mapBrainStatusToRetry(p, nowMs) {
+    const deadline = nowMs + Math.max(0, p.retryInSec ?? 0) * 1000;
+    switch (p.phase) {
+        case 'reconnecting':
+            return { kind: 'stalled', deadline };
+        case 'rate_limited':
+            return { kind: 'error', deadline, error: { formatted: '', rateLimits: {} } };
+        case 'circuit_open':
+            return {
+                kind: 'error',
+                deadline,
+                error: { formatted: p.detail ?? 'Service temporarily unavailable', isNetworkDown: true },
+            };
+        case 'retrying':
+        default:
+            return { kind: 'error', deadline, error: { formatted: '' } };
+    }
+}

package/dist/seam.d.ts

@@ -0,0 +1,187 @@
+/**
+ * client-core seam types — 黑板 [1651] 设计稿 v1.1 已对签形([1652] core 签/[1653] 钉版)。
+ *
+ * 平面判据(成文,[1652]):「重启后还该看得见的进 transcript,纯瞬态进 chrome。」
+ * transcript id 纪律([1653] v1 定案,后改=BREAKING):优先从 wire 稳定键确定性派生
+ * (StampedAgentEvent.id/seq/toolCallId),ctx.uuid() 仅兜底无稳定键合成帧;
+ * 往返守卫不变量:同流重放 ⇒ 同 id 序列。
+ */
+import type { SDKMessage } from '@sema-agent/agent-types';
+/** 宿主注入的适配上下文(时钟/铸号可测,B 形跨端确定性)。 */
+export interface AdapterContext {
+    sessionId: string;
+    /** 兜底铸号——仅当帧无稳定键时使用(见 deriveTranscriptId)。 */
+    uuid(): string;
+    now(): number;
+}
+/** chrome 平面事件 v1 枚举(cli 现役 UI 面归纳;additive 演进,臂只增不改)。
+ *
+ * v1.1 增臂(#52a adapt() 首批落码,2026-07-25):下方 8 臂随 adapt() 管线一起加入——
+ * 它们全是 cli sdkMessagesToCcEvents 里「壳态耦合」的副作用面(store 写 / hook fire /
+ * 队列操作 / 瞬态 render 事件),按 [1652] 判据(纯瞬态进 chrome)投影成事件让宿主消费。
+ * 每臂的「宿主消费义务」写在臂上方注释里——不实现该义务 = 该 UI 面在宿主上是哑的。 */
+export type ChromeEvent = {
+    kind: 'retry_status';
+    laneProof: LaneProof;
+    status: unknown;
+} | {
+    kind: 'panel_task';
+    laneProof: LaneProof;
+    event: unknown;
+} | {
+    kind: 'bgshell_settle';
+    laneProof: LaneProof;
+    taskId: string;
+    status: string;
+    outputPath?: string;
+} | {
+    kind: 'tasks_expand';
+    laneProof: LaneProof;
+} | {
+    kind: 'thinking_activity';
+    laneProof: LaneProof;
+    active: boolean;
+}
+/**
+ * 一个 turn 开场(cli `yield {type:'stream_request_start'}` 的等价面)。
+ * 宿主消费义务:把 spinner 置 'requesting' 态(CC query.ts:337 同形);不落转录。
+ */
+ | {
+    kind: 'request_start';
+    laneProof: LaneProof;
+}
+/**
+ * 合并后的活体增量(cli COALESCER 的 content_block_start/delta 语义面)。`opening`=该
+ * channel 本段首帧(宿主应先发 content_block_start 再发 delta);`estimatedTokens`=CJK 加权
+ * token 估算(cli estimateCjkTokens 同权重),给 spinner 计数用。
+ * 宿主消费义务:① 渲活体预览(streamingText/streamingThinking)② 推进 responseLength/
+ * spinner 模式 ③ 绝不落转录——committed 形随后由 transcript 平面的 assistant 消息给出。
+ */
+ | {
+    kind: 'stream_delta';
+    laneProof: LaneProof;
+    channel: 'text' | 'thinking';
+    text: string;
+    estimatedTokens: number;
+    opening: boolean;
+}
+/**
+ * 187 C1a 计量喂料(cli messageStartEvt / messageDeltaEndEvt 的语义面)。
+ * phase='start' 携 ttftMs(首 token 时延),phase='end' 携该 model round 的 outputTokens。
+ * 宿主消费义务:驱动自己的 responseLength reducer(start=压基线,end=按真 output_tokens 对账);
+ * 不落转录。
+ */
+ | {
+    kind: 'response_metrics';
+    laneProof: LaneProof;
+    phase: 'start' | 'end';
+    ttftMs?: number;
+    outputTokens?: number;
+}
+/**
+ * 非持久 attachment 行(cli 的 diagnostics / steering_injected / workspace_changed /
+ * compact_file_reference 四类 attachment render 事件)。按 [1652] 判据归 chrome:
+ * attachment 不进壳 jsonl,重启后本就该消失。
+ * 宿主消费义务:渲成自己的 attachment 行(CC 宿主=AttachmentMessage,按 attachment.type 分臂,
+ * 必须带 default 臂——core 可加新 source);`id` 为确定性行键(列表 key 用);不落转录。
+ */
+ | {
+    kind: 'attachment';
+    laneProof: LaneProof;
+    id: string;
+    attachment: unknown;
+}
+/**
+ * 一条终态 task_notification 抵达(引擎已 server-side steer-inject 过,壳侧只做记账)。
+ * 宿主消费义务(cli 现役三件,缺一即回归):
+ *  ① drop 壳队列里同 run 的 Path B 条目(workflow_complete/probe feeder),否则 idle
+ *     auto-submit 会把同一完成再喂模型一遍(跨进程双投的壳侧半场);
+ *  ② 非 background_bash:清 resident 台账(面板行终态由本帧落,不由 turn sweep 假结)。
+ * 跨通道去重(「补发通道不得再注入模型一遍」)由**适配器自持台账**负责,不摊给宿主——
+ * 见 adapt.ts 的 notifiedRuns / workflow_notification_enqueue 臂的发射门。
+ * 注:面板行 end 事件本身走 panel_task 臂、SubagentStop 走 subagent_lifecycle 臂,不重复。
+ */
+ | {
+    kind: 'notification_terminal';
+    laneProof: LaneProof;
+    taskId: string;
+    status: string;
+    taskType?: string;
+}
+/**
+ * 子代生命周期 hook 触发点(cli fireSubagentStartHook / fireSubagentStopHook)。
+ * `guard:'if-started'` = 宿主必须先查自己的「已 fire Start」台账,没 fire 过 Start 的
+ * taskId(workflow runId / 外来 id)绝不 fire Stop。
+ * 宿主消费义务:fire SubagentStart/SubagentStop hooks(observe-only,fail-soft,永不阻塞流);
+ * Start 对一个 taskId 一生只许一次(进程级台账去重,frame-lane-matrix #4)。
+ */
+ | {
+    kind: 'subagent_lifecycle';
+    laneProof: LaneProof;
+    phase: 'start' | 'stop';
+    taskId: string;
+    agentType?: string;
+    guard?: 'if-started';
+}
+/**
+ * 带外后台 workflow 完成推送(service 1.75 Path B:引擎**没有** server-side 注入,壳负责喂模型)。
+ * 宿主消费义务:把 `message`(模型面 `<task-notification>` 正文,适配器已按 core 同形铸好)
+ * 入「完成通知队列」,idle 时 auto-submit 给模型(CC RemoteAgentTask 先例,默认 'later' 优先级)。
+ * 跨通道去重(同一 run 已由推送帧记账 ⇒ 本臂根本不会发)由适配器台账保证,宿主无需再判。
+ */
+ | {
+    kind: 'workflow_notification_enqueue';
+    laneProof: LaneProof;
+    runId: string;
+    status: 'completed' | 'failed';
+    summary: string;
+    message: string;
+}
+/**
+ * 引擎侧 task 族工具调用的台账同步点(cli handleEngineTaskToolUse:引擎模式下壳工具的 call()
+ * 从不执行,ctrl+t 面板的本地 store 只能靠这条侧信道)。
+ * 宿主消费义务:按 toolUseId 幂等地把 TaskCreate/TaskUpdate 落自己的 task store(畸形 input
+ * fail-soft 丢弃);不落转录。
+ */
+ | {
+    kind: 'task_ledger_sync';
+    laneProof: LaneProof;
+    source: 'tool_use';
+    toolName: string;
+    toolUseId: string;
+    input: unknown;
+};
+/** 车道纪律一等公民([1617] 家族固化):chrome 事件构造必须携判别证明。 */
+export type LaneProof = {
+    lane: 'main';
+} | {
+    lane: 'subagent';
+    parentToolCallId: string;
+} | {
+    lane: 'workflow';
+    via: 'workflowRunId' | 'wa-id' | 'workflow-card-parent';
+    key: string;
+};
+/** 双平面输出。 */
+export type AdapterOutput = {
+    plane: 'transcript';
+    message: SDKMessage;
+} | {
+    plane: 'chrome';
+    event: ChromeEvent;
+};
+/** L3 适配器接口(实现分批落码;首版先出纯函数面,见 index.ts)。 */
+export interface WireToCcAdapter {
+    adapt(frames: AsyncIterable<unknown>, ctx: AdapterContext): AsyncGenerator<AdapterOutput>;
+    /** 台账序列化位(#9 定谳的工程化:重启恢复=台账加载+纯重放)。 */
+    exportLedger(): Record<string, unknown>;
+}
+/**
+ * transcript id 确定性派生([1653] 定案):稳定键优先序 = 帧 id > seq > toolCallId;
+ * 全缺才用 ctx.uuid()。同流重放 ⇒ 同 id 序列(往返守卫钉此不变量)。
+ */
+export declare function deriveTranscriptId(frame: {
+    id?: unknown;
+    seq?: unknown;
+    toolCallId?: unknown;
+}, ctx: Pick<AdapterContext, 'uuid'>): string;

package/dist/seam.js

@@ -0,0 +1,13 @@
+/**
+ * transcript id 确定性派生([1653] 定案):稳定键优先序 = 帧 id > seq > toolCallId;
+ * 全缺才用 ctx.uuid()。同流重放 ⇒ 同 id 序列(往返守卫钉此不变量)。
+ */
+export function deriveTranscriptId(frame, ctx) {
+    if (typeof frame.id === 'string' && frame.id.length > 0)
+        return `wid_${frame.id}`;
+    if (typeof frame.seq === 'number')
+        return `wseq_${frame.seq}`;
+    if (typeof frame.toolCallId === 'string' && frame.toolCallId.length > 0)
+        return `wtc_${frame.toolCallId}`;
+    return ctx.uuid();
+}

package/dist/steering.d.ts

@@ -0,0 +1,61 @@
+/**
+ * steering.ts — `steering_injected` → renderable attachment projection (PURE)。
+ * cli src/sema/steeringAttachments.ts 的逐字搬运(#52a;差分守卫钉两侧等价)。
+ *
+ * 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:
+ * `deadline_nudge` / `finalize` (TB telemetry B3) and the design/133 turn-boundary attachment
+ * producers `todo_reminder` / `task_reminder` / `changed_files` / `plan_mode`, plus the G1 [482]
+ * members `background_tasks` / `tools_delta` (core 1.253).
+ *
+ * [479] ask-1 contract: a renderer that branches on `source` MUST carry a default arm — core may add
+ * sources without a cross-repo lockstep. This mapper is that branch point: known sources get their
+ * copy (the 四值文案), everything else falls to the generic default row (never dropped, never a
+ * crash). PURE (no env/IO) so it unit-tests without the render graph — the wireCaps pattern.
+ *
+ * Render policy (CC 2.1.198 parity): CC NULL-renders its own turn-boundary reminders
+ * (`todo_reminder` / `task_reminder` / `plan_mode` are in NULL_RENDERING_TYPES — the user never sees
+ * them in the normal transcript). The projected `steering_injected` attachment therefore renders
+ * ONLY in transcript (ctrl+o) / verbose mode (AttachmentMessage arm) — normal-mode output stays
+ * byte-identical to CC, while sema's two-process split keeps engine-side injections observable.
+ */
+/** A sema `steering_injected` attachment (transcript/verbose-only dim row). */
+export interface SteeringInjectedAttachment {
+    type: 'steering_injected';
+    /** The wire source verbatim (open set — core may extend). */
+    source: string;
+    /** Per-source display copy (the [479] ask-1 四值 + defaults). */
+    label: string;
+    /** The injected body's first 220 chars (wire-clipped), newline-flattened by the renderer. */
+    preview: string;
+}
+/**
+ * The CC `task_status` attachment shape ([487]② G1 backgroundTasks): the SAME attachment the LOCAL
+ * post-compact path produces (services/compact/compact.ts task_status rows), so the engine's
+ * post-compact recap renders through the SAME GenericTaskStatus (vbl) component — `Task "{desc}"
+ * completed in background / still running in background / stopped`, 198 verbatim. VISIBLE (CC
+ * renders these, unlike the reminders). `outputFilePath` omitted — the task lives engine-side.
+ */
+export interface EngineTaskStatusAttachment {
+    type: 'task_status';
+    taskId: string;
+    taskType: 'local_bash';
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'killed';
+    description: string;
+    deltaSummary: null;
+}
+export type SteeringRenderable = SteeringInjectedAttachment | EngineTaskStatusAttachment;
+/** Default-arm label for a source this shell build predates. */
+export declare function steeringLabel(source: string): string;
+/**
+ * Project one `steering_injected` wire event into its renderable attachment(s). Always returns at
+ * least one attachment (default 兜底) — an engine injection is never silently invisible in
+ * transcript mode, whatever the source.
+ *
+ * `background_tasks` ([487]② G1): the preview lines parse into CC `task_status` attachments — the
+ * SAME (VISIBLE) GenericTaskStatus/vbl rendering the LOCAL post-compact path uses, three-state copy
+ * 198 verbatim, `[task_id]` addressable via TaskOutput/TaskStop. A preview clipped beyond
+ * recognition falls back to the generic (transcript-only) row — never invisible, never a crash.
+ */
+export declare function steeringInjectedToAttachments(source: string, preview: string): SteeringRenderable[];