let-them-talk 3.2.2 → 3.3.0

package/README.md

@@ -0,0 +1,242 @@
+# Let Them Talk
+
+[![npm version](https://img.shields.io/npm/v/let-them-talk.svg)](https://www.npmjs.com/package/let-them-talk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**MCP server + web dashboard that lets AI CLI agents talk to each other.**
+
+Open two (or more) Claude Code, Gemini CLI, or Codex CLI terminals — and let them collaborate, debate, review code, or divide tasks. Watch the conversation unfold in a real-time web dashboard with a kanban board, agent monitoring, and message injection.
+
+## Quick Start
+
+```bash
+# 1. Install in any project
+npx let-them-talk init
+
+# 2. Launch the web dashboard
+npx let-them-talk dashboard
+
+# 3. In Terminal 1: tell the agent to register as "A", say hello, then call listen()
+# 4. In Terminal 2: tell the agent to register as "B", then call listen()
+```
+
+Or use a template for guided setup:
+
+```bash
+npx let-them-talk init --template team    # Coordinator + Researcher + Coder
+npx let-them-talk init --template review  # Author + Reviewer
+npx let-them-talk init --template debate  # Pro + Con
+npx let-them-talk templates               # List all templates
+```
+
+## How It Works
+
+```
+Terminal 1 (Claude Code)          Terminal 2 (Gemini CLI)          Terminal 3 (Codex CLI)
+        |                                 |                                |
+        v                                 v                                v
+   MCP Server                        MCP Server                      MCP Server
+   (stdio process)                   (stdio process)                 (stdio process)
+        |                                 |                                |
+        +------------- Shared Filesystem (.agent-bridge/) ----------------+
+                       |  messages.jsonl  |  history.jsonl  |
+                       |  agents.json     |  tasks.json     |
+                       |  profiles.json   |  workflows.json |
+                       |  workspaces/     |  plugins/       |
+                                    |
+                                    v
+                        Web Dashboard (localhost:3000)
+                        Real-time SSE + Agent monitoring
+                        Tasks + Workspaces + Workflows + Plugins
+```
+
+Each CLI terminal spawns its own MCP server process via stdio. All processes read/write to a shared `.agent-bridge/` directory. The dashboard monitors the same files via Server-Sent Events for real-time updates.
+
+## Features
+
+### 27 MCP Tools + Plugins
+
+**Messaging**
+
+| Tool | Description |
+|------|-------------|
+| `register` | Set agent identity (any name, optional provider) |
+| `list_agents` | Show all agents with status, profiles, branches |
+| `send_message` | Send to specific agent (auto-routes with 2) |
+| `broadcast` | Send to all agents at once |
+| `wait_for_reply` | Block until message arrives (5min timeout) |
+| `listen` | Block indefinitely — never times out |
+| `check_messages` | Non-blocking peek at inbox |
+| `ack_message` | Confirm message was processed |
+| `get_history` | View conversation with thread/branch filter |
+| `get_summary` | Condensed conversation recap |
+| `handoff` | Transfer work to another agent with context |
+| `share_file` | Send file contents to another agent |
+| `reset` | Clear data (auto-archives first) |
+
+**Tasks & Workflows**
+
+| Tool | Description |
+|------|-------------|
+| `create_task` | Create and assign tasks |
+| `update_task` | Update task status (pending/in_progress/done/blocked) |
+| `list_tasks` | View tasks with filters |
+| `create_workflow` | Create multi-step pipeline with assignees |
+| `advance_workflow` | Complete current step, auto-handoff to next |
+| `workflow_status` | Get workflow progress |
+
+**Profiles & Workspaces**
+
+| Tool | Description |
+|------|-------------|
+| `update_profile` | Set display name, avatar, bio, role |
+| `workspace_write` | Write to your key-value workspace (50 keys, 100KB/value) |
+| `workspace_read` | Read workspace entries (yours or another agent's) |
+| `workspace_list` | List workspace keys |
+
+**Conversation Branching**
+
+| Tool | Description |
+|------|-------------|
+| `fork_conversation` | Fork conversation at any message point |
+| `switch_branch` | Switch to a different branch |
+| `list_branches` | List all branches with message counts |
+
+### Web Dashboard (4 tabs)
+
+- **Messages** — SSE-powered real-time feed, full markdown, message grouping, date separators, bookmarks, pins, emoji reactions, search, conversation replay
+- **Tasks** — Kanban board (pending/in_progress/done/blocked), status updates from dashboard
+- **Workspaces** — Per-agent key-value browser with collapsible accordion UI
+- **Workflows** — Horizontal pipeline visualization, advance/skip steps from dashboard
+- **Agent monitoring** — active/sleeping/dead/listening status, profile popups with avatars, provider badges, activity heatmap
+- **Conversation branching** — branch tabs, switch between conversation forks
+- **Message injection** — send messages or broadcast to agents from the browser
+- **Plugin management** — plugin cards with enable/disable toggles
+- **Export** — shareable HTML or Markdown download
+- **Multi-project** — monitor multiple folders + auto-discover
+- **Dark/light theme** — toggle with localStorage persistence
+- **Mobile responsive** — hamburger sidebar, works on phones and tablets
+
+### Reliability
+
+- **Heartbeat** — 10s pings track agent liveness
+- **Auto-compact** — message queue cleaned when > 500 lines
+- **Auto-archive** — conversations saved before reset
+- **Context hints** — warns agents when conversation gets long
+- **Dead recipient warnings** — alerts when sending to offline agents
+- **Clean exit** — agents deregister on process exit
+
+## Agent Templates
+
+Pre-built team configurations with ready-to-paste prompts:
+
+| Template | Agents | Best For |
+|----------|--------|----------|
+| `pair` | A, B | Simple conversations, brainstorming |
+| `team` | Coordinator, Researcher, Coder | Complex features, research + implementation |
+| `review` | Author, Reviewer | Code review with structured feedback |
+| `debate` | Pro, Con | Evaluating trade-offs and decisions |
+
+## CLI Commands
+
+```bash
+npx let-them-talk init                    # Auto-detect CLI and configure
+npx let-them-talk init --all              # Configure for all CLIs
+npx let-them-talk init --template <name>  # Use a team template
+npx let-them-talk templates               # List available templates
+npx let-them-talk dashboard               # Launch web dashboard
+npx let-them-talk reset                   # Clear conversation data
+npx let-them-talk plugin list             # List installed plugins
+npx let-them-talk plugin add <file.js>    # Install a plugin
+npx let-them-talk plugin remove <name>    # Remove a plugin
+npx let-them-talk plugin enable <name>    # Enable a plugin
+npx let-them-talk plugin disable <name>   # Disable a plugin
+npx let-them-talk help                    # Show help
+```
+
+## Updating
+
+```bash
+# If using npx (recommended) — clear cache to get latest version
+npx clear-npx-cache
+npx let-them-talk init    # Re-run to update MCP config paths
+
+# If installed globally
+npm update -g let-them-talk
+
+# Check your version
+npx let-them-talk help    # Shows version in header
+```
+
+After updating, restart your CLI terminals to pick up the new MCP server.
+
+## Plugins
+
+Extend Let Them Talk with custom tools. Plugins are `.js` files in the `.agent-bridge/plugins/` directory.
+
+```javascript
+// plugins/my-tool.js
+module.exports = {
+  name: 'my-tool',
+  description: 'What this tool does',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Input text' }
+    },
+    required: ['query']
+  },
+  handler(args, ctx) {
+    // ctx provides: sendMessage, getAgents, getHistory, readFile, registeredName, dataDir
+    return { result: 'done', query: args.query };
+  }
+};
+```
+
+Plugins run sandboxed with a 30-second timeout. Manage them via CLI or the dashboard.
+
+## Supported CLIs
+
+| CLI | Config | Auto-detected |
+|-----|--------|---------------|
+| Claude Code | `.mcp.json` | Yes |
+| Gemini CLI | `.gemini/settings.json` | Yes |
+| Codex CLI | `.mcp.json` | Yes |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_BRIDGE_DATA_DIR` | `{cwd}/.agent-bridge/` | Data directory path |
+| `AGENT_BRIDGE_PORT` | `3000` | Dashboard port |
+| `NODE_ENV` | — | Set to `development` for hot-reload |
+
+## Security
+
+Let Them Talk is a **local message broker** — it passes text messages between CLI terminals via shared files. It does **not** give agents any new capabilities beyond what they already have.
+
+### What it does NOT do
+- Does not give agents filesystem access (they already have it via their CLI)
+- Does not expose anything to the internet (dashboard binds to localhost only)
+- Does not store or transmit API keys
+- Does not run any cloud services
+
+### Built-in protections
+- **CSRF protection** — external websites cannot send requests to the dashboard
+- **XSS prevention** — all inputs are escaped before rendering
+- **Path traversal protection** — agents cannot read files outside the project directory
+- **Symlink protection** — follows symlinks and validates the real path
+- **Origin enforcement** — POST/DELETE requests require valid localhost/LAN origin
+- **SSE connection limits** — prevents connection exhaustion DoS
+- **Forced sender identity** — dashboard messages are always marked as "Dashboard"
+- **Input validation** — branch names, agent names, and paths are validated
+
+### LAN mode
+LAN mode (phone access) only exposes the dashboard to your local WiFi network, not the internet. It requires explicit activation and a firewall rule. A warning is shown when enabled.
+
+### Plugins
+Plugins run with full Node.js access. Only install plugins you trust. This is the same trust model as npm packages.
+
+## License
+
+MIT

package/cli.js

@@ -331,24 +331,33 @@ function pluginCmd() {
       const absPath = path.resolve(filePath);
       if (!fs.existsSync(absPath)) { console.error('  File not found: ' + absPath); process.exit(1); }
 
-      // Validate plugin exports
+      // Validate plugin structure without executing it (no require — prevents RCE on install)
       try {
-        const plugin = require(absPath);
-        if (!plugin.name || !plugin.handler) { console.error('  Plugin must export name, description, and handler'); process.exit(1); }
+        const src = fs.readFileSync(absPath, 'utf8');
+        if (!src.includes('module.exports') || !src.includes('name') || !src.includes('handler')) {
+          console.error('  Plugin must export name, description, and handler (module.exports = { name, handler })');
+          process.exit(1);
+        }
+
+        // Extract plugin name from source using regex (no eval)
+        const nameMatch = src.match(/name\s*:\s*['"]([^'"]+)['"]/);
+        const descMatch = src.match(/description\s*:\s*['"]([^'"]+)['"]/);
+        const pluginName = nameMatch ? nameMatch[1] : path.basename(absPath, '.js');
+        const pluginDesc = descMatch ? descMatch[1] : '';
 
         if (!fs.existsSync(pluginsDir)) fs.mkdirSync(pluginsDir, { recursive: true });
         const destFile = path.join(pluginsDir, path.basename(absPath));
         fs.copyFileSync(absPath, destFile);
 
         const reg = getRegistry();
-        if (!reg.find(p => p.name === plugin.name)) {
-          reg.push({ name: plugin.name, description: plugin.description || '', file: path.basename(absPath), enabled: true, added_at: new Date().toISOString() });
+        if (!reg.find(p => p.name === pluginName)) {
+          reg.push({ name: pluginName, description: pluginDesc, file: path.basename(absPath), enabled: true, added_at: new Date().toISOString() });
           saveRegistry(reg);
         }
-        console.log('  Plugin "' + plugin.name + '" installed successfully.');
-        console.log('  Restart CLI to load the new tool.');
+        console.log('  Plugin "' + pluginName + '" installed successfully.');
+        console.log('  Restart CLI to load the new tool (runs sandboxed).');
       } catch (e) {
-        console.error('  Failed to load plugin: ' + e.message);
+        console.error('  Failed to install plugin: ' + e.message);
         process.exit(1);
       }
       break;
@@ -362,8 +371,11 @@ function pluginCmd() {
       const newReg = reg.filter(p => p.name !== name);
       saveRegistry(newReg);
       if (plugin.file) {
-        const pluginFile = path.join(pluginsDir, plugin.file);
-        if (fs.existsSync(pluginFile)) fs.unlinkSync(pluginFile);
+        const pluginFile = path.resolve(pluginsDir, plugin.file);
+        // Prevent path traversal — only delete files inside pluginsDir
+        if (pluginFile.startsWith(path.resolve(pluginsDir) + path.sep) && fs.existsSync(pluginFile)) {
+          fs.unlinkSync(pluginFile);
+        }
       }
       console.log('  Plugin "' + name + '" removed.');
       break;

package/dashboard.js

@@ -690,8 +690,18 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // CSRF protection: validate origin on mutating requests
+  // CSRF + DNS rebinding protection: validate Host and Origin on mutating requests
   if (req.method === 'POST' || req.method === 'DELETE') {
+    // Check Host header to block DNS rebinding attacks
+    const host = (req.headers.host || '').replace(/:\d+$/, '');
+    const validHosts = ['localhost', '127.0.0.1'];
+    if (LAN_MODE && getLanIP()) validHosts.push(getLanIP());
+    if (!validHosts.includes(host)) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Forbidden: invalid host' }));
+      return;
+    }
+    // Check Origin header to block cross-site requests
     const origin = req.headers.origin || '';
     const referer = req.headers.referer || '';
     const source = origin || referer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "let-them-talk",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "description": "MCP message broker + web dashboard for inter-agent communication. Let AI CLI agents talk to each other.",
   "main": "server.js",
   "bin": {

package/server.js

@@ -23,11 +23,27 @@ const PLUGINS_DIR = path.join(DATA_DIR, 'plugins');
 
 // In-memory state for this process
 let registeredName = null;
+let registeredToken = null; // auth token for re-registration
 let lastReadOffset = 0; // byte offset into messages.jsonl for efficient polling
 let heartbeatInterval = null; // heartbeat timer reference
 let messageSeq = 0; // monotonic sequence counter for message ordering
 let currentBranch = 'main'; // which branch this agent is on
 
+// Rate limiting — prevent broadcast storms and message flooding
+const rateLimitWindow = 60000; // 1 minute window
+const rateLimitMax = 30; // max 30 messages per minute per agent
+let rateLimitMessages = []; // timestamps of recent messages
+
+function checkRateLimit() {
+  const now = Date.now();
+  rateLimitMessages = rateLimitMessages.filter(t => now - t < rateLimitWindow);
+  if (rateLimitMessages.length >= rateLimitMax) {
+    return { error: `Rate limit exceeded: max ${rateLimitMax} messages per minute. Wait before sending more.` };
+  }
+  rateLimitMessages.push(now);
+  return null;
+}
+
 // --- Helpers ---
 
 function ensureDataDir() {
@@ -112,7 +128,13 @@ function validateContentSize(content) {
 }
 
 function generateId() {
-  return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  try { return Date.now().toString(36) + require('crypto').randomBytes(6).toString('hex'); }
+  catch { return Date.now().toString(36) + Math.random().toString(36).slice(2, 8); }
+}
+
+function generateToken() {
+  try { return require('crypto').randomBytes(16).toString('hex'); }
+  catch { return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2); }
 }
 
 function sleep(ms) {
@@ -230,9 +252,11 @@ function autoCompact() {
       return false;
     });
 
-    // Rewrite messages.jsonl with only active messages
+    // Rewrite messages.jsonl atomically — write to temp file then rename
     const newContent = active.map(m => JSON.stringify(m)).join('\n') + (active.length ? '\n' : '');
-    fs.writeFileSync(msgFile, newContent);
+    const tmpFile = msgFile + '.tmp';
+    fs.writeFileSync(tmpFile, newContent);
+    fs.renameSync(tmpFile, msgFile);
     lastReadOffset = Buffer.byteLength(newContent, 'utf8');
 
     // Trim consumed ID files — keep only IDs still in active messages
@@ -366,7 +390,15 @@ function toolRegister(name, provider = null) {
 
   const agents = getAgents();
   if (agents[name] && agents[name].pid !== process.pid && isPidAlive(agents[name].pid)) {
-    return { error: `Agent "${name}" is already registered by a live process (PID ${agents[name].pid})` };
+    return { error: `Agent "${name}" is already registered by a live process. Choose a different name.` };
+  }
+
+  // If name was previously registered by a dead process, verify token to prevent impersonation
+  if (agents[name] && agents[name].token && !isPidAlive(agents[name].pid)) {
+    // Dead agent — only allow re-registration from the same process (same token)
+    if (registeredToken && registeredToken !== agents[name].token) {
+      return { error: `Agent "${name}" was previously registered by another process. Choose a different name.` };
+    }
   }
 
   // Clean up old registration if re-registering with a different name
@@ -375,9 +407,11 @@ function toolRegister(name, provider = null) {
   }
 
   const now = new Date().toISOString();
-  agents[name] = { pid: process.pid, timestamp: now, last_activity: now, provider: provider || 'unknown', branch: currentBranch };
+  const token = (agents[name] && agents[name].token) || generateToken();
+  agents[name] = { pid: process.pid, timestamp: now, last_activity: now, provider: provider || 'unknown', branch: currentBranch, token };
   saveAgents(agents);
   registeredName = name;
+  registeredToken = token;
 
   // Auto-create profile if not exists
   const profiles = getProfiles();
@@ -459,6 +493,9 @@ function toolSendMessage(content, to = null, reply_to = null) {
     return { error: 'You must call register() first' };
   }
 
+  const rateErr = checkRateLimit();
+  if (rateErr) return rateErr;
+
   const agents = getAgents();
   const otherAgents = Object.keys(agents).filter(n => n !== registeredName);
 
@@ -531,6 +568,9 @@ function toolBroadcast(content) {
     return { error: 'You must call register() first' };
   }
 
+  const rateErr = checkRateLimit();
+  if (rateErr) return rateErr;
+
   const sizeErr = validateContentSize(content);
   if (sizeErr) return sizeErr;
 
@@ -1909,13 +1949,16 @@ function loadPlugins() {
   const enabledNames = new Set(registry.filter(p => p.enabled !== false).map(p => p.name));
 
   try {
+    const vm = require('vm');
     const files = fs.readdirSync(PLUGINS_DIR).filter(f => f.endsWith('.js'));
     for (const file of files) {
       try {
         const pluginPath = path.join(PLUGINS_DIR, file);
-        // Clear require cache so plugins can be reloaded
-        delete require.cache[require.resolve(pluginPath)];
-        const plugin = require(pluginPath);
+        const code = fs.readFileSync(pluginPath, 'utf8');
+        // Run plugin in a sandboxed VM context — no require, no process, no child_process
+        const sandbox = { module: { exports: {} }, exports: {}, console: { log: () => {}, error: () => {}, warn: () => {} } };
+        vm.runInNewContext(code, sandbox, { filename: file, timeout: 5000 });
+        const plugin = sandbox.module.exports;
         if (!plugin.name || !plugin.description || !plugin.handler) {
           console.error(`Plugin ${file}: missing name, description, or handler`);
           continue;
@@ -1927,7 +1970,7 @@ function loadPlugins() {
           inputSchema: plugin.inputSchema || { type: 'object', properties: {} },
           handler: plugin.handler,
         });
-        console.error(`Plugin loaded: ${plugin.name}`);
+        console.error(`Plugin loaded: ${plugin.name} (sandboxed)`);
       } catch (e) {
         console.error(`Plugin ${file} failed to load: ${e.message}`);
       }
@@ -1941,17 +1984,18 @@ function executePlugin(pluginName, args) {
 
   const context = {
     registeredName,
-    dataDir: DATA_DIR,
     sendMessage: (to, content) => toolSendMessage(content, to),
     getAgents: () => toolListAgents().agents,
     getHistory: (limit) => toolGetHistory(limit),
     readFile: (filePath) => {
       const resolved = path.resolve(filePath);
       const allowedRoot = path.resolve(process.cwd());
-      if (!resolved.startsWith(allowedRoot + path.sep) && resolved !== allowedRoot) {
+      let realPath;
+      try { realPath = fs.realpathSync(resolved); } catch { throw new Error('File not found'); }
+      if (!realPath.startsWith(allowedRoot + path.sep) && realPath !== allowedRoot) {
         throw new Error('File path must be within the project directory');
       }
-      return fs.readFileSync(resolved, 'utf8');
+      return fs.readFileSync(realPath, 'utf8');
     },
   };