@claudetools/tools 0.8.3 → 0.8.5

package/dist/helpers/circuit-breaker.js

@@ -0,0 +1,97 @@
+// =============================================================================
+// Circuit Breaker for Worker Failure Tracking
+// =============================================================================
+//
+// Implements the circuit breaker pattern to prevent dispatching tasks to
+// failing workers. Tracks failures per worker type and opens circuit after
+// threshold is reached. Circuit auto-closes after cooldown period.
+//
+// Circuit States:
+// - CLOSED: Normal operation, tasks dispatched
+// - OPEN: Too many failures, tasks NOT dispatched to this worker type
+// - HALF_OPEN: Cooldown complete, attempting recovery (not implemented yet)
+//
+// Configuration
+const FAILURE_THRESHOLD = 3; // Open circuit after N failures
+const FAILURE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes window for counting failures
+const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes cooldown before auto-close
+// In-memory circuit state (per worker type)
+const circuits = new Map();
+/**
+ * Record a worker failure
+ * Increments failure count and potentially opens the circuit
+ */
+export function recordWorkerFailure(workerType) {
+    const now = Date.now();
+    const state = circuits.get(workerType) || {
+        failures: 0,
+        lastFailure: 0,
+        openedAt: null,
+    };
+    // If circuit is already open, don't count new failures
+    if (state.openedAt !== null) {
+        return;
+    }
+    // Check if last failure was outside the window
+    if (now - state.lastFailure > FAILURE_WINDOW_MS) {
+        // Reset failure count (new window)
+        state.failures = 1;
+    }
+    else {
+        // Within window, increment
+        state.failures++;
+    }
+    state.lastFailure = now;
+    // Check if we should open the circuit
+    if (state.failures >= FAILURE_THRESHOLD) {
+        state.openedAt = now;
+        console.warn(`[Circuit Breaker] OPENED for worker type: ${workerType} (${state.failures} failures)`);
+    }
+    circuits.set(workerType, state);
+}
+/**
+ * Check if circuit is open for a worker type
+ * Auto-closes circuit if cooldown period has elapsed
+ */
+export function isCircuitOpen(workerType) {
+    const state = circuits.get(workerType);
+    // No failures recorded = closed
+    if (!state || state.openedAt === null) {
+        return false;
+    }
+    const now = Date.now();
+    const timeSinceOpened = now - state.openedAt;
+    // Check if cooldown has elapsed
+    if (timeSinceOpened >= COOLDOWN_MS) {
+        // Auto-close circuit
+        state.openedAt = null;
+        state.failures = 0;
+        circuits.set(workerType, state);
+        console.info(`[Circuit Breaker] AUTO-CLOSED for worker type: ${workerType} (cooldown elapsed)`);
+        return false;
+    }
+    // Still in cooldown
+    return true;
+}
+/**
+ * Get circuit status for all worker types
+ * Useful for monitoring and debugging
+ */
+export function getCircuitStatus() {
+    // Return a copy of the current state
+    return new Map(circuits);
+}
+/**
+ * Manually reset a circuit (for testing or admin override)
+ */
+export function resetCircuit(workerType) {
+    circuits.delete(workerType);
+    console.info(`[Circuit Breaker] RESET for worker type: ${workerType}`);
+}
+/**
+ * Reset all circuits (for testing)
+ */
+export function resetAllCircuits() {
+    circuits.clear();
+    console.info('[Circuit Breaker] RESET ALL circuits');
+}

package/dist/helpers/compact-formatter.d.ts

@@ -49,3 +49,5 @@ export declare function compactMemoryIndex(entries: {
     relevance: number;
     is_critical?: boolean;
 }[]): string;
+/** Compact task handoff */
+export declare function compactTaskHandoff(task: Task, handedOff: boolean, newWorkerType: string): string;

package/dist/helpers/compact-formatter.js

@@ -128,3 +128,9 @@ export function compactMemoryIndex(entries) {
         return `${i + 1}. ${critical}${e.summary.slice(0, 60)} (${rel}%) [${shortId(e.id)}]`;
     }).join('\n');
 }
+/** Compact task handoff */
+export function compactTaskHandoff(task, handedOff, newWorkerType) {
+    if (!handedOff)
+        return `❌ Failed to hand off: ${task.title}`;
+    return `🔄 Handed off: ${task.title} → ${newWorkerType} (ready for re-dispatch)`;
+}

