agents 0.24.0 → 0.26.0

package/dist/{agent-routing-B2XLNMxq.d.ts → agent-routing-0DR0Tk2v.d.ts}

@@ -8,13 +8,13 @@ import {
   u as LifecycleRouteAddress,
   v as LifecycleJobOutcome,
   x as Connection
-} from "./capability-runner-BUBa6Ake.js";
-import { t as RetryOptions } from "./retries-D9B2UCq3.js";
+} from "./capability-runner-DBAnGr6L.js";
+import { t as RetryOptions } from "./retries-CV6AkXmQ.js";
 import {
   r as LifecycleRouteEnvelope,
   t as Lifecycle
-} from "./durable-object-lifecycle-ei7M7lqB.js";
-import { n as CurrentAgentContext } from "./current-agent-C4w86kcN.js";
+} from "./durable-object-lifecycle-HhgOMWq9.js";
+import { n as CurrentAgentContext } from "./current-agent-vAk_5JMt.js";
 import { t as AgentEmail } from "./internal_context-BlxFEWfn.js";
 import { r as EmailResolver, s as SendEmailOptions } from "./email-7TatiTnl.js";
 import {
@@ -41,10 +41,10 @@ import {
   i as Schedule,
   o as ScheduleOptions,
   t as Scheduler
-} from "./scheduler-BGq6M5Kd.js";
-import { i as QueueItem } from "./types-DCD6BNZH.js";
-import { l as TaskHandlers, r as Tasks } from "./tasks-V2lCT8ZV.js";
-import { t as State } from "./index-Dlgtd3Mj.js";
+} from "./scheduler-RdACNXDP.js";
+import { i as QueueItem } from "./types-BA4anrjI.js";
+import { l as TaskHandlers, r as Tasks } from "./tasks-9YxYtByh.js";
+import { t as State } from "./index-BreL0YrQ.js";
 import { t as CallableMetadata } from "./callable-decorator-DP__HhBA.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import {
@@ -407,6 +407,11 @@ type RootFacetRpcSurface = {
     connectionId: string,
     state: unknown
   ): Promise<unknown>;
+  _cf_closeSubAgentConnectionsForPrefix(
+    prefix: ReadonlyArray<AgentPathStep>,
+    code: number,
+    reason: string
+  ): Promise<void>;
 };
 //#endregion
 //#region src/dynamic-agents/bridges.d.ts
@@ -549,9 +554,6 @@ interface DynamicAgentHostPort {
   ): boolean;
   hasSubAgent(className: string, name: string): boolean;
   _cf_resolveSubAgent(className: string, name: string): Promise<unknown>;
