@claudetools/tools 0.8.3 → 0.8.5

package/dist/context-cli.js

@@ -0,0 +1,309 @@
+// =============================================================================
+// Context Management CLI Commands
+// =============================================================================
+// CLI interface for context window management: status, evict, summarise, reset
+import chalk from 'chalk';
+import ora from 'ora';
+import prompts from 'prompts';
+import { getSessionStore } from './context/session-store.js';
+import { createEvictionEngine } from './context/eviction-engine.js';
+import { createExchangeSummariser } from './context/exchange-summariser.js';
+// -----------------------------------------------------------------------------
+// Utility Functions
+// -----------------------------------------------------------------------------
+function success(msg) {
+    console.log(chalk.green('✓ ') + msg);
+}
+function error(msg) {
+    console.log(chalk.red('✗ ') + msg);
+}
+function info(msg) {
+    console.log(chalk.blue('ℹ ') + msg);
+}
+function warn(msg) {
+    console.log(chalk.yellow('⚠ ') + msg);
+}
+function header(title) {
+    console.log('\n' + chalk.cyan('━'.repeat(50)));
+    console.log(chalk.cyan.bold(title));
+    console.log(chalk.cyan('━'.repeat(50)) + '\n');
+}
+/**
+ * Get session ID from args or prompt user to select
+ */
+async function getSessionId(args) {
+    // Check if session ID provided as argument
+    const sessionIdArg = args.find((arg) => arg.startsWith('--session='));
+    if (sessionIdArg) {
+        return sessionIdArg.split('=')[1];
+    }
+    // List available sessions
+    const store = getSessionStore();
+    const sessions = await store.listSessions();
+    if (sessions.length === 0) {
+        error('No active sessions found');
+        return null;
+    }
+    // If only one session, use it
+    if (sessions.length === 1) {
+        return sessions[0].session_id;
+    }
+    // Prompt user to select
+    const choices = sessions.map((s) => ({
+        title: `${s.session_id} (${s.model}, started ${s.started_at.toLocaleString()})`,
+        value: s.session_id,
+    }));
+    const response = await prompts({
+        type: 'select',
+        name: 'sessionId',
+        message: 'Select a session:',
+        choices,
+    });
+    return response.sessionId || null;
+}
+/**
+ * Format fill percentage with colour coding
+ */
+function formatFill(fill) {
+    const percentage = (fill * 100).toFixed(1);
+    if (fill < 0.5) {
+        return chalk.green(`${percentage}%`);
+    }
+    else if (fill < 0.7) {
+        return chalk.yellow(`${percentage}%`);
+    }
+    else {
+        return chalk.red(`${percentage}%`);
+    }
+}
+/**
+ * Format session summary
+ */
+function formatSessionSummary(session) {
+    console.log(chalk.bold('Session ID:'), session.session_id);
+    console.log(chalk.bold('Model:'), session.model);
+    console.log(chalk.bold('Started:'), session.started_at.toLocaleString());
+    console.log(chalk.bold('Context Limit:'), session.context_limit.toLocaleString(), 'tokens');
+    console.log(chalk.bold('Estimated Fill:'), formatFill(session.estimated_fill));
+    console.log(chalk.bold('Used Tokens:'), Math.round(session.estimated_fill * session.context_limit).toLocaleString());
+    console.log(chalk.bold('Injected Facts:'), session.injected_facts.length);
+    console.log(chalk.bold('Exchanges:'), session.exchanges.length);
+    // Show exchange summary
+    const summarisedCount = session.exchanges.filter((ex) => ex.summarised_at).length;
+    if (summarisedCount > 0) {
+        console.log(chalk.bold('Summarised Exchanges:'), summarisedCount);
+    }
+    console.log(chalk.bold('Last Updated:'), session.last_updated.toLocaleString());
+}
+// -----------------------------------------------------------------------------
+// Commands
+// -----------------------------------------------------------------------------
+/**
+ * claudetools context status - Show current session context usage
+ */
+export async function contextStatus(args) {
+    header('Context Status');
+    const sessionId = await getSessionId(args);
+    if (!sessionId) {
+        process.exit(1);
+    }
+    const spinner = ora('Loading session state...').start();
+    try {
+        const store = getSessionStore();
+        const session = await store.getSession(sessionId);
+        if (!session) {
+            spinner.fail('Session not found');
+            process.exit(1);
+        }
+        spinner.succeed('Session loaded');
+        console.log();
+        formatSessionSummary(session);
+        // Show warnings
+        console.log();
+        if (session.estimated_fill > 0.85) {
+            warn('Critical: Context window is near full (>85%). Emergency eviction may be triggered.');
+        }
+        else if (session.estimated_fill > 0.6) {
+            warn('Warning: Context window is filling up (>60%). Consider running eviction.');
+        }
+        else {
+            success('Context window is healthy.');
+        }
+        // Show eviction eligibility
+        const engine = createEvictionEngine();
+        if (engine.shouldEvict(session)) {
+            console.log();
+            info('Automatic eviction will be triggered at next opportunity.');
+        }
+    }
+    catch (err) {
+        spinner.fail('Failed to load session');
+        throw err;
+    }
+}
+/**
+ * claudetools context evict - Manually trigger eviction cycle
+ */
+export async function contextEvict(args) {
+    header('Context Eviction');
+    const sessionId = await getSessionId(args);
+    if (!sessionId) {
+        process.exit(1);
+    }
+    const spinner = ora('Loading session state...').start();
+    try {
+        const store = getSessionStore();
+        const session = await store.getSession(sessionId);
+        if (!session) {
+            spinner.fail('Session not found');
+            process.exit(1);
+        }
+        spinner.text = 'Analysing session...';
+        // Check if eviction is needed
+        const engine = createEvictionEngine();
+        if (!engine.shouldEvict(session)) {
+            spinner.info(`No eviction needed (fill: ${formatFill(session.estimated_fill)})`);
+            return;
+        }
+        // Get eviction plan
+        const plan = engine.getEvictionPlan(session);
+        spinner.stop();
+        console.log();
+        console.log(chalk.bold('Eviction Plan:'));
+        console.log(chalk.bold('Facts to evict:'), plan.factsToEvict.length);
+        console.log(chalk.bold('Current fill:'), formatFill(session.estimated_fill));
+        console.log(chalk.bold('Expected fill after:'), formatFill(plan.expectedFillAfter));
+        if (plan.includesCritical) {
+            warn('Plan includes evicting CRITICAL facts (fill >85%)');
+        }
+        // Confirm before proceeding
+        const confirm = await prompts({
+            type: 'confirm',
+            name: 'proceed',
+            message: 'Proceed with eviction?',
+            initial: true,
+        });
+        if (!confirm.proceed) {
+            info('Eviction cancelled');
+            return;
+        }
+        spinner.start('Evicting facts...');
+        // Execute eviction
+        const result = await engine.runEviction(session);
+        spinner.succeed('Eviction complete');
+        console.log();
+        console.log(chalk.bold('Evicted:'), result.evictedCount, 'facts');
+        console.log(chalk.bold('New fill:'), formatFill(result.newEstimatedFill));
+        // Update session in store
+        await store.updateSession(sessionId, { estimated_fill: result.newEstimatedFill });
+        success(`Context window reduced from ${formatFill(session.estimated_fill)} to ${formatFill(result.newEstimatedFill)}`);
+    }
+    catch (err) {
+        spinner.fail('Eviction failed');
+        throw err;
+    }
+}
+/**
+ * claudetools context summarise - Summarise and compress exchanges
+ */
+export async function contextSummarise(args) {
+    header('Exchange Summarisation');
+    const sessionId = await getSessionId(args);
+    if (!sessionId) {
+        process.exit(1);
+    }
+    const spinner = ora('Loading session state...').start();
+    try {
+        const store = getSessionStore();
+        const session = await store.getSession(sessionId);
+        if (!session) {
+            spinner.fail('Session not found');
+            process.exit(1);
+        }
+        spinner.text = 'Analysing exchanges...';
+        // Check if summarisation is needed
+        const summariser = createExchangeSummariser();
+        if (!summariser.shouldSummarise(session)) {
+            spinner.info('No exchanges need summarisation (< 10 unsummarised)');
+            return;
+        }
+        spinner.stop();
+        console.log();
+        const unsummarised = session.exchanges.filter((ex) => !ex.summarised_at);
+        console.log(chalk.bold('Unsummarised exchanges:'), unsummarised.length);
+        console.log(chalk.bold('Total exchanges:'), session.exchanges.length);
+        // Confirm before proceeding
+        const confirm = await prompts({
+            type: 'confirm',
+            name: 'proceed',
+            message: 'Proceed with summarisation?',
+            initial: true,
+        });
+        if (!confirm.proceed) {
+            info('Summarisation cancelled');
+            return;
+        }
+        spinner.start('Summarising exchanges...');
+        // Execute summarisation
+        const result = await summariser.summariseOldExchanges(session);
+        spinner.succeed('Summarisation complete');
+        console.log();
+        console.log(chalk.bold('Summarised:'), result.summarisedCount, 'exchanges');
+        console.log(chalk.bold('Tokens saved:'), result.tokensSaved.toLocaleString());
+        // Mark exchanges as summarised in store
+        for (let i = 0; i < result.summarisedCount; i++) {
+            await store.markExchangeSummarised(sessionId, i);
+        }
+        success(`Compressed ${result.summarisedCount} exchanges, saved ~${result.tokensSaved} tokens`);
+    }
+    catch (err) {
+        spinner.fail('Summarisation failed');
+        throw err;
+    }
+}
+/**
+ * claudetools context reset - Clear session state
+ */
+export async function contextReset(args) {
+    header('Context Reset');
+    const sessionId = await getSessionId(args);
+    if (!sessionId) {
+        process.exit(1);
+    }
+    const spinner = ora('Loading session state...').start();
+    try {
+        const store = getSessionStore();
+        const session = await store.getSession(sessionId);
+        if (!session) {
+            spinner.fail('Session not found');
+            process.exit(1);
+        }
+        spinner.stop();
+        console.log();
+        formatSessionSummary(session);
+        console.log();
+        warn('This will permanently delete all session data including:');
+        console.log('  - Injected facts');
+        console.log('  - Exchange history');
+        console.log('  - Token usage estimates');
+        // Confirm before proceeding
+        const confirm = await prompts({
+            type: 'confirm',
+            name: 'proceed',
+            message: chalk.red('Are you sure you want to delete this session?'),
+            initial: false,
+        });
+        if (!confirm.proceed) {
+            info('Reset cancelled');
+            return;
+        }
+        spinner.start('Deleting session...');
+        await store.deleteSession(sessionId);
+        spinner.succeed('Session deleted');
+        success('Context state cleared');
+    }
+    catch (err) {
+        spinner.fail('Reset failed');
+        throw err;
+    }
+}

