wave-agent-sdk 0.19.9 → 1.0.0

package/dist/utils/worktreeUtils.js

@@ -2,11 +2,16 @@
  * Git worktree creation and removal utilities for the SDK.
  * Used by EnterWorktree and ExitWorktree tools.
  */
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { getGitMainRepoRoot, getDefaultRemoteBranch, ensureWaveRuntimeFilesExcluded, } from "./gitUtils.js";
 import { logger } from "./globalLogger.js";
+// Post-creation setup runs inside the shared `wave --stdio` process too
+// (desktop sessions), so use the async execFile: a synchronous git call
+// (e.g. `git ls-files` over a large working tree) would freeze every session.
+const execFileAsync = promisify(execFile);
 /**
  * Validate a worktree name to prevent path traversal and invalid characters.
  */
@@ -211,6 +216,288 @@ export function createWorktree(name, cwd, options) {
         throw new Error(`Failed to create worktree: ${error.message}\n${stderr}`);
     }
 }
+/** Translate a single gitignore glob into a RegExp (gitignore semantics). */
+function globToRegExp(glob) {
+    let source = "^";
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === "*") {
+            if (glob[i + 1] === "*") {
+                if (glob[i + 2] === "/") {
+                    // "**/" matches zero or more leading directories
+                    source += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    source += ".*";
+                    i += 1;
+                }
+            }
+            else {
+                source += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            source += "[^/]";
+        }
+        else if (ch === "[") {
+            const end = glob.indexOf("]", i + 1);
+            if (end === -1) {
+                source += "\\[";
+            }
+            else {
+                let charClass = glob.slice(i, end + 1);
+                if (charClass.startsWith("[!")) {
+                    // gitignore uses "[!...]" for a negated character class
+                    charClass = "[^" + charClass.slice(2);
+                }
+                source += charClass;
+                i = end;
+            }
+        }
+        else {
+            source += ch.replace(/[.+^${}()|\\]/g, "\\$&");
+        }
+    }
+    source += "$";
+    return new RegExp(source);
+}
+/**
+ * Parse .worktreeinclude content into patterns. Blank lines and "#" comments
+ * are skipped, matching gitignore conventions.
+ */
+function parseWorktreeIncludePatterns(content) {
+    const patterns = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        let raw = line;
+        const negated = raw.startsWith("!");
+        if (negated)
+            raw = raw.slice(1);
+        const dirOnly = raw.endsWith("/");
+        if (dirOnly)
+            raw = raw.slice(0, -1);
+        const anchored = raw.startsWith("/");
+        if (anchored)
+            raw = raw.slice(1);
+        if (!raw)
+            continue;
+        patterns.push({
+            raw,
+            negated,
+            dirOnly,
+            anchored,
+            anyLevel: !anchored && !raw.includes("/"),
+            regex: globToRegExp(raw),
+        });
+    }
+    return patterns;
+}
+/** Test a single pattern against one candidate path. */
+function testPatternAgainst(pattern, candidate) {
+    if (pattern.anyLevel) {
+        // Match the full path or any "/"-suffix (basename at any level)
+        if (pattern.regex.test(candidate))
+            return true;
+        for (let i = 0; i < candidate.length; i++) {
+            if (candidate[i] === "/" && pattern.regex.test(candidate.slice(i + 1))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    return pattern.regex.test(candidate);
+}
+/**
+ * Test a pattern against a path and every ancestor prefix. Excluding a
+ * directory excludes everything beneath it (gitignore semantics), so ancestor
+ * prefixes are always treated as directories.
+ */
+function patternMatchesPath(pattern, relPath, isDir) {
+    let candidate = relPath;
+    for (;;) {
+        const candidateIsDir = candidate === relPath ? isDir : true;
+        if (!(pattern.dirOnly && !candidateIsDir) &&
+            testPatternAgainst(pattern, candidate)) {
+            return true;
+        }
+        const idx = candidate.lastIndexOf("/");
+        if (idx === -1)
+            break;
+        candidate = candidate.slice(0, idx);
+    }
+    return false;
+}
+/** Last-match-wins resolution with "!" negation. */
+function worktreeIncludeMatches(patterns, relPath, isDir) {
+    let matched = false;
+    for (const pattern of patterns) {
+        if (patternMatchesPath(pattern, relPath, isDir)) {
+            matched = !pattern.negated;
+        }
+    }
+    return matched;
+}
+/**
+ * A positive pattern targets something inside a collapsed directory: either it
+ * literally starts with the directory path, or the directory path starts with
+ * the pattern's literal (pre-glob) prefix.
+ */
+function needsExpansion(patterns, dir) {
+    return patterns.some((p) => {
+        if (p.negated)
+            return false;
+        if (p.raw.startsWith(dir + "/"))
+            return true;
+        const globIdx = p.raw.search(/[*?[]/);
+        if (globIdx > 0 && dir.startsWith(p.raw.slice(0, globIdx)))
+            return true;
+        return false;
+    });
+}
+// --- Post-creation setup -----------------------------------------------------
+/**
+ * Copy <repoRoot>/.wave/settings.local.json into the worktree so local
+ * configuration (permissions, env, ...) carries over. Missing files are
+ * skipped silently; other failures only log a warning.
+ */
+async function copyLocalSettingsToWorktree(repoRoot, worktreePath) {
+    const relativePath = path.join(".wave", "settings.local.json");
+    const sourcePath = path.join(repoRoot, relativePath);
+    const destPath = path.join(worktreePath, relativePath);
+    let content;
+    try {
+        content = await fs.promises.readFile(sourcePath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            logger.warn(`Failed to read ${sourcePath}: ${error.message}`);
+        }
+        return;
+    }
+    try {
+        await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+        await fs.promises.writeFile(destPath, content);
+    }
+    catch (error) {
+        logger.warn(`Failed to copy ${relativePath} into worktree: ${error.message}`);
+    }
+}
+/**
+ * Copy files listed in <repoRoot>/.worktreeinclude into the worktree. Each
+ * non-comment line is a gitignore pattern; matching gitignored files are
+ * copied at their relative paths.
+ */
+async function copyWorktreeIncludeFiles(repoRoot, worktreePath) {
+    const includePath = path.join(repoRoot, ".worktreeinclude");
+    let content;
+    try {
+        content = await fs.promises.readFile(includePath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const patterns = parseWorktreeIncludePatterns(content);
+    if (patterns.length === 0)
+        return [];
+    const worktreeRelPath = path
+        .relative(repoRoot, worktreePath)
+        .split(path.sep)
+        .join("/");
+    // The worktree lives under .wave/worktrees/, which is gitignored — never
+    // copy the worktree (or anything inside it) into itself.
+    const isSelf = (entry) => entry === worktreeRelPath || entry.startsWith(worktreeRelPath + "/");
+    // "--directory" collapses fully-ignored directories into single entries,
+    // which keeps the listing fast on large repos.
+    let entries;
+    try {
+        const { stdout } = await execFileAsync("git", [
+            "ls-files",
+            "--others",
+            "--ignored",
+            "--exclude-standard",
+            "--directory",
+        ], { cwd: repoRoot, encoding: "utf8" });
+        entries = stdout.trim().split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    const copied = [];
+    const dirsToExpand = [];
+    const copyToWorktree = async (relativePath) => {
+        const srcPath = path.join(repoRoot, relativePath);
+        const destPath = path.join(worktreePath, relativePath);
+        try {
+            await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+            await fs.promises.copyFile(srcPath, destPath);
+            copied.push(relativePath);
+        }
+        catch (error) {
+            logger.warn(`Failed to copy ${relativePath} into worktree: ${error.message}`);
+        }
+    };
+    for (const entry of entries) {
+        if (isSelf(entry))
+            continue;
+        if (entry.endsWith("/")) {
+            const dir = entry.slice(0, -1);
+            if (worktreeIncludeMatches(patterns, dir, true)) {
+                // The directory itself matches — copy it wholesale
+                try {
+                    await fs.promises.cp(path.join(repoRoot, dir), path.join(worktreePath, dir), {
+                        recursive: true,
+                    });
+                    copied.push(entry);
+                }
+                catch (error) {
+                    logger.warn(`Failed to copy ${entry} into worktree: ${error.message}`);
+                }
+            }
+            else if (needsExpansion(patterns, dir)) {
+                dirsToExpand.push(dir);
+            }
+        }
+        else if (worktreeIncludeMatches(patterns, entry, false)) {
+            await copyToWorktree(entry);
+        }
+    }
+    if (dirsToExpand.length > 0) {
+        // List the files inside collapsed dirs whose contents are targeted
+        try {
+            const { stdout } = await execFileAsync("git", [
+                "ls-files",
+                "--others",
+                "--ignored",
+                "--exclude-standard",
+                "--",
+                ...dirsToExpand,
+            ], { cwd: repoRoot, encoding: "utf8" });
+            for (const file of stdout.trim().split("\n").filter(Boolean)) {
+                if (isSelf(file))
+                    continue;
+                if (worktreeIncludeMatches(patterns, file, false)) {
+                    await copyToWorktree(file);
+                }
+            }
+        }
+        catch {
+            // Expansion is best-effort; the worktree is already usable without it
+        }
+    }
+    return copied;
+}
+/**
+ * Set up a freshly created worktree: copy local settings and gitignored
+ * project files (via .worktreeinclude) from the main repo. Best-effort — any
+ * failure only logs a warning and never fails worktree creation.
+ */
+export async function performPostCreationSetup(worktreePath, repoRoot) {
+    await copyLocalSettingsToWorktree(repoRoot, worktreePath);
+    await copyWorktreeIncludeFiles(repoRoot, worktreePath);
+}
 /**
  * Remove a git worktree and its branch.
  */
@@ -273,6 +560,57 @@ export function removeWorktree(info) {
         throw error;
     }
 }
+/**
+ * Validate that a worktree path is safe to remove before running git removal.
+ * Aligns with Claude Code v2.1.216+ background-session checks:
+ * - rejects a path whose final component is a symlink;
+ * - rejects a path that resolves outside the repo root.
+ *
+ * A path that no longer exists (worktree already removed) is allowed so that
+ * removal stays best-effort/idempotent; its nearest existing ancestor is used
+ * for the containment check. Throws an Error on invalid paths.
+ */
+export function validateWorktreeRemovalPath(worktreePath, repoRoot) {
+    const SYMLINK_PREFIX = "Refusing to remove worktree at symlink path:";
+    // Reject a symlink as the final path component.
+    try {
+        if (fs.lstatSync(worktreePath).isSymbolicLink()) {
+            throw new Error(`${SYMLINK_PREFIX} ${worktreePath}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(SYMLINK_PREFIX)) {
+            throw error;
+        }
+        // lstat failed (path missing) — the containment check below still applies.
+    }
+    const resolvedRepoRoot = fs.realpathSync(repoRoot);
+    // Resolve the path, following symlinks in existing components. If the path
+    // (or a parent) no longer exists, fall back to the deepest existing ancestor
+    // so the containment check still guards against traversal outside the repo.
+    let resolvedPath;
+    let existingAncestor = worktreePath;
+    for (;;) {
+        try {
+            resolvedPath = fs.realpathSync(existingAncestor);
+            break;
+        }
+        catch {
+            const parent = path.dirname(existingAncestor);
+            if (parent === existingAncestor) {
+                throw new Error(`Invalid worktree path for removal: ${worktreePath}`);
+            }
+            existingAncestor = parent;
+        }
+    }
+    if (existingAncestor !== worktreePath) {
+        resolvedPath = path.join(resolvedPath, path.relative(existingAncestor, worktreePath));
+    }
+    const relative = path.relative(resolvedRepoRoot, resolvedPath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`Refusing to remove worktree outside repo root: ${worktreePath}`);
+    }
+}
 /**
  * Count uncommitted files and new commits in a worktree.
  * Returns null if git commands fail (fail-closed).

package/package.json

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

package/src/agent.ts

@@ -95,7 +95,10 @@ export class Agent {
 
   // Dynamic configuration getter methods
   public getGatewayConfig(): GatewayConfig {
-    return this.configurationService.resolveGatewayConfig();
+    return {
+      ...this.configurationService.resolveGatewayConfig(),
+      sessionId: this.messageManager.getSessionId(),
+    };
   }
 
   public getModelConfig(): ModelConfig {
@@ -924,7 +927,9 @@ export class Agent {
           cwd: this.workdir,
           worktreePath,
           env: Object.fromEntries(
-            Object.entries(process.env).filter((e) => e[1] !== undefined),
+            Object.entries(this.configurationService.getMergedEnv()).filter(
+              (e) => e[1] !== undefined,
+            ),
           ) as Record<string, string>,
         },
       );

package/src/index.ts

@@ -29,6 +29,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 

package/src/managers/aiManager.ts

@@ -214,9 +214,27 @@ export class AIManager {
     return this.container.get<ConfigurationService>("ConfigurationService")!;
   }
 
+  /**
+   * OS env merged with the per-session env snapshot. Falls back to process.env
+   * when ConfigurationService is absent or its getMergedEnv is missing (e.g. in
+   * unit tests with partial mocks), so hook-context env construction never
+   * throws. Use this (not the non-null `configurationService` getter) when
+   * building hook context env.
+   */
+  private get mergedEnv(): Record<string, string> {
+    return (
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getMergedEnv?.() ?? (process.env as Record<string, string>)
+    );
+  }
+
   // Getter methods for accessing dynamic configuration
   public getGatewayConfig(): GatewayConfig {
-    return this.configurationService.resolveGatewayConfig();
+    return {
+      ...this.configurationService.resolveGatewayConfig(),
+      sessionId: this.messageManager.getSessionId(),
+    };
   }
 
   public getModelConfig(): ModelConfig {
@@ -1739,7 +1757,7 @@ export class AIManager {
         lastAssistantMessage: lastAssistantText, // Stop/SubagentStop: last assistant message text
         // Stop hooks don't need toolName, toolInput, toolResponse, or userPrompt
         env: Object.fromEntries(
-          Object.entries(process.env).filter((e) => e[1] !== undefined),
+          Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined),
         ) as Record<string, string>, // Include environment variables
       };
 
@@ -1933,7 +1951,7 @@ export class AIManager {
             const sessionId = this.messageManager.getSessionId();
             const transcriptPath = this.messageManager.getTranscriptPath();
             const env = Object.fromEntries(
-              Object.entries(process.env).filter((e) => e[1] !== undefined),
+              Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined),
             ) as Record<string, string>;
             await this.hookManager.executeCwdChangedHooks(
               oldCwd,
@@ -2028,7 +2046,7 @@ export class AIManager {
         toolInput,
         subagentType: this.subagentType, // Include subagent type in hook context
         env: Object.fromEntries(
-          Object.entries(process.env).filter((e) => e[1] !== undefined),
+          Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined),
         ) as Record<string, string>, // Include environment variables
       };
 
@@ -2104,7 +2122,7 @@ export class AIManager {
         subagentType: this.subagentType, // Include subagent type in hook context
         planFilePath: this.permissionManager?.getPlanFilePath(),
         env: Object.fromEntries(
-          Object.entries(process.env).filter((e) => e[1] !== undefined),
+          Object.entries(this.mergedEnv).filter((e) => e[1] !== undefined),
         ) as Record<string, string>, // Include environment variables
       };
 

package/src/managers/backgroundTaskManager.ts

@@ -8,6 +8,7 @@ import { logger } from "../utils/globalLogger.js";
 import { Container } from "../utils/container.js";
 import { MessageQueue } from "./messageQueue.js";
 import { resolveShellPath } from "../utils/shellResolver.js";
+import type { ConfigurationService } from "../services/configurationService.js";
 
 export interface BackgroundTaskManagerCallbacks {
   onBackgroundTasksChange?: (tasks: BackgroundTask[]) => void;
@@ -32,6 +33,19 @@ export class BackgroundTaskManager {
     this.workdir = options.workdir;
   }
 
+  /**
+   * Merged env (OS env overlaid with this session's settings snapshot) for
+   * background-task subprocesses, so settings `env` vars reach them without
+   * polluting other sessions in one `wave --stdio` process.
+   */
+  private get sessionEnv(): Record<string, string> {
+    return (
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getMergedEnv?.() ?? (process.env as Record<string, string>)
+    );
+  }
+
   /**
    * Fire the onBackgroundTasksChange callback so UI consumers refresh.
    * Public so other managers (e.g. WorkflowManager) can trigger a refresh
@@ -73,6 +87,7 @@ export class BackgroundTaskManager {
       cwd: cwd ?? this.workdir,
       env: {
         ...process.env,
+        ...this.sessionEnv,
       },
     });
 

package/src/managers/bangManager.ts

@@ -2,6 +2,7 @@ import { spawn, type ChildProcess } from "child_process";
 import type { MessageManager } from "./messageManager.js";
 import { Container } from "../utils/container.js";
 import { resolveShellPath } from "../utils/shellResolver.js";
+import type { ConfigurationService } from "../services/configurationService.js";
 
 export interface BangManagerOptions {
   workdir: string;
@@ -29,6 +30,19 @@ export class BangManager {
     return this.container.get<MessageManager>("MessageManager")!;
   }
 
+  /**
+   * Merged env (OS env overlaid with this session's settings snapshot) for
+   * bang-command subprocesses, so settings `env` vars reach them without
+   * polluting other sessions in one `wave --stdio` process.
+   */
+  private get sessionEnv(): Record<string, string> {
+    return (
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getMergedEnv?.() ?? (process.env as Record<string, string>)
+    );
+  }
+
   private setCommandRunning(isRunning: boolean): void {
     this.isCommandRunning = isRunning;
     this.onCommandRunningChange?.(isRunning);
@@ -51,6 +65,7 @@ export class BangManager {
         cwd: this.workdir,
         env: {
           ...process.env,
+          ...this.sessionEnv,
         },
       });
 

package/src/managers/hookManager.ts

@@ -13,6 +13,7 @@ import {
   type HookExecutionResult,
   type HookValidationResult,
   type SessionEndSource,
+  type SessionStartSource,
   HookConfigurationError,
   isValidHookEvent,
   isValidHookEventConfig,
@@ -26,6 +27,7 @@ import { executeCommand, isCommandSafe } from "../services/hook.js";
 import { MessageSource } from "../types/index.js";
 import type { MessageManager } from "./messageManager.js";
 import { Container } from "../utils/container.js";
+import type { ConfigurationService } from "../services/configurationService.js";
 
 import { logger } from "../utils/globalLogger.js";
 
@@ -46,6 +48,19 @@ export class HookManager {
     this.matcher = matcher;
   }
 
+  /**
+   * Merged env for this session (OS env overlaid with the per-session settings
+   * snapshot). Hook subprocesses spawn with this env so settings.json `env`
+   * vars reach hooks without polluting other sessions in one stdio process.
+   */
+  private get sessionEnv(): Record<string, string> {
+    return (
+      this.container
+        .get<ConfigurationService>("ConfigurationService")
+        ?.getMergedEnv?.() ?? (process.env as Record<string, string>)
+    );
+  }
+
   /**
    * Load hook configuration from programmatic source (AgentOptions.hooks)
    */
@@ -916,7 +931,7 @@ export class HookManager {
    * Collects additionalContext and initialUserMessage from hook stdout.
    */
   async executeSessionStartHooks(
-    source: "startup" | "compact" | "clear",
+    source: SessionStartSource,
     sessionId: string,
     transcriptPath: string,
     agentType?: string,
@@ -935,7 +950,7 @@ export class HookManager {
       source,
       agentType,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };
 
@@ -989,7 +1004,7 @@ export class HookManager {
       cwd: this.workdir,
       endSource: source,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };
 
@@ -1024,7 +1039,7 @@ export class HookManager {
       cwd: this.workdir,
       compactInstructions: customInstructions,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };
 
@@ -1061,7 +1076,7 @@ export class HookManager {
       cwd: this.workdir,
       compactSummary,
       env: Object.fromEntries(
-        Object.entries(process.env).filter((e) => e[1] !== undefined),
+        Object.entries(this.sessionEnv).filter((e) => e[1] !== undefined),
       ) as Record<string, string>,
     };