@dalmasonto/taskflow-mcp 1.0.5 → 1.0.7

package/README.md

@@ -40,7 +40,10 @@ By default, Claude Code will prompt you to approve each MCP tool call. To allow
       "mcp__taskflow__*"
     ]
   },
-  "enableAllProjectMcpServers": true
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "taskflow"
+  ]
 }
 ```
 
@@ -112,6 +115,34 @@ The `get_agent_instructions` tool tells agents to:
 5. **Stay in sync** — create tasks for new work items to keep the tracker up to date
 6. **Read descriptions** — task descriptions contain implementation details and acceptance criteria
 
+## Agent Inbox — Remote Communication
+
+The Agent Inbox lets agents ask questions that appear in the TaskFlow UI. Users can respond from any device (phone, browser, another machine), and the response is delivered back to the agent's terminal automatically.
+
+### How it works
+
+1. Agent calls `ask_user` with a question, context, and optional quick-tap choices
+2. Question appears instantly in the TaskFlow UI at `/inbox`
+3. User responds from the UI — response is injected into the agent's terminal via tmux
+4. Agent also asks in the terminal normally, so the user can answer from either place
+
+### Setup for auto-injection
+
+For responses to be injected directly into the terminal, run Claude Code inside tmux:
+
+```bash
+# Install tmux (one-time)
+sudo apt-get install -y tmux
+
+# Start a tmux session and run claude inside it
+tmux new -s agent
+claude
+```
+
+Without tmux, the inbox still works — agents can use `check_response` to poll for answers, or the user can dismiss questions answered in the terminal.
+
+See [Terminal Injection Setup](../docs/agent-inbox-terminal-injection.md) for full details, multiple agent setup, and cleanup instructions.
+
 ## Available Tools
 
 ### Agent
@@ -168,6 +199,12 @@ The `get_agent_instructions` tool tells agents to:
 | `mark_all_notifications_read` | Mark all as read |
 | `clear_notifications` | Delete all notifications |
 
+### Agent Inbox
+| Tool | Description |
+|------|-------------|
+| `ask_user` | Post a question to the Agent Inbox for remote response. Returns immediately with message ID |
+| `check_response` | Check if the user has responded to a previously posted question |
+
 ### Settings
 | Tool | Description |
 |------|-------------|

package/dist/agent-registry.d.ts

@@ -0,0 +1,23 @@
+interface AgentRow {
+    id: number;
+    name: string;
+    project_path: string;
+    pid: number;
+    tmux_pane: string | null;
+    status: string;
+    connected_at: string;
+    disconnected_at: string | null;
+}
+/** Register an agent. Returns the assigned name. */
+export declare function registerAgent(options?: {
+    customName?: string;
+}): string;
+/** Mark an agent as disconnected */
+export declare function unregisterAgent(name: string): void;
+/** Check all registered agents and mark dead ones as disconnected */
+export declare function checkAgentLiveness(): void;
+/** Get a registered agent by name */
+export declare function getAgent(name: string): AgentRow | undefined;
+/** List all agents, optionally filtered by status */
+export declare function listAgents(status?: string): AgentRow[];
+export {};

package/dist/agent-registry.js

@@ -0,0 +1,107 @@
+import { execSync } from 'child_process';
+import { getDb } from './db.js';
+import { broadcast } from './sse.js';
+import { logActivity } from './helpers.js';
+/** Check if a process is still alive */
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Detect the tmux pane for a given PID */
+function detectTmuxPane(pid) {
+    try {
+        const ptsPath = execSync(`readlink /proc/${pid}/fd/0`).toString().trim();
+        const panes = execSync('tmux list-panes -a -F "#{pane_id} #{pane_tty}"').toString().trim().split('\n');
+        for (const line of panes) {
+            const [paneId, paneTty] = line.split(' ');
+            if (paneTty === ptsPath)
+                return paneId;
+        }
+    }
+    catch { /* tmux not available */ }
+    return null;
+}
+/** Generate a unique agent name from the project folder, auto-suffixing on collision */
+function generateName(folderName) {
+    const db = getDb();
+    const existing = db.prepare('SELECT * FROM agent_registry WHERE name = ?').get(folderName);
+    if (!existing || !isAlive(existing.pid)) {
+        return folderName;
+    }
+    for (let i = 2; i < 100; i++) {
+        const candidate = `${folderName}:${i}`;
+        const row = db.prepare('SELECT * FROM agent_registry WHERE name = ?').get(candidate);
+        if (!row || !isAlive(row.pid))
+            return candidate;
+    }
+    return `${folderName}:${Date.now()}`;
+}
+/** Register an agent. Returns the assigned name. */
+export function registerAgent(options) {
+    const db = getDb();
+    const agentPid = process.ppid;
+    const projectPath = process.cwd();
+    const folderName = projectPath.split('/').pop() || 'unknown';
+    // Check if this PID already has a registration — reuse it
+    const existingByPid = db.prepare('SELECT * FROM agent_registry WHERE pid = ? AND status = ?').get(agentPid, 'connected');
+    if (existingByPid) {
+        // Update tmux pane in case it changed, but keep the same name
+        const tmuxPane = detectTmuxPane(agentPid);
+        if (tmuxPane !== existingByPid.tmux_pane) {
+            db.prepare('UPDATE agent_registry SET tmux_pane = ? WHERE id = ?').run(tmuxPane, existingByPid.id);
+        }
+        return existingByPid.name;
+    }
+    // Clean up dead agents first to free up names
+    checkAgentLiveness();
+    const name = options?.customName || generateName(folderName);
+    const tmuxPane = detectTmuxPane(agentPid);
+    const ts = new Date().toISOString();
+    const existing = db.prepare('SELECT * FROM agent_registry WHERE name = ?').get(name);
+    if (existing) {
+        db.prepare('UPDATE agent_registry SET project_path = ?, pid = ?, tmux_pane = ?, status = ?, connected_at = ?, disconnected_at = NULL WHERE name = ?').run(projectPath, agentPid, tmuxPane, 'connected', ts, name);
+    }
+    else {
+        db.prepare('INSERT INTO agent_registry (name, project_path, pid, tmux_pane, status, connected_at) VALUES (?, ?, ?, ?, ?, ?)').run(name, projectPath, agentPid, tmuxPane, 'connected', ts);
+    }
+    const row = db.prepare('SELECT * FROM agent_registry WHERE name = ?').get(name);
+    broadcast('agent_connected', { entity: 'agent', action: 'agent_connected', payload: row });
+    logActivity('agent_connected', `Agent "${name}" connected`, { entityType: 'agent' });
+    return name;
+}
+/** Mark an agent as disconnected */
+export function unregisterAgent(name) {
+    const db = getDb();
+    const ts = new Date().toISOString();
+    db.prepare("UPDATE agent_registry SET status = 'disconnected', disconnected_at = ? WHERE name = ?").run(ts, name);
+    const row = db.prepare('SELECT * FROM agent_registry WHERE name = ?').get(name);
+    broadcast('agent_disconnected', { entity: 'agent', action: 'agent_disconnected', payload: row });
+    logActivity('agent_disconnected', `Agent "${name}" disconnected`, { entityType: 'agent' });
+}
+/** Check all registered agents and mark dead ones as disconnected */
+export function checkAgentLiveness() {
+    const db = getDb();
+    const liveAgents = db.prepare("SELECT * FROM agent_registry WHERE status = 'connected'").all();
+    for (const agent of liveAgents) {
+        if (!isAlive(agent.pid)) {
+            unregisterAgent(agent.name);
+        }
+    }
+}
+/** Get a registered agent by name */
+export function getAgent(name) {
+    return getDb().prepare('SELECT * FROM agent_registry WHERE name = ?').get(name);
+}
+/** List all agents, optionally filtered by status */
+export function listAgents(status) {
+    const db = getDb();
+    if (status) {
+        return db.prepare('SELECT * FROM agent_registry WHERE status = ? ORDER BY connected_at DESC').all(status);
+    }
+    return db.prepare('SELECT * FROM agent_registry ORDER BY connected_at DESC').all();
+}

package/dist/db.js

@@ -91,6 +91,33 @@ function initSchema(db) {
       value TEXT NOT NULL
     );
 
+    CREATE TABLE IF NOT EXISTS agent_messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER REFERENCES projects(id) ON DELETE CASCADE,
+      question TEXT NOT NULL,
+      context TEXT,
+      choices TEXT,
+      response TEXT,
+      agent_pid INTEGER,
+      delivered INTEGER,
+      sender_name TEXT NOT NULL DEFAULT 'unknown',
+      recipient_name TEXT NOT NULL DEFAULT 'user',
+      status TEXT NOT NULL DEFAULT 'pending',
+      created_at TEXT NOT NULL,
+      answered_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS agent_registry (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL UNIQUE,
+      project_path TEXT NOT NULL,
+      pid INTEGER NOT NULL,
+      tmux_pane TEXT,
+      status TEXT NOT NULL DEFAULT 'connected',
+      connected_at TEXT NOT NULL,
+      disconnected_at TEXT
+    );
+
     CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
     CREATE INDEX IF NOT EXISTS idx_tasks_project_id ON tasks(project_id);
     CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority);
@@ -99,7 +126,59 @@ function initSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_activity_logs_action ON activity_logs(action);
     CREATE INDEX IF NOT EXISTS idx_notifications_read ON notifications(read);
     CREATE INDEX IF NOT EXISTS idx_notifications_created_at ON notifications(created_at);
+    CREATE INDEX IF NOT EXISTS idx_agent_messages_status ON agent_messages(status);
+    CREATE INDEX IF NOT EXISTS idx_agent_messages_project_id ON agent_messages(project_id);
+    CREATE INDEX IF NOT EXISTS idx_agent_registry_status ON agent_registry(status);
+    CREATE INDEX IF NOT EXISTS idx_agent_registry_name ON agent_registry(name);
   `);
