wave-agent-sdk 0.19.9 → 1.0.1

package/src/managers/hookManager.ts

@@ -13,6 +13,7 @@ import {
   type HookExecutionResult,
   type HookValidationResult,
   type SessionEndSource,
+  type SessionStartSource,
   HookConfigurationError,
   isValidHookEvent,
   isValidHookEventConfig,
@@ -26,6 +27,7 @@ import { executeCommand, isCommandSafe } from "../services/hook.js";
 import { MessageSource } from "../types/index.js";
 import type { MessageManager } from "./messageManager.js";
 import { Container } from "../utils/container.js";
+import type { ConfigurationService } from "../services/configurationService.js";
 
 import { logger } from "../utils/globalLogger.js";
 
@@ -46,6 +48,19 @@ export class HookManager {
     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.
+   */
+  private get sessionEnv(): Record<string, string> {
+    return (
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getMergedEnv?.() ?? (process.env as Record<string, string>)
+    );
+  }
+
   /**
    * Load hook configuration from programmatic source (AgentOptions.hooks)
    */
@@ -916,7 +931,7 @@ export class HookManager {
    * Collects additionalContext and initialUserMessage from hook stdout.
    */
   async executeSessionStartHooks(
-    source: "startup" | "compact" | "clear",
+    source: SessionStartSource,
     sessionId: string,
     transcriptPath: string,
     agentType?: string,
@@ -935,7 +950,7 @@ export class HookManager {
       source,
       agentType,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };
 
@@ -989,7 +1004,7 @@ export class HookManager {
       cwd: this.workdir,
       endSource: source,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };
 
@@ -1024,7 +1039,7 @@ export class HookManager {
       cwd: this.workdir,
       compactInstructions: customInstructions,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };
 
@@ -1061,7 +1076,7 @@ export class HookManager {
       cwd: this.workdir,
       compactSummary,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };
 

package/src/managers/mcpManager.ts

@@ -9,6 +9,7 @@ import { ChatCompletionFunctionTool } from "openai/resources.js";
 import { createMcpToolPlugin, findToolServer } from "../utils/mcpUtils.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "../tools/types.js";
 import { Container } from "../utils/container.js";
+import type { ConfigurationService } from "../services/configurationService.js";
 import type {
   Logger,
   McpServerConfig,
@@ -42,7 +43,21 @@ export interface McpManagerOptions {
  */
 const WAVE_TEMPLATE_VARS = ["WAVE_PLUGIN_ROOT", "CLAUDE_PLUGIN_ROOT"];
 
-export 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 function expandEnvVars(
+  value: string,
+  env: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
+): string {
   return value.replace(/\$\{([^}]+)\}/g, (_match, expr: string) => {
     const [varName, ...rest] = expr.split(":-");
     const defaultValue = rest.join(":-");
@@ -50,45 +65,53 @@ export function expandEnvVars(value: string): string {
     if (WAVE_TEMPLATE_VARS.includes(varName)) {
       return _match; // return original ${...} string untouched
     }
-    return process.env[varName] ?? defaultValue;
+    return env[varName] ?? process.env[varName] ?? defaultValue;
   });
 }
 
 /**
  * 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 function resolveMcpConfig(config: McpConfig): McpConfig {
+export function resolveMcpConfig(
+  config: McpConfig,
+  env: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
+): McpConfig {
   const resolved: McpConfig = { mcpServers: {} };
 
   for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
     const resolvedServer: McpServerConfig = { ...serverConfig };
 
     if (resolvedServer.command) {
-      resolvedServer.command = expandEnvVars(resolvedServer.command);
+      resolvedServer.command = expandEnvVars(resolvedServer.command, env);
     }
 
     if (resolvedServer.args) {
-      resolvedServer.args = resolvedServer.args.map(expandEnvVars);
+      resolvedServer.args = resolvedServer.args.map((a) =>
+        expandEnvVars(a, env),
+      );
     }
 
     if (resolvedServer.env) {
       const resolvedEnv: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedServer.env)) {
-        resolvedEnv[key] = expandEnvVars(val);
+        resolvedEnv[key] = expandEnvVars(val, env);
       }
       resolvedServer.env = resolvedEnv;
     }
 
     if (resolvedServer.url) {
-      resolvedServer.url = expandEnvVars(resolvedServer.url);
+      resolvedServer.url = expandEnvVars(resolvedServer.url, env);
     }
 
     if (resolvedServer.headers) {
       const resolvedHeaders: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedServer.headers)) {
-        resolvedHeaders[key] = expandEnvVars(val);
+        resolvedHeaders[key] = expandEnvVars(val, env);
       }
       resolvedServer.headers = resolvedHeaders;
     }
@@ -119,6 +142,19 @@ export class McpManager {
     this.mcpServers = options.mcpServers;
   }
 
+  /**
+   * 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(): Record<string, string> {
+    return (
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getMergedEnv?.() ?? (process.env as Record<string, string>)
+    );
+  }
+
   /**
    * Initialize MCP manager with working directory and optionally auto-connect
    */
@@ -189,7 +225,7 @@ export class McpManager {
     try {
       const configContent = await fs.readFile(this.configPath, "utf-8");
       const rawConfig: McpConfig = JSON.parse(configContent);
-      const workspaceConfig = resolveMcpConfig(rawConfig);
+      const workspaceConfig = resolveMcpConfig(rawConfig, this.envSnapshot);
 
       // Extract original (pre-resolution) URLs for safe display
       const originalUrls: Record<string, string | undefined> = {};
@@ -284,28 +320,31 @@ export class McpManager {
     // Capture original URL before any resolution for safe display
     const originalUrl = config.url;
 
-    // Expand env vars from process.env (e.g. ${TAVILY_API_KEY})
+    // Expand env vars against the session snapshot (over OS env, e.g. ${TAVILY_API_KEY})
+    const env = this.envSnapshot;
     const resolvedConfig: McpServerConfig = { ...config };
     if (resolvedConfig.command) {
-      resolvedConfig.command = expandEnvVars(resolvedConfig.command);
+      resolvedConfig.command = expandEnvVars(resolvedConfig.command, env);
     }
     if (resolvedConfig.args) {
-      resolvedConfig.args = resolvedConfig.args.map(expandEnvVars);
+      resolvedConfig.args = resolvedConfig.args.map((a) =>
+        expandEnvVars(a, env),
+      );
     }
     if (resolvedConfig.env) {
       const resolvedEnv: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedConfig.env)) {
-        resolvedEnv[key] = expandEnvVars(val);
+        resolvedEnv[key] = expandEnvVars(val, env);
       }
       resolvedConfig.env = resolvedEnv;
     }
     if (resolvedConfig.url) {
-      resolvedConfig.url = expandEnvVars(resolvedConfig.url);
+      resolvedConfig.url = expandEnvVars(resolvedConfig.url, env);
     }
     if (resolvedConfig.headers) {
       const resolvedHeaders: Record<string, string> = {};
       for (const [key, val] of Object.entries(resolvedConfig.headers)) {
-        resolvedHeaders[key] = expandEnvVars(val);
+        resolvedHeaders[key] = expandEnvVars(val, env);
       }
       resolvedConfig.headers = resolvedHeaders;
     }
@@ -433,8 +472,11 @@ export class McpManager {
           );
         }
 
+        // Base env = OS env overlaid with this session's settings snapshot, so
+        // custom env vars from settings.json reach the MCP server subprocess
+        // without polluting other sessions sharing one `wave --stdio` process.
         const env: Record<string, string> = {
-          ...(process.env as Record<string, string>),
+          ...this.envSnapshot,
           ...(server.config.env || {}),
         };
 

package/src/managers/messageManager.ts

@@ -37,7 +37,6 @@ import { READ_TOOL_NAME } from "../constants/tools.js";
 import { Container } from "../utils/container.js";
 
 export interface MessageManagerCallbacks {
-  onMessagesChange?: (messages: Message[]) => void;
   onSessionIdChange?: (sessionId: string) => void;
   onLatestTotalTokensChange?: (latestTotalTokens: number) => void;
   onUsagesChange?: (usages: Usage[]) => void;
@@ -64,9 +63,17 @@ export interface MessageManagerCallbacks {
   onCompactBlockAdded?: (content: string) => void;
   onCompactionStateChange?: (isCompacting: boolean) => void;
   // Bang callback
-  onAddBangMessage?: (command: string) => void;
-  onUpdateBangMessage?: (command: string, output: string) => void;
-  onCompleteBangMessage?: (command: string, exitCode: number) => void;
+  onAddBangMessage?: (command: string, messageId: string) => void;
+  onUpdateBangMessage?: (
+    command: string,
+    output: string,
+    messageId: string,
+  ) => void;
+  onCompleteBangMessage?: (
+    command: string,
+    exitCode: number,
+    messageId: string,
+  ) => void;
   onInfoBlockAdded?: (content: string) => void;
   // Rewind callbacks
   onShowRewind?: () => void;
@@ -322,8 +329,6 @@ export class MessageManager {
       this.extractFileReadsFromMessage(messages[messages.length - 1]);
       this.extractSkillInvocationsFromMessage(messages[messages.length - 1]);
     }
-
-    this.callbacks.onMessagesChange?.([...messages]);
   }
 
   /**
@@ -339,6 +344,20 @@ export class MessageManager {
         return;
       }
 
+      // CC-aligned lazy materialization: when the session file has not been
+      // materialized yet (no saved messages) and every unsaved message is a
+      // meta message (isMeta: true, e.g. SessionStart hook context), skip
+      // persistence. Persisting meta-only sessions would create "0 tokens /
+      // No content" ghost entries in the resume list. The meta messages stay
+      // in memory and are flushed together with the first real user/assistant
+      // message (matches CC's pendingEntries buffering).
+      if (
+        this.savedMessageCount === 0 &&
+        unsavedMessages.every((m) => m.isMeta)
+      ) {
+        return;
+      }
+
       // Create session if needed (only when we have messages to save)
       if (this.savedMessageCount === 0) {
         // This is the first time saving messages, so create the session
@@ -622,7 +641,9 @@ export class MessageManager {
       command,
     });
     this.setMessages(updatedMessages);
-    this.callbacks.onAddBangMessage?.(command);
+    // The bang message is appended as the last message
+    const messageId = this.messages[this.messages.length - 1]?.id ?? "";
+    this.callbacks.onAddBangMessage?.(command, messageId);
   }
 
   public updateBangMessage(command: string, output: string): void {
@@ -632,7 +653,8 @@ export class MessageManager {
       output,
     });
     this.setMessages(updatedMessages);
-    this.callbacks.onUpdateBangMessage?.(command, output);
+    const messageId = this.findBangMessageId(command) ?? "";
+    this.callbacks.onUpdateBangMessage?.(command, output, messageId);
   }
 
   public completeBangMessage(
@@ -647,7 +669,25 @@ export class MessageManager {
       output,
     });
     this.setMessages(updatedMessages);
-    this.callbacks.onCompleteBangMessage?.(command, exitCode);
+    const messageId = this.findBangMessageId(command) ?? "";
+    this.callbacks.onCompleteBangMessage?.(command, exitCode, messageId);
+  }
+
+  /**
+   * Find the message ID of the most recent message containing a bang block
+   * for the given command. Bang callbacks do not carry a block ID, so the
+   * message is located by matching the command against bang blocks.
+   */
+  private findBangMessageId(command: string): string | undefined {
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const message = this.messages[i];
+      if (message.role !== "user") continue;
+      const hasBangBlock = message.blocks?.some(
+        (block) => block.type === "bang" && block.command === command,
+      );
+      if (hasBangBlock) return message.id;
+    }
+    return undefined;
   }
 
   public addNotificationMessage(
@@ -700,7 +740,6 @@ export class MessageManager {
   /**
    * Finalize a streaming block of the given type by setting its stage to "end".
    * Fires the corresponding incremental callback with chunk="" to signal finalization.
-   * Does NOT call onMessagesChange — the caller is responsible for that.
    * Returns true if a block was finalized.
    */
   private finalizeStreamingBlock(
@@ -807,8 +846,6 @@ export class MessageManager {
     });
 
     // Note: Subagent-specific callbacks are now handled by SubagentManager
-
-    this.callbacks.onMessagesChange?.([...this.messages]); // Still need to notify of changes
   }
 
   /**
@@ -871,8 +908,6 @@ export class MessageManager {
       accumulated: newAccumulatedReasoning,
       stage: "streaming",
     });
-
-    this.callbacks.onMessagesChange?.([...this.messages]); // Still need to notify of changes
   }
 
   /**
@@ -885,15 +920,8 @@ export class MessageManager {
     const lastMessage = this.messages[this.messages.length - 1];
     if (lastMessage.role !== "assistant") return;
 
-    const textFinalized = this.finalizeStreamingBlock(lastMessage, "text");
-    const reasoningFinalized = this.finalizeStreamingBlock(
-      lastMessage,
-      "reasoning",
-    );
-
-    if (textFinalized || reasoningFinalized) {
-      this.callbacks.onMessagesChange?.([...this.messages]);
-    }
+    this.finalizeStreamingBlock(lastMessage, "text");
+    this.finalizeStreamingBlock(lastMessage, "reasoning");
   }
 
   /**

package/src/managers/subagentManager.ts

@@ -790,6 +790,7 @@ export class SubagentManager {
   private createSubagentCallbacks(subagentId: string) {
     return {
       onUserMessageAdded: (params: UserMessageParams) => {
+        this.refreshSubagentState(subagentId);
         // Forward user message events to parent via SubagentManager callbacks
         if (this.callbacks?.onSubagentUserMessageAdded) {
           this.callbacks.onSubagentUserMessageAdded(subagentId, params);
@@ -797,6 +798,7 @@ export class SubagentManager {
       },
 
       onAssistantMessageAdded: (messageId: string) => {
+        this.refreshSubagentState(subagentId);
         // Forward assistant message events to parent via SubagentManager callbacks
         if (this.callbacks?.onSubagentAssistantMessageAdded) {
           this.callbacks.onSubagentAssistantMessageAdded(subagentId, messageId);
@@ -809,6 +811,7 @@ export class SubagentManager {
         accumulated: string;
         stage: "streaming" | "end";
       }) => {
+        this.refreshSubagentState(subagentId);
         // Forward assistant content updates to parent via SubagentManager callbacks
         if (this.callbacks?.onSubagentAssistantContentUpdated) {
           this.callbacks.onSubagentAssistantContentUpdated({
@@ -823,6 +826,7 @@ export class SubagentManager {
         accumulated: string;
         stage: "streaming" | "end";
       }) => {
+        this.refreshSubagentState(subagentId);
         // Forward assistant reasoning updates to parent via SubagentManager callbacks
         if (this.callbacks?.onSubagentAssistantReasoningUpdated) {
           this.callbacks.onSubagentAssistantReasoningUpdated({
@@ -833,6 +837,7 @@ export class SubagentManager {
       },
 
       onToolBlockUpdated: (params: ToolBlockUpdateCallbackParams) => {
+        this.refreshSubagentState(subagentId);
         const instance = this.instances.get(subagentId);
         if (instance) {
           // Log tool execution to file only when finalized
@@ -852,31 +857,6 @@ export class SubagentManager {
         }
       },
 
-      // These callbacks will be handled by the parent agent
-      onMessagesChange: (messages: Message[]) => {
-        const instance = this.instances.get(subagentId);
-        if (instance) {
-          instance.messages = messages;
-          // Compute usedTools from messages (last 2 tool blocks)
-          const toolBlocks = messages.flatMap(
-            (m) => m.blocks?.filter((b) => b.type === "tool") ?? [],
-          );
-          const last2 = toolBlocks.slice(-2);
-          instance.usedTools = last2.map((tb) => ({
-            name: tb.name ?? "",
-            parameters: tb.parameters ?? "",
-            compactParams: tb.compactParams,
-            stage: tb.stage,
-          }));
-          // Trigger the onUpdate callback if provided
-          instance.onUpdate?.();
-          // Forward subagent message changes to parent via callbacks
-          if (this.callbacks?.onSubagentMessagesChange) {
-            this.callbacks.onSubagentMessagesChange(subagentId, messages);
-          }
-        }
-      },
-
       onLatestTotalTokensChange: (tokens: number) => {
         const instance = this.instances.get(subagentId);
         if (instance) {
@@ -890,6 +870,7 @@ export class SubagentManager {
       },
 
       onErrorBlockAdded: (error: string) => {
+        this.refreshSubagentState(subagentId);
         const instance = this.instances.get(subagentId);
         if (instance?.logStream) {
           instance.logStream.write(
@@ -899,4 +880,34 @@ export class SubagentManager {
       },
     };
   }
+
+  /**
+   * Pull the latest messages from the subagent instance's MessageManager and
+   * refresh the instance's cached messages, usedTools, onUpdate and the
+   * onSubagentMessagesChange forwarding. Triggered by incremental callbacks.
+   */
+  private refreshSubagentState(subagentId: string): void {
+    const instance = this.instances.get(subagentId);
+    if (!instance) return;
+
+    const messages = instance.messageManager.getMessages();
+    instance.messages = messages;
+    // Compute usedTools from messages (last 2 tool blocks)
+    const toolBlocks = messages.flatMap(
+      (m) => m.blocks?.filter((b) => b.type === "tool") ?? [],
+    );
+    const last2 = toolBlocks.slice(-2);
+    instance.usedTools = last2.map((tb) => ({
+      name: tb.name ?? "",
+      parameters: tb.parameters ?? "",
+      compactParams: tb.compactParams,
+      stage: tb.stage,
+    }));
+    // Trigger the onUpdate callback if provided
+    instance.onUpdate?.();
+    // Forward subagent message changes to parent via callbacks
+    if (this.callbacks?.onSubagentMessagesChange) {
+      this.callbacks.onSubagentMessagesChange(subagentId, messages);
+    }
+  }
 }

package/src/managers/toolManager.ts

@@ -253,6 +253,13 @@ class ToolManager {
             "WorkflowManager",
           )
         : undefined,
+      sessionEnv: this.container.has("ConfigurationService")
+        ? this.container
+            .get<
+              import("../services/configurationService.js").ConfigurationService
+            >("ConfigurationService")
+            ?.getMergedEnv?.()
+        : undefined,
       sessionId: context.sessionId,
       toolCallId: context.toolCallId,
     };

package/src/prompts/index.ts

@@ -346,10 +346,6 @@ export function formatCompactSummary(summary: string): string {
 }
 
 export const WEB_CONTENT_SYSTEM_PROMPT = `You are a helpful assistant that extracts information from web content. The content is provided in Markdown format.`;
-export const BTW_SYSTEM_PROMPT = `You are a helpful assistant. Answer the user's side question based on the conversation history. 
-Do NOT say things like "Let me try...", "I'll now...", "Let me check...", or promise to take any action. 
-If you don't know the answer, say so - do not offer to look it up or investigate. 
-Simply answer the question with the information you have.`;
 
 export function buildSystemPrompt(
   basePrompt: string | undefined,