wave-agent-sdk 0.13.2 → 0.13.3

package/dist/utils/pathEncoder.js

@@ -16,7 +16,6 @@ export class PathEncoder {
             pathSeparatorReplacement: options.pathSeparatorReplacement ?? "-",
             spaceReplacement: options.spaceReplacement ?? "_",
             invalidCharReplacement: options.invalidCharReplacement ?? "_",
-            preserveCase: options.preserveCase ?? false,
             hashLength: options.hashLength ?? 8,
         };
         this.constraints = this.getFilesystemConstraints();
@@ -50,10 +49,7 @@ export class PathEncoder {
             .join("");
         const invalidChars = new RegExp(`[${escapedChars}]`, "g");
         encoded = encoded.replace(invalidChars, this.options.invalidCharReplacement);
-        // Convert to lowercase unless preserveCase is true
-        if (!this.options.preserveCase) {
-            encoded = encoded.toLowerCase();
-        }
+        // Case is preserved
         // Handle length limit with hash
         if (encoded.length > this.options.maxLength) {
             const hash = this.generateHash(pathToEncode, this.options.hashLength);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",

package/src/agent.ts

@@ -3,11 +3,13 @@ import { MessageManager } from "./managers/messageManager.js";
 import { AIManager } from "./managers/aiManager.js";
 import { ToolManager } from "./managers/toolManager.js";
 import { SubagentManager } from "./managers/subagentManager.js";
+import { ForkedAgentManager } from "./managers/forkedAgentManager.js";
 import { McpManager } from "./managers/mcpManager.js";
 import { LspManager } from "./managers/lspManager.js";
 import { BangManager } from "./managers/bangManager.js";
 import { CronManager } from "./managers/cronManager.js";
 import { BackgroundTaskManager } from "./managers/backgroundTaskManager.js";
+import { NotificationQueue } from "./managers/notificationQueue.js";
 import { SlashCommandManager } from "./managers/slashCommandManager.js";
 import { PluginManager } from "./managers/pluginManager.js";
 import { HookManager } from "./managers/hookManager.js";
@@ -37,6 +39,7 @@ import { SkillManager } from "./managers/skillManager.js";
 import { TaskManager } from "./services/taskManager.js";
 import { btw } from "./services/aiService.js";
 import { convertMessagesForAPI } from "./utils/convertMessagesForAPI.js";
+import { parseTaskNotificationXml } from "./utils/notificationXml.js";
 import { InitializationService } from "./services/initializationService.js";
 import { InteractionService } from "./services/interactionService.js";
 import { ConfigurationService } from "./services/configurationService.js";
@@ -56,12 +59,14 @@ export class Agent {
   private permissionManager: PermissionManager; // Add permission manager instance
   private planManager: PlanManager; // Add plan manager instance
   private subagentManager: SubagentManager; // Add subagent manager instance
+  private forkedAgentManager: ForkedAgentManager; // Add forked agent manager instance
   private slashCommandManager: SlashCommandManager; // Add slash command manager instance
   private pluginManager: PluginManager; // Add plugin manager instance
   private skillManager: SkillManager; // Add skill manager instance
   private cronManager: CronManager; // Add cron manager instance
   private hookManager: HookManager; // Add hooks manager instance
   private reversionManager: ReversionManager;
+  private notificationQueue: NotificationQueue; // Add notification queue instance
   private memoryRuleManager: MemoryRuleManager; // Add memory rule manager instance
   private liveConfigManager: LiveConfigManager; // Add live configuration manager
   private taskManager: TaskManager;
@@ -185,11 +190,23 @@ export class Agent {
     this.toolManager = this.container.get("ToolManager")!;
     this.liveConfigManager = this.container.get("LiveConfigManager")!;
     this.subagentManager = this.container.get("SubagentManager")!;
+    this.forkedAgentManager = this.container.get("ForkedAgentManager")!;
     this.aiManager = this.container.get("AIManager")!;
     this.slashCommandManager = this.container.get("SlashCommandManager")!;
     this.pluginManager = this.container.get("PluginManager")!;
     this.bangManager = this.container.get("BangManager")!;
     this.cronManager = this.container.get("CronManager")!;
+    this.notificationQueue = this.container.get("NotificationQueue")!;
+
+    // Wire up notification queue to trigger AI when notifications arrive while idle
+    this.notificationQueue.onNotificationsEnqueued = () => {
+      // If the AI is NOT loading (idle), trigger a new AI cycle to process notifications
+      if (!this.aiManager.isLoading) {
+        this.processPendingNotifications().catch((error) => {
+          this.logger?.error("Failed to process pending notifications:", error);
+        });
+      }
+    };
 
     // Set initial permission mode if provided
     if (options.permissionMode) {
@@ -425,6 +442,31 @@ export class Agent {
     this.aiManager.abortAIMessage();
   }
 
+  /**
+   * Process pending background task notifications by injecting them as user messages
+   * and triggering a new AI response cycle.
+   */
+  private async processPendingNotifications(): Promise<void> {
+    const notifications = this.notificationQueue.dequeueAll();
+    if (notifications.length === 0) return;
+
+    for (const notification of notifications) {
+      const block = parseTaskNotificationXml(notification);
+      if (block) {
+        this.messageManager.addNotificationMessage({
+          taskId: block.taskId,
+          taskType: block.taskType,
+          status: block.status,
+          summary: block.summary,
+          outputFile: block.outputFile,
+        });
+      }
+    }
+
+    // Trigger AI to process the notifications
+    await this.aiManager.sendAIMessage({ recursionDepth: 0 });
+  }
+
   /** Execute bash command (bang command) */
   public async bang(command: string): Promise<void> {
     await this.bangManager?.executeCommand(command);
@@ -491,6 +533,8 @@ export class Agent {
     }
     // Cleanup subagent manager
     this.subagentManager.cleanup();
+    // Cleanup forked agent manager
+    this.forkedAgentManager.cleanup();
     // Cleanup skill manager
     await this.skillManager.destroy();
     // Cleanup live configuration reload

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "./utils/fileSearch.js";
 export * from "./utils/globalLogger.js";
 export * from "./utils/mcpUtils.js";
 export * from "./utils/messageOperations.js";
+export * from "./utils/notificationXml.js";
 export * from "./utils/path.js";
 export * from "./utils/promptHistory.js";
 export * from "./utils/stringUtils.js";

package/src/managers/aiManager.ts

@@ -1,6 +1,7 @@
 import { type CallAgentOptions } from "../services/aiService.js";
 import * as aiService from "../services/aiService.js";
 import { convertMessagesForAPI } from "../utils/convertMessagesForAPI.js";
+import { parseTaskNotificationXml } from "../utils/notificationXml.js";
 import { calculateComprehensiveTotalTokens } from "../utils/tokenCalculation.js";
 import * as fs from "node:fs/promises";
 import type {
@@ -14,6 +15,7 @@ import type { ToolManager } from "./toolManager.js";
 import type { ToolContext, ToolResult } from "../tools/types.js";
 import type { MessageManager } from "./messageManager.js";
 import type { BackgroundTaskManager } from "./backgroundTaskManager.js";
+import type { NotificationQueue } from "./notificationQueue.js";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
 import type { HookManager } from "./hookManager.js";
 import type { ExtendedHookExecutionContext } from "../types/hooks.js";
@@ -178,6 +180,11 @@ export class AIManager {
 
   public setIsLoading(isLoading: boolean): void {
     this.isLoading = isLoading;
+    const options =
+      this.container.get<import("../types/agent.js").AgentOptions>(
+        "AgentOptions",
+      );
+    options?.callbacks?.onLoadingChange?.(isLoading);
   }
 
   public abortAIMessage(): void {
@@ -340,6 +347,14 @@ export class AIManager {
       return;
     }
 
+    // Set loading state early for the initial call, before any async work
+    if (recursionDepth === 0) {
+      this.setIsLoading(true);
+      if (allowedRules && allowedRules.length > 0) {
+        this.permissionManager?.addTemporaryRules(allowedRules);
+      }
+    }
+
     // Scan for file mentions in the last user message
     if (recursionDepth === 0) {
       const messages = this.messageManager.getMessages();
@@ -380,14 +395,6 @@ export class AIManager {
       toolAbortController = this.toolAbortController!;
     }
 
-    // Only set loading state for the initial call
-    if (recursionDepth === 0) {
-      this.setIsLoading(true);
-      if (allowedRules && allowedRules.length > 0) {
-        this.permissionManager?.addTemporaryRules(allowedRules);
-      }
-    }
-
     // Get recent message history
     const recentMessages = convertMessagesForAPI(
       this.messageManager.getMessages(),
@@ -899,44 +906,72 @@ export class AIManager {
         // Set loading to false first
         this.setIsLoading(false);
 
-        // Clear temporary rules
-        this.permissionManager?.clearTemporaryRules();
-
-        // Clear abort controllers
-        this.abortController = null;
-        this.toolAbortController = null;
-
-        // Execute Stop/SubagentStop hooks only if the operation was not aborted
-        const isCurrentlyAborted =
-          abortController.signal.aborted || toolAbortController.signal.aborted;
-
-        if (!isCurrentlyAborted) {
-          // Record committed snapshots to message history for the final turn
-          if (this.reversionManager) {
-            const snapshots =
-              this.reversionManager.getAndClearCommittedSnapshots();
-            if (snapshots.length > 0) {
-              this.messageManager.addFileHistoryBlock(snapshots);
+        // Inject pending notifications from background tasks
+        const notificationQueue = this.container.has("NotificationQueue")
+          ? this.container.get<NotificationQueue>("NotificationQueue")
+          : undefined;
+        if (notificationQueue && notificationQueue.hasPending()) {
+          const notifications = notificationQueue.dequeueAll();
+          for (const notification of notifications) {
+            const block = parseTaskNotificationXml(notification);
+            if (block) {
+              this.messageManager.addNotificationMessage({
+                taskId: block.taskId,
+                taskType: block.taskType,
+                status: block.status,
+                summary: block.summary,
+                outputFile: block.outputFile,
+              });
             }
           }
+          // Recursively process the notifications
+          await this.sendAIMessage({
+            recursionDepth: 0,
+            model,
+            allowedRules,
+            maxTokens,
+          });
+        } else {
+          // Clear temporary rules
+          this.permissionManager?.clearTemporaryRules();
+
+          // Clear abort controllers
+          this.abortController = null;
+          this.toolAbortController = null;
+
+          // Execute Stop/SubagentStop hooks only if the operation was not aborted
+          const isCurrentlyAborted =
+            abortController.signal.aborted ||
+            toolAbortController.signal.aborted;
+
+          if (!isCurrentlyAborted) {
+            // Record committed snapshots to message history for the final turn
+            if (this.reversionManager) {
+              const snapshots =
+                this.reversionManager.getAndClearCommittedSnapshots();
+              if (snapshots.length > 0) {
+                this.messageManager.addFileHistoryBlock(snapshots);
+              }
+            }
 
-          const shouldContinue = await this.executeStopHooks();
+            const shouldContinue = await this.executeStopHooks();
 
-          // If Stop/SubagentStop hooks indicate we should continue (due to blocking errors),
-          // restart the AI conversation cycle
-          if (shouldContinue) {
-            logger?.info(
-              `${this.subagentType ? "SubagentStop" : "Stop"} hooks indicate issues need fixing, continuing conversation...`,
-            );
+            // If Stop/SubagentStop hooks indicate we should continue (due to blocking errors),
+            // restart the AI conversation cycle
+            if (shouldContinue) {
+              logger?.info(
+                `${this.subagentType ? "SubagentStop" : "Stop"} hooks indicate issues need fixing, continuing conversation...`,
+              );
 
-            // Restart the conversation to let AI fix the issues
-            // Use recursionDepth = 0 to set loading false again for continuation
-            await this.sendAIMessage({
-              recursionDepth: 0,
-              model,
-              allowedRules,
-              maxTokens,
-            });
+              // Restart the conversation to let AI fix the issues
+              // Use recursionDepth = 0 to set loading false again for continuation
+              await this.sendAIMessage({
+                recursionDepth: 0,
+                model,
+                allowedRules,
+                maxTokens,
+              });
+            }
           }
         }
       }

package/src/managers/backgroundTaskManager.ts

@@ -2,10 +2,15 @@ import { spawn, type ChildProcess } from "child_process";
 import * as os from "os";
 import * as fs from "fs";
 import * as path from "path";
-import { BackgroundTask, BackgroundShell } from "../types/processes.js";
+import {
+  BackgroundTask,
+  BackgroundShell,
+  BackgroundSubagent,
+} from "../types/processes.js";
 import { stripAnsiColors } from "../utils/stringUtils.js";
 import { logger } from "../utils/globalLogger.js";
 import { Container } from "../utils/container.js";
+import { NotificationQueue } from "./notificationQueue.js";
 
 export interface BackgroundTaskManagerCallbacks {
   onBackgroundTasksChange?: (tasks: BackgroundTask[]) => void;
@@ -30,6 +35,10 @@ export class BackgroundTaskManager {
     this.workdir = options.workdir;
   }
 
+  private get notificationQueue(): NotificationQueue {
+    return this.container.get<NotificationQueue>("NotificationQueue")!;
+  }
+
   private notifyTasksChange(): void {
     this.callbacks.onBackgroundTasksChange?.(Array.from(this.tasks.values()));
   }
@@ -153,6 +162,18 @@ export class BackgroundTaskManager {
       shell.endTime = Date.now();
       shell.runtime = shell.endTime - startTime;
       this.notifyTasksChange();
+
+      // Enqueue completion notification
+      const notificationQueue = this.container.has("NotificationQueue")
+        ? this.container.get<NotificationQueue>("NotificationQueue")
+        : undefined;
+      if (notificationQueue) {
+        const statusStr = shell.status;
+        const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
+        notificationQueue.enqueue(
+          `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
+        );
+      }
     };
 
     const onError = (error: Error) => {
@@ -170,6 +191,17 @@ export class BackgroundTaskManager {
       shell.endTime = Date.now();
       shell.runtime = shell.endTime - startTime;
       this.notifyTasksChange();
+
+      // Enqueue error notification
+      const notificationQueue = this.container.has("NotificationQueue")
+        ? this.container.get<NotificationQueue>("NotificationQueue")
+        : undefined;
+      if (notificationQueue) {
+        const summary = `Command "${command}" failed with error: ${stripAnsiColors(error.message)}`;
+        notificationQueue.enqueue(
+          `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+        );
+      }
     };
 
     child.stdout?.on("data", onStdout);
@@ -278,6 +310,18 @@ export class BackgroundTaskManager {
       shell.endTime = Date.now();
       shell.runtime = shell.endTime - startTime;
       this.notifyTasksChange();
+
+      // Enqueue completion notification
+      const notificationQueue = this.container.has("NotificationQueue")
+        ? this.container.get<NotificationQueue>("NotificationQueue")
+        : undefined;
+      if (notificationQueue) {
+        const statusStr = shell.status;
+        const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
+        notificationQueue.enqueue(
+          `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
+        );
+      }
     });
 
     child.on("error", (error) => {
@@ -292,6 +336,17 @@ export class BackgroundTaskManager {
       shell.endTime = Date.now();
       shell.runtime = shell.endTime - startTime;
       this.notifyTasksChange();
+
+      // Enqueue error notification
+      const notificationQueue = this.container.has("NotificationQueue")
+        ? this.container.get<NotificationQueue>("NotificationQueue")
+        : undefined;
+      if (notificationQueue) {
+        const summary = `Command "${command}" failed with error: ${stripAnsiColors(error.message)}`;
+        notificationQueue.enqueue(
+          `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+        );
+      }
     });
 
     return id;
@@ -371,6 +426,22 @@ export class BackgroundTaskManager {
     task.endTime = Date.now();
     task.runtime = task.endTime - task.startTime;
     this.notifyTasksChange();
+
+    // Enqueue killed notification
+    const notificationQueue = this.container.has("NotificationQueue")
+      ? this.container.get<NotificationQueue>("NotificationQueue")
+      : undefined;
+    if (notificationQueue) {
+      const description = (task as BackgroundSubagent).description || "";
+      const command = (task as BackgroundShell).command || "";
+      const summary =
+        task.type === "subagent"
+          ? `Agent task "${description}" was stopped`
+          : `Command "${command}" was stopped`;
+      notificationQueue.enqueue(
+        `<task-notification>\n<task-id>${id}</task-id>\n<task-type>${task.type}</task-type>\n<status>killed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+      );
+    }
     return true;
   }
 

package/src/managers/forkedAgentManager.ts

@@ -0,0 +1,193 @@
+import { randomUUID } from "crypto";
+import * as os from "os";
+import * as fs from "fs";
+import * as path from "path";
+import type { Message } from "../types/index.js";
+import { logger } from "../utils/globalLogger.js";
+import { Container } from "../utils/container.js";
+import { SubagentManager, type SubagentInstance } from "./subagentManager.js";
+import type { PermissionMode } from "../types/permissions.js";
+
+export interface ForkedAgentEntry {
+  id: string;
+  instance: SubagentInstance;
+  logPath: string;
+  logStream?: fs.WriteStream;
+  status: "running" | "completed" | "failed";
+}
+
+export interface ForkedAgentManagerCallbacks {
+  onForkedAgentStatusChange?: (entries: ForkedAgentEntry[]) => void;
+}
+
+export class ForkedAgentManager {
+  private activeForks = new Map<string, ForkedAgentEntry>();
+  private callbacks: ForkedAgentManagerCallbacks;
+
+  constructor(
+    private container: Container,
+    options: { callbacks?: ForkedAgentManagerCallbacks } = {},
+  ) {
+    this.callbacks = options.callbacks || {};
+  }
+
+  private get subagentManager(): SubagentManager {
+    return this.container.get<SubagentManager>("SubagentManager")!;
+  }
+
+  /**
+   * Creates a forked subagent with conversation history and executes it asynchronously (fire-and-forget).
+   * Does NOT interact with BackgroundTaskManager.
+   */
+  async forkAndExecute(
+    subagentType: string,
+    messages: Message[],
+    parameters: {
+      description: string;
+      allowedTools?: string[];
+      model?: string;
+      permissionModeOverride?: PermissionMode;
+    },
+    prompt: string,
+  ): Promise<string> {
+    const id = randomUUID();
+
+    // Create log file for debugging
+    const logPath = path.join(os.tmpdir(), `wave-forked-agent-${id}.log`);
+    const logStream = fs.createWriteStream(logPath, { flags: "a" });
+
+    const entry: ForkedAgentEntry = {
+      id,
+      instance: {} as SubagentInstance, // Temporary placeholder
+      logPath,
+      logStream,
+      status: "running",
+    };
+    this.activeForks.set(id, entry);
+
+    // Fire-and-forget execution
+    this.executeFork(entry, subagentType, messages, parameters, prompt).catch(
+      (error) => {
+        logger.error("Forked agent execution failed:", error);
+      },
+    );
+
+    return id;
+  }
+
+  private async executeFork(
+    entry: ForkedAgentEntry,
+    subagentType: string,
+    messages: Message[],
+    parameters: {
+      description: string;
+      allowedTools?: string[];
+      model?: string;
+      permissionModeOverride?: PermissionMode;
+    },
+    prompt: string,
+  ): Promise<void> {
+    try {
+      const configuration =
+        await this.subagentManager.findSubagent(subagentType);
+      if (!configuration) {
+        throw new Error(`Subagent type ${subagentType} not found`);
+      }
+
+      const instance = await this.subagentManager.createInstance(
+        configuration,
+        {
+          description: parameters.description,
+          subagent_type: subagentType,
+          prompt: "",
+          allowedTools: parameters.allowedTools,
+          model: parameters.model,
+          permissionModeOverride: parameters.permissionModeOverride,
+        },
+        false,
+      );
+
+      // Pre-load the message manager with conversation history
+      instance.messageManager.setMessages(messages);
+      instance.logStream = entry.logStream;
+
+      entry.instance = instance;
+
+      // Execute the agent asynchronously
+      const result = await this.subagentManager.executeAgent(
+        instance,
+        prompt,
+        undefined,
+        false, // NOT runInBackground — we handle logging ourselves
+      );
+
+      // Write final response and completion to log
+      if (entry.logStream) {
+        entry.logStream.write(
+          `[${new Date().toISOString()}] Final response:\n${result}\n`,
+        );
+        entry.logStream.write(
+          `[${new Date().toISOString()}] Agent completed successfully\n`,
+        );
+        entry.logStream.end();
+      }
+
+      entry.status = "completed";
+      this.notifyChange();
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+
+      if (entry.logStream) {
+        entry.logStream.write(
+          `[${new Date().toISOString()}] Agent failed: ${errorMessage}\n`,
+        );
+        entry.logStream.end();
+      }
+
+      entry.status = "failed";
+      this.notifyChange();
+    }
+  }
+
+  /**
+   * Abort a running forked agent.
+   */
+  stop(id: string): boolean {
+    const entry = this.activeForks.get(id);
+    if (!entry) {
+      return false;
+    }
+
+    entry.instance?.aiManager?.abortAIMessage();
+    entry.logStream?.destroy();
+    this.activeForks.delete(id);
+    this.notifyChange();
+    return true;
+  }
+
+  /**
+   * Stop all running forked agents and clear the map.
+   */
+  cleanup(): void {
+    for (const [, entry] of this.activeForks) {
+      entry.instance?.aiManager?.abortAIMessage();
+      entry.logStream?.destroy();
+    }
+    this.activeForks.clear();
+    this.notifyChange();
+  }
+
+  /**
+   * Returns list of active forked agents.
+   */
+  getActiveForks(): ForkedAgentEntry[] {
+    return Array.from(this.activeForks.values());
+  }
+
+  private notifyChange(): void {
+    this.callbacks.onForkedAgentStatusChange?.(
+      Array.from(this.activeForks.values()),
+    );
+  }
+}

package/src/managers/messageManager.ts

@@ -9,8 +9,10 @@ import {
   completeBangInMessage,
   removeLastUserMessage,
   addToolBlockToMessageInMessages,
+  addNotificationMessageToMessages,
   UserMessageParams,
   type AgentToolBlockUpdateParams,
+  type AddNotificationMessageParams,
   generateMessageId,
 } from "../utils/messageOperations.js";
 import type { Message, Usage } from "../types/index.js";
@@ -56,6 +58,13 @@ export interface MessageManagerCallbacks {
   onFileHistoryBlockAdded?: (
     snapshots: import("../types/reversion.js").FileSnapshot[],
   ) => void;
+  // Notification callback
+  onNotificationMessageAdded?: (params: {
+    taskId: string;
+    taskType: "shell" | "agent";
+    status: "completed" | "failed" | "killed";
+    summary: string;
+  }) => void;
 }
 
 import { logger } from "../utils/globalLogger.js";
@@ -587,6 +596,22 @@ export class MessageManager {
     this.callbacks.onCompleteBangMessage?.(command, exitCode);
   }
 
+  public addNotificationMessage(
+    params: Omit<AddNotificationMessageParams, "messages">,
+  ): void {
+    const newMessages = addNotificationMessageToMessages({
+      messages: this.messages,
+      ...params,
+    });
+    this.setMessages(newMessages);
+    this.callbacks.onNotificationMessageAdded?.({
+      taskId: params.taskId,
+      taskType: params.taskType,
+      status: params.status,
+      summary: params.summary,
+    });
+  }
+
   /**
    * Rebuild usage array from messages containing usage metadata
    * Called during session restoration to reconstruct usage tracking