@sema-agent/client-core 0.75.1 → 0.76.1

package/dist/index.d.ts

@@ -140,6 +140,7 @@ export * from './steering.js';
 export * from './diagnostics.js';
 export * from './retryStatus.js';
 export * from './sessionMemoryStatus.js';
+export * from './memorySpecWire.js';
 export * from './adapt.js';
 export * from './adapt/textSegmentAuthority.js';
 export * from './engineHttpTools.js';
@@ -157,6 +158,11 @@ export * from './writeProtectionCapability.js';
 export * from './webSearchBackendCapability.js';
 export * from './executionLaneCapability.js';
 export * from './approvalsStreamLiveCapability.js';
+export * from './peerLaneCapability.js';
+export * from './permissionRulesWriteCapability.js';
+export * from './memoryComplianceCapability.js';
+export * from './memoryOriginCapability.js';
+export * from './memoryEntriesWire.js';
 export * from './deviceExecutorManagementCapability.js';
 export * from './mcpReconnect.js';
 export * from './leaderConflict.js';
@@ -165,6 +171,7 @@ export * from './runCancelContext.js';
 export * from './argvFlagValue.js';
 export * from './readFacePosture.js';
 export * from './mcpPanel.js';
+export * from './mcpLiveness.js';
 export * from './effectiveFacts.js';
 export * from './gateOutcome.js';
 export * from './postureKnob.js';
@@ -257,6 +264,7 @@ export * from './model/providerPresets.js';
 export * from './hitl/hitlBridge.js';
 export * from './hitl/suspendedReopen.js';
 export * from './hitl/approvalOutcomeNote.js';
+export * from './hitl/approvalResolution.js';
 export { toolEndOutputText, ENGINE_ABORT_TOOL_RESULT } from './hitl/frameRouter.js';
 export { isAskTool } from './hitl/frameRouter.js';
 export * from './hitl/hitlHostSurface.js';

package/dist/index.js

@@ -151,6 +151,7 @@ export * from './retryStatus.js';
 // 把「部署没这个面」说成「你这个会话不存在」;② 五键缺席语义**逐键不同**,健康会话上就有两键
 // 合法缺席,一律读成「没有/关着/0」就是对用户下一个证不出的断言。
 export * from './sessionMemoryStatus.js';
+export * from './memorySpecWire.js';
 export * from './adapt.js';
 // ── L-318(0.68.2):`text_end` 权威段替换的**判决单源** + print 形车道的段账状态机 ──────────
 // 修前这套六形判据有两份实现:本包 `adapt/textStream.replaceAnswerSegment`(交互车道)与 cli
@@ -193,6 +194,23 @@ export * from './executionLaneCapability.js';
 // · approvalsStreamLiveCapability(0.73.3 CC-61):capabilities.approvalsStreamLive 四态读面 + feed 消费方「要不要靠对账拉」的判据单源。
 export * from './approvalsStreamLiveCapability.js';
 // · deviceExecutorManagementCapability(0.74.2 CC-69):capabilities.deviceExecutor.management 四态读面 + 管理动词可用性判据单源。
+//   各只能力位读器的 tee / 读口 / 失效口 / 测试钩共用 `engineCapReader`(0.76.1 CC-75;包内叶,不出 barrel)。
+// · peerLaneCapability(0.76.1 CC-102):capabilities.peerLane 四态读面 —— 键缺席 = 老 worker 判不出、`false` = 明确没挂跨会话目录席(正面事实);
+//   非 HTTP 面,消费方式是渲染/预期,不 gate 某个动词。「要不要露出跨会话入口」三态判据单源 peerLaneAvailable。
+export * from './peerLaneCapability.js';
+// · permissionRulesWriteCapability(0.76.1 CC-102):capabilities.permissionRulesWrite 四态读面 —— 键缺席 = 这份二进制比单步写口老(藏入口)、
+//   键在场按值判「这次调用够不够得着」(与撤销面那只部署级存在性信号刻意不同源,别互相套用读法)。布尔便利口 permissionRulesWriteAvailable 是本位唯一派生点。
+export * from './permissionRulesWriteCapability.js';
+// · memoryComplianceCapability(0.76.1 CC-97a):capabilities.memoryCompliance 四态读面(出处问询 / 抹除两口)——
+//   键缺席 = 老引擎判不出、`false` = 明确的否、畸形删格绝不折否;两口可用性三态判据 + 记忆治理面 501 码单源。
+export * from './memoryComplianceCapability.js';
+// · memoryOriginCapability(0.76.1 CC-97a):capabilities.memoryOrigin 四态读面(外源标记人面三口)——
+//   与上一只**同判据不同位**,刻意各持一张表、不合并(引擎刻意不合并,今天恒同值也不许折)。
+export * from './memoryOriginCapability.js';
+// · memoryEntriesWire(0.76.1 CC-97a):记忆条目面三个 200 回体的窄读口(导出条目行 / 抹除证明 / 外源清标回执)——
+//   逐行窄读三向边界(空数组 = 真 0 / 非空全坏 = malformed / 半坏 = present + dropped)、`historyUnknown` 三态原样过境、
+//   「抹了 0 条」与「200 空体」与「读不懂」判成三回事,以及「空答绝不读作本店干净」的代码落点(判词口的 originAware 必填形参)。
+export * from './memoryEntriesWire.js';
 export * from './deviceExecutorManagementCapability.js';
 // S-381 / core 7.22.0 #857(0.72.9 CC-30;server ≥7.85.0,sdk 尚未声明):会话内 MCP re-dial 的消费口 —— 200 三态按 outcome 分形读、
 // unsupported 恒五键、名册按 toolNames 在场性、失败按 errorCode 分诊、「重连 = 一次交易」措辞单源;能力位 mcpReconnect 三态读。
@@ -213,6 +231,9 @@ export * from './argvFlagValue.js';
 export * from './readFacePosture.js';
 // CC-03(0.68.2):`GET /v1/sessions/:id/mcp` 面板体的防御读视图 + lastLegMcp 一行措辞铸点(三端共用)。
 export * from './mcpPanel.js';
