@claudetools/tools 0.3.9 → 0.5.0

package/dist/helpers/library-detection.js

@@ -0,0 +1,145 @@
+// =============================================================================
+// Library/Framework Detection for Task Planning
+// =============================================================================
+/**
+ * Common libraries and frameworks to detect in task descriptions
+ * Maps lowercase keywords to canonical library names
+ */
+const LIBRARY_KEYWORDS = {
+    // Frontend frameworks
+    'react': 'React',
+    'reactjs': 'React',
+    'react.js': 'React',
+    'next': 'Next.js',
+    'nextjs': 'Next.js',
+    'next.js': 'Next.js',
+    'vue': 'Vue.js',
+    'vuejs': 'Vue.js',
+    'vue.js': 'Vue.js',
+    'angular': 'Angular',
+    'svelte': 'Svelte',
+    'sveltekit': 'SvelteKit',
+    // Backend frameworks
+    'express': 'Express',
+    'expressjs': 'Express',
+    'fastify': 'Fastify',
+    'hono': 'Hono',
+    'koa': 'Koa',
+    'nest': 'NestJS',
+    'nestjs': 'NestJS',
+    // Databases & ORMs
+    'supabase': 'Supabase',
+    'firebase': 'Firebase',
+    'prisma': 'Prisma',
+    'drizzle': 'Drizzle',
+    'mongoose': 'Mongoose',
+    'mongodb': 'MongoDB',
+    'postgres': 'PostgreSQL',
+    'postgresql': 'PostgreSQL',
+    'mysql': 'MySQL',
+    'redis': 'Redis',
+    // State management
+    'redux': 'Redux',
+    'zustand': 'Zustand',
+    'jotai': 'Jotai',
+    'recoil': 'Recoil',
+    'tanstack': 'TanStack Query',
+    'react-query': 'TanStack Query',
+    'swr': 'SWR',
+    // UI libraries
+    'tailwind': 'Tailwind CSS',
+    'tailwindcss': 'Tailwind CSS',
+    'shadcn': 'shadcn/ui',
+    'radix': 'Radix UI',
+    'chakra': 'Chakra UI',
+    'mantine': 'Mantine',
+    'mui': 'Material UI',
+    'material-ui': 'Material UI',
+    // Testing
+    'jest': 'Jest',
+    'vitest': 'Vitest',
+    'playwright': 'Playwright',
+    'cypress': 'Cypress',
+    'testing-library': 'Testing Library',
+    // Build tools
+    'vite': 'Vite',
+    'webpack': 'Webpack',
+    'esbuild': 'esbuild',
+    'turbopack': 'Turbopack',
+    'turborepo': 'Turborepo',
+    // Auth & APIs
+    'auth': 'Authentication',
+    'oauth': 'OAuth',
+    'jwt': 'JWT',
+    'stripe': 'Stripe',
+    'openai': 'OpenAI',
+    'langchain': 'LangChain',
+    'vercel': 'Vercel',
+    // Other
+    'typescript': 'TypeScript',
+    'graphql': 'GraphQL',
+    'trpc': 'tRPC',
+    'zod': 'Zod',
+    'socket.io': 'Socket.IO',
+    'websocket': 'WebSocket',
+};
+/**
+ * Context7-compatible library ID mappings
+ * Maps canonical names to context7 library IDs
+ */
+export const CONTEXT7_LIBRARY_IDS = {
+    'React': '/facebook/react',
+    'Next.js': '/vercel/next.js',
+    'Vue.js': '/vuejs/vue',
+    'Supabase': '/supabase/supabase',
+    'Prisma': '/prisma/prisma',
+    'Tailwind CSS': '/tailwindlabs/tailwindcss',
+    'TypeScript': '/microsoft/typescript',
+    'Vitest': '/vitest-dev/vitest',
+    'Zod': '/colinhacks/zod',
+    'tRPC': '/trpc/trpc',
+    'TanStack Query': '/tanstack/query',
+};
+/**
+ * Detect libraries mentioned in text
+ * @param text - Text to scan for library mentions
+ * @returns Array of detected libraries with mention counts
+ */
+export function detectLibraries(text) {
+    const lowerText = text.toLowerCase();
+    const detected = new Map();
+    // Scan for each keyword
+    for (const [keyword, libraryName] of Object.entries(LIBRARY_KEYWORDS)) {
+        // Use word boundary matching to avoid partial matches
+        const regex = new RegExp(`\\b${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi');
+        const matches = lowerText.match(regex);
+        if (matches) {
+            const current = detected.get(libraryName) || 0;
+            detected.set(libraryName, current + matches.length);
+        }
+    }
+    // Convert to array and sort by mention count
+    const results = [];
+    for (const [name, mentions] of detected) {
+        results.push({
+            name,
+            context7Id: CONTEXT7_LIBRARY_IDS[name],
+            mentions,
+        });
+    }
+    return results.sort((a, b) => b.mentions - a.mentions);
+}
+/**
+ * Detect libraries from goal and task descriptions
+ * @param goal - The epic/plan goal
+ * @param tasks - Array of task objects with title and description
+ * @returns Deduplicated list of detected libraries
+ */
+export function detectLibrariesFromPlan(goal, tasks) {
+    // Combine all text
+    const allText = [
+        goal,
+        ...tasks.map(t => `${t.title} ${t.description || ''}`),
+    ].join(' ');
+    return detectLibraries(allText);
+}

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

@@ -0,0 +1,49 @@
+import { type Task } from './tasks.js';
+export interface TimedOutTask {
+    task: Task;
+    lockExpiredAt: string;
+    timeSinceExpiry: number;
+}
+export interface RetryMetadata {
+    retryCount: number;
+    lastFailedAt: string;
+    lastError?: string;
+    failureHistory: Array<{
+        timestamp: string;
+        error?: string;
+    }>;
+}
+/**
+ * Detect tasks that have timed out (lock expired while in_progress)
+ * These are likely abandoned or failed tasks
+ */
+export declare function detectTimedOutTasks(userId: string, projectId: string): Promise<TimedOutTask[]>;
+/**
+ * Retry a failed or timed-out task
+ * Returns success: false if retry limit exceeded
+ */
+export declare function retryTask(userId: string, projectId: string, taskId: string, maxRetries?: number, errorContext?: string): Promise<{
+    success: boolean;
+    data?: {
+        task: Task;
+        retryCount: number;
+        retriesRemaining: number;
+    };
+    error?: string;
+}>;
+/**
+ * Mark a task as failed with context
+ */
+export declare function failTask(userId: string, projectId: string, taskId: string, errorContext: string, agentId?: string): Promise<{
+    success: boolean;
+    data: Task;
+}>;
+/**
+ * Auto-detect and handle timed-out tasks
+ * Returns tasks that were auto-retried
+ */
+export declare function autoRetryTimedOutTasks(userId: string, projectId: string, maxRetries?: number): Promise<{
+    timedOut: TimedOutTask[];
+    retried: Task[];
+    failed: Task[];
+}>;

package/dist/helpers/tasks-retry.js

@@ -0,0 +1,168 @@
+// =============================================================================
+// Task Failure Handling & Retry System
+// =============================================================================
+import { apiRequest } from './api-client.js';
+import { getTask, listTasks, updateTaskStatus, addTaskContext } from './tasks.js';
+/**
+ * Get retry metadata from task metadata
+ */
+function getRetryMetadata(task) {
+    const metadata = task.metadata || {};
+    return {
+        retryCount: metadata.retryCount || 0,
+        lastFailedAt: metadata.lastFailedAt || '',
+        lastError: metadata.lastError,
+        failureHistory: metadata.failureHistory || [],
+    };
+}
+/**
+ * Update retry metadata
+ */
+function updateRetryMetadata(metadata, error) {
+    const current = metadata;
+    const retryCount = (current.retryCount || 0) + 1;
+    const timestamp = new Date().toISOString();
+    const failureHistory = (current.failureHistory || []);
+    return {
+        ...metadata,
+        retryCount,
+        lastFailedAt: timestamp,
+        lastError: error,
+        failureHistory: [
+            ...failureHistory,
+            { timestamp, error },
+        ],
+    };
+}
+/**
+ * Detect tasks that have timed out (lock expired while in_progress)
+ * These are likely abandoned or failed tasks
+ */
+export async function detectTimedOutTasks(userId, projectId) {
+    // Get all in_progress tasks
+    const result = await listTasks(userId, projectId, {
+        status: 'in_progress',
+        limit: 100,
+    });
+    if (!result.success || !result.data.length) {
+        return [];
+    }
+    const now = new Date();
+    const timedOut = [];
+    for (const task of result.data) {
+        // Check if lock has expired
+        if (task.lock_expires_at) {
+            const lockExpires = new Date(task.lock_expires_at);
+            if (lockExpires < now) {
+                timedOut.push({
+                    task,
+                    lockExpiredAt: task.lock_expires_at,
+                    timeSinceExpiry: now.getTime() - lockExpires.getTime(),
+                });
+            }
+        }
+    }
+    return timedOut;
+}
+/**
+ * Retry a failed or timed-out task
+ * Returns success: false if retry limit exceeded
+ */
+export async function retryTask(userId, projectId, taskId, maxRetries = 3, errorContext) {
+    // Get current task
+    const taskResult = await getTask(userId, projectId, taskId);
+    if (!taskResult.success) {
+        return {
+            success: false,
+            error: 'Task not found',
+        };
+    }
+    const task = taskResult.data;
+    const retryMetadata = getRetryMetadata(task);
+    // Check retry limit
+    if (retryMetadata.retryCount >= maxRetries) {
+        // Mark as failed permanently
+        await updateTaskStatus(userId, projectId, taskId, 'failed');
+        // Add failure context
+        await addTaskContext(userId, projectId, taskId, 'work_log', `Task failed permanently after ${retryMetadata.retryCount} retries. Last error: ${errorContext || 'Unknown'}`, 'system');
+        return {
+            success: false,
+            error: `Retry limit exceeded (${maxRetries} retries)`,
+        };
+    }
+    // Update metadata with failure info
+    const updatedMetadata = updateRetryMetadata(task.metadata || {}, errorContext);
+    // Update task with retry metadata and reset status
+    // Using the /api/v1/tasks/:userId/:projectId/:taskId endpoint with POST
+    await apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}`, 'POST', {
+        status: 'ready',
+        assigned_to: null,
+        locked_at: null,
+        lock_expires_at: null,
+        metadata: updatedMetadata,
+    });
+    // Add retry context
+    const newRetryCount = retryMetadata.retryCount + 1;
+    await addTaskContext(userId, projectId, taskId, 'work_log', `Task retry ${newRetryCount}/${maxRetries}. Previous failure: ${errorContext || 'Lock timeout'}`, 'system');
+    // Get updated task
+    const updatedResult = await getTask(userId, projectId, taskId);
+    const updatedTask = updatedResult.data;
+    return {
+        success: true,
+        data: {
+            task: updatedTask,
+            retryCount: newRetryCount,
+            retriesRemaining: maxRetries - newRetryCount,
+        },
+    };
+}
+/**
+ * Mark a task as failed with context
+ */
+export async function failTask(userId, projectId, taskId, errorContext, agentId) {
+    // Get current task to update metadata
+    const taskResult = await getTask(userId, projectId, taskId);
+    if (!taskResult.success) {
+        throw new Error('Task not found');
+    }
+    const task = taskResult.data;
+    const updatedMetadata = updateRetryMetadata(task.metadata || {}, errorContext);
+    // Update to failed status with metadata
+    await apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}`, 'POST', {
+        status: 'failed',
+        metadata: updatedMetadata,
+        assigned_to: null,
+        locked_at: null,
+        lock_expires_at: null,
+    });
+    // Add failure context
+    await addTaskContext(userId, projectId, taskId, 'work_log', `Task failed: ${errorContext}`, agentId || 'system');
+    // Get updated task
+    const result = await getTask(userId, projectId, taskId);
+    return result;
+}
+/**
+ * Auto-detect and handle timed-out tasks
+ * Returns tasks that were auto-retried
+ */
+export async function autoRetryTimedOutTasks(userId, projectId, maxRetries = 3) {
+    const timedOut = await detectTimedOutTasks(userId, projectId);
+    const retried = [];
+    const failed = [];
+    for (const { task, timeSinceExpiry } of timedOut) {
+        const minutesSinceExpiry = Math.floor(timeSinceExpiry / 1000 / 60);
+        const errorContext = `Lock timeout: expired ${minutesSinceExpiry} minutes ago`;
+        const retryResult = await retryTask(userId, projectId, task.id, maxRetries, errorContext);
+        if (retryResult.success && retryResult.data) {
+            retried.push(retryResult.data.task);
+        }
+        else {
+            // Task failed permanently
+            const failResult = await getTask(userId, projectId, task.id);
+            if (failResult.success) {
+                failed.push(failResult.data);
+            }
+        }
+    }
+    return { timedOut, retried, failed };
+}

package/dist/helpers/tasks.d.ts

@@ -127,12 +127,23 @@ export declare function heartbeatTask(userId: string, projectId: string, taskId:
         new_expires_at: string;
     };
 }>;
+export declare const DEFAULT_MAX_PARALLEL = 5;
+/**
+ * Get count of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts
+ */
+export declare function getActiveTaskCount(userId: string, projectId: string, epicId?: string): Promise<{
+    inProgress: number;
+    claimed: number;
+    total: number;
+}>;
 /**
  * Get all tasks ready for parallel dispatch
  * - Filters for 'ready' status
  * - 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
  */
 export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, maxParallel?: number): Promise<DispatchableTask[]>;
 /**
@@ -147,6 +158,18 @@ export declare function getExecutionContext(userId: string, projectId: string, t
     siblingTasks?: Task[];
 }>;
 /**
- * Find newly unblocked tasks after a completion
+ * 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[]>;
+/**
+ * Get epic status with progress tracking
+ * Auto-completes epic if all child tasks are done
+ */
+export declare function getEpicStatus(userId: string, projectId: string, epicId: string): Promise<{
+    epic: Task;
+    totalTasks: number;
+    byStatus: Record<string, number>;
+    percentComplete: number;
+    allComplete: boolean;
+    autoCompleted: boolean;
+}>;

package/dist/helpers/tasks.js

@@ -2,7 +2,7 @@
 // Task Management System
 // =============================================================================
 import { apiRequest } from './api-client.js';
-import { matchTaskToWorker } from './workers.js';
+import { matchTaskToWorker, buildWorkerPrompt } from './workers.js';
 export function parseJsonArray(value) {
     if (!value)
         return [];
@@ -90,14 +90,57 @@ export async function heartbeatTask(userId, projectId, taskId, agentId, extendMi
 // -----------------------------------------------------------------------------
 // Orchestration Functions
 // -----------------------------------------------------------------------------
+// Configuration: Default maximum parallel tasks
+export const DEFAULT_MAX_PARALLEL = 5;
+/**
+ * Get count of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts
+ */
+export async function getActiveTaskCount(userId, projectId, epicId) {
+    // Get all in_progress tasks
+    const inProgressResult = await listTasks(userId, projectId, {
+        status: 'in_progress',
+        parent_id: epicId,
+        limit: 100,
+    });
+    let inProgressCount = 0;
+    let claimedCount = 0;
+    if (inProgressResult.success && inProgressResult.data.length > 0) {
+        const now = new Date();
+        for (const task of inProgressResult.data) {
+            inProgressCount++;
+            // Check if task is also claimed (has valid lock)
+            if (task.assigned_to && task.lock_expires_at) {
+                const lockExpires = new Date(task.lock_expires_at);
+                if (lockExpires > now) {
+                    claimedCount++;
+                }
+            }
+        }
+    }
+    return {
+        inProgress: inProgressCount,
+        claimed: claimedCount,
+        total: inProgressCount,
+    };
+}
 /**
  * Get all tasks ready for parallel dispatch
  * - Filters for 'ready' status
  * - 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
  */
-export async function getDispatchableTasks(userId, projectId, epicId, maxParallel = 5) {
+export async function getDispatchableTasks(userId, projectId, epicId, maxParallel = DEFAULT_MAX_PARALLEL) {
+    // Get current active task count
+    const activeCount = await getActiveTaskCount(userId, projectId, epicId);
+    // Calculate remaining capacity
+    const remainingCapacity = maxParallel - activeCount.total;
+    if (remainingCapacity <= 0) {
+        // No capacity available, return empty array
+        return [];
+    }
     // Get all tasks with 'ready' status
     const result = await listTasks(userId, projectId, {
         status: 'ready',
@@ -152,7 +195,8 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             parentContext: taskData.parent,
             dependencies: [],
         });
-        if (dispatchable.length >= maxParallel) {
+        // Only dispatch tasks that fit within remaining capacity
+        if (dispatchable.length >= remainingCapacity) {
             break;
         }
     }
@@ -184,46 +228,29 @@ export async function getExecutionContext(userId, projectId, taskId) {
             siblingTasks = siblingResult.data.filter(t => t.id !== taskId);
         }
     }
-    // Build system prompt
-    let systemPrompt = worker.promptTemplate + '\n\n';
-    systemPrompt += `# Task: ${task.title}\n\n`;
-    if (task.description) {
-        systemPrompt += `## Description\n${task.description}\n\n`;
-    }
-    // Add acceptance criteria
-    const criteria = parseJsonArray(task.acceptance_criteria);
-    if (criteria.length > 0) {
-        systemPrompt += `## Acceptance Criteria\n`;
-        criteria.forEach((c, i) => {
-            systemPrompt += `${i + 1}. ${c}\n`;
-        });
-        systemPrompt += '\n';
-    }
-    // Add parent context
-    if (taskData.parent) {
-        systemPrompt += `## Epic Context\n`;
-        systemPrompt += `**Epic:** ${taskData.parent.title}\n`;
-        if (taskData.parent.description) {
-            systemPrompt += `**Goal:** ${taskData.parent.description}\n`;
-        }
-        systemPrompt += '\n';
-    }
-    // Add attached context
-    if (taskData.context.length > 0) {
-        systemPrompt += `## Attached Context\n`;
-        for (const ctx of taskData.context) {
-            systemPrompt += `### ${ctx.context_type.toUpperCase()}${ctx.source ? ` (${ctx.source})` : ''}\n`;
-            systemPrompt += `${ctx.content}\n\n`;
-        }
-    }
-    // Add sibling task awareness
-    if (siblingTasks && siblingTasks.length > 0) {
-        systemPrompt += `## Related Tasks (for awareness)\n`;
-        for (const sibling of siblingTasks.slice(0, 5)) {
-            systemPrompt += `- ${sibling.title} [${sibling.status}]\n`;
-        }
-        systemPrompt += '\n';
-    }
+    // Build structured system prompt using the template system
+    const systemPrompt = buildWorkerPrompt({
+        task: {
+            id: task.id,
+            title: task.title,
+            description: task.description || undefined,
+            acceptance_criteria: task.acceptance_criteria,
+        },
+        worker,
+        epicContext: taskData.parent ? {
+            title: taskData.parent.title,
+            description: taskData.parent.description || undefined,
+        } : undefined,
+        attachedContext: taskData.context.map(ctx => ({
+            type: ctx.context_type,
+            content: ctx.content,
+            source: ctx.source || undefined,
+        })),
+        siblingTasks: siblingTasks?.slice(0, 5).map(s => ({
+            title: s.title,
+            status: s.status,
+        })),
+    });
     return {
         task,
         worker,
@@ -234,20 +261,20 @@ export async function getExecutionContext(userId, projectId, taskId) {
     };
 }
 /**
- * Find newly unblocked tasks after a completion
+ * Find newly unblocked tasks after a completion and update their status to ready
  */
 export async function resolveTaskDependencies(userId, projectId, completedTaskId, epicId) {
-    // Get all tasks that might be blocked by the completed task
-    const result = await listTasks(userId, projectId, {
-        status: 'ready', // or 'blocked'
+    // Get all blocked tasks that might be unblocked by the completed task
+    const blockedResult = await listTasks(userId, projectId, {
+        status: 'blocked',
         parent_id: epicId,
         limit: 50,
     });
-    if (!result.success) {
+    if (!blockedResult.success) {
         return [];
     }
     const newlyUnblocked = [];
-    for (const task of result.data) {
+    for (const task of blockedResult.data) {
         const blockedBy = parseJsonArray(task.blocked_by);
         // Check if this task was blocked by the completed task
         if (blockedBy.includes(completedTaskId)) {
@@ -265,10 +292,79 @@ export async function resolveTaskDependencies(userId, projectId, completedTaskId
                     }
                 }
             }
+            // If all blockers are complete, update task status to ready
             if (allBlockersComplete) {
-                newlyUnblocked.push(task);
+                const updateResult = await updateTaskStatus(userId, projectId, task.id, 'ready');
+                if (updateResult.success) {
+                    newlyUnblocked.push(updateResult.data);
+                }
             }
         }
     }
     return newlyUnblocked;
 }
+/**
+ * Get epic status with progress tracking
+ * Auto-completes epic if all child tasks are done
+ */
+export async function getEpicStatus(userId, projectId, epicId) {
+    // Get the epic
+    const epicResult = await getTask(userId, projectId, epicId);
+    if (!epicResult.success) {
+        throw new Error(`Epic not found: ${epicId}`);
+    }
+    const epic = epicResult.data;
+    // Verify it's an epic
+    if (epic.type !== 'epic') {
+        throw new Error(`Task ${epicId} is not an epic (type: ${epic.type})`);
+    }
+    // Get all child tasks
+    const tasksResult = await listTasks(userId, projectId, {
+        parent_id: epicId,
+        limit: 100,
+    });
+    if (!tasksResult.success) {
+        return {
+            epic,
+            totalTasks: 0,
+            byStatus: {},
+            percentComplete: 0,
+            allComplete: false,
+            autoCompleted: false,
+        };
+    }
+    const tasks = tasksResult.data;
+    const totalTasks = tasks.length;
+    // Count by status
+    const byStatus = {
+        backlog: 0,
+        ready: 0,
+        in_progress: 0,
+        blocked: 0,
+        review: 0,
+        done: 0,
+        cancelled: 0,
+    };
+    for (const task of tasks) {
+        byStatus[task.status] = (byStatus[task.status] || 0) + 1;
+    }
+    // Calculate progress
+    const doneCount = byStatus.done || 0;
+    const percentComplete = totalTasks > 0 ? Math.round((doneCount / totalTasks) * 100) : 0;
+    const allComplete = totalTasks > 0 && doneCount === totalTasks;
+    // Auto-complete epic if all tasks done and epic not already done
+    let autoCompleted = false;
+    if (allComplete && epic.status !== 'done') {
+        await updateTaskStatus(userId, projectId, epicId, 'done', 'system:auto-complete');
+        epic.status = 'done';
+        autoCompleted = true;
+    }
+    return {
+        epic,
+        totalTasks,
+        byStatus,
+        percentComplete,
+        allComplete,
+        autoCompleted,
+    };
+}