agents 0.21.0 → 0.23.0

package/dist/email.js.map

@@ -1 +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/agents/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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"}
+{"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/** Cloudflare Email Service binding. */\nexport type EmailSendBinding = SendEmail;\n\n/** Options for sending an outbound email from an Agent. */\nexport type SendEmailOptions = {\n  binding: EmailSendBinding;\n  to: string | string[];\n  from: string | { email: string; name?: string };\n  subject: string;\n  text?: string;\n  html?: string;\n  replyTo?: string | { email: string; name?: string };\n  cc?: string | string[];\n  bcc?: string | string[];\n  inReplyTo?: string;\n  headers?: Record<string, string>;\n  secret?: string;\n};\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/agents/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/{handler-stateless-C_bo-Ytq.d.ts → handler-stateless-DxYpJ_XF.d.ts}

@@ -44,13 +44,13 @@ interface ServeOptions {
   jurisdiction?: DurableObjectJurisdiction;
 }
 //#endregion
-//#region src/mcp/auth-context.d.ts
+//#region src/mcp/server/auth-context.d.ts
 interface McpAuthContext {
   props: Record<string, unknown>;
 }
 declare function getMcpAuthContext(): McpAuthContext | undefined;
 //#endregion
-//#region src/mcp/handler-stateless.d.ts
+//#region src/mcp/server/handler-stateless.d.ts
 interface CreateStatelessMcpHandlerOptions extends Omit<
   CreateMcpHandlerOptions,
   "bus"
@@ -104,4 +104,4 @@ export {
   CreateStatelessMcpHandlerOptions as t,
   McpClientOptions as u
 };
-//# sourceMappingURL=handler-stateless-C_bo-Ytq.d.ts.map
+//# sourceMappingURL=handler-stateless-DxYpJ_XF.d.ts.map

package/dist/{handler-stateless-CIkKPETH.js → handler-stateless-VvrWSAVA.js}

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { WebStandardStreamableHTTPServerTransport, createMcpHandler, hostHeaderValidationResponse, isJSONRPCRequest, isLegacyRequest, localhostAllowedHostnames, localhostAllowedOrigins, originValidationResponse } from "@modelcontextprotocol/server";
-//#region src/mcp/auth-context.ts
+//#region src/mcp/server/auth-context.ts
 const VERIFIED_OAUTH_CONTEXT = Symbol.for("cloudflare.workers-oauth-provider.verified-context.v1");
 const authContextStorage = new AsyncLocalStorage();
 function getMcpAuthContext() {
@@ -49,7 +49,7 @@ function getVerifiedOAuthAuthInfo(ctx) {
 	};
 }
 //#endregion
-//#region src/mcp/handler-errors.ts
+//#region src/mcp/server/handler-errors.ts
 function internalErrorResponse(id = null) {
 	return Response.json({
 		jsonrpc: "2.0",
@@ -70,7 +70,7 @@ function reportHandlerError(onerror, error) {
 	} catch {}
 }
 //#endregion
-//#region src/mcp/handler-legacy-compat.ts
+//#region src/mcp/server/handler-legacy-compat.ts
 /**
 * Temporary adapter for Legacy compatibility on the SDK v2 transport.
 *
@@ -178,7 +178,7 @@ function createLegacyCompatibilityRequestHandler(factory, handlerOptions = {}) {
 	return { fetch };
 }
 //#endregion
-//#region src/mcp/handler-stateless.ts
+//#region src/mcp/server/handler-stateless.ts
 const DEFAULT_CORS_OPTIONS = {
 	origin: "*",
 	headers: "Content-Type, Accept, Authorization, mcp-session-id, MCP-Protocol-Version, Mcp-Method, Mcp-Name",
@@ -315,4 +315,4 @@ function createStatelessMcpHandler(factory, options = {}) {
 //#endregion
 export { getMcpAuthContext as n, runWithAuthContext as r, createStatelessMcpHandler as t };
 
-//# sourceMappingURL=handler-stateless-CIkKPETH.js.map
+//# sourceMappingURL=handler-stateless-VvrWSAVA.js.map

package/dist/handler-stateless-VvrWSAVA.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-stateless-VvrWSAVA.js","names":["candidate","createSdkMcpHandler"],"sources":["../src/mcp/server/auth-context.ts","../src/mcp/server/handler-errors.ts","../src/mcp/server/handler-legacy-compat.ts","../src/mcp/server/handler-stateless.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { AuthInfo } from \"@modelcontextprotocol/server\";\n\nconst VERIFIED_OAUTH_CONTEXT = Symbol.for(\n  \"cloudflare.workers-oauth-provider.verified-context.v1\"\n);\n\ninterface VerifiedWorkersOAuthContext {\n  version: 1;\n  token: string;\n  clientId: string;\n  scopes: string[];\n  expiresAt?: number;\n  resource?: string;\n  props: Record<string, unknown>;\n}\n\nexport interface McpAuthContext {\n  props: Record<string, unknown>;\n}\n\nconst authContextStorage = new AsyncLocalStorage<McpAuthContext>();\n\nexport function getMcpAuthContext(): McpAuthContext | undefined {\n  return authContextStorage.getStore();\n}\n\nexport function runWithAuthContext<T>(context: McpAuthContext, fn: () => T): T {\n  return authContextStorage.run(context, fn);\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    return false;\n  }\n  const prototype = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction invalidVerifiedContext(): never {\n  throw new TypeError(\"Invalid verified OAuth request context\");\n}\n\nexport function getVerifiedOAuthAuthInfo(\n  ctx: ExecutionContext\n): { authInfo: AuthInfo; props: Record<string, unknown> } | undefined {\n  const symbolContext = ctx as ExecutionContext & Record<symbol, unknown>;\n  if (!(VERIFIED_OAUTH_CONTEXT in symbolContext)) return undefined;\n\n  const value = symbolContext[VERIFIED_OAUTH_CONTEXT];\n  if (!isPlainRecord(value) || value.version !== 1) invalidVerifiedContext();\n\n  const candidate = value as Partial<VerifiedWorkersOAuthContext>;\n  const { token, clientId, scopes, expiresAt, resource, props } = candidate;\n  if (\n    typeof token !== \"string\" ||\n    token.length === 0 ||\n    typeof clientId !== \"string\" ||\n    clientId.length === 0 ||\n    !Array.isArray(scopes) ||\n    !scopes.every((scope) => typeof scope === \"string\") ||\n    !isPlainRecord(props)\n  ) {\n    invalidVerifiedContext();\n  }\n\n  if (\n    expiresAt !== undefined &&\n    (typeof expiresAt !== \"number\" ||\n      !Number.isFinite(expiresAt) ||\n      expiresAt <= 0)\n  ) {\n    invalidVerifiedContext();\n  }\n\n  let resourceUrl: URL | undefined;\n  if (resource !== undefined) {\n    if (typeof resource !== \"string\") invalidVerifiedContext();\n    try {\n      resourceUrl = new URL(resource);\n    } catch {\n      invalidVerifiedContext();\n    }\n    if (resourceUrl.protocol !== \"http:\" && resourceUrl.protocol !== \"https:\") {\n      invalidVerifiedContext();\n    }\n  }\n\n  if (ctx.props !== props) invalidVerifiedContext();\n\n  return {\n    props,\n    authInfo: {\n      token,\n      clientId,\n      scopes: [...scopes],\n      ...(expiresAt !== undefined && { expiresAt }),\n      ...(resourceUrl !== undefined && { resource: resourceUrl }),\n      extra: { props }\n    }\n  };\n}\n","export function internalErrorResponse(\n  id: string | number | null = null\n): Response {\n  return Response.json(\n    {\n      jsonrpc: \"2.0\",\n      error: { code: -32603, message: \"Internal server error\" },\n      id\n    },\n    { status: 500 }\n  );\n}\n\nexport function requestIdFromParsedBody(body: unknown): string | number | null {\n  if (\n    typeof body !== \"object\" ||\n    body === null ||\n    Array.isArray(body) ||\n    !(\"method\" in body) ||\n    typeof body.method !== \"string\" ||\n    !(\"id\" in body)\n  ) {\n    return null;\n  }\n  return typeof body.id === \"string\" || typeof body.id === \"number\"\n    ? body.id\n    : null;\n}\n\nexport function reportHandlerError(\n  onerror: ((error: Error) => void) | undefined,\n  error: unknown\n): void {\n  try {\n    onerror?.(error instanceof Error ? error : new Error(String(error)));\n  } catch {\n    // Error reporting must not change the response.\n  }\n}\n","import {\n  WebStandardStreamableHTTPServerTransport,\n  isJSONRPCRequest,\n  type CreateMcpHandlerOptions,\n  type McpHandlerRequestOptions,\n  type McpServer,\n  type McpServerFactory,\n  type Server\n} from \"@modelcontextprotocol/server\";\nimport {\n  internalErrorResponse,\n  reportHandlerError,\n  requestIdFromParsedBody\n} from \"./handler-errors\";\n/**\n * Temporary adapter for Legacy compatibility on the SDK v2 transport.\n *\n * Local deltas from the upstream stateless fallback:\n *\n * - impossible stateless server-to-client requests fail immediately rather\n *   than leaving the tool handler waiting for a session response.\n *\n * Streaming and keepalive behavior remain delegated to the SDK transport.\n * Remove this adapter once the SDK exposes the reverse-request policy directly.\n */\nexport function createLegacyCompatibilityRequestHandler(\n  factory: McpServerFactory,\n  handlerOptions: Pick<CreateMcpHandlerOptions, \"keepAliveMs\" | \"onerror\"> = {}\n) {\n  const { keepAliveMs, onerror } = handlerOptions;\n  const fetch = async (\n    request: Request,\n    requestOptions: McpHandlerRequestOptions | undefined\n  ): Promise<Response> => {\n    // Match the upstream Legacy fallback: GET and DELETE are session operations\n    // and cannot be served by a fresh per-request transport. Reject\n    // them before running a factory with application-visible side effects.\n    if (request.method.toUpperCase() !== \"POST\") {\n      return Response.json(\n        {\n          jsonrpc: \"2.0\",\n          error: { code: -32000, message: \"Method not allowed.\" },\n          id: null\n        },\n        { status: 405 }\n      );\n    }\n\n    if (request.signal.aborted) {\n      return new Response(null, { status: 499 });\n    }\n\n    let product: McpServer | Server | undefined;\n    let transport: WebStandardStreamableHTTPServerTransport | undefined;\n    let teardownPromise: Promise<void> | undefined;\n    const teardown = () =>\n      (teardownPromise ??= (async () => {\n        await Promise.all([\n          transport?.close().catch(() => {}),\n          product?.close().catch(() => {})\n        ]);\n      })());\n    const onAbort = () => void teardown();\n\n    try {\n      product = await factory({\n        era: \"legacy\",\n        ...(requestOptions?.authInfo !== undefined && {\n          authInfo: requestOptions.authInfo\n        }),\n        requestInfo: request\n      });\n      transport = new WebStandardStreamableHTTPServerTransport({\n        keepAliveMs,\n        sessionIdGenerator: undefined\n      });\n\n      const send = transport.send.bind(transport);\n      transport.send = async (message, sendOptions) => {\n        if (isJSONRPCRequest(message)) {\n          transport?.onmessage?.({\n            jsonrpc: \"2.0\",\n            id: message.id,\n            error: {\n              code: -32603,\n              message:\n                \"Server-to-client requests are unavailable in the Legacy compatibility lane. \" +\n                \"Use inputRequired(...) for Stateless clients, or route \" +\n                \"Legacy traffic to a sessionful transport.\"\n            }\n          });\n          return;\n        }\n        await send(message, sendOptions);\n      };\n\n      await product.connect(transport);\n      if (request.signal.aborted) {\n        await teardown();\n        return new Response(null, { status: 499 });\n      }\n      request.signal.addEventListener(\"abort\", onAbort, { once: true });\n      const response = await transport.handleRequest(request, {\n        ...(requestOptions?.authInfo !== undefined && {\n          authInfo: requestOptions.authInfo\n        }),\n        ...(requestOptions?.parsedBody !== undefined && {\n          parsedBody: requestOptions.parsedBody\n        })\n      });\n\n      if (\n        response.body === null ||\n        !response.headers.get(\"content-type\")?.includes(\"text/event-stream\")\n      ) {\n        request.signal.removeEventListener(\"abort\", onAbort);\n        await teardown();\n        return response;\n      }\n\n      const reader = response.body.getReader();\n      const body = new ReadableStream<Uint8Array>({\n        async pull(controller) {\n          try {\n            const { done, value } = await reader.read();\n            if (done) {\n              request.signal.removeEventListener(\"abort\", onAbort);\n              await teardown();\n              controller.close();\n            } else if (value !== undefined) {\n              controller.enqueue(value);\n            }\n          } catch (error) {\n            request.signal.removeEventListener(\"abort\", onAbort);\n            await teardown();\n            controller.error(error);\n          }\n        },\n        async cancel(reason) {\n          request.signal.removeEventListener(\"abort\", onAbort);\n          await reader.cancel(reason).catch(() => {});\n          await teardown();\n        }\n      });\n      return new Response(body, {\n        status: response.status,\n        statusText: response.statusText,\n        headers: response.headers\n      });\n    } catch (error) {\n      request.signal.removeEventListener(\"abort\", onAbort);\n      await teardown();\n      reportHandlerError(onerror, error);\n      return internalErrorResponse(\n        requestIdFromParsedBody(requestOptions?.parsedBody)\n      );\n    }\n  };\n\n  return { fetch };\n}\n","import {\n  createMcpHandler as createSdkMcpHandler,\n  hostHeaderValidationResponse,\n  isLegacyRequest,\n  localhostAllowedHostnames,\n  localhostAllowedOrigins,\n  originValidationResponse,\n  type AuthInfo,\n  type CreateMcpHandlerOptions as SdkCreateMcpHandlerOptions,\n  type McpHandlerRequestOptions,\n  type McpServerFactory,\n  type ServerNotifier\n} from \"@modelcontextprotocol/server\";\nimport {\n  getVerifiedOAuthAuthInfo,\n  runWithAuthContext,\n  type McpAuthContext\n} from \"./auth-context\";\nimport { internalErrorResponse, reportHandlerError } from \"./handler-errors\";\nimport { createLegacyCompatibilityRequestHandler } from \"./handler-legacy-compat\";\nimport type { CORSOptions } from \"../types\";\n\nexport interface CreateStatelessMcpHandlerOptions extends Omit<\n  SdkCreateMcpHandlerOptions,\n  \"bus\"\n> {\n  /** Exact pathname handled by this Worker wrapper. @default \"/mcp\" */\n  route?: string;\n  /** CORS headers applied by the Worker wrapper. Pass `false` to disable. */\n  corsOptions?: CORSOptions | false;\n  /**\n   * Restrict `Host` headers to these hostnames. Localhost and `workers.dev`\n   * endpoints receive matching defaults; custom domains rely on Cloudflare\n   * routing unless this option is set.\n   */\n  allowedHostnames?: string[];\n  /**\n   * Restrict present browser `Origin` headers to these hostnames. Requests\n   * without an Origin (including non-browser MCP clients) remain valid. The\n   * default includes localhost-class Origins, the endpoint's `workers.dev`\n   * hostname, and a concrete `corsOptions.origin` hostname. Pass `\"*\"` only\n   * when equivalent Origin validation runs in trusted middleware upstream.\n   */\n  allowedOriginHostnames?: string[] | \"*\";\n  /** Application props exposed through {@link getMcpAuthContext}. */\n  authContext?: McpAuthContext;\n}\n\nexport type StatelessMcpHandler = {\n  (request: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;\n  fetch(\n    request: Request,\n    options?: McpHandlerRequestOptions\n  ): Promise<Response>;\n  notify: ServerNotifier;\n};\n\nexport type StatelessMcpServerInput = McpServerFactory;\n\nconst DEFAULT_CORS_OPTIONS: Required<CORSOptions> = {\n  origin: \"*\",\n  headers:\n    \"Content-Type, Accept, Authorization, mcp-session-id, MCP-Protocol-Version, Mcp-Method, Mcp-Name\",\n  methods: \"GET, POST, DELETE, OPTIONS\",\n  exposeHeaders: \"mcp-session-id\",\n  maxAge: 86400\n};\n\nfunction corsHeaders(options: CORSOptions = {}): Headers {\n  const merged = { ...DEFAULT_CORS_OPTIONS, ...options };\n  return new Headers({\n    \"Access-Control-Allow-Headers\": merged.headers,\n    \"Access-Control-Allow-Methods\": merged.methods,\n    \"Access-Control-Allow-Origin\": merged.origin,\n    \"Access-Control-Expose-Headers\": merged.exposeHeaders,\n    \"Access-Control-Max-Age\": String(merged.maxAge)\n  });\n}\n\nfunction withCors(response: Response, options: CORSOptions | false): Response {\n  const headers = new Headers(response.headers);\n  if (options === false) {\n    for (const name of Array.from(headers.keys())) {\n      if (name.toLowerCase().startsWith(\"access-control-\")) {\n        headers.delete(name);\n      }\n    }\n  } else {\n    for (const [name, value] of corsHeaders(options)) {\n      headers.set(name, value);\n    }\n  }\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers\n  });\n}\n\nfunction wrapResponseBodyWithAuthContext(\n  response: Response,\n  authContext: McpAuthContext | undefined\n): Response {\n  if (!authContext || !response.body) return response;\n\n  const reader = response.body.getReader();\n  const body = new ReadableStream<Uint8Array>({\n    pull(controller) {\n      return runWithAuthContext(authContext, async () => {\n        try {\n          const { done, value } = await reader.read();\n          if (done) {\n            controller.close();\n          } else {\n            controller.enqueue(value);\n          }\n        } catch (error) {\n          controller.error(error);\n        }\n      });\n    },\n    cancel(reason) {\n      return runWithAuthContext(authContext, () => reader.cancel(reason));\n    }\n  });\n\n  return new Response(body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers: response.headers\n  });\n}\n\nexport function createStatelessMcpHandler(\n  factory: StatelessMcpServerInput,\n  options: CreateStatelessMcpHandlerOptions = {}\n): StatelessMcpHandler {\n  const optionRecord = options as Record<string, unknown>;\n  if (optionRecord.bus !== undefined) {\n    throw new TypeError(\n      'createMcpHandler option \"bus\" is not exposed by the Agents SDK.'\n    );\n  }\n  const legacyOnlyOption = [\n    \"transport\",\n    \"storage\",\n    \"sessionIdGenerator\",\n    \"onsessioninitialized\",\n    \"onsessionclosed\",\n    \"enableJsonResponse\",\n    \"eventStore\",\n    \"allowedHosts\",\n    \"allowedOrigins\",\n    \"enableDnsRebindingProtection\",\n    \"retryInterval\"\n  ].find((key) => optionRecord[key] !== undefined);\n  if (legacyOnlyOption) {\n    throw new TypeError(\n      `createMcpHandler option \"${legacyOnlyOption}\" is only supported with an MCP SDK v1 server. The managed SDK v2 handler is stateless; remove this option or keep the v1 server during migration.`\n    );\n  }\n\n  const {\n    route = \"/mcp\",\n    corsOptions = {},\n    allowedHostnames,\n    allowedOriginHostnames,\n    authContext,\n    legacy = \"stateless\",\n    ...sdkOptions\n  } = options;\n\n  const sdkHandler = createSdkMcpHandler(factory, {\n    ...sdkOptions,\n    legacy: \"reject\"\n  });\n  const legacyCompatibilityHandler =\n    legacy === \"stateless\"\n      ? createLegacyCompatibilityRequestHandler(factory, {\n          keepAliveMs: sdkOptions.keepAliveMs,\n          onerror: sdkOptions.onerror\n        })\n      : undefined;\n\n  const serve = async (\n    request: Request,\n    requestOptions?: McpHandlerRequestOptions,\n    workerCtx?: ExecutionContext\n  ): Promise<Response> => {\n    const requestUrl = new URL(request.url);\n    if (requestUrl.pathname !== route) {\n      return withCors(new Response(\"Not Found\", { status: 404 }), corsOptions);\n    }\n\n    // The SDK app factories can distinguish their bind address from an\n    // attacker-controlled Host header. A bare Worker cannot. Use defaults we\n    // can establish independently: localhost-class names, a standard\n    // workers.dev route, and any concrete CORS Origin the application chose.\n    // Custom-domain deployments can provide explicit Host and Origin lists.\n    const localEndpoint = localhostAllowedHostnames().includes(\n      requestUrl.hostname\n    );\n    const workersDevEndpoint = requestUrl.hostname.endsWith(\".workers.dev\");\n    const acceptedHostnames =\n      allowedHostnames ??\n      (localEndpoint\n        ? localhostAllowedHostnames()\n        : workersDevEndpoint\n          ? [requestUrl.hostname]\n          : undefined);\n    const hostRejection = acceptedHostnames\n      ? hostHeaderValidationResponse(request, acceptedHostnames)\n      : undefined;\n    if (hostRejection) {\n      return withCors(hostRejection, corsOptions);\n    }\n    if (allowedOriginHostnames !== \"*\") {\n      let acceptedOriginHostnames = allowedOriginHostnames;\n      if (acceptedOriginHostnames === undefined) {\n        const defaults = new Set(localhostAllowedOrigins());\n        if (workersDevEndpoint) defaults.add(requestUrl.hostname);\n        if (corsOptions !== false && corsOptions.origin !== undefined) {\n          try {\n            const configuredOrigin = new URL(corsOptions.origin);\n            if (\n              (configuredOrigin.protocol === \"http:\" ||\n                configuredOrigin.protocol === \"https:\") &&\n              configuredOrigin.hostname\n            ) {\n              defaults.add(configuredOrigin.hostname);\n            }\n          } catch {\n            // A wildcard or malformed CORS value does not expand the allowlist.\n          }\n        }\n        acceptedOriginHostnames = [...defaults];\n      }\n      const originRejection = originValidationResponse(\n        request,\n        acceptedOriginHostnames ?? []\n      );\n      if (originRejection) {\n        return withCors(originRejection, corsOptions);\n      }\n    }\n\n    if (request.method === \"OPTIONS\" && corsOptions !== false) {\n      return new Response(null, { headers: corsHeaders(corsOptions) });\n    }\n\n    const legacyRequest =\n      legacyCompatibilityHandler !== undefined &&\n      (await isLegacyRequest(request, requestOptions?.parsedBody));\n\n    try {\n      const verified = workerCtx\n        ? getVerifiedOAuthAuthInfo(workerCtx)\n        : undefined;\n      const explicitAuthInfo = requestOptions?.authInfo;\n      if (\n        verified &&\n        explicitAuthInfo &&\n        explicitAuthInfo.clientId !== verified.authInfo.clientId\n      ) {\n        throw new TypeError(\"Conflicting verified OAuth client identity\");\n      }\n\n      const authInfo: AuthInfo | undefined =\n        explicitAuthInfo ?? verified?.authInfo;\n      const resolvedAuthContext =\n        authContext ??\n        (verified\n          ? { props: verified.props }\n          : workerCtx?.props && Object.keys(workerCtx.props).length > 0\n            ? { props: workerCtx.props as Record<string, unknown> }\n            : undefined);\n      const upstreamOptions: McpHandlerRequestOptions | undefined =\n        requestOptions || authInfo\n          ? { ...requestOptions, ...(authInfo && { authInfo }) }\n          : undefined;\n      const invoke = async () => {\n        if (legacyRequest && legacyCompatibilityHandler) {\n          return legacyCompatibilityHandler.fetch(request, upstreamOptions);\n        }\n        return sdkHandler.fetch(request, upstreamOptions);\n      };\n      const response = resolvedAuthContext\n        ? await runWithAuthContext(resolvedAuthContext, invoke)\n        : await invoke();\n      return withCors(\n        wrapResponseBodyWithAuthContext(response, resolvedAuthContext),\n        corsOptions\n      );\n    } catch (error) {\n      reportHandlerError(sdkOptions.onerror, error);\n      return withCors(internalErrorResponse(), corsOptions);\n    }\n  };\n\n  const callable = (request: Request, _env: unknown, ctx: ExecutionContext) =>\n    serve(request, undefined, ctx);\n  const fetch = (request: Request, requestOptions?: McpHandlerRequestOptions) =>\n    serve(request, requestOptions);\n\n  return Object.assign(callable, {\n    fetch,\n    notify: sdkHandler.notify\n  }) as StatelessMcpHandler;\n}\n"],"mappings":"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"}

package/dist/index-BB0kqhIz.d.ts

@@ -0,0 +1,101 @@
+import {
+  D as ChannelInboundMessage,
+  F as ChannelMessageSurface,
+  U as UserIdentity,
+  V as ChannelIdentity,
+  a as ChannelApprovalRequestOptions,
+  d as ChannelRoute,
+  h as DeliveryResult,
+  j as ChannelIngressEvent,
+  l as ChannelDeliveryOptions,
+  n as Channel,
+  p as ChannelStreamOptions,
+  s as ChannelChunkSource,
+  u as ChannelMessage,
+  w as ChannelEmailInput,
+  y as ChannelApprovalResponse
+} from "./channel-Bnm4S7T2.js";
+
+//#region src/channels/host/index.d.ts
+type ChannelMessageEvent = {
+  channelKey: string;
+  route: string /** Stable identity derived only from the configured Channel and eventId. */;
+  dispatchId: string;
+  message: ChannelInboundMessage;
+};
+type ChannelApprovalResponseEvent = {
+  channelKey: string;
+  route: string /** Stable identity derived only from the configured Channel and eventId. */;
+  dispatchId: string;
+  response: ChannelApprovalResponse;
+};
+type ChannelRouteEvent = {
+  channelKey: string;
+  event: ChannelIngressEvent;
+  route:
+    | string
+    | null /** Stable identity derived only from the configured Channel and eventId. */;
+  dispatchId: string;
+};
+type ChannelHostOptions = {
+  channels: Record<
+    string,
+    Channel
+  > /** Used when a Channel does not provide a route. Default: event thread id. */;
+  defaultRoute?: ChannelRoute /** Resolve an existing, explicitly linked application user. */;
+  findUser?(
+    identity: ChannelIdentity
+  ): Promise<UserIdentity | null> /** Observes every valid route outcome before application dispatch. */;
+  onRoute?(event: ChannelRouteEvent): void | Promise<void>;
+  onMessage?(event: ChannelMessageEvent): void | Promise<void>;
+  onApprovalResponse?(
+    event: ChannelApprovalResponseEvent
+  ): void | Promise<void>;
+};
+/**
+ * Authenticates and normalizes ingress through configured Channel adapters,
+ * resolves outbound surfaces, and awaits the application's durable handoff.
+ */
+declare class ChannelHost {
+  #private;
+  constructor(options: ChannelHostOptions);
+  handleRequest(request: Request): Promise<Response | undefined>;
+  handleEmail(email: ChannelEmailInput): Promise<boolean>;
+  /** Deliver through the configured Channel or composite named by the surface. */
+  deliver(
+    surface: ChannelMessageSurface,
+    message: ChannelMessage,
+    options?: ChannelDeliveryOptions
+  ): Promise<DeliveryResult>;
+  /**
+   * Deliver a progressively generated answer to the Channel or composite
+   * named by the surface.
+   *
+   * A Channel that can stream consumes the stream itself. A Channel that
+   * cannot never learns it was a stream, because the Host collects the answer
+   * and calls `deliver` once.
+   */
+  stream(
+    surface: ChannelMessageSurface,
+    chunks: ChannelChunkSource,
+    options?: ChannelStreamOptions
+  ): Promise<DeliveryResult>;
+  /** Request approval through the Channel or composite named by the surface. */
+  requestApproval(
+    surface: ChannelMessageSurface,
+    options: ChannelApprovalRequestOptions
+  ): Promise<DeliveryResult>;
+  /** Return the identity's configured Channel destination, when supported. */
+  contactSurface(identity: ChannelIdentity): ChannelMessageSurface | null;
+  /** Resolve whether a surface can currently be selected without delivery. */
+  isAvailable(surface: ChannelMessageSurface): Promise<boolean>;
+}
+//#endregion
+export {
+  ChannelRouteEvent as a,
+  ChannelMessageEvent as i,
+  ChannelHost as n,
+  ChannelHostOptions as r,
+  ChannelApprovalResponseEvent as t
+};
+//# sourceMappingURL=index-BB0kqhIz.d.ts.map

package/dist/index-XDkuQ7zm.d.ts

@@ -0,0 +1,89 @@
+//#region src/tasks/errors.d.ts
+/**
+ * Error classes for the Tasks capability. Each carries a stable `name` so
+ * hosts and tests can classify failures without depending on message text.
+ */
+/**
+ * Thrown by a step callback to fail its run immediately, skipping any
+ * remaining retry attempts.
+ *
+ * Errors named `"NonRetryableError"` from other sources (for example
+ * `cloudflare:workflows`) are honored the same way.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class NonRetryableError extends Error {
+  constructor(
+    message: string,
+    options?: {
+      cause?: unknown;
+    }
+  );
+}
+/**
+ * Thrown before executing user code when one replay uses the same step name
+ * twice. Step names are durable journal keys and must be unique within a run.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class DuplicateTaskStepError extends Error {
+  /** The step name used more than once. */
+  readonly stepName: string;
+  constructor(stepName: string);
+}
+/**
+ * Thrown when a replay observes a journal that this handler code cannot have
+ * written — a known step under a different kind, for example. The run fails
+ * rather than guessing; changing a definition's step layout for in-flight
+ * runs requires versioning the definition name.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class TaskReplayDivergedError extends Error {
+  /** The step name where replay diverged from the journal. */
+  readonly stepName: string;
+  constructor(stepName: string, detail: string);
+}
+/**
+ * Recorded against a run whose persisted definition name is no longer
+ * registered after a deployment. The run fails visibly; it is never silently
+ * deleted and never replayed against a different handler.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class MissingTaskDefinitionError extends Error {
+  /** The persisted definition name that no longer resolves. */
+  readonly definition: string;
+  constructor(definition: string);
+}
+/**
+ * Thrown when a Task input, step result, metadata value, or final result is
+ * not JSON-serializable or exceeds the serialized size limit.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class TaskSerializationError extends Error {
+  constructor(context: string, detail: string);
+}
+//#endregion
+//#region src/tasks/serialization.d.ts
+/**
+ * Value serialization for the Tasks capability.
+ *
+ * Task inputs, step results, metadata, and final results persist as JSON
+ * text in SQLite. `undefined` (and a `void` handler result) is represented
+ * as SQL `NULL` rather than a JSON envelope, so the JSON column space stays
+ * plain: `"null"` is JSON `null`, column `NULL` is `undefined`.
+ */
+/** Default ceiling for one serialized value (1 MiB). */
+declare const MAX_SERIALIZED_BYTES = 1048576;
+//#endregion
+export {
+  TaskReplayDivergedError as a,
+  NonRetryableError as i,
+  DuplicateTaskStepError as n,
+  TaskSerializationError as o,
+  MissingTaskDefinitionError as r,
+  MAX_SERIALIZED_BYTES as t
+};
+//# sourceMappingURL=index-XDkuQ7zm.d.ts.map

