agentxjs 2.6.0 → 2.7.0

package/src/CommandHandler.ts

@@ -89,16 +89,16 @@ export class CommandHandler {
         case "image.messages":
           return await this.handleImageMessages(params);
 
-        // Agent
-        case "agent.get":
+        // Instance
+        case "instance.get":
           return await this.handleAgentGet(params);
-        case "agent.list":
+        case "instance.list":
           return await this.handleAgentList(params);
-        case "agent.destroy":
+        case "instance.destroy":
           return await this.handleAgentDestroy(params);
-        case "agent.destroyAll":
+        case "instance.destroyAll":
           return await this.handleAgentDestroyAll(params);
-        case "agent.interrupt":
+        case "instance.interrupt":
           return await this.handleAgentInterrupt(params);
 
         // Message
@@ -228,9 +228,9 @@ export class CommandHandler {
   }
 
   private async handleImageRun(params: unknown): Promise<RpcResponse> {
-    const { imageId, agentId: requestedAgentId } = params as {
+    const { imageId, instanceId: requestedInstanceId } = params as {
       imageId: string;
-      agentId?: string;
+      instanceId?: string;
     };
 
     // Check if already have a running agent for this image
@@ -241,30 +241,30 @@ export class CommandHandler {
     if (existingAgent) {
       logger.debug("Reusing existing agent for image", {
         imageId,
-        agentId: existingAgent.agentId,
+        instanceId: existingAgent.instanceId,
       });
       return ok({
         imageId,
-        agentId: existingAgent.agentId,
+        instanceId: existingAgent.instanceId,
         sessionId: existingAgent.sessionId,
         containerId: existingAgent.containerId,
         reused: true,
       });
     }
 
-    // Create new agent (with optional custom agentId)
+    // Create new agent (with optional custom instanceId)
     const agent = await this.runtime.createAgent({
       imageId,
-      agentId: requestedAgentId,
+      instanceId: requestedInstanceId,
     });
     logger.info("Created new agent for image", {
       imageId,
-      agentId: agent.agentId,
+      instanceId: agent.instanceId,
     });
 
     return ok({
       imageId,
-      agentId: agent.agentId,
+      instanceId: agent.instanceId,
       sessionId: agent.sessionId,
       containerId: agent.containerId,
       reused: false,
@@ -280,8 +280,8 @@ export class CommandHandler {
       .find((a) => a.imageId === imageId && a.lifecycle === "running");
 
     if (agent) {
-      await this.runtime.stopAgent(agent.agentId);
-      logger.info("Stopped agent for image", { imageId, agentId: agent.agentId });
+      await this.runtime.stopAgent(agent.instanceId);
+      logger.info("Stopped agent for image", { imageId, instanceId: agent.instanceId });
     } else {
       logger.debug("No running agent found for image", { imageId });
     }
@@ -344,13 +344,13 @@ export class CommandHandler {
   // ==================== Agent Commands ====================
 
   private async handleAgentGet(params: unknown): Promise<RpcResponse> {
-    const { agentId } = params as { agentId: string };
-    const agent = this.runtime.getAgent(agentId);
+    const { instanceId } = params as { instanceId: string };
+    const agent = this.runtime.getAgent(instanceId);
 
     return ok({
       agent: agent
         ? {
-            agentId: agent.agentId,
+            instanceId: agent.instanceId,
             imageId: agent.imageId,
             containerId: agent.containerId,
             sessionId: agent.sessionId,
@@ -369,7 +369,7 @@ export class CommandHandler {
 
     return ok({
       agents: agents.map((a) => ({
-        agentId: a.agentId,
+        instanceId: a.instanceId,
         imageId: a.imageId,
         containerId: a.containerId,
         sessionId: a.sessionId,
@@ -379,47 +379,47 @@ export class CommandHandler {
   }
 
   private async handleAgentDestroy(params: unknown): Promise<RpcResponse> {
-    const { agentId } = params as { agentId: string };
+    const { instanceId } = params as { instanceId: string };
 
     // Check if agent exists first
-    const agent = this.runtime.getAgent(agentId);
+    const agent = this.runtime.getAgent(instanceId);
     if (!agent) {
-      return ok({ agentId, success: false });
+      return ok({ instanceId, success: false });
     }
 
-    await this.runtime.destroyAgent(agentId);
-    return ok({ agentId, success: true });
+    await this.runtime.destroyAgent(instanceId);
+    return ok({ instanceId, success: true });
   }
 
   private async handleAgentDestroyAll(params: unknown): Promise<RpcResponse> {
     const { containerId } = params as { containerId: string };
     const agents = this.runtime.getAgentsByContainer(containerId);
     for (const agent of agents) {
-      await this.runtime.destroyAgent(agent.agentId);
+      await this.runtime.destroyAgent(agent.instanceId);
     }
     return ok({ containerId });
   }
 
   private async handleAgentInterrupt(params: unknown): Promise<RpcResponse> {
-    const { agentId } = params as { agentId: string };
-    this.runtime.interrupt(agentId);
-    return ok({ agentId });
+    const { instanceId } = params as { instanceId: string };
+    this.runtime.interrupt(instanceId);
+    return ok({ instanceId });
   }
 
   // ==================== Message Commands ====================
 
   private async handleMessageSend(params: unknown): Promise<RpcResponse> {
-    const { agentId, imageId, content } = params as {
-      agentId?: string;
+    const { instanceId, imageId, content } = params as {
+      instanceId?: string;
       imageId?: string;
       content: string | UserContentPart[];
     };
 
-    let targetAgentId: string;
+    let targetInstanceId: string;
 
-    if (agentId) {
+    if (instanceId) {
       // Direct agent reference
-      targetAgentId = agentId;
+      targetInstanceId = instanceId;
     } else if (imageId) {
       // Auto-activate image: find or create agent
       const existingAgent = this.runtime
@@ -427,26 +427,26 @@ export class CommandHandler {
         .find((a) => a.imageId === imageId && a.lifecycle === "running");
 
       if (existingAgent) {
-        targetAgentId = existingAgent.agentId;
+        targetInstanceId = existingAgent.instanceId;
         logger.debug("Using existing agent for message", {
           imageId,
-          agentId: targetAgentId,
+          instanceId: targetInstanceId,
         });
       } else {
         // Create new agent for this image
         const agent = await this.runtime.createAgent({ imageId });
-        targetAgentId = agent.agentId;
+        targetInstanceId = agent.instanceId;
         logger.info("Auto-created agent for message", {
           imageId,
-          agentId: targetAgentId,
+          instanceId: targetInstanceId,
         });
       }
     } else {
-      return err(-32602, "Either agentId or imageId is required");
+      return err(-32602, "Either instanceId or imageId is required");
     }
 
-    await this.runtime.receive(targetAgentId, content);
-    return ok({ agentId: targetAgentId, imageId });
+    await this.runtime.receive(targetInstanceId, content);
+    return ok({ instanceId: targetInstanceId, imageId });
   }
 
   // ==================== Prototype Commands ====================

package/src/LocalClient.ts

@@ -12,7 +12,7 @@ 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 { createLocalInstances } from "./namespaces/agents";
 import { createLocalContainers } from "./namespaces/containers";
 import { createLocalImages } from "./namespaces/images";
 import { createLocalLLM } from "./namespaces/llm";
@@ -48,13 +48,13 @@ export class LocalClient implements AgentX {
 
     const container = createLocalContainers(platform);
     const image = createLocalImages(platform);
-    const agent = createLocalAgents(agentxRuntime);
+    const instance = createLocalInstances(agentxRuntime);
     const session = createLocalSessions(agentxRuntime);
     const llm = createLocalLLM(platform);
     const prototype = createLocalPrototypes(platform);
-    const present = createPresentations(this, image);
+    const present = createPresentations(this, session);
 
-    this.runtime = { container, image, agent, session, present, llm, prototype };
+    this.runtime = { container, image, instance, session, present, llm, prototype };
     this.provider = llm;
     this.prototype = prototype;
     this.chat = this.createChatNamespace();
@@ -110,14 +110,14 @@ export class LocalClient implements AgentX {
   // ==================== Private ====================
 
   private createChatNamespace(): ChatNamespace {
-    const instance = this.runtime;
+    const rt = 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);
+          const protoRes = await rt.prototype.get(params.prototypeId);
           if (protoRes.record) {
             const proto = protoRes.record;
             mergedParams = {
@@ -131,33 +131,34 @@ export class LocalClient implements AgentX {
           }
         }
         const { prototypeId: _pid, ...imageParams } = mergedParams;
-        const imgRes = await instance.image.create({ containerId, ...imageParams });
-        const agentRes = await instance.agent.create({ imageId: imgRes.record.imageId });
+        const imgRes = await rt.image.create({ containerId, ...imageParams });
+        const instRes = await rt.instance.create({ imageId: imgRes.record.imageId });
         return new AgentHandleImpl(
           {
-            agentId: agentRes.agentId,
-            imageId: agentRes.imageId,
-            containerId: agentRes.containerId,
-            sessionId: agentRes.sessionId,
+            instanceId: instRes.instanceId,
+            imageId: instRes.imageId,
+            containerId: instRes.containerId,
+            sessionId: instRes.sessionId,
           },
-          instance
+          rt
         );
       },
       async list() {
-        return instance.image.list();
+        return rt.image.list();
       },
       async get(id) {
-        const res = await instance.image.get(id);
+        const res = await rt.image.get(id);
         if (!res.record) return null;
         const r = res.record;
+        const instRes = await rt.instance.create({ imageId: r.imageId });
         return new AgentHandleImpl(
           {
-            agentId: r.imageId,
-            imageId: r.imageId,
-            containerId: r.containerId,
-            sessionId: r.sessionId,
+            instanceId: instRes.instanceId,
+            imageId: instRes.imageId,
+            containerId: instRes.containerId,
+            sessionId: instRes.sessionId,
           },
-          instance
+          rt
         );
       },
     };

package/src/RemoteClient.ts

@@ -11,7 +11,7 @@ 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 { createRemoteInstances } from "./namespaces/agents";
 import { createRemoteContainers } from "./namespaces/containers";
 import { createRemoteImages } from "./namespaces/images";
 import { createRemoteLLM } from "./namespaces/llm";
@@ -65,13 +65,13 @@ export class RemoteClient implements AgentX {
     // Assemble namespaces
     const container = createRemoteContainers(this.rpcClient);
     const image = createRemoteImages(this.rpcClient, (sessionId) => this.subscribe(sessionId));
-    const agent = createRemoteAgents(this.rpcClient);
+    const instance = createRemoteInstances(this.rpcClient);
     const session = createRemoteSessions(this.rpcClient);
     const llm = createRemoteLLM(this.rpcClient);
     const prototype = createRemotePrototypes(this.rpcClient);
-    const present = createPresentations(this, image);
+    const present = createPresentations(this, session);
 
-    this.runtime = { container, image, agent, session, present, llm, prototype };
+    this.runtime = { container, image, instance, session, present, llm, prototype };
     this.provider = llm;
     this.prototype = prototype;
     this.chat = this.createChatNamespace();
@@ -137,14 +137,14 @@ export class RemoteClient implements AgentX {
   // ==================== Private ====================
 
   private createChatNamespace(): ChatNamespace {
-    const instance = this.runtime;
+    const rt = 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);
+          const protoRes = await rt.prototype.get(params.prototypeId);
           if (protoRes.record) {
             const proto = protoRes.record;
             mergedParams = {
@@ -158,33 +158,34 @@ export class RemoteClient implements AgentX {
           }
         }
         const { prototypeId: _pid, ...imageParams } = mergedParams;
-        const imgRes = await instance.image.create({ containerId, ...imageParams });
-        const agentRes = await instance.agent.create({ imageId: imgRes.record.imageId });
+        const imgRes = await rt.image.create({ containerId, ...imageParams });
+        const instRes = await rt.instance.create({ imageId: imgRes.record.imageId });
         return new AgentHandleImpl(
           {
-            agentId: agentRes.agentId,
-            imageId: agentRes.imageId,
-            containerId: agentRes.containerId,
-            sessionId: agentRes.sessionId,
+            instanceId: instRes.instanceId,
+            imageId: instRes.imageId,
+            containerId: instRes.containerId,
+            sessionId: instRes.sessionId,
           },
-          instance
+          rt
         );
       },
       async list() {
-        return instance.image.list();
+        return rt.image.list();
       },
       async get(id) {
-        const res = await instance.image.get(id);
+        const res = await rt.image.get(id);
         if (!res.record) return null;
         const r = res.record;
+        const instRes = await rt.instance.create({ imageId: r.imageId });
         return new AgentHandleImpl(
           {
-            agentId: r.imageId,
-            imageId: r.imageId,
-            containerId: r.containerId,
-            sessionId: r.sessionId,
+            instanceId: instRes.instanceId,
+            imageId: instRes.imageId,
+            containerId: instRes.containerId,
+            sessionId: instRes.sessionId,
           },
-          instance
+          rt
         );
       },
     };

package/src/index.ts

@@ -187,12 +187,7 @@ export {
 export { createServer, type ServerConfig } from "./server";
 // Re-export types
 export type {
-  AgentCreateResponse,
-  AgentGetResponse,
   AgentHandle,
-  AgentInfo,
-  AgentListResponse,
-  AgentNamespace,
   AgentX,
   AgentXBuilder,
   AgentXServer,
@@ -210,6 +205,11 @@ export type {
   ImageListResponse,
   ImageNamespace,
   ImageRecord,
+  InstanceCreateResponse,
+  InstanceGetResponse,
+  InstanceInfo,
+  InstanceListResponse,
+  InstanceNamespace,
   LLMNamespace,
   LLMProviderCreateResponse,
   LLMProviderDefaultResponse,

package/src/namespaces/agents.ts

@@ -5,19 +5,22 @@
 import type { RpcClient, RpcMethod } from "@agentxjs/core/network";
 import type { AgentXRuntime } from "@agentxjs/core/runtime";
 import type {
-  AgentCreateResponse,
-  AgentGetResponse,
-  AgentListResponse,
-  AgentNamespace,
   BaseResponse,
+  InstanceCreateResponse,
+  InstanceGetResponse,
+  InstanceListResponse,
+  InstanceNamespace,
 } from "../types";
 
 /**
  * Create local agent namespace backed by embedded runtime
  */
-export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
+export function createLocalInstances(runtime: AgentXRuntime): InstanceNamespace {
   return {
-    async create(params: { imageId: string; agentId?: string }): Promise<AgentCreateResponse> {
+    async create(params: {
+      imageId: string;
+      instanceId?: string;
+    }): Promise<InstanceCreateResponse> {
       // Reuse existing running agent for this image
       const existingAgent = runtime
         .getAgents()
@@ -25,7 +28,7 @@ export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
 
       if (existingAgent) {
         return {
-          agentId: existingAgent.agentId,
+          instanceId: existingAgent.instanceId,
           imageId: existingAgent.imageId,
           containerId: existingAgent.containerId,
           sessionId: existingAgent.sessionId,
@@ -35,11 +38,11 @@ export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
 
       const agent = await runtime.createAgent({
         imageId: params.imageId,
-        agentId: params.agentId,
+        instanceId: params.instanceId,
       });
 
       return {
-        agentId: agent.agentId,
+        instanceId: agent.instanceId,
         imageId: agent.imageId,
         containerId: agent.containerId,
         sessionId: agent.sessionId,
@@ -47,12 +50,12 @@ export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
       };
     },
 
-    async get(agentId: string): Promise<AgentGetResponse> {
-      const agent = runtime.getAgent(agentId);
+    async get(instanceId: string): Promise<InstanceGetResponse> {
+      const agent = runtime.getAgent(instanceId);
       return {
         agent: agent
           ? {
-              agentId: agent.agentId,
+              instanceId: agent.instanceId,
               imageId: agent.imageId,
               containerId: agent.containerId,
               sessionId: agent.sessionId,
@@ -64,12 +67,12 @@ export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
       };
     },
 
-    async list(containerId?: string): Promise<AgentListResponse> {
+    async list(containerId?: string): Promise<InstanceListResponse> {
       const agents = containerId ? runtime.getAgentsByContainer(containerId) : runtime.getAgents();
 
       return {
         agents: agents.map((a) => ({
-          agentId: a.agentId,
+          instanceId: a.instanceId,
           imageId: a.imageId,
           containerId: a.containerId,
           sessionId: a.sessionId,
@@ -79,10 +82,10 @@ export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
       };
     },
 
-    async destroy(agentId: string): Promise<BaseResponse> {
-      const agent = runtime.getAgent(agentId);
+    async destroy(instanceId: string): Promise<BaseResponse> {
+      const agent = runtime.getAgent(instanceId);
       if (agent) {
-        await runtime.destroyAgent(agentId);
+        await runtime.destroyAgent(instanceId);
       }
       return { requestId: "" };
     },
@@ -92,29 +95,32 @@ export function createLocalAgents(runtime: AgentXRuntime): AgentNamespace {
 /**
  * Create remote agent namespace backed by RPC client
  */
-export function createRemoteAgents(rpcClient: RpcClient): AgentNamespace {
+export function createRemoteInstances(rpcClient: RpcClient): InstanceNamespace {
   return {
-    async create(params: { imageId: string; agentId?: string }): Promise<AgentCreateResponse> {
+    async create(params: {
+      imageId: string;
+      instanceId?: string;
+    }): Promise<InstanceCreateResponse> {
       // Agent creation via image.run RPC
-      const result = await rpcClient.call<AgentCreateResponse>("image.run" as RpcMethod, {
+      const result = await rpcClient.call<InstanceCreateResponse>("image.run" as RpcMethod, {
         imageId: params.imageId,
-        agentId: params.agentId,
+        instanceId: params.instanceId,
       });
       return { ...result, requestId: "" };
     },
 
-    async get(agentId: string): Promise<AgentGetResponse> {
-      const result = await rpcClient.call<AgentGetResponse>("agent.get", { agentId });
+    async get(instanceId: string): Promise<InstanceGetResponse> {
+      const result = await rpcClient.call<InstanceGetResponse>("instance.get", { instanceId });
       return { ...result, requestId: "" };
     },
 
-    async list(containerId?: string): Promise<AgentListResponse> {
-      const result = await rpcClient.call<AgentListResponse>("agent.list", { containerId });
+    async list(containerId?: string): Promise<InstanceListResponse> {
+      const result = await rpcClient.call<InstanceListResponse>("instance.list", { containerId });
       return { ...result, requestId: "" };
     },
 
-    async destroy(agentId: string): Promise<BaseResponse> {
-      const result = await rpcClient.call<BaseResponse>("agent.destroy", { agentId });
+    async destroy(instanceId: string): Promise<BaseResponse> {
+      const result = await rpcClient.call<BaseResponse>("instance.destroy", { instanceId });
       return { ...result, requestId: "" };
     },
   };

package/src/namespaces/presentations.ts

@@ -5,23 +5,23 @@
  */
 
 import { messagesToConversations, Presentation, type PresentationOptions } from "../presentation";
-import type { AgentX, ImageNamespace, PresentationNamespace } from "../types";
+import type { AgentX, PresentationNamespace, SessionNamespace } from "../types";
 
 /**
  * Create presentation namespace.
  *
- * Takes the full AgentX (for Presentation event wiring) and the ImageNamespace
- * (for message history), avoiding circular access to `instance` during construction.
+ * Takes the full AgentX (for Presentation event wiring) and the SessionNamespace
+ * (for message history via instanceId).
  */
 export function createPresentations(
   agentx: AgentX,
-  imageNs: ImageNamespace
+  sessionNs: SessionNamespace
 ): PresentationNamespace {
   return {
-    async create(agentId: string, options?: PresentationOptions): Promise<Presentation> {
-      const messages = await imageNs.getMessages(agentId);
+    async create(instanceId: string, options?: PresentationOptions): Promise<Presentation> {
+      const messages = await sessionNs.getMessages(instanceId);
       const conversations = messagesToConversations(messages);
-      return new Presentation(agentx, agentId, options, conversations);
+      return new Presentation(agentx, instanceId, options, conversations);
     },
   };
 }

package/src/namespaces/sessions.ts

@@ -5,25 +5,25 @@
 import type { Message, UserContentPart } from "@agentxjs/core/agent";
 import type { RpcClient } from "@agentxjs/core/network";
 import type { AgentXRuntime } from "@agentxjs/core/runtime";
-import type { AgentInfo, BaseResponse, MessageSendResponse, SessionNamespace } from "../types";
+import type { BaseResponse, InstanceInfo, MessageSendResponse, SessionNamespace } 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 send(instanceId: string, content: string | unknown[]): Promise<MessageSendResponse> {
+      await runtime.receive(instanceId, content as string | UserContentPart[]);
+      return { instanceId, requestId: "" };
     },
 
-    async interrupt(agentId: string): Promise<BaseResponse> {
-      runtime.interrupt(agentId);
+    async interrupt(instanceId: string): Promise<BaseResponse> {
+      runtime.interrupt(instanceId);
       return { requestId: "" };
     },
 
-    async getMessages(agentId: string): Promise<Message[]> {
-      const agent = runtime.getAgent(agentId);
+    async getMessages(instanceId: string): Promise<Message[]> {
+      const agent = runtime.getAgent(instanceId);
       if (!agent) return [];
       return runtime.platform.sessionRepository.getMessages(agent.sessionId);
     },
@@ -35,21 +35,23 @@ export function createLocalSessions(runtime: AgentXRuntime): SessionNamespace {
  */
 export function createRemoteSessions(rpcClient: RpcClient): SessionNamespace {
   return {
-    async send(agentId: string, content: string | unknown[]): Promise<MessageSendResponse> {
+    async send(instanceId: string, content: string | unknown[]): Promise<MessageSendResponse> {
       const result = await rpcClient.call<MessageSendResponse>("message.send", {
-        agentId,
+        instanceId,
         content,
       });
       return { ...result, requestId: "" };
     },
 
-    async interrupt(agentId: string): Promise<BaseResponse> {
-      const result = await rpcClient.call<BaseResponse>("agent.interrupt", { agentId });
+    async interrupt(instanceId: string): Promise<BaseResponse> {
+      const result = await rpcClient.call<BaseResponse>("instance.interrupt", { instanceId });
       return { ...result, requestId: "" };
     },
 
-    async getMessages(agentId: string): Promise<Message[]> {
-      const agentRes = await rpcClient.call<{ agent: AgentInfo | null }>("agent.get", { agentId });
+    async getMessages(instanceId: string): Promise<Message[]> {
+      const agentRes = await rpcClient.call<{ agent: InstanceInfo | null }>("instance.get", {
+        instanceId,
+      });
       if (!agentRes.agent) return [];
       const msgRes = await rpcClient.call<{ messages: Message[] }>("image.messages", {
         imageId: agentRes.agent.imageId,