@agentxjs/types 1.5.11 → 1.7.0

package/dist/src/agentx/index.d.ts

@@ -938,6 +938,54 @@ interface RemoteConfig {
 	* @example "ws://localhost:5200"
 	*/
 	serverUrl: string;
+	/**
+	* Custom headers for WebSocket connection authentication
+	*
+	* - Node.js: Headers are sent during WebSocket handshake
+	* - Browser: Headers are sent in first authentication message (WebSocket API limitation)
+	*
+	* Supports both static values and dynamic functions (sync or async).
+	*
+	* @example
+	* ```typescript
+	* // Static headers
+	* headers: { Authorization: "Bearer sk-xxx" }
+	*
+	* // Dynamic headers (sync)
+	* headers: () => ({ Authorization: `Bearer ${getToken()}` })
+	*
+	* // Dynamic headers (async)
+	* headers: async () => ({ Authorization: `Bearer ${await fetchToken()}` })
+	* ```
+	*/
+	headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+	/**
+	* Business context injected into all requests
+	*
+	* This context is automatically merged into the `data` field of every request.
+	* Individual requests can override with their own context.
+	*
+	* Supports both static values and dynamic functions (sync or async).
+	*
+	* @example
+	* ```typescript
+	* // Static context
+	* context: { userId: "123", tenantId: "abc" }
+	*
+	* // Dynamic context (sync)
+	* context: () => ({ userId: getCurrentUser().id, permissions: getPermissions() })
+	*
+	* // Dynamic context (async)
+	* context: async () => ({ userId: await getUserId(), sessionId: await getSessionId() })
+	*
+	* // Request-level override
+	* agentx.request("message_send", {
+	*   content: "Hello",
+	*   context: { traceId: "trace-xxx" } // Merged with global context
+	* })
+	* ```
+	*/
+	context?: Record<string, unknown> | (() => Record<string, unknown> | Promise<Record<string, unknown>>);
 }
 /**
 * AgentX configuration

package/dist/src/agentx/index.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/agentx/index.ts"],
   "sourcesContent": [
-    "/**\n * AgentX - Unified High-Level API for AI Agents\n *\n * AgentX provides a simple, consistent API for both local and remote modes.\n * It wraps Runtime and provides the same interface regardless of deployment.\n *\n * ## Two Modes\n *\n * ```\n * Local Mode                          Remote Mode\n * ─────────────────────────────────────────────────────────\n * AgentX                              AgentX\n *   │                                   │\n *   └── Runtime (embedded)              └── WebSocket ──→ Server\n *         │                                                │\n *         └── LLM, Storage                                 └── Runtime\n * ```\n *\n * ## API Design\n *\n * All operations use CommandEvent pattern:\n * - `request(type, data)` - Send request, wait for response\n * - `on(type, handler)` - Subscribe to events\n * - `onCommand(type, handler)` - Type-safe command subscription\n *\n * ## Usage\n *\n * ```typescript\n * // Local mode (default)\n * const agentx = await createAgentX();\n *\n * // Local mode with custom LLM and storage\n * const agentx = await createAgentX({\n *   llm: { apiKey: \"sk-...\", model: \"claude-opus-4-20250514\" },\n *   storage: { driver: \"postgresql\", url: \"postgres://...\" },\n * });\n *\n * // Remote mode\n * const agentx = await createAgentX({ server: \"ws://localhost:5200\" });\n *\n * // Same API for both modes!\n * const res = await agentx.request(\"container_create_request\", {\n *   containerId: \"my-container\"\n * });\n *\n * agentx.on(\"text_delta\", (e) => console.log(e.data.text));\n *\n * await agentx.dispose();\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { SystemEvent } from \"~/event/base\";\nimport type {\n  CommandEventMap,\n  CommandRequestType,\n  ResponseEventFor,\n  RequestDataFor,\n} from \"~/event/command\";\nimport type { LogLevel, LoggerFactory } from \"~/common/logger\";\n\n// ============================================================================\n// Configuration - Local Mode\n// ============================================================================\n\n/**\n * LLM configuration\n */\nexport interface LLMConfig {\n  /**\n   * Anthropic API key (required)\n   */\n  apiKey: string;\n\n  /**\n   * API base URL\n   * @default \"https://api.anthropic.com\"\n   */\n  baseUrl?: string;\n\n  /**\n   * Model name\n   * @default \"claude-sonnet-4-20250514\"\n   */\n  model?: string;\n}\n\n/**\n * Storage driver type\n */\nexport type StorageDriver =\n  | \"memory\"\n  | \"fs\"\n  | \"redis\"\n  | \"mongodb\"\n  | \"sqlite\"\n  | \"mysql\"\n  | \"postgresql\";\n\n/**\n * Storage configuration\n */\nexport interface StorageConfig {\n  /**\n   * Storage driver\n   * @default \"memory\"\n   */\n  driver?: StorageDriver;\n\n  /**\n   * File path (for sqlite, fs drivers)\n   * @example \"./data.db\" for sqlite\n   * @example \"./data\" for fs\n   */\n  path?: string;\n\n  /**\n   * Connection URL (for redis, mongodb, mysql, postgresql)\n   * @example \"redis://localhost:6379\"\n   * @example \"mongodb://localhost:27017/agentx\"\n   * @example \"mysql://user:pass@localhost:3306/agentx\"\n   * @example \"postgres://user:pass@localhost:5432/agentx\"\n   */\n  url?: string;\n}\n\n/**\n * Logger configuration\n */\nexport interface LoggerConfig {\n  /**\n   * Log level\n   * @default LogLevel.INFO\n   */\n  level?: LogLevel;\n\n  /**\n   * Custom logger factory implementation\n   * If provided, this factory will be used to create all logger instances.\n   * If not provided, uses ConsoleLogger with console options.\n   */\n  factory?: LoggerFactory;\n\n  /**\n   * Console logger options (only used when factory is not provided)\n   */\n  console?: {\n    /**\n     * Enable colored output\n     * @default true (Node.js), false (browser)\n     */\n    colors?: boolean;\n\n    /**\n     * Include timestamps in log output\n     * @default true\n     */\n    timestamps?: boolean;\n  };\n}\n\n/**\n * Local mode configuration\n *\n * Runs AgentX with local runtime, connecting directly to LLM API.\n */\nexport interface LocalConfig {\n  /**\n   * LLM configuration\n   */\n  llm?: LLMConfig;\n\n  /**\n   * Logger configuration\n   */\n  logger?: LoggerConfig;\n\n  /**\n   * Default agent definition\n   *\n   * When creating a new image without explicit config, these values are used.\n   * The definition is copied to ImageRecord at creation time.\n   */\n  defaultAgent?: AgentDefinition;\n\n  /**\n   * AgentX base directory for runtime data (containers, workdirs, storage, logs)\n   * @default \"~/.agentx\" (user's home directory)\n   * @example \"/var/lib/agentx\"\n   * @example \"/Users/john/.agentx\"\n   *\n   * Directory structure:\n   * - {agentxDir}/data/agentx.db - SQLite database (auto-configured)\n   * - {agentxDir}/logs/ - Log files (if configured)\n   * - {agentxDir}/containers/ - Agent workdirs\n   */\n  agentxDir?: string;\n\n  /**\n   * Runtime environment configuration\n   * For advanced settings like Claude Code executable path\n   */\n  environment?: {\n    /**\n     * Path to Claude Code executable\n     * Required for binary distribution where Claude Code is bundled\n     * @example \"/path/to/claude-code/cli.js\"\n     */\n    claudeCodePath?: string;\n  };\n\n  /**\n   * HTTP server to attach WebSocket to.\n   * If provided, WebSocket upgrade will be handled on the same port.\n   * The server should handle authentication before upgrading.\n   *\n   * @example\n   * ```typescript\n   * import { createServer } from \"http\";\n   * import { Hono } from \"hono\";\n   *\n   * const app = new Hono();\n   * // ... add auth middleware\n   *\n   * const server = createServer(app.fetch);\n   * const agentx = await createAgentX({ server });\n   *\n   * server.listen(5200);\n   * ```\n   */\n  server?: {\n    on(\n      event: \"upgrade\",\n      listener: (\n        request: { url?: string; headers: { host?: string } },\n        socket: unknown,\n        head: unknown\n      ) => void\n    ): void;\n  };\n}\n\n// ============================================================================\n// Configuration - Remote Mode\n// ============================================================================\n\n/**\n * Remote mode configuration\n *\n * Connects to a remote AgentX server via WebSocket.\n */\nexport interface RemoteConfig {\n  /**\n   * Remote server URL (WebSocket)\n   * @example \"ws://localhost:5200\"\n   */\n  serverUrl: string;\n}\n\n// ============================================================================\n// Union Type\n// ============================================================================\n\n/**\n * AgentX configuration\n *\n * - LocalConfig: Run with local runtime (default)\n * - RemoteConfig: Connect to remote server\n */\nexport type AgentXConfig = LocalConfig | RemoteConfig;\n\n/**\n * Type guard: is this a remote config?\n */\nexport function isRemoteConfig(config: AgentXConfig): config is RemoteConfig {\n  return \"serverUrl\" in config && typeof config.serverUrl === \"string\";\n}\n\n/**\n * Type guard: is this a local config?\n */\nexport function isLocalConfig(config: AgentXConfig): config is LocalConfig {\n  return !isRemoteConfig(config);\n}\n\n// ============================================================================\n// Unsubscribe\n// ============================================================================\n\n/**\n * Unsubscribe function\n */\nexport type Unsubscribe = () => void;\n\n// ============================================================================\n// AgentX Interface\n// ============================================================================\n\n/**\n * AgentX - Main API interface\n *\n * Unified API for both local and remote modes.\n */\nexport interface AgentX {\n  // ==================== Core API ====================\n\n  /**\n   * Send a command request and wait for response.\n   *\n   * @example\n   * ```typescript\n   * const res = await agentx.request(\"container_create_request\", {\n   *   containerId: \"my-container\"\n   * });\n   * console.log(res.data.containerId);\n   * ```\n   */\n  request<T extends CommandRequestType>(\n    type: T,\n    data: RequestDataFor<T>,\n    timeout?: number\n  ): Promise<ResponseEventFor<T>>;\n\n  /**\n   * Subscribe to events.\n   *\n   * @example\n   * ```typescript\n   * agentx.on(\"text_delta\", (e) => {\n   *   process.stdout.write(e.data.text);\n   * });\n   * ```\n   */\n  on<T extends string>(type: T, handler: (event: SystemEvent & { type: T }) => void): Unsubscribe;\n\n  /**\n   * Subscribe to command events with full type safety.\n   *\n   * @example\n   * ```typescript\n   * agentx.onCommand(\"container_create_response\", (e) => {\n   *   console.log(e.data.containerId);\n   * });\n   * ```\n   */\n  onCommand<T extends keyof CommandEventMap>(\n    type: T,\n    handler: (event: CommandEventMap[T]) => void\n  ): Unsubscribe;\n\n  /**\n   * Emit a command event.\n   *\n   * For fine-grained control. Usually prefer `request()`.\n   */\n  emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T][\"data\"]): void;\n\n  // ==================== Server API (local mode only) ====================\n\n  /**\n   * Start listening for remote connections.\n   *\n   * Only available in local mode.\n   *\n   * @example\n   * ```typescript\n   * await agentx.listen(5200);\n   * console.log(\"Server running on ws://localhost:5200\");\n   * ```\n   */\n  listen(port: number, host?: string): Promise<void>;\n\n  /**\n   * Stop listening for remote connections.\n   */\n  close(): Promise<void>;\n\n  // ==================== Lifecycle ====================\n\n  /**\n   * Dispose AgentX and release all resources.\n   */\n  dispose(): Promise<void>;\n}\n\n// ============================================================================\n// Factory Function\n// ============================================================================\n\n/**\n * Create AgentX instance\n *\n * @example\n * ```typescript\n * // Local mode (default)\n * const agentx = await createAgentX();\n *\n * // Local mode with config\n * const agentx = await createAgentX({\n *   llm: { apiKey: \"sk-...\" },\n *   storage: { driver: \"sqlite\", path: \"./data.db\" },\n * });\n *\n * // Remote mode\n * const agentx = await createAgentX({ server: \"ws://localhost:5200\" });\n * ```\n */\nexport declare function createAgentX(config?: AgentXConfig): Promise<AgentX>;\n\n// ============================================================================\n// Agent Definition\n// ============================================================================\n\nimport type { McpServerConfig } from \"~/runtime/internal/container/sandbox/mcp\";\n\n/**\n * AgentDefinition - Static template for defining an Agent\n *\n * Used to define agent behavior and capabilities before instantiation.\n * This is the \"application layer\" configuration that describes what an agent does.\n *\n * @example\n * ```typescript\n * const MyAgent = defineAgent({\n *   name: \"Assistant\",\n *   description: \"A helpful AI assistant\",\n *   systemPrompt: \"You are a helpful assistant.\",\n *   mcpServers: {\n *     filesystem: {\n *       command: \"npx\",\n *       args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]\n *     }\n *   }\n * });\n * ```\n */\nexport interface AgentDefinition {\n  /**\n   * Agent name (required)\n   */\n  name: string;\n\n  /**\n   * Agent description\n   */\n  description?: string;\n\n  /**\n   * System prompt - controls agent behavior\n   */\n  systemPrompt?: string;\n\n  /**\n   * MCP servers configuration\n   *\n   * Key is server name, value is server configuration.\n   * Supports stdio, sse, http, and sdk transport types.\n   */\n  mcpServers?: Record<string, McpServerConfig>;\n}\n\n/**\n * Define an Agent with type safety\n *\n * Helper function that provides type inference for AgentDefinition.\n * The returned definition can be used with AgentX to create agent instances.\n *\n * Implementation is in `agentxjs` package.\n *\n * @example\n * ```typescript\n * import { defineAgent } from \"agentxjs\";\n *\n * export const MyAgent = defineAgent({\n *   name: \"MyAgent\",\n *   systemPrompt: \"You are helpful.\",\n *   mcpServers: {\n *     github: { type: \"sse\", url: \"http://localhost:3000/sse\" }\n *   }\n * });\n * ```\n */\nexport declare function defineAgent<T extends AgentDefinition>(definition: T): T;\n"
+    "/**\n * AgentX - Unified High-Level API for AI Agents\n *\n * AgentX provides a simple, consistent API for both local and remote modes.\n * It wraps Runtime and provides the same interface regardless of deployment.\n *\n * ## Two Modes\n *\n * ```\n * Local Mode                          Remote Mode\n * ─────────────────────────────────────────────────────────\n * AgentX                              AgentX\n *   │                                   │\n *   └── Runtime (embedded)              └── WebSocket ──→ Server\n *         │                                                │\n *         └── LLM, Storage                                 └── Runtime\n * ```\n *\n * ## API Design\n *\n * All operations use CommandEvent pattern:\n * - `request(type, data)` - Send request, wait for response\n * - `on(type, handler)` - Subscribe to events\n * - `onCommand(type, handler)` - Type-safe command subscription\n *\n * ## Usage\n *\n * ```typescript\n * // Local mode (default)\n * const agentx = await createAgentX();\n *\n * // Local mode with custom LLM and storage\n * const agentx = await createAgentX({\n *   llm: { apiKey: \"sk-...\", model: \"claude-opus-4-20250514\" },\n *   storage: { driver: \"postgresql\", url: \"postgres://...\" },\n * });\n *\n * // Remote mode\n * const agentx = await createAgentX({ server: \"ws://localhost:5200\" });\n *\n * // Same API for both modes!\n * const res = await agentx.request(\"container_create_request\", {\n *   containerId: \"my-container\"\n * });\n *\n * agentx.on(\"text_delta\", (e) => console.log(e.data.text));\n *\n * await agentx.dispose();\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { SystemEvent } from \"~/event/base\";\nimport type {\n  CommandEventMap,\n  CommandRequestType,\n  ResponseEventFor,\n  RequestDataFor,\n} from \"~/event/command\";\nimport type { LogLevel, LoggerFactory } from \"~/common/logger\";\n\n// ============================================================================\n// Configuration - Local Mode\n// ============================================================================\n\n/**\n * LLM configuration\n */\nexport interface LLMConfig {\n  /**\n   * Anthropic API key (required)\n   */\n  apiKey: string;\n\n  /**\n   * API base URL\n   * @default \"https://api.anthropic.com\"\n   */\n  baseUrl?: string;\n\n  /**\n   * Model name\n   * @default \"claude-sonnet-4-20250514\"\n   */\n  model?: string;\n}\n\n/**\n * Storage driver type\n */\nexport type StorageDriver =\n  | \"memory\"\n  | \"fs\"\n  | \"redis\"\n  | \"mongodb\"\n  | \"sqlite\"\n  | \"mysql\"\n  | \"postgresql\";\n\n/**\n * Storage configuration\n */\nexport interface StorageConfig {\n  /**\n   * Storage driver\n   * @default \"memory\"\n   */\n  driver?: StorageDriver;\n\n  /**\n   * File path (for sqlite, fs drivers)\n   * @example \"./data.db\" for sqlite\n   * @example \"./data\" for fs\n   */\n  path?: string;\n\n  /**\n   * Connection URL (for redis, mongodb, mysql, postgresql)\n   * @example \"redis://localhost:6379\"\n   * @example \"mongodb://localhost:27017/agentx\"\n   * @example \"mysql://user:pass@localhost:3306/agentx\"\n   * @example \"postgres://user:pass@localhost:5432/agentx\"\n   */\n  url?: string;\n}\n\n/**\n * Logger configuration\n */\nexport interface LoggerConfig {\n  /**\n   * Log level\n   * @default LogLevel.INFO\n   */\n  level?: LogLevel;\n\n  /**\n   * Custom logger factory implementation\n   * If provided, this factory will be used to create all logger instances.\n   * If not provided, uses ConsoleLogger with console options.\n   */\n  factory?: LoggerFactory;\n\n  /**\n   * Console logger options (only used when factory is not provided)\n   */\n  console?: {\n    /**\n     * Enable colored output\n     * @default true (Node.js), false (browser)\n     */\n    colors?: boolean;\n\n    /**\n     * Include timestamps in log output\n     * @default true\n     */\n    timestamps?: boolean;\n  };\n}\n\n/**\n * Local mode configuration\n *\n * Runs AgentX with local runtime, connecting directly to LLM API.\n */\nexport interface LocalConfig {\n  /**\n   * LLM configuration\n   */\n  llm?: LLMConfig;\n\n  /**\n   * Logger configuration\n   */\n  logger?: LoggerConfig;\n\n  /**\n   * Default agent definition\n   *\n   * When creating a new image without explicit config, these values are used.\n   * The definition is copied to ImageRecord at creation time.\n   */\n  defaultAgent?: AgentDefinition;\n\n  /**\n   * AgentX base directory for runtime data (containers, workdirs, storage, logs)\n   * @default \"~/.agentx\" (user's home directory)\n   * @example \"/var/lib/agentx\"\n   * @example \"/Users/john/.agentx\"\n   *\n   * Directory structure:\n   * - {agentxDir}/data/agentx.db - SQLite database (auto-configured)\n   * - {agentxDir}/logs/ - Log files (if configured)\n   * - {agentxDir}/containers/ - Agent workdirs\n   */\n  agentxDir?: string;\n\n  /**\n   * Runtime environment configuration\n   * For advanced settings like Claude Code executable path\n   */\n  environment?: {\n    /**\n     * Path to Claude Code executable\n     * Required for binary distribution where Claude Code is bundled\n     * @example \"/path/to/claude-code/cli.js\"\n     */\n    claudeCodePath?: string;\n  };\n\n  /**\n   * HTTP server to attach WebSocket to.\n   * If provided, WebSocket upgrade will be handled on the same port.\n   * The server should handle authentication before upgrading.\n   *\n   * @example\n   * ```typescript\n   * import { createServer } from \"http\";\n   * import { Hono } from \"hono\";\n   *\n   * const app = new Hono();\n   * // ... add auth middleware\n   *\n   * const server = createServer(app.fetch);\n   * const agentx = await createAgentX({ server });\n   *\n   * server.listen(5200);\n   * ```\n   */\n  server?: {\n    on(\n      event: \"upgrade\",\n      listener: (\n        request: { url?: string; headers: { host?: string } },\n        socket: unknown,\n        head: unknown\n      ) => void\n    ): void;\n  };\n}\n\n// ============================================================================\n// Configuration - Remote Mode\n// ============================================================================\n\n/**\n * Remote mode configuration\n *\n * Connects to a remote AgentX server via WebSocket.\n */\nexport interface RemoteConfig {\n  /**\n   * Remote server URL (WebSocket)\n   * @example \"ws://localhost:5200\"\n   */\n  serverUrl: string;\n\n  /**\n   * Custom headers for WebSocket connection authentication\n   *\n   * - Node.js: Headers are sent during WebSocket handshake\n   * - Browser: Headers are sent in first authentication message (WebSocket API limitation)\n   *\n   * Supports both static values and dynamic functions (sync or async).\n   *\n   * @example\n   * ```typescript\n   * // Static headers\n   * headers: { Authorization: \"Bearer sk-xxx\" }\n   *\n   * // Dynamic headers (sync)\n   * headers: () => ({ Authorization: `Bearer ${getToken()}` })\n   *\n   * // Dynamic headers (async)\n   * headers: async () => ({ Authorization: `Bearer ${await fetchToken()}` })\n   * ```\n   */\n  headers?:\n    | Record<string, string>\n    | (() => Record<string, string> | Promise<Record<string, string>>);\n\n  /**\n   * Business context injected into all requests\n   *\n   * This context is automatically merged into the `data` field of every request.\n   * Individual requests can override with their own context.\n   *\n   * Supports both static values and dynamic functions (sync or async).\n   *\n   * @example\n   * ```typescript\n   * // Static context\n   * context: { userId: \"123\", tenantId: \"abc\" }\n   *\n   * // Dynamic context (sync)\n   * context: () => ({ userId: getCurrentUser().id, permissions: getPermissions() })\n   *\n   * // Dynamic context (async)\n   * context: async () => ({ userId: await getUserId(), sessionId: await getSessionId() })\n   *\n   * // Request-level override\n   * agentx.request(\"message_send\", {\n   *   content: \"Hello\",\n   *   context: { traceId: \"trace-xxx\" } // Merged with global context\n   * })\n   * ```\n   */\n  context?:\n    | Record<string, unknown>\n    | (() => Record<string, unknown> | Promise<Record<string, unknown>>);\n}\n\n// ============================================================================\n// Union Type\n// ============================================================================\n\n/**\n * AgentX configuration\n *\n * - LocalConfig: Run with local runtime (default)\n * - RemoteConfig: Connect to remote server\n */\nexport type AgentXConfig = LocalConfig | RemoteConfig;\n\n/**\n * Type guard: is this a remote config?\n */\nexport function isRemoteConfig(config: AgentXConfig): config is RemoteConfig {\n  return \"serverUrl\" in config && typeof config.serverUrl === \"string\";\n}\n\n/**\n * Type guard: is this a local config?\n */\nexport function isLocalConfig(config: AgentXConfig): config is LocalConfig {\n  return !isRemoteConfig(config);\n}\n\n// ============================================================================\n// Unsubscribe\n// ============================================================================\n\n/**\n * Unsubscribe function\n */\nexport type Unsubscribe = () => void;\n\n// ============================================================================\n// AgentX Interface\n// ============================================================================\n\n/**\n * AgentX - Main API interface\n *\n * Unified API for both local and remote modes.\n */\nexport interface AgentX {\n  // ==================== Core API ====================\n\n  /**\n   * Send a command request and wait for response.\n   *\n   * @example\n   * ```typescript\n   * const res = await agentx.request(\"container_create_request\", {\n   *   containerId: \"my-container\"\n   * });\n   * console.log(res.data.containerId);\n   * ```\n   */\n  request<T extends CommandRequestType>(\n    type: T,\n    data: RequestDataFor<T>,\n    timeout?: number\n  ): Promise<ResponseEventFor<T>>;\n\n  /**\n   * Subscribe to events.\n   *\n   * @example\n   * ```typescript\n   * agentx.on(\"text_delta\", (e) => {\n   *   process.stdout.write(e.data.text);\n   * });\n   * ```\n   */\n  on<T extends string>(type: T, handler: (event: SystemEvent & { type: T }) => void): Unsubscribe;\n\n  /**\n   * Subscribe to command events with full type safety.\n   *\n   * @example\n   * ```typescript\n   * agentx.onCommand(\"container_create_response\", (e) => {\n   *   console.log(e.data.containerId);\n   * });\n   * ```\n   */\n  onCommand<T extends keyof CommandEventMap>(\n    type: T,\n    handler: (event: CommandEventMap[T]) => void\n  ): Unsubscribe;\n\n  /**\n   * Emit a command event.\n   *\n   * For fine-grained control. Usually prefer `request()`.\n   */\n  emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T][\"data\"]): void;\n\n  // ==================== Server API (local mode only) ====================\n\n  /**\n   * Start listening for remote connections.\n   *\n   * Only available in local mode.\n   *\n   * @example\n   * ```typescript\n   * await agentx.listen(5200);\n   * console.log(\"Server running on ws://localhost:5200\");\n   * ```\n   */\n  listen(port: number, host?: string): Promise<void>;\n\n  /**\n   * Stop listening for remote connections.\n   */\n  close(): Promise<void>;\n\n  // ==================== Lifecycle ====================\n\n  /**\n   * Dispose AgentX and release all resources.\n   */\n  dispose(): Promise<void>;\n}\n\n// ============================================================================\n// Factory Function\n// ============================================================================\n\n/**\n * Create AgentX instance\n *\n * @example\n * ```typescript\n * // Local mode (default)\n * const agentx = await createAgentX();\n *\n * // Local mode with config\n * const agentx = await createAgentX({\n *   llm: { apiKey: \"sk-...\" },\n *   storage: { driver: \"sqlite\", path: \"./data.db\" },\n * });\n *\n * // Remote mode\n * const agentx = await createAgentX({ server: \"ws://localhost:5200\" });\n * ```\n */\nexport declare function createAgentX(config?: AgentXConfig): Promise<AgentX>;\n\n// ============================================================================\n// Agent Definition\n// ============================================================================\n\nimport type { McpServerConfig } from \"~/runtime/internal/container/sandbox/mcp\";\n\n/**\n * AgentDefinition - Static template for defining an Agent\n *\n * Used to define agent behavior and capabilities before instantiation.\n * This is the \"application layer\" configuration that describes what an agent does.\n *\n * @example\n * ```typescript\n * const MyAgent = defineAgent({\n *   name: \"Assistant\",\n *   description: \"A helpful AI assistant\",\n *   systemPrompt: \"You are a helpful assistant.\",\n *   mcpServers: {\n *     filesystem: {\n *       command: \"npx\",\n *       args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]\n *     }\n *   }\n * });\n * ```\n */\nexport interface AgentDefinition {\n  /**\n   * Agent name (required)\n   */\n  name: string;\n\n  /**\n   * Agent description\n   */\n  description?: string;\n\n  /**\n   * System prompt - controls agent behavior\n   */\n  systemPrompt?: string;\n\n  /**\n   * MCP servers configuration\n   *\n   * Key is server name, value is server configuration.\n   * Supports stdio, sse, http, and sdk transport types.\n   */\n  mcpServers?: Record<string, McpServerConfig>;\n}\n\n/**\n * Define an Agent with type safety\n *\n * Helper function that provides type inference for AgentDefinition.\n * The returned definition can be used with AgentX to create agent instances.\n *\n * Implementation is in `agentxjs` package.\n *\n * @example\n * ```typescript\n * import { defineAgent } from \"agentxjs\";\n *\n * export const MyAgent = defineAgent({\n *   name: \"MyAgent\",\n *   systemPrompt: \"You are helpful.\",\n *   mcpServers: {\n *     github: { type: \"sse\", url: \"http://localhost:3000/sse\" }\n *   }\n * });\n * ```\n */\nexport declare function defineAgent<T extends AgentDefinition>(definition: T): T;\n"
   ],
