@sema-agent/sdk 23.1.0 → 25.0.0

package/dist/errors.d.ts

@@ -12,6 +12,7 @@ import type { ApprovalStaleCurrentPending, PendingGateMaterial } from "./types.j
 export declare class APIError extends Error {
     readonly status: number;
     readonly errorCode: string | undefined;
+    name: string;
     /**
      * 🔴 **错误体上 `error` / `errorCode` 之外的全部键,原样**(K-09 销账,SDK 11.1.0)。`{}` = 这条体上
      * 没有附加键(**不是** `undefined`:「没有附加材料」只该有一种读法)。
@@ -27,7 +28,7 @@ export declare class APIError extends Error {
      *
      * ⚠️ 既有的具名位({@link retriable}、`retryAfterMs`、各子类的结构化字段)是**先于本格存在**的镜像,
      * 值来自同一张体 —— 它们不因本格而改变,新键也不再因此长出第 N 个属性。例外只由票面裁定开出,开了也仍同在本格:
-     * 现有一例 = K-19 `ParkedResumeStartupError.startupCause`(wire 键 `cause`;跨仓请托 [8537] / 认领 [8539] 点名要一个具型的读位;23.0.0 起是引擎五词闭集
+     * 现有一例 = K-19 `ParkedResumeStartupError.startupCause`(wire 键 `cause`;跨仓请托 [8537] / 认领 [8539] 点名要一个具型的读位;23.0.0 起是引擎的成因闭集(core 7.52.0 起六词)
      * `ResumeStartupCause`;值仍原样在 `extra.cause`)。
      * ⚠️ **未清洗**:`message` 是给人看/进日志的那一半,过 `scrub()`;本格是给机器分支的那一半,原样透传
      * (是 server 契约里的机读键,不是自由文本)。要把它打进日志的调用方自己负责清洗。
@@ -56,6 +57,11 @@ export declare class APIError extends Error {
      *  🔴 **server ≥7.124.0:这一码的体多两只版本键** `writerVersion` / `readerVersion`(每个铸点同律 —— core 原码镜像与 server 自铸的两只读法记号拒都带;形见
      *  {@link CheckpointUnsupportedVersionExtra},值经 {@link extra} 到达)。「停驻行的格式比本引擎新」只有这一个来源:`writerVersion` 比 `readerVersion` 新 ⇒ 回到那一版(或更新的一版)去决,不是在本引擎上重试。
      *
+     *  🔴 **server ≥7.132.0 一只写点、一条律**:三类续跑拒(server 重放存量体前的拒、准入策略折叠 `resume_blocked_by_policy`、引擎拒的续跑)上 `retriable: true` 在场 ⇔ **有一张待批卡仍在等、
+     *  run 行留 `suspended`**(server `resumeRefusalWithCard` 一处追加,排在体尾)。由此两处订正:① `resume_blocked_by_policy` 自 7.132.0 起**同带** `retriable: true`(卡同样仍 pending;此前不带);
+     *  ② **终态 run 的 `POST /v1/runs/:id/steer` 在铸唤醒卡之前拒的路径不带它**(没有卡)—— `checkpoint.unsupported_version` 的 allow 读法 / 模式词读法两臂在那条路径上此前自述 `true`,是错的。
+     *  同批:引擎拒的续跑体多三只判别位 `blockedBy` / `field` / `reason`(加性,见 {@link ResumeRefusalExtra});体键序变(`taskId` 移到 `errorCode` 之后、`retriable` 在体尾,键集不变)。
+     *
      *  🔴 `undefined` means "the server did not say", NOT "not retriable" — it is a CONDITIONAL field server-side
      *  (absent ⇒ key omitted), so reading its absence as an explicit `false` over-reads the wire.
      *
@@ -76,6 +82,7 @@ export declare class APIError extends Error {
  *  🔴 [2400] CB-3(SDK 4.2.0):状态兜底**只剩 401**。无码 503 已改归 {@link ServiceStateError} —— 那条臂
  *  上真正可达的是中间层的无码 503(「上游暂时不可用」),把它铸成本类等于把「稍后重试」说成「你没权限」。 */
 export declare class AuthError extends APIError {
+    name: string;
 }
 /** `request.*` 前缀族 —— **请求本身有问题,改请求即可**(400 为主,另有 413 / 422 / 4xx 兜底粗码)。
  *  一律 NOT retryable verbatim:同一个 body 重发永远同一个结果。子类 {@link PayloadTooLargeError} 专指
@@ -141,12 +148,14 @@ export declare class AuthError extends APIError {
  *  (体里同时还有别的毛病而先撞上的是那一个时,`message` 说那个毛病、`field` 照带)。要「去掉这只键重发」的调用方按**码 + `err.extra.field`** 判,**别解析句子**
  *  (三口的句子在 7.119.0 收成逐字同一句,≤7.118.x 各说各的)。体里没有这只键的坏体**没有** `field`。本类不为它开具名属性(同上:开形一格)。 */
 export declare class BadRequestError extends APIError {
+    name: string;
 }
 /** [2420] `attachment.*` 族(上传面拒收):`attachment.too_large`(413)携 {@link maxBytes},
  *  `attachment.mime_not_allowed`(415)携 {@link allowed}——两键是用户能改正的唯一量(压到多大/换什么类型)。 */
 export declare class AttachmentRejectedError extends APIError {
     readonly maxBytes?: number | undefined;
     readonly allowed?: string[] | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, maxBytes?: number | undefined, allowed?: string[] | undefined);
 }
 /** `not_found.*` 前缀族 —— 资源不存在。⚠️ 也包含**属主门**:server 对非属主一律回 404 同码同文
@@ -170,12 +179,14 @@ export declare class AttachmentRejectedError extends APIError {
  *  反枚举不变式),永远走不到这两个码 —— 所以它们泄漏的全部信息是「**你自己**这条 run 的状态」,
  *  而那本来就是 `runs.get(taskId)` 直答的东西。 */
 export declare class NotFoundError extends APIError {
+    name: string;
 }
 /** `limit.*` 前缀族 —— 配额 / 限流 / 保留窗(429 限流与成本配额、416 续读点过保留窗)。
  *  `retryAfterMs` 来自 `Retry-After` 头(由 transport 喂入)。
  *  ⚠️ 429 那两个成员码({@link RateLimitedError} 起)走更具体的子类,见下。 */
 export declare class LimitExceededError extends APIError {
     readonly retryAfterMs?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, retryAfterMs?: number | undefined);
 }
 /** `capability.*` 前缀族 —— **本部署没接这个面**(501)。重试无意义、开开关也没用:要么换部署形态
@@ -191,6 +202,7 @@ export declare class LimitExceededError extends APIError {
  *  `capability.snapshot_store_required`(history blob GET)· `capability.policy_purge_required`(同步整族,嵌入方形)。**唯一登记例外**:`a2aServe` 的两条路由不可用时答 404(反指纹)。
  *  ⚠️ **按状态码判「没权限 / 不存在 / 不可用」的分支要改按 `errorCode`**:403 可能是「不在名单」也可能(≤7.115.x)是名单空;404 可能是「真不存在」也可能(≤7.115.x)是「这台没挂这一族」。 */
 export declare class CapabilityUnavailableError extends APIError {
+    name: string;
 }
 /** `feature.*` 前缀族 —— **面存在,但开关是关的**(501;`feature.metrics_disabled` 是 404)。
  *  处置:提示管理员打开对应开关(`RESOURCE_SUSPEND` / 三个 LIVE HITL 开关 / `STREAM_APPROVAL_ENABLED` /
@@ -201,6 +213,7 @@ export declare class CapabilityUnavailableError extends APIError {
  *  server ≥7.116.0 新增两员(都是 501,开旋钮即可):`feature.memory_consolidation_disabled`(记忆整理两口,`MEMORY_CONSOLIDATION_DRIVER` 关或出厂缺省派生关 ——
  *  没配便宜模型;此前 404)· `feature.config_catalog_disabled`(`CONFIG_CATALOG_ENABLED=false` 时 `GET /v1/config/catalog`;此前 404)。 */
 export declare class FeatureDisabledError extends APIError {
+    name: string;
 }
 /** `internal.*` 前缀族 —— 服务端自己出错(500 / 502)。细节不上 wire。
  *  部分成员**明确可重试**(`internal.cancel_not_terminalized` = 重试 cancel;
@@ -210,6 +223,7 @@ export declare class FeatureDisabledError extends APIError {
  *  (会话规则店读不出)**不在本族**(不以 `internal.` 开头)⇒ 落带码的 {@link APIError},同样不自动重试;按 `.errorCode` 分支,
  *  `error` 是引擎 / 店的原句(给运维看,不含盘上路径)。 */
 export declare class InternalServerError extends APIError {
+    name: string;
 }
 /** `state.*` 前缀族 —— 服务端**当前状态**不接受这个请求(503)。开集,下面是本包逐码注过的成员(附录 A 为准;server ≥7.119.0 新增 `state.scenario_assignment_unknown`):
  *   · `state.model_roster_pending`(roster 还没拉到)/ `state.no_sandbox_base`(没有可用的 sandbox-base)
@@ -254,6 +268,7 @@ export declare class InternalServerError extends APIError {
  *  {@link import("./types.js").CenterWiringCapability.failMode} / `leaseHealth`。 */
 export declare class ServiceStateError extends APIError {
     readonly retryAfterMs?: number | undefined;
+    name: string;
     /**
      * 等待提示(**毫秒**,单位与 {@link LimitExceededError.retryAfterMs} 同口径)。缺席 = server 这一支
      * **没给**窗(如 `state.sse_connection_cap` 那些「换通道」成员),不是「可以立刻重打」。
@@ -282,6 +297,7 @@ export declare class ServiceStateError extends APIError {
 export declare class WorkspaceFileTooLargeError extends APIError {
     readonly sizeBytes: number;
     readonly limit: number;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, sizeBytes: number, limit: number);
 }
 /** 429 — per-principal rate limit. `retryAfterMs` from `Retry-After` (the SDK honors it on retry). */
@@ -301,6 +317,7 @@ export declare class WorkspaceFileTooLargeError extends APIError {
  *  codeless 503 arm to {@link ServiceStateError}; the status tariff now falls back to AuthError for 401 ONLY.) */
 export declare class DrainingError extends APIError {
     readonly retryAfterMs?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, retryAfterMs?: number | undefined);
 }
 /** 429 —— per-principal 限流。`retryAfterMs` 来自 `Retry-After`(SDK 重试时遵守它)。
@@ -323,6 +340,7 @@ export declare class RateLimitedError extends LimitExceededError {
     readonly usedMicroUsd?: number | undefined;
     /** `limit.cost_quota_exceeded` only —— 本窗口的上限(micro-USD)。缺席同上。 */
     readonly limitMicroUsd?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, retryAfterMs?: number, 
     /** `limit.cost_quota_exceeded` only —— 本窗口已花费(micro-USD)。缺席 = 服务端没给/给了坏值。 */
     usedMicroUsd?: number | undefined, 
