@acosmi/sdk-ts 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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).
 
+## [1.1.0] — 2026-05-06
+
+### Added
+
+- **Agent Runs SDK Gateway** — 新增 `client.agentRuns` namespace，作为 CrabDesign、CrabCode、CrabClaw 等下游产品接入 Acosmi 云端智能体循环的正式 SDK 协议边界：
+  - `create(req, signal?)`
+  - `stream(runId, opts?, signal?)`
+  - `run(req, opts?, signal?)`
+  - `cancel(runId, signal?)`
+  - `get(runId, signal?)`
+  - `listArtifacts(runId, signal?)`
+  - `downloadArtifact(runId, artifactId, signal?)`
+  - `submitLocalToolResult(runId, result, signal?)`
+  - `runWithLocalTools(req, handlers, opts?, signal?)`
+
+- **Agent Run protocol types** — 新增 `AgentRunCreateRequest`、`AgentRunStreamEvent` discriminated union、`AgentRunArtifact`、`AgentRunStreamError` 等公开类型。SDK public API 使用 camelCase，HTTP wire-format 使用 snake_case。
+
+- **Local tool bridge protocol** — SDK 不内置产品专属本地文件读取逻辑；`local_tool_request` 由下游处理，并通过 `submitLocalToolResult({ requestId, ok, content | error })` 返回。便捷封装 `runWithLocalTools` 支持 handler 超时、拒绝和取消。
+
+- **Durable Agent Run Gateway contract** — Nexus Agent Run Gateway 使用租户隔离的 durable run store 持久化 run 状态、SSE event、artifact 和 local tool result；stream 支持断线后的 durable event replay，并将 local tool request 真正桥接到 ADK function call 等待点。
+
+- **Exact usage settlement** — Agent Runs 结算只接受 provider/ADK 透传的 `exact: true` usage，并通过 tk-dist `SettlePrecise(input/output/cacheRead/cacheCreate)` 精算；若 provider 未返回精确 usage，服务端会释放 hold 并返回 `usage_missing_released`，不会用字符数或 token 估算扣费。
+
+### Changed
+
+- **401 retry policy for Agent Runs** — Agent Runs 客户端只对 GET/stream/download 等安全查询做单次 401 refresh retry；`create`、`submitLocalToolResult` 等可能产生副作用的 POST 不自动重放，避免重复创建 run 或重复计费。
+
+### Tests
+
+- 新增 `test/agent-runs.test.ts`，覆盖 create 字段序列化、完整流事件解析、401 refresh 策略、error 事件结构化抛出、local tool result payload、artifact 下载文件名/content-type 解析。
+- `scripts/smoke-pack.mjs` 增加 consumer 视角的 `client.agentRuns` 类型调用验证。
+
 ## [1.0.2] — 2026-05-06
 
 ### Fixed
@@ -96,5 +128,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 36/36 vitest 全绿,源码 typecheck/lint/build 0 错误
 - 翻车机制:`prepublishOnly` 仅跑源码 typecheck/vitest/build,不验证 packed product 在 consumer 视角能否解析
 
+[1.1.0]: https://github.com/acosmi/sdk-ts/releases/tag/v1.1.0
+[1.0.2]: https://github.com/acosmi/sdk-ts/releases/tag/v1.0.2
 [1.0.1]: https://github.com/acosmi/sdk-ts/releases/tag/v1.0.1
 [1.0.0]: https://www.npmjs.com/package/@acosmi/sdk-ts/v/1.0.0

package/README.md

@@ -1,15 +1,15 @@
 # @acosmi/sdk-ts
 
