agents 0.17.3 → 0.18.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { r as __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context-D
 import {
   $ as RoutingRetryOptions,
   A as AgentGetOptions,
+  At as MCP_SERVER_ID_MAX_LENGTH,
   B as EmailSendBinding,
   C as DetachedRunAgentToolResult,
   D as AddRpcMcpServerOptions,
@@ -16,8 +17,8 @@ import {
   L as DEFAULT_AGENT_STATIC_OPTIONS,
   M as AgentOptions,
   N as AgentStaticOptions,
+  Nt as normalizeServerId,
   O as Agent,
-  Ot as MCP_SERVER_ID_MAX_LENGTH,
   P as CallableMetadata,
   Q as RPCResponse,
   R as DeleteFibersOptions,
@@ -32,14 +33,14 @@ import {
   _ as AgentToolRunState,
   _t as MCPAITool,
   a as AgentToolEvent,
-  an as routeSubAgentRequest,
+  an as SUB_PREFIX,
   at as StartFiberResult,
   b as AgentToolTerminalStatus,
   c as AgentToolFailure,
+  cn as parseSubAgentPath,
   ct as SubAgentClass,
   d as AgentToolMilestone,
   dt as callable,
-  en as TransportType,
   et as Schedule,
   f as AgentToolProgress,
   ft as getAgentByName,
@@ -48,30 +49,29 @@ import {
   h as AgentToolRunInspection,
   ht as routeAgentRequest,
   i as AgentToolDisplayMetadata,
-  in as parseSubAgentPath,
+  in as TransportType,
   it as StartFiberOptions,
   j as AgentNamespace,
-  jt as normalizeServerId,
   k as AgentContext,
   l as AgentToolInterruptedReason,
+  ln as routeSubAgentRequest,
   lt as SubAgentStub,
   m as AgentToolRunInfo,
   mt as routeAgentEmail,
   n as AGENT_TOOL_PROGRESS_PART,
-  nn as SubAgentPathMatch,
   nt as SendEmailOptions,
   o as AgentToolEventMessage,
+  on as SubAgentPathMatch,
   ot as StateUpdateMessage,
   p as AgentToolProgressSnapshot,
   pt as getCurrentAgent,
   q as MCPServer,
   r as AgentToolChildAdapter,
-  rn as getSubAgentByName,
   rt as SqlError,
   s as AgentToolEventState,
+  sn as getSubAgentByName,
   st as StreamingResponse,
   t as AGENT_TOOL_MILESTONE_PART,
-  tn as SUB_PREFIX,
   tt as ScheduleCriteria,
   u as AgentToolLifecycleResult,
   ut as WSMessage,
@@ -81,14 +81,15 @@ import {
   x as ChatCapableAgentClass,
   y as AgentToolStoredChunk,
   z as EmailRoutingOptions
-} from "./agent-tool-types-CNyE1iz_.js";
+} from "./agent-tool-types-BNUGGBzQ.js";
 import { n as camelCaseToKebabCase } from "./utils-CGtGDSgA.js";
 import {
-  a as isPlatformTransientError,
+  i as isDurableObjectStorageReset,
   n as isDurableObjectCodeUpdateReset,
+  o as isPlatformTransientError,
   r as isDurableObjectMemoryLimitReset,
   t as RetryOptions
-} from "./retries-CvHJwSuh.js";
+} from "./retries-CAvxtG9d.js";
 import {
   n as AgentsOAuthProvider,
   r as DurableObjectOAuthClientProvider,
@@ -181,6 +182,7 @@ export {
   getSubAgentByName,
   isDurableObjectCodeUpdateReset,
   isDurableObjectMemoryLimitReset,
+  isDurableObjectStorageReset,
   isPlatformTransientError,
   normalizeServerId,
   parseSubAgentPath,

package/dist/index.js

@@ -5,10 +5,11 @@ import { camelCaseToKebabCase, isInternalJsStubProp } from "./utils.js";
 import { createHeaderBasedEmailResolver, signAgentHeaders } from "./email.js";
 import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-DZBYAB34.js";
 import { SUB_PREFIX, getSubAgentByName, parseSubAgentPath, routeSubAgentRequest } from "./sub-routing.js";
-import { isDurableObjectCodeUpdateReset, isDurableObjectMemoryLimitReset, isErrorRetryable, isPlatformTransientError, tryN, validateRetryOptions } from "./retries.js";
-import { a as MCPConnectionState, c as RPC_DO_PREFIX, i as normalizeServerId, l as DisposableStore, n as MCP_SERVER_ID_MAX_LENGTH, t as MCPClientManager } from "./client-BZ-B3NhC.js";
+import { isDurableObjectCodeUpdateReset, isDurableObjectMemoryLimitReset, isDurableObjectStorageReset, isErrorRetryable, isPlatformTransientError, tryN, validateRetryOptions } from "./retries.js";
+import { a as MCPConnectionState, c as RPC_DO_PREFIX, i as normalizeServerId, l as DisposableStore, n as MCP_SERVER_ID_MAX_LENGTH, t as MCPClientManager } from "./client-CcjiFpTf.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider.js";
 import { genericObservability } from "./observability/index.js";
+import { n as writeSpanAttributes, t as tracer } from "./cloudflare-BldFV0Pa.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { parseCronExpression } from "cron-schedule";
 import { nanoid } from "nanoid";
@@ -481,6 +482,23 @@ var Agent = class Agent extends Server {
 			timestamp: Date.now()
 		});
 	}
+	_withAgentSpan(operation, storagePhase, attributes, run) {
+		let agentId;
+		try {
+			agentId = this.name;
+		} catch {
+			agentId = void 0;
+		}
+		return tracer.withSpan(operation, {
+			"cloudflare.agents.agent.id": agentId,
+			"cloudflare.agents.agent.name": this._ParentClass.name,
+			"cloudflare.agents.operation.name": operation,
+			"cloudflare.agents.storage.grouped": true,
+			"cloudflare.agents.storage.system": "durable_object",
+			"cloudflare.agents.storage.phase": storagePhase,
+			...attributes
+		}, (span) => run((finishAttributes) => writeSpanAttributes(span, finishAttributes)));
+	}
 	/**
 	* Execute SQL queries against the Agent's database
 	* @template T Type of the returned rows
@@ -722,6 +740,11 @@ var Agent = class Agent extends Server {
         VALUES (${SCHEMA_VERSION_ROW_ID}, ${String(CURRENT_SCHEMA_VERSION)})
       `;
 		}
+		this._schemaInitialization = {
+			previousVersion: schemaVersion,
+			currentVersion: CURRENT_SCHEMA_VERSION,
+			migrated: schemaVersion < CURRENT_SCHEMA_VERSION
+		};
 	}
 	constructor(ctx, env) {
 		super(ctx, env);
@@ -753,14 +776,25 @@ var Agent = class Agent extends Server {
 		this._flushingQueue = false;
 		this.maxConcurrentAgentTools = Infinity;
 		this._subAgentRegistryReady = false;
-		if (!wrappedClasses.has(this.constructor)) {
-			this._autoWrapCustomMethods();
-			wrappedClasses.add(this.constructor);
-		}
-		this._ensureSchema();
-		this.mcp = new MCPClientManager(this._ParentClass.name, "0.0.1", {
-			storage: this.ctx.storage,
-			createAuthProvider: (callbackUrl) => this.createMcpOAuthProvider(callbackUrl)
+		this.mcp = this._withAgentSpan("agent_initialization", "initialization", {}, (update) => {
+			if (!wrappedClasses.has(this.constructor)) {
+				this._autoWrapCustomMethods();
+				wrappedClasses.add(this.constructor);
+			}
+			this._withAgentSpan("initialize_agent_storage", "initialization", {}, (updateStorage) => {
+				this._ensureSchema();
+				const schemaAttributes = {
+					"cloudflare.agents.schema.version.previous": this._schemaInitialization?.previousVersion,
+					"cloudflare.agents.schema.version.current": this._schemaInitialization?.currentVersion,
+					"cloudflare.agents.schema.migrated": this._schemaInitialization?.migrated
+				};
+				updateStorage(schemaAttributes);
+				update(schemaAttributes);
+			});
+			return new MCPClientManager(this._ParentClass.name, "0.0.1", {
+				storage: this.ctx.storage,
+				createAuthProvider: (callbackUrl) => this.createMcpOAuthProvider(callbackUrl)
+			});
 		});
 		this._disposables.add(this.mcp.onServerStateChanged(async () => {
 			this.broadcastMcpServers();
@@ -960,36 +994,46 @@ var Agent = class Agent extends Server {
 			});
 		};
 		const _onStart = this.onStart.bind(this);
-		this.onStart = async (props) => {
+		const startAgent = async (props, update) => {
 			return __DO_NOT_USE_WILL_BREAK__agentContext.run({
 				agent: this,
 				connection: void 0,
 				request: void 0,
 				email: void 0
 			}, async () => {
-				if (await this.ctx.storage.get("cf_agents_is_facet")) this._isFacet = true;
-				const storedFacetName = await this.ctx.storage.get("cf_agents_facet_name");
-				if (typeof storedFacetName === "string") this._facetName = storedFacetName;
-				const storedParentPath = await this.ctx.storage.get("cf_agents_parent_path");
-				if (isValidParentPath(storedParentPath)) this._parentPath = storedParentPath;
-				try {
-					await this._cf_hydrateSubAgentConnectionsFromRoot();
-				} catch (error) {
-					console.warn("[Agent] Unable to hydrate sub-agent WebSocket connections:", error);
-				}
+				await this._withAgentSpan("restore_agent_state", "startup", {}, async () => {
+					if (await this.ctx.storage.get("cf_agents_is_facet")) this._isFacet = true;
+					const storedFacetName = await this.ctx.storage.get("cf_agents_facet_name");
+					if (typeof storedFacetName === "string") this._facetName = storedFacetName;
+					const storedParentPath = await this.ctx.storage.get("cf_agents_parent_path");
+					if (isValidParentPath(storedParentPath)) this._parentPath = storedParentPath;
+					try {
+						await this._cf_hydrateSubAgentConnectionsFromRoot();
+					} catch (error) {
+						console.warn("[Agent] Unable to hydrate sub-agent WebSocket connections:", error);
+					}
+				});
 				await this._tryCatch(async () => {
-					await this.mcp.restoreConnectionsFromStorage(this.name);
-					await this._restoreRpcMcpServers();
-					this.broadcastMcpServers();
-					this._checkOrphanedWorkflows();
-					await this._checkRunFibers();
-					const startupAgentToolRunIds = this._agentToolRunRecoveryRunIds();
+					await this._withAgentSpan("restore_mcp_connections", "startup", {}, async () => {
+						await this.mcp.restoreConnectionsFromStorage(this.name);
+						await this._restoreRpcMcpServers();
+						this.broadcastMcpServers();
+					});
+					const startupAgentToolRunIds = await this._withAgentSpan("recover_agent_work", "startup", {}, async () => {
+						this._checkOrphanedWorkflows();
+						await this._checkRunFibers();
+						return this._agentToolRunRecoveryRunIds();
+					});
+					update({
+						"cloudflare.agents.start.facet": this._isFacet,
+						"cloudflare.agents.recovery.agent_tools.count": startupAgentToolRunIds.length
+					});
 					const chatRecoveryBefore = this.chatRecovery;
 					this._insideOnStart = true;
 					this._warnedScheduleInOnStart.clear();
 					let result;
 					try {
-						result = await _onStart(props);
+						result = await this._withAgentSpan("run_user_on_start", "startup", {}, () => _onStart(props));
 					} finally {
 						this._insideOnStart = false;
 					}
@@ -1004,6 +1048,7 @@ var Agent = class Agent extends Server {
 				});
 			});
 		};
+		this.onStart = (props) => this._withAgentSpan("agent_start", "startup", {}, (update) => startAgent(props, update));
 	}
 	/**
 	* Check for workflows referencing unknown bindings and warn with migration suggestion.
@@ -2837,10 +2882,15 @@ var Agent = class Agent extends Server {
 	}
 	async _runFiberInternal(id, name, fn, options) {
 		const signal = options?.signal ?? new AbortController().signal;
-		this.sql`
-      INSERT INTO cf_agents_runs (id, name, snapshot, created_at)
-      VALUES (${id}, ${name}, NULL, ${Date.now()})
-    `;
+		this._withAgentSpan("initialize_fiber", "fiber", {
+			"cloudflare.agents.fiber.id": id,
+			"cloudflare.agents.fiber.name": name
+		}, () => {
+			this.sql`
+          INSERT INTO cf_agents_runs (id, name, snapshot, created_at)
+          VALUES (${id}, ${name}, NULL, ${Date.now()})
+        `;
+		});
 		const startedAt = Date.now();
 		this._emit("fiber:run:started", {
 			fiberId: id,
@@ -2850,14 +2900,19 @@ var Agent = class Agent extends Server {
 		this._runFiberActiveFibers.add(id);
 		const writeSnapshot = (data) => {
 			const snapshot = JSON.stringify(data);
-			this.sql`
-        UPDATE cf_agents_runs SET snapshot = ${snapshot}
-        WHERE id = ${id}
-      `;
-			if (options?.managed) this.sql`
-          UPDATE cf_agents_fibers SET snapshot = ${snapshot}
-          WHERE fiber_id = ${id}
-        `;
+			this._withAgentSpan("persist_fiber_snapshot", "fiber", {
+				"cloudflare.agents.fiber.id": id,
+				"cloudflare.agents.fiber.name": name
+			}, () => {
+				this.sql`
+            UPDATE cf_agents_runs SET snapshot = ${snapshot}
+            WHERE id = ${id}
+          `;
+				if (options?.managed) this.sql`
+              UPDATE cf_agents_fibers SET snapshot = ${snapshot}
+              WHERE fiber_id = ${id}
+            `;
+			});
 		};
 		let root;
 		let registeredFacetRun = false;
@@ -2908,7 +2963,12 @@ var Agent = class Agent extends Server {
 			}
 		} finally {
 			this._runFiberActiveFibers.delete(id);
-			this.sql`DELETE FROM cf_agents_runs WHERE id = ${id}`;
+			this._withAgentSpan("finalize_fiber", "fiber", {
+				"cloudflare.agents.fiber.id": id,
+				"cloudflare.agents.fiber.name": name
+			}, () => {
+				this.sql`DELETE FROM cf_agents_runs WHERE id = ${id}`;
+			});
 			dispose();
 			if (root && registeredFacetRun) try {
 				await root._cf_unregisterFacetRun(this.selfPath, id);
@@ -3328,6 +3388,9 @@ var Agent = class Agent extends Server {
     `[0]?.count ?? 0) > 0;
 	}
 	async _scheduleNextAlarm() {
+		await this._withAgentSpan("schedule_agent_alarm", "alarm", {}, () => this._scheduleNextAlarmBody());
+	}
+	async _scheduleNextAlarmBody() {
 		if (await this._hasPendingDestroy()) {
 			await this.ctx.storage.setAlarm(Date.now());
 			return;
@@ -6716,11 +6779,33 @@ var Agent = class Agent extends Server {
 		}
 		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.AUTHENTICATING) {
+				const authProvider = conn.options.transport.authProvider;
+				const authUrl = await this._redeemableAuthUrl(existingServer.id, authProvider?.authUrl, authProvider) ?? await this._redeemableAuthUrl(existingServer.id, existingServer.auth_url, authProvider);
+				if (authUrl) return {
+					id: existingServer.id,
+					state: MCPConnectionState.AUTHENTICATING,
+					authUrl
+				};
+				const reconnectResult = await this.mcp.connectToServer(existingServer.id);
+				if (reconnectResult.state === MCPConnectionState.AUTHENTICATING) {
+					if (!reconnectResult.authUrl) throw new Error("OAuth configuration incomplete: missing authUrl");
+					return {
+						id: existingServer.id,
+						state: reconnectResult.state,
+						authUrl: reconnectResult.authUrl
+					};
+				}
+				if (reconnectResult.state === MCPConnectionState.CONNECTED) {
+					const discoverResult = await this.mcp.discoverIfConnected(existingServer.id);
+					if (!discoverResult?.success) throw new Error(`Failed to discover MCP server capabilities: ${discoverResult?.error ?? "connection not found"}`);
+					return {
+						id: existingServer.id,
+						state: MCPConnectionState.READY
+					};
+				}
+				throw new Error(`Failed to connect to MCP server at ${normalizedUrl}: ${reconnectResult.error}`);
+			}
 			if (conn.connectionState === MCPConnectionState.FAILED) throw new Error(`MCP server "${serverName}" is in failed state: ${conn.connectionError}`);
 			return {
 				id: existingServer.id,
@@ -6787,7 +6872,7 @@ var Agent = class Agent extends Server {
 			const normalizedHost = resolvedCallbackHost.replace(/\/$/, "");
 			callbackUrl = resolvedCallbackPath ? `${normalizedHost}/${resolvedCallbackPath.replace(/^\//, "")}` : `${normalizedHost}/${resolvedAgentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
 		}
-		const id = requestedId ?? nanoid(8);
+		const id = requestedId ?? existingServer?.id ?? nanoid(8);
 		let authProvider;
 		if (callbackUrl) {
 			authProvider = this.createMcpOAuthProvider(callbackUrl);
@@ -6831,6 +6916,26 @@ var Agent = class Agent extends Server {
 			state: MCPConnectionState.READY
 		};
 	}
+	async _redeemableAuthUrl(serverId, authUrl, authProvider) {
+		if (!this._isAbsoluteHttpUrl(authUrl) || !authProvider) return;
+		const state = new URL(authUrl).searchParams.get("state");
+		if (!state) return authUrl;
+		authProvider.serverId = serverId;
+		try {
+			return (await authProvider.checkState(state)).valid ? authUrl : void 0;
+		} catch {
+			return;
+		}
+	}
+	_isAbsoluteHttpUrl(value) {
+		if (!value) return false;
+		try {
+			const url = new URL(value);
+			return url.protocol === "http:" || url.protocol === "https:";
+		} catch {
+			return false;
+		}
+	}
 	async removeMcpServer(id) {
 		await this.mcp.removeServer(id);
 	}
@@ -7117,6 +7222,6 @@ var StreamingResponse = class {
 	}
 };
 //#endregion
-export { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART, Agent, DEFAULT_AGENT_STATIC_OPTIONS, DurableObjectOAuthClientProvider, MCP_SERVER_ID_MAX_LENGTH, MessageType, SUB_PREFIX, SqlError, StreamingResponse, __DO_NOT_USE_WILL_BREAK__agentContext, callable, camelCaseToKebabCase, createHeaderBasedEmailResolver, getAgentByName, getCurrentAgent, getSubAgentByName, isDurableObjectCodeUpdateReset, isDurableObjectMemoryLimitReset, isPlatformTransientError, normalizeServerId, parseSubAgentPath, routeAgentEmail, routeAgentRequest, routeSubAgentRequest, unstable_callable };
+export { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART, Agent, DEFAULT_AGENT_STATIC_OPTIONS, DurableObjectOAuthClientProvider, MCP_SERVER_ID_MAX_LENGTH, MessageType, SUB_PREFIX, SqlError, StreamingResponse, __DO_NOT_USE_WILL_BREAK__agentContext, callable, camelCaseToKebabCase, createHeaderBasedEmailResolver, getAgentByName, getCurrentAgent, getSubAgentByName, isDurableObjectCodeUpdateReset, isDurableObjectMemoryLimitReset, isDurableObjectStorageReset, isPlatformTransientError, normalizeServerId, parseSubAgentPath, routeAgentEmail, routeAgentRequest, routeSubAgentRequest, unstable_callable };
 
 //# sourceMappingURL=index.js.map