@cursor/july 0.1.28 → 0.1.30

package/src/internal/reminder-runner.ts

@@ -5,7 +5,6 @@
  */
 
 import { randomBytes } from "node:crypto";
-import { join } from "node:path";
 import type {
   AuthContext,
   ReminderCreateInput,
@@ -15,6 +14,7 @@ import type {
   ReminderUntilContext,
 } from "../types.js";
 import { parseDuration } from "./duration.js";
+import type { PlatformTimers } from "./platform-timers.js";
 import {
   defaultBusyPolicy,
   MAX_TIMER_MS,
@@ -22,11 +22,7 @@ import {
   ReminderValidationError,
   resolveSchedule,
 } from "./reminder-schedule.js";
-import {
-  type ReminderBusyPolicy,
-  type ReminderRecord,
-  ReminderStore,
-} from "./reminder-store.js";
+import type { ReminderBusyPolicy, ReminderRecord } from "./reminder-store.js";
 import { APP_AUTH } from "./schedule-runner.js";
 import { SessionBusyError, type SessionEngine } from "./session-engine.js";
 
@@ -98,7 +94,7 @@ function buildFirePrompt(record: ReminderRecord): string {
 }
 
 export class ReminderRunner {
-  private readonly store: ReminderStore;
+  private readonly records = new Map<string, ReminderRecord>();
   private readonly handlers = new Map<string, LiveHandlers>();
   private readonly timers = new Map<string, NodeJS.Timeout>();
   private readonly firing = new Set<string>();
@@ -108,28 +104,70 @@ export class ReminderRunner {
 
   constructor(
     private readonly engine: SessionEngine,
-    private readonly logger: (line: string) => void = () => {}
-  ) {
-    this.store = new ReminderStore(join(engine.stateRoot, "reminders"));
-  }
+    private readonly logger: (line: string) => void = () => {},
+    private readonly platformTimers?: PlatformTimers
+  ) {}
 
-  get storeRoot(): string {
-    return join(this.engine.stateRoot, "reminders");
+  /**
+   * Load reminder documents from the control plane into memory. Does not
+   * arm in-process timers — the CP owns clocks.
+   */
+  async hydrate(): Promise<void> {
+    if (this.platformTimers === undefined) {
+      return;
+    }
+    let remote: ReminderRecord[] = [];
+    try {
+      remote = await this.platformTimers.listReminders();
+    } catch (error) {
+      this.logger(
+        `[agentkit] reminders: control-plane list failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+      return;
+    }
+    this.records.clear();
+    for (const record of remote) {
+      this.records.set(record.id, record);
+    }
+    let disarmedOrphan = 0;
+    for (const record of [...this.records.values()]) {
+      if (record.status !== "armed") {
+        continue;
+      }
+      if (
+        (record.hasRunHandler === true || record.hasUntilFn === true) &&
+        this.handlers.get(record.id) === undefined
+      ) {
+        await this.disarm(record, "handler_lost_on_restart");
+        disarmedOrphan += 1;
+      }
+    }
+    if (remote.length > 0 || disarmedOrphan > 0) {
+      this.logger(
+        `[agentkit] reminders: hydrated ${remote.length} reminder(s) from control plane` +
+          (disarmedOrphan > 0
+            ? `; disarmed ${disarmedOrphan} without live handlers`
+            : "")
+      );
+    }
   }
 
-  /** Start deadline timers for armed reminders (call after restore). */
+  /** Start deadline timers for armed reminders (tests / no control plane). */
   async start(): Promise<void> {
     if (this.started) return;
     this.started = true;
-    // Materialize sink-backed reminders onto local disk before arming
-    // (local wins when both sides have the same id).
-    await this.hydrateFromStorage();
-    const armed = await this.store.listArmed();
+    await this.hydrate();
+    if (this.platformTimers !== undefined) {
+      return;
+    }
+    const armed = [...this.records.values()].filter(
+      (r) => r.status === "armed"
+    );
     let restored = 0;
     let disarmedOrphan = 0;
     for (const record of armed) {
-      // Run / function-until handlers are in-memory only. After restart they
-      // are gone — disarm rather than falling back to a generic prompt fire.
       if (
         (record.hasRunHandler === true || record.hasUntilFn === true) &&
         this.handlers.get(record.id) === undefined
@@ -151,43 +189,52 @@ export class ReminderRunner {
     }
   }
 
-  /**
-   * Pull reminder records from `defineStorage` into `<stateRoot>/reminders`
-   * when local disk is empty for that id. Failures are logged and skipped.
-   */
-  private async hydrateFromStorage(): Promise<void> {
-    const storage = this.engine.storage;
-    if (storage === undefined || !storage.canBulkRestore) {
-      return;
+  private async persist(record: ReminderRecord): Promise<void> {
+    if (this.platformTimers !== undefined) {
+      await this.platformTimers.putReminder(record);
     }
-    let hydrated = 0;
-    try {
-      const remote = await storage.listReminders();
-      for (const record of remote) {
-        const local = await this.store.get(record.id);
-        if (local !== undefined) {
-          continue;
+    this.records.set(record.id, record);
+  }
+
+  private async getRecord(id: string): Promise<ReminderRecord | undefined> {
+    if (this.platformTimers !== undefined) {
+      try {
+        const remote = await this.platformTimers.getReminder(id);
+        if (remote === undefined) {
+          this.records.delete(id);
+          return undefined;
         }
-        // Local write only — re-mirroring would just echo the sink.
-        await this.store.save(record);
-        hydrated += 1;
+        this.records.set(id, remote);
+        return remote;
+      } catch (error) {
+        this.logger(
+          `[agentkit] reminders: control-plane get failed for ${id}: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        return this.records.get(id);
       }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.logger(`[agentkit] reminders: storage hydrate failed: ${message}`);
-      return;
-    }
-    if (hydrated > 0) {
-      this.logger(
-        `[agentkit] reminders: hydrated ${hydrated} reminder(s) from storage`
-      );
     }
+    return this.records.get(id);
   }
 
-  /** Persist locally and mirror into the authored storage sink when present. */
-  private async persist(record: ReminderRecord): Promise<void> {
-    await this.store.save(record);
-    this.engine.storage?.reminder(record);
+  private async allRecords(): Promise<ReminderRecord[]> {
+    if (this.platformTimers !== undefined) {
+      try {
+        const remote = await this.platformTimers.listReminders();
+        this.records.clear();
+        for (const record of remote) {
+          this.records.set(record.id, record);
+        }
+      } catch (error) {
+        this.logger(
+          `[agentkit] reminders: control-plane list failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+      }
+    }
+    return [...this.records.values()];
   }
 
   stop(): void {
@@ -256,7 +303,7 @@ export class ReminderRunner {
       run: input.run,
       untilFn,
     });
-    if (this.started) {
+    if (this.started && this.platformTimers === undefined) {
       this.armTimer(record);
     }
 
@@ -268,7 +315,7 @@ export class ReminderRunner {
     purpose?: string;
     continuationToken?: string;
   }): Promise<ReminderInfo[]> {
-    const all = await this.store.list();
+    const all = await this.allRecords();
     return all
       .filter((r) => {
         if (filter?.status !== undefined && r.status !== filter.status) {
@@ -301,7 +348,7 @@ export class ReminderRunner {
     id: string,
     reason = "explicit_cancel"
   ): Promise<ReminderInfo | undefined> {
-    const record = await this.store.get(id);
+    const record = await this.getRecord(id);
     if (record === undefined) {
       return undefined;
     }
@@ -325,7 +372,7 @@ export class ReminderRunner {
     continuationToken: string,
     reason: string
   ): Promise<number> {
-    const armed = await this.store.listArmed();
+    const armed = (await this.allRecords()).filter((r) => r.status === "armed");
     let n = 0;
     for (const record of armed) {
       if (record.continuationToken === continuationToken) {
@@ -347,7 +394,7 @@ export class ReminderRunner {
     oldToken: string,
     newToken: string
   ): Promise<number> {
-    const armed = await this.store.listArmed();
+    const armed = (await this.allRecords()).filter((r) => r.status === "armed");
     let n = 0;
     for (const record of armed) {
       if (
@@ -366,17 +413,30 @@ export class ReminderRunner {
     return n;
   }
 
-  /** Fire one reminder immediately (dev / hillclimb). */
-  async dispatch(reminderId: string): Promise<{
+  /** Fire one reminder immediately (dev / hillclimb / control plane). */
+  async dispatch(
+    reminderId: string,
+    opts: { expectedFireCount?: number } = {}
+  ): Promise<{
     reminderId: string;
     outcome: "fired" | "noop";
     reason?: string;
   }> {
-    const record = await this.store.get(reminderId);
+    const record = await this.getRecord(reminderId);
     if (record === undefined) {
-      const ids = (await this.store.list()).map((r) => r.id);
+      const ids = (await this.allRecords()).map((r) => r.id);
       throw new UnknownReminderError(reminderId, ids);
     }
+    if (
+      opts.expectedFireCount !== undefined &&
+      record.fireCount !== opts.expectedFireCount
+    ) {
+      return {
+        reminderId,
+        outcome: "noop",
+        reason: "stale_fire_count",
+      };
+    }
     const result = await this.fire(record.id, { force: true });
     return { reminderId, ...result };
   }
@@ -401,7 +461,7 @@ export class ReminderRunner {
         // Keep recurring reminders alive after unexpected throws.
         // One-shots stay armed so a failed wake can be retried / dispatched.
         try {
-          const current = await this.store.get(record.id);
+          const current = await this.getRecord(record.id);
           if (current === undefined || current.status !== "armed") return;
           const oneShot =
             current.scheduleKind === "delay" || current.scheduleKind === "at";
@@ -442,7 +502,7 @@ export class ReminderRunner {
     }
     this.firing.add(id);
     try {
-      const record = await this.store.get(id);
+      const record = await this.getRecord(id);
       if (record === undefined || record.status !== "armed") {
         this.clearTimer(id);
         return { outcome: "noop", reason: "not_armed" };
@@ -493,7 +553,7 @@ export class ReminderRunner {
           return { outcome: "fired", reason: "skipped_busy" };
         }
         await this.whenSessionIdle(record.channelId, record.continuationToken);
-        const still = await this.store.get(id);
+        const still = await this.getRecord(id);
         if (still === undefined || still.status !== "armed") {
           return { outcome: "noop", reason: "disarmed_while_waiting" };
         }
@@ -511,7 +571,7 @@ export class ReminderRunner {
       }
 
       // Cancel / disarm during the handler must win over reschedule.
-      const latest = await this.store.get(id);
+      const latest = await this.getRecord(id);
       if (result.action === "stop") {
         if (latest !== undefined && latest.status === "armed") {
           await this.disarm(latest, "run_stop");
@@ -740,7 +800,7 @@ export class ReminderRunner {
     _outcome: "skip" | "delivered",
     reschedule?: { delay?: string | number; at?: Date | string }
   ): Promise<void> {
-    const current = await this.store.get(record.id);
+    const current = await this.getRecord(record.id);
     if (current === undefined || current.status !== "armed") {
       return;
     }
@@ -781,7 +841,9 @@ export class ReminderRunner {
         updatedAt: new Date().toISOString(),
       };
       await this.persist(updated);
-      this.armTimer(updated);
+      if (this.platformTimers === undefined) {
+        this.armTimer(updated);
+      }
       return;
     }
 
@@ -817,7 +879,9 @@ export class ReminderRunner {
       updatedAt: new Date().toISOString(),
     };
     await this.persist(updated);
-    this.armTimer(updated);
+    if (this.platformTimers === undefined) {
+      this.armTimer(updated);
+    }
   }
 }
 

package/src/internal/reminder-store.ts

@@ -1,10 +1,11 @@
 /**
- * Durable reminder instance store under `<stateRoot>/reminders/`.
+ * Reminder document store used by the local control plane
+ * (`<stateRoot>/control-plane/reminders/`).
  *
  * Handlers (`run` / function `until`) are not serializable — they live only
- * in the in-memory {@link ReminderRunner} registry. Disk holds schedule,
- * prompt, target, and status so one-shots / recurring ticks survive restart
- * for prompt-form reminders.
+ * in the in-memory {@link ReminderRunner} registry. The control plane holds
+ * schedule, prompt, target, and status so prompt-form reminders survive
+ * restart.
  */
 
 import {

package/src/internal/sdk-runner.ts

@@ -27,6 +27,7 @@ import {
   type TurnOutcome,
   type TurnUsage,
 } from "../types.js";
+import { mapSdkTokenUsage, usageTokenSum } from "./cloud-turn-cost.js";
 
 /** Internal seam between the session engine and the Cursor SDK harness. */
 export interface AgentRunner {
@@ -215,7 +216,7 @@ export class CursorSdkRunner implements AgentRunner {
       }
       try {
         const result = await run.wait();
-        const outcome = toTurnOutcome(result);
+        let outcome = toTurnOutcome(result);
         if (outcome.status === "error") {
           // An error result usually means the handle's transport is poisoned
           // — most often a cached access token that aged past its 60-minute
@@ -224,6 +225,16 @@ export class CursorSdkRunner implements AgentRunner {
           // attempt resumes the conversation from the store on a fresh
           // transport instead of failing every turn until a restart.
           this.evictAgent(request.sessionId, agentPromise);
+        } else if (
+          request.runtime === "cloud" &&
+          outcome.status === "finished" &&
+          usageTokenSum(outcome.usage) <= 0 &&
+          result.id !== ""
+        ) {
+          // Cloud `wait()` drops usage after stream reconnect / getRun replay,
+          // or returns an all-zero stub. `getUsage` still has the run's tokens
+          // (eventually); without them traces/ABs never record an estimated cost.
+          outcome = await fillMissingCloudUsage(agent, result.id, outcome);
         }
         return outcome;
       } finally {
@@ -553,6 +564,43 @@ function toTurnOutcome(result: RunResult): TurnOutcome {
   };
 }
 
+/** Billing can lag briefly after `wait()`; retry before giving up on cost. */
+const CLOUD_USAGE_RETRY_DELAYS_MS = [0, 400, 1200] as const;
+
+/**
+ * Cloud `wait()` often omits usage after a stream drop. Pull the run's
+ * tokens from the usage API so the engine can still estimate cost.
+ * Failures are ignored: a missing estimate is better than failing the turn.
+ */
+async function fillMissingCloudUsage(
+  agent: SDKAgent,
+  runId: string,
+  outcome: TurnOutcome
+): Promise<TurnOutcome> {
+  for (const delayMs of CLOUD_USAGE_RETRY_DELAYS_MS) {
+    if (delayMs > 0) {
+      await sleep(delayMs);
+    }
+    try {
+      const billed = await agent.getUsage({ runId });
+      const mapped = mapSdkTokenUsage(billed.usage);
+      if (usageTokenSum(mapped) <= 0) {
+        continue;
+      }
+      return { ...outcome, usage: mapped };
+    } catch {
+      // Transient usage-API failures should still burn the retry budget.
+    }
+  }
+  return outcome;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
 export function runErrorMessage(result: Pick<RunResult, "error">): string {
   return result.error?.message?.trim() || "The Cursor agent run failed";
 }

package/src/internal/server.ts

@@ -98,10 +98,19 @@ import {
   requireSessionOwner,
 } from "./http-channel.js";
 import { validateToolInput } from "./json-schema.js";
+import {
+  createLocalControlPlane,
+  type LocalControlPlane,
+} from "./local-control-plane.js";
 import { createLogRing, type LogRing } from "./log-ring.js";
 import { createAgentMcpEndpoint, MCP_ENDPOINT_PATH } from "./mcp-endpoint.js";
 import { isLoopbackAddress } from "./net.js";
 import { collectPeerConnections } from "./peer-connections.js";
+import {
+  PLATFORM_SCHEDULE_CATALOG_FILENAME,
+  syncHostedPlatformSchedules,
+} from "./platform-schedule-sync.js";
+import { createCursorHostedPlatformTimers } from "./platform-timers.js";
 import {
   type AgentIndexEntry,
   renderAgentsIndexHtml,
@@ -155,6 +164,7 @@ interface MountedRuntime {
   engine: SessionEngine;
   scheduleRunner: ScheduleRunner;
   reminderRunner: ReminderRunner;
+  controlPlane?: LocalControlPlane;
   /** Playground eval batches (`/v1/dev/evals`); loopbackUrl set after listen. */
   evalRuns: EvalRunStore;
 }
@@ -196,6 +206,7 @@ export async function startServer(
   );
   const dev = options.dev ?? false;
   const playground = options.playground ?? true;
+  const noControlPlane = options.noControlPlane === true;
   const runSchedules = options.schedules ?? !dev;
   const runReminders = options.reminders ?? !dev;
 
@@ -408,7 +419,21 @@ export async function startServer(
       githubAuthWarmed = true;
     }
     const scheduleRunner = new ScheduleRunner(engine, project, logger);
-    const reminderRunner = new ReminderRunner(engine, logger);
+    let reminderRunner!: ReminderRunner;
+    const localControlPlane = noControlPlane
+      ? undefined
+      : await createLocalControlPlane({
+          fireSchedule: (name) => scheduleRunner.dispatch(name),
+          fireReminder: (id, fireCount) =>
+            reminderRunner.dispatch(id, { expectedFireCount: fireCount }),
+          stateDir: join(stateRoot, "control-plane"),
+          armReminderClocks: runReminders,
+          logger,
+        });
+    const timerClient = noControlPlane
+      ? createCursorHostedPlatformTimers()
+      : localControlPlane;
+    reminderRunner = new ReminderRunner(engine, logger, timerClient);
     const evalRuns = new EvalRunStore(
       project.rootDir,
       logger,
@@ -443,12 +468,16 @@ export async function startServer(
       scheduleRunner,
       reminderRunner,
       evalRuns,
+      ...(localControlPlane === undefined
+        ? {}
+        : { controlPlane: localControlPlane }),
     };
     runtimes.push(runtime);
     const accountRefs = accountRefsBySlug.get(slug);
     mountAgentRoutes(router, runtime, {
       dev,
       playground,
+      noControlPlane,
       multi,
       logger,
       logRing,
@@ -509,12 +538,18 @@ export async function startServer(
         }
       }
     }
-    if (runSchedules) {
-      scheduleRunner.start();
+    if (timerClient !== undefined && runSchedules) {
+      await syncHostedPlatformSchedules({
+        timers: timerClient,
+        schedules: project.schedules,
+        catalogPath: join(stateRoot, PLATFORM_SCHEDULE_CATALOG_FILENAME),
+        logger,
+      });
     }
-    if (runReminders) {
-      await reminderRunner.start();
+    if (timerClient !== undefined) {
+      await reminderRunner.hydrate();
     }
+    localControlPlane?.startClocks();
   }
 
   if (docsSite) {
@@ -806,6 +841,7 @@ export async function startServer(
       await cursorEventRelay?.stop();
       await cursorSlackRelay?.stop();
       for (const runtime of runtimes) {
+        runtime.controlPlane?.stop();
         runtime.scheduleRunner.stop();
         runtime.reminderRunner.stop();
         // Before the engines close their storage coordinators, so the
@@ -849,6 +885,7 @@ function mountAgentRoutes(
   args: {
     dev: boolean;
     playground: boolean;
+    noControlPlane?: boolean;
     multi: boolean;
     logger: (line: string) => void;
     logRing: LogRing;
@@ -860,7 +897,7 @@ function mountAgentRoutes(
   }
 ): void {
   const { slug, project, engine, scheduleRunner, reminderRunner } = runtime;
-  const { dev, playground, multi, logger, logRing } = args;
+  const { dev, playground, noControlPlane, multi, logger, logRing } = args;
   // "" (single) -> "/v1/..."; "my-agent" (multi) -> "/my-agent/v1/...".
   const base = slug === "" ? "" : `/${slug}`;
 
@@ -893,6 +930,18 @@ function mountAgentRoutes(
         ? [allowAll()]
         : [localDevStrict()];
   const httpAuth = project.httpChannel.auth ?? defaultAuth;
+  // Temporal posts this marker on a direct pod port-token fetch. The alias
+  // proxy strips it, so webhook/playground tokens cannot present it.
+  const platformTimerFireAuth: AuthPolicy = (request) => {
+    if (request.headers.get("x-agent-serve-timed-work") === "1") {
+      return {
+        authenticator: "app",
+        principalId: "agent-serve:timed-work",
+        principalType: "runtime",
+      };
+    }
+    return null;
+  };
   // Playground lists/opens Slack (and other channel) sessions across
   // principals when `--dev` (loopback) or `--allow-anonymous` (trusted
   // shared host, e.g. corp Okta ALB). Never when bearer / custom channel
@@ -1294,6 +1343,72 @@ function mountAgentRoutes(
     },
   });
 
+  if (noControlPlane === true) {
+    router.add({
+      method: "POST",
+      pattern: `${base}/v1/internal/schedules/:scheduleId/fire`,
+      auth: [platformTimerFireAuth],
+      handler: async (_request, ctx) => {
+        const scheduleId = ctx.params.scheduleId ?? "";
+        try {
+          const { sessionIds } = await scheduleRunner.dispatch(scheduleId);
+          return jsonResponse({ scheduleId, sessionIds });
+        } catch (error) {
+          if (error instanceof UnknownScheduleError) {
+            return jsonResponse(
+              {
+                ok: false,
+                error: "unknown_schedule",
+                availableScheduleIds: error.availableScheduleIds,
+              },
+              { status: 404 }
+            );
+          }
+          throw error;
+        }
+      },
+    });
+    router.add({
+      method: "POST",
+      pattern: `${base}/v1/internal/reminders/:reminderId/fire`,
+      auth: [platformTimerFireAuth],
+      handler: async (request, ctx) => {
+        const reminderId = ctx.params.reminderId ?? "";
+        const fireCountRaw = new URL(request.url).searchParams.get("fireCount");
+        const expectedFireCount =
+          fireCountRaw === null ? undefined : Number(fireCountRaw);
+        try {
+          const result = await reminderRunner.dispatch(
+            reminderId,
+            expectedFireCount !== undefined &&
+              Number.isInteger(expectedFireCount)
+              ? { expectedFireCount }
+              : {}
+          );
+          return jsonResponse(result);
+        } catch (error) {
+          if (error instanceof UnknownReminderError) {
+            return jsonResponse(
+              {
+                ok: false,
+                error: "unknown_reminder",
+                availableReminderIds: error.availableReminderIds,
+              },
+              { status: 404 }
+            );
+          }
+          if (error instanceof ReminderValidationError) {
+            return jsonResponse(
+              { ok: false, error: "invalid_reminder", message: error.message },
+              { status: 400 }
+            );
+          }
+          throw error;
+        }
+      },
+    });
+  }
+
   if (dev) {
     router.add({
       method: "POST",