bashkit 0.3.1 → 0.4.0

package/dist/index.js

@@ -615,19 +615,197 @@ var DEFAULT_CONFIG = {
 // src/tools/ask-user.ts
 import { tool, zodSchema } from "ai";
 import { z } from "zod";
+
+// src/utils/debug.ts
+import { appendFileSync } from "node:fs";
+var state = {
+  mode: "off",
+  logs: [],
+  counters: new Map,
+  parentStack: []
+};
+var MAX_STRING_LENGTH = 1000;
+var MAX_ARRAY_ITEMS = 10;
+function initDebugMode() {
+  const envValue = process.env.BASHKIT_DEBUG;
+  if (!envValue) {
+    state.mode = "off";
+    return;
+  }
+  if (envValue === "1" || envValue === "stderr") {
+    state.mode = "stderr";
+  } else if (envValue === "json") {
+    state.mode = "json";
+  } else if (envValue === "memory") {
+    state.mode = "memory";
+  } else if (envValue.startsWith("file:")) {
+    state.mode = "file";
+    state.filePath = envValue.slice(5);
+  } else {
+    state.mode = "stderr";
+  }
+}
+initDebugMode();
+function isDebugEnabled() {
+  return state.mode !== "off";
+}
+function generateId(tool) {
+  const count = (state.counters.get(tool) || 0) + 1;
+  state.counters.set(tool, count);
+  return `${tool}-${count}`;
+}
+function truncateString(str) {
+  if (str.length <= MAX_STRING_LENGTH)
+    return str;
+  return `${str.slice(0, MAX_STRING_LENGTH)}... [truncated, ${str.length - MAX_STRING_LENGTH} more chars]`;
+}
+function summarize(data, depth = 0) {
+  if (depth > 5)
+    return "[nested object]";
+  if (data === null || data === undefined)
+    return data;
+  if (typeof data === "string") {
+    return truncateString(data);
+  }
+  if (typeof data === "number" || typeof data === "boolean") {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    const truncated = data.length > MAX_ARRAY_ITEMS;
+    const items = data.slice(0, MAX_ARRAY_ITEMS).map((item) => summarize(item, depth + 1));
+    if (truncated) {
+      return [...items, `[${data.length - MAX_ARRAY_ITEMS} more items]`];
+    }
+    return items;
+  }
+  if (typeof data === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      result[key] = summarize(value, depth + 1);
+    }
+    return result;
+  }
+  return String(data);
+}
+function emitEvent(event) {
+  if (state.mode === "off")
+    return;
+  switch (state.mode) {
+    case "memory":
+      state.logs.push(event);
+      break;
+    case "json":
+      process.stderr.write(`${JSON.stringify(event)}
+`);
+      break;
+    case "file":
+      if (state.filePath) {
+        appendFileSync(state.filePath, `${JSON.stringify(event)}
+`);
+      }
+      break;
+    case "stderr":
+    default:
+      formatHumanReadable(event);
+      break;
+  }
+}
+function formatHumanReadable(event) {
+  const indent = "  ".repeat(state.parentStack.length);
+  if (event.event === "start") {
+    const inputSummary = event.input ? Object.entries(event.input).map(([k, v]) => `${k}=${JSON.stringify(v)}`).slice(0, 3).join(" ") : "";
+    process.stderr.write(`${indent}[bashkit:${event.tool}] → ${inputSummary}
+`);
+  } else if (event.event === "end") {
+    const summaryStr = event.summary ? Object.entries(event.summary).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(" ") : "";
+    process.stderr.write(`${indent}[bashkit:${event.tool}] ← ${event.duration_ms}ms ${summaryStr}
+`);
+  } else if (event.event === "error") {
+    process.stderr.write(`${indent}[bashkit:${event.tool}] ✗ ${event.error}
+`);
+  }
+}
+function debugStart(tool, input) {
+  if (state.mode === "off")
+    return "";
+  const id = generateId(tool);
+  const parent = state.parentStack.length > 0 ? state.parentStack[state.parentStack.length - 1] : undefined;
+  const event = {
+    id,
+    ts: Date.now(),
+    tool,
+    event: "start",
+    input: input ? summarize(input) : undefined,
+    parent
+  };
+  emitEvent(event);
+  return id;
+}
+function debugEnd(id, tool, options) {
+  if (state.mode === "off" || !id)
+    return;
+  const event = {
+    id,
+    ts: Date.now(),
+    tool,
+    event: "end",
+    output: options.output ? summarize(options.output) : undefined,
+    summary: options.summary,
+    duration_ms: options.duration_ms
+  };
+  emitEvent(event);
+}
+function debugError(id, tool, error) {
+  if (state.mode === "off" || !id)
+    return;
+  const event = {
+    id,
+    ts: Date.now(),
+    tool,
+    event: "error",
+    error: error instanceof Error ? error.message : error
+  };
+  emitEvent(event);
+}
+function pushParent(id) {
+  if (state.mode === "off" || !id)
+    return;
+  state.parentStack.push(id);
+}
+function popParent() {
+  if (state.mode === "off")
+    return;
+  state.parentStack.pop();
+}
+function getDebugLogs() {
+  return [...state.logs];
+}
+function clearDebugLogs() {
+  state.logs = [];
+  state.counters.clear();
+  state.parentStack = [];
+}
+function reinitDebugMode() {
+  state.logs = [];
+  state.counters.clear();
+  state.parentStack = [];
+  initDebugMode();
+}
+
+// src/tools/ask-user.ts
 var questionOptionSchema = z.object({
   label: z.string().describe("The display text for this option. Should be concise (1-5 words). Add '(Recommended)' suffix for suggested options."),
-  description: z.string().optional().describe("Explanation of what this option means or its implications.")
+  description: z.string().nullable().default(null).describe("Explanation of what this option means or its implications.")
 });
 var structuredQuestionSchema = z.object({
-  header: z.string().optional().describe("Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'."),
+  header: z.string().nullable().default(null).describe("Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'."),
   question: z.string().describe("The complete question to ask the user. Should be clear and specific."),
-  options: z.array(questionOptionSchema).min(2).max(4).optional().describe("Available choices for this question. 2-4 options. An 'Other' option is automatically available to users."),
-  multiSelect: z.boolean().optional().describe("Set to true to allow the user to select multiple options instead of just one.")
+  options: z.array(questionOptionSchema).min(2).max(4).nullable().default(null).describe("Available choices for this question. 2-4 options. An 'Other' option is automatically available to users."),
+  multiSelect: z.boolean().nullable().default(null).describe("Set to true to allow the user to select multiple options instead of just one.")
 });
 var askUserInputSchema = z.object({
-  question: z.string().optional().describe("Simple question string (for backward compatibility). Use 'questions' for structured multi-choice."),
-  questions: z.array(structuredQuestionSchema).min(1).max(4).optional().describe("Structured questions with options (1-4 questions).")
+  question: z.string().nullable().default(null).describe("Simple question string (for backward compatibility). Use 'questions' for structured multi-choice."),
+  questions: z.array(structuredQuestionSchema).min(1).max(4).nullable().default(null).describe("Structured questions with options (1-4 questions).")
 });
 var ASK_USER_DESCRIPTION = `Use this tool when you need to ask the user questions during execution.
 
@@ -664,22 +842,46 @@ function createAskUserTool(config) {
     description: ASK_USER_DESCRIPTION,
     inputSchema: zodSchema(askUserInputSchema),
     execute: async (input) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("ask-user", {
+        hasQuestion: !!input.question,
+        questionCount: input.questions?.length ?? 0,
+        question: input.question ? input.question.length > 100 ? `${input.question.slice(0, 100)}...` : input.question : undefined
+      }) : "";
       try {
         if (!input.question && !input.questions) {
-          return {
-            error: "Either 'question' or 'questions' must be provided"
-          };
+          const error2 = "Either 'question' or 'questions' must be provided";
+          if (debugId)
+            debugError(debugId, "ask-user", error2);
+          return { error: error2 };
         }
         if (input.questions && input.questions.length > 0) {
           if (normalizedConfig.onStructuredQuestions) {
             const answers = await normalizedConfig.onStructuredQuestions(input.questions);
             const firstKey = Object.keys(answers)[0];
             const firstAnswer = answers[firstKey];
+            const durationMs2 = Math.round(performance.now() - startTime);
+            if (debugId) {
+              debugEnd(debugId, "ask-user", {
+                summary: {
+                  type: "structured",
+                  answerCount: Object.keys(answers).length
+                },
+                duration_ms: durationMs2
+              });
+            }
             return {
               answer: Array.isArray(firstAnswer) ? firstAnswer.join(", ") : firstAnswer,
               answers
             };
           }
+          const durationMs = Math.round(performance.now() - startTime);
+          if (debugId) {
+            debugEnd(debugId, "ask-user", {
+              summary: { type: "structured", awaiting: true },
+              duration_ms: durationMs
+            });
+          }
           return {
             questions: input.questions,
             awaiting_response: true
@@ -688,18 +890,36 @@ function createAskUserTool(config) {
         if (input.question) {
           if (normalizedConfig.onQuestion) {
             const answer = await normalizedConfig.onQuestion(input.question);
+            const durationMs2 = Math.round(performance.now() - startTime);
+            if (debugId) {
+              debugEnd(debugId, "ask-user", {
+                summary: { type: "simple", hasAnswer: true },
+                duration_ms: durationMs2
+              });
+            }
             return { answer };
           }
+          const durationMs = Math.round(performance.now() - startTime);
+          if (debugId) {
+            debugEnd(debugId, "ask-user", {
+              summary: { type: "simple", awaiting: true },
+              duration_ms: durationMs
+            });
+          }
           return {
             question: input.question,
             awaiting_response: true
           };
         }
-        return { error: "No question provided" };
+        const error = "No question provided";
+        if (debugId)
+          debugError(debugId, "ask-user", error);
+        return { error };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "ask-user", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -710,9 +930,9 @@ import { tool as tool2, zodSchema as zodSchema2 } from "ai";
 import { z as z2 } from "zod";
 var bashInputSchema = z2.object({
   command: z2.string().describe("The command to execute"),
-  timeout: z2.number().optional().describe("Optional timeout in milliseconds (max 600000)"),
-  description: z2.string().optional().describe("Clear, concise description of what this command does in 5-10 words"),
-  run_in_background: z2.boolean().optional().describe("Set to true to run this command in the background")
+  timeout: z2.number().nullable().default(null).describe("Optional timeout in milliseconds (max 600000)"),
+  description: z2.string().nullable().default(null).describe("Clear, concise description of what this command does in 5-10 words"),
+  run_in_background: z2.boolean().nullable().default(null).describe("Set to true to run this command in the background")
 });
 var BASH_DESCRIPTION = `Executes a bash command in a persistent shell session with optional timeout.
 
