@sema-agent/client-core 0.73.3 → 0.73.5

package/dist/fleet/workflowSizeWarning.js

@@ -0,0 +1,155 @@
+/**
+ * src/fleet/workflowSizeWarning.ts —— workflow **规模告警**的判定(0.73.5)。
+ *
+ * 三端 footer / 面板都要回答同一个问题:「这条 workflow 是不是大到该提醒用户了」。判定与 CC 同形
+ * (三个缺省帽、每 agent 用量估算、guideline 表、两个 env 覆盖、三档文案与宽度阶梯),属于客户端公共逻辑,
+ * 由本包单源;端只负责读环境、读设置、量宽度与渲染。
+ *
+ * 🔴 **入参按 fleet 视图的三态键读**(`FleetWorkflowView`:`totalCount` / `startedCount` / `doneCount` /
+ *    `failedCount` / `tokens` 全是可选位,缺席 = wire 没报 = 不知道)。出参三态:
+ *      · `warn`    —— 有**正向证据**证明至少一条轴超帽(别的键缺席不挡它;下界分母算出的上界**不算**证据);
+ *      · `ok`      —— 两条轴都判得出,且都在帽内(或 ultracode 压掉了整条告警);
+ *      · `unknown` —— 没有超帽的正向证据,且至少一条轴判不出。**未知的规模不能被当作规模正常**:
+ *                     `unknown` 绝不折成 `ok`,`missing` 点名缺了哪几键。
+ *
+ * 🔴 **分母口径**(每 agent 用量 `u = tokens / started`):
+ *      · `startedCount` 在场且不小于 `doneCount + failedCount` ⇒ 用引擎真值(含真 0:「一个都还没起」是一条真信息
+ *        ⇒ 用先验);比已完成数还小(帧间竞态)⇒ 这份读数是陈旧的,按下面的下界处置;
+ *      · 缺席 ⇒ 只有 `doneCount` / `failedCount` **两键都在场**才回退成下界,结果标 `startedIsLowerBound`。
+ *        下界偏小 ⇒ `u` 偏大 ⇒ 算出来的是投影的**上界**(`projectedTokensUpperBound`,不是 `projectedTokens`):
+ *        上界在帽内 ⇒ 真的在帽内 ⇒ 可以判 `ok`;上界超帽**不是**超帽的证据(同一份读数补上真 `startedCount`
+ *        可能远在帽内)⇒ 投影轴判不出,`unknown`。想保守一点的端可以自己拿上界去提示,判词不替它撒谎;
+ *      · 下界为 0 ⇒ 每 agent 用量判不出:「0 个完成」不是「一个没起」的证据,先验只在引擎**亲口**报
+ *        `startedCount = 0` 时可用;
+ *      · 只有一键在场 ⇒ 不回退(缺席的那键不读作 0)。
+ */
+/** 缺省 agent 数帽。 */
+export const WORKFLOW_SIZE_WARNING_AGENT_CAP = 25;
+/** 缺省 token 帽(已花 ∨ 投影)。 */
+export const WORKFLOW_SIZE_WARNING_TOKEN_CAP = 1_500_000;
+/** 还没有任何 agent 起跑时的每 agent 用量先验。 */
+export const WORKFLOW_SIZE_WARNING_TOKENS_PER_AGENT = 70_000;
+/** 显式 `workflowSizeGuideline` → agent 数帽。`unrestricted` 与缺省(未配置)**不贡献帽**,故不在表里。 */
+export const WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS = Object.freeze({
+    small: 5,
+    medium: 15,
+    large: 50,
+});
+/** 两个 env 覆盖各自的名字,按读取优先级排(品牌名在前,兼容名在后)。本包不读 `process.env`,名字单源在这里。 */
+export const WORKFLOW_SIZE_WARNING_ENV_NAMES = Object.freeze({
+    agents: Object.freeze(['SEMA_CODE_WORKFLOW_SIZE_WARNING_AGENTS', 'CLAUDE_CODE_WORKFLOW_SIZE_WARNING_AGENTS']),
+    tokens: Object.freeze(['SEMA_CODE_WORKFLOW_SIZE_WARNING_TOKENS', 'CLAUDE_CODE_WORKFLOW_SIZE_WARNING_TOKENS']),
+});
+/** 三档文案(宽 → 窄)。 */
+export const WORKFLOW_SIZE_WARNING_TEXT_LONG = '⚠ Large workflow · /workflows to stop';
+export const WORKFLOW_SIZE_WARNING_TEXT_SHORT = '⚠ Large workflow';
+export const WORKFLOW_SIZE_WARNING_TEXT_MIN = '⚠';
+/** 有限非负数,否则缺席(坏形按缺席,不猜)。 */
+function count(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
+}
+/** 正有限数,否则缺席。 */
+function positive(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined;
+}
+function guidelineCap(size) {
+    return size !== undefined && Object.hasOwn(WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS, size)
+        ? WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS[size]
+        : undefined;
+}
+/** 规模判定。纯函数:每个环境量都由调用方注入。 */
+export function evaluateWorkflowSize(input) {
+    const agentCap = positive(input.envAgentCap) ?? guidelineCap(input.guidelineSize) ?? WORKFLOW_SIZE_WARNING_AGENT_CAP;
+    const tokenCap = positive(input.envTokenCap) ?? WORKFLOW_SIZE_WARNING_TOKEN_CAP;
+    const scheduled = count(input.totalCount);
+    const tokens = count(input.tokens);
+    const base = {
+        agentCap,
+        tokenCap,
+        ...(scheduled !== undefined ? { scheduledAgents: scheduled } : {}),
+        ...(tokens !== undefined ? { totalTokens: tokens } : {}),
+    };
+    if (input.ultracodeActive === true)
+        return { kind: 'ok', suppressed: true, ...base };
+    // 分母:真值 / 两键下界 / 判不出。
+    const startedWire = count(input.startedCount);
+    const done = count(input.doneCount);
+    const failed = count(input.failedCount);
+    const bound = done !== undefined && failed !== undefined ? done + failed : undefined;
+    let started;
+    let lowerBound = false;
+    if (startedWire !== undefined && (bound === undefined || startedWire >= bound)) {
+        started = startedWire;
+    }
+    else if (bound !== undefined) {
+        // `startedCount` 缺席,或它比已完成数还小(帧间竞态:已完成的 agent 必然起过 ⇒ 这份 started 是陈旧的)。
+        // 顶上来的 `done + failed` 只是**下界**,不是真值 —— 与缺席同一处置。
+        started = bound;
+        lowerBound = true;
+    }
+    // 投影:分母是真值 ⇒ 投影;分母是下界(> 0)⇒ 只有上界;其余判不出。
+    let projected;
+    let upperBound;
+    if (scheduled !== undefined && tokens !== undefined && started !== undefined) {
+        if (!lowerBound) {
+            projected = Math.max(tokens, Math.round((started > 0 ? tokens / started : WORKFLOW_SIZE_WARNING_TOKENS_PER_AGENT) * scheduled));
+        }
+        else if (started > 0) {
+            upperBound = Math.max(tokens, Math.round((tokens / started) * scheduled));
+        }
+    }
+    const facts = {
+        ...base,
+        ...(projected !== undefined ? { projectedTokens: projected } : {}),
+        ...(upperBound !== undefined ? { projectedTokensUpperBound: upperBound } : {}),
+        ...(lowerBound && scheduled !== undefined && tokens !== undefined ? { startedIsLowerBound: true } : {}),
+    };
+    /** 投影轴在帽内的证据:真投影在帽内,或上界在帽内。 */
+    const projectionWithinCap = (projected !== undefined && projected <= tokenCap) || (upperBound !== undefined && upperBound <= tokenCap);
+    const overAgents = scheduled !== undefined && scheduled > agentCap;
+    const overTokens = (tokens !== undefined && tokens > tokenCap) || (projected !== undefined && projected > tokenCap);
+    if (overAgents || overTokens) {
+        return { kind: 'warn', axis: overAgents && overTokens ? 'both' : overAgents ? 'agents' : 'tokens', ...facts };
+    }
+    const missing = [];
+    if (scheduled === undefined)
+        missing.push('totalCount');
+    if (tokens === undefined)
+        missing.push('tokens');
+    if (scheduled !== undefined && tokens !== undefined && !projectionWithinCap)
+        missing.push('startedCount');
+    if (missing.length > 0)
+        return { kind: 'unknown', missing, ...facts };
+    return { kind: 'ok', ...facts };
+}
+/**
+ * 两个 env 覆盖的读口。`env` 由调用方交(本包不碰 `process.env`)。每组按 {@link WORKFLOW_SIZE_WARNING_ENV_NAMES}
+ * 的顺序取**第一个在场的名字**;那个名字的值不是正有限数 ⇒ 该键不在场,**不回落**到第二个名字
+ * (显式写错不该被悄悄换源)。
+ */
+export function readWorkflowSizeWarningEnvCaps(env) {
+    const pick = (names) => {
+        if (env === undefined || env === null)
+            return undefined;
+        for (const n of names) {
+            const raw = env[n];
+            if (typeof raw !== 'string')
+                continue; // 空串也是「在场」:在场的坏值就地止步,不回落
+            return positive(Number(raw));
+        }
+        return undefined;
+    };
+    const a = pick(WORKFLOW_SIZE_WARNING_ENV_NAMES.agents);
+    const t = pick(WORKFLOW_SIZE_WARNING_ENV_NAMES.tokens);
+    return { ...(a !== undefined ? { envAgentCap: a } : {}), ...(t !== undefined ? { envTokenCap: t } : {}) };
+}
+/** 宽度阶梯:挑放得下的最长一档;连字形都放不下 ⇒ `undefined`(整段不渲)。`width` 由调用方注入(与渲染器同一把尺)。 */
+export function workflowSizeWarningTextForWidth(available, width) {
+    if (available >= width(WORKFLOW_SIZE_WARNING_TEXT_LONG))
+        return WORKFLOW_SIZE_WARNING_TEXT_LONG;
+    if (available >= width(WORKFLOW_SIZE_WARNING_TEXT_SHORT))
+        return WORKFLOW_SIZE_WARNING_TEXT_SHORT;
+    if (available >= width(WORKFLOW_SIZE_WARNING_TEXT_MIN))
+        return WORKFLOW_SIZE_WARNING_TEXT_MIN;
+    return undefined;
+}