+// CC-36(0.76.1):引擎托管 MCP 服务器的**活性观察**(`wiring_manifest.mcp[].liveness`)结构读口 ——
+// 三词闭集词表 + 行级三向读数(缺席 / 在场读不出 / 一次观察)+ 腿级四读数判词与它的唯一措辞铸点。
+export * from './mcpLiveness.js';
 export * from './effectiveFacts.js';
 export * from './gateOutcome.js';
 // 0.63.0(sdk 8.8.0 / engine ≥7.67.0 / S-178):`serverGates` 三根 posture 旋钮的读数窄读器
@@ -446,6 +467,8 @@ export * from './hitl/hitlBridge.js';
 export * from './hitl/suspendedReopen.js';
 // 0.74.5 CC-88:流内帧腿审批结局 → 宿主便签的单源映射(三端手拼退役)
 export * from './hitl/approvalOutcomeNote.js';
+// CC-77 ①:「一次审批决断最后怎么了」的单源判别联合 + 唯一映射口(additive;既有结局型面一字不动)
+export * from './hitl/approvalResolution.js';
 // [C93] P0 直讨(0.17.1):toolEndOutputText 单一真源导出——web/desktop 被点名「两端务必接」的
 // 6.0.0 output content-block 归一,此前 frameRouter 内私有,两端手抄=漂移温床。frameRouter 只
 // 挑名导出这一件(整星导出会把路由内部面全泄进公面)。
@@ -498,7 +521,8 @@ export * from './hitl/resumeRunningCard.js';
 //   RulesFailure 处置分类(404 两支绝不共用一格)、keyset 翻页收口(游标失效重列 + 页数硬帽)、
 //   skipped.reason 前缀分类、persist-ack 三态读口 —— 读口与 `readToolApprovalRespondAck`
 //   **合成一处**(census top-08 #1 的双份台账收口本体);CC settings 三层 fs 读、SDK facade
-//   装配、通知呈现留宿主。
+//   装配、通知呈现留宿主。0.76.1 CC-102 补 persistedRulesWriteAvailable:单步写入口便利口,
+//   只派生自 permissionRulesWriteCapability 的四态读数,与撤销面那只合取式刻意不同源。
 // · localAllowRule:parseLocalAllowRule 窄化五步(①整工具拒/②工具名对齐/③字面锚/⑤裸解释器
 //   前缀/⑤b canonical 危险谓词)骨架;危险谓词与规则语法经 `LocalAllowRuleDeps` 注入
 //   (parkOwnership deps 同形)—— 谓词表本体(BARE_SHELL_PREFIXES / dangerousPatterns)留宿主,

package/dist/mcpLiveness.d.ts

