@sema-agent/client-core 0.68.1 → 0.69.0

package/dist/mcpPanel.d.ts

@@ -0,0 +1,104 @@
+/**
+ * mcpPanel.ts — `GET /v1/sessions/:id/mcp` 面板体(sdk `McpStatusPanel`)的**防御读视图**
+ * (CC-03,0.68.2;server 7.77.0 S-297 可选键 `lastLegMcp`;回 A-093 ③)。
+ *
+ * ── 为什么在包里(归层)────────────────────────────────────────────────────────────────────
+ * 面板体是三端都要渲的同一份读面:`servers[]` 是「这台部署此刻按需 materialize 出来的连接状态」,
+ * `lastLegMcp` 是「这个会话最近一条腿的账本里申报了哪些 MCP」。**两面合法可不同**(部署缺省场景
+ * 与按请求注入的名册本来就是两张表),契约 G.7 第 4 条禁止消费端拿它们对账后渲「不一致」。
+ * 这条纪律若各端自己写一遍,迟早有一端写反。⇒ 读法(哪些键、坏形怎么办、缺席说什么)只在这里
+ * 有一份;端只渲。
+ *
+ * ── 缺席语义(逐键)──────────────────────────────────────────────────────────────────────────
+ *  · `lastLegMcp` **整键缺席** = server 的三形同形(新会话 / 最近腿的账本行在保留窗外 / 该腿没推
+ *    `wiring_manifest`)**或**引擎早于 7.77.0;本视图同样不铸该键。「为什么缺席」这一位答不出来,
+ *    也不猜。
+ *  · `lastLegMcp` **在场但形坏**(`runId` / `at` 不是非空串、`mcp` 读不出一行)⇒ 视图不铸该键,
+ *    改立 {@link McpPanelView.lastLegMcpUnreadable}(never false)。「引擎送了一份我读不懂的」与
+ *    「引擎没送」对运维是两句话,不折成一个 `undefined`。
+ *  · `degraded`:只在 server 的超时臂铸(sdk openapi 顶注逐字)⇒ 本视图 never false:在场 = 取不到,
+ *    缺席 = 正常 materialize(`servers: []` 那时是「一台都没配」这句正面事实,不是「不知道」)。
+ *  · `servers[]` 逐行:`name` + `status` 是必需两座(缺一丢该行,坏一行只丢那一行);**非空输入而零行
+ *    幸存 ⇒ 整个视图 `undefined`**(「我读不出来」不是「我知道是零」,与 `wiring_manifest.mcp`
+ *    同一条规矩)。`status` 按开集读(sdk 只声明 connected/failed 两词,core 未来加词照渲不丢行)。
+ *  · `error`:server 已脱敏 + 200 字符封顶;本视图仍按 UNTRUSTED-for-display 再过一次
+ *    {@link capForDisplay}(呈前消毒 + 封长),与本包其余远端文本铸点同律。
+ *
+ * ── `mcp[]` 条目与 `wiring_manifest` 第三段**同一只读器**─────────────────────────────────────
+ * `lastLegMcp.mcp[]` 是该腿 `wiring_manifest.mcp[]` 的逐字回放(server S-297),本视图直接调
+ * {@link projectMcpSection} —— 同一形、同一判据、同一缺席律;三端渲这两处用同一个
+ * {@link WiringManifestMcpEntry},不会出现「活体腿一种形、账本回放另一种形」。
+ */
+import type { AgentClient } from '@sema-agent/sdk';
+import { type WiringManifestMcpEntry } from './adapter/downstream/eventToSdkMessage.js';
+/** 面板 `servers[]` 一行(sdk `McpServerStatus` 的窄读;开集键不透传,逐键挑)。 */
+export interface McpPanelServerView {
+    /** 配置名(引擎产的标识,非用户内容)。 */
+    name: string;
+    /** `connected` / `failed`(sdk 声明的两词;**按开集读**,认不得的词照渲不丢行)。 */
+    status: string;
+    /** 服务器自报的名字与版本(仅 connected 时有)。缺席 = 没报。 */
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 挂上来的工具名(仅 connected 时有)。缺席 = 没报,**不是**空表。 */
+    toolNames?: string[];
+    /** 失败因由(仅 failed 时;server 已脱敏 + 封顶,本视图再消毒一次)。 */
+    error?: string;
+}
+/** `lastLegMcp{runId,at,mcp[]}`(server ≥7.77.0 S-297)的窄读。 */
+export interface McpPanelLastLegView {
+    /** 该会话最近一条腿的 runId。 */
+    runId: string;
+    /** 写账本副本的钟(ISO;**不是** materialize 时刻 `asOf`,两者不比)。 */
+    at: string;
+    /** 该腿 `wiring_manifest.mcp[]` 逐字 —— 与活体腿的第三段同一只读器、同一形。 */
+    mcp: WiringManifestMcpEntry[];
+}
+/** `GET /v1/sessions/:id/mcp` 的读视图(缺席语义见文件顶注)。 */
+export interface McpPanelView {
+    /** THIS materialize 时刻(ISO)。 */
+    asOf: string;
+    /** materialization-time 状态,不是 live 健康(壳渲「as of <asOf>」)。空表 = 一台都没配。 */
+    servers: McpPanelServerView[];
+    /** never false:在场 = materialize 超时/失败,`servers` 空但**不是**「没有 MCP」。 */
+    degraded?: true;
+    /** 最近一条腿的申报名册(server ≥7.77.0);缺席语义见顶注。🔴 禁与 `servers[]` 对账渲告警。 */
+    lastLegMcp?: McpPanelLastLegView;
+    /** never false:server 送了 `lastLegMcp` 但本视图读不出来(与整键缺席不是同一句话)。 */
+    lastLegMcpUnreadable?: true;
+}
+/**
+ * 面板体 → 读视图;**畸形一律 `undefined`**,绝不抛出(必填位 fail-closed,可选位只丢自己)。
+ *
+ * 🔴 `lastLegMcp` 只按「键在不在」判在场(`'lastLegMcp' in body`),不按真值判:server 的缺席形
+ *    是**键不出现**(LL-3),不是 `null`/`undefined` 在场 —— 后两者是坏形,走 `lastLegMcpUnreadable`。
+ * 🔴 本函数**不比** `servers[]` 与 `lastLegMcp.mcp[]`,视图上也没有任何「一致/不一致」位
+ *    (契约 G.7 第 4 条:两面合法可不同)。
+ */
+export declare function projectMcpPanel(body: unknown): McpPanelView | undefined;
+/**
+ * 取面板体并投成读视图(CC-03 补件,0.69.0):`GET /v1/sessions/:id/mcp` 经 sdk `client.sessions.mcp`(自 sdk 0.0.75 在场,
+ * 与 `runs.subagentOutput` 同一条 transport,鉴权/principal 由 sdk 带 —— 本包**不**裸 fetch,不做第二套鉴权铸点)。
+ *
+ * 🔴 返回 `undefined` 的三形**同形**(与 {@link projectMcpPanel} 的缺席律一致):传输失败(网络 / 4xx / 5xx / abort)、
+ *    体读不出(必填位坏)、`sessionId` 空串(不发请求)。「为什么」不在返回值上 —— 传输失败留一行 `hostLog('debug')`,
+ *    端要分「未观测 vs 读不出」用 {@link mcpPanelLastLegDetail} 的 `reachable` 位(`view !== undefined` 即 reachable)。
+ * 🔴 `client` 只钉 `sessions` 一格(`Pick`):端传本包 `makeEngineWireClient` 造的实例即可,测试可喂假客户端。
+ */
+export declare function fetchMcpPanel(client: Pick<AgentClient, 'sessions'>, sessionId: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<McpPanelView | undefined>;
+/**
+ * `lastLegMcp` 那一行措辞的**唯一铸点**(三端共用;别在各端的行装配里另写一遍)。
+ *
+ * 🔴 四句刻意逐字互异(黑盒锚),且**没有一句**提到 `servers[]`:
+ *   ① 在场 —— 名册 + runId + at;
+ *   ② `opts.reachable === false` —— 「未观测」:这次进程没读到面板体;
+ *   ③ 面板读到了但 `lastLegMcp` 整键缺席 —— 「不报」:三形同形 + 老引擎,**不武断咎为版本**;
+ *   ④ 在场但读不懂 —— 「读不出」:与③是两句话。
+ */
+export declare function mcpPanelLastLegDetail(view: McpPanelView | undefined, opts: {
+    reachable: boolean;
+}): string;

package/dist/mcpPanel.js

@@ -0,0 +1,129 @@
+import { hostLog } from './host.js';
+import { projectMcpSection } from './adapter/downstream/eventToSdkMessage.js';
+import { capForDisplay } from './fleetTaskDesc.js';
+/** `error` 上屏前的封长(server 侧 `slice(200)`,同值)。 */
+const MCP_PANEL_ERROR_MAX = 200;
+/** 名字类词形的封长(与本包其余 detail 铸点同值同理由)。 */
+const MCP_PANEL_WORD_MAX = 40;
+/** `mcpPanelLastLegDetail` 里列出的名字上限(再多就是一行读不完的表,不是一句读数)。 */
+const MCP_PANEL_NAMES_MAX = 8;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+function projectServerRow(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    if (!nonEmpty(raw.name) || !nonEmpty(raw.status))
+        return undefined;
+    const row = { name: raw.name, status: raw.status };
+    const si = raw.serverInfo;
+    if (isRecord(si) && typeof si.name === 'string' && typeof si.version === 'string') {
+        row.serverInfo = { name: si.name, version: si.version };
+    }
+    if (Array.isArray(raw.toolNames) && raw.toolNames.every((t) => typeof t === 'string')) {
+        row.toolNames = [...raw.toolNames];
+    }
+    if (typeof raw.error === 'string')
+        row.error = capForDisplay(raw.error, MCP_PANEL_ERROR_MAX);
+    return row;
+}
+function projectLastLeg(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    if (!nonEmpty(raw.runId) || !nonEmpty(raw.at))
+        return undefined;
+    const mcp = projectMcpSection(raw.mcp);
+    if (mcp === undefined)
+        return undefined;
+    return { runId: raw.runId, at: raw.at, mcp };
+}
+/**
+ * 面板体 → 读视图;**畸形一律 `undefined`**,绝不抛出(必填位 fail-closed,可选位只丢自己)。
+ *
+ * 🔴 `lastLegMcp` 只按「键在不在」判在场(`'lastLegMcp' in body`),不按真值判:server 的缺席形
+ *    是**键不出现**(LL-3),不是 `null`/`undefined` 在场 —— 后两者是坏形,走 `lastLegMcpUnreadable`。
+ * 🔴 本函数**不比** `servers[]` 与 `lastLegMcp.mcp[]`,视图上也没有任何「一致/不一致」位
+ *    (契约 G.7 第 4 条:两面合法可不同)。
+ */
+export function projectMcpPanel(body) {
+    if (!isRecord(body))
+        return undefined;
+    if (!nonEmpty(body.asOf))
+        return undefined;
+    if (!Array.isArray(body.servers))
+        return undefined;
+    const servers = [];
+    for (const r of body.servers) {
+        const row = projectServerRow(r);
+        if (row !== undefined)
+            servers.push(row);
+    }
+    if (body.servers.length > 0 && servers.length === 0)
+        return undefined;
+    const view = { asOf: body.asOf, servers };
+    if (body.degraded === true)
+        view.degraded = true;
+    if ('lastLegMcp' in body) {
+        const leg = projectLastLeg(body.lastLegMcp);
+        if (leg !== undefined)
+            view.lastLegMcp = leg;
+        else
+            view.lastLegMcpUnreadable = true;
+    }
+    return view;
+}
+/**
+ * 取面板体并投成读视图(CC-03 补件,0.69.0):`GET /v1/sessions/:id/mcp` 经 sdk `client.sessions.mcp`(自 sdk 0.0.75 在场,
+ * 与 `runs.subagentOutput` 同一条 transport,鉴权/principal 由 sdk 带 —— 本包**不**裸 fetch,不做第二套鉴权铸点)。
+ *
+ * 🔴 返回 `undefined` 的三形**同形**(与 {@link projectMcpPanel} 的缺席律一致):传输失败(网络 / 4xx / 5xx / abort)、
+ *    体读不出(必填位坏)、`sessionId` 空串(不发请求)。「为什么」不在返回值上 —— 传输失败留一行 `hostLog('debug')`,
+ *    端要分「未观测 vs 读不出」用 {@link mcpPanelLastLegDetail} 的 `reachable` 位(`view !== undefined` 即 reachable)。
+ * 🔴 `client` 只钉 `sessions` 一格(`Pick`):端传本包 `makeEngineWireClient` 造的实例即可,测试可喂假客户端。
+ */
+export async function fetchMcpPanel(client, sessionId, opts) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0)
+        return undefined;
+    let body;
+    try {
+        body = await client.sessions.mcp(sessionId, opts?.signal ? { signal: opts.signal } : undefined);
+    }
+    catch (e) {
+        const status = e?.status;
+        hostLog('debug', `[mcp-panel] ${sessionId}: ${typeof status === 'number' ? status : String(e).slice(0, 160)}`);
+        return undefined;
+    }
+    return projectMcpPanel(body);
+}
+/**
+ * `lastLegMcp` 那一行措辞的**唯一铸点**(三端共用;别在各端的行装配里另写一遍)。
+ *
+ * 🔴 四句刻意逐字互异(黑盒锚),且**没有一句**提到 `servers[]`:
+ *   ① 在场 —— 名册 + runId + at;
+ *   ② `opts.reachable === false` —— 「未观测」:这次进程没读到面板体;
+ *   ③ 面板读到了但 `lastLegMcp` 整键缺席 —— 「不报」:三形同形 + 老引擎,**不武断咎为版本**;
+ *   ④ 在场但读不懂 —— 「读不出」:与③是两句话。
+ */
+export function mcpPanelLastLegDetail(view, opts) {
+    if (!opts.reachable)
+        return "last leg mcp not observed (this end could not read the session's MCP panel)";
+    if (view === undefined)
+        return 'last leg mcp unreadable (the MCP panel body could not be read by this client)';
+    if (view.lastLegMcp !== undefined) {
+        const { runId, at, mcp } = view.lastLegMcp;
+        const names = mcp.slice(0, MCP_PANEL_NAMES_MAX).map((e) => capForDisplay(e.name, MCP_PANEL_WORD_MAX));
+        const more = mcp.length > MCP_PANEL_NAMES_MAX ? `, +${mcp.length - MCP_PANEL_NAMES_MAX} more` : '';
+        const roster = mcp.length === 0 ? 'none declared' : `${names.join(', ')}${more}`;
+        return `last leg mcp: ${roster} (run ${capForDisplay(runId, MCP_PANEL_WORD_MAX)}, at ${capForDisplay(at, MCP_PANEL_WORD_MAX)})`;
+    }
+    if (view.lastLegMcpUnreadable === true) {
+        return 'last leg mcp unreadable (the engine sent a shape this client cannot read)';
+    }
+    return 'last leg mcp not reported (no leg in the retention window, no manifest on the last leg, or the engine predates it)';
+}
+/**
+ * **编译期对账钉**(不出公面):sdk 的 `McpStatusPanel` 必须能赋给视图的必填半场 —— 名字在
+ * sdk ≥8.8.0 上存在(本包 peer 地板),`tsc` 在改名当天报「没有导出成员」。
+ * 反向刻意不钉(视图比 sdk 形窄:开集键不透传、`degraded` 收成 never-false)。
+ */
+const _mcpPanelShapePin = (p) => p;
+void _mcpPanelShapePin;

