@acosmi/sdk-ts 2.19.4 → 2.19.6

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2.19.6
+
+- `QuotaSummarySubscriptionPool` 追加三个可选字段 `boosterRemaining?: number` / `boosterCount?: number` / `boosterNextExpiresAt?: string`，描述订阅池里由**加油包**贡献的那一部分：网关 `quota_summary.go` 在既有那一次 alive 遍历里，对 alive 的 COMMERCIAL 桶中 `sourceType === 'booster_pack'` 的行求和（`boosterRemaining`，单位同 `unit`，即**微 Credits**，÷1000 = Credits）、计数（`boosterCount`，一行 = 一个加油包）、并在这些 alive **限期**桶里选举最早到期时刻（`boosterNextExpiresAt`，ISO-8601）。加油包是「加总额度」的产品动作，与只清 5 小时 / 7 天窗口、对额度池零交互的**重置卡**是两笔账，展示端不得互相替代。
+- **三个字段的缺席语义**：缺席 = 老网关（扣费通还没在 `/api/entitlements/buckets` 上下发 `sourceType`），**或**此刻一个 alive 加油包都没有 —— 两种都**不可当 0 读**。网关一行都认不出时三个键一起不下发，绝不写 0；写 0 等于在老网关上向用户断言「你没有加油包」，而真相是客户端不知道。展示端的合同是「三个字段齐全才渲染副行」。`boosterNextExpiresAt` 另有第三种缺席可能：加油包确实存在、但全是永久桶（不参与到期选举，与 `expiresAt` 同口径），此时 `boosterRemaining` / `boosterCount` 仍在场。
+- **零破坏性变更**：纯类型面追加，无运行时代码改动。`getQuotaSummary` 历来原样透传网关响应体，2.19.5 的调用方式一字不改仍然成立。
+
+## 2.19.5
+
+- `StreamError` 新增 `serverRetryable?: boolean` 与 `retryAfterSecs?: number`（追加字段，解析点仍只有 `parseStreamError` 一个，`/chat` 线 `event: failed` 与 `/anthropic` 线 `event: error` 同表）。`serverRetryable` 是帧上 `retryable` 的**原值**，不与 `requestDisposition` 合取：既有的 `retryable` 是两者的合取，而流内错误帧并不总下发 `requestDisposition`，于是「服务端明说可以重试」会被合取成 `false` —— 两端各自正确，合起来恒否，消费方分不出「服务端明说不可重试」（一票否决）与「服务端没说」（该回落到本地分类表）。`retryAfterSecs` 只收**有限非负数**，`null` / 负数 / NaN / Infinity / 非数字一律 `undefined`：宁可不给，绝不编造等待时间。两个字段缺席即 `undefined`，绝不补默认值；`retryable` 的合取语义一字未动。
+- 新增导出 `isStreamError(err): err is StreamError` —— `name === 'StreamError'` ∧ `errorCode` 是字符串的**结构**判据。消费方在 worker / `vm` 上下文里，或 SDK 被打进第二份 bundle 时，`instanceof StreamError` 会静默为 `false`，症状与「这段分类代码压根没写」逐字相同。`HTTPError` 也带可选 `errorCode`，靠 `name` 分开。
+- 新增 `ChatStreamOptions`，作为 `chatStream` / `chatMessagesStream` 的**末位**可选实参。`requestTimeoutMs` 声明这一次流的总时长安全网（从开始迭代算起，与调用方 `signal` 先到者生效，`break` 提前退出也会释放计时器）；`onResponseHeaders` 在拿到响应之后、判断 `resp.ok` **之前**交出整份响应头，用于读网关随头下发的流控提示（如 `X-Acosmi-Stream-Keepalive`，秒）—— 那个数只在头里，等流内事件时已经晚了，而最需要它的恰恰是一个事件都不来的流。与既有两个流式回调同构：旁路信号，回调抛错被吞掉且不中断流；401 刷新重试后由真正开始流的那次响应触发。
+- `FileTokenStore.withLock` 不再把 Windows 的 delete-pending 当成致命错误。NT 在 `unlink` 之后、最后一个句柄关闭之前把文件置为 `STATUS_DELETE_PENDING`，这期间 `open(lockPath, 'wx')` 抛的是 `EPERM`（实测原文 `EPERM: operation not permitted, open '...tokens.json.lock'`；`EBUSY` 是同机理的第二种表现）而**不是** `EEXIST`；判据只认 `EEXIST`，于是同一把锁上的一次正常交接被 `throw e` 报成永久失败 —— 同进程 5 个并发 `withLock` 就能稳定复现，受害者是 refresh token rotation 那段临界区。现在「锁被占」的判据是 `EEXIST` ∪（`win32` 且 code ∈ {`EPERM`, `EBUSY`}），命中后者时**跳过 stale 检测**直接退避重试（delete-pending 的文件 `stat` 要么失败要么给出前一持有者的旧 mtime，两种都会把「正在消失的锁」误判成「崩溃残留」，而 `stat` 失败那条腿是 `continue`、不过 `acquireTimeoutMs` 检查，会退化成不退出的忙循环），重试仍受 `acquireTimeoutMs` 上界约束。`EACCES` **不在**这个集合里：它在 Windows 上更常见的产地是锁目录只读 / 被策略拒绝这类真配置错误，收进来等于把「立刻报 `EACCES`」拖成「30 秒后报 acquire timeout」。**非 Windows 平台控制流逐字节不变** —— POSIX 的 `EPERM` 同样是真权限错误，一律不收。
+- **零破坏性变更**：前三项全部是追加式（新可选字段 / 新导出 / 末位新可选实参），2.19.4 的调用方式一字不改仍然成立。`requestTimeoutMs` 缺席或非有限正数时**不武装任何计时器**，与 2.19.4 逐字一致 —— 流式链路历来只受调用方 `signal` 约束（`CHAT_REQUEST_TIMEOUT_MS` 的注释此前误把两个流式方法也算了进去，本版同步勘误：那两条路径从来没有武装过它）。给历来无上限的流凭空补一道默认墙钟，第一个被杀的就是健康的长任务。
+
 ## 2.19.4
 
 - Stop dropping the OpenAI-line streaming usage tail frame. With `stream_options.include_usage: true` the upstream sends content frames, then the `finish_reason` frame, then `{"choices":[],"usage":{...}}`, then `data: [DONE]`. The stream converter discarded every frame without `choices`, and it had already emitted `message_delta` (without usage) and `message_stop` on the `finish_reason` frame, so no OpenAI-line turn streamed through `chatMessagesStream` ever carried usage and consumers counted it as zero. The converter now records the usage object of any frame, with or without `choices` (later frames override earlier ones), and puts it in the `message_delta` that immediately precedes the single `message_stop`.

