@acosmi/sdk-ts 2.15.0 → 2.17.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to `@acosmi/sdk-ts` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.17.0] - 2026-08-15 — 桌面 loopback OAuth state 全路径闸 + 端口确定性关闭
+
+**回环监听在整个登录期间对本机任意进程开放，state 是唯一的门。** 2.16.0 及更早版本的桌面 loopback `authorize` 不生成也不校验 OAuth `state`（`af2daa0b` 已在源码补上核心校验，但从未发版）；且校验只覆盖"带 code"的回调 —— 携带 OAuth error 的回调**绕过 state 直接把登录结算成"用户已拒绝"**，本机恶意进程不猜任何秘密就能打断/塑形一次等待中的登录；重复 `state` 参数取首值即可蒙混（`?code=攻击者的码&state=<正确值>&state=x` 在旧实现下**成功登录到攻击者会话**）。本版把 state 校验提到 `/callback` 所有形态之前，并收紧为"恰好一个"。
+
+### Fixed
+
+- **`/callback` 全形态 state 先行校验** —— 成功回调、OAuth error 回调、畸形回调一律先验 state 再消费 code / 结算 denied。缺失、重复（含重复的正确值）、错值均以稳定错误码 `state_mismatch` 拒绝本次登录、返回安全失败页并关闭 listener；错误信息只描述形态，不回显 code / state / token / 完整 callback query。
+- **"恰好一个 state"** —— `searchParams.getAll('state').length === 1` 且严格等值；重复参数不再因 `get()` 取首值而通过。
+- **端口确定性关闭** —— `finally` 里在 `server.close()` 后补 `closeIdleConnections?.()`：Node 18 上 `close()` 不关浏览器残留的 idle keep-alive 连接，端口会滞留到对端松手；现在每条终止路径（成功 / 各类 state 失败 / 用户拒绝 / 超时 / 取消 / 浏览器打开失败）都以端口完全关闭收尾。
+
+### 回归闸门
+
+- `test/auth/desktop-loopback-state.test.ts` —— 十路终止矩阵：成功、缺失 state、错误 state、重复 state（异值与同值）、恶意先到回调后合法回调不能复活、用户拒绝（正确 state + OAuth error → `auth_denied`）、超时、取消（pre-aborted signal）、浏览器打开失败后手动回调仍可完成；每条路径断言**只结算一次**（事件流恰一条 error / 结果不可翻转）且**新连接最终被拒**（listener teardown）。对 2.16.0 实测：4 条缺口用例全红（其中"重复 state 首值正确"在旧实现下以攻击者 code 成功 resolve），6 条保行为用例双版本皆绿。
+
+## [2.16.0] - 2026-08-06 — chat 超时预算真正下传 + 流式活性回调
+
+**一个预算只有在被传下去时才存在。** `chat` / `chatMessagesAnthropic` / `chatMessagesOpenAI` 三条推理链路都用 `withRequestTimeout(CHAT_REQUEST_TIMEOUT_MS)` 建了 11 分钟的外层预算，却只把 `ctl.signal` 传给 `doJSONFullRaw` —— 后者的 `timeoutMs` 形参有 **30 秒**默认值，会**另建**一个计时器并恒先于外层触发。于是 v1.6.0 那次"调整为 11min 以容纳 DeepSeek 保活窗口"的改动，**一天都没生效过**，而它上方的注释还在声称它已生效。
+
+这不是理论缺陷。生产网关单日 **29 条** latency 落在 27 831–30 046 ms 的 499（客户端主动断开），横跨 **4 个厂商 5 个模型**；受害最重的恰是各客户端的默认主循环模型 —— 也正是唯一拿到网关 11 分钟长首字节预算的那个 provider。它拿着最宽的服务端预算，死得最惨，因为杀它的计时器在客户端。真实用户主动取消的 latency 是随机的（1 294 / 1 575 ms），与这一串高度聚集的 30 秒在同一张表里一眼可分。
+
+### Fixed
+
+- **`chat` / `chatMessagesAnthropic` / `chatMessagesOpenAI` / `generateVideo` 显式下传 `CHAT_REQUEST_TIMEOUT_MS`** —— 与同文件 `embeddings` / `rerank` / `generateImage` 三个一直正确的兄弟调用对齐。`generateVideo` 此前连外层预算都没有，同样被钉在 30 秒；现按其直接兄弟 `generateImage` 的形状修复（单次网络操作，不另加外层 controller）。
+- **`Client.chat` 上方那条 v1.6.0 注释重写** —— 它描述的是一个从未交付的行为。注释与实测冲突时以实测为准，且必须同 PR 修掉；留着它就是给下一个读代码的人埋雷。
+
+### Added
+
+- **`CHAT_REQUEST_TIMEOUT_MS` 导出** —— 供回归闸门按**符号**断言，避免测试抄字面量后与真源各自漂移（抄件断言恒绿 = 零覆盖）。消费方要更短的预算传 `signal` 即可，`withRequestTimeout` 取二者先到者。
+- **`UpstreamActivityCallback` + `chatStream` / `chatMessagesStream` 的第 4 个可选实参 `onUpstreamActivity`** —— 消费方的流空闲看门狗判据是"多久没收到事件"，但 SSE 上有两类**有字节、无事件**的情形对它完全失明：① 上游/网关推理前发的保活注释行被 `isSSECommentLine` 吞掉；② OpenAI 格式下 converter 对某些 data 行返回零事件。**心跳只有在抵达做判决的那一层时才叫心跳** —— 网关补心跳而 SDK 吞掉，等于没补。本回调对每一条 SSE 行触发一次（含注释行），早于任何过滤与解析；回调抛错被吞掉且不中断流（旁路信号不该有能力杀死主链路）。不传时行为逐字节不变。
+
+### 回归闸门
+
+- `test/chat-timeout-budget.test.ts` —— 四条链路的**行为**断言（活过 30 秒、死在 `CHAT_REQUEST_TIMEOUT_MS`），外加一条 **default-deny 结构闸门**：`doJSONFullRaw` 的每个调用点必须显式传预算，控制面端点要豁免须进具名 allowlist 并写明理由。附负向对照，防扫描器坏掉后闸门恒绿。
+- `test/stream-upstream-activity.test.ts` —— 判据是"第一个事件到达前已有 ≥3 次活性"，只可能由 3 条保活注释行产生；刻意不用"活性次数 > 事件数"，那条在注释行根本没进循环时会假绿。
+
 ## [2.15.0] - 2026-08-02 — sources 四态分类与零结果契约
 
 ### Added