+    // Migrations — add columns that may be missing on existing databases
+    const cols = db.prepare("PRAGMA table_info(agent_messages)").all();
+    const colNames = new Set(cols.map(c => c.name));
+    if (!colNames.has('agent_pid')) {
+        db.exec('ALTER TABLE agent_messages ADD COLUMN agent_pid INTEGER');
+    }
+    if (!colNames.has('delivered')) {
+        db.exec('ALTER TABLE agent_messages ADD COLUMN delivered INTEGER');
+    }
+    if (!colNames.has('sender_name')) {
+        db.exec("ALTER TABLE agent_messages ADD COLUMN sender_name TEXT NOT NULL DEFAULT 'unknown'");
+    }
+    if (!colNames.has('recipient_name')) {
+        db.exec("ALTER TABLE agent_messages ADD COLUMN recipient_name TEXT NOT NULL DEFAULT 'user'");
+    }
+    // Migration: make agent_messages.project_id nullable if it was NOT NULL
+    try {
+        const tableInfo = db.prepare("SELECT sql FROM sqlite_master WHERE name = 'agent_messages'").get();
+        if (tableInfo?.sql?.includes('project_id INTEGER NOT NULL')) {
+            db.exec(`
+        CREATE TABLE agent_messages_new (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          project_id INTEGER REFERENCES projects(id) ON DELETE CASCADE,
+          question TEXT NOT NULL,
+          context TEXT,
+          choices TEXT,
+          response TEXT,
+          agent_pid INTEGER,
+          delivered INTEGER,
+          sender_name TEXT NOT NULL DEFAULT 'unknown',
+          recipient_name TEXT NOT NULL DEFAULT 'user',
+          status TEXT NOT NULL DEFAULT 'pending',
+          created_at TEXT NOT NULL,
+          answered_at TEXT
+        );
+        INSERT INTO agent_messages_new SELECT
+          id, project_id, question, context, choices, response, agent_pid, delivered,
+          COALESCE(sender_name, 'unknown'), COALESCE(recipient_name, 'user'),
+          status, created_at, answered_at
+        FROM agent_messages;
+        DROP TABLE agent_messages;
+        ALTER TABLE agent_messages_new RENAME TO agent_messages;
+        CREATE INDEX IF NOT EXISTS idx_agent_messages_status ON agent_messages(status);
+        CREATE INDEX IF NOT EXISTS idx_agent_messages_project_id ON agent_messages(project_id);
+      `);
+        }
+    }
+    catch { /* table may not exist yet */ }
 }
 export function closeDb() {
     if (db) {

package/dist/index.js

@@ -31,8 +31,16 @@ function cleanupOrphanedSessions() {
     }
 }
 cleanupOrphanedSessions();
-// Always start the HTTP/SSE server
-startSSEServer();
+// Always start the HTTP/SSE server (probes for existing instances, finds fallback port)
+await startSSEServer();
+// Liveness checker — periodically check registered agents and mark dead ones
+setInterval(async () => {
+    try {
+        const { checkAgentLiveness } = await import('./agent-registry.js');
+        checkAgentLiveness();
+    }
+    catch { /* ignore */ }
+}, 30_000);
 // Only start MCP stdio transport when not in http-only mode
 if (!httpOnly) {
     const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
@@ -45,6 +53,7 @@ if (!httpOnly) {
     const { registerNotificationTools } = await import('./tools/notifications.js');
     const { registerSettingsTools } = await import('./tools/settings.js');
     const { registerAgentTools } = await import('./tools/agent.js');
+    const { registerAgentInboxTools } = await import('./tools/agent-inbox.js');
     const server = new McpServer({
         name: 'taskflow',
         version: '1.0.0',
@@ -57,6 +66,82 @@ if (!httpOnly) {
     registerActivityTools(server);
     registerNotificationTools(server);
     registerSettingsTools(server);
+    registerAgentInboxTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    const { registerAgent, unregisterAgent } = await import('./agent-registry.js');
+    // Auto-register this agent
+    const agentName = registerAgent();
+    console.error(`[agent] registered as "${agentName}"`);
+    // Graceful shutdown — mark agent as disconnected
+    const cleanup = () => { try {
+        unregisterAgent(agentName);
+    }
+    catch { } process.exit(0); };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    // Background poller: deliver messages to this agent's terminal via tmux
+    const POLL_INTERVAL = 3000;
+    const agentPid = process.ppid;
+    let tmuxTarget = null;
+    try {
+        const { execSync: exec } = await import('child_process');
+        const ptsPath = exec(`readlink /proc/${agentPid}/fd/0`).toString().trim();
+        const panes = exec('tmux list-panes -a -F "#{pane_id} #{pane_tty}"').toString().trim().split('\n');
+        for (const line of panes) {
+            const [paneId, paneTty] = line.split(' ');
+            if (paneTty === ptsPath) {
+                tmuxTarget = paneId;
+                break;
+            }
+        }
+        if (tmuxTarget)
+            console.error(`[inject] tmux pane ${tmuxTarget} for agent "${agentName}"`);
+        else
+            console.error('[inject] agent not in tmux — terminal injection disabled');
+    }
+    catch {
+        console.error('[inject] tmux not available');
+    }
+    if (tmuxTarget) {
+        const { execSync: exec } = await import('child_process');
+        const target = tmuxTarget;
+        setInterval(() => {
+            try {
+                const db = getDb();
+                // Check for messages addressed to this agent (from user or other agents)
+                // AND for answered questions this agent sent (inbox responses)
+                // Check by agent name AND by agent_pid (backward compat with old messages)
+                const incoming = db.prepare(`SELECT * FROM agent_messages WHERE delivered IS NULL AND (
+            (recipient_name = ? AND status = 'pending') OR
+            (sender_name = ? AND recipient_name = 'user' AND status = 'answered') OR
+            (agent_pid = ? AND recipient_name = 'user' AND status = 'answered')
+          )`).all(agentName, agentName, agentPid);
+                for (const msg of incoming) {
+                    db.prepare('UPDATE agent_messages SET delivered = 1 WHERE id = ?').run(msg.id);
+                    let text;
+                    if (msg.recipient_name === agentName && msg.sender_name === 'user') {
+                        text = `[Message from User]: ${msg.question}`;
+                    }
+                    else if (msg.recipient_name === agentName && msg.sender_name !== 'user') {
+                        text = `[Message from ${msg.sender_name}]: ${msg.question}`;
+                    }
+                    else if (msg.status === 'answered' && msg.response) {
+                        text = `[Inbox Response] to "${msg.question.slice(0, 60)}": ${msg.response}`;
+                    }
+                    else {
+                        continue;
+                    }
+                    try {
+                        exec(`tmux send-keys -t ${target} ${JSON.stringify(text)} Enter`, { stdio: 'ignore', timeout: 5000 });
+                        console.error(`[inject] delivered message ${msg.id} to tmux pane ${target}`);
+                    }
+                    catch (err) {
+                        console.error(`[inject] tmux send-keys failed for message ${msg.id}:`, err);
+                    }
+                }
+            }
+            catch { /* ignore */ }
+        }, POLL_INTERVAL);
+    }
 }

package/dist/sse.d.ts

@@ -1,7 +1,9 @@
-export declare function startSSEServer(): void;
+export declare function startSSEServer(): Promise<void>;
 export declare function markSSEActive(): void;
 /**
  * Broadcast an SSE event. If this process owns the SSE server, send directly.
- * Otherwise, relay via HTTP to the process that does (sidecar on port 3456).
+ * Otherwise, relay via HTTP to the process that does.
  */
 export declare function broadcast(event: string, data: object): void;
+/** Returns the port the SSE server is actively using */
+export declare function getActivePort(): number;

package/dist/sse.js

@@ -1,6 +1,9 @@
 import { createServer } from 'http';
 import { getDb } from './db.js';
 import { logActivity } from './helpers.js';
+const SERVICE_ID = 'taskflow-mcp';
+const MAX_PORT_ATTEMPTS = 10;
+const PROBE_TIMEOUT_MS = 2000;
 const clients = new Set();
 function resolvePort() {
     // CLI arg takes priority: --port 4000
@@ -14,7 +17,27 @@ function resolvePort() {
     }
     return 3456;
 }
-const PORT = resolvePort();
+const PREFERRED_PORT = resolvePort();
+/** The port that is actually serving SSE — either ours or an existing instance's */
+let activePort = PREFERRED_PORT;
+/** Probe a port to check if a TaskFlow service is already running there */
+async function probeTaskFlow(port) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetch(`http://localhost:${port}/healthz`, { signal: controller.signal });
+        if (!res.ok)
+            return false;
+        const body = await res.json();
+        return body.service === SERVICE_ID;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 function jsonResponse(res, status, data) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(data));
@@ -26,7 +49,7 @@ function readBody(req) {
         req.on('end', () => resolve(body));
     });
 }
-export function startSSEServer() {
+export async function startSSEServer() {
     const server = createServer(async (req, res) => {
         // CORS headers for all requests
         res.setHeader('Access-Control-Allow-Origin', '*');
@@ -37,6 +60,11 @@ export function startSSEServer() {
             res.end();
             return;
         }
+        // GET /healthz — identity probe so other instances can detect us
+        if (req.url === '/healthz' && req.method === 'GET') {
+            jsonResponse(res, 200, { service: SERVICE_ID, pid: process.pid });
+            return;
+        }
         if (req.url === '/events' && req.method === 'GET') {
             res.writeHead(200, {
                 'Content-Type': 'text/event-stream',
@@ -58,7 +86,9 @@ export function startSSEServer() {
             const sessions = db.prepare('SELECT * FROM sessions').all();
             const settings = db.prepare('SELECT * FROM settings').all();
             const activityLogs = db.prepare('SELECT * FROM activity_logs ORDER BY created_at DESC LIMIT 200').all();
-            jsonResponse(res, 200, { tasks, projects, sessions, settings, activityLogs });
+            const agentMessages = db.prepare('SELECT * FROM agent_messages ORDER BY created_at DESC LIMIT 100').all();
+            const agentRegistry = db.prepare('SELECT * FROM agent_registry ORDER BY connected_at DESC').all();
+            jsonResponse(res, 200, { tasks, projects, sessions, settings, activityLogs, agentMessages, agentRegistry });
             return;
         }
         // ─── Mutation endpoints ───────────────────────────────────────────
@@ -69,6 +99,8 @@ export function startSSEServer() {
             db.exec('DELETE FROM projects');
             db.exec('DELETE FROM notifications');
             db.exec('DELETE FROM activity_logs');
+            db.exec('DELETE FROM agent_messages');
+            db.exec('DELETE FROM agent_registry');
             logActivity('data_cleared', 'All data cleared via UI', { entityType: 'system' });
             broadcast('data_cleared', { entity: 'system', action: 'data_cleared', payload: {} });
             jsonResponse(res, 200, { cleared: true });
@@ -234,18 +266,121 @@ export function startSSEServer() {
             jsonResponse(res, 200, { relayed: true });
             return;
         }
+        // POST /api/agent-messages/:id/respond — user responds to an agent question
+        const agentRespondMatch = req.url?.match(/^\/api\/agent-messages\/(\d+)\/respond$/);
+        if (agentRespondMatch && req.method === 'POST') {
+            const db = getDb();
+            const id = Number(agentRespondMatch[1]);
+            const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+            if (!message) {
+                jsonResponse(res, 404, { error: 'Message not found' });
+                return;
+            }
+            if (message.status === 'answered') {
+                jsonResponse(res, 400, { error: 'Already answered' });
+                return;
+            }
+            const body = JSON.parse(await readBody(req));
+            const response = body.response;
+            if (!response) {
+                jsonResponse(res, 400, { error: 'Response is required' });
+                return;
+            }
+            const ts = new Date().toISOString();
+            db.prepare('UPDATE agent_messages SET response = ?, status = ?, answered_at = ? WHERE id = ?')
+                .run(response, 'answered', ts, id);
+            const updated = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+            broadcast('agent_question_answered', { entity: 'agent_message', action: 'agent_question_answered', payload: updated });
+            logActivity('agent_question_answered', `Responded to: ${message.question}`, { entityType: 'agent_message', entityId: id });
+            jsonResponse(res, 200, updated);
+            return;
+        }
+        // POST /api/agent-messages/:id/dismiss — dismiss without responding (answered in terminal)
+        const agentDismissMatch = req.url?.match(/^\/api\/agent-messages\/(\d+)\/dismiss$/);
+        if (agentDismissMatch && req.method === 'POST') {
+            const db = getDb();
+            const id = Number(agentDismissMatch[1]);
+            const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+            if (!message) {
+                jsonResponse(res, 404, { error: 'Message not found' });
+                return;
+            }
+            if (message.status !== 'pending') {
+                jsonResponse(res, 400, { error: 'Message is not pending' });
+                return;
+            }
+            const ts = new Date().toISOString();
+            db.prepare('UPDATE agent_messages SET status = ?, answered_at = ? WHERE id = ?')
+                .run('dismissed', ts, id);
+            const updated = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+            broadcast('agent_question_answered', { entity: 'agent_message', action: 'agent_question_answered', payload: updated });
+            jsonResponse(res, 200, updated);
+            return;
+        }
+        // POST /api/agent-messages/send — user sends a message to an agent
+        if (req.url === '/api/agent-messages/send' && req.method === 'POST') {
+            const db = getDb();
+            const body = JSON.parse(await readBody(req));
+            const { recipient, message: msgText, projectId } = body;
+            if (!recipient || !msgText) {
+                jsonResponse(res, 400, { error: 'recipient and message are required' });
+                return;
+            }
+            const ts = new Date().toISOString();
+            const result = db.prepare(`INSERT INTO agent_messages (project_id, question, sender_name, recipient_name, status, created_at)
+         VALUES (?, ?, 'user', ?, 'pending', ?)`).run(projectId ?? null, msgText, recipient, ts);
+            const id = result.lastInsertRowid;
+            const msg = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+            broadcast('agent_question', { entity: 'agent_message', action: 'agent_question', payload: msg });
+            jsonResponse(res, 200, msg);
+            return;
+        }
         res.writeHead(404);
         res.end('Not Found');
     });
-    server.on('error', (err) => {
-        if (err.code === 'EADDRINUSE') {
-            // Another MCP instance already owns this port — skip SSE, MCP tools still work
-            return;
+    // Try ports sequentially: probe occupied ports to see if they're ours
+    await new Promise((resolve) => {
+        let attempt = 0;
+        function tryPort(port) {
+            if (attempt >= MAX_PORT_ATTEMPTS) {
+                console.error(`[SSE] failed to bind after ${MAX_PORT_ATTEMPTS} attempts (ports ${PREFERRED_PORT}–${port - 1})`);
+                resolve();
+                return;
+            }
+            server.once('error', async (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    const isTaskFlow = await probeTaskFlow(port);
+                    if (isTaskFlow) {
+                        // Another TaskFlow instance owns this port — connect to it instead
+                        activePort = port;
+                        console.log(`[SSE] port ${port} owned by another TaskFlow instance (pid probe) — using it`);
+                        resolve();
+                    }
+                    else {
+                        // Not ours — try next port
+                        console.log(`[SSE] port ${port} in use by non-TaskFlow service — trying ${port + 1}`);
+                        attempt++;
+                        tryPort(port + 1);
+                    }
+                }
+                else {
+                    console.error('[SSE] unexpected server error:', err.message);
+                    resolve();
+                }
+            });
+            server.listen(port, '0.0.0.0', () => {
+                activePort = port;
+                markSSEActive();
+                if (port !== PREFERRED_PORT) {
+                    console.log(`[SSE] listening on fallback port ${port} (preferred ${PREFERRED_PORT} was unavailable)`);
+                }
+                else {
+                    console.log(`[SSE] listening on port ${port}`);
+                }
+                resolve();
+            });
         }
-        // Unexpected error — still don't crash the MCP process
-    });
-    server.listen(PORT, '0.0.0.0', () => {
-        markSSEActive();
+        tryPort(PREFERRED_PORT);
     });
 }
 /** Broadcast directly to connected SSE clients in this process */
@@ -262,7 +397,7 @@ export function markSSEActive() {
 }
 /**
  * Broadcast an SSE event. If this process owns the SSE server, send directly.
- * Otherwise, relay via HTTP to the process that does (sidecar on port 3456).
+ * Otherwise, relay via HTTP to the process that does.
  */
 export function broadcast(event, data) {
     if (sseServerActive && clients.size > 0) {
@@ -271,7 +406,7 @@ export function broadcast(event, data) {
     else {
         // Relay to the SSE server owner via HTTP
         const body = JSON.stringify({ event, data });
-        fetch(`http://localhost:${PORT}/api/broadcast`, {
+        fetch(`http://localhost:${activePort}/api/broadcast`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body,
@@ -280,3 +415,7 @@ export function broadcast(event, data) {
         });
     }
 }
+/** Returns the port the SSE server is actively using */
+export function getActivePort() {
+    return activePort;
+}

package/dist/tools/activity.d.ts

@@ -18,6 +18,7 @@ export declare function clearActivityLog(): Promise<{
 export declare function logDebug(params: {
     message: string;
     task_id?: number;
+    project_id?: number;
     detail?: string;
 }): Promise<{
     content: {

package/dist/tools/activity.js

@@ -34,8 +34,11 @@ export async function clearActivityLog() {
 export async function logDebug(params) {
     const db = getDb();
     const now = new Date().toISOString();
+    // task_id takes priority; fall back to project_id
+    const entityType = params.task_id ? 'task' : params.project_id ? 'project' : null;
+    const entityId = params.task_id ?? params.project_id ?? null;
     const result = db.prepare(`INSERT INTO activity_logs (action, title, detail, entity_type, entity_id, created_at)
-     VALUES (?, ?, ?, ?, ?, ?)`).run('debug_log', params.message, params.detail ?? null, params.task_id ? 'task' : null, params.task_id ?? null, now);
+     VALUES (?, ?, ?, ?, ?, ?)`).run('debug_log', params.message, params.detail ?? null, entityType, entityId, now);
     const entry = db.prepare('SELECT * FROM activity_logs WHERE id = ?').get(result.lastInsertRowid);
     broadcastChange('activity', 'activity_logged', entry);
     return successResponse({ id: result.lastInsertRowid, message: params.message });
@@ -48,9 +51,10 @@ export function registerActivityTools(server) {
         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());
-    server.tool('log_debug', 'Log a debug entry to the activity log. Use this while debugging to record what you are investigating, what you tried, what you found, and your reasoning. Optionally link to a task. These entries appear in the Activity Pulse in the UI.', {
+    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, what you tried'),
+        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));
 }

package/dist/tools/agent-inbox.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** The name assigned to this agent after registration */
+declare let myAgentName: string | null;
+export { myAgentName };
+export declare function registerAgentInboxTools(server: McpServer): void;

package/dist/tools/agent-inbox.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { getDb } from '../db.js';
+import { logActivity, errorResponse, successResponse, now, broadcastChange } from '../helpers.js';
+import { registerAgent as doRegister, getAgent, listAgents } from '../agent-registry.js';
+/** The name assigned to this agent after registration */
+let myAgentName = null;
+/** Get or auto-register the agent name */
+function ensureRegistered() {
+    if (!myAgentName) {
+        myAgentName = doRegister();
+    }
+    return myAgentName;
+}
+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) => {
+        myAgentName = doRegister({ customName: params.name });
+        return successResponse({ name: myAgentName, message: `Registered as "${myAgentName}"` });
+    });
+    server.tool('ask_user', 'Post a question to the TaskFlow Agent Inbox for the user to answer remotely. Returns immediately with the message ID. The question appears in the Agent Inbox UI with full context and optional quick-tap choices. After posting, use check_response to retrieve the user\'s answer. Always tell the user you posted a question so they know to check the inbox.', {
+        project_id: z.number().describe('Project ID to attach the question to'),
+        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) => {
+        const db = getDb();
+        const project = db.prepare('SELECT id FROM projects WHERE id = ?').get(params.project_id);
+        if (!project)
+            return errorResponse(`Project ${params.project_id} not found`, 'NOT_FOUND');
+        const senderName = ensureRegistered();
+        const ts = now();
+        const result = db.prepare(`INSERT INTO agent_messages (project_id, question, context, choices, sender_name, recipient_name, agent_pid, status, created_at)
+         VALUES (?, ?, ?, ?, ?, 'user', ?, 'pending', ?)`).run(params.project_id, params.question, params.context ?? null, params.choices ? JSON.stringify(params.choices) : null, senderName, process.ppid, ts);
+        const id = result.lastInsertRowid;
+        const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+        broadcastChange('agent_message', 'agent_question', message);
+        logActivity('agent_question', params.question, { entityType: 'agent_message', entityId: id });
+        return successResponse({
+            id,
+            status: 'pending',
+            sender: senderName,
+            message: `Question posted to Agent Inbox (id: ${id}). Use check_response(${id}) to retrieve the user's answer.`,
+        });
+    });
+    server.tool('check_response', 'Check if the user has responded to a previously posted agent question. Returns the response if answered, or status "pending" if still waiting.', {
+        message_id: z.number().describe('The agent message ID returned by ask_user'),
+    }, async (params) => {
+        const db = getDb();
+        const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(params.message_id);
+        if (!message)
+            return errorResponse(`Message ${params.message_id} not found`, 'NOT_FOUND');
+        if (message.status === 'answered') {
+            return successResponse({
+                id: message.id, status: 'answered', response: message.response,
+                question: message.question, answered_at: message.answered_at,
+            });
+        }
+        return successResponse({
+            id: message.id, status: 'pending', question: message.question,
+            message: 'User has not responded yet. Try again later or continue with other work.',
+        });
+    });
+    server.tool('send_to_agent', 'Send a message to another agent by name. Returns immediately. The recipient agent will receive the message in their terminal (if running in tmux).', {
+        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) => {
+        const db = getDb();
+        const senderName = ensureRegistered();
+        const recipient = getAgent(params.recipient);
+        if (!recipient)
+            return errorResponse(`Agent "${params.recipient}" not found`, 'NOT_FOUND');
+        const ts = now();
+        const result = db.prepare(`INSERT INTO agent_messages (project_id, question, context, sender_name, recipient_name, status, created_at)
+         VALUES (NULL, ?, ?, ?, ?, 'pending', ?)`).run(params.message, params.context ?? null, senderName, params.recipient, ts);
+        const id = result.lastInsertRowid;
+        const msg = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+        broadcastChange('agent_message', 'agent_question', msg);
+        return successResponse({ id, sender: senderName, recipient: params.recipient, status: 'pending' });
+    });
+    server.tool('check_messages', 'Check for incoming messages from users or other agents addressed to this agent.', {}, 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);
+        return successResponse({
+            agent: name,
+            count: messages.length,
+            messages: messages.map(m => ({
+                id: m.id, sender: m.sender_name, question: m.question,
+                context: m.context, choices: m.choices ? JSON.parse(m.choices) : null,
+                created_at: m.created_at,
+            })),
+        });
+    });
+    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) => {
+        const agents = listAgents(params.status);
+        return successResponse(agents);
+    });
+}

package/dist/tools/agent.js

@@ -12,8 +12,8 @@ export async function getAgentInstructions() {
     const instructions = {
         role: 'TaskFlow — local-first task & time tracker with MCP integration.',
         startup: [
-            'search_projects to find the current project (try name variants; confirm with user if ambiguous)',
-            'list_tasks status="in_progress" and status="blocked"',
+            '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',
         ],
         state: {
@@ -24,26 +24,43 @@ export async function getAgentInstructions() {
             unread: unreadNotifs,
         },
         rules: [
+            // Project discovery
+            'The project name should be derived from the working directory folder name. Always search_projects first. If no match, create the project using create_project with the folder name. If multiple matches, present them to the user and ask which one to use.',
             // Task tracking
             'Proactively create tasks for ALL substantial work — features, bugs, refactors, AND debugging/investigation. Debugging is real work: create a task for it (e.g. "Debug: SSE connection dropping"), start a timer, and track it the same way you would a feature. search_tasks first to avoid duplicates. Link tasks to the confirmed project.',
             'Timer lifecycle: start_timer → work → stop_timer(final_status). Use "done"/"partial_done"/"blocked". pause_timer when waiting for input. This applies equally to debugging tasks — start a timer before investigating, stop it when resolved or blocked.',
             'MUST stop_timer with "done" when work is complete. Never leave finished tasks in "in_progress" or "paused". This includes debugging tasks — when the bug is fixed or the investigation concludes, stop the timer.',
+            // Bugs & post-build debugging
+            'When a user reports a bug or you discover one while testing/building: FIRST search_tasks for an existing related task. If found (even if "done"), move it back to in_progress (update_task_status) — this reopens the task and auto-starts a timer. Then log_debug on that task to document the new bug. If no related task exists, create a new one (e.g. "Bug: sidebar not rendering in light mode") with tag "bug", start the timer, and begin debugging.',
+            'This also applies to post-build issues: after running a build/test and seeing failures, do NOT silently fix them. Open or reopen a task first, log what failed, then fix. The task becomes the paper trail — the user and future agents can see what broke, what was tried, and how it was resolved.',
             // Dependencies
             'Check task dependencies before starting. If any dep is incomplete, set task to "blocked".',
             'After completing a task, check if blocked tasks depending on it can be unblocked.',
             // Prioritization
             'When user is unsure what to work on: list_tasks priority="critical"/"high" status="not_started".',
-            // Logging
-            'ALWAYS log your entire debugging process using log_debug with task_id. Log every stage: issue identification, hypothesis, files read/edited, commands run, errors encountered, fixes attempted, and resolution. This creates a visible trail in the Activity Pulse so users can follow your reasoning in real-time.',
-            'log_debug early and often — not just at the end. Log when you start investigating, when you find a clue, when you edit a file, and when the fix lands. Use Markdown: headings for stages, code blocks for errors/paths, bold for key findings.',
+            // Transparency — CRITICAL
+            'ALWAYS tell the user what commands you are running and why. Before executing a shell command, state: "Running: `<command>`". After significant actions (file edits, installs, config changes), summarize what changed. The user must be able to reconstruct what happened from your messages alone — they should never wonder "what did the agent do?".',
+            'When starting work, briefly state the approach: what you plan to do, which files you expect to touch, and what commands you will run. This gives the user a chance to course-correct before you act.',
+            // Debug logging — comprehensive
+            'ALWAYS log your work using log_debug. Log with a task_id when working on a specific task, or with project_id for project-level observations. Use log_debug as a running journal — it shows up in the Activity Pulse and on the project page so the user (and future agents) can follow your reasoning.',
+            'What to log: **every stage** of your process. When you start investigating, when you form a hypothesis, when you read/edit a file, the exact commands you run (with output snippets), errors encountered, fixes attempted, and the resolution. Log the **path you took**, not just the destination.',
+            'Log early and often — not just at the end. A debug log entry per significant step (e.g. "Read `sse.ts:57` — found the healthz route exists but is unreachable because..."). Use Markdown: `## headings` for stages, `` `code blocks` `` for errors/paths/commands, **bold** for key findings.',
+            'For project-level notes (architecture decisions, setup gotchas, "how to run the app"), use log_debug with project_id instead of task_id. These appear on the project page and serve as living documentation.',
             // Formatting
             'Use Markdown in descriptions — headings, bullets, code blocks, bold. The UI renders it.',
+            // Agent Inbox — remote communication
+            'When you need user input (choices, confirmations, clarifications), ALWAYS do BOTH: (1) ask the question normally in the terminal conversation, AND (2) call ask_user to post it to the Agent Inbox. This lets the user respond from either the terminal or the TaskFlow UI remotely. If the user explicitly tells you not to use the inbox (e.g. "don\'t post to inbox"), skip the ask_user call.',
+            'After calling ask_user, continue your work if possible. The user may respond from the UI, and the response will be delivered to your terminal automatically (if running in tmux). You can also call check_response to poll for the answer.',
+            // 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.',
         ],
         workflow: 'not_started → in_progress (start_timer) → paused (pause_timer) → done/partial_done/blocked (stop_timer)',
         tips: [
             'Filter by tags (list_tasks tag="bug"), search by keyword (search_tasks), get full detail (get_task id).',
             '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.',
         ],
     };
     return successResponse(instructions);

package/dist/types.d.ts

@@ -27,6 +27,17 @@ export declare const NotificationType: z.ZodEnum<{
     error: "error";
 }>;
 export type NotificationType = z.infer<typeof NotificationType>;
+export declare const AgentMessageStatus: z.ZodEnum<{
+    pending: "pending";
+    answered: "answered";
+    dismissed: "dismissed";
+}>;
+export type AgentMessageStatus = z.infer<typeof AgentMessageStatus>;
+export declare const AgentStatus: z.ZodEnum<{
+    connected: "connected";
+    disconnected: "disconnected";
+}>;
+export type AgentStatus = z.infer<typeof AgentStatus>;
 export declare const ActivityAction: z.ZodEnum<{
     task_created: "task_created";
     task_deleted: "task_deleted";
@@ -51,10 +62,14 @@ export declare const ActivityAction: z.ZodEnum<{
     tag_added: "tag_added";
     tag_removed: "tag_removed";
     debug_log: "debug_log";
+    agent_question: "agent_question";
+    agent_question_answered: "agent_question_answered";
+    agent_connected: "agent_connected";
+    agent_disconnected: "agent_disconnected";
 }>;
 export type ActivityAction = z.infer<typeof ActivityAction>;
 export declare const VALID_TRANSITIONS: Record<TaskStatus, TaskStatus[]>;
-export type ErrorCode = 'NOT_FOUND' | 'INVALID_TRANSITION' | 'VALIDATION_ERROR' | 'CYCLE_DETECTED' | 'SESSION_ALREADY_ACTIVE' | 'NO_ACTIVE_SESSION';
+export type ErrorCode = 'NOT_FOUND' | 'INVALID_TRANSITION' | 'VALIDATION_ERROR' | 'CYCLE_DETECTED' | 'SESSION_ALREADY_ACTIVE' | 'NO_ACTIVE_SESSION' | 'ALREADY_ANSWERED';
 export declare const LinkSchema: z.ZodObject<{
     label: z.ZodString;
     url: z.ZodString;

package/dist/types.js

@@ -5,6 +5,8 @@ export const TaskStatus = z.enum([
 export const TaskPriority = z.enum(['low', 'medium', 'high', 'critical']);
 export const ProjectType = z.enum(['active_project', 'project_idea']);
 export const NotificationType = z.enum(['info', 'success', 'warning', 'error']);
+export const AgentMessageStatus = z.enum(['pending', 'answered', 'dismissed']);
+export const AgentStatus = z.enum(['connected', 'disconnected']);
 export const ActivityAction = z.enum([
     'task_created', 'task_deleted', 'task_status_changed', 'task_completed',
     'task_partial_done', 'timer_started', 'timer_paused', 'timer_stopped',
@@ -12,6 +14,8 @@ export const ActivityAction = z.enum([
     'tasks_bulk_created', 'settings_saved', 'data_seeded', 'data_cleared',
     'task_linked', 'task_unlinked', 'dependency_added', 'dependency_removed',
     'link_added', 'tag_added', 'tag_removed', 'debug_log',
+    'agent_question', 'agent_question_answered',
+    'agent_connected', 'agent_disconnected',
 ]);
 export const VALID_TRANSITIONS = {
     not_started: ['in_progress', 'blocked'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalmasonto/taskflow-mcp",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "MCP server for TaskFlow — manage projects, tasks, timers, analytics via AI agents",
   "type": "module",
   "main": "dist/index.js",