@agentxjs/server 1.9.1-dev

package/bin/server.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+/**
+ * AgentX Server - Standalone server startup script
+ *
+ * Usage:
+ *   ANTHROPIC_API_KEY=sk-xxx bun run bin/server.ts
+ *
+ * Environment variables:
+ *   ANTHROPIC_API_KEY - Required: Claude API key
+ *   ANTHROPIC_BASE_URL - Optional: Custom API endpoint
+ *   PORT - Server port (default: 5200)
+ *   HOST - Server host (default: 0.0.0.0)
+ *   DATA_PATH - Data storage path (default: ./data)
+ *   LOG_LEVEL - Log level: debug/info/warn/error (default: info)
+ */
+
+import { createServer } from "../src";
+import { nodeProvider } from "@agentxjs/node-provider";
+import { createClaudeDriverFactory } from "@agentxjs/claude-driver";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("server/bin");
+
+async function main() {
+  // Validate API key
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    console.error("Error: ANTHROPIC_API_KEY environment variable is required");
+    console.error("");
+    console.error("Usage:");
+    console.error("  ANTHROPIC_API_KEY=sk-xxx bun run bin/server.ts");
+    process.exit(1);
+  }
+
+  // Configuration from environment
+  const port = parseInt(process.env.PORT ?? "5200", 10);
+  const host = process.env.HOST ?? "0.0.0.0";
+  const dataPath = process.env.DATA_PATH ?? "./data";
+  const logDir = process.env.LOG_DIR ?? `${dataPath}/logs`;
+  const debug = process.env.LOG_LEVEL === "debug";
+
+  logger.info("Starting AgentX Server", {
+    port,
+    host,
+    dataPath,
+    logDir,
+    debug,
+  });
+
+  // Create driver factory
+  const driverFactory = createClaudeDriverFactory();
+
+  // Create server with nodeProvider
+  const server = await createServer({
+    provider: nodeProvider({
+      dataPath,
+      driverFactory,
+      logDir,
+    }),
+    port,
+    host,
+    debug,
+  });
+
+  // Start listening
+  await server.listen();
+
+  logger.info("AgentX Server started", {
+    url: `ws://${host}:${port}`,
+  });
+
+  // Handle shutdown
+  const shutdown = async () => {
+    logger.info("Shutting down...");
+    await server.dispose();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((err) => {
+  console.error("Failed to start server:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@agentxjs/server",
+  "version": "1.9.1-dev",
+  "description": "AgentX Server - WebSocket server with Provider support",
+  "type": "module",
+  "bin": {
+    "agentx-server": "./bin/server.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run bin/server.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@agentxjs/core": "workspace:*",
+    "@agentxjs/node-provider": "workspace:*",
+    "@agentxjs/claude-driver": "workspace:*",
+    "commonxjs": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}

package/src/CommandHandler.ts

@@ -0,0 +1,423 @@
+/**
+ * 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)
+ */
+
+import type { AgentXRuntime } from "@agentxjs/core/runtime";
+import type { UserContentPart } from "@agentxjs/core/agent";
+import type { RpcMethod } from "@agentxjs/core/network";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("server/CommandHandler");
+
+/**
+ * RPC Result type
+ */
+export interface RpcResult<T = unknown> {
+  success: true;
+  data: T;
+}
+
+export interface RpcError {
+  success: false;
+  code: number;
+  message: string;
+}
+
+export type RpcResponse<T = unknown> = RpcResult<T> | RpcError;
+
+/**
+ * Helper to create success result
+ */
+function ok<T>(data: T): RpcResult<T> {
+  return { success: true, data };
+}
+
+/**
+ * Helper to create error result
+ */
+function err(code: number, message: string): RpcError {
+  return { success: false, code, message };
+}
+
+/**
+ * CommandHandler - Processes RPC requests directly
+ */
+export class CommandHandler {
+  private readonly runtime: AgentXRuntime;
+
+  constructor(runtime: AgentXRuntime) {
+    this.runtime = runtime;
+    logger.debug("CommandHandler created");
+  }
+
+  /**
+   * Handle an RPC request and return response
+   */
+  async handle(method: RpcMethod, params: unknown): Promise<RpcResponse> {
+    logger.debug("Handling RPC request", { method });
+
+    try {
+      switch (method) {
+        // Container
+        case "container.create":
+          return await this.handleContainerCreate(params);
+        case "container.get":
+          return await this.handleContainerGet(params);
+        case "container.list":
+          return await this.handleContainerList(params);
+
+        // Image
+        case "image.create":
+          return await this.handleImageCreate(params);
+        case "image.get":
+          return await this.handleImageGet(params);
+        case "image.list":
+          return await this.handleImageList(params);
+        case "image.delete":
+          return await this.handleImageDelete(params);
+        case "image.run":
+          return await this.handleImageRun(params);
+        case "image.stop":
+          return await this.handleImageStop(params);
+        case "image.update":
+          return await this.handleImageUpdate(params);
+        case "image.messages":
+          return await this.handleImageMessages(params);
+
+        // Agent
+        case "agent.get":
+          return await this.handleAgentGet(params);
+        case "agent.list":
+          return await this.handleAgentList(params);
+        case "agent.destroy":
+          return await this.handleAgentDestroy(params);
+        case "agent.destroyAll":
+          return await this.handleAgentDestroyAll(params);
+        case "agent.interrupt":
+          return await this.handleAgentInterrupt(params);
+
+        // Message
+        case "message.send":
+          return await this.handleMessageSend(params);
+
+        default:
+          return err(-32601, `Method not found: ${method}`);
+      }
+    } catch (error) {
+      logger.error("RPC handler error", { method, error });
+      return err(-32000, error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  // ==================== Container Commands ====================
+
+  private async handleContainerCreate(params: unknown): Promise<RpcResponse> {
+    const { containerId } = params as { containerId: string };
+    const { getOrCreateContainer } = await import("@agentxjs/core/container");
+    const { containerRepository, imageRepository, sessionRepository } = this.runtime.provider;
+
+    const container = await getOrCreateContainer(containerId, {
+      containerRepository,
+      imageRepository,
+      sessionRepository,
+    });
+
+    return ok({ containerId: container.containerId });
+  }
+
+  private async handleContainerGet(params: unknown): Promise<RpcResponse> {
+    const { containerId } = params as { containerId: string };
+    const exists = await this.runtime.provider.containerRepository.containerExists(containerId);
+    return ok({ containerId, exists });
+  }
+
+  private async handleContainerList(_params: unknown): Promise<RpcResponse> {
+    const containers = await this.runtime.provider.containerRepository.findAllContainers();
+    return ok({ containerIds: containers.map((c) => c.containerId) });
+  }
+
+  // ==================== Image Commands ====================
+
+  private async handleImageCreate(params: unknown): Promise<RpcResponse> {
+    const { containerId, name, description, systemPrompt, mcpServers } = params as {
+      containerId: string;
+      name?: string;
+      description?: string;
+      systemPrompt?: string;
+      mcpServers?: Record<string, unknown>;
+    };
+
+    const { imageRepository, sessionRepository } = this.runtime.provider;
+    const { createImage } = await import("@agentxjs/core/image");
+
+    const image = await createImage(
+      { containerId, name, description, systemPrompt, mcpServers: mcpServers as any },
+      { imageRepository, sessionRepository }
+    );
+
+    return ok({
+      record: image.toRecord(),
+      __subscriptions: [image.sessionId],
+    });
+  }
+
+  private async handleImageGet(params: unknown): Promise<RpcResponse> {
+    const { imageId } = params as { imageId: string };
+    const record = await this.runtime.provider.imageRepository.findImageById(imageId);
+    return ok({
+      record,
+      __subscriptions: record?.sessionId ? [record.sessionId] : undefined,
+    });
+  }
+
+  private async handleImageList(params: unknown): Promise<RpcResponse> {
+    const { containerId } = params as { containerId?: string };
+    const records = containerId
+      ? await this.runtime.provider.imageRepository.findImagesByContainerId(containerId)
+      : await this.runtime.provider.imageRepository.findAllImages();
+
+    return ok({
+      records,
+      __subscriptions: records.map((r) => r.sessionId),
+    });
+  }
+
+  private async handleImageDelete(params: unknown): Promise<RpcResponse> {
+    const { imageId } = params as { imageId: string };
+    const { loadImage } = await import("@agentxjs/core/image");
+    const { imageRepository, sessionRepository } = this.runtime.provider;
+
+    const image = await loadImage(imageId, { imageRepository, sessionRepository });
+    if (image) {
+      await image.delete();
+    }
+
+    return ok({ imageId });
+  }
+
+  private async handleImageRun(params: unknown): Promise<RpcResponse> {
+    const { imageId, agentId: requestedAgentId } = params as {
+      imageId: string;
+      agentId?: string;
+    };
+
+    // Check if already have a running agent for this image
+    const existingAgent = this.runtime
+      .getAgents()
+      .find((a) => a.imageId === imageId && a.lifecycle === "running");
+
+    if (existingAgent) {
+      logger.debug("Reusing existing agent for image", {
+        imageId,
+        agentId: existingAgent.agentId,
+      });
+      return ok({
+        imageId,
+        agentId: existingAgent.agentId,
+        sessionId: existingAgent.sessionId,
+        containerId: existingAgent.containerId,
+        reused: true,
+      });
+    }
+
+    // Create new agent (with optional custom agentId)
+    const agent = await this.runtime.createAgent({
+      imageId,
+      agentId: requestedAgentId,
+    });
+    logger.info("Created new agent for image", {
+      imageId,
+      agentId: agent.agentId,
+    });
+
+    return ok({
+      imageId,
+      agentId: agent.agentId,
+      sessionId: agent.sessionId,
+      containerId: agent.containerId,
+      reused: false,
+    });
+  }
+
+  private async handleImageStop(params: unknown): Promise<RpcResponse> {
+    const { imageId } = params as { imageId: string };
+
+    // Find running agent for this image
+    const agent = this.runtime
+      .getAgents()
+      .find((a) => a.imageId === imageId && a.lifecycle === "running");
+
+    if (agent) {
+      await this.runtime.stopAgent(agent.agentId);
+      logger.info("Stopped agent for image", { imageId, agentId: agent.agentId });
+    } else {
+      logger.debug("No running agent found for image", { imageId });
+    }
+
+    return ok({ imageId });
+  }
+
+  private async handleImageUpdate(params: unknown): Promise<RpcResponse> {
+    const { imageId, updates } = params as {
+      imageId: string;
+      updates: { name?: string; description?: string };
+    };
+
+    // Get existing image
+    const imageRecord = await this.runtime.provider.imageRepository.findImageById(imageId);
+    if (!imageRecord) {
+      return err(404, `Image not found: ${imageId}`);
+    }
+
+    // Update image record
+    const updatedRecord = {
+      ...imageRecord,
+      ...updates,
+      updatedAt: Date.now(),
+    };
+
+    await this.runtime.provider.imageRepository.saveImage(updatedRecord);
+
+    logger.info("Updated image", { imageId, updates });
+
+    return ok({ record: updatedRecord });
+  }
+
+  private async handleImageMessages(params: unknown): Promise<RpcResponse> {
+    const { imageId } = params as { imageId: string };
+
+    // Get image record to find sessionId
+    const imageRecord = await this.runtime.provider.imageRepository.findImageById(imageId);
+    if (!imageRecord) {
+      return err(404, `Image not found: ${imageId}`);
+    }
+
+    // Get messages from session
+    const messages = await this.runtime.provider.sessionRepository.getMessages(
+      imageRecord.sessionId
+    );
+
+    logger.debug("Got messages for image", { imageId, count: messages.length });
+
+    return ok({ imageId, messages });
+  }
+
+  // ==================== Agent Commands ====================
+
+  private async handleAgentGet(params: unknown): Promise<RpcResponse> {
+    const { agentId } = params as { agentId: string };
+    const agent = this.runtime.getAgent(agentId);
+
+    return ok({
+      agent: agent
+        ? {
+            agentId: agent.agentId,
+            imageId: agent.imageId,
+            containerId: agent.containerId,
+            sessionId: agent.sessionId,
+            lifecycle: agent.lifecycle,
+          }
+        : null,
+      exists: !!agent,
+    });
+  }
+
+  private async handleAgentList(params: unknown): Promise<RpcResponse> {
+    const { containerId } = params as { containerId?: string };
+    const agents = containerId
+      ? this.runtime.getAgentsByContainer(containerId)
+      : this.runtime.getAgents();
+
+    return ok({
+      agents: agents.map((a) => ({
+        agentId: a.agentId,
+        imageId: a.imageId,
+        containerId: a.containerId,
+        sessionId: a.sessionId,
+        lifecycle: a.lifecycle,
+      })),
+    });
+  }
+
+  private async handleAgentDestroy(params: unknown): Promise<RpcResponse> {
+    const { agentId } = params as { agentId: string };
+
+    // Check if agent exists first
+    const agent = this.runtime.getAgent(agentId);
+    if (!agent) {
+      return ok({ agentId, success: false });
+    }
+
+    await this.runtime.destroyAgent(agentId);
+    return ok({ agentId, success: true });
+  }
+
+  private async handleAgentDestroyAll(params: unknown): Promise<RpcResponse> {
+    const { containerId } = params as { containerId: string };
+    const agents = this.runtime.getAgentsByContainer(containerId);
+    for (const agent of agents) {
+      await this.runtime.destroyAgent(agent.agentId);
+    }
+    return ok({ containerId });
+  }
+
+  private async handleAgentInterrupt(params: unknown): Promise<RpcResponse> {
+    const { agentId } = params as { agentId: string };
+    this.runtime.interrupt(agentId);
+    return ok({ agentId });
+  }
+
+  // ==================== Message Commands ====================
+
+  private async handleMessageSend(params: unknown): Promise<RpcResponse> {
+    const { agentId, imageId, content } = params as {
+      agentId?: string;
+      imageId?: string;
+      content: string | UserContentPart[];
+    };
+
+    let targetAgentId: string;
+
+    if (agentId) {
+      // Direct agent reference
+      targetAgentId = agentId;
+    } else if (imageId) {
+      // Auto-activate image: find or create agent
+      const existingAgent = this.runtime
+        .getAgents()
+        .find((a) => a.imageId === imageId && a.lifecycle === "running");
+
+      if (existingAgent) {
+        targetAgentId = existingAgent.agentId;
+        logger.debug("Using existing agent for message", {
+          imageId,
+          agentId: targetAgentId,
+        });
+      } else {
+        // Create new agent for this image
+        const agent = await this.runtime.createAgent({ imageId });
+        targetAgentId = agent.agentId;
+        logger.info("Auto-created agent for message", {
+          imageId,
+          agentId: targetAgentId,
+        });
+      }
+    } else {
+      return err(-32602, "Either agentId or imageId is required");
+    }
+
+    await this.runtime.receive(targetAgentId, content);
+    return ok({ agentId: targetAgentId, imageId });
+  }
+
+  // ==================== Lifecycle ====================
+
+  dispose(): void {
+    logger.debug("CommandHandler disposed");
+  }
+}

package/src/Server.ts

@@ -0,0 +1,350 @@
+/**
+ * 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 { AgentXProvider } from "@agentxjs/core/runtime";
+import type { ChannelConnection } from "@agentxjs/core/network";
+import type { BusEvent, SystemEvent } from "@agentxjs/core/event";
+import { createAgentXRuntime } from "@agentxjs/core/runtime";
+import {
+  parseMessage,
+  isRequest,
+  isNotification,
+  createSuccessResponse,
+  createErrorResponse,
+  createStreamEvent,
+  RpcErrorCodes,
+  type RpcMethod,
+} from "@agentxjs/core/network";
+import {
+  WebSocketServer,
+  isDeferredProvider,
+  type DeferredProviderConfig,
+} from "@agentxjs/node-provider";
+import { createLogger } from "commonxjs/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 providers)
+ */
+export interface ServerConfig {
+  /**
+   * AgentX Provider (can be AgentXProvider or DeferredProviderConfig)
+   */
+  provider: AgentXProvider | DeferredProviderConfig;
+
+  /**
+   * 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;
+
+  // Resolve deferred provider if needed
+  const provider: AgentXProvider = isDeferredProvider(config.provider)
+    ? await config.provider.resolve()
+    : config.provider;
+
+  // Create runtime from provider
+  const runtime = createAgentXRuntime(provider);
+
+  // Create WebSocket server
+  const wsServer = new WebSocketServer({
+    heartbeat: true,
+    heartbeatInterval: 30000,
+    debug: config.debug,
+  });
+
+  // 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
+  provider.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/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @agentxjs/server
+ *
+ * AgentX Server - WebSocket server with Provider support.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from "@agentxjs/server";
+ * import { nodeProvider } from "@agentxjs/node-provider";
+ * import { claudeDriver } from "@agentxjs/claude-driver";
+ *
+ * const server = await createServer({
+ *   provider: nodeProvider({
+ *     dataPath: "./data",
+ *     driver: claudeDriver({ apiKey: process.env.ANTHROPIC_API_KEY }),
+ *   }),
+ *   port: 5200,
+ * });
+ *
+ * await server.listen();
+ * console.log("Server listening on ws://localhost:5200");
+ *
+ * // Attach to existing HTTP server
+ * import { createServer as createHttpServer } from "node:http";
+ *
+ * const httpServer = createHttpServer();
+ * const agentxServer = await createServer({
+ *   provider: nodeProvider({ ... }),
+ *   server: httpServer,
+ *   wsPath: "/ws",
+ * });
+ *
+ * httpServer.listen(3000);
+ * ```
+ */
+
+export { createServer, type ServerConfig } from "./Server";
+export type { AgentXServer } from "./types";
+export { CommandHandler } from "./CommandHandler";

package/src/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Server Types
+ */
+
+/**
+ * AgentX Server instance
+ */
+export interface AgentXServer {
+  /**
+   * Start listening (standalone mode only)
+   */
+  listen(port?: number, host?: string): Promise<void>;
+
+  /**
+   * Close server and cleanup
+   */
+  close(): Promise<void>;
+
+  /**
+   * Dispose all resources
+   */
+  dispose(): Promise<void>;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}