attocode 0.1.0

package/dist/src/integrations/sandbox/seatbelt.js

@@ -0,0 +1,298 @@
+/**
+ * Seatbelt Sandbox (macOS)
+ *
+ * Uses macOS sandbox-exec with Seatbelt profiles to restrict command execution.
+ * Seatbelt is Apple's mandatory access control framework.
+ *
+ * Key features:
+ * - Fine-grained file system access control
+ * - Network access restrictions
+ * - Process spawning limits
+ * - Signal restrictions
+ *
+ * Note: This uses spawn() with explicit shell arguments for the sandboxed execution.
+ * The sandbox itself provides the security layer - we're wrapping shell execution
+ * with OS-level access controls.
+ *
+ * Reference: https://reverse.put.as/wp-content/uploads/2011/09/Apple-Sandbox-Guide-v1.0.pdf
+ */
+import { spawn, execSync } from 'child_process';
+// =============================================================================
+// SEATBELT PROFILE GENERATION
+// =============================================================================
+/**
+ * Generate a Seatbelt profile based on options.
+ */
+function generateSeatbeltProfile(options) {
+    const writablePaths = options.writablePaths ?? ['.'];
+    const readablePaths = options.readablePaths ?? ['/'];
+    const networkAllowed = options.networkAllowed ?? false;
+    const workingDir = options.workingDir ?? process.cwd();
+    // Start with version declaration and deny default
+    const rules = [
+        '(version 1)',
+        '(deny default)',
+    ];
+    // Allow process management
+    rules.push('(allow process-fork)');
+    rules.push('(allow process-exec)');
+    rules.push('(allow signal (target self))');
+    // Allow system basics
+    rules.push('(allow sysctl-read)');
+    rules.push('(allow mach-lookup)');
+    rules.push('(allow ipc-posix-shm)');
+    // Allow file reads for standard paths
+    const standardReadPaths = [
+        '/bin',
+        '/usr/bin',
+        '/usr/local/bin',
+        '/opt/homebrew/bin',
+        '/sbin',
+        '/usr/sbin',
+        '/lib',
+        '/usr/lib',
+        '/usr/local/lib',
+        '/opt/homebrew/lib',
+        '/System',
+        '/Library/Frameworks',
+        '/private/var/db',
+        '/dev/null',
+        '/dev/urandom',
+        '/dev/random',
+        '/dev/tty',
+        '/etc',
+        '/private/etc',
+        '/var/folders', // Temp files
+        '/private/var/folders',
+        '/tmp',
+        '/private/tmp',
+    ];
+    // Add read access for standard paths
+    for (const path of standardReadPaths) {
+        rules.push(`(allow file-read* (subpath "${path}"))`);
+    }
+    // Add user-specified readable paths
+    for (const path of readablePaths) {
+        const resolvedPath = resolvePath(path, workingDir);
+        rules.push(`(allow file-read* (subpath "${resolvedPath}"))`);
+    }
+    // Add write access for specified paths
+    for (const path of writablePaths) {
+        const resolvedPath = resolvePath(path, workingDir);
+        rules.push(`(allow file-read* (subpath "${resolvedPath}"))`);
+        rules.push(`(allow file-write* (subpath "${resolvedPath}"))`);
+    }
+    // Temp directory access
+    rules.push('(allow file-read* (subpath "/tmp"))');
+    rules.push('(allow file-write* (subpath "/tmp"))');
+    rules.push('(allow file-read* (subpath "/private/tmp"))');
+    rules.push('(allow file-write* (subpath "/private/tmp"))');
+    // Allow write to stderr/stdout
+    rules.push('(allow file-write* (literal "/dev/tty"))');
+    rules.push('(allow file-write* (literal "/dev/null"))');
+    // Network access
+    if (networkAllowed) {
+        rules.push('(allow network*)');
+    }
+    else {
+        // Still allow localhost for dev servers
+        rules.push('(allow network-inbound (local ip "*:*"))');
+        rules.push('(allow network-outbound (local ip "localhost:*"))');
+        rules.push('(allow network-outbound (local ip "127.0.0.1:*"))');
+        rules.push('(allow network-outbound (local ip "::1:*"))');
+    }
+    return rules.join('\n');
+}
+/**
+ * Resolve a path relative to working directory.
+ */
+function resolvePath(path, workingDir) {
+    if (path.startsWith('/')) {
+        return path;
+    }
+    if (path === '.') {
+        return workingDir;
+    }
+    return `${workingDir}/${path}`;
+}
+// =============================================================================
+// SEATBELT SANDBOX
+// =============================================================================
+/**
+ * macOS Seatbelt sandbox implementation.
+ */
+export class SeatbeltSandbox {
+    options;
+    available = null;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Execute a command inside the Seatbelt sandbox.
+     *
+     * Note: We use spawn with 'bash -c' because the sandbox-exec command
+     * itself provides the security boundary. The command string is passed
+     * to the sandboxed shell, which has restricted access via Seatbelt.
+     */
+    async execute(command, options) {
+        const mergedOptions = { ...this.options, ...options };
+        const profile = generateSeatbeltProfile(mergedOptions);
+        const timeout = mergedOptions.timeout ?? 60000;
+        const workDir = mergedOptions.workingDir ?? process.cwd();
+        return new Promise((resolve) => {
+            // sandbox-exec -p 'profile' bash -c 'command'
+            // The sandbox profile restricts what the shell can do
+            const proc = spawn('sandbox-exec', ['-p', profile, 'bash', '-c', command], {
+                cwd: workDir,
+                env: {
+                    ...process.env,
+                    ...mergedOptions.env,
+                    // Add common paths to PATH
+                    PATH: [
+                        process.env.PATH,
+                        '/usr/local/bin',
+                        '/opt/homebrew/bin',
+                        '/usr/bin',
+                        '/bin',
+                    ].filter(Boolean).join(':'),
+                },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            let killed = false;
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                killed = true;
+                proc.kill('SIGKILL');
+            }, timeout);
+            proc.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('close', (code) => {
+                clearTimeout(timer);
+                // Check if the sandbox blocked something
+                const sandboxError = this.parseSandboxError(stderr);
+                resolve({
+                    stdout,
+                    stderr,
+                    exitCode: code ?? 1,
+                    killed,
+                    timedOut,
+                    error: sandboxError,
+                });
+            });
+            proc.on('error', (err) => {
+                clearTimeout(timer);
+                resolve({
+                    stdout,
+                    stderr,
+                    exitCode: 1,
+                    killed: false,
+                    timedOut: false,
+                    error: err.message,
+                });
+            });
+        });
+    }
+    /**
+     * Check if Seatbelt is available on this system.
+     */
+    async isAvailable() {
+        if (this.available !== null) {
+            return this.available;
+        }
+        // Must be macOS
+        if (process.platform !== 'darwin') {
+            this.available = false;
+            return false;
+        }
+        // Check if sandbox-exec exists
+        try {
+            execSync('which sandbox-exec', { stdio: 'pipe' });
+            this.available = true;
+            return true;
+        }
+        catch {
+            this.available = false;
+            return false;
+        }
+    }
+    /**
+     * Get sandbox type.
+     */
+    getType() {
+        return 'seatbelt';
+    }
+    /**
+     * Cleanup resources.
+     */
+    async cleanup() {
+        // No persistent resources to clean up
+    }
+    /**
+     * Parse sandbox error from stderr.
+     */
+    parseSandboxError(stderr) {
+        // Look for sandbox denial messages
+        if (stderr.includes('sandbox-exec:') || stderr.includes('deny')) {
+            const match = stderr.match(/sandbox-exec: (.+)/);
+            if (match) {
+                return `Sandbox denied: ${match[1]}`;
+            }
+        }
+        return undefined;
+    }
+}
+// =============================================================================
+// PREDEFINED PROFILES
+// =============================================================================
+/**
+ * Strict profile - minimal access for pure computation.
+ */
+export const STRICT_PROFILE = {
+    writablePaths: [],
+    readablePaths: ['/usr/lib', '/System'],
+    networkAllowed: false,
+    timeout: 30000,
+    maxMemoryMB: 256,
+    maxCpuSeconds: 10,
+};
+/**
+ * Development profile - allows npm, node, git operations.
+ */
+export const DEV_PROFILE = {
+    writablePaths: ['.', 'node_modules', '.git'],
+    readablePaths: ['/'],
+    networkAllowed: true, // Allow npm install
+    timeout: 300000, // 5 minutes
+    maxMemoryMB: 1024,
+    maxCpuSeconds: 120,
+};
+/**
+ * Build profile - allows compilation but no network.
+ */
+export const BUILD_PROFILE = {
+    writablePaths: ['.', 'dist', 'build', 'node_modules/.cache'],
+    readablePaths: ['/'],
+    networkAllowed: false,
+    timeout: 300000,
+    maxMemoryMB: 2048,
+    maxCpuSeconds: 300,
+};
+/**
+ * Test profile - allows test execution with limited write access.
+ */
+export const TEST_PROFILE = {
+    writablePaths: ['.', 'coverage', 'test-results', 'node_modules/.cache'],
+    readablePaths: ['/'],
+    networkAllowed: false, // Tests should be isolated
+    timeout: 600000, // 10 minutes
+    maxMemoryMB: 1024,
+    maxCpuSeconds: 300,
+};
+//# sourceMappingURL=seatbelt.js.map

