agents 0.3.9 → 0.4.0

package/dist/email.js

@@ -1,3 +1,223 @@
-import { a as createSecureReplyEmailResolver, i as createHeaderBasedEmailResolver, n as createAddressBasedEmailResolver, o as isAutoReplyEmail, r as createCatchAllEmailResolver, s as signAgentHeaders, t as DEFAULT_MAX_AGE_SECONDS } from "./email-XHsSYsTO.js";
+//#region src/email.ts
+/**
+* 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;
+* }
+* ```
+*/
+function isAutoReplyEmail(headers) {
+	return headers.some((h) => {
+		const key = h.key.toLowerCase();
+		const value = h.value.toLowerCase();
+		if (key === "auto-submitted") return value !== "no";
+		if (key === "x-auto-response-suppress") return true;
+		if (key === "precedence") return value === "bulk" || value === "junk" || value === "list";
+		return false;
+	});
+}
+/** Default signature expiration: 30 days in seconds */
+const DEFAULT_MAX_AGE_SECONDS = 720 * 60 * 60;
+/** Maximum allowed clock skew for future timestamps: 5 minutes */
+const MAX_CLOCK_SKEW_SECONDS = 300;
+/**
+* Compute HMAC-SHA256 signature for agent routing headers
+* @param secret - Secret key for HMAC
+* @param agentName - Name of the agent
+* @param agentId - ID of the agent instance
+* @param timestamp - Unix timestamp in seconds
+* @returns Base64-encoded HMAC signature
+*/
+async function computeAgentSignature(secret, agentName, agentId, timestamp) {
+	const encoder = new TextEncoder();
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const data = encoder.encode(`${agentName}:${agentId}:${timestamp}`);
+	const signature = await crypto.subtle.sign("HMAC", key, data);
+	return btoa(String.fromCharCode(...new Uint8Array(signature)));
+}
+/**
+* Verify HMAC-SHA256 signature for agent routing headers
+* @param secret - Secret key for HMAC
+* @param agentName - Name of the agent
+* @param agentId - ID of the agent instance
+* @param signature - Base64-encoded signature to verify
+* @param timestamp - Unix timestamp in seconds when signature was created
+* @param maxAgeSeconds - Maximum age of signature in seconds (default: 30 days)
+* @returns Verification result with reason if invalid
+*/
+async function verifyAgentSignature(secret, agentName, agentId, signature, timestamp, maxAgeSeconds = DEFAULT_MAX_AGE_SECONDS) {
+	try {
+		const timestampNum = Number.parseInt(timestamp, 10);
+		if (Number.isNaN(timestampNum)) return {
+			valid: false,
+			reason: "malformed_timestamp"
+		};
+		const now = Math.floor(Date.now() / 1e3);
+		if (timestampNum > now + MAX_CLOCK_SKEW_SECONDS) return {
+			valid: false,
+			reason: "invalid"
+		};
+		if (now - timestampNum > maxAgeSeconds) return {
+			valid: false,
+			reason: "expired"
+		};
+		const expected = await computeAgentSignature(secret, agentName, agentId, timestamp);
+		if (expected.length !== signature.length) return {
+			valid: false,
+			reason: "invalid"
+		};
+		let result = 0;
+		for (let i = 0; i < expected.length; i++) result |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+		if (result !== 0) return {
+			valid: false,
+			reason: "invalid"
+		};
+		return { valid: true };
+	} catch (error) {
+		console.warn("[agents] Signature verification error:", error);
+		return {
+			valid: false,
+			reason: "invalid"
+		};
+	}
+}
+/**
+* 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
+* ```
+*/
+async function signAgentHeaders(secret, agentName, agentId) {
+	if (!secret) throw new Error("secret is required for signing agent headers");
+	if (!agentName) throw new Error("agentName is required for signing agent headers");
+	if (!agentId) throw new Error("agentId is required for signing agent headers");
+	if (agentName.includes(":")) throw new Error("agentName cannot contain colons");
+	if (agentId.includes(":")) throw new Error("agentId cannot contain colons");
+	const timestamp = Math.floor(Date.now() / 1e3).toString();
+	const signature = await computeAgentSignature(secret, agentName, agentId, timestamp);
+	return {
+		"X-Agent-Name": agentName,
+		"X-Agent-ID": agentId,
+		"X-Agent-Sig": signature,
+		"X-Agent-Sig-Ts": timestamp
+	};
+}
+/**
+* @deprecated REMOVED due to security vulnerability (IDOR via spoofed headers).
+* @throws Always throws an error with migration guidance.
+*/
+function createHeaderBasedEmailResolver() {
+	throw new Error("createHeaderBasedEmailResolver has been removed due to a security vulnerability. It trusted attacker-controlled email headers for routing, enabling IDOR attacks.\n\nMigration options:\n  - For inbound mail: use createAddressBasedEmailResolver(agentName)\n  - For reply flows: use createSecureReplyEmailResolver(secret) with signed headers\n\nSee https://github.com/cloudflare/agents/blob/main/docs/email.md for details.");
+}
+/**
+* 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);
+*   }
+* });
+* ```
+*/
+function createSecureReplyEmailResolver(secret, options) {
+	if (!secret) throw new Error("secret is required for createSecureReplyEmailResolver");
+	const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE_SECONDS;
+	const onInvalidSignature = options?.onInvalidSignature;
+	return async (email, _env) => {
+		const agentName = email.headers.get("x-agent-name");
+		const agentId = email.headers.get("x-agent-id");
+		const signature = email.headers.get("x-agent-sig");
+		const timestamp = email.headers.get("x-agent-sig-ts");
+		if (!agentName || !agentId || !signature || !timestamp) {
+			onInvalidSignature?.(email, "missing_headers");
+			return null;
+		}
+		const result = await verifyAgentSignature(secret, agentName, agentId, signature, timestamp, maxAge);
+		if (!result.valid) {
+			onInvalidSignature?.(email, result.reason);
+			return null;
+		}
+		return {
+			agentName,
+			agentId,
+			_secureRouted: true
+		};
+	};
+}
+/**
+* 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
+*/
+function createAddressBasedEmailResolver(defaultAgentName) {
+	return async (email, _env) => {
+		const emailMatch = email.to.match(/^([^+@]{1,64})(?:\+([^@]{1,64}))?@(.{1,253})$/);
+		if (!emailMatch) return null;
+		const [, localPart, subAddress] = emailMatch;
+		if (subAddress) return {
+			agentName: localPart,
+			agentId: subAddress
+		};
+		return {
+			agentName: defaultAgentName,
+			agentId: localPart
+		};
+	};
+}
+/**
+* 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
+*/
+function createCatchAllEmailResolver(agentName, agentId) {
+	return async () => ({
+		agentName,
+		agentId
+	});
+}
 