@@ -353,6 +371,7 @@ export interface QuotaExhaustedDetail {
  *  usage window=引擎部署级 token 治理窗(design/166,`USAGE_WINDOWS`)。两类同为 429 但处置来源不同。 */
 export declare class QuotaExhaustedError extends RateLimitedError {
     readonly detail: QuotaExhaustedDetail;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, retryAfterMs: number | undefined, detail: QuotaExhaustedDetail);
 }
 /** 429 `errorCode:"usage.window_exhausted"` — 部署级 token 治理窗耗尽(server ≥6.1.0 提交面
@@ -364,6 +383,7 @@ export declare class QuotaExhaustedError extends RateLimitedError {
 export declare class UsageWindowExhaustedError extends RateLimitedError {
     /** 响应体的 retryAfterSec(秒,上取整;与 Retry-After 头同源)。缺席=服务端没给。 */
     readonly retryAfterSec?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, retryAfterMs: number | undefined, 
     /** 响应体的 retryAfterSec(秒,上取整;与 Retry-After 头同源)。缺席=服务端没给。 */
     retryAfterSec?: number | undefined);
@@ -380,6 +400,7 @@ export declare class UsageWindowExhaustedError extends RateLimitedError {
 export declare class MemoryAdmissionError extends APIError {
     /** 仅 transient 形(admission_required)可能在场;terminal 形恒缺席(等待提示在终局拒上是方向性谎言)。 */
     readonly retryAfterSec?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** 仅 transient 形(admission_required)可能在场;terminal 形恒缺席(等待提示在终局拒上是方向性谎言)。 */
     retryAfterSec?: number | undefined);
@@ -392,12 +413,14 @@ export declare class MemoryAdmissionError extends APIError {
 export declare class ScenarioNotAllowedError extends APIError {
     /** The principal's allowed scenario names (may be empty on an older service / defensive drop). */
     readonly allowlist: string[];
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** The principal's allowed scenario names (may be empty on an older service / defensive drop). */
     allowlist: string[]);
 }
 /** errorCode `budget.precall` / `budget.exceeded` — per-task or per-principal cost ceiling. NOT retryable. */
 export declare class BudgetExceededError extends APIError {
+    name: string;
 }
 /** 409 — session already has an active run, or an idempotency conflict / session CAS conflict.
  *
@@ -436,6 +459,7 @@ export declare class ConflictError extends APIError {
      *  resume 入口(gateKind 分路),cancel 是保底。自愈臂判别:只对 409 重试,2xx 已接受的提交绝不 cancel([2265]/[2267])。 */
     readonly activeTaskStatus?: string | undefined;
     readonly pendingGate?: PendingGateMaterial | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, activeTaskId?: string | undefined, 
     /** [2255]① server ≥3.21:conflict.session_active_run 携带的真出路材料(ADDITIVE / tolerate-absent)。
      *  running ⇒ steer/cancel 两条路;suspended/needs_review ⇒ pendingGate.decidePath 是那一个正确的
@@ -488,6 +512,7 @@ export declare class DeviceError extends ConflictError {
     /** `device.rebind_rev_conflict` 的当前 rev(顶层键)—— 壳一跳重定位:直接拿它重发换绑。
      *  其余码上缺席(**守卫式**:非有限数丢弃 ⇒ 缺席,绝不把垃圾当前态)。 */
     readonly currentRev?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** `device.rebind_rev_conflict` 的当前 rev(顶层键)—— 壳一跳重定位:直接拿它重发换绑。
      *  其余码上缺席(**守卫式**:非有限数丢弃 ⇒ 缺席,绝不把垃圾当前态)。 */
@@ -508,6 +533,7 @@ export declare class SyncConflictError extends ConflictError {
         relation: "fork" | "stale";
         [k: string]: unknown;
     };
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** The §7 `fork`/`stale` relation with the exclusive entry sets (untyped at the JSON boundary). */
     relation: {
@@ -515,9 +541,15 @@ export declare class SyncConflictError extends ConflictError {
         [k: string]: unknown;
     });
 }