package/README.md

@@ -7,7 +7,7 @@
 ## 状态
 
 - **主实现 / 事实标准**：本 TS SDK 现为 Acosmi SDK 的主力实现。Go SDK [acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) 已暂停维护，待 TS 稳定后再从 TS 反向翻译补齐。
-- **当前版本：`2.19.1`**（认证生命周期与上游错误归属修复，2026-09-08）。
+- **当前版本：`2.19.5`**（流内重试提示透出 + 流式可选项，2026-09-19）。
 - **`v2.19.1`**：可选 versioned 凭据存储、原子刷新与本地退出，支持将 HTTP / WebSocket 绑定到固定登录身份；外部凭据使用独立的 external 模式。所有模式仅在完整网关错误合同证明用户访问凭据失效且请求未接收时自动刷新重试，普通 401 原样返回。versioned 模式要求上游 metadata 的认证合同为 2、网关错误合同为 1；默认 legacy 存储接口继续可用。详见 [CHANGELOG](./CHANGELOG.md)。
 - **`v2.18.0`（加性类型发布）**：`ManagedModel` 新增可选字段 `thinking_levels?: string[]` —— 网关下发的**升序思考档位 id 列表**（`ThinkingOff`/`ThinkingHigh`/`ThinkingMax` 的子集）。`listModels` 对它原样透传，公开签名向后兼容、零行为变化；`[]` = 该模型无思考档，`undefined` = 旧网关未播报（按"未知"处理，严禁自行推档）。详见〈思考档位 `thinking_levels`〉。
 - **`v2.17.0`（安全修复发布）**：桌面 loopback `authorize()` 对 `/callback` 的**一切形态**（成功 / OAuth error / 畸形）先行校验 CSRF `state`，且必须"恰好一个"并严格等值 —— 缺失、重复（含重复的正确值）、错值一律以稳定错误码 `state_mismatch` 拒绝本次登录；此前携带 OAuth error 的回调绕过 state 直接结算 `auth_denied`，本机任意进程零知识即可打断/塑形等待中的登录，且 `?code=…&state=<正确值>&state=x` 这类重复参数可蒙混通过。`finally` 补 `closeIdleConnections()`，每条终止路径以端口完全关闭收尾。公开 API 签名零变化；回归闸门 `test/auth/desktop-loopback-state.test.ts` 十路终止矩阵。
