@cursor/july 0.1.26 → 0.1.27

package/src/internal/session-cost.ts

@@ -0,0 +1,231 @@
+/**
+ * Per-session cost metrics folded from a durable session event stream.
+ *
+ * Powers `agent-serve cost [sessionId]`: each `turn.completed` event carries
+ * the turn's token usage and the estimated dollar cost recorded by the
+ * engine (see `model-pricing.ts`), so a session's spend is a pure fold over
+ * its `events.ndjson` — no server-side aggregation required.
+ */
+
+import type { SessionEvent, TurnCost, TurnUsage } from "../types.js";
+import { formatCostUsd, roundCostUsd } from "./trajectory.js";
+
+/** One agent loop pass (turn) with its usage and estimated cost. */
+export interface SessionCostTurn {
+  turnId: string;
+  failed: boolean;
+  usage?: TurnUsage;
+  cost?: TurnCost;
+}
+
+export interface SessionCostTotals {
+  turns: number;
+  turnFailures: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  /** Sum of per-turn estimated costs (USD). */
+  costUsd: number;
+  /** Turns that reported usage but had no known model rates. */
+  unpricedTurns: number;
+}
+
+export interface SessionCostReport {
+  sessionId: string;
+  turns: SessionCostTurn[];
+  totals: SessionCostTotals;
+}
+
+export function emptySessionCostTotals(): SessionCostTotals {
+  return {
+    turns: 0,
+    turnFailures: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costUsd: 0,
+    unpricedTurns: 0,
+  };
+}
+
+export function addSessionCostTotals(
+  target: SessionCostTotals,
+  delta: SessionCostTotals
+): void {
+  target.turns += delta.turns;
+  target.turnFailures += delta.turnFailures;
+  target.inputTokens += delta.inputTokens;
+  target.outputTokens += delta.outputTokens;
+  target.cacheReadTokens += delta.cacheReadTokens;
+  target.cacheWriteTokens += delta.cacheWriteTokens;
+  target.costUsd = roundCostUsd(target.costUsd + delta.costUsd);
+  target.unpricedTurns += delta.unpricedTurns;
+}
+
+/** Fold a session event stream into per-turn and total cost metrics. */
+export function buildSessionCostReport(
+  events: readonly SessionEvent[]
+): SessionCostReport {
+  let sessionId = "";
+  const turns: SessionCostTurn[] = [];
+  const totals = emptySessionCostTotals();
+
+  for (const event of events) {
+    if (sessionId === "" && typeof event.sessionId === "string") {
+      sessionId = event.sessionId;
+    }
+    if (event.type !== "turn.completed" && event.type !== "turn.failed") {
+      continue;
+    }
+    const turn: SessionCostTurn = {
+      turnId: event.turnId ?? `turn_${turns.length + 1}`,
+      failed: event.type === "turn.failed",
+    };
+    totals.turns += 1;
+    if (event.type === "turn.failed") {
+      totals.turnFailures += 1;
+      turns.push(turn);
+      continue;
+    }
+    const usage = event.data.usage;
+    if (usage !== undefined) {
+      turn.usage = usage;
+      totals.inputTokens += usage.inputTokens;
+      totals.outputTokens += usage.outputTokens;
+      totals.cacheReadTokens += usage.cacheReadTokens;
+      totals.cacheWriteTokens += usage.cacheWriteTokens;
+    }
+    const cost = event.data.cost;
+    if (cost !== undefined) {
+      turn.cost = cost;
+      totals.costUsd = roundCostUsd(totals.costUsd + cost.totalUsd);
+    } else if (usage !== undefined) {
+      totals.unpricedTurns += 1;
+    }
+    turns.push(turn);
+  }
+
+  return { sessionId, turns, totals };
+}
+
+function formatCount(value: number): string {
+  return String(value);
+}
+
+/** Per-turn table for `agent-serve cost <sessionId>`. */
+export function formatSessionCostText(report: SessionCostReport): string {
+  const lines: string[] = [];
+  lines.push(
+    `session ${report.sessionId || "(unknown)"}  est. cost: ${formatCostUsd(report.totals.costUsd)}`
+  );
+  if (report.turns.length === 0) {
+    lines.push("No turns recorded.");
+    return `${lines.join("\n")}\n`;
+  }
+  const header = [
+    "TURN",
+    "IN",
+    "OUT",
+    "CACHE R",
+    "CACHE W",
+    "EST COST",
+    "MODEL",
+    "STATUS",
+  ];
+  const rows = report.turns.map((turn) => [
+    turn.turnId,
+    turn.usage === undefined ? "—" : formatCount(turn.usage.inputTokens),
+    turn.usage === undefined ? "—" : formatCount(turn.usage.outputTokens),
+    turn.usage === undefined ? "—" : formatCount(turn.usage.cacheReadTokens),
+    turn.usage === undefined ? "—" : formatCount(turn.usage.cacheWriteTokens),
+    turn.cost === undefined ? "—" : formatCostUsd(turn.cost.totalUsd),
+    turn.cost?.model ?? "—",
+    turn.failed ? "failed" : "ok",
+  ]);
+  rows.push([
+    "total",
+    formatCount(report.totals.inputTokens),
+    formatCount(report.totals.outputTokens),
+    formatCount(report.totals.cacheReadTokens),
+    formatCount(report.totals.cacheWriteTokens),
+    formatCostUsd(report.totals.costUsd),
+    "",
+    report.totals.turnFailures > 0
+      ? `${report.totals.turnFailures} failed`
+      : "",
+  ]);
+  lines.push(renderTable(header, rows));
+  appendUnpricedNote(lines, report.totals.unpricedTurns);
+  return `${lines.join("\n")}\n`;
+}
+
+export interface SessionCostRow {
+  sessionId: string;
+  channelId: string;
+  title?: string;
+  updatedAt?: string;
+  totals: SessionCostTotals;
+}
+
+/** All-sessions table for `agent-serve cost` (no session id). */
+export function formatSessionsCostText(rows: SessionCostRow[]): string {
+  if (rows.length === 0) {
+    return "No sessions.\n";
+  }
+  const header = [
+    "SESSION",
+    "CHANNEL",
+    "TURNS",
+    "IN",
+    "OUT",
+    "EST COST",
+    "UPDATED",
+  ];
+  const totals = emptySessionCostTotals();
+  const body = rows.map((row) => {
+    addSessionCostTotals(totals, row.totals);
+    return [
+      row.sessionId,
+      row.channelId,
+      formatCount(row.totals.turns),
+      formatCount(row.totals.inputTokens),
+      formatCount(row.totals.outputTokens),
+      formatCostUsd(row.totals.costUsd),
+      row.updatedAt ?? "",
+    ];
+  });
+  body.push([
+    "total",
+    "",
+    formatCount(totals.turns),
+    formatCount(totals.inputTokens),
+    formatCount(totals.outputTokens),
+    formatCostUsd(totals.costUsd),
+    "",
+  ]);
+  const lines = [renderTable(header, body)];
+  appendUnpricedNote(lines, totals.unpricedTurns);
+  return `${lines.join("\n")}\n`;
+}
+
+function appendUnpricedNote(lines: string[], unpricedTurns: number): void {
+  if (unpricedTurns > 0) {
+    lines.push(
+      `note: ${unpricedTurns} turn(s) reported usage for a model with no known rates; est. cost excludes them.`
+    );
+  }
+}
+
+function renderTable(header: string[], rows: string[][]): string {
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...rows.map((row) => (row[i] ?? "").length))
+  );
+  const renderRow = (row: string[]): string =>
+    row
+      .map((cell, i) => cell.padEnd(widths[i] ?? 0))
+      .join("  ")
+      .trimEnd();
+  return [renderRow(header), ...rows.map(renderRow)].join("\n");
+}

