@cursor/bdk 0.2.1

package/src/internal/hosted-delivery.ts

@@ -0,0 +1,1152 @@
+import { randomBytes } from "node:crypto";
+import type { AuthPolicy, ChannelHandlerArgs, SendMessageOptions, TurnOutcome } from "../types.js";
+import { dispatchOutcome } from "./channel-dispatch.js";
+import {
+  consumeHostedBoundSecrets,
+  type HostedBoundSecretsResult,
+} from "./cursor/hosted-bound-secrets.js";
+import {
+  createDeferredChannelSession,
+  DeferredChannelSessionError,
+} from "./deferred-channel-session.js";
+import { describeErrorCode } from "./describe-error.js";
+import { classifyExpectedDeliveryFailure } from "./expected-delivery-failure.js";
+import {
+  formatGuestNetworkServerTiming,
+  GUEST_CONNECT_STALLED,
+  GUEST_NETWORK_UNAVAILABLE,
+  GuestNetworkUnavailableError,
+  type GuestNetworkWaitResult,
+  type GuestNetworkWaitStats,
+  waitForGuestNetworkReady,
+} from "./guest-network.js";
+import {
+  getHostedAdmissionAdapter,
+  type HostedAdmissionAdapter,
+} from "./hosted-admission-adapter.js";
+import {
+  HostedAdmissionLocalSendError,
+  runDuringHostedAdmission,
+} from "./hosted-admission-context.js";
+import {
+  HOSTED_ADMISSION_PATH,
+  HOSTED_DELIVERY_HEADER,
+  HOSTED_DELIVERY_PROTOCOL_VERSION,
+  HOSTED_EXECUTION_PATH,
+  HOSTED_GUEST_RETRY_TERMINAL,
+  HOSTED_GUEST_RETRY_TRANSIENT,
+  HOSTED_MAX_CONSUMED_DELIVERY_IDS,
+  type HostedAdmission,
+  type HostedGuestRetryDisposition,
+  type HostedReminderFireDescriptorPayload,
+  hostedFailureClassification,
+  hostedGuestErrorResponse,
+  isHostedReminderAdmission,
+  parseHostedAdmission,
+  parseHostedExecution,
+  parseHostedReminderFireDescriptorPayload,
+  parseHostedReminderFirePayload,
+} from "./hosted-delivery-protocol.js";
+import {
+  abortReasonFromTurnStatus,
+  HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
+  hostedExecutionDiagId,
+} from "./hosted-execution-diag.js";
+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";
+import { endActiveHttpSpan } from "./otel/http.js";
+import { ReminderValidationError, UnknownReminderError } from "./reminder-runner.js";
+import { mapThrownRequestError, 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 = {
+  delivery: HostedAdmission;
+  definition: object;
+  args: ChannelHandlerArgs;
+};
+
+type PendingSend = {
+  channelId: string;
+  message: string;
+  options: SendMessageOptions;
+  mailboxContinuationKey: string;
+};
+
+type AdmissionDispatch = {
+  response: Response;
+  pendingSend?: PendingSend;
+};
+
+type ExecutionReply = {
+  status: number;
+  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
+ * fail the delivery exactly once. It surfaces as a 422 because the control
+ * plane retries 5xx admissions (fresh pod, side effects re-run, identical
+ * failure, up to the Temporal attempt cap); a non-5xx/408/429 status makes
+ * it reject the delivery non-retryably instead.
+ */
+class HostedSendLimitExceeded extends Error {
+  constructor() {
+    super(
+      "The hosted delivery protocol carries exactly one pending send per " +
+        "delivery, and this delivery already captured one. Combine both " +
+        "messages into a single send(), or split the work across deliveries.",
+    );
+  }
+}
+
+// Authored/task-derived text stays bounded on this internal response path
+// (and is never persisted to Temporal history by the control plane).
+const MAX_ERROR_MESSAGE_LENGTH = 1024;
+
+function boundedMessage(text: string): string {
+  return text.length > MAX_ERROR_MESSAGE_LENGTH
+    ? `${text.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
+    : 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
+ * the existing (retryable or rethrow) handling.
+ */
+function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
+  const code =
+    error instanceof HostedSendLimitExceeded
+      ? "hosted_send_limit_exceeded"
+      : error instanceof DeferredChannelSessionError
+        ? "hosted_deferred_session_unusable"
+        : error instanceof HostedAdmissionLocalSendError
+          ? "hosted_local_send_rejected"
+          : undefined;
+  if (code === undefined) {
+    return undefined;
+  }
+  return {
+    response: terminalHostedError(422, code, boundedMessage((error as Error).message)),
+  };
+}
+
+/**
+ * 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
+ * and executed only after the control plane allocates `ses_…`. Capturing
+ * does not terminate the caller — `send` returns an inert deferred handle so
+ * a task body runs to completion before the admission response is computed.
+ *
+ * Dispatch is the adapter the mounted channel attached. Hosted delivery
+ * does not switch on `channelKind`.
+ */
+export async function dispatchHostedAdmission(input: DispatchInput): Promise<AdmissionDispatch> {
+  const adapter = getHostedAdmissionAdapter(input.definition);
+  if (adapter === undefined || adapter.kind !== input.delivery.channelKind) {
+    return {
+      response: terminalHostedError(422, "channel_kind_mismatch"),
+    };
+  }
+  // The admission window marker follows the async graph into task bodies so
+  // the engine can refuse local sends that would bypass the capture stub.
+  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,
+): Promise<AdmissionDispatch> {
+  const background: Promise<unknown>[] = [];
+  let captured: { message: string; options: SendMessageOptions } | undefined;
+  const capturingArgs: ChannelHandlerArgs = {
+    ...input.args,
+    send: async (message, options = {}) => {
+      if (captured !== undefined) {
+        throw new HostedSendLimitExceeded();
+      }
+      captured = { message, options };
+      return createDeferredChannelSession();
+    },
+    waitUntil: promise => {
+      background.push(promise);
+    },
+  };
+  const args = adapter.prepareArgs?.(capturingArgs) ?? capturingArgs;
+  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,
+      mailboxContinuationKey: input.delivery.mailboxContinuationKey,
+      platformHandoff: input.delivery.platformHandoff,
+    });
+  } catch (error) {
+    const mapped = mappedAdmissionFailure(error);
+    if (mapped !== undefined) {
+      return mapped;
+    }
+    return {
+      response: terminalHostedError(
+        500,
+        "agent_admission_threw",
+        boundedMessage(error instanceof Error ? error.message : String(error)),
+      ),
+    };
+  }
+  if (!dispatched.ok) {
+    return {
+      response: terminalHostedError(
+        dispatched.status >= 400 ? dispatched.status : 502,
+        "channel_dispatch_failed",
+      ),
+    };
+  }
+
+  try {
+    await Promise.all(background);
+  } catch (error) {
+    const mapped = mappedAdmissionFailure(error);
+    if (mapped !== undefined) {
+      return mapped;
+    }
+    return {
+      response: terminalHostedError(
+        503,
+        "background_dispatch_failed",
+        boundedMessage(error instanceof Error ? error.message : String(error)),
+      ),
+    };
+  }
+  if (captured !== undefined) {
+    return {
+      response: Response.json({
+        ok: true,
+        v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+        outcome: "send",
+      }),
+      pendingSend: {
+        channelId: input.delivery.channelId,
+        message: captured.message,
+        options: captured.options,
+        mailboxContinuationKey: input.delivery.mailboxContinuationKey,
+      },
+    };
+  }
+  // A "send" tag with nothing captured means the channel's send bypassed the
+  // capture stub, so there is nothing for the control plane to execute.
+  const outcome = dispatchOutcome(dispatched);
+  if (outcome === undefined || outcome === "send") {
+    return {
+      response: terminalHostedError(502, "channel_outcome_missing"),
+    };
+  }
+  return {
+    response: Response.json({
+      ok: true,
+      v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+      outcome,
+    }),
+  };
+}
+
+function withServerTiming(
+  response: Response,
+  durationMs: number,
+  guestNetwork?: GuestNetworkWaitStats,
+  latency?: HostedExecutionLatencySnapshot,
+): Response {
+  const parts = [`agent_sdk;desc="hosted";dur=${Math.max(0, durationMs).toFixed(1)}`];
+  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, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+function guestNetworkStatsFromWait(value: unknown): GuestNetworkWaitStats {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "outcome" in value &&
+    ((value as GuestNetworkWaitResult).outcome === "ready" ||
+      (value as GuestNetworkWaitResult).outcome === "skipped") &&
+    typeof (value as GuestNetworkWaitResult).waitMs === "number" &&
+    typeof (value as GuestNetworkWaitResult).probeAttempts === "number"
+  ) {
+    const result = value as GuestNetworkWaitResult;
+    return {
+      outcome: result.outcome,
+      waitMs: result.waitMs,
+      probeAttempts: result.probeAttempts,
+    };
+  }
+  if (value === "skipped") {
+    return { outcome: "skipped", waitMs: 0, probeAttempts: 0 };
+  }
+  return { outcome: "ready", waitMs: 0, probeAttempts: 0 };
+}
+
+function guestNetworkStatsFromError(error: unknown): GuestNetworkWaitStats {
+  if (error instanceof GuestNetworkUnavailableError) {
+    return {
+      outcome: "unavailable",
+      waitMs: error.waitMs,
+      probeAttempts: error.probeAttempts,
+    };
+  }
+  return { outcome: "unavailable", waitMs: 0, probeAttempts: 0 };
+}
+
+function logGuestNetworkWait(phase: "admission" | "execution", stats: GuestNetworkWaitStats): void {
+  if (stats.outcome === "skipped") {
+    return;
+  }
+  console.info(
+    `[agent-sdk] guest network ${stats.outcome} phase=${phase} waitMs=${String(stats.waitMs)} probes=${String(stats.probeAttempts)}`,
+  );
+}
+
+export function registerHostedDeliveryRoute(input: {
+  router: Router;
+  base: string;
+  channels: Array<{ id: string; definition: object }>;
+  buildHandlerArgs(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
+   * moment the reply lands, and a shed session-record flush would strand
+   * the conversation on the next wake.
+   */
+  drainSessionDurability?(sessionId: string): Promise<void>;
+  /**
+   * Export in-memory OTel batches before the HTTP reply. Hosted v2 may
+   * destroy the VM as soon as that reply lands; SIGTERM is not guaranteed.
+   */
+  flushOtel?(): Promise<void>;
+  /**
+   * Serve `--state-root` (not the per-slug SessionEngine dir). Hosted
+   * freeze is `/workspace/.agent-serve`; the Temporal host reads
+   * `hosted-execution.json` from that path after the POST returns.
+   */
+  stateRoot?: string;
+  /**
+   * Upsert this execution into the v2 session-level framework-store log.
+   * Called for the pre-turn `running` claim and every terminal outcome so
+   * a dead Node process still leaves a leftover. Soft-fail inside the
+   * store; this path still awaits so a parked pod cannot shed the write.
+   */
+  persistSessionRun?(write: SessionRunExecutionWrite): Promise<void>;
+  /** Snapshot the local `start.log` tee onto `logs/{ses_…}`. */
+  flushStartLog?(startLogId: string): Promise<void>;
+  /** Snapshot of the process log ring at persist time. */
+  snapshotLogs?(): LogRingEntry[];
+  /**
+   * Drop the cached SDK agent handle before the HTTP reply. Hosted v2
+   * hibernates this process as soon as the reply lands; leaving the handle
+   * in memory freezes a dead Connect/HTTP2 session that the next wake
+   * then reuses.
+   */
+  evictSdkSession?(sessionId: string): void;
+  /**
+   * Wait until guest egress works before authored admission/execution.
+   * Defaults to {@link waitForGuestNetworkReady}. Tests inject a stub.
+   */
+  waitForGuestNetwork?(): Promise<GuestNetworkWaitResult | unknown>;
+  /**
+   * Hydrate `process.env` from the task-bind secret files and remove them
+   * from disk. Defaults to {@link consumeHostedBoundSecrets}. Tests inject a
+   * stub.
+   */
+  consumeBoundSecrets?(): HostedBoundSecretsResult;
+}): void {
+  const pending = new Map<
+    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());
+  const consumeBoundSecrets = input.consumeBoundSecrets ?? (() => consumeHostedBoundSecrets());
+  /**
+   * Close the bind-file handoff before anything else touches the request.
+   * A surviving secret is retryable: the control plane re-binds and the next
+   * attempt consumes a fresh pair of files.
+   */
+  const finishBoundSecrets = (): Response | undefined => {
+    const consumed = consumeBoundSecrets();
+    return consumed.ok
+      ? undefined
+      : transientHostedError(503, consumed.code, boundedMessage(consumed.message));
+  };
+  const finishNetworkWait = async (
+    phase: "admission" | "execution",
+  ): Promise<{
+    response?: Response;
+    timing: GuestNetworkWaitStats;
+  }> => {
+    try {
+      const timing = guestNetworkStatsFromWait(await waitForNetwork());
+      logGuestNetworkWait(phase, timing);
+      return { timing };
+    } catch (error) {
+      const timing = guestNetworkStatsFromError(error);
+      logGuestNetworkWait(phase, timing);
+      const message =
+        error instanceof GuestNetworkUnavailableError
+          ? error.message
+          : error instanceof Error
+            ? error.message
+            : "Guest network is not ready for outbound requests.";
+      return {
+        timing,
+        response: transientHostedError(503, GUEST_NETWORK_UNAVAILABLE, boundedMessage(message)),
+      };
+    }
+  };
+  const pruneExpired = () => {
+    const now = Date.now();
+    for (const [token, item] of pending) {
+      if (item.expiresAt <= now) {
+        pending.delete(token);
+      }
+    }
+  };
+
+  // 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 => {
+    if (request.headers.get(HOSTED_DELIVERY_HEADER) !== "1") {
+      return null;
+    }
+    return {
+      authenticator: "app",
+      principalId: "agent-sdk:hosted-delivery",
+      principalType: "runtime",
+    };
+  };
+  input.router.add({
+    method: "POST",
+    pattern: `${input.base}${HOSTED_ADMISSION_PATH}`,
+    auth: [auth],
+    handler: async request =>
+      afterHostedWork(input.flushOtel, async () => {
+        const startedAt = performance.now();
+        let guestNetwork: GuestNetworkWaitStats | undefined;
+        const finish = (response: Response) =>
+          withServerTiming(response, performance.now() - startedAt, guestNetwork);
+        const unconsumed = finishBoundSecrets();
+        if (unconsumed !== undefined) {
+          return finish(unconsumed);
+        }
+        const rawAdmission = await readJsonObject(request);
+        const delivery = parseHostedAdmission(rawAdmission);
+        if (delivery === undefined) {
+          const rawKeys =
+            typeof rawAdmission === "object" &&
+            rawAdmission !== null &&
+            !Array.isArray(rawAdmission)
+              ? Object.keys(rawAdmission as Record<string, unknown>)
+              : [];
+          console.info(
+            `[agent-sdk] hosted admission rejected: envelope failed to parse keys=${JSON.stringify(rawKeys)} hasManagedAutomation=${String(rawKeys.includes("managedAutomation"))}`,
+          );
+          return finish(
+            terminalHostedError(
+              400,
+              "invalid_hosted_admission",
+              "Expected a supported Agent SDK hosted-admission envelope.",
+            ),
+          );
+        }
+        console.info(
+          `[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(
+            terminalHostedError(
+              404,
+              "channel_not_found",
+              `No channel named "${delivery.channelId}" is mounted.`,
+            ),
+          );
+        }
+        const network = await finishNetworkWait("admission");
+        guestNetwork = network.timing;
+        if (network.response !== undefined) {
+          return finish(network.response);
+        }
+        const admitted = await dispatchHostedAdmission({
+          delivery,
+          definition: channel.definition,
+          args: input.buildHandlerArgs(delivery.channelId),
+        });
+        if (admitted.pendingSend === undefined) {
+          return finish(admitted.response);
+        }
+        pruneExpired();
+        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({
+            ok: true,
+            v: HOSTED_DELIVERY_PROTOCOL_VERSION,
+            outcome: "send",
+            admissionToken,
+          }),
+        );
+      }),
+  });
+  input.router.add({
+    method: "POST",
+    pattern: `${input.base}${HOSTED_EXECUTION_PATH}`,
+    auth: [auth],
+    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, latencySnapshot);
+        const unconsumed = finishBoundSecrets();
+        if (unconsumed !== undefined) {
+          return finish(unconsumed);
+        }
+        const execution = parseHostedExecution(await readJsonObject(request));
+        if (execution === undefined) {
+          return finish(
+            terminalHostedError(
+              400,
+              "invalid_hosted_execution",
+              "Expected a supported Agent SDK hosted-execution envelope.",
+            ),
+          );
+        }
+        pruneExpired();
+        const admitted = pending.get(execution.admissionToken);
+        if (admitted === undefined) {
+          return finish(
+            transientHostedError(
+              409,
+              "hosted_admission_unavailable",
+              "The hosted admission token is missing or expired.",
+            ),
+          );
+        }
+        if (
+          admitted.sessionPublicId !== undefined &&
+          admitted.sessionPublicId !== execution.sessionPublicId
+        ) {
+          return finish(
+            transientHostedError(
+              409,
+              "hosted_admission_session_mismatch",
+              "The hosted admission token is already bound to another session.",
+            ),
+          );
+        }
+        const network = await finishNetworkWait("execution");
+        guestNetwork = network.timing;
+        if (network.response !== undefined) {
+          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);
+          const sinks: HostedExecutionFlushSinks = {
+            ...(input.stateRoot === undefined ? {} : { stateRoot: input.stateRoot }),
+            ...(input.persistSessionRun === undefined
+              ? {}
+              : { persistSessionRun: input.persistSessionRun }),
+            ...(input.flushStartLog === undefined ? {} : { flushStartLog: input.flushStartLog }),
+            ...(input.snapshotLogs === undefined ? {} : { snapshotLogs: input.snapshotLogs }),
+          };
+          const writeDiag = async (fields: {
+            sessionId: string;
+            turnStatus: string;
+            message?: string;
+            abortReason?: ReturnType<typeof abortReasonFromTurnStatus> | "execute_throw";
+            failureCode?: string;
+            errorCode?: string;
+            error?: unknown;
+          }): Promise<void> => {
+            const classification =
+              fields.failureCode === undefined
+                ? undefined
+                : hostedFailureClassification(fields.failureCode);
+            await flushHostedExecutionRecord(sinks, {
+              executionId,
+              sessionPublicId: execution.sessionPublicId,
+              sessionId: fields.sessionId,
+              turnStatus: fields.turnStatus,
+              durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+              ...(fields.message === undefined ? {} : { message: fields.message }),
+              ...(fields.abortReason === undefined ? {} : { abortReason: fields.abortReason }),
+              failureCode: fields.failureCode,
+              ...(fields.errorCode === undefined ? {} : { errorCode: fields.errorCode }),
+              classification,
+              ...(fields.error === undefined ? {} : { error: fields.error }),
+            });
+          };
+          // Claim the file before the turn runs. The host reads it after its
+          // own POST returns, which for a 9-minute timeout is while this turn
+          // is still going; without this marker that read would surface the
+          // PREVIOUS delivery's terminal record as if it were this one's.
+          await writeDiag({
+            sessionId: "",
+            turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
+          });
+          let sessionId = "";
+          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,
+                  ...(outcome.errorCode === undefined ? {} : { errorCode: outcome.errorCode }),
+                });
+                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,
+                          ...(outcome.errorCode === undefined
+                            ? {}
+                            : { errorCode: outcome.errorCode }),
+                        },
+                      }
+                    : {
+                        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);
+                const thrownErrorCode = describeErrorCode(error);
+                await writeDiag({
+                  sessionId: "",
+                  turnStatus: "error",
+                  message: error instanceof Error ? error.message : String(error),
+                  abortReason: "execute_throw",
+                  failureCode: "internal_error",
+                  error,
+                  ...(thrownErrorCode === undefined ? {} : { errorCode: thrownErrorCode }),
+                });
+                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);
+                }
+              }
+            },
+          );
+        })();
+        const reply = await admitted.execution;
+        return finish(Response.json(reply.body, { status: reply.status }));
+      }),
+  });
+}
+
+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>
+): void {
+  if (evict === undefined) {
+    return;
+  }
+  const seen = new Set<string>();
+  for (const id of ids) {
+    if (id === undefined || id === "" || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    evict(id);
+  }
+}
+
+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"
+    | "unpaid_invoice"
+    | "usage_limit";
+  retry: HostedGuestRetryDisposition;
+} {
+  if (outcome.errorCode === "agent_dependency_failed") {
+    return {
+      error: "agent_dependency_failed",
+      retry: HOSTED_GUEST_RETRY_TERMINAL,
+    };
+  }
+  if (outcome.status === "cancelled") {
+    return {
+      error: "turn_cancelled",
+      retry: HOSTED_GUEST_RETRY_TERMINAL,
+    };
+  }
+  // Before the transient-code map: a usage-limit turn can carry `unknown`,
+  // which would otherwise retry as a stalled guest connect.
+  const expected = classifyExpectedDeliveryFailure(outcome.errorMessage);
+  if (expected !== undefined) {
+    return { error: expected, retry: HOSTED_GUEST_RETRY_TERMINAL };
+  }
+  if (
+    outcome.status === "error" &&
+    outcome.errorCode !== undefined &&
+    TRANSIENT_TURN_ERROR_CODES.has(outcome.errorCode)
+  ) {
+    return {
+      error: GUEST_CONNECT_STALLED,
+      retry: HOSTED_GUEST_RETRY_TRANSIENT,
+    };
+  }
+  return { error: "turn_failed", retry: HOSTED_GUEST_RETRY_TERMINAL };
+}
+
+async function afterHostedWork<T>(
+  flushOtel: (() => Promise<void>) | undefined,
+  work: () => Promise<T>,
+): Promise<T> {
+  try {
+    const result = await work();
+    if (result instanceof Response) {
+      endActiveHttpSpan(result.status);
+    }
+    return result;
+  } catch (error) {
+    const status = statusForThrownRequestError(error);
+    endActiveHttpSpan(status, status >= 500 ? error : undefined);
+    throw error;
+  } finally {
+    if (flushOtel !== undefined) {
+      try {
+        await flushOtel();
+      } catch {
+        // Soft-fail: exporter failure must not change hosted HTTP.
+      }
+    }
+  }
+}