@claudetools/tools 0.8.3 → 0.8.5

package/dist/helpers/tasks.js

@@ -3,6 +3,7 @@
 // =============================================================================
 import { apiRequest } from './api-client.js';
 import { matchTaskToWorker, buildWorkerPrompt } from './workers.js';
+import { isCircuitOpen } from './circuit-breaker.js';
 export function parseJsonArray(value) {
     if (!value)
         return [];
@@ -51,11 +52,12 @@ export async function getTask(userId, projectId, taskId, full = false) {
     const endpoint = full ? 'full' : '';
     return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}${endpoint ? `/${endpoint}` : ''}`);
 }
-export async function claimTask(userId, projectId, taskId, agentId, lockDurationMinutes = 30) {
-    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/claim`, 'POST', {
-        agent_id: agentId,
-        lock_duration_minutes: lockDurationMinutes,
-    });
+export async function claimTask(userId, projectId, taskId, agentId, lockDurationMinutes) {
+    const body = { agent_id: agentId };
+    if (lockDurationMinutes !== undefined) {
+        body.lock_duration_minutes = lockDurationMinutes;
+    }
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/claim`, 'POST', body);
 }
 export async function releaseTask(userId, projectId, taskId, agentId, newStatus, workLog) {
     return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/release`, 'POST', {
@@ -90,11 +92,29 @@ export async function heartbeatTask(userId, projectId, taskId, agentId, extendMi
 // -----------------------------------------------------------------------------
 // Orchestration Functions
 // -----------------------------------------------------------------------------
-// Configuration: Default maximum parallel tasks
-export const DEFAULT_MAX_PARALLEL = 5;
+// Effort weights for capacity planning
+export const EFFORT_WEIGHTS = {
+    xs: 1,
+    s: 2,
+    m: 4,
+    l: 8,
+    xl: 16,
+};
+// Default lock duration by effort size (in minutes)
+// Used when no explicit lockDurationMinutes is provided to claimTask
+export const LOCK_DURATION_BY_EFFORT = {
+    xs: 15, // Extra small: 15 minutes
+    s: 30, // Small: 30 minutes (default)
+    m: 60, // Medium: 1 hour
+    l: 120, // Large: 2 hours
+    xl: 240, // Extra large: 4 hours
+};
+// Configuration: Default capacity budget in effort units
+// 20 units allows: 20 xs tasks OR 1 xl + 1 m task OR 5 m tasks, etc.
+export 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 async function getActiveTaskCount(userId, projectId, epicId) {
     // Get all in_progress tasks
@@ -105,10 +125,15 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
     });
     let inProgressCount = 0;
     let claimedCount = 0;
+    let effortLoad = 0;
     if (inProgressResult.success && inProgressResult.data.length > 0) {
         const now = new Date();
         for (const task of inProgressResult.data) {
             inProgressCount++;
+            // Calculate effort weight (default to 'm' = 4 units if not specified)
+            const effort = task.estimated_effort || 'm';
+            const weight = EFFORT_WEIGHTS[effort] || EFFORT_WEIGHTS.m;
+            effortLoad += weight;
             // 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);
@@ -122,6 +147,7 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
         inProgress: inProgressCount,
         claimed: claimedCount,
         total: inProgressCount,
+        effortLoad,
     };
 }
 /**
@@ -130,13 +156,13 @@ export async function getActiveTaskCount(userId, projectId, epicId) {
  * - 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 async function getDispatchableTasks(userId, projectId, epicId, maxParallel = DEFAULT_MAX_PARALLEL) {
-    // Get current active task count
+export async function getDispatchableTasks(userId, projectId, epicId, capacityBudget = DEFAULT_CAPACITY_BUDGET) {
+    // Get current active task effort load
     const activeCount = await getActiveTaskCount(userId, projectId, epicId);
-    // Calculate remaining capacity
-    const remainingCapacity = maxParallel - activeCount.total;
+    // Calculate remaining effort capacity
+    let remainingCapacity = capacityBudget - activeCount.effortLoad;
     if (remainingCapacity <= 0) {
         // No capacity available, return empty array
         return [];
@@ -178,6 +204,13 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
                 continue; // Still blocked
             }
         }
+        // Calculate task effort weight
+        const effort = task.estimated_effort || 'm';
+        const taskEffort = EFFORT_WEIGHTS[effort] || EFFORT_WEIGHTS.m;
+        // Check if this task fits within remaining capacity
+        if (taskEffort > remainingCapacity) {
+            continue; // Task too large for remaining capacity
+        }
         // Match to expert worker
         const worker = matchTaskToWorker({
             title: task.title,
@@ -185,6 +218,11 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             domain: task.domain || undefined,
             tags: parseJsonArray(task.tags),
         });
+        // Circuit breaker check: skip if worker circuit is open
+        if (isCircuitOpen(worker.id)) {
+            console.warn(`[Circuit Breaker] Skipping task ${task.id} - circuit OPEN for worker type: ${worker.id}`);
+            continue; // Skip this task
+        }
         // Get task context
         const fullTask = await getTask(userId, projectId, task.id, true);
         const taskData = fullTask.data;
@@ -195,13 +233,48 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             parentContext: taskData.parent,
             dependencies: [],
         });
-        // Only dispatch tasks that fit within remaining capacity
-        if (dispatchable.length >= remainingCapacity) {
+        // Reduce remaining capacity by the effort of this task
+        remainingCapacity -= taskEffort;
+        // Stop if no capacity remains
+        if (remainingCapacity <= 0) {
             break;
         }
     }
+    // Sort by priority: critical → high → medium → low
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    dispatchable.sort((a, b) => (priorityOrder[a.task.priority] ?? 2) - (priorityOrder[b.task.priority] ?? 2));
     return dispatchable;
 }
+/**
+ * Check if task lock is about to expire and return warning
+ */
+export function getLockExpiryWarning(lockExpiresAt) {
+    if (!lockExpiresAt) {
+        return { warning: false, minutes_remaining: 0 };
+    }
+    const now = new Date();
+    const expiryTime = new Date(lockExpiresAt);
+    const secondsRemaining = (expiryTime.getTime() - now.getTime()) / 1000;
+    const minutesRemaining = Math.floor(secondsRemaining / 60);
+    // Expired (lock time has passed)
+    if (secondsRemaining <= 0) {
+        return {
+            warning: true,
+            minutes_remaining: 0,
+            message: '🚨 Lock has EXPIRED. Task may be claimed by another agent.',
+        };
+    }
+    // Warn if lock expires within 5 minutes (but not yet expired)
+    if (minutesRemaining <= 5 && minutesRemaining >= 1) {
+        return {
+            warning: true,
+            minutes_remaining: minutesRemaining,
+            message: `⚠️  Lock expires in ${minutesRemaining} minute${minutesRemaining !== 1 ? 's' : ''}. Call task_heartbeat to extend.`,
+        };
+    }
+    // Less than 1 minute but not expired - no warning (edge case)
+    return { warning: false, minutes_remaining: minutesRemaining };
+}
 /**
  * Get full execution context for a worker agent
  */
@@ -251,6 +324,8 @@ export async function getExecutionContext(userId, projectId, taskId) {
             status: s.status,
         })),
     });
