@dexto/core 1.2.6 → 1.4.0

package/dist/agent/DextoAgent.cjs

@@ -66,6 +66,8 @@ __export(DextoAgent_exports, {
   DextoAgent: () => DextoAgent
 });
 module.exports = __toCommonJS(DextoAgent_exports);
+var import_crypto = require("crypto");
+var import_events = require("events");
 var import_resources = require("../resources/index.js");
 var import_utils = require("../context/utils.js");
 var import_prompts = require("../prompts/index.js");
@@ -81,13 +83,14 @@ var import_errors = require("../llm/errors.js");
 var import_errors2 = require("./errors.js");
 var import_errors3 = require("../mcp/errors.js");
 var import_DextoRuntimeError = require("../errors/DextoRuntimeError.js");
+var import_DextoValidationError = require("../errors/DextoValidationError.js");
 var import_result_bridge = require("../errors/result-bridge.cjs");
 var import_result = require("../utils/result.cjs");
 var import_resolver2 = require("../mcp/resolver.js");
 var import_registry = require("../llm/registry.js");
 var import_service_initializer2 = require("../utils/service-initializer.js");
 var import_schemas2 = require("./schemas.js");
-var import_events = require("../events/index.js");
+var import_events2 = require("../events/index.js");
 var import_safe_stringify = require("../utils/safe-stringify.cjs");
 var import_title_generator = require("../session/title-generator.js");
 var _DextoAgent_decorators, _init;
@@ -127,7 +130,7 @@ class DextoAgent {
       agentId: this.config.agentId,
       component: import_types.DextoLogComponent.AGENT
     });