@@ -0,0 +1,179 @@
+/**
+ * mcpLiveness.ts — 引擎托管的 MCP 服务器**活性观察**(`wiring_manifest.mcp[].liveness`)的三端共用
+ * **结构读口** + 三词闭集词表 + 腿级判词(CC-36,0.76.1)。引擎内核自 7.24.3 起铸这一格,服务端的转发层自 7.91.2 起把它送上 wire ——
+ * 更老的服务端上这一格**恒缺席**(读数 = `indeterminate`,正是缺席语义要兜的那一档,不是故障)。
+ *
+ * ── 这一格答的是哪一个问题 ────────────────────────────────────────────────────────────────────
+ * 「这台服务器**还够得着吗**」。引擎不为它发任何自己的流量 —— 每条记录都是那条腿**已经做过的工作**
+ * (拨号、re-dial、传输关闭、一次发现传输没了的请求)顺带盖的章,自带盖章时刻 `observedAt`。
+ * ⇒ 它是**每条腿的一张快照**,不是心跳、不是轮询、更不是「此刻」。
+ *
+ * 🔴 **同一行上的三个位各说各的,谁都不许顶替谁、不许互相校验、不许据其一推另一个**:
+ *  · `status`(申报 / 连接时判决)—— 这条腿**拨号那一刻**的判词,引擎**有意冻结**它(服务器中途死了这一格
+ *    仍读 `connected`);
+ *  · re-dial 回执的 `outcome`(动作判决)—— **一次动作**的判词,过去式;
+ *  · `liveness`(本件)—— 连接层**最后学到的那件事**,自带时戳。
+ *  最直白的一格:`status: 'failed'` 与 `liveness.state: 'reachable'` **同一行并存是真行** —— 服务器答了
+ *  握手、答的是协议错(**活着,且配错了**)。判据是「两格都在」,不是「两格一致」。
+ *
+ * ── 🔴 四种读数(三个词 + 缺席),缺席**不是**其中任何一个词 ────────────────────────────────────
+ *  · `reachable`   —— **一次交换完成了**(连上并列出了,或服务器自己答了 —— MCP 级的拒绝**也是答**,所以
+ *    它证明够得着,即便那次调用失败);
+ *  · `unreachable` —— 试过,丢在传输或时钟上(拒连 / 重置 / 关闭 / 起不来 / 超时);
+ *  · `unknown`     —— **试过,而回来的东西答不了这个问题**(服务器前面那台网关写的 HTTP 状态、非 MCP 载荷、
+ *    没有结构的抛出值)。它是一句**更强**的断言:引擎看了,看不出来。
+ *  · **缺席 = indeterminate** —— 这一行**没有可用的观察记录**。四个来源在 wire 上**同形**,消费端分不出也
+ *    不需要分:① 这条腿没走到那台服务器(`status: 'skipped'`);② 那份声明从来没被拨过(`invalid_config`);
+ *    ③ 这是一条老引擎 / 老服务端的帧;④ 上游判形没过、那一格被摘掉了。
+ *    🔴 **不许据缺席反推「这条腿拨没拨过号」**,也不许把它折进 `unknown`、折成「健康」、折成「关着」。
+ *    这四句话在本包里是四句不同的话,任何折叠都是「把不知道说成没有 / 说成好着呢」的变体。
+ *
+ * ── 为什么是结构读(不靠型面) ─────────────────────────────────────────────────────────────────
+ * 本包 peer 地板上的 wire 型面里**还没有这一格**(键形是引擎侧先出、型面后出的常态)。所以本件按契约
+ * **结构读**:从 `unknown` 起按键路径窄化,判据自带(见下),**不抬 peer 地板、不等型面**。安全性不靠型
+ * 而靠三条:① 三词按**闭集恰等**判,认不得的词一律畸形(词表属主在上游,本包**不放宽**成开集 —— 放宽了
+ * 就会把一个没人定义过的词当成一句真话往屏上送);② `observedAt` 按**有限数**判;③ 判形没过 ⇒ 这一格
+ * 摘掉、那一行照读(与上游同判),而摘掉的**理由**留在 {@link McpLivenessCell} 的 `unreadable` 臂上,
+ * 与「引擎没报」分开。型面出键那天由包侧门逼一次显式处置(见 `run-mcp-liveness-test.mjs` 的上游见证臂)。
+ *
+ * ── `errorCode` 只随 `unreachable` ────────────────────────────────────────────────────────────
+ * 它是那句话的**注脚**(为什么够不着),不是那句话本身。上游的单点铸造保证它**只随 `unreachable`** 出现,
+ * 理由逐字可查:`unknown` 的全部意思就是「那次失败并没有决定可达性」,把失败类别挂在那个词上等于请消费端
+ * 拿一份说明不了可达性的证据去决定下一步动作。⇒ 本读口在**非 `unreachable`** 臂上**丢掉这只注脚**
+ * (整格仍在、`state` 仍读):去掉的恰是上游点名要防的那条误读路,而 `state` 那句话一个字没动。
+ * 注脚自己形坏(空串 / 非串)同样**只丢它自己不拆整格** —— 代价如实:此时读到的是「够不着,原因没说」,
+ * **不是**「这条记录坏了」。词按**开集**读(十词闭集的属主在上游,抄一张会把新词吞成缺席)。
+ */
+/**
+ * 活性词的**三词闭集**(与上游同序:能完成交换 / 完不成 / 答不了)。
+ *
+ * 🔴 **它只有三个词**。腿级判词的第四个读数 `indeterminate`(见 {@link McpLegLivenessReading})**不是**
+ *    本表成员,也绝不许被加进来:本表是**上游的词表**,那第四个读数是**缺席**在本包里的名字。
+ * 🔴 消费端按本表写的 `switch` 判**恰等**(不 trim、不折大小写、不按前缀猜);上游加词的唯一处置是
+ *    **本表同批加一格 + 补一条读数格**,而不是在消费点放宽判据。
+ */
+export declare const MCP_LIVENESS_STATES: readonly ["reachable", "unreachable", "unknown"];
+/** {@link MCP_LIVENESS_STATES} 的三个词 —— **由那张表派生**,不另手写一份(两份手写迟早各说一套;本包不依赖上游型面,见文件顶注)。 */
+export type McpLivenessState = (typeof MCP_LIVENESS_STATES)[number];
+/** 一台服务器的**一次**活性观察(读视图;逐键挑,开集键不透传)。 */
+export interface McpLivenessView {
+    /** 三词闭集(见 {@link MCP_LIVENESS_STATES});认不得的词不到这里(整格判畸形)。 */
+    state: McpLivenessState;
+    /** 盖章时刻(epoch 毫秒,有限数)。🔴 它是**那条腿**的观察时刻 —— 不是「此刻」,也不与面板的
+     *  `asOf` 同源,两者**不比**。 */
+    observedAt: number;
+    /** 够不着的**类别注脚**(开集,上游十词;**只随 `unreachable`** 在场)。缺席 = 原因没说,
+     *  **不是**「这条记录坏了」,更不是第四态。 */
+    errorCode?: string;
+}
+/**
+ * 一行上这一格的三向读数(**缺席 / 在场读不出 / 一次观察**三句话分开,任何两句都不折)。
+ *  · `absent`      —— 键不在场 = 没有可用的观察记录(四源同形,见文件顶注);
+ *  · `unreadable`  —— 键**在场**而读不出(整格不是对象 / 词出闭集 / `observedAt` 非有限数)。它与 `absent`
+ *    **不是**一句话:「引擎送了一份我读不懂的」与「引擎没报」对运维是两件事;
+ *  · `observation` —— 读得出的那一次观察。
+ */
+export type McpLivenessCell = {
+    kind: 'absent';
+} | {
+    kind: 'unreadable';
+} | {
+    kind: 'observation';
+    liveness: McpLivenessView;
+};
+/**
+ * 从**一行** MCP 名册条目里读这一格(结构读;单一铸点,别在消费点再写一遍判据)。
+ *
+ * 缺席答什么:`{kind:'absent'}` —— 判据是**自有键在不在**(`Object.hasOwn`),不按真值判。原型链上的
+ *   同名键**永远不会**上 wire,拿它当在场 = 把本进程对象的形状当成引擎说过的话;`null` / `undefined`
+ *   显式在场是**坏形**(走 `unreadable`),不是缺席形。
+ * 畸形答什么:`{kind:'unreadable'}` —— 整行不是对象、整格不是对象(含 `null` / 数组 / 串 / 数)、
+ *   `state` 不是三词之一(含空串、近形拼法、大小写变体)、`observedAt` 非有限数(含缺席 / 串 / `NaN`)。
+ *   🔴 **绝不**折成 `{kind:'absent'}`(会把「送来一份读不懂的」说成「引擎没报」),更**绝不**折成
+ *   `reachable` 或任何一个词(那是把读不出说成好着呢)。
+ * 为什么不折:这三句话在本包下游各对一种不同的处置 —— 缺席 = 什么都不渲(**不许**渲「一台都够不着」也
+ *   **不许**渲「都好着」);读不出 = 渲「这一格读不出」并让运维去看引擎版本与投影层;观察 = 渲那个词
+ *   + 那个时刻。折任何一对,渲出来的都是一句谁都没说过的话。
+ *
+ * ⚠️ 本口**只读这一格**:同行的 `status` / `errorCode` / `delivered` 一个字节都不碰,也不拿它们互相校验
+ *    (三个位各说各的,见文件顶注)。
+ */
+export declare function readMcpLiveness(row: unknown): McpLivenessCell;
+/**
+ * 腿级判词能吃的**最小行形**(结构型入参:凡带这两格的行视图都喂得进来,本口刻意不与某一张具体的
+ * 行视图型耦合 —— 活体腿的名册与面板上那条腿的回放是**同一只读器**的产物,判词也只该有一份)。
+ */
+export interface McpLivenessBearingRow {
+    /** 读得出的那次观察(缺席 = 这一行没有可用观察,或那一格读不出 —— 后者看 {@link livenessUnreadable})。 */
+    liveness?: McpLivenessView;
+    /** never false:这一行的活性格**在场而读不出**(与整格缺席不是一句话)。 */
+    livenessUnreadable?: true;
+}
+/**
+ * 一条腿的活性读数:三个词 + `indeterminate`(= 这条腿上**没有任何在场的活性格**)。
+ *
+ * 🔴 `indeterminate` **不是**上游词表的成员(词表仍是三词,见 {@link MCP_LIVENESS_STATES})——
+ *    它是**缺席**在本包里的名字,存在的全部理由就是不让缺席借用那三个词里的任何一个。
+ */
+export type McpLegLivenessReading = McpLivenessState | 'indeterminate';
+/** 一条腿的活性判词 + 它的两条诚实附注。 */
+export interface McpEngineLegHealth {
+    /** 判词(四读数;合成规则见 {@link mcpLivenessRollupOf})。 */
+    reading: McpLegLivenessReading;
+    /** never false:这条腿上**至少有一行**的活性格在场而读不出(判词为什么退到 `unknown` 的分辨位)。 */
+    unreadableCells?: true;
+    /**
+     * **判词那个词自己的**观察时刻(epoch 毫秒)= 带着决定 {@link reading} 那个词的那些行里**最新的**一格。
+     *
+     * 🔴 刻意**不是**「这条腿上所有观察里最新的那一格」(异源对抗复审 r1 [medium] 采纳,真病):一行在
+     *    t=1000 观察到 `unreachable`、另一行在 t=900000 观察到 `reachable` 时,跨行取最大会让「至少有一台
+     *    够不着」这句判词后面跟上一个**属于那次成功观察**的时刻 —— 运维会把一次旧故障读成刚刚又被确认一次。
+     *    ⇒ 时刻与判词**同源**:判词说 `unreachable`,这一格就是最新那次 `unreachable` 的时刻。
+     * 🔴 在场 iff 有**读得出的观察**决定了判词:`indeterminate` 上永不在场;判词是 `unknown` 而**只**由
+     *    「在场读不出」的格决定(没有一格读得出)时同样不在场 —— 读不出的格没有可用时刻,编一个就是造读数。
+     * ⚠️ 它是**那条腿**的观察时刻,不是「此刻」,也与面板的 materialize 时刻不同源、**不比**。
+     *    别的词那些行的时刻本口不铸(要逐行时刻就读行视图,不要从一个聚合值反推某一行)。
+     */
+    observedAt?: number;
+}
+/**
+ * 一条腿的名册 → 活性判词(**唯一铸点**:别在各端的状态行装配里另写一遍这套合成规则)。
+ *
+ * 合成规则 = **最坏事实优先**,不是多数票、不是取最新一格:
+ *  ① 任一行 `unreachable` ⇒ `unreachable`(有一台**可证**打不通时说「够得着」,就是把坏消息折成健康);
+ *  ② 否则任一行 `unknown` **或任一行的格读不出**(`livenessUnreadable`,或入参自带一格形坏的 `liveness`)
+ *     ⇒ `unknown`。在**腿**这一层,`unknown` 的意思恰是
+ *     「有观察在场而答不了这个问题」,而一份读不懂的格**同样答不了** ⇒ 🔴 **读不出的格绝不作可达的证据**
+ *     (否则「一行读不出 + 一行 reachable」会合成一句「这条腿够得着」,而那行读不出的格完全可能本来写着
+ *     `unreachable`)。为什么答不了,由 {@link McpEngineLegHealth.unreadableCells} 分辨;
+ *  ③ 否则任一行 `reachable` ⇒ `reachable`(其余行缺席 = 没观察,不是反证);
+ *  ④ 否则 ⇒ `indeterminate`。
+ *
+ * 缺席答什么:`{reading:'indeterminate'}` —— 三种入参落这一档且**刻意同形**:段读不出(`undefined`)、
+ *   零申报(`[]`,这条腿一台服务器都没申报 ⇒ 没有服务器就没有观察)、每一行的活性格都缺席(老引擎 /
+ *   都没走到)。要分「一台都没申报」与「有服务器但没报活性」,问名册本身(行数)或在场判词,**不要**
+ *   让本口替那一问答话。
+ * 畸形答什么:整个入参不是数组 ⇒ `indeterminate`;行本身不是对象 ⇒ **那一行什么都不贡献**(连「有没有
+ *   这一格」都没读出来,不替它认领一格);行在而那一格形坏 ⇒ 按上面的 ② 算「读不出」。**永不抛**。
+ * 为什么不折:`indeterminate` 与三个词之间**没有**默认值可回落 —— 回落到 `reachable` 是谎、回落到
+ *   `unreachable` 是恐慌、回落到 `unknown` 是替引擎认领一次它没做过的观察。
+ */
+export declare function mcpLivenessRollupOf(rows: readonly McpLivenessBearingRow[] | undefined): McpEngineLegHealth;
+/**
+ * 活性那一行措辞的**唯一铸点**(三端共用;别在各端的行装配里另写一遍)。
+ *
+ * 🔴 四句刻意逐字互异,且**没有一句**把 `indeterminate` 说成「都好着」或「一台都够不着」:
+ *  ① `reachable`     —— 上次交换完成了(这条腿的观察,带时刻);
+ *  ② `unreachable`   —— 至少一台**可证**够不着;
+ *  ③ `unknown`       —— 看过了,答不了(读不出的格同落这一档,附注多一句);
+ *  ③′ `unknown` 且**只**由读不出的格决定(判词无时刻 ∧ `unreadableCells`)—— 另一句:记录在场而**本端读不出**。
+ *     ③ 那句的主语是「回来的东西」(引擎看了、看不出来),③′ 的主语是本端的读器 —— 上游哪天加了第四个词,
+ *     老客户端落的正是 ③′;把它说成 ③ 等于替引擎认领一次它没做过的「看不出来」。
+ *  ④ `indeterminate` —— **没报**:这条腿上没有可用的观察记录,**不武断咎为引擎版本**(四源同形)。
+ * 🔴 句子里**不出现**服务器台数与「健康 / 正常」这类词:台数在名册上,而「健康」是本格答不了的问题
+ *    (它只答「还够得着吗」)。
+ * 🔴 句尾那个时刻**属于句子里那个判词**(见 {@link McpEngineLegHealth.observedAt}):说「至少有一台够不着」
+ *    时它是最新那次**够不着**的观察时刻,不是这条腿上任何一次观察的最大值 —— 否则一句旧故障的判词会跟上
+ *    一个属于别的词的新时刻,读起来像刚刚又确认了一次。时刻缺席时句子里就没有时刻,不编「刚刚」。
+ */
+export declare function mcpEngineLegHealthDetail(health: McpEngineLegHealth | undefined): string;

