@cursor/july 0.1.25 → 0.1.27

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
@@ -716,7 +731,10 @@ export class SessionEngine {
         lastCreated = session;
         return session;
       };
-      const returned = await definition.receive(input, { send });
+      const returned = await definition.receive(input, {
+        send,
+        artifacts: this.artifactsApi(),
+      });
       const session = returned ?? lastCreated;
       if (session === undefined) {
         throw new Error(
@@ -1249,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, {
@@ -1257,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;
 }
 
 /**
@@ -1505,6 +1528,12 @@ export interface ChannelStartArgs {
    * should prefer this over `console.*` so CLI/eval hosts can redirect.
    */
   logger: (line: string) => void;
+  /**
+   * Durable artifacts (unbound, same facade as
+   * {@link ChannelHandlerArgs.artifacts}) — for host pipelines the channel
+   * drives outside any route handler.
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**
@@ -1551,7 +1580,7 @@ export interface ChannelConfig<TState = JsonValue> {
    */
   receive?: (
     input: ReceiveInput,
-    args: { send: SendMessageFn }
+    args: { send: SendMessageFn; artifacts: ArtifactsApi }
     // biome-ignore lint/suspicious/noConfusingVoidType: hooks may return a session, nothing, or an async nothing
   ) => Promise<ChannelSession | undefined | void> | ChannelSession | void;
   /** Stream-event handlers for sessions owned by this channel. */
@@ -1742,6 +1771,11 @@ export interface ScheduleHandlerArgs {
   appAuth: AuthContext;
   /** Shared host services (MCP / GitHub / Slack). Same as tool `ctx.host`. */
   host: HostContext;
+  /**
+   * Durable artifacts (unbound — schedule handlers have no ambient session;
+   * pass `sessionId` explicitly to attribute).
+   */
+  artifacts: ArtifactsApi;
 }
 
 export interface ScheduleConfig {
@@ -1795,6 +1829,12 @@ export interface ReminderFireContext extends ReminderUntilContext {
   /** Wake the reminder's already-bound session (target is implicit). */
   followup(args: { message: string }): Promise<ChannelSession>;
   cancel(reason?: string): Promise<void>;
+  /**
+   * Durable artifacts (unbound — the reminder is bound to a continuation
+   * token, not a resolved session; pass `sessionId` in `tag` input to
+   * attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**

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"}