wave-agent-sdk 0.0.6 → 0.0.8

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);
     }
 };
 /**
@@ -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 [];
     }
 };
@@ -190,8 +191,8 @@ export const getRecentBashCommands = (workdir, limit = 10) => {
         const deduped = deduplicateCommands(filtered);
         return deduped.slice(-limit).reverse(); // Latest first
     }
-    catch {
-        // logger.debug("Failed to get recent bash commands:", error);
+    catch (error) {
+        logger.debug("Failed to get recent bash commands:", error);
         return [];
     }
 };
@@ -205,10 +206,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 +226,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/cacheControlUtils.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+    };
+}
+/**
+ * Configuration for cache control application
+ */
+export interface CacheControlConfig {
+    cacheSystemMessage: boolean;
+    cacheUserMessageCount: number;
+    cacheLastTool: boolean;
+}
+/**
+ * Default cache control configuration
+ */
+export declare const DEFAULT_CACHE_CONTROL_CONFIG: CacheControlConfig;
+/**
+ * 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[];
+/**
+ * Transforms messages for Claude cache control
+ * @param messages - Original OpenAI message array
+ * @param modelName - Model name for cache detection
+ * @param config - Cache control configuration
+ * @returns Messages with cache control markers applied
+ */
+export declare function transformMessagesForClaudeCache(messages: ChatCompletionMessageParam[], modelName: string, config?: CacheControlConfig): 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;
+/**
+ * Adds cache control to the last N user messages in a conversation
+ * This optimizes multi-turn conversations by caching recent user context
+ *
+ * @param messages - Array of chat completion messages
+ * @param maxUserMessagesToCache - Maximum number of recent user messages to cache (default: 2)
+ * @returns Modified messages array with cache control on recent user messages
+ */
+export declare function addCacheControlToRecentUserMessages(messages: ChatCompletionMessageParam[], maxUserMessagesToCache?: number): ChatCompletionMessageParam[];
+/**
+ * Helper function to identify user message indices that should be cached
+ * Used for testing and validation purposes
+ *
+ * @param messages - Array of chat completion messages
+ * @param maxUserMessagesToCache - Maximum number of recent user messages to identify
+ * @returns Array of indices for user messages that should be cached
+ */
+export declare function findRecentUserMessageIndices(messages: ChatCompletionMessageParam[], maxUserMessagesToCache?: number): number[];
+//# 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,EAC1B,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAM1B;;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;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,OAAO,CAAC;CACxB;AAMD;;GAEG;AACH,eAAO,MAAM,4BAA4B,EAAE,kBAIjC,CAAC;AAMX;;;;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;AAED;;;;;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;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,0BAA0B,EAAE,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,kBAAiD,GACxD,0BAA0B,EAAE,CAkE9B;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;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,0BAA0B,EAAE,EACtC,sBAAsB,GAAE,MAAU,GACjC,0BAA0B,EAAE,CAuE9B;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,0BAA0B,EAAE,EACtC,sBAAsB,GAAE,MAAU,GACjC,MAAM,EAAE,CAqBV"}

package/dist/utils/cacheControlUtils.js

