agentxjs 2.5.0 → 2.6.1

package/src/LocalClient.ts

@@ -17,14 +17,14 @@ 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 {
-  AgentHandle,
   AgentX,
-  Embodiment,
-  ImageListResponse,
-  InstanceNamespace,
+  ChatNamespace,
   LLMNamespace,
+  PrototypeNamespace,
+  RuntimeNamespace,
 } from "./types";
 
 const logger = createLogger("agentx/LocalClient");
@@ -33,26 +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 instance: InstanceNamespace;
+  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;
 
     const container = createLocalContainers(platform);
     const image = createLocalImages(platform);
-    const agent = createLocalAgents(runtime);
-    const session = createLocalSessions(runtime);
+    const agent = createLocalAgents(agentxRuntime);
+    const session = createLocalSessions(agentxRuntime);
     const llm = createLocalLLM(platform);
+    const prototype = createLocalPrototypes(platform);
     const present = createPresentations(this, image);
 
-    this.instance = { container, image, agent, session, present, llm };
+    this.runtime = { container, image, agent, session, present, llm, prototype };
     this.provider = llm;
+    this.prototype = prototype;
+    this.chat = this.createChatNamespace();
 
     logger.info("LocalClient initialized");
   }
@@ -64,59 +69,17 @@ export class LocalClient implements AgentX {
   }
 
   get events(): EventBus {
-    return this.runtime.platform.eventBus;
-  }
-
-  // ==================== Top-level Agent API ====================
-
-  async create(params: {
-    name?: string;
-    description?: string;
-    contextId?: string;
-    embody?: Embodiment;
-    customData?: Record<string, unknown>;
-  }): Promise<AgentHandle> {
-    const containerId = "default";
-    const imgRes = await this.instance.image.create({ containerId, ...params });
-    const agentRes = await this.instance.agent.create({ imageId: imgRes.record.imageId });
-    return new AgentHandleImpl(
-      {
-        agentId: agentRes.agentId,
-        imageId: agentRes.imageId,
-        containerId: agentRes.containerId,
-        sessionId: agentRes.sessionId,
-      },
-      this.instance
-    );
-  }
-
-  async list(): Promise<ImageListResponse> {
-    return this.instance.image.list();
-  }
-
-  async get(agentId: string): Promise<AgentHandle | null> {
-    const res = await this.instance.image.get(agentId);
-    if (!res.record) return null;
-    const r = res.record;
-    return new AgentHandleImpl(
-      {
-        agentId: r.imageId,
-        imageId: r.imageId,
-        containerId: r.containerId,
-        sessionId: r.sessionId,
-      },
-      this.instance
-    );
+    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 {
@@ -126,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);
     });
   }
