wave-agent-sdk 0.0.7 → 0.0.10

package/src/agent.ts

@@ -4,16 +4,25 @@ import {
 } from "./managers/messageManager.js";
 import { AIManager } from "./managers/aiManager.js";
 import { ToolManager } from "./managers/toolManager.js";
-import { SubagentManager } from "./managers/subagentManager.js";
+import {
+  SubagentManager,
+  type SubagentManagerCallbacks,
+} 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,
@@ -21,11 +30,24 @@ import type {
   GatewayConfig,
   ModelConfig,
   Usage,
+  PermissionMode,
+  PermissionCallback,
 } from "./types/index.js";
 import { HookManager } from "./managers/hookManager.js";
-import { configResolver } from "./utils/configResolver.js";
+import { LiveConfigManager } from "./managers/liveConfigManager.js";
 import { configValidator } from "./utils/configValidator.js";
 import { SkillManager } from "./managers/skillManager.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
@@ -37,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;
@@ -52,20 +77,23 @@ export interface AgentOptions {
   workdir?: string;
   /**Optional custom system prompt - if provided, replaces default system prompt */
   systemPrompt?: string;
-
-  // New: Session directory configuration
-  /**
-   * Optional custom directory for session file storage
-   * @default join(homedir(), ".wave", "sessions")
-   * @example "/path/to/custom/sessions"
-   */
-  sessionDir?: 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 {}
+    McpManagerCallbacks,
+    SubagentManagerCallbacks {
+  onPermissionModeChange?: (mode: PermissionMode) => void;
+}
 
 export class Agent {
   private messageManager: MessageManager;
@@ -76,17 +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 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;
+    }
+
+    // Re-validate configuration after update
+    this.resolveAndValidateConfig();
+  }
 
   /**
    * Agent constructor - handles configuration resolution and validation
@@ -96,7 +187,6 @@ export class Agent {
    * Agent.create() to maintain API consistency.
    *
    * @param options - Configuration options for the Agent instance
-   * @param options.sessionDir - Optional custom directory for session storage
    */
   private constructor(options: AgentOptions) {
     const {
@@ -104,47 +194,37 @@ export class Agent {
       logger,
       workdir,
       systemPrompt,
-      sessionDir,
+      stream = true,
     } = options;
 
-    // Resolve configuration from constructor args and environment variables
-    const gatewayConfig = configResolver.resolveGatewayConfig(
-      options.apiKey,
-      options.baseURL,
-    );
-    const modelConfig = configResolver.resolveModelConfig(
-      options.agentModel,
-      options.fastModel,
-    );
-    const tokenLimit = configResolver.resolveTokenLimit(options.tokenLimit);
+    // Set working directory early as we need it for loading configuration
+    this.workdir = workdir || process.cwd();
 
-    // 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.workdir = workdir || process.cwd(); // Set working directory, default to current working directory
     this.systemPrompt = systemPrompt; // Save custom system prompt
+    this.stream = stream; // Save streaming mode flag
 
-    // 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
+
+    // Initialize permission manager
+    this.permissionManager = new PermissionManager({ logger: this.logger });
+    this.permissionManager.setOnConfiguredDefaultModeChange((mode) => {
+      this.options.callbacks?.onPermissionModeChange?.(mode);
+    });
 
+    // Initialize configuration service and hooks manager
     this.hookManager = new HookManager(this.workdir, undefined, this.logger); // Initialize hooks manager
 
     // Initialize MessageManager
@@ -152,19 +232,89 @@ export class Agent {
       callbacks,
       workdir: this.workdir,
       logger: this.logger,
-      sessionDir,
     });
 
+    // 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({
       workdir: this.workdir,
       parentToolManager: this.toolManager,
       parentMessageManager: this.messageManager,
+      callbacks: {
+        onSubagentUserMessageAdded: callbacks.onSubagentUserMessageAdded,
+        onSubagentAssistantMessageAdded:
+          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),
     });
 
@@ -183,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
@@ -224,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);
       }
@@ -257,6 +409,31 @@ export class Agent {
     return this.workdir;
   }
 
