wave-agent-sdk 0.19.9 → 1.0.0

package/src/tools/exitWorktreeTool.ts

@@ -162,16 +162,8 @@ export const exitWorktreeTool: ToolPlugin = {
       session.originalHeadCommit,
     ) ?? { changedFiles: 0, commits: 0 };
 
-    removeWorktree(worktreeInfo);
-
-    // Clear session state and restore CWD
-    const aiManager = context.aiManager;
-    if (aiManager) {
-      aiManager.setWorktreeSession(null);
-      aiManager.setWorkdir(originalCwd);
-    }
-
-    // Trigger WorktreeRemove hook (non-blocking)
+    // Trigger WorktreeRemove hook (non-blocking) BEFORE git removal so hooks
+    // can still read files inside the worktree to clean up external resources.
     let hookTriggered = false;
     if (context.hookManager) {
       try {
@@ -182,11 +174,13 @@ export const exitWorktreeTool: ToolPlugin = {
             projectDir: originalCwd,
             timestamp: new Date(),
             sessionId: context.sessionId ?? "",
-            transcriptPath: context.messageManager?.getTranscriptPath() ?? "",
+            transcriptPath: context.messageManager?.getTranscriptPath?.() ?? "",
             cwd: originalCwd,
             worktreePath,
             env: Object.fromEntries(
-              Object.entries(process.env).filter((e) => e[1] !== undefined),
+              Object.entries(context.sessionEnv ?? process.env).filter(
+                (e) => e[1] !== undefined,
+              ),
             ) as Record<string, string>,
           },
         );
@@ -206,6 +200,15 @@ export const exitWorktreeTool: ToolPlugin = {
       }
     }
 