package/dist/hitl/approvalsFeed.d.ts

@@ -91,6 +91,8 @@ export interface ApprovalsFeedStats {
     snapshots: number;
     /** 0.72.14:对账节拍真取件的次数(与 `polls` 分开记 —— 它不属于回落轮询腿)。 */
     reconciles: number;
+    /** 0.73.4:「欠一次看」的重试取件次数(见 `ApprovalsFeedOptions.pushTakeRetryMs`)。 */
+    pushTakeRetries: number;
 }
 /**
  * 0.72.14 **对账节拍**:悬挂的流内 ask 出现 / 结算时,较老的引擎不在 `approvals.stream` 上发任何事件 ⇒ push 腿连着也
@@ -132,6 +134,16 @@ export interface ApprovalsFeedOptions {
      *   · **`refresh()`** 不受管 —— 那是端自己按下的显式动作。
      */
     shouldPoll?: () => boolean;
+    /**
+     * 0.73.4:**欠一次看**的重试基础间隔(ms;缺省 1000;`<= 0` = 关,与 0.73.3 之前同)。
+     *
+     * push 腿收到事件 = 引擎说「变了」;那一次 `list()` 若失败(抛出,或回体读不懂),这个「变了」就没人去看:
+     * 其后的 heartbeat 不触发取件,没有别的事件的话,那张待批的卡一直不出现。⇒ 任何一次 push 侧取件
+     * (起手那次、事件触发的、`refresh()`)没看成,就记一笔欠账并按 base、2×base、4×base … 退避重试,
+     * 间隔封顶 30 s 与 base 的较大者,**不按次数放弃**(有人可能正在等这张卡);**比欠账更晚发起**的任何一次
+     * 取件看成(哪条腿都算)即销账、撤定时器、间隔回到 base;更早发起、迟到回来的成功不销账。只在 push 模式记账 —— 轮询模式下轮询腿自己会再来。
+     */
+    pushTakeRetryMs?: number;
     /** 0.72.14:对账节拍(见 {@link ApprovalsFeedReconcileOptions})。缺省不起。 */
     reconcile?: ApprovalsFeedReconcileOptions;
     signal?: AbortSignal;

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/hitl/planReviewWire.js

