attocode 0.2.3 → 0.2.5

package/dist/src/integrations/quality/auto-checkpoint.js

@@ -0,0 +1,252 @@
+/**
+ * Auto-Checkpoint Resumption
+ *
+ * Saves lightweight checkpoints at key execution points so that
+ * work can be recovered if the agent crashes or times out.
+ *
+ * Key points where checkpoints are saved:
+ * - After each tool batch execution
+ * - Before LLM calls (so the prompt is recoverable)
+ * - After significant state changes (plan approval, mode switch)
+ *
+ * On startup, detects recent sessions (<5 min) and offers auto-resume.
+ */
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const DEFAULT_CONFIG = {
+    checkpointDir: '.agent/checkpoints',
+    maxCheckpointsPerSession: 10,
+    maxAge: 3600000, // 1 hour
+    enabled: true,
+    minInterval: 30000, // 30 seconds
+};
+// =============================================================================
+// AUTO-CHECKPOINT MANAGER
+// =============================================================================
+export class AutoCheckpointManager {
+    config;
+    lastCheckpointTime = 0;
+    checkpointCount = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        if (this.config.enabled) {
+            try {
+                mkdirSync(this.config.checkpointDir, { recursive: true });
+            }
+            catch {
+                // Directory creation may fail
+            }
+        }
+    }
+    /**
+     * Save a checkpoint at a key execution point.
+     * Respects minInterval to avoid excessive I/O.
+     */
+    save(checkpoint) {
+        if (!this.config.enabled)
+            return null;
+        const now = Date.now();
+        if (now - this.lastCheckpointTime < this.config.minInterval) {
+            return null; // Too soon since last checkpoint
+        }
+        const id = `ckpt-${now}-${Math.random().toString(36).slice(2, 6)}`;
+        const fullCheckpoint = {
+            ...checkpoint,
+            id,
+            timestamp: now,
+        };
+        try {
+            const sessionDir = join(this.config.checkpointDir, checkpoint.sessionId);
+            mkdirSync(sessionDir, { recursive: true });
+            const filePath = join(sessionDir, `${id}.json`);
+            // Don't persist full messages array to save space - just metadata
+            const persistable = {
+                ...fullCheckpoint,
+                messages: undefined, // Strip messages to keep checkpoints small
+                _messageCount: fullCheckpoint.messages?.length ?? 0,
+            };
+            writeFileSync(filePath, JSON.stringify(persistable, null, 2), 'utf-8');
+            this.lastCheckpointTime = now;
+            this.checkpointCount++;
+            // Cleanup old checkpoints for this session
+            this.cleanupSession(checkpoint.sessionId);
+            return id;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Load a specific checkpoint.
+     */
+    load(sessionId, checkpointId) {
+        try {
+            const filePath = join(this.config.checkpointDir, sessionId, `${checkpointId}.json`);
+            const content = readFileSync(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Find sessions with recent checkpoints that could be resumed.
+     */
+    findResumeCandidates(maxAgeMs) {
+        const maxAge = maxAgeMs ?? 300000; // Default: 5 minutes
+        const now = Date.now();
+        const candidates = [];
+        try {
+            if (!existsSync(this.config.checkpointDir))
+                return [];
+            const sessions = readdirSync(this.config.checkpointDir);
+            for (const sessionId of sessions) {
+                const sessionDir = join(this.config.checkpointDir, sessionId);
+                try {
+                    const stat = statSync(sessionDir);
+                    if (!stat.isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const checkpoints = this.loadSessionCheckpoints(sessionId);
+                if (checkpoints.length === 0)
+                    continue;
+                // Most recent checkpoint
+                const latest = checkpoints[checkpoints.length - 1];
+                const age = now - latest.timestamp;
+                if (age <= maxAge) {
+                    candidates.push({
+                        sessionId,
+                        checkpoint: latest,
+                        ageMs: age,
+                        checkpointCount: checkpoints.length,
+                    });
+                }
+            }
+        }
+        catch {
+            // Directory reading may fail
+        }
+        // Sort by recency (most recent first)
+        return candidates.sort((a, b) => a.ageMs - b.ageMs);
+    }
+    /**
+     * Load all checkpoints for a session, sorted by timestamp.
+     */
+    loadSessionCheckpoints(sessionId) {
+        const sessionDir = join(this.config.checkpointDir, sessionId);
+        const checkpoints = [];
+        try {
+            if (!existsSync(sessionDir))
+                return [];
+            const files = readdirSync(sessionDir).filter(f => f.endsWith('.json'));
+            for (const file of files) {
+                try {
+                    const content = readFileSync(join(sessionDir, file), 'utf-8');
+                    checkpoints.push(JSON.parse(content));
+                }
+                catch {
+                    // Skip malformed checkpoints
+                }
+            }
+        }
+        catch {
+            return [];
+        }
+        return checkpoints.sort((a, b) => a.timestamp - b.timestamp);
+    }
+    /**
+     * Get a summary of a checkpoint for display.
+     */
+    formatCheckpointSummary(checkpoint) {
+        const age = Date.now() - checkpoint.timestamp;
+        const ageStr = age < 60000
+            ? `${Math.round(age / 1000)}s ago`
+            : `${Math.round(age / 60000)}m ago`;
+        const lines = [
+            `Session: ${checkpoint.sessionId}`,
+            `Checkpoint: ${checkpoint.label} (${ageStr})`,
+            `Iteration: ${checkpoint.iteration}`,
+        ];
+        if (checkpoint.objective) {
+            lines.push(`Objective: ${checkpoint.objective.slice(0, 100)}`);
+        }
+        if (checkpoint.tokensUsed) {
+            lines.push(`Tokens used: ${checkpoint.tokensUsed}`);
+        }
+        if (checkpoint.filesModified && checkpoint.filesModified.length > 0) {
+            lines.push(`Files modified: ${checkpoint.filesModified.join(', ')}`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Clean up old checkpoints globally.
+     */
+    cleanupAll() {
+        let cleaned = 0;
+        const now = Date.now();
+        try {
+            if (!existsSync(this.config.checkpointDir))
+                return 0;
+            const sessions = readdirSync(this.config.checkpointDir);
+            for (const sessionId of sessions) {
+                const sessionDir = join(this.config.checkpointDir, sessionId);
+                try {
+                    const stat = statSync(sessionDir);
+                    if (!stat.isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const checkpoints = this.loadSessionCheckpoints(sessionId);
+                for (const ckpt of checkpoints) {
+                    if (now - ckpt.timestamp > this.config.maxAge) {
+                        try {
+                            unlinkSync(join(sessionDir, `${ckpt.id}.json`));
+                            cleaned++;
+                        }
+                        catch {
+                            // Deletion may fail
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory operations may fail
+        }
+        return cleaned;
+    }
+    // ===========================================================================
+    // INTERNAL
+    // ===========================================================================
+    cleanupSession(sessionId) {
+        const checkpoints = this.loadSessionCheckpoints(sessionId);
+        if (checkpoints.length > this.config.maxCheckpointsPerSession) {
+            // Remove oldest checkpoints
+            const toRemove = checkpoints.slice(0, checkpoints.length - this.config.maxCheckpointsPerSession);
+            const sessionDir = join(this.config.checkpointDir, sessionId);
+            for (const ckpt of toRemove) {
+                try {
+                    unlinkSync(join(sessionDir, `${ckpt.id}.json`));
+                }
+                catch {
+                    // Deletion may fail
+                }
+            }
+        }
+    }
+}
+/**
+ * Create an auto-checkpoint manager.
+ */
+export function createAutoCheckpointManager(config) {
+    return new AutoCheckpointManager(config);
+}
+//# sourceMappingURL=auto-checkpoint.js.map

package/dist/src/integrations/quality/auto-checkpoint.js.map

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

package/dist/src/integrations/quality/dead-letter-queue.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Dead Letter Queue
+ *
+ * Persists failed operations for later retry or manual intervention.
+ * Integrates with SQLite store for durability across sessions.
+ *
+ * @example
+ * ```typescript
+ * const dlq = createDeadLetterQueue(db);
+ *
+ * // On failure, add to DLQ
+ * await dlq.add({
+ *   operation: 'tool:bash',
+ *   args: { command: 'npm install' },
+ *   error: new Error('ETIMEDOUT'),
+ *   sessionId: 'session-123',
+ * });
+ *
+ * // At session start, drain pending items
+ * const pending = await dlq.getPending();
+ * for (const item of pending) {
+ *   const success = await retry(item);
+ *   if (success) await dlq.resolve(item.id);
+ * }
+ * ```
+ */
+import type Database from 'better-sqlite3';
+import { ErrorCategory, type AgentError } from '../../errors/index.js';
+/**
+ * Status of a dead letter item.
+ */
+export type DeadLetterStatus = 'pending' | 'retrying' | 'resolved' | 'abandoned';
+/**
+ * A failed operation stored in the dead letter queue.
+ */
+export interface DeadLetterItem {
+    /** Unique ID */
+    id: string;
+    /** Session ID (if associated with a session) */
+    sessionId?: string;
+    /** Operation type (e.g., 'tool:bash', 'mcp:playwright:click') */
+    operation: string;
+    /** Operation arguments (serialized JSON) */
+    args: string;
+    /** Error message */
+    error: string;
+    /** Error category for recovery decisions */
+    category: ErrorCategory;
+    /** Number of retry attempts made */
+    attempts: number;
+    /** Maximum retry attempts before abandoning */
+    maxAttempts: number;
+    /** Timestamp of last retry attempt */
+    lastAttempt: Date;
+    /** Timestamp for next retry (if scheduled) */
+    nextRetry?: Date;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Current status */
+    status: DeadLetterStatus;
+    /** When the item was created */
+    createdAt: Date;
+    /** When the item was resolved (if resolved) */
+    resolvedAt?: Date;
+}
+/**
+ * Input for adding a dead letter.
+ */
+export interface AddDeadLetterInput {
+    /** Operation type */
+    operation: string;
+    /** Operation arguments */
+    args: unknown;
+    /** Error that caused the failure */
+    error: Error | AgentError;
+    /** Associated session ID */
+    sessionId?: string;
+    /** Maximum retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for querying the dead letter queue.
+ */
+export interface DeadLetterQueryOptions {
+    /** Filter by status */
+    status?: DeadLetterStatus;
+    /** Filter by operation type */
+    operation?: string;
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Only items ready for retry (nextRetry <= now) */
+    readyForRetry?: boolean;
+    /** Limit number of results */
+    limit?: number;
+    /** Order by field */
+    orderBy?: 'createdAt' | 'lastAttempt' | 'nextRetry';
+}
+/**
+ * Dead letter queue statistics.
+ */
+export interface DeadLetterStats {
+    total: number;
+    pending: number;
+    retrying: number;
+    resolved: number;
+    abandoned: number;
+    byOperation: Record<string, number>;
+    byCategory: Record<string, number>;
+}
+/**
+ * Dead letter queue event types.
+ */
+export type DeadLetterEvent = {
+    type: 'item.added';
+    item: DeadLetterItem;
+} | {
+    type: 'item.retrying';
+    item: DeadLetterItem;
+} | {
+    type: 'item.resolved';
+    item: DeadLetterItem;
+} | {
+    type: 'item.abandoned';
+    item: DeadLetterItem;
+} | {
+    type: 'item.deleted';
+    id: string;
+};
+export type DeadLetterEventListener = (event: DeadLetterEvent) => void;
+/**
+ * Dead letter queue backed by SQLite.
+ */
+export declare class DeadLetterQueue {
+    private db;
+    private listeners;
+    private stmts?;
+    constructor(db: Database.Database);
+    private prepareStatements;
+    /**
+     * Check if DLQ is available (table exists).
+     */
+    isAvailable(): boolean;
+    /**
+     * Add a failed operation to the dead letter queue.
+     */
+    add(input: AddDeadLetterInput): Promise<DeadLetterItem>;
+    /**
+     * Get a dead letter item by ID.
+     */
+    get(id: string): DeadLetterItem | null;
+    /**
+     * Get pending items ready for retry.
+     */
+    getPending(options?: DeadLetterQueryOptions): DeadLetterItem[];
+    /**
+     * Query dead letters with filters.
+     */
+    query(options?: DeadLetterQueryOptions): DeadLetterItem[];
+    /**
+     * Mark an item as being retried.
+     */
+    markRetrying(id: string): void;
+    /**
+     * Mark an item as resolved (successful retry).
+     */
+    resolve(id: string): void;
+    /**
+     * Mark an item as abandoned (max retries exceeded or non-recoverable).
+     */
+    abandon(id: string): void;
+    /**
+     * Return an item to pending status after a failed retry.
+     */
+    returnToPending(id: string): void;
+    /**
+     * Delete an item from the queue.
+     */
+    delete(id: string): void;
+    /**
+     * Get queue statistics.
+     */
+    getStats(): DeadLetterStats;
+    /**
+     * Cleanup old resolved/abandoned items.
+     */
+    cleanup(olderThanDays?: number): number;
+    /**
+     * Add an event listener.
+     */
+    on(listener: DeadLetterEventListener): () => void;
+    private emit;
+    /**
+     * Calculate next retry time based on attempts and error category.
+     */
+    private calculateNextRetry;
+    private rowToItem;
+    private retryTimer;
+    private retryExecutor;
+    /**
+     * Register a retry executor function that will be called for each pending item.
+     * The executor should attempt to re-execute the operation and return true on success.
+     */
+    setRetryExecutor(executor: (item: DeadLetterItem) => Promise<boolean>): void;
+    /**
+     * Process all pending items that are ready for retry.
+     * Returns the number of items processed (resolved + abandoned).
+     */
+    processRetries(): Promise<{
+        resolved: number;
+        failed: number;
+        abandoned: number;
+    }>;
+    /**
+     * Start a periodic retry loop.
+     * @param intervalMs - How often to check for retries (default: 60000ms = 1 minute)
+     */
+    startRetryLoop(intervalMs?: number): void;
+    /**
+     * Stop the periodic retry loop.
+     */
+    stopRetryLoop(): void;
+}
+/**
+ * Create a dead letter queue instance.
+ */
+export declare function createDeadLetterQueue(db: Database.Database): DeadLetterQueue;
+/**
+ * Format dead letter stats for display.
+ */
+export declare function formatDeadLetterStats(stats: DeadLetterStats): string;
+//# sourceMappingURL=dead-letter-queue.d.ts.map

package/dist/src/integrations/quality/dead-letter-queue.d.ts.map

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