package/dist/mcpLiveness.js

@@ -0,0 +1,218 @@
+/**
+ * mcpLiveness.ts — 引擎托管的 MCP 服务器**活性观察**(`wiring_manifest.mcp[].liveness`)的三端共用
+ * **结构读口** + 三词闭集词表 + 腿级判词(CC-36,0.76.1)。引擎内核自 7.24.3 起铸这一格,服务端的转发层自 7.91.2 起把它送上 wire ——
+ * 更老的服务端上这一格**恒缺席**(读数 = `indeterminate`,正是缺席语义要兜的那一档,不是故障)。
+ *
+ * ── 这一格答的是哪一个问题 ────────────────────────────────────────────────────────────────────
+ * 「这台服务器**还够得着吗**」。引擎不为它发任何自己的流量 —— 每条记录都是那条腿**已经做过的工作**
+ * (拨号、re-dial、传输关闭、一次发现传输没了的请求)顺带盖的章,自带盖章时刻 `observedAt`。
+ * ⇒ 它是**每条腿的一张快照**,不是心跳、不是轮询、更不是「此刻」。
+ *
+ * 🔴 **同一行上的三个位各说各的,谁都不许顶替谁、不许互相校验、不许据其一推另一个**:
+ *  · `status`(申报 / 连接时判决)—— 这条腿**拨号那一刻**的判词,引擎**有意冻结**它(服务器中途死了这一格
+ *    仍读 `connected`);
+ *  · re-dial 回执的 `outcome`(动作判决)—— **一次动作**的判词,过去式;
+ *  · `liveness`(本件)—— 连接层**最后学到的那件事**,自带时戳。
+ *  最直白的一格:`status: 'failed'` 与 `liveness.state: 'reachable'` **同一行并存是真行** —— 服务器答了
+ *  握手、答的是协议错(**活着,且配错了**)。判据是「两格都在」,不是「两格一致」。
+ *
+ * ── 🔴 四种读数(三个词 + 缺席),缺席**不是**其中任何一个词 ────────────────────────────────────
+ *  · `reachable`   —— **一次交换完成了**(连上并列出了,或服务器自己答了 —— MCP 级的拒绝**也是答**,所以
+ *    它证明够得着,即便那次调用失败);
+ *  · `unreachable` —— 试过,丢在传输或时钟上(拒连 / 重置 / 关闭 / 起不来 / 超时);
+ *  · `unknown`     —— **试过,而回来的东西答不了这个问题**(服务器前面那台网关写的 HTTP 状态、非 MCP 载荷、
+ *    没有结构的抛出值)。它是一句**更强**的断言:引擎看了,看不出来。
+ *  · **缺席 = indeterminate** —— 这一行**没有可用的观察记录**。四个来源在 wire 上**同形**,消费端分不出也
+ *    不需要分:① 这条腿没走到那台服务器(`status: 'skipped'`);② 那份声明从来没被拨过(`invalid_config`);
+ *    ③ 这是一条老引擎 / 老服务端的帧;④ 上游判形没过、那一格被摘掉了。
+ *    🔴 **不许据缺席反推「这条腿拨没拨过号」**,也不许把它折进 `unknown`、折成「健康」、折成「关着」。
+ *    这四句话在本包里是四句不同的话,任何折叠都是「把不知道说成没有 / 说成好着呢」的变体。
+ *
+ * ── 为什么是结构读(不靠型面) ─────────────────────────────────────────────────────────────────
+ * 本包 peer 地板上的 wire 型面里**还没有这一格**(键形是引擎侧先出、型面后出的常态)。所以本件按契约
+ * **结构读**:从 `unknown` 起按键路径窄化,判据自带(见下),**不抬 peer 地板、不等型面**。安全性不靠型
+ * 而靠三条:① 三词按**闭集恰等**判,认不得的词一律畸形(词表属主在上游,本包**不放宽**成开集 —— 放宽了
+ * 就会把一个没人定义过的词当成一句真话往屏上送);② `observedAt` 按**有限数**判;③ 判形没过 ⇒ 这一格
+ * 摘掉、那一行照读(与上游同判),而摘掉的**理由**留在 {@link McpLivenessCell} 的 `unreadable` 臂上,
+ * 与「引擎没报」分开。型面出键那天由包侧门逼一次显式处置(见 `run-mcp-liveness-test.mjs` 的上游见证臂)。
+ *
+ * ── `errorCode` 只随 `unreachable` ────────────────────────────────────────────────────────────
+ * 它是那句话的**注脚**(为什么够不着),不是那句话本身。上游的单点铸造保证它**只随 `unreachable`** 出现,
+ * 理由逐字可查:`unknown` 的全部意思就是「那次失败并没有决定可达性」,把失败类别挂在那个词上等于请消费端
+ * 拿一份说明不了可达性的证据去决定下一步动作。⇒ 本读口在**非 `unreachable`** 臂上**丢掉这只注脚**
+ * (整格仍在、`state` 仍读):去掉的恰是上游点名要防的那条误读路,而 `state` 那句话一个字没动。
+ * 注脚自己形坏(空串 / 非串)同样**只丢它自己不拆整格** —— 代价如实:此时读到的是「够不着,原因没说」,
+ * **不是**「这条记录坏了」。词按**开集**读(十词闭集的属主在上游,抄一张会把新词吞成缺席)。
+ */
+/**
+ * 活性词的**三词闭集**(与上游同序:能完成交换 / 完不成 / 答不了)。
+ *
+ * 🔴 **它只有三个词**。腿级判词的第四个读数 `indeterminate`(见 {@link McpLegLivenessReading})**不是**
+ *    本表成员,也绝不许被加进来:本表是**上游的词表**,那第四个读数是**缺席**在本包里的名字。
+ * 🔴 消费端按本表写的 `switch` 判**恰等**(不 trim、不折大小写、不按前缀猜);上游加词的唯一处置是
+ *    **本表同批加一格 + 补一条读数格**,而不是在消费点放宽判据。
+ */
+export const MCP_LIVENESS_STATES = Object.freeze(['reachable', 'unreachable', 'unknown']);
+/** 三词闭集的**唯一**判据(恰等;行级读口与腿级判词共用这一只,不各写一遍)。 */
+const isLivenessState = (v) => typeof v === 'string' && MCP_LIVENESS_STATES.includes(v);
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * 从**一行** MCP 名册条目里读这一格(结构读;单一铸点,别在消费点再写一遍判据)。
+ *
+ * 缺席答什么:`{kind:'absent'}` —— 判据是**自有键在不在**(`Object.hasOwn`),不按真值判。原型链上的
+ *   同名键**永远不会**上 wire,拿它当在场 = 把本进程对象的形状当成引擎说过的话;`null` / `undefined`
+ *   显式在场是**坏形**(走 `unreadable`),不是缺席形。
+ * 畸形答什么:`{kind:'unreadable'}` —— 整行不是对象、整格不是对象(含 `null` / 数组 / 串 / 数)、
+ *   `state` 不是三词之一(含空串、近形拼法、大小写变体)、`observedAt` 非有限数(含缺席 / 串 / `NaN`)。
+ *   🔴 **绝不**折成 `{kind:'absent'}`(会把「送来一份读不懂的」说成「引擎没报」),更**绝不**折成
+ *   `reachable` 或任何一个词(那是把读不出说成好着呢)。
+ * 为什么不折:这三句话在本包下游各对一种不同的处置 —— 缺席 = 什么都不渲(**不许**渲「一台都够不着」也
+ *   **不许**渲「都好着」);读不出 = 渲「这一格读不出」并让运维去看引擎版本与投影层;观察 = 渲那个词
+ *   + 那个时刻。折任何一对,渲出来的都是一句谁都没说过的话。
+ *
+ * ⚠️ 本口**只读这一格**:同行的 `status` / `errorCode` / `delivered` 一个字节都不碰,也不拿它们互相校验
+ *    (三个位各说各的,见文件顶注)。
+ */
+export function readMcpLiveness(row) {
+    // 整行不是对象:说「引擎没报」就是替引擎发言 —— 我们连有没有这一行都没读出来。
+    if (!isRecord(row))
+        return { kind: 'unreadable' };
+    if (!Object.hasOwn(row, 'liveness'))
+        return { kind: 'absent' };
+    const cell = row.liveness;
+    if (!isRecord(cell))
+        return { kind: 'unreadable' };
+    const state = cell.state;
+    if (!isLivenessState(state))
+        return { kind: 'unreadable' };
+    const observedAt = cell.observedAt;
+    if (typeof observedAt !== 'number' || !Number.isFinite(observedAt))
+        return { kind: 'unreadable' };
+    const liveness = { state, observedAt };
+    // 注脚:只随 unreachable 收,且形坏只丢它自己(见文件顶注最后一段)。
+    if (state === 'unreachable' && typeof cell.errorCode === 'string' && cell.errorCode.length > 0) {
+        liveness.errorCode = cell.errorCode;
+    }
+    return { kind: 'observation', liveness };
+}
+/**
+ * 一条腿的名册 → 活性判词(**唯一铸点**:别在各端的状态行装配里另写一遍这套合成规则)。
+ *
+ * 合成规则 = **最坏事实优先**,不是多数票、不是取最新一格:
+ *  ① 任一行 `unreachable` ⇒ `unreachable`(有一台**可证**打不通时说「够得着」,就是把坏消息折成健康);
+ *  ② 否则任一行 `unknown` **或任一行的格读不出**(`livenessUnreadable`,或入参自带一格形坏的 `liveness`)
+ *     ⇒ `unknown`。在**腿**这一层,`unknown` 的意思恰是
+ *     「有观察在场而答不了这个问题」,而一份读不懂的格**同样答不了** ⇒ 🔴 **读不出的格绝不作可达的证据**
+ *     (否则「一行读不出 + 一行 reachable」会合成一句「这条腿够得着」,而那行读不出的格完全可能本来写着
+ *     `unreachable`)。为什么答不了,由 {@link McpEngineLegHealth.unreadableCells} 分辨;
+ *  ③ 否则任一行 `reachable` ⇒ `reachable`(其余行缺席 = 没观察,不是反证);
+ *  ④ 否则 ⇒ `indeterminate`。
+ *
+ * 缺席答什么:`{reading:'indeterminate'}` —— 三种入参落这一档且**刻意同形**:段读不出(`undefined`)、
+ *   零申报(`[]`,这条腿一台服务器都没申报 ⇒ 没有服务器就没有观察)、每一行的活性格都缺席(老引擎 /
+ *   都没走到)。要分「一台都没申报」与「有服务器但没报活性」,问名册本身(行数)或在场判词,**不要**
+ *   让本口替那一问答话。
+ * 畸形答什么:整个入参不是数组 ⇒ `indeterminate`;行本身不是对象 ⇒ **那一行什么都不贡献**(连「有没有
+ *   这一格」都没读出来,不替它认领一格);行在而那一格形坏 ⇒ 按上面的 ② 算「读不出」。**永不抛**。
+ * 为什么不折:`indeterminate` 与三个词之间**没有**默认值可回落 —— 回落到 `reachable` 是谎、回落到
+ *   `unreachable` 是恐慌、回落到 `unknown` 是替引擎认领一次它没做过的观察。
+ */
+export function mcpLivenessRollupOf(rows) {
+    if (!Array.isArray(rows))
+        return { reading: 'indeterminate' };
+    let unreachable = false;
+    let unknown = false;
+    let reachable = false;
+    let unreadable = false;
+    // 按**词**分别记最新时刻:判词定下来之后只取那个词自己的(见 McpEngineLegHealth.observedAt 的理由)。
+    const newestByWord = {};
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object')
+            continue;
+        if (row.livenessUnreadable === true)
+            unreadable = true;
+        const lv = row.liveness;
+        // `undefined` = 这一格不在 = 没有观察(JSON 上根本没有这一键):什么都不贡献,也不算「读不出」。
+        if (lv === undefined)
+            continue;
+        // 形再核一次(本口是公面,入参可能来自宿主自建管线而不是本包的读器):整格不是对象、词出闭集、
+        // 时刻非有限数 ⇒ 与 `livenessUnreadable` **同判**(算「在场而读不出」)。🔴 刻意不让它「什么都不贡献」:
+        // 那样一行读不懂的格会被另一行的 `reachable` 盖过去,合成一句「这条腿够得着」—— 正是本件要防的那一折。
+        if (lv === null || typeof lv !== 'object' || Array.isArray(lv)) {
+            unreadable = true;
+            continue;
+        }
+        const word = lv.state;
+        if (!isLivenessState(word)) {
+            unreadable = true;
+            continue;
+        }
+        if (typeof lv.observedAt !== 'number' || !Number.isFinite(lv.observedAt)) {
+            unreadable = true;
+            continue;
+        }
+        if (word === 'unreachable')
+            unreachable = true;
+        else if (word === 'unknown')
+            unknown = true;
+        else
+            reachable = true;
+        const seen = newestByWord[word];
+        if (seen === undefined || lv.observedAt > seen)
+            newestByWord[word] = lv.observedAt;
+    }
+    const reading = unreachable
+        ? 'unreachable'
+        : unknown || unreadable
+            ? 'unknown'
+            : reachable
+                ? 'reachable'
+                : 'indeterminate';
+    // 时刻与判词同源:`indeterminate` 没有时刻;`unknown` 若只由读不出的格决定,那个词一格可读观察都没有 ⇒ 同样没有时刻。
+    const at = reading === 'indeterminate' ? undefined : newestByWord[reading];
+    return {
+        reading,
+        ...(unreadable ? { unreadableCells: true } : {}),
+        ...(at !== undefined ? { observedAt: at } : {}),
+    };
+}
+/** 观察时刻的呈前写法:ISO(与本包其余时刻面同形)。🔴 **超出 `Date` 可表示区间的有限数原样印数字,
+ *  绝不抛、也绝不回落到一个编出来的时刻** —— 那一格是引擎给的读数,不是本包的时钟。 */
+const epochLabel = (ms) => Math.abs(ms) <= 8.64e15 ? new Date(ms).toISOString() : String(ms);
+/**
+ * 活性那一行措辞的**唯一铸点**(三端共用;别在各端的行装配里另写一遍)。
+ *
+ * 🔴 四句刻意逐字互异,且**没有一句**把 `indeterminate` 说成「都好着」或「一台都够不着」:
+ *  ① `reachable`     —— 上次交换完成了(这条腿的观察,带时刻);
+ *  ② `unreachable`   —— 至少一台**可证**够不着;
+ *  ③ `unknown`       —— 看过了,答不了(读不出的格同落这一档,附注多一句);
+ *  ③′ `unknown` 且**只**由读不出的格决定(判词无时刻 ∧ `unreadableCells`)—— 另一句:记录在场而**本端读不出**。
+ *     ③ 那句的主语是「回来的东西」(引擎看了、看不出来),③′ 的主语是本端的读器 —— 上游哪天加了第四个词,
+ *     老客户端落的正是 ③′;把它说成 ③ 等于替引擎认领一次它没做过的「看不出来」。
+ *  ④ `indeterminate` —— **没报**:这条腿上没有可用的观察记录,**不武断咎为引擎版本**(四源同形)。
+ * 🔴 句子里**不出现**服务器台数与「健康 / 正常」这类词:台数在名册上,而「健康」是本格答不了的问题
+ *    (它只答「还够得着吗」)。
+ * 🔴 句尾那个时刻**属于句子里那个判词**(见 {@link McpEngineLegHealth.observedAt}):说「至少有一台够不着」
+ *    时它是最新那次**够不着**的观察时刻,不是这条腿上任何一次观察的最大值 —— 否则一句旧故障的判词会跟上
+ *    一个属于别的词的新时刻,读起来像刚刚又确认了一次。时刻缺席时句子里就没有时刻,不编「刚刚」。
+ */
+export function mcpEngineLegHealthDetail(health) {
+    if (health === undefined)
+        return 'mcp liveness not reported (no liveness observation is available to this client)';
+    const unreadable = health.unreadableCells === true ? ' (one or more liveness records could not be read)' : '';
+    const at = health.observedAt !== undefined ? `, last observed at ${epochLabel(health.observedAt)}` : '';
+    switch (health.reading) {
+        case 'reachable':
+            return `mcp liveness: an exchange completed for every server that was observed on this leg${at}${unreadable}`;
+        case 'unreachable':
+            return `mcp liveness: at least one server was observed unreachable on this leg${at}${unreadable}`;
+        case 'unknown':
+            // ③′:时刻缺席 ∧ 有读不出的格 ⇒ 这个 unknown 一格可读观察都没有(时刻与判词同源,见 McpEngineLegHealth.observedAt)。
+            if (health.observedAt === undefined && health.unreadableCells === true) {
+                return 'mcp liveness: liveness records are present on this leg, but this client could not read them';
+            }
+            return `mcp liveness: observed on this leg, but what came back does not answer whether the server can be reached${at}${unreadable}`;
+        default:
+            return `mcp liveness not reported (no observation record on this leg's roster)${unreadable}`;
+    }
+}

