@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/leaderConflict.js

@@ -1,41 +1,11 @@
-/**
- * leaderConflict — leader run 终局 `needs_human` + `result.conflict` 的**三端共用读面**(0.72.10;server ≥7.83.0 C-R63 ④;
- * 契约 §15;sdk `LeaderRecord.result` 声明为 `unknown`,本读器是它在客户端的唯一形)。
- *
- * ── 这一口答的是哪件事 ────────────────────────────────────────────────────────────────────
- * 7.83.0 起 worker 分支合不上时,leader run **不再**起任何模型去解冲突,而是把冲突**列给用户**:`status:"needs_human"` +
- * `result.conflict { baseSha, files[], filesTruncated?, workers[], rejHead? }` + `result.salvaged[]`(全部 worker 各一份补丁,尽力而为)。
- * 壳只有「列出来 + 把补丁落盘」两件事;缺席语义 / 坏形判别 / 措辞三端各写一遍必各错一遍 ⇒ 归包。
- *
- * ── 🔴 五条契约读法(§15 逐字)──────────────────────────────────────────────────────────────
- *  ① **缺席不可分**:`result` 无 `conflict` 键 = 这一趟没有冲突,**或**对面是老 server(<7.83.0,那时冲突走别的终局)。
- *     两者 wire 上不可区分 ⇒ 读数 `none`,措辞把两种可能都摆出来,不替 server 断言其中一种。
- *  ② **在场但读不懂 ≠ 缺席**:`conflict` 在场但必填座缺 / 形坏 ⇒ `unreadable`。它和 `none` 是两个词 —— server 明明报了冲突,
- *     壳若因读不懂而渲成「没冲突」,用户会把一棵带冲突标记的树当干净树用。
- *  ③ **`filesTruncated` 只在清单被截断时在场且恒 `true`;缺席 = 这就是全部**。在场却不是 `true` ⇒ unreadable,不编「全部」也不编「截断」。
- *  ④ **`workers[].applied` 是布尔事实**:`false` = 这只 worker 的补丁没进树(冲突者本人,或排在它后面没轮到的)。`salvaged[].patch`
- *     是**工件**(给落盘口),原样透传、不消毒、不截断;`rejHead` 是**屏上诊断片段**(server 已脱敏 ≤2 KiB),呈前按 UNTRUSTED-for-display
- *     再过一次(转义控制符 + 封长)。两者在 server 侧走同一只脱敏口,客户端只按用途分「落盘 / 上屏」,不再加第二套判据。
- *  ⑤ **`needs_human` 是「等人」不是「失败」**:契约明令不许据它自动重试一条 leader run。措辞单源 {@link leaderConflictDetail},
- *     句子里不出现重试;壳零自拼句子。
- *
- * ── 防御读纪律(与 `mcpReconnect` / `sessionMemoryStatus` 同律)─────────────────────────────
- *  · 永不抛:载体非对象 / 敌意 getter ⇒ `undefined`(记录本身不成形);`status` 缺席或非串 ⇒ `undefined`;
- *  · `status` 按**开集**透传(契约闭集四词,但客户端不替 server 断言闭集 —— 新词照带,壳 switch 必带 default);
- *  · 多余成员不过境,数组是新拷贝(壳改视图不回写 wire 体)。
- */
 import { capForDisplay } from './fleetTaskDesc.js';
-/** 契约 §15 `GET /v1/leader/:id` 的 `status` 四词(仅作词表;读器按开集透传)。 */
 export const LEADER_RUN_STATUSES = Object.freeze(['running', 'completed', 'failed', 'needs_human']);
-/** `rejHead` 上屏封长(显示字符;server 侧已 ≤2 KiB,这里是呈前的第二道,与工件字节无关)。 */
 export const LEADER_REJ_HEAD_DISPLAY_MAX = 2048;
-/** 冲突句里最多点名几条冲突路径(其余以「and N more」收口;路径是 UNTRUSTED-for-display,逐条消毒)。 */
 const DETAIL_FILES_MAX = 5;
 const DETAIL_PATH_MAX = 120;
 const DETAIL_BRANCH_MAX = 80;
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const nonEmptyString = (v) => typeof v === 'string' && v.length > 0;
-/** JSON 永远带不来 `undefined`;本地拼出来的 `{ key: undefined }` 按缺席读,与 wire 上整键缺席同义。 */
 const present = (o, key) => Object.hasOwn(o, key) && o[key] !== undefined;
 function readWorkers(v) {
     if (!Array.isArray(v))
@@ -71,10 +41,6 @@ function readConflict(v) {
     }
     return out;
 }
-/**
- * 尽力而为的表:坏行逐行丢弃(一行坏不该让用户拿不到别的 worker 的补丁);`patch` 原样。
- * 返回 `{ rows, incomplete }`:`incomplete` = 在场但读不全(非数组 / 非空全坏 / 混合);缺席、`[]`、全好 ⇒ false。
- */
 function readSalvaged(result) {
     if (!isRecord(result) || !present(result, 'salvaged'))
         return { rows: [], incomplete: false };
@@ -91,10 +57,6 @@ function readSalvaged(result) {
     }
     return { rows, incomplete: dropped > 0 };
 }
