agent-relay 1.6.0 → 2.0.0

package/packages/mcp/STAFFING_PLAN.md

@@ -0,0 +1,294 @@
+# MCP Server Implementation - Staffing Plan
+
+> Generated from analysis of SPEC.md
+
+## Overview
+
+**Goal**: Give AI agents (Claude, Codex, Gemini, Cursor) native MCP tools for Agent Relay communication.
+
+**Estimated Total Effort**: 12-16 hours across 4-6 agents
+
+---
+
+## Phase 1: Core Infrastructure
+
+**Agent**: MCPInfra  
+**CLI**: claude  
+**Duration**: ~2-3 hours  
+**Branch**: feature/mcp-infrastructure
+
+### Tasks
+1. Create package structure (packages/mcp/)
+2. Set up package.json, tsconfig.json
+3. Implement src/discover.ts - socket discovery with priority:
+   - RELAY_SOCKET env var
+   - RELAY_PROJECT env var
+   - CWD .relay/config.json
+   - Scan data directory
+4. Implement src/client.ts - RelayClient class
+   - Socket connection to daemon
+   - Frame parsing with @agent-relay/protocol
+   - Handshake (HELLO/WELCOME)
+   - Message handlers
+5. Implement src/errors.ts - Error types
+   - RelayError, DaemonNotRunningError, AgentNotFoundError, TimeoutError
+6. Write tests/discover.test.ts
+
+### Acceptance Criteria
+- Package builds with npm run build
+- Discovery finds socket in all priority scenarios
+- Client connects to running daemon
+- All tests pass
+
+---
+
+## Phase 2a: MCP Tools (Group 1)
+
+**Agent**: MCPTools1  
+**CLI**: claude  
+**Duration**: ~3-4 hours  
+**Branch**: feature/mcp-tools-messaging  
+**Depends on**: Phase 1
+
+### Tasks
+1. Implement src/tools/relay-send.ts
+   - Direct messages, channels, broadcast
+   - Thread support
+   - await_response with timeout
+2. Implement src/tools/relay-inbox.ts
+   - Filter by sender, channel
+   - Limit and unread_only options
+3. Implement src/tools/relay-who.ts
+   - List online agents
+   - Include idle flag, parent info
+4. Write unit tests for all 3 tools
+
+### Acceptance Criteria
+- relay_send sends to agents, channels, broadcast
+- relay_send with await_response blocks and returns reply
+- relay_inbox returns filtered messages
+- relay_who lists agents with status
+- All tests pass
+
+---
+
+## Phase 2b: MCP Tools (Group 2)
+
+**Agent**: MCPTools2  
+**CLI**: claude  
+**Duration**: ~3-4 hours  
+**Branch**: feature/mcp-tools-spawn  
+**Depends on**: Phase 1  
+**Parallel with**: Phase 2a
+
+### Tasks
+1. Implement src/tools/relay-spawn.ts
+   - Spawn worker with name, cli, task
+   - Optional model and cwd
+2. Implement src/tools/relay-release.ts
+   - Release worker by name
+   - Optional reason
+3. Implement src/tools/relay-status.ts
+   - Connection state
+   - Agent name, project, socket info
+4. Implement src/tools/index.ts - exports
+5. Write unit tests for all 3 tools
+
+### Acceptance Criteria
+- relay_spawn creates worker agents
+- relay_release terminates workers
+- relay_status returns connection diagnostics
+- All tests pass
+
+---
+
+## Phase 3: MCP Server Assembly
+
+**Agent**: MCPServer  
+**CLI**: claude  
+**Duration**: ~2-3 hours  
+**Branch**: feature/mcp-server  
+**Depends on**: Phase 2a + 2b
+
+### Tasks
+1. Implement src/index.ts - MCP server entry point
+   - Wire all 6 tools
+   - Handle tool calls
+   - Connect to relay daemon on startup
+2. Implement src/bin.ts - CLI binary
+   - install command
+   - serve command
+3. Implement src/prompts/protocol.ts
+   - Full protocol documentation prompt
+4. Implement src/resources/
+   - agents.ts - relay://agents
+   - inbox.ts - relay://inbox
+   - project.ts - relay://project
+5. Write integration tests
+
+### Acceptance Criteria
+- npx @agent-relay/mcp serve starts MCP server
+- All 6 tools callable via MCP protocol
+- Protocol prompt available
+- Resources return live data
+- Integration tests pass
+
+---
+
+## Phase 4: Installation System
+
+**Agent**: MCPInstall  
+**CLI**: claude  
+**Duration**: ~2 hours  
+**Branch**: feature/mcp-install  
+**Depends on**: Phase 3
+
+### Tasks
+1. Implement src/install.ts - editor installation logic
+   - Detect installed editors (Claude, Cursor, VS Code)
+   - Read/modify editor config files
+2. Implement src/install-cli.ts - CLI wrapper
+3. Add agent-relay mcp command to main CLI
+   - agent-relay mcp install
+   - agent-relay mcp serve
+4. Update agent-relay setup to offer MCP install
+5. Write install tests
+
+### Acceptance Criteria
+- npx @agent-relay/mcp install auto-detects editors
+- Claude Code config updated correctly
+- Cursor config updated correctly
+- agent-relay mcp install works from main CLI
+
+---
+
+## Phase 5: Cloud Integration
+
+**Agent**: MCPCloud  
+**CLI**: claude  
+**Duration**: ~1-2 hours  
+**Branch**: feature/mcp-cloud  
+**Depends on**: Phase 4
+
+### Tasks
+1. Update deploy/workspace/Dockerfile
+   - Install @agent-relay/mcp globally
+   - Pre-configure Claude Code settings
+   - Pre-configure Cursor settings
+2. Set environment variables for socket discovery
+3. Test with all CLI tools in workspace
+
+### Acceptance Criteria
+- New workspaces have MCP pre-configured
+- Claude Code in workspace has relay tools
+- Cursor in workspace has relay tools
+- Socket discovery works via RELAY_PROJECT env
+
+---
+
+## Dependency Graph
+
+    Phase 1 (MCPInfra)
+           |
+           v
+      +---------+
+      |         |
+      v         v
+    Phase 2a  Phase 2b  [PARALLEL]
+      |         |
+      +----+----+
+           |
+           v
+    Phase 3 (MCPServer)
+           |
+           v
+    Phase 4 (MCPInstall)
+           |
+           v
+    Phase 5 (MCPCloud)
+
+---
+
+## Spawn Commands Reference
+
+### Phase 1 - Spawn MCPInfra
+NAME: MCPInfra
+CLI: claude
+TASK: Implement MCP core infrastructure per packages/mcp/SPEC.md Phase 1:
+  1. Create packages/mcp/ structure
+  2. Implement src/discover.ts (socket discovery)
+  3. Implement src/client.ts (RelayClient)
+  4. Implement src/errors.ts
+  5. Write tests/discover.test.ts
+BRANCH: feature/mcp-infrastructure
+
+### Phase 2a - Spawn MCPTools1 (after Phase 1)
+NAME: MCPTools1
+CLI: claude
+TASK: Implement MCP messaging tools per packages/mcp/SPEC.md:
+  1. src/tools/relay-send.ts
+  2. src/tools/relay-inbox.ts  
+  3. src/tools/relay-who.ts
+  4. Unit tests for all 3
+BRANCH: feature/mcp-tools-messaging
+
+### Phase 2b - Spawn MCPTools2 (after Phase 1, parallel with 2a)
+NAME: MCPTools2
+CLI: claude
+TASK: Implement MCP spawn/control tools per packages/mcp/SPEC.md:
+  1. src/tools/relay-spawn.ts
+  2. src/tools/relay-release.ts
+  3. src/tools/relay-status.ts
+  4. src/tools/index.ts (exports)
+  5. Unit tests for all 3
+BRANCH: feature/mcp-tools-spawn
+
+### Phase 3 - Spawn MCPServer (after Phase 2a + 2b)
+NAME: MCPServer
+CLI: claude
+TASK: Assemble MCP server per packages/mcp/SPEC.md Phase 3:
+  1. src/index.ts - MCP server entry point
+  2. src/bin.ts - CLI binary
+  3. src/prompts/protocol.ts
+  4. src/resources/ (agents, inbox, project)
+  5. Integration tests
+BRANCH: feature/mcp-server
+
+### Phase 4 - Spawn MCPInstall (after Phase 3)
+NAME: MCPInstall
+CLI: claude
+TASK: Implement MCP installation per packages/mcp/SPEC.md Phase 4:
+  1. src/install.ts - editor detection
+  2. src/install-cli.ts
+  3. Add agent-relay mcp command
+  4. Update agent-relay setup
+  5. Install tests
+BRANCH: feature/mcp-install
+
+### Phase 5 - Spawn MCPCloud (after Phase 4)
+NAME: MCPCloud
+CLI: claude
+TASK: Cloud integration per packages/mcp/SPEC.md Phase 5:
+  1. Update deploy/workspace/Dockerfile
+  2. Pre-configure Claude Code and Cursor
+  3. Set RELAY_PROJECT env
+  4. Test in workspace container
+BRANCH: feature/mcp-cloud
+
+---
+
+## Open Questions
+
+1. **Daemon Protocol**: Does current daemon support SPAWN, RELEASE, WHO, INBOX message types, or do those need to be added first?
+2. **Package Publishing**: When should @agent-relay/mcp be published to npm?
+3. **Priority**: Local-first or cloud-first testing?
+
+---
+
+## Quick Start for New Session
+
+To resume this work:
+1. Read this file and SPEC.md
+2. Check which phases are complete (look for merged branches)
+3. Spawn the next agent in sequence
+4. Monitor progress via relay messages

