wave-agent-sdk 0.13.5 → 0.14.0

package/src/tools/bashTool.ts

@@ -139,7 +139,10 @@ Use the gh command via the Bash tool for GitHub-related tasks including working
 - Do not retry failing commands in a sleep loop — diagnose the root cause.
 - If waiting for a background task you started with \`run_in_background\`, you will be notified when it completes — do not poll.
 - If you must poll an external process, use a check command (e.g. \`gh run view\`) rather than sleeping first.
-- If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.`,
+- If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.
+
+# CWD management
+Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of \`cd\`. You may use \`cd\` if the User explicitly requests it. When you use \`cd\`, the shell working directory will be reset to the original working directory after the command completes.`,
   execute: async (
     args: Record<string, unknown>,
     context: ToolContext,
@@ -221,9 +224,16 @@ Use the gh command via the Bash tool for GitHub-related tasks including working
       const { id: taskId } = backgroundTaskManager.startShell(command, timeout);
       const task = backgroundTaskManager.getTask(taskId);
       const outputPath = task?.outputPath;
+      const backgroundMsg = [
+        `Command started in background with ID: ${taskId}.`,
+        `You will be notified automatically when it completes.`,
+        outputPath
+          ? `output_file: ${outputPath}`
+          : `Use ${READ_TOOL_NAME} tool with task_id="${taskId}" to read the output.`,
+      ].join("\n");
       return {
         success: true,
-        content: `Command started in background with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ` Use ${READ_TOOL_NAME} tool with task_id="${taskId}" to monitor output.`}`,
+        content: backgroundMsg,
         shortResult: `Background process ${taskId} started`,
       };
     }
@@ -446,9 +456,20 @@ Use the gh command via the Bash tool for GitHub-related tasks including working
             }
           }
 
-          // If CWD changed, call the onCwdChange callback
+          // If CWD changed, call the onCwdChange callback and add notification
+          let cwdChangedNotification = "";
           if (newCwd && newCwd !== context.workdir && context.onCwdChange) {
-            context.onCwdChange(newCwd);
+            const isInSafeZone =
+              context.permissionManager?.isPathInSafeZone?.(newCwd) ?? true;
+
+            if (isInSafeZone) {
+              context.onCwdChange(newCwd);
+            } else if (context.originalWorkdir) {
+              context.onCwdChange(context.originalWorkdir);
+              cwdChangedNotification = `Shell cwd was reset to ${context.originalWorkdir}\n`;
+            } else {
+              context.onCwdChange(newCwd);
+            }
           }
 
           const exitCode = code ?? 0;
@@ -457,7 +478,8 @@ Use the gh command via the Bash tool for GitHub-related tasks including working
 
           // Handle large output by truncation and persistence if needed
           const finalOutput =
-            combinedOutput || `Command executed with exit code: ${exitCode}`;
+            cwdChangedNotification +
+            (combinedOutput || `Command executed with exit code: ${exitCode}`);
           const content = processOutput(finalOutput);
 
           const lines = combinedOutput.trim().split("\n");

package/src/tools/types.ts