-  _cf_cleanupFacetPrefix(
-    ownerPath: ReadonlyArray<AgentPathStep>
-  ): Promise<void>;
   _cf_routeLifecycle(
     target: LifecycleRouteAddress | undefined,
     envelope: LifecycleRouteEnvelope
@@ -761,6 +763,12 @@ declare class DynamicAgentsInternal extends LifecycleCapability {
    * storage. Transitively deletes the child's own children.
    */
   delete(className: string, name: string): Promise<void>;
+  /** Root-side: close sockets whose `/sub/...` target is under `prefix`. */
+  closeConnectionsForPrefix(
+    prefix: ReadonlyArray<AgentPathStep>,
+    code: number,
+    reason: string
+  ): void;
   /** Drop all facet-side virtual connections (test/rehydration hook). */
   clearVirtualConnections(): void;
   /** Facet-side lookup of a virtual connection by id. */
@@ -3685,6 +3693,20 @@ declare const AGENT_TOOL_PROGRESS_PART = "data-agent-progress";
  * re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.
  */
 declare const AGENT_TOOL_MILESTONE_PART = "data-agent-milestone";
+/**
+ * Whether a chunk body is a progress or milestone frame. These are broadcast
+ * but never written to the child's chunk store, so they have no stored-chunk
+ * position and must not take part in stored-position numbering or dedupe.
+ */
+declare function isAgentToolLifecycleChunk(body: string): boolean;
+/**
+ * Whether a forwarded chunk has no stored-chunk position: a progress or
+ * milestone frame, or a chunk too large to store. Such chunks carry the next
+ * stored position without consuming it.
+ */
+declare function isPositionlessAgentToolChunk(
+  chunk: AgentToolStoredChunk
+): boolean;
 /**
  * Ephemeral progress signal a running sub-agent emits with `reportProgress`. The
  * well-known fields drive generic UI (a bar + status line) with no per-app
@@ -3851,7 +3873,17 @@ type RunAgentToolOptions<Input = unknown, Self = Record<string, unknown>> = {
    * must outlive the spawning turn; cancel it explicitly via `cancelAgentTool`.
    */
   detached?: boolean | DetachedAgentToolConfig<Self>;
+  /**
+   * Which child events reach the parent's clients. `"full"` (default) forwards
+   * every streamed chunk. `"terminal"` forwards only lifecycle events: started,
+   * progress and milestone frames, and the terminal event. The child still
+   * persists its whole stream, and the parent still tails it for completion,
+   * cancellation, progress and recovery. Use it for a headless parent with no
+   * client watching the child. Not supported with `detached`.
+   */
+  eventDelivery?: AgentToolEventDelivery;
 };
+type AgentToolEventDelivery = "full" | "terminal";
 /**
  * Result of dispatching a detached run. Returns immediately after dispatch
  * rather than after completion.
@@ -3915,6 +3947,12 @@ type AgentToolRunInspection<Output = unknown> = {
 type AgentToolStoredChunk = {
   sequence: number;
   body: string;
+  /**
+   * Set when the child broadcast this chunk but could not store it (it exceeds
+   * the stored-chunk size limit). The chunk is never replayed, so it carries
+   * the next stored position without consuming it and dedupes on this id.
+   */
+  unstoredId?: string;
 };
 type AgentToolChildAdapter<Input = unknown, Output = unknown> = {
   startAgentToolRun(
@@ -3922,11 +3960,23 @@ type AgentToolChildAdapter<Input = unknown, Output = unknown> = {
     options: {
       runId: string;
       signal?: AbortSignal;
+      /**
+       * `"terminal"` means no client is watching this run's chunks, so the
+       * child can skip broadcasting them.
+       */
+      eventDelivery?: AgentToolEventDelivery;
     }
   ): Promise<AgentToolRunInspection<Output>>;
   cancelAgentToolRun(runId: string, reason?: unknown): Promise<void>;
   inspectAgentToolRun(
-    runId: string
+    runId: string,
+    options?: {
+      /**
+       * `false` reports the stored row as-is instead of first reconciling
+       * (and possibly sealing) a stale run. Defaults to `true`.
+       */
+      reconcile?: boolean;
+    }
   ): Promise<AgentToolRunInspection<Output> | null>;
   getAgentToolChunks(
     runId: string,
@@ -3954,7 +4004,8 @@ type AgentToolEvent =
   | {
       kind: "chunk";
       runId: string;
-      body: string;
+      body: string /** See {@link AgentToolStoredChunk.unstoredId}. */;
+      unstoredId?: string;
     }
   | {
       kind: "finished";
@@ -4317,9 +4368,9 @@ declare const DEFAULT_AGENT_STATIC_OPTIONS: {
   /**
    * Optional hard wall-clock ceiling (ms) on a single agent-tool re-attach
    * (#1630). Caps the total wait even as the no-progress budget re-arms across
-   * stream-closes. Defaults to `Infinity` (no implicit cap), mirroring
-   * chat-recovery's `maxRecoveryWork` (#1672): a healthy, still-advancing child
-   * is followed for as long as it makes progress — a hung child is bounded by
+   * stream-closes. Defaults to `Infinity` (no implicit cap, #1672): a healthy,
+   * still-advancing child is followed for as long as it makes progress — a
+   * hung child is bounded by
    * the no-progress budget, and a content-runaway by the child's own
    * `maxRecoveryWork` / `shouldKeepRecovering`. Set a finite value to impose a
    * wall-clock cap (which also tears the child down on `window-exceeded`).
@@ -4389,9 +4440,9 @@ interface AgentStaticOptions {
   /**
    * Optional hard wall-clock ceiling in milliseconds on a single agent-tool
    * re-attach (#1630). Caps the total wait even as the no-progress budget
-   * re-arms across stream-closes. Default: `Infinity` (no implicit cap),
-   * mirroring chat-recovery's `maxRecoveryWork` (#1672) — a healthy,
-   * still-advancing child is followed for as long as it makes progress, exactly
+   * re-arms across stream-closes. Default: `Infinity` (no implicit cap,
+   * #1672) — a healthy, still-advancing child is followed for as long as it
+   * makes progress, exactly
    * as on the live (never-evicted) path. Set a finite value to impose a
    * wall-clock cap (which also tears the child down on `window-exceeded`); `0`
    * also disables the ceiling.
@@ -4461,7 +4512,7 @@ type WorkflowName<E> = WorkflowBinding<E> | (string & {});
 declare class Agent<
   Env extends Cloudflare.Env = Cloudflare.Env,
   TState = unknown,
-  Props extends Record<string, unknown> = Record<string, unknown>
+  Props extends object = object
 > extends DurableObject<Env> {
   /**
    * Runtime lifecycle and reusable durable capabilities for this Agent.
@@ -5501,6 +5552,11 @@ declare class Agent<
     code?: number,
     reason?: string
   ): Promise<void>;
+  _cf_closeSubAgentConnectionsForPrefix(
+    prefix: ReadonlyArray<AgentPathStep>,
+    code: number,
+    reason: string
+  ): Promise<void>;
   _cf_setSubAgentConnectionState(
     connectionId: string,
     state: unknown
@@ -5924,8 +5980,23 @@ declare class Agent<
   private _stringifyAgentToolOutput;
   private _broadcastAgentToolEvent;
   private _broadcastAgentToolChunks;
+  private _isTerminalOnlyAgentToolRun;
   private _broadcastAgentToolStoredChunks;
+  /**
+   * One budget shared by every step of a bounded recovery read, so a run's
+   * total time stays within `timeoutMs`. Returns the remaining milliseconds,
+   * never below 1 because a non-positive timeout means "unbounded".
+   */
+  private _agentToolRecoveryDeadline;
   private _broadcastAgentToolStoredChunksFromAdapter;
+  /**
+   * Milestones are persisted on the child run rather than in its chunk log, so
+   * replay re-emits them from the child's inspection. The client dedupes them
+   * on the milestone's own sequence, so a milestone already seen live is a no-op.
+   * They carry the next stored-chunk sequence without consuming it, matching
+   * the live path.
+   */
+  private _broadcastAgentToolMilestones;
   private _forwardAgentToolStream;
   /**
    * Hook invoked by `_forwardAgentToolStream` after a child produces output that
@@ -6019,9 +6090,9 @@ declare class Agent<
    * dies and recovers again during deploy churn is still collected. A genuinely
    * silent/hung child can never block recovery forever: it seals `interrupted`
    * after one `noProgressTimeoutMs` window. `maxWindowMs` is an OPTIONAL hard
-   * wall-clock ceiling (default `Infinity` — uncapped, mirroring #1672's
-   * `maxRecoveryWork`); set it finite to also bound a child that keeps
-   * progressing, which seals `window-exceeded` and tears the child down.
+   * wall-clock ceiling (default `Infinity` — uncapped, #1672); set it finite
+   * to also bound a child that keeps progressing, which seals
+   * `window-exceeded` and tears the child down.
    *
    * Returns the terminal `result` (and `completedAt`) when the child reaches a
    * terminal status, plus the advanced broadcast `sequence`. Returns
@@ -6037,6 +6108,8 @@ declare class Agent<
   private _scheduleAgentToolRunRecovery;
   private _agentToolRunRecoveryRunIds;
   private _getAgentToolChunksForRecovery;
+  /** Resolve to `undefined` when `promise` rejects or outlasts `timeoutMs`. */
+  private _settleWithinRecoveryTimeout;
   /**
    * Shared facet resolution — takes a CamelCase class name string
    * (matching `ctx.exports`) rather than a class reference. Both
@@ -6739,7 +6812,7 @@ interface AgentRouteMatch<Env = Cloudflare.Env> {
 }
 interface AgentRouteOptions<
   Env = Cloudflare.Env,
-  Props extends Record<string, unknown> = Record<string, unknown>
+  Props extends object = object
 > {
   /** URL prefix before the binding and instance name. Default: `agents`. */
   prefix?: string;
@@ -6782,10 +6855,7 @@ interface AgentRouteOptions<
 /** Configuration options for {@link routeAgentRequest}. */
 type AgentOptions<Env> = AgentRouteOptions<Env>;
 /** Options for resolving and starting a named Agent. */
-type AgentGetOptions<
-  Env,
-  Props extends Record<string, unknown> = Record<string, unknown>
-> = Pick<
+type AgentGetOptions<Env, Props extends object = object> = Pick<
   AgentRouteOptions<Env, Props>,
   "jurisdiction" | "locationHint" | "props" | "routingRetry"
 >;
@@ -6815,7 +6885,7 @@ declare function routeAgentRequest<Env>(
 declare function getAgentByName<
   Env extends Cloudflare.Env = Cloudflare.Env,
   T extends Agent<Env> = Agent<Env>,
-  Props extends Record<string, unknown> = Record<string, unknown>
+  Props extends object = object
 >(
   namespace: DurableObjectNamespace<T>,
   name: string,
@@ -6823,143 +6893,146 @@ declare function getAgentByName<
 ): Promise<DurableObjectStub<T>>;
 //#endregion
 export {
-  DetachedAgentToolConfig as $,
-  ElicitRequest$2 as $t,
+  ChatCapableAgentClass as $,
+  RPCServerTransport as $t,
   getCurrentAgent as A,
-  withInvocationScope as An,
-  MCPAIToolSet as At,
-  AgentToolInterruptedReason as B,
-  MCPServerFilter as Bt,
+  getSubAgentByName as An,
+  ElicitRequest$1 as At,
+  AgentToolFailure as B,
+  MCPConnectionResult as Bt,
   MCPServersState as C,
-  buildAgentPath as Cn,
-  WorkflowQueryCriteria as Ct,
+  BuildAgentPathOptions as Cn,
+  WorkflowInfo as Ct,
   StartFiberResult as D,
-  getSubAgentByName as Dn,
-  ElicitRequest$1 as Dt,
+  buildAgentUrl as Dn,
+  WorkflowRejectedError as Dt,
   StartFiberOptions as E,
-  buildSubAgentPathUnchecked as En,
-  WorkflowTrackingRow as Et,
+  buildAgentPath as En,
+  WorkflowQueryCriteria as Et,
   AgentToolDisplayMetadata as F,
-  MCPClientOAuthCallbackConfig as Ft,
-  AgentToolRunInfo as G,
-  normalizeServerId as Gt,
-  AgentToolMilestone as H,
-  MCP_SERVER_ID_MAX_LENGTH as Ht,
+  MCPClientElicitationHandlers as Ft,
+  AgentToolProgressSnapshot as G,
+  MCP_SERVER_ID_MAX_LENGTH as Gt,
+  AgentToolLifecycleResult as H,
+  MCPOAuthCallbackResult as Ht,
   AgentToolEvent as I,
-  MCPClientOAuthResult as It,
-  AgentToolRunState as J,
-  RPCClientTransport as Jt,
-  AgentToolRunInspection as K,
-  MCPElicitationHandler as Kt,
-  AgentToolEventMessage as L,
-  MCPConnectionResult as Lt,
+  MCPClientManager as It,
+  AgentToolRunPart as J,
+  normalizeServerId as Jt,
+  AgentToolRunInfo as K,
+  RegisterServerOptions as Kt,
+  AgentToolEventDelivery as L,
+  MCPClientManagerOptions as Lt,
   AGENT_TOOL_MILESTONE_PART as M,
-  MCPClientElicitationHandlers as Mt,
+  routeSubAgentRequest as Mn,
+  MCPAITool as Mt,
   AGENT_TOOL_PROGRESS_PART as N,
-  MCPClientManager as Nt,
+  withInvocationScope as Nn,
+  MCPAIToolSet as Nt,
   StateUpdateMessage as O,
-  parseSubAgentPath as On,
-  ElicitResult$2 as Ot,
+  buildSubAgentPath as On,
+  WorkflowStatus as Ot,
   AgentToolChildAdapter as P,
-  MCPClientManagerOptions as Pt,
-  ChatCapableAgentClass as Q,
-  RPC_DO_PREFIX as Qt,
-  AgentToolEventState as R,
-  MCPDiscoverResult as Rt,
+  MCPClientElicitationHandler as Pt,
+  AgentToolTerminalStatus as Q,
+  RPCClientTransportOptions as Qt,
+  AgentToolEventMessage as R,
+  MCPClientOAuthCallbackConfig as Rt,
   MCPServerMessage as S,
-  SubAgentPathMatch as Sn,
-  WorkflowProgressCallback as St,
+  AgentPathStep as Sn,
+  WorkflowEventPayload as St,
   RPCResponse as T,
-  buildSubAgentPath as Tn,
-  WorkflowStatus as Tt,
-  AgentToolProgress as U,
-  RegisterServerOptions as Ut,
-  AgentToolLifecycleResult as V,
-  MCPServerOptions as Vt,
-  AgentToolProgressSnapshot as W,
-  getNamespacedData as Wt,
-  AgentToolStoredChunk as X,
-  RPCServerTransport as Xt,
-  AgentToolRunStatus as Y,
-  RPCClientTransportOptions as Yt,
-  AgentToolTerminalStatus as Z,
-  RPCServerTransportOptions as Zt,
+  SubAgentPathMatch as Tn,
+  WorkflowProgressCallback as Tt,
+  AgentToolMilestone as U,
+  MCPServerFilter as Ut,
+  AgentToolInterruptedReason as V,
+  MCPDiscoverResult as Vt,
+  AgentToolProgress as W,
+  MCPServerOptions as Wt,
+  AgentToolRunStatus as X,
+  MCPElicitationHandlers as Xt,
+  AgentToolRunState as Y,
+  MCPElicitationHandler as Yt,
+  AgentToolStoredChunk as Z,
+  RPCClientTransport as Zt,
   FiberRecoveryContext as _,
-  DynamicAgentClass as _n,
-  WorkflowErrorCallback as _t,
+  WorkerTransportOptions as _n,
+  WorkflowCallbackBase as _t,
   routeAgentRequest as a,
-  createMcpHandler$1 as an,
-  AgentWorkflowOrigin as at,
+  McpAgent as an,
+  isPositionlessAgentToolChunk as at,
   ListFibersOptions as b,
-  BuildAgentPathOptions as bn,
-  WorkflowInfo as bt,
+  DynamicAgentClass as bn,
+  WorkflowErrorCallback as bt,
   Agent as c,
-  CreateMcpHandlerOptions$1 as cn,
-  AgentWorkflowStep as ct,
+  createMcpHandler$1 as cn,
+  AgentWorkflowOrigin as ct,
   AgentStaticOptions as d,
-  MCPStorageApi as dn,
-  RunWorkflowOptions as dt,
-  ElicitRequestSchema as en,
-  DetachedRunAgentToolResult as et,
+  CreateMcpHandlerOptions$1 as dn,
+  AgentWorkflowStep as dt,
+  RPCServerTransportOptions as en,
+  DetachedAgentToolConfig as et,
   DEFAULT_AGENT_STATIC_OPTIONS as f,
-  TransportState as fn,
-  WaitForApprovalOptions as ft,
+  LegacyMcpHandler as fn,
+  ApprovalEventPayload as ft,
   FiberInspection as g,
-  StreamableHTTPEdgeClientTransport as gn,
-  WorkflowCompleteCallback as gt,
+  WorkerTransport as gn,
+  WorkflowCallback as gt,
   FiberContext as h,
-  SSEEdgeClientTransport as hn,
-  WorkflowCallbackType as ht,
+  TransportState as hn,
+  WaitForApprovalOptions as ht,
   getAgentByName as i,
-  DurableObjectEventStore as in,
-  AgentWorkflowInternalParams as it,
+  ElicitResult$3 as in,
+  isAgentToolLifecycleChunk as it,
   routeAgentEmail as j,
-  MCPClientElicitationHandler as jt,
+  parseSubAgentPath as jn,
+  ElicitResult$2 as jt,
   StreamingResponse as k,
-  routeSubAgentRequest as kn,
-  MCPAITool as kt,
+  buildSubAgentPathUnchecked as kn,
+  WorkflowTrackingRow as kt,
   AgentContext as l,
-  LegacyMcpHandler as ln,
-  ApprovalEventPayload as lt,
+  experimental_createMcpHandler as ln,
+  AgentWorkflowParams as lt,
   EmailRoutingOptions as m,
-  WorkerTransportOptions as mn,
-  WorkflowCallbackBase as mt,
+  MCPStorageApi as mn,
+  RunWorkflowOptions as mt,
   AgentOptions as n,
-  McpAgent as nn,
-  RunAgentToolResult as nt,
+  ElicitRequest$2 as nn,
+  RunAgentToolOptions as nt,
   AddMcpServerOptions as o,
-  experimental_createMcpHandler as on,
-  AgentWorkflowParams as ot,
+  ClearableEventStore as on,
+  AgentWorkflowEvent as ot,
   DeleteFibersOptions as p,
-  WorkerTransport as pn,
-  WorkflowCallback as pt,
-  AgentToolRunPart as q,
-  MCPElicitationHandlers as qt,
+  createLegacyMcpHandler as pn,
+  DefaultProgress as pt,
+  AgentToolRunInspection as q,
+  getNamespacedData as qt,
   RoutingRetryOptions as r,
-  ClearableEventStore as rn,
-  AgentWorkflowEvent as rt,
+  ElicitRequestSchema as rn,
+  RunAgentToolResult as rt,
   AddRpcMcpServerOptions as s,
-  CreateLegacyMcpHandlerOptions as sn,
-  AgentWorkflowPathStep as st,
+  DurableObjectEventStore as sn,
+  AgentWorkflowInternalParams as st,
   AgentGetOptions as t,
-  ElicitResult$3 as tn,
-  RunAgentToolOptions as tt,
+  RPC_DO_PREFIX as tn,
+  DetachedRunAgentToolResult as tt,
   AgentNamespace as u,
-  createLegacyMcpHandler as un,
-  DefaultProgress as ut,
+  CreateLegacyMcpHandlerOptions as un,
+  AgentWorkflowPathStep as ut,
   FiberRecoveryResult as v,
-  DynamicAgentStub as vn,
-  WorkflowEventCallback as vt,
+  SSEEdgeClientTransport as vn,
+  WorkflowCallbackType as vt,
   RPCRequest as w,
-  buildAgentUrl as wn,
-  WorkflowRejectedError as wt,
+  SUB_PREFIX as wn,
+  WorkflowPage as wt,
   MCPServer as x,
-  SUB_PREFIX as xn,
-  WorkflowPage as xt,
+  DynamicAgentStub as xn,
+  WorkflowEventCallback as xt,
   FiberStatus as y,
-  AgentPathStep as yn,
-  WorkflowEventPayload as yt,
-  AgentToolFailure as z,
-  MCPOAuthCallbackResult as zt
+  StreamableHTTPEdgeClientTransport as yn,
+  WorkflowCompleteCallback as yt,
+  AgentToolEventState as z,
+  MCPClientOAuthResult as zt
 };
-//# sourceMappingURL=agent-routing-B2XLNMxq.d.ts.map
+//# sourceMappingURL=agent-routing-0DR0Tk2v.d.ts.map

package/dist/agent-routing.d.ts

@@ -4,7 +4,7 @@ import {
   n as AgentOptions,
   r as RoutingRetryOptions,
   t as AgentGetOptions
-} from "./agent-routing-B2XLNMxq.js";
+} from "./agent-routing-0DR0Tk2v.js";
 export {
   AgentGetOptions,
   AgentOptions,

package/dist/agent-routing.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-routing.js","names":[],"sources":["../src/agent-routing.ts"],"sourcesContent":["import type { Agent } from \"./index\";\nimport { camelCaseToKebabCase } from \"./utils\";\n\nconst namespaceMapCache = new WeakMap<\n  object,\n  Record<string, DurableObjectNamespace>\n>();\nconst bindingNameCache = new WeakMap<object, Record<string, string>>();\n\nconst DEFAULT_ROUTING_RETRY_OPTIONS = {\n  maxAttempts: 3,\n  baseDelayMs: 100,\n  maxDelayMs: 800\n};\n\ninterface RoutingRetryEvent {\n  error: unknown;\n  attempt: number;\n  maxAttempts: number;\n  delayMs: number;\n  name: string;\n  className?: string;\n}\n\n/** Retry policy for Agent routing infrastructure failures. */\nexport interface RoutingRetryOptions {\n  /** Max number of attempts, including the first. Default: 3. */\n  maxAttempts?: number;\n  /** Base delay in milliseconds for exponential backoff. Default: 100. */\n  baseDelayMs?: number;\n  /** Maximum delay in milliseconds. Default: 800. */\n  maxDelayMs?: number;\n  /** Optional callback invoked before each retry delay. */\n  onRetry?: (event: RoutingRetryEvent) => void | Promise<void>;\n}\n\ninterface AgentRouteMatch<Env = Cloudflare.Env> {\n  /** The Durable Object environment binding name. */\n  className: Extract<keyof Env, string>;\n  /** The named Durable Object instance extracted from the URL. */\n  name: string;\n}\n\ninterface AgentRouteOptions<\n  Env = Cloudflare.Env,\n  Props extends Record<string, unknown> = Record<string, unknown>\n> {\n  /** URL prefix before the binding and instance name. Default: `agents`. */\n  prefix?: string;\n  jurisdiction?: DurableObjectJurisdiction;\n  locationHint?: DurableObjectLocationHint;\n  /** Properties supplied before lifecycle startup. */\n  props?: Props;\n  /**\n   * Whether to enable CORS for matched routes.\n   *\n   * When `true`, uses default permissive CORS headers:\n   * - Access-Control-Allow-Origin: *\n   * - Access-Control-Allow-Methods: GET, POST, HEAD, OPTIONS\n   * - Access-Control-Allow-Headers: *\n   * - Access-Control-Max-Age: 86400\n   *\n   * For credentialed requests, pass explicit headers with a specific origin.\n   * When set to a `HeadersInit` value, uses those as the CORS headers instead.\n   * CORS preflight requests are handled automatically for matched routes.\n   */\n  cors?: boolean | HeadersInit;\n  /**\n   * Retry transient Durable Object infrastructure errors thrown while routing.\n   * Enabled by default; pass `false` to disable.\n   */\n  routingRetry?: false | RoutingRetryOptions;\n  onBeforeConnect?: (\n    request: Request,\n    route: AgentRouteMatch<Env>\n  ) => Response | Request | void | Promise<Response | Request | void>;\n  onBeforeRequest?: (\n    request: Request,\n    route: AgentRouteMatch<Env>\n  ) =>\n    | Response\n    | Request\n    | void\n    | Promise<Response | Request | undefined | void>;\n}\n\n/** Configuration options for {@link routeAgentRequest}. */\nexport type AgentOptions<Env> = AgentRouteOptions<Env>;\n\n/** Options for resolving and starting a named Agent. */\nexport type AgentGetOptions<\n  Env,\n  Props extends Record<string, unknown> = Record<string, unknown>\n> = Pick<\n  AgentRouteOptions<Env, Props>,\n  \"jurisdiction\" | \"locationHint\" | \"props\" | \"routingRetry\"\n>;\n\ninterface ResolvedRoutingRetryOptions extends Required<\n  Omit<RoutingRetryOptions, \"onRetry\">\n> {\n  onRetry?: RoutingRetryOptions[\"onRetry\"];\n}\n\ninterface RoutingRetryContext {\n  name: string;\n  className?: string;\n}\n\nfunction durableObjectGetOptions(\n  options: { locationHint?: DurableObjectLocationHint } | undefined\n) {\n  return options?.locationHint\n    ? { locationHint: options.locationHint }\n    : undefined;\n}\n\nfunction validatePositiveInteger(value: number, name: string): void {\n  if (!Number.isFinite(value) || value < 1) {\n    throw new Error(`${name} must be >= 1`);\n  }\n  if (!Number.isInteger(value)) {\n    throw new Error(`${name} must be an integer`);\n  }\n}\n\nfunction validatePositiveNumber(value: number, name: string): void {\n  if (!Number.isFinite(value) || value <= 0) {\n    throw new Error(`${name} must be > 0`);\n  }\n}\n\nfunction resolveRoutingRetryOptions(\n  options: false | RoutingRetryOptions | undefined\n): ResolvedRoutingRetryOptions | null {\n  if (options === false) return null;\n\n  const resolved = {\n    maxAttempts:\n      options?.maxAttempts ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxAttempts,\n    baseDelayMs:\n      options?.baseDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.baseDelayMs,\n    maxDelayMs: options?.maxDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxDelayMs,\n    onRetry: options?.onRetry\n  };\n\n  validatePositiveInteger(resolved.maxAttempts, \"routingRetry.maxAttempts\");\n  validatePositiveNumber(resolved.baseDelayMs, \"routingRetry.baseDelayMs\");\n  validatePositiveNumber(resolved.maxDelayMs, \"routingRetry.maxDelayMs\");\n  if (resolved.baseDelayMs > resolved.maxDelayMs) {\n    throw new Error(\"routingRetry.baseDelayMs must be <= maxDelayMs\");\n  }\n\n  return resolved;\n}\n\nfunction isRetryableDurableObjectError(error: unknown): boolean {\n  if (typeof error !== \"object\" || error === null) return false;\n  // SAFETY: Cloudflare's retryable and overloaded error flags are optional\n  // runtime properties not represented on the base Error type.\n  const typed = error as { retryable?: boolean; overloaded?: boolean };\n  return typed.retryable === true && typed.overloaded !== true;\n}\n\nfunction routingRetryDelayMs(\n  attempt: number,\n  options: ResolvedRoutingRetryOptions\n): number {\n  const upperBoundMs = Math.min(\n    options.maxDelayMs,\n    options.baseDelayMs * 2 ** (attempt - 1)\n  );\n  return Math.floor(Math.random() * upperBoundMs);\n}\n\nasync function retryDurableObjectOperation<T>(\n  operation: () => Promise<T>,\n  context: RoutingRetryContext,\n  retryOptions: false | RoutingRetryOptions | undefined\n): Promise<T> {\n  const resolved = resolveRoutingRetryOptions(retryOptions);\n  if (!resolved) return await operation();\n\n  let attempt = 1;\n  while (true) {\n    try {\n      return await operation();\n    } catch (error) {\n      const nextAttempt = attempt + 1;\n      if (\n        nextAttempt > resolved.maxAttempts ||\n        !isRetryableDurableObjectError(error)\n      ) {\n        throw error;\n      }\n\n      const delayMs = routingRetryDelayMs(attempt, resolved);\n      try {\n        await resolved.onRetry?.({\n          error,\n          attempt,\n          maxAttempts: resolved.maxAttempts,\n          delayMs,\n          name: context.name,\n          className: context.className\n        });\n      } catch (callbackError) {\n        console.warn(\n          \"Durable Object routing retry callback failed:\",\n          callbackError\n        );\n      }\n      await new Promise((resolve) => setTimeout(resolve, delayMs));\n      attempt = nextAttempt;\n    }\n  }\n}\n\nfunction encodeLifecycleProps(props: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(props));\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n\nfunction mutableRequest(request: Request): Request {\n  return new Request(request);\n}\n\nfunction cloneRequestForFetch(request: Request): Request {\n  // SAFETY: Workers Types v5 preserves an unconstrained `cf` generic from\n  // clone(). Cloning does not change the runtime Request representation.\n  return request.clone() as Request;\n}\n\nfunction resolveCorsHeaders(\n  cors: boolean | HeadersInit | undefined\n): Record<string, string> | null {\n  if (cors === true) {\n    return {\n      \"Access-Control-Allow-Origin\": \"*\",\n      \"Access-Control-Allow-Methods\": \"GET, POST, HEAD, OPTIONS\",\n      \"Access-Control-Allow-Headers\": \"*\",\n      \"Access-Control-Max-Age\": \"86400\"\n    };\n  }\n  if (cors && typeof cors === \"object\") {\n    const headers = new Headers(cors);\n    const record: Record<string, string> = {};\n    headers.forEach((value, key) => {\n      record[key] = value;\n    });\n    return record;\n  }\n  return null;\n}\n\n/**\n * Route `/agents/:binding/:name` HTTP and WebSocket requests to a named\n * Durable Object. The target may extend `Agent` or compose `Lifecycle`\n * directly into a plain `DurableObject`.\n *\n * @param request - Incoming Worker request.\n * @param env - Worker environment containing Durable Object bindings.\n * @param options - Routing options.\n * @returns The matched response, or `null` when the path does not match.\n */\nexport async function routeAgentRequest<Env>(\n  request: Request,\n  env: Env,\n  options?: AgentOptions<Env>\n): Promise<Response | null> {\n  // SAFETY: Worker environments are object records. The unconstrained Env\n  // generic is retained for compatibility with the previously published API.\n  const environment = env as object;\n  if (!namespaceMapCache.has(environment)) {\n    const namespaceMap: Record<string, DurableObjectNamespace> = {};\n    const bindingNames: Record<string, string> = {};\n    for (const [key, value] of Object.entries(environment)) {\n      if (\n        value &&\n        typeof value === \"object\" &&\n        \"idFromName\" in value &&\n        typeof value.idFromName === \"function\"\n      ) {\n        const kebab = camelCaseToKebabCase(key);\n        // SAFETY: The structural idFromName check above identifies a Durable\n        // Object namespace at the Worker environment boundary.\n        namespaceMap[kebab] = value as DurableObjectNamespace;\n        bindingNames[kebab] = key;\n      }\n    }\n    namespaceMapCache.set(environment, namespaceMap);\n    bindingNameCache.set(environment, bindingNames);\n  }\n\n  const map = namespaceMapCache.get(environment) as Record<\n    string,\n    DurableObjectNamespace\n  >;\n  const bindingNames = bindingNameCache.get(environment) as Record<\n    string,\n    string\n  >;\n  const prefixParts = (options?.prefix || \"agents\").split(\"/\");\n  const parts = new URL(request.url).pathname.split(\"/\").filter(Boolean);\n  const prefixMatches = prefixParts.every(\n    (part, index) => parts[index] === part\n  );\n  if (!prefixMatches || parts.length < prefixParts.length + 2) return null;\n\n  const namespaceName = parts[prefixParts.length];\n  const name = parts[prefixParts.length + 1];\n  if (!name || !namespaceName) return null;\n\n  const boundNamespace = map[namespaceName];\n  if (!boundNamespace) {\n    console.error(\n      `The URL ${request.url} with namespace \"${namespaceName}\" and name \"${name}\" does not match any Durable Object binding.`\n    );\n    return new Response(\"Invalid request\", { status: 400 });\n  }\n\n  const corsHeaders = resolveCorsHeaders(options?.cors);\n  const isWebSocket =\n    request.headers.get(\"Upgrade\")?.toLowerCase() === \"websocket\";\n  const withCorsHeaders = (response: Response): Response => {\n    if (!corsHeaders || isWebSocket) return response;\n    const nextResponse = new Response(response.body, response);\n    for (const [key, value] of Object.entries(corsHeaders)) {\n      nextResponse.headers.set(key, value);\n    }\n    return nextResponse;\n  };\n\n  if (request.method === \"OPTIONS\" && corsHeaders) {\n    return new Response(null, { headers: corsHeaders });\n  }\n\n  const namespace = options?.jurisdiction\n    ? boundNamespace.jurisdiction(options.jurisdiction)\n    : boundNamespace;\n  const id = namespace.idFromName(name);\n  const getOptions = durableObjectGetOptions(options);\n  request = mutableRequest(request);\n\n  // SAFETY: binding names come directly from Object.entries(env), so they are\n  // string keys of Env.\n  const className = bindingNames[namespaceName] as Extract<keyof Env, string>;\n  const route: AgentRouteMatch<Env> = { className, name };\n\n  if (isWebSocket) {\n    const requestOrResponse = await options?.onBeforeConnect?.(request, route);\n    if (requestOrResponse instanceof Request) {\n      request = mutableRequest(requestOrResponse);\n    } else if (requestOrResponse instanceof Response) {\n      return requestOrResponse;\n    }\n  } else {\n    const requestOrResponse = await options?.onBeforeRequest?.(request, route);\n    if (requestOrResponse instanceof Request) {\n      request = mutableRequest(requestOrResponse);\n    } else if (requestOrResponse instanceof Response) {\n      return withCorsHeaders(requestOrResponse);\n    }\n  }\n\n  if (options?.props !== undefined) {\n    request.headers.set(\n      \"x-agents-lifecycle-props\",\n      encodeLifecycleProps(options.props)\n    );\n  }\n\n  const response = await retryDurableObjectOperation(\n    () => namespace.get(id, getOptions).fetch(cloneRequestForFetch(request)),\n    { name, className },\n    options?.routingRetry\n  );\n  return isWebSocket ? response : withCorsHeaders(response);\n}\n\n/**\n * Get a named Agent stub after its lifecycle startup has completed.\n *\n * @param namespace - Agent Durable Object namespace.\n * @param name - Agent instance name.\n * @param options - Placement, startup properties, and retry options.\n * @returns The initialized Agent stub.\n */\nexport async function getAgentByName<\n  Env extends Cloudflare.Env = Cloudflare.Env,\n  T extends Agent<Env> = Agent<Env>,\n  Props extends Record<string, unknown> = Record<string, unknown>\n>(\n  namespace: DurableObjectNamespace<T>,\n  name: string,\n  options?: AgentGetOptions<Env, Props>\n): Promise<DurableObjectStub<T>> {\n  const target = options?.jurisdiction\n    ? namespace.jurisdiction(options.jurisdiction)\n    : namespace;\n  const id = target.idFromName(name);\n  const stub = target.get(id, durableObjectGetOptions(options));\n\n  // SAFETY: Agent exposes this internal initializer specifically for native\n  // RPC calls, which bypass the lifecycle-installed fetch handler.\n  const lifecycleStub = stub as unknown as {\n    __unsafe_ensureInitialized(props?: Props): Promise<void>;\n  };\n  await retryDurableObjectOperation(\n    () => lifecycleStub.__unsafe_ensureInitialized(options?.props),\n    { name },\n    options?.routingRetry\n  );\n\n  return stub;\n}\n"],"mappings":"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"}
+{"version":3,"file":"agent-routing.js","names":[],"sources":["../src/agent-routing.ts"],"sourcesContent":["import type { Agent } from \"./index\";\nimport { camelCaseToKebabCase } from \"./utils\";\n\nconst namespaceMapCache = new WeakMap<\n  object,\n  Record<string, DurableObjectNamespace>\n>();\nconst bindingNameCache = new WeakMap<object, Record<string, string>>();\n\nconst DEFAULT_ROUTING_RETRY_OPTIONS = {\n  maxAttempts: 3,\n  baseDelayMs: 100,\n  maxDelayMs: 800\n};\n\ninterface RoutingRetryEvent {\n  error: unknown;\n  attempt: number;\n  maxAttempts: number;\n  delayMs: number;\n  name: string;\n  className?: string;\n}\n\n/** Retry policy for Agent routing infrastructure failures. */\nexport interface RoutingRetryOptions {\n  /** Max number of attempts, including the first. Default: 3. */\n  maxAttempts?: number;\n  /** Base delay in milliseconds for exponential backoff. Default: 100. */\n  baseDelayMs?: number;\n  /** Maximum delay in milliseconds. Default: 800. */\n  maxDelayMs?: number;\n  /** Optional callback invoked before each retry delay. */\n  onRetry?: (event: RoutingRetryEvent) => void | Promise<void>;\n}\n\ninterface AgentRouteMatch<Env = Cloudflare.Env> {\n  /** The Durable Object environment binding name. */\n  className: Extract<keyof Env, string>;\n  /** The named Durable Object instance extracted from the URL. */\n  name: string;\n}\n\ninterface AgentRouteOptions<\n  Env = Cloudflare.Env,\n  Props extends object = object\n> {\n  /** URL prefix before the binding and instance name. Default: `agents`. */\n  prefix?: string;\n  jurisdiction?: DurableObjectJurisdiction;\n  locationHint?: DurableObjectLocationHint;\n  /** Properties supplied before lifecycle startup. */\n  props?: Props;\n  /**\n   * Whether to enable CORS for matched routes.\n   *\n   * When `true`, uses default permissive CORS headers:\n   * - Access-Control-Allow-Origin: *\n   * - Access-Control-Allow-Methods: GET, POST, HEAD, OPTIONS\n   * - Access-Control-Allow-Headers: *\n   * - Access-Control-Max-Age: 86400\n   *\n   * For credentialed requests, pass explicit headers with a specific origin.\n   * When set to a `HeadersInit` value, uses those as the CORS headers instead.\n   * CORS preflight requests are handled automatically for matched routes.\n   */\n  cors?: boolean | HeadersInit;\n  /**\n   * Retry transient Durable Object infrastructure errors thrown while routing.\n   * Enabled by default; pass `false` to disable.\n   */\n  routingRetry?: false | RoutingRetryOptions;\n  onBeforeConnect?: (\n    request: Request,\n    route: AgentRouteMatch<Env>\n  ) => Response | Request | void | Promise<Response | Request | void>;\n  onBeforeRequest?: (\n    request: Request,\n    route: AgentRouteMatch<Env>\n  ) =>\n    | Response\n    | Request\n    | void\n    | Promise<Response | Request | undefined | void>;\n}\n\n/** Configuration options for {@link routeAgentRequest}. */\nexport type AgentOptions<Env> = AgentRouteOptions<Env>;\n\n/** Options for resolving and starting a named Agent. */\nexport type AgentGetOptions<Env, Props extends object = object> = Pick<\n  AgentRouteOptions<Env, Props>,\n  \"jurisdiction\" | \"locationHint\" | \"props\" | \"routingRetry\"\n>;\n\ninterface ResolvedRoutingRetryOptions extends Required<\n  Omit<RoutingRetryOptions, \"onRetry\">\n> {\n  onRetry?: RoutingRetryOptions[\"onRetry\"];\n}\n\ninterface RoutingRetryContext {\n  name: string;\n  className?: string;\n}\n\nfunction durableObjectGetOptions(\n  options: { locationHint?: DurableObjectLocationHint } | undefined\n) {\n  return options?.locationHint\n    ? { locationHint: options.locationHint }\n    : undefined;\n}\n\nfunction validatePositiveInteger(value: number, name: string): void {\n  if (!Number.isFinite(value) || value < 1) {\n    throw new Error(`${name} must be >= 1`);\n  }\n  if (!Number.isInteger(value)) {\n    throw new Error(`${name} must be an integer`);\n  }\n}\n\nfunction validatePositiveNumber(value: number, name: string): void {\n  if (!Number.isFinite(value) || value <= 0) {\n    throw new Error(`${name} must be > 0`);\n  }\n}\n\nfunction resolveRoutingRetryOptions(\n  options: false | RoutingRetryOptions | undefined\n): ResolvedRoutingRetryOptions | null {\n  if (options === false) return null;\n\n  const resolved = {\n    maxAttempts:\n      options?.maxAttempts ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxAttempts,\n    baseDelayMs:\n      options?.baseDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.baseDelayMs,\n    maxDelayMs: options?.maxDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxDelayMs,\n    onRetry: options?.onRetry\n  };\n\n  validatePositiveInteger(resolved.maxAttempts, \"routingRetry.maxAttempts\");\n  validatePositiveNumber(resolved.baseDelayMs, \"routingRetry.baseDelayMs\");\n  validatePositiveNumber(resolved.maxDelayMs, \"routingRetry.maxDelayMs\");\n  if (resolved.baseDelayMs > resolved.maxDelayMs) {\n    throw new Error(\"routingRetry.baseDelayMs must be <= maxDelayMs\");\n  }\n\n  return resolved;\n}\n\nfunction isRetryableDurableObjectError(error: unknown): boolean {\n  if (typeof error !== \"object\" || error === null) return false;\n  // SAFETY: Cloudflare's retryable and overloaded error flags are optional\n  // runtime properties not represented on the base Error type.\n  const typed = error as { retryable?: boolean; overloaded?: boolean };\n  return typed.retryable === true && typed.overloaded !== true;\n}\n\nfunction routingRetryDelayMs(\n  attempt: number,\n  options: ResolvedRoutingRetryOptions\n): number {\n  const upperBoundMs = Math.min(\n    options.maxDelayMs,\n    options.baseDelayMs * 2 ** (attempt - 1)\n  );\n  return Math.floor(Math.random() * upperBoundMs);\n}\n\nasync function retryDurableObjectOperation<T>(\n  operation: () => Promise<T>,\n  context: RoutingRetryContext,\n  retryOptions: false | RoutingRetryOptions | undefined\n): Promise<T> {\n  const resolved = resolveRoutingRetryOptions(retryOptions);\n  if (!resolved) return await operation();\n\n  let attempt = 1;\n  while (true) {\n    try {\n      return await operation();\n    } catch (error) {\n      const nextAttempt = attempt + 1;\n      if (\n        nextAttempt > resolved.maxAttempts ||\n        !isRetryableDurableObjectError(error)\n      ) {\n        throw error;\n      }\n\n      const delayMs = routingRetryDelayMs(attempt, resolved);\n      try {\n        await resolved.onRetry?.({\n          error,\n          attempt,\n          maxAttempts: resolved.maxAttempts,\n          delayMs,\n          name: context.name,\n          className: context.className\n        });\n      } catch (callbackError) {\n        console.warn(\n          \"Durable Object routing retry callback failed:\",\n          callbackError\n        );\n      }\n      await new Promise((resolve) => setTimeout(resolve, delayMs));\n      attempt = nextAttempt;\n    }\n  }\n}\n\nfunction encodeLifecycleProps(props: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(props));\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n\nfunction mutableRequest(request: Request): Request {\n  return new Request(request);\n}\n\nfunction cloneRequestForFetch(request: Request): Request {\n  // SAFETY: Workers Types v5 preserves an unconstrained `cf` generic from\n  // clone(). Cloning does not change the runtime Request representation.\n  return request.clone() as Request;\n}\n\nfunction resolveCorsHeaders(\n  cors: boolean | HeadersInit | undefined\n): Record<string, string> | null {\n  if (cors === true) {\n    return {\n      \"Access-Control-Allow-Origin\": \"*\",\n      \"Access-Control-Allow-Methods\": \"GET, POST, HEAD, OPTIONS\",\n      \"Access-Control-Allow-Headers\": \"*\",\n      \"Access-Control-Max-Age\": \"86400\"\n    };\n  }\n  if (cors && typeof cors === \"object\") {\n    const headers = new Headers(cors);\n    const record: Record<string, string> = {};\n    headers.forEach((value, key) => {\n      record[key] = value;\n    });\n    return record;\n  }\n  return null;\n}\n\n/**\n * Route `/agents/:binding/:name` HTTP and WebSocket requests to a named\n * Durable Object. The target may extend `Agent` or compose `Lifecycle`\n * directly into a plain `DurableObject`.\n *\n * @param request - Incoming Worker request.\n * @param env - Worker environment containing Durable Object bindings.\n * @param options - Routing options.\n * @returns The matched response, or `null` when the path does not match.\n */\nexport async function routeAgentRequest<Env>(\n  request: Request,\n  env: Env,\n  options?: AgentOptions<Env>\n): Promise<Response | null> {\n  // SAFETY: Worker environments are object records. The unconstrained Env\n  // generic is retained for compatibility with the previously published API.\n  const environment = env as object;\n  if (!namespaceMapCache.has(environment)) {\n    const namespaceMap: Record<string, DurableObjectNamespace> = {};\n    const bindingNames: Record<string, string> = {};\n    for (const [key, value] of Object.entries(environment)) {\n      if (\n        value &&\n        typeof value === \"object\" &&\n        \"idFromName\" in value &&\n        typeof value.idFromName === \"function\"\n      ) {\n        const kebab = camelCaseToKebabCase(key);\n        // SAFETY: The structural idFromName check above identifies a Durable\n        // Object namespace at the Worker environment boundary.\n        namespaceMap[kebab] = value as DurableObjectNamespace;\n        bindingNames[kebab] = key;\n      }\n    }\n    namespaceMapCache.set(environment, namespaceMap);\n    bindingNameCache.set(environment, bindingNames);\n  }\n\n  const map = namespaceMapCache.get(environment) as Record<\n    string,\n    DurableObjectNamespace\n  >;\n  const bindingNames = bindingNameCache.get(environment) as Record<\n    string,\n    string\n  >;\n  const prefixParts = (options?.prefix || \"agents\").split(\"/\");\n  const parts = new URL(request.url).pathname.split(\"/\").filter(Boolean);\n  const prefixMatches = prefixParts.every(\n    (part, index) => parts[index] === part\n  );\n  if (!prefixMatches || parts.length < prefixParts.length + 2) return null;\n\n  const namespaceName = parts[prefixParts.length];\n  const name = parts[prefixParts.length + 1];\n  if (!name || !namespaceName) return null;\n\n  const boundNamespace = map[namespaceName];\n  if (!boundNamespace) {\n    console.error(\n      `The URL ${request.url} with namespace \"${namespaceName}\" and name \"${name}\" does not match any Durable Object binding.`\n    );\n    return new Response(\"Invalid request\", { status: 400 });\n  }\n\n  const corsHeaders = resolveCorsHeaders(options?.cors);\n  const isWebSocket =\n    request.headers.get(\"Upgrade\")?.toLowerCase() === \"websocket\";\n  const withCorsHeaders = (response: Response): Response => {\n    if (!corsHeaders || isWebSocket) return response;\n    const nextResponse = new Response(response.body, response);\n    for (const [key, value] of Object.entries(corsHeaders)) {\n      nextResponse.headers.set(key, value);\n    }\n    return nextResponse;\n  };\n\n  if (request.method === \"OPTIONS\" && corsHeaders) {\n    return new Response(null, { headers: corsHeaders });\n  }\n\n  const namespace = options?.jurisdiction\n    ? boundNamespace.jurisdiction(options.jurisdiction)\n    : boundNamespace;\n  const id = namespace.idFromName(name);\n  const getOptions = durableObjectGetOptions(options);\n  request = mutableRequest(request);\n\n  // SAFETY: binding names come directly from Object.entries(env), so they are\n  // string keys of Env.\n  const className = bindingNames[namespaceName] as Extract<keyof Env, string>;\n  const route: AgentRouteMatch<Env> = { className, name };\n\n  if (isWebSocket) {\n    const requestOrResponse = await options?.onBeforeConnect?.(request, route);\n    if (requestOrResponse instanceof Request) {\n      request = mutableRequest(requestOrResponse);\n    } else if (requestOrResponse instanceof Response) {\n      return requestOrResponse;\n    }\n  } else {\n    const requestOrResponse = await options?.onBeforeRequest?.(request, route);\n    if (requestOrResponse instanceof Request) {\n      request = mutableRequest(requestOrResponse);\n    } else if (requestOrResponse instanceof Response) {\n      return withCorsHeaders(requestOrResponse);\n    }\n  }\n\n  if (options?.props !== undefined) {\n    request.headers.set(\n      \"x-agents-lifecycle-props\",\n      encodeLifecycleProps(options.props)\n    );\n  }\n\n  const response = await retryDurableObjectOperation(\n    () => namespace.get(id, getOptions).fetch(cloneRequestForFetch(request)),\n    { name, className },\n    options?.routingRetry\n  );\n  return isWebSocket ? response : withCorsHeaders(response);\n}\n\n/**\n * Get a named Agent stub after its lifecycle startup has completed.\n *\n * @param namespace - Agent Durable Object namespace.\n * @param name - Agent instance name.\n * @param options - Placement, startup properties, and retry options.\n * @returns The initialized Agent stub.\n */\nexport async function getAgentByName<\n  Env extends Cloudflare.Env = Cloudflare.Env,\n  T extends Agent<Env> = Agent<Env>,\n  Props extends object = object\n>(\n  namespace: DurableObjectNamespace<T>,\n  name: string,\n  options?: AgentGetOptions<Env, Props>\n): Promise<DurableObjectStub<T>> {\n  const target = options?.jurisdiction\n    ? namespace.jurisdiction(options.jurisdiction)\n    : namespace;\n  const id = target.idFromName(name);\n  const stub = target.get(id, durableObjectGetOptions(options));\n\n  // SAFETY: Agent exposes this internal initializer specifically for native\n  // RPC calls, which bypass the lifecycle-installed fetch handler.\n  const lifecycleStub = stub as unknown as {\n    __unsafe_ensureInitialized(props?: Props): Promise<void>;\n  };\n  await retryDurableObjectOperation(\n    () => lifecycleStub.__unsafe_ensureInitialized(options?.props),\n    { name },\n    options?.routingRetry\n  );\n\n  return stub;\n}\n"],"mappings":"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"}