@sema-agent/client-core 0.67.1 → 0.68.0

package/dist/adapter/activeRunSelfHeal.js

@@ -173,6 +173,53 @@ function readStatus(record) {
     const st = record?.status;
     return typeof st === 'string' && st.length > 0 ? st : null;
 }
+/**
+ * 「这条 run 还占着会话吗」的**直接读数**(0.68.0 / L-230;server 7.73.0 S-122 P-45:
+ * `GET /v1/runs/:id` 上的 `heldBy`)。
+ *
+ * 三态,**刻意不是布尔**:
+ *  · `'held'`     —— `heldBy` 是一个非空串 = **有一条 run 名字在上面**,它确实还占着;
+ *  · `'released'` —— `heldBy` 显式是 `null` = 一句**正面事实**:会话已经交出来了;
+ *  · `'unknown'`  —— 这一位**整键缺席**(老引擎 / 不发这一位的部署),或者形不对
+ *    (非串非 null)⇒ 读不出,**绝不**当成 released。
+ *
+ * 🔴 `null` 与「键不在」必须分开,这是本读器存在的全部理由:
+ *    把两者都读成「释放了」,老引擎上每一次探测都会当场答「已释放」并立刻重发那条消息 ——
+ *    而它可能一头撞回一个还锁着的会话(再吃一个 409,正是这条腿存在的理由);
+ *    把两者都读成「还占着」,新引擎上那句正面事实白给了,窗要一直等到点。
+ * 🔴 判据用 `Object.hasOwn`:`{heldBy: undefined}` 与 `{}` 在这里是**同一件事**(都读不出),
+ *    而 `null` 必须与它们分开 —— 靠 `?? ` / `!= null` 一类写法分不出来。
+ */
+function readClaimHolder(record) {
+    if (record === null || typeof record !== 'object')
+        return 'unknown';
+    if (!Object.hasOwn(record, 'heldBy'))
+        return 'unknown';
+    const v = record.heldBy;
+    if (v === null)
+        return 'released';
+    if (typeof v === 'string' && v.length > 0)
+        return 'held';
+    // 空串 / 数 / 对象:形不对 ⇒ 读不出(失效方向在保守那一侧:不宣告释放)。
+    return 'unknown';
+}
+/**
+ * cancel 回执(202 体)/ run 行上的 `cancelRequested`(0.68.0 / L-230;server 7.73.0 S-122 P-45)。
+ *
+ * 🔴 **三态**同上:`true` / `false` 都是真读数,**读不出 ⇒ `undefined`**(老引擎不发这一位)。
+ *    绝不折 `false` —— 「没请求过取消」与「不知道有没有请求过」对下一步的含义不同:前者可以放心
+ *    再发一次 cancel,后者再发就可能是第二枪。
+ * 🔴 它**不是**「已经取消了」:上游逐字是 *requested*,一次**已受理的请求**,不是终局。
+ *    会话有没有交出来仍然只由 {@link readClaimHolder} 与 {@link CLAIM_RELEASED_STATES} 回答。
+ */
+export function readCancelRequested(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return undefined;
+    if (!Object.hasOwn(body, 'cancelRequested'))
+        return undefined;
+    const v = body.cancelRequested;
+    return typeof v === 'boolean' ? v : undefined;
+}
 /** 重开判决 → 结局(真呈现回执消费点:`presented === false` 时 reopened 断言不成立)。 */
 function reopenDelivered(verdict) {
     return verdict.reopened === true && verdict.presented !== false;
@@ -339,28 +386,33 @@ export async function waitForClaimRelease(taskId, deps) {
     const isAborted = () => deps.signal?.aborted === true;
     let delay = CANCEL_POLL_START_MS;
     let lastStatus = null;
+    // 🔴 0.68.0 / L-230:`heldBy` 的三态与 `lastStatus` **同律** —— 只记最近一次**有回答**的探测。
+    let lastHolder = 'unknown';
     for (;;) {
         if (isAborted())
-            return { released: false, waitedMs: waited(), aborted: true, lastStatus };
+            return { released: false, waitedMs: waited(), aborted: true, lastStatus, lastHolder };
         const remaining = deadline - now();
         if (remaining <= 0)
-            return { released: false, waitedMs: waited(), aborted: false, lastStatus };
+            return { released: false, waitedMs: waited(), aborted: false, lastStatus, lastHolder };
         await sleep(Math.min(delay, remaining), deps.signal);
         if (isAborted())
-            return { released: false, waitedMs: waited(), aborted: true, lastStatus };
+            return { released: false, waitedMs: waited(), aborted: true, lastStatus, lastHolder };
         delay = Math.min(Math.round(delay * 1.5), CANCEL_POLL_MAX_MS);
         let status;
+        let holder;
         const lease = claimProbeLease(deps.signal, deadline - now());
         try {
-            status = readStatus(await deps.get(taskId, {
+            const record = await deps.get(taskId, {
                 signal: lease.signal,
                 ...(deps.session !== undefined ? { session: deps.session } : {}),
-            }));
+            });
+            status = readStatus(record);
+            holder = readClaimHolder(record);
         }
         catch {
             lease.release();
             if (isAborted())
-                return { released: false, waitedMs: waited(), aborted: true, lastStatus };
+                return { released: false, waitedMs: waited(), aborted: true, lastStatus, lastHolder };
             // 🔴 本发是被**窗自己的截止**掐掉的(lease 到点;caller 未中止)⇒ 没有读到任何回答 ——
             // 既不是释放证据,也不是「读不出来」的新证据,上一发**完成了的**读数保持在座(#244 F1
             // 换装批 G-c 尾竞态定谳:R2 [medium] 的「只记最近一次」指最近一次**有回答**的探测 ——
@@ -371,6 +423,7 @@ export async function waitForClaimRelease(taskId, deps) {
             // 这一发**有回答但读不出**(404/传输错)⇒ 最新证据是「不知道」,陈旧的成功读数当场作废
             // (见 lastStatus 头注)。
             lastStatus = null;
+            lastHolder = 'unknown';
             // 🔴 **404 也只是「读不到」,不是「释放了」**(二次评审 [high] 处置,2026-08-14):这个读口的
             // 404 在 SDK 契约上是 `not_found.run` —— 「这条 run 不存在」与「它不是你的」**共用同一个码,
             // 且是刻意设计的不可分辨**(跨租户不给存在性预言机)。凭它断言「那条 run 已经不占着会话」,
@@ -381,10 +434,22 @@ export async function waitForClaimRelease(taskId, deps) {
         }
         lease.release(); // 🔴 定时器必清:这只是**普通**定时器(见 claimProbeLease),不清就把进程多拖活一拍
         lastStatus = status; // 奇形记录(读不出 status)同样把陈旧读数清掉 —— 最新证据仍是「不知道」
+        lastHolder = holder;
+        // ── 🔴 0.68.0 / L-230(server 7.73.0 S-122 P-45 读面消费)—— **两条释放证据,取并** ────────
+        // ① `heldBy === null` —— 引擎**直说**会话交出来了。这是本批新接的那条,而且它比 ② 强:
+        //    ② 是拿「run 走到了某个终态词」去**推断**锁没了,而锁与 run 的生命周期不是同一件事
+        //    (park 态保留 claim 正是这条推断会踩的坑,也是 `CLAIM_RELEASED_STATES` 是白名单而不是
+        //    「running 之外的一切」的原因)。有直接证据就别再推断。
+        // ② `status ∈ CLAIM_RELEASED_STATES` —— 老引擎不发 `heldBy`(读出 `'unknown'`)时的**既有路**,
+        //    一字未动。⇒ 本件对老引擎**零行为变化**;对新引擎多了一条更早、更硬的收口证据。
+        // 🔴 `'unknown'` 绝不当成释放:缺席不是证据(与本文件 404 那一格逐字同一条纪律)。
+        if (holder === 'released') {
+            return { released: true, waitedMs: waited(), aborted: false, lastStatus: status, lastHolder: holder };
+        }
         // status 读不出(奇形记录)/ 还在跑 / park / 没想过的新词 ⇒ 都不算释放,继续等到点(保守方向:
         // 宁可不重发)。判据见 {@link CLAIM_RELEASED_STATES}。
         if (status !== null && CLAIM_RELEASED_STATES.includes(status)) {
-            return { released: true, waitedMs: waited(), aborted: false, lastStatus: status };
+            return { released: true, waitedMs: waited(), aborted: false, lastStatus: status, lastHolder: holder };
         }
     }
 }
@@ -800,7 +865,13 @@ async function cancelAndConfirmRelease(taskId, durable, durableGet, deps) {
         outcome: 'timeout',
         waitedMs: verdict.waitedMs,
         aborted: verdict.aborted,
-        confirmedHeld: verdict.lastStatus !== null && CLAIM_HELD_STATES.includes(verdict.lastStatus),
+        // 🔴 0.68.0 / L-230:**两条持锁证据取并**,直接证据优先 ——
+        //    ① `heldBy` 读出 `'held'` = 引擎**直说**那条 run 还占着(server 7.73.0 S-122 P-45 读面);
+        //    ② 老引擎不发那一位(`'unknown'`)⇒ 回落既有的按状态词推断({@link CLAIM_HELD_STATES})。
+        //    🔴 `'released'` 在这里到不了(released 的判决在上面就 return 了),`'unknown'` 不算证据 ——
+        //    两条都答不出时仍然收口成 `false` = 「确认不了」,文案绝不说「它还占着」。
+        confirmedHeld: verdict.lastHolder === 'held' ||
+            (verdict.lastStatus !== null && CLAIM_HELD_STATES.includes(verdict.lastStatus)),
     };
 }
 /**

package/dist/adapter/downstream/eventToSdkMessage.d.ts

@@ -235,7 +235,24 @@ export interface WiringManifestMcpEntry {
  * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
  * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no
  * standalone usage SDKMessage arm; the run driver folds it into the footer /
- * terminal rollup. Returns `undefined` when the optional `usage` is absent.
+ * terminal rollup.
+ *
+ * ── 🔴 0.68.0 BREAKING(core 7.17.0 #711;异源对抗复审轮三实抓的**第五处**)──────────────────
+ * 返回 `undefined` 的含义从「`usage` 这一格缺席」收窄成 **「这一轮的账不知道」**,两种入形都答它:
+ *   ① `ev.usage` 整个缺席 —— #711 之后这**不再是一条合法形**(契约违约;`runStream` 那一层另有
+ *      响亮留痕,本读器只如实答「不知道」);
+ *   ② `usageMissing: true` **且六格全是 0** —— 那正是 core 的**占位**
+ *      (`rs.turn.turnUsage ?? {六个 0}`,`run-harness-handlers.js:289-293`)。
+ * 🔴 为什么必须改:#711 之前,「这一轮没量出账」这件事在 wire 上的形是**不发 usage** ⇒ 本函数答
+ *    `undefined`;#711 之后同一件事的形变成六个 0,而本函数是**公面导出** —— 不改的话,同一个真实
+ *    情形在引擎升级前后由同一个公开读器给出两个相反的答案(「不知道」变成「这一轮恰好花了 0」),
+ *    而调用方**一个字都没改**。收窄之后跨引擎升级的答案**逐字不变**。
+ * 🔴 **非零照交**:`usageMissing` 并不保证六格是零(core 在同一轮里可能已攒到真数字而另一次调用
+ *    报了缺账 ⇒ 判别位与真数字同帧并存)。占位恒为全零,所以**任何一格非零**都说明这一轮真的量到过
+ *    ⇒ 照交镜像(那些数字是**下界**,而「是不是下界」由帧上的 `usageMissing` / 终帧的
+ *    `_sema_usage_lower_bound` 回答,不由本函数回答)。
+ * ⚠️ 要**原样**的 wire 镜像(不做任何判断)请直接调 {@link turnUsageToModelUsage} —— 那一只是
+ *    纯映射,本函数是**带缺席语义的读器**,两者刻意分开。
  */
 export declare function turnEndUsage(ev: Extract<AgentEvent, {
     type: 'turn_end';

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -1198,10 +1198,41 @@ function humanInputProjection(ev, ctx) {
  * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
  * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no
  * standalone usage SDKMessage arm; the run driver folds it into the footer /
- * terminal rollup. Returns `undefined` when the optional `usage` is absent.
+ * terminal rollup.
+ *
+ * ── 🔴 0.68.0 BREAKING(core 7.17.0 #711;异源对抗复审轮三实抓的**第五处**)──────────────────
+ * 返回 `undefined` 的含义从「`usage` 这一格缺席」收窄成 **「这一轮的账不知道」**,两种入形都答它:
+ *   ① `ev.usage` 整个缺席 —— #711 之后这**不再是一条合法形**(契约违约;`runStream` 那一层另有
+ *      响亮留痕,本读器只如实答「不知道」);
+ *   ② `usageMissing: true` **且六格全是 0** —— 那正是 core 的**占位**
+ *      (`rs.turn.turnUsage ?? {六个 0}`,`run-harness-handlers.js:289-293`)。
+ * 🔴 为什么必须改:#711 之前,「这一轮没量出账」这件事在 wire 上的形是**不发 usage** ⇒ 本函数答
+ *    `undefined`;#711 之后同一件事的形变成六个 0,而本函数是**公面导出** —— 不改的话,同一个真实
+ *    情形在引擎升级前后由同一个公开读器给出两个相反的答案(「不知道」变成「这一轮恰好花了 0」),
+ *    而调用方**一个字都没改**。收窄之后跨引擎升级的答案**逐字不变**。
+ * 🔴 **非零照交**:`usageMissing` 并不保证六格是零(core 在同一轮里可能已攒到真数字而另一次调用
+ *    报了缺账 ⇒ 判别位与真数字同帧并存)。占位恒为全零,所以**任何一格非零**都说明这一轮真的量到过
+ *    ⇒ 照交镜像(那些数字是**下界**,而「是不是下界」由帧上的 `usageMissing` / 终帧的
+ *    `_sema_usage_lower_bound` 回答,不由本函数回答)。
+ * ⚠️ 要**原样**的 wire 镜像(不做任何判断)请直接调 {@link turnUsageToModelUsage} —— 那一只是
+ *    纯映射,本函数是**带缺席语义的读器**,两者刻意分开。
  */
 export function turnEndUsage(ev) {
-    return ev.usage ? turnUsageToModelUsage(ev.usage) : undefined;
+    // 🔴 **成形判据不是 `!raw`**(异源复审轮四同族):wire 是 JSON、SSE 解析原样透传 ⇒ `usage: null` /
+    //    `usage: 7` 这类形真到得了这里。`null` 会让映射在读字段时抛;标量更坏 —— 它会被映射成一份
+    //    **看起来已测量**的全零账(`toCcModelUsage(7)` 逐格读不出、逐格折 0)。坏形与缺席同义:
+    //    **这一轮的账不知道**。
+    const rawValue = ev.usage;
+    if (typeof rawValue !== 'object' || rawValue === null || Array.isArray(rawValue))
+        return undefined;
+    const raw = rawValue;
+    const unknown = ev.usageMissing === true;
+    // 占位判据 = **六格全零**(不是「有 usageMissing 就算占位」)。逐格按值判,非有限值当 0 看待
+    // (那一格本来就读不出,它不构成「量到过」的证据)。
+    const placeholder = unknown &&
+        [raw.inputTokens, raw.totalInputTokens, raw.outputTokens, raw.cacheReadTokens, raw.cacheWriteTokens, raw.costMicroUsd]
+            .every((v) => !(typeof v === 'number' && Number.isFinite(v) && v !== 0));
+    return placeholder ? undefined : turnUsageToModelUsage(raw);
 }
 /**
  * Defensive open-set read of a `suspended` gate kind for the run driver's HITL

package/dist/adapter/downstream/terminalToSdkResult.d.ts

@@ -238,13 +238,15 @@ export interface RunCostFacts {
  * 🔴 `stats` 不是可读对象(409 拒绝信封 / park 体 / `failed` 事件帧)⇒ 返 `undefined` =
  * **这条帧没有账**,调用方据此「不说话」(不发臂、不铸键),而不是发一条全缺席的空账。
  *
- * 🔴 **第二参 `ctx`(0.67.1 / B-091,additive)**:流内观测面。给了它,对账段上的
+ * 🔴 **第二参 `observed`(0.67.1 / B-091,additive)**:**这一条流**的流内观测快照。给了它,对账段上的
  * {@link RunCostReconcile.usageLowerBound} 就是**取并后**的读数(见 {@link usageLowerBoundOf});
  * 不给(旧签名)⇒ 只读 `stats` 那一半,既有端逐位不变。
  * ⚠️ 包内的两个调用点(`costFactParts` 与 `runStream` 的 `run_cost_reconciled` 铸点)**都必须**
  * 传它 —— 少传一处就是把本件修的那条不对称原样种回去。
+ * 🔴 0.67.2 / 车 I 件 I-1:它是**按次调用的入参**,不再是 `EmitContext` 上的一格 —— 共享 ctx 被复用
+ * 给多条流时,那一格会把别的流的缺口串进这一条(见 {@link usageLowerBoundOf} 的第三段 🔴)。
  */
-export declare function readRunCostFacts(stats: TaskStats | undefined, ctx?: {
+export declare function readRunCostFacts(stats: TaskStats | undefined, observed?: {
     readonly usageMissingObserved?: boolean;
 }): RunCostFacts | undefined;
 /**
@@ -267,9 +269,24 @@ export interface SemaSubagentUsageRow {
     readonly cacheReadTokens?: number;
     /** `true` ⇒ 这只子任务**至少有一轮**没报 usage,本行三个数是**下界**。never false。 */
     readonly usageMissing?: true;
+    /**
+     * 0.67.2(车 I 件 I-2)—— `true` ⇒ **这一行是两个身份命名空间的同字面碰撞合并出来的**:
+     * 一半轮次的行键来自真身份 `sourceTaskId`、另一半来自回落的 `parentToolCallId`,而两者的**字面相等**。
+     * 本层没有任何读数能把它们拆回去(core 的合同不保证两个命名空间互斥),所以这一行的数字是**几只
+     * 子任务混在一起**的和。⇒ 这一位在场时**必然**伴随 `_sema_nested_usage_by_task_partial`,消费方
+     * 不许把本行当成某一只子代的账去渲。**never false**(缺席 = 这一行的每一轮都来自同一个命名空间)。
+     */
+    readonly keyCollision?: true;
 }
 /** {@link SemaSubagentUsageRow} 的累加中间态(runStream 持有;`readonly` 在收口那一拍才加)。 */
 export interface MutableSubagentUsageRow {
+    /**
+     * 0.67.2(车 I 件 I-2)—— **交付面的裸 id**(`sourceTaskId`,缺席时是回落的 `parentToolCallId`)。
+     * 🔴 累加表的**键**从 0.67.2 起带出身前缀(`s:` / `p:`,见 `runStream` 的 `rowKey`),因为两个身份
+     * 命名空间的字面可以相等、并在累加那一层就把两只子任务并掉(并掉之后出身位只剩一种,「出身混合」
+     * 那道闸读不出混合);交付面的键仍然必须是**裸 id**(端零改),所以原值存在行上,前缀不出本层。
+     */
+    taskId: string;
     turns: number;
     inputTokens: number;
     outputTokens: number;
@@ -287,6 +304,35 @@ export interface MutableSubagentUsageRow {
      */
     keyFromParentFallback?: true;
 }
+/**
+ * 子代用量面的**下界判别位键名**(`_sema_subagent_usage_partial`)。
+ *
+ * 🔴 它与终帧的 `_sema_usage_lower_bound` **刻意不同名**(见上段):两者答的是两个问题,
+ *    一个消费面同时拿到两者时必须分得出来。
+ * 🔴 本包**不在任何 wire 帧上铸它** —— 它是**渲染面**的位(端把一行子代用量交给自己的视图时用)。
+ *    包给名与判据,是为了三端零自拼(同 `gateIdentity` 的三条身份键字面同一条纪律)。
+ */
+export declare const SEMA_SUBAGENT_USAGE_PARTIAL_KEY = "_sema_subagent_usage_partial";
+/**
+ * 一行子代用量的数字**是不是下界**({@link SEMA_SUBAGENT_USAGE_PARTIAL_KEY} 该不该立)。
+ *
+ * 三个来源**取并**,每一条都能独立让这一行的数字不是最终数:
+ *  · `row.usageMissing` —— 这只子代**至少有一轮**引擎没报账(数字照累加,但它是下界);
+ *  · `row.keyCollision` —— 两个命名空间的 id 撞了字面,这一行是**几只子代的账并起来的**;
+ *  · `opts.tablePartial` —— 整张表对不上引擎的权威合计(`_sema_nested_usage_by_task_partial`)⇒
+ *    表里**每一行**都不可证完整。
+ *
+ * 🔴 **`false` 不是「这一行是最终数」的证据**:它只说「本端没有任何一条理由认为它是下界」。
+ *    行本身还没收口(端自己的 store 知道,包不知道)时,端要自己把那一条并进来 —— 所以这只谓词
+ *    收一个 `opts`,而不是假装它掌握全部真相。
+ * 🔴 非对象 / 缺席入参 ⇒ `false`(答不出,不是断言);坏形位(非 `true` 的值)不当真。
+ */
+export declare function subagentUsageIsPartial(row: {
+    readonly usageMissing?: unknown;
+    readonly keyCollision?: unknown;
+} | null | undefined, opts?: {
+    readonly tablePartial?: boolean;
+}): boolean;
 /** 终帧两个超集键的产物形(见 {@link nestedUsageByTaskParts})。 */
 export interface SemaNestedUsageByTask {
     readonly rows: Readonly<Record<string, SemaSubagentUsageRow>>;
@@ -317,14 +363,37 @@ export interface SemaTerminalModelUsage extends SemaModelUsage {
 /** `done` → SDKResultSuccess (contract 02 §2.10 / 08 CS-10). */
 export declare function doneToSdkResult(ev: Extract<AgentEvent, {
     type: 'done';
-}>, ctx: EmitContext): SDKMessage;
+}>, ctx: EmitContext, 
+/**
+ * 0.67.2:**这一条流**的收口快照 —— usage 缺口观测(见 {@link usageLowerBoundOf})与 per-subagent
+ * 累加表(见 {@link nestedUsageByTaskParts})。两格都是 per-stream 的事实,缺席 ⇒ 这次投影没有流内面
+ * (只读 `stats` 那一半、两个分表键都不铸),**绝不**回头去读调用方对象上可能残留的上一条流。
+ */
+observed?: {
+    readonly usageMissingObserved?: boolean;
+    readonly nestedUsageByTask?: ReadonlyMap<string, MutableSubagentUsageRow>;
+}): SDKMessage;
 /** `failed` → SDKResultError (contract 02 §2.11 / 08 CS-11). */
 export declare function failedToSdkResult(ev: Extract<AgentEvent, {
     type: 'failed';
-}>, ctx: EmitContext): SDKMessage;
-/** Dispatch a terminal AgentEvent to its SDKResult arm. */
+}>, ctx: EmitContext, 
+/** 0.67.2:同 {@link doneToSdkResult} 的第三参。 */
+observed?: {
+    readonly usageMissingObserved?: boolean;
+    readonly nestedUsageByTask?: ReadonlyMap<string, MutableSubagentUsageRow>;
+}): SDKMessage;
+/**
+ * Dispatch a terminal AgentEvent to its SDKResult arm.
+ *
+ * 🔴 第三参(0.67.2 / 车 I 件 I-1):**这一条流**的 usage 观测快照。`runStream` 在终帧那一拍**按值**
+ * 交给它与 `run_cost_reconciled` 铸臂 —— 两个投影口读的是**同一份本流快照**,而不是一个可能被别的流
+ * 写过的共享位。缺席(端直调)⇒ 与 0.67.1 的旧签名逐位同行为。
+ */
 export declare function terminalToSdkResult(ev: Extract<AgentEvent, {
     type: 'done';
 } | {
     type: 'failed';
-}>, ctx: EmitContext): SDKMessage;
+}>, ctx: EmitContext, observed?: {
+    readonly usageMissingObserved?: boolean;
+    readonly nestedUsageByTask?: ReadonlyMap<string, MutableSubagentUsageRow>;
+}): SDKMessage;