@acosmi/sdk-ts 1.0.1 → 1.1.0

package/dist/node/index.cjs

@@ -1405,9 +1405,18 @@ function skillScopes() {
 }
 
 // src/store.ts
+var fileLockDefaults = {
+  /** 获取锁的超时上限 (毫秒). refresh 流程含网络 < 30s, 30s 已远超正常完成时间. */
+  acquireTimeoutMs: 3e4,
+  /** 旧锁判定阈值 (毫秒). 锁文件 mtime 早于此值视为 stale 进程崩溃残留, 自动 break. */
+  staleMs: 6e4,
+  /** 重试间隔基数 (毫秒). 真实间隔 = base + random(0, jitter). */
+  retryBaseMs: 30,
+  retryJitterMs: 70
+};
 var FileTokenStore = class {
   path;
-  /** 简单串行化锁 (替代 Go sync.Mutex) */
+  /** 进程内串行化 (Promise chain) — 与跨进程 flock 配合, 避免单进程内并发持锁产生死锁式互等. */
   chain = Promise.resolve();
   constructor(path) {
     if (typeof process === "undefined" || !process.versions || !process.versions.node) {
@@ -1426,7 +1435,9 @@ var FileTokenStore = class {
     this.path = path.join(os.homedir(), ".acosmi", "tokens.json");
     return this.path;
   }
-  withLock(fn) {
+  /** 进程内串行 (维持 v1.0.1 单进程语义). flock 之外另一层防御: 如果用户自己就是单进程
+   *  并发场景, 不必每次都进 flock 旁路文件 IO. */
+  withChain(fn) {
     const next = this.chain.then(fn, fn);
     this.chain = next.then(
       () => void 0,
@@ -1434,19 +1445,106 @@ var FileTokenStore = class {
     );
     return next;
   }
+  /**
+   * 跨进程临界区. 用 sidecar `<path>.lock` 文件 + O_EXCL 创建语义实现互斥:
+   *   - 创建成功 = 持有锁; 写入 pid+timestamp 便于诊断
+   *   - 创建失败 (EEXIST) = 别的进程持锁, backoff 重试
+   *   - 锁文件 mtime > staleMs = 进程崩溃残留, unlink 后重试
+   *   - acquireTimeoutMs 超时 = 抛错 (caller 应作为 transient error 处理, 上层 retry)
+   *
+   * 注意: O_EXCL 在 NFS 上不保证原子; FileTokenStore 适用于本地文件系统 (典型用户家目录).
+   * 真要跨机共享 token, 应实现自定义 Keychain / 数据库 store, 不要用 FileTokenStore.
+   */
+  async withLock(fn) {
+    const fs = await import('fs/promises');
+    const pathMod = await import('path');
+    const p = await this.resolvePath();
+    const lockPath = `${p}.lock`;
+    const dir = pathMod.dirname(p);
+    await fs.mkdir(dir, { recursive: true, mode: 448 });
+    const startMs = Date.now();
+    let release = null;
+    while (true) {
+      try {
+        const fh = await fs.open(lockPath, "wx", 384);
+        try {
+          await fh.writeFile(`${process.pid}
+${Date.now()}
+`, "utf8");
+        } finally {
+          await fh.close();
+        }
+        release = async () => {
+          try {
+            await fs.unlink(lockPath);
+          } catch {
+          }
+        };
+        break;
+      } catch (e) {
+        if (!isAlreadyExistsError(e)) throw e;
+        let stale = false;
+        try {
+          const st = await fs.stat(lockPath);
+          if (Date.now() - st.mtimeMs > fileLockDefaults.staleMs) stale = true;
+        } catch {
+          continue;
+        }
+        if (stale) {
+          try {
+            await fs.unlink(lockPath);
+          } catch {
+          }
+          continue;
+        }
+        if (Date.now() - startMs > fileLockDefaults.acquireTimeoutMs) {
+          throw new Error(
+            `acquire token file lock timeout (${fileLockDefaults.acquireTimeoutMs}ms): ${lockPath}`
+          );
+        }
+        const waitMs = fileLockDefaults.retryBaseMs + Math.random() * fileLockDefaults.retryJitterMs;
+        await new Promise((r) => setTimeout(r, waitMs));
+      }
+    }
+    try {
+      return await fn();
+    } finally {
+      if (release) await release();
+    }
+  }
+  /**
+   * 写入 token. 流程:
+   *   1. mkdir -p (默认路径目录)
+   *   2. 写入 `<path>.tmp.<pid>`
+   *   3. fsync 后 rename 到正式路径 (POSIX 上 rename(2) 同分区原子, Windows 上 ReplaceFile)
+   *
+   * 选择 atomic rename 而非直接 writeFile: 多进程并发或本进程崩溃时, 读端永远看到的是
+   * 完整的旧/新 JSON, 不会读到截断半文件 (Client.create.store.load 可能在另一进程
+   * 写入中间触发, atomic rename 避免它解析失败).
+   */
   save(tokens) {
-    return this.withLock(async () => {
+    return this.withChain(async () => {
       const fs = await import('fs/promises');
-      const path = await import('path');
+      const pathMod = await import('path');
       const p = await this.resolvePath();
-      const dir = path.dirname(p);
+      const dir = pathMod.dirname(p);
       await fs.mkdir(dir, { recursive: true, mode: 448 });
+      const tmp = `${p}.tmp.${process.pid}.${Date.now()}.${Math.floor(Math.random() * 1e6)}`;
       const data = JSON.stringify(tokens, null, 2);
-      await fs.writeFile(p, data, { encoding: "utf8", mode: 384 });
+      await fs.writeFile(tmp, data, { encoding: "utf8", mode: 384 });
+      try {
+        await fs.rename(tmp, p);
+      } catch (e) {
+        try {
+          await fs.unlink(tmp);
+        } catch {
+        }
+        throw e;
+      }
     });
   }
   load() {
-    return this.withLock(async () => {
+    return this.withChain(async () => {
       const fs = await import('fs/promises');
       const p = await this.resolvePath();
       try {
@@ -1461,7 +1559,7 @@ var FileTokenStore = class {
     });
   }
   clear() {
-    return this.withLock(async () => {
+    return this.withChain(async () => {
       const fs = await import('fs/promises');
       const p = await this.resolvePath();
       try {
@@ -1479,6 +1577,12 @@ function isNotExistError(e) {
   }
   return false;
 }
+function isAlreadyExistsError(e) {
+  if (typeof e === "object" && e !== null && "code" in e) {
+    return e.code === "EEXIST";
+  }
+  return false;
+}
 function newFileTokenStore(path) {
   return new FileTokenStore(path);
 }
@@ -1870,8 +1974,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();
@@ -2345,61 +2466,67 @@ var Client = class _Client {
     if (!tokenSetIsExpired(tokens)) {
       return tokens.access_token;
     }
-    return this.withMu(async () => {
-      if (this.tokens == null) {
-        throw new Error("not authorized, call login() first");
-      }
-      if (!tokenSetIsExpired(this.tokens)) {
-        return this.tokens.access_token;
-      }
-      if (this.meta == null) {
+    return this.withMu(
+      () => this.storeWithLock(async () => {
+        await this.syncFromDisk();
+        if (this.tokens == null) {
+          throw new Error("not authorized, call login() first");
+        }
+        if (!tokenSetIsExpired(this.tokens)) {
+          return this.tokens.access_token;
+        }
+        if (this.meta == null) {
+          try {
+            this.meta = await discover(this.serverURL, signal);
+          } catch (e) {
+            throw new Error(
+              `discover for refresh: ${e instanceof Error ? e.message : String(e)}`
+            );
+          }
+        }
+        let tokenResp;
         try {
-          this.meta = await discover(this.serverURL, signal);
+          tokenResp = await refreshToken(this.meta, this.tokens.client_id, this.tokens.refresh_token, signal);
         } catch (e) {
-          throw new Error(
-            `discover for refresh: ${e instanceof Error ? e.message : String(e)}`
-          );
+          throw new Error(`refresh token: ${e instanceof Error ? e.message : String(e)}`);
         }
-      }
-      let tokenResp;
-      try {
-        tokenResp = await refreshToken(this.meta, this.tokens.client_id, this.tokens.refresh_token, signal);
-      } catch (e) {
-        throw new Error(`refresh token: ${e instanceof Error ? e.message : String(e)}`);
-      }
-      this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
-      try {
-        await this.store.save(this.tokens);
-      } catch (e) {
-        console.warn(`[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`);
-      }
-      return this.tokens.access_token;
-    });
+        this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
+        try {
+          await this.store.save(this.tokens);
+        } catch (e) {
+          console.warn(`[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return this.tokens.access_token;
+      })
+    );
   }
   /** 强制刷新 token (用于 401 重试) */
   async forceRefresh(signal) {
-    return this.withMu(async () => {
-      if (this.tokens == null) {
-        throw new Error("no tokens to refresh");
-      }
-      if (this.meta == null) {
-        this.meta = await discover(this.serverURL, signal);
-      }
-      const tokenResp = await refreshToken(
-        this.meta,
-        this.tokens.client_id,
-        this.tokens.refresh_token,
-        signal
-      );
-      this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
-      try {
-        await this.store.save(this.tokens);
-      } catch (e) {
-        console.warn(
-          `[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`
+    return this.withMu(
+      () => this.storeWithLock(async () => {
+        await this.syncFromDisk();
+        if (this.tokens == null) {
+          throw new Error("no tokens to refresh");
+        }
+        if (this.meta == null) {
+          this.meta = await discover(this.serverURL, signal);
+        }
+        const tokenResp = await refreshToken(
+          this.meta,
+          this.tokens.client_id,
+          this.tokens.refresh_token,
+          signal
         );
-      }
-    });
+        this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
+        try {
+          await this.store.save(this.tokens);
+        } catch (e) {
+          console.warn(
+            `[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`
+          );
+        }
+      })
+    );
   }
   /** 互斥锁 helper (替代 Go sync.Mutex) */
   withMu(fn) {
@@ -2410,6 +2537,29 @@ var Client = class _Client {
     );
     return next;
   }
+  /** v1.0.2: 跨进程临界区 helper. store.withLock 可选, 缺省则直接调用 fn (LocalStorage /
+   *  InMemory 单进程无需). */
+  async storeWithLock(fn) {
+    const lock = this.store.withLock;
+    if (typeof lock === "function") {
+      return lock.call(this.store, fn);
+    }
+    return fn();
+  }
+  /** v1.0.2: 从磁盘同步 token (refresh 前). 别的进程 rotation 后磁盘 refresh_token 已变,
+   *  本进程内存仍是旧 R0; 不同步直接 refresh 必撞网关 400. load 失败保留内存继续 (容错). */
+  async syncFromDisk() {
+    let onDisk = null;
+    try {
+      onDisk = await this.store.load();
+    } catch {
+      return;
+    }
+    if (!onDisk) return;
+    if (this.tokens == null || onDisk.refresh_token !== this.tokens.refresh_token) {
+      this.tokens = onDisk;
+    }
+  }
   // ===========================================================================
   // Managed Models
   // ===========================================================================
@@ -3123,6 +3273,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(
@@ -3947,6 +4578,8 @@ Client.prototype.getBugReport = async function(bugID, signal) {
   return resp.data;
 };
 
+exports.AgentRunStreamError = AgentRunStreamError;
+exports.AgentRunsClient = AgentRunsClient;
 exports.Client = Client;
 exports.DefaultRetryPolicy = DefaultRetryPolicy;
 exports.ErrAuthDenied = ErrAuthDenied;
@@ -4002,6 +4635,7 @@ exports.discover = discover;
 exports.effectivePolicy = effectivePolicy;
 exports.exchangeCode = exchangeCode;
 exports.extractAnthropicBlockMeta = extractAnthropicBlockMeta;
+exports.fileLockDefaults = fileLockDefaults;
 exports.getAdapter = getAdapter;
 exports.getAdapterForModel = getAdapterForModel;
 exports.isSSLError = isSSLError;