byterover-cli 0.2.0 → 0.3.0

package/dist/infra/cipher/llm/retry/retry-with-backoff.js

@@ -0,0 +1,247 @@
+/**
+ * Retry with Backoff Utility.
+ *
+ * Provides a generic retry mechanism with exponential backoff for async operations.
+ * Used by RetryableContentGenerator and can be used for other retry scenarios.
+ */
+import { calculateRetryDelay, DEFAULT_RETRY_POLICY, isRetryableError, } from './retry-policy.js';
+/**
+ * Sleep for a specified duration.
+ *
+ * @param ms - Duration in milliseconds
+ * @param signal - Optional abort signal
+ * @returns Promise that resolves after the delay
+ */
+async function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('Retry aborted'));
+            return;
+        }
+        const timeout = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timeout);
+            reject(new Error('Retry aborted'));
+        });
+    });
+}
+/**
+ * Execute an async operation with retry and exponential backoff.
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry options
+ * @returns Promise resolving to the operation result or throwing after all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   {
+ *     policy: DEFAULT_RETRY_POLICY,
+ *     onRetry: ({ attempt, delayMs }) => {
+ *       console.log(`Retry ${attempt}, waiting ${delayMs}ms`)
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export async function withRetry(operation, options = {}) {
+    const policy = options.policy ?? DEFAULT_RETRY_POLICY;
+    const maxAttempts = policy.maxRetries + 1;
+    return attemptWithRetry({
+        attempt: 1,
+        maxAttempts,
+        operation,
+        options,
+        policy,
+    });
+}
+/**
+ * Internal helper to attempt retry recursively.
+ */
+async function attemptWithRetry(config) {
+    const { attempt, maxAttempts, operation, options, policy } = config;
+    // Check if aborted
+    if (options.signal?.aborted) {
+        throw new Error('Retry aborted');
+    }
+    try {
+        return await operation();
+    }
+    catch (error) {
+        // Check if this is the last attempt
+        if (attempt >= maxAttempts) {
+            const context = {
+                attempt,
+                delayMs: 0,
+                error,
+                maxAttempts,
+            };
+            options.onExhausted?.(context);
+            throw error;
+        }
+        // Check if error is retryable
+        const isRetryable = options.isRetryable?.(error) ?? isRetryableError(error, policy);
+        if (!isRetryable) {
+            throw error;
+        }
+        // Calculate delay and invoke callback
+        const delayMs = calculateRetryDelay(attempt, policy);
+        const context = {
+            attempt,
+            delayMs,
+            error,
+            maxAttempts,
+        };
+        options.onRetry?.(context);
+        // Wait before retrying
+        await sleep(delayMs, options.signal);
+        // Recursively attempt again
+        return attemptWithRetry({
+            attempt: attempt + 1,
+            maxAttempts,
+            operation,
+            options,
+            policy,
+        });
+    }
+}
+/**
+ * Execute an async operation with retry and return a detailed result.
+ *
+ * Unlike `withRetry`, this function never throws and always returns a result object.
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry options
+ * @returns Promise resolving to a RetryResult object
+ *
+ * @example
+ * ```typescript
+ * const { success, result, error, attempts } = await withRetryResult(
+ *   () => fetchData(),
+ *   { policy: DEFAULT_RETRY_POLICY }
+ * )
+ *
+ * if (success) {
+ *   console.log('Data:', result)
+ * } else {
+ *   console.error('Failed after', attempts, 'attempts:', error)
+ * }
+ * ```
+ */
+export async function withRetryResult(operation, options = {}) {
+    const policy = options.policy ?? DEFAULT_RETRY_POLICY;
+    const maxAttempts = policy.maxRetries + 1;
+    const startTime = Date.now();
+    return attemptWithRetryResult({
+        attempt: 1,
+        maxAttempts,
+        operation,
+        options,
+        policy,
+        startTime,
+    });
+}
+/**
+ * Internal helper to attempt retry recursively with result tracking.
+ */
+async function attemptWithRetryResult(config) {
+    const { attempt, maxAttempts, operation, options, policy, startTime } = config;
+    // Check if aborted
+    if (options.signal?.aborted) {
+        return {
+            attempts: attempt,
+            error: new Error('Retry aborted'),
+            success: false,
+            totalTimeMs: Date.now() - startTime,
+        };
+    }
+    try {
+        const result = await operation();
+        return {
+            attempts: attempt,
+            result,
+            success: true,
+            totalTimeMs: Date.now() - startTime,
+        };
+    }
+    catch (error) {
+        // Check if this is the last attempt
+        if (attempt >= maxAttempts) {
+            const context = {
+                attempt,
+                delayMs: 0,
+                error,
+                maxAttempts,
+            };
+            options.onExhausted?.(context);
+            return {
+                attempts: attempt,
+                error,
+                success: false,
+                totalTimeMs: Date.now() - startTime,
+            };
+        }
+        // Check if error is retryable
+        const isRetryable = options.isRetryable?.(error) ?? isRetryableError(error, policy);
+        if (!isRetryable) {
+            return {
+                attempts: attempt,
+                error,
+                success: false,
+                totalTimeMs: Date.now() - startTime,
+            };
+        }
+        // Calculate delay and invoke callback
+        const delayMs = calculateRetryDelay(attempt, policy);
+        const context = {
+            attempt,
+            delayMs,
+            error,
+            maxAttempts,
+        };
+        options.onRetry?.(context);
+        // Wait before retrying
+        try {
+            await sleep(delayMs, options.signal);
+        }
+        catch {
+            // Aborted during sleep
+            return {
+                attempts: attempt,
+                error: new Error('Retry aborted'),
+                success: false,
+                totalTimeMs: Date.now() - startTime,
+            };
+        }
+        // Recursively attempt again
+        return attemptWithRetryResult({
+            attempt: attempt + 1,
+            maxAttempts,
+            operation,
+            options,
+            policy,
+            startTime,
+        });
+    }
+}
+/**
+ * Create a retryable version of an async function.
+ *
+ * @param fn - The async function to wrap
+ * @param options - Retry options
+ * @returns A new function that will retry on failure
+ *
+ * @example
+ * ```typescript
+ * const retryableFetch = makeRetryable(
+ *   (url: string) => fetch(url).then(r => r.json()),
+ *   { policy: DEFAULT_RETRY_POLICY }
+ * )
+ *
+ * const data = await retryableFetch('https://api.example.com/data')
+ * ```
+ */
+export function makeRetryable(fn, options = {}) {
+    return (...args) => withRetry(() => fn(...args), options);
+}

