@claudetools/tools 0.8.2 → 0.8.3

package/dist/handlers/tool-handlers.js

@@ -7,9 +7,11 @@ import { getDefaultProjectId, DEFAULT_USER_ID, lastContextUsed, setLastContextUs
 import { EXPERT_WORKERS, matchTaskToWorker, buildWorkerPrompt } from '../helpers/workers.js';
 import { validateTaskDescription } from '../templates/orchestrator-prompt.js';
 import { searchMemory, addMemory, storeFact, getContext, getSummary, getEntities, injectContext, apiRequest, listCachedDocs, getCachedDocs, cacheDocs, getMemoryIndex, getMemoryDetail, getDisclosureAnalytics } from '../helpers/api-client.js';
+import { recordToolCall, getToolCallWarnings } from '../helpers/session-validation.js';
 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 { detectTimedOutTasks, retryTask, failTask, autoRetryTimedOutTasks, } from '../helpers/tasks-retry.js';
 import { detectLibrariesFromPlan } from '../helpers/library-detection.js';
@@ -38,6 +40,10 @@ export function registerToolHandlers(server) {
         const timer = mcpLogger.startTimer();
         // Log tool call
         mcpLogger.toolCall(name, args || {});
+        // Record tool call in session for sequence validation
+        recordToolCall(name, args);
+        // Get workflow warnings (if any) for this tool call
+        const workflowWarnings = getToolCallWarnings(name, args);
         try {
             switch (name) {
                 case 'memory_explain': {
@@ -758,30 +764,16 @@ export function registerToolHandlers(server) {
                     await updateTaskStatus(DEFAULT_USER_ID, projectId, taskId, 'in_progress', agentId);
                     mcpLogger.toolResult(name, true, timer());
                     const data = claimResult.data;
-                    let output = `# Starting: ${data.task.title}\n\n`;
-                    output += `**Task ID:** ${taskId}\n`;
-                    output += `**Status:** in_progress\n`;
-                    output += `**Lock expires:** ${data.lock_expires_at}\n\n`;
+                    // Compact output: just essentials
+                    let output = compactTaskStart(data.task, data.lock_expires_at);
                     if (data.task.description) {
-                        output += `## Description\n${data.task.description}\n\n`;
+                        output += `\n${data.task.description}`;
                     }
+                    // Only show criteria if present (compact)
                     const criteria = parseJsonArray(data.task.acceptance_criteria);
                     if (criteria.length) {
-                        output += `## Acceptance Criteria\n`;
-                        criteria.forEach((c, i) => {
-                            output += `${i + 1}. ${c}\n`;
-                        });
-                        output += '\n';
-                    }
-                    if (data.context?.length) {
-                        output += `## Previous Context\n`;
-                        data.context.forEach((c) => {
-                            output += `### ${c.context_type} (${c.added_by})\n`;
-                            output += `${c.content}\n\n`;
-                        });
+                        output += `\nCriteria: ${criteria.join('; ')}`;
                     }
-                    output += `---\n`;
-                    output += `Use \`task_complete\` when done, or \`task_add_context\` to log progress.\n`;
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -798,25 +790,8 @@ export function registerToolHandlers(server) {
                     // Check for newly unblocked tasks (orchestration awareness)
                     const newlyUnblocked = await resolveTaskDependencies(DEFAULT_USER_ID, projectId, taskId, task.parent_id || undefined);
                     mcpLogger.toolResult(name, true, timer());
-                    let output = `# Completed: ${task.title}\n\n`;
-                    output += `**Task ID:** \`${taskId}\`\n`;
-                    output += `**Status:** done ✅\n\n`;
-                    output += `## Summary\n${summary}\n\n`;
-                    // Show newly unblocked tasks for orchestration
-                    if (newlyUnblocked.length > 0) {
-                        output += `---\n\n`;
-                        output += `## 🔓 Newly Unblocked Tasks (${newlyUnblocked.length})\n\n`;
-                        for (const unblocked of newlyUnblocked) {
-                            const worker = matchTaskToWorker({
-                                title: unblocked.title,
-                                description: unblocked.description || undefined,
-                                domain: unblocked.domain || undefined,
-                            });
-                            output += `- **${unblocked.title}** (\`${unblocked.id}\`)\n`;
-                            output += `  → Worker: ${worker.name}\n`;
-                        }
-                        output += `\n**Next:** Use \`task_dispatch\` to spawn parallel workers for unblocked tasks.\n`;
-                    }
+                    // Compact output
+                    const output = compactTaskComplete(task, summary, newlyUnblocked);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -843,24 +818,8 @@ export function registerToolHandlers(server) {
                         blocked_by: blockedBy,
                     });
                     mcpLogger.toolResult(name, true, timer());
-                    const task = result.data;
-                    let output = `# Task Created\n\n`;
-                    output += `**ID:** ${task.id}\n`;
-                    output += `**Type:** ${task.type}\n`;
-                    output += `**Title:** ${task.title}\n`;
-                    output += `**Status:** ${task.status}\n`;
-                    output += `**Priority:** ${task.priority}\n`;
-                    if (task.parent_id)
-                        output += `**Parent:** ${task.parent_id}\n`;
-                    if (task.description)
-                        output += `\n**Description:**\n${task.description}\n`;
-                    const taskCriteria = parseJsonArray(task.acceptance_criteria);
-                    if (taskCriteria.length) {
-                        output += `\n**Acceptance Criteria:**\n`;
-                        taskCriteria.forEach((c, i) => {
-                            output += `${i + 1}. ${c}\n`;
-                        });
-                    }
+                    // Compact output
+                    const output = compactTaskCreated(result.data);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -875,45 +834,8 @@ export function registerToolHandlers(server) {
                     };
                     const result = await listTasks(DEFAULT_USER_ID, projectId, filters);
                     mcpLogger.toolResult(name, true, timer());
-                    const tasks = result.data;
-                    let output = `# Tasks (${tasks.length})\n\n`;
-                    if (tasks.length === 0) {
-                        output += `No tasks found matching the filters.\n`;
-                    }
-                    else {
-                        // Group by type for better organization
-                        const epics = tasks.filter(t => t.type === 'epic');
-                        const regularTasks = tasks.filter(t => t.type === 'task');
-                        const subtasks = tasks.filter(t => t.type === 'subtask');
-                        const formatTask = (t) => {
-                            const statusEmoji = {
-                                backlog: '📋', ready: '🟢', in_progress: '🔄',
-                                blocked: '🚫', review: '👀', done: '✅', cancelled: '❌'
-                            };
-                            const emoji = statusEmoji[t.status] || '📝';
-                            let line = `- ${emoji} **${t.title}** (\`${t.id}\`)`;
-                            line += ` [${t.status}]`;
-                            if (t.priority !== 'medium')
-                                line += ` [${t.priority}]`;
-                            if (t.assigned_to)
-                                line += ` → ${t.assigned_to}`;
-                            return line;
-                        };
-                        if (epics.length > 0) {
-                            output += `## Epics\n`;
-                            epics.forEach(t => { output += formatTask(t) + '\n'; });
-                            output += '\n';
-                        }
-                        if (regularTasks.length > 0) {
-                            output += `## Tasks\n`;
-                            regularTasks.forEach(t => { output += formatTask(t) + '\n'; });
-                            output += '\n';
-                        }
-                        if (subtasks.length > 0) {
-                            output += `## Subtasks\n`;
-                            subtasks.forEach(t => { output += formatTask(t) + '\n'; });
-                        }
-                    }
+                    // Compact output
+                    const output = compactTaskList(result.data);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -987,17 +909,8 @@ export function registerToolHandlers(server) {
                     const result = await claimTask(DEFAULT_USER_ID, projectId, taskId, agentId, lockDuration);
                     mcpLogger.toolResult(name, true, timer());
                     const data = result.data;
-                    let output = `# Task Claimed\n\n`;
-                    output += `**Task:** ${data.task.title}\n`;
-                    output += `**Claimed:** ${data.claimed ? '✅ Yes' : '❌ No'}\n`;
-                    output += `**Lock Expires:** ${data.lock_expires_at}\n`;
-                    output += `**Agent:** ${agentId}\n`;
-                    if (data.context?.length) {
-                        output += `\n## Previous Context\n`;
-                        data.context.forEach(c => {
-                            output += `### ${c.context_type}\n${c.content}\n\n`;
-                        });
-                    }
+                    // Compact output
+                    const output = compactTaskClaim(data.task, data.claimed, data.lock_expires_at);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -1009,13 +922,8 @@ export function registerToolHandlers(server) {
                     const workLog = args?.work_log;
                     const result = await releaseTask(DEFAULT_USER_ID, projectId, taskId, agentId, newStatus, workLog);
                     mcpLogger.toolResult(name, true, timer());
-                    const data = result.data;
-                    let output = `# Task Released\n\n`;
-                    output += `**Task:** ${data.task.title}\n`;
-                    output += `**Released:** ${data.released ? '✅ Yes' : '❌ No'}\n`;
-                    output += `**New Status:** ${data.task.status}\n`;
-                    if (workLog)
-                        output += `**Work Log:** ${workLog}\n`;
+                    // Compact output
+                    const output = compactTaskRelease(result.data.task, result.data.released);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -1026,11 +934,8 @@ export function registerToolHandlers(server) {
                     const agentId = args?.agent_id;
                     const result = await updateTaskStatus(DEFAULT_USER_ID, projectId, taskId, status, agentId);
                     mcpLogger.toolResult(name, true, timer());
-                    const task = result.data;
-                    let output = `# Status Updated\n\n`;
-                    output += `**Task:** ${task.title}\n`;
-                    output += `**New Status:** ${task.status}\n`;
-                    output += `**Updated At:** ${task.updated_at}\n`;
+                    // Compact output
+                    const output = compactStatusUpdate(result.data);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -1043,14 +948,8 @@ export function registerToolHandlers(server) {
                     const source = args?.source;
                     const result = await addTaskContext(DEFAULT_USER_ID, projectId, taskId, contextType, content, addedBy, source);
                     mcpLogger.toolResult(name, true, timer());
-                    const ctx = result.data;
-                    let output = `# Context Added\n\n`;
-                    output += `**ID:** ${ctx.id}\n`;
-                    output += `**Type:** ${ctx.context_type}\n`;
-                    output += `**Added By:** ${ctx.added_by}\n`;
-                    if (ctx.source)
-                        output += `**Source:** ${ctx.source}\n`;
-                    output += `\n**Content:**\n${ctx.content}\n`;
+                    // Compact output
+                    const output = compactContextAdded(result.data);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -1058,29 +957,9 @@ export function registerToolHandlers(server) {
                 case 'task_summary': {
                     const result = await getTaskSummary(DEFAULT_USER_ID, projectId);
                     mcpLogger.toolResult(name, true, timer());
+                    // Compact output
                     const data = result.data;
-                    let output = `# Task Summary\n\n`;
-                    output += `## By Status\n`;
-                    const statusEmoji = {
-                        backlog: '📋', ready: '🟢', in_progress: '🔄',
-                        blocked: '🚫', review: '👀', done: '✅', cancelled: '❌'
-                    };
-                    Object.entries(data.by_status).forEach(([status, count]) => {
-                        const emoji = statusEmoji[status] || '📝';
-                        output += `- ${emoji} ${status}: **${count}**\n`;
-                    });
-                    output += `\n## By Type\n`;
-                    Object.entries(data.by_type).forEach(([type, count]) => {
-                        output += `- ${type}: **${count}**\n`;
-                    });
-                    output += `\n## Active Agents\n`;
-                    output += `**${data.active_agents}** agent(s) currently working on tasks\n`;
-                    if (data.recent_events?.length) {
-                        output += `\n## Recent Activity\n`;
-                        data.recent_events.slice(0, 5).forEach(e => {
-                            output += `- ${e.event_type}: ${e.task_title} (${new Date(e.created_at).toLocaleString()})\n`;
-                        });
-                    }
+                    const output = compactSummary(data.by_status, data.by_type, data.active_agents);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -1091,10 +970,8 @@ export function registerToolHandlers(server) {
                     const extendMinutes = args?.extend_minutes || 30;
                     const result = await heartbeatTask(DEFAULT_USER_ID, projectId, taskId, agentId, extendMinutes);
                     mcpLogger.toolResult(name, true, timer());
-                    const data = result.data;
-                    let output = `# Heartbeat\n\n`;
-                    output += `**Extended:** ${data.extended ? '✅ Yes' : '❌ No'}\n`;
-                    output += `**New Expiry:** ${data.new_expires_at}\n`;
+                    // Compact output
+                    const output = compactHeartbeat(result.data.extended, result.data.new_expires_at);
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -1808,30 +1685,42 @@ export function registerToolHandlers(server) {
                 case 'codedna_generate_api': {
                     const result = await handleGenerateApi(args);
                     mcpLogger.toolResult(name, true, timer());
+                    let output = JSON.stringify(result, null, 2);
+                    if (workflowWarnings) {
+                        output += '\n\n' + workflowWarnings;
+                    }
                     return {
                         content: [{
                                 type: 'text',
-                                text: JSON.stringify(result, null, 2),
+                                text: output,
                             }],
                     };
                 }
                 case 'codedna_generate_frontend': {
                     const result = await handleGenerateFrontend(args);
                     mcpLogger.toolResult(name, true, timer());
+                    let output = JSON.stringify(result, null, 2);
+                    if (workflowWarnings) {
+                        output += '\n\n' + workflowWarnings;
+                    }
                     return {
                         content: [{
                                 type: 'text',
-                                text: JSON.stringify(result, null, 2),
+                                text: output,
                             }],
                     };
                 }
                 case 'codedna_generate_component': {
                     const result = await handleGenerateComponent(args);
                     mcpLogger.toolResult(name, true, timer());
+                    let output = JSON.stringify(result, null, 2);
+                    if (workflowWarnings) {
+                        output += '\n\n' + workflowWarnings;
+                    }
                     return {
                         content: [{
                                 type: 'text',
-                                text: JSON.stringify(result, null, 2),
+                                text: output,
                             }],
                     };
                 }

package/dist/helpers/compact-formatter.d.ts

@@ -0,0 +1,51 @@
+import type { Task, TaskContext } from './tasks.js';
+/** Truncate task ID to first 8 chars */
+export declare function shortId(id: string): string;
+/** Format task status with icon */
+export declare function statusIcon(status: string): string;
+/** Single-line task representation */
+export declare function compactTask(t: Task): string;
+/** Compact task list - one line per task */
+export declare function compactTaskList(tasks: Task[]): string;
+/** Compact task creation result */
+export declare function compactTaskCreated(task: Task): string;
+/** Compact task start result */
+export declare function compactTaskStart(task: Task, lockExpires: string): string;
+/** Compact task complete result */
+export declare function compactTaskComplete(task: Task, summary: string, unblocked?: Task[]): string;
+/** Compact task claim result */
+export declare function compactTaskClaim(task: Task, claimed: boolean, expires: string): string;
+/** Compact task release result */
+export declare function compactTaskRelease(task: Task, released: boolean): string;
+/** Compact status update */
+export declare function compactStatusUpdate(task: Task): string;
+/** Compact context added */
+export declare function compactContextAdded(ctx: TaskContext): string;
+/** Compact heartbeat */
+export declare function compactHeartbeat(extended: boolean, expires: string): string;
+/** Compact memory search result */
+export declare function compactMemorySearch(facts: {
+    fact: string;
+}[], entities: {
+    name: string;
+}[]): string;
+/** Compact memory store result */
+export declare function compactFactStored(entity1: string, rel: string, entity2: string, factId: string): string;
+/** Compact summary stats */
+export declare function compactSummary(byStatus: Record<string, number>, byType: Record<string, number>, activeAgents: number): string;
+/** Compact epic progress */
+export declare function compactEpicStatus(title: string, progress: number, stats: Record<string, number>): string;
+/** Compact dispatch list */
+export declare function compactDispatch(items: {
+    task: Task;
+    worker: {
+        name: string;
+    };
+}[]): string;
+/** Compact memory index */
+export declare function compactMemoryIndex(entries: {
+    id: string;
+    summary: string;
+    relevance: number;
+    is_critical?: boolean;
+}[]): string;

package/dist/helpers/compact-formatter.js

@@ -0,0 +1,130 @@
+// =============================================================================
+// Compact Response Formatter
+// =============================================================================
+// Minimizes tool output to conserve context window.
+// Every byte counts - prefer single-line responses where possible.
+const STATUS_ICONS = {
+    backlog: '📋',
+    ready: '🟢',
+    in_progress: '🔄',
+    blocked: '🚫',
+    review: '👀',
+    done: '✅',
+    cancelled: '❌',
+};
+/** Truncate task ID to first 8 chars */
+export function shortId(id) {
+    return id.slice(0, 8);
+}
+/** Format task status with icon */
+export function statusIcon(status) {
+    return STATUS_ICONS[status] || '📝';
+}
+/** Single-line task representation */
+export function compactTask(t) {
+    return `${statusIcon(t.status)} ${t.title} (${shortId(t.id)}) [${t.status}]`;
+}
+/** Compact task list - one line per task */
+export function compactTaskList(tasks) {
+    if (tasks.length === 0)
+        return 'No tasks found.';
+    return tasks.map(t => compactTask(t)).join('\n');
+}
+/** Compact task creation result */
+export function compactTaskCreated(task) {
+    return `Created: ${task.type} "${task.title}" → ${shortId(task.id)}`;
+}
+/** Compact task start result */
+export function compactTaskStart(task, lockExpires) {
+    return `Started: ${task.title} (${shortId(task.id)}) lock until ${new Date(lockExpires).toLocaleTimeString()}`;
+}
+/** Compact task complete result */
+export function compactTaskComplete(task, summary, unblocked) {
+    let result = `✅ ${task.title} → done`;
+    if (unblocked && unblocked.length > 0) {
+        result += `\n🔓 Unblocked: ${unblocked.map(t => t.title).join(', ')}`;
+    }
+    return result;
+}
+/** Compact task claim result */
+export function compactTaskClaim(task, claimed, expires) {
+    if (!claimed)
+        return `❌ Failed to claim: ${task.title}`;
+    return `Claimed: ${task.title} (${shortId(task.id)}) until ${new Date(expires).toLocaleTimeString()}`;
+}
+/** Compact task release result */
+export function compactTaskRelease(task, released) {
+    if (!released)
+        return `❌ Failed to release: ${task.title}`;
+    return `Released: ${task.title} → ${task.status}`;
+}
+/** Compact status update */
+export function compactStatusUpdate(task) {
+    return `${statusIcon(task.status)} ${task.title} → ${task.status}`;
+}
+/** Compact context added */
+export function compactContextAdded(ctx) {
+    return `+ ${ctx.context_type} context added (${shortId(ctx.id)})`;
+}
+/** Compact heartbeat */
+export function compactHeartbeat(extended, expires) {
+    if (!extended)
+        return '❌ Heartbeat failed';
+    return `♥ Extended until ${new Date(expires).toLocaleTimeString()}`;
+}
+/** Compact memory search result */
+export function compactMemorySearch(facts, entities) {
+    if (facts.length === 0 && entities.length === 0)
+        return 'No results.';
+    const parts = [];
+    if (entities.length > 0) {
+        parts.push(`Entities: ${entities.map(e => e.name).join(', ')}`);
+    }
+    if (facts.length > 0) {
+        parts.push('Facts:');
+        facts.forEach(f => parts.push(`• ${f.fact}`));
+    }
+    return parts.join('\n');
+}
+/** Compact memory store result */
+export function compactFactStored(entity1, rel, entity2, factId) {
+    return `Stored: ${entity1} ${rel} ${entity2} (${shortId(factId)})`;
+}
+/** Compact summary stats */
+export function compactSummary(byStatus, byType, activeAgents) {
+    const statusParts = Object.entries(byStatus)
+        .filter(([, count]) => count > 0)
+        .map(([s, c]) => `${statusIcon(s)}${c}`)
+        .join(' ');
+    const typeParts = Object.entries(byType)
+        .filter(([, count]) => count > 0)
+        .map(([t, c]) => `${t}:${c}`)
+        .join(' ');
+    return `Tasks: ${statusParts}\nTypes: ${typeParts}\nAgents: ${activeAgents}`;
+}
+/** Compact epic progress */
+export function compactEpicStatus(title, progress, stats) {
+    const pct = Math.round(progress * 100);
+    const bar = '█'.repeat(Math.round(pct / 10)) + '░'.repeat(10 - Math.round(pct / 10));
+    const statusLine = Object.entries(stats)
+        .filter(([, c]) => c > 0)
+        .map(([s, c]) => `${statusIcon(s)}${c}`)
+        .join(' ');
+    return `${title}: [${bar}] ${pct}%\n${statusLine}`;
+}
+/** Compact dispatch list */
+export function compactDispatch(items) {
+    if (items.length === 0)
+        return 'No tasks ready for dispatch.';
+    return `Ready (${items.length}):\n` + items.map(i => `• ${i.task.title} → ${i.worker.name}`).join('\n');
+}
+/** Compact memory index */
+export function compactMemoryIndex(entries) {
+    if (entries.length === 0)
+        return 'No memories found.';
+    return entries.map((e, i) => {
+        const critical = e.is_critical ? '🔴' : '';
+        const rel = Math.round(e.relevance * 100);
+        return `${i + 1}. ${critical}${e.summary.slice(0, 60)} (${rel}%) [${shortId(e.id)}]`;
+    }).join('\n');
+}

package/dist/helpers/engagement-tracker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Track an engagement event via the API
+ * This persists the event to D1 for analytics
+ */
+export declare function trackEngagementEvent(sessionId: string, projectId: string, eventType: 'search' | 'detail' | 'inject' | 'store_fact' | 'context_referenced'): Promise<void>;
+export declare function getSessionId(): string;
+/**
+ * Reset session ID (for testing or explicit session boundaries)
+ */
+export declare function resetSessionId(): void;

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