package/dist/mcpPanel.d.ts

@@ -36,6 +36,7 @@
  */
 import type { AgentClient } from '@sema-agent/sdk';
 import { type WiringManifestMcpEntryView } from './adapter/downstream/eventToSdkMessage.js';
+import { type McpEngineLegHealth } from './mcpLiveness.js';
 /** 面板 `servers[]` 一行(sdk `McpServerStatus` 的窄读;开集键不透传,逐键挑)。 */
 export interface McpPanelServerView {
     /** 配置名(引擎产的标识,非用户内容)。 */
@@ -120,3 +121,19 @@ export declare function mcpPanelLastLegDetail(view: McpPanelView | undefined, op
  */
 export type McpEngineLegPresence = 'present' | 'absent' | 'unknown';
 export declare function mcpEngineLegPresence(view: McpPanelView | undefined): McpEngineLegPresence;
+/**
+ * CC-36(0.76.1):**这条腿的 MCP 活性判词**,只从本包的面板视图求(不自拼第二份判据、不发第二次请求)。
+ * 合成规则、四个读数与「缺席 ≠ unknown」那几句话的单一铸点在 {@link mcpLivenessRollupOf};本口只做一件事 ——
+ * 把面板上**带活性格的那一面**交给它。
+ *
+ * 🔴 **活性只在「最近那条腿的名册」这一面上**(`lastLegMcp.mcp[]`)。面板自己的 `servers[]` 半场**没有**
+ *    这一格:那一面是**部署缺省场景**此刻按需物化出来的台账,它的投影是逐键挑的白名单,今天不带活性位 ——
+ *    所以本口读不到它**不是漏读,是那一面今天没有这句话**。哪天它带上了,处置是同批补一格读数 + 判据,
+ *    而**不是**拿这一面的词去顶另一面(两面合法可不同,视图上从来没有、也不会有「一致/不一致」位)。
+ * 🔴 **判词说的是「那条腿」,不是「此刻」**:`observedAt` 属于那条腿的观察时刻,与面板的 `asOf` 不同源、
+ *    **不比**。壳渲这一行必须带腿的时刻,别渲成一个实时健康灯。
+ * 🔴 `view === undefined`(传输失败 / 体读不出 / 空 sessionId,三形同形)与「面板读到了但没有那条腿的
+ *    名册」**都答 `indeterminate`**:两者的共同点正是这句话本身 —— 本包**说不出**这条腿的活性。
+ *    要分辨「这次读没读到面板」问 {@link mcpPanelLastLegDetail} 的 `reachable` 位,**不要**让本口替它答。
+ */
+export declare function mcpEngineLegHealthOf(view: McpPanelView | undefined): McpEngineLegHealth;

package/dist/mcpPanel.js

@@ -1,6 +1,7 @@
 import { hostLog } from './host.js';
 import { projectMcpSection } from './adapter/downstream/eventToSdkMessage.js';
 import { capForDisplay } from './fleetTaskDesc.js';
+import { mcpLivenessRollupOf } from './mcpLiveness.js';
 /** `error` 上屏前的封长(server 侧 `slice(200)`,同值)。 */
 const MCP_PANEL_ERROR_MAX = 200;
 /** 名字类词形的封长(与本包其余 detail 铸点同值同理由)。 */
@@ -140,3 +141,23 @@ export function mcpEngineLegPresence(view) {
         return 'present';
     return 'absent';
 }
+/**
+ * CC-36(0.76.1):**这条腿的 MCP 活性判词**,只从本包的面板视图求(不自拼第二份判据、不发第二次请求)。
+ * 合成规则、四个读数与「缺席 ≠ unknown」那几句话的单一铸点在 {@link mcpLivenessRollupOf};本口只做一件事 ——
+ * 把面板上**带活性格的那一面**交给它。
+ *
+ * 🔴 **活性只在「最近那条腿的名册」这一面上**(`lastLegMcp.mcp[]`)。面板自己的 `servers[]` 半场**没有**
+ *    这一格:那一面是**部署缺省场景**此刻按需物化出来的台账,它的投影是逐键挑的白名单,今天不带活性位 ——
+ *    所以本口读不到它**不是漏读,是那一面今天没有这句话**。哪天它带上了,处置是同批补一格读数 + 判据,
+ *    而**不是**拿这一面的词去顶另一面(两面合法可不同,视图上从来没有、也不会有「一致/不一致」位)。
+ * 🔴 **判词说的是「那条腿」,不是「此刻」**:`observedAt` 属于那条腿的观察时刻,与面板的 `asOf` 不同源、
+ *    **不比**。壳渲这一行必须带腿的时刻,别渲成一个实时健康灯。
+ * 🔴 `view === undefined`(传输失败 / 体读不出 / 空 sessionId,三形同形)与「面板读到了但没有那条腿的
+ *    名册」**都答 `indeterminate`**:两者的共同点正是这句话本身 —— 本包**说不出**这条腿的活性。
+ *    要分辨「这次读没读到面板」问 {@link mcpPanelLastLegDetail} 的 `reachable` 位,**不要**让本口替它答。
+ */
+export function mcpEngineLegHealthOf(view) {
+    if (view === undefined)
+        return { reading: 'indeterminate' };
+    return mcpLivenessRollupOf(view.lastLegMcp?.mcp);
+}