agentxjs 2.4.0 → 2.5.0

package/src/LocalClient.ts

@@ -10,6 +10,7 @@ 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";
@@ -18,13 +19,12 @@ import { createLocalLLM } from "./namespaces/llm";
 import { createPresentations } from "./namespaces/presentations";
 import { createLocalSessions } from "./namespaces/sessions";
 import type {
-  AgentNamespace,
+  AgentHandle,
   AgentX,
-  ContainerNamespace,
-  ImageNamespace,
+  Embodiment,
+  ImageListResponse,
+  InstanceNamespace,
   LLMNamespace,
-  PresentationNamespace,
-  SessionNamespace,
 } from "./types";
 
 const logger = createLogger("agentx/LocalClient");
@@ -37,23 +37,22 @@ export class LocalClient implements AgentX {
   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 instance: InstanceNamespace;
+  readonly provider: LLMNamespace;
 
   constructor(runtime: AgentXRuntime) {
     this.runtime = runtime;
     const platform = runtime.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(runtime);
+    const session = createLocalSessions(runtime);
+    const llm = createLocalLLM(platform);
+    const present = createPresentations(this, image);
+
+    this.instance = { container, image, agent, session, present, llm };
+    this.provider = llm;
 
     logger.info("LocalClient initialized");
   }
@@ -68,6 +67,48 @@ export class LocalClient implements AgentX {
     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
+    );
+  }
+
   // ==================== Event Subscription ====================
 
   on<T extends string>(type: T, handler: BusEventHandler<BusEvent & { type: T }>): Unsubscribe {

package/src/RemoteClient.ts

@@ -10,6 +10,7 @@ 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";
@@ -17,14 +18,13 @@ import { createRemoteLLM } from "./namespaces/llm";
 import { createPresentations } from "./namespaces/presentations";
 import { createRemoteSessions } from "./namespaces/sessions";
 import type {
-  AgentNamespace,
+  AgentHandle,
   AgentX,
-  ContainerNamespace,
-  ImageNamespace,
+  Embodiment,
+  ImageListResponse,
+  InstanceNamespace,
   LLMNamespace,
-  PresentationNamespace,
   RemoteClientConfig,
-  SessionNamespace,
 } from "./types";
 
 const logger = createLogger("agentx/RemoteClient");
@@ -37,12 +37,8 @@ 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 instance: InstanceNamespace;
+  readonly provider: LLMNamespace;
 
   constructor(config: RemoteClientConfig) {
     this.config = config;
@@ -65,12 +61,15 @@ 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 present = createPresentations(this, image);
+
+    this.instance = { container, image, agent, session, present, llm };
+    this.provider = llm;
   }
 
   // ==================== Properties ====================
@@ -83,6 +82,48 @@ 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> {

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.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * await agent.send("Hello!");
  * ```
  *
  * @example Remote mode
@@ -74,29 +75,18 @@ export function createAgentX(config?: PlatformConfig): AgentXBuilder {
       return getLocalClient().events;
     },
 
-    get container() {
-      return getLocalClient().container;
+    get instance() {
+      return getLocalClient().instance;
     },
 
-    get image() {
-      return getLocalClient().image;
+    get provider() {
+      return getLocalClient().provider;
     },
 
-    get agent() {
-      return getLocalClient().agent;
-    },
-
-    get session() {
-      return getLocalClient().session;
-    },
-
-    get presentation() {
-      return getLocalClient().presentation;
-    },
-
-    get llm() {
-      return getLocalClient().llm;
-    },
+    // Top-level Agent API
+    create: (params) => getLocalClient().create(params),
+    list: () => getLocalClient().list(),
+    get: (agentId) => getLocalClient().get(agentId),
 
     on(type, handler) {
       return getLocalClient().on(type, handler);
@@ -196,6 +186,7 @@ export { createServer, type ServerConfig } from "./server";
 export type {
   AgentCreateResponse,
   AgentGetResponse,
+  AgentHandle,
   AgentInfo,
   AgentListResponse,
   AgentNamespace,
@@ -209,11 +200,13 @@ export type {
   ContainerInfo,
   ContainerListResponse,
   ContainerNamespace,
+  Embodiment,
   ImageCreateResponse,
   ImageGetResponse,
   ImageListResponse,
   ImageNamespace,
   ImageRecord,
+  InstanceNamespace,
   LLMNamespace,
   LLMProviderCreateResponse,
   LLMProviderDefaultResponse,

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);
     },

package/src/presentation/Presentation.ts

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

package/src/types.ts

@@ -46,6 +46,15 @@ export interface AgentInfo {
   lifecycle?: string;
 }
 
+/**
+ * Embodiment — runtime configuration for an agent's "body".
+ */
+export interface Embodiment {
+  model?: string;
+  systemPrompt?: string;
+  mcpServers?: Record<string, unknown>;
+}
+
 /**
  * Image record from server
  */
@@ -55,7 +64,12 @@ export interface ImageRecord {
   sessionId: string;
   name?: string;
   description?: string;
+  contextId?: string;
+  embody?: Embodiment;
+  /** @deprecated Use `embody.systemPrompt` instead. */
   systemPrompt?: string;
+  /** @deprecated Use `embody.mcpServers` instead. */
+  mcpServers?: Record<string, unknown>;
   customData?: Record<string, unknown>;
   createdAt: number;
   updatedAt: number;
@@ -229,14 +243,14 @@ export interface ContainerNamespace {
  */
 export interface ImageNamespace {
   /**
-   * Create a new image
+   * Create a new image from an Agent blueprint
    */
   create(params: {
     containerId: string;
     name?: string;
     description?: string;
-    systemPrompt?: string;
-    mcpServers?: Record<string, unknown>;
+    contextId?: string;
+    embody?: Embodiment;
     customData?: Record<string, unknown>;
   }): Promise<ImageCreateResponse>;
 
@@ -258,6 +272,7 @@ export interface ImageNamespace {
     updates: {
       name?: string;
       description?: string;
+      embody?: Embodiment;
       customData?: Record<string, unknown>;
     }
   ): Promise<ImageUpdateResponse>;
@@ -385,7 +400,7 @@ export interface PresentationNamespace {
    *
    * @example
    * ```typescript
-   * const pres = agentx.presentation.create(agentId, {
+   * const pres = ax.present(agentId, {
    *   onUpdate: (state) => renderUI(state),
    *   onError: (error) => console.error(error),
    * });
@@ -397,12 +412,100 @@ export interface PresentationNamespace {
   create(agentId: string, options?: PresentationOptions): Promise<Presentation>;
 }
 
+// ============================================================================
+// Instance Namespace — internal implementation details
+// ============================================================================
+
+/**
+ * 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,
+ * and presentation subsystems for advanced use cases.
+ */
+export interface InstanceNamespace {
+  readonly container: ContainerNamespace;
+  readonly image: ImageNamespace;
+  readonly agent: AgentNamespace;
+  readonly session: SessionNamespace;
+  readonly present: PresentationNamespace;
+  readonly llm: LLMNamespace;
+}
+
+// ============================================================================
+// Agent Handle
+// ============================================================================
+
+/**
+ * AgentHandle — a live reference to a created agent.
+ *
+ * Returned by `ax.create()` and `ax.get()`. Holds the agent's identity
+ * and provides instance-level operations (send, interrupt, etc.).
+ *
+ * @example
+ * ```typescript
+ * const agent = await ax.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * await agent.send("Hello!");
+ * const messages = await agent.history();
+ * ```
+ */
+export interface AgentHandle {
+  readonly agentId: string;
+  readonly imageId: string;
+  readonly containerId: string;
+  readonly sessionId: string;
+
+  /**
+   * Send a message to this agent
+   */
+  send(content: string | unknown[]): Promise<MessageSendResponse>;
+
+  /**
+   * Interrupt this agent's current response
+   */
+  interrupt(): Promise<BaseResponse>;
+
+  /**
+   * Get message history
+   */
+  history(): Promise<Message[]>;
+
+  /**
+   * Create a presentation for UI integration
+   */
+  present(options?: PresentationOptions): Promise<Presentation>;
+
+  /**
+   * Update this agent's metadata
+   */
+  update(updates: {
+    name?: string;
+    description?: string;
+    embody?: Embodiment;
+    customData?: Record<string, unknown>;
+  }): Promise<void>;
+
+  /**
+   * Delete this agent
+   */
+  delete(): Promise<void>;
+}
+
 // ============================================================================
 // AgentX Client Interface
 // ============================================================================
 
 /**
- * AgentX Client SDK — unified interface for local, remote, and server modes
+ * AgentX Client SDK — unified interface for local, remote, and server modes.
+ *
+ * @example
+ * ```typescript
+ * const ax = createAgentX(config);
+ * const agent = await ax.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * await agent.send("Hello!");
+ * ```
+ *
+ * For advanced use cases, access `ax.instance.*` for low-level subsystems.
  */
 export interface AgentX {
   /**
@@ -415,14 +518,42 @@ export interface AgentX {
    */
   readonly events: EventBus;
 
-  // ==================== Namespaced Operations ====================
+  // ==================== Agent API (top-level) ====================
 
-  readonly container: ContainerNamespace;
-  readonly image: ImageNamespace;
-  readonly agent: AgentNamespace;
-  readonly session: SessionNamespace;
-  readonly presentation: PresentationNamespace;
-  readonly llm: LLMNamespace;
+  /**
+   * Create a new agent from a blueprint
+   */
+  create(params: {
+    name?: string;
+    description?: string;
+    contextId?: string;
+    embody?: Embodiment;
+    customData?: Record<string, unknown>;
+  }): Promise<AgentHandle>;
+
+  /**
+   * List all agents
+   */
+  list(): Promise<ImageListResponse>;
+
+  /**
+   * Get agent by ID
+   */
+  get(agentId: string): Promise<AgentHandle | null>;
+
+  // ==================== Instance (low-level) ====================
+
+  /**
+   * Low-level access to internal subsystems (image, agent, session, container, llm).
+   */
+  readonly instance: InstanceNamespace;
+
+  // ==================== LLM Provider (system-level) ====================
+
+  /**
+   * LLM provider management (system-level, not per-agent)
+   */
+  readonly provider: LLMNamespace;
 
   // ==================== Event Subscription ====================
 
@@ -432,35 +563,12 @@ export interface AgentX {
 
   // ==================== Error Handling ====================
 
-  /**
-   * Top-level error handler — receives all AgentXError instances from any layer.
-   *
-   * Independent of `on("error", ...)` (stream events) and `presentation.onError` (UI errors).
-   *
-   * @example
-   * ```typescript
-   * ax.onError((error) => {
-   *   console.error(`[${error.category}] ${error.code}: ${error.message}`);
-   *   if (!error.recoverable) {
-   *     // Circuit is open, stop sending requests
-   *   }
-   * });
-   * ```
-   */
   onError(handler: (error: AgentXError) => void): Unsubscribe;
 
   // ==================== RPC ====================
 
   /**
-   * Universal JSON-RPC entry point — works in all modes:
-   * - Local: dispatches to CommandHandler directly
-   * - Remote: forwards to the remote server via RPC client
-   *
-   * @example
-   * ```typescript
-   * const result = await ax.rpc("container.create", { containerId: "default" });
-   * const { records } = await ax.rpc<{ records: ImageRecord[] }>("image.list");
-   * ```
+   * Universal JSON-RPC entry point
    */
   rpc<T = unknown>(method: string, params?: unknown): Promise<T>;
 
@@ -523,7 +631,8 @@ export interface AgentXServer {
  * const ax = createAgentX(node({ createDriver }))
  *
  * // Local use
- * await ax.agent.create({ imageId: "..." })
+ * const agent = await ax.create({ name: "Aristotle" })
+ * await agent.send("Hello!")
  *
  * // Connect to remote server
  * const client = await ax.connect("wss://...")