@cursor/july 0.1.107 → 0.1.109

package/src/internal/platform-timers.ts

@@ -8,6 +8,14 @@
  * executes fires.
  */
 
+import {
+  REMINDER_CP_PROTOCOL_VERSION,
+  type ReminderControlPlane,
+  type ReminderCreateIntent,
+  type ReminderExecutionOutcome,
+  type ReminderFireClaim,
+  type ReminderOutcomeApplyResult,
+} from "./reminder-control-plane-protocol.js";
 import { isReminderRecord, type ReminderRecord } from "./reminder-store.js";
 
 const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
@@ -171,3 +179,186 @@ export function createCursorHostedPlatformTimers(
     },
   };
 }
+
+/** v2 reminder CP is factory ECS (`/internal/agentsdk/*`), not timed-work. */
+const AGENTSDK_REMINDERS_PREFIX = "/internal/agentsdk";
+
+/**
+ * Bounded retries for idempotent CP outcome writes after the guest handler
+ * has already run. Delivery is at-least-once: a transient apply failure may
+ * re-enter the handler on the next Temporal admission. Do not claim
+ * exactly-once handler execution.
+ */
+const APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS = 3;
+const APPLY_REMINDER_OUTCOME_RETRY_DELAY_MS = 50;
+
+async function sleepMs(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function withBoundedApplyRetries<T>(run: () => Promise<T>): Promise<T> {
+  let lastError: unknown;
+  for (
+    let attempt = 1;
+    attempt <= APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS;
+    attempt++
+  ) {
+    try {
+      return await run();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS) {
+        break;
+      }
+      await sleepMs(APPLY_REMINDER_OUTCOME_RETRY_DELAY_MS * attempt);
+    }
+  }
+  throw lastError;
+}
+
+async function timedWorkJsonFetch(
+  options: CursorHostedPlatformTimersOptions,
+  method: "GET" | "POST" | "PUT" | "DELETE",
+  path: string,
+  body?: unknown
+): Promise<Response> {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("reminder control plane requires fetch");
+  }
+  return fetchImpl(`${resolveBaseUrl(options)}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${resolveApiKey(options)}`,
+      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+}
+
+/**
+ * Cursor-hosted HTTP ReminderControlPlane for architecture v2.
+ * Speaks factory `/internal/agentsdk/reminders` (ELB → factory ECS).
+ * CP owns ids and time. v1 PUT/DELETE reminders stay on timed-work.
+ */
+export function createCursorHostedReminderControlPlane(
+  options: CursorHostedPlatformTimersOptions = {}
+): ReminderControlPlane {
+  return {
+    protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+    async createReminder(intent: ReminderCreateIntent) {
+      const response = await timedWorkJsonFetch(
+        options,
+        "POST",
+        `${AGENTSDK_REMINDERS_PREFIX}/reminders`,
+        intent
+      );
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(
+          `reminder CP create failed: HTTP ${response.status} ${text}`
+        );
+      }
+      const parsed: unknown = await response.json();
+      if (!isReminderRecord(parsed)) {
+        throw new Error("reminder CP create returned invalid record");
+      }
+      return parsed;
+    },
+    async getReminder(id) {
+      const response = await timedWorkJsonFetch(
+        options,
+        "GET",
+        `${AGENTSDK_REMINDERS_PREFIX}/reminders/${encodeURIComponent(id)}`
+      );
+      if (response.status === 404) {
+        return undefined;
+      }
+      if (!response.ok) {
+        throw new Error(`reminder CP get failed: HTTP ${response.status}`);
+      }
+      const parsed: unknown = await response.json();
+      return isReminderRecord(parsed) ? parsed : undefined;
+    },
+    async listReminders() {
+      const response = await timedWorkJsonFetch(
+        options,
+        "GET",
+        `${AGENTSDK_REMINDERS_PREFIX}/reminders`
+      );
+      if (!response.ok) {
+        throw new Error(`reminder CP list failed: HTTP ${response.status}`);
+      }
+      const parsed: unknown = await response.json();
+      if (
+        parsed === null ||
+        typeof parsed !== "object" ||
+        !("reminders" in parsed) ||
+        !Array.isArray((parsed as { reminders: unknown }).reminders)
+      ) {
+        return [];
+      }
+      return (parsed as { reminders: unknown[] }).reminders.filter(
+        isReminderRecord
+      );
+    },
+    async cancelReminder(id, reason) {
+      const response = await timedWorkJsonFetch(
+        options,
+        "POST",
+        `${AGENTSDK_REMINDERS_PREFIX}/reminders/${encodeURIComponent(id)}/cancel`,
+        reason === undefined ? {} : { reason }
+      );
+      if (response.status === 404) {
+        return undefined;
+      }
+      if (!response.ok) {
+        throw new Error(`reminder CP cancel failed: HTTP ${response.status}`);
+      }
+      const parsed: unknown = await response.json();
+      return isReminderRecord(parsed) ? parsed : undefined;
+    },
+    async rekeyReminders(channelId, oldToken, newToken) {
+      const response = await timedWorkJsonFetch(
+        options,
+        "POST",
+        `${AGENTSDK_REMINDERS_PREFIX}/reminders/rekey`,
+        { channelId, oldToken, newToken }
+      );
+      if (!response.ok) {
+        throw new Error(`reminder CP rekey failed: HTTP ${response.status}`);
+      }
+      const parsed: unknown = await response.json();
+      if (
+        parsed === null ||
+        typeof parsed !== "object" ||
+        typeof (parsed as { count?: unknown }).count !== "number"
+      ) {
+        throw new Error("reminder CP rekey returned invalid body");
+      }
+      return (parsed as { count: number }).count;
+    },
+    async applyReminderOutcome(
+      claim: ReminderFireClaim,
+      outcome: ReminderExecutionOutcome
+    ): Promise<ReminderOutcomeApplyResult> {
+      // Handler side effects may already have run; retry only the idempotent
+      // CP write. Exhausted failures stay thrown so Temporal can re-admit
+      // (at-least-once — not exactly-once).
+      return await withBoundedApplyRetries(async () => {
+        const response = await timedWorkJsonFetch(
+          options,
+          "POST",
+          `${AGENTSDK_REMINDERS_PREFIX}/reminders/outcome`,
+          { claim, outcome }
+        );
+        if (!response.ok) {
+          throw new Error(
+            `reminder CP outcome apply failed: HTTP ${response.status}`
+          );
+        }
+        return (await response.json()) as ReminderOutcomeApplyResult;
+      });
+    },
+  };
+}

