agentxjs 2.0.3 → 2.0.5

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { Message } from '@agentxjs/core/agent';
 import { CreateDriver } from '@agentxjs/core/driver';
+import { AgentXRuntime, AgentXPlatform } from '@agentxjs/core/runtime';
+import { Message } from '@agentxjs/core/agent';
 import { Unsubscribe, BusEvent, EventBus, BusEventHandler } from '@agentxjs/core/event';
-import { AgentXPlatform } from '@agentxjs/core/runtime';
+import * as _agentxjs_core_network from '@agentxjs/core/network';
+import { RpcMethod } from '@agentxjs/core/network';
 
 /**
  * Presentation Types
@@ -214,87 +216,6 @@ declare function messagesToConversations(messages: Message[]): Conversation[];
  * Static or dynamic value
  */
 type MaybeAsync<T> = T | (() => T) | (() => Promise<T>);
-/**
- * LLM provider identifier
- */
-type LLMProvider = "anthropic" | "openai" | "google" | "xai" | "deepseek" | "mistral";
-/**
- * AgentX unified configuration
- *
- * Supports two modes:
- * - **Local mode**: `apiKey` present → embedded Runtime + MonoDriver
- * - **Remote mode**: `serverUrl` present → WebSocket client
- */
-interface AgentXConfig {
-    /**
-     * API key for LLM provider (local mode)
-     * If present, enables local mode with embedded Runtime
-     */
-    apiKey?: string;
-    /**
-     * LLM provider (local mode)
-     * @default "anthropic"
-     */
-    provider?: LLMProvider;
-    /**
-     * Model ID (local mode)
-     */
-    model?: string;
-    /**
-     * Base URL for API endpoint (local mode, for proxy/private deployments)
-     */
-    baseUrl?: string;
-    /**
-     * Data storage path (local mode)
-     * @default ":memory:" (in-memory storage)
-     */
-    dataPath?: string;
-    /**
-     * Custom CreateDriver factory (local mode, advanced)
-     * If provided, overrides the default MonoDriver
-     */
-    createDriver?: CreateDriver;
-    /**
-     * Custom AgentXPlatform (local mode, advanced)
-     * If provided, overrides the default NodePlatform
-     */
-    customPlatform?: AgentXPlatform;
-    /**
-     * WebSocket server URL (remote mode)
-     * If present, enables remote mode
-     */
-    serverUrl?: string;
-    /**
-     * Headers for authentication (remote mode, static or dynamic)
-     * In Node.js: sent during WebSocket handshake
-     * In browsers: sent as first auth message (WebSocket API limitation)
-     */
-    headers?: MaybeAsync<Record<string, string>>;
-    /**
-     * Business context injected into all requests (remote mode)
-     * Useful for passing userId, tenantId, permissions, etc.
-     */
-    context?: MaybeAsync<Record<string, unknown>>;
-    /**
-     * Log level for AgentX runtime
-     * Controls verbosity of console/file logging.
-     * @default "info"
-     */
-    logLevel?: "debug" | "info" | "warn" | "error" | "silent";
-    /**
-     * Request timeout in milliseconds (default: 30000)
-     */
-    timeout?: number;
-    /**
-     * Enable debug logging
-     * @deprecated Use `logLevel: "debug"` instead
-     */
-    debug?: boolean;
-    /**
-     * Auto reconnect on connection loss (default: true, remote mode only)
-     */
-    autoReconnect?: boolean;
-}
 /**
  * Agent info returned from server
  */