package/dist/infra/cipher/llm/thought-parser.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Thought Parsing Utilities
+ *
+ * Handles parsing and processing of thinking/thought signatures from Gemini models.
+ * Thoughts represent the model's reasoning process before generating responses or tool calls.
+ */
+/**
+ * Parsed thought summary with subject and description
+ */
+export interface ThoughtSummary {
+    /**
+     * Description or details of the thought
+     */
+    description: string;
+    /**
+     * Subject of the thought (extracted from **subject** format)
+     */
+    subject: string;
+}
+/**
+ * Thinking configuration for Gemini models
+ */
+export interface ThinkingConfig {
+    /**
+     * Whether to include thoughts in responses
+     * @default false
+     */
+    includeThoughts?: boolean;
+    /**
+     * Thinking token budget for Gemini 2.x models
+     * @default 512
+     */
+    thinkingBudget?: number;
+    /**
+     * Thinking level for Gemini 3.x models
+     * @default 'HIGH'
+     */
+    thinkingLevel?: ThinkingLevel;
+}
+/**
+ * Thinking levels for Gemini 3.x models
+ */
+export declare enum ThinkingLevel {
+    HIGH = "HIGH",
+    LOW = "LOW",
+    MEDIUM = "MEDIUM",
+    UNSPECIFIED = "THINKING_LEVEL_UNSPECIFIED"
+}
+/**
+ * Default thinking mode token budget
+ */
+export declare const DEFAULT_THINKING_BUDGET = 512;
+/**
+ * Synthetic thought signature used for Preview models
+ */
+export declare const SYNTHETIC_THOUGHT_SIGNATURE = "skip_thought_signature_validator";
+/**
+ * Utility object for parsing thoughts from LLM responses
+ */
+export declare const ThoughtParser: {
+    /**
+     * Delimiters for subject extraction
+     */
+    readonly END_DELIMITER: "**";
+    /**
+     * Extract just the description from thought text
+     *
+     * @param text - Thought text
+     * @returns Description string
+     */
+    readonly extractDescription: (text: string) => string;
+    /**
+     * Extract just the subject from thought text
+     *
+     * @param text - Thought text
+     * @returns Subject string or empty if no subject found
+     */
+    readonly extractSubject: (text: string) => string;
+    /**
+     * Check if text contains a thought subject
+     *
+     * @param text - Text to check
+     * @returns True if text contains **subject** format
+     */
+    readonly hasSubject: (text: string) => boolean;
+    /**
+     * Parse thought text into subject and description.
+     *
+     * Extracts subject from **subject** format:
+     * - Text between ** ** becomes the subject
+     * - Rest of the text becomes the description
+     *
+     * @param rawText - Raw thought text from LLM
+     * @returns Parsed thought summary
+     *
+     * @example
+     * ```typescript
+     * const thought = ThoughtParser.parse("**Analyzing code** Let me review the structure")
+     * // Returns: { subject: "Analyzing code", description: "Let me review the structure" }
+     * ```
+     */
+    readonly parse: (rawText: string) => ThoughtSummary;
+    /**
+     * Delimiters for subject extraction
+     */
+    readonly START_DELIMITER: "**";
+};
+/**
+ * Utility object for managing thinking configuration
+ */
+export declare const ThinkingConfigManager: {
+    /**
+     * Get thinking config based on model version
+     *
+     * - Gemini 3.x: Uses thinkingLevel
+     * - Gemini 2.x: Uses thinkingBudget
+     * - Other models: No thinking config
+     *
+     * @param model - Model identifier
+     * @returns Thinking configuration or undefined
+     */
+    readonly getConfigForModel: (model: string) => ThinkingConfig | undefined;
+    /**
+     * Check if model is a preview model requiring thought signatures
+     *
+     * @param model - Model identifier
+     * @returns True if model is preview
+     */
+    readonly isPreviewModel: (model: string) => boolean;
+    /**
+     * Merge user config with model defaults
+     *
+     * @param model - Model identifier
+     * @param userConfig - User-provided config (optional)
+     * @returns Merged configuration
+     */
+    readonly mergeConfig: (model: string, userConfig?: ThinkingConfig) => ThinkingConfig | undefined;
+    /**
+     * Check if model supports thinking
+     *
+     * @param model - Model identifier
+     * @returns True if model supports thinking
+     */
+    readonly supportsThinking: (model: string) => boolean;
+};