@@ -358,6 +358,30 @@ const stream = client.chatMessagesStream(
 
 网关没下发（旧版本 / 非托管路径）时回调**一次都不触发**，SDK 绝不合成占位值；流照常出。浏览器端消费方还需网关 CORS `Access-Control-Expose-Headers` 放行该头（网关 v2026-09-01 起已放行）。
 
+### 流式可选项 `ChatStreamOptions`（v2.19.5+）
+
+`chatStream` / `chatMessagesStream` 的**末位**可选实参。两项都是追加语义，不传时行为与既往逐字一致。
+
+```ts
+const stream = client.chatMessagesStream(
+  modelId,
+  { messages, max_tokens: 4096 },
+  abortSignal,
+  onUpstreamActivity,
+  onGatewayRequestID,
+  {
+    requestTimeoutMs: 60 * 60 * 1000,        // ← 安全网，不是主判据
+    onResponseHeaders: h => {
+      const keepalive = h.get('X-Acosmi-Stream-Keepalive'); // 秒；缺失为 null
+      if (keepalive) armIdleWatchdog(Number(keepalive));
+    },
+  },
+);
+```
+
+- **`requestTimeoutMs`** —— 这一次流的**总时长**预算，从开始迭代算到流结束；与 `signal` 先到者生效，调用方 `break` 提前退出也会释放计时器。**缺席或非有限正数 = 不武装任何计时器**（流式链路历来只受调用方 `signal` 约束；`CHAT_REQUEST_TIMEOUT_MS` 只作用于非流式的 `chat` / `chatMessages`）。杀一条流的判据应当是**失去活性证据**（见上面的 `onUpstreamActivity`）而不是「活得太久」—— 这一条的职责只是给「看门狗本身坏掉」兜底，因此应当显著长于活性预算。
+- **`onResponseHeaders`** —— 在拿到响应之后、判断 `resp.ok` **之前**触发，因此 HTTP 错误响应上同样触发；401 刷新重试后由真正开始流的那次响应触发。网关的流控提示只存在于响应头里，等流内事件已经晚了，而最需要它的恰恰是一个事件都不来的流。与其它两个流式回调同构：旁路信号，回调抛错被吞掉且不中断流。
+
 ### Sources SSE 四态分类（v2.15+）
 
 `sources: []` 是检索成功但没有可展示引用的合法零结果，不是传输损坏。需要精确区分状态的新 consumer 使用加性接口 `classifySourcesEvent()`：
@@ -878,7 +902,7 @@ const view = await client.getBugReport(result.feedback_id);
 | -------------------- | ---------------------------------------------------------------------- |
 | `HTTPError`          | 4xx/5xx，含 `statusCode` / `body` / `type` / `retryAfter`              |
 | `NetworkError`       | TCP/DNS/TLS 失败；含 `isTimeout()` / `isEOF()` 便捷判定                  |
-| `StreamError`        | gateway `managed_model_stream_failed` 事件解析（含 `code` / `stage` / `retryable`） |
+| `StreamError`        | gateway `managed_model_stream_failed` 事件解析（含 `code` / `stage` / `retryable`；v2.19.5 起另带 `serverRetryable` = 帧上 `retryable` 原值、`retryAfterSecs` = 建议等待秒数，缺席均为 `undefined`。跨 realm 用 `isStreamError()` 判，别用 `instanceof`） |
 | `AgentRunStreamError` | Agent Runs 流返回 `error` 事件（默认抛出；可设 `throwOnError:false` 自行消费） |
 | `BusinessError`      | 网关返回 `code !== 0`，含 `code` (number) / `message` (字符串)         |
 | `RateLimitError`     | 429（含 `retryAfter`）                                                 |
@@ -1170,7 +1194,13 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 2.19.0 | **当前版本** | **网关消费请求 ID 透出（2026-09-01）**。网关把 `consumeRequestID`（即 `managed_model_usage_logs.request_id`）放进 `X-Acosmi-Request-Id` 响应头；加性导出 `GATEWAY_REQUEST_ID_HEADER` 与 `GatewayRequestIDCallback`，`chatMessagesStream` / `chatStream` 新增第 5 个可选实参、`chatMessages` / `chat` 新增第 4 个可选实参。响应头在首字节之前到达，因此覆盖流中段中断 / 零事件 / HTTP 错误全部形态。旧网关下回调零触发、绝不合成占位值，流照常出。不传回调时行为逐字节不变。 |
+| 2.19.6 | **当前版本** | **订阅池加油包份额（2026-09-20）**。`QuotaSummarySubscriptionPool` 加性新增 `boosterRemaining?` / `boosterCount?` / `boosterNextExpiresAt?`：网关在既有那一次 alive 遍历里，对 alive 的 COMMERCIAL 桶中 `sourceType === 'booster_pack'` 的行求和（微 Credits，÷1000 = Credits）、计数（一行 = 一个加油包）、并在这些 alive **限期**桶里选举最早到期时刻。**三者缺席 = 老网关或此刻没有加油包，都不可读成 0**（网关一行都认不出时三个键一起不下发，绝不写 0）；`boosterNextExpiresAt` 另可因「加油包全是永久桶」而单独缺席，此时前两个字段仍在场。加油包是「加总额度」的产品动作，与只清 5 小时 / 7 天窗口、对额度池零交互的重置卡是两笔账。纯类型面追加，无运行时改动。 |
+| 2.19.5 | 稳定版 | **流内重试提示透出 + 流式可选项（2026-09-19）**。`StreamError` 加性新增 `serverRetryable`（帧上 `retryable` **原值**，不与 `requestDisposition` 合取 —— 合取会把「服务端明说可重试」与「服务端没说」压成同一个 `false`）与 `retryAfterSecs`（只收有限非负数，非法值一律 `undefined`）；加性导出结构判据 `isStreamError()`（worker / `vm` / 二次打包下 `instanceof` 静默为假）；`chatStream` / `chatMessagesStream` 新增**末位**可选实参 `ChatStreamOptions`（`requestTimeoutMs` 总时长安全网、`onResponseHeaders` 在 `resp.ok` 判断前交出响应头，用于读 `X-Acosmi-Stream-Keepalive` 等流控提示）。全部追加式；不传 `requestTimeoutMs` 时**不武装任何计时器**，流式链路行为与 2.19.4 逐字一致。另修 `FileTokenStore.withLock` 在 Windows delete-pending 窗口把 `EPERM` / `EBUSY` 当成致命错误（NT 在 `unlink` 之后、最后一个句柄关闭之前抛的不是 `EEXIST`，于是同一把锁上的一次正常交接被报成永久失败）；这两个码现在按「锁被占」退避重试并跳过 stale 检测，`EACCES` 刻意不收，非 Windows 平台控制流逐字节不变。 |
+| 2.19.4 | 稳定版 | **OpenAI 线流式 usage 尾帧回收 + 子路径入口修复 + 一批 wire 容错**。`stream_options.include_usage` 下上游在 `finish_reason` 帧之后才发 `{"choices":[],"usage":{...}}`，转换器此前丢弃一切不带 `choices` 的帧、且已在 `finish_reason` 帧上发出不带 usage 的 `message_delta` 与 `message_stop`，于是 OpenAI 线经 `chatMessagesStream` 的回合从来没有带过 usage、消费方一律记成 0；现在任何帧上的 usage 都被记录（后帧覆盖前帧）并写进 `message_stop` 前紧邻的那条 `message_delta`。内容块仍在 `finish_reason` 帧关闭，但尚未见到 usage 时 `message_delta` / `message_stop` 会等「带 usage 的帧 / `data: [DONE]` / body 结束」三者中最先到的一个，新增 `OpenAIStreamConverter.flush()` 在流末补发这次延迟收口（绝不为从未给过 `finish_reason` 的流伪造收口，也没有任何路径会发两次 `message_stop`）。流式 usage 映射与非流式逐字相同（`prompt_tokens`→`input_tokens`、`completion_tokens`→`output_tokens`），缓存 token 与 reasoning token 明细既不映射也不冲抵，缺失或非有限数一律省略而不是写 0。修复 `@acosmi/sdk-ts/adapters/openai` 与 `@acosmi/sdk-ts/adapters/anthropic` 两个子路径入口**加载即抛**（Node ESM / CJS 下 `OpenAIAdapter is not a constructor`、Bun 下 `undefined is not a constructor`）：`ProviderFormat` / `ProviderAdapter` 迁进不 import 任何 adapter 实现的叶子模块，各入口导出名一字不变；`test:pack` 现在会在各自全新的 Node 进程里对每个声明了 `import` 或 `require` 条件的 `exports` 子路径真加载一次。另容忍不带 `delta` 的流 `choice`、不带 `choices` 的非流式响应、不带 `usage` 的非流式响应（分别按空 delta / 空数组 / 0 处理，不再抛错，其余字段照常转换）；修正 text 先于 `reasoning_content` 到达时两个 `content_block_start` 都落在 index 0 的块序错乱。类型面加性新增 `WindowLimitStatus.fiveHourSoftContinuing?`、`WindowLimitStatus.inflightHeldCredits?`、`QuotaSummary.subscriptionPool?` —— 三者缺席都表示「旧网关没播报」，不得读成 `false` / `0`。 |
+| 2.19.3 | 稳定版 | **OpenAI 线网关流失败帧不再把自己撞崩**。网关用 `event: failed` 发结构化错误帧，而 `chatMessagesStream` 的 OpenAI 分支捕获了 SSE 事件名却从不读它，错误帧于是被送进 OpenAI chunk 转换器、死在 `chunk.choices.length` 上 —— 真实上游原因被一个无关的 TypeError 顶掉。该分支现在把 `failed` / `error` 帧交给既有的 `parseStreamError`，与 `chatStreamWithUsage` 早已在做的完全一致；`OpenAIStreamChunk.choices` 同版改为可选（类型声明必填而 wire 确实会省，正是那个 TypeError 的来处）。Anthropic 线零行为变化，请求构造零变化。 |
+| 2.19.2 | 稳定版 | **思考档位透传补全**。目录支持的 low / medium / xhigh / max 四档在两个 chat adapter 上原样保留；显式「关闭思考」的请求被真正投递给 OpenAI 兼容网关；2.19.1 的凭据与请求 ID 行为保持不变。 |
+| 2.19.1 | 稳定版 | **认证生命周期与上游错误归属修复（2026-09-08）**。新增显式 `credentialMode: 'versioned'`，通过调用方提供的 `VersionedCredentialStore` 原子读写凭据，多进程同时刷新共用同一份持久状态、刷新结果不确定时要求重新登录；新增 `credentialRequestOwner` 把请求绑定到构造时的存储实例、登录会话与已验证身份（已退出或被替换的客户端不能借用另一个账号的凭据，WebSocket 票据与晚到事件遵守同一归属）；新增 `logoutCredential(signal?, expected?)`，本地提交结果与远端吊销结果分开；新增显式 `credentialMode: 'external'` 与 `accessTokenProvider`。HTTP 401 只有在完整错误合同明确归属用户访问凭据失效、且请求未被接收时才触发一次刷新重试，提供商拒绝 / 已接收请求 / 缺失合同的错误不再被误当成登录过期。默认仍为 `legacy` 模式。 |
+| 2.19.0 | 稳定版 | **网关消费请求 ID 透出（2026-09-01）**。网关把 `consumeRequestID`（即 `managed_model_usage_logs.request_id`）放进 `X-Acosmi-Request-Id` 响应头；加性导出 `GATEWAY_REQUEST_ID_HEADER` 与 `GatewayRequestIDCallback`，`chatMessagesStream` / `chatStream` 新增第 5 个可选实参、`chatMessages` / `chat` 新增第 4 个可选实参。响应头在首字节之前到达，因此覆盖流中段中断 / 零事件 / HTTP 错误全部形态。旧网关下回调零触发、绝不合成占位值，流照常出。不传回调时行为逐字节不变。 |
 | 2.18.0 | 稳定版 | **`ManagedModel.thinking_levels` 类型面对齐（2026-08-29）**。加性新增可选字段 `thinking_levels?: string[]`：网关下发的升序思考档位 id 列表（`'off'`/`'high'`/`'max'` 的子集，按「admin 声明 ∩ wire 层真投递」派生）。`listModels` 原样透传，无归一化、无新方法、公开签名零变化。`[]` = 该模型无思考档；`undefined` = 旧网关未播报，调用方按"未知"处理，严禁按模型名推档。 |
 | 2.17.0 | 稳定版 | **桌面 loopback OAuth state 全路径闸 + 端口确定性关闭（2026-08-15）**。`/callback` 一切形态（成功 / OAuth error / 畸形）先验 `state` 且必须恰好一个并严格等值；缺失 / 重复（含重复的正确值）/ 错值一律 `state_mismatch` 拒绝且不再被误结算为 `auth_denied`；错误信息只描述形态，不回显 code / state / token / 完整 callback query。`finally` 补 `closeIdleConnections()`（Node 18 上 `close()` 不关残留 idle keep-alive）。用户真拒绝（OAuth error + 正确 state）语义保留为 `auth_denied`。公开 API 签名零变化。 |
 | 2.16.0 | 稳定版 | **chat 超时预算真正下传 + 流式活性回调（2026-08-06）**。`chat` / `chatMessagesAnthropic` / `chatMessagesOpenAI` / `generateVideo` 此前漏传 `doJSONFullRaw` 的第 5 实参，内层 **30 秒**默认值恒先于外层 11 分钟预算触发 —— v1.6.0 那次"调整为 11min"一天都没生效过（生产实证：单日 29 条 latency≈30 000 ms 的 499，横跨 4 厂商 5 模型，受害最重的是默认主循环模型）。加性导出 `CHAT_REQUEST_TIMEOUT_MS`；`chatStream` / `chatMessagesStream` 新增第 4 个可选实参 `onUpstreamActivity`，让被 `isSSECommentLine` 吞掉的保活注释行（以及 OpenAI 格式下零事件的 data 行）能抵达消费方的空闲看门狗。不传回调时行为逐字节不变。 |

package/dist/browser/index.mjs

@@ -148,6 +148,14 @@ var init_types = __esm({
 });
 
 // src/shared/errors.ts
+function finiteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function isStreamError(err) {
+  if (err == null || typeof err !== "object") return false;
+  const e = err;
+  return e.name === "StreamError" && typeof e.errorCode === "string";
+}
 function nullableID(value) {
   return value === null || typeof value === "string";
 }
@@ -357,8 +365,23 @@ var init_errors = __esm({
       userMessage;
       /** gateway 原始 error 字符串 */
       rawError;
-      /** 客户端是否值得重试 */
+      /** 客户端是否值得重试 (= 服务端 `retryable` **且** `requestDisposition === 'not_accepted'`) */
       retryable;
+      /**
+       * 服务端在帧上声明的 `retryable` **原值** (2.19.5 起) —— 不与 requestDisposition 合取,
+       * 缺席即 undefined。
+       *
+       * 为什么要并列存一份: 上面的 `retryable` 是两个判据的合取, 网关的流内错误帧并不总是
+       * 下发 `requestDisposition`, 于是"服务端明说可重试"会被合取成 false —— 两端各自正确,
+       * 合起来恒否。消费方要区分**「服务端明说不可重试」**(false, 一票否决) 与**「服务端没说」**
+       * (undefined, 回落到自己的本地分类表) 时, 只能读这个原值; 读 `retryable` 两种情形不可分。
+       */
+      serverRetryable;
+      /**
+       * 服务端建议的等待秒数 (2.19.5 起)。**有限非负数**才收, 其余 (null / 负数 /
+       * NaN / Infinity / 非数字) 一律 undefined —— 宁可不给, 绝不编造等待时间。
+       */
+      retryAfterSecs;
       errorContractVersion;
       faultDomain;
       requestDisposition;
@@ -381,6 +404,8 @@ var init_errors = __esm({
         this.userMessage = userMessage;
         this.rawError = rawError;
         this.retryable = retryable;
+        this.serverRetryable = opts.retryable;
+        this.retryAfterSecs = finiteNonNegative(opts.retryAfterSecs);
         this.errorContractVersion = opts.errorContractVersion;
         this.faultDomain = opts.faultDomain;
         this.requestDisposition = opts.requestDisposition;
@@ -2195,7 +2220,10 @@ var FileTokenStore = class {
   /**
    * 跨进程临界区. 用 sidecar `<path>.lock` 文件 + O_EXCL 创建语义实现互斥:
    *   - 创建成功 = 持有锁; 写入 pid+timestamp 便于诊断
-   *   - 创建失败 (EEXIST) = 别的进程持锁, backoff 重试
+   *   - 创建失败 (EEXIST) = 别的进程持锁, stale 检测后 backoff 重试
+   *   - 创建失败 (Windows 的 EPERM / EBUSY) = 前一持有者的 unlink 处于 delete-pending,
+   *     同属争用; 跳过 stale 检测直接 backoff 重试 (见 catch 内注释)。EACCES 不在其中 —
+   *     它是真权限错误, 立即抛
    *   - 锁文件 mtime > staleMs = 进程崩溃残留, unlink 后重试
    *   - acquireTimeoutMs 超时 = 抛错 (caller 应作为 transient error 处理, 上层 retry)
    *
@@ -2224,25 +2252,29 @@ ${Date.now()}
         release = async () => {
           try {
             await fs.unlink(lockPath);
-          } catch {
+          } catch (e) {
+            warnLockCleanupFailed("release", lockPath, e);
           }
         };
         break;
       } catch (e) {
-        if (!isAlreadyExistsError(e)) throw e;
-        let stale = false;
-        try {
-          const st = await fs.stat(lockPath);
-          if (Date.now() - st.mtimeMs > fileLockDefaults.staleMs) stale = true;
-        } catch {
-          continue;
-        }
-        if (stale) {
+        if (!isLockContendedError(e)) throw e;
+        if (!isWindowsLockBusyError(e)) {
+          let stale = false;
           try {
-            await fs.unlink(lockPath);
+            const st = await fs.stat(lockPath);
+            if (Date.now() - st.mtimeMs > fileLockDefaults.staleMs) stale = true;
           } catch {
+            continue;
+          }
+          if (stale) {
+            try {
+              await fs.unlink(lockPath);
+            } catch (e2) {
+              warnLockCleanupFailed("stale-break", lockPath, e2);
+            }
+            continue;
           }
-          continue;
         }
         if (Date.now() - startMs > fileLockDefaults.acquireTimeoutMs) {
           throw new Error(
@@ -2342,12 +2374,27 @@ ${Date.now()}
     });
   }
 };
+function warnLockCleanupFailed(stage, lockPath, e) {
+  if (isNotExistError(e)) return;
+  console.warn(
+    `[acosmi-sdk] warning: unlink token file lock (${stage}) failed: ${lockPath}: ${e instanceof Error ? e.message : String(e)}`
+  );
+}
 function isNotExistError(e) {
   if (typeof e === "object" && e !== null && "code" in e) {
     return e.code === "ENOENT";
   }
   return false;
 }
+function isWindowsLockBusyError(e) {
+  if (typeof process === "undefined" || process.platform !== "win32") return false;
+  if (typeof e !== "object" || e === null || !("code" in e)) return false;
+  const code = e.code;
+  return code === "EPERM" || code === "EBUSY";
+}
+function isLockContendedError(e) {
+  return isAlreadyExistsError(e) || isWindowsLockBusyError(e);
+}
 function isAlreadyExistsError(e) {
   if (typeof e === "object" && e !== null && "code" in e) {
     return e.code === "EEXIST";
@@ -2941,7 +2988,7 @@ function parseStreamError(data) {
   let code = payload.errorCode ?? "";
   const stage = payload.stage ?? "";
   let message = payload.message ?? "";
-  const retryable = payload.retryable ?? false;
+  const retryable = payload.retryable;
   let rawError = "";
   if (payload.error != null) {
     if (typeof payload.error === "string") {
@@ -2959,6 +3006,7 @@ function parseStreamError(data) {
     message,
     rawError,
     retryable,
+    retryAfterSecs: payload.retryAfterSecs,
     errorContractVersion: payload.errorContractVersion,
     faultDomain: payload.faultDomain,
     requestDisposition: payload.requestDisposition,
@@ -3169,6 +3217,25 @@ function notifyGatewayRequestID(cb, headers) {
   } catch {
   }
 }
+function notifyResponseHeaders(cb, headers) {
+  if (!cb) return;
+  try {
+    cb(headers);
+  } catch {
+  }
+}
+function armStreamRequestTimeout(opts, parent) {
+  const ms = opts?.requestTimeoutMs;
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms <= 0) return void 0;
+  return withRequestTimeout(ms, parent);
+}
+async function* disposeTimeoutWhenSettled(inner, ctl) {
+  try {
+    yield* inner;
+  } finally {
+    ctl.dispose();
+  }
+}
 var DEFAULT_API_TIMEOUT_MS = 6e4;
 function newDeferred() {
   let resolve;
@@ -4302,10 +4369,23 @@ var Client = class _Client {
    *
    * @param onUpstreamActivity 见 {@link UpstreamActivityCallback}
    * @param onGatewayRequestID 见 {@link GatewayRequestIDCallback}
+   * @param opts 见 {@link ChatStreamOptions} (2.19.5 起)
    */
-  chatStream(modelID, req, signal, onUpstreamActivity, onGatewayRequestID) {
+  chatStream(modelID, req, signal, onUpstreamActivity, onGatewayRequestID, opts) {
     return {
-      [Symbol.asyncIterator]: () => this.chatStreamGen(modelID, req, signal, false, onUpstreamActivity, onGatewayRequestID)
+      [Symbol.asyncIterator]: () => {
+        const ctl = armStreamRequestTimeout(opts, signal);
+        const inner = this.chatStreamGen(
+          modelID,
+          req,
+          ctl?.signal ?? signal,
+          false,
+          onUpstreamActivity,
+          onGatewayRequestID,
+          opts?.onResponseHeaders
+        );
+        return ctl ? disposeTimeoutWhenSettled(inner, ctl) : inner;
+      }
     };
   }
   /**
@@ -4315,13 +4395,26 @@ var Client = class _Client {
    *
    * @param onUpstreamActivity 见 {@link UpstreamActivityCallback}
    * @param onGatewayRequestID 见 {@link GatewayRequestIDCallback}
+   * @param opts 见 {@link ChatStreamOptions} (2.19.5 起)
    */
-  chatMessagesStream(modelID, req, signal, onUpstreamActivity, onGatewayRequestID) {
+  chatMessagesStream(modelID, req, signal, onUpstreamActivity, onGatewayRequestID, opts) {
     return {
-      [Symbol.asyncIterator]: () => this.chatMessagesStreamGen(modelID, req, signal, false, onUpstreamActivity, onGatewayRequestID)
+      [Symbol.asyncIterator]: () => {
+        const ctl = armStreamRequestTimeout(opts, signal);
+        const inner = this.chatMessagesStreamGen(
+          modelID,
+          req,
+          ctl?.signal ?? signal,
+          false,
+          onUpstreamActivity,
+          onGatewayRequestID,
+          opts?.onResponseHeaders
+        );
+        return ctl ? disposeTimeoutWhenSettled(inner, ctl) : inner;
+      }
     };
   }
-  async *chatStreamGen(modelID, req, signal, retried, onUpstreamActivity, onGatewayRequestID) {
+  async *chatStreamGen(modelID, req, signal, retried, onUpstreamActivity, onGatewayRequestID, onResponseHeaders) {
     const r = { ...req, stream: true };
     const { body, adapter } = await this.buildChatRequest(modelID, r, signal);
     const token = await this.ensureToken(signal);
@@ -4353,10 +4446,11 @@ var Client = class _Client {
           `stream: unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
         );
       }
-      yield* this.chatStreamGen(modelID, req, signal, true, onUpstreamActivity, onGatewayRequestID);
+      yield* this.chatStreamGen(modelID, req, signal, true, onUpstreamActivity, onGatewayRequestID, onResponseHeaders);
       return;
     }
     notifyGatewayRequestID(onGatewayRequestID, resp.headers);
+    notifyResponseHeaders(onResponseHeaders, resp.headers);
     if (!resp.ok) {
       const bodyBytes = await readLimited(resp.body, maxErrorBodySize);
       throw parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
@@ -4391,7 +4485,7 @@ var Client = class _Client {
       }
     }
   }
-  async *chatMessagesStreamGen(modelID, req, signal, retried, onUpstreamActivity, onGatewayRequestID) {
+  async *chatMessagesStreamGen(modelID, req, signal, retried, onUpstreamActivity, onGatewayRequestID, onResponseHeaders) {
     const r = { ...req, stream: true };
     const { body, adapter } = await this.buildChatRequest(modelID, r, signal);
     const token = await this.ensureToken(signal);
@@ -4423,10 +4517,11 @@ var Client = class _Client {
           `messages stream: unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
         );
       }
-      yield* this.chatMessagesStreamGen(modelID, req, signal, true, onUpstreamActivity, onGatewayRequestID);
+      yield* this.chatMessagesStreamGen(modelID, req, signal, true, onUpstreamActivity, onGatewayRequestID, onResponseHeaders);
       return;
     }
     notifyGatewayRequestID(onGatewayRequestID, resp.headers);
+    notifyResponseHeaders(onResponseHeaders, resp.headers);
     if (!resp.ok) {
       const bodyBytes = await readLimited(resp.body, maxErrorBodySize);
       throw parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
@@ -8962,6 +9057,6 @@ function brandCredential(c) {
   return c;
 }
 
-export { AGENT_RUN_META_TITLE, AGENT_RUN_META_WORKSPACE, ALL_INTEGRATION_STATUS, ALL_PLATFORMS, ALL_REGIONS, AgentRunStreamError, AgentRunsClient, AnthropicAdapter, AudienceEnum, BillingModeEnum, BucketClassCommercial, BucketClassGeneric, BusinessError, CHAT_REQUEST_TIMEOUT_MS, ChatBridgeClient, Client, ComplianceClient, CompliancePollError, CrabCodeByokClient, DEFAULT_API_TIMEOUT_MS, DEFAULT_GATEWAY_BASE_URL, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GATEWAY_REQUEST_ID_HEADER, HTTPError, IdempotencyKeyHeader, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OAuthTokenEndpointError, OpenAIAdapter, OrderTerminalError, ProductFamilyEnum, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, RegionScopeEnum, ScopeAI, ScopeAccount, ScopeAgentAccessManage, ScopeChatBridge, ScopeChatBridgeRead, ScopeChatBridgeRotate, ScopeChatBridgeWrite, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeRemoteControl, ScopeRemoteControlAgentRun, ScopeRemoteControlPermissionResponse, ScopeRemoteControlSessionControl, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingLow, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, agentAccessScopes, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, asCredentialRef, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, chatBridgeScopes, classifyComplianceError, classifySourcesEvent, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, getWindowLimitStreamDetails, isBillingConfirmable, isChannelInboundEvent, isComplianceBusinessError, isComplianceTerminalError, isContinuableWindowLimitError, isIntegrationStatus, isInvalidGrantError, isPlatform, isRegion, isSSECommentLine, isSSLError, isTerminalRemoteEvent, isUserAccessTokenRejected, isValidTokenSet, isWindowLimitError, isWindowLimitStreamError, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, readGatewayErrorContract, refreshToken, register, registerWebOAuthClient, remoteControlScopes, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
+export { AGENT_RUN_META_TITLE, AGENT_RUN_META_WORKSPACE, ALL_INTEGRATION_STATUS, ALL_PLATFORMS, ALL_REGIONS, AgentRunStreamError, AgentRunsClient, AnthropicAdapter, AudienceEnum, BillingModeEnum, BucketClassCommercial, BucketClassGeneric, BusinessError, CHAT_REQUEST_TIMEOUT_MS, ChatBridgeClient, Client, ComplianceClient, CompliancePollError, CrabCodeByokClient, DEFAULT_API_TIMEOUT_MS, DEFAULT_GATEWAY_BASE_URL, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GATEWAY_REQUEST_ID_HEADER, HTTPError, IdempotencyKeyHeader, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OAuthTokenEndpointError, OpenAIAdapter, OrderTerminalError, ProductFamilyEnum, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, RegionScopeEnum, ScopeAI, ScopeAccount, ScopeAgentAccessManage, ScopeChatBridge, ScopeChatBridgeRead, ScopeChatBridgeRotate, ScopeChatBridgeWrite, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeRemoteControl, ScopeRemoteControlAgentRun, ScopeRemoteControlPermissionResponse, ScopeRemoteControlSessionControl, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingLow, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, agentAccessScopes, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, asCredentialRef, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, chatBridgeScopes, classifyComplianceError, classifySourcesEvent, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, getWindowLimitStreamDetails, isBillingConfirmable, isChannelInboundEvent, isComplianceBusinessError, isComplianceTerminalError, isContinuableWindowLimitError, isIntegrationStatus, isInvalidGrantError, isPlatform, isRegion, isSSECommentLine, isSSLError, isStreamError, isTerminalRemoteEvent, isUserAccessTokenRejected, isValidTokenSet, isWindowLimitError, isWindowLimitStreamError, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, readGatewayErrorContract, refreshToken, register, registerWebOAuthClient, remoteControlScopes, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map