agentxjs 1.9.9-dev → 2.0.0

package/src/index.ts

@@ -1,82 +1,160 @@
 /**
  * agentxjs - AgentX Client SDK
  *
- * Connect to AgentX servers from Node.js and browsers.
+ * Unified entry point supporting local and remote modes.
  *
- * @example
+ * @example Local mode (embedded runtime)
  * ```typescript
  * import { createAgentX } from "agentxjs";
  *
- * // Connect to server
  * const agentx = await createAgentX({
- *   serverUrl: "ws://localhost:5200",
- *   headers: { Authorization: "Bearer sk-xxx" },
- *   context: { userId: "123", tenantId: "abc" },
- * });
- *
- * // Create container and image
- * await agentx.createContainer("my-container");
- * const { record: image } = await agentx.createImage({
- *   containerId: "my-container",
- *   name: "Assistant",
- *   systemPrompt: "You are a helpful assistant",
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ *   provider: "anthropic",
  * });
  *
- * // Create agent and send message
- * const { agentId } = await agentx.createAgent({ imageId: image.imageId });
- *
- * // Subscribe to events
- * agentx.on("text_delta", (event) => {
- *   process.stdout.write(event.data.text);
+ * 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("assistant_message", (event) => {
- *   console.log("Complete:", event.data.content);
- * });
- *
- * // Send message
- * await agentx.sendMessage(agentId, "Hello!");
- *
- * // Cleanup
- * await agentx.dispose();
+ * agentx.on("text_delta", (e) => process.stdout.write(e.data.text));
+ * await agentx.sessions.send(agentId, "Hello!");
  * ```
  *
- * @example Dynamic headers and context
+ * @example Remote mode (WebSocket client)
  * ```typescript
+ * import { createAgentX } from "agentxjs";
+ *
  * const agentx = await createAgentX({
  *   serverUrl: "ws://localhost:5200",
- *   headers: () => ({ Authorization: `Bearer ${getToken()}` }),
- *   context: async () => ({
- *     userId: await getUserId(),
- *     permissions: await getPermissions(),
- *   }),
  * });
  * ```
  */
 
 import { RemoteClient } from "./RemoteClient";
