wave-agent-sdk 0.16.13 → 0.17.0

package/src/prompts/planModeReminders.ts

@@ -0,0 +1,138 @@
+import {
+  ASK_USER_QUESTION_TOOL_NAME,
+  EDIT_TOOL_NAME,
+  WRITE_TOOL_NAME,
+  EXIT_PLAN_MODE_TOOL_NAME,
+  AGENT_TOOL_NAME,
+} from "../constants/tools.js";
+import {
+  EXPLORE_SUBAGENT_TYPE,
+  PLAN_SUBAGENT_TYPE,
+} from "../constants/subagents.js";
+
+export function wrapInSystemReminder(content: string): string {
+  return `<system-reminder>\n${content}\n</system-reminder>`;
+}
+
+export function buildPlanModeReminder(
+  planFilePath: string,
+  planExists: boolean,
+  isSubagent: boolean = false,
+): string {
+  const planFileInfo = planExists
+    ? `A plan file already exists at ${planFilePath}. You can read it and make incremental edits using the ${EDIT_TOOL_NAME} tool if you need to.`
+    : `No plan file exists yet. You should create your plan at ${planFilePath} using the ${WRITE_TOOL_NAME} tool if you need to.`;
+
+  const subagentPlanFileInfo = planExists
+    ? `A plan file already exists at ${planFilePath}. You can read it for context if needed.`
+    : `No plan file exists yet.`;
+
+  if (isSubagent) {
+    return wrapInSystemReminder(`Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received (for example, to make edits). Instead, your role is to explore the codebase and return your findings as text output. Do NOT attempt to write or edit any files — the parent agent will write the plan file based on your text response.
+
+## Plan File Info:
+${subagentPlanFileInfo}
+Answer the user's query comprehensively, using the ${ASK_USER_QUESTION_TOOL_NAME} tool if you need to ask the user clarifying questions. If you do use the ${ASK_USER_QUESTION_TOOL_NAME}, make sure to ask all clarifying questions you need to fully understand the user's intent before proceeding.`);
+  }
+
+  return wrapInSystemReminder(`Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including making configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.
+
+## Plan File Info:
+${planFileInfo}
+You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.
+
+## Plan Workflow
+
+### Phase 1: Initial Understanding
+Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions. Critical: In this phase you should only use the ${AGENT_TOOL_NAME} tool with subagent_type=${EXPLORE_SUBAGENT_TYPE}.
+
+1. Focus on understanding the user's request and the code associated with their request. Actively search for existing functions, utilities, and patterns that can be reused — avoid proposing new code when suitable implementations already exist.
+
+2. **Launch up to 3 ${EXPLORE_SUBAGENT_TYPE} agents IN PARALLEL** (single message, multiple tool calls) to efficiently explore the codebase.
+   - Use 1 agent when the task is isolated to known files, the user provided specific file paths, or you're making a small targeted change.
+   - Use multiple agents when: the scope is uncertain, multiple areas of the codebase are involved, or you need to understand existing patterns before planning.
+   - Quality over quantity - 3 agents maximum, but you should try to use the minimum number of agents necessary (usually just 1)
+   - If using multiple agents: Provide each agent with a specific search focus or area to explore. Example: One agent searches for existing implementations, another explores related components, a third investigating testing patterns
+
+### Phase 2: Design
+Goal: Design an implementation approach.
+
+Launch agent(s) with subagent_type=${PLAN_SUBAGENT_TYPE} to design the implementation based on the user's intent and your exploration results from Phase 1.
+
+You can launch up to 3 agent(s) in parallel.
+
+**Guidelines:**
+- **Default**: Launch at least 1 Plan agent for most tasks - it helps validate your understanding and consider alternatives
+- **Skip agents**: Only for truly trivial tasks (typo fixes, single-line changes, simple renames)
+- **Multiple agents**: Use up to 3 agents for complex tasks that benefit from different perspectives
+
+Examples of when to use multiple agents:
+- The task touches multiple parts of the codebase
+- It's a large refactor or architectural change
+- There are many edge cases to consider
+- You'd benefit from exploring different approaches
+
+Example perspectives by task type:
+- New feature: simplicity vs performance vs maintainability
+- Bug fix: root cause vs workaround vs prevention
+- Refactoring: minimal change vs clean architecture
+
+In the agent prompt:
+- Provide comprehensive background context from Phase 1 exploration including filenames and code path traces
+- Describe requirements and constraints
+- Request a detailed implementation plan
+
+### Phase 3: Review
+Goal: Review the plan(s) from Phase 2 and ensure alignment with the user's intentions.
+1. Read the critical files identified by agents to deepen your understanding
+2. Ensure that the plans align with the user's original request
+3. Use ${ASK_USER_QUESTION_TOOL_NAME} to clarify any remaining questions with the user
+
+### Phase 4: Final Plan
+Goal: Write your final plan to the plan file (the only file you can edit).
+- Begin with a **Context** section: explain why this change is being made — the problem or need it addresses, what prompted it, and the intended outcome
+- Include only your recommended approach, not all alternatives
+- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively
+- Include the paths of critical files to be modified
+- Reference existing functions and utilities you found that should be reused, with their file paths
+- Include a verification section describing how to test the changes end-to-end (run the code, use MCP tools, run tests)
+
+### Phase 5: Call ${EXIT_PLAN_MODE_TOOL_NAME}
+At the very end of your turn, once you have asked the user questions and are happy with your final plan file - you should always call ${EXIT_PLAN_MODE_TOOL_NAME} to indicate to the user that you are done planning.
+This is critical - your turn should only end with either using the ${ASK_USER_QUESTION_TOOL_NAME} tool OR calling ${EXIT_PLAN_MODE_TOOL_NAME}. Do not stop unless it's for these 2 reasons
+
+**Important:** Use ${ASK_USER_QUESTION_TOOL_NAME} ONLY to clarify requirements or choose between approaches. Use ${EXIT_PLAN_MODE_TOOL_NAME} to request plan approval. Do NOT ask about plan approval in any other way - no text questions, no AskUserQuestion. Phrases like "Is this plan okay?", "Should I proceed?", "How does this plan look?", "Any changes before we start?", or similar MUST use ${EXIT_PLAN_MODE_TOOL_NAME}.
+
+NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications using the ${ASK_USER_QUESTION_TOOL_NAME} tool. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.`);
+}
+
+export function buildPlanModeSparseReminder(planFilePath: string): string {
+  return wrapInSystemReminder(
+    `Plan mode still active (see full instructions earlier in conversation). Read-only except plan file at ${planFilePath}. End turns with ${ASK_USER_QUESTION_TOOL_NAME} or ${EXIT_PLAN_MODE_TOOL_NAME}.`,
+  );
+}
+
+export function buildPlanModeReEntryReminder(planFilePath: string): string {
+  return wrapInSystemReminder(`## Re-entering Plan Mode
+
+You are returning to plan mode after having previously exited it. A plan file exists at ${planFilePath} from your previous planning session.
+
+**Before proceeding with any new planning, you should:**
+1. Read the existing plan file to understand what was previously planned
+2. Evaluate the user's current request against that plan
+3. Decide how to proceed:
+   - **Different task**: If the user's request is for a different task—even if it's similar or related—start fresh by overwriting the existing plan
+   - **Same task, continuing**: If this is explicitly a continuation or refinement of the exact same task, modify the existing plan while cleaning up outdated or irrelevant sections
+4. Continue on with the plan process and most importantly you should always edit the plan file one way or the other before calling ${EXIT_PLAN_MODE_TOOL_NAME}
+
+Treat this as a fresh planning session. Do not assume the existing plan is relevant without evaluating it first.`);
+}
+
+export function buildExitedPlanModeReminder(
+  planFilePath?: string,
+  planExists?: boolean,
+): string {
+  return wrapInSystemReminder(`## Exited Plan Mode
+
+You have exited plan mode. You can now make edits, run tools, and take actions.${planExists ? ` The plan file is located at ${planFilePath} if you need to reference it.` : ""}`);
+}

