@sema-agent/client-core 0.74.1 → 0.74.3

package/dist/runCancelContext.d.ts

@@ -0,0 +1,49 @@
+/**
+ * runCancelContext — run 记录上 server 自铸的**取消现场**侧记键 `cancelContext`(server ≥7.87.3 `PersistedTaskResult =
+ * TaskResult & { cancelContext? }`,`dist/plugins/store-contracts.d.ts` `RunCancelContext` 四座)的三端共用读面,与
+ * `turn_aborted{reason:'engine_error'}` 之后「到底是谁把这条 run 结掉的」的**成因判定**(0.74.3 CC-71;cli L-212 (a) 消费半场归包)。
+ * sdk 9.7.1 对该键无型 ⇒ 按契约结构读。
+ *
+ * ── 🔴 读法 ─────────────────────────────────────────────────────────────────────────────────
+ *  ① `cancelContext` 缺席 = 老 server / 这条 run 不是被取消的 / 记录形不带 —— **不折成「未取消」**,读数是 `not_reported`。
+ *  ② 四座各自可缺席、各自防御读:`lastEventKind`(串)/ `lastEventAgeMs`(≥0 有限数)/ `elapsedMs`(≥0 有限数;绝不折 0)/
+ *     `lastBrainStatus`(对象,原样带出不窄读)。「有 age 无 kind」是合法读数。
+ *  ③ 成因判定 {@link classifyRunAbortCause}:只由 run 记录上的**机读证据**得出 —— `errorCode` ∈ 取消码 ⇒ `cancelled_by_user`;
+ *     `cancelContext` 在场而码不是取消码 ⇒ 仍按码判(现场只是附注);码缺席 / 认不出 ⇒ `unknown`。**缺席不猜**。
+ */
+/** 四座读数(在场才带)。 */
+export interface RunCancelContextView {
+    readonly lastEventKind?: string;
+    readonly lastEventAgeMs?: number;
+    readonly elapsedMs?: number;
+    readonly lastBrainStatus?: Readonly<Record<string, unknown>>;
+}
+export type RunCancelContextReading = {
+    kind: 'not_reported';
+} | {
+    kind: 'present';
+    context: RunCancelContextView;
+};
+/** run 记录(`runs.get` 回体 / `done.result`)→ 取消现场读数;记录非对象 ⇒ `undefined`(判不出,与 not_reported 分开)。 */
+export declare function readRunCancelContext(record: unknown): RunCancelContextReading | undefined;
+import { type RunTerminalRead } from './runTerminal.js';
+export type RunAbortCause = {
+    kind: 'cancelled';
+    context?: RunCancelContextView;
+} | {
+    kind: 'engine_error';
+    code?: string;
+    message?: string;
+}
+/** run 记录仍非终态:流断了而 run 还在(壳这一端的事实,不是 run 的成因)。`status` 原词。 */
+ | {
+    kind: 'run_still_live';
+    status?: string;
+} | {
+    kind: 'unknown';
+    terminal?: RunTerminalRead['kind'];
+};
+/** 取消码常量(server `CANCELLED_CODE` / sdk runs.d.ts 逐字)。 */
+export declare const RUN_CANCELLED_CODE: "cancelled";
+/** 壳带 `engineTaskId` 去 `runs.get` 拿回的记录 ⇒ 成因。只由机读证据得出;缺席不猜。 */
+export declare function classifyRunAbortCause(record: unknown): RunAbortCause;

package/dist/runCancelContext.js