-/** design/80 D-1 — the checkpoint you tried to decide is already TERMINAL (someone else resolved it, it was
- *  GC'd past its abandonment-TTL, or its SLA deadline fired a resolve-deny). DISTINCT from a binding mismatch
- *  and from session-CAS 409. Client action: this pending is gone → REFETCH the inbox; do not retry the decide. */
+/** 409 `approval_stale` — **one code, two causes**, told apart by the body:
+ *  - **with {@link ApprovalStaleError.terminal}** = the checkpoint you tried to decide is already TERMINAL (someone else resolved it, it was
+ *    GC'd past its abandonment-TTL, or its SLA deadline fired a resolve-deny). That pending is gone → REFETCH the inbox; do not retry the decide.
+ *  - **no `terminal` and {@link ApprovalStaleError.currentPending} present** = the binding you echoed is STALE (the `boundCallId` no longer matches the row
+ *    that is pending now — the card was superseded between your read and your decide). The pending row is still alive: use `currentPending` to
+ *    re-point (one hop) and decide again; no full inbox re-pull needed.
+ *  - Neither key = the server could not name a current pending (no pending, a non-tool gate, or the row read failed): REFETCH.
+ *  Only a wrong `boundInputHash` (with the right `boundCallId`) is NOT this error: it lands in core's bare 409 `approval_binding_mismatch`
+ *  ({@link ApprovalBindingMismatchError}). DISTINCT from the session-CAS 409. */
 export declare class ApprovalStaleError extends APIError {
     readonly terminal?: "resolved" | "expired_abort" | "expired_sla" | undefined;
     /** S-02(server ≥7.52)—— 本会话**当前** pending 的三件 D-1 坐标(additive 指路键):壳拿它一跳
@@ -530,6 +562,7 @@ export declare class ApprovalStaleError extends APIError {
      *  (S-57 前它穿透成 `approval_binding_mismatch`+`field:"boundCallId"`,无指路;那条臂现只剩
      *  server 比对与 core CAS 之间的竞态窗)。 */
     readonly currentPending?: ApprovalStaleCurrentPending | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, terminal?: "resolved" | "expired_abort" | "expired_sla" | undefined, 
     /** S-02(server ≥7.52)—— 本会话**当前** pending 的三件 D-1 坐标(additive 指路键):壳拿它一跳
      *  重定位再 decide,免整队重拉。缺席=无 pending/非工具门/行读失败(server F 类留痕臂)或老 server。
@@ -553,6 +586,7 @@ export declare class ApprovalStaleError extends APIError {
  *  对着 ≤7.123.x 的 server,那一席仍借本码到达:{@link field} 按闭集读,不认识的词读作缺席,原值在 `err.extra.field`。`retriable: true` 形不变(卡仍 pending、run 行重新 park)。 */
 export declare class ApprovalBindingMismatchError extends APIError {
     readonly field?: ApprovalBindingField | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, field?: ApprovalBindingField | undefined);
 }
 /** design/80 D-1 (core 1.101.0) — a concurrent resolve/reopen advanced the checkpoint's revision inside the
@@ -560,6 +594,7 @@ export declare class ApprovalBindingMismatchError extends APIError {
  *  do NOT treat as ApprovalStaleError. Client action: REFETCH the PendingCheckpoint + re-present, then decide
  *  again (retryable). */
 export declare class ApprovalConcurrentlyReopenedError extends APIError {
+    name: string;
 }
 /** `steering.*` 族的基类(SDK 1.1.0 —— 从**逐码枚举**改成**前缀分派**,与 `stop.*` / `decide.*` 同形)。
  *
@@ -572,16 +607,19 @@ export declare class ApprovalConcurrentlyReopenedError extends APIError {
  *  这是有意的 —— 「409」是传输层的巧合,「steer 目标有歧义」才是消费端要分支的东西;按 [clean-cut] 硬切,
  *  不留双继承之类的兼容层。整族一把接:`catch (e instanceof SteeringError)`。 */
 export declare class SteeringError extends APIError {
+    name: string;
 }
 /** design/80 D-A — you steered a run that is NOT running (it is durable-`suspended`, terminal, or unknown).
  *  Steer is at-most-once and NOT queued. Client action: surface "task isn't running"; if suspended, the path
  *  forward is the approval decide, not a steer. */
 export declare class SteeringNotRunningError extends SteeringError {
+    name: string;
 }
 /** design/80 D-A — the steer text carried a control-plane escape (e.g. `</system-reminder>`) and core rejected
  *  it (runtask.ts:489). Client action: it's an injection attempt or a malformed steer — surface it; don't retry
  *  verbatim. (The BFF also fences steer text defensively; this is core's authoritative reject.) */
 export declare class SteeringInvalidContentError extends SteeringError {
+    name: string;
 }
 /** `steering.ambiguous_target`(子代 steer/resume 面,server `http/routes/runs.ts`)/
  *  `steering.ambiguous_label`(workflow agent steer 面,`http/routes/workflows.ts`)—— **这一个 run 里有
@@ -589,12 +627,14 @@ export declare class SteeringInvalidContentError extends SteeringError {
  *  Client action:两个码同一个处置 —— **换一个唯一的定位方式**(子代面用 `parentToolCallId`;workflow 面
  *  用更具体的 label/句柄),原样重试永远同一个结果。`.errorCode` 区分是哪条轴上歧义。 */
 export declare class SteeringAmbiguousTargetError extends SteeringError {
+    name: string;
 }
 /** `steering.still_running` —— 你对一个**还在飞**的子代调了 `resume`(revive 只在 settle 之后合法;
  *  也可能是上一次 resume 还没落地)。409。
  *  Client action:要么改调 steer(给在跑的它递话),要么等它 settle 再 resume。**与
  *  {@link SteeringNotRunningError} 正好互为反面**,两个码塌在一起会让 UI 说反话。 */
 export declare class SteeringStillRunningError extends SteeringError {
+    name: string;
 }
 /** `steering.queue_full`(server ≥7.3.0 / core 5.14.0 #147)—— 这条 run **确实**挂着,但它 checkpoint 上
  *  已 park 的转向队列**满了**。队列是有界且 **fail-loud** 的:引擎绝不驱逐一条已被接受的指令来腾位子
@@ -603,6 +643,7 @@ export declare class SteeringStillRunningError extends SteeringError {
  *  只是现在放不下。让它 resume 把已 park 的投递掉(或减少并发转向)之后再发。两个码塌在一起会让 UI
  *  说反话(同 `still_running` 的先例),所以它有自己的类而不是落基类。 */
 export declare class SteeringQueueFullError extends SteeringError {
+    name: string;
 }
 /** `steering.ledger_unavailable`(server ≥7.110.0,S-928;子代 steer 路由自 server ≥7.111.0 / S-966 起同样可达)—— server 在回 `200 applied`
  *  (interrupt{text}:`202 queued-immediate`;子代 steer:`200 applied`)**之前**
@@ -612,6 +653,7 @@ export declare class SteeringQueueFullError extends SteeringError {
  *  照用,server 侧零受理、零注入 ⇒ 不会重复)。不是改内容(invalid_content / blocked_by_hook)、不是换 key(duplicate_input_id)、
  *  不是等 resume(queue_full)。处置分岔 ⇒ 自己的类(判据二),`.errorCode` 保留。 */
 export declare class SteeringLedgerUnavailableError extends SteeringError {
+    name: string;
 }
 /** `steering.duplicate_input_id`(parked 腿 server ≥7.3.0 / core 5.14.0 #147;live 腿 server ≥7.23.0 /
  *  core 5.35.0 #257 起同样可达)—— 你带的 `Idempotency-Key` 已经
@@ -629,6 +671,7 @@ export declare class SteeringDuplicateInputIdError extends SteeringError {
     /** 体 `detail.differs`:{@link STEER_REPLAY_FACETS} 的非空子集(引擎的序)。整体成形或整体缺席 —— 不是数组 / 空 / 含集外词 ⇒ undefined
      *  (原值仍在 {@link APIError.extra};与 server 自己的读口同判:读不出就不铸)。 */
     readonly differs?: readonly SteerReplayFacet[] | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** 体 `detail.differs`:{@link STEER_REPLAY_FACETS} 的非空子集(引擎的序)。整体成形或整体缺席 —— 不是数组 / 空 / 含集外词 ⇒ undefined
      *  (原值仍在 {@link APIError.extra};与 server 自己的读口同判:读不出就不铸)。 */
@@ -650,7 +693,11 @@ export type SteerReplayFacet = (typeof STEER_REPLAY_FACETS)[number];
  *     ⚠️ 这一条**必须**是拒:`reason` 自 1.284.0 起在直连门的 HMAC 签名载荷里(ASSISTANT-WIRE-CONTRACT §6.2),
  *     服务端截过的字节与签名方签的字节必然不同 ⇒ MAC 恒不匹配,截断只会把可诊断的 413 变成费解的 401。
  *  Client action:缩短该字段后重发(重试原文没有意义);两个上限都是 server 侧常量,别在客户端猜。 */