+  /** 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 */
   public get isLoading(): boolean {
     return this.aiManager.isLoading;
@@ -303,9 +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.sessionDir - Optional custom directory for session file storage.
-   *   If not provided, defaults to ~/.wave/sessions/. Can be relative or absolute path.
-   *   Examples: "./app-sessions", "/var/myapp/sessions", "~/Documents/sessions"
+   * @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
@@ -317,22 +494,15 @@ export class Agent {
    *
    * @example
    * ```typescript
-   * // Basic usage with default session directory
+   * // Basic usage
    * const agent = await Agent.create({
    *   apiKey: 'your-api-key',
    *   baseURL: 'https://api.example.com'
    * });
-   *
-   * // Custom session directory
-   * const agent = await Agent.create({
-   *   apiKey: 'your-api-key',
-   *   baseURL: 'https://api.example.com',
-   *   sessionDir: './app-sessions'
-   * });
    * ```
    */
   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,
@@ -342,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;
@@ -351,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)
@@ -370,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
@@ -377,32 +574,253 @@ 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:",
+        error,
+      );
+      // 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(sessionToRestore?.messages || []);
+
+      if (sessionToRestore)
+        this.messageManager.initializeFromSession(sessionToRestore);
+    }
+  }
+
+  /**
+   * 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(messages: Message[]): Promise<void> {
+    try {
+      // Only attempt to restore subagent sessions if we have messages (session was restored)
+      if (messages.length === 0) {
+        return;
+      }
+
+      // Extract sessionId -> subagentId mapping from SubagentBlocks
+      const subagentBlockMap = new Map<
+        string,
+        { subagentId: string; configuration: SubagentConfiguration }
+      >(); // sessionId -> { subagentId, configuration }
+
+      for (const message of messages) {
+        if (message.role === "assistant" && message.blocks) {
+          for (const block of message.blocks) {
+            if (
+              block.type === "subagent" &&
+              block.sessionId &&
+              block.subagentId &&
+              block.configuration
+            ) {
+              subagentBlockMap.set(block.sessionId, {
+                subagentId: block.subagentId,
+                configuration: block.configuration,
+              });
+            }
+          }
+        }
+      }
+
+      if (subagentBlockMap.size === 0) {
+        return; // No subagent blocks found
+      }
+
+      // Load subagent sessions using sessionIds
+      const subagentSessions = [];
+      for (const [sessionId, blockData] of subagentBlockMap) {
+        try {
+          const sessionData = await loadSessionFromJsonl(
+            sessionId,
+            this.messageManager.getWorkdir(),
+            "subagent",
+          );
+          if (sessionData) {
+            subagentSessions.push({
+              sessionData,
+              subagentId: blockData.subagentId, // Use the subagentId from SubagentBlock
+              configuration: blockData.configuration, // Include configuration
+            });
+          }
+        } catch (error) {
+          this.logger?.warn(
+            `Failed to load subagent session ${sessionId}:`,
+            error,
+          );
+        }
+      }
+
+      if (subagentSessions.length > 0) {
+        this.logger?.debug(
+          `Found ${subagentSessions.length} subagent sessions to restore`,
+        );
+
+        // Restore subagent sessions through the SubagentManager
+        await this.subagentManager.restoreSubagentSessions(subagentSessions);
+
+        this.logger?.debug("Subagent sessions restored successfully");
+      }
+    } catch (error) {
+      this.logger?.warn("Failed to restore subagent sessions:", error);
+      // Don't throw error to prevent app startup failure
     }
   }
 
+  /**
+   * 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();
   }
@@ -451,10 +869,50 @@ 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
+    try {
+      await this.liveConfigManager.shutdown();
+    } catch (error) {
+      this.logger?.error(
+        "Error shutting down live configuration reload:",
+        error,
+      );
+    }
+    // Cleanup memory store
   }
 
+  /**
+   * 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 }>,
@@ -509,6 +967,7 @@ export class Agent {
               transcriptPath: this.messageManager.getTranscriptPath(),
               cwd: this.workdir,
               userPrompt: content,
+              env: this.configurationService.getEnvironmentVars(), // Include configuration environment variables
             },
           );
 
@@ -547,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}`,
@@ -566,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,
@@ -623,4 +1092,43 @@ export class Agent {
   public getCustomCommands(): CustomSlashCommand[] {
     return this.slashCommandManager.getCustomCommands();
   }
+
+  /**
+   * Get the current permission mode
+   */
+  public getPermissionMode(): PermissionMode {
+    return this.toolManager.getPermissionMode();
+  }
+
+  /**
+   * Set the permission mode
+   * @param mode - The new permission mode
+   */
+  public setPermissionMode(mode: PermissionMode): void {
+    this.toolManager.setPermissionMode(mode);
+    this.options.callbacks?.onPermissionModeChange?.(mode);
+  }
+
+  /**
+   * Add a persistent permission rule
+   * @param rule - The rule to add (e.g., "Bash(ls)")
+   */
+  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),
+        });
+      }
+    }
+  }
 }