wave-agent-sdk 0.13.1 → 0.13.3

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

package/src/managers/notificationQueue.ts

@@ -0,0 +1,19 @@
+export class NotificationQueue {
+  private queue: string[] = [];
+  onNotificationsEnqueued?: () => void;
+
+  enqueue(notification: string): void {
+    this.queue.push(notification);
+    this.onNotificationsEnqueued?.();
+  }
+
+  dequeueAll(): string[] {
+    const items = [...this.queue];
+    this.queue = [];
+    return items;
+  }
+
+  hasPending(): boolean {
+    return this.queue.length > 0;
+  }
+}

package/src/managers/permissionManager.ts

@@ -50,6 +50,7 @@ const SAFE_COMMANDS = [
   "wc",
   "sleep",
   "find",
+  "sort",
 ];
 
 const DEFAULT_ALLOWED_RULES = [
@@ -867,6 +868,7 @@ export class PermissionManager {
                   cmd === "tail" ||
                   cmd === "wc" ||
                   cmd === "sleep" ||
+                  cmd === "sort" ||
                   (cmd === "find" && !isDangerousFind(part))
                 ) {
                   return true;

package/src/managers/subagentManager.ts

@@ -13,6 +13,7 @@ import {
   createAbortPromise,
 } from "../utils/abortUtils.js";
 import { BackgroundTaskManager } from "./backgroundTaskManager.js";
+import { NotificationQueue } from "./notificationQueue.js";
 import { logger } from "../utils/globalLogger.js";
 import {
   UserMessageParams,
@@ -21,6 +22,7 @@ import {
 
 import { Container } from "../utils/container.js";
 import type { PermissionManager } from "./permissionManager.js";
+import type { PermissionMode } from "../types/permissions.js";
 import { ConfigurationService } from "../services/configurationService.js";
 
 export interface SubagentManagerCallbacks {
@@ -85,6 +87,7 @@ export interface SubagentManagerOptions {
 
 export class SubagentManager {
   private instances = new Map<string, SubagentInstance>();
+  private subagentPermissionManagers = new Map<string, PermissionManager>();
   private cachedConfigurations: SubagentConfiguration[] | null = null;
 
   private workdir: string;
@@ -110,6 +113,47 @@ export class SubagentManager {
    */
   async initialize(): Promise<void> {
     await this.loadConfigurations();
+
+    // Hook into parent PermissionManager's update methods to propagate rules to subagents
+    const parentPm = this.container.get<PermissionManager>("PermissionManager");
+    if (
+      parentPm &&
+      typeof parentPm.updateAllowedRules === "function" &&
+      typeof parentPm.updateDeniedRules === "function" &&
+      typeof parentPm.updateAdditionalDirectories === "function"
+    ) {
+      const origUpdateAllowed = parentPm.updateAllowedRules.bind(parentPm);
+      const origUpdateDenied = parentPm.updateDeniedRules.bind(parentPm);
+      const origUpdateDirs =
+        parentPm.updateAdditionalDirectories.bind(parentPm);
+
+      parentPm.updateAllowedRules = (rules: string[]) => {
+        origUpdateAllowed(rules);
+        this.syncPermissionRulesToSubagents();
+      };
+      parentPm.updateDeniedRules = (rules: string[]) => {
+        origUpdateDenied(rules);
+        this.syncPermissionRulesToSubagents();
+      };
+      parentPm.updateAdditionalDirectories = (directories: string[]) => {
+        origUpdateDirs(directories);
+        this.syncPermissionRulesToSubagents();
+      };
+    }
+  }
+
+  /**
+   * Sync parent permission rules to all running subagents
+   */
+  private syncPermissionRulesToSubagents(): void {
+    const parentPm = this.container.get<PermissionManager>("PermissionManager");
+    if (!parentPm) return;
+
+    for (const [, pm] of this.subagentPermissionManagers) {
+      pm.updateAllowedRules(parentPm.getAllowedRules());
+      pm.updateDeniedRules(parentPm.getDeniedRules());
+      pm.updateAdditionalDirectories(parentPm.getAdditionalDirectories());
+    }
   }
 
   /**
@@ -159,6 +203,7 @@ export class SubagentManager {
       allowedTools?: string[];
       model?: string;
       stream?: boolean;
+      permissionModeOverride?: PermissionMode;
     },
     runInBackground?: boolean,
     onUpdate?: () => void,
@@ -176,6 +221,23 @@ export class SubagentManager {
     // Create a child container for the subagent to isolate its managers
     const subagentContainer = this.container.createChild();
 
+    // Register a modified AgentOptions without onLoadingChange to prevent subagent loading
+    // from affecting the parent agent's loading state
+    const parentOptions =
+      this.container.get<import("../types/agent.js").AgentOptions>(
+        "AgentOptions",
+      );
+    if (parentOptions) {
+      const subagentOptions: import("../types/agent.js").AgentOptions = {
+        ...parentOptions,
+        callbacks: {
+          ...parentOptions.callbacks,
+          onLoadingChange: undefined,
+        },
+      };
+      subagentContainer.register("AgentOptions", subagentOptions);
+    }
+
     // Create isolated PermissionManager for the subagent
     const { PermissionManager } = await import("./permissionManager.js");
     const parentPermissionManager =
@@ -183,6 +245,7 @@ export class SubagentManager {
     const subagentPermissionManager = new PermissionManager(subagentContainer, {
       workdir: this.workdir,
       configuredPermissionMode:
+        parameters.permissionModeOverride ??
         parentPermissionManager?.getConfiguredPermissionMode(),
       allowedRules: parentPermissionManager?.getAllowedRules(),
       deniedRules: parentPermissionManager?.getDeniedRules(),
@@ -200,6 +263,9 @@ export class SubagentManager {
     });
     subagentContainer.register("PermissionManager", subagentPermissionManager);
 
+    // Track this subagent's PermissionManager for rule sync
+    this.subagentPermissionManagers.set(subagentId, subagentPermissionManager);
+
     // Add temporary permission rules if provided
     if (parameters.allowedTools) {
       logger.debug(
@@ -241,6 +307,22 @@ export class SubagentManager {
     });
     subagentContainer.register("AIManager", aiManager);
 
+    // Create isolated NotificationQueue for the subagent/forked agent
+    const subagentNotificationQueue = new NotificationQueue();
+    subagentContainer.register("NotificationQueue", subagentNotificationQueue);
+
+    // Create isolated BackgroundTaskManager for the subagent/forked agent
+    const subagentBackgroundTaskManager = new BackgroundTaskManager(
+      subagentContainer,
+      {
+        workdir: this.workdir,
+      },
+    );
+    subagentContainer.register(
+      "BackgroundTaskManager",
+      subagentBackgroundTaskManager,
+    );
+
     const instance: SubagentInstance = {
       subagentId,
       configuration,
@@ -262,42 +344,6 @@ export class SubagentManager {
     return instance;
   }
 
-  /**
-   * Create a new subagent instance initialized with a copy of the current message history.
-   * This is used for background tasks like auto-memory extraction.
-   */
-  async forkAgent(
-    subagentType: string,
-    messages: Message[],
-    parameters: {
-      description: string;
-      allowedTools?: string[];
-      model?: string;
-    },
-    onUpdate?: () => void,
-  ): Promise<SubagentInstance> {
-    const configuration = await this.findSubagent(subagentType);
-    if (!configuration) {
-      throw new Error(`Subagent type ${subagentType} not found`);
-    }
-
-    const instance = await this.createInstance(
-      configuration,
-      {
-        ...parameters,
-        subagent_type: subagentType,
-        prompt: "", // Forked agents start with history
-      },
-      false,
-      onUpdate,
-    );
-
-    // Initialize the message manager with provided messages
-    instance.messageManager.setMessages(messages);
-
-    return instance;
-  }
-
   /**
    * Execute agent using subagent instance
    *
@@ -367,6 +413,17 @@ export class SubagentManager {
               task.endTime = Date.now();
               task.runtime = task.endTime - startTime;
             }
+
+            // Enqueue completion notification
+            const notificationQueue = this.container.has("NotificationQueue")
+              ? this.container.get<NotificationQueue>("NotificationQueue")
+              : undefined;
+            if (notificationQueue) {
+              const summary = `Agent task "${instance.description}" completed`;
+              notificationQueue.enqueue(
+                `<task-notification>\n<task-id>${taskId}</task-id>\n<task-type>agent</task-type>\n<status>completed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+              );
+            }
           } catch (error) {
             const task = backgroundTaskManager?.getTask(taskId);
             if (task) {
@@ -376,6 +433,19 @@ export class SubagentManager {
               task.endTime = Date.now();
               task.runtime = task.endTime - startTime;
             }
+
+            // Enqueue error notification
+            const notificationQueue = this.container.has("NotificationQueue")
+              ? this.container.get<NotificationQueue>("NotificationQueue")
+              : undefined;
+            if (notificationQueue) {
+              const errorMsg =
+                error instanceof Error ? error.message : String(error);
+              const summary = `Agent task "${instance.description}" failed: ${errorMsg}`;
+              notificationQueue.enqueue(
+                `<task-notification>\n<task-id>${taskId}</task-id>\n<task-type>agent</task-type>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+              );
+            }
           }
         })();
 
@@ -519,6 +589,17 @@ export class SubagentManager {
             task.runtime = task.endTime - task.startTime;
           }
         }
+
+        // Enqueue completion notification
+        const notificationQueue = this.container.has("NotificationQueue")
+          ? this.container.get<NotificationQueue>("NotificationQueue")
+          : undefined;
+        if (notificationQueue) {
+          const summary = `Agent task "${instance.description}" completed`;
+          notificationQueue.enqueue(
+            `<task-notification>\n<task-id>${instance.backgroundTaskId}</task-id>\n<task-type>agent</task-type>\n<status>completed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+          );
+        }
       }
 
       return response || "Agent completed with no text response";
@@ -543,6 +624,19 @@ export class SubagentManager {
             task.runtime = task.endTime - task.startTime;
           }
         }
+
+        // Enqueue error notification
+        const notificationQueue = this.container.has("NotificationQueue")
+          ? this.container.get<NotificationQueue>("NotificationQueue")
+          : undefined;
+        if (notificationQueue) {
+          const errorMsg =
+            error instanceof Error ? error.message : String(error);
+          const summary = `Agent task "${instance.description}" failed: ${errorMsg}`;
+          notificationQueue.enqueue(
+            `<task-notification>\n<task-id>${instance.backgroundTaskId}</task-id>\n<task-type>agent</task-type>\n<status>failed</status>\n<summary>${summary}</summary>\n</task-notification>`,
+          );
+        }
       }
       throw error;
     } finally {
@@ -595,6 +689,7 @@ export class SubagentManager {
         instance.status === "aborted")
     ) {
       this.instances.delete(subagentId);
+      this.subagentPermissionManagers.delete(subagentId);
     }
   }
 
@@ -671,12 +766,11 @@ export class SubagentManager {
 
             // Log tool execution to file
             if (instance.logStream) {
-              const compactParams = (params.parameters || "{}").substring(
-                0,
-                100,
-              );
+              const displayParams =
+                params.compactParams ||
+                (params.parameters || "{}").substring(0, 100);
               instance.logStream.write(
-                `[${new Date().toISOString()}] Running tool: ${params.name} with params: ${compactParams}${compactParams.length >= 100 ? "..." : ""}\n`,
+                `[${new Date().toISOString()}] ${params.name}${displayParams ? ` ${displayParams}` : ""}\n`,
               );
             }
           }

package/src/services/autoMemoryService.ts

@@ -2,7 +2,7 @@ import * as path from "node:path";
 import * as fs from "node:fs/promises";
 import { Container } from "../utils/container.js";
 import { MessageManager } from "../managers/messageManager.js";
-import { SubagentManager } from "../managers/subagentManager.js";
+import { ForkedAgentManager } from "../managers/forkedAgentManager.js";
 import { MemoryService } from "./memory.js";
 import { ConfigurationService } from "./configurationService.js";
 import { logger } from "../utils/globalLogger.js";
@@ -24,8 +24,8 @@ export class AutoMemoryService {
     return this.container.get<MessageManager>("MessageManager")!;
   }
 
-  private get subagentManager(): SubagentManager {
-    return this.container.get<SubagentManager>("SubagentManager")!;
+  private get forkedAgentManager(): ForkedAgentManager {
+    return this.container.get<ForkedAgentManager>("ForkedAgentManager")!;
   }
 
   private get memoryService(): MemoryService {
@@ -143,8 +143,13 @@ export class AutoMemoryService {
       }
     }
 
-    // Fork the general-purpose agent with restricted tool access
-    const instance = await this.subagentManager.forkAgent(
+    const prompt = buildAutoMemoryExtractionPrompt(
+      newMessageCount,
+      existingMemoriesManifest,
+    );
+
+    // Execute the forked agent in background (fire-and-forget, decoupled from BackgroundTaskManager)
+    await this.forkedAgentManager.forkAndExecute(
       "general-purpose",
       messages,
       {
@@ -157,20 +162,9 @@ export class AutoMemoryService {
           `Edit(${memoryDir}/**/*)`,
         ],
         model: "fastModel", // Use fast model for background tasks to reduce latency and cost
+        permissionModeOverride: "dontAsk", // Auto-deny out-of-scope writes without prompting user
       },
-    );
-
-    const prompt = buildAutoMemoryExtractionPrompt(
-      newMessageCount,
-      existingMemoriesManifest,
-    );
-
-    // Execute in background so it doesn't block the main conversation flow
-    await this.subagentManager.executeAgent(
-      instance,
       `${prompt}\n\nThe memory directory for this project is: ${memoryDir}`,
-      undefined,
-      true, // runInBackground
     );
 
     logger.debug("Auto-memory extraction started in background.");

package/src/services/interactionService.ts

@@ -7,6 +7,7 @@ import type { ConfigurationService } from "./configurationService.js";
 import type { AIManager } from "../managers/aiManager.js";
 import type { SubagentManager } from "../managers/subagentManager.js";
 import type { TaskManager } from "./taskManager.js";
+import type { NotificationQueue } from "../managers/notificationQueue.js";
 
 export interface InteractionContext {
   messageManager: MessageManager;
@@ -58,6 +59,23 @@ export class InteractionService {
         // Don't add to history, let normal message processing logic below handle it
       }
 
+      // Inject pending notifications from background tasks
+      const notificationQueue = context.aiManager["container"].has(
+        "NotificationQueue",
+      )
+        ? context.aiManager["container"].get<NotificationQueue>(
+            "NotificationQueue",
+          )
+        : undefined;
+      if (notificationQueue && notificationQueue.hasPending()) {
+        const notifications = notificationQueue.dequeueAll();
+        for (const notification of notifications) {
+          messageManager.addUserMessage({
+            content: notification,
+          });
+        }
+      }
+
       // Handle normal AI message
       // Add user message first, will automatically sync to UI
       messageManager.addUserMessage({

package/src/types/agent.ts

@@ -95,4 +95,5 @@ export interface AgentCallbacks
   onBackgroundCurrentTask?: () => void;
   onModelChange?: (model: string) => void;
   onConfiguredModelsChange?: (models: string[]) => void;
+  onLoadingChange?: (loading: boolean) => void;
 }

package/src/types/messaging.ts

@@ -27,7 +27,8 @@ export type MessageBlock =
   | BangBlock
   | CompressBlock
   | ReasoningBlock
-  | FileHistoryBlock;
+  | FileHistoryBlock
+  | TaskNotificationBlock;
 
 export interface TextBlock {
   type: "text";
@@ -99,3 +100,12 @@ export interface FileHistoryBlock {
   type: "file_history";
   snapshots: import("./reversion.js").FileSnapshot[];
 }
+
+export interface TaskNotificationBlock {
+  type: "task_notification";
+  taskId: string;
+  taskType: "shell" | "agent";
+  status: "completed" | "failed" | "killed";
+  summary: string;
+  outputFile?: string;
+}