package/packages/mcp/dist/bin.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * @agent-relay/mcp CLI
+ *
+ * Main entry point for the MCP package CLI.
+ *
+ * Usage:
+ *   npx @agent-relay/mcp install     - Install MCP server for editors
+ *   npx @agent-relay/mcp serve       - Run MCP server (used by editors)
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/packages/mcp/dist/bin.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * @agent-relay/mcp CLI
+ *
+ * Main entry point for the MCP package CLI.
+ *
+ * Usage:
+ *   npx @agent-relay/mcp install     - Install MCP server for editors
+ *   npx @agent-relay/mcp serve       - Run MCP server (used by editors)
+ */
+import { parseArgs } from 'node:util';
+import { runInstall, validateEditor, getValidEditors } from './install-cli.js';
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+        editor: { type: 'string', short: 'e' },
+        global: { type: 'boolean', short: 'g' },
+        'dry-run': { type: 'boolean', short: 'n' },
+        uninstall: { type: 'boolean', short: 'u' },
+        list: { type: 'boolean', short: 'l' },
+        status: { type: 'boolean', short: 's' },
+        quiet: { type: 'boolean', short: 'q' },
+    },
+});
+const command = positionals[0];
+const VERSION = '0.1.0';
+function showHelp() {
+    console.log(`
+@agent-relay/mcp v${VERSION} - MCP Server for Agent Relay
+
+Usage:
+  npx @agent-relay/mcp <command> [options]
+
+Commands:
+  install     Install MCP server configuration for your editor
+  serve       Run the MCP server (used internally by editors)
+
+Install Options:
+  -e, --editor <name>   Editor to configure (auto-detect if not specified)
+  -g, --global          Install globally (not project-specific)
+  -n, --dry-run         Show what would be done without making changes
+  -u, --uninstall       Remove MCP server configuration
+  -l, --list            List supported editors
+  -s, --status          Show installation status
+  -q, --quiet           Minimal output
+
+Supported Editors:
+  ${getValidEditors().join(', ')}
+
+Examples:
+  npx @agent-relay/mcp install                    # Auto-detect editors
+  npx @agent-relay/mcp install --editor claude    # Claude Desktop only
+  npx @agent-relay/mcp install --editor cursor    # Cursor only
+  npx @agent-relay/mcp install --global           # Global config
+  npx @agent-relay/mcp install --list             # List editors
+  npx @agent-relay/mcp install --status           # Show status
+  npx @agent-relay/mcp install --uninstall        # Remove config
+  npx @agent-relay/mcp serve                      # Run server (for editors)
+`);
+}
+// Handle --help at top level
+if (values.help && !command) {
+    showHelp();
+    process.exit(0);
+}
+// Handle --version
+if (values.version) {
+    console.log(VERSION);
+    process.exit(0);
+}
+// No command provided
+if (!command) {
+    showHelp();
+    process.exit(0);
+}
+// Validate editor if specified
+if (values.editor && !validateEditor(values.editor)) {
+    console.error(`Error: Unknown editor '${values.editor}'`);
+    console.error(`Valid editors: ${getValidEditors().join(', ')}`);
+    process.exit(1);
+}
+switch (command) {
+    case 'install':
+        runInstall({
+            editor: values.editor,
+            global: values.global,
+            dryRun: values['dry-run'],
+            uninstall: values.uninstall,
+            list: values.list,
+            status: values.status,
+            quiet: values.quiet,
+        });
+        break;
+    case 'serve':
+        // Dynamic import to avoid loading server code when not needed
+        (async () => {
+            try {
+                const { createRelayClient, runMCPServer, discoverSocket } = await import('./index.js');
+                // Discover socket or use default agent name
+                const discovery = discoverSocket();
+                const agentName = process.env.RELAY_AGENT_NAME || `mcp-${process.pid}`;
+                // Create client and run server
+                const client = createRelayClient({
+                    agentName,
+                    socketPath: discovery?.socketPath,
+                    project: discovery?.project,
+                });
+                await runMCPServer(client);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error('Failed to start MCP server:', message);
+                process.exit(1);
+            }
+        })();
+        break;
+    case 'help':
+        showHelp();
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        console.error('Run with --help for usage');
+        process.exit(1);
+}
+//# sourceMappingURL=bin.js.map

