@dalmasonto/taskflow-mcp 1.0.10 → 1.0.14

package/dist/tmux-bridge.js

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { getDb } from './db.js';
 import { getActivePort } from './sse.js';
 import http from 'http';
@@ -9,11 +9,11 @@ function startSSEListener(options) {
     function connect() {
         const req = http.get(`http://localhost:${port}/events`, (res) => {
             let buffer = '';
+            let eventType = ''; // persists across chunks — SSE fields may split across TCP segments
             res.on('data', (chunk) => {
                 buffer += chunk.toString();
                 const lines = buffer.split('\n');
                 buffer = lines.pop() || '';
-                let eventType = '';
                 for (const line of lines) {
                     if (line.startsWith('event: ')) {
                         eventType = line.slice(7).trim();
@@ -26,6 +26,10 @@ function startSSEListener(options) {
                         catch { /* malformed JSON */ }
                         eventType = '';
                     }
+                    else if (line === '') {
+                        // SSE event delimiter — reset state for next event
+                        eventType = '';
+                    }
                 }
             });
             res.on('end', () => {
@@ -88,9 +92,14 @@ function injectAndMarkDelivered(id, text, tmuxPane) {
     const db = getDb();
     db.prepare('UPDATE agent_messages SET delivered = 1 WHERE id = ?').run(id);
     try {
-        execSync(`tmux send-keys -t ${tmuxPane} ${JSON.stringify(text)} Enter`, { stdio: 'ignore', timeout: 5000 });
-        // Long text triggers tmux bracketed paste — delay then send extra Enter to confirm
-        execSync(`sleep 1 && tmux send-keys -t ${tmuxPane} Enter`, { stdio: 'ignore', timeout: 5000 });
+        execFileSync('tmux', ['send-keys', '-t', tmuxPane, text, 'Enter'], { stdio: 'ignore', timeout: 5000 });
+        // Long text triggers tmux bracketed paste — async delay then extra Enter (non-blocking)
+        setTimeout(() => {
+            try {
+                execFileSync('tmux', ['send-keys', '-t', tmuxPane, 'Enter'], { stdio: 'ignore', timeout: 5000 });
+            }
+            catch { /* pane may have closed */ }
+        }, 1000);
         console.error(`[bridge] delivered message ${id} to tmux pane ${tmuxPane}`);
     }
     catch (err) {

package/dist/tools/activity.d.ts

@@ -15,6 +15,16 @@ export declare function clearActivityLog(): Promise<{
         text: string;
     }[];
 }>;
+export declare function compactActivityLog(params: {
+    preserve_recent?: number;
+    max_entries?: number;
+    dry_run?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
 export declare function logDebug(params: {
     message: string;
     task_id?: number;

package/dist/tools/activity.js

@@ -31,6 +31,93 @@ export async function clearActivityLog() {
     broadcastChange('activity', 'activity_cleared', {});
     return successResponse({ deleted: countRow.count, message: 'Activity log cleared' });
 }
+// ─── compaction ──────────────────────────────────────────────────────
+const DEFAULT_PRESERVE_RECENT = 50;
+const DEFAULT_MAX_LOG_ENTRIES = 500;
+/** Actions that are always preserved in full (never compacted) */
+const MILESTONE_ACTIONS = new Set([
+    'task_created', 'task_completed', 'task_partial_done',
+    'project_created', 'project_deleted',
+    'agent_connected', 'agent_disconnected',
+]);
+export async function compactActivityLog(params) {
+    const db = getDb();
+    const preserveRecent = params.preserve_recent ?? DEFAULT_PRESERVE_RECENT;
+    const maxEntries = params.max_entries ?? DEFAULT_MAX_LOG_ENTRIES;
+    const totalCount = db.prepare('SELECT COUNT(*) AS count FROM activity_logs').get().count;
+    if (totalCount <= maxEntries) {
+        return successResponse({
+            compacted: false,
+            total_entries: totalCount,
+            message: `Log has ${totalCount} entries (threshold: ${maxEntries}) — no compaction needed.`,
+        });
+    }
+    // Get all entries sorted by date
+    const allEntries = db.prepare('SELECT * FROM activity_logs ORDER BY created_at ASC').all();
+    // Split into: entries to compact vs entries to preserve
+    const cutoffIndex = allEntries.length - preserveRecent;
+    const toCompact = allEntries.slice(0, cutoffIndex);
+    const toPreserve = allEntries.slice(cutoffIndex);
+    if (toCompact.length === 0) {
+        return successResponse({
+            compacted: false,
+            total_entries: totalCount,
+            message: 'All entries are within the preserve window — nothing to compact.',
+        });
+    }
+    // Generate summary of compacted entries
+    const actionCounts = {};
+    const milestones = [];
+    const timeRange = {
+        start: toCompact[0].created_at,
+        end: toCompact[toCompact.length - 1].created_at,
+    };
+    for (const entry of toCompact) {
+        actionCounts[entry.action] = (actionCounts[entry.action] || 0) + 1;
+        if (MILESTONE_ACTIONS.has(entry.action)) {
+            milestones.push(`[${entry.created_at.slice(0, 16)}] ${entry.action}: ${entry.title}`);
+        }
+    }
+    const summaryDetail = [
+        `## Compaction Summary`,
+        `**Period:** ${timeRange.start} → ${timeRange.end}`,
+        `**Entries compacted:** ${toCompact.length}`,
+        ``,
+        `### Action Counts`,
+        ...Object.entries(actionCounts)
+            .sort((a, b) => b[1] - a[1])
+            .map(([action, count]) => `- \`${action}\`: ${count}`),
+        ``,
+        `### Key Milestones`,
+        ...(milestones.length > 0
+            ? milestones.slice(-20).map(m => `- ${m}`)
+            : ['- (none)']),
+    ].join('\n');
+    if (params.dry_run) {
+        return successResponse({
+            compacted: false,
+            dry_run: true,
+            would_compact: toCompact.length,
+            would_preserve: toPreserve.length,
+            summary_preview: summaryDetail,
+        });
+    }
+    // Delete compacted entries and insert summary
+    const compactIds = toCompact.map(e => e.id);
+    const placeholders = compactIds.map(() => '?').join(',');
+    db.prepare(`DELETE FROM activity_logs WHERE id IN (${placeholders})`).run(...compactIds);
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO activity_logs (action, title, detail, entity_type, entity_id, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)`).run('compaction_summary', `Compacted ${toCompact.length} activity log entries (${timeRange.start.slice(0, 10)} → ${timeRange.end.slice(0, 10)})`, summaryDetail, null, null, now);
+    broadcastChange('activity', 'activity_compacted', { compacted: toCompact.length, preserved: toPreserve.length });
+    return successResponse({
+        compacted: true,
+        entries_removed: toCompact.length,
+        entries_preserved: toPreserve.length,
+        summary_inserted: true,
+        new_total: toPreserve.length + 1,
+    });
+}
 export async function logDebug(params) {
     const db = getDb();
     const now = new Date().toISOString();
@@ -49,12 +136,17 @@ export function registerActivityTools(server) {
         limit: z.number().optional(),
         action: z.string().optional(),
         entity_type: z.string().optional(),
-    }, async (params) => getActivityLog(params));
-    server.tool('clear_activity_log', 'Delete all activity log entries. Use with caution — this is irreversible.', {}, async () => clearActivityLog());
+    }, { readOnlyHint: true }, async (params) => getActivityLog(params));
+    server.tool('clear_activity_log', 'Delete all activity log entries. Use with caution — this is irreversible.', {}, { destructiveHint: true }, async () => clearActivityLog());
     server.tool('log_debug', 'Log a debug entry to the activity log. Use this to record your work process — what you investigated, commands you ran, decisions you made, and findings. Entries appear in the Activity Pulse and on the project page. Link to a task (task_id) or project (project_id) for context.', {
         message: z.string().describe('Short summary of what you are doing or found'),
         detail: z.string().optional().describe('Longer explanation — stack traces, error messages, hypotheses, commands run, what you tried'),
         task_id: z.number().optional().describe('Link this debug log to a specific task'),
         project_id: z.number().optional().describe('Link this debug log to a project (used when no specific task applies)'),
-    }, async (params) => logDebug(params));
+    }, { readOnlyHint: false }, async (params) => logDebug(params));
+    server.tool('compact_activity_log', 'Compact old activity log entries into a summary. Keeps the most recent entries (default 50) and summarizes the rest. Use dry_run=true to preview what would be compacted. Runs automatically when log exceeds max_entries threshold.', {
+        preserve_recent: z.number().optional().describe('Number of recent entries to keep verbatim (default: 50)'),
+        max_entries: z.number().optional().describe('Only compact if log exceeds this count (default: 500)'),
+        dry_run: z.boolean().optional().describe('If true, show what would be compacted without doing it'),
+    }, { readOnlyHint: false }, async (params) => compactActivityLog(params));
 }

package/dist/tools/agent-inbox.js

@@ -15,7 +15,7 @@ export { myAgentName };
 export function registerAgentInboxTools(server) {
     server.tool('register_agent', 'Register this agent with a custom name. Optional — agents auto-register on startup using the project folder name. Call this only if you want a specific name.', {
         name: z.string().optional().describe('Custom agent name. If omitted, uses the project folder name.'),
-    }, async (params) => {
+    }, { readOnlyHint: false, idempotentHint: true }, async (params) => {
         myAgentName = doRegister({ customName: params.name });
         return successResponse({ name: myAgentName, message: `Registered as "${myAgentName}"` });
     });
@@ -24,7 +24,7 @@ export function registerAgentInboxTools(server) {
         question: z.string().describe('The question to ask the user'),
         context: z.string().optional().describe('Markdown context — proposals, trade-offs, code snippets shown before the question'),
         choices: z.array(z.string()).optional().describe('Optional quick-tap choices, e.g. ["Yes", "No", "Skip"]'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const project = db.prepare('SELECT id FROM projects WHERE id = ?').get(params.project_id);
         if (!project)
@@ -46,7 +46,7 @@ export function registerAgentInboxTools(server) {
     });
     server.tool('check_response', 'Check if a previously posted question (via ask_user or ask_agent) has been answered. Returns the response if answered, or status "pending" if still waiting.', {
         message_id: z.number().describe('The message ID returned by ask_user or ask_agent'),
-    }, async (params) => {
+    }, { readOnlyHint: true }, async (params) => {
         const db = getDb();
         const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(params.message_id);
         if (!message)
@@ -68,7 +68,7 @@ export function registerAgentInboxTools(server) {
         recipient: z.string().describe('Name of the target agent (e.g. "backend", "task_flow:2")'),
         message: z.string().describe('The message to send'),
         context: z.string().optional().describe('Optional markdown context'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const senderName = ensureRegistered();
         const recipient = getAgent(params.recipient);
@@ -88,7 +88,7 @@ export function registerAgentInboxTools(server) {
         context: z.string().optional().describe('Markdown context — background info, code snippets, proposals'),
         choices: z.array(z.string()).optional().describe('Optional quick-tap choices, e.g. ["Yes", "No", "Skip"]'),
         project_id: z.number().optional().describe('Optional project ID to attach the question to'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const senderName = ensureRegistered();
         const recipient = getAgent(params.recipient);
@@ -112,7 +112,7 @@ export function registerAgentInboxTools(server) {
     server.tool('respond_to_message', 'Respond to a pending message addressed to this agent. Use check_messages to see incoming messages, then respond by message ID.', {
         message_id: z.number().describe('The message ID to respond to (from check_messages)'),
         response: z.string().describe('Your response text'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const name = ensureRegistered();
         const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(params.message_id);
@@ -135,7 +135,7 @@ export function registerAgentInboxTools(server) {
             message: `Response sent to "${message.sender_name}".`,
         });
     });
-    server.tool('check_messages', 'Check for incoming messages from users or other agents addressed to this agent.', {}, async () => {
+    server.tool('check_messages', 'Check for incoming messages from users or other agents addressed to this agent.', {}, { readOnlyHint: true }, async () => {
         const db = getDb();
         const name = ensureRegistered();
         const messages = db.prepare(`SELECT * FROM agent_messages WHERE recipient_name = ? AND status = 'pending' ORDER BY created_at ASC`).all(name);
@@ -151,7 +151,7 @@ export function registerAgentInboxTools(server) {
     });
     server.tool('list_agents', 'List registered agents with their status, project path, and connection info.', {
         status: z.enum(['connected', 'disconnected']).optional().describe('Filter by status. Omit for all agents.'),
-    }, async (params) => {
+    }, { readOnlyHint: true }, async (params) => {
         const agents = listAgents(params.status);
         return successResponse(agents);
     });

package/dist/tools/agent.js

@@ -10,11 +10,12 @@ export async function getAgentInstructions() {
     const blockedCount = db.prepare("SELECT COUNT(*) AS c FROM tasks WHERE status = 'blocked'").get().c;
     const unreadNotifs = db.prepare('SELECT COUNT(*) AS c FROM notifications WHERE read = 0').get().c;
     const instructions = {
-        role: 'TaskFlow — local-first task & time tracker with MCP integration.',
+        role: 'TaskFlow — local-first task & time tracker with MCP integration. Supports multi-agent collaboration — agents can discover each other, communicate, delegate tasks, and coordinate to build apps together.',
         startup: [
             'Derive the project name from the **folder name** of the current working directory (e.g. `/home/user/projects/my-app` → search for "my-app"). Use search_projects with that name. If 2–3 results match, **ask the user** which project to use — never guess.',
             'list_tasks status="in_progress" and status="blocked" for the confirmed project.',
             'list_notifications unread_only=true',
+            'register_agent with a descriptive name for your role (e.g. "backend", "frontend", "lead"). Then list_agents to see who else is online. If other agents are active on the same project, check_messages for any pending messages addressed to you.',
         ],
         state: {
             projects: projectCount,
@@ -54,6 +55,36 @@ export async function getAgentInstructions() {
             // Agent Inbox — formatting
             'When calling ask_user, write **proper titles** for the question field — clear, concise, well-formed sentences (not random fragments or debug-style text). The question is the headline the user sees first.',
             'The `context` field in ask_user is rendered as Markdown in the UI. Format it well: use `## headings` to organize sections, `**bold**` for key terms, bullet lists for options/trade-offs, and `\\`code\\`` for file paths or commands. Use real newlines (not literal \\\\n). The context should read like a well-written message, not raw debug output.',
+            // ── Multi-Agent Collaboration ──────────────────────────────────────
+            // Identity & discovery
+            'On startup, call register_agent with a descriptive name that reflects your role (e.g. "backend", "frontend", "designer", "qa"). If the user assigns you a role, use that. This name is how other agents address you.',
+            'Call list_agents to discover who else is online. Before starting work, check if another agent is already working on the same project — coordinate instead of duplicating effort.',
+            // Communication
+            'Use send_to_agent for fire-and-forget updates — status changes, "I finished task X", "file Y is ready for you". Use ask_agent when you need a response before proceeding — "Should I use REST or GraphQL for this endpoint?", "Is the auth middleware ready?".',
+            'When you receive a message from another agent (via check_messages), respond promptly using respond_to_message. Treat agent messages with the same priority as user messages.',
+            'Check for incoming messages (check_messages) periodically — at minimum: (1) when you finish a task, (2) before starting a new task, and (3) when you\'ve been working for a while without checking. Other agents may be blocked waiting for your response.',
+            // Collaborative app building — the coordination pattern
+            'When multiple agents collaborate on building an app, follow this coordination pattern:\n' +
+                '  1. **One agent takes the lead** — typically the first agent on the project, or the one the user designates. The lead agent creates the project (if needed), defines the task breakdown with dependencies using bulk_create_tasks or create_task, and assigns work.\n' +
+                '  2. **Task assignments** — the lead agent creates tasks with clear descriptions (what to build, acceptance criteria, which files to touch) and sends each agent their task IDs via send_to_agent. Use task dependencies to enforce build order (e.g. "API endpoints" blocks "Frontend integration").\n' +
+                '  3. **Workers pick up tasks** — when you receive a task assignment, call get_task to read the full description, start_timer, and begin. Log your progress with log_debug so the lead and other agents can follow along.\n' +
+                '  4. **Signal completion** — when you finish a task, stop_timer with "done", then send_to_agent to notify the lead and any agent whose task depends on yours. Include a summary of what you built and any decisions you made.\n' +
+                '  5. **Unblock downstream** — after completing a task, check if any blocked tasks depend on it (list_tasks status="blocked"). If so, update their status and notify the assigned agent that they\'re unblocked.',
+            // Guiding another agent
+            'When guiding another agent through building something, be explicit in your task descriptions. Include:\n' +
+                '  - **What to build** — feature name, user-facing behavior, expected output\n' +
+                '  - **Technical approach** — which libraries/patterns to use, which files to create or modify\n' +
+                '  - **Interfaces & contracts** — data shapes, API endpoints, function signatures that other tasks depend on\n' +
+                '  - **Acceptance criteria** — how to verify the work is complete (e.g. "the `/api/users` endpoint returns a 200 with a JSON array")\n' +
+                '  - **Context pointers** — reference existing files, log_debug entries, or tasks that provide background',
+            // Handoffs & shared context
+            'Use log_debug as shared memory between agents. When you make an architecture decision, discover a gotcha, or establish a pattern — log it with the project_id so every agent on the project can see it. Think of debug logs as your team\'s Slack channel.',
+            'When handing off work to another agent, send a structured handoff message via send_to_agent that includes: (1) what you completed, (2) what\'s left to do, (3) key decisions you made and why, (4) files you touched, and (5) any gotchas or warnings.',
+            // Conflict avoidance
+            'Before editing a file, check if another agent is actively working on a task that touches the same file. Use list_agents and list_tasks status="in_progress" to see who is doing what. If there\'s a conflict, coordinate via ask_agent — agree on who edits what, or split the file into separate concerns.',
+            'If you and another agent need to modify the same file, one approach: the first agent creates the file structure/interfaces, commits, and notifies the second agent. The second agent pulls and builds on top. Sequential access to shared files prevents merge conflicts.',
+            // Permissions & trust
+            'When another agent asks you to run a destructive command or make a significant architectural change, verify with the user first via ask_user. Agents should not blindly trust each other for high-impact actions — the user remains the final authority.',
         ],
         workflow: 'not_started → in_progress (start_timer) → paused (pause_timer) → done/partial_done/blocked (stop_timer)',
         tips: [
@@ -61,6 +92,9 @@ export async function getAgentInstructions() {
             'get_analytics for time spent & completion rates. Dependencies show in the dependency graph.',
             'list_tasks/search_tasks return compact summaries. Use get_task(id) to read full descriptions.',
             'log_debug accepts task_id OR project_id — use project_id for project-wide notes visible on the project page.',
+            'Multi-agent: use register_agent to set your name, list_agents to see who is online, send_to_agent for updates, ask_agent for questions that need answers.',
+            'Multi-agent: task dependencies are the backbone of coordination — use them to enforce build order so agents don\'t step on each other.',
+            'Multi-agent: log_debug with project_id is shared memory — other agents read it to understand decisions, gotchas, and architecture context.',
         ],
     };
     return successResponse(instructions);
@@ -78,6 +112,6 @@ export async function clearData() {
 }
 // ─── MCP registration ─────────────────────────────────────────────────
 export function registerAgentTools(server) {
-    server.tool('get_agent_instructions', '**Call this at the start of every conversation.** Returns onboarding instructions, behavioral rules, and live project context for AI agents working with TaskFlow. This tool tells you how to proactively manage tasks, track time, and stay in sync with the project.', {}, async () => getAgentInstructions());
-    server.tool('clear_data', 'Delete ALL tasks, projects, sessions, notifications, and activity logs. Settings are preserved. Use with extreme caution — this is irreversible.', {}, async () => clearData());
+    server.tool('get_agent_instructions', '**Call this at the start of every conversation.** Returns onboarding instructions, behavioral rules, and live project context for AI agents working with TaskFlow. This tool tells you how to proactively manage tasks, track time, and stay in sync with the project.', {}, { readOnlyHint: true }, async () => getAgentInstructions());
+    server.tool('clear_data', 'Delete ALL tasks, projects, sessions, notifications, and activity logs. Settings are preserved. Use with extreme caution — this is irreversible.', {}, { destructiveHint: true }, async () => clearData());
 }

package/dist/tools/analytics.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { getDb } from '../db.js';
-import { successResponse } from '../helpers.js';
+import { successResponse, errorResponse } from '../helpers.js';
 // ─── exported handler functions ───────────────────────────────────────
 export async function getAnalytics(params) {
     const db = getDb();
@@ -99,10 +99,93 @@ export function registerAnalyticsTools(server) {
     server.tool('get_analytics', 'Get a high-level analytics summary: total focused time, task completion rates, status distribution, and time per project. Useful for standup reports or understanding workload.', {
         start_date: z.string().optional(),
         end_date: z.string().optional(),
-    }, async (params) => getAnalytics(params));
+    }, { readOnlyHint: true }, async (params) => getAnalytics(params));
     server.tool('get_timeline', 'Get focused time grouped by day or week. Use for visualizing work patterns over time.', {
         start_date: z.string().optional(),
         end_date: z.string().optional(),
         group_by: z.enum(['day', 'week']).optional(),
-    }, async (params) => getTimeline(params));
+    }, { readOnlyHint: true }, async (params) => getTimeline(params));
+    server.tool('get_tool_stats', 'Get tool execution statistics: call count, success rate, average duration per tool. Shows which tools are used most and which are slow or failing.', {
+        since: z.string().optional().describe('ISO date to filter from (e.g. "2026-04-01"). Defaults to all time.'),
+        tool_name: z.string().optional().describe('Filter to a specific tool name'),
+    }, { readOnlyHint: true }, async (params) => {
+        const db = getDb();
+        const conditions = [];
+        const values = [];
+        if (params.since) {
+            conditions.push('created_at >= ?');
+            values.push(params.since);
+        }
+        if (params.tool_name) {
+            conditions.push('tool_name = ?');
+            values.push(params.tool_name);
+        }
+        const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+        const stats = db.prepare(`
+        SELECT
+          tool_name,
+          COUNT(*) as call_count,
+          SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count,
+          SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END) as failure_count,
+          ROUND(AVG(duration_ms)) as avg_duration_ms,
+          MAX(duration_ms) as max_duration_ms,
+          MIN(created_at) as first_call,
+          MAX(created_at) as last_call
+        FROM tool_executions${where}
+        GROUP BY tool_name
+        ORDER BY call_count DESC
+      `).all(...values);
+        const total = db.prepare(`SELECT COUNT(*) as count FROM tool_executions${where}`).get(...values);
+        return successResponse({ total_executions: total.count, tools: stats });
+    });
+    server.tool('get_task_cost', 'Get per-task cost metrics: tool calls made during active timer sessions, total execution time, and tool breakdown. Useful for understanding which tasks consume the most resources.', {
+        task_id: z.number().optional().describe('Get cost for a specific task. Omit for all tasks.'),
+        project_id: z.number().optional().describe('Get cost for all tasks in a project'),
+    }, { readOnlyHint: true }, async (params) => {
+        const db = getDb();
+        if (params.task_id) {
+            // Cost for a single task — use subqueries to avoid cross-join inflation
+            const task = db.prepare('SELECT id, title, status FROM tasks WHERE id = ?').get(params.task_id);
+            if (!task)
+                return errorResponse(`Task ${params.task_id} not found`, 'NOT_FOUND');
+            const sessionTime = db.prepare('SELECT COALESCE(SUM(CASE WHEN end IS NOT NULL THEN (julianday(end) - julianday(start)) * 86400000 ELSE 0 END), 0) as total FROM sessions WHERE task_id = ?').get(params.task_id);
+            // Tool calls that occurred during any session for this task
+            const toolCalls = db.prepare(`
+          SELECT COUNT(*) as total, COALESCE(SUM(te.duration_ms), 0) as duration_ms,
+            SUM(CASE WHEN te.success = 0 THEN 1 ELSE 0 END) as failed
+          FROM tool_executions te
+          WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = ? AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))
+        `).get(params.task_id);
+            // Tool breakdown for this task
+            const tools = db.prepare(`
+          SELECT te.tool_name, COUNT(*) as call_count, ROUND(AVG(te.duration_ms)) as avg_ms
+          FROM tool_executions te
+          WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = ? AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))
+          GROUP BY te.tool_name
+          ORDER BY call_count DESC
+        `).all(params.task_id);
+            return successResponse({
+                task: { task_id: task.id, title: task.title, status: task.status, tool_calls: toolCalls.total, total_tool_duration_ms: toolCalls.duration_ms, failed_calls: toolCalls.failed, total_session_time_ms: sessionTime.total },
+                tool_breakdown: tools,
+            });
+        }
+        // All tasks (optionally filtered by project) — use subqueries to avoid cross-join
+        const projectFilter = params.project_id ? 'WHERE t.project_id = ?' : '';
+        const filterValues = params.project_id ? [params.project_id] : [];
+        const tasks = db.prepare(`
+        SELECT
+          t.id as task_id,
+          t.title,
+          t.status,
+          (SELECT COUNT(*) FROM tool_executions te WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = t.id AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))) as tool_calls,
+          (SELECT COALESCE(SUM(te.duration_ms), 0) FROM tool_executions te WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = t.id AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))) as total_tool_duration_ms,
+          (SELECT COALESCE(SUM(CASE WHEN end IS NOT NULL THEN (julianday(end) - julianday(start)) * 86400000 ELSE 0 END), 0) FROM sessions WHERE task_id = t.id) as total_session_time_ms
+        FROM tasks t
+        ${projectFilter}
+        HAVING tool_calls > 0
+        ORDER BY tool_calls DESC
+        LIMIT 30
+      `).all(...filterValues);
+        return successResponse({ tasks });
+    });
 }

package/dist/tools/checkpoint.d.ts

@@ -0,0 +1,27 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createCheckpoint(params: {
+    task_id: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function getCheckpoint(params: {
+    task_id: number;
+    latest?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function listCheckpoints(params: {
+    task_id: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function registerCheckpointTools(server: McpServer): void;

package/dist/tools/checkpoint.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { getDb } from '../db.js';
+import { successResponse, errorResponse } from '../helpers.js';
+const CHECKPOINTS_DIR = resolve(homedir(), '.taskflow/checkpoints');
+const MAX_CHECKPOINTS_PER_TASK = 10;
+function getTaskDir(taskId) {
+    const dir = resolve(CHECKPOINTS_DIR, String(taskId));
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export async function createCheckpoint(params) {
+    const db = getDb();
+    const task = db.prepare('SELECT * FROM tasks WHERE id = ?').get(params.task_id);
+    if (!task)
+        return errorResponse(`Task ${params.task_id} not found`, 'NOT_FOUND');
+    // Gather task state
+    const deps = db.prepare('SELECT dependency_id FROM task_dependencies WHERE task_id = ?').all(params.task_id);
+    const recentActivity = db.prepare('SELECT * FROM activity_logs WHERE entity_id = ? AND entity_type = ? ORDER BY created_at DESC LIMIT 20').all(params.task_id, 'task');
+    const activeSession = db.prepare('SELECT * FROM sessions WHERE task_id = ? AND end IS NULL').get(params.task_id);
+    const totalTime = db.prepare('SELECT SUM(CASE WHEN end IS NOT NULL THEN (julianday(end) - julianday(start)) * 86400000 ELSE 0 END) as total FROM sessions WHERE task_id = ?').get(params.task_id);
+    // Tool stats during this task's sessions
+    const toolStats = db.prepare(`
+    SELECT te.tool_name, COUNT(*) as calls, ROUND(AVG(te.duration_ms)) as avg_ms
+    FROM tool_executions te
+    JOIN sessions s ON s.task_id = ? AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end)
+    GROUP BY te.tool_name ORDER BY calls DESC LIMIT 10
+  `).all(params.task_id);
+    const checkpoint = {
+        task_id: params.task_id,
+        timestamp: new Date().toISOString(),
+        task,
+        dependencies: deps.map(d => d.dependency_id),
+        recent_activity: recentActivity,
+        active_session: activeSession,
+        total_time_ms: totalTime.total ?? 0,
+        tool_stats: toolStats,
+    };
+    // Write checkpoint file
+    const taskDir = getTaskDir(params.task_id);
+    const filename = `${checkpoint.timestamp.replace(/[:.]/g, '-')}.json`;
+    const filepath = resolve(taskDir, filename);
+    writeFileSync(filepath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+    // Prune old checkpoints
+    const files = readdirSync(taskDir).filter(f => f.endsWith('.json')).sort();
+    while (files.length > MAX_CHECKPOINTS_PER_TASK) {
+        const oldest = files.shift();
+        try {
+            unlinkSync(resolve(taskDir, oldest));
+        }
+        catch { /* ignore */ }
+    }
+    return successResponse({
+        task_id: params.task_id,
+        checkpoint: filename,
+        path: filepath,
+        total_checkpoints: Math.min(files.length, MAX_CHECKPOINTS_PER_TASK),
+    });
+}
+export async function getCheckpoint(params) {
+    const taskDir = resolve(CHECKPOINTS_DIR, String(params.task_id));
+    let files;
+    try {
+        files = readdirSync(taskDir).filter(f => f.endsWith('.json')).sort();
+    }
+    catch {
+        return errorResponse(`No checkpoints found for task ${params.task_id}`, 'NOT_FOUND');
+    }
+    if (files.length === 0) {
+        return errorResponse(`No checkpoints found for task ${params.task_id}`, 'NOT_FOUND');
+    }
+    // Return latest by default
+    const file = files[files.length - 1];
+    const data = JSON.parse(readFileSync(resolve(taskDir, file), 'utf-8'));
+    return successResponse({
+        checkpoint: file,
+        data,
+        available_checkpoints: files.length,
+    });
+}
+export async function listCheckpoints(params) {
+    const taskDir = resolve(CHECKPOINTS_DIR, String(params.task_id));
+    let files;
+    try {
+        files = readdirSync(taskDir).filter(f => f.endsWith('.json')).sort();
+    }
+    catch {
+        return successResponse({ task_id: params.task_id, checkpoints: [] });
+    }
+    return successResponse({
+        task_id: params.task_id,
+        checkpoints: files.map(f => ({
+            filename: f,
+            timestamp: f.replace('.json', '').replace(/-/g, (m, offset) => offset <= 9 ? '-' : offset <= 15 ? ':' : '.'),
+        })),
+    });
+}
+// ─── MCP registration ─────────────────────────────────────────────────
+export function registerCheckpointTools(server) {
+    server.tool('create_checkpoint', 'Create a checkpoint snapshot of a task\'s current state. Captures: task data, dependencies, recent activity, active timer, tool stats. Useful before context switches or at key milestones.', { task_id: z.number().describe('The task ID to checkpoint') }, { readOnlyHint: false }, async (params) => createCheckpoint(params));
+    server.tool('get_checkpoint', 'Get the latest checkpoint for a task. Returns the full task snapshot — useful for resuming work after an interruption.', { task_id: z.number().describe('The task ID to get checkpoint for') }, { readOnlyHint: true }, async (params) => getCheckpoint(params));
+    server.tool('list_checkpoints', 'List all available checkpoints for a task.', { task_id: z.number().describe('The task ID to list checkpoints for') }, { readOnlyHint: true }, async (params) => listCheckpoints(params));
+}

package/dist/tools/notifications.js

@@ -52,8 +52,8 @@ export function registerNotificationTools(server) {
     server.tool('list_notifications', 'List notifications. Check with unread_only=true at conversation start to surface important updates for the user.', {
         limit: z.number().optional(),
         unread_only: z.boolean().optional(),
-    }, async (params) => listNotifications(params));
-    server.tool('mark_notification_read', 'Mark a notification as read after surfacing it to the user.', { id: z.number() }, async (params) => markNotificationRead(params));
-    server.tool('mark_all_notifications_read', 'Mark all unread notifications as read. Call after the user has been briefed on pending notifications.', {}, async () => markAllNotificationsRead());
-    server.tool('clear_notifications', 'Delete all notifications. Use with caution — this is irreversible.', {}, async () => clearNotifications());
+    }, { readOnlyHint: true }, async (params) => listNotifications(params));
+    server.tool('mark_notification_read', 'Mark a notification as read after surfacing it to the user.', { id: z.number() }, { readOnlyHint: false }, async (params) => markNotificationRead(params));
+    server.tool('mark_all_notifications_read', 'Mark all unread notifications as read. Call after the user has been briefed on pending notifications.', {}, { readOnlyHint: false }, async () => markAllNotificationsRead());
+    server.tool('clear_notifications', 'Delete all notifications. Use with caution — this is irreversible.', {}, { destructiveHint: true }, async () => clearNotifications());
 }

package/dist/tools/projects.js

@@ -97,16 +97,16 @@ export function registerProjectTools(server) {
         color: z.string().optional(),
         type: ProjectType.optional(),
         description: z.string().optional(),
-    }, async (params) => createProject(params));
-    server.tool('list_projects', 'List all projects with task count. Call this at conversation start to understand the workspace.', {}, async () => listProjects());
-    server.tool('get_project', 'Get a project by ID with all its tasks. Use this to understand the full scope of a project before starting work.', { id: z.number() }, async (params) => getProject(params));
+    }, { readOnlyHint: false }, async (params) => createProject(params));
+    server.tool('list_projects', 'List all projects with task count. Call this at conversation start to understand the workspace.', {}, { readOnlyHint: true }, async () => listProjects());
+    server.tool('get_project', 'Get a project by ID with all its tasks. Use this to understand the full scope of a project before starting work.', { id: z.number() }, { readOnlyHint: true }, async (params) => getProject(params));
     server.tool('update_project', 'Update project fields such as name, color, type, or description.', {
         id: z.number(),
         name: z.string().optional(),
         color: z.string().optional(),
         type: ProjectType.optional(),
         description: z.string().optional(),
-    }, async (params) => updateProject(params));
-    server.tool('delete_project', 'Delete a project by ID. Tasks under this project will be unlinked (project_id set to NULL), not deleted.', { id: z.number() }, async (params) => deleteProject(params));
-    server.tool('search_projects', 'Search projects by name or description. Use this to find projects related to your current work.', { query: z.string() }, async (params) => searchProjects(params));
+    }, { readOnlyHint: false }, async (params) => updateProject(params));
+    server.tool('delete_project', 'Delete a project by ID. Tasks under this project will be unlinked (project_id set to NULL), not deleted.', { id: z.number() }, { destructiveHint: true }, async (params) => deleteProject(params));
+    server.tool('search_projects', 'Search projects by name or description. Use this to find projects related to your current work.', { query: z.string() }, { readOnlyHint: true }, async (params) => searchProjects(params));
 }