agents 0.0.0-2a6e66e → 0.0.0-2bea91f

package/src/index.ts

@@ -22,10 +22,13 @@ import {
   routePartykitRequest
 } from "partyserver";
 import { camelCaseToKebabCase } from "./client";
-import { MCPClientManager } from "./mcp/client";
-// import type { MCPClientConnection } from "./mcp/client-connection";
+import { MCPClientManager, type MCPClientOAuthResult } from "./mcp/client";
+import type { MCPConnectionState } from "./mcp/client-connection";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider";
+import type { TransportType } from "./mcp/types";
 import { genericObservability, type Observability } from "./observability";
+import { DisposableStore } from "./core/events";
+import { MessageType } from "./ai-types";
 
 export type { Connection, ConnectionContext, WSMessage } from "partyserver";
 
@@ -43,7 +46,7 @@ export type RPCRequest = {
  * State update message from client
  */
 export type StateUpdateMessage = {
-  type: "cf_agent_state";
+  type: MessageType.CF_AGENT_STATE;
   state: unknown;
 };
 
@@ -51,7 +54,7 @@ export type StateUpdateMessage = {
  * RPC response message to client
  */
 export type RPCResponse = {
-  type: "rpc";
+  type: MessageType.RPC;
   id: string;
 } & (
   | {
@@ -78,7 +81,7 @@ function isRPCRequest(msg: unknown): msg is RPCRequest {
     typeof msg === "object" &&
     msg !== null &&
     "type" in msg &&
-    msg.type === "rpc" &&
+    msg.type === MessageType.RPC &&
     "id" in msg &&
     typeof msg.id === "string" &&
     "method" in msg &&
@@ -96,7 +99,7 @@ function isStateUpdateMessage(msg: unknown): msg is StateUpdateMessage {
     typeof msg === "object" &&
     msg !== null &&
     "type" in msg &&
-    msg.type === "cf_agent_state" &&
+    msg.type === MessageType.CF_AGENT_STATE &&
     "state" in msg
   );
 }
@@ -117,7 +120,7 @@ const callableMetadata = new Map<Function, CallableMetadata>();
  * Decorator that marks a method as callable by clients
  * @param metadata Optional metadata about the callable method
  */
-export function unstable_callable(metadata: CallableMetadata = {}) {
+export function callable(metadata: CallableMetadata = {}) {
   return function callableDecorator<This, Args extends unknown[], Return>(
     target: (this: This, ...args: Args) => Return,
     // biome-ignore lint/correctness/noUnusedFunctionParameters: later
@@ -131,6 +134,23 @@ export function unstable_callable(metadata: CallableMetadata = {}) {
   };
 }
 
+let didWarnAboutUnstableCallable = false;
+
+/**
+ * Decorator that marks a method as callable by clients
+ * @deprecated this has been renamed to callable, and unstable_callable will be removed in the next major version
+ * @param metadata Optional metadata about the callable method
+ */
+export const unstable_callable = (metadata: CallableMetadata = {}) => {
+  if (!didWarnAboutUnstableCallable) {
+    didWarnAboutUnstableCallable = true;
+    console.warn(
+      "unstable_callable is deprecated, use callable instead. unstable_callable will be removed in the next major version."
+    );
+  }
+  callable(metadata);
+};
+
 export type QueueItem<T = string> = {
   id: string;
   payload: T;
@@ -179,11 +199,13 @@ function getNextCronTime(cron: string) {
   return interval.getNextDate();
 }
 
+export type { TransportType } from "./mcp/types";
+
 /**
  * MCP Server state update message from server -> Client
  */
 export type MCPServerMessage = {
-  type: "cf_agent_mcp_servers";
+  type: MessageType.CF_AGENT_MCP_SERVERS;
   mcp: MCPServersState;
 };
 
@@ -203,7 +225,7 @@ export type MCPServer = {
   // This state is specifically about the temporary process of getting a token (if needed).
   // Scope outside of that can't be relied upon because when the DO sleeps, there's no way
   // to communicate a change to a non-ready state.
-  state: "authenticating" | "connecting" | "ready" | "discovering" | "failed";
+  state: MCPConnectionState;
   instructions: string | null;
   capabilities: ServerCapabilities | null;
 };
@@ -272,7 +294,13 @@ function withAgentContext<T extends (...args: any[]) => any>(
   method: T
 ): (this: Agent<unknown, unknown>, ...args: Parameters<T>) => ReturnType<T> {
   return function (...args: Parameters<T>): ReturnType<T> {
-    const { connection, request, email } = getCurrentAgent();
+    const { connection, request, email, agent } = getCurrentAgent();
+
+    if (agent === this) {
+      // already wrapped, so we can just call the method
+      return method.apply(this, args);
+    }
+    // not wrapped, so we need to wrap it
     return agentContext.run({ agent: this, connection, request, email }, () => {
       return method.apply(this, args);
     });
@@ -284,13 +312,21 @@ function withAgentContext<T extends (...args: any[]) => any>(
  * @template Env Environment type containing bindings
  * @template State State type to store within the Agent
  */
-export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
+export class Agent<
+  Env = typeof env,
+  State = unknown,
+  Props extends Record<string, unknown> = Record<string, unknown>
+> extends Server<Env, Props> {
   private _state = DEFAULT_STATE as State;
+  private _disposables = new DisposableStore();
 
   private _ParentClass: typeof Agent<Env, State> =
     Object.getPrototypeOf(this).constructor;
 
-  mcp: MCPClientManager = new MCPClientManager(this._ParentClass.name, "0.0.1");
+  readonly mcp: MCPClientManager = new MCPClientManager(
+    this._ParentClass.name,
+    "0.0.1"
+  );
 
   /**
    * Initial state for the Agent
@@ -383,8 +419,25 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
   constructor(ctx: AgentContext, env: Env) {
     super(ctx, env);
 
-    // Auto-wrap custom methods with agent context
-    this._autoWrapCustomMethods();
+    if (!wrappedClasses.has(this.constructor)) {
+      // Auto-wrap custom methods with agent context
+      this._autoWrapCustomMethods();
+      wrappedClasses.add(this.constructor);
+    }
+
+    // Broadcast server state after background connects (for OAuth servers)
+    this._disposables.add(
+      this.mcp.onConnected(async () => {
+        this.broadcastMcpServers();
+      })
+    );
+
+    // Emit MCP observability events
+    this._disposables.add(
+      this.mcp.onObservabilityEvent((event) => {
+        this.observability?.emit(event);
+      })
+    );
 
     this.sql`
       CREATE TABLE IF NOT EXISTS cf_agents_state (
@@ -441,21 +494,24 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
         { agent: this, connection: undefined, request, email: undefined },
         async () => {
           if (this.mcp.isCallbackRequest(request)) {
-            await this.mcp.handleCallbackRequest(request);
-
-            // after the MCP connection handshake, we can send updated mcp state
-            this.broadcast(
-              JSON.stringify({
-                mcp: this.getMcpServers(),
-                type: "cf_agent_mcp_servers"
-              })
-            );
+            const result = await this.mcp.handleCallbackRequest(request);
+            this.broadcastMcpServers();
+
+            if (result.authSuccess) {
+              // Start background connection if auth was successful
+              this.mcp
+                .establishConnection(result.serverId)
+                .catch((error) => {
+                  console.error("Background connection failed:", error);
+                })
+                .finally(() => {
+                  // Broadcast after background connection resolves (success/failure)
+                  this.broadcastMcpServers();
+                });
+            }
 
-            // We probably should let the user configure this response/redirect, but this is fine for now.
-            return new Response("<script>window.close();</script>", {
-              headers: { "content-type": "text/html" },
-              status: 200
-            });
+            // Handle OAuth callback response using MCPClientManager configuration
+            return this.handleOAuthCallbackResponse(result, request);
           }
 
           return this._tryCatch(() => _onRequest(request));
@@ -530,7 +586,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
                 id,
                 result,
                 success: true,
-                type: "rpc"
+                type: MessageType.RPC
               };
               connection.send(JSON.stringify(response));
             } catch (e) {
@@ -540,7 +596,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
                   e instanceof Error ? e.message : "Unknown error occurred",
                 id: parsed.id,
                 success: false,
-                type: "rpc"
+                type: MessageType.RPC
               };
               connection.send(JSON.stringify(response));
               console.error("RPC error:", e);
@@ -559,44 +615,42 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
       // must fix this
       return agentContext.run(
         { agent: this, connection, request: ctx.request, email: undefined },
-        async () => {
-          setTimeout(() => {
-            if (this.state) {
-              connection.send(
-                JSON.stringify({
-                  state: this.state,
-                  type: "cf_agent_state"
-                })
-              );
-            }
-
+        () => {
+          if (this.state) {
             connection.send(
               JSON.stringify({
-                mcp: this.getMcpServers(),
-                type: "cf_agent_mcp_servers"
+                state: this.state,
+                type: MessageType.CF_AGENT_STATE
               })
             );
+          }
 
-            this.observability?.emit(
-              {
-                displayMessage: "Connection established",
-                id: nanoid(),
-                payload: {
-                  connectionId: connection.id
-                },
-                timestamp: Date.now(),
-                type: "connect"
+          connection.send(
+            JSON.stringify({
+              mcp: this.getMcpServers(),
+              type: MessageType.CF_AGENT_MCP_SERVERS
+            })
+          );
+
+          this.observability?.emit(
+            {
+              displayMessage: "Connection established",
+              id: nanoid(),
+              payload: {
+                connectionId: connection.id
               },
-              this.ctx
-            );
-            return this._tryCatch(() => _onConnect(connection, ctx));
-          }, 20);
+              timestamp: Date.now(),
+              type: "connect"
+            },
+            this.ctx
+          );
+          return this._tryCatch(() => _onConnect(connection, ctx));
         }
       );
     };
 
     const _onStart = this.onStart.bind(this);
-    this.onStart = async () => {
+    this.onStart = async (props?: Props) => {
       return agentContext.run(
         {
           agent: this,
@@ -610,15 +664,20 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
             SELECT id, name, server_url, client_id, auth_url, callback_url, server_options FROM cf_agents_mcp_servers;
           `;
 
-            this.broadcast(
-              JSON.stringify({
-                mcp: this.getMcpServers(),
-                type: "cf_agent_mcp_servers"
-              })
-            );
+            this.broadcastMcpServers();
 
             // from DO storage, reconnect to all servers not currently in the oauth flow using our saved auth information
             if (servers && Array.isArray(servers) && servers.length > 0) {
+              // Restore callback URLs for OAuth-enabled servers
+              servers.forEach((server) => {
+                if (server.callback_url) {
+                  // Register the full redirect URL including serverId to avoid ambiguous matches
+                  this.mcp.registerCallbackUrl(
+                    `${server.callback_url}/${server.id}`
+                  );
+                }
+              });
+
               servers.forEach((server) => {
                 this._connectToMcpServerInternal(
                   server.name,
@@ -634,12 +693,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
                 )
                   .then(() => {
                     // Broadcast updated MCP servers state after each server connects
-                    this.broadcast(
-                      JSON.stringify({
-                        mcp: this.getMcpServers(),
-                        type: "cf_agent_mcp_servers"
-                      })
-                    );
+                    this.broadcastMcpServers();
                   })
                   .catch((error) => {
                     console.error(
@@ -647,16 +701,11 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
                       error
                     );
                     // Still broadcast even if connection fails, so clients know about the failure
-                    this.broadcast(
-                      JSON.stringify({
-                        mcp: this.getMcpServers(),
-                        type: "cf_agent_mcp_servers"
-                      })
-                    );
+                    this.broadcastMcpServers();
                   });
               });
             }
-            return _onStart();
+            return _onStart(props);
           });
         }
       );
@@ -679,7 +728,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
     this.broadcast(
       JSON.stringify({
         state: state,
-        type: "cf_agent_state"
+        type: MessageType.CF_AGENT_STATE
       }),
       source !== "server" ? [source.id] : []
     );
@@ -832,41 +881,37 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
     while (proto && proto !== Object.prototype && depth < 10) {
       const methodNames = Object.getOwnPropertyNames(proto);
       for (const methodName of methodNames) {
-        // Skip if it's a private method or not a function
+        const descriptor = Object.getOwnPropertyDescriptor(proto, methodName);
+
+        // Skip if it's a private method, a base method, a getter, or not a function,
         if (
           baseMethods.has(methodName) ||
           methodName.startsWith("_") ||
-          typeof this[methodName as keyof this] !== "function"
+          !descriptor ||
+          !!descriptor.get ||
+          typeof descriptor.value !== "function"
         ) {
           continue;
         }
-        // If the method doesn't exist in base prototypes, it's a custom method
-        if (!baseMethods.has(methodName)) {
-          const descriptor = Object.getOwnPropertyDescriptor(proto, methodName);
-          if (descriptor && typeof descriptor.value === "function") {
-            // Wrap the custom method with context
-
-            const wrappedFunction = withAgentContext(
-              // biome-ignore lint/suspicious/noExplicitAny: I can't typescript
-              this[methodName as keyof this] as (...args: any[]) => any
-              // biome-ignore lint/suspicious/noExplicitAny: I can't typescript
-            ) as any;
-
-            // if the method is callable, copy the metadata from the original method
-            if (this._isCallable(methodName)) {
-              callableMetadata.set(
-                wrappedFunction,
-                callableMetadata.get(
-                  this[methodName as keyof this] as Function
-                )!
-              );
-            }
 
-            // set the wrapped function on the prototype
-            this.constructor.prototype[methodName as keyof this] =
-              wrappedFunction;
-          }
+        // Now, methodName is confirmed to be a custom method/function
+        // Wrap the custom method with context
+        const wrappedFunction = withAgentContext(
+          // biome-ignore lint/suspicious/noExplicitAny: I can't typescript
+          this[methodName as keyof this] as (...args: any[]) => any
+          // biome-ignore lint/suspicious/noExplicitAny: I can't typescript
+        ) as any;
+
+        // if the method is callable, copy the metadata from the original method
+        if (this._isCallable(methodName)) {
+          callableMetadata.set(
+            wrappedFunction,
+            callableMetadata.get(this[methodName as keyof this] as Function)!
+          );
         }
+
+        // set the wrapped function on the prototype
+        this.constructor.prototype[methodName as keyof this] = wrappedFunction;
       }
 
       proto = Object.getPrototypeOf(proto);
@@ -1349,6 +1394,8 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
     // delete all alarms
     await this.ctx.storage.deleteAlarm();
     await this.ctx.storage.deleteAll();
+    this._disposables.dispose();
+    await this.mcp.dispose?.();
     this.ctx.abort("destroyed"); // enforce that the agent is evicted
 
     this.observability?.emit(
@@ -1374,25 +1421,42 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
   /**
    * Connect to a new MCP Server
    *
+   * @param serverName Name of the MCP server
    * @param url MCP Server SSE URL
-   * @param callbackHost Base host for the agent, used for the redirect URI.
+   * @param callbackHost Base host for the agent, used for the redirect URI. If not provided, will be derived from the current request.
    * @param agentsPrefix agents routing prefix if not using `agents`
-   * @param options MCP client and transport (header) options
+   * @param options MCP client and transport options
    * @returns authUrl
    */
   async addMcpServer(
     serverName: string,
     url: string,
-    callbackHost: string,
+    callbackHost?: string,
     agentsPrefix = "agents",
     options?: {
       client?: ConstructorParameters<typeof Client>[1];
       transport?: {
-        headers: HeadersInit;
+        headers?: HeadersInit;
+        type?: TransportType;
       };
     }
   ): Promise<{ id: string; authUrl: string | undefined }> {
-    const callbackUrl = `${callbackHost}/${agentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
+    // If callbackHost is not provided, derive it from the current request
+    let resolvedCallbackHost = callbackHost;
+    if (!resolvedCallbackHost) {
+      const { request } = getCurrentAgent();
+      if (!request) {
+        throw new Error(
+          "callbackHost is required when not called within a request context"
+        );
+      }
+
+      // Extract the origin from the request
+      const requestUrl = new URL(request.url);
+      resolvedCallbackHost = `${requestUrl.protocol}//${requestUrl.host}`;
+    }
+
+    const callbackUrl = `${resolvedCallbackHost}/${agentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
 
     const result = await this._connectToMcpServerInternal(
       serverName,
@@ -1400,6 +1464,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
       callbackUrl,
       options
     );
+
     this.sql`
         INSERT
         OR REPLACE INTO cf_agents_mcp_servers (id, name, server_url, client_id, auth_url, callback_url, server_options)
@@ -1414,17 +1479,12 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
         );
     `;
 
-    this.broadcast(
-      JSON.stringify({
-        mcp: this.getMcpServers(),
-        type: "cf_agent_mcp_servers"
-      })
-    );
+    this.broadcastMcpServers();
 
     return result;
   }
 
-  async _connectToMcpServerInternal(
+  private async _connectToMcpServerInternal(
     _serverName: string,
     url: string,
     callbackUrl: string,
@@ -1440,6 +1500,7 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
        */
       transport?: {
         headers?: HeadersInit;
+        type?: TransportType;
       };
     },
     reconnect?: {
@@ -1464,6 +1525,9 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
       }
     }
 
+    // Use the transport type specified in options, or default to "auto"
+    const transportType: TransportType = options?.transport?.type ?? "auto";
+
     // allows passing through transport headers if necessary
     // this handles some non-standard bearer auth setups (i.e. MCP server behind CF access instead of OAuth)
     let headerTransportOpts: SSEClientTransportOptions = {};
@@ -1487,7 +1551,8 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
       reconnect,
       transport: {
         ...headerTransportOpts,
-        authProvider
+        authProvider,
+        type: transportType
       }
     });
 
@@ -1500,15 +1565,11 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
 
   async removeMcpServer(id: string) {
     this.mcp.closeConnection(id);
+    this.mcp.unregisterCallbackUrl(id);
     this.sql`
       DELETE FROM cf_agents_mcp_servers WHERE id = ${id};
     `;
-    this.broadcast(
-      JSON.stringify({
-        mcp: this.getMcpServers(),
-        type: "cf_agent_mcp_servers"
-      })
-    );
+    this.broadcastMcpServers();
   }
 
   getMcpServers(): MCPServersState {
@@ -1540,8 +1601,53 @@ export class Agent<Env = typeof env, State = unknown> extends Server<Env> {
 
     return mcpState;
   }
+
+  private broadcastMcpServers() {
+    this.broadcast(
+      JSON.stringify({
+        mcp: this.getMcpServers(),
+        type: MessageType.CF_AGENT_MCP_SERVERS
+      })
+    );
+  }
+
+  /**
+   * Handle OAuth callback response using MCPClientManager configuration
+   * @param result OAuth callback result
+   * @param request The original request (needed for base URL)
+   * @returns Response for the OAuth callback
+   */
+  private handleOAuthCallbackResponse(
+    result: MCPClientOAuthResult,
+    request: Request
+  ): Response {
+    const config = this.mcp.getOAuthCallbackConfig();
+
+    // Use custom handler if configured
+    if (config?.customHandler) {
+      return config.customHandler(result);
+    }
+
+    // Use redirect URLs if configured
+    if (config?.successRedirect && result.authSuccess) {
+      return Response.redirect(config.successRedirect);
+    }
+
+    if (config?.errorRedirect && !result.authSuccess) {
+      return Response.redirect(
+        `${config.errorRedirect}?error=${encodeURIComponent(result.authError || "Unknown error")}`
+      );
+    }
+
+    // Default behavior - redirect to base URL
+    const baseUrl = new URL(request.url).origin;
+    return Response.redirect(baseUrl);
+  }
 }
 
+// A set of classes that have been wrapped with agent context
+const wrappedClasses = new Set<typeof Agent.prototype.constructor>();
+
 /**
  * Namespace for creating Agent instances
  * @template Agentic Type of the Agent class
@@ -1857,12 +1963,17 @@ export type EmailSendOptions = {
  * @param options Options for Agent creation
  * @returns Promise resolving to an Agent instance stub
  */
-export async function getAgentByName<Env, T extends Agent<Env>>(
+export async function getAgentByName<
+  Env,
+  T extends Agent<Env>,
+  Props extends Record<string, unknown> = Record<string, unknown>
+>(
   namespace: AgentNamespace<T>,
   name: string,
   options?: {
     jurisdiction?: DurableObjectJurisdiction;
     locationHint?: DurableObjectLocationHint;
+    props?: Props;
   }
 ) {
   return getServerByName<Env, T>(namespace, name, options);
@@ -1894,7 +2005,7 @@ export class StreamingResponse {
       id: this._id,
       result: chunk,
       success: true,
-      type: "rpc"
+      type: MessageType.RPC
     };
     this._connection.send(JSON.stringify(response));
   }
@@ -1913,7 +2024,7 @@ export class StreamingResponse {
       id: this._id,
       result: finalChunk,
       success: true,
-      type: "rpc"
+      type: MessageType.RPC
     };
     this._connection.send(JSON.stringify(response));
   }