@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/websearch/searchProviderPresets.js

@@ -1,10 +1,8 @@
 import presetData from './searchProviderPresets.json' with { type: 'json' };
 const rawTable = presetData;
-/** wire 枚举守卫(与服务端 `web-search.ts` 的三值校验同一份口径)。 */
 function isWebSearchProvider(v) {
     return v === 'brave' || v === 'tavily' || v === 'searxng';
 }
-/** `null` = 诚实缺席 ⇒ 键整个不出现在对象上(而不是留一个 `undefined` 值位)。 */
 function optional(v, key) {
     return v === null ? {} : { [key]: v };
 }
@@ -23,15 +21,9 @@ function toPreset(row) {
         ...optional(row.note, 'note'),
     };
 }
-/** 搜索 provider 目录(表序即端的展示序)。 */
 export const SEARCH_PROVIDER_PRESETS = rawTable.presets
     .map(toPreset)
     .filter((p) => p !== undefined);
-/**
- * 数据表自检口(与 `compensationSplitViolations()` 同一个套路:表的不变量做成可执行判据,
- * 由门断言恒空)。上面 `toPreset` 对非法 provider 的行只能**丢掉**(类型化的表里放不下它),
- * 丢掉本身是静默的 —— 这个函数就是那份静默的账。
- */
 export function searchPresetTableViolations() {
     const out = [];
     const seen = new Set();
@@ -60,14 +52,12 @@ export function searchPresetTableViolations() {
     }
     return out;
 }
-/** 按 id 取一行(trim + 大小写不敏感,与 wire 侧 provider 归一同口径)。查不到 ⇒ undefined。 */
 export function findSearchPreset(id) {
     const key = typeof id === 'string' ? id.trim().toLowerCase() : '';
     if (!key)
         return undefined;
     return SEARCH_PROVIDER_PRESETS.find(p => p.id.toLowerCase() === key);
 }
