@sema-agent/client-core 0.68.0 → 0.68.1

package/docs/INTEGRATION-CLIENTS.md

@@ -19,7 +19,7 @@
 
 | 项 | 值 | 真源 |
 |---|---|---|
-| 本包 | `@sema-agent/client-core` **0.68.0**(本批发布版 = 🔴 **BREAKING** minor:内容批 4e98884(车 S),core 7.16.0 → **7.17.1** 提货:`turn_end.usage` 缺席臂退役(违约响亮留痕 + 整帧不投影 + 下界位,占位零判据贯穿五处)/ 终态词两表分源 `TERMINAL_CAUSE_KINDS` + `RUN_TERMINAL_STATUSES`(旧名无别名删)/ `ask_unresolvable.cause`、`durable_gate_unavailable.source` 读器 / `readWorkflowParks` 三键 + park 四拒码 / `heldBy`·`cancelRequested` 三态 / L-244·L-245·L-246 包侧半场;引擎地板 core ≥7.17.0;详见 §33(母本 §33z 逐键处置表);`CHANGELOG.md` `## 0.68.0(2026-09-13)`;0.67.2 patch = 上一版)| `package.json` `version` |
+| 本包 | `@sema-agent/client-core` **0.68.1**(本批发布版 = patch,additive 零 BREAKING 型面:内容批 3253313(车 CC-A),L-310 `text_end` 权威段替换——`text_segment_end` 从纯信号变成「信号 + 权威内容 + 分歧位」(`diverged` / `committedPrefixDiverged` / `committedPrefixLen` 三键 never-false;`CHROME_ARM_TABLE` 本臂 `required` 翻 true)/ L-290 `ToolRosterEntryView` 出身三键 / [7226] 包侧缺口 ① `ControlSafetyCode` 加员 `blocked_by_hook` ⑤ `memoryCapture` 单成员闭集响亮拒;§34 / 34e 三端升级必读四条)|
 | peer:wire 契约 | `@sema-agent/sdk` **>=8.4.0**(value-level,非 type-only;**0.60.0 抬版**,四条硬理由见 §24a 与 `scripts/run-sdk-floor-test.mjs` 的 `FLOOR` 注;上一次是 0.59.0 的 `>=8.3.0`)。🔴 支持窗同批收到 **engine ≥7.64.0**:sdk 8.4.0 与 7.63.0 及以前的 wire **不同窗** | `package.json` `peerDependencies` |
 | peer:会话词汇表 | `@sema-agent/agent-types` **>=0.2.0**(type-only,零运行时) | 同上 |
 | runtime dep | `diff` ^9.0.0(**唯一**一条;portability 门按**等值**钉死) | `package.json` `dependencies` |
@@ -7342,3 +7342,269 @@ off 车道的 Bash ask 上它现在**恒在场**(`true`),而 classify 车道的
 | 9 | S-8 其余七件(`skillCommandsToSpecs` 候选面 / `classifierStreakOf` 连败面 / `fetchDelegatedPrompt` 在飞记号 / `registerOutstandingBgTask` 订阅事件 / 交互 run steer 座 / `pathNotInRootRow` 措辞铸点) | **declined**(本批不做,逐条理由) | 它们都是**新能力面**(新公面 + 新行为 + 各自的门三件),而本批已经带着三件 🔴 BREAKING 与一次引擎地板抬升 —— 把新能力与 BREAKING 混在一版,端的换装清单会分不出「必须改」与「可以接」。🔴 另有两件带**上游前提**:`classifierStreakOf` 的到货形依赖 core #742(7.18.0 才有 `GateDisposition.classifier` 三键与 `auto.classifier_fallback` 通告码,见 L-260),现在铸会铸出一个上游还没定形的读法;`registerOutstandingBgTask` 发订阅事件牵动通知链的时序(本包最容易出跨流串账的一族)。⇒ 整体**改期**,与下一批非 BREAKING 的内容批同发 |
 
 ---
