@cursor/july 0.1.105 → 0.1.108

package/src/internal/server.ts

@@ -66,6 +66,7 @@ import type {
   ReminderInfo,
   ServeOptions,
 } from "../types.js";
+import { invokeChannelRoute } from "./channel-route-dispatch.js";
 import { selectConversationMirror } from "./conversation-mirror.js";
 import {
   type CursorAccountConnectionRef,
@@ -129,6 +130,12 @@ import {
 } from "./handleAgentServeTrigger.js";
 import { createHostPlatforms, warmupHostGitHubAuth } from "./host-platforms.js";
 import { registerHostedDeliveryRoute } from "./hosted-delivery.js";
+import type { HostedReminderFireDescriptorPayload } from "./hosted-delivery-protocol.js";
+import {
+  HOSTED_DELIVERY_HEADER,
+  HOSTED_GUEST_RETRY_TERMINAL,
+  hostedGuestErrorResponse,
+} from "./hosted-delivery-protocol.js";
 import { hostedErrorStackSnippet } from "./hosted-execution-diag.js";
 import { flushHostedExecutionProcessDeath } from "./hosted-execution-flush.js";
 import {
@@ -138,7 +145,6 @@ import {
   readJsonObject,
   requireSessionOwner,
 } from "./http-channel.js";
-import { validateToolInput } from "./json-schema.js";
 import { DEFAULT_SERVE_PORT, listenHttpServer } from "./listen-port.js";
 import {
   createLocalControlPlane,
@@ -171,7 +177,10 @@ import {
   PLATFORM_SCHEDULE_CATALOG_FILENAME,
   syncHostedPlatformSchedules,
 } from "./platform-schedule-sync.js";
-import { createCursorHostedPlatformTimers } from "./platform-timers.js";
+import {
+  createCursorHostedPlatformTimers,
+  createCursorHostedReminderControlPlane,
+} from "./platform-timers.js";
 import {
   type AgentIndexEntry,
   renderAgentsIndexHtml,
@@ -188,9 +197,15 @@ import {
   collectMemoryHealthFields,
   sumEventLogStats,
 } from "./process-memory-telemetry.js";
+import {
+  claimFromDescriptor,
+  type ReminderControlPlane,
+  type ReminderFireDescriptor,
+} from "./reminder-control-plane-protocol.js";
 import {
   ReminderRunner,
   ReminderValidationError,
+  rejectAnonymousReminderHandlers,
   UnknownReminderError,
 } from "./reminder-runner.js";
 import { mapThrownRequestError } from "./request-error-status.js";
@@ -204,6 +219,7 @@ import { RuntimeDispatchingRunner } from "./runtime-dispatch-runner.js";
 import { ScheduleRunner, UnknownScheduleError } from "./schedule-runner.js";
 import { type AgentRunner, CursorSdkRunner } from "./sdk-runner.js";
 import {
+  HTTP_CHANNEL_ID,
   InvalidContinuationTokenError,
   SessionEngine,
   ToolInputError,
@@ -246,6 +262,11 @@ interface MountedRuntime {
   scheduleRunner: ScheduleRunner;
   reminderRunner: ReminderRunner;
   controlPlane?: LocalControlPlane;
+  /**
+   * Hosted (or local) reminder CP client for architecture v2 descriptor
+   * execution. Undefined when the project is not on the CP protocol.
+   */
+  reminderControlPlane?: ReminderControlPlane;
   /** Playground eval batches (`/v1/dev/evals`); loopbackUrl set after listen. */
   evalRuns: EvalRunStore;
 }
@@ -368,13 +389,15 @@ export async function startServer(
   // One resolution for every Cursor credential consumer (SDK runner, account
   // MCP bridge, SCM event relay, GitHub credentials): explicit option →
   // CURSOR_API_KEY → CURSOR_API_KEY_FILE (or the hosted default path) →
-  // stored `agent-sdk login`. SDK / GitHub / account MCP re-read later;
-  // Slack and deployment-event relays capture the key at start.
+  // CURSOR_SERVICE_ACCOUNT_KEY → stored `agent-sdk login`. SDK / GitHub /
+  // account MCP re-read later; Slack and deployment-event relays capture
+  // the key at start.
   const accountKey = await resolveApiKey(
     options.apiKey === undefined ? {} : { apiKey: options.apiKey }
   );
   // First present source wins (we define the order): option → env → file →
-  // stored login. Re-read so bind can drop env or file onto a listening process.
+  // service account → stored login. Re-read so bind can drop env or file
+  // onto a listening process.
   const liveCursorApiKey = (): string | undefined =>
     resolveApiKeySync(
       options.apiKey === undefined ? {} : { apiKey: options.apiKey }
@@ -846,12 +869,23 @@ export async function startServer(
     }
     const scheduleRunner = new ScheduleRunner(engine, project, logger);
     let reminderRunner!: ReminderRunner;
+    const architecture = project.agent.architecture;
+    const useReminderCpProtocol = architecture === "v2";
     const localControlPlane = noControlPlane
       ? undefined
       : await createLocalControlPlane({
           fireSchedule: (name) => scheduleRunner.dispatch(name),
-          fireReminder: (id, fireCount) =>
-            reminderRunner.dispatch(id, { expectedFireCount: fireCount }),
+          ...(useReminderCpProtocol
+            ? {
+                executeReminder: (descriptor) =>
+                  reminderRunner.executeFire(descriptor),
+              }
+            : {
+                fireReminder: (id, fireCount) =>
+                  reminderRunner.dispatch(id, {
+                    expectedFireCount: fireCount,
+                  }),
+              }),
           stateDir: join(stateRoot, "control-plane"),
           armReminderClocks: runReminders,
           logger,
@@ -859,7 +893,23 @@ export async function startServer(
     const timerClient = noControlPlane
       ? createCursorHostedPlatformTimers()
       : localControlPlane;
-    reminderRunner = new ReminderRunner(engine, logger, timerClient);
+    const hostedReminderControlPlane =
+      noControlPlane && useReminderCpProtocol
+        ? createCursorHostedReminderControlPlane()
+        : undefined;
+    const reminderControlPlane = useReminderCpProtocol
+      ? (localControlPlane ?? hostedReminderControlPlane)
+      : undefined;
+    reminderRunner = new ReminderRunner(engine, logger, timerClient, {
+      namedHandlers: project.reminders ?? [],
+      // Architecture v2 rejects anonymous run/until everywhere (local + hosted).
+      rejectAnonymousHandlers: rejectAnonymousReminderHandlers({
+        noControlPlane,
+        architecture,
+      }),
+      architecture,
+      controlPlane: reminderControlPlane,
+    });
     const evalRuns = new EvalRunStore(
       project.rootDir,
       logger,
@@ -897,6 +947,7 @@ export async function startServer(
       ...(localControlPlane === undefined
         ? {}
         : { controlPlane: localControlPlane }),
+      ...(reminderControlPlane === undefined ? {} : { reminderControlPlane }),
     };
     runtimes.push(runtime);
     const accountRefs = accountRefsBySlug.get(slug);
@@ -935,6 +986,7 @@ export async function startServer(
         const startArgs: ChannelStartArgs = {
           send: (message, sendOptions) =>
             engine.send(channel.id, message, sendOptions),
+          architecture: project.agent.architecture,
           getSession: (sessionId) =>
             engine.getChannelSession(channel.id, sessionId),
           receive: (target, input) => engine.receive(target, input),
@@ -1455,7 +1507,14 @@ function mountAgentRoutes(
     evictSdkSession?: (sessionId: string) => void;
   }
 ): void {
-  const { slug, project, engine, scheduleRunner, reminderRunner } = runtime;
+  const {
+    slug,
+    project,
+    engine,
+    scheduleRunner,
+    reminderRunner,
+    reminderControlPlane,
+  } = runtime;
   const {
     dev,
     playground,
@@ -1514,13 +1573,47 @@ function mountAgentRoutes(
     registerHostedDeliveryRoute({
       router,
       base,
-      channels: project.channels,
+      // The built-in http channel is not in `project.channels`; the control
+      // plane's session start (`agentsdk.session`) is delivered to it.
+      channels: [
+        ...project.channels,
+        { id: HTTP_CHANNEL_ID, definition: project.httpChannel },
+      ],
       buildHandlerArgs: (channelId, hostedSessionId) =>
         buildChannelHandlerArgs({
           runtime,
           channelId,
           hostedSessionId,
         }),
+      fireReminder: (reminderId, fireCount) =>
+        reminderRunner.dispatch(reminderId, { expectedFireCount: fireCount }),
+      executeReminderDescriptor: async (descriptor) => {
+        if (reminderControlPlane === undefined) {
+          throw new Error("hosted reminder CP client is not configured");
+        }
+        const fireDescriptor = descriptor as unknown as ReminderFireDescriptor;
+        const outcome = await reminderRunner.executeFire(fireDescriptor);
+        // applyReminderOutcome is idempotent and internally retries transient
+        // CP failures. Handler execution is at-least-once across Temporal
+        // re-admission if apply ultimately fails.
+        const apply = await reminderControlPlane.applyReminderOutcome(
+          claimFromDescriptor(fireDescriptor),
+          outcome
+        );
+        // Cancel/rekey winning the race is a successful no-op from the guest's
+        // perspective (fired work may have run; lifecycle authority stayed CP).
+        if (!apply.applied && apply.reason === "missing") {
+          return {
+            reminderId: descriptor.id,
+            outcome: "noop" as const,
+            reason: apply.reason,
+          };
+        }
+        return {
+          reminderId: descriptor.id,
+          outcome: "fired" as const,
+        };
+      },
       drainSessionDurability: (sessionId) =>
         engine.drainSessionDurability(sessionId),
       flushOtel: args.flushOtel,
@@ -2334,75 +2427,18 @@ function mountAgentRoutes(
         method: channelRoute.method,
         pattern: `${base}/v1/channels/${channel.id}${channelRoute.path}`,
         auth: channelAuth,
-        handler: async (request, ctx) => {
-          const handlerArgs = buildChannelHandlerArgs({
-            runtime,
-            channelId: channel.id,
-            params: ctx.params,
-            requestIp: ctx.requestIp,
-            auth: ctx.auth,
-          });
-
-          if (channelRoute.querySchema !== undefined) {
-            const rawQuery = Object.fromEntries(
-              new URL(request.url).searchParams.entries()
-            );
-            const queryValidation = validateToolInput(
-              channelRoute.querySchema,
-              rawQuery
-            );
-            if (!queryValidation.ok) {
-              return jsonResponse(
-                { error: queryValidation.message },
-                { status: 400 }
-              );
-            }
-            handlerArgs.query = queryValidation.value;
-          }
-
-          if (channelRoute.bodySchema !== undefined) {
-            // Buffer once so handlers that need the raw body (e.g. GitHub
-            // HMAC) can still read `request.text()` / `request.json()`.
-            let bodyText: string;
-            try {
-              bodyText = await request.text();
-            } catch {
-              return jsonResponse(
-                { error: "Failed to read request body" },
-                { status: 400 }
-              );
-            }
-            let rawBody: unknown;
-            try {
-              rawBody = bodyText === "" ? {} : JSON.parse(bodyText);
-            } catch {
-              return jsonResponse(
-                { error: "Request body must be valid JSON" },
-                { status: 400 }
-              );
-            }
-            const bodyValidation = validateToolInput(
-              channelRoute.bodySchema,
-              rawBody
-            );
-            if (!bodyValidation.ok) {
-              return jsonResponse(
-                { error: bodyValidation.message },
-                { status: 400 }
-              );
-            }
-            handlerArgs.body = bodyValidation.value;
-            request = new Request(request.url, {
-              method: request.method,
-              headers: request.headers,
-              body: bodyText === "" ? undefined : bodyText,
-              // node: undici / fetch may require duplex for streamed bodies;
-              // a string body does not.
-            });
-          }
-
-          return channelRoute.handler(request, handlerArgs);
-        },
+        handler: (request, ctx) =>
+          invokeChannelRoute({
+            route: channelRoute,
+            request,
+            handlerArgs: buildChannelHandlerArgs({
+              runtime,
+              channelId: channel.id,
+              params: ctx.params,
+              requestIp: ctx.requestIp,
+              auth: ctx.auth,
+            }),
+          }),
       });
     }
   }
@@ -2985,19 +3021,34 @@ async function handleRequest(
   logger: (line: string) => void
 ): Promise<void> {
   let response: Response;
+  let hostedDeliveryRequest = false;
   const method = req.method ?? "GET";
   try {
     const request = await toFetchRequest(req);
+    hostedDeliveryRequest = request.headers.get(HOSTED_DELIVERY_HEADER) === "1";
+    const requestErrorResponse = (
+      status: number,
+      error: string,
+      message: string
+    ) =>
+      hostedDeliveryRequest
+        ? hostedGuestErrorResponse({
+            status,
+            error,
+            retry: HOSTED_GUEST_RETRY_TERMINAL,
+            message,
+          })
+        : errorResponse(status, error, message);
     const url = new URL(request.url);
     const match = router.match(request.method, url.pathname);
     if (match === undefined) {
       response = router.hasPath(url.pathname)
-        ? errorResponse(
+        ? requestErrorResponse(
             405,
             "method_not_allowed",
             `${request.method} is not supported on ${url.pathname}.`
           )
-        : errorResponse(
+        : requestErrorResponse(
             404,
             "not_found",
             `No route for ${request.method} ${url.pathname}.`
@@ -3011,7 +3062,7 @@ async function handleRequest(
         unauthorized = auth === null;
       }
       response = unauthorized
-        ? errorResponse(
+        ? requestErrorResponse(
             401,
             "unauthorized",
             "No auth policy admitted this request. In production, configure channel auth (e.g. bearerAuth) — the default localDevStrict() policy only admits loopback callers with a loopback Host."
@@ -3025,7 +3076,14 @@ async function handleRequest(
   } catch (error) {
     const mapped = mapThrownRequestError(error);
     if (mapped !== undefined) {
-      response = errorResponse(mapped.status, mapped.code, mapped.message);
+      response = hostedDeliveryRequest
+        ? hostedGuestErrorResponse({
+            status: mapped.status,
+            error: mapped.code,
+            retry: mapped.retry,
+            message: mapped.message,
+          })
+        : errorResponse(mapped.status, mapped.code, mapped.message);
     } else {
       logger(
         `[agent-sdk] request failed: ${
@@ -3035,13 +3093,18 @@ async function handleRequest(
         }`
       );
       const snippet = hostedErrorStackSnippet(error);
-      response = errorResponse(
-        500,
-        "internal_error",
+      const message =
         snippet.length > 0
           ? `Internal server error: ${snippet}`
-          : "Internal server error."
-      );
+          : "Internal server error.";
+      response = hostedDeliveryRequest
+        ? hostedGuestErrorResponse({
+            status: 500,
+            error: "internal_error",
+            retry: HOSTED_GUEST_RETRY_TERMINAL,
+            message,
+          })
+        : errorResponse(500, "internal_error", message);
     }
   }