wave-agent-sdk 0.18.3 → 0.18.5

package/src/managers/mcpManager.ts

@@ -484,29 +484,40 @@ export class McpManager {
           stderr: "pipe", // Pipe stderr to capture it
         });
 
-        // Handle stderr output for StdioClientTransport
+        // Buffer stderr silently (MCP servers use stderr for all logging;
+        // stdout is reserved for JSON-RPC). Only dump it on connection
+        // success (once) or failure — not line-by-line in real time.
+        // Aligns with Claude Code's approach to avoid noise from [INFO],
+        // [DEBUG], Warning: lines that are not actual errors.
         const stderr = (transport as StdioClientTransport).stderr;
+        let stderrOutput = "";
         if (stderr) {
-          let buffer = "";
           stderr.on("data", (chunk: Buffer) => {
-            buffer += chunk.toString();
-            const lines = buffer.split("\n");
-            buffer = lines.pop() || "";
-            for (const line of lines) {
-              if (line.trim()) {
-                logger?.error(`[MCP Server ${name}] ${line}`);
-              }
-            }
-          });
-          stderr.on("end", () => {
-            if (buffer.trim()) {
-              logger?.error(`[MCP Server ${name}] ${buffer}`);
+            if (stderrOutput.length < 64 * 1024 * 1024) {
+              stderrOutput += chunk.toString();
             }
           });
         }
 
         client = createClient();
-        await client.connect(transport);
+        try {
+          await client.connect(transport);
+        } catch (error) {
+          if (stderrOutput.trim()) {
+            logger?.error(
+              `[MCP Server ${name}] Server stderr: ${stderrOutput.trim()}`,
+            );
+          }
+          throw error;
+        }
+
+        // Dump accumulated stderr once after successful connection
+        if (stderrOutput.trim()) {
+          logger?.debug(
+            `[MCP Server ${name}] Server stderr: ${stderrOutput.trim()}`,
+          );
+          stderrOutput = "";
+        }
 
         const toolsResponse = await client.listTools();
         tools =

package/src/managers/messageManager.ts

@@ -28,8 +28,10 @@ import {
 } from "../services/session.js";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
 import type { MemoryRuleManager } from "./MemoryRuleManager.js";
+import type { MemoryRule } from "../types/memoryRule.js";
 import type { MemoryService } from "../services/memory.js";
 import { pathEncoder } from "../utils/pathEncoder.js";
+import { READ_TOOL_NAME } from "../constants/tools.js";
 
 import { Container } from "../utils/container.js";
 
@@ -100,7 +102,8 @@ export class MessageManager {
   private callbacks: MessageManagerCallbacks;
   private transcriptPath: string; // Cached transcript path
   private savedMessageCount: number; // Track how many messages have been saved to prevent duplication
-  private filesInContext: Set<string> = new Set(); // Track files mentioned in the conversation
+  private pendingFileReadTriggers: Set<string> = new Set(); // File paths read via Read tool, awaiting rule matching
+  private loadedRuleIds: Set<string> = new Set(); // IDs of conditional rules already injected as meta messages
   private recentFileReads: Map<string, { content: string; timestamp: number }> =
     new Map(); // Track file read contents
   private invokedSkills: Map<string, { skillName: string; timestamp: number }> =
@@ -172,10 +175,27 @@ export class MessageManager {
   }
 
   /**
-   * Returns all files mentioned in the current conversation context.
+   * Process pending file read triggers: match against conditional rules,
+   * return rules not yet loaded (dedup via loadedRuleIds), mark them as loaded.
+   * Clears triggers after processing.
    */
-  public getFilesInContext(): string[] {
-    return Array.from(this.filesInContext);
+  public processTriggeredRules(): MemoryRule[] {
+    if (!this.memoryRuleManager || this.pendingFileReadTriggers.size === 0) {
+      this.pendingFileReadTriggers.clear();
+      return [];
+    }
+    const filePaths = Array.from(this.pendingFileReadTriggers);
+    this.pendingFileReadTriggers.clear();
+
+    const { conditional } =
+      this.memoryRuleManager.getActiveRulesSplit(filePaths);
+    const newRules = conditional.filter(
+      (rule) => !this.loadedRuleIds.has(rule.id),
+    );
+    for (const rule of newRules) {
+      this.loadedRuleIds.add(rule.id);
+    }
+    return newRules;
   }
 
   public getSessionDir(): string {
@@ -187,7 +207,8 @@ export class MessageManager {
   }
 
   /**
-   * Get combined memory content (project memory + user memory + modular rules)
+   * Get combined memory content (project memory + user memory + unconditional rules)
+   * Note: conditional rules are handled separately via processTriggeredRules().
    */
   public async getCombinedMemory(): Promise<string> {
     let combined = await this.memoryService.getCombinedMemoryContent(
@@ -195,17 +216,41 @@ export class MessageManager {
     );
 
     if (this.memoryRuleManager) {
-      const filesInContext = this.getFilesInContext();
-      const activeRules = this.memoryRuleManager.getActiveRules(filesInContext);
-      if (activeRules.length > 0) {
+      const { unconditional } = this.memoryRuleManager.getActiveRulesSplit([]);
+      if (unconditional.length > 0) {
         combined += "\n\n";
-        combined += activeRules.map((r) => r.content).join("\n\n");
+        combined += unconditional.map((r) => r.content).join("\n\n");
       }
     }
 
     return combined;
   }
 
+  /**
+   * Get memory content for message-array injection:
+   * - prependContent: AGENTS.md + user memory + unconditional rules (for head injection)
+   * Conditional rules are handled separately via processTriggeredRules().
+   */
+  public async getMemoryForInjection(): Promise<{
+    prependContent: string;
+  }> {
+    const baseMemory = await this.memoryService.getCombinedMemoryContent(
+      this.workdir,
+    );
+
+    let prependContent = baseMemory;
+
+    if (this.memoryRuleManager) {
+      const { unconditional } = this.memoryRuleManager.getActiveRulesSplit([]);
+      if (unconditional.length > 0) {
+        prependContent += "\n\n";
+        prependContent += unconditional.map((r) => r.content).join("\n\n");
+      }
+    }
+
+    return { prependContent };
+  }
+
   /**
    * Compute the transcript path using cached encoded workdir
    * Called during construction and when sessionId changes
@@ -243,62 +288,43 @@ export class MessageManager {
   }
 
   /**
-   * Adds a file path to the set of files in context, normalizing it if necessary.
+   * Record a file path read via the Read tool, to be matched against
+   * conditional memory rules before the next AI call.
    */
-  public touchFile(filePath: string): void {
+  public triggerFileRead(filePath: string): void {
     const normalizedPath = isAbsolute(filePath)
       ? relative(this.workdir, filePath)
       : filePath;
-    this.filesInContext.add(normalizedPath);
+    this.pendingFileReadTriggers.add(normalizedPath);
   }
 
   /**
-   * Checks if a file has been read or edited in this conversation.
+   * Check if a file has been read (for read-before-edit enforcement).
+   * Uses recentFileReads Map populated from Read tool execution.
    */
-  public hasFileInContext(filePath: string): boolean {
+  public hasFileBeenRead(filePath: string): boolean {
     const normalizedPath = isAbsolute(filePath)
       ? relative(this.workdir, filePath)
       : filePath;
-    return this.filesInContext.has(normalizedPath);
-  }
-
-  /**
-   * Extracts and adds file paths from a message's tool blocks.
-   */
-  private addPathsFromMessage(message: Message): void {
-    for (const block of message.blocks) {
-      if (block.type === "tool" && block.parameters) {
-        try {
-          const params = JSON.parse(block.parameters) as Record<
-            string,
-            unknown
-          >;
-          const paths = this.extractPathsFromParams(params);
-          for (const p of paths) {
-            this.touchFile(p);
-          }
-        } catch {
-          // Ignore parse errors
-        }
-      }
-    }
+    return (
+      this.recentFileReads.has(normalizedPath) ||
+      this.recentFileReads.has(filePath)
+    );
   }
 
   public setMessages(messages: Message[]): void {
     const oldLength = this.messages.length;
     this.messages = [...messages];
 
-    // Incrementally add paths from new messages
+    // Incrementally extract metadata from new messages
     const newMessages = messages.slice(oldLength);
     for (const message of newMessages) {
-      this.addPathsFromMessage(message);
       this.extractFileReadsFromMessage(message);
       this.extractSkillInvocationsFromMessage(message);
     }
 
     // Also check if the last message was updated (common for tool blocks)
     if (messages.length > 0 && messages.length === oldLength) {
-      this.addPathsFromMessage(messages[messages.length - 1]);
       this.extractFileReadsFromMessage(messages[messages.length - 1]);
       this.extractSkillInvocationsFromMessage(messages[messages.length - 1]);
     }
@@ -377,6 +403,9 @@ export class MessageManager {
     this.setMessages([...sessionData.messages]);
     this.setlatestTotalTokens(sessionData.metadata.latestTotalTokens);
 
+    // Rebuild loadedRuleIds from persisted meta messages (session restore)
+    this.rebuildLoadedRuleIds();
+
     // Set saved message count to the number of loaded messages since they're already saved
     // This must be done after setSessionId which resets it to 0
     this.savedMessageCount = sessionData.messages.length;
@@ -568,18 +597,9 @@ export class MessageManager {
     // Set new message list
     this.setMessages(newMessages);
 
-    // Reset and re-populate filesInContext
-    this.filesInContext.clear();
-    for (const message of this.messages) {
-      this.addPathsFromMessage(message);
-    }
-
-    // Scan compactedContent for file mentions
-    const fileMentionRegex = /(?:^|\s)@([\w.\-/]+)/g;
-    let match;
-    while ((match = fileMentionRegex.exec(compactedContent)) !== null) {
-      this.touchFile(match[1]);
-    }
+    // Clear and rebuild loaded rule IDs from remaining meta messages
+    this.clearLoadedRuleIds();
+    this.rebuildLoadedRuleIds();
 
     // Trigger compaction callback
     this.callbacks.onCompactBlockAdded?.(compactedContent);
@@ -1008,35 +1028,6 @@ export class MessageManager {
     }
   }
 
-  private extractPathsFromParams(params: Record<string, unknown>): string[] {
-    const paths: string[] = [];
-    if (typeof params !== "object" || params === null) return paths;
-
-    // Common parameter names for file paths
-    const pathKeys = [
-      "path",
-      "filePath",
-      "file_path",
-      "target_file",
-      "targetFile",
-    ];
-    for (const key of pathKeys) {
-      if (typeof params[key] === "string") {
-        paths.push(params[key]);
-      }
-    }
-
-    // Handle arrays of paths (e.g. in Glob or Grep results if we ever track those,
-    // but here we track inputs to tools)
-    if (Array.isArray(params.files)) {
-      for (const f of params.files) {
-        if (typeof f === "string") paths.push(f);
-      }
-    }
-
-    return paths;
-  }
-
   /**
    * Extract file read contents from tool result blocks in a message.
    */
@@ -1044,7 +1035,7 @@ export class MessageManager {
     for (const block of message.blocks) {
       if (
         block.type === "tool" &&
-        block.name === "read" &&
+        block.name === READ_TOOL_NAME &&
         block.stage === "end" &&
         block.result &&
         block.parameters
@@ -1143,4 +1134,30 @@ export class MessageManager {
   public clearInvokedSkills(): void {
     this.invokedSkills.clear();
   }
+
+  /**
+   * Clear the loaded rule IDs set (e.g., after compaction resets context).
+   */
+  public clearLoadedRuleIds(): void {
+    this.loadedRuleIds.clear();
+  }
+
+  /**
+   * Rebuild loadedRuleIds from persisted messages (session restore / post-compaction).
+   * Scans for <!-- rule: {ruleId} --> markers in user meta message content.
+   */
+  public rebuildLoadedRuleIds(): void {
+    for (const message of this.messages) {
+      if (message.role !== "user" || !message.isMeta) continue;
+      for (const block of message.blocks) {
+        if (block.type === "text") {
+          const content = (block as { content: string }).content;
+          const match = content.match(/<!-- rule: (.+?) -->/);
+          if (match) {
+            this.loadedRuleIds.add(match[1]);
+          }
+        }
+      }
+    }
+  }
 }

package/src/prompts/index.ts

@@ -3,7 +3,6 @@ import { ToolPlugin } from "../tools/types.js";
 import { isGitRepository } from "../utils/gitUtils.js";
 import { getCurrentWorktreeSession } from "../utils/worktreeSession.js";
 import { buildAutoMemoryPrompt } from "./autoMemory.js";
-import { PermissionMode } from "../types/permissions.js";
 import {
   EXPLORE_SUBAGENT_TYPE,
   PLAN_SUBAGENT_TYPE,
@@ -96,12 +95,12 @@ export function buildPlanModePrompt(
     : `No plan file exists yet. You should create your plan at ${planFilePath} using the ${WRITE_TOOL_NAME} tool if you need to.`;
 
   if (isSubagent) {
-    return `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, you should:
+    return `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 tasks). Instead, you should:
 
 ## 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.
-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.`;
+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 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 `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 changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.
@@ -154,14 +153,14 @@ In the agent prompt:
 ### 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
+2. Ensure 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
+- Ensure the 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)
@@ -177,6 +176,16 @@ NOTE: At any point in time through this workflow you should feel free to ask the
 
 export const DEFAULT_SYSTEM_PROMPT = BASE_SYSTEM_PROMPT;
 
+/**
+ * A block of the system prompt with cacheability metadata.
+ * Static blocks (cacheable: true) get cache_control markers for Claude models.
+ * Dynamic blocks (cacheable: false) change per-turn and must not invalidate the cache.
+ */
+export interface SystemPromptBlock {
+  text: string;
+  cacheable: boolean;
+}
+
 export const COMPACT_MESSAGES_SYSTEM_PROMPT = `You are continuing work on a software engineering task. Write a detailed continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary.
 
 First, write your analysis in <analysis> tags as a thinking scratchpad:
@@ -237,33 +246,33 @@ export function buildSystemPrompt(
   options: {
     workdir?: string;
     originalWorkdir?: string;
-    memory?: string;
     language?: string;
     isSubagent?: boolean;
     autoMemory?: {
       directory: string;
       content: string;
     };
-    permissionMode?: PermissionMode;
   } = {},
-): string {
-  let prompt = basePrompt || DEFAULT_SYSTEM_PROMPT;
-  prompt += `\n\n${DOING_TASKS_PROMPT}`;
-  prompt += `\n\n${EXECUTING_ACTIONS_PROMPT}`;
+): SystemPromptBlock[] {
+  // --- Static block (cacheable) ---
+  let staticText = basePrompt || DEFAULT_SYSTEM_PROMPT;
+  staticText += `\n\n${DOING_TASKS_PROMPT}`;
+  staticText += `\n\n${EXECUTING_ACTIONS_PROMPT}`;
 
   if (tools.length > 0) {
-    prompt += `\n\n${TOOL_POLICY}`;
+    staticText += `\n\n${TOOL_POLICY}`;
   }
 
-  prompt += `\n\n${OUTPUT_EFFICIENCY_PROMPT}`;
-  prompt += `\n\n${TONE_AND_STYLE_PROMPT}`;
+  staticText += `\n\n${OUTPUT_EFFICIENCY_PROMPT}`;
+  staticText += `\n\n${TONE_AND_STYLE_PROMPT}`;
 
-  if (options.permissionMode === "dontAsk") {
-    prompt += `\n\n# Permission Mode\nThe user has selected the 'dontAsk' permission mode. In this mode, any restricted tool call that does not match a pre-approved rule in 'permissions.allow' or 'temporaryRules' will be automatically denied without prompting the user. You will receive a 'Permission denied' error for such calls. This is intended to prevent interruptions for untrusted tools while allowing pre-approved ones to run seamlessly.`;
-  }
+  const blocks: SystemPromptBlock[] = [{ text: staticText, cacheable: true }];
+
+  // --- Dynamic block (not cacheable) ---
+  let dynamicText = "";
 
   if (options.language) {
-    prompt += `\n\n# Language\nAlways respond in ${options.language}. Use ${options.language} for all explanations, comments, and communications with the user. Technical terms and code identifiers should remain in their original form.`;
+    dynamicText += `\n\n# Language\nAlways respond in ${options.language}. Use ${options.language} for all explanations, comments, and communications with the user. Technical terms and code identifiers should remain in their original form.`;
   }
 
   if (options.workdir) {
@@ -280,7 +289,7 @@ export function buildSystemPrompt(
 
     const worktreeSession = getCurrentWorktreeSession();
 
-    prompt += `
+    dynamicText += `
 
 Here is useful information about the environment you are running in:
 <env>
@@ -295,17 +304,17 @@ Today's date: ${today}
   }
 
   if (options.autoMemory) {
-    prompt += `\n\n${buildAutoMemoryPrompt(options.autoMemory.directory)}`;
+    dynamicText += `\n\n${buildAutoMemoryPrompt(options.autoMemory.directory)}`;
     if (options.autoMemory.content.trim()) {
-      prompt += `\n\n## MEMORY.md\n\n${options.autoMemory.content}`;
+      dynamicText += `\n\n## MEMORY.md\n\n${options.autoMemory.content}`;
     }
   }
 
-  if (options.memory && options.memory.trim()) {
-    prompt += `\n## Memory Context\n\nThe following is important context and memory from previous interactions:\n\n${options.memory}`;
+  if (dynamicText.trim()) {
+    blocks.push({ text: dynamicText, cacheable: false });
   }
 
-  return prompt;
+  return blocks;
 }
 
 export function enhanceSystemPromptWithEnvDetails(

package/src/services/aiService.ts

@@ -16,6 +16,7 @@ import {
   supportsPromptCaching,
   extendUsageWithCacheMetrics,
   type ClaudeUsage,
+  type ClaudeChatCompletionContentPartText,
 } from "../utils/cacheControlUtils.js";
 
 import * as os from "os";
@@ -26,6 +27,7 @@ import {
   COMPACT_MESSAGES_SYSTEM_PROMPT,
   WEB_CONTENT_SYSTEM_PROMPT,
   BTW_SYSTEM_PROMPT,
+  type SystemPromptBlock,
 } from "../prompts/index.js";
 import { GOAL_EVALUATION_SYSTEM_PROMPT } from "../constants/goalPrompts.js";
 
@@ -159,7 +161,7 @@ export interface CallAgentOptions {
   workdir: string; // Current working directory
   tools?: ChatCompletionFunctionTool[]; // Tool configuration
   model?: string; // Custom model
-  systemPrompt?: string; // Custom system prompt
+  systemPrompt?: string | SystemPromptBlock[]; // Custom system prompt (string or structured blocks)
   maxTokens?: number; // Maximum output tokens
   toolChoice?:
     | "auto"
@@ -262,22 +264,47 @@ export async function callAgent(
       fetch: gatewayConfig.fetch,
     });
 
-    // Build system prompt content
-    const systemContent = systemPrompt || "";
+    // Determine model early (needed for system prompt construction)
+    const currentModel = model || modelConfig.model;
+    const resolvedMaxTokens = options.maxTokens ?? modelConfig.maxTokens;
 
-    // Add system prompt
-    const systemMessage: ChatCompletionMessageParam = {
-      role: "system",
-      content: systemContent,
-    };
+    // Build system message content
+    let systemMessage: ChatCompletionMessageParam;
+    if (Array.isArray(systemPrompt)) {
+      if (supportsPromptCaching(currentModel)) {
+        // For Claude models, map blocks to content parts with cache_control on cacheable blocks
+        const contentParts: ClaudeChatCompletionContentPartText[] =
+          systemPrompt.map((block) => {
+            const part: ClaudeChatCompletionContentPartText = {
+              type: "text",
+              text: block.text,
+            };
+            if (block.cacheable) {
+              part.cache_control = { type: "ephemeral" };
+            }
+            return part;
+          });
+        systemMessage = {
+          role: "system",
+          content: contentParts,
+        } as ChatCompletionMessageParam;
+      } else {
+        // For non-Claude models, join blocks into a single string
+        systemMessage = {
+          role: "system",
+          content: systemPrompt.map((b) => b.text).join("\n\n"),
+        };
+      }
+    } else {
+      systemMessage = {
+        role: "system",
+        content: systemPrompt || "",
+      };
+    }
 
     // ChatCompletionMessageParam[] is already in OpenAI format, add system prompt to the beginning
     openaiMessages = [systemMessage, ...messages];
 
-    // Apply cache control for Claude models
-    const currentModel = model || modelConfig.model;
-    const resolvedMaxTokens = options.maxTokens ?? modelConfig.maxTokens;
-
     processedTools = tools;
 
     if (supportsPromptCaching(currentModel)) {