@@ -0,0 +1,81 @@
+/**
+ * runCancelContext — run 记录上 server 自铸的**取消现场**侧记键 `cancelContext`(server ≥7.87.3 `PersistedTaskResult =
+ * TaskResult & { cancelContext? }`,`dist/plugins/store-contracts.d.ts` `RunCancelContext` 四座)的三端共用读面,与
+ * `turn_aborted{reason:'engine_error'}` 之后「到底是谁把这条 run 结掉的」的**成因判定**(0.74.3 CC-71;cli L-212 (a) 消费半场归包)。
+ * sdk 9.7.1 对该键无型 ⇒ 按契约结构读。
+ *
+ * ── 🔴 读法 ─────────────────────────────────────────────────────────────────────────────────
+ *  ① `cancelContext` 缺席 = 老 server / 这条 run 不是被取消的 / 记录形不带 —— **不折成「未取消」**,读数是 `not_reported`。
+ *  ② 四座各自可缺席、各自防御读:`lastEventKind`(串)/ `lastEventAgeMs`(≥0 有限数)/ `elapsedMs`(≥0 有限数;绝不折 0)/
+ *     `lastBrainStatus`(对象,原样带出不窄读)。「有 age 无 kind」是合法读数。
+ *  ③ 成因判定 {@link classifyRunAbortCause}:只由 run 记录上的**机读证据**得出 —— `errorCode` ∈ 取消码 ⇒ `cancelled_by_user`;
+ *     `cancelContext` 在场而码不是取消码 ⇒ 仍按码判(现场只是附注);码缺席 / 认不出 ⇒ `unknown`。**缺席不猜**。
+ */
+function nonNegFinite(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
+}
+/** run 记录(`runs.get` 回体 / `done.result`)→ 取消现场读数;记录非对象 ⇒ `undefined`(判不出,与 not_reported 分开)。 */
+export function readRunCancelContext(record) {
+    if (record === null || typeof record !== 'object')
+        return undefined;
+    const r = record;
+    // 记录形两种:顶层 `result.cancelContext`(PersistedTaskResult)或已经是 result 本身。
+    const holder = r.result !== null && typeof r.result === 'object' ? r.result : r;
+    if (!Object.hasOwn(holder, 'cancelContext') || holder.cancelContext === undefined)
+        return { kind: 'not_reported' };
+    const c = holder.cancelContext;
+    if (c === null || typeof c !== 'object' || Array.isArray(c))
+        return undefined;
+    const o = c;
+    const kind = typeof o.lastEventKind === 'string' && o.lastEventKind.length > 0 ? o.lastEventKind : undefined;
+    const age = nonNegFinite(o.lastEventAgeMs);
+    const elapsed = nonNegFinite(o.elapsedMs);
+    const brain = o.lastBrainStatus !== null && typeof o.lastBrainStatus === 'object' && !Array.isArray(o.lastBrainStatus) ? o.lastBrainStatus : undefined;
+    return {
+        kind: 'present',
+        context: {
+            ...(kind !== undefined ? { lastEventKind: kind } : {}),
+            ...(age !== undefined ? { lastEventAgeMs: age } : {}),
+            ...(elapsed !== undefined ? { elapsedMs: elapsed } : {}),
+            ...(brain !== undefined ? { lastBrainStatus: brain } : {}),
+        },
+    };
+}
+// ── 成因判定(闭集四词;cli L-212 (a) 对齐)────────────────────────────────────────────────
+//
+// 字节出处(cli 亲 grep server 7.87.3 dist):
+//   · 被取消 = 唯一铸点 `run-cancel-context.js` `mintCancelledResult` ⇒ `terminal:{kind:"failed", code:"cancelled"}`,
+//     且**只有这条路**挂 `cancelContext`;
+//   · 引擎错 = `terminal.kind === "failed"` 且 code !== "cancelled";code 是 core 的**开集**(network / brain.* / limits.* …)⇒ 只渲原码,不枚举;
+//   · 客户端断连**没有独立字节**:server 走的是 detach / park(durable run 继续跑、在等的 ask 停驻),run 记录不会因此失败 ⇒
+//     它不是 run 的成因,是壳这一端的事实 —— 判法 = run 记录仍非终态(running / queued / suspended / needs_review)⇒ `run_still_live`。
+//   · 别的(完成 / 挡住 / 读不出终态词)⇒ `unknown`,不猜。
+import { readRunTerminal } from './runTerminal.js';
+/** 取消码常量(server `CANCELLED_CODE` / sdk runs.d.ts 逐字)。 */
+export const RUN_CANCELLED_CODE = 'cancelled';
+const LIVE_STATUSES = new Set(['running', 'queued', 'suspended', 'needs_review']);
+/** 壳带 `engineTaskId` 去 `runs.get` 拿回的记录 ⇒ 成因。只由机读证据得出;缺席不猜。 */
+export function classifyRunAbortCause(record) {
+    if (record === null || typeof record !== 'object')
+        return { kind: 'unknown' };
+    const r = record;
+    const status = typeof r.status === 'string' && r.status.length > 0 ? r.status : undefined;
+    const holder = r.result !== null && typeof r.result === 'object' ? r.result : record;
+    const read = readRunTerminal(holder);
+    if (read !== null && read.kind === 'failed') {
+        if (read.code === RUN_CANCELLED_CODE) {
+            const cc = readRunCancelContext(record);
+            return { kind: 'cancelled', ...(cc?.kind === 'present' ? { context: cc.context } : {}) };
+        }
+        return { kind: 'engine_error', ...(read.code !== undefined ? { code: read.code } : {}), ...(read.message !== undefined ? { message: read.message } : {}) };
+    }
+    // 非终态 = run 还活着:嵌套 paused 臂 / 平面 paused 词 / 行上 status 仍是在飞词(平面读器对 running / queued 答 unknown{word},
+    // 那不是「读不出」,是「还没结」—— 所以先看 status 再落 unknown)。
+    if (read !== null && read.kind === 'paused')
+        return { kind: 'run_still_live', ...(status !== undefined ? { status } : {}) };
+    // 异源复审 R2 [medium]:result 已是终态(completed / blocked)而行上 status 还是在飞词 = 两处证据矛盾 ⇒ unknown(带观测到的终态词),
+    // 不按外层 status 说「还活着」——result 是终局记录,行状态可能滞后;矛盾不是 liveness 的证据。
+    if ((read === null || read.kind === 'unknown') && status !== undefined && LIVE_STATUSES.has(status))
+        return { kind: 'run_still_live', status };
+    return { kind: 'unknown', ...(read !== null ? { terminal: read.kind } : {}) };
+}

