@cursor/july 0.1.105 → 0.1.107

package/src/internal/hosted-delivery.ts

@@ -36,9 +36,15 @@ import {
   HOSTED_DELIVERY_HEADER,
   HOSTED_DELIVERY_PROTOCOL_VERSION,
   HOSTED_EXECUTION_PATH,
+  HOSTED_GUEST_RETRY_TERMINAL,
+  HOSTED_GUEST_RETRY_TRANSIENT,
   type HostedAdmission,
+  type HostedGuestRetryDisposition,
+  hostedGuestErrorResponse,
+  isHostedReminderAdmission,
   parseHostedAdmission,
   parseHostedExecution,
+  parseHostedReminderFirePayload,
 } from "./hosted-delivery-protocol.js";
 import {
   abortReasonFromTurnStatus,
@@ -50,9 +56,13 @@ import {
   type HostedExecutionFlushSinks,
 } from "./hosted-execution-flush.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
-import { errorResponse, readJsonObject } from "./http-channel.js";
+import { readJsonObject } from "./http-channel.js";
 import type { LogRingEntry } from "./log-ring.js";
 import { endActiveHttpSpan } from "./otel/http.js";
+import {
+  ReminderValidationError,
+  UnknownReminderError,
+} from "./reminder-runner.js";
 import { statusForThrownRequestError } from "./request-error-status.js";
 import type { Router } from "./router.js";
 import type { SessionRunExecutionWrite } from "./session-run-log.js";
@@ -108,6 +118,32 @@ function boundedMessage(text: string): string {
     : text;
 }
 
+function terminalHostedError(
+  status: number,
+  error: string,
+  message?: string
+): Response {
+  return hostedGuestErrorResponse({
+    status,
+    error,
+    retry: HOSTED_GUEST_RETRY_TERMINAL,
+    message,
+  });
+}
+
+function transientHostedError(
+  status: number,
+  error: string,
+  message?: string
+): Response {
+  return hostedGuestErrorResponse({
+    status,
+    error,
+    retry: HOSTED_GUEST_RETRY_TRANSIENT,
+    message,
+  });
+}
+
 /**
  * Classify deterministic authored protocol violations as non-retryable 422
  * admissions. Anything else returns `undefined` so callers fall through to
@@ -126,7 +162,7 @@ function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
     return undefined;
   }
   return {
-    response: errorResponse(
+    response: terminalHostedError(
       422,
       code,
       boundedMessage((error as Error).message)
@@ -150,10 +186,7 @@ export async function dispatchHostedAdmission(
   const adapter = getHostedAdmissionAdapter(input.definition);
   if (adapter === undefined || adapter.kind !== input.delivery.channelKind) {
     return {
-      response: Response.json(
-        { ok: false, error: "channel_kind_mismatch" },
-        { status: 422 }
-      ),
+      response: terminalHostedError(422, "channel_kind_mismatch"),
     };
   }
   // The admission window marker follows the async graph into task bodies so
@@ -161,6 +194,70 @@ export async function dispatchHostedAdmission(
   return runDuringHostedAdmission(() => runAdmission(input, adapter));
 }
 
+/**
+ * Reserved reminder admission: parse the compact payload and invoke
+ * ReminderRunner.dispatch. Returns a standard hosted outcome (`task` /
+ * `skip`) and never opens the send-capture / model-session path here —
+ * prompt-form fires still follow up inside the runner.
+ */
+async function dispatchHostedReminderAdmission(
+  input: {
+    fireReminder?(
+      reminderId: string,
+      expectedFireCount: number
+    ): Promise<{
+      reminderId: string;
+      outcome: "fired" | "noop";
+      reason?: string;
+    }>;
+  },
+  delivery: HostedAdmission
+): Promise<Response> {
+  if (input.fireReminder === undefined) {
+    return transientHostedError(
+      503,
+      "reminder_dispatch_unavailable",
+      "This guest has no reminder runner wired for hosted admission."
+    );
+  }
+  const payload = parseHostedReminderFirePayload(delivery.payload);
+  if (payload === undefined) {
+    return terminalHostedError(
+      400,
+      "invalid_reminder_payload",
+      "Expected reminder payload { reminderId, fireCount }."
+    );
+  }
+  try {
+    const result = await input.fireReminder(
+      payload.reminderId,
+      payload.fireCount
+    );
+    const outcome = result.outcome === "noop" ? "skip" : "task";
+    return Response.json({
+      ok: true,
+      v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+      outcome,
+    });
+  } catch (error) {
+    if (error instanceof UnknownReminderError) {
+      return terminalHostedError(
+        404,
+        "unknown_reminder",
+        boundedMessage(error.message)
+      );
+    }
+    if (error instanceof ReminderValidationError) {
+      return terminalHostedError(
+        400,
+        "invalid_reminder",
+        boundedMessage(error.message)
+      );
+    }
+    throw error;
+  }
+}
+
 async function runAdmission(
   input: DispatchInput,
   adapter: HostedAdmissionAdapter
@@ -198,9 +295,9 @@ async function runAdmission(
   }
   if (!dispatched.ok) {
     return {
-      response: Response.json(
-        { ok: false, error: "channel_dispatch_failed" },
-        { status: dispatched.status >= 400 ? dispatched.status : 502 }
+      response: terminalHostedError(
+        dispatched.status >= 400 ? dispatched.status : 502,
+        "channel_dispatch_failed"
       ),
     };
   }
@@ -213,7 +310,7 @@ async function runAdmission(
       return rejected;
     }
     return {
-      response: errorResponse(
+      response: terminalHostedError(
         503,
         "background_dispatch_failed",
         boundedMessage(error instanceof Error ? error.message : String(error))
@@ -240,10 +337,7 @@ async function runAdmission(
   const outcome = dispatchOutcome(dispatched);
   if (outcome === undefined || outcome === "send") {
     return {
-      response: Response.json(
-        { ok: false, error: "channel_outcome_missing" },
-        { status: 502 }
-      ),
+      response: terminalHostedError(502, "channel_outcome_missing"),
     };
   }
   return {
@@ -329,6 +423,19 @@ export function registerHostedDeliveryRoute(input: {
     channelId: string,
     sessionPublicId?: string
   ): ChannelHandlerArgs;
+  /**
+   * Reserved reminder admission: dispatch a hydrated ReminderRunner fire
+   * without authored channel admission. Returns the runner's outcome so the
+   * route can map fired → task and noop → skip.
+   */
+  fireReminder?(
+    reminderId: string,
+    expectedFireCount: number
+  ): Promise<{
+    reminderId: string;
+    outcome: "fired" | "noop";
+    reason?: string;
+  }>;
   /**
    * Await the session's durable mirror (dispatch chain + storage queue)
    * before the execution reply: the control plane may park the pod the
@@ -400,7 +507,11 @@ export function registerHostedDeliveryRoute(input: {
     const consumed = consumeBoundSecrets();
     return consumed.ok
       ? undefined
-      : errorResponse(503, consumed.code, boundedMessage(consumed.message));
+      : transientHostedError(
+          503,
+          consumed.code,
+          boundedMessage(consumed.message)
+        );
   };
   const finishNetworkWait = async (
     phase: "admission" | "execution"
@@ -423,7 +534,7 @@ export function registerHostedDeliveryRoute(input: {
             : "Guest network is not ready for outbound requests.";
       return {
         timing,
-        response: errorResponse(
+        response: transientHostedError(
           503,
           GUEST_NETWORK_UNAVAILABLE,
           boundedMessage(message)
@@ -483,7 +594,7 @@ export function registerHostedDeliveryRoute(input: {
             `[agent-sdk] hosted admission rejected: envelope failed to parse keys=${JSON.stringify(rawKeys)} hasManagedAutomation=${String(rawKeys.includes("managedAutomation"))}`
           );
           return finish(
-            errorResponse(
+            terminalHostedError(
               400,
               "invalid_hosted_admission",
               "Expected a supported Agent SDK hosted-admission envelope."
@@ -494,12 +605,20 @@ export function registerHostedDeliveryRoute(input: {
           `[agent-sdk] hosted admission received deliveryId=${delivery.deliveryId} channelId=${delivery.channelId} channelKind=${delivery.channelKind} eventType=${delivery.eventType} sessionMode=${delivery.sessionMode} managedAutomation=${delivery.managedAutomation === undefined ? "<absent>" : `automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${delivery.managedAutomation.slackChannels === undefined ? "<absent>" : JSON.stringify(delivery.managedAutomation.slackChannels)}`}`
         );
         recordHostedManagedAutomation(delivery);
+        if (isHostedReminderAdmission(delivery)) {
+          const network = await finishNetworkWait("admission");
+          guestNetwork = network.timing;
+          if (network.response !== undefined) {
+            return finish(network.response);
+          }
+          return finish(await dispatchHostedReminderAdmission(input, delivery));
+        }
         const channel = input.channels.find(
           (candidate) => candidate.id === delivery.channelId
         );
         if (channel === undefined) {
           return finish(
-            errorResponse(
+            terminalHostedError(
               404,
               "channel_not_found",
               `No channel named "${delivery.channelId}" is mounted.`
@@ -556,7 +675,7 @@ export function registerHostedDeliveryRoute(input: {
         const execution = parseHostedExecution(await readJsonObject(request));
         if (execution === undefined) {
           return finish(
-            errorResponse(
+            terminalHostedError(
               400,
               "invalid_hosted_execution",
               "Expected a supported Agent SDK hosted-execution envelope."
@@ -567,7 +686,7 @@ export function registerHostedDeliveryRoute(input: {
         const admitted = pending.get(execution.admissionToken);
         if (admitted === undefined) {
           return finish(
-            errorResponse(
+            transientHostedError(
               409,
               "hosted_admission_unavailable",
               "The hosted admission token is missing or expired."
@@ -579,7 +698,7 @@ export function registerHostedDeliveryRoute(input: {
           admitted.sessionPublicId !== execution.sessionPublicId
         ) {
           return finish(
-            errorResponse(
+            transientHostedError(
               409,
               "hosted_admission_session_mismatch",
               "The hosted admission token is already bound to another session."
@@ -682,11 +801,15 @@ export function registerHostedDeliveryRoute(input: {
               // waitForCompletion resolves (does not throw) on a quiet
               // Connect abort. Map that to guest_connect_stalled so TAS
               // retries the same pod. Real runner failures stay turn_failed.
+              const hostedFailure = hostedFailureForUnfinishedTurn(
+                outcome.errorMessage
+              );
               return {
                 status: 503,
                 body: {
                   ok: false,
-                  error: hostedErrorForUnfinishedTurn(outcome.errorMessage),
+                  error: hostedFailure.error,
+                  retry: hostedFailure.retry,
                   turnStatus: outcome.status,
                   message: outcome.errorMessage,
                 },
@@ -739,16 +862,20 @@ function evictHostedSdkSessions(
   }
 }
 
-function hostedErrorForUnfinishedTurn(
-  errorMessage: string | undefined
-): typeof GUEST_CONNECT_STALLED | "turn_failed" {
+function hostedFailureForUnfinishedTurn(errorMessage: string | undefined): {
+  error: typeof GUEST_CONNECT_STALLED | "turn_failed";
+  retry: HostedGuestRetryDisposition;
+} {
   if (
     errorMessage !== undefined &&
     isQuietGuestConnectStallMessage(errorMessage)
   ) {
-    return GUEST_CONNECT_STALLED;
+    return {
+      error: GUEST_CONNECT_STALLED,
+      retry: HOSTED_GUEST_RETRY_TRANSIENT,
+    };
   }
-  return "turn_failed";
+  return { error: "turn_failed", retry: HOSTED_GUEST_RETRY_TERMINAL };
 }
 
 async function afterHostedWork<T>(