package/dist/infra/cipher/llm/thought-parser.js

@@ -0,0 +1,190 @@
+/**
+ * Thought Parsing Utilities
+ *
+ * Handles parsing and processing of thinking/thought signatures from Gemini models.
+ * Thoughts represent the model's reasoning process before generating responses or tool calls.
+ */
+/**
+ * Thinking levels for Gemini 3.x models
+ */
+export var ThinkingLevel;
+(function (ThinkingLevel) {
+    ThinkingLevel["HIGH"] = "HIGH";
+    ThinkingLevel["LOW"] = "LOW";
+    ThinkingLevel["MEDIUM"] = "MEDIUM";
+    ThinkingLevel["UNSPECIFIED"] = "THINKING_LEVEL_UNSPECIFIED";
+})(ThinkingLevel || (ThinkingLevel = {}));
+/**
+ * Default thinking mode token budget
+ */
+export const DEFAULT_THINKING_BUDGET = 512;
+/**
+ * Synthetic thought signature used for Preview models
+ */
+export const SYNTHETIC_THOUGHT_SIGNATURE = 'skip_thought_signature_validator';
+/**
+ * Utility object for parsing thoughts from LLM responses
+ */
+export const ThoughtParser = {
+    /**
+     * Delimiters for subject extraction
+     */
+    END_DELIMITER: '**',
+    /**
+     * Extract just the description from thought text
+     *
+     * @param text - Thought text
+     * @returns Description string
+     */
+    extractDescription(text) {
+        const { description } = this.parse(text);
+        return description;
+    },
+    /**
+     * Extract just the subject from thought text
+     *
+     * @param text - Thought text
+     * @returns Subject string or empty if no subject found
+     */
+    extractSubject(text) {
+        const { subject } = this.parse(text);
+        return subject;
+    },
+    /**
+     * Check if text contains a thought subject
+     *
+     * @param text - Text to check
+     * @returns True if text contains **subject** format
+     */
+    hasSubject(text) {
+        if (!text)
+            return false;
+        const startIndex = text.indexOf(this.START_DELIMITER);
+        if (startIndex === -1)
+            return false;
+        const endIndex = text.indexOf(this.END_DELIMITER, startIndex + this.START_DELIMITER.length);
+        return endIndex !== -1;
+    },
+    /**
+     * Parse thought text into subject and description.
+     *
+     * Extracts subject from **subject** format:
+     * - Text between ** ** becomes the subject
+     * - Rest of the text becomes the description
+     *
+     * @param rawText - Raw thought text from LLM
+     * @returns Parsed thought summary
+     *
+     * @example
+     * ```typescript
+     * const thought = ThoughtParser.parse("**Analyzing code** Let me review the structure")
+     * // Returns: { subject: "Analyzing code", description: "Let me review the structure" }
+     * ```
+     */
+    parse(rawText) {
+        if (!rawText) {
+            return { description: '', subject: '' };
+        }
+        const startIndex = rawText.indexOf(this.START_DELIMITER);
+        // No delimiter found - entire text is description
+        if (startIndex === -1) {
+            return { description: rawText.trim(), subject: '' };
+        }
+        const endIndex = rawText.indexOf(this.END_DELIMITER, startIndex + this.START_DELIMITER.length);
+        // End delimiter not found - entire text is description
+        if (endIndex === -1) {
+            return { description: rawText.trim(), subject: '' };
+        }
+        // Extract subject from between delimiters
+        const subject = rawText
+            .slice(startIndex + this.START_DELIMITER.length, endIndex)
+            .trim();
+        // Rest is description (before start + after end)
+        const description = (rawText.slice(0, startIndex) +
+            rawText.slice(endIndex + this.END_DELIMITER.length)).trim();
+        return { description, subject };
+    },
+    /**
+     * Delimiters for subject extraction
+     */
+    START_DELIMITER: '**',
+};
+/**
+ * Utility object for managing thinking configuration
+ */
+export const ThinkingConfigManager = {
+    /**
+     * Get thinking config based on model version
+     *
+     * - Gemini 3.x: Uses thinkingLevel
+     * - Gemini 2.x: Uses thinkingBudget
+     * - Other models: No thinking config
+     *
+     * @param model - Model identifier
+     * @returns Thinking configuration or undefined
+     */
+    getConfigForModel(model) {
+        const lowerModel = model.toLowerCase();
+        // Only Gemini models support thinking
+        if (!lowerModel.includes('gemini')) {
+            return undefined;
+        }
+        // Gemini 3.x models
+        if (lowerModel.startsWith('gemini-3') || lowerModel.includes('gemini-3')) {
+            return {
+                includeThoughts: false,
+                thinkingLevel: ThinkingLevel.HIGH,
+            };
+        }
+        // Gemini 2.x models
+        if (lowerModel.startsWith('gemini-2') || lowerModel.includes('gemini-2')) {
+            return {
+                includeThoughts: false,
+                thinkingBudget: DEFAULT_THINKING_BUDGET,
+            };
+        }
+        // Other Gemini models - use budget as default
+        return {
+            includeThoughts: false,
+            thinkingBudget: DEFAULT_THINKING_BUDGET,
+        };
+    },
+    /**
+     * Check if model is a preview model requiring thought signatures
+     *
+     * @param model - Model identifier
+     * @returns True if model is preview
+     */
+    isPreviewModel(model) {
+        return model.toLowerCase().includes('preview');
+    },
+    /**
+     * Merge user config with model defaults
+     *
+     * @param model - Model identifier
+     * @param userConfig - User-provided config (optional)
+     * @returns Merged configuration
+     */
+    mergeConfig(model, userConfig) {
+        const modelDefaults = this.getConfigForModel(model);
+        if (!modelDefaults) {
+            return userConfig;
+        }
+        if (!userConfig) {
+            return modelDefaults;
+        }
+        return {
+            ...modelDefaults,
+            ...userConfig,
+        };
+    },
+    /**
+     * Check if model supports thinking
+     *
+     * @param model - Model identifier
+     * @returns True if model supports thinking
+     */
+    supportsThinking(model) {
+        return model.toLowerCase().includes('gemini');
+    },
+};