package/dist/sqlEngineCapability.js

@@ -43,7 +43,7 @@
  */
 import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
-import { engineCapsGeneration } from './engineCapsCache.js';
+import { snapshotCapsGeneration, capsGenerationStillCurrent } from './engineCapsGenerationGuard.js';
 /**
  * caps 回体 → 本格读数;**畸形一律 `undefined`**(= 这一格不写 ⇒ 读口答 `unobserved`)。
  *
@@ -66,15 +66,19 @@ export function projectSqlEngineCapability(caps) {
     if (typeof sql !== 'object')
         return undefined;
     const s = sql;
-    if (typeof s.engine !== 'string' || s.engine === '')
+    // 🔴 只读一次(0.74.2 CC-69 复审 R1 族扫):校验与返回各读一次,变化的 getter 会让校验读到合形、返回读到别的。
+    const engine = s.engine;
+    const isolation = s.isolation;
+    const txnMode = s.txnMode;
+    if (typeof engine !== 'string' || engine === '')
         return undefined;
-    if (typeof s.isolation !== 'string' || s.isolation === '')
+    if (typeof isolation !== 'string' || isolation === '')
         return undefined;
     // 🔴 `txnMode`:`null` 是**铸点域内的合法值**(见 SqlEngineCapabilityView 顶注),不是畸形。
     //    但这一位在铸点上**恒在场** ⇒ 键缺席(`undefined`)与非串非 null 仍判载体坏了。
-    if (s.txnMode !== null && (typeof s.txnMode !== 'string' || s.txnMode === ''))
+    if (txnMode !== null && (typeof txnMode !== 'string' || txnMode === ''))
         return undefined;
-    return { kind: 'present', view: { engine: s.engine, isolation: s.isolation, txnMode: s.txnMode } };
+    return { kind: 'present', view: { engine, isolation, txnMode } };
 }
 const readingByBase = new Map();
 /**
@@ -99,22 +103,32 @@ const readingByBase = new Map();
  *    有任何东西变坏。🔴 **tee 自己抓号是假判据**(陈旧那一发在这里读到的是新代号,永远像当代的)。
  */
 export function noteEngineCapsForSqlEngine(baseUrl, caps, opts) {
+    if (typeof baseUrl !== 'string' || baseUrl === '')
+        return;
+    // 🔴 代际只在入口**快照一次**(异源对抗复审 R3):opts 是调用方的对象,回体上的 getter 能在投影中途改它;首末两次核对都用这份快照,
+    //    读 opts / 读代际抛出 ⇒ 不动格(与陈旧代际同一处置)。
+    const gen = snapshotCapsGeneration(opts);
+    if (gen === null)
+        return; // 调用方 opts 的 getter 抛出 = 供给坏了 ⇒ 不动格
+    if (!capsGenerationStillCurrent(baseUrl, gen))
+        return;
+    let reading;
     try {
-        if (typeof baseUrl !== 'string' || baseUrl === '')
-            return;
-        // 陈旧代际的那一发整只丢掉(见本函数顶注的 `opts.generation` 段);不传 ⇒ 照写,零行为变化。
-        if (opts?.generation !== undefined && opts.generation !== engineCapsGeneration(baseUrl))
-            return;
-        const reading = projectSqlEngineCapability(caps);
-        if (reading === undefined) {
-            readingByBase.delete(baseUrl);
-            return;
-        }
-        readingByBase.set(baseUrl, reading);
+        reading = projectSqlEngineCapability(caps);
     }
     catch {
-        /* fail-soft:本 tee 任何分支都不许打断 caps 探测链 */
+        // 🔴 0.74.2 同形存量(CC-69 复审 R1 族扫):抛 getter / Proxy 的回体 = 畸形,与「投影答 undefined」同一处置 —— 删格,不许留着上一台的读数。
+        reading = undefined;
+    }
+    // 🔴 投影之后**再核一次代际**(异源对抗复审 R2):投影会执行回体上不可信的 getter,它可以在中途让这一格换代
+    //    (invalidate + 新代际的 tee 已写入);此时无论投影返回还是抛出,都不许动新代际的格。
+    if (!capsGenerationStillCurrent(baseUrl, gen))
+        return;
+    if (reading === undefined) {
+        readingByBase.delete(baseUrl);
+        return;
     }
+    readingByBase.set(baseUrl, reading);
 }
 /**
  * 本进程观测到的 SQL 姿态;这一格空缺 ⇒ `{kind:'unobserved'}`(**绝不**折成 `none`)。
@@ -159,8 +173,8 @@ export function sqlEngineDoctorDetail(reading) {
     switch (reading.kind) {
         case 'unobserved':
             // 0.59.2(cli B-038):不点名任何端的命令 —— 「去哪里看」是端的事,包只说事实。
-            return ('not observed — the engine reports it on /v1/capabilities; this process has not received ' +
-                'a capabilities response from the engine yet');
+            return ('not observed — the engine reports it on /v1/capabilities; this process has no usable ' +
+                'capabilities reading cached for it (none received, or the last one was unreadable)');
         case 'not_reported':
             return 'not reported by this engine — the capability position needs a newer engine';
         case 'none':

package/dist/webSearchBackendCapability.js

@@ -38,7 +38,7 @@
  */
 import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
