@cursor/july 0.1.105 → 0.1.108

package/src/internal/hosted-delivery.ts

@@ -3,6 +3,7 @@ import type {
   AuthPolicy,
   ChannelHandlerArgs,
   SendMessageOptions,
+  TurnOutcome,
 } from "../types.js";
 import { dispatchOutcome } from "./channel-dispatch.js";
 import {
@@ -20,7 +21,6 @@ import {
   GuestNetworkUnavailableError,
   type GuestNetworkWaitResult,
   type GuestNetworkWaitStats,
-  isQuietGuestConnectStallMessage,
   waitForGuestNetworkReady,
 } from "./guest-network.js";
 import {
@@ -36,9 +36,18 @@ import {
   HOSTED_DELIVERY_HEADER,
   HOSTED_DELIVERY_PROTOCOL_VERSION,
   HOSTED_EXECUTION_PATH,
+  HOSTED_GUEST_RETRY_TERMINAL,
+  HOSTED_GUEST_RETRY_TRANSIENT,
   type HostedAdmission,
+  type HostedGuestRetryDisposition,
+  type HostedReminderFireDescriptorPayload,
+  hostedFailureClassification,
+  hostedGuestErrorResponse,
+  isHostedReminderAdmission,
   parseHostedAdmission,
   parseHostedExecution,
+  parseHostedReminderFireDescriptorPayload,
+  parseHostedReminderFirePayload,
 } from "./hosted-delivery-protocol.js";
 import {
   abortReasonFromTurnStatus,
@@ -50,10 +59,17 @@ 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 { statusForThrownRequestError } from "./request-error-status.js";
+import {
+  ReminderValidationError,
+  UnknownReminderError,
+} from "./reminder-runner.js";
+import {
+  mapThrownRequestError,
+  statusForThrownRequestError,
+} from "./request-error-status.js";
 import type { Router } from "./router.js";
 import type { SessionRunExecutionWrite } from "./session-run-log.js";
 
@@ -108,6 +124,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 +168,7 @@ function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
     return undefined;
   }
   return {
-    response: errorResponse(
+    response: terminalHostedError(
       422,
       code,
       boundedMessage((error as Error).message)
@@ -134,6 +176,31 @@ function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
   };
 }
 
+/**
+ * Prefer the shared throw → HTTP mapper (guest network / connect stall /
+ * session busy / …) before collapsing into agent_admission_threw or
+ * background_dispatch_failed. Those agent codes otherwise hide typed
+ * transient failures that the outer handleRequest boundary never sees.
+ */
+function mappedAdmissionFailure(error: unknown): AdmissionDispatch | undefined {
+  const rejected = nonRetryableRejection(error);
+  if (rejected !== undefined) {
+    return rejected;
+  }
+  const mapped = mapThrownRequestError(error);
+  if (mapped === undefined) {
+    return undefined;
+  }
+  return {
+    response: hostedGuestErrorResponse({
+      status: mapped.status,
+      error: mapped.code,
+      retry: mapped.retry,
+      message: boundedMessage(mapped.message),
+    }),
+  };
+}
+
 /**
  * Run authored admission without creating a framework session. Authored
  * `task` callbacks execute as sessionless work; the first `send` is captured
@@ -150,10 +217,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 +225,118 @@ 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;
+    }>;
+    /**
+     * Architecture v2: execute an immutable CP descriptor and apply the
+     * structured outcome. Must not GET/PUT reminder lifecycle documents.
+     */
+    executeReminderDescriptor?(
+      descriptor: HostedReminderFireDescriptorPayload
+    ): Promise<{
+      reminderId: string;
+      outcome: "fired" | "noop";
+      reason?: string;
+    }>;
+  },
+  delivery: HostedAdmission
+): Promise<Response> {
+  const descriptor = parseHostedReminderFireDescriptorPayload(delivery.payload);
+  if (descriptor !== undefined) {
+    if (input.executeReminderDescriptor === undefined) {
+      return transientHostedError(
+        503,
+        "reminder_dispatch_unavailable",
+        "This guest has no reminder CP executor wired for hosted admission."
+      );
+    }
+    try {
+      const result = await input.executeReminderDescriptor(descriptor);
+      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)
+        );
+      }
+      // Transient CP apply/fetch failures must remain retryable.
+      throw error;
+    }
+  }
+
+  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 descriptor or legacy 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
@@ -184,23 +360,30 @@ async function runAdmission(
   let dispatched: Response;
   try {
     dispatched = await adapter.dispatch({
+      channelId: input.delivery.channelId,
       eventType: input.delivery.eventType,
       payload: input.delivery.payload,
       deliveryId: input.delivery.deliveryId,
       args,
     });
   } catch (error) {
-    const rejected = nonRetryableRejection(error);
-    if (rejected !== undefined) {
-      return rejected;
+    const mapped = mappedAdmissionFailure(error);
+    if (mapped !== undefined) {
+      return mapped;
     }
-    throw error;
+    return {
+      response: terminalHostedError(
+        500,
+        "agent_admission_threw",
+        boundedMessage(error instanceof Error ? error.message : String(error))
+      ),
+    };
   }
   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"
       ),
     };
   }
