wave-agent-sdk 0.10.1 → 0.10.2

package/dist/utils/gitUtils.js

@@ -58,6 +58,28 @@ export function getGitCommonDir(cwd) {
         return getGitRepoRoot(cwd);
     }
 }
+/**
+ * Get the main repository root directory (the first worktree in the list)
+ * @param cwd Working directory
+ * @returns Main repository root path
+ */
+export function getGitMainRepoRoot(cwd) {
+    try {
+        const output = execSync("git worktree list --porcelain", {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const lines = output.split("\n");
+        if (lines.length > 0 && lines[0].startsWith("worktree ")) {
+            return lines[0].substring("worktree ".length).trim();
+        }
+        return getGitRepoRoot(cwd);
+    }
+    catch {
+        return getGitRepoRoot(cwd);
+    }
+}
 /**
  * Get the default remote branch (e.g., origin/main)
  * @param cwd Working directory

package/package.json

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

package/src/agent.ts

@@ -235,7 +235,14 @@ export class Agent {
   public getBackgroundShellOutput(
     id: string,
     filter?: string,
-  ): { stdout: string; stderr: string; status: string } | null {
+  ): {
+    stdout: string;
+    stderr: string;
+    status: string;
+    outputPath?: string;
+    type: string;
+    exitCode?: number;
+  } | null {
     return this.backgroundTaskManager.getOutput(id, filter);
   }
 
@@ -248,7 +255,14 @@ export class Agent {
   public getBackgroundTaskOutput(
     id: string,
     filter?: string,
-  ): { stdout: string; stderr: string; status: string } | null {
+  ): {
+    stdout: string;
+    stderr: string;
+    status: string;
+    outputPath?: string;
+    type: string;
+    exitCode?: number;
+  } | null {
     return this.backgroundTaskManager.getOutput(id, filter);
   }
 
@@ -456,6 +470,8 @@ export class Agent {
     }
     // Cleanup subagent manager
     this.subagentManager.cleanup();
+    // Cleanup skill manager
+    await this.skillManager.destroy();
     // Cleanup live configuration reload
     try {
       await this.liveConfigManager.shutdown();

package/src/builtin-skills/settings/HOOKS.md

@@ -0,0 +1,95 @@
+# Wave Hooks Configuration
+
+Hooks allow you to automate tasks when certain events occur in Wave. This document provides detailed guidance on how to configure complex hooks in `settings.json`.
+
+## Hook Events
+
+Wave supports the following hook events:
+
+- `WorktreeCreate`: Triggered when a new worktree is created.
+- `TaskStart`: Triggered when a task starts.
+- `TaskComplete`: Triggered when a task is completed.
+- `TaskError`: Triggered when a task fails.
+- `SessionStart`: Triggered when a new session starts.
+- `SessionEnd`: Triggered when a session ends.
+
+## Hook Configuration Structure
+
+Hooks are configured in the `hooks` field of `settings.json`. Each event can have multiple hook configurations.
+
+```json
+{
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "command": "pnpm install",
+        "description": "Install dependencies in new worktree",
+        "blocking": true,
+        "timeout": 300000
+      }
+    ],
+    "TaskComplete": [
+      {
+        "command": "pnpm test",
+        "description": "Run tests after task completion",
+        "blocking": false
+      }
+    ]
+  }
+}
+```
+
+## Hook Configuration Fields
+
+- `command`: The shell command to execute.
+- `description`: A brief description of the hook's purpose.
+- `blocking`: (Optional) Whether the hook should block the main agent's execution (default: `false`).
+- `timeout`: (Optional) Maximum execution time in milliseconds (default: `60000`).
+- `env`: (Optional) Environment variables specific to this hook.
+- `cwd`: (Optional) Working directory for the hook command.
+
+## Advanced Hook Examples
+
+### 1. Conditional Hooks
+You can use shell logic within the `command` field to create conditional hooks.
+```json
+{
+  "hooks": {
+    "TaskComplete": [
+      {
+        "command": "if [ \"$WAVE_TASK_STATUS\" = \"completed\" ]; then pnpm lint; fi",
+        "description": "Run linting only on successful task completion"
+      }
+    ]
+  }
+}
+```
+
+### 2. Hook Chaining
+You can chain multiple commands in a single hook or define multiple hooks for the same event.
+```json
+{
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "command": "pnpm install && pnpm build",
+        "description": "Install and build in new worktree"
+      }
+    ]
+  }
+}
+```
+
+### 3. Using Environment Variables
+Wave provides several environment variables to hooks:
+- `WAVE_PROJECT_DIR`: The root directory of the project.
+- `WAVE_SESSION_ID`: The current session ID.
+- `WAVE_TASK_ID`: The current task ID (if applicable).
+- `WAVE_TASK_STATUS`: The status of the task (for `TaskComplete` and `TaskError`).
+
+## Best Practices
+
+- **Keep hooks fast**: Long-running hooks can slow down your workflow, especially if they are `blocking`.
+- **Use descriptive names**: Help yourself and others understand what each hook does.
+- **Test your hooks**: Run the commands manually first to ensure they work as expected.
+- **Use local overrides**: For machine-specific hooks, use `.wave/settings.local.json`.

package/src/builtin-skills/settings/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: settings
+description: Manage Wave settings and get guidance on settings.json
+allowed-tools: Bash, Read, Write
+---
+
+# Wave Settings Skill
+
+This skill helps you manage your Wave configuration and provides guidance on how to use `settings.json`.
+
+## What is `settings.json`?
+
+`settings.json` is the central configuration file for Wave. It allows you to customize hooks, environment variables, tool permissions, and more.
+
+Wave looks for `settings.json` in three scopes:
+1.  **User Scope**: Global settings for all projects. Located at `~/.wave/settings.json`.
+2.  **Project Scope**: Settings specific to the current project. Located at `.wave/settings.json` in your project root.
+3.  **Local Scope**: Local overrides for the current project (not committed to git). Located at `.wave/settings.local.json`.
+
+## Common Settings
+
+### 1. Hooks
+Hooks allow you to automate tasks when certain events occur (e.g., `WorktreeCreate`, `TaskStart`).
+For detailed hook configuration, see [HOOKS.md](${WAVE_SKILL_DIR}/HOOKS.md).
+
+### 2. Environment Variables
+Set environment variables that will be available to all tools and hooks.
+```json
+{
+  "env": {
+    "NODE_ENV": "development",
+    "API_KEY": "your-api-key"
+  }
+}
+```
+
+### 3. Permissions
+Manage tool permissions and define the "Safe Zone".
+```json
+{
+  "permissions": {
+    "allow": ["Bash", "Read"],
+    "deny": ["Write"],
+    "defaultMode": "interactive",
+    "additionalDirectories": ["/tmp/wave-exports"]
+  }
+}
+```
+
+### 4. Enabled Plugins
+Enable or disable specific plugins.
+```json
+{
+  "enabledPlugins": {
+    "git-plugin": true,
+    "experimental-plugin": false
+  }
+}
+```
+
+### 5. Model and Token Configuration
+Define which AI models Wave should use and set token limits via environment variables.
+```json
+{
+  "env": {
+    "WAVE_MODEL": "gemini-3-flash",
+    "WAVE_FAST_MODEL": "gemini-2.5-flash",
+    "WAVE_MAX_INPUT_TOKENS": "100000",
+    "WAVE_MAX_OUTPUT_TOKENS": "4096"
+  }
+}
+```
+
+### 6. Other Settings
+- `language`: Preferred language for agent communication (e.g., `"en"`, `"zh"`).
+- `autoMemoryEnabled`: Enable or disable auto-memory (default: `true`).
+
+## How to use this skill
+
+You can ask me to:
+- "Show my current settings"
+- "Update my project settings to enable auto-memory"
+- "How do I configure a post-commit hook?"
+- "What are the available permission modes?"
+
+I will guide you through the process and ensure your configuration is valid.

package/src/core/session.ts

@@ -1,5 +1,6 @@
 export {
   listSessions,
+  listAllSessions,
   truncateContent,
   loadSessionFromJsonl,
   loadFullMessageThread,

package/src/managers/backgroundTaskManager.ts

@@ -293,7 +293,14 @@ export class BackgroundTaskManager {
   public getOutput(
     id: string,
     filter?: string,
-  ): { stdout: string; stderr: string; status: string } | null {
+  ): {
+    stdout: string;
+    stderr: string;
+    status: string;
+    outputPath?: string;
+    type: string;
+    exitCode?: number;
+  } | null {
     const task = this.tasks.get(id);
     if (!task) {
       return null;
@@ -323,6 +330,9 @@ export class BackgroundTaskManager {
       stdout,
       stderr,
       status: task.status,
+      outputPath: task.outputPath,
+      type: task.type,
+      exitCode: task.exitCode,
     };
   }
 

package/src/managers/permissionManager.ts

@@ -34,7 +34,19 @@ import {
 import { Container } from "../utils/container.js";
 import { ConfigurationService } from "../services/configurationService.js";
 
-const SAFE_COMMANDS = ["cd", "ls", "pwd", "true", "false"];
+const SAFE_COMMANDS = [
+  "cd",
+  "ls",
+  "pwd",
+  "true",
+  "false",
+  "grep",
+  "rg",
+  "cat",
+  "head",
+  "tail",
+  "wc",
+];
 
 const DEFAULT_ALLOWED_RULES = [
   "Bash(git status*)",
@@ -69,7 +81,12 @@ const DEFAULT_ALLOWED_RULES = [
   "Bash(whoami*)",
   "Bash(date*)",
   "Bash(uptime*)",
-  "Bash(wc -l*)",
+  "Bash(grep*)",
+  "Bash(rg*)",
+  "Bash(cat*)",
+  "Bash(head*)",
+  "Bash(tail*)",
+  "Bash(wc*)",
 ];
 
 import { logger } from "../utils/globalLogger.js";
@@ -649,7 +666,13 @@ export class PermissionManager {
                   cmd === "pwd" ||
                   cmd === "true" ||
                   cmd === "false" ||
-                  cmd === "ls"
+                  cmd === "ls" ||
+                  cmd === "grep" ||
+                  cmd === "rg" ||
+                  cmd === "cat" ||
+                  cmd === "head" ||
+                  cmd === "tail" ||
+                  cmd === "wc"
                 ) {
                   return true;
                 }
@@ -751,7 +774,13 @@ export class PermissionManager {
             cmd === "pwd" ||
             cmd === "true" ||
             cmd === "false" ||
-            cmd === "ls"
+            cmd === "ls" ||
+            cmd === "grep" ||
+            cmd === "rg" ||
+            cmd === "cat" ||
+            cmd === "head" ||
+            cmd === "tail" ||
+            cmd === "wc"
           ) {
             isSafe = true;
           } else {

package/src/managers/skillManager.ts

@@ -1,6 +1,8 @@
 import { readdir, stat } from "fs/promises";
 import { join } from "path";
 import { homedir } from "os";
+import { EventEmitter } from "events";
+import { FileWatcherService } from "../services/fileWatcher.js";
 import type {
   SkillManagerOptions,
   SkillMetadata,
@@ -17,6 +19,7 @@ import {
   replaceBashCommandsWithOutput,
   executeBashCommands,
 } from "../utils/markdownParser.js";
+import { getBuiltinSkillsDir } from "../utils/configPaths.js";
 
 import { Container } from "../utils/container.js";
 import { logger } from "../utils/globalLogger.js";
@@ -24,7 +27,7 @@ import { logger } from "../utils/globalLogger.js";
 /**
  * Manages skill discovery and loading
  */
-export class SkillManager {
+export class SkillManager extends EventEmitter {
   private personalSkillsPath: string;
   private scanTimeout: number;
   private workdir: string;
@@ -32,15 +35,19 @@ export class SkillManager {
   private skillMetadata = new Map<string, SkillMetadata>();
   private skillContent = new Map<string, Skill>();
   private initialized = false;
+  private fileWatcher: FileWatcherService | null = null;
+  private watchEnabled: boolean;
 
   constructor(
     private container: Container,
     options: SkillManagerOptions = {},
   ) {
+    super();
     this.personalSkillsPath =
       options.personalSkillsPath || join(homedir(), ".wave", "skills");
     this.scanTimeout = options.scanTimeout || 5000;
     this.workdir = options.workdir || process.cwd();
+    this.watchEnabled = options.watch ?? false;
   }
 
   /**
@@ -50,26 +57,10 @@ export class SkillManager {
     logger?.debug("Initializing SkillManager...");
 
     try {
-      // Clear existing data before discovery
-      this.skillMetadata.clear();
-      this.skillContent.clear();
+      await this.refreshSkills();
 
-      const discovery = await this.discoverSkills();
-
-      // Store discovered skill metadata
-      discovery.personalSkills.forEach((skill, name) => {
-        this.skillMetadata.set(name, skill);
-      });
-      discovery.projectSkills.forEach((skill, name) => {
-        this.skillMetadata.set(name, skill);
-      });
-
-      // Log any discovery errors
-      if (discovery.errors.length > 0) {
-        logger?.warn(`Found ${discovery.errors.length} skill discovery errors`);
-        discovery.errors.forEach((error) => {
-          logger?.warn(`Skill error in ${error.skillPath}: ${error.message}`);
-        });
+      if (this.watchEnabled && !this.fileWatcher) {
+        await this.setupWatcher();
       }
 
       this.initialized = true;
@@ -82,6 +73,85 @@ export class SkillManager {
     }
   }
 
+  /**
+   * Refresh skills by re-discovering them
+   */
+  private async refreshSkills(): Promise<void> {
+    // Clear existing data before discovery
+    this.skillMetadata.clear();
+    this.skillContent.clear();
+
+    const discovery = await this.discoverSkills();
+
+    // Store discovered skill metadata
+    discovery.builtinSkills.forEach((skill, name) => {
+      this.skillMetadata.set(name, skill);
+    });
+    discovery.personalSkills.forEach((skill, name) => {
+      this.skillMetadata.set(name, skill);
+    });
+    discovery.projectSkills.forEach((skill, name) => {
+      this.skillMetadata.set(name, skill);
+    });
+
+    // Log any discovery errors
+    if (discovery.errors.length > 0) {
+      logger?.warn(`Found ${discovery.errors.length} skill discovery errors`);
+      discovery.errors.forEach((error) => {
+        logger?.warn(`Skill error in ${error.skillPath}: ${error.message}`);
+      });
+    }
+
+    this.emit("refreshed", Array.from(this.skillMetadata.values()));
+  }
+
+  /**
+   * Setup file watcher for skill directories
+   */
+  private async setupWatcher(): Promise<void> {
+    if (this.fileWatcher) {
+      await this.fileWatcher.cleanup();
+    }
+
+    this.fileWatcher = new FileWatcherService(logger);
+
+    const pathsToWatch = [
+      this.personalSkillsPath,
+      join(this.workdir, ".wave", "skills"),
+    ];
+
+    logger?.debug(`Setting up skill watcher for: ${pathsToWatch.join(", ")}`);
+
+    for (const pathToWatch of pathsToWatch) {
+      await this.fileWatcher.watchFile(pathToWatch, async (event) => {
+        if (
+          event.path.endsWith("SKILL.md") ||
+          event.type === "delete" ||
+          event.type === "create"
+        ) {
+          logger?.debug(
+            `Skill change detected (${event.type}): ${event.path}. Refreshing skills...`,
+          );
+          try {
+            await this.refreshSkills();
+          } catch (error) {
+            logger?.error("Failed to refresh skills after change:", error);
+          }
+        }
+      });
+    }
+  }
+
+  /**
+   * Cleanup resources
+   */
+  async destroy(): Promise<void> {
+    if (this.fileWatcher) {
+      await this.fileWatcher.cleanup();
+      this.fileWatcher = null;
+    }
+  }
+
   /**
    * Check if the skill manager is initialized
    */
@@ -132,9 +202,14 @@ export class SkillManager {
   }
 
   /**
-   * Discover skills in both personal and project directories
+   * Discover skills in builtin, personal and project directories
    */
   private async discoverSkills(): Promise<SkillDiscoveryResult> {
+    const builtinCollection = await this.discoverSkillCollection(
+      getBuiltinSkillsDir(),
+      "builtin",
+    );
+
     const personalCollection = await this.discoverSkillCollection(
       this.personalSkillsPath,
       "personal",
@@ -146,9 +221,14 @@ export class SkillManager {
     );
 
     return {
+      builtinSkills: builtinCollection.skills,
       personalSkills: personalCollection.skills,
       projectSkills: projectCollection.skills,
-      errors: [...personalCollection.errors, ...projectCollection.errors],
+      errors: [
+        ...builtinCollection.errors,
+        ...personalCollection.errors,
+        ...projectCollection.errors,
+      ],
     };
   }
 
@@ -157,7 +237,7 @@ export class SkillManager {
    */
   private async discoverSkillCollection(
     basePath: string,
-    type: "personal" | "project",
+    type: "personal" | "project" | "builtin",
   ): Promise<SkillCollection> {
     const collection: SkillCollection = {
       type,
@@ -166,8 +246,14 @@ export class SkillManager {
       errors: [],
     };
 
-    const skillsPath =
-      type === "personal" ? basePath : join(basePath, ".wave", "skills");
+    let skillsPath: string;
+    if (type === "personal") {
+      skillsPath = basePath;
+    } else if (type === "builtin") {
+      skillsPath = basePath;
+    } else {
+      skillsPath = join(basePath, ".wave", "skills");
+    }
 
     try {
       const skillDirs = await this.findSkillDirectories(skillsPath);

package/src/managers/slashCommandManager.ts

@@ -42,6 +42,14 @@ export class SlashCommandManager {
   public initialize(): void {
     this.initializeBuiltinCommands();
     this.loadCustomCommands();
+
+    // Listen for skill refreshes and update skill commands
+    const skillManager = this.container.get<SkillManager>("SkillManager");
+    if (skillManager) {
+      skillManager.on("refreshed", (skills: SkillMetadata[]) => {
+        this.registerSkillCommands(skills);
+      });
+    }
   }
 
   private get messageManager(): MessageManager {

package/src/prompts/index.ts

@@ -256,6 +256,7 @@ Usage notes:
 - Avoid listing every component or file structure that can be easily discovered.
 - Don't include generic development practices.
 - If there are Cursor rules (in .cursor/rules/ or .cursorrules) or Copilot rules (in .github/copilot-instructions.md), make sure to include the important parts.
+- Do NOT include rules from .wave/rules/ as they are automatically loaded by the system.
 - If there is a README.md, make sure to include the important parts.
 - Do not make up information such as "Common Development Tasks", "Tips for Development", "Support and Documentation" unless this is expressly included in other files that you read.
 - Be sure to prefix the file with the following text:

package/src/services/configurationService.ts

@@ -588,6 +588,7 @@ export class ConfigurationService {
     return {
       userPaths: allPaths.userPaths,
       projectPaths: allPaths.projectPaths,
+      builtinPaths: allPaths.builtinPaths,
       allPaths: allPaths.allPaths,
       existingPaths: existingPaths.existingPaths,
     };