wave-agent-sdk 0.0.7 → 0.0.10

package/dist/utils/bashHistory.js

@@ -4,6 +4,7 @@
  */
 import fs from "fs";
 import { BASH_HISTORY_FILE, DATA_DIRECTORY } from "./constants.js";
+import { logger } from "./globalLogger.js";
 const HISTORY_VERSION = 1;
 const MAX_HISTORY_SIZE = 1000;
 /**
@@ -15,8 +16,8 @@ const ensureDataDirectory = () => {
             fs.mkdirSync(DATA_DIRECTORY, { recursive: true });
         }
     }
-    catch {
-        // logger.debug("Failed to create data directory:", error);
+    catch (error) {
+        logger.debug("Failed to create data directory:", error);
     }
 };
 /**
@@ -35,7 +36,7 @@ export const loadBashHistory = () => {
         const history = JSON.parse(data);
         // Version compatibility check
         if (history.version !== HISTORY_VERSION) {
-            // logger.debug("Bash history version mismatch, resetting history");
+            logger.debug("Bash history version mismatch, resetting history");
             return {
                 commands: [],
                 version: HISTORY_VERSION,
@@ -43,8 +44,8 @@ export const loadBashHistory = () => {
         }
         return history;
     }
-    catch {
-        // logger.debug("Failed to load bash history:", error);
+    catch (error) {
+        logger.debug("Failed to load bash history:", error);
         return {
             commands: [],
             version: HISTORY_VERSION,
@@ -58,7 +59,7 @@ export const saveBashHistory = (history) => {
     try {
         // Skip saving to file when in test environment
         if (process.env.NODE_ENV === "test") {
-            // logger.debug("Skipping bash history save in test environment");
+            logger.debug("Skipping bash history save in test environment");
             return;
         }
         ensureDataDirectory();
@@ -69,8 +70,8 @@ export const saveBashHistory = (history) => {
         const data = JSON.stringify(history, null, 2);
         fs.writeFileSync(BASH_HISTORY_FILE, data, "utf-8");
     }
-    catch {
-        // logger.debug("Failed to save bash history:", error);
+    catch (error) {
+        logger.debug("Failed to save bash history:", error);
     }
 };
 /**
@@ -78,11 +79,6 @@ export const saveBashHistory = (history) => {
  */
 export const addBashCommandToHistory = (command, workdir) => {
     try {
-        // Filter system-generated commands, do not add to history
-        if (command.startsWith("git add . && git commit -m")) {
-            // logger.debug("Skipping system-generated command:", { command, workdir });
-            return;
-        }
         const history = loadBashHistory();
         const timestamp = Date.now();
         // Check if it's a duplicate consecutive command to avoid duplicate recording
@@ -102,10 +98,10 @@ export const addBashCommandToHistory = (command, workdir) => {
             });
         }
         saveBashHistory(history);
-        // logger.debug("Added bash command to history:", { command, workdir });
+        logger.debug("Added bash command to history:", { command, workdir });
     }
