@cursor/july 0.1.25 → 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/channels/github/github-channel.ts

@@ -10,6 +10,7 @@ import {
 import { isDevMode } from "../../internal/dev-mode.js";
 import type {
   AgentCloudOptions,
+  ArtifactsApi,
   AuthContext,
   ChannelDefinition,
   ChannelEventHandlers,
@@ -68,7 +69,7 @@ import type {
  */
 type GitHubParsedContext = Omit<
   GitHubEventContext,
-  "github" | "thread" | "host"
+  "github" | "thread" | "host" | "artifacts"
 >;
 
 const DEFAULT_PULL_REQUEST_ACTIONS: ReadonlySet<string> = new Set([
@@ -737,6 +738,7 @@ async function handlePullRequest(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch =
     input.options.onPullRequest === undefined
@@ -828,6 +830,7 @@ async function handleIssueComment(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
 
   const dispatch =
@@ -918,6 +921,7 @@ async function handleReviewComment(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
 
   const dispatch =
@@ -994,6 +998,7 @@ async function handleIssue(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onIssue(ctx, parsed.issue);
   if (dispatch === null) {
@@ -1053,6 +1058,7 @@ async function handleCheckSuite(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.checkSuite
     );
@@ -1079,6 +1085,7 @@ async function handleCheckSuite(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onCheckSuite(ctx, parsed.checkSuite);
   if (dispatch === null) {
@@ -1143,6 +1150,7 @@ async function handleCheckRun(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.checkRun
     );
@@ -1169,6 +1177,7 @@ async function handleCheckRun(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onCheckRun(ctx, parsed.checkRun);
   if (dispatch === null) {
@@ -1229,6 +1238,7 @@ async function handleWorkflowRun(input: {
         ctx: parsed.unanchoredCtx,
         installationId,
         host: input.args.host,
+        artifacts: input.args.artifacts,
       }),
       parsed.workflowRun
     );
@@ -1255,6 +1265,7 @@ async function handleWorkflowRun(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onWorkflowRun(ctx, parsed.workflowRun);
   if (dispatch === null) {
@@ -1326,6 +1337,7 @@ async function handleStatus(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onStatus(ctx, parsed.status);
   if (dispatch === null) {
@@ -1399,6 +1411,7 @@ async function handleGenericEvent(input: {
     bindingState: binding,
     installationId,
     host: input.args.host,
+    artifacts: input.args.artifacts,
   });
   const dispatch = await input.options.onEvent(ctx, parsed.event);
   if (dispatch === null) {
@@ -2224,11 +2237,12 @@ function escapeRegExp(value: string): string {
  */
 function enrichEventContext(input: {
   bindingConfig: GitHubBindingConfig;
-  ctx: Omit<GitHubEventContext, "github" | "thread" | "host"> &
+  ctx: Omit<GitHubEventContext, "github" | "thread" | "host" | "artifacts"> &
     Partial<Pick<GitHubEventContext, "github" | "thread">>;
   bindingState: GitHubBindingState;
   installationId?: number;
   host: HostContext;
+  artifacts: ArtifactsApi;
 }): GitHubEventContext {
   const { github, thread } = buildGitHubBinding({
     config: input.bindingConfig,
@@ -2242,6 +2256,7 @@ function enrichEventContext(input: {
     github,
     thread,
     host: input.host,
+    artifacts: input.artifacts,
   };
 }
 
@@ -2254,6 +2269,7 @@ function enrichCiContext(input: {
   ctx: GitHubParsedContext;
   installationId?: number;
   host: HostContext;
+  artifacts: ArtifactsApi;
 }): GitHubEventContext {
   const binding = githubBindingStateForEvent({
     kind: input.ctx.conversation.kind,
@@ -2269,6 +2285,7 @@ function enrichCiContext(input: {
     bindingState: binding,
     installationId: input.installationId,
     host: input.host,
+    artifacts: input.artifacts,
   });
 }
 

package/src/channels/github/types.ts

@@ -1,5 +1,6 @@
 import type {
   AgentCloudOptions,
+  ArtifactsApi,
   AuthContext,
   AuthPolicy,
   ChannelEventHandlers,
@@ -306,6 +307,11 @@ export interface GitHubEventContext {
   thread: GitHubThread;
   /** Shared host services (MCP / host GitHub / Slack). Same as tool `ctx.host`. */
   host: HostContext;
+  /**
+   * Durable artifacts (unbound — the hook runs before any session is
+   * admitted; pass `sessionId` in `tag` input to attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**

package/src/channels/slack/api.ts

@@ -3,7 +3,7 @@
  */
 
 import { ErrorCode, type WebAPIPlatformError, WebClient } from "@slack/web-api";
-import type { HostContext } from "../../types.js";
+import type { ArtifactsApi, HostContext } from "../../types.js";
 import {
   SLACK_DEFAULT_LOADING_MESSAGES,
   SLACK_LOADING_MESSAGE_MAX_LEN,
@@ -540,6 +540,7 @@ export function buildSlackBinding(args: {
   threadTs: string;
   teamId?: string;
   host: HostContext;
+  artifacts: ArtifactsApi;
   onThreadTsChanged?: (threadTs: string) => void;
   log?: SlackLog;
 }): SlackBinding {
@@ -643,5 +644,6 @@ export function buildSlackBinding(args: {
       ...(args.teamId === undefined ? {} : { teamId: args.teamId }),
     },
     host: args.host,
+    artifacts: args.artifacts,
   };
 }

package/src/channels/slack/cursor-account.ts

@@ -12,7 +12,7 @@
  * dispatches relayed envelopes through the pack's normal inbound path.
  */
 
-import type { HostContext, SendMessageFn } from "../../types.js";
+import type { ArtifactsApi, HostContext, SendMessageFn } from "../../types.js";
 import { dispatchInboundMessage } from "./dispatch.js";
 import type { EventIdDedupe } from "./event-id-dedupe.js";
 import { slackTextToMarkdown } from "./inbound.js";
@@ -114,6 +114,7 @@ export async function dispatchCursorSlackEnvelope(args: {
   envelope: CursorSlackEnvelope;
   send: SendMessageFn;
   host: HostContext;
+  artifacts: ArtifactsApi;
   hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
   isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
   getContinuationLastBotMessageTs?: (
@@ -167,6 +168,7 @@ export async function dispatchCursorSlackEnvelope(args: {
     send: args.send,
     credentials: runtime.credentials,
     host: args.host,
+    artifacts: args.artifacts,
     log,
     evalCommandsEnabled: runtime.options.evalCommands !== false,
     cursorAgentName: envelope.agentName,

package/src/channels/slack/dispatch.ts

@@ -2,7 +2,12 @@
  * Shared inbound dispatch for Slack Events API bodies and Socket Mode.
  */
 
-import type { HostContext, JsonValue, SendMessageFn } from "../../types.js";
+import type {
+  ArtifactsApi,
+  HostContext,
+  JsonValue,
+  SendMessageFn,
+} from "../../types.js";
 import { buildSlackBinding, slackContinuationKey } from "./api.js";
 import { firstLineTitle, maybeSetThreadTitle } from "./assistant.js";
 import type { SlackBotMentionGate } from "./bot-mentions.js";
@@ -65,6 +70,8 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
   credentials: SlackCredentials | undefined;
   eventIds: EventIdDedupe;
   host: HostContext;
+  /** Unbound artifacts facade handed to handler bindings (`ctx.artifacts`). */
+  artifacts: ArtifactsApi;
   log?: SlackLog;
   /** Dispatch on `app_mention`. Defaults to `true`. */
   mentionsEnabled?: boolean;
@@ -110,6 +117,7 @@ export async function dispatchInboundMessage(args: {
   send: SendMessageFn;
   credentials: SlackCredentials | undefined;
   host: HostContext;
+  artifacts: ArtifactsApi;
   hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
   isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
   getContinuationLastBotMessageTs?: (
@@ -132,6 +140,7 @@ export async function dispatchInboundMessage(args: {
     channelId: message.channelId,
     threadTs: message.threadTs,
     host: args.host,
+    artifacts: args.artifacts,
     log,
     ...(message.teamId === undefined ? {} : { teamId: message.teamId }),
   });
@@ -450,6 +459,7 @@ export function dispatchInboundFromEventBody(
         send: deps.send,
         credentials: deps.credentials,
         host: deps.host,
+        artifacts: deps.artifacts,
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
@@ -490,6 +500,7 @@ export function dispatchInboundFromEventBody(
         send: deps.send,
         credentials: deps.credentials,
         host: deps.host,
+        artifacts: deps.artifacts,
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,

package/src/channels/slack/interactive.ts

@@ -9,6 +9,7 @@
 
 import type {
   ApprovalDecision,
+  ArtifactsApi,
   AuthContext,
   ChannelSession,
   HostContext,
@@ -275,6 +276,7 @@ export interface SlackBlockActionDispatchDeps extends SlackContinuationProbes {
   send: SendMessageFn;
   credentials: SlackCredentials | undefined;
   host: HostContext;
+  artifacts: ArtifactsApi;
   log?: SlackLog;
 }
 
@@ -347,6 +349,7 @@ export async function dispatchBlockAction(
     send: deps.send,
     credentials: deps.credentials,
     host: deps.host,
+    artifacts: deps.artifacts,
     log,
     // Click text is synthetic — never treat it as a stop/eval directive.
     evalCommandsEnabled: false,

package/src/channels/slack/slack-channel.ts

@@ -9,6 +9,7 @@
 
 import { allowAll, defineChannel } from "../../channels.js";
 import type {
+  ArtifactsApi,
   ChannelDefinition,
   ChannelEventHandlers,
   HostContext,
@@ -215,6 +216,7 @@ export function slackChannel<const Name extends string = string>(
     send: SendMessageFn;
     waitUntil: (promise: Promise<unknown>) => void;
     host: HostContext;
+    artifacts: ArtifactsApi;
     hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
     isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
     getContinuationLastBotMessageTs?: (
@@ -230,6 +232,7 @@ export function slackChannel<const Name extends string = string>(
       credentials,
       eventIds,
       host: args.host,
+      artifacts: args.artifacts,
       log: getLog(),
       mentionsEnabled,
       directMessagesEnabled,
@@ -410,6 +413,7 @@ export function slackChannel<const Name extends string = string>(
                   send: args.send,
                   credentials,
                   host: args.host,
+                  artifacts: args.artifacts,
                   log: getLog(),
                   evalCommandsEnabled,
                   ...(args.hasContinuationSession === undefined
@@ -454,6 +458,7 @@ export function slackChannel<const Name extends string = string>(
               send: args.send,
               waitUntil: args.waitUntil,
               host: args.host,
+              artifacts: args.artifacts,
               ...(args.hasContinuationSession === undefined
                 ? {}
                 : { hasContinuationSession: args.hasContinuationSession }),
@@ -496,6 +501,7 @@ export function slackChannel<const Name extends string = string>(
             send: args.send,
             credentials,
             host: args.host,
+            artifacts: args.artifacts,
             log: getLog(),
             hasContinuationSession: args.hasContinuationSession,
             isContinuationBusy: args.isContinuationBusy,

package/src/channels/slack/types.ts

@@ -4,6 +4,7 @@
 
 import type {
   AgentCloudOptions,
+  ArtifactsApi,
   AuthContext,
   ChannelEventHandlers,
   HostContext,
@@ -189,6 +190,11 @@ export interface SlackBinding {
   };
   /** Shared host services (MCP / GitHub / Slack). */
   host: HostContext;
+  /**
+   * Durable artifacts (unbound — the handler runs before any session is
+   * admitted; pass `sessionId` in `tag` input to attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 export type SlackMessageHandler = (

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`.
  *