@dexto/core 1.2.4 → 1.2.5

package/dist/agent/DextoAgent.js

@@ -8,16 +8,19 @@ import { expandMessageReferences } from "../resources/index.js";
 import { expandBlobReferences } from "../context/utils.js";
 import { PromptManager } from "../prompts/index.js";
 import { SessionError } from "../session/index.js";
-import { logger } from "../logger/index.js";
+import { createLogger } from "../logger/factory.js";
+import { DextoLogComponent } from "../logger/v2/types.js";
 import { InstrumentClass } from "../telemetry/decorators.js";
+import { trace, context, propagation } from "@opentelemetry/api";
 import { LLMUpdatesSchema } from "../llm/schemas.js";
 import { resolveAndValidateLLMConfig } from "../llm/resolver.js";
 import { validateInputForLLM } from "../llm/validation.js";
+import { LLMError } from "../llm/errors.js";
 import { AgentError } from "./errors.js";
 import { MCPError } from "../mcp/errors.js";
+import { DextoRuntimeError } from "../errors/DextoRuntimeError.js";
 import { ensureOk } from "../errors/result-bridge.js";
 import { fail, zodToIssues } from "../utils/result.js";
-import { DextoValidationError } from "../errors/DextoValidationError.js";
 import { resolveAndValidateMcpServerConfig } from "../mcp/resolver.js";
 import {
   getSupportedProviders,
@@ -27,11 +30,11 @@ import {
 } from "../llm/registry.js";
 import { createAgentServices } from "../utils/service-initializer.js";
 import { AgentConfigSchema } from "./schemas.js";
-import { getDextoPath } from "../utils/path.js";
+import {
+  AgentEventBus,
+  STREAMING_EVENTS
+} from "../events/index.js";
 import { safeStringify } from "../utils/safe-stringify.js";
-import { loadAgentConfig } from "../config/loader.js";
-import { promises as fs } from "fs";
-import { parseDocument } from "yaml";
 import { deriveHeuristicTitle, generateSessionTitle } from "../session/title-generator.js";
 const requiredServices = [
   "mcpManager",
@@ -55,10 +58,22 @@ _DextoAgent_decorators = [InstrumentClass({
   ]
 })];
 class DextoAgent {
+  /**
+   * Creates a DextoAgent instance.
+   *
+   * @param config - Agent configuration (validated and enriched)
+   * @param configPath - Optional path to config file (for relative path resolution)
+   */
   constructor(config, configPath) {
     this.configPath = configPath;
     this.config = AgentConfigSchema.parse(config);
-    logger.info("DextoAgent created.");
+    this.logger = createLogger({
+      config: this.config.logger,
+      agentId: this.config.agentId,
+      component: DextoLogComponent.AGENT
+    });
+    this.agentEventBus = new AgentEventBus();
+    this.logger.info("DextoAgent created.");
   }
   /**
    * These services are public for use by the outside world
@@ -77,19 +92,20 @@ class DextoAgent {
   services;
   // Search service for conversation search
   searchService;
-  // Default session for backward compatibility
-  defaultSession = null;
-  // Current default session ID for loadSession functionality
-  currentDefaultSessionId = "default";
   // Track initialization state
   _isStarted = false;
   _isStopped = false;
-  // Store config for async initialization
+  // Store config for async initialization (accessible before start() for setup)
   config;
-  // Event subscribers (e.g., WebSocket, Webhook handlers)
+  // Event subscribers (e.g., SSE, Webhook handlers)
   eventSubscribers = /* @__PURE__ */ new Set();
   // Telemetry instance for distributed tracing
   telemetry;
+  // Approval handler for manual tool confirmation and elicitation
+  // Set via setApprovalHandler() before start() if needed
+  approvalHandler;
+  // Logger instance for this agent (dependency injection)
+  logger;
   /**
    * Starts the agent by initializing all async services.
    * This method handles storage backends, MCP connections, session manager initialization, and other async operations.
@@ -102,8 +118,13 @@ class DextoAgent {
       throw AgentError.alreadyStarted();
     }
     try {
-      logger.info("Starting DextoAgent...");
-      const services = await createAgentServices(this.config, this.configPath);
+      this.logger.info("Starting DextoAgent...");
+      const services = await createAgentServices(
+        this.config,
+        this.configPath,
+        this.logger,
+        this.agentEventBus
+      );
       for (const service of requiredServices) {
         if (!services[service]) {
           throw AgentError.initializationFailed(
@@ -111,12 +132,31 @@ class DextoAgent {
           );
         }
       }
+      const needsHandler = this.config.toolConfirmation.mode === "manual" || this.config.elicitation.enabled;
+      if (needsHandler && !this.approvalHandler) {
+        const reasons = [];
+        if (this.config.toolConfirmation.mode === "manual") {
+          reasons.push('tool confirmation mode is "manual"');
+        }
+        if (this.config.elicitation.enabled) {
+          reasons.push("elicitation is enabled");
+        }
+        throw AgentError.initializationFailed(
+          `An approval handler is required but not configured (${reasons.join(" and ")}).
+Either:
+  \u2022 Call agent.setApprovalHandler() before starting
+  \u2022 Set toolConfirmation: { mode: "auto-approve" } or { mode: "auto-deny" }
+  \u2022 Disable elicitation: { enabled: false }`
+        );
+      }
+      if (this.approvalHandler) {
+        services.approvalManager.setHandler(this.approvalHandler);
+      }
       Object.assign(this, {
         mcpManager: services.mcpManager,
         toolManager: services.toolManager,
         resourceManager: services.resourceManager,
         systemPromptManager: services.systemPromptManager,
-        agentEventBus: services.agentEventBus,
         stateManager: services.stateManager,
         sessionManager: services.sessionManager,
         memoryManager: services.memoryManager,
@@ -128,20 +168,25 @@ class DextoAgent {
         this.resourceManager,
         this.config,
         this.agentEventBus,
-        services.storageManager.getDatabase()
+        services.storageManager.getDatabase(),
+        this.logger
       );
       await promptManager.initialize();
       Object.assign(this, { promptManager });
       this._isStarted = true;
       this._isStopped = false;
-      logger.info("DextoAgent started successfully.");
+      this.logger.info("DextoAgent started successfully.");
       for (const subscriber of this.eventSubscribers) {
         subscriber.subscribe(this.agentEventBus);
       }
-      const logPath = getDextoPath("logs", "dexto.log");
-      console.log(`\u{1F4CB} Logs available at: ${logPath}`);
+      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) {
-      logger.error("Failed to start DextoAgent", error);
+      this.logger.error("Failed to start DextoAgent", {
+        error: error instanceof Error ? error.message : String(error)
+      });
       throw error;
     }
   }
@@ -154,19 +199,19 @@ class DextoAgent {
    */
   async stop() {
     if (this._isStopped) {
-      logger.warn("Agent is already stopped");
+      this.logger.warn("Agent is already stopped");
       return;
     }
     if (!this._isStarted) {
       throw AgentError.notStarted();
     }
     try {
-      logger.info("Stopping DextoAgent...");
+      this.logger.info("Stopping DextoAgent...");
       const shutdownErrors = [];
       try {
         if (this.sessionManager) {
           await this.sessionManager.cleanup();
-          logger.debug("SessionManager cleaned up successfully");
+          this.logger.debug("SessionManager cleaned up successfully");
         }
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
@@ -175,7 +220,7 @@ class DextoAgent {
       try {
         if (this.services?.pluginManager) {
           await this.services.pluginManager.cleanup();
-          logger.debug("PluginManager cleaned up successfully");
+          this.logger.debug("PluginManager cleaned up successfully");
         }
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
@@ -184,7 +229,7 @@ class DextoAgent {
       try {
         if (this.mcpManager) {
           await this.mcpManager.disconnectAll();
-          logger.debug("MCPManager disconnected all clients successfully");
+          this.logger.debug("MCPManager disconnected all clients successfully");
         }
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
@@ -193,7 +238,7 @@ class DextoAgent {
       try {
         if (this.services?.storageManager) {
           await this.services.storageManager.disconnect();
-          logger.debug("Storage manager disconnected successfully");
+          this.logger.debug("Storage manager disconnected successfully");
         }
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
@@ -203,18 +248,20 @@ class DextoAgent {
       this._isStarted = false;
       if (shutdownErrors.length > 0) {
         const errorMessages = shutdownErrors.map((e) => e.message).join("; ");
-        logger.warn(`DextoAgent stopped with some errors: ${errorMessages}`);
+        this.logger.warn(`DextoAgent stopped with some errors: ${errorMessages}`);
       } else {
-        logger.info("DextoAgent stopped successfully.");
+        this.logger.info("DextoAgent stopped successfully.");
       }
     } catch (error) {
-      logger.error("Failed to stop DextoAgent", error);
+      this.logger.error("Failed to stop DextoAgent", {
+        error: error instanceof Error ? error.message : String(error)
+      });
       throw error;
     }
   }
   /**
    * Register an event subscriber that will be automatically re-subscribed on agent restart.
-   * Subscribers are typically API layer components (WebSocket, Webhook handlers) that need
+   * Subscribers are typically API layer components (SSE, Webhook handlers) that need
    * to receive agent events. If the agent is already started, the subscriber is immediately subscribed.
    *
    * @param subscriber - Object implementing AgentEventSubscriber interface
@@ -256,11 +303,11 @@ class DextoAgent {
    */
   ensureStarted() {
     if (this._isStopped) {
-      logger.warn("Agent is stopped");
+      this.logger.warn("Agent is stopped");
       throw AgentError.stopped();
     }
     if (!this._isStarted) {
-      logger.warn("Agent is not started");
+      this.logger.warn("Agent is not started");
       throw AgentError.notStarted();
     }
   }
@@ -272,110 +319,347 @@ class DextoAgent {
    * @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 sessionId - Optional session ID for multi-session scenarios
+   * @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
    */
   async run(textInput, imageDataInput, fileDataInput, sessionId, stream = false) {
     this.ensureStarted();
-    try {
-      const targetSessionId = sessionId || this.currentDefaultSessionId;
-      const llmConfig = this.stateManager.getLLMConfig(targetSessionId);
-      const validation = validateInputForLLM(
-        {
-          text: textInput,
-          ...imageDataInput && { imageData: imageDataInput },
-          ...fileDataInput && { fileData: fileDataInput }
-        },
-        {
-          provider: llmConfig.provider,
-          model: llmConfig.model
-        }
-      );
-      ensureOk(validation);
-      const existingSession = await this.sessionManager.getSession(targetSessionId);
-      const session = existingSession || await this.sessionManager.createSession(targetSessionId);
-      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(", ");
-            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) {
-            logger.warn(
-              `Expanded message size (${(expandedSize / 1024 / 1024).toFixed(2)}MB) exceeds limit (${MAX_EXPANDED_SIZE / 1024 / 1024}MB). Content may be truncated.`
+    if (!sessionId || typeof sessionId !== "string") {
+      throw new Error("sessionId is required and must be a non-empty string");
+    }
+    const targetSessionId = sessionId;
+    const activeContext = context.active();
+    const span = trace.getActiveSpan();
+    if (span) {
+      span.setAttribute("sessionId", targetSessionId);
+    }
+    const existingBaggage = propagation.getBaggage(activeContext);
+    const baggageEntries = {};
+    if (existingBaggage) {
+      existingBaggage.getAllEntries().forEach(([key, entry]) => {
+        baggageEntries[key] = { ...entry };
+      });
+    }
+    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)
             );
-          }
-          finalText = expansion.expandedMessage;
-          if (expansion.extractedImages.length > 0 && !imageDataInput) {
-            const firstImage = expansion.extractedImages[0];
-            if (firstImage) {
-              finalImageData = {
-                image: firstImage.image,
-                mimeType: firstImage.mimeType
-              };
-              logger.debug(
-                `Using extracted image: ${firstImage.name} (${firstImage.mimeType})`
+            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.`
+            );
           }
-        } catch (error) {
-          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;
         }
-      }
-      if (!finalText.trim() && !finalImageData && !fileDataInput) {
-        logger.warn(
-          "Resource expansion resulted in empty content. Using original message."
+        const response = await session.run(
+          finalText,
+          finalImageData,
+          fileDataInput,
+          stream
         );
-        finalText = textInput;
+        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;
+      }
+    });
+  }
+  /**
+   * 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)
+   * @returns Promise that resolves to the complete response
+   *
+   * @example
+   * ```typescript
+   * const response = await agent.generate("What is 2+2?", { sessionId: "default" });
+   * console.log(response.content); // "4"
+   * console.log(response.usage.totalTokens); // 50
+   * ```
+   */
+  async generate(message, options) {
+    const events = [];
+    for await (const event of await this.stream(message, options)) {
+      events.push(event);
+    }
+    const errorEvent = events.find(
+      (e) => e.type === "llm:error"
+    );
+    if (errorEvent) {
+      if (errorEvent.error instanceof DextoRuntimeError) {
+        throw errorEvent.error;
       }
-      void this.maybeGenerateTitle(targetSessionId, finalText, llmConfig);
-      const response = await session.run(finalText, finalImageData, fileDataInput, stream);
-      this.sessionManager.incrementMessageCount(session.id).catch(
-        (error) => logger.warn(
-          `Failed to increment message count: ${error instanceof Error ? error.message : String(error)}`
-        )
+      const llmConfig = this.stateManager.getLLMConfig(options.sessionId);
+      throw LLMError.generationFailed(
+        errorEvent.error.message,
+        llmConfig.provider,
+        llmConfig.model
       );
-      return response;
-    } catch (error) {
-      logger.error(
-        `Error during DextoAgent.run: ${error instanceof Error ? error.message : JSON.stringify(error)}`
+    }
+    const responseEvent = events.find((e) => e.type === "llm:response");
+    if (!responseEvent || responseEvent.type !== "llm:response") {
+      const llmConfig = this.stateManager.getLLMConfig(options.sessionId);
+      throw LLMError.generationFailed(
+        "Stream did not complete successfully - no response received",
+        llmConfig.provider,
+        llmConfig.model
       );
-      throw error;
     }
+    const toolCallEvents = events.filter(
+      (e) => e.type === "llm:tool-call"
+    );
+    const toolResultEvents = events.filter(
+      (e) => e.type === "llm:tool-result"
+    );
+    const toolCalls = toolCallEvents.map((tc) => {
+      const toolResult = toolResultEvents.find((tr) => tr.callId === tc.callId);
+      return {
+        toolName: tc.toolName,
+        args: tc.args,
+        callId: tc.callId || `tool_${Date.now()}`,
+        result: toolResult ? {
+          success: toolResult.success,
+          data: toolResult.sanitized
+        } : void 0
+      };
+    });
+    const messageId = `msg_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+    const defaultUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0
+    };
+    const usage = responseEvent.tokenUsage ?? defaultUsage;
+    return {
+      content: responseEvent.content,
+      reasoning: responseEvent.reasoning,
+      usage,
+      toolCalls,
+      sessionId: options.sessionId,
+      messageId
+    };
+  }
+  /**
+   * Stream a response (yields events as they arrive).
+   * This is the recommended method for real-time streaming UI updates.
+   *
+   * TODO: Refactor to move AsyncIterator down to LLM service level (Option 1).
+   * Streaming message API that returns core AgentEvents in real-time.
+   * Only emits STREAMING_EVENTS (tier 1 visibility) - events designed for real-time chat UIs.
+   *
+   * 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)
+   *
+   * @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`);
+   *   }
+   * }
+   * ```
+   */
+  async stream(message, options) {
+    this.ensureStarted();
+    if (!options.sessionId) {
+      throw new Error("sessionId is required in StreamOptions");
+    }
+    const sessionId = options.sessionId;
+    const imageData = options.imageData;
+    const fileData = options.fileData;
+    const signal = options.signal;
+    const eventQueue = [];
+    let completed = false;
+    let _streamError = null;
+    const controller = new AbortController();
+    const cleanupSignal = controller.signal;
+    const listeners = [];
+    const cleanupListeners = () => {
+      if (listeners.length === 0) {
+        return;
+      }
+      for (const { event, listener } of listeners) {
+        this.agentEventBus.off(event, listener);
+      }
+      listeners.length = 0;
+    };
+    if (signal) {
+      const abortHandler = () => {
+        cleanupListeners();
+        controller.abort();
+      };
+      signal.addEventListener("abort", abortHandler, { once: true });
+    }
+    for (const eventName of 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;
+      completed = true;
+      this.logger.error(
+        `Error in DextoAgent.stream: ${error instanceof Error ? error.message : String(error)}`
+      );
+      eventQueue.push({
+        type: "llm:error",
+        error,
+        recoverable: false,
+        context: "run_failed",
+        sessionId
+      });
+    });
+    const iterator = {
+      async next() {
+        while (!completed && eventQueue.length === 0) {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          if (signal?.aborted) {
+            cleanupListeners();
+            controller.abort();
+            return { done: true, value: void 0 };
+          }
+        }
+        if (eventQueue.length > 0) {
+          return { done: false, value: eventQueue.shift() };
+        }
+        if (completed) {
+          cleanupListeners();
+          controller.abort();
+          return { done: true, value: void 0 };
+        }
+        cleanupListeners();
+        return { done: true, value: void 0 };
+      },
+      async return() {
+        cleanupListeners();
+        controller.abort();
+        return { done: true, value: void 0 };
+      },
+      [Symbol.asyncIterator]() {
+        return iterator;
+      }
+    };
+    return iterator;
   }
   /**
-   * Cancels the currently running turn for a session (or the default session).
+   * Cancels the currently running turn for a session.
    * Safe to call even if no run is in progress.
-   * @param sessionId Optional session id; defaults to current default session
+   * @param sessionId Session id (required)
    * @returns true if a run was in progress and was signaled to abort; false otherwise
    */
   async cancel(sessionId) {
     this.ensureStarted();
-    const targetSessionId = sessionId || this.currentDefaultSessionId;
-    if (!sessionId && this.defaultSession && this.defaultSession.id === targetSessionId) {
-      return this.defaultSession.cancel();
+    if (!sessionId || typeof sessionId !== "string") {
+      throw new Error("sessionId is required and must be a non-empty string");
     }
-    const existing = await this.sessionManager.getSession(targetSessionId, false);
+    const existing = await this.sessionManager.getSession(sessionId, false);
     if (existing) {
       return existing.cancel();
     }
@@ -415,9 +699,6 @@ class DextoAgent {
    */
   async endSession(sessionId) {
     this.ensureStarted();
-    if (sessionId === this.currentDefaultSessionId) {
-      this.defaultSession = null;
-    }
     return this.sessionManager.endSession(sessionId);
   }
   /**
@@ -427,9 +708,6 @@ class DextoAgent {
    */
   async deleteSession(sessionId) {
     this.ensureStarted();
-    if (sessionId === this.currentDefaultSessionId) {
-      this.defaultSession = null;
-    }
     return this.sessionManager.deleteSession(sessionId);
   }
   /**
@@ -456,66 +734,63 @@ class DextoAgent {
     return await this.sessionManager.getSessionTitle(sessionId);
   }
   /**
-   * Background task: generate and persist a session title using the same LLM.
-   * Runs only for the first user message (messageCount === 0 and no existing title).
-   * Never throws; timeboxed in the generator.
+   * Generate a title for a session on-demand.
+   * Uses the first user message content to generate a descriptive title.
+   *
+   * @param sessionId Session ID to generate title for
+   * @returns Promise that resolves to the generated title, or null if generation failed
    */
-  async maybeGenerateTitle(sessionId, userText, llmConfig) {
-    try {
-      const metadata = await this.sessionManager.getSessionMetadata(sessionId);
-      if (!metadata) {
-        logger.debug(
-          `[SessionTitle] No session metadata available for ${sessionId}, skipping title generation`
-        );
-        return;
-      }
-      if (metadata.title) {
-        logger.debug(
-          `[SessionTitle] Session ${sessionId} already has title '${metadata.title}', skipping`
-        );
-        return;
-      }
-      if (!userText || !userText.trim()) {
-        logger.debug(
-          `[SessionTitle] User text empty for session ${sessionId}, skipping title generation`
-        );
-        return;
-      }
-      logger.debug(
-        `[SessionTitle] Checking title generation preconditions for session ${sessionId}`
-      );
-      const result = await generateSessionTitle(
-        llmConfig,
-        llmConfig.router,
-        this.toolManager,
-        this.systemPromptManager,
-        this.resourceManager,
-        userText
+  async generateSessionTitle(sessionId) {
+    this.ensureStarted();
+    const metadata = await this.sessionManager.getSessionMetadata(sessionId);
+    if (!metadata) {
+      throw SessionError.notFound(sessionId);
+    }
+    if (metadata.title) {
+      this.logger.debug(
+        `[SessionTitle] Session ${sessionId} already has title '${metadata.title}'`
       );
-      if (result.error) {
-        logger.debug(
-          `[SessionTitle] LLM title generation failed for ${sessionId}: ${result.error}${result.timedOut ? " (timeout)" : ""}`
-        );
-      }
-      let title = result.title;
-      if (!title) {
-        title = deriveHeuristicTitle(userText);
-        if (title) {
-          logger.info(`[SessionTitle] Using heuristic title for ${sessionId}: ${title}`);
-        } else {
-          logger.debug(
-            `[SessionTitle] No suitable title derived for session ${sessionId}`
-          );
-          return;
-        }
+      return metadata.title;
+    }
+    const session = await this.sessionManager.getSession(sessionId);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    const history = await session.getHistory();
+    const firstUserMsg = history.find((m) => m.role === "user");
+    if (!firstUserMsg) {
+      this.logger.debug(`[SessionTitle] No user message found for session ${sessionId}`);
+      return null;
+    }
+    const userText = typeof firstUserMsg.content === "string" ? firstUserMsg.content : firstUserMsg.content?.filter((p) => p.type === "text").map((p) => p.text).join(" ");
+    if (!userText || !userText.trim()) {
+      this.logger.debug(`[SessionTitle] Empty user text for session ${sessionId}`);
+      return null;
+    }
+    const llmConfig = this.getEffectiveConfig(sessionId).llm;
+    const result = await generateSessionTitle(
+      llmConfig,
+      llmConfig.router,
+      this.toolManager,
+      this.systemPromptManager,
+      this.resourceManager,
+      userText,
+      this.logger
+    );
+    let title = result.title;
+    if (!title) {
+      title = deriveHeuristicTitle(userText);
+      if (title) {
+        this.logger.info(`[SessionTitle] Using heuristic title for ${sessionId}: ${title}`);
       } else {
-        logger.info(`[SessionTitle] Generated LLM title for ${sessionId}: ${title}`);
+        this.logger.debug(`[SessionTitle] No suitable title derived for ${sessionId}`);
+        return null;
       }
-      await this.sessionManager.setSessionTitle(sessionId, title, { ifUnsetOnly: true });
-      this.agentEventBus.emit("dexto:sessionTitleUpdated", { sessionId, title });
-    } catch (err) {
-      logger.silly(`Title generation skipped/failed for ${sessionId}: ${String(err)}`);
+    } else {
+      this.logger.info(`[SessionTitle] Generated LLM title for ${sessionId}: ${title}`);
     }
+    await this.sessionManager.setSessionTitle(sessionId, title, { ifUnsetOnly: true });
+    return title;
   }
   /**
    * Gets the conversation history for a specific session.
@@ -536,14 +811,16 @@ class DextoAgent {
     return await Promise.all(
       history.map(async (message) => ({
         ...message,
-        content: await expandBlobReferences(message.content, this.resourceManager).catch(
-          (error) => {
-            logger.warn(
-              `Failed to expand blob references in message: ${error instanceof Error ? error.message : String(error)}`
-            );
-            return message.content;
-          }
-        )
+        content: await expandBlobReferences(
+          message.content,
+          this.resourceManager,
+          this.logger
+        ).catch((error) => {
+          this.logger.warn(
+            `Failed to expand blob references in message: ${error instanceof Error ? error.message : String(error)}`
+          );
+          return message.content;
+        })
       }))
     );
   }
@@ -569,88 +846,23 @@ class DextoAgent {
     return await this.searchService.searchSessions(query);
   }
   /**
-   * Loads a session as the new "default" session for this agent.
-   * All subsequent operations that don't specify a session ID will use this session.
-   * This provides a clean "current working session" pattern for API users.
-   *
-   * @param sessionId The session ID to load as default, or null to reset to original default
-   * @throws Error if session doesn't exist
-   *
-   * @example
-   * ```typescript
-   * // Load a specific session as default
-   * await agent.loadSessionAsDefault('project-alpha');
-   * await agent.run("What's the status?"); // Uses project-alpha session
-   *
-   * // Reset to original default
-   * await agent.loadSessionAsDefault(null);
-   * await agent.run("Hello"); // Uses 'default' session
-   * ```
-   */
-  async loadSessionAsDefault(sessionId = null) {
-    this.ensureStarted();
-    if (sessionId === null) {
-      this.currentDefaultSessionId = "default";
-      this.defaultSession = null;
-      logger.debug("Agent default session reset to original default");
-      return;
-    }
-    const session = await this.sessionManager.getSession(sessionId);
-    if (!session) {
-      throw SessionError.notFound(sessionId);
-    }
-    this.currentDefaultSessionId = sessionId;
-    this.defaultSession = null;
-    logger.info(`Agent default session changed to: ${sessionId}`);
-  }
-  /**
-   * Gets the currently loaded default session ID.
-   * This reflects the session loaded via loadSession().
-   *
-   * @returns The current default session ID
-   */
-  getCurrentSessionId() {
-    this.ensureStarted();
-    return this.currentDefaultSessionId;
-  }
-  /**
-   * Gets the currently loaded default session.
-   * This respects the session loaded via loadSession().
-   *
-   * @returns The current default ChatSession
-   */
-  async getDefaultSession() {
-    this.ensureStarted();
-    if (!this.defaultSession || this.defaultSession.id !== this.currentDefaultSessionId) {
-      this.defaultSession = await this.sessionManager.createSession(
-        this.currentDefaultSessionId
-      );
-    }
-    return this.defaultSession;
-  }
-  /**
-   * Resets the conversation history for a specific session or the default session.
+   * Resets the conversation history for a specific session.
    * Keeps the session alive but the conversation history is cleared.
-   * @param sessionId Optional session ID. If not provided, resets the currently loaded default session.
+   * @param sessionId Session ID (required)
    */
   async resetConversation(sessionId) {
     this.ensureStarted();
+    if (!sessionId || typeof sessionId !== "string") {
+      throw new Error("sessionId is required and must be a non-empty string");
+    }
     try {
-      const targetSessionId = sessionId || this.currentDefaultSessionId;
-      if (!sessionId) {
-        if (!this.defaultSession || this.defaultSession.id !== this.currentDefaultSessionId) {
-          this.defaultSession = await this.sessionManager.createSession(
-            this.currentDefaultSessionId
-          );
-        }
-      }
-      await this.sessionManager.resetSession(targetSessionId);
-      logger.info(`DextoAgent conversation reset for session: ${targetSessionId}`);
-      this.agentEventBus.emit("dexto:conversationReset", {
-        sessionId: targetSessionId
+      await this.sessionManager.resetSession(sessionId);
+      this.logger.info(`DextoAgent conversation reset for session: ${sessionId}`);
+      this.agentEventBus.emit("session:reset", {
+        sessionId
       });
     } catch (error) {
-      logger.error(
+      this.logger.error(
         `Error during DextoAgent.resetConversation: ${error instanceof Error ? error.message : String(error)}`
       );
       throw error;
@@ -704,22 +916,24 @@ class DextoAgent {
    */
   async switchLLM(llmUpdates, sessionId) {
     this.ensureStarted();
-    logger.debug(`DextoAgent.switchLLM: llmUpdates: ${safeStringify(llmUpdates)}`);
+    this.logger.debug(`DextoAgent.switchLLM: llmUpdates: ${safeStringify(llmUpdates)}`);
     const parseResult = LLMUpdatesSchema.safeParse(llmUpdates);
     if (!parseResult.success) {
       const validation = fail(zodToIssues(parseResult.error, "error"));
-      ensureOk(validation);
+      ensureOk(validation, this.logger);
       throw new Error("Unreachable");
     }
     const validatedUpdates = parseResult.data;
     const currentLLMConfig = sessionId ? this.stateManager.getRuntimeConfig(sessionId).llm : this.stateManager.getRuntimeConfig().llm;
-    const result = resolveAndValidateLLMConfig(currentLLMConfig, validatedUpdates);
-    const validatedConfig = ensureOk(result);
+    const result = resolveAndValidateLLMConfig(currentLLMConfig, validatedUpdates, this.logger);
+    const validatedConfig = ensureOk(result, this.logger);
     await this.performLLMSwitch(validatedConfig, sessionId);
-    logger.info(`DextoAgent.switchLLM: LLM switched to: ${safeStringify(validatedConfig)}`);
+    this.logger.info(
+      `DextoAgent.switchLLM: LLM switched to: ${safeStringify(validatedConfig)}`
+    );
     const warnings = result.issues.filter((issue) => issue.severity === "warning");
     if (warnings.length > 0) {
-      logger.warn(
+      this.logger.warn(
         `LLM switch completed with warnings: ${warnings.map((w) => w.message).join(", ")}`
       );
     }
@@ -743,7 +957,7 @@ class DextoAgent {
       }
       await this.sessionManager.switchLLMForSpecificSession(validatedConfig, sessionScope);
     } else {
-      await this.sessionManager.switchLLMForDefaultSession(validatedConfig);
+      this.logger.debug("LLM config updated at agent level (no active session switches)");
     }
   }
   /**
@@ -857,31 +1071,35 @@ class DextoAgent {
     this.ensureStarted();
     const existingServerNames = Object.keys(this.stateManager.getRuntimeConfig().mcpServers);
     const validation = resolveAndValidateMcpServerConfig(name, config, existingServerNames);
-    const validatedConfig = ensureOk(validation);
+    const validatedConfig = ensureOk(validation, this.logger);
     this.stateManager.addMcpServer(name, validatedConfig);
     try {
       await this.mcpManager.connectServer(name, validatedConfig);
       await this.toolManager.refresh();
-      this.agentEventBus.emit("dexto:mcpServerConnected", {
+      this.agentEventBus.emit("mcp:server-connected", {
         name,
         success: true
       });
-      this.agentEventBus.emit("dexto:availableToolsUpdated", {
+      this.agentEventBus.emit("tools:available-updated", {
         tools: Object.keys(await this.toolManager.getAllTools()),
         source: "mcp"
       });
-      logger.info(`DextoAgent: Successfully added and connected to MCP server '${name}'.`);
+      this.logger.info(
+        `DextoAgent: Successfully added and connected to MCP server '${name}'.`
+      );
       const warnings = validation.issues.filter((i) => i.severity === "warning");
       if (warnings.length > 0) {
-        logger.warn(
+        this.logger.warn(
           `MCP server connected with warnings: ${warnings.map((w) => w.message).join(", ")}`
         );
       }
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      logger.error(`DextoAgent: Failed to connect to MCP server '${name}': ${errorMessage}`);
+      this.logger.error(
+        `DextoAgent: Failed to connect to MCP server '${name}': ${errorMessage}`
+      );
       this.stateManager.removeMcpServer(name);
-      this.agentEventBus.emit("dexto:mcpServerConnected", {
+      this.agentEventBus.emit("mcp:server-connected", {
         name,
         success: false,
         error: errorMessage
@@ -908,20 +1126,22 @@ class DextoAgent {
   async restartMcpServer(name) {
     this.ensureStarted();
     try {
-      logger.info(`DextoAgent: Restarting MCP server '${name}'...`);
+      this.logger.info(`DextoAgent: Restarting MCP server '${name}'...`);
       await this.mcpManager.restartServer(name);
       await this.toolManager.refresh();
-      this.agentEventBus.emit("dexto:mcpServerRestarted", {
+      this.agentEventBus.emit("mcp:server-restarted", {
         serverName: name
       });
-      this.agentEventBus.emit("dexto:availableToolsUpdated", {
+      this.agentEventBus.emit("tools:available-updated", {
         tools: Object.keys(await this.toolManager.getAllTools()),
         source: "mcp"
       });
-      logger.info(`DextoAgent: Successfully restarted MCP server '${name}'.`);
+      this.logger.info(`DextoAgent: Successfully restarted MCP server '${name}'.`);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      logger.error(`DextoAgent: Failed to restart MCP server '${name}': ${errorMessage}`);
+      this.logger.error(
+        `DextoAgent: Failed to restart MCP server '${name}': ${errorMessage}`
+      );
       throw error;
     }
   }
@@ -1036,10 +1256,10 @@ class DextoAgent {
    */
   async getSystemPrompt() {
     this.ensureStarted();
-    const context = {
+    const context2 = {
       mcpManager: this.mcpManager
     };
-    return await this.systemPromptManager.build(context);
+    return await this.systemPromptManager.build(context2);
   }
   /**
    * Lists all available prompts from all providers (MCP, internal, starter, custom).
@@ -1113,7 +1333,8 @@ class DextoAgent {
   /**
    * Gets the effective configuration for a session or the default configuration.
    * @param sessionId Optional session ID. If not provided, returns default config.
-   * @returns The effective configuration object
+   * @returns The effective configuration object (validated with defaults applied)
+   * @remarks Requires agent to be started. Use `agent.config` for pre-start access.
    */
   getEffectiveConfig(sessionId) {
     this.ensureStarted();
@@ -1132,84 +1353,48 @@ class DextoAgent {
     return this.configPath;
   }
   /**
-   * Reloads the agent configuration from disk.
-   * This will re-read the config file, validate it, and detect what changed.
-   * Most configuration changes require a full agent restart to take effect.
+   * Reloads the agent configuration with a new config object.
+   * Validates the new config, detects what changed, and automatically
+   * restarts the agent if necessary to apply the changes.
    *
-   * To apply changes: stop the agent and start it again with the new config.
-   *
-   * @returns Object containing list of changes that require restart
-   * @throws Error if config file cannot be read or is invalid
+   * @param newConfig The new agent configuration to apply
+   * @returns Object containing whether agent was restarted and list of changes applied
+   * @throws Error if config is invalid or restart fails
    *
    * TODO: improve hot reload capabilites so that we don't always require a restart
    */
-  async reloadConfig() {
-    if (!this.configPath) {
-      throw AgentError.noConfigPath();
-    }
-    logger.info(`Reloading agent configuration from: ${this.configPath}`);
+  async reload(newConfig) {
+    this.logger.info("Reloading agent configuration");
     const oldConfig = this.config;
-    const newConfig = await loadAgentConfig(this.configPath);
     const validated = AgentConfigSchema.parse(newConfig);
-    const restartRequired = this.detectRestartRequiredChanges(oldConfig, validated);
+    const changesApplied = this.detectConfigChanges(oldConfig, validated);
     this.config = validated;
-    if (restartRequired.length > 0) {
-      logger.warn(
-        `Configuration updated. Restart required to apply: ${restartRequired.join(", ")}`
+    let restarted = false;
+    if (changesApplied.length > 0) {
+      this.logger.info(
+        `Configuration changed. Restarting agent to apply: ${changesApplied.join(", ")}`
       );
+      await this.restart();
+      restarted = true;
+      this.logger.info("Agent restarted successfully with new configuration");
     } else {
-      logger.info("Agent configuration reloaded successfully (no changes detected)");
+      this.logger.info("Agent configuration reloaded successfully (no changes detected)");
     }
     return {
-      restartRequired
+      restarted,
+      changesApplied
     };
   }
-  /**
-   * Updates and saves the agent configuration to disk.
-   * This merges the updates with the raw config from disk, validates, and writes to file.
-   * IMPORTANT: This preserves environment variable placeholders (e.g., $OPENAI_API_KEY)
-   * to avoid leaking secrets into the config file.
-   * @param updates Partial configuration updates to apply
-   * @param targetPath Optional path to save to (defaults to current config path)
-   * @returns Object containing list of changes that require restart
-   * @throws Error if validation fails or file cannot be written
-   */
-  async updateAndSaveConfig(updates, targetPath) {
-    const path = targetPath || this.configPath;
-    if (!path) {
-      throw AgentError.noConfigPath();
-    }
-    logger.info(`Updating and saving agent configuration to: ${path}`);
-    const rawYaml = await fs.readFile(path, "utf-8");
-    const doc = parseDocument(rawYaml);
-    const rawConfig = doc.toJSON();
-    const updatedRawConfig = { ...rawConfig, ...updates };
-    const parsed = AgentConfigSchema.safeParse(updatedRawConfig);
-    if (!parsed.success) {
-      const result = fail(zodToIssues(parsed.error, "error"));
-      throw new DextoValidationError(result.issues);
-    }
-    for (const [key, value] of Object.entries(updates)) {
-      doc.set(key, value);
-    }
-    const yamlContent = String(doc);
-    const tmpPath = `${path}.tmp`;
-    await fs.writeFile(tmpPath, yamlContent, "utf-8");
-    await fs.rename(tmpPath, path);
-    const reloadResult = await this.reloadConfig();
-    logger.info(`Agent configuration saved to: ${path}`);
-    return reloadResult;
-  }
   /**
    * Detects configuration changes that require a full agent restart.
+   * Pure comparison logic - no file I/O.
    * Returns an array of change descriptions.
    *
    * @param oldConfig Previous validated configuration
    * @param newConfig New validated configuration
    * @returns Array of restart-required change descriptions
-   * @private
    */
-  detectRestartRequiredChanges(oldConfig, newConfig) {
+  detectConfigChanges(oldConfig, newConfig) {
     const changes = [];
     if (JSON.stringify(oldConfig.storage) !== JSON.stringify(newConfig.storage)) {
       changes.push("Storage backend");
@@ -1234,6 +1419,58 @@ class DextoAgent {
     }
     return changes;
   }
+  // ============= APPROVAL HANDLER API =============
+  /**
+   * Set a custom approval handler for manual approval mode.
+   *
+   * When `toolConfirmation.mode` is set to 'manual', an approval handler must be
+   * provided to process tool confirmation requests. The handler will be called
+   * whenever a tool execution requires user approval.
+   *
+   * The handler receives an approval request and must return a promise that resolves
+   * to an approval response with the user's decision (approved/denied/cancelled).
+   *
+   * @param handler The approval handler function
+   *
+   * @example
+   * ```typescript
+   * import { ApprovalStatus } from '@dexto/core';
+   *
+   * agent.setApprovalHandler(async (request) => {
+   *   // Present approval request to user (CLI, UI, webhook, etc.)
+   *   console.log(`Approve tool: ${request.metadata.toolName}?`);
+   *   console.log(`Args: ${JSON.stringify(request.metadata.args)}`);
+   *
+   *   // Collect user's decision (this is just an example)
+   *   const approved = await getUserInput();
+   *
+   *   return {
+   *     approvalId: request.approvalId,
+   *     status: approved ? ApprovalStatus.APPROVED : ApprovalStatus.DENIED,
+   *     sessionId: request.sessionId,
+   *   };
+   * });
+   * ```
+   */
+  setApprovalHandler(handler) {
+    this.approvalHandler = handler;
+    if (this._isStarted && this.services) {
+      this.services.approvalManager.setHandler(handler);
+    }
+    this.logger.debug("Approval handler registered");
+  }
+  /**
+   * Clear the current approval handler.
+   *
+   * After calling this, manual approval mode will fail if a tool requires approval.
+   */
+  clearApprovalHandler() {
+    this.approvalHandler = void 0;
+    if (this._isStarted && this.services) {
+      this.services.approvalManager.clearHandler();
+    }
+    this.logger.debug("Approval handler cleared");
+  }
   // ============= AGENT MANAGEMENT =============
   // Note: Agent management methods have been moved to the Dexto orchestrator class.
   // See: /packages/core/src/Dexto.ts