wave-agent-sdk 0.10.3 → 0.11.0

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

@@ -1,17 +1,18 @@
 # 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`.
+Hooks allow you to automate tasks when certain events occur in Wave. This document provides detailed guidance on how to configure hooks in `settings.json`.
 
 ## Hook Events
 
 Wave supports the following hook events:
 
+- `PreToolUse`: Triggered before a tool is executed.
+- `PostToolUse`: Triggered after a tool has finished executing.
+- `UserPromptSubmit`: Triggered when a user submits a prompt.
+- `PermissionRequest`: Triggered when Wave requests permission to use a tool.
+- `Stop`: Triggered when Wave finishes its response cycle (no more tool calls).
+- `SubagentStop`: Triggered when a subagent finishes its response cycle.
 - `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
 
@@ -20,19 +21,26 @@ Hooks are configured in the `hooks` field of `settings.json`. Each event can hav
 ```json
 {
   "hooks": {
-    "WorktreeCreate": [
+    "PreToolUse": [
       {
-        "command": "pnpm install",
-        "description": "Install dependencies in new worktree",
-        "blocking": true,
-        "timeout": 300000
+        "matcher": "Write",
+        "hooks": [
+          {
+            "command": "pnpm lint",
+            "description": "Run lint before writing files"
+          }
+        ]
       }
     ],
-    "TaskComplete": [
+    "PermissionRequest": [
       {
-        "command": "pnpm test",
-        "description": "Run tests after task completion",
-        "blocking": false
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "command": "echo \"Permission requested for Bash tool\" >> hooks.log",
+            "description": "Log permission requests for Bash"
+          }
+        ]
       }
     ]
   }
@@ -41,55 +49,34 @@ Hooks are configured in the `hooks` field of `settings.json`. Each event can hav
 
 ## 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.
+- `matcher`: (Optional) A pattern to match against the tool name (e.g., "Write", "Read*", "/^Edit/"). Only applicable for `PreToolUse`, `PostToolUse`, and `PermissionRequest`.
+- `hooks`: An array of hook commands to execute.
+  - `command`: The shell command to execute.
+  - `description`: A brief description of the hook's purpose.
+  - `async`: (Optional) Whether the hook should run in the background without blocking (default: `false`).
+  - `timeout`: (Optional) Maximum execution time in seconds (default: `600`).
 
-## Advanced Hook Examples
+## Hook Input JSON
 
-### 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"
-      }
-    ]
-  }
-}
-```
+Wave provides detailed context to hook processes via `stdin` as a JSON object. This allows hooks to make informed decisions based on the current state.
 
-### 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"
-      }
-    ]
-  }
-}
-```
+### Common Fields
+- `session_id`: The current session ID.
+- `transcript_path`: Path to the session transcript file (JSON).
+- `cwd`: The current working directory.
+- `hook_event_name`: The name of the triggering event.
 
-### 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`).
+### Event-Specific Fields
+- `tool_name`: (PreToolUse, PostToolUse, PermissionRequest) The name of the tool.
+- `tool_input`: (PreToolUse, PostToolUse, PermissionRequest) The input parameters passed to the tool.
+- `tool_response`: (PostToolUse) The result of the tool execution.
+- `user_prompt`: (UserPromptSubmit) The text submitted by the user.
+- `subagent_type`: (If executed by a subagent) The type of the subagent.
+- `name`: (WorktreeCreate) The name of the new worktree.
 
 ## Best Practices
 
-- **Keep hooks fast**: Long-running hooks can slow down your workflow, especially if they are `blocking`.
+- **Keep hooks fast**: Long-running hooks can slow down your workflow unless they are `async`.
 - **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

@@ -41,7 +41,7 @@ Manage tool permissions and define the "Safe Zone".
   "permissions": {
     "allow": ["Bash", "Read"],
     "deny": ["Write"],
-    "defaultMode": "interactive",
+    "permissionMode": "default",
     "additionalDirectories": ["/tmp/wave-exports"]
   }
 }

package/src/constants/tools.ts

@@ -15,3 +15,6 @@ export const TASK_GET_TOOL_NAME = "TaskGet";
 export const TASK_UPDATE_TOOL_NAME = "TaskUpdate";
 export const TASK_LIST_TOOL_NAME = "TaskList";
 export const WRITE_TOOL_NAME = "Write";
