@sema-agent/client-core 0.4.0 → 0.6.0

package/dist/seam.d.ts

@@ -6,13 +6,69 @@
  * (StampedAgentEvent.id/seq/toolCallId),ctx.uuid() 仅兜底无稳定键合成帧;
  * 往返守卫不变量:同流重放 ⇒ 同 id 序列。
  */
-import type { SDKMessage } from '@sema-agent/agent-types';
-/** 宿主注入的适配上下文(时钟/铸号可测,B 形跨端确定性)。 */
+import type { ModelUsage, SDKMessage } from '@sema-agent/agent-types';
+/**
+ * `AbortSignal` 的结构型(B3 扩容,SEAM-GAP-4)。
+ *
+ * 🔴 **别写成 `AbortSignal`**:本包 tsconfig 是 `"types": []` + 无 DOM lib(浏览器可移植性的
+ * 静态保障),`AbortSignal` 这个名字在本包里根本不存在。真 `AbortSignal`(浏览器原生 / Node
+ * globalThis)结构上满足本型,直接传即可,零适配。
+ */
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+}
+/** 宿主定时器句柄(不透明:Node 是 Timeout 对象、浏览器是 number,库侧只负责回传)。 */
+export type TimerHandle = unknown;
+/** `ctx.log` 的级别词表(cli utils/debug logForDebugging 的等价面)。 */
+export type AdapterLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * 宿主注入的适配上下文(时钟/铸号可测,B 形跨端确定性)。
+ *
+ * **B3 扩容(0.5.0,契约 minor —— 只加可选位,既有宿主零改动)**:下面五个可选口是
+ * 「客户端内核需要、但实现方式因端而异」的能力(设计稿 §5.4①)。浏览器实现全部原生零 polyfill:
+ * `log`→console/上报、`probe`→省略、`signal`→AbortController.signal、
+ * `setTimer/clearTimer`→setTimeout/clearTimeout。
+ *
+ * 🔴 **缺席语义都是「该能力不启用」,不是「报错」也不是「换个方式偷偷做」**:
+ * 内核绝不 `require('fs')` 写探针、绝不 `console.log`、绝不 `setTimeout` 兜底 ——
+ * 那正是这批要切掉的东西(§5.2 的 33 个 `utils/debug` 消费点)。
+ */
 export interface AdapterContext {
     sessionId: string;
     /** 兜底铸号——仅当帧无稳定键时使用(见 deriveTranscriptId)。 */
     uuid(): string;
     now(): number;
+    /**
+     * 诊断日志(替 cli `utils/debug.logForDebugging` —— 那一行 import 就把 1565 个文件拉进闭包,
+     * 是浏览器可移植性的头号污染源,设计稿 §2.1.3)。缺席 = 内核静默(绝不回落 console)。
+     */
+    log?(level: AdapterLogLevel, msg: string, data?: unknown): void;
+    /**
+     * 行式探针(替 cli 的 6 处 `SEMA_*_PROBE` 文件探针 —— Ink 挂载后 console 被吞,壳侧靠写文件
+     * 取证)。`channel` = 探针名(如 `'stream'`),`line` = 单行载荷。浏览器宿主直接省略。
+     */
+    probe?(channel: string, line: string): void;
+    /**
+     * turn 级中断信号(SEAM-GAP-4)。Esc/abort 后内核立刻停止投影,**不产终答**
+     * (CC 自己的 abort 路径渲 InterruptedByUser chrome,由宿主负责)。
+     * 缺席 = 该 turn 不可中断(既有行为)。
+     */
+    signal?: AbortSignalLike;
+    /**
+     * 宿主定时器(T40 IDLE-FLUSH 竞速需要)。`fn` 到点执行一次。
+     * 🔴 **缺席 = IDLE-FLUSH 过渡修不启用**(纯等下一帧,与 0.4.0 逐字同行为)——绝不用
+     * `setTimeout` 兜底:那会在没有宏任务概念的宿主上凭空造出一个时钟。
+     */
+    setTimer?(ms: number, fn: () => void): TimerHandle;
+    clearTimer?(handle: TimerHandle): void;
+    /**
+     * 活体增量攒批节拍(T29)。缺席 = `FLUSH_INTERVAL_MS` 默认值。
+     * 🔴 这是**宿主渲染策略**,不是 wire 语义:CC 自己两个端就是两个值(桌面宿主
+     * `makeStreamDeltaCoalescer`=16ms 单帧攒批;我们对标的 CC 2.1.207 CLI 口径=100ms,
+     * 降重绘频率让长回答滚动更稳)。合并**语义**(先思考后文本、段边界重开块)与节拍无关,
+     * 所以节拍下放给宿主、语义留库里。
+     */
+    coalesceIntervalMs?: number;
 }
 /** chrome 平面事件 v1 枚举(cli 现役 UI 面归纳;additive 演进,臂只增不改)。
  *
@@ -24,7 +80,15 @@ export type ChromeEvent = {
     kind: 'retry_status';
     laneProof: LaneProof;
     status: unknown;
-} | {
+}
+/**
+ * footer 面板行事件(载荷 = 本包 `EngineAgentPanelEvent`,B1 已搬入)。
+ * 宿主消费义务:原样 `publishEngineAgentPanelEvent(event)`。
+ * 🔴 **session 常驻台账(`markEnginePanelTaskResident`/`clearEnginePanelTaskResident`)不在宿主义务里**
+ * —— B4 起由适配器**整臂自持**(读者 `isEnginePanelTaskResident` 也在本包,写读同包 = R4 纪律)。
+ * 宿主再写一遍不会更对,只会两臂打架。
+ */
+ | {
     kind: 'panel_task';
     laneProof: LaneProof;
     event: unknown;
@@ -93,10 +157,14 @@ export type ChromeEvent = {
 }
 /**
  * 一条终态 task_notification 抵达(引擎已 server-side steer-inject 过,壳侧只做记账)。
- * 宿主消费义务(cli 现役三件,缺一即回归):
- *  ① drop 壳队列里同 run 的 Path B 条目(workflow_complete/probe feeder),否则 idle
- *     auto-submit 会把同一完成再喂模型一遍(跨进程双投的壳侧半场);
- *  ② 非 background_bash:清 resident 台账(面板行终态由本帧落,不由 turn sweep 假结)。
+ * 宿主消费义务(cli 现役三件里 **B4 起只剩零件**——见下,本臂现在纯属「告知」):
+ *  ① ~~drop 壳队列里同 run 的 Path B 条目~~ → B2 起 `dropQueuedNotificationsForRun` 已在本包,
+ *     B4 起由适配器自己调(宿主只需在启动时 `installNotificationQueuePort`);
+ *  ② ~~清 resident 台账~~ → B4 起由适配器自己调(`clearEnginePanelTaskResident` 在本包)。
+ *  ⇒ 宿主对本臂的义务 = **可选的 UI 提示**(如"后台任务完成"toast)。<br>
+ *  🔴 配对纪律([paired-mechanisms-must-share-premise]):这两件从「宿主义务」改成「库自持」是
+ *     **整臂让位**,不是两边都做——宿主若仍照旧实现,两次 drop/clear 幂等无害,但**记号必须删**,
+ *     否则下一棒会以为库没做。
  * 跨通道去重(「补发通道不得再注入模型一遍」)由**适配器自持台账**负责,不摊给宿主——
  * 见 adapt.ts 的 notifiedRuns / workflow_notification_enqueue 臂的发射门。
  * 注:面板行 end 事件本身走 panel_task 臂、SubagentStop 走 subagent_lifecycle 臂,不重复。
@@ -110,10 +178,14 @@ export type ChromeEvent = {
 }
 /**
  * 子代生命周期 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)。
+ * 宿主消费义务:fire SubagentStart/SubagentStop hooks(observe-only,fail-soft,永不阻塞流)。
+ *
+ * 🔴 **B4 起「一生只许一次」的台账由适配器自持**(实例级 = 一个 session 一份,cli 的 module 级
+ * 等价物):`phase:'start'` 对同一 taskId **本臂只会发一次**,宿主收到就 fire,不必再去重。
+ * `guard:'if-started'` 同理已由适配器解掉——**只有真 fire 过 Start 的 taskId 才会收到带 guard 的
+ * stop**(cli `task_notification` 臂 `firedSubagentStartHookTaskIds.has()` 的等价面)。guard 字段
+ * 保留只为让宿主能识别这条 stop 的来源臂,**不是**要宿主再判一次(判据锚在能决定结果的量上:
+ * 台账在库里,宿主手上根本没有那个量)。
  */
  | {
     kind: 'subagent_lifecycle';
@@ -123,6 +195,44 @@ export type ChromeEvent = {
     agentType?: string;
     guard?: 'if-started';
 }
+/**
+ * B4 新臂 ①(A 层 `task_progress` 搬入)—— **inline 群组行**的累计统计(cli
+ * `engineInlineTaskStats` 的三个写口:`publishEngineInlineTaskTick` / `settleEngineInlineTaskStats`
+ * / `settleAllEngineInlineTaskStats`)。转录里那条 "Running N agents… ├ … 12 tool uses" 的数字面。
+ *
+ * 为什么与 `panel_task` 分臂:两者键不同 —— 本臂按**委派卡 id**(`cardId` = tool_use id,渲染面
+ * 的 AgentProgressLine 只有卡 id 在手),`panel_task` 按 **taskId**(footer 面板行)。同一 tick
+ * 同时喂两面是 cli 现役行为,合臂会逼消费端反解键。
+ *
+ * 宿主消费义务(三个 op 逐一,缺一即回归):
+ *  · `op:'tick'` → `publishEngineInlineTaskTick(cardId, stats)`(已 settle 的卡是 no-op);
+ *  · `op:'settle'` → `settleEngineInlineTaskStats(cardId, isError)`(冻结终值,幂等);
+ *  · `op:'settle_all'` → `settleAllEngineInlineTaskStats()`(turn 末/abort 的防御 sweep 孪生腿)。
+ * 三个函数本包已导出(B1 搬入),宿主直接转发即可,不必自己实现语义。
+ */
+ | {
+    kind: 'inline_task_stats';
+    laneProof: LaneProof;
+    op: 'tick';
+    /** 委派 tool_use id(渲染面订阅键)。 */
+    cardId: string;
+    stats: {
+        toolUses: number;
+        totalTokens: number;
+        durationMs: number;
+        currentAction?: string;
+    };
+} | {
+    kind: 'inline_task_stats';
+    laneProof: LaneProof;
+    op: 'settle';
+    cardId: string;
+    isError: boolean;
+} | {
+    kind: 'inline_task_stats';
+    laneProof: LaneProof;
+    op: 'settle_all';
+}
 /**
  * 带外后台 workflow 完成推送(service 1.75 Path B:引擎**没有** server-side 注入,壳负责喂模型)。
  * 宿主消费义务:把 `message`(模型面 `<task-notification>` 正文,适配器已按 core 同形铸好)
@@ -150,7 +260,64 @@ export type ChromeEvent = {
     toolName: string;
     toolUseId: string;
     input: unknown;
+}
+/**
+ * B3 新臂 ①(T38 三清的第三清 + T57 五处断闸的第五处)—— E12「下一步可问什么」建议**批**。
+ * `suggestions: null` = 作废(turn 开场必发一次:上一轮的建议对新上下文是噪声,挂着不掉会让人
+ * 以为是这一轮的产出);非空数组 = 本轮产出。
+ * 🔴 UNTRUSTED 模型文本(service 已 redact),**仅 UI**:宿主消费义务 = 推给 composer 上方的
+ * chips 面;**绝不回喂模型、绝不落转录、绝不进 /compact 的对话体**。
+ * 子流(parentToolCallId 标)的建议不发本臂 —— 断闸在库里,不摊给宿主。
+ */
+ | {
+    kind: 'prompt_suggestions';
+    laneProof: LaneProof;
+    suggestions: readonly string[] | null;
+}
+/**
+ * B3 新臂 ②(runStream 外向边切除,设计稿 §5.2 第二条边)—— 每个 leader `turn_end` 折叠出的
+ * 真 usage。此前是 runStream 里一条 `void import('lastTurnUsageStore')` 的壳内动态边。
+ * 宿主消费义务:落「最近一次 turn 的真 usage」槽,供 statusline 类消费面在消息面取不到 usage
+ * 时回落(不落 = 插件的 Context 条恒 0%,原病复发)。子流 turn_end **不发本臂**(判据同 §E2:
+ * statusline 显示的是主会话窗口,子代 usage 会把 Context% 打成孩子的窗口占用)。
+ */
+ | {
+    kind: 'last_turn_usage';
+    laneProof: LaneProof;
+    usage: ModelUsage;
+}
+/**
+ * B3 新臂 ③(runStream 外向边切除,设计稿 §5.2 头号污染源)—— `done{status:"needs_review"}` +
+ * gate `plan_review` 的 park 终帧。此前是 runStream 里一条 `await import('planReviewWire')`,
+ * 而 planReviewWire → `utils/debug` → **整棵 1565 文件的 CC 树**进闭包(浏览器可移植性归零)。
+ * 宿主消费义务:弹审批卡(cli 借 AskUserQuestion overlay 合成 question,决断走
+ * `/v1/assistant/tasks/:id/plan_review` resume verb);**fail-soft**——不实现或实现失败都不影响
+ * 紧随其后的终态帧照常投影(用户至少看到 plan fence + 一条普通完成)。
+ * `result` = done 帧的 RAW `result` 载荷(判形与取 taskId 都由宿主做,库不猜)。
+ */
+ | {
+    kind: 'plan_review_park';
+    laneProof: LaneProof;
+    result: unknown;
 };
+/** `ChromeEvent` 的判别键(臂名)—— 覆盖率断言与宿主装配自检都锚在它上。 */
+export type ChromeArmKind = ChromeEvent['kind'];
+/**
+ * chrome 臂**覆盖率断言出口**(§8-1 裁决的一半:client-core 定接口不定实现)。
+ *
+ * 用途:任何宿主(TUI / web / 桌面)在自检里遍历本表,对 `required:true` 的臂断言"我实现了消费口"。
+ * 不实现 = 该 UI 面在那个宿主上是**哑的**(不是报错,是静默没有)—— 这正是多端最容易漏的一类,
+ * 所以把义务做成**数据**而不是散落在注释里。
+ *
+ * `required` 判据:**不实现会让已发生的行为丢失**(转录/模型输入/hook/去重)⇒ true;
+ * 只影响可选装饰(spinner 计量、活体预览、chips)⇒ false。
+ * `duty` = 一句话义务(完整义务在上方每臂的注释里,那里是真源)。
+ */
+export declare const CHROME_ARMS: readonly {
+    kind: ChromeArmKind;
+    required: boolean;
+    duty: string;
+}[];
 /** 车道纪律一等公民([1617] 家族固化):chrome 事件构造必须携判别证明。 */
 export type LaneProof = {
     lane: 'main';

package/dist/seam.js

@@ -1,3 +1,33 @@
+/**
+ * chrome 臂**覆盖率断言出口**(§8-1 裁决的一半:client-core 定接口不定实现)。
+ *
+ * 用途:任何宿主(TUI / web / 桌面)在自检里遍历本表,对 `required:true` 的臂断言"我实现了消费口"。
+ * 不实现 = 该 UI 面在那个宿主上是**哑的**(不是报错,是静默没有)—— 这正是多端最容易漏的一类,
+ * 所以把义务做成**数据**而不是散落在注释里。
+ *
+ * `required` 判据:**不实现会让已发生的行为丢失**(转录/模型输入/hook/去重)⇒ true;
+ * 只影响可选装饰(spinner 计量、活体预览、chips)⇒ false。
+ * `duty` = 一句话义务(完整义务在上方每臂的注释里,那里是真源)。
+ */
+export const CHROME_ARMS = [
+    { kind: 'retry_status', required: false, duty: '渲/清 spinner 的重试覆盖层' },
+    { kind: 'panel_task', required: true, duty: 'publishEngineAgentPanelEvent(event) 原样转发' },
+    { kind: 'bgshell_settle', required: true, duty: '后台 shell 面板行落终态(含 outputPath)' },
+    { kind: 'tasks_expand', required: false, duty: '展开 ctrl+t 任务面板' },
+    { kind: 'thinking_activity', required: false, duty: '开/收活体 "∴ Thinking…" 行' },
+    { kind: 'request_start', required: false, duty: 'spinner 置 requesting 态' },
+    { kind: 'stream_delta', required: false, duty: '渲活体预览 + 推进 responseLength' },
+    { kind: 'response_metrics', required: false, duty: '驱动 responseLength reducer(ttft/对账)' },
+    { kind: 'attachment', required: false, duty: '渲 attachment 行(必须带 default 臂)' },
+    { kind: 'notification_terminal', required: false, duty: '可选 UI 提示(记账已由库自持)' },
+    { kind: 'subagent_lifecycle', required: true, duty: 'fire SubagentStart/Stop hooks(去重已由库解)' },
+    { kind: 'workflow_notification_enqueue', required: true, duty: 'message 入完成通知队列,idle 时喂模型' },
+    { kind: 'task_ledger_sync', required: true, duty: '按 toolUseId 幂等落 TaskCreate/TaskUpdate' },
+    { kind: 'inline_task_stats', required: true, duty: 'tick/settle/settle_all 转发给 engineInlineTaskStats' },
+    { kind: 'prompt_suggestions', required: false, duty: '推 composer 上方 chips(绝不回喂模型)' },
+    { kind: 'last_turn_usage', required: true, duty: '落最近一次 turn 真 usage(statusline 回落源)' },
+    { kind: 'plan_review_park', required: true, duty: '弹 plan 审批卡(fail-soft,不挡后续终态帧)' },
+];
 /**
  * transcript id 确定性派生([1653] 定案):稳定键优先序 = 帧 id > seq > toolCallId;
  * 全缺才用 ctx.uuid()。同流重放 ⇒ 同 id 序列(往返守卫钉此不变量)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node scripts/run-client-core-pure-test.mjs && node scripts/run-client-core-diff-test.mjs"
+    "test": "node scripts/run-client-core-pure-test.mjs && node scripts/run-client-core-portability-test.mjs && node scripts/run-client-core-diff-test.mjs"
   },
   "dependencies": {},
   "peerDependencies": {