agents 0.21.0 → 0.23.0

package/dist/observability/index.d.ts

@@ -1,11 +1,11 @@
 import {
-  a as genericObservability,
-  i as channels,
+  a as subscribe,
+  i as genericObservability,
   n as Observability,
-  o as subscribe,
+  o as channels,
   r as ObservabilityEvent,
   t as ChannelEventMap
-} from "../index-BRnybD6X.js";
+} from "../index-YSKgfgg9.js";
 export {
   ChannelEventMap,
   Observability,

package/dist/observability/index.js

@@ -1,67 +1,20 @@
-import { channel, subscribe as subscribe$1, unsubscribe } from "node:diagnostics_channel";
+import { n as publishDiagnosticsEvent, t as channels } from "../diagnostics-BzvaX2UT.js";
+import { subscribe as subscribe$1, unsubscribe } from "node:diagnostics_channel";
 //#region src/observability/index.ts
 /**
-* Diagnostics channels for agent observability.
-*
-* Events are published to named channels using the Node.js diagnostics_channel API.
-* By default, publishing to a channel with no subscribers is a no-op (zero overhead).
-*
-* To observe events, subscribe to the channels you care about:
-* ```ts
-* import { subscribe } from "node:diagnostics_channel";
-* subscribe("agents:rpc", (event) => console.log(event));
-* ```
-*
-* In production, all published messages are automatically forwarded to
-* Tail Workers via `event.diagnosticsChannelEvents` — no subscription needed.
-*/
-const channels = {
-	state: channel("agents:state"),
-	rpc: channel("agents:rpc"),
-	message: channel("agents:message"),
-	chat: channel("agents:chat"),
-	transcript: channel("agents:transcript"),
-	fiber: channel("agents:fiber"),
-	agentTool: channel("agents:agent_tool"),
-	schedule: channel("agents:schedule"),
-	lifecycle: channel("agents:lifecycle"),
-	workflow: channel("agents:workflow"),
-	mcp: channel("agents:mcp"),
-	email: channel("agents:email"),
-	channel: channel("agents:channel")
-};
-/**
 * Channel keys whose diagnostics channel name differs from `agents:${key}`.
 * Keep this in sync with {@link channels} for any camelCase key that maps to a
 * snake_case diagnostics channel.
 */
 const CHANNEL_DIAGNOSTIC_NAME_OVERRIDES = { agentTool: "agents:agent_tool" };
 /**
-* Map event type prefixes to their diagnostics channel.
-*/
-function getChannel(type) {
-	if (type.startsWith("mcp:")) return channels.mcp;
-	if (type.startsWith("workflow:")) return channels.workflow;
-	if (type.startsWith("fiber:")) return channels.fiber;
-	if (type.startsWith("transcript:") || type.startsWith("chat:transcript:")) return channels.transcript;
-	if (type.startsWith("chat:")) return channels.chat;
-	if (type.startsWith("agent_tool:")) return channels.agentTool;
-	if (type.startsWith("schedule:") || type.startsWith("queue:")) return channels.schedule;
-	if (type.startsWith("message:") || type.startsWith("tool:") || type.startsWith("submission:") || type.startsWith("action:")) return channels.message;
-	if (type === "rpc" || type.startsWith("rpc:")) return channels.rpc;
-	if (type.startsWith("state:")) return channels.state;
-	if (type.startsWith("email:")) return channels.email;
-	if (type.startsWith("channel:") || type.startsWith("notice:")) return channels.channel;
-	return channels.lifecycle;
-}
-/**
 * The default observability implementation.
 *
 * Publishes events to diagnostics_channel. Events are silent unless
 * a subscriber is registered or a Tail Worker is attached.
 */
 const genericObservability = { emit(event) {
-	getChannel(event.type).publish(event);
+	publishDiagnosticsEvent(event);
 } };
 /**
 * Subscribe to a typed observability channel.

package/dist/observability/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["dcUnsubscribe"],"sources":["../../src/observability/index.ts"],"sourcesContent":["import {\n  channel,\n  subscribe as dcSubscribe,\n  unsubscribe as dcUnsubscribe,\n  type Channel\n} from \"node:diagnostics_channel\";\nimport type { AgentObservabilityEvent } from \"./agent\";\nimport type { MCPObservabilityEvent } from \"./mcp\";\n\n/**\n * Union of all observability event types from different domains\n */\nexport type ObservabilityEvent =\n  | AgentObservabilityEvent\n  | MCPObservabilityEvent;\n\nexport interface Observability {\n  /**\n   * Emit an event for the Agent's observability implementation to handle.\n   * @param event - The event to emit\n   */\n  emit(event: ObservabilityEvent): void;\n}\n\n/**\n * Diagnostics channels for agent observability.\n *\n * Events are published to named channels using the Node.js diagnostics_channel API.\n * By default, publishing to a channel with no subscribers is a no-op (zero overhead).\n *\n * To observe events, subscribe to the channels you care about:\n * ```ts\n * import { subscribe } from \"node:diagnostics_channel\";\n * subscribe(\"agents:rpc\", (event) => console.log(event));\n * ```\n *\n * In production, all published messages are automatically forwarded to\n * Tail Workers via `event.diagnosticsChannelEvents` — no subscription needed.\n */\nexport const channels = {\n  state: channel(\"agents:state\"),\n  rpc: channel(\"agents:rpc\"),\n  message: channel(\"agents:message\"),\n  chat: channel(\"agents:chat\"),\n  transcript: channel(\"agents:transcript\"),\n  fiber: channel(\"agents:fiber\"),\n  agentTool: channel(\"agents:agent_tool\"),\n  schedule: channel(\"agents:schedule\"),\n  lifecycle: channel(\"agents:lifecycle\"),\n  workflow: channel(\"agents:workflow\"),\n  mcp: channel(\"agents:mcp\"),\n  email: channel(\"agents:email\"),\n  channel: channel(\"agents:channel\")\n} as const;\n\n/**\n * Channel keys whose diagnostics channel name differs from `agents:${key}`.\n * Keep this in sync with {@link channels} for any camelCase key that maps to a\n * snake_case diagnostics channel.\n */\nconst CHANNEL_DIAGNOSTIC_NAME_OVERRIDES: Partial<Record<string, string>> = {\n  agentTool: \"agents:agent_tool\"\n};\n\n/**\n * Map event type prefixes to their diagnostics channel.\n */\nfunction getChannel(type: string): Channel {\n  if (type.startsWith(\"mcp:\")) return channels.mcp;\n  if (type.startsWith(\"workflow:\")) return channels.workflow;\n  if (type.startsWith(\"fiber:\")) return channels.fiber;\n  if (type.startsWith(\"transcript:\") || type.startsWith(\"chat:transcript:\"))\n    return channels.transcript;\n  if (type.startsWith(\"chat:\")) return channels.chat;\n  if (type.startsWith(\"agent_tool:\")) return channels.agentTool;\n  if (type.startsWith(\"schedule:\") || type.startsWith(\"queue:\"))\n    return channels.schedule;\n  if (\n    type.startsWith(\"message:\") ||\n    type.startsWith(\"tool:\") ||\n    type.startsWith(\"submission:\") ||\n    type.startsWith(\"action:\")\n  )\n    return channels.message;\n  if (type === \"rpc\" || type.startsWith(\"rpc:\")) return channels.rpc;\n  if (type.startsWith(\"state:\")) return channels.state;\n  if (type.startsWith(\"email:\")) return channels.email;\n  if (type.startsWith(\"channel:\") || type.startsWith(\"notice:\"))\n    return channels.channel;\n  // connect, disconnect, destroy\n  return channels.lifecycle;\n}\n\n/**\n * The default observability implementation.\n *\n * Publishes events to diagnostics_channel. Events are silent unless\n * a subscriber is registered or a Tail Worker is attached.\n */\nexport const genericObservability: Observability = {\n  emit(event) {\n    getChannel(event.type).publish(event);\n  }\n};\n\n/**\n * Maps each channel key to the observability events it carries.\n */\nexport type ChannelEventMap = {\n  state: Extract<ObservabilityEvent, { type: `state:${string}` }>;\n  rpc: Extract<ObservabilityEvent, { type: \"rpc\" | `rpc:${string}` }>;\n  message: Extract<\n    ObservabilityEvent,\n    {\n      type:\n        | `message:${string}`\n        | `tool:${string}`\n        | `submission:${string}`\n        | `action:${string}`;\n    }\n  >;\n  chat: Exclude<\n    Extract<ObservabilityEvent, { type: `chat:${string}` }>,\n    { type: `chat:transcript:${string}` }\n  >;\n  transcript: Extract<\n    ObservabilityEvent,\n    { type: `transcript:${string}` | `chat:transcript:${string}` }\n  >;\n  fiber: Extract<ObservabilityEvent, { type: `fiber:${string}` }>;\n  agentTool: Extract<ObservabilityEvent, { type: `agent_tool:${string}` }>;\n  schedule: Extract<\n    ObservabilityEvent,\n    { type: `schedule:${string}` | `queue:${string}` }\n  >;\n  lifecycle: Extract<\n    ObservabilityEvent,\n    { type: \"connect\" | \"disconnect\" | \"destroy\" }\n  >;\n  workflow: Extract<ObservabilityEvent, { type: `workflow:${string}` }>;\n  mcp: Extract<ObservabilityEvent, { type: `mcp:${string}` }>;\n  email: Extract<ObservabilityEvent, { type: `email:${string}` }>;\n  channel: Extract<\n    ObservabilityEvent,\n    { type: `channel:${string}` | `notice:${string}` }\n  >;\n};\n\n/**\n * Subscribe to a typed observability channel.\n *\n * ```ts\n * import { subscribe } from \"agents/observability\";\n *\n * const unsub = subscribe(\"rpc\", (event) => {\n *   console.log(event.payload.method); // fully typed\n * });\n * ```\n *\n * @returns A function that unsubscribes the callback.\n */\nexport function subscribe<K extends keyof ChannelEventMap>(\n  channelKey: K,\n  callback: (event: ChannelEventMap[K]) => void\n): () => void {\n  const name =\n    CHANNEL_DIAGNOSTIC_NAME_OVERRIDES[channelKey] ?? `agents:${channelKey}`;\n  const handler = (message: unknown, _name: string | symbol) =>\n    callback(message as ChannelEventMap[K]);\n  dcSubscribe(name, handler);\n  return () => dcUnsubscribe(name, handler);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAuCA,MAAa,WAAW;CACtB,OAAO,QAAQ,cAAc;CAC7B,KAAK,QAAQ,YAAY;CACzB,SAAS,QAAQ,gBAAgB;CACjC,MAAM,QAAQ,aAAa;CAC3B,YAAY,QAAQ,mBAAmB;CACvC,OAAO,QAAQ,cAAc;CAC7B,WAAW,QAAQ,mBAAmB;CACtC,UAAU,QAAQ,iBAAiB;CACnC,WAAW,QAAQ,kBAAkB;CACrC,UAAU,QAAQ,iBAAiB;CACnC,KAAK,QAAQ,YAAY;CACzB,OAAO,QAAQ,cAAc;CAC7B,SAAS,QAAQ,gBAAgB;AACnC;;;;;;AAOA,MAAM,oCAAqE,EACzE,WAAW,oBACb;;;;AAKA,SAAS,WAAW,MAAuB;CACzC,IAAI,KAAK,WAAW,MAAM,GAAG,OAAO,SAAS;CAC7C,IAAI,KAAK,WAAW,WAAW,GAAG,OAAO,SAAS;CAClD,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO,SAAS;CAC/C,IAAI,KAAK,WAAW,aAAa,KAAK,KAAK,WAAW,kBAAkB,GACtE,OAAO,SAAS;CAClB,IAAI,KAAK,WAAW,OAAO,GAAG,OAAO,SAAS;CAC9C,IAAI,KAAK,WAAW,aAAa,GAAG,OAAO,SAAS;CACpD,IAAI,KAAK,WAAW,WAAW,KAAK,KAAK,WAAW,QAAQ,GAC1D,OAAO,SAAS;CAClB,IACE,KAAK,WAAW,UAAU,KAC1B,KAAK,WAAW,OAAO,KACvB,KAAK,WAAW,aAAa,KAC7B,KAAK,WAAW,SAAS,GAEzB,OAAO,SAAS;CAClB,IAAI,SAAS,SAAS,KAAK,WAAW,MAAM,GAAG,OAAO,SAAS;CAC/D,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO,SAAS;CAC/C,IAAI,KAAK,WAAW,QAAQ,GAAG,OAAO,SAAS;CAC/C,IAAI,KAAK,WAAW,UAAU,KAAK,KAAK,WAAW,SAAS,GAC1D,OAAO,SAAS;CAElB,OAAO,SAAS;AAClB;;;;;;;AAQA,MAAa,uBAAsC,EACjD,KAAK,OAAO;CACV,WAAW,MAAM,IAAI,CAAC,CAAC,QAAQ,KAAK;AACtC,EACF;;;;;;;;;;;;;;AA0DA,SAAgB,UACd,YACA,UACY;CACZ,MAAM,OACJ,kCAAkC,eAAe,UAAU;CAC7D,MAAM,WAAW,SAAkB,UACjC,SAAS,OAA6B;CACxC,YAAY,MAAM,OAAO;CACzB,aAAaA,YAAc,MAAM,OAAO;AAC1C"}
+{"version":3,"file":"index.js","names":["dcUnsubscribe"],"sources":["../../src/observability/index.ts"],"sourcesContent":["import {\n  subscribe as dcSubscribe,\n  unsubscribe as dcUnsubscribe\n} from \"node:diagnostics_channel\";\nimport type { AgentObservabilityEvent } from \"./agent\";\nimport type { MCPObservabilityEvent } from \"./mcp\";\nimport { publishDiagnosticsEvent } from \"./diagnostics\";\nexport { channels } from \"./diagnostics\";\n\n/**\n * Union of all observability event types from different domains\n */\nexport type ObservabilityEvent =\n  | AgentObservabilityEvent\n  | MCPObservabilityEvent;\n\nexport interface Observability {\n  /**\n   * Emit an event for the Agent's observability implementation to handle.\n   * @param event - The event to emit\n   */\n  emit(event: ObservabilityEvent): void;\n}\n\n/**\n * Channel keys whose diagnostics channel name differs from `agents:${key}`.\n * Keep this in sync with {@link channels} for any camelCase key that maps to a\n * snake_case diagnostics channel.\n */\nconst CHANNEL_DIAGNOSTIC_NAME_OVERRIDES: Partial<Record<string, string>> = {\n  agentTool: \"agents:agent_tool\"\n};\n\n/**\n * The default observability implementation.\n *\n * Publishes events to diagnostics_channel. Events are silent unless\n * a subscriber is registered or a Tail Worker is attached.\n */\nexport const genericObservability: Observability = {\n  emit(event) {\n    publishDiagnosticsEvent(event);\n  }\n};\n\n/**\n * Maps each channel key to the observability events it carries.\n */\nexport type ChannelEventMap = {\n  state: Extract<ObservabilityEvent, { type: `state:${string}` }>;\n  rpc: Extract<ObservabilityEvent, { type: \"rpc\" | `rpc:${string}` }>;\n  message: Extract<\n    ObservabilityEvent,\n    {\n      type:\n        | `message:${string}`\n        | `tool:${string}`\n        | `submission:${string}`\n        | `action:${string}`;\n    }\n  >;\n  chat: Exclude<\n    Extract<ObservabilityEvent, { type: `chat:${string}` }>,\n    { type: `chat:transcript:${string}` }\n  >;\n  transcript: Extract<\n    ObservabilityEvent,\n    { type: `transcript:${string}` | `chat:transcript:${string}` }\n  >;\n  fiber: Extract<ObservabilityEvent, { type: `fiber:${string}` }>;\n  agentTool: Extract<ObservabilityEvent, { type: `agent_tool:${string}` }>;\n  schedule: Extract<\n    ObservabilityEvent,\n    { type: `schedule:${string}` | `queue:${string}` }\n  >;\n  lifecycle: Extract<\n    ObservabilityEvent,\n    { type: \"connect\" | \"disconnect\" | \"destroy\" }\n  >;\n  workflow: Extract<ObservabilityEvent, { type: `workflow:${string}` }>;\n  mcp: Extract<ObservabilityEvent, { type: `mcp:${string}` }>;\n  email: Extract<ObservabilityEvent, { type: `email:${string}` }>;\n  channel: Extract<\n    ObservabilityEvent,\n    { type: `channel:${string}` | `notice:${string}` }\n  >;\n};\n\n/**\n * Subscribe to a typed observability channel.\n *\n * ```ts\n * import { subscribe } from \"agents/observability\";\n *\n * const unsub = subscribe(\"rpc\", (event) => {\n *   console.log(event.payload.method); // fully typed\n * });\n * ```\n *\n * @returns A function that unsubscribes the callback.\n */\nexport function subscribe<K extends keyof ChannelEventMap>(\n  channelKey: K,\n  callback: (event: ChannelEventMap[K]) => void\n): () => void {\n  const name =\n    CHANNEL_DIAGNOSTIC_NAME_OVERRIDES[channelKey] ?? `agents:${channelKey}`;\n  const handler = (message: unknown, _name: string | symbol) =>\n    callback(message as ChannelEventMap[K]);\n  dcSubscribe(name, handler);\n  return () => dcUnsubscribe(name, handler);\n}\n"],"mappings":";;;;;;;;AA6BA,MAAM,oCAAqE,EACzE,WAAW,oBACb;;;;;;;AAQA,MAAa,uBAAsC,EACjD,KAAK,OAAO;CACV,wBAAwB,KAAK;AAC/B,EACF;;;;;;;;;;;;;;AA0DA,SAAgB,UACd,YACA,UACY;CACZ,MAAM,OACJ,kCAAkC,eAAe,UAAU;CAC7D,MAAM,WAAW,SAAkB,UACjC,SAAS,OAA6B;CACxC,YAAY,MAAM,OAAO;CACzB,aAAaA,YAAc,MAAM,OAAO;AAC1C"}

package/dist/{protocol-Dqc2MQxo.js → protocol-B0nh6KNf.js}

@@ -9,8 +9,10 @@ var StreamAccumulator = class {
 		this._isContinuation = options.continuation ?? false;
 		this.parts = options.existingParts ? [...options.existingParts] : [];
 		this.metadata = options.existingMetadata ? { ...options.existingMetadata } : void 0;
+		this._pendingContinuationChunks = this._isContinuation && options.existingParts === void 0 && options.existingMetadata === void 0 ? [] : null;
 	}
 	applyChunk(chunk) {
+		this._pendingContinuationChunks?.push(chunk);
 		const handled = applyChunkToParts(this.parts, chunk);
 		if (chunk.type === "tool-approval-request" && chunk.toolCallId) return {
 			handled,
@@ -101,7 +103,8 @@ var StreamAccumulator = class {
 	/**
 	* Merge this accumulator's message into an existing message array.
 	* Handles continuation (walk backward for last assistant), replacement
-	* (update existing by messageId), or append (new message).
+	* (update existing by messageId), or append (new message). An unseeded
+	* continuation adopts current parts here before applying its queued chunks.
 	*/
 	mergeInto(messages) {
 		let existingIdx = messages.findIndex((m) => m.id === this.messageId);
@@ -111,6 +114,15 @@ var StreamAccumulator = class {
 				break;
 			}
 		}
+		if (this._pendingContinuationChunks !== null) {
+			const pendingChunks = this._pendingContinuationChunks;
+			this._pendingContinuationChunks = null;
+			this.parts.splice(0, this.parts.length, ...existingIdx >= 0 ? messages[existingIdx].parts : []);
+			const currentMetadata = existingIdx >= 0 ? asMetadata(messages[existingIdx].metadata) : void 0;
+			this.metadata = currentMetadata ? { ...currentMetadata } : void 0;
+			if (existingIdx >= 0) this.messageId = messages[existingIdx].id;
+			for (const chunk of pendingChunks) this.applyChunk(chunk);
+		}
 		const partialMessage = {
 			id: existingIdx >= 0 ? messages[existingIdx].id : this.messageId,
 			role: "assistant",
@@ -147,25 +159,11 @@ function transition(state, event) {
 		case "response": {
 			let accumulator;
 			const isReplayedStart = event.replay === true && event.chunkData?.type === "start";
-			if (state.status === "idle" || state.streamId !== event.streamId || isReplayedStart) {
-				let messageId = event.messageId;
-				let existingParts;
-				let existingMetadata;
-				if (event.continuation && event.currentMessages) {
-					for (let i = event.currentMessages.length - 1; i >= 0; i--) if (event.currentMessages[i].role === "assistant") {
-						messageId = event.currentMessages[i].id;
-						existingParts = [...event.currentMessages[i].parts];
-						if (event.currentMessages[i].metadata != null) existingMetadata = { ...event.currentMessages[i].metadata };
-						break;
-					}
-				}
-				accumulator = new StreamAccumulator({
-					messageId,
-					continuation: event.continuation,
-					existingParts,
-					existingMetadata
-				});
-			} else accumulator = state.accumulator;
+			if (state.status === "idle" || state.streamId !== event.streamId || isReplayedStart) accumulator = new StreamAccumulator({
+				messageId: event.messageId,
+				continuation: event.continuation
+			});
+			else accumulator = state.accumulator;
 			if (event.chunkData) accumulator.applyChunk(event.chunkData);
 			let messagesUpdate;
 			if (event.done) {
@@ -224,4 +222,4 @@ const CHAT_MESSAGE_TYPES = {
 //#endregion
 export { StreamAccumulator as i, STREAM_RESUME_NONE_REASONS as n, transition as r, CHAT_MESSAGE_TYPES as t };
 
-//# sourceMappingURL=protocol-Dqc2MQxo.js.map
+//# sourceMappingURL=protocol-B0nh6KNf.js.map

package/dist/protocol-B0nh6KNf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-B0nh6KNf.js","names":[],"sources":["../src/chat/stream-accumulator.ts","../src/chat/broadcast-state.ts","../src/chat/protocol.ts"],"sourcesContent":["/**\n * StreamAccumulator — unified chunk-to-message builder.\n *\n * Used by @cloudflare/ai-chat (server + client) and @cloudflare/think\n * to incrementally build a UIMessage from stream chunks. Wraps\n * applyChunkToParts and handles the metadata chunk types (start, finish,\n * message-metadata, error) that applyChunkToParts does not cover.\n *\n * The accumulator signals domain-specific concerns (early persistence,\n * cross-message tool updates) via ChunkAction returns — callers handle\n * these according to their context.\n */\n\nimport type { UIMessage } from \"ai\";\nimport { applyChunkToParts, type StreamChunkData } from \"./message-builder\";\n\nfunction asMetadata(value: unknown): Record<string, unknown> | undefined {\n  if (value != null && typeof value === \"object\" && !Array.isArray(value)) {\n    return value as Record<string, unknown>;\n  }\n  return undefined;\n}\n\nexport interface StreamAccumulatorOptions {\n  messageId: string;\n  /** Whether chunks continue the current assistant message when merged. */\n  continuation?: boolean;\n  /** Eager seed; omitted continuations seed from the messages passed to `mergeInto`. */\n  existingParts?: UIMessage[\"parts\"];\n  existingMetadata?: Record<string, unknown>;\n}\n\nexport type ChunkAction =\n  | {\n      type: \"start\";\n      messageId?: string;\n      metadata?: Record<string, unknown>;\n    }\n  | {\n      type: \"finish\";\n      finishReason?: string;\n      metadata?: Record<string, unknown>;\n    }\n  | { type: \"message-metadata\"; metadata: Record<string, unknown> }\n  | { type: \"tool-approval-request\"; toolCallId: string }\n  | {\n      type: \"cross-message-tool-update\";\n      updateType: \"output-available\" | \"output-error\";\n      toolCallId: string;\n      output?: unknown;\n      errorText?: string;\n      preliminary?: boolean;\n    }\n  | { type: \"error\"; error: string };\n\nexport interface ChunkResult {\n  handled: boolean;\n  action?: ChunkAction;\n}\n\nexport class StreamAccumulator {\n  messageId: string;\n  readonly parts: UIMessage[\"parts\"];\n  metadata?: Record<string, unknown>;\n  private _isContinuation: boolean;\n  // Continuation chunks wait here until mergeInto can seed from current state.\n  private _pendingContinuationChunks: StreamChunkData[] | null;\n\n  constructor(options: StreamAccumulatorOptions) {\n    this.messageId = options.messageId;\n    this._isContinuation = options.continuation ?? false;\n    this.parts = options.existingParts ? [...options.existingParts] : [];\n    this.metadata = options.existingMetadata\n      ? { ...options.existingMetadata }\n      : undefined;\n    this._pendingContinuationChunks =\n      this._isContinuation &&\n      options.existingParts === undefined &&\n      options.existingMetadata === undefined\n        ? []\n        : null;\n  }\n\n  applyChunk(chunk: StreamChunkData): ChunkResult {\n    this._pendingContinuationChunks?.push(chunk);\n    const handled = applyChunkToParts(this.parts, chunk);\n\n    // Detect tool-approval-request for early persistence signaling\n    if (chunk.type === \"tool-approval-request\" && chunk.toolCallId) {\n      return {\n        handled,\n        action: { type: \"tool-approval-request\", toolCallId: chunk.toolCallId }\n      };\n    }\n\n    // Detect cross-message tool output/error: applyChunkToParts returns true\n    // for recognized types but silently does nothing when the toolCallId\n    // doesn't exist in the current parts array.\n    if (\n      (chunk.type === \"tool-output-available\" ||\n        chunk.type === \"tool-output-error\") &&\n      chunk.toolCallId\n    ) {\n      const foundInParts = this.parts.some(\n        (p) => \"toolCallId\" in p && p.toolCallId === chunk.toolCallId\n      );\n      if (!foundInParts) {\n        return {\n          handled,\n          action: {\n            type: \"cross-message-tool-update\",\n            updateType:\n              chunk.type === \"tool-output-available\"\n                ? \"output-available\"\n                : \"output-error\",\n            toolCallId: chunk.toolCallId,\n            output: chunk.output,\n            errorText: chunk.errorText,\n            preliminary: chunk.preliminary\n          }\n        };\n      }\n    }\n\n    if (!handled) {\n      switch (chunk.type) {\n        case \"start\": {\n          if (chunk.messageId != null && !this._isContinuation) {\n            this.messageId = chunk.messageId;\n          }\n          const startMeta = asMetadata(chunk.messageMetadata);\n          if (startMeta) {\n            this.metadata = this.metadata\n              ? { ...this.metadata, ...startMeta }\n              : { ...startMeta };\n          }\n          return {\n            handled: true,\n            action: {\n              type: \"start\",\n              messageId: chunk.messageId,\n              metadata: startMeta\n            }\n          };\n        }\n        case \"finish\": {\n          const finishMeta = asMetadata(chunk.messageMetadata);\n          if (finishMeta) {\n            this.metadata = this.metadata\n              ? { ...this.metadata, ...finishMeta }\n              : { ...finishMeta };\n          }\n          const finishReason =\n            \"finishReason\" in chunk\n              ? (chunk.finishReason as string)\n              : undefined;\n          return {\n            handled: true,\n            action: {\n              type: \"finish\",\n              finishReason,\n              metadata: finishMeta\n            }\n          };\n        }\n        case \"message-metadata\": {\n          const msgMeta = asMetadata(chunk.messageMetadata);\n          if (msgMeta) {\n            this.metadata = this.metadata\n              ? { ...this.metadata, ...msgMeta }\n              : { ...msgMeta };\n          }\n          return {\n            handled: true,\n            action: {\n              type: \"message-metadata\",\n              metadata: msgMeta ?? {}\n            }\n          };\n        }\n        case \"finish-step\": {\n          return { handled: true };\n        }\n        case \"error\": {\n          return {\n            handled: true,\n            action: {\n              type: \"error\",\n              error: chunk.errorText ?? JSON.stringify(chunk)\n            }\n          };\n        }\n      }\n    }\n\n    return { handled };\n  }\n\n  /** Snapshot the current state as a UIMessage. */\n  toMessage(): UIMessage {\n    return {\n      id: this.messageId,\n      role: \"assistant\",\n      parts: [...this.parts],\n      ...(this.metadata != null && { metadata: this.metadata })\n    } as UIMessage;\n  }\n\n  /**\n   * Merge this accumulator's message into an existing message array.\n   * Handles continuation (walk backward for last assistant), replacement\n   * (update existing by messageId), or append (new message). An unseeded\n   * continuation adopts current parts here before applying its queued chunks.\n   */\n  mergeInto(messages: UIMessage[]): UIMessage[] {\n    let existingIdx = messages.findIndex((m) => m.id === this.messageId);\n\n    if (existingIdx < 0 && this._isContinuation) {\n      for (let i = messages.length - 1; i >= 0; i--) {\n        if (messages[i].role === \"assistant\") {\n          existingIdx = i;\n          break;\n        }\n      }\n    }\n\n    if (this._pendingContinuationChunks !== null) {\n      const pendingChunks = this._pendingContinuationChunks;\n      this._pendingContinuationChunks = null;\n      this.parts.splice(\n        0,\n        this.parts.length,\n        ...(existingIdx >= 0 ? messages[existingIdx].parts : [])\n      );\n      const currentMetadata =\n        existingIdx >= 0\n          ? asMetadata(messages[existingIdx].metadata)\n          : undefined;\n      this.metadata = currentMetadata ? { ...currentMetadata } : undefined;\n      if (existingIdx >= 0) {\n        this.messageId = messages[existingIdx].id;\n      }\n      for (const chunk of pendingChunks) {\n        this.applyChunk(chunk);\n      }\n    }\n\n    const messageId =\n      existingIdx >= 0 ? messages[existingIdx].id : this.messageId;\n\n    const partialMessage: UIMessage = {\n      id: messageId,\n      role: \"assistant\",\n      parts: [...this.parts],\n      ...(this.metadata != null && { metadata: this.metadata })\n    } as UIMessage;\n\n    if (existingIdx >= 0) {\n      const updated = [...messages];\n      updated[existingIdx] = partialMessage;\n      return updated;\n    }\n    return [...messages, partialMessage];\n  }\n}\n","/**\n * Broadcast stream state machine.\n *\n * Manages the lifecycle of a StreamAccumulator for broadcast/resume\n * streams — the path where this client is *observing* a stream owned\n * by another tab or resumed after reconnect, rather than the transport-\n * owned path that feeds directly into useChat.\n *\n * The transition function is pure (no React, no WebSocket, no side\n * effects). Callers dispatch events and apply the returned state +\n * messagesUpdate. Side effects (sending ACKs, calling onData) stay\n * in the caller.\n */\n\nimport type { UIMessage } from \"ai\";\nimport { StreamAccumulator } from \"./stream-accumulator\";\nimport type { StreamChunkData } from \"./message-builder\";\n\n// ── State ──────────────────────────────────────────────────────────\n\nexport type BroadcastStreamState =\n  | { status: \"idle\" }\n  | {\n      status: \"observing\";\n      streamId: string;\n      accumulator: StreamAccumulator;\n    };\n\n// ── Events ─────────────────────────────────────────────────────────\n\nexport type BroadcastStreamEvent =\n  | {\n      type: \"response\";\n      streamId: string;\n      /** Fallback message ID for a new accumulator (ignored if one exists for this stream). */\n      messageId: string;\n      chunkData?: unknown;\n      done?: boolean;\n      error?: boolean;\n      replay?: boolean;\n      replayComplete?: boolean;\n      continuation?: boolean;\n      /** @deprecated Continuations now seed from current messages in `messagesUpdate`. */\n      currentMessages?: UIMessage[];\n    }\n  | {\n      type: \"resume-fallback\";\n      streamId: string;\n      messageId: string;\n    }\n  | { type: \"clear\" };\n\n// ── Result ─────────────────────────────────────────────────────────\n\nexport interface TransitionResult {\n  state: BroadcastStreamState;\n  messagesUpdate?: (prev: UIMessage[]) => UIMessage[];\n  isStreaming: boolean;\n}\n\n// ── Transition ─────────────────────────────────────────────────────\n\nexport function transition(\n  state: BroadcastStreamState,\n  event: BroadcastStreamEvent\n): TransitionResult {\n  switch (event.type) {\n    case \"clear\":\n      return { state: { status: \"idle\" }, isStreaming: false };\n\n    case \"resume-fallback\": {\n      const accumulator = new StreamAccumulator({\n        messageId: event.messageId\n      });\n      return {\n        state: {\n          status: \"observing\",\n          streamId: event.streamId,\n          accumulator\n        },\n        isStreaming: true\n      };\n    }\n\n    case \"response\": {\n      let accumulator: StreamAccumulator;\n\n      // A replayed `start` chunk means the server is re-sending the stream\n      // buffer from chunk 0 (resume replay). Re-initialize the accumulator\n      // instead of appending into an existing one: replaying into an\n      // accumulator that already holds this stream's parts would duplicate\n      // them (a second `text-start` unconditionally opens a second text\n      // part — #1733). Re-initializing makes replay idempotent under any\n      // number of replays, including a second replay triggered by a\n      // duplicate STREAM_RESUMING → ACK cycle or a reconnect.\n      const isReplayedStart =\n        event.replay === true &&\n        (event.chunkData as { type?: string } | null | undefined)?.type ===\n          \"start\";\n\n      if (\n        state.status === \"idle\" ||\n        state.streamId !== event.streamId ||\n        isReplayedStart\n      ) {\n        accumulator = new StreamAccumulator({\n          messageId: event.messageId,\n          continuation: event.continuation\n        });\n      } else {\n        accumulator = state.accumulator;\n      }\n\n      if (event.chunkData) {\n        accumulator.applyChunk(event.chunkData as StreamChunkData);\n      }\n\n      let messagesUpdate: ((prev: UIMessage[]) => UIMessage[]) | undefined;\n\n      if (event.done) {\n        messagesUpdate = (prev) => accumulator.mergeInto(prev);\n        return {\n          state: { status: \"idle\" },\n          messagesUpdate,\n          isStreaming: false\n        };\n      }\n\n      if (event.chunkData && !event.replay) {\n        messagesUpdate = (prev) => accumulator.mergeInto(prev);\n      } else if (event.replayComplete) {\n        messagesUpdate = (prev) => accumulator.mergeInto(prev);\n      }\n\n      return {\n        state: {\n          status: \"observing\",\n          streamId: event.streamId,\n          accumulator\n        },\n        messagesUpdate,\n        isStreaming: true\n      };\n    }\n  }\n}\n","/**\n * Wire protocol message type constants for the cf_agent_chat_* protocol.\n *\n * These are the string values used on the wire between agent servers and\n * clients. Both @cloudflare/ai-chat (via its MessageType enum) and\n * @cloudflare/think use these values.\n */\nexport const STREAM_RESUME_NONE_REASONS = {\n  /** No active, pending, or terminal stream exists for this agent. */\n  IDLE: \"idle\",\n  /** An active tool continuation is owned by another live connection. */\n  CONTINUATION_OWNED: \"continuation-owned\"\n} as const;\n\nexport type StreamResumeNoneReason =\n  (typeof STREAM_RESUME_NONE_REASONS)[keyof typeof STREAM_RESUME_NONE_REASONS];\n\nexport const CHAT_MESSAGE_TYPES = {\n  CHAT_MESSAGES: \"cf_agent_chat_messages\",\n  USE_CHAT_REQUEST: \"cf_agent_use_chat_request\",\n  USE_CHAT_RESPONSE: \"cf_agent_use_chat_response\",\n  CHAT_CLEAR: \"cf_agent_chat_clear\",\n  CHAT_REQUEST_CANCEL: \"cf_agent_chat_request_cancel\",\n  STREAM_RESUMING: \"cf_agent_stream_resuming\",\n  STREAM_RESUME_ACK: \"cf_agent_stream_resume_ack\",\n  STREAM_RESUME_REQUEST: \"cf_agent_stream_resume_request\",\n  STREAM_RESUME_NONE: \"cf_agent_stream_resume_none\",\n  // Server→client: a turn has been accepted but its resumable stream has not\n  // started yet (queued, debouncing, waiting on MCP setup, or running async\n  // work in `onChatMessage`). Sent in response to a resume request (or on\n  // connect) so a reconnecting/re-mounting client keeps its expectation instead\n  // of resolving its resume probe to \"no stream\" and then false-timing-out the\n  // turn. Resolved by a later `STREAM_RESUMING` (stream started) or\n  // `STREAM_RESUME_NONE` (turn settled without streaming). Backward-compatible —\n  // clients that don't understand it ignore it. See issue #1784.\n  STREAM_PENDING: \"cf_agent_stream_pending\",\n  TOOL_RESULT: \"cf_agent_tool_result\",\n  TOOL_APPROVAL: \"cf_agent_tool_approval\",\n  MESSAGE_UPDATED: \"cf_agent_message_updated\",\n  // Server→client: a durable chat turn is being recovered (interrupted by a\n  // deploy/eviction or a stream-stall watchdog abort and now resuming). Sent\n  // when a recovery continuation is scheduled and cleared on every terminal\n  // outcome; `@cloudflare/think` also replays it on connect so a client that\n  // joins mid-recovery learns it. Purely a progress hint — backward-compatible\n  // (clients that don't understand it ignore it). See issue #1620.\n  CHAT_RECOVERING: \"cf_agent_chat_recovering\"\n} as const;\n"],"mappings":"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"}

package/dist/react.d.ts

@@ -1,8 +1,8 @@
 import {
-  Y as MCPServersState,
-  _ as AgentToolRunState,
-  g as AgentToolRunPart
-} from "./agent-tool-types-CzGGB-20.js";
+  C as MCPServersState,
+  J as AgentToolRunPart,
+  Y as AgentToolRunState
+} from "./agent-routing-DE5zmCQ8.js";
 import { ClientParameters } from "./serializable.js";
 import {
   AgentConnectionError,

package/dist/react.js

@@ -1,5 +1,5 @@
-import "./types.js";
 import { camelCaseToKebabCase } from "./utils.js";
+import "./types.js";
 import { AgentConnectionError, createStubProxy, isTerminalCloseEvent } from "./client.js";
 import { buildSubAgentPathUnchecked } from "./sub-routing.js";
 import { n as applyAgentToolEvent, r as createAgentToolEventState } from "./agent-tools-y7zLfw4Q.js";

package/dist/{retries-CAvxtG9d.d.ts → retries-D9Ds-1lz.d.ts}

@@ -111,17 +111,28 @@ declare function isDurableObjectMemoryLimitReset(error: unknown): boolean;
  * error — re-running yields the same failure). A genuine application error
  * carries none of these signals, so it is never misclassified by this check.
  */
+/**
+ * Whether a failure is the PLATFORM's rather than the application's — any
+ * platform transient (see {@link isPlatformTransientError}, which includes
+ * superseded-isolate resets) or a memory-limit reset. Failed work in this
+ * class must be PRESERVED and deferred, never completed as an application
+ * failure. The two sub-classes defer differently: transients re-run
+ * indefinitely (the platform recovers), while memory-limit deferral is
+ * bounded by the alarm circuit breaker (#1825).
+ */
+declare function isPlatformFailure(error: unknown): boolean;
 declare function isPlatformTransientError(error: unknown): boolean;
 //#endregion
 export {
   isErrorRetryable as a,
-  tryN as c,
+  jitterBackoff as c,
   isDurableObjectStorageReset as i,
-  validateRetryOptions as l,
+  tryN as l,
   isDurableObjectCodeUpdateReset as n,
-  isPlatformTransientError as o,
+  isPlatformFailure as o,
   isDurableObjectMemoryLimitReset as r,
-  jitterBackoff as s,
-  RetryOptions as t
+  isPlatformTransientError as s,
+  RetryOptions as t,
+  validateRetryOptions as u
 };
-//# sourceMappingURL=retries-CAvxtG9d.d.ts.map
+//# sourceMappingURL=retries-D9Ds-1lz.d.ts.map

package/dist/retries.d.ts

@@ -1,20 +1,22 @@
 import {
   a as isErrorRetryable,
-  c as tryN,
+  c as jitterBackoff,
   i as isDurableObjectStorageReset,
-  l as validateRetryOptions,
+  l as tryN,
   n as isDurableObjectCodeUpdateReset,
-  o as isPlatformTransientError,
+  o as isPlatformFailure,
   r as isDurableObjectMemoryLimitReset,
-  s as jitterBackoff,
-  t as RetryOptions
-} from "./retries-CAvxtG9d.js";
+  s as isPlatformTransientError,
+  t as RetryOptions,
+  u as validateRetryOptions
+} from "./retries-D9Ds-1lz.js";
 export {
   RetryOptions,
   isDurableObjectCodeUpdateReset,
   isDurableObjectMemoryLimitReset,
   isDurableObjectStorageReset,
   isErrorRetryable,
+  isPlatformFailure,
   isPlatformTransientError,
   jitterBackoff,
   tryN,

package/dist/retries.js

@@ -213,6 +213,18 @@ function isDurableObjectMemoryLimitReset(error) {
 * error — re-running yields the same failure). A genuine application error
 * carries none of these signals, so it is never misclassified by this check.
 */
+/**
+* Whether a failure is the PLATFORM's rather than the application's — any
+* platform transient (see {@link isPlatformTransientError}, which includes
+* superseded-isolate resets) or a memory-limit reset. Failed work in this
+* class must be PRESERVED and deferred, never completed as an application
+* failure. The two sub-classes defer differently: transients re-run
+* indefinitely (the platform recovers), while memory-limit deferral is
+* bounded by the alarm circuit breaker (#1825).
+*/
+function isPlatformFailure(error) {
+	return isPlatformTransientError(error) || isDurableObjectMemoryLimitReset(error);
+}
 function isPlatformTransientError(error) {
 	for (const e of selfAndCauses(error)) {
 		const message = errorMessageOf(e);
@@ -224,6 +236,6 @@ function isPlatformTransientError(error) {
 	return false;
 }
 //#endregion
-export { isDurableObjectCodeUpdateReset, isDurableObjectMemoryLimitReset, isDurableObjectStorageReset, isErrorRetryable, isPlatformTransientError, jitterBackoff, tryN, validateRetryOptions };
+export { isDurableObjectCodeUpdateReset, isDurableObjectMemoryLimitReset, isDurableObjectStorageReset, isErrorRetryable, isPlatformFailure, isPlatformTransientError, jitterBackoff, tryN, validateRetryOptions };
 
 //# sourceMappingURL=retries.js.map

package/dist/retries.js.map

@@ -1 +1 @@
-{"version":3,"file":"retries.js","names":[],"sources":["../src/retries.ts"],"sourcesContent":["/**\n * Retry options for schedule(), scheduleEvery(), queue(), and this.retry().\n */\nexport interface RetryOptions {\n  /** Max number of attempts (including the first). Default: 3 */\n  maxAttempts?: number;\n  /** Base delay in ms for exponential backoff. Default: 100 */\n  baseDelayMs?: number;\n  /** Max delay cap in ms. Default: 3000 */\n  maxDelayMs?: number;\n}\n\n/**\n * Internal options for tryN -- extends RetryOptions with a shouldRetry predicate.\n */\ninterface TryNOptions extends RetryOptions {\n  /**\n   * Predicate to determine if an error should be retried.\n   * Receives the error and the next attempt number (so callers can\n   * make attempt-aware decisions).\n   * If not provided, all errors are retried.\n   */\n  shouldRetry?: (err: unknown, nextAttempt: number) => boolean;\n}\n\n/**\n * Validate retry options eagerly so invalid config fails at enqueue/schedule time\n * rather than at execution time. Checks individual field ranges, enforces integer\n * maxAttempts, and validates cross-field constraints after resolving against\n * defaults when provided.\n */\nexport function validateRetryOptions(\n  options: RetryOptions,\n  defaults?: Required<RetryOptions>\n): void {\n  if (options.maxAttempts !== undefined) {\n    if (!Number.isFinite(options.maxAttempts) || options.maxAttempts < 1) {\n      throw new Error(\"retry.maxAttempts must be >= 1\");\n    }\n    if (!Number.isInteger(options.maxAttempts)) {\n      throw new Error(\"retry.maxAttempts must be an integer\");\n    }\n  }\n  if (options.baseDelayMs !== undefined) {\n    if (!Number.isFinite(options.baseDelayMs) || options.baseDelayMs <= 0) {\n      throw new Error(\"retry.baseDelayMs must be > 0\");\n    }\n  }\n  if (options.maxDelayMs !== undefined) {\n    if (!Number.isFinite(options.maxDelayMs) || options.maxDelayMs <= 0) {\n      throw new Error(\"retry.maxDelayMs must be > 0\");\n    }\n  }\n\n  // Resolve against defaults (when provided) so that cross-field checks\n  // catch e.g. { baseDelayMs: 5000 } against default maxDelayMs: 3000.\n  const resolvedBase = options.baseDelayMs ?? defaults?.baseDelayMs;\n  const resolvedMax = options.maxDelayMs ?? defaults?.maxDelayMs;\n  if (\n    resolvedBase !== undefined &&\n    resolvedMax !== undefined &&\n    resolvedBase > resolvedMax\n  ) {\n    throw new Error(\"retry.baseDelayMs must be <= retry.maxDelayMs\");\n  }\n}\n\n/**\n * Returns the number of milliseconds to wait before retrying a request.\n * Uses the \"Full Jitter\" approach from\n * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/\n *\n * @param attempt The current attempt number (1-indexed).\n * @param baseDelayMs Base delay multiplier in ms.\n * @param maxDelayMs Maximum delay cap in ms.\n * @returns Milliseconds to wait before retrying.\n */\nexport function jitterBackoff(\n  attempt: number,\n  baseDelayMs: number,\n  maxDelayMs: number\n): number {\n  const upperBoundMs = Math.min(2 ** attempt * baseDelayMs, maxDelayMs);\n  return Math.floor(Math.random() * upperBoundMs);\n}\n\n/**\n * Retry an async function up to `n` total attempts with jittered exponential backoff.\n *\n * @param n Total number of attempts (must be a finite integer >= 1).\n * @param fn The async function to retry. Receives the current attempt number (1-indexed).\n * @param options Retry configuration.\n * @returns The result of `fn` on success.\n * @throws The last error if all attempts fail or `shouldRetry` returns false.\n */\nexport async function tryN<T>(\n  n: number,\n  fn: (attempt: number) => Promise<T>,\n  options?: TryNOptions\n): Promise<T> {\n  if (!Number.isFinite(n) || n < 1) {\n    throw new Error(\"retry.maxAttempts must be >= 1\");\n  }\n  n = Math.floor(n);\n\n  const rawBase = options?.baseDelayMs ?? 100;\n  const rawMax = options?.maxDelayMs ?? 3000;\n\n  if (!Number.isFinite(rawBase) || rawBase <= 0) {\n    throw new Error(\"retry.baseDelayMs must be > 0\");\n  }\n  if (!Number.isFinite(rawMax) || rawMax <= 0) {\n    throw new Error(\"retry.maxDelayMs must be > 0\");\n  }\n\n  const baseDelayMs = Math.floor(rawBase);\n  const maxDelayMs = Math.floor(rawMax);\n\n  if (baseDelayMs > maxDelayMs) {\n    throw new Error(\"retry.baseDelayMs must be <= retry.maxDelayMs\");\n  }\n\n  let attempt = 1;\n  while (true) {\n    try {\n      return await fn(attempt);\n    } catch (err) {\n      const nextAttempt = attempt + 1;\n      if (\n        nextAttempt > n ||\n        (options?.shouldRetry && !options.shouldRetry(err, nextAttempt))\n      ) {\n        throw err;\n      }\n      const delay = jitterBackoff(attempt, baseDelayMs, maxDelayMs);\n      await new Promise((resolve) => setTimeout(resolve, delay));\n      attempt = nextAttempt;\n    }\n  }\n}\n\n/**\n * Returns true if the given error is retryable according to Durable Object error handling.\n * See https://developers.cloudflare.com/durable-objects/best-practices/error-handling/\n *\n * An error is retryable if it has `retryable: true` but is NOT an overloaded error.\n */\nexport function isErrorRetryable(err: unknown): boolean {\n  if (typeof err !== \"object\" || err === null) {\n    return false;\n  }\n  const msg = String(err);\n  const typed = err as { retryable?: boolean; overloaded?: boolean };\n  return (\n    Boolean(typed.retryable) &&\n    !typed.overloaded &&\n    !msg.includes(\"Durable Object is overloaded\")\n  );\n}\n\n/**\n * The \"superseded isolate\" platform messages — the invocation is running on an\n * isolate the platform has replaced with a new version (a deploy / code\n * update). For the rest of that invocation every operation throws the same\n * error (code never reloads mid-invocation), so in-process retries are futile;\n * but the next fresh invocation runs the new code and succeeds.\n *\n * workerd surfaces this as a plain `Error` with one of a few messages, all the\n * same failure class — a message match is the only signal:\n *   - \"Durable Object reset because its code was updated.\"  (DO storage op on a\n *     superseded isolate / deploy bounce)\n *   - \"This script has been upgraded. Please send a new request to connect to\n *     the new version.\"  (a stub/connection to a superseded script; the message\n *     literally instructs the caller to retry on the new version)\n *\n * The match stays close to the verbatim platform strings (rather than a loose\n * \"upgraded\"/\"reset\" substring) so an ordinary application error that happens\n * to mention those words is NOT misclassified as a supersede.\n */\nconst SUPERSEDED_ISOLATE_PATTERN =\n  /reset because its code was updated|this script has been upgraded/i;\n\n/**\n * The \"Network connection lost.\" platform transient — the connection between\n * the isolate and its storage (or another DO) dropped. Unlike a supersede this\n * MAY succeed on an in-process retry (a momentary blip), so it must not skip\n * the in-process retry budget — but during a deploy-reset window it never\n * succeeds in-process and surfaces interleaved with the supersede messages\n * (SQL ops throw `SqlError: SQL query failed: Network connection lost.` while\n * KV ops throw the reset message), so on retry exhaustion it must be treated\n * as the platform's failure, not the callback's.\n */\nconst CONNECTION_LOST_PATTERN = /network connection lost/i;\n\n/**\n * The exact Durable Object storage-reset platform signal. Keep this narrow:\n * ordinary SQL and generic internal errors are application failures. This is a\n * transient storage reset, not a memory-limit poison pill.\n */\nconst STORAGE_RESET_PATTERN =\n  /Internal error in Durable Object storage caused object to be reset/i;\n\n/**\n * The Durable Object memory-limit reset — the isolate exceeded its 128 MB limit\n * and was reset by the platform (workerd surfaces this verbatim as\n * \"Durable Object's isolate exceeded its memory limit and was reset.\"; the D1\n * sibling is \"D1 DB's isolate exceeded its memory limit and was reset.\").\n *\n * The match is the broad shared fragment \"exceeded its memory limit\" rather than\n * the full \"...and was reset\" sentence: real-world surfacings truncate or reword\n * the tail (some log pipelines clip the message; D1/storage wrappers re-prefix\n * it), and a customer-reported loop (#1825) showed lines carrying only the\n * \"exceeded its memory limit\" fragment. Missing a surfacing here means the\n * circuit breaker never engages, so we err toward the broader match — and even a\n * false positive is fail-safe (a tightly-bounded retry-then-seal, not data loss).\n *\n * This is DELIBERATELY a separate class from `SUPERSEDED_ISOLATE_PATTERN` /\n * {@link isPlatformTransientError}, and is NOT folded into them. A supersede or\n * connection-lost transient means \"re-run the same work and it succeeds on a\n * healthy isolate\" — those classes can be deferred and retried *indefinitely*. A\n * memory-limit reset is the opposite: re-running the SAME memory-heavy work\n * deterministically re-OOMs (the footprint, not the platform, is the cause), so\n * deferring it indefinitely would PRESERVE the one-shot row and re-run the\n * doomed work forever (amplifying the loop and cost — see #1825). It is a\n * poison-pill signal: callers must bound retries tightly and then SEAL.\n *\n * Accordingly the schedule executor (`_executeScheduleCallback`) and the\n * alarm-boundary circuit breaker (`Agent.alarm`) treat it as its OWN class: a\n * memory-limit reset is re-thrown (row preserved) so it reaches the breaker,\n * which tolerates a few strikes (`maxAlarmMemoryLimitStrikes`) and then seals +\n * purges the looping row — i.e. *bounded* deferral, never the unbounded deferral\n * the transient classes get.\n */\nconst MEMORY_LIMIT_RESET_PATTERN = /exceeded its memory limit/i;\n\nfunction errorMessageOf(error: unknown): string {\n  return error instanceof Error\n    ? error.message\n    : typeof error === \"string\"\n      ? error\n      : \"\";\n}\n\n/**\n * Iterate an error and its `cause` chain (depth-limited so a cyclic chain\n * can't spin). Wrappers like `SqlError` carry the original platform error in\n * `cause` and may not propagate signal properties (e.g. the CF `retryable`\n * flag), so classification must look through them.\n */\nfunction* selfAndCauses(error: unknown): Generator<unknown> {\n  let current = error;\n  for (let depth = 0; depth < 8 && current != null; depth++) {\n    yield current;\n    current =\n      typeof current === \"object\"\n        ? (current as { cause?: unknown }).cause\n        : undefined;\n  }\n}\n\n/**\n * Whether an error (or anything in its `cause` chain) is a transient\n * \"superseded isolate\" failure — see `SUPERSEDED_ISOLATE_PATTERN`. In-process\n * retries are futile for this class; the work must be deferred to a fresh\n * invocation, which runs the new code and succeeds.\n */\nexport function isDurableObjectCodeUpdateReset(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    if (SUPERSEDED_ISOLATE_PATTERN.test(errorMessageOf(e))) return true;\n  }\n  return false;\n}\n\n/**\n * Whether an error (or anything in its `cause` chain) carries the exact\n * Durable Object storage-reset platform fragment. Generic SQL/internal errors\n * deliberately do not qualify.\n */\nexport function isDurableObjectStorageReset(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    if (STORAGE_RESET_PATTERN.test(errorMessageOf(e))) return true;\n  }\n  return false;\n}\n\n/**\n * Whether an error (or anything in its `cause` chain, or a raw error-message\n * string) is a Durable Object memory-limit reset — see\n * {@link MEMORY_LIMIT_RESET_PATTERN}. Unlike {@link isPlatformTransientError},\n * re-running the same work re-OOMs deterministically, so callers must NOT defer\n * it like a transient; they should bound retries tightly and then seal (#1825).\n */\nexport function isDurableObjectMemoryLimitReset(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    if (MEMORY_LIMIT_RESET_PATTERN.test(errorMessageOf(e))) return true;\n  }\n  return false;\n}\n\n/**\n * Whether an error (or anything in its `cause` chain) is a transient failure\n * of the PLATFORM rather than of the code that threw it:\n *\n *   - a superseded-isolate reset (\"reset because its code was updated\" /\n *     \"this script has been upgraded\") — a deploy replaced the isolate;\n *   - an error the platform itself flags `retryable: true` (excluding\n *     overloaded errors, where retrying the same object won't help) — see\n *     `isErrorRetryable`;\n *   - \"Network connection lost.\" — the storage/stub connection dropped. The\n *     CF `retryable` flag does not survive error wrappers (e.g. `SqlError`\n *     copies only the message + `cause`) and is absent in some local-dev\n *     shapes, so the verbatim message is matched as well;\n *   - the exact \"Internal error in Durable Object storage caused object to be\n *     reset\" platform fragment. Generic internal and SQL errors remain fatal.\n *\n * Used to decide whether failed work should be RE-RUN LATER (platform\n * transient — the same work succeeds once the platform recovers, typically\n * seconds after a deploy) versus ABANDONED as genuinely failing (application\n * error — re-running yields the same failure). A genuine application error\n * carries none of these signals, so it is never misclassified by this check.\n */\nexport function isPlatformTransientError(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    const message = errorMessageOf(e);\n    if (SUPERSEDED_ISOLATE_PATTERN.test(message)) return true;\n    if (CONNECTION_LOST_PATTERN.test(message)) return true;\n    if (STORAGE_RESET_PATTERN.test(message)) return true;\n    if (isErrorRetryable(e)) return true;\n  }\n  return false;\n}\n"],"mappings":"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"}
+{"version":3,"file":"retries.js","names":[],"sources":["../src/retries.ts"],"sourcesContent":["/**\n * Retry options for schedule(), scheduleEvery(), queue(), and this.retry().\n */\nexport interface RetryOptions {\n  /** Max number of attempts (including the first). Default: 3 */\n  maxAttempts?: number;\n  /** Base delay in ms for exponential backoff. Default: 100 */\n  baseDelayMs?: number;\n  /** Max delay cap in ms. Default: 3000 */\n  maxDelayMs?: number;\n}\n\n/**\n * Internal options for tryN -- extends RetryOptions with a shouldRetry predicate.\n */\ninterface TryNOptions extends RetryOptions {\n  /**\n   * Predicate to determine if an error should be retried.\n   * Receives the error and the next attempt number (so callers can\n   * make attempt-aware decisions).\n   * If not provided, all errors are retried.\n   */\n  shouldRetry?: (err: unknown, nextAttempt: number) => boolean;\n}\n\n/**\n * Validate retry options eagerly so invalid config fails at enqueue/schedule time\n * rather than at execution time. Checks individual field ranges, enforces integer\n * maxAttempts, and validates cross-field constraints after resolving against\n * defaults when provided.\n */\nexport function validateRetryOptions(\n  options: RetryOptions,\n  defaults?: Required<RetryOptions>\n): void {\n  if (options.maxAttempts !== undefined) {\n    if (!Number.isFinite(options.maxAttempts) || options.maxAttempts < 1) {\n      throw new Error(\"retry.maxAttempts must be >= 1\");\n    }\n    if (!Number.isInteger(options.maxAttempts)) {\n      throw new Error(\"retry.maxAttempts must be an integer\");\n    }\n  }\n  if (options.baseDelayMs !== undefined) {\n    if (!Number.isFinite(options.baseDelayMs) || options.baseDelayMs <= 0) {\n      throw new Error(\"retry.baseDelayMs must be > 0\");\n    }\n  }\n  if (options.maxDelayMs !== undefined) {\n    if (!Number.isFinite(options.maxDelayMs) || options.maxDelayMs <= 0) {\n      throw new Error(\"retry.maxDelayMs must be > 0\");\n    }\n  }\n\n  // Resolve against defaults (when provided) so that cross-field checks\n  // catch e.g. { baseDelayMs: 5000 } against default maxDelayMs: 3000.\n  const resolvedBase = options.baseDelayMs ?? defaults?.baseDelayMs;\n  const resolvedMax = options.maxDelayMs ?? defaults?.maxDelayMs;\n  if (\n    resolvedBase !== undefined &&\n    resolvedMax !== undefined &&\n    resolvedBase > resolvedMax\n  ) {\n    throw new Error(\"retry.baseDelayMs must be <= retry.maxDelayMs\");\n  }\n}\n\n/**\n * Returns the number of milliseconds to wait before retrying a request.\n * Uses the \"Full Jitter\" approach from\n * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/\n *\n * @param attempt The current attempt number (1-indexed).\n * @param baseDelayMs Base delay multiplier in ms.\n * @param maxDelayMs Maximum delay cap in ms.\n * @returns Milliseconds to wait before retrying.\n */\nexport function jitterBackoff(\n  attempt: number,\n  baseDelayMs: number,\n  maxDelayMs: number\n): number {\n  const upperBoundMs = Math.min(2 ** attempt * baseDelayMs, maxDelayMs);\n  return Math.floor(Math.random() * upperBoundMs);\n}\n\n/**\n * Retry an async function up to `n` total attempts with jittered exponential backoff.\n *\n * @param n Total number of attempts (must be a finite integer >= 1).\n * @param fn The async function to retry. Receives the current attempt number (1-indexed).\n * @param options Retry configuration.\n * @returns The result of `fn` on success.\n * @throws The last error if all attempts fail or `shouldRetry` returns false.\n */\nexport async function tryN<T>(\n  n: number,\n  fn: (attempt: number) => Promise<T>,\n  options?: TryNOptions\n): Promise<T> {\n  if (!Number.isFinite(n) || n < 1) {\n    throw new Error(\"retry.maxAttempts must be >= 1\");\n  }\n  n = Math.floor(n);\n\n  const rawBase = options?.baseDelayMs ?? 100;\n  const rawMax = options?.maxDelayMs ?? 3000;\n\n  if (!Number.isFinite(rawBase) || rawBase <= 0) {\n    throw new Error(\"retry.baseDelayMs must be > 0\");\n  }\n  if (!Number.isFinite(rawMax) || rawMax <= 0) {\n    throw new Error(\"retry.maxDelayMs must be > 0\");\n  }\n\n  const baseDelayMs = Math.floor(rawBase);\n  const maxDelayMs = Math.floor(rawMax);\n\n  if (baseDelayMs > maxDelayMs) {\n    throw new Error(\"retry.baseDelayMs must be <= retry.maxDelayMs\");\n  }\n\n  let attempt = 1;\n  while (true) {\n    try {\n      return await fn(attempt);\n    } catch (err) {\n      const nextAttempt = attempt + 1;\n      if (\n        nextAttempt > n ||\n        (options?.shouldRetry && !options.shouldRetry(err, nextAttempt))\n      ) {\n        throw err;\n      }\n      const delay = jitterBackoff(attempt, baseDelayMs, maxDelayMs);\n      await new Promise((resolve) => setTimeout(resolve, delay));\n      attempt = nextAttempt;\n    }\n  }\n}\n\n/**\n * Returns true if the given error is retryable according to Durable Object error handling.\n * See https://developers.cloudflare.com/durable-objects/best-practices/error-handling/\n *\n * An error is retryable if it has `retryable: true` but is NOT an overloaded error.\n */\nexport function isErrorRetryable(err: unknown): boolean {\n  if (typeof err !== \"object\" || err === null) {\n    return false;\n  }\n  const msg = String(err);\n  const typed = err as { retryable?: boolean; overloaded?: boolean };\n  return (\n    Boolean(typed.retryable) &&\n    !typed.overloaded &&\n    !msg.includes(\"Durable Object is overloaded\")\n  );\n}\n\n/**\n * The \"superseded isolate\" platform messages — the invocation is running on an\n * isolate the platform has replaced with a new version (a deploy / code\n * update). For the rest of that invocation every operation throws the same\n * error (code never reloads mid-invocation), so in-process retries are futile;\n * but the next fresh invocation runs the new code and succeeds.\n *\n * workerd surfaces this as a plain `Error` with one of a few messages, all the\n * same failure class — a message match is the only signal:\n *   - \"Durable Object reset because its code was updated.\"  (DO storage op on a\n *     superseded isolate / deploy bounce)\n *   - \"This script has been upgraded. Please send a new request to connect to\n *     the new version.\"  (a stub/connection to a superseded script; the message\n *     literally instructs the caller to retry on the new version)\n *\n * The match stays close to the verbatim platform strings (rather than a loose\n * \"upgraded\"/\"reset\" substring) so an ordinary application error that happens\n * to mention those words is NOT misclassified as a supersede.\n */\nconst SUPERSEDED_ISOLATE_PATTERN =\n  /reset because its code was updated|this script has been upgraded/i;\n\n/**\n * The \"Network connection lost.\" platform transient — the connection between\n * the isolate and its storage (or another DO) dropped. Unlike a supersede this\n * MAY succeed on an in-process retry (a momentary blip), so it must not skip\n * the in-process retry budget — but during a deploy-reset window it never\n * succeeds in-process and surfaces interleaved with the supersede messages\n * (SQL ops throw `SqlError: SQL query failed: Network connection lost.` while\n * KV ops throw the reset message), so on retry exhaustion it must be treated\n * as the platform's failure, not the callback's.\n */\nconst CONNECTION_LOST_PATTERN = /network connection lost/i;\n\n/**\n * The exact Durable Object storage-reset platform signal. Keep this narrow:\n * ordinary SQL and generic internal errors are application failures. This is a\n * transient storage reset, not a memory-limit poison pill.\n */\nconst STORAGE_RESET_PATTERN =\n  /Internal error in Durable Object storage caused object to be reset/i;\n\n/**\n * The Durable Object memory-limit reset — the isolate exceeded its 128 MB limit\n * and was reset by the platform (workerd surfaces this verbatim as\n * \"Durable Object's isolate exceeded its memory limit and was reset.\"; the D1\n * sibling is \"D1 DB's isolate exceeded its memory limit and was reset.\").\n *\n * The match is the broad shared fragment \"exceeded its memory limit\" rather than\n * the full \"...and was reset\" sentence: real-world surfacings truncate or reword\n * the tail (some log pipelines clip the message; D1/storage wrappers re-prefix\n * it), and a customer-reported loop (#1825) showed lines carrying only the\n * \"exceeded its memory limit\" fragment. Missing a surfacing here means the\n * circuit breaker never engages, so we err toward the broader match — and even a\n * false positive is fail-safe (a tightly-bounded retry-then-seal, not data loss).\n *\n * This is DELIBERATELY a separate class from `SUPERSEDED_ISOLATE_PATTERN` /\n * {@link isPlatformTransientError}, and is NOT folded into them. A supersede or\n * connection-lost transient means \"re-run the same work and it succeeds on a\n * healthy isolate\" — those classes can be deferred and retried *indefinitely*. A\n * memory-limit reset is the opposite: re-running the SAME memory-heavy work\n * deterministically re-OOMs (the footprint, not the platform, is the cause), so\n * deferring it indefinitely would PRESERVE the one-shot row and re-run the\n * doomed work forever (amplifying the loop and cost — see #1825). It is a\n * poison-pill signal: callers must bound retries tightly and then SEAL.\n *\n * Accordingly the schedule executor (`_executeScheduleCallback`) and the\n * alarm-boundary circuit breaker (`Agent.alarm`) treat it as its OWN class: a\n * memory-limit reset is re-thrown (row preserved) so it reaches the breaker,\n * which tolerates a few strikes (`maxAlarmMemoryLimitStrikes`) and then seals +\n * purges the looping row — i.e. *bounded* deferral, never the unbounded deferral\n * the transient classes get.\n */\nconst MEMORY_LIMIT_RESET_PATTERN = /exceeded its memory limit/i;\n\nfunction errorMessageOf(error: unknown): string {\n  return error instanceof Error\n    ? error.message\n    : typeof error === \"string\"\n      ? error\n      : \"\";\n}\n\n/**\n * Iterate an error and its `cause` chain (depth-limited so a cyclic chain\n * can't spin). Wrappers like `SqlError` carry the original platform error in\n * `cause` and may not propagate signal properties (e.g. the CF `retryable`\n * flag), so classification must look through them.\n */\nfunction* selfAndCauses(error: unknown): Generator<unknown> {\n  let current = error;\n  for (let depth = 0; depth < 8 && current != null; depth++) {\n    yield current;\n    current =\n      typeof current === \"object\"\n        ? (current as { cause?: unknown }).cause\n        : undefined;\n  }\n}\n\n/**\n * Whether an error (or anything in its `cause` chain) is a transient\n * \"superseded isolate\" failure — see `SUPERSEDED_ISOLATE_PATTERN`. In-process\n * retries are futile for this class; the work must be deferred to a fresh\n * invocation, which runs the new code and succeeds.\n */\nexport function isDurableObjectCodeUpdateReset(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    if (SUPERSEDED_ISOLATE_PATTERN.test(errorMessageOf(e))) return true;\n  }\n  return false;\n}\n\n/**\n * Whether an error (or anything in its `cause` chain) carries the exact\n * Durable Object storage-reset platform fragment. Generic SQL/internal errors\n * deliberately do not qualify.\n */\nexport function isDurableObjectStorageReset(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    if (STORAGE_RESET_PATTERN.test(errorMessageOf(e))) return true;\n  }\n  return false;\n}\n\n/**\n * Whether an error (or anything in its `cause` chain, or a raw error-message\n * string) is a Durable Object memory-limit reset — see\n * {@link MEMORY_LIMIT_RESET_PATTERN}. Unlike {@link isPlatformTransientError},\n * re-running the same work re-OOMs deterministically, so callers must NOT defer\n * it like a transient; they should bound retries tightly and then seal (#1825).\n */\nexport function isDurableObjectMemoryLimitReset(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    if (MEMORY_LIMIT_RESET_PATTERN.test(errorMessageOf(e))) return true;\n  }\n  return false;\n}\n\n/**\n * Whether an error (or anything in its `cause` chain) is a transient failure\n * of the PLATFORM rather than of the code that threw it:\n *\n *   - a superseded-isolate reset (\"reset because its code was updated\" /\n *     \"this script has been upgraded\") — a deploy replaced the isolate;\n *   - an error the platform itself flags `retryable: true` (excluding\n *     overloaded errors, where retrying the same object won't help) — see\n *     `isErrorRetryable`;\n *   - \"Network connection lost.\" — the storage/stub connection dropped. The\n *     CF `retryable` flag does not survive error wrappers (e.g. `SqlError`\n *     copies only the message + `cause`) and is absent in some local-dev\n *     shapes, so the verbatim message is matched as well;\n *   - the exact \"Internal error in Durable Object storage caused object to be\n *     reset\" platform fragment. Generic internal and SQL errors remain fatal.\n *\n * Used to decide whether failed work should be RE-RUN LATER (platform\n * transient — the same work succeeds once the platform recovers, typically\n * seconds after a deploy) versus ABANDONED as genuinely failing (application\n * error — re-running yields the same failure). A genuine application error\n * carries none of these signals, so it is never misclassified by this check.\n */\n/**\n * Whether a failure is the PLATFORM's rather than the application's — any\n * platform transient (see {@link isPlatformTransientError}, which includes\n * superseded-isolate resets) or a memory-limit reset. Failed work in this\n * class must be PRESERVED and deferred, never completed as an application\n * failure. The two sub-classes defer differently: transients re-run\n * indefinitely (the platform recovers), while memory-limit deferral is\n * bounded by the alarm circuit breaker (#1825).\n */\nexport function isPlatformFailure(error: unknown): boolean {\n  return (\n    isPlatformTransientError(error) || isDurableObjectMemoryLimitReset(error)\n  );\n}\n\nexport function isPlatformTransientError(error: unknown): boolean {\n  for (const e of selfAndCauses(error)) {\n    const message = errorMessageOf(e);\n    if (SUPERSEDED_ISOLATE_PATTERN.test(message)) return true;\n    if (CONNECTION_LOST_PATTERN.test(message)) return true;\n    if (STORAGE_RESET_PATTERN.test(message)) return true;\n    if (isErrorRetryable(e)) return true;\n  }\n  return false;\n}\n"],"mappings":"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"}

package/dist/routing/index.d.ts

@@ -0,0 +1,137 @@
+import {
+  r as CapabilityWebSocketUpgradeContext,
+  s as LifecycleCapability,
+  t as CapabilityRequestContext
+} from "../capability-runner-Be_-PLR1.js";
+import {
+  a as routeAgentRequest,
+  c as Agent,
+  i as getAgentByName,
+  n as AgentOptions,
+  r as RoutingRetryOptions,
+  t as AgentGetOptions
+} from "../agent-routing-DE5zmCQ8.js";
+
+//#region src/routing/routed-agents.d.ts
+/** A public entry in an {@link RoutedAgents}. */
+type RoutedAgentEntry<Metadata = unknown> = {
+  /** Stable application-facing identifier used in routes. */ readonly id: string /** Application-owned metadata stored with the entry. */;
+  readonly metadata: Metadata | null /** Creation time, as Unix milliseconds. */;
+  readonly createdAt: number /** Time the entry or its metadata last changed, as Unix milliseconds. */;
+  readonly updatedAt: number;
+};
+/** Options for creating an entry in an {@link RoutedAgents}. */
+type RoutedAgentCreateOptions<Metadata = unknown> = {
+  /** Initial application-owned metadata. */ readonly metadata?: Metadata;
+};
+/** Configuration for an {@link RoutedAgents}. */
+type RoutedAgentsOptions<TAgent extends Agent> = {
+  /** Top-level Durable Object namespace the entries are created in. */ readonly namespace: DurableObjectNamespace<TAgent> /** One URL-safe path segment under the owning Durable Object. */;
+  readonly route: string;
+};
+/**
+ * A durable, routed collection of independent top-level Agents.
+ *
+ * Install this on the owning Durable Object, typically a per-user hub. It
+ * maps public entry IDs to opaque physical Agent names, handles catalog
+ * CRUD without waking any target, and forwards matching HTTP requests and
+ * WebSocket upgrades to the selected Agent. After an upgrade the target
+ * owns the socket, so ordinary frames never wake the owner. The target
+ * Agent needs no matching capability. Destroying the owner condemns every
+ * remaining entry with a few retries so targets don't casually outlive
+ * their catalog — this is best-effort, not a durability guarantee; see
+ * {@link RoutedAgents.dispose}.
+ *
+ * Pick a `route` that cannot appear as a literal path segment elsewhere
+ * under the owner (its own name, another route, or a path the owner's own
+ * `onRequest` handles) — forwarding matches every occurrence of the route
+ * segment in the path, so a coincidental match with no active entry
+ * behind it is answered `404` instead of reaching the owner.
+ *
+ * A forwarded suffix is not searched for a `/sub/{class}/{name}` dynamic
+ * agents marker: `Agent.fetch()` resolves that marker against the OWNER's
+ * exported classes before this capability's `onRequest` ever runs, so a
+ * matching marker is served as a facet of the owner, not forwarded to the
+ * target. Address a target's own dynamic agents through a direct
+ * connection to that target, not through the owner's route.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class RoutedAgents<
+  TAgent extends Agent = Agent,
+  Metadata = unknown
+> extends LifecycleCapability {
+  #private;
+  /**
+   * @param options - Target binding and the route segment this capability
+   * claims. Install with `this.lifecycle.use()` before startup.
+   */
+  constructor(options: RoutedAgentsOptions<TAgent>);
+  /** Create an entry without waking the target Agent. */
+  create(
+    options?: RoutedAgentCreateOptions<Metadata>
+  ): Promise<RoutedAgentEntry<Metadata>>;
+  /** Resolve an active entry to an initialized, typed Agent stub. */
+  get(id: string): Promise<DurableObjectStub<TAgent> | null>;
+  /**
+   * List active entries, most recently updated first. Entries whose
+   * `updatedAt` ties are ordered by actual write order, not by the
+   * random entry `id`.
+   */
+  list(): Promise<ReadonlyArray<RoutedAgentEntry<Metadata>>>;
+  /** Replace an active entry's metadata. Returns false for unknown IDs. */
+  setMetadata(id: string, metadata: Metadata | null): Promise<boolean>;
+  /**
+   * Make an entry unreachable, condemn its Agent, then remove the row.
+   * Returns false for unknown IDs.
+   *
+   * The target is condemned through Agent's deferred teardown, which
+   * durably marks it and returns without aborting the isolate; its storage
+   * is wiped on its own next wake, moments later, and the marker survives
+   * interruption. A failed RPC leaves a hidden `deleting` row so a
+   * repeated call retries.
+   */
+  delete(id: string): Promise<boolean>;
+  onStart(): void;
+  /**
+   * Condemn every remaining entry (including one already `deleting`, in
+   * case its own condemnation RPC never landed) when the owner itself is
+   * destroyed.
+   *
+   * `Agent.destroy()` disposes capabilities before it wipes its own
+   * storage, so the catalog is still readable here — without this, the
+   * catalog would vanish with the owner while every target it named kept
+   * running and billing storage, unreachable forever.
+   *
+   * This is best-effort, not a durability guarantee: `Agent.destroy()`
+   * wipes the owner's storage immediately after disposal regardless of
+   * whether any capability's `dispose()` reports failure, so a target
+   * that is still unreachable after retries here is orphaned for good —
+   * there is no later "repeated call retries" for a catalog row that no
+   * longer exists. Retrying briefly here converts the common transient
+   * failure into a condemned target instead of an orphan; it cannot
+   * convert a target that is durably unreachable.
+   */
+  dispose(): Promise<void>;
+  /** Forward a matching HTTP request to the selected Agent. */
+  onRequest({
+    request
+  }: CapabilityRequestContext): Promise<Response | undefined>;
+  /** Forward a matching upgrade so the selected Agent owns the WebSocket. */
+  onWebSocketUpgrade({
+    request
+  }: CapabilityWebSocketUpgradeContext): Promise<Response | undefined>;
+}
+//#endregion
+export {
+  type AgentGetOptions,
+  type AgentOptions,
+  type RoutedAgentCreateOptions,
+  type RoutedAgentEntry,
+  RoutedAgents,
+  type RoutedAgentsOptions,
+  type RoutingRetryOptions,
+  getAgentByName,
+  routeAgentRequest
+};
+//# sourceMappingURL=index.d.ts.map