agentxjs 1.9.9-dev → 2.0.0

package/src/types.ts

@@ -3,6 +3,9 @@
  */
 
 import type { BusEvent, EventBus, Unsubscribe, BusEventHandler } from "@agentxjs/core/event";
+import type { CreateDriver } from "@agentxjs/core/driver";
+import type { AgentXPlatform } from "@agentxjs/core/runtime";
+import type { Message } from "@agentxjs/core/agent";
 import type { Presentation, PresentationOptions } from "./presentation";
 
 // ============================================================================
@@ -15,27 +18,90 @@ import type { Presentation, PresentationOptions } from "./presentation";
 export type MaybeAsync<T> = T | (() => T) | (() => Promise<T>);
 
 /**
- * AgentX client configuration
+ * LLM provider identifier
+ */
+export 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
  */
 export interface AgentXConfig {
+  // ===== Local Mode =====
+
+  /**
+   * 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;
+
+  // ===== Remote Mode =====
+
   /**
-   * WebSocket server URL
+   * 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>>;
 
+  // ===== Common =====
+
+  /**
+   * 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)
    */
@@ -43,11 +109,12 @@ export interface AgentXConfig {
 
   /**
    * 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;
 }
@@ -77,6 +144,7 @@ export interface ImageRecord {
   name?: string;
   description?: string;
   systemPrompt?: string;
+  customData?: Record<string, unknown>;
   createdAt: number;
   updatedAt: number;
 }
@@ -149,6 +217,13 @@ export interface ImageListResponse extends BaseResponse {
   __subscriptions?: string[];
 }
 
+/**
+ * Image update response
+ */
+export interface ImageUpdateResponse extends BaseResponse {
+  record: ImageRecord;
+}
+
 /**
  * Container create response
  */
@@ -179,101 +254,183 @@ export interface MessageSendResponse extends BaseResponse {
 }
 
 // ============================================================================
-// AgentX Client Interface
+// Namespace Interfaces
 // ============================================================================
 
 /**
- * AgentX Client SDK
+ * Container operations namespace
  */
-export interface AgentX {
+export 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
+ */
+export 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>;
 
-  // ==================== Agent Operations ====================
+  /**
+   * 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
+ */
+export interface AgentNamespace {
   /**
    * Create a new agent
    */
-  createAgent(params: { imageId: string; agentId?: string }): Promise<AgentCreateResponse>;
+  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>;
-
-  // ==================== Message Operations ====================
+  destroy(agentId: string): Promise<BaseResponse>;
+}
 
+/**
+ * Session operations namespace (messaging)
+ */
+export 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>;
 
-  // ==================== Image Operations ====================
+  /**
+   * Get message history for an agent's session
+   */
+  getMessages(agentId: string): Promise<Message[]>;
+}
 
+/**
+ * Presentation operations namespace
+ */
+export interface PresentationNamespace {
   /**
-   * Create a new image
+   * 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();
+   * ```
    */
-  createImage(params: {
-    containerId: string;
-    name?: string;
-    description?: string;
-    systemPrompt?: string;
-    mcpServers?: Record<string, unknown>;
-  }): Promise<ImageCreateResponse>;
+  create(agentId: string, options?: PresentationOptions): Promise<Presentation>;
+}
 
+// ============================================================================
+// AgentX Client Interface
+// ============================================================================
+
+/**
+ * AgentX Client SDK
+ */
+export interface AgentX {
   /**
-   * Get image by ID
+   * Check if connected to server
    */
-  getImage(imageId: string): Promise<ImageGetResponse>;
+  readonly connected: boolean;
 
   /**
-   * List images
+   * Event bus for subscribing to events
    */
-  listImages(containerId?: string): Promise<ImageListResponse>;
+  readonly events: EventBus;
+
+  // ==================== Namespaced Operations ====================
 
   /**
-   * Delete image
+   * Container operations
    */
-  deleteImage(imageId: string): Promise<BaseResponse>;
+  readonly containers: ContainerNamespace;
 
-  // ==================== Container Operations ====================
+  /**
+   * Image operations
+   */
+  readonly images: ImageNamespace;
 
   /**
-   * Create or get container
+   * Agent operations
    */
-  createContainer(containerId: string): Promise<ContainerCreateResponse>;
+  readonly agents: AgentNamespace;
 
   /**
-   * Get container
+   * Session operations (messaging)
    */
-  getContainer(containerId: string): Promise<ContainerGetResponse>;
+  readonly sessions: SessionNamespace;
 
   /**
-   * List containers
+   * Presentation operations (UI integration)
    */
-  listContainers(): Promise<ContainerListResponse>;
+  readonly presentations: PresentationNamespace;
 
   // ==================== Event Subscription ====================
 
@@ -292,24 +449,6 @@ export interface AgentX {
    */
   subscribe(sessionId: string): void;
 
-  // ==================== Presentation ====================
-
-  /**
-   * 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;
-
   // ==================== Lifecycle ====================
 
   /**