package/dist/infra/cipher/llm/tokenizers/claude-tokenizer.d.ts

@@ -0,0 +1,47 @@
+import type { ITokenizer } from '../../../../core/interfaces/cipher/i-tokenizer.js';
+/**
+ * Tokenizer for Anthropic Claude models - CURRENTLY USING APPROXIMATION.
+ *
+ * This implementation uses a character-based approximation rather than
+ * accurate token counting. This is a temporary solution due to the
+ * complexity of integrating Anthropic's token counting API.
+ *
+ * Claude models use a tokenizer similar to GPT's, with approximately
+ * 3.5-4 characters per token for English text. We use 3.5 as a middle ground.
+ *
+ * TODO: Consider these improvements:
+ * 1. Use Anthropic's official token counting API (requires async handling or separate service)
+ * 2. Implement a WASM-based tokenizer for accurate synchronous counting
+ * 3. Cache token counts for frequently used text
+ * 4. Model-specific adjustments based on actual Claude tokenization patterns
+ *
+ * Reference: https://docs.anthropic.com/en/docs/about-claude/models
+ */
+export declare class ClaudeTokenizer implements ITokenizer {
+    private readonly modelName;
+    /**
+     * Creates a new Claude tokenizer instance.
+     *
+     * @param model - The Claude model name (e.g., 'claude-3-5-sonnet-20241022', 'claude-3-opus-20240229')
+     *                Currently not used for approximation, but stored for future improvements
+     */
+    constructor(model: string);
+    /**
+     * Approximates the token count for Anthropic Claude models.
+     *
+     * Uses a character-based approximation: ~3.5 characters per token.
+     * This is based on Anthropic's documentation and common patterns for
+     * English text with Claude's tokenizer.
+     *
+     * IMPORTANT: This is NOT accurate for Claude models and should be replaced
+     * with a proper implementation when possible. The actual token count can vary
+     * significantly based on:
+     * - Language (non-English text may have different ratios)
+     * - Content type (code vs prose)
+     * - Special characters and formatting
+     *
+     * @param text - Text content to count tokens for
+     * @returns Approximate number of tokens
+     */
+    countTokens(text: string): number;
+}

