wave-agent-sdk 1.0.4 → 1.0.6

package/src/utils/cacheControlUtils.ts

@@ -1,426 +0,0 @@
-/**
- * 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,
-  CompletionUsage,
-} from "openai/resources";
-import { logger } from "./globalLogger.js";
-import { supportsPromptCaching } from "./modelCapabilities.js";
-import type { ModelCapabilities } from "../types/config.js";
-
-// ============================================================================
-// Core Types
-// ============================================================================
-
-/**
- * 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 prompt_tokens_details with cache_creation_input_tokens
- * Some models (e.g. Gemini, DeepSeek) return this field inside prompt_tokens_details
- */
-export interface ExtendedPromptTokensDetails
-  extends CompletionUsage.PromptTokensDetails {
-  cache_creation_input_tokens?: number;
-}
-
-/**
- * Enhanced usage metrics including cache information
- * Supports both Claude-specific top-level fields and OpenAI-standard prompt_tokens_details
- */
-export interface ClaudeUsage extends CompletionUsage {
-  prompt_tokens: number;
-  completion_tokens: number;
-  total_tokens: number;
-
-  // Cache extensions (from Claude top-level or OpenAI prompt_tokens_details)
-  cache_read_input_tokens?: number; // Claude: cache_read_input_tokens / OpenAI: prompt_tokens_details.cached_tokens
-  cache_creation_input_tokens?: number; // Claude: cache_creation_input_tokens / OpenAI: prompt_tokens_details.cache_creation_input_tokens
-  cache_creation?: {
-    ephemeral_5m_input_tokens: number;
-    ephemeral_1h_input_tokens: number;
-  };
-
-  // Override prompt_tokens_details to include cache_creation_input_tokens
-  prompt_tokens_details?: ExtendedPromptTokensDetails;
-}
-
-// ============================================================================
-// Default Configuration
-// ============================================================================
-
-// ============================================================================
-// Utility Functions (Basic Structure - to be implemented)
-// ============================================================================
-
-/**
- * Validates cache control structure
- * @param control - Object to validate
- * @returns True if valid cache control object
- */
-export function isValidCacheControl(control: unknown): control is CacheControl {
-  return (
-    control !== null &&
-    typeof control === "object" &&
-    control !== undefined &&
-    "type" in control &&
-    (control as { type: unknown }).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: string | ChatCompletionContentPart[],
-  shouldCache: boolean,
-): ClaudeChatCompletionContentPartText[] {
-  // 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): part is ChatCompletionContentPartText => {
-        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 all parts, add cache control to last text part only
-  let lastTextIndex = -1;
-  for (let i = content.length - 1; i >= 0; i--) {
-    const part = content[i];
-    if (
-      part &&
-      typeof part === "object" &&
-      part.type === "text" &&
-      typeof (part as ChatCompletionContentPartText).text === "string"
-    ) {
-      lastTextIndex = i;
-      break;
-    }
-  }
-
-  return content.map((part, index) => {
-    if (
-      index === lastTextIndex &&
-      part &&
-      typeof part === "object" &&
-      part.type === "text" &&
-      typeof (part as ChatCompletionContentPartText).text === "string"
-    ) {
-      return {
-        ...(part as ChatCompletionContentPartText),
-        cache_control: { type: "ephemeral" },
-      };
-    }
-    return part;
-  }) as ClaudeChatCompletionContentPartText[];
-}
-
-/**
- * Counts the total number of content blocks across all messages.
- * Each element in a message's content array counts as one block.
- * String content counts as one block. Null/undefined content counts as zero
- * (e.g. assistant messages with only tool_calls).
- * @param messages - Array of chat messages
- * @returns Total content block count
- */
-export function countContentBlocks(
-  messages: ChatCompletionMessageParam[],
-): number {
-  let count = 0;
-  for (const message of messages) {
-    if (!message || typeof message !== "object") continue;
-    const content = message.content;
-    if (typeof content === "string") {
-      count += 1;
-    } else if (Array.isArray(content)) {
-      count += content.length;
-    }
-  }
-  return count;
-}
-
-/**
- * Transforms messages for explicit cache control.
- *
- * Cache breakpoints (following Claude Code's "last message marker" strategy):
- * 1. System message — always marked (stable prefix)
- * 2. Last message — the last user/assistant message with content is marked.
- *    The API scans backward from this marker within 20 blocks. Since each
- *    turn adds ~2 blocks (< 20), the previous request's marker position
- *    always falls within the scan window, ensuring cache hits.
- *
- * Tools are marked separately via addCacheControlToLastTool (called by aiService).
- *
- * @param messages - Original OpenAI message array
- * @param capabilities - Declarative model capabilities for cache detection
- * @returns Messages with cache control markers applied
- */
-export function transformMessagesForExplicitCache(
-  messages: ChatCompletionMessageParam[],
-  capabilities?: ModelCapabilities,
-): ChatCompletionMessageParam[] {
-  // Validate inputs
-  if (!messages || !Array.isArray(messages)) {
-    logger.warn(
-      "Invalid messages array provided to transformMessagesForExplicitCache",
-    );
-    return [];
-  }
-
-  if (messages.length === 0) {
-    return [];
-  }
-
-  // Only apply cache control for models that support prompt caching
-  if (!supportsPromptCaching(capabilities)) {
-    return messages;
-  }
-
-  // Find first system message index
-  const firstSystemIndex = messages.findIndex((m) => m.role === "system");
-
-  // Determine which message indices should receive cache_control markers
-  const cacheIndices = new Set<number>();
-
-  // Marker 1: First system message (always — stable prefix)
-  if (firstSystemIndex !== -1) {
-    cacheIndices.add(firstSystemIndex);
-  }
-
-  // Marker 2: Last message with content (user or assistant).
-  // This marker moves each turn (~2 blocks), but since the move is < 20 blocks,
-  // the previous marker position is always within the API's 20-block scan window.
-  // This ensures the entire conversation prefix is cached.
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i];
-    if (!msg || typeof msg !== "object") continue;
-    if (i === firstSystemIndex) continue;
-    if (msg.role !== "user" && msg.role !== "assistant") continue;
-
-    const content = msg.content;
-    const hasContent =
-      (typeof content === "string" && content.length > 0) ||
-      (Array.isArray(content) && content.length > 0);
-
-    if (hasContent) {
-      cacheIndices.add(i);
-      break;
-    }
-  }
-
-  // Apply cache_control markers to selected messages
-  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;
-    }
-
-    if (!cacheIndices.has(index)) {
-      return message;
-    }
-
-    const content =
-      (message.content as string | ChatCompletionContentPart[]) || "";
-
-    // Idempotency: skip if content already has cache_control (system message)
-    if (message.role === "system" && Array.isArray(content)) {
-      const hasCacheControl = content.some(
-        (part) =>
-          part.type === "text" &&
-          (part as ClaudeChatCompletionContentPartText).cache_control,
-      );
-      if (hasCacheControl) {
-        return message;
-      }
-    }
-
-    const transformedContent = addCacheControlToContent(content, true);
-
-    return {
-      ...message,
-      content: transformedContent,
-    } as ChatCompletionMessageParam;
-  });
-
-  return result;
-}
-
-/**
- * Extends standard usage with cache metrics
- * Extracts cache tokens from both Claude-specific top-level fields and
- * OpenAI-standard prompt_tokens_details (used by Gemini, DeepSeek, etc.)
- * @param standardUsage - OpenAI usage response
- * @param cacheMetrics - Additional cache metrics from the API response
- * @returns Extended usage with cache information
- */
-export function extendUsageWithCacheMetrics(
-  standardUsage: CompletionUsage,
-  cacheMetrics?: Partial<ClaudeUsage>,
-): ClaudeUsage {
-  const baseUsage: ClaudeUsage = {
-    prompt_tokens: standardUsage.prompt_tokens,
-    completion_tokens: standardUsage.completion_tokens,
-    total_tokens: standardUsage.total_tokens,
-  };
-
-  if (!cacheMetrics) {
-    return baseUsage;
-  }
-
-  // Extract cache_read_input_tokens from Claude top-level field
-  if (typeof cacheMetrics.cache_read_input_tokens === "number") {
-    baseUsage.cache_read_input_tokens = cacheMetrics.cache_read_input_tokens;
-  }
-  // Fallback to prompt_tokens_details.cached_tokens (OpenAI standard)
-  else if (cacheMetrics.prompt_tokens_details?.cached_tokens != null) {
-    baseUsage.cache_read_input_tokens =
-      cacheMetrics.prompt_tokens_details.cached_tokens;
-  }
-
-  // Extract cache_creation_input_tokens from Claude top-level field
-  if (typeof cacheMetrics.cache_creation_input_tokens === "number") {
-    baseUsage.cache_creation_input_tokens =
-      cacheMetrics.cache_creation_input_tokens;
-  }
-  // Fallback to prompt_tokens_details.cache_creation_input_tokens
-  else if (
-    cacheMetrics.prompt_tokens_details?.cache_creation_input_tokens != null
-  ) {
-    baseUsage.cache_creation_input_tokens =
-      cacheMetrics.prompt_tokens_details.cache_creation_input_tokens;
-  }
-
-  // Extract cache_creation breakdown (Claude-specific)
-  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: unknown): usage is ClaudeUsage {
-  if (!usage || typeof usage !== "object") {
-    return false;
-  }
-
-  const usageObj = usage as Record<string, unknown>;
-
-  // 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 as Record<string, unknown>;
-    if (
-      typeof cacheCreation !== "object" ||
-      typeof cacheCreation.ephemeral_5m_input_tokens !== "number" ||
-      typeof cacheCreation.ephemeral_1h_input_tokens !== "number"
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}

package/src/utils/commandArgumentParser.ts

@@ -1,161 +0,0 @@
-/**
- * Command Argument Parser
- *
- * Provides parameter substitution for custom slash commands similar to Claude's system:
- * - $ARGUMENTS: All arguments as a single string
- * - $1, $2, $3, etc.: Individual positional arguments
- * - Supports quoted arguments with spaces
- * - Handles escaped quotes within arguments
- */
-
-/**
- * Parse command arguments from a string, respecting quotes
- */
-export function parseCommandArguments(argsString: string): string[] {
-  if (!argsString.trim()) {
-    return [];
-  }
-
-  const args: string[] = [];
-  let current = "";
-  let inQuotes = false;
-  let quoteChar = "";
-  let escaped = false;
-
-  for (let i = 0; i < argsString.length; i++) {
-    const char = argsString[i];
-    const nextChar = argsString[i + 1];
-
-    if (escaped) {
-      current += char;
-      escaped = false;
-      continue;
-    }
-
-    if (char === "\\") {
-      // Handle escape sequences
-      if (inQuotes && (nextChar === quoteChar || nextChar === "\\")) {
-        escaped = true;
-        continue;
-      }
-      current += char;
-      continue;
-    }
-
-    if (!inQuotes && (char === '"' || char === "'")) {
-      // Start quoted string
-      inQuotes = true;
-      quoteChar = char;
-      continue;
-    }
-
-    if (inQuotes && char === quoteChar) {
-      // End quoted string
-      inQuotes = false;
-      quoteChar = "";
-      continue;
-    }
-
-    if (!inQuotes && /\s/.test(char)) {
-      // Whitespace outside quotes - end current argument
-      if (current) {
-        args.push(current);
-        current = "";
-      }
-      continue;
-    }
-
-    current += char;
-  }
-
-  // Add final argument if any
-  if (current) {
-    args.push(current);
-  }
-
-  return args;
-}
-
-/**
- * Substitute command parameters in content
- */
-export function substituteCommandParameters(
-  content: string,
-  argsString: string,
-): string {
-  if (!hasParameterPlaceholders(content)) {
-    if (!argsString.trim()) {
-      return content;
-    }
-    const separator = content && !/\s$/.test(content) ? " " : "";
-    return `${content}${separator}${argsString}`;
-  }
-
-  const args = parseCommandArguments(argsString);
-
-  let result = content;
-
-  // Replace $ARGUMENTS with all arguments
-  result = result.replace(/\$ARGUMENTS/g, argsString);
-
-  // Replace positional parameters $1, $2, etc.
-  // Sort by parameter number (descending) to avoid replacing $10 with $1 + "0"
-  const positionalParams = [...result.matchAll(/\$(\d+)/g)]
-    .map((match) => parseInt(match[1], 10))
-    .filter((value, index, array) => array.indexOf(value) === index) // unique
-    .sort((a, b) => b - a); // descending order
-
-  for (const paramNum of positionalParams) {
-    const paramValue = args[paramNum - 1] || ""; // Arrays are 0-indexed, params are 1-indexed
-    const paramRegex = new RegExp(`\\$${paramNum}`, "g");
-    result = result.replace(paramRegex, paramValue);
-  }
-
-  return result;
-}
-
-/**
- * Extract command name and arguments from a slash command input
- * Example: "/fix-issue 123 high-priority" -> { command: "fix-issue", args: "123 high-priority" }
- */
-export function parseSlashCommandInput(input: string): {
-  command: string;
-  args: string;
-} {
-  const trimmed = input.trim();
-
-  if (!trimmed.startsWith("/")) {
-    throw new Error("Input must start with /");
-  }
-
-  const withoutSlash = trimmed.substring(1);
-  const firstSpaceIndex = withoutSlash.indexOf(" ");
-
-  if (firstSpaceIndex === -1) {
-    // No arguments
-    return {
-      command: withoutSlash,
-      args: "",
-    };
-  }
-
-  return {
-    command: withoutSlash.substring(0, firstSpaceIndex),
-    args: withoutSlash.substring(firstSpaceIndex + 1).trim(),
-  };
-}
-
-/**
- * Check if content contains parameter placeholders
- */
-export function hasParameterPlaceholders(content: string): boolean {
-  return /\$(?:ARGUMENTS|\d+)/.test(content);
-}
-
-/**
- * Get all parameter placeholders used in content
- */
-export function getUsedParameterPlaceholders(content: string): string[] {
-  const matches = content.match(/\$(?:ARGUMENTS|\d+)/g);
-  return matches ? [...new Set(matches)] : [];
-}

package/src/utils/commandPathResolver.ts

@@ -1,88 +0,0 @@
-import { relative, basename } from "path";
-
-/**
- * Command path resolver utilities for command discovery
- * Handles conversion between file paths and command IDs
- */
-
-/**
- * Generate command ID from file path
- * @param filePath - Absolute path to markdown file
- * @param rootDir - Root commands directory path
- * @returns Command identifier string
- * @throws Error on invalid path structure
- */
-export function generateCommandId(filePath: string, rootDir: string): string {
-  // Handle null/undefined inputs
-  if (filePath == null || rootDir == null) {
-    throw new Error("File path and root directory must be provided");
-  }
-
-  // Handle empty root directory (for root level commands)
-  const relativePath = rootDir === "" ? filePath : relative(rootDir, filePath);
-
-  // Handle edge cases
-  if (!relativePath || relativePath === ".") {
-    throw new Error("Command filename cannot be empty");
-  }
-
-  const segments = relativePath
-    .split(/[\\/]/)
-    .filter((segment) => segment !== "");
-
-  // Remove .md extension from the last segment
-  const lastSegment = segments[segments.length - 1];
-  if (!lastSegment.endsWith(".md")) {
-    throw new Error(`Command files must have .md extension`);
-  }
-
-  const commandName = basename(lastSegment, ".md");
-
-  // Handle empty filename after removing extension
-  if (commandName === "") {
-    throw new Error("Command filename cannot be empty");
-  }
-
-  // Validate depth (no nesting allowed)
-  if (segments.length > 1) {
-    throw new Error(
-      `Command nesting not supported: ${relativePath}. Commands must be in the root directory.`,
-    );
-  }
-
-  // Validate command name
-  if (!validateSegment(commandName)) {
-    throw new Error(
-      `Invalid command name: "${commandName}" in ${relativePath}. Must match pattern /^[a-zA-Z][a-zA-Z0-9_.-]*$/`,
-    );
-  }
-
-  return commandName;
-}
-
-/**
- * Validate command ID format
- * @param commandId - Command identifier to validate
- * @returns Boolean indicating validity
- */
-export function validateCommandId(commandId: string): boolean {
-  // Handle null/undefined inputs
-  if (commandId == null) {
-    return false;
-  }
-
-  // Command ID must be a single segment (no colons)
-  const pattern = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-  return pattern.test(commandId);
-}
-
-/**
- * Validate individual path segment
- * @param segment - Path segment to validate
- * @returns Boolean indicating validity
- */
-function validateSegment(segment: string): boolean {
-  // Segments should start with letters and can contain letters, numbers, dashes, underscores, dots
-  const pattern = /^[a-zA-Z][a-zA-Z0-9_.-]*$/;
-  return pattern.test(segment);
-}