wave-agent-sdk 0.15.0 → 0.15.2

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/messageOperations.ts

@@ -160,6 +160,7 @@ export const addUserMessageToMessages = ({
     id: id || generateMessageId(),
     role: "user",
     blocks,
+    timestamp: new Date().toISOString(),
     ...(isMeta !== undefined && { isMeta }),
   };
   return [...messages, userMessage];
@@ -231,6 +232,7 @@ export const addAssistantMessageToMessages = (
     id: generateMessageId(),
     role: "assistant",
     blocks,
+    timestamp: new Date().toISOString(),
     usage, // Include usage data if provided
     ...(additionalFields ? { additionalFields: { ...additionalFields } } : {}),
   };
@@ -407,6 +409,7 @@ export const addErrorBlockToMessage = ({
           content: error,
         },
       ],
+      timestamp: new Date().toISOString(),
     });
   }
 
@@ -430,6 +433,7 @@ export const addBangMessage = ({
         exitCode: null,
       },
     ],
+    timestamp: new Date().toISOString(),
   };
 
   return [...messages, outputMessage];
@@ -620,6 +624,7 @@ export const addNotificationMessageToMessages = ({
     id: generateMessageId(),
     role: "user",
     blocks: [block],
+    timestamp: new Date().toISOString(),
   };
 
   return [...messages, notificationMessage];

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;
+}

package/src/utils/worktreeUtils.ts

