wave-agent-sdk 0.19.8 → 1.0.0

package/dist/managers/aiManager.js

@@ -6,8 +6,8 @@ import { calculateComprehensiveTotalTokens } from "../utils/tokenCalculation.js"
 import { estimateTokens } from "../utils/tokenEstimate.js";
 import { getTaskReminderTurnCounts, maybeInjectTaskReminder, TASK_REMINDER_CONFIG, } from "../utils/taskReminder.js";
 import { existsSync } from "node:fs";
-import { buildSystemPrompt } from "../prompts/index.js";
-import { buildPlanModeReminder, buildPlanModeReEntryReminder, buildExitedPlanModeReminder, } from "../prompts/planModeReminders.js";
+import { buildSystemPrompt, formatCompactSummary, getCompactPrompt, } from "../prompts/index.js";
+import { buildPlanModeReminder, buildPlanModeReEntryReminder, buildExitedPlanModeReminder, wrapInSystemReminder, } from "../prompts/planModeReminders.js";
 import { recoverTruncatedJson } from "../utils/stringUtils.js";
 import { logger } from "../utils/globalLogger.js";
 import { startInteractionSpan, endInteractionSpan, startLLMRequestSpan, endLLMRequestSpan, resetTracingState, } from "../telemetry/sessionTracing.js";
