@sema-agent/client-core 0.73.2 → 0.73.4

package/dist/hitl/approvalsFeed.js

@@ -69,7 +69,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
     let takeSeq = 0;
     let lastObservedSeq = 0;
     const stats = {
-        pushEvents: 0, heartbeats: 0, polls: 0, listErrors: 0, streamFailures: 0, snapshots: 0, reconciles: 0,
+        pushEvents: 0, heartbeats: 0, polls: 0, listErrors: 0, streamFailures: 0, snapshots: 0, reconciles: 0, pushTakeRetries: 0,
     };
     /** 域词表-14 收编:「怎么调 unref」的单一实现见 unrefTimer.ts,本函数只是就地起个短名。 */
     function arm(t) {
@@ -101,6 +101,56 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         }
         return verdict;
     }
+    // ── 0.73.4 欠一次看(见 `pushTakeRetryMs` 头注)──
+    const pushTakeRetryBaseMs = opts?.pushTakeRetryMs ?? 1000;
+    const pushTakeRetryMaxMs = Math.max(pushTakeRetryBaseMs, 30_000);
+    let pushTakeRetryTimer;
+    let pushTakeRetryDelayMs = pushTakeRetryBaseMs;
+    /** 欠账锚在**发起序号**上:最近一次没看成的 push 侧取件是第几号(0 = 不欠)。 */
+    let owedSinceSeq = 0;
+    /** 已经看成的最晚发起序号(与欠账独立记):比它更早发起的失败是迟到的旧账,不记(对偶的乱序形)。 */
+    let lastLookedSeq = 0;
+    /**
+     * 销账只认**比欠账更晚发起**的取件:更早发起的那一次看的是失败之前的世界,它迟到的成功说明不了
+     * 「引擎说变了的那一下」已经有人看过(乱序是真的会发生的:慢 list / `refresh()` 与 push 重取撞车)。
+     */
+    function noteTakeLooked(seq) {
+        if (seq > lastLookedSeq)
+            lastLookedSeq = seq;
+        if (seq <= owedSinceSeq)
+            return;
+        owedSinceSeq = 0;
+        if (pushTakeRetryTimer !== undefined) {
+            clearTimeout(pushTakeRetryTimer);
+            pushTakeRetryTimer = undefined;
+        }
+        pushTakeRetryDelayMs = pushTakeRetryBaseMs;
+    }
+    function noteTakeMissed(via, seq) {
+        if (via !== 'push' || pushTakeRetryBaseMs <= 0)
+            return;
+        if (seq < lastLookedSeq)
+            return; // 更晚发起的一眼已经看成 ⇒ 这次迟到的失败不欠
+        if (seq > owedSinceSeq)
+            owedSinceSeq = seq;
+        if (stopped || ac.signal.aborted)
+            return;
+        if (pushTakeRetryTimer !== undefined)
+            return; // 幂等:已经有一只在排
+        const delay = pushTakeRetryDelayMs;
+        pushTakeRetryDelayMs = Math.min(pushTakeRetryDelayMs * 2, pushTakeRetryMaxMs);
+        pushTakeRetryTimer = arm(setTimeout(() => {
+            pushTakeRetryTimer = undefined;
+            if (stopped || ac.signal.aborted)
+                return;
+            stats.pushTakeRetries++;
+            // 欠账不随模式走:期间若降级到轮询,这一次照取(轮询腿可能被 shouldPoll 关着)。
+            void take('push').catch(e => {
+                // 重试自己逃逸(回体坏形):欠账已在 take() 内续记并再排,这里只接住 rejection。
+                hostLog('debug', `approvalsFeed: push-take retry escaped (unreadable body?) — still owed: ${String(e)}`);
+            });
+        }, delay));
+    }
     async function take(via, 
     /** [F4957-1 二审] 发起这次取件时的轮询代际(只有轮询腿传;push/refresh 不受代际管)。 */
     leg) {
@@ -118,6 +168,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             if (reading.kind === 'malformed') {
                 stats.listErrors++;
                 hostLog('debug', `approvalsFeed: list() body has an unreadable livePending section (${via} leg) — snapshot not committed`);
+                noteTakeMissed(via, seq);
                 return;
             }
             if (reading.kind === 'present') {
@@ -129,11 +180,25 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         catch (e) {
             stats.listErrors++;
             hostLog('debug', `approvalsFeed: list() failed (${via} leg): ${String(e)}`);
+            noteTakeMissed(via, seq);
             return;
         }
         if (stopped)
             return;
-        const d = digestOf(rows, live);
+        // 🔴 摘要排在销账**之前**:回体坏形(例:`pending` 不是数组)会让它抛出、整次取件逃逸(各调用点自己接盘,
+        // 轮询腿的连续逃逸计数靠的就是这条路)。先销账再抛 = 一份读不懂的回体把欠账销了,之后再没人来看。
+        // 逃逸本身也是「没看成」:在**这里**统一记欠账再原样抛出,四个调用点(起手 / 事件 / refresh / 重试)不必各记各的。
+        let d;
+        try {
+            d = digestOf(rows, live);
+        }
+        catch (e) {
+            noteTakeMissed(via, seq);
+            throw e;
+        }
+        // 看成了(回体读得懂)⇒ 销掉**更早发起**的欠账(判据在发起序号上,见 noteTakeLooked;与下面两道提交闸无关:
+        // 销账问的是「失败之后有没有人再看过」,提交闸问的是「这份结论还新不新」)。
+        noteTakeLooked(seq);
         // 🔴 [F4957-1 二审 finding②] 代际闸必须排在**提交之前**:下面四行(lastDigest / revision /
         // last / onSnapshot)一落,视图就已经被改了 —— 守卫排在 take() 之外只挡得住计数与续排,挡不住
         // 回滚。乱序是真的会发生的:旧 poll 在途 → push 重连并发布新快照 → 旧 poll 才带着**更老**的
@@ -407,6 +472,8 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                 clearTimeout(retryTimer);
             if (reconcileTimer !== undefined)
                 clearTimeout(reconcileTimer);
+            if (pushTakeRetryTimer !== undefined)
+                clearTimeout(pushTakeRetryTimer);
             opts?.signal?.removeEventListener('abort', onOuterAbort);
             ac.abort();
         },

package/dist/index.d.ts

@@ -156,6 +156,7 @@ export * from './sqlEngineCapability.js';
 export * from './writeProtectionCapability.js';
 export * from './webSearchBackendCapability.js';
 export * from './executionLaneCapability.js';
+export * from './approvalsStreamLiveCapability.js';
 export * from './mcpReconnect.js';
 export * from './leaderConflict.js';
 export * from './runTerminal.js';

package/dist/index.js

@@ -190,6 +190,8 @@ export * from './webSearchBackendCapability.js';
 // 0.72.13 CC-54:`capabilities.executionLane`(server ≥7.86.0 S-426)四态读面 —— 键缺席 = 老 server 判不了(≠ 不是本机车道);
 // 「工具是否跑在本机」判据归包(读到位用位,读不到原样用调用方旁证)。
 export * from './executionLaneCapability.js';
+// · approvalsStreamLiveCapability(0.73.3 CC-61):capabilities.approvalsStreamLive 四态读面 + feed 消费方「要不要靠对账拉」的判据单源。
+export * from './approvalsStreamLiveCapability.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 三态读。
 export * from './mcpReconnect.js';

package/dist/notifications.js

@@ -174,7 +174,10 @@ export function parseTranscriptNotificationSeeds(messages) {
                 renderedKeys.push(`${external ? 'external:' : ''}${taskId}:${status}`);
                 // L-215② 族扫(0.65.0):终局判据走单铸谓词 —— 修前这里手抄三词,core [6908] 的 `blocked`
                 //    漏在外面 ⇒ 一条已经渲过的 `blocked` 通知不进 `notifiedKeys`,重开会话后**再投一次**。
-                if (!external && isTerminalStatus(status)) {
+                // 0.73.3(CC-60 A-D11):这条 XML 有**两个生产者**、两张终局词表 —— core task-notification(带 cancelled)与本包
+                //    enqueueBgChildNotification(status 来自 run 行状态面,带 blocked)⇒ 按**并集**判终局;`event` 是唯一非终局。
+                //    两张冻结元组各自不动(动任一张 = 把另一个生产者的词丢掉)。
+                if (!external && (isTerminalStatus(status) || isTaskNotificationTerminalStatus(status))) {
                     notifiedKeys.push(taskId);
                 }
                 seeded++;

package/dist/steering.d.ts

@@ -45,7 +45,8 @@ export interface EngineTaskStatusAttachment {
     type: 'task_status';
     taskId: string;
     taskType: 'local_bash';
-    status: 'pending' | 'running' | 'completed' | 'failed' | 'killed';
+    /** 0.73.3(CC-60 A-D13):+`parked`(core 第四个 vbl 臂:停在待批检查点 —— 恰是最需要用户看见的状态)。 */
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'killed' | 'parked';
     description: string;
     deltaSummary: null;
 }

package/dist/steering.js

@@ -62,6 +62,8 @@ const PHRASE_TO_STATUS = [
     ['completed in background', 'completed'],
     ['still running in background', 'running'],
     ['stopped', 'killed'],
+    // 0.73.3(A-D13):core 第四个 vbl 臂,排在 raw-status 兜底组之前(此前恒不命中 ⇒ compaction 后停在待批检查点的行整行消失)。
+    ['parked awaiting an out-of-band approval — do NOT re-issue the gated call', 'parked'],
     // core's raw-status fallback arm for the non-vbl states (announce snapshots pending/running, but
     // parse defensively — a settle can race the boundary).
     ['pending', 'pending'],

package/dist/subagent/engineTaskHandleWire.d.ts

@@ -23,7 +23,9 @@ export declare function fetchEngineTaskOutput(handle: string, opts?: {
  * 曾经各写一份 `.includes()` 判读,同一个协议标记有两处互不知情的判读点——现在两处判读结果
  * 对同一输入恒一致,因为已经是同一个函数)。
  */
-export declare function mergeTaskOutput(prev: string, fresh: string): string;
+/** 0.73.3(CC-60 A-D3):`cursorSemantics` 机读位(server ≥7.77.0 `taskOutput` 面):"cursor" = 读了就消费 ⇒ append;"full" = 全量重读安全 ⇒ 替换。
+ *  **缺席 / 认不出 ⇒ 现行文案标记臂兜底**(老 server 不发这个键;sdk 头注逐字「别把缺席当 full」)。 */
+export declare function mergeTaskOutput(prev: string, fresh: string, cursorSemantics?: string): string;
 export type EngineTaskStopOutcome = 
 /** 200:停止动作完成(status = wire 终态照实;重复 stop 幂等)。 */
 {

package/dist/subagent/engineTaskHandleWire.js

@@ -121,7 +121,10 @@ export async function fetchEngineTaskOutput(handle, opts) {
         });
         const fresh = typeof r?.content === 'string' ? r.content : '';
         const prev = accumulated.get(handle) ?? '';
-        const merged = mergeTaskOutput(prev, fresh);
+        // A-D3:机读位优先 —— sdk 9.7.1 `SubagentOutputResult.cursorSemantics` 是**回体顶层**键(与 `output` 并列;generic taskOutput 面才铸,
+        //    窄面 subagentOutput 不带 ⇒ 缺席走文案臂)。异源对抗复审:首版读成 `output.cursorSemantics`,正常回体恒回落文案臂。
+        const cursorSemantics = r?.cursorSemantics;
+        const merged = mergeTaskOutput(prev, fresh, typeof cursorSemantics === 'string' ? cursorSemantics : undefined);
         accumulated.set(handle, merged);
         const out = r?.output ?? {};
         if (engineWireDebugEnabled()) {
@@ -148,9 +151,15 @@ export async function fetchEngineTaskOutput(handle, opts) {
  * 曾经各写一份 `.includes()` 判读,同一个协议标记有两处互不知情的判读点——现在两处判读结果
  * 对同一输入恒一致,因为已经是同一个函数)。
  */
-export function mergeTaskOutput(prev, fresh) {
+/** 0.73.3(CC-60 A-D3):`cursorSemantics` 机读位(server ≥7.77.0 `taskOutput` 面):"cursor" = 读了就消费 ⇒ append;"full" = 全量重读安全 ⇒ 替换。
+ *  **缺席 / 认不出 ⇒ 现行文案标记臂兜底**(老 server 不发这个键;sdk 头注逐字「别把缺席当 full」)。 */
+export function mergeTaskOutput(prev, fresh, cursorSemantics) {
     if (fresh.length === 0)
         return prev;
+    if (cursorSemantics === 'full')
+        return fresh;
+    if (cursorSemantics === 'cursor')
+        return prev + fresh;
     const marker = spoolMarkerOf(fresh);
     if (marker === 'full')
         return fresh;

package/dist/toolResult.d.ts

@@ -22,6 +22,8 @@ export declare const STRUCTURED_DETAIL_TYPES: ReadonlySet<string>;
 export declare function structuredDetailType(structured: unknown): string | undefined;
 export declare const PROTOCOL_MARKERS: {
     /** T11 bash 框架:退出码行头(core tools/fs/index.ts runShell)。 */
+    /** 0.73.3(CC-60 A-D5):认 core 两个发货变体 —— exit1 注记形 `exit code: 1 (<note>)` 与图片形(首行后**没有** `--- stdout ---` 行,
+     *  紧跟 `[Image data detected …]`)。第 2 组 = 括号注记(缺席 = undefined),第 3 组 = 老形的 stdout 分隔行(图片形缺席)。 */
     readonly bashHead: RegExp;
     /** T11 bash 框架:stderr 分隔行。 */
     readonly bashStderrSep: "\n--- stderr ---\n";
@@ -42,6 +44,7 @@ export declare const PROTOCOL_MARKERS: {
     /** T13 TaskOutput:stderr 分隔行。 */
     readonly taskOutputStderrLine: RegExp;
     /** T13 TaskOutput:agent 结果分隔行。 */
+    /** 0.73.3(CC-60 A-D4):认可选括号注记 `--- result (partial) ---`(core 被 stop 打断的子代任务此前正文整段切不出)。 */
     readonly taskOutputResultLine: RegExp;
     /** [1505] spool 协议:全量可重读形(`engineTaskHandleWire.ts` mergeTaskOutput 单源消费点)。 */
     readonly spoolStdoutFull: "--- stdout (full, re-readable) ---";
@@ -65,6 +68,7 @@ export declare function parseModelFacingBash(text: string): {
     stdout: string;
     stderr: string;
     exitCode: number | null;
+    note?: string;
 } | null;
 /**
  * T12 —— 剥引擎的 `delimitUntrusted` 围栏(core untrusted-text.ts:118)**仅供渲染**。

package/dist/toolResult.js

@@ -171,7 +171,9 @@ const WF_TERMINAL_STATUSES = new Set([
 // 这里只是把「谁在判读」收敛到具名常量 + 单一函数,每域一个 pattern home。
 export const PROTOCOL_MARKERS = {
     /** T11 bash 框架:退出码行头(core tools/fs/index.ts runShell)。 */
-    bashHead: /^exit code: (-?\d+)\n--- stdout ---\n/,
+    /** 0.73.3(CC-60 A-D5):认 core 两个发货变体 —— exit1 注记形 `exit code: 1 (<note>)` 与图片形(首行后**没有** `--- stdout ---` 行,
+     *  紧跟 `[Image data detected …]`)。第 2 组 = 括号注记(缺席 = undefined),第 3 组 = 老形的 stdout 分隔行(图片形缺席)。 */
+    bashHead: /^exit code: (-?\d+)(?: \(([^)\n]*)\))?\n(--- stdout ---\n)?/,
     /** T11 bash 框架:stderr 分隔行。 */
     bashStderrSep: '\n--- stderr ---\n',
     /** T11 bash 框架:空 stdout 哨兵。 */
@@ -191,7 +193,8 @@ export const PROTOCOL_MARKERS = {
     /** T13 TaskOutput:stderr 分隔行。 */
     taskOutputStderrLine: /^--- (?:new )?stderr[^\n]*---\n?/m,
     /** T13 TaskOutput:agent 结果分隔行。 */
-    taskOutputResultLine: /^--- result ---\n?/m,
+    /** 0.73.3(CC-60 A-D4):认可选括号注记 `--- result (partial) ---`(core 被 stop 打断的子代任务此前正文整段切不出)。 */
+    taskOutputResultLine: /^--- result(?: \([^)\n]*\))? ---\n?/m,
     /** [1505] spool 协议:全量可重读形(`engineTaskHandleWire.ts` mergeTaskOutput 单源消费点)。 */
     spoolStdoutFull: '--- stdout (full, re-readable) ---',
     /** [1505] spool 协议:增量新字节形。 */
@@ -238,7 +241,12 @@ export function parseModelFacingBash(text) {
     const head = PROTOCOL_MARKERS.bashHead.exec(text);
     if (!head)
         return null;
+    // 图片形(无 stdout 分隔行)只在首行后紧跟图片提示时才算命中;别的「首行后不是分隔行」的文本不是 bash 框架
+    if (head[3] === undefined && !text.slice(head[0].length).startsWith('[Image data detected'))
+        return null;
     const exitCode = Number(head[1]);
+    // 0.73.3(A-D5):首行括号注记 = 引擎对这次退出码的解释(良性非零退出);structured 缺席时它是唯一能喂给同一个良性槽的来源
+    const note = typeof head[2] === 'string' && head[2] !== '' ? head[2] : undefined;
     let rest = text.slice(head[0].length);
     let stderr = '';
     // 直写 `PROTOCOL_MARKERS.bashStderrSep`(不再中转 `const sep`):⑬ 段的角色普查按**用法形**
@@ -250,7 +258,7 @@ export function parseModelFacingBash(text) {
         rest = rest.slice(0, si);
     }
     const stdout = rest === PROTOCOL_MARKERS.bashEmptySentinel ? '' : rest;
-    return { stdout, stderr, exitCode: Number.isFinite(exitCode) ? exitCode : null };
+    return { stdout, stderr, exitCode: Number.isFinite(exitCode) ? exitCode : null, ...(note !== undefined ? { note } : {}) };
 }
 /**
  * T12 —— 剥引擎的 `delimitUntrusted` 围栏(core untrusted-text.ts:118)**仅供渲染**。
@@ -406,9 +414,13 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
             // isError:false + structured.returnCodeInterpretation('No matches found')。注记在场 ⇒
             // 非零退出不再翻 failed(CC 同款:interpretation 形走 data 路径非 error 路径,
             // pretty223:394251/815147 直证)。[1948] 裁定不动:无注记的非零退出照旧按退出码补位。
+            // 0.73.3(A-D5):structured 缺席(core boundedCard 超 64 KiB 整只丢)时,首行括号注记是同一件事 ⇒ 喂同一个良性槽;
+            //    只放宽正则不接这一位,会把「正文丢失」换成「红色错误卡」。structured 在场仍以它为准。
             const benignInterp = typeof s?.returnCodeInterpretation === 'string' && s.returnCodeInterpretation.length > 0
                 ? s.returnCodeInterpretation
-                : undefined;
+                : 'note' in slots && typeof slots.note === 'string' && slots.note.length > 0
+                    ? slots.note
+                    : undefined;
             const failed = isError || (slots.exitCode != null && slots.exitCode !== 0 && benignInterp === undefined);
             if (failed) {
                 // 失败卡走 UserToolErrorMessage,它读 BLOCK content 且非字符串会被吞成
@@ -884,6 +896,10 @@ modelText) {
                 };
             }
             const wfName = typeof inner?.name === 'string' && inner.name.length > 0 ? inner.name : undefined;
+            // 0.73.4(CC-63):**run 级**错误码。引擎在这张结构卡的**顶层**铸 `errorCode`(与 `completionId` 同层;有值才带,
+            // 缺席 = 这条 run 没有码),今天只有 workflow 形带。它不是 `agent_runs[].errorCode`(per-agent,住在模型面 JSON 里),
+            // 也不在内层 `details` 上。开集原词透传;缺席 / 空串 / 非字符串 ⇒ 键不铸,绝不编码。CC 的 task 形没有这一格 ⇒ 超集键。
+            const runErrorCode = typeof s.errorCode === 'string' && s.errorCode.length > 0 ? s.errorCode : undefined;
             let output = bodyText ?? '';
             if (taskType === 'workflow') {
                 // 终态轮询卡经过投影 = 模型 in-band 已收到结局 ⇒ 预 seed runId 去重(补发通道对同 runId 丢弃)。
@@ -904,6 +920,7 @@ modelText) {
                         description: wfName ?? taskId,
                         output,
                         ...(error !== undefined ? { error } : {}),
+                        ...(runErrorCode !== undefined ? { _sema_error_code: runErrorCode } : {}),
                     },
                 },
             };