@@ -458,6 +379,10 @@ interface ImageNamespace {
      * Delete image
      */
     delete(imageId: string): Promise<BaseResponse>;
+    /**
+     * Get message history for an image
+     */
+    getMessages(imageId: string): Promise<Message[]>;
 }
 /**
  * Agent operations namespace
@@ -509,7 +434,7 @@ interface PresentationNamespace {
      *
      * @example
      * ```typescript
-     * const pres = agentx.presentations.create(agentId, {
+     * const pres = agentx.presentation.create(agentId, {
      *   onUpdate: (state) => renderUI(state),
      *   onError: (error) => console.error(error),
      * });
@@ -521,106 +446,226 @@ interface PresentationNamespace {
     create(agentId: string, options?: PresentationOptions): Promise<Presentation>;
 }
 /**
- * AgentX Client SDK
+ * AgentX Client SDK — unified interface for local, remote, and server modes
  */
 interface AgentX {
     /**
-     * Check if connected to server
+     * Check if connected/active
      */
     readonly connected: boolean;
     /**
      * Event bus for subscribing to events
      */
     readonly events: EventBus;
+    readonly container: ContainerNamespace;
+    readonly image: ImageNamespace;
+    readonly agent: AgentNamespace;
+    readonly session: SessionNamespace;
+    readonly presentation: PresentationNamespace;
+    on<T extends string>(type: T, handler: BusEventHandler<BusEvent & {
+        type: T;
+    }>): Unsubscribe;
+    onAny(handler: BusEventHandler): Unsubscribe;
+    subscribe(sessionId: string): void;
+    disconnect(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * Options for connecting to a remote AgentX server
+ */
+interface ConnectOptions {
+    /** Authentication headers */
+    headers?: MaybeAsync<Record<string, string>>;
+    /** Business context injected into requests */
+    context?: MaybeAsync<Record<string, unknown>>;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Auto reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+}
+/**
+ * Configuration for serving as an AgentX server
+ */
+interface ServeConfig {
+    /** Port to listen on (default: 5200) */
+    port?: number;
+    /** Host to bind to (default: "0.0.0.0") */
+    host?: string;
+    /** Existing HTTP server to attach to */
+    server?: unknown;
+    /** WebSocket path when attached (default: "/ws") */
+    wsPath?: string;
+}
+/**
+ * Server instance returned by serve()
+ */
+interface AgentXServer {
+    listen(port?: number, host?: string): Promise<void>;
+    close(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * AgentXBuilder — fluent API entry point
+ *
+ * Created by `createAgentX(platform?)`. The builder itself is an AgentX
+ * instance (local mode). Call `.connect()` to get a remote client,
+ * or `.serve()` to start a server.
+ *
+ * @example
+ * ```typescript
+ * const ax = createAgentX(node({ createDriver }))
+ *
+ * // Local use
+ * await ax.agent.create({ imageId: "..." })
+ *
+ * // Connect to remote server
+ * const client = await ax.connect("wss://...")
+ *
+ * // Serve as server
+ * const server = await ax.serve({ port: 3100 })
+ * ```
+ */
+interface AgentXBuilder extends AgentX {
     /**
-     * Container operations
-     */
-    readonly containers: ContainerNamespace;
-    /**
-     * Image operations
+     * Connect to a remote AgentX server
      */
-    readonly images: ImageNamespace;
+    connect(serverUrl: string, options?: ConnectOptions): Promise<AgentX>;
     /**
-     * Agent operations
+     * Start serving as an AgentX server
      */
-    readonly agents: AgentNamespace;
+    serve(config?: ServeConfig): Promise<AgentXServer>;
+}
+
+/**
+ * CommandHandler - Handles JSON-RPC requests directly
+ *
+ * No longer uses EventBus for request/response. Instead:
+ * - Receives RPC requests directly
+ * - Returns RPC responses directly
+ * - EventBus is only used for stream events (notifications)
+ */
+
+/**
+ * RPC Result type
+ */
+interface RpcResult<T = unknown> {
+    success: true;
+    data: T;
+}
+interface RpcError {
+    success: false;
+    code: number;
+    message: string;
+}
+type RpcResponse<T = unknown> = RpcResult<T> | RpcError;
+/**
+ * CommandHandler - Processes RPC requests directly
+ */
+declare class CommandHandler {
+    private readonly runtime;
+    constructor(runtime: AgentXRuntime);
+    /**
+     * Handle an RPC request and return response
+     */
+    handle(method: RpcMethod, params: unknown): Promise<RpcResponse>;
+    private handleContainerCreate;
+    private handleContainerGet;
+    private handleContainerList;
+    private handleImageCreate;
+    private handleImageGet;
+    private handleImageList;
+    private handleImageDelete;
+    private handleImageRun;
+    private handleImageStop;
+    private handleImageUpdate;
+    private handleImageMessages;
+    private handleAgentGet;
+    private handleAgentList;
+    private handleAgentDestroy;
+    private handleAgentDestroyAll;
+    private handleAgentInterrupt;
+    private handleMessageSend;
+    dispose(): void;
+}
+
+/**
+ * Server configuration (supports both immediate and deferred platforms)
+ */
+interface ServerConfig {
     /**
-     * Session operations (messaging)
+     * AgentX Platform — must provide `channelServer` for accepting WebSocket connections.
      */
-    readonly sessions: SessionNamespace;
+    platform: AgentXPlatform;
     /**
-     * Presentation operations (UI integration)
+     * LLM Driver factory function - creates Driver per Agent
      */
-    readonly presentations: PresentationNamespace;
+    createDriver: CreateDriver;
     /**
-     * Subscribe to specific event type
+     * Port to listen on (standalone mode)
      */
-    on<T extends string>(type: T, handler: BusEventHandler<BusEvent & {
-        type: T;
-    }>): Unsubscribe;
+    port?: number;
     /**
-     * Subscribe to all events
+     * Host to bind to (default: "0.0.0.0")
      */
-    onAny(handler: BusEventHandler): Unsubscribe;
+    host?: string;
     /**
-     * Subscribe to session events
+     * Existing HTTP server to attach to (attached mode)
      */
-    subscribe(sessionId: string): void;
+    server?: _agentxjs_core_network.MinimalHTTPServer;
     /**
-     * Disconnect from server
+     * WebSocket path when attached (default: "/ws")
      */
-    disconnect(): Promise<void>;
+    wsPath?: string;
     /**
-     * Dispose and cleanup
+     * Enable debug logging
      */
-    dispose(): Promise<void>;
+    debug?: boolean;
 }
+/**
+ * Create an AgentX server
+ */
+declare function createServer(config: ServerConfig): Promise<AgentXServer>;
 
 /**
  * agentxjs - AgentX Client SDK
  *
- * Unified entry point supporting local and remote modes.
+ * Fluent API supporting local, remote, and server modes.
  *
- * @example Local mode (embedded runtime)
+ * @example Local mode
  * ```typescript
  * import { createAgentX } from "agentxjs";
+ * import { node } from "@agentxjs/node-platform";
  *
- * const agentx = await createAgentX({
- *   apiKey: process.env.ANTHROPIC_API_KEY,
- *   provider: "anthropic",
- * });
- *
- * await agentx.containers.create("my-app");
- * const { record: image } = await agentx.images.create({
- *   containerId: "my-app",
- *   systemPrompt: "You are helpful",
- * });
- * const { agentId } = await agentx.agents.create({ imageId: image.imageId });
- *
- * agentx.on("text_delta", (e) => process.stdout.write(e.data.text));
- * await agentx.sessions.send(agentId, "Hello!");
+ * const ax = createAgentX(node({ createDriver }));
+ * await ax.agent.create({ imageId: "..." });
  * ```
  *
- * @example Remote mode (WebSocket client)
+ * @example Remote mode
  * ```typescript
- * import { createAgentX } from "agentxjs";
+ * const ax = createAgentX();
+ * const client = await ax.connect("ws://localhost:5200");
+ * ```
  *
- * const agentx = await createAgentX({
- *   serverUrl: "ws://localhost:5200",
- * });
+ * @example Server mode
+ * ```typescript
+ * const ax = createAgentX(node({ createDriver }));
+ * const server = await ax.serve({ port: 5200 });
  * ```
  */
 
 /**
- * Create an AgentX client
- *
- * Mode detection:
- * - `serverUrl` present → **Remote mode** (WebSocket client)
- * - `apiKey` present → **Local mode** (embedded Runtime + MonoDriver)
+ * Platform configuration for createAgentX
+ */
+interface PlatformConfig {
+    platform: AgentXPlatform;
+    createDriver: CreateDriver;
+}
+/**
+ * Create an AgentX builder
  *
- * @param config - Client configuration
- * @returns Connected AgentX client
+ * @param config - Platform configuration (optional). Without it, only connect() is available.
+ * @returns AgentXBuilder — local AgentX + connect() + serve()
  */
-declare function createAgentX(config: AgentXConfig): Promise<AgentX>;
+declare function createAgentX(config?: PlatformConfig): AgentXBuilder;
 
-export { type AgentCreateResponse, type AgentGetResponse, type AgentInfo, type AgentListResponse, type AgentNamespace, type AgentX, type AgentXConfig, type AssistantConversation, type BaseResponse, type Block, type ContainerCreateResponse, type ContainerGetResponse, type ContainerInfo, type ContainerListResponse, type ContainerNamespace, type Conversation, type ErrorConversation, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageNamespace, type ImageRecord, type LLMProvider, type MaybeAsync, type MessageSendResponse, Presentation, type PresentationErrorHandler, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type SessionNamespace, type TextBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, initialPresentationState, messagesToConversations, presentationReducer };
+export { type AgentCreateResponse, type AgentGetResponse, type AgentInfo, type AgentListResponse, type AgentNamespace, type AgentX, type AgentXBuilder, type AgentXServer, type AssistantConversation, type BaseResponse, type Block, CommandHandler, type ConnectOptions, type ContainerCreateResponse, type ContainerGetResponse, type ContainerInfo, type ContainerListResponse, type ContainerNamespace, type Conversation, type ErrorConversation, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageNamespace, type ImageRecord, type MaybeAsync, type MessageSendResponse, type PlatformConfig, Presentation, type PresentationErrorHandler, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type ServeConfig, type ServerConfig, type SessionNamespace, type TextBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, createServer, initialPresentationState, messagesToConversations, presentationReducer };

package/dist/index.js

@@ -1,3 +1,11 @@
+import {
+  CommandHandler,
+  createServer
+} from "./chunk-ZFL27HK7.js";
+
+// src/index.ts
+import { createAgentXRuntime } from "@agentxjs/core/runtime";
+
 // src/LocalClient.ts
 import { createLogger } from "commonxjs/logger";
 
@@ -188,6 +196,11 @@ function createLocalImages(platform) {
         await image.delete();
       }
       return { requestId: "" };
+    },
+    async getMessages(imageId) {
+      const imageRecord = await platform.imageRepository.findImageById(imageId);
+      if (!imageRecord) return [];
+      return platform.sessionRepository.getMessages(imageRecord.sessionId);
     }
   };
 }
@@ -230,6 +243,10 @@ function createRemoteImages(rpcClient, subscribeFn) {
     async delete(imageId) {
       const result = await rpcClient.call("image.delete", { imageId });
       return { ...result, requestId: "" };
+    },
+    async getMessages(imageId) {
+      const result = await rpcClient.call("image.messages", { imageId });
+      return result.messages ?? [];
     }
   };
 }