-/**
- * 把 `GET /v1/leader/:id` 的记录(sdk `LeaderRecord`,`result` 为 `unknown`)投成 {@link LeaderConflictView}。
- * 永不抛;记录本身不成形(非对象 / `status` 缺席或非串 / 敌意 getter)⇒ `undefined`。
- */
 export function projectLeaderConflict(record) {
     try {
         if (!isRecord(record) || !nonEmptyString(record.status))
@@ -115,7 +77,6 @@ export function projectLeaderConflict(record) {
     }
 }
 const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
-/** 打捞补丁句(三形共用):有数带数;读不全 ⇒ 说材料存在但读不出、去看原始结果,绝不落到「没有补丁」;零且读全 ⇒ 如实说没有。 */
 function salvageSentence(view) {
     const n = view.salvaged.length;
     if (view.salvagedIncomplete) {
@@ -125,15 +86,6 @@ function salvageSentence(view) {
     }
     return n === 0 ? 'No salvaged patches were returned.' : `${plural(n, 'salvaged patch', 'salvaged patches')} available to save.`;
 }
-/**
- * 一句措辞的**唯一铸点**(三端共用;壳零自拼)。
- *  · `conflict`:等人 + 基点短 sha + 冲突文件数(截断则明说)+ 哪几支进了树 / 没进 + 打捞补丁句;
- *  · `none`:只说「没有报告冲突详情」,🔴 **明说这不证明已经合并**(异源对抗复审采纳:`running` 与未进合并的 `failed` 也走这句,
- *    缺席只证明没有冲突报告,不证明执行过合并 —— 说成「已无冲突合并」会让用户以为工作已合入而不去恢复);
- *  · `unreadable`:server 报了冲突但读不出,让用户去 server 侧看。
- * 三句都带同一条打捞补丁句(有数带数 / 零则如实说没有 / 读不全则说材料存在但读不出,绝不说「没有」)。
- * 🔴 句子里不出现重试(契约:`needs_human` 在等人)。`rejHead` / `patch` 一个字节都不进句子。
- */
 export function leaderConflictDetail(view) {
     const salvage = salvageSentence(view);
     if (view.kind === 'none') {

package/dist/limitsWire.d.ts

@@ -1,114 +1,17 @@
-/**
- * src/limitsWire.ts — headless `-p` run-limits wire: expose the engine's TASK-LEVEL budget face on
- * the headless `-p` path via `TaskRequest.limits`.
- *
- * ── core 5.8.0 词表迁移([2489],2026-08-04)────────────────────────────────────────────
- * `limits` 是**唯一预算面,默认全空 = 无限制**。本模块拼的三个键都骑 5.8.0 的新词表:
- *   · `maxWalltimeMs`(**毫秒**;5.7 的 `limits.timeoutSec` 已删,单位一并变)
- *   · `maxTurns`
- *   · `maxOutputTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮;
- *     wire 键名自 5.7 起一直是 maxOutputTokens,core 内部才叫 maxTokens——[2569] 案订正)。
- *     🔴 到限形订正([2592]/[2593] 案):这是**单请求输出上限**不是累计预算——撞线=生成中被
- *     截断(工具调用参数途中被砍以 provider 截断披露上浮,core 3dfdb8f 起披露点名 cap),
- *     **不出** `limits.max_tokens_exceeded`(那是 core 内部累计预算键 `maxTokens` 的码,本 wire
- *     从不发那个键 ⇒ 消费端别拿那个码当 --max-tokens 的到限判据)。
- * 到限语义也换了:**没有配速机器了**。5.8.0 删掉了 deadlineNudge / callCapByDeadline /
- * gracefulFinalize 那一套(以及引擎侧 1000 轮安全网、fork 200、session-bg 30min 暗注等全部隐式
- * 默认),走到 `maxWalltimeMs` 不再是「引擎自己减速然后优雅收尾」,而是**响亮终局**:
- * `status:'failed'` + `errorCode:'limits.max_walltime_exceeded'`(`status:'timeout'` 这个词整体退役)。
- * 四个新码 `limits.max_{tokens,cost,turns,walltime}_exceeded` 的下游投影见
- * `adapter/downstream/terminalToSdkResult.ts`。
- *
- * ✅ **窗口期已关闭(退役批,2026-08-04)**:交付时点壳的引擎是 server 5.14.0(捆 core 5.7),它
- * **不认识** `maxWalltimeMs`/`maxTokens`(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,未知键
- * 静默丢弃),所以那段时间三个键里只有 `maxTurns` 真的生效。**server 6.0.0 已捆 core 5.8.0 发车**
- * ⇒ 新键集在班车上生效,读面的双代兜底(`adapter/downstream/terminalToSdkResult.ts`)本批一并退役。
- * 写面从头到尾是**单一新形**,不做两代并发(同时发 `timeoutSec` + `maxWalltimeMs` 会在 5.8 引擎上撞
- * `config.limit_unknown_key` 当场失败,那是拿窗口期的一次静默无视换班车到货后的确定性失败)。
- *
- * THREE FLAGS, THREE ALIGNMENT BUCKETS:
- *  · `--deadline <sec>`   → limits.maxWalltimeMs(用户面仍是**秒**,拼 wire 时 ×1000)。Upstream
- *    CC 2.1.207 has NO deadline flag → SUPERSET, help copy says so.
- *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
- *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
- *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
- *    carries the cap to where the turns actually run.
- *  · `--max-tokens <n>`   → limits.maxOutputTokens(5.8.0 主限;wire 键名见接口注——绝不直发
- *    core 内部键 maxTokens,[2569] 案)。Upstream CC 2.1.207 has no run-level
- *    token budget flag → SUPERSET.
- *
- * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
- *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
- *     value (integer domain below; a mis-typed budget bound must not quietly run unbounded).
- *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
- *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` / `SEMA_HEADLESS_MAX_TOKENS`
- *     → 同 a) FAIL-LOUD on an invalid value(#132 / test [2508] 2026-08-04 推翻旧 batch-E
- *     「静默降级」形;见 headlessLimitsFromEnv 的 JSDoc——非法值 {ok:false} 上抛,caller exit 1,
- *     常驻门 run-limits-env-failloud-test.mjs 守此形)。
- *  c) neither                                          → NO stamp = today's behaviour, verbatim.
- *
- * DOMAINS (integer, inclusive): deadline 30..86400 **秒**(→ 30_000..86_400_000 ms 上 wire)·
- * maxTurns / maxTokens = **正整数**(上界 = JS 安全整数)。maxTurns 此前钉 1..1000,那个上界抄的是
- * 引擎侧 1000 轮安全网;5.8.0 把该安全网整体退役了,壳再替它守一个不存在的墙就是凭空拒绝合法配置。
- *
- * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
- * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
- * construction; but a user-supplied SEMA_ENGINE_URL may point at an older engine. When the user
- * EXPLICITLY passed a flag (env-lane defaults stay quiet) and SEMA_ENGINE_URL is in play, the caller
- * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
- * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
- * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
- *
- * 📐 **两道地板,守的不是同一件事**(退役批补记,2026-08-04):
- *   · 第一地板 `LIMITS_WIRE_MIN_ENGINE = 1.196.0` = 「`limits` 这个**字段**存不存在」(server 1.196.0
- *     起接受 body.limits);低于它,整个预算面被丢。
- *   · 第二地板 **server ≥ 6.0.0** = 「**新键集**认不认」。6.0.0 是第一个捆 core 5.8.0 的 server 版本,
- *     也就是第一个认识 `maxWalltimeMs` 的版本(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,
- *     未知键静默丢弃)。**[2569] 案订正**:`maxOutputTokens` 自 5.7 就在 wire 词表,本模块此前
- *     直发 core 内部键 `maxTokens` 才是被静默无视的那个(server 6.3.0 起 400);对 1.196.0 ≤
- *     version < 6.0.0 的引擎,`maxTurns`/`maxOutputTokens` 生效而 `maxWalltimeMs` 被静默无视。
- *     之所以过去写不出这条:/health 自报的是 server 版本,而键名代际取决于它捆的 core 版本,当时
- *     两者没有可从 wire 读出的映射;6.0.0 这班车把映射钉死了(6.0.0 ⇒ core ≥5.8),这条地板才成立。
- *   · 本文件的运行期探针目前只对第一地板发声(warn, don't block);第二地板先落成契约事实写在这里,
- *     要不要给它也配一条 stderr 提示是**行为面**决定,按宪法三问单独走,不在退役批里顺手加。
- */
 import { type EnvLike } from './hostEnv.js';
-/** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
 export declare const HEADLESS_DEADLINE_ENV = "SEMA_HEADLESS_DEADLINE_SEC";
 export declare const HEADLESS_MAX_TURNS_ENV = "SEMA_HEADLESS_MAX_TURNS";
 export declare const HEADLESS_MAX_TOKENS_ENV = "SEMA_HEADLESS_MAX_TOKENS";
-/** `--deadline` 的**用户面**整数域(秒;30s..24h)。上 wire 前 ×1000 换成 `maxWalltimeMs`。 */
 export declare const DEADLINE_SEC_MIN = 30;
 export declare const DEADLINE_SEC_MAX = 86400;
-/**
- * `maxTurns` / `maxTokens` 的整数域 = **正整数**(上界只到 JS 安全整数,再大就不是「一个精确的
- * 轮数/token 数」而是浮点近似了 —— 那种值静默夹取比拒绝更坏)。
- *
- * `MAX_TURNS_MAX` 此前是 `1_000`,抄的是引擎侧的 1000 轮安全网;core 5.8.0 把那张网**整体退役**
- * (「零配置任务现在没有任何任务级兜底」,[2489]),壳再守它 = 替一堵不存在的墙拒绝合法配置。
- * 常量名保留(它仍然是这个域的上界,只是值换成了真上界),消费者的 help 文案请按「正整数」写。
- */
 export declare const MAX_TURNS_MIN = 1;
 export declare const MAX_TURNS_MAX: number;
 export declare const MAX_TOKENS_MIN = 1;
 export declare const MAX_TOKENS_MAX: number;
-/** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
 export declare const LIMITS_WIRE_MIN_ENGINE: readonly [number, number, number];
-/**
- * `TaskRequest.limits` 的壳侧子集(core 5.8.0 词表)。引擎那份还有
- * `maxCostUsd`/`maxOutputTokens`/`approachNotice`/`degrade`/… —— 本模块只拼 CLI flag 暴露的三个键,
- * 其余键由别的配置面负责,别在这里悄悄补默认值(默认全空 = 无限制,是 5.8.0 的显式设计)。
- */
 export interface HeadlessLimits {
-    /** 墙钟预算,**毫秒**(用户面 `--deadline` 是秒)。到限 ⇒ failed + `limits.max_walltime_exceeded`。 */
     maxWalltimeMs?: number;
-    /** 轮数预算。到限 ⇒ failed + `limits.max_turns_exceeded`。 */
     maxTurns?: number;
-    /** token 预算(5.8.0 主限)。到限 ⇒ failed + `limits.max_tokens_exceeded`(result 带已产出正文)。
-     *  🔴 wire 键=**maxOutputTokens**(sdk 6.2.0 types.d.ts:472 实测词表;[2569] 案定谳):
-     *  `maxTokens` 是 core TaskSpec 内部键,server 从未从 wire 采纳它(此前 200 静默空转,
-     *  6.3.0 起对 limits.maxTokens 直接 400)。用户面 `--max-tokens`/`SEMA_HEADLESS_MAX_TOKENS`
-     *  名称不变——变的只是上 wire 的键名。[same-name-different-meaning-crosses-layers] 同族。 */
     maxOutputTokens?: number;
 }
 export type LimitsParseResult = {
@@ -119,22 +22,7 @@ export type LimitsParseResult = {
     ok: false;
     error: string;
 };
-/**
- * Parse `--deadline` + `--max-turns` + `--max-tokens` out of an argv slice. No flags ⇒ `{ok:true}`
- * with no limits. Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer /
- * out-of-domain ⇒ fail-LOUD parse error (never a silent default — same stance as
- * `--scenario`/`--sandbox`). `flaggedFlags` names the flags that EXPLICITLY contributed (the
- * version-gate probe trigger).
- */
 export declare function parseLimitsArgv(argv: string[]): LimitsParseResult;
-/**
- * The settings-lane defaults. FAIL-LOUD on a bad value (#132 / test [2508],2026-08-04,推翻旧
- * batch-E「静默降级」形):设置了 SEMA_HEADLESS_* 却是非法值时,旧行为=不开 SEMA_DEBUG 完全无声、
- * 按「无限期限」跑——用户以为设了预算,实际什么都没设,这正是 [honest-absence] 禁的那类静默谎报。
- * 现与 flag 路径同拍响亮拒(同文案形,caller exit 1):配置错了要在第一次跑就知道,而不是在一个
- * 本该 300s 停的任务跑了一夜之后。返回判别联合;唯一消费者是下面的 limitsForPrint(仓际零外部
- * 消费,干净切不设兼容)。
- */
 export type HeadlessEnvLimitsResult = {
     ok: true;
     limits: HeadlessLimits | undefined;
@@ -143,21 +31,8 @@ export type HeadlessEnvLimitsResult = {
     error: string;
 };
 export declare function headlessLimitsFromEnv(env?: EnvLike): HeadlessEnvLimitsResult;
-/**
- * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
- * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
- * yields {maxWalltimeMs:300000, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
- */
 export declare function limitsForPrint(argv: string[], env?: EnvLike): LimitsParseResult;
-/** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
 export declare function versionSupportsLimits(v: string | undefined): boolean;
-/**
- * Version-gate probe (triage risk ③): GET `${baseUrl}/health`, read `version`, and return ONE honest
- * stderr line when the engine is confirmed <1.196.0 — the caller prints it and SENDS ANYWAY (the old
- * server drops the field server-side; warn, don't block). Returns undefined when the engine is new
- * enough, unreachable, or self-describes no parsable version (can't confirm staleness — fail-soft
- * silent; the release-pinned self-spawn lane never even reaches this probe).
- */
 export declare function engineLimitsSupportWarning(baseUrl: string, flaggedFlags: string[], opts?: {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;

package/dist/limitsWire.js

@@ -1,101 +1,15 @@
-/**
- * src/limitsWire.ts — headless `-p` run-limits wire: expose the engine's TASK-LEVEL budget face on
- * the headless `-p` path via `TaskRequest.limits`.
- *
- * ── core 5.8.0 词表迁移([2489],2026-08-04)────────────────────────────────────────────
- * `limits` 是**唯一预算面,默认全空 = 无限制**。本模块拼的三个键都骑 5.8.0 的新词表:
- *   · `maxWalltimeMs`(**毫秒**;5.7 的 `limits.timeoutSec` 已删,单位一并变)
- *   · `maxTurns`
- *   · `maxOutputTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮;
- *     wire 键名自 5.7 起一直是 maxOutputTokens,core 内部才叫 maxTokens——[2569] 案订正)。
- *     🔴 到限形订正([2592]/[2593] 案):这是**单请求输出上限**不是累计预算——撞线=生成中被
- *     截断(工具调用参数途中被砍以 provider 截断披露上浮,core 3dfdb8f 起披露点名 cap),
- *     **不出** `limits.max_tokens_exceeded`(那是 core 内部累计预算键 `maxTokens` 的码,本 wire
- *     从不发那个键 ⇒ 消费端别拿那个码当 --max-tokens 的到限判据)。
- * 到限语义也换了:**没有配速机器了**。5.8.0 删掉了 deadlineNudge / callCapByDeadline /
- * gracefulFinalize 那一套(以及引擎侧 1000 轮安全网、fork 200、session-bg 30min 暗注等全部隐式
- * 默认),走到 `maxWalltimeMs` 不再是「引擎自己减速然后优雅收尾」,而是**响亮终局**:
- * `status:'failed'` + `errorCode:'limits.max_walltime_exceeded'`(`status:'timeout'` 这个词整体退役)。
- * 四个新码 `limits.max_{tokens,cost,turns,walltime}_exceeded` 的下游投影见
- * `adapter/downstream/terminalToSdkResult.ts`。
- *
- * ✅ **窗口期已关闭(退役批,2026-08-04)**:交付时点壳的引擎是 server 5.14.0(捆 core 5.7),它
- * **不认识** `maxWalltimeMs`/`maxTokens`(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,未知键
- * 静默丢弃),所以那段时间三个键里只有 `maxTurns` 真的生效。**server 6.0.0 已捆 core 5.8.0 发车**
- * ⇒ 新键集在班车上生效,读面的双代兜底(`adapter/downstream/terminalToSdkResult.ts`)本批一并退役。
- * 写面从头到尾是**单一新形**,不做两代并发(同时发 `timeoutSec` + `maxWalltimeMs` 会在 5.8 引擎上撞
- * `config.limit_unknown_key` 当场失败,那是拿窗口期的一次静默无视换班车到货后的确定性失败)。
- *
- * THREE FLAGS, THREE ALIGNMENT BUCKETS:
- *  · `--deadline <sec>`   → limits.maxWalltimeMs(用户面仍是**秒**,拼 wire 时 ×1000)。Upstream
- *    CC 2.1.207 has NO deadline flag → SUPERSET, help copy says so.
- *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
- *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
- *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
- *    carries the cap to where the turns actually run.
- *  · `--max-tokens <n>`   → limits.maxOutputTokens(5.8.0 主限;wire 键名见接口注——绝不直发
- *    core 内部键 maxTokens,[2569] 案)。Upstream CC 2.1.207 has no run-level
- *    token budget flag → SUPERSET.
- *
- * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
- *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
- *     value (integer domain below; a mis-typed budget bound must not quietly run unbounded).
- *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
- *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` / `SEMA_HEADLESS_MAX_TOKENS`
- *     → 同 a) FAIL-LOUD on an invalid value(#132 / test [2508] 2026-08-04 推翻旧 batch-E
- *     「静默降级」形;见 headlessLimitsFromEnv 的 JSDoc——非法值 {ok:false} 上抛,caller exit 1,
- *     常驻门 run-limits-env-failloud-test.mjs 守此形)。
- *  c) neither                                          → NO stamp = today's behaviour, verbatim.
- *
- * DOMAINS (integer, inclusive): deadline 30..86400 **秒**(→ 30_000..86_400_000 ms 上 wire)·
- * maxTurns / maxTokens = **正整数**(上界 = JS 安全整数)。maxTurns 此前钉 1..1000,那个上界抄的是
- * 引擎侧 1000 轮安全网;5.8.0 把该安全网整体退役了,壳再替它守一个不存在的墙就是凭空拒绝合法配置。
- *
- * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
- * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
- * construction; but a user-supplied SEMA_ENGINE_URL may point at an older engine. When the user
- * EXPLICITLY passed a flag (env-lane defaults stay quiet) and SEMA_ENGINE_URL is in play, the caller
- * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
- * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
- * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
- *
- * 📐 **两道地板,守的不是同一件事**(退役批补记,2026-08-04):
- *   · 第一地板 `LIMITS_WIRE_MIN_ENGINE = 1.196.0` = 「`limits` 这个**字段**存不存在」(server 1.196.0
- *     起接受 body.limits);低于它,整个预算面被丢。
- *   · 第二地板 **server ≥ 6.0.0** = 「**新键集**认不认」。6.0.0 是第一个捆 core 5.8.0 的 server 版本,
- *     也就是第一个认识 `maxWalltimeMs` 的版本(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,
- *     未知键静默丢弃)。**[2569] 案订正**:`maxOutputTokens` 自 5.7 就在 wire 词表,本模块此前
- *     直发 core 内部键 `maxTokens` 才是被静默无视的那个(server 6.3.0 起 400);对 1.196.0 ≤
- *     version < 6.0.0 的引擎,`maxTurns`/`maxOutputTokens` 生效而 `maxWalltimeMs` 被静默无视。
- *     之所以过去写不出这条:/health 自报的是 server 版本,而键名代际取决于它捆的 core 版本,当时
- *     两者没有可从 wire 读出的映射;6.0.0 这班车把映射钉死了(6.0.0 ⇒ core ≥5.8),这条地板才成立。
- *   · 本文件的运行期探针目前只对第一地板发声(warn, don't block);第二地板先落成契约事实写在这里,
- *     要不要给它也配一条 stderr 提示是**行为面**决定,按宪法三问单独走,不在退役批里顺手加。
- */
 import { hostEnv } from './hostEnv.js';
 import { lastFlagValue } from './argvFlagValue.js';
-/** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
 export const HEADLESS_DEADLINE_ENV = 'SEMA_HEADLESS_DEADLINE_SEC';
 export const HEADLESS_MAX_TURNS_ENV = 'SEMA_HEADLESS_MAX_TURNS';
 export const HEADLESS_MAX_TOKENS_ENV = 'SEMA_HEADLESS_MAX_TOKENS';
-/** `--deadline` 的**用户面**整数域(秒;30s..24h)。上 wire 前 ×1000 换成 `maxWalltimeMs`。 */
 export const DEADLINE_SEC_MIN = 30;
 export const DEADLINE_SEC_MAX = 86_400;
-/**
- * `maxTurns` / `maxTokens` 的整数域 = **正整数**(上界只到 JS 安全整数,再大就不是「一个精确的
- * 轮数/token 数」而是浮点近似了 —— 那种值静默夹取比拒绝更坏)。
- *
- * `MAX_TURNS_MAX` 此前是 `1_000`,抄的是引擎侧的 1000 轮安全网;core 5.8.0 把那张网**整体退役**
- * (「零配置任务现在没有任何任务级兜底」,[2489]),壳再守它 = 替一堵不存在的墙拒绝合法配置。
- * 常量名保留(它仍然是这个域的上界,只是值换成了真上界),消费者的 help 文案请按「正整数」写。
- */
 export const MAX_TURNS_MIN = 1;
 export const MAX_TURNS_MAX = Number.MAX_SAFE_INTEGER;
 export const MAX_TOKENS_MIN = 1;
 export const MAX_TOKENS_MAX = Number.MAX_SAFE_INTEGER;
-/** 用户面秒 → wire 毫秒(core 5.8.0 `limits.maxWalltimeMs` 的单位)。 */
 const SEC_TO_MS = 1_000;
-/** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
 export const LIMITS_WIRE_MIN_ENGINE = [1, 196, 0];
 const DEADLINE_USAGE = `sema: --deadline expects a whole number of seconds between ${DEADLINE_SEC_MIN} and ${DEADLINE_SEC_MAX}.\n` +
     '  --deadline <sec>     wall-clock budget for this run (sema superset — no upstream equivalent):\n' +
@@ -111,15 +25,7 @@ const MAX_TOKENS_USAGE = 'sema: --max-tokens expects a positive whole number of
     '                       generation mid-stream (a cut inside tool-call arguments surfaces as a\n' +
     '                       provider truncation error)\n' +
     '  (no flag)            no output-token cap — today\'s behaviour';
-/** STRICT integer shape for explicit flag values: ASCII digits only (no sign/decimal/exponent/space). */
 const INT_RE = /^\d+$/;
-// `lastFlagValue` (the `--name <v>`/`--name=<v>`/repeated-flag-last-wins scan) now lives in
-// argvFlagValue.ts (REF-CC-143/dup-07, P3 wave1 卡C-argv, 2026-08-01) — this was the fullest of five
-// hand-rolled copies (present/raw/valueMissing three-state) and is the one the shared leaf was cribbed
-// from verbatim; see that file's header for the shared 缺值 contract. All three flags are
-// all-positive domains, so a NEGATIVE number (which looks flag-shaped to the scanner) correctly
-// falls into the same fail-loud usage-hint path as a genuinely missing value below.
-/** Validate a RAW flag value against an inclusive integer domain. Returns the number or null. */
 function parseIntInDomain(raw, min, max) {
     const v = raw.trim();
     if (!INT_RE.test(v))
@@ -129,17 +35,9 @@ function parseIntInDomain(raw, min, max) {
         return null;
     return n;
 }
-/** 三个键任一在场 ⇒ 值得 stamp(空对象绝不上 wire —— 那是「配了个空预算」不是「没配」)。 */
 function hasAnyLimit(l) {
     return l.maxWalltimeMs !== undefined || l.maxTurns !== undefined || l.maxOutputTokens !== undefined;
 }
-/**
- * Parse `--deadline` + `--max-turns` + `--max-tokens` out of an argv slice. No flags ⇒ `{ok:true}`
- * with no limits. Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer /
- * out-of-domain ⇒ fail-LOUD parse error (never a silent default — same stance as
- * `--scenario`/`--sandbox`). `flaggedFlags` names the flags that EXPLICITLY contributed (the
- * version-gate probe trigger).
- */
 export function parseLimitsArgv(argv) {
     const limits = {};
     const flaggedFlags = [];
@@ -148,7 +46,6 @@ export function parseLimitsArgv(argv) {
         const n = dl.raw !== undefined ? parseIntInDomain(dl.raw, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX) : null;
         if (n === null)
             return { ok: false, error: DEADLINE_USAGE };
-        // 用户面是秒,wire 面是毫秒(core 5.8.0 `maxWalltimeMs`)—— 换算只在这一个方向、这一个点做。
         limits.maxWalltimeMs = n * SEC_TO_MS;
         flaggedFlags.push('--deadline');
     }
@@ -185,7 +82,7 @@ export function headlessLimitsFromEnv(env = hostEnv()) {
                 error: `Error: ${HEADLESS_DEADLINE_ENV}="${dl}" is not an integer in ${DEADLINE_SEC_MIN}..${DEADLINE_SEC_MAX} (seconds). Fix or unset it.`,
             };
         }
-        out.maxWalltimeMs = n * SEC_TO_MS; // env 面同样是秒(变量名带 _SEC),换算同一口
+        out.maxWalltimeMs = n * SEC_TO_MS;
     }
     const mt = env[HEADLESS_MAX_TURNS_ENV]?.trim();
     if (mt) {
@@ -205,23 +102,16 @@ export function headlessLimitsFromEnv(env = hostEnv()) {
     }
     return { ok: true, limits: hasAnyLimit(out) ? out : undefined };
 }
-/**
- * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
- * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
- * yields {maxWalltimeMs:300000, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
- */
 export function limitsForPrint(argv, env = hostEnv()) {
     const parsed = parseLimitsArgv(argv);
     if (!parsed.ok)
         return parsed;
-    // #132:env 面非法值与 flag 同拍响亮拒(见 headlessLimitsFromEnv 头注)。
     const fromEnv = headlessLimitsFromEnv(env);
     if (!fromEnv.ok)
         return { ok: false, error: fromEnv.error };
     const merged = { ...(fromEnv.limits ?? {}), ...(parsed.limits ?? {}) };
     return { ok: true, ...(hasAnyLimit(merged) ? { limits: merged } : {}), flaggedFlags: parsed.flaggedFlags };
 }
-/** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
 export function versionSupportsLimits(v) {
     const m = v ? /^(\d+)\.(\d+)\.(\d+)/.exec(v) : null;
     if (!m)
@@ -234,13 +124,6 @@ export function versionSupportsLimits(v) {
         return b > mb;
     return c >= mc;
 }
-/**
- * Version-gate probe (triage risk ③): GET `${baseUrl}/health`, read `version`, and return ONE honest
- * stderr line when the engine is confirmed <1.196.0 — the caller prints it and SENDS ANYWAY (the old
- * server drops the field server-side; warn, don't block). Returns undefined when the engine is new
- * enough, unreachable, or self-describes no parsable version (can't confirm staleness — fail-soft
- * silent; the release-pinned self-spawn lane never even reaches this probe).
- */
 export async function engineLimitsSupportWarning(baseUrl, flaggedFlags, opts) {
     const fetchImpl = opts?.fetchImpl ?? fetch;
     const controller = new AbortController();
@@ -254,14 +137,13 @@ export async function engineLimitsSupportWarning(baseUrl, flaggedFlags, opts) {
             return undefined;
         const body = (await res.json());
         const version = typeof body?.version === 'string' ? body.version : undefined;
-        // No version field = pre-1.96 engine — definitely older than 1.196.0, warn honestly.
         if (versionSupportsLimits(version))
             return undefined;
         const flags = flaggedFlags.length > 0 ? flaggedFlags.join('/') : '--deadline/--max-turns/--max-tokens';
         return `[sema] engine ${version ?? '(unversioned, pre-1.96)'} does not support ${flags} (needs ≥1.196.0); the flag will be ignored by the engine`;
     }
     catch {
-        return undefined; // unreachable/timeout — cannot confirm staleness, stay silent
+        return undefined;
     }
     finally {
         clearTimeout(timer);

package/dist/liveInitToolFace.d.ts

@@ -1,97 +1,20 @@
-/**
- * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 · B2 判给后批的**宿主耦合六件**之一):cli
- *    `src/sema/liveInitToolFace.ts` 整搬。B2 当时不搬的理由 = 它 `await import('./engineTarget.js')`
- *    取凭证,而 engineTarget 是 fs 重图;B4 的 §8-2 收编把凭证解析定到了 `resolveWireAuth`
- *    (engineWireSdk,零依赖),那条理由随之消失。
- *
- * 🔴 搬迁三处差分(行为一字节不变):
- *   ① 凭证:`engineTarget.resolveLiveAuthToken(baseUrl)`(其 token 缺省 = `process.env.SEMA_LIVE_TOKEN`)
- *      → `resolveWireAuth(baseUrl, env.SEMA_LIVE_TOKEN)`。两者是同一套 #118 三态,`resolveWireAuth`
- *      的头注自述就是它的收编口。取值面完全一致:三态里只有**真 token 串**与 `'anon'` 是 string,
- *      `{mode:'loopback-unauthed'}` 是对象 ⇒ 原文那句 `typeof t === 'string' ? t : undefined` 语义照搬。
- *   ② 三个 `await import('./xxxWire.js')` fail-soft 动态 import → **静态 import**(scenarioWire /
- *      interactiveToolsWire / webSearchWireCaps 三件 B5 都已在本包内)。原文那三层 try/catch 的
- *      目的是「模块缺席也别挡首帧」,包内它们不可能缺席;**try/catch 仍逐条保留**——它护的另一半是
- *      「函数自己抛」,那半在包内照样成立。
- *   ③ `process.env` → 入参 `EnvLike`(签名本来就显式收 env;缺省值不存在,调用方必传)。
- *
- * 🔴 模块级状态:`cached`(baseUrl+scenario+旋钮 键控的一次性探测缓存)。写读口都在本文件;
- *    两份实例只是多探一次(不是静默失效),但仍登记进单实例清单。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * liveInitToolFace — 件1(core [931] 壳半场):headless `-p` live 车道 `system/init` 首帧的
- * `tools` 自报面,从「壳静态工具表」改为「引擎实挂 wire 词表」生成。
- *
- * 根因(core [931]/CC209 裁决):壳自报静态表(TodoWrite 在、TaskCreate 族不在)而引擎 wire 实挂
- * TaskCreate 族(core 1.296+ 默认)且不挂 TodoWrite ⇒ SDK/自动化消费者照自报面配
- * `--disallowedTools TodoWrite` 之类静默无效(fail-open)。core 1.300 已在引擎侧加名单池审计
- * advisory(config.toolpolicy.unmatched_names)兜观测面;这里是壳半场 = 自报按实挂生成。
- *
- * 真源层级(gap-check 2026-07-16 实测读数,server 1.214.0 / core 1.300.0):
- *   1. server 无全量挂载探测面:GET /v1/capabilities 只有能力布尔;
- *      GET /v1/capabilities/scenarios/:name 只含【场景附加】工具(default/code →
- *      Now/WebFetch/Agent/TaskCreate 族七具),首方 band(Bash/Read/…)由 core prepare-task
- *      另挂、不进该面 ⇒ 整表无法远端取。
- *   2. 故缺省场景用壳已知 wire 词表(下表):观测 tap 记录壳 `-p` live 车道 LLM 请求体
- *      tools[].name(REMOTE_EXEC=host 生产姿势)实测定稿,再按壳自己 stamp 的请求旋钮修正
- *      (interactiveTools≠false → AskUserQuestion;settings.webSearch 在 → WebSearch)。
- *   3. per-scenario 差异如实标注:非缺省 scenario(--scenario/SEMA_HEADLESS_SCENARIO)的工具面
- *      由部署定义(scan/oa = repo-readonly 面,首方 band 是否在位壳无法确证)⇒ 尽力探场景详情面
- *      GET /v1/capabilities/scenarios/:name 报【场景附加】工具 + runner 恒挂段,并经
- *      SEMA_DEBUG 如实标注是探测面而非整表;探测失败回退缺省词表(fail-soft,绝不阻塞首帧)。
- *   4. mock/离线车道(无 SEMA_LIVE_BASEURL)返回 null,调用方保持现状静态表 —— 宪法三问的
- *      补偿轴:离线态回退静态表,行为字节不变。
- *
- * 已知局限(如实):词表按 pin 的 server/core 版本定稿,外接旧引擎或无执行底座的 worker
- * (REMOTE_EXEC 缺省的裸 worker 不挂 hands band)会有偏差 —— 但相比旧静态表(TodoWrite 幻影 +
- * TaskCreate 族缺席)已是严格更准的自报;整表探测面等引擎侧补(见 [931] 报告)。
- */
 import { type EngineProbeOpts } from './engineWireSdk.js';
 import type { EnvLike } from './hostEnv.js';
-/** hands band(本地/远程执行底座在位时 prepare-task 挂载;壳自 spawn 恒 REMOTE_EXEC=host ⇒ 在位)。 */
 export declare const ENGINE_HANDS_BAND: readonly string[];
-/** 缺省(code/default)场景附加段 —— 与 GET /v1/capabilities/scenarios/{code,default} 详情面
- *  实测逐字一致(场景工厂 nowTool + assembleFullBodyTools)。
- *  ⚠️ TodoWrite 故意不在(core 1.296+ 默认 taskList:true ⇒ TodoWrite 不挂,[931] 本案根因);
- *  TaskCreate 族在 —— 这两条就是本修要对齐的实况。 */
 export declare const ENGINE_SCENARIO_EXTRAS_DEFAULT: readonly string[];
-/** runner 恒挂段(prepare-task 按请求旋钮挂载、场景无关):壳 `-p` 恒 stamp
- *  selfOrchestration→Workflow、attachments.backgroundTasks→TaskOutput/TaskStop/Monitor/
- *  SendMessage/AgentTranscript;ReadToolResult/ReportBlocked/ReportFindings/Skill/Cron 族/
- *  ScheduleWakeup 为 runner 缺省注入。 */
 export declare const ENGINE_RUNNER_FACE: readonly string[];
-/** [1036]/clay 裁:runner 恒挂段按壳已知 env 门过滤——print 宿主前置 SCHEDULER_ENABLED=false
- *  (scheduler 族 headless 不挂)/SELF_ORCHESTRATION_ENABLED=false(Workflow 卸)时,自报面
- *  必须跟实挂(此前静态词表在 env 门形态失真=自报 32 实挂 28,消融实测逮到)。 */
 export declare function runnerFaceForEnv(env: EnvLike): string[];
 export type LiveInitToolFace = {
     tools: Array<{
         name: string;
     }>;
-    /** 'wire-vocabulary' = 缺省词表;'scenario-probe' = 非缺省场景 + 详情面探测成功。 */
     source: 'wire-vocabulary' | 'scenario-probe';
 };
-/** 测试钩子:清缓存。 */
 export declare function _resetLiveInitToolFaceForTest(): void;
-/** 非缺省场景的详情面探测:SDK 0.0.52 scenarioCapabilities(name)(GET /v1/capabilities/scenarios/:name,
- *  同 wire 同 encodeURIComponent)→ { tools(场景附加段), toolset }。fail-soft:任何失败(网络/404/
- *  形状不符/超时)返回 null,调用层回退缺省词表。等价性记账:超时经 client timeoutMs(缺省 2s 同预算,
- *  maxRetries=0 单发同原语义);ScenarioDetail 类型面之外仍保留逐字段运行时校验(引擎回什么不轻信)。
- *  principal 头:SDK 6.11 起值检查删头(缺席不发;F-011 停发后单机形恒缺席)——原手抄在无 principal
- *  时省略该头;principal-first 宪法姿势,对 requirePrincipal 部署是 fail-open 改善。 */
 export declare function probeScenarioTools(baseUrl: string, scenario: string, opts?: EngineProbeOpts): Promise<{
     tools: string[];
     toolset?: string;
 } | null>;
-/**
- * resolveLiveInitToolFace — live 车道 init 首帧 `tools` 的实挂投影。
- *   · 无 SEMA_LIVE_BASEURL ⇒ null(mock/离线车道,调用方维持静态表现状);
- *   · 缺省场景 ⇒ hands band + runner 恒挂段 + 旋钮修正(词表车道,零 IO);
- *   · 非缺省场景 ⇒ 详情面探测成功用【场景附加 + runner 恒挂】(如实标注:hands band 是否在位
- *     由部署定,不妄报),失败回退缺省词表;
- *   · 任何内部错误 fail-soft 返回 null(调用方回退静态表,首帧永不因此缺席)。
- */
 export declare function resolveLiveInitToolFace(argv: readonly string[], env: EnvLike, opts?: {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;