@voltagent/server-core 1.0.24 → 1.0.26

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { H as HttpMethod, A as ApiResponse, a as A2AServerLikeWithHandlers } fro
 export { P as A2AErrorCode, y as A2AJsonRpcId, F as A2ARequestContext, t as A2A_ROUTES, o as AGENT_ROUTES, q as ALL_ROUTES, N as AgentCard, K as AgentCardCapabilities, I as AgentCardProviderInfo, G as AgentCardSkill, an as AppSetupConfig, ar as DEFAULT_CORS_OPTIONS, E as ErrorResponse, J as JsonRpcError, C as JsonRpcHandlerResult, D as JsonRpcRequest, z as JsonRpcResponse, B as JsonRpcStream, L as LOG_ROUTES, ab as LogFilterOptions, ac as LogHandlerResponse, s as MCP_ROUTES, f as MemoryConversationMessagesResult, g as MemoryConversationStepsResult, e as MemoryConversationSummary, l as MemoryGetMessagesQuery, m as MemoryGetStepsQuery, k as MemoryListConversationsQuery, j as MemoryListUsersQuery, d as MemoryUserAgentSummary, M as MemoryUserSummary, h as MemoryWorkingMemoryResult, p as OBSERVABILITY_MEMORY_ROUTES, O as OBSERVABILITY_ROUTES, am as OpenApiInfo, R as ResponseDefinition, n as RouteDefinition, b as StreamResponse, S as SuccessResponse, U as UPDATE_ROUTES, V as VoltA2AError, W as WORKFLOW_ROUTES, x as executeA2ARequest, r as getAllRoutesArray, ag as getConversationMessagesHandler, ah as getConversationStepsHandler, aq as getOpenApiDoc, ao as getOrCreateLogger, al as getResponseStatus, u as getRoutesByTag, ai as getWorkingMemoryHandler, a8 as handleCancelWorkflow, _ as handleChatStream, a5 as handleExecuteWorkflow, $ as handleGenerateObject, Y as handleGenerateText, a1 as handleGetAgent, a2 as handleGetAgentHistory, X as handleGetAgents, ad as handleGetLogs, a4 as handleGetWorkflow, aa as handleGetWorkflowState, a3 as handleGetWorkflows, a9 as handleResumeWorkflow, a0 as handleStreamObject, Z as handleStreamText, a6 as handleStreamWorkflow, a7 as handleSuspendWorkflow, i as isErrorResponse, T as isJsonRpcRequest, c as isSuccessResponse, af as listMemoryConversationsHandler, ae as listMemoryUsersHandler, ak as mapHandlerResponse, aj as mapLogResponse, Q as normalizeError, v as parseJsonRpcRequest, w as resolveAgentCard, ap as shouldEnableSwaggerUI } from './edge-CtOnFGMl.mjs';
 import { LogFilter, Logger } from '@voltagent/internal';
 import { z } from 'zod';