package/README.md

@@ -290,6 +290,30 @@ for await (const ev of stream) {
 
 `chatStreamWithUsage()` 返回带 usage/error/sources 标签的 AsyncIterable，便于聚合统计（详见 `src/core/client.ts`）。
 
+### 上游活性回调 `onUpstreamActivity`（v2.16+）
+
+如果你的集成层自带**流空闲看门狗**（"多久没收到事件就判定连接死了"），必须接这个回调，否则看门狗会误杀健康连接。
+
+SSE 上有两类**有字节、无事件**的情形，看门狗对它们完全失明：
+
+1. 上游（如 DeepSeek）与网关在开始推理前发的保活注释行 `: keep-alive` —— 按 SSE 规范它们不构成事件，被 `isSSECommentLine` 跳过；
+2. OpenAI 格式下 converter 对某些 data 行返回零事件。
+
+两种情形连接都健康、字节都在流动。**心跳只有在抵达做判决的那一层时才叫心跳** —— 网关补了心跳而 SDK 吞掉，等于没补。
+
+```ts
+let lastActivity = Date.now();
+
+const stream = client.chatMessagesStream(
+  modelId,
+  { messages, max_tokens: 4096 },
+  abortSignal,
+  () => { lastActivity = Date.now(); },   // ← 每条 SSE 行触发一次，含注释行
+);
+```
+
+语义是「链路刚刚有动静」，不是「来了一个事件」；对每条 SSE 行触发一次，早于任何过滤与解析。回调抛出的错误会被吞掉且不中断流（旁路信号不该有能力杀死主链路）。不传时行为逐字节不变。
+
 ### Sources SSE 四态分类（v2.15+）
 
 `sources: []` 是检索成功但没有可展示引用的合法零结果，不是传输损坏。需要精确区分状态的新 consumer 使用加性接口 `classifySourcesEvent()`：
@@ -1100,7 +1124,8 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 2.15.0 | **当前版本** | **sources 四态分类与零结果契约（2026-08-02）**。加性新增 `classifySourcesEvent`、`SourcesEventParseResult` 与稳定 issue code，区分非 sources、合法空结果、有效结果和结构损坏；未知额外字段继续兼容。既有 `parseSourcesEvent` 的返回形状、宽松解析和 `null` 条件保持不变。 |
+| 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 行）能抵达消费方的空闲看门狗。不传回调时行为逐字节不变。 |
+| 2.15.0 | 稳定版 | **sources 四态分类与零结果契约（2026-08-02）**。加性新增 `classifySourcesEvent`、`SourcesEventParseResult` 与稳定 issue code，区分非 sources、合法空结果、有效结果和结构损坏；未知额外字段继续兼容。既有 `parseSourcesEvent` 的返回形状、宽松解析和 `null` 条件保持不变。 |
 | 2.14.0 | 稳定版 | **托管模型 input modalities 开放值域（2026-08-02）**。snake_case/camelCase 归一规则对称，数据字段允许未来新增标签；查询 API 仍保留已知标签自动补全。现网 camelCase 路径行为不变。 |
 | 2.13.0 | 稳定版 | **邀请奖励窗口重置券（2026-08-01）**。加性新增窗口重置券总览与幂等核销 API，不改变既有 token、额度和会员调用。 |
 | 2.12.0 | 稳定版 | **5 小时窗口软限额（2026-07-11）**。加性透传 `windowOverridable`、继续开关与结构化状态；老网关缺字段时按硬等待处理。 |
@@ -1123,7 +1148,7 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 | 1.8.1 | 稳定版 | **enterprise 企业席位域落地（商品化总规划 P6a）**。新增 `client.enterprise.*`：`listMyEnterprises` / `getEnterprise` / `inviteMember` / `listEnterpriseMembers` / `listOrgSubscriptions` / `listSeats` / `assignSeat` / `revokeSeat` / `getOrgConsumeReport`。OWNER/ADMIN 权限下席位月度变更 ≤ 3 次（超出返 41xxx 业务码）；订阅 + 席位 + 用量报表三视图齐备。 |
 | 1.8.0 | 稳定版 | **casehall 法律案件咨询域落地（商品化总规划 P5 方案 B）**。新增 `client.casehall.*`：`listLawyers` / `getLawyer` / `submitCaseLead` / `listMyCaseLeads` / `getMyCases` / `bookConsultation` / `listMyConsultations` / `listMyLegalOrders` / `listLegalSKUs`。律师库公开端点（VERIFIED + ACTIVE，PII L3 已脱敏）+ 案件线索 + 咨询 + 5 LEGAL_SERVICE SKU；admin 板块 9 模块不在 SDK 边界。 |
 | 1.7.0 | 稳定版 | **subscription + pricing + products 三域落地（商品化总规划 P1-P4）**。`subscription`：`listPlans` / `listUserSubscriptions`（订阅档位 + 用户订阅）。`pricing`：`getPricingConfig` / `quoteCompliance`（公开业务参数 + csign 合规 SKU 报价）。`products`：`getProductBySlug` / `listProductsByFamily` / `listComplianceSkus` / `listPublicModels`（商品中心 productFamily / audience / billingMode 索引）。 |
-| 1.6.0 | 稳定版 | `ChatRequest.endUserId` 业务侧终端用户稳定标识，跨 provider 通用语义；SDK 自动按 wire-format 注入（OpenAI 顶层 `user_id` / Anthropic `metadata.user_id`）；不传时网关从认证身份 HMAC-SHA256 自动派生 32 字符 id。`validateEndUserId(s)` helper 校验 PII / 长度 / 字符集。SSE keep-alive + 11 分钟超时调优；网关侧命中三项隔离能力（内容安全 / KV-cache / 调度）。 |
+| 1.6.0 | 稳定版 | `ChatRequest.endUserId` 业务侧终端用户稳定标识，跨 provider 通用语义；SDK 自动按 wire-format 注入（OpenAI 顶层 `user_id` / Anthropic `metadata.user_id`）；不传时网关从认证身份 HMAC-SHA256 自动派生 32 字符 id。`validateEndUserId(s)` helper 校验 PII / 长度 / 字符集。SSE keep-alive 注释行显式跳过；网关侧命中三项隔离能力（内容安全 / KV-cache / 调度）。**订正（2026-08-06）**：本行原写"11 分钟超时调优"，实际该次改动只建了外层 `AbortController`、未下传给 `doJSONFullRaw`，内层 30 秒默认值始终生效 —— **该调优直到 2.16.0 才真正落地**。 |
 | 1.5.1 | 历史稳定版 | **Docs / examples / 源码注释全量复核与修订 — 无 API 变化**。修补 8 项漂移与遗漏：README API 总览补 25+ 漏列方法（Chat 内部方法、Auth 浏览器 Web OAuth 4 原语、Skills/Notifications/Entitlements/Packages 全量、WS `connect/disconnect/isConnected`）；重写 §"手动 OAuth" 段对齐 `auth.ts` 真实签名；§"双格式红线" + 三个 chat 示例 `maxTokens` → snake_case `max_tokens`；错误表补 `ModelNotFoundError`；§Agent Runs 补 13 类 stream event 完整表；新增 §`sanitize` 命名空间小节；`docs/compliance.md` 6 处 `Since v1.6/.../1.10` 统一为 `v1.5.0 (originally planned as ...)`；手册 §7 scope 数 12 → 15 + 新增 S1-S6 rollup 段；`examples/compliance-evidence-timestamp.ts` 补 `ScopeComplianceReportsWrite`（v1.3.2 漂移生产 401 隐患）；`examples/auth-oauth-flow.ts` + `examples/core-chat.ts` 注释对齐当前契约；`src/index.ts` + `src/browser.ts` + `src/auth/auth.ts` 注释从 Go-port 语义改为"TS 主实现 + Web OAuth 替代品"。`typecheck` / `lint` / `vitest`(214) / `build` / `test:pack` 全绿。 |
 | 1.5.0 | 稳定版 | 沉淀 `src/shared/` 跨域共享 DTO（`PageRequest`/`PageResult` 别名、`OperationId`/`OperationStatus`/`IdempotencyKeyHeader`、`RetryAdvice` 叠加层、`PrincipalRef`/`TenantRef`、`FeatureGateStatus`/`StepUpStatus`/`BillingPreflightResult`）。**同时全量 rollup compliance gateway S1-S6** 能力（原 1.6.0-1.11.0 roadmap，见 [CHANGELOG.md](./CHANGELOG.md)）：S1 6 个分页列表、S2 capabilities + operations 投影、S3 TSA 只读视图、S4 envelope 收尾 + void、S5 合同模板全生命周期 + 2 新 scope（`compliance:contract_template:{read,write}`）、S6 用印执行分页（`listSealUses`）。当前 compliance scope 总数 **15** 个（`complianceScopes()` 返回）。纯增量；8 个平台控制面占位命名空间仍待后端契约就绪后落地。 |
 | 1.4.2 | 稳定版 | `src/` 从扁平 36 文件按业务域重组为 per-domain 目录；公共导出符号集合、`exports`、`dist/` 路径一字未变（纯内部重组）。新增 TypeDoc API 文档。 |

package/dist/browser/index.mjs

@@ -1,7 +1,12 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -1322,6 +1327,7 @@ async function authorize(meta, clientID, scopes, opts = {}) {
   };
   const verifier = await generateCodeVerifier();
   const challenge = await codeChallenge(verifier);
+  const state = await generateState();
   const http = await import('http');
   const server = http.createServer();
   await new Promise((resolve, reject) => {
@@ -1337,6 +1343,8 @@ async function authorize(meta, clientID, scopes, opts = {}) {
     codeResolver = resolve;
     codeRejecter = reject;
   });
+  codePromise.catch(() => {
+  });
   server.on("request", (req, res) => {
     const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
     if (url.pathname !== "/callback") {
@@ -1344,6 +1352,16 @@ async function authorize(meta, clientID, scopes, opts = {}) {
       res.end();
       return;
     }
+    const states = url.searchParams.getAll("state");
+    const stateFailure = states.length === 0 ? "callback missing state" : states.length > 1 ? "callback carried multiple state values" : states[0] !== state ? "callback state does not match pending state" : null;
+    if (stateFailure !== null) {
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(
+        `<!DOCTYPE html><html><head><meta charset="utf-8"><title>\u6388\u6743\u5931\u8D25</title></head><body style="font-family:system-ui,sans-serif;text-align:center;padding:60px 20px"><h2>\u6388\u6743\u5931\u8D25</h2><p>\u56DE\u8C03\u6821\u9A8C\u672A\u901A\u8FC7, \u5DF2\u4E2D\u6B62\u767B\u5F55\u3002</p><p style="color:#888;font-size:14px">\u53EF\u4EE5\u5173\u95ED\u6B64\u7A97\u53E3\u3002</p></body></html>`
+      );
+      codeRejecter(new Error(`authorize: ${ErrStateMismatch}: ${stateFailure} (possible CSRF)`));
+      return;
+    }
     const code = url.searchParams.get("code");
     if (!code) {
       const errMsg = url.searchParams.get("error_description") || url.searchParams.get("error") || "";
@@ -1374,6 +1392,7 @@ async function authorize(meta, clientID, scopes, opts = {}) {
   authURL.searchParams.set("response_type", "code");
   authURL.searchParams.set("code_challenge", challenge);
   authURL.searchParams.set("code_challenge_method", "S256");
+  authURL.searchParams.set("state", state);
   if (scopes.length > 0) {
     authURL.searchParams.set("scope", scopes.join(" "));
   }
@@ -1411,7 +1430,9 @@ async function authorize(meta, clientID, scopes, opts = {}) {
     return { result: { code, redirectURI }, verifier };
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    if (msg.includes("denied")) {
+    if (msg.includes(ErrStateMismatch)) {
+      emit({ type: EventError, err_code: ErrStateMismatch, error: msg });
+    } else if (msg.includes("denied")) {
       emit({ type: EventError, err_code: ErrAuthDenied, error: msg });
     } else if (msg.includes("timed out")) {
       emit({ type: EventError, err_code: ErrTimeout, error: msg });
@@ -1422,6 +1443,7 @@ async function authorize(meta, clientID, scopes, opts = {}) {
   } finally {
     if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
     server.close();
+    server.closeIdleConnections?.();
   }
 }
 function htmlEscape(s) {
@@ -2288,6 +2310,13 @@ var ErrOAuthCORSBlocked = "oauth_cors_blocked";
 var ErrRefreshProxyFailed = "refresh_proxy_failed";
 var ErrTokenExpired = "token_expired";
 var CHAT_REQUEST_TIMEOUT_MS = 11 * 60 * 1e3;
+function notifyUpstreamActivity(cb) {
+  if (!cb) return;
+  try {
+    cb();
+  } catch {
+  }
+}
 var DEFAULT_API_TIMEOUT_MS = 6e4;
 function newDeferred() {
   let resolve;
@@ -3001,7 +3030,13 @@ var Client = class _Client {
     try {
       const { body, adapter } = await this.buildChatRequest(modelID, r, ctl.signal);
       const endpoint = `/managed-models/${encodeURIComponent(modelID)}${adapter.endpointSuffix()}`;
-      const { result, headers } = await this.doJSONFullRaw("POST", endpoint, body, ctl.signal);
+      const { result, headers } = await this.doJSONFullRaw(
+        "POST",
+        endpoint,
+        body,
+        ctl.signal,
+        CHAT_REQUEST_TIMEOUT_MS
+      );
       const resp = adapter.parseResponse(result);
       const v1 = headers.get("X-Token-Remaining");
       if (v1) {
@@ -3066,7 +3101,13 @@ var Client = class _Client {
    */
   async generateVideo(modelID, req, signal) {
     const endpoint = `/managed-models/${encodeURIComponent(modelID)}/videos/generations`;
-    const { result } = await this.doJSONFullRaw("POST", endpoint, req, signal);
+    const { result } = await this.doJSONFullRaw(
+      "POST",
+      endpoint,
+      req,
+      signal,
+      CHAT_REQUEST_TIMEOUT_MS
+    );
     return this.unwrapAPIResponse(result);
   }
   /**
@@ -3135,7 +3176,8 @@ var Client = class _Client {
         "POST",
         `/managed-models/${encodeURIComponent(modelID)}/anthropic`,
         data,
-        ctl.signal
+        ctl.signal,
+        CHAT_REQUEST_TIMEOUT_MS
       );
       const rawStr = new TextDecoder().decode(result);
       try {
@@ -3169,7 +3211,13 @@ var Client = class _Client {
       const body = adapter.buildRequestBody(caps, r);
       const data = JSON.stringify(body);
       const endpoint = `/managed-models/${encodeURIComponent(modelID)}${adapter.endpointSuffix()}`;
-      const { result } = await this.doJSONFullRaw("POST", endpoint, data, ctl.signal);
+      const { result } = await this.doJSONFullRaw(
+        "POST",
+        endpoint,
+        data,
+        ctl.signal,
+        CHAT_REQUEST_TIMEOUT_MS
+      );
       const { parseOpenAIResponseToAnthropic: parseOpenAIResponseToAnthropic2 } = await Promise.resolve().then(() => (init_openai(), openai_exports));
       return parseOpenAIResponseToAnthropic2(result);
     } finally {
@@ -3179,23 +3227,27 @@ var Client = class _Client {
   /**
    * 流式聊天 (SSE), 通过 async generator 返回事件
    * v0.5.0: 根据 adapter 路由端点
+   *
+   * @param onUpstreamActivity 见 {@link UpstreamActivityCallback}
    */
-  chatStream(modelID, req, signal) {
+  chatStream(modelID, req, signal, onUpstreamActivity) {
     return {
-      [Symbol.asyncIterator]: () => this.chatStreamGen(modelID, req, signal, false)
+      [Symbol.asyncIterator]: () => this.chatStreamGen(modelID, req, signal, false, onUpstreamActivity)
     };
   }
   /**
    * Anthropic 原生格式流式聊天 (SSE)
    * 调用 POST /managed-models/:id/anthropic, SSE 事件为 Anthropic 协议格式
    * 无 started/settled/failed 自定义事件, 无 data: [DONE], message_stop 为自然结束
+   *
+   * @param onUpstreamActivity 见 {@link UpstreamActivityCallback}
    */
-  chatMessagesStream(modelID, req, signal) {
+  chatMessagesStream(modelID, req, signal, onUpstreamActivity) {
     return {
-      [Symbol.asyncIterator]: () => this.chatMessagesStreamGen(modelID, req, signal, false)
+      [Symbol.asyncIterator]: () => this.chatMessagesStreamGen(modelID, req, signal, false, onUpstreamActivity)
     };
   }
-  async *chatStreamGen(modelID, req, signal, retried) {
+  async *chatStreamGen(modelID, req, signal, retried, onUpstreamActivity) {
     const r = { ...req, stream: true };
     const { body, adapter } = await this.buildChatRequest(modelID, r, signal);
     const token = await this.ensureToken(signal);
@@ -3228,7 +3280,7 @@ var Client = class _Client {
           `stream: unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
         );
       }
-      yield* this.chatStreamGen(modelID, req, signal, true);
+      yield* this.chatStreamGen(modelID, req, signal, true, onUpstreamActivity);
       return;
     }
     if (!resp.ok) {
@@ -3244,6 +3296,7 @@ var Client = class _Client {
     }
     let currentEvent = "";
     for await (const line of iterSSELines(resp.body)) {
+      notifyUpstreamActivity(onUpstreamActivity);
       if (isSSECommentLine(line)) continue;
       if (line.startsWith("event:")) {
         currentEvent = line.slice("event:".length).trim();
@@ -3264,7 +3317,7 @@ var Client = class _Client {
       }
     }
   }
-  async *chatMessagesStreamGen(modelID, req, signal, retried) {
+  async *chatMessagesStreamGen(modelID, req, signal, retried, onUpstreamActivity) {
     const r = { ...req, stream: true };
     const { body, adapter } = await this.buildChatRequest(modelID, r, signal);
     const token = await this.ensureToken(signal);
@@ -3297,7 +3350,7 @@ var Client = class _Client {
           `messages stream: unauthorized and refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
         );
       }
-      yield* this.chatMessagesStreamGen(modelID, req, signal, true);
+      yield* this.chatMessagesStreamGen(modelID, req, signal, true, onUpstreamActivity);
       return;
     }
     if (!resp.ok) {
@@ -3310,6 +3363,7 @@ var Client = class _Client {
     if (adapter.format() === 1 /* OpenAI */) {
       const converter = newOpenAIStreamConverter();
       for await (const line of iterSSELines(resp.body)) {
+        notifyUpstreamActivity(onUpstreamActivity);
         if (isSSECommentLine(line)) continue;
         if (line.startsWith("event:")) {
           line.slice("event:".length).trim();
@@ -3324,6 +3378,7 @@ var Client = class _Client {
       const blockTypeMap = /* @__PURE__ */ new Map();
       let currentEvent = "";
       for await (const line of iterSSELines(resp.body)) {
+        notifyUpstreamActivity(onUpstreamActivity);
         if (isSSECommentLine(line)) continue;
         if (line.startsWith("event:")) {
           currentEvent = line.slice("event:".length).trim();
@@ -3456,7 +3511,19 @@ var Client = class _Client {
       ctl.dispose();
     }
   }
-  /** doJSONFull 的 raw bytes 变体 (chat 用, 不立即 JSON.parse) */
+  /**
+   * doJSONFull 的 raw bytes 变体 (chat 用, 不立即 JSON.parse)
+   *
+   * ⚠️ 契约 (2026-08-06): `timeoutMs` 的 30s 默认值只适用于**控制面**端点 (列目录 /
+   * 查配额 / 取任务状态)。凡走**模型推理或生成**的端点 —— chat / anthropic /
+   * embeddings / rerank / images / videos —— 一律必须显式传入 `CHAT_REQUEST_TIMEOUT_MS`,
+   * 哪怕调用方已经用 `withRequestTimeout` 建了外层预算: 外层只约束 `signal`, 内层
+   * 会**另建**一个 `timeoutMs` 计时器, 30s 恒先于任何更长的外层预算触发。
+   *
+   * 这不是假设 —— 2026-08-06 事故里 chat 路径正因漏传本参数而被恒定钉死在 30s,
+   * 且上方 v1.6.0 的注释还声称它已是 11min。回归闸门见
+   * `tests/chat-timeout-budget.test.ts`。
+   */
   async doJSONFullRaw(method, path, body, signal, timeoutMs = 3e4) {
     return this.doJSONFullRawInternal(method, path, body, signal, false, timeoutMs);
   }
@@ -4124,6 +4191,7 @@ var ScopeChatBridge = "chat_bridge";
 var ScopeChatBridgeRead = "chat_bridge:read";
 var ScopeChatBridgeWrite = "chat_bridge:write";
 var ScopeChatBridgeRotate = "chat_bridge:rotate";
+var ScopeAgentAccessManage = "agent_access:manage";
 var ScopeModels = "models";
 var ScopeModelsChat = "models:chat";
 var ScopeEntitlements = "entitlements";
@@ -4152,6 +4220,9 @@ function remoteControlScopes() {
 function chatBridgeScopes() {
   return [ScopeChatBridge];
 }
+function agentAccessScopes() {
+  return [ScopeAgentAccessManage];
+}
 
 // src/models/index.ts
 init_types();
@@ -7117,6 +7188,15 @@ function sleep2(ms, signal) {
 }
 
 // src/support/bug-report.ts
+function unwrapBugReport(raw, op, isComplete) {
+  if (raw && isComplete(raw)) return raw;
+  const inner = raw?.data;
+  if (inner && isComplete(inner)) return inner;
+  const keys = raw && typeof raw === "object" ? Object.keys(raw) : [];
+  throw new Error(
+    `acosmi: ${op}: gateway accepted the request but the response is missing required fields (observed keys: ${keys.length > 0 ? keys.join(",") : "<none>"})`
+  );
+}
 Client.prototype.submitBugReport = async function(reportData, signal) {
   if (reportData == null) {
     throw new Error("acosmi: reportData required");
@@ -7133,7 +7213,11 @@ Client.prototype.submitBugReport = async function(reportData, signal) {
     { content: contentStr },
     signal
   );
-  return result.data;
+  return unwrapBugReport(
+    result,
+    "submitBugReport",
+    (r) => typeof r.feedback_id === "string" && r.feedback_id.length > 0
+  );
 };
 Client.prototype.getBugReport = async function(bugID, signal) {
   const trimmed = bugID.trim();
@@ -7146,7 +7230,7 @@ Client.prototype.getBugReport = async function(bugID, signal) {
     null,
     signal
   );
-  return resp.data;
+  return unwrapBugReport(resp, "getBugReport", (r) => typeof r.id === "string");
 };
 
 // src/subscription/client.ts
@@ -7728,6 +7812,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, 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, HTTPError, IdempotencyKeyHeader, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OAuthTokenEndpointError, OpenAIAdapter, OrderTerminalError, ProductFamilyEnum, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, RegionScopeEnum, ScopeAI, ScopeAccount, 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, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, 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, isValidTokenSet, isWindowLimitError, isWindowLimitStreamError, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, 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, 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, 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, isValidTokenSet, isWindowLimitError, isWindowLimitStreamError, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, remoteControlScopes, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map