@cursor/july 0.1.109 → 0.1.112

package/src/internal/hosted-delivery.ts

@@ -38,6 +38,7 @@ import {
   HOSTED_EXECUTION_PATH,
   HOSTED_GUEST_RETRY_TERMINAL,
   HOSTED_GUEST_RETRY_TRANSIENT,
+  HOSTED_MAX_CONSUMED_DELIVERY_IDS,
   type HostedAdmission,
   type HostedGuestRetryDisposition,
   type HostedReminderFireDescriptorPayload,
@@ -58,6 +59,13 @@ import {
   flushHostedExecutionRecord,
   type HostedExecutionFlushSinks,
 } from "./hosted-execution-flush.js";
+import {
+  finalizeHostedExecutionLatency,
+  formatHostedExecutionLatencyServerTiming,
+  type HostedExecutionLatencySnapshot,
+  hostedExecutionNow,
+  runWithHostedExecutionLatency,
+} from "./hosted-execution-latency.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { readJsonObject } from "./http-channel.js";
 import type { LogRingEntry } from "./log-ring.js";
@@ -71,6 +79,10 @@ import {
   statusForThrownRequestError,
 } from "./request-error-status.js";
 import type { Router } from "./router.js";
+import {
+  type EngineSendOptions,
+  HostedEnqueueNotActiveError,
+} from "./session-engine.js";
 import type { SessionRunExecutionWrite } from "./session-run-log.js";
 
 type DispatchInput = {
@@ -96,6 +108,19 @@ type ExecutionReply = {
   body: Record<string, unknown>;
 };
 
+type HostedEnqueueOutcome = {
+  outcome: "enqueued" | "not_active";
+};
+
+type ActiveOwnerContext = {
+  primaryDeliveryId: string;
+  acceptedDeliveryIds: string[];
+  accepting: boolean;
+  inflightInjects: Set<Promise<void>>;
+  /** Shared result for duplicate enqueue deliveryId retries. */
+  enqueueResults: Map<string, Promise<HostedEnqueueOutcome>>;
+};
+
 /**
  * A second `send()` in one delivery is a deterministic authored bug — the
  * wire protocol carries exactly one pending send per delivery — so it must
@@ -352,7 +377,7 @@ async function runAdmission(
       captured = { message, options };
       return createDeferredChannelSession();
     },
-    waitUntil: (promise) => {
+    waitUntil: promise => {
       background.push(promise);
     },
   };
@@ -365,6 +390,8 @@ async function runAdmission(
       payload: input.delivery.payload,
       deliveryId: input.delivery.deliveryId,
       args,
+      mailboxContinuationKey: input.delivery.mailboxContinuationKey,
+      platformHandoff: input.delivery.platformHandoff,
     });
   } catch (error) {
     const mapped = mappedAdmissionFailure(error);
@@ -438,7 +465,8 @@ async function runAdmission(
 function withServerTiming(
   response: Response,
   durationMs: number,
-  guestNetwork?: GuestNetworkWaitStats
+  guestNetwork?: GuestNetworkWaitStats,
+  latency?: HostedExecutionLatencySnapshot
 ): Response {
   const parts = [
     `agent_sdk;desc="hosted";dur=${Math.max(0, durationMs).toFixed(1)}`,
@@ -446,6 +474,9 @@ function withServerTiming(
   if (guestNetwork !== undefined) {
     parts.push(formatGuestNetworkServerTiming(guestNetwork));
   }
+  if (latency !== undefined) {
+    parts.push(...formatHostedExecutionLatencyServerTiming(latency));
+  }
   const headers = new Headers(response.headers);
   headers.set("Server-Timing", parts.join(", "));
   return new Response(response.body, {
@@ -585,11 +616,14 @@ export function registerHostedDeliveryRoute(input: {
     string,
     {
       send: PendingSend;
+      channelKind: string;
       expiresAt: number;
+      deliveryId: string;
       sessionPublicId?: string;
       execution?: Promise<ExecutionReply>;
     }
   >();
+  const activeOwners = new Map<string, ActiveOwnerContext>();
   const pendingTtlMs = 10 * 60_000;
   const waitForNetwork =
     input.waitForGuestNetwork ?? (() => waitForGuestNetworkReady());
@@ -650,7 +684,7 @@ export function registerHostedDeliveryRoute(input: {
 
   // Hosted callers reach this only through AnyRun's signed pod-port URL.
   // The marker is a second, route-specific fence distinct from channel auth.
-  const auth: AuthPolicy = (request) => {
+  const auth: AuthPolicy = request => {
     if (request.headers.get(HOSTED_DELIVERY_HEADER) !== "1") {
       return null;
     }
@@ -664,7 +698,7 @@ export function registerHostedDeliveryRoute(input: {
     method: "POST",
     pattern: `${input.base}${HOSTED_ADMISSION_PATH}`,
     auth: [auth],
-    handler: async (request) =>
+    handler: async request =>
       afterHostedWork(input.flushOtel, async () => {
         const startedAt = performance.now();
         let guestNetwork: GuestNetworkWaitStats | undefined;
@@ -711,7 +745,7 @@ export function registerHostedDeliveryRoute(input: {
           return finish(await dispatchHostedReminderAdmission(input, delivery));
         }
         const channel = input.channels.find(
-          (candidate) => candidate.id === delivery.channelId
+          candidate => candidate.id === delivery.channelId
         );
         if (channel === undefined) {
           return finish(
@@ -739,7 +773,9 @@ export function registerHostedDeliveryRoute(input: {
         const admissionToken = randomBytes(24).toString("hex");
         pending.set(admissionToken, {
           send: admitted.pendingSend,
+          channelKind: delivery.channelKind,
           expiresAt: Date.now() + pendingTtlMs,
+          deliveryId: delivery.deliveryId,
         });
         return finish(
           Response.json({
@@ -755,15 +791,17 @@ export function registerHostedDeliveryRoute(input: {
     method: "POST",
     pattern: `${input.base}${HOSTED_EXECUTION_PATH}`,
     auth: [auth],
-    handler: async (request) =>
+    handler: async request =>
       afterHostedWork(input.flushOtel, async () => {
         const startedAt = performance.now();
         let guestNetwork: GuestNetworkWaitStats | undefined;
+        let latencySnapshot: HostedExecutionLatencySnapshot | undefined;
         const finish = (response: Response) =>
           withServerTiming(
             response,
             performance.now() - startedAt,
-            guestNetwork
+            guestNetwork,
+            latencySnapshot
           );
         const unconsumed = finishBoundSecrets();
         if (unconsumed !== undefined) {
@@ -808,6 +846,24 @@ export function registerHostedDeliveryRoute(input: {
           return finish(network.response);
         }
         admitted.sessionPublicId = execution.sessionPublicId;
+
+        if (execution.mode === "enqueue") {
+          const enqueueOutcome = await enqueueIntoActiveOwner({
+            activeOwners,
+            sessionPublicId: execution.sessionPublicId,
+            deliveryId: admitted.deliveryId,
+            send: admitted.send,
+            buildHandlerArgs: input.buildHandlerArgs,
+          });
+          return finish(
+            Response.json({
+              ok: true,
+              v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+              ...enqueueOutcome,
+            })
+          );
+        }
+
         admitted.execution ??= (async (): Promise<ExecutionReply> => {
           const startedAt = performance.now();
           const executionId = hostedExecutionDiagId(execution.admissionToken);
@@ -868,83 +924,154 @@ export function registerHostedDeliveryRoute(input: {
             turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
           });
           let sessionId = "";
-          try {
-            const args = input.buildHandlerArgs(
-              admitted.send.channelId,
-              execution.sessionPublicId
-            );
-            const session = await args.send(admitted.send.message, {
-              ...admitted.send.options,
-              mailboxContinuation: {
-                key: admitted.send.mailboxContinuationKey,
-              },
-            });
-            sessionId = session.id;
-            const outcome = await session.waitForCompletion();
-            // Failed turns drain too: their record/continuation updates must
-            // survive the park just like a finished turn's.
-            await input.drainSessionDurability?.(session.id);
-            // Evict before the reply: TAS parks and hibernates this process
-            // as soon as the POST returns. A leftover SDK handle freezes a
-            // dead Connect/HTTP2 session that the next wake then reuses.
-            evictHostedSdkSessions(
-              input.evictSdkSession,
-              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.cancellationReason
-              ),
-              failureCode: hostedFailure?.error,
-            });
-            if (hostedFailure !== undefined) {
-              return {
-                status: 503,
-                body: {
-                  ok: false,
-                  error: hostedFailure.error,
-                  retry: hostedFailure.retry,
-                  classification: hostedFailureClassification(
-                    hostedFailure.error
-                  ),
+          const owner: ActiveOwnerContext = {
+            primaryDeliveryId: admitted.deliveryId,
+            acceptedDeliveryIds: [],
+            accepting: true,
+            inflightInjects: new Set(),
+            enqueueResults: new Map(),
+          };
+          activeOwners.set(execution.sessionPublicId, owner);
+          return await runWithHostedExecutionLatency(
+            { channelKind: admitted.channelKind },
+            async () => {
+              let completionAt: number | undefined;
+              let drainAt: number | undefined;
+              try {
+                const args = input.buildHandlerArgs(
+                  admitted.send.channelId,
+                  execution.sessionPublicId
+                );
+                const session = await args.send(admitted.send.message, {
+                  ...admitted.send.options,
+                  mailboxContinuation: {
+                    key: admitted.send.mailboxContinuationKey,
+                  },
+                });
+                sessionId = session.id;
+                // The pre-turn claim used an empty sessionId. Stamp the
+                // engine id now so a dashboard / session-view poll that
+                // only has the factory `ses_…` can follow `session-events/`.
+                await writeDiag({
+                  sessionId,
+                  turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
+                });
+                const outcome = await session.waitForCompletion();
+                completionAt = hostedExecutionNow();
+                // Status is the owner turn. waitForCompletion still waited
+                // for any drained successor so this process is not parked
+                // mid-follow-up; a successor failure must not 503-retry the
+                // owner after satellites already ran.
+                // Close acceptance at the turn boundary, before durability
+                // work creates an idle-but-still-addressable window.
+                owner.accepting = false;
+                if (owner.inflightInjects.size > 0) {
+                  await Promise.allSettled([...owner.inflightInjects]);
+                }
+                // Failed turns drain too: their record/continuation updates must
+                // survive the park just like a finished turn's.
+                await input.drainSessionDurability?.(session.id);
+                drainAt = hostedExecutionNow();
+                const consumedDeliveryIds = [
+                  owner.primaryDeliveryId,
+                  ...owner.acceptedDeliveryIds,
+                ];
+                if (
+                  consumedDeliveryIds.length > HOSTED_MAX_CONSUMED_DELIVERY_IDS
+                ) {
+                  throw new Error(
+                    `hosted execute consumedDeliveryIds length ${String(consumedDeliveryIds.length)} exceeds cap ${String(HOSTED_MAX_CONSUMED_DELIVERY_IDS)}`
+                  );
+                }
+                // Evict before the reply: TAS parks and hibernates this process
+                // as soon as the POST returns. A leftover SDK handle freezes a
+                // dead Connect/HTTP2 session that the next wake then reuses.
+                evictHostedSdkSessions(
+                  input.evictSdkSession,
+                  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.cancellationReason
+                  ),
+                  failureCode: hostedFailure?.error,
+                });
+                const reply =
+                  hostedFailure !== undefined
+                    ? {
+                        status: 503,
+                        body: {
+                          ok: false,
+                          error: hostedFailure.error,
+                          retry: hostedFailure.retry,
+                          classification: hostedFailureClassification(
+                            hostedFailure.error
+                          ),
+                          turnStatus: outcome.status,
+                          message: outcome.errorMessage,
+                        },
+                      }
+                    : {
+                        status: 200,
+                        body: {
+                          ok: true,
+                          v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+                          outcome: "send",
+                          consumedDeliveryIds,
+                        },
+                      };
+                // Finalize as late as possible so `post_drain` and `total`
+                // include eviction + diag write after durability drain.
+                latencySnapshot = finalizeHostedExecutionLatency({
+                  completionAt,
+                  drainAt,
+                  endedAt: hostedExecutionNow(),
+                });
+                return reply;
+              } catch (error) {
+                owner.accepting = false;
+                if (owner.inflightInjects.size > 0) {
+                  await Promise.allSettled([...owner.inflightInjects]);
+                }
+                evictHostedSdkSessions(
+                  input.evictSdkSession,
+                  sessionId,
+                  execution.sessionPublicId
+                );
+                await writeDiag({
+                  sessionId: "",
+                  turnStatus: "error",
+                  message:
+                    error instanceof Error ? error.message : String(error),
+                  abortReason: "execute_throw",
+                  failureCode: "internal_error",
+                  error,
+                });
+                const endedAt = hostedExecutionNow();
+                // Preserve completion/drain marks when the failure happened
+                // during post-drain work; otherwise collapse to endedAt.
+                latencySnapshot = finalizeHostedExecutionLatency({
+                  completionAt: completionAt ?? endedAt,
+                  drainAt: drainAt ?? endedAt,
+                  endedAt,
+                });
+                throw error;
+              } finally {
+                if (activeOwners.get(execution.sessionPublicId) === owner) {
+                  activeOwners.delete(execution.sessionPublicId);
+                }
+              }
             }
-            return {
-              status: 200,
-              body: {
-                ok: true,
-                v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-                outcome: "send",
-              },
-            };
-          } catch (error) {
-            evictHostedSdkSessions(
-              input.evictSdkSession,
-              sessionId,
-              execution.sessionPublicId
-            );
-            await writeDiag({
-              sessionId: "",
-              turnStatus: "error",
-              message: error instanceof Error ? error.message : String(error),
-              abortReason: "execute_throw",
-              failureCode: "internal_error",
-              error,
-            });
-            throw error;
-          }
+          );
         })();
         const reply = await admitted.execution;
         return finish(Response.json(reply.body, { status: reply.status }));
@@ -952,6 +1079,92 @@ export function registerHostedDeliveryRoute(input: {
   });
 }
 
+async function enqueueIntoActiveOwner(input: {
+  activeOwners: Map<string, ActiveOwnerContext>;
+  sessionPublicId: string;
+  deliveryId: string;
+  send: PendingSend;
+  buildHandlerArgs: (
+    channelId: string,
+    sessionPublicId?: string
+  ) => ChannelHandlerArgs;
+}): Promise<HostedEnqueueOutcome> {
+  const owner = input.activeOwners.get(input.sessionPublicId);
+  if (owner === undefined || !owner.accepting) {
+    return { outcome: "not_active" };
+  }
+
+  const existing = owner.enqueueResults.get(input.deliveryId);
+  if (existing !== undefined) {
+    const shared = await existing;
+    if (shared.outcome === "enqueued" || shared.outcome === "not_active") {
+      return { outcome: shared.outcome };
+    }
+    return { outcome: "not_active" };
+  }
+
+  let resolveResult!: (value: HostedEnqueueOutcome) => void;
+  const resultPromise = new Promise<HostedEnqueueOutcome>(resolve => {
+    resolveResult = resolve;
+  });
+  owner.enqueueResults.set(input.deliveryId, resultPromise);
+
+  // Capacity includes the primary delivery id.
+  if (
+    1 + owner.acceptedDeliveryIds.length >=
+    HOSTED_MAX_CONSUMED_DELIVERY_IDS
+  ) {
+    const outcome = { outcome: "not_active" as const };
+    resolveResult(outcome);
+    return outcome;
+  }
+
+  // Reserve before send so concurrent enqueues cannot oversubscribe.
+  owner.acceptedDeliveryIds.push(input.deliveryId);
+
+  const inject = (async (): Promise<void> => {
+    try {
+      const args = input.buildHandlerArgs(
+        input.send.channelId,
+        input.sessionPublicId
+      );
+      const enqueueOptions = {
+        ...input.send.options,
+        mailboxContinuation: {
+          key: input.send.mailboxContinuationKey,
+        },
+        hostedEnqueueOnly: true,
+      } as SendMessageOptions & EngineSendOptions;
+      const session = await args.send(input.send.message, enqueueOptions);
+      if (session.coalesced !== true) {
+        throw new HostedEnqueueNotActiveError(input.sessionPublicId);
+      }
+      resolveResult({ outcome: "enqueued" });
+    } catch (error) {
+      const idx = owner.acceptedDeliveryIds.lastIndexOf(input.deliveryId);
+      if (idx >= 0) {
+        owner.acceptedDeliveryIds.splice(idx, 1);
+      }
+      resolveResult({ outcome: "not_active" });
+      if (!(error instanceof HostedEnqueueNotActiveError)) {
+        console.warn(
+          `[agent-sdk] hosted enqueue inject failed deliveryId=${input.deliveryId}: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+      }
+    }
+  })();
+
+  owner.inflightInjects.add(inject);
+  try {
+    await inject;
+  } finally {
+    owner.inflightInjects.delete(inject);
+  }
+  return await resultPromise;
+}
+
 function evictHostedSdkSessions(
   evict: ((sessionId: string) => void) | undefined,
   ...ids: Array<string | undefined>

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

@@ -118,8 +118,8 @@ export function hostedErrorStackSnippet(error: unknown): string {
     if (stack !== undefined && stack.length > 0) {
       const lines = stack
         .split("\n")
-        .map((line) => line.trimEnd())
-        .filter((line) => line.trim().length > 0)
+        .map(line => line.trimEnd())
+        .filter(line => line.trim().length > 0)
         .slice(0, HOSTED_ERROR_STACK_LINE_COUNT);
       const text = lines.join("\n");
       return text.length > HOSTED_ERROR_SNIPPET_MAX_CHARS
@@ -174,7 +174,7 @@ export function parseHostedExecutionDiag(
     return undefined;
   }
   const body = parsed as Record<string, unknown>;
-  if (Object.keys(body).some((key) => !DIAG_KEYS.has(key))) {
+  if (Object.keys(body).some(key => !DIAG_KEYS.has(key))) {
     return undefined;
   }
   if (