@@ -558,6 +558,16 @@ releaseLatch) {
                         'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
                             'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.';
                 }
+                else if (status === 404 && refusedCode === 'not_found.plan_review') {
+                    // 0.73.5:这道门已经不在了(早先的决断已生效,或已过期)。现场形:用户在一张**陈旧的重开卡**上作答 ⇒ 404;
+                    // 通用句「decision failed: HTTP 404 …」被模型读成「计划被拒 / 计划失败」,于是对用户说计划被拒并重新规划 ——
+                    // 而那份计划其实已批准并跑完。⇒ 明说这不是拒绝也不是失败,只是这次作答没有对象;效果态仍是 not_applied。
+                    hostLog('debug', `planReviewWire: ${decision} → 404 not_found.plan_review (no pending plan review any more — an earlier decision likely settled it)`);
+                    effect = 'not_applied';
+                    outcome =
+                        `This ${decision} was not applied: the engine no longer has a pending plan review for this task — an earlier decision most likely already went through (or the review expired). ` +
+                            'This is NOT a rejection of the plan and NOT a failure of the task; the answer just given simply had nothing left to act on.';
+                }
                 else if (typeof status === 'number') {
                     const msg = e instanceof Error ? e.message : String(e);
                     hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);

package/dist/index.d.ts