@@ -0,0 +1,288 @@
+/**
+ * Git worktree creation and removal utilities for the SDK.
+ * Used by EnterWorktree and ExitWorktree tools.
+ */
+
+import { execSync } from "node:child_process";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { getGitMainRepoRoot, getDefaultRemoteBranch } from "./gitUtils.js";
+import { logger } from "./globalLogger.js";
+
+export interface WorktreeInfo {
+  name: string;
+  path: string;
+  branch: string;
+  repoRoot: string;
+  isNew: boolean;
+  /** HEAD commit of the original branch at creation time, for dirty-check on exit */
+  originalHeadCommit?: string;
+}
+
+/**
+ * Validate a worktree name to prevent path traversal and invalid characters.
+ */
+export function validateWorktreeName(name: string): void {
+  const MAX_LENGTH = 64;
+  if (name.length > MAX_LENGTH) {
+    throw new Error(
+      `Invalid worktree name: must be ${MAX_LENGTH} characters or fewer (got ${name.length})`,
+    );
+  }
+  for (const segment of name.split("/")) {
+    if (segment === "." || segment === "..") {
+      throw new Error(
+        `Invalid worktree name "${name}": must not contain "." or ".." path segments`,
+      );
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(segment)) {
+      throw new Error(
+        `Invalid worktree name "${name}": each "/"-separated segment must be non-empty and contain only letters, digits, dots, underscores, and dashes`,
+      );
+    }
+  }
+}
+
+/**
+ * Generate a random worktree name.
+ */
+export function generateWorktreeName(): string {
+  const adjectives = [
+    "swift",
+    "calm",
+    "bold",
+    "keen",
+    "bright",
+    "cool",
+    "deep",
+    "fair",
+    "gentle",
+    "grand",
+  ];
+  const nouns = [
+    "fox",
+    "owl",
+    "hawk",
+    "wolf",
+    "bear",
+    "lynx",
+    "pike",
+    "kite",
+    "dove",
+    "stag",
+  ];
+  const adj = adjectives[Math.floor(Math.random() * adjectives.length)];
+  const noun = nouns[Math.floor(Math.random() * nouns.length)];
+  const num = Math.floor(Math.random() * 900) + 100;
+  return `${adj}-${noun}-${num}`;
+}
+
+/**
+ * Get the current HEAD commit SHA.
+ */
+export function getHeadCommit(cwd: string): string {
+  return execSync(`git -C "${cwd}" rev-parse HEAD`, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+/**
+ * Create a git worktree for use during a session.
+ */
+export function createWorktree(name: string, cwd: string): WorktreeInfo {
+  const repoRoot = getGitMainRepoRoot(cwd);
+  if (!repoRoot) {
+    throw new Error(
+      "Cannot create a worktree: not in a git repository. Configure WorktreeCreate and WorktreeRemove hooks in settings.json to use worktree isolation with other VCS systems.",
+    );
+  }
+
+  // Capture HEAD commit before creating worktree (for dirty-check on exit)
+  const originalHeadCommit = getHeadCommit(cwd);
+
+  const worktreePath = path.join(repoRoot, ".wave", "worktrees", name);
+  const branchName = `worktree-${name}`;
+  const baseBranch = getDefaultRemoteBranch(cwd);
+
+  // Ensure parent directory exists
+  const parentDir = path.dirname(worktreePath);
+  if (!fs.existsSync(parentDir)) {
+    fs.mkdirSync(parentDir, { recursive: true });
+  }
+
+  // Check if worktree already exists
+  if (fs.existsSync(worktreePath)) {
+    return {
+      name,
+      path: worktreePath,
+      branch: branchName,
+      repoRoot,
+      isNew: false,
+      originalHeadCommit,
+    };
+  }
+
+  try {
+    // Create worktree and branch
+    execSync(
+      `git worktree add -b ${branchName} "${worktreePath}" ${baseBranch}`,
+      {
+        cwd: repoRoot,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          GIT_TERMINAL_PROMPT: "0",
+          GIT_ASKPASS: "",
+        },
+      },
+    );
+
+    return {
+      name,
+      path: worktreePath,
+      branch: branchName,
+      repoRoot,
+      isNew: true,
+      originalHeadCommit,
+    };
+  } catch (error: unknown) {
+    const stderr = (error as { stderr?: Buffer }).stderr?.toString() || "";
+    if (stderr.includes("already exists")) {
+      // Branch exists but worktree doesn't — attach to existing branch
+      try {
+        execSync(`git worktree add "${worktreePath}" ${branchName}`, {
+          cwd: repoRoot,
+          stdio: ["ignore", "pipe", "pipe"],
+          env: {
+            ...process.env,
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_ASKPASS: "",
+          },
+        });
+        return {
+          name,
+          path: worktreePath,
+          branch: branchName,
+          repoRoot,
+          isNew: true,
+          originalHeadCommit,
+        };
+      } catch (innerError: unknown) {
+        throw new Error(
+          `Failed to add worktree: ${(innerError as Error).message}`,
+        );
+      }
+    }
+    throw new Error(
+      `Failed to create worktree: ${(error as Error).message}\n${stderr}`,
+    );
+  }
+}
+
+/**
+ * Remove a git worktree and its branch.
+ */
+export function removeWorktree(info: WorktreeInfo): void {
+  const repoRoot = info.repoRoot;
+
+  try {
+    // Get current branch in worktree before removing
+    let currentBranch: string | undefined;
+    try {
+      currentBranch = execSync(`git rev-parse --abbrev-ref HEAD`, {
+        cwd: info.path,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      // Ignore errors
+    }
+
+    // Remove worktree
+    execSync(`git worktree remove --force "${info.path}"`, {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    // Delete worktree branch
+    try {
+      execSync(`git branch -D ${info.branch}`, {
+        cwd: repoRoot,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } 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 {
+          execSync(`git branch -D ${currentBranch}`, {
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+          });
+        } catch {
+          // Ignore errors
+        }
+      }
+    }
+  } catch (error: unknown) {
+    logger.error("Failed to remove worktree or branch:", {
+      error: error instanceof Error ? error.message : String(error),
+      worktreePath: info.path,
+    });
+    throw error;
+  }
+}
+
+/**
+ * Count uncommitted files and new commits in a worktree.
+ * Returns null if git commands fail (fail-closed).
+ */
+export function countWorktreeChanges(
+  worktreePath: string,
+  originalHeadCommit: string | undefined,
+): { changedFiles: number; commits: number } | null {
+  try {
+    const statusOutput = execSync(
+      `git -C "${worktreePath}" status --porcelain`,
+      {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+    const changedFiles = statusOutput
+      .split("\n")
+      .filter((l) => l.trim() !== "").length;
+
+    if (!originalHeadCommit) {
+      return null;
+    }
+
+    const revListOutput = execSync(
+      `git -C "${worktreePath}" rev-list --count ${originalHeadCommit}..HEAD`,
+      {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+    const commits = parseInt(revListOutput.trim(), 10) || 0;
+
+    return { changedFiles, commits };
+  } catch {
+    return null;
+  }
+}