@@ -58,6 +58,7 @@ export interface ToolContext {
   abortSignal?: AbortSignal;
   backgroundTaskManager?: import("../managers/backgroundTaskManager.js").BackgroundTaskManager;
   workdir: string;
+  originalWorkdir?: string;
   /** Permission mode for this tool execution */
   permissionMode?: PermissionMode;
   /** Custom permission callback */

package/src/tools/webFetchTool.ts

@@ -1,35 +1,105 @@
 import TurndownService from "turndown";
+import { LRUCache } from "lru-cache";
 import { WEB_FETCH_TOOL_NAME } from "../constants/tools.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { logger } from "../utils/globalLogger.js";
 
+// --- Security Limits ---
+const MAX_HTTP_CONTENT_LENGTH = 10 * 1024 * 1024; // 10MB
+const FETCH_TIMEOUT_MS = 60_000; // 60s
+const MAX_REDIRECTS = 10;
+const MAX_MARKDOWN_LENGTH = 100_000;
+const USER_AGENT = "Wave-User (+https://github.com/netease-lcap/wave-agent)";
+
+// --- Cache (LRU with 15min TTL, 50MB max) ---
 const CACHE_TTL = 15 * 60 * 1000; // 15 minutes
-const cache = new Map<string, { content: string; timestamp: number }>();
+const CACHE_MAX_BYTES = 50 * 1024 * 1024; // 50MB
+
+interface CacheEntry {
+  bytes: number;
+  code: number;
+  codeText: string;
+  content: string;
+  contentType: string;
+}
+
+const cache = new LRUCache<string, CacheEntry>({
+  ttl: CACHE_TTL,
+  maxSize: CACHE_MAX_BYTES,
+  sizeCalculation: (entry) => entry.bytes,
+});
+
+// --- Helpers ---
 
-function getFromCache(url: string): string | null {
-  const cached = cache.get(url);
-  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
-    return cached.content;
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+type URLValidationResult = { valid: true } | { valid: false; error: string };
+
+function validateURL(url: string): URLValidationResult {
+  if (url.length > 2000) {
+    return {
+      valid: false,
+      error: "URL exceeds maximum length of 2000 characters",
+    };
   }
-  if (cached) {
-    cache.delete(url);
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    return {
+      valid: false,
+      error: `Invalid URL: ${error instanceof Error ? error.message : String(error)}`,
+    };
   }
-  return null;
-}
 
-function setToCache(url: string, content: string) {
-  cache.set(url, { content, timestamp: Date.now() });
+  if (parsed.username || parsed.password) {
+    return { valid: false, error: "URL must not contain username or password" };
+  }
+
+  const hostParts = parsed.hostname.split(".");
+  if (hostParts.length < 2) {
+    return {
+      valid: false,
+      error: "URL hostname must have at least two parts (e.g., example.com)",
+    };
+  }
+
+  return { valid: true };
 }
 
-// Clean up cache every 15 minutes
-setInterval(() => {
-  const now = Date.now();
-  for (const [url, cached] of cache.entries()) {
-    if (now - cached.timestamp >= CACHE_TTL) {
-      cache.delete(url);
-    }
+function isPermittedRedirect(
+  originalUrl: string,
+  redirectUrl: string,
+): boolean {
+  try {
+    const original = new URL(originalUrl);
+    const redirect = new URL(redirectUrl);
+    const origHost = original.host;
+    const redirHost = redirect.host;
+
+    // Same host
+    if (origHost === redirHost) return true;
+
+    // www. variation (e.g., example.com <-> www.example.com)
+    const bareOrig = origHost.replace(/^www\./, "");
+    const bareRedir = redirHost.replace(/^www\./, "");
+    if (bareOrig === bareRedir) return true;
+
+    return false;
+  } catch {
+    return false;
   }
-}, CACHE_TTL).unref();
+}
+
+const GITHUB_URL_ERROR =
+  "For GitHub URLs, please use the 'gh' CLI via the Bash tool instead (e.g., 'gh pr view', 'gh issue view', 'gh api').";
+
+// --- Tool ---
 
 export const webFetchTool: ToolPlugin = {
   name: WEB_FETCH_TOOL_NAME,
@@ -50,10 +120,11 @@ Usage notes:
   - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
   - The URL must be a fully-formed valid URL
   - HTTP URLs will be automatically upgraded to HTTPS
+  - Content exceeding ${formatSize(MAX_MARKDOWN_LENGTH)} will be truncated
   - The prompt should describe what information you want to extract from the page
   - This tool is read-only and does not modify any files
   - Results may be summarized if the content is very large
-  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
+  - Includes an LRU cache with a 15-minute TTL for faster responses when repeatedly accessing the same URL
   - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
   - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).`,
       parameters: {
@@ -94,92 +165,110 @@ Usage notes:
       url = "https://" + url.substring(7);
     }
 
+    // Validate URL
+    const validation = validateURL(url);
+    if (!validation.valid) {
+      return {
+        success: false,
+        content: "",
+        error: validation.error,
+      };
+    }
+
     // Check for GitHub URLs
     if (url.includes("github.com")) {
       return {
         success: false,
         content: "",
-        error:
-          "For GitHub URLs, please use the 'gh' CLI via the Bash tool instead (e.g., 'gh pr view', 'gh issue view', 'gh api').",
+        error: GITHUB_URL_ERROR,
       };
     }
 
     try {
-      let markdown = getFromCache(url);
-
-      if (!markdown) {
-        const response = await fetch(url, {
-          redirect: "manual",
-          headers: {
-            "User-Agent":
-              "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
-          },
-        });
-
-        if (response.status >= 300 && response.status < 400) {
-          const location = response.headers.get("location");
-          if (location) {
-            const redirectUrl = new URL(location, url).toString();
-            const originalHost = new URL(url).host;
-            const redirectHost = new URL(redirectUrl).host;
-
-            if (originalHost !== redirectHost) {
-              return {
-                success: true,
-                content: `REDIRECT_TO: ${redirectUrl}\nThe URL redirected to a different host. Please make a new WebFetch request with this redirect URL if you wish to continue.`,
-              };
-            }
-            // If same host, we could follow it, but the requirement says "When a URL redirects to a different host, the tool will inform you".
-            // For simplicity and following the requirement strictly, let's just return the redirect for different hosts.
-            // If it's the same host, we can try to fetch again or just return it too.
-            return {
-              success: true,
-              content: `REDIRECT_TO: ${redirectUrl}\nThe URL redirected. Please make a new WebFetch request with this redirect URL.`,
-            };
-          }
-        }
-
-        if (!response.ok) {
-          return {
-            success: false,
-            content: "",
-            error: `Failed to fetch URL: ${response.status} ${response.statusText}`,
-          };
-        }
-
-        const html = await response.text();
-        const turndownService = new TurndownService();
-        markdown = turndownService.turndown(html);
-        setToCache(url, markdown);
+      const cached = cache.get(url);
+      if (cached) {
+        const markdown = cached.content;
+        return processWithAI(
+          url,
+          prompt,
+          markdown,
+          cached.code,
+          cached.codeText,
+          context,
+        );
+      }
+
+      // Fetch with redirect following
+      const result = await fetchWithRedirects(url, context.abortSignal);
+
+      if (result.kind === "redirect") {
+        return {
+          success: true,
+          content: `REDIRECT_TO: ${result.redirectUrl}\nThe URL redirected to a different host. Please make a new WebFetch request with this redirect URL if you wish to continue.`,
+        };
+      }
+
+      if (result.kind === "error") {
+        return {
+          success: false,
+          content: "",
+          error: result.error,
+        };
+      }
+
+      const { response, finalUrl } = result;
+
+      if (!response.ok) {
+        return {
+          success: false,
+          content: "",
+          error: `Failed to fetch URL: ${response.status} ${response.statusText}`,
+        };
       }
 
-      // Process with AI
-      if (!context.aiManager || !context.aiService) {
+      const contentLengthHeader = response.headers.get("content-length");
+      const contentLength = contentLengthHeader
+        ? parseInt(contentLengthHeader, 10)
+        : null;
+      if (contentLength !== null && contentLength > MAX_HTTP_CONTENT_LENGTH) {
         return {
           success: false,
-          content: markdown,
-          error:
-            "AI Manager or AI Service not available for processing content",
+          content: "",
+          error: `Content too large: ${formatSize(contentLength)} exceeds limit of ${formatSize(MAX_HTTP_CONTENT_LENGTH)}`,
         };
       }
 
-      const modelConfig = context.aiManager.getModelConfig();
-      const fastModel = modelConfig.fastModel;
+      const html = await response.text();
+      const turndownService = new TurndownService();
+      let markdown = turndownService.turndown(html);
+
+      const markdownBytes = new TextEncoder().encode(markdown).length;
+
+      // Truncate if too large
+      if (markdown.length > MAX_MARKDOWN_LENGTH) {
+        markdown =
+          markdown.substring(0, MAX_MARKDOWN_LENGTH) +
+          `[Content truncated at ${MAX_MARKDOWN_LENGTH} characters due to length limit.]`;
+      }
 
-      const aiResponse = await context.aiService.processWebContent({
-        gatewayConfig: context.aiManager.getGatewayConfig(),
-        modelConfig: modelConfig,
+      // Store in LRU cache
+      cache.set(finalUrl, {
+        bytes: markdownBytes,
+        code: response.status,
+        codeText: response.statusText,
         content: markdown,
-        prompt: prompt,
-        model: fastModel,
-        abortSignal: context.abortSignal,
+        contentType: response.headers.get("content-type") || "",
       });
 
-      return {
-        success: true,
-        content: aiResponse.content || "",
-        shortResult: `Processed content from ${url}`,
-      };
+      return processWithAI(
+        finalUrl,
+        prompt,
+        markdown,
+        response.status,
+        response.statusText,
+        context,
+        markdownBytes,
+      );
     } catch (error) {
       logger.error(`WebFetch failed for ${url}:`, error);
       return {
@@ -193,3 +282,104 @@ Usage notes:
     return `Fetch ${params.url}`;
   },
 };
+
+// --- Fetch with redirect following ---
+
+async function fetchWithRedirects(
+  initialUrl: string,
+  abortSignal?: AbortSignal,
+  redirectCount = 0,
+): Promise<
+  | { kind: "response"; response: Response; finalUrl: string }
+  | { kind: "redirect"; redirectUrl: string }
+  | { kind: "error"; error: string }
+> {
+  if (redirectCount >= MAX_REDIRECTS) {
+    return {
+      kind: "error",
+      error: `Too many redirects (max ${MAX_REDIRECTS})`,
+    };
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  // Forward the context's abort signal if provided
+  if (abortSignal) {
+    abortSignal.addEventListener("abort", () => controller.abort(), {
+      once: true,
+    });
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(initialUrl, {
+      redirect: "manual",
+      signal: controller.signal,
+      headers: {
+        "User-Agent": USER_AGENT,
+        Accept: "text/markdown, text/html, */*",
+      },
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  if (response.status >= 300 && response.status < 400) {
+    const location = response.headers.get("location");
+    if (location) {
+      const redirectUrl = new URL(location, initialUrl).toString();
+
+      if (!isPermittedRedirect(initialUrl, redirectUrl)) {
+        return { kind: "redirect", redirectUrl };
+      }
+
+      // Follow permitted redirect recursively
+      return fetchWithRedirects(redirectUrl, abortSignal, redirectCount + 1);
+    }
+  }
+
+  return { kind: "response", response, finalUrl: initialUrl };
+}
+
+// --- AI Processing ---
+
+async function processWithAI(
+  url: string,
+  prompt: string,
+  markdown: string,
+  statusCode: number,
+  statusText: string,
+  context: ToolContext,
+  contentSize?: number,
+): Promise<ToolResult> {
+  if (!context.aiManager || !context.aiService) {
+    return {
+      success: false,
+      content: markdown,
+      error: "AI Manager or AI Service not available for processing content",
+    };
+  }
+
+  const modelConfig = context.aiManager.getModelConfig();
+  const fastModel = modelConfig.fastModel;
+
+  const aiResponse = await context.aiService.processWebContent({
+    gatewayConfig: context.aiManager.getGatewayConfig(),
+    modelConfig: modelConfig,
+    content: markdown,
+    prompt: prompt,
+    model: fastModel,
+    abortSignal: context.abortSignal,
+  });
+
+  const sizeStr =
+    contentSize !== undefined ? formatSize(contentSize) : "unknown size";
+  const statusStr = `${statusCode} ${statusText}`.trim();
+
+  return {
+    success: true,
+    content: aiResponse.content || "",
+    shortResult: `Received ${sizeStr} (${statusStr}) from ${url}`,
+  };
+}

package/src/types/messaging.ts

@@ -69,6 +69,7 @@ export interface ToolBlock {
   compactParams?: string; // Compact parameter display
   parametersChunk?: string; // Incremental parameter updates for streaming
   isManuallyBackgrounded?: boolean; // Whether the tool was manually backgrounded by the user
+  timestamp?: number; // Unix ms, set when tool result is finalized (stage="end")
 }
 
 export interface ImageBlock {

package/src/utils/convertMessagesForAPI.ts

@@ -58,7 +58,7 @@ export function convertMessagesForAPI(
       );
       if (compressBlock && compressBlock.type === "compress") {
         recentMessages.unshift({
-          role: "assistant",
+          role: "user",
           content: compressBlock.content,
         });
       }

package/src/utils/groupMessagesByApiRound.ts

@@ -0,0 +1,120 @@
+import type { Message } from "../types/index.js";
+
+export interface ApiRound {
+  messages: Message[];
+  estimatedTokens: number;
+}
+
+/**
+ * Groups messages into "API rounds" — each round corresponds to one API
+ * call-response cycle. This is critical because in agentic sessions with a
+ * single user prompt, Wave creates a new Message per API round (each recursive
+ * sendAIMessage call creates a new assistant message).
+ *
+ * Boundaries:
+ *  - A new `role: "user"` message starts a new round.
+ *  - A new `role: "assistant"` message with a different `id` starts a new round.
+ *  - A message with a `compress` block is pushed as its own round and starts a
+ *    new round after it.
+ */
+export function groupMessagesByApiRound(messages: Message[]): ApiRound[] {
+  const rounds: ApiRound[] = [];
+  let currentRound: Message[] = [];
+  let lastAssistantId: string | undefined;
+
+  for (const msg of messages) {
+    let startNewRound = false;
+
+    if (msg.role === "user") {
+      startNewRound = true;
+    } else if (msg.role === "assistant") {
+      // Compress block is always its own round
+      const hasCompress = msg.blocks.some((b) => b.type === "compress");
+      if (hasCompress) {
+        startNewRound = true;
+      } else if (msg.id !== lastAssistantId) {
+        // New assistant id starts a new round.
+        // Exception: if the current round is [user] (first assistant after a
+        // user prompt in a normal conversation), keep them together as one
+        // round. But if we already have assistant(s) in this round (agentic
+        // tool loop), the new id starts a new round.
+        const roundHasOtherAssistant = currentRound.some(
+          (m) => m.role === "assistant" && m.id !== msg.id,
+        );
+        if (roundHasOtherAssistant) {
+          startNewRound = true;
+        }
+      }
+      lastAssistantId = msg.id;
+    }
+
+    if (startNewRound && currentRound.length > 0) {
+      rounds.push({
+        messages: currentRound,
+        estimatedTokens: estimateTokens(currentRound),
+      });
+      currentRound = [];
+    }
+
+    currentRound.push(msg);
+
+    // After pushing a compress message as its own round, flush immediately
+    if (
+      msg.role === "assistant" &&
+      msg.blocks.some((b) => b.type === "compress")
+    ) {
+      rounds.push({
+        messages: currentRound,
+        estimatedTokens: estimateTokens(currentRound),
+      });
+      currentRound = [];
+    }
+  }
+
+  if (currentRound.length > 0) {
+    rounds.push({
+      messages: currentRound,
+      estimatedTokens: estimateTokens(currentRound),
+    });
+  }
+
+  return rounds;
+}
+
+/**
+ * Returns the last `roundCount` complete API rounds as a flat message array.
+ * Never splits a tool_use/tool_result pair. If fewer rounds exist, returns all.
+ */
+export function getLastApiRounds(
+  messages: Message[],
+  roundCount: number,
+): Message[] {
+  const rounds = groupMessagesByApiRound(messages);
+  const lastRounds = rounds.slice(-roundCount);
+  return lastRounds.flatMap((r) => r.messages);
+}
+
+/**
+ * Roughly estimate token count from character count (~4 chars per token).
+ */
+function estimateTokens(messages: Message[]): number {
+  let chars = 0;
+  for (const msg of messages) {
+    for (const block of msg.blocks) {
+      if ("content" in block && typeof block.content === "string") {
+        chars += block.content.length;
+      }
+      if (
+        block.type === "tool" &&
+        block.parameters &&
+        typeof block.parameters === "string"
+      ) {
+        chars += block.parameters.length;
+      }
+      if (block.type === "tool" && block.result) {
+        chars += block.result.length;
+      }
+    }
+  }
+  return Math.ceil(chars / 4);
+}

package/src/utils/messageOperations.ts

@@ -49,6 +49,7 @@ export interface UpdateToolBlockParams {
   compactParams?: string;
   parametersChunk?: string; // Incremental parameter updates for streaming
   isManuallyBackgrounded?: boolean;
+  timestamp?: number;
 }
 
 // Agent specific interfaces (without messages parameter)