wave-agent-sdk 1.0.10 → 1.1.0

package/dist/utils/asyncWorkRegistry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Registry of live async work that must drain before the agent is destroyed.
+ *
+ * Fire-and-forget work (dispatch, background subagents, fork subagents)
+ * registers its promise here so destroy() can wait deterministically instead
+ * of silently abandoning it (the "ghost work" class of #1808). The registry
+ * swallows rejections so an unregistered fire-and-forget caller can't turn a
+ * settled-then-removed promise into an unhandled rejection.
+ */
+export declare class AsyncWorkRegistry {
+    private readonly drainTimeoutMs;
+    private work;
+    private waiters;
+    constructor(drainTimeoutMs?: number);
+    get size(): number;
+    isEmpty(): boolean;
+    /**
+     * Register a promise as live work. The promise is removed when it settles
+     * (fulfilled or rejected); rejections are consumed here so tracking never
+     * produces an unhandled rejection. Returns the original promise unchanged
+     * so the caller can still await it.
+     */
+    track<T>(promise: Promise<T>): Promise<T>;
+    private remove;
+    /**
+     * Wait until the registry is empty, or until the timeout elapses. Loops
+     * until empty: work registered after an await point is still drained.
+     * Returns true if drained, false on timeout (leftover work is no longer
+     * lifecycle-managed).
+     */
+    drain(timeoutMs?: number): Promise<boolean>;
+}

package/dist/utils/asyncWorkRegistry.js

@@ -0,0 +1,81 @@
+/**
+ * Registry of live async work that must drain before the agent is destroyed.
+ *
+ * Fire-and-forget work (dispatch, background subagents, fork subagents)
+ * registers its promise here so destroy() can wait deterministically instead
+ * of silently abandoning it (the "ghost work" class of #1808). The registry
+ * swallows rejections so an unregistered fire-and-forget caller can't turn a
+ * settled-then-removed promise into an unhandled rejection.
+ */
+export class AsyncWorkRegistry {
+    constructor(drainTimeoutMs = 10000) {
+        this.drainTimeoutMs = drainTimeoutMs;
+        this.work = new Set();
+        this.waiters = [];
+    }
+    get size() {
+        return this.work.size;
+    }
+    isEmpty() {
+        return this.work.size === 0;
+    }
+    /**
+     * Register a promise as live work. The promise is removed when it settles
+     * (fulfilled or rejected); rejections are consumed here so tracking never
+     * produces an unhandled rejection. Returns the original promise unchanged
+     * so the caller can still await it.
+     */
+    track(promise) {
+        this.work.add(promise);
+        promise.then(() => this.remove(promise), () => this.remove(promise));
+        return promise;
+    }
+    remove(promise) {
+        this.work.delete(promise);
+        if (this.work.size === 0) {
+            const waiters = this.waiters;
+            this.waiters = [];
+            for (const resolve of waiters) {
+                resolve();
+            }
+        }
+    }
+    /**
+     * Wait until the registry is empty, or until the timeout elapses. Loops
+     * until empty: work registered after an await point is still drained.
+     * Returns true if drained, false on timeout (leftover work is no longer
+     * lifecycle-managed).
+     */
+    async drain(timeoutMs = this.drainTimeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (this.work.size > 0) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                return false;
+            }
+            // Wait for the registry to empty, or for the timeout — whichever comes
+            // first (a tracked promise may never settle).
+            let waiter;
+            const notified = new Promise((resolve) => {
+                waiter = resolve;
+                this.waiters.push(resolve);
+            });
+            let timer;
+            const timedOut = new Promise((resolve) => {
+                timer = setTimeout(resolve, remaining);
+            });
+            await Promise.race([notified, timedOut]);
+            if (timer)
+                clearTimeout(timer);
+            // If the timer won, the work set is still non-empty: drop our waiter so
+            // a later drain isn't woken by a stale notification. If notified won,
+            // remove() already cleared the waiters array.
+            if (waiter && this.work.size > 0) {
+                const idx = this.waiters.indexOf(waiter);
+                if (idx >= 0)
+                    this.waiters.splice(idx, 1);
+            }
+        }
+        return true;
+    }
+}

package/dist/utils/containerSetup.js

@@ -27,6 +27,7 @@ import { MemoryService } from "../services/memory.js";
 import { AutoMemoryService } from "../services/autoMemoryService.js";
 import { USER_MEMORY_FILE } from "./constants.js";
 import { getGitMainRepoRoot } from "./gitUtils.js";