package/src/internal/session-engine.ts

@@ -34,6 +34,7 @@ import {
   type ChannelEventHandler,
   type ChannelSession,
   type ConnectionTransport,
+  DEFAULT_MODEL,
   DIRECT_TOOL_CALL_CHANNEL_ID,
   type HookHandler,
   type HostContext,
@@ -80,6 +81,7 @@ import {
 } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
+import { estimateTurnCost } from "./model-pricing.js";
 import {
   buildSessionContextBlock,
   SCHEDULE_CHANNEL_PREFIX,
@@ -535,6 +537,19 @@ export class SessionEngine {
           pendingWorkspaceFiles: options.workspaceFiles,
         }));
       }
+      // Refresh the cloud attach the same way: a follow-up send carries the
+      // caller's CURRENT cloud options (e.g. a PR attach re-derived per wake),
+      // and the first send's snapshot must not pin this session's turns to a
+      // stale repo/prUrl for the session's lifetime.
+      if (
+        options.cloud !== undefined &&
+        JSON.stringify(options.cloud) !== JSON.stringify(record.cloudOverride)
+      ) {
+        record = await this.updateRecord(record.sessionId, (current) => ({
+          ...current,
+          cloudOverride: options.cloud,
+        }));
+      }
       const coalesced = await this.startTurn(record.sessionId, message, {
         admission: options.admission ?? "preempt",
         ...(options.coalesceSourceTs === undefined
@@ -1252,6 +1267,18 @@ export class SessionEngine {
 
     const finalResult = outcome.result ?? mapper.finalText;
     const finalUsage = outcome.usage ?? mapper.usage;
+    // Estimated dollar cost of this loop pass, persisted alongside usage so
+    // traces / A/B metrics / the CLI can aggregate spend without re-pricing.
+    const finalCost =
+      finalUsage === undefined
+        ? undefined
+        : estimateTurnCost(
+            this.project.agent.model ?? DEFAULT_MODEL,
+            finalUsage
+          );
+    if (finalCost !== undefined) {
+      outcome = { ...outcome, cost: finalCost };
+    }
 
     if (outcome.status === "finished") {
       await this.appendEvent(sessionId, {
@@ -1260,6 +1287,7 @@ export class SessionEngine {
         data: {
           ...(finalResult === undefined ? {} : { result: finalResult }),
           ...(finalUsage === undefined ? {} : { usage: finalUsage }),
+          ...(finalCost === undefined ? {} : { cost: finalCost }),
         },
       });
     } else {

package/src/internal/trajectory.ts

@@ -7,7 +7,7 @@
  */
 
 import { readFile } from "node:fs/promises";
-import type { SessionEvent, TurnUsage } from "../types.js";
+import type { SessionEvent, TurnCost, TurnUsage } from "../types.js";
 
 export interface TrajectoryToolCall {
   callId: string;
@@ -37,6 +37,8 @@ export interface TrajectoryTurn {
   toolCalls: TrajectoryToolCall[];
   subagents: TrajectorySubagent[];
   usage?: TurnUsage;
+  /** Estimated dollar cost of this turn (from the `turn.completed` event). */
+  cost?: TurnCost;
   result?: string;
   failed: boolean;
   error?: string;
@@ -51,6 +53,8 @@ export interface Trajectory {
   finalText: string;
   turnsFailed: number;
   toolCallCount: number;
+  /** Sum of per-turn estimated costs; present when any turn reported cost. */
+  totalCostUsd?: number;
   turns: TrajectoryTurn[];
 }
 
@@ -228,6 +232,9 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
         if (event.data.usage !== undefined) {
           turn.usage = event.data.usage;
         }
+        if (event.data.cost !== undefined) {
+          turn.cost = event.data.cost;
+        }
         if (event.data.result !== undefined) {
           turn.result = event.data.result;
           if (turn.assistantText === "") {
@@ -267,6 +274,13 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
     0
   );
   const lastGood = [...turns].reverse().find((t) => t.assistantText !== "");
+  const costedTurns = turns.filter((t) => t.cost !== undefined);
+  const totalCostUsd =
+    costedTurns.length === 0
+      ? undefined
+      : roundCostUsd(
+          costedTurns.reduce((sum, t) => sum + (t.cost?.totalUsd ?? 0), 0)
+        );
   return {
     sessionId,
     ...(sdkAgentId === undefined ? {} : { sdkAgentId }),
@@ -276,10 +290,30 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
     finalText: lastGood?.assistantText ?? "",
     turnsFailed,
     toolCallCount,
+    ...(totalCostUsd === undefined ? {} : { totalCostUsd }),
     turns,
   };
 }
 
+/** Micro-dollar precision so summed floats stay readable in JSON. */
+export function roundCostUsd(usd: number): number {
+  return Math.round(usd * 1e6) / 1e6;
+}
+
+/** Compact dollar display for estimated costs (`$0.0132`, `$1.25`). */
+export function formatCostUsd(usd: number): string {
+  if (!Number.isFinite(usd)) {
+    return "—";
+  }
+  if (usd === 0) {
+    return "$0.00";
+  }
+  if (usd >= 0.1) {
+    return `$${usd.toFixed(2)}`;
+  }
+  return `$${usd.toFixed(4)}`;
+}
+
 /** Parse an `events.ndjson` file (or any NDJSON blob of SessionEvents). */
 export function parseEventsNdjson(text: string): SessionEvent[] {
   const events: SessionEvent[] = [];
@@ -318,7 +352,11 @@ export function formatTrajectoryText(trajectory: Trajectory): string {
     lines.push(`url: ${trajectory.agentUrl}`);
   }
   lines.push(
-    `turns: ${trajectory.turns.length}  tools=${trajectory.toolCallCount}  failed: ${trajectory.turnsFailed}`
+    `turns: ${trajectory.turns.length}  tools=${trajectory.toolCallCount}  failed: ${trajectory.turnsFailed}${
+      trajectory.totalCostUsd === undefined
+        ? ""
+        : `  est. cost: ${formatCostUsd(trajectory.totalCostUsd)}`
+    }`
   );
   for (const turn of trajectory.turns) {
     lines.push("");
@@ -356,7 +394,11 @@ export function formatTrajectoryText(trajectory: Trajectory): string {
     }
     if (turn.usage !== undefined) {
       lines.push(
-        `  usage: in ${turn.usage.inputTokens} out ${turn.usage.outputTokens}`
+        `  usage: in ${turn.usage.inputTokens} out ${turn.usage.outputTokens}${
+          turn.cost === undefined
+            ? ""
+            : `  est. cost: ${formatCostUsd(turn.cost.totalUsd)}`
+        }`
       );
     }
   }

package/src/types.ts

@@ -942,7 +942,7 @@ export type SessionEventPayload =
     }
   | {
       type: "turn.completed";
-      data: { result?: string; usage?: TurnUsage };
+      data: { result?: string; usage?: TurnUsage; cost?: TurnCost };
     }
   | { type: "turn.failed"; data: { message: string } }
   | { type: "session.waiting"; data: Record<string, never> }
@@ -960,6 +960,27 @@ export interface TurnUsage {
   reasoningTokens?: number;
 }
 
+/**
+ * Estimated dollar cost of one turn's token usage (one agent loop pass).
+ * Recorded on `turn.completed` events so traces, the playground, A/B
+ * metrics, and the CLI can aggregate spend. Estimates price the turn's
+ * {@link TurnUsage} against the framework's snapshot of Cursor's published
+ * per-model rates — the billed amount on the Cursor dashboard is the source
+ * of truth.
+ */
+export interface TurnCost {
+  /** Estimated total for the turn, in USD. */
+  totalUsd: number;
+  inputUsd: number;
+  outputUsd: number;
+  cacheReadUsd: number;
+  cacheWriteUsd: number;
+  /** Normalized model id the estimate was priced against. */
+  model: string;
+  /** Always `"estimate"`: framework rate table, not the billing pipeline. */
+  source: "estimate";
+}
+
 // ============================================================================
 // Sessions
 // ============================================================================
@@ -1061,6 +1082,8 @@ export interface TurnOutcome {
   result?: string;
   errorMessage?: string;
   usage?: TurnUsage;
+  /** Estimated cost of {@link usage} when the model has known rates. */
+  cost?: TurnCost;
 }
 
 /**

package/dist/channels/github/instrument.d.ts

@@ -1,20 +0,0 @@
-/**
- * Per-request observability for GitHub channel Octokit clients.
- *
- * Every Octokit built by `createGitHubOctokit` / `callGitHubApi` gets one
- * structured `[agentkit/github]` line per GitHub API request (REST and
- * GraphQL), including rate-limit headers so installation-quota pressure can
- * be attributed to agentkit deployments from hosted-runtime logs.
- */
-import type { Octokit } from "@octokit/rest";
-export type GitHubRequestLogWrite = (line: string) => void;
-/** Best-effort GraphQL operation name (`query Foo` / `mutation Bar`). */
-export declare function parseGraphQLOperationName(query: unknown): string | undefined;
-/**
- * Wrap an Octokit so every request emits one structured log line. Returns
- * the same instance for call-through convenience. Idempotent per instance.
- */
-export declare function instrumentGitHubOctokit(octokit: Octokit, input?: {
-    write?: GitHubRequestLogWrite;
-}): Octokit;
-//# sourceMappingURL=instrument.d.ts.map

package/dist/channels/github/instrument.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../../../src/channels/github/instrument.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AA4C3D,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ5E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,KAAK,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAAE,GACxC,OAAO,CAmDT"}