@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/hosted-delivery.ts

@@ -1,1152 +0,0 @@
-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.
-      }
-    }
-  }
-}