@claudetools/tools 0.8.2 → 0.8.4

package/dist/helpers/engagement-tracker.js

@@ -0,0 +1,61 @@
+// =============================================================================
+// Engagement Tracking Helper
+// =============================================================================
+// Tracks memory engagement events to the API for persistence
+// =============================================================================
+import { mcpLogger } from '../logger.js';
+import { API_BASE_URL } from './config.js';
+/**
+ * Track an engagement event via the API
+ * This persists the event to D1 for analytics
+ */
+export async function trackEngagementEvent(sessionId, projectId, eventType) {
+    try {
+        // Get API key from environment
+        const apiKey = process.env.CLAUDETOOLS_API_KEY;
+        if (!apiKey) {
+            mcpLogger.debug('API', 'No API key - skipping engagement tracking');
+            return;
+        }
+        const response = await fetch(`${API_BASE_URL}/api/v1/engagement/track`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                session_id: sessionId,
+                project_id: projectId,
+                event_type: eventType,
+            }),
+        });
+        if (!response.ok) {
+            mcpLogger.warn('API', `Failed to track engagement event: ${response.status}`);
+            return;
+        }
+        mcpLogger.debug('API', `Tracked ${eventType} event for session ${sessionId}`);
+    }
+    catch (error) {
+        // Don't fail the main operation if tracking fails
+        mcpLogger.debug('API', `Failed to track engagement event: ${error}`);
+    }
+}
+/**
+ * Get current session ID
+ * This should ideally come from Claude Code's session system
+ * For now, we'll use a simple timestamp-based session ID
+ */
+let currentSessionId = null;
+export function getSessionId() {
+    if (!currentSessionId) {
+        // Generate session ID: session_<timestamp>
+        currentSessionId = `session_${Date.now()}`;
+    }
+    return currentSessionId;
+}
+/**
+ * Reset session ID (for testing or explicit session boundaries)
+ */
+export function resetSessionId() {
+    currentSessionId = null;
+}

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/session-validation.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Record a tool call in the session
+ */
+export declare function recordToolCall(name: string, args?: Record<string, unknown>): void;
+/**
+ * Validate that memory_search was called before task_start
+ * Returns validation result with warnings if violated
+ */
+export declare function validateTaskStartSequence(taskId: string): {
+    valid: boolean;
+    warnings: string[];
+};
+/**
+ * Validate that codebase_map was called before code modification tools
+ * Code modification tools: codedna_generate_*, or any task involving file changes
+ */
+export declare function validateCodebaseMapSequence(): {
+    valid: boolean;
+    warnings: string[];
+};
+/**
+ * Check if a tool name indicates code modification
+ */
+export declare function isCodeModificationTool(toolName: string): boolean;
+/**
+ * Record when auto-injected context is used
+ * This tracks the +20 point event when context is automatically provided
+ */
+export declare function recordContextReference(projectId?: string): void;
+/**
+ * Calculate engagement score (0-100)
+ * - memory_search: +30
+ * - memory_detail: +20
+ * - memory_inject: +20
+ * - memory_store_fact: +10
+ * - context_referenced: +20
+ */
+export declare function calculateEngagementScore(): number;
+/**
+ * Get engagement statistics
+ */
+export declare function getEngagementStats(): {
+    score: number;
+    breakdown: {
+        searchCount: number;
+        searchPoints: number;
+        detailCount: number;
+        detailPoints: number;
+        injectCount: number;
+        injectPoints: number;
+        storeFactCount: number;
+        storeFactPoints: number;
+        contextReferencedCount: number;
+        contextReferencedPoints: number;
+    };
+};
+/**
+ * Get session statistics for debugging
+ */
+export declare function getSessionStats(): {
+    totalCalls: number;
+    uniqueTaskStarts: number;
+    uniqueSearches: number;
+    codebaseMapCalled: boolean;
+    recentCalls: string[];
+    engagement: ReturnType<typeof getEngagementStats>;
+};
+/**
+ * Clear session state (for testing or manual reset)
+ */
+export declare function clearSessionState(): void;
+/**
+ * Get formatted warnings for tool execution
+ * Returns null if no warnings
+ */
+export declare function getToolCallWarnings(toolName: string, args?: Record<string, unknown>): string | null;