@@ -135,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) {
@@ -144,6 +107,63 @@ 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;
+        const agentRes = await instance.agent.create({ imageId: r.imageId });
+        return new AgentHandleImpl(
+          {
+            agentId: agentRes.agentId,
+            imageId: agentRes.imageId,
+            containerId: agentRes.containerId,
+            sessionId: agentRes.sessionId,
+          },
+          instance
+        );
+      },
+    };
+  }
+
   // ==================== Lifecycle ====================
 
   async disconnect(): Promise<void> {
@@ -152,7 +172,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

@@ -16,15 +16,15 @@ 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 {
-  AgentHandle,
   AgentX,
-  Embodiment,
-  ImageListResponse,
-  InstanceNamespace,
+  ChatNamespace,
   LLMNamespace,
+  PrototypeNamespace,
   RemoteClientConfig,
+  RuntimeNamespace,
 } from "./types";
 
 const logger = createLogger("agentx/RemoteClient");
@@ -37,8 +37,10 @@ export class RemoteClient implements AgentX {
   private readonly eventBus: EventBus;
   private readonly rpcClient: RpcClient;
 
-  readonly instance: InstanceNamespace;
+  readonly chat: ChatNamespace;
+  readonly runtime: RuntimeNamespace;
   readonly provider: LLMNamespace;
+  readonly prototype: PrototypeNamespace;
 
   constructor(config: RemoteClientConfig) {
     this.config = config;
@@ -66,10 +68,13 @@ export class RemoteClient implements AgentX {
     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.instance = { container, image, agent, session, present, llm };
+    this.runtime = { container, image, agent, session, present, llm, prototype };
     this.provider = llm;
+    this.prototype = prototype;
+    this.chat = this.createChatNamespace();
   }
 
   // ==================== Properties ====================
@@ -82,48 +87,6 @@ export class RemoteClient implements AgentX {
     return this.eventBus;
   }
 
-  // ==================== Top-level Agent API ====================
-
-  async create(params: {
-    name?: string;
-    description?: string;
-    contextId?: string;
-    embody?: Embodiment;
-    customData?: Record<string, unknown>;
-  }): Promise<AgentHandle> {
-    const containerId = "default";
-    const imgRes = await this.instance.image.create({ containerId, ...params });
-    const agentRes = await this.instance.agent.create({ imageId: imgRes.record.imageId });
-    return new AgentHandleImpl(
-      {
-        agentId: agentRes.agentId,
-        imageId: agentRes.imageId,
-        containerId: agentRes.containerId,
-        sessionId: agentRes.sessionId,
-      },
-      this.instance
-    );
-  }
-
-  async list(): Promise<ImageListResponse> {
-    return this.instance.image.list();
-  }
-
-  async get(agentId: string): Promise<AgentHandle | null> {
-    const res = await this.instance.image.get(agentId);
-    if (!res.record) return null;
-    const r = res.record;
-    return new AgentHandleImpl(
-      {
-        agentId: r.imageId,
-        imageId: r.imageId,
-        containerId: r.containerId,
-        sessionId: r.sessionId,
-      },
-      this.instance
-    );
-  }
-
   // ==================== Connection ====================
 
   async connect(): Promise<void> {
@@ -170,4 +133,61 @@ 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;
+        const agentRes = await instance.agent.create({ imageId: r.imageId });
+        return new AgentHandleImpl(
+          {
+            agentId: agentRes.agentId,
+            imageId: agentRes.imageId,
+            containerId: agentRes.containerId,
+            sessionId: agentRes.sessionId,
+          },
+          instance
+        );
+      },
+    };
+  }
 }

package/src/index.ts

@@ -9,7 +9,7 @@
  * import { nodePlatform } from "@agentxjs/node-platform";
  *
  * const ax = createAgentX(nodePlatform({ createDriver }));