-    this.agentEventBus = new import_events.AgentEventBus();
+    this.agentEventBus = new import_events2.AgentEventBus();
     this.logger.info("DextoAgent created.");
   }
   /**
@@ -159,6 +162,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;
   /**
@@ -234,10 +239,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)
@@ -368,173 +369,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");
-    }
-    const targetSessionId = sessionId;
-    const activeContext = import_api.context.active();
-    const span = import_api.trace.getActiveSpan();
-    if (span) {
-      span.setAttribute("sessionId", targetSessionId);
-    }
-    const existingBaggage = import_api.propagation.getBaggage(activeContext);
-    const baggageEntries = {};
-    if (existingBaggage) {
-      existingBaggage.getAllEntries().forEach(([key, entry]) => {
-        baggageEntries[key] = { ...entry };
+  async run(textInput, imageDataInput, fileDataInput, sessionId, _stream = false) {
+    const parts = [];
+    if (textInput) {
+      parts.push({ type: "text", text: textInput });
+    }
+    if (imageDataInput) {
+      parts.push({
+        type: "image",
+        image: imageDataInput.image,
+        mimeType: imageDataInput.mimeType
       });
     }
-    baggageEntries.sessionId = { ...baggageEntries.sessionId, value: targetSessionId };
-    const updatedContext = import_api.propagation.setBaggage(
-      activeContext,
-      import_api.propagation.createBaggage(baggageEntries)
-    );
-    const verifyBaggage = import_api.propagation.getBaggage(updatedContext);
-    this.logger.debug(
-      `Baggage after setting sessionId: ${JSON.stringify(
-        Array.from(verifyBaggage?.getAllEntries() || [])
-      )}`
-    );
-    return await import_api.context.with(updatedContext, async () => {
-      try {
-        const llmConfig = this.stateManager.getLLMConfig(targetSessionId);
-        const validation = (0, import_validation.validateInputForLLM)(
-          {
-            text: textInput,
-            ...imageDataInput && { imageData: imageDataInput },
-            ...fileDataInput && { fileData: fileDataInput }
-          },
-          {
-            provider: llmConfig.provider,
-            model: llmConfig.model
-          },
-          this.logger
-        );
-        (0, import_result_bridge.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 (0, import_resources.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;
-      }
-    });
+    if (fileDataInput) {
+      parts.push({
+        type: "file",
+        data: fileDataInput.data,
+        mimeType: fileDataInput.mimeType,
+        ...fileDataInput.filename && { filename: fileDataInput.filename }
+      });
+    }
+    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.type === "llm:error"
+    const fatalErrorEvent = events.find(
+      (e) => e.name === "llm:error" && e.recoverable !== true
     );
-    if (errorEvent) {
-      if (errorEvent.error instanceof import_DextoRuntimeError.DextoRuntimeError) {
-        throw errorEvent.error;
+    if (fatalErrorEvent) {
+      if (fatalErrorEvent.error instanceof import_DextoRuntimeError.DextoRuntimeError || fatalErrorEvent.error instanceof import_DextoValidationError.DextoValidationError) {
+        throw fatalErrorEvent.error;
       }
-      const llmConfig = this.stateManager.getLLMConfig(options.sessionId);
+      const llmConfig = this.stateManager.getLLMConfig(sessionId);
       throw import_errors.LLMError.generationFailed(
-        errorEvent.error.message,
+        fatalErrorEvent.error.message,
         llmConfig.provider,
         llmConfig.model
       );
     }
-    const responseEvent = events.find((e) => e.type === "llm:response");
-    if (!responseEvent || responseEvent.type !== "llm:response") {
-      const llmConfig = this.stateManager.getLLMConfig(options.sessionId);
+    const responseEvent = events.find((e) => e.name === "llm:response");
+    if (!responseEvent || responseEvent.name !== "llm:response") {
+      const llmConfig = this.stateManager.getLLMConfig(sessionId);
       throw import_errors.LLMError.generationFailed(
         "Stream did not complete successfully - no response received",
         llmConfig.provider,
@@ -542,10 +458,10 @@ Either:
       );
     }
     const toolCallEvents = events.filter(
-      (e) => e.type === "llm:tool-call"
+      (e) => e.name === "llm:tool-call"
     );
     const toolResultEvents = events.filter(
-      (e) => e.type === "llm:tool-result"
+      (e) => e.name === "llm:tool-result"
     );
     const toolCalls = toolCallEvents.map((tc) => {
       const toolResult = toolResultEvents.find((tr) => tr.callId === tc.callId);
@@ -559,7 +475,6 @@ Either:
         } : void 0
       };
     });
-    const messageId = `msg_${Date.now()}_${Math.random().toString(36).substring(7)}`;
     const defaultUsage = {
       inputTokens: 0,
       outputTokens: 0,
@@ -571,8 +486,7 @@ Either:
       reasoning: responseEvent.reasoning,
       usage,
       toolCalls,
-      sessionId: options.sessionId,
-      messageId
+      sessionId
     };
   }
   /**
@@ -586,45 +500,51 @@ 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)
-   * @returns AsyncIterator that yields StreamingEvent objects (core events with type property)
+   * @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.type === 'llm:chunk') {
-   *     process.stdout.write(event.content);
-   *   }
-   *   if (event.type === '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 import_errors2.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);
+    (0, import_events.setMaxListeners)(30, cleanupSignal);
     const listeners = [];
     const cleanupListeners = () => {
       if (listeners.length === 0) {
         return;
       }
       for (const { event, listener } of listeners) {
-        this.agentEventBus.off(event, listener);
+        this.agentEventBus.off(
+          event,
+          listener
+        );
       }
       listeners.length = 0;
+      this.activeStreamControllers.delete(sessionId);
     };
     if (signal) {
       const abortHandler = () => {
@@ -633,49 +553,262 @@ Either:
       };
       signal.addEventListener("abort", abortHandler, { once: true });
     }
-    for (const eventName of import_events.STREAMING_EVENTS) {
-      const listener = (data) => {
-        if (data.sessionId !== void 0 && data.sessionId !== sessionId) {
-          return;
-        }
-        eventQueue.push({ type: eventName, ...data });
-        if (eventName === "llm:response" || eventName === "llm:error" && !data.recoverable) {
-          completed = true;
-        }
-      };
-      this.agentEventBus.on(eventName, listener, {
-        signal: cleanupSignal
-      });
-      listeners.push({ event: eventName, listener });
-    }
-    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((error) => {
-      _streamError = error;
+    const thinkingListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "llm:thinking", ...data });
+    };
+    this.agentEventBus.on("llm:thinking", thinkingListener, { signal: cleanupSignal });
+    listeners.push({ event: "llm:thinking", listener: thinkingListener });
+    const chunkListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "llm:chunk", ...data });
+    };
+    this.agentEventBus.on("llm:chunk", chunkListener, { signal: cleanupSignal });
+    listeners.push({ event: "llm:chunk", listener: chunkListener });
+    const responseListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "llm:response", ...data });
+    };
+    this.agentEventBus.on("llm:response", responseListener, { signal: cleanupSignal });
+    listeners.push({ event: "llm:response", listener: responseListener });
+    const toolCallListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "llm:tool-call", ...data });
+    };
+    this.agentEventBus.on("llm:tool-call", toolCallListener, { signal: cleanupSignal });
+    listeners.push({ event: "llm:tool-call", listener: toolCallListener });
+    const toolResultListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "llm:tool-result", ...data });
+    };
+    this.agentEventBus.on("llm:tool-result", toolResultListener, { signal: cleanupSignal });
+    listeners.push({ event: "llm:tool-result", listener: toolResultListener });
+    const errorListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "llm:error", ...data });
+      if (!data.recoverable) {
+        completed = true;
+      }
+    };
+    this.agentEventBus.on("llm:error", errorListener, { signal: cleanupSignal });
+    listeners.push({ event: "llm:error", listener: errorListener });
+    const unsupportedInputListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "llm:unsupported-input", ...data });
+    };
+    this.agentEventBus.on("llm:unsupported-input", unsupportedInputListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "llm:unsupported-input", listener: unsupportedInputListener });
+    const titleUpdatedListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "session:title-updated", ...data });
+    };
+    this.agentEventBus.on("session:title-updated", titleUpdatedListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "session:title-updated", listener: titleUpdatedListener });
+    const approvalRequestListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "approval:request", ...data });
+    };
+    this.agentEventBus.on("approval:request", approvalRequestListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "approval:request", listener: approvalRequestListener });
+    const approvalResponseListener = (data) => {
+      if (data.sessionId !== sessionId) return;
+      eventQueue.push({ name: "approval:response", ...data });
+    };
+    this.agentEventBus.on("approval:response", approvalResponseListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "approval:response", listener: approvalResponseListener });
+    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 instanceof Error ? error.message : String(error)}`
+    };
+    this.agentEventBus.on("run:complete", runCompleteListener, {
+      signal: cleanupSignal
+    });
+    listeners.push({ event: "run:complete", listener: runCompleteListener });
+    (async () => {
+      const activeContext = import_api.context.active();
+      const activeSpan = import_api.trace.getActiveSpan();
+      if (activeSpan) {
+        activeSpan.setAttribute("sessionId", sessionId);
+      }
+      const existingBaggage = import_api.propagation.getBaggage(activeContext);
+      const baggageEntries = {};
+      if (existingBaggage) {
+        existingBaggage.getAllEntries().forEach(([key, entry]) => {
+          baggageEntries[key] = { ...entry };
+        });
+      }
+      baggageEntries.sessionId = { ...baggageEntries.sessionId, value: sessionId };
+      const updatedContext = import_api.propagation.setBaggage(
+        activeContext,
+        import_api.propagation.createBaggage(baggageEntries)
       );
-      eventQueue.push({
-        type: "llm:error",
-        error,
-        recoverable: false,
-        context: "run_failed",
-        sessionId
+      await import_api.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 = (0, import_validation.validateInputForLLM)(
+            { text: textContent },
+            { provider: llmConfig.provider, model: llmConfig.model },
+            this.logger
+          );
+          (0, import_result_bridge.ensureOk)(textValidation, this.logger);
+          for (const imagePart of imageParts) {
+            const imageValidation = (0, import_validation.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
+            );
+            (0, import_result_bridge.ensureOk)(imageValidation, this.logger);
+          }
+          for (const filePart of fileParts) {
+            const fileValidation = (0, import_validation.validateInputForLLM)(
+              {
+                fileData: {
+                  data: typeof filePart.data === "string" ? filePart.data : filePart.data.toString(),
+                  mimeType: filePart.mimeType
+                }
+              },
+              { provider: llmConfig.provider, model: llmConfig.model },
+              this.logger
+            );
+            (0, import_result_bridge.ensureOk)(fileValidation, this.logger);
+          }
+          if (textContent.includes("@")) {
+            try {
+              const resources = await this.resourceManager.list();
+              const expansion = await (0, import_resources.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 import_DextoRuntimeError.DextoRuntimeError || err instanceof import_DextoValidationError.DextoValidationError ? err : err instanceof Error ? err : import_errors2.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 };
@@ -703,6 +836,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 import_session.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 import_session.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 import_session.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 import_session.SessionError.notFound(sessionId);
+    }
+    return session.clearMessageQueue();
+  }
   /**
    * Cancels the currently running turn for a session.
    * Safe to call even if no run is in progress.
@@ -712,13 +912,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 import_errors2.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 =============
   /**
@@ -825,7 +1032,6 @@ Either:
     const llmConfig = this.getEffectiveConfig(sessionId).llm;
     const result = await (0, import_title_generator.generateSessionTitle)(
       llmConfig,
-      llmConfig.router,
       this.toolManager,
       this.systemPromptManager,
       this.resourceManager,
@@ -908,7 +1114,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 import_errors2.AgentError.apiValidationError(
+        "sessionId is required and must be a non-empty string"
+      );
     }
     try {
       await this.sessionManager.resetSession(sessionId);
@@ -923,6 +1131,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 import_errors2.AgentError.apiValidationError(
+        "sessionId is required and must be a non-empty string"
+      );
+    }
+    const session = await this.sessionManager.getSession(sessionId);
+    if (!session) {
+      throw import_session.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.
@@ -937,7 +1176,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:
@@ -962,8 +1201,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' }, '*');
@@ -1115,19 +1354,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 = (0, import_resolver2.resolveAndValidateMcpServerConfig)(name, config, existingServerNames);
     const validatedConfig = (0, import_result_bridge.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();
@@ -1139,9 +1382,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(
@@ -1150,9 +1391,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,
@@ -1163,14 +1402,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 import_errors3.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 import_errors3.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 import_errors3.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 import_errors3.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 import_errors3.MCPError.disconnectionFailed(name, errorMessage);
+    }
   }
   /**
    * Restarts an MCP server by disconnecting and reconnecting with its original configuration.
@@ -1203,13 +1509,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-${(0, import_crypto.randomUUID)()}`;
+    return await this.toolManager.executeTool(toolName, args, toolCallId);
   }
   /**
    * Gets all available tools from all connected MCP servers.
@@ -1247,6 +1558,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.
@@ -1342,6 +1726,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