agents 0.0.0-931d633 → 0.0.0-93d3975

package/dist/{index-CITGJflw.d.ts → index-DUnsVDnf.d.ts}

@@ -1,87 +1,29 @@
+import { n as AgentEmail } from "./context-_sPQqJWv.js";
+import {
+  h as TransportType,
+  t as MCPClientManager,
+  u as MCPConnectionState
+} from "./client-C_M5uPrn.js";
+import { t as Observability } from "./index-CyDpAVHZ.js";
+import { n as MessageType } from "./ai-types-D_hTbf25.js";
+import {
+  Connection,
+  Connection as Connection$1,
+  ConnectionContext,
+  PartyServerOptions,
+  Server,
+  WSMessage
+} from "partyserver";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
-  ServerCapabilities,
-  Tool,
   Prompt,
   Resource,
+  ServerCapabilities,
+  Tool
 } from "@modelcontextprotocol/sdk/types.js";
-import { Server, Connection, PartyServerOptions } from "partyserver";
-import { MCPClientManager } from "./mcp/client.js";
-import { Message } from "ai";
+import { env } from "cloudflare:workers";
 
-type BaseEvent<
-  T extends string,
-  Payload extends Record<string, unknown> = {},
-> = {
-  type: T;
-  /**
-   * The unique identifier for the event
-   */
-  id: string;
-  /**
-   * The message to display in the logs for this event, should the implementation choose to display
-   * a human-readable message.
-   */
-  displayMessage: string;
-  /**
-   * The payload of the event
-   */
-  payload: Payload;
-  /**
-   * The timestamp of the event in milliseconds since epoch
-   */
-  timestamp: number;
-};
-/**
- * The type of events that can be emitted by an Agent
- */
-type ObservabilityEvent =
-  | BaseEvent<
-      "state:update",
-      {
-        state: unknown;
-        previousState: unknown;
-      }
-    >
-  | BaseEvent<
-      "rpc",
-      {
-        method: string;
-        args: unknown[];
-        streaming?: boolean;
-        success: boolean;
-      }
-    >
-  | BaseEvent<
-      "message:request" | "message:response",
-      {
-        message: Message[];
-      }
-    >
-  | BaseEvent<"message:clear">
-  | BaseEvent<
-      "schedule:create" | "schedule:execute" | "schedule:cancel",
-      Schedule<unknown>
-    >
-  | BaseEvent<"destroy">
-  | BaseEvent<
-      "connect",
-      {
-        connectionId: string;
-      }
-    >;
-interface Observability {
-  /**
-   * Emit an event for the Agent's observability implementation to handle.
-   * @param event - The event to emit
-   * @param ctx - The execution context of the invocation
-   */
-  emit(event: ObservabilityEvent, ctx: DurableObjectState): void;
-}
-/**
- * A generic observability implementation that logs events to the console.
- */
-declare const genericObservability: Observability;
+//#region src/index.d.ts
 
 /**
  * RPC request message from client
@@ -96,14 +38,14 @@ type RPCRequest = {
  * State update message from client
  */
 type StateUpdateMessage = {
-  type: "cf_agent_state";
+  type: MessageType.CF_AGENT_STATE;
   state: unknown;
 };
 /**
  * RPC response message to client
  */
 type RPCResponse = {
-  type: "rpc";
+  type: MessageType.RPC;
   id: string;
 } & (
   | {
@@ -134,12 +76,24 @@ type CallableMetadata = {
  * Decorator that marks a method as callable by clients
  * @param metadata Optional metadata about the callable method
  */
-declare function unstable_callable(
+declare function callable(
   metadata?: CallableMetadata
 ): <This, Args extends unknown[], Return>(
   target: (this: This, ...args: Args) => Return,
   context: ClassMethodDecoratorContext
 ) => (this: This, ...args: Args) => Return;
+/**
+ * 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
+ */
+declare const unstable_callable: (metadata?: CallableMetadata) => void;
+type QueueItem<T = string> = {
+  id: string;
+  payload: T;
+  callback: keyof Agent<unknown>;
+  created_at: number;
+};
 /**
  * Represents a scheduled task within an Agent
  * @template T Type of the payload data
@@ -179,41 +133,54 @@ type Schedule<T = string> = {
  * MCP Server state update message from server -> Client
  */
 type MCPServerMessage = {
-  type: "cf_agent_mcp_servers";
+  type: MessageType.CF_AGENT_MCP_SERVERS;
   mcp: MCPServersState;
 };
 type MCPServersState = {
   servers: {
     [id: string]: MCPServer;
   };
-  tools: Tool[];
-  prompts: Prompt[];
-  resources: Resource[];
+  tools: (Tool & {
+    serverId: string;
+  })[];
+  prompts: (Prompt & {
+    serverId: string;
+  })[];
+  resources: (Resource & {
+    serverId: string;
+  })[];
 };
 type MCPServer = {
   name: string;
   server_url: string;
   auth_url: string | null;
-  state: "authenticating" | "connecting" | "ready" | "discovering" | "failed";
+  state: MCPConnectionState;
   instructions: string | null;
   capabilities: ServerCapabilities | null;
 };
 declare function getCurrentAgent<
-  T extends Agent<unknown, unknown> = Agent<unknown, unknown>,
+  T extends Agent<unknown, unknown> = Agent<unknown, unknown>
 >(): {
   agent: T | undefined;
   connection: Connection | undefined;
-  request: Request<unknown, CfProperties<unknown>> | undefined;
+  request: Request | undefined;
+  email: AgentEmail | undefined;
 };
 /**
  * Base class for creating Agent implementations
  * @template Env Environment type containing bindings
  * @template State State type to store within the Agent
  */
-declare class Agent<Env, State = unknown> extends Server<Env> {
+declare class Agent<
+  Env = typeof env,
+  State = unknown,
+  Props extends Record<string, unknown> = Record<string, unknown>
+> extends Server<Env, Props> {
   private _state;
+  private _disposables;
+  private _destroyed;
   private _ParentClass;
-  mcp: MCPClientManager;
+  readonly mcp: MCPClientManager;
   /**
    * Initial state for the Agent
    * Override to provide default state values
@@ -259,17 +226,75 @@ declare class Agent<Env, State = unknown> extends Server<Env> {
    */
   onStateUpdate(state: State | undefined, source: Connection | "server"): void;
   /**
-   * Called when the Agent receives an email
+   * Called when the Agent receives an email via routeAgentEmail()
+   * Override this method to handle incoming emails
    * @param email Email message to process
    */
-  onEmail(email: ForwardableEmailMessage): Promise<void>;
+  _onEmail(email: AgentEmail): Promise<void>;
+  /**
+   * Reply to an email
+   * @param email The email to reply to
+   * @param options Options for the reply
+   * @returns void
+   */
+  replyToEmail(
+    email: AgentEmail,
+    options: {
+      fromName: string;
+      subject?: string | undefined;
+      body: string;
+      contentType?: string;
+      headers?: Record<string, string>;
+    }
+  ): Promise<void>;
   private _tryCatch;
+  /**
+   * Automatically wrap custom methods with agent context
+   * This ensures getCurrentAgent() works in all custom methods without decorators
+   */
+  private _autoWrapCustomMethods;
   onError(connection: Connection, error: unknown): void | Promise<void>;
   onError(error: unknown): void | Promise<void>;
   /**
    * Render content (not implemented in base class)
    */
   render(): void;
+  /**
+   * Queue a task to be executed in the future
+   * @param payload Payload to pass to the callback
+   * @param callback Name of the method to call
+   * @returns The ID of the queued task
+   */
+  queue<T = unknown>(callback: keyof this, payload: T): Promise<string>;
+  private _flushingQueue;
+  private _flushQueue;
+  /**
+   * Dequeue a task by ID
+   * @param id ID of the task to dequeue
+   */
+  dequeue(id: string): Promise<void>;
+  /**
+   * Dequeue all tasks
+   */
+  dequeueAll(): Promise<void>;
+  /**
+   * Dequeue all tasks by callback
+   * @param callback Name of the callback to dequeue
+   */
+  dequeueAllByCallback(callback: string): Promise<void>;
+  /**
+   * Get a queued task by ID
+   * @param id ID of the task to get
+   * @returns The task or undefined if not found
+   */
+  getQueue(id: string): Promise<QueueItem<string> | undefined>;
+  /**
+   * Get all queues by key and value
+   * @param key Key to filter by
+   * @param value Value to filter by
+   * @returns Array of matching QueueItem objects
+   */
+  getQueues(key: string, value: string): Promise<QueueItem<string>[]>;
   /**
    * Schedule a task to be executed in the future
    * @template T Type of the payload data
@@ -307,7 +332,7 @@ declare class Agent<Env, State = unknown> extends Server<Env> {
   /**
    * Cancel a scheduled task
    * @param id ID of the task to cancel
-   * @returns true if the task was cancelled, false otherwise
+   * @returns true if the task was cancelled, false if the task was not found
    */
   cancelSchedule(id: string): Promise<boolean>;
   private _scheduleNextAlarm;
@@ -332,55 +357,62 @@ declare class Agent<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
-   * @returns authUrl
+   * @param options MCP client and transport options
+   * @returns Server id and state - either "authenticating" with authUrl, or "ready"
+   * @throws If connection or discovery fails
    */
   addMcpServer(
     serverName: string,
     url: string,
-    callbackHost: string,
+    callbackHost?: string,
     agentsPrefix?: string,
     options?: {
       client?: ConstructorParameters<typeof Client>[1];
-      transport?: {
-        headers: HeadersInit;
-      };
-    }
-  ): Promise<{
-    id: string;
-    authUrl: string | undefined;
-  }>;
-  _connectToMcpServerInternal(
-    _serverName: string,
-    url: string,
-    callbackUrl: string,
-    options?: {
-      client?: ConstructorParameters<typeof Client>[1];
-      /**
-       * We don't expose the normal set of transport options because:
-       * 1) we can't serialize things like the auth provider or a fetch function into the DB for reconnection purposes
-       * 2) We probably want these options to be agnostic to the transport type (SSE vs Streamable)
-       *
-       * This has the limitation that you can't override fetch, but I think headers should handle nearly all cases needed (i.e. non-standard bearer auth).
-       */
       transport?: {
         headers?: HeadersInit;
+        type?: TransportType;
       };
-    },
-    reconnect?: {
-      id: string;
-      oauthClientId?: string;
     }
-  ): Promise<{
-    id: string;
-    authUrl: string | undefined;
-    clientId: string | undefined;
-  }>;
+  ): Promise<
+    | {
+        id: string;
+        state: typeof MCPConnectionState.AUTHENTICATING;
+        authUrl: string;
+      }
+    | {
+        id: string;
+        state: typeof MCPConnectionState.READY;
+        authUrl?: undefined;
+      }
+  >;
   removeMcpServer(id: string): Promise<void>;
   getMcpServers(): MCPServersState;
+  private broadcastMcpServers;
+  /**
+   * Handle MCP OAuth callback request if it's an OAuth callback.
+   *
+   * This method encapsulates the entire OAuth callback flow:
+   * 1. Checks if the request is an MCP OAuth callback
+   * 2. Processes the OAuth code exchange
+   * 3. Establishes the connection if successful
+   * 4. Broadcasts MCP server state updates
+   * 5. Returns the appropriate HTTP response
+   *
+   * @param request The incoming HTTP request
+   * @returns Response if this was an OAuth callback, null otherwise
+   */
+  private handleMcpOAuthCallback;
+  /**
+   * 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;
 }
 /**
  * Namespace for creating Agent instances
@@ -413,17 +445,62 @@ declare function routeAgentRequest<Env>(
   env: Env,
   options?: AgentOptions<Env>
 ): Promise<Response | null>;
+type EmailResolver<Env> = (
+  email: ForwardableEmailMessage,
+  env: Env
+) => Promise<{
+  agentName: string;
+  agentId: string;
+} | null>;
+/**
+ * Create a resolver that uses the message-id header to determine the agent to route the email to
+ * @returns A function that resolves the agent to route the email to
+ */
+declare function createHeaderBasedEmailResolver<Env>(): EmailResolver<Env>;
+/**
+ * Create a resolver that uses the email address to determine the agent to route the email to
+ * @param defaultAgentName The default agent name to use if the email address does not contain a sub-address
+ * @returns A function that resolves the agent to route the email to
+ */
+declare function createAddressBasedEmailResolver<Env>(
+  defaultAgentName: string
+): EmailResolver<Env>;
+/**
+ * Create a resolver that uses the agentName and agentId to determine the agent to route the email to
+ * @param agentName The name of the agent to route the email to
+ * @param agentId The id of the agent to route the email to
+ * @returns A function that resolves the agent to route the email to
+ */
+declare function createCatchAllEmailResolver<Env>(
+  agentName: string,
+  agentId: string
+): EmailResolver<Env>;
+type EmailRoutingOptions<Env> = AgentOptions<Env> & {
+  resolver: EmailResolver<Env>;
+};
 /**
  * Route an email to the appropriate Agent
- * @param email Email message to route
- * @param env Environment containing Agent bindings
- * @param options Routing options
+ * @param email The email to route
+ * @param env The environment containing the Agent bindings
+ * @param options The options for routing the email
+ * @returns A promise that resolves when the email has been routed
  */
 declare function routeAgentEmail<Env>(
-  _email: ForwardableEmailMessage,
-  _env: Env,
-  _options?: AgentOptions<Env>
+  email: ForwardableEmailMessage,
+  env: Env,
+  options: EmailRoutingOptions<Env>
 ): Promise<void>;
+type EmailSendOptions = {
+  to: string;
+  subject: string;
+  body: string;
+  contentType?: string;
+  headers?: Record<string, string>;
+  includeRoutingHeaders?: boolean;
+  agentName?: string;
+  agentId?: string;
+  domain?: string;
+};
 /**
  * Get or create an Agent by name
  * @template Env Environment type containing bindings
@@ -433,12 +510,17 @@ declare function routeAgentEmail<Env>(
  * @param options Options for Agent creation
  * @returns Promise resolving to an Agent instance stub
  */
-declare function getAgentByName<Env, T extends Agent<Env>>(
+declare 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;
   }
 ): Promise<DurableObjectStub<T>>;
 /**
@@ -460,27 +542,36 @@ declare class StreamingResponse {
    */
   end(finalChunk?: unknown): void;
 }
-
+//#endregion
 export {
-  Agent as A,
-  type CallableMetadata as C,
-  type MCPServersState as M,
-  type ObservabilityEvent as O,
-  type RPCRequest as R,
-  type StateUpdateMessage as S,
-  type AgentContext as a,
-  type Observability as b,
-  type RPCResponse as c,
-  type Schedule as d,
-  type MCPServerMessage as e,
-  type MCPServer as f,
-  genericObservability as g,
-  getCurrentAgent as h,
-  type AgentNamespace as i,
-  type AgentOptions as j,
-  routeAgentEmail as k,
-  getAgentByName as l,
-  StreamingResponse as m,
-  routeAgentRequest as r,
-  unstable_callable as u,
+  createCatchAllEmailResolver as C,
+  routeAgentEmail as D,
+  getCurrentAgent as E,
+  routeAgentRequest as O,
+  createAddressBasedEmailResolver as S,
+  getAgentByName as T,
+  Schedule as _,
+  CallableMetadata as a,
+  WSMessage as b,
+  EmailResolver as c,
+  MCPServer as d,
+  MCPServerMessage as f,
+  RPCResponse as g,
+  RPCRequest as h,
+  AgentOptions as i,
+  unstable_callable as k,
+  EmailRoutingOptions as l,
+  QueueItem as m,
+  AgentContext as n,
+  Connection$1 as o,
+  MCPServersState as p,
+  AgentNamespace as r,
+  ConnectionContext as s,
+  Agent as t,
+  EmailSendOptions as u,
+  StateUpdateMessage as v,
+  createHeaderBasedEmailResolver as w,
+  callable as x,
+  StreamingResponse as y
 };
+//# sourceMappingURL=index-DUnsVDnf.d.ts.map

package/dist/index.d.ts

@@ -1,31 +1,70 @@
-import "@modelcontextprotocol/sdk/client/index.js";
-import "@modelcontextprotocol/sdk/types.js";
-export { Connection, ConnectionContext, WSMessage } from "partyserver";
-import "./mcp/client.js";
+import { n as AgentEmail } from "./context-_sPQqJWv.js";
+import { h as TransportType } from "./client-C_M5uPrn.js";
+import "./mcp-CzbSsLfc.js";
+import "./do-oauth-client-provider-B-ryFIPr.js";
+import "./index-CyDpAVHZ.js";
+import "./ai-types-D_hTbf25.js";
+import {
+  C as createCatchAllEmailResolver,
+  D as routeAgentEmail,
+  E as getCurrentAgent,
+  O as routeAgentRequest,
+  S as createAddressBasedEmailResolver,
+  T as getAgentByName,
+  _ as Schedule,
+  a as CallableMetadata,
+  b as WSMessage,
+  c as EmailResolver,
+  d as MCPServer,
+  f as MCPServerMessage,
+  g as RPCResponse,
+  h as RPCRequest,
+  i as AgentOptions,
+  k as unstable_callable,
+  l as EmailRoutingOptions,
+  m as QueueItem,
+  n as AgentContext,
+  o as Connection,
+  p as MCPServersState,
+  r as AgentNamespace,
+  s as ConnectionContext,
+  t as Agent,
+  u as EmailSendOptions,
+  v as StateUpdateMessage,
+  w as createHeaderBasedEmailResolver,
+  x as callable,
+  y as StreamingResponse
+} from "./index-DUnsVDnf.js";
 export {
-  A as Agent,
-  a as AgentContext,
-  i as AgentNamespace,
-  j as AgentOptions,
-  C as CallableMetadata,
-  f as MCPServer,
-  e as MCPServerMessage,
-  M as MCPServersState,
-  R as RPCRequest,
-  c as RPCResponse,
-  d as Schedule,
-  S as StateUpdateMessage,
-  m as StreamingResponse,
-  l as getAgentByName,
-  h as getCurrentAgent,
-  k as routeAgentEmail,
-  r as routeAgentRequest,
-  u as unstable_callable,
-} from "./index-CITGJflw.js";
-import "zod";
-import "@modelcontextprotocol/sdk/client/sse.js";
-import "@modelcontextprotocol/sdk/shared/protocol.js";
-import "ai";
-import "./mcp/do-oauth-client-provider.js";
-import "@modelcontextprotocol/sdk/client/auth.js";
-import "@modelcontextprotocol/sdk/shared/auth.js";
+  Agent,
+  AgentContext,
+  AgentEmail,
+  AgentNamespace,
+  AgentOptions,
+  CallableMetadata,
+  Connection,
+  ConnectionContext,
+  EmailResolver,
+  EmailRoutingOptions,
+  EmailSendOptions,
+  MCPServer,
+  MCPServerMessage,
+  MCPServersState,
+  QueueItem,
+  RPCRequest,
+  RPCResponse,
+  Schedule,
+  StateUpdateMessage,
+  StreamingResponse,
+  TransportType,
+  WSMessage,
+  callable,
+  createAddressBasedEmailResolver,
+  createCatchAllEmailResolver,
+  createHeaderBasedEmailResolver,
+  getAgentByName,
+  getCurrentAgent,
+  routeAgentEmail,
+  routeAgentRequest,
+  unstable_callable
+};

package/dist/index.js

@@ -1,22 +1,8 @@
-import {
-  Agent,
-  StreamingResponse,
-  getAgentByName,
-  getCurrentAgent,
-  routeAgentEmail,
-  routeAgentRequest,
-  unstable_callable
-} from "./chunk-JFRK72K3.js";
-import "./chunk-E3LCYPCB.js";
-import "./chunk-767EASBA.js";
-import "./chunk-NKZZ66QY.js";
-export {
-  Agent,
-  StreamingResponse,
-  getAgentByName,
-  getCurrentAgent,
-  routeAgentEmail,
-  routeAgentRequest,
-  unstable_callable
-};
-//# sourceMappingURL=index.js.map
+import "./context-BkKbAa1R.js";
+import "./ai-types-CwgHzwUb.js";
+import "./client-CcyhkGfN.js";
+import "./client-QZa2Rq0l.js";
+import "./do-oauth-client-provider-B1fVIshX.js";
+import { a as createCatchAllEmailResolver, c as getCurrentAgent, d as unstable_callable, i as createAddressBasedEmailResolver, l as routeAgentEmail, n as StreamingResponse, o as createHeaderBasedEmailResolver, r as callable, s as getAgentByName, t as Agent, u as routeAgentRequest } from "./src-BmbDclOA.js";
+
+export { Agent, StreamingResponse, callable, createAddressBasedEmailResolver, createCatchAllEmailResolver, createHeaderBasedEmailResolver, getAgentByName, getCurrentAgent, routeAgentEmail, routeAgentRequest, unstable_callable };