byterover-cli 0.4.1 → 1.0.1

package/dist/infra/cipher/llm/tool-output-processor.d.ts

@@ -3,7 +3,13 @@
  *
  * Handles truncation and file saving for large tool outputs.
  * Prevents context overflow by truncating outputs while preserving critical information.
+ *
+ * Enhanced with:
+ * - Attachment extraction from structured/MCP-style outputs
+ * - Title extraction for display
+ * - Support for image and file attachments
  */
+import type { AttachmentPart } from '../../../core/interfaces/cipher/message-types.js';
 /**
  * Configuration for output truncation behavior
  */
@@ -33,6 +39,10 @@ export interface TruncationConfig {
  * Result of output processing
  */
 export interface ProcessedOutput {
+    /**
+     * Attachments extracted from tool output (images, files)
+     */
+    attachments?: AttachmentPart[];
     /**
      * Processed content (truncated if necessary)
      */
@@ -54,6 +64,10 @@ export interface ProcessedOutput {
          */
         truncated?: boolean;
     };
+    /**
+     * Human-readable title for display
+     */
+    title?: string;
 }
 /**
  * Default truncation configuration
@@ -83,6 +97,43 @@ export declare class ToolOutputProcessor {
      * @returns Processed output with metadata
      */
     processOutput(toolName: string, output: unknown): Promise<ProcessedOutput>;
+    /**
+     * Process structured tool output that may contain attachments.
+     *
+     * Handles:
+     * - MCP-style responses with content array (text + image items)
+     * - Structured outputs with explicit attachments array
+     * - Title extraction for display
+     *
+     * @param toolName - Name of the tool that produced the output
+     * @param output - Raw tool output (structured or plain)
+     * @returns Processed output with attachments and title
+     */
+    processStructuredOutput(toolName: string, output: unknown): Promise<ProcessedOutput>;
+    /**
+     * Extract attachments from structured output.
+     */
+    private extractAttachments;
+    /**
+     * Extract attachments from MCP-style content array.
+     */
+    private extractMcpAttachments;
+    /**
+     * Extract text content from MCP-style content array.
+     */
+    private extractMcpTextContent;
+    /**
+     * Extract text content from structured output.
+     */
+    private extractTextContent;
+    /**
+     * Check if output is an MCP-style content array.
+     */
+    private isMcpContentArray;
+    /**
+     * Check if output is a structured output with potential attachments.
+     */
+    private isStructuredOutput;
     /**
      * Save content to a temporary file
      *

package/dist/infra/cipher/llm/tool-output-processor.js

@@ -3,6 +3,11 @@
  *
  * Handles truncation and file saving for large tool outputs.
  * Prevents context overflow by truncating outputs while preserving critical information.
+ *
+ * Enhanced with:
+ * - Attachment extraction from structured/MCP-style outputs
+ * - Title extraction for display
+ * - Support for image and file attachments
  */
 import { existsSync, promises as fsPromises, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -32,6 +37,7 @@ export class ToolOutputProcessor {
             ...config,
         };
     }
+    // ==================== PUBLIC METHODS ====================
     /**
      * Process tool output with truncation and file saving
      *
@@ -67,6 +73,139 @@ export class ToolOutputProcessor {
             },
         };
     }
+    /**
+     * Process structured tool output that may contain attachments.
+     *
+     * Handles:
+     * - MCP-style responses with content array (text + image items)
+     * - Structured outputs with explicit attachments array
+     * - Title extraction for display
+     *
+     * @param toolName - Name of the tool that produced the output
+     * @param output - Raw tool output (structured or plain)
+     * @returns Processed output with attachments and title
+     */
+    async processStructuredOutput(toolName, output) {
+        // Try to detect structured output
+        if (this.isStructuredOutput(output)) {
+            const structured = output;
+            const attachments = this.extractAttachments(structured);
+            const textContent = this.extractTextContent(structured);
+            // Process the text content with truncation
+            const processed = await this.processOutput(toolName, textContent);
+            return {
+                ...processed,
+                attachments: attachments.length > 0 ? attachments : undefined,
+                title: structured.title,
+            };
+        }
+        // Try to detect MCP-style content array
+        if (this.isMcpContentArray(output)) {
+            const contentArray = output;
+            const attachments = this.extractMcpAttachments(contentArray);
+            const textContent = this.extractMcpTextContent(contentArray);
+            // Process the text content with truncation
+            const processed = await this.processOutput(toolName, textContent);
+            return {
+                ...processed,
+                attachments: attachments.length > 0 ? attachments : undefined,
+            };
+        }
+        // Fall back to regular processing
+        return this.processOutput(toolName, output);
+    }
+    // ==================== PRIVATE METHODS (alphabetical order) ====================
+    /**
+     * Extract attachments from structured output.
+     */
+    extractAttachments(structured) {
+        const attachments = [];
+        // Extract from explicit attachments array
+        if (structured.attachments) {
+            for (const att of structured.attachments) {
+                attachments.push({
+                    data: att.data,
+                    filename: att.filename,
+                    mime: att.mimeType,
+                    type: att.type,
+                });
+            }
+        }
+        // Extract images from MCP-style content array
+        if (Array.isArray(structured.content)) {
+            for (const item of structured.content) {
+                if (item.type === 'image' && item.data && item.mimeType) {
+                    attachments.push({
+                        data: `data:${item.mimeType};base64,${item.data}`,
+                        mime: item.mimeType,
+                        type: 'image',
+                    });
+                }
+            }
+        }
+        return attachments;
+    }
+    /**
+     * Extract attachments from MCP-style content array.
+     */
+    extractMcpAttachments(content) {
+        const attachments = [];
+        for (const item of content) {
+            if (item.type === 'image' && item.data && item.mimeType) {
+                attachments.push({
+                    data: `data:${item.mimeType};base64,${item.data}`,
+                    mime: item.mimeType,
+                    type: 'image',
+                });
+            }
+        }
+        return attachments;
+    }
+    /**
+     * Extract text content from MCP-style content array.
+     */
+    extractMcpTextContent(content) {
+        return content
+            .filter((item) => item.type === 'text' && item.text)
+            .map((item) => item.text)
+            .join('\n');
+    }
+    /**
+     * Extract text content from structured output.
+     */
+    extractTextContent(structured) {
+        if (typeof structured.content === 'string') {
+            return structured.content;
+        }
+        if (Array.isArray(structured.content)) {
+            return structured.content
+                .filter((item) => item.type === 'text' && item.text)
+                .map((item) => item.text)
+                .join('\n');
+        }
+        return '';
+    }
+    /**
+     * Check if output is an MCP-style content array.
+     */
+    isMcpContentArray(output) {
+        if (!Array.isArray(output)) {
+            return false;
+        }
+        // Check if all items have a type field
+        return output.every((item) => typeof item === 'object' && item !== null && 'type' in item && (item.type === 'text' || item.type === 'image'));
+    }
+    /**
+     * Check if output is a structured output with potential attachments.
+     */
+    isStructuredOutput(output) {
+        if (typeof output !== 'object' || output === null) {
+            return false;
+        }
+        const obj = output;
+        // Must have at least one of: content, attachments, or title
+        return 'content' in obj || 'attachments' in obj || 'title' in obj;
+    }
     /**
      * Save content to a temporary file
      *

package/dist/infra/cipher/process/command-validator.d.ts

@@ -13,6 +13,29 @@ export declare class CommandValidator {
      * @param config - Process configuration for security settings
      */
     constructor(config: Pick<ProcessConfig, 'allowedCommands' | 'blockedCommands' | 'securityLevel'>);
+    /**
+     * Extract file path arguments from a command.
+     *
+     * Identifies commands that operate on file paths and extracts
+     * the path arguments for validation. Filters out flags (arguments
+     * starting with -) and special arguments like chmod modes.
+     *
+     * @param command - Command string to parse
+     * @returns Array of path arguments (normalized for the current platform)
+     *
+     * @example
+     * extractPathArguments('rm -rf /home/user/file.txt')
+     * // Returns ['/home/user/file.txt']
+     *
+     * @example
+     * extractPathArguments('cp src/file.txt dest/file.txt')
+     * // Returns ['src/file.txt', 'dest/file.txt']
+     *
+     * @example
+     * extractPathArguments('chmod 755 script.sh')
+     * // Returns ['script.sh'] (755 is filtered as chmod mode)
+     */
+    extractPathArguments(command: string): string[];
     /**
      * Get the list of allowed commands.
      *

package/dist/infra/cipher/process/command-validator.js

@@ -1,7 +1,29 @@
+import { normalizePath } from './path-utils.js';
 /**
  * Maximum allowed command length (characters).
  */
 const MAX_COMMAND_LENGTH = 10_000;
+/**
+ * Commands that operate on file paths and need path validation.
+ * These commands take file/directory paths as arguments.
+ */
+const PATH_SENSITIVE_COMMANDS = new Set([
+    'cat',
+    'cd',
+    'chmod',
+    'chown',
+    'cp',
+    'head',
+    'less',
+    'ln',
+    'mkdir',
+    'more',
+    'mv',
+    'rm',
+    'rmdir',
+    'tail',
+    'touch',
+]);
 /**
  * Dangerous patterns that should always be blocked or require approval.
  *
@@ -132,6 +154,59 @@ export class CommandValidator {
     constructor(config) {
         this.config = config;
     }
+    /**
+     * Extract file path arguments from a command.
+     *
+     * Identifies commands that operate on file paths and extracts
+     * the path arguments for validation. Filters out flags (arguments
+     * starting with -) and special arguments like chmod modes.
+     *
+     * @param command - Command string to parse
+     * @returns Array of path arguments (normalized for the current platform)
+     *
+     * @example
+     * extractPathArguments('rm -rf /home/user/file.txt')
+     * // Returns ['/home/user/file.txt']
+     *
+     * @example
+     * extractPathArguments('cp src/file.txt dest/file.txt')
+     * // Returns ['src/file.txt', 'dest/file.txt']
+     *
+     * @example
+     * extractPathArguments('chmod 755 script.sh')
+     * // Returns ['script.sh'] (755 is filtered as chmod mode)
+     */
+    extractPathArguments(command) {
+        const trimmed = command.trim();
+        const parts = trimmed.split(/\s+/);
+        const commandName = parts[0];
+        // Only extract paths from path-sensitive commands
+        if (!PATH_SENSITIVE_COMMANDS.has(commandName)) {
+            return [];
+        }
+        return parts.slice(1).filter((arg) => {
+            // Skip flags (arguments starting with -)
+            if (arg.startsWith('-')) {
+                return false;
+            }
+            // Skip chmod numeric modes (e.g., 755, 0644) and symbolic modes (e.g., +x, u+rwx)
+            if (commandName === 'chmod') {
+                // Numeric mode: 3-4 octal digits
+                if (/^[0-7]{3,4}$/.test(arg)) {
+                    return false;
+                }
+                // Symbolic mode: starts with +, -, or contains = with permission letters
+                if (/^[ugoa]*[+-=][rwxXstugo]+$/.test(arg)) {
+                    return false;
+                }
+            }
+            // Skip chown user:group specifiers (contains : but not a path separator pattern)
+            if (commandName === 'chown' && /^[^/]+:[^/]*$/.test(arg) && !arg.includes('/')) {
+                return false;
+            }
+            return true;
+        }).map((path) => normalizePath(path));
+    }
     /**
      * Get the list of allowed commands.
      *

package/dist/infra/cipher/process/path-utils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Path utilities for cross-platform compatibility.
+ *
+ * Provides functions for normalizing paths across different environments,
+ * particularly handling Git Bash and MSYS/Cygwin Unix-style paths on Windows.
+ */
+/**
+ * Normalize paths for cross-platform compatibility.
+ * Handles Git Bash Unix-style paths on Windows (e.g., /c/Users/... -> C:\Users\...)
+ *
+ * @param inputPath - Path to normalize
+ * @returns Normalized path for the current platform
+ *
+ * @example
+ * // On Windows with Git Bash path
+ * normalizePath('/c/Users/name') // Returns 'C:\\Users\\name'
+ *
+ * @example
+ * // On Unix, returns unchanged
+ * normalizePath('/home/user') // Returns '/home/user'
+ */
+export declare function normalizePath(inputPath: string): string;
+/**
+ * Check if a path is a Windows absolute path.
+ *
+ * @param inputPath - Path to check
+ * @returns True if the path is a Windows absolute path (e.g., C:\ or C:/)
+ *
+ * @example
+ * isWindowsAbsolute('C:\\Users') // Returns true
+ * isWindowsAbsolute('C:/Users')  // Returns true
+ * isWindowsAbsolute('/home/user') // Returns false
+ */
+export declare function isWindowsAbsolute(inputPath: string): boolean;
+/**
+ * Normalize path for comparison (lowercase drive letter on Windows, forward slashes on all platforms).
+ * Useful when comparing paths that may have different separator styles.
+ *
+ * Always converts backslashes to forward slashes regardless of platform,
+ * since paths from external sources (APIs, configs) may contain Windows-style
+ * separators even when running on Unix.
+ *
+ * @param inputPath - Path to normalize for comparison
+ * @returns Normalized path with forward slashes (and lowercase drive on Windows)
+ *
+ * @example
+ * // On Windows
+ * normalizeForComparison('C:\\Users\\Name') // Returns 'c:/Users/Name'
+ *
+ * @example
+ * // On Unix (also converts backslashes)
+ * normalizeForComparison('auth\\jwt\\context.md') // Returns 'auth/jwt/context.md'
+ */
+export declare function normalizeForComparison(inputPath: string): string;
+/**
+ * Check if a path appears to be a Git Bash or MSYS/Cygwin Unix-style path on Windows.
+ *
+ * @param inputPath - Path to check
+ * @returns True if the path looks like a Unix-style path that needs normalization on Windows
+ *
+ * @example
+ * isUnixStyleWindowsPath('/c/Users') // Returns true
+ * isUnixStyleWindowsPath('/cygdrive/c/Users') // Returns true
+ * isUnixStyleWindowsPath('/home/user') // Returns false (no drive letter pattern)
+ */
+export declare function isUnixStyleWindowsPath(inputPath: string): boolean;

package/dist/infra/cipher/process/path-utils.js

@@ -0,0 +1,94 @@
+/**
+ * Path utilities for cross-platform compatibility.
+ *
+ * Provides functions for normalizing paths across different environments,
+ * particularly handling Git Bash and MSYS/Cygwin Unix-style paths on Windows.
+ */
+/**
+ * Normalize paths for cross-platform compatibility.
+ * Handles Git Bash Unix-style paths on Windows (e.g., /c/Users/... -> C:\Users\...)
+ *
+ * @param inputPath - Path to normalize
+ * @returns Normalized path for the current platform
+ *
+ * @example
+ * // On Windows with Git Bash path
+ * normalizePath('/c/Users/name') // Returns 'C:\\Users\\name'
+ *
+ * @example
+ * // On Unix, returns unchanged
+ * normalizePath('/home/user') // Returns '/home/user'
+ */
+export function normalizePath(inputPath) {
+    if (process.platform !== 'win32') {
+        return inputPath;
+    }
+    // Git Bash on Windows returns Unix-style paths like /c/Users/...
+    if (/^\/[a-z]\//i.test(inputPath)) {
+        return inputPath
+            .replace(/^\/([a-z])\//i, (_, drive) => `${drive.toUpperCase()}:\\`)
+            .replaceAll('/', '\\');
+    }
+    // MSYS/Cygwin style: /cygdrive/c/...
+    if (/^\/cygdrive\/[a-z]\//i.test(inputPath)) {
+        return inputPath
+            .replace(/^\/cygdrive\/([a-z])\//i, (_, drive) => `${drive.toUpperCase()}:\\`)
+            .replaceAll('/', '\\');
+    }
+    return inputPath;
+}
+/**
+ * Check if a path is a Windows absolute path.
+ *
+ * @param inputPath - Path to check
+ * @returns True if the path is a Windows absolute path (e.g., C:\ or C:/)
+ *
+ * @example
+ * isWindowsAbsolute('C:\\Users') // Returns true
+ * isWindowsAbsolute('C:/Users')  // Returns true
+ * isWindowsAbsolute('/home/user') // Returns false
+ */
+export function isWindowsAbsolute(inputPath) {
+    return /^[a-z]:\\/i.test(inputPath) || /^[a-z]:\//i.test(inputPath);
+}
+/**
+ * Normalize path for comparison (lowercase drive letter on Windows, forward slashes on all platforms).
+ * Useful when comparing paths that may have different separator styles.
+ *
+ * Always converts backslashes to forward slashes regardless of platform,
+ * since paths from external sources (APIs, configs) may contain Windows-style
+ * separators even when running on Unix.
+ *
+ * @param inputPath - Path to normalize for comparison
+ * @returns Normalized path with forward slashes (and lowercase drive on Windows)
+ *
+ * @example
+ * // On Windows
+ * normalizeForComparison('C:\\Users\\Name') // Returns 'c:/Users/Name'
+ *
+ * @example
+ * // On Unix (also converts backslashes)
+ * normalizeForComparison('auth\\jwt\\context.md') // Returns 'auth/jwt/context.md'
+ */
+export function normalizeForComparison(inputPath) {
+    let result = inputPath.replaceAll('\\', '/');
+    // Lowercase drive letter on Windows only
+    if (process.platform === 'win32') {
+        result = result.replace(/^([A-Z]):/, (_, drive) => `${drive.toLowerCase()}:`);
+    }
+    return result;
+}
+/**
+ * Check if a path appears to be a Git Bash or MSYS/Cygwin Unix-style path on Windows.
+ *
+ * @param inputPath - Path to check
+ * @returns True if the path looks like a Unix-style path that needs normalization on Windows
+ *
+ * @example
+ * isUnixStyleWindowsPath('/c/Users') // Returns true
+ * isUnixStyleWindowsPath('/cygdrive/c/Users') // Returns true
+ * isUnixStyleWindowsPath('/home/user') // Returns false (no drive letter pattern)
+ */
+export function isUnixStyleWindowsPath(inputPath) {
+    return /^\/[a-z]\//i.test(inputPath) || /^\/cygdrive\/[a-z]\//i.test(inputPath);
+}

package/dist/infra/cipher/process/process-service.d.ts

@@ -52,6 +52,8 @@ export declare class ProcessService implements IProcessService {
     /**
      * Terminate a background process.
      *
+     * Uses process tree killing to ensure all child processes are terminated.
+     *
      * @param processId - Unique process identifier
      */
     killProcess(processId: string): Promise<void>;
@@ -82,6 +84,18 @@ export declare class ProcessService implements IProcessService {
      * @returns Process handle with processId
      */
     private executeInBackground;
+    /**
+     * Kill a process and all its children (process tree).
+     *
+     * On Unix, uses process groups (-pid) to kill all descendants.
+     * On Windows, uses taskkill with /t flag for tree kill.
+     * Falls back to direct kill if process group kill fails.
+     *
+     * @param child - Child process to kill
+     * @param pid - Process ID (optional, extracted from child if not provided)
+     * @returns Promise that resolves when kill attempt completes
+     */
+    private killProcessTree;
     /**
      * Resolve and validate working directory.
      *
@@ -92,4 +106,22 @@ export declare class ProcessService implements IProcessService {
      * @returns Safe absolute working directory
      */
     private resolveSafeCwd;
+    /**
+     * Sleep for specified milliseconds.
+     *
+     * @param ms - Milliseconds to sleep
+     * @returns Promise that resolves after the delay
+     */
+    private sleep;
+    /**
+     * Validate file path arguments in a command.
+     *
+     * Extracts path arguments from path-sensitive commands and validates
+     * that they are within the configured base directory.
+     *
+     * @param command - Command string to validate
+     * @param baseDir - Base directory for confinement
+     * @throws ProcessError if any path argument is outside the base directory
+     */
+    private validatePathArguments;
 }