agentxjs 0.0.0-dev-20260312143810

package/src/RemoteClient.ts

@@ -0,0 +1,132 @@
+/**
+ * RemoteClient - AgentX client for remote server
+ *
+ * Uses RpcClient from @agentxjs/core/network for JSON-RPC communication.
+ * This class focuses on business logic, not protocol details.
+ */
+
+import type { AgentXError } from "@agentxjs/core/error";
+import type { BusEvent, BusEventHandler, EventBus, Unsubscribe } from "@agentxjs/core/event";
+import { EventBusImpl } from "@agentxjs/core/event";
+import { RpcClient, type RpcMethod } from "@agentxjs/core/network";
+import { createLogger } from "commonxjs/logger";
+import { createRemoteAgents } from "./namespaces/agents";
+import { createRemoteContainers } from "./namespaces/containers";
+import { createRemoteImages } from "./namespaces/images";
+import { createRemoteLLM } from "./namespaces/llm";
+import { createPresentations } from "./namespaces/presentations";
+import { createRemoteSessions } from "./namespaces/sessions";
+import type {
+  AgentNamespace,
+  AgentX,
+  ContainerNamespace,
+  ImageNamespace,
+  LLMNamespace,
+  PresentationNamespace,
+  RemoteClientConfig,
+  SessionNamespace,
+} from "./types";
+
+const logger = createLogger("agentx/RemoteClient");
+
+/**
+ * RemoteClient implementation using JSON-RPC 2.0
+ */
+export class RemoteClient implements AgentX {
+  private readonly config: RemoteClientConfig;
+  private readonly eventBus: EventBus;
+  private readonly rpcClient: RpcClient;
+
+  readonly container: ContainerNamespace;
+  readonly image: ImageNamespace;
+  readonly agent: AgentNamespace;
+  readonly session: SessionNamespace;
+  readonly presentation: PresentationNamespace;
+  readonly llm: LLMNamespace;
+
+  constructor(config: RemoteClientConfig) {
+    this.config = config;
+    this.eventBus = new EventBusImpl();
+
+    // Create RPC client (WebSocket factory from platform if available)
+    this.rpcClient = new RpcClient({
+      url: config.serverUrl,
+      createWebSocket: config.customPlatform?.channelClient,
+      timeout: config.timeout ?? 30000,
+      autoReconnect: config.autoReconnect ?? true,
+      headers: config.headers as Record<string, string> | undefined,
+      debug: false,
+    });
+
+    // Forward stream events to internal event bus
+    this.rpcClient.onStreamEvent((topic, event) => {
+      logger.debug("Received stream event", { topic, type: event.type });
+      this.eventBus.emit(event as BusEvent);
+    });
+
+    // Assemble namespaces
+    this.container = createRemoteContainers(this.rpcClient);
+    this.image = createRemoteImages(this.rpcClient, (sessionId) => this.subscribe(sessionId));
+    this.agent = createRemoteAgents(this.rpcClient);
+    this.session = createRemoteSessions(this.rpcClient);
+    this.presentation = createPresentations(this);
+    this.llm = createRemoteLLM(this.rpcClient);
+  }
+
+  // ==================== Properties ====================
+
+  get connected(): boolean {
+    return this.rpcClient.connected;
+  }
+
+  get events(): EventBus {
+    return this.eventBus;
+  }
+
+  // ==================== Connection ====================
+
+  async connect(): Promise<void> {
+    await this.rpcClient.connect();
+    logger.info("Connected to server", { url: this.config.serverUrl });
+  }
+
+  async disconnect(): Promise<void> {
+    this.rpcClient.disconnect();
+    logger.info("Disconnected from server");
+  }
+
+  async dispose(): Promise<void> {
+    this.rpcClient.dispose();
+    this.eventBus.destroy();
+    logger.info("RemoteClient disposed");
+  }
+
+  // ==================== Event Subscription ====================
+
+  on<T extends string>(type: T, handler: BusEventHandler<BusEvent & { type: T }>): Unsubscribe {
+    return this.eventBus.on(type, handler);
+  }
+
+  onAny(handler: BusEventHandler): Unsubscribe {
+    return this.eventBus.onAny(handler);
+  }
+
+  subscribe(sessionId: string): void {
+    this.rpcClient.subscribe(sessionId);
+    logger.debug("Subscribed to session", { sessionId });
+  }
+
+  // ==================== Error Handling ====================
+
+  onError(handler: (error: AgentXError) => void): Unsubscribe {
+    return this.eventBus.on("agentx_error", (event) => {
+      handler(event.data as AgentXError);
+    });
+  }
+
+  // ==================== RPC ====================
+
+  async rpc<T = unknown>(method: string, params?: unknown): Promise<T> {
+    return this.rpcClient.call<T>(method as RpcMethod, params);
+  }
+}

