wave-agent-sdk 0.12.10 → 0.13.0

package/src/managers/messageManager.ts

@@ -430,6 +430,8 @@ export class MessageManager {
   }
 
   public updateToolBlock(params: AgentToolBlockUpdateParams): void {
+    // Finalize any streaming text/reasoning blocks before adding/updating a tool block
+    this.finalizeCurrentStreamingBlocks();
     const newMessages = updateToolBlockInMessage({
       messages: this.messages,
       ...params,
@@ -447,6 +449,8 @@ export class MessageManager {
     messageId: string,
     params: Omit<AgentToolBlockUpdateParams, "id">,
   ): string {
+    // Finalize any streaming text/reasoning blocks before adding a tool block
+    this.finalizeCurrentStreamingBlocks();
     const { messages: newMessages, toolBlockId } =
       addToolBlockToMessageInMessages(this.messages, messageId, params);
     this.setMessages(newMessages);
@@ -647,12 +651,14 @@ export class MessageManager {
       lastMessage.blocks[textBlockIndex] = {
         type: "text",
         content: newAccumulatedContent,
+        stage: "streaming",
       };
     } else {
       // Add new text block if none exists
       lastMessage.blocks.push({
         type: "text",
         content: newAccumulatedContent,
+        stage: "streaming",
       });
     }
 
@@ -696,12 +702,14 @@ export class MessageManager {
       lastMessage.blocks[reasoningBlockIndex] = {
         type: "reasoning",
         content: newAccumulatedReasoning,
+        stage: "streaming",
       };
     } else {
       // Add new reasoning block if none exists
       lastMessage.blocks.push({
         type: "reasoning",
         content: newAccumulatedReasoning,
+        stage: "streaming",
       });
     }
 
@@ -714,6 +722,41 @@ export class MessageManager {
     this.callbacks.onMessagesChange?.([...this.messages]); // Still need to notify of changes
   }
 
+  /**
+   * Public wrapper for finalizeCurrentStreamingBlocks.
+   * Finalizes text/reasoning blocks after streaming completes (e.g. final response with no tools).
+   */
+  public finalizeStreamingBlocks(): void {
+    this.finalizeCurrentStreamingBlocks();
+  }
+
+  /**
+   * Finalize streaming text/reasoning blocks by setting their stage to "end".
+   * Called when a new block (e.g. tool) is appended during streaming.
+   */
+  private finalizeCurrentStreamingBlocks(): void {
+    if (this.messages.length === 0) return;
+    const lastMessage = this.messages[this.messages.length - 1];
+    if (lastMessage.role !== "assistant") return;
+
+    const newBlocks = lastMessage.blocks.map((block) => {
+      if (
+        (block.type === "text" || block.type === "reasoning") &&
+        block.stage === "streaming"
+      ) {
+        return { ...block, stage: "end" as const };
+      }
+      return block;
+    });
+
+    // Only update if something changed
+    const changed = newBlocks.some((b, i) => b !== lastMessage.blocks[i]);
+    if (changed) {
+      lastMessage.blocks = newBlocks;
+      this.callbacks.onMessagesChange?.([...this.messages]);
+    }
+  }
+
   /**
    * Remove the last user message from the conversation
    * Used for hook error handling when the user prompt needs to be erased

package/src/managers/slashCommandManager.ts

@@ -179,7 +179,8 @@ export class SlashCommandManager {
             if (skill.context === "fork") {
               // Forked skill execution: add user message with text + tool block
               const messageId = this.messageManager.addUserMessage({
-                content: `/${skill.name} ${args || ""}`,
+                content: `/${skill.name}${args ? ` ${args}` : ""}`,
+                customCommandContent: prepared.content,
               });
 
               const toolBlockId = this.messageManager.addToolBlockToMessage(
@@ -285,7 +286,8 @@ export class SlashCommandManager {
 
             // Add user message with the processed content
             this.messageManager.addUserMessage({
-              content: result.content,
+              content: `/${skill.name}${args ? ` ${args}` : ""}`,
+              customCommandContent: result.content,
             });
 
             // Trigger AI response
@@ -489,20 +491,25 @@ export class SlashCommandManager {
       // Parse bash commands from the content
       const { commands, processedContent } = parseBashCommands(content);
 
-      // Execute bash commands if any
-      let finalContent = processedContent;
+      // Add user message immediately so text block shows before bash execution
+      const messageId = this.messageManager.addUserMessage({
+        content: `/${commandName}`,
+        customCommandContent: processedContent,
+      });
+
+      // Execute bash commands and update the message if any exist
       if (commands.length > 0) {
         const bashResults = await executeBashCommands(commands, this.workdir);
-        finalContent = replaceBashCommandsWithOutput(
+        const finalContent = replaceBashCommandsWithOutput(
           processedContent,
           bashResults,
         );
-      }
 
-      // Add user message with the processed content
-      this.messageManager.addUserMessage({
-        content: finalContent,
-      });
+        // Update the user message with the bash-processed content
+        this.messageManager.updateUserMessage(messageId, {
+          customCommandContent: finalContent,
+        });
+      }
 
       // Execute the AI conversation with custom configuration
       await this.aiManager.sendAIMessage({

package/src/managers/subagentManager.ts

@@ -343,7 +343,8 @@ export class SubagentManager {
           outputPath: logPath,
           subagentId: instance.subagentId,
           onStop: () => {
-            instance.logStream?.end();
+            instance.logStream?.destroy();
+            instance.logStream = undefined;
             instance.aiManager.abortAIMessage();
             this.cleanupInstance(instance.subagentId);
           },
@@ -421,7 +422,8 @@ export class SubagentManager {
       outputPath: logPath,
       subagentId: instance.subagentId,
       onStop: () => {
-        instance.logStream?.end();
+        instance.logStream?.destroy();
+        instance.logStream = undefined;
         instance.aiManager.abortAIMessage();
         this.cleanupInstance(instance.subagentId);
       },

package/src/managers/toolManager.ts

@@ -4,6 +4,7 @@ import { taskStopTool } from "../tools/taskStopTool.js";
 import { editTool } from "../tools/editTool.js";
 import { writeTool } from "../tools/writeTool.js";
 import { exitPlanModeTool } from "../tools/exitPlanMode.js";
+import { enterPlanModeTool } from "../tools/enterPlanMode.js";
 import { askUserQuestionTool } from "../tools/askUserQuestion.js";
 import { cronCreateTool } from "../tools/cronCreateTool.js";
 import { cronDeleteTool } from "../tools/cronDeleteTool.js";
@@ -106,6 +107,7 @@ class ToolManager {
       editTool,
       writeTool,
       exitPlanModeTool,
+      enterPlanModeTool,
       askUserQuestionTool,
       globTool,
       grepTool,
@@ -296,13 +298,23 @@ class ToolManager {
           return false;
         }
         if (effectivePermissionMode === "bypassPermissions") {
-          if (tool.name === "ExitPlanMode" || tool.name === "AskUserQuestion") {
+          if (
+            tool.name === "ExitPlanMode" ||
+            tool.name === "AskUserQuestion" ||
+            tool.name === "EnterPlanMode"
+          ) {
             return false;
           }
         }
         if (tool.name === "ExitPlanMode") {
           return effectivePermissionMode === "plan";
         }
+        if (tool.name === "EnterPlanMode") {
+          return (
+            effectivePermissionMode !== "plan" &&
+            effectivePermissionMode !== "bypassPermissions"
+          );
+        }
         return true;
       })
       .map((tool) => {

package/src/services/MarketplaceService.ts

@@ -69,7 +69,28 @@ export class MarketplaceService {
   }
 
   /**
-   * Acquires a file-based lock and executes the provided function.
+   * Check if a lock file is stale by reading its PID and checking if the process is alive.
+   * Returns true if the lock is stale and safe to remove.
+   */
+  private async isStaleLock(): Promise<boolean> {
+    try {
+      const content = await fs.readFile(this.lockPath, "utf-8");
+      const pid = parseInt(content.trim(), 10);
+      if (isNaN(pid)) return true;
+      // Check if the process is still running
+      try {
+        process.kill(pid, 0);
+        return false; // Process exists, lock is valid
+      } catch {
+        return true; // Process doesn't exist, lock is stale
+      }
+    } catch {
+      return true; // Can't read lock file, assume stale
+    }
+  }
+
+  /**
+   * Acquires a file-based lock (with PID tracking for stale lock detection) and executes the provided function.
    * Supports re-entrancy within the same process.
    */
   private async withLock<T>(fn: () => Promise<T>): Promise<T> {
@@ -92,6 +113,14 @@ export class MarketplaceService {
           "code" in error &&
           error.code === "EEXIST"
         ) {
+          // Check for stale lock every 60 retries (every ~6 seconds)
+          if (i > 0 && i % 60 === 0) {
+            const stale = await this.isStaleLock();
+            if (stale) {
+              await fs.unlink(this.lockPath).catch(() => {});
+              continue;
+            }
+          }
           await new Promise((resolve) => setTimeout(resolve, retryDelay));
           continue;
         }
@@ -105,6 +134,9 @@ export class MarketplaceService {
       );
     }
 
+    // Write PID into the lock file for stale lock detection
+    await fs.writeFile(this.lockPath, String(process.pid), "utf-8");
+
     MarketplaceService.isLockedInProcess = true;
     try {
       return await fn();

package/src/services/configurationService.ts

@@ -8,6 +8,7 @@
 import { readFileSync, existsSync, promises as fs } from "fs";
 import * as path from "path";
 import { isValidHookEvent } from "../types/hooks.js";
+import { logger } from "../utils/globalLogger.js";
 import type {
   ConfigurationLoadResult,
   ValidationResult,
@@ -50,8 +51,8 @@ import { parseCustomHeaders } from "../utils/stringUtils.js";
  */
 export class ConfigurationService {
   private currentConfiguration: WaveConfiguration | null = null;
-  private env: Record<string, string> = {};
   private options: AgentOptions = {};
+  private _configuredEnvKeys = new Set<string>();
 
   /**
    * Set agent options for configuration resolution
@@ -356,14 +357,13 @@ export class ConfigurationService {
    * This replaces direct process.env modification
    */
   setEnvironmentVars(env: Record<string, string>): void {
-    this.env = { ...env };
-  }
-
-  /**
-   * Get current environment variables
-   */
-  getEnvironmentVars(): Record<string, string> {
-    return { ...this.env };
+    for (const [key, value] of Object.entries(env)) {
+      if (process.env[key] !== undefined && !this._configuredEnvKeys.has(key)) {
+        logger.warn(`Overriding environment variable: ${key}`);
+      }
+      process.env[key] = value;
+      this._configuredEnvKeys.add(key);
+    }
   }
 
   // =============================================================================
@@ -396,7 +396,7 @@ export class ConfigurationService {
     } else if (this.options.apiKey !== undefined) {
       resolvedApiKey = this.options.apiKey;
     } else {
-      resolvedApiKey = this.env.WAVE_API_KEY;
+      resolvedApiKey = process.env.WAVE_API_KEY;
     }
 
     // Resolve base URL: override > options > env (settings.json) > process.env
@@ -407,7 +407,7 @@ export class ConfigurationService {
     } else if (this.options.baseURL !== undefined) {
       resolvedBaseURL = this.options.baseURL;
     } else {
-      resolvedBaseURL = this.env.WAVE_BASE_URL || "";
+      resolvedBaseURL = process.env.WAVE_BASE_URL || "";
     }
 
     // Fallback to process.env if still not resolved (for dynamic updates in tests)
@@ -422,7 +422,7 @@ export class ConfigurationService {
       throw new ConfigurationError(CONFIG_ERRORS.MISSING_BASE_URL, "baseURL", {
         constructor: baseURL,
         environment: process.env.WAVE_BASE_URL,
-        settings: this.env.WAVE_BASE_URL,
+        settings: process.env.WAVE_BASE_URL,
       });
     }
 
@@ -436,7 +436,7 @@ export class ConfigurationService {
 
     // Resolve custom headers from environment: env (settings.json) > process.env
     const envCustomHeaders =
-      this.env.WAVE_CUSTOM_HEADERS || process.env.WAVE_CUSTOM_HEADERS || "";
+      process.env.WAVE_CUSTOM_HEADERS || process.env.WAVE_CUSTOM_HEADERS || "";
     const parsedEnvHeaders = parseCustomHeaders(envCustomHeaders);
 
     // Merge headers: env headers < options < override
@@ -475,14 +475,14 @@ export class ConfigurationService {
     const resolvedAgentModel =
       model ||
       this.options.model ||
-      this.env.WAVE_MODEL ||
+      process.env.WAVE_MODEL ||
       process.env.WAVE_MODEL;
 
     // Resolve fast model: override > options > env (settings.json) > process.env
     const resolvedFastModel =
       fastModel ||
       this.options.fastModel ||
-      this.env.WAVE_FAST_MODEL ||
+      process.env.WAVE_FAST_MODEL ||
       process.env.WAVE_FAST_MODEL;
 
     // Validate required fields
@@ -490,7 +490,6 @@ export class ConfigurationService {
       throw new ConfigurationError(CONFIG_ERRORS.MISSING_MODEL, "model", {
         constructor: model,
         environment: process.env.WAVE_MODEL,
-        settings: this.env.WAVE_MODEL,
       });
     }
 
@@ -501,7 +500,6 @@ export class ConfigurationService {
         {
           constructor: fastModel,
           environment: process.env.WAVE_FAST_MODEL,
-          settings: this.env.WAVE_FAST_MODEL,
         },
       );
     }
@@ -549,7 +547,7 @@ export class ConfigurationService {
 
     // Try env (settings.json) first, then process.env
     const envMaxInputTokens =
-      this.env.WAVE_MAX_INPUT_TOKENS || process.env.WAVE_MAX_INPUT_TOKENS;
+      process.env.WAVE_MAX_INPUT_TOKENS || process.env.WAVE_MAX_INPUT_TOKENS;
     if (envMaxInputTokens) {
       const parsed = parseInt(envMaxInputTokens, 10);
       if (!isNaN(parsed)) {
@@ -599,7 +597,8 @@ export class ConfigurationService {
 
     // 2. WAVE_DISABLE_AUTO_MEMORY environment variable
     const disableAutoMemory =
-      this.env.WAVE_DISABLE_AUTO_MEMORY || process.env.WAVE_DISABLE_AUTO_MEMORY;
+      process.env.WAVE_DISABLE_AUTO_MEMORY ||
+      process.env.WAVE_DISABLE_AUTO_MEMORY;
     if (disableAutoMemory === "1" || disableAutoMemory === "true") {
       return false;
     }
@@ -621,7 +620,7 @@ export class ConfigurationService {
 
     // 2. WAVE_AUTO_MEMORY_FREQUENCY environment variable
     const envFrequency =
-      this.env.WAVE_AUTO_MEMORY_FREQUENCY ||
+      process.env.WAVE_AUTO_MEMORY_FREQUENCY ||
       process.env.WAVE_AUTO_MEMORY_FREQUENCY;
     if (envFrequency) {
       const parsed = parseInt(envFrequency, 10);
@@ -653,7 +652,7 @@ export class ConfigurationService {
 
     // Try env (settings.json) first, then process.env
     const envMaxOutputTokens =
-      this.env.WAVE_MAX_OUTPUT_TOKENS || process.env.WAVE_MAX_OUTPUT_TOKENS;
+      process.env.WAVE_MAX_OUTPUT_TOKENS || process.env.WAVE_MAX_OUTPUT_TOKENS;
     if (envMaxOutputTokens) {
       const parsed = parseInt(envMaxOutputTokens, 10);
       if (!isNaN(parsed) && parsed > 0) {
@@ -680,7 +679,7 @@ export class ConfigurationService {
 
     // Add current model from options or environment
     const currentModel =
-      this.options.model || this.env.WAVE_MODEL || process.env.WAVE_MODEL;
+      this.options.model || process.env.WAVE_MODEL || process.env.WAVE_MODEL;
     if (currentModel) {
       models.add(currentModel);
     }

package/src/services/initializationService.ts

@@ -192,7 +192,9 @@ export class InitializationService {
           transcriptPath: messageManager.getTranscriptPath(),
           cwd: workdir,
           worktreeName: agentOptions.worktreeName,
-          env: configurationService.getEnvironmentVars(),
+          env: Object.fromEntries(
+            Object.entries(process.env).filter((e) => e[1] !== undefined),
+          ) as Record<string, string>,
         });
 
         // Process hook results

package/src/services/interactionService.ts

@@ -33,7 +33,6 @@ export class InteractionService {
       slashCommandManager,
       hookManager,
       workdir,
-      configurationService,
       logger,
       aiManager,
     } = context;
@@ -83,7 +82,9 @@ export class InteractionService {
               transcriptPath: messageManager.getTranscriptPath(),
               cwd: workdir,
               userPrompt: content,
-              env: configurationService.getEnvironmentVars(), // Include configuration environment variables
+              env: Object.fromEntries(
+                Object.entries(process.env).filter((e) => e[1] !== undefined),
+              ) as Record<string, string>, // Include environment variables
             },
           );
 

package/src/tools/enterPlanMode.ts

@@ -0,0 +1,107 @@
+import { logger } from "../utils/globalLogger.js";
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import { ENTER_PLAN_MODE_TOOL_NAME } from "../constants/tools.js";
+import { OPERATION_CANCELLED_BY_USER } from "../types/permissions.js";
+
+/**
+ * Enter Plan Mode Tool Plugin
+ */
+export const enterPlanModeTool: ToolPlugin = {
+  name: ENTER_PLAN_MODE_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: ENTER_PLAN_MODE_TOOL_NAME,
+      description:
+        "Request to enter plan mode for complex tasks requiring user approval before coding",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        additionalProperties: false,
+      },
+    },
+  },
+  prompt:
+    () => `Use this tool to proactively request entering plan mode when a task is non-trivial and benefits from planning before implementation.
+
+## When to Use This Tool
+- Multi-file changes or refactoring that requires architectural decisions
+- New features with multiple implementation steps or design trade-offs
+- Tasks where you want user approval on approach before writing code
+- Complex bug fixes that span multiple components
+
+## When NOT to Use This Tool
+- Simple fixes (typos, small logic changes in a single file)
+- Research tasks (searching files, reading code, gathering information)
+- Tasks where the implementation approach is straightforward and unambiguous
+- When already in plan mode
+
+## Examples
+
+1. Task: "Refactor the authentication system to use OAuth2" - Use EnterPlanMode to propose an approach before implementation.
+2. Task: "Add input validation to the login form" - Do NOT use EnterPlanMode, just implement it.
+3. Task: "Migrate the database schema to support multi-tenancy" - Use EnterPlanMode to plan the migration steps.
+4. Task: "Fix the off-by-one error in the pagination logic" - Do NOT use EnterPlanMode, just fix the bug.
+`,
+  execute: async (
+    _args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> => {
+    try {
+      if (!context.permissionManager) {
+        return {
+          success: false,
+          content: "",
+          error: "Permission manager is not available",
+        };
+      }
+
+      const permissionContext = context.permissionManager.createContext(
+        ENTER_PLAN_MODE_TOOL_NAME,
+        context.permissionMode || "default",
+        context.canUseToolCallback,
+        {},
+        context.toolCallId,
+      );
+
+      // No "allow always" option for plan mode transitions (matching Claude Code behavior)
+      permissionContext.hidePersistentOption = true;
+
+      const permissionResult =
+        await context.permissionManager.checkPermission(permissionContext);
+
+      if (permissionResult.behavior === "deny") {
+        if (permissionResult.message === OPERATION_CANCELLED_BY_USER) {
+          return {
+            success: false,
+            content: OPERATION_CANCELLED_BY_USER,
+          };
+        }
+        return {
+          success: false,
+          content: `User declined to enter plan mode. Proceed in current mode.`,
+          error: permissionResult.message
+            ? undefined
+            : "Operation declined by user",
+        };
+      }
+
+      return {
+        success: true,
+        content:
+          "Plan mode entered successfully. Please write your plan to the plan file and use ExitPlanMode when ready for approval.",
+        shortResult: "Plan mode entered",
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.error(`EnterPlanMode tool error: ${errorMessage}`);
+      return {
+        success: false,
+        content: "",
+        error: errorMessage,
+      };
+    }
+  },
+};

package/src/types/messaging.ts

@@ -32,7 +32,9 @@ export type MessageBlock =
 export interface TextBlock {
   type: "text";
   content: string;
+  customCommandContent?: string;
   source?: MessageSource;
+  stage?: "streaming" | "end";
 }
 
 export interface ErrorBlock {
@@ -77,7 +79,7 @@ export interface BangBlock {
   type: "bang";
   command: string;
   output: string;
-  isRunning: boolean;
+  stage: "running" | "end";
   exitCode: number | null;
 }
 
@@ -90,6 +92,7 @@ export interface CompressBlock {
 export interface ReasoningBlock {
   type: "reasoning";
   content: string;
+  stage?: "streaming" | "end";
 }
 
 export interface FileHistoryBlock {

package/src/types/permissions.ts

@@ -12,6 +12,7 @@ import {
   EDIT_TOOL_NAME,
   BASH_TOOL_NAME,
   WRITE_TOOL_NAME,
+  ENTER_PLAN_MODE_TOOL_NAME,
   EXIT_PLAN_MODE_TOOL_NAME,
   ASK_USER_QUESTION_TOOL_NAME,
 } from "../constants/tools.js";
@@ -68,6 +69,7 @@ export const RESTRICTED_TOOLS = [
   EDIT_TOOL_NAME,
   BASH_TOOL_NAME,
   WRITE_TOOL_NAME,
+  ENTER_PLAN_MODE_TOOL_NAME,
   EXIT_PLAN_MODE_TOOL_NAME,
   ASK_USER_QUESTION_TOOL_NAME,
 ] as const;

package/src/utils/containerSetup.ts

@@ -111,9 +111,7 @@ export function setupAgentContainer(
   container.register("MessageManager", messageManager);
 
   const resolvedTaskListId =
-    configurationService.getEnvironmentVars().WAVE_TASK_LIST_ID ||
-    process.env.WAVE_TASK_LIST_ID ||
-    messageManager.getRootSessionId();
+    process.env.WAVE_TASK_LIST_ID || messageManager.getRootSessionId();
 
   const taskManager = new TaskManager(container, resolvedTaskListId);
   container.register("TaskManager", taskManager);
@@ -189,7 +187,9 @@ export function setupAgentContainer(
             cwd: workdir,
             toolName: context.toolName,
             toolInput: context.toolInput,
-            env: configurationService.getEnvironmentVars(),
+            env: Object.fromEntries(
+              Object.entries(process.env).filter((e) => e[1] !== undefined),
+            ) as Record<string, string>,
           });
 
           if (results.length > 0) {

package/src/utils/convertMessagesForAPI.ts

@@ -191,9 +191,10 @@ export function convertMessagesForAPI(
           block.content &&
           block.content.trim().length > 0
         ) {
+          const textForApi = block.customCommandContent ?? block.content;
           contentParts.push({
             type: "text",
-            text: block.content,
+            text: textForApi,
           });
         }