agentxjs 2.9.0-dev-20260317033749 → 2.9.0-dev-20260317042246

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { AgentXPlatform } from '@agentxjs/core/runtime';
 import { UserContentPart, 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 { BusEvent, EventBus, BusEventHandler, Unsubscribe } from '@agentxjs/core/event';
 import { LLMProtocol, LLMProviderRecord } from '@agentxjs/core/persistence';
 export { Capability, Context, ContextProvider } from '@agentxjs/core/context';
 
@@ -206,99 +206,67 @@ declare const initialMetrics: PresentationMetrics;
 declare const initialPresentationState: PresentationState;
 
 /**
- * Presentation Class
- *
- * High-level API for UI integration.
- * Wraps AgentX client and provides presentation state management.
- */
-
-/**
- * Presentation update handler
- */
-type PresentationUpdateHandler = (state: PresentationState) => void;
-/**
- * Presentation error handler
+ * Workspace — file tree + operations, unified.
  */
-type PresentationErrorHandler = (error: Error) => void;
+interface Workspace {
+    /** Current file tree (real-time updates) */
+    readonly files: readonly FileTreeEntry[];
+    /** Read file content */
+    read(path: string): Promise<string>;
+    /** Write content to file */
+    write(path: string, content: string): Promise<void>;
+    /** List directory entries */
+    list(path?: string): Promise<FileTreeEntry[]>;
+}
 /**
- * Presentation options
+ * Options for creating a Presentation
  */
 interface PresentationOptions {
-    /**
-     * Called on every state update
-     */
-    onUpdate?: PresentationUpdateHandler;
-    /**
-     * Called on errors
-     */
-    onError?: PresentationErrorHandler;
+    /** Called on every state change (legacy — prefer subscribe) */
+    onUpdate?: (state: PresentationState) => void;
 }
-/**
- * Presentation - UI-friendly wrapper for AgentX
- */
 declare class Presentation {
-    private agentx;
-    private instanceId;
-    private state;
-    private updateHandlers;
-    private errorHandlers;
-    private eventUnsubscribe;
-    /**
-     * Workspace operations — read, write, list files in the agent's workspace.
-     * null when the agent has no workspace.
-     */
-    readonly workspace: PresentationWorkspace | null;
+    private _agentx;
+    private _instanceId;
+    private _state;
+    private _listeners;
+    private _legacyHandlers;
+    private _eventUnsubscribe;
+    private _workspaceOps;
     constructor(agentx: AgentX, instanceId: string, options?: PresentationOptions, initialConversations?: Conversation[], workspace?: PresentationWorkspace | null);
-    /**
-     * Get current state
-     */
-    getState(): PresentationState;
-    /**
-     * Subscribe to state updates
-     */
-    onUpdate(handler: PresentationUpdateHandler): Unsubscribe;
-    /**
-     * Subscribe to errors
+    /** All conversations (user, assistant, error) */
+    get conversations(): readonly Conversation[];
+    /** Current agent status */
+    get status(): PresentationState["status"];
+    /** WebSocket connection state */
+    get connection(): ConnectionState;
+    /** Token usage and context metrics */
+    get metrics(): PresentationMetrics;
+    /** Workspace — file tree + operations. null if agent has no workspace. */
+    get workspace(): Workspace | null;
+    /**
+     * Subscribe to state changes.
+     * Compatible with React's useSyncExternalStore.
+     * Does NOT call listener immediately.
+     *
+     * @returns Unsubscribe function
      */
-    onError(handler: PresentationErrorHandler): Unsubscribe;
+    subscribe(listener: () => void): () => void;
     /**
-     * Send a message (text or content parts with files/images)
+     * Get state snapshot.
+     * Compatible with React's useSyncExternalStore.
      */
+    getSnapshot(): PresentationState;
+    /** Send a message */
     send(content: string | UserContentPart[]): Promise<void>;
-    /**
-     * Interrupt current response
-     */
+    /** Interrupt current response */
     interrupt(): Promise<void>;
-    /**
-     * Rewind conversation to a specific index.
-     *
-     * Calls runtime.rewind — a system-level operation that:
-     * 1. Truncates session messages
-     * 2. Resets circuit breaker
-     * 3. Emits rewind event → reducer updates state
-     *
-     * @param index - conversation index to rewind to (0-based, removes this index and after)
-     */
+    /** Rewind conversation to a specific index (removes index and everything after) */
     rewind(index: number): Promise<void>;
-    /**
-     * Edit a user message and resend.
-     * Rewinds to the message, replaces it, and sends the new content.
-     *
-     * @param index - conversation index of the user message to edit (0-based)
-     * @param content - new content to send
-     */
-    editAndResend(index: number, content: string | UserContentPart[]): Promise<void>;
-    /**
-     * Reset state
-     */
-    reset(): void;
-    /**
-     * Dispose and cleanup
-     */
+    /** Dispose and cleanup all subscriptions */
     dispose(): void;
-    private subscribeToEvents;
-    private notify;
-    private notifyError;
+    private _subscribeToEvents;
+    private _notify;
 }
 
 /**
@@ -840,4 +808,4 @@ interface PlatformConfig {
  */
 declare function createAgentX(config?: PlatformConfig): AgentXBuilder;
 
-export { type AgentConfig, type AgentHandle, type AgentX, type AgentXBuilder, type AgentXServer, type AssistantConversation, type BaseResponse, type Block, type ChatNamespace, type ConnectOptions, type Conversation, type ErrorConversation, type FileBlock, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageNamespace, type ImageRecord, type ImageUpdateResponse, type InstanceCreateResponse, type InstanceGetResponse, type InstanceInfo, type InstanceListResponse, type LLMNamespace, type LLMProviderCreateResponse, type LLMProviderDefaultResponse, type LLMProviderGetResponse, type LLMProviderListResponse, type LLMProviderUpdateResponse, type MaybeAsync, type MessageSendResponse, type PlatformConfig, Presentation, type PresentationErrorHandler, type PresentationMetrics, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type RuntimeNamespace, type ServeConfig, type SessionNamespace, type TextBlock, type ThinkingBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, initialMetrics, initialPresentationState, messagesToConversations, presentationReducer };
+export { type AgentConfig, type AgentHandle, type AgentX, type AgentXBuilder, type AgentXServer, type AssistantConversation, type BaseResponse, type Block, type ChatNamespace, type ConnectOptions, type Conversation, type ErrorConversation, type FileBlock, type FileTreeEntry, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageNamespace, type ImageRecord, type ImageUpdateResponse, type InstanceCreateResponse, type InstanceGetResponse, type InstanceInfo, type InstanceListResponse, type LLMNamespace, type LLMProviderCreateResponse, type LLMProviderDefaultResponse, type LLMProviderGetResponse, type LLMProviderListResponse, type LLMProviderUpdateResponse, type MaybeAsync, type MessageSendResponse, type PlatformConfig, Presentation, type PresentationMetrics, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationWorkspace, type RuntimeNamespace, type ServeConfig, type SessionNamespace, type TextBlock, type ThinkingBlock, type ToolBlock, type UserConversation, type Workspace, type WorkspaceState, addUserConversation, createAgentX, createInitialState, initialMetrics, initialPresentationState, messagesToConversations, presentationReducer };

package/dist/index.js

@@ -741,103 +741,111 @@ function messagesToConversations(messages) {
 
 // src/presentation/Presentation.ts
 var Presentation = class {
-  agentx;
-  instanceId;
-  state;
-  updateHandlers = /* @__PURE__ */ new Set();
-  errorHandlers = /* @__PURE__ */ new Set();
-  eventUnsubscribe = null;
-  /**
-   * Workspace operations — read, write, list files in the agent's workspace.
-   * null when the agent has no workspace.
-   */
-  workspace;
+  _agentx;
+  _instanceId;
+  _state;
+  _listeners = /* @__PURE__ */ new Set();
+  _legacyHandlers = /* @__PURE__ */ new Set();
+  _eventUnsubscribe = null;
+  _workspaceOps;
   constructor(agentx, instanceId, options, initialConversations, workspace) {
-    this.agentx = agentx;
-    this.instanceId = instanceId;
-    this.workspace = workspace ?? null;
-    this.state = initialConversations?.length ? { ...initialPresentationState, conversations: initialConversations } : createInitialState();
+    this._agentx = agentx;
+    this._instanceId = instanceId;
+    this._workspaceOps = workspace ?? null;
+    this._state = initialConversations?.length ? { ...initialPresentationState, conversations: initialConversations } : createInitialState();
     if (options?.onUpdate) {
-      this.updateHandlers.add(options.onUpdate);
+      this._legacyHandlers.add(options.onUpdate);
     }
-    if (options?.onError) {
-      this.errorHandlers.add(options.onError);
-    }
-    this.subscribeToEvents();
-    if (this.workspace) {
-      this.workspace.list(".").then((files) => {
-        this.state = { ...this.state, workspace: { files } };
-        this.notify();
+    this._subscribeToEvents();
+    if (this._workspaceOps) {
+      this._workspaceOps.list(".").then((files) => {
+        this._state = { ...this._state, workspace: { files } };
+        this._notify();
       });
     }
   }
-  /**
-   * Get current state
-   */
-  getState() {
-    return this.state;
+  // ==================== State (direct properties) ====================
+  /** All conversations (user, assistant, error) */
+  get conversations() {
+    return this._state.conversations;
   }
-  /**
-   * Subscribe to state updates
-   */
-  onUpdate(handler) {
-    this.updateHandlers.add(handler);
-    handler(this.state);
-    return () => {
-      this.updateHandlers.delete(handler);
+  /** Current agent status */
+  get status() {
+    return this._state.status;
+  }
+  /** WebSocket connection state */
+  get connection() {
+    return this._state.connection;
+  }
+  /** Token usage and context metrics */
+  get metrics() {
+    return this._state.metrics;
+  }
+  /** Workspace — file tree + operations. null if agent has no workspace. */
+  get workspace() {
+    if (!this._workspaceOps) return null;
+    const ops = this._workspaceOps;
+    const wsState = this._state.workspace;
+    return {
+      get files() {
+        return wsState?.files ?? [];
+      },
+      read: (path) => ops.read(path),
+      write: (path, content) => ops.write(path, content),
+      list: (path) => ops.list(path)
     };
   }
+  // ==================== Subscribe ====================
   /**
-   * Subscribe to errors
+   * Subscribe to state changes.
+   * Compatible with React's useSyncExternalStore.
+   * Does NOT call listener immediately.
+   *
+   * @returns Unsubscribe function
    */
-  onError(handler) {
-    this.errorHandlers.add(handler);
+  subscribe(listener) {
+    this._listeners.add(listener);
     return () => {
-      this.errorHandlers.delete(handler);
+      this._listeners.delete(listener);
     };
   }
   /**
-   * Send a message (text or content parts with files/images)
+   * Get state snapshot.
+   * Compatible with React's useSyncExternalStore.
    */
+  getSnapshot() {
+    return this._state;
+  }
+  // ==================== Actions ====================
+  /** Send a message */
   async send(content) {
-    this.state = addUserConversation(this.state, content);
-    this.notify();
+    this._state = addUserConversation(this._state, content);
+    this._notify();
     await new Promise((resolve) => setTimeout(resolve, 0));
     try {
-      await this.agentx.runtime.session.send(this.instanceId, content);
+      await this._agentx.runtime.session.send(this._instanceId, content);
     } catch (error) {
-      this.notifyError(error instanceof Error ? error : new Error(String(error)));
+      console.error("Presentation send error:", error);
     }
   }
-  /**
-   * Interrupt current response
-   */
+  /** Interrupt current response */
   async interrupt() {
     try {
-      await this.agentx.runtime.session.interrupt(this.instanceId);
+      await this._agentx.runtime.session.interrupt(this._instanceId);
     } catch (error) {
-      this.notifyError(error instanceof Error ? error : new Error(String(error)));
+      console.error("Presentation interrupt error:", error);
     }
   }
-  /**
-   * Rewind conversation to a specific index.
-   *
-   * Calls runtime.rewind — a system-level operation that:
-   * 1. Truncates session messages
-   * 2. Resets circuit breaker
-   * 3. Emits rewind event → reducer updates state
-   *
-   * @param index - conversation index to rewind to (0-based, removes this index and after)
-   */
+  /** Rewind conversation to a specific index (removes index and everything after) */
   async rewind(index) {
-    const conversations = this.state.conversations;
+    const conversations = this._state.conversations;
     if (index < 0 || index >= conversations.length) return;
     try {
-      const messages = await this.agentx.runtime.session.getMessages(this.instanceId);
+      const messages = await this._agentx.runtime.session.getMessages(this._instanceId);
       if (messages.length === 0) return;
       if (index === 0) {
-        await this.agentx.rpc("runtime.rewind", {
-          imageId: this.instanceId,
+        await this._agentx.rpc("runtime.rewind", {
+          imageId: this._instanceId,
           messageId: messages[0].id
         });
       } else {
@@ -853,78 +861,56 @@ var Presentation = class {
           }
         }
         if (msgIndex >= 0 && msgIndex < messages.length) {
-          await this.agentx.rpc("runtime.rewind", {
-            imageId: this.instanceId,
+          await this._agentx.rpc("runtime.rewind", {
+            imageId: this._instanceId,
             messageId: messages[msgIndex].id
           });
         }
       }
     } catch (error) {
-      this.notifyError(error instanceof Error ? error : new Error(String(error)));
+      console.error("Presentation rewind error:", error);
     }
   }
-  /**
-   * Edit a user message and resend.
-   * Rewinds to the message, replaces it, and sends the new content.
-   *
-   * @param index - conversation index of the user message to edit (0-based)
-   * @param content - new content to send
-   */
-  async editAndResend(index, content) {
-    await this.rewind(index);
-    await this.send(content);
-  }
-  /**
-   * Reset state
-   */
-  reset() {
-    this.state = createInitialState();
-    this.notify();
-  }
-  /**
-   * Dispose and cleanup
-   */
+  /** Dispose and cleanup all subscriptions */
   dispose() {
-    if (this.eventUnsubscribe) {
-      this.eventUnsubscribe();
-      this.eventUnsubscribe = null;
+    if (this._eventUnsubscribe) {
+      this._eventUnsubscribe();
+      this._eventUnsubscribe = null;
     }
-    this.updateHandlers.clear();
-    this.errorHandlers.clear();
+    this._listeners.clear();
+    this._legacyHandlers.clear();
   }
   // ==================== Private ====================
-  subscribeToEvents() {
-    this.eventUnsubscribe = this.agentx.onAny((event) => {
+  _subscribeToEvents() {
+    this._eventUnsubscribe = this._agentx.onAny((event) => {
       const eventWithContext = event;
       const eventAgentId = eventWithContext.context?.instanceId;
-      if (eventAgentId && eventAgentId !== this.instanceId) {
+      if (eventAgentId && eventAgentId !== this._instanceId) {
         const eventImageId = eventWithContext.context?.imageId;
-        if (!eventImageId || eventImageId !== this.instanceId) {
+        if (!eventImageId || eventImageId !== this._instanceId) {
           return;
         }
       }
-      const newState = presentationReducer(this.state, event);
-      if (newState !== this.state) {
-        this.state = newState;
-        this.notify();
+      const newState = presentationReducer(this._state, event);
+      if (newState !== this._state) {
+        this._state = newState;
+        this._notify();
       }
     });
   }
-  notify() {
-    for (const handler of this.updateHandlers) {
+  _notify() {
+    for (const listener of this._listeners) {
       try {
-        handler(this.state);
+        listener();
       } catch (error) {
-        console.error("Presentation update handler error:", error);
+        console.error("Presentation listener error:", error);
       }
     }
-  }
-  notifyError(error) {
-    for (const handler of this.errorHandlers) {
+    for (const handler of this._legacyHandlers) {
       try {
-        handler(error);
-      } catch (e) {
-        console.error("Presentation error handler error:", e);
+        handler(this._state);
+      } catch (error) {
+        console.error("Presentation handler error:", error);
       }
     }
   }