@mastra/server 1.58.0-alpha.12 → 1.58.0-alpha.13

package/dist/{channels-CPTIswT2.js.map → channels-B9yt3a2P.js.map}

@@ -1 +1 @@
-{"version":3,"file":"channels-CPTIswT2.js","names":[],"sources":["../src/server/schemas/channels.ts","../src/server/handlers/channels.ts"],"sourcesContent":["import { z } from 'zod/v4';\n\n// ============================================================================\n// Path Parameter Schemas\n// ============================================================================\n\nexport const channelPlatformPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n});\n\nexport const channelAgentPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n  agentId: z.string().describe('Agent identifier'),\n});\n\n// ============================================================================\n// Body Parameter Schemas\n// ============================================================================\n\nexport const connectChannelBodySchema = z.object({\n  agentId: z.string().describe('Agent identifier to connect'),\n  options: z.record(z.string(), z.unknown()).optional().describe('Platform-specific connection options'),\n});\n\n// ============================================================================\n// Response Schemas\n// ============================================================================\n\nconst channelPlatformInfoSchema = z.object({\n  id: z.string().describe('Platform identifier'),\n  name: z.string().describe('Human-readable platform name'),\n  isConfigured: z.boolean().describe('Whether the platform is ready to connect agents'),\n  connectOptionsSchema: z.record(z.string(), z.unknown()).optional().describe('JSON Schema for connect options'),\n});\n\nconst channelInstallationInfoSchema = z.object({\n  id: z.string().describe('Installation identifier'),\n  platform: z.string().describe('Platform identifier'),\n  agentId: z.string().describe('Connected agent identifier'),\n  status: z.enum(['active', 'pending']).describe('Installation status'),\n  displayName: z.string().optional().describe('Platform-specific display name'),\n  installedAt: z.coerce.date().optional().describe('Installation timestamp'),\n});\n\nconst channelConnectOAuthSchema = z.object({\n  type: z.literal('oauth').describe('OAuth-based connection requiring browser redirect'),\n  authorizationUrl: z.string().describe('OAuth authorization URL for user redirect'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectDeepLinkSchema = z.object({\n  type: z.literal('deep_link').describe('Deep-link connection requiring native app interaction'),\n  url: z.string().describe('Deep link URL to open in platform app'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectImmediateSchema = z.object({\n  type: z.literal('immediate').describe('Immediate connection with no user interaction needed'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectResultSchema = z.discriminatedUnion('type', [\n  channelConnectOAuthSchema,\n  channelConnectDeepLinkSchema,\n  channelConnectImmediateSchema,\n]);\n\nexport const listChannelPlatformsResponseSchema = z.array(channelPlatformInfoSchema);\n\nexport const listChannelInstallationsResponseSchema = z.array(channelInstallationInfoSchema);\n\nexport const connectChannelResponseSchema = channelConnectResultSchema;\n\nexport const disconnectChannelResponseSchema = z.object({\n  success: z.boolean(),\n});\n","import type { Mastra } from '@mastra/core';\nimport type { ChannelProvider } from '@mastra/core/channels';\nimport type { RequestContext } from '@mastra/core/di';\nimport { coreFeatures } from '@mastra/core/features';\n\nimport { MASTRA_USER_KEY } from '../constants';\nimport { HTTPException } from '../http-exception';\nimport {\n  channelPlatformPathParams,\n  channelAgentPathParams,\n  connectChannelBodySchema,\n  listChannelPlatformsResponseSchema,\n  listChannelInstallationsResponseSchema,\n  connectChannelResponseSchema,\n  disconnectChannelResponseSchema,\n} from '../schemas/channels';\nimport { createRoute } from '../server-adapter/routes/route-builder';\n\nimport { assertWriteAccess, getCallerAuthorId, hasAdminBypass, hasScopedPermission } from './authorship';\nimport { handleError } from './error';\n\n// ============================================================================\n// Feature gate + helpers\n// ============================================================================\n\nfunction assertChannelsAvailable(): void {\n  if (!coreFeatures.has('channels')) {\n    throw new HTTPException(501, { message: 'Channels require a newer version of @mastra/core' });\n  }\n}\n\nfunction getChannelOrThrow(mastra: Mastra, platform: string): ChannelProvider {\n  const channels = Object.values(mastra.channels ?? {});\n  const channel = channels.find(c => c.id === platform);\n  if (!channel) {\n    const available = channels.map(c => c.id).join(', ');\n    throw new HTTPException(404, {\n      message: `Channel \"${platform}\" is not registered. Available: ${available || 'none'}`,\n    });\n  }\n  return channel;\n}\n\n/**\n * Unified connect/disconnect authorization.\n *\n * - Stored agent exists → same write access as editing the agent record.\n * - Code-defined agent (no stored record) → route's `requiresAuth` is the gate.\n * - Agent doesn't exist anywhere:\n *   - connect → 404 (can't connect a channel to a non-existent agent)\n *   - disconnect → orphan cleanup, gated on `channels:write`\n */\nasync function assertChannelAgentWriteAccess(\n  mastra: Mastra,\n  requestContext: RequestContext,\n  agentId: string,\n  action: 'connect' | 'disconnect',\n): Promise<void> {\n  const storage = mastra.getStorage();\n  const agentsStore = storage ? await storage.getStore('agents') : null;\n  const stored = agentsStore ? await agentsStore.getById(agentId) : null;\n\n  if (stored) {\n    assertWriteAccess({\n      requestContext,\n      resource: 'agents',\n      resourceId: agentId,\n      action: 'edit',\n      record: stored,\n    });\n    return;\n  }\n\n  // Not in stored-agents (or storage doesn't support it). Check the runtime\n  // registry for a code-defined agent.\n  const codeDefined = mastra.getAgentById(agentId);\n  if (codeDefined) {\n    // Code-defined agents have no owner/ACL — route's requiresAuth /\n    // requiresPermission is the gate. Pass-through.\n    return;\n  }\n\n  if (action === 'connect') {\n    throw new HTTPException(404, { message: `Agent \"${agentId}\" not found` });\n  }\n\n  // Disconnect against an unknown agentId = orphan cleanup (stored agent was\n  // deleted but the channel installation row is still around). Allow it, but\n  // gate on channels:write so this isn't an \"any authenticated user\" backdoor.\n  // Follow the same no-auth-configured pass-through as assertWriteAccess.\n  const callerAuthorId = getCallerAuthorId(requestContext);\n  if (!callerAuthorId && !requestContext.get(MASTRA_USER_KEY)) return;\n  if (hasAdminBypass(requestContext, 'channels')) return;\n  if (hasScopedPermission({ requestContext, resource: 'channels', action: 'write' })) return;\n\n  throw new HTTPException(404, { message: 'Not found' });\n}\n\n// ============================================================================\n// Route Definitions\n// ============================================================================\n\n/**\n * GET /channels/platforms - List available channel platforms\n */\nexport const LIST_CHANNEL_PLATFORMS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/platforms',\n  responseType: 'json',\n  responseSchema: listChannelPlatformsResponseSchema,\n  summary: 'List channel platforms',\n  description: 'Returns available channel platforms and their configuration status',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra }) => {\n    assertChannelsAvailable();\n    try {\n      const channels = Object.values(mastra.channels ?? {});\n      return channels.map(channel => {\n        if (channel.getInfo) {\n          return channel.getInfo();\n        }\n        return {\n          id: channel.id,\n          name: channel.id.charAt(0).toUpperCase() + channel.id.slice(1),\n          isConfigured: true,\n        };\n      });\n    } catch (error) {\n      return handleError(error, 'Error listing channel platforms');\n    }\n  },\n});\n\n/**\n * GET /channels/:platform/installations - List installations for a platform\n */\nexport const LIST_CHANNEL_INSTALLATIONS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/:platform/installations',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  responseSchema: listChannelInstallationsResponseSchema,\n  summary: 'List channel installations',\n  description: 'Returns all active and pending installations for a channel platform',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, platform }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.listInstallations) {\n        return [];\n      }\n\n      return await channel.listInstallations();\n    } catch (error) {\n      return handleError(error, 'Error listing channel installations');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/connect - Connect an agent to a platform\n */\nexport const CONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/connect',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  bodySchema: connectChannelBodySchema,\n  responseSchema: connectChannelResponseSchema,\n  summary: 'Connect agent to channel',\n  description: 'Creates a platform app for the agent and returns an OAuth authorization URL',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId, options }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.connect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic connection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'connect');\n\n      return await channel.connect(agentId, options);\n    } catch (error) {\n      return handleError(error, 'Error connecting agent to channel');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/:agentId/disconnect - Disconnect an agent from a platform\n */\nexport const DISCONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/:agentId/disconnect',\n  responseType: 'json',\n  pathParamSchema: channelAgentPathParams,\n  responseSchema: disconnectChannelResponseSchema,\n  summary: 'Disconnect agent from channel',\n  description: 'Deletes the platform app and cleans up the installation',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.disconnect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic disconnection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'disconnect');\n\n      await channel.disconnect(agentId);\n      return { success: true };\n    } catch (error) {\n      return handleError(error, 'Error disconnecting agent from channel');\n    }\n  },\n});\n"],"mappings":"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"}
+{"version":3,"file":"channels-B9yt3a2P.js","names":[],"sources":["../src/server/schemas/channels.ts","../src/server/handlers/channels.ts"],"sourcesContent":["import { z } from 'zod/v4';\n\n// ============================================================================\n// Path Parameter Schemas\n// ============================================================================\n\nexport const channelPlatformPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n});\n\nexport const channelAgentPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n  agentId: z.string().describe('Agent identifier'),\n});\n\n// ============================================================================\n// Body Parameter Schemas\n// ============================================================================\n\nexport const connectChannelBodySchema = z.object({\n  agentId: z.string().describe('Agent identifier to connect'),\n  options: z.record(z.string(), z.unknown()).optional().describe('Platform-specific connection options'),\n});\n\n// ============================================================================\n// Response Schemas\n// ============================================================================\n\nconst channelPlatformInfoSchema = z.object({\n  id: z.string().describe('Platform identifier'),\n  name: z.string().describe('Human-readable platform name'),\n  isConfigured: z.boolean().describe('Whether the platform is ready to connect agents'),\n  connectOptionsSchema: z.record(z.string(), z.unknown()).optional().describe('JSON Schema for connect options'),\n});\n\nconst channelInstallationInfoSchema = z.object({\n  id: z.string().describe('Installation identifier'),\n  platform: z.string().describe('Platform identifier'),\n  agentId: z.string().describe('Connected agent identifier'),\n  status: z.enum(['active', 'pending']).describe('Installation status'),\n  displayName: z.string().optional().describe('Platform-specific display name'),\n  installedAt: z.coerce.date().optional().describe('Installation timestamp'),\n});\n\nconst channelConnectOAuthSchema = z.object({\n  type: z.literal('oauth').describe('OAuth-based connection requiring browser redirect'),\n  authorizationUrl: z.string().describe('OAuth authorization URL for user redirect'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectDeepLinkSchema = z.object({\n  type: z.literal('deep_link').describe('Deep-link connection requiring native app interaction'),\n  url: z.string().describe('Deep link URL to open in platform app'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectImmediateSchema = z.object({\n  type: z.literal('immediate').describe('Immediate connection with no user interaction needed'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectResultSchema = z.discriminatedUnion('type', [\n  channelConnectOAuthSchema,\n  channelConnectDeepLinkSchema,\n  channelConnectImmediateSchema,\n]);\n\nexport const listChannelPlatformsResponseSchema = z.array(channelPlatformInfoSchema);\n\nexport const listChannelInstallationsResponseSchema = z.array(channelInstallationInfoSchema);\n\nexport const connectChannelResponseSchema = channelConnectResultSchema;\n\nexport const disconnectChannelResponseSchema = z.object({\n  success: z.boolean(),\n});\n","import type { Mastra } from '@mastra/core';\nimport type { ChannelProvider } from '@mastra/core/channels';\nimport type { RequestContext } from '@mastra/core/di';\nimport { coreFeatures } from '@mastra/core/features';\n\nimport { MASTRA_USER_KEY } from '../constants';\nimport { HTTPException } from '../http-exception';\nimport {\n  channelPlatformPathParams,\n  channelAgentPathParams,\n  connectChannelBodySchema,\n  listChannelPlatformsResponseSchema,\n  listChannelInstallationsResponseSchema,\n  connectChannelResponseSchema,\n  disconnectChannelResponseSchema,\n} from '../schemas/channels';\nimport { createRoute } from '../server-adapter/routes/route-builder';\n\nimport { assertWriteAccess, getCallerAuthorId, hasAdminBypass, hasScopedPermission } from './authorship';\nimport { handleError } from './error';\n\n// ============================================================================\n// Feature gate + helpers\n// ============================================================================\n\nfunction assertChannelsAvailable(): void {\n  if (!coreFeatures.has('channels')) {\n    throw new HTTPException(501, { message: 'Channels require a newer version of @mastra/core' });\n  }\n}\n\nfunction getChannelOrThrow(mastra: Mastra, platform: string): ChannelProvider {\n  const channels = Object.values(mastra.channels ?? {});\n  const channel = channels.find(c => c.id === platform);\n  if (!channel) {\n    const available = channels.map(c => c.id).join(', ');\n    throw new HTTPException(404, {\n      message: `Channel \"${platform}\" is not registered. Available: ${available || 'none'}`,\n    });\n  }\n  return channel;\n}\n\n/**\n * Unified connect/disconnect authorization.\n *\n * - Stored agent exists → same write access as editing the agent record.\n * - Code-defined agent (no stored record) → route's `requiresAuth` is the gate.\n * - Agent doesn't exist anywhere:\n *   - connect → 404 (can't connect a channel to a non-existent agent)\n *   - disconnect → orphan cleanup, gated on `channels:write`\n */\nasync function assertChannelAgentWriteAccess(\n  mastra: Mastra,\n  requestContext: RequestContext,\n  agentId: string,\n  action: 'connect' | 'disconnect',\n): Promise<void> {\n  const storage = mastra.getStorage();\n  const agentsStore = storage ? await storage.getStore('agents') : null;\n  const stored = agentsStore ? await agentsStore.getById(agentId) : null;\n\n  if (stored) {\n    assertWriteAccess({\n      requestContext,\n      resource: 'agents',\n      resourceId: agentId,\n      action: 'edit',\n      record: stored,\n    });\n    return;\n  }\n\n  // Not in stored-agents (or storage doesn't support it). Check the runtime\n  // registry for a code-defined agent.\n  const codeDefined = mastra.getAgentById(agentId);\n  if (codeDefined) {\n    // Code-defined agents have no owner/ACL — route's requiresAuth /\n    // requiresPermission is the gate. Pass-through.\n    return;\n  }\n\n  if (action === 'connect') {\n    throw new HTTPException(404, { message: `Agent \"${agentId}\" not found` });\n  }\n\n  // Disconnect against an unknown agentId = orphan cleanup (stored agent was\n  // deleted but the channel installation row is still around). Allow it, but\n  // gate on channels:write so this isn't an \"any authenticated user\" backdoor.\n  // Follow the same no-auth-configured pass-through as assertWriteAccess.\n  const callerAuthorId = getCallerAuthorId(requestContext);\n  if (!callerAuthorId && !requestContext.get(MASTRA_USER_KEY)) return;\n  if (hasAdminBypass(requestContext, 'channels')) return;\n  if (hasScopedPermission({ requestContext, resource: 'channels', action: 'write' })) return;\n\n  throw new HTTPException(404, { message: 'Not found' });\n}\n\n// ============================================================================\n// Route Definitions\n// ============================================================================\n\n/**\n * GET /channels/platforms - List available channel platforms\n */\nexport const LIST_CHANNEL_PLATFORMS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/platforms',\n  responseType: 'json',\n  responseSchema: listChannelPlatformsResponseSchema,\n  summary: 'List channel platforms',\n  description: 'Returns available channel platforms and their configuration status',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra }) => {\n    assertChannelsAvailable();\n    try {\n      const channels = Object.values(mastra.channels ?? {});\n      return channels.map(channel => {\n        if (channel.getInfo) {\n          return channel.getInfo();\n        }\n        return {\n          id: channel.id,\n          name: channel.id.charAt(0).toUpperCase() + channel.id.slice(1),\n          isConfigured: true,\n        };\n      });\n    } catch (error) {\n      return handleError(error, 'Error listing channel platforms');\n    }\n  },\n});\n\n/**\n * GET /channels/:platform/installations - List installations for a platform\n */\nexport const LIST_CHANNEL_INSTALLATIONS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/:platform/installations',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  responseSchema: listChannelInstallationsResponseSchema,\n  summary: 'List channel installations',\n  description: 'Returns all active and pending installations for a channel platform',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, platform }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.listInstallations) {\n        return [];\n      }\n\n      return await channel.listInstallations();\n    } catch (error) {\n      return handleError(error, 'Error listing channel installations');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/connect - Connect an agent to a platform\n */\nexport const CONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/connect',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  bodySchema: connectChannelBodySchema,\n  responseSchema: connectChannelResponseSchema,\n  summary: 'Connect agent to channel',\n  description: 'Creates a platform app for the agent and returns an OAuth authorization URL',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId, options }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.connect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic connection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'connect');\n\n      return await channel.connect(agentId, options);\n    } catch (error) {\n      return handleError(error, 'Error connecting agent to channel');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/:agentId/disconnect - Disconnect an agent from a platform\n */\nexport const DISCONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/:agentId/disconnect',\n  responseType: 'json',\n  pathParamSchema: channelAgentPathParams,\n  responseSchema: disconnectChannelResponseSchema,\n  summary: 'Disconnect agent from channel',\n  description: 'Deletes the platform app and cleans up the installation',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.disconnect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic disconnection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'disconnect');\n\n      await channel.disconnect(agentId);\n      return { success: true };\n    } catch (error) {\n      return handleError(error, 'Error disconnecting agent from channel');\n    }\n  },\n});\n"],"mappings":"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"}