+import { LocalClient } from "./LocalClient";
 import type { AgentX, AgentXConfig } 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
  */
 export async function createAgentX(config: AgentXConfig): Promise<AgentX> {
-  const client = new RemoteClient(config);
-  await client.connect();
-  return client;
+  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)"
+  );
+}
+
+/**
+ * Resolve platform for remote mode
+ *
+ * In Node.js: auto-import node-platform to get webSocketFactory
+ * In browser: no platform needed (native WebSocket is the default)
+ */
+async function resolvePlatformForRemote(config: AgentXConfig): Promise<AgentXConfig> {
+  if (config.customPlatform?.webSocketFactory) {
+    return config;
+  }
+
+  // In browser, native WebSocket works — no platform needed
+  if (typeof globalThis !== "undefined" && (globalThis as any).window?.document !== undefined) {
+    return config;
+  }
+
+  // Node.js — auto-resolve webSocketFactory from node-platform
+  try {
+    const { createNodeWebSocket } = await import("@agentxjs/node-platform/network");
+    return {
+      ...config,
+      customPlatform: {
+        ...config.customPlatform,
+        webSocketFactory: createNodeWebSocket,
+      } as any,
+    };
+  } catch {
+    // node-platform not available, fall back to global WebSocket
+    return config;
+  }
+}
+
+/**
+ * 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),
+    });
+  }
+
+  // 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",
+        },
+      });
+    };
+  }
+
+  // Create runtime
+  const runtime = createAgentXRuntime(platform, createDriver);
+
+  return new LocalClient(runtime);
 }
 
 // Re-export types
 export type {
   AgentX,
   AgentXConfig,
+  LLMProvider,
   MaybeAsync,
   AgentInfo,
   ImageRecord,
   ContainerInfo,
+  ContainerNamespace,
+  ImageNamespace,
+  AgentNamespace,
+  SessionNamespace,
+  PresentationNamespace,
   AgentCreateResponse,
   AgentGetResponse,
   AgentListResponse,
@@ -112,4 +190,5 @@ export {
   addUserConversation,
   createInitialState,
   initialPresentationState,
+  messagesToConversations,
 } from "./presentation";

package/src/namespaces/agents.ts

@@ -0,0 +1,121 @@
+/**
+ * Agent namespace factories
+ */
+
+import type { AgentXRuntime } from "@agentxjs/core/runtime";
+import type { RpcClient, RpcMethod } from "@agentxjs/core/network";
+import type {
+  AgentNamespace,
+  AgentCreateResponse,
+  AgentGetResponse,
+  AgentListResponse,
+  BaseResponse,
+} from "../types";
+
+/**
+ * Create local agent namespace backed by embedded runtime
+ */
+export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
+  return {
+    async create(params: { imageId: string; agentId?: string }): Promise<AgentCreateResponse> {
+      // Reuse existing running agent for this image
+      const existingAgent = runtime
+        .getAgents()
+        .find((a) => a.imageId === params.imageId && a.lifecycle === "running");
+
+      if (existingAgent) {
+        return {
+          agentId: existingAgent.agentId,
+          imageId: existingAgent.imageId,
+          containerId: existingAgent.containerId,
+          sessionId: existingAgent.sessionId,
+          requestId: "",
+        };
+      }
+
+      const agent = await runtime.createAgent({
+        imageId: params.imageId,
+        agentId: params.agentId,
+      });
+
+      return {
+        agentId: agent.agentId,
+        imageId: agent.imageId,
+        containerId: agent.containerId,
+        sessionId: agent.sessionId,
+        requestId: "",
+      };
+    },
+
+    async get(agentId: string): Promise<AgentGetResponse> {
+      const agent = runtime.getAgent(agentId);
+      return {
+        agent: agent
+          ? {
+              agentId: agent.agentId,
+              imageId: agent.imageId,
+              containerId: agent.containerId,
+              sessionId: agent.sessionId,
+              lifecycle: agent.lifecycle,
+            }
+          : null,
+        exists: !!agent,
+        requestId: "",
+      };
+    },
+
+    async list(containerId?: string): Promise<AgentListResponse> {
+      const agents = containerId ? runtime.getAgentsByContainer(containerId) : runtime.getAgents();
+
+      return {
+        agents: agents.map((a) => ({
+          agentId: a.agentId,
+          imageId: a.imageId,
+          containerId: a.containerId,
+          sessionId: a.sessionId,
+          lifecycle: a.lifecycle,
+        })),
+        requestId: "",
+      };
+    },
+
+    async destroy(agentId: string): Promise<BaseResponse> {
+      const agent = runtime.getAgent(agentId);
+      if (agent) {
+        await runtime.destroyAgent(agentId);
+      }
+      return { requestId: "" };
+    },
+  };
+}
+
+/**
+ * Create remote agent namespace backed by RPC client
+ */
+export function createRemoteAgents(rpcClient: RpcClient): AgentNamespace {
+  return {
+    async create(params: { imageId: string; agentId?: string }): Promise<AgentCreateResponse> {
+      // Agent creation via image.run RPC
+      const result = await rpcClient.call<AgentCreateResponse>("image.run" as RpcMethod, {
+        imageId: params.imageId,
+        agentId: params.agentId,
+      });
+      return { ...result, requestId: "" };
+    },
+
+    async get(agentId: string): Promise<AgentGetResponse> {
+      const result = await rpcClient.call<AgentGetResponse>("agent.get", { agentId });
+      return { ...result, requestId: "" };
+    },
+
+    async list(containerId?: string): Promise<AgentListResponse> {
+      const result = await rpcClient.call<AgentListResponse>("agent.list", { containerId });
+      return { ...result, requestId: "" };
+    },
+
+    async destroy(agentId: string): Promise<BaseResponse> {
+      const result = await rpcClient.call<BaseResponse>("agent.destroy", { agentId });
+      return { ...result, requestId: "" };
+    },
+  };
+}

package/src/namespaces/containers.ts

@@ -0,0 +1,68 @@
+/**
+ * Container namespace factories
+ */
+
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import type { RpcClient } from "@agentxjs/core/network";
+import type {
+  ContainerNamespace,
+  ContainerCreateResponse,
+  ContainerGetResponse,
+  ContainerListResponse,
+} from "../types";
+
+/**
+ * Create local container namespace backed by embedded runtime
+ */
+export function createLocalContainers(platform: AgentXPlatform): ContainerNamespace {
+  return {
+    async create(containerId: string): Promise<ContainerCreateResponse> {
+      const { getOrCreateContainer } = await import("@agentxjs/core/container");
+      const { containerRepository, imageRepository, sessionRepository } = platform;
+
+      const container = await getOrCreateContainer(containerId, {
+        containerRepository,
+        imageRepository,
+        sessionRepository,
+      });
+
+      return { containerId: container.containerId, requestId: "" };
+    },
+
+    async get(containerId: string): Promise<ContainerGetResponse> {
+      const exists = await platform.containerRepository.containerExists(containerId);
+      return { containerId, exists, requestId: "" };
+    },
+
+    async list(): Promise<ContainerListResponse> {
+      const containers = await platform.containerRepository.findAllContainers();
+      return { containerIds: containers.map((c) => c.containerId), requestId: "" };
+    },
+  };
+}
+
+/**
+ * Create remote container namespace backed by RPC client
+ */
+export function createRemoteContainers(rpcClient: RpcClient): ContainerNamespace {
+  return {
+    async create(containerId: string): Promise<ContainerCreateResponse> {
+      const result = await rpcClient.call<ContainerCreateResponse>("container.create", {
+        containerId,
+      });
+      return { ...result, requestId: "" };
+    },
+
+    async get(containerId: string): Promise<ContainerGetResponse> {
+      const result = await rpcClient.call<ContainerGetResponse>("container.get", {
+        containerId,
+      });
+      return { ...result, requestId: "" };
+    },
+
+    async list(): Promise<ContainerListResponse> {
+      const result = await rpcClient.call<ContainerListResponse>("container.list", {});
+      return { ...result, requestId: "" };
+    },
+  };
+}

