@claudetools/tools 0.8.3 → 0.8.4

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

@@ -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;

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/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/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 };