-    catch {
-        // logger.debug("Failed to add bash command to history:", error);
+    catch (error) {
+        logger.debug("Failed to add bash command to history:", error);
     }
 };
 /**
@@ -121,7 +117,7 @@ export const searchBashHistory = (query, limit = 10, workdir) => {
         if (!normalizedQuery) {
             // If no search query, return recent commands (deduplicated)
             const deduped = deduplicateCommands(filteredCommands);
-            return deduped.slice(-limit).reverse(); // Latest first
+            return deduped.slice(0, limit); // Latest first
         }
         // Search by relevance
         const matches = filteredCommands
@@ -156,11 +152,16 @@ export const searchBashHistory = (query, limit = 10, workdir) => {
         // Deduplicate search results, keep latest record
         const dedupedMatches = deduplicateCommands(matches);
         const result = dedupedMatches.slice(0, limit);
-        // logger.debug("Bash history search results:", { query, workdir: process.cwd(), originalCount: matches.length, dedupedCount: result.length });
+        logger.debug("Bash history search results:", {
+            query,
+            workdir: process.cwd(),
+            originalCount: matches.length,
+            dedupedCount: result.length,
+        });
         return result;
     }
-    catch {
-        // logger.debug("Failed to search bash history:", error);
+    catch (error) {
+        logger.debug("Failed to search bash history:", error);
         return [];
     }
 };
@@ -176,8 +177,8 @@ const deduplicateCommands = (commands) => {
             commandMap.set(entry.command, entry);
         }
     }
-    // Sort by timestamp and return
-    return Array.from(commandMap.values()).sort((a, b) => a.timestamp - b.timestamp);
+    // Sort by timestamp and return (new to old)
+    return Array.from(commandMap.values()).sort((a, b) => b.timestamp - a.timestamp);
 };
 /**
  * Get recently used bash commands
@@ -188,13 +189,30 @@ export const getRecentBashCommands = (workdir, limit = 10) => {
         const filtered = history.commands.filter((entry) => entry.workdir === workdir);
         // Return recent commands after deduplication
         const deduped = deduplicateCommands(filtered);
-        return deduped.slice(-limit).reverse(); // Latest first
+        return deduped.slice(0, limit); // Latest first
     }
-    catch {
-        // logger.debug("Failed to get recent bash commands:", error);
+    catch (error) {
+        logger.debug("Failed to get recent bash commands:", error);
         return [];
     }
 };
+/**
+ * Delete a specific command from bash history
+ */
+export const deleteBashCommandFromHistory = (command, workdir) => {
+    try {
+        const history = loadBashHistory();
+        const initialLength = history.commands.length;
+        history.commands = history.commands.filter((entry) => !(entry.command === command && entry.workdir === workdir));
+        if (history.commands.length !== initialLength) {
+            saveBashHistory(history);
+            logger.debug("Deleted bash command from history:", { command, workdir });
+        }
+    }
+    catch (error) {
+        logger.debug("Failed to delete bash command from history:", error);
+    }
+};
 /**
  * Clear bash history
  */
@@ -205,10 +223,10 @@ export const clearBashHistory = () => {
             version: HISTORY_VERSION,
         };
         saveBashHistory(history);
-        // logger.debug("Bash history cleared");
+        logger.debug("Bash history cleared");
     }
-    catch {
-        // logger.debug("Failed to clear bash history:", error);
+    catch (error) {
+        logger.debug("Failed to clear bash history:", error);
     }
 };
 /**
@@ -225,8 +243,8 @@ export const getBashCommandStats = () => {
             workdirs,
         };
     }
-    catch {
-        // logger.debug("Failed to get bash command stats:", error);
+    catch (error) {
+        logger.debug("Failed to get bash command stats:", error);
         return {
             totalCommands: 0,
             uniqueCommands: 0,

package/dist/utils/builtinSubagents.d.ts

@@ -0,0 +1,7 @@
+import type { SubagentConfiguration } from "./subagentParser.js";
+/**
+ * Get all built-in subagent configurations
+ * Built-in subagents have priority 3 (lowest) and can be overridden by user/project configs
+ */
+export declare function getBuiltinSubagents(): SubagentConfiguration[];
+//# sourceMappingURL=builtinSubagents.d.ts.map

package/dist/utils/builtinSubagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtinSubagents.d.ts","sourceRoot":"","sources":["../../src/utils/builtinSubagents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,qBAAqB,EAAE,CAK7D"}

package/dist/utils/builtinSubagents.js

