agentxjs 2.0.2 → 2.0.4

package/src/index.ts

@@ -1,146 +1,158 @@
 /**
  * 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 });
  * ```
  */
 
+import type { CreateDriver } from "@agentxjs/core/driver";
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import { createAgentXRuntime } from "@agentxjs/core/runtime";
 import { LocalClient } from "./LocalClient";
 import { RemoteClient } from "./RemoteClient";
-import type { AgentX, AgentXConfig } from "./types";
+import type { AgentX, AgentXBuilder, AgentXServer, ConnectOptions, ServeConfig } from "./types";
 
 /**
- * Create an AgentX client
- *
- * Mode detection:
- * - `serverUrl` present → **Remote mode** (WebSocket client)
- * - `apiKey` present → **Local mode** (embedded Runtime + MonoDriver)
- *
- * @param config - Client configuration
- * @returns Connected AgentX client
+ * Platform configuration for createAgentX
  */
-export async function createAgentX(config: AgentXConfig): Promise<AgentX> {
-  if (config.serverUrl) {
-    // Remote mode — resolve platform for WebSocket factory if needed
-    const resolvedConfig = await resolvePlatformForRemote(config);
-    const client = new RemoteClient(resolvedConfig);
-    await client.connect();
-    return client;
-  }
-
-  if (config.apiKey || config.createDriver || config.customPlatform) {
-    // Local mode
-    return createLocalClient(config);
-  }
-
-  throw new Error(
-    "Invalid AgentX config: provide either 'serverUrl' (remote mode) or 'apiKey' (local mode)"
-  );
+export interface PlatformConfig {
+  platform: AgentXPlatform;
+  createDriver: CreateDriver;
 }
 
 /**
- * Resolve platform for remote mode
+ * Create an AgentX builder
  *
- * In Node.js: auto-import node-platform to get channelClient
- * In browser: no platform needed (native WebSocket is the default)
+ * @param config - Platform configuration (optional). Without it, only connect() is available.
+ * @returns AgentXBuilder — local AgentX + connect() + serve()
  */
-async function resolvePlatformForRemote(config: AgentXConfig): Promise<AgentXConfig> {
-  if (config.customPlatform?.channelClient) {
-    return config;
-  }
+export function createAgentX(config?: PlatformConfig): AgentXBuilder {
+  let localClient: LocalClient | null = null;
 
-  // In browser, native WebSocket works — no platform needed
-  if (typeof globalThis !== "undefined" && (globalThis as any).window?.document !== undefined) {
-    return config;
+  function getLocalClient(): LocalClient {
+    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;
   }
 
-  // Node.js — auto-resolve channelClient from node-platform
-  try {
-    const { createNodeWebSocket } = await import("@agentxjs/node-platform/network");
-    return {
-      ...config,
-      customPlatform: {
-        ...config.customPlatform,
-        channelClient: createNodeWebSocket,
-      } as any,
-    };
-  } catch {
-    // node-platform not available, fall back to global WebSocket
-    return config;
+  if (config) {
+    getLocalClient();
   }
-}
 
-/**
- * Create a local client with embedded runtime
- */
-async function createLocalClient(config: AgentXConfig): Promise<AgentX> {
-  const { createAgentXRuntime } = await import("@agentxjs/core/runtime");
-
-  // Resolve platform
-  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" : undefined),
-    });
-  }
+  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;
+    },
 
-  // Resolve createDriver
-  let createDriver = config.createDriver;
-  if (!createDriver) {
-    const { createMonoDriver } = await import("@agentxjs/mono-driver");
-    createDriver = (driverConfig: import("@agentxjs/core/driver").DriverConfig) => {
-      const existingOptions = (driverConfig as any).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",
-        },
+    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: string, options?: ConnectOptions): Promise<AgentX> {
+      const remoteClient = new RemoteClient({
+        serverUrl,
+        headers: options?.headers as Record<string, string> | undefined,
+        context: options?.context,
+        timeout: options?.timeout,
+        autoReconnect: options?.autoReconnect,
+        customPlatform: config?.platform,
       });
-    };
-  }
+      await remoteClient.connect();
+      return remoteClient;
+    },
 
