wave-agent-sdk 0.0.8 → 0.0.10

package/src/agent.ts

@@ -10,13 +10,19 @@ import {
 } from "./managers/subagentManager.js";
 import * as memory from "./services/memory.js";
 import { McpManager, type McpManagerCallbacks } from "./managers/mcpManager.js";
+import { LspManager } from "./managers/lspManager.js";
 import { BashManager } from "./managers/bashManager.js";
 import {
   BackgroundBashManager,
   type BackgroundBashManagerCallbacks,
 } from "./managers/backgroundBashManager.js";
 import { SlashCommandManager } from "./managers/slashCommandManager.js";
-import type { SlashCommand, CustomSlashCommand } from "./types/index.js";
+import { PermissionManager } from "./managers/permissionManager.js";
+import type {
+  SlashCommand,
+  CustomSlashCommand,
+  ILspManager,
+} from "./types/index.js";
 import type {
   Message,
   Logger,
@@ -24,17 +30,24 @@ import type {
   GatewayConfig,
   ModelConfig,
   Usage,
+  PermissionMode,
+  PermissionCallback,
 } from "./types/index.js";
 import { HookManager } from "./managers/hookManager.js";
-import { MemoryStoreService } from "./services/memoryStore.js";
-import { initializeMemoryStore } from "./services/memory.js";
 import { LiveConfigManager } from "./managers/liveConfigManager.js";
-import { configResolver } from "./utils/configResolver.js";
 import { configValidator } from "./utils/configValidator.js";
 import { SkillManager } from "./managers/skillManager.js";
-import { loadSessionFromJsonl } from "./services/session.js";
+import {
+  loadSessionFromJsonl,
+  handleSessionRestoration,
+} from "./services/session.js";
 import type { SubagentConfiguration } from "./utils/subagentParser.js";
 import { setGlobalLogger } from "./utils/globalLogger.js";
+import { ConfigurationService } from "./services/configurationService.js";
+import * as fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { ClientOptions } from "openai";
 
 /**
  * Configuration options for Agent instances
@@ -46,6 +59,9 @@ export interface AgentOptions {
   // Optional configuration with environment fallbacks
   apiKey?: string;
   baseURL?: string;
+  defaultHeaders?: Record<string, string>;
+  fetchOptions?: ClientOptions["fetchOptions"];
+  fetch?: ClientOptions["fetch"];
   agentModel?: string;
   fastModel?: string;
   tokenLimit?: number;
@@ -61,13 +77,23 @@ export interface AgentOptions {
   workdir?: string;
   /**Optional custom system prompt - if provided, replaces default system prompt */
   systemPrompt?: string;
+  /**Permission mode - defaults to "default" */
+  permissionMode?: PermissionMode;
+  /**Custom permission callback */
+  canUseTool?: PermissionCallback;
+  /**Whether to use streaming mode for AI responses - defaults to true */
+  stream?: boolean;
+  /**Optional custom LSP manager - if not provided, a standalone one will be created */
+  lspManager?: ILspManager;
 }
 
 export interface AgentCallbacks
   extends MessageManagerCallbacks,
     BackgroundBashManagerCallbacks,
     McpManagerCallbacks,
