feat(agent): add dispose api and onDispose hook

multimodal/agent-interface/src/agent-event-stream.ts

@@ -523,11 +523,6 @@ export namespace AgentEventStream {
      */
     getEventsByType(types: AgentEventStream.EventType[], limit?: number): AgentEventStream.Event[];
 
-    /**
-     * Clear all events from the stream
-     */
-    clear(): void;
-
     /**
      * Subscribe to new events
      */
@@ -557,5 +552,10 @@ export namespace AgentEventStream {
      * Get tool call results since the last assistant message
      */
     getLatestToolResults(): { toolCallId: string; toolName: string; content: any }[];
+
+    /**
+     * Clear all events from the stream
+     */
+    dispose(): void;
   }
 }

multimodal/agent-interface/src/agent.ts

@@ -81,6 +81,22 @@ export interface IAgent<T extends AgentOptions = AgentOptions> {
    */
   status(): AgentStatus;
 
+  /**
+   * Dispose of the agent and release all resources
+   *
+   * This method should be called when the agent is no longer needed.
+   * It will:
+   * - Stop any running tasks
+   * - Clean up event listeners and subscriptions
+   * - Release system resources
+   * - Reset internal state
+   *
+   * After calling dispose(), the agent should not be used anymore.
+   *
+   * @returns A promise that resolves when disposal is complete
+   */
+  dispose(): Promise<void>;
+
   /**
    * Get the event stream associated with this agent
    *

multimodal/agent/src/agent/agent.ts

@@ -689,4 +689,29 @@ Provide concise and accurate responses.`;
       return registeredTools;
     }
   }
+
+  /**
+   * Override the disposal hook to perform Agent-specific cleanup
+   *
+   * @returns A promise that resolves when cleanup is complete
+   */
+  protected async onDispose(): Promise<void> {
+    this.logger.info('Starting Agent cleanup process');
+
+    // 1. Abort and end any running execution
+    if (this.executionController.isExecuting()) {
+      this.logger.info('Aborting running execution during disposal');
+      this.executionController.abort();
+
+      try {
+        await this.executionController.endExecution(AgentStatus.IDLE);
+      } catch (error) {
+        this.logger.warn(`Error ending execution during disposal: ${error}`);
+      }
+    }
+
+    // 2. Clear event stream
+    this.eventStream.dispose();
+    this.logger.info('Agent cleanup completed successfully');
+  }
 }

multimodal/agent/src/agent/base-agent.ts

@@ -34,6 +34,7 @@ import { getLogger } from '../utils/logger';
 export abstract class BaseAgent<T extends AgentOptions = AgentOptions> {
   protected logger = getLogger('BaseAgent');
   private shouldTerminateLoop = false;
+  private isDisposed = false;
 
   constructor(protected options: T) {}
 
@@ -46,6 +47,66 @@ export abstract class BaseAgent<T extends AgentOptions = AgentOptions> {
     // Derived classes can override to add initialization logic
   }
 
+  /**
+   * Dispose of the agent and release all resources
+   *
+   * This method provides a base implementation that:
+   * - Marks the agent as disposed
+   * - Resets internal state
+   * - Calls the disposal hook for derived classes
+   *
+   * Derived classes should override onDispose() to add specific cleanup logic.
+   *
+   * @returns A promise that resolves when disposal is complete
+   */
+  public async dispose(): Promise<void> {
+    if (this.isDisposed) {
+      this.logger.debug('Agent already disposed, ignoring dispose call');
+      return;
+    }
+
+    this.logger.info('Disposing agent and releasing resources');
+
+    try {
+      // Call the disposal hook for derived classes
+      await this.onDispose();
+
+      // Reset internal state
+      this.shouldTerminateLoop = false;
+      this.isDisposed = true;
+
+      this.logger.info('Agent disposal completed successfully');
+    } catch (error) {
+      this.logger.error(`Error during agent disposal: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Check if the agent has been disposed
+   *
+   * @returns True if the agent has been disposed
+   */
+  protected isAgentDisposed(): boolean {
+    return this.isDisposed;
+  }
+
+  /**
+   * Hook called during agent disposal
+   *
+   * Derived classes can override this method to perform custom cleanup:
+   * - Close connections
+   * - Clear timers
+   * - Release custom resources
+   * - Clean up event listeners
+   *
+   * @returns A promise that resolves when custom disposal is complete
+   */
+  protected onDispose(): Promise<void> | void {
+    // Default implementation does nothing
+    // Derived classes can override to add disposal logic
+  }
+
   /**
    * Hook called before sending a request to the LLM
    * This allows subclasses to inspect the request before it's sent

multimodal/agent/src/agent/event-stream.ts

@@ -126,14 +126,6 @@ export class AgentEventStreamProcessor implements AgentEventStream.Processor {
     }));
   }
 
-  /**
-   * Clear all events from the stream
-   */
-  clear(): void {
-    this.events = [];
-    this.logger.debug('Event stream cleared');
-  }
-
   /**
    * Subscribe to new events
    */
@@ -211,4 +203,13 @@ export class AgentEventStreamProcessor implements AgentEventStream.Processor {
       this.logger.debug('Unsubscribed from streaming events');
     };
   }
+
+  /**
+   * Clear all events from the stream
+   */
+  dispose(): void {
+    this.events = [];
+    this.subscribers = [];
+    this.logger.debug('Event stream cleared');
+  }
 }