wave-agent-sdk 1.1.4 → 1.2.0

package/dist/utils/containerSetup.d.ts

@@ -16,4 +16,14 @@ export interface AgentContainerSetupOptions {
     addPermissionRule: (rule: string) => Promise<void>;
     addUsage: (usage: Usage) => void;
 }
-export declare function setupAgentContainer(setupOptions: AgentContainerSetupOptions): Container;
+export interface AgentContainerSetupResult {
+    container: Container;
+    /**
+     * Unregister module-level listeners registered during setup (remote settings
+     * hot-update, auth change). Must be called when the agent is destroyed;
+     * without it the module-level callback arrays pin the agent's object graph
+     * (the callback closures capture per-agent managers).
+     */
+    teardown: () => void;
+}
+export declare function setupAgentContainer(setupOptions: AgentContainerSetupOptions): AgentContainerSetupResult;

package/dist/utils/containerSetup.js

@@ -14,7 +14,7 @@ import { HookManager } from "../managers/hookManager.js";
 import { SkillManager } from "../managers/skillManager.js";
 import { SlashCommandManager } from "../managers/slashCommandManager.js";
 import { PluginManager } from "../managers/pluginManager.js";
-import { BangManager } from "../managers/bangManager.js";
+import { BashModeManager } from "../managers/bashModeManager.js";
 import { CronManager } from "../managers/cronManager.js";
 import { WorkflowManager } from "../managers/workflowManager.js";
 import { MemoryRuleManager } from "../managers/MemoryRuleManager.js";
