agentxjs 1.9.0 → 1.9.2-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,275 +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 __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-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/createRemoteAgentX.ts
-import { hasSubscriptions } from "@agentxjs/types/agentx";
-import { createLogger, generateRequestId } from "@agentxjs/common";
-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
-  });
-  logger.info("Client connected");
-  const handlers = new Map;
-  const pendingRequests = new Map;
-  const subscribedSessions = new Set(["global"]);
-  function subscribeToSession(sessionId) {
-    if (subscribedSessions.has(sessionId)) {
-      return;
-    }
-    client.send(JSON.stringify({
-      type: "subscribe",
-      sessionId
-    }));
-    subscribedSessions.add(sessionId);
-    logger.debug("Subscribed to session", { sessionId });
-  }
-  client.onMessage((message) => {
-    try {
-      const event = JSON.parse(message);
-      logger.debug("Received event", {
-        type: event.type,
-        category: event.category,
-        requestId: event.data?.requestId
-      });
-      if (event.type === "system_error") {
-        const errorData = event.data;
-        logger.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)) {
-        logger.debug("Resolving pending request", { requestId, eventType: event.type });
-        const pending = pendingRequests.get(requestId);
-        clearTimeout(pending.timer);
-        pendingRequests.delete(requestId);
-        pending.resolve(event);
-        return;
-      }
-      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(() => {
-    logger.warn("WebSocket closed");
-  });
-  client.onError((error) => {
-    logger.error("WebSocket error", { error: error.message });
-  });
-  client.onOpen(() => {
-    if (subscribedSessions.size > 1) {
-      logger.info("Reconnected, re-subscribing to sessions", {
-        sessions: Array.from(subscribedSessions)
-      });
-      for (const sessionId of subscribedSessions) {
-        if (sessionId !== "global") {
-          client.send(JSON.stringify({
-            type: "subscribe",
-            sessionId
-          }));
-        }
-      }
-    }
-  });
-  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 = generateRequestId();
-      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
-          };
-          logger.debug("Merged context into request", {
-            type,
-            requestId,
-            contextKeys: Object.keys(resolvedContext)
-          });
-        } catch (error) {
-          logger.error("Failed to resolve context", {
-            type,
-            requestId,
-            error: error instanceof Error ? error.message : String(error)
-          });
-        }
-      }
-      const response = await 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));
-      });
-      const responseData = response.data;
-      if (hasSubscriptions(responseData)) {
-        for (const sessionId of responseData.__subscriptions) {
-          subscribeToSession(sessionId);
-        }
-        logger.debug("Auto-subscribed to sessions from response", {
-          type,
-          sessionIds: responseData.__subscriptions
-        });
-      }
-      return response;
-    },
-    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();
-      subscribedSessions.clear();
-      client.dispose();
-    }
-  };
-}
-var logger;
-var init_createRemoteAgentX = __esm(() => {
-  logger = createLogger("agentx/RemoteClient");
-});
-
-// 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
-init_createRemoteAgentX();
-import { isRemoteConfig } from "@agentxjs/types/agentx";
-
-// 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=DABE902E367A863664756E2164756E21