agentxjs 2.0.3 → 2.0.5

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");
+    },
+  };
+}

package/src/types.ts

@@ -3,7 +3,6 @@
  */
 
 import type { Message } from "@agentxjs/core/agent";
-import type { CreateDriver } from "@agentxjs/core/driver";
 import type { BusEvent, BusEventHandler, EventBus, Unsubscribe } from "@agentxjs/core/event";
 import type { AgentXPlatform } from "@agentxjs/core/runtime";
 import type { Presentation, PresentationOptions } from "./presentation";
@@ -18,105 +17,16 @@ import type { Presentation, PresentationOptions } from "./presentation";
 export type MaybeAsync<T> = T | (() => T) | (() => Promise<T>);
 
 /**
- * LLM provider identifier
+ * Internal config passed to RemoteClient
+ * @internal
  */
-export 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
- */
-export interface AgentXConfig {
-  // ===== Local Mode =====
-
-  /**
-   * 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;
-
-  // ===== Remote Mode =====
-
-  /**
-   * 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)
-   */
+export interface RemoteClientConfig {
+  serverUrl: string;
   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>>;
-
-  // ===== Common =====
-
-  /**
-   * 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;
+  customPlatform?: AgentXPlatform;
 }
 
 // ============================================================================
@@ -319,6 +229,11 @@ export interface ImageNamespace {
    * Delete image
    */
   delete(imageId: string): Promise<BaseResponse>;
+
+  /**
+   * Get message history for an image
+   */
+  getMessages(imageId: string): Promise<Message[]>;
 }
 
 /**
@@ -375,7 +290,7 @@ export 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),
    * });
@@ -392,11 +307,11 @@ export interface PresentationNamespace {
 // ============================================================================
 
 /**
- * AgentX Client SDK
+ * AgentX Client SDK — unified interface for local, remote, and server modes
  */
 export interface AgentX {
   /**
-   * Check if connected to server
+   * Check if connected/active
    */
   readonly connected: boolean;
 
@@ -407,59 +322,96 @@ export interface AgentX {
 
   // ==================== Namespaced Operations ====================
 
-  /**
-   * Container operations
-   */
-  readonly containers: ContainerNamespace;
-
-  /**
-   * Image operations
-   */
-  readonly images: ImageNamespace;
-
-  /**
-   * Agent operations
-   */
-  readonly agents: AgentNamespace;
-
-  /**
-   * Session operations (messaging)
-   */
-  readonly sessions: SessionNamespace;
-
-  /**
-   * Presentation operations (UI integration)
-   */
-  readonly presentations: PresentationNamespace;
+  readonly container: ContainerNamespace;
+  readonly image: ImageNamespace;
+  readonly agent: AgentNamespace;
+  readonly session: SessionNamespace;
+  readonly presentation: PresentationNamespace;
 
   // ==================== Event Subscription ====================
 
-  /**
-   * Subscribe to specific event type
-   */
   on<T extends string>(type: T, handler: BusEventHandler<BusEvent & { type: T }>): Unsubscribe;
-
-  /**
-   * Subscribe to all events
-   */
   onAny(handler: BusEventHandler): Unsubscribe;
-
-  /**
-   * Subscribe to session events
-   */
   subscribe(sessionId: string): void;
 
   // ==================== Lifecycle ====================
 
+  disconnect(): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+// ============================================================================
+// Fluent Builder Interface
+// ============================================================================
+
+/**
+ * Options for connecting to a remote AgentX server
+ */
+export 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
+ */
+export 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()
+ */
+export 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 })
+ * ```
+ */
+export interface AgentXBuilder extends AgentX {
   /**
-   * Disconnect from server
+   * Connect to a remote AgentX server
    */
-  disconnect(): Promise<void>;
+  connect(serverUrl: string, options?: ConnectOptions): Promise<AgentX>;
 
   /**
-   * Dispose and cleanup
+   * Start serving as an AgentX server
    */
-  dispose(): Promise<void>;
+  serve(config?: ServeConfig): Promise<AgentXServer>;
 }
 
 // ============================================================================