@acosmi/sdk-ts 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,7 +5,79 @@ 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).
 
-## [Unreleased]
+## [1.6.0] - 2026-05-24
+
+### Added — 业务侧终端用户 id (endUserId) + 请求保活
+
+- `ChatRequest.endUserId?: string` — 业务侧终端用户 id, 跨 provider 通用语义。
+  序列化规则:
+  - OpenAI wire: 顶层 `body["user_id"]`
+  - Anthropic wire: 合并到 `body["metadata"]["user_id"]`; caller `metadata` 显式键优先
+- 约束: 长度 ≤ 512, 字符集 `[a-zA-Z0-9_-]+`, **禁止包含用户隐私信息** (邮箱/手机/真名等).
+- 公开 helper `validateEndUserId(s)`, `isSSECommentLine(line)`, 常量 `maxEndUserIdLength`.
+- Chat / ChatMessages / ChatStream / ChatMessagesStream 的 per-request timeout 5min → **11min**,
+  覆盖 DeepSeek 上游 "开始推理前最大 10min 保活" 窗口。
+- SSE 外层循环显式跳过 `: comment` 注释行 (": keep-alive"), 防止未来添加 else-branch 误抛 JSON parse error。
+- 网关 sanitizer step 4.4 做最终校验 + 派生 + 注入; caller 显式覆盖需 `scope=endusr.set`,
+  无授权时 endUserId 被丢弃, 上游收到的是网关 HMAC 派生值 (32 字符稳定 id)。
+
+### Security — devDep upgrade（消除 4 项 moderate Dependabot alerts）
+
+- `vitest` `^1.0.0` → `^4.1.7`（跨 3 major），传递性把 `vite` `5.4.21` → `8.0.14`
+  / `esbuild` 路径升到 fixed 区间，消除：
+  - **GHSA-67mh-4wv8-2f99** — esbuild dev server CORS bypass（fix: 0.25.0）
+  - **GHSA-4w7w-66w2-5vf9** — vite path traversal in optimized deps `.map` handling（fix: 6.4.2）
+- **Consumer 零影响**：vitest/vite/esbuild 全在 devDependencies，dist tarball 与
+  package.json `engines.node >=18` 不变；不需要打 tag / 发新版。
+- 验证：`npm audit` 0 vulnerabilities / `vitest 4.1.7` 17 文件 214 case
+  全绿 / typecheck / lint / build / test:pack consumer 视角 PASS / docs 重生
+  无新增 errors。
+
+---
+
+## [1.5.1] — 2026-05-23
+
+> **Docs / examples patch — 无 API 变化**。对 README、`docs/compliance.md`、`docs/开发与发布手册.md`、`examples/`、源码注释做全量复核与修订，消除发现的 8 项漂移与遗漏。无 runtime 行为变更、无新增/移除导出符号、无 wire-format 变化；`typecheck` / `lint` / `vitest`(214) / `build` / `test:pack` 全绿。
+
+### Changed — README.md
+
+- 补全 API 总览表 25+ 漏列方法：`chatMessages` / `chatMessagesStream` / `buildChatRequest` / `loginWithHandler` / `isAuthorized` / `getTokenSet` / 浏览器 Web OAuth 4 原语 / `discoverWithProfile` / `register` / `revokeToken` / `generateState` / `ensureModelCached` / `browseSkillStore` / `getSkillSummary` / `certifySkill` / `getCertificationStatus` / `markAllNotificationsRead` / `deleteNotification` / `unregisterDevice` / `updateNotificationPreference` / WS `connect`/`disconnect`/`isConnected` / `listConsumeRecords` / `invalidateCoefficientCache` / `getTokenPackageDetail` / `listMyOrders` / `Client.create`。
+- 修复 §"双格式红线" 把 `preferredFormat` / `supportedFormats` 错写为 camelCase 的描述——`ManagedModel` 上这两个字段是 snake_case wire 字段；同步说明 `modelId` / `isEnabled` / `inputModalities` 等顶层走 camelCase。
+- 修复 Quick Start / 流式 / Web Search 三个示例的 `ChatRequest` 字段：`maxTokens` → `max_tokens`（与 `src/models/types.ts:ChatRequest.max_tokens` 对齐）。
+- 重写 §"手动 OAuth" 段：`register/authorize/exchangeCode` 全部按 `src/auth/auth.ts` 真实签名重写——`register` 不接 scopes / `authorize` 需 `reg.client_id`+`handler:` 而非 `onEvent:`、返回 `{ result, verifier }` / `exchangeCode` 需 5 个位置参数含 `result.redirectURI` + `verifier`；指向 `examples/auth-oauth-flow.ts` 完整示例；加浏览器 Web OAuth 替代品指引。
+- §错误处理表补 `ModelNotFoundError`（`chat` / `ensureModelCached` listModels 自动刷新后仍未命中）；为既有 `NetworkError` / `StreamError` / `CompliancePollError` 补字段细节。
+- §Agent Runs 段补 `AgentRunStreamEvent` 完整 13 类事件表（`run_started` / `status` / `text_delta` / `reasoning_delta` / `tool_call` / `tool_result` / `local_tool_request` / `artifact` / `sources` / `usage` / `settle` / `error` / `done`）。
+- 新增 §`sanitize` 命名空间小节：列 `client.setDefensiveSanitize` / `setAutoStripEphemeralHistory` / `applyRequestSanitizers` 三个 mixin 方法 + `sanitize.sanitize` / `dropBlocks` / `stripEphemeral` + 17 个 `Block*` 常量 + `MinimalSanitizeConfig` 字段（`maxMessagesTurns` / `permanentDenyBlocks` / `maxImageBytes` / `maxVideoBytes` / `maxPDFBytes`）+ thinking 块硬豁免红线。
+- §历史表 1.5.0 行补"compliance gateway S1-S6 全量 rollup + scope 总数 15"说明。
+
+### Changed — docs/compliance.md
+
+- 6 处版本号漂移修订：`Since v1.6.0 / 1.7.0 / 1.8.0 / 1.9.0 / 1.10.0` + `Contract-template scopes (added in v1.10.0)` → 统一为 `v1.5.0 (originally planned as v1.X.0 — see CHANGELOG §"SN：..."`，避免消费者误以为这些方法在未来版本才有。
+
+### Changed — docs/开发与发布手册.md
+
+- §7 必测清单：`test/compliance-scopes.test.ts — 12 个` → `15 个`，附 12 → 13（v1.3.2）→ 15（v1.5.0 S5）演进注解。
+- §7 新增"Compliance gateway S1-S6 rollup（v1.5.0）"小节，逐 S 列出新增 25+ SDK 方法、对应后端 G1-G6、新增 scope 与 fail-closed 红线。
+
+### Changed — examples/
+
+- `examples/compliance-evidence-timestamp.ts` 补 `ScopeComplianceReportsWrite`（`createReport` 自 v1.3.2 起改用独立 write scope；过去用 `ScopeComplianceReportsRead` 在生产会 401）。
+- `examples/auth-oauth-flow.ts` 顶部注释指向 v1.4.0+ Web OAuth 原语（`discoverWebOAuthMetadata` / `registerWebOAuthClient` / `createWebAuthorizationRequest` / `completeWebAuthorizationRequest`）+ `Config.browserRefreshMode` / `refreshProxyURL` (v1.4.1+) CORS 规避方案。
+- `examples/core-chat.ts` 顶部注释把 `preferredFormat` / `supportedFormats` 改回 snake_case；补 `ChatRequest` snake_case wire / `ManagedModel` 顶层 camelCase 字段命名说明。
+
+### Changed — 源码注释（无 runtime 影响）
+
+- `src/index.ts` 顶部注释从"端口源 acosmi-sdk-go v0.19.0 (一字不差对齐)"改为"自 2026-05-22 起 TS 是主实现 / 事实标准"，与 README §状态 + 手册 §1 / §10 一致。
+- `src/browser.ts` 顶部注释加 v1.4.0+ Web OAuth 替代品 + v1.4.1+ `browserRefreshMode` 指引。
+- `src/auth/auth.ts` 顶部 + `authorize()` doc：从"浏览器侧应自行实现 popup window"改为指向同文件内 Web OAuth 原语。
+- `docs/api/`（TypeDoc 生成）已同步重生成。
+
+### Verified
+
+- `typecheck`：0 errors
+- `vitest`：17 files / **214 tests passed**
+- `npm pack --dry-run`：tarball 内容无变化
+- 跨语言契约印记（snake_case wire / 双 adapter 等地位 / bug-for-bug 行为）零回归
 
 ---
 

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 反向翻译补齐
-- 当前版本：**1.5.0**（沉淀 `src/shared/` 跨域共享 DTO——分页 / operation / retryAdvice / principal / gate 原语；`1.4.2` `src/` 按业务域重组；`1.4.x` 浏览器 Web OAuth；`1.3.x` `client.compliance` 合规域客户端；详见 [CHANGELOG](./CHANGELOG.md)）
+- 当前版本：**1.6.0**（v1.6.0 新增 `ChatRequest.endUserId` 业务侧终端用户 id + SSE keep-alive 注释行自动跳过 + per-request 超时 5min→11min 覆盖上游"开始推理前最长 10min 保活"窗口；详见下方"用户隔离 (v1.6.0+)"+ [CHANGELOG](./CHANGELOG.md)）。`1.5.x` 文档复核 + `src/shared/` 跨域 DTO + compliance gateway S1-S6 rollup；`1.4.x` `src/` 按业务域重组 + 浏览器 Web OAuth；`1.3.x` `client.compliance` 合规域客户端
 - 测试：发布前需通过 typecheck/lint/vitest/build/packed-tarball smoke (`npm run test:pack`)
 - API 参考文档：`npm run docs` 经 TypeDoc 生成到 `docs/api/`
 - 包链接：[npm](https://www.npmjs.com/package/@acosmi/sdk-ts) · [GitHub Releases](https://github.com/acosmi/sdk-ts/releases)
@@ -28,11 +28,30 @@ await client.login('My App', allScopes());
 
 const resp = await client.chat('claude-opus-4-7', {
   messages: [{ role: 'user', content: 'Hello' }],
-  maxTokens: 1024,
+  max_tokens: 1024, // ChatRequest 走 snake_case wire 字段（与上游 Go json tag 对齐）
+  endUserId: 'user-abc-123', // v1.6.0+ 业务侧稳定 id, 启用上游隔离 / KV-cache / 调度策略
 });
 console.log(resp.content);
 ```
 
+### 用户隔离 (v1.6.0+)
+
+`ChatRequest.endUserId` — 业务侧终端用户的稳定标识, **跨 provider 通用语义**, 不绑死 DeepSeek。SDK 自动按 wire-format 注入: OpenAI 顶层 `user_id` / Anthropic `metadata.user_id`; 网关侧校验并派生后送达上游, 命中三项隔离能力 (内容安全 / KV-cache / 调度)。
+
+**约束**: 字符集 `[a-zA-Z0-9_-]+`, 长度 ≤ 512, **禁止包含 PII** (邮箱 / 手机 / 真名等)。可用 `validateEndUserId(s)` helper 自校验。
+
+```ts
+import { validateEndUserId } from '@acosmi/sdk-ts';
+
+const err = validateEndUserId(uid);
+if (err) {
+  // 处理: PII / 长度 / 字符集不合规
+  throw new Error(err);
+}
+```
+
+不传 `endUserId` 时网关从认证身份 HMAC-SHA256 自动派生 32 字符稳定 id, 业务无感知。流式 + 同步 + Anthropic + OpenAI 四条路径均支持。
+
 ## 双格式红线（设计核心）
 
 SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应两个不同下游产品。
@@ -42,12 +61,12 @@ SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应
 | `AnthropicAdapter` | `POST /managed-models/:id/anthropic`  | Anthropic 原生格式（含 thinking 等）|
 | `OpenAIAdapter`    | `POST /managed-models/:id/chat`       | OpenAI 兼容格式（DeepSeek/GLM 等）  |
 
-路由由 `getAdapterForModel(model)` 按 ManagedModel 的 `preferredFormat` / `supportedFormats` 决策：
+路由由 `getAdapterForModel(model)` 按 ManagedModel 的 `preferred_format` / `supported_formats` 决策（wire-format 字段，snake_case 与上游 Go json tag 严格对齐；ManagedModel 上其余顶层字段如 `modelId` / `isEnabled` / `inputModalities` 走 camelCase，详见 `src/models/types.ts`）：
 
-1. `preferredFormat` 非空 → 按值（`anthropic` | `openai`）
-2. `supportedFormats` 含 `anthropic` → AnthropicAdapter
-3. `supportedFormats` 含 `openai` → OpenAIAdapter
-4. 两字段均空（旧上游）→ 按 provider 名回落
+1. `preferred_format` 非空 → 按值（`anthropic` | `openai`）
+2. `supported_formats` 含 `anthropic` → AnthropicAdapter
+3. `supported_formats` 含 `openai` → OpenAIAdapter
+4. 两字段均空（旧上游）→ 按 `provider` 名回落
 
 `client.chat()` / `client.chatStream()` 内部自动调 `getAdapterForModel`，使用方无需关心。
 
@@ -66,7 +85,7 @@ SDK 同时提供 **Anthropic + OpenAI 两条 endpoint**，**等地位**，对应
 ```ts
 const stream = client.chatStream('claude-opus-4-7', {
   messages: [{ role: 'user', content: '写一首诗' }],
-  maxTokens: 1024,
+  max_tokens: 1024,
 });
 
 for await (const ev of stream) {
@@ -142,6 +161,24 @@ await client.agentRuns.cancel(run.runId); // safe to call from UI cancel buttons
 
 `stream(runId)` 支持 durable replay：断线后重新连接同一个 run，会先回放已持久化的 Agent Run SSE 事件，再继续消费运行中的事件。`usage` / `settle` 事件会暴露 `exact`、`cacheReadTokens`、`cacheCreateTokens` 等字段，便于下游展示真实结算状态。
 
+**`AgentRunStreamEvent` 完整事件类型**（union，详见 `src/agent-runs/types.ts`；上面示例只演示了 4 种常见分支）：
+
+| `type` | 触发 / 含义 | 关键字段 |
+| --- | --- | --- |
+| `run_started` | 流首事件，确认服务端已开始执行 | `runId`、`sessionId` |
+| `status` | 任务粗粒度状态变化 | `status` (`queued`/`running`/`completed`/`failed`/`cancelled`)、`message?` |
+| `text_delta` | 主要文本输出增量 | `text` |
+| `reasoning_delta` | 推理 / 思考过程增量（debug 用，不一定向终端用户展示） | `text` |
+| `tool_call` | Agent 发起内置 / 网关工具调用 | `id`、`name`、`input?` |
+| `tool_result` | 内置 / 网关工具调用结果 | `id`、`name?`、`result?`、`error?` |
+| `local_tool_request` | Agent 请求宿主提供本地只读工具结果，宿主须用 `submitLocalToolResult` 回填 | `requestId`、`name`、`input` |
+| `artifact` | 产出文件（图片 / 代码 / 文档等）；用 `downloadArtifact(runId, artifact.id)` 下载 | `artifact: AgentRunArtifact` |
+| `sources` | 网络检索 / RAG 来源信息 | `sources` |
+| `usage` | provider/ADK 透传的 token usage | `usage.exact`、`inputTokens`、`outputTokens`、`totalTokens`、`cacheReadTokens`、`cacheCreateTokens` |
+| `settle` | 服务端结算事件 | `settlement.status`、`tokenRemaining`、`callRemaining`、`exact`、`retryQueued` |
+| `error` | 失败事件（`throwOnError:true` 默认会转 `AgentRunStreamError` 抛出） | `error.code`、`error.message`、`error.stage`、`error.retryable` |
+| `done` | 流终止 | `runId`、`status` |
+
 ## 认证
 
 ### 浏览器内 / 自动 OAuth（推荐）
@@ -153,17 +190,45 @@ const token = await client.ensureToken();      // 拿到当前有效 access toke
 
 ### 手动 OAuth（CLI / 自定义流程）
 
+底层 helper 适用于自管 token 的 CLI / 自定义授权 UI。**大多数场景直接用 `client.login(appName, scopes)` 即可**——它内部封装了下面全部步骤。完整可运行示例见 [`examples/auth-oauth-flow.ts`](./examples/auth-oauth-flow.ts)。
+
 ```ts
-import { discover, register, authorize, exchangeCode } from '@acosmi/sdk-ts';
+import {
+  discover,           // RFC 8414 元数据发现
+  register,           // RFC 7591 动态客户端注册
+  authorize,          // 本地 loopback PKCE（仅 Node）
+  exchangeCode,       // code + verifier → token
+  refreshToken,       // 续期
+  newTokenSet,        // 把 TokenResponse 包成可持久化 TokenSet
+  FileTokenStore,
+  allScopes,
+} from '@acosmi/sdk-ts';
 
 const meta = await discover(process.env.ACOSMI_SERVER_URL!);
-const reg = await register(meta, 'My CLI', allScopes());
-const result = await authorize(meta, reg, allScopes(), {
-  onEvent: (ev) => console.log(ev.type, ev.url),
+const reg = await register(meta, 'My CLI');            // 不接 scopes 参数
+const scopes = allScopes();
+
+// authorize 返回 { result, verifier }，result.code + result.redirectURI 给 exchangeCode
+const { result, verifier } = await authorize(meta, reg.client_id, scopes, {
+  handler: (ev) => {
+    if (ev.type === 'auth_url') console.log('open in browser:', ev.url);
+  },
 });
-const tokens = await exchangeCode(meta, reg, result.code, result.codeVerifier);
+
+const tokenResp = await exchangeCode(
+  meta,
+  reg.client_id,
+  result.code,
+  result.redirectURI,      // 来自 authorize 返回；不是手动构造的 redirect_uri
+  verifier,                 // 来自 authorize 返回；不是 result.* 上的字段
+);
+
+const tokens = newTokenSet(tokenResp, reg.client_id, process.env.ACOSMI_SERVER_URL!);
+await new FileTokenStore('./tokens.json').save(tokens);
 ```
 
+> 浏览器侧（无法启 loopback HTTP server）请改用 v1.4.0+ Web OAuth 原语 `discoverWebOAuthMetadata` + `registerWebOAuthClient` + `createWebAuthorizationRequest` + `completeWebAuthorizationRequest`，由调用方实现 popup / 同窗口 redirect handler，SDK 负责 PKCE / state 校验 / token 兑换。
+
 ### Token 持久化
 
 ```ts
@@ -179,16 +244,20 @@ const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL!, store: ne
 
 | 模块         | 主要方法                                                                             |
 | ------------ | ------------------------------------------------------------------------------------ |
-| **Chat**     | `chat`, `chatStream`, `chatStreamWithUsage`                                          |
+| **Client 构造** | `new Client(cfg)`（同步），`Client.create(cfg)`（async；预加载已有 TokenStore）            |
+| **Chat**     | `chat`, `chatStream`, `chatStreamWithUsage`, `chatMessages`, `chatMessagesStream`, `buildChatRequest` |
 | **Agent Runs** | `agentRuns.create`, `agentRuns.stream`, `agentRuns.run`, `agentRuns.cancel`, `agentRuns.get`, `agentRuns.listArtifacts`, `agentRuns.downloadArtifact`, `agentRuns.submitLocalToolResult`, `agentRuns.runWithLocalTools` |
-| **Auth**     | `login`, `logout`, `ensureToken`, `forceRefresh`, `discover`, `authorize`, `exchangeCode`, `refreshToken` |
-| **Models**   | `listModels`, `listModelsWithStatus`, `getModelCapabilities`, `getQuotaSummary`, `modelSupportsInputModality`, `modelSupportsImageInput`, `findFirstModelByInputModality`, `findDesktopVisualUnderstandingModel` |
-| **Skills**   | `browseSkills`, `browseSkillsList`, `getSkillDetail`, `resolveSkill`, `installSkill`, `downloadSkill`, `uploadSkill`, `generateSkill`, `optimizeSkill`, `validateSkill` |
+| **Auth — 内置 Loopback OAuth** | `login`, `loginWithHandler`, `logout`, `ensureToken`, `forceRefresh`, `isAuthorized`, `getTokenSet` |
+| **Auth — 手动 OAuth 原语** | `discover`, `discoverWithProfile`, `register`, `authorize`, `exchangeCode`, `refreshToken`, `revokeToken`, `generateState` |
+| **Auth — 浏览器 Web OAuth (v1.4.0+)** | `discoverWebOAuthMetadata`, `registerWebOAuthClient`, `createWebAuthorizationRequest`, `completeWebAuthorizationRequest` |
+| **Models**   | `listModels`, `listModelsWithStatus`, `getModelCapabilities`, `getQuotaSummary`, `ensureModelCached`, `modelSupportsInputModality`, `modelSupportsImageInput`, `findFirstModelByInputModality`, `findDesktopVisualUnderstandingModel` |
+| **Skills**   | `browseSkillStore`, `browseSkills`, `browseSkillsList`, `getSkillDetail`, `getSkillSummary`, `resolveSkill`, `installSkill`, `downloadSkill`, `uploadSkill`, `generateSkill`, `optimizeSkill`, `validateSkill`, `certifySkill`, `getCertificationStatus` |
 | **Tools**    | `listTools`, `getTool`                                                               |
 | **Wallet**   | `getWalletStats`, `getWalletTransactions`                                            |
-| **Entitlements** | `getBalance`, `getBalanceDetail`, `listEntitlements`, `claimMonthlyFree`, `getByModel`, `listBuckets`, `listCoefficients` |
-| **Packages** | `listTokenPackages`, `buyTokenPackage`, `getOrderStatus`, `waitForPayment`           |
-| **Notifications** | `listNotifications`, `getUnreadCount`, `markNotificationRead`, `registerDevice`, `listNotificationPreferences` |
+| **Entitlements** | `getBalance`, `getBalanceDetail`, `listEntitlements`, `listConsumeRecords`, `claimMonthlyFree`, `getByModel`, `listBuckets`, `listCoefficients`, `invalidateCoefficientCache` |
+| **Packages** | `listTokenPackages`, `getTokenPackageDetail`, `buyTokenPackage`, `getOrderStatus`, `listMyOrders`, `waitForPayment` |
+| **Notifications** | `listNotifications`, `getUnreadCount`, `markNotificationRead`, `markAllNotificationsRead`, `deleteNotification`, `registerDevice`, `unregisterDevice`, `listNotificationPreferences`, `updateNotificationPreference` |
+| **Notifications — WebSocket** | `connect`, `disconnect`, `isConnected` (实时推送订阅；浏览器走原生 WebSocket，Node 18-21 需自装 `ws`，Node 22+ 用原生) |
 | **Bug Report** | `submitBugReport`, `getBugReport`                                                  |
 | **Web Search** | `newWebSearchTool` (factory)                                                       |
 | **Compliance** | `compliance.createEvidenceAsset`, `compliance.issueTimestamp`, `compliance.waitForTimestampVerified`, `compliance.buildEvidencePackage`, `compliance.createReport`, `compliance.downloadReport`, `compliance.createSigningEnvelope`, `compliance.signEnvelope`, `compliance.getProviderRequest`, `compliance.waitForProviderRequestTerminal` |
@@ -216,6 +285,39 @@ const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL!, store: ne
 > `compliance` 分页 / gate 能力预沉淀的【共享原语】；消费这些类型的命名空间方法
 > 须待对应后端端点就绪后才落地，当前 8 个占位命名空间尚未从根入口导出。
 
+### `sanitize` 命名空间（历史消息清理）
+
+`@acosmi/sdk-ts` 把 `src/sanitize/` 整体以命名空间方式导出（`import { sanitize } from '@acosmi/sdk-ts'`），同时也通过 `@acosmi/sdk-ts/sanitize` 子路径单独导入。Client 与 ChatRequest 的粘合（`Client.prototype.applyRequestSanitizers`）由 `src/core/sanitize-bridge.ts` 通过 declaration merging 自动注入。**默认零开销**——只有显式调用 `client.setDefensiveSanitize(cfg)` 或 `client.setAutoStripEphemeralHistory(true)` 后才走流水线。
+
+| 公开符号 | 形态 | 用途 |
+| --- | --- | --- |
+| `client.setDefensiveSanitize(cfg)` | Client 方法（runtime 注入） | 配置请求前底线防御（`maxMessagesTurns` 历史轮深度、`permanentDenyBlocks` block 类型黑名单、`maxImageBytes` / `maxVideoBytes` / `maxPDFBytes` base64 内联媒体上限）；传 `{}` 关闭 |
+| `client.setAutoStripEphemeralHistory(on)` | Client 方法（runtime 注入） | 开启后每次请求自动从 `rawMessages` 剥除带 `acosmi_ephemeral:true` 标记的 block，并联动剥引用已剥 `tool_use_id` 的 `tool_result` |
+| `client.applyRequestSanitizers(req)` | Client 方法（buildChatRequest 内部自动调用） | 一般无需手动调；自定义 build 链路时可直接复用 |
+| `sanitize.sanitize(messages, cfg)` | 函数 | 对消息历史做白名单过滤 + 深度 / 尺寸校验 + ephemeral 剥离，返回新数组 |
+| `sanitize.dropBlocks(messages, predicate)` | 函数 | 按谓词剔除 content blocks（联动剔除引用同 tool_use_id 的 tool_result） |
+| `sanitize.stripEphemeral(messages)` | 函数 | 剥离 `acosmi_ephemeral:true` 块（端口自 Go `sanitize.StripEphemeral`，bug-for-bug） |
+| `sanitize.MinimalSanitizeConfig` | 类型 | sanitize 配置 |
+| `sanitize.BlockType` / `BlockText` / `BlockImage` / `BlockVideo` / `BlockDocument` / `BlockSearchResult` / `BlockThinking` / `BlockRedactedThinking` / `BlockToolUse` / `BlockToolResult` / `BlockToolReference` / `BlockServerToolUse` / `BlockWebSearchToolResult` / `BlockCodeExecutionToolResult` / `BlockMCPToolUse` / `BlockMCPToolResult` / `BlockContainerUpload` | 类型 + 常量 | 已知 block 类型常量 |
+| `sanitize.HistoryTooDeepError` / `BlockDeniedError` / `SizeError` | 错误 | sanitize 规则不通过时分类抛出（也导出对应单例 `ErrHistoryTooDeep` / `ErrBlockDenied`） |
+
+```ts
+import { Client, sanitize } from '@acosmi/sdk-ts';
+
+const client = new Client({ serverURL });
+
+// 启用底线防御 + 自动剥 ephemeral
+client.setDefensiveSanitize({
+  maxMessagesTurns: 64,
+  // 其他字段按 MinimalSanitizeConfig 形态填充
+});
+client.setAutoStripEphemeralHistory(true);
+
+// 之后 chat / chatStream 走 buildChatRequest 时自动应用 applyRequestSanitizers。
+```
+
+> 红线：**thinking 块在 Anthropic 续轮的"上一轮返回什么、下一轮就必须原样回传"硬约束下走豁免**，禁止从历史中剔除；`tool_use_id` 联动剔除规则参考 `test/sanitize/history.test.ts` 的 P0 红线测试。详细行为见 `src/sanitize/history.ts` + `defensive.ts`。
+
 ### 示例：Skill 商店搜索
 
 ```ts
@@ -246,7 +348,7 @@ const tool = newWebSearchTool({
 
 const resp = await client.chat('claude-opus-4-7', {
   messages: [{ role: 'user', content: '查一下 Web Components 最新规范' }],
-  maxTokens: 2048,
+  max_tokens: 2048,
   tools: [tool],
 });
 ```
@@ -323,13 +425,14 @@ const view = await client.getBugReport(result.feedback_id);
 | 错误类型             | 触发                                                                   |
 | -------------------- | ---------------------------------------------------------------------- |
 | `HTTPError`          | 4xx/5xx，含 `statusCode` / `body` / `type` / `retryAfter`              |
-| `NetworkError`       | TCP/DNS/TLS 失败                                                       |
-| `StreamError`        | SSE 流解析失败                                                         |
+| `NetworkError`       | TCP/DNS/TLS 失败；含 `isTimeout()` / `isEOF()` 便捷判定                  |
+| `StreamError`        | gateway `managed_model_stream_failed` 事件解析（含 `code` / `stage` / `retryable`） |
 | `AgentRunStreamError` | Agent Runs 流返回 `error` 事件（默认抛出；可设 `throwOnError:false` 自行消费） |
 | `BusinessError`      | 网关返回 `code !== 0`，含 `code` (number) / `message` (字符串)         |
 | `RateLimitError`     | 429（含 `retryAfter`）                                                 |
 | `OrderTerminalError` | `waitForPayment` 终态失败                                              |
-| `CompliancePollError` | `waitForTimestampVerified` / `waitForProviderRequestTerminal` 终态失败或超时 |
+| `ModelNotFoundError` | `chat` / `ensureModelCached`：listModels 自动刷新一次后仍未命中目标 modelId（v0.13.x 起替代旧硬返 anthropic 占位的行为，含 `modelId` 字段） |
+| `CompliancePollError` | `waitForTimestampVerified` / `waitForProviderRequestTerminal` 终态失败或超时（含 `kind: 'timeout' | 'terminal_failure' | 'unknown'`） |
 
 ```ts
 import { HTTPError, BusinessError } from '@acosmi/sdk-ts';
@@ -482,6 +585,7 @@ client.compliance.getCapabilities(signal?)                 // 能力闸门列表
 client.compliance.getFeatureGate(action, signal?)          // 单动作能力（便捷，一次网络请求）
 client.compliance.listOperations(req?, signal?)            // 操作投影分页 → PageResult
 client.compliance.getOperation(id, signal?)                // 操作投影详情
+client.compliance.classifyError(err)                       // BusinessError → ComplianceErrorInfo | null（同顶层 classifyComplianceError，便于在 catch 块上链式调用）
 
 client.compliance.listTsaProviders(signal?)                // TSA provider 只读列表
 client.compliance.getTsaStats(signal?)                     // 时间章统计只读视图
@@ -579,7 +683,8 @@ npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 1.5.0 | 当前稳定版 | 沉淀 `src/shared/` 跨域共享 DTO（`PageRequest`/`PageResult` 别名、`OperationId`/`OperationStatus`/`IdempotencyKeyHeader`、`RetryAdvice` 叠加层、`PrincipalRef`/`TenantRef`、`FeatureGateStatus`/`StepUpStatus`/`BillingPreflightResult`）。纯增量；8 个平台控制面占位命名空间仍待后端契约就绪后落地。 |
+| 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 文档。 |
 | 1.4.1 | 稳定版 | 新增 `Config.browserRefreshMode` / `refreshProxyURL`——浏览器 Web OAuth token 刷新策略（规避 issuer CORS 403）。 |
 | 1.4.0 | 稳定版 | 新增浏览器 Web OAuth 原语 `discoverWebOAuthMetadata` / `registerWebOAuthClient`（csign `/login` Web OAuth 接入）。 |

package/dist/browser/index.mjs

@@ -365,8 +365,17 @@ var init_anthropic = __esm({
             body["effort"] = req.effort;
           }
         }
-        if (req.metadata) {
-          body["metadata"] = req.metadata;
+        if (req.metadata || req.endUserId && req.endUserId !== "") {
+          const meta = {};
+          if (req.metadata) {
+            for (const [k, v] of Object.entries(req.metadata)) {
+              meta[k] = v;
+            }
+          }
+          if (req.endUserId && req.endUserId !== "" && meta["user_id"] === void 0) {
+            meta["user_id"] = req.endUserId;
+          }
+          body["metadata"] = meta;
         }
         const allTools = [];
         if (req.tools != null) {
@@ -710,6 +719,9 @@ var init_openai = __esm({
             body[k] = v;
           }
         }
+        if (req.endUserId && req.endUserId !== "") {
+          body["user_id"] = req.endUserId;
+        }
         if (req.stream === true) {
           body["stream_options"] = { include_usage: true };
         }
@@ -1773,6 +1785,30 @@ function extractAnthropicBlockMeta(eventType, data, blockTypeMap) {
 // src/core/client.ts
 init_openai();
 
+// src/models/enduser.ts
+var maxEndUserIdLength = 512;
+function validateEndUserId(s) {
+  if (!s) return null;
+  if (s.length > maxEndUserIdLength) {
+    return `endUserId length ${s.length} > ${maxEndUserIdLength}`;
+  }
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    const ok = c >= 97 && c <= 122 || // a-z
+    c >= 65 && c <= 90 || // A-Z
+    c >= 48 && c <= 57 || // 0-9
+    c === 95 || // _
+    c === 45;
+    if (!ok) {
+      return `endUserId contains invalid char code 0x${c.toString(16)} at offset ${i} (allowed: [a-zA-Z0-9_-])`;
+    }
+  }
+  return null;
+}
+function isSSECommentLine(line) {
+  return line.length > 0 && line.charCodeAt(0) === 58;
+}
+
 // src/core/http.ts
 init_errors();
 var maxDownloadSize = 50 * 1024 * 1024;
@@ -1963,6 +1999,7 @@ var FilterStatusUnknown = "";
 var ErrOAuthCORSBlocked = "oauth_cors_blocked";
 var ErrRefreshProxyFailed = "refresh_proxy_failed";
 var ErrTokenExpired = "token_expired";
+var CHAT_REQUEST_TIMEOUT_MS = 11 * 60 * 1e3;
 function newDeferred() {
   let resolve;
   let reject;
@@ -2556,7 +2593,7 @@ var Client = class _Client {
    */
   async chat(modelID, req, signal) {
     req.stream = false;
-    const ctl = withRequestTimeout(5 * 60 * 1e3, signal);
+    const ctl = withRequestTimeout(CHAT_REQUEST_TIMEOUT_MS, signal);
     try {
       const { body, adapter } = await this.buildChatRequest(modelID, req, ctl.signal);
       const endpoint = `/managed-models/${encodeURIComponent(modelID)}${adapter.endpointSuffix()}`;
@@ -2603,7 +2640,7 @@ var Client = class _Client {
   }
   async chatMessagesAnthropic(modelID, req, adapter, signal) {
     req.stream = false;
-    const ctl = withRequestTimeout(5 * 60 * 1e3, signal);
+    const ctl = withRequestTimeout(CHAT_REQUEST_TIMEOUT_MS, signal);
     try {
       const caps = this.getCachedCapabilities(modelID) ?? zeroModelCapabilities();
       const body = adapter.buildRequestBody(caps, req);
@@ -2640,7 +2677,7 @@ var Client = class _Client {
   }
   async chatMessagesOpenAI(modelID, req, adapter, signal) {
     req.stream = false;
-    const ctl = withRequestTimeout(5 * 60 * 1e3, signal);
+    const ctl = withRequestTimeout(CHAT_REQUEST_TIMEOUT_MS, signal);
     try {
       const caps = this.getCachedCapabilities(modelID) ?? zeroModelCapabilities();
       const body = adapter.buildRequestBody(caps, req);
@@ -2721,6 +2758,7 @@ var Client = class _Client {
     }
     let currentEvent = "";
     for await (const line of iterSSELines(resp.body)) {
+      if (isSSECommentLine(line)) continue;
       if (line.startsWith("event:")) {
         currentEvent = line.slice("event:".length).trim();
       } else if (line.startsWith("data:")) {
@@ -2786,6 +2824,7 @@ var Client = class _Client {
     if (adapter.format() === 1 /* OpenAI */) {
       const converter = newOpenAIStreamConverter();
       for await (const line of iterSSELines(resp.body)) {
+        if (isSSECommentLine(line)) continue;
         if (line.startsWith("event:")) {
           line.slice("event:".length).trim();
         } else if (line.startsWith("data:")) {
@@ -2799,6 +2838,7 @@ var Client = class _Client {
       const blockTypeMap = /* @__PURE__ */ new Map();
       let currentEvent = "";
       for await (const line of iterSSELines(resp.body)) {
+        if (isSSECommentLine(line)) continue;
         if (line.startsWith("event:")) {
           currentEvent = line.slice("event:".length).trim();
         } else if (line.startsWith("data:")) {
@@ -6086,6 +6126,6 @@ Client.prototype.getBugReport = async function(bugID, signal) {
   return resp.data;
 };
 
-export { AgentRunStreamError, AgentRunsClient, AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, ComplianceClient, CompliancePollError, 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, OpenAIAdapter, OrderTerminalError, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
+export { AgentRunStreamError, AgentRunsClient, AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, ComplianceClient, CompliancePollError, 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, OpenAIAdapter, OrderTerminalError, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSECommentLine, isSSLError, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map