@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/toolRoster.d.ts

@@ -1,62 +1,12 @@
-/**
- * src/toolRoster.ts — 一条腿的**工具名册**(`wiring_manifest.tools: ToolRoster`)窄读器 +
- * `tool_roster_delta` 应用(0.63.0;L-161;engine >=7.66.0 有臂 / >=7.9.0 真推 /
- * sdk 8.6.0 型面 + 8.7.0 `pathTarget` 三键)。
- *
- * -- 名册回答的是三端一直在猜的那一问 --------------------------------------------------------
- * 「这条腿到底挂了哪些工具、每一只是什么面」此前只能猜:`liveInitToolFace.ts` 那三张词表
- * (`ENGINE_HANDS_BAND` / `ENGINE_SCENARIO_EXTRAS_DEFAULT` / `ENGINE_RUNNER_FACE`)是 2026-07-16
- * 一次 tap 实测的**估计值**,按 pin 的引擎版本定稿;外接别的引擎、别的场景、别的 env 门就会偏。
- * 名册是**引擎自己说的**:每只工具的身份(契约 id / 形状指纹 / 能力 id)、轴(effect / egress /
- * irreversibility)、面(family / pathTarget / renderHints)。
- * 🔴 **名册在场用名册,缺席才回落三表**。本批**不删**那三张表(名册只在 effective 半场、且只有
- *    >=7.9.0 的引擎才真推,回落还得留着);`liveInitToolFace.ts` 的头注登记了退役条款:
- *    **名册恒在场的版本到货即删表**。
- *
- * -- 🔴 绝不半张名册(照抄上游的纪律)--------------------------------------------------------
- * 引擎的 fail-open 台账逐字写着:载荷过不了 core 自己的判形器 => 那一段缺席 / 那一帧不发,
- * **绝不半张脸上 wire**;并写明反方向更坏 ——「把一份判不了形的名册照发,消费端会把读不出的行
- * 当成**这只工具没挂**」。本窄读器照抄这条:**任一行读不出 => 整只 `undefined`**;`count` 与真实
- * 行数对不上同理(core 在铸点 run-time 断言两者相等)。少几行的名册比没有名册坏。
- * ⚠️ 例外只有**面**:一行的 `pathTarget` / `renderHints` 自己形坏时只丢那一格,行还在 —— 面不是
- *    身份,丢一张面不等于「这只工具没挂」。
- *
- * -- 🔴 `fromDigest` 对不上**不是拒绝** ------------------------------------------------------
- * 契约里唯一的硬话:`fromDigest` 对不上时,**携带的整只名册无论如何都是新状态**,只有 `summary`
- * 变得不可用(消费端记一次 skew 后按快照重同步)。所以 {@link applyToolRosterDelta} 在 skew 时
- * **照换名册、只丢 summary**。拒绝换会让消费端永远抱着一份过期名册 —— 那比一次 skew 坏得多,
- * 而且它把「位置从名册来、永远不从 summary 来」这条契约反过来用了。
- *
- * -- 开集读 -----------------------------------------------------------------------------------
- * `source`(七词)/ `effect` / `family` / `access` / 三个 `*Provenance` 等词表的属主都是引擎,一律
- * **原样透传**,不窄读成枚举 —— 那会在引擎加词当天把一份真名册判没。
- *
- * -- 🔴 逐键窄读器 vs 上游的逐字透传(L-290 的病形,0.68.1)-----------------------------------
- * server(`src/trace/project.ts` 的 `tools` 段)对名册的姿势是**整只判形 + 逐字透传**,理由逐字:
- * 成员表由 core 以 typebox schema 单点持有,手抄一张挑键表 = 立刻多一份会漂的镜像。本读器**确实**
- * 是那份镜像(本包要给三端一个窄化过的视图,不能把 30 余键的开集原样甩出去)—— 所以镜像必须有账:
- * `scripts/run-tool-roster-projection-test.mjs` **G 段**拿**实装 core 的 schema 成员表**与本读器
- * 真挑出来的键集逐键对账,core 的每一个成员要么被挑、要么在账上写明「为什么不挑」;上游加一个
- * 成员而账上没有 ⇒ 当天红。没有这本账,「挑漏一个键 = 那个键在包边界上不存在」就会一直无声发生。
- */
-/** 一只工具的**路径目标**(引擎的 `pathTarget`;`base`/`absent`/`patternParam` 是 core 7.9.1 #635 加的)。 */
 export interface ToolRosterPathTargetView {
-    /** 输入里哪个键是路径。 */
     param: string;
-    /** `read` / `create` / `edit`;**开集读**。 */
     access: string;
-    /** 同义键。 */
     aliases?: readonly string[];
     skillScopeEligible?: true;
-    /** 相对路径按哪个基解析(`cwd` 活目录 / `root` 任务根);**声明时才在场**,缺席就是缺席。 */
     base?: string;
-    /** 参数缺席时目标是什么(`none` 无 / `base` 基目录)。同上,缺席不铸默认。 */
     absent?: string;
-    /** 承载 glob **模式**的输入键(如 `Glob.pattern`)。 */
     patternParam?: string;
 }
