@cursor/july 0.1.29 → 0.1.31

package/src/files-backends/local-fs.ts

@@ -0,0 +1,178 @@
+/**
+ * Local-disk file sink: one file per key under a directory you own.
+ *
+ * The default off Cursor-managed hosting. Paths are real, so the harness can
+ * open a file with its ordinary tools — that is why this reports
+ * `materialized` — and there are no etags, so `conflictDetection` is honestly
+ * false and concurrent writers are last-writer-wins.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import {
+  FilePathRejectedError,
+  type FileSink,
+  type FileSinkBody,
+  type FileSinkEntry,
+} from "../files.js";
+
+export interface LocalFilesOptions {
+  /** Directory the sink owns. */
+  filesRoot: string;
+  /**
+   * Prefix trimmed off each key before building the on-disk path, so the tree
+   * reads `deployment/notes.md` instead of repeating the framework key root.
+   *
+   * Framework-supplied. Authors should omit it: the value has to match the
+   * internal key scheme exactly, and a near-miss would silently nest files
+   * under a redundant path instead of failing. Omitted, keys are stored
+   * verbatim, which is always correct and lets two agents share one root.
+   */
+  stripKeyPrefix?: string;
+}
+
+/**
+ * Default sink: one file per key under the state root, written atomically.
+ *
+ * Reports `materialized` because the paths are real — that is what lets the
+ * harness read a file with its ordinary tools — and reports no `etags`, so
+ * `host.files.capabilities.conflictDetection` is honestly false and concurrent
+ * writers are last-writer-wins.
+ */
+export function localFiles(options: LocalFilesOptions): FileSink {
+  const root = resolve(options.filesRoot);
+
+  const stripPrefix = options.stripKeyPrefix ?? "";
+  const pathForKey = (key: string): string => {
+    const rel =
+      stripPrefix !== "" && key.startsWith(stripPrefix)
+        ? key.slice(stripPrefix.length)
+        : key;
+    const candidate = resolve(root, rel);
+    const within = relative(root, candidate);
+    if (within === "" || within === ".." || within.startsWith(`..${sep}`)) {
+      throw new FilePathRejectedError(
+        `host.files key does not resolve under the state root: ${key}`
+      );
+    }
+    return candidate;
+  };
+
+  const entryFor = async (
+    key: string,
+    absPath: string
+  ): Promise<FileSinkEntry | undefined> => {
+    try {
+      const info = await stat(absPath);
+      if (!info.isFile()) {
+        return undefined;
+      }
+      return { key, size: info.size, mtimeMs: info.mtimeMs };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  };
+
+  return {
+    capabilities: { materialized: true },
+
+    materializedPath: (key) => pathForKey(key),
+
+    async put(key, body): Promise<void> {
+      const target = pathForKey(key);
+      await mkdir(join(target, ".."), { recursive: true });
+      // Same-directory temp + rename: a reader either sees the previous value
+      // or the whole new one, never a half-written file.
+      const tmp = join(target, "..", `.tmp-${randomUUID()}`);
+      try {
+        await writeFile(tmp, body);
+        await rename(tmp, target);
+      } catch (error) {
+        await rm(tmp, { force: true });
+        throw error;
+      }
+    },
+
+    async get(key): Promise<FileSinkBody | undefined> {
+      try {
+        return { body: new Uint8Array(await readFile(pathForKey(key))) };
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "ENOENT" || code === "EISDIR") {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+
+    async delete(key): Promise<void> {
+      await rm(pathForKey(key), { force: true });
+    },
+
+    async stat(key): Promise<FileSinkEntry | undefined> {
+      return await entryFor(key, pathForKey(key));
+    },
+
+    async list(prefix): Promise<FileSinkEntry[]> {
+      // Walk the deepest existing directory at or above the prefix, then keep
+      // the keys that actually start with it — `prefix` is a key prefix, not a
+      // directory, so `notes/sum` must match `notes/summary.md`.
+      const prefixPath = pathForKey(prefix);
+      const searchRoot = (await isDirectory(prefixPath))
+        ? prefixPath
+        : join(prefixPath, "..");
+      const out: FileSinkEntry[] = [];
+      for await (const absPath of walkFiles(searchRoot)) {
+        const key = `${stripPrefix}${relative(root, absPath).split(sep).join("/")}`;
+        if (!key.startsWith(prefix)) {
+          continue;
+        }
+        const entry = await entryFor(key, absPath);
+        if (entry !== undefined) {
+          out.push(entry);
+        }
+      }
+      return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    },
+  };
+}
+
+async function isDirectory(absPath: string): Promise<boolean> {
+  try {
+    return (await stat(absPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function* walkFiles(dir: string): AsyncGenerator<string> {
+  let entries: Awaited<ReturnType<typeof readdir>>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  for (const entry of entries) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(abs);
+    } else if (entry.isFile() && !entry.name.startsWith(".tmp-")) {
+      yield abs;
+    }
+  }
+}

package/src/files.ts

@@ -0,0 +1,195 @@
+/**
+ * The internal sink contract behind `ctx.host.files` — durable, file-shaped
+ * state that must outlive the engine process.
+ *
+ * Deliberately **not a filesystem**: no file descriptors, no seeking, no
+ * rename, no directories as first-class objects, and no POSIX errno contract
+ * — a sink that is an HTTP API can implement all of it. The framework
+ * **mints every key** from a stable, versioned scheme (see {@link fileKeys});
+ * sinks see opaque strings and never learn which deployment or session a key
+ * belongs to, which is what keeps one deployment's files unreachable from
+ * another's.
+ *
+ * Internal for now: the authored plug-in surface (`agent/files.ts` with a
+ * `defineFiles`, mirroring `defineStorage`) is deliberately deferred so this
+ * ships as exactly the hosted connector plus the local default. When it
+ * lands, {@link FileSink} is the contract authored sinks implement.
+ *
+ * Delivery semantics differ from {@link import("./storage.js").defineStorage}
+ * on purpose. Storage is a fire-and-forget mirror of framework state, so a
+ * throwing `put` is logged and dropped. Files are author data the next turn
+ * may depend on, so {@link HostFilesApi} writes are **awaited and surface
+ * their failure** — an author who writes evidence and then delegates has to
+ * know the write did not land.
+ */
+
+import { STORAGE_KEY_ROOT } from "./storage.js";
+
+// ============================================================================
+// Sink interface
+// ============================================================================
+
+/** One entry returned by {@link FileSink.list}. */
+export interface FileSinkEntry {
+  /** Framework-minted key, as passed to {@link FileSink.put}. */
+  key: string;
+  size: number;
+  /** Last-modified epoch ms, when the sink tracks one. */
+  mtimeMs?: number;
+  /** Opaque version tag; required for `ifMatch` to be usable. */
+  etag?: string;
+}
+
+/** One stored value plus the version it was read at. */
+export interface FileSinkBody {
+  body: Uint8Array;
+  etag?: string;
+}
+
+/** Outcome of {@link FileSink.put}. */
+export interface FileSinkPutResult {
+  /** Version tag after the write, when the sink issues one. */
+  etag?: string;
+}
+
+/**
+ * What a sink can do beyond the four required calls. Absent flags are false,
+ * so the narrowest possible sink — four functions over an HTTP API — is valid
+ * and the framework degrades visibly rather than assuming.
+ */
+export interface FileSinkCapabilities {
+  /**
+   * `put` honors `ifMatch` and rejects a stale write. Required for
+   * {@link HostFilesApi} to report `conflictDetection`.
+   */
+  etags?: boolean;
+  /**
+   * The sink keeps a local copy at {@link FileSink.materializedPath} that the
+   * harness can read with ordinary file tools.
+   */
+  materialized?: boolean;
+  /** Largest value the sink accepts, in bytes. */
+  maxBytes?: number;
+}
+
+/**
+ * The pluggable file store. Keys are framework-minted opaque strings; a sink
+ * may treat them as flat keys or split on `/` to build a hierarchy.
+ */
+export interface FileSink {
+  /**
+   * Write or replace one value. When `ifMatch` is set and the sink reports
+   * {@link FileSinkCapabilities.etags}, the write must fail unless the stored
+   * version matches — throw {@link FileConflictError} to say so precisely.
+   * `ifMatch: null` means "must not already exist".
+   */
+  put(
+    key: string,
+    body: Uint8Array,
+    options?: { ifMatch?: string | null }
+  ): Promise<FileSinkPutResult | void>;
+  /** Read one value. Miss → `undefined`. */
+  get(key: string): Promise<FileSinkBody | Uint8Array | undefined>;
+  /** Remove one key. No-op when missing. */
+  delete(key: string): Promise<void>;
+  /** Entries whose key starts with `prefix`, in key order. */
+  list(prefix: string): Promise<FileSinkEntry[]>;
+  /** Per-key metadata without transferring the body. Optional; `list` is the fallback. */
+  stat?(key: string): Promise<FileSinkEntry | undefined>;
+  /**
+   * Absolute path of the sink's local copy of `key`, or `undefined` when it
+   * keeps none. Only consulted when
+   * {@link FileSinkCapabilities.materialized} is set.
+   */
+  materializedPath?(key: string): string | undefined;
+  capabilities?: FileSinkCapabilities;
+}
+
+// ============================================================================
+// Key scheme
+// ============================================================================
+
+/**
+ * The framework-owned file key scheme, a stable versioned contract under
+ * {@link STORAGE_KEY_ROOT}. Sinks may treat these as opaque, or route on
+ * prefixes.
+ *
+ * | Key | Holds |
+ * | --- | --- |
+ * | `agentkit/v1/{agent}/files/deployment/{path}` | Deployment-scoped file, shared by every session and surviving redeploys |
+ * | `agentkit/v1/{agent}/files/deployment/{partition}/{path}` | Deployment-scoped file under an author partition (a PR, a customer, a branch) |
+ * | `agentkit/v1/{agent}/files/sessions/{sessionId}/{path}` | Session-scoped file |
+ *
+ * Scoping lives here, above the sink, so a sink cannot be handed a key for a
+ * deployment or session other than its own.
+ */
+export const fileKeys = {
+  deployment: (agent: string, path: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/files/deployment/${path}`,
+  deploymentPartition: (
+    agent: string,
+    partition: string,
+    path: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/files/deployment/${partition}/${path}`,
+  session: (agent: string, sessionId: string, path: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/files/sessions/${sessionId}/${path}`,
+  deploymentPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/files/deployment/`,
+  sessionPrefix: (agent: string, sessionId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/files/sessions/${sessionId}/`,
+} as const;
+
+/** Errors raised by the file surface. Thrown by sinks and by the framework. */
+export class FileConflictError extends Error {
+  constructor(
+    readonly key: string,
+    options?: { cause?: unknown; storedEtag?: string }
+  ) {
+    super(
+      `host.files write for "${key}" lost a race with another writer${
+        options?.storedEtag === undefined
+          ? ""
+          : ` (stored version ${options.storedEtag})`
+      }`
+    );
+    this.name = "FileConflictError";
+    if (options?.cause !== undefined) {
+      this.cause = options.cause;
+    }
+    if (options?.storedEtag !== undefined) {
+      this.storedEtag = options.storedEtag;
+    }
+  }
+  storedEtag?: string;
+}
+
+/** A path the framework refuses to mint a key for. */
+export class FilePathRejectedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FilePathRejectedError";
+  }
+}
+
+/** A session-scoped call with no session in scope. */
+export class FileSessionRequiredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FileSessionRequiredError";
+  }
+}
+
+/** A value larger than the sink accepts. */
+export class FileTooLargeError extends Error {
+  constructor(
+    readonly key: string,
+    readonly size: number,
+    readonly maxBytes: number
+  ) {
+    super(
+      `host.files value for "${key}" is ${size} bytes, over the sink's ${maxBytes}-byte limit`
+    );
+    this.name = "FileTooLargeError";
+  }
+}

package/src/internal/ab-collector.ts

@@ -147,7 +147,7 @@ export class ABCollector {
           },
           (key, error) => {
             this.logger(
-              `[agentkit] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`
+              `[agent-sdk] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`
             );
           }
         );
@@ -174,7 +174,7 @@ export class ABCollector {
           await def.onSample(sample);
         } catch (error) {
           this.logger(
-            `[agentkit] ab "${experiment.name}" onSample threw: ${describeError(error)}`
+            `[agent-sdk] ab "${experiment.name}" onSample threw: ${describeError(error)}`
           );
         }
         this.persistSample?.(sample);

package/src/internal/ab-fold.ts

@@ -161,7 +161,7 @@ export async function applyABDerive(
         ctx,
         (key, error) => {
           logger(
-            `[agentkit] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`
+            `[agent-sdk] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`
           );
         }
       );

package/src/internal/cli-ax.ts

@@ -1863,8 +1863,8 @@ const COST_FETCH_CONCURRENCY = 4;
  * With a session id: per-turn token usage + estimated cost for that session.
  * Without one: one row per session (all sessions on the target) plus a
  * total row. `--json` prints the underlying report(s); text is the default.
- * Costs are the engine's recorded estimates on `turn.completed` events
- * (see `model-pricing.ts`); turns persisted before cost tracking simply
+ * Costs are recorded on `turn.completed` via `POST /v1/models/estimate-cost`
+ * (billed usage when available). Turns persisted before cost tracking simply
  * count as unpriced.
  */
 export async function cmdCost(

package/src/internal/cli-deploy.ts

@@ -1,5 +1,5 @@
 /**
- * `agentkit deploy | deployments | deployment | stop | rotate-token |
+ * `agent-sdk deploy | deployments | deployment | stop | rotate-token |
  * rotate-pod-credential | secrets set|list|unset` — Heroku-style deploys
  * onto Cursor's managed agent-serve hosting.
  *
@@ -554,7 +554,7 @@ async function deployOne(
   const { dir, slug } = target;
 
   // Fill --repo/--ref/--path from the local git checkout when omitted so
-  // `agentkit deploy` inside an agent directory is enough. Only probe git
+  // `agent-sdk deploy` inside an agent directory is enough. Only probe git
   // for real agent projects (avoids ambient monorepo remotes when someone
   // deploys a bare --slug). Explicit flags always win.
   const isAgent = await isAgentProjectDir(dir);
@@ -968,6 +968,11 @@ export async function cmdDeploymentStatus(
   ) {
     lines.push(`  service account: ${detail.serviceAccountId}`);
   }
+  if (detail.agentStoreSourceId !== undefined) {
+    // The durable file store's address: GET /v0/agent-serve-files/<id> lists
+    // it, and the pod sees it as AGENT_SERVE_STORE_SOURCE_ID.
+    lines.push(`  file store:  ${detail.agentStoreSourceId}`);
+  }
   if (
     detail.egressAllowedDomains !== undefined &&
     detail.egressAllowedDomains.length > 0

package/src/internal/cli-docs.ts

@@ -1,5 +1,5 @@
 /**
- * `agentkit docs` / `npx @cursor/july docs` — serve the shipped VitePress
+ * `agent-sdk docs` / `npx @cursor/july docs` — serve the shipped VitePress
  * site on loopback and open it in a browser. Does not start an agent host.
  */
 

package/src/internal/cli-github.ts

@@ -196,7 +196,7 @@ async function cmdGithubForward(options: GithubCliOptions): Promise<number> {
       );
       return 1;
     }
-    process.stderr.write(`[agentkit] inferred --repo ${repo}\n`);
+    process.stderr.write(`[agent-sdk] inferred --repo ${repo}\n`);
   }
 
   const secret = options.secret ?? process.env.GITHUB_WEBHOOK_SECRET;
@@ -219,30 +219,30 @@ async function cmdGithubForward(options: GithubCliOptions): Promise<number> {
   });
 
   process.stderr.write(
-    `[agentkit] forwarding ${org !== undefined ? `org ${org}` : `repo ${repo}`} to ${targets.length} channel${targets.length === 1 ? "" : "s"}:\n`
+    `[agent-sdk] forwarding ${org !== undefined ? `org ${org}` : `repo ${repo}`} to ${targets.length} channel${targets.length === 1 ? "" : "s"}:\n`
   );
   for (const target of targets) {
     process.stderr.write(
-      `[agentkit]   → ${targetLabel(target)}  ${target.url}  (${target.events.join(", ")})\n`
+      `[agent-sdk]   → ${targetLabel(target)}  ${target.url}  (${target.events.join(", ")})\n`
     );
   }
   if (fanout) {
     process.stderr.write(
-      `[agentkit] fan-out proxy on ${forwardUrl} (union events: ${events.join(", ")})\n`
+      `[agent-sdk] fan-out proxy on ${forwardUrl} (union events: ${events.join(", ")})\n`
     );
   }
   if (secret === undefined || secret === "") {
     process.stderr.write(
-      "[agentkit] no signing secret — deliveries are unsigned. A `serve --dev` github channel accepts them; set GITHUB_WEBHOOK_SECRET on both sides to verify signatures (required for a non-dev target).\n"
+      "[agent-sdk] no signing secret — deliveries are unsigned. A `serve --dev` github channel accepts them; set GITHUB_WEBHOOK_SECRET on both sides to verify signatures (required for a non-dev target).\n"
     );
   }
   const envToken = detectGitHubEnvTokenOverride();
   if (envToken !== undefined) {
     process.stderr.write(
-      `[agentkit] warning: ${githubEnvTokenHint(envToken)}\n`
+      `[agent-sdk] warning: ${githubEnvTokenHint(envToken)}\n`
     );
   }
-  process.stderr.write(`[agentkit] running: gh ${redact(args)}\n`);
+  process.stderr.write(`[agent-sdk] running: gh ${redact(args)}\n`);
 
   try {
     return await spawnGh(args);
@@ -318,7 +318,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
   );
   if (unsupported.length > 0) {
     process.stderr.write(
-      `[agentkit] cannot synthesize (skipped): ${unsupported.join(", ")}\n`
+      `[agent-sdk] cannot synthesize (skipped): ${unsupported.join(", ")}\n`
     );
   }
   if (eventsToReplay.length === 0) {
@@ -364,7 +364,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
       check,
     });
     if ("error" in result) {
-      process.stderr.write(`[agentkit] skipping ${event}: ${result.error}\n`);
+      process.stderr.write(`[agent-sdk] skipping ${event}: ${result.error}\n`);
       continue;
     }
     synthesized.push(result);
@@ -376,7 +376,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
 
   const secret = options.secret ?? process.env.GITHUB_WEBHOOK_SECRET;
   process.stderr.write(
-    `[agentkit] replaying ${ref.label} (${synthesized
+    `[agent-sdk] replaying ${ref.label} (${synthesized
       .map((s) => s.eventName)
       .join(
         ", "
@@ -399,7 +399,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
 
     if (options.out !== undefined) {
       const file = await writeReplayFixture(options.out, event);
-      process.stderr.write(`[agentkit] wrote ${file}\n`);
+      process.stderr.write(`[agent-sdk] wrote ${file}\n`);
     }
 
     const label = eventLabel(event);
@@ -434,7 +434,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
               `${delivery.label} ${delivery.status || "ERR"}${delivery.ok ? "" : " (rejected)"}`
           )
           .join(", ") || "(no matching channel)";
-      process.stderr.write(`[agentkit]   ${label} → ${summary}\n`);
+      process.stderr.write(`[agent-sdk]   ${label} → ${summary}\n`);
     }
   }
 
@@ -745,7 +745,7 @@ async function ensureWebhookExtension(
     };
   }
   process.stderr.write(
-    `[agentkit] installing ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}…\n`
+    `[agent-sdk] installing ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}…\n`
   );
   if (
     (await tryExec({

package/src/internal/cli-mcp-oauth.ts

@@ -1,5 +1,5 @@
 /**
- * `agentkit mcp oauth <connection> [--store]`.
+ * `agent-sdk mcp oauth <connection> [--store]`.
  *
  * Host MCP OAuth for `defineConnection({ url, oauth: true })` (local tokens,
  * optionally stored as deployment secrets), and service-account connector
@@ -109,7 +109,7 @@ export async function cmdMcpOauth(
     },
   });
 
-  const client = new Client({ name: "agentkit-mcp-oauth", version: "0.1.0" });
+  const client = new Client({ name: "agent-sdk-mcp-oauth", version: "0.1.0" });
   const url = new URL(transport.url);
   const requestInit =
     transport.headers === undefined

package/src/internal/cli-mcp.ts

@@ -1,5 +1,5 @@
 /**
- * `agentkit mcp` — stdio ↔ streamable-HTTP proxy for an agent's MCP endpoint.
+ * `agent-sdk mcp` — stdio ↔ streamable-HTTP proxy for an agent's MCP endpoint.
  *
  * Every served agent is an MCP server at `<base>/v1/mcp` (hosted deployments
  * run in single mode, so the endpoint sits directly on the engine base URL).
@@ -15,11 +15,11 @@
  * - `--url <baseUrl>` — a running server (local `serve` mount or self-hosted
  *   base URL), with optional `--bearer-token`.
  *
- * `agentkit mcp install` writes the matching entry into `~/.cursor/mcp.json`
+ * `agent-sdk mcp install` writes the matching entry into `~/.cursor/mcp.json`
  * so the agent shows up as an MCP server in Cursor:
  *
  *   { "mcpServers": { "weather-agent": {
- *       "command": "agentkit",
+ *       "command": "agent-sdk",
  *       "args": ["mcp", "--prod", "--slug", "weather-agent"] } } }
  *
  * stdout is reserved for the MCP wire in serve mode; all logging goes to
@@ -620,7 +620,7 @@ export async function cmdMcpInstall(options: McpCliOptions): Promise<number> {
  * engineAccess server-side, so the entry never carries a pod hostname or a
  * short-lived port token — only the durable, stable gateway URL.
  *
- * Auth: this headless/CLI entry sends the `agentkit login` API key as a
+ * Auth: this headless/CLI entry sends the `agent-sdk login` API key as a
  * bearer against the user-API-key gateway surface. That key is written to
  * `mcp.json` in plain text (flagged below); a signed-in Cursor client
  * (Glass) can instead use the session gateway surface with no header at all

package/src/internal/cli-skills.ts

@@ -60,7 +60,7 @@ export async function cmdInstallSkills(
       return 0;
     }
     const action = plan.firstInstall ? "install" : "update";
-    out(`Would ${action} ${plan.leaves.length} agentkit ${noun}\n`);
+    out(`Would ${action} ${plan.leaves.length} Agent SDK ${noun}\n`);
     out(previewBlock(plan));
     return 0;
   }

package/src/internal/cloud-turn-cost.ts

@@ -1,5 +1,5 @@
 /**
- * Recover token usage / estimated cost for cloud turns that finished without
+ * Recover token usage / billed cost for cloud turns that finished without
  * either field on `turn.completed`.
  *
  * Cloud `run.wait()` often drops streamed usage after SSE reconnect, and
@@ -14,15 +14,17 @@ import type {
   TurnCost,
   TurnUsage,
 } from "../types.js";
-import { estimateTurnCost } from "./model-pricing.js";
+import { modelSettingId, turnCostFromCents } from "./turn-cost.js";
 
 export interface CloudRunUsage {
   runId: string;
   usage: TurnUsage;
+  cost?: { rawCostCents: number; chargedCents: number };
 }
 
 export interface CloudAgentUsage {
   usage: TurnUsage;
+  cost?: { rawCostCents: number; chargedCents: number };
   runs: CloudRunUsage[];
 }
 
@@ -100,7 +102,7 @@ export function applyCloudUsageToEvents(
     if (index !== undefined) {
       patches.set(index, {
         usage: billed.usage,
-        cost: estimateTurnCost(model, billed.usage),
+        cost: turnCostFromBilled(model, billed.cost),
       });
     }
   } else if (
@@ -115,7 +117,7 @@ export function applyCloudUsageToEvents(
       }
       patches.set(index, {
         usage: run.usage,
-        cost: estimateTurnCost(model, run.usage),
+        cost: turnCostFromBilled(model, run.cost),
       });
     }
   } else {
@@ -138,6 +140,20 @@ export function applyCloudUsageToEvents(
   });
 }
 
+function turnCostFromBilled(
+  model: ModelSetting,
+  cost: { rawCostCents: number; chargedCents: number } | undefined
+): TurnCost | undefined {
+  if (cost === undefined) {
+    return undefined;
+  }
+  return turnCostFromCents({
+    model: modelSettingId(model),
+    cost,
+    source: "usage",
+  });
+}
+
 export function mapSdkTokenUsage(usage: {
   inputTokens: number;
   outputTokens: number;