@dalmasonto/taskflow-mcp 1.0.11 → 1.0.14

package/dist/agent-registry.d.ts

@@ -8,7 +8,11 @@ interface AgentRow {
     connected_at: string;
     disconnected_at: string | null;
 }
-/** Register an agent. Returns the assigned name. */
+/** Register an agent. Returns the assigned name.
+ *  Uses project_path as the stable identifier — same directory reuses
+ *  disconnected entries, preserving message history across sessions.
+ *  Multiple concurrent agents in the same project get suffixed names.
+ */
 export declare function registerAgent(options?: {
     customName?: string;
 }): string;

package/dist/agent-registry.js

@@ -41,39 +41,43 @@ function generateName(folderName) {
     }
     return `${folderName}:${Date.now()}`;
 }
-/** Register an agent. Returns the assigned name. */
+/** Register an agent. Returns the assigned name.
+ *  Uses project_path as the stable identifier — same directory reuses
+ *  disconnected entries, preserving message history across sessions.
+ *  Multiple concurrent agents in the same project get suffixed names.
+ */
 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 (or rename if customName provided)
-    const existingByPid = db.prepare('SELECT * FROM agent_registry WHERE pid = ? AND status = ?').get(agentPid, 'connected');
-    if (existingByPid) {
-        const tmuxPane = detectTmuxPane(agentPid);
-        if (tmuxPane !== existingByPid.tmux_pane) {
-            db.prepare('UPDATE agent_registry SET tmux_pane = ? WHERE id = ?').run(tmuxPane, existingByPid.id);
-        }
-        // Allow renaming via customName
-        if (options?.customName && options.customName !== existingByPid.name) {
-            db.prepare('UPDATE agent_registry SET name = ? WHERE id = ?').run(options.customName, existingByPid.id);
-            broadcast('agent_connected', { entity: 'agent', action: 'agent_connected', payload: { ...existingByPid, name: options.customName, tmux_pane: tmuxPane ?? existingByPid.tmux_pane } });
-            return options.customName;
-        }
-        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);
+    // Clean up dead agents first so we can reuse their entries
+    checkAgentLiveness();
+    // Find all entries for this project path
+    const entries = db.prepare('SELECT * FROM agent_registry WHERE project_path = ? ORDER BY connected_at DESC').all(projectPath);
+    // Priority 1: Reuse a disconnected entry (preserves history)
+    const disconnected = entries.find(e => e.status === 'disconnected');
+    if (disconnected) {
+        const newName = options?.customName || disconnected.name;
+        const renamed = newName !== disconnected.name;
+        // Update agent_messages if renaming to preserve history
+        if (renamed) {
+            db.prepare('UPDATE agent_messages SET sender_name = ? WHERE sender_name = ?').run(newName, disconnected.name);
+            db.prepare('UPDATE agent_messages SET recipient_name = ? WHERE recipient_name = ?').run(newName, disconnected.name);
+        }
+        db.prepare('UPDATE agent_registry SET name = ?, pid = ?, tmux_pane = ?, status = ?, connected_at = ?, disconnected_at = NULL WHERE id = ?').run(newName, agentPid, tmuxPane, 'connected', ts, disconnected.id);
+        const row = db.prepare('SELECT * FROM agent_registry WHERE id = ?').get(disconnected.id);
+        broadcast('agent_connected', { entity: 'agent', action: 'agent_connected', payload: row });
+        logActivity('agent_connected', `Agent "${newName}" reconnected`, { entityType: 'agent' });
+        return newName;
     }
+    // Priority 2: All entries for this path are connected — this is a concurrent agent
+    // Generate a suffixed name to avoid collision
+    const baseName = options?.customName || folderName;
+    const name = entries.length === 0 ? baseName : generateName(baseName);
+    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' });

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export interface TaskFlowConfig {
+    port: number;
+    host: string;
+    databasePath: string;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    agentLivenessInterval: number;
+    maxPortAttempts: number;
+}
+/** Keys that live in the config file (not SQLite) */
+export declare const SERVER_CONFIG_KEYS: Set<string>;
+export declare function getConfig(): TaskFlowConfig;
+/** Check if a setting key is a server-level config key */
+export declare function isServerConfigKey(key: string): boolean;
+/**
+ * Update a single key in ~/.taskflow_config.json.
+ * Re-reads the file first to avoid clobbering other keys.
+ * Returns the updated config value.
+ */
+export declare function writeConfigKey(key: string, value: unknown): void;

