wave-agent-sdk 0.15.1 → 0.15.2

package/src/tools/toolSearchTool.ts

@@ -0,0 +1,228 @@
+/**
+ * ToolSearchTool - Discovers deferred tool schemas on demand.
+ *
+ * When tool deferral is enabled, deferred tools are not sent to the API.
+ * The model must call this tool to discover a deferred tool's full schema
+ * before it can invoke it.
+ *
+ * Query formats:
+ * - "select:ToolName" — direct selection by name (comma-separated for multiple)
+ * - "notebook jupyter" — keyword search, up to max_results best matches
+ * - "+slack send" — require "slack" in the name, rank by remaining terms
+ */
+
+import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
+import {
+  isDeferredTool,
+  TOOL_SEARCH_TOOL_NAME,
+} from "../utils/isDeferredTool.js";
+
+function formatSchema(tool: ToolPlugin): string {
+  const desc = tool.config.function.description || "";
+  const params = JSON.stringify(tool.config.function.parameters || {}, null, 2);
+  return `${tool.name}: ${desc}\nParameters: ${params}`;
+}
+
+/**
+ * Parse tool name into searchable parts (handles CamelCase and underscores).
+ */
+function parseToolName(name: string): string[] {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1 $2") // CamelCase to spaces
+    .replace(/_/g, " ")
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/**
+ * Keyword search over deferred tools by name and description.
+ * Matches Claude Code's scoring: required terms (+prefix) must all match,
+ * optional terms contribute to ranking.
+ */
+function keywordSearch(
+  query: string,
+  deferredTools: ToolPlugin[],
+  maxResults: number,
+): ToolPlugin[] {
+  const queryLower = query.toLowerCase().trim();
+  const queryTerms = queryLower.split(/\s+/).filter(Boolean);
+
+  // Exact match fast path
+  const exact = deferredTools.find((t) => t.name.toLowerCase() === queryLower);
+  if (exact) return [exact];
+
+  // Partition into required (+prefixed) and optional terms
+  const requiredTerms: string[] = [];
+  const optionalTerms: string[] = [];
+  for (const term of queryTerms) {
+    if (term.startsWith("+") && term.length > 1) {
+      requiredTerms.push(term.slice(1));
+    } else {
+      optionalTerms.push(term);
+    }
+  }
+
+  const allScoringTerms =
+    requiredTerms.length > 0
+      ? [...requiredTerms, ...optionalTerms]
+      : queryTerms;
+
+  // Pre-filter to tools matching ALL required terms
+  let candidateTools = deferredTools;
+  if (requiredTerms.length > 0) {
+    candidateTools = deferredTools.filter((tool) => {
+      const parts = parseToolName(tool.name);
+      const desc = (tool.config.function.description || "").toLowerCase();
+      return requiredTerms.every(
+        (term) =>
+          parts.includes(term) ||
+          parts.some((p) => p.includes(term)) ||
+          desc.includes(term),
+      );
+    });
+  }
+
+  // Score each tool
+  const scored = candidateTools
+    .map((tool) => {
+      const parts = parseToolName(tool.name);
+      const desc = (tool.config.function.description || "").toLowerCase();
+      let score = 0;
+
+      for (const term of allScoringTerms) {
+        // Exact part match (high weight)
+        if (parts.includes(term)) {
+          score += tool.isMcp ? 12 : 10;
+        } else if (parts.some((p) => p.includes(term))) {
+          score += tool.isMcp ? 6 : 5;
+        }
+
+        // Full name fallback
+        if (tool.name.toLowerCase().includes(term) && score === 0) {
+          score += 3;
+        }
+
+        // Description match
+        if (desc.includes(term)) {
+          score += 2;
+        }
+      }
+
+      return { tool, score };
+    })
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, maxResults)
+    .map((s) => s.tool);
+
+  return scored;
+}
+
+export const toolSearchTool: ToolPlugin = {
+  name: TOOL_SEARCH_TOOL_NAME,
+  config: {
+    type: "function",
+    function: {
+      name: TOOL_SEARCH_TOOL_NAME,
+      description: `Fetches full schema definitions for deferred tools so they can be called.
+
+Deferred tools appear by name in <available-deferred-tools> messages. Until fetched, only the name is known — there is no parameter schema, so the tool cannot be invoked. This tool takes a query, matches it against the deferred tool list, and returns the matched tools' complete JSONSchema definitions inside a <functions> block. Once a tool's schema appears in that result, it is callable exactly like any tool defined at the top of the prompt.
+
+Result format: each matched tool appears as one <function>{"description": "...", "name": "...", "parameters": {...}}`,
+    },
+  },
+  shouldDefer: false, // Always available
+  execute: async (
+    args: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolResult> => {
+    const { query, max_results = 5 } = args as {
+      query?: string;
+      max_results?: number;
+    };
+
+    if (!query) {
+      return {
+        success: false,
+        content: "",
+        error: "Missing required 'query' parameter",
+      };
+    }
+
+    if (!context.toolManager) {
+      return {
+        success: false,
+        content: "",
+        error: "ToolManager not available in context",
+      };
+    }
+
+    const allTools = context.toolManager.list();
+    const deferredTools = allTools.filter(isDeferredTool);
+
+    // Handle select: prefix
+    const selectMatch = query.match(/^select:(.+)$/i);
+    if (selectMatch) {
+      const requested = selectMatch[1]!
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+
+      const found: ToolPlugin[] = [];
+      const missing: string[] = [];
+
+      for (const toolName of requested) {
+        const tool =
+          deferredTools.find((t) => t.name === toolName) ??
+          allTools.find((t) => t.name === toolName);
+        if (tool) {
+          if (!found.some((f) => f.name === tool.name)) found.push(tool);
+        } else {
+          missing.push(toolName);
+        }
+      }
+
+      if (found.length === 0) {
+        return {
+          success: false,
+          content: "",
+          error: `No matching deferred tools found for: ${missing.join(", ")}`,
+        };
+      }
+
+      const result = found.map(formatSchema).join("\n\n---\n\n");
+      const shortResult = `Discovered tools: ${found.map((t) => t.name).join(", ")}`;
+
+      return {
+        success: true,
+        content: result,
+        shortResult,
+      };
+    }
+
+    // Keyword search
+    const matches = keywordSearch(query, deferredTools, max_results);
+
+    if (matches.length === 0) {
+      return {
+        success: false,
+        content: "",
+        error: `No matching deferred tools found for query: "${query}". Available deferred tools: ${getDeferredToolNamesList(deferredTools)}`,
+      };
+    }
+
+    const result = matches.map(formatSchema).join("\n\n---\n\n");
+    const shortResult = `Found ${matches.length} tools: ${matches.map((t) => t.name).join(", ")}`;
+
+    return {
+      success: true,
+      content: result,
+      shortResult,
+    };
+  },
+};
+
+function getDeferredToolNamesList(tools: ToolPlugin[]): string {
+  return tools.map((t) => t.name).join(", ");
+}

package/src/tools/types.ts

@@ -31,6 +31,21 @@ export interface ToolPlugin {
     workdir?: string;
     isSubagent?: boolean;
   }) => string;