-import { MCPServerRegistry, A2AServerRegistry, ServerProviderDeps, IServerProvider } from '@voltagent/core';
+import { MCPServerRegistry, A2AServerRegistry, ServerProviderDeps, RegisteredTrigger, IServerProvider } from '@voltagent/core';
 import { Tool, CallToolResult, Prompt, GetPromptRequest, GetPromptResult, Resource, ResourceContents, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
 export { CallToolResult, GetPromptRequest, GetPromptResult, Prompt, Resource, ResourceContents, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
 import { MCPServerLike as MCPServerLike$1, MCPServerDeps, MCPServerMetadata as MCPServerMetadata$1 } from '@voltagent/internal/mcp';
@@ -31,6 +31,7 @@ interface ServerEndpointSummary {
     method: string;
     description?: string;
     group?: string;
+    name?: string;
 }
 interface ServerStartupOptions {
     enableSwaggerUI?: boolean;
@@ -1702,6 +1703,19 @@ declare function getLogsBySpanIdHandler(spanId: string, deps: ServerProviderDeps
  */
 declare function queryLogsHandler(query: any, deps: ServerProviderDeps): Promise<any>;
 
+interface TriggerHttpRequestContext {
+    body: unknown;
+    headers: Record<string, string>;
+    query?: Record<string, string | string[]>;
+    raw?: unknown;
+}
+interface TriggerHandlerHttpResponse {
+    status: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+declare function executeTriggerHandler(registration: RegisteredTrigger, request: TriggerHttpRequestContext, deps: ServerProviderDeps, logger: Logger): Promise<TriggerHandlerHttpResponse>;
+
 declare function setupObservabilityHandler(body: {
     publicKey?: string;
     secretKey?: string;
@@ -1772,14 +1786,26 @@ interface AuthProvider<TRequest = any> {
 declare const DEFAULT_PUBLIC_ROUTES: string[];
 /**
  * Routes that require authentication by default
- * These are the actual execution endpoints
+ * These endpoints execute operations, modify state, or access sensitive data
  */
 declare const PROTECTED_ROUTES: string[];
 /**
  * Check if a path matches a route pattern
+ *
+ * Supports multiple pattern types:
+ * - Exact match: "/agents" matches "/agents"
+ * - Parameters: "/agents/:id" matches "/agents/123"
+ * - Trailing wildcard: "/observability/*" matches "/observability/traces" and "/observability/memory/users"
+ * - Double-star: "/api/**" matches "/api" and all children
+ *
  * @param path The actual request path (e.g., "/agents/123")
- * @param pattern The route pattern (e.g., "/agents/:id")
+ * @param pattern The route pattern (e.g., "/agents/:id" or "/observability/*")
  * @returns True if the path matches the pattern
+ *
+ * @example
+ * pathMatches("/observability/traces", "/observability/*") → true
+ * pathMatches("/observability/memory/users", "/observability/*") → true
+ * pathMatches("/api/traces", "/observability/*") → false
  */
 declare function pathMatches(path: string, pattern: string): boolean;
 /**
@@ -1792,6 +1818,62 @@ declare function pathMatches(path: string, pattern: string): boolean;
  */
 declare function requiresAuth(method: string, path: string, publicRoutes?: string[], defaultPrivate?: boolean): boolean;
 
+/**
+ * Authentication utility functions
+ */
+/**
+ * Check if request is from development environment
+ *
+ * Requires BOTH client header AND non-production environment for security.
+ * This prevents production bypass while allowing local development.
+ *
+ * @param req - The incoming HTTP request
+ * @returns True if both dev header and non-production environment are present
+ *
+ * @example
+ * // Local development with header (typical case)
+ * NODE_ENV=undefined + x-voltagent-dev=true → true (auth bypassed)
+ *
+ * // Development with header (playground)
+ * NODE_ENV=development + x-voltagent-dev=true → true (auth bypassed)
+ *
+ * // Development without header (testing auth)
+ * NODE_ENV=undefined + no header → false (auth required)
+ *
+ * // Production with header (attacker attempt)
+ * NODE_ENV=production + x-voltagent-dev=true → false (auth required)
+ *
+ * @security
+ * - Client header alone: Cannot bypass in production
+ * - Non-production env alone: Developer can still test auth
+ * - Both required: Selective bypass for DX
+ * - Production is strictly protected (NODE_ENV=production)
+ */
+declare function isDevRequest(req: Request): boolean;
+/**
+ * Check if request has valid Console access
+ * Works in both development and production environments
+ *
+ * @param req - The incoming HTTP request
+ * @returns True if request has valid console access
+ *
+ * @example
+ * // Development with dev header
+ * NODE_ENV=development + x-voltagent-dev=true → true
+ *
+ * // Production with console key
+ * NODE_ENV=production + x-console-access-key=valid-key → true
+ *
+ * // Production without key
+ * NODE_ENV=production + no key → false
+ *
+ * @security
+ * - In development: Uses existing dev bypass
+ * - In production: Requires matching console access key
+ * - Key must match VOLTAGENT_CONSOLE_ACCESS_KEY env var
+ */
+declare function hasConsoleAccess(req: Request): boolean;
+
 /**
  * JWT authentication options
  */
@@ -1835,49 +1917,6 @@ declare function jwtAuth(options: JWTAuthOptions): AuthProvider<Request>;
  */
 declare function createJWT(payload: object, secret: string, options?: jwt.SignOptions): string;
 
-/**
- * Auth utility functions that can be reused across different server implementations
- */
-/**
- * Extract Bearer token from Authorization header
- * @param authHeader The Authorization header value
- * @returns The token if found, undefined otherwise
- */
-declare function extractBearerToken(authHeader: string | undefined | null): string | undefined;
-/**
- * Extract token from various sources
- * @param headers Headers object or map
- * @param cookies Optional cookies object
- * @param query Optional query parameters
- * @returns The token if found, undefined otherwise
- */
-declare function extractToken(headers: Record<string, string | string[] | undefined> | Headers, cookies?: Record<string, string>, query?: Record<string, string | string[] | undefined>): string | undefined;
-/**
- * Create user context object for injection into requests
- * @param user The authenticated user object
- * @param existingContext Optional existing context to merge with
- * @returns The user context object
- */
-declare function createUserContext(user: any, existingContext?: Record<string, any>): Record<string, any>;
-/**
- * Inject user context into request body
- * @param body The original request body
- * @param user The authenticated user
- * @returns The modified body with user context
- */
-declare function injectUserIntoBody(body: any, user: any): any;
-/**
- * Create a standardized auth error response
- * @param message The error message
- * @param statusCode The HTTP status code
- * @returns The error response object
- */
-declare function createAuthErrorResponse(message: string, statusCode?: number): {
-    success: false;
-    error: string;
-    statusCode: number;
-};
-
 /**
  * Process agent options from request body
  */
@@ -2053,7 +2092,7 @@ declare function createSSEResponse(stream: ReadableStream<Uint8Array>, status?:
 /**
  * Main WebSocket connection handler - framework agnostic
  */
-declare function handleWebSocketConnection(ws: IWebSocket, req: IncomingMessage, deps: ServerProviderDeps, logger: Logger): Promise<void>;
+declare function handleWebSocketConnection(ws: IWebSocket, req: IncomingMessage, deps: ServerProviderDeps, logger: Logger, user?: any): Promise<void>;
 /**
  * Clean up all WebSocket connections
  */
@@ -2159,16 +2198,19 @@ declare function createWebSocketRouter(): WebSocketRouter;
  * Create and configure a WebSocket server
  * @param deps Server provider dependencies
  * @param logger Logger instance
+ * @param auth Optional authentication provider
  * @returns Configured WebSocket server
  */
-declare function createWebSocketServer(deps: ServerProviderDeps, logger: Logger): WebSocketServer;
+declare function createWebSocketServer(deps: ServerProviderDeps, logger: Logger, _auth?: AuthProvider<any>): WebSocketServer;
 /**
  * Setup WebSocket upgrade handler for HTTP server
  * @param server HTTP server instance
  * @param wss WebSocket server instance
  * @param pathPrefix Path prefix for WebSocket connections (default: "/ws")
+ * @param auth Optional authentication provider
+ * @param logger Logger instance
  */
-declare function setupWebSocketUpgrade(server: any, wss: WebSocketServer, pathPrefix?: string): void;
+declare function setupWebSocketUpgrade(server: any, wss: WebSocketServer, pathPrefix?: string, auth?: AuthProvider<any>, logger?: Logger): void;
 
 /**
  * WebSocket handler for Observability events
@@ -2182,7 +2224,7 @@ declare function setupObservabilityListeners(): void;
 /**
  * Handle new WebSocket connection for observability
  */
-declare function handleObservabilityConnection(ws: IWebSocket, request: any, _deps: ServerProviderDeps): void;
+declare function handleObservabilityConnection(ws: IWebSocket, request: any, _deps: ServerProviderDeps, user?: any): void;
 /**
  * Close all observability WebSocket connections
  */
@@ -2267,4 +2309,4 @@ declare abstract class BaseServerProvider implements IServerProvider {
     private collectFeatureEndpoints;
 }
 
-export { A2AServerLikeWithHandlers, type A2AServerLookupResult, AgentListSchema, AgentParamsSchema, AgentResponseSchema, ApiResponse, type AuthProvider, type BaseCustomEndpointDefinition, type BaseServerConfig, BaseServerProvider, BasicJsonSchema, type CapabilityRecord, CustomEndpointError, type CustomEndpointHandler, DEFAULT_A2A_ROUTE_PREFIX, DEFAULT_A2A_WELL_KNOWN_PREFIX, DEFAULT_MCP_HTTP_SEGMENT, DEFAULT_MCP_MESSAGES_SEGMENT, DEFAULT_MCP_ROUTE_PREFIX, DEFAULT_MCP_SSE_SEGMENT, DEFAULT_PUBLIC_ROUTES, ErrorSchema, type FilterContext, GenerateOptionsSchema, HttpMethod, type IWebSocket, type JWTAuthOptions, type LogStreamClient, LogStreamManager, type MCPAgentMetadata, type MCPListedTool, type MCPServerCapabilitiesConfig, type MCPServerLike, type MCPServerMetadata, type MCPServerPackageInfo, type MCPServerRemoteInfo, type MCPToolMetadata, type MCPToolOrigin, type MCPWorkflowSummary, MCP_SESSION_QUERY_PARAM, type McpInvokeToolRequest, type McpInvokeToolResponse, type McpPromptDetailResponse, type McpPromptListResponse, type McpResourceDetailResponse, type McpResourceListResponse, type McpResourceTemplateListResponse, type McpRouteOptions, type McpRoutePaths, type McpServerDetailResponse, type McpServerListResponse, type McpServerLookupResult, McpSessionStore, type McpSetLogLevelRequest, type McpSetLogLevelResponse, type McpToolListResponse, ObjectRequestSchema, ObjectResponseSchema, PROTECTED_ROUTES, ParamsSchema, type PortConfig, type ProcessedAgentOptions, type ProtocolConfig, type ProtocolRecord, type ServerEndpointSummary, type ServerProviderConfig, type ServerStartupOptions, StreamObjectEventSchema, StreamTextEventSchema, SubAgentResponseSchema, TextRequestSchema, TextResponseSchema, type WebSocketAdapter, type WebSocketConnectionHandler, type WebSocketConnectionInfo, type WebSocketEventHandlers, type WebSocketMessage, WebSocketRouter, WorkflowCancelRequestSchema, WorkflowCancelResponseSchema, WorkflowExecutionParamsSchema, WorkflowExecutionRequestSchema, WorkflowExecutionResponseSchema, WorkflowListSchema, WorkflowParamsSchema, WorkflowResponseSchema, WorkflowResumeRequestSchema, WorkflowResumeResponseSchema, WorkflowStreamEventSchema, WorkflowSuspendRequestSchema, WorkflowSuspendResponseSchema, buildA2AEndpointPath, buildAgentCardPath, buildMcpRoutePaths, cleanupWebSockets, closeAllObservabilityConnections, colors, createAuthErrorResponse, createJWT, createSSEHeaders, createSSEResponse, createSSEStream, createUserContext, createWebSocketRouter, createWebSocketServer, extractBearerToken, extractToken, formatSSE, getLandingPageHTML, getLogsBySpanIdHandler, getLogsByTraceIdHandler, getObservabilityStatusHandler, getPortsToTry, getSpanByIdHandler, getTraceByIdHandler, getTracesHandler, handleCheckUpdates, handleGetMcpPrompt, handleGetMcpResource, handleGetMcpServer, handleInstallUpdates, handleInvokeMcpServerTool, handleListMcpPrompts, handleListMcpResourceTemplates, handleListMcpResources, handleListMcpServerTools, handleListMcpServers, handleObservabilityConnection, handleSetMcpLogLevel, handleWebSocketConnection, injectUserIntoBody, jwtAuth, listA2AServers, listMcpServers, lookupA2AServer, lookupMcpServer, pathMatches, portManager, preferredPorts, printServerStartup, processAgentOptions, processWorkflowOptions, queryLogsHandler, requiresAuth, setupObservabilityHandler, setupObservabilityListeners, setupWebSocketUpgrade, transformToSSE, validateBaseCustomEndpoint, validateEndpointMethod, validateEndpointPath };
+export { A2AServerLikeWithHandlers, type A2AServerLookupResult, AgentListSchema, AgentParamsSchema, AgentResponseSchema, ApiResponse, type AuthProvider, type BaseCustomEndpointDefinition, type BaseServerConfig, BaseServerProvider, BasicJsonSchema, type CapabilityRecord, CustomEndpointError, type CustomEndpointHandler, DEFAULT_A2A_ROUTE_PREFIX, DEFAULT_A2A_WELL_KNOWN_PREFIX, DEFAULT_MCP_HTTP_SEGMENT, DEFAULT_MCP_MESSAGES_SEGMENT, DEFAULT_MCP_ROUTE_PREFIX, DEFAULT_MCP_SSE_SEGMENT, DEFAULT_PUBLIC_ROUTES, ErrorSchema, type FilterContext, GenerateOptionsSchema, HttpMethod, type IWebSocket, type JWTAuthOptions, type LogStreamClient, LogStreamManager, type MCPAgentMetadata, type MCPListedTool, type MCPServerCapabilitiesConfig, type MCPServerLike, type MCPServerMetadata, type MCPServerPackageInfo, type MCPServerRemoteInfo, type MCPToolMetadata, type MCPToolOrigin, type MCPWorkflowSummary, MCP_SESSION_QUERY_PARAM, type McpInvokeToolRequest, type McpInvokeToolResponse, type McpPromptDetailResponse, type McpPromptListResponse, type McpResourceDetailResponse, type McpResourceListResponse, type McpResourceTemplateListResponse, type McpRouteOptions, type McpRoutePaths, type McpServerDetailResponse, type McpServerListResponse, type McpServerLookupResult, McpSessionStore, type McpSetLogLevelRequest, type McpSetLogLevelResponse, type McpToolListResponse, ObjectRequestSchema, ObjectResponseSchema, PROTECTED_ROUTES, ParamsSchema, type PortConfig, type ProcessedAgentOptions, type ProtocolConfig, type ProtocolRecord, type ServerEndpointSummary, type ServerProviderConfig, type ServerStartupOptions, StreamObjectEventSchema, StreamTextEventSchema, SubAgentResponseSchema, TextRequestSchema, TextResponseSchema, type TriggerHandlerHttpResponse, type TriggerHttpRequestContext, type WebSocketAdapter, type WebSocketConnectionHandler, type WebSocketConnectionInfo, type WebSocketEventHandlers, type WebSocketMessage, WebSocketRouter, WorkflowCancelRequestSchema, WorkflowCancelResponseSchema, WorkflowExecutionParamsSchema, WorkflowExecutionRequestSchema, WorkflowExecutionResponseSchema, WorkflowListSchema, WorkflowParamsSchema, WorkflowResponseSchema, WorkflowResumeRequestSchema, WorkflowResumeResponseSchema, WorkflowStreamEventSchema, WorkflowSuspendRequestSchema, WorkflowSuspendResponseSchema, buildA2AEndpointPath, buildAgentCardPath, buildMcpRoutePaths, cleanupWebSockets, closeAllObservabilityConnections, colors, createJWT, createSSEHeaders, createSSEResponse, createSSEStream, createWebSocketRouter, createWebSocketServer, executeTriggerHandler, formatSSE, getLandingPageHTML, getLogsBySpanIdHandler, getLogsByTraceIdHandler, getObservabilityStatusHandler, getPortsToTry, getSpanByIdHandler, getTraceByIdHandler, getTracesHandler, handleCheckUpdates, handleGetMcpPrompt, handleGetMcpResource, handleGetMcpServer, handleInstallUpdates, handleInvokeMcpServerTool, handleListMcpPrompts, handleListMcpResourceTemplates, handleListMcpResources, handleListMcpServerTools, handleListMcpServers, handleObservabilityConnection, handleSetMcpLogLevel, handleWebSocketConnection, hasConsoleAccess, isDevRequest, jwtAuth, listA2AServers, listMcpServers, lookupA2AServer, lookupMcpServer, pathMatches, portManager, preferredPorts, printServerStartup, processAgentOptions, processWorkflowOptions, queryLogsHandler, requiresAuth, setupObservabilityHandler, setupObservabilityListeners, setupWebSocketUpgrade, transformToSSE, validateBaseCustomEndpoint, validateEndpointMethod, validateEndpointPath };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { H as HttpMethod, A as ApiResponse, a as A2AServerLikeWithHandlers } fro
 export { P as A2AErrorCode, y as A2AJsonRpcId, F as A2ARequestContext, t as A2A_ROUTES, o as AGENT_ROUTES, q as ALL_ROUTES, N as AgentCard, K as AgentCardCapabilities, I as AgentCardProviderInfo, G as AgentCardSkill, an as AppSetupConfig, ar as DEFAULT_CORS_OPTIONS, E as ErrorResponse, J as JsonRpcError, C as JsonRpcHandlerResult, D as JsonRpcRequest, z as JsonRpcResponse, B as JsonRpcStream, L as LOG_ROUTES, ab as LogFilterOptions, ac as LogHandlerResponse, s as MCP_ROUTES, f as MemoryConversationMessagesResult, g as MemoryConversationStepsResult, e as MemoryConversationSummary, l as MemoryGetMessagesQuery, m as MemoryGetStepsQuery, k as MemoryListConversationsQuery, j as MemoryListUsersQuery, d as MemoryUserAgentSummary, M as MemoryUserSummary, h as MemoryWorkingMemoryResult, p as OBSERVABILITY_MEMORY_ROUTES, O as OBSERVABILITY_ROUTES, am as OpenApiInfo, R as ResponseDefinition, n as RouteDefinition, b as StreamResponse, S as SuccessResponse, U as UPDATE_ROUTES, V as VoltA2AError, W as WORKFLOW_ROUTES, x as executeA2ARequest, r as getAllRoutesArray, ag as getConversationMessagesHandler, ah as getConversationStepsHandler, aq as getOpenApiDoc, ao as getOrCreateLogger, al as getResponseStatus, u as getRoutesByTag, ai as getWorkingMemoryHandler, a8 as handleCancelWorkflow, _ as handleChatStream, a5 as handleExecuteWorkflow, $ as handleGenerateObject, Y as handleGenerateText, a1 as handleGetAgent, a2 as handleGetAgentHistory, X as handleGetAgents, ad as handleGetLogs, a4 as handleGetWorkflow, aa as handleGetWorkflowState, a3 as handleGetWorkflows, a9 as handleResumeWorkflow, a0 as handleStreamObject, Z as handleStreamText, a6 as handleStreamWorkflow, a7 as handleSuspendWorkflow, i as isErrorResponse, T as isJsonRpcRequest, c as isSuccessResponse, af as listMemoryConversationsHandler, ae as listMemoryUsersHandler, ak as mapHandlerResponse, aj as mapLogResponse, Q as normalizeError, v as parseJsonRpcRequest, w as resolveAgentCard, ap as shouldEnableSwaggerUI } from './edge-CtOnFGMl.js';
 import { LogFilter, Logger } from '@voltagent/internal';
 import { z } from 'zod';
-import { MCPServerRegistry, A2AServerRegistry, ServerProviderDeps, IServerProvider } from '@voltagent/core';
+import { MCPServerRegistry, A2AServerRegistry, ServerProviderDeps, RegisteredTrigger, IServerProvider } from '@voltagent/core';
 import { Tool, CallToolResult, Prompt, GetPromptRequest, GetPromptResult, Resource, ResourceContents, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
 export { CallToolResult, GetPromptRequest, GetPromptResult, Prompt, Resource, ResourceContents, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
 import { MCPServerLike as MCPServerLike$1, MCPServerDeps, MCPServerMetadata as MCPServerMetadata$1 } from '@voltagent/internal/mcp';
@@ -31,6 +31,7 @@ interface ServerEndpointSummary {
     method: string;
     description?: string;
     group?: string;
+    name?: string;
 }
 interface ServerStartupOptions {
     enableSwaggerUI?: boolean;
@@ -1702,6 +1703,19 @@ declare function getLogsBySpanIdHandler(spanId: string, deps: ServerProviderDeps
  */
 declare function queryLogsHandler(query: any, deps: ServerProviderDeps): Promise<any>;
 
+interface TriggerHttpRequestContext {
+    body: unknown;
+    headers: Record<string, string>;
+    query?: Record<string, string | string[]>;
+    raw?: unknown;
+}
+interface TriggerHandlerHttpResponse {
+    status: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+declare function executeTriggerHandler(registration: RegisteredTrigger, request: TriggerHttpRequestContext, deps: ServerProviderDeps, logger: Logger): Promise<TriggerHandlerHttpResponse>;
+
 declare function setupObservabilityHandler(body: {
     publicKey?: string;
     secretKey?: string;
@@ -1772,14 +1786,26 @@ interface AuthProvider<TRequest = any> {
 declare const DEFAULT_PUBLIC_ROUTES: string[];
 /**
  * Routes that require authentication by default
- * These are the actual execution endpoints
+ * These endpoints execute operations, modify state, or access sensitive data
  */
 declare const PROTECTED_ROUTES: string[];
 /**
  * Check if a path matches a route pattern
+ *
+ * Supports multiple pattern types:
+ * - Exact match: "/agents" matches "/agents"
+ * - Parameters: "/agents/:id" matches "/agents/123"
+ * - Trailing wildcard: "/observability/*" matches "/observability/traces" and "/observability/memory/users"
+ * - Double-star: "/api/**" matches "/api" and all children
+ *
  * @param path The actual request path (e.g., "/agents/123")
- * @param pattern The route pattern (e.g., "/agents/:id")
+ * @param pattern The route pattern (e.g., "/agents/:id" or "/observability/*")
  * @returns True if the path matches the pattern
+ *
+ * @example
+ * pathMatches("/observability/traces", "/observability/*") → true
+ * pathMatches("/observability/memory/users", "/observability/*") → true
+ * pathMatches("/api/traces", "/observability/*") → false
  */
 declare function pathMatches(path: string, pattern: string): boolean;
 /**
@@ -1792,6 +1818,62 @@ declare function pathMatches(path: string, pattern: string): boolean;
  */
 declare function requiresAuth(method: string, path: string, publicRoutes?: string[], defaultPrivate?: boolean): boolean;
 
+/**
+ * Authentication utility functions
+ */
+/**
+ * Check if request is from development environment
+ *
+ * Requires BOTH client header AND non-production environment for security.
+ * This prevents production bypass while allowing local development.
+ *
+ * @param req - The incoming HTTP request
+ * @returns True if both dev header and non-production environment are present
+ *
+ * @example
+ * // Local development with header (typical case)
+ * NODE_ENV=undefined + x-voltagent-dev=true → true (auth bypassed)
+ *
+ * // Development with header (playground)
+ * NODE_ENV=development + x-voltagent-dev=true → true (auth bypassed)
+ *
+ * // Development without header (testing auth)
+ * NODE_ENV=undefined + no header → false (auth required)
+ *
+ * // Production with header (attacker attempt)
+ * NODE_ENV=production + x-voltagent-dev=true → false (auth required)
+ *
+ * @security
+ * - Client header alone: Cannot bypass in production
+ * - Non-production env alone: Developer can still test auth
+ * - Both required: Selective bypass for DX
+ * - Production is strictly protected (NODE_ENV=production)
+ */
+declare function isDevRequest(req: Request): boolean;
+/**
+ * Check if request has valid Console access
+ * Works in both development and production environments
+ *
+ * @param req - The incoming HTTP request
+ * @returns True if request has valid console access
+ *
+ * @example
+ * // Development with dev header
+ * NODE_ENV=development + x-voltagent-dev=true → true
+ *
+ * // Production with console key
+ * NODE_ENV=production + x-console-access-key=valid-key → true
+ *
+ * // Production without key
+ * NODE_ENV=production + no key → false
+ *
+ * @security
+ * - In development: Uses existing dev bypass
+ * - In production: Requires matching console access key
+ * - Key must match VOLTAGENT_CONSOLE_ACCESS_KEY env var
+ */
+declare function hasConsoleAccess(req: Request): boolean;
+
 /**
  * JWT authentication options
  */
@@ -1835,49 +1917,6 @@ declare function jwtAuth(options: JWTAuthOptions): AuthProvider<Request>;
  */
 declare function createJWT(payload: object, secret: string, options?: jwt.SignOptions): string;
 
-/**
- * Auth utility functions that can be reused across different server implementations
- */
-/**
- * Extract Bearer token from Authorization header
- * @param authHeader The Authorization header value
- * @returns The token if found, undefined otherwise
- */
-declare function extractBearerToken(authHeader: string | undefined | null): string | undefined;
-/**
- * Extract token from various sources
- * @param headers Headers object or map
- * @param cookies Optional cookies object
- * @param query Optional query parameters
- * @returns The token if found, undefined otherwise
- */
-declare function extractToken(headers: Record<string, string | string[] | undefined> | Headers, cookies?: Record<string, string>, query?: Record<string, string | string[] | undefined>): string | undefined;
-/**
- * Create user context object for injection into requests
- * @param user The authenticated user object
- * @param existingContext Optional existing context to merge with
- * @returns The user context object
- */
-declare function createUserContext(user: any, existingContext?: Record<string, any>): Record<string, any>;
-/**
- * Inject user context into request body
- * @param body The original request body
- * @param user The authenticated user
- * @returns The modified body with user context
- */
-declare function injectUserIntoBody(body: any, user: any): any;
-/**
- * Create a standardized auth error response
- * @param message The error message
- * @param statusCode The HTTP status code
- * @returns The error response object
- */
-declare function createAuthErrorResponse(message: string, statusCode?: number): {
-    success: false;
-    error: string;
-    statusCode: number;
-};
-
 /**
  * Process agent options from request body
  */
@@ -2053,7 +2092,7 @@ declare function createSSEResponse(stream: ReadableStream<Uint8Array>, status?:
 /**
  * Main WebSocket connection handler - framework agnostic
  */
-declare function handleWebSocketConnection(ws: IWebSocket, req: IncomingMessage, deps: ServerProviderDeps, logger: Logger): Promise<void>;
+declare function handleWebSocketConnection(ws: IWebSocket, req: IncomingMessage, deps: ServerProviderDeps, logger: Logger, user?: any): Promise<void>;
 /**
  * Clean up all WebSocket connections
  */
@@ -2159,16 +2198,19 @@ declare function createWebSocketRouter(): WebSocketRouter;
  * Create and configure a WebSocket server
  * @param deps Server provider dependencies
  * @param logger Logger instance
+ * @param auth Optional authentication provider
  * @returns Configured WebSocket server
  */
-declare function createWebSocketServer(deps: ServerProviderDeps, logger: Logger): WebSocketServer;
+declare function createWebSocketServer(deps: ServerProviderDeps, logger: Logger, _auth?: AuthProvider<any>): WebSocketServer;
 /**
  * Setup WebSocket upgrade handler for HTTP server
  * @param server HTTP server instance
  * @param wss WebSocket server instance
  * @param pathPrefix Path prefix for WebSocket connections (default: "/ws")
+ * @param auth Optional authentication provider
+ * @param logger Logger instance
  */
-declare function setupWebSocketUpgrade(server: any, wss: WebSocketServer, pathPrefix?: string): void;
+declare function setupWebSocketUpgrade(server: any, wss: WebSocketServer, pathPrefix?: string, auth?: AuthProvider<any>, logger?: Logger): void;
 
 /**
  * WebSocket handler for Observability events
@@ -2182,7 +2224,7 @@ declare function setupObservabilityListeners(): void;
 /**
  * Handle new WebSocket connection for observability
  */
-declare function handleObservabilityConnection(ws: IWebSocket, request: any, _deps: ServerProviderDeps): void;
+declare function handleObservabilityConnection(ws: IWebSocket, request: any, _deps: ServerProviderDeps, user?: any): void;
 /**
  * Close all observability WebSocket connections
  */
@@ -2267,4 +2309,4 @@ declare abstract class BaseServerProvider implements IServerProvider {
     private collectFeatureEndpoints;
 }
 
-export { A2AServerLikeWithHandlers, type A2AServerLookupResult, AgentListSchema, AgentParamsSchema, AgentResponseSchema, ApiResponse, type AuthProvider, type BaseCustomEndpointDefinition, type BaseServerConfig, BaseServerProvider, BasicJsonSchema, type CapabilityRecord, CustomEndpointError, type CustomEndpointHandler, DEFAULT_A2A_ROUTE_PREFIX, DEFAULT_A2A_WELL_KNOWN_PREFIX, DEFAULT_MCP_HTTP_SEGMENT, DEFAULT_MCP_MESSAGES_SEGMENT, DEFAULT_MCP_ROUTE_PREFIX, DEFAULT_MCP_SSE_SEGMENT, DEFAULT_PUBLIC_ROUTES, ErrorSchema, type FilterContext, GenerateOptionsSchema, HttpMethod, type IWebSocket, type JWTAuthOptions, type LogStreamClient, LogStreamManager, type MCPAgentMetadata, type MCPListedTool, type MCPServerCapabilitiesConfig, type MCPServerLike, type MCPServerMetadata, type MCPServerPackageInfo, type MCPServerRemoteInfo, type MCPToolMetadata, type MCPToolOrigin, type MCPWorkflowSummary, MCP_SESSION_QUERY_PARAM, type McpInvokeToolRequest, type McpInvokeToolResponse, type McpPromptDetailResponse, type McpPromptListResponse, type McpResourceDetailResponse, type McpResourceListResponse, type McpResourceTemplateListResponse, type McpRouteOptions, type McpRoutePaths, type McpServerDetailResponse, type McpServerListResponse, type McpServerLookupResult, McpSessionStore, type McpSetLogLevelRequest, type McpSetLogLevelResponse, type McpToolListResponse, ObjectRequestSchema, ObjectResponseSchema, PROTECTED_ROUTES, ParamsSchema, type PortConfig, type ProcessedAgentOptions, type ProtocolConfig, type ProtocolRecord, type ServerEndpointSummary, type ServerProviderConfig, type ServerStartupOptions, StreamObjectEventSchema, StreamTextEventSchema, SubAgentResponseSchema, TextRequestSchema, TextResponseSchema, type WebSocketAdapter, type WebSocketConnectionHandler, type WebSocketConnectionInfo, type WebSocketEventHandlers, type WebSocketMessage, WebSocketRouter, WorkflowCancelRequestSchema, WorkflowCancelResponseSchema, WorkflowExecutionParamsSchema, WorkflowExecutionRequestSchema, WorkflowExecutionResponseSchema, WorkflowListSchema, WorkflowParamsSchema, WorkflowResponseSchema, WorkflowResumeRequestSchema, WorkflowResumeResponseSchema, WorkflowStreamEventSchema, WorkflowSuspendRequestSchema, WorkflowSuspendResponseSchema, buildA2AEndpointPath, buildAgentCardPath, buildMcpRoutePaths, cleanupWebSockets, closeAllObservabilityConnections, colors, createAuthErrorResponse, createJWT, createSSEHeaders, createSSEResponse, createSSEStream, createUserContext, createWebSocketRouter, createWebSocketServer, extractBearerToken, extractToken, formatSSE, getLandingPageHTML, getLogsBySpanIdHandler, getLogsByTraceIdHandler, getObservabilityStatusHandler, getPortsToTry, getSpanByIdHandler, getTraceByIdHandler, getTracesHandler, handleCheckUpdates, handleGetMcpPrompt, handleGetMcpResource, handleGetMcpServer, handleInstallUpdates, handleInvokeMcpServerTool, handleListMcpPrompts, handleListMcpResourceTemplates, handleListMcpResources, handleListMcpServerTools, handleListMcpServers, handleObservabilityConnection, handleSetMcpLogLevel, handleWebSocketConnection, injectUserIntoBody, jwtAuth, listA2AServers, listMcpServers, lookupA2AServer, lookupMcpServer, pathMatches, portManager, preferredPorts, printServerStartup, processAgentOptions, processWorkflowOptions, queryLogsHandler, requiresAuth, setupObservabilityHandler, setupObservabilityListeners, setupWebSocketUpgrade, transformToSSE, validateBaseCustomEndpoint, validateEndpointMethod, validateEndpointPath };
+export { A2AServerLikeWithHandlers, type A2AServerLookupResult, AgentListSchema, AgentParamsSchema, AgentResponseSchema, ApiResponse, type AuthProvider, type BaseCustomEndpointDefinition, type BaseServerConfig, BaseServerProvider, BasicJsonSchema, type CapabilityRecord, CustomEndpointError, type CustomEndpointHandler, DEFAULT_A2A_ROUTE_PREFIX, DEFAULT_A2A_WELL_KNOWN_PREFIX, DEFAULT_MCP_HTTP_SEGMENT, DEFAULT_MCP_MESSAGES_SEGMENT, DEFAULT_MCP_ROUTE_PREFIX, DEFAULT_MCP_SSE_SEGMENT, DEFAULT_PUBLIC_ROUTES, ErrorSchema, type FilterContext, GenerateOptionsSchema, HttpMethod, type IWebSocket, type JWTAuthOptions, type LogStreamClient, LogStreamManager, type MCPAgentMetadata, type MCPListedTool, type MCPServerCapabilitiesConfig, type MCPServerLike, type MCPServerMetadata, type MCPServerPackageInfo, type MCPServerRemoteInfo, type MCPToolMetadata, type MCPToolOrigin, type MCPWorkflowSummary, MCP_SESSION_QUERY_PARAM, type McpInvokeToolRequest, type McpInvokeToolResponse, type McpPromptDetailResponse, type McpPromptListResponse, type McpResourceDetailResponse, type McpResourceListResponse, type McpResourceTemplateListResponse, type McpRouteOptions, type McpRoutePaths, type McpServerDetailResponse, type McpServerListResponse, type McpServerLookupResult, McpSessionStore, type McpSetLogLevelRequest, type McpSetLogLevelResponse, type McpToolListResponse, ObjectRequestSchema, ObjectResponseSchema, PROTECTED_ROUTES, ParamsSchema, type PortConfig, type ProcessedAgentOptions, type ProtocolConfig, type ProtocolRecord, type ServerEndpointSummary, type ServerProviderConfig, type ServerStartupOptions, StreamObjectEventSchema, StreamTextEventSchema, SubAgentResponseSchema, TextRequestSchema, TextResponseSchema, type TriggerHandlerHttpResponse, type TriggerHttpRequestContext, type WebSocketAdapter, type WebSocketConnectionHandler, type WebSocketConnectionInfo, type WebSocketEventHandlers, type WebSocketMessage, WebSocketRouter, WorkflowCancelRequestSchema, WorkflowCancelResponseSchema, WorkflowExecutionParamsSchema, WorkflowExecutionRequestSchema, WorkflowExecutionResponseSchema, WorkflowListSchema, WorkflowParamsSchema, WorkflowResponseSchema, WorkflowResumeRequestSchema, WorkflowResumeResponseSchema, WorkflowStreamEventSchema, WorkflowSuspendRequestSchema, WorkflowSuspendResponseSchema, buildA2AEndpointPath, buildAgentCardPath, buildMcpRoutePaths, cleanupWebSockets, closeAllObservabilityConnections, colors, createJWT, createSSEHeaders, createSSEResponse, createSSEStream, createWebSocketRouter, createWebSocketServer, executeTriggerHandler, formatSSE, getLandingPageHTML, getLogsBySpanIdHandler, getLogsByTraceIdHandler, getObservabilityStatusHandler, getPortsToTry, getSpanByIdHandler, getTraceByIdHandler, getTracesHandler, handleCheckUpdates, handleGetMcpPrompt, handleGetMcpResource, handleGetMcpServer, handleInstallUpdates, handleInvokeMcpServerTool, handleListMcpPrompts, handleListMcpResourceTemplates, handleListMcpResources, handleListMcpServerTools, handleListMcpServers, handleObservabilityConnection, handleSetMcpLogLevel, handleWebSocketConnection, hasConsoleAccess, isDevRequest, jwtAuth, listA2AServers, listMcpServers, lookupA2AServer, lookupMcpServer, pathMatches, portManager, preferredPorts, printServerStartup, processAgentOptions, processWorkflowOptions, queryLogsHandler, requiresAuth, setupObservabilityHandler, setupObservabilityListeners, setupWebSocketUpgrade, transformToSSE, validateBaseCustomEndpoint, validateEndpointMethod, validateEndpointPath };