@@ -227,6 +227,7 @@ export * from './headlessPermissionModeWire.js';
 export * from './headlessReconnectWire.js';
 export * from './fleet/fleetProjection.js';
 export * from './fleet/fleetLedger.js';
+export * from './fleet/workflowSizeWarning.js';
 export * from './subagent/engineDelegatedPrompt.js';
 export * from './subagent/engineRowStopGate.js';
 export * from './subagent/engineSubagentOutput.js';

package/dist/index.js

@@ -364,6 +364,8 @@ export * from './headlessReconnectWire.js';
 //   · `engineWireTarget.ts` 的 `installed` —— 非 Node 宿主的显式 wire 目标。
 export * from './fleet/fleetProjection.js';
 export * from './fleet/fleetLedger.js';
+// 0.73.5(CC-58):workflow 规模告警判定(三态;缺席 = 不知道,未知的规模不当作规模正常)。
+export * from './fleet/workflowSizeWarning.js';
 export * from './subagent/engineDelegatedPrompt.js';
 export * from './subagent/engineRowStopGate.js';
 export * from './subagent/engineSubagentOutput.js';

package/dist/toolResult.js

@@ -896,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 丢弃)。
@@ -916,6 +920,7 @@ modelText) {
                         description: wfName ?? taskId,
                         output,
                         ...(error !== undefined ? { error } : {}),
+                        ...(runErrorCode !== undefined ? { _sema_error_code: runErrorCode } : {}),
                     },
                 },
             };