+import { AsyncWorkRegistry } from "./asyncWorkRegistry.js";
 import { logger } from "./globalLogger.js";
 import { authService } from "../services/authService.js";
 import { remoteSettingsService } from "../services/remoteSettingsService.js";
@@ -45,6 +46,10 @@ export function setupAgentContainer(setupOptions) {
     container.register("WorktreeSession", null);
     const messageQueue = new MessageQueue();
     container.register("MessageQueue", messageQueue);
+    // Registry of live async work that must drain before the agent is destroyed
+    // (dispatch, background subagents, fork subagents — the fire-and-forget work
+    // sites). destroy() awaits its drain() so no async work can outlive the agent.
+    container.register("AsyncWorkRegistry", new AsyncWorkRegistry());
     const foregroundTaskManager = new ForegroundTaskManager(container);
     container.register("ForegroundTaskManager", foregroundTaskManager);
     container.register("ConfigurationService", configurationService);

package/dist/utils/skillParser.js

@@ -147,7 +147,6 @@ export function validateSkillMetadata(metadata) {
     // Import SKILL_DEFAULTS dynamically to avoid circular imports
     const NAME_PATTERN = /^[a-z0-9-]+$/;
     const MAX_NAME_LENGTH = 64;
-    const MAX_DESCRIPTION_LENGTH = 1024;
     const MIN_DESCRIPTION_LENGTH = 1;
     // Validate name
     if (!metadata.name) {
@@ -161,7 +160,8 @@ export function validateSkillMetadata(metadata) {
             errors.push("Skill name must contain only lowercase letters, numbers, and hyphens");
         }
     }
-    // Validate description
+    // Validate description (no length limit, aligned with Claude Code which
+    // truncates long descriptions at render time instead of rejecting the skill)
     if (!metadata.description) {
         errors.push("Skill description is required");
     }
@@ -169,9 +169,6 @@ export function validateSkillMetadata(metadata) {
         if (metadata.description.length < MIN_DESCRIPTION_LENGTH) {
             errors.push(`Skill description must be at least ${MIN_DESCRIPTION_LENGTH} character`);
         }
-        if (metadata.description.length > MAX_DESCRIPTION_LENGTH) {
-            errors.push(`Skill description must be ${MAX_DESCRIPTION_LENGTH} characters or less`);
-        }
     }
     return errors;
 }
@@ -194,7 +191,7 @@ export function formatSkillError(skillPath, errors) {
         "  1. Ensure SKILL.md has valid YAML frontmatter (---...---)",
         "  2. Include required fields: name and description",
         "  3. Use lowercase letters, numbers, and hyphens only for name",
-        "  4. Keep name under 64 characters and description under 1024 characters",
+        "  4. Keep name under 64 characters",
     ].join("\n");
     return `${header}\n${errorList}\n\n${suggestions}`;
 }