-  // Create runtime
-  const runtime = createAgentXRuntime(platform, createDriver);
+    async serve(serveConfig?: ServeConfig): Promise<AgentXServer> {
+      if (!config) {
+        throw new Error("serve() requires a platform. Pass a PlatformConfig to createAgentX().");
+      }
+      if (!config.platform.channelServer) {
+        throw new Error(
+          "serve() requires platform.channelServer. Ensure your platform supports server mode."
+        );
+      }
 
-  return new LocalClient(runtime);
+      const { createServer } = await import("./server");
+      return createServer({
+        platform: config.platform,
+        createDriver: config.createDriver,
+        port: serveConfig?.port,
+        host: serveConfig?.host,
+        server: serveConfig?.server as any,
+        wsPath: serveConfig?.wsPath,
+      });
+    },
+  };
 }
 
+// Re-export server
+export { CommandHandler } from "./CommandHandler";
 // Re-export Presentation types and classes
 export type {
   AssistantConversation,
@@ -164,6 +176,7 @@ export {
   Presentation,
   presentationReducer,
 } from "./presentation";
+export { createServer, type ServerConfig } from "./server";
 // Re-export types
 export type {
   AgentCreateResponse,
@@ -172,8 +185,10 @@ export type {
   AgentListResponse,
   AgentNamespace,
   AgentX,
-  AgentXConfig,
+  AgentXBuilder,
+  AgentXServer,
   BaseResponse,
+  ConnectOptions,
   ContainerCreateResponse,
   ContainerGetResponse,
   ContainerInfo,
@@ -184,9 +199,9 @@ export type {
   ImageListResponse,
   ImageNamespace,
   ImageRecord,
-  LLMProvider,
   MaybeAsync,
   MessageSendResponse,
   PresentationNamespace,
+  ServeConfig,
   SessionNamespace,
 } from "./types";

package/src/namespaces/presentations.ts

@@ -14,7 +14,7 @@ import type { AgentX, PresentationNamespace } from "../types";
 export function createPresentations(agentx: AgentX): PresentationNamespace {
   return {
     async create(agentId: string, options?: PresentationOptions): Promise<Presentation> {
-      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);
     },

package/src/presentation/Presentation.ts

@@ -110,7 +110,7 @@ export class Presentation {
 
     try {
       // Send message via agentx
-      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)));
     }
@@ -121,7 +121,7 @@ export class Presentation {
    */
   async interrupt(): Promise<void> {
     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)));
     }

package/src/server.ts

