agents 0.0.0-f6c26e4 → 0.0.0-f7bd395

package/src/index.ts

@@ -1,3 +1,4 @@
+import type { env } from "cloudflare:workers";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
@@ -25,6 +26,7 @@ import { MCPClientManager } from "./mcp/client";
 // import type { MCPClientConnection } from "./mcp/client-connection";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider";
 import { genericObservability, type Observability } from "./observability";
+import { MessageType } from "./ai-types";
 
 export type { Connection, ConnectionContext, WSMessage } from "partyserver";
 
@@ -42,7 +44,7 @@ export type RPCRequest = {
  * State update message from client
  */
 export type StateUpdateMessage = {
-  type: "cf_agent_state";
+  type: MessageType.CF_AGENT_STATE;
   state: unknown;
 };
 
@@ -50,7 +52,7 @@ export type StateUpdateMessage = {
  * RPC response message to client
  */
 export type RPCResponse = {
-  type: "rpc";
+  type: MessageType.RPC;
   id: string;
 } & (
   | {
@@ -77,7 +79,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 &&
@@ -95,7 +97,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
   );
 }
@@ -116,7 +118,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
@@ -130,6 +132,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;
@@ -182,7 +201,7 @@ function getNextCronTime(cron: string) {
  * MCP Server state update message from server -> Client
  */
 export type MCPServerMessage = {
-  type: "cf_agent_mcp_servers";
+  type: MessageType.CF_AGENT_MCP_SERVERS;
   mcp: MCPServersState;
 };
 
@@ -271,7 +290,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);
     });
@@ -283,7 +308,11 @@ 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, 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 _ParentClass: typeof Agent<Env, State> =
@@ -446,7 +475,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
             this.broadcast(
               JSON.stringify({
                 mcp: this.getMcpServers(),
-                type: "cf_agent_mcp_servers"
+                type: MessageType.CF_AGENT_MCP_SERVERS
               })
             );
 
@@ -515,10 +544,8 @@ export class Agent<Env, State = unknown> extends Server<Env> {
                   displayMessage: `RPC call to ${method}`,
                   id: nanoid(),
                   payload: {
-                    args,
                     method,
-                    streaming: metadata?.streaming,
-                    success: true
+                    streaming: metadata?.streaming
                   },
                   timestamp: Date.now(),
                   type: "rpc"
@@ -531,7 +558,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
                 id,
                 result,
                 success: true,
-                type: "rpc"
+                type: MessageType.RPC
               };
               connection.send(JSON.stringify(response));
             } catch (e) {
@@ -541,7 +568,7 @@ export class Agent<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);
@@ -560,44 +587,42 @@ export class Agent<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,
@@ -606,15 +631,22 @@ export class Agent<Env, State = unknown> extends Server<Env> {
           email: undefined
         },
         async () => {
-          const servers = this.sql<MCPServerRow>`
+          await this._tryCatch(() => {
+            const servers = this.sql<MCPServerRow>`
             SELECT id, name, server_url, client_id, auth_url, callback_url, server_options FROM cf_agents_mcp_servers;
           `;
 
-          // 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) {
-            Promise.allSettled(
-              servers.map((server) => {
-                return this._connectToMcpServerInternal(
+            this.broadcast(
+              JSON.stringify({
+                mcp: this.getMcpServers(),
+                type: MessageType.CF_AGENT_MCP_SERVERS
+              })
+            );
+
+            // 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) {
+              servers.forEach((server) => {
+                this._connectToMcpServerInternal(
                   server.name,
                   server.server_url,
                   server.callback_url,
@@ -625,18 +657,33 @@ export class Agent<Env, State = unknown> extends Server<Env> {
                     id: server.id,
                     oauthClientId: server.client_id ?? undefined
                   }
-                );
-              })
-            ).then((_results) => {
-              this.broadcast(
-                JSON.stringify({
-                  mcp: this.getMcpServers(),
-                  type: "cf_agent_mcp_servers"
-                })
-              );
-            });
-          }
-          await this._tryCatch(() => _onStart());
+                )
+                  .then(() => {
+                    // Broadcast updated MCP servers state after each server connects
+                    this.broadcast(
+                      JSON.stringify({
+                        mcp: this.getMcpServers(),
+                        type: MessageType.CF_AGENT_MCP_SERVERS
+                      })
+                    );
+                  })
+                  .catch((error) => {
+                    console.error(
+                      `Error connecting to MCP server: ${server.name} (${server.server_url})`,
+                      error
+                    );
+                    // Still broadcast even if connection fails, so clients know about the failure
+                    this.broadcast(
+                      JSON.stringify({
+                        mcp: this.getMcpServers(),
+                        type: MessageType.CF_AGENT_MCP_SERVERS
+                      })
+                    );
+                  });
+              });
+            }
+            return _onStart(props);
+          });
         }
       );
     };
@@ -646,7 +693,6 @@ export class Agent<Env, State = unknown> extends Server<Env> {
     state: State,
     source: Connection | "server" = "server"
   ) {
-    const previousState = this._state;
     this._state = state;
     this.sql`
     INSERT OR REPLACE INTO cf_agents_state (id, state)
@@ -659,7 +705,7 @@ export class Agent<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] : []
     );
