agentxjs 2.0.3 → 2.0.5

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/images.ts

@@ -2,6 +2,7 @@
  * Image namespace factories
  */
 
+import type { Message } from "@agentxjs/core/agent";
 import type { RpcClient } from "@agentxjs/core/network";
 import type { AgentXPlatform } from "@agentxjs/core/runtime";
 import type {
@@ -100,6 +101,12 @@ export function createLocalImages(platform: AgentXPlatform): ImageNamespace {
 
       return { requestId: "" };
     },
+
+    async getMessages(imageId: string): Promise<Message[]> {
+      const imageRecord = await platform.imageRepository.findImageById(imageId);
+      if (!imageRecord) return [];
+      return platform.sessionRepository.getMessages(imageRecord.sessionId);
+    },
   };
 }
 
@@ -176,5 +183,10 @@ export function createRemoteImages(
       const result = await rpcClient.call<BaseResponse>("image.delete", { imageId });
       return { ...result, requestId: "" };
     },
+
+    async getMessages(imageId: string): Promise<Message[]> {
+      const result = await rpcClient.call<{ messages: Message[] }>("image.messages", { imageId });
+      return result.messages ?? [];
+    },
   };
 }

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)));
     }