+    removeWorktree(worktreeInfo);
+
+    // Clear session state and restore CWD
+    const aiManager = context.aiManager;
+    if (aiManager) {
+      aiManager.setWorktreeSession(null);
+      aiManager.setWorkdir(originalCwd);
+    }
+
     const discardParts: string[] = [];
     if (summary.commits > 0) {
       discardParts.push(

package/src/tools/types.ts

@@ -127,4 +127,11 @@ export interface ToolContext {
   originalWorkdir?: string;
   /** Workflow manager instance for workflow orchestration */
   workflowManager?: import("../managers/workflowManager.js").WorkflowManager;
+  /**
+   * Per-session merged environment (OS env overlaid with the settings env
+   * snapshot) for this session. Tools that spawn subprocesses (Bash, hooks)
+   * should merge this on top of `process.env` so settings `env` vars reach
+   * the subprocess without polluting other sessions in one stdio process.
+   */
+  sessionEnv?: Record<string, string>;
 }

package/src/types/config.ts

@@ -12,6 +12,8 @@ export interface GatewayConfig {
   defaultHeaders?: Record<string, string>;
   fetchOptions?: OpenAI["fetchOptions"];
   fetch?: OpenAI["fetch"];
+  /** Session identifier, sent as the `x-session-id` request header for backend correlation. */
+  sessionId?: string;
 }
 
 export interface ModelCapabilities {

package/src/types/hooks.ts

@@ -102,9 +102,9 @@ export class HookConfigurationError extends Error {
   }
 }
 
-export type SessionStartSource = "startup" | "compact" | "clear";
+export type SessionStartSource = "startup" | "resume" | "compact" | "clear";
 
-export type SessionEndSource = "exit" | "stop" | "compact" | "clear";
+export type SessionEndSource = "exit" | "resume" | "stop" | "compact" | "clear";
 
 // Type guards for runtime validation
 export function isValidHookEvent(event: string): event is HookEvent {

package/src/utils/containerSetup.ts

@@ -227,7 +227,9 @@ export function setupAgentContainer(
             toolInput: context.toolInput,
             planFilePath: permissionManager.getPlanFilePath(),
             env: Object.fromEntries(
-              Object.entries(process.env).filter((e) => e[1] !== undefined),
+              Object.entries(configurationService.getMergedEnv()).filter(
+                (e) => e[1] !== undefined,
+              ),
             ) as Record<string, string>,
           });
 

package/src/utils/openaiClient.ts

@@ -97,6 +97,7 @@ export class OpenAIClient {
     const {
       baseURL,
       apiKey,
+      sessionId,
       defaultHeaders,
       fetchOptions,
       fetch: customFetch,
@@ -105,6 +106,7 @@ export class OpenAIClient {
     const headers = {
       "Content-Type": "application/json",
       ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      ...(sessionId ? { "x-session-id": sessionId } : {}),
       ...defaultHeaders,
     };
 

package/src/utils/pathEncoder.ts

@@ -212,8 +212,13 @@ export class PathEncoder {
       resolvedPath = absolutePath;
     }
 
-    // Encode the resolved path
-    const encodedName = await this.encode(resolvedPath);
+    // Encode the resolved path. Use encodeSync (pure string transform) rather
+    // than encode(): realpath was already attempted above with its own fallback,
+    // so re-resolving via encode()->resolvePath() would throw ENOENT again when
+    // the workdir no longer exists (e.g. a deleted worktree during agent
+    // shutdown). Session files live under <baseSessionDir>/<encoded>/ regardless
+    // of the workdir's existence, so encoding must not require it to exist.
+    const encodedName = this.encodeSync(resolvedPath);
     const encodedPath = join(baseSessionDir, encodedName);
 
     // Generate hash if encoding resulted in truncation

package/src/utils/worktreeUtils.ts

@@ -3,7 +3,8 @@
  * 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 {
@@ -13,6 +14,11 @@ import {
 } 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);
+
 export interface WorktreeInfo {
   name: string;
   path: string;
@@ -266,6 +272,338 @@ export function createWorktree(
   }
 }
 
+// --- .worktreeinclude matching ----------------------------------------------
+
+interface WorktreeIncludePattern {
+  /** Normalized pattern text (no leading "/", no trailing "/", no "!") */
+  raw: string;
+  negated: boolean;
+  /** Pattern ends with "/" — matches directories only */
+  dirOnly: boolean;
+  /** Pattern had a leading "/" — anchored to the repo root */
+  anchored: boolean;
+  /** No "/" and not anchored — matches the basename at any level */
+  anyLevel: boolean;
+  regex: RegExp;
+}
+
+/** Translate a single gitignore glob into a RegExp (gitignore semantics). */
+function globToRegExp(glob: string): RegExp {
+  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: string,
+): WorktreeIncludePattern[] {
+  const patterns: WorktreeIncludePattern[] = [];
+  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: WorktreeIncludePattern,
+  candidate: string,
+): boolean {
+  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: WorktreeIncludePattern,
+  relPath: string,
+  isDir: boolean,
+): boolean {
+  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: WorktreeIncludePattern[],
+  relPath: string,
+  isDir: boolean,
+): boolean {
+  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: WorktreeIncludePattern[],
+  dir: string,
+): boolean {
+  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: string,
+  worktreePath: string,
+): Promise<void> {
+  const relativePath = path.join(".wave", "settings.local.json");
+  const sourcePath = path.join(repoRoot, relativePath);
+  const destPath = path.join(worktreePath, relativePath);
+  let content: string;
+  try {
+    content = await fs.promises.readFile(sourcePath, "utf8");
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      logger.warn(`Failed to read ${sourcePath}: ${(error as Error).message}`);
+    }
+    return;
+  }
+  try {
+    await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+    await fs.promises.writeFile(destPath, content);
+  } catch (error: unknown) {
+    logger.warn(
+      `Failed to copy ${relativePath} into worktree: ${(error as 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: string,
+  worktreePath: string,
+): Promise<string[]> {
+  const includePath = path.join(repoRoot, ".worktreeinclude");
+  let content: string;
+  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: string) =>
+    entry === worktreeRelPath || entry.startsWith(worktreeRelPath + "/");
+
+  // "--directory" collapses fully-ignored directories into single entries,
+  // which keeps the listing fast on large repos.
+  let entries: string[];
+  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: string[] = [];
+  const dirsToExpand: string[] = [];
+
+  const copyToWorktree = async (relativePath: string): Promise<void> => {
+    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: unknown) {
+      logger.warn(
+        `Failed to copy ${relativePath} into worktree: ${(error as 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: unknown) {
+          logger.warn(
+            `Failed to copy ${entry} into worktree: ${(error as 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: string,
+  repoRoot: string,
+): Promise<void> {
+  await copyLocalSettingsToWorktree(repoRoot, worktreePath);
+  await copyWorktreeIncludeFiles(repoRoot, worktreePath);
+}
+
 /**
  * Remove a git worktree and its branch.
  */
@@ -338,6 +676,68 @@ export function removeWorktree(info: WorktreeInfo): void {
   }
 }
 
+/**
+ * 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: string,
+  repoRoot: string,
+): void {
+  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: unknown) {
+    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: string;
+  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).