package/src/namespaces/images.ts

@@ -0,0 +1,180 @@
+/**
+ * Image namespace factories
+ */
+
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import type { RpcClient } from "@agentxjs/core/network";
+import type {
+  ImageNamespace,
+  ImageCreateResponse,
+  ImageGetResponse,
+  ImageListResponse,
+  ImageUpdateResponse,
+  BaseResponse,
+} from "../types";
+
+/**
+ * Create local image namespace backed by embedded runtime
+ */
+export function createLocalImages(platform: AgentXPlatform): ImageNamespace {
+  return {
+    async create(params: {
+      containerId: string;
+      name?: string;
+      description?: string;
+      systemPrompt?: string;
+      mcpServers?: Record<string, unknown>;
+      customData?: Record<string, unknown>;
+    }): Promise<ImageCreateResponse> {
+      const { imageRepository, sessionRepository } = platform;
+      const { createImage } = await import("@agentxjs/core/image");
+
+      const image = await createImage(
+        {
+          containerId: params.containerId,
+          name: params.name,
+          description: params.description,
+          systemPrompt: params.systemPrompt,
+          mcpServers: params.mcpServers as any,
+          customData: params.customData,
+        },
+        { imageRepository, sessionRepository }
+      );
+
+      return {
+        record: image.toRecord(),
+        __subscriptions: [image.sessionId],
+        requestId: "",
+      };
+    },
+
+    async get(imageId: string): Promise<ImageGetResponse> {
+      const record = await platform.imageRepository.findImageById(imageId);
+      return {
+        record,
+        __subscriptions: record?.sessionId ? [record.sessionId] : undefined,
+        requestId: "",
+      };
+    },
+
+    async list(containerId?: string): Promise<ImageListResponse> {
+      const records = containerId
+        ? await platform.imageRepository.findImagesByContainerId(containerId)
+        : await platform.imageRepository.findAllImages();
+
+      return {
+        records,
+        __subscriptions: records.map((r) => r.sessionId),
+        requestId: "",
+      };
+    },
+
+    async update(
+      imageId: string,
+      updates: {
+        name?: string;
+        description?: string;
+        customData?: Record<string, unknown>;
+      }
+    ): Promise<ImageUpdateResponse> {
+      const { loadImage } = await import("@agentxjs/core/image");
+      const { imageRepository, sessionRepository } = platform;
+
+      const image = await loadImage(imageId, { imageRepository, sessionRepository });
+      if (!image) {
+        throw new Error(`Image not found: ${imageId}`);
+      }
+
+      const updated = await image.update(updates);
+      return { record: updated.toRecord(), requestId: "" };
+    },
+
+    async delete(imageId: string): Promise<BaseResponse> {
+      const { loadImage } = await import("@agentxjs/core/image");
+      const { imageRepository, sessionRepository } = platform;
+
+      const image = await loadImage(imageId, { imageRepository, sessionRepository });
+      if (image) {
+        await image.delete();
+      }
+
+      return { requestId: "" };
+    },
+  };
+}
+
+/**
+ * Create remote image namespace backed by RPC client
+ */
+export function createRemoteImages(
+  rpcClient: RpcClient,
+  subscribeFn: (sessionId: string) => void
+): ImageNamespace {
+  return {
+    async create(params: {
+      containerId: string;
+      name?: string;
+      description?: string;
+      systemPrompt?: string;
+      mcpServers?: Record<string, unknown>;
+      customData?: Record<string, unknown>;
+    }): Promise<ImageCreateResponse> {
+      const result = await rpcClient.call<ImageCreateResponse>("image.create", params);
+
+      // Auto subscribe to session events
+      if (result.__subscriptions) {
+        for (const sessionId of result.__subscriptions) {
+          subscribeFn(sessionId);
+        }
+      }
+
+      return { ...result, requestId: "" };
+    },
+
+    async get(imageId: string): Promise<ImageGetResponse> {
+      const result = await rpcClient.call<ImageGetResponse>("image.get", { imageId });
+
+      // Auto subscribe
+      if (result.__subscriptions) {
+        for (const sessionId of result.__subscriptions) {
+          subscribeFn(sessionId);
+        }
+      }
+
+      return { ...result, requestId: "" };
+    },
+
+    async list(containerId?: string): Promise<ImageListResponse> {
+      const result = await rpcClient.call<ImageListResponse>("image.list", { containerId });
+
+      // Auto subscribe
+      if (result.__subscriptions) {
+        for (const sessionId of result.__subscriptions) {
+          subscribeFn(sessionId);
+        }
+      }
+
+      return { ...result, requestId: "" };
+    },
+
+    async update(
+      imageId: string,
+      updates: {
+        name?: string;
+        description?: string;
+        customData?: Record<string, unknown>;
+      }
+    ): Promise<ImageUpdateResponse> {
+      const result = await rpcClient.call<ImageUpdateResponse>("image.update", {
+        imageId,
+        updates,
+      });
+      return { ...result, requestId: "" };
+    },
+
+    async delete(imageId: string): Promise<BaseResponse> {
+      const result = await rpcClient.call<BaseResponse>("image.delete", { imageId });
+      return { ...result, requestId: "" };
+    },
+  };
+}