package/dist/helpers/error-tracking.js

@@ -28,7 +28,7 @@ export class CodeDNAErrorTracker {
             // Store error in memory system as a fact
             const userId = DEFAULT_USER_ID;
             const projectId = error.projectId || resolveProjectId();
-            await storeFact(projectId, 'CodeDNA', 'ERROR_OCCURRED', error.operation, JSON.stringify(errorRecord), userId);
+            await storeFact(projectId, 'CodeDNA', 'ERROR_OCCURRED', error.operation, JSON.stringify(errorRecord), { userId });
             // Log to console for immediate visibility
             console.error('[CodeDNA Error]', {
                 operation: error.operation,

package/dist/helpers/tasks-retry.d.ts

@@ -7,12 +7,19 @@ export interface TimedOutTask {
 export interface RetryMetadata {
     retryCount: number;
     lastFailedAt: string;
+    lastRetryAt?: string;
     lastError?: string;
     failureHistory: Array<{
         timestamp: string;
         error?: string;
     }>;
 }
+/**
+ * Calculate exponential backoff delay in milliseconds
+ * Formula: delay_ms = min(1000 * 2^retry_count, 300000)
+ * Max delay is 5 minutes (300000ms)
+ */
+export declare function calculateBackoffDelay(retryCount: number): number;
 /**
  * Detect tasks that have timed out (lock expired while in_progress)
  * These are likely abandoned or failed tasks
@@ -28,8 +35,10 @@ export declare function retryTask(userId: string, projectId: string, taskId: str
         task: Task;
         retryCount: number;
         retriesRemaining: number;
+        retryAfter?: string;
     };
     error?: string;
+    retryAfter?: string;
 }>;
 /**
  * Mark a task as failed with context

package/dist/helpers/tasks-retry.js

@@ -11,10 +11,22 @@ function getRetryMetadata(task) {
     return {
         retryCount: metadata.retryCount || 0,
         lastFailedAt: metadata.lastFailedAt || '',
+        lastRetryAt: metadata.lastRetryAt,
         lastError: metadata.lastError,
         failureHistory: metadata.failureHistory || [],
     };
 }
+/**
+ * Calculate exponential backoff delay in milliseconds
+ * Formula: delay_ms = min(1000 * 2^retry_count, 300000)
+ * Max delay is 5 minutes (300000ms)
+ */
+export function calculateBackoffDelay(retryCount) {
+    const baseDelay = 1000; // 1 second
+    const maxDelay = 300000; // 5 minutes
+    const delay = baseDelay * Math.pow(2, retryCount);
+    return Math.min(delay, maxDelay);
+}
 /**
  * Update retry metadata
  */
@@ -27,6 +39,7 @@ function updateRetryMetadata(metadata, error) {
         ...metadata,
         retryCount,
         lastFailedAt: timestamp,
+        lastRetryAt: timestamp,
         lastError: error,
         failureHistory: [
             ...failureHistory,
@@ -90,6 +103,23 @@ export async function retryTask(userId, projectId, taskId, maxRetries = 3, error
             error: `Retry limit exceeded (${maxRetries} retries)`,
         };
     }
+    // Check exponential backoff window
+    if (retryMetadata.lastRetryAt && retryMetadata.retryCount > 0) {
+        const lastRetryTime = new Date(retryMetadata.lastRetryAt);
+        const now = new Date();
+        const timeSinceLastRetry = now.getTime() - lastRetryTime.getTime();
+        const backoffDelay = calculateBackoffDelay(retryMetadata.retryCount);
+        if (timeSinceLastRetry < backoffDelay) {
+            const remainingBackoff = backoffDelay - timeSinceLastRetry;
+            const retryAfterTime = new Date(now.getTime() + remainingBackoff);
+            const retryAfter = retryAfterTime.toISOString();
+            return {
+                success: false,
+                error: `Task is in backoff window. Please wait ${Math.ceil(remainingBackoff / 1000)} seconds before retrying.`,
+                retryAfter,
+            };
+        }
+    }
     // Update metadata with failure info
     const updatedMetadata = updateRetryMetadata(task.metadata || {}, errorContext);
     // Update task with retry metadata and reset status

package/dist/helpers/tasks.d.ts

@@ -127,15 +127,30 @@ export declare function heartbeatTask(userId: string, projectId: string, taskId:
         new_expires_at: string;
     };
 }>;
-export declare const DEFAULT_MAX_PARALLEL = 5;
+export declare const EFFORT_WEIGHTS: {
+    readonly xs: 1;
+    readonly s: 2;
+    readonly m: 4;
+    readonly l: 8;
+    readonly xl: 16;
+};
+export declare const LOCK_DURATION_BY_EFFORT: {
+    readonly xs: 15;
+    readonly s: 30;
+    readonly m: 60;
+    readonly l: 120;
+    readonly xl: 240;
+};
+export declare const DEFAULT_CAPACITY_BUDGET = 20;
 /**
- * Get count of currently active tasks
- * Returns both in_progress and claimed (locked) task counts
+ * Get effort-weighted load of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts, plus effort-weighted load
  */
 export declare function getActiveTaskCount(userId: string, projectId: string, epicId?: string): Promise<{
     inProgress: number;
     claimed: number;
     total: number;
+    effortLoad: number;
 }>;
 /**
  * Get all tasks ready for parallel dispatch
@@ -143,9 +158,17 @@ export declare function getActiveTaskCount(userId: string, projectId: string, ep
  * - Excludes already claimed tasks
  * - Resolves dependencies (only returns unblocked tasks)
  * - Matches each to appropriate expert worker
- * - Respects max parallel limit by considering currently active tasks
+ * - Respects effort-weighted capacity budget
  */
-export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, maxParallel?: number): Promise<DispatchableTask[]>;
+export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, capacityBudget?: number): Promise<DispatchableTask[]>;
+/**
+ * Check if task lock is about to expire and return warning
+ */
+export declare function getLockExpiryWarning(lockExpiresAt: string | null): {
+    warning: boolean;
+    minutes_remaining: number;
+    message?: string;
+};
 /**
  * Get full execution context for a worker agent
  */
@@ -156,11 +179,41 @@ export declare function getExecutionContext(userId: string, projectId: string, t
     context: TaskContext[];
     parentTask?: Task;
     siblingTasks?: Task[];
+    lockWarning?: {
+        warning: boolean;
+        minutes_remaining: number;
+        message?: string;
+    };
 }>;
 /**
  * Find newly unblocked tasks after a completion and update their status to ready
  */
 export declare function resolveTaskDependencies(userId: string, projectId: string, completedTaskId: string, epicId?: string): Promise<Task[]>;
+/**
+ * Aggregate work_log context from all tasks in an epic
+ * Used by orchestrator to synthesize final results
+ */
+export declare function getEpicAggregate(userId: string, projectId: string, epicId: string, includePending?: boolean): Promise<{
+    epic: {
+        id: string;
+        title: string;
+        description: string;
+        status: string;
+    };
+    tasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+        work_log: string | null;
+        completed_at: string | null;
+    }>;
+    summary_stats: {
+        total: number;
+        completed: number;
+        in_progress: number;
+        pending: number;
+    };
+}>;
 /**
  * Get epic status with progress tracking
  * Auto-completes epic if all child tasks are done
@@ -173,3 +226,36 @@ export declare function getEpicStatus(userId: string, projectId: string, epicId:
     allComplete: boolean;
     autoCompleted: boolean;
 }>;
+export declare function handoffTask(userId: string, projectId: string, taskId: string, agentId: string, newWorkerType: string, reason: string): Promise<{
+    success: boolean;
+    data: {
+        task: Task;
+        handed_off: boolean;
+        new_worker_type: string;
+    };
+}>;
+/**
+ * Revise an existing epic by adding/removing/updating tasks
+ * Enables iterative planning without recreating the entire epic
+ */
+export declare function reviseEpic(userId: string, projectId: string, epicId: string, changes: {
+    add_tasks?: {
+        title: string;
+        description?: string;
+        effort?: string;
+        domain?: string;
+        blocked_by?: string[];
+    }[];
+    remove_task_ids?: string[];
+    update_tasks?: {
+        task_id: string;
+        title?: string;
+        description?: string;
+        effort?: string;
+    }[];
+}): Promise<{
+    epic: Task;
+    added: Task[];
+    removed: string[];
+    updated: Task[];
+}>;