agents 0.3.10 → 0.4.0

package/dist/client-storage-Cvy5r9FG.d.ts

@@ -0,0 +1,355 @@
+import { t as MCPObservabilityEvent } from "./mcp-Dw5vDrY8.js";
+import { AgentMcpOAuthProvider } from "./mcp/do-oauth-client-provider.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  SSEClientTransport,
+  SSEClientTransportOptions
+} from "@modelcontextprotocol/sdk/client/sse.js";
+import {
+  StreamableHTTPClientTransport,
+  StreamableHTTPClientTransportOptions
+} from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  ElicitRequest,
+  ElicitResult,
+  Prompt,
+  Resource,
+  ResourceTemplate,
+  ServerCapabilities,
+  Tool
+} from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/core/events.d.ts
+interface Disposable {
+  dispose(): void;
+}
+type Event<T> = (listener: (e: T) => void) => Disposable;
+declare class Emitter<T> implements Disposable {
+  private _listeners;
+  readonly event: Event<T>;
+  fire(data: T): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/mcp/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type BaseTransportType = "sse" | "streamable-http";
+type TransportType = BaseTransportType | "auto";
+interface CORSOptions {
+  origin?: string;
+  methods?: string;
+  headers?: string;
+  maxAge?: number;
+  exposeHeaders?: string;
+}
+interface ServeOptions {
+  binding?: string;
+  corsOptions?: CORSOptions;
+  transport?: BaseTransportType;
+  jurisdiction?: DurableObjectJurisdiction;
+}
+//#endregion
+//#region src/mcp/client-connection.d.ts
+/**
+ * Connection state machine for MCP client connections.
+ *
+ * State transitions:
+ * - Non-OAuth: init() → CONNECTING → DISCOVERING → READY
+ * - OAuth: init() → AUTHENTICATING → (callback) → CONNECTING → DISCOVERING → READY
+ * - Any state can transition to FAILED on error
+ */
+declare const MCPConnectionState: {
+  /** Waiting for OAuth authorization to complete */ readonly AUTHENTICATING: "authenticating" /** Establishing transport connection to MCP server */;
+  readonly CONNECTING: "connecting" /** Transport connection established */;
+  readonly CONNECTED: "connected" /** Discovering server capabilities (tools, resources, prompts) */;
+  readonly DISCOVERING: "discovering" /** Fully connected and ready to use */;
+  readonly READY: "ready" /** Connection failed at some point */;
+  readonly FAILED: "failed";
+};
+/**
+ * Connection state type for MCP client connections.
+ */
+type MCPConnectionState =
+  (typeof MCPConnectionState)[keyof typeof MCPConnectionState];
+type MCPTransportOptions = (
+  | SSEClientTransportOptions
+  | StreamableHTTPClientTransportOptions
+) & {
+  authProvider?: AgentMcpOAuthProvider;
+  type?: TransportType;
+};
+/**
+ * Result of a discovery operation.
+ * success indicates whether discovery completed successfully.
+ * error is present when success is false.
+ */
+type MCPDiscoveryResult = {
+  success: boolean;
+  error?: string;
+};
+declare class MCPClientConnection {
+  url: URL;
+  options: {
+    transport: MCPTransportOptions;
+    client: ConstructorParameters<typeof Client>[1];
+  };
+  client: Client;
+  connectionState: MCPConnectionState;
+  connectionError: string | null;
+  lastConnectedTransport: BaseTransportType | undefined;
+  instructions?: string;
+  tools: Tool[];
+  prompts: Prompt[];
+  resources: Resource[];
+  resourceTemplates: ResourceTemplate[];
+  serverCapabilities: ServerCapabilities | undefined;
+  /** Tracks in-flight discovery to allow cancellation */
+  private _discoveryAbortController;
+  private readonly _onObservabilityEvent;
+  readonly onObservabilityEvent: Event<MCPObservabilityEvent>;
+  constructor(
+    url: URL,
+    info: ConstructorParameters<typeof Client>[0],
+    options?: {
+      transport: MCPTransportOptions;
+      client: ConstructorParameters<typeof Client>[1];
+    }
+  );
+  /**
+   * Initialize a client connection, if authentication is required, the connection will be in the AUTHENTICATING state
+   * Sets connection state based on the result and emits observability events
+   *
+   * @returns Error message if connection failed, undefined otherwise
+   */
+  init(): Promise<string | undefined>;
+  /**
+   * Finish OAuth by probing transports based on configured type.
+   * - Explicit: finish on that transport
+   * - Auto: try streamable-http, then sse on 404/405/Not Implemented
+   */
+  private finishAuthProbe;
+  /**
+   * Complete OAuth authorization
+   */
+  completeAuthorization(code: string): Promise<void>;
+  /**
+   * Discover server capabilities and register tools, resources, prompts, and templates.
+   * This method does the work but does not manage connection state - that's handled by discover().
+   */
+  discoverAndRegister(): Promise<void>;
+  /**
+   * Discover server capabilities with timeout and cancellation support.
+   * If called while a previous discovery is in-flight, the previous discovery will be aborted.
+   *
+   * @param options Optional configuration
+   * @param options.timeoutMs Timeout in milliseconds (default: 15000)
+   * @returns Result indicating success/failure with optional error message
+   */
+  discover(options?: { timeoutMs?: number }): Promise<MCPDiscoveryResult>;
+  /**
+   * Cancel any in-flight discovery operation.
+   * Called when closing the connection.
+   */
+  cancelDiscovery(): void;
+  /**
+   * Notification handler registration for tools
+   * Should only be called if serverCapabilities.tools exists
+   */
+  registerTools(): Promise<Tool[]>;
+  /**
+   * Notification handler registration for resources
+   * Should only be called if serverCapabilities.resources exists
+   */
+  registerResources(): Promise<Resource[]>;
+  /**
+   * Notification handler registration for prompts
+   * Should only be called if serverCapabilities.prompts exists
+   */
+  registerPrompts(): Promise<Prompt[]>;
+  registerResourceTemplates(): Promise<ResourceTemplate[]>;
+  fetchTools(): Promise<
+    {
+      inputSchema: {
+        [x: string]: unknown;
+        type: "object";
+        properties?:
+          | {
+              [x: string]: object;
+            }
+          | undefined;
+        required?: string[] | undefined;
+      };
+      name: string;
+      description?: string | undefined;
+      outputSchema?:
+        | {
+            [x: string]: unknown;
+            type: "object";
+            properties?:
+              | {
+                  [x: string]: object;
+                }
+              | undefined;
+            required?: string[] | undefined;
+          }
+        | undefined;
+      annotations?:
+        | {
+            title?: string | undefined;
+            readOnlyHint?: boolean | undefined;
+            destructiveHint?: boolean | undefined;
+            idempotentHint?: boolean | undefined;
+            openWorldHint?: boolean | undefined;
+          }
+        | undefined;
+      execution?:
+        | {
+            taskSupport?: "optional" | "required" | "forbidden" | undefined;
+          }
+        | undefined;
+      _meta?:
+        | {
+            [x: string]: unknown;
+          }
+        | undefined;
+      icons?:
+        | {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+          }[]
+        | undefined;
+      title?: string | undefined;
+    }[]
+  >;
+  fetchResources(): Promise<
+    {
+      uri: string;
+      name: string;
+      description?: string | undefined;
+      mimeType?: string | undefined;
+      annotations?:
+        | {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+          }
+        | undefined;
+      _meta?:
+        | {
+            [x: string]: unknown;
+          }
+        | undefined;
+      icons?:
+        | {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+          }[]
+        | undefined;
+      title?: string | undefined;
+    }[]
+  >;
+  fetchPrompts(): Promise<
+    {
+      name: string;
+      description?: string | undefined;
+      arguments?:
+        | {
+            name: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+          }[]
+        | undefined;
+      _meta?:
+        | {
+            [x: string]: unknown;
+          }
+        | undefined;
+      icons?:
+        | {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+          }[]
+        | undefined;
+      title?: string | undefined;
+    }[]
+  >;
+  fetchResourceTemplates(): Promise<
+    {
+      uriTemplate: string;
+      name: string;
+      description?: string | undefined;
+      mimeType?: string | undefined;
+      annotations?:
+        | {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+          }
+        | undefined;
+      _meta?:
+        | {
+            [x: string]: unknown;
+          }
+        | undefined;
+      icons?:
+        | {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+          }[]
+        | undefined;
+      title?: string | undefined;
+    }[]
+  >;
+  /**
+   * Handle elicitation request from server
+   * Automatically uses the Agent's built-in elicitation handling if available
+   */
+  handleElicitationRequest(_request: ElicitRequest): Promise<ElicitResult>;
+  /**
+   * Get the transport for the client
+   * @param transportType - The transport type to get
+   * @returns The transport for the client
+   */
+  getTransport(
+    transportType: BaseTransportType
+  ): StreamableHTTPClientTransport | SSEClientTransport;
+  private tryConnect;
+  private _capabilityErrorHandler;
+}
+//#endregion
+//#region src/mcp/client-storage.d.ts
+/**
+ * Represents a row in the cf_agents_mcp_servers table
+ */
+type MCPServerRow = {
+  id: string;
+  name: string;
+  server_url: string;
+  client_id: string | null;
+  auth_url: string | null;
+  callback_url: string;
+  server_options: string | null;
+};
+//#endregion
+export {
+  BaseTransportType as a,
+  ServeOptions as c,
+  Event as d,
+  MCPTransportOptions as i,
+  TransportType as l,
+  MCPClientConnection as n,
+  CORSOptions as o,
+  MCPConnectionState as r,
+  MaybePromise as s,
+  MCPServerRow as t,
+  Emitter as u
+};
+//# sourceMappingURL=client-storage-Cvy5r9FG.d.ts.map

package/dist/client.d.ts

@@ -13,7 +13,7 @@ type AgentClientOptions<State = unknown> = Omit<
   PartySocketOptions,
   "party" | "room"
 > & {
-  /** Name of the agent to connect to (ignored if basePath is set) */ agent: string; /** Name of the specific Agent instance (ignored if basePath is set) */
+  /** Name of the agent to connect to (ignored if basePath is set) */ agent: string /** Name of the specific Agent instance (ignored if basePath is set) */;
   name?: string;
   /**
    * Full URL path - bypasses agent/name URL construction.
@@ -23,8 +23,12 @@ type AgentClientOptions<State = unknown> = Omit<
    * // Client connects to /user, server routes based on session
    * useAgent({ agent: "UserAgent", basePath: "user" })
    */
-  basePath?: string; /** Called when the Agent's state is updated */
-  onStateUpdate?: (state: State, source: "server" | "client") => void;
+  basePath?: string /** Called when the Agent's state is updated */;
+  onStateUpdate?: (
+    state: State,
+    source: "server" | "client"
+  ) => void /** Called when a state update fails (e.g., connection is readonly) */;
+  onStateUpdateError?: (error: string) => void;
   /**
    * Called when the server sends the agent's identity on connect.
    * Useful when using basePath, as the actual instance name is determined server-side.
@@ -63,22 +67,22 @@ type AgentClientOptions<State = unknown> = Omit<
 type StreamOptions = {
   /** Called when a chunk of data is received */ onChunk?: (
     chunk: unknown
-  ) => void; /** Called when the stream ends */
-  onDone?: (finalChunk: unknown) => void; /** Called when an error occurs */
+  ) => void /** Called when the stream ends */;
+  onDone?: (finalChunk: unknown) => void /** Called when an error occurs */;
   onError?: (error: string) => void;
 };
 /**
  * Options for RPC calls
  */
 type CallOptions = {
-  /** Timeout in milliseconds. If the call doesn't complete within this time, it will be rejected. */ timeout?: number; /** Streaming options for handling streaming responses */
+  /** Timeout in milliseconds. If the call doesn't complete within this time, it will be rejected. */ timeout?: number /** Streaming options for handling streaming responses */;
   stream?: StreamOptions;
 };
 /**
  * Options for the agentFetch function
  */
 type AgentClientFetchOptions = Omit<PartyFetchOptions, "party" | "room"> & {
-  /** Name of the agent to connect to (ignored if basePath is set) */ agent: string; /** Name of the specific Agent instance (ignored if basePath is set) */
+  /** Name of the agent to connect to (ignored if basePath is set) */ agent: string /** Name of the specific Agent instance (ignored if basePath is set) */;
   name?: string;
   /**
    * Full URL path - bypasses agent/name URL construction.

package/dist/client.js

@@ -1,5 +1,5 @@
-import { t as MessageType } from "./types-BITaDFf-.js";
-import { t as camelCaseToKebabCase } from "./utils-B49TmLCI.js";
+import { MessageType } from "./types.js";
+import { camelCaseToKebabCase } from "./utils.js";
 import { PartySocket } from "partysocket";
 
 //#region src/client.ts
@@ -84,6 +84,10 @@ var AgentClient = class extends PartySocket {
 					this.options.onStateUpdate?.(parsedMessage.state, "server");
 					return;
 				}
+				if (parsedMessage.type === MessageType.CF_AGENT_STATE_ERROR) {
+					this.options.onStateUpdateError?.(parsedMessage.error);
+					return;
+				}
 				if (parsedMessage.type === MessageType.RPC) {
 					const response = parsedMessage;
 					const pending = this._pendingCalls.get(response.id);

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import {\n  type PartyFetchOptions,\n  PartySocket,\n  type PartySocketOptions\n} from \"partysocket\";\nimport type { RPCRequest, RPCResponse } from \"./\";\nimport type {\n  SerializableReturnValue,\n  SerializableValue\n} from \"./serializable\";\nimport { MessageType } from \"./types\";\n\n/**\n * Options for creating an AgentClient\n */\nexport type AgentClientOptions<State = unknown> = Omit<\n  PartySocketOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the client connects to this path directly.\n   * Server must handle routing manually (e.g., with getAgentByName + fetch).\n   * @example\n   * // Client connects to /user, server routes based on session\n   * useAgent({ agent: \"UserAgent\", basePath: \"user\" })\n   */\n  basePath?: string;\n  /** Called when the Agent's state is updated */\n  onStateUpdate?: (state: State, source: \"server\" | \"client\") => void;\n  /**\n   * Called when the server sends the agent's identity on connect.\n   * Useful when using basePath, as the actual instance name is determined server-side.\n   * @param name The actual agent instance name\n   * @param agent The agent class name (kebab-case)\n   */\n  onIdentity?: (name: string, agent: string) => void;\n  /**\n   * Called when identity changes on reconnect (different instance than before).\n   * If not provided and identity changes, a warning will be logged.\n   * @param oldName Previous instance name\n   * @param newName New instance name\n   * @param oldAgent Previous agent class name\n   * @param newAgent New agent class name\n   */\n  onIdentityChange?: (\n    oldName: string,\n    newName: string,\n    oldAgent: string,\n    newAgent: string\n  ) => void;\n  /**\n   * Additional path to append to the URL.\n   * Works with both standard routing and basePath.\n   * @example\n   * // With basePath: /user/settings\n   * { basePath: \"user\", path: \"settings\" }\n   * // Standard: /agents/my-agent/room/settings\n   * { agent: \"MyAgent\", name: \"room\", path: \"settings\" }\n   */\n  path?: string;\n};\n\n/**\n * Options for streaming RPC calls\n */\nexport type StreamOptions = {\n  /** Called when a chunk of data is received */\n  onChunk?: (chunk: unknown) => void;\n  /** Called when the stream ends */\n  onDone?: (finalChunk: unknown) => void;\n  /** Called when an error occurs */\n  onError?: (error: string) => void;\n};\n\n/**\n * Options for RPC calls\n */\nexport type CallOptions = {\n  /** Timeout in milliseconds. If the call doesn't complete within this time, it will be rejected. */\n  timeout?: number;\n  /** Streaming options for handling streaming responses */\n  stream?: StreamOptions;\n};\n\n/**\n * Options for the agentFetch function\n */\nexport type AgentClientFetchOptions = Omit<\n  PartyFetchOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the request is made to this path directly.\n   */\n  basePath?: string;\n};\n\nimport { camelCaseToKebabCase } from \"./utils\";\n\n/**\n * WebSocket client for connecting to an Agent\n */\nexport class AgentClient<State = unknown> extends PartySocket {\n  /**\n   * @deprecated Use agentFetch instead\n   */\n  static fetch(_opts: PartyFetchOptions): Promise<Response> {\n    throw new Error(\n      \"AgentClient.fetch is not implemented, use agentFetch instead\"\n    );\n  }\n  agent: string;\n  name: string;\n\n  /**\n   * Whether the client has received identity from the server.\n   * Becomes true after the first identity message is received.\n   * Resets to false on connection close.\n   */\n  identified = false;\n\n  /**\n   * Promise that resolves when identity has been received from the server.\n   * Useful for waiting before making calls that depend on knowing the instance.\n   * Resets on connection close so it can be awaited again after reconnect.\n   */\n  get ready(): Promise<void> {\n    return this._readyPromise;\n  }\n\n  private options: AgentClientOptions<State>;\n  private _pendingCalls = new Map<\n    string,\n    {\n      resolve: (value: unknown) => void;\n      reject: (error: Error) => void;\n      stream?: StreamOptions;\n      type?: unknown;\n    }\n  >();\n  private _readyPromise!: Promise<void>;\n  private _resolveReady!: () => void;\n  private _previousName: string | null = null;\n  private _previousAgent: string | null = null;\n\n  private _resetReady() {\n    this._readyPromise = new Promise((resolve) => {\n      this._resolveReady = resolve;\n    });\n  }\n\n  constructor(options: AgentClientOptions<State>) {\n    const agentNamespace = camelCaseToKebabCase(options.agent);\n\n    // If basePath is provided, use it directly; otherwise construct from agent/name\n    const socketOptions = options.basePath\n      ? { basePath: options.basePath, path: options.path, ...options }\n      : {\n          party: agentNamespace,\n          prefix: \"agents\",\n          room: options.name || \"default\",\n          path: options.path,\n          ...options\n        };\n\n    super(socketOptions);\n    this.agent = agentNamespace;\n    this.name = options.name || \"default\";\n    this.options = options;\n\n    // Initialize ready promise\n    this._resetReady();\n\n    this.addEventListener(\"message\", (event) => {\n      if (typeof event.data === \"string\") {\n        let parsedMessage: Record<string, unknown>;\n        try {\n          parsedMessage = JSON.parse(event.data);\n        } catch (_error) {\n          // silently ignore invalid messages for now\n          // TODO: log errors with log levels\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_IDENTITY) {\n          const oldName = this._previousName;\n          const oldAgent = this._previousAgent;\n          const newName = parsedMessage.name as string;\n          const newAgent = parsedMessage.agent as string;\n\n          // Resolve ready/identified\n          this.identified = true;\n          this._resolveReady();\n\n          // Detect identity change on reconnect\n          if (\n            oldName !== null &&\n            oldAgent !== null &&\n            (oldName !== newName || oldAgent !== newAgent)\n          ) {\n            if (this.options.onIdentityChange) {\n              this.options.onIdentityChange(\n                oldName,\n                newName,\n                oldAgent,\n                newAgent\n              );\n            } else {\n              const agentChanged = oldAgent !== newAgent;\n              const nameChanged = oldName !== newName;\n              let changeDescription = \"\";\n              if (agentChanged && nameChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\", instance \"${oldName}\" → \"${newName}\"`;\n              } else if (agentChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\"`;\n              } else {\n                changeDescription = `instance \"${oldName}\" → \"${newName}\"`;\n              }\n              console.warn(\n                `[agents] Identity changed on reconnect: ${changeDescription}. ` +\n                  \"This can happen with server-side routing (e.g., basePath with getAgentByName) \" +\n                  \"where the instance is determined by auth/session. \" +\n                  \"Provide onIdentityChange callback to handle this explicitly, \" +\n                  \"or ignore if this is expected for your routing pattern.\"\n              );\n            }\n          }\n\n          // Always update from server identity (server is authoritative)\n          this._previousName = newName;\n          this._previousAgent = newAgent;\n          this.name = newName;\n          this.agent = newAgent;\n\n          // Call onIdentity callback\n          this.options.onIdentity?.(newName, newAgent);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE) {\n          this.options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === MessageType.RPC) {\n          const response = parsedMessage as RPCResponse;\n          const pending = this._pendingCalls.get(response.id);\n          if (!pending) return;\n\n          if (!response.success) {\n            pending.reject(new Error(response.error));\n            this._pendingCalls.delete(response.id);\n            pending.stream?.onError?.(response.error);\n            return;\n          }\n\n          // Handle streaming responses\n          if (\"done\" in response) {\n            if (response.done) {\n              pending.resolve(response.result);\n              this._pendingCalls.delete(response.id);\n              pending.stream?.onDone?.(response.result);\n            } else {\n              pending.stream?.onChunk?.(response.result);\n            }\n          } else {\n            // Non-streaming response\n            pending.resolve(response.result);\n            this._pendingCalls.delete(response.id);\n          }\n        }\n      }\n    });\n\n    // Clean up pending calls and reset ready state when connection closes\n    this.addEventListener(\"close\", () => {\n      // Reset ready state for next connection\n      this.identified = false;\n      this._resetReady();\n\n      // Reject any remaining pending calls (e.g., from unexpected disconnect)\n      this._rejectPendingCalls(\"Connection closed\");\n    });\n  }\n\n  /**\n   * Reject all pending RPC calls with the given reason.\n   */\n  private _rejectPendingCalls(reason: string) {\n    const error = new Error(reason);\n    for (const pending of this._pendingCalls.values()) {\n      pending.reject(error);\n      pending.stream?.onError?.(reason);\n    }\n    this._pendingCalls.clear();\n  }\n\n  setState(state: State) {\n    this.send(JSON.stringify({ state, type: MessageType.CF_AGENT_STATE }));\n    this.options.onStateUpdate?.(state, \"client\");\n  }\n\n  /**\n   * Close the connection and immediately reject all pending RPC calls.\n   * This provides immediate feedback on intentional close rather than\n   * waiting for the WebSocket close handshake to complete.\n   *\n   * Note: Any calls made after `close()` will be rejected when the\n   * underlying WebSocket close event fires.\n   */\n  close(code?: number, reason?: string) {\n    // Immediately reject all pending calls on intentional close\n    this._rejectPendingCalls(\"Connection closed\");\n\n    // Then close the underlying socket\n    super.close(code, reason);\n  }\n\n  /**\n   * Call a method on the Agent\n   * @param method Name of the method to call\n   * @param args Arguments to pass to the method\n   * @param options Options for the call (timeout, streaming) or legacy StreamOptions\n   * @returns Promise that resolves with the method's return value\n   */\n  call<T extends SerializableReturnValue>(\n    method: string,\n    args?: SerializableValue[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n  call<T = unknown>(\n    method: string,\n    args?: unknown[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n  async call<T>(\n    method: string,\n    args: unknown[] = [],\n    options?: CallOptions | StreamOptions\n  ): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      const id = crypto.randomUUID();\n      let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n      // Detect legacy format: { onChunk?, onDone?, onError? } vs new format: { timeout?, stream? }\n      const isLegacyFormat =\n        options &&\n        (\"onChunk\" in options || \"onDone\" in options || \"onError\" in options);\n      const streamOptions = isLegacyFormat\n        ? (options as StreamOptions)\n        : (options as CallOptions | undefined)?.stream;\n      const timeout = isLegacyFormat\n        ? undefined\n        : (options as CallOptions | undefined)?.timeout;\n\n      // Set up timeout if specified\n      if (timeout) {\n        timeoutId = setTimeout(() => {\n          const pending = this._pendingCalls.get(id);\n          this._pendingCalls.delete(id);\n          const errorMessage = `RPC call to ${method} timed out after ${timeout}ms`;\n          // Call stream onError callback if present (for streaming calls)\n          pending?.stream?.onError?.(errorMessage);\n          reject(new Error(errorMessage));\n        }, timeout);\n      }\n\n      this._pendingCalls.set(id, {\n        reject: (e: Error) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          reject(e);\n        },\n        resolve: (value: unknown) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          resolve(value as T);\n        },\n        stream: streamOptions,\n        type: null as T\n      });\n\n      const request: RPCRequest = {\n        args,\n        id,\n        method,\n        type: MessageType.RPC\n      };\n\n      this.send(JSON.stringify(request));\n    });\n  }\n}\n\n/**\n * Make an HTTP request to an Agent\n * @param opts Connection options\n * @param init Request initialization options\n * @returns Promise resolving to a Response\n */\nexport function agentFetch(opts: AgentClientFetchOptions, init?: RequestInit) {\n  const agentNamespace = camelCaseToKebabCase(opts.agent);\n\n  // If basePath is provided, use it directly; otherwise construct from agent/name\n  // When basePath is set, room/party aren't used by PartySocket (basePath replaces the URL)\n  if (opts.basePath) {\n    return PartySocket.fetch(\n      { basePath: opts.basePath, ...opts } as unknown as PartyFetchOptions,\n      init\n    );\n  }\n\n  return PartySocket.fetch(\n    {\n      party: agentNamespace,\n      prefix: \"agents\",\n      room: opts.name || \"default\",\n      ...opts\n    },\n    init\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import {\n  type PartyFetchOptions,\n  PartySocket,\n  type PartySocketOptions\n} from \"partysocket\";\nimport type { RPCRequest, RPCResponse } from \"./\";\nimport type {\n  SerializableReturnValue,\n  SerializableValue\n} from \"./serializable\";\nimport { MessageType } from \"./types\";\n\n/**\n * Options for creating an AgentClient\n */\nexport type AgentClientOptions<State = unknown> = Omit<\n  PartySocketOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the client connects to this path directly.\n   * Server must handle routing manually (e.g., with getAgentByName + fetch).\n   * @example\n   * // Client connects to /user, server routes based on session\n   * useAgent({ agent: \"UserAgent\", basePath: \"user\" })\n   */\n  basePath?: string;\n  /** Called when the Agent's state is updated */\n  onStateUpdate?: (state: State, source: \"server\" | \"client\") => void;\n  /** Called when a state update fails (e.g., connection is readonly) */\n  onStateUpdateError?: (error: string) => void;\n  /**\n   * Called when the server sends the agent's identity on connect.\n   * Useful when using basePath, as the actual instance name is determined server-side.\n   * @param name The actual agent instance name\n   * @param agent The agent class name (kebab-case)\n   */\n  onIdentity?: (name: string, agent: string) => void;\n  /**\n   * Called when identity changes on reconnect (different instance than before).\n   * If not provided and identity changes, a warning will be logged.\n   * @param oldName Previous instance name\n   * @param newName New instance name\n   * @param oldAgent Previous agent class name\n   * @param newAgent New agent class name\n   */\n  onIdentityChange?: (\n    oldName: string,\n    newName: string,\n    oldAgent: string,\n    newAgent: string\n  ) => void;\n  /**\n   * Additional path to append to the URL.\n   * Works with both standard routing and basePath.\n   * @example\n   * // With basePath: /user/settings\n   * { basePath: \"user\", path: \"settings\" }\n   * // Standard: /agents/my-agent/room/settings\n   * { agent: \"MyAgent\", name: \"room\", path: \"settings\" }\n   */\n  path?: string;\n};\n\n/**\n * Options for streaming RPC calls\n */\nexport type StreamOptions = {\n  /** Called when a chunk of data is received */\n  onChunk?: (chunk: unknown) => void;\n  /** Called when the stream ends */\n  onDone?: (finalChunk: unknown) => void;\n  /** Called when an error occurs */\n  onError?: (error: string) => void;\n};\n\n/**\n * Options for RPC calls\n */\nexport type CallOptions = {\n  /** Timeout in milliseconds. If the call doesn't complete within this time, it will be rejected. */\n  timeout?: number;\n  /** Streaming options for handling streaming responses */\n  stream?: StreamOptions;\n};\n\n/**\n * Options for the agentFetch function\n */\nexport type AgentClientFetchOptions = Omit<\n  PartyFetchOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the request is made to this path directly.\n   */\n  basePath?: string;\n};\n\nimport { camelCaseToKebabCase } from \"./utils\";\n\n/**\n * WebSocket client for connecting to an Agent\n */\nexport class AgentClient<State = unknown> extends PartySocket {\n  /**\n   * @deprecated Use agentFetch instead\n   */\n  static fetch(_opts: PartyFetchOptions): Promise<Response> {\n    throw new Error(\n      \"AgentClient.fetch is not implemented, use agentFetch instead\"\n    );\n  }\n  agent: string;\n  name: string;\n\n  /**\n   * Whether the client has received identity from the server.\n   * Becomes true after the first identity message is received.\n   * Resets to false on connection close.\n   */\n  identified = false;\n\n  /**\n   * Promise that resolves when identity has been received from the server.\n   * Useful for waiting before making calls that depend on knowing the instance.\n   * Resets on connection close so it can be awaited again after reconnect.\n   */\n  get ready(): Promise<void> {\n    return this._readyPromise;\n  }\n\n  private options: AgentClientOptions<State>;\n  private _pendingCalls = new Map<\n    string,\n    {\n      resolve: (value: unknown) => void;\n      reject: (error: Error) => void;\n      stream?: StreamOptions;\n      type?: unknown;\n    }\n  >();\n  private _readyPromise!: Promise<void>;\n  private _resolveReady!: () => void;\n  private _previousName: string | null = null;\n  private _previousAgent: string | null = null;\n\n  private _resetReady() {\n    this._readyPromise = new Promise((resolve) => {\n      this._resolveReady = resolve;\n    });\n  }\n\n  constructor(options: AgentClientOptions<State>) {\n    const agentNamespace = camelCaseToKebabCase(options.agent);\n\n    // If basePath is provided, use it directly; otherwise construct from agent/name\n    const socketOptions = options.basePath\n      ? { basePath: options.basePath, path: options.path, ...options }\n      : {\n          party: agentNamespace,\n          prefix: \"agents\",\n          room: options.name || \"default\",\n          path: options.path,\n          ...options\n        };\n\n    super(socketOptions);\n    this.agent = agentNamespace;\n    this.name = options.name || \"default\";\n    this.options = options;\n\n    // Initialize ready promise\n    this._resetReady();\n\n    this.addEventListener(\"message\", (event) => {\n      if (typeof event.data === \"string\") {\n        let parsedMessage: Record<string, unknown>;\n        try {\n          parsedMessage = JSON.parse(event.data);\n        } catch (_error) {\n          // silently ignore invalid messages for now\n          // TODO: log errors with log levels\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_IDENTITY) {\n          const oldName = this._previousName;\n          const oldAgent = this._previousAgent;\n          const newName = parsedMessage.name as string;\n          const newAgent = parsedMessage.agent as string;\n\n          // Resolve ready/identified\n          this.identified = true;\n          this._resolveReady();\n\n          // Detect identity change on reconnect\n          if (\n            oldName !== null &&\n            oldAgent !== null &&\n            (oldName !== newName || oldAgent !== newAgent)\n          ) {\n            if (this.options.onIdentityChange) {\n              this.options.onIdentityChange(\n                oldName,\n                newName,\n                oldAgent,\n                newAgent\n              );\n            } else {\n              const agentChanged = oldAgent !== newAgent;\n              const nameChanged = oldName !== newName;\n              let changeDescription = \"\";\n              if (agentChanged && nameChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\", instance \"${oldName}\" → \"${newName}\"`;\n              } else if (agentChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\"`;\n              } else {\n                changeDescription = `instance \"${oldName}\" → \"${newName}\"`;\n              }\n              console.warn(\n                `[agents] Identity changed on reconnect: ${changeDescription}. ` +\n                  \"This can happen with server-side routing (e.g., basePath with getAgentByName) \" +\n                  \"where the instance is determined by auth/session. \" +\n                  \"Provide onIdentityChange callback to handle this explicitly, \" +\n                  \"or ignore if this is expected for your routing pattern.\"\n              );\n            }\n          }\n\n          // Always update from server identity (server is authoritative)\n          this._previousName = newName;\n          this._previousAgent = newAgent;\n          this.name = newName;\n          this.agent = newAgent;\n\n          // Call onIdentity callback\n          this.options.onIdentity?.(newName, newAgent);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE) {\n          this.options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE_ERROR) {\n          this.options.onStateUpdateError?.(parsedMessage.error as string);\n          return;\n        }\n        if (parsedMessage.type === MessageType.RPC) {\n          const response = parsedMessage as RPCResponse;\n          const pending = this._pendingCalls.get(response.id);\n          if (!pending) return;\n\n          if (!response.success) {\n            pending.reject(new Error(response.error));\n            this._pendingCalls.delete(response.id);\n            pending.stream?.onError?.(response.error);\n            return;\n          }\n\n          // Handle streaming responses\n          if (\"done\" in response) {\n            if (response.done) {\n              pending.resolve(response.result);\n              this._pendingCalls.delete(response.id);\n              pending.stream?.onDone?.(response.result);\n            } else {\n              pending.stream?.onChunk?.(response.result);\n            }\n          } else {\n            // Non-streaming response\n            pending.resolve(response.result);\n            this._pendingCalls.delete(response.id);\n          }\n        }\n      }\n    });\n\n    // Clean up pending calls and reset ready state when connection closes\n    this.addEventListener(\"close\", () => {\n      // Reset ready state for next connection\n      this.identified = false;\n      this._resetReady();\n\n      // Reject any remaining pending calls (e.g., from unexpected disconnect)\n      this._rejectPendingCalls(\"Connection closed\");\n    });\n  }\n\n  /**\n   * Reject all pending RPC calls with the given reason.\n   */\n  private _rejectPendingCalls(reason: string) {\n    const error = new Error(reason);\n    for (const pending of this._pendingCalls.values()) {\n      pending.reject(error);\n      pending.stream?.onError?.(reason);\n    }\n    this._pendingCalls.clear();\n  }\n\n  setState(state: State) {\n    this.send(JSON.stringify({ state, type: MessageType.CF_AGENT_STATE }));\n    this.options.onStateUpdate?.(state, \"client\");\n  }\n\n  /**\n   * Close the connection and immediately reject all pending RPC calls.\n   * This provides immediate feedback on intentional close rather than\n   * waiting for the WebSocket close handshake to complete.\n   *\n   * Note: Any calls made after `close()` will be rejected when the\n   * underlying WebSocket close event fires.\n   */\n  close(code?: number, reason?: string) {\n    // Immediately reject all pending calls on intentional close\n    this._rejectPendingCalls(\"Connection closed\");\n\n    // Then close the underlying socket\n    super.close(code, reason);\n  }\n\n  /**\n   * Call a method on the Agent\n   * @param method Name of the method to call\n   * @param args Arguments to pass to the method\n   * @param options Options for the call (timeout, streaming) or legacy StreamOptions\n   * @returns Promise that resolves with the method's return value\n   */\n  call<T extends SerializableReturnValue>(\n    method: string,\n    args?: SerializableValue[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n  call<T = unknown>(\n    method: string,\n    args?: unknown[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n  async call<T>(\n    method: string,\n    args: unknown[] = [],\n    options?: CallOptions | StreamOptions\n  ): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      const id = crypto.randomUUID();\n      let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n      // Detect legacy format: { onChunk?, onDone?, onError? } vs new format: { timeout?, stream? }\n      const isLegacyFormat =\n        options &&\n        (\"onChunk\" in options || \"onDone\" in options || \"onError\" in options);\n      const streamOptions = isLegacyFormat\n        ? (options as StreamOptions)\n        : (options as CallOptions | undefined)?.stream;\n      const timeout = isLegacyFormat\n        ? undefined\n        : (options as CallOptions | undefined)?.timeout;\n\n      // Set up timeout if specified\n      if (timeout) {\n        timeoutId = setTimeout(() => {\n          const pending = this._pendingCalls.get(id);\n          this._pendingCalls.delete(id);\n          const errorMessage = `RPC call to ${method} timed out after ${timeout}ms`;\n          // Call stream onError callback if present (for streaming calls)\n          pending?.stream?.onError?.(errorMessage);\n          reject(new Error(errorMessage));\n        }, timeout);\n      }\n\n      this._pendingCalls.set(id, {\n        reject: (e: Error) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          reject(e);\n        },\n        resolve: (value: unknown) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          resolve(value as T);\n        },\n        stream: streamOptions,\n        type: null as T\n      });\n\n      const request: RPCRequest = {\n        args,\n        id,\n        method,\n        type: MessageType.RPC\n      };\n\n      this.send(JSON.stringify(request));\n    });\n  }\n}\n\n/**\n * Make an HTTP request to an Agent\n * @param opts Connection options\n * @param init Request initialization options\n * @returns Promise resolving to a Response\n */\nexport function agentFetch(opts: AgentClientFetchOptions, init?: RequestInit) {\n  const agentNamespace = camelCaseToKebabCase(opts.agent);\n\n  // If basePath is provided, use it directly; otherwise construct from agent/name\n  // When basePath is set, room/party aren't used by PartySocket (basePath replaces the URL)\n  if (opts.basePath) {\n    return PartySocket.fetch(\n      { basePath: opts.basePath, ...opts } as unknown as PartyFetchOptions,\n      init\n    );\n  }\n\n  return PartySocket.fetch(\n    {\n      party: agentNamespace,\n      prefix: \"agents\",\n      room: opts.name || \"default\",\n      ...opts\n    },\n    init\n  );\n}\n"],"mappings":"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"}

package/dist/email.d.ts

@@ -1,20 +1,149 @@
-import { n as AgentEmail } from "./internal_context-CEu5ji80.js";
-import {
-  a as SecureReplyResolverOptions,
-  c as createCatchAllEmailResolver,
-  d as isAutoReplyEmail,
-  f as signAgentHeaders,
-  i as EmailResolverResult,
-  l as createHeaderBasedEmailResolver,
-  n as EmailHeader,
-  o as SignatureFailureReason,
-  r as EmailResolver,
-  s as createAddressBasedEmailResolver,
-  t as DEFAULT_MAX_AGE_SECONDS,
-  u as createSecureReplyEmailResolver
-} from "./email-8ljcpvwV.js";
+import { AgentEmail } from "./internal_context.js";
+
+//#region src/email.d.ts
+/**
+ * Header object as returned by postal-mime and similar email parsing libraries.
+ * Each header has a lowercase key and a string value.
+ */
+type EmailHeader = {
+  /** Lowercase header name (e.g., "content-type", "x-custom-header") */ key: string /** Header value */;
+  value: string;
+};
+/**
+ * Check if an email appears to be an auto-reply based on standard headers.
+ * Checks for Auto-Submitted (RFC 3834), X-Auto-Response-Suppress, and Precedence headers.
+ *
+ * @param headers - Headers array from postal-mime Email.headers or similar format
+ * @returns true if email appears to be an auto-reply
+ *
+ * @example
+ * ```typescript
+ * if (isAutoReplyEmail(parsed.headers)) {
+ *   // Skip processing auto-replies
+ *   return;
+ * }
+ * ```
+ */
+declare function isAutoReplyEmail(headers: EmailHeader[]): boolean;
+/** Default signature expiration: 30 days in seconds */
+declare const DEFAULT_MAX_AGE_SECONDS: number;
+/**
+ * Sign agent routing headers for secure reply flows.
+ * Use this when sending outbound emails to ensure replies can be securely routed back.
+ *
+ * @param secret - Secret key for HMAC signing (store in environment variables)
+ * @param agentName - Name of the agent
+ * @param agentId - ID of the agent instance
+ * @returns Headers object with X-Agent-Name, X-Agent-ID, X-Agent-Sig, and X-Agent-Sig-Ts
+ *
+ * @example
+ * ```typescript
+ * const headers = await signAgentHeaders(env.EMAIL_SECRET, "MyAgent", this.name);
+ * // Use these headers when sending outbound emails
+ * ```
+ */
+declare function signAgentHeaders(
+  secret: string,
+  agentName: string,
+  agentId: string
+): Promise<Record<string, string>>;
+type EmailResolverResult = {
+  agentName: string;
+  agentId: string /** @internal Indicates this resolver requires secure reply signing */;
+  _secureRouted?: boolean;
+} | null;
+type EmailResolver<Env> = (
+  email: ForwardableEmailMessage,
+  env: Env
+) => Promise<EmailResolverResult>;
+/**
+ * Reason for signature verification failure
+ */
+type SignatureFailureReason =
+  | "missing_headers"
+  | "expired"
+  | "invalid"
+  | "malformed_timestamp";
+/**
+ * Options for createSecureReplyEmailResolver
+ */
+type SecureReplyResolverOptions = {
+  /**
+   * Maximum age of signature in seconds.
+   * Signatures older than this will be rejected.
+   * Default: 30 days (2592000 seconds)
+   */
+  maxAge?: number;
+  /**
+   * Callback invoked when signature verification fails.
+   * Useful for logging and debugging.
+   */
+  onInvalidSignature?: (
+    email: ForwardableEmailMessage,
+    reason: SignatureFailureReason
+  ) => void;
+};
+/**
+ * @deprecated REMOVED due to security vulnerability (IDOR via spoofed headers).
+ * @throws Always throws an error with migration guidance.
+ */
+declare function createHeaderBasedEmailResolver<Env>(): EmailResolver<Env>;
+/**
+ * Create a resolver for routing email replies with signature verification.
+ * This resolver verifies that replies contain a valid HMAC signature, preventing
+ * attackers from routing emails to arbitrary agent instances.
+ *
+ * @param secret - Secret key for HMAC verification (must match the key used with signAgentHeaders)
+ * @param options - Optional configuration for signature verification
+ * @returns A function that resolves the agent to route the email to, or null if signature is invalid
+ *
+ * @example
+ * ```typescript
+ * // In your email handler
+ * const secureResolver = createSecureReplyEmailResolver(env.EMAIL_SECRET, {
+ *   maxAge: 7 * 24 * 60 * 60, // 7 days
+ *   onInvalidSignature: (email, reason) => {
+ *     console.warn(`Invalid signature from ${email.from}: ${reason}`);
+ *   }
+ * });
+ * const addressResolver = createAddressBasedEmailResolver("MyAgent");
+ *
+ * await routeAgentEmail(email, env, {
+ *   resolver: async (email, env) => {
+ *     // Try secure reply routing first
+ *     const replyRouting = await secureResolver(email, env);
+ *     if (replyRouting) return replyRouting;
+ *     // Fall back to address-based routing
+ *     return addressResolver(email, env);
+ *   }
+ * });
+ * ```
+ */
+declare function createSecureReplyEmailResolver<Env>(
+  secret: string,
+  options?: SecureReplyResolverOptions
+): 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>;
+//#endregion
 export {
-  AgentEmail,
+  type AgentEmail,
   DEFAULT_MAX_AGE_SECONDS,
   EmailHeader,
   EmailResolver,
@@ -28,3 +157,4 @@ export {
   isAutoReplyEmail,
   signAgentHeaders
 };
+//# sourceMappingURL=email.d.ts.map