-/** 引擎吃的五个 env 键(单一真源:端别再手写字面量)。 */
 export const WEB_SEARCH_ENV_KEYS = {
     provider: 'WEB_SEARCH_PROVIDER',
     apiKey: 'WEB_SEARCH_API_KEY',
@@ -77,9 +67,7 @@ export const WEB_SEARCH_ENV_KEYS = {
 };
 export const WEB_SEARCH_MAX_RESULTS_MIN = 1;
 export const WEB_SEARCH_MAX_RESULTS_MAX = 20;
-/** 引擎侧的默认值,**只供端显示**(「默认 10」)。🔴 绝不由本模块写进 env,理由见文件头纪律 2。 */
 export const WEB_SEARCH_ENGINE_DEFAULTS = { maxResults: 10, timeoutMs: 10000 };
-/** 绝对 http/https URL 形校验。相对地址/其它协议一律拒 —— 引擎会拿它去拨号。 */
 function isDialableUrl(raw) {
     try {
         const u = new URL(raw);
@@ -90,13 +78,6 @@ function isDialableUrl(raw) {
     }
 }
 const trimmed = (v) => (typeof v === 'string' ? v.trim() : '');
-/**
- * 判定一份选择能不能编译成可用的 env。**纯判定,不产出任何值** —— 端可以在用户还在输入时
- * 反复调它做即时提示,不必担心把半截配置漏给引擎。
- *
- * 🔴 越界的 `maxResults` 判红而不是 clamp:引擎那侧确实会 clamp,但客户端替用户把 50 改成 20
- * 是**替他改了他填的数**却不告诉他。宁可红一下让端说「1..20」。
- */
 export function validateWebSearchChoice(choice = {}) {
     const id = trimmed(choice.presetId);
     if (!id)
@@ -124,20 +105,12 @@ export function validateWebSearchChoice(choice = {}) {
     }
     return { ok: true, preset };
 }
-/**
- * 用户选择 → 引擎 env。**唯一**的编译口(端别自己拼字面量键)。
- *
- * 🔴 三条已在文件头写死的纪律在这里落地:配置不可用 ⇒ `{}`(fail-closed,理由去问
- * `validateWebSearchChoice`);用户没填的可选项不出键(不替引擎钉默认值);任何值都先 trim,
- * 空串一律当没填 —— 返回的对象里**不存在**值为空串的键。
- */
 export function buildWebSearchEnv(choice = {}) {
     const verdict = validateWebSearchChoice(choice);
     if (!verdict.ok)
         return {};
     const { preset } = verdict;
     const env = { [WEB_SEARCH_ENV_KEYS.provider]: preset.provider };
-    // needsKey=false 的家不带 key:那家用不上它,把凭证多送一程没有收益只有暴露面。
     const apiKey = trimmed(choice.apiKey);
     if (preset.needsKey && apiKey)
         env[WEB_SEARCH_ENV_KEYS.apiKey] = apiKey;

package/dist/wireErrorTriage.d.ts

@@ -1,190 +1,34 @@
-/**
- * 网络/传输层失败的词面基表(壳 seamQuery「件2c transport 收窄」的那条正则逐字)。
- * 判据变更义务:加词=各端跟批;删词/改形=先与消费端对表(web 叠加宿主词的半场见其
- * turn-error-classify 头注)。
- */
 export declare const WIRE_NETWORK_ERROR_PATTERN: RegExp;
-/** turn 错误的结构化分型判决(渲染/文案归端;门与遥测按 kind 对账)。 */
-export type TurnWireErrorVerdict = 
-/** 引擎应答了非 2xx(reachable)。`errorCode` 只认活键([2055]);缺席=不带。 */
-{
+export type TurnWireErrorVerdict = {
     kind: 'http';
     status: number;
     errorCode?: string;
     message: string;
-}
-/** SDK typed park 信号:流结束但 run 未达终态(多半 suspended 候人决断)—— 不是故障。 */
- | {
+} | {
     kind: 'stream-ended-without-terminal';
-}
-/** 真网络/传输层失败(引擎压根没应答)。detail = cause 原话 > message > String(err)。 */
- | {
+} | {
     kind: 'transport';
     detail: string;
-}
-/** 分类不明(多半是客户端自己的 bug)—— 如实报,绝不指去查引擎/网络。 */
- | {
+} | {
     kind: 'internal';
     name: string;
     detail: string;
 };
-/**
- * turn 错误分型(模块头②节的四臂;臂序=壳 `semaApiErrorContent` 逐字:http → park 信号 →
- * transport/internal)。纯判定,永不抛。
- */
 export declare function classifyTurnWireError(err: unknown): TurnWireErrorVerdict;
-/**
- * 真·网络/传输层失败判(壳 `engineTarget.isEngineTransportError` 逐字语义):typed HTTP error
- * (numeric `status` 在场 = 引擎应答了)恒 false —— 死端点分诊绝不误挂在活引擎的业务错误上。
- * 消费面:headless `-p` 死 pin 提示 / 审批提交腿的重试判型(approvalSubmitRetry)。
- */
 export declare function isWireTransportError(err: unknown): boolean;
-/**
- * 判型:server drain 门的 pre-stream 拒收(503 + `errorCode:"draining"`)。结构判读不
- * instanceof(mock/包装错误同判);机器码单腿(sdk 4.0.0 起 message 腿退役)。
- * 消费面的重试铁律(严格限定 pre-stream、有界)归壳 seamQuery 的重试环。
- */
 export declare function isPreStreamDrainingReject(err: unknown): boolean;
-/**
- * #166 — `resume_at.*` 错误码族:提交带的 resumeAt 锚服务端不认(Esc 杀锚未持久化的典型形)。
- * 🔴 刻意**不**用 `isRewindFamilyCode`(那是含 `rewind_snapshot.` 的宽形):去锚自动重发的安全性
- * 论证只对 resume_at 族做过,放宽属行为变更(RESUME_AT_ERROR_CODE_PREFIX 头注)。
- *
- * ## #355 D1 —— 两条载体腿(2026-08-27)
- * 同一个语义在 wire 上有**两种形**,此前只认第一种:
- *   · **机读形**(既有腿,一字未动):core prepare-throw 经 `resumeAtHttpStatus` 落 4xx,
- *     `errorCode` **原样透传**真子码(`resume_at.not_found` / `resume_at.before_target_not_user` …)
- *     ⇒ 前缀命中。
- *   · **包装形**(本腿新增):server 的**预检腿**在 core 之前就 4xx —— `boot/resolve-spec.ts`
- *     抛 `HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)")`
- *     且**不带** `code`,于是 `http/send.ts` 的 `httpErrorCode(404)` 盖上按状态码派生的粗码
- *     `not_found.resource`,真子码**只活在人话里**。SDK `classifyApiError` 把 body 的 `error`
- *     原样搬进 `APIError.message`(scrub 只动 Bearer/presigned),所以壳收到的是
- *     `{status:404, errorCode:'not_found.resource', message:'…(resume_at.unknown_event)'}`。
- *     旧判据 false ⇒ #166 去锚重发整臂跳过 ⇒ 会话每条消息秒死 404、永久死锁(1.0.93 现网案)。
- *
- * ## 放宽的论证(engineErrorCodes `RESUME_AT_ERROR_CODE_PREFIX` 头注要求「放宽须论证」)
- * 本腿放宽的是**载体**(码位 → 码位∪人话),不是**族**:
- *   ① 三重合取收敛误触面:`status === 404`(引擎真应答了,不是网络/内部错)+ 人话里出现
- *      **同一个族前缀**字面 + 调用点自己的 `req.resumeAt !== undefined`(seamQuery #166 臂)
- *      —— 没带锚的提交压根进不来,与「404 里恰好出现 `resume_at.` 字样」撞车要三件同时成立。
- *   ② 族边界一字未松,而且文本腿收成**闭集**:只认 `RESUME_AT_TEXT_COMPAT` 里那两对
- *      「状态 × 括号收尾子码」——`404 × (resume_at.unknown_event)` 与
- *      `422 × (resume_at.no_session)`,正是 `boot/resolve-spec.ts` 两处**不带 `code`** 的 throw。
- *      `rewind_snapshot.` / `rewind_files_to.` 邻族不入内(邻族的自动重发安全性没论证过);
- *      开集形与裸子串形都已被异源复审证伪(token 边界 + 回显注入两条,论证见
- *      {@link RESUME_AT_TEXT_COMPAT})。带 code 的那一路(core prepare-throw 经 `resumeAtHttpStatus`
- *      落 4xx)`errorCode` 原样透传,早被 ① 接住,压根不经过这里。
- *   ③ 422 那一支不是「顺手放宽」:它与 404 支同为预检腿的 codeless throw,处置也同款 —— 去锚重发在
- *      `no_session` 上不但安全、而且**正是正解**(没有可分支的 session,新起一轮本来就是对的)。
- *      原形把它留在门外、负控还把「422 恒 false」钉成期望值 —— 那不是负控,是把残余固化成契约。
- *   ④ 误触的代价上界很低而漏判的代价是死锁:误命中最多多发一次**去锚的**同一条提交(pre-stream
- *      零副作用,与 draining 同一铁律边界)+ 一行人话;漏判 = 会话再也发不出消息。
- *   ⑤ 刻意**不**加「粗码必须等于 `request.unprocessable` / `not_found.resource`」这层收窄:那张
- *      状态码→粗码表是 server `http/send.ts` 的实现细节(会随版本增删),把判据押在它上面等于给自己
- *      种一颗静默失效的雷;判别力已由 ② 的闭集承担。
- *
- * 🔴 根治在发端、且**已经落地**:server 给那四条拒绝子码补上了结构化 `code` 参,新 worker 一律走
- * 机读腿 ①。本腿因此是**对已发布旧 server 的过渡垫片**(1.0.93 现网用户跑的正是那些),不是长期形;
- * 等最低 server 版本推过去之后可以整条退役。
- *
- * 🔴 只影响本函数的判定,`RESUME_AT_ERROR_CODE_PREFIX` 常量与它的另一个消费点
- * `isRewindFamilyCode`(rewind 可自解族的**码**判别)一字未动。
- */
 export declare function isResumeAtRejection(err: unknown): boolean;
-/**
- * 第 `attempt`(0-based)次 draining 重试前的等待:`err.retryAfterMs`(SDK 若带)封顶优先
- * (上限 15s = server drain 门现值,防把一个 turn park 到分钟级),缺席走退避梯
- * (默认 1s/2s/4s = 壳 S4-P0 实测值;超出梯长取末档)。`opts.ladder` = 端的测试钩子注入口
- * (壳 `setDrainingBackoffForTest` 经此透传)。纯函数,零模块状态(singleton 门口径)。
- */
 export declare function drainingRetryDelayMs(err: unknown, attempt: number, opts?: {
     ladder?: readonly number[];
     retryAfterCapMs?: number;
 }): number;
-/** 结构化拒绝字段(与 SDK `ScenarioNotAllowedError` 同形;判定层不依赖 SDK 类型面)。 */
 export interface ScenarioDenyDetail {
-    /** The principal's allowed scenario names (defensively filtered; may be empty). */
     allowlist: string[];
 }
-/**
- * 从一个被 catch 的错误判定「场景不在指派列表」并提取结构化 detail。
- * duck-typed(不 instanceof — bundle 下跨包类标识可能双实例):`status===400 &&
- * errorCode===SCENARIO_NOT_ALLOWED_ERROR_CODE` 即命中;allowlist 缺席/非数组/畸形项 → 逐项
- * 防御过滤成空数组(兜底文案契约归端)。非该 code 的 400 / 其他错误 → null(绝不误吃普通 400)。
- * 🔴 键位([2055] 死键纪律):只认 `errorCode`,退役 `code` 键不做兼容(clean-cut)。
- */
 export declare function scenarioDenyFromError(err: unknown): ScenarioDenyDetail | null;
-/**
- * {@link resumeRetryLaterFromError} 的结构化读数。
- *
- * 判定层**不依赖 SDK 类型面**(与 {@link ScenarioDenyDetail} 同款):注入面可能是宿主的裸 fetch、
- * desktop 的 IPC 转投、web 跨 bundle 的 plain object,也可能是比本包新一版的 SDK ——
- * 这些形上 `instanceof ResumeRetryLaterError` 一律为假,而 `errorCode` 恒在。
- */
 export interface ResumeRetryLaterDetail {
-    /**
-     * 命中的那一个码({@link RESUME_RETRY_LATER_CODES} 的成员之一)。
-     * 🔴 **两码不是同一个处置**:能不能等看 {@link waitable}(本码 ∧ 有没有窗),本位只回答「是哪一个
-     * 成因」—— 治理窗满(与部署的账本配额有关)还是部署预检拒(与部署自己那只 `resumePreflight`
-     * 有关)。排障要分得清,措辞也要分得清;**别拿本位反推可等性**。
-     */
     code: string;
-    /**
-     * server 给的**等待秒数**。
-     * 🔴 **缺席 = 服务端没给窗**,不是 0、不是「立刻」—— 绝不渲一个编出来的倒计时
-     *    ([honest-absence-not-fabricated-zero])。≤7.46 引擎、以及**把这条错误经 SDK ≤8.0 映射
-     *    过来**的宿主(那些版本上本码落无字段的族基类 `SubagentResumeConflictError`)都恒缺席。
-     * 🔴 **「缺席时该说什么」不由本位决定,由 {@link waitable} 决定**:`waitable === true` 而窗缺席
-     *    (治理窗满、或老 SDK 把窗吞了)⇒ 说「稍后重试」但不给数字;`waitable === false` ⇒ **不许**
-     *    说「稍后重试」(见那一位顶注:那是不可判,不是可等)。
-     */
     retryAfterSec?: number;
-    /**
-     * **等一会儿到底有没有用** —— 本口唯一的处置位,也是全包对这个问题的**单一判断点**。
-     *
-     * 🔴 **为什么不是「命中本族即可等」**(异源对抗复审 [medium] 真病修):`resume.preflight_rejected`
-     *    在 core 侧有**两条臂** —— 缺省的 `retry_later`(行留 pending,同一 token 障碍清除后仍可赎)
-     *    与显式 `terminal`(行已被这次拒绝的单发 expire CAS 结清,token **不可再赎**)——而**判别位
-     *    在 message 散文里**,wire 上没有机读位。仅凭码就宣告「稍后重试」,会把一个终局说成暂时等待。
-     *    本包**不按文案分臂**(按文案分支正是上游改一个词就静默空转的形),所以只认**正向证据**:
-     *      · `resume.usage_window_exhausted` ⇒ 恒 `true` —— core 铸文的不变量是「什么都没消费、
-     *        什么都没解钉,同一 token 带同一决议在窗放开后可直兑」,这一码本身就是证据;
-     *      · `resume.preflight_rejected` ⇒ **只有** server 给了等待窗({@link retryAfterSec} 在场)才 `true`;
-     *        窗缺席时是 `false` = **不可判**,不是「不可重试」。
-     * 🔴 **「有窗 ⇒ 一定是 retry_later 臂」是直证不是推断**(core 7.3.1 fixture 直读
-     *    `@sema-agent/core/dist/core/runner/runtask.js` 的 `resumePreflight` 拒绝段):
-     *      · `terminal` 臂(`disposition === 'terminal'` ∧ 有可读 message ⇒ 单发 `store.expire` CAS 结清、
-     *        文末逐字 "the token is not redeemable")抛的 `CheckpointError` **一个 detail 都不带** ⇒
-     *        `retryAfterMs` 结构上不存在 ⇒ server 那一侧无从铸 `retryAfterSec`;
-     *      · `retry_later` 臂(超时/崩溃/普通拒三支,文末逐字 "the checkpoint stays pending and the same
-     *        token is redeemable once the obstacle clears")**只在部署真给了 `retryAfterMs` 时**带 detail。
-     *    ⇒ 窗**在场**是 retry_later 的充分证据;窗**缺席**两臂都可能(retry_later 也常常没有建议),
-     *    所以缺席只能读作「不知道」。
-     * 🔴 `false` 的正确读法是「**我不知道还能不能再赎**,读引擎那行原文」——**不是**「一定不能」。
-     *    两臂都成立的那句话仍可放心说:这一拒发生在提交之前,人的决定没被消费。
-     */
     waitable: boolean;
 }
-/**
- * 被 catch 的错误 → resume **时间性拒绝**读数;不是那两个码 ⇒ `null`(绝不误吃这一族里别的 409)。
- *
- * 🔴 **判据只有 `errorCode`,不看 HTTP 数字**:与 `classifySubagentResumeFailure`(同包
- *    `subagent/engineSubagentResume.ts`)的既有口径同律(`resume.*` 那一族成员全是 409,按数字分支
- *    等于把几种不同处置压成一种);而本口的
- *    处置是**告诉人等一会儿**——非破坏性,不需要 {@link scenarioDenyFromError} 那种「码 ∧ 状态」的
- *    合取闸(那一条守的是别让一个只是**引用**了该码的响应驱动一次真动作)。
- * 🔴 **结构读不 `instanceof`**:见 {@link ResumeRetryLaterDetail} 顶注(三端注入面 / 跨 bundle 同名类
- *    是两个实例)。键位只认 `errorCode`([2055] 死键纪律,退役 `code` 槽不做兼容)。
- * 🔴 **本口只报事实,处置位是 {@link ResumeRetryLaterDetail.waitable}**:命中本族 **≠** 一定可等 ——
- *    `resume.preflight_rejected` 有一条 `terminal` 臂(token 不可再赎)而判别位只在 message 散文里。
- *    「等一会儿有没有用」的判断收在 `waitable` 这一位上(全包单一判断点),名字里的 RetryLater 是
- *    上游 SDK 的类名锚,**不是**本口对每一次命中的断言。
- * 🔴 **`retryAfterSec` 的窄读域 = server 的铸键域**(整数 ∧ ≥1),不更宽也不更窄:
- *      · server 铸键逐字是「ms → 秒**向上取整**、**下限 1**」⇒ 真供给里不存在 0 / 负数 / 小数;
- *      · 放行 0 就是对消费端说「立刻重试」,而 resume 是 AT-MOST-ONCE 的有副作用动作
- *        (叫醒 = 真跑一轮)—— 一个 0 会把「等一会儿」变成热循环;
- *      · 放行小数会让端渲出「等 0.4 秒」这种上游从未说过的量。
- *    坏值一律**降缺席**(不是降 0、不是取绝对值):没读到窗与读到一个假窗,前者诚实。
- */
 export declare function resumeRetryLaterFromError(err: unknown): ResumeRetryLaterDetail | null;

package/dist/wireErrorTriage.js

@@ -1,37 +1,5 @@
-/**
- * wireErrorTriage.ts — turn 错误分型的**判定半场**(A-028.11/.13,#244 族E,2026-08-15)。
- *
- * ## 收编前的形(census top-10 §1/§3)
- * 同一套「turn 失败 → 分型 → 处置类」判定跑着**两份半**:
- *   · 壳 `seamQuery.semaApiErrorContent` 的判型内联(typed HTTP / 网络词面 / internal 三分支)
- *     + `isPreStreamDrainingReject` / `isResumeAtRejection` / `drainingRetryDelayMs`;
- *   · 壳 `engineTarget.isEngineTransportError`(注释自陈「两处判据变更须同步」的第二份 inline);
- *   · web `turn-error-classify.ts`(580 行第二实现,靠跨仓逐 token 读壳源码的 parity 门硬撑)。
- * 本件把**纯判定**收成一份:错误对象 → 结构化分型判决。人话文案与渲染(Ink 行 / web 卡)
- * 按 §8-5 归各端 —— 本件绝不铸一句面向用户的话。
- *
- * ## 判定语义(壳侧逐字,行为面零变化)
- *   ① `typeof err.status === 'number'` ⇒ **http**(引擎真的应答了):机器码只认 `errorCode`
- *      ([2055] 死键纪律:退役 `code` 槽不作兼容);
- *   ② `err.name === 'StreamEndedWithoutTerminalError'`(#156/[2669] SDK typed park 信号,name 判
- *      别 —— 跨包 instanceof 不可靠)⇒ **stream-ended-without-terminal**(run 多半 suspended
- *      候人决断,绝不谎报网络/壳 bug);
- *   ③ 网络词面命中或 undici `cause` 在场 ⇒ **transport**(真网络层;detail 取 cause 原话优先);
- *   ④ 其余 ⇒ **internal**(分类不明如实说,不编造网络原因 —— 编一个具体原因比说不知道坏得多)。
- *
- * ## 词面表的跨端义务
- * {@link WIRE_NETWORK_ERROR_PATTERN} 是壳/web 共用的**基表**(web 侧另有浏览器 fetch 的四种说法
- * `failed to fetch`/`networkerror`/`network error`/`load failed`,那是宿主词,由 web 在自己那半场
- * 叠加)。web 的 run-error-table-parity-test(逐 token 读壳源码)随本件退役为「共用同一 import」。
- */
 import { DRAINING_ERROR_CODE, RESUME_AT_ERROR_CODE_PREFIX, RESUME_RETRY_LATER_CODES, RESUME_USAGE_WINDOW_EXHAUSTED, SCENARIO_NOT_ALLOWED_ERROR_CODE, } from './engineErrorCodes.js';
-/**
- * 网络/传输层失败的词面基表(壳 seamQuery「件2c transport 收窄」的那条正则逐字)。
- * 判据变更义务:加词=各端跟批;删词/改形=先与消费端对表(web 叠加宿主词的半场见其
- * turn-error-classify 头注)。
- */
 export const WIRE_NETWORK_ERROR_PATTERN = /fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|EPIPE|socket hang up|UND_ERR|terminated|other side closed/i;
-/** 传输失败 detail 的取值序(undici `.cause` 的精确 host:port 优先)。包内共用,不出公面。 */
 function wireErrorDetail(err) {
     const e = err;
     const cause = e?.cause;
@@ -39,10 +7,6 @@ function wireErrorDetail(err) {
         (typeof e?.message === 'string' && e.message.length > 0 && e.message) ||
         String(err));
 }
-/**
- * turn 错误分型(模块头②节的四臂;臂序=壳 `semaApiErrorContent` 逐字:http → park 信号 →
- * transport/internal)。纯判定,永不抛。
- */
 export function classifyTurnWireError(err) {
     const e = err;
     if (typeof e?.status === 'number') {
@@ -50,11 +14,6 @@ export function classifyTurnWireError(err) {
         const message = typeof e.message === 'string' && e.message.length > 0 ? e.message : String(err);
         return { kind: 'http', status: e.status, ...(errorCode !== undefined ? { errorCode } : {}), message };
     }
-    // park 判别按 `name` **结构读**,不附加 instanceof Error(复审 F3 [medium] 真病修):壳源形的
-    // `err instanceof Error &&` 合取在单进程壳里恒真无害,但本件是三端共用面 —— desktop IPC 序列化 /
-    // web 跨 bundle 的同名错误是 plain object,instanceof 合取会把「候人决断」误诊成「客户端 bug +
-    // 建议重跑」(重跑=重复 turn,且掩盖真待决态)。壳注释自陈的意图本就是「name 判别(跨包
-    // instanceof 不可靠)」—— 这里把实现对齐到意图(更强形,park 臂只宽不窄)。
     const errName = typeof err === 'object' && err !== null && typeof err.name === 'string'
         ? err.name
         : undefined;
@@ -67,128 +26,29 @@ export function classifyTurnWireError(err) {
         return { kind: 'transport', detail };
     return { kind: 'internal', name: err instanceof Error ? err.name : typeof err, detail };
 }
-/**
- * 真·网络/传输层失败判(壳 `engineTarget.isEngineTransportError` 逐字语义):typed HTTP error
- * (numeric `status` 在场 = 引擎应答了)恒 false —— 死端点分诊绝不误挂在活引擎的业务错误上。
- * 消费面:headless `-p` 死 pin 提示 / 审批提交腿的重试判型(approvalSubmitRetry)。
- */
 export function isWireTransportError(err) {
     const e = err;
     if (typeof e?.status === 'number')
         return false;
     return e?.cause !== undefined || WIRE_NETWORK_ERROR_PATTERN.test(wireErrorDetail(err));
 }
-/**
- * 判型:server drain 门的 pre-stream 拒收(503 + `errorCode:"draining"`)。结构判读不
- * instanceof(mock/包装错误同判);机器码单腿(sdk 4.0.0 起 message 腿退役)。
- * 消费面的重试铁律(严格限定 pre-stream、有界)归壳 seamQuery 的重试环。
- */
 export function isPreStreamDrainingReject(err) {
     const e = err;
     return typeof e?.status === 'number' && e.status === 503 && e.errorCode === DRAINING_ERROR_CODE;
 }
-/**
- * #355 D1 文本兼容腿认的**闭集**:server 预检腿两处 codeless throw 的「状态 × 子码」配对,
- * 且必须以 server 自己那种**括号收尾**的形出现(`…(resume_at.unknown_event)`)。
- *
- * 🔴 为什么是闭集而不是开集(异源复审第四轮 [medium] 真病修):这条腿的定位是「**已发布**的旧
- * server 的兼容垫片」——一个**历史封闭**的集合。新码一律带结构化 `errorCode`(server 已在发端补齐
- * 四条子码的 `code` 参),走前缀腿 ① 直接命中,根本不经过这里。开集在这里换不来任何前瞻性,却把
- * 判据暴露在**回显注入**下。
- *
- * 🔴 回显注入是真事(亲读 server `config.ts:formatUnmatchableToolNames`):它把**用户送来的**工具名
- * 逐字拼进错误文本(`… names tool(s) …: <用户的名字> → <guidance>`,多条以 `; ` 连接),再由
- * `resolve-spec` 翻成一个**普通 codeless 422**。于是「任意 422 + 文本里出现 resume_at.<任意成员>」
- * 这种开集判据,可以被一条名叫 `resume_at.foo` 的权限规则触发 —— 而那一拍用户的 `resumeAt` 锚是
- * **有效**的,后果是:壳把有效锚删掉、渲一行「恢复点失效」(与事实不符 = 编造归因)、再重发一次。
- *
- * 堵法是**闭集 + 串尾锚**两件一起:
- *   · 闭集挡住 `resume_at.<任意成员>`;
- *   · 串尾锚(消费点用 `endsWith`)挡住「用户把整串 `(resume_at.no_session)` 连括号写进权限名」——
- *     那一形里回显内容后面必然还跟着 ` → guidance`,永远到不了串尾。少了串尾锚,闭集单独是漏的
- *     (异源复审第五轮实测反证)。
- * 串尾成立的依据是实证不是假设:7.42.0–7.50.0 七份已发布 server 产物里,这两句的码后面紧跟的就是
- * 字符串字面量的结束引号。
- *
- * 字面单源:两枚子码由 {@link RESUME_AT_ERROR_CODE_PREFIX} 拼出,常量改了这里自动跟。
- * 认不出 ⇒ 退化成「不自动去锚重发」= 修这一批之前的行为,绝不会更坏。
- */
 const RESUME_AT_TEXT_COMPAT = [
     { status: 404, marker: `(${RESUME_AT_ERROR_CODE_PREFIX}unknown_event)` },
     { status: 422, marker: `(${RESUME_AT_ERROR_CODE_PREFIX}no_session)` },
 ];
-/**
- * #166 — `resume_at.*` 错误码族:提交带的 resumeAt 锚服务端不认(Esc 杀锚未持久化的典型形)。
- * 🔴 刻意**不**用 `isRewindFamilyCode`(那是含 `rewind_snapshot.` 的宽形):去锚自动重发的安全性
- * 论证只对 resume_at 族做过,放宽属行为变更(RESUME_AT_ERROR_CODE_PREFIX 头注)。
- *
- * ## #355 D1 —— 两条载体腿(2026-08-27)
- * 同一个语义在 wire 上有**两种形**,此前只认第一种:
- *   · **机读形**(既有腿,一字未动):core prepare-throw 经 `resumeAtHttpStatus` 落 4xx,
- *     `errorCode` **原样透传**真子码(`resume_at.not_found` / `resume_at.before_target_not_user` …)
- *     ⇒ 前缀命中。
- *   · **包装形**(本腿新增):server 的**预检腿**在 core 之前就 4xx —— `boot/resolve-spec.ts`
- *     抛 `HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)")`
- *     且**不带** `code`,于是 `http/send.ts` 的 `httpErrorCode(404)` 盖上按状态码派生的粗码
- *     `not_found.resource`,真子码**只活在人话里**。SDK `classifyApiError` 把 body 的 `error`
- *     原样搬进 `APIError.message`(scrub 只动 Bearer/presigned),所以壳收到的是
- *     `{status:404, errorCode:'not_found.resource', message:'…(resume_at.unknown_event)'}`。
- *     旧判据 false ⇒ #166 去锚重发整臂跳过 ⇒ 会话每条消息秒死 404、永久死锁(1.0.93 现网案)。
- *
- * ## 放宽的论证(engineErrorCodes `RESUME_AT_ERROR_CODE_PREFIX` 头注要求「放宽须论证」)
- * 本腿放宽的是**载体**(码位 → 码位∪人话),不是**族**:
- *   ① 三重合取收敛误触面:`status === 404`(引擎真应答了,不是网络/内部错)+ 人话里出现
- *      **同一个族前缀**字面 + 调用点自己的 `req.resumeAt !== undefined`(seamQuery #166 臂)
- *      —— 没带锚的提交压根进不来,与「404 里恰好出现 `resume_at.` 字样」撞车要三件同时成立。
- *   ② 族边界一字未松,而且文本腿收成**闭集**:只认 `RESUME_AT_TEXT_COMPAT` 里那两对
- *      「状态 × 括号收尾子码」——`404 × (resume_at.unknown_event)` 与
- *      `422 × (resume_at.no_session)`,正是 `boot/resolve-spec.ts` 两处**不带 `code`** 的 throw。
- *      `rewind_snapshot.` / `rewind_files_to.` 邻族不入内(邻族的自动重发安全性没论证过);
- *      开集形与裸子串形都已被异源复审证伪(token 边界 + 回显注入两条,论证见
- *      {@link RESUME_AT_TEXT_COMPAT})。带 code 的那一路(core prepare-throw 经 `resumeAtHttpStatus`
- *      落 4xx)`errorCode` 原样透传,早被 ① 接住,压根不经过这里。
- *   ③ 422 那一支不是「顺手放宽」:它与 404 支同为预检腿的 codeless throw,处置也同款 —— 去锚重发在
- *      `no_session` 上不但安全、而且**正是正解**(没有可分支的 session,新起一轮本来就是对的)。
- *      原形把它留在门外、负控还把「422 恒 false」钉成期望值 —— 那不是负控,是把残余固化成契约。
- *   ④ 误触的代价上界很低而漏判的代价是死锁:误命中最多多发一次**去锚的**同一条提交(pre-stream
- *      零副作用,与 draining 同一铁律边界)+ 一行人话;漏判 = 会话再也发不出消息。
- *   ⑤ 刻意**不**加「粗码必须等于 `request.unprocessable` / `not_found.resource`」这层收窄:那张
- *      状态码→粗码表是 server `http/send.ts` 的实现细节(会随版本增删),把判据押在它上面等于给自己
- *      种一颗静默失效的雷;判别力已由 ② 的闭集承担。
- *
- * 🔴 根治在发端、且**已经落地**:server 给那四条拒绝子码补上了结构化 `code` 参,新 worker 一律走
- * 机读腿 ①。本腿因此是**对已发布旧 server 的过渡垫片**(1.0.93 现网用户跑的正是那些),不是长期形;
- * 等最低 server 版本推过去之后可以整条退役。
- *
- * 🔴 只影响本函数的判定,`RESUME_AT_ERROR_CODE_PREFIX` 常量与它的另一个消费点
- * `isRewindFamilyCode`(rewind 可自解族的**码**判别)一字未动。
- */
 export function isResumeAtRejection(err) {
     const e = err;
     if (typeof e?.errorCode === 'string' && e.errorCode.startsWith(RESUME_AT_ERROR_CODE_PREFIX))
         return true;
-    // 文本兼容腿:只认闭集里那两对「状态 × 括号收尾子码」(见 {@link RESUME_AT_TEXT_COMPAT})。
     const marker = RESUME_AT_TEXT_COMPAT.find((c) => c.status === e?.status)?.marker;
     if (marker === undefined)
         return false;
-    // 两个人话载体**各自独立判**(异源复审 [medium] 真病修:原形取「第一个非空」,而 SDK
-    // `classifyApiError` 的 `message` 恒非空(缺席时回落 `HTTP <status>`)⇒ `errorMessage` 那条腿在
-    // 「泛化 message + 细节在 errorMessage」的包装形下恒不可达 = 死腿)。
-    //   · `message` = SDK `APIError` 的正身(壳 seamQuery catch 到的就是它,生产真形);
-    //   · `errorMessage` = 同一句话在 wire 体 / `TaskResult` 上的键位(轮询腿把体直接当错误对象抛时的形)。
-    // 结构读不 instanceof:三端共用面,desktop IPC / web 跨 bundle 的同名错误是 plain object。
-    // 🔴 `endsWith` 而不是 `includes`(异源复审第五轮 [medium] 真病修):server 自己那两句**以码收尾**
-    //    (亲验 7.42.0–7.50.0 七份已发布产物,码后紧跟的就是字符串字面量的结束引号);而回显形里用户内容
-    //    后面必然还跟着 ` → guidance`。只认串尾 ⇒ 用户就算把整串 `(resume_at.no_session)` 连括号一起
-    //    写进权限名,它在错误文本里也永远不在串尾,注入这条路彻底堵死。
     return [e?.message, e?.errorMessage].some((t) => typeof t === 'string' && t.endsWith(marker));
 }
-/**
- * 第 `attempt`(0-based)次 draining 重试前的等待:`err.retryAfterMs`(SDK 若带)封顶优先
- * (上限 15s = server drain 门现值,防把一个 turn park 到分钟级),缺席走退避梯
- * (默认 1s/2s/4s = 壳 S4-P0 实测值;超出梯长取末档)。`opts.ladder` = 端的测试钩子注入口
- * (壳 `setDrainingBackoffForTest` 经此透传)。纯函数,零模块状态(singleton 门口径)。
- */
 export function drainingRetryDelayMs(err, attempt, opts) {
     const ra = err?.retryAfterMs;
     if (typeof ra === 'number' && Number.isFinite(ra) && ra >= 0) {
@@ -197,13 +57,6 @@ export function drainingRetryDelayMs(err, attempt, opts) {
     const ladder = opts?.ladder && opts.ladder.length > 0 ? opts.ladder : [1_000, 2_000, 4_000];
     return ladder[Math.min(attempt, ladder.length - 1)] ?? 1_000;
 }
-/**
- * 从一个被 catch 的错误判定「场景不在指派列表」并提取结构化 detail。
- * duck-typed(不 instanceof — bundle 下跨包类标识可能双实例):`status===400 &&
- * errorCode===SCENARIO_NOT_ALLOWED_ERROR_CODE` 即命中;allowlist 缺席/非数组/畸形项 → 逐项
- * 防御过滤成空数组(兜底文案契约归端)。非该 code 的 400 / 其他错误 → null(绝不误吃普通 400)。
- * 🔴 键位([2055] 死键纪律):只认 `errorCode`,退役 `code` 键不做兼容(clean-cut)。
- */
 export function scenarioDenyFromError(err) {
     if (typeof err !== 'object' || err === null)
         return null;
@@ -215,27 +68,6 @@ export function scenarioDenyFromError(err) {
         : [];
     return { allowlist };
 }
-/**
- * 被 catch 的错误 → resume **时间性拒绝**读数;不是那两个码 ⇒ `null`(绝不误吃这一族里别的 409)。
- *
- * 🔴 **判据只有 `errorCode`,不看 HTTP 数字**:与 `classifySubagentResumeFailure`(同包
- *    `subagent/engineSubagentResume.ts`)的既有口径同律(`resume.*` 那一族成员全是 409,按数字分支
- *    等于把几种不同处置压成一种);而本口的
- *    处置是**告诉人等一会儿**——非破坏性,不需要 {@link scenarioDenyFromError} 那种「码 ∧ 状态」的
- *    合取闸(那一条守的是别让一个只是**引用**了该码的响应驱动一次真动作)。
- * 🔴 **结构读不 `instanceof`**:见 {@link ResumeRetryLaterDetail} 顶注(三端注入面 / 跨 bundle 同名类
- *    是两个实例)。键位只认 `errorCode`([2055] 死键纪律,退役 `code` 槽不做兼容)。
- * 🔴 **本口只报事实,处置位是 {@link ResumeRetryLaterDetail.waitable}**:命中本族 **≠** 一定可等 ——
- *    `resume.preflight_rejected` 有一条 `terminal` 臂(token 不可再赎)而判别位只在 message 散文里。
- *    「等一会儿有没有用」的判断收在 `waitable` 这一位上(全包单一判断点),名字里的 RetryLater 是
- *    上游 SDK 的类名锚,**不是**本口对每一次命中的断言。
- * 🔴 **`retryAfterSec` 的窄读域 = server 的铸键域**(整数 ∧ ≥1),不更宽也不更窄:
- *      · server 铸键逐字是「ms → 秒**向上取整**、**下限 1**」⇒ 真供给里不存在 0 / 负数 / 小数;
- *      · 放行 0 就是对消费端说「立刻重试」,而 resume 是 AT-MOST-ONCE 的有副作用动作
- *        (叫醒 = 真跑一轮)—— 一个 0 会把「等一会儿」变成热循环;
- *      · 放行小数会让端渲出「等 0.4 秒」这种上游从未说过的量。
- *    坏值一律**降缺席**(不是降 0、不是取绝对值):没读到窗与读到一个假窗,前者诚实。
- */
 export function resumeRetryLaterFromError(err) {
     if (typeof err !== 'object' || err === null)
         return null;
@@ -244,12 +76,9 @@ export function resumeRetryLaterFromError(err) {
     if (typeof code !== 'string' || !RESUME_RETRY_LATER_CODES.includes(code))
         return null;
     const sec = e.retryAfterSec;
-    // 局部名刻意不叫 `window`:本包出浏览器包(portability 门真跑 esbuild --platform=browser),
-    // 一个遮蔽宿主全局的同名局部变量在阅读期就是噪音。
     const windowSec = typeof sec === 'number' && Number.isInteger(sec) && sec >= 1 ? sec : undefined;
     return {
         code,
-        // 见 {@link ResumeRetryLaterDetail.waitable}:治理窗满这一码本身即证据;预检拒只认「server 真给了窗」。
         waitable: code === RESUME_USAGE_WINDOW_EXHAUSTED || windowSec !== undefined,
         ...(windowSec !== undefined ? { retryAfterSec: windowSec } : {}),
     };

package/dist/wireRefusalCopy.d.ts

@@ -1,44 +1,16 @@
-/**
- * wireRefusalCopy — 两条 wire 拒绝的三端共用读口与人话面(0.73.1)。
- *
- * ① `POST /v1/runs/:id/cancel` 的 **409 是两个码、两种相反的处置**:
- *    · `conflict.approval_settled` —— park 臂:取消打在一条停驻的 run 上,而那扇审批门被并发的决断 / 回收抢先结算了。
- *      处置 = **重读决议结果**(别人已经替这条 run 做了决定),不是盲目重试。
- *    · `conflict.run_not_running` —— running 臂:取消旗反复挂不上(行在 running 与 park 之间来回跳,有界重分类用尽)。
- *      处置 = **直接重试**。
- *    只看 409 状态码会把两者合成一句,其中一半人被指错路。码缺席 / 认不出 ⇒ `unrecognized`,不猜。
- *
- * ② 提交面 **429 `usage.window_exhausted`**:部署级用量窗耗尽,**可等待**的拒绝(窗滑动后原样重发即可)。
- *    `retryAfterSec` 在场就说等多久,缺席就不编数。它与续跑面的 `resume.usage_window_exhausted` 是两个码、两句话 ——
- *    后者说的是一条已停驻的 run 续跑时撞窗(决定没被消费、token 仍可赎),套到提交面上每一个字都不对。
- *
- * 读口只认 `errorCode`(退役的 `code` 槽不做兼容),永不抛;措辞单源在这里,端只拼接不另写。
- */
 import { USAGE_WINDOW_EXHAUSTED } from './engineErrorCodes.js';
-/** cancel 的 409 · park 臂:审批门已被并发结算。 */
 export declare const CONFLICT_APPROVAL_SETTLED = "conflict.approval_settled";
-/** cancel 的 409 · running 臂:取消旗反复挂不上。 */
 export declare const CONFLICT_RUN_NOT_RUNNING = "conflict.run_not_running";
 export type CancelConflictKind = 'approval_settled' | 'run_not_running' | 'unrecognized';
-/** `code` 在场 = 引擎给的原码(`unrecognized` 时也原样带出,便于留痕);缺席 = 这条 409 没带机器码。 */
 export interface CancelConflictDetail {
     kind: CancelConflictKind;
     code?: string;
 }
-/** cancel 抛出的错误 → 409 三形;不是 409(状态不是 409 且不是 sdk 的 `ConflictError`)/ 非对象 ⇒ `null`。 */
 export declare function cancelConflictFromError(err: unknown): CancelConflictDetail | null;
-/** 三句人话(唯一措辞真源)。🔴 两种处置不许说反:settled 句不提重试取消,not_running 句不说已被决定。 */
 export declare function cancelConflictContent(detail: Pick<CancelConflictDetail, 'kind'>): string;
-/** 提交面用量窗耗尽的读数。`retryAfterSec` 缺席 = 引擎没说要等多久(绝不编一个数)。 */
 export interface UsageWindowExhaustedDetail {
     code: typeof USAGE_WINDOW_EXHAUSTED;
     retryAfterSec?: number;
 }
-/**
- * 只认 **HTTP 429 载体**上的 `errorCode === "usage.window_exhausted"`;同码落在终态 run 记录上的形(跑到 turn 边界才被停下)**不在本读面**
- * (那一形工作可能已经发生,处置相反 —— 先看结果再决定怎么续)。
- * 等待量两个来源:回体 `retryAfterSec`(秒)优先;缺席时读 `retryAfterMs`(sdk 从 `Retry-After` 头喂入)上取整换算。
- */
 export declare function usageWindowExhaustedFromError(err: unknown): UsageWindowExhaustedDetail | null;
-/** 一句人话(唯一措辞真源):有数带数,无数不编数;说清这是部署的用量窗、不是请求写错了。 */
 export declare function usageWindowExhaustedContent(detail: UsageWindowExhaustedDetail): string;

package/dist/wireRefusalCopy.js

@@ -1,29 +1,10 @@
-/**
- * wireRefusalCopy — 两条 wire 拒绝的三端共用读口与人话面(0.73.1)。
- *
- * ① `POST /v1/runs/:id/cancel` 的 **409 是两个码、两种相反的处置**:
- *    · `conflict.approval_settled` —— park 臂:取消打在一条停驻的 run 上,而那扇审批门被并发的决断 / 回收抢先结算了。
- *      处置 = **重读决议结果**(别人已经替这条 run 做了决定),不是盲目重试。
- *    · `conflict.run_not_running` —— running 臂:取消旗反复挂不上(行在 running 与 park 之间来回跳,有界重分类用尽)。
- *      处置 = **直接重试**。
- *    只看 409 状态码会把两者合成一句,其中一半人被指错路。码缺席 / 认不出 ⇒ `unrecognized`,不猜。
- *
- * ② 提交面 **429 `usage.window_exhausted`**:部署级用量窗耗尽,**可等待**的拒绝(窗滑动后原样重发即可)。
- *    `retryAfterSec` 在场就说等多久,缺席就不编数。它与续跑面的 `resume.usage_window_exhausted` 是两个码、两句话 ——
- *    后者说的是一条已停驻的 run 续跑时撞窗(决定没被消费、token 仍可赎),套到提交面上每一个字都不对。
- *
- * 读口只认 `errorCode`(退役的 `code` 槽不做兼容),永不抛;措辞单源在这里,端只拼接不另写。
- */
 import { USAGE_WINDOW_EXHAUSTED } from './engineErrorCodes.js';
-/** cancel 的 409 · park 臂:审批门已被并发结算。 */
 export const CONFLICT_APPROVAL_SETTLED = 'conflict.approval_settled';
-/** cancel 的 409 · running 臂:取消旗反复挂不上。 */
 export const CONFLICT_RUN_NOT_RUNNING = 'conflict.run_not_running';
 function readStringField(o, key) {
     const v = o[key];
     return typeof v === 'string' && v !== '' ? v : undefined;
 }
-/** cancel 抛出的错误 → 409 三形;不是 409(状态不是 409 且不是 sdk 的 `ConflictError`)/ 非对象 ⇒ `null`。 */
 export function cancelConflictFromError(err) {
     try {
         if (err === null || typeof err !== 'object')
@@ -44,7 +25,6 @@ export function cancelConflictFromError(err) {
         return null;
     }
 }
-/** 三句人话(唯一措辞真源)。🔴 两种处置不许说反:settled 句不提重试取消,not_running 句不说已被决定。 */
 export function cancelConflictContent(detail) {
     switch (detail.kind) {
         case 'approval_settled':
@@ -61,11 +41,6 @@ export function cancelConflictContent(detail) {
 function nonNegativeFinite(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0;
 }
-/**
- * 只认 **HTTP 429 载体**上的 `errorCode === "usage.window_exhausted"`;同码落在终态 run 记录上的形(跑到 turn 边界才被停下)**不在本读面**
- * (那一形工作可能已经发生,处置相反 —— 先看结果再决定怎么续)。
- * 等待量两个来源:回体 `retryAfterSec`(秒)优先;缺席时读 `retryAfterMs`(sdk 从 `Retry-After` 头喂入)上取整换算。
- */
 export function usageWindowExhaustedFromError(err) {
     try {
         if (err === null || typeof err !== 'object')
@@ -73,8 +48,6 @@ export function usageWindowExhaustedFromError(err) {
         const o = err;
         if (o.errorCode !== USAGE_WINDOW_EXHAUSTED)
             return null;
-        // 🔴 只认 **HTTP 429 载体**(状态 429,或 sdk 的 UsageWindowExhaustedError / RateLimitedError 名):同一个码也会落在终态 run 记录上
-        //    (跑到 turn 边界才被用量窗停下,同样带 retryAfterMs)—— 那不是「提交未受理」,套这句话会把已经发生的工作说成没做。
         const rawStatus = o.status ?? o.statusCode;
         const is429 = rawStatus === 429 || (rawStatus === undefined && (o.name === 'UsageWindowExhaustedError' || o.name === 'RateLimitedError'));
         if (!is429)
@@ -101,7 +74,6 @@ function humanWait(sec) {
     const mm = m % 60;
     return mm === 0 ? `${h} h` : `${h} h ${mm} min`;
 }
-/** 一句人话(唯一措辞真源):有数带数,无数不编数;说清这是部署的用量窗、不是请求写错了。 */
 export function usageWindowExhaustedContent(detail) {
     const head = "The deployment's usage window is exhausted, so the engine did not accept this request · Nothing is wrong with the request itself";
     return detail.retryAfterSec !== undefined