package/dist/request/taskRequest.d.ts

@@ -118,6 +118,60 @@ export interface TaskRequestInput {
         outputStyle?: string;
     };
 }
+/**
+ * 合一后的请求构造器 —— **按车道出两形**,字段集差异全部由 `REQUEST_FIELD_MATRIX` 决定。
+ *
+ * 🔴 行为纪律:本函数**不做任何统一**。print 没有 `ultracode` 就是没有(表里 `gap:true` 记着账),
+ * 补齐要另立项 —— 在这里顺手加一行,就是把「合一」偷换成「行为改动」。
+ */
+/**
+ * ⑤ 的**响亮拒**([7226] 包侧缺口 ⑤;异源对抗复审轮五 finding① 采纳)。
+ *
+ * 🔴 修前这里是「不是 `'off'` 就整键不 stamp」——**静默删键**,而删掉的恰是一条**隐私声明**:
+ *    一个把 `/memory-capture off` 打成 `OFF` 的会话,请求照发、引擎照常采集,**没有任何人会知道**。
+ * 🔴 上游把这条写死了(装机 core `dist/core/memory.d.ts` 的 `capture?: "off"` 头注**逐字**):
+ *    「Any other value — `"on"`, `"OFF"`, booleans, garbage — is REFUSED loudly
+ *    (`config.memory_capture_spelling`), never read as either state (**a privacy request must not be
+ *    dropped by a typo**, and capture must not be switched off by one either)」;server 契约 §12.4
+ *    同样写明坏拼写 400 `request.field_invalid`,并点名「把一条隐私请求按打字错误静默丢掉恰是**禁的方向**」。
+ *    ⇒ 提前删键 = 把上游那道响亮门**绕过去**,方向正好反了。
+ * 🔴 与本文件 `resolvedSnapshotForWire` 对畸形权限快照的处置**同一条纪律**(那里也是抛,理由逐字
+ *    是「降空 = 让请求带着被剥掉的权限面发出去」)——两处都是**声明方向**的位:丢了没人看得见。
+ * ⚠️ `undefined` / `null` = **合法缺席**(端没有这个入口 / 没有声明),照旧不 stamp,不拒。
+ * ⚠️ **不分车道、不受 live 门**:拒绝不是「stamp 一个键」,不改请求形状;而一条打错字的隐私声明
+ *    在哪条车道上都不该被默默放行。
+ * (本包是发出去的 npm 公开面:JS 调用方与版本偏斜的宿主都到得了这里,型面拦不住。)
+ */
+/**
+ * wire 上那个**单成员闭集**的唯一字面(server §12.4)。导出它是为了让端的断言/门有一个机读锚,
+ * 🔴 **不是**为了让端拿它去自己拼请求 —— 拼请求走 {@link memoryCaptureDeclarationField}。
+ */
+export declare const MEMORY_CAPTURE_OFF: "off";
+/**
+ * 「本会话声明过 opt-out 没有」这个**意图位** → 提交腿的 spread-ready 片段(L-316,0.68.2)。
+ *
+ * ── 为什么这一只在包里(归层,不是搬家)────────────────────────────────────────────────────
+ * 端手里只有一个**布尔**:「这条会话敲过 `/memory-capture off` 没有」。而 wire 上那个值是
+ * **单成员闭集**的一个字面串 —— 谁铸这个串,谁就得同时承担「拼错了会被 400 响亮拒、而且这是
+ * 一条**隐私**声明、拼错即静默失效」这件事。cli 1.0.x 起这个串在壳里另有一处铸点
+ * (`memoryCaptureOptOut.memoryCaptureRequestField`),web / desktop 接这条腿时会各铸第三、第四处
+ * —— 三端各写一个字面量,正是本层存在的理由(与 `taskNotificationToPrintFrame` 同一条先例)。
+ * ⇒ 端交**意图位**,值由本层唯一铸出;拼写门与 {@link buildTaskRequest} 的响亮拒共用同一个字面。
+ *
+ * 🔴 **`false` ⇒ 整键缺席**,不是 `{ memoryCapture: undefined }`、更不是某个「on」值:wire 上
+ *    压根没有那个值(单成员闭集),**缺席就是「照常采集」的唯一写法**。所以未启用时本片段对
+ *    wire 字节零影响。
+ * 🔴 **本层只答「下一条提交带不带这一键」,不答「采集关没关」**:后者只有引擎知道(老 worker
+ *    静默忽略本键 / 部署策略 403 / 控制面写失败),任何端都不许拿这一位去渲一句「已经关了」。
+ *
+ * 用法(端逐字照抄,别在外面再包一层字面量):
+ * ```ts
+ * buildTaskRequest({ …, ...memoryCaptureDeclarationField(declaredForThisSession) }, 'interactive')
+ * ```
+ */
+export declare function memoryCaptureDeclarationField(declared: boolean): {
+    memoryCapture: 'off';
+} | Record<string, never>;
 export declare function buildTaskRequest(input: TaskRequestInput, lane: RequestLane): TaskRequestLike;
 /** `applyLiveRequestDefaults` 的宿主输入(端解析好的值,同样零取值方式)。 */
 export interface LiveDefaultsInput {

package/dist/request/taskRequest.js

@@ -417,6 +417,36 @@ const resolvedSnapshotForWire = (resolved) => {
  *    在哪条车道上都不该被默默放行。
  * (本包是发出去的 npm 公开面:JS 调用方与版本偏斜的宿主都到得了这里,型面拦不住。)
  */
+/**
+ * wire 上那个**单成员闭集**的唯一字面(server §12.4)。导出它是为了让端的断言/门有一个机读锚,
+ * 🔴 **不是**为了让端拿它去自己拼请求 —— 拼请求走 {@link memoryCaptureDeclarationField}。
+ */
+export const MEMORY_CAPTURE_OFF = 'off';
+/**
+ * 「本会话声明过 opt-out 没有」这个**意图位** → 提交腿的 spread-ready 片段(L-316,0.68.2)。
+ *
+ * ── 为什么这一只在包里(归层,不是搬家)────────────────────────────────────────────────────
+ * 端手里只有一个**布尔**:「这条会话敲过 `/memory-capture off` 没有」。而 wire 上那个值是
+ * **单成员闭集**的一个字面串 —— 谁铸这个串,谁就得同时承担「拼错了会被 400 响亮拒、而且这是
+ * 一条**隐私**声明、拼错即静默失效」这件事。cli 1.0.x 起这个串在壳里另有一处铸点
+ * (`memoryCaptureOptOut.memoryCaptureRequestField`),web / desktop 接这条腿时会各铸第三、第四处
+ * —— 三端各写一个字面量,正是本层存在的理由(与 `taskNotificationToPrintFrame` 同一条先例)。
+ * ⇒ 端交**意图位**,值由本层唯一铸出;拼写门与 {@link buildTaskRequest} 的响亮拒共用同一个字面。
+ *
+ * 🔴 **`false` ⇒ 整键缺席**,不是 `{ memoryCapture: undefined }`、更不是某个「on」值:wire 上
+ *    压根没有那个值(单成员闭集),**缺席就是「照常采集」的唯一写法**。所以未启用时本片段对
+ *    wire 字节零影响。
+ * 🔴 **本层只答「下一条提交带不带这一键」,不答「采集关没关」**:后者只有引擎知道(老 worker
+ *    静默忽略本键 / 部署策略 403 / 控制面写失败),任何端都不许拿这一位去渲一句「已经关了」。
+ *
+ * 用法(端逐字照抄,别在外面再包一层字面量):
+ * ```ts
+ * buildTaskRequest({ …, ...memoryCaptureDeclarationField(declaredForThisSession) }, 'interactive')
+ * ```
+ */
+export function memoryCaptureDeclarationField(declared) {
+    return declared ? { memoryCapture: MEMORY_CAPTURE_OFF } : {};
+}
 const refuseBadMemoryCapture = (v) => {
     if (v === undefined || v === null)
         return;

package/dist/sdkWireTransit.d.ts

@@ -0,0 +1,41 @@
+/**
+ * src/sdkWireTransit.ts — SDK **wire 面**的转口口(L-61 存量清零;clay 令 C-R43「所有欠账绝不延期」)。
+ *
+ * ── 为什么开这一只(与 `engineHttpTools.ts` 的分界)──────────────────────────────────────────
+ * `engineHttpTools.ts` 转的是两件**纯工具**(URL builder / 存活探针)。本文件转的是 wire 面的
+ * **客户端类**、**帧谓词**与**型面** —— 端至今只能直连 `@sema-agent/sdk` 去取它们
+ * (cli sdk-isolation 存量册 `sdk-value` 桶的剩余条目),而「壳对引擎 wire 的一切消费必须经本包」
+ * 这条公约对它们一直不成立。
+ *
+ * 🔴 **为什么 0.68.2 之前把 `AgentClient` 记成 declined,现在改成转口**(改口要给理由,不能只改结论):
+ *    此前的理由是「转口一个客户端类 = 本包为它的连接姿势/鉴权头/重试语义背书」。这条**顾虑仍然
+ *    成立**,但它指向的是「端该不该直接 new 一个 AgentClient」这个**设计问题**,而不是「这条 import
+ *    该不该经本包」这个**归层问题**——把两者绑在一起的代价是:归层这件事被一个未排期的设计件
+ *    无限期挡住(存量窗已因此过期两代)。⇒ 分开处理:
+ *      · **归层现在做**(本文件,原样转口,零包装);
+ *      · **设计件照旧欠着**:本包已有的自有路 `makeEngineWireClient` 才是推荐姿势,端上新码一律走
+ *        那一条;本转口口只给**存量**用,不是新码的入口。这一条写在这里,不靠人记得。
+ *
+ * 🔴 **原样转口,一个字节都不加工**(与 `engineHttpTools.ts` 同一条纪律):不包装、不改签名、
+ *    不补默认值 —— 包一层就是把「同一实现」这条唯一的抗漂移保证亲手拆掉。
+ *
+ * ── 可移植门为什么不受影响(实测,不是推断)────────────────────────────────────────────────
+ *  · `@sema-agent/sdk` **本来就在** `EXPECTED_PACKAGES_INDEX` 等值集里(本包已有值级 SDK import)
+ *    ⇒ 集合一个字节不动;
+ *  · SDK 的 `dist/` 全树 **零 `node:` 内建**(实测:`grep -rl "node:" dist/*.js` 空),传输走全局
+ *    `fetch`/`AbortController` = web 标准 ⇒ ③ 段的 `--platform=browser` 真打包面零风险;
+ *  · 型面转口是 `export type`,编译后整段消失 ⇒ 闭包扫描的「剥 type-only」那一步本来就不看它。
+ */
+export { AgentClient } from '@sema-agent/sdk';
+export { isApprovalRequestFrameV1, isApprovalRevokeFrameV1 } from '@sema-agent/sdk';
+/**
+ * ── ③ wire **型面**(零运行期,`export type`)────────────────────────────────────────────────
+ *
+ * 🔴 **射程写明**(免得下一棒把这里当成「SDK 型面的全量镜像」):本表**只**收端上存量直连实际用到
+ *    的那些名字,一个不多。全量镜像是另一件事(会把本包的 `.d.ts` 与 SDK 的每一次型面改动绑死),
+ *    与 `@sema-agent/agent-types` 的**CC 形**全量镜像不是一回事 —— 那边镜的是 CC SDK 的会话词汇,
+ *    这边是引擎 wire 的请求/事件/回执形。
+ * 🔴 **谁是权威**:权威恒是 `@sema-agent/sdk` 本身。本文件是**别名**,上游改名 ⇒ 本文件当场编译红,
+ *    端跟着红 —— 这正是型面转口相对「端各自直连」唯一多出来的那点好处(红在一处,不是散在九处)。
+ */
+export type { TaskRequest, SemaSettings, SkillSpec, AgentEvent, RunReceipt, CancelAck, RunRecord, ToolApprovalRespondAck, FleetTaskRow, FleetWorkflowRow, ApprovalCard, ApprovalRequestFrame, ApprovalRiskAxes, AskDecisionAck, AskDecisionBody, } from '@sema-agent/sdk';

package/dist/sdkWireTransit.js

@@ -0,0 +1,32 @@
+/**
+ * src/sdkWireTransit.ts — SDK **wire 面**的转口口(L-61 存量清零;clay 令 C-R43「所有欠账绝不延期」)。
+ *
+ * ── 为什么开这一只(与 `engineHttpTools.ts` 的分界)──────────────────────────────────────────
+ * `engineHttpTools.ts` 转的是两件**纯工具**(URL builder / 存活探针)。本文件转的是 wire 面的
+ * **客户端类**、**帧谓词**与**型面** —— 端至今只能直连 `@sema-agent/sdk` 去取它们
+ * (cli sdk-isolation 存量册 `sdk-value` 桶的剩余条目),而「壳对引擎 wire 的一切消费必须经本包」
+ * 这条公约对它们一直不成立。
+ *
+ * 🔴 **为什么 0.68.2 之前把 `AgentClient` 记成 declined,现在改成转口**(改口要给理由,不能只改结论):
+ *    此前的理由是「转口一个客户端类 = 本包为它的连接姿势/鉴权头/重试语义背书」。这条**顾虑仍然
+ *    成立**,但它指向的是「端该不该直接 new 一个 AgentClient」这个**设计问题**,而不是「这条 import
+ *    该不该经本包」这个**归层问题**——把两者绑在一起的代价是:归层这件事被一个未排期的设计件
+ *    无限期挡住(存量窗已因此过期两代)。⇒ 分开处理:
+ *      · **归层现在做**(本文件,原样转口,零包装);
+ *      · **设计件照旧欠着**:本包已有的自有路 `makeEngineWireClient` 才是推荐姿势,端上新码一律走
+ *        那一条;本转口口只给**存量**用,不是新码的入口。这一条写在这里,不靠人记得。
+ *
+ * 🔴 **原样转口,一个字节都不加工**(与 `engineHttpTools.ts` 同一条纪律):不包装、不改签名、
+ *    不补默认值 —— 包一层就是把「同一实现」这条唯一的抗漂移保证亲手拆掉。
+ *
+ * ── 可移植门为什么不受影响(实测,不是推断)────────────────────────────────────────────────
+ *  · `@sema-agent/sdk` **本来就在** `EXPECTED_PACKAGES_INDEX` 等值集里(本包已有值级 SDK import)
+ *    ⇒ 集合一个字节不动;
+ *  · SDK 的 `dist/` 全树 **零 `node:` 内建**(实测:`grep -rl "node:" dist/*.js` 空),传输走全局
+ *    `fetch`/`AbortController` = web 标准 ⇒ ③ 段的 `--platform=browser` 真打包面零风险;
+ *  · 型面转口是 `export type`,编译后整段消失 ⇒ 闭包扫描的「剥 type-only」那一步本来就不看它。
+ */
+// ── ① 客户端类(存量转口;新码走 `makeEngineWireClient`)────────────────────────────────────
+export { AgentClient } from '@sema-agent/sdk';
+// ── ② 流内审批帧的**信封谓词**(v1 窄化判据;端拿它判「这一帧是不是我认得的那一代」)──────────
+export { isApprovalRequestFrameV1, isApprovalRevokeFrameV1 } from '@sema-agent/sdk';

package/dist/seam.d.ts

@@ -533,7 +533,7 @@ export type ChromeEvent = {
  * ⚠️ **只有 live 腿有本帧**(server 7.69.0 亲读:durable/bg 腿把它喂给 rewind 锚而不入账本)
  * ⇒ replay/resume 上映射表是空的;那时正解是**不画分割线**,不是回退成「画在最后一条」。
  */
- | MessageCommittedChromeEvent | EngineNoticeChromeEvent | TextSegmentEndChromeEvent | WiringManifestChromeEvent | ResultTextDivergedChromeEvent
+ | MessageCommittedChromeEvent | EngineNoticeChromeEvent | TextSegmentEndChromeEvent | ThinkingSegmentEndChromeEvent | WiringManifestChromeEvent | ResultTextDivergedChromeEvent
 /**
  * B-078 / L-208(0.65.0):design/172 流内审批协议的**两条帧**。修前它们在标准管线上落
  * `dropped('unsupported_arm')`,壳自己另接一份 ⇒ 只走包管线的宿主(desktop/web)拿不到
@@ -696,6 +696,54 @@ export interface TextSegmentEndChromeEvent {
      * 🔴 按**增量拼文**计长,不是 `content` 上的偏移量(见义务 ①)。
      */
     committedPrefixLen?: number;
+    /**
+     * **段身份**(CC-01,0.68.2)—— 与本段已过境的 committed assistant 文本行顶层 `_sema_segment_id`
+     * **同值**(本包在 `adapt()` 出口盖;语义与铸法见 `SEMA_SEGMENT_ID_KEY` 头注)。
+     * 🔴 宿主按 {@link TextSegmentEndChromeEvent.committedPrefixLen} 换掉已提交那一截时,认行的钥匙是
+     *    **两把**:行 `uuid` ∧ 行上的段身份 === 本键(按字节相等找行会被同后缀的独立行冒充)。
+     * 恒在场(本包每条 leader 段边界都带);它**不是** wire 键 —— `eventId` 才是引擎铸的事件身份。
+     */
+    segmentId: string;
+    /** core 铸的事件身份(uuidv7 形);wire 未必带 ⇒ 缺席时本键不在场。 */
+    eventId?: string;
+}
+/**
+ * {@link ChromeEvent} 的 `thinking_segment_end` 臂(CC-02,0.68.3;server ≥7.77.0 S-310 `reasoning_end`,
+ * sdk ≥9.4.0 `SegmentEndFields` 与 `text_end` 单源)——「**引擎明报:一段推理到此为止,这是它的权威全文**」。
+ *
+ * ── 与 `text_segment_end` 同一句消费律(sdk 顶注逐字:一个 wire 概念一份形,读法只学一次)────────
+ * `reasoning_delta` 逐 chunk 脱敏对**跨 chunk** 的凭据形无能为力,只有整段看得见 ⇒ `content` 是经与
+ * `text_end` / `result` **同一只**脱敏器的段权威全文,**可以**与活体增量的拼接不相等。本包在臂上做
+ * **整段替换**(思考缓冲 + 活体尾巴),三个 additive 键与 `text_segment_end` **同名同律**(never-false)。
+ *
+ * ── 与散文段的一处结构差(读这一条再接)──────────────────────────────────────────────────────
+ * 思考块**没有 idle-flush**:本包只在三处正常边界提交它(思考→回答边界 / 工具卡前 / turn 收口),
+ * 提交是**整块**的 ⇒ 「已提交前缀」在思考面上是**全有或全无**:`committedPrefixDiverged` 在场时,
+ * `committedPrefixLen` 恒 = 那条已 committed 思考行的全文长度,而且本臂**多带一把钥匙**
+ * {@link ThinkingSegmentEndChromeEvent.committedUuid}(那条行的 `uuid`,本包铸的)—— 思考行**不盖**
+ * `_sema_segment_id`(CC-01 只盖文本行,刻意),宿主认行用这把 uuid 就够了(整块换,不切片)。
+ *
+ * ── 🔴 宿主消费义务(与 `text_segment_end` 逐条同形)─────────────────────────────────────────
+ *  ① `diverged` 在场 ⇒ **自己拼 `stream_delta{channel:'thinking'}` 上屏**的端按 `content` 重渲该块;
+ *     只渲 transcript 平面的端零改动(包已把权威全文换进思考缓冲,下一次提交交的就是它)。
+ *  ② `committedPrefixDiverged` 在场 ⇒ **所有端都要做**:那条已 committed 的思考行(`uuid === committedUuid`)
+ *     是过期的,整块换成 `content`;本包在这一形上**一个字节都不再交**(再交一条 = 同一段推理上屏两遍)。
+ *  ③ 三键全缺席 ⇒ 照旧只当对账/定界,拿 `content` 再渲一行 = 同一段上屏两遍。
+ *  ④ 缺席 ≠ 段没结束:只有会报块结束的引擎才发它;按整条流判有没有边界帧。
+ */
+export interface ThinkingSegmentEndChromeEvent {
+    kind: 'thinking_segment_end';
+    laneProof: LaneProof;
+    /** 该段推理的**权威全文**(server ≥7.77.0 经脱敏器;可以与活体增量拼接不相等)。读法见义务 ①③。 */
+    content: string;
+    /** 活体面那份过期了(never false)。 */
+    diverged?: true;
+    /** 已 committed 的那条思考行过期了(never false)⇒ 整块换,本包不再交字节。 */
+    committedPrefixDiverged?: true;
+    /** 已 committed 思考行的全文长度(UTF-16 代码单元;never 0)—— 思考面上恒 = 整块。 */
+    committedPrefixLen?: number;
+    /** `committedPrefixDiverged` 在场时恒在场:要换掉的那条思考行的 `uuid`(本包铸)。 */
+    committedUuid?: string;
     /** core 铸的事件身份(uuidv7 形);wire 未必带 ⇒ 缺席时本键不在场。 */
     eventId?: string;
 }

package/dist/seam.js

@@ -78,6 +78,14 @@ const CHROME_ARM_TABLE = {
         required: false,
         duty: '可选:渲引擎通告(按 code+detail,message 仅 fallback;未知 code 也必须渲不许丢;durable 重放按 eventId 幂等;harvest 的 moved/escalated 并列呈现绝不相减)',
     },
+    thinking_segment_end: {
+        // CC-02(0.68.3):与 text_segment_end 同一类目的后果 —— server 7.77.0 起不接 = 未脱敏的推理字节留在
+        //    本地转录里(b2 形上那条明文思考行已经渲过 = 已发生的行为)⇒ `required: true`,理由同上臂。
+        required: true,
+        duty: '整段替换:①`diverged`(never false)在场 ⇒ 自己拼 thinking stream_delta 上屏的端按 content 重渲该块;' +
+            '②`committedPrefixDiverged`(never false)在场 ⇒ 所有端把 `uuid === committedUuid` 的那条已 committed 思考行**整块**换成 content(思考面无 idle-flush,前缀全有或全无,`committedPrefixLen` 恒 = 该行全文长度,单位 UTF-16 代码单元);' +
+            '本包在这一形上一个字节都不再交;③三键全缺席 ⇒ 照旧只当对账/定界;④缺席 ≠ 段没结束,按整条流判。',
+    },
     wiring_manifest: {
         required: false,
         duty: '可选:渲引擎接线自述里的三段用户面事实(modelGate = 本 run 被模型门卸掉的工具 + 逐字恢复办法;' +
@@ -124,7 +132,7 @@ const CHROME_ARM_TABLE = {
             '缺席 ⇒ 本包交的是尾段,前缀+尾段=content,什么都不用丢;③`committedPrefixLen`(never 0)= 定位量,' +
             '🔴 **单位 = JS 字符串长度(UTF-16 代码单元),不是 UTF-8 字节、也不是几条消息**' +
             '(按 UTF-8 字节截会在非 ASCII 正文上截错位置把凭据留在屏上;按消息丢会连合并在同一条消息里的上一段定稿一起删掉),' +
-            '照抄 `已committed正文.slice(0, 长度 - committedPrefixLen) + content`;按**增量拼文**计长、不是 content 上的偏移;④三键全缺席 ⇒ 照旧只当对账/定界,拿 content 再渲一行 = 同一段上屏两遍。' +
+            '照抄 `已committed正文.slice(0, 长度 - committedPrefixLen) + content`;按**增量拼文**计长、不是 content 上的偏移;④三键全缺席 ⇒ 照旧只当对账/定界,拿 content 再渲一行 = 同一段上屏两遍;⑤`segmentId`(恒在场)= 段身份,与本段已过境的 committed 文本行顶层 `_sema_segment_id` 同值 —— 换掉已提交那截时认行的钥匙是**两把**:行 uuid ∧ 段身份(按字节相等找行会被同后缀的独立行冒充)。' +
             '🔴 缺席只表示「没报」,绝不等于「段没结束」——要退回自家启发式必须按整条流判、不按单帧判',
     },
 };

package/dist/workflowClient.d.ts

@@ -71,6 +71,13 @@ export interface WorkflowParkRowView {
     sessionId: string;
     /** 最初跑出这只 park 的那条 run。 */
     originRunId: string;
+    /**
+     * core 7.18.0 #755(0.68.3 CC-05):这一行**在记录上**,但还没有任何 journal 确认它属于谁 ——
+     * `originRunId` 此时说的是「材料**属于**哪条 run」,不是「在哪条 run 上见过」,消费端**禁**当已确认读。
+     * never-false:确认那一刻上游**删键**(绝不写 `false`)⇒ 缺席 = 已确认(与 7.18.0 之前写的行同读)。
+     * 本包逐字投影(core 顶注:same projection obligation as `parks` —— 丢了就把一条未确认行读成已确认)。
+     */
+    originUnconfirmed?: true;
 }
 /**
  * `GET /v1/workflows/:id` 的 `parks[]` → 三键行;**整键缺席 ⇒ `undefined`**(与空数组逐字可分)。
@@ -85,6 +92,19 @@ export interface WorkflowParkRowView {
  * 🔴 纯函数、零副作用、**绝不抛**。
  */
 export declare function readWorkflowParks(run: unknown): readonly WorkflowParkRowView[] | undefined;
+/**
+ * `GET /v1/workflows/:id` 的 `resumeAdmissionIncomplete`(core 7.18.0 #755,0.68.3 CC-05)——
+ * 「这条 resume run 的准入**没有完成**」:记录从创建起带 `true`,准入完成那一刻**删键**。
+ *
+ * 🔴 **在场 = 不是 resume 基**(引擎自己会拒 `workflow.park_truth_unreadable` / `admission_incomplete`,
+ *    且不从它派生候选);缺席 = 每条非 resume run 与每次完成了的准入的常态。⇒ 读者只认在场,
+ *    缺席不是断言。never-false:严格 `true` 才算在场,其余一律缺席。
+ * 🔴 与 {@link readWorkflowParks} **同一条投影义务**(core 顶注逐字:dropping it turns a refused record
+ *    back into an admissible one)—— 端渲 resume 候选 / 面板行时**必须**带上这一位;本包不把它折进
+ *    `parks` 的缺席(那一形有自己的两义,见 `readWorkflowParks` 顶注)。
+ * 🔴 纯函数、零副作用、绝不抛;坏载体 ⇒ `false`(不是「读不出」:这一位没有第三态)。
+ */
+export declare function readWorkflowResumeAdmissionIncomplete(run: unknown): boolean;
 /** 台账里的一个 agent(读口产物,只读快照;缺席 = 不知道,绝不渲成 0/空)。 */
 export interface WorkflowActivityAgentView {
     /** `ctx.agent` 调用的稳定身份(SSE 主键);老引擎/无 callKey 的帧上缺席。 */

package/dist/workflowClient.js

@@ -411,13 +411,31 @@ export function readWorkflowParks(run) {
             continue;
         // 🔴 **逐键铸**,不 spread:上游在这张行上多放一个键(尤其是凭据形)时,它在结构上到不了
         //    本包的产物。这不是风格选择 —— 它是本段 ① 那条红线的实现。
-        rows.push({ callKey, sessionId, originRunId });
+        // 7.18.0:第四键 never-false,严格 `true` 才铸(`false`/`"true"`/`1` 都是坏值 = 缺席 = 已确认)。
+        rows.push({ callKey, sessionId, originRunId, ...(o.originUnconfirmed === true ? { originUnconfirmed: true } : {}) });
     }
     // 非空输入而一行都没活下来 ⇒ 读不出,不是「零 park」(绝不铸 `[]` 冒充一句正面事实)。
     if (raw.length > 0 && rows.length === 0)
         return undefined;
     return rows;
 }
+/**
+ * `GET /v1/workflows/:id` 的 `resumeAdmissionIncomplete`(core 7.18.0 #755,0.68.3 CC-05)——
+ * 「这条 resume run 的准入**没有完成**」:记录从创建起带 `true`,准入完成那一刻**删键**。
+ *
+ * 🔴 **在场 = 不是 resume 基**(引擎自己会拒 `workflow.park_truth_unreadable` / `admission_incomplete`,
+ *    且不从它派生候选);缺席 = 每条非 resume run 与每次完成了的准入的常态。⇒ 读者只认在场,
+ *    缺席不是断言。never-false:严格 `true` 才算在场,其余一律缺席。
+ * 🔴 与 {@link readWorkflowParks} **同一条投影义务**(core 顶注逐字:dropping it turns a refused record
+ *    back into an admissible one)—— 端渲 resume 候选 / 面板行时**必须**带上这一位;本包不把它折进
+ *    `parks` 的缺席(那一形有自己的两义,见 `readWorkflowParks` 顶注)。
+ * 🔴 纯函数、零副作用、绝不抛;坏载体 ⇒ `false`(不是「读不出」:这一位没有第三态)。
+ */
+export function readWorkflowResumeAdmissionIncomplete(run) {
+    if (typeof run !== 'object' || run === null || Array.isArray(run))
+        return false;
+    return run.resumeAdmissionIncomplete === true;
+}
 // ── 轮询/退避节拍(REF-CC-131,域词表-15):三个 3000ms 常量语义各不相同,拆开命名——合并成一个
 // 会把三条独立的退避策略绑死在一起(其中任一策略调优都会误伤另外两条)。──────────────────────
 /** owner 名下暂无任何 run(`resolveRunId` 回 null)时的重试间隔:不是错误,只是「还没有可监的