@@ -0,0 +1,65 @@
+/**
+ * Get all built-in subagent configurations
+ * Built-in subagents have priority 3 (lowest) and can be overridden by user/project configs
+ */
+export function getBuiltinSubagents() {
+    return [
+        createExploreSubagent(),
+        // Add more built-in subagents here as needed
+    ];
+}
+/**
+ * Create the Explore built-in subagent configuration
+ * Specialized for codebase exploration and file search tasks
+ */
+function createExploreSubagent() {
+    const systemPrompt = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+- Using Language Server Protocol (LSP) for deep code intelligence (definitions, references, etc.)
+
+Guidelines:
+- Use Glob for broad file pattern matching
+- Use Grep for searching file contents with regex
+- Use Read when you know the specific file path you need to read
+- Use LSP for code intelligence features like finding definitions, references, implementations, and symbols. This is especially useful for understanding complex code relationships.
+- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Return file paths as absolute paths in your final response
+- For clear communication, avoid using emojis
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.`;
+    // Define allowed tools for read-only operations
+    const allowedTools = ["Glob", "Grep", "Read", "Bash", "LS", "LSP"];
+    return {
+        name: "Explore",
+        description: 'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.',
+        systemPrompt,
+        tools: allowedTools,
+        model: "fastModel", // Special value that will use parent's fastModel
+        filePath: "<builtin:Explore>",
+        scope: "builtin",
+        priority: 3, // Lowest priority - can be overridden by user configs
+    };
+}

package/dist/utils/cacheControlUtils.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Cache Control Utilities for Claude Models
+ *
+ * This module provides utilities for adding cache_control markers to Claude models
+ * to optimize token usage and reduce costs. Cache control is only applied to Claude
+ * models and preserves backward compatibility with existing message formats.
+ */
+import type { ChatCompletionMessageParam, ChatCompletionContentPart, ChatCompletionContentPartText, ChatCompletionFunctionTool, CompletionUsage } from "openai/resources";
+/**
+ * Cache control directive for Claude models
+ */
+export interface CacheControl {
+    type: "ephemeral";
+}
+/**
+ * Extended text content part with cache control support
+ */
+export interface ClaudeChatCompletionContentPartText extends ChatCompletionContentPartText {
+    type: "text";
+    text: string;
+    cache_control?: CacheControl;
+}
+/**
+ * Extended tool definition with cache control support
+ */
+export interface ClaudeChatCompletionFunctionTool extends ChatCompletionFunctionTool {
+    type: "function";
+    function: ChatCompletionFunctionTool["function"];
+    cache_control?: CacheControl;
+}
+/**
+ * Enhanced usage metrics including Claude cache information
+ */
+export interface ClaudeUsage extends CompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_creation?: {
+        ephemeral_5m_input_tokens: number;
+        ephemeral_1h_input_tokens: number;
+    };
+}
+/**
+ * Determines if a model supports cache control
+ * @param modelName - Model identifier
+ * @returns True if model name contains 'claude' (case-insensitive)
+ */
+export declare function isClaudeModel(modelName: string): boolean;
+/**
+ * Validates cache control structure
+ * @param control - Object to validate
+ * @returns True if valid cache control object
+ */
+export declare function isValidCacheControl(control: unknown): control is CacheControl;
+/**
+ * Adds cache control markers to message content
+ * @param content - Original content (string or structured)
+ * @param shouldCache - Whether to add cache control
+ * @returns Structured content with cache control markers
+ */
+export declare function addCacheControlToContent(content: string | ChatCompletionContentPart[], shouldCache: boolean): ClaudeChatCompletionContentPartText[];
+/**
+ * Adds cache control to the last tool in tools array
+ * @param tools - Array of tool definitions
+ * @returns Tools array with cache control on last tool
+ */
+export declare function addCacheControlToLastTool(tools: ChatCompletionFunctionTool[]): ClaudeChatCompletionFunctionTool[];
+/**
+ * Finds the latest message index at 20-message intervals (sliding window approach)
+ * @param messages - Array of chat completion messages
+ * @returns Index of the latest interval message (20th, 40th, 60th, etc.) or -1 if none
+ */
+export declare function findIntervalMessageIndex(messages: ChatCompletionMessageParam[]): number;
+/**
+ * Transforms messages for Claude cache control with hardcoded strategy
+ * @param messages - Original OpenAI message array
+ * @param modelName - Model name for cache detection
+ * @returns Messages with cache control markers applied
+ */
+export declare function transformMessagesForClaudeCache(messages: ChatCompletionMessageParam[], modelName: string): ChatCompletionMessageParam[];
+/**
+ * Extends standard usage with cache metrics
+ * @param standardUsage - OpenAI usage response
+ * @param cacheMetrics - Additional cache metrics from Claude
+ * @returns Extended usage with cache information
+ */
+export declare function extendUsageWithCacheMetrics(standardUsage: CompletionUsage, cacheMetrics?: Partial<ClaudeUsage>): ClaudeUsage;
+/**
+ * Validates Claude usage structure
+ * @param usage - Usage object to validate
+ * @returns True if usage structure is valid
+ */
+export declare function isValidClaudeUsage(usage: unknown): usage is ClaudeUsage;
+//# sourceMappingURL=cacheControlUtils.d.ts.map

package/dist/utils/cacheControlUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheControlUtils.d.ts","sourceRoot":"","sources":["../../src/utils/cacheControlUtils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,6BAA6B,EAC7B,0BAA0B,EAE1B,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAO1B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mCACf,SAAQ,6BAA6B;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,YAAY,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,gCACf,SAAQ,0BAA0B;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,0BAA0B,CAAC,UAAU,CAAC,CAAC;IACjD,aAAa,CAAC,EAAE,YAAY,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IAGrB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,cAAc,CAAC,EAAE;QACf,yBAAyB,EAAE,MAAM,CAAC;QAClC,yBAAyB,EAAE,MAAM,CAAC;KACnC,CAAC;CACH;AAUD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAaxD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,YAAY,CAQ7E;AA0BD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,GAAG,yBAAyB,EAAE,EAC7C,WAAW,EAAE,OAAO,GACnB,mCAAmC,EAAE,CAkEvC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,0BAA0B,EAAE,GAClC,gCAAgC,EAAE,CAwCpC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,0BAA0B,EAAE,GACrC,MAAM,CAoBR;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,0BAA0B,EAAE,EACtC,SAAS,EAAE,MAAM,GAChB,0BAA0B,EAAE,CAoF9B;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,eAAe,EAC9B,YAAY,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAClC,WAAW,CAkCb;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAyCvE"}

package/dist/utils/cacheControlUtils.js

@@ -0,0 +1,324 @@
+/**
+ * Cache Control Utilities for Claude Models
+ *
+ * This module provides utilities for adding cache_control markers to Claude models
+ * to optimize token usage and reduce costs. Cache control is only applied to Claude
+ * models and preserves backward compatibility with existing message formats.
+ */
+import { logger } from "./globalLogger.js";
+// ============================================================================
+// Default Configuration
+// ============================================================================
+// ============================================================================
+// Utility Functions (Basic Structure - to be implemented)
+// ============================================================================
+/**
+ * Determines if a model supports cache control
+ * @param modelName - Model identifier
+ * @returns True if model name contains 'claude' (case-insensitive)
+ */
+export function isClaudeModel(modelName) {
+    // Handle null, undefined, and non-string inputs
+    if (!modelName || typeof modelName !== "string") {
+        return false;
+    }
+    // Handle empty strings and whitespace-only strings
+    const trimmed = modelName.trim();
+    if (trimmed.length === 0) {
+        return false;
+    }
+    return trimmed.toLowerCase().includes("claude");
+}
+/**
+ * Validates cache control structure
+ * @param control - Object to validate
+ * @returns True if valid cache control object
+ */
+export function isValidCacheControl(control) {
+    return (control !== null &&
+        typeof control === "object" &&
+        control !== undefined &&
+        "type" in control &&
+        control.type === "ephemeral");
+}
+/**
+ * Adds cache control to the last tool call in an array
+ * @param toolCalls - Array of tool calls
+ * @returns Tool calls array with cache control on the last tool call
+ */
+function addCacheControlToLastToolCall(toolCalls) {
+    if (!toolCalls || toolCalls.length === 0) {
+        return toolCalls;
+    }
+    const result = [...toolCalls];
+    const lastIndex = result.length - 1;
+    // Add cache control to the last tool call
+    result[lastIndex] = {
+        ...result[lastIndex],
+        cache_control: { type: "ephemeral" },
+    };
+    return result;
+}
+/**
+ * Adds cache control markers to message content
+ * @param content - Original content (string or structured)
+ * @param shouldCache - Whether to add cache control
+ * @returns Structured content with cache control markers
+ */
+export function addCacheControlToContent(content, shouldCache) {
+    // Handle null/undefined content
+    if (content == null) {
+        return [];
+    }
+    // If shouldCache is false, return content as text parts without cache control
+    if (!shouldCache) {
+        if (typeof content === "string") {
+            return [{ type: "text", text: content }];
+        }
+        // Validate array input
+        if (!Array.isArray(content)) {
+            logger.warn("Invalid content type for cache control transformation:", typeof content);
+            return [];
+        }
+        // Filter and convert only text parts with validation
+        return content
+            .filter((part) => {
+            if (!part || typeof part !== "object") {
+                return false;
+            }
+            return part.type === "text" && typeof part.text === "string";
+        })
+            .map((part) => ({ type: "text", text: part.text }));
+    }
+    // shouldCache is true - add cache control markers
+    if (typeof content === "string") {
+        // Transform string content to structured array with cache control
+        return [
+            {
+                type: "text",
+                text: content,
+                cache_control: { type: "ephemeral" },
+            },
+        ];
+    }
+    // Validate array input
+    if (!Array.isArray(content)) {
+        logger.warn("Invalid content type for cache control transformation:", typeof content);
+        return [];
+    }
+    // Handle structured content - preserve existing structure, add cache control to text parts
+    return content
+        .filter((part) => {
+        if (!part || typeof part !== "object") {
+            return false;
+        }
+        return part.type === "text" && typeof part.text === "string";
+    })
+        .map((part) => ({
+        type: "text",
+        text: part.text,
+        cache_control: { type: "ephemeral" },
+    }));
+}
+/**
+ * Adds cache control to the last tool in tools array
+ * @param tools - Array of tool definitions
+ * @returns Tools array with cache control on last tool
+ */
+export function addCacheControlToLastTool(tools) {
+    // Handle null, undefined, or empty arrays
+    if (!tools || !Array.isArray(tools) || tools.length === 0) {
+        return [];
+    }
+    // Validate tools structure
+    const validTools = tools.filter((tool) => {
+        if (!tool || typeof tool !== "object") {
+            logger.warn("Invalid tool structure detected, skipping:", tool);
+            return false;
+        }
+        if (tool.type !== "function" || !tool.function) {
+            logger.warn("Tool is not a function type or missing function property:", tool);
+            return false;
+        }
+        return true;
+    });
+    if (validTools.length === 0) {
+        logger.warn("No valid tools found for cache control");
+        return [];
+    }
+    // Create a copy of the valid tools array
+    const result = validTools.map((tool) => ({
+        ...tool,
+    }));
+    // Add cache control to the last tool only
+    const lastIndex = result.length - 1;
+    result[lastIndex] = {
+        ...result[lastIndex],
+        cache_control: { type: "ephemeral" },
+    };
+    return result;
+}
+/**
+ * Finds the latest message index at 20-message intervals (sliding window approach)
+ * @param messages - Array of chat completion messages
+ * @returns Index of the latest interval message (20th, 40th, 60th, etc.) or -1 if none
+ */
+export function findIntervalMessageIndex(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) {
+        return -1;
+    }
+    const interval = 20; // Hardcoded interval
+    const messageCount = messages.length;
+    // Find the largest interval that fits within the message count
+    // Math.floor(messageCount / interval) gives us how many complete intervals we have
+    // Multiply by interval to get the position of the latest interval message
+    const latestIntervalPosition = Math.floor(messageCount / interval) * interval;
+    // If no complete intervals exist, return -1
+    if (latestIntervalPosition === 0) {
+        return -1;
+    }
+    // Convert from 1-based position to 0-based index
+    return latestIntervalPosition - 1;
+}
+/**
+ * Transforms messages for Claude cache control with hardcoded strategy
+ * @param messages - Original OpenAI message array
+ * @param modelName - Model name for cache detection
+ * @returns Messages with cache control markers applied
+ */
+export function transformMessagesForClaudeCache(messages, modelName) {
+    // Validate inputs
+    if (!messages || !Array.isArray(messages)) {
+        logger.warn("Invalid messages array provided to transformMessagesForClaudeCache");
+        return [];
+    }
+    if (messages.length === 0) {
+        return [];
+    }
+    // Only apply cache control for Claude models
+    if (!isClaudeModel(modelName)) {
+        return messages;
+    }
+    // Find the latest interval message index (20th, 40th, 60th, etc.)
+    const intervalMessageIndex = findIntervalMessageIndex(messages);
+    // Find last system message index
+    let lastSystemIndex = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "system") {
+            lastSystemIndex = i;
+            break;
+        }
+    }
+    const result = messages.map((message, index) => {
+        // Validate message structure
+        if (!message || typeof message !== "object" || !message.role) {
+            logger.warn("Invalid message structure at index", index, ":", message);
+            return message; // Return as-is to avoid breaking the flow
+        }
+        // Last system message: always cached (hardcoded)
+        if (message.role === "system" && index === lastSystemIndex) {
+            return {
+                ...message,
+                content: addCacheControlToContent(message.content || "", true),
+            };
+        }
+        // Interval-based message caching: cache message at latest interval position (sliding window)
+        if (index === intervalMessageIndex) {
+            // If the message is a tool role, add cache control directly to the message
+            if (message.role === "tool") {
+                return {
+                    ...message,
+                    cache_control: { type: "ephemeral" },
+                };
+            }
+            // If the message has tool calls, cache the last tool call instead of content
+            else if (message.role === "assistant" &&
+                message.tool_calls &&
+                message.tool_calls.length > 0) {
+                return {
+                    ...message,
+                    tool_calls: addCacheControlToLastToolCall(message.tool_calls),
+                };
+            }
+            else {
+                // For other message types without tool calls, cache the content
+                return {
+                    ...message,
+                    content: addCacheControlToContent(message.content || "", true),
+                };
+            }
+        }
+        // Return message unchanged
+        return message;
+    });
+    return result;
+}
+/**
+ * Extends standard usage with cache metrics
+ * @param standardUsage - OpenAI usage response
+ * @param cacheMetrics - Additional cache metrics from Claude
+ * @returns Extended usage with cache information
+ */
+export function extendUsageWithCacheMetrics(standardUsage, cacheMetrics) {
+    const baseUsage = {
+        prompt_tokens: standardUsage.prompt_tokens,
+        completion_tokens: standardUsage.completion_tokens,
+        total_tokens: standardUsage.total_tokens,
+    };
+    // Add cache metrics if provided
+    if (cacheMetrics) {
+        if (typeof cacheMetrics.cache_read_input_tokens === "number") {
+            baseUsage.cache_read_input_tokens = cacheMetrics.cache_read_input_tokens;
+        }
+        if (typeof cacheMetrics.cache_creation_input_tokens === "number") {
+            baseUsage.cache_creation_input_tokens =
+                cacheMetrics.cache_creation_input_tokens;
+        }
+        if (cacheMetrics.cache_creation &&
+            typeof cacheMetrics.cache_creation.ephemeral_5m_input_tokens ===
+                "number" &&
+            typeof cacheMetrics.cache_creation.ephemeral_1h_input_tokens === "number") {
+            baseUsage.cache_creation = {
+                ephemeral_5m_input_tokens: cacheMetrics.cache_creation.ephemeral_5m_input_tokens,
+                ephemeral_1h_input_tokens: cacheMetrics.cache_creation.ephemeral_1h_input_tokens,
+            };
+        }
+    }
+    return baseUsage;
+}
+/**
+ * Validates Claude usage structure
+ * @param usage - Usage object to validate
+ * @returns True if usage structure is valid
+ */
+export function isValidClaudeUsage(usage) {
+    if (!usage || typeof usage !== "object") {
+        return false;
+    }
+    const usageObj = usage;
+    // Check required standard fields
+    const hasStandardFields = typeof usageObj.prompt_tokens === "number" &&
+        typeof usageObj.completion_tokens === "number" &&
+        typeof usageObj.total_tokens === "number";
+    if (!hasStandardFields) {
+        return false;
+    }
+    // Check optional cache fields
+    const hasCacheFields = (usageObj.cache_read_input_tokens === undefined ||
+        typeof usageObj.cache_read_input_tokens === "number") &&
+        (usageObj.cache_creation_input_tokens === undefined ||
+            typeof usageObj.cache_creation_input_tokens === "number");
+    if (!hasCacheFields) {
+        return false;
+    }
+    // Check cache_creation object if present
+    if (usageObj.cache_creation !== undefined) {
+        const cacheCreation = usageObj.cache_creation;
+        if (typeof cacheCreation !== "object" ||
+            typeof cacheCreation.ephemeral_5m_input_tokens !== "number" ||
+            typeof cacheCreation.ephemeral_1h_input_tokens !== "number") {
+            return false;
+        }
+    }
+    return true;
+}