-import { engineCapsGeneration } from './engineCapsCache.js';
+import { snapshotCapsGeneration, capsGenerationStillCurrent } from './engineCapsGenerationGuard.js';
 /** `backend: "none"` —— 唯一带独立语义的词(见文件头);其余词按开集读。 */
 export const WEB_SEARCH_BACKEND_NONE = 'none';
 /**
@@ -77,21 +77,32 @@ const readingByBase = new Map();
  *    那一刻 `engineCapsGeneration(baseUrl)` 抓号、在这里原样交回,陈旧那一发整只丢掉;不传 ⇒ 照写。
  */
 export function noteEngineCapsForWebSearchBackend(baseUrl, caps, opts) {
+    if (typeof baseUrl !== 'string' || baseUrl === '')
+        return;
+    // 🔴 代际只在入口**快照一次**(异源对抗复审 R3):opts 是调用方的对象,回体上的 getter 能在投影中途改它;首末两次核对都用这份快照,
+    //    读 opts / 读代际抛出 ⇒ 不动格(与陈旧代际同一处置)。
+    const gen = snapshotCapsGeneration(opts);
+    if (gen === null)
+        return; // 调用方 opts 的 getter 抛出 = 供给坏了 ⇒ 不动格
+    if (!capsGenerationStillCurrent(baseUrl, gen))
+        return;
+    let reading;
     try {
-        if (typeof baseUrl !== 'string' || baseUrl === '')
-            return;
-        if (opts?.generation !== undefined && opts.generation !== engineCapsGeneration(baseUrl))
-            return;
-        const reading = projectWebSearchBackendCapability(caps);
-        if (reading === undefined) {
-            readingByBase.delete(baseUrl);
-            return;
-        }
-        readingByBase.set(baseUrl, reading);
+        reading = projectWebSearchBackendCapability(caps);
     }
     catch {
-        /* fail-soft:本 tee 任何分支都不许打断 caps 探测链 */
+        // 🔴 0.74.2 同形存量(CC-69 复审 R1 族扫):抛 getter / Proxy 的回体 = 畸形,与「投影答 undefined」同一处置 —— 删格,不许留着上一台的读数。
+        reading = undefined;
+    }
+    // 🔴 投影之后**再核一次代际**(异源对抗复审 R2):投影会执行回体上不可信的 getter,它可以在中途让这一格换代
+    //    (invalidate + 新代际的 tee 已写入);此时无论投影返回还是抛出,都不许动新代际的格。
+    if (!capsGenerationStillCurrent(baseUrl, gen))
+        return;
+    if (reading === undefined) {
+        readingByBase.delete(baseUrl);
+        return;
     }
+    readingByBase.set(baseUrl, reading);
 }
 /** 本进程观测到的部署默认后端;这一格空缺 ⇒ `{kind:'unobserved'}`(**绝不**折成 `none`)。 */
 export function observedWebSearchBackend(baseUrl = engineWireTarget()?.baseUrl) {
@@ -115,7 +126,7 @@ export function webSearchBackendDoctorDetail(reading) {
     switch (reading.kind) {
         case 'unobserved':
             return ('deployment default backend not observed — the engine reports it on /v1/capabilities; ' +
-                'this process has not received a capabilities response from the engine yet');
+                'this process has no usable capabilities reading cached for it (none received, or the last one was unreadable)');
         case 'not_reported':
             return ('deployment default backend not reported by this engine — only newer engines advertise it; ' +
                 'this does not say whether the deployment has a search backend');

package/dist/writeProtectionCapability.js

@@ -31,7 +31,7 @@
  */
 import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
-import { engineCapsGeneration } from './engineCapsCache.js';
+import { snapshotCapsGeneration, capsGenerationStillCurrent } from './engineCapsGenerationGuard.js';
 /**
  * caps 回体 → 本格读数;**畸形一律 `undefined`**(= 这一格不写 ⇒ 读口答 `unobserved`)。
  *
@@ -55,13 +55,17 @@ export function projectWriteProtectionCapability(caps) {
     if (typeof wp !== 'object' || Array.isArray(wp))
         return undefined;
     const w = wp;
-    if (typeof w.armed !== 'boolean')
+    // 🔴 只读一次(0.74.2 CC-69 复审 R1 族扫):校验与返回各读一次,变化的 getter 会让校验读到合形、返回读到别的。
+    const armed = w.armed;
+    const replaced = w.replaced;
+    const rows = w.rows;
+    if (typeof armed !== 'boolean')
         return undefined;
-    if (typeof w.replaced !== 'boolean')
+    if (typeof replaced !== 'boolean')
         return undefined;
-    if (typeof w.rows !== 'number' || !Number.isInteger(w.rows) || w.rows < 0)
+    if (typeof rows !== 'number' || !Number.isInteger(rows) || rows < 0)
         return undefined;
-    return { kind: 'present', view: { armed: w.armed, rows: w.rows, replaced: w.replaced } };
+    return { kind: 'present', view: { armed, rows, replaced } };
 }
 /**
  * operator 面回体的 `writeProtection` 段 → 读数;不成形 ⇒ `undefined`。
@@ -124,22 +128,32 @@ const readingByBase = new Map();
  *    有任何东西变坏。🔴 **tee 自己抓号是假判据**(陈旧那一发在这里读到的是新代号,永远像当代的)。
  */
 export function noteEngineCapsForWriteProtection(baseUrl, caps, opts) {
+    if (typeof baseUrl !== 'string' || baseUrl === '')
+        return;
+    // 🔴 代际只在入口**快照一次**(异源对抗复审 R3):opts 是调用方的对象,回体上的 getter 能在投影中途改它;首末两次核对都用这份快照,
+    //    读 opts / 读代际抛出 ⇒ 不动格(与陈旧代际同一处置)。
+    const gen = snapshotCapsGeneration(opts);
+    if (gen === null)
+        return; // 调用方 opts 的 getter 抛出 = 供给坏了 ⇒ 不动格
+    if (!capsGenerationStillCurrent(baseUrl, gen))
+        return;
+    let reading;
     try {
-        if (typeof baseUrl !== 'string' || baseUrl === '')
-            return;
-        // 陈旧代际的那一发整只丢掉(见本函数顶注的 `opts.generation` 段);不传 ⇒ 照写,零行为变化。
-        if (opts?.generation !== undefined && opts.generation !== engineCapsGeneration(baseUrl))
-            return;
-        const reading = projectWriteProtectionCapability(caps);
-        if (reading === undefined) {
-            readingByBase.delete(baseUrl);
-            return;
-        }
-        readingByBase.set(baseUrl, reading);
+        reading = projectWriteProtectionCapability(caps);
     }
     catch {
-        /* fail-soft:本 tee 任何分支都不许打断 caps 探测链 */
+        // 🔴 0.74.2 同形存量(CC-69 复审 R1 族扫):抛 getter / Proxy 的回体 = 畸形,与「投影答 undefined」同一处置 —— 删格,不许留着上一台的读数。
+        reading = undefined;
+    }
+    // 🔴 投影之后**再核一次代际**(异源对抗复审 R2):投影会执行回体上不可信的 getter,它可以在中途让这一格换代
+    //    (invalidate + 新代际的 tee 已写入);此时无论投影返回还是抛出,都不许动新代际的格。
+    if (!capsGenerationStillCurrent(baseUrl, gen))
+        return;
+    if (reading === undefined) {
+        readingByBase.delete(baseUrl);
+        return;
     }
+    readingByBase.set(baseUrl, reading);
 }
 /** 本进程观测到的写保护姿态;这一格空缺 ⇒ `{kind:'unobserved'}`(**绝不**折成 `none`)。 */
 export function observedWriteProtection(baseUrl = engineWireTarget()?.baseUrl) {
@@ -162,8 +176,8 @@ const WP_DETAIL_MAX = 40;
 export function writeProtectionDoctorDetail(reading) {
     switch (reading.kind) {
         case 'unobserved':
-            return ('not observed — the engine reports it on /v1/capabilities; this process has not received ' +
-                'a capabilities response from the engine yet');
+            return ('not observed — the engine reports it on /v1/capabilities; this process has no usable ' +
+                'capabilities reading cached for it (none received, or the last one was unreadable)');
         case 'not_reported':
             return ('not reported by this engine — the capability position needs a newer engine; this says ' +
                 'nothing about whether a protected-name table is in effect (an absent seat is the engine ' +