package/src/services/aiService.ts

@@ -758,6 +758,7 @@ export interface CompactMessagesOptions {
   messages: ChatCompletionMessageParam[];
   abortSignal?: AbortSignal;
   model?: string;
+  customInstructions?: string;
 }
 
 export interface CompactMessagesResult {
@@ -835,7 +836,9 @@ export async function compactMessages(
           ...cleanedMessages,
           {
             role: "user",
-            content: `Please create a detailed summary of the conversation so far.`,
+            content: options.customInstructions
+              ? `Please create a detailed summary of the conversation so far. Pay special attention to these instructions: ${options.customInstructions}`
+              : `Please create a detailed summary of the conversation so far.`,
           },
         ],
       },

package/src/services/configurationService.ts

@@ -511,12 +511,14 @@ export class ConfigurationService {
     maxTokens?: number,
     permissionMode?: PermissionMode,
   ): ModelConfig {
-    // Resolve agent model: override > options > process.env (includes settings.json env)
+    // Resolve agent model: override > options > currentConfiguration (settings.json model, possibly remote-merged) > process.env
+    // Priority: user's explicit model field > admin's env.WAVE_MODEL default.
+    // If admin wants hard enforcement, they set the `model` scalar field (overwrites local in mergeRemoteSettings).
     const resolvedAgentModel =
       model ||
       this.options.model ||
-      process.env.WAVE_MODEL ||
-      this.currentConfiguration?.model;
+      this.currentConfiguration?.model ||
+      process.env.WAVE_MODEL;
 
     // Resolve fast model: override > options > process.env (includes settings.json env)
     const resolvedFastModel =

package/src/services/initializationService.ts

@@ -77,6 +77,9 @@ export class InitializationService {
 
     const startTime = performance.now();
 
+    // Set global logger early so managers can use it during initialization
+    setGlobalLogger(logger || null);
+
     // Initialize managers first
     try {
       const phaseStart = performance.now();
@@ -123,6 +126,19 @@ export class InitializationService {
       // Don't throw error to prevent app startup failure
     }
 
+    // Initialize remote settings (load disk cache synchronously, then fetch in background)
+    // Must happen BEFORE loadMergedConfiguration so remote env vars are available
+    try {
+      const phaseStart = performance.now();
+      await remoteSettingsService.initialize();
+      logger?.debug(
+        `Initialization Phase [Remote Settings] took ${(performance.now() - phaseStart).toFixed(2)}ms`,
+      );
+    } catch (error) {
+      logger?.error("Failed to initialize remote settings:", error);
+      // Don't throw error to prevent app startup failure - continue without remote settings
+    }
+
     // Initialize hooks configuration
     try {
       const phaseStart = performance.now();
@@ -263,9 +279,6 @@ export class InitializationService {
       logger?.error("Failed to initialize auto-memory directory:", error);
     }
 
-    // Set global logger for SDK-wide access before discovering rules
-    setGlobalLogger(logger || null);
-
     // Discover modular memory rules
     try {
       const phaseStart = performance.now();
@@ -289,18 +302,6 @@ export class InitializationService {
       // Don't throw error to prevent app startup failure - continue without live reload
     }
 
-    // Initialize remote settings (fetch server-managed config)
-    try {
-      const phaseStart = performance.now();
-      await remoteSettingsService.initialize();
-      logger?.debug(
-        `Initialization Phase [Remote Settings] took ${(performance.now() - phaseStart).toFixed(2)}ms`,
-      );
-    } catch (error) {
-      logger?.error("Failed to initialize remote settings:", error);
-      // Don't throw error to prevent app startup failure - continue without remote settings
-    }
-
     // Memory is lazy-cached on first getCombinedMemoryContent call
     // No explicit loading needed during initialization
 

package/src/tools/bashTool.ts

@@ -432,18 +432,17 @@ The working directory persists between commands. Try to maintain your current wo
           }
 
           // If CWD changed, call the onCwdChange callback and add notification
-          let cwdResetMessage: string | undefined;
+          let cwdMessage: string | undefined;
           if (newCwd && newCwd !== context.workdir && context.onCwdChange) {
             const isInSafeZone =
               context.permissionManager?.isPathInSafeZone?.(newCwd) ?? true;
 
-            if (isInSafeZone) {
-              context.onCwdChange(newCwd);
-            } else if (context.originalWorkdir) {
+            if (!isInSafeZone && context.originalWorkdir) {
               context.onCwdChange(context.originalWorkdir);
-              cwdResetMessage = `Shell cwd was reset to ${context.originalWorkdir}`;
+              cwdMessage = `Shell cwd was reset to ${context.originalWorkdir}`;
             } else {
               context.onCwdChange(newCwd);
+              cwdMessage = `Shell working directory changed to ${newCwd}`;
             }
           }
 
@@ -451,9 +450,9 @@ The working directory persists between commands. Try to maintain your current wo
           const combinedOutput =
             outputBuffer + (errorBuffer ? "\n" + errorBuffer : "");
 
-          // Prepend CWD reset message to output if present (like Claude Code's stderr approach)
+          // Prepend CWD change message to output if present
           const finalOutput =
-            (cwdResetMessage ? cwdResetMessage + "\n" : "") +
+            (cwdMessage ? cwdMessage + "\n" : "") +
             (combinedOutput || `Command executed with exit code: ${exitCode}`);
           const content = processToolResult(
             finalOutput,

package/src/tools/editTool.ts

@@ -30,6 +30,7 @@ Usage:
 - 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: {
@@ -109,6 +110,18 @@ Usage:
     // Touch file to track it in context
     context.messageManager?.touchFile(filePath);
 
+    // Enforce read-before-edit: the file must have been read first
+    if (
+      context.messageManager &&
+      !context.messageManager.hasFileInContext(filePath)
+    ) {
+      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 {
       const resolvedPath = resolvePath(filePath, context.workdir);
 
@@ -124,19 +137,23 @@ Usage:
         };
       }
 
+      // 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 = originalContent.indexOf(oldString);
-      const matchedOldString = index !== -1 ? oldString : null;
+      const index = normalizedContent.indexOf(normalizedOldString);
+      const matchedOldString = index !== -1 ? normalizedOldString : null;
       const startLineNumber =
         index !== -1
-          ? originalContent.substring(0, index).split("\n").length
+          ? normalizedContent.substring(0, index).split("\n").length
           : undefined;
 
       if (!matchedOldString) {
         return {
           success: false,
           content: "",
-          error: analyzeEditMismatch(),
+          error: analyzeEditMismatch(normalizedOldString),
         };
       }
 
@@ -146,11 +163,11 @@ Usage:
       if (replaceAll) {
         // Replace all matches
         const regex = new RegExp(escapeRegExp(matchedOldString), "g");
-        newContent = originalContent.replace(regex, newString);
-        replacementCount = (originalContent.match(regex) || []).length;
+        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 = originalContent.split(matchedOldString).length - 1;
+        const matches = normalizedContent.split(matchedOldString).length - 1;
         if (matches > 1) {
           return {
             success: false,
@@ -159,7 +176,7 @@ Usage:
           };
         }
 
-        newContent = originalContent.replace(matchedOldString, newString);
+        newContent = normalizedContent.replace(matchedOldString, newString);
         replacementCount = 1;
       }
 

package/src/tools/exitPlanMode.ts

@@ -107,6 +107,9 @@ Ensure your plan is complete and unambiguous:
         };
       }
 
+      context.permissionManager.setHasExitedPlanMode(true);
+      context.permissionManager.setNeedsPlanModeExitAttachment(true);
+
       return {
         success: true,
         content: "Plan approved. Exiting plan mode.",

package/src/types/agent.ts

@@ -30,6 +30,8 @@ export interface AgentOptions {
   /** Wave server URL for SSO authentication (fallback to WAVE_SERVER_URL env var) */
   serverUrl?: string;
   defaultHeaders?: Record<string, string>;
+  /** Per-subagent-type headers, merged into defaultHeaders for matching subagents */
+  subagentHeaders?: Record<string, Record<string, string>>;
   fetchOptions?: ClientOptions["fetchOptions"];
   fetch?: ClientOptions["fetch"];
   model?: string;

package/src/types/hooks.ts

@@ -24,7 +24,9 @@ export type HookEvent =
   | "WorktreeRemove"
   | "CwdChanged"
   | "SessionStart"
-  | "SessionEnd";
+  | "SessionEnd"
+  | "PreCompact"
+  | "PostCompact";
 
 // Individual hook command configuration
 export interface HookCommand {
@@ -117,6 +119,8 @@ export function isValidHookEvent(event: string): event is HookEvent {
     "CwdChanged",
     "SessionStart",
     "SessionEnd",
+    "PreCompact",
+    "PostCompact",
   ].includes(event);
 }
 
@@ -187,6 +191,8 @@ export interface HookJsonInput {
   source?: SessionStartSource; // Present for SessionStart events
   agent_type?: string; // Present for SessionStart events
   end_source?: SessionEndSource; // Present for SessionEnd events
+  compact_instructions?: string; // Present for PreCompact events
+  compact_summary?: string; // Present for PostCompact events
 }
 
 // Extended context interface for passing additional data to hook executor
@@ -205,6 +211,8 @@ export interface ExtendedHookExecutionContext extends HookExecutionContext {
   source?: SessionStartSource; // Session start source (SessionStart only)
   agentType?: string; // Agent type identifier (SessionStart only)
   endSource?: SessionEndSource; // Session end source (SessionEnd only)
+  compactInstructions?: string; // Custom instructions for PreCompact
+  compactSummary?: string; // Summary text for PostCompact
 }
 
 // Environment variables injected into hook processes

package/src/types/mcp.ts

@@ -4,6 +4,7 @@
  */
 
 export interface McpServerConfig {
+  type?: "stdio" | "sse" | "http";
   command?: string;
   args?: string[];
   env?: Record<string, string>;

package/src/utils/editUtils.ts

@@ -10,8 +10,11 @@ export function escapeRegExp(string: string): string {
 }
 
 /**
- * Returns a generic error message when old_string is not found.
+ * Returns an error message when old_string is not found, including
+ * the attempted string to help the model self-correct on retry.
  */
-export function analyzeEditMismatch(): string {
-  return "old_string not found in file";
+export function analyzeEditMismatch(oldString: string): string {
+  const displayString =
+    oldString.length > 200 ? oldString.substring(0, 200) + "..." : oldString;
+  return `String to replace not found in file.\nString: ${displayString}`;
 }