package/dist/config.js

@@ -0,0 +1,108 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { homedir } from 'os';
+/** Keys that live in the config file (not SQLite) */
+export const SERVER_CONFIG_KEYS = new Set([
+    'port',
+    'host',
+    'databasePath',
+    'logLevel',
+    'agentLivenessInterval',
+    'maxPortAttempts',
+]);
+// ─── defaults ────────────────────────────────────────────────────────
+const DEFAULTS = {
+    port: 3456,
+    host: '127.0.0.1',
+    databasePath: '~/.taskflow/taskflow.db',
+    logLevel: 'info',
+    agentLivenessInterval: 30_000,
+    maxPortAttempts: 10,
+};
+// ─── config file path ────────────────────────────────────────────────
+const CONFIG_PATH = resolve(homedir(), '.taskflow_config.json');
+// ─── loader ──────────────────────────────────────────────────────────
+function loadFromFile() {
+    try {
+        const raw = readFileSync(CONFIG_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            console.error(`[config] Warning: ${CONFIG_PATH} is not a JSON object — using defaults`);
+            return {};
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // File doesn't exist — that's fine, use defaults
+            return {};
+        }
+        console.error(`[config] Warning: failed to read ${CONFIG_PATH} — ${err.message}`);
+        return {};
+    }
+}
+function applyCliAndEnvOverrides(config) {
+    // Env vars override config file
+    if (process.env.TASKFLOW_SSE_PORT) {
+        const p = parseInt(process.env.TASKFLOW_SSE_PORT, 10);
+        if (!isNaN(p))
+            config.port = p;
+    }
+    if (process.env.TASKFLOW_DB_PATH) {
+        config.databasePath = process.env.TASKFLOW_DB_PATH;
+    }
+    if (process.env.TASKFLOW_HOST) {
+        config.host = process.env.TASKFLOW_HOST;
+    }
+    if (process.env.TASKFLOW_LOG_LEVEL) {
+        config.logLevel = process.env.TASKFLOW_LOG_LEVEL;
+    }
+    // CLI args take highest priority
+    const portArgIdx = process.argv.indexOf('--port');
+    if (portArgIdx !== -1 && process.argv[portArgIdx + 1]) {
+        const p = parseInt(process.argv[portArgIdx + 1], 10);
+        if (!isNaN(p))
+            config.port = p;
+    }
+    const hostArgIdx = process.argv.indexOf('--host');
+    if (hostArgIdx !== -1 && process.argv[hostArgIdx + 1]) {
+        config.host = process.argv[hostArgIdx + 1];
+    }
+    return config;
+}
+// ─── singleton ───────────────────────────────────────────────────────
+let _config = null;
+export function getConfig() {
+    if (_config)
+        return _config;
+    const fileValues = loadFromFile();
+    _config = applyCliAndEnvOverrides({ ...DEFAULTS, ...fileValues });
+    return _config;
+}
+/** Check if a setting key is a server-level config key */
+export function isServerConfigKey(key) {
+    return SERVER_CONFIG_KEYS.has(key);
+}
+// ─── write-back ──────────────────────────────────────────────────────
+/**
+ * Update a single key in ~/.taskflow_config.json.
+ * Re-reads the file first to avoid clobbering other keys.
+ * Returns the updated config value.
+ */
+export function writeConfigKey(key, value) {
+    let existing = {};
+    try {
+        const raw = readFileSync(CONFIG_PATH, 'utf-8');
+        existing = JSON.parse(raw);
+    }
+    catch {
+        // File doesn't exist or is malformed — start fresh
+    }
+    existing[key] = value;
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+    // Update the in-memory singleton so get_setting reflects the change immediately
+    if (_config && key in DEFAULTS) {
+        _config[key] = value;
+    }
+}

package/dist/db.js

@@ -2,7 +2,7 @@ import Database from 'better-sqlite3';
 import { mkdirSync } from 'fs';
 import { dirname, resolve } from 'path';
 import { homedir } from 'os';