@@ -208,12 +391,12 @@ async function runAdmission(
   try {
     await Promise.all(background);
   } catch (error) {
-    const rejected = nonRetryableRejection(error);
-    if (rejected !== undefined) {
-      return rejected;
+    const mapped = mappedAdmissionFailure(error);
+    if (mapped !== undefined) {
+      return mapped;
     }
     return {
-      response: errorResponse(
+      response: terminalHostedError(
         503,
         "background_dispatch_failed",
         boundedMessage(error instanceof Error ? error.message : String(error))
@@ -240,10 +423,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 +509,30 @@ 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;
+  }>;
+  /**
+   * Architecture v2: execute an immutable CP fire descriptor and apply the
+   * structured outcome via the hosted ReminderControlPlane client.
+   */
+  executeReminderDescriptor?(
+    descriptor: HostedReminderFireDescriptorPayload
+  ): 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 +604,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 +631,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 +691,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 +702,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 +772,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 +783,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 +795,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."
@@ -616,8 +832,13 @@ export function registerHostedDeliveryRoute(input: {
             abortReason?:
               | ReturnType<typeof abortReasonFromTurnStatus>
               | "execute_throw";
+            failureCode?: string;
             error?: unknown;
           }): Promise<void> => {
+            const classification =
+              fields.failureCode === undefined
+                ? undefined
+                : hostedFailureClassification(fields.failureCode);
             await flushHostedExecutionRecord(sinks, {
               executionId,
               sessionPublicId: execution.sessionPublicId,
@@ -633,6 +854,8 @@ export function registerHostedDeliveryRoute(input: {
               ...(fields.abortReason === undefined
                 ? {}
                 : { abortReason: fields.abortReason }),
+              failureCode: fields.failureCode,
+              classification,
               ...(fields.error === undefined ? {} : { error: fields.error }),
             });
           };
@@ -669,24 +892,30 @@ export function registerHostedDeliveryRoute(input: {
               session.id,
               execution.sessionPublicId
             );
+            const hostedFailure =
+              outcome.status === "finished"
+                ? undefined
+                : hostedFailureForUnfinishedTurn(outcome);
             await writeDiag({
               sessionId: session.id,
               turnStatus: outcome.status,
               message: outcome.errorMessage,
               abortReason: abortReasonFromTurnStatus(
                 outcome.status,
-                outcome.errorMessage
+                outcome.cancellationReason
               ),
+              failureCode: hostedFailure?.error,
             });
-            if (outcome.status !== "finished") {
-              // 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.
+            if (hostedFailure !== undefined) {
               return {
                 status: 503,
                 body: {
                   ok: false,
-                  error: hostedErrorForUnfinishedTurn(outcome.errorMessage),
+                  error: hostedFailure.error,
+                  retry: hostedFailure.retry,
+                  classification: hostedFailureClassification(
+                    hostedFailure.error
+                  ),
                   turnStatus: outcome.status,
                   message: outcome.errorMessage,
                 },
@@ -711,6 +940,7 @@ export function registerHostedDeliveryRoute(input: {
               turnStatus: "error",
               message: error instanceof Error ? error.message : String(error),
               abortReason: "execute_throw",
+              failureCode: "internal_error",
               error,
             });
             throw error;
@@ -739,16 +969,46 @@ function evictHostedSdkSessions(
   }
 }
 
-function hostedErrorForUnfinishedTurn(
-  errorMessage: string | undefined
-): typeof GUEST_CONNECT_STALLED | "turn_failed" {
+const TRANSIENT_TURN_ERROR_CODES: ReadonlySet<string> = new Set([
+  "ABORT_ERR",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "canceled",
+  "unavailable",
+  "unknown",
+]);
+
+function hostedFailureForUnfinishedTurn(outcome: TurnOutcome): {
+  error:
+    | typeof GUEST_CONNECT_STALLED
+    | "agent_dependency_failed"
+    | "turn_cancelled"
+    | "turn_failed";
+  retry: HostedGuestRetryDisposition;
+} {
+  if (outcome.errorCode === "agent_dependency_failed") {
+    return {
+      error: "agent_dependency_failed",
+      retry: HOSTED_GUEST_RETRY_TERMINAL,
+    };
+  }
   if (
-    errorMessage !== undefined &&
-    isQuietGuestConnectStallMessage(errorMessage)
+    outcome.status === "error" &&
+    outcome.errorCode !== undefined &&
+    TRANSIENT_TURN_ERROR_CODES.has(outcome.errorCode)
   ) {
-    return GUEST_CONNECT_STALLED;
+    return {
+      error: GUEST_CONNECT_STALLED,
+      retry: HOSTED_GUEST_RETRY_TRANSIENT,
+    };
+  }
+  if (outcome.status === "cancelled") {
+    return {
+      error: "turn_cancelled",
+      retry: HOSTED_GUEST_RETRY_TERMINAL,
+    };
   }
-  return "turn_failed";
+  return { error: "turn_failed", retry: HOSTED_GUEST_RETRY_TERMINAL };
 }
 
 async function afterHostedWork<T>(

package/src/internal/hosted-execution-diag.ts

@@ -8,7 +8,11 @@ import { createHash, randomBytes } from "node:crypto";
 import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { HOSTED_EXECUTION_DIAG_FILENAME } from "./hosted-delivery-protocol.js";
+import {
+  HOSTED_EXECUTION_DIAG_FILENAME,
+  type HostedFailureClassification,
+  parseHostedFailureClassification,
+} from "./hosted-delivery-protocol.js";
 
 export const HOSTED_EXECUTION_DIAG_VERSION = 1;
 /** Cap so a runaway message cannot fill the guest disk or the host log. */
@@ -57,6 +61,8 @@ export type HostedExecutionDiag = {
   signalAborted?: boolean;
   requestId?: string;
   abortReason?: HostedExecutionDiagAbortReason;
+  failureCode?: string;
+  classification?: HostedFailureClassification;
 };
 
 /** Written before the turn starts so a stalled execution still has a record. */
@@ -75,6 +81,8 @@ const DIAG_KEYS = new Set([
   "signalAborted",
   "requestId",
   "abortReason",
+  "failureCode",
+  "classification",
 ]);
 
 const ABORT_REASONS = new Set<HostedExecutionDiagAbortReason>([
@@ -137,13 +145,13 @@ export function hostedExecutionDiagPath(stateRoot: string): string {
 
 export function abortReasonFromTurnStatus(
   status: string,
-  message: string | undefined
+  cancellationReason: "signal" | "runner" | undefined
 ): HostedExecutionDiagAbortReason | undefined {
   if (status === "finished") {
     return undefined;
   }
   if (status === "cancelled") {
-    return message !== undefined && /abort/i.test(message)
+    return cancellationReason === "signal"
       ? "signal_abort"
       : "runner_cancelled";
   }
@@ -197,6 +205,14 @@ export function parseHostedExecutionDiag(
     HOSTED_ERROR_SNIPPET_MAX_CHARS
   );
   const requestId = boundedOptionalString(body.requestId, 128);
+  const failureCode = boundedOptionalString(body.failureCode, 64);
+  const classification =
+    body.classification === undefined
+      ? undefined
+      : parseHostedFailureClassification(body.classification);
+  if (body.classification !== undefined && classification === undefined) {
+    return undefined;
+  }
   const abortReason =
     body.abortReason === undefined
       ? undefined
@@ -226,6 +242,8 @@ export function parseHostedExecutionDiag(
     ...(body.signalAborted === true ? { signalAborted: true } : {}),
     ...(requestId === undefined ? {} : { requestId }),
     ...(abortReason === undefined ? {} : { abortReason }),
+    ...(failureCode === undefined ? {} : { failureCode }),
+    ...(classification === undefined ? {} : { classification }),
   };
 }
 

package/src/internal/hosted-execution-flush.ts

@@ -9,6 +9,7 @@
  * so TAS does not treat a previous delivery's terminal record as this one.
  */
 
+import type { HostedFailureClassification } from "./hosted-delivery-protocol.js";
 import {
   type HostedExecutionDiagAbortReason,
   hostedErrorStackSnippet,
@@ -46,6 +47,8 @@ export type HostedExecutionFlushFields = {
   durationMs: number;
   message?: string;
   abortReason?: HostedExecutionDiagAbortReason;
+  failureCode?: string;
+  classification?: HostedFailureClassification;
   error?: unknown;
 };
 
@@ -75,12 +78,12 @@ export async function flushHostedExecutionRecord(
       durationMs: fields.durationMs,
       ...(message === undefined ? {} : { message }),
       ...(stack === undefined || stack.length === 0 ? {} : { stack }),
-      ...(message !== undefined && /abort/i.test(message)
-        ? { signalAborted: true }
-        : {}),
+      signalAborted: fields.abortReason === "signal_abort" ? true : undefined,
       ...(fields.abortReason === undefined
         ? {}
         : { abortReason: fields.abortReason }),
+      failureCode: fields.failureCode,
+      classification: fields.classification,
     });
   }
   if (sinks.persistSessionRun !== undefined) {