let-them-talk 3.2.1 → 3.2.3

package/README.md

@@ -0,0 +1,226 @@
+# 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
+```
+
+## 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/dashboard.js

@@ -262,7 +262,7 @@ function apiInjectMessage(body, query) {
   }
 
   if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
-  const fromName = body.from || 'Dashboard';
+  const fromName = 'Dashboard';
   const now = new Date().toISOString();
 
   // Broadcast to all agents
@@ -310,6 +310,16 @@ function apiAddProject(body) {
   const absPath = path.resolve(body.path);
   if (!fs.existsSync(absPath)) return { error: `Path does not exist: ${absPath}` };
 
+  // Restrict to paths under cwd or paths that look like project directories
+  const cwd = path.resolve(process.cwd());
+  if (!absPath.startsWith(cwd + path.sep) && absPath !== cwd) {
+    const hasProject = fs.existsSync(path.join(absPath, 'package.json')) ||
+                       fs.existsSync(path.join(absPath, '.git'));
+    if (!hasProject) {
+      return { error: 'Path must be a project directory (with package.json or .git)' };
+    }
+  }
+
   const projects = getProjects();
   const name = body.name || path.basename(absPath);
   if (projects.find(p => p.path === absPath)) return { error: 'Project already added' };
@@ -416,7 +426,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;backgrou
 <script>
 var COLORS=['#58a6ff','#3fb950','#d29922','#f85149','#bc8cff','#f778ba','#79c0ff','#7ee787','#e3b341','#ffa198'];
 var colorMap={},ci=0;
-var data=${JSON.stringify(history)};
+var data=${JSON.stringify(history).replace(/<\//g, '<\\/')};
 function esc(t){var d=document.createElement('div');d.textContent=t;return d.innerHTML}
 function fmt(t){
 var h=esc(t);
@@ -603,6 +613,9 @@ function apiLaunchAgent(body) {
   if (!cli || !['claude', 'gemini', 'codex'].includes(cli)) {
     return { error: 'Invalid cli type. Must be: claude, gemini, or codex' };
   }
+  if (project_dir && !validateProjectPath(project_dir)) {
+    return { error: 'Project directory not registered. Add it via the dashboard first.' };
+  }
   const projectDir = project_dir || process.cwd();
   if (!fs.existsSync(projectDir)) {
     return { error: 'Project directory does not exist: ' + projectDir };
@@ -618,7 +631,7 @@ function apiLaunchAgent(body) {
 
   // Try to launch terminal on Windows
   if (process.platform === 'win32') {
-    spawn('cmd', ['/c', 'start', 'cmd', '/k', `cd /d "${projectDir}" && ${cliCmd}`], { cwd: projectDir, shell: false, detached: true, stdio: 'ignore' });
+    spawn('cmd', ['/c', 'start', 'cmd', '/k', cliCmd], { cwd: projectDir, shell: false, detached: true, stdio: 'ignore' });
     return { success: true, launched: true, cli, project_dir: projectDir, prompt: launchPrompt };
   }
 
@@ -677,6 +690,20 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  // CSRF protection: validate origin on mutating requests
+  if (req.method === 'POST' || req.method === 'DELETE') {
+    const origin = req.headers.origin || '';
+    const referer = req.headers.referer || '';
+    const source = origin || referer;
+    const isLocal = !source || source.includes('localhost:' + PORT) || source.includes('127.0.0.1:' + PORT);
+    const isLan = LAN_MODE && getLanIP() && source.includes(getLanIP() + ':' + PORT);
+    if (!isLocal && !isLan) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Forbidden: invalid origin' }));
+      return;
+    }
+  }
+
   try {
     // Validate project parameter on all API endpoints
     const projectParam = url.searchParams.get('project');
@@ -953,6 +980,11 @@ const server = http.createServer(async (req, res) => {
     }
     // Server-Sent Events endpoint for real-time updates
     else if (url.pathname === '/api/events' && req.method === 'GET') {
+      if (sseClients.size >= 100) {
+        res.writeHead(503, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Too many SSE connections' }));
+        return;
+      }
       res.writeHead(200, {
         'Content-Type': 'text/event-stream',
         'Cache-Control': 'no-cache',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "let-them-talk",
-  "version": "3.2.1",
+  "version": "3.2.3",
   "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

@@ -436,7 +436,6 @@ function toolListAgents() {
     const idleSeconds = Math.floor((Date.now() - new Date(lastActivity).getTime()) / 1000);
     const profile = profiles[name] || {};
     result[name] = {
-      pid: info.pid,
       alive,
       registered_at: info.timestamp,
       last_activity: lastActivity,
@@ -568,6 +567,7 @@ async function toolWaitForReply(timeoutSeconds = 300, from = null) {
   if (!registeredName) {
     return { error: 'You must call register() first' };
   }
+  timeoutSeconds = Math.min(Math.max(1, timeoutSeconds || 300), 3600);
 
   setListening(true);
 
@@ -646,6 +646,12 @@ function toolAckMessage(messageId) {
     return { error: 'You must call register() first' };
   }
 
+  const history = readJsonl(getHistoryFile(currentBranch));
+  const msg = history.find(m => m.id === messageId);
+  if (msg && msg.to !== registeredName) {
+    return { error: 'Can only acknowledge messages addressed to you' };
+  }
+
   const acks = getAcks();
   acks[messageId] = {
     acked_by: registeredName,
@@ -773,6 +779,7 @@ async function toolListenCodex(from = null) {
 }
 
 function toolGetHistory(limit = 50, thread_id = null) {
+  limit = Math.min(Math.max(1, limit || 50), 500);
   let history = readJsonl(getHistoryFile(currentBranch));
   if (thread_id) {
     history = history.filter(m => m.thread_id === thread_id || m.id === thread_id);
@@ -840,17 +847,16 @@ function toolShareFile(filePath, to = null, summary = null) {
     return { error: 'You must call register() first' };
   }
 
-  // Resolve the file path — restrict to project directory
+  // Resolve the file path — restrict to project directory (follow symlinks)
   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 { return { error: 'File not found' }; }
+  if (!realPath.startsWith(allowedRoot + path.sep) && realPath !== allowedRoot) {
     return { error: 'File path must be within the project directory' };
   }
-  if (!fs.existsSync(resolved)) {
-    return { error: `File not found: ${path.basename(resolved)}` };
-  }
 
-  const stat = fs.statSync(resolved);
+  const stat = fs.statSync(realPath);
   if (stat.size > 100000) {
     return { error: `File too large (${Math.round(stat.size / 1024)}KB). Maximum 100KB for sharing.` };
   }
@@ -872,8 +878,8 @@ function toolShareFile(filePath, to = null, summary = null) {
     return { error: `Agent "${to}" is not registered` };
   }
 
-  const fileContent = fs.readFileSync(resolved, 'utf8');
-  const fileName = path.basename(resolved);
+  const fileContent = fs.readFileSync(realPath, 'utf8');
+  const fileName = path.basename(realPath);
 
   messageSeq++;
   const content = summary
@@ -1006,6 +1012,7 @@ function toolListTasks(status = null, assignee = null) {
 }
 
 function toolGetSummary(lastN = 20) {
+  lastN = Math.min(Math.max(1, lastN || 20), 500);
   const history = readJsonl(getHistoryFile(currentBranch));
   if (history.length === 0) {
     return { summary: 'No messages in conversation yet.', message_count: 0 };
@@ -1137,8 +1144,8 @@ function toolWorkspaceWrite(key, content) {
 }
 
 function toolWorkspaceRead(key, agent) {
+  if (!registeredName) return { error: 'You must call register() first' };
   const targetAgent = agent || registeredName;
-  if (!targetAgent) return { error: 'Specify agent or register first' };
 
   const ws = getWorkspace(targetAgent);
   if (key) {