agentxjs 1.8.1 → 1.9.1-dev

package/README.md

@@ -1,393 +0,0 @@
-# agentxjs
-
-> Unified API for AI Agents - Server and Browser
-
-## Overview
-
-`agentxjs` provides a **unified API** for building AI agents that works seamlessly across server (Node.js) and browser environments.
-
-**Key Features:**
-
-- **Unified API** - Same `createAgentX()` function for both server and browser
-- **Type-Safe Configuration** - TypeScript discriminates between Source and Mirror modes
-- **Docker-Style Lifecycle** - Container → Agent → Image
-- **Event-Driven** - Real-time streaming events (text_delta, tool_call, etc.)
-
-## Installation
-
-```bash
-pnpm add agentxjs
-```
-
----
-
-## Quick Start
-
-### Server (Source Mode)
-
-```typescript
-import { createAgentX } from "agentxjs";
-
-// Minimal - reads ANTHROPIC_API_KEY from environment
-const agentx = createAgentX();
-
-// Or with explicit configuration
-const agentx = createAgentX({
-  apiKey: "sk-ant-...",
-  model: "claude-sonnet-4-20250514",
-});
-
-// Run an agent
-const agent = await agentx.run({ name: "Assistant" });
-
-// Subscribe to events
-agent.on("text_delta", (e) => process.stdout.write(e.data.text));
-
-// Send message
-await agent.receive("Hello!");
-
-// Cleanup
-await agentx.dispose();
-```
-
-### Browser (Mirror Mode)
-
-```typescript
-import { createAgentX } from "agentxjs";
-
-// Connect to remote server via WebSocket
-const agentx = createAgentX({
-  serverUrl: "ws://localhost:5200",
-  token: "optional-auth-token",
-});
-
-// Same API as server!
-const agent = await agentx.run({ name: "Assistant" });
-
-agent.on("text_delta", (e) => console.log(e.data.text));
-
-await agent.receive("Hello!");
-```
-
----
-
-## API Design
-
-### Configuration Types
-
-```typescript
-// Server-side configuration (Source mode)
-interface SourceConfig {
-  apiKey?: string; // Default: process.env.ANTHROPIC_API_KEY
-  model?: string; // Default: "claude-sonnet-4-20250514"
-  baseUrl?: string; // Default: "https://api.anthropic.com"
-  persistence?: Persistence;
-}
-
-// Browser-side configuration (Mirror mode)
-interface MirrorConfig {
-  serverUrl: string; // WebSocket URL, e.g., "ws://localhost:5200"
-  token?: string; // Authentication token
-  headers?: Record<string, string>;
-}
-
-// Type discrimination: presence of `serverUrl` determines mode
-type AgentXConfig = SourceConfig | MirrorConfig;
-```
-
-### Type Guards
-
-```typescript
-import { isMirrorConfig, isSourceConfig } from "agentxjs";
-
-const config: AgentXConfig = { serverUrl: "ws://localhost:5200" };
-
-if (isMirrorConfig(config)) {
-  // TypeScript knows this is MirrorConfig
-  console.log(config.serverUrl);
-}
-
-if (isSourceConfig(config)) {
-  // TypeScript knows this is SourceConfig
-  console.log(config.apiKey);
-}
-```
-
-### AgentX Interface
-
-```typescript
-interface AgentX {
-  // Quick start - run agent in default container
-  run(config: AgentRunConfig): Promise<Agent>;
-
-  // Container management
-  readonly containers: ContainersAPI;
-
-  // Agent management (cross-container)
-  readonly agents: AgentsAPI;
-
-  // Image (snapshot) management
-  readonly images: ImagesAPI;
-
-  // Cleanup
-  dispose(): Promise<void>;
-}
-```
-
-### Sub-APIs
-
-```typescript
-// Container management
-interface ContainersAPI {
-  create(containerId: string): Promise<Container>;
-  get(containerId: string): Container | undefined;
-  list(): Container[];
-}
-
-// Agent management
-interface AgentsAPI {
-  run(containerId: string, config: AgentRunConfig): Promise<Agent>;
-  get(agentId: string): Agent | undefined;
-  list(containerId: string): Agent[];
-  destroy(agentId: string): Promise<boolean>;
-  destroyAll(containerId: string): Promise<void>;
-}
-
-// Image management
-interface ImagesAPI {
-  snapshot(agent: Agent): Promise<AgentImage>;
-  list(): Promise<AgentImage[]>;
-  get(imageId: string): Promise<AgentImage | null>;
-  delete(imageId: string): Promise<void>;
-}
-```
-
-### Agent Run Configuration
-
-```typescript
-interface AgentRunConfig {
-  name: string;
-  systemPrompt?: string;
-}
-```
-
----
-
-## Architecture
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                         createAgentX(config)                      │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│  config has serverUrl?                                            │
-│         │                                                         │
-│         ├── YES ──▶ Mirror Mode (Browser)                         │
-│         │           - MirrorRuntime                               │
-│         │           - WebSocket communication                     │
-│         │           - Local state mirrors server                  │
-│         │                                                         │
-│         └── NO ───▶ Source Mode (Server)                          │
-│                     - Runtime                                     │
-│                     - Direct LLM access                           │
-│                     - Persistence layer                           │
-│                                                                   │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│                        AgentX API                                 │
-│                                                                   │
-│   agentx.run(config)           Quick start                        │
-│   agentx.containers.*          Container lifecycle                │
-│   agentx.agents.*              Agent operations                   │
-│   agentx.images.*              Snapshot management                │
-│   agentx.dispose()             Cleanup                            │
-│                                                                   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Source vs Mirror
-
-| Aspect        | Source (Server)      | Mirror (Browser) |
-| ------------- | -------------------- | ---------------- |
-| Runtime       | Runtime              | MirrorRuntime    |
-| LLM Access    | Direct API calls     | Via server       |
-| Persistence   | Local (SQLite, etc.) | Server-side      |
-| Communication | N/A                  | WebSocket events |
-| Use Case      | Backend services     | Frontend apps    |
-
----
-
-## Docker-Style Lifecycle
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                     Lifecycle Flow                                │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│   Container                                                       │
-│       │                                                           │
-│       │ run(config)                                               │
-│       ▼                                                           │
-│   Agent (running instance)                                        │
-│       │                                                           │
-│       │ snapshot()                                                │
-│       ▼                                                           │
-│   AgentImage (frozen state)                                       │
-│       │                                                           │
-│       │ resume()                                                  │
-│       ▼                                                           │
-│   Agent (restored from image)                                     │
-│                                                                   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Image Operations
-
-```typescript
-// Create snapshot
-const agent = await agentx.run({ name: "Assistant" });
-await agent.receive("Hello!");
-const image = await agentx.images.snapshot(agent);
-
-// Resume from snapshot
-const resumedAgent = await image.resume();
-// Agent has previous conversation history
-```
-
----
-
-## Event System
-
-### Stream Events (Real-time)
-
-```typescript
-agent.on("message_start", (e) => {
-  /* Response started */
-});
-agent.on("text_delta", (e) => console.log(e.data.text));
-agent.on("tool_call", (e) => {
-  /* Tool being called */
-});
-agent.on("tool_result", (e) => {
-  /* Tool result received */
-});
-agent.on("message_stop", (e) => {
-  /* Response complete */
-});
-```
-
-### Subscribe to All Events
-
-```typescript
-agent.on((event) => {
-  console.log(event.type, event.data);
-});
-```
-
----
-
-## Advanced Usage
-
-### Container Management
-
-```typescript
-// Create named container
-const container = await agentx.containers.create("my-container");
-
-// Run agent in container
-const agent = await agentx.agents.run("my-container", {
-  name: "Assistant",
-  systemPrompt: "You are helpful",
-});
-
-// List agents in container
-const agents = agentx.agents.list("my-container");
-
-// Destroy all agents in container
-await agentx.agents.destroyAll("my-container");
-```
-
-### Custom Persistence (Source Mode)
-
-```typescript
-import { createAgentX } from "agentxjs";
-import { createPersistence } from "@agentxjs/persistence";
-
-const agentx = createAgentX({
-  apiKey: "sk-ant-...",
-  persistence: createPersistence({
-    driver: "sqlite",
-    path: "./data.db",
-  }),
-});
-```
-
----
-
-## Design Decisions
-
-### Why Unified `createAgentX`?
-
-Instead of separate `createSource()` and `createMirror()` functions, we use a single `createAgentX()` with type discrimination:
-
-```typescript
-// Type system determines mode automatically
-createAgentX(); // Source (no serverUrl)
-createAgentX({ apiKey: "..." }); // Source (no serverUrl)
-createAgentX({ serverUrl: "ws://..." }); // Mirror (has serverUrl)
-```
-
-**Benefits:**
-
-- Single import, single function to learn
-- TypeScript enforces correct configuration
-- Easy refactoring between modes
-
-### Why WebSocket for Mirror?
-
-Mirror mode uses WebSocket (not HTTP/SSE) for bidirectional communication:
-
-1. **Request/Response pattern** - Browser sends commands, server responds
-2. **Real-time events** - Server pushes stream events to browser
-3. **State synchronization** - Browser maintains local mirror of server state
-
-### Why No `defineAgent`?
-
-Previous versions required:
-
-```typescript
-const MyAgent = defineAgent({ name: "Assistant", ... });
-agentx.definitions.register(MyAgent);
-const image = agentx.images.getMetaImage(MyAgent.name);
-const agent = await image.run();
-```
-
-New API is simpler:
-
-```typescript
-const agent = await agentx.run({ name: "Assistant", ... });
-```
-
-The `AgentRunConfig` replaces `AgentDefinition` for most use cases. For advanced scenarios (versioning, derived images), use the Images API directly.
-
----
-
-## Package Dependencies
-
-```text
-@agentxjs/types      Type definitions
-       ↑
-@agentxjs/common     Logger facade
-       ↑
-@agentxjs/runtime    Runtime implementation
-       ↑
-@agentxjs/mirror     MirrorRuntime implementation
-       ↑
-agentxjs             This package (unified API)
-```
-
----
-
-## License
-
-MIT