-const DEFAULT_DB_PATH = '~/.taskflow/taskflow.db';
+import { getConfig } from './config.js';
 let db = null;
 // Expands ~/path to $HOME/path. Only handles ~/ prefix, not ~user/ paths.
 export function resolvePath(p) {
@@ -14,7 +14,7 @@ export function resolvePath(p) {
 export function getDb() {
     if (db)
         return db;
-    return initDb(process.env.TASKFLOW_DB_PATH || DEFAULT_DB_PATH);
+    return initDb(getConfig().databasePath);
 }
 // For testing: initialize with a specific path (use ':memory:' for tests)
 export function initDb(path) {
@@ -131,6 +131,18 @@ function initSchema(db) {
     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);
+    CREATE INDEX IF NOT EXISTS idx_agent_registry_project_path ON agent_registry(project_path);
+
+    CREATE TABLE IF NOT EXISTS tool_executions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      tool_name TEXT NOT NULL,
+      duration_ms INTEGER NOT NULL,
+      success INTEGER NOT NULL DEFAULT 1,
+      error_message TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_tool_executions_tool_name ON tool_executions(tool_name);
+    CREATE INDEX IF NOT EXISTS idx_tool_executions_created_at ON tool_executions(created_at);
   `);
     // Migrations — add columns that may be missing on existing databases
     const cols = db.prepare("PRAGMA table_info(agent_messages)").all();
@@ -184,6 +196,15 @@ function initSchema(db) {
         }
     }
     catch { /* table may not exist yet */ }
+    // Migration: add allowed_tools and denied_tools to tasks
+    const taskCols = db.prepare("PRAGMA table_info(tasks)").all();
+    const taskColNames = new Set(taskCols.map(c => c.name));
+    if (!taskColNames.has('allowed_tools')) {
+        db.exec("ALTER TABLE tasks ADD COLUMN allowed_tools TEXT");
+    }
+    if (!taskColNames.has('denied_tools')) {
+        db.exec("ALTER TABLE tasks ADD COLUMN denied_tools TEXT");
+    }
 }
 export function closeDb() {
     if (db) {

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { getConfig } from './config.js';
 import { startSSEServer } from './sse.js';
 import { getDb } from './db.js';
 import { broadcast } from './sse.js';
@@ -34,13 +35,14 @@ cleanupOrphanedSessions();
 // 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
+const cfg = getConfig();
 setInterval(async () => {
     try {
         const { checkAgentLiveness } = await import('./agent-registry.js');
         checkAgentLiveness();
     }
     catch { /* ignore */ }
-}, 30_000);
+}, cfg.agentLivenessInterval);
 // Only start MCP stdio transport when not in http-only mode
 if (!httpOnly) {
     const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
@@ -54,10 +56,74 @@ if (!httpOnly) {
     const { registerSettingsTools } = await import('./tools/settings.js');
     const { registerAgentTools } = await import('./tools/agent.js');
     const { registerAgentInboxTools } = await import('./tools/agent-inbox.js');
+    const { registerTerminalTools } = await import('./tools/terminal.js');
+    const { registerResources } = await import('./resources.js');
+    const { registerCheckpointTools } = await import('./tools/checkpoint.js');
     const server = new McpServer({
         name: 'taskflow',
         version: '1.0.0',
     });
+    // Wrap server.tool() to track execution time and log failures
+    const originalTool = server.tool.bind(server);
+    server.tool = function (...args) {
+        const toolName = args[0];
+        // Find the callback (always the last argument, and it's a function)
+        const cbIndex = args.length - 1;
+        const originalCb = args[cbIndex];
+        if (typeof originalCb === 'function') {
+            args[cbIndex] = async (...cbArgs) => {
+                // Check task-scoped tool allowlists if a timer is active
+                try {
+                    const db = getDb();
+                    const activeSession = db.prepare("SELECT task_id FROM sessions WHERE end IS NULL ORDER BY start DESC LIMIT 1").get();
+                    if (activeSession) {
+                        const task = db.prepare("SELECT allowed_tools, denied_tools FROM tasks WHERE id = ?").get(activeSession.task_id);
+                        if (task) {
+                            if (task.denied_tools) {
+                                const denied = JSON.parse(task.denied_tools);
+                                if (denied.includes(toolName)) {
+                                    return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: `Tool "${toolName}" is denied for task #${activeSession.task_id}`, code: 'TOOL_DENIED' }) }] };
+                                }
+                            }
+                            if (task.allowed_tools) {
+                                const allowed = JSON.parse(task.allowed_tools);
+                                if (!allowed.includes(toolName)) {
+                                    return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: `Tool "${toolName}" is not in the allowlist for task #${activeSession.task_id}`, code: 'TOOL_NOT_ALLOWED' }) }] };
+                                }
+                            }
+                        }
+                    }
+                }
+                catch { /* don't break tool execution on allowlist check failure */ }
+                const start = Date.now();
+                try {
+                    const result = await originalCb(...cbArgs);
+                    const duration = Date.now() - start;
+                    // Record execution and broadcast event
+                    try {
+                        const ts = new Date().toISOString();
+                        const db = getDb();
+                        db.prepare('INSERT INTO tool_executions (tool_name, duration_ms, success, created_at) VALUES (?, ?, 1, ?)').run(toolName, duration, ts);
+                        broadcast('tool_executed', { entity: 'tool', action: 'tool_executed', payload: { tool_name: toolName, duration_ms: duration, success: true, created_at: ts } });
+                    }
+                    catch { /* don't break tool execution */ }
+                    return result;
+                }
+                catch (err) {
+                    const duration = Date.now() - start;
+                    try {
+                        const ts = new Date().toISOString();
+                        const db = getDb();
+                        db.prepare('INSERT INTO tool_executions (tool_name, duration_ms, success, error_message, created_at) VALUES (?, ?, 0, ?, ?)').run(toolName, duration, err.message ?? String(err), ts);
+                        broadcast('tool_failed', { entity: 'tool', action: 'tool_failed', payload: { tool_name: toolName, duration_ms: duration, success: false, error: err.message, created_at: ts } });
+                    }
+                    catch { /* don't break tool execution */ }
+                    throw err;
+                }
+            };
+        }
+        return originalTool.apply(server, args);
+    };
     registerAgentTools(server);
     registerTaskTools(server);
     registerProjectTools(server);