-> Acosmi 模型网关 TypeScript SDK — 双格式（Anthropic + OpenAI）多端（浏览器 / Node ≥18 / Deno / Bun）
+> Acosmi 模型网关 + Agent Run Gateway TypeScript SDK — 双格式（Anthropic + OpenAI）多端（浏览器 / Node ≥18 / Deno / Bun）
 
 [![npm](https://img.shields.io/npm/v/%40acosmi%2Fsdk-ts.svg)](https://www.npmjs.com/package/@acosmi/sdk-ts)
 
 ## 状态
 
 - 端口源：[acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) v1.0.0（与 Go SDK 联动稳定测试版）
-- 当前版本：**1.0.1**（稳定测试版，与 Go SDK 联动 1.0.x；1.0.0 已 deprecate due to broken packaging，详见 [CHANGELOG](./CHANGELOG.md)）
-- 测试：36/36 vitest 全绿，typecheck/lint/build 0 错误；packed-tarball smoke (`npm run test:pack`) 在 prepublishOnly 闸内
-- 包链接：[npm](https://www.npmjs.com/package/@acosmi/sdk-ts/v/1.0.1) · [tarball](https://registry.npmjs.org/@acosmi/sdk-ts/-/sdk-ts-1.0.1.tgz) · [GitHub Release](https://github.com/acosmi/sdk-ts/releases/tag/v1.0.1) · [provenance](https://registry.npmjs.org/-/npm/v1/attestations/@acosmi%2fsdk-ts@1.0.1)（SLSA v1，CI 自动签）
+- 当前版本：**1.1.0**（新增 SDK-facing Agent Runs 公开 API；详见 [CHANGELOG](./CHANGELOG.md)）
+- 测试：56/56 vitest 全绿，typecheck/lint/build 0 错误；packed-tarball smoke (`npm run test:pack`) 在 prepublishOnly 闸内
+- 包链接：[npm](https://www.npmjs.com/package/@acosmi/sdk-ts/v/1.1.0) · [tarball](https://registry.npmjs.org/@acosmi/sdk-ts/-/sdk-ts-1.1.0.tgz) · [GitHub Release](https://github.com/acosmi/sdk-ts/releases/tag/v1.1.0)
 
 ## 安装
 
@@ -78,6 +78,69 @@ for await (const ev of stream) {
 
 `chatStreamWithUsage()` 返回带 usage/error/sources 标签的 AsyncIterable，便于聚合统计（详见 `src/client.ts`）。
 
+## Agent Runs
+
+`client.agentRuns` 是下游产品接入 Acosmi 云端智能体循环的正式 SDK 边界。CrabDesign、CrabCode、CrabClaw 等产品应通过这里创建、流式消费、取消、查询和下载智能体任务，不要直连 Nexus 内部 `/api/v4/chat/completions`。
+
+服务端 Agent Run Gateway 会按认证上下文做 `tenantId + userId` 隔离，run 状态、SSE event、artifact 和 local tool result 都是 durable store；任务执行会进入 Acosmi 统一 entitlement 预扣/结算/释放链路。结算只使用 provider/ADK 透传的精确 usage；如果 provider 未返回 `exact: true` usage，服务端会释放 hold，不会使用估算 token 扣费。
+
+```ts
+import { Client, allScopes } from '@acosmi/sdk-ts';
+
+const client = new Client({ serverURL: 'https://acosmi.com' });
+await client.login('CrabDesign', allScopes());
+
+const run = await client.agentRuns.create({
+  appId: 'crabdesign',
+  mode: 'design',
+  sessionId: 'session-optional',
+  input: 'Create a landing page mockup for a fintech dashboard',
+  activeSkillIds: ['brand-system'],
+  knowledgeBaseIds: ['kb-product'],
+  localContextPolicy: {
+    enabled: true,
+    readonly: true,
+    maxBytes: 128_000,
+    allowedTools: ['read_file'],
+  },
+  artifactPolicy: { enabled: true, maxFiles: 10 },
+});
+
+for await (const event of client.agentRuns.stream(run.runId, { throwOnError: false })) {
+  switch (event.type) {
+    case 'text_delta':
+      process.stdout.write(event.text);
+      break;
+    case 'reasoning_delta':
+      console.debug('[reasoning]', event.text);
+      break;
+    case 'local_tool_request': {
+      // SDK only defines the protocol. Product code owns local read-only tools.
+      const content = await readReadonlyLocalContext(event.name, event.input);
+      await client.agentRuns.submitLocalToolResult(run.runId, {
+        requestId: event.requestId,
+        ok: true,
+        content,
+      });
+      break;
+    }
+    case 'artifact': {
+      const file = await client.agentRuns.downloadArtifact(run.runId, event.artifact.id);
+      console.log('artifact', file.filename, file.contentType, file.data.byteLength);
+      break;
+    }
+    case 'error':
+      throw new Error(event.error.message);
+  }
+}
+
+await client.agentRuns.cancel(run.runId); // safe to call from UI cancel buttons
+```
+
+本地工具桥是显式 opt-in：SDK 不内置任何 CrabDesign/CrabCode 专属文件读取逻辑。`local_tool_request` 由下游处理，结果通过 `submitLocalToolResult({ requestId, ok, content | error })` 返回；拒绝、超时和取消都由下游 handler 控制。`allowedTools` 必须使用稳定的 ASCII function name，例如 `read_file`。
+
+`stream(runId)` 支持 durable replay：断线后重新连接同一个 run，会先回放已持久化的 Agent Run SSE 事件，再继续消费运行中的事件。`usage` / `settle` 事件会暴露 `exact`、`cacheReadTokens`、`cacheCreateTokens` 等字段，便于下游展示真实结算状态。
+
 ## 认证
 
 ### 浏览器内 / 自动 OAuth（推荐）
@@ -116,6 +179,7 @@ const client = new Client({ serverURL: 'https://acosmi.com', tokenStore: new Fil
 | 模块         | 主要方法                                                                             |
 | ------------ | ------------------------------------------------------------------------------------ |
 | **Chat**     | `chat`, `chatStream`, `chatStreamWithUsage`                                          |
+| **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`      |
 | **Skills**   | `browseSkills`, `browseSkillsList`, `getSkillDetail`, `resolveSkill`, `installSkill`, `downloadSkill`, `uploadSkill`, `generateSkill`, `optimizeSkill`, `validateSkill` |
@@ -206,6 +270,7 @@ const view = await client.getBugReport(result.feedback_id);
 | `HTTPError`          | 4xx/5xx，含 `status` / `body` / `requestID`  |
 | `NetworkError`       | TCP/DNS/TLS 失败                             |
 | `StreamError`        | SSE 流解析失败                               |
+| `AgentRunStreamError` | Agent Runs 流返回 `error` 事件（默认抛出；可设 `throwOnError:false` 自行消费） |
 | `BusinessError`      | 网关返回 `code !== 0`，含 `code` / `bizMsg`  |
 | `RateLimitError`     | 429（含 `retryAfter`）                       |
 | `OrderTerminalError` | `waitForPayment` 终态失败                    |
@@ -249,7 +314,9 @@ npm run build
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 1.0.1 | 当前稳定版 | 修复 1.0.0 双层 broken packaging:tsup 输出 `.mjs+.cjs` 与 exports 字段对齐;9 处 `declare module` 绑包名 `@acosmi/sdk-ts` 让 d.ts augmentation 在 consumer 视角合并;prepublishOnly 加 packed-tarball 烟测拦截"源码过 / 打包后 broken"。 |
+| 1.1.0 | 当前稳定版 | 新增 SDK-facing `agentRuns` 网关客户端，覆盖 create/stream/cancel/get/artifacts/local-tool-result，并提供本地只读工具桥协议。 |
+| 1.0.2 | 稳定版 | 修复多进程共享 token refresh rotation 竞态。 |
+| 1.0.1 | 历史稳定版 | 修复 1.0.0 双层 broken packaging:tsup 输出 `.mjs+.cjs` 与 exports 字段对齐;9 处 `declare module` 绑包名 `@acosmi/sdk-ts` 让 d.ts augmentation 在 consumer 视角合并;prepublishOnly 加 packed-tarball 烟测拦截"源码过 / 打包后 broken"。 |
 | 1.0.0 | **deprecated** | 双层 broken:(1) `package.json.exports` 8 处 `.mjs` 引用与 tsup 默认 `.js+.cjs` 错位 → bun/Node ESM `Cannot find module`;(2) 9 处 `declare module` 用相对路径,consumer 视角断链 → 50+ 方法 TS2339。`npm install @acosmi/sdk-ts` 自动跳到 1.0.1。 |
 
 ## License

package/dist/browser/index.mjs

@@ -1972,8 +1972,25 @@ function extractAnthropicBlockMeta(eventType, data, blockTypeMap) {
   }
 }
 
-// src/index.ts
-init_betas();
+// src/agent-runs-types.ts
+var AgentRunStreamError = class extends Error {
+  event;
+  code;
+  stage;
+  retryable;
+  constructor(event) {
+    const err = event.error;
+    super(err.stage ? `agent run failed: ${err.stage}: ${err.message}` : `agent run failed: ${err.message}`);
+    this.name = "AgentRunStreamError";
+    this.event = event;
+    this.code = err.code ?? "";
+    this.stage = err.stage ?? "";
+    this.retryable = err.retryable ?? false;
+  }
+};
+
+// src/client/agent-runs.ts
+init_types();
 
 // src/client.ts
 init_types();
@@ -3254,6 +3271,487 @@ async function sleep(ms, signal) {
   });
 }
 
+// src/client/agent-runs.ts
+var agentRunsByClient = /* @__PURE__ */ new WeakMap();
+Object.defineProperty(Client.prototype, "agentRuns", {
+  configurable: true,
+  enumerable: false,
+  get() {
+    let existing = agentRunsByClient.get(this);
+    if (!existing) {
+      existing = new AgentRunsClient(this);
+      agentRunsByClient.set(this, existing);
+    }
+    return existing;
+  }
+});
+var AgentRunsClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async create(req, signal) {
+    const resp = await this.requestAPI(
+      "POST",
+      "/agent-runs",
+      toWireCreateRequest(req),
+      signal,
+      { retryOn401: false }
+    );
+    return fromWireCreateResponse(resp);
+  }
+  get(runId, signal) {
+    return this.requestAPI(
+      "GET",
+      `/agent-runs/${encodeURIComponent(runId)}`,
+      null,
+      signal,
+      { retryOn401: true }
+    ).then(fromWireRun);
+  }
+  stream(runId, opts = {}, signal) {
+    return {
+      [Symbol.asyncIterator]: () => this.streamGen(runId, opts, signal)
+    };
+  }
+  cancel(runId, signal) {
+    return this.requestAPI(
+      "POST",
+      `/agent-runs/${encodeURIComponent(runId)}/cancel`,
+      {},
+      signal,
+      { retryOn401: false }
+    ).then(fromWireRun);
+  }
+  listArtifacts(runId, signal) {
+    return this.requestAPI(
+      "GET",
+      `/agent-runs/${encodeURIComponent(runId)}/artifacts`,
+      null,
+      signal,
+      { retryOn401: true }
+    ).then((r) => (r.artifacts ?? []).map(fromWireArtifact));
+  }
+  async downloadArtifact(runId, artifactId, signal) {
+    const resp = await this.requestRaw(
+      "GET",
+      `/agent-runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`,
+      null,
+      signal,
+      { retryOn401: true }
+    );
+    const contentType = resp.headers.get("Content-Type") ?? void 0;
+    const filename = filenameFromContentDisposition(resp.headers.get("Content-Disposition")) ?? artifactId;
+    const data = await readLimited(resp.body, maxDownloadSize);
+    return { data, filename, contentType };
+  }
+  submitLocalToolResult(runId, result, signal) {
+    return this.requestAPI(
+      "POST",
+      `/agent-runs/${encodeURIComponent(runId)}/local-tool-results`,
+      toWireLocalToolResult(result),
+      signal,
+      { retryOn401: false }
+    ).then(fromWireRun);
+  }
+  run(req, opts = {}, signal) {
+    return {
+      [Symbol.asyncIterator]: () => this.runGen(req, opts, signal)
+    };
+  }
+  runWithLocalTools(req, handlers, opts = {}, signal) {
+    return {
+      [Symbol.asyncIterator]: () => this.runWithLocalToolsGen(req, handlers, opts, signal)
+    };
+  }
+  async *runGen(req, opts, signal) {
+    const created = await this.create(req, signal);
+    yield* this.stream(created.runId, opts, signal);
+  }
+  async *runWithLocalToolsGen(req, handlers, opts, signal) {
+    let currentRunId = "";
+    for await (const event of this.run(req, opts, signal)) {
+      if (event.type === "run_started") {
+        currentRunId = event.runId;
+      }
+      if (opts.onEvent) await opts.onEvent(event);
+      let localToolTask;
+      if (event.type === "local_tool_request") {
+        if (currentRunId === "") {
+          throw new Error("local tool request arrived before run_started");
+        }
+        localToolTask = this.invokeLocalTool(currentRunId, event, handlers, opts.timeoutMs, signal).then(async (result) => {
+          await this.submitLocalToolResult(currentRunId, result, signal);
+        });
+      }
+      yield event;
+      if (localToolTask) await localToolTask;
+    }
+  }
+  async invokeLocalTool(runId, event, handlers, timeoutMs = 3e4, signal) {
+    const handler = handlers[event.name];
+    if (!handler) {
+      return {
+        requestId: event.requestId,
+        ok: false,
+        error: `local tool rejected: no handler for ${event.name}`
+      };
+    }
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    let parentAbort;
+    if (signal) {
+      if (signal.aborted) ctl.abort();
+      else {
+        parentAbort = () => ctl.abort();
+        signal.addEventListener("abort", parentAbort);
+      }
+    }
+    try {
+      const content = await handler(event.input, {
+        runId,
+        requestId: event.requestId,
+        name: event.name,
+        signal: ctl.signal
+      });
+      return { requestId: event.requestId, ok: true, content };
+    } catch (e) {
+      if (signal?.aborted) throw e;
+      const timedOut = ctl.signal.aborted;
+      return {
+        requestId: event.requestId,
+        ok: false,
+        error: timedOut ? `local tool timed out after ${timeoutMs}ms` : errorMessage(e)
+      };
+    } finally {
+      clearTimeout(timer);
+      if (parentAbort && signal) signal.removeEventListener("abort", parentAbort);
+    }
+  }
+  async *streamGen(runId, opts, signal) {
+    const resp = await this.requestRaw(
+      "GET",
+      `/agent-runs/${encodeURIComponent(runId)}/stream`,
+      null,
+      signal,
+      { retryOn401: true, accept: "text/event-stream" }
+    );
+    if (!resp.body) {
+      throw new Error("agent run stream: empty response body");
+    }
+    for await (const event of readAgentRunEvents(resp.body)) {
+      if (event.type === "error" && opts.throwOnError !== false) {
+        throw new AgentRunStreamError(event);
+      }
+      yield event;
+    }
+  }
+  async requestAPI(method, path, body, signal, opts) {
+    const resp = await this.requestRaw(method, path, body, signal, opts);
+    const text = await resp.text();
+    const result = JSON.parse(text);
+    const bizErr = apiResponseBusinessError(result);
+    if (bizErr) throw bizErr;
+    return result.data;
+  }
+  async requestRaw(method, path, body, signal, opts, retried = false) {
+    const token = await this.client.ensureToken(signal);
+    const url = this.client.apiURL(path);
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: opts.accept ?? "application/json"
+    };
+    let bodyStr;
+    if (body != null) {
+      bodyStr = typeof body === "string" ? body : JSON.stringify(body);
+      headers["Content-Type"] = "application/json";
+    }
+    const resp = await this.client.doRequest({ method, url, headers, body: bodyStr }, signal);
+    if (resp.status === 401 && opts.retryOn401 && !retried) {
+      try {
+        await resp.body?.cancel();
+      } catch {
+      }
+      await this.client.forceRefresh(signal);
+      return this.requestRaw(method, path, body, signal, opts, true);
+    }
+    if (resp.status < 200 || resp.status >= 300) {
+      const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+      throw parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+    }
+    return resp;
+  }
+};
+function toWireCreateRequest(req) {
+  return {
+    app_id: req.appId,
+    mode: req.mode,
+    session_id: req.sessionId,
+    input: req.input,
+    messages: req.messages,
+    model: req.model,
+    active_skill_ids: req.activeSkillIds,
+    knowledge_base_ids: req.knowledgeBaseIds,
+    metadata: req.metadata,
+    local_context_policy: req.localContextPolicy ? {
+      enabled: req.localContextPolicy.enabled,
+      readonly: req.localContextPolicy.readonly,
+      max_bytes: req.localContextPolicy.maxBytes,
+      allowed_tools: req.localContextPolicy.allowedTools
+    } : void 0,
+    artifact_policy: req.artifactPolicy ? {
+      enabled: req.artifactPolicy.enabled,
+      max_files: req.artifactPolicy.maxFiles
+    } : void 0
+  };
+}
+function toWireLocalToolResult(result) {
+  return {
+    request_id: result.requestId,
+    ok: result.ok,
+    content: result.content,
+    error: result.error
+  };
+}
+function fromWireCreateResponse(resp) {
+  return {
+    runId: resp.run_id ?? "",
+    sessionId: resp.session_id ?? "",
+    status: toStatus(resp.status)
+  };
+}
+function fromWireRun(resp) {
+  return {
+    runId: resp.run_id ?? "",
+    sessionId: resp.session_id ?? "",
+    appId: resp.app_id,
+    mode: resp.mode,
+    status: toStatus(resp.status),
+    createdAt: resp.created_at,
+    startedAt: resp.started_at,
+    completedAt: resp.completed_at,
+    error: normalizeError(resp.error),
+    metadata: resp.metadata
+  };
+}
+function fromWireArtifact(resp) {
+  return {
+    id: resp.id ?? resp.artifact_id ?? "",
+    filename: resp.filename ?? resp.name ?? resp.id ?? resp.artifact_id ?? "artifact",
+    contentType: resp.content_type ?? resp.mime_type,
+    size: typeof resp.size === "number" ? resp.size : void 0,
+    type: resp.type,
+    metadata: resp.metadata
+  };
+}
+async function* readAgentRunEvents(body) {
+  let eventName = "";
+  let dataLines = [];
+  const flush = () => {
+    if (dataLines.length === 0) return null;
+    const data = dataLines.join("\n");
+    dataLines = [];
+    if (data === "[DONE]") return null;
+    return parseAgentRunEvent(eventName, data);
+  };
+  for await (const line of iterSSELines(body)) {
+    if (line === "") {
+      const event2 = flush();
+      eventName = "";
+      if (event2) yield event2;
+      continue;
+    }
+    if (line.startsWith(":")) continue;
+    if (line.startsWith("event:")) {
+      eventName = line.slice("event:".length).trim();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice("data:".length).trimStart());
+    }
+  }
+  const event = flush();
+  if (event) yield event;
+}
+function parseAgentRunEvent(eventName, data) {
+  const payload = JSON.parse(data);
+  const obj = isRecord(payload) ? payload : { type: eventName, data: payload };
+  const type = stringField(obj, "type") || eventName;
+  switch (type) {
+    case "run_started":
+      return {
+        type: "run_started",
+        runId: stringField(obj, "run_id", "runId"),
+        sessionId: stringField(obj, "session_id", "sessionId")
+      };
+    case "status":
+      return {
+        type: "status",
+        status: stringField(obj, "status"),
+        message: optionalStringField(obj, "message")
+      };
+    case "text_delta":
+      return { type: "text_delta", text: stringField(obj, "text") };
+    case "reasoning_delta":
+      return { type: "reasoning_delta", text: stringField(obj, "text") };
+    case "tool_call":
+      return {
+        type: "tool_call",
+        id: stringField(obj, "id"),
+        name: stringField(obj, "name"),
+        input: obj.input
+      };
+    case "tool_result":
+      return {
+        type: "tool_result",
+        id: stringField(obj, "id"),
+        name: optionalStringField(obj, "name"),
+        result: obj.result,
+        error: optionalStringField(obj, "error")
+      };
+    case "local_tool_request":
+      return {
+        type: "local_tool_request",
+        requestId: stringField(obj, "request_id", "requestId"),
+        name: stringField(obj, "name"),
+        input: obj.input
+      };
+    case "artifact":
+      return {
+        type: "artifact",
+        artifact: fromWireArtifact(isRecord(obj.artifact) ? obj.artifact : obj)
+      };
+    case "sources":
+      return { type: "sources", sources: obj.sources };
+    case "usage":
+      return {
+        type: "usage",
+        usage: normalizeUsage(isRecord(obj.usage) ? obj.usage : obj)
+      };
+    case "settle":
+      return {
+        type: "settle",
+        settlement: normalizeSettlement(isRecord(obj.settlement) ? obj.settlement : obj)
+      };
+    case "error":
+      return { type: "error", error: normalizeError(obj.error) ?? normalizeError(obj) };
+    case "done":
+      return {
+        type: "done",
+        runId: stringField(obj, "run_id", "runId"),
+        status: stringField(obj, "status")
+      };
+    default:
+      return {
+        type: "error",
+        error: {
+          code: "unknown_event",
+          message: `unknown agent run event: ${type}`,
+          raw: obj
+        }
+      };
+  }
+}
+function normalizeUsage(value) {
+  return {
+    ...value,
+    inputTokens: numberField(value, "input_tokens", "inputTokens"),
+    outputTokens: numberField(value, "output_tokens", "outputTokens"),
+    totalTokens: numberField(value, "total_tokens", "totalTokens"),
+    cacheReadTokens: numberField(value, "cache_read_tokens", "cacheReadTokens"),
+    cacheCreateTokens: numberField(value, "cache_create_tokens", "cacheCreateTokens"),
+    exact: booleanField(value, "exact"),
+    source: optionalStringField(value, "source")
+  };
+}
+function normalizeSettlement(value) {
+  return {
+    ...value,
+    requestId: optionalStringField(value, "request_id", "requestId"),
+    status: optionalStringField(value, "status"),
+    consumeStatus: optionalStringField(value, "consume_status", "consumeStatus"),
+    inputTokens: numberField(value, "input_tokens", "inputTokens"),
+    outputTokens: numberField(value, "output_tokens", "outputTokens"),
+    totalTokens: numberField(value, "total_tokens", "totalTokens"),
+    cacheReadTokens: numberField(value, "cache_read_tokens", "cacheReadTokens"),
+    cacheCreateTokens: numberField(value, "cache_create_tokens", "cacheCreateTokens"),
+    tokenRemaining: numberField(value, "token_remaining", "tokenRemaining"),
+    callRemaining: numberField(value, "call_remaining", "callRemaining"),
+    retryQueued: booleanField(value, "retry_queued", "retryQueued"),
+    exact: booleanField(value, "exact")
+  };
+}
+function normalizeError(value) {
+  if (value == null) return void 0;
+  if (typeof value === "string") return { message: value, raw: value };
+  if (!isRecord(value)) return { message: String(value), raw: value };
+  return {
+    code: optionalStringField(value, "code", "error_code", "errorCode"),
+    message: stringField(value, "message", "error") || "agent run failed",
+    stage: optionalStringField(value, "stage"),
+    retryable: typeof value.retryable === "boolean" ? value.retryable : void 0,
+    raw: value
+  };
+}
+function toStatus(status) {
+  switch (status) {
+    case "running":
+    case "completed":
+    case "failed":
+    case "cancelled":
+      return status;
+    default:
+      return "queued";
+  }
+}
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function stringField(obj, ...keys) {
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === "string") return value;
+  }
+  return "";
+}
+function optionalStringField(obj, ...keys) {
+  const value = stringField(obj, ...keys);
+  return value === "" ? void 0 : value;
+}
+function numberField(obj, ...keys) {
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return void 0;
+}
+function booleanField(obj, ...keys) {
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === "boolean") return value;
+  }
+  return void 0;
+}
+function filenameFromContentDisposition(value) {
+  if (!value) return null;
+  const utf8 = /filename\*=UTF-8''([^;]+)/i.exec(value);
+  if (utf8?.[1]) {
+    try {
+      return decodeURIComponent(utf8[1]);
+    } catch {
+      return utf8[1];
+    }
+  }
+  const plain = /filename="?([^";]+)"?/i.exec(value);
+  return plain?.[1] ?? null;
+}
+function errorMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+
+// src/index.ts
+init_betas();
+
 // src/client/entitlements.ts
 Client.prototype.getBalance = async function(signal) {
   const resp = await this.doJSON(
@@ -4078,6 +4576,6 @@ Client.prototype.getBugReport = async function(bugID, signal) {
   return resp.data;
 };
 
-export { AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, 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, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, getAdapter, getAdapterForModel, isSSLError, modelScopes, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
+export { AgentRunStreamError, AgentRunsClient, AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, 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, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, getAdapter, getAdapterForModel, isSSLError, modelScopes, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map