+    // Check for lock expiry warning
+    const lockWarning = getLockExpiryWarning(task.lock_expires_at);
     return {
         task,
         worker,
@@ -258,6 +333,7 @@ export async function getExecutionContext(userId, projectId, taskId) {
         context: taskData.context,
         parentTask: taskData.parent,
         siblingTasks,
+        lockWarning,
     };
 }
 /**
@@ -303,6 +379,81 @@ export async function resolveTaskDependencies(userId, projectId, completedTaskId
     }
     return newlyUnblocked;
 }
+/**
+ * Aggregate work_log context from all tasks in an epic
+ * Used by orchestrator to synthesize final results
+ */
+export async function getEpicAggregate(userId, projectId, epicId, includePending = false) {
+    // 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: {
+                id: epic.id,
+                title: epic.title,
+                description: epic.description,
+                status: epic.status,
+            },
+            tasks: [],
+            summary_stats: {
+                total: 0,
+                completed: 0,
+                in_progress: 0,
+                pending: 0,
+            },
+        };
+    }
+    const allTasks = tasksResult.data;
+    // Get work_log context for each task
+    const tasksWithLogs = await Promise.all(allTasks.map(async (task) => {
+        // Get full task data to access context
+        const fullTaskResult = await getTask(userId, projectId, task.id, true);
+        const fullTaskData = fullTaskResult.data;
+        // Find work_log context
+        const workLogContext = fullTaskData.context?.find(ctx => ctx.context_type === 'work_log');
+        return {
+            id: task.id,
+            title: task.title,
+            status: task.status,
+            work_log: workLogContext?.content || null,
+            completed_at: task.completed_at,
+        };
+    }));
+    // Filter based on includePending
+    const filteredTasks = includePending
+        ? tasksWithLogs
+        : tasksWithLogs.filter(t => t.status === 'done' || t.status === 'in_progress');
+    // Calculate stats
+    const stats = {
+        total: allTasks.length,
+        completed: allTasks.filter(t => t.status === 'done').length,
+        in_progress: allTasks.filter(t => t.status === 'in_progress').length,
+        pending: allTasks.filter(t => t.status === 'ready' || t.status === 'backlog').length,
+    };
+    return {
+        epic: {
+            id: epic.id,
+            title: epic.title,
+            description: epic.description,
+            status: epic.status,
+        },
+        tasks: filteredTasks,
+        summary_stats: stats,
+    };
+}
 /**
  * Get epic status with progress tracking
  * Auto-completes epic if all child tasks are done
@@ -368,3 +519,97 @@ export async function getEpicStatus(userId, projectId, epicId) {
         autoCompleted,
     };
 }
+export async function handoffTask(userId, projectId, taskId, agentId, newWorkerType, reason) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/handoff`, 'POST', {
+        agent_id: agentId,
+        new_worker_type: newWorkerType,
+        reason,
+    });
+}
+/**
+ * Revise an existing epic by adding/removing/updating tasks
+ * Enables iterative planning without recreating the entire epic
+ */
+export async function reviseEpic(userId, projectId, epicId, changes) {
+    // Verify epic exists and is not done
+    const epicResult = await getTask(userId, projectId, epicId);
+    if (!epicResult.success) {
+        throw new Error(`Epic not found: ${epicId}`);
+    }
+    const epic = epicResult.data;
+    if (epic.type !== 'epic') {
+        throw new Error(`Task ${epicId} is not an epic (type: ${epic.type})`);
+    }
+    if (epic.status === 'done') {
+        throw new Error(`Cannot revise completed epic: ${epicId}`);
+    }
+    const added = [];
+    const removed = [];
+    const updated = [];
+    // Add new tasks
+    if (changes.add_tasks && changes.add_tasks.length > 0) {
+        for (const taskDef of changes.add_tasks) {
+            const taskResult = await createTask(userId, projectId, {
+                type: 'task',
+                title: taskDef.title,
+                description: taskDef.description,
+                parent_id: epicId,
+                priority: epic.priority,
+                estimated_effort: taskDef.effort,
+                blocked_by: taskDef.blocked_by,
+                domain: taskDef.domain,
+            });
+            added.push(taskResult.data);
+        }
+    }
+    // Remove tasks (set to cancelled status)
+    if (changes.remove_task_ids && changes.remove_task_ids.length > 0) {
+        for (const taskId of changes.remove_task_ids) {
+            try {
+                await updateTaskStatus(userId, projectId, taskId, 'cancelled', 'system:epic-revision');
+                removed.push(taskId);
+            }
+            catch (error) {
+                // Log but continue - task may not exist
+                console.warn(`Failed to cancel task ${taskId}:`, error);
+            }
+        }
+    }
+    // Update existing tasks
+    // Note: The API doesn't support PATCH for tasks, so we can only update status
+    // For title/description/effort updates, we'll need to add context explaining the change
+    if (changes.update_tasks && changes.update_tasks.length > 0) {
+        for (const update of changes.update_tasks) {
+            try {
+                const taskResult = await getTask(userId, projectId, update.task_id);
+                if (!taskResult.success)
+                    continue;
+                const task = taskResult.data;
+                // Add context about the updates since we can't modify fields directly
+                const updates = [];
+                if (update.title && update.title !== task.title) {
+                    updates.push(`Title updated: "${task.title}" → "${update.title}"`);
+                }
+                if (update.description && update.description !== task.description) {
+                    updates.push(`Description updated: "${update.description}"`);
+                }
+                if (update.effort && update.effort !== task.estimated_effort) {
+                    updates.push(`Effort updated: ${task.estimated_effort || 'unset'} → ${update.effort}`);
+                }
+                if (updates.length > 0) {
+                    await addTaskContext(userId, projectId, update.task_id, 'decision', updates.join('\n'), 'task_plan_revise', 'epic-revision');
+                    updated.push(task);
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to update task ${update.task_id}:`, error);
+            }
+        }
+    }
+    return {
+        epic,
+        added,
+        removed,
+        updated,
+    };
+}

package/dist/helpers/usage-analytics.js

@@ -29,7 +29,7 @@ export class UsageAnalytics {
             const userId = DEFAULT_USER_ID;
             const projectId = event.projectId || resolveProjectId();
             // Store as fact in memory system
-            await storeFact(projectId, 'CodeDNA', 'GENERATION_COMPLETED', event.generator || event.operation, JSON.stringify(usageEvent), userId);
+            await storeFact(projectId, 'CodeDNA', 'GENERATION_COMPLETED', event.generator || event.operation, JSON.stringify(usageEvent), { userId });
             console.log('[CodeDNA Analytics]', {
                 operation: event.operation,
                 generator: event.generator,

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { handleStopHook, sessionStore, usageEstimator } from './stop.js';
+export type { StopHookInput, SessionData, ContextHealth } from './stop.js';
+export { handlePostToolUseHook, sessionStore as postToolUseSessionStore, evictionEngine, } from './post-tool-use.js';
+export type { PostToolUseInput, SessionData as PostToolUseSessionData, EvictionTrigger, } from './post-tool-use.js';

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+// =============================================================================
+// Claude Code Hooks - Index
+// =============================================================================
+// Exports hook handlers for Claude Code integration
+export { handleStopHook, sessionStore, usageEstimator } from './stop.js';
+export { handlePostToolUseHook, sessionStore as postToolUseSessionStore, evictionEngine, } from './post-tool-use.js';

package/dist/hooks/post-tool-use-hook-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/hooks/post-tool-use-hook-cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// =============================================================================
+// Post-Tool-Use Hook CLI Entry Point
+// =============================================================================
+// Called by Claude Code when PostToolUse event occurs
+// Reads hook input from stdin, processes it, and outputs to stdout/stderr
+import { handlePostToolUseHook } from './post-tool-use.js';
+async function main() {
+    try {
+        // Read JSON input from stdin
+        let inputData = '';
+        // Set up stdin reading
+        process.stdin.setEncoding('utf8');
+        for await (const chunk of process.stdin) {
+            inputData += chunk;
+        }
+        // Parse hook input
+        const hookInput = JSON.parse(inputData);
+        // Validate hook event
+        if (hookInput.hook_event_name !== 'PostToolUse') {
+            console.error(`Error: Expected PostToolUse event, got ${hookInput.hook_event_name}`);
+            process.exit(1);
+        }
+        // Process the hook
+        await handlePostToolUseHook(hookInput);
+        // Success - exit code 0
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error processing PostToolUse hook:', error);
+        process.exit(1);
+    }
+}
+main();

package/dist/hooks/post-tool-use.d.ts

@@ -0,0 +1,67 @@
+interface PostToolUseInput {
+    session_id?: string;
+    hook_event_name: 'PostToolUse';
+    tool_name: string;
+    tool_input?: Record<string, unknown>;
+    tool_output?: string;
+    post_tool_use_active?: boolean;
+}
+interface EvictionTrigger {
+    triggered: boolean;
+    level: 'none' | 'standard' | 'emergency';
+    estimated_fill: number;
+    message: string;
+}
+interface SessionData {
+    session_id: string;
+    tool_executions: number;
+    estimated_tokens: number;
+    context_limit: number;
+    estimated_fill: number;
+    last_updated: Date;
+    tool_output_tokens: number;
+}
+declare class SessionStore {
+    /**
+     * Get or create session data
+     */
+    getSession(sessionId: string): SessionData;
+    /**
+     * Update session with tool output tokens
+     */
+    updateSession(sessionId: string, outputTokens: number): SessionData;
+    /**
+     * Clear session (for cleanup)
+     */
+    clearSession(sessionId: string): void;
+    /**
+     * Get all sessions (for debugging)
+     */
+    getAllSessions(): SessionData[];
+}
+declare const sessionStore: SessionStore;
+declare class EvictionTriggerEngine {
+    /**
+     * Check if eviction should be triggered based on fill percentage
+     */
+    checkEvictionTrigger(session: SessionData): EvictionTrigger;
+    /**
+     * Run standard eviction cycle
+     * NOTE: This is a placeholder - actual implementation would call into
+     * the context rotation/eviction system when it's built
+     */
+    runStandardEviction(session: SessionData): Promise<void>;
+    /**
+     * Run emergency eviction cycle
+     * More aggressive eviction for critical situations
+     */
+    runEmergencyEviction(session: SessionData): Promise<void>;
+}
+declare const evictionEngine: EvictionTriggerEngine;
+/**
+ * Handle PostToolUse hook event
+ * Updates session state with tool output and triggers eviction if needed
+ */
+export declare function handlePostToolUseHook(input: PostToolUseInput): Promise<void>;
+export { sessionStore, evictionEngine };
+export type { PostToolUseInput, SessionData, EvictionTrigger };