+  /**
+   * When true, this tool is deferred — it's not sent to the API until the model
+   * discovers it via ToolSearch. MCP tools are always deferred.
+   */
+  shouldDefer?: boolean;
+  /**
+   * When true, this tool is never deferred — its full schema always appears in
+   * the initial prompt even when tool search is enabled.
+   */
+  alwaysLoad?: boolean;
+  /**
+   * When true, this is an MCP tool (auto-set by McpManager). MCP tools are
+   * always deferred unless they have alwaysLoad: true.
+   */
+  isMcp?: boolean;
 }
 
 export interface ToolResult {
@@ -58,6 +73,8 @@ export interface ToolContext {
   abortSignal?: AbortSignal;
   backgroundTaskManager?: import("../managers/backgroundTaskManager.js").BackgroundTaskManager;
   workdir: string;
+  /** Tool manager instance for tool discovery (used by ToolSearchTool) */
+  toolManager?: import("../managers/toolManager.js").ToolManager;
   /** Permission mode for this tool execution */
   permissionMode?: PermissionMode;
   /** Custom permission callback */
@@ -103,4 +120,6 @@ export interface ToolContext {
   };
   /** State of files read in the current session for deduplication */
   readFileState?: Map<string, { mtime: number; hash: string }>;
+  /** Hook manager instance for executing hooks */
+  hookManager?: import("../managers/hookManager.js").HookManager;
 }

package/src/tools/webFetchTool.ts

@@ -103,6 +103,7 @@ const GITHUB_URL_ERROR =
 
 export const webFetchTool: ToolPlugin = {
   name: WEB_FETCH_TOOL_NAME,
+  shouldDefer: true,
   config: {
     type: "function",
     function: {

package/src/types/agent.ts

@@ -8,6 +8,7 @@ import type {
   ILspManager,
   PluginConfig,
   BackgroundTask,
+  McpServerConfig,
 } from "./index.js";
 import type { MessageManagerCallbacks } from "../managers/messageManager.js";
 import type { BackgroundTaskManagerCallbacks } from "../managers/backgroundTaskManager.js";
@@ -78,6 +79,11 @@ export interface AgentOptions {
    * These rules follow the standard permission rule syntax: `ToolName` or `ToolName(pattern)`.
    */
   disallowedTools?: string[];
+  /**
+   * Optional MCP server configs to connect at startup.
+   * Overrides .mcp.json for specified server names.
+   */
+  mcpServers?: Record<string, McpServerConfig>;
   [key: string]: unknown;
 }
 

package/src/types/hooks.ts

@@ -21,6 +21,7 @@ export type HookEvent =
   | "SubagentStop"
   | "PermissionRequest"
   | "WorktreeCreate"
+  | "WorktreeRemove"
   | "SessionStart"
   | "SessionEnd";
 
@@ -45,6 +46,8 @@ export interface HookExecutionContext {
   toolName?: string; // Present for PreToolUse/PostToolUse events
   projectDir: string; // Absolute path for $WAVE_PROJECT_DIR
   timestamp: Date;
+  worktreeName?: string; // Present for WorktreeCreate
+  worktreePath?: string; // Present for WorktreeRemove
 }
 
 // Result of hook execution
@@ -109,6 +112,7 @@ export function isValidHookEvent(event: string): event is HookEvent {
     "SubagentStop",
     "PermissionRequest",
     "WorktreeCreate",
+    "WorktreeRemove",
     "SessionStart",
     "SessionEnd",
   ].includes(event);

package/src/utils/containerSetup.ts

@@ -26,9 +26,8 @@ import { ConfigurationService } from "../services/configurationService.js";
 import { ReversionService } from "../services/reversionService.js";
 import { MemoryService } from "../services/memory.js";
 import { AutoMemoryService } from "../services/autoMemoryService.js";
-import { getGitMainRepoRoot } from "./gitUtils.js";
 import { USER_MEMORY_FILE } from "./constants.js";
-import type { AgentOptions } from "../types/index.js";
+import type { AgentOptions, McpServerConfig } from "../types/index.js";
 import type {
   PermissionMode,
   Usage,
@@ -89,11 +88,6 @@ export function setupAgentContainer(
   container.register("ForegroundTaskManager", foregroundTaskManager);
   container.register("ConfigurationService", configurationService);
 
-  if (options.worktreeName) {
-    container.register("WorktreeName", options.worktreeName);
-    container.register("MainRepoRoot", getGitMainRepoRoot(workdir));
-  }
-
   const memoryService = new MemoryService(container);
   container.register("MemoryService", memoryService);
 
@@ -145,7 +139,12 @@ export function setupAgentContainer(
   });
   container.register("BackgroundTaskManager", backgroundTaskManager);
 
-  const mcpManager = new McpManager(container, { callbacks });
+  const mcpManager = new McpManager(container, {
+    callbacks,
+    mcpServers: options.mcpServers as
+      | Record<string, McpServerConfig>
+      | undefined,
+  });
   container.register("McpManager", mcpManager);
 
   const lspManager = options.lspManager || new LspManager(container);

package/src/utils/cronToHuman.ts

@@ -0,0 +1,99 @@
+// Human-readable cron expression display.
+// Intentionally narrow: covers common patterns; falls through to raw cron
+// string for anything else. Based on Claude Code's cronToHuman implementation.
+
+const DAY_NAMES = [
+  "Sunday",
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+  "Saturday",
+];
+
+function formatLocalTime(minute: number, hour: number): string {
+  const d = new Date(2000, 0, 1, hour, minute);
+  return d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" });
+}
+
+/**
+ * Convert a cron expression to a human-readable string.
+ * Covers common patterns; falls through to raw cron for anything else.
+ */
+export function cronToHuman(cron: string): string {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 5) return cron;
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts as [
+    string,
+    string,
+    string,
+    string,
+    string,
+  ];
+
+  // Every N minutes: step/N * * * *
+  const everyMinMatch = minute.match(/^\*\/(\d+)$/);
+  if (
+    everyMinMatch &&
+    hour === "*" &&
+    dayOfMonth === "*" &&
+    month === "*" &&
+    dayOfWeek === "*"
+  ) {
+    const n = parseInt(everyMinMatch[1]!, 10);
+    return n === 1 ? "Every minute" : `Every ${n} minutes`;
+  }
+
+  // Every hour: 0 * * * *
+  if (
+    minute.match(/^\d+$/) &&
+    hour === "*" &&
+    dayOfMonth === "*" &&
+    month === "*" &&
+    dayOfWeek === "*"
+  ) {
+    const m = parseInt(minute, 10);
+    if (m === 0) return "Every hour";
+    return `Every hour at :${m.toString().padStart(2, "0")}`;
+  }
+
+  // Every N hours: 0 step/N * * *
+  const everyHourMatch = hour.match(/^\*\/(\d+)$/);
+  if (
+    minute.match(/^\d+$/) &&
+    everyHourMatch &&
+    dayOfMonth === "*" &&
+    month === "*" &&
+    dayOfWeek === "*"
+  ) {
+    const n = parseInt(everyHourMatch[1]!, 10);
+    const m = parseInt(minute, 10);
+    const suffix = m === 0 ? "" : ` at :${m.toString().padStart(2, "0")}`;
+    return n === 1 ? `Every hour${suffix}` : `Every ${n} hours${suffix}`;
+  }
+
+  if (!minute.match(/^\d+$/) || !hour.match(/^\d+$/)) return cron;
+  const m = parseInt(minute, 10);
+  const h = parseInt(hour, 10);
+
+  // Daily at specific time: M H * * *
+  if (dayOfMonth === "*" && month === "*" && dayOfWeek === "*") {
+    return `Every day at ${formatLocalTime(m, h)}`;
+  }
+
+  // Specific day of week: M H * * D
+  if (dayOfMonth === "*" && month === "*" && dayOfWeek.match(/^\d$/)) {
+    const dayIndex = parseInt(dayOfWeek, 10) % 7;
+    const dayName = DAY_NAMES[dayIndex];
+    if (dayName) return `Every ${dayName} at ${formatLocalTime(m, h)}`;
+  }
+
+  // Weekdays: M H * * 1-5
+  if (dayOfMonth === "*" && month === "*" && dayOfWeek === "1-5") {
+    return `Weekdays at ${formatLocalTime(m, h)}`;
+  }
+
+  return cron;
+}

package/src/utils/isDeferredTool.ts

@@ -0,0 +1,36 @@
+/**
+ * Determines if a tool should be deferred (not sent to the API until discovered).
+ *
+ * A tool is deferred if:
+ * - It has shouldDefer: true
+ * - It is an MCP tool (isMcp: true)
+ *
+ * A tool is NEVER deferred if:
+ * - It has alwaysLoad: true
+ * - It is the ToolSearch tool itself (must always be available)
+ */
+
+import type { ToolPlugin } from "../tools/types.js";
+
+export const TOOL_SEARCH_TOOL_NAME = "ToolSearch";
+
+export function isDeferredTool(tool: ToolPlugin): boolean {
+  // Never defer if explicitly marked as alwaysLoad
+  if (tool.alwaysLoad === true) return false;
+
+  // Never defer ToolSearch itself — the model needs it to discover other tools
+  if (tool.name === TOOL_SEARCH_TOOL_NAME) return false;
+
+  // MCP tools are always deferred (workflow-specific, potentially many)
+  if (tool.isMcp === true) return true;
+
+  // Defer if marked with shouldDefer flag
+  return tool.shouldDefer === true;
+}
+
+/**
+ * Get the list of deferred tool names from a tools array.
+ */
+export function getDeferredToolNames(tools: ToolPlugin[]): string[] {
+  return tools.filter(isDeferredTool).map((t) => t.name);
+}

package/src/utils/mcpUtils.ts

@@ -91,6 +91,7 @@ export function createMcpToolPlugin(
   return {
     name: prefixedName,
     config: mcpToolToOpenAITool(mcpTool, serverName),
+    isMcp: true, // MCP tools are always deferred
     async execute(
       args: Record<string, unknown>,
       context?: ToolContext,

package/src/utils/parseCronExpression.ts

@@ -0,0 +1,78 @@
+// Minimal cron expression validation.
+// Supports the standard 5-field cron subset:
+//   minute hour day-of-month month day-of-week
+//
+// Field syntax: wildcard, N, step (star-slash-N), range (N-M), list (N,M,...).
+// No L, W, ?, or name aliases. Based on Claude Code's parseCronExpression.
+
+type FieldRange = { min: number; max: number };
+
+const FIELD_RANGES: FieldRange[] = [
+  { min: 0, max: 59 }, // minute
+  { min: 0, max: 23 }, // hour
+  { min: 1, max: 31 }, // dayOfMonth
+  { min: 1, max: 12 }, // month
+  { min: 0, max: 6 }, // dayOfWeek (0=Sunday; 7 accepted as Sunday alias)
+];
+
+function expandField(field: string, range: FieldRange): number[] | null {
+  const { min, max } = range;
+  const out = new Set<number>();
+
+  for (const part of field.split(",")) {
+    // wildcard or star-slash-N
+    const stepMatch = part.match(/^\*(?:\/(\d+))?$/);
+    if (stepMatch) {
+      const step = stepMatch[1] ? parseInt(stepMatch[1], 10) : 1;
+      if (step < 1) return null;
+      for (let i = min; i <= max; i += step) out.add(i);
+      continue;
+    }
+
+    // N-M or N-M/S
+    const rangeMatch = part.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);
+    if (rangeMatch) {
+      const lo = parseInt(rangeMatch[1]!, 10);
+      const hi = parseInt(rangeMatch[2]!, 10);
+      const step = rangeMatch[3] ? parseInt(rangeMatch[3], 10) : 1;
+      const isDow = min === 0 && max === 6;
+      const effMax = isDow ? 7 : max;
+      if (lo > hi || step < 1 || lo < min || hi > effMax) return null;
+      for (let i = lo; i <= hi; i += step) {
+        out.add(isDow && i === 7 ? 0 : i);
+      }
+      continue;
+    }
+
+    // plain N
+    const singleMatch = part.match(/^\d+$/);
+    if (singleMatch) {
+      let n = parseInt(part, 10);
+      if (min === 0 && max === 6 && n === 7) n = 0;
+      if (n < min || n > max) return null;
+      out.add(n);
+      continue;
+    }
+
+    return null;
+  }
+
+  if (out.size === 0) return null;
+  return Array.from(out).sort((a, b) => a - b);
+}
+
+/**
+ * Validate a 5-field cron expression.
+ * Returns true if valid, false otherwise.
+ */
+export function parseCronExpression(expr: string): boolean {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return false;
+
+  for (let i = 0; i < 5; i++) {
+    const result = expandField(parts[i]!, FIELD_RANGES[i]!);
+    if (!result) return false;
+  }
+
+  return true;
+}

package/src/utils/worktreeSession.ts

@@ -0,0 +1,36 @@
+/**
+ * Module-level worktree session state tracking.
+ * Analogous to Claude Code's currentWorktreeSession in worktree.ts.
+ *
+ * Tracks whether the current session entered a worktree via EnterWorktree tool,
+ * so ExitWorktree can validate scope and restore the original CWD.
+ */
+
+export interface WorktreeSession {
+  /** The working directory the session was in before EnterWorktree */
+  originalCwd: string;
+  /** Path to the worktree directory */
+  worktreePath: string;
+  /** Git branch name for the worktree */
+  worktreeBranch: string;
+  /** User-provided or auto-generated worktree name */
+  worktreeName: string;
+  /** Whether this worktree was newly created (vs resumed existing) */
+  isNew: boolean;
+  /** The canonical git repo root */
+  repoRoot: string;
+  /** The HEAD commit of the original branch at worktree creation time */
+  originalHeadCommit?: string;
+}
+
+let currentWorktreeSession: WorktreeSession | null = null;
+
+export function getCurrentWorktreeSession(): WorktreeSession | null {
+  return currentWorktreeSession;
+}
+
+export function setCurrentWorktreeSession(
+  session: WorktreeSession | null,
+): void {
+  currentWorktreeSession = session;
+}