package/src/internal/reminder-control-plane-protocol.ts

@@ -27,6 +27,8 @@ import type { ReminderRecord } from "./reminder-store.js";
 
 /** Wire / persistence version for this control-plane protocol. */
 export const REMINDER_CP_PROTOCOL_VERSION = 1 as const;
+/** Each recurring/retry fire can spend a model turn and create hosted work. */
+export const REMINDER_CP_MIN_RECURRING_INTERVAL_MS = 60_000 as const;
 
 export type ReminderCpProtocolVersion = typeof REMINDER_CP_PROTOCOL_VERSION;
 
@@ -293,6 +295,14 @@ export function intentToNewRecord(
     scheduleSpecToCreateFields(intent.schedule),
     nowMs
   );
+  if (
+    resolved.kind === "every" &&
+    (resolved.intervalMs ?? 0) < REMINDER_CP_MIN_RECURRING_INTERVAL_MS
+  ) {
+    throw new ReminderValidationError(
+      `every must be >= 1m (got ${intent.schedule.kind === "every" ? intent.schedule.every : ""})`
+    );
+  }
   const nowIso = new Date(nowMs).toISOString();
   return {
     version: 1,
@@ -429,11 +439,14 @@ export function applyOutcomeToRecord(
   const nowIso = new Date(nowMs).toISOString();
 
   if (outcome.kind === "retry") {
-    const delayMs = outcome.delayMs ?? 0;
+    const delayMs = Math.max(
+      REMINDER_CP_MIN_RECURRING_INTERVAL_MS,
+      outcome.delayMs ?? REMINDER_CP_MIN_RECURRING_INTERVAL_MS
+    );
     const updated: ReminderRecord = {
       ...record,
       status: "armed",
-      nextFireAtMs: nowMs + Math.max(0, delayMs),
+      nextFireAtMs: nowMs + delayMs,
       // Same fireCount; bump generation so a second apply of the old claim is stale.
       generation: recordGeneration(record) + 1,
       updatedAt: nowIso,

package/src/internal/reminder-runner.ts

@@ -18,6 +18,11 @@ import type {
   ReminderStatus,
   ReminderUntilContext,
 } from "../types.js";
+import {
+  channelContinuationIdentity,
+  httpContinuationIdentity,
+} from "./continuation-channel.js";
+import { continuationSource } from "./continuation-identity.js";
 import { NAME_PATTERN } from "./discovery/names.js";
 import { parseDuration } from "./duration.js";
 import type { PlatformTimers } from "./platform-timers.js";
@@ -39,7 +44,12 @@ import {
 } from "./reminder-schedule.js";
 import type { ReminderBusyPolicy, ReminderRecord } from "./reminder-store.js";
 import { APP_AUTH } from "./schedule-runner.js";
-import { SessionBusyError, type SessionEngine } from "./session-engine.js";
+import {
+  type EngineSendOptions,
+  HTTP_CHANNEL_ID,
+  SessionBusyError,
+  type SessionEngine,
+} from "./session-engine.js";
 
 export { ReminderValidationError } from "./reminder-schedule.js";
 
@@ -1040,16 +1050,56 @@ export class ReminderRunner {
     return this.sendFollowup(record, buildFirePrompt(record), auth);
   }
 
+  /**
+   * Join the reminder's existing session. Control-plane (`/v2`) channels
+   * refuse authored `continuationToken`; pass the stored key as
+   * {@link EngineSendOptions.mailboxContinuation} so the engine reuses the
+   * CP-selected identity without channel admission.
+   */
+  private followupSendOptions(
+    record: ReminderRecord,
+    auth: AuthContext | null
+  ): EngineSendOptions {
+    if (this.channelUsesControlPlaneContinuation(record.channelId)) {
+      return {
+        auth,
+        mailboxContinuation: { key: record.continuationToken },
+      };
+    }
+    return {
+      auth,
+      continuationToken: record.continuationToken,
+    };
+  }
+
+  private channelUsesControlPlaneContinuation(channelId: string): boolean {
+    const project = this.engine.project;
+    // Test doubles may omit `project`; keep the legacy continuationToken path.
+    if (project === undefined) {
+      return false;
+    }
+    const identity =
+      channelId === HTTP_CHANNEL_ID
+        ? httpContinuationIdentity(project.httpChannel)
+        : channelContinuationIdentity(
+            project.channels.find((channel) => channel.id === channelId)
+              ?.definition
+          );
+    return continuationSource(identity) === "control-plane";
+  }
+
   private async sendFollowup(
     record: ReminderRecord,
     message: string,
     auth: AuthContext | null
   ): Promise<ReminderFireResult> {
+    const sendOptions = this.followupSendOptions(record, auth);
     try {
-      const session = await this.engine.send(record.channelId, message, {
-        auth,
-        continuationToken: record.continuationToken,
-      });
+      const session = await this.engine.send(
+        record.channelId,
+        message,
+        sendOptions
+      );
       this.engine.trackBackground(this.engine.waitForCompletion(session.id));
       return { action: "delivered" };
     } catch (error) {
@@ -1059,10 +1109,11 @@ export class ReminderRunner {
         }
         await this.whenSessionIdle(record.channelId, record.continuationToken);
         try {
-          const session = await this.engine.send(record.channelId, message, {
-            auth,
-            continuationToken: record.continuationToken,
-          });
+          const session = await this.engine.send(
+            record.channelId,
+            message,
+            sendOptions
+          );
           this.engine.trackBackground(
             this.engine.waitForCompletion(session.id)
           );

package/src/internal/resolve-prod-target.ts

@@ -16,6 +16,7 @@ import {
   validateDeploymentSlug,
 } from "./deploy-client.js";
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
 import { sleep as defaultSleep } from "./sleep.js";
 import { stderrPalette } from "./terminal-style.js";
 
@@ -38,6 +39,8 @@ export interface ResolveProdTargetOptions {
   apiKey?: string;
   fetchImpl?: typeof fetch;
   err?: (text: string) => void;
+  /** Skip when the caller already ran {@link rejectV2ForLegacyCommand}. */
+  skipLegacyArchitectureCheck?: boolean;
   /** Test seam for reachability-retry backoff. */
   sleep?: (ms: number) => Promise<void>;
 }
@@ -95,6 +98,13 @@ export async function resolveProdTarget(
       `Could not resolve Cursor credentials/team for the hosted deployment (see above).`
     );
   }
+  if (options.skipLegacyArchitectureCheck !== true) {
+    await rejectV2ForLegacyCommand({
+      client: auth.client,
+      teamId: auth.teamId,
+      slug,
+    });
+  }
 
   // A hibernated engine can briefly omit engineAccess while getPod fails
   // during wake. Retry a few times before surfacing "not reachable yet".
@@ -198,6 +208,11 @@ export async function resolveProdAliasPlaygroundUrl(
       `Could not resolve Cursor credentials/team for the hosted deployment (see above).`
     );
   }
+  await rejectV2ForLegacyCommand({
+    client: auth.client,
+    teamId: auth.teamId,
+    slug,
+  });
 
   let detail: DeploymentDetail;
   try {

package/src/internal/run-client.ts

@@ -34,7 +34,7 @@ export interface RunClientOptions extends RequestAuth {
   onEvent?: (event: SessionEvent) => void;
   /**
    * Create-time session purpose. Pass `"eval"` from the eval harness so
-   * live `defineAB` enrollment is skipped. Default `"live"`.
+   * the session is marked as regression traffic. Default `"live"`.
    */
   purpose?: SessionPurpose;
 }

package/src/internal/sdk-runner.ts

@@ -355,7 +355,7 @@ export class CursorSdkRunner implements AgentRunner {
         ) {
           // 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.
+          // (eventually); without them traces never record an estimated cost.
           outcome = await fillMissingCloudUsage(agent, result.id, outcome);
         }
         return outcome;
@@ -518,7 +518,7 @@ export class CursorSdkRunner implements AgentRunner {
     const resolved = resolveApiKeySync({ apiKey: this.options.apiKey });
     if (resolved === undefined) {
       throw new Error(
-        `The Cursor SDK runner requires a Cursor credential: run \`${CLI} login\`, set CURSOR_API_KEY or CURSOR_API_KEY_FILE, or pass serve({ apiKey }).`
+        `The Cursor SDK runner requires a Cursor credential: run \`${CLI} login\`, set CURSOR_API_KEY, CURSOR_SERVICE_ACCOUNT_KEY, or CURSOR_API_KEY_FILE, or pass serve({ apiKey }).`
       );
     }
     return resolved.apiKey;
@@ -805,6 +805,7 @@ function toTurnOutcome(result: RunResult): TurnOutcome {
     ...(result.status === "error"
       ? { errorMessage: runErrorMessage(result) }
       : {}),
+    errorCode: result.status === "error" ? result.error?.code : undefined,
     ...(usage === undefined ? {} : { usage }),
   };
 }