package/dist/browser.js

@@ -1,228 +0,0 @@
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined")
-    return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
-// src/browser.ts
-import { isLocalConfig, isRemoteConfig as isRemoteConfig2 } from "@agentxjs/types/agentx";
-import {
-  isFromSource,
-  hasIntent,
-  isRequest,
-  isResult,
-  isNotification
-} from "@agentxjs/types/event";
-import { isCommandEvent, isCommandRequest, isCommandResponse } from "@agentxjs/types/event";
-import {
-  isAgentEvent,
-  isAgentStreamEvent,
-  isAgentStateEvent,
-  isAgentMessageEvent,
-  isAgentTurnEvent
-} from "@agentxjs/types/event";
-import { isRemoteConfig as isRemoteConfig3 } from "@agentxjs/types/agentx";
-
-// src/createAgentX.ts
-import { isRemoteConfig } from "@agentxjs/types/agentx";
-import { createLogger } from "@agentxjs/common";
-var remoteLogger = createLogger("agentx/RemoteClient");
-async function createRemoteAgentX(config) {
-  const { createWebSocketClient } = await import("@agentxjs/network");
-  const client = await createWebSocketClient({
-    serverUrl: config.serverUrl,
-    headers: config.headers,
-    autoReconnect: true,
-    minReconnectionDelay: 1000,
-    maxReconnectionDelay: 1e4,
-    connectionTimeout: 4000,
-    maxRetries: Infinity,
-    debug: false
-  });
-  const handlers = new Map;
-  const pendingRequests = new Map;
-  client.onMessage((message) => {
-    try {
-      const event = JSON.parse(message);
-      remoteLogger.info("Received event", {
-        type: event.type,
-        category: event.category,
-        requestId: event.data?.requestId
-      });
-      if (event.type === "system_error") {
-        const errorData = event.data;
-        remoteLogger.error(errorData.message, {
-          severity: errorData.severity,
-          requestId: event.data?.requestId,
-          details: errorData.details
-        });
-      }
-      const requestId = event.data?.requestId;
-      if (event.category === "response" && requestId && pendingRequests.has(requestId)) {
-        remoteLogger.info("Resolving pending request", { requestId, eventType: event.type });
-        const pending = pendingRequests.get(requestId);
-        clearTimeout(pending.timer);
-        pendingRequests.delete(requestId);
-        pending.resolve(event);
-        return;
-      }
-      remoteLogger.info("Dispatching to handlers", { type: event.type });
-      const typeHandlers = handlers.get(event.type);
-      if (typeHandlers) {
-        for (const handler of typeHandlers) {
-          handler(event);
-        }
-      }
-      const allHandlers = handlers.get("*");
-      if (allHandlers) {
-        for (const handler of allHandlers) {
-          handler(event);
-        }
-      }
-    } catch {}
-  });
-  client.onClose(() => {
-    remoteLogger.warn("WebSocket closed");
-  });
-  client.onError((error) => {
-    remoteLogger.error("WebSocket error", { error: error.message });
-  });
-  function subscribe(type, handler) {
-    if (!handlers.has(type)) {
-      handlers.set(type, new Set);
-    }
-    handlers.get(type).add(handler);
-    return () => {
-      handlers.get(type)?.delete(handler);
-    };
-  }
-  return {
-    async request(type, data, timeout = 30000) {
-      const requestId = `req_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
-      let mergedData = { ...data, requestId };
-      if (config.context) {
-        try {
-          let resolvedContext;
-          if (typeof config.context === "function") {
-            resolvedContext = await Promise.resolve(config.context());
-          } else {
-            resolvedContext = config.context;
-          }
-          mergedData = {
-            ...resolvedContext,
-            ...data,
-            requestId
-          };
-          remoteLogger.info("Merged context into request", {
-            type,
-            requestId,
-            contextKeys: Object.keys(resolvedContext)
-          });
-        } catch (error) {
-          remoteLogger.error("Failed to resolve context", {
-            type,
-            requestId,
-            error: error instanceof Error ? error.message : String(error)
-          });
-        }
-      }
-      return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-          pendingRequests.delete(requestId);
-          reject(new Error(`Request timeout: ${type}`));
-        }, timeout);
-        pendingRequests.set(requestId, {
-          resolve,
-          reject,
-          timer
-        });
-        const event = {
-          type,
-          timestamp: Date.now(),
-          data: mergedData,
-          source: "command",
-          category: "request",
-          intent: "request"
-        };
-        client.send(JSON.stringify(event));
-      });
-    },
-    on(type, handler) {
-      return subscribe(type, handler);
-    },
-    onCommand(type, handler) {
-      return subscribe(type, handler);
-    },
-    emitCommand(type, data) {
-      const event = {
-        type,
-        timestamp: Date.now(),
-        data,
-        source: "command",
-        category: type.toString().endsWith("_response") ? "response" : "request",
-        intent: type.toString().endsWith("_response") ? "result" : "request"
-      };
-      client.send(JSON.stringify(event));
-    },
-    async listen() {
-      throw new Error("Cannot listen in remote mode");
-    },
-    async close() {},
-    async dispose() {
-      for (const pending of pendingRequests.values()) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error("AgentX disposed"));
-      }
-      pendingRequests.clear();
-      handlers.clear();
-      client.dispose();
-    }
-  };
-}
-
-// src/browser.ts
-async function createAgentX(config) {
-  if (!config || !isRemoteConfig3(config)) {
-    throw new Error("Browser environment only supports remote mode. " + 'Please provide { serverUrl: "ws://..." } configuration.');
-  }
-  return createRemoteAgentX(config);
-}
-export {
-  isResult,
-  isRequest,
-  isRemoteConfig2 as isRemoteConfig,
-  isNotification,
-  isLocalConfig,
-  isFromSource,
-  isCommandResponse,
-  isCommandRequest,
-  isCommandEvent,
-  isAgentTurnEvent,
-  isAgentStreamEvent,
-  isAgentStateEvent,
-  isAgentMessageEvent,
-  isAgentEvent,
-  hasIntent,
-  createRemoteAgentX,
-  createAgentX
-};
-
-//# debugId=8D4B9F8AA8319ED964756E2164756E21

package/dist/browser.js.map

@@ -1,11 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/browser.ts", "../src/createAgentX.ts"],
-  "sourcesContent": [
-    "/**\n * agentxjs - Browser Entry Point\n *\n * This entry is automatically selected by bundlers (Vite, Webpack, etc.)\n * when building for browser environments.\n *\n * Only includes remote mode (WebSocket client).\n * Does not include Node.js specific code (runtime, fs, sqlite, etc.)\n */\n\n// Re-export everything from index except createAgentX\nexport type {\n  AgentX,\n  AgentXConfig,\n  LocalConfig,\n  RemoteConfig,\n  LLMConfig,\n  StorageConfig,\n  StorageDriver,\n  Unsubscribe,\n} from \"@agentxjs/types/agentx\";\n\nexport { isLocalConfig, isRemoteConfig } from \"@agentxjs/types/agentx\";\n\n// Event types\nexport type {\n  SystemEvent,\n  EventSource,\n  EventCategory,\n  EventIntent,\n  EventContext,\n} from \"@agentxjs/types/event\";\n\nexport {\n  isFromSource,\n  hasIntent,\n  isRequest,\n  isResult,\n  isNotification,\n} from \"@agentxjs/types/event\";\n\n// Command events\nexport type {\n  CommandEvent,\n  CommandRequest,\n  CommandResponse,\n  CommandEventType,\n  CommandRequestType,\n  CommandEventMap,\n  ContainerCreateRequest,\n  ContainerCreateResponse,\n  ContainerGetRequest,\n  ContainerGetResponse,\n  ContainerListRequest,\n  ContainerListResponse,\n  AgentGetRequest,\n  AgentGetResponse,\n  AgentListRequest,\n  AgentListResponse,\n  AgentDestroyRequest,\n  AgentDestroyResponse,\n  MessageSendRequest,\n  MessageSendResponse,\n  AgentInterruptRequest,\n  AgentInterruptResponse,\n  ImageCreateRequest,\n  ImageCreateResponse,\n  ImageRunRequest,\n  ImageRunResponse,\n  ImageStopRequest,\n  ImageStopResponse,\n  ImageUpdateRequest,\n  ImageUpdateResponse,\n  ImageListRequest,\n  ImageListResponse,\n  ImageListItem,\n  ImageGetRequest,\n  ImageGetResponse,\n  ImageDeleteRequest,\n  ImageDeleteResponse,\n} from \"@agentxjs/types/event\";\n\nexport { isCommandEvent, isCommandRequest, isCommandResponse } from \"@agentxjs/types/event\";\n\n// Agent events\nexport type {\n  AgentEvent,\n  AgentEventCategory,\n  AgentStreamEvent,\n  AgentTextDeltaEvent,\n  AgentMessageStartEvent,\n  AgentMessageStopEvent,\n  AgentToolUseStartEvent,\n  AgentToolUseStopEvent,\n  AgentToolResultEvent,\n  AgentStateEvent,\n  ConversationStartEvent,\n  ConversationEndEvent,\n  ConversationThinkingEvent,\n  ConversationRespondingEvent,\n  ToolExecutingEvent,\n  ToolCompletedEvent,\n  ErrorOccurredEvent,\n  AgentMessageEvent,\n  UserMessageEvent,\n  AssistantMessageEvent,\n  ToolCallMessageEvent,\n  ToolResultMessageEvent,\n  AgentTurnEvent,\n  TurnRequestEvent,\n  TurnResponseEvent,\n  TokenUsage,\n} from \"@agentxjs/types/event\";\n\nexport {\n  isAgentEvent,\n  isAgentStreamEvent,\n  isAgentStateEvent,\n  isAgentMessageEvent,\n  isAgentTurnEvent,\n} from \"@agentxjs/types/event\";\n\n// Data types\nexport type { ImageRecord } from \"@agentxjs/types\";\n\nexport type {\n  Message,\n  UserMessage,\n  AssistantMessage,\n  ToolCallMessage,\n  ToolResultMessage,\n  AgentError,\n  ContentPart,\n  TextPart,\n  ToolCallPart,\n  ToolResultPart,\n  ToolResultOutput,\n} from \"@agentxjs/types/agent\";\n\n// Browser-only createAgentX (remote mode only)\nimport type { AgentX, AgentXConfig } from \"@agentxjs/types/agentx\";\nimport { isRemoteConfig } from \"@agentxjs/types/agentx\";\nimport { createRemoteAgentX } from \"./createAgentX\";\n\n/**\n * Create AgentX instance (Browser version - remote mode only)\n *\n * @param config - Must be RemoteConfig with server URL\n * @returns AgentX instance\n *\n * @example\n * ```typescript\n * const agentx = await createAgentX({ server: \"ws://localhost:5200\" });\n * ```\n */\nexport async function createAgentX(config: AgentXConfig): Promise<AgentX> {\n  if (!config || !isRemoteConfig(config)) {\n    throw new Error(\n      \"Browser environment only supports remote mode. \" +\n        'Please provide { serverUrl: \"ws://...\" } configuration.'\n    );\n  }\n  return createRemoteAgentX(config);\n}\n\n// Also export createRemoteAgentX for explicit usage\nexport { createRemoteAgentX } from \"./createAgentX\";\n",
-    "/**\n * createAgentX - Factory function for creating AgentX instances\n *\n * Supports two modes:\n * - Local mode: Uses Runtime directly (Claude API) - Node.js only\n * - Remote mode: Connects to AgentX server via WebSocket - Browser & Node.js\n *\n * Local mode implementation is dynamically imported to enable tree-shaking\n * in browser builds.\n */\n\nimport type { AgentX, AgentXConfig, RemoteConfig, Unsubscribe } from \"@agentxjs/types/agentx\";\nimport { isRemoteConfig } from \"@agentxjs/types/agentx\";\nimport type {\n  CommandEventMap,\n  CommandRequestType,\n  ResponseEventFor,\n  RequestDataFor,\n  SystemEvent,\n} from \"@agentxjs/types/event\";\nimport { createLogger } from \"@agentxjs/common\";\n\nconst remoteLogger = createLogger(\"agentx/RemoteClient\");\n\n/**\n * Create AgentX instance\n *\n * @param config - Configuration (LocalConfig or RemoteConfig)\n * @returns AgentX instance\n *\n * @example\n * ```typescript\n * // Remote mode (browser & Node.js)\n * const agentx = await createAgentX({ serverUrl: \"ws://localhost:5200\" });\n *\n * // Local mode (Node.js only)\n * const agentx = await createAgentX({ llm: { apiKey: \"sk-...\" } });\n * ```\n */\nexport async function createAgentX(config?: AgentXConfig): Promise<AgentX> {\n  if (config && isRemoteConfig(config)) {\n    return createRemoteAgentX(config);\n  }\n\n  // Dynamic import for tree-shaking in browser builds\n  const { createLocalAgentX } = await import(\"./createLocalAgentX\");\n  return createLocalAgentX(config ?? {});\n}\n\n// ============================================================================\n// Remote Mode Implementation (Browser & Node.js compatible)\n// ============================================================================\n\n/**\n * Create AgentX instance in remote mode\n *\n * Connects to an AgentX server via WebSocket.\n * Works in both browser and Node.js environments.\n *\n * @param config - Remote configuration (serverUrl, headers, context)\n * @returns AgentX instance\n */\nexport async function createRemoteAgentX(config: RemoteConfig): Promise<AgentX> {\n  // Use @agentxjs/network for WebSocket client (handles browser/Node.js differences)\n  const { createWebSocketClient } = await import(\"@agentxjs/network\");\n\n  const client = await createWebSocketClient({\n    serverUrl: config.serverUrl,\n    headers: config.headers,\n    autoReconnect: true,\n    minReconnectionDelay: 1000,\n    maxReconnectionDelay: 10000,\n    connectionTimeout: 4000,\n    maxRetries: Infinity,\n    debug: false,\n  });\n\n  const handlers = new Map<string, Set<(event: SystemEvent) => void>>();\n  const pendingRequests = new Map<\n    string,\n    {\n      resolve: (event: SystemEvent) => void;\n      reject: (err: Error) => void;\n      timer: ReturnType<typeof setTimeout>;\n    }\n  >();\n\n  // Handle incoming messages\n  client.onMessage((message: string) => {\n    try {\n      const event = JSON.parse(message) as SystemEvent;\n\n      remoteLogger.info(\"Received event\", {\n        type: event.type,\n        category: event.category,\n        requestId: (event.data as any)?.requestId,\n      });\n\n      // Handle error events - log as error (but still dispatch to handlers)\n      if (event.type === \"system_error\") {\n        const errorData = event.data as { message: string; severity?: string; details?: unknown };\n        remoteLogger.error(errorData.message, {\n          severity: errorData.severity,\n          requestId: (event.data as any)?.requestId,\n          details: errorData.details,\n        });\n        // Continue to dispatch to handlers (don't return here)\n      }\n\n      // Check if it's a response to a pending request\n      const requestId = (event.data as { requestId?: string })?.requestId;\n      if (event.category === \"response\" && requestId && pendingRequests.has(requestId)) {\n        remoteLogger.info(\"Resolving pending request\", { requestId, eventType: event.type });\n        const pending = pendingRequests.get(requestId)!;\n        clearTimeout(pending.timer);\n        pendingRequests.delete(requestId);\n        pending.resolve(event);\n        return;\n      }\n\n      remoteLogger.info(\"Dispatching to handlers\", { type: event.type });\n\n      // Dispatch to handlers\n      const typeHandlers = handlers.get(event.type);\n      if (typeHandlers) {\n        for (const handler of typeHandlers) {\n          handler(event);\n        }\n      }\n\n      // Dispatch to \"*\" handlers\n      const allHandlers = handlers.get(\"*\");\n      if (allHandlers) {\n        for (const handler of allHandlers) {\n          handler(event);\n        }\n      }\n    } catch {\n      // Ignore parse errors\n    }\n  });\n\n  // Handle connection events\n  client.onClose(() => {\n    remoteLogger.warn(\"WebSocket closed\");\n  });\n\n  client.onError((error: Error) => {\n    remoteLogger.error(\"WebSocket error\", { error: error.message });\n  });\n\n  function subscribe(type: string, handler: (event: SystemEvent) => void): Unsubscribe {\n    if (!handlers.has(type)) {\n      handlers.set(type, new Set());\n    }\n    handlers.get(type)!.add(handler);\n    return () => {\n      handlers.get(type)?.delete(handler);\n    };\n  }\n\n  return {\n    async request<T extends CommandRequestType>(\n      type: T,\n      data: RequestDataFor<T>,\n      timeout: number = 30000\n    ): Promise<ResponseEventFor<T>> {\n      const requestId = `req_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;\n\n      // Resolve and merge context if provided\n      let mergedData = { ...data, requestId };\n      if (config.context) {\n        try {\n          let resolvedContext: Record<string, unknown>;\n          if (typeof config.context === \"function\") {\n            resolvedContext = await Promise.resolve(config.context());\n          } else {\n            resolvedContext = config.context;\n          }\n\n          // Merge context into data\n          // Request-level context (if present in data) takes precedence\n          mergedData = {\n            ...resolvedContext,\n            ...data,\n            requestId,\n          } as RequestDataFor<T> & { requestId: string };\n\n          remoteLogger.info(\"Merged context into request\", {\n            type,\n            requestId,\n            contextKeys: Object.keys(resolvedContext),\n          });\n        } catch (error) {\n          remoteLogger.error(\"Failed to resolve context\", {\n            type,\n            requestId,\n            error: error instanceof Error ? error.message : String(error),\n          });\n          // Continue without context if resolution fails\n        }\n      }\n\n      return new Promise((resolve, reject) => {\n        const timer = setTimeout(() => {\n          pendingRequests.delete(requestId);\n          reject(new Error(`Request timeout: ${type}`));\n        }, timeout);\n\n        pendingRequests.set(requestId, {\n          resolve: resolve as (event: SystemEvent) => void,\n          reject,\n          timer,\n        });\n\n        const event: SystemEvent = {\n          type,\n          timestamp: Date.now(),\n          data: mergedData,\n          source: \"command\",\n          category: \"request\",\n          intent: \"request\",\n        };\n\n        client.send(JSON.stringify(event));\n      });\n    },\n\n    on<T extends string>(\n      type: T,\n      handler: (event: SystemEvent & { type: T }) => void\n    ): Unsubscribe {\n      return subscribe(type, handler as (event: SystemEvent) => void);\n    },\n\n    onCommand<T extends keyof CommandEventMap>(\n      type: T,\n      handler: (event: CommandEventMap[T]) => void\n    ): Unsubscribe {\n      return subscribe(type, handler as (event: SystemEvent) => void);\n    },\n\n    emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T][\"data\"]): void {\n      const event: SystemEvent = {\n        type,\n        timestamp: Date.now(),\n        data,\n        source: \"command\",\n        category: type.toString().endsWith(\"_response\") ? \"response\" : \"request\",\n        intent: type.toString().endsWith(\"_response\") ? \"result\" : \"request\",\n      };\n      client.send(JSON.stringify(event));\n    },\n\n    async listen() {\n      throw new Error(\"Cannot listen in remote mode\");\n    },\n\n    async close() {\n      // No-op in remote mode\n    },\n\n    async dispose() {\n      for (const pending of pendingRequests.values()) {\n        clearTimeout(pending.timer);\n        pending.reject(new Error(\"AgentX disposed\"));\n      }\n      pendingRequests.clear();\n      handlers.clear();\n      client.dispose();\n    },\n  };\n}\n"
-  ],
-  "mappings": "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",
-  "debugId": "8D4B9F8AA8319ED964756E2164756E21",
-  "names": []
-}