@@ -0,0 +1,346 @@
+/**
+ * AgentX Server Implementation (JSON-RPC 2.0)
+ *
+ * Creates a WebSocket server that:
+ * 1. Accepts client connections
+ * 2. Handles JSON-RPC requests directly via CommandHandler
+ * 3. Broadcasts stream events as JSON-RPC notifications
+ *
+ * Message Types:
+ * - RPC Request (has id): Client → Server → Client (direct response)
+ * - RPC Notification (no id): Server → Client (stream events)
+ */
+
+import type { CreateDriver } from "@agentxjs/core/driver";
+import type { BusEvent, SystemEvent } from "@agentxjs/core/event";
+import type { ChannelConnection } from "@agentxjs/core/network";
+import {
+  createErrorResponse,
+  createStreamEvent,
+  createSuccessResponse,
+  isNotification,
+  isRequest,
+  parseMessage,
+  RpcErrorCodes,
+  type RpcMethod,
+} from "@agentxjs/core/network";
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import { createAgentXRuntime } from "@agentxjs/core/runtime";
+import { createLogger } from "@deepracticex/logger";
+import { CommandHandler } from "./CommandHandler";
+import type { AgentXServer } from "./types";
+
+const logger = createLogger("server/Server");
+
+/**
+ * Connection state
+ */
+interface ConnectionState {
+  connection: ChannelConnection;
+  subscribedTopics: Set<string>;
+}
+
+/**
+ * Server configuration (supports both immediate and deferred platforms)
+ */
+export interface ServerConfig {
+  /**
+   * AgentX Platform — must provide `channelServer` for accepting WebSocket connections.
+   */
+  platform: AgentXPlatform;
+
+  /**
+   * LLM Driver factory function - creates Driver per Agent
+   */
+  createDriver: CreateDriver;
+
+  /**
+   * Port to listen on (standalone mode)
+   */
+  port?: number;
+
+  /**
+   * Host to bind to (default: "0.0.0.0")
+   */
+  host?: string;
+
+  /**
+   * Existing HTTP server to attach to (attached mode)
+   */
+  server?: import("@agentxjs/core/network").MinimalHTTPServer;
+
+  /**
+   * WebSocket path when attached (default: "/ws")
+   */
+  wsPath?: string;
+
+  /**
+   * Enable debug logging
+   */
+  debug?: boolean;
+}
+
+/**
+ * Create an AgentX server
+ */
+export async function createServer(config: ServerConfig): Promise<AgentXServer> {
+  const { wsPath = "/ws" } = config;
+  const platform = config.platform;
+
+  // Create runtime from platform + driver
+  const runtime = createAgentXRuntime(platform, config.createDriver);
+
+  // Get channel server from platform
+  const wsServer = platform.channelServer;
+  if (!wsServer) {
+    throw new Error("Platform must provide channelServer for server mode");
+  }
+
+  // Create command handler (no longer needs eventBus)
+  const commandHandler = new CommandHandler(runtime);
+
+  // Track connections
+  const connections = new Map<string, ConnectionState>();
+
+  /**
+   * Subscribe connection to a topic
+   */
+  function subscribeToTopic(connectionId: string, topic: string): void {
+    const state = connections.get(connectionId);
+    if (!state || state.subscribedTopics.has(topic)) return;
+
+    state.subscribedTopics.add(topic);
+    logger.debug("Connection subscribed to topic", { connectionId, topic });
+  }
+
+  /**
+   * Check if event should be sent to connection based on subscriptions
+   */
+  function shouldSendToConnection(state: ConnectionState, event: BusEvent): boolean {
+    // Skip internal driver events
+    if (event.source === "driver" && event.intent !== "notification") {
+      return false;
+    }
+
+    // Skip command events (they are handled via RPC, not broadcast)
+    if (event.source === "command") {
+      return false;
+    }
+
+    // Check if subscribed to event's session
+    const eventWithContext = event as BusEvent & { context?: { sessionId?: string } };
+    const sessionId = eventWithContext.context?.sessionId;
+    if (sessionId && state.subscribedTopics.has(sessionId)) {
+      return true;
+    }
+
+    // Send to global subscribers
+    return state.subscribedTopics.has("global");
+  }
+
+  /**
+   * Send JSON-RPC response to a specific connection
+   */
+  function sendResponse(connection: ChannelConnection, id: string | number, result: unknown): void {
+    const response = createSuccessResponse(id, result);
+    connection.send(JSON.stringify(response));
+  }
+
+  /**
+   * Send JSON-RPC error to a specific connection
+   */
+  function sendError(
+    connection: ChannelConnection,
+    id: string | number | null,
+    code: number,
+    message: string
+  ): void {
+    const response = createErrorResponse(id, code, message);
+    connection.send(JSON.stringify(response));
+  }
+
+  // Handle new connections
+  wsServer.onConnection((connection) => {
+    const state: ConnectionState = {
+      connection,
+      subscribedTopics: new Set(["global"]),
+    };
+    connections.set(connection.id, state);
+
+    logger.info("Client connected", {
+      connectionId: connection.id,
+      totalConnections: connections.size,
+    });
+
+    // Handle messages from client
+    connection.onMessage(async (message) => {
+      try {
+        const parsed = parseMessage(message);
+
+        // Handle single message (not batch)
+        if (!Array.isArray(parsed)) {
+          await handleParsedMessage(connection, state, parsed);
+        } else {
+          // Handle batch (not common, but supported by JSON-RPC 2.0)
+          for (const item of parsed) {
+            await handleParsedMessage(connection, state, item);
+          }
+        }
+      } catch (err) {
+        logger.error("Failed to parse message", { error: (err as Error).message });
+        sendError(connection, null, RpcErrorCodes.PARSE_ERROR, "Parse error");
+      }
+    });
+
+    // Cleanup on disconnect
+    connection.onClose(() => {
+      connections.delete(connection.id);
+      logger.info("Client disconnected", {
+        connectionId: connection.id,
+        totalConnections: connections.size,
+      });
+    });
+  });
+
+  /**
+   * Handle a parsed JSON-RPC message
+   */
+  async function handleParsedMessage(
+    connection: ChannelConnection,
+    state: ConnectionState,
+    parsed: import("jsonrpc-lite").IParsedObject
+  ): Promise<void> {
+    if (isRequest(parsed)) {
+      // JSON-RPC Request - handle and respond directly
+      const payload = parsed.payload as {
+        id: string | number;
+        method: string;
+        params: unknown;
+      };
+      const { id, method, params } = payload;
+
+      logger.debug("Received RPC request", { id, method });
+
+      // Call command handler
+      const result = await commandHandler.handle(method as RpcMethod, params);
+
+      if (result.success) {
+        sendResponse(connection, id, result.data);
+      } else {
+        sendError(connection, id, result.code, result.message);
+      }
+    } else if (isNotification(parsed)) {
+      // JSON-RPC Notification - control messages
+      const payload = parsed.payload as {
+        method: string;
+        params: unknown;
+      };
+      const { method, params } = payload;
+
+      logger.debug("Received notification", { method });
+
+      if (method === "subscribe") {
+        const { topic } = params as { topic: string };
+        subscribeToTopic(connection.id, topic);
+      } else if (method === "unsubscribe") {
+        const { topic } = params as { topic: string };
+        state.subscribedTopics.delete(topic);
+        logger.debug("Connection unsubscribed from topic", { connectionId: connection.id, topic });
+      } else if (method === "control.ack") {
+        // ACK for reliable delivery - handled by network layer
+        logger.debug("Received ACK notification");
+      }
+    } else {
+      // Invalid message
+      logger.warn("Received invalid JSON-RPC message");
+    }
+  }
+
+  // Route internal events to connected clients as JSON-RPC notifications
+  platform.eventBus.onAny((event) => {
+    // Only broadcast broadcastable events
+    if (!shouldBroadcastEvent(event)) {
+      return;
+    }
+
+    // Get topic from event context
+    const eventWithContext = event as BusEvent & { context?: { sessionId?: string } };
+    const topic = eventWithContext.context?.sessionId || "global";
+
+    // Wrap as JSON-RPC notification
+    const notification = createStreamEvent(topic, event as SystemEvent);
+    const message = JSON.stringify(notification);
+
+    for (const [connectionId, state] of connections) {
+      if (shouldSendToConnection(state, event)) {
+        state.connection.sendReliable(message, {
+          timeout: 10000,
+          onTimeout: () => {
+            logger.warn("Event ACK timeout", {
+              connectionId,
+              eventType: event.type,
+            });
+          },
+        });
+      }
+    }
+  });
+
+  /**
+   * Check if event should be broadcast
+   */
+  function shouldBroadcastEvent(event: BusEvent): boolean {
+    // Skip internal driver events
+    if (event.source === "driver" && event.intent !== "notification") {
+      return false;
+    }
+
+    // Skip command events (handled via RPC)
+    if (event.source === "command") {
+      return false;
+    }
+
+    // Check broadcastable flag
+    const systemEvent = event as SystemEvent;
+    if (systemEvent.broadcastable === false) {
+      return false;
+    }
+
+    return true;
+  }
+
+  // Attach to existing server if provided
+  if (config.server) {
+    wsServer.attach(config.server, wsPath);
+    logger.info("WebSocket attached to existing server", { path: wsPath });
+  }
+
+  return {
+    async listen(port?: number, host?: string) {
+      if (config.server) {
+        throw new Error(
+          "Cannot listen when attached to existing server. The server should call listen() instead."
+        );
+      }
+
+      const listenPort = port ?? config.port ?? 5200;
+      const listenHost = host ?? config.host ?? "0.0.0.0";
+
+      await wsServer.listen(listenPort, listenHost);
+      logger.info("Server listening", { port: listenPort, host: listenHost });
+    },
+
+    async close() {
+      await wsServer.close();
+      logger.info("Server closed");
+    },
+
+    async dispose() {
+      // Cleanup in order
+      await wsServer.dispose();
+      commandHandler.dispose();
+      await runtime.shutdown();
+      logger.info("Server disposed");
+    },
+  };
+}