@@ -0,0 +1,367 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// Default Configuration
+// ============================================================================
+/**
+ * Default cache control configuration
+ */
+export const DEFAULT_CACHE_CONTROL_CONFIG = {
+    cacheSystemMessage: true,
+    cacheUserMessageCount: 2,
+    cacheLastTool: true,
+};
+// ============================================================================
+// 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 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)) {
+            console.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)) {
+        console.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") {
+            console.warn("Invalid tool structure detected, skipping:", tool);
+            return false;
+        }
+        if (tool.type !== "function" || !tool.function) {
+            console.warn("Tool is not a function type or missing function property:", tool);
+            return false;
+        }
+        return true;
+    });
+    if (validTools.length === 0) {
+        console.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;
+}
+/**
+ * Transforms messages for Claude cache control
+ * @param messages - Original OpenAI message array
+ * @param modelName - Model name for cache detection
+ * @param config - Cache control configuration
+ * @returns Messages with cache control markers applied
+ */
+export function transformMessagesForClaudeCache(messages, modelName, config = DEFAULT_CACHE_CONTROL_CONFIG) {
+    // Validate inputs
+    if (!messages || !Array.isArray(messages)) {
+        console.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;
+    }
+    // Validate config
+    if (!config || typeof config !== "object") {
+        console.warn("Invalid cache control config, using defaults");
+        config = DEFAULT_CACHE_CONTROL_CONFIG;
+    }
+    const result = messages.map((message, index) => {
+        // Validate message structure
+        if (!message || typeof message !== "object" || !message.role) {
+            console.warn("Invalid message structure at index", index, ":", message);
+            return message; // Return as-is to avoid breaking the flow
+        }
+        // System message: cache if enabled in config
+        if (message.role === "system" && config.cacheSystemMessage) {
+            return {
+                ...message,
+                content: addCacheControlToContent(message.content, true),
+            };
+        }
+        // User messages: cache last N messages based on config
+        if (message.role === "user" && config.cacheUserMessageCount > 0) {
+            const userMessageIndices = [];
+            messages.forEach((msg, idx) => {
+                if (msg.role === "user") {
+                    userMessageIndices.push(idx);
+                }
+            });
+            // Check if this user message is among the last N
+            const isRecentUser = userMessageIndices
+                .slice(-config.cacheUserMessageCount)
+                .includes(index);
+            if (isRecentUser) {
+                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;
+}
+/**
+ * Adds cache control to the last N user messages in a conversation
+ * This optimizes multi-turn conversations by caching recent user context
+ *
+ * @param messages - Array of chat completion messages
+ * @param maxUserMessagesToCache - Maximum number of recent user messages to cache (default: 2)
+ * @returns Modified messages array with cache control on recent user messages
+ */
+export function addCacheControlToRecentUserMessages(messages, maxUserMessagesToCache = 2) {
+    // Validate inputs
+    if (!messages || !Array.isArray(messages)) {
+        console.warn("Invalid messages array provided to addCacheControlToRecentUserMessages");
+        return [];
+    }
+    if (messages.length === 0 || maxUserMessagesToCache <= 0) {
+        return messages;
+    }
+    // Validate maxUserMessagesToCache is a reasonable number
+    if (maxUserMessagesToCache > 100) {
+        console.warn("maxUserMessagesToCache is unusually high:", maxUserMessagesToCache, "limiting to 100");
+        maxUserMessagesToCache = 100;
+    }
+    // Find all user message indices in reverse order (most recent first)
+    const userMessageIndices = [];
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        // Validate message structure
+        if (!message || typeof message !== "object" || !message.role) {
+            console.warn("Invalid message at index", i, ", skipping");
+            continue;
+        }
+        if (message.role === "user") {
+            userMessageIndices.push(i);
+            if (userMessageIndices.length >= maxUserMessagesToCache) {
+                break;
+            }
+        }
+    }
+    // If no user messages found, return unchanged
+    if (userMessageIndices.length === 0) {
+        return messages;
+    }
+    // Create a copy of messages and modify the identified user messages
+    const modifiedMessages = [...messages];
+    for (const index of userMessageIndices) {
+        const message = modifiedMessages[index];
+        if (message.role === "user" && message.content != null) {
+            try {
+                modifiedMessages[index] = {
+                    ...message,
+                    content: addCacheControlToContent(message.content, true),
+                };
+            }
+            catch (error) {
+                console.warn("Failed to add cache control to user message at index", index, ":", error);
+                // Continue with original message if transformation fails
+            }
+        }
+    }
+    return modifiedMessages;
+}
+/**
+ * Helper function to identify user message indices that should be cached
+ * Used for testing and validation purposes
+ *
+ * @param messages - Array of chat completion messages
+ * @param maxUserMessagesToCache - Maximum number of recent user messages to identify
+ * @returns Array of indices for user messages that should be cached
+ */
+export function findRecentUserMessageIndices(messages, maxUserMessagesToCache = 2) {
+    if (!Array.isArray(messages) ||
+        messages.length === 0 ||
+        maxUserMessagesToCache <= 0) {
+        return [];
+    }
+    const userMessageIndices = [];
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            userMessageIndices.push(i);
+            if (userMessageIndices.length >= maxUserMessagesToCache) {
+                break;
+            }
+        }
+    }
+    // Return indices in original order (not reversed)
+    return userMessageIndices.reverse();
+}

package/dist/utils/commandPathResolver.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Command path resolver utilities for nested command discovery
+ * Handles conversion between file paths and command IDs with colon syntax
+ */
+export interface CommandIdParts {
+    namespace?: string;
+    commandName: string;
+    isNested: boolean;
+    depth: number;
+    segments: string[];
+}
+/**
+ * Generate command ID from file path
+ * @param filePath - Absolute path to markdown file
+ * @param rootDir - Root commands directory path
+ * @returns Command identifier string (e.g., "openspec:apply")
+ * @throws Error on invalid path structure
+ */
+export declare function generateCommandId(filePath: string, rootDir: string): string;
+/**
+ * Parse command ID into components
+ * @param commandId - Command identifier (e.g., "openspec:apply")
+ * @returns Object with namespace and command name
+ * @throws Error on malformed command ID
+ */
+export declare function parseCommandId(commandId: string): CommandIdParts;
+/**
+ * Validate command ID format
+ * @param commandId - Command identifier to validate
+ * @returns Boolean indicating validity
+ */
+export declare function validateCommandId(commandId: string): boolean;
+/**
+ * Convert file path to command segments array
+ * @param filePath - Absolute path to markdown file
+ * @param rootDir - Root commands directory path
+ * @returns Array of path segments
+ */
+export declare function getCommandSegments(filePath: string, rootDir: string): string[];
+/**
+ * Get namespace from command segments
+ * @param segments - Command path segments
+ * @returns Namespace string or undefined for flat commands
+ */
+export declare function getNamespace(segments: string[]): string | undefined;
+/**
+ * Get command depth from segments
+ * @param segments - Command path segments
+ * @returns Depth number (0 for root, 1 for nested)
+ */
+export declare function getDepth(segments: string[]): number;
+//# sourceMappingURL=commandPathResolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commandPathResolver.d.ts","sourceRoot":"","sources":["../../src/utils/commandPathResolver.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAmD3E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAyChE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAU5D;AAaD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,MAAM,EAAE,CASV;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnD"}