+/** ⚠️ 同一类也接 `413 request.payload_too_large`(`request.*` 族里唯一的分岔,处置同样是「缩短后重发」)—— server ≥7.132.0:TiDB / MySQL 协议部署上**提交体**超库的单行墙 / 包墙
+ *  (`min(8 MiB, 库的单行上限 − 64 KiB)`,按体的 JSON 字节判)也落这一码,体带 `wallSource`(墙从哪来,见 {@link PayloadWallRefusalExtra});写续跑输入那一笔被库以「一行装不下」拒的答复同码
+ *  (活流腿是终帧 `done`,`result.errorCode` 同码)。此前受理、写库那一刻 500。出路:缩小内联图 / 附件,或运维抬库的单行上限。 */
 export declare class PayloadTooLargeError extends APIError {
+    name: string;
 }
 /** [1833] G13 — `runs.taskStop` 的 409 冲突家族(server `src/http/routes/runs.ts` 的 stop 路由,`errorCode`
  *  判别;design/158 A9 域拆分后已不在 `src/http/server.ts`):
@@ -659,6 +706,7 @@ export declare class PayloadTooLargeError extends APIError {
  *  恢复赢了)/ `stop.park_arbiter_unreachable`(仲裁店不可达,真相未知——core 1.397 三分)。
  *  开集:未来新 `stop.*` 码同样落到本类(`errorCode` 原样携带),消费方 switch 要留 default。 */
 export declare class TaskStopConflictError extends ConflictError {
+    name: string;
 }
 /** 409 `interrupt.*` 族(core #504 / server ≥7.52 `POST /v1/runs/:id/interrupt`)—— 前缀开集,与 `stop.*`
  *  同形。两个现役码,处置相反所以**都别盲重试**,按 `.errorCode` 分支:
@@ -668,27 +716,32 @@ export declare class TaskStopConflictError extends ConflictError {
  *     那两条腿返回结果不返回流)⇒ 要 run 级停用 `POST /v1/runs/:id/cancel`;证得出他副本时文案会指路重发。
  *  终态/刚落定臂复用 `steering.not_running`(→ {@link SteeringNotRunningError}),不在本族。 */
 export declare class InterruptConflictError extends ConflictError {
+    name: string;
 }
 /** design/80 D-G (direct-connect door, service [84]) — the signed principal JWT (`X-Approval-Principal-Token`)
  *  failed to verify against the worker's projected pubkey anchor (bad sig / exp / iss / aud / alg-not-pinned).
  *  401. Client action: re-sign a fresh short-TTL JWT; persistent ⇒ BFF signing key/anchor misaligned. FORWARD-
  *  DRAFT: wire codes are service-locked; the BFF signer + live path land at M2. */
 export declare class PrincipalUnverifiedError extends APIError {
+    name: string;
 }
 /** design/80 D-G — the JWT verified but its `cnf.bnd` ≠ SHA256(checkpointToken): the identity assertion was
  *  minted for a DIFFERENT decision and lifted onto this one (token-lift). A SAFETY signal. 401. Client action:
  *  NEVER retry verbatim; re-mint the JWT bound to THIS checkpointToken. */
 export declare class PrincipalUnboundError extends APIError {
+    name: string;
 }
 /** ASSISTANT-WIRE-CONTRACT §4b（service main 6cd0164）— 你对一个 human/policy_ask 门调了 resume（CONTINUE）。
  *  409 errorCode `gate_not_resumable`。一个 "continue" 绝不能绕过人审。SEMANTIC（错门）, NOT session-CAS ConflictError。
  *  Client action: 这条路是 /decide（approve/deny）, 不是 resume —— 改走人审 UI。 */
 export declare class GateNotResumableError extends APIError {
+    name: string;
 }
 /** ASSISTANT-WIRE-CONTRACT §4c（service main 6cd0164）— 你对一个非 plan_review 门调了 plan_review。
  *  409 errorCode `gate_not_plan_review`。一个 plan 决策绝不能解 tool 审批 / resource_limit。SEMANTIC（错门）, NOT ConflictError。
  *  Client action: 按 gateKind 选对的决策端点（/decide 或 /resume）, 重取 inbox。 */
 export declare class GateNotPlanReviewError extends APIError {
+    name: string;
 }
 /** [2400] CB-2(SDK 4.2.0)—— 语义错门守卫的**第三个**成员(与上面两兄弟同形):你对一个**不是工具审批门**
  *  的挂起调了 `/v1/approvals/:sessionId/decide`。409 errorCode `gate_not_tool_approval`
@@ -699,6 +752,7 @@ export declare class GateNotPlanReviewError extends APIError {
  *  🔴 与 session-CAS `ConflictError` 刻意不同类:两者都是 409,但这一条说的是「你敲错门了」,处置是**换端点**,
  *  不是「重读再试」。 */
 export declare class GateNotToolApprovalError extends APIError {
+    name: string;
 }
 /** 409 `conflict.ask_decided` —— 这张卡**已经被结算过**,而你送的是**不同**的决议(同 `idempotencyKey`
  *  的重试走的是 200 回放,不到这里)。body 携带**首决回显**:谁、什么决议、什么时刻。
@@ -712,6 +766,7 @@ export declare class AskDecidedError extends ConflictError {
     readonly decidedAtMs?: number | undefined;
     /** 首决者身份断言(server 自铸;actor 永不参与权限判定,仅审计/呈现)。 */
     readonly actor?: ActorAssertion | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** 首决:被接受的那个决议。 */
     firstDecision?: "approve" | "deny" | undefined, 