-/** 一只工具的**渲染提示**(引擎自己给的人话名 / 进行时文案 / 摘要参数 / 结果卡 / 审批卡型)。
- *  🔴 端渲这只工具时用它,**别按工具名猜** —— 按名字猜正是 `liveInitToolFace` 三张估计词表的病根。 */
 export interface ToolRosterRenderHintsView {
     userFacingName?: string;
     activity?: string;
@@ -64,13 +14,10 @@ export interface ToolRosterRenderHintsView {
     resultCards?: readonly string[];
     approvalCard?: string;
 }
-/** 名册里的一行。身份两键必填,其余全可选(缺席即缺席,绝不铸默认)。 */
 export interface ToolRosterEntryView {
     name: string;
     aliases?: readonly string[];
-    /** `builtin` / `caller` / `host` / `mcp` / `a2a` / `external` / `synthetic`;**开集读**。 */
     source: string;
-    /** mcp / a2a / external 行才有的出身(`peer` = 声明名)。 */
     origin?: {
         peer: string;
         declaredBy?: string;
@@ -81,38 +28,14 @@ export interface ToolRosterEntryView {
     };
     shapeDigest?: string;
     wireSchemaDigest?: string;
-    /** 卡的身份。**同名不同身的两行按两只 id 去重,不按 `name`**。 */
     cardId?: string;
     capabilityId?: string;
-    /** `read` / `write` / `idempotent`;开集读。 */
     effect?: string;
-    /**
-     * `effect` 这根轴**是谁说的**(`declared` 定义自报 / `caller` 调用方声明 / `synthetic` 引擎合成 /
-     * `default` 谁都没说,落默认);**开集读**。见下面 {@link ToolRosterEntryView.contentOriginProvenance}
-     * 的头注 —— 三个出身键同生同灭。
-     */
     effectProvenance?: string;
     egress?: boolean;
-    /** `egress` 这根轴的出身(`declared` / `caller` / `default`);**开集读**,读法同上。 */
     egressProvenance?: string;
-    /** `never` / `maybe` / `always`;开集读。 */
     irreversibility?: string;
     contentOrigin?: string;
-    /**
-     * `contentOrigin` 这根轴的出身(`declared` 定义自报 / `server` mcp·a2a 行由服务端定 /
-     * `exempted` 在受信工具豁免名单里 / `default` 谁都没说);**开集读**(L-290,0.68.1)。
-     *
-     * 🔴 **为什么要有这一位**:轴的**值**说的是「这只工具的产出算不算外来内容」,而一个
-     * `contentOrigin: "local"` 到底是**工具自己声明**的、还是**因为它在豁免名单里**才这样 ——
-     * 在信任面上是两件事。诊断行(壳 `/doctor` 的「Tools (engine leg)」)读的正是后者。
-     * 🔴 **族扫(同形存量清剿)**:server `src/trace/project.ts` 的 `tools` 段是**整只判形 + 逐字
-     * 透传**,而本读器是**逐键挑** —— 挑漏的键在包边界上等于不存在。三根轴各有一个出身键,漏的形
-     * 一模一样,所以三个一起挑,不是只补被点名的那一个;核过之后 core `ToolRosterEntry` 的**每一个**
-     * 成员在 `scripts/run-tool-roster-projection-test.mjs` G 段都有一行处置(挑 / 不挑 + 理由),
-     * 上游再加成员当天红。
-     * ⚠️ 出身键是**诊断面**,刻意**不进** {@link ToolShim}(那是渲染面:人话名 / 卡型 / 三根轴的
-     * **值**)—— 端渲一只工具时要的是「它是什么」,不是「这句话是谁说的」。
-     */
     contentOriginProvenance?: string;
     family?: string;
     pathTarget?: ToolRosterPathTargetView;
@@ -122,36 +45,14 @@ export interface ToolRosterEntryView {
         params?: readonly string[];
     };
 }
-/** 一条腿的整只名册。 */
 export interface ToolRosterView {
     schemaVersion: number;
-    /** 引擎自报的行数;本读器已核过它等于 `entries.length`(对不上 => 整只判没)。 */
     count: number;
-    /** 整只名册的指纹,**恰 16 位小写 hex**;任一轴/面/契约/别名变化都会移动它。重同步的锚。 */
     digest: string;
-    /** **声明序 = 模型看到的 `tools[]` 序**(不排序、不去重、不重排)。 */
     entries: readonly ToolRosterEntryView[];
 }
-/**
- * `wiring_manifest` 的 `tools` 段 → 名册视图;整段缺席 / 任一行读不出 / `count` 对不上 =>
- * `undefined`,绝不抛出。
- *
- * ⚠️ **空名册是正面事实**(这条腿一只工具都没挂),照读成 0 行 —— 与 `wiring_manifest.mcp[]` 的
- *    空数组同一条已定谳的纪律,把它折成缺席等于把引擎明说的一句话读成「不知道」。
- * ⚠️ 只在 **effective 半场**(live 帧)才有;诊断端点返回的 `static` 半场恒无 —— 那里的缺席是
- *    结构性的,不是「这台引擎太老」。
- */
 export declare function projectToolRoster(manifest: unknown): ToolRosterView | undefined;
-/** 名册里的工具名,**按声明序**(= 模型看到的 `tools[]` 序)。 */
 export declare function toolRosterNames(roster: ToolRosterView | undefined): readonly string[];
-/**
- * 端渲一只工具时要用的那张**面**(`liveInitToolFace.ts` 三张估计词表的继任形)。
- *
- * 🔴 **面只从名册的行取,绝不从工具名猜**:一个叫 `Bash` 的行不一定是 shell 家族(caller 挂的
- *    同名工具、mcp 命名空间下的同名工具都可能),而「按名字猜出来的面」正是三张估计词表的病根。
- * 🔴 **缺席就是缺席**:轴(`egress` / `irreversibility` / `effect`)读不出时留空,**绝不**填
- *    `false` / `'never'` —— 那会把「不知道」渲成「安全」,是这条面上最贵的一种谎。
- */
 export interface ToolShim {
     name: string;
     source: string;
@@ -163,73 +64,32 @@ export interface ToolShim {
     effect?: string;
     egress?: boolean;
     irreversibility?: string;
-    /** 输入里哪个键是路径(端渲写卡/围栏提示要用)。 */
     pathTargetParam?: string;
-    /** mcp / a2a / external 行的声明名。 */
     peer?: string;
-    /** 身份两只 id:**同名不同身的两行按它们去重,不按 `name`**。 */
     cardId?: string;
     capabilityId?: string;
 }
-/** 名册的一行 → 端用的面。行不成形(身份两键读不出)=> `undefined`,绝不抛出。 */
 export declare function toolShimFromRoster(entry: unknown): ToolShim | undefined;
-/** 一次 `tool_roster_delta` 应用之后的状态。 */
 export interface ToolRosterDeltaApplication {
-    /** 应用后消费端该持有的名册。帧判不出形 => 原样是入参那一份(什么都没发生)。 */
     roster: ToolRosterView | undefined;
-    /** 这一帧被采纳了吗(帧判不出形 => `false`)。 */
     applied: boolean;
-    /**
-     * `fromDigest` 与手上那份对不上(或手上压根没有名册)。
-     * 🔴 **这不是拒绝** —— 名册照换,只有 {@link summary} 变得不可用。消费端据此记一次偏斜。
-     */
     skew: boolean;
-    /**
-     * 三张**互不相交**的名单。`skew` 为真、或这一段自己形坏时**缺席** —— 交一份对不上的名单比
-     * 不交更坏(位置永远从名册来,从来不从 summary 来)。
-     * ⚠️ 三张全空是**正面事实**(一次字节相同的 re-mint 也会发帧),不是「读不出」。
-     */
     summary?: ToolRosterDeltaSummary;
 }
-/**
- * 一次名册变更的**名字摘要**:三张**互不相交**的名单。
- * ⚠️ 位置永远从名册来,从来不从这里来 —— 这三张名单只回答「变了哪些名字」。
- * ⚠️ 三张全空是**正面事实**(一次字节相同的 re-mint 也会发帧),不是「读不出」。
- */
 export interface ToolRosterDeltaSummary {
     added: readonly string[];
     removed: readonly string[];
     changed: readonly string[];
 }
-/**
- * `tool_roster_delta` → 新的持有状态。**纯函数**(不改入参)。
- *
- * 🔴 `fromDigest` 对不上**不是拒绝**(契约里唯一的硬话):携带的整只名册无论如何都是新状态,
- *    只有 `summary` 变得不可用。拒绝换会让消费端永远抱着一份过期名册 —— 比一次 skew 坏得多。
- * 🔴 手上**没有**名册(首帧就是 delta)同样算 `skew`:没有可比的 digest 就是比不出来,而
- *    「比不出来」不许被读成「对上了」。
- * 🔴 帧本身判不出形 => **什么都没发生**:原样交回入参那一份(不清空 —— 清空会把一次读不懂的帧
- *    变成一次「所有工具都没挂」)。
- */
-/** CC-08(0.71.0):一帧 `tool_roster_delta` 的**视图**(不应用、不比对 digest —— 那是持名册的宿主的事)。 */
 export interface ToolRosterDeltaView {
-    /** 这一帧假定消费端手上那份名册的 digest。对不上 = 记 skew 后整只替换,不是拒绝。 */
     fromDigest: string;
-    /** 变更**之后**的整只名册(位置信息一律从它读)。 */
     roster: ToolRosterView;
-    /** 三个两两不相交的名字列表;读不出(半张名单)⇒ 整键缺席,名册照交。 */
     summary?: ToolRosterSummaryView;
 }
-/** CC-08(0.71.0):`tool_roster_delta.summary` —— 三个两两不相交的名字列表(`changed` 里那个名字的新行在 `roster` 里)。 */
 export interface ToolRosterSummaryView {
     added: readonly string[];
     removed: readonly string[];
     changed: readonly string[];
 }
-/**
- * CC-08(0.71.0):`tool_roster_delta.delta` → 视图;`fromDigest` 非空串 ∧ `roster` 读得出才成形,否则 `undefined`
- * (server 判不出 core 的形就整帧不发,所以本层读不出 = 坏帧,由投影口报 malformed)。
- * 宿主拿它喂 {@link applyToolRosterDelta}(那只吃 raw,这里给的是已窄读的同形;两只读法同源 `readRoster`)。
- */
 export declare function projectToolRosterDelta(delta: unknown): ToolRosterDeltaView | undefined;
 export declare function applyToolRosterDelta(held: ToolRosterView | undefined, delta: unknown): ToolRosterDeltaApplication;

package/dist/toolRoster.js

@@ -1,48 +1,6 @@
-/**
- * src/toolRoster.ts — 一条腿的**工具名册**(`wiring_manifest.tools: ToolRoster`)窄读器 +
- * `tool_roster_delta` 应用(0.63.0;L-161;engine >=7.66.0 有臂 / >=7.9.0 真推 /
- * sdk 8.6.0 型面 + 8.7.0 `pathTarget` 三键)。
- *
- * -- 名册回答的是三端一直在猜的那一问 --------------------------------------------------------
- * 「这条腿到底挂了哪些工具、每一只是什么面」此前只能猜:`liveInitToolFace.ts` 那三张词表
- * (`ENGINE_HANDS_BAND` / `ENGINE_SCENARIO_EXTRAS_DEFAULT` / `ENGINE_RUNNER_FACE`)是 2026-07-16
- * 一次 tap 实测的**估计值**,按 pin 的引擎版本定稿;外接别的引擎、别的场景、别的 env 门就会偏。
- * 名册是**引擎自己说的**:每只工具的身份(契约 id / 形状指纹 / 能力 id)、轴(effect / egress /
- * irreversibility)、面(family / pathTarget / renderHints)。
- * 🔴 **名册在场用名册,缺席才回落三表**。本批**不删**那三张表(名册只在 effective 半场、且只有
- *    >=7.9.0 的引擎才真推,回落还得留着);`liveInitToolFace.ts` 的头注登记了退役条款:
- *    **名册恒在场的版本到货即删表**。
- *
- * -- 🔴 绝不半张名册(照抄上游的纪律)--------------------------------------------------------
- * 引擎的 fail-open 台账逐字写着:载荷过不了 core 自己的判形器 => 那一段缺席 / 那一帧不发,
- * **绝不半张脸上 wire**;并写明反方向更坏 ——「把一份判不了形的名册照发,消费端会把读不出的行
- * 当成**这只工具没挂**」。本窄读器照抄这条:**任一行读不出 => 整只 `undefined`**;`count` 与真实
- * 行数对不上同理(core 在铸点 run-time 断言两者相等)。少几行的名册比没有名册坏。
- * ⚠️ 例外只有**面**:一行的 `pathTarget` / `renderHints` 自己形坏时只丢那一格,行还在 —— 面不是
- *    身份,丢一张面不等于「这只工具没挂」。
- *
- * -- 🔴 `fromDigest` 对不上**不是拒绝** ------------------------------------------------------
- * 契约里唯一的硬话:`fromDigest` 对不上时,**携带的整只名册无论如何都是新状态**,只有 `summary`
- * 变得不可用(消费端记一次 skew 后按快照重同步)。所以 {@link applyToolRosterDelta} 在 skew 时
- * **照换名册、只丢 summary**。拒绝换会让消费端永远抱着一份过期名册 —— 那比一次 skew 坏得多,
- * 而且它把「位置从名册来、永远不从 summary 来」这条契约反过来用了。
- *
- * -- 开集读 -----------------------------------------------------------------------------------
- * `source`(七词)/ `effect` / `family` / `access` / 三个 `*Provenance` 等词表的属主都是引擎,一律
- * **原样透传**,不窄读成枚举 —— 那会在引擎加词当天把一份真名册判没。
- *
- * -- 🔴 逐键窄读器 vs 上游的逐字透传(L-290 的病形,0.68.1)-----------------------------------
- * server(`src/trace/project.ts` 的 `tools` 段)对名册的姿势是**整只判形 + 逐字透传**,理由逐字:
- * 成员表由 core 以 typebox schema 单点持有,手抄一张挑键表 = 立刻多一份会漂的镜像。本读器**确实**
- * 是那份镜像(本包要给三端一个窄化过的视图,不能把 30 余键的开集原样甩出去)—— 所以镜像必须有账:
- * `scripts/run-tool-roster-projection-test.mjs` **G 段**拿**实装 core 的 schema 成员表**与本读器
- * 真挑出来的键集逐键对账,core 的每一个成员要么被挑、要么在账上写明「为什么不挑」;上游加一个
- * 成员而账上没有 ⇒ 当天红。没有这本账,「挑漏一个键 = 那个键在包边界上不存在」就会一直无声发生。
- */
 const str = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
 const strArr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
 const obj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) ? v : undefined;
-/** 指纹判据:**恰** 16 位小写 hex(引擎铸的就是这个形;放宽会让一个坏锚看起来能用)。 */
 const DIGEST_RE = /^[0-9a-f]{16}$/;
 function readPathTarget(raw) {
     const o = obj(raw);
@@ -50,7 +8,6 @@ function readPathTarget(raw) {
         return undefined;
     const param = str(o.param);
     const access = str(o.access);
-    // 两必填键读不出 => 这张面不成形。**只丢面,不丢行**(面不是身份)。
     if (param === undefined || access === undefined)
         return undefined;
     const aliases = strArr(o.aliases);
@@ -73,7 +30,6 @@ function readEntry(raw) {
         return undefined;
     const name = str(o.name);
     const source = str(o.source);
-    // 身份两键读不出 => 这一行不成形 => 由调用方把**整只名册**判没(见模块顶注)。
     if (name === undefined || source === undefined)
         return undefined;
     const originRaw = obj(o.origin);
@@ -99,7 +55,6 @@ function readEntry(raw) {
         ...(str(o.cardId) !== undefined ? { cardId: str(o.cardId) } : {}),
         ...(str(o.capabilityId) !== undefined ? { capabilityId: str(o.capabilityId) } : {}),
         ...(str(o.effect) !== undefined ? { effect: str(o.effect) } : {}),
-        // L-290 族扫:三根轴各自的**出身**键(开集读,`str()` 同律;坏形只丢这一格,行还在 —— 出身不是身份)。
         ...(str(o.effectProvenance) !== undefined ? { effectProvenance: str(o.effectProvenance) } : {}),
         ...(typeof o.egress === 'boolean' ? { egress: o.egress } : {}),
         ...(str(o.egressProvenance) !== undefined ? { egressProvenance: str(o.egressProvenance) } : {}),
@@ -133,7 +88,6 @@ function readEntry(raw) {
             : {}),
     };
 }
-/** 一只**已经剥出来**的名册体(不带 `tools` 包层)→ 视图;坏形 => `undefined`。 */
 function readRoster(raw) {
     const o = obj(raw);
     if (o === undefined)
@@ -145,13 +99,11 @@ function readRoster(raw) {
         return undefined;
     if (typeof o.count !== 'number' || !Number.isInteger(o.count) || o.count < 0)
         return undefined;
-    // 🔴 count 是引擎在铸点 run-time 断言过的量;对不上 => 这份载荷在路上被改过或被半截序列化。
     if (o.count !== o.entries.length)
         return undefined;
     const entries = [];
     for (const raw2 of o.entries) {
         const e = readEntry(raw2);
-        // 🔴 绝不半张名册:一行读不出 => 整只判没(见模块顶注)。
         if (e === undefined)
             return undefined;
         entries.push(e);
@@ -159,15 +111,6 @@ function readRoster(raw) {
     const schemaVersion = typeof o.schemaVersion === 'number' && Number.isFinite(o.schemaVersion) ? o.schemaVersion : 1;
     return { schemaVersion, count: o.count, digest, entries };
 }
-/**
- * `wiring_manifest` 的 `tools` 段 → 名册视图;整段缺席 / 任一行读不出 / `count` 对不上 =>
- * `undefined`,绝不抛出。
- *
- * ⚠️ **空名册是正面事实**(这条腿一只工具都没挂),照读成 0 行 —— 与 `wiring_manifest.mcp[]` 的
- *    空数组同一条已定谳的纪律,把它折成缺席等于把引擎明说的一句话读成「不知道」。
- * ⚠️ 只在 **effective 半场**(live 帧)才有;诊断端点返回的 `static` 半场恒无 —— 那里的缺席是
- *    结构性的,不是「这台引擎太老」。
- */
 export function projectToolRoster(manifest) {
     const o = obj(manifest);
     if (o === undefined)
@@ -176,11 +119,9 @@ export function projectToolRoster(manifest) {
         return undefined;
     return readRoster(o.tools);
 }
-/** 名册里的工具名,**按声明序**(= 模型看到的 `tools[]` 序)。 */
 export function toolRosterNames(roster) {
     return roster?.entries.map((e) => e.name) ?? [];
 }
-/** 名册的一行 → 端用的面。行不成形(身份两键读不出)=> `undefined`,绝不抛出。 */
 export function toolShimFromRoster(entry) {
     const e = readEntry(entry);
     if (e === undefined)
@@ -211,23 +152,16 @@ function readSummary(raw) {
     const changed = strArr(o.changed);
     if (added === undefined || removed === undefined || changed === undefined)
         return undefined;
-    // 数组里混进非串时 `strArr` 会静默滤掉 —— 那等于交一份少了名字的名单,与「绝不半张」同罪。
     if (!Array.isArray(o.added) || added.length !== o.added.length ||
         !Array.isArray(o.removed) || removed.length !== o.removed.length ||
         !Array.isArray(o.changed) || changed.length !== o.changed.length) {
         return undefined;
     }
-    // 契约:三张名单**互不相交**。交了集就是坏 summary。
     const all = [...added, ...removed, ...changed];
     if (new Set(all).size !== all.length)
         return undefined;
     return { added, removed, changed };
 }
-/**
- * CC-08(0.71.0):`tool_roster_delta.delta` → 视图;`fromDigest` 非空串 ∧ `roster` 读得出才成形,否则 `undefined`
- * (server 判不出 core 的形就整帧不发,所以本层读不出 = 坏帧,由投影口报 malformed)。
- * 宿主拿它喂 {@link applyToolRosterDelta}(那只吃 raw,这里给的是已窄读的同形;两只读法同源 `readRoster`)。
- */
 export function projectToolRosterDelta(delta) {
     const d = obj(delta);
     if (d === undefined)

package/dist/typePins.d.ts

@@ -1,51 +1,5 @@
-/**
- * src/typePins.ts — shared type-only "bidirectional exhaustiveness pin" primitive
- * (REF-CC-145 / REF-CC-dup-12, P3 wave1 卡C-argv, 2026-08-01).
- *
- * 🔴 [2006] B-CC-2(2026-07-29):a `readonly X[]` annotation only proves "every element is a
- * legal X" — it never proves the reverse ("every X has an element"). Add an eighth arm to a
- * literal union and forget to add it to the matching const tuple and the compiler stays silent;
- * the new arm is then silently dropped by whatever `Set`/`switch` consumes the tuple at runtime.
- * `Covers<A, B>` is the door's single mint point: `Exclude<A, B> extends never` collapses to
- * `never` exactly when "every member of A is also in B"; pinning it to `true` turns a violation
- * into a compile-time red. Callers crib a pair per axis: `[Covers<A, B>, Covers<B, A>]`.
- *
- * type-only export: zero runtime cost, zero transitive dependency (the portability door's
- * value-level closure scan strips type-only edges before walking the graph — see
- * run-client-core-portability-test.mjs 头注 "①源码级传递闭包…剥 type-only").
- */
 export type Covers<A, B> = Exclude<A, B> extends never ? true : never;
-/**
- * 🔴 `AllReadonly<T>`(0.48.0,对抗复审 [medium] 采纳后铸的第二把钉)—— 「T 的**每一个**顶层
- * 属性都是 `readonly`」的编译期判据。`true` = 全只读;`false` = 至少有一个可写位。
- *
- * 为什么需要它:把一个自铸形换成上游形的**别名**时,成员名与成员类型都能逐个对上,唯独
- * **修饰符**会静默丢失 —— 而 `readonly` 是已发布的类型契约的一部分。本批实翻:0.47.0 的
- * `GateCurrentPending` 三位全 `readonly`(那三位是 D-1 坐标,契约是**逐字回显、绝不本地重算**),
- * 换成上游 `ApprovalStaleCurrentPending` 的别名之后三位都变成可写 —— 名字、字段、行为门全绿,
- * 只有消费方手上的契约悄悄弱了一档。这类退化**没有任何行为门看得见**(它不改变任何运行期字节),
- * 只有编译期判据抓得住。
- *
- * 实现锚 = TS 的「同一性」惯用法:两个泛型函数签名只有在类型**完全相同**(含修饰符)时才互相
- * 赋值兼容,所以某个位与「剥掉它 readonly 的同一个位」相等 ⇔ 那个位本来就没有 readonly。
- *
- * 🔴 **逐位判,不是整形判**(本批自查命中,首版就是错的):整形写法
- * `IdenticalTo<T, {-readonly [K in keyof T]: T[K]}, false, true>` 只要**有一位**是 readonly 就答
- * `true` —— 它其实是 `SomeReadonly`,名字比它做的事强一档。实测反证:
- * `{readonly a: string; b: number}`(一半只读)在整形写法下答 `true`,于是「三位里有两位被改成可写」
- * 这类**部分退化**能整个溜过去。⇒ 改成把每一位单独拎出来判,全体无可写位才 `true`。
- * (`[X] extends [never]` 的方括号是必须的:裸 `X extends never` 在 X 是联合时会分配,空联合恒真。)
- *
- * 🔴 **守到哪、没守到哪(明写,免得下一棒over-trust 这把钉)**:本判据是**浅层**的 —— 它只判 T 的
- * **顶层**属性(可选位也进得来,`-?` 管这一格)。嵌套对象**内部**的成员是否 readonly、数组元素是否
- * `readonly T[]`,它一概不看,`Readonly<T>` 本身也只做一层。所以它能抓的是「整形/部分位的顶层
- * readonly 退化」,抓不到「某个嵌套成员从 readonly 变可写」。
- * 今天的唯一消费者 `GateCurrentPending` 三位全是**扁平标量**(两 `string` + 一可选 `string`),
- * 浅层判据对它是**完备**的;哪天有人拿它去钉一个带嵌套对象的形,先回来读这一段
- * ——「一道只守住一半却被当成守住全部的门」比没有门更坏([surfacing-is-not-gating] 同族)。
- */
 type IdenticalTo<X, Y, Yes, No> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? Yes : No;
-/** T 里**可写**位的名字联合(全只读 ⇒ `never`)。`-?` 让可选位也进得来。 */
 type WritableKeys<T> = {
     [P in keyof T]-?: IdenticalTo<{
         [Q in P]: T[P];

package/dist/types/engineState.d.ts

@@ -1,116 +1,45 @@
-/**
- * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/types/engineState.ts 逐字搬入(纯类型,零运行时;壳侧改 re-export)。
- * ⚠️ 归属注记:`EngineInstance`/`TOCConfig` 描述的是**宿主**职责(spawn/端口/日志路径),逻辑本体
- * (engineLifecycleManager)按设计稿 §2.4.2-A 留 TUI;搬进本包的只是**形状**,让 desktop 宿主与
- * TUI 宿主共用同一套 /health 与 engine.port 契约类型,不代表生命周期逻辑下沉。
- */
-/**
- * TOC 一体化 (TP-A-P0-IMPL Step 5) — Engine Lifecycle 状态类型。
- *
- * 壳一体化起本地引擎(ai-agent-service file 模式),对用户透明,体验等同 CC 单进程。
- * 本文件只定义跨 lifecycle 流转的纯数据形状,不含逻辑(逻辑在 engineLifecycleManager.ts)。
- *
- * 真相源契约:engine.port 文件是壳↔引擎的「当前活引擎」单一发现锚点(flock 串行化写,
- * write-temp+fsync+mv 原子落盘)。HealthResponse 字段与引擎 server.ts:645-660 /health 逐字对齐
- * (W2 同约定实现):instanceId/dataRoot/configHash/pid —— 壳据此判断「连对引擎」防陈旧 port 连错。
- */
-/** 引擎 GET /health 返回体(与 ai-agent-service server.ts:645-660 对齐;字段大多 additive 可缺)。 */
 export interface HealthResponse {
-    /** 恒为 'ok';非 200 / 非此值 = 不健康。 */
     status: string;
-    /** 当前模型 id(configHash 的一部分,信息性)。 */
     model?: string;
-    /** 会话存储后端('file' for TOC local)。 */
     sessionBackend?: string;
-    /** 活跃 session 数(信息性)。 */
     sessions?: number;
-    /** 引擎实例身份(uuidv7,每次 boot 唯一)。陈旧 port 连错引擎时此值会变 → 拒连。 */
     instanceId?: string;
-    /** 引擎 localDataRoot 解析结果。壳校验 === assembleChildEnv 注入的 LOCAL_DATA_ROOT。 */
     dataRoot?: string;
-    /** restart-relevant config 的稳定指纹(无 secret)。drift 检测:configHash 变 → 拒连旧引擎。 */
     configHash?: string;
-    /** 引擎进程 pid。orphan reap 的 kill-0 目标 + heartbeat 死活判定。 */
     pid?: number;
-    /** 引擎监听端口。 */
     port?: number;
-    /** 引擎请求重启(center restart 信号);壳侧信息性。 */
     restartRequired?: boolean;
-    /** 引擎 build 版本自述(service 1.96+,[392]ask②)。复用时与本地 dist 版本比对,不一致=陈旧代码拒复用。 */
     version?: string;
 }
-/**
- * engine.port 文件落盘的 JSON 形状(write-temp+fsync+mv 原子写)。
- * 壳启动时读此文件做引擎发现:存在且 kill-0 活 + /health 身份匹配 → 复用;否则 reap + spawn。
- * 🔴 secrets 边界:绝不写入任何明文 token/secret(只透传到 child env)。grep engine.port 不得见 secret。
- */
 export interface EnginePortFile {
-    /** 引擎监听端口。 */
     port: number;
-    /** spawn 出的引擎子进程 pid(kill-0 存活检测 / orphan reap 目标)。 */
     pid: number;
-    /** 引擎实例身份(uuidv7);连接前用 /health 复验,不匹配 = 陈旧 port。 */
     instanceId?: string;
-    /** 引擎 localDataRoot;身份校验用。 */
     dataRoot?: string;
-    /** boot 时记录的 configHash;drift 检测基线。 */
     configHash?: string;
-    /** 引擎日志文件路径(<configHome>/engine-<pid>.log),壳可 tail 诊断。 */
     logPath: string;
-    /** 落盘时间戳(epoch ms);信息性 / 调试用。 */
     startedAt: number;
-    /** 写文件的格式版本(向后兼容);当前 1。 */
     version: number;
-    /**
-     * P2 云配置整体开关:spawn 该引擎时生效的配置源标签('local' | 'cloud:<profile>')。
-     * ADDITIVE 可缺(老文件缺 = 'local')。boot 复用检查:与当前 desiredEngineConfigSource() 不一致
-     * → 视同配置漂移 reap+respawn(models 域走 CONFIG_LOCAL_DIR shadow,restart-to-apply)。
-     */
     configSource?: string;
 }
-/**
- * 内存中持有的「已托管引擎实例」句柄。lifecycle 全程持有,shutdown 时据此 SIGTERM/SIGKILL。
- */
 export interface EngineInstance {
-    /** 监听端口。 */
     port: number;
-    /** 子进程 pid。 */
     pid: number;
-    /** baseUrl = http://127.0.0.1:<port>,壳设到 SEMA_LIVE_BASEURL。 */
     baseUrl: string;
-    /** /health 校验拿到的身份(复用既有引擎时可能来自 probe,而非自己 spawn)。 */
     instanceId?: string;
-    /** 引擎 dataRoot。 */
     dataRoot?: string;
-    /** boot configHash 基线(heartbeat drift 检测)。 */
     configHash?: string;
-    /** 日志文件路径(自己 spawn 的才有;复用既有引擎为 undefined)。 */
     logPath?: string;
-    /** true = 本壳 spawn 出来的(shutdown 时负责回收);false = 复用既有引擎(不杀)。 */
     ownedByThisShell: boolean;
-    /** node ChildProcess 句柄(仅自己 spawn 时有;复用既有为 undefined)。as unknown 避免类型耦合 child_process。 */
     child?: unknown;
 }
-/**
- * 壳注入给引擎子进程的 TOC env pack(§3.1)。引擎默认偏云(PORT=8090/DB_BACKEND=tidb/
- * CONFIG_PROVIDER=undefined),壳必须显式覆盖为 local 单用户模式,绝不依赖引擎默认。
- * secrets(ANTHROPIC_API_KEY/E2B_API_KEY 等)仅在父 env 存在时透传到 child,不落任何文件。
- */
 export interface TOCConfig {
-    /** 选定端口(显式 pin SEMA_ENGINE_PORT 优先;无 pin 按 config dir 派生 + 空闲探测,P0-2)。 */
     port: number;
-    /** 引擎数据根 = <configHome>/engine-data;引擎 LOCAL_DATA_ROOT 优先级链最高项。 */
     localDataRoot: string;
-    /** 本地 config.d 目录 = <configHome>/config.d(引擎 CONFIG_LOCAL_DIR)。 */
     configLocalDir: string;
-    /** 壳配置主目录(getClaudeConfigHomeDir());也作 SEMA_CONFIG_DIR 注入对齐路径。 */
     configHome: string;
-    /** per-spawn 随机服务令牌(uuid),SERVICE_AUTH_TOKENS="<uuid>=system:shell-local";不落 .env。 */
     serviceAuthToken: string;
-    /** 引擎入口文件绝对路径(ai-agent-service/dist/main.js,缺则回退 tsx src/main.ts)。 */
     engineEntry: string;
-    /** 引擎入口的工作目录(ai-agent-service 根)。 */
     engineCwd: string;
-    /** 引擎日志输出文件(<configHome>/engine-<pid>.log;pid spawn 后回填,先用占位)。 */
     logPath: string;
 }

package/dist/types/engineState.js

@@ -1,17 +1 @@
-/**
- * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/types/engineState.ts 逐字搬入(纯类型,零运行时;壳侧改 re-export)。
- * ⚠️ 归属注记:`EngineInstance`/`TOCConfig` 描述的是**宿主**职责(spawn/端口/日志路径),逻辑本体
- * (engineLifecycleManager)按设计稿 §2.4.2-A 留 TUI;搬进本包的只是**形状**,让 desktop 宿主与
- * TUI 宿主共用同一套 /health 与 engine.port 契约类型,不代表生命周期逻辑下沉。
- */
-/**
- * TOC 一体化 (TP-A-P0-IMPL Step 5) — Engine Lifecycle 状态类型。
- *
- * 壳一体化起本地引擎(ai-agent-service file 模式),对用户透明,体验等同 CC 单进程。
- * 本文件只定义跨 lifecycle 流转的纯数据形状,不含逻辑(逻辑在 engineLifecycleManager.ts)。
- *
- * 真相源契约:engine.port 文件是壳↔引擎的「当前活引擎」单一发现锚点(flock 串行化写,
- * write-temp+fsync+mv 原子落盘)。HealthResponse 字段与引擎 server.ts:645-660 /health 逐字对齐
- * (W2 同约定实现):instanceId/dataRoot/configHash/pid —— 壳据此判断「连对引擎」防陈旧 port 连错。
- */
 export {};

package/dist/ultracodeWireCaps.d.ts

@@ -1,87 +1,12 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/ultracodeWireCaps.ts 逐字搬入(零依赖;🔴 模块级 ultracodePreset 是 sticky 单实例态,写口 setUltracodePreset 与读口 ultracodeForWire 必须同实例)。
- */
-/**
- * src/sema/ultracodeWireCaps.ts — the shell's TWO opt-in sources for the CC-parity `settings.ultracode` PRESET,
- * projected onto `TaskRequest.settings.ultracode` (a typed boolean the SERVICE — ai-agent-service 1.48.0 — reads
- * and EXPANDS to `thinking:"max"` + `selfOrchestration:true`; both core's existing orthogonal axes, fail-closed
- * gates unchanged). design/111 (core/search AI 2026-06-30): ultracode is a STANDALONE settings boolean folding
- * "max thinking × workflow orchestration", surfaced in sema as the top notch of the `/effort` dial.
- *
- * Two sources, ONE structured-spec output (`settings.ultracode:true` — never prompt text):
- *
- *  ① L2 dial preset (STICKY): the `/effort ultracode` pick. The effort dial COERCES the reasoning axis to `xhigh`
- *     (overrides/effort.tsx executeEffortSema — "ultracode runs at xhigh effort"), which would LOSE the
- *     orchestration axis. So the dial separately latches this module-level preset: ON when `ultracode` is picked,
- *     OFF when any OTHER effort level is picked (a sticky session setting, like CC's settings.ultracode boolean).
- *
- *  ② L3 keyword (PER-TURN): a client-side scan of the REAL human turn input for the literal word "ultracode".
- *     🔴 RED LINE (design/111 L3, the ONLY injection risk): scan ONLY the human's current-turn submission, BEFORE
- *     any untrusted content (tool results / file reads / web / subagent / MCP) is concatenated. NEVER scan the
- *     assembled prompt server-side — a malicious file containing "ultracode" would be a privilege-escalation
- *     injection. The keyword is a UX convenience switch, NOT a security decision point: privilege STILL passes the
- *     service's fail-closed per-principal `allowWorkflows` gate (core deliberately refuses prompt scanning,
- *     prepare-task.ts:1612 — that boundary is correct). The output is a STRUCTURED spec (the boolean), never
- *     injected prompt text.
- *
- * Both sources are OR'd live-side by `toTaskRequest`; the SAME `SEMA_LIVE_BASEURL` gate the other capability wires
- * use keeps the mock request shape unchanged (the stamp IS the opt-in; absent ⇒ the engine never expands ultracode).
- *
- * The PRESET state is module-level (mirrors seamQuery's seam* injectors): the dial (a React override) latches it,
- * the seam reads it. The KEYWORD scan is a PURE function (caller passes the human input) so it bundles + unit-tests
- * without React/AppState.
- */
 import { type EnvLike } from './hostEnv.js';
-/** Latch the dial preset. `effort.tsx` calls this whenever an effort level is APPLIED: `true` for the `ultracode`
- *  notch, `false` for every other level (so switching the dial OFF ultracode clears the workflow-orchestration axis
- *  while the reasoning axis follows the picked level). */
 export declare function setUltracodePreset(on: boolean): void;
-/** Read the sticky dial preset (the L2 source). */
 export declare function getUltracodePreset(): boolean;
-/** Test/boot reset — clears the latched preset (e.g. a fresh session). */
 export declare function _resetUltracodePreset(): void;
-/**
- * L3 keyword source: `true` iff the REAL human turn input contains the "ultracode" keyword, else `undefined`.
- * 🔴 The caller MUST pass ONLY the human's current-turn submission (seamQuery's `objective`, derived from the
- * projectable user message) — NOT any assembled/untrusted content. Returns `true | undefined` (never `false`) to
- * mirror the strict additive-stamp discipline of the other wire caps (a stamped `false` would needlessly change
- * the default request shape).
- */
 export declare function ultracodeFromInput(humanInput: string | undefined): true | undefined;
-/**
- * Combine the two sources into the structured spec the seam stamps. `true` when EITHER the sticky dial preset is on
- * OR the human's current-turn input contains the keyword; otherwise `undefined` (⇒ no stamp ⇒ default behaviour).
- * Returns `true | undefined` so the seam can spread `...(ultracode ? { ultracode } : {})` without changing the
- * default request shape. The CALLER gates this to LIVE mode (mock parity).
- */
 export declare function ultracodeForRequest(humanInput: string | undefined): true | undefined;
 export declare function workflowFromInput(humanInput: string | undefined): true | undefined;
-/**
- * [1052]① 收官形(clay 裁 B 的 core deferred 机制件,cli 接线半场):Workflow「全局默认开但不暴露」——
- * 未命中激活源的 TaskRequest 带 `deferTools:["Workflow"]`(core 1.314 对已挂载工具做 design/36 延迟披露:
- * 占位符上 wire、schema 字节撤出缓存前缀、ToolSearch 可激活=中途激活通路);命中任一激活源 ⇒ `undefined`
- * (不 defer=名字+schema 全量上 wire):
- *   a) 用户当轮说 "workflow"(workflowFromInput,只扫真人输入);
- *   b) "ultracode" 关键词(L3,同一红线);
- *   c) `/effort ultracode` sticky dial(L2 preset)。
- * CALLER 前置两门:live 门(mock 形不变)+ selfOrchestration stamp 存在(opt-out 时 Workflow 根本不挂载,
- * defer 无意义)。前缀缓存注记:defer↔不 defer 的翻转只发生在真人激活当轮,与 CC 209 ToolSearch materialize
- * 同一形——非激活轮的前缀指纹稳定([1044]② clay 硬约束 ii 的解)。
- */
 export declare function workflowDeferForRequest(humanInput: string | undefined, env?: EnvLike): ['Workflow'] | undefined;
-/** [1077]④ 低频工具惰性注入:`SEMA_DEFER_TOOLS=<csv>`(wire 名)追加进 deferTools(core 1.314
- *  延迟披露腿)。**缺省翻转已裁(clay [1212]⑤,2026-07-19)**:九件低频工具缺省 defer——判决数=
- *  -2,484 tok/首调用+多轮 gate 零行为退化;defer≠禁用(占位符在,模型 ToolSearch 随取)。
- *  逃生门:`SEMA_DEFER_LOWFREQ=0/false/no/off` 关缺省名单(九件恢复全量上前缀)。 */
 export declare const DEFER_TOOLS_ENV: "SEMA_DEFER_TOOLS";
 export declare const DEFER_LOWFREQ_ENV: "SEMA_DEFER_LOWFREQ";
-/** clay 裁定的缺省惰性名单([1076]④ 评测九件原单,[1090]② 判决数)。 */
 export declare const DEFAULT_LOWFREQ_DEFER: readonly string[];
-/**
- * The FULL deferTools list for a request: the Workflow default-defer lane (activation sources, see
- * {@link workflowDeferForRequest}) + the DEFAULT low-frequency list (clay [1212]⑤, opt-out via
- * SEMA_DEFER_LOWFREQ) + the SEMA_DEFER_TOOLS extra list, deduped. An activation hit removes ONLY
- * Workflow (the user asked for it by name); the other lanes are source-independent. Empty ⇒
- * `undefined` (no stamp, request shape unchanged).
- */
 export declare function deferToolsForRequest(humanInput: string | undefined, env?: EnvLike): string[] | undefined;