agentxjs 1.9.10-dev → 2.0.1

package/dist/index.d.ts

@@ -1,4 +1,7 @@
-import { BusEvent, Unsubscribe, EventBus, BusEventHandler } from '@agentxjs/core/event';
+import { Message } from '@agentxjs/core/agent';
+import { CreateDriver } from '@agentxjs/core/driver';
+import { Unsubscribe, BusEvent, EventBus, BusEventHandler } from '@agentxjs/core/event';
+import { AgentXPlatform } from '@agentxjs/core/runtime';
 
 /**
  * Presentation Types
@@ -43,6 +46,13 @@ interface UserConversation {
     role: "user";
     blocks: Block[];
 }
+/**
+ * Token usage for a message (one LLM call / step)
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
 /**
  * Assistant conversation
  */
@@ -50,6 +60,8 @@ interface AssistantConversation {
     role: "assistant";
     blocks: Block[];
     isStreaming: boolean;
+    /** Accumulated token usage across all steps in this conversation */
+    usage?: TokenUsage;
 }
 /**
  * Error conversation
@@ -84,26 +96,6 @@ interface PresentationState {
  */
 declare const initialPresentationState: PresentationState;
 
-/**
- * Presentation Reducer
- *
- * Aggregates stream events into PresentationState.
- * Pure function: (state, event) => newState
- */
-
-/**
- * Reduce a stream event into presentation state
- */
-declare function presentationReducer(state: PresentationState, event: BusEvent): PresentationState;
-/**
- * Add a user conversation to state
- */
-declare function addUserConversation(state: PresentationState, content: string): PresentationState;
-/**
- * Create initial state
- */
-declare function createInitialState(): PresentationState;
-
 /**
  * Presentation Class
  *
@@ -142,7 +134,7 @@ declare class Presentation {
     private updateHandlers;
     private errorHandlers;
     private eventUnsubscribe;
-    constructor(agentx: AgentX, agentId: string, options?: PresentationOptions);
+    constructor(agentx: AgentX, agentId: string, options?: PresentationOptions, initialConversations?: Conversation[]);
     /**
      * Get current state
      */
@@ -176,6 +168,44 @@ declare class Presentation {
     private notifyError;
 }
 
+/**
+ * Presentation Reducer
+ *
+ * Aggregates events into PresentationState.
+ * Pure function: (state, event) => newState
+ *
+ * Event consumption strategy:
+ * - Stream layer: message_start, text_delta, tool_use_start, tool_use_stop, message_stop
+ *   (for real-time streaming display)
+ * - Message layer: tool_result_message
+ *   (for tool execution results — arrives after message_stop)
+ *
+ * Tool calls are stream-level blocks within the assistant turn,
+ * matching the mainstream API pattern (Anthropic, OpenAI).
+ */
+
+/**
+ * Reduce an event into presentation state.
+ *
+ * Consumes:
+ * - Stream events: message_start, text_delta, tool_use_start, tool_use_stop, message_stop
+ * - Message events: tool_result_message
+ * - Error events: error
+ */
+declare function presentationReducer(state: PresentationState, event: BusEvent): PresentationState;
+declare function addUserConversation(state: PresentationState, content: string): PresentationState;
+declare function createInitialState(): PresentationState;
+/**
+ * Convert persisted Messages to Presentation Conversations.
+ *
+ * Groups consecutive assistant + tool-result messages
+ * into a single AssistantConversation.
+ *
+ * Tool calls are now part of AssistantMessage.content (as ToolCallPart),
+ * so we extract them directly from the assistant message.
+ */
+declare function messagesToConversations(messages: Message[]): Conversation[];
+
 /**
  * AgentX Client SDK Types
  */