@@ -67,6 +133,9 @@ if (!httpOnly) {
     registerNotificationTools(server);
     registerSettingsTools(server);
     registerAgentInboxTools(server);
+    registerTerminalTools(server);
+    registerCheckpointTools(server);
+    registerResources(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const { registerAgent, unregisterAgent } = await import('./agent-registry.js');

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerResources(server: McpServer): void;

package/dist/resources.js

@@ -0,0 +1,76 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getDb } from './db.js';
+export function registerResources(server) {
+    // ─── Projects Resource ──────────────────────────────────────────────
+    server.resource('projects', new ResourceTemplate('taskflow://projects/{id}', {
+        list: async () => {
+            const db = getDb();
+            const projects = db.prepare('SELECT * FROM projects ORDER BY updated_at DESC').all();
+            return {
+                resources: projects.map(p => ({
+                    uri: `taskflow://projects/${p.id}`,
+                    name: p.name,
+                    description: p.description ?? undefined,
+                    mimeType: 'application/json',
+                })),
+            };
+        },
+    }), { description: 'TaskFlow projects', mimeType: 'application/json' }, async (uri, variables) => {
+        const db = getDb();
+        const id = Number(variables.id);
+        const project = db.prepare('SELECT * FROM projects WHERE id = ?').get(id);
+        if (!project) {
+            return { contents: [{ uri: uri.href, text: JSON.stringify({ error: 'Project not found' }), mimeType: 'application/json' }] };
+        }
+        // Include task count and recent tasks
+        const taskCount = db.prepare('SELECT COUNT(*) as count FROM tasks WHERE project_id = ?').get(id);
+        const recentTasks = db.prepare('SELECT id, title, status, priority FROM tasks WHERE project_id = ? ORDER BY updated_at DESC LIMIT 10').all(id);
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: JSON.stringify({ ...project, task_count: taskCount.count, recent_tasks: recentTasks }, null, 2),
+                    mimeType: 'application/json',
+                }],
+        };
+    });
+    // ─── Tasks Resource ─────────────────────────────────────────────────
+    server.resource('tasks', new ResourceTemplate('taskflow://tasks/{id}', {
+        list: async () => {
+            const db = getDb();
+            // List active tasks (not done) for discoverability
+            const tasks = db.prepare("SELECT * FROM tasks WHERE status != 'done' ORDER BY updated_at DESC LIMIT 50").all();
+            return {
+                resources: tasks.map(t => ({
+                    uri: `taskflow://tasks/${t.id}`,
+                    name: `[${t.status}] ${t.title}`,
+                    description: t.description?.slice(0, 100) ?? undefined,
+                    mimeType: 'application/json',
+                })),
+            };
+        },
+    }), { description: 'TaskFlow tasks', mimeType: 'application/json' }, async (uri, variables) => {
+        const db = getDb();
+        const id = Number(variables.id);
+        const task = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+        if (!task) {
+            return { contents: [{ uri: uri.href, text: JSON.stringify({ error: 'Task not found' }), mimeType: 'application/json' }] };
+        }
+        // Include time tracking and dependencies
+        const sessions = db.prepare('SELECT * FROM sessions WHERE task_id = ? ORDER BY start DESC LIMIT 5').all(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(id);
+        const deps = db.prepare('SELECT dependency_id FROM task_dependencies WHERE task_id = ?').all(id);
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: JSON.stringify({
+                        ...task,
+                        tags: task.tags ? JSON.parse(task.tags) : [],
+                        total_time_ms: totalTime.total ?? 0,
+                        recent_sessions: sessions,
+                        dependencies: deps.map(d => d.dependency_id),
+                    }, null, 2),
+                    mimeType: 'application/json',
+                }],
+        };
+    });
+}