-    SubagentManagerCallbacks {}
+    SubagentManagerCallbacks {
+  onPermissionModeChange?: (mode: PermissionMode) => void;
+}
 
 export class Agent {
   private messageManager: MessageManager;
@@ -78,26 +104,80 @@ export class Agent {
   private logger?: Logger; // Add optional logger property
   private toolManager: ToolManager; // Add tool registry instance
   private mcpManager: McpManager; // Add MCP manager instance
+  private lspManager: ILspManager; // Add LSP manager instance
+  private permissionManager: PermissionManager; // Add permission manager instance
   private subagentManager: SubagentManager; // Add subagent manager instance
   private slashCommandManager: SlashCommandManager; // Add slash command manager instance
   private hookManager: HookManager; // Add hooks manager instance
-  private memoryStore: MemoryStoreService; // Add memory store service
   private liveConfigManager: LiveConfigManager; // Add live configuration manager
+  private configurationService: ConfigurationService; // Add configuration service
   private workdir: string; // Working directory
   private systemPrompt?: string; // Custom system prompt
   private _usages: Usage[] = []; // Usage tracking array
+  private stream: boolean; // Streaming mode flag
+
+  // Configuration options storage for dynamic resolution
+  private options: AgentOptions;
+
+  // Memory content storage
+  private _projectMemoryContent: string = "";
+  private _userMemoryContent: string = "";
+
+  // Dynamic configuration getter methods
+  public getGatewayConfig(): GatewayConfig {
+    return this.configurationService.resolveGatewayConfig(
+      this.options.apiKey,
+      this.options.baseURL,
+      this.options.defaultHeaders,
+      this.options.fetchOptions,
+      this.options.fetch,
+    );
+  }
+
+  public getModelConfig(): ModelConfig {
+    return this.configurationService.resolveModelConfig(
+      this.options.agentModel,
+      this.options.fastModel,
+    );
+  }
+
+  public getTokenLimit(): number {
+    return this.configurationService.resolveTokenLimit(this.options.tokenLimit);
+  }
+
+  /**
+   * Update agent configuration dynamically
+   *
+   * @param config - Configuration updates for gateway, model, and token limit
+   */
+  public updateConfig(config: {
+    gateway?: Partial<GatewayConfig>;
+    model?: Partial<ModelConfig>;
+    tokenLimit?: number;
+  }): void {
+    if (config.gateway) {
+      this.options.apiKey = config.gateway.apiKey ?? this.options.apiKey;
+      this.options.baseURL = config.gateway.baseURL ?? this.options.baseURL;
+      this.options.defaultHeaders =
+        config.gateway.defaultHeaders ?? this.options.defaultHeaders;
+      this.options.fetchOptions =
+        config.gateway.fetchOptions ?? this.options.fetchOptions;
+      this.options.fetch = config.gateway.fetch ?? this.options.fetch;
+    }
+
+    if (config.model) {
+      this.options.agentModel =
+        config.model.agentModel ?? this.options.agentModel;
+      this.options.fastModel = config.model.fastModel ?? this.options.fastModel;
+    }
 
-  // Configuration properties
-  private gatewayConfig: GatewayConfig;
-  private modelConfig: ModelConfig;
-  private tokenLimit: number;
+    if (config.tokenLimit !== undefined) {
+      this.options.tokenLimit = config.tokenLimit;
+    }
 
-  // Original constructor values for preserving overrides during live updates
-  private readonly constructorApiKey?: string;
-  private readonly constructorBaseURL?: string;
-  private readonly constructorAgentModel?: string;
-  private readonly constructorFastModel?: string;
-  private readonly constructorTokenLimit?: number;
+    // Re-validate configuration after update
+    this.resolveAndValidateConfig();
+  }
 
   /**
    * Agent constructor - handles configuration resolution and validation
@@ -109,110 +189,43 @@ export class Agent {
    * @param options - Configuration options for the Agent instance
    */
   private constructor(options: AgentOptions) {
-    const { callbacks = {}, logger, workdir, systemPrompt } = options;
-
-    // Set working directory first so it can be used for configuration resolution
+    const {
+      callbacks = {},
+      logger,
+      workdir,
+      systemPrompt,
+      stream = true,
+    } = options;
+
+    // Set working directory early as we need it for loading configuration
     this.workdir = workdir || process.cwd();
 
-    // Store original constructor values for live config updates
-    this.constructorApiKey = options.apiKey;
-    this.constructorBaseURL = options.baseURL;
-    this.constructorAgentModel = options.agentModel;
-    this.constructorFastModel = options.fastModel;
-    this.constructorTokenLimit = options.tokenLimit;
-
-    // Resolve configuration from constructor args and environment variables with live config support
-    const gatewayConfig = configResolver.resolveGatewayConfig(
-      options.apiKey,
-      options.baseURL,
-      this.workdir,
-    );
-    const modelConfig = configResolver.resolveModelConfig(
-      options.agentModel,
-      options.fastModel,
-      this.workdir,
-    );
-    const tokenLimit = configResolver.resolveTokenLimit(
-      options.tokenLimit,
-      this.workdir,
-    );
-
-    // Validate resolved configuration
-    configValidator.validateGatewayConfig(gatewayConfig);
-    configValidator.validateTokenLimit(tokenLimit);
-    configValidator.validateModelConfig(
-      modelConfig.agentModel,
-      modelConfig.fastModel,
-    );
+    // Initialize configuration service
+    this.configurationService = new ConfigurationService();
 
     this.logger = logger; // Save the passed logger
     this.systemPrompt = systemPrompt; // Save custom system prompt
+    this.stream = stream; // Save streaming mode flag
 
-    // Set global logger for SDK-wide access
-    setGlobalLogger(logger || null);
-
-    // Store resolved configuration
-    this.gatewayConfig = gatewayConfig;
-    this.modelConfig = modelConfig;
-    this.tokenLimit = tokenLimit;
+    // Store options for dynamic configuration resolution
+    this.options = options;
 
     this.backgroundBashManager = new BackgroundBashManager({
       callbacks,
       workdir: this.workdir,
     });
     this.mcpManager = new McpManager({ callbacks, logger: this.logger }); // Initialize MCP manager
-    this.toolManager = new ToolManager({
-      mcpManager: this.mcpManager,
-      logger: this.logger,
-    }); // Initialize tool registry, pass MCP manager
+    this.lspManager =
+      options.lspManager || new LspManager({ logger: this.logger }); // Initialize LSP manager
 
-    this.memoryStore = new MemoryStoreService(this.logger); // Initialize memory store service
-    initializeMemoryStore(this.memoryStore); // Initialize global memory store reference
-    this.hookManager = new HookManager(this.workdir, undefined, this.logger); // Initialize hooks manager
-    this.liveConfigManager = new LiveConfigManager({
-      workdir: this.workdir,
-      logger: this.logger,
-      onConfigurationChanged: () => {
-        // Update Agent configuration (AIManager, SubagentManager)
-        this.updateConfiguration();
+    // Initialize permission manager
+    this.permissionManager = new PermissionManager({ logger: this.logger });
+    this.permissionManager.setOnConfiguredDefaultModeChange((mode) => {
+      this.options.callbacks?.onPermissionModeChange?.(mode);
+    });
 
-        // Reload hook configuration
-        try {
-          this.hookManager.loadConfigurationFromSettings();
-          this.logger?.info(
-            "Live Config: Hook configuration reloaded successfully",
-          );
-        } catch (error) {
-          this.logger?.error(
-            `Live Config: Failed to reload hook configuration: ${(error as Error).message}`,
-          );
-        }
-      },
-      onMemoryStoreFileChanged: async (
-        filePath: string,
-        changeType: "add" | "change" | "unlink",
-      ) => {
-        try {
-          if (changeType === "unlink") {
-            // Handle file deletion gracefully
-            this.memoryStore.removeContent(filePath);
-            this.logger?.info(
-              "Live Config: Removed AGENTS.md from memory store due to file deletion",
-            );
-          } else {
-            // Update memory store content for add/change
-            await this.memoryStore.updateContent(filePath);
-            this.logger?.info(
-              "Live Config: Updated AGENTS.md content in memory store",
-            );
-          }
-        } catch (error) {
-          this.logger?.error(
-            `Live Config: Failed to update memory store: ${(error as Error).message}`,
-          );
-        }
-      },
-    }); // Initialize live configuration manager
+    // Initialize configuration service and hooks manager
+    this.hookManager = new HookManager(this.workdir, undefined, this.logger); // Initialize hooks manager
 
     // Initialize MessageManager
     this.messageManager = new MessageManager({
@@ -221,6 +234,65 @@ export class Agent {
       logger: this.logger,
     });
 
+    // Create a wrapper for canUseTool that triggers notification hooks
+    const canUseToolWithNotification: PermissionCallback | undefined =
+      options.canUseTool
+        ? async (context) => {
+            try {
+              // Trigger notification hooks before calling the original callback
+              const notificationMessage = `Claude needs your permission to use ${context.toolName}`;
+              await this.hookManager.executeHooks("Notification", {
+                event: "Notification",
+                projectDir: this.workdir,
+                timestamp: new Date(),
+                sessionId: this.sessionId,
+                transcriptPath: this.messageManager.getTranscriptPath(),
+                cwd: this.workdir,
+                message: notificationMessage,
+                notificationType: "permission_prompt",
+                env: this.configurationService.getEnvironmentVars(), // Include configuration environment variables
+              });
+            } catch (error) {
+              this.logger?.warn("Failed to execute notification hooks", {
+                toolName: context.toolName,
+                error: error instanceof Error ? error.message : String(error),
+              });
+              // Continue with permission check even if hooks fail
+            }
+
+            // Call the original callback
+            const decision = await options.canUseTool!(context);
+
+            // Handle state changes from decision
+            if (decision.newPermissionMode) {
+              this.setPermissionMode(decision.newPermissionMode);
+            }
+
+            if (decision.newPermissionRule) {
+              await this.addPermissionRule(decision.newPermissionRule);
+            }
+
+            return decision;
+          }
+        : undefined;
+
+    // Initialize tool manager with permission context
+    this.toolManager = new ToolManager({
+      mcpManager: this.mcpManager,
+      lspManager: this.lspManager,
+      logger: this.logger,
+      permissionManager: this.permissionManager,
+      permissionMode: options.permissionMode, // Let PermissionManager handle defaultMode resolution
+      canUseToolCallback: canUseToolWithNotification,
+    }); // Initialize tool registry with permission support
+    this.liveConfigManager = new LiveConfigManager({
+      workdir: this.workdir,
+      logger: this.logger,
+      hookManager: this.hookManager,
+      permissionManager: this.permissionManager,
+      configurationService: this.configurationService,
+    }); // Initialize live configuration manager
+
     // Initialize subagent manager with all dependencies in constructor
     // IMPORTANT: Must be initialized AFTER MessageManager
     this.subagentManager = new SubagentManager({
@@ -233,13 +305,15 @@ export class Agent {
           callbacks.onSubagentAssistantMessageAdded,
         onSubagentAssistantContentUpdated:
           callbacks.onSubagentAssistantContentUpdated,
+        onSubagentAssistantReasoningUpdated:
+          callbacks.onSubagentAssistantReasoningUpdated,
         onSubagentToolBlockUpdated: callbacks.onSubagentToolBlockUpdated,
         onSubagentMessagesChange: callbacks.onSubagentMessagesChange,
       }, // Pass subagent callbacks for forwarding
       logger: this.logger,
-      gatewayConfig,
-      modelConfig,
-      tokenLimit,
+      getGatewayConfig: () => this.getGatewayConfig(),
+      getModelConfig: () => this.getModelConfig(),
+      getTokenLimit: () => this.getTokenLimit(),
       hookManager: this.hookManager,
       onUsageAdded: (usage) => this.addUsage(usage),
     });
@@ -259,9 +333,11 @@ export class Agent {
       },
       workdir: this.workdir,
       systemPrompt: this.systemPrompt,
-      gatewayConfig: this.gatewayConfig,
-      modelConfig: this.modelConfig,
-      tokenLimit: this.tokenLimit,
+      stream: this.stream, // Pass streaming mode flag
+      getGatewayConfig: () => this.getGatewayConfig(),
+      getModelConfig: () => this.getModelConfig(),
+      getTokenLimit: () => this.getTokenLimit(),
+      getEnvironmentVars: () => this.configurationService.getEnvironmentVars(), // Provide access to configuration environment variables
     });
 
     // Initialize command manager
@@ -300,9 +376,9 @@ export class Agent {
    * Rebuild usage array from messages containing usage metadata
    * Called during session restoration to reconstruct usage tracking
    */
-  private rebuildUsageFromMessages(): void {
+  private rebuildUsageFromMessages(messages: Message[]): void {
     this._usages = [];
-    this.messages.forEach((message) => {
+    messages.forEach((message) => {
       if (message.role === "assistant" && message.usage) {
         this._usages.push(message.usage);
       }
@@ -333,9 +409,29 @@ export class Agent {
     return this.workdir;
   }
 
-  /** Get merged environment variables from Wave configuration */
-  public get environmentVars(): Record<string, string> | undefined {
-    return this.hookManager.getEnvironmentVars();
+  /** Get project memory content */
+  public get projectMemory(): string {
+    return this._projectMemoryContent;
+  }
+
+  /** Get user memory content */
+  public get userMemory(): string {
+    return this._userMemoryContent;
+  }
+
+  /** Get combined memory content (project + user) */
+  public get combinedMemory(): string {
+    let combined = "";
+    if (this._projectMemoryContent.trim()) {
+      combined += this._projectMemoryContent;
+    }
+    if (this._userMemoryContent.trim()) {
+      if (combined) {
+        combined += "\n\n";
+      }
+      combined += this._userMemoryContent;
+    }
+    return combined;
   }
 
   /** Get AI loading status */
@@ -384,6 +480,9 @@ export class Agent {
    * @param options - Configuration options for the Agent instance
    * @param options.apiKey - API key for the AI service (or set WAVE_API_KEY env var)
    * @param options.baseURL - Base URL for the AI service (or set WAVE_BASE_URL env var)
+   * @param options.defaultHeaders - Optional HTTP headers to pass to the AI service
+   * @param options.fetchOptions - Optional fetch options to pass to the AI service
+   * @param options.fetch - Optional custom fetch implementation
    * @param options.callbacks - Optional callbacks for various Agent events
    * @param options.restoreSessionId - Optional session ID to restore from
    * @param options.continueLastSession - Whether to continue the last session automatically
@@ -403,7 +502,7 @@ export class Agent {
    * ```
    */
   static async create(options: AgentOptions): Promise<Agent> {
-    // Create Agent instance - configuration resolution and validation now happens in constructor
+    // Create Agent instance
     const instance = new Agent(options);
     await instance.initialize({
       restoreSessionId: options.restoreSessionId,
@@ -413,6 +512,27 @@ export class Agent {
     return instance;
   }
 
+  /**
+   * Resolve and validate configuration from constructor args, environment variables,
+   * and loaded settings.json.
+   *
+   * This is called during initialization after settings.json has been loaded.
+   */
+  private resolveAndValidateConfig(): void {
+    // Resolve configuration from constructor args and environment variables (including settings.json)
+    const gatewayConfig = this.getGatewayConfig();
+    const modelConfig = this.getModelConfig();
+    const tokenLimit = this.getTokenLimit();
+
+    // Validate resolved configuration
+    configValidator.validateGatewayConfig(gatewayConfig);
+    configValidator.validateTokenLimit(tokenLimit);
+    configValidator.validateModelConfig(
+      modelConfig.agentModel,
+      modelConfig.fastModel,
+    );
+  }
+
   /** Private initialization method, handles async initialization logic */
   private async initialize(options?: {
     restoreSessionId?: string;
@@ -422,7 +542,10 @@ export class Agent {
     // Initialize managers first
     try {
       // Initialize SkillManager
-      const skillManager = new SkillManager({ logger: this.logger });
+      const skillManager = new SkillManager({
+        logger: this.logger,
+        workdir: this.workdir,
+      });
       await skillManager.initialize();
 
       // Initialize SubagentManager (load and cache configurations)
@@ -441,6 +564,9 @@ export class Agent {
     // Initialize MCP servers with auto-connect
     try {
       await this.mcpManager.initialize(this.workdir, true);
+      if (this.lspManager instanceof LspManager) {
+        await this.lspManager.initialize(this.workdir);
+      }
     } catch (error) {
       this.logger?.error("Failed to initialize MCP servers:", error);
       // Don't throw error to prevent app startup failure
@@ -448,20 +574,58 @@ export class Agent {
 
     // Initialize hooks configuration
     try {
-      // Load hooks configuration from user and project settings
+      // Load hooks configuration using ConfigurationService
       this.logger?.debug("Loading hooks configuration...");
-      this.hookManager.loadConfigurationFromSettings();
+      const configResult =
+        await this.configurationService.loadMergedConfiguration(this.workdir);
+
+      this.hookManager.loadConfigurationFromWaveConfig(
+        configResult.configuration,
+      );
       this.logger?.debug("Hooks system initialized successfully");
     } catch (error) {
       this.logger?.error("Failed to initialize hooks system:", error);
       // Don't throw error to prevent app startup failure
     }
 
+    // Resolve and validate configuration after loading settings.json
+    this.resolveAndValidateConfig();
+
+    // Set global logger for SDK-wide access after validation
+    setGlobalLogger(this.logger || null);
+
     // Initialize live configuration reload
     try {
       this.logger?.debug("Initializing live configuration reload...");
       await this.liveConfigManager.initialize();
       this.logger?.debug("Live configuration reload initialized successfully");
+
+      // Update permission manager with configuration-based defaultMode
+      const currentConfig = this.liveConfigManager.getCurrentConfiguration();
+      if (currentConfig?.defaultMode) {
+        this.logger?.debug(
+          "Applying configured defaultMode to PermissionManager",
+          {
+            defaultMode: currentConfig.defaultMode,
+          },
+        );
+        this.permissionManager.updateConfiguredDefaultMode(
+          currentConfig.defaultMode,
+        );
+      }
+
+      // Update permission manager with configuration-based allowed rules
+      if (currentConfig?.permissions?.allow) {
+        this.logger?.debug(
+          "Applying configured allowed rules to PermissionManager",
+          {
+            count: currentConfig.permissions.allow.length,
+          },
+        );
+        this.permissionManager.updateAllowedRules(
+          currentConfig.permissions.allow,
+        );
+      }
     } catch (error) {
       this.logger?.error(
         "Failed to initialize live configuration reload:",
@@ -470,23 +634,69 @@ export class Agent {
       // Don't throw error to prevent app startup failure - continue without live reload
     }
 
+    // Load memory files during initialization
+    try {
+      this.logger?.debug("Loading memory files...");
+
+      // Load project memory from AGENTS.md (bypass memory store for direct file access)
+      try {
+        const projectMemoryPath = path.join(this.workdir, "AGENTS.md");
+        this._projectMemoryContent = await fs.readFile(
+          projectMemoryPath,
+          "utf-8",
+        );
+        this.logger?.debug("Project memory loaded successfully");
+      } catch (error) {
+        this._projectMemoryContent = "";
+        this.logger?.debug(
+          "Project memory file not found or unreadable, using empty content:",
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+
+      // Load user memory (bypass memory store for direct file access)
+      try {
+        const userMemoryPath = path.join(os.homedir(), ".wave", "AGENTS.md");
+        this._userMemoryContent = await fs.readFile(userMemoryPath, "utf-8");
+        this.logger?.debug("User memory loaded successfully");
+      } catch (error) {
+        this._userMemoryContent = "";
+        this.logger?.debug(
+          "User memory file not found or unreadable, using empty content:",
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+
+      this.logger?.debug("Memory initialization completed");
+    } catch (error) {
+      // Ensure memory is always initialized even if loading fails
+      this._projectMemoryContent = "";
+      this._userMemoryContent = "";
+      this.logger?.error("Failed to load memory files:", error);
+      // Don't throw error to prevent app startup failure
+    }
+
     // Handle session restoration or set provided messages
     if (options?.messages) {
       // If messages are provided, use them directly (useful for testing)
       this.messageManager.setMessages(options.messages);
       // Rebuild usage array from restored messages
-      this.rebuildUsageFromMessages();
+      this.rebuildUsageFromMessages(options.messages);
     } else {
       // Otherwise, handle session restoration
-      await this.messageManager.handleSessionRestoration(
+      const sessionToRestore = await handleSessionRestoration(
         options?.restoreSessionId,
         options?.continueLastSession,
+        this.messageManager.getWorkdir(),
       );
       // Rebuild usage array from restored messages
-      this.rebuildUsageFromMessages();
+      this.rebuildUsageFromMessages(sessionToRestore?.messages || []);
 
       // After main session is restored, restore any associated subagent sessions
-      await this.restoreSubagentSessions();
+      await this.restoreSubagentSessions(sessionToRestore?.messages || []);
+
+      if (sessionToRestore)
+        this.messageManager.initializeFromSession(sessionToRestore);
     }
   }
 
@@ -494,10 +704,10 @@ export class Agent {
    * Restore subagent sessions associated with the current main session
    * This method is called after the main session is restored to load any subagent sessions
    */
-  private async restoreSubagentSessions(): Promise<void> {
+  private async restoreSubagentSessions(messages: Message[]): Promise<void> {
     try {
       // Only attempt to restore subagent sessions if we have messages (session was restored)
-      if (this.messages.length === 0) {
+      if (messages.length === 0) {
         return;
       }
 
@@ -507,7 +717,7 @@ export class Agent {
         { subagentId: string; configuration: SubagentConfiguration }
       >(); // sessionId -> { subagentId, configuration }
 
-      for (const message of this.messages) {
+      for (const message of messages) {
         if (message.role === "assistant" && message.blocks) {
           for (const block of message.blocks) {
             if (
@@ -536,6 +746,7 @@ export class Agent {
           const sessionData = await loadSessionFromJsonl(
             sessionId,
             this.messageManager.getWorkdir(),
+            "subagent",
           );
           if (sessionData) {
             subagentSessions.push({
@@ -568,6 +779,48 @@ export class Agent {
     }
   }
 
+  /**
+   * Restore a session by ID, switching to the target session without destroying the Agent instance
+   * @param sessionId - The ID of the session to restore
+   */
+  public async restoreSession(sessionId: string): Promise<void> {
+    // 1. Validation
+    if (!sessionId || sessionId === this.sessionId) {
+      return; // No-op if session ID is invalid or already current
+    }
+
+    // 2. Auto-save current session
+    try {
+      await this.messageManager.saveSession();
+    } catch (error) {
+      this.logger?.warn(
+        "Failed to save current session before restore:",
+        error,
+      );
+      // Continue with restoration even if save fails
+    }
+
+    // 3. Load target session
+    const sessionData = await loadSessionFromJsonl(
+      sessionId,
+      this.messageManager.getWorkdir(),
+    );
+    if (!sessionData) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    // 4. Clean current state
+    this.abortMessage(); // Abort any running operations
+    this.subagentManager.cleanup(); // Clean up active subagents
+
+    // 5. Rebuild usage and restore subagents (in correct order)
+    this.rebuildUsageFromMessages(sessionData.messages);
+    await this.restoreSubagentSessions(sessionData.messages);
+
+    // 6. Initialize session state last
+    this.messageManager.initializeFromSession(sessionData);
+  }
+
   public abortAIMessage(): void {
     this.aiManager.abortAIMessage();
   }
@@ -616,6 +869,10 @@ export class Agent {
     this.backgroundBashManager.cleanup();
     // Cleanup MCP connections
     await this.mcpManager.cleanup();
+    // Cleanup LSP connections
+    if (this.lspManager instanceof LspManager) {
+      await this.lspManager.cleanup();
+    }
     // Cleanup subagent manager
     this.subagentManager.cleanup();
     // Cleanup live configuration reload
@@ -628,14 +885,34 @@ export class Agent {
       );
     }
     // Cleanup memory store
-    try {
-      this.memoryStore.clear();
-      this.logger?.debug("Memory store cleared successfully");
-    } catch (error) {
-      this.logger?.error("Error clearing memory store:", error);
-    }
   }
 
+  /**
+   * Send a message to the AI agent with optional images
+   *
+   * @param content - The text content of the message to send
+   * @param images - Optional array of images to include with the message
+   * @param images[].path - File path to the image or base64 encoded image data
+   * @param images[].mimeType - MIME type of the image (e.g., 'image/png', 'image/jpeg')
+   * @returns Promise that resolves when the message has been processed
+   *
+   * @example
+   * ```typescript
+   * // Send a text message
+   * await agent.sendMessage("Hello, how are you?");
+   *
+   * // Send a message with images using file paths
+   * await agent.sendMessage("What do you see in these images?", [
+   *   { path: "/path/to/image.png", mimeType: "image/png" },
+   *   { path: "/path/to/photo.jpg", mimeType: "image/jpeg" }
+   * ]);
+   *
+   * // Send a message with base64 encoded image
+   * await agent.sendMessage("Analyze this image", [
+   *   { path: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", mimeType: "image/png" }
+   * ]);
+   * ```
+   */
   public async sendMessage(
     content: string,
     images?: Array<{ path: string; mimeType: string }>,
@@ -690,6 +967,7 @@ export class Agent {
               transcriptPath: this.messageManager.getTranscriptPath(),
               cwd: this.workdir,
               userPrompt: content,
+              env: this.configurationService.getEnvironmentVars(), // Include configuration environment variables
             },
           );
 
@@ -728,16 +1006,25 @@ export class Agent {
     type: "project" | "user",
   ): Promise<void> {
     try {
+      // Ensure the message starts with # for memory functions
+      const formattedMessage = message.startsWith("#")
+        ? message
+        : `#${message}`;
+
       if (type === "project") {
-        await memory.addMemory(message, this.workdir);
+        await memory.addMemory(formattedMessage, this.workdir);
+        // Update internal state after successful save
+        this._projectMemoryContent = await memory.readMemoryFile(this.workdir);
       } else {
-        await memory.addUserMemory(message);
+        await memory.addUserMemory(formattedMessage);
+        // Update internal state after successful save
+        this._userMemoryContent = await memory.getUserMemoryContent();
       }
 
       // Add successful MemoryBlock to the last assistant message
       const memoryText = message.substring(1).trim();
       const typeLabel = type === "project" ? "Project Memory" : "User Memory";
-      const storagePath = type === "project" ? "AGENTS.md" : "user-memory.md";
+      const storagePath = "AGENTS.md";
 
       this.messageManager.addMemoryBlock(
         `${typeLabel}: ${memoryText}`,
@@ -747,13 +1034,14 @@ export class Agent {
       );
     } catch (error) {
       // Add failed MemoryBlock to the last assistant message
+      const memoryText = message.substring(1).trim();
       const typeLabel = type === "project" ? "Project Memory" : "User Memory";
-      const storagePath = type === "project" ? "AGENTS.md" : "user-memory.md";
+      const storagePath = "AGENTS.md";
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
 
       this.messageManager.addMemoryBlock(
-        `${typeLabel} add failed: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
+        `${typeLabel}: ${memoryText} - Error: ${errorMessage}`,
         false,
         type,
         storagePath,
@@ -805,86 +1093,42 @@ export class Agent {
     return this.slashCommandManager.getCustomCommands();
   }
 
-  // ========== Live Configuration Management ==========
-
   /**
-   * Update Agent configuration from live settings.json changes
-   * This method refreshes all configuration-dependent components with new values
-   * Note: Constructor values still take precedence over live configuration
+   * Get the current permission mode
    */
-  public updateConfiguration(): void {
-    try {
-      this.logger?.info(
-        "Live Config: Updating Agent configuration from live settings",
-      );
-
-      // Re-resolve configuration with current workdir, preserving constructor overrides
-      // We need to track what was explicitly provided in constructor vs. what should use live config
-      const newGatewayConfig = configResolver.resolveGatewayConfig(
-        this.constructorApiKey, // Preserve constructor override if provided
-        this.constructorBaseURL, // Preserve constructor override if provided
-        this.workdir,
-      );
-      const newModelConfig = configResolver.resolveModelConfig(
-        this.constructorAgentModel, // Preserve constructor override if provided
-        this.constructorFastModel, // Preserve constructor override if provided
-        this.workdir,
-      );
-      const newTokenLimit = configResolver.resolveTokenLimit(
-        this.constructorTokenLimit,
-        this.workdir,
-      );
-
-      // Validate new configuration
-      configValidator.validateGatewayConfig(newGatewayConfig);
-      configValidator.validateTokenLimit(newTokenLimit);
-      configValidator.validateModelConfig(
-        newModelConfig.agentModel,
-        newModelConfig.fastModel,
-      );
-
-      // Update stored configuration
-      this.gatewayConfig = newGatewayConfig;
-      this.modelConfig = newModelConfig;
-      this.tokenLimit = newTokenLimit;
-
-      // Update AIManager with new configuration
-      this.aiManager.updateConfiguration(
-        newGatewayConfig,
-        newModelConfig,
-        newTokenLimit,
-      );
-
-      // Update SubagentManager with new configuration
-      this.subagentManager.updateConfiguration(
-        newGatewayConfig,
-        newModelConfig,
-        newTokenLimit,
-      );
+  public getPermissionMode(): PermissionMode {
+    return this.toolManager.getPermissionMode();
+  }
 
-      this.logger?.info(
-        `Live Config: Agent configuration updated successfully - model: ${newModelConfig.agentModel}, tokenLimit: ${newTokenLimit}`,
-      );
-    } catch (error) {
-      this.logger?.error(
-        `Live Config: Failed to update Agent configuration: ${(error as Error).message}`,
-      );
-      // Don't throw - continue with previous configuration
-    }
+  /**
+   * Set the permission mode
+   * @param mode - The new permission mode
+   */
+  public setPermissionMode(mode: PermissionMode): void {
+    this.toolManager.setPermissionMode(mode);
+    this.options.callbacks?.onPermissionModeChange?.(mode);
   }
 
   /**
-   * Get current Agent configuration for debugging
+   * Add a persistent permission rule
+   * @param rule - The rule to add (e.g., "Bash(ls)")
    */
-  public getCurrentConfiguration(): {
-    gatewayConfig: GatewayConfig;
-    modelConfig: ModelConfig;
-    tokenLimit: number;
-  } {
-    return {
-      gatewayConfig: { ...this.gatewayConfig },
-      modelConfig: { ...this.modelConfig },
-      tokenLimit: this.tokenLimit,
-    };
+  private async addPermissionRule(rule: string): Promise<void> {
+    // 1. Update PermissionManager state
+    const currentRules = this.permissionManager.getAllowedRules();
+    if (!currentRules.includes(rule)) {
+      this.permissionManager.updateAllowedRules([...currentRules, rule]);
+
+      // 2. Persist to settings.local.json
+      try {
+        await this.configurationService.addAllowedRule(this.workdir, rule);
+        this.logger?.debug("Persistent permission rule added", { rule });
+      } catch (error) {
+        this.logger?.error("Failed to persist permission rule", {
+          rule,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
   }
 }