package/packages/mcp/dist/client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * RelayClient - Client for connecting to the Agent Relay daemon
+ */
+export interface RelayClient {
+    send(to: string, message: string, options?: {
+        thread?: string;
+    }): Promise<void>;
+    sendAndWait(to: string, message: string, options?: {
+        thread?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        from: string;
+        content: string;
+        thread?: string;
+    }>;
+    spawn(options: {
+        name: string;
+        cli: string;
+        task: string;
+        model?: string;
+        cwd?: string;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    release(name: string, reason?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    getStatus(): Promise<{
+        connected: boolean;
+        agentName: string;
+        project: string;
+        socketPath: string;
+        daemonVersion?: string;
+        uptime?: string;
+    }>;
+    getInbox(options?: {
+        limit?: number;
+        unread_only?: boolean;
+        from?: string;
+        channel?: string;
+    }): Promise<Array<{
+        id: string;
+        from: string;
+        content: string;
+        channel?: string;
+        thread?: string;
+    }>>;
+    listAgents(options?: {
+        include_idle?: boolean;
+        project?: string;
+    }): Promise<Array<{
+        name: string;
+        cli: string;
+        idle?: boolean;
+        parent?: string;
+    }>>;
+}
+export interface RelayClientOptions {
+    agentName: string;
+    socketPath?: string;
+    project?: string;
+    timeout?: number;
+}
+export declare function createRelayClient(options: RelayClientOptions): RelayClient;
+export default createRelayClient;
+//# sourceMappingURL=client.d.ts.map

package/packages/mcp/dist/client.js

@@ -0,0 +1,115 @@
+/**
+ * RelayClient - Client for connecting to the Agent Relay daemon
+ */
+import { createConnection } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { discoverSocket } from './cloud.js';
+import { DaemonNotRunningError } from './errors.js';
+export function createRelayClient(options) {
+    const { agentName, project = 'default', timeout = 5000 } = options;
+    const discovery = discoverSocket({ socketPath: options.socketPath });
+    const socketPath = discovery?.socketPath || options.socketPath || '/tmp/agent-relay.sock';
+    // Use randomUUID for collision-resistant request IDs
+    const generateId = () => `${agentName}-${randomUUID()}`;
+    async function request(type, payload) {
+        return new Promise((resolve, reject) => {
+            const id = generateId();
+            const req = { type, id, payload };
+            let timedOut = false;
+            let buffer = '';
+            const socket = createConnection(socketPath);
+            const timeoutId = setTimeout(() => {
+                timedOut = true;
+                socket.destroy();
+                reject(new Error(`Request timeout after ${timeout}ms`));
+            }, timeout);
+            socket.on('connect', () => socket.write(JSON.stringify(req) + '\n'));
+            socket.on('data', (data) => {
+                // Ignore data if we've already timed out
+                if (timedOut)
+                    return;
+                buffer += data.toString();
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const response = JSON.parse(line);
+                        if (response.id === id) {
+                            clearTimeout(timeoutId);
+                            socket.end();
+                            if (response.error)
+                                reject(new Error(response.error));
+                            else
+                                resolve(response.payload);
+                            return;
+                        }
+                    }
+                    catch (parseError) {
+                        // Log parse errors in debug mode for easier troubleshooting
+                        if (process.env.DEBUG || process.env.RELAY_DEBUG) {
+                            console.error('[RelayClient] Failed to parse daemon response:', line, parseError);
+                        }
+                    }
+                }
+            });
+            socket.on('error', (err) => {
+                clearTimeout(timeoutId);
+                // Provide user-friendly error for common connection failures
+                const errno = err.code;
+                if (errno === 'ECONNREFUSED' || errno === 'ENOENT') {
+                    reject(new DaemonNotRunningError(`Cannot connect to daemon at ${socketPath}`));
+                }
+                else {
+                    reject(err);
+                }
+            });
+        });
+    }
+    return {
+        async send(to, message, opts = {}) {
+            await request('SEND', { from: agentName, to, body: message, thread: opts.thread });
+        },
+        async sendAndWait(to, message, opts = {}) {
+            const r = await request('SEND_AND_WAIT', { from: agentName, to, body: message, thread: opts.thread, timeoutMs: opts.timeoutMs || 30000 });
+            return { from: r.from, content: r.body, thread: r.thread };
+        },
+        async spawn(opts) {
+            try {
+                await request('SPAWN', { ...opts, parent: agentName });
+                return { success: true };
+            }
+            catch (e) {
+                return { success: false, error: e instanceof Error ? e.message : String(e) };
+            }
+        },
+        async release(name, reason) {
+            try {
+                await request('RELEASE', { name, reason });
+                return { success: true };
+            }
+            catch (e) {
+                return { success: false, error: e instanceof Error ? e.message : String(e) };
+            }
+        },
+        async getStatus() {
+            try {
+                const s = await request('STATUS', {});
+                return { connected: true, agentName, project, socketPath, daemonVersion: s.version, uptime: s.uptime ? Math.floor(s.uptime / 1000) + 's' : undefined };
+            }
+            catch {
+                return { connected: false, agentName, project, socketPath };
+            }
+        },
+        async getInbox(opts = {}) {
+            const msgs = await request('INBOX', { agent: agentName, limit: opts.limit, unreadOnly: opts.unread_only, from: opts.from, channel: opts.channel });
+            return msgs.map(m => ({ id: m.id, from: m.from, content: m.body, channel: m.channel, thread: m.thread }));
+        },
+        async listAgents(opts = {}) {
+            return request('LIST_AGENTS', { includeIdle: opts.include_idle, project: opts.project });
+        },
+    };
+}
+export default createRelayClient;
+//# sourceMappingURL=client.js.map