-export { DEFAULT_MAX_AGE_SECONDS, createAddressBasedEmailResolver, createCatchAllEmailResolver, createHeaderBasedEmailResolver, createSecureReplyEmailResolver, isAutoReplyEmail, signAgentHeaders };
+//#endregion
+export { DEFAULT_MAX_AGE_SECONDS, createAddressBasedEmailResolver, createCatchAllEmailResolver, createHeaderBasedEmailResolver, createSecureReplyEmailResolver, isAutoReplyEmail, signAgentHeaders };
+//# sourceMappingURL=email.js.map

package/dist/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","names":[],"sources":["../src/email.ts"],"sourcesContent":["/**\n * Email routing types, resolvers, and signing utilities for Agents\n */\n\n// Re-export AgentEmail type\nexport type { AgentEmail } from \"./internal_context\";\n\n// ============================================================================\n// Email header utilities\n// ============================================================================\n\n/**\n * Header object as returned by postal-mime and similar email parsing libraries.\n * Each header has a lowercase key and a string value.\n */\nexport type EmailHeader = {\n  /** Lowercase header name (e.g., \"content-type\", \"x-custom-header\") */\n  key: string;\n  /** Header value */\n  value: string;\n};\n\n/**\n * Check if an email appears to be an auto-reply based on standard headers.\n * Checks for Auto-Submitted (RFC 3834), X-Auto-Response-Suppress, and Precedence headers.\n *\n * @param headers - Headers array from postal-mime Email.headers or similar format\n * @returns true if email appears to be an auto-reply\n *\n * @example\n * ```typescript\n * if (isAutoReplyEmail(parsed.headers)) {\n *   // Skip processing auto-replies\n *   return;\n * }\n * ```\n */\nexport function isAutoReplyEmail(headers: EmailHeader[]): boolean {\n  return headers.some((h) => {\n    const key = h.key.toLowerCase();\n    const value = h.value.toLowerCase();\n\n    // RFC 3834: Auto-Submitted header\n    // \"no\" means normal (human-sent) email, anything else indicates auto-reply\n    if (key === \"auto-submitted\") {\n      return value !== \"no\";\n    }\n\n    // X-Auto-Response-Suppress: any value indicates sender doesn't want auto-replies\n    if (key === \"x-auto-response-suppress\") {\n      return true;\n    }\n\n    // Precedence: only bulk/junk/list indicate automated/mass mail\n    if (key === \"precedence\") {\n      return value === \"bulk\" || value === \"junk\" || value === \"list\";\n    }\n\n    return false;\n  });\n}\n\n// ============================================================================\n// Signing utilities\n// ============================================================================\n\n/** Default signature expiration: 30 days in seconds */\nexport const DEFAULT_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;\n\n/** Maximum allowed clock skew for future timestamps: 5 minutes */\nconst MAX_CLOCK_SKEW_SECONDS = 5 * 60;\n\n/**\n * Compute HMAC-SHA256 signature for agent routing headers\n * @param secret - Secret key for HMAC\n * @param agentName - Name of the agent\n * @param agentId - ID of the agent instance\n * @param timestamp - Unix timestamp in seconds\n * @returns Base64-encoded HMAC signature\n */\nasync function computeAgentSignature(\n  secret: string,\n  agentName: string,\n  agentId: string,\n  timestamp: string\n): Promise<string> {\n  const encoder = new TextEncoder();\n  const key = await crypto.subtle.importKey(\n    \"raw\",\n    encoder.encode(secret),\n    { name: \"HMAC\", hash: \"SHA-256\" },\n    false,\n    [\"sign\"]\n  );\n  const data = encoder.encode(`${agentName}:${agentId}:${timestamp}`);\n  const signature = await crypto.subtle.sign(\"HMAC\", key, data);\n  return btoa(String.fromCharCode(...new Uint8Array(signature)));\n}\n\n/**\n * Result of signature verification\n */\ntype SignatureVerificationResult =\n  | { valid: true }\n  | { valid: false; reason: \"expired\" | \"invalid\" | \"malformed_timestamp\" };\n\n/**\n * Verify HMAC-SHA256 signature for agent routing headers\n * @param secret - Secret key for HMAC\n * @param agentName - Name of the agent\n * @param agentId - ID of the agent instance\n * @param signature - Base64-encoded signature to verify\n * @param timestamp - Unix timestamp in seconds when signature was created\n * @param maxAgeSeconds - Maximum age of signature in seconds (default: 30 days)\n * @returns Verification result with reason if invalid\n */\nasync function verifyAgentSignature(\n  secret: string,\n  agentName: string,\n  agentId: string,\n  signature: string,\n  timestamp: string,\n  maxAgeSeconds: number = DEFAULT_MAX_AGE_SECONDS\n): Promise<SignatureVerificationResult> {\n  try {\n    // Validate timestamp format\n    const timestampNum = Number.parseInt(timestamp, 10);\n    if (Number.isNaN(timestampNum)) {\n      return { valid: false, reason: \"malformed_timestamp\" };\n    }\n\n    // Check timestamp validity\n    const now = Math.floor(Date.now() / 1000);\n\n    // Reject timestamps too far in the future (prevents extending signature validity)\n    if (timestampNum > now + MAX_CLOCK_SKEW_SECONDS) {\n      return { valid: false, reason: \"invalid\" };\n    }\n\n    // Check if signature has expired\n    if (now - timestampNum > maxAgeSeconds) {\n      return { valid: false, reason: \"expired\" };\n    }\n\n    const expected = await computeAgentSignature(\n      secret,\n      agentName,\n      agentId,\n      timestamp\n    );\n    // Constant-time comparison to prevent timing attacks\n    if (expected.length !== signature.length) {\n      return { valid: false, reason: \"invalid\" };\n    }\n    let result = 0;\n    for (let i = 0; i < expected.length; i++) {\n      result |= expected.charCodeAt(i) ^ signature.charCodeAt(i);\n    }\n    if (result !== 0) {\n      return { valid: false, reason: \"invalid\" };\n    }\n    return { valid: true };\n  } catch (error) {\n    console.warn(\"[agents] Signature verification error:\", error);\n    return { valid: false, reason: \"invalid\" };\n  }\n}\n\n/**\n * Sign agent routing headers for secure reply flows.\n * Use this when sending outbound emails to ensure replies can be securely routed back.\n *\n * @param secret - Secret key for HMAC signing (store in environment variables)\n * @param agentName - Name of the agent\n * @param agentId - ID of the agent instance\n * @returns Headers object with X-Agent-Name, X-Agent-ID, X-Agent-Sig, and X-Agent-Sig-Ts\n *\n * @example\n * ```typescript\n * const headers = await signAgentHeaders(env.EMAIL_SECRET, \"MyAgent\", this.name);\n * // Use these headers when sending outbound emails\n * ```\n */\nexport async function signAgentHeaders(\n  secret: string,\n  agentName: string,\n  agentId: string\n): Promise<Record<string, string>> {\n  if (!secret) {\n    throw new Error(\"secret is required for signing agent headers\");\n  }\n  if (!agentName) {\n    throw new Error(\"agentName is required for signing agent headers\");\n  }\n  if (!agentId) {\n    throw new Error(\"agentId is required for signing agent headers\");\n  }\n  // Reject colons to prevent signature confusion attacks\n  // (signature payload uses colon as delimiter: \"agentName:agentId:timestamp\")\n  if (agentName.includes(\":\")) {\n    throw new Error(\"agentName cannot contain colons\");\n  }\n  if (agentId.includes(\":\")) {\n    throw new Error(\"agentId cannot contain colons\");\n  }\n\n  const timestamp = Math.floor(Date.now() / 1000).toString();\n  const signature = await computeAgentSignature(\n    secret,\n    agentName,\n    agentId,\n    timestamp\n  );\n  return {\n    \"X-Agent-Name\": agentName,\n    \"X-Agent-ID\": agentId,\n    \"X-Agent-Sig\": signature,\n    \"X-Agent-Sig-Ts\": timestamp\n  };\n}\n\n// ============================================================================\n// Email routing types and resolvers\n// ============================================================================\n\nexport type EmailResolverResult = {\n  agentName: string;\n  agentId: string;\n  /** @internal Indicates this resolver requires secure reply signing */\n  _secureRouted?: boolean;\n} | null;\n\nexport type EmailResolver<Env> = (\n  email: ForwardableEmailMessage,\n  env: Env\n) => Promise<EmailResolverResult>;\n\n/**\n * Reason for signature verification failure\n */\nexport type SignatureFailureReason =\n  | \"missing_headers\"\n  | \"expired\"\n  | \"invalid\"\n  | \"malformed_timestamp\";\n\n/**\n * Options for createSecureReplyEmailResolver\n */\nexport type SecureReplyResolverOptions = {\n  /**\n   * Maximum age of signature in seconds.\n   * Signatures older than this will be rejected.\n   * Default: 30 days (2592000 seconds)\n   */\n  maxAge?: number;\n  /**\n   * Callback invoked when signature verification fails.\n   * Useful for logging and debugging.\n   */\n  onInvalidSignature?: (\n    email: ForwardableEmailMessage,\n    reason: SignatureFailureReason\n  ) => void;\n};\n\n/**\n * @deprecated REMOVED due to security vulnerability (IDOR via spoofed headers).\n * @throws Always throws an error with migration guidance.\n */\nexport function createHeaderBasedEmailResolver<Env>(): EmailResolver<Env> {\n  throw new Error(\n    \"createHeaderBasedEmailResolver has been removed due to a security vulnerability. \" +\n      \"It trusted attacker-controlled email headers for routing, enabling IDOR attacks.\\n\\n\" +\n      \"Migration options:\\n\" +\n      \"  - For inbound mail: use createAddressBasedEmailResolver(agentName)\\n\" +\n      \"  - For reply flows: use createSecureReplyEmailResolver(secret) with signed headers\\n\\n\" +\n      \"See https://github.com/cloudflare/agents/blob/main/docs/email.md for details.\"\n  );\n}\n\n/**\n * Create a resolver for routing email replies with signature verification.\n * This resolver verifies that replies contain a valid HMAC signature, preventing\n * attackers from routing emails to arbitrary agent instances.\n *\n * @param secret - Secret key for HMAC verification (must match the key used with signAgentHeaders)\n * @param options - Optional configuration for signature verification\n * @returns A function that resolves the agent to route the email to, or null if signature is invalid\n *\n * @example\n * ```typescript\n * // In your email handler\n * const secureResolver = createSecureReplyEmailResolver(env.EMAIL_SECRET, {\n *   maxAge: 7 * 24 * 60 * 60, // 7 days\n *   onInvalidSignature: (email, reason) => {\n *     console.warn(`Invalid signature from ${email.from}: ${reason}`);\n *   }\n * });\n * const addressResolver = createAddressBasedEmailResolver(\"MyAgent\");\n *\n * await routeAgentEmail(email, env, {\n *   resolver: async (email, env) => {\n *     // Try secure reply routing first\n *     const replyRouting = await secureResolver(email, env);\n *     if (replyRouting) return replyRouting;\n *     // Fall back to address-based routing\n *     return addressResolver(email, env);\n *   }\n * });\n * ```\n */\nexport function createSecureReplyEmailResolver<Env>(\n  secret: string,\n  options?: SecureReplyResolverOptions\n): EmailResolver<Env> {\n  if (!secret) {\n    throw new Error(\"secret is required for createSecureReplyEmailResolver\");\n  }\n\n  const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE_SECONDS;\n  const onInvalidSignature = options?.onInvalidSignature;\n\n  return async (email: ForwardableEmailMessage, _env: Env) => {\n    const agentName = email.headers.get(\"x-agent-name\");\n    const agentId = email.headers.get(\"x-agent-id\");\n    const signature = email.headers.get(\"x-agent-sig\");\n    const timestamp = email.headers.get(\"x-agent-sig-ts\");\n\n    if (!agentName || !agentId || !signature || !timestamp) {\n      onInvalidSignature?.(email, \"missing_headers\");\n      return null;\n    }\n\n    const result = await verifyAgentSignature(\n      secret,\n      agentName,\n      agentId,\n      signature,\n      timestamp,\n      maxAge\n    );\n\n    if (!result.valid) {\n      onInvalidSignature?.(email, result.reason);\n      return null;\n    }\n\n    return { agentName, agentId, _secureRouted: true };\n  };\n}\n\n/**\n * Create a resolver that uses the email address to determine the agent to route the email to\n * @param defaultAgentName The default agent name to use if the email address does not contain a sub-address\n * @returns A function that resolves the agent to route the email to\n */\nexport function createAddressBasedEmailResolver<Env>(\n  defaultAgentName: string\n): EmailResolver<Env> {\n  return async (email: ForwardableEmailMessage, _env: Env) => {\n    // Length limits per RFC 5321: local part max 64 chars, domain max 253 chars\n    const emailMatch = email.to.match(\n      /^([^+@]{1,64})(?:\\+([^@]{1,64}))?@(.{1,253})$/\n    );\n    if (!emailMatch) {\n      return null;\n    }\n\n    const [, localPart, subAddress] = emailMatch;\n\n    if (subAddress) {\n      return {\n        agentName: localPart,\n        agentId: subAddress\n      };\n    }\n\n    // Option 2: Use defaultAgentName namespace, localPart as agentId\n    // Common for catch-all email routing to a single EmailAgent namespace\n    return {\n      agentName: defaultAgentName,\n      agentId: localPart\n    };\n  };\n}\n\n/**\n * Create a resolver that uses the agentName and agentId to determine the agent to route the email to\n * @param agentName The name of the agent to route the email to\n * @param agentId The id of the agent to route the email to\n * @returns A function that resolves the agent to route the email to\n */\nexport function createCatchAllEmailResolver<Env>(\n  agentName: string,\n  agentId: string\n): EmailResolver<Env> {\n  return async () => ({ agentName, agentId });\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,27 +1,29 @@
-import { n as AgentEmail } from "./internal_context-CEu5ji80.js";
+import { AgentEmail } from "./internal_context.js";
+import { EmailResolver, createHeaderBasedEmailResolver } from "./email.js";
 import {
-  l as createHeaderBasedEmailResolver,
-  r as EmailResolver
-} from "./email-8ljcpvwV.js";
+  l as TransportType,
+  r as MCPConnectionState
+} from "./client-storage-Cvy5r9FG.js";
 import {
-  h as TransportType,
-  t as MCPClientManager,
-  u as MCPConnectionState
-} from "./client-Ba-xntmv.js";
+  AgentMcpOAuthProvider,
+  AgentsOAuthProvider
+} from "./mcp/do-oauth-client-provider.js";
+import { MCPClientManager } from "./mcp/client.js";
 import {
-  _ as WorkflowPage,
-  g as WorkflowInfo,
-  h as WorkflowEventPayload,
-  l as WorkflowCallback,
-  s as RunWorkflowOptions,
-  y as WorkflowQueryCriteria
-} from "./workflow-types-Z_Oem1FJ.js";
-import { t as Observability } from "./index-N6791tVt.js";
-import { t as MessageType } from "./types-DSSHBW6w.js";
+  RunWorkflowOptions,
+  WorkflowCallback,
+  WorkflowEventPayload,
+  WorkflowInfo,
+  WorkflowPage,
+  WorkflowQueryCriteria
+} from "./workflow-types.js";
+import { Observability } from "./observability/index.js";
+import { MessageType } from "./types.js";
 import {
   Connection,
   Connection as Connection$1,
   ConnectionContext,
+  ConnectionContext as ConnectionContext$1,
   PartyServerOptions,
   Server,
   WSMessage
@@ -77,7 +79,7 @@ type RPCResponse = {
  * Metadata for a callable method
  */
 type CallableMetadata = {
-  /** Optional description of what the method does */ description?: string; /** Whether the method supports streaming responses */
+  /** Optional description of what the method does */ description?: string /** Whether the method supports streaming responses */;
   streaming?: boolean;
 };
 /**
@@ -96,7 +98,7 @@ declare function callable(
   metadata?: CallableMetadata
 ): <This, Args extends unknown[], Return>(
   target: (this: This, ...args: Args) => Return,
-  context: ClassMethodDecoratorContext
+  _context: ClassMethodDecoratorContext
 ) => (this: This, ...args: Args) => Return;
 /**
  * Decorator that marks a method as callable by clients
@@ -107,7 +109,7 @@ declare const unstable_callable: (
   metadata?: CallableMetadata
 ) => <This, Args extends unknown[], Return>(
   target: (this: This, ...args: Args) => Return,
-  context: ClassMethodDecoratorContext
+  _context: ClassMethodDecoratorContext
 ) => (this: This, ...args: Args) => Return;
 type QueueItem<T = string> = {
   id: string;
@@ -120,27 +122,27 @@ type QueueItem<T = string> = {
  * @template T Type of the payload data
  */
 type Schedule<T = string> = {
-  /** Unique identifier for the schedule */ id: string; /** Name of the method to be called */
-  callback: string; /** Data to be passed to the callback */
+  /** Unique identifier for the schedule */ id: string /** Name of the method to be called */;
+  callback: string /** Data to be passed to the callback */;
   payload: T;
 } & (
   | {
-      /** Type of schedule for one-time execution at a specific time */ type: "scheduled"; /** Timestamp when the task should execute */
+      /** Type of schedule for one-time execution at a specific time */ type: "scheduled" /** Timestamp when the task should execute */;
       time: number;
     }
   | {
-      /** Type of schedule for delayed execution */ type: "delayed"; /** Timestamp when the task should execute */
-      time: number; /** Number of seconds to delay execution */
+      /** Type of schedule for delayed execution */ type: "delayed" /** Timestamp when the task should execute */;
+      time: number /** Number of seconds to delay execution */;
       delayInSeconds: number;
     }
   | {
-      /** Type of schedule for recurring execution based on cron expression */ type: "cron"; /** Timestamp for the next execution */
-      time: number; /** Cron expression defining the schedule */
+      /** Type of schedule for recurring execution based on cron expression */ type: "cron" /** Timestamp for the next execution */;
+      time: number /** Cron expression defining the schedule */;
       cron: string;
     }
   | {
-      /** Type of schedule for recurring execution at fixed intervals */ type: "interval"; /** Timestamp for the next execution */
-      time: number; /** Number of seconds between executions */
+      /** Type of schedule for recurring execution at fixed intervals */ type: "interval" /** Timestamp for the next execution */;
+      time: number /** Number of seconds between executions */;
       intervalSeconds: number;
     }
 );
@@ -170,6 +172,7 @@ type MCPServer = {
   server_url: string;
   auth_url: string | null;
   state: MCPConnectionState;
+  error: string | null;
   instructions: string | null;
   capabilities: ServerCapabilities | null;
 };
@@ -177,11 +180,19 @@ type MCPServer = {
  * Options for adding an MCP server
  */
 type AddMcpServerOptions = {
-  /** OAuth callback host (auto-derived from request if omitted) */ callbackHost?: string; /** Agents routing prefix (default: "agents") */
-  agentsPrefix?: string; /** MCP client options */
-  client?: ConstructorParameters<typeof Client>[1]; /** Transport options */
+  /** OAuth callback host (auto-derived from request if omitted) */ callbackHost?: string;
+  /**
+   * Custom callback URL path — bypasses the default `/agents/{class}/{name}/callback` construction.
+   * Required when `sendIdentityOnConnect` is `false` to prevent leaking the instance name.
+   * When set, the callback URL becomes `{callbackHost}/{callbackPath}`.
+   * The developer must route this path to the agent instance via `getAgentByName`.
+   * Should be a plain path (e.g., `/mcp-callback`) — do not include query strings or fragments.
+   */
+  callbackPath?: string /** Agents routing prefix (default: "agents") */;
+  agentsPrefix?: string /** MCP client options */;
+  client?: ConstructorParameters<typeof Client>[1] /** Transport options */;
   transport?: {
-    /** Custom headers for authentication (e.g., bearer tokens, CF Access) */ headers?: HeadersInit; /** Transport type: "sse", "streamable-http", or "auto" (default) */
+    /** Custom headers for authentication (e.g., bearer tokens, CF Access) */ headers?: HeadersInit /** Transport type: "sse", "streamable-http", or "auto" (default) */;
     type?: TransportType;
   };
 };
@@ -190,7 +201,7 @@ type AddMcpServerOptions = {
  * Child classes can override specific options without spreading.
  */
 declare const DEFAULT_AGENT_STATIC_OPTIONS: {
-  /** Whether the Agent should hibernate when inactive */ hibernate: boolean; /** Whether to send identity (name, agent) to clients on connect */
+  /** Whether the Agent should hibernate when inactive */ hibernate: boolean /** Whether to send identity (name, agent) to clients on connect */;
   sendIdentityOnConnect: boolean;
   /**
    * Timeout in seconds before a running interval schedule is considered "hung"
@@ -241,6 +252,19 @@ declare class Agent<
   private _state;
   private _disposables;
   private _destroyed;
+  /**
+   * Stores raw state accessors for wrapped connections.
+   * Used by setConnectionReadonly/isConnectionReadonly to read/write the
+   * _cf_readonly flag without going through the user-facing state/setState.
+   */
+  private _rawStateAccessors;
+  /**
+   * Cached persistence-hook dispatch mode, computed once in the constructor.
+   * - "new"  → call onStateChanged
+   * - "old"  → call onStateUpdate (deprecated)
+   * - "none" → neither hook is overridden, skip entirely
+   */
+  private _persistenceHookMode;
   private _ParentClass;
   readonly mcp: MCPClientManager;
   /**
@@ -289,8 +313,39 @@ declare class Agent<
   /**
    * Update the Agent's state
    * @param state New state to set
+   * @throws Error if called from a readonly connection context
    */
   setState(state: State): void;
+  /**
+   * Wraps connection.state and connection.setState so that the internal
+   * _cf_readonly flag is hidden from user code and cannot be accidentally
+   * overwritten. Must be called before any user code sees the connection.
+   *
+   * Idempotent — safe to call multiple times on the same connection.
+   */
+  private _ensureConnectionWrapped;
+  /**
+   * Mark a connection as readonly or readwrite
+   * @param connection The connection to mark
+   * @param readonly Whether the connection should be readonly (default: true)
+   */
+  setConnectionReadonly(connection: Connection$1, readonly?: boolean): void;
+  /**
+   * Check if a connection is marked as readonly
+   * @param connection The connection to check
+   * @returns True if the connection is readonly
+   */
+  isConnectionReadonly(connection: Connection$1): boolean;
+  /**
+   * Override this method to determine if a connection should be readonly on connect
+   * @param _connection The connection that is being established
+   * @param _ctx Connection context
+   * @returns True if the connection should be readonly
+   */
+  shouldConnectionBeReadonly(
+    _connection: Connection$1,
+    _ctx: ConnectionContext$1
+  ): boolean;
   /**
    * Called before the Agent's state is persisted and broadcast.
    * Override to validate or reject an update by throwing an error.
@@ -299,7 +354,25 @@ declare class Agent<
    */
   validateStateChange(nextState: State, source: Connection$1 | "server"): void;
   /**
-   * Called when the Agent's state is updated
+   * Called after the Agent's state has been persisted and broadcast to all clients.
+   * This is a notification hook — errors here are routed to onError and do not
+   * affect state persistence or client broadcasts.
+   *
+   * @param state Updated state
+   * @param source Source of the state update ("server" or a client connection)
+   */
+  onStateChanged(
+    state: State | undefined,
+    source: Connection$1 | "server"
+  ): void;
+  /**
+   * @deprecated Renamed to `onStateChanged` — the behavior is identical.
+   * `onStateUpdate` will be removed in the next major version.
+   *
+   * Called after the Agent's state has been persisted and broadcast to all clients.
+   * This is a server-side notification hook. For the client-side state callback,
+   * see the `onStateUpdate` option in `useAgent` / `AgentClient`.
+   *
    * @param state Updated state
    * @param source Source of the state update ("server" or a client connection)
    */
@@ -307,6 +380,11 @@ declare class Agent<
     state: State | undefined,
     source: Connection$1 | "server"
   ): void;
+  /**
+   * Dispatch to the appropriate persistence hook based on the mode
+   * cached in the constructor. No prototype walks at call time.
+   */
+  private _callStatePersistenceHook;
   /**
    * Called when the Agent receives an email via routeAgentEmail()
    * Override this method to handle incoming emails
@@ -882,6 +960,29 @@ declare class Agent<
   >;
   removeMcpServer(id: string): Promise<void>;
   getMcpServers(): MCPServersState;
+  /**
+   * Create the OAuth provider used when connecting to MCP servers that require authentication.
+   *
+   * Override this method in a subclass to supply a custom OAuth provider implementation,
+   * for example to use pre-registered client credentials, mTLS-based authentication,
+   * or any other OAuth flow beyond dynamic client registration.
+   *
+   * @example
+   * // Custom OAuth provider
+   * class MyAgent extends Agent {
+   *   createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider {
+   *     return new MyCustomOAuthProvider(
+   *       this.ctx.storage,
+   *       this.name,
+   *       callbackUrl
+   *     );
+   *   }
+   * }
+   *
+   * @param callbackUrl The OAuth callback URL for the authorization flow
+   * @returns An {@link AgentMcpOAuthProvider} instance used by {@link addMcpServer}
+   */
+  createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider;
   private broadcastMcpServers;
   /**
    * Handle MCP OAuth callback request if it's an OAuth callback.
@@ -919,12 +1020,7 @@ type AgentContext = DurableObjectState;
 /**
  * Configuration options for Agent routing
  */
-type AgentOptions<Env> = PartyServerOptions<Env> & {
-  /**
-   * Whether to enable CORS for the Agent
-   */
-  cors?: boolean | HeadersInit | undefined;
-};
+type AgentOptions<Env> = PartyServerOptions<Env>;
 /**
  * Route a request to the appropriate Agent
  * @param request Request to route
@@ -1016,9 +1112,11 @@ export {
   AddMcpServerOptions,
   Agent,
   AgentContext,
+  type AgentMcpOAuthProvider,
   AgentNamespace,
   AgentOptions,
   AgentStaticOptions,
+  type AgentsOAuthProvider,
   CallableMetadata,
   type Connection,
   type ConnectionContext,