@sema-agent/client-core 0.62.1 → 0.63.0

package/dist/toolRoster.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 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` 等词表的属主都是引擎,一律**原样透传**,不窄读成
+ * 枚举 —— 那会在引擎加词当天把一份真名册判没。
+ */
+/** 一只工具的**路径目标**(引擎的 `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;
+    summaryParams?: readonly string[];
+    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;
+    };
+    contract?: {
+        contractId: string;
+        implementationRevision?: string;
+    };
+    shapeDigest?: string;
+    wireSchemaDigest?: string;
+    /** 卡的身份。**同名不同身的两行按两只 id 去重,不按 `name`**。 */
+    cardId?: string;
+    capabilityId?: string;
+    /** `read` / `write` / `idempotent`;开集读。 */
+    effect?: string;
+    egress?: boolean;
+    /** `never` / `maybe` / `always`;开集读。 */
+    irreversibility?: string;
+    contentOrigin?: string;
+    family?: string;
+    pathTarget?: ToolRosterPathTargetView;
+    renderHints?: ToolRosterRenderHintsView;
+    ruleFace?: {
+        primaryParams?: readonly string[];
+        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;
+    family?: string;
+    userFacingName?: string;
+    activity?: string;
+    approvalCard?: string;
+    summaryParams?: readonly string[];
+    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 就是比不出来,而
+ *    「比不出来」不许被读成「对上了」。
+ * 🔴 帧本身判不出形 => **什么都没发生**:原样交回入参那一份(不清空 —— 清空会把一次读不懂的帧
+ *    变成一次「所有工具都没挂」)。
+ */
+export declare function applyToolRosterDelta(held: ToolRosterView | undefined, delta: unknown): ToolRosterDeltaApplication;

package/dist/toolRoster.js

@@ -0,0 +1,236 @@
+/**
+ * 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` 等词表的属主都是引擎,一律**原样透传**,不窄读成
+ * 枚举 —— 那会在引擎加词当天把一份真名册判没。
+ */
+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);
+    if (o === undefined)
+        return undefined;
+    const param = str(o.param);
+    const access = str(o.access);
+    // 两必填键读不出 => 这张面不成形。**只丢面,不丢行**(面不是身份)。
+    if (param === undefined || access === undefined)
+        return undefined;
+    const aliases = strArr(o.aliases);
+    const base = str(o.base);
+    const absent = str(o.absent);
+    const patternParam = str(o.patternParam);
+    return {
+        param,
+        access,
+        ...(aliases !== undefined ? { aliases } : {}),
+        ...(o.skillScopeEligible === true ? { skillScopeEligible: true } : {}),
+        ...(base !== undefined ? { base } : {}),
+        ...(absent !== undefined ? { absent } : {}),
+        ...(patternParam !== undefined ? { patternParam } : {}),
+    };
+}
+function readEntry(raw) {
+    const o = obj(raw);
+    if (o === undefined)
+        return undefined;
+    const name = str(o.name);
+    const source = str(o.source);
+    // 身份两键读不出 => 这一行不成形 => 由调用方把**整只名册**判没(见模块顶注)。
+    if (name === undefined || source === undefined)
+        return undefined;
+    const originRaw = obj(o.origin);
+    const peer = originRaw !== undefined ? str(originRaw.peer) : undefined;
+    const declaredBy = originRaw !== undefined ? str(originRaw.declaredBy) : undefined;
+    const contractRaw = obj(o.contract);
+    const contractId = contractRaw !== undefined ? str(contractRaw.contractId) : undefined;
+    const implementationRevision = contractRaw !== undefined ? str(contractRaw.implementationRevision) : undefined;
+    const hintsRaw = obj(o.renderHints);
+    const ruleFaceRaw = obj(o.ruleFace);
+    return {
+        name,
+        source,
+        ...(strArr(o.aliases) !== undefined ? { aliases: strArr(o.aliases) } : {}),
+        ...(peer !== undefined
+            ? { origin: { peer, ...(declaredBy !== undefined ? { declaredBy } : {}) } }
+            : {}),
+        ...(contractId !== undefined
+            ? { contract: { contractId, ...(implementationRevision !== undefined ? { implementationRevision } : {}) } }
+            : {}),
+        ...(str(o.shapeDigest) !== undefined ? { shapeDigest: str(o.shapeDigest) } : {}),
+        ...(str(o.wireSchemaDigest) !== undefined ? { wireSchemaDigest: str(o.wireSchemaDigest) } : {}),
+        ...(str(o.cardId) !== undefined ? { cardId: str(o.cardId) } : {}),
+        ...(str(o.capabilityId) !== undefined ? { capabilityId: str(o.capabilityId) } : {}),
+        ...(str(o.effect) !== undefined ? { effect: str(o.effect) } : {}),
+        ...(typeof o.egress === 'boolean' ? { egress: o.egress } : {}),
+        ...(str(o.irreversibility) !== undefined ? { irreversibility: str(o.irreversibility) } : {}),
+        ...(str(o.contentOrigin) !== undefined ? { contentOrigin: str(o.contentOrigin) } : {}),
+        ...(str(o.family) !== undefined ? { family: str(o.family) } : {}),
+        ...(readPathTarget(o.pathTarget) !== undefined
+            ? { pathTarget: readPathTarget(o.pathTarget) }
+            : {}),
+        ...(hintsRaw !== undefined
+            ? {
+                renderHints: {
+                    ...(str(hintsRaw.userFacingName) !== undefined ? { userFacingName: str(hintsRaw.userFacingName) } : {}),
+                    ...(str(hintsRaw.activity) !== undefined ? { activity: str(hintsRaw.activity) } : {}),
+                    ...(strArr(hintsRaw.summaryParams) !== undefined ? { summaryParams: strArr(hintsRaw.summaryParams) } : {}),
+                    ...(strArr(hintsRaw.resultCards) !== undefined ? { resultCards: strArr(hintsRaw.resultCards) } : {}),
+                    ...(str(hintsRaw.approvalCard) !== undefined ? { approvalCard: str(hintsRaw.approvalCard) } : {}),
+                },
+            }
+            : {}),
+        ...(ruleFaceRaw !== undefined
+            ? {
+                ruleFace: {
+                    ...(strArr(ruleFaceRaw.primaryParams) !== undefined ? { primaryParams: strArr(ruleFaceRaw.primaryParams) } : {}),
+                    ...(strArr(ruleFaceRaw.params) !== undefined ? { params: strArr(ruleFaceRaw.params) } : {}),
+                },
+            }
+            : {}),
+    };
+}
+/** 一只**已经剥出来**的名册体(不带 `tools` 包层)→ 视图;坏形 => `undefined`。 */
+function readRoster(raw) {
+    const o = obj(raw);
+    if (o === undefined)
+        return undefined;
+    const digest = typeof o.digest === 'string' && DIGEST_RE.test(o.digest) ? o.digest : undefined;
+    if (digest === undefined)
+        return undefined;
+    if (!Array.isArray(o.entries))
+        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);
+    }
+    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)
+        return undefined;
+    if (!('tools' in o))
+        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)
+        return undefined;
+    return {
+        name: e.name,
+        source: e.source,
+        ...(e.family !== undefined ? { family: e.family } : {}),
+        ...(e.renderHints?.userFacingName !== undefined ? { userFacingName: e.renderHints.userFacingName } : {}),
+        ...(e.renderHints?.activity !== undefined ? { activity: e.renderHints.activity } : {}),
+        ...(e.renderHints?.approvalCard !== undefined ? { approvalCard: e.renderHints.approvalCard } : {}),
+        ...(e.renderHints?.summaryParams !== undefined ? { summaryParams: e.renderHints.summaryParams } : {}),
+        ...(e.effect !== undefined ? { effect: e.effect } : {}),
+        ...(e.egress !== undefined ? { egress: e.egress } : {}),
+        ...(e.irreversibility !== undefined ? { irreversibility: e.irreversibility } : {}),
+        ...(e.pathTarget?.param !== undefined ? { pathTargetParam: e.pathTarget.param } : {}),
+        ...(e.origin?.peer !== undefined ? { peer: e.origin.peer } : {}),
+        ...(e.cardId !== undefined ? { cardId: e.cardId } : {}),
+        ...(e.capabilityId !== undefined ? { capabilityId: e.capabilityId } : {}),
+    };
+}
+function readSummary(raw) {
+    const o = obj(raw);
+    if (o === undefined)
+        return undefined;
+    const added = strArr(o.added);
+    const removed = strArr(o.removed);
+    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 };
+}
+/**
+ * `tool_roster_delta` → 新的持有状态。**纯函数**(不改入参)。
+ *
+ * 🔴 `fromDigest` 对不上**不是拒绝**(契约里唯一的硬话):携带的整只名册无论如何都是新状态,
+ *    只有 `summary` 变得不可用。拒绝换会让消费端永远抱着一份过期名册 —— 比一次 skew 坏得多。
+ * 🔴 手上**没有**名册(首帧就是 delta)同样算 `skew`:没有可比的 digest 就是比不出来,而
+ *    「比不出来」不许被读成「对上了」。
+ * 🔴 帧本身判不出形 => **什么都没发生**:原样交回入参那一份(不清空 —— 清空会把一次读不懂的帧
+ *    变成一次「所有工具都没挂」)。
+ */
+export function applyToolRosterDelta(held, delta) {
+    const d = obj(delta);
+    const next = d !== undefined ? readRoster(d.roster) : undefined;
+    if (d === undefined || next === undefined || typeof d.fromDigest !== 'string') {
+        return { roster: held, applied: false, skew: false };
+    }
+    const skew = held === undefined || held.digest !== d.fromDigest;
+    const summary = skew ? undefined : readSummary(d.summary);
+    return {
+        roster: next,
+        applied: true,
+        skew,
+        ...(summary !== undefined ? { summary } : {}),
+    };
+}