agents 0.6.0 → 0.7.0

package/dist/agent-DnmmRjyv.d.ts

@@ -0,0 +1,231 @@
+//#region src/observability/base.d.ts
+/**
+ * Base event structure for all observability events
+ */
+type BaseEvent<
+  T extends string,
+  Payload extends Record<string, unknown> = Record<string, never>
+> = {
+  type: T;
+  /**
+   * The payload of the event
+   */
+  payload: Payload;
+  /**
+   * The timestamp of the event in milliseconds since epoch
+   */
+  timestamp: number;
+};
+//#endregion
+//#region src/observability/mcp.d.ts
+/**
+ * MCP-specific observability events
+ * These track the lifecycle of MCP connections and operations
+ */
+type MCPObservabilityEvent =
+  | BaseEvent<
+      "mcp:client:preconnect",
+      {
+        serverId: string;
+      }
+    >
+  | BaseEvent<
+      "mcp:client:connect",
+      {
+        url: string;
+        transport: string;
+        state: string;
+        error?: string;
+      }
+    >
+  | BaseEvent<
+      "mcp:client:authorize",
+      {
+        serverId: string;
+        authUrl: string;
+        clientId?: string;
+      }
+    >
+  | BaseEvent<
+      "mcp:client:discover",
+      {
+        url?: string;
+        state?: string;
+        error?: string;
+        capability?: string;
+      }
+    >;
+//#endregion
+//#region src/observability/agent.d.ts
+/**
+ * Agent-specific observability events
+ * These track the lifecycle and operations of an Agent
+ */
+type AgentObservabilityEvent =
+  | BaseEvent<"state:update">
+  | BaseEvent<
+      "rpc",
+      {
+        method: string;
+        streaming?: boolean;
+      }
+    >
+  | BaseEvent<
+      "rpc:error",
+      {
+        method: string;
+        error: string;
+      }
+    >
+  | BaseEvent<"message:request">
+  | BaseEvent<"message:response">
+  | BaseEvent<"message:clear">
+  | BaseEvent<
+      "message:cancel",
+      {
+        requestId: string;
+      }
+    >
+  | BaseEvent<
+      "message:error",
+      {
+        error: string;
+      }
+    >
+  | BaseEvent<
+      "tool:result",
+      {
+        toolCallId: string;
+        toolName: string;
+      }
+    >
+  | BaseEvent<
+      "tool:approval",
+      {
+        toolCallId: string;
+        approved: boolean;
+      }
+    >
+  | BaseEvent<
+      "schedule:create",
+      {
+        callback: string;
+        id: string;
+      }
+    >
+  | BaseEvent<
+      "schedule:execute",
+      {
+        callback: string;
+        id: string;
+      }
+    >
+  | BaseEvent<
+      "schedule:cancel",
+      {
+        callback: string;
+        id: string;
+      }
+    >
+  | BaseEvent<
+      "schedule:retry",
+      {
+        callback: string;
+        id: string;
+        attempt: number;
+        maxAttempts: number;
+      }
+    >
+  | BaseEvent<
+      "schedule:error",
+      {
+        callback: string;
+        id: string;
+        error: string;
+        attempts: number;
+      }
+    >
+  | BaseEvent<
+      "queue:retry",
+      {
+        callback: string;
+        id: string;
+        attempt: number;
+        maxAttempts: number;
+      }
+    >
+  | BaseEvent<
+      "queue:error",
+      {
+        callback: string;
+        id: string;
+        error: string;
+        attempts: number;
+      }
+    >
+  | BaseEvent<"destroy">
+  | BaseEvent<
+      "connect",
+      {
+        connectionId: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:start",
+      {
+        workflowId: string;
+        workflowName?: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:event",
+      {
+        workflowId: string;
+        eventType?: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:approved",
+      {
+        workflowId: string;
+        reason?: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:rejected",
+      {
+        workflowId: string;
+        reason?: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:terminated",
+      {
+        workflowId: string;
+        workflowName?: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:paused",
+      {
+        workflowId: string;
+        workflowName?: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:resumed",
+      {
+        workflowId: string;
+        workflowName?: string;
+      }
+    >
+  | BaseEvent<
+      "workflow:restarted",
+      {
+        workflowId: string;
+        workflowName?: string;
+      }
+    >;
+//#endregion
+export { MCPObservabilityEvent as n, AgentObservabilityEvent as t };
+//# sourceMappingURL=agent-DnmmRjyv.d.ts.map

package/dist/{client-connection-BqngKttp.js → client-connection-D3Wcd6Q6.js}

@@ -1,4 +1,3 @@
-import { nanoid } from "nanoid";
 import { getServerByName } from "partyserver";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
@@ -66,9 +65,18 @@ function isTransportNotImplemented(error) {
 //#endregion
 //#region src/mcp/rpc.ts
 const RPC_DO_PREFIX = "rpc:";
+function makeInvalidRequestError(id) {
+	return {
+		jsonrpc: "2.0",
+		id: id ?? null,
+		error: {
+			code: -32600,
+			message: "Invalid Request"
+		}
+	};
+}
 function validateBatch(batch) {
 	if (batch.length === 0) throw new Error("Invalid JSON-RPC batch: array must not be empty");
-	for (const msg of batch) JSONRPCMessageSchema.parse(msg);
 }
 var RPCClientTransport = class {
 	constructor(options) {
@@ -155,7 +163,11 @@ var RPCServerTransport = class {
 			}
 			return responses.length === 0 ? void 0 : responses;
 		}
-		JSONRPCMessageSchema.parse(message);
+		try {
+			JSONRPCMessageSchema.parse(message);
+		} catch {
+			return makeInvalidRequestError(typeof message === "object" && message !== null && "id" in message ? message.id : null);
+		}
 		this._pendingResponse = null;
 		if (!("id" in message)) {
 			this.onmessage?.(message);
@@ -249,29 +261,25 @@ var MCPClientConnection = class {
 			this.lastConnectedTransport = res.transport;
 			this._onObservabilityEvent.fire({
 				type: "mcp:client:connect",
-				displayMessage: `Connected successfully using ${res.transport} transport for ${this.url.toString()}`,
 				payload: {
 					url: this.url.toString(),
 					transport: res.transport,
 					state: this.connectionState
 				},
-				timestamp: Date.now(),
-				id: nanoid()
+				timestamp: Date.now()
 			});
 			return;
 		} else if (res.state === MCPConnectionState.FAILED && res.error) {
 			const errorMessage = toErrorMessage(res.error);
 			this._onObservabilityEvent.fire({
 				type: "mcp:client:connect",
-				displayMessage: `Failed to connect to ${this.url.toString()}: ${errorMessage}`,
 				payload: {
 					url: this.url.toString(),
 					transport: transportType,
 					state: this.connectionState,
 					error: errorMessage
 				},
-				timestamp: Date.now(),
-				id: nanoid()
+				timestamp: Date.now()
 			});
 			return errorMessage;
 		}
@@ -369,13 +377,11 @@ var MCPClientConnection = class {
 		} catch (error) {
 			this._onObservabilityEvent.fire({
 				type: "mcp:client:discover",
-				displayMessage: `Failed to discover capabilities for ${this.url.toString()}: ${toErrorMessage(error)}`,
 				payload: {
 					url: this.url.toString(),
 					error: toErrorMessage(error)
 				},
-				timestamp: Date.now(),
-				id: nanoid()
+				timestamp: Date.now()
 			});
 			throw error;
 		}
@@ -393,13 +399,11 @@ var MCPClientConnection = class {
 		if (this.connectionState !== MCPConnectionState.CONNECTED && this.connectionState !== MCPConnectionState.READY) {
 			this._onObservabilityEvent.fire({
 				type: "mcp:client:discover",
-				displayMessage: `Discovery skipped for ${this.url.toString()}, state is ${this.connectionState}`,
 				payload: {
 					url: this.url.toString(),
 					state: this.connectionState
 				},
-				timestamp: Date.now(),
-				id: nanoid()
+				timestamp: Date.now()
 			});
 			return {
 				success: false,
@@ -433,10 +437,8 @@ var MCPClientConnection = class {
 			this.connectionState = MCPConnectionState.READY;
 			this._onObservabilityEvent.fire({
 				type: "mcp:client:discover",
-				displayMessage: `Discovery completed for ${this.url.toString()}`,
 				payload: { url: this.url.toString() },
-				timestamp: Date.now(),
-				id: nanoid()
+				timestamp: Date.now()
 			});
 			return { success: true };
 		} catch (e) {
@@ -582,14 +584,12 @@ var MCPClientConnection = class {
 				const url = this.url.toString();
 				this._onObservabilityEvent.fire({
 					type: "mcp:client:discover",
-					displayMessage: `The server advertised support for the capability ${method.split("/")[0]}, but returned "Method not found" for '${method}' for ${url}`,
 					payload: {
 						url,
 						capability: method.split("/")[0],
 						error: toErrorMessage(e)
 					},
-					timestamp: Date.now(),
-					id: nanoid()
+					timestamp: Date.now()
 				});
 				return empty;
 			}
@@ -600,4 +600,4 @@ var MCPClientConnection = class {
 
 //#endregion
 export { RPC_DO_PREFIX as a, Emitter as c, RPCServerTransport as i, MCPConnectionState as n, toErrorMessage as o, RPCClientTransport as r, DisposableStore as s, MCPClientConnection as t };
-//# sourceMappingURL=client-connection-BqngKttp.js.map
+//# sourceMappingURL=client-connection-D3Wcd6Q6.js.map

package/dist/client-connection-D3Wcd6Q6.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-connection-D3Wcd6Q6.js","names":[],"sources":["../src/core/events.ts","../src/mcp/errors.ts","../src/mcp/rpc.ts","../src/mcp/client-connection.ts"],"sourcesContent":["export interface Disposable {\n  dispose(): void;\n}\n\nexport function toDisposable(fn: () => void): Disposable {\n  return { dispose: fn };\n}\n\nexport class DisposableStore implements Disposable {\n  private readonly _items: Disposable[] = [];\n\n  add<T extends Disposable>(d: T): T {\n    this._items.push(d);\n    return d;\n  }\n\n  dispose(): void {\n    while (this._items.length) {\n      try {\n        this._items.pop()!.dispose();\n      } catch {\n        // best-effort cleanup\n      }\n    }\n  }\n}\n\nexport type Event<T> = (listener: (e: T) => void) => Disposable;\n\nexport class Emitter<T> implements Disposable {\n  private _listeners: Set<(e: T) => void> = new Set();\n\n  readonly event: Event<T> = (listener) => {\n    this._listeners.add(listener);\n    return toDisposable(() => this._listeners.delete(listener));\n  };\n\n  fire(data: T): void {\n    for (const listener of [...this._listeners]) {\n      try {\n        listener(data);\n      } catch (err) {\n        // do not let one bad listener break others\n        console.error(\"Emitter listener error:\", err);\n      }\n    }\n  }\n\n  dispose(): void {\n    this._listeners.clear();\n  }\n}\n","export function toErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction getErrorCode(error: unknown): number | undefined {\n  if (\n    error &&\n    typeof error === \"object\" &&\n    \"code\" in error &&\n    typeof (error as { code: unknown }).code === \"number\"\n  ) {\n    return (error as { code: number }).code;\n  }\n  return undefined;\n}\n\nexport function isUnauthorized(error: unknown): boolean {\n  const code = getErrorCode(error);\n  if (code === 401) return true;\n\n  const msg = toErrorMessage(error);\n  return msg.includes(\"Unauthorized\") || msg.includes(\"401\");\n}\n\n// MCP SDK change (v1.24.0, commit 6b90e1a):\n//   - Old: Error POSTing to endpoint (HTTP 404): Not Found\n//   - New: StreamableHTTPError with code: 404 and message Error POSTing to endpoint: Not Found\nexport function isTransportNotImplemented(error: unknown): boolean {\n  const code = getErrorCode(error);\n  if (code === 404 || code === 405) return true;\n\n  const msg = toErrorMessage(error);\n  return (\n    msg.includes(\"404\") ||\n    msg.includes(\"405\") ||\n    msg.includes(\"Not Implemented\") ||\n    msg.includes(\"not implemented\")\n  );\n}\n","import type {\n  Transport,\n  TransportSendOptions\n} from \"@modelcontextprotocol/sdk/shared/transport.js\";\nimport type {\n  JSONRPCMessage,\n  MessageExtraInfo\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport { JSONRPCMessageSchema } from \"@modelcontextprotocol/sdk/types.js\";\nimport { getServerByName } from \"partyserver\";\nimport type { McpAgent } from \".\";\n\nexport const RPC_DO_PREFIX = \"rpc:\";\n\nfunction makeInvalidRequestError(id: unknown): JSONRPCMessage {\n  return {\n    jsonrpc: \"2.0\",\n    id: id ?? null,\n    error: {\n      code: -32600,\n      message: \"Invalid Request\"\n    }\n  } as JSONRPCMessage;\n}\n\nfunction validateBatch(batch: JSONRPCMessage[]): void {\n  if (batch.length === 0) {\n    throw new Error(\"Invalid JSON-RPC batch: array must not be empty\");\n  }\n}\n\nexport interface RPCClientTransportOptions<T extends McpAgent = McpAgent> {\n  namespace: DurableObjectNamespace<T>;\n  name: string;\n  props?: Record<string, unknown>;\n}\n\nexport class RPCClientTransport implements Transport {\n  private _namespace: DurableObjectNamespace<McpAgent>;\n  private _name: string;\n  private _props?: Record<string, unknown>;\n  private _stub?: DurableObjectStub<McpAgent>;\n  private _started = false;\n  private _protocolVersion?: string;\n\n  sessionId?: string;\n  onclose?: () => void;\n  onerror?: (error: Error) => void;\n  onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;\n\n  constructor(options: RPCClientTransportOptions<McpAgent>) {\n    this._namespace = options.namespace;\n    this._name = options.name;\n    this._props = options.props;\n  }\n\n  setProtocolVersion(version: string): void {\n    this._protocolVersion = version;\n  }\n\n  getProtocolVersion(): string | undefined {\n    return this._protocolVersion;\n  }\n\n  async start(): Promise<void> {\n    if (this._started) {\n      throw new Error(\"Transport already started\");\n    }\n\n    const doName = `${RPC_DO_PREFIX}${this._name}`;\n    this._stub = await getServerByName(this._namespace, doName, {\n      props: this._props\n    });\n\n    this._started = true;\n  }\n\n  async close(): Promise<void> {\n    this._started = false;\n    this._stub = undefined;\n    this.onclose?.();\n  }\n\n  async send(\n    message: JSONRPCMessage | JSONRPCMessage[],\n    options?: TransportSendOptions\n  ): Promise<void> {\n    if (!this._started || !this._stub) {\n      throw new Error(\"Transport not started\");\n    }\n\n    try {\n      const result: JSONRPCMessage | JSONRPCMessage[] | undefined =\n        await this._stub.handleMcpMessage(message);\n\n      if (!result) {\n        return;\n      }\n\n      const extra: MessageExtraInfo | undefined = options?.relatedRequestId\n        ? { requestInfo: { headers: {} } }\n        : undefined;\n\n      const messages = Array.isArray(result) ? result : [result];\n      for (const msg of messages) {\n        this.onmessage?.(msg, extra);\n      }\n    } catch (error) {\n      this.onerror?.(error as Error);\n      throw error;\n    }\n  }\n}\n\nexport interface RPCServerTransportOptions {\n  timeout?: number;\n}\n\nexport class RPCServerTransport implements Transport {\n  private _started = false;\n  private _pendingResponse: JSONRPCMessage | JSONRPCMessage[] | null = null;\n  private _responseResolver: (() => void) | null = null;\n  private _protocolVersion?: string;\n  private _timeout: number;\n\n  sessionId?: string;\n  onclose?: () => void;\n  onerror?: (error: Error) => void;\n  onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;\n\n  constructor(options?: RPCServerTransportOptions) {\n    this._timeout = options?.timeout ?? 60000;\n  }\n\n  setProtocolVersion(version: string): void {\n    this._protocolVersion = version;\n  }\n\n  getProtocolVersion(): string | undefined {\n    return this._protocolVersion;\n  }\n\n  async start(): Promise<void> {\n    if (this._started) {\n      throw new Error(\"Transport already started\");\n    }\n    this._started = true;\n  }\n\n  async close(): Promise<void> {\n    this._started = false;\n    this.onclose?.();\n    if (this._responseResolver) {\n      this._responseResolver();\n      this._responseResolver = null;\n    }\n  }\n\n  async send(\n    message: JSONRPCMessage,\n    _options?: TransportSendOptions\n  ): Promise<void> {\n    if (!this._started) {\n      throw new Error(\"Transport not started\");\n    }\n\n    if (!this._pendingResponse) {\n      this._pendingResponse = message;\n    } else if (Array.isArray(this._pendingResponse)) {\n      this._pendingResponse.push(message);\n    } else {\n      this._pendingResponse = [this._pendingResponse, message];\n    }\n\n    if (this._responseResolver) {\n      const resolver = this._responseResolver;\n      queueMicrotask(() => resolver());\n    }\n  }\n\n  async handle(\n    message: JSONRPCMessage | JSONRPCMessage[]\n  ): Promise<JSONRPCMessage | JSONRPCMessage[] | undefined> {\n    if (!this._started) {\n      throw new Error(\"Transport not started\");\n    }\n\n    if (Array.isArray(message)) {\n      validateBatch(message);\n\n      const responses: JSONRPCMessage[] = [];\n      for (const msg of message) {\n        const response = await this.handle(msg);\n        if (response !== undefined) {\n          if (Array.isArray(response)) {\n            responses.push(...response);\n          } else {\n            responses.push(response);\n          }\n        }\n      }\n\n      return responses.length === 0 ? undefined : responses;\n    }\n\n    try {\n      JSONRPCMessageSchema.parse(message);\n    } catch {\n      const id =\n        typeof message === \"object\" && message !== null && \"id\" in message\n          ? (message as { id: unknown }).id\n          : null;\n      return makeInvalidRequestError(id);\n    }\n\n    this._pendingResponse = null;\n\n    const isNotification = !(\"id\" in message);\n    if (isNotification) {\n      this.onmessage?.(message);\n      return undefined;\n    }\n\n    let timeoutId: ReturnType<typeof setTimeout> | null = null;\n    const responsePromise = new Promise<void>((resolve, reject) => {\n      timeoutId = setTimeout(() => {\n        this._responseResolver = null;\n        reject(\n          new Error(\n            `Request timeout: No response received within ${this._timeout}ms`\n          )\n        );\n      }, this._timeout);\n\n      this._responseResolver = () => {\n        if (timeoutId) {\n          clearTimeout(timeoutId);\n          timeoutId = null;\n        }\n        this._responseResolver = null;\n        resolve();\n      };\n    });\n\n    this.onmessage?.(message);\n\n    try {\n      await responsePromise;\n    } catch (error) {\n      this._pendingResponse = null;\n      this._responseResolver = null;\n      throw error;\n    }\n\n    const response = this._pendingResponse;\n    this._pendingResponse = null;\n\n    return response ?? undefined;\n  }\n}\n","import { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport {\n  SSEClientTransport,\n  type SSEClientTransportOptions\n} from \"@modelcontextprotocol/sdk/client/sse.js\";\nimport {\n  StreamableHTTPClientTransport,\n  type StreamableHTTPClientTransportOptions\n} from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\n// Import types directly from MCP SDK\nimport type {\n  Prompt,\n  Resource,\n  Tool\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  type ClientCapabilities,\n  type ElicitRequest,\n  ElicitRequestSchema,\n  type ElicitResult,\n  type ListPromptsResult,\n  type ListResourceTemplatesResult,\n  type ListResourcesResult,\n  type ListToolsResult,\n  PromptListChangedNotificationSchema,\n  ResourceListChangedNotificationSchema,\n  type ResourceTemplate,\n  type ServerCapabilities,\n  ToolListChangedNotificationSchema\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport { Emitter, type Event } from \"../core/events\";\nimport type { MCPObservabilityEvent } from \"../observability/mcp\";\nimport type { AgentMcpOAuthProvider } from \"./do-oauth-client-provider\";\nimport {\n  isTransportNotImplemented,\n  isUnauthorized,\n  toErrorMessage\n} from \"./errors\";\nimport { RPCClientTransport, type RPCClientTransportOptions } from \"./rpc\";\nimport type {\n  BaseTransportType,\n  HttpTransportType,\n  TransportType,\n  McpClientOptions\n} from \"./types\";\n\n/**\n * Connection state machine for MCP client connections.\n *\n * State transitions:\n * - Non-OAuth: init() → CONNECTING → DISCOVERING → READY\n * - OAuth: init() → AUTHENTICATING → (callback) → CONNECTING → DISCOVERING → READY\n * - Any state can transition to FAILED on error\n */\nexport const MCPConnectionState = {\n  /** Waiting for OAuth authorization to complete */\n  AUTHENTICATING: \"authenticating\",\n  /** Establishing transport connection to MCP server */\n  CONNECTING: \"connecting\",\n  /** Transport connection established */\n  CONNECTED: \"connected\",\n  /** Discovering server capabilities (tools, resources, prompts) */\n  DISCOVERING: \"discovering\",\n  /** Fully connected and ready to use */\n  READY: \"ready\",\n  /** Connection failed at some point */\n  FAILED: \"failed\"\n} as const;\n\n/**\n * Connection state type for MCP client connections.\n */\nexport type MCPConnectionState =\n  (typeof MCPConnectionState)[keyof typeof MCPConnectionState];\n\n/**\n * Transport options for MCP client connections.\n * Combines transport-specific options with auth provider and type selection.\n */\nexport type MCPTransportOptions = (\n  | SSEClientTransportOptions\n  | StreamableHTTPClientTransportOptions\n  | RPCClientTransportOptions\n) & {\n  authProvider?: AgentMcpOAuthProvider;\n  type?: TransportType;\n};\n\nexport type MCPClientConnectionResult = {\n  state: MCPConnectionState;\n  error?: Error;\n  transport?: BaseTransportType;\n};\n\n/**\n * Result of a discovery operation.\n * success indicates whether discovery completed successfully.\n * error is present when success is false.\n */\nexport type MCPDiscoveryResult = {\n  success: boolean;\n  error?: string;\n};\n\nexport class MCPClientConnection {\n  client: Client;\n  connectionState: MCPConnectionState = MCPConnectionState.CONNECTING;\n  connectionError: string | null = null;\n  lastConnectedTransport: BaseTransportType | undefined;\n  instructions?: string;\n  tools: Tool[] = [];\n  prompts: Prompt[] = [];\n  resources: Resource[] = [];\n  resourceTemplates: ResourceTemplate[] = [];\n  serverCapabilities: ServerCapabilities | undefined;\n\n  /** Tracks in-flight discovery to allow cancellation */\n  private _discoveryAbortController: AbortController | undefined;\n\n  private readonly _onObservabilityEvent = new Emitter<MCPObservabilityEvent>();\n  public readonly onObservabilityEvent: Event<MCPObservabilityEvent> =\n    this._onObservabilityEvent.event;\n\n  constructor(\n    public url: URL,\n    info: ConstructorParameters<typeof Client>[0],\n    public options: {\n      transport: MCPTransportOptions;\n      client: McpClientOptions;\n    } = { client: {}, transport: {} }\n  ) {\n    const clientOptions = {\n      ...options.client,\n      capabilities: {\n        ...options.client?.capabilities,\n        elicitation: {}\n      } as ClientCapabilities\n    };\n\n    this.client = new Client(info, clientOptions);\n  }\n\n  /**\n   * Initialize a client connection, if authentication is required, the connection will be in the AUTHENTICATING state\n   * Sets connection state based on the result and emits observability events\n   *\n   * @returns Error message if connection failed, undefined otherwise\n   */\n  async init(): Promise<string | undefined> {\n    const transportType = this.options.transport.type;\n    if (!transportType) {\n      throw new Error(\"Transport type must be specified\");\n    }\n\n    const res = await this.tryConnect(transportType);\n\n    // Set the connection state\n    this.connectionState = res.state;\n\n    // Handle the result and emit appropriate events\n    if (res.state === MCPConnectionState.CONNECTED && res.transport) {\n      // Set up elicitation request handler after successful connection\n      this.client.setRequestHandler(\n        ElicitRequestSchema,\n        async (request: ElicitRequest) => {\n          return await this.handleElicitationRequest(request);\n        }\n      );\n\n      this.lastConnectedTransport = res.transport;\n\n      this._onObservabilityEvent.fire({\n        type: \"mcp:client:connect\",\n        payload: {\n          url: this.url.toString(),\n          transport: res.transport,\n          state: this.connectionState\n        },\n        timestamp: Date.now()\n      });\n      return undefined;\n    } else if (res.state === MCPConnectionState.FAILED && res.error) {\n      const errorMessage = toErrorMessage(res.error);\n      this._onObservabilityEvent.fire({\n        type: \"mcp:client:connect\",\n        payload: {\n          url: this.url.toString(),\n          transport: transportType,\n          state: this.connectionState,\n          error: errorMessage\n        },\n        timestamp: Date.now()\n      });\n      return errorMessage;\n    }\n    return undefined;\n  }\n\n  /**\n   * Finish OAuth by probing transports based on configured type.\n   * - Explicit: finish on that transport\n   * - Auto: try streamable-http, then sse on 404/405/Not Implemented\n   */\n  private async finishAuthProbe(code: string): Promise<void> {\n    if (!this.options.transport.authProvider) {\n      throw new Error(\"No auth provider configured\");\n    }\n\n    const configuredType = this.options.transport.type;\n    if (!configuredType) {\n      throw new Error(\"Transport type must be specified\");\n    }\n\n    const finishAuth = async (base: HttpTransportType) => {\n      const transport = this.getTransport(base);\n      if (\n        \"finishAuth\" in transport &&\n        typeof transport.finishAuth === \"function\"\n      ) {\n        await transport.finishAuth(code);\n      }\n    };\n\n    if (configuredType === \"rpc\") {\n      throw new Error(\"RPC transport does not support authentication\");\n    }\n\n    if (configuredType === \"sse\" || configuredType === \"streamable-http\") {\n      await finishAuth(configuredType);\n      return;\n    }\n\n    // For \"auto\" mode, try streamable-http first, then fall back to SSE\n    try {\n      await finishAuth(\"streamable-http\");\n    } catch (e) {\n      if (isTransportNotImplemented(e)) {\n        await finishAuth(\"sse\");\n        return;\n      }\n      throw e;\n    }\n  }\n\n  /**\n   * Complete OAuth authorization\n   */\n  async completeAuthorization(code: string): Promise<void> {\n    if (this.connectionState !== MCPConnectionState.AUTHENTICATING) {\n      throw new Error(\n        \"Connection must be in authenticating state to complete authorization\"\n      );\n    }\n\n    try {\n      // Finish OAuth by probing transports per configuration\n      await this.finishAuthProbe(code);\n\n      // Mark as connecting\n      this.connectionState = MCPConnectionState.CONNECTING;\n    } catch (error) {\n      this.connectionState = MCPConnectionState.FAILED;\n      throw error;\n    }\n  }\n\n  /**\n   * Discover server capabilities and register tools, resources, prompts, and templates.\n   * This method does the work but does not manage connection state - that's handled by discover().\n   */\n  async discoverAndRegister(): Promise<void> {\n    this.serverCapabilities = this.client.getServerCapabilities();\n    if (!this.serverCapabilities) {\n      throw new Error(\"The MCP Server failed to return server capabilities\");\n    }\n\n    // Build list of operations to perform based on server capabilities\n    type DiscoveryResult =\n      | string\n      | undefined\n      | Tool[]\n      | Resource[]\n      | Prompt[]\n      | ResourceTemplate[];\n    const operations: Promise<DiscoveryResult>[] = [];\n    const operationNames: string[] = [];\n\n    // Instructions (always try to fetch if available)\n    operations.push(Promise.resolve(this.client.getInstructions()));\n    operationNames.push(\"instructions\");\n\n    // Only register capabilities that the server advertises\n    if (this.serverCapabilities.tools) {\n      operations.push(this.registerTools());\n      operationNames.push(\"tools\");\n    }\n\n    if (this.serverCapabilities.resources) {\n      operations.push(this.registerResources());\n      operationNames.push(\"resources\");\n    }\n\n    if (this.serverCapabilities.prompts) {\n      operations.push(this.registerPrompts());\n      operationNames.push(\"prompts\");\n    }\n\n    if (this.serverCapabilities.resources) {\n      operations.push(this.registerResourceTemplates());\n      operationNames.push(\"resource templates\");\n    }\n\n    try {\n      const results = await Promise.all(operations);\n      for (let i = 0; i < results.length; i++) {\n        const result = results[i];\n        const name = operationNames[i];\n\n        switch (name) {\n          case \"instructions\":\n            this.instructions = result as string | undefined;\n            break;\n          case \"tools\":\n            this.tools = result as Tool[];\n            break;\n          case \"resources\":\n            this.resources = result as Resource[];\n            break;\n          case \"prompts\":\n            this.prompts = result as Prompt[];\n            break;\n          case \"resource templates\":\n            this.resourceTemplates = result as ResourceTemplate[];\n            break;\n        }\n      }\n    } catch (error) {\n      this._onObservabilityEvent.fire({\n        type: \"mcp:client:discover\",\n        payload: {\n          url: this.url.toString(),\n          error: toErrorMessage(error)\n        },\n        timestamp: Date.now()\n      });\n\n      throw error;\n    }\n  }\n\n  /**\n   * Discover server capabilities with timeout and cancellation support.\n   * If called while a previous discovery is in-flight, the previous discovery will be aborted.\n   *\n   * @param options Optional configuration\n   * @param options.timeoutMs Timeout in milliseconds (default: 15000)\n   * @returns Result indicating success/failure with optional error message\n   */\n  async discover(\n    options: { timeoutMs?: number } = {}\n  ): Promise<MCPDiscoveryResult> {\n    const { timeoutMs = 15000 } = options;\n\n    // Check if state allows discovery\n    if (\n      this.connectionState !== MCPConnectionState.CONNECTED &&\n      this.connectionState !== MCPConnectionState.READY\n    ) {\n      this._onObservabilityEvent.fire({\n        type: \"mcp:client:discover\",\n        payload: {\n          url: this.url.toString(),\n          state: this.connectionState\n        },\n        timestamp: Date.now()\n      });\n      return {\n        success: false,\n        error: `Discovery skipped - connection in ${this.connectionState} state`\n      };\n    }\n\n    // Cancel any previous in-flight discovery\n    if (this._discoveryAbortController) {\n      this._discoveryAbortController.abort();\n      this._discoveryAbortController = undefined;\n    }\n\n    // Create a new AbortController for this discovery\n    const abortController = new AbortController();\n    this._discoveryAbortController = abortController;\n\n    this.connectionState = MCPConnectionState.DISCOVERING;\n\n    let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n    try {\n      // Create timeout promise\n      const timeoutPromise = new Promise<never>((_, reject) => {\n        timeoutId = setTimeout(\n          () => reject(new Error(`Discovery timed out after ${timeoutMs}ms`)),\n          timeoutMs\n        );\n      });\n\n      // Check if aborted before starting\n      if (abortController.signal.aborted) {\n        throw new Error(\"Discovery was cancelled\");\n      }\n\n      // Create an abort promise that rejects when signal fires\n      const abortPromise = new Promise<never>((_, reject) => {\n        abortController.signal.addEventListener(\"abort\", () => {\n          reject(new Error(\"Discovery was cancelled\"));\n        });\n      });\n\n      await Promise.race([\n        this.discoverAndRegister(),\n        timeoutPromise,\n        abortPromise\n      ]);\n\n      // Clear timeout on success\n      if (timeoutId !== undefined) {\n        clearTimeout(timeoutId);\n      }\n\n      // Discovery succeeded - transition to ready\n      this.connectionState = MCPConnectionState.READY;\n\n      this._onObservabilityEvent.fire({\n        type: \"mcp:client:discover\",\n        payload: {\n          url: this.url.toString()\n        },\n        timestamp: Date.now()\n      });\n\n      return { success: true };\n    } catch (e) {\n      // Always clear the timeout\n      if (timeoutId !== undefined) {\n        clearTimeout(timeoutId);\n      }\n\n      // Return to CONNECTED state so user can retry discovery\n      this.connectionState = MCPConnectionState.CONNECTED;\n\n      const error = e instanceof Error ? e.message : String(e);\n      return { success: false, error };\n    } finally {\n      // Clean up the abort controller\n      this._discoveryAbortController = undefined;\n    }\n  }\n\n  /**\n   * Cancel any in-flight discovery operation.\n   * Called when closing the connection.\n   */\n  cancelDiscovery(): void {\n    if (this._discoveryAbortController) {\n      this._discoveryAbortController.abort();\n      this._discoveryAbortController = undefined;\n    }\n  }\n\n  /**\n   * Notification handler registration for tools\n   * Should only be called if serverCapabilities.tools exists\n   */\n  async registerTools(): Promise<Tool[]> {\n    if (this.serverCapabilities?.tools?.listChanged) {\n      this.client.setNotificationHandler(\n        ToolListChangedNotificationSchema,\n        async (_notification) => {\n          this.tools = await this.fetchTools();\n        }\n      );\n    }\n\n    return this.fetchTools();\n  }\n\n  /**\n   * Notification handler registration for resources\n   * Should only be called if serverCapabilities.resources exists\n   */\n  async registerResources(): Promise<Resource[]> {\n    if (this.serverCapabilities?.resources?.listChanged) {\n      this.client.setNotificationHandler(\n        ResourceListChangedNotificationSchema,\n        async (_notification) => {\n          this.resources = await this.fetchResources();\n        }\n      );\n    }\n\n    return this.fetchResources();\n  }\n\n  /**\n   * Notification handler registration for prompts\n   * Should only be called if serverCapabilities.prompts exists\n   */\n  async registerPrompts(): Promise<Prompt[]> {\n    if (this.serverCapabilities?.prompts?.listChanged) {\n      this.client.setNotificationHandler(\n        PromptListChangedNotificationSchema,\n        async (_notification) => {\n          this.prompts = await this.fetchPrompts();\n        }\n      );\n    }\n\n    return this.fetchPrompts();\n  }\n\n  async registerResourceTemplates(): Promise<ResourceTemplate[]> {\n    return this.fetchResourceTemplates();\n  }\n\n  async fetchTools() {\n    let toolsAgg: Tool[] = [];\n    let toolsResult: ListToolsResult = { tools: [] };\n    do {\n      toolsResult = await this.client\n        .listTools({\n          cursor: toolsResult.nextCursor\n        })\n        .catch(this._capabilityErrorHandler({ tools: [] }, \"tools/list\"));\n      toolsAgg = toolsAgg.concat(toolsResult.tools);\n    } while (toolsResult.nextCursor);\n    return toolsAgg;\n  }\n\n  async fetchResources() {\n    let resourcesAgg: Resource[] = [];\n    let resourcesResult: ListResourcesResult = { resources: [] };\n    do {\n      resourcesResult = await this.client\n        .listResources({\n          cursor: resourcesResult.nextCursor\n        })\n        .catch(\n          this._capabilityErrorHandler({ resources: [] }, \"resources/list\")\n        );\n      resourcesAgg = resourcesAgg.concat(resourcesResult.resources);\n    } while (resourcesResult.nextCursor);\n    return resourcesAgg;\n  }\n\n  async fetchPrompts() {\n    let promptsAgg: Prompt[] = [];\n    let promptsResult: ListPromptsResult = { prompts: [] };\n    do {\n      promptsResult = await this.client\n        .listPrompts({\n          cursor: promptsResult.nextCursor\n        })\n        .catch(this._capabilityErrorHandler({ prompts: [] }, \"prompts/list\"));\n      promptsAgg = promptsAgg.concat(promptsResult.prompts);\n    } while (promptsResult.nextCursor);\n    return promptsAgg;\n  }\n\n  async fetchResourceTemplates() {\n    let templatesAgg: ResourceTemplate[] = [];\n    let templatesResult: ListResourceTemplatesResult = {\n      resourceTemplates: []\n    };\n    do {\n      templatesResult = await this.client\n        .listResourceTemplates({\n          cursor: templatesResult.nextCursor\n        })\n        .catch(\n          this._capabilityErrorHandler(\n            { resourceTemplates: [] },\n            \"resources/templates/list\"\n          )\n        );\n      templatesAgg = templatesAgg.concat(templatesResult.resourceTemplates);\n    } while (templatesResult.nextCursor);\n    return templatesAgg;\n  }\n\n  /**\n   * Handle elicitation request from server\n   * Automatically uses the Agent's built-in elicitation handling if available\n   */\n  async handleElicitationRequest(\n    _request: ElicitRequest\n  ): Promise<ElicitResult> {\n    // Elicitation handling must be implemented by the platform\n    // For MCP servers, this should be handled by McpAgent.elicitInput()\n    throw new Error(\n      \"Elicitation handler must be implemented for your platform. Override handleElicitationRequest method.\"\n    );\n  }\n  /**\n   * Get the transport for the client\n   * @param transportType - The transport type to get\n   * @returns The transport for the client\n   */\n  getTransport(transportType: BaseTransportType) {\n    switch (transportType) {\n      case \"streamable-http\":\n        return new StreamableHTTPClientTransport(\n          this.url,\n          this.options.transport as StreamableHTTPClientTransportOptions\n        );\n      case \"sse\":\n        return new SSEClientTransport(\n          this.url,\n          this.options.transport as SSEClientTransportOptions\n        );\n      case \"rpc\":\n        return new RPCClientTransport(\n          this.options.transport as RPCClientTransportOptions\n        );\n      default:\n        throw new Error(`Unsupported transport type: ${transportType}`);\n    }\n  }\n\n  private async tryConnect(\n    transportType: TransportType\n  ): Promise<MCPClientConnectionResult> {\n    const transports: BaseTransportType[] =\n      transportType === \"auto\" ? [\"streamable-http\", \"sse\"] : [transportType];\n\n    for (const currentTransportType of transports) {\n      const isLastTransport =\n        currentTransportType === transports[transports.length - 1];\n      const hasFallback =\n        transportType === \"auto\" &&\n        currentTransportType === \"streamable-http\" &&\n        !isLastTransport;\n\n      const transport = this.getTransport(currentTransportType);\n\n      try {\n        await this.client.connect(transport);\n\n        return {\n          state: MCPConnectionState.CONNECTED,\n          transport: currentTransportType\n        };\n      } catch (e) {\n        const error = e instanceof Error ? e : new Error(String(e));\n\n        if (isUnauthorized(error)) {\n          return {\n            state: MCPConnectionState.AUTHENTICATING\n          };\n        }\n\n        if (isTransportNotImplemented(error) && hasFallback) {\n          // Try the next transport\n          continue;\n        }\n\n        return {\n          state: MCPConnectionState.FAILED,\n          error\n        };\n      }\n    }\n\n    // Should never reach here\n    return {\n      state: MCPConnectionState.FAILED,\n      error: new Error(\"No transports available\")\n    };\n  }\n\n  private _capabilityErrorHandler<T>(empty: T, method: string) {\n    return (e: { code: number }) => {\n      // server is badly behaved and returning invalid capabilities. This commonly occurs for resource templates\n      if (e.code === -32601) {\n        const url = this.url.toString();\n        this._onObservabilityEvent.fire({\n          type: \"mcp:client:discover\",\n          payload: {\n            url,\n            capability: method.split(\"/\")[0],\n            error: toErrorMessage(e)\n          },\n          timestamp: Date.now()\n        });\n        return empty;\n      }\n      throw e;\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/{client-storage-D5nDLKMW.d.ts → client-storage-tusTuoSF.d.ts}

@@ -1,4 +1,4 @@
-import { n as MCPObservabilityEvent } from "./agent-BHM7Gp_m.js";
+import { n as MCPObservabilityEvent } from "./agent-DnmmRjyv.js";
 import { AgentMcpOAuthProvider } from "./mcp/do-oauth-client-provider.js";
 import { McpAgent } from "./mcp/index.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -601,4 +601,4 @@ export {
   MaybePromise as x,
   StreamableHTTPEdgeClientTransport as y
 };
-//# sourceMappingURL=client-storage-D5nDLKMW.d.ts.map
+//# sourceMappingURL=client-storage-tusTuoSF.d.ts.map

package/dist/experimental/forever.d.ts

@@ -1,5 +1,5 @@
 import { RetryOptions } from "../retries.js";
-import "../client-storage-D5nDLKMW.js";
+import "../client-storage-tusTuoSF.js";
 import { Agent, Schedule } from "../index.js";
 
 //#region src/experimental/forever.d.ts
@@ -52,7 +52,7 @@ type RawFiberRow = {
   created_at: number;
 };
 type Constructor<T = object> = new (...args: any[]) => T;
-type AgentLike = Constructor<Pick<Agent<Cloudflare.Env>, "sql" | "scheduleEvery" | "cancelSchedule" | "alarm">>;
+type AgentLike = Constructor<Pick<Agent<Cloudflare.Env>, "sql" | "scheduleEvery" | "cancelSchedule" | "alarm" | "keepAlive" | "keepAliveWhile">>;
 declare function withFibers<TBase extends AgentLike>(Base: TBase, options?: {
   debugFibers?: boolean;
 }): {
@@ -61,8 +61,7 @@ declare function withFibers<TBase extends AgentLike>(Base: TBase, options?: {
     _fiberRecoveryInProgress: boolean; /** @internal */
     _fiberLastCleanupTime: number; /** @internal */
     _fiberDebug(msg: string, ...args: unknown[]): void; /** @internal */
-    _cf_fiberHeartbeat(): Promise<void>;
-    keepAlive(): Promise<() => void>;
+    _cf_keepAliveHeartbeat(): Promise<void>;
     spawnFiber(methodName: keyof /*elided*/any, payload?: unknown, options?: {
       maxRetries?: number;
     }): string;
@@ -93,26 +92,16 @@ declare function withFibers<TBase extends AgentLike>(Base: TBase, options?: {
     _checkInterruptedFibers(): Promise<void>; /** @internal */
     _cleanupOrphanedHeartbeats(): void; /** @internal */
     _maybeCleanupFibers(): void;
+    readonly alarm: () => Promise<void>;
     sql: <T = Record<string, string | number | boolean | null>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]) => T[];
     scheduleEvery: <T = string>(intervalSeconds: number, callback: keyof Agent<Cloudflare.Env, unknown, Record<string, unknown>>, payload?: T | undefined, options?: {
       retry?: RetryOptions;
     }) => Promise<Schedule<T>>;
     cancelSchedule: (id: string) => Promise<boolean>;
-    readonly alarm: () => Promise<void>;
+    keepAlive: () => Promise<() => void>;
+    keepAliveWhile: <T>(fn: () => Promise<T>) => Promise<T>;
   };
 } & TBase;
-/**
- * Keep a Durable Object alive via a scheduled heartbeat.
- * Returns a disposer function that cancels the heartbeat.
- *
- * Standalone version usable by any Agent subclass without requiring
- * the full fiber mixin. The agent must have a no-op method with the
- * given callbackName for the scheduler to invoke.
- *
- * @param agent - The agent instance (must have scheduleEvery and cancelSchedule)
- * @param callbackName - Name of a no-op method on the agent class (must exist)
- */
-declare function keepAlive(agent: Pick<Agent<Cloudflare.Env>, "scheduleEvery" | "cancelSchedule">, callbackName: string): Promise<() => void>;
 //#endregion
-export { FiberCompleteContext, FiberContext, FiberRecoveryContext, FiberState, keepAlive, withFibers };
+export { FiberCompleteContext, FiberContext, FiberRecoveryContext, FiberState, withFibers };
 //# sourceMappingURL=forever.d.ts.map

package/dist/experimental/forever.js

@@ -33,8 +33,6 @@ import { nanoid } from "nanoid";
 *
 * @experimental This API is not yet stable and may change.
 */
-console.warn("[agents/experimental/forever] WARNING: You are using an experimental API that WILL break between releases. Do not use in production.");
-const KEEP_ALIVE_INTERVAL_MS = 1e4;
 const FIBER_CLEANUP_INTERVAL_MS = 600 * 1e3;
 const FIBER_CLEANUP_COMPLETED_MS = 1440 * 60 * 1e3;
 const FIBER_CLEANUP_FAILED_MS = 10080 * 60 * 1e3;
@@ -47,6 +45,7 @@ function withFibers(Base, options) {
 			this._fiberActiveFibers = /* @__PURE__ */ new Set();
 			this._fiberRecoveryInProgress = false;
 			this._fiberLastCleanupTime = 0;
+			console.warn("[agents/experimental/forever] WARNING: You are using an experimental API that WILL break between releases. Do not use in production.");
 			this.sql`
         CREATE TABLE IF NOT EXISTS cf_agents_fibers (
           id TEXT PRIMARY KEY NOT NULL,
@@ -69,21 +68,9 @@ function withFibers(Base, options) {
 		/** @internal */ _fiberDebug(msg, ...args) {
 			if (debugEnabled) console.debug(`[fiber] ${msg}`, ...args);
 		}
-		/** @internal */ async _cf_fiberHeartbeat() {
+		/** @internal */ async _cf_keepAliveHeartbeat() {
 			await this._checkInterruptedFibers();
 		}
-		async keepAlive() {
-			const heartbeatSeconds = Math.ceil(KEEP_ALIVE_INTERVAL_MS / 1e3);
-			const schedule = await this.scheduleEvery(heartbeatSeconds, "_cf_fiberHeartbeat");
-			this._fiberDebug("keepAlive started, schedule=%s", schedule.id);
-			let disposed = false;
-			return () => {
-				if (disposed) return;
-				disposed = true;
-				this._fiberDebug("keepAlive disposed, schedule=%s", schedule.id);
-				this.cancelSchedule(schedule.id);
-			};
-		}
 		spawnFiber(methodName, payload, options) {
 			this._maybeCleanupFibers();
 			const name = methodName;
@@ -333,7 +320,7 @@ function withFibers(Base, options) {
 		/** @internal */ _cleanupOrphanedHeartbeats() {
 			this.sql`
         DELETE FROM cf_agents_schedules
-        WHERE callback = '_cf_fiberHeartbeat'
+        WHERE callback = '_cf_keepAliveHeartbeat'
       `;
 			this._fiberDebug("cleaned up orphaned heartbeat schedules");
 		}
@@ -354,28 +341,7 @@ function withFibers(Base, options) {
 	}
 	return FiberAgent;
 }
-/**
-* Keep a Durable Object alive via a scheduled heartbeat.
-* Returns a disposer function that cancels the heartbeat.
-*
-* Standalone version usable by any Agent subclass without requiring
-* the full fiber mixin. The agent must have a no-op method with the
-* given callbackName for the scheduler to invoke.
-*
-* @param agent - The agent instance (must have scheduleEvery and cancelSchedule)
-* @param callbackName - Name of a no-op method on the agent class (must exist)
-*/
-async function keepAlive(agent, callbackName) {
-	const heartbeatSeconds = Math.ceil(KEEP_ALIVE_INTERVAL_MS / 1e3);
-	const schedule = await agent.scheduleEvery(heartbeatSeconds, callbackName);
-	let disposed = false;
-	return () => {
-		if (disposed) return;
-		disposed = true;
-		agent.cancelSchedule(schedule.id);
-	};
-}
 
 //#endregion
-export { keepAlive, withFibers };
+export { withFibers };
 //# sourceMappingURL=forever.js.map