@cursor/july 0.1.27 → 0.1.29

package/src/internal/session-engine.ts

@@ -21,6 +21,7 @@ import {
   SlackAskDedupeStore,
   SlackNudgeStore,
 } from "../channels/slack/nudge-store.js";
+import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
 import {
   type AgentProject,
   type ApprovalDecision,
@@ -68,11 +69,22 @@ import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
 import { samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
+import {
+  applyCloudUsageToEvents,
+  type CloudAgentUsage,
+  cloudSdkAgentIdFromEvents,
+  isUnpricedCompletedTurn,
+  mapSdkTokenUsage,
+} from "./cloud-turn-cost.js";
 import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
 import { createHostKvApi } from "./host-kv.js";
-import { createHostPlatforms, type HostPlatforms } from "./host-platforms.js";
+import {
+  createHostPlatforms,
+  createHostSlackClient,
+  type HostPlatforms,
+} from "./host-platforms.js";
 import {
   formatContinuationToken,
   newContinuationKey,
@@ -182,6 +194,12 @@ export interface SessionEngineOptions {
   runner: AgentRunner;
   logger?: (line: string) => void;
   platforms?: HostPlatforms;
+  /**
+   * Test seam / override for cloud billed usage (`Agent.getUsage`). Used to
+   * backfill `turn.completed` rows that older engines persisted without
+   * usage/cost so the playground Trace tab can still show an estimate.
+   */
+  getCloudUsage?: (sdkAgentId: string) => Promise<CloudAgentUsage | undefined>;
 }
 
 /**
@@ -289,12 +307,20 @@ export class SessionEngine {
   private readonly artifactsStore: ArtifactsStore;
   /** Serve-time resolved connections (see {@link setResolvedConnections}). */
   private resolvedConnections: EngineResolvedConnection[] = [];
+  private readonly getCloudUsage: (
+    sdkAgentId: string
+  ) => Promise<CloudAgentUsage | undefined>;
+  /** Sessions whose completed turns are fully priced (no further backfill). */
+  private readonly cloudCostBackfillDone = new Set<string>();
+  /** Deduped in-flight cloud cost backfills, keyed by session id. */
+  private readonly cloudCostBackfill = new Map<string, Promise<void>>();
 
   constructor(options: SessionEngineOptions) {
     this.project = options.project;
     this.stateRoot = options.stateRoot;
     this.runner = options.runner;
     this.logger = options.logger ?? (() => {});
+    this.getCloudUsage = options.getCloudUsage ?? defaultGetCloudUsage;
     this.turnGovernor = new TurnGovernor(options.project.agent.concurrency);
     this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
     this.nudgeStore = new SlackNudgeStore(
@@ -344,7 +370,20 @@ export class SessionEngine {
         (connection) => !isSymbolicConnectionTransport(connection.transport)
       )
     );
-    this.platforms = options.platforms ?? createHostPlatforms();
+    const basePlatforms = options.platforms ?? createHostPlatforms();
+    const slackBinding = resolveDedicatedSlackHostBinding(
+      options.project.channels
+    );
+    this.platforms =
+      slackBinding === undefined
+        ? basePlatforms
+        : {
+            github: basePlatforms.github,
+            slack: createHostSlackClient({
+              credentials: slackBinding.credentials,
+              envPrefix: slackBinding.envPrefix,
+            }),
+          };
     for (const channel of options.project.channels) {
       this.channelsById.set(channel.id, channel.definition);
     }
@@ -2266,6 +2305,9 @@ export class SessionEngine {
     sessionId: string,
     startIndex = 0
   ): Promise<ReadableStream<Uint8Array>> {
+    // Playground Trace replays this stream; backfill before the snapshot
+    // so historical Sherlock-style cloud turns can show est. cost.
+    await this.backfillCloudTurnCosts(sessionId);
     const log = await this.logs.get(sessionId);
     return log.stream(startIndex);
   }
@@ -2314,11 +2356,86 @@ export class SessionEngine {
   }
 
   /** Snapshot of recorded events (for download / offline trace). */
-  async listEvents(sessionId: string, startIndex = 0): Promise<SessionEvent[]> {
+  async listEvents(
+    sessionId: string,
+    startIndex = 0,
+    options?: { backfillCloudCost?: boolean }
+  ): Promise<SessionEvent[]> {
+    if (options?.backfillCloudCost === true) {
+      await this.backfillCloudTurnCosts(sessionId);
+    }
     const log = await this.logs.get(sessionId);
     return log.snapshot(startIndex);
   }
 
+  /**
+   * Historical cloud turns may lack usage/cost on `turn.completed` (pre-0.1.29
+   * engines, or getUsage still zero at turn end). Fill them from billed usage
+   * before the playground replays the stream so Trace can show est. cost.
+   */
+  private backfillCloudTurnCosts(sessionId: string): Promise<void> {
+    if (this.cloudCostBackfillDone.has(sessionId)) {
+      return Promise.resolve();
+    }
+    const pending = this.cloudCostBackfill.get(sessionId);
+    if (pending !== undefined) {
+      return pending;
+    }
+    const work = this.runCloudTurnCostBackfill(sessionId)
+      .catch((error) => {
+        this.logger(
+          `[agentkit] cloud cost backfill failed for ${sessionId}: ${describeError(error)}`
+        );
+      })
+      .finally(() => {
+        this.cloudCostBackfill.delete(sessionId);
+      });
+    this.cloudCostBackfill.set(sessionId, work);
+    return work;
+  }
+
+  private async runCloudTurnCostBackfill(sessionId: string): Promise<void> {
+    const log = await this.logs.get(sessionId);
+    const events = log.snapshot(0);
+    if (!events.some((event) => isUnpricedCompletedTurn(event))) {
+      if (
+        !this.isTurnRunning(sessionId) &&
+        events.some((event) => event.type === "turn.completed")
+      ) {
+        this.cloudCostBackfillDone.add(sessionId);
+      }
+      return;
+    }
+    const record = await this.sessions.get(sessionId);
+    const sdkAgentId =
+      (record?.sdkAgentId !== undefined && record.sdkAgentId.startsWith("bc-")
+        ? record.sdkAgentId
+        : undefined) ?? cloudSdkAgentIdFromEvents(events);
+    if (sdkAgentId === undefined) {
+      return;
+    }
+    const billed = await this.getCloudUsage(sdkAgentId);
+    if (billed === undefined) {
+      return;
+    }
+    const model = this.project.agent.model ?? DEFAULT_MODEL;
+    const patched = applyCloudUsageToEvents(events, billed, model);
+    if (patched === undefined) {
+      return;
+    }
+    for (let i = 0; i < patched.length; i++) {
+      const next = patched[i];
+      const prev = events[i];
+      if (next === undefined || prev === next) {
+        continue;
+      }
+      log.replace(i, next);
+    }
+    if (!log.snapshot(0).some((event) => isUnpricedCompletedTurn(event))) {
+      this.cloudCostBackfillDone.add(sessionId);
+    }
+  }
+
   async setContinuationToken(
     sessionId: string,
     token: string | null
@@ -2770,6 +2887,24 @@ function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+async function defaultGetCloudUsage(
+  sdkAgentId: string
+): Promise<CloudAgentUsage | undefined> {
+  try {
+    const { Agent } = await import("@cursor/sdk");
+    const billed = await Agent.getUsage(sdkAgentId);
+    return {
+      usage: mapSdkTokenUsage(billed.usage),
+      runs: billed.runs.map((run) => ({
+        runId: run.runId,
+        usage: mapSdkTokenUsage(run.usage),
+      })),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 /** Detects the `{ content, isError: true }` rich-result error envelope. */
 function isErrorEnvelope(result: unknown): boolean {
   return (

package/src/internal/storage-coordinator.ts

@@ -10,9 +10,10 @@
  * failures — a throwing sink is logged and its write dropped; storage
  * must never stall or fail a turn.
  *
- * Scaling shape: sessions and reminders reduce to keyed puts on the KV
- * sink; eval runs and A/B metrics go to their dedicated tables
- * (`evals` / `abs`). Everything shares one bounded, serialized queue.
+ * Scaling shape: sessions reduce to keyed puts on the KV sink; eval runs
+ * and A/B metrics go to their dedicated tables (`evals` / `abs`).
+ * Reminder documents live on the control plane. Everything shares one
+ * bounded, serialized queue.
  */
 
 import type { ABMetricSample } from "../ab.js";
@@ -29,7 +30,6 @@ import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
 import type { EvalRunStorage } from "./eval-run-store.js";
-import { isReminderRecord, type ReminderRecord } from "./reminder-store.js";
 
 /** Event types that close a unit of work — flush point for turn-end batching. */
 const TURN_BOUNDARY_EVENTS: ReadonlySet<SessionEvent["type"]> = new Set([
@@ -417,43 +417,6 @@ export class StorageCoordinator {
     return record;
   }
 
-  // ==========================================================================
-  // Reminders
-  // ==========================================================================
-
-  /**
-   * Mirror one reminder record (create / fire / cancel / disarm). Local
-   * disk under `--state-root/reminders` remains the live source of truth;
-   * this is the durable copy for host replacement.
-   */
-  reminder(record: ReminderRecord): void {
-    if (this.closed) {
-      return;
-    }
-    this.enqueue(
-      [
-        this.putOp(
-          storageKeys.reminder(this.agentName, record.id),
-          record as unknown as JsonValue
-        ),
-      ],
-      "policy"
-    );
-  }
-
-  /**
-   * Saved reminder records for this agent (startup hydrate into local
-   * disk). Errors read as empty — same posture as session bulk restore.
-   */
-  async listReminders(): Promise<ReminderRecord[]> {
-    const entries = await this.tryList(
-      storageKeys.reminderPrefix(this.agentName)
-    );
-    return entries.flatMap((entry) =>
-      isReminderRecord(entry.value) ? [entry.value] : []
-    );
-  }
-
   // ==========================================================================
   // Author KV ({@link HostContext.kv})
   // ==========================================================================

package/src/storage.ts

@@ -275,7 +275,6 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
  * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
  * | `agentkit/v1/{agent}/artifacts/{id}` | `ArtifactRecord` via `ctx.artifacts` |
  *
@@ -301,10 +300,6 @@ export const storageKeys = {
     continuationKey: string
   ): string =>
     `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
-  reminder: (agent: string, reminderId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
-  reminderPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
   /**
    * Author-facing opaque JSON (see {@link HostContext.kv}). `key` is
    * URI-encoded / digested like other caller-controlled segments.

package/src/types.ts

@@ -2108,6 +2108,8 @@ export interface AgentChannelRouteInfo {
 /** JSON-safe projection of the manifest returned by `GET /v1/info`. */
 export interface AgentProjectInfo {
   name: string;
+  /** Short agent description when authored on `defineAgent`. */
+  description?: string;
   model?: ModelSetting;
   runtime: AgentRuntime;
   cloud?: AgentCloudPublicInfo;
@@ -2251,10 +2253,17 @@ export interface ServeOptions {
   schedules?: boolean;
   /**
    * Arm reminder deadline timers automatically. Defaults to `!dev`
-   * (same as schedules). Prompt-form reminders still persist in `--dev`;
-   * fire them via `POST /v1/dev/reminders/:id` or `handle.dispatchReminder`.
+   * (same as schedules). Prompt-form reminders still persist on the
+   * control plane in `--dev`; fire them via `POST /v1/dev/reminders/:id`
+   * or `handle.dispatchReminder`.
    */
   reminders?: boolean;
+  /**
+   * Do not start the bundled control plane (schedule/reminder clocks).
+   * Cursor hosting passes this so the kit talks to the Cursor backend
+   * instead. Local `serve` should leave this unset.
+   */
+  noControlPlane?: boolean;
   /**
    * Serve the bundled web playground at `/playground` (chat, streaming,
    * tool calls, sessions, schedule dispatch). Defaults to true; the API