package/dist/handlers/codedna-handlers.d.ts

@@ -369,7 +369,7 @@ export declare function handleInitProject(args: {
     patterns: {
         pattern_id: string;
         name: string;
-        category: "hooks" | "components" | "forms" | "state" | "validation" | "styling" | "anti-patterns";
+        category: "hooks" | "state" | "components" | "forms" | "validation" | "styling" | "anti-patterns";
         description: string;
     }[];
     summary: {

package/dist/handlers/tool-handlers.js

@@ -11,8 +11,8 @@ import { recordToolCall, getToolCallWarnings } from '../helpers/session-validati
 import { queryDependencies, analyzeImpact } from '../helpers/dependencies.js';
 import { checkPatterns } from '../helpers/patterns.js';
 import { formatContextForClaude } from '../helpers/formatter.js';
-import { compactTaskList, compactTaskCreated, compactTaskStart, compactTaskComplete, compactTaskClaim, compactTaskRelease, compactStatusUpdate, compactContextAdded, compactHeartbeat, compactSummary, } from '../helpers/compact-formatter.js';
-import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, getEpicStatus, getActiveTaskCount, } from '../helpers/tasks.js';
+import { shortId, compactTaskList, compactTaskCreated, compactTaskStart, compactTaskComplete, compactTaskClaim, compactTaskRelease, compactStatusUpdate, compactContextAdded, compactHeartbeat, compactTaskHandoff, compactSummary, } from '../helpers/compact-formatter.js';
+import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, handoffTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, getEpicStatus, getEpicAggregate, getActiveTaskCount, reviseEpic, } from '../helpers/tasks.js';
 import { detectTimedOutTasks, retryTask, failTask, autoRetryTimedOutTasks, } from '../helpers/tasks-retry.js';
 import { detectLibrariesFromPlan } from '../helpers/library-detection.js';
 import { handleGenerateApi, handleGenerateFrontend, handleGenerateComponent, handleListGenerators, handleValidateSpec, handleListPatterns, handleGetPattern, handleDetectPatterns, handleInitProject, } from './codedna-handlers.js';
@@ -132,17 +132,89 @@ export function registerToolHandlers(server) {
                     const relationship = args?.relationship;
                     const entity2 = args?.entity2;
                     const context = args?.context;
-                    const result = await storeFact(projectId, entity1, relationship, entity2, context);
+                    const is_critical = args?.is_critical;
+                    // Commercial-grade storage with blocking verification
+                    const MAX_RETRIES = 3;
+                    const VERIFY_DELAY_MS = 200;
+                    let lastError = null;
+                    let storedFactId = null;
+                    let storedIsCritical = false;
+                    let verified = false;
+                    let attempts = 0;
+                    for (let attempt = 1; attempt <= MAX_RETRIES && !verified; attempt++) {
+                        attempts = attempt;
+                        try {
+                            // Step 1: Store the fact
+                            mcpLogger.info('STORE', `Attempt ${attempt}/${MAX_RETRIES}: Storing "${entity1} ${relationship} ${entity2}"${is_critical ? ' [CRITICAL]' : ''}`);
+                            const result = await storeFact(projectId, entity1, relationship, entity2, context, { is_critical });
+                            storedFactId = result.fact_id;
+                            storedIsCritical = result.is_critical;
+                            mcpLogger.info('STORE', `Storage response: ${JSON.stringify(result)}`);
+                            if (!result.success || !result.fact_id) {
+                                lastError = new Error(`Storage returned unsuccessful: ${JSON.stringify(result)}`);
+                                mcpLogger.warn('STORE', `Attempt ${attempt} failed: ${lastError.message}`);
+                                continue;
+                            }
+                            // Step 2: Wait briefly for eventual consistency
+                            await new Promise(resolve => setTimeout(resolve, VERIFY_DELAY_MS));
+                            // Step 3: Verify the fact is retrievable by searching for it
+                            mcpLogger.info('STORE', `Verifying fact ${storedFactId} is retrievable...`);
+                            const searchQuery = `${entity1} ${relationship} ${entity2}`;
+                            const searchResult = await searchMemory(projectId, searchQuery, 5);
+                            // Check if our fact appears in results
+                            const factFound = searchResult.relevant_facts?.some(f => f.fact?.includes(entity1) && f.fact?.includes(entity2)) || false;
+                            if (factFound) {
+                                verified = true;
+                                mcpLogger.info('STORE', `✓ Fact verified as retrievable`);
+                            }
+                            else {
+                                lastError = new Error(`Fact stored but not found in search results`);
+                                mcpLogger.warn('STORE', `Attempt ${attempt}: Stored but not retrievable. Search returned ${searchResult.relevant_facts?.length || 0} facts.`);
+                            }
+                        }
+                        catch (err) {
+                            lastError = err instanceof Error ? err : new Error(String(err));
+                            mcpLogger.error('STORE', `Attempt ${attempt} error: ${lastError.message}`, err);
+                        }
+                    }
                     mcpLogger.memoryStore(entity1, relationship, entity2);
-                    mcpLogger.toolResult(name, true, timer(), `ID: ${result.fact_id}`);
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `Stored fact: "${entity1} ${relationship} ${entity2}" (ID: ${result.fact_id})`,
-                            },
-                        ],
-                    };
+                    const criticalTag = storedIsCritical ? ' 🔴 CRITICAL' : '';
+                    if (verified && storedFactId) {
+                        mcpLogger.toolResult(name, true, timer(), `ID: ${storedFactId} (verified)${criticalTag}`);
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `✓ Stored and verified: "${entity1} ${relationship} ${entity2}" (ID: ${storedFactId})${criticalTag}`,
+                                },
+                            ],
+                        };
+                    }
+                    else if (storedFactId) {
+                        // Stored but couldn't verify - warn but don't fail
+                        mcpLogger.toolResult(name, true, timer(), `ID: ${storedFactId} (unverified)${criticalTag}`);
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `⚠️ Stored but verification pending: "${entity1} ${relationship} ${entity2}" (ID: ${storedFactId})${criticalTag}\nNote: Fact may take a moment to become searchable.`,
+                                },
+                            ],
+                        };
+                    }
+                    else {
+                        // Complete failure after all retries
+                        mcpLogger.toolResult(name, false, timer(), `Failed after ${attempts} attempts`);
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `❌ Failed to store fact after ${attempts} attempts: "${entity1} ${relationship} ${entity2}"\nError: ${lastError?.message || 'Unknown error'}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
                 }
                 case 'memory_get_context': {
                     const query = args?.query;
@@ -755,6 +827,73 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_plan_revise': {
+                    const epicId = args?.epic_id;
+                    const addTasks = args?.add_tasks;
+                    const removeTaskIds = args?.remove_task_ids;
+                    const updateTasks = args?.update_tasks;
+                    try {
+                        const result = await reviseEpic(DEFAULT_USER_ID, projectId, epicId, {
+                            add_tasks: addTasks,
+                            remove_task_ids: removeTaskIds,
+                            update_tasks: updateTasks,
+                        });
+                        mcpLogger.toolResult(name, true, timer(), `Epic ${shortId(epicId)} revised: +${result.added.length} tasks, -${result.removed.length} tasks, ~${result.updated.length} tasks`);
+                        let output = `# Epic Revised: ${result.epic.title}\n\n`;
+                        output += `**Epic ID:** \`${result.epic.id}\`\n`;
+                        output += `**Status:** ${result.epic.status}\n\n`;
+                        if (result.added.length > 0) {
+                            output += `## Added Tasks (${result.added.length})\n\n`;
+                            result.added.forEach((task, i) => {
+                                output += `${i + 1}. **${task.title}** (\`${shortId(task.id)}\`)`;
+                                if (task.estimated_effort)
+                                    output += ` - ${task.estimated_effort}`;
+                                output += `\n`;
+                                if (task.description)
+                                    output += `   ${task.description}\n`;
+                            });
+                            output += '\n';
+                        }
+                        if (result.removed.length > 0) {
+                            output += `## Cancelled Tasks (${result.removed.length})\n\n`;
+                            result.removed.forEach((taskId, i) => {
+                                output += `${i + 1}. \`${shortId(taskId)}\` (cancelled)\n`;
+                            });
+                            output += '\n';
+                        }
+                        if (result.updated.length > 0) {
+                            output += `## Updated Tasks (${result.updated.length})\n\n`;
+                            result.updated.forEach((task, i) => {
+                                output += `${i + 1}. **${task.title}** (\`${shortId(task.id)}\`) - Context added with update details\n`;
+                            });
+                            output += '\n';
+                        }
+                        // Get updated epic status
+                        const epicStatus = await getEpicStatus(DEFAULT_USER_ID, projectId, epicId);
+                        output += `## Current Status\n\n`;
+                        output += `**Total Tasks:** ${epicStatus.totalTasks}\n`;
+                        output += `**Progress:** ${epicStatus.percentComplete}% complete\n`;
+                        output += `**By Status:**\n`;
+                        Object.entries(epicStatus.byStatus).forEach(([status, count]) => {
+                            if (count > 0) {
+                                output += `- ${status}: ${count}\n`;
+                            }
+                        });
+                        return {
+                            content: [{ type: 'text', text: output }],
+                        };
+                    }
+                    catch (error) {
+                        mcpLogger.toolResult(name, false, timer(), error instanceof Error ? error.message : 'Unknown error');
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `Error revising epic: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                                }],
+                            isError: true,
+                        };
+                    }
+                }
                 case 'task_start': {
                     const taskId = args?.task_id;
                     const agentId = args?.agent_id || 'claude-code';
@@ -976,6 +1115,19 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_handoff': {
+                    const taskId = args?.task_id;
+                    const newWorkerType = args?.new_worker_type;
+                    const reason = args?.reason;
+                    const agentId = args?.agent_id || 'claude-code';
+                    const result = await handoffTask(DEFAULT_USER_ID, projectId, taskId, agentId, newWorkerType, reason);
+                    mcpLogger.toolResult(name, true, timer());
+                    // Compact output
+                    const output = compactTaskHandoff(result.data.task, result.data.handed_off, result.data.new_worker_type);
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
                 // =========================================================================
                 // ORCHESTRATION HANDLERS
                 // =========================================================================
@@ -1028,7 +1180,12 @@ export function registerToolHandlers(server) {
                     output += `**Task:** ${context.task.title}\n`;
                     output += `**Task ID:** \`${context.task.id}\`\n`;
                     output += `**Worker Type:** ${context.worker.name} (\`${context.worker.id}\`)\n`;
-                    output += `**Status:** ${context.task.status}\n\n`;
+                    output += `**Status:** ${context.task.status}\n`;
+                    // Display lock expiry warning if present
+                    if (context.lockWarning?.warning && context.lockWarning.message) {
+                        output += `\n${context.lockWarning.message}\n`;
+                    }
+                    output += `\n`;
                     output += `## System Prompt for Worker\n\n`;
                     output += `\`\`\`\n${context.systemPrompt}\`\`\`\n\n`;
                     if (context.parentTask) {
@@ -1152,6 +1309,47 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_aggregate': {
+                    const epicId = args?.epic_id;
+                    const includePending = args?.include_pending || false;
+                    const aggregate = await getEpicAggregate(DEFAULT_USER_ID, projectId, epicId, includePending);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Epic Aggregate: ${aggregate.epic.title}\n\n`;
+                    output += `**Epic ID:** \`${epicId}\`\n`;
+                    output += `**Epic Status:** ${aggregate.epic.status}\n`;
+                    output += `**Description:** ${aggregate.epic.description}\n\n`;
+                    output += `## Summary Statistics\n\n`;
+                    output += `- **Total Tasks:** ${aggregate.summary_stats.total}\n`;
+                    output += `- **Completed:** ${aggregate.summary_stats.completed}\n`;
+                    output += `- **In Progress:** ${aggregate.summary_stats.in_progress}\n`;
+                    output += `- **Pending:** ${aggregate.summary_stats.pending}\n\n`;
+                    output += `## Task Work Logs\n\n`;
+                    if (aggregate.tasks.length === 0) {
+                        output += `No tasks ${includePending ? '' : 'with work logs '}found for this epic.\n`;
+                    }
+                    else {
+                        for (const task of aggregate.tasks) {
+                            const statusEmoji = task.status === 'done' ? '✅' : task.status === 'in_progress' ? '🔄' : '📋';
+                            output += `### ${statusEmoji} ${task.title}\n`;
+                            output += `- **Task ID:** \`${task.id}\`\n`;
+                            output += `- **Status:** ${task.status}\n`;
+                            if (task.completed_at) {
+                                const completedDate = new Date(task.completed_at).toLocaleString();
+                                output += `- **Completed:** ${completedDate}\n`;
+                            }
+                            if (task.work_log) {
+                                output += `- **Work Log:**\n\n`;
+                                output += `  ${task.work_log}\n\n`;
+                            }
+                            else {
+                                output += `- **Work Log:** None\n\n`;
+                            }
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
                 case 'task_detect_timeouts': {
                     const timedOut = await detectTimedOutTasks(DEFAULT_USER_ID, projectId);
                     mcpLogger.toolResult(name, true, timer());
@@ -1206,6 +1404,10 @@ export function registerToolHandlers(server) {
                         if (result.error?.includes('Retry limit exceeded')) {
                             output += `The task has been marked as **failed** permanently.\n`;
                         }
+                        else if (result.retryAfter) {
+                            output += `**Retry After:** ${result.retryAfter}\n`;
+                            output += `The task is in exponential backoff. Please wait before retrying.\n`;
+                        }
                     }
                     return {
                         content: [{ type: 'text', text: output }],

package/dist/helpers/api-client.d.ts

@@ -26,9 +26,13 @@ export declare function addMemory(projectId: string, sessionId: string, messages
     episode_ids: string[];
 }>;
 export declare function searchMemory(projectId: string, query: string, limit?: number, userId?: string): Promise<MemoryContext>;
-export declare function storeFact(projectId: string, entity1: string, relationship: string, entity2: string, context: string, userId?: string): Promise<{
+export declare function storeFact(projectId: string, entity1: string, relationship: string, entity2: string, context: string, options?: {
+    userId?: string;
+    is_critical?: boolean;
+}): Promise<{
     success: boolean;
     fact_id: string;
+    is_critical: boolean;
 }>;
 export declare function getContext(projectId: string, query?: string, userId?: string): Promise<MemoryContext>;
 export declare function getSummary(projectId: string, userId?: string): Promise<string>;

package/dist/helpers/api-client.js

@@ -39,12 +39,14 @@ export async function searchMemory(projectId, query, limit = 10, userId = DEFAUL
         limit,
     });
 }
-export async function storeFact(projectId, entity1, relationship, entity2, context, userId = DEFAULT_USER_ID) {
+export async function storeFact(projectId, entity1, relationship, entity2, context, options = {}) {
+    const userId = options.userId ?? DEFAULT_USER_ID;
     return apiRequest(`/api/v1/memory/${userId}/${projectId}/fact`, 'POST', {
         entity1,
         relationship,
         entity2,
         context,
+        ...(options.is_critical !== undefined && { is_critical: options.is_critical }),
     });
 }
 export async function getContext(projectId, query, userId = DEFAULT_USER_ID) {

package/dist/helpers/circuit-breaker.d.ts

@@ -0,0 +1,28 @@
+export interface CircuitState {
+    failures: number;
+    lastFailure: number;
+    openedAt: number | null;
+}
+/**
+ * Record a worker failure
+ * Increments failure count and potentially opens the circuit
+ */
+export declare function recordWorkerFailure(workerType: string): void;
+/**
+ * Check if circuit is open for a worker type
+ * Auto-closes circuit if cooldown period has elapsed
+ */
+export declare function isCircuitOpen(workerType: string): boolean;
+/**
+ * Get circuit status for all worker types
+ * Useful for monitoring and debugging
+ */
+export declare function getCircuitStatus(): Map<string, CircuitState>;
+/**
+ * Manually reset a circuit (for testing or admin override)
+ */
+export declare function resetCircuit(workerType: string): void;
+/**
+ * Reset all circuits (for testing)
+ */
+export declare function resetAllCircuits(): void;