wave-agent-sdk 0.15.0 → 0.15.2

package/dist/utils/worktreeUtils.js

@@ -0,0 +1,236 @@
+/**
+ * Git worktree creation and removal utilities for the SDK.
+ * Used by EnterWorktree and ExitWorktree tools.
+ */
+import { execSync } from "node:child_process";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { getGitMainRepoRoot, getDefaultRemoteBranch } from "./gitUtils.js";
+import { logger } from "./globalLogger.js";
+/**
+ * Validate a worktree name to prevent path traversal and invalid characters.
+ */
+export function validateWorktreeName(name) {
+    const MAX_LENGTH = 64;
+    if (name.length > MAX_LENGTH) {
+        throw new Error(`Invalid worktree name: must be ${MAX_LENGTH} characters or fewer (got ${name.length})`);
+    }
+    for (const segment of name.split("/")) {
+        if (segment === "." || segment === "..") {
+            throw new Error(`Invalid worktree name "${name}": must not contain "." or ".." path segments`);
+        }
+        if (!/^[a-zA-Z0-9._-]+$/.test(segment)) {
+            throw new Error(`Invalid worktree name "${name}": each "/"-separated segment must be non-empty and contain only letters, digits, dots, underscores, and dashes`);
+        }
+    }
+}
+/**
+ * Generate a random worktree name.
+ */
+export function generateWorktreeName() {
+    const adjectives = [
+        "swift",
+        "calm",
+        "bold",
+        "keen",
+        "bright",
+        "cool",
+        "deep",
+        "fair",
+        "gentle",
+        "grand",
+    ];
+    const nouns = [
+        "fox",
+        "owl",
+        "hawk",
+        "wolf",
+        "bear",
+        "lynx",
+        "pike",
+        "kite",
+        "dove",
+        "stag",
+    ];
+    const adj = adjectives[Math.floor(Math.random() * adjectives.length)];
+    const noun = nouns[Math.floor(Math.random() * nouns.length)];
+    const num = Math.floor(Math.random() * 900) + 100;
+    return `${adj}-${noun}-${num}`;
+}
+/**
+ * Get the current HEAD commit SHA.
+ */
+export function getHeadCommit(cwd) {
+    return execSync(`git -C "${cwd}" rev-parse HEAD`, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+/**
+ * Create a git worktree for use during a session.
+ */
+export function createWorktree(name, cwd) {
+    const repoRoot = getGitMainRepoRoot(cwd);
+    if (!repoRoot) {
+        throw new Error("Cannot create a worktree: not in a git repository. Configure WorktreeCreate and WorktreeRemove hooks in settings.json to use worktree isolation with other VCS systems.");
+    }
+    // Capture HEAD commit before creating worktree (for dirty-check on exit)
+    const originalHeadCommit = getHeadCommit(cwd);
+    const worktreePath = path.join(repoRoot, ".wave", "worktrees", name);
+    const branchName = `worktree-${name}`;
+    const baseBranch = getDefaultRemoteBranch(cwd);
+    // Ensure parent directory exists
+    const parentDir = path.dirname(worktreePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    // Check if worktree already exists
+    if (fs.existsSync(worktreePath)) {
+        return {
+            name,
+            path: worktreePath,
+            branch: branchName,
+            repoRoot,
+            isNew: false,
+            originalHeadCommit,
+        };
+    }
+    try {
+        // Create worktree and branch
+        execSync(`git worktree add -b ${branchName} "${worktreePath}" ${baseBranch}`, {
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: "0",
+                GIT_ASKPASS: "",
+            },
+        });
+        return {
+            name,
+            path: worktreePath,
+            branch: branchName,
+            repoRoot,
+            isNew: true,
+            originalHeadCommit,
+        };
+    }
+    catch (error) {
+        const stderr = error.stderr?.toString() || "";
+        if (stderr.includes("already exists")) {
+            // Branch exists but worktree doesn't — attach to existing branch
+            try {
+                execSync(`git worktree add "${worktreePath}" ${branchName}`, {
+                    cwd: repoRoot,
+                    stdio: ["ignore", "pipe", "pipe"],
+                    env: {
+                        ...process.env,
+                        GIT_TERMINAL_PROMPT: "0",
+                        GIT_ASKPASS: "",
+                    },
+                });
+                return {
+                    name,
+                    path: worktreePath,
+                    branch: branchName,
+                    repoRoot,
+                    isNew: true,
+                    originalHeadCommit,
+                };
+            }
+            catch (innerError) {
+                throw new Error(`Failed to add worktree: ${innerError.message}`);
+            }
+        }
+        throw new Error(`Failed to create worktree: ${error.message}\n${stderr}`);
+    }
+}
+/**
+ * Remove a git worktree and its branch.
+ */
+export function removeWorktree(info) {
+    const repoRoot = info.repoRoot;
+    try {
+        // Get current branch in worktree before removing
+        let currentBranch;
+        try {
+            currentBranch = execSync(`git rev-parse --abbrev-ref HEAD`, {
+                cwd: info.path,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim();
+        }
+        catch {
+            // Ignore errors
+        }
+        // Remove worktree
+        execSync(`git worktree remove --force "${info.path}"`, {
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Delete worktree branch
+        try {
+            execSync(`git branch -D ${info.branch}`, {
+                cwd: repoRoot,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch {
+            // Ignore errors
+        }
+        // Delete current branch if different and not protected
+        if (currentBranch &&
+            currentBranch !== info.branch &&
+            currentBranch !== "HEAD") {
+            const defaultRemoteBranch = getDefaultRemoteBranch(repoRoot);
+            const defaultBranchName = defaultRemoteBranch.split("/").pop();
+            if (currentBranch !== defaultBranchName &&
+                currentBranch !== "main" &&
+                currentBranch !== "master") {
+                try {
+                    execSync(`git branch -D ${currentBranch}`, {
+                        cwd: repoRoot,
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
+                }
+                catch {
+                    // Ignore errors
+                }
+            }
+        }
+    }
+    catch (error) {
+        logger.error("Failed to remove worktree or branch:", {
+            error: error instanceof Error ? error.message : String(error),
+            worktreePath: info.path,
+        });
+        throw error;
+    }
+}
+/**
+ * Count uncommitted files and new commits in a worktree.
+ * Returns null if git commands fail (fail-closed).
+ */
+export function countWorktreeChanges(worktreePath, originalHeadCommit) {
+    try {
+        const statusOutput = execSync(`git -C "${worktreePath}" status --porcelain`, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const changedFiles = statusOutput
+            .split("\n")
+            .filter((l) => l.trim() !== "").length;
+        if (!originalHeadCommit) {
+            return null;
+        }
+        const revListOutput = execSync(`git -C "${worktreePath}" rev-list --count ${originalHeadCommit}..HEAD`, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const commits = parseInt(revListOutput.trim(), 10) || 0;
+        return { changedFiles, commits };
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

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

package/src/agent.ts

@@ -83,10 +83,6 @@ export class Agent {
   // Configuration options storage for dynamic resolution
   private options: AgentOptions;
 
-  // Memory content storage
-  private _projectMemoryContent: string = "";
-  private _userMemoryContent: string = "";
-
   // Dynamic configuration getter methods
   public getGatewayConfig(): GatewayConfig {
     return this.configurationService.resolveGatewayConfig();
@@ -282,12 +278,20 @@ export class Agent {
 
   /** Get project memory content */
   public get projectMemory(): string {
-    return this._projectMemoryContent;
+    const memoryService =
+      this.container.get<import("./services/memory.js").MemoryService>(
+        "MemoryService",
+      );
+    return memoryService?.cachedProjectMemory ?? "";
   }
 
   /** Get user memory content */
   public get userMemory(): string {
-    return this._userMemoryContent;
+    const memoryService =
+      this.container.get<import("./services/memory.js").MemoryService>(
+        "MemoryService",
+      );
+    return memoryService?.cachedUserMemory ?? "";
   }
 
   /** Get combined memory content (project + user + modular rules) */
@@ -414,6 +418,7 @@ export class Agent {
    * @param options.messages - Optional initial messages for testing convenience
    * @param options.workdir - Working directory (defaults to process.cwd())
    * @param options.systemPrompt - Optional custom system prompt
+   * @param options.mcpServers - Optional MCP server configs to connect at startup
    * @returns Promise that resolves to initialized Agent instance
    *
    * @example
@@ -479,12 +484,6 @@ export class Agent {
         memoryRuleManager: this.memoryRuleManager,
         liveConfigManager: this.liveConfigManager,
         taskManager: this.taskManager,
-        setProjectMemory: (content) => {
-          this._projectMemoryContent = content;
-        },
-        setUserMemory: (content) => {
-          this._userMemoryContent = content;
-        },
         resolveAndValidateConfig: () => this.resolveAndValidateConfig(),
       },
       options,
@@ -603,6 +602,44 @@ export class Agent {
     this.options.callbacks?.onBackgroundCurrentTask?.();
   }
 
+  /**
+   * Trigger WorktreeRemove hook before agent destruction.
+   * Called from CLI exit dialog when user chooses to remove the worktree.
+   * Non-blocking: errors logged but don't prevent removal.
+   */
+  public async triggerWorktreeRemoveHook(worktreePath: string): Promise<void> {
+    if (!this.hookManager.hasHooks("WorktreeRemove")) {
+      return;
+    }
+    try {
+      const sessionId = this.messageManager.getSessionId();
+      const transcriptPath = this.messageManager.getTranscriptPath();
+      const hookResults = await this.hookManager.executeHooks(
+        "WorktreeRemove",
+        {
+          event: "WorktreeRemove",
+          projectDir: this.workdir,
+          timestamp: new Date(),
+          sessionId,
+          transcriptPath,
+          cwd: this.workdir,
+          worktreePath,
+          env: Object.fromEntries(
+            Object.entries(process.env).filter((e) => e[1] !== undefined),
+          ) as Record<string, string>,
+        },
+      );
+      // Process results via messageManager (may not be visible during shutdown)
+      this.hookManager.processHookResults(
+        "WorktreeRemove",
+        hookResults,
+        this.messageManager,
+      );
+    } catch (error) {
+      this.logger?.warn("WorktreeRemove hooks execution failed:", error);
+    }
+  }
+
   /** Destroy managers, clean up resources */
   public async destroy(): Promise<void> {
     // Clear notification callback first to prevent any late triggers from
@@ -894,4 +931,16 @@ export class Agent {
   public get taskListId(): string {
     return this.taskManager.getTaskListId();
   }
+
+  /**
+   * Check if there are any running background tasks or active subagents
+   */
+  public get hasRunningBackgroundWork(): boolean {
+    const runningTasks = this.backgroundTaskManager
+      .getAllTasks()
+      .some((t) => t.status === "running");
+    const activeSubagents =
+      this.subagentManager.getActiveInstances().length > 0;
+    return runningTasks || activeSubagents;
+  }
 }

package/src/constants/tools.ts

@@ -19,3 +19,6 @@ export const CRON_CREATE_TOOL_NAME = "CronCreate";
 export const CRON_DELETE_TOOL_NAME = "CronDelete";
 export const CRON_LIST_TOOL_NAME = "CronList";
 export const WEB_FETCH_TOOL_NAME = "WebFetch";
+export const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
+export const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
+export const TOOL_SEARCH_TOOL_NAME = "ToolSearch";

package/src/index.ts

@@ -26,4 +26,5 @@ export * from "./utils/hookMatcher.js";
 export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
+export * from "./utils/worktreeSession.js";
 export * from "./types/index.js";

package/src/managers/aiManager.ts

@@ -53,20 +53,20 @@ export class AIManager {
   private abortController: AbortController | null = null;
   onLoadingChange?: (loading: boolean) => void;
   private toolAbortController: AbortController | null = null;
-  private workdir: string;
   private systemPrompt?: string;
   private subagentType?: string; // Store subagent type for hook context
   private stream: boolean; // Streaming mode flag
   private modelOverride?: string;
   private consecutiveCompactionFailures: number = 0;
   private readonly maxTurns?: number;
+  /** Tracks which deferred tools have been discovered via ToolSearch */
+  private discoveredTools = new Set<string>();
 
   // Service overrides
   constructor(
     private container: Container,
     options: AIManagerOptions,
   ) {
-    this.workdir = options.workdir;
     this.systemPrompt = options.systemPrompt;
     this.subagentType = options.subagentType; // Store subagent type
     this.stream = options.stream ?? true; // Default to true if not specified
@@ -166,7 +166,16 @@ export class AIManager {
   }
 
   public getWorkdir(): string {
-    return this.workdir;
+    return this.container.get<string>("Workdir") ?? process.cwd();
+  }
+
+  /**
+   * Update the working directory mid-session (e.g., when entering/exiting a worktree).
+   * Also updates process.chdir() so bash commands use the new directory.
+   */
+  public setWorkdir(newWorkdir: string): void {
+    this.container.register("Workdir", newWorkdir);
+    process.chdir(newWorkdir);
   }
 
   private isCompacting: boolean = false;
@@ -185,8 +194,9 @@ export class AIManager {
     return this.toolManager.getToolsConfig({
       availableSubagents,
       availableSkills,
-      workdir: this.workdir,
+      workdir: this.getWorkdir(),
       isSubagent: !!this.subagentType,
+      discoveredTools: this.discoveredTools,
     });
   }
 
@@ -233,7 +243,7 @@ export class AIManager {
         .find((plugin) => plugin.name === toolName);
       if (toolPlugin?.formatCompactParams) {
         const context: ToolContext = {
-          workdir: this.workdir,
+          workdir: this.getWorkdir(),
           taskManager: this.taskManager,
         };
         return toolPlugin.formatCompactParams(toolArgs, context);
@@ -332,7 +342,7 @@ export class AIManager {
 
           // 2. Working directory
           contextParts.push(
-            `\n\n[Working Directory]\nCurrent working directory: ${this.workdir}`,
+            `\n\n[Working Directory]\nCurrent working directory: ${this.getWorkdir()}`,
           );
 
           // 3. Plan mode context
@@ -620,10 +630,10 @@ export class AIManager {
 
       if (this.getAutoMemoryEnabled()) {
         const directory = this.memoryService.getAutoMemoryDirectory(
-          this.workdir,
+          this.getWorkdir(),
         );
         const content = await this.memoryService.getAutoMemoryContent(
-          this.workdir,
+          this.getWorkdir(),
         );
         autoMemoryOptions = { directory, content };
       }
@@ -635,14 +645,14 @@ export class AIManager {
         messages: recentMessages,
         sessionId: this.messageManager.getSessionId(),
         abortSignal: abortController.signal,
-        workdir: this.workdir, // Pass working directory
+        workdir: this.getWorkdir(), // Pass working directory
         tools: toolsConfig, // Pass filtered tool configuration
         model: model, // Use passed model
         systemPrompt: buildSystemPrompt(
           this.systemPrompt,
           filteredToolPlugins,
           {
-            workdir: this.workdir,
+            workdir: this.getWorkdir(),
             memory: combinedMemory,
             language: this.getLanguage(),
             isSubagent: !!this.subagentType,
@@ -892,7 +902,7 @@ export class AIManager {
               const context: ToolContext = {
                 abortSignal: toolAbortController.signal,
                 backgroundTaskManager: this.backgroundTaskManager,
-                workdir: this.workdir,
+                workdir: this.getWorkdir(),
                 messageId: this.messageManager.getMessages().slice(-1)[0]?.id,
                 sessionId: this.messageManager.getSessionId(),
                 toolCallId: toolId,
@@ -952,6 +962,11 @@ export class AIManager {
                 toolArgs,
                 toolResult,
               );
+
+              // Track discovered tools from ToolSearch results
+              if (toolName === "ToolSearch" && toolResult.success) {
+                this.trackDiscoveredTools(toolResult.content);
+              }
             } catch (toolError) {
               const errorMessage =
                 toolError instanceof Error
@@ -1196,11 +1211,11 @@ export class AIManager {
 
       const context: ExtendedHookExecutionContext = {
         event: hookName,
-        projectDir: this.workdir,
+        projectDir: this.getWorkdir(),
         timestamp: new Date(),
         sessionId: this.messageManager.getSessionId(),
         transcriptPath: this.messageManager.getTranscriptPath(),
-        cwd: this.workdir,
+        cwd: this.getWorkdir(),
         subagentType: this.subagentType, // Include subagent type in hook context
         // Stop hooks don't need toolName, toolInput, toolResponse, or userPrompt
         env: Object.fromEntries(
@@ -1252,7 +1267,7 @@ export class AIManager {
         if (autoMemoryService) {
           // Trigger extraction, but don't block the return.
           // onTurnEnd itself returns quickly after forking.
-          autoMemoryService.onTurnEnd(this.workdir).catch((err) => {
+          autoMemoryService.onTurnEnd(this.getWorkdir()).catch((err) => {
             logger?.error("Auto-memory extraction trigger failed:", err);
           });
         }
@@ -1283,12 +1298,12 @@ export class AIManager {
     try {
       const context: ExtendedHookExecutionContext = {
         event: "PreToolUse",
-        projectDir: this.workdir,
+        projectDir: this.getWorkdir(),
         timestamp: new Date(),
         toolName,
         sessionId: this.messageManager.getSessionId(),
         transcriptPath: this.messageManager.getTranscriptPath(),
-        cwd: this.workdir,
+        cwd: this.getWorkdir(),
         toolInput,
         subagentType: this.subagentType, // Include subagent type in hook context
         env: Object.fromEntries(
@@ -1350,12 +1365,12 @@ export class AIManager {
     try {
       const context: ExtendedHookExecutionContext = {
         event: "PostToolUse",
-        projectDir: this.workdir,
+        projectDir: this.getWorkdir(),
         timestamp: new Date(),
         toolName,
         sessionId: this.messageManager.getSessionId(),
         transcriptPath: this.messageManager.getTranscriptPath(),
-        cwd: this.workdir,
+        cwd: this.getWorkdir(),
         toolInput,
         toolResponse,
         subagentType: this.subagentType, // Include subagent type in hook context
@@ -1397,4 +1412,44 @@ export class AIManager {
       logger?.error("PostToolUse hook execution failed:", error);
     }
   }
+
+  /**
+   * Parse ToolSearch result content to extract discovered tool names.
+   * ToolSearch returns content like "ToolName: description\nParameters: {...}"
+   * or shortResult like "Discovered tools: ToolA, ToolB".
+   */
+  private trackDiscoveredTools(content: string): void {
+    // Try to extract tool names from shortResult-style content
+    const discoveredMatch = content.match(/Discovered tools?: ([\w-, ]+)/);
+    if (discoveredMatch) {
+      const names = discoveredMatch[1]!
+        .split(",")
+        .map((n) => n.trim())
+        .filter(Boolean);
+      for (const name of names) {
+        this.discoveredTools.add(name);
+      }
+      logger?.debug("Discovered tools:", names);
+      return;
+    }
+
+    // Fallback: extract tool names from "ToolName: description" pattern
+    const lines = content.split("\n");
+    const nonToolKeywords = new Set([
+      "parameters",
+      "description",
+      "result",
+      "error",
+      "content",
+      "type",
+      "properties",
+      "required",
+    ]);
+    for (const line of lines) {
+      const toolMatch = line.match(/^([\w-]+):/);
+      if (toolMatch && !nonToolKeywords.has(toolMatch[1]!.toLowerCase())) {
+        this.discoveredTools.add(toolMatch[1]!);
+      }
+    }
+  }
 }

package/src/managers/hookManager.ts

@@ -377,6 +377,11 @@ export class HookManager {
         messageManager.addErrorBlock(errorMessage);
         return { shouldBlock: false };
 
+      case "WorktreeRemove":
+        // Non-blocking for cleanup, log error but don't block
+        messageManager.addErrorBlock(errorMessage);
+        return { shouldBlock: false };
+
       case "SessionStart":
         // Non-blocking for startup, show error in error block
         messageManager.addErrorBlock(errorMessage);
@@ -591,6 +596,7 @@ export class HookManager {
         event === "Stop" ||
         event === "SubagentStop" ||
         event === "WorktreeCreate" ||
+        event === "WorktreeRemove" ||
         event === "SessionStart" ||
         event === "SessionEnd") &&
       context.toolName !== undefined
@@ -669,6 +675,7 @@ export class HookManager {
       event === "Stop" ||
       event === "SubagentStop" ||
       event === "WorktreeCreate" ||
+      event === "WorktreeRemove" ||
       event === "SessionStart" ||
       event === "SessionEnd"
     ) {
@@ -731,6 +738,7 @@ export class HookManager {
         event === "Stop" ||
         event === "SubagentStop" ||
         event === "WorktreeCreate" ||
+        event === "WorktreeRemove" ||
         event === "SessionStart" ||
         event === "SessionEnd") &&
       config.matcher
@@ -772,6 +780,7 @@ export class HookManager {
           SubagentStop: 0,
           PermissionRequest: 0,
           WorktreeCreate: 0,
+          WorktreeRemove: 0,
           SessionStart: 0,
           SessionEnd: 0,
         },
@@ -786,6 +795,7 @@ export class HookManager {
       SubagentStop: 0,
       PermissionRequest: 0,
       WorktreeCreate: 0,
+      WorktreeRemove: 0,
       SessionStart: 0,
       SessionEnd: 0,
     };