package/dist/infra/cipher/llm/tokenizers/claude-tokenizer.js

@@ -0,0 +1,55 @@
+/**
+ * Tokenizer for Anthropic Claude models - CURRENTLY USING APPROXIMATION.
+ *
+ * This implementation uses a character-based approximation rather than
+ * accurate token counting. This is a temporary solution due to the
+ * complexity of integrating Anthropic's token counting API.
+ *
+ * Claude models use a tokenizer similar to GPT's, with approximately
+ * 3.5-4 characters per token for English text. We use 3.5 as a middle ground.
+ *
+ * TODO: Consider these improvements:
+ * 1. Use Anthropic's official token counting API (requires async handling or separate service)
+ * 2. Implement a WASM-based tokenizer for accurate synchronous counting
+ * 3. Cache token counts for frequently used text
+ * 4. Model-specific adjustments based on actual Claude tokenization patterns
+ *
+ * Reference: https://docs.anthropic.com/en/docs/about-claude/models
+ */
+export class ClaudeTokenizer {
+    modelName;
+    /**
+     * Creates a new Claude tokenizer instance.
+     *
+     * @param model - The Claude model name (e.g., 'claude-3-5-sonnet-20241022', 'claude-3-opus-20240229')
+     *                Currently not used for approximation, but stored for future improvements
+     */
+    constructor(model) {
+        this.modelName = model;
+    }
+    /**
+     * Approximates the token count for Anthropic Claude models.
+     *
+     * Uses a character-based approximation: ~3.5 characters per token.
+     * This is based on Anthropic's documentation and common patterns for
+     * English text with Claude's tokenizer.
+     *
+     * IMPORTANT: This is NOT accurate for Claude models and should be replaced
+     * with a proper implementation when possible. The actual token count can vary
+     * significantly based on:
+     * - Language (non-English text may have different ratios)
+     * - Content type (code vs prose)
+     * - Special characters and formatting
+     *
+     * @param text - Text content to count tokens for
+     * @returns Approximate number of tokens
+     */
+    countTokens(text) {
+        if (!text) {
+            return 0;
+        }
+        // Approximation: ~3.5 characters per token
+        // Claude's tokenizer is similar to GPT's, typically more efficient than 4 chars/token
+        return Math.ceil(text.length / 3.5);
+    }
+}