byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/llm/openrouter-llm-service.js

@@ -29,8 +29,8 @@ export class OpenRouterLLMService {
     formatter;
     logger;
     memoryManager;
-    promptFactory;
     sessionEventBus;
+    systemPromptManager;
     tokenizer;
     toolManager;
     /**
@@ -48,7 +48,7 @@ export class OpenRouterLLMService {
      */
     constructor(sessionId, config, options) {
         this.toolManager = options.toolManager;
-        this.promptFactory = options.systemPromptManager;
+        this.systemPromptManager = options.systemPromptManager;
         this.memoryManager = options.memoryManager;
         this.sessionEventBus = options.sessionEventBus;
         this.logger = options.logger ?? new NoOpLogger();
@@ -97,23 +97,22 @@ export class OpenRouterLLMService {
      * 3. Returning final response when no more tool calls
      *
      * @param textInput - User input text
-     * @param sessionId - Session ID for tracking the conversation
      * @param options - Execution options
      * @param options.signal - Optional abort signal for cancellation
      * @param options.imageData - Optional image data
      * @param options.fileData - Optional file data
      * @param options.stream - Whether to stream response (not implemented yet)
      * @param options.executionContext - Optional execution context (for JSON input mode, etc.)
-     * @param options.mode - Optional mode for system prompt ('json-input' enables autonomous mode)
+     * @param options.taskId - Task ID for billing tracking
      * @returns Final assistant response
      */
-    async completeTask(textInput, sessionId, options) {
+    async completeTask(textInput, options) {
         // Extract options with defaults
-        const { executionContext, fileData, imageData, mode, signal } = options ?? {};
+        const { executionContext, fileData, imageData, signal } = options ?? {};
         // Add user message to context
         await this.contextManager.addUserMessage(textInput, imageData, fileData);
-        // Get all available tools
-        const toolSet = this.toolManager.getAllTools();
+        // Get filtered tools based on command type (e.g., only read-only tools for 'query')
+        const toolSet = this.toolManager.getToolsForCommand(executionContext?.commandType);
         const tools = Object.entries(toolSet).map(([name, schema]) => ({
             function: {
                 description: schema.description ?? '',
@@ -131,7 +130,7 @@ export class OpenRouterLLMService {
             }
             try {
                 // eslint-disable-next-line no-await-in-loop -- Sequential iterations required for agentic loop
-                const result = await this.executeAgenticIteration(iterationCount, tools, executionContext, mode);
+                const result = await this.executeAgenticIteration(iterationCount, tools, executionContext);
                 if (result !== null) {
                     return result;
                 }
@@ -211,25 +210,24 @@ export class OpenRouterLLMService {
      * @param iterationCount - Current iteration number
      * @param tools - Available tools for this iteration
      * @param executionContext - Optional execution context
-     * @param mode - Optional mode for system prompt
      * @returns Final response string if complete, null if more iterations needed
      */
-    async executeAgenticIteration(iterationCount, tools, executionContext, mode) {
-        // Build system prompt using SimplePromptFactory (before compression for correct token accounting)
-        const availableTools = this.toolManager.getToolNames();
+    async executeAgenticIteration(iterationCount, tools, executionContext) {
+        // Build system prompt using SystemPromptManager (before compression for correct token accounting)
+        // Use filtered tool names based on command type (e.g., only read-only tools for 'query')
+        const availableTools = this.toolManager.getToolNamesForCommand(executionContext?.commandType);
         const markersSet = this.toolManager.getAvailableMarkers();
-        // Convert Set<string> to Record<string, string> for SimplePromptFactory
+        // Convert Set<string> to Record<string, string> for SystemPromptManager
         const availableMarkers = {};
         for (const marker of markersSet) {
             availableMarkers[marker] = marker;
         }
-        const systemPrompt = await this.promptFactory.buildSystemPrompt({
+        const systemPrompt = await this.systemPromptManager.build({
             availableMarkers,
             availableTools,
             commandType: executionContext?.commandType,
             conversationMetadata: executionContext?.conversationMetadata,
             memoryManager: this.memoryManager,
-            mode,
         });
         // Verbose debug: Show complete system prompt
         if (this.config.verbose) {

package/dist/infra/cipher/llm/retry/retry-policy.d.ts

@@ -31,6 +31,7 @@ export interface RetryPolicy {
  * - 2x exponential backoff
  * - 25% jitter
  * - Retries on common transient errors (429, 500, 502, 503, 504)
+ * - Retries on empty/incomplete LLM responses (transient API issues)
  */
 export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
 /**

package/dist/infra/cipher/llm/retry/retry-policy.js

@@ -12,6 +12,7 @@
  * - 2x exponential backoff
  * - 25% jitter
  * - Retries on common transient errors (429, 500, 502, 503, 504)
+ * - Retries on empty/incomplete LLM responses (transient API issues)
  */
 export const DEFAULT_RETRY_POLICY = {
     backoffMultiplier: 2,
@@ -29,6 +30,11 @@ export const DEFAULT_RETRY_POLICY = {
         'capacity',
         'timeout',
         'temporarily unavailable',
+        // LLM empty/incomplete response errors (transient API issues)
+        'neither content nor tool calls',
+        'no content',
+        'empty response',
+        'no messages',
     ],
     retryableStatusCodes: [429, 500, 502, 503, 504],
 };
@@ -53,6 +59,11 @@ export const AGGRESSIVE_RETRY_POLICY = {
         'capacity',
         'timeout',
         'temporarily unavailable',
+        // LLM empty/incomplete response errors (transient API issues)
+        'neither content nor tool calls',
+        'no content',
+        'empty response',
+        'no messages',
     ],
     retryableStatusCodes: [429, 500, 502, 503, 504],
 };

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

@@ -19,10 +19,11 @@ async function sleep(ms, signal) {
             return;
         }
         const timeout = setTimeout(resolve, ms);
-        signal?.addEventListener('abort', () => {
+        const abortHandler = () => {
             clearTimeout(timeout);
             reject(new Error('Retry aborted'));
-        });
+        };
+        signal?.addEventListener('abort', abortHandler, { once: true });
     });
 }
 /**

package/dist/infra/cipher/llm/sanitization/base64-utils.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Base64 detection and parsing utilities for tool output sanitization.
+ *
+ * These utilities help identify and process base64-encoded content in tool outputs,
+ * enabling the sanitization pipeline to detect and handle binary data appropriately.
+ *
+ * Based on dexto's isLikelyBase64String() and parseDataUri() patterns.
+ */
+/**
+ * Check if a string is likely a Base64-encoded binary blob.
+ *
+ * Uses heuristics to detect base64 content:
+ * 1. Length threshold (default 512 chars)
+ * 2. Character set matching (base64 alphabet only)
+ * 3. Low non-base64 character ratio
+ *
+ * This is intentionally conservative to avoid false positives on
+ * normal text that happens to look like base64.
+ *
+ * @param value - The string to check
+ * @param minLength - Minimum length threshold (default: 512)
+ * @returns true if the string is likely base64-encoded binary data
+ */
+export declare function isLikelyBase64String(value: string, minLength?: number): boolean;
+/**
+ * Result of parsing a data URI.
+ */
+export interface ParsedDataUri {
+    /** The base64-encoded content */
+    base64: string;
+    /** The MIME type from the data URI */
+    mediaType: string;
+}
+/**
+ * Parse a data URI and extract media type and base64 content.
+ *
+ * Supports the standard data URI format:
+ * data:[<mediatype>][;base64],<data>
+ *
+ * @param value - The data URI string to parse
+ * @returns Parsed components or null if not a valid base64 data URI
+ */
+export declare function parseDataUri(value: string): null | ParsedDataUri;
+/**
+ * Estimate byte length from base64 string length.
+ *
+ * Base64 encoding uses 4 characters to represent 3 bytes.
+ * This approximation is useful for size threshold checks.
+ *
+ * @param charLength - Length of the base64 string
+ * @returns Approximate byte count of the decoded data
+ */
+export declare function base64LengthToBytes(charLength: number): number;
+/**
+ * Format byte size as human-readable string.
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string like "1.5 KB" or "2.3 MB"
+ */
+export declare function formatByteSize(bytes: number): string;
+/**
+ * Check if a value is a valid base64 string (strict check).
+ *
+ * Unlike isLikelyBase64String which uses heuristics, this performs
+ * a stricter validation that the string is valid base64 format.
+ *
+ * @param value - The string to validate
+ * @returns true if valid base64 format
+ */
+export declare function isValidBase64(value: string): boolean;
+/**
+ * Safely decode base64 string to Buffer.
+ *
+ * @param base64 - Base64 encoded string
+ * @returns Decoded Buffer or null if invalid
+ */
+export declare function safeBase64Decode(base64: string): Buffer | null;
+/**
+ * Encode data to base64 string.
+ *
+ * @param data - Data to encode (Buffer, Uint8Array, or string)
+ * @returns Base64 encoded string
+ */
+export declare function encodeToBase64(data: Buffer | string | Uint8Array): string;
+/**
+ * Create a data URI from base64 content and MIME type.
+ *
+ * @param base64 - Base64 encoded content
+ * @param mimeType - MIME type of the content
+ * @returns Data URI string
+ */
+export declare function createDataUri(base64: string, mimeType: string): string;
+/**
+ * Extract base64 content from a data URI or return the original if not a data URI.
+ *
+ * @param value - Data URI or raw base64 string
+ * @returns Object with base64 content and optional MIME type
+ */
+export declare function extractBase64Content(value: string): {
+    base64: string;
+    mimeType?: string;
+};

package/dist/infra/cipher/llm/sanitization/base64-utils.js

@@ -0,0 +1,182 @@
+/**
+ * Base64 detection and parsing utilities for tool output sanitization.
+ *
+ * These utilities help identify and process base64-encoded content in tool outputs,
+ * enabling the sanitization pipeline to detect and handle binary data appropriately.
+ *
+ * Based on dexto's isLikelyBase64String() and parseDataUri() patterns.
+ */
+/**
+ * Default minimum length for base64 heuristic detection.
+ * Strings shorter than this are unlikely to be meaningful base64 blobs.
+ */
+const MIN_BASE64_HEURISTIC_LENGTH = 512;
+/**
+ * Regular expression for valid base64 characters.
+ * Includes standard base64 alphabet plus padding and optional whitespace.
+ */
+const BASE64_CHARSET_REGEX = /^[A-Za-z0-9+/=\r\n\s]+$/;
+/**
+ * Check if a string is likely a Base64-encoded binary blob.
+ *
+ * Uses heuristics to detect base64 content:
+ * 1. Length threshold (default 512 chars)
+ * 2. Character set matching (base64 alphabet only)
+ * 3. Low non-base64 character ratio
+ *
+ * This is intentionally conservative to avoid false positives on
+ * normal text that happens to look like base64.
+ *
+ * @param value - The string to check
+ * @param minLength - Minimum length threshold (default: 512)
+ * @returns true if the string is likely base64-encoded binary data
+ */
+export function isLikelyBase64String(value, minLength = MIN_BASE64_HEURISTIC_LENGTH) {
+    if (!value || typeof value !== 'string')
+        return false;
+    if (value.length < minLength)
+        return false;
+    // Fast-path for data URIs which explicitly declare base64
+    if (value.startsWith('data:') && value.includes(';base64,'))
+        return true;
+    // Check character set - must be valid base64 characters
+    if (!BASE64_CHARSET_REGEX.test(value))
+        return false;
+    // Calculate non-base64 character ratio (whitespace excluded)
+    const strippedValue = value.replaceAll(/[\r\n\s]/g, '');
+    const nonBase64Count = (strippedValue.match(/[^A-Za-z0-9+/=]/g) || []).length;
+    const nonBase64Ratio = nonBase64Count / strippedValue.length;
+    // Very low ratio of non-base64 chars suggests actual base64
+    return nonBase64Ratio < 0.01;
+}
+/**
+ * Parse a data URI and extract media type and base64 content.
+ *
+ * Supports the standard data URI format:
+ * data:[<mediatype>][;base64],<data>
+ *
+ * @param value - The data URI string to parse
+ * @returns Parsed components or null if not a valid base64 data URI
+ */
+export function parseDataUri(value) {
+    if (!value || typeof value !== 'string')
+        return null;
+    if (!value.startsWith('data:'))
+        return null;
+    const commaIndex = value.indexOf(',');
+    if (commaIndex === -1)
+        return null;
+    const meta = value.slice(5, commaIndex); // Skip 'data:'
+    // Must be base64 encoded
+    if (!/;base64$/i.test(meta))
+        return null;
+    const mediaType = meta.replace(/;base64$/i, '') || 'application/octet-stream';
+    const base64 = value.slice(commaIndex + 1);
+    return { base64, mediaType };
+}
+/**
+ * Estimate byte length from base64 string length.
+ *
+ * Base64 encoding uses 4 characters to represent 3 bytes.
+ * This approximation is useful for size threshold checks.
+ *
+ * @param charLength - Length of the base64 string
+ * @returns Approximate byte count of the decoded data
+ */
+export function base64LengthToBytes(charLength) {
+    // Remove padding chars from calculation for accuracy
+    const paddingChars = charLength > 0 ? (charLength % 4 === 0 ? 0 : 4 - (charLength % 4)) : 0;
+    return Math.floor(((charLength - paddingChars) * 3) / 4);
+}
+/**
+ * Format byte size as human-readable string.
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string like "1.5 KB" or "2.3 MB"
+ */
+export function formatByteSize(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${Number.parseFloat((bytes / k ** i).toFixed(1))} ${sizes[i]}`;
+}
+/**
+ * Check if a value is a valid base64 string (strict check).
+ *
+ * Unlike isLikelyBase64String which uses heuristics, this performs
+ * a stricter validation that the string is valid base64 format.
+ *
+ * @param value - The string to validate
+ * @returns true if valid base64 format
+ */
+export function isValidBase64(value) {
+    if (!value || typeof value !== 'string')
+        return false;
+    // Remove whitespace
+    const cleaned = value.replaceAll(/[\r\n\s]/g, '');
+    // Check length is multiple of 4
+    if (cleaned.length % 4 !== 0)
+        return false;
+    // Check character set
+    return /^[A-Za-z0-9+/]*={0,2}$/.test(cleaned);
+}
+/**
+ * Safely decode base64 string to Buffer.
+ *
+ * @param base64 - Base64 encoded string
+ * @returns Decoded Buffer or null if invalid
+ */
+export function safeBase64Decode(base64) {
+    try {
+        // Remove whitespace
+        const cleaned = base64.replaceAll(/[\r\n\s]/g, '');
+        // Validate before decoding
+        if (!isValidBase64(cleaned))
+            return null;
+        return Buffer.from(cleaned, 'base64');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Encode data to base64 string.
+ *
+ * @param data - Data to encode (Buffer, Uint8Array, or string)
+ * @returns Base64 encoded string
+ */
+export function encodeToBase64(data) {
+    if (typeof data === 'string') {
+        return Buffer.from(data, 'utf8').toString('base64');
+    }
+    if (Buffer.isBuffer(data)) {
+        return data.toString('base64');
+    }
+    // At this point, data must be Uint8Array
+    return Buffer.from(data).toString('base64');
+}
+/**
+ * Create a data URI from base64 content and MIME type.
+ *
+ * @param base64 - Base64 encoded content
+ * @param mimeType - MIME type of the content
+ * @returns Data URI string
+ */
+export function createDataUri(base64, mimeType) {
+    return `data:${mimeType};base64,${base64}`;
+}
+/**
+ * Extract base64 content from a data URI or return the original if not a data URI.
+ *
+ * @param value - Data URI or raw base64 string
+ * @returns Object with base64 content and optional MIME type
+ */
+export function extractBase64Content(value) {
+    const parsed = parseDataUri(value);
+    if (parsed) {
+        return { base64: parsed.base64, mimeType: parsed.mediaType };
+    }
+    return { base64: value };
+}

package/dist/infra/cipher/llm/sanitization/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tool output sanitization module.
+ *
+ * Provides utilities for sanitizing tool outputs:
+ * - Base64 detection and parsing
+ * - Media persistence to blob storage
+ * - Text truncation
+ * - Consistent tool result formatting
+ */
+export { base64LengthToBytes, createDataUri, encodeToBase64, extractBase64Content, formatByteSize, isLikelyBase64String, isValidBase64, parseDataUri, safeBase64Decode, } from './base64-utils.js';
+export type { ParsedDataUri } from './base64-utils.js';
+export { createToolSanitizer, sanitizeToolResult, ToolSanitizer, } from './tool-sanitizer.js';

package/dist/infra/cipher/llm/sanitization/index.js

@@ -0,0 +1,13 @@
+/**
+ * Tool output sanitization module.
+ *
+ * Provides utilities for sanitizing tool outputs:
+ * - Base64 detection and parsing
+ * - Media persistence to blob storage
+ * - Text truncation
+ * - Consistent tool result formatting
+ */
+// Base64 utilities
+export { base64LengthToBytes, createDataUri, encodeToBase64, extractBase64Content, formatByteSize, isLikelyBase64String, isValidBase64, parseDataUri, safeBase64Decode, } from './base64-utils.js';
+// Tool sanitizer
+export { createToolSanitizer, sanitizeToolResult, ToolSanitizer, } from './tool-sanitizer.js';

package/dist/infra/cipher/llm/sanitization/tool-sanitizer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tool output sanitization pipeline.
+ *
+ * This module provides a comprehensive sanitization pipeline for tool outputs:
+ * 1. normalize() - Convert arbitrary tool output to MessagePart[]
+ * 2. persistMedia() - Store large media as blob references
+ * 3. applySanitization() - Apply final cleanup (truncation, etc.)
+ *
+ */
+import type { IBlobStorage } from '../../../../core/interfaces/cipher/i-blob-storage.js';
+import type { MessagePart } from '../../../../core/interfaces/cipher/message-types.js';
+import type { NormalizedToolOutput, PersistMediaResult, SanitizedToolResult, SanitizeToolResultOptions } from '../../../../core/interfaces/cipher/sanitization-types.js';
+/**
+ * Tool output sanitizer.
+ *
+ * Provides a pipeline for sanitizing tool outputs:
+ * - Normalizes arbitrary output formats to MessagePart[]
+ * - Stores large media in blob storage with lazy references
+ * - Applies text truncation and cleanup
+ */
+export declare class ToolSanitizer {
+    private readonly blobStorage?;
+    private readonly maxInlineMediaBytes;
+    private readonly maxTextLength;
+    constructor(options?: {
+        blobStorage?: IBlobStorage;
+        maxInlineMediaBytes?: number;
+        maxTextLength?: number;
+    });
+    /**
+     * Step 3: Apply final sanitization (truncation, etc.).
+     */
+    applySanitization(parts: MessagePart[], maxTextLength?: number): MessagePart[];
+    /**
+     * Step 1: Normalize arbitrary tool output to MessagePart array.
+     */
+    normalize(result: unknown): NormalizedToolOutput;
+    /**
+     * Step 2: Persist large media to blob storage.
+     */
+    persistMedia(parts: MessagePart[], toolName: string, toolCallId: string, maxInlineBytes?: number): Promise<PersistMediaResult>;
+    /**
+     * Sanitize a tool result through the full pipeline.
+     */
+    sanitize(result: unknown, options: SanitizeToolResultOptions): Promise<SanitizedToolResult>;
+    private extractData;
+    private generateBlobId;
+    private normalizeArray;
+    private normalizeArrayItem;
+    private normalizeObject;
+    private normalizeResourceContent;
+    private normalizeString;
+    private normalizeValue;
+    private persistFileIfNeeded;
+    private persistImageIfNeeded;
+    /**
+     * Recursively sanitize object, replacing large base64 with placeholders.
+     */
+    private sanitizeDeepObject;
+    private storeAsBlob;
+    private truncateText;
+}
+/**
+ * Create a ToolSanitizer instance.
+ */
+export declare function createToolSanitizer(options?: {
+    blobStorage?: IBlobStorage;
+    maxInlineMediaBytes?: number;
+    maxTextLength?: number;
+}): ToolSanitizer;
+/**
+ * Convenience function to sanitize a tool result with default options.
+ */
+export declare function sanitizeToolResult(result: unknown, options: SanitizeToolResultOptions): Promise<SanitizedToolResult>;