attocode 0.2.4 → 0.2.5

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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"}