package/dist/{channels-FoIf30Hv.cjs → channels-BRoq3VKR.cjs}

@@ -1,5 +1,5 @@
 const require_http_exception = require("./http-exception-CKDHupKw.cjs");
-const require_route_builder = require("./route-builder-BBovb2TE.cjs");
+const require_route_builder = require("./route-builder-BAAedfru.cjs");
 require("./constants-ChBaIptn.cjs");
 const require_server_handlers_error = require("./server/handlers/error.cjs");
 const require_server_handlers_authorship = require("./server/handlers/authorship.cjs");
@@ -227,4 +227,4 @@ Object.defineProperty(exports, "LIST_CHANNEL_PLATFORMS_ROUTE", {
 	}
 });
 
-//# sourceMappingURL=channels-FoIf30Hv.cjs.map
+//# sourceMappingURL=channels-BRoq3VKR.cjs.map

package/dist/{channels-FoIf30Hv.cjs.map → channels-BRoq3VKR.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"channels-FoIf30Hv.cjs","names":["z","coreFeatures","HTTPException","getCallerAuthorId","hasAdminBypass","hasScopedPermission","createRoute","handleError"],"sources":["../src/server/schemas/channels.ts","../src/server/handlers/channels.ts"],"sourcesContent":["import { z } from 'zod/v4';\n\n// ============================================================================\n// Path Parameter Schemas\n// ============================================================================\n\nexport const channelPlatformPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n});\n\nexport const channelAgentPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n  agentId: z.string().describe('Agent identifier'),\n});\n\n// ============================================================================\n// Body Parameter Schemas\n// ============================================================================\n\nexport const connectChannelBodySchema = z.object({\n  agentId: z.string().describe('Agent identifier to connect'),\n  options: z.record(z.string(), z.unknown()).optional().describe('Platform-specific connection options'),\n});\n\n// ============================================================================\n// Response Schemas\n// ============================================================================\n\nconst channelPlatformInfoSchema = z.object({\n  id: z.string().describe('Platform identifier'),\n  name: z.string().describe('Human-readable platform name'),\n  isConfigured: z.boolean().describe('Whether the platform is ready to connect agents'),\n  connectOptionsSchema: z.record(z.string(), z.unknown()).optional().describe('JSON Schema for connect options'),\n});\n\nconst channelInstallationInfoSchema = z.object({\n  id: z.string().describe('Installation identifier'),\n  platform: z.string().describe('Platform identifier'),\n  agentId: z.string().describe('Connected agent identifier'),\n  status: z.enum(['active', 'pending']).describe('Installation status'),\n  displayName: z.string().optional().describe('Platform-specific display name'),\n  installedAt: z.coerce.date().optional().describe('Installation timestamp'),\n});\n\nconst channelConnectOAuthSchema = z.object({\n  type: z.literal('oauth').describe('OAuth-based connection requiring browser redirect'),\n  authorizationUrl: z.string().describe('OAuth authorization URL for user redirect'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectDeepLinkSchema = z.object({\n  type: z.literal('deep_link').describe('Deep-link connection requiring native app interaction'),\n  url: z.string().describe('Deep link URL to open in platform app'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectImmediateSchema = z.object({\n  type: z.literal('immediate').describe('Immediate connection with no user interaction needed'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectResultSchema = z.discriminatedUnion('type', [\n  channelConnectOAuthSchema,\n  channelConnectDeepLinkSchema,\n  channelConnectImmediateSchema,\n]);\n\nexport const listChannelPlatformsResponseSchema = z.array(channelPlatformInfoSchema);\n\nexport const listChannelInstallationsResponseSchema = z.array(channelInstallationInfoSchema);\n\nexport const connectChannelResponseSchema = channelConnectResultSchema;\n\nexport const disconnectChannelResponseSchema = z.object({\n  success: z.boolean(),\n});\n","import type { Mastra } from '@mastra/core';\nimport type { ChannelProvider } from '@mastra/core/channels';\nimport type { RequestContext } from '@mastra/core/di';\nimport { coreFeatures } from '@mastra/core/features';\n\nimport { MASTRA_USER_KEY } from '../constants';\nimport { HTTPException } from '../http-exception';\nimport {\n  channelPlatformPathParams,\n  channelAgentPathParams,\n  connectChannelBodySchema,\n  listChannelPlatformsResponseSchema,\n  listChannelInstallationsResponseSchema,\n  connectChannelResponseSchema,\n  disconnectChannelResponseSchema,\n} from '../schemas/channels';\nimport { createRoute } from '../server-adapter/routes/route-builder';\n\nimport { assertWriteAccess, getCallerAuthorId, hasAdminBypass, hasScopedPermission } from './authorship';\nimport { handleError } from './error';\n\n// ============================================================================\n// Feature gate + helpers\n// ============================================================================\n\nfunction assertChannelsAvailable(): void {\n  if (!coreFeatures.has('channels')) {\n    throw new HTTPException(501, { message: 'Channels require a newer version of @mastra/core' });\n  }\n}\n\nfunction getChannelOrThrow(mastra: Mastra, platform: string): ChannelProvider {\n  const channels = Object.values(mastra.channels ?? {});\n  const channel = channels.find(c => c.id === platform);\n  if (!channel) {\n    const available = channels.map(c => c.id).join(', ');\n    throw new HTTPException(404, {\n      message: `Channel \"${platform}\" is not registered. Available: ${available || 'none'}`,\n    });\n  }\n  return channel;\n}\n\n/**\n * Unified connect/disconnect authorization.\n *\n * - Stored agent exists → same write access as editing the agent record.\n * - Code-defined agent (no stored record) → route's `requiresAuth` is the gate.\n * - Agent doesn't exist anywhere:\n *   - connect → 404 (can't connect a channel to a non-existent agent)\n *   - disconnect → orphan cleanup, gated on `channels:write`\n */\nasync function assertChannelAgentWriteAccess(\n  mastra: Mastra,\n  requestContext: RequestContext,\n  agentId: string,\n  action: 'connect' | 'disconnect',\n): Promise<void> {\n  const storage = mastra.getStorage();\n  const agentsStore = storage ? await storage.getStore('agents') : null;\n  const stored = agentsStore ? await agentsStore.getById(agentId) : null;\n\n  if (stored) {\n    assertWriteAccess({\n      requestContext,\n      resource: 'agents',\n      resourceId: agentId,\n      action: 'edit',\n      record: stored,\n    });\n    return;\n  }\n\n  // Not in stored-agents (or storage doesn't support it). Check the runtime\n  // registry for a code-defined agent.\n  const codeDefined = mastra.getAgentById(agentId);\n  if (codeDefined) {\n    // Code-defined agents have no owner/ACL — route's requiresAuth /\n    // requiresPermission is the gate. Pass-through.\n    return;\n  }\n\n  if (action === 'connect') {\n    throw new HTTPException(404, { message: `Agent \"${agentId}\" not found` });\n  }\n\n  // Disconnect against an unknown agentId = orphan cleanup (stored agent was\n  // deleted but the channel installation row is still around). Allow it, but\n  // gate on channels:write so this isn't an \"any authenticated user\" backdoor.\n  // Follow the same no-auth-configured pass-through as assertWriteAccess.\n  const callerAuthorId = getCallerAuthorId(requestContext);\n  if (!callerAuthorId && !requestContext.get(MASTRA_USER_KEY)) return;\n  if (hasAdminBypass(requestContext, 'channels')) return;\n  if (hasScopedPermission({ requestContext, resource: 'channels', action: 'write' })) return;\n\n  throw new HTTPException(404, { message: 'Not found' });\n}\n\n// ============================================================================\n// Route Definitions\n// ============================================================================\n\n/**\n * GET /channels/platforms - List available channel platforms\n */\nexport const LIST_CHANNEL_PLATFORMS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/platforms',\n  responseType: 'json',\n  responseSchema: listChannelPlatformsResponseSchema,\n  summary: 'List channel platforms',\n  description: 'Returns available channel platforms and their configuration status',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra }) => {\n    assertChannelsAvailable();\n    try {\n      const channels = Object.values(mastra.channels ?? {});\n      return channels.map(channel => {\n        if (channel.getInfo) {\n          return channel.getInfo();\n        }\n        return {\n          id: channel.id,\n          name: channel.id.charAt(0).toUpperCase() + channel.id.slice(1),\n          isConfigured: true,\n        };\n      });\n    } catch (error) {\n      return handleError(error, 'Error listing channel platforms');\n    }\n  },\n});\n\n/**\n * GET /channels/:platform/installations - List installations for a platform\n */\nexport const LIST_CHANNEL_INSTALLATIONS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/:platform/installations',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  responseSchema: listChannelInstallationsResponseSchema,\n  summary: 'List channel installations',\n  description: 'Returns all active and pending installations for a channel platform',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, platform }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.listInstallations) {\n        return [];\n      }\n\n      return await channel.listInstallations();\n    } catch (error) {\n      return handleError(error, 'Error listing channel installations');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/connect - Connect an agent to a platform\n */\nexport const CONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/connect',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  bodySchema: connectChannelBodySchema,\n  responseSchema: connectChannelResponseSchema,\n  summary: 'Connect agent to channel',\n  description: 'Creates a platform app for the agent and returns an OAuth authorization URL',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId, options }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.connect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic connection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'connect');\n\n      return await channel.connect(agentId, options);\n    } catch (error) {\n      return handleError(error, 'Error connecting agent to channel');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/:agentId/disconnect - Disconnect an agent from a platform\n */\nexport const DISCONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/:agentId/disconnect',\n  responseType: 'json',\n  pathParamSchema: channelAgentPathParams,\n  responseSchema: disconnectChannelResponseSchema,\n  summary: 'Disconnect agent from channel',\n  description: 'Deletes the platform app and cleans up the installation',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.disconnect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic disconnection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'disconnect');\n\n      await channel.disconnect(agentId);\n      return { success: true };\n    } catch (error) {\n      return handleError(error, 'Error disconnecting agent from channel');\n    }\n  },\n});\n"],"mappings":"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"}
+{"version":3,"file":"channels-BRoq3VKR.cjs","names":["z","coreFeatures","HTTPException","getCallerAuthorId","hasAdminBypass","hasScopedPermission","createRoute","handleError"],"sources":["../src/server/schemas/channels.ts","../src/server/handlers/channels.ts"],"sourcesContent":["import { z } from 'zod/v4';\n\n// ============================================================================\n// Path Parameter Schemas\n// ============================================================================\n\nexport const channelPlatformPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n});\n\nexport const channelAgentPathParams = z.object({\n  platform: z.string().describe('Channel platform identifier (e.g., \"slack\")'),\n  agentId: z.string().describe('Agent identifier'),\n});\n\n// ============================================================================\n// Body Parameter Schemas\n// ============================================================================\n\nexport const connectChannelBodySchema = z.object({\n  agentId: z.string().describe('Agent identifier to connect'),\n  options: z.record(z.string(), z.unknown()).optional().describe('Platform-specific connection options'),\n});\n\n// ============================================================================\n// Response Schemas\n// ============================================================================\n\nconst channelPlatformInfoSchema = z.object({\n  id: z.string().describe('Platform identifier'),\n  name: z.string().describe('Human-readable platform name'),\n  isConfigured: z.boolean().describe('Whether the platform is ready to connect agents'),\n  connectOptionsSchema: z.record(z.string(), z.unknown()).optional().describe('JSON Schema for connect options'),\n});\n\nconst channelInstallationInfoSchema = z.object({\n  id: z.string().describe('Installation identifier'),\n  platform: z.string().describe('Platform identifier'),\n  agentId: z.string().describe('Connected agent identifier'),\n  status: z.enum(['active', 'pending']).describe('Installation status'),\n  displayName: z.string().optional().describe('Platform-specific display name'),\n  installedAt: z.coerce.date().optional().describe('Installation timestamp'),\n});\n\nconst channelConnectOAuthSchema = z.object({\n  type: z.literal('oauth').describe('OAuth-based connection requiring browser redirect'),\n  authorizationUrl: z.string().describe('OAuth authorization URL for user redirect'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectDeepLinkSchema = z.object({\n  type: z.literal('deep_link').describe('Deep-link connection requiring native app interaction'),\n  url: z.string().describe('Deep link URL to open in platform app'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectImmediateSchema = z.object({\n  type: z.literal('immediate').describe('Immediate connection with no user interaction needed'),\n  installationId: z.string().describe('Installation identifier'),\n});\n\nconst channelConnectResultSchema = z.discriminatedUnion('type', [\n  channelConnectOAuthSchema,\n  channelConnectDeepLinkSchema,\n  channelConnectImmediateSchema,\n]);\n\nexport const listChannelPlatformsResponseSchema = z.array(channelPlatformInfoSchema);\n\nexport const listChannelInstallationsResponseSchema = z.array(channelInstallationInfoSchema);\n\nexport const connectChannelResponseSchema = channelConnectResultSchema;\n\nexport const disconnectChannelResponseSchema = z.object({\n  success: z.boolean(),\n});\n","import type { Mastra } from '@mastra/core';\nimport type { ChannelProvider } from '@mastra/core/channels';\nimport type { RequestContext } from '@mastra/core/di';\nimport { coreFeatures } from '@mastra/core/features';\n\nimport { MASTRA_USER_KEY } from '../constants';\nimport { HTTPException } from '../http-exception';\nimport {\n  channelPlatformPathParams,\n  channelAgentPathParams,\n  connectChannelBodySchema,\n  listChannelPlatformsResponseSchema,\n  listChannelInstallationsResponseSchema,\n  connectChannelResponseSchema,\n  disconnectChannelResponseSchema,\n} from '../schemas/channels';\nimport { createRoute } from '../server-adapter/routes/route-builder';\n\nimport { assertWriteAccess, getCallerAuthorId, hasAdminBypass, hasScopedPermission } from './authorship';\nimport { handleError } from './error';\n\n// ============================================================================\n// Feature gate + helpers\n// ============================================================================\n\nfunction assertChannelsAvailable(): void {\n  if (!coreFeatures.has('channels')) {\n    throw new HTTPException(501, { message: 'Channels require a newer version of @mastra/core' });\n  }\n}\n\nfunction getChannelOrThrow(mastra: Mastra, platform: string): ChannelProvider {\n  const channels = Object.values(mastra.channels ?? {});\n  const channel = channels.find(c => c.id === platform);\n  if (!channel) {\n    const available = channels.map(c => c.id).join(', ');\n    throw new HTTPException(404, {\n      message: `Channel \"${platform}\" is not registered. Available: ${available || 'none'}`,\n    });\n  }\n  return channel;\n}\n\n/**\n * Unified connect/disconnect authorization.\n *\n * - Stored agent exists → same write access as editing the agent record.\n * - Code-defined agent (no stored record) → route's `requiresAuth` is the gate.\n * - Agent doesn't exist anywhere:\n *   - connect → 404 (can't connect a channel to a non-existent agent)\n *   - disconnect → orphan cleanup, gated on `channels:write`\n */\nasync function assertChannelAgentWriteAccess(\n  mastra: Mastra,\n  requestContext: RequestContext,\n  agentId: string,\n  action: 'connect' | 'disconnect',\n): Promise<void> {\n  const storage = mastra.getStorage();\n  const agentsStore = storage ? await storage.getStore('agents') : null;\n  const stored = agentsStore ? await agentsStore.getById(agentId) : null;\n\n  if (stored) {\n    assertWriteAccess({\n      requestContext,\n      resource: 'agents',\n      resourceId: agentId,\n      action: 'edit',\n      record: stored,\n    });\n    return;\n  }\n\n  // Not in stored-agents (or storage doesn't support it). Check the runtime\n  // registry for a code-defined agent.\n  const codeDefined = mastra.getAgentById(agentId);\n  if (codeDefined) {\n    // Code-defined agents have no owner/ACL — route's requiresAuth /\n    // requiresPermission is the gate. Pass-through.\n    return;\n  }\n\n  if (action === 'connect') {\n    throw new HTTPException(404, { message: `Agent \"${agentId}\" not found` });\n  }\n\n  // Disconnect against an unknown agentId = orphan cleanup (stored agent was\n  // deleted but the channel installation row is still around). Allow it, but\n  // gate on channels:write so this isn't an \"any authenticated user\" backdoor.\n  // Follow the same no-auth-configured pass-through as assertWriteAccess.\n  const callerAuthorId = getCallerAuthorId(requestContext);\n  if (!callerAuthorId && !requestContext.get(MASTRA_USER_KEY)) return;\n  if (hasAdminBypass(requestContext, 'channels')) return;\n  if (hasScopedPermission({ requestContext, resource: 'channels', action: 'write' })) return;\n\n  throw new HTTPException(404, { message: 'Not found' });\n}\n\n// ============================================================================\n// Route Definitions\n// ============================================================================\n\n/**\n * GET /channels/platforms - List available channel platforms\n */\nexport const LIST_CHANNEL_PLATFORMS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/platforms',\n  responseType: 'json',\n  responseSchema: listChannelPlatformsResponseSchema,\n  summary: 'List channel platforms',\n  description: 'Returns available channel platforms and their configuration status',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra }) => {\n    assertChannelsAvailable();\n    try {\n      const channels = Object.values(mastra.channels ?? {});\n      return channels.map(channel => {\n        if (channel.getInfo) {\n          return channel.getInfo();\n        }\n        return {\n          id: channel.id,\n          name: channel.id.charAt(0).toUpperCase() + channel.id.slice(1),\n          isConfigured: true,\n        };\n      });\n    } catch (error) {\n      return handleError(error, 'Error listing channel platforms');\n    }\n  },\n});\n\n/**\n * GET /channels/:platform/installations - List installations for a platform\n */\nexport const LIST_CHANNEL_INSTALLATIONS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/channels/:platform/installations',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  responseSchema: listChannelInstallationsResponseSchema,\n  summary: 'List channel installations',\n  description: 'Returns all active and pending installations for a channel platform',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, platform }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.listInstallations) {\n        return [];\n      }\n\n      return await channel.listInstallations();\n    } catch (error) {\n      return handleError(error, 'Error listing channel installations');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/connect - Connect an agent to a platform\n */\nexport const CONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/connect',\n  responseType: 'json',\n  pathParamSchema: channelPlatformPathParams,\n  bodySchema: connectChannelBodySchema,\n  responseSchema: connectChannelResponseSchema,\n  summary: 'Connect agent to channel',\n  description: 'Creates a platform app for the agent and returns an OAuth authorization URL',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId, options }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.connect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic connection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'connect');\n\n      return await channel.connect(agentId, options);\n    } catch (error) {\n      return handleError(error, 'Error connecting agent to channel');\n    }\n  },\n});\n\n/**\n * POST /channels/:platform/:agentId/disconnect - Disconnect an agent from a platform\n */\nexport const DISCONNECT_CHANNEL_ROUTE = createRoute({\n  method: 'POST',\n  path: '/channels/:platform/:agentId/disconnect',\n  responseType: 'json',\n  pathParamSchema: channelAgentPathParams,\n  responseSchema: disconnectChannelResponseSchema,\n  summary: 'Disconnect agent from channel',\n  description: 'Deletes the platform app and cleans up the installation',\n  tags: ['Channels'],\n  requiresAuth: true,\n  handler: async ({ mastra, requestContext, platform, agentId }) => {\n    assertChannelsAvailable();\n    try {\n      const channel = getChannelOrThrow(mastra, platform);\n\n      if (!channel.disconnect) {\n        throw new HTTPException(400, {\n          message: `Channel \"${platform}\" does not support programmatic disconnection`,\n        });\n      }\n\n      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'disconnect');\n\n      await channel.disconnect(agentId);\n      return { success: true };\n    } catch (error) {\n      return handleError(error, 'Error disconnecting agent from channel');\n    }\n  },\n});\n"],"mappings":"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"}

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-server
 description: Documentation for @mastra/server. Use when working with @mastra/server APIs, configuration, or implementation.
 metadata:
   package: "@mastra/server"