@@ -763,12 +983,18 @@ function createBashTool(sandbox, config) {
       description: _description,
       run_in_background: _run_in_background
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("bash", {
+        command: command.length > 200 ? `${command.slice(0, 200)}...` : command,
+        timeout
+      }) : "";
       if (config?.blockedCommands) {
         for (const blocked of config.blockedCommands) {
           if (command.includes(blocked)) {
-            return {
-              error: `Command blocked: contains '${blocked}'`
-            };
+            const error = `Command blocked: contains '${blocked}'`;
+            if (debugId)
+              debugError(debugId, "bash", error);
+            return { error };
           }
         }
       }
@@ -787,6 +1013,18 @@ function createBashTool(sandbox, config) {
           stderr = stderr.slice(0, maxOutputLength) + `
 [output truncated, ${stderr.length - maxOutputLength} chars omitted]`;
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "bash", {
+            summary: {
+              exitCode: result.exitCode,
+              stdoutLen: result.stdout.length,
+              stderrLen: result.stderr.length,
+              interrupted: result.interrupted
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           stdout,
           stderr,
@@ -795,9 +1033,10 @@ function createBashTool(sandbox, config) {
           duration_ms: result.durationMs
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "bash", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -810,7 +1049,7 @@ var editInputSchema = z3.object({
   file_path: z3.string().describe("The absolute path to the file to modify"),
   old_string: z3.string().describe("The text to replace"),
   new_string: z3.string().describe("The text to replace it with (must be different from old_string)"),
-  replace_all: z3.boolean().optional().describe("Replace all occurrences of old_string (default false)")
+  replace_all: z3.boolean().nullable().default(null).describe("Replace all occurrences of old_string (default false)")
 });
 var EDIT_DESCRIPTION = `Performs exact string replacements in files.
 
@@ -840,31 +1079,51 @@ function createEditTool(sandbox, config) {
       file_path,
       old_string,
       new_string,
-      replace_all = false
+      replace_all: rawReplaceAll
     }) => {
+      const replace_all = rawReplaceAll ?? false;
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("edit", {
+        file_path,
+        old_string: old_string.length > 100 ? `${old_string.slice(0, 100)}...` : old_string,
+        replace_all
+      }) : "";
       if (old_string === new_string) {
-        return { error: "old_string and new_string must be different" };
+        const error = "old_string and new_string must be different";
+        if (debugId)
+          debugError(debugId, "edit", error);
+        return { error };
       }
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => file_path.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${file_path}` };
+          const error = `Path not allowed: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
       }
       try {
         const exists = await sandbox.fileExists(file_path);
         if (!exists) {
-          return { error: `File not found: ${file_path}` };
+          const error = `File not found: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
         const content = await sandbox.readFile(file_path);
         const occurrences = content.split(old_string).length - 1;
         if (occurrences === 0) {
-          return { error: `String not found in file: "${old_string}"` };
+          const error = `String not found in file: "${old_string}"`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
         if (!replace_all && occurrences > 1) {
-          return {
-            error: `String appears ${occurrences} times in file. Use replace_all=true to replace all, or provide a more unique string.`
-          };
+          const error = `String appears ${occurrences} times in file. Use replace_all=true to replace all, or provide a more unique string.`;
+          if (debugId)
+            debugError(debugId, "edit", error);
+          return { error };
         }
         let newContent;
         let replacements;
@@ -876,15 +1135,23 @@ function createEditTool(sandbox, config) {
           replacements = 1;
         }
         await sandbox.writeFile(file_path, newContent);
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "edit", {
+            summary: { replacements },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: `Successfully edited ${file_path}`,
           file_path,
           replacements
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "edit", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -951,33 +1218,44 @@ In plan mode, you'll:
 - This tool REQUIRES user approval - they must consent to entering plan mode
 - If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
 - Users appreciate being consulted before significant changes`;
-function createEnterPlanModeTool(state, onEnter) {
+function createEnterPlanModeTool(state2, onEnter) {
   return tool4({
     description: ENTER_PLAN_MODE_DESCRIPTION,
     inputSchema: zodSchema4(enterPlanModeInputSchema),
     execute: async ({
       reason
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("enter-plan-mode", { reason }) : "";
       try {
-        if (state.isActive) {
-          return {
-            error: "Already in planning mode. Use ExitPlanMode to exit."
-          };
+        if (state2.isActive) {
+          const error = "Already in planning mode. Use ExitPlanMode to exit.";
+          if (debugId)
+            debugError(debugId, "enter-plan-mode", error);
+          return { error };
         }
-        state.isActive = true;
-        state.enteredAt = new Date;
-        state.reason = reason;
+        state2.isActive = true;
+        state2.enteredAt = new Date;
+        state2.reason = reason;
         if (onEnter) {
           await onEnter(reason);
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "enter-plan-mode", {
+            summary: { mode: "planning" },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: `Entered planning mode: ${reason}. Use Read, Grep, and Glob to explore. Call ExitPlanMode when ready with a plan.`,
           mode: "planning"
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "enter-plan-mode", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1017,19 +1295,32 @@ function createExitPlanModeTool(onPlanSubmit) {
     execute: async ({
       plan
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("exit-plan-mode", {
+        planLength: plan.length,
+        planPreview: plan.length > 200 ? `${plan.slice(0, 200)}...` : plan
+      }) : "";
       try {
         let approved;
         if (onPlanSubmit) {
           approved = await onPlanSubmit(plan);
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "exit-plan-mode", {
+            summary: { approved },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: approved ? "Plan approved, proceeding with execution" : "Plan submitted for review",
           approved
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "exit-plan-mode", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1040,7 +1331,7 @@ import { tool as tool6, zodSchema as zodSchema6 } from "ai";
 import { z as z6 } from "zod";
 var globInputSchema = z6.object({
   pattern: z6.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js", "*.md")'),
-  path: z6.string().optional().describe("Directory to search in (defaults to working directory)")
+  path: z6.string().nullable().default(null).describe("Directory to search in (defaults to working directory)")
 });
 var GLOB_DESCRIPTION = `
 - Fast file pattern matching tool that works with any codebase size
@@ -1061,29 +1352,48 @@ function createGlobTool(sandbox, config) {
       pattern,
       path
     }) => {
-      const searchPath = path || ".";
+      const searchPath = path ?? ".";
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("glob", { pattern, path: searchPath }) : "";
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => searchPath.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${searchPath}` };
+          const error = `Path not allowed: ${searchPath}`;
+          if (debugId)
+            debugError(debugId, "glob", error);
+          return { error };
         }
       }
       try {
-        const result = await sandbox.exec(`find ${searchPath} -type f -name "${pattern}" 2>/dev/null | head -1000`, { timeout: config?.timeout });
+        const findFlag = pattern.includes("/") ? "-path" : "-name";
+        const findPattern = pattern.includes("/") && !pattern.startsWith("*") ? `*/${pattern}` : pattern;
+        const result = await sandbox.exec(`find ${searchPath} -type f ${findFlag} "${findPattern}" 2>/dev/null | head -1000`, { timeout: config?.timeout });
         if (result.exitCode !== 0 && result.stderr) {
-          return { error: result.stderr };
+          const error = result.stderr;
+          if (debugId)
+            debugError(debugId, "glob", error);
+          return { error };
         }
         const matches = result.stdout.split(`
 `).filter(Boolean).map((p) => p.trim());
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "glob", {
+            summary: { count: matches.length },
+            output: matches.slice(0, 10),
+            duration_ms: durationMs
+          });
+        }
         return {
           matches,
           count: matches.length,
           search_path: searchPath
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "glob", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1094,18 +1404,18 @@ import { tool as tool7, zodSchema as zodSchema7 } from "ai";
 import { z as z7 } from "zod";
 var grepInputSchema = z7.object({
   pattern: z7.string().describe("The regular expression pattern to search for in file contents"),
-  path: z7.string().optional().describe("File or directory to search in (defaults to cwd)"),
-  glob: z7.string().optional().describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
-  type: z7.string().optional().describe('File type to search (e.g. "js", "py", "rust")'),
-  output_mode: z7.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts'),
-  "-i": z7.boolean().optional().describe("Case insensitive search"),
-  "-n": z7.boolean().optional().describe("Show line numbers in output. Requires output_mode: 'content'. Defaults to true."),
-  "-B": z7.number().optional().describe("Number of lines to show before each match. Requires output_mode: 'content'."),
-  "-A": z7.number().optional().describe("Number of lines to show after each match. Requires output_mode: 'content'."),
-  "-C": z7.number().optional().describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
-  head_limit: z7.number().optional().describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
-  offset: z7.number().optional().describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
-  multiline: z7.boolean().optional().describe("Enable multiline mode where patterns can span lines. Default: false.")
+  path: z7.string().nullable().default(null).describe("File or directory to search in (defaults to cwd)"),
+  glob: z7.string().nullable().default(null).describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
+  type: z7.string().nullable().default(null).describe('File type to search (e.g. "js", "py", "rust")'),
+  output_mode: z7.enum(["content", "files_with_matches", "count"]).nullable().default(null).describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts'),
+  "-i": z7.boolean().nullable().default(null).describe("Case insensitive search"),
+  "-n": z7.boolean().nullable().default(null).describe("Show line numbers in output. Requires output_mode: 'content'. Defaults to true."),
+  "-B": z7.number().nullable().default(null).describe("Number of lines to show before each match. Requires output_mode: 'content'."),
+  "-A": z7.number().nullable().default(null).describe("Number of lines to show after each match. Requires output_mode: 'content'."),
+  "-C": z7.number().nullable().default(null).describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
+  head_limit: z7.number().nullable().default(null).describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
+  offset: z7.number().nullable().default(null).describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
+  multiline: z7.boolean().nullable().default(null).describe("Enable multiline mode where patterns can span lines. Default: false.")
 });
 var GREP_DESCRIPTION = `A powerful content search tool built on ripgrep with regex support.
 
@@ -1140,27 +1450,43 @@ function createGrepTool(sandbox, config) {
         path,
         glob,
         type,
-        output_mode = "files_with_matches",
+        output_mode: rawOutputMode,
         "-i": caseInsensitive,
         "-B": beforeContext,
         "-A": afterContext,
         "-C": context,
         head_limit,
-        offset = 0,
+        offset: rawOffset,
         multiline
       } = input;
+      const output_mode = rawOutputMode ?? "files_with_matches";
+      const offset = rawOffset ?? 0;
       const searchPath = path || ".";
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("grep", {
+        pattern,
+        path: searchPath,
+        output_mode,
+        glob,
+        type,
+        caseInsensitive,
+        multiline
+      }) : "";
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => searchPath.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${searchPath}` };
+          const error = `Path not allowed: ${searchPath}`;
+          if (debugId)
+            debugError(debugId, "grep", error);
+          return { error };
         }
       }
       try {
         if (!sandbox.rgPath) {
-          return {
-            error: "Ripgrep not available. Call ensureSandboxTools(sandbox) before using Grep with remote sandboxes."
-          };
+          const error = "Ripgrep not available. Call ensureSandboxTools(sandbox) before using Grep with remote sandboxes.";
+          if (debugId)
+            debugError(debugId, "grep", error);
+          return { error };
         }
         const cmd = buildRipgrepCommand({
           rgPath: sandbox.rgPath,
@@ -1176,17 +1502,48 @@ function createGrepTool(sandbox, config) {
           multiline
         });
         const result = await sandbox.exec(cmd, { timeout: config?.timeout });
+        const durationMs = Math.round(performance.now() - startTime);
+        let output;
         if (output_mode === "files_with_matches") {
-          return parseFilesOutput(result.stdout);
+          output = parseFilesOutput(result.stdout);
+          if (debugId) {
+            debugEnd(debugId, "grep", {
+              summary: {
+                fileCount: output.count,
+                exitCode: result.exitCode
+              },
+              duration_ms: durationMs
+            });
+          }
         } else if (output_mode === "count") {
-          return parseCountOutput(result.stdout);
+          output = parseCountOutput(result.stdout);
+          if (debugId) {
+            debugEnd(debugId, "grep", {
+              summary: {
+                total: output.total,
+                exitCode: result.exitCode
+              },
+              duration_ms: durationMs
+            });
+          }
         } else {
-          return parseContentOutput(result.stdout, head_limit, offset);
+          output = parseContentOutput(result.stdout, head_limit, offset);
+          if (debugId) {
+            debugEnd(debugId, "grep", {
+              summary: {
+                matchCount: output.total_matches,
+                exitCode: result.exitCode
+              },
+              duration_ms: durationMs
+            });
+          }
         }
+        return output;
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "grep", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1253,7 +1610,7 @@ function parseCountOutput(stdout) {
     total
   };
 }
-function parseContentOutput(stdout, head_limit, offset = 0) {
+function parseContentOutput(stdout, head_limit, offset) {
   const fileData = new Map;
   for (const line of stdout.split(`
 `).filter(Boolean)) {
@@ -1350,8 +1707,8 @@ import { tool as tool8, zodSchema as zodSchema8 } from "ai";
 import { z as z8 } from "zod";
 var readInputSchema = z8.object({
   file_path: z8.string().describe("Absolute path to file or directory"),
-  offset: z8.number().optional().describe("Line number to start reading from (1-indexed)"),
-  limit: z8.number().optional().describe("Maximum number of lines to read")
+  offset: z8.number().nullable().default(null).describe("Line number to start reading from (1-indexed)"),
+  limit: z8.number().nullable().default(null).describe("Maximum number of lines to read")
 });
 var READ_DESCRIPTION = `Reads a file from the local filesystem. You can access any file directly by using this tool.
 Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
@@ -1377,20 +1734,35 @@ function createReadTool(sandbox, config) {
       offset,
       limit
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("read", { file_path, offset, limit }) : "";
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => file_path.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${file_path}` };
+          const error = `Path not allowed: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "read", error);
+          return { error };
         }
       }
       try {
         const exists = await sandbox.fileExists(file_path);
         if (!exists) {
-          return { error: `Path not found: ${file_path}` };
+          const error = `Path not found: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "read", error);
+          return { error };
         }
         const isDir = await sandbox.isDirectory(file_path);
         if (isDir) {
           const entries = await sandbox.readDir(file_path);
+          const durationMs2 = Math.round(performance.now() - startTime);
+          if (debugId) {
+            debugEnd(debugId, "read", {
+              summary: { type: "directory", count: entries.length },
+              duration_ms: durationMs2
+            });
+          }
           return {
             type: "directory",
             entries,
@@ -1416,9 +1788,10 @@ function createReadTool(sandbox, config) {
             "dylib"
           ];
           if (binaryExtensions.includes(ext || "")) {
-            return {
-              error: `Cannot read binary file: ${file_path} (file exists, ${content.length} bytes). Use appropriate tools to process ${ext?.toUpperCase()} files (e.g., Python scripts for PDFs).`
-            };
+            const error = `Cannot read binary file: ${file_path} (file exists, ${content.length} bytes). Use appropriate tools to process ${ext?.toUpperCase()} files (e.g., Python scripts for PDFs).`;
+            if (debugId)
+              debugError(debugId, "read", error);
+            return { error };
           }
         }
         const allLines = content.split(`
@@ -1426,9 +1799,10 @@ function createReadTool(sandbox, config) {
         const totalLines = allLines.length;
         const maxLinesWithoutLimit = config?.maxFileSize || 500;
         if (!limit && totalLines > maxLinesWithoutLimit) {
-          return {
-            error: `File is large (${totalLines} lines). Use 'offset' and 'limit' to read in chunks. Example: offset=1, limit=100 for first 100 lines.`
-          };
+          const error = `File is large (${totalLines} lines). Use 'offset' and 'limit' to read in chunks. Example: offset=1, limit=100 for first 100 lines.`;
+          if (debugId)
+            debugError(debugId, "read", error);
+          return { error };
         }
         const startLine = offset ? offset - 1 : 0;
         const endLine = limit ? startLine + limit : allLines.length;
@@ -1437,6 +1811,18 @@ function createReadTool(sandbox, config) {
           line_number: startLine + i + 1,
           content: line
         }));
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "read", {
+            summary: {
+              type: "text",
+              totalLines,
+              returnedLines: lines.length,
+              bytes: content.length
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           type: "text",
           content: selectedLines.join(`
@@ -1445,9 +1831,10 @@ function createReadTool(sandbox, config) {
           total_lines: totalLines
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "read", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1481,22 +1868,29 @@ function createSkillTool(config) {
     execute: async ({
       name
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("skill", { name, availableSkills: Object.keys(skills) }) : "";
       try {
         const skill = skills[name];
         if (!skill) {
           const available = Object.keys(skills);
           if (available.length === 0) {
-            return { error: "No skills are available." };
+            const error2 = "No skills are available.";
+            if (debugId)
+              debugError(debugId, "skill", error2);
+            return { error: error2 };
           }
-          return {
-            error: `Skill '${name}' not found. Available skills: ${available.join(", ")}`
-          };
+          const error = `Skill '${name}' not found. Available skills: ${available.join(", ")}`;
+          if (debugId)
+            debugError(debugId, "skill", error);
+          return { error };
         }
         let instructions;
         if (!sandbox) {
-          return {
-            error: `Cannot load skill '${name}': no sandbox provided to read ${skill.path}`
-          };
+          const error = `Cannot load skill '${name}': no sandbox provided to read ${skill.path}`;
+          if (debugId)
+            debugError(debugId, "skill", error);
+          return { error };
         }
         const content = await sandbox.readFile(skill.path);
         const frontmatterEnd = content.indexOf(`
@@ -1509,6 +1903,17 @@ function createSkillTool(config) {
         if (onActivate) {
           await onActivate(skill, instructions);
         }
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "skill", {
+            summary: {
+              skillName: skill.name,
+              instructionLength: instructions.length,
+              hasAllowedTools: !!skill.allowedTools
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           name: skill.name,
           instructions,
@@ -1516,9 +1921,10 @@ function createSkillTool(config) {
           message: skill.allowedTools ? `Skill '${name}' activated. Restricted to tools: ${skill.allowedTools.join(", ")}` : `Skill '${name}' activated. Follow the instructions below.`
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "skill", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1613,6 +2019,11 @@ function createWebFetchTool(config) {
     providerOptions,
     execute: async (input) => {
       const { url, prompt } = input;
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("web-fetch", {
+        url,
+        prompt: prompt.length > 200 ? `${prompt.slice(0, 200)}...` : prompt
+      }) : "";
       try {
         const { content, finalUrl } = await fetchContent(url, apiKey, provider);
         const result = await generateText({
@@ -1623,6 +2034,16 @@ Content from ${url}:
 
 ${content}`
         });
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "web-fetch", {
+            summary: {
+              contentLength: content.length,
+              responseLength: result.text.length
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           response: result.text,
           url,
@@ -1632,15 +2053,18 @@ ${content}`
         if (error && typeof error === "object" && "status" in error) {
           const statusCode = error.status;
           const message = error.message || "API request failed";
+          if (debugId)
+            debugError(debugId, "web-fetch", `${message} (status: ${statusCode})`);
           return {
             error: message,
             status_code: statusCode,
             retryable: RETRYABLE_STATUS_CODES.includes(statusCode)
           };
         }
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "web-fetch", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1697,8 +2121,8 @@ async function searchContent(apiKey, provider, options) {
 }
 var webSearchInputSchema = z11.object({
   query: z11.string().describe("The search query to use"),
-  allowed_domains: z11.array(z11.string()).optional().describe("Only include results from these domains"),
-  blocked_domains: z11.array(z11.string()).optional().describe("Never include results from these domains")
+  allowed_domains: z11.array(z11.string()).nullable().default(null).describe("Only include results from these domains"),
+  blocked_domains: z11.array(z11.string()).nullable().default(null).describe("Never include results from these domains")
 });
 var WEB_SEARCH_DESCRIPTION = `Searches the web and returns results with links. Use this for accessing up-to-date information beyond your knowledge cutoff.
 
@@ -1736,12 +2160,22 @@ function createWebSearchTool(config) {
     providerOptions,
     execute: async (input) => {
       const { query, allowed_domains, blocked_domains } = input;
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("web-search", { query, allowed_domains, blocked_domains }) : "";
       try {
         const results = await searchContent(apiKey, provider, {
           query,
           allowedDomains: allowed_domains,
           blockedDomains: blocked_domains
         });
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "web-search", {
+            summary: { resultCount: results.length },
+            output: results.slice(0, 5).map((r) => ({ title: r.title, url: r.url })),
+            duration_ms: durationMs
+          });
+        }
         return {
           results,
           total_results: results.length,
@@ -1751,15 +2185,18 @@ function createWebSearchTool(config) {
         if (error && typeof error === "object" && "status" in error) {
           const statusCode = error.status;
           const message = error.message || "API request failed";
+          if (debugId)
+            debugError(debugId, "web-search", `${message} (status: ${statusCode})`);
           return {
             error: message,
             status_code: statusCode,
             retryable: RETRYABLE_STATUS_CODES.includes(statusCode)
           };
         }
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "web-search", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1795,29 +2232,43 @@ function createWriteTool(sandbox, config) {
       file_path,
       content
     }) => {
+      const startTime = performance.now();
       const byteLength = Buffer.byteLength(content, "utf-8");
+      const debugId = isDebugEnabled() ? debugStart("write", { file_path, contentLength: byteLength }) : "";
       if (config?.maxFileSize && byteLength > config.maxFileSize) {
-        return {
-          error: `File content exceeds maximum size of ${config.maxFileSize} bytes (got ${byteLength})`
-        };
+        const error = `File content exceeds maximum size of ${config.maxFileSize} bytes (got ${byteLength})`;
+        if (debugId)
+          debugError(debugId, "write", error);
+        return { error };
       }
       if (config?.allowedPaths) {
         const isAllowed = config.allowedPaths.some((allowed) => file_path.startsWith(allowed));
         if (!isAllowed) {
-          return { error: `Path not allowed: ${file_path}` };
+          const error = `Path not allowed: ${file_path}`;
+          if (debugId)
+            debugError(debugId, "write", error);
+          return { error };
         }
       }
       try {
         await sandbox.writeFile(file_path, content);
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "write", {
+            summary: { bytes_written: byteLength },
+            duration_ms: durationMs
+          });
+        }
         return {
           message: `Successfully wrote to ${file_path}`,
           bytes_written: byteLength,
           file_path
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "write", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -1835,8 +2286,8 @@ var taskInputSchema = z13.object({
   description: z13.string().describe("A short (3-5 word) description of the task"),
   prompt: z13.string().describe("The task for the agent to perform"),
   subagent_type: z13.string().describe("The type of specialized agent to use for this task"),
-  system_prompt: z13.string().optional().describe("Optional custom system prompt for this agent. If provided, overrides the default system prompt for the subagent type. Use this to create dynamic, specialized agents on the fly."),
-  tools: z13.array(z13.string()).optional().describe("Optional list of tool names this agent can use (e.g., ['Read', 'Grep', 'WebSearch']). If provided, overrides the default tools for the subagent type. Use this to restrict or expand the agent's capabilities.")
+  system_prompt: z13.string().nullable().default(null).describe("Optional custom system prompt for this agent. If provided, overrides the default system prompt for the subagent type. Use this to create dynamic, specialized agents on the fly."),
+  tools: z13.array(z13.string()).nullable().default(null).describe("Optional list of tool names this agent can use (e.g., ['Read', 'Grep', 'WebSearch']). If provided, overrides the default tools for the subagent type. Use this to restrict or expand the agent's capabilities.")
 });
 var TASK_DESCRIPTION = `Launch a new agent to handle complex, multi-step tasks autonomously.
 
@@ -1864,16 +2315,22 @@ var eventCounter = 0;
 function generateEventId() {
   return `subagent-${Date.now()}-${++eventCounter}`;
 }
-function filterTools(allTools, allowedTools) {
-  if (!allowedTools)
-    return allTools;
-  const filtered = {};
-  for (const name of allowedTools) {
-    if (allTools[name]) {
-      filtered[name] = allTools[name];
+function filterTools(allTools, allowedTools, additionalTools) {
+  let result;
+  if (allowedTools) {
+    result = {};
+    for (const name of allowedTools) {
+      if (allTools[name]) {
+        result[name] = allTools[name];
+      }
     }
+  } else {
+    result = allTools;
+  }
+  if (additionalTools) {
+    result = { ...result, ...additionalTools };
   }
-  return filtered;
+  return result;
 }
 function createTaskTool(config) {
   const {
@@ -1895,10 +2352,20 @@ function createTaskTool(config) {
       tools: customTools
     }) => {
       const startTime = performance.now();
+      const typeConfig = subagentTypes[subagent_type] || {};
+      const debugId = isDebugEnabled() ? debugStart("task", {
+        subagent_type,
+        description,
+        tools: [
+          ...customTools ?? typeConfig.tools ?? Object.keys(allTools),
+          ...Object.keys(typeConfig.additionalTools ?? {})
+        ]
+      }) : "";
+      if (debugId)
+        pushParent(debugId);
       try {
-        const typeConfig = subagentTypes[subagent_type] || {};
         const model = typeConfig.model || defaultModel;
-        const tools = filterTools(allTools, customTools ?? typeConfig.tools);
+        const tools = filterTools(allTools, customTools ?? typeConfig.tools, typeConfig.additionalTools);
         const systemPrompt = system_prompt ?? typeConfig.systemPrompt;
         const commonOptions = {
           model,
@@ -1969,6 +2436,19 @@ function createTaskTool(config) {
             }
           });
           const durationMs2 = Math.round(performance.now() - startTime);
+          if (debugId) {
+            popParent();
+            debugEnd(debugId, "task", {
+              summary: {
+                tokens: {
+                  input: usage2.inputTokens,
+                  output: usage2.outputTokens
+                },
+                steps: response.messages?.length
+              },
+              duration_ms: durationMs2
+            });
+          }
           return {
             result: text,
             usage: usage2.inputTokens !== undefined && usage2.outputTokens !== undefined ? {
@@ -1996,6 +2476,19 @@ function createTaskTool(config) {
           input_tokens: result.usage.inputTokens,
           output_tokens: result.usage.outputTokens
         } : undefined;
+        if (debugId) {
+          popParent();
+          debugEnd(debugId, "task", {
+            summary: {
+              tokens: {
+                input: result.usage.inputTokens,
+                output: result.usage.outputTokens
+              },
+              steps: result.steps?.length
+            },
+            duration_ms: durationMs
+          });
+        }
         return {
           result: result.text,
           usage,
@@ -2005,6 +2498,10 @@ function createTaskTool(config) {
         };
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId) {
+          popParent();
+          debugError(debugId, "task", errorMessage);
+        }
         return { error: errorMessage };
       }
     }
@@ -2052,15 +2549,22 @@ var TODO_WRITE_DESCRIPTION = `Use this tool to create and manage a structured ta
 - Keep exactly ONE task in_progress at any time
 - ONLY mark completed when FULLY accomplished
 - If blocked/errors, keep in_progress and create new task for the blocker`;
-function createTodoWriteTool(state, onUpdate) {
+function createTodoWriteTool(state2, onUpdate) {
   return tool14({
     description: TODO_WRITE_DESCRIPTION,
     inputSchema: zodSchema14(todoWriteInputSchema),
     execute: async ({
       todos
     }) => {
+      const startTime = performance.now();
+      const debugId = isDebugEnabled() ? debugStart("todo-write", {
+        todoCount: todos.length,
+        pending: todos.filter((t) => t.status === "pending").length,
+        in_progress: todos.filter((t) => t.status === "in_progress").length,
+        completed: todos.filter((t) => t.status === "completed").length
+      }) : "";
       try {
-        state.todos = todos;
+        state2.todos = todos;
         if (onUpdate) {
           onUpdate(todos);
         }
@@ -2070,14 +2574,22 @@ function createTodoWriteTool(state, onUpdate) {
           in_progress: todos.filter((t) => t.status === "in_progress").length,
           completed: todos.filter((t) => t.status === "completed").length
         };
+        const durationMs = Math.round(performance.now() - startTime);
+        if (debugId) {
+          debugEnd(debugId, "todo-write", {
+            summary: stats,
+            duration_ms: durationMs
+          });
+        }
         return {
           message: "Todo list updated successfully",
           stats
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (debugId)
+          debugError(debugId, "todo-write", errorMessage);
+        return { error: errorMessage };
       }
     }
   });
@@ -2326,20 +2838,20 @@ function pruneMessagesByTokens(messages, config) {
 }
 
 // src/utils/compact-conversation.ts
-async function compactConversation(messages, config, state = { conversationSummary: "" }) {
+async function compactConversation(messages, config, state2 = { conversationSummary: "" }) {
   const currentTokens = estimateMessagesTokens(messages);
   const threshold = config.compactionThreshold ?? 0.85;
   const limit = config.maxTokens * threshold;
   if (currentTokens < limit) {
-    return { messages, state, didCompact: false };
+    return { messages, state: state2, didCompact: false };
   }
   const protectCount = config.protectRecentMessages ?? 10;
   const recentMessages = messages.slice(-protectCount);
   const oldMessages = messages.slice(0, -protectCount);
   if (oldMessages.length === 0) {
-    return { messages, state, didCompact: false };
+    return { messages, state: state2, didCompact: false };
   }
-  const newSummary = await summarizeMessages(oldMessages, config.summarizerModel, config.taskContext, state.conversationSummary);
+  const newSummary = await summarizeMessages(oldMessages, config.summarizerModel, config.taskContext, state2.conversationSummary);
   const compactedMessages = [
     {
       role: "user",
@@ -2874,10 +3386,13 @@ async function createDirectory(sandbox, path) {
 export {
   skillsToXml,
   setupAgentEnvironment,
+  reinitDebugMode,
   pruneMessagesByTokens,
   parseSkillMetadata,
   loadSkillBundles,
   loadSkillBundle,
+  isDebugEnabled,
+  getDebugLogs,
   getContextStatus,
   fetchSkills,
   fetchSkill,
@@ -2909,6 +3424,7 @@ export {
   contextNeedsCompaction,
   contextNeedsAttention,
   compactConversation,
+  clearDebugLogs,
   cached,
   anthropicPromptCacheMiddlewareV2,
   anthropicPromptCacheMiddleware,