agentxjs 2.4.0 → 2.6.0

package/src/CommandHandler.ts

@@ -105,6 +105,18 @@ export class CommandHandler {
         case "message.send":
           return await this.handleMessageSend(params);
 
+        // Prototype
+        case "prototype.create":
+          return await this.handlePrototypeCreate(params);
+        case "prototype.get":
+          return await this.handlePrototypeGet(params);
+        case "prototype.list":
+          return await this.handlePrototypeList(params);
+        case "prototype.update":
+          return await this.handlePrototypeUpdate(params);
+        case "prototype.delete":
+          return await this.handlePrototypeDelete(params);
+
         // LLM Provider
         case "llm.create":
           return await this.handleLLMCreate(params);
@@ -158,12 +170,12 @@ export class CommandHandler {
   // ==================== Image Commands ====================
 
   private async handleImageCreate(params: unknown): Promise<RpcResponse> {
-    const { containerId, name, description, systemPrompt, mcpServers, customData } = params as {
+    const { containerId, name, description, contextId, embody, customData } = params as {
       containerId: string;
       name?: string;
       description?: string;
-      systemPrompt?: string;
-      mcpServers?: Record<string, unknown>;
+      contextId?: string;
+      embody?: import("@agentxjs/core/persistence").Embodiment;
       customData?: Record<string, unknown>;
     };
 
@@ -171,7 +183,7 @@ export class CommandHandler {
     const { createImage } = await import("@agentxjs/core/image");
 
     const image = await createImage(
-      { containerId, name, description, systemPrompt, mcpServers: mcpServers as any, customData },
+      { containerId, name, description, contextId, embody, customData },
       { imageRepository, sessionRepository }
     );
 
@@ -280,7 +292,12 @@ export class CommandHandler {
   private async handleImageUpdate(params: unknown): Promise<RpcResponse> {
     const { imageId, updates } = params as {
       imageId: string;
-      updates: { name?: string; description?: string; customData?: Record<string, unknown> };
+      updates: {
+        name?: string;
+        description?: string;
+        embody?: import("@agentxjs/core/persistence").Embodiment;
+        customData?: Record<string, unknown>;
+      };
     };
 
     // Get existing image
@@ -289,10 +306,12 @@ export class CommandHandler {
       return err(404, `Image not found: ${imageId}`);
     }
 
-    // Update image record
+    // Update image record (embody is merged, not replaced)
+    const { embody: embodyUpdates, ...otherUpdates } = updates;
     const updatedRecord = {
       ...imageRecord,
-      ...updates,
+      ...otherUpdates,
+      embody: embodyUpdates ? { ...imageRecord.embody, ...embodyUpdates } : imageRecord.embody,
       updatedAt: Date.now(),
     };
 
@@ -430,6 +449,111 @@ export class CommandHandler {
     return ok({ agentId: targetAgentId, imageId });
   }
 
+  // ==================== Prototype Commands ====================
+
+  private async handlePrototypeCreate(params: unknown): Promise<RpcResponse> {
+    const { containerId, name, description, contextId, embody, customData } = params as {
+      containerId: string;
+      name: string;
+      description?: string;
+      contextId?: string;
+      embody?: import("@agentxjs/core/persistence").Embodiment;
+      customData?: Record<string, unknown>;
+    };
+
+    const repo = this.runtime.platform.prototypeRepository;
+    if (!repo) {
+      return err(-32000, "Prototype repository not available");
+    }
+
+    const now = Date.now();
+    const random = Math.random().toString(36).slice(2, 8);
+    const record = {
+      prototypeId: `proto_${now}_${random}`,
+      containerId,
+      name,
+      description,
+      contextId,
+      embody,
+      customData,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await repo.savePrototype(record);
+    return ok({ record });
+  }
+
+  private async handlePrototypeGet(params: unknown): Promise<RpcResponse> {
+    const { prototypeId } = params as { prototypeId: string };
+    const repo = this.runtime.platform.prototypeRepository;
+    if (!repo) {
+      return err(-32000, "Prototype repository not available");
+    }
+
+    const record = await repo.findPrototypeById(prototypeId);
+    return ok({ record });
+  }
+
+  private async handlePrototypeList(params: unknown): Promise<RpcResponse> {
+    const { containerId } = params as { containerId?: string };
+    const repo = this.runtime.platform.prototypeRepository;
+    if (!repo) {
+      return err(-32000, "Prototype repository not available");
+    }
+
+    const records = containerId
+      ? await repo.findPrototypesByContainerId(containerId)
+      : await repo.findAllPrototypes();
+
+    return ok({ records });
+  }
+
+  private async handlePrototypeUpdate(params: unknown): Promise<RpcResponse> {
+    const { prototypeId, updates } = params as {
+      prototypeId: string;
+      updates: {
+        name?: string;
+        description?: string;
+        contextId?: string;
+        embody?: import("@agentxjs/core/persistence").Embodiment;
+        customData?: Record<string, unknown>;
+      };
+    };
+
+    const repo = this.runtime.platform.prototypeRepository;
+    if (!repo) {
+      return err(-32000, "Prototype repository not available");
+    }
+
+    const existing = await repo.findPrototypeById(prototypeId);
+    if (!existing) {
+      return err(404, `Prototype not found: ${prototypeId}`);
+    }
+
+    const { embody: embodyUpdates, ...otherUpdates } = updates;
+    const updated = {
+      ...existing,
+      ...otherUpdates,
+      embody: embodyUpdates ? { ...existing.embody, ...embodyUpdates } : existing.embody,
+      updatedAt: Date.now(),
+    };
+
+    await repo.savePrototype(updated);
+    return ok({ record: updated });
+  }
+
+  private async handlePrototypeDelete(params: unknown): Promise<RpcResponse> {
+    const { prototypeId } = params as { prototypeId: string };
+    const repo = this.runtime.platform.prototypeRepository;
+    if (!repo) {
+      return err(-32000, "Prototype repository not available");
+    }
+
+    await repo.deletePrototype(prototypeId);
+    return ok({ prototypeId });
+  }
+
   // ==================== LLM Provider Commands ====================
 
   private async handleLLMCreate(params: unknown): Promise<RpcResponse> {

package/src/LocalClient.ts

@@ -10,21 +10,21 @@ import type { BusEvent, BusEventHandler, EventBus, Unsubscribe } from "@agentxjs
 import type { RpcMethod } from "@agentxjs/core/network";
 import type { AgentXRuntime } from "@agentxjs/core/runtime";
 import { createLogger } from "commonxjs/logger";
+import { AgentHandleImpl } from "./AgentHandle";
 import { CommandHandler } from "./CommandHandler";
 import { createLocalAgents } from "./namespaces/agents";
 import { createLocalContainers } from "./namespaces/containers";
 import { createLocalImages } from "./namespaces/images";
 import { createLocalLLM } from "./namespaces/llm";
 import { createPresentations } from "./namespaces/presentations";
+import { createLocalPrototypes } from "./namespaces/prototypes";
 import { createLocalSessions } from "./namespaces/sessions";
 import type {
-  AgentNamespace,
   AgentX,
-  ContainerNamespace,
-  ImageNamespace,
+  ChatNamespace,
   LLMNamespace,
-  PresentationNamespace,
-  SessionNamespace,
+  PrototypeNamespace,
+  RuntimeNamespace,
 } from "./types";
 
 const logger = createLogger("agentx/LocalClient");
@@ -33,27 +33,31 @@ const logger = createLogger("agentx/LocalClient");
  * LocalClient - Embedded runtime implementation
  */
 export class LocalClient implements AgentX {
-  private readonly runtime: AgentXRuntime;
+  private readonly _runtime: AgentXRuntime;
   private commandHandler: CommandHandler | null = null;
   private isDisposed = false;
 
-  readonly container: ContainerNamespace;
-  readonly image: ImageNamespace;
-  readonly agent: AgentNamespace;
-  readonly session: SessionNamespace;
-  readonly presentation: PresentationNamespace;
-  readonly llm: LLMNamespace;
+  readonly chat: ChatNamespace;
+  readonly runtime: RuntimeNamespace;
+  readonly provider: LLMNamespace;
+  readonly prototype: PrototypeNamespace;
 
-  constructor(runtime: AgentXRuntime) {
-    this.runtime = runtime;
-    const platform = runtime.platform;
+  constructor(agentxRuntime: AgentXRuntime) {
+    this._runtime = agentxRuntime;
+    const platform = agentxRuntime.platform;
 
-    this.container = createLocalContainers(platform);
-    this.image = createLocalImages(platform);
-    this.agent = createLocalAgents(runtime);
-    this.session = createLocalSessions(runtime);
-    this.presentation = createPresentations(this);
-    this.llm = createLocalLLM(platform);
+    const container = createLocalContainers(platform);
+    const image = createLocalImages(platform);
+    const agent = createLocalAgents(agentxRuntime);
+    const session = createLocalSessions(agentxRuntime);
+    const llm = createLocalLLM(platform);
+    const prototype = createLocalPrototypes(platform);
+    const present = createPresentations(this, image);
+
+    this.runtime = { container, image, agent, session, present, llm, prototype };
+    this.provider = llm;
+    this.prototype = prototype;
+    this.chat = this.createChatNamespace();
 
     logger.info("LocalClient initialized");
   }
@@ -65,17 +69,17 @@ export class LocalClient implements AgentX {
   }
 
   get events(): EventBus {
-    return this.runtime.platform.eventBus;
+    return this._runtime.platform.eventBus;
   }
 
   // ==================== Event Subscription ====================
 
   on<T extends string>(type: T, handler: BusEventHandler<BusEvent & { type: T }>): Unsubscribe {
-    return this.runtime.platform.eventBus.on(type, handler);
+    return this._runtime.platform.eventBus.on(type, handler);
   }
 
   onAny(handler: BusEventHandler): Unsubscribe {
-    return this.runtime.platform.eventBus.onAny(handler);
+    return this._runtime.platform.eventBus.onAny(handler);
   }
 
   subscribe(_sessionId: string): void {
@@ -85,7 +89,7 @@ export class LocalClient implements AgentX {
   // ==================== Error Handling ====================
 
   onError(handler: (error: AgentXError) => void): Unsubscribe {
-    return this.runtime.platform.eventBus.on("agentx_error", (event) => {
+    return this._runtime.platform.eventBus.on("agentx_error", (event) => {
       handler(event.data as AgentXError);
     });
   }
@@ -94,7 +98,7 @@ export class LocalClient implements AgentX {
 
   async rpc<T = unknown>(method: string, params?: unknown): Promise<T> {
     if (!this.commandHandler) {
-      this.commandHandler = new CommandHandler(this.runtime);
+      this.commandHandler = new CommandHandler(this._runtime);
     }
     const result = await this.commandHandler.handle(method as RpcMethod, params);
     if (result.success) {
@@ -103,6 +107,62 @@ export class LocalClient implements AgentX {
     throw new Error(result.message);
   }
 
+  // ==================== Private ====================
+
+  private createChatNamespace(): ChatNamespace {
+    const instance = this.runtime;
+    return {
+      async create(params) {
+        const containerId = "default";
+        // If prototypeId is provided, merge prototype config into params
+        let mergedParams = { ...params };
+        if (params.prototypeId) {
+          const protoRes = await instance.prototype.get(params.prototypeId);
+          if (protoRes.record) {
+            const proto = protoRes.record;
+            mergedParams = {
+              name: proto.name,
+              description: proto.description,
+              contextId: proto.contextId,
+              embody: proto.embody,
+              customData: proto.customData,
+              ...params, // inline params override prototype
+            };
+          }
+        }
+        const { prototypeId: _pid, ...imageParams } = mergedParams;
+        const imgRes = await instance.image.create({ containerId, ...imageParams });
+        const agentRes = await instance.agent.create({ imageId: imgRes.record.imageId });
+        return new AgentHandleImpl(
+          {
+            agentId: agentRes.agentId,
+            imageId: agentRes.imageId,
+            containerId: agentRes.containerId,
+            sessionId: agentRes.sessionId,
+          },
+          instance
+        );
+      },
+      async list() {
+        return instance.image.list();
+      },
+      async get(id) {
+        const res = await instance.image.get(id);
+        if (!res.record) return null;
+        const r = res.record;
+        return new AgentHandleImpl(
+          {
+            agentId: r.imageId,
+            imageId: r.imageId,
+            containerId: r.containerId,
+            sessionId: r.sessionId,
+          },
+          instance
+        );
+      },
+    };
+  }
+
   // ==================== Lifecycle ====================
 
   async disconnect(): Promise<void> {
@@ -111,7 +171,7 @@ export class LocalClient implements AgentX {
 
   async dispose(): Promise<void> {
     if (this.isDisposed) return;
-    await this.runtime.shutdown();
+    await this._runtime.shutdown();
     this.isDisposed = true;
     logger.info("LocalClient disposed");
   }

package/src/RemoteClient.ts

@@ -10,21 +10,21 @@ import type { BusEvent, BusEventHandler, EventBus, Unsubscribe } from "@agentxjs
 import { EventBusImpl } from "@agentxjs/core/event";
 import { RpcClient, type RpcMethod } from "@agentxjs/core/network";
 import { createLogger } from "commonxjs/logger";
+import { AgentHandleImpl } from "./AgentHandle";
 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 { createRemotePrototypes } from "./namespaces/prototypes";
 import { createRemoteSessions } from "./namespaces/sessions";
 import type {
-  AgentNamespace,
   AgentX,
-  ContainerNamespace,
-  ImageNamespace,
+  ChatNamespace,
   LLMNamespace,
-  PresentationNamespace,
+  PrototypeNamespace,
   RemoteClientConfig,
-  SessionNamespace,
+  RuntimeNamespace,
 } from "./types";
 
 const logger = createLogger("agentx/RemoteClient");
@@ -37,12 +37,10 @@ export class RemoteClient implements AgentX {
   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;
+  readonly chat: ChatNamespace;
+  readonly runtime: RuntimeNamespace;
+  readonly provider: LLMNamespace;
+  readonly prototype: PrototypeNamespace;
 
   constructor(config: RemoteClientConfig) {
     this.config = config;
@@ -65,12 +63,18 @@ export class RemoteClient implements AgentX {
     });
 
     // 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);
+    const container = createRemoteContainers(this.rpcClient);
+    const image = createRemoteImages(this.rpcClient, (sessionId) => this.subscribe(sessionId));
+    const agent = createRemoteAgents(this.rpcClient);
+    const session = createRemoteSessions(this.rpcClient);
+    const llm = createRemoteLLM(this.rpcClient);
+    const prototype = createRemotePrototypes(this.rpcClient);
+    const present = createPresentations(this, image);
+
+    this.runtime = { container, image, agent, session, present, llm, prototype };
+    this.provider = llm;
+    this.prototype = prototype;
+    this.chat = this.createChatNamespace();
   }
 
   // ==================== Properties ====================
@@ -129,4 +133,60 @@ export class RemoteClient implements AgentX {
   async rpc<T = unknown>(method: string, params?: unknown): Promise<T> {
     return this.rpcClient.call<T>(method as RpcMethod, params);
   }
+
+  // ==================== Private ====================
+
+  private createChatNamespace(): ChatNamespace {
+    const instance = this.runtime;
+    return {
+      async create(params) {
+        const containerId = "default";
+        // If prototypeId is provided, merge prototype config into params
+        let mergedParams = { ...params };
+        if (params.prototypeId) {
+          const protoRes = await instance.prototype.get(params.prototypeId);
+          if (protoRes.record) {
+            const proto = protoRes.record;
+            mergedParams = {
+              name: proto.name,
+              description: proto.description,
+              contextId: proto.contextId,
+              embody: proto.embody,
+              customData: proto.customData,
+              ...params, // inline params override prototype
+            };
+          }
+        }
+        const { prototypeId: _pid, ...imageParams } = mergedParams;
+        const imgRes = await instance.image.create({ containerId, ...imageParams });
+        const agentRes = await instance.agent.create({ imageId: imgRes.record.imageId });
+        return new AgentHandleImpl(
+          {
+            agentId: agentRes.agentId,
+            imageId: agentRes.imageId,
+            containerId: agentRes.containerId,
+            sessionId: agentRes.sessionId,
+          },
+          instance
+        );
+      },
+      async list() {
+        return instance.image.list();
+      },
+      async get(id) {
+        const res = await instance.image.get(id);
+        if (!res.record) return null;
+        const r = res.record;
+        return new AgentHandleImpl(
+          {
+            agentId: r.imageId,
+            imageId: r.imageId,
+            containerId: r.containerId,
+            sessionId: r.sessionId,
+          },
+          instance
+        );
+      },
+    };
+  }
 }

package/src/index.ts

@@ -9,7 +9,8 @@
  * import { nodePlatform } from "@agentxjs/node-platform";
  *
  * const ax = createAgentX(nodePlatform({ createDriver }));
- * await ax.agent.create({ imageId: "..." });
+ * const agent = await ax.chat.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * await agent.send("Hello!");
  * ```
  *
  * @example Remote mode
@@ -74,28 +75,20 @@ export function createAgentX(config?: PlatformConfig): AgentXBuilder {
       return getLocalClient().events;
     },
 
-    get container() {
-      return getLocalClient().container;
+    get runtime() {
+      return getLocalClient().runtime;
     },
 
-    get image() {
-      return getLocalClient().image;
+    get provider() {
+      return getLocalClient().provider;
     },
 
-    get agent() {
-      return getLocalClient().agent;
+    get chat() {
+      return getLocalClient().chat;
     },
 
-    get session() {
-      return getLocalClient().session;
-    },
-
-    get presentation() {
-      return getLocalClient().presentation;
-    },
-
-    get llm() {
-      return getLocalClient().llm;
+    get prototype() {
+      return getLocalClient().prototype;
     },
 
     on(type, handler) {
@@ -196,6 +189,7 @@ export { createServer, type ServerConfig } from "./server";
 export type {
   AgentCreateResponse,
   AgentGetResponse,
+  AgentHandle,
   AgentInfo,
   AgentListResponse,
   AgentNamespace,
@@ -203,12 +197,14 @@ export type {
   AgentXBuilder,
   AgentXServer,
   BaseResponse,
+  ChatNamespace,
   ConnectOptions,
   ContainerCreateResponse,
   ContainerGetResponse,
   ContainerInfo,
   ContainerListResponse,
   ContainerNamespace,
+  Embodiment,
   ImageCreateResponse,
   ImageGetResponse,
   ImageListResponse,
@@ -223,6 +219,12 @@ export type {
   MaybeAsync,
   MessageSendResponse,
   PresentationNamespace,
+  PrototypeCreateResponse,
+  PrototypeGetResponse,
+  PrototypeListResponse,
+  PrototypeNamespace,
+  PrototypeUpdateResponse,
+  RuntimeNamespace,
   ServeConfig,
   SessionNamespace,
 } from "./types";

package/src/namespaces/presentations.ts

@@ -1,20 +1,25 @@
 /**
  * Presentation namespace factory
  *
- * Single factory for both local and remote modes —
- * Presentation only depends on the AgentX interface.
+ * Single factory for both local and remote modes.
  */
 
 import { messagesToConversations, Presentation, type PresentationOptions } from "../presentation";
-import type { AgentX, PresentationNamespace } from "../types";
+import type { AgentX, ImageNamespace, PresentationNamespace } from "../types";
 
 /**
- * Create presentation namespace backed by any AgentX client
+ * Create presentation namespace.
+ *
+ * Takes the full AgentX (for Presentation event wiring) and the ImageNamespace
+ * (for message history), avoiding circular access to `instance` during construction.
  */
-export function createPresentations(agentx: AgentX): PresentationNamespace {
+export function createPresentations(
+  agentx: AgentX,
+  imageNs: ImageNamespace
+): PresentationNamespace {
   return {
     async create(agentId: string, options?: PresentationOptions): Promise<Presentation> {
-      const messages = await agentx.session.getMessages(agentId);
+      const messages = await imageNs.getMessages(agentId);
       const conversations = messagesToConversations(messages);
       return new Presentation(agentx, agentId, options, conversations);
     },