agentxjs 2.6.1 → 2.8.0

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,

package/src/presentation/Presentation.ts

@@ -41,7 +41,7 @@ export interface PresentationOptions {
  */
 export class Presentation {
   private agentx: AgentX;
-  private agentId: string;
+  private instanceId: string;
   private state: PresentationState;
   private updateHandlers: Set<PresentationUpdateHandler> = new Set();
   private errorHandlers: Set<PresentationErrorHandler> = new Set();
@@ -49,12 +49,12 @@ export class Presentation {
 
   constructor(
     agentx: AgentX,
-    agentId: string,
+    instanceId: string,
     options?: PresentationOptions,
     initialConversations?: Conversation[]
   ) {
     this.agentx = agentx;
-    this.agentId = agentId;
+    this.instanceId = instanceId;
     this.state = initialConversations?.length
       ? { ...initialPresentationState, conversations: initialConversations }
       : createInitialState();
@@ -110,7 +110,7 @@ export class Presentation {
 
     try {
       // Send message via agentx
-      await this.agentx.runtime.session.send(this.agentId, content);
+      await this.agentx.runtime.session.send(this.instanceId, 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.runtime.session.interrupt(this.agentId);
+      await this.agentx.runtime.session.interrupt(this.instanceId);
     } catch (error) {
       this.notifyError(error instanceof Error ? error : new Error(String(error)));
     }
@@ -150,15 +150,15 @@ export class Presentation {
   // ==================== Private ====================
 
   private subscribeToEvents(): void {
-    // Subscribe to all events and filter by agentId
+    // Subscribe to all events and filter by instanceId
     this.eventUnsubscribe = this.agentx.onAny((event: BusEvent) => {
       // Filter events for this agent (if context is available)
-      // Note: Events from server may or may not include context with agentId
-      const eventWithContext = event as BusEvent & { context?: { agentId?: string } };
-      const eventAgentId = eventWithContext.context?.agentId;
+      // Note: Events from server may or may not include context with instanceId
+      const eventWithContext = event as BusEvent & { context?: { instanceId?: string } };
+      const eventAgentId = eventWithContext.context?.instanceId;
 
-      // Only filter if event has agentId and it doesn't match
-      if (eventAgentId && eventAgentId !== this.agentId) {
+      // Only filter if event has instanceId and it doesn't match
+      if (eventAgentId && eventAgentId !== this.instanceId) {
         return;
       }
 

package/src/types.ts

@@ -5,7 +5,7 @@
 import type { Message } from "@agentxjs/core/agent";
 import type { AgentXError } from "@agentxjs/core/error";
 import type { BusEvent, BusEventHandler, EventBus, Unsubscribe } from "@agentxjs/core/event";
-import type { LLMProtocol, LLMProviderRecord, PrototypeRecord } from "@agentxjs/core/persistence";
+import type { LLMProtocol, LLMProviderRecord } from "@agentxjs/core/persistence";
 import type { AgentXPlatform } from "@agentxjs/core/runtime";
 import type { Presentation, PresentationOptions } from "./presentation";
 
@@ -38,8 +38,8 @@ export interface RemoteClientConfig {
 /**
  * Agent info returned from server
  */
-export interface AgentInfo {
-  agentId: string;
+export interface InstanceInfo {
+  instanceId: string;
   imageId: string;
   containerId: string;
   sessionId: string;
@@ -47,16 +47,28 @@ export interface AgentInfo {
 }
 
 /**
- * Embodiment — runtime configuration for an agent's "body".
+ * AgentConfig — flat runtime configuration for creating an agent.
+ * AgentConfig IS the body — no wrapper needed.
  */
-export interface Embodiment {
+export interface AgentConfig {
+  /** LLM model identifier */
   model?: string;
+  /** System prompt for the agent */
   systemPrompt?: string;
+  /** MCP server configurations for tool access */
   mcpServers?: Record<string, unknown>;
+  /** Context provider ID (e.g. RoleX individual) */
+  contextId?: string;
+  /** Display name */
+  name?: string;
+  /** Description */
+  description?: string;
+  /** Arbitrary custom data */
+  customData?: Record<string, unknown>;
 }
 
 /**
- * Image record from server
+ * Image record from server (internal persistence)
  */
 export interface ImageRecord {
   imageId: string;
@@ -65,23 +77,14 @@ export interface ImageRecord {
   name?: string;
   description?: string;
   contextId?: string;
-  embody?: Embodiment;
-  /** @deprecated Use `embody.systemPrompt` instead. */
+  model?: string;
   systemPrompt?: string;
-  /** @deprecated Use `embody.mcpServers` instead. */
   mcpServers?: Record<string, unknown>;
   customData?: Record<string, unknown>;
   createdAt: number;
   updatedAt: number;
 }
 
-/**
- * Container info
- */
-export interface ContainerInfo {
-  containerId: string;
-}
-
 // ============================================================================
 // Request/Response Types
 // ============================================================================
@@ -97,8 +100,8 @@ export interface BaseResponse {
 /**
  * Agent create response
  */
-export interface AgentCreateResponse extends BaseResponse {
-  agentId: string;
+export interface InstanceCreateResponse extends BaseResponse {
+  instanceId: string;
   imageId: string;
   containerId: string;
   sessionId: string;
@@ -107,16 +110,16 @@ export interface AgentCreateResponse extends BaseResponse {
 /**
  * Agent get response
  */
-export interface AgentGetResponse extends BaseResponse {
-  agent: AgentInfo | null;
+export interface InstanceGetResponse extends BaseResponse {
+  agent: InstanceInfo | null;
   exists: boolean;
 }
 
 /**
  * Agent list response
  */
-export interface AgentListResponse extends BaseResponse {
-  agents: AgentInfo[];
+export interface InstanceListResponse extends BaseResponse {
+  agents: InstanceInfo[];
 }
 
 /**
@@ -150,33 +153,11 @@ export interface ImageUpdateResponse extends BaseResponse {
   record: ImageRecord;
 }
 
-/**
- * Container create response
- */
-export interface ContainerCreateResponse extends BaseResponse {
-  containerId: string;
-}
-
-/**
- * Container get response
- */
-export interface ContainerGetResponse extends BaseResponse {
-  containerId: string;
-  exists: boolean;
-}
-
-/**
- * Container list response
- */
-export interface ContainerListResponse extends BaseResponse {
-  containerIds: string[];
-}
-
 /**
  * Message send response
  */
 export interface MessageSendResponse extends BaseResponse {
-  agentId: string;
+  instanceId: string;
 }
 
 /**
@@ -214,62 +195,10 @@ export interface LLMProviderDefaultResponse extends BaseResponse {
   record: LLMProviderRecord | null;
 }
 
-// ============================================================================
-// Prototype Response Types
-// ============================================================================
-
-/**
- * Prototype create response
- */
-export interface PrototypeCreateResponse extends BaseResponse {
-  record: PrototypeRecord;
-}
-
-/**
- * Prototype get response
- */
-export interface PrototypeGetResponse extends BaseResponse {
-  record: PrototypeRecord | null;
-}
-
-/**
- * Prototype list response
- */
-export interface PrototypeListResponse extends BaseResponse {
-  records: PrototypeRecord[];
-}
-
-/**
- * Prototype update response
- */
-export interface PrototypeUpdateResponse extends BaseResponse {
-  record: PrototypeRecord;
-}
-
 // ============================================================================
 // Namespace Interfaces
 // ============================================================================
 
-/**
- * Container operations namespace
- */
-export interface ContainerNamespace {
-  /**
-   * Create or get container
-   */
-  create(containerId: string): Promise<ContainerCreateResponse>;
-
-  /**
-   * Get container
-   */
-  get(containerId: string): Promise<ContainerGetResponse>;
-
-  /**
-   * List containers
-   */
-  list(): Promise<ContainerListResponse>;
-}
-
 /**
  * Image operations namespace
  */
@@ -277,14 +206,7 @@ export interface ImageNamespace {
   /**
    * Create a new image from an Agent blueprint
    */
-  create(params: {
-    containerId: string;
-    name?: string;
-    description?: string;
-    contextId?: string;
-    embody?: Embodiment;
-    customData?: Record<string, unknown>;
-  }): Promise<ImageCreateResponse>;
+  create(params: AgentConfig): Promise<ImageCreateResponse>;
 
   /**
    * Get image by ID
@@ -294,19 +216,19 @@ export interface ImageNamespace {
   /**
    * List images
    */
-  list(containerId?: string): Promise<ImageListResponse>;
+  list(): Promise<ImageListResponse>;
 
   /**
    * Update image
    */
   update(
     imageId: string,
-    updates: {
-      name?: string;
-      description?: string;
-      embody?: Embodiment;
-      customData?: Record<string, unknown>;
-    }
+    updates: Partial<
+      Pick<
+        AgentConfig,
+        "name" | "description" | "model" | "systemPrompt" | "mcpServers" | "customData"
+      >
+    >
   ): Promise<ImageUpdateResponse>;
 
   /**
@@ -323,26 +245,26 @@ export interface ImageNamespace {
 /**
  * Agent operations namespace
  */
-export interface AgentNamespace {
+export interface InstanceNamespace {
   /**
    * Create a new agent
    */
-  create(params: { imageId: string; agentId?: string }): Promise<AgentCreateResponse>;
+  create(params: { imageId: string; instanceId?: string }): Promise<InstanceCreateResponse>;
 
   /**
    * Get agent by ID
    */
-  get(agentId: string): Promise<AgentGetResponse>;
+  get(instanceId: string): Promise<InstanceGetResponse>;
 
   /**
    * List agents
    */
-  list(containerId?: string): Promise<AgentListResponse>;
+  list(): Promise<InstanceListResponse>;
 
   /**
    * Destroy an agent
    */
-  destroy(agentId: string): Promise<BaseResponse>;
+  destroy(instanceId: string): Promise<BaseResponse>;
 }
 
 /**
@@ -352,17 +274,17 @@ export interface SessionNamespace {
   /**
    * Send message to agent
    */
-  send(agentId: string, content: string | unknown[]): Promise<MessageSendResponse>;
+  send(instanceId: string, content: string | unknown[]): Promise<MessageSendResponse>;
 
   /**
    * Interrupt agent
    */
-  interrupt(agentId: string): Promise<BaseResponse>;
+  interrupt(instanceId: string): Promise<BaseResponse>;
 
   /**
    * Get message history for an agent's session
    */
-  getMessages(agentId: string): Promise<Message[]>;
+  getMessages(instanceId: string): Promise<Message[]>;
 }
 
 /**
@@ -373,7 +295,6 @@ export interface LLMNamespace {
    * Create a new LLM provider configuration
    */
   create(params: {
-    containerId: string;
     name: string;
     vendor: string;
     protocol: LLMProtocol;
@@ -388,9 +309,9 @@ export interface LLMNamespace {
   get(id: string): Promise<LLMProviderGetResponse>;
 
   /**
-   * List LLM providers for a container
+   * List LLM providers
    */
-  list(containerId: string): Promise<LLMProviderListResponse>;
+  list(): Promise<LLMProviderListResponse>;
 
   /**
    * Update LLM provider
@@ -413,60 +334,14 @@ export interface LLMNamespace {
   delete(id: string): Promise<BaseResponse>;
 
   /**
-   * Set default LLM provider for a container
+   * Set default LLM provider
    */
   setDefault(id: string): Promise<BaseResponse>;
 
   /**
-   * Get default LLM provider for a container
-   */
-  getDefault(containerId: string): Promise<LLMProviderDefaultResponse>;
-}
-
-/**
- * Prototype operations namespace — manage reusable agent templates
- */
-export interface PrototypeNamespace {
-  /**
-   * Register a new prototype
-   */
-  create(params: {
-    containerId: string;
-    name: string;
-    description?: string;
-    contextId?: string;
-    embody?: Embodiment;
-    customData?: Record<string, unknown>;
-  }): Promise<PrototypeCreateResponse>;
-
-  /**
-   * Get prototype by ID
-   */
-  get(prototypeId: string): Promise<PrototypeGetResponse>;
-
-  /**
-   * List prototypes
+   * Get default LLM provider
    */
-  list(containerId?: string): Promise<PrototypeListResponse>;
-
-  /**
-   * Update prototype
-   */
-  update(
-    prototypeId: string,
-    updates: {
-      name?: string;
-      description?: string;
-      contextId?: string;
-      embody?: Embodiment;
-      customData?: Record<string, unknown>;
-    }
-  ): Promise<PrototypeUpdateResponse>;
-
-  /**
-   * Delete prototype
-   */
-  delete(prototypeId: string): Promise<BaseResponse>;
+  getDefault(): Promise<LLMProviderDefaultResponse>;
 }
 
 /**
@@ -478,7 +353,7 @@ export interface PresentationNamespace {
    *
    * @example
    * ```typescript
-   * const pres = ax.present(agentId, {
+   * const pres = ax.present(instanceId, {
    *   onUpdate: (state) => renderUI(state),
    *   onError: (error) => console.error(error),
    * });
@@ -487,7 +362,7 @@ export interface PresentationNamespace {
    * pres.dispose();
    * ```
    */
-  create(agentId: string, options?: PresentationOptions): Promise<Presentation>;
+  create(instanceId: string, options?: PresentationOptions): Promise<Presentation>;
 }
 
 // ============================================================================
@@ -498,17 +373,15 @@ export interface PresentationNamespace {
  * Instance — low-level access to internal subsystems.
  *
  * Most users should use the top-level Agent API (ax.create, ax.send, etc.).
- * Instance exposes the underlying image, agent, session, container, llm,
+ * Instance exposes the underlying image, agent, session, llm,
  * and presentation subsystems for advanced use cases.
  */
 export interface RuntimeNamespace {
-  readonly container: ContainerNamespace;
   readonly image: ImageNamespace;
-  readonly agent: AgentNamespace;
+  readonly instance: InstanceNamespace;
   readonly session: SessionNamespace;
   readonly present: PresentationNamespace;
   readonly llm: LLMNamespace;
-  readonly prototype: PrototypeNamespace;
 }
 
 // ============================================================================
@@ -523,13 +396,13 @@ export interface RuntimeNamespace {
  *
  * @example
  * ```typescript
- * const agent = await ax.chat.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * const agent = await ax.chat.create({ name: "Aristotle", model: "claude-sonnet-4-6" });
  * await agent.send("Hello!");
  * const messages = await agent.history();
  * ```
  */
 export interface AgentHandle {
-  readonly agentId: string;
+  readonly instanceId: string;
   readonly imageId: string;
   readonly containerId: string;
   readonly sessionId: string;
@@ -557,12 +430,14 @@ export interface AgentHandle {
   /**
    * Update this agent's metadata
    */
-  update(updates: {
-    name?: string;
-    description?: string;
-    embody?: Embodiment;
-    customData?: Record<string, unknown>;
-  }): Promise<void>;
+  update(
+    updates: Partial<
+      Pick<
+        AgentConfig,
+        "name" | "description" | "model" | "systemPrompt" | "mcpServers" | "customData"
+      >
+    >
+  ): Promise<void>;
 
   /**
    * Delete this agent
@@ -583,18 +458,8 @@ export interface AgentHandle {
 export interface ChatNamespace {
   /**
    * Create a new conversation
-   *
-   * When `prototypeId` is provided, the conversation inherits the prototype's
-   * configuration (contextId, embody, etc.). Inline params override prototype values.
    */
-  create(params: {
-    prototypeId?: string;
-    name?: string;
-    description?: string;
-    contextId?: string;
-    embody?: Embodiment;
-    customData?: Record<string, unknown>;
-  }): Promise<AgentHandle>;
+  create(params: AgentConfig): Promise<AgentHandle>;
 
   /**
    * List all conversations
@@ -617,7 +482,7 @@ export interface ChatNamespace {
  * @example
  * ```typescript
  * const ax = createAgentX(config);
- * const agent = await ax.chat.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * const agent = await ax.chat.create({ name: "Aristotle", model: "claude-sonnet-4-6" });
  * await agent.send("Hello!");
  * ```
  *
@@ -641,17 +506,10 @@ export interface AgentX {
    */
   readonly chat: ChatNamespace;
 
-  // ==================== Prototype (templates) ====================
-
-  /**
-   * Prototype management — register and manage reusable agent templates.
-   */
-  readonly prototype: PrototypeNamespace;
-
   // ==================== Instance (low-level) ====================
 
   /**
-   * Low-level access to internal subsystems (image, agent, session, container, llm).
+   * Low-level access to internal subsystems (image, agent, session, llm).
    */
   readonly runtime: RuntimeNamespace;