agentxjs 2.4.0 → 2.6.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { Message } from '@agentxjs/core/agent';
 import { AgentXError } from '@agentxjs/core/error';
 export { AgentXError, AgentXErrorCategory, AgentXErrorCode, AgentXErrorContext } from '@agentxjs/core/error';
 import { Unsubscribe, BusEvent, EventBus, BusEventHandler } from '@agentxjs/core/event';
-import { LLMProtocol, LLMProviderRecord } from '@agentxjs/core/persistence';
+import { PrototypeRecord, LLMProtocol, LLMProviderRecord } from '@agentxjs/core/persistence';
 import * as _agentxjs_core_network from '@agentxjs/core/network';
 import { RpcMethod } from '@agentxjs/core/network';
 
@@ -229,6 +229,14 @@ interface AgentInfo {
     sessionId: string;
     lifecycle?: string;
 }
+/**
+ * Embodiment — runtime configuration for an agent's "body".
+ */
+interface Embodiment {
+    model?: string;
+    systemPrompt?: string;
+    mcpServers?: Record<string, unknown>;
+}
 /**
  * Image record from server
  */
@@ -238,7 +246,12 @@ 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;
@@ -360,6 +373,30 @@ interface LLMProviderUpdateResponse extends BaseResponse {
 interface LLMProviderDefaultResponse extends BaseResponse {
     record: LLMProviderRecord | null;
 }
+/**
+ * Prototype create response
+ */
+interface PrototypeCreateResponse extends BaseResponse {
+    record: PrototypeRecord;
+}
+/**
+ * Prototype get response
+ */
+interface PrototypeGetResponse extends BaseResponse {
+    record: PrototypeRecord | null;
+}
+/**
+ * Prototype list response
+ */
+interface PrototypeListResponse extends BaseResponse {
+    records: PrototypeRecord[];
+}
+/**
+ * Prototype update response
+ */
+interface PrototypeUpdateResponse extends BaseResponse {
+    record: PrototypeRecord;
+}
 /**
  * Container operations namespace
  */
@@ -382,14 +419,14 @@ interface ContainerNamespace {
  */
 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>;
     /**
@@ -406,6 +443,7 @@ interface ImageNamespace {
     update(imageId: string, updates: {
         name?: string;
         description?: string;
+        embody?: Embodiment;
         customData?: Record<string, unknown>;
     }): Promise<ImageUpdateResponse>;
     /**
@@ -506,6 +544,44 @@ interface LLMNamespace {
      */
     getDefault(containerId: string): Promise<LLMProviderDefaultResponse>;
 }
+/**
+ * Prototype operations namespace — manage reusable agent templates
+ */
+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
+     */
+    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>;
+}
 /**
  * Presentation operations namespace
  */
