@cursor/july 0.1.26 → 0.1.27

package/src/bin/agent-serve.ts

@@ -29,6 +29,7 @@ import {
   type AxCliOptions,
   cmdCall,
   cmdChat,
+  cmdCost,
   cmdEval,
   cmdEvalCancel,
   cmdEvalStatus,
@@ -55,6 +56,7 @@ import {
 } from "../internal/cli-deploy.js";
 import {
   CLI_COMMAND_NAME as CLI,
+  PACKAGE_NAME,
   packageVersion,
 } from "../internal/distribution.js";
 import { loadAgentLocalEnv } from "../internal/local-env.js";
@@ -85,6 +87,8 @@ Usage:
   ${CLI} session     <sessionId> [--url <baseUrl> | --prod]
                           [--json | --text | --events]
                           [--slug <slug>] [--team <id>] [--dir <path>]
+  ${CLI} cost        [sessionId] [--url <baseUrl> | --prod] [--json]
+                          [--slug <slug>] [--team <id>] [--dir <path>]
   ${CLI} playground  [--url <baseUrl> | --prod] [--session <id>] [--print]
                           [--slug <slug>] [--team <id>] [--dir <path>]
   ${CLI} docs        [--port <n>] [--host <host>] [--print]
@@ -161,6 +165,10 @@ Commands:
   session     Show one session. Default: text trajectory. --json for trajectory
               JSON; --events for the raw event list. To continue interactively,
               use \`${CLI} resume [id]\`.
+  cost        Pull cost metrics. With a session id: per-turn token usage and
+              estimated cost for that session. Without one: one row per
+              session plus a total. Costs are the engine's recorded estimates
+              from turn.completed events; --json for machine-readable reports.
   playground  Open the web playground. --prod starts a loopback proxy that
               injects hosted engine credentials (browsers cannot set them).
               --print skips opening a browser. Ctrl-C stops the proxy.
@@ -908,6 +916,22 @@ async function main(argv: string[]): Promise<number> {
       );
     }
 
+    case "cost": {
+      return cmdCost(
+        positionals[0] ?? values["session-id"] ?? values.session,
+        axFromOptions({
+          dir,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          json: values.json,
+        })
+      );
+    }
+
     case "playground": {
       return cmdPlayground(
         axFromOptions({
@@ -1383,11 +1407,15 @@ function printServeBanner(
 ): void {
   const c = stdoutPalette();
   const agents = handle.agents;
+  // Name the framework build in the boot line: hosted engines install the
+  // published package at provision time, so the serve log is the only
+  // durable record of which build a deployment's turns actually ran on.
+  const versionTag = c.dim(`(${PACKAGE_NAME} ${packageVersion()})`);
   if (agents.length > 1) {
-    process.stdout.write(`${agents.length} agents listening\n`);
+    process.stdout.write(`${agents.length} agents listening ${versionTag}\n`);
   } else {
     const info = projectInfo(agents[0]?.project ?? handle.project);
-    process.stdout.write(`${info.name} listening\n`);
+    process.stdout.write(`${info.name} listening ${versionTag}\n`);
   }
 
   const playgroundUrl = resolvePlaygroundBannerUrl(handle, opts.noPlayground);

package/src/internal/ab-fold.ts

@@ -187,6 +187,10 @@ export function applyBuiltinMetrics(
         m.cacheReadTokens += usage.cacheReadTokens;
         m.cacheWriteTokens += usage.cacheWriteTokens;
       }
+      const cost = event.data.cost;
+      if (cost !== undefined) {
+        m.costUsd += cost.totalUsd;
+      }
       addWallTime(accum, event.at);
       break;
     }

package/src/internal/ab-snapshot.ts

@@ -323,6 +323,7 @@ function addMetrics(target: ABMetrics, delta: ABMetrics): void {
   target.outputTokens += delta.outputTokens;
   target.cacheReadTokens += delta.cacheReadTokens;
   target.cacheWriteTokens += delta.cacheWriteTokens;
+  target.costUsd += delta.costUsd;
   target.wallTimeMs += delta.wallTimeMs;
   for (const [key, value] of Object.entries(delta.custom)) {
     target.custom[key] = (target.custom[key] ?? 0) + value;

package/src/internal/cli-ax.ts

@@ -50,6 +50,7 @@ import {
 } from "./init-project.js";
 import { offerInstallCursorSkills } from "./install-cursor-skills.js";
 import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
+import { mapPool } from "./map-pool.js";
 import { openBrowser } from "./open-browser.js";
 import { startPlaygroundProxy } from "./playground-proxy.js";
 import {
@@ -59,6 +60,12 @@ import {
   resolveProdTarget,
 } from "./resolve-prod-target.js";
 import { runSession } from "./run-client.js";
+import {
+  buildSessionCostReport,
+  formatSessionCostText,
+  formatSessionsCostText,
+  type SessionCostRow,
+} from "./session-cost.js";
 import {
   fetchSessionEvents,
   formatSessionsTable,
@@ -1771,6 +1778,94 @@ export async function cmdSession(
   }
 }
 
+/** Sessions fetched concurrently when `cost` aggregates every session. */
+const COST_FETCH_CONCURRENCY = 4;
+
+/**
+ * `cost [sessionId]` — pull per-session cost metrics.
+ *
+ * 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
+ * count as unpriced.
+ */
+export async function cmdCost(
+  sessionId: string | undefined,
+  options: AxCliOptions
+): Promise<number> {
+  const target = await resolveSessionTarget(options);
+  if (typeof target === "number") {
+    return target;
+  }
+  const auth = {
+    bearerToken: options.bearerToken,
+    headers: target.headers,
+  };
+
+  try {
+    const resolved = trimNonEmpty(sessionId);
+    if (resolved !== undefined) {
+      const events = await fetchSessionEvents({
+        baseUrl: target.agentUrl,
+        sessionId: resolved,
+        auth,
+        fetchImpl: options.fetchImpl,
+      });
+      const report = buildSessionCostReport(events);
+      if (report.sessionId === "") {
+        report.sessionId = resolved;
+      }
+      if (options.json === true) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else {
+        process.stdout.write(formatSessionCostText(report));
+      }
+      return 0;
+    }
+
+    const listed = await listSessionsWithSource({
+      baseUrl: target.agentUrl,
+      auth,
+      fetchImpl: options.fetchImpl,
+    });
+    const rows = await mapPool(
+      listed.sessions,
+      COST_FETCH_CONCURRENCY,
+      async (session): Promise<SessionCostRow> => {
+        const events = await fetchSessionEvents({
+          baseUrl: target.agentUrl,
+          sessionId: session.sessionId,
+          auth,
+          fetchImpl: options.fetchImpl,
+        });
+        const report = buildSessionCostReport(events);
+        return {
+          sessionId: session.sessionId,
+          channelId: session.channelId,
+          title: session.title,
+          updatedAt: session.updatedAt,
+          totals: report.totals,
+        };
+      }
+    );
+    if (options.json === true) {
+      process.stdout.write(`${JSON.stringify({ sessions: rows }, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatSessionsCostText(rows));
+    }
+    return 0;
+  } catch (error) {
+    process.stderr.write(
+      `${sanitizeCustomerError(
+        error instanceof Error ? error.message : String(error)
+      )}\n`
+    );
+    return 1;
+  }
+}
+
 /**
  * `playground` — open the web UI against local / `--url` / `--prod`.
  *

package/src/internal/model-pricing.ts

@@ -0,0 +1,426 @@
+/**
+ * Best-effort dollar-cost estimation for agent turns.
+ *
+ * The Cursor harness streams token usage (`turn-ended`) but no dollar cost,
+ * and server-billed cost is only queryable for cloud agents — so the
+ * framework prices token usage against a built-in snapshot of Cursor's
+ * published per-model API rates. Estimates are marked `source: "estimate"`
+ * everywhere they surface (traces, playground, A/B metrics, CLI); the billed
+ * amount on the Cursor dashboard remains the source of truth.
+ *
+ * Unknown models produce no estimate rather than a wrong one. Deployments
+ * can extend or correct the table without a package upgrade via the
+ * `AGENT_SERVE_MODEL_PRICING` environment variable (a JSON object merged
+ * over the defaults, keyed by model id).
+ */
+
+import type { ModelSetting, TurnCost, TurnUsage } from "../types.js";
+
+/** USD per million tokens for one pricing tier. */
+export interface ModelPricingTier {
+  inputUsdPerMTok: number;
+  outputUsdPerMTok: number;
+  cacheReadUsdPerMTok: number;
+  /** Defaults to {@link inputUsdPerMTok} when omitted (provider convention). */
+  cacheWriteUsdPerMTok?: number;
+}
+
+export interface ModelPricing extends ModelPricingTier {
+  /** Rates when the model's `fast` parameter is `"true"`. */
+  fast?: ModelPricingTier;
+}
+
+const M = 1_000_000;
+
+/**
+ * Snapshot of Cursor API per-model token rates (USD per million tokens).
+ * Keyed by normalized model id; family aliases (`sonnet`, `gpt`, …) point at
+ * the model they currently resolve to.
+ */
+export const DEFAULT_MODEL_PRICING: Readonly<Record<string, ModelPricing>> = {
+  // xAI / Cursor-served Grok
+  "grok-4.5": {
+    inputUsdPerMTok: 2,
+    outputUsdPerMTok: 6,
+    cacheReadUsdPerMTok: 0.5,
+    fast: { inputUsdPerMTok: 4, outputUsdPerMTok: 18, cacheReadUsdPerMTok: 1 },
+  },
+  "grok-4.20": {
+    inputUsdPerMTok: 2,
+    outputUsdPerMTok: 6,
+    cacheReadUsdPerMTok: 0.2,
+  },
+  "grok-4.3": {
+    inputUsdPerMTok: 1.25,
+    outputUsdPerMTok: 2.5,
+    cacheReadUsdPerMTok: 0.125,
+  },
+  "grok-code": {
+    inputUsdPerMTok: 0.2,
+    outputUsdPerMTok: 1.5,
+    cacheReadUsdPerMTok: 0.02,
+  },
+
+  // Anthropic
+  "opus-5": {
+    inputUsdPerMTok: 5,
+    outputUsdPerMTok: 25,
+    cacheReadUsdPerMTok: 0.5,
+    cacheWriteUsdPerMTok: 6.25,
+    fast: {
+      inputUsdPerMTok: 10,
+      outputUsdPerMTok: 50,
+      cacheReadUsdPerMTok: 1,
+      cacheWriteUsdPerMTok: 12.5,
+    },
+  },
+  "opus-4.8": {
+    inputUsdPerMTok: 5,
+    outputUsdPerMTok: 25,
+    cacheReadUsdPerMTok: 0.5,
+    cacheWriteUsdPerMTok: 6.25,
+    fast: {
+      inputUsdPerMTok: 10,
+      outputUsdPerMTok: 50,
+      cacheReadUsdPerMTok: 1,
+      cacheWriteUsdPerMTok: 12.5,
+    },
+  },
+  "opus-4.7": {
+    inputUsdPerMTok: 5,
+    outputUsdPerMTok: 25,
+    cacheReadUsdPerMTok: 0.5,
+    cacheWriteUsdPerMTok: 6.25,
+    fast: {
+      inputUsdPerMTok: 30,
+      outputUsdPerMTok: 150,
+      cacheReadUsdPerMTok: 3,
+      cacheWriteUsdPerMTok: 37.5,
+    },
+  },
+  "opus-4.6": {
+    inputUsdPerMTok: 5,
+    outputUsdPerMTok: 25,
+    cacheReadUsdPerMTok: 0.5,
+    cacheWriteUsdPerMTok: 6.25,
+  },
+  "opus-4.5": {
+    inputUsdPerMTok: 5,
+    outputUsdPerMTok: 25,
+    cacheReadUsdPerMTok: 0.5,
+    cacheWriteUsdPerMTok: 6.25,
+  },
+  "sonnet-5": {
+    inputUsdPerMTok: 3,
+    outputUsdPerMTok: 15,
+    cacheReadUsdPerMTok: 0.3,
+    cacheWriteUsdPerMTok: 3.75,
+  },
+  "sonnet-4.6": {
+    inputUsdPerMTok: 3,
+    outputUsdPerMTok: 15,
+    cacheReadUsdPerMTok: 0.3,
+    cacheWriteUsdPerMTok: 3.75,
+  },
+  "sonnet-4.5": {
+    inputUsdPerMTok: 3,
+    outputUsdPerMTok: 15,
+    cacheReadUsdPerMTok: 0.3,
+    cacheWriteUsdPerMTok: 3.75,
+  },
+  "haiku-4.5": {
+    inputUsdPerMTok: 1,
+    outputUsdPerMTok: 5,
+    cacheReadUsdPerMTok: 0.1,
+    cacheWriteUsdPerMTok: 1.25,
+  },
+  "fable-5": {
+    inputUsdPerMTok: 10,
+    outputUsdPerMTok: 50,
+    cacheReadUsdPerMTok: 1,
+    cacheWriteUsdPerMTok: 12.5,
+  },
+
+  // OpenAI
+  "gpt-5.6": {
+    inputUsdPerMTok: 5,
+    outputUsdPerMTok: 30,
+    cacheReadUsdPerMTok: 0.5,
+    cacheWriteUsdPerMTok: 6.25,
+    fast: {
+      inputUsdPerMTok: 10,
+      outputUsdPerMTok: 60,
+      cacheReadUsdPerMTok: 1,
+      cacheWriteUsdPerMTok: 12.5,
+    },
+  },
+  "gpt-5.5": {
+    inputUsdPerMTok: 5,
+    outputUsdPerMTok: 30,
+    cacheReadUsdPerMTok: 0.5,
+  },
+  "gpt-5.4": {
+    inputUsdPerMTok: 2.5,
+    outputUsdPerMTok: 15,
+    cacheReadUsdPerMTok: 0.25,
+  },
+  "gpt-5.2": {
+    inputUsdPerMTok: 1.75,
+    outputUsdPerMTok: 14,
+    cacheReadUsdPerMTok: 0.175,
+  },
+  "gpt-mini": {
+    inputUsdPerMTok: 0.75,
+    outputUsdPerMTok: 4.5,
+    cacheReadUsdPerMTok: 0.075,
+  },
+  "codex-5.3": {
+    inputUsdPerMTok: 1.75,
+    outputUsdPerMTok: 14,
+    cacheReadUsdPerMTok: 0.175,
+  },
+  "codex-5.2": {
+    inputUsdPerMTok: 1.75,
+    outputUsdPerMTok: 14,
+    cacheReadUsdPerMTok: 0.175,
+  },
+
+  // Google
+  "gemini-3.1-pro": {
+    inputUsdPerMTok: 2,
+    outputUsdPerMTok: 12,
+    cacheReadUsdPerMTok: 0.2,
+  },
+  "gemini-3-pro": {
+    inputUsdPerMTok: 2,
+    outputUsdPerMTok: 12,
+    cacheReadUsdPerMTok: 0.2,
+  },
+  "gemini-3.6-flash": {
+    inputUsdPerMTok: 1.5,
+    outputUsdPerMTok: 7.5,
+    cacheReadUsdPerMTok: 0.15,
+  },
+  "gemini-3.5-flash": {
+    inputUsdPerMTok: 1.5,
+    outputUsdPerMTok: 9,
+    cacheReadUsdPerMTok: 0.15,
+  },
+
+  // Cursor Composer
+  "composer-2.5": {
+    inputUsdPerMTok: 0.5,
+    outputUsdPerMTok: 2.5,
+    cacheReadUsdPerMTok: 0.2,
+    fast: {
+      inputUsdPerMTok: 3,
+      outputUsdPerMTok: 15,
+      cacheReadUsdPerMTok: 0.5,
+    },
+  },
+  "composer-2": {
+    inputUsdPerMTok: 0.5,
+    outputUsdPerMTok: 2.5,
+    cacheReadUsdPerMTok: 0.2,
+  },
+
+  // Moonshot / Zhipu
+  "kimi-k3": {
+    inputUsdPerMTok: 3,
+    outputUsdPerMTok: 15,
+    cacheReadUsdPerMTok: 0.3,
+  },
+  "kimi-k2.7": {
+    inputUsdPerMTok: 0.95,
+    outputUsdPerMTok: 4,
+    cacheReadUsdPerMTok: 0.19,
+  },
+  "kimi-k2.5": {
+    inputUsdPerMTok: 0.6,
+    outputUsdPerMTok: 3,
+    cacheReadUsdPerMTok: 0.1,
+  },
+  "glm-5.2": {
+    inputUsdPerMTok: 1.4,
+    outputUsdPerMTok: 4.4,
+    cacheReadUsdPerMTok: 0.26,
+  },
+};
+
+/** Family aliases → the model id they currently resolve to. */
+const MODEL_ID_ALIASES: Readonly<Record<string, string>> = {
+  grok: "grok-4.20",
+  "grok-latest": "grok-4.3",
+  "grok-code-latest": "grok-code",
+  opus: "opus-5",
+  "opus-latest": "opus-5",
+  sonnet: "sonnet-4.6",
+  "sonnet-latest": "sonnet-5",
+  haiku: "haiku-4.5",
+  "haiku-latest": "haiku-4.5",
+  fable: "fable-5",
+  gpt: "gpt-5.6",
+  "gpt-latest": "gpt-5.6",
+  "gpt-5-6-sol": "gpt-5.6",
+  "gpt-5-5": "gpt-5.5",
+  "gpt-mini-latest": "gpt-mini",
+  codex: "codex-5.3",
+  "codex-latest": "codex-5.3",
+  gemini: "gemini-3.1-pro",
+  "gemini-latest": "gemini-3.1-pro",
+  "gemini-pro": "gemini-3.1-pro",
+  "gemini-pro-latest": "gemini-3.1-pro",
+  "gemini-flash": "gemini-3.6-flash",
+  "gemini-flash-latest": "gemini-3.6-flash",
+  composer: "composer-2.5",
+  "composer-latest": "composer-2.5",
+  "composer-2-5": "composer-2.5",
+  kimi: "kimi-k2.7",
+  "kimi-latest": "kimi-k2.7",
+};
+
+/** Env var holding a JSON pricing override merged over the defaults. */
+export const MODEL_PRICING_ENV_VAR = "AGENT_SERVE_MODEL_PRICING";
+
+let cachedEnvOverride:
+  | { raw: string | undefined; table: Record<string, ModelPricing> }
+  | undefined;
+
+function envOverrideTable(): Record<string, ModelPricing> {
+  const raw = process.env[MODEL_PRICING_ENV_VAR];
+  if (cachedEnvOverride !== undefined && cachedEnvOverride.raw === raw) {
+    return cachedEnvOverride.table;
+  }
+  let table: Record<string, ModelPricing> = {};
+  if (raw !== undefined && raw.trim() !== "") {
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (typeof parsed === "object" && parsed !== null) {
+        for (const [key, value] of Object.entries(parsed)) {
+          const tier = parsePricing(value);
+          if (tier !== undefined) {
+            table[normalizeModelId(key)] = tier;
+          }
+        }
+      }
+    } catch {
+      table = {};
+    }
+  }
+  cachedEnvOverride = { raw, table };
+  return table;
+}
+
+function parseTier(value: unknown): ModelPricingTier | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const row = value as Record<string, unknown>;
+  const input = row.inputUsdPerMTok;
+  const output = row.outputUsdPerMTok;
+  const cacheRead = row.cacheReadUsdPerMTok;
+  if (
+    !isRate(input) ||
+    !isRate(output) ||
+    (cacheRead !== undefined && !isRate(cacheRead))
+  ) {
+    return undefined;
+  }
+  const cacheWrite = row.cacheWriteUsdPerMTok;
+  return {
+    inputUsdPerMTok: input,
+    outputUsdPerMTok: output,
+    cacheReadUsdPerMTok: isRate(cacheRead) ? cacheRead : input,
+    cacheWriteUsdPerMTok: isRate(cacheWrite) ? cacheWrite : undefined,
+  };
+}
+
+function parsePricing(value: unknown): ModelPricing | undefined {
+  const base = parseTier(value);
+  if (base === undefined) {
+    return undefined;
+  }
+  const fast = parseTier((value as Record<string, unknown>).fast);
+  return { ...base, fast };
+}
+
+function isRate(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+export function normalizeModelId(id: string): string {
+  return id.trim().toLowerCase();
+}
+
+function modelId(model: ModelSetting): string {
+  return typeof model === "string" ? model : model.id;
+}
+
+function modelHasFastParam(model: ModelSetting): boolean {
+  if (typeof model === "string") {
+    return false;
+  }
+  return (
+    model.params?.some(
+      (param) => param.id === "fast" && param.value === "true"
+    ) === true
+  );
+}
+
+/**
+ * Rates for a model selection, honoring its `fast` parameter. `undefined`
+ * when the model is not in the table (no estimate is better than a wrong
+ * one).
+ */
+export function resolveModelPricing(
+  model: ModelSetting
+): ModelPricingTier | undefined {
+  const overrides = envOverrideTable();
+  const rawId = normalizeModelId(modelId(model));
+  const canonicalId = MODEL_ID_ALIASES[rawId] ?? rawId;
+  const pricing =
+    overrides[rawId] ??
+    overrides[canonicalId] ??
+    DEFAULT_MODEL_PRICING[rawId] ??
+    DEFAULT_MODEL_PRICING[canonicalId];
+  if (pricing === undefined) {
+    return undefined;
+  }
+  if (modelHasFastParam(model) && pricing.fast !== undefined) {
+    return pricing.fast;
+  }
+  return pricing;
+}
+
+/**
+ * Estimate the dollar cost of one turn's token usage. `undefined` when the
+ * model has no known rates.
+ */
+export function estimateTurnCost(
+  model: ModelSetting,
+  usage: TurnUsage
+): TurnCost | undefined {
+  const tier = resolveModelPricing(model);
+  if (tier === undefined) {
+    return undefined;
+  }
+  const cacheWriteRate = tier.cacheWriteUsdPerMTok ?? tier.inputUsdPerMTok;
+  const inputUsd = (usage.inputTokens / M) * tier.inputUsdPerMTok;
+  const outputUsd = (usage.outputTokens / M) * tier.outputUsdPerMTok;
+  const cacheReadUsd = (usage.cacheReadTokens / M) * tier.cacheReadUsdPerMTok;
+  const cacheWriteUsd = (usage.cacheWriteTokens / M) * cacheWriteRate;
+  return {
+    totalUsd: roundUsd(inputUsd + outputUsd + cacheReadUsd + cacheWriteUsd),
+    inputUsd: roundUsd(inputUsd),
+    outputUsd: roundUsd(outputUsd),
+    cacheReadUsd: roundUsd(cacheReadUsd),
+    cacheWriteUsd: roundUsd(cacheWriteUsd),
+    model: normalizeModelId(modelId(model)),
+    source: "estimate",
+  };
+}
+
+/** Keep persisted estimates readable: micro-dollar precision. */
+function roundUsd(usd: number): number {
+  return Math.round(usd * 1e6) / 1e6;
+}

package/src/internal/sdk-runner.ts

@@ -431,9 +431,17 @@ export class CursorSdkRunner implements AgentRunner {
     if (request.isFirstTurn) {
       return Agent.create(options);
     }
-    throw new Error(
-      `Cloud session ${request.sessionId} is missing sdkAgentId; cannot resume.`
+    // A cloud session past its first turn should carry the bound agent id
+    // (the engine persists it via onSdkAgentId as soon as create() reports
+    // one). Reaching here means the binding turn failed before the server
+    // ever minted an agent — e.g. create() rejected its PR attach — so the
+    // session would otherwise fail every future turn. Mirror the local
+    // host-replacement path above: a fresh conversation beats failing this
+    // thread forever, and the new id binds to the session for later resumes.
+    this.log(
+      `[agentkit] cloud session ${request.sessionId} has no bound cloud agent; creating a fresh one`
     );
+    return Agent.create(options);
   }
 
   private getStore(stateDir: string): Promise<LocalAgentStore> {