-  version: "1.58.0-alpha.12"
+  version: "1.58.0-alpha.13"
 ---
 
 ## When to use
@@ -18,6 +18,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 - [A2A](references/docs-agents-a2a.md) - Expose and call remote Mastra agents over the Agent-to-Agent protocol.
 - [Custom adapters](references/docs-server-custom-adapters.md) - Create a custom server adapter for frameworks other than Hono or Express.
+- [Custom API routes](references/docs-server-custom-api-routes.md) - Expose additional HTTP endpoints from your Mastra server.
 - [Middleware](references/docs-server-middleware.md) - Apply custom middleware functions to intercept requests.
 
 ### Reference

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.58.0-alpha.12",
+  "version": "1.58.0-alpha.13",
   "package": "@mastra/server",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-server-custom-api-routes.md

@@ -0,0 +1,375 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Custom API routes
+
+By default, Mastra automatically exposes registered agents and workflows via its server. For additional behavior you can define your own HTTP routes.
+
+Routes are provided with a helper `registerApiRoute()` from `@mastra/core/server`. Routes can live in the same file as the `Mastra` instance but separating them helps keep configuration concise.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/my-custom-route', {
+        method: 'GET',
+        handler: async c => {
+          const mastra = c.get('mastra')
+          const agent = await mastra.getAgent('my-agent')
+
+          return c.json({ message: 'Custom route' })
+        },
+      }),
+    ],
+  },
+})
+```
+
+Once registered, a custom route will be accessible from the root of the server. For example:
+
+```bash
+curl http://localhost:4111/my-custom-route
+```
+
+Each route's handler receives the Hono `Context`. Within the handler you can access the `Mastra` instance to fetch or call agents and workflows.
+
+## Schema validation
+
+Use [`createRoute()`](https://mastra.ai/reference/server/create-route) in `apiRoutes` to parse and validate path parameters, query parameters, and request bodies with Zod. The schemas also infer the handler parameters and generate OpenAPI metadata.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { createRoute } from '@mastra/server/server-adapter'
+import { z } from 'zod'
+
+const createItemRoute = createRoute({
+  method: 'POST',
+  path: '/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string().min(1),
+  }),
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+  handler: async ({ name }) => ({
+    id: crypto.randomUUID(),
+    name,
+  }),
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [createItemRoute],
+  },
+})
+```
+
+By default, Mastra returns a `400` response when validation fails. The `onValidationError` callback can override the status and response body. Validated values and the `Mastra` server context are passed directly to the handler.
+
+## Middleware
+
+To add route-specific middleware pass a `middleware` array when calling `registerApiRoute()`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/my-custom-route', {
+        method: 'GET',
+        middleware: [
+          async (c, next) => {
+            console.log(`${c.req.method} ${c.req.url}`)
+            await next()
+          },
+        ],
+        handler: async c => {
+          return c.json({ message: 'Custom route with middleware' })
+        },
+      }),
+    ],
+  },
+})
+```
+
+## OpenAPI documentation
+
+Custom routes can include OpenAPI metadata to appear in the Swagger UI alongside Mastra server routes. You can access the OpenAPI spec at `/api/openapi.json`, where both custom routes and built-in routes are listed. Pass an `openapi` option with standard OpenAPI operation fields.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+import { z } from 'zod'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/items/:itemId', {
+        method: 'GET',
+        openapi: {
+          summary: 'Get item by ID',
+          description: 'Retrieves a single item by its unique identifier',
+          tags: ['Items'],
+          parameters: [
+            {
+              name: 'itemId',
+              in: 'path',
+              required: true,
+              description: 'The item ID',
+              schema: { type: 'string' },
+            },
+          ],
+          responses: {
+            200: {
+              description: 'Item found',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      id: { type: 'string' },
+                      name: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            },
+            404: {
+              description: 'Item not found',
+            },
+          },
+        },
+        handler: async c => {
+          const itemId = c.req.param('itemId')
+          return c.json({ id: itemId, name: 'Example Item' })
+        },
+      }),
+    ],
+  },
+})
+```
+
+### Using Zod Schemas
+
+Zod schemas in the `openapi` configuration are converted to JSON Schema when the OpenAPI document is generated:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+import { z } from 'zod'
+
+const ItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+})
+
+const CreateItemSchema = z.object({
+  name: z.string().min(1),
+  price: z.number().positive(),
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/items', {
+        method: 'POST',
+        openapi: {
+          summary: 'Create a new item',
+          tags: ['Items'],
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: CreateItemSchema,
+              },
+            },
+          },
+          responses: {
+            201: {
+              description: 'Item created',
+              content: {
+                'application/json': {
+                  schema: ItemSchema,
+                },
+              },
+            },
+          },
+        },
+        handler: async c => {
+          const body = await c.req.json()
+          return c.json({ id: 'new-id', ...body }, 201)
+        },
+      }),
+    ],
+  },
+})
+```
+
+### Viewing in Swagger UI
+
+When running in development mode (`mastra dev`) or with `swaggerUI: true` in build options, your custom routes appear in the Swagger UI at `/swagger-ui`.
+
+```typescript
+export const mastra = new Mastra({
+  server: {
+    build: {
+      swaggerUI: true, // Enable in production builds
+    },
+    apiRoutes: [
+      // Your routes...
+    ],
+  },
+})
+```
+
+## Authentication
+
+When authentication is configured on your Mastra server, custom API routes require authentication by default. To make a route publicly accessible, set `requiresAuth: false`:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+import { MastraJwtAuth } from '@mastra/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraJwtAuth({
+      secret: process.env.MASTRA_JWT_SECRET,
+    }),
+    apiRoutes: [
+      // Protected route (default behavior)
+      registerApiRoute('/protected-data', {
+        method: 'GET',
+        handler: async c => {
+          // Access authenticated user from request context
+          const user = c.get('requestContext').get('user')
+          return c.json({ message: 'Authenticated user', user })
+        },
+      }),
+
+      // Public route (no authentication required)
+      registerApiRoute('/webhooks/github', {
+        method: 'POST',
+        requiresAuth: false, // Explicitly opt out of authentication
+        handler: async c => {
+          const payload = await c.req.json()
+          // Process webhook without authentication
+          return c.json({ received: true })
+        },
+      }),
+    ],
+  },
+})
+```
+
+### Authentication behavior
+
+- **No auth configured**: All routes (built-in and custom) are public
+
+- **Auth configured**:
+
+  - Mastra-provided routes (`/api/agents/*`, `/api/workflows/*`, etc.) require authentication
+  - Custom routes require authentication by default
+  - Custom routes can opt out with `requiresAuth: false`
+
+### Accessing user information
+
+When a request is authenticated, the user object is available in the request context:
+
+```typescript
+registerApiRoute('/user-profile', {
+  method: 'GET',
+  handler: async c => {
+    const requestContext = c.get('requestContext')
+    const user = requestContext.get('user')
+
+    return c.json({ user })
+  },
+})
+```
+
+For more information about authentication providers, see the [Auth documentation](https://mastra.ai/docs/server/auth).
+
+## Continue generation after client disconnect
+
+Built-in streaming helpers such as [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) forward the incoming request's `AbortSignal` to `agent.stream()`. That's the right default when a browser disconnect should cancel the model call.
+
+For custom streaming routes that should stop when the client disconnects, pass `c.req.raw.signal` to long-running work such as `agent.stream()`. Mastra's Node-based adapters also stop reading streamed `Response` bodies from custom routes when the client connection closes. Streamed response body errors that aren't caused by client disconnects still propagate through the adapter's normal error handling. In Hono, disconnect behavior depends on the host runtime forwarding connection closes to `request.signal`.
+
+```typescript
+registerApiRoute('/stream', {
+  method: 'GET',
+  handler: async c => {
+    const stream = await agent.stream(prompt, {
+      abortSignal: c.req.raw.signal,
+    })
+
+    return stream.toTextStreamResponse()
+  },
+})
+```
+
+If you want the server to keep generating and persist the final response even after the client disconnects, build a custom route around the underlying `MastraModelOutput`. Start the agent stream without forwarding `c.req.raw.signal`, then call `consumeStream()` in the background so generation continues server-side.
+
+```typescript
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  InferUIMessageChunk,
+  UIMessage,
+} from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/chat/persist/:agentId', {
+        method: 'POST',
+        handler: async c => {
+          const { messages, memory } = await c.req.json()
+          const mastra = c.get('mastra')
+          const agent = mastra.getAgent(c.req.param('agentId'))
+
+          const stream = await agent.stream(messages, {
+            memory,
+            // Do not pass c.req.raw.signal if this route should keep running
+            // after the client disconnects.
+          })
+
+          void stream.consumeStream().catch(error => {
+            mastra.getLogger()?.error('Background stream consumption failed', { error })
+          })
+
+          const uiStream = createUIMessageStream({
+            originalMessages: messages,
+            execute: async ({ writer }) => {
+              for await (const part of toAISdkStream(stream, { from: 'agent' })) {
+                writer.write(part as InferUIMessageChunk<UIMessage>)
+              }
+            },
+          })
+
+          return createUIMessageStreamResponse({ stream: uiStream })
+        },
+      }),
+    ],
+  },
+})
+```
+
+> **Note:** Use this pattern only when you intentionally want work to continue after the HTTP client is gone. If you want disconnects to cancel generation, keep using `chatRoute()` or forward the request `AbortSignal` yourself.
+
+## Related
+
+- [registerApiRoute() Reference](https://mastra.ai/reference/server/register-api-route): Full API reference
+- [Server Middleware](https://mastra.ai/docs/server/middleware): Global middleware configuration
+- [Mastra Server](https://mastra.ai/docs/server/mastra-server): Server configuration options

package/dist/docs/references/reference-server-create-route.md

@@ -72,10 +72,36 @@ handler: async params => {
 
 ## Return value
 
-Returns a `ServerRoute` object that can be registered with an adapter.
+Returns a `ServerRoute` object that can be registered with an adapter or passed to `server.apiRoutes` on the `Mastra` instance.
 
 ## Examples
 
+### Register through `server.apiRoutes`
+
+Routes created with `createRoute()` can be passed to `server.apiRoutes`. The adapter registers them with runtime validation, typed handler parameters, and generated OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { createRoute } from '@mastra/server/server-adapter'
+import { z } from 'zod'
+
+const createItemRoute = createRoute({
+  method: 'POST',
+  path: '/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string(),
+  }),
+  handler: async ({ name }) => ({ id: 'new-id', name }),
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [createItemRoute],
+  },
+})
+```
+
 ### GET route with path params
 
 ```typescript

package/dist/{dynamic-workflows-CQs6_anZ.js → dynamic-workflows-B0TE8mjA.js}

@@ -1,6 +1,6 @@
 import { n as __exportAll } from "./rolldown-runtime-DuvcJU0W.js";
 import { t as HTTPException } from "./http-exception-CyfxZB6W.js";
-import { n as createRoute } from "./route-builder-CQkb7tQY.js";
+import { n as createRoute } from "./route-builder-YQ_gLIvW.js";
 import { handleError } from "./server/handlers/error.js";
 import { z } from "zod/v4";
 //#region src/server/schemas/dynamic-workflows.ts
@@ -335,4 +335,4 @@ const DELETE_DYNAMIC_WORKFLOW_ROUTE = createRoute({
 //#endregion
 export { dynamic_workflows_exports as a, UPSERT_DYNAMIC_WORKFLOW_ROUTE as i, GET_DYNAMIC_WORKFLOW_ROUTE as n, LIST_DYNAMIC_WORKFLOWS_ROUTE as r, DELETE_DYNAMIC_WORKFLOW_ROUTE as t };
 
-//# sourceMappingURL=dynamic-workflows-CQs6_anZ.js.map
+//# sourceMappingURL=dynamic-workflows-B0TE8mjA.js.map