@@ -672,10 +718,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
             {
               displayMessage: "State updated",
               id: nanoid(),
-              payload: {
-                previousState,
-                state
-              },
+              payload: {},
               timestamp: Date.now(),
               type: "state:update"
             },
@@ -815,41 +858,37 @@ export class Agent<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);
@@ -927,7 +966,6 @@ export class Agent<Env, State = unknown> extends Server<Env> {
     }
     this._flushingQueue = true;
     while (true) {
-      const executed: string[] = [];
       const result = this.sql<QueueItem<string>>`
       SELECT * FROM cf_agents_queues
       ORDER BY created_at ASC
@@ -959,13 +997,10 @@ export class Agent<Env, State = unknown> extends Server<Env> {
                 queueItem: QueueItem<string>
               ) => Promise<void>
             ).bind(this)(JSON.parse(row.payload as string), row);
-            executed.push(row.id);
+            await this.dequeue(row.id);
           }
         );
       }
-      for (const id of executed) {
-        await this.dequeue(id);
-      }
     }
     this._flushingQueue = false;
   }
@@ -1040,7 +1075,10 @@ export class Agent<Env, State = unknown> extends Server<Env> {
         {
           displayMessage: `Schedule ${schedule.id} created`,
           id: nanoid(),
-          payload: schedule,
+          payload: {
+            callback: callback as string,
+            id: id
+          },
           timestamp: Date.now(),
           type: "schedule:create"
         },
@@ -1210,7 +1248,10 @@ export class Agent<Env, State = unknown> extends Server<Env> {
         {
           displayMessage: `Schedule ${id} cancelled`,
           id: nanoid(),
-          payload: schedule,
+          payload: {
+            callback: schedule.callback,
+            id: schedule.id
+          },
           timestamp: Date.now(),
           type: "schedule:cancel"
         },
@@ -1226,9 +1267,9 @@ export class Agent<Env, State = unknown> extends Server<Env> {
   private async _scheduleNextAlarm() {
     // Find the next schedule that needs to be executed
     const result = this.sql`
-      SELECT time FROM cf_agents_schedules 
+      SELECT time FROM cf_agents_schedules
       WHERE time > ${Math.floor(Date.now() / 1000)}
-      ORDER BY time ASC 
+      ORDER BY time ASC
       LIMIT 1
     `;
     if (!result) return;
@@ -1275,7 +1316,10 @@ export class Agent<Env, State = unknown> extends Server<Env> {
                 {
                   displayMessage: `Schedule ${row.id} executed`,
                   id: nanoid(),
-                  payload: row,
+                  payload: {
+                    callback: row.callback,
+                    id: row.id
+                  },
                   timestamp: Date.now(),
                   type: "schedule:execute"
                 },
@@ -1395,7 +1439,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
     this.broadcast(
       JSON.stringify({
         mcp: this.getMcpServers(),
-        type: "cf_agent_mcp_servers"
+        type: MessageType.CF_AGENT_MCP_SERVERS
       })
     );
 
@@ -1484,7 +1528,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
     this.broadcast(
       JSON.stringify({
         mcp: this.getMcpServers(),
-        type: "cf_agent_mcp_servers"
+        type: MessageType.CF_AGENT_MCP_SERVERS
       })
     );
   }
@@ -1696,6 +1740,13 @@ export type EmailRoutingOptions<Env> = AgentOptions<Env> & {
   resolver: EmailResolver<Env>;
 };
 
+// Cache the agent namespace map for email routing
+// This maps both kebab-case and original names to namespaces
+const agentMapCache = new WeakMap<
+  Record<string, unknown>,
+  Record<string, unknown>
+>();
+
 /**
  * Route an email to the appropriate Agent
  * @param email The email to route
@@ -1715,28 +1766,41 @@ export async function routeAgentEmail<Env>(
     return;
   }
 
-  const namespaceBinding = env[routingInfo.agentName as keyof Env];
-  if (!namespaceBinding) {
-    throw new Error(
-      `Agent namespace '${routingInfo.agentName}' not found in environment`
-    );
+  // Build a map that includes both original names and kebab-case versions
+  if (!agentMapCache.has(env as Record<string, unknown>)) {
+    const map: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(env as Record<string, unknown>)) {
+      if (
+        value &&
+        typeof value === "object" &&
+        "idFromName" in value &&
+        typeof value.idFromName === "function"
+      ) {
+        // Add both the original name and kebab-case version
+        map[key] = value;
+        map[camelCaseToKebabCase(key)] = value;
+      }
+    }
+    agentMapCache.set(env as Record<string, unknown>, map);
   }
 
-  // Type guard to check if this is actually a DurableObjectNamespace (AgentNamespace)
-  if (
-    typeof namespaceBinding !== "object" ||
-    !("idFromName" in namespaceBinding) ||
-    typeof namespaceBinding.idFromName !== "function"
-  ) {
+  const agentMap = agentMapCache.get(env as Record<string, unknown>)!;
+  const namespace = agentMap[routingInfo.agentName];
+
+  if (!namespace) {
+    // Provide helpful error message listing available agents
+    const availableAgents = Object.keys(agentMap)
+      .filter((key) => !key.includes("-")) // Show only original names, not kebab-case duplicates
+      .join(", ");
     throw new Error(
-      `Environment binding '${routingInfo.agentName}' is not an AgentNamespace (found: ${typeof namespaceBinding})`
+      `Agent namespace '${routingInfo.agentName}' not found in environment. Available agents: ${availableAgents}`
     );
   }
 
-  // Safe cast after runtime validation
-  const namespace = namespaceBinding as unknown as AgentNamespace<Agent<Env>>;
-
-  const agent = await getAgentByName(namespace, routingInfo.agentId);
+  const agent = await getAgentByName(
+    namespace as unknown as AgentNamespace<Agent<Env>>,
+    routingInfo.agentId
+  );
 
   // let's make a serialisable version of the email
   const serialisableEmail: AgentEmail = {
@@ -1815,12 +1879,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);
@@ -1852,7 +1921,7 @@ export class StreamingResponse {
       id: this._id,
       result: chunk,
       success: true,
-      type: "rpc"
+      type: MessageType.RPC
     };
     this._connection.send(JSON.stringify(response));
   }
@@ -1871,7 +1940,7 @@ export class StreamingResponse {
       id: this._id,
       result: finalChunk,
       success: true,
-      type: "rpc"
+      type: MessageType.RPC
     };
     this._connection.send(JSON.stringify(response));
   }