-  "mappings": ";AAmRO,SAAS,cAAc,CAAC,QAA8C;AAAA,EAC3E,OAAO,eAAe,UAAU,OAAO,OAAO,cAAc;AAAA;AAMvD,SAAS,aAAa,CAAC,QAA6C;AAAA,EACzE,OAAO,CAAC,eAAe,MAAM;AAAA;",
+  "mappings": ";AAyUO,SAAS,cAAc,CAAC,QAA8C;AAAA,EAC3E,OAAO,eAAe,UAAU,OAAO,OAAO,cAAc;AAAA;AAMvD,SAAS,aAAa,CAAC,QAA6C;AAAA,EACzE,OAAO,CAAC,eAAe,MAAM;AAAA;",
   "debugId": "55C19403325817F564756E2164756E21",
   "names": []
 }

package/dist/src/network/index.d.ts

@@ -146,6 +146,15 @@ interface ChannelClientOptions {
 	* Enable debug logging (default: false)
 	*/
 	debug?: boolean;
+	/**
+	* Custom headers for WebSocket connection
+	*
+	* - Node.js: Headers are sent during WebSocket handshake
+	* - Browser: Headers are sent in first authentication message (WebSocket API limitation)
+	*
+	* Supports both static values and dynamic functions (sync or async).
+	*/
+	headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
 }
 /**
 * Channel server factory options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentxjs/types",
-  "version": "1.5.11",
+  "version": "1.7.0",
   "description": "Type definitions for AgentX ecosystem",
   "license": "MIT",
   "engines": {