@@ -725,6 +780,7 @@ export declare class AskDecidedError extends ConflictError {
  *  条款排除了它(一次同意不得被复用到另一次未经确认的征询)。
  *  Client action:换一个 key 重发(**不是**换 askId)。 */
 export declare class AskIdempotencyConflictError extends ConflictError {
+    name: string;
 }
 /** 410 `gone.ask_parked` / `gone.ask` —— 窗已关闭,这张卡的结局**已经铸定**,流内回决面对它已不存在。
  *
@@ -768,6 +824,7 @@ export declare class AskGoneError extends APIError {
      *  `orphan_ttl_exceeded` / `crashed_before_park` / `shutdown_before_park`)。组外的词、词表外的词在 mapper 里就被丢弃(原值仍在 `err.extra.cause`),不会到这里。
      *  缺席 = 行上没写成因(升级前落的存量行)或 ≤7.123.x 的 server(那一代的键叫 `deniedReason`)。 */
     readonly endingCause?: AskRowEndingCause | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** `PARKED` | `DENIED` | `VOID`(`gone.ask` 腿携带;`gone.ask_parked` 腿恒 PARKED,可缺席)。具名闭集型 {@link AskGoneState}
      *  ({@link toApiError} 只会产出三词之一,越界值在 mapper 里就被丢弃)。 */
@@ -820,6 +877,234 @@ export interface CheckpointUnsupportedVersionExtra {
     writerVersion?: string;
     readerVersion?: string;
 }
+/**
+ * **续跑 409 体的三只判别位**(server ≥7.132.0 / core 7.52.0;值经 `err.extra`〔{@link APIError.extra}〕到达)—— 引擎拒一次续跑时 `CheckpointError.detail` 的三个机读位**原样过境**,
+ * 键名与 server 自己在重放存量体之前拒的 409 `resume_blocked_by_policy` 同义 ⇒ 两种「谁发现的」读同一组键(有则在,无则缺席,不造键):
+ *  · `blockedBy` —— 挡住它的准入码 = 同一份坏配置在一次新跑上报的 `errorCode`(引擎拒那一侧今天只有 `checkpoint.config_refused` 带它,闭集属主 core `CHECKPOINT_CONFIG_REFUSAL_CODES`,
+ *    core 7.53.0 起 40 词 —— 本包不枚举,按「新跑上的 errorCode」读;`resume_blocked_by_policy` 上它恒在,读位另有具名的 {@link ResumeBlockedByPolicyError.blockedBy});
+ *  · `field` —— 哪一侧 / 哪一格(`checkpoint.config_refused` 上:`taskConfig` 改配置后同一张卡再决 / `deps`〔core 7.53.0 起〕部署自己的座位坏了,修部署后同一张卡再决 /
+ *    `inheritedGate` 行自己记下的模式种子坏了,只能取消这条 run);
+ *  · `reason` —— 同码多臂时哪一臂(闭集属主 core `CheckpointErrorReason`;**每一个**引擎码都过境 —— `checkpoint.unsupported_version` 的 `version_newer` 等自 7.132.0 起也上 wire)。
+ * 「改一格再决」与「只能在停它的那一版 worker 上跑完、或取消」靠 `field` + `blockedBy` + `reason` 分;`retriable: true` 在场 ⇔ 卡仍 pending(见 {@link APIError.retriable})。
+ * 一处如实例外:后台停驻子代腿被同类认领前拒时答 422 `parked_resume.startup_failed`,体只带 `cause`(到引擎的回执带上这几键为止)。
+ * 读法:`if (e instanceof ConflictError && e.errorCode?.startsWith("checkpoint.")) { const f = e.extra as ResumeRefusalExtra; … }`。
+ */
+export interface ResumeRefusalExtra {
+    blockedBy?: string;
+    field?: string;
+    reason?: string;
+}
+/**
+ * `400 request.field_invalid` 的**撞帽与坏条目机读位**(一组键,各面同名;值经 `err.extra` 到达,本类不为它们开具名属性)。
+ *  · `field` —— 撞帽 / 坏条目那一处的**体内坐标**(`skills[1].allowedTools`、`agents[0].denyTools[3]`、`agents`、`allowTools`、`settings.permissions.allow`、`additionalDirectories` …);
+ *  · `reason` —— 闭集四词,穷举读:`over_cap`(条数:数组的条目数)/ `too_long`(字符数:一段文字的长度;server ≥7.132.0)/ **`too_large`**(字节数:一份载荷的体积;**server ≥7.133.0**,只在 **413** 上 —— 见下)/ `bad_entry`(坏条目);
+ *  · `count` + `cap` —— 撞帽形(`over_cap` / `too_long` / `too_large`):送来的量与帽(**量纲由 `reason` 定**:条数 / 字符数 / 字节数);`index` —— `bad_entry` 形的首个坏条目下标(数组本身不是数组时缺席)。
+ *    🔴 **量不出的形**(server ≥7.133.0):读体读到帽就停〔体没读完 —— 不为量一个数把 8 MiB 之外的字节再读进内存〕/ 库只说「一行装不下」时,**`count` 缺席、`cap` 只在帽已知时在**(不编数):
+ *    **读体超 8 MiB 恒答 `413 request.payload_too_large`**,体 `{ field: "body", reason: "too_large", cap }`(无 `count`;此前多数口答 400、一批口折 400)—— 同一组机读位也在其余 413 / 400 的撞帽口上(`field` 高亮坐标);
+ * 射程:server ≥7.106.0 起 `settings.permissions.{allow,deny,ask}` 三桶(`over_cap` / `bad_entry`);**server ≥7.132.0 扩到**提交体上全部工具名清单(技能 `allowedTools` / `disallowedTools`
+ * 顶层与子代两层、根 `allowTools` / `excludeTools`、子代 `allowTools` / `denyTools`)、子代定义(条数 32、`name` 64 字、`whenToUse` / `whenToUseLean` / `observer` / `observerMessage` 4096 字、
+ * `systemPrompt` 65536 字、`allowTools` / `denyTools` 64 条与单条 128 字)、`additionalDirectories` / `additionalReadDirectories`(64 条;坏条目同 `bad_entry`)。
+ * 撞帽句的头一句恒为 `<field> has <count> entries|characters — at most <cap> are accepted`(句子给人看,机器读本组键)。请求体上其余的帽(`systemPrompt` / `appendSystemPrompt`、
+ * `settings.outputStyle` / `settings.env`、`jobId`、`clientContext`、`sandboxImageProfile`、`outputSchema`、`resumeAt`、技能 `content`、`images` 的 413)仍只有句子;形错(不是串 / 空串 / 不是数组)只有句子、不铸 `reason`。
+ * ⚠️ 同一个码上另有两种机读版式,按 `field` 区分(不按键猜):`field === "settings.hooks"` ⇒ 嵌套 `detail`({@link SettingsHooksRefusalDetail});领养 principals 两句的 `detail` 是**串**。
+ * 续跑腿同判:折成 409 `resume_blocked_by_policy`(`blockedBy: "request.field_invalid"`),本组键随体原样带上。
+ */
+export interface RequestFieldRefusalExtra {
+    field?: string;
+    reason?: RequestFieldRefusalReason;
+    count?: number;
+    cap?: number;
+    index?: number;
+}
+/** {@link RequestFieldRefusalExtra.reason} 的闭集(server 契约附录 A `request.field_invalid` 行;`too_large` 是 server ≥7.133.0 加的第四词 —— **量纲词**三个 `over_cap` / `too_long` / `too_large`
+ *  与一个坏条目词 `bad_entry`:见 {@link RequestFieldRefusalExtra.reason} 注)。闭集成员增长是加性的,但对它做 `switch` 穷举的消费端要补一条 `case`。 */
+export type RequestFieldRefusalReason = "over_cap" | "too_long" | "too_large" | "bad_entry";
+/** `settings.hooks` 拒判决的坐标:契约分类器的段形数组,相对请求体的 `settings` 对象(如 `["hooks","PreToolUse",0,"hooks",1]`);用户文本段经契约包的出门读法,凭据形不原样回显,
+ *  每个串段过拒句回显口径(剥控制与双向字符、截到 64 字、超出加 `…`)。 */
+export type SettingsHooksConfigPath = Array<string | number>;
+/**
+ * `400 request.field_invalid` 上 `field === "settings.hooks"` 那一族的 `detail`(对象形;server ≥7.115.0 起 matcher 拒带它,**server ≥7.132.0 起 `settings.hooks` 的每一只拒都带**,
+ * 且**恒带 `path`** —— 判决所在的坐标,见 {@link SettingsHooksConfigPath})。按 `reason` 分形,穷举读(多一形 = server 侧编译红,本包同批加)。
+ * 支持地板之内的老 server 交的老形照收(一条律:老 server 缺的键在型上可选):server 7.126.0–7.131.x 的 matcher 三形(`dead_alias` / `over_budget` / `invalid_regex`)**无 `path`**;
+ * server 7.115.0–7.125.x 只有死别名一形且**无 `reason`**(`{ event, alias, canonical }`,末一臂 —— `reason === undefined` 判它)。7.132.0 才有的形 `path` 必有。
+ *  · matcher 四形(fresh 提交面的 matcher 判据):`dead_alias`(选中别名而选不中正名;`alias` / `canonical` 取自引擎静态目录)· `over_budget`(单次求值超每次额度 `budgetMs`)·
+ *    `budget_exceeded`(server ≥7.132.0:一次受理里所有已完成正则形求值的耗时之和超过受理总额度 `totalMs`〔5 000 ms〕)· `invalid_regex`(正则编不过;7.132.0 起写在任一契约事件上都判);
+ *    四形都带 `event`,后三形带 `groupIndex`(从 0 起);
+ *  · 配置读者的拒:契约分类器的码原样(`HOOKS_REJECTION_CODES` 六词 / `HOOKS_DROPPED_PIECE_CODES` 五词,连字符拼法)+ 可选 `key`(那一块上让它坏的键);
+ *  · `unsupported_entry_type` + `type`(本服务不执行的条目类型,`path` 指那一条的 `type`);
+ *  · `over_cap` / `too_long` + `count` / `cap`(服务侧上限:组数 16、一个事件的条目总数 32〔`path` 指第一条超出的条目〕、命令 / URL 8192 字、header 32 个 / 合计 8192 字、`allowedEnvVars` 32 个);
+ *  · `unnamed_refusal`(分类器说拒却一块都没点名 —— 契约漂移,fail-closed);
+ *  · **`wire_key_invalid`**(server ≥7.133.0)—— 本服务自己读的三只 wire 键形错:组上的 `source`(闭集见 {@link import("./settings.js").SettingsHookGroupSource})· command 条目上的 `plugin` / `args`
+ *    (见 {@link import("./settings.js").SettingsHookPluginContext});`key` 点名那一只,`path` 指那一只键的坐标。**整份拒,不剥**(此前它们被分类器当未知键静默剥掉:剥 `source` = 托管组落进非托管车道,剥 `args` = exec 形只剩可执行名)。
+ *    另:插件上下文合计一道 8192 字的总字符帽 —— 超了走既有的 `over_cap` 形(`count` / `cap`)。
+ * 读法:`if (e.extra.field === "settings.hooks") { const d = e.extra.detail as SettingsHooksRefusalDetail; switch (d.reason) { … } }` —— 分流后提示用户改那一处,**不要解析句子**。
+ */
+export type SettingsHooksRefusalDetail = {
+    reason: "dead_alias";
+    event: string;
+    alias: string;
+    canonical: string;
+    path?: SettingsHooksConfigPath;
+} | {
+    reason: "over_budget";
+    event: string;
+    groupIndex: number;
+    budgetMs: number;
+    path?: SettingsHooksConfigPath;
+} | {
+    reason: "budget_exceeded";
+    event: string;
+    groupIndex: number;
+    totalMs: number;
+    path: SettingsHooksConfigPath;
+} | {
+    reason: "invalid_regex";
+    event: string;
+    groupIndex: number;
+    path?: SettingsHooksConfigPath;
+} | {
+    reason: SettingsHooksPieceCode;
+    path: SettingsHooksConfigPath;
+    key?: string;
+} | {
+    reason: "unsupported_entry_type";
+    path: SettingsHooksConfigPath;
+    type: string;
+} | {
+    reason: "over_cap" | "too_long";
+    path: SettingsHooksConfigPath;
+    count: number;
+    cap: number;
+} | {
+    reason: "unnamed_refusal";
+    path: SettingsHooksConfigPath;
+} | {
+    reason: "wire_key_invalid";
+    key: "source" | "plugin" | "args" | (string & {});
+    path: SettingsHooksConfigPath;
+} | {
+    reason?: undefined;
+    event: string;
+    alias: string;
+    canonical: string;
+    path?: undefined;
+};
+/** 契约包(`@sema-agent/settings-schema/hooks`)分类器的码:`HOOKS_REJECTION_CODES` 六词 ∪ `HOOKS_DROPPED_PIECE_CODES` 五词(镜像;门钉对钉版 server 依赖的契约包运行期常量)。 */
+export declare const SETTINGS_HOOKS_PIECE_CODES: readonly ["guard-outside-hooks", "hooks-is-matcher", "guard-under-unknown-event", "guard-event-not-array", "guard-matcher-invalid", "guard-entry-invalid", "hooks-not-object", "unknown-event", "event-not-array", "matcher-invalid", "entry-invalid"];
+/** {@link SETTINGS_HOOKS_PIECE_CODES} 的成员型。 */
+export type SettingsHooksPieceCode = (typeof SETTINGS_HOOKS_PIECE_CODES)[number];
+/**
+ * `400 request.invalid_json` 的 `reason` 闭集(server ≥7.133.0;体 `{ error, errorCode, reason }`,值经 `err.extra.reason` 到达):请求体不是这一口要的 JSON ——
+ * `not_json`(体不是合法 JSON)/ `not_object`(体是合法 JSON 但不是对象,而这一口要对象;如 `compact` 口)。**读开集**(未知词按「请求体形不对」处置)。
+ * 🔴 **BREAKING(wire 码,server 7.133.0)**:坏 JSON 体恒答 `400 request.invalid_json`。此前同一件事在多数口答 `request.rejected`(状态兜底粗码)、`notify` / `wake` / 权限规则三口答 `request.body_shape`,
+ * 一批口读体超限折 400 —— 按那几个码识别「坏 JSON」的代码要改读 `errorCode === "request.invalid_json"` + `reason`(零别名、零开关)。≤7.132.x 的 server 仍是旧码:**本包的读法恒是按 wire 上的 `errorCode` 分,不按版本猜**。
+ */
+export declare const INVALID_JSON_REASONS: readonly ["not_json", "not_object"];
+/** {@link INVALID_JSON_REASONS} 的成员型(读侧开集)。 */
+export type InvalidJsonReason = (typeof INVALID_JSON_REASONS)[number];
+/** `400 request.invalid_json` 体上的机读位(值经 `err.extra` 到达,本类不为它开具名属性;落 {@link BadRequestError})。 */
+export interface InvalidJsonRefusalExtra {
+    reason?: InvalidJsonReason | (string & {});
+}
+/**
+ * `400 request.field_conflict` 的 `detail.kind` 闭集(server ≥7.133.0,**十四词**):一份请求体**自己跟自己矛盾**(两个键不能同带)是哪一类约束。同一个约束的几个拒点同一个词。体 `detail`:
+ * `{ kind, fields[], count?, cap? }` —— `fields` = 被点名的请求体坐标(主语在前,至少一个;动态下标用 `agents[1].skills` 形),`count` / `cap` 只在「折叠上限」那一类带(合起来的量与帽)。句子与码不变;老 server 只有一句英文。
+ * 每类的坐标闭集:`cascade_verify`(`verify` / `cascade` / `sandboxImageProfile` / `resumeAt` / `suggestNextPrompts`)· `image_profile`(`capabilitiesNeeded` / `sandboxImageProfile`)·
+ * `resume_anchor`(`resumeAtMode` / `resumeAt`)· `system_prompt_fold`(`appendSystemPrompt` / `settings.outputStyle`)· `file_history_restore`(`fileHistory` / `restoreFiles` / `rewindFilesTo` / `rewindFiles`)·
+ * `skills_disabled`(`disableSkills` / `skills` / `agents[i].skills`)· `existing_session`(`requireExistingSession` / `sessionId`)· `scratchpad_root`(`cwd` / `scratchpadDir`)· `ask_answer`(`decision` / `answer`)·
+ * `policy_person_ask`(`decision` / `decidedBy`)· `plan_edit`(`decision` / `editedPlan`)· `plan_mode_after`(`decision` / `permissionModeAfter`)· `bound_call_door`(`boundCallId`)· `remember_decision`(`remember` / `decision`)。
+ * 壳按 `detail.kind` 分支、按 `detail.fields` 高亮冲突的两处输入;**读开集**(未知 kind 按「请求体自相矛盾」处置)。
+ */
+export declare const FIELD_CONFLICT_KINDS: readonly ["cascade_verify", "image_profile", "resume_anchor", "system_prompt_fold", "file_history_restore", "skills_disabled", "existing_session", "scratchpad_root", "ask_answer", "policy_person_ask", "plan_edit", "plan_mode_after", "bound_call_door", "remember_decision"];
+/** {@link FIELD_CONFLICT_KINDS} 的成员型(读侧开集)。 */
+export type FieldConflictKind = (typeof FIELD_CONFLICT_KINDS)[number];
+/** `400 request.field_conflict` 体上的机读位(值经 `err.extra` 到达;落 {@link BadRequestError};顶层 `detail` 见 {@link FIELD_CONFLICT_KINDS})。 */
+export interface FieldConflictRefusalExtra {
+    detail?: {
+        kind: FieldConflictKind | (string & {});
+        fields: string[];
+        count?: number;
+        cap?: number;
+    };
+}
+/**
+ * 工具名清单与设置规则拒体 / 受理告知上的一条**条目问题**(server ≥7.133.0;`detail.problems[]` / 200 体 `warnings[]` 同一只形):
+ *  · `code` —— 这条问题所属拒码(拒体里 = 该拒的码;`warnings[]` 里 = 引擎对该条的读数码);
+ *  · `field` —— 条目所在清单在请求体里的坐标(`settings.permissions.allow` / `skills[i].allowedTools` …);
+ *  · `entry` —— 条目**原串**(server 过脱敏口回显,不是你发的原字节保证);
+ *  · `reason` —— 机读原因:多数是**引擎的词原样**(引擎读成空的原因词);server 自铸两词 {@link SERVER_ENTRY_PROBLEM_REASONS}:`not_in_roster`(放行侧选择器清单里的这个名字不在名册、也不是协议命名空间名 —— 引擎照旧受理,之后只告运维;**只在受理告知 `warnings[]`**)·
+ *    `home_unresolvable`(设置规则 422 的词:`~/` 形路径规则而本部署解不出执行环境的家目录)。另有一个**不是 server 自铸**的词:`below_trust_floor`(契约包 `LAYER_ADMISSION_VERDICTS` 里的词,server 在调用方信任档低于该成员的准入门槛时拿它当 `reason`,见 {@link BelowTrustFloorExtra};
+ *    **不在** {@link SERVER_ENTRY_PROBLEM_REASONS} 里)。**读开集**。
+ */
+export interface EntryProblem {
+    code: string;
+    field: string;
+    entry: string;
+    reason: string;
+}
+/** server 自铸的两个条目问题词(闭集,其余 `reason` 是引擎的词原样):`not_in_roster`(受理告知 `warnings[]` 的词)· `home_unresolvable`(设置规则 422 的词)。 */
+export declare const SERVER_ENTRY_PROBLEM_REASONS: readonly ["not_in_roster", "home_unresolvable"];
+/** {@link SERVER_ENTRY_PROBLEM_REASONS} 的成员型。 */
+export type ServerEntryProblemReason = (typeof SERVER_ENTRY_PROBLEM_REASONS)[number];
+/**
+ * 条目问题拒体上的机读位(server ≥7.133.0;值经 `err.extra` 到达):顶层 `field` = 第一条问题的坐标(句子点名的那张清单),`detail = { problems[], total }` ——
+ * `problems` 至多 1000 条(= 一张清单的条数帽),`total` 是真数(`total > problems.length` ⇒ 被截,没列全)。工具名清单(技能 `allowedTools` / `disallowedTools`、子代 `allowTools` / `denyTools`、根 `allowTools` / `excludeTools`)
+ * 与 `settings.permissions` 三桶的拒都带它。逐条提示用户改哪一条,**别解析句子**。
+ */
+export interface EntryProblemsRefusalExtra {
+    field?: string;
+    detail?: {
+        problems: EntryProblem[];
+        total: number;
+    };
+}
+/**
+ * `400 request.field_invalid` 上 `detail.problems[].reason === "below_trust_floor"` 的拒体(server ≥7.133.0):请求里「不经人答就生效」的规则表(`settings.permissions` 各桶、被按名点用的自带技能的 `allowedTools` /
+ * `disallowedTools`)按**调用方信任档**准入 —— `allow` 放宽免问面要 `global`;`deny` / `ask` 只收紧、任何档都收。低于门槛的放宽**响亮拒而不是静默丢**(契约要求);`detail.callerTrust` = 这次请求被准入的档
+ * (`global` / `project`,**开集读**,与 `capabilities.settings.permissions.callerTrust` 同词表);`detail.problems[]` 逐条点名被拒的条目(`reason: "below_trust_floor"`)。
+ * 出路:答卡(本地同意出口)/ 抬角色到治理域写角色 / 把规则放进部署的 `APPROVAL_GRANT` / 去掉 `allow` 开跑时答卡 —— 壳提交前读 `callerTrust` 能力位就不会撞。续跑腿不读本档(存储体在自己的受理口按当时的档准入过)。
+ */
+export interface BelowTrustFloorExtra {
+    field?: string;
+    detail?: {
+        problems: EntryProblem[];
+        total: number;
+        callerTrust: "global" | "project" | (string & {});
+    };
+}
+/** `400 config.user_attachment_invalid` 体上的 `detail`(server ≥7.132.0 / core 7.53.0;体 = `{ error, errorCode, detail? }`,值经 `err.extra.detail` 到达):引擎在句首点名的字段 ——
+ *  `path` = 句子开头那一段(`TaskSpec.userAttachments[2].text`),`index` = 0 起的附件位置,**只在句子点名一只附件时在场**(整只席位的拒 —— 不是数组 / 超条数 —— 只有 `path`)。
+ *  与流式 `done.result` / run 记录上 `terminal.detail.detail` 同一份(那两面上的同一只码同形)。本码今天是附录 A 里唯一随码带 `detail` 的 400。 */
+export interface UserAttachmentRefusalExtra {
+    detail?: {
+        path: string;
+        index?: number;
+    };
+}
+/**
+ * 413 拒体上「拒它的那堵墙的数字是不是库自己报的」(server ≥7.132.0;server `SqlWallSource`):`reported` = 库报的墙(引擎在连接初始化时读到的);`assumed` = 不是库报的,
+ * 按受支持引擎里最保守的缺省墙拒 —— 引擎事实还没建立(连接初始化被拒 / 还没读到),或事实在场但这一堵墙读失败退了文档缺省(TiDB < 7.6 又无 `CONFIG` 权限读不到
+ * `txn-entry-size-limit`;`max_allowed_packet` 读不出)。事实没建立的窗口里稍后重试按库报的墙重判;读失败退缺省的墙不会自己变真 —— 持续则要运维让服务读得到那个上限。
+ */
+export type SqlWallSource = "reported" | "assumed";
+/** `413 request.payload_too_large` 在**提交口**(`POST /v1/tasks` / `/v1/tasks/stream` / `/v1/runs`)因库的单行墙 / 包墙拒时体上的机读位(server ≥7.132.0;值经 `err.extra` 到达,
+ *  本码落 {@link PayloadTooLargeError})。同码的其余 413(体超 8 MiB、附件、内联图片)不带它 ⇒ 缺席。 */
+export interface PayloadWallRefusalExtra {
+    wallSource?: SqlWallSource;
+    /** server ≥7.133.0:同体另带统一撞帽机读位({@link RequestFieldRefusalExtra}):`field: "body"` · `reason: "too_large"` · `count`(这份体的 JSON 字节数)· `cap`(这一堵墙的字节数)。老 server 只有 `wallSource`。 */
+    field?: string;
+    reason?: RequestFieldRefusalReason;
+    count?: number;
+    cap?: number;
+}
+/** SQL 快照 blob 的帽**从哪来**(server ≥7.132.0;server `SqlBlobCapReading.source`):`operator` = 运维设的 `SNAPSHOT_BLOB_SQL_MAX_BYTES`;`reported` / `assumed` = 由库的墙
+ *  推出时那一条腿的墙数字出处(同 {@link SqlWallSource})。 */
+export type BlobSqlCapSource = "operator" | SqlWallSource;
+/** `PUT /v1/sessions/:id/sync/blobs/:hash` 的 `413 blob_too_large_for_sql` 体上的机读位(server ≥7.132.0;体 = `{ error, errorCode, wallSource }`,值经 `err.extra` 到达)。
+ *  句子按三形分,不把旋钮或假定说成库的上限。`reported` / `operator` 形重试同一份 blob 不会自己变好(出路:配对象存储);`assumed` 形可稍后重试 / 让服务读得到库的上限 / 设旋钮。 */
+export interface BlobTooLargeForSqlExtra {
+    wallSource?: BlobSqlCapSource;
+}
 /** `DENIED` 态的唯一合法结局成因(server 全仓 `DENIED` 只有一个写点)—— {@link ASK_ROW_ENDING_CAUSES} 的首员。导出是因为消费端要拿它做
  *  「路由失败 vs 人拒」的判别与文案分支 —— 手抄一份字符串正是这条界线被抹掉的常见方式。server ≥7.124.0 起它住在 410 体的 `cause` 键上(此前 `deniedReason`)。 */
 export declare const DENY_REASON_ROUTING_FAILURE = "routing_failure_fail_closed";
@@ -840,6 +1125,7 @@ export declare class AskParkingError extends APIError {
     readonly retryAfterMs?: number | undefined;
     /** body 里的秒制成对键(与头同源;守卫式提取,非有限数丢弃)。 */
     readonly retryAfterSec?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** `Retry-After` 头解析出的毫秒(transport 统一喂入)。 */
     retryAfterMs?: number | undefined, 
@@ -848,6 +1134,7 @@ export declare class AskParkingError extends APIError {
 }
 /** design/80 D-G — the direct-connect door requires the HMAC envelope (`X-Approval-Mac`) and it was absent. */
 export declare class ApprovalMacRequiredError extends APIError {
+    name: string;
 }
 /** design/80 D-G — the HMAC envelope failed verification (wrong key/kid, or a tampered [token,callId,hash,
  *  decision] tuple). 401. Client action: re-sign with the active HMAC kid; persistent ⇒ key rotation skew.
@@ -858,6 +1145,7 @@ export declare class ApprovalMacRequiredError extends APIError {
  *  删除、零双读、混版两向皆 401)对**本包的调用方**零动作 —— 除非它自己就是那个签名器,那时它按 server 的
  *  契约 §6 改形。**没有直连门的部署完全不受影响**。 */
 export declare class ApprovalMacInvalidError extends APIError {
+    name: string;
 }
 /** `resume_outcome_invalid` — a plan_review / dry-run-review outcome was REJECTED BY CONTENT SANITIZE
  *  (`editedPlan`/`reason` carried a forbidden tag), or — on the tool-approval gate — one cell of the decision body is not valid:
@@ -871,6 +1159,7 @@ export declare class ApprovalMacInvalidError extends APIError {
  *  precisely so a UI routes to the right recovery (fix the text and re-submit) instead of the action-binding
  *  flow. Collapsing the two back into one type in the SDK would undo that split. Usually `retriable`. */
 export declare class ResumeOutcomeInvalidError extends APIError {
+    name: string;
 }
 /** `resume_blocked_by_policy` — an admission policy CHANGED between suspend and resume, and the resume is no
  *  longer admissible. Not a race: retrying as-is stays blocked until the policy or the request changes.
@@ -894,6 +1183,7 @@ export declare class ResumeBlockedByPolicyError extends APIError {
      * 「The check that refused it: resume_blocked_by_policy」—— 编一个值比缺席更坏。支持地板抬过 7.104.0 的那一版可改必有(那时缺席不再可达)。
      */
     readonly blockedBy?: string | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /**
      * **哪一道检查拒的**:被折叠的那只拒绝**直接**出去时会带的 `errorCode`。server ≥7.104.0(S-607)起 wire 上**恒在**:带码的原拒绝 ⇒
@@ -913,6 +1203,7 @@ export declare class ResumeBlockedByPolicyError extends APIError {
  *  session_not_found。前缀开集:core 未来新码至少落到本类(`.errorCode` 判别),不塌匿名 409。
  *  ⚠️ 与下划线形的 resume_outcome_invalid / resume_blocked_by_policy 是**两族**(那两个在上面,先判)。 */
 export declare class SubagentResumeConflictError extends ConflictError {
+    name: string;
 }
 /** A-075.10 —— resume 族的**时间性拒绝**二码(前码 server ≥7.47.0、后码 ≥7.51.0;亲读 `http/server.ts` 拒绝体铸点):
  *  `resume.usage_window_exhausted`(#449 G1,core 5.60.1:该行账本键上的部署治理窗满了;「什么都没消费、
@@ -928,6 +1219,7 @@ export declare class ResumeRetryLaterError extends SubagentResumeConflictError {
     readonly retryAfterMs?: number | undefined;
     /** 响应体的 `retryAfterSec`(秒;守卫式提取,非有限数当缺席)。缺席=服务端没给窗。 */
     readonly retryAfterSec?: number | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, 
     /** `Retry-After` 头解析出的毫秒(transport 喂入;该腿 server 今天不发头 ⇒ 通常缺席)。 */
     retryAfterMs?: number | undefined, 
@@ -939,10 +1231,12 @@ export declare class ResumeRetryLaterError extends SubagentResumeConflictError {
  *  ⚠️ [2400] CB-2 起 `wake.` 是**前缀开集**:未来的 `wake.*` 新码至少落到 {@link ConflictError}
  *  (`.errorCode` 原样携带),不再塌成匿名 409。 */
 export declare class WakeGatePendingError extends ConflictError {
+    name: string;
 }
 /** 409 `compact.not_running` / `detach.not_running` —— replica-local live-verb 族:run 已终态,或活在
  *  另一副本(手动 compact/detach 只对本副本的活流有效)。`.errorCode` 判别是哪个 verb。 */
 export declare class RunNotLiveError extends ConflictError {
+    name: string;
 }
 /** Base of the `decide.*` family — catch this to handle the whole decide door in one place.
  *  Codes that fall on THIS class rather than a subclass need a human: `row_unrevivable` (damaged row),
@@ -967,6 +1261,7 @@ export declare class DecideError extends APIError {
      *  AND by which server sent it — 7.72.0 changed the "host not parked" answer without renaming the code,
      *  see that class's doc). */
     readonly runId?: string | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, taskId?: string | undefined, 
     /** revive legs only — the claim-rollback disposition the server reported. */
     rollback?: string | undefined, 
@@ -986,6 +1281,7 @@ export declare class DecideError extends APIError {
  *  different occupant. The re-fetch then usually shows the card GONE (a 7.104.0 session delete retires its parked children's cards) —
  *  nothing is left to decide; this form mostly meets cards left behind by a session deleted before 7.104.0. */
 export declare class DecideParkMovedError extends DecideError {
+    name: string;
 }
 /** `decide.parked_answer_required` / `decide.parked_remember_unsupported` — this park shape does not accept
  *  the decide you sent (an AskUserQuestion approve without `body.answer` — server 5.12.0/core 5.7.0 RB-459;
@@ -994,18 +1290,22 @@ export declare class DecideParkMovedError extends DecideError {
  *  `decide.parked_answer_unsupported` / `..._question_unsupported` are retired: the answer HAS a hookpoint
  *  now and a parked question CAN be approved (with an answer). */
 export declare class DecideUnsupportedError extends DecideError {
+    name: string;
 }
 /**
- * Why a parked resume could not start its approved action — the engine's closed set `RESUME_STARTUP_CAUSES` (core 7.51.0), word for word and in
+ * Why a parked resume could not start its approved action — the engine's closed set `RESUME_STARTUP_CAUSES` (core 7.51.0; six words since core 7.52.0), word for word and in
  * order. Server ≥ 7.129.0 relays it as the 422 `parked_resume.startup_failed` body's `cause`, screened against this set (a word the engine did
  * not say, or one outside the set ⇒ the key is absent). What each word tells the caller to do:
  *  · `environment` — the leg's infrastructure failed (workspace restore, an abort); the decision is untouched — retrying replays it;
  *  · `session_gone` — the resumed agent's transcript session is missing;
+ *  · `transcript_corrupt` — (core 7.52.0 #1796, server ≥ 7.132.0) the resumed agent's transcript is there but damaged: no header its store wrote, a leaf
+ *    or parent entry missing from the log, or a lost tail the checkpoint was cut inside. The row reopens as for `session_gone` (a system retry, the
+ *    decision is untouched); only the receipt now says which. Servers ≤ 7.131.x answered `session_gone` / no cause for these;
  *  · `tool_unavailable` — the approved tool is not available to the resumed leg (gone, or replaced by a different contract) — this approval cannot run, decide afresh;
  *  · `configuration` — the deployment's configuration refuses the resumed leg; a retry under the same configuration fails the same way;
  *  · `decision_rejected` — the decision does not fit the checkpoint (another gate's answer, an input the constraints refuse) — correct it and resubmit.
  */
-export declare const RESUME_STARTUP_CAUSES: readonly ["environment", "session_gone", "tool_unavailable", "configuration", "decision_rejected"];
+export declare const RESUME_STARTUP_CAUSES: readonly ["environment", "session_gone", "transcript_corrupt", "tool_unavailable", "configuration", "decision_rejected"];
 export type ResumeStartupCause = (typeof RESUME_STARTUP_CAUSES)[number];
 /** `parked_resume.startup_failed` (422 — core code PASSTHROUGH, server 5.12.0/RB-459): the decide was
  *  accepted and the revive attempted, but the resume failed during startup — the child's session is gone,
@@ -1042,6 +1342,7 @@ export declare class ParkedResumeStartupError extends DecideError {
      * raw value is still at `err.extra.cause`.
      */
     readonly startupCause?: ResumeStartupCause | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, taskId?: string, rollback?: string, runId?: string, 
     /**
      * K-19 — the machine-readable CAUSE WORD of this startup failure (client-core [8537] CC-225; server S-818 relays it
@@ -1064,6 +1365,7 @@ export declare class ParkedResumeStartupError extends DecideError {
 }
 /** `decide.store_unreachable` — the durable agent store is unreachable. Transient: retry the same decide. */
 export declare class DecideStoreUnreachableError extends DecideError {
+    name: string;
 }
 /** `decide.workflow_host_unknown` / `decide.workflow_host_not_parked` (409, server >=7.69.0 / S-185) — the
  *  pending belongs to a **workflow child** that parked on an approval gate, and the deployment could not hand
@@ -1089,6 +1391,7 @@ export declare class DecideStoreUnreachableError extends DecideError {
  *  (Grouped by what the caller must do — the same axis as {@link DecideParkMovedError} — rather than by status;
  *  both are 409 but neither is the "the park moved, refetch the list" doctrine.) */
 export declare class DecideWorkflowHostError extends DecideError {
+    name: string;
 }
 /** `decide.workflow_parks_unreadable` (409, server >=7.75.0 / S-252) — the pending belongs to a **workflow
  *  child**, and (the 7.75.0–7.117.x reading; a server ≥7.118.0 narrows the triggers — see the 7.118.0 paragraph at the end)
@@ -1159,6 +1462,7 @@ export declare class DecideWorkflowParksUnreadableError extends DecideError {
      *  (the body's top-level `readableHolderRunId`; absent when there is none or a tie — never `null`). Where the work can be carried
      *  on; it does NOT clear this refusal (the damaged record `.runId` names still blocks delivery until it is repaired). */
     readonly readableHolderRunId?: string | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, taskId?: string, rollback?: string, runId?: string, 
     /** server ≥7.118.0, the "record cannot be read" cause only: the readable record that holds this card at the highest generation
      *  (the body's top-level `readableHolderRunId`; absent when there is none or a tie — never `null`). Where the work can be carried
@@ -1178,6 +1482,7 @@ export declare class DecideWorkflowParkForkedError extends DecideError {
     /** The resumed runs that all hold this card (the body's `runIds`, ≥2 on the wire). Whole-or-nothing: absent when the body does
      *  not carry an array of non-empty strings (the raw value stays on {@link APIError.extra}). */
     readonly runIds?: readonly string[] | undefined;
+    name: string;
     constructor(status: number, errorCode: string | undefined, message: string, taskId?: string, rollback?: string, runId?: string, 
     /** The resumed runs that all hold this card (the body's `runIds`, ≥2 on the wire). Whole-or-nothing: absent when the body does
      *  not carry an array of non-empty strings (the raw value stays on {@link APIError.extra}). */
@@ -1208,17 +1513,21 @@ export declare function toApiError(status: number, body: unknown, retryAfterMs?:
  *  failed. `message` is secret-scrubbed (a registry/proxy may echo an Authorization header into an error body). */
 export declare class ControlError extends Error {
     readonly status: number;
+    name: string;
     constructor(status: number, message: string);
 }
 /** 401 — missing/invalid registry Bearer (SEMA_REGISTRY_TOKEN). Fail-closed. */
 export declare class ControlAuthError extends ControlError {
+    name: string;
 }
 /** 403 — authenticated but the token's role is below what the write needs (editor / publisher per domain).
  *  Client action: surface "needs a higher role"; do NOT retry with the same token. */
 export declare class ControlForbiddenError extends ControlError {
+    name: string;
 }
 /** 404 — unknown domain / unknown change id / unknown worker. */
 export declare class ControlNotFoundError extends ControlError {
+    name: string;
 }
 /** 400 — zod validation failed. `issues` carries the flat `{ path, message }[]` (batch prefixes path with
  *  `[changeIndex, domain, …]`). Client action: fix the offending field; this is deterministic, do NOT retry. */
@@ -1228,6 +1537,7 @@ export declare class ControlValidationError extends ControlError {
         message: string;
         code?: string;
     }[];
+    name: string;
     constructor(status: number, message: string, issues: {
         path: (string | number)[];
         message: string;
@@ -1240,6 +1550,7 @@ export declare class ControlValidationError extends ControlError {
  *  K-17: every 409 EXCEPT the scope-gone one — that is {@link ControlScopeGoneError}, deliberately not this class. */
 export declare class ControlConflictError extends ControlError {
     readonly currentVersion?: number | undefined;
+    name: string;
     constructor(status: number, message: string, currentVersion?: number | undefined);
 }
 /** 409 scope-gone (K-17; web-admin wave41 W41F): the rollback's TARGET scope was deleted — or deleted and re-created under
@@ -1251,6 +1562,7 @@ export declare class ControlConflictError extends ControlError {
  *  reviewed. Client action: stop, keep the intent, have a person confirm the scope is still the one to write. Still a
  *  {@link ControlError} (`status` 409, scrubbed `message`), so a family-wide catch keeps matching. */
 export declare class ControlScopeGoneError extends ControlError {
+    name: string;
 }
 /** Map a control-plane HTTP status + parsed body to the right typed error. Body envelope is `{ error, issues?,
  *  message?, currentVersion?, errorCode? }`. 🔴 message is scrubbed (Bearer / presigned) before surfacing.