package/dist/sse.js

@@ -1,23 +1,25 @@
 import { createServer } from 'http';
+import { execFileSync } from 'child_process';
 import { getDb } from './db.js';
 import { logActivity } from './helpers.js';
+import { getConfig } from './config.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
-    const portArgIdx = process.argv.indexOf('--port');
-    if (portArgIdx !== -1 && process.argv[portArgIdx + 1]) {
-        return parseInt(process.argv[portArgIdx + 1], 10);
+// ─── Event buffer for Last-Event-ID replay ──────────────────────────
+const EVENT_BUFFER_SIZE = 200;
+let eventIdCounter = 0;
+const eventBuffer = [];
+function bufferEvent(event, data) {
+    const id = ++eventIdCounter;
+    eventBuffer.push({ id, event, data });
+    if (eventBuffer.length > EVENT_BUFFER_SIZE) {
+        eventBuffer.shift();
     }
-    // Then env var
-    if (process.env.TASKFLOW_SSE_PORT) {
-        return parseInt(process.env.TASKFLOW_SSE_PORT, 10);
-    }
-    return 3456;
+    return id;
 }
-const PREFERRED_PORT = resolvePort();
+const cfg = getConfig();
+const PREFERRED_PORT = cfg.port;
 /** 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 */
@@ -73,6 +75,14 @@ export async function startSSEServer() {
             });
             // Send initial connection event
             res.write('event: connected\ndata: {}\n\n');