package/dist/src/integrations/sandbox/seatbelt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seatbelt.js","sourceRoot":"","sources":["../../../../src/integrations/sandbox/seatbelt.ts"],"names":[],"mappings":"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"}

package/dist/src/integrations/semantic-cache.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Semantic Cache Integration
+ *
+ * Caches LLM responses based on semantic similarity of queries.
+ * Returns cached response if a query is similar enough to a previous one.
+ * Adapted from tricks/semantic-cache.ts.
+ *
+ * Usage:
+ *   const cache = createSemanticCacheManager({ threshold: 0.95 });
+ *   const hit = await cache.get("What is X?");
+ *   if (hit) return hit.response;
+ *   // else call LLM and cache result
+ *   await cache.set("What is X?", response);
+ */
+/**
+ * Cache entry.
+ */
+export interface CacheEntry {
+    id: string;
+    query: string;
+    response: string;
+    embedding?: number[];
+    createdAt: Date;
+    expiresAt?: Date;
+    hitCount: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Cache hit result.
+ */
+export interface CacheHit {
+    entry: CacheEntry;
+    similarity: number;
+}
+/**
+ * Embedding function type.
+ */
+export type EmbeddingFunction = (text: string) => Promise<number[]>;
+/**
+ * Semantic cache configuration.
+ */
+export interface SemanticCacheConfig {
+    /** Enable/disable semantic caching */
+    enabled?: boolean;
+    /** Similarity threshold (0-1, default 0.95) - higher = more strict */
+    threshold?: number;
+    /** Maximum cache size (entries) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (0 = no expiry) */
+    ttl?: number;
+    /** Custom embedding function (uses simple hash-based by default) */
+    embedFunction?: EmbeddingFunction;
+}
+/**
+ * Cache statistics.
+ */
+export interface CacheStats {
+    size: number;
+    totalHits: number;
+    avgHits: number;
+    hitRate: number;
+    totalQueries: number;
+}
+/**
+ * Cache event types.
+ */
+export type CacheEvent = {
+    type: 'cache.hit';
+    query: string;
+    similarity: number;
+    entryId: string;
+} | {
+    type: 'cache.miss';
+    query: string;
+} | {
+    type: 'cache.set';
+    query: string;
+    entryId: string;
+} | {
+    type: 'cache.evict';
+    entryId: string;
+    reason: 'size' | 'ttl';
+} | {
+    type: 'cache.cleared';
+};
+export type CacheEventListener = (event: CacheEvent) => void;
+/**
+ * Cosine similarity between two vectors.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Manages semantic caching of LLM responses.
+ */
+export declare class SemanticCacheManager {
+    private entries;
+    private config;
+    private eventListeners;
+    private totalQueries;
+    private totalHits;
+    constructor(config?: SemanticCacheConfig);
+    /**
+     * Get cached response for a query.
+     */
+    get(query: string, threshold?: number): Promise<CacheHit | null>;
+    /**
+     * Store a query/response pair.
+     */
+    set(query: string, response: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Check if a similar query exists (without incrementing hit count).
+     */
+    has(query: string, threshold?: number): Promise<boolean>;
+    /**
+     * Delete an entry by ID.
+     */
+    delete(id: string): boolean;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): CacheStats;
+    /**
+     * Find similar entries (for debugging/inspection).
+     */
+    findSimilar(query: string, limit?: number): Promise<CacheHit[]>;
+    /**
+     * Get all entries (for debugging).
+     */
+    getAllEntries(): CacheEntry[];
+    /**
+     * Update configuration.
+     */
+    setConfig(updates: Partial<SemanticCacheConfig>): void;
+    /**
+     * Get current configuration.
+     */
+    getConfig(): Omit<SemanticCacheConfig, 'embedFunction'>;
+    /**
+     * Subscribe to cache events.
+     */
+    subscribe(listener: CacheEventListener): () => void;
+    /**
+     * Cleanup resources.
+     */
+    cleanup(): void;
+    /**
+     * Clean expired entries.
+     */
+    private cleanExpired;
+    /**
+     * Evict least recently used entry.
+     */
+    private evictLRU;
+    /**
+     * Emit a cache event.
+     */
+    private emit;
+}
+/**
+ * Create a semantic cache manager.
+ */
+export declare function createSemanticCacheManager(config?: SemanticCacheConfig): SemanticCacheManager;
+/**
+ * Create a strict cache (higher similarity threshold).
+ */
+export declare function createStrictCache(): SemanticCacheManager;
+/**
+ * Create a lenient cache (lower similarity threshold).
+ */
+export declare function createLenientCache(): SemanticCacheManager;
+/**
+ * Create a cached wrapper around an LLM call function.
+ */
+export declare function withSemanticCache<T extends (...args: string[]) => Promise<string>>(fn: T, cache: SemanticCacheManager): T;
+//# sourceMappingURL=semantic-cache.d.ts.map

package/dist/src/integrations/semantic-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-cache.d.ts","sourceRoot":"","sources":["../../../src/integrations/semantic-cache.ts"],"names":[],"mappings":"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"}