package/dist/{index-BRnybD6X.d.ts → index-YSKgfgg9.d.ts}

@@ -776,33 +776,8 @@ type AgentObservabilityEvent =
       }
     >;
 //#endregion
-//#region src/observability/index.d.ts
-/**
- * Union of all observability event types from different domains
- */
-type ObservabilityEvent = AgentObservabilityEvent | MCPObservabilityEvent;
-interface Observability {
-  /**
-   * Emit an event for the Agent's observability implementation to handle.
-   * @param event - The event to emit
-   */
-  emit(event: ObservabilityEvent): void;
-}
-/**
- * Diagnostics channels for agent observability.
- *
- * Events are published to named channels using the Node.js diagnostics_channel API.
- * By default, publishing to a channel with no subscribers is a no-op (zero overhead).
- *
- * To observe events, subscribe to the channels you care about:
- * ```ts
- * import { subscribe } from "node:diagnostics_channel";
- * subscribe("agents:rpc", (event) => console.log(event));
- * ```
- *
- * In production, all published messages are automatically forwarded to
- * Tail Workers via `event.diagnosticsChannelEvents` — no subscription needed.
- */
+//#region src/observability/diagnostics.d.ts
+/** Diagnostics channels for Agent and Lifecycle telemetry. */
 declare const channels: {
   readonly state: Channel<any, any>;
   readonly rpc: Channel<any, any>;
@@ -810,6 +785,8 @@ declare const channels: {
   readonly chat: Channel<any, any>;
   readonly transcript: Channel<any, any>;
   readonly fiber: Channel<any, any>;
+  readonly task: Channel<any, any>;
+  readonly stream: Channel<any, any>;
   readonly agentTool: Channel<any, any>;
   readonly schedule: Channel<any, any>;
   readonly lifecycle: Channel<any, any>;
@@ -818,6 +795,19 @@ declare const channels: {
   readonly email: Channel<any, any>;
   readonly channel: Channel<any, any>;
 };
+//#endregion
+//#region src/observability/index.d.ts
+/**
+ * Union of all observability event types from different domains
+ */
+type ObservabilityEvent = AgentObservabilityEvent | MCPObservabilityEvent;
+interface Observability {
+  /**
+   * Emit an event for the Agent's observability implementation to handle.
+   * @param event - The event to emit
+   */
+  emit(event: ObservabilityEvent): void;
+}
 /**
  * The default observability implementation.
  *
@@ -936,12 +926,12 @@ declare function subscribe$1<K extends keyof ChannelEventMap>(
 ): () => void;
 //#endregion
 export {
-  genericObservability as a,
-  channels as i,
+  subscribe$1 as a,
+  genericObservability as i,
   Observability as n,
-  subscribe$1 as o,
+  channels as o,
   ObservabilityEvent as r,
   MCPObservabilityEvent as s,
   ChannelEventMap as t
 };
-//# sourceMappingURL=index-BRnybD6X.d.ts.map
+//# sourceMappingURL=index-YSKgfgg9.d.ts.map