@@ -185,34 +215,83 @@ declare class Presentation {
  */
 type MaybeAsync<T> = T | (() => T) | (() => Promise<T>);
 /**
- * AgentX client configuration
+ * LLM provider identifier
+ */
+type LLMProvider = "anthropic" | "openai" | "google" | "xai" | "deepseek" | "mistral";
+/**
+ * AgentX unified configuration
+ *
+ * Supports two modes:
+ * - **Local mode**: `apiKey` present → embedded Runtime + MonoDriver
+ * - **Remote mode**: `serverUrl` present → WebSocket client
  */
 interface AgentXConfig {
     /**
-     * WebSocket server URL
+     * API key for LLM provider (local mode)
+     * If present, enables local mode with embedded Runtime
+     */
+    apiKey?: string;
+    /**
+     * LLM provider (local mode)
+     * @default "anthropic"
+     */
+    provider?: LLMProvider;
+    /**
+     * Model ID (local mode)
+     */
+    model?: string;
+    /**
+     * Base URL for API endpoint (local mode, for proxy/private deployments)
+     */
+    baseUrl?: string;
+    /**
+     * Data storage path (local mode)
+     * @default ":memory:" (in-memory storage)
+     */
+    dataPath?: string;
+    /**
+     * Custom CreateDriver factory (local mode, advanced)
+     * If provided, overrides the default MonoDriver
+     */
+    createDriver?: CreateDriver;
+    /**
+     * Custom AgentXPlatform (local mode, advanced)
+     * If provided, overrides the default NodePlatform
+     */
+    customPlatform?: AgentXPlatform;
+    /**
+     * WebSocket server URL (remote mode)
+     * If present, enables remote mode
      */
-    serverUrl: string;
+    serverUrl?: string;
     /**
-     * Headers for authentication (static or dynamic)
+     * Headers for authentication (remote mode, static or dynamic)
      * In Node.js: sent during WebSocket handshake
      * In browsers: sent as first auth message (WebSocket API limitation)
      */
     headers?: MaybeAsync<Record<string, string>>;
     /**
-     * Business context injected into all requests
+     * Business context injected into all requests (remote mode)
      * Useful for passing userId, tenantId, permissions, etc.
      */
     context?: MaybeAsync<Record<string, unknown>>;
+    /**
+     * Log level for AgentX runtime
+     * Controls verbosity of console/file logging.
+     * @default "info"
+     */
+    logLevel?: "debug" | "info" | "warn" | "error" | "silent";
     /**
      * Request timeout in milliseconds (default: 30000)
      */
     timeout?: number;
     /**
      * Enable debug logging
+     * @deprecated Use `logLevel: "debug"` instead
      */
     debug?: boolean;
     /**
-     * Auto reconnect on connection loss (default: true)
+     * Auto reconnect on connection loss (default: true, remote mode only)
      */
     autoReconnect?: boolean;
 }
@@ -236,6 +315,7 @@ interface ImageRecord {
     name?: string;
     description?: string;
     systemPrompt?: string;
+    customData?: Record<string, unknown>;
     createdAt: number;
     updatedAt: number;
 }
@@ -295,6 +375,12 @@ interface ImageListResponse extends BaseResponse {
     records: ImageRecord[];
     __subscriptions?: string[];
 }
+/**
+ * Image update response
+ */
+interface ImageUpdateResponse extends BaseResponse {
+    record: ImageRecord;
+}
 /**
  * Container create response
  */
@@ -321,78 +407,151 @@ interface MessageSendResponse extends BaseResponse {
     agentId: string;
 }
 /**
- * AgentX Client SDK
+ * Container operations namespace
  */
-interface AgentX {
+interface ContainerNamespace {
     /**
-     * Check if connected to server
+     * Create or get container
      */
-    readonly connected: boolean;
+    create(containerId: string): Promise<ContainerCreateResponse>;
     /**
-     * Event bus for subscribing to events
+     * Get container
      */
-    readonly events: EventBus;
+    get(containerId: string): Promise<ContainerGetResponse>;
+    /**
+     * List containers
+     */
+    list(): Promise<ContainerListResponse>;
+}
+/**
+ * Image operations namespace
+ */
+interface ImageNamespace {
+    /**
+     * Create a new image
+     */
+    create(params: {
+        containerId: string;
+        name?: string;
+        description?: string;
+        systemPrompt?: string;
+        mcpServers?: Record<string, unknown>;
+        customData?: Record<string, unknown>;
+    }): Promise<ImageCreateResponse>;
+    /**
+     * Get image by ID
+     */
+    get(imageId: string): Promise<ImageGetResponse>;
+    /**
+     * List images
+     */
+    list(containerId?: string): Promise<ImageListResponse>;
+    /**
+     * Update image
+     */
+    update(imageId: string, updates: {
+        name?: string;
+        description?: string;
+        customData?: Record<string, unknown>;
+    }): Promise<ImageUpdateResponse>;
+    /**
+     * Delete image
+     */
+    delete(imageId: string): Promise<BaseResponse>;
+}
+/**
+ * Agent operations namespace
+ */
+interface AgentNamespace {
     /**
      * Create a new agent
      */
-    createAgent(params: {
+    create(params: {
         imageId: string;
         agentId?: string;
     }): Promise<AgentCreateResponse>;
     /**
      * Get agent by ID
      */
-    getAgent(agentId: string): Promise<AgentGetResponse>;
+    get(agentId: string): Promise<AgentGetResponse>;
     /**
      * List agents
      */
-    listAgents(containerId?: string): Promise<AgentListResponse>;
+    list(containerId?: string): Promise<AgentListResponse>;
     /**
      * Destroy an agent
      */
-    destroyAgent(agentId: string): Promise<BaseResponse>;
+    destroy(agentId: string): Promise<BaseResponse>;
+}
+/**
+ * Session operations namespace (messaging)
+ */
+interface SessionNamespace {
     /**
      * Send message to agent
      */
-    sendMessage(agentId: string, content: string | unknown[]): Promise<MessageSendResponse>;
+    send(agentId: string, content: string | unknown[]): Promise<MessageSendResponse>;
     /**
      * Interrupt agent
      */
     interrupt(agentId: string): Promise<BaseResponse>;
     /**
-     * Create a new image
+     * Get message history for an agent's session
      */
-    createImage(params: {
-        containerId: string;
-        name?: string;
-        description?: string;
-        systemPrompt?: string;
-        mcpServers?: Record<string, unknown>;
-    }): Promise<ImageCreateResponse>;
+    getMessages(agentId: string): Promise<Message[]>;
+}
+/**
+ * Presentation operations namespace
+ */
+interface PresentationNamespace {
     /**
-     * Get image by ID
+     * Create a presentation for UI integration
+     *
+     * @example
+     * ```typescript
+     * const pres = agentx.presentations.create(agentId, {
+     *   onUpdate: (state) => renderUI(state),
+     *   onError: (error) => console.error(error),
+     * });
+     *
+     * await pres.send("Hello!");
+     * pres.dispose();
+     * ```
      */
-    getImage(imageId: string): Promise<ImageGetResponse>;
+    create(agentId: string, options?: PresentationOptions): Promise<Presentation>;
+}
+/**
+ * AgentX Client SDK
+ */
+interface AgentX {
     /**
-     * List images
+     * Check if connected to server
      */
-    listImages(containerId?: string): Promise<ImageListResponse>;
+    readonly connected: boolean;
     /**
-     * Delete image
+     * Event bus for subscribing to events
      */
-    deleteImage(imageId: string): Promise<BaseResponse>;
+    readonly events: EventBus;
     /**
-     * Create or get container
+     * Container operations
      */
-    createContainer(containerId: string): Promise<ContainerCreateResponse>;
+    readonly containers: ContainerNamespace;
     /**
-     * Get container
+     * Image operations
      */
-    getContainer(containerId: string): Promise<ContainerGetResponse>;
+    readonly images: ImageNamespace;
     /**
-     * List containers
+     * Agent operations
      */
-    listContainers(): Promise<ContainerListResponse>;
+    readonly agents: AgentNamespace;
+    /**
+     * Session operations (messaging)
+     */
+    readonly sessions: SessionNamespace;
+    /**
+     * Presentation operations (UI integration)
+     */
+    readonly presentations: PresentationNamespace;
     /**
      * Subscribe to specific event type
      */
@@ -407,21 +566,6 @@ interface AgentX {
      * Subscribe to session events
      */
     subscribe(sessionId: string): void;
-    /**
-     * Create a presentation for UI integration
-     *
-     * @example
-     * ```typescript
-     * const presentation = agentx.presentation(agentId);
-     *
-     * presentation.onUpdate((state) => {
-     *   render(state.conversations);
-     * });
-     *
-     * await presentation.send("Hello!");
-     * ```
-     */
-    presentation(agentId: string, options?: PresentationOptions): Presentation;
     /**
      * Disconnect from server
      */
@@ -435,55 +579,34 @@ interface AgentX {
 /**
  * agentxjs - AgentX Client SDK
  *
- * Connect to AgentX servers from Node.js and browsers.
+ * Unified entry point supporting local and remote modes.
  *
- * @example
+ * @example Local mode (embedded runtime)
  * ```typescript
  * import { createAgentX } from "agentxjs";
  *
- * // Connect to server
  * const agentx = await createAgentX({
- *   serverUrl: "ws://localhost:5200",
- *   headers: { Authorization: "Bearer sk-xxx" },
- *   context: { userId: "123", tenantId: "abc" },
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ *   provider: "anthropic",
  * });
  *
- * // Create container and image
- * await agentx.createContainer("my-container");
- * const { record: image } = await agentx.createImage({
- *   containerId: "my-container",
- *   name: "Assistant",
- *   systemPrompt: "You are a helpful assistant",
+ * await agentx.containers.create("my-app");
+ * const { record: image } = await agentx.images.create({
+ *   containerId: "my-app",
+ *   systemPrompt: "You are helpful",
  * });
+ * const { agentId } = await agentx.agents.create({ imageId: image.imageId });
  *
- * // Create agent and send message
- * const { agentId } = await agentx.createAgent({ imageId: image.imageId });
- *
- * // Subscribe to events
- * agentx.on("text_delta", (event) => {
- *   process.stdout.write(event.data.text);
- * });
- *
- * agentx.on("assistant_message", (event) => {
- *   console.log("Complete:", event.data.content);
- * });
- *
- * // Send message
- * await agentx.sendMessage(agentId, "Hello!");
- *
- * // Cleanup
- * await agentx.dispose();
+ * agentx.on("text_delta", (e) => process.stdout.write(e.data.text));
+ * await agentx.sessions.send(agentId, "Hello!");
  * ```
  *
- * @example Dynamic headers and context
+ * @example Remote mode (WebSocket client)
  * ```typescript
+ * import { createAgentX } from "agentxjs";
+ *
  * const agentx = await createAgentX({
  *   serverUrl: "ws://localhost:5200",
- *   headers: () => ({ Authorization: `Bearer ${getToken()}` }),
- *   context: async () => ({
- *     userId: await getUserId(),
- *     permissions: await getPermissions(),
- *   }),
  * });
  * ```
  */
@@ -491,9 +614,13 @@ interface AgentX {
 /**
  * Create an AgentX client
  *
+ * Mode detection:
+ * - `serverUrl` present → **Remote mode** (WebSocket client)
+ * - `apiKey` present → **Local mode** (embedded Runtime + MonoDriver)
+ *
  * @param config - Client configuration
  * @returns Connected AgentX client
  */
 declare function createAgentX(config: AgentXConfig): Promise<AgentX>;
 
-export { type AgentCreateResponse, type AgentGetResponse, type AgentInfo, type AgentListResponse, type AgentX, type AgentXConfig, type AssistantConversation, type BaseResponse, type Block, type ContainerCreateResponse, type ContainerGetResponse, type ContainerInfo, type ContainerListResponse, type Conversation, type ErrorConversation, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageRecord, type MaybeAsync, type MessageSendResponse, Presentation, type PresentationErrorHandler, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type TextBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, initialPresentationState, presentationReducer };
+export { type AgentCreateResponse, type AgentGetResponse, type AgentInfo, type AgentListResponse, type AgentNamespace, type AgentX, type AgentXConfig, type AssistantConversation, type BaseResponse, type Block, 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 LLMProvider, type MaybeAsync, type MessageSendResponse, Presentation, type PresentationErrorHandler, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type SessionNamespace, type TextBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, initialPresentationState, messagesToConversations, presentationReducer };