- * const agent = await ax.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * const agent = await ax.chat.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
  * await agent.send("Hello!");
  * ```
  *
@@ -75,18 +75,21 @@ export function createAgentX(config?: PlatformConfig): AgentXBuilder {
       return getLocalClient().events;
     },
 
-    get instance() {
-      return getLocalClient().instance;
+    get runtime() {
+      return getLocalClient().runtime;
     },
 
     get provider() {
       return getLocalClient().provider;
     },
 
-    // Top-level Agent API
-    create: (params) => getLocalClient().create(params),
-    list: () => getLocalClient().list(),
-    get: (agentId) => getLocalClient().get(agentId),
+    get chat() {
+      return getLocalClient().chat;
+    },
+
+    get prototype() {
+      return getLocalClient().prototype;
+    },
 
     on(type, handler) {
       return getLocalClient().on(type, handler);
@@ -194,6 +197,7 @@ export type {
   AgentXBuilder,
   AgentXServer,
   BaseResponse,
+  ChatNamespace,
   ConnectOptions,
   ContainerCreateResponse,
   ContainerGetResponse,
@@ -206,7 +210,6 @@ export type {
   ImageListResponse,
   ImageNamespace,
   ImageRecord,
-  InstanceNamespace,
   LLMNamespace,
   LLMProviderCreateResponse,
   LLMProviderDefaultResponse,
@@ -216,6 +219,12 @@ export type {
   MaybeAsync,
   MessageSendResponse,
   PresentationNamespace,
+  PrototypeCreateResponse,
+  PrototypeGetResponse,
+  PrototypeListResponse,
+  PrototypeNamespace,
+  PrototypeUpdateResponse,
+  RuntimeNamespace,
   ServeConfig,
   SessionNamespace,
 } from "./types";

package/src/namespaces/prototypes.ts

@@ -0,0 +1,136 @@
+/**
+ * Prototype namespace factories
+ */
+
+import type { RpcClient } from "@agentxjs/core/network";
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import type {
+  BaseResponse,
+  PrototypeCreateResponse,
+  PrototypeGetResponse,
+  PrototypeListResponse,
+  PrototypeNamespace,
+  PrototypeUpdateResponse,
+} from "../types";
+
+/**
+ * Create local prototype namespace backed by embedded runtime
+ */
+export function createLocalPrototypes(platform: AgentXPlatform): PrototypeNamespace {
+  return {
+    async create(params): Promise<PrototypeCreateResponse> {
+      const repo = platform.prototypeRepository;
+      if (!repo) {
+        throw new Error("Prototype repository not available");
+      }
+
+      const now = Date.now();
+      const random = Math.random().toString(36).slice(2, 8);
+      const record = {
+        prototypeId: `proto_${now}_${random}`,
+        containerId: params.containerId,
+        name: params.name,
+        description: params.description,
+        contextId: params.contextId,
+        embody: params.embody,
+        customData: params.customData,
+        createdAt: now,
+        updatedAt: now,
+      };
+
+      await repo.savePrototype(record);
+      return { record, requestId: "" };
+    },
+
+    async get(prototypeId: string): Promise<PrototypeGetResponse> {
+      const repo = platform.prototypeRepository;
+      if (!repo) {
+        throw new Error("Prototype repository not available");
+      }
+
+      const record = await repo.findPrototypeById(prototypeId);
+      return { record, requestId: "" };
+    },
+
+    async list(containerId?: string): Promise<PrototypeListResponse> {
+      const repo = platform.prototypeRepository;
+      if (!repo) {
+        throw new Error("Prototype repository not available");
+      }
+
+      const records = containerId
+        ? await repo.findPrototypesByContainerId(containerId)
+        : await repo.findAllPrototypes();
+
+      return { records, requestId: "" };
+    },
+
+    async update(prototypeId, updates): Promise<PrototypeUpdateResponse> {
+      const repo = platform.prototypeRepository;
+      if (!repo) {
+        throw new Error("Prototype repository not available");
+      }
+
+      const existing = await repo.findPrototypeById(prototypeId);
+      if (!existing) {
+        throw new Error(`Prototype not found: ${prototypeId}`);
+      }
+
+      const { embody: embodyUpdates, ...otherUpdates } = updates;
+      const updatedRecord = {
+        ...existing,
+        ...otherUpdates,
+        embody: embodyUpdates ? { ...existing.embody, ...embodyUpdates } : existing.embody,
+        updatedAt: Date.now(),
+      };
+
+      await repo.savePrototype(updatedRecord);
+      return { record: updatedRecord, requestId: "" };
+    },
+
+    async delete(prototypeId: string): Promise<BaseResponse> {
+      const repo = platform.prototypeRepository;
+      if (!repo) {
+        throw new Error("Prototype repository not available");
+      }
+
+      await repo.deletePrototype(prototypeId);
+      return { requestId: "" };
+    },
+  };
+}
+
+/**
+ * Create remote prototype namespace backed by RPC client
+ */
+export function createRemotePrototypes(rpcClient: RpcClient): PrototypeNamespace {
+  return {
+    async create(params): Promise<PrototypeCreateResponse> {
+      const result = await rpcClient.call<PrototypeCreateResponse>("prototype.create", params);
+      return { ...result, requestId: "" };
+    },
+
+    async get(prototypeId: string): Promise<PrototypeGetResponse> {
+      const result = await rpcClient.call<PrototypeGetResponse>("prototype.get", { prototypeId });
+      return { ...result, requestId: "" };
+    },
+
+    async list(containerId?: string): Promise<PrototypeListResponse> {
+      const result = await rpcClient.call<PrototypeListResponse>("prototype.list", { containerId });
+      return { ...result, requestId: "" };
+    },
+
+    async update(prototypeId, updates): Promise<PrototypeUpdateResponse> {
+      const result = await rpcClient.call<PrototypeUpdateResponse>("prototype.update", {
+        prototypeId,
+        updates,
+      });
+      return { ...result, requestId: "" };
+    },
+
+    async delete(prototypeId: string): Promise<BaseResponse> {
+      const result = await rpcClient.call<BaseResponse>("prototype.delete", { prototypeId });
+      return { ...result, requestId: "" };
+    },
+  };
+}

package/src/presentation/Presentation.ts

@@ -110,7 +110,7 @@ export class Presentation {
 
     try {
       // Send message via agentx
-      await this.agentx.instance.session.send(this.agentId, content);
+      await this.agentx.runtime.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.instance.session.interrupt(this.agentId);
+      await this.agentx.runtime.session.interrupt(this.agentId);
     } catch (error) {
       this.notifyError(error instanceof Error ? error : new Error(String(error)));
     }