+
+## §34 🆕 0.68.1 内容批(L-310 `text_end` 权威段替换 / L-290 `contentOriginProvenance` / 包侧缺口 ①⑤)
+
+### 34a. 本节速览
+
+| 件 | 一句话 | 端要做什么 |
+|---|---|---|
+| S-1 🔴 **安全面** | **`text_end.content` 是经脱敏器的段权威全文,而 `text_delta` 仍逐字** ⇒ 两者**可以不相等**(server ≥7.75.3)。本包此前只把它当段界信号、**不动文本缓冲**,于是屏上的活体流与 transcript 平面的 committed 消息用的都是 delta 拼文 —— 一段引用了凭据的回答以**未脱敏**字节留在本地转录里。改口后:臂**整段替换**段缓冲与活体尾巴,并把三个 never-false 键交给宿主;`CHROME_ARM_TABLE` 上本臂的 `required` 同批 `false` → **`true`** | **自己拼 delta 上屏**的端(desktop / web 若各自缝合 `stream_delta`)必须消费 `diverged` 做替换;🔴 `committedPrefixDiverged` 那一条**所有端都要做**(包在那一形上交不出东西)。只渲 transcript 平面的端在该键缺席时**自动正确** |
+| S-2 | `ToolRosterEntryView` 补**出身三键** `contentOriginProvenance` / `effectProvenance` / `egressProvenance`(L-290 + 同形族扫;开集读,缺席即缺席) | additive;诊断行(壳 `/doctor`「Tools (engine leg)」)按需渲。**不进** `ToolShim`(渲染面 vs 诊断面分家) |
+| S-3 | `ControlSafetyCode` 补**第 8 码** `blocked_by_hook`(`steering.blocked_by_hook`,422,部署 `userPromptSubmit` 门拦下) | 🔴 端上按 `ControlSafetyCode` 做**穷举 switch** 的地方要加一臂(`default` 臂必须在);处置 = 「输入**未被受理**,改内容自由重试」,与 `invalid_content` / `steering_other` 都不同 |
+| S-4 | `REQUEST_FIELD_MATRIX` 补 `memoryCapture` 行 + `TaskRequestInput.memoryCapture?: 'off'` + 构造器 stamp(单成员闭集)+ 🔴 坏值**响亮拒** | 有「本会话不再记忆」入口的端把值交给唯一构造口,别再自建白名单绕 `unregisteredRequestKeys`;🔴 端上若曾把用户输入直接透给这一位,现在**打错字会抛**(这是设计:静默删键会让 opt-out 无声丢失) |
+
+**共同形**:这一批的三件都是**「上游已经把事实放上 wire,而本包的某一层把它读丢了」**。
+S-1 丢的是**字节**(拿 delta 拼文当权威全文),S-2 丢的是**键**(逐键窄读器没挑),
+S-3/S-4 丢的是**表行**(码表与字段矩阵各缺一行)。三者的共同处置也只有一条:
+**把「读丢」变成当天会红的机器判据** —— S-1 的四形格、S-2 的逐键处置台账(对**实装 core 的 schema**)、
+S-3/S-4 的表行负控。没有这三本账,「挑漏一个键 / 少认一个码 = 那件事在包边界上不存在」会一直无声发生。
+
+**出处**:server 的 `ASSISTANT-WIRE-CONTRACT.md` §5.1 live 面(7.75.3 脱敏面收口)、(2) `steering.*` 码表第 8 行、
+§12.4 提交面 `memoryCapture`;core 的 `core/tool-roster.ts:114`(`contentOriginProvenance` 四词)+
+server 的 `trace/project.ts` 的 `tools` 段(整只判形 + **逐字透传**);comms [7226] 包侧缺口 ①⑤。
+
+**🔴 逐键处置表见 §34z。**
+
+---
+
+### 34b. S-1 🔴 `text_end` 权威段替换(L-310;安全面)
+
+**上游的形变**(server `ASSISTANT-WIRE-CONTRACT` §5.1「live 面(7.75.3 起)」逐字):
+
+> `POST /v1/tasks/stream` / 转发子代腿 / 子代 tail 面上的 `text_end.content`(段权威全文)与上面三面走**同一只**
+> 脱敏器;`text_delta` 仍逐字(跨 chunk 的凭据无法就地判,流式脱敏是独立设计件)——⇒ 消费端在 `text_end`
+> 到达时应以它**整段替换**已攒的 delta,而不是只当段界信号。
+
+⇒ 「`content` 与增量拼接逐字节相等」这句(core 臂注的半句,本包 `seam.ts` 义务① 与
+`eventToSdkMessage.ts` 臂注都照抄过)**自 7.75.3 起不再成立**。按它「别拿它再渲一行」= 屏上与
+转录里留的是**未脱敏**那一份。
+
+**本包的处置**(`src/adapt/textStream.ts` 的 `replaceAnswerSegment` + `src/adapt/arms.ts` 的 `textSegmentEndArm`):
+
+| 修前 | 修后 | 为什么 |
+|---|---|---|
+| 臂只投 chrome 信号,头注自陈「本批**不动**文本缓冲」 | 臂调 `replaceAnswerSegment(content, frame)` **整段替换**,再发信号 | 不动缓冲 = `emitAnswerSegment` 铸出来的 committed assistant 消息是 delta 拼文 = 未脱敏字节进本地转录 |
+| `textSegmentEndArm: ProjectionArmFn`(零适配器状态) | `ArmFn`(吃 `{ text }`) | 封闭性声明就是签名:要碰状态就得改签名,改签名在 diff 里显形(`arms.ts` 头注的两级 deps 纪律) |
+| 事件只有 `content` / `eventId` | +`diverged` / `committedPrefixDiverged` / `committedPrefixLen`,**全部 never-false** | 缺席 = 否定(与 `_sema_usage_absent` 同律);铸 `false`/`0` 会把「这一段没分歧」与「这台引擎不报分歧」折成同一个字节 |
+| 替换**在**发事件之前 | — | 反过来会留一拍窗口:宿主按信号去读转录面,读到的还是旧拼文 |
+
+**🔴 替换语义 —— 六形逐形处置**(每一形都是判断,不是顺手;判据锚在**真正决定结果的量**上):
+
+> ⚠️ 下面 (c)(e) 两形是**异源对抗复审当场实抓**的真病(两条都对着装机 core 的真字节复现),
+> 不是理论边界 —— 它们的处置与第一版设计**不同**,读的时候别按第一版的直觉推。
+
+| 形 | 发生条件 | 处置 | 判据锚 |
+|---|---|---|---|
+| (a) 常态 | `text_end` 先于段提交,整段还押在缓冲里 | 段缓冲整段换成 `content`(**封存**),下一次段提交铸出来的 committed 文本**就是**权威全文 | 已提交前缀长度 = 0 |
+| (b1) 半段已 flush,前缀仍对得上 | idle-flush 提交过半段,且 `content.startsWith(<已提交前缀>)` | 只封存**未提交尾段**(`content` 去掉前缀那一截);两条 committed 拼起来**逐字节** = `content`,宿主什么都不用丢 | 🔴 `content.startsWith(<已提交前缀>)` —— **不是**「有没有 idle-flush 过」(那是前置条件,不是决定结果的量) |
+| (b2) 半段已 flush,**前缀自己也过期** | 凭据落在已经上屏的那半段里 ⇒ `content` 不以已提交前缀开头 | 🔴 **一个字节都不再交**给转录面,并立 `committedPrefixDiverged` ⇒ 该段唯一算数的那一份就是帧上的 `content`,宿主把 `committedPrefixLen` 指的那一截换成它;**整截都在当前这条消息里时同批同步终答补差账**(否则 `result` 臂会把权威全文当成「屏上缺的后缀」再渲一遍,轮三 finding② 实抓;跨消息那几形**刻意不碰账**,轮四 finding①② 收窄,理由与留白见下)。**包内撤不回**:那条 transcript 消息早已 yield,只有宿主持有句柄 —— 包能做的是**把这件事说出来**;再补一条 = 同一段话上屏两遍 | 同上(判据同一个,结论相反) |
+| (c) 🔴 一 turn 多段 | 第二个 `text_end`(**anthropic 车道常态**:装机 core `brain/anthropic.js` 在 `content_block_stop` 上逐块 push) | 定稿正文**封存**、段缓冲**清空**给下一段用。⚠️ 不清空 ⇒ 第二段的 delta 接着往同一个缓冲里加、再被第二帧的 `content` 整段覆盖 ⇒ **第一段正文凭空消失**,且第二帧还会误报 `diverged`(复审实抓)。封存**不切消息**:整 turn 仍只提交一条 assistant 文本消息 | 「引擎说这一段写完了」⇒ 它的字节此后只能被整体提交,不能再被下一段追加/覆盖 |
+| (d) 子流 | `parentToolCallId` 在场 | **根本到不了替换**:臂在断闸处 `return`(零 chrome 事件 + leader 缓冲一字节不动)。顺序不许倒过来 | 断闸按「**键在不在**」判,不按「是不是串」判(既有纪律) |
+| (e) 🔴 **迟到的段边界** | 工具卡先到、`text_end` 后到(**openai 车道实测时序**:装机 core `brain/openai.js` 在 `finalize()` 里 push `text_end`,而 `toolcall_end` 先触发 `engine/loop/agent-loop.js` 的 `executor.maybeAdmit`)。**卡之后同段还可以继续出 delta**(brain 持续累加文本到 `finalize`) | 🔴 **两本前缀账相加**:包侧边界带走的那些截 + 本消息内 idle-flush 掉的,合起来才是「这一段已经撤不回的部分」。⇒ 照算分歧、照发三个键;前缀对得上就只交**尾段**,对不上就**一个字节都不交**。⚠️ 修前踩了两次:轮一按「两个缓冲都空 = 没经手过」全否返回 ⇒ 未脱敏正文静留转录、三键一个不发;轮二订正后仍「只在当前缓冲全空时才读上一本账」⇒ 卡后一有 delta 前缀就不算了,旧明文留存**而且**权威全文被完整提交第二次(同一段上屏两遍)。两条都实测复现过 | 包侧边界(工具卡 / 消息划界)**不是**引擎段边界 —— 只有 `text_end` 是;而「当前缓冲空不空」**不是**「本包经没经手这一段」 |
+| (f) 🔴 本包零经手 | 两本前缀账 **∧** 段缓冲全空 | **什么都不做**,三位全报否 | 替换的语义是「换掉本包自己缝合出来的那一段」,不是「凭空铸一段」。可达形两条:① durable 内容腿(整块 `text` 帧本身就是一整条 assistant 消息、已铸过 transcript 行)之后到的 `text_end`;② 宿主只喂 `text_end` 的自建管线。塞进缓冲 ⇒ turn 收口**再铸一条一模一样的**。**红先绿后实抓**:pure 门既有正控 `#323-g`(「本臂不铸 transcript 行」)当场红 |
+
+**活体面(`stream_delta`)怎么算**:已经泄出去的那一截**撤不回**。所以 ——
+已泄前缀仍是 `content` 的前缀 ⇒ 尾巴换成 `content` 剩下那一截(屏上接着往下写,零重复);
+已泄前缀**不是** `content` 的前缀 ⇒ **不再补任何尾巴**(在一段错的前缀后面接上权威后缀,拼出来的是
+一段谁都没说过的话),由宿主按 `diverged` 重渲整段。
+
+**🔴 最小键集为什么恰是三个**(「宿主能不能只凭一帧就知道要不要重渲」):
+
+- `diverged`(never false)= **活体面**那份过期了 ⇒ 要不要重渲;
+- `committedPrefixDiverged`(never false)= **转录面**已经 committed 的那一截也过期了。它是真正的分水岭:
+  缺席时包随后交的是**尾段**(前缀 + 尾段 = `content`,什么都不用丢);在场时包**一个字节都不再交**
+  ⇒ 该段唯一算数的那一份就是帧上的 `content`,宿主必须用它重渲并**丢掉**此前那些消息。
+  **两形的 `diverged` 与 `committedPrefixLen` 完全同形,而宿主动作正相反** —— 合成一个位办不到。
+  🔴 `diverged` 那一条只有**自己拼 delta 上屏**的宿主要做;`committedPrefixDiverged` 那一条
+  **所有宿主都要做**(包在那一形上交不出东西,只有宿主能修)——`CHROME_ARM_TABLE` 上本臂的
+  `required` 因此从 `false` 翻成 **`true`**;
+- `committedPrefixLen`(never 0)= **定位量**。宿主照抄这一行就对:
+  `已committed正文.slice(0, 已committed正文.length - committedPrefixLen) + content`。
+  🔴 **单位 = JS 字符串长度(UTF-16 代码单元),不是 UTF-8 字节**(轮三 finding① 订正:按字节截会在
+  任何非 ASCII 正文上截错位置 —— 实测 `sk-…` + `中文`×30 的 UTF-16 长度 82 / UTF-8 字节 202,
+  按 202 截会把凭据**原样留在屏上**还附带乱码)。
+  🔴 **也不是「几条消息」**(轮二 finding② 订正):本包在 idle-flush 那一形下会把「上一段的定稿 +
+  这一段的半截」合并进**同一条** assistant 消息(分段行为零改动的代价),按**消息**去丢会把已经
+  定稿的上一段一起删掉,而本包**不会再补发**它。
+  🔴 它按**增量拼文**计长,**不是** `content` 上的偏移量(前缀自己也可能被脱敏改过字节,拿它去切
+  `content` 在 b2 那一形上会切出半截乱码)。
+  🔴 **一条总不变量**(三轮复审逼出来的那句话,也是本件最该记住的边界):
+  **本包只在「整段都在自己手里(同一条 committed 消息内)」时改自己交的字节;段一旦跨过包侧边界
+  (工具卡 / 消息划界),就只发这三个键、不动任何既有行为** —— 转录逐条、终帧补差走向都与
+  **0.68.0 逐字相同**(常驻门按「补差臂走向」这个真正决定结果的量做基线对照)。
+  轮五实测的反例正是踩了这条:在跨消息那一形清掉未提交尾段,会让 `result` 从第⑤臂(只报一行分岔)
+  改成第④臂(**补吐一整段**)—— 那是**新增**的重复转录路径,不是「更安全」。
+
+  ⚠️ **随之而来的如实留白**:跨消息那几形里,`committedPrefixLen` 指的那一截可能落在**别条**消息里、
+  甚至中间**夹着一张工具卡**;而终帧补差的基线也不会跟着换(它本来就不跟,与本批无关 —— 主树
+  0.68.0 上同一条时序**实测同形**)。根因是同一个:**包按自己的边界切 committed 消息,引擎按
+  content block 切段**。根治 = 「每个引擎段各自一条 committed 消息」(= CC 在 `content_block_stop`
+  上的原生做法,`seam.ts` 本臂头注早已点名),那是**分段行为改动**、与撤 idle-flush 启发式同一件事,
+  按宪法三问单独走;本批不做,把边界如实写在这里而不是假装没有。
+
+📋 **刻意没有第四个键 `authoritative: true`**:它会在**每一帧**上恒为真 ⇒ 零判别力,既分不出新旧引擎
+(引擎版本不在帧上,本包不猜版本 —— 与 §33b 那条「刻意不留按引擎版本分岔的兼容读」同一条纪律),
+也不驱动宿主的任何分支。
+
+📋 **仍然留白的那一件**:让 `textStream` 真的**撤掉** idle-flush 启发式。core 臂注明写 `text_end` 是
+「诚实缺席」的位(只有会报块结束的 brain 才发它),所以要撤得先按**每条流**判「这条流带不带边界帧」
+再决定退不退启发式 —— 带状态的行为面改动,按宪法三问单独走。权威替换是**兼容**启发式的
+(b1/b2 两形由两个前缀键如实交代),**不是**它的继任。
+
+### 34c. S-2 `ToolRosterEntryView` 出身三键(L-290 + 同形族扫)
+
+**病形**:server(`trace/project.ts` 的 `tools` 段)对名册的姿势是**整只判形 + 逐字透传**,理由逐字
+「成员表由 core 以 typebox schema 单点持有,手抄一张挑键表 = 立刻多一份会漂的镜像」;而本包
+`src/toolRoster.ts` 是**逐键窄读器** —— 挑漏的键在包边界上**等于不存在**。`contentOriginProvenance`
+就是这么漏的(壳 `/doctor`「Tools (engine leg)」行读不到)。
+
+**🔴 族扫(同形存量清剿宪法的两问)**:病形 = 「逐键窄读器对上游已透传的键静默无感」;
+同形存量 = core `ToolRosterEntry` 32 个成员里本包此前只挑 17 个,**15 个没挑**。
+处置不是只补被点名的那一个:
+
+- **点杀 + 同族三键**:三根轴(`contentOrigin` / `effect` / `egress`)**各有一个出身键**,漏的形一模一样
+  ⇒ 三个一起挑(`contentOriginProvenance` / `effectProvenance` / `egressProvenance`,开集读、缺席即缺席、
+  坏形只丢这一格不丢行)。
+- **族扫落成机器账**:`scripts/run-tool-roster-projection-test.mjs` **G 段**拿**实装 `@sema-agent/core` 的
+  schema 成员表**与窄读器**真挑出来的键集**逐键对账 —— core 有而账上没有 ⇒ 红;账上标「挑」而没挑 ⇒ 红;
+  账上标「不挑」却挑了 ⇒ 红;每条「不挑」都写理由。**上游再加成员当天红**,这才是根治。
+- **12 条 declined 的理由**(逐条在门里,摘要):`inputKeys`(schema 概要 ≠ 本次调用的真实入参)/
+  `offload`·`offloadThresholdChars`·`compactable`·`budgetExempt`·`validateInput`·`deferred`·`alwaysLoad`
+  (引擎执行面与挂载策略,端边界上无对应动作)/ `reversibilityProbe`·`approvalPreview`(探针/预览在场与否
+  不是卡上那根轴的值)/ `modelGate`(本包**已有**专门读面 `wiring_manifest.modelGate`,再挑一次 = 两份会漂)/
+  `mountedBy`(部署侧分诊量,端的诊断行读的是 `source`)。
+
+⚠️ 出身键是**诊断面**,刻意**不进** `ToolShim`(那是渲染面:人话名 / 卡型 / 三根轴的**值**)——
+端渲一只工具时要的是「它是什么」,不是「这句话是谁说的」。
+
+### 34d. S-3 / S-4 包侧缺口 ①⑤([7226])
+
+**① `controlRouter` steering 码表第 8 码**(`src/controlRouter.ts` 的 `STEERING_CODE_TO_SAFETY` / `STEERING_ADVICE`):
+`steering.blocked_by_hook`(422)—— 部署的 `userPromptSubmit` 门拦下了这条输入,block / 超时 / 崩溃**同码
+fail-closed**,成因由 message 判别。🔴 **输入未被受理**(无 `human_input` 帧、`inputId` 不入账)⇒ 处置 =
+**改内容自由重试**。修前它落开集兜底位 `steering_other`,而那一位的判词逐字是「别按成员猜它的意思」——
+兜底在这一位上不是安全降级,是把一条**能自救**的拒绝渲成一条不知道怎么办的拒绝。
+⚠️ SDK 8.8.0 **没有**专属子类(`errors.d.ts` 的 `Steering*Error` 只有六只)⇒ 只能按 `errorCode` 认;
+`/steer` 的 **park 腿结构性不可达本码**(hook 对 parked 转向的拦截发生在 resume 再投递时刻,走
+`steering.parked_input_blocked` 通告),本路由器调的是 live 腿,所以这一位在这里可达。
+
+**⑤ `REQUEST_FIELD_MATRIX` 的 `memoryCapture` 行**(`src/request/taskRequest.ts`):server §12.4 的提交面
+body 键 `memoryCapture?: "off"` —— **单成员闭集,没有 `"on"`**。修前整条不在矩阵里 ⇒ 端把它放进请求体时
+`unregisteredRequestKeys` 当场点名,唯一「合规」出路是端自己加白名单(`attachmentIds` 已经走过这条弯路)。
+本批同批补齐三件(只补表不补构造器 = 端还得在唯一构造口外面手加一行):表行 + `TaskRequestInput.memoryCapture?: 'off'`
++ 构造器 `=== 'off'` 才 stamp。🔴 与**中途翻转 verb**(`POST /v1/runs/:id/memory/capture-optout`,能力位
+`runMemoryCaptureOptOut`)是**同一条一次性单向记录的两个口**,不是两个轴:verb 管这一条在飞的 run,
+本键管「本会话的下一次新提交」;verb 的非 live 409 `steering.not_running` 正是**指路本键**,端没有本键
+就接不住那条指路。
+
+---
+
+### 34e. 🔴 三端升级必读(固定段式,[C295];本批**四条**)
+
+1. 🔴 **安全面:`text_segment_end` 从「纯信号」变成「信号 + 权威内容 + 分歧位」**(`ChromeEvent` 的
+   `TextSegmentEndChromeEvent`,三个 additive 键全部 never-false;`CHROME_ARM_TABLE` 上本臂的
+   `required` 同批 `false` → **`true`** —— 按本表自检覆盖率的端会当场显形,那正是目的)。
+   · `diverged` 在场 ⇒ **自己拼 `stream_delta` 上屏**的端必须用 `content` **重渲该段**并以它为该段的
+     committed 文本,**不许保留增量拼文**(不实现 = 未脱敏字节留在那个宿主的屏上与转录里);
+     只渲 transcript 平面的端在这一条上零改动(包已经把权威全文换进段缓冲)。
+   · 🔴 `committedPrefixDiverged` 在场 ⇒ **所有端都要做**:这一段此前已 committed 的正文是过期的,
+     把 `committedPrefixLen` 指的那一截换成 `content` —— 包在这一形上**一个字节都不再交**
+     (撤不回的那截拼不出 `content`,再补一条 = 同一段话上屏两遍),不做就只剩未脱敏的那半截、
+     还缺后半段。
+   · `committedPrefixLen` 是定位量,照抄
+     `已committed正文.slice(0, 已committed正文.length - committedPrefixLen) + content`。
+     🔴 **单位 = JS 字符串长度(UTF-16 代码单元)**:**不是 UTF-8 字节**(按字节截会在非 ASCII 正文上
+     把凭据原样留在屏上)、**也不是「几条消息」**(包会把上一段的定稿与这一段的半截合并进同一条
+     消息,按消息丢会把上一段一起删掉,而包**不会再补发**它)。按**增量拼文**计长,不是 `content`
+     上的偏移。
+   · ⚠️ **迟到的段边界**(引擎在工具执行之后才报这一段的边界 —— openai 车道的实测时序)同样带着
+     这三个键到达,而它指的可能是**上一条** assistant 消息。按同一条规矩处置,别因为「这一段看起来
+     早就结束了」就跳过。
+2. 🔴 **`ControlSafetyCode` 加员 `blocked_by_hook`** —— 端上按这个联合做**穷举 switch / 映射表**的地方
+   会**编译期红**(没有 `default` 臂的话),这是设计:处置与 `invalid_content`(正文违规,SURFACE 别
+   strip-and-retry)和 `steering_other`(别猜它的意思)**都不同**,塌进任何一位 UI 都会说反话。
+   正确文案口径 = 「这条输入**没有被受理**(部署的提交门拦下了),改一改内容再发即可,不是重复提交」。
+3. 🔴 **`memoryCapture` 坏值现在会抛**:`buildTaskRequest` 对 `'on'`/`'OFF'`/空串/布尔/对象等一切
+   表外写法**抛 `TypeError`**(两条车道、不受 live 门)。端上若曾把用户输入直接透给这一位,打错字
+   从此是**响亮失败**而不是静默继续采集 —— 这是设计(core/server 都点名「把一条隐私请求按打字
+   错误静默丢掉是禁的方向」)。`undefined`/`null` 仍是合法缺席。
+4. **两件 additive,可接可不接**:`ToolRosterEntryView` 的出身三键
+   `contentOriginProvenance`/`effectProvenance`/`egressProvenance`(开集读,🔴 缺席 ≠ `"default"` ——
+   缺席是「这台引擎没报」,`default` 是「报了,谁都没声明」;两者别折成一个字节);
+   `TaskRequestInput.memoryCapture?: 'off'`(单成员闭集,`'on'` 与坏拼写一律不上 wire)。
+
+**包侧缺口:** 无(本批 [7226] ①⑤ 两条已清;其余条目不在本包边界上,见 §34z ③)。
+
+### 34f. 黑盒判据(test 视角;wire 可观察,不引用内部实现)
+
+> 新增一列「web 可复用构造形」(0.68.0 打分扣点采纳,[C295]):同一条判据在 web/desktop 端怎么构造。
+
+| # | 判据 | 期望 | web 可复用构造形 |
+|---|---|---|---|
+| G34-00 | 🔴 `CHROME_ARMS` 里 `text_segment_end` 那一行 | `required === true`(0.68.1 从 `false` 翻面);`duty` 文案点名三个键 | 读公面导出 `CHROME_ARMS` |
+| G34-01 | 一条 run:`text_delta` 逐字流出含凭据形的文本,随后 `text_end.content` 为脱敏后的同一段 | 最终转录里那条 assistant 消息的正文 = `text_end.content` **逐字节**;未脱敏字节**零命中** | 假 wire:两条 `text_delta` + 一条 `text_end`,断言 `transcript` 平面 assistant 文本 |
+| G34-02 | 同上,但 `text_end.content` 与拼文**逐字节相同**(不含凭据形的常态) | chrome `text_segment_end` 上 `diverged` / `committedPrefixDiverged` / `committedPrefixLen` **三键全缺席**;转录正文不变 | 同上,`text_end.content` 用拼文原串 |
+| G34-03 | 段中途触发 idle-flush(静默 ≥1.5s + 段尾句末)提交半段,随后 `text_end` 的权威全文**只改了尾段** | `committedPrefixLen` = 已提交字节数、`diverged` 在场、`committedPrefixDiverged` **缺席**;两条 committed 消息拼起来 = `content` | 需要宿主时钟口(`setTimer`);或直接对 `text_segment_end` 事件断言三键组合 |
+| G34-04 | 同 G34-03,但凭据落在**已提交的半段**里(权威全文的前缀也变了) | 🔴 `committedPrefixDiverged` **在场**,且包**不再为这一段提交任何正文**(实测:随后没有新的 assistant 文本消息)—— 该段唯一算数的那一份是事件上的 `content`,宿主把 `committedPrefixLen` 指的**字节区间**换成它 | 同上,`text_end.content` 把前缀那一截也换掉;断言**最终转录**,不要只查三个键在不在 |
+| G34-04b | 🔴 `A → text_end(A) → B前缀(含凭据) → idle-flush → B尾 → text_end(B)` | `committedPrefixLen` 只统计 **B** 那一截;把已 committed 正文**尾部**这么多字节换成 `content(B)`,得到「A 的定稿 + B 的权威全文」。⚠️ 按**消息**丢会把 A 一起删掉(包把两段合并进了同一条消息,且不会再补发 A) | 需要宿主时钟口;或直接对回执/事件的 `committedPrefixLen` 与最终转录做字节级重建 |
+| G34-05 | 🔴 一个 turn 里两条 `text_end`(两段),**中间没有工具卡也没有 idle 提交** | 两段的正文**都**到得了最终转录(拼成一条 assistant 消息);第二帧的 `diverged` 只按第二段自己算、`committedPrefixLen` 缺席 | 两组 delta + 两条 `text_end` 直接喂 `adapt()`,**不要**手动插段提交(手插会把病整个掩盖) |
+| G34-05b | 🔴 delta(含凭据) → tool_start(工具卡) → **迟到的** `text_end`(脱敏后全文) | `diverged` + `committedPrefixDiverged` + `committedPrefixLen` 三键**都在场**(字节区间落在**卡之前**那条消息上);包**不铸**新的 assistant 消息 | 三帧直接喂 `adapt()`;openai 车道的真实时序 |
+| G34-05c | 🔴 delta(含凭据) → tool_start → **同段后续 delta** → 迟到的 `text_end` | 卡前那截明文**算进** `committedPrefixLen`;`committedPrefixDiverged` 在场;权威全文**不被完整提交第二次**(否则同一段上屏两遍 + 明文没人清) | 四帧喂 `adapt()`;brain 持续累加文本到 `finalize`,streamingToolExecution 允许这条交错 |
+| G34-05d | 同 G34-05c,但正文里**没有**凭据形 | 前缀对得上 ⇒ 只交**尾段**,两条拼起来 = 权威全文(反向自证:不是「一律不交」) | 同上 |
+| G34-06 | `text_end` 带 `parentToolCallId`(子代/编排流) | leader 面**零** `text_segment_end` 事件;leader 段缓冲一字节不动(收口铸出来的正文仍是 leader 自己的 delta 拼文) | 先喂 leader delta,再喂带 `parentToolCallId` 的 `text_end`,断言两件 |
+| G34-07 | 🔴 只喂 `text_end`、**零** `text_delta`(或 durable 整块 `text` 帧之后再来 `text_end`) | **不铸第二条** assistant 消息(同一段文字绝不上屏两遍) | 单帧 `text_end`;以及 `text`(durable)+ `text_end` 两帧 |
+| G34-08 | 名册行带 `contentOriginProvenance` / `effectProvenance` / `egressProvenance` | 三键逐字出现在 `projectToolRoster(...).entries[i]` 上;整键缺席 ⇒ 视图上整键不在场(不铸 `"default"`) | `wiring_manifest.tools` 假载荷 |
+| G34-09 | 名册行的出身键是坏形(空串 / 数字 / `null` / 对象) | 只丢那一格,**行还在**(名册不整只判没) | 同上,逐形喂 |
+| G34-10 | `/steer` 被部署的 `userPromptSubmit` 门拒(422 `steering.blocked_by_hook`) | 抛 `ControlSafetyError`,`code === 'blocked_by_hook'`;判词含 wire 码原文与「未受理 / 可重试」口径 | 假 `runs.steer` 抛 `{ errorCode:'steering.blocked_by_hook', status:422 }` |
+| G34-11 | 同上,未来未知码 `steering.<new>` | 仍落 `steering_other`(开集兜底没有被本批收窄) | 同上换码 |
+| G34-04c | 🔴 前缀含 **CJK / emoji**(非 ASCII)时的宿主重建 | 按 `已committed正文.slice(0, 长度 - committedPrefixLen) + content`(**UTF-16**)重建 ⇒ 未脱敏字节零残留;按 **UTF-8 字节**截 ⇒ 凭据原样残留(反向自证:单位写错的真实后果) | 前缀用 `'sk-…' + '中文'.repeat(30)`;两条重建路径都跑 |
+| G34-04d | 🔴 `delta(含凭据) → idle-flush → delta → 脱敏 text_end`(整截都在**同一条**消息里)→ 终帧带同一份权威全文 | 终答补差**不再追加一份重复正文**(`lastCommittedAnswerText` 已 = 权威全文 ⇒ 落「两份是同一段话」那一臂) | 整链喂 `adapt()` 到 `result`,断言最终转录零重复 |
+| G34-04e | 同上但段**跨过工具卡**(一张 / 两张) | 🔴 **总不变量**:三个修正键仍然正确,而转录逐条 + 终帧**补差臂走向**都与 **0.68.0 逐字相同**(本包只发信号、不动既有行为)。不是本批引入的回归 | 同一条时序跑「认得 text_end」与「不认得」两遍,对照转录与补差基线 |
+| G34-12 | 请求体带 `memoryCapture: 'off'` | 两条车道都 stamp 到 wire;`unregisteredRequestKeys` 两条车道都不点名 | `buildTaskRequest(input, lane)` + `unregisteredRequestKeys` |
+| G34-13 | 🔴 请求体带 `memoryCapture: 'on'` / `'OFF'` / `''` / 布尔 / 对象等任意坏值 | **抛 `TypeError`,拒绝构造请求**(两条车道、不受 live 门);错误文本只报形状不回显值。⚠️ **不是**「静默删键」—— 那会把一条隐私声明按打字错误丢掉,正是 core `memory.d.ts` 与 server §12.4 **点名禁的方向**(会话照常被采集,而声明人不会知道) | `buildTaskRequest` 逐坏值 × 两车道 × live/非 live;`undefined`/`null` 反向自证 = 合法缺席不拒 |
+
+### 34g. 常驻门(本批新增一道 + 扩两道)
+
+| 门 | 守什么 |
+|---|---|
+| 🆕 `scripts/run-text-segment-authority-test.mjs` | S-1 的**六形** + 活体面两形 + 三键 never-false + b1/b2 分水岭 + **两条组合时序**(工具卡后同段继续出 delta / 多段×idle×b2 的字节区间重建)+ `CHROME_ARM_TABLE` 义务文案与实现同律(含 `required` 翻面与「单位是字节不是消息」)+ 端到端两趟(单段 / **连续两段**,后者刻意不手动插段提交)|
+| `scripts/run-tool-roster-projection-test.mjs` | 扩 F 段(出身三键:在场挑出 / 第二成员 / 整键缺席不铸默认 / 开集 / 五种坏形只丢一格 / 不进 `ToolShim`)+ 🆕 **G 段逐键处置台账**(对**实装 core 的 schema 成员表**双向对账 + declined 逐条有理由) |
+| `scripts/run-client-core-pure-test.mjs` | 扩 FIX③ 段(steering 第 8 码归位 + 与两位近邻分家 + 判词口径)与 B8① 段(`memoryCapture` 表行 / 两车道 stamp / 单成员闭集 / 坏拼写 / live 门 / 不再被点名);两段下限同批贴当日实测(B8 158→164、FIX7 89→92) |
+
+---
+
+### §34z 逐键处置表(本批合同的**每一行**在本包的落点)
+
+> 口径与 §33z 一致:`consumed`(+ `文件#符号` 坐标)/ `declined`(+ 理由)/ `n-a`(+ 理由)/ `pending`(+ 票)。
+> **这张表是下游抄 `wire-consumption-manifest` 的母本**。
+
+#### ① server 7.75.3 脱敏面(`ASSISTANT-WIRE-CONTRACT` §5.1 live 面)
+
+| # | 键 / 面 | 处置 | 坐标 / 理由 |
+|---|---|---|---|
+| 1 | `text_end.content` = **经脱敏器的段权威全文**(与 `text_delta` 可不相等) | **consumed** 🔴 | `src/adapt/textStream.ts` 的 `#replaceAnswerSegment` / `#segmentCommitted`;`src/adapt/arms.ts` 的 `#textSegmentEndArm`(改签名成 `ArmFn`);`src/seam.ts` 的 `#TextSegmentEndChromeEvent`(义务① 改口 + 三键);门 `run-text-segment-authority-test.mjs` |
+| 2 | `text_delta` **仍逐字**(流式脱敏是独立设计件) | **consumed**(读法) | 同上 —— 活体面「已泄前缀不是 `content` 前缀 ⇒ 不再补尾巴」那一臂正是按这条写的 |
+| 3 | 替换记号闭形 `«redacted»` / `«redacted:<词>»` / `«redacted:<词>:partial»`(7.75.2 起对嵌套亦然,**残留一形**) | **n-a** | 本包**不解析**这些记号(渲染,不回喂模型)—— 解析失败兜底是**端**的事(契约原文点名「消费端解析 `«…»` 时应留兜底,别当断言」)。grep 证:`src/` 全树 `redacted` **0 命中** |
+| 4 | `reasoning_delta` 逐 chunk 脱敏(跨 chunk 形有残留) | **n-a**(本批) | 思考面本包无「权威全文」对位帧(core 没有 `reasoning_end` 的 content 权威位)⇒ 没有可替换的对象。上游若给出对位帧,按 S-1 同形跟车 |
+| 5 | 禁按 `result` 字节做身份/哈希比对 | **consumed**(零改) | `src/adapt/arms.ts` 的 `#resultArm` 终答补差五格本来就是**前缀/相等**语义,不做哈希;b2 那一形落既有第⑤臂 `result_text_diverged`(**长度位,不复述正文**),是诚实结局不是回归 |
+| 6 | `structuredOutput` 不脱敏(调用方 schema 校验过的对象) | **n-a** | 本包不碰 `structuredOutput` 的字节。grep 证:`src/` 全树 `structuredOutput` **0 命中** |
+
+#### ② core 名册成员(core 的 `core/tool-roster.ts` 的 `ToolRosterEntry`,32 键)
+
+| # | 键 / 面 | 处置 | 坐标 / 理由 |
+|---|---|---|---|
+| 1 | `contentOriginProvenance`(四词) | **consumed** | `src/toolRoster.ts` 的 `#ToolRosterEntryView` / `#readEntry`(开集读) |
+| 2 | `effectProvenance` / `egressProvenance`(同形族扫) | **consumed** | 同上 —— 三根轴各一个出身键,漏的形一模一样 |
+| 3 | 其余 12 个未挑成员 | **declined**(逐条有理由) | 理由逐条在 `scripts/run-tool-roster-projection-test.mjs` G 段的 `DISPOSITION` 账上,摘要见 §34c;🔴 该段对**实装 core schema** 双向对账,上游加成员当天红 |
+| 4 | 已挑的 17 个存量成员 | **consumed**(零改) | `src/toolRoster.ts` 同上,0.63.0 起 |
+
+#### ③ [7226] 包侧缺口(点名 @client-core 的两条)
+
+| # | 键 / 面 | 处置 | 坐标 / 理由 |
+|---|---|---|---|
+| 1 | ① `steering.blocked_by_hook`(第 8 码,422) | **consumed** | `src/controlRouter.ts` 的 `#ControlSafetyCode`(加员 `blocked_by_hook`)/ `#STEERING_CODE_TO_SAFETY` / `#STEERING_ADVICE` |
+| 2 | ⑤ `memoryCapture: "off"`(提交面,单成员闭集) | **consumed** | `src/request/taskRequest.ts` 的 `#REQUEST_FIELD_MATRIX`(新行)/ `#TaskRequestInput.memoryCapture` / `#buildTaskRequest` 的 `=== 'off'` stamp |
+| 3 | `steering.parked_input_blocked`(park 腿的**通告**,不是拒绝码) | **n-a** | 它是 `engine_notice` 码册里的一员、不是 `steering.*` 拒绝族;本路由器调的是 live 腿,park 腿结构性不可达。通告面读点另在 `src/engineNoticeCodes.ts`,本批不动 |
+| 4 | 中途翻转 verb `POST /v1/runs/:id/memory/capture-optout` + 能力位 `runMemoryCaptureOptOut` | **n-a**(本批) | 那是**动词面**(需要 run 属主门 + 活流句柄),不在请求构造面上;本批补的是它 409 时**指路**的那个声明键。端按能力位渲入口的纪律不变(假 affordance) |
+| 5 | `memoryCapture` 坏拼写 400 `request.field_invalid` / core `config.memory_capture_spelling` | **n-a** | server 是权威校验方,本层不预铸第二判官;但也不替它买路(`'on'` / 表外拼写整键不 stamp) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.68.0",
+  "version": "0.68.1",
   "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. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",