package/dist/utils/windowsPaths.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Windows path conversion utilities for Git Bash (POSIX shell) execution.
+ *
+ * Hook commands on Windows are executed via Git Bash instead of cmd.exe
+ * (cmd.exe does not strip quotes from arguments after the first token, so
+ * `node "C:\path\script.js"` silently fails — see issue #1773). Git Bash
+ * cannot resolve Windows paths like `C:\Users\foo`: backslashes are treated
+ * as escape characters and the drive letter breaks POSIX semantics. These
+ * helpers convert Windows paths to the POSIX form Git Bash expects
+ * (`C:\Users\foo` → `/c/Users/foo`), matching Claude Code's
+ * `windowsPathToPosixPath`.
+ */
+/**
+ * Convert a single Windows path to POSIX form for Git Bash:
+ *   - `C:\Users\foo`  → `/c/Users/foo`
+ *   - `C:/Users/foo`  → `/c/Users/foo`
+ *   - `\\server\share` → `//server/share` (UNC preserved)
+ *   - Already POSIX or relative paths are returned with slashes flipped.
+ */
+export declare function windowsPathToPosixPath(p: string): string;
+/**
+ * Convert every Windows absolute path inside a shell command string to POSIX
+ * form so Git Bash can parse it. Handles both quoted paths (which may contain
+ * spaces, e.g. `node "C:\Program Files\script.js"`) and bare paths
+ * (`cd C:\path\x`). Drive letters preceded by another alphanumeric character
+ * (e.g. URLs like `http://`) are left untouched.
+ */
+export declare function toPosixCommand(command: string): string;

package/dist/utils/windowsPaths.js

@@ -0,0 +1,47 @@
+/**
+ * Windows path conversion utilities for Git Bash (POSIX shell) execution.
+ *
+ * Hook commands on Windows are executed via Git Bash instead of cmd.exe
+ * (cmd.exe does not strip quotes from arguments after the first token, so
+ * `node "C:\path\script.js"` silently fails — see issue #1773). Git Bash
+ * cannot resolve Windows paths like `C:\Users\foo`: backslashes are treated
+ * as escape characters and the drive letter breaks POSIX semantics. These
+ * helpers convert Windows paths to the POSIX form Git Bash expects
+ * (`C:\Users\foo` → `/c/Users/foo`), matching Claude Code's
+ * `windowsPathToPosixPath`.
+ */
+/**
+ * Convert a single Windows path to POSIX form for Git Bash:
+ *   - `C:\Users\foo`  → `/c/Users/foo`
+ *   - `C:/Users/foo`  → `/c/Users/foo`
+ *   - `\\server\share` → `//server/share` (UNC preserved)
+ *   - Already POSIX or relative paths are returned with slashes flipped.
+ */
+export function windowsPathToPosixPath(p) {
+    // UNC paths: \\server\share -> //server/share
+    if (p.startsWith("\\\\")) {
+        return p.replace(/\\/g, "/");
+    }
+    // Drive letter paths: C:\Users\foo -> /c/Users/foo
+    const match = p.match(/^([A-Za-z]):[\\/]/);
+    if (match) {
+        const driveLetter = match[1].toLowerCase();
+        return `/${driveLetter}${p.slice(2).replace(/\\/g, "/")}`;
+    }
+    // Already POSIX or relative — just flip slashes
+    return p.replace(/\\/g, "/");
+}
+/**
+ * Convert every Windows absolute path inside a shell command string to POSIX
+ * form so Git Bash can parse it. Handles both quoted paths (which may contain
+ * spaces, e.g. `node "C:\Program Files\script.js"`) and bare paths
+ * (`cd C:\path\x`). Drive letters preceded by another alphanumeric character
+ * (e.g. URLs like `http://`) are left untouched.
+ */
+export function toPosixCommand(command) {
+    // Quoted paths first (may contain spaces) — keep the surrounding quotes.
+    let converted = command.replace(/"([A-Za-z]):[\\/][^"]*"/g, (quoted) => `"${windowsPathToPosixPath(quoted.slice(1, -1))}"`);
+    // Bare (unquoted) paths.
+    converted = converted.replace(/(?<![A-Za-z0-9])([A-Za-z]):[\\/][^\s"']*/g, (match) => windowsPathToPosixPath(match));
+    return converted;
+}

package/dist/utils/worktreeSession.d.ts

@@ -22,4 +22,10 @@ export interface WorktreeSession {
     repoRoot: string;
     /** The HEAD commit of the original branch at worktree creation time */
     originalHeadCommit?: string;
+    /**
+     * True when this worktree was created by a WorktreeCreate hook (not by git).
+     * Deletion delegates to the WorktreeRemove hook; wave never runs
+     * `git worktree remove` for hook-based worktrees (aligned with Claude Code).
+     */
+    hookBased?: boolean;
 }

package/dist/utils/worktreeUtils.d.ts

@@ -41,6 +41,13 @@ export declare function createWorktree(name: string, cwd: string, options?: {
 export declare function performPostCreationSetup(worktreePath: string, repoRoot: string): Promise<void>;
 /**
  * Remove a git worktree and its branch.
+ *
+ * Removal is best-effort: `git worktree remove --force` deletes the worktree
+ * metadata before the working directory, and on Windows its recursive deletion
+ * is MAX_PATH-limited — deep paths (e.g. node_modules) can fail with "Filename
+ * too long", leaving an orphan directory. When git fails we fall back to
+ * fs.rmSync with an extended-length path (bypasses MAX_PATH) and prune stale
+ * metadata. Failures are logged but never block branch deletion.
  */
 export declare function removeWorktree(info: WorktreeInfo): void;
 /**

package/dist/utils/worktreeUtils.js

@@ -498,32 +498,77 @@ export async function performPostCreationSetup(worktreePath, repoRoot) {
     await copyLocalSettingsToWorktree(repoRoot, worktreePath);
     await copyWorktreeIncludeFiles(repoRoot, worktreePath);
 }
+/**
+ * On Windows, prefix an absolute path with the extended-length marker (`\\?\`)
+ * so recursive removal bypasses the 260-char MAX_PATH limit. POSIX paths are
+ * returned unchanged.
+ */
+function toExtendedLengthPath(worktreePath) {
+    if (process.platform !== "win32") {
+        return worktreePath;
+    }
+    const absolute = path.win32.resolve(worktreePath);
+    if (absolute.startsWith("\\\\?\\")) {
+        return absolute;
+    }
+    if (absolute.startsWith("\\\\")) {
+        // UNC path: \\server\share -> \\?\UNC\server\share
+        return `\\\\?\\UNC\\${absolute.slice(2)}`;
+    }
+    return `\\\\?\\${absolute}`;
+}
 /**
  * Remove a git worktree and its branch.
+ *
+ * Removal is best-effort: `git worktree remove --force` deletes the worktree
+ * metadata before the working directory, and on Windows its recursive deletion
+ * is MAX_PATH-limited — deep paths (e.g. node_modules) can fail with "Filename
+ * too long", leaving an orphan directory. When git fails we fall back to
+ * fs.rmSync with an extended-length path (bypasses MAX_PATH) and prune stale
+ * metadata. Failures are logged but never block branch deletion.
  */
 export function removeWorktree(info) {
     const repoRoot = info.repoRoot;
+    // Get current branch in worktree before removing
+    let currentBranch;
+    try {
+        currentBranch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: info.path,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        // Ignore errors
+    }
+    // Remove worktree
     try {
-        // Get current branch in worktree before removing
-        let currentBranch;
-        try {
-            currentBranch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
-                cwd: info.path,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "ignore"],
-            }).trim();
-        }
-        catch {
-            // Ignore errors
-        }
-        // Remove worktree
         execFileSync("git", ["worktree", "remove", "--force", info.path], {
             cwd: repoRoot,
             stdio: ["ignore", "pipe", "pipe"],
         });
-        // Delete worktree branch
+    }
+    catch (error) {
+        logger.warn("git worktree remove failed, falling back to fs.rmSync:", {
+            error: error instanceof Error ? error.message : String(error),
+            worktreePath: info.path,
+        });
+        try {
+            fs.rmSync(toExtendedLengthPath(info.path), {
+                recursive: true,
+                force: true,
+            });
+        }
+        catch (rmError) {
+            logger.error("Failed to remove worktree or branch:", {
+                error: rmError instanceof Error ? rmError.message : String(rmError),
+                worktreePath: info.path,
+            });
+        }
+        // git removes worktree metadata before the working directory; prune any
+        // leftovers in case git failed before deleting them.
         try {
-            execFileSync("git", ["branch", "-D", info.branch], {
+            execFileSync("git", ["worktree", "prune"], {
                 cwd: repoRoot,
                 stdio: ["ignore", "pipe", "pipe"],
             });
@@ -531,33 +576,36 @@ export function removeWorktree(info) {
         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 {
-                    execFileSync("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,
+    // Delete worktree branch
+    try {
+        execFileSync("git", ["branch", "-D", info.branch], {
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
         });
-        throw error;
+    }
+    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 {
+                execFileSync("git", ["branch", "-D", currentBranch], {
+                    cwd: repoRoot,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+            }
+            catch {
+                // Ignore errors
+            }
+        }
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "1.0.10",
+  "version": "1.1.0",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",
@@ -63,11 +63,10 @@
     "@vitest/coverage-v8": "^4.1.7",
     "rimraf": "^6.1.2",
     "tsc-alias": "^1.8.16",
-    "tsx": "^4.20.4",
     "vitest": "^4.1.7"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "license": "MIT",
   "scripts": {
@@ -76,6 +75,9 @@
     "watch": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --watch",
     "test": "vitest run --reporter=dot",
     "test:coverage": "vitest run --coverage --reporter=dot",
+    "test:unit": "vitest run --reporter=dot --exclude 'tests/integration/**' --exclude '**/*.integration.test.ts'",
+    "test:unit:coverage": "vitest run --coverage --reporter=dot --exclude 'tests/integration/**' --exclude '**/*.integration.test.ts'",
+    "test:integration": "vitest run --reporter=dot tests/integration .integration.test",
     "lint": "eslint --cache",
     "format": "prettier --write ."
   }