package/src/namespaces/presentations.ts

@@ -0,0 +1,22 @@
+/**
+ * Presentation namespace factory
+ *
+ * Single factory for both local and remote modes —
+ * Presentation only depends on the AgentX interface.
+ */
+
+import type { AgentX, PresentationNamespace } from "../types";
+import { Presentation, type PresentationOptions, messagesToConversations } from "../presentation";
+
+/**
+ * Create presentation namespace backed by any AgentX client
+ */
+export function createPresentations(agentx: AgentX): PresentationNamespace {
+  return {
+    async create(agentId: string, options?: PresentationOptions): Promise<Presentation> {
+      const messages = await agentx.sessions.getMessages(agentId);
+      const conversations = messagesToConversations(messages);
+      return new Presentation(agentx, agentId, options, conversations);
+    },
+  };
+}

package/src/namespaces/sessions.ts

@@ -0,0 +1,60 @@
+/**
+ * Session namespace factories (messaging)
+ */
+
+import type { AgentXRuntime } from "@agentxjs/core/runtime";
+import type { UserContentPart, Message } from "@agentxjs/core/agent";
+import type { RpcClient } from "@agentxjs/core/network";
+import type { SessionNamespace, MessageSendResponse, BaseResponse, AgentInfo } from "../types";
+
+/**
+ * Create local session namespace backed by embedded runtime
+ */
+export function createLocalSessions(runtime: AgentXRuntime): SessionNamespace {
+  return {
+    async send(agentId: string, content: string | unknown[]): Promise<MessageSendResponse> {
+      await runtime.receive(agentId, content as string | UserContentPart[]);
+      return { agentId, requestId: "" };
+    },
+
+    async interrupt(agentId: string): Promise<BaseResponse> {
+      runtime.interrupt(agentId);
+      return { requestId: "" };
+    },
+
+    async getMessages(agentId: string): Promise<Message[]> {
+      const agent = runtime.getAgent(agentId);
+      if (!agent) return [];
+      return runtime.platform.sessionRepository.getMessages(agent.sessionId);
+    },
+  };
+}
+
+/**
+ * Create remote session namespace backed by RPC client
+ */
+export function createRemoteSessions(rpcClient: RpcClient): SessionNamespace {
+  return {
+    async send(agentId: string, content: string | unknown[]): Promise<MessageSendResponse> {
+      const result = await rpcClient.call<MessageSendResponse>("message.send", {
+        agentId,
+        content,
+      });
+      return { ...result, requestId: "" };
+    },
+
+    async interrupt(agentId: string): Promise<BaseResponse> {
+      const result = await rpcClient.call<BaseResponse>("agent.interrupt", { agentId });
+      return { ...result, requestId: "" };
+    },
+
+    async getMessages(agentId: string): Promise<Message[]> {
+      const agentRes = await rpcClient.call<{ agent: AgentInfo | null }>("agent.get", { agentId });
+      if (!agentRes.agent) return [];
+      const msgRes = await rpcClient.call<{ messages: Message[] }>("image.messages", {
+        imageId: agentRes.agent.imageId,
+      });
+      return msgRes.messages ?? [];
+    },
+  };
+}