@@ -586,7 +603,7 @@ var Presentation = class {
     this.state = addUserConversation(this.state, content);
     this.notify();
     try {
-      await this.agentx.sessions.send(this.agentId, content);
+      await this.agentx.session.send(this.agentId, content);
     } catch (error) {
       this.notifyError(error instanceof Error ? error : new Error(String(error)));
     }
@@ -596,7 +613,7 @@ var Presentation = class {
    */
   async interrupt() {
     try {
-      await this.agentx.sessions.interrupt(this.agentId);
+      await this.agentx.session.interrupt(this.agentId);
     } catch (error) {
       this.notifyError(error instanceof Error ? error : new Error(String(error)));
     }
@@ -658,7 +675,7 @@ var Presentation = class {
 function createPresentations(agentx) {
   return {
     async create(agentId, options) {
-      const messages = await agentx.sessions.getMessages(agentId);
+      const messages = await agentx.session.getMessages(agentId);
       const conversations = messagesToConversations(messages);
       return new Presentation(agentx, agentId, options, conversations);
     }
@@ -712,19 +729,19 @@ var logger = createLogger("agentx/LocalClient");
 var LocalClient = class {
   runtime;
   isDisposed = false;
-  containers;
-  images;
-  agents;
-  sessions;
-  presentations;
+  container;
+  image;
+  agent;
+  session;
+  presentation;
   constructor(runtime) {
     this.runtime = runtime;
     const platform = runtime.platform;
-    this.containers = createLocalContainers(platform);
-    this.images = createLocalImages(platform);
-    this.agents = createLocalAgents(runtime);
-    this.sessions = createLocalSessions(runtime);
-    this.presentations = createPresentations(this);
+    this.container = createLocalContainers(platform);
+    this.image = createLocalImages(platform);
+    this.agent = createLocalAgents(runtime);
+    this.session = createLocalSessions(runtime);
+    this.presentation = createPresentations(this);
     logger.info("LocalClient initialized");
   }
   // ==================== Properties ====================
@@ -763,11 +780,11 @@ var RemoteClient = class {
   config;
   eventBus;
   rpcClient;
-  containers;
-  images;
-  agents;
-  sessions;
-  presentations;
+  container;
+  image;
+  agent;
+  session;
+  presentation;
   constructor(config) {
     this.config = config;
     this.eventBus = new EventBusImpl();
@@ -783,11 +800,11 @@ var RemoteClient = class {
       logger2.debug("Received stream event", { topic, type: event.type });
       this.eventBus.emit(event);
     });
-    this.containers = createRemoteContainers(this.rpcClient);
-    this.images = createRemoteImages(this.rpcClient, (sessionId) => this.subscribe(sessionId));
-    this.agents = createRemoteAgents(this.rpcClient);
-    this.sessions = createRemoteSessions(this.rpcClient);
-    this.presentations = createPresentations(this);
+    this.container = createRemoteContainers(this.rpcClient);
+    this.image = createRemoteImages(this.rpcClient, (sessionId) => this.subscribe(sessionId));
+    this.agent = createRemoteAgents(this.rpcClient);
+    this.session = createRemoteSessions(this.rpcClient);
+    this.presentation = createPresentations(this);
   }
   // ==================== Properties ====================
   get connected() {
@@ -824,77 +841,100 @@ var RemoteClient = class {
 };
 
 // src/index.ts
-async function createAgentX(config) {
-  if (config.serverUrl) {
-    const resolvedConfig = await resolvePlatformForRemote(config);
-    const client = new RemoteClient(resolvedConfig);
-    await client.connect();
-    return client;
-  }
-  if (config.apiKey || config.createDriver || config.customPlatform) {
-    return createLocalClient(config);
-  }
-  throw new Error(
-    "Invalid AgentX config: provide either 'serverUrl' (remote mode) or 'apiKey' (local mode)"
-  );
-}
-async function resolvePlatformForRemote(config) {
-  if (config.customPlatform?.channelClient) {
-    return config;
+function createAgentX(config) {
+  let localClient = null;
+  function getLocalClient() {
+    if (localClient) return localClient;
+    if (!config) {
+      throw new Error(
+        "Local mode requires a platform. Pass a PlatformConfig to createAgentX(), or use connect() for remote mode."
+      );
+    }
+    const runtime = createAgentXRuntime(config.platform, config.createDriver);
+    localClient = new LocalClient(runtime);
+    return localClient;
   }
-  if (typeof globalThis !== "undefined" && globalThis.window?.document !== void 0) {
-    return config;
+  if (config) {
+    getLocalClient();
   }
-  try {
-    const { createNodeWebSocket } = await import("@agentxjs/node-platform/network");
-    return {
-      ...config,
-      customPlatform: {
-        ...config.customPlatform,
-        channelClient: createNodeWebSocket
+  return {
+    get connected() {
+      return localClient?.connected ?? false;
+    },
+    get events() {
+      return getLocalClient().events;
+    },
+    get container() {
+      return getLocalClient().container;
+    },
+    get image() {
+      return getLocalClient().image;
+    },
+    get agent() {
+      return getLocalClient().agent;
+    },
+    get session() {
+      return getLocalClient().session;
+    },
+    get presentation() {
+      return getLocalClient().presentation;
+    },
+    on(type, handler) {
+      return getLocalClient().on(type, handler);
+    },
+    onAny(handler) {
+      return getLocalClient().onAny(handler);
+    },
+    subscribe(sessionId) {
+      getLocalClient().subscribe(sessionId);
+    },
+    async disconnect() {
+      await localClient?.disconnect();
+    },
+    async dispose() {
+      await localClient?.dispose();
+      localClient = null;
+    },
+    async connect(serverUrl, options) {
+      const remoteClient = new RemoteClient({
+        serverUrl,
+        headers: options?.headers,
+        context: options?.context,
+        timeout: options?.timeout,
+        autoReconnect: options?.autoReconnect,
+        customPlatform: config?.platform
+      });
+      await remoteClient.connect();
+      return remoteClient;
+    },
+    async serve(serveConfig) {
+      if (!config) {
+        throw new Error("serve() requires a platform. Pass a PlatformConfig to createAgentX().");
       }
-    };
-  } catch {
-    return config;
-  }
-}
-async function createLocalClient(config) {
-  const { createAgentXRuntime } = await import("@agentxjs/core/runtime");
-  let platform;
-  if (config.customPlatform) {
-    platform = config.customPlatform;
-  } else {
-    const { createNodePlatform } = await import("@agentxjs/node-platform");
-    platform = await createNodePlatform({
-      dataPath: config.dataPath ?? ":memory:",
-      logLevel: config.logLevel ?? (config.debug ? "debug" : void 0)
-    });
-  }
-  let createDriver = config.createDriver;
-  if (!createDriver) {
-    const { createMonoDriver } = await import("@agentxjs/mono-driver");
-    createDriver = (driverConfig) => {
-      const existingOptions = driverConfig.options ?? {};
-      return createMonoDriver({
-        ...driverConfig,
-        apiKey: config.apiKey ?? driverConfig.apiKey,
-        baseUrl: config.baseUrl ?? driverConfig.baseUrl,
-        model: config.model ?? driverConfig.model,
-        options: {
-          ...existingOptions,
-          provider: config.provider ?? existingOptions.provider ?? "anthropic"
-        }
+      if (!config.platform.channelServer) {
+        throw new Error(
+          "serve() requires platform.channelServer. Ensure your platform supports server mode."
+        );
+      }
+      const { createServer: createServer2 } = await import("./server-IFVYHIJF.js");
+      return createServer2({
+        platform: config.platform,
+        createDriver: config.createDriver,
+        port: serveConfig?.port,
+        host: serveConfig?.host,
+        server: serveConfig?.server,
+        wsPath: serveConfig?.wsPath
       });
-    };
-  }
-  const runtime = createAgentXRuntime(platform, createDriver);
-  return new LocalClient(runtime);
+    }
+  };
 }
 export {
+  CommandHandler,
   Presentation,
   addUserConversation,
   createAgentX,
   createInitialState,
+  createServer,
   initialPresentationState,
   messagesToConversations,
   presentationReducer