package/src/index.ts

@@ -0,0 +1,228 @@
+/**
+ * agentxjs - AgentX Client SDK
+ *
+ * Fluent API supporting local, remote, and server modes.
+ *
+ * @example Local mode
+ * ```typescript
+ * import { createAgentX } from "agentxjs";
+ * import { nodePlatform } from "@agentxjs/node-platform";
+ *
+ * const ax = createAgentX(nodePlatform({ createDriver }));
+ * await ax.agent.create({ imageId: "..." });
+ * ```
+ *
+ * @example Remote mode
+ * ```typescript
+ * const ax = createAgentX();
+ * const client = await ax.connect("ws://localhost:5200");
+ * ```
+ *
+ * @example Server mode
+ * ```typescript
+ * const ax = createAgentX(nodePlatform({ 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, AgentXBuilder, AgentXServer, ConnectOptions, ServeConfig } from "./types";
+
+/**
+ * Platform configuration for createAgentX
+ */
+export interface PlatformConfig {
+  platform: AgentXPlatform;
+  createDriver: CreateDriver;
+}
+
+/**
+ * Create an AgentX builder
+ *
+ * @param config - Platform configuration (optional). Without it, only connect() is available.
+ * @returns AgentXBuilder — local AgentX + connect() + serve()
+ */
+export function createAgentX(config?: PlatformConfig): AgentXBuilder {
+  let localClient: LocalClient | null = null;
+
+  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;
+  }
+
+  if (config) {
+    getLocalClient();
+  }
+
+  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;
+    },
+
+    get llm() {
+      return getLocalClient().llm;
+    },
+
+    on(type, handler) {
+      return getLocalClient().on(type, handler);
+    },
+
+    onAny(handler) {
+      return getLocalClient().onAny(handler);
+    },
+
+    subscribe(sessionId) {
+      getLocalClient().subscribe(sessionId);
+    },
+
+    onError(handler) {
+      return getLocalClient().onError(handler);
+    },
+
+    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;
+    },
+
+    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."
+        );
+      }
+
+      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,
+      });
+    },
+
+    async rpc<T = unknown>(method: string, params?: unknown): Promise<T> {
+      return getLocalClient().rpc<T>(method, params);
+    },
+  };
+}
+
+export type { AgentXErrorCategory, AgentXErrorContext } from "@agentxjs/core/error";
+// Re-export error types
+export { AgentXError, AgentXErrorCode } from "@agentxjs/core/error";
+// Re-export server
+export { CommandHandler } from "./CommandHandler";
+// Re-export Presentation types and classes
+export type {
+  AssistantConversation,
+  Block,
+  Conversation,
+  ErrorConversation,
+  ImageBlock,
+  PresentationErrorHandler,
+  PresentationOptions,
+  PresentationState,
+  PresentationUpdateHandler,
+  TextBlock,
+  ToolBlock,
+  UserConversation,
+} from "./presentation";
+export {
+  addUserConversation,
+  createInitialState,
+  initialPresentationState,
+  messagesToConversations,
+  Presentation,
+  presentationReducer,
+} from "./presentation";
+export { createServer, type ServerConfig } from "./server";
+// Re-export types
+export type {
+  AgentCreateResponse,
+  AgentGetResponse,
+  AgentInfo,
+  AgentListResponse,
+  AgentNamespace,
+  AgentX,
+  AgentXBuilder,
+  AgentXServer,
+  BaseResponse,
+  ConnectOptions,
+  ContainerCreateResponse,
+  ContainerGetResponse,
+  ContainerInfo,
+  ContainerListResponse,
+  ContainerNamespace,
+  ImageCreateResponse,
+  ImageGetResponse,
+  ImageListResponse,
+  ImageNamespace,
+  ImageRecord,
+  LLMNamespace,
+  LLMProviderCreateResponse,
+  LLMProviderDefaultResponse,
+  LLMProviderGetResponse,
+  LLMProviderListResponse,
+  LLMProviderUpdateResponse,
+  MaybeAsync,
+  MessageSendResponse,
+  PresentationNamespace,
+  ServeConfig,
+  SessionNamespace,
+} from "./types";

package/src/namespaces/agents.ts

@@ -0,0 +1,121 @@
+/**
+ * Agent namespace factories
+ */
+
+import type { RpcClient, RpcMethod } from "@agentxjs/core/network";
+import type { AgentXRuntime } from "@agentxjs/core/runtime";
+import type {
+  AgentCreateResponse,
+  AgentGetResponse,
+  AgentListResponse,
+  AgentNamespace,
+  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 { RpcClient } from "@agentxjs/core/network";
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import type {
+  ContainerCreateResponse,
+  ContainerGetResponse,
+  ContainerListResponse,
+  ContainerNamespace,
+} 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: "" };
+    },
+  };
+}