@dexto/core 1.3.0 → 1.4.0

package/dist/agent/DextoAgent.js

@@ -2,8 +2,10 @@ import {
   __decorateElement,
   __decoratorStart,
   __runInitializers
-} from "../chunk-C6A6W6XS.js";
+} from "../chunk-PTJYTZNU.js";
 var _DextoAgent_decorators, _init;
+import { randomUUID } from "crypto";
+import { setMaxListeners } from "events";
 import { expandMessageReferences } from "../resources/index.js";
 import { expandBlobReferences } from "../context/utils.js";
 import { PromptManager } from "../prompts/index.js";
@@ -19,6 +21,7 @@ import { LLMError } from "../llm/errors.js";
 import { AgentError } from "./errors.js";
 import { MCPError } from "../mcp/errors.js";
 import { DextoRuntimeError } from "../errors/DextoRuntimeError.js";
+import { DextoValidationError } from "../errors/DextoValidationError.js";
 import { ensureOk } from "../errors/result-bridge.js";
 import { fail, zodToIssues } from "../utils/result.js";
 import { resolveAndValidateMcpServerConfig } from "../mcp/resolver.js";
@@ -103,6 +106,8 @@ class DextoAgent {
   // Approval handler for manual tool confirmation and elicitation
   // Set via setApprovalHandler() before start() if needed
   approvalHandler;
+  // Active stream controllers per session - allows cancel() to abort iterators
+  activeStreamControllers = /* @__PURE__ */ new Map();
   // Logger instance for this agent (dependency injection)
   logger;
   /**
@@ -178,10 +183,6 @@ Either:
       for (const subscriber of this.eventSubscribers) {
         subscriber.subscribe(this.agentEventBus);
       }
-      const fileTransport = this.config.logger?.transports?.find((t) => t.type === "file");
-      if (fileTransport && "path" in fileTransport) {
-        console.log(`\u{1F4CB} Logs available at: ${fileTransport.path}`);
-      }
     } catch (error) {
       this.logger.error("Failed to start DextoAgent", {
         error: error instanceof Error ? error.message : String(error)
@@ -312,173 +313,88 @@ Either:
   }
   // ============= CORE AGENT FUNCTIONALITY =============
   /**
-   * Main method for processing user input.
-   * Processes user input through the agent's LLM service and returns the response.
+   * Process user input and return the response.
+   *
+   * @deprecated Use generate() or stream() instead for multi-image support.
+   * This method is kept for backward compatibility and only supports single image/file.
    *
-   * @param textInput - The user's text message or query to process
-   * @param imageDataInput - Optional image data and MIME type for multimodal input
-   * @param fileDataInput - Optional file data and MIME type for file input
+   * @param textInput - The user's text message
+   * @param imageDataInput - Optional single image data
+   * @param fileDataInput - Optional single file data
    * @param sessionId - Session ID for the conversation (required)
-   * @param stream - Whether to stream the response (default: false)
-   * @returns Promise that resolves to the AI's response text, or null if no significant response
-   * @throws Error if processing fails
+   * @param _stream - Ignored (streaming is handled internally)
+   * @returns Promise that resolves to the AI's response text
    */
-  async run(textInput, imageDataInput, fileDataInput, sessionId, stream = false) {
-    this.ensureStarted();
-    if (!sessionId || typeof sessionId !== "string") {
-      throw new Error("sessionId is required and must be a non-empty string");
+  async run(textInput, imageDataInput, fileDataInput, sessionId, _stream = false) {
+    const parts = [];
+    if (textInput) {
+      parts.push({ type: "text", text: textInput });
     }
-    const targetSessionId = sessionId;
-    const activeContext = context.active();
-    const span = trace.getActiveSpan();
-    if (span) {
-      span.setAttribute("sessionId", targetSessionId);
+    if (imageDataInput) {
+      parts.push({
+        type: "image",
+        image: imageDataInput.image,
+        mimeType: imageDataInput.mimeType
+      });
     }
-    const existingBaggage = propagation.getBaggage(activeContext);
-    const baggageEntries = {};
-    if (existingBaggage) {
-      existingBaggage.getAllEntries().forEach(([key, entry]) => {
-        baggageEntries[key] = { ...entry };
+    if (fileDataInput) {
+      parts.push({
+        type: "file",
+        data: fileDataInput.data,
+        mimeType: fileDataInput.mimeType,
+        ...fileDataInput.filename && { filename: fileDataInput.filename }
       });
     }
-    baggageEntries.sessionId = { ...baggageEntries.sessionId, value: targetSessionId };
-    const updatedContext = propagation.setBaggage(
-      activeContext,
-      propagation.createBaggage(baggageEntries)
-    );
-    const verifyBaggage = propagation.getBaggage(updatedContext);
-    this.logger.debug(
-      `Baggage after setting sessionId: ${JSON.stringify(
-        Array.from(verifyBaggage?.getAllEntries() || [])
-      )}`
-    );
-    return await context.with(updatedContext, async () => {
-      try {
-        const llmConfig = this.stateManager.getLLMConfig(targetSessionId);
-        const validation = validateInputForLLM(
-          {
-            text: textInput,
-            ...imageDataInput && { imageData: imageDataInput },
-            ...fileDataInput && { fileData: fileDataInput }
-          },
-          {
-            provider: llmConfig.provider,
-            model: llmConfig.model
-          },
-          this.logger
-        );
-        ensureOk(validation, this.logger);
-        const session = await this.sessionManager.getSession(targetSessionId) || await this.sessionManager.createSession(targetSessionId);
-        this.logger.debug(
-          `DextoAgent.run: sessionId=${targetSessionId}, textLength=${textInput?.length ?? 0}, hasImage=${Boolean(
-            imageDataInput
-          )}, hasFile=${Boolean(fileDataInput)}`
-        );
-        let finalText = textInput;
-        let finalImageData = imageDataInput;
-        if (textInput && textInput.includes("@")) {
-          try {
-            const resources = await this.resourceManager.list();
-            const expansion = await expandMessageReferences(
-              textInput,
-              resources,
-              (uri) => this.resourceManager.read(uri)
-            );
-            if (expansion.unresolvedReferences.length > 0) {
-              const unresolvedNames = expansion.unresolvedReferences.map((ref) => ref.originalRef).join(", ");
-              this.logger.warn(
-                `Could not resolve ${expansion.unresolvedReferences.length} resource reference(s): ${unresolvedNames}`
-              );
-            }
-            const MAX_EXPANDED_SIZE = 5 * 1024 * 1024;
-            const expandedSize = Buffer.byteLength(expansion.expandedMessage, "utf-8");
-            if (expandedSize > MAX_EXPANDED_SIZE) {
-              this.logger.warn(
-                `Expanded message size (${(expandedSize / 1024 / 1024).toFixed(2)}MB) exceeds limit (${MAX_EXPANDED_SIZE / 1024 / 1024}MB). Content may be truncated.`
-              );
-            }
-            finalText = expansion.expandedMessage;
-            if (expansion.extractedImages.length > 0 && !imageDataInput) {
-              const firstImage = expansion.extractedImages[0];
-              if (firstImage) {
-                finalImageData = {
-                  image: firstImage.image,
-                  mimeType: firstImage.mimeType
-                };
-                this.logger.debug(
-                  `Using extracted image: ${firstImage.name} (${firstImage.mimeType})`
-                );
-              }
-            }
-          } catch (error) {
-            this.logger.error(
-              `Failed to expand resource references: ${error instanceof Error ? error.message : String(error)}. Continuing with original message.`
-            );
-          }
-        }
-        if (!finalText.trim() && !finalImageData && !fileDataInput) {
-          this.logger.warn(
-            "Resource expansion resulted in empty content. Using original message."
-          );
-          finalText = textInput;
-        }
-        const response = await session.run(
-          finalText,
-          finalImageData,
-          fileDataInput,
-          stream
-        );
-        this.sessionManager.incrementMessageCount(session.id).catch(
-          (error) => this.logger.warn(
-            `Failed to increment message count: ${error instanceof Error ? error.message : String(error)}`
-          )
-        );
-        return response;
-      } catch (error) {
-        this.logger.error(
-          `Error during DextoAgent.run: ${error instanceof Error ? error.message : JSON.stringify(error)}`
-        );
-        throw error;
-      }
-    });
+    const response = await this.generate(parts.length > 0 ? parts : textInput, sessionId);
+    return response.content;
   }
   /**
    * Generate a complete response (waits for full completion).
    * This is the recommended method for non-streaming use cases.
    *
-   * @param message The user's message
-   * @param options Configuration options (sessionId is required, imageData, fileData, signal are optional)
+   * @param content String message or array of content parts (text, images, files)
+   * @param sessionId Session ID for the conversation
+   * @param options Optional configuration (signal for cancellation)
    * @returns Promise that resolves to the complete response
    *
    * @example
    * ```typescript
-   * const response = await agent.generate("What is 2+2?", { sessionId: "default" });
+   * // Simple text message
+   * const response = await agent.generate('What is 2+2?', 'session-1');
    * console.log(response.content); // "4"
-   * console.log(response.usage.totalTokens); // 50
+   *
+   * // Multimodal with image
+   * const response = await agent.generate(
+   *     [
+   *         { type: 'text', text: 'Describe this image' },
+   *         { type: 'image', image: base64Data, mimeType: 'image/png' }
+   *     ],
+   *     'session-1'
+   * );
    * ```
    */
-  async generate(message, options) {
+  async generate(content, sessionId, options) {
     const events = [];
-    for await (const event of await this.stream(message, options)) {
+    for await (const event of await this.stream(content, sessionId, options)) {
       events.push(event);
     }
-    const errorEvent = events.find(
-      (e) => e.name === "llm:error"
+    const fatalErrorEvent = events.find(
+      (e) => e.name === "llm:error" && e.recoverable !== true
     );
-    if (errorEvent) {
-      if (errorEvent.error instanceof DextoRuntimeError) {
-        throw errorEvent.error;
+    if (fatalErrorEvent) {
+      if (fatalErrorEvent.error instanceof DextoRuntimeError || fatalErrorEvent.error instanceof DextoValidationError) {
+        throw fatalErrorEvent.error;
       }
-      const llmConfig = this.stateManager.getLLMConfig(options.sessionId);
+      const llmConfig = this.stateManager.getLLMConfig(sessionId);
       throw LLMError.generationFailed(
-        errorEvent.error.message,
+        fatalErrorEvent.error.message,
         llmConfig.provider,
         llmConfig.model
       );
     }
     const responseEvent = events.find((e) => e.name === "llm:response");
     if (!responseEvent || responseEvent.name !== "llm:response") {
-      const llmConfig = this.stateManager.getLLMConfig(options.sessionId);
+      const llmConfig = this.stateManager.getLLMConfig(sessionId);
       throw LLMError.generationFailed(
         "Stream did not complete successfully - no response received",
         llmConfig.provider,
@@ -514,7 +430,7 @@ Either:
       reasoning: responseEvent.reasoning,
       usage,
       toolCalls,
-      sessionId: options.sessionId
+      sessionId
     };
   }
   /**
@@ -528,36 +444,38 @@ Either:
    * Events are forwarded directly from the AgentEventBus with no mapping layer,
    * providing a unified event system across all API layers.
    *
-   * @param message The user's message
-   * @param options Configuration options (sessionId is required, imageData, fileData, signal are optional)
+   * @param content String message or array of content parts (text, images, files)
+   * @param sessionId Session ID for the conversation
+   * @param options Optional configuration (signal for cancellation)
    * @returns AsyncIterator that yields StreamingEvent objects (core events with name property)
    *
    * @example
    * ```typescript
-   * for await (const event of await agent.stream("Write a poem", { sessionId: "default" })) {
-   *   if (event.name === 'llm:chunk') {
-   *     process.stdout.write(event.content);
-   *   }
-   *   if (event.name === 'llm:tool-call') {
-   *     console.log(`\n[Using ${event.toolName}]\n`);
-   *   }
+   * // Simple text
+   * for await (const event of await agent.stream('Write a poem', 'session-1')) {
+   *   if (event.name === 'llm:chunk') process.stdout.write(event.content);
    * }
+   *
+   * // Multimodal
+   * for await (const event of await agent.stream(
+   *     [{ type: 'text', text: 'Describe this' }, { type: 'image', image: data, mimeType: 'image/png' }],
+   *     'session-1'
+   * )) { ... }
    * ```
    */
-  async stream(message, options) {
+  async stream(content, sessionId, options) {
     this.ensureStarted();
-    if (!options.sessionId) {
-      throw new Error("sessionId is required in StreamOptions");
+    if (!sessionId) {
+      throw AgentError.apiValidationError("sessionId is required");
     }
-    const sessionId = options.sessionId;
-    const imageData = options.imageData;
-    const fileData = options.fileData;
-    const signal = options.signal;
+    const signal = options?.signal;
+    let contentParts = typeof content === "string" ? [{ type: "text", text: content }] : [...content];
     const eventQueue = [];
     let completed = false;
-    let _streamError = null;
     const controller = new AbortController();
     const cleanupSignal = controller.signal;
+    this.activeStreamControllers.set(sessionId, controller);
+    setMaxListeners(30, cleanupSignal);
     const listeners = [];
     const cleanupListeners = () => {
       if (listeners.length === 0) {
@@ -570,6 +488,7 @@ Either:
         );
       }
       listeners.length = 0;
+      this.activeStreamControllers.delete(sessionId);
     };
     if (signal) {
       const abortHandler = () => {
@@ -593,7 +512,6 @@ Either:
     const responseListener = (data) => {
       if (data.sessionId !== sessionId) return;
       eventQueue.push({ name: "llm:response", ...data });
-      completed = true;
     };
     this.agentEventBus.on("llm:response", responseListener, { signal: cleanupSignal });
     listeners.push({ event: "llm:response", listener: responseListener });
@@ -650,34 +568,191 @@ Either:
       signal: cleanupSignal
     });
     listeners.push({ event: "approval:response", listener: approvalResponseListener });
-    const imageDataForRun = imageData ? {
-      image: typeof imageData.image === "string" ? imageData.image : imageData.image.toString(),
-      mimeType: imageData.mimeType || "image/png"
-    } : void 0;
-    const fileDataForRun = fileData ? {
-      data: typeof fileData.data === "string" ? fileData.data : fileData.data.toString(),
-      mimeType: fileData.mimeType,
-      ...fileData.filename && { filename: fileData.filename }
-    } : void 0;
-    this.run(message, imageDataForRun, fileDataForRun, sessionId, true).catch((err) => {
-      const error = err instanceof Error ? err : new Error(String(err));
-      _streamError = error;
+    const toolRunningListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "tool:running", ...data });
+    };
+    this.agentEventBus.on("tool:running", toolRunningListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "tool:running", listener: toolRunningListener });
+    const messageQueuedListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "message:queued", ...data });
+    };
+    this.agentEventBus.on("message:queued", messageQueuedListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "message:queued", listener: messageQueuedListener });
+    const messageDequeuedListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "message:dequeued", ...data });
+    };
+    this.agentEventBus.on("message:dequeued", messageDequeuedListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "message:dequeued", listener: messageDequeuedListener });
+    const runCompleteListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "run:complete", ...data });
       completed = true;
-      this.logger.error(`Error in DextoAgent.stream: ${error.message}`);
-      const errorEvent = {
-        name: "llm:error",
-        error,
-        recoverable: false,
-        context: "run_failed",
-        sessionId
-      };
-      eventQueue.push(errorEvent);
+    };
+    this.agentEventBus.on("run:complete", runCompleteListener, {
+      signal: cleanupSignal
     });
+    listeners.push({ event: "run:complete", listener: runCompleteListener });
+    (async () => {
+      const activeContext = context.active();
+      const activeSpan = trace.getActiveSpan();
+      if (activeSpan) {
+        activeSpan.setAttribute("sessionId", sessionId);
+      }
+      const existingBaggage = propagation.getBaggage(activeContext);
+      const baggageEntries = {};
+      if (existingBaggage) {
+        existingBaggage.getAllEntries().forEach(([key, entry]) => {
+          baggageEntries[key] = { ...entry };
+        });
+      }
+      baggageEntries.sessionId = { ...baggageEntries.sessionId, value: sessionId };
+      const updatedContext = propagation.setBaggage(
+        activeContext,
+        propagation.createBaggage(baggageEntries)
+      );
+      await context.with(updatedContext, async () => {
+        try {
+          const llmConfig = this.stateManager.getLLMConfig(sessionId);
+          const textParts = contentParts.filter(
+            (p) => p.type === "text"
+          );
+          const textContent = textParts.map((p) => p.text).join("\n");
+          const imageParts = contentParts.filter(
+            (p) => p.type === "image"
+          );
+          const fileParts = contentParts.filter(
+            (p) => p.type === "file"
+          );
+          this.logger.debug(
+            `DextoAgent.stream: sessionId=${sessionId}, textLength=${textContent?.length ?? 0}, imageCount=${imageParts.length}, fileCount=${fileParts.length}`
+          );
+          const textValidation = validateInputForLLM(
+            { text: textContent },
+            { provider: llmConfig.provider, model: llmConfig.model },
+            this.logger
+          );
+          ensureOk(textValidation, this.logger);
+          for (const imagePart of imageParts) {
+            const imageValidation = validateInputForLLM(
+              {
+                imageData: {
+                  image: typeof imagePart.image === "string" ? imagePart.image : imagePart.image.toString(),
+                  mimeType: imagePart.mimeType || "image/png"
+                }
+              },
+              { provider: llmConfig.provider, model: llmConfig.model },
+              this.logger
+            );
+            ensureOk(imageValidation, this.logger);
+          }
+          for (const filePart of fileParts) {
+            const fileValidation = validateInputForLLM(
+              {
+                fileData: {
+                  data: typeof filePart.data === "string" ? filePart.data : filePart.data.toString(),
+                  mimeType: filePart.mimeType
+                }
+              },
+              { provider: llmConfig.provider, model: llmConfig.model },
+              this.logger
+            );
+            ensureOk(fileValidation, this.logger);
+          }
+          if (textContent.includes("@")) {
+            try {
+              const resources = await this.resourceManager.list();
+              const expansion = await expandMessageReferences(
+                textContent,
+                resources,
+                (uri) => this.resourceManager.read(uri)
+              );
+              if (expansion.unresolvedReferences.length > 0) {
+                const unresolvedNames = expansion.unresolvedReferences.map((ref) => ref.originalRef).join(", ");
+                this.logger.warn(
+                  `Could not resolve ${expansion.unresolvedReferences.length} resource reference(s): ${unresolvedNames}`
+                );
+              }
+              const MAX_EXPANDED_SIZE = 5 * 1024 * 1024;
+              const expandedSize = Buffer.byteLength(
+                expansion.expandedMessage,
+                "utf-8"
+              );
+              if (expandedSize > MAX_EXPANDED_SIZE) {
+                this.logger.warn(
+                  `Expanded message size (${(expandedSize / 1024 / 1024).toFixed(2)}MB) exceeds limit (${MAX_EXPANDED_SIZE / 1024 / 1024}MB). Content may be truncated.`
+                );
+              }
+              contentParts = contentParts.filter((p) => p.type !== "text");
+              if (expansion.expandedMessage.trim()) {
+                contentParts.unshift({
+                  type: "text",
+                  text: expansion.expandedMessage
+                });
+              }
+              for (const img of expansion.extractedImages) {
+                contentParts.push({
+                  type: "image",
+                  image: img.image,
+                  mimeType: img.mimeType
+                });
+                this.logger.debug(
+                  `Added extracted image: ${img.name} (${img.mimeType})`
+                );
+              }
+            } catch (error) {
+              this.logger.error(
+                `Failed to expand resource references: ${error instanceof Error ? error.message : String(error)}. Continuing with original message.`
+              );
+            }
+          }
+          const hasTextContent = contentParts.some(
+            (p) => p.type === "text" && p.text.trim()
+          );
+          const hasMediaContent = contentParts.some(
+            (p) => p.type === "image" || p.type === "file"
+          );
+          if (!hasTextContent && !hasMediaContent) {
+            this.logger.warn(
+              "Resource expansion resulted in empty content. Using original message."
+            );
+            contentParts = [{ type: "text", text: textContent }];
+          }
+          const session = await this.sessionManager.getSession(sessionId) || await this.sessionManager.createSession(sessionId);
+          await session.stream(contentParts, signal ? { signal } : void 0);
+          this.sessionManager.incrementMessageCount(session.id).catch(
+            (error) => this.logger.warn(
+              `Failed to increment message count: ${error instanceof Error ? error.message : String(error)}`
+            )
+          );
+        } catch (err) {
+          const error = err instanceof DextoRuntimeError || err instanceof DextoValidationError ? err : err instanceof Error ? err : AgentError.streamFailed(String(err));
+          completed = true;
+          this.logger.error(`Error in DextoAgent.stream: ${error.message}`);
+          const errorEvent = {
+            name: "llm:error",
+            error,
+            recoverable: false,
+            context: "run_failed",
+            sessionId
+          };
+          eventQueue.push(errorEvent);
+        }
+      });
+    })();
     const iterator = {
       async next() {
         while (!completed && eventQueue.length === 0) {
           await new Promise((resolve) => setTimeout(resolve, 0));
-          if (signal?.aborted) {
+          if (signal?.aborted || cleanupSignal.aborted) {
             cleanupListeners();
             controller.abort();
             return { done: true, value: void 0 };
@@ -705,6 +780,73 @@ Either:
     };
     return iterator;
   }
+  /**
+   * Check if a session is currently processing a message.
+   * @param sessionId Session id
+   * @returns true if the session is busy processing; false otherwise
+   */
+  async isSessionBusy(sessionId) {
+    this.ensureStarted();
+    const session = await this.sessionManager.getSession(sessionId, false);
+    return session?.isBusy() ?? false;
+  }
+  /**
+   * Queue a message for processing when a session is busy.
+   * The message will be injected into the conversation when the current turn completes.
+   *
+   * @param sessionId Session id
+   * @param message The user message to queue
+   * @returns Queue position and message ID
+   * @throws Error if session doesn't support message queueing
+   */
+  async queueMessage(sessionId, message) {
+    this.ensureStarted();
+    const session = await this.sessionManager.getSession(sessionId, false);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    return session.queueMessage(message);
+  }
+  /**
+   * Get all queued messages for a session.
+   * @param sessionId Session id
+   * @returns Array of queued messages
+   */
+  async getQueuedMessages(sessionId) {
+    this.ensureStarted();
+    const session = await this.sessionManager.getSession(sessionId, false);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    return session.getQueuedMessages();
+  }
+  /**
+   * Remove a queued message.
+   * @param sessionId Session id
+   * @param messageId The ID of the queued message to remove
+   * @returns true if message was found and removed, false otherwise
+   */
+  async removeQueuedMessage(sessionId, messageId) {
+    this.ensureStarted();
+    const session = await this.sessionManager.getSession(sessionId, false);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    return session.removeQueuedMessage(messageId);
+  }
+  /**
+   * Clear all queued messages for a session.
+   * @param sessionId Session id
+   * @returns Number of messages that were cleared
+   */
+  async clearMessageQueue(sessionId) {
+    this.ensureStarted();
+    const session = await this.sessionManager.getSession(sessionId, false);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    return session.clearMessageQueue();
+  }
   /**
    * Cancels the currently running turn for a session.
    * Safe to call even if no run is in progress.
@@ -714,13 +856,20 @@ Either:
   async cancel(sessionId) {
     this.ensureStarted();
     if (!sessionId || typeof sessionId !== "string") {
-      throw new Error("sessionId is required and must be a non-empty string");
+      throw AgentError.apiValidationError(
+        "sessionId is required and must be a non-empty string"
+      );
+    }
+    const streamController = this.activeStreamControllers.get(sessionId);
+    if (streamController) {
+      streamController.abort();
+      this.activeStreamControllers.delete(sessionId);
     }
     const existing = await this.sessionManager.getSession(sessionId, false);
     if (existing) {
       return existing.cancel();
     }
-    return false;
+    return !!streamController;
   }
   // ============= SESSION MANAGEMENT =============
   /**
@@ -827,7 +976,6 @@ Either:
     const llmConfig = this.getEffectiveConfig(sessionId).llm;
     const result = await generateSessionTitle(
       llmConfig,
-      llmConfig.router,
       this.toolManager,
       this.systemPromptManager,
       this.resourceManager,
@@ -910,7 +1058,9 @@ Either:
   async resetConversation(sessionId) {
     this.ensureStarted();
     if (!sessionId || typeof sessionId !== "string") {
-      throw new Error("sessionId is required and must be a non-empty string");
+      throw AgentError.apiValidationError(
+        "sessionId is required and must be a non-empty string"
+      );
     }
     try {
       await this.sessionManager.resetSession(sessionId);
@@ -925,6 +1075,37 @@ Either:
       throw error;
     }
   }
+  /**
+   * Clears the context window for a session without deleting history.
+   *
+   * This adds a "context clear" marker to the conversation history. When the
+   * context is loaded for LLM, messages before this marker are filtered out
+   * (via filterCompacted). The full history remains in the database for
+   * review via /resume or session history.
+   *
+   * Use this for /clear command - it preserves history but gives a fresh
+   * context window to the LLM.
+   *
+   * @param sessionId Session ID (required)
+   */
+  async clearContext(sessionId) {
+    this.ensureStarted();
+    if (!sessionId || typeof sessionId !== "string") {
+      throw AgentError.apiValidationError(
+        "sessionId is required and must be a non-empty string"
+      );
+    }
+    const session = await this.sessionManager.getSession(sessionId);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    const contextManager = session.getContextManager();
+    await contextManager.clearContext();
+    this.logger.info(`Context cleared for session: ${sessionId}`);
+    this.agentEventBus.emit("context:cleared", {
+      sessionId
+    });
+  }
   // ============= LLM MANAGEMENT =============
   /**
    * Gets the current LLM configuration with all defaults applied.
@@ -939,7 +1120,7 @@ Either:
    * This is a comprehensive method that handles ALL validation, configuration building, and switching internally.
    *
    * Design:
-   * - Input: Partial<LLMConfig> (allows optional fields like maxIterations?, router?)
+   * - Input: Partial<LLMConfig> (allows optional fields like maxIterations?)
    * - Output: LLMConfig (user-friendly type with all defaults applied)
    *
    * Key features:
@@ -964,8 +1145,8 @@ Either:
    * // Switch to a different provider with explicit API key
    * await agent.switchLLM({ provider: 'anthropic', model: 'claude-4-sonnet-20250514', apiKey: 'sk-ant-...' });
    *
-   * // Switch with router and session options
-   * await agent.switchLLM({ provider: 'anthropic', model: 'claude-4-sonnet-20250514', router: 'in-built' }, 'user-123');
+   * // Switch with session options
+   * await agent.switchLLM({ provider: 'anthropic', model: 'claude-4-sonnet-20250514' }, 'user-123');
    *
    * // Switch for all sessions
    * await agent.switchLLM({ model: 'gpt-5' }, '*');
@@ -1117,19 +1298,23 @@ Either:
   }
   // ============= MCP SERVER MANAGEMENT =============
   /**
-   * Connects a new MCP server and adds it to the runtime configuration.
+   * Adds a new MCP server to the runtime configuration and connects it if enabled.
    * This method handles validation, state management, and establishing the connection.
    *
-   * @param name The name of the server to connect.
+   * @param name The name of the server to add.
    * @param config The configuration object for the server.
    * @throws DextoError if validation fails or connection fails
    */
-  async connectMcpServer(name, config) {
+  async addMcpServer(name, config) {
     this.ensureStarted();
     const existingServerNames = Object.keys(this.stateManager.getRuntimeConfig().mcpServers);
     const validation = resolveAndValidateMcpServerConfig(name, config, existingServerNames);
     const validatedConfig = ensureOk(validation, this.logger);
-    this.stateManager.addMcpServer(name, validatedConfig);
+    this.stateManager.setMcpServer(name, validatedConfig);
+    if (validatedConfig.enabled === false) {
+      this.logger.info(`MCP server '${name}' added but not connected (disabled)`);
+      return;
+    }
     try {
       await this.mcpManager.connectServer(name, validatedConfig);
       await this.toolManager.refresh();
@@ -1141,9 +1326,7 @@ Either:
         tools: Object.keys(await this.toolManager.getAllTools()),
         source: "mcp"
       });
-      this.logger.info(
-        `DextoAgent: Successfully added and connected to MCP server '${name}'.`
-      );
+      this.logger.info(`MCP server '${name}' added and connected successfully`);
       const warnings = validation.issues.filter((i) => i.severity === "warning");
       if (warnings.length > 0) {
         this.logger.warn(
@@ -1152,9 +1335,7 @@ Either:
       }
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      this.logger.error(
-        `DextoAgent: Failed to connect to MCP server '${name}': ${errorMessage}`
-      );
+      this.logger.error(`Failed to connect MCP server '${name}': ${errorMessage}`);
       this.stateManager.removeMcpServer(name);
       this.agentEventBus.emit("mcp:server-connected", {
         name,
@@ -1165,14 +1346,81 @@ Either:
     }
   }
   /**
-   * Removes and disconnects an MCP server.
+   * @deprecated Use `addMcpServer` instead. This method will be removed in a future version.
+   */
+  async connectMcpServer(name, config) {
+    return this.addMcpServer(name, config);
+  }
+  /**
+   * Enables a disabled MCP server and connects it.
+   * Updates the runtime state to enabled=true and establishes the connection.
+   *
+   * @param name The name of the server to enable.
+   * @throws MCPError if server is not found or connection fails
+   */
+  async enableMcpServer(name) {
+    this.ensureStarted();
+    const currentConfig = this.stateManager.getRuntimeConfig().mcpServers[name];
+    if (!currentConfig) {
+      throw MCPError.serverNotFound(name);
+    }
+    const updatedConfig = { ...currentConfig, enabled: true };
+    this.stateManager.setMcpServer(name, updatedConfig);
+    try {
+      await this.mcpManager.connectServer(name, updatedConfig);
+      await this.toolManager.refresh();
+      this.agentEventBus.emit("mcp:server-connected", { name, success: true });
+      this.logger.info(`MCP server '${name}' enabled and connected`);
+    } catch (error) {
+      this.stateManager.setMcpServer(name, currentConfig);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Failed to enable MCP server '${name}': ${errorMessage}`);
+      throw MCPError.connectionFailed(name, errorMessage);
+    }
+  }
+  /**
+   * Disables an MCP server and disconnects it.
+   * Updates the runtime state to enabled=false and closes the connection.
+   *
+   * @param name The name of the server to disable.
+   * @throws MCPError if server is not found or disconnect fails
+   */
+  async disableMcpServer(name) {
+    this.ensureStarted();
+    const currentConfig = this.stateManager.getRuntimeConfig().mcpServers[name];
+    if (!currentConfig) {
+      throw MCPError.serverNotFound(name);
+    }
+    const updatedConfig = { ...currentConfig, enabled: false };
+    this.stateManager.setMcpServer(name, updatedConfig);
+    try {
+      await this.mcpManager.removeClient(name);
+      await this.toolManager.refresh();
+      this.logger.info(`MCP server '${name}' disabled and disconnected`);
+    } catch (error) {
+      this.stateManager.setMcpServer(name, currentConfig);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Failed to disable MCP server '${name}': ${errorMessage}`);
+      throw MCPError.disconnectionFailed(name, errorMessage);
+    }
+  }
+  /**
+   * Removes and disconnects an MCP server completely.
+   * Use this for deleting a server - removes from both runtime state and disconnects.
    * @param name The name of the server to remove.
+   * @throws MCPError if disconnection fails
    */
   async removeMcpServer(name) {
     this.ensureStarted();
-    await this.mcpManager.removeClient(name);
-    this.stateManager.removeMcpServer(name);
-    await this.toolManager.refresh();
+    try {
+      await this.mcpManager.removeClient(name);
+      this.stateManager.removeMcpServer(name);
+      await this.toolManager.refresh();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Failed to remove MCP server '${name}': ${errorMessage}`);
+      throw MCPError.disconnectionFailed(name, errorMessage);
+    }
   }
   /**
    * Restarts an MCP server by disconnecting and reconnecting with its original configuration.
@@ -1205,13 +1453,18 @@ Either:
   /**
    * Executes a tool from any source (MCP servers, custom tools, or internal tools).
    * This is the unified interface for tool execution that can handle all tool types.
+   *
+   * Note: This is for direct/programmatic tool execution outside of LLM flow.
+   * A toolCallId is generated automatically for tracking purposes.
+   *
    * @param toolName The name of the tool to execute
    * @param args The arguments to pass to the tool
    * @returns The result of the tool execution
    */
   async executeTool(toolName, args) {
     this.ensureStarted();
-    return await this.toolManager.executeTool(toolName, args);
+    const toolCallId = `direct-${randomUUID()}`;
+    return await this.toolManager.executeTool(toolName, args, toolCallId);
   }
   /**
    * Gets all available tools from all connected MCP servers.
@@ -1249,6 +1502,79 @@ Either:
     this.ensureStarted();
     return this.mcpManager.getFailedConnections();
   }
+  /**
+   * Gets the connection status of a single MCP server.
+   * @param name The server name
+   * @returns The connection status, or undefined if server not configured
+   *
+   * TODO: Move to MCPManager once it has access to server configs (enabled state).
+   * Currently here because MCPManager only tracks connections, not config.
+   */
+  getMcpServerStatus(name) {
+    this.ensureStarted();
+    const config = this.stateManager.getRuntimeConfig();
+    const serverConfig = config.mcpServers[name];
+    if (!serverConfig) return void 0;
+    const enabled = serverConfig.enabled !== false;
+    const connectedClients = this.mcpManager.getClients();
+    const failedConnections = this.mcpManager.getFailedConnections();
+    let status;
+    if (!enabled) {
+      status = "disconnected";
+    } else if (connectedClients.has(name)) {
+      status = "connected";
+    } else {
+      status = "error";
+    }
+    const result = {
+      name,
+      type: serverConfig.type,
+      enabled,
+      status
+    };
+    if (failedConnections[name]) {
+      result.error = failedConnections[name];
+    }
+    return result;
+  }
+  /**
+   * Gets all configured MCP servers with their connection status.
+   * Centralizes the status computation logic used by CLI, server, and webui.
+   * @returns Array of server info with computed status
+   *
+   * TODO: Move to MCPManager once it has access to server configs (enabled state).
+   * Currently here because MCPManager only tracks connections, not config.
+   */
+  getMcpServersWithStatus() {
+    this.ensureStarted();
+    const config = this.stateManager.getRuntimeConfig();
+    const mcpServers = config.mcpServers || {};
+    const connectedClients = this.mcpManager.getClients();
+    const failedConnections = this.mcpManager.getFailedConnections();
+    const servers = [];
+    for (const [name, serverConfig] of Object.entries(mcpServers)) {
+      const enabled = serverConfig.enabled !== false;
+      let status;
+      if (!enabled) {
+        status = "disconnected";
+      } else if (connectedClients.has(name)) {
+        status = "connected";
+      } else {
+        status = "error";
+      }
+      const server = {
+        name,
+        type: serverConfig.type,
+        enabled,
+        status
+      };
+      if (failedConnections[name]) {
+        server.error = failedConnections[name];
+      }
+      servers.push(server);
+    }
+    return servers;
+  }
   // ============= RESOURCE MANAGEMENT =============
   /**
    * Lists all available resources with their info.
@@ -1344,6 +1670,21 @@ Either:
     this.ensureStarted();
     return await this.promptManager.has(name);
   }
+  /**
+   * Refreshes the prompts cache, reloading from all providers.
+   * Call this after adding/deleting prompts to make them immediately available.
+   *
+   * @param newPrompts Optional - if provided, updates the config prompts before refreshing.
+   *                   Use this when you've modified the agent config file and need to
+   *                   update both the runtime config and refresh the cache.
+   */
+  async refreshPrompts(newPrompts) {
+    this.ensureStarted();
+    if (newPrompts) {
+      this.promptManager.updateConfigPrompts(newPrompts);
+    }
+    await this.promptManager.refresh();
+  }
   /**
    * Gets a prompt with its messages.
    * @param name The name of the prompt