@@ -38,6 +38,12 @@ export function setupAgentContainer(setupOptions) {
     const container = new Container();
     container.register("AgentOptions", options);
     container.register("Workdir", workdir);
+    // Module-level listener teardowns collected during setup and returned to the
+    // agent, which invokes them in destroy(). The remote-settings callback
+    // strongly captures the per-agent LiveConfigManager: without unsubscribing
+    // it in destroy(), the module-level callback array keeps every created
+    // agent's object graph alive even after the host drops its references.
+    const teardowns = [];
     if (options.worktreeName) {
         container.register("WorktreeName", options.worktreeName);
         container.register("MainRepoRoot", getGitMainRepoRoot(workdir));
@@ -107,14 +113,14 @@ export function setupAgentContainer(setupOptions) {
     });
     container.register("McpManager", mcpManager);
     // Wire up auth change callback to refresh/clear remote settings
-    authService.onAuthChange(async (event) => {
+    teardowns.push(authService.onAuthChange(async (event) => {
         if (event === "login") {
             await remoteSettingsService.refresh();
         }
         else if (event === "logout") {
             remoteSettingsService.clear();
         }
-    });
+    }));
     const lspManager = options.lspManager || new LspManager(container);
     container.register("LspManager", lspManager);
     const permissionManager = new PermissionManager(container, {
@@ -234,9 +240,8 @@ export function setupAgentContainer(setupOptions) {
             // Same gate for the builtin /artifact skill: refresh emits "refreshed"
             // so slash-command registration follows enableArtifact. Awaited (via the
             // awaited onReload) so skills are re-populated before Agent.create()
-            // returns — reloadFeatureGatedSkills() clears the skill map before
-            // rediscovering asynchronously, which would otherwise expose an empty
-            // skill list to callers right after create().
+            // returns — otherwise callers right after create() could observe a
+            // mid-refresh skill list.
             await skillManager.reloadFeatureGatedSkills().catch((error) => {
                 logger.error("Failed to reload feature-gated skills:", error);
             });
@@ -245,9 +250,12 @@ export function setupAgentContainer(setupOptions) {
     container.register("LiveConfigManager", liveConfigManager);
     // Wire up remote settings hot-update: when polling detects changed settings,
     // reload configuration so admin changes propagate to the running agent.
-    remoteSettingsService.onSettingsUpdate(async () => {
+    // The callback strongly captures the per-agent LiveConfigManager, so it MUST
+    // be unsubscribed in destroy() via teardown — otherwise the module-level
+    // callback array pins the whole agent object graph.
+    teardowns.push(remoteSettingsService.onSettingsUpdate(async () => {
         await liveConfigManager.reload();
-    });
+    }));
     const subagentManager = new SubagentManager(container, {
         workdir,
         callbacks: {
@@ -280,12 +288,19 @@ export function setupAgentContainer(setupOptions) {
     slashCommandManager.initialize();
     const pluginManager = new PluginManager(container, { workdir });
     container.register("PluginManager", pluginManager);
-    const bangManager = new BangManager(container, { workdir });
-    container.register("BangManager", bangManager);
+    const bashModeManager = new BashModeManager(container, { workdir });
+    container.register("BashModeManager", bashModeManager);
     const cronManager = new CronManager(container, messageManager.getSessionId());
     container.register("CronManager", cronManager);
     cronManager.start();
     const workflowManager = new WorkflowManager(container);
     container.register("WorkflowManager", workflowManager);
-    return container;
+    return {
+        container,
+        teardown: () => {
+            for (const unsubscribe of teardowns) {
+                unsubscribe();
+            }
+        },
+    };
 }

package/dist/utils/fileUtils.d.ts

@@ -26,6 +26,17 @@ export declare function readFirstNLines(filePath: string, maxLines: number): Pro
  * @return {Promise<string>} - The last non-empty line of the file, or an empty string if no non-empty lines found.
  */
 export declare function getLastLine(filePath: string, minLength?: number): Promise<string>;
+/**
+ * Read up to `maxBytes` from the end of a file and return the lines it holds,
+ * oldest first. The window may start in the middle of a line, in which case
+ * that partial first line is dropped so every returned line is complete —
+ * callers parse them as JSON.
+ *
+ * @param {string} filePath - The path to the file.
+ * @param {number} maxBytes - Size of the tail window (default 64KB).
+ * @return {Promise<string[]>} - Trailing non-empty lines, or [] if unreadable.
+ */
+export declare function readTailLines(filePath: string, maxBytes?: number): Promise<string[]>;
 /**
  * Suggests similar paths if a file is not found.
  */

package/dist/utils/fileUtils.js

@@ -136,6 +136,43 @@ export async function getLastLine(filePath, minLength = 1) {
         }
     }
 }
+/**
+ * Read up to `maxBytes` from the end of a file and return the lines it holds,
+ * oldest first. The window may start in the middle of a line, in which case
+ * that partial first line is dropped so every returned line is complete —
+ * callers parse them as JSON.
+ *
+ * @param {string} filePath - The path to the file.
+ * @param {number} maxBytes - Size of the tail window (default 64KB).
+ * @return {Promise<string[]>} - Trailing non-empty lines, or [] if unreadable.
+ */
+export async function readTailLines(filePath, maxBytes = 64 * 1024) {
+    let fileHandle;
+    try {
+        const stats = await fs.stat(filePath);
+        const fileSize = stats.size;
+        if (fileSize === 0)
+            return [];
+        const readSize = Math.min(maxBytes, fileSize);
+        const start = fileSize - readSize;
+        fileHandle = await fs.open(filePath, "r");
+        const buffer = Buffer.alloc(readSize);
+        const { bytesRead } = await fileHandle.read(buffer, 0, readSize, start);
+        const lines = buffer.subarray(0, bytesRead).toString("utf8").split("\n");
+        if (start > 0)
+            lines.shift(); // partial line (window began mid-line)
+        return lines.map((line) => line.trim()).filter((line) => line !== "");
+    }
+    catch {
+        // Unreadable file (missing, permissions, race with deletion): no tail.
+        return [];
+    }
+    finally {
+        if (fileHandle) {
+            await fileHandle.close();
+        }
+    }
+}
 /**
  * Simple Levenshtein distance implementation
  */

package/dist/utils/messageOperations.d.ts

@@ -54,21 +54,6 @@ export interface AddErrorBlockParams {
     messages: Message[];
     error: string;
 }
-export interface AddBangParams {
-    messages: Message[];
-    command: string;
-}
-export interface UpdateBangParams {
-    messages: Message[];
-    command: string;
-    output: string;
-}
-export interface CompleteBangParams {
-    messages: Message[];
-    command: string;
-    exitCode: number;
-    output?: string;
-}
 /**
  * Convert image file path to base64 format
  * @param imagePath Image file path
@@ -94,9 +79,6 @@ export declare const updateToolBlockInMessage: ({ messages, id, messageId, param
     messageId?: string;
 };
 export declare const addErrorBlockToMessage: ({ messages, error, }: AddErrorBlockParams) => Message[];
-export declare const addBangMessage: ({ messages, command, }: AddBangParams) => Message[];
-export declare const updateBangInMessage: ({ messages, command, output, }: UpdateBangParams) => Message[];
-export declare const completeBangInMessage: ({ messages, command, exitCode, output, }: CompleteBangParams) => Message[];
 /**
  * Helper to count tool blocks in messages
  */

package/dist/utils/messageOperations.js

@@ -304,64 +304,6 @@ export const addErrorBlockToMessage = ({ messages, error, }) => {
     }
     return newMessages;
 };
-// Add bang block to message list
-export const addBangMessage = ({ messages, command, }) => {
-    const outputMessage = {
-        id: generateMessageId(),
-        role: "user",
-        blocks: [
-            {
-                type: "bang",
-                command,
-                output: "",
-                stage: "running",
-                exitCode: null,
-            },
-        ],
-        timestamp: new Date().toISOString(),
-    };
-    return [...messages, outputMessage];
-};
-// Update output content of bang block
-export const updateBangInMessage = ({ messages, command, output, }) => {
-    const newMessages = [...messages];
-    // Find the last user message with a bang block for this command
-    for (let i = newMessages.length - 1; i >= 0; i--) {
-        const msg = newMessages[i];
-        if (msg.role === "user") {
-            const commandBlock = msg.blocks.find((block) => block.type === "bang" &&
-                block.command === command &&
-                block.stage === "running");
-            if (commandBlock && commandBlock.type === "bang") {
-                commandBlock.output = output.trim();
-                break;
-            }
-        }
-    }
-    return newMessages;
-};
-// Complete bang execution, update exit status
-export const completeBangInMessage = ({ messages, command, exitCode, output, }) => {
-    const newMessages = [...messages];
-    // Find the last user message with a bang block for this command
-    for (let i = newMessages.length - 1; i >= 0; i--) {
-        const msg = newMessages[i];
-        if (msg.role === "user") {
-            const commandBlock = msg.blocks.find((block) => block.type === "bang" &&
-                block.command === command &&
-                block.stage === "running");
-            if (commandBlock && commandBlock.type === "bang") {
-                commandBlock.stage = "end";
-                commandBlock.exitCode = exitCode;
-                if (output !== undefined) {
-                    commandBlock.output = output.trim();
-                }
-                break;
-            }
-        }
-    }
-    return newMessages;
-};
 /**
  * Helper to count tool blocks in messages
  */
@@ -458,10 +400,6 @@ export function getMessageContent(message) {
     if (textBlock && "content" in textBlock) {
         return textBlock.content;
     }
-    const bangBlock = message.blocks.find((block) => block.type === "bang");
-    if (bangBlock && "command" in bangBlock) {
-        return `!${bangBlock.command}`;
-    }
     const compactBlock = message.blocks.find((block) => block.type === "compact");
     if (compactBlock && "content" in compactBlock) {
         return compactBlock.content;

package/dist/utils/subagentParser.js

@@ -1,4 +1,5 @@
 import { readFileSync, readdirSync, statSync } from "fs";
+import { homedir } from "os";
 import { join, extname, basename } from "path";
 import { logger } from "./globalLogger.js";
 import { getBuiltinSubagentsDir } from "./configPaths.js";
@@ -165,8 +166,14 @@ function scanSubagentDirectory(dirPath, scope) {
 export async function loadSubagentConfigurations(workdir, env = process.env) {
     const projectWaveDir = join(workdir, ".wave", "agents");
     const projectClaudeDir = join(workdir, ".claude", "agents");
-    const userWaveDir = join(process.env.HOME || "~", ".wave", "agents");
-    const userClaudeDir = join(process.env.HOME || "~", ".claude", "agents");
+    // Resolve user-level dirs via os.homedir() (NOT process.env.HOME): every
+    // other user-path resolver in the SDK (settings, skills, MCP, rules, ~/
+    // expansion in the Write tool) uses os.homedir(), which on Windows falls
+    // back to USERPROFILE. Windows GUI-launched processes (Electron desktop)
+    // typically have no HOME set, so process.env.HOME made user-level subagents
+    // silently invisible there (`~/.wave/agents` resolved as a relative path).
+    const userWaveDir = join(homedir(), ".wave", "agents");
+    const userClaudeDir = join(homedir(), ".claude", "agents");
     const builtinDir = getBuiltinSubagentsDir();
     // Load configurations from all sources
     let builtinConfigs = scanSubagentDirectory(builtinDir, "builtin");

package/dist/utils/tokenCalculation.js

@@ -62,14 +62,6 @@ export function roughTokenCountForMessages(messages) {
                         total += estimateTokens(block.result);
                     }
                     break;
-                case "bang":
-                    if (block.command) {
-                        total += estimateTokens(block.command);
-                    }
-                    if (block.output) {
-                        total += estimateTokens(block.output);
-                    }
-                    break;
                 case "task_notification":
                     total += estimateTokens(block.summary);
                     break;

package/dist/utils/worktreeUtils.d.ts

@@ -47,7 +47,8 @@ export declare function performPostCreationSetup(worktreePath: string, repoRoot:
  * 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.
+ * metadata. Failures are logged; when the directory survives, its branch is
+ * deliberately kept so the leftover checkout stays reachable through git.
  */
 export declare function removeWorktree(info: WorktreeInfo): void;
 /**

package/dist/utils/worktreeUtils.js

@@ -517,6 +517,36 @@ function toExtendedLengthPath(worktreePath) {
     }
     return `\\\\?\\${absolute}`;
 }
+/**
+ * Describe what is still on disk after a failed removal. Without this a log
+ * line cannot distinguish "directory already gone" from "the whole checkout is
+ * still sitting there".
+ */
+function probeResidue(worktreePath) {
+    try {
+        if (!fs.existsSync(worktreePath))
+            return "none";
+        const entries = fs.readdirSync(worktreePath);
+        const head = entries.slice(0, 5).join(",");
+        return `${entries.length}[${head}${entries.length > 5 ? ",…" : ""}]`;
+    }
+    catch (error) {
+        return `unknown(${error.code ?? "error"})`;
+    }
+}
+/** Delete the worktree directory with fs.rmSync; returns the error, if any. */
+function rmWorktreeDirWithFs(worktreePath) {
+    try {
+        fs.rmSync(toExtendedLengthPath(worktreePath), {
+            recursive: true,
+            force: true,
+        });
+        return null;
+    }
+    catch (error) {
+        return error;
+    }
+}
 /**
  * Remove a git worktree and its branch.
  *
@@ -525,28 +555,36 @@ function toExtendedLengthPath(worktreePath) {
  * 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.
+ * metadata. Failures are logged; when the directory survives, its branch is
+ * deliberately kept so the leftover checkout stays reachable through git.
  */
 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 {
         execFileSync("git", ["worktree", "remove", "--force", info.path], {
             cwd: repoRoot,
             stdio: ["ignore", "pipe", "pipe"],
         });
+        // git exits 0 even when it did not delete the directory: on Windows it
+        // cannot remove the directory symlinks/junctions that pnpm's node_modules
+        // is made of, so it deletes the files, leaves the skeleton behind and still
+        // reports success. Verify on disk instead of trusting the exit status.
+        if (fs.existsSync(info.path)) {
+            logger.warn("git worktree remove reported success but the directory survived, falling back to fs.rmSync:", {
+                worktreePath: info.path,
+                residue: probeResidue(info.path),
+            });
+            const rmError = rmWorktreeDirWithFs(info.path);
+            if (rmError !== null) {
+                logger.error("Failed to remove worktree or branch:", {
+                    worktreePath: info.path,
+                    stage: "fs(after git success)",
+                    error: rmError instanceof Error ? rmError.message : String(rmError),
+                    residue: probeResidue(info.path),
+                });
+            }
+        }
     }
     catch (error) {
         logger.warn("git worktree remove failed, falling back to fs.rmSync:", {
@@ -577,7 +615,19 @@ export function removeWorktree(info) {
             // Ignore errors
         }
     }
-    // Delete worktree branch
+    // The directory, not any exit code, decides whether the removal happened. A
+    // surviving directory means its checkout (and any uncommitted work in it) is
+    // still on disk, and the branch is the only ref still leading back to it.
+    if (fs.existsSync(info.path)) {
+        logger.warn(`Worktree directory survived removal — keeping ${info.branch} so the leftover checkout stays reachable:`, {
+            worktreePath: info.path,
+            residue: probeResidue(info.path),
+        });
+        return;
+    }
+    // Delete the worktree's own branch. Branches the user checked out inside the
+    // worktree are never touched — they may hold commits that are not reachable
+    // from anywhere else (aligned with Claude Code).
     try {
         execFileSync("git", ["branch", "-D", info.branch], {
             cwd: repoRoot,
@@ -587,26 +637,6 @@ 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
-            }
-        }
-    }
 }
 /**
  * Validate that a worktree path is safe to remove before running git removal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",
@@ -26,6 +26,10 @@
       "types": "./dist/constants/tools.d.ts",
       "default": "./dist/constants/tools.js"
     },
+    "./stdio": {
+      "types": "./dist/stdio/index.d.ts",
+      "default": "./dist/stdio/index.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -50,6 +54,7 @@
     "@vscode/ripgrep": "^1.18.0",
     "chokidar": "^4.0.3",
     "cron-parser": "^5.5.0",
+    "fflate": "^0.8.3",
     "fuzzysort": "^3.1.0",
     "glob": "^13.0.0",
     "lru-cache": "^11.3.5",

package/dist/managers/bangManager.d.ts

@@ -1,26 +0,0 @@
-import { Container } from "../utils/container.js";
-export interface BangManagerOptions {
-    workdir: string;
-}
-export interface CommandExecutionResult {
-    exitCode: number;
-    output: string;
-}
-export declare class BangManager {
-    private container;
-    private workdir;
-    isCommandRunning: boolean;
-    private currentProcess;
-    onCommandRunningChange?: (running: boolean) => void;
-    constructor(container: Container, options: BangManagerOptions);
-    private get 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();
-    private setCommandRunning;
-    executeCommand(command: string): Promise<number>;
-    abortCommand(): void;
-}

package/dist/managers/bangManager.js

@@ -1,78 +0,0 @@
-import { spawn } from "child_process";
-import { resolveShellPath } from "../utils/shellResolver.js";
-export class BangManager {
-    constructor(container, options) {
-        this.container = container;
-        this.isCommandRunning = false;
-        this.currentProcess = null;
-        this.workdir = options.workdir;
-    }
-    get messageManager() {
-        return this.container.get("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.
-     */
-    get sessionEnv() {
-        return (this.container
-            .get("ConfigurationService")
-            ?.getMergedEnv?.() ?? process.env);
-    }
-    setCommandRunning(isRunning) {
-        this.isCommandRunning = isRunning;
-        this.onCommandRunningChange?.(isRunning);
-    }
-    async executeCommand(command) {
-        if (this.isCommandRunning) {
-            throw new Error("Command already running");
-        }
-        this.setCommandRunning(true);
-        // Add bang placeholder
-        this.messageManager.addBangMessage(command);
-        return new Promise((resolve) => {
-            const child = spawn(command, {
-                shell: resolveShellPath() ?? true,
-                stdio: "pipe",
-                cwd: this.workdir,
-                env: {
-                    ...process.env,
-                    ...this.sessionEnv,
-                },
-            });
-            this.currentProcess = child;
-            let outputBuffer = "";
-            const updateOutput = (newData) => {
-                outputBuffer += newData;
-            };
-            child.stdout?.on("data", (data) => {
-                updateOutput(data.toString());
-            });
-            child.stderr?.on("data", (data) => {
-                updateOutput(data.toString());
-            });
-            child.on("exit", (code, signal) => {
-                const exitCode = code === null && signal ? 130 : (code ?? 0);
-                this.messageManager.completeBangMessage(command, exitCode, outputBuffer);
-                this.setCommandRunning(false);
-                this.currentProcess = null;
-                resolve(exitCode);
-            });
-            child.on("error", (error) => {
-                updateOutput(`\nError: ${error.message}\n`);
-                this.messageManager.completeBangMessage(command, 1, outputBuffer);
-                this.setCommandRunning(false);
-                this.currentProcess = null;
-                resolve(1);
-            });
-        });
-    }
-    abortCommand() {
-        if (this.currentProcess && this.isCommandRunning) {
-            this.currentProcess.kill("SIGKILL");
-            this.currentProcess = null;
-            this.isCommandRunning = false;
-        }
-    }
-}