agents 0.5.1 → 0.7.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { camelCaseToKebabCase } from "./utils.js";
 import { createHeaderBasedEmailResolver, signAgentHeaders } from "./email.js";
 import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
 import { isErrorRetryable, tryN, validateRetryOptions } from "./retries.js";
-import { i as DisposableStore, n as MCPConnectionState } from "./client-connection-CGMuV62J.js";
+import { a as RPC_DO_PREFIX, n as MCPConnectionState, s as DisposableStore } from "./client-connection-D3Wcd6Q6.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider.js";
 import { MCPClientManager } from "./mcp/client.js";
 import { genericObservability } from "./observability/index.js";
@@ -66,6 +66,7 @@ const unstable_callable = (metadata = {}) => {
 function getNextCronTime(cron) {
 	return parseCronExpression(cron).getNextDate();
 }
+const KEEP_ALIVE_INTERVAL_MS = 3e4;
 const STATE_ROW_ID = "cf_state_row_id";
 const STATE_WAS_CHANGED = "cf_state_was_changed";
 const DEFAULT_STATE = {};
@@ -106,12 +107,31 @@ function extractInternalFlags(raw) {
 	for (const key of Object.keys(raw)) if (CF_INTERNAL_KEYS.has(key)) result[key] = raw[key];
 	return result;
 }
+/** Max length for error strings broadcast to clients. */
+const MAX_ERROR_STRING_LENGTH = 500;
+/**
+* Sanitize an error string before broadcasting to clients.
+* MCP error strings may contain untrusted content from external OAuth
+* providers — truncate and strip control characters to limit XSS risk.
+*/
+const CONTROL_CHAR_RE = /* @__PURE__ */ new RegExp("[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F]", "g");
+function sanitizeErrorString(error) {
+	if (error === null) return null;
+	let sanitized = error.replace(CONTROL_CHAR_RE, "");
+	if (sanitized.length > MAX_ERROR_STRING_LENGTH) sanitized = sanitized.substring(0, MAX_ERROR_STRING_LENGTH) + "...";
+	return sanitized;
+}
 /**
 * Tracks which agent constructors have already emitted the onStateUpdate
 * deprecation warning, so it fires at most once per class.
 */
 const _onStateUpdateWarnedClasses = /* @__PURE__ */ new WeakSet();
 /**
+* Tracks which agent constructors have already emitted the
+* sendIdentityOnConnect deprecation warning, so it fires at most once per class.
+*/
+const _sendIdentityWarnedClasses = /* @__PURE__ */ new WeakSet();
+/**
 * Default options for Agent configuration.
 * Child classes can override specific options without spreading.
 */
@@ -234,6 +254,17 @@ var Agent = class Agent extends Server {
 		return this._cachedOptions;
 	}
 	/**
+	* Emit an observability event with auto-generated timestamp.
+	* @internal
+	*/
+	_emit(type, payload = {}) {
+		this.observability?.emit({
+			type,
+			payload,
+			timestamp: Date.now()
+		});
+	}
+	/**
 	* Execute SQL queries against the Agent's database
 	* @template T Type of the returned rows
 	* @param strings SQL query template strings
@@ -246,7 +277,7 @@ var Agent = class Agent extends Server {
 			query = strings.reduce((acc, str, i) => acc + str + (i < values.length ? "?" : ""), "");
 			return [...this.ctx.storage.sql.exec(query, ...values)];
 		} catch (e) {
-			throw this.onError(new SqlError(query, e));
+			throw new SqlError(query, e);
 		}
 	}
 	constructor(ctx, env) {
@@ -291,29 +322,17 @@ var Agent = class Agent extends Server {
 					const { maxAttempts, baseDelayMs, maxDelayMs } = resolveRetryConfig(parseRetryOptions(row), this._resolvedOptions.retry);
 					const parsedPayload = JSON.parse(row.payload);
 					try {
-						this.observability?.emit({
-							displayMessage: `Schedule ${row.id} executed`,
-							id: nanoid(),
-							payload: {
-								callback: row.callback,
-								id: row.id
-							},
-							timestamp: Date.now(),
-							type: "schedule:execute"
-						}, this.ctx);
+						this._emit("schedule:execute", {
+							callback: row.callback,
+							id: row.id
+						});
 						await tryN(maxAttempts, async (attempt) => {
-							if (attempt > 1) this.observability?.emit({
-								displayMessage: `Retrying schedule callback "${row.callback}" (attempt ${attempt}/${maxAttempts})`,
-								id: nanoid(),
-								payload: {
-									callback: row.callback,
-									id: row.id,
-									attempt,
-									maxAttempts
-								},
-								timestamp: Date.now(),
-								type: "schedule:retry"
-							}, this.ctx);
+							if (attempt > 1) this._emit("schedule:retry", {
+								callback: row.callback,
+								id: row.id,
+								attempt,
+								maxAttempts
+							});
 							await callback.bind(this)(parsedPayload, row);
 						}, {
 							baseDelayMs,
@@ -321,6 +340,12 @@ var Agent = class Agent extends Server {
 						});
 					} catch (e) {
 						console.error(`error executing callback "${row.callback}" after ${maxAttempts} attempts`, e);
+						this._emit("schedule:error", {
+							callback: row.callback,
+							id: row.id,
+							error: e instanceof Error ? e.message : String(e),
+							attempts: maxAttempts
+						});
 						try {
 							await this.onError(e);
 						} catch {}
@@ -509,35 +534,27 @@ var Agent = class Agent extends Server {
 						const metadata = callableMetadata.get(methodFn);
 						if (metadata?.streaming) {
 							const stream = new StreamingResponse(connection, id);
-							this.observability?.emit({
-								displayMessage: `RPC streaming call to ${method}`,
-								id: nanoid(),
-								payload: {
-									method,
-									streaming: true
-								},
-								timestamp: Date.now(),
-								type: "rpc"
-							}, this.ctx);
+							this._emit("rpc", {
+								method,
+								streaming: true
+							});
 							try {
 								await methodFn.apply(this, [stream, ...args]);
 							} catch (err) {
 								console.error(`Error in streaming method "${method}":`, err);
+								this._emit("rpc:error", {
+									method,
+									error: err instanceof Error ? err.message : String(err)
+								});
 								if (!stream.isClosed) stream.error(err instanceof Error ? err.message : String(err));
 							}
 							return;
 						}
 						const result = await methodFn.apply(this, args);
-						this.observability?.emit({
-							displayMessage: `RPC call to ${method}`,
-							id: nanoid(),
-							payload: {
-								method,
-								streaming: metadata?.streaming
-							},
-							timestamp: Date.now(),
-							type: "rpc"
-						}, this.ctx);
+						this._emit("rpc", {
+							method,
+							streaming: metadata?.streaming
+						});
 						const response = {
 							done: true,
 							id,
@@ -555,6 +572,10 @@ var Agent = class Agent extends Server {
 						};
 						connection.send(JSON.stringify(response));
 						console.error("RPC error:", e);
+						this._emit("rpc:error", {
+							method: parsed.method,
+							error: e instanceof Error ? e.message : String(e)
+						});
 					}
 					return;
 				}
@@ -572,11 +593,20 @@ var Agent = class Agent extends Server {
 			}, async () => {
 				if (this.shouldConnectionBeReadonly(connection, ctx)) this.setConnectionReadonly(connection, true);
 				if (this.shouldSendProtocolMessages(connection, ctx)) {
-					if (this._resolvedOptions.sendIdentityOnConnect) connection.send(JSON.stringify({
-						name: this.name,
-						agent: camelCaseToKebabCase(this._ParentClass.name),
-						type: MessageType.CF_AGENT_IDENTITY
-					}));
+					if (this._resolvedOptions.sendIdentityOnConnect) {
+						const ctor = this.constructor;
+						if (ctor.options?.sendIdentityOnConnect === void 0 && !_sendIdentityWarnedClasses.has(ctor)) {
+							if (!new URL(ctx.request.url).pathname.includes(this.name)) {
+								_sendIdentityWarnedClasses.add(ctor);
+								console.warn(`[Agent] ${ctor.name}: sending instance name "${this.name}" to clients via sendIdentityOnConnect (the name is not visible in the URL with custom routing). If this name is sensitive, add \`static options = { sendIdentityOnConnect: false }\` to opt out. Set it to true to silence this message.`);
+							}
+						}
+						connection.send(JSON.stringify({
+							name: this.name,
+							agent: camelCaseToKebabCase(this._ParentClass.name),
+							type: MessageType.CF_AGENT_IDENTITY
+						}));
+					}
 					if (this.state) connection.send(JSON.stringify({
 						state: this.state,
 						type: MessageType.CF_AGENT_STATE
@@ -586,13 +616,7 @@ var Agent = class Agent extends Server {
 						type: MessageType.CF_AGENT_MCP_SERVERS
 					}));
 				} else this._setConnectionNoProtocol(connection);
-				this.observability?.emit({
-					displayMessage: "Connection established",
-					id: nanoid(),
-					payload: { connectionId: connection.id },
-					timestamp: Date.now(),
-					type: "connect"
-				}, this.ctx);
+				this._emit("connect", { connectionId: connection.id });
 				return this._tryCatch(() => _onConnect(connection, ctx));
 			});
 		};
@@ -606,6 +630,7 @@ var Agent = class Agent extends Server {
 			}, async () => {
 				await this._tryCatch(async () => {
 					await this.mcp.restoreConnectionsFromStorage(this.name);
+					await this._restoreRpcMcpServers();
 					this.broadcastMcpServers();
 					this._checkOrphanedWorkflows();
 					return _onStart(props);
@@ -671,13 +696,7 @@ var Agent = class Agent extends Server {
 					request,
 					email
 				}, async () => {
-					this.observability?.emit({
-						displayMessage: "State updated",
-						id: nanoid(),
-						payload: {},
-						timestamp: Date.now(),
-						type: "state:update"
-					}, this.ctx);
+					this._emit("state:update");
 					await this._callStatePersistenceHook(nextState, source);
 				});
 			} catch (e) {
@@ -1079,18 +1098,12 @@ var Agent = class Agent extends Server {
 						const parsedPayload = JSON.parse(row.payload);
 						try {
 							await tryN(maxAttempts, async (attempt) => {
-								if (attempt > 1) this.observability?.emit({
-									displayMessage: `Retrying queue callback "${row.callback}" (attempt ${attempt}/${maxAttempts})`,
-									id: nanoid(),
-									payload: {
-										callback: row.callback,
-										id: row.id,
-										attempt,
-										maxAttempts
-									},
-									timestamp: Date.now(),
-									type: "queue:retry"
-								}, this.ctx);
+								if (attempt > 1) this._emit("queue:retry", {
+									callback: row.callback,
+									id: row.id,
+									attempt,
+									maxAttempts
+								});
 								await callback.bind(this)(parsedPayload, row);
 							}, {
 								baseDelayMs,
@@ -1098,11 +1111,17 @@ var Agent = class Agent extends Server {
 							});
 						} catch (e) {
 							console.error(`queue callback "${row.callback}" failed after ${maxAttempts} attempts`, e);
+							this._emit("queue:error", {
+								callback: row.callback,
+								id: row.id,
+								error: e instanceof Error ? e.message : String(e),
+								attempts: maxAttempts
+							});
 							try {
 								await this.onError(e);
 							} catch {}
 						} finally {
-							await this.dequeue(row.id);
+							this.dequeue(row.id);
 						}
 					});
 				}
@@ -1177,16 +1196,10 @@ var Agent = class Agent extends Server {
 		const id = nanoid(9);
 		if (options?.retry) validateRetryOptions(options.retry, this._resolvedOptions.retry);
 		const retryJson = options?.retry ? JSON.stringify(options.retry) : null;
-		const emitScheduleCreate = (schedule) => this.observability?.emit({
-			displayMessage: `Schedule ${schedule.id} created`,
-			id: nanoid(),
-			payload: {
-				callback,
-				id
-			},
-			timestamp: Date.now(),
-			type: "schedule:create"
-		}, this.ctx);
+		const emitScheduleCreate = () => this._emit("schedule:create", {
+			callback,
+			id
+		});
 		if (typeof callback !== "string") throw new Error("Callback must be a string");
 		if (typeof this[callback] !== "function") throw new Error(`this.${callback} is not a function`);
 		if (when instanceof Date) {
@@ -1204,7 +1217,7 @@ var Agent = class Agent extends Server {
 				time: timestamp,
 				type: "scheduled"
 			};
-			emitScheduleCreate(schedule);
+			emitScheduleCreate();
 			return schedule;
 		}
 		if (typeof when === "number") {
@@ -1224,7 +1237,7 @@ var Agent = class Agent extends Server {
 				time: timestamp,
 				type: "delayed"
 			};
-			emitScheduleCreate(schedule);
+			emitScheduleCreate();
 			return schedule;
 		}
 		if (typeof when === "string") {
@@ -1244,7 +1257,7 @@ var Agent = class Agent extends Server {
 				time: timestamp,
 				type: "cron"
 			};
-			emitScheduleCreate(schedule);
+			emitScheduleCreate();
 			return schedule;
 		}
 		throw new Error(`Invalid schedule type: ${JSON.stringify(when)}(${typeof when}) trying to schedule ${callback}`);
@@ -1284,16 +1297,10 @@ var Agent = class Agent extends Server {
 			time: timestamp,
 			type: "interval"
 		};
-		this.observability?.emit({
-			displayMessage: `Schedule ${schedule.id} created`,
-			id: nanoid(),
-			payload: {
-				callback,
-				id
-			},
-			timestamp: Date.now(),
-			type: "schedule:create"
-		}, this.ctx);
+		this._emit("schedule:create", {
+			callback,
+			id
+		});
 		return schedule;
 	}
 	/**
@@ -1351,20 +1358,77 @@ var Agent = class Agent extends Server {
 	async cancelSchedule(id) {
 		const schedule = this.getSchedule(id);
 		if (!schedule) return false;
-		this.observability?.emit({
-			displayMessage: `Schedule ${id} cancelled`,
-			id: nanoid(),
-			payload: {
-				callback: schedule.callback,
-				id: schedule.id
-			},
-			timestamp: Date.now(),
-			type: "schedule:cancel"
-		}, this.ctx);
+		this._emit("schedule:cancel", {
+			callback: schedule.callback,
+			id: schedule.id
+		});
 		this.sql`DELETE FROM cf_agents_schedules WHERE id = ${id}`;
 		await this._scheduleNextAlarm();
 		return true;
 	}
+	/**
+	* Keep the Durable Object alive via alarm heartbeats.
+	* Returns a disposer function that stops the heartbeat when called.
+	*
+	* Use this when you have long-running work and need to prevent the
+	* DO from going idle (eviction after ~70-140s of inactivity).
+	* The heartbeat fires every 30 seconds via the scheduling system.
+	*
+	* @experimental This API may change between releases.
+	*
+	* @example
+	* ```ts
+	* const dispose = await this.keepAlive();
+	* try {
+	*   // ... long-running work ...
+	* } finally {
+	*   dispose();
+	* }
+	* ```
+	*/
+	async keepAlive() {
+		const heartbeatSeconds = Math.ceil(KEEP_ALIVE_INTERVAL_MS / 1e3);
+		const schedule = await this.scheduleEvery(heartbeatSeconds, "_cf_keepAliveHeartbeat");
+		let disposed = false;
+		return () => {
+			if (disposed) return;
+			disposed = true;
+			this.cancelSchedule(schedule.id);
+		};
+	}
+	/**
+	* Run an async function while keeping the Durable Object alive.
+	* The heartbeat is automatically stopped when the function completes
+	* (whether it succeeds or throws).
+	*
+	* This is the recommended way to use keepAlive — it guarantees cleanup
+	* so you cannot forget to dispose the heartbeat.
+	*
+	* @experimental This API may change between releases.
+	*
+	* @example
+	* ```ts
+	* const result = await this.keepAliveWhile(async () => {
+	*   const data = await longRunningComputation();
+	*   return data;
+	* });
+	* ```
+	*/
+	async keepAliveWhile(fn) {
+		const dispose = await this.keepAlive();
+		try {
+			return await fn();
+		} finally {
+			dispose();
+		}
+	}
+	/**
+	* Internal no-op callback invoked by the keepAlive heartbeat schedule.
+	* Its only purpose is to keep the DO alive — the alarm machinery
+	* handles the rest.
+	* @internal
+	*/
+	async _cf_keepAliveHeartbeat() {}
 	async _scheduleNextAlarm() {
 		const result = this.sql`
       SELECT time FROM cf_agents_schedules
@@ -1395,13 +1459,7 @@ var Agent = class Agent extends Server {
 		setTimeout(() => {
 			this.ctx.abort("destroyed");
 		}, 0);
-		this.observability?.emit({
-			displayMessage: "Agent destroyed",
-			id: nanoid(),
-			payload: {},
-			timestamp: Date.now(),
-			type: "destroy"
-		}, this.ctx);
+		this._emit("destroy");
 	}
 	/**
 	* Check if a method is callable
@@ -1481,16 +1539,10 @@ var Agent = class Agent extends Server {
 			if (e instanceof Error && e.message.includes("UNIQUE constraint failed")) throw new Error(`Workflow with ID "${workflowId}" is already being tracked`);
 			throw e;
 		}
-		this.observability?.emit({
-			displayMessage: `Workflow ${instance.id} started`,
-			id: nanoid(),
-			payload: {
-				workflowId: instance.id,
-				workflowName
-			},
-			timestamp: Date.now(),
-			type: "workflow:start"
-		}, this.ctx);
+		this._emit("workflow:start", {
+			workflowId: instance.id,
+			workflowName
+		});
 		return instance.id;
 	}
 	/**
@@ -1519,16 +1571,10 @@ var Agent = class Agent extends Server {
 			baseDelayMs: 200,
 			maxDelayMs: 3e3
 		});
-		this.observability?.emit({
-			displayMessage: `Event sent to workflow ${workflowId}`,
-			id: nanoid(),
-			payload: {
-				workflowId,
-				eventType: event.type
-			},
-			timestamp: Date.now(),
-			type: "workflow:event"
-		}, this.ctx);
+		this._emit("workflow:event", {
+			workflowId,
+			eventType: event.type
+		});
 	}
 	/**
 	* Approve a waiting workflow.
@@ -1556,16 +1602,10 @@ var Agent = class Agent extends Server {
 				metadata: data?.metadata
 			}
 		});
-		this.observability?.emit({
-			displayMessage: `Workflow ${workflowId} approved`,
-			id: nanoid(),
-			payload: {
-				workflowId,
-				reason: data?.reason
-			},
-			timestamp: Date.now(),
-			type: "workflow:approved"
-		}, this.ctx);
+		this._emit("workflow:approved", {
+			workflowId,
+			reason: data?.reason
+		});
 	}
 	/**
 	* Reject a waiting workflow.
@@ -1591,16 +1631,10 @@ var Agent = class Agent extends Server {
 				reason: data?.reason
 			}
 		});
-		this.observability?.emit({
-			displayMessage: `Workflow ${workflowId} rejected`,
-			id: nanoid(),
-			payload: {
-				workflowId,
-				reason: data?.reason
-			},
-			timestamp: Date.now(),
-			type: "workflow:rejected"
-		}, this.ctx);
+		this._emit("workflow:rejected", {
+			workflowId,
+			reason: data?.reason
+		});
 	}
 	/**
 	* Terminate a running workflow.
@@ -1637,16 +1671,10 @@ var Agent = class Agent extends Server {
 		}
 		const status = await instance.status();
 		this._updateWorkflowTracking(workflowId, status);
-		this.observability?.emit({
-			displayMessage: `Workflow ${workflowId} terminated`,
-			id: nanoid(),
-			payload: {
-				workflowId,
-				workflowName: workflowInfo.workflowName
-			},
-			timestamp: Date.now(),
-			type: "workflow:terminated"
-		}, this.ctx);
+		this._emit("workflow:terminated", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
 	}
 	/**
 	* Pause a running workflow.
@@ -1683,16 +1711,10 @@ var Agent = class Agent extends Server {
 		}
 		const status = await instance.status();
 		this._updateWorkflowTracking(workflowId, status);
-		this.observability?.emit({
-			displayMessage: `Workflow ${workflowId} paused`,
-			id: nanoid(),
-			payload: {
-				workflowId,
-				workflowName: workflowInfo.workflowName
-			},
-			timestamp: Date.now(),
-			type: "workflow:paused"
-		}, this.ctx);
+		this._emit("workflow:paused", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
 	}
 	/**
 	* Resume a paused workflow.
@@ -1728,16 +1750,10 @@ var Agent = class Agent extends Server {
 		}
 		const status = await instance.status();
 		this._updateWorkflowTracking(workflowId, status);
-		this.observability?.emit({
-			displayMessage: `Workflow ${workflowId} resumed`,
-			id: nanoid(),
-			payload: {
-				workflowId,
-				workflowName: workflowInfo.workflowName
-			},
-			timestamp: Date.now(),
-			type: "workflow:resumed"
-		}, this.ctx);
+		this._emit("workflow:resumed", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
 	}
 	/**
 	* Restart a workflow instance.
@@ -1795,16 +1811,10 @@ var Agent = class Agent extends Server {
 			const status = await instance.status();
 			this._updateWorkflowTracking(workflowId, status);
 		}
-		this.observability?.emit({
-			displayMessage: `Workflow ${workflowId} restarted`,
-			id: nanoid(),
-			payload: {
-				workflowId,
-				workflowName: workflowInfo.workflowName
-			},
-			timestamp: Date.now(),
-			type: "workflow:restarted"
-		}, this.ctx);
+		this._emit("workflow:restarted", {
+			workflowId,
+			workflowName: workflowInfo.workflowName
+		});
 	}
 	/**
 	* Find a workflow binding by its name.
@@ -2096,6 +2106,37 @@ var Agent = class Agent extends Server {
 			if (key === className || camelCaseToKebabCase(key) === camelCaseToKebabCase(className)) return key;
 		}
 	}
+	_findBindingNameForNamespace(namespace) {
+		for (const [key, value] of Object.entries(this.env)) if (value === namespace) return key;
+	}
+	async _restoreRpcMcpServers() {
+		const rpcServers = this.mcp.getRpcServersFromStorage();
+		for (const server of rpcServers) {
+			if (this.mcp.mcpConnections[server.id]) continue;
+			const opts = server.server_options ? JSON.parse(server.server_options) : {};
+			const namespace = this.env[opts.bindingName];
+			if (!namespace) {
+				console.warn(`[Agent] Cannot restore RPC MCP server "${server.name}": binding "${opts.bindingName}" not found in env`);
+				continue;
+			}
+			const normalizedName = server.server_url.replace(RPC_DO_PREFIX, "");
+			try {
+				await this.mcp.connect(`${RPC_DO_PREFIX}${normalizedName}`, {
+					reconnect: { id: server.id },
+					transport: {
+						type: "rpc",
+						namespace,
+						name: normalizedName,
+						props: opts.props
+					}
+				});
+				const conn = this.mcp.mcpConnections[server.id];
+				if (conn && conn.connectionState === MCPConnectionState.CONNECTED) await this.mcp.discoverIfConnected(server.id);
+			} catch (error) {
+				console.error(`[Agent] Error restoring RPC MCP server "${server.name}":`, error);
+			}
+		}
+	}
 	/**
 	* Handle a callback from a workflow.
 	* Called when the Agent receives a callback at /_workflow/callback.
@@ -2202,63 +2243,87 @@ var Agent = class Agent extends Server {
 			});
 		} else if (action === "reset") this.setState(this.initialState);
 	}
-	/**
-	* Connect to a new MCP Server
-	*
-	* @example
-	* // Simple usage
-	* await this.addMcpServer("github", "https://mcp.github.com");
-	*
-	* @example
-	* // With options (preferred for custom headers, transport, etc.)
-	* await this.addMcpServer("github", "https://mcp.github.com", {
-	*   transport: { headers: { "Authorization": "Bearer ..." } }
-	* });
-	*
-	* @example
-	* // Legacy 5-parameter signature (still supported)
-	* await this.addMcpServer("github", url, callbackHost, agentsPrefix, options);
-	*
-	* @param serverName Name of the MCP server
-	* @param url MCP Server URL
-	* @param callbackHostOrOptions Options object, or callback host string (legacy)
-	* @param agentsPrefix agents routing prefix if not using `agents` (legacy)
-	* @param options MCP client and transport options (legacy)
-	* @returns Server id and state - either "authenticating" with authUrl, or "ready"
-	* @throws If connection or discovery fails
-	*/
-	async addMcpServer(serverName, url, callbackHostOrOptions, agentsPrefix, options) {
+	async addMcpServer(serverName, urlOrBinding, callbackHostOrOptions, agentsPrefix, options) {
+		const isHttpTransport = typeof urlOrBinding === "string";
+		const normalizedUrl = isHttpTransport ? new URL(urlOrBinding).href : void 0;
+		const existingServer = this.mcp.listServers().find((s) => s.name === serverName && (!isHttpTransport || new URL(s.server_url).href === normalizedUrl));
+		if (existingServer && this.mcp.mcpConnections[existingServer.id]) {
+			const conn = this.mcp.mcpConnections[existingServer.id];
+			if (conn.connectionState === MCPConnectionState.AUTHENTICATING && conn.options.transport.authProvider?.authUrl) return {
+				id: existingServer.id,
+				state: MCPConnectionState.AUTHENTICATING,
+				authUrl: conn.options.transport.authProvider.authUrl
+			};
+			if (conn.connectionState === MCPConnectionState.FAILED) throw new Error(`MCP server "${serverName}" is in failed state: ${conn.connectionError}`);
+			return {
+				id: existingServer.id,
+				state: MCPConnectionState.READY
+			};
+		}
+		if (typeof urlOrBinding !== "string") {
+			const rpcOpts = callbackHostOrOptions;
+			const normalizedName = serverName.toLowerCase().replace(/\s+/g, "-");
+			const reconnectId = existingServer?.id;
+			const { id } = await this.mcp.connect(`${RPC_DO_PREFIX}${normalizedName}`, {
+				reconnect: reconnectId ? { id: reconnectId } : void 0,
+				transport: {
+					type: "rpc",
+					namespace: urlOrBinding,
+					name: normalizedName,
+					props: rpcOpts?.props
+				}
+			});
+			const conn = this.mcp.mcpConnections[id];
+			if (conn && conn.connectionState === MCPConnectionState.CONNECTED) {
+				const discoverResult = await this.mcp.discoverIfConnected(id);
+				if (discoverResult && !discoverResult.success) throw new Error(`Failed to discover MCP server capabilities: ${discoverResult.error}`);
+			} else if (conn && conn.connectionState === MCPConnectionState.FAILED) throw new Error(`Failed to connect to MCP server "${serverName}" via RPC: ${conn.connectionError}`);
+			const bindingName = this._findBindingNameForNamespace(urlOrBinding);
+			if (bindingName) this.mcp.saveRpcServerToStorage(id, serverName, normalizedName, bindingName, rpcOpts?.props);
+			return {
+				id,
+				state: MCPConnectionState.READY
+			};
+		}
+		const httpOptions = callbackHostOrOptions;
 		let resolvedCallbackHost;
 		let resolvedAgentsPrefix;
 		let resolvedOptions;
 		let resolvedCallbackPath;
-		if (typeof callbackHostOrOptions === "object" && callbackHostOrOptions !== null) {
-			resolvedCallbackHost = callbackHostOrOptions.callbackHost;
-			resolvedCallbackPath = callbackHostOrOptions.callbackPath;
-			resolvedAgentsPrefix = callbackHostOrOptions.agentsPrefix ?? "agents";
+		if (typeof httpOptions === "object" && httpOptions !== null) {
+			resolvedCallbackHost = httpOptions.callbackHost;
+			resolvedCallbackPath = httpOptions.callbackPath;
+			resolvedAgentsPrefix = httpOptions.agentsPrefix ?? "agents";
 			resolvedOptions = {
-				client: callbackHostOrOptions.client,
-				transport: callbackHostOrOptions.transport,
-				retry: callbackHostOrOptions.retry
+				client: httpOptions.client,
+				transport: httpOptions.transport,
+				retry: httpOptions.retry
 			};
 		} else {
-			resolvedCallbackHost = callbackHostOrOptions;
+			resolvedCallbackHost = httpOptions;
 			resolvedAgentsPrefix = agentsPrefix ?? "agents";
 			resolvedOptions = options;
 		}
-		if (!this._resolvedOptions.sendIdentityOnConnect && !resolvedCallbackPath) throw new Error("callbackPath is required in addMcpServer options when sendIdentityOnConnect is false — the default callback URL would expose the instance name. Provide a callbackPath and route the callback request to this agent via getAgentByName.");
+		if (!this._resolvedOptions.sendIdentityOnConnect && resolvedCallbackHost && !resolvedCallbackPath) throw new Error("callbackPath is required in addMcpServer options when sendIdentityOnConnect is false — the default callback URL would expose the instance name. Provide a callbackPath and route the callback request to this agent via getAgentByName.");
 		if (!resolvedCallbackHost) {
 			const { request } = getCurrentAgent();
-			if (!request) throw new Error("callbackHost is required when not called within a request context");
-			const requestUrl = new URL(request.url);
-			resolvedCallbackHost = `${requestUrl.protocol}//${requestUrl.host}`;
+			if (request) {
+				const requestUrl = new URL(request.url);
+				resolvedCallbackHost = `${requestUrl.protocol}//${requestUrl.host}`;
+			}
+		}
+		let callbackUrl;
+		if (resolvedCallbackHost) {
+			const normalizedHost = resolvedCallbackHost.replace(/\/$/, "");
+			callbackUrl = resolvedCallbackPath ? `${normalizedHost}/${resolvedCallbackPath.replace(/^\//, "")}` : `${normalizedHost}/${resolvedAgentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
 		}
-		const normalizedHost = resolvedCallbackHost.replace(/\/$/, "");
-		const callbackUrl = resolvedCallbackPath ? `${normalizedHost}/${resolvedCallbackPath.replace(/^\//, "")}` : `${normalizedHost}/${resolvedAgentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
 		await this.mcp.ensureJsonSchema();
 		const id = nanoid(8);
-		const authProvider = this.createMcpOAuthProvider(callbackUrl);
-		authProvider.serverId = id;
+		let authProvider;
+		if (callbackUrl) {
+			authProvider = this.createMcpOAuthProvider(callbackUrl);
+			authProvider.serverId = id;
+		}
 		const transportType = resolvedOptions?.transport?.type ?? "auto";
 		let headerTransportOpts = {};
 		if (resolvedOptions?.transport?.headers) headerTransportOpts = {
@@ -2269,7 +2334,7 @@ var Agent = class Agent extends Server {
 			requestInit: { headers: resolvedOptions?.transport?.headers }
 		};
 		await this.mcp.registerServer(id, {
-			url,
+			url: normalizedUrl,
 			name: serverName,
 			callbackUrl,
 			client: resolvedOptions?.client,
@@ -2281,12 +2346,15 @@ var Agent = class Agent extends Server {
 			retry: resolvedOptions?.retry
 		});
 		const result = await this.mcp.connectToServer(id);
-		if (result.state === MCPConnectionState.FAILED) throw new Error(`Failed to connect to MCP server at ${url}: ${result.error}`);
-		if (result.state === MCPConnectionState.AUTHENTICATING) return {
-			id,
-			state: result.state,
-			authUrl: result.authUrl
-		};
+		if (result.state === MCPConnectionState.FAILED) throw new Error(`Failed to connect to MCP server at ${normalizedUrl}: ${result.error}`);
+		if (result.state === MCPConnectionState.AUTHENTICATING) {
+			if (!callbackUrl) throw new Error("This MCP server requires OAuth authentication. Provide callbackHost in addMcpServer options to enable the OAuth flow.");
+			return {
+				id,
+				state: result.state,
+				authUrl: result.authUrl
+			};
+		}
 		const discoverResult = await this.mcp.discoverIfConnected(id);
 		if (discoverResult && !discoverResult.success) throw new Error(`Failed to discover MCP server capabilities: ${discoverResult.error}`);
 		return {
@@ -2312,7 +2380,7 @@ var Agent = class Agent extends Server {
 			mcpState.servers[server.id] = {
 				auth_url: server.auth_url,
 				capabilities: serverConn?.serverCapabilities ?? null,
-				error: serverConn?.connectionError ?? null,
+				error: sanitizeErrorString(serverConn?.connectionError ?? null),
 				instructions: serverConn?.instructions ?? null,
 				name: server.name,
 				server_url: server.server_url,
@@ -2431,16 +2499,22 @@ async function routeAgentEmail(email, env, options) {
 	}
 	if (!agentMapCache.has(env)) {
 		const map = {};
+		const originalNames = [];
 		for (const [key, value] of Object.entries(env)) if (value && typeof value === "object" && "idFromName" in value && typeof value.idFromName === "function") {
 			map[key] = value;
 			map[camelCaseToKebabCase(key)] = value;
+			map[key.toLowerCase()] = value;
+			originalNames.push(key);
 		}
-		agentMapCache.set(env, map);
+		agentMapCache.set(env, {
+			map,
+			originalNames
+		});
 	}
-	const agentMap = agentMapCache.get(env);
-	const namespace = agentMap[routingInfo.agentName];
+	const cached = agentMapCache.get(env);
+	const namespace = cached.map[routingInfo.agentName];
 	if (!namespace) {
-		const availableAgents = Object.keys(agentMap).filter((key) => !key.includes("-")).join(", ");
+		const availableAgents = cached.originalNames.join(", ");
 		throw new Error(`Agent namespace '${routingInfo.agentName}' not found in environment. Available agents: ${availableAgents}`);
 	}
 	const agent = await getAgentByName(namespace, routingInfo.agentId);