@syrin/cli 1.3.0

package/dist/runtime/sandbox/io-monitor.js

@@ -0,0 +1,98 @@
+/**
+ * I/O monitor for sandboxed tool execution.
+ * Monitors filesystem and network operations (does not block).
+ */
+import * as path from 'path';
+/**
+ * I/O monitor for tracking operations during tool execution.
+ */
+export class IOMonitor {
+    fsOperations = [];
+    networkOperations = [];
+    tempDir;
+    projectRoot;
+    constructor(tempDir, projectRoot) {
+        this.tempDir = path.resolve(tempDir);
+        this.projectRoot = path.resolve(projectRoot);
+    }
+    /**
+     * Record a filesystem operation.
+     */
+    recordFSOperation(operation, filePath) {
+        const resolvedPath = path.resolve(filePath);
+        this.fsOperations.push({
+            operation,
+            path: resolvedPath,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Record a network operation.
+     */
+    recordNetworkOperation(url, method) {
+        this.networkOperations.push({
+            url,
+            method,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Get all filesystem operations.
+     */
+    getFSOperations() {
+        return this.fsOperations;
+    }
+    /**
+     * Get all network operations.
+     */
+    getNetworkOperations() {
+        return this.networkOperations;
+    }
+    /**
+     * Get filesystem operations that are side effects (writes to project files).
+     * Writes to temp directory are NOT considered side effects.
+     */
+    getSideEffects() {
+        return this.fsOperations.filter(op => {
+            // Only writes and deletes to project files are side effects
+            if (op.operation !== 'write' && op.operation !== 'delete') {
+                return false;
+            }
+            const resolvedPath = path.resolve(op.path);
+            // Check if path is within temp directory (tempDir is already resolved in constructor)
+            if (resolvedPath.startsWith(this.tempDir)) {
+                return false; // Not a side effect (within temp dir)
+            }
+            // Check if path is within project root (projectRoot is already resolved in constructor)
+            if (resolvedPath.startsWith(this.projectRoot)) {
+                return true; // Side effect (write/delete to project file)
+            }
+            // Writes outside project root are also side effects
+            return true;
+        });
+    }
+    /**
+     * Get filesystem operations filtered by operation type.
+     */
+    getFSOperationsByType(operation) {
+        return this.fsOperations.filter(op => op.operation === operation);
+    }
+    /**
+     * Clear all recorded operations.
+     */
+    clear() {
+        this.fsOperations = [];
+        this.networkOperations = [];
+    }
+    /**
+     * Get summary of I/O operations.
+     */
+    getSummary() {
+        return {
+            totalFSOperations: this.fsOperations.length,
+            sideEffects: this.getSideEffects().length,
+            networkOperations: this.networkOperations.length,
+        };
+    }
+}
+//# sourceMappingURL=io-monitor.js.map

package/dist/runtime/sandbox/time-parser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility functions for parsing time strings.
+ * Supports formats like "30s", "5m", "2h", "1d"
+ */
+/**
+ * Parse a time string to milliseconds.
+ * @param timeString - Time string in format: <number><unit> (e.g., "30s", "5m", "2h", "1d")
+ * @returns Time in milliseconds, or undefined if invalid
+ * @throws {Error} If format is invalid
+ */
+export declare function parseTimeString(timeString: string): number;
+/**
+ * Format milliseconds to human-readable time string.
+ * @param milliseconds - Time in milliseconds
+ * @returns Human-readable time string (e.g., "5m", "2h")
+ * @throws {RangeError} If milliseconds is negative
+ */
+export declare function formatTimeString(milliseconds: number): string;
+//# sourceMappingURL=time-parser.d.ts.map

package/dist/runtime/sandbox/time-parser.js

@@ -0,0 +1,67 @@
+/**
+ * Utility functions for parsing time strings.
+ * Supports formats like "30s", "5m", "2h", "1d"
+ */
+/**
+ * Parse a time string to milliseconds.
+ * @param timeString - Time string in format: <number><unit> (e.g., "30s", "5m", "2h", "1d")
+ * @returns Time in milliseconds, or undefined if invalid
+ * @throws {Error} If format is invalid
+ */
+export function parseTimeString(timeString) {
+    const match = timeString.match(/^(\d+)([smhd])$/i);
+    if (!match) {
+        throw new Error(`Invalid time format: "${timeString}". Expected format: <number><unit> (e.g., "30s", "5m", "2h")`);
+    }
+    const value = parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    if (value <= 0) {
+        throw new Error(`Time value must be positive: ${value}`);
+    }
+    const multipliers = {
+        s: 1000, // seconds to milliseconds
+        m: 60 * 1000, // minutes to milliseconds
+        h: 60 * 60 * 1000, // hours to milliseconds
+        d: 24 * 60 * 60 * 1000, // days to milliseconds
+    };
+    const multiplier = multipliers[unit];
+    if (!multiplier) {
+        throw new Error(`Unknown time unit: "${unit}". Supported units: s, m, h, d`);
+    }
+    const milliseconds = value * multiplier;
+    // Check for overflow: ensure the result doesn't exceed Number.MAX_SAFE_INTEGER
+    // Also check for Infinity (which can occur when multiplying very large numbers)
+    if (!isFinite(milliseconds) || milliseconds > Number.MAX_SAFE_INTEGER) {
+        throw new Error(`Time value "${timeString}" exceeds maximum safe integer (${Number.MAX_SAFE_INTEGER}ms). Use a smaller value.`);
+    }
+    return milliseconds;
+}
+/**
+ * Format milliseconds to human-readable time string.
+ * @param milliseconds - Time in milliseconds
+ * @returns Human-readable time string (e.g., "5m", "2h")
+ * @throws {RangeError} If milliseconds is negative
+ */
+export function formatTimeString(milliseconds) {
+    if (milliseconds < 0) {
+        throw new RangeError(`Cannot format negative milliseconds: ${milliseconds}. Time must be non-negative.`);
+    }
+    if (milliseconds < 1000) {
+        return `${milliseconds}ms`;
+    }
+    const seconds = Math.floor(milliseconds / 1000);
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) {
+        return `${minutes}m`;
+    }
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) {
+        return `${hours}h`;
+    }
+    const days = Math.floor(hours / 24);
+    return `${days}d`;
+}
+//# sourceMappingURL=time-parser.js.map

package/dist/runtime/sandbox/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Sandbox types and interfaces.
+ * Shared types for sandbox execution functionality.
+ */
+/**
+ * Error types for tool execution.
+ */
+export declare enum ToolExecutionErrorType {
+    /** Input validation error (e.g., wrong type, missing required field) */
+    INPUT_VALIDATION = "INPUT_VALIDATION",
+    /** Output validation error (output doesn't match schema) */
+    OUTPUT_VALIDATION = "OUTPUT_VALIDATION",
+    /** Tool execution error (runtime error in tool) */
+    EXECUTION_ERROR = "EXECUTION_ERROR",
+    /** Timeout error */
+    TIMEOUT = "TIMEOUT",
+    /** Network/connection error */
+    CONNECTION_ERROR = "CONNECTION_ERROR",
+    /** Unknown error */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Enhanced error with classification.
+ */
+export interface ToolExecutionError extends Error {
+    /** Error type classification */
+    errorType: ToolExecutionErrorType;
+    /** Original error code from MCP (if available) */
+    errorCode?: number;
+    /** Additional error context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Result of a single tool execution.
+ * Discriminated union: successful executions have output, failed executions have error.
+ */
+export type ToolExecutionResult = {
+    /** Discriminator: true for successful executions */
+    success: true;
+    /** Tool output */
+    output: unknown;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Memory used in MB (if available) */
+    memoryUsed?: number;
+} | {
+    /** Discriminator: false for failed executions */
+    success: false;
+    /** Error that occurred during execution */
+    error: ToolExecutionError;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Memory used in MB (if available) */
+    memoryUsed?: number;
+    /** Whether execution timed out */
+    timedOut?: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/sandbox/types.js

@@ -0,0 +1,23 @@
+/**
+ * Sandbox types and interfaces.
+ * Shared types for sandbox execution functionality.
+ */
+/**
+ * Error types for tool execution.
+ */
+export var ToolExecutionErrorType;
+(function (ToolExecutionErrorType) {
+    /** Input validation error (e.g., wrong type, missing required field) */
+    ToolExecutionErrorType["INPUT_VALIDATION"] = "INPUT_VALIDATION";
+    /** Output validation error (output doesn't match schema) */
+    ToolExecutionErrorType["OUTPUT_VALIDATION"] = "OUTPUT_VALIDATION";
+    /** Tool execution error (runtime error in tool) */
+    ToolExecutionErrorType["EXECUTION_ERROR"] = "EXECUTION_ERROR";
+    /** Timeout error */
+    ToolExecutionErrorType["TIMEOUT"] = "TIMEOUT";
+    /** Network/connection error */
+    ToolExecutionErrorType["CONNECTION_ERROR"] = "CONNECTION_ERROR";
+    /** Unknown error */
+    ToolExecutionErrorType["UNKNOWN"] = "UNKNOWN";
+})(ToolExecutionErrorType || (ToolExecutionErrorType = {}));
+//# sourceMappingURL=types.js.map

package/dist/runtime/test/behavior-observer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Behavioral observer for tool execution.
+ * Observes and detects unsafe tool behaviors.
+ */
+import type { IOMonitor, FSOperationRecord } from '../../runtime/sandbox/index.js';
+import type { ToolExecutionResult } from '../../runtime/sandbox/index.js';
+import type { ToolContract } from './contract-types.js';
+/**
+ * Side effect detection result.
+ */
+export interface SideEffectResult {
+    /** Whether side effects violate the contract (detected when contract requires none) */
+    detected: boolean;
+    /** List of observed side effect operations */
+    sideEffects: FSOperationRecord[];
+    /** Whether any side effects were observed (regardless of contract) */
+    observed: boolean;
+}
+/**
+ * Output size validation result.
+ */
+export interface OutputSizeResult {
+    /** Whether output size exceeds limit */
+    exceedsLimit: boolean;
+    /** Actual output size in bytes */
+    actualSize: number;
+    /** Maximum allowed size in bytes */
+    maxSize: number;
+    /** Size limit from contract (e.g., "50kb") */
+    limitString: string;
+}
+/**
+ * Behavioral observer for tool execution.
+ */
+export declare class BehaviorObserver {
+    /**
+     * Detect side effects from I/O monitor.
+     */
+    detectSideEffects(ioMonitor: IOMonitor, contract: ToolContract): SideEffectResult;
+    /**
+     * Check output size against contract limits.
+     */
+    checkOutputSize(results: ToolExecutionResult[], contract: ToolContract, defaultMaxSizeKB?: number): OutputSizeResult[];
+    /**
+     * Detect if tool execution timed out or failed.
+     * E016 should only trigger for timeouts and connection errors, NOT execution errors (E019).
+     */
+    detectUnboundedExecution(results: ToolExecutionResult[]): {
+        detected: boolean;
+        timedOut: boolean;
+        errors: Error[];
+    };
+    /**
+     * Detect execution errors (E019) - separate from unbounded execution (E016).
+     */
+    detectExecutionErrors(results: ToolExecutionResult[]): {
+        detected: boolean;
+        errors: Error[];
+    };
+}
+//# sourceMappingURL=behavior-observer.d.ts.map

package/dist/runtime/test/behavior-observer.js

@@ -0,0 +1,140 @@
+/**
+ * Behavioral observer for tool execution.
+ * Observes and detects unsafe tool behaviors.
+ */
+import { ToolExecutionErrorType } from '../../runtime/sandbox/index.js';
+/**
+ * Parse size string (e.g., "50kb", "1mb") to bytes.
+ */
+function parseSize(sizeStr) {
+    const match = sizeStr.match(/^(\d+)(kb|mb|gb|b)?$/i);
+    if (!match) {
+        throw new Error(`Invalid size format: ${sizeStr}`);
+    }
+    const value = parseInt(match[1], 10);
+    const unit = (match[2] || 'b').toLowerCase();
+    switch (unit) {
+        case 'kb':
+            return value * 1024;
+        case 'mb':
+            return value * 1024 * 1024;
+        case 'gb':
+            return value * 1024 * 1024 * 1024;
+        case 'b':
+        default:
+            return value;
+    }
+}
+/**
+ * Calculate size of a value in bytes (JSON stringified).
+ */
+function calculateSize(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), 'utf8');
+    }
+    catch {
+        // If value can't be stringified, estimate
+        return String(value).length;
+    }
+}
+/**
+ * Behavioral observer for tool execution.
+ */
+export class BehaviorObserver {
+    /**
+     * Detect side effects from I/O monitor.
+     */
+    detectSideEffects(ioMonitor, contract) {
+        const sideEffects = ioMonitor.getSideEffects();
+        const observed = sideEffects.length > 0;
+        // Check if side effects violate contract
+        const guarantees = contract.guarantees;
+        const requiresNoSideEffects = guarantees?.side_effects === 'none';
+        const violatesContract = observed && requiresNoSideEffects;
+        return {
+            detected: violatesContract,
+            sideEffects,
+            observed,
+        };
+    }
+    /**
+     * Check output size against contract limits.
+     */
+    checkOutputSize(results, contract, defaultMaxSizeKB = 50) {
+        const guarantees = contract.guarantees;
+        const maxSizeStr = guarantees?.max_output_size;
+        // Determine max size
+        let maxSizeBytes;
+        if (maxSizeStr) {
+            maxSizeBytes = parseSize(maxSizeStr);
+        }
+        else {
+            maxSizeBytes = defaultMaxSizeKB * 1024;
+        }
+        // Check each result
+        return results.map(result => {
+            if (!result.success) {
+                // Failed executions don't have output, so they can't exceed size limit
+                return {
+                    exceedsLimit: false,
+                    actualSize: 0,
+                    maxSize: maxSizeBytes,
+                    limitString: maxSizeStr || `${defaultMaxSizeKB}kb`,
+                };
+            }
+            const actualSize = calculateSize(result.output);
+            return {
+                exceedsLimit: actualSize > maxSizeBytes,
+                actualSize,
+                maxSize: maxSizeBytes,
+                limitString: maxSizeStr || `${defaultMaxSizeKB}kb`,
+            };
+        });
+    }
+    /**
+     * Detect if tool execution timed out or failed.
+     * E016 should only trigger for timeouts and connection errors, NOT execution errors (E019).
+     */
+    detectUnboundedExecution(results) {
+        const failedResults = results.filter((r) => !r.success);
+        const timedOut = failedResults.some(r => r.timedOut === true);
+        // Filter out input validation errors (E018) and execution errors (E019)
+        // E016 should only detect timeouts and connection errors (unbounded execution)
+        const errors = failedResults
+            .filter(r => {
+            const errorType = r.error.errorType;
+            // Exclude input validation errors (handled by E018)
+            // Exclude execution errors (handled by E019)
+            // Only include timeouts and connection errors for E016
+            return (errorType !== ToolExecutionErrorType.INPUT_VALIDATION &&
+                errorType !== ToolExecutionErrorType.EXECUTION_ERROR &&
+                (r.timedOut === true ||
+                    errorType === ToolExecutionErrorType.CONNECTION_ERROR ||
+                    errorType === ToolExecutionErrorType.TIMEOUT));
+        })
+            .map(r => r.error);
+        return {
+            detected: timedOut || errors.length > 0,
+            timedOut,
+            errors,
+        };
+    }
+    /**
+     * Detect execution errors (E019) - separate from unbounded execution (E016).
+     */
+    detectExecutionErrors(results) {
+        const failedResults = results.filter((r) => !r.success);
+        const errors = failedResults
+            .filter(r => {
+            const errorType = r.error.errorType;
+            // Only include execution errors (not input validation, not timeouts)
+            return errorType === ToolExecutionErrorType.EXECUTION_ERROR;
+        })
+            .map(r => r.error);
+        return {
+            detected: errors.length > 0,
+            errors,
+        };
+    }
+}
+//# sourceMappingURL=behavior-observer.js.map

package/dist/runtime/test/contract-loader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Contract file loader.
+ * Loads and parses tool contract YAML files.
+ */
+import type { ParsedContract } from './contract-types.js';
+/**
+ * Load a contract from a YAML file.
+ * @param filePath - Path to the contract YAML file
+ * @returns Parsed contract with metadata
+ * @throws {ConfigurationError} If file is missing or invalid
+ */
+export declare function loadContract(filePath: string): ParsedContract;
+/**
+ * Discover all contract files in a directory (recursively).
+ * @param toolsDir - Directory containing contract files
+ * @returns Array of contract file paths
+ * @throws {ConfigurationError} If directory doesn't exist
+ */
+export declare function discoverContractFiles(toolsDir: string): string[];
+/**
+ * Load all contracts from a tools directory.
+ * @param toolsDir - Directory containing contract files
+ * @returns Array of parsed contracts
+ * @throws {ConfigurationError} If directory doesn't exist or contracts are invalid
+ */
+export declare function loadAllContracts(toolsDir: string): ParsedContract[];
+/**
+ * Match tool name to contract file.
+ * Extracts tool name from filename regardless of directory depth.
+ * @param filePath - Path to contract file
+ * @returns Tool name extracted from filename
+ */
+export declare function extractToolNameFromPath(filePath: string): string;
+/**
+ * Find contract for a specific tool name.
+ * @param contracts - Array of parsed contracts
+ * @param toolName - Tool name to find
+ * @returns Contract for the tool, or undefined if not found
+ */
+export declare function findContractForTool(contracts: ParsedContract[], toolName: string): ParsedContract | undefined;
+//# sourceMappingURL=contract-loader.d.ts.map

package/dist/runtime/test/contract-loader.js

@@ -0,0 +1,158 @@
+/**
+ * Contract file loader.
+ * Loads and parses tool contract YAML files.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { load } from 'js-yaml';
+import { ZodError } from 'zod';
+import { validateContract } from './contract-schema.js';
+import { ConfigurationError } from '../../utils/errors.js';
+/**
+ * Load a contract from a YAML file.
+ * @param filePath - Path to the contract YAML file
+ * @returns Parsed contract with metadata
+ * @throws {ConfigurationError} If file is missing or invalid
+ */
+export function loadContract(filePath) {
+    try {
+        // Read and parse YAML file (removes TOCTOU risk by combining read + parse in try-catch)
+        const fileContent = fs.readFileSync(filePath, 'utf-8');
+        const contractData = load(fileContent);
+        if (!contractData || typeof contractData !== 'object') {
+            throw new ConfigurationError(`Contract file is empty or invalid: ${filePath}`, {
+                context: { filePath },
+            });
+        }
+        // Validate contract schema
+        const validatedContract = validateContract(contractData);
+        // Extract metadata
+        const directory = path.dirname(filePath);
+        const toolName = validatedContract.tool;
+        return {
+            ...validatedContract,
+            filePath,
+            directory,
+            toolName,
+        };
+    }
+    catch (error) {
+        if (error instanceof ConfigurationError) {
+            throw error;
+        }
+        // Handle file system errors (file not found, permission denied, etc.)
+        if (error && typeof error === 'object' && 'code' in error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                throw new ConfigurationError(`Contract file not found: ${filePath}`, {
+                    context: { filePath },
+                    cause: error instanceof Error ? error : undefined,
+                });
+            }
+        }
+        // Handle Zod validation errors
+        if (error instanceof ZodError) {
+            throw new ConfigurationError(`Invalid contract schema in ${filePath}: ${error.message}`, {
+                cause: error,
+                context: { filePath },
+            });
+        }
+        throw new ConfigurationError(`Failed to load contract from ${filePath}: ${error instanceof Error ? error.message : String(error)}`, {
+            cause: error instanceof Error ? error : new Error(String(error)),
+            context: { filePath },
+        });
+    }
+}
+/**
+ * Discover all contract files in a directory (recursively).
+ * @param toolsDir - Directory containing contract files
+ * @returns Array of contract file paths
+ * @throws {ConfigurationError} If directory doesn't exist
+ */
+export function discoverContractFiles(toolsDir) {
+    // Check if directory exists
+    if (!fs.existsSync(toolsDir)) {
+        throw new ConfigurationError(`Tools directory not found: ${toolsDir}. Create it and add tool contract files (tools/<tool-name>.yaml)`, {
+            context: { toolsDir },
+        });
+    }
+    if (!fs.statSync(toolsDir).isDirectory()) {
+        throw new ConfigurationError(`Path is not a directory: ${toolsDir}`, {
+            context: { toolsDir },
+        });
+    }
+    const contractFiles = [];
+    /**
+     * Recursively find all .yaml files in directory.
+     */
+    function findYamlFiles(dir) {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // Recursively search subdirectories
+                findYamlFiles(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.yaml')) {
+                contractFiles.push(fullPath);
+            }
+        }
+    }
+    findYamlFiles(toolsDir);
+    return contractFiles.sort(); // Sort for consistent ordering
+}
+/**
+ * Load all contracts from a tools directory.
+ * @param toolsDir - Directory containing contract files
+ * @returns Array of parsed contracts
+ * @throws {ConfigurationError} If directory doesn't exist or contracts are invalid
+ */
+export function loadAllContracts(toolsDir) {
+    const contractFiles = discoverContractFiles(toolsDir);
+    if (contractFiles.length === 0) {
+        throw new ConfigurationError(`No contract files found in ${toolsDir}. Add tool contract files (tools/<tool-name>.yaml)`, {
+            context: { toolsDir },
+        });
+    }
+    const contracts = [];
+    const errors = [];
+    for (const filePath of contractFiles) {
+        try {
+            const contract = loadContract(filePath);
+            contracts.push(contract);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            errors.push({ file: filePath, error: errorMessage });
+        }
+    }
+    if (errors.length > 0) {
+        const errorMessages = errors
+            .map(e => `  - ${e.file}: ${e.error}`)
+            .join('\n');
+        throw new ConfigurationError(`Failed to load ${errors.length} contract file(s):\n${errorMessages}`, {
+            context: { toolsDir, errors },
+        });
+    }
+    return contracts;
+}
+/**
+ * Match tool name to contract file.
+ * Extracts tool name from filename regardless of directory depth.
+ * @param filePath - Path to contract file
+ * @returns Tool name extracted from filename
+ */
+export function extractToolNameFromPath(filePath) {
+    const filename = path.basename(filePath, '.yaml');
+    return filename;
+}
+/**
+ * Find contract for a specific tool name.
+ * @param contracts - Array of parsed contracts
+ * @param toolName - Tool name to find
+ * @returns Contract for the tool, or undefined if not found
+ */
+export function findContractForTool(contracts, toolName) {
+    return contracts.find(contract => contract.tool === toolName);
+}
+//# sourceMappingURL=contract-loader.js.map