@claudetools/tools 0.8.2 → 0.8.4

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': {
@@ -126,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;
@@ -758,30 +836,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 +862,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 +890,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 +906,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 +981,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 +994,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 +1006,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 +1020,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 +1029,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 +1042,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 +1757,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/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/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;