package/dist/helpers/session-validation.js

@@ -0,0 +1,221 @@
+// =============================================================================
+// Session-level Tool Call Validation
+// =============================================================================
+// Tracks tool call sequences within a session to enforce best practices:
+// - memory_search before task_start
+// - codebase_map before code modifications
+// - No code in task descriptions (enforced via validateTaskDescription)
+import { mcpLogger } from '../logger.js';
+import { trackEngagementEvent, getSessionId } from './engagement-tracker.js';
+const sessionState = {
+    toolCalls: [],
+    taskStarts: new Set(),
+    memorySearches: new Set(),
+    codebaseMapCalled: false,
+    engagement: {
+        searchCount: 0,
+        detailCount: 0,
+        injectCount: 0,
+        storeFactCount: 0,
+        contextReferencedCount: 0,
+    },
+};
+/**
+ * Record a tool call in the session
+ */
+export function recordToolCall(name, args) {
+    sessionState.toolCalls.push({
+        name,
+        timestamp: Date.now(),
+        args,
+    });
+    // Track specific tool types
+    if (name === 'task_start' && args?.task_id) {
+        sessionState.taskStarts.add(args.task_id);
+    }
+    if (name === 'memory_search' && args?.query) {
+        sessionState.memorySearches.add(args.query);
+    }
+    if (name === 'codebase_map') {
+        sessionState.codebaseMapCalled = true;
+    }
+    // Track engagement and persist to API
+    const projectId = args?.project_id;
+    let eventType;
+    switch (name) {
+        case 'memory_search':
+            sessionState.engagement.searchCount++;
+            eventType = 'search';
+            break;
+        case 'memory_detail':
+            sessionState.engagement.detailCount++;
+            eventType = 'detail';
+            break;
+        case 'memory_inject':
+            sessionState.engagement.injectCount++;
+            eventType = 'inject';
+            break;
+        case 'memory_store_fact':
+            sessionState.engagement.storeFactCount++;
+            eventType = 'store_fact';
+            break;
+    }
+    // Track to API if this is a memory tool
+    if (eventType && projectId) {
+        trackEngagementEvent(getSessionId(), projectId, eventType).catch(() => {
+            // Silently fail - don't block the tool call
+        });
+    }
+    mcpLogger.debug('TOOL', `Recorded tool call: ${name}`);
+}
+/**
+ * Validate that memory_search was called before task_start
+ * Returns validation result with warnings if violated
+ */
+export function validateTaskStartSequence(taskId) {
+    const warnings = [];
+    // Check if any memory_search happened in this session
+    if (sessionState.memorySearches.size === 0) {
+        warnings.push('BEST PRACTICE: Call memory_search() before task_start() to recall relevant context and past decisions.');
+    }
+    // Check recent tool calls (last 10 calls)
+    const recentCalls = sessionState.toolCalls.slice(-10).map(c => c.name);
+    const hasRecentMemorySearch = recentCalls.includes('memory_search');
+    if (!hasRecentMemorySearch && sessionState.memorySearches.size > 0) {
+        warnings.push('RECOMMENDATION: Consider calling memory_search() to check for updated context since your last search.');
+    }
+    return {
+        valid: warnings.length === 0,
+        warnings,
+    };
+}
+/**
+ * Validate that codebase_map was called before code modification tools
+ * Code modification tools: codedna_generate_*, or any task involving file changes
+ */
+export function validateCodebaseMapSequence() {
+    const warnings = [];
+    if (!sessionState.codebaseMapCalled) {
+        warnings.push('BEST PRACTICE: Call codebase_map() before making code changes to understand project structure and prevent conflicts.');
+    }
+    return {
+        valid: warnings.length === 0,
+        warnings,
+    };
+}
+/**
+ * Check if a tool name indicates code modification
+ */
+export function isCodeModificationTool(toolName) {
+    const codeTools = [
+        'codedna_generate_api',
+        'codedna_generate_frontend',
+        'codedna_generate_component',
+        'task_start', // Tasks often involve code changes
+    ];
+    return codeTools.includes(toolName);
+}
+/**
+ * Record when auto-injected context is used
+ * This tracks the +20 point event when context is automatically provided
+ */
+export function recordContextReference(projectId) {
+    sessionState.engagement.contextReferencedCount++;
+    // Track to API if project ID is available
+    if (projectId) {
+        trackEngagementEvent(getSessionId(), projectId, 'context_referenced').catch(() => {
+            // Silently fail - don't block the resource read
+        });
+    }
+    mcpLogger.debug('TOOL', 'Recorded context reference (auto-inject)');
+}
+/**
+ * Calculate engagement score (0-100)
+ * - memory_search: +30
+ * - memory_detail: +20
+ * - memory_inject: +20
+ * - memory_store_fact: +10
+ * - context_referenced: +20
+ */
+export function calculateEngagementScore() {
+    const { searchCount, detailCount, injectCount, storeFactCount, contextReferencedCount } = sessionState.engagement;
+    const rawScore = searchCount * 30 +
+        detailCount * 20 +
+        injectCount * 20 +
+        storeFactCount * 10 +
+        contextReferencedCount * 20;
+    // Cap at 100
+    return Math.min(rawScore, 100);
+}
+/**
+ * Get engagement statistics
+ */
+export function getEngagementStats() {
+    const { searchCount, detailCount, injectCount, storeFactCount, contextReferencedCount } = sessionState.engagement;
+    return {
+        score: calculateEngagementScore(),
+        breakdown: {
+            searchCount,
+            searchPoints: searchCount * 30,
+            detailCount,
+            detailPoints: detailCount * 20,
+            injectCount,
+            injectPoints: injectCount * 20,
+            storeFactCount,
+            storeFactPoints: storeFactCount * 10,
+            contextReferencedCount,
+            contextReferencedPoints: contextReferencedCount * 20,
+        },
+    };
+}
+/**
+ * Get session statistics for debugging
+ */
+export function getSessionStats() {
+    return {
+        totalCalls: sessionState.toolCalls.length,
+        uniqueTaskStarts: sessionState.taskStarts.size,
+        uniqueSearches: sessionState.memorySearches.size,
+        codebaseMapCalled: sessionState.codebaseMapCalled,
+        recentCalls: sessionState.toolCalls.slice(-10).map(c => c.name),
+        engagement: getEngagementStats(),
+    };
+}
+/**
+ * Clear session state (for testing or manual reset)
+ */
+export function clearSessionState() {
+    sessionState.toolCalls = [];
+    sessionState.taskStarts.clear();
+    sessionState.memorySearches.clear();
+    sessionState.codebaseMapCalled = false;
+    sessionState.engagement = {
+        searchCount: 0,
+        detailCount: 0,
+        injectCount: 0,
+        storeFactCount: 0,
+        contextReferencedCount: 0,
+    };
+    mcpLogger.debug('TOOL', 'Session state cleared');
+}
+/**
+ * Get formatted warnings for tool execution
+ * Returns null if no warnings
+ */
+export function getToolCallWarnings(toolName, args) {
+    const warnings = [];
+    // Validate task_start sequence
+    if (toolName === 'task_start' && args?.task_id) {
+        const validation = validateTaskStartSequence(args.task_id);
+        warnings.push(...validation.warnings);
+    }
+    // Validate codebase_map before code changes
+    if (isCodeModificationTool(toolName)) {
+        const validation = validateCodebaseMapSequence();
+        warnings.push(...validation.warnings);
+    }
+    if (warnings.length === 0) {
+        return null;
+    }
+    return `\n⚠️  WORKFLOW RECOMMENDATIONS:\n${warnings.map(w => `  - ${w}`).join('\n')}\n`;
+}

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