+export const CRON_CREATE_TOOL_NAME = "CronCreate";
+export const CRON_DELETE_TOOL_NAME = "CronDelete";
+export const CRON_LIST_TOOL_NAME = "CronList";

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./constants/tools.js";
 // Export main agent
 export * from "./agent.js";
 export * from "./core/plugin.js";
+export * from "./managers/cronManager.js";
 
 // Export all utilities
 export * from "./utils/bashParser.js";

package/src/managers/aiManager.ts

@@ -8,6 +8,7 @@ import type {
   ModelConfig,
   Usage,
   PermissionMode,
+  Message,
 } from "../types/index.js";
 import type { ToolManager } from "./toolManager.js";
 import type { ToolContext, ToolResult } from "../tools/types.js";
@@ -160,26 +161,18 @@ export class AIManager {
   /**
    * Get filtered tool configuration based on tools list
    */
-  private getFilteredToolsConfig(tools?: string[]) {
+  private getFilteredToolsConfig() {
     // Get available subagents and skills for dynamic prompts
     const availableSubagents = this.subagentManager?.getConfigurations();
     const availableSkills = this.skillManager
       ?.getAvailableSkills()
       .filter((skill) => !skill.disableModelInvocation);
 
-    const allTools = this.toolManager.getToolsConfig({
+    return this.toolManager.getToolsConfig({
       availableSubagents,
       availableSkills,
       workdir: this.workdir,
     });
-
-    // If no tools specified, return all tools
-    if (!tools || tools.length === 0) {
-      return allTools;
-    }
-
-    // Filter tools
-    return allTools.filter((tool) => tools.includes(tool.function.name));
   }
 
   public setIsLoading(isLoading: boolean): void {
@@ -336,18 +329,10 @@ export class AIManager {
       model?: string;
       /** Rules for automatic tool approval (e.g., "Bash(git status*)") */
       allowedRules?: string[];
-      /** List of tools available to the AI (e.g., ["Bash", "Read"]) */
-      tools?: string[];
       maxTokens?: number;
     } = {},
   ): Promise<void> {
-    const {
-      recursionDepth = 0,
-      model,
-      allowedRules,
-      tools,
-      maxTokens,
-    } = options;
+    const { recursionDepth = 0, model, allowedRules, maxTokens } = options;
 
     // Only check isLoading for the initial call (recursionDepth === 0)
     if (recursionDepth === 0 && this.isLoading) {
@@ -401,7 +386,7 @@ export class AIManager {
       const currentMode = this.permissionManager?.getCurrentEffectiveMode(
         this.getModelConfig().permissionMode,
       );
-      const toolsConfig = this.getFilteredToolsConfig(tools);
+      const toolsConfig = this.getFilteredToolsConfig();
       const toolNames = new Set(toolsConfig.map((t) => t.function.name));
       const filteredToolPlugins = this.toolManager
         .getTools()
@@ -489,7 +474,6 @@ export class AIManager {
             name: toolCall.name,
             parameters: toolCall.parameters,
             parametersChunk: toolCall.parametersChunk,
-            compactParams: toolCall.parameters?.split("\n").pop()?.slice(-30),
             stage: toolCall.stage || "streaming", // Default to streaming if stage not provided
           });
         };
@@ -655,7 +639,18 @@ export class AIManager {
               toolArgs,
             );
 
-            // Emit running stage for non-streaming tool calls (tool execution about to start)
+            // Emit start stage for non-streaming tool calls
+            if (!this.stream) {
+              this.messageManager.updateToolBlock({
+                id: toolId,
+                stage: "start",
+                name: toolName,
+                compactParams,
+                parameters: argsString,
+              });
+            }
+
+            // Emit running stage (tool execution about to start)
             this.messageManager.updateToolBlock({
               id: toolId,
               stage: "running",
@@ -717,6 +712,7 @@ export class AIManager {
                 error: toolResult.error,
                 stage: "end",
                 name: toolName,
+                compactParams,
                 shortResult: toolResult.shortResult,
                 isManuallyBackgrounded: toolResult.isManuallyBackgrounded,
                 startLineNumber: toolResult.startLineNumber,
@@ -803,12 +799,65 @@ export class AIManager {
             });
           }
 
+          // Duplicate Tool Call Detection
+          if (toolCalls.length > 0) {
+            const messages = this.messageManager.getMessages();
+            // Find the most recent assistant message BEFORE the current one that has tool blocks
+            // The current assistant message is messages[messages.length - 1]
+            let previousAssistantWithTools: Message | undefined;
+            for (let i = messages.length - 2; i >= 0; i--) {
+              const msg = messages[i];
+              if (
+                msg.role === "assistant" &&
+                msg.blocks.some((b) => b.type === "tool")
+              ) {
+                previousAssistantWithTools = msg;
+                break;
+              }
+            }
+
+            if (previousAssistantWithTools) {
+              const previousToolBlocks =
+                previousAssistantWithTools.blocks.filter(
+                  (b): b is import("../types/messaging.js").ToolBlock =>
+                    b.type === "tool",
+                );
+
+              for (const currentToolCall of toolCalls) {
+                const currentName = currentToolCall.function?.name;
+                const currentArgs = currentToolCall.function?.arguments;
+
+                const isDuplicate = previousToolBlocks.some(
+                  (prevBlock) =>
+                    prevBlock.name === currentName &&
+                    prevBlock.parameters === currentArgs,
+                );
+
+                if (isDuplicate && currentName) {
+                  const toolId = currentToolCall.id;
+                  const lastMessage = messages[messages.length - 1];
+                  const toolBlock = lastMessage.blocks.find(
+                    (b): b is import("../types/messaging.js").ToolBlock =>
+                      b.type === "tool" && b.id === toolId,
+                  );
+                  if (toolBlock) {
+                    const warning = `\n\nNote: You just called this tool with the same arguments in the previous turn. Please ensure you are not in a loop and consider if you need to change your approach.`;
+                    this.messageManager.updateToolBlock({
+                      id: toolId,
+                      result: (toolBlock.result || "") + warning,
+                      stage: "end",
+                    });
+                  }
+                }
+              }
+            }
+          }
+
           // Recursively call AI service, increment recursion depth, and pass same configuration
           await this.sendAIMessage({
             recursionDepth: recursionDepth + 1,
             model,
             allowedRules,
-            tools,
             maxTokens,
           });
         }
@@ -861,7 +910,6 @@ export class AIManager {
               recursionDepth: 0,
               model,
               allowedRules,
-              tools,
               maxTokens,
             });
           }

package/src/managers/cronManager.ts

@@ -0,0 +1,167 @@
+import { Container } from "../utils/container.js";
+import { CronJob } from "../types/cron.js";
+import { AIManager } from "./aiManager.js";
+import { MessageManager } from "./messageManager.js";
+import { CronExpressionParser } from "cron-parser";
+import { logger } from "../utils/globalLogger.js";
+
+export class CronManager {
+  private jobs = new Map<string, CronJob>();
+  private interval: NodeJS.Timeout | null = null;
+
+  constructor(private container: Container) {}
+
+  private get aiManager(): AIManager {
+    return this.container.get<AIManager>("AIManager")!;
+  }
+
+  private get messageManager(): MessageManager {
+    return this.container.get<MessageManager>("MessageManager")!;
+  }
+
+  public start(): void {
+    if (this.interval) return;
+    this.interval = setInterval(() => this.checkJobs(), 60000); // Check every minute
+  }
+
+  public stop(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+  }
+
+  public createJob(
+    job: Omit<CronJob, "id" | "createdAt" | "nextRun" | "periodMs">,
+  ): CronJob {
+    const id = Math.random().toString(36).substring(2, 11);
+    const createdAt = Date.now();
+
+    const interval = CronExpressionParser.parse(job.cron);
+    const nextRunDate = interval.next().toDate();
+    const nextRun = nextRunDate.getTime();
+
+    // Calculate periodMs
+    const secondRunDate = interval.next().toDate();
+    const periodMs = secondRunDate.getTime() - nextRunDate.getTime();
+
+    // Apply Jitter
+    const jitteredNextRun = this.applyJitter(
+      nextRun,
+      periodMs,
+      job.recurring,
+      nextRunDate,
+      id,
+    );
+
+    const newJob: CronJob = {
+      ...job,
+      id,
+      createdAt,
+      nextRun: jitteredNextRun,
+      periodMs,
+    };
+
+    this.jobs.set(id, newJob);
+    return newJob;
+  }
+
+  public deleteJob(id: string): boolean {
+    return this.jobs.delete(id);
+  }
+
+  public listJobs(): CronJob[] {
+    return Array.from(this.jobs.values());
+  }
+
+  private applyJitter(
+    nextRun: number,
+    periodMs: number,
+    recurring: boolean,
+    nextRunDate: Date,
+    id: string,
+  ): number {
+    const deterministicRandom = this.getDeterministicRandom(id);
+    if (recurring) {
+      // Recurring: Random delay up to 10% of period (max 15 min)
+      const maxJitter = Math.min(periodMs * 0.1, 15 * 60 * 1000);
+      return nextRun + deterministicRandom * maxJitter;
+    } else {
+      // One-shot: Random early fire up to 90s if scheduled on :00 or :30
+      const minutes = nextRunDate.getMinutes();
+      const seconds = nextRunDate.getSeconds();
+      if ((minutes === 0 || minutes === 30) && seconds === 0) {
+        return nextRun - deterministicRandom * 90 * 1000;
+      }
+    }
+    return nextRun;
+  }
+
+  private getDeterministicRandom(id: string): number {
+    let hash = 0;
+    for (let i = 0; i < id.length; i++) {
+      const char = id.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0; // Convert to 32bit integer
+    }
+    // Use a simple LCG-like approach to get a value between 0 and 1
+    const x = Math.sin(hash) * 10000;
+    return x - Math.floor(x);
+  }
+
+  private async checkJobs(): Promise<void> {
+    const now = Date.now();
+    const aiManager = this.aiManager;
+    const messageManager = this.messageManager;
+
+    for (const [id, job] of this.jobs.entries()) {
+      // Expiration: Recurring jobs MUST auto-expire after 7 days
+      if (job.recurring && now - job.createdAt > 7 * 24 * 60 * 60 * 1000) {
+        this.jobs.delete(id);
+        continue;
+      }
+
+      if (now >= job.nextRun) {
+        // Idle-Check: Only fire jobs if AIManager.isLoading is false
+        if (aiManager.isLoading) {
+          logger?.debug(`CronManager: Skipping job ${id} because AI is busy`);
+          continue;
+        }
+
+        logger?.info(`CronManager: Firing job ${id}: ${job.prompt}`);
+
+        // Execution
+        messageManager.addUserMessage({ content: job.prompt });
+        aiManager.sendAIMessage().catch((err) => {
+          logger?.error(`CronManager: Failed to execute job ${id}`, err);
+        });
+
+        if (job.recurring) {
+          // Schedule next run
+          try {
+            const interval = CronExpressionParser.parse(job.cron, {
+              currentDate: new Date(job.nextRun + 1000),
+            });
+            const nextRunDate = interval.next().toDate();
+            const nextRun = nextRunDate.getTime();
+            job.nextRun = this.applyJitter(
+              nextRun,
+              job.periodMs,
+              true,
+              nextRunDate,
+              id,
+            );
+          } catch (e) {
+            logger?.error(
+              `CronManager: Failed to parse cron for recurring job ${id}`,
+              e,
+            );
+            this.jobs.delete(id);
+          }
+        } else {
+          this.jobs.delete(id);
+        }
+      }
+    }
+  }
+}

package/src/managers/hookManager.ts

@@ -236,13 +236,17 @@ export class HookManager {
     for (const result of results) {
       if (result.exitCode === 2) {
         // Handle blocking error immediately and return
-        return this.handleBlockingError(
+        const blockingResult = this.handleBlockingError(
           event,
           result,
           messageManager,
           toolId,
           toolParameters,
         );
+        return {
+          shouldBlock: blockingResult.shouldBlock,
+          errorMessage: blockingResult.errorMessage,
+        };
       }
     }
 
@@ -280,7 +284,7 @@ export class HookManager {
         source: MessageSource.HOOK,
       });
     }
-    // For other hook types (PreToolUse, PostToolUse, Stop), ignore stdout
+    // For other hook types (PreToolUse, PostToolUse, Stop, PermissionRequest), ignore stdout
   }
 
   /**
@@ -338,10 +342,10 @@ export class HookManager {
         });
         return { shouldBlock: true, errorMessage };
 
-      case "Notification":
-        // For notification hooks with exit code 2, only show stderr in error block
+      case "PermissionRequest":
+        // For permission request hooks with exit code 2, show stderr in error block and block (deny) permission
         messageManager.addErrorBlock(errorMessage);
-        return { shouldBlock: false };
+        return { shouldBlock: true, errorMessage };
 
       case "SubagentStop":
         // Similar to Stop, show error and allow blocking
@@ -544,7 +548,11 @@ export class HookManager {
     }
 
     // Validate tool-specific requirements
-    if (event === "PreToolUse" || event === "PostToolUse") {
+    if (
+      event === "PreToolUse" ||
+      event === "PostToolUse" ||
+      event === "PermissionRequest"
+    ) {
       if (!context.toolName || typeof context.toolName !== "string") {
         errors.push(`${event} event requires a valid toolName in context`);
       }
@@ -554,7 +562,6 @@ export class HookManager {
     if (
       (event === "UserPromptSubmit" ||
         event === "Stop" ||
-        event === "Notification" ||
         event === "SubagentStop" ||
         event === "WorktreeCreate") &&
       context.toolName !== undefined
@@ -631,7 +638,6 @@ export class HookManager {
     if (
       event === "UserPromptSubmit" ||
       event === "Stop" ||
-      event === "Notification" ||
       event === "SubagentStop" ||
       event === "WorktreeCreate"
     ) {
@@ -639,7 +645,11 @@ export class HookManager {
     }
 
     // For tool-based events, check matcher if present
-    if (event === "PreToolUse" || event === "PostToolUse") {
+    if (
+      event === "PreToolUse" ||
+      event === "PostToolUse" ||
+      event === "PermissionRequest"
+    ) {
       if (!config.matcher) {
         // No matcher means applies to all tools
         return true;
@@ -673,7 +683,12 @@ export class HookManager {
     }
 
     // Validate matcher requirements
-    if ((event === "PreToolUse" || event === "PostToolUse") && config.matcher) {
+    if (
+      (event === "PreToolUse" ||
+        event === "PostToolUse" ||
+        event === "PermissionRequest") &&
+      config.matcher
+    ) {
       if (!this.matcher.isValidPattern(config.matcher)) {
         errors.push(`${prefix}: Invalid matcher pattern: ${config.matcher}`);
       }
@@ -683,7 +698,6 @@ export class HookManager {
     if (
       (event === "UserPromptSubmit" ||
         event === "Stop" ||
-        event === "Notification" ||
         event === "SubagentStop" ||
         event === "WorktreeCreate") &&
       config.matcher
@@ -723,7 +737,7 @@ export class HookManager {
           UserPromptSubmit: 0,
           Stop: 0,
           SubagentStop: 0,
-          Notification: 0,
+          PermissionRequest: 0,
           WorktreeCreate: 0,
         },
       };
@@ -735,7 +749,7 @@ export class HookManager {
       UserPromptSubmit: 0,
       Stop: 0,
       SubagentStop: 0,
-      Notification: 0,
+      PermissionRequest: 0,
       WorktreeCreate: 0,
     };
 

package/src/managers/liveConfigManager.ts

@@ -258,8 +258,8 @@ export class LiveConfigManager {
 
       // Update permission manager if available
       if (this.permissionManager) {
-        this.permissionManager.updateConfiguredDefaultMode(
-          this.currentConfiguration.permissions?.defaultMode,
+        this.permissionManager.updateConfiguredPermissionMode(
+          this.currentConfiguration.permissions?.permissionMode,
         );
         this.permissionManager.updateAllowedRules(
           this.currentConfiguration.permissions?.allow || [],

package/src/managers/mcpManager.ts

@@ -347,6 +347,7 @@ export class McpManager {
   async executeMcpTool(
     toolName: string,
     args: Record<string, unknown>,
+    context?: ToolContext,
   ): Promise<{
     success: boolean;
     content: string;
@@ -360,6 +361,23 @@ export class McpManager {
       );
     }
 
+    // Permission check
+    if (context?.permissionManager) {
+      const permissionContext = context.permissionManager.createContext(
+        toolName,
+        context.permissionMode || "default",
+        context.canUseToolCallback,
+        args,
+        context.toolCallId,
+      );
+
+      const decision =
+        await context.permissionManager.checkPermission(permissionContext);
+      if (decision.behavior === "deny") {
+        throw new Error(decision.message || "Permission denied");
+      }
+    }
+
     const parts = toolName.split("__");
     if (parts.length < 3) {
       throw new Error(
@@ -479,8 +497,11 @@ export class McpManager {
         const plugin = createMcpToolPlugin(
           tool,
           server.name,
-          (name: string, args: Record<string, unknown>) =>
-            this.executeMcpTool(name, args),
+          (
+            name: string,
+            args: Record<string, unknown>,
+            context?: ToolContext,
+          ) => this.executeMcpTool(name, args, context),
         );
         mcpTools.set(plugin.name, plugin);
       }