agents 0.0.0-f913299 → 0.0.0-f9f03b4

package/dist/index.d.ts

@@ -1,6 +1,29 @@
+import { env } from "cloudflare:workers";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  ServerCapabilities,
+  Tool,
+  Prompt,
+  Resource
+} from "@modelcontextprotocol/sdk/types.js";
 import { Server, Connection, PartyServerOptions } from "partyserver";
 export { Connection, ConnectionContext, WSMessage } from "partyserver";
-import { WorkflowEntrypoint as WorkflowEntrypoint$1 } from "cloudflare:workers";
+import {
+  e as MCPClientManager,
+  T as TransportType,
+  f as MCPConnectionState
+} from "./client-DVoPb3-C.js";
+import { Observability } from "./observability/index.js";
+import { MessageType } from "./ai-types.js";
+import "zod";
+import "@modelcontextprotocol/sdk/shared/protocol.js";
+import "ai";
+import "./mcp-BH1fJeiU.js";
+import "@modelcontextprotocol/sdk/client/sse.js";
+import "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import "./mcp/do-oauth-client-provider.js";
+import "@modelcontextprotocol/sdk/client/auth.js";
+import "@modelcontextprotocol/sdk/shared/auth.js";
 
 /**
  * RPC request message from client
@@ -15,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;
 } & (
   | {
@@ -53,16 +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;
 /**
- * A class for creating workflow entry points that can be used with Cloudflare Workers
+ * 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 class WorkflowEntrypoint extends WorkflowEntrypoint$1 {}
+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
@@ -98,13 +129,52 @@ type Schedule<T = string> = {
       cron: string;
     }
 );
+
+/**
+ * MCP Server state update message from server -> Client
+ */
+type MCPServerMessage = {
+  type: MessageType.CF_AGENT_MCP_SERVERS;
+  mcp: MCPServersState;
+};
+type MCPServersState = {
+  servers: {
+    [id: string]: MCPServer;
+  };
+  tools: Tool[];
+  prompts: Prompt[];
+  resources: Resource[];
+};
+type MCPServer = {
+  name: string;
+  server_url: string;
+  auth_url: string | null;
+  state: MCPConnectionState;
+  instructions: string | null;
+  capabilities: ServerCapabilities | null;
+};
+declare function getCurrentAgent<
+  T extends Agent<unknown, unknown> = Agent<unknown, unknown>
+>(): {
+  agent: T | undefined;
+  connection: Connection | 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> {
-  #private;
+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 _ParentClass;
+  readonly mcp: MCPClientManager;
   /**
    * Initial state for the Agent
    * Override to provide default state values
@@ -121,6 +191,10 @@ declare class Agent<Env, State = unknown> extends Server<Env> {
     /** Whether the Agent should hibernate when inactive */
     hibernate: boolean;
   };
+  /**
+   * The observability implementation to use for the Agent
+   */
+  observability?: Observability;
   /**
    * Execute SQL queries against the Agent's database
    * @template T Type of the returned rows
@@ -133,6 +207,7 @@ declare class Agent<Env, State = unknown> extends Server<Env> {
     ...values: (string | number | boolean | null)[]
   ): T[];
   constructor(ctx: AgentContext, env: Env);
+  private _setStateInternal;
   /**
    * Update the Agent's state
    * @param state New state to set
@@ -145,16 +220,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): 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
@@ -182,7 +316,6 @@ declare class Agent<Env, State = unknown> extends Server<Env> {
    * @returns Array of matching Schedule objects
    */
   getSchedules<T = string>(criteria?: {
-    description?: string;
     id?: string;
     type?: "scheduled" | "delayed" | "cron";
     timeRange?: {
@@ -196,15 +329,62 @@ declare class Agent<Env, State = unknown> extends Server<Env> {
    * @returns true if the task was cancelled, false otherwise
    */
   cancelSchedule(id: string): Promise<boolean>;
+  private _scheduleNextAlarm;
   /**
-   * Method called when an alarm fires
-   * Executes any scheduled tasks that are due
+   * Method called when an alarm fires.
+   * Executes any scheduled tasks that are due.
+   *
+   * @remarks
+   * To schedule a task, please use the `this.schedule` method instead.
+   * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
    */
-  alarm(): Promise<void>;
+  readonly alarm: () => Promise<void>;
   /**
    * Destroy the Agent, removing all state and scheduled tasks
    */
   destroy(): Promise<void>;
+  /**
+   * Get all methods marked as callable on this Agent
+   * @returns A map of method names to their metadata
+   */
+  private _isCallable;
+  /**
+   * 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. 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 options
+   * @returns authUrl
+   */
+  addMcpServer(
+    serverName: string,
+    url: string,
+    callbackHost?: string,
+    agentsPrefix?: string,
+    options?: {
+      client?: ConstructorParameters<typeof Client>[1];
+      transport?: {
+        headers?: HeadersInit;
+        type?: TransportType;
+      };
+    }
+  ): Promise<{
+    id: string;
+    authUrl: string | undefined;
+  }>;
+  private _connectToMcpServerInternal;
+  removeMcpServer(id: string): Promise<void>;
+  getMcpServers(): MCPServersState;
+  private broadcastMcpServers;
+  /**
+   * 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
@@ -237,17 +417,72 @@ 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>
+  options: EmailRoutingOptions<Env>
 ): Promise<void>;
+type AgentEmail = {
+  from: string;
+  to: string;
+  getRaw: () => Promise<Uint8Array>;
+  headers: Headers;
+  rawSize: number;
+  setReject: (reason: string) => void;
+  forward: (rcptTo: string, headers?: Headers) => Promise<void>;
+  reply: (options: { from: string; to: string; raw: string }) => 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
@@ -257,19 +492,26 @@ 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>>;
 /**
  * A wrapper for streaming responses in callable methods
  */
 declare class StreamingResponse {
-  #private;
+  private _connection;
+  private _id;
+  private _closed;
   constructor(connection: Connection, id: string);
   /**
    * Send a chunk of data to the client
@@ -286,17 +528,30 @@ declare class StreamingResponse {
 export {
   Agent,
   type AgentContext,
+  type AgentEmail,
   type AgentNamespace,
   type AgentOptions,
   type CallableMetadata,
+  type EmailResolver,
+  type EmailRoutingOptions,
+  type EmailSendOptions,
+  type MCPServer,
+  type MCPServerMessage,
+  type MCPServersState,
+  type QueueItem,
   type RPCRequest,
   type RPCResponse,
   type Schedule,
   type StateUpdateMessage,
   StreamingResponse,
-  WorkflowEntrypoint,
+  TransportType,
+  callable,
+  createAddressBasedEmailResolver,
+  createCatchAllEmailResolver,
+  createHeaderBasedEmailResolver,
   getAgentByName,
+  getCurrentAgent,
   routeAgentEmail,
   routeAgentRequest,
-  unstable_callable,
+  unstable_callable
 };

package/dist/index.js

@@ -1,18 +1,30 @@
 import {
   Agent,
   StreamingResponse,
-  WorkflowEntrypoint,
+  callable,
+  createAddressBasedEmailResolver,
+  createCatchAllEmailResolver,
+  createHeaderBasedEmailResolver,
   getAgentByName,
+  getCurrentAgent,
   routeAgentEmail,
   routeAgentRequest,
   unstable_callable
-} from "./chunk-X6BBKLSC.js";
-import "./chunk-HMLY7DHA.js";
+} from "./chunk-254F4GDT.js";
+import "./chunk-3OT2NNEW.js";
+import "./chunk-Z44WASMA.js";
+import "./chunk-QEVM4BVL.js";
+import "./chunk-BER7KXUJ.js";
+import "./chunk-PR4QN5HX.js";
 export {
   Agent,
   StreamingResponse,
-  WorkflowEntrypoint,
+  callable,
+  createAddressBasedEmailResolver,
+  createCatchAllEmailResolver,
+  createHeaderBasedEmailResolver,
   getAgentByName,
+  getCurrentAgent,
   routeAgentEmail,
   routeAgentRequest,
   unstable_callable

package/dist/mcp/client.d.ts

@@ -0,0 +1,12 @@
+import 'zod';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/shared/protocol.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'ai';
+export { e as MCPClientManager, d as MCPClientOAuthCallbackConfig, c as MCPClientOAuthResult, g as getNamespacedData } from '../client-DVoPb3-C.js';
+import '../mcp-BH1fJeiU.js';
+import '@modelcontextprotocol/sdk/client/sse.js';
+import '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import './do-oauth-client-provider.js';
+import '@modelcontextprotocol/sdk/client/auth.js';
+import '@modelcontextprotocol/sdk/shared/auth.js';

package/dist/mcp/client.js

@@ -0,0 +1,10 @@
+import {
+  MCPClientManager,
+  getNamespacedData
+} from "../chunk-3OT2NNEW.js";
+import "../chunk-PR4QN5HX.js";
+export {
+  MCPClientManager,
+  getNamespacedData
+};
+//# sourceMappingURL=client.js.map

package/dist/mcp/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/mcp/do-oauth-client-provider.d.ts

@@ -0,0 +1,42 @@
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { OAuthClientMetadata, OAuthClientInformation, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+
+interface AgentsOAuthProvider extends OAuthClientProvider {
+    authUrl: string | undefined;
+    clientId: string | undefined;
+    serverId: string | undefined;
+}
+declare class DurableObjectOAuthClientProvider implements AgentsOAuthProvider {
+    storage: DurableObjectStorage;
+    clientName: string;
+    baseRedirectUrl: string;
+    private _authUrl_;
+    private _serverId_;
+    private _clientId_;
+    constructor(storage: DurableObjectStorage, clientName: string, baseRedirectUrl: string);
+    get clientMetadata(): OAuthClientMetadata;
+    get clientUri(): string;
+    get redirectUrl(): string;
+    get clientId(): string;
+    set clientId(clientId_: string);
+    get serverId(): string;
+    set serverId(serverId_: string);
+    keyPrefix(clientId: string): string;
+    clientInfoKey(clientId: string): string;
+    clientInformation(): Promise<OAuthClientInformation | undefined>;
+    saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void>;
+    tokenKey(clientId: string): string;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    get authUrl(): string | undefined;
+    /**
+     * Because this operates on the server side (but we need browser auth), we send this url back to the user
+     * and require user interact to initiate the redirect flow
+     */
+    redirectToAuthorization(authUrl: URL): Promise<void>;
+    codeVerifierKey(clientId: string): string;
+    saveCodeVerifier(verifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+}
+
+export { type AgentsOAuthProvider, DurableObjectOAuthClientProvider };

package/dist/mcp/do-oauth-client-provider.js

@@ -0,0 +1,8 @@
+import {
+  DurableObjectOAuthClientProvider
+} from "../chunk-Z44WASMA.js";
+import "../chunk-PR4QN5HX.js";
+export {
+  DurableObjectOAuthClientProvider
+};
+//# sourceMappingURL=do-oauth-client-provider.js.map

package/dist/mcp/do-oauth-client-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/mcp/index.d.ts

@@ -0,0 +1,79 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { JSONRPCMessage, ElicitResult } from '@modelcontextprotocol/sdk/types.js';
+export { ElicitRequest, ElicitRequestSchema, ElicitResult } from '@modelcontextprotocol/sdk/types.js';
+import { Agent } from '../index.js';
+import { M as MaybePromise, B as BaseTransportType, S as ServeOptions } from '../client-DVoPb3-C.js';
+export { d as MCPClientOAuthCallbackConfig, c as MCPClientOAuthResult, a as SSEEdgeClientTransport, b as StreamableHTTPEdgeClientTransport } from '../client-DVoPb3-C.js';
+import { Connection, ConnectionContext } from 'partyserver';
+import 'cloudflare:workers';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '../observability/index.js';
+import '../mcp-BH1fJeiU.js';
+import '../ai-types.js';
+import 'ai';
+import 'zod';
+import '@modelcontextprotocol/sdk/shared/protocol.js';
+import '@modelcontextprotocol/sdk/client/sse.js';
+import '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import './do-oauth-client-provider.js';
+import '@modelcontextprotocol/sdk/client/auth.js';
+import '@modelcontextprotocol/sdk/shared/auth.js';
+
+declare abstract class McpAgent<Env = unknown, State = unknown, Props extends Record<string, unknown> = Record<string, unknown>> extends Agent<Env, State, Props> {
+    private _transport?;
+    props?: Props;
+    abstract server: MaybePromise<McpServer | Server>;
+    abstract init(): Promise<void>;
+    setInitializeRequest(initializeRequest: JSONRPCMessage): Promise<void>;
+    getInitializeRequest(): Promise<JSONRPCMessage | undefined>;
+    /** Read the transport type for this agent.
+     * This relies on the naming scheme being `sse:${sessionId}`
+     * or `streamable-http:${sessionId}`.
+     */
+    getTransportType(): BaseTransportType;
+    /** Read the sessionId for this agent.
+     * This relies on the naming scheme being `sse:${sessionId}`
+     * or `streamable-http:${sessionId}`.
+     */
+    getSessionId(): string;
+    /** Get the unique WebSocket. SSE transport only. */
+    private getWebSocket;
+    /** Returns a new transport matching the type of the Agent. */
+    private initTransport;
+    /** Update and store the props */
+    updateProps(props?: Props): Promise<void>;
+    reinitializeServer(): Promise<void>;
+    /** Sets up the MCP transport and server every time the Agent is started.*/
+    onStart(props?: Props): Promise<void>;
+    /** Validates new WebSocket connections. */
+    onConnect(conn: Connection, { request: req }: ConnectionContext): Promise<void>;
+    /** Handles MCP Messages for the legacy SSE transport. */
+    onSSEMcpMessage(_sessionId: string, messageBody: unknown): Promise<Error | null>;
+    /** Elicit user input with a message and schema */
+    elicitInput(params: {
+        message: string;
+        requestedSchema: unknown;
+    }): Promise<ElicitResult>;
+    /** Wait for elicitation response through storage polling */
+    private _waitForElicitationResponse;
+    /** Handle elicitation responses */
+    private _handleElicitationResponse;
+    /** Return a handler for the given path for this MCP.
+     * Defaults to Streamable HTTP transport.
+     */
+    static serve(path: string, { binding, corsOptions, transport }?: ServeOptions): {
+        fetch<Env>(this: void, request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
+    };
+    /**
+     * Legacy api
+     **/
+    static mount(path: string, opts?: Omit<ServeOptions, "transport">): {
+        fetch<Env>(this: void, request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
+    };
+    static serveSSE(path: string, opts?: Omit<ServeOptions, "transport">): {
+        fetch<Env>(this: void, request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
+    };
+}
+
+export { McpAgent };