@@ -515,7 +591,7 @@ interface PresentationNamespace {
      *
      * @example
      * ```typescript
-     * const pres = agentx.presentation.create(agentId, {
+     * const pres = ax.present(agentId, {
      *   onUpdate: (state) => renderUI(state),
      *   onError: (error) => console.error(error),
      * });
@@ -527,7 +603,110 @@ interface PresentationNamespace {
     create(agentId: string, options?: PresentationOptions): Promise<Presentation>;
 }
 /**
- * AgentX Client SDK — unified interface for local, remote, and server modes
+ * 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.
+ */
+interface RuntimeNamespace {
+    readonly container: ContainerNamespace;
+    readonly image: ImageNamespace;
+    readonly agent: AgentNamespace;
+    readonly session: SessionNamespace;
+    readonly present: PresentationNamespace;
+    readonly llm: LLMNamespace;
+    readonly prototype: PrototypeNamespace;
+}
+/**
+ * AgentHandle — a live reference to a created agent.
+ *
+ * Returned by `ax.chat.create()` and `ax.chat.get()`. Holds the agent's identity
+ * and provides instance-level operations (send, interrupt, etc.).
+ *
+ * @example
+ * ```typescript
+ * const agent = await ax.chat.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * await agent.send("Hello!");
+ * const messages = await agent.history();
+ * ```
+ */
+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>;
+}
+/**
+ * Chat operations — create and manage conversations.
+ *
+ * Each conversation is backed by an Image (persistent record)
+ * and returns an AgentHandle for interaction.
+ */
+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>;
+    /**
+     * List all conversations
+     */
+    list(): Promise<ImageListResponse>;
+    /**
+     * Get a conversation by ID
+     */
+    get(id: string): Promise<AgentHandle | null>;
+}
+/**
+ * AgentX Client SDK — unified interface for local, remote, and server modes.
+ *
+ * @example
+ * ```typescript
+ * const ax = createAgentX(config);
+ * const agent = await ax.chat.create({ name: "Aristotle", embody: { model: "claude-sonnet-4-6" } });
+ * await agent.send("Hello!");
+ * ```
+ *
+ * For advanced use cases, access `ax.runtime.*` for low-level subsystems.
  */
 interface AgentX {
     /**
@@ -538,43 +717,30 @@ interface AgentX {
      * Event bus for subscribing to events
      */
     readonly events: EventBus;
-    readonly container: ContainerNamespace;
-    readonly image: ImageNamespace;
-    readonly agent: AgentNamespace;
-    readonly session: SessionNamespace;
-    readonly presentation: PresentationNamespace;
-    readonly llm: LLMNamespace;
+    /**
+     * Conversation management — create, list, and open conversations.
+     */
+    readonly chat: ChatNamespace;
+    /**
+     * Prototype management — register and manage reusable agent templates.
+     */
+    readonly prototype: PrototypeNamespace;
+    /**
+     * Low-level access to internal subsystems (image, agent, session, container, llm).
+     */
+    readonly runtime: RuntimeNamespace;
+    /**
+     * LLM provider management (system-level, not per-agent)
+     */
+    readonly provider: LLMNamespace;
     on<T extends string>(type: T, handler: BusEventHandler<BusEvent & {
         type: T;
     }>): Unsubscribe;
     onAny(handler: BusEventHandler): Unsubscribe;
     subscribe(sessionId: string): void;
-    /**
-     * 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;
     /**
-     * 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>;
     disconnect(): Promise<void>;
@@ -626,7 +792,8 @@ interface AgentXServer {
  * const ax = createAgentX(node({ createDriver }))
  *
  * // Local use
- * await ax.agent.create({ imageId: "..." })
+ * const agent = await ax.chat.create({ name: "Aristotle" })
+ * await agent.send("Hello!")
  *
  * // Connect to remote server
  * const client = await ax.connect("wss://...")
@@ -695,6 +862,11 @@ declare class CommandHandler {
     private handleAgentDestroyAll;
     private handleAgentInterrupt;
     private handleMessageSend;
+    private handlePrototypeCreate;
+    private handlePrototypeGet;
+    private handlePrototypeList;
+    private handlePrototypeUpdate;
+    private handlePrototypeDelete;
     private handleLLMCreate;
     private handleLLMGet;
     private handleLLMList;
@@ -753,7 +925,8 @@ declare function createServer(config: ServerConfig): Promise<AgentXServer>;
  * 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
@@ -784,4 +957,4 @@ interface PlatformConfig {
  */
 declare function createAgentX(config?: PlatformConfig): AgentXBuilder;
 
-export { type AgentCreateResponse, type AgentGetResponse, type AgentInfo, type AgentListResponse, type AgentNamespace, type AgentX, type AgentXBuilder, type AgentXServer, type AssistantConversation, type BaseResponse, type Block, CommandHandler, type ConnectOptions, type ContainerCreateResponse, type ContainerGetResponse, type ContainerInfo, type ContainerListResponse, type ContainerNamespace, type Conversation, type ErrorConversation, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageNamespace, type ImageRecord, type LLMNamespace, type LLMProviderCreateResponse, type LLMProviderDefaultResponse, type LLMProviderGetResponse, type LLMProviderListResponse, type LLMProviderUpdateResponse, type MaybeAsync, type MessageSendResponse, type PlatformConfig, Presentation, type PresentationErrorHandler, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type ServeConfig, type ServerConfig, type SessionNamespace, type TextBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, createServer, initialPresentationState, messagesToConversations, presentationReducer };
+export { type AgentCreateResponse, type AgentGetResponse, type AgentHandle, type AgentInfo, type AgentListResponse, type AgentNamespace, type AgentX, type AgentXBuilder, type AgentXServer, type AssistantConversation, type BaseResponse, type Block, type ChatNamespace, CommandHandler, type ConnectOptions, type ContainerCreateResponse, type ContainerGetResponse, type ContainerInfo, type ContainerListResponse, type ContainerNamespace, type Conversation, type Embodiment, type ErrorConversation, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageNamespace, type ImageRecord, type LLMNamespace, type LLMProviderCreateResponse, type LLMProviderDefaultResponse, type LLMProviderGetResponse, type LLMProviderListResponse, type LLMProviderUpdateResponse, type MaybeAsync, type MessageSendResponse, type PlatformConfig, Presentation, type PresentationErrorHandler, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type PrototypeCreateResponse, type PrototypeGetResponse, type PrototypeListResponse, type PrototypeNamespace, type PrototypeUpdateResponse, type RuntimeNamespace, type ServeConfig, type ServerConfig, type SessionNamespace, type TextBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, createServer, initialPresentationState, messagesToConversations, presentationReducer };