+            // Replay missed events if client sends Last-Event-ID
+            const lastEventId = req.headers['last-event-id'];
+            if (lastEventId && typeof lastEventId === 'string') {
+                const missed = eventBuffer.filter(e => e.id > Number(lastEventId));
+                for (const e of missed) {
+                    res.write(`id: ${e.id}\nevent: ${e.event}\ndata: ${e.data}\n\n`);
+                }
+            }
             clients.add(res);
             req.on('close', () => {
                 clients.delete(res);
@@ -337,6 +347,77 @@ export async function startSSEServer() {
             jsonResponse(res, 200, msg);
             return;
         }
+        // GET /api/terminal/:agentName/capture — capture terminal content via tmux
+        const captureMatch = req.url?.match(/^\/api\/terminal\/([^/]+)\/capture$/);
+        if (captureMatch && req.method === 'GET') {
+            const agentName = decodeURIComponent(captureMatch[1]);
+            const db = getDb();
+            const agent = db.prepare('SELECT * FROM agent_registry WHERE name = ?').get(agentName);
+            if (!agent) {
+                jsonResponse(res, 404, { error: `Agent "${agentName}" not found` });
+                return;
+            }
+            if (!agent.tmux_pane) {
+                jsonResponse(res, 400, { error: `Agent "${agentName}" has no tmux pane` });
+                return;
+            }
+            try {
+                const output = execFileSync('tmux', ['capture-pane', '-p', '-t', agent.tmux_pane], { timeout: 5000 }).toString();
+                jsonResponse(res, 200, { agent: agentName, pane: agent.tmux_pane, content: output });
+            }
+            catch (err) {
+                jsonResponse(res, 500, { error: `Failed to capture pane: ${err.message}` });
+            }
+            return;
+        }
+        // POST /api/terminal/:agentName/send-keys — inject raw keystrokes into agent's tmux pane
+        const sendKeysMatch = req.url?.match(/^\/api\/terminal\/([^/]+)\/send-keys$/);
+        if (sendKeysMatch && req.method === 'POST') {
+            const agentName = decodeURIComponent(sendKeysMatch[1]);
+            const db = getDb();
+            const agent = db.prepare('SELECT * FROM agent_registry WHERE name = ?').get(agentName);
+            if (!agent) {
+                jsonResponse(res, 404, { error: `Agent "${agentName}" not found` });
+                return;
+            }
+            if (!agent.tmux_pane) {
+                jsonResponse(res, 400, { error: `Agent "${agentName}" has no tmux pane` });
+                return;
+            }
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                jsonResponse(res, 400, { error: 'Invalid JSON body' });
+                return;
+            }
+            const keys = body.keys;
+            const enter = body.enter !== false; // default: send Enter after keys
+            if (typeof keys !== 'string') {
+                jsonResponse(res, 400, { error: 'keys must be a string' });
+                return;
+            }
+            try {
+                const args = ['send-keys', '-t', agent.tmux_pane, keys];
+                if (enter)
+                    args.push('Enter');
+                execFileSync('tmux', args, { stdio: 'ignore', timeout: 5000 });
+                logActivity('terminal_send_keys', `Sent keys to ${agentName}: ${keys.slice(0, 50)}`, { entityType: 'agent' });
+                jsonResponse(res, 200, { agent: agentName, pane: agent.tmux_pane, keys, enter, sent: true });
+            }
+            catch (err) {
+                jsonResponse(res, 500, { error: `Failed to send keys: ${err.message}` });
+            }
+            return;
+        }
+        // GET /api/terminal/agents — list agents with tmux panes for terminal interaction
+        if (req.url === '/api/terminal/agents' && req.method === 'GET') {
+            const db = getDb();
+            const agents = db.prepare("SELECT name, tmux_pane, status, pid FROM agent_registry WHERE tmux_pane IS NOT NULL ORDER BY connected_at DESC").all();
+            jsonResponse(res, 200, agents);
+            return;
+        }
         res.writeHead(404);
         res.end('Not Found');
     });
@@ -344,8 +425,8 @@ export async function startSSEServer() {
     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})`);
+            if (attempt >= cfg.maxPortAttempts) {
+                console.error(`[SSE] failed to bind after ${cfg.maxPortAttempts} attempts (ports ${PREFERRED_PORT}–${port - 1})`);
                 resolve();
                 return;
             }
@@ -370,9 +451,21 @@ export async function startSSEServer() {
                     resolve();
                 }
             });
-            server.listen(port, '0.0.0.0', () => {
+            server.listen(port, cfg.host, () => {
                 activePort = port;
                 markSSEActive();
+                // Heartbeat — keeps connections alive and detects stale clients
+                setInterval(() => {
+                    const ping = `:ping ${Date.now()}\n\n`;
+                    for (const client of clients) {
+                        try {
+                            client.write(ping);
+                        }
+                        catch {
+                            clients.delete(client);
+                        }
+                    }
+                }, 30_000);
                 if (port !== PREFERRED_PORT) {
                     console.log(`[SSE] listening on fallback port ${port} (preferred ${PREFERRED_PORT} was unavailable)`);
                 }
@@ -387,7 +480,9 @@ export async function startSSEServer() {
 }
 /** Broadcast directly to connected SSE clients in this process */
 function broadcastLocal(event, data) {
-    const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+    const dataStr = JSON.stringify(data);
+    const id = bufferEvent(event, dataStr);
+    const message = `id: ${id}\nevent: ${event}\ndata: ${dataStr}\n\n`;
     for (const client of clients) {
         client.write(message);
     }
@@ -412,8 +507,8 @@ export function broadcast(event, data) {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body,
-        }).catch(() => {
-            // SSE server not running — silently skip
+        }).catch((err) => {
+            console.error(`[SSE] broadcast relay to port ${activePort} failed: ${err.message}`);
         });
     }
 }