wave-agent-sdk 1.0.4 → 1.0.6

package/src/tools/cronCreateTool.ts

@@ -1,161 +0,0 @@
-import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
-import { CRON_CREATE_TOOL_NAME } from "../constants/tools.js";
-import { cronToHuman } from "../utils/cronToHuman.js";
-import { parseCronExpression } from "../utils/parseCronExpression.js";
-
-const DEFAULT_MAX_AGE_DAYS = 7;
-const MAX_JOBS = 50;
-
-const CRON_CREATE_DESCRIPTION = `Schedule a prompt to run at a future time within this Wave session — either recurring on a cron schedule, or once at a specific time.`;
-
-const CRON_CREATE_PROMPT = `Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders.
-
-Uses standard 5-field cron in the user's local timezone: minute hour day-of-month month day-of-week. "0 9 * * *" means 9am local — no timezone conversion needed.
-
-## One-shot tasks (recurring: false)
-
-For "remind me at X" or "at <time>, do Y" requests — fire once then auto-delete.
-Pin minute/hour/day-of-month/month to specific values:
-  "remind me at 2:30pm today to check the deploy" → cron: "30 14 <today_dom> <today_month> *", recurring: false
-  "tomorrow morning, run the smoke test" → cron: "57 8 <tomorrow_dom> <tomorrow_month> *", recurring: false
-
-## Recurring jobs (recurring: true, the default)
-
-For "every N minutes" / "every hour" / "weekdays at 9am" requests:
-  "*/5 * * * *" (every 5 min), "0 * * * *" (hourly), "0 9 * * 1-5" (weekdays at 9am local)
-
-## Avoid the :00 and :30 minute marks when the task allows it
-
-Every user who asks for "9am" gets \`0 9\`, and every user who asks for "hourly" gets \`0 *\` — which means requests from across the planet land on the API at the same instant. When the user's request is approximate, pick a minute that is NOT 0 or 30:
-  "every morning around 9" → "57 8 * * *" or "3 9 * * *" (not "0 9 * * *")
-  "hourly" → "7 * * * *" (not "0 * * * *")
-  "in an hour or so, remind me to..." → pick whatever minute you land on, don't round
-
-Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.
-
-## Session-only vs durable
-
-By default, jobs live only in this Wave session — nothing is written to disk, and the job is gone when Wave exits.
-Set \`durable: true\` to persist the job to \`.wave/scheduled_tasks.json\` so it survives Wave restarts (requires the session to hold the scheduler lock).
-
-## Runtime behavior
-
-Jobs only fire while the REPL is idle (not mid-query). The scheduler adds a small deterministic jitter on top of whatever you pick: recurring tasks fire up to 10% of their period late (max 15 min); one-shot tasks landing on :00 or :30 fire up to 90s early. Picking an off-minute is still the bigger lever.
-
-Recurring tasks auto-expire after ${DEFAULT_MAX_AGE_DAYS} days — they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the ${DEFAULT_MAX_AGE_DAYS}-day limit when scheduling recurring jobs.
-
-Returns a job ID you can pass to CronDelete.`;
-
-export const cronCreateTool: ToolPlugin = {
-  name: CRON_CREATE_TOOL_NAME,
-  config: {
-    type: "function",
-    function: {
-      name: CRON_CREATE_TOOL_NAME,
-      description: CRON_CREATE_DESCRIPTION,
-      parameters: {
-        type: "object",
-        properties: {
-          cron: {
-            type: "string",
-            description:
-              'Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "*/5 * * * *" = every 5 minutes, "30 14 28 2 *" = Feb 28 at 2:30pm local once).',
-          },
-          prompt: {
-            type: "string",
-            description: "The prompt to enqueue at each fire time.",
-          },
-          recurring: {
-            type: "boolean",
-            description: `true (default) = fire on every cron match until deleted or auto-expired after ${DEFAULT_MAX_AGE_DAYS} days. false = fire once at the next match, then auto-delete. Use false for "remind me at X" one-shot requests with pinned minute/hour/dom/month.`,
-            default: true,
-          },
-          durable: {
-            type: "boolean",
-            description:
-              "true = persist job to .wave/scheduled_tasks.json so it survives Wave restarts. false (default) = session-only, removed when Wave exits.",
-            default: false,
-          },
-        },
-        required: ["cron", "prompt"],
-      },
-    },
-  },
-  prompt: () => CRON_CREATE_PROMPT,
-  execute: async (
-    args: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolResult> => {
-    const {
-      cron,
-      prompt,
-      recurring = true,
-      durable = false,
-    } = args as {
-      cron: string;
-      prompt: string;
-      recurring?: boolean;
-      durable?: boolean;
-    };
-
-    if (!context.cronManager) {
-      return {
-        success: false,
-        content: "",
-        error: "CronManager not available",
-      };
-    }
-
-    // Validate cron expression
-    if (!parseCronExpression(cron)) {
-      return {
-        success: false,
-        content: "",
-        error: `Invalid cron expression '${cron}'. Expected 5 fields: M H DoM Mon DoW.`,
-      };
-    }
-
-    // Check max jobs limit
-    const existingJobs = context.cronManager.listJobs();
-    if (existingJobs.length >= MAX_JOBS) {
-      return {
-        success: false,
-        content: "",
-        error: `Too many scheduled jobs (max ${MAX_JOBS}). Cancel one first.`,
-      };
-    }
-
-    try {
-      const job = context.cronManager.createJob({
-        cron,
-        prompt,
-        recurring,
-        durable,
-      });
-
-      const humanSchedule = cronToHuman(cron);
-      const where = durable
-        ? "Persisted to .wave/scheduled_tasks.json"
-        : "Session-only (not written to disk, dies when Wave exits)";
-      const resultMessage = recurring
-        ? `Scheduled recurring job ${job.id} (${humanSchedule}). ${where}. Auto-expires after ${DEFAULT_MAX_AGE_DAYS} days. Use CronDelete to cancel sooner.`
-        : `Scheduled one-shot task ${job.id} (${humanSchedule}). ${where}. It will fire once then auto-delete.`;
-
-      return {
-        success: true,
-        content: JSON.stringify(
-          { id: job.id, humanSchedule, recurring, durable },
-          null,
-          2,
-        ),
-        shortResult: resultMessage,
-      };
-    } catch (error) {
-      return {
-        success: false,
-        content: "",
-        error: error instanceof Error ? error.message : String(error),
-      };
-    }
-  },
-};

package/src/tools/cronDeleteTool.ts

@@ -1,51 +0,0 @@
-import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
-import { CRON_DELETE_TOOL_NAME } from "../constants/tools.js";
-
-const CRON_DELETE_DESCRIPTION = "Cancel a scheduled cron job by ID";
-
-const CRON_DELETE_PROMPT = `Cancel a cron job previously scheduled with CronCreate. Removes it from both the in-memory session store and durable file storage (if applicable).`;
-
-export const cronDeleteTool: ToolPlugin = {
-  name: CRON_DELETE_TOOL_NAME,
-  config: {
-    type: "function",
-    function: {
-      name: CRON_DELETE_TOOL_NAME,
-      description: CRON_DELETE_DESCRIPTION,
-      parameters: {
-        type: "object",
-        properties: {
-          id: {
-            type: "string",
-            description: "Job ID returned by CronCreate",
-          },
-        },
-        required: ["id"],
-      },
-    },
-  },
-  prompt: () => CRON_DELETE_PROMPT,
-  execute: async (
-    args: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolResult> => {
-    const { id } = args as { id: string };
-
-    if (!context.cronManager) {
-      return {
-        success: false,
-        content: "",
-        error: "CronManager not available",
-      };
-    }
-
-    const success = context.cronManager.deleteJob(id);
-
-    return {
-      success,
-      content: JSON.stringify({ success }, null, 2),
-      shortResult: success ? `Deleted job ${id}` : `Job ${id} not found`,
-      error: success ? undefined : `Job ${id} not found`,
-    };
-  },
-};

package/src/tools/cronListTool.ts

@@ -1,47 +0,0 @@
-import { ToolPlugin, ToolResult, ToolContext } from "./types.js";
-import { CRON_LIST_TOOL_NAME } from "../constants/tools.js";
-
-const CRON_LIST_DESCRIPTION = "List scheduled cron jobs";
-
-const CRON_LIST_PROMPT = `List all cron jobs scheduled via CronCreate in this session.`;
-
-export const cronListTool: ToolPlugin = {
-  name: CRON_LIST_TOOL_NAME,
-  config: {
-    type: "function",
-    function: {
-      name: CRON_LIST_TOOL_NAME,
-      description: CRON_LIST_DESCRIPTION,
-      parameters: {
-        type: "object",
-        properties: {},
-      },
-    },
-  },
-  prompt: () => CRON_LIST_PROMPT,
-  execute: async (
-    _args: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolResult> => {
-    if (!context.cronManager) {
-      return {
-        success: false,
-        content: "",
-        error: "CronManager not available",
-      };
-    }
-
-    const jobs = context.cronManager.listJobs();
-
-    const annotatedJobs = jobs.map((job) => ({
-      ...job,
-      scope: job.durable ? "durable" : "session-only",
-    }));
-
-    return {
-      success: true,
-      content: JSON.stringify({ jobs: annotatedJobs }, null, 2),
-      shortResult: `Found ${jobs.length} jobs`,
-    };
-  },
-};

package/src/tools/editTool.ts

@@ -1,313 +0,0 @@
-import { readFile, writeFile, stat } from "fs/promises";
-import { createHash } from "crypto";
-import { logger } from "../utils/globalLogger.js";
-import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
-import { resolvePath, getDisplayPath } from "../utils/path.js";
-import { escapeRegExp, analyzeEditMismatch } from "../utils/editUtils.js";
-import { EDIT_TOOL_NAME, READ_TOOL_NAME } from "../constants/tools.js";
-
-/**
- * Format compact parameter display
- */
-function formatCompactParams(
-  args: Record<string, unknown>,
-  context: ToolContext,
-): string {
-  const filePath = args.file_path as string;
-  return getDisplayPath(filePath || "", context.workdir);
-}
-
-/**
- * Single file edit tool plugin
- */
-export const editTool: ToolPlugin = {
-  name: EDIT_TOOL_NAME,
-  isConcurrencySafe: false,
-  formatCompactParams,
-  prompt: () =>
-    `Performs exact string replacements in files.
-
-Usage:
-- You must use your \`${READ_TOOL_NAME}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. 
-- When editing text from ${READ_TOOL_NAME} tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- Use the smallest \`old_string\` that's clearly unique — usually 2-4 adjacent lines is sufficient. Avoid including 10+ lines of context when less uniquely identifies the target. Shorter matches are less likely to contain reproduction errors.
-- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`. 
-- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`,
-  config: {
-    type: "function",
-    function: {
-      name: EDIT_TOOL_NAME,
-      description: "A tool for editing files",
-      parameters: {
-        type: "object",
-        properties: {
-          file_path: {
-            type: "string",
-            description: "The absolute path to the file to modify",
-          },
-          old_string: {
-            type: "string",
-            description: "The text to replace",
-          },
-          new_string: {
-            type: "string",
-            description:
-              "The text to replace it with (must be different from old_string)",
-          },
-          replace_all: {
-            type: "boolean",
-            default: false,
-            description: "Replace all occurences of old_string (default false)",
-          },
-        },
-        required: ["file_path", "old_string", "new_string"],
-        additionalProperties: false,
-      },
-    },
-  },
-  execute: async (
-    args: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolResult> => {
-    const filePath = args.file_path as string;
-    const oldString = args.old_string as string;
-    const newString = args.new_string as string;
-    const replaceAll = (args.replace_all as boolean) || false;
-
-    // Validate required parameters
-    if (!filePath || typeof filePath !== "string") {
-      return {
-        success: false,
-        content: "",
-        error: "file_path parameter is required and must be a string",
-      };
-    }
-
-    if (typeof oldString !== "string") {
-      return {
-        success: false,
-        content: "",
-        error: "old_string parameter is required and must be a string",
-      };
-    }
-
-    if (typeof newString !== "string") {
-      return {
-        success: false,
-        content: "",
-        error: "new_string parameter is required and must be a string",
-      };
-    }
-
-    if (oldString === newString) {
-      return {
-        success: false,
-        content: "",
-        error: "old_string and new_string must be different",
-      };
-    }
-
-    // Trigger conditional rule loading for this file
-    context.messageManager?.triggerFileRead(filePath);
-
-    // Enforce read-before-edit: the file must have been read or written first.
-    // readFileState is populated by Read, Write, and Edit tools — single source
-    // of truth, aligned with Claude Code's readFileState approach. Skipped in
-    // plan mode: permissionManager enforces a plan-file-only gate whose denial
-    // message must surface instead of being masked by a read-state rejection.
-    const resolvedPath = resolvePath(filePath, context.workdir);
-    if (
-      context.permissionMode !== "plan" &&
-      !context.readFileState?.has(resolvedPath)
-    ) {
-      return {
-        success: false,
-        content: "",
-        error: `You must read the file with the ${READ_TOOL_NAME} tool before editing it. Use ${READ_TOOL_NAME} on ${filePath} first.`,
-      };
-    }
-
-    try {
-      // Read file content
-      let originalContent: string;
-      try {
-        originalContent = await readFile(resolvedPath, "utf-8");
-      } catch (readError) {
-        return {
-          success: false,
-          content: "",
-          error: `Failed to read file: ${readError instanceof Error ? readError.message : String(readError)}`,
-        };
-      }
-
-      // Staleness check (aligned with Claude Code): only flag when the file got
-      // newer since last read. For full reads, a content-hash fallback avoids
-      // false positives when mtime changed but content didn't (git checkout,
-      // editor round-trip save, cloud sync, antivirus). Partial reads get no
-      // fallback since only a slice was cached. Skipped in plan mode (see
-      // read-before-edit note above) so the plan-file-only denial wins.
-      if (context.permissionMode !== "plan" && context.readFileState) {
-        const state = context.readFileState.get(resolvedPath);
-        if (state) {
-          const currentStats = await stat(resolvedPath);
-          if (currentStats.mtime.getTime() > state.mtime) {
-            const isFullRead =
-              state.offset === undefined && state.limit === undefined;
-            const contentUnchanged =
-              isFullRead &&
-              createHash("sha256").update(originalContent).digest("hex") ===
-                state.hash;
-            if (!contentUnchanged) {
-              return {
-                success: false,
-                content: "",
-                error:
-                  "File has been unexpectedly modified since last read. Read it again before editing it.",
-              };
-            }
-          }
-        }
-      }
-
-      // Normalize line endings for matching
-      const normalizedContent = originalContent.replace(/\r\n/g, "\n");
-      const normalizedOldString = oldString.replace(/\r\n/g, "\n");
-
-      // Check if old_string exists
-      const index = normalizedContent.indexOf(normalizedOldString);
-      const matchedOldString = index !== -1 ? normalizedOldString : null;
-      const startLineNumber =
-        index !== -1
-          ? normalizedContent.substring(0, index).split("\n").length
-          : undefined;
-
-      if (!matchedOldString) {
-        return {
-          success: false,
-          content: "",
-          error: analyzeEditMismatch(normalizedOldString),
-        };
-      }
-
-      let newContent: string;
-      let replacementCount: number;
-
-      if (replaceAll) {
-        // Replace all matches
-        const regex = new RegExp(escapeRegExp(matchedOldString), "g");
-        newContent = normalizedContent.replace(regex, newString);
-        replacementCount = (normalizedContent.match(regex) || []).length;
-      } else {
-        // Replace only the first match, but first check if it's unique
-        const matches = normalizedContent.split(matchedOldString).length - 1;
-        if (matches > 1) {
-          return {
-            success: false,
-            content: "",
-            error: `old_string appears ${matches} times in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all=true to change every instance.`,
-          };
-        }
-
-        newContent = normalizedContent.replace(matchedOldString, newString);
-        replacementCount = 1;
-      }
-
-      // Permission check after validation but before real operation
-      if (context.permissionManager) {
-        try {
-          const permissionContext = context.permissionManager.createContext(
-            EDIT_TOOL_NAME,
-            context.permissionMode || "default",
-            context.canUseToolCallback,
-            {
-              file_path: filePath,
-              old_string: oldString,
-              new_string: newString,
-              replace_all: replaceAll,
-              startLineNumber,
-            },
-            context.toolCallId,
-          );
-          const permissionResult =
-            await context.permissionManager.checkPermission(permissionContext);
-
-          if (permissionResult.behavior === "deny") {
-            return {
-              success: false,
-              content: "",
-              error: `${EDIT_TOOL_NAME} operation denied by user, reason: ${permissionResult.message || "No reason provided"}`,
-            };
-          }
-        } catch {
-          return {
-            success: false,
-            content: "",
-            error: "Permission check failed",
-          };
-        }
-      }
-
-      // Record snapshot for reversion
-      let snapshotId: string | undefined;
-      if (context.reversionManager && context.messageId) {
-        snapshotId = await context.reversionManager.recordSnapshot(
-          context.messageId,
-          resolvedPath,
-          "modify",
-        );
-      }
-
-      // Write file
-      try {
-        await writeFile(resolvedPath, newContent, "utf-8");
-        // Commit snapshot on success
-        if (context.reversionManager && snapshotId) {
-          await context.reversionManager.commitSnapshot(snapshotId);
-        }
-      } catch (writeError) {
-        return {
-          success: false,
-          content: "",
-          error: `Failed to write file: ${writeError instanceof Error ? writeError.message : String(writeError)}`,
-        };
-      }
-
-      // Update readFileState so subsequent serialized edits see fresh state
-      if (context.readFileState) {
-        const newStats = await stat(resolvedPath);
-        const hash = createHash("sha256").update(newContent).digest("hex");
-        context.readFileState.set(resolvedPath, {
-          mtime: newStats.mtime.getTime(),
-          hash,
-          offset: undefined,
-          limit: undefined,
-        });
-      }
-
-      const shortResult = replaceAll
-        ? `Replaced ${replacementCount} instances`
-        : "Text replaced successfully";
-
-      logger.debug(`Edit tool: ${shortResult}`);
-
-      return {
-        success: true,
-        content: shortResult,
-        shortResult,
-        filePath: resolvedPath,
-        startLineNumber,
-      };
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      logger.error(`Edit tool error: ${errorMessage}`);
-      return {
-        success: false,
-        content: "",
-        error: errorMessage,
-      };
-    }
-  },
-};

package/src/tools/enterPlanMode.ts

@@ -1,124 +0,0 @@
-import { logger } from "../utils/globalLogger.js";
-import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
-import { ENTER_PLAN_MODE_TOOL_NAME } from "../constants/tools.js";
-import { OPERATION_CANCELLED_BY_USER } from "../types/permissions.js";
-
-/**
- * Enter Plan Mode Tool Plugin
- */
-export const enterPlanModeTool: ToolPlugin = {
-  name: ENTER_PLAN_MODE_TOOL_NAME,
-  config: {
-    type: "function",
-    function: {
-      name: ENTER_PLAN_MODE_TOOL_NAME,
-      description:
-        "Request to enter plan mode for complex tasks requiring user approval before coding",
-      parameters: {
-        type: "object",
-        properties: {},
-        required: [],
-        additionalProperties: false,
-      },
-    },
-  },
-  prompt:
-    () => `Use this tool to proactively request entering plan mode when a task is non-trivial and benefits from planning before implementation.
-
-## When to Use This Tool
-- Multi-file changes or refactoring that requires architectural decisions
-- New features with multiple implementation steps or design trade-offs
-- Tasks where you want user approval on approach before writing code
-- Complex bug fixes that span multiple components
-
-## When NOT to Use This Tool
-- Simple fixes (typos, small logic changes in a single file)
-- Research tasks (searching files, reading code, gathering information)
-- Tasks where the implementation approach is straightforward and unambiguous
-- When already in plan mode
-
-## Examples
-
-1. Task: "Refactor the authentication system to use OAuth2" - Use EnterPlanMode to propose an approach before implementation.
-2. Task: "Add input validation to the login form" - Do NOT use EnterPlanMode, just implement it.
-3. Task: "Migrate the database schema to support multi-tenancy" - Use EnterPlanMode to plan the migration steps.
-4. Task: "Fix the off-by-one error in the pagination logic" - Do NOT use EnterPlanMode, just fix the bug.
-`,
-  execute: async (
-    _args: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolResult> => {
-    try {
-      // Runtime guard: tool is always visible but only works outside plan mode
-      if (context.permissionMode === "plan") {
-        return {
-          success: false,
-          content: "Already in plan mode. Use ExitPlanMode to exit.",
-          error: "Already in plan mode",
-        };
-      }
-
-      if (!context.permissionManager) {
-        return {
-          success: false,
-          content: "",
-          error: "Permission manager is not available",
-        };
-      }
-
-      const permissionContext = context.permissionManager.createContext(
-        ENTER_PLAN_MODE_TOOL_NAME,
-        context.permissionMode || "default",
-        context.canUseToolCallback,
-        {},
-        context.toolCallId,
-      );
-
-      // No "allow always" option for plan mode transitions (matching Claude Code behavior)
-      permissionContext.hidePersistentOption = true;
-
-      const permissionResult =
-        await context.permissionManager.checkPermission(permissionContext);
-
-      if (permissionResult.behavior === "deny") {
-        if (permissionResult.message === OPERATION_CANCELLED_BY_USER) {
-          return {
-            success: false,
-            content: OPERATION_CANCELLED_BY_USER,
-          };
-        }
-        return {
-          success: false,
-          content: `User declined to enter plan mode. Proceed in current mode.`,
-          error: permissionResult.message
-            ? undefined
-            : "Operation declined by user",
-        };
-      }
-
-      // Ensure the full plan mode transition happens (planManager + UI callback).
-      // In bypass mode the canUseTool callback is not invoked, so the transition
-      // never occurs. In normal mode, the callback already handled it
-      // (permissionResult.newPermissionMode will be set).
-      if (!permissionResult.newPermissionMode && context.toolManager) {
-        context.toolManager.requestPermissionModeChange("plan");
-      }
-
-      return {
-        success: true,
-        content:
-          "Plan mode entered successfully. Please write your plan to the plan file and use ExitPlanMode when ready for approval.",
-        shortResult: "Plan mode entered",
-      };
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      logger.error(`EnterPlanMode tool error: ${errorMessage}`);
-      return {
-        success: false,
-        content: "",
-        error: errorMessage,
-      };
-    }
-  },
-};