@@ -99,9 +99,24 @@ export class AIManager {
     get configurationService() {
         return this.container.get("ConfigurationService");
     }
+    /**
+     * OS env merged with the per-session env snapshot. Falls back to process.env
+     * when ConfigurationService is absent or its getMergedEnv is missing (e.g. in
+     * unit tests with partial mocks), so hook-context env construction never
+     * throws. Use this (not the non-null `configurationService` getter) when
+     * building hook context env.
+     */
+    get mergedEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     // Getter methods for accessing dynamic configuration
     getGatewayConfig() {
-        return this.configurationService.resolveGatewayConfig();
+        return {
+            ...this.configurationService.resolveGatewayConfig(),
+            sessionId: this.messageManager.getSessionId(),
+        };
     }
     getModelConfig() {
         const permissionMode = this.container.has("PermissionMode")
@@ -348,30 +363,35 @@ export class AIManager {
         await this.messageManager.saveSession();
         this.setIsCompacting(true);
         try {
-            const recentChatMessages = convertMessagesForAPI(messagesToCompact);
-            // 4. Call compactMessages with optional custom instructions
-            const compactResult = await aiService.compactMessages({
-                gatewayConfig: this.getGatewayConfig(),
-                modelConfig: this.getModelConfig(),
-                messages: recentChatMessages,
-                abortSignal: options.abortSignal,
-                model: this.getModelConfig().fastModel,
-                customInstructions: mergedInstructions,
+            const modelConfig = this.getModelConfig();
+            const recentChatMessages = convertMessagesForAPI(messagesToCompact, {
+                supportsVision: supportsVision(modelConfig.capabilities),
             });
+            const compactPrompt = getCompactPrompt(mergedInstructions);
+            // 4. Fork path: fork the conversation with the same system prompt,
+            // tools, model, and generation params as the main loop so the forked
+            // request prefix matches exactly and the prompt cache is reused.
+            const forkResult = await this.runCompactFork(recentChatMessages, compactPrompt, options.abortSignal);
+            const summaryContent = forkResult.content;
+            const compactTokens = forkResult.usage;
+            if (!summaryContent) {
+                throw new Error("Compaction failed: the model produced no summary output");
+            }
+            const compactModel = modelConfig.model;
             // 5. Handle usage tracking
             let compactUsage;
-            if (compactResult.usage) {
+            if (compactTokens) {
                 compactUsage = {
-                    prompt_tokens: compactResult.usage.prompt_tokens,
-                    completion_tokens: compactResult.usage.completion_tokens,
-                    total_tokens: compactResult.usage.total_tokens,
-                    model: this.getModelConfig().fastModel,
+                    ...compactTokens,
+                    model: compactModel,
                     operation_type: "compact",
                 };
             }
-            // 6. Build post-compact context restoration
-            const enhancedSummary = await this.buildPostCompactContext(compactResult.content);
-            // 7. Execute message reconstruction
+            // 6. Strip the <analysis> scratchpad and extract the <summary> body
+            const formattedSummary = formatCompactSummary(summaryContent);
+            // 7. Build post-compact context restoration
+            const enhancedSummary = await this.buildPostCompactContext(formattedSummary);
+            // 8. Execute message reconstruction
             await this.messageManager.compactMessagesAndUpdateSession(enhancedSummary, compactUsage);
             // Re-add plan mode reminder as persistent meta message after compaction
             const postCompactMode = this.permissionManager?.getCurrentEffectiveMode(this.getModelConfig().permissionMode);
@@ -385,20 +405,20 @@ export class AIManager {
                     });
                 }
             }
-            // 8. Track usage
+            // 9. Track usage
             if (compactUsage && this.callbacks?.onUsageAdded) {
                 this.callbacks.onUsageAdded(compactUsage);
             }
             this.consecutiveCompactionFailures = 0;
             // Reset incremental tracing state after compaction
             resetTracingState();
-            // 9. Log OTEL event
+            // 10. Log OTEL event
             logOTelEvent("compaction", {
                 beforeTokens: String(messagesToCompact.length),
                 afterTokens: "1",
-                model: this.getModelConfig().fastModel,
+                model: compactModel,
             }).catch(() => { });
-            // 10. Run SessionStart hooks (existing behavior)
+            // 11. Run SessionStart hooks (existing behavior)
             if (this.hookManager) {
                 try {
                     const newSessionId = this.messageManager.getSessionId();
@@ -420,10 +440,10 @@ export class AIManager {
                     logger?.warn(`SessionStart hooks on compact failed: ${error.message}`);
                 }
             }
-            // 11. Run PostCompact hooks
+            // 12. Run PostCompact hooks
             if (this.hookManager) {
                 try {
-                    await this.hookManager.executePostCompactHooks(this.messageManager.getSessionId(), this.messageManager.getTranscriptPath(), compactResult.content);
+                    await this.hookManager.executePostCompactHooks(this.messageManager.getSessionId(), this.messageManager.getTranscriptPath(), formattedSummary);
                 }
                 catch (error) {
                     logger?.warn(`PostCompact hooks failed: ${error.message}`);
@@ -440,6 +460,115 @@ export class AIManager {
             this.setIsCompacting(false);
         }
     }
+    /**
+     * Build the system prompt used by the main agent loop. Extracted so the
+     * compaction fork can mirror it exactly — the forked request prefix must
+     * match the main conversation's for the prompt cache to be reused.
+     */
+    async buildMainSystemPrompt(filteredToolPlugins) {
+        let autoMemoryOptions;
+        if (this.getAutoMemoryEnabled()) {
+            const directory = this.memoryService.getAutoMemoryDirectory(this.getWorkdir());
+            const content = await this.memoryService.getAutoMemoryContent(this.getWorkdir());
+            autoMemoryOptions = { directory, content };
+        }
+        return buildSystemPrompt(this.systemPrompt, filteredToolPlugins, {
+            workdir: this.getWorkdir(),
+            originalWorkdir: this.getOriginalWorkdir(),
+            language: this.getLanguage(),
+            isSubagent: !!this.subagentType,
+            worktreeSession: this.getWorktreeSession(),
+            autoMemory: autoMemoryOptions,
+        });
+    }
+    resolveFilteredTools() {
+        const toolsConfig = this.getFilteredToolsConfig();
+        const toolNames = new Set(toolsConfig.map((t) => t.function.name));
+        const filteredToolPlugins = this.toolManager
+            .getTools()
+            .filter((t) => toolNames.has(t.name));
+        return { toolsConfig, toolNames, filteredToolPlugins };
+    }
+    /**
+     * Fork-path compaction: run a bounded agent loop over a copy of the
+     * conversation using the same system prompt, tools, model, and generation
+     * params as the main loop, so the forked request prefix matches exactly
+     * and the prompt cache is reused. Tool calls are denied locally (the model
+     * is told to summarize, not act) and their rejections are fed back for
+     * another turn. Returns undefined content when the model never produces
+     * text; the caller treats that as a compaction failure.
+     */
+    async runCompactFork(historyMessages, compactPrompt, abortSignal) {
+        const MAX_FORK_TURNS = 3;
+        const modelConfig = this.getModelConfig();
+        const gatewayConfig = this.getGatewayConfig();
+        const sessionId = this.messageManager.getSessionId();
+        const workdir = this.getWorkdir();
+        const forkMessages = [...historyMessages];
+        // Mirror the main loop's memory injection so the request prefix matches.
+        const { prependContent } = await this.messageManager.getMemoryForInjection();
+        if (prependContent.trim()) {
+            forkMessages.unshift({
+                role: "user",
+                content: wrapInSystemReminder(prependContent),
+            });
+        }
+        forkMessages.push({ role: "user", content: compactPrompt });
+        const { toolsConfig, filteredToolPlugins } = this.resolveFilteredTools();
+        const systemPrompt = await this.buildMainSystemPrompt(filteredToolPlugins);
+        let totalUsage;
+        let content;
+        for (let turn = 0; turn < MAX_FORK_TURNS; turn++) {
+            const result = await aiService.callAgent({
+                gatewayConfig,
+                modelConfig,
+                messages: forkMessages,
+                sessionId,
+                abortSignal,
+                workdir,
+                tools: toolsConfig,
+                systemPrompt,
+                toolChoice: this.toolChoiceOverride,
+                // Stream so a slow reasoning model emits first bytes before the
+                // gateway's idle timeout fires (non-streaming waits for the full
+                // summary, which exceeds the timeout on large contexts).
+                stream: true,
+            });
+            if (result.usage) {
+                totalUsage = {
+                    prompt_tokens: (totalUsage?.prompt_tokens ?? 0) + result.usage.prompt_tokens,
+                    completion_tokens: (totalUsage?.completion_tokens ?? 0) +
+                        result.usage.completion_tokens,
+                    total_tokens: (totalUsage?.total_tokens ?? 0) + result.usage.total_tokens,
+                };
+            }
+            if (result.content?.trim()) {
+                content = result.content;
+                break;
+            }
+            if (result.tool_calls && result.tool_calls.length > 0) {
+                // Deny all tool calls locally and feed the rejections back so the
+                // model gets another turn to produce the summary text.
+                forkMessages.push({
+                    role: "assistant",
+                    content: result.content ?? null,
+                    tool_calls: result.tool_calls,
+                });
+                for (const toolCall of result.tool_calls) {
+                    forkMessages.push({
+                        role: "tool",
+                        tool_call_id: toolCall.id,
+                        content: "Tool use is not allowed during compaction",
+                    });
+                }
+                continue;
+            }
+            // Neither text nor tool calls: retrying the identical request is
+            // pointless, bail out and let the caller fail the compaction.
+            break;
+        }
+        return { content, usage: totalUsage };
+    }
     /**
      * Build post-compact context restoration content.
      * Restores file reads, working directory, plan mode, skills, and background tasks.
@@ -573,7 +702,7 @@ export class AIManager {
         // has superseded us. setIsLoading(true) here also closes the "idle but
         // previous turn not finished" race window by marking us busy immediately.
         this.turnGeneration++;
-        const myGeneration = this.turnGeneration;
+        let myGeneration = this.turnGeneration;
         this.setIsLoading(true);
         outer: while (true) {
             let shouldRestart = false;
@@ -659,19 +788,10 @@ export class AIManager {
                     // Track if assistant message has been created
                     let assistantMessageCreated = false;
                     logger?.debug("modelConfig in sendAIMessage", this.getModelConfig());
-                    const toolsConfig = this.getFilteredToolsConfig();
-                    const toolNames = new Set(toolsConfig.map((t) => t.function.name));
-                    const filteredToolPlugins = this.toolManager
-                        .getTools()
-                        .filter((t) => toolNames.has(t.name));
-                    let autoMemoryOptions;
-                    if (this.getAutoMemoryEnabled()) {
-                        const directory = this.memoryService.getAutoMemoryDirectory(this.getWorkdir());
-                        const content = await this.memoryService.getAutoMemoryContent(this.getWorkdir());
-                        autoMemoryOptions = { directory, content };
-                    }
+                    const { toolsConfig, toolNames, filteredToolPlugins } = this.resolveFilteredTools();
                     // Get memory for message-array injection (not system prompt)
                     const { prependContent } = await this.messageManager.getMemoryForInjection();
+                    const mainSystemPrompt = await this.buildMainSystemPrompt(filteredToolPlugins);
                     // Call AI service with streaming callbacks if enabled
                     const callAgentOptions = {
                         gatewayConfig: this.getGatewayConfig(),
@@ -682,14 +802,7 @@ export class AIManager {
                         workdir: this.getWorkdir(), // Pass working directory
                         tools: toolsConfig, // Pass filtered tool configuration
                         model: model, // Use passed model
-                        systemPrompt: buildSystemPrompt(this.systemPrompt, filteredToolPlugins, {
-                            workdir: this.getWorkdir(),
-                            originalWorkdir: this.getOriginalWorkdir(),
-                            language: this.getLanguage(),
-                            isSubagent: !!this.subagentType,
-                            worktreeSession: this.getWorktreeSession(),
-                            autoMemory: autoMemoryOptions,
-                        }), // Pass custom system prompt
+                        systemPrompt: mainSystemPrompt, // Pass custom system prompt
                         maxTokens: maxTokens, // Pass max tokens override
                         toolChoice: this.toolChoiceOverride, // Pass tool_choice override
                     };
@@ -697,7 +810,7 @@ export class AIManager {
                     if (prependContent.trim()) {
                         callAgentOptions.messages.unshift({
                             role: "user",
-                            content: `<system-reminder>\n${prependContent}\n</system-reminder>`,
+                            content: wrapInSystemReminder(prependContent),
                         });
                     }
                     // Task reminder: persist as meta message (conditional rules already persisted above)
@@ -1087,6 +1200,14 @@ export class AIManager {
                             });
                         }
                     }
+                    // Re-assert loading state before restarting: if this turn was
+                    // aborted, abortAIMessage already reset loading to false, and the
+                    // restart below continues the conversation — the UI must show
+                    // streaming again (cursor, stop button, ESC handling).
+                    this.setIsLoading(true);
+                    // Adopt the current (possibly abort-bumped) generation so this
+                    // continued turn's end-of-turn cleanup is not skipped as superseded.
+                    myGeneration = this.turnGeneration;
                     // Restart outer loop to process the notifications
                     shouldRestart = true;
                     turnOffset = 0;
@@ -1156,7 +1277,7 @@ export class AIManager {
                 sessionCrons, // Stop-only: session cron jobs snapshot
                 lastAssistantMessage: lastAssistantText, // Stop/SubagentStop: last assistant message text
                 // Stop hooks don't need toolName, toolInput, toolResponse, or userPrompt
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)), // Include environment variables
+                env: Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined)), // Include environment variables
             };
             const results = await this.hookManager.executeHooks(hookName, context);
             // Process hook results to handle exit codes and appropriate responses
@@ -1311,7 +1432,7 @@ export class AIManager {
                     if (this.hookManager) {
                         const sessionId = this.messageManager.getSessionId();
                         const transcriptPath = this.messageManager.getTranscriptPath();
-                        const env = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined));
+                        const env = Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined));
                         await this.hookManager.executeCwdChangedHooks(oldCwd, newCwd, sessionId, transcriptPath, env);
                     }
                 },
@@ -1378,7 +1499,7 @@ export class AIManager {
                 cwd: this.getWorkdir(),
                 toolInput,
                 subagentType: this.subagentType, // Include subagent type in hook context
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)), // Include environment variables
+                env: Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined)), // Include environment variables
             };
             const results = await this.hookManager.executeHooks("PreToolUse", context);
             // Process hook results to handle exit codes and determine if tool should be blocked
@@ -1431,7 +1552,7 @@ export class AIManager {
                 toolResponse,
                 subagentType: this.subagentType, // Include subagent type in hook context
                 planFilePath: this.permissionManager?.getPlanFilePath(),
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)), // Include environment variables
+                env: Object.fromEntries(Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined)), // Include environment variables
             };
             const results = await this.hookManager.executeHooks("PostToolUse", context);
             // Process hook results to handle exit codes and update tool results

package/dist/managers/backgroundTaskManager.d.ts

@@ -15,6 +15,12 @@ export declare class BackgroundTaskManager {
     private callbacks;
     private workdir;
     constructor(container: Container, options: BackgroundTaskManagerOptions);
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * background-task subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    private get sessionEnv();
     /**
      * Fire the onBackgroundTasksChange callback so UI consumers refresh.
      * Public so other managers (e.g. WorkflowManager) can trigger a refresh

package/dist/managers/backgroundTaskManager.js

@@ -13,6 +13,16 @@ export class BackgroundTaskManager {
         this.callbacks = options.callbacks || {};
         this.workdir = options.workdir;
     }
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * background-task subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    get sessionEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     /**
      * Fire the onBackgroundTasksChange callback so UI consumers refresh.
      * Public so other managers (e.g. WorkflowManager) can trigger a refresh
@@ -44,6 +54,7 @@ export class BackgroundTaskManager {
             cwd: cwd ?? this.workdir,
             env: {
                 ...process.env,
+                ...this.sessionEnv,
             },
         });
         // Create log file

package/dist/managers/bangManager.d.ts

@@ -14,6 +14,12 @@ export declare class BangManager {
     onCommandRunningChange?: (running: boolean) => void;
     constructor(container: Container, options: BangManagerOptions);
     private get messageManager();
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * bang-command subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    private get sessionEnv();
     private setCommandRunning;
     executeCommand(command: string): Promise<number>;
     abortCommand(): void;

package/dist/managers/bangManager.js

@@ -10,6 +10,16 @@ export class BangManager {
     get messageManager() {
         return this.container.get("MessageManager");
     }
+    /**
+     * Merged env (OS env overlaid with this session's settings snapshot) for
+     * bang-command subprocesses, so settings `env` vars reach them without
+     * polluting other sessions in one `wave --stdio` process.
+     */
+    get sessionEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     setCommandRunning(isRunning) {
         this.isCommandRunning = isRunning;
         this.onCommandRunningChange?.(isRunning);
@@ -28,6 +38,7 @@ export class BangManager {
                 cwd: this.workdir,
                 env: {
                     ...process.env,
+                    ...this.sessionEnv,
                 },
             });
             this.currentProcess = child;

package/dist/managers/hookManager.d.ts

@@ -4,7 +4,7 @@
  * Central orchestrator for the hooks system. Handles configuration loading,
  * validation, and hook execution across all supported events.
  */
-import { type HookEvent, type HookExecutionContext, type ExtendedHookExecutionContext, type HookExecutionResult, type HookValidationResult, type SessionEndSource } from "../types/hooks.js";
+import { type HookEvent, type HookExecutionContext, type ExtendedHookExecutionContext, type HookExecutionResult, type HookValidationResult, type SessionEndSource, type SessionStartSource } from "../types/hooks.js";
 import type { WaveConfiguration, PartialHookConfiguration } from "../types/configuration.js";
 import { HookMatcher } from "../utils/hookMatcher.js";
 import type { MessageManager } from "./messageManager.js";
@@ -18,6 +18,12 @@ export declare class HookManager {
     private readonly matcher;
     private readonly workdir;
     constructor(container: Container, workdir: string, matcher?: HookMatcher);
+    /**
+     * Merged env for this session (OS env overlaid with the per-session settings
+     * snapshot). Hook subprocesses spawn with this env so settings.json `env`
+     * vars reach hooks without polluting other sessions in one stdio process.
+     */
+    private get sessionEnv();
     /**
      * Load hook configuration from programmatic source (AgentOptions.hooks)
      */
@@ -118,7 +124,7 @@ export declare class HookManager {
      * Execute SessionStart hooks during initialization.
      * Collects additionalContext and initialUserMessage from hook stdout.
      */
-    executeSessionStartHooks(source: "startup" | "compact" | "clear", sessionId: string, transcriptPath: string, agentType?: string): Promise<{
+    executeSessionStartHooks(source: SessionStartSource, sessionId: string, transcriptPath: string, agentType?: string): Promise<{
         results: HookExecutionResult[];
         additionalContext?: string;
         initialUserMessage?: string;

package/dist/managers/hookManager.js

@@ -18,6 +18,16 @@ export class HookManager {
         this.workdir = workdir;
         this.matcher = matcher;
     }
+    /**
+     * Merged env for this session (OS env overlaid with the per-session settings
+     * snapshot). Hook subprocesses spawn with this env so settings.json `env`
+     * vars reach hooks without polluting other sessions in one stdio process.
+     */
+    get sessionEnv() {
+        return (this.container
+            .get("ConfigurationService")
+            ?.getMergedEnv?.() ?? process.env);
+    }
     /**
      * Load hook configuration from programmatic source (AgentOptions.hooks)
      */
@@ -674,7 +684,7 @@ export class HookManager {
             cwd: this.workdir,
             source,
             agentType,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("SessionStart", context);
         let additionalContext;
@@ -718,7 +728,7 @@ export class HookManager {
             transcriptPath,
             cwd: this.workdir,
             endSource: source,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("SessionEnd", context);
         // Process results but never block shutdown
@@ -740,7 +750,7 @@ export class HookManager {
             transcriptPath,
             cwd: this.workdir,
             compactInstructions: customInstructions,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("PreCompact", context);
         let additionalInstructions;
@@ -767,7 +777,7 @@ export class HookManager {
             transcriptPath,
             cwd: this.workdir,
             compactSummary,
-            env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+            env: Object.fromEntries(Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined)),
         };
         const results = await this.executeHooks("PostCompact", context);
         if (results.length > 0) {

package/dist/managers/mcpManager.d.ts

@@ -11,13 +11,21 @@ export interface McpManagerOptions {
     /** Pre-configured MCP servers passed from constructor options */
     mcpServers?: Record<string, McpServerConfig>;
 }
-export declare function expandEnvVars(value: string): string;
+/**
+ * Expand environment variables in a string value.
+ * Supports ${VAR} and ${VAR:-default} patterns.
+ *
+ * @param env - Merged env to resolve against (session snapshot over OS env).
+ *              Defaults to `process.env` for backward compatibility with tests
+ *              and standalone callers.
+ */
+export declare function expandEnvVars(value: string, env?: Record<string, string | undefined>): string;
 /**
  * Walk an MCP config and resolve environment variables in all string fields.
- * Only expands ${VAR} from process.env (skipping WAVE_PLUGIN_ROOT which is
- * handled at spawn time).
+ * Expands ${VAR} against the session env snapshot (over OS env); falls back to
+ * process.env. WAVE_PLUGIN_ROOT is skipped — handled at spawn time.
  */
-export declare function resolveMcpConfig(config: McpConfig): McpConfig;
+export declare function resolveMcpConfig(config: McpConfig, env?: Record<string, string | undefined>): McpConfig;
 export declare class McpManager {
     private container;
     private config;
@@ -30,6 +38,12 @@ export declare class McpManager {
     private reconnectTimers;
     private reconnectAttempts;
     constructor(container: Container, options?: McpManagerOptions);
+    /**
+     * Merged env for this session: OS env overlaid with the per-session settings
+     * snapshot. MCP env-var expansion (${VAR}) resolves against this so multiple
+     * sessions in one `wave --stdio` process don't read each other's settings env.
+     */
+    private get envSnapshot();
     /**
      * Initialize MCP manager with working directory and optionally auto-connect
      */