agent-relay 1.6.0 → 2.0.4

package/packages/mcp/dist/prompts/protocol.js

@@ -0,0 +1,168 @@
+/**
+ * Protocol Documentation Prompt
+ *
+ * Provides the full Agent Relay protocol documentation as an MCP prompt.
+ * This is included automatically when an agent connects.
+ */
+export const protocolPrompt = {
+    name: 'relay_protocol',
+    description: 'Full Agent Relay protocol documentation',
+    arguments: [],
+};
+export const PROTOCOL_DOCUMENTATION = `
+# Agent Relay Protocol
+
+You are connected to Agent Relay, a real-time messaging system for AI agent coordination.
+
+## Communication Patterns
+
+### Direct Messages
+Send a message to a specific agent by name:
+\`\`\`
+relay_send(to="Alice", message="Can you review this PR?")
+\`\`\`
+
+### Channel Messages
+Send to a channel (prefix with #):
+\`\`\`
+relay_send(to="#engineering", message="Build complete")
+\`\`\`
+Channel messages are visible to all agents subscribed to that channel.
+
+### Broadcast
+Send to all online agents:
+\`\`\`
+relay_send(to="*", message="System maintenance in 5 minutes")
+\`\`\`
+Use sparingly - broadcasts interrupt all agents.
+
+### Threaded Conversations
+For multi-turn conversations, use thread IDs:
+\`\`\`
+relay_send(to="Bob", message="Starting task", thread="task-123")
+relay_send(to="Bob", message="Task update", thread="task-123")
+\`\`\`
+
+### Await Response
+Block and wait for a reply:
+\`\`\`
+relay_send(to="Worker", message="Process this file", await_response=true, timeout_ms=60000)
+\`\`\`
+
+## Spawning Workers
+
+Create worker agents to parallelize work:
+
+\`\`\`
+relay_spawn(
+  name="TestRunner",
+  cli="claude",
+  task="Run the test suite in src/tests/ and report any failures"
+)
+\`\`\`
+
+Workers:
+- Run in separate processes
+- Have their own CLI instance
+- Can use relay to communicate back
+- Should be released when done
+
+### Worker Lifecycle
+1. Spawn worker with task
+2. Worker sends ACK when ready
+3. Worker sends progress updates
+4. Worker sends DONE when complete
+5. Lead releases worker
+
+### Release Workers
+\`\`\`
+relay_release(name="TestRunner", reason="Tests completed")
+\`\`\`
+
+## Message Protocol
+
+When you receive messages, they follow this format:
+\`\`\`
+Relay message from Alice [msg-id-123]: Content here
+\`\`\`
+
+Channel messages include the channel:
+\`\`\`
+Relay message from Alice [msg-id-456] [#general]: Hello team!
+\`\`\`
+
+### ACK/DONE Protocol
+When assigned a task:
+1. Send ACK immediately: "ACK: Starting work on X"
+2. Send progress updates as needed
+3. Send DONE when complete: "DONE: Completed X with result Y"
+
+Example:
+\`\`\`
+# When receiving a task
+relay_send(to="Lead", message="ACK: Starting test suite run")
+
+# ... do work ...
+
+relay_send(to="Lead", message="DONE: All 42 tests passed")
+\`\`\`
+
+## Best Practices
+
+### For Lead Agents
+- Spawn workers for parallelizable tasks
+- Keep track of spawned workers
+- Release workers when done
+- Use channels for team announcements
+
+### For Worker Agents
+- ACK immediately when receiving tasks
+- Send progress updates for long tasks
+- Send DONE with results when complete
+- Ask clarifying questions if needed
+
+### Message Etiquette
+- Keep messages concise
+- Include relevant context
+- Use threads for related messages
+- Don't spam broadcasts
+
+## Checking Messages
+
+Proactively check your inbox:
+\`\`\`
+relay_inbox()
+relay_inbox(from="Lead")
+relay_inbox(channel="#urgent")
+\`\`\`
+
+## Seeing Who's Online
+
+\`\`\`
+relay_who()
+\`\`\`
+
+## Error Handling
+
+If relay returns an error:
+- "Daemon not running" - The relay daemon needs to be started
+- "Agent not found" - Target agent is offline
+- "Channel not found" - Channel doesn't exist
+- "Timeout" - No response within timeout period
+
+## Multi-Project Communication
+
+In multi-project setups, specify project:
+\`\`\`
+relay_send(to="frontend:Designer", message="Need UI mockup")
+\`\`\`
+
+Special targets:
+- \`project:lead\` - Lead agent of that project
+- \`project:*\` - Broadcast to project
+- \`*:*\` - Broadcast to all projects
+`;
+export function getProtocolPrompt() {
+    return PROTOCOL_DOCUMENTATION;
+}
+//# sourceMappingURL=protocol.js.map

package/packages/mcp/dist/resources/agents.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Agents Resource
+ *
+ * Provides live list of online agents as an MCP resource.
+ * URI: relay://agents
+ */
+import type { Resource } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+export declare const agentsResource: Resource;
+export declare function getAgentsResource(client: RelayClient): Promise<string>;
+//# sourceMappingURL=agents.d.ts.map

package/packages/mcp/dist/resources/agents.js

@@ -0,0 +1,17 @@
+/**
+ * Agents Resource
+ *
+ * Provides live list of online agents as an MCP resource.
+ * URI: relay://agents
+ */
+export const agentsResource = {
+    uri: 'relay://agents',
+    name: 'Online Agents',
+    description: 'Live list of agents currently connected to relay',
+    mimeType: 'application/json',
+};
+export async function getAgentsResource(client) {
+    const agents = await client.listAgents({ include_idle: true });
+    return JSON.stringify(agents, null, 2);
+}
+//# sourceMappingURL=agents.js.map

package/packages/mcp/dist/resources/inbox.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Inbox Resource
+ *
+ * Provides current inbox contents as an MCP resource.
+ * URI: relay://inbox
+ */
+import type { Resource } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+export declare const inboxResource: Resource;
+export declare function getInboxResource(client: RelayClient): Promise<string>;
+//# sourceMappingURL=inbox.d.ts.map

package/packages/mcp/dist/resources/inbox.js

@@ -0,0 +1,17 @@
+/**
+ * Inbox Resource
+ *
+ * Provides current inbox contents as an MCP resource.
+ * URI: relay://inbox
+ */
+export const inboxResource = {
+    uri: 'relay://inbox',
+    name: 'Message Inbox',
+    description: 'Your pending messages',
+    mimeType: 'application/json',
+};
+export async function getInboxResource(client) {
+    const messages = await client.getInbox({ unread_only: true, limit: 50 });
+    return JSON.stringify(messages, null, 2);
+}
+//# sourceMappingURL=inbox.js.map

package/packages/mcp/dist/resources/index.d.ts

@@ -0,0 +1,4 @@
+export { agentsResource, getAgentsResource } from './agents.js';
+export { inboxResource, getInboxResource } from './inbox.js';
+export { projectResource, getProjectResource } from './project.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/mcp/dist/resources/index.js

@@ -0,0 +1,4 @@
+export { agentsResource, getAgentsResource } from './agents.js';
+export { inboxResource, getInboxResource } from './inbox.js';
+export { projectResource, getProjectResource } from './project.js';
+//# sourceMappingURL=index.js.map

package/packages/mcp/dist/resources/project.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Project Resource
+ *
+ * Provides current project configuration as an MCP resource.
+ * URI: relay://project
+ */
+import type { Resource } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+export declare const projectResource: Resource;
+export declare function getProjectResource(client: RelayClient): Promise<string>;
+//# sourceMappingURL=project.d.ts.map

package/packages/mcp/dist/resources/project.js

@@ -0,0 +1,21 @@
+/**
+ * Project Resource
+ *
+ * Provides current project configuration as an MCP resource.
+ * URI: relay://project
+ */
+export const projectResource = {
+    uri: 'relay://project',
+    name: 'Project Info',
+    description: 'Current relay project configuration',
+    mimeType: 'application/json',
+};
+export async function getProjectResource(client) {
+    const status = await client.getStatus();
+    return JSON.stringify({
+        project: status.project,
+        socketPath: status.socketPath,
+        daemonVersion: status.daemonVersion,
+    }, null, 2);
+}
+//# sourceMappingURL=project.js.map

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

@@ -0,0 +1,19 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { RelayClient } from './client.js';
+/**
+ * MCP Server configuration options
+ */
+export interface MCPServerConfig {
+    name?: string;
+    version?: string;
+}
+/**
+ * Create and configure an MCP server for Agent Relay
+ */
+export declare function createMCPServer(client: RelayClient, config?: MCPServerConfig): Server;
+/**
+ * Run the MCP server with stdio transport.
+ * This is the main entry point when running as a standalone process.
+ */
+export declare function runMCPServer(client: RelayClient, config?: MCPServerConfig): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/packages/mcp/dist/server.js

@@ -0,0 +1,215 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { relaySendTool, relaySendSchema, handleRelaySend, relayInboxTool, relayInboxSchema, handleRelayInbox, relayWhoTool, relayWhoSchema, handleRelayWho, relaySpawnTool, relaySpawnSchema, handleRelaySpawn, relayReleaseTool, relayReleaseSchema, handleRelayRelease, relayStatusTool, relayStatusSchema, handleRelayStatus, relayLogsTool, relayLogsSchema, handleRelayLogs, relayMetricsTool, relayMetricsSchema, handleRelayMetrics, relayHealthTool, relayHealthSchema, handleRelayHealth, } from './tools/index.js';
+import { protocolPrompt, getProtocolPrompt } from './prompts/index.js';
+import { agentsResource, getAgentsResource, inboxResource, getInboxResource, projectResource, getProjectResource, } from './resources/index.js';
+/**
+ * All available relay tools
+ */
+const TOOLS = [
+    relaySendTool,
+    relayInboxTool,
+    relayWhoTool,
+    relaySpawnTool,
+    relayReleaseTool,
+    relayStatusTool,
+    relayLogsTool,
+    relayMetricsTool,
+    relayHealthTool,
+];
+/**
+ * All available prompts
+ */
+const PROMPTS = [protocolPrompt];
+/**
+ * All available resources
+ */
+const RESOURCES = [agentsResource, inboxResource, projectResource];
+/**
+ * Create and configure an MCP server for Agent Relay
+ */
+export function createMCPServer(client, config) {
+    const serverName = config?.name ?? 'agent-relay-mcp';
+    const serverVersion = config?.version ?? '0.1.0';
+    const server = new Server({
+        name: serverName,
+        version: serverVersion,
+    }, {
+        capabilities: {
+            tools: {},
+            prompts: {},
+            resources: {},
+        },
+    });
+    // Register tool listing handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    // Register tool call handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case 'relay_send': {
+                    const input = relaySendSchema.parse(args);
+                    result = await handleRelaySend(client, input);
+                    break;
+                }
+                case 'relay_inbox': {
+                    const input = relayInboxSchema.parse(args);
+                    result = await handleRelayInbox(client, input);
+                    break;
+                }
+                case 'relay_who': {
+                    const input = relayWhoSchema.parse(args);
+                    result = await handleRelayWho(client, input);
+                    break;
+                }
+                case 'relay_spawn': {
+                    const input = relaySpawnSchema.parse(args);
+                    result = await handleRelaySpawn(client, input);
+                    break;
+                }
+                case 'relay_release': {
+                    const input = relayReleaseSchema.parse(args);
+                    result = await handleRelayRelease(client, input);
+                    break;
+                }
+                case 'relay_status': {
+                    const input = relayStatusSchema.parse(args);
+                    result = await handleRelayStatus(client, input);
+                    break;
+                }
+                case 'relay_logs': {
+                    const input = relayLogsSchema.parse(args);
+                    result = await handleRelayLogs(client, input);
+                    break;
+                }
+                case 'relay_metrics': {
+                    const input = relayMetricsSchema.parse(args);
+                    result = await handleRelayMetrics(client, input);
+                    break;
+                }
+                case 'relay_health': {
+                    const input = relayHealthSchema.parse(args);
+                    result = await handleRelayHealth(client, input);
+                    break;
+                }
+                default:
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Unknown tool: ${name}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: result,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error executing ${name}: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Register prompt listing handler
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: PROMPTS,
+    }));
+    // Register prompt get handler
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name } = request.params;
+        if (name === 'relay_protocol') {
+            return {
+                description: 'Agent Relay protocol documentation',
+                messages: [
+                    {
+                        role: 'user',
+                        content: { type: 'text', text: getProtocolPrompt() },
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    });
+    // Register resource listing handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: RESOURCES,
+    }));
+    // Register resource read handler
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        switch (uri) {
+            case 'relay://agents':
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'application/json',
+                            text: await getAgentsResource(client),
+                        },
+                    ],
+                };
+            case 'relay://inbox':
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'application/json',
+                            text: await getInboxResource(client),
+                        },
+                    ],
+                };
+            case 'relay://project':
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'application/json',
+                            text: await getProjectResource(client),
+                        },
+                    ],
+                };
+            default:
+                throw new Error(`Unknown resource: ${uri}`);
+        }
+    });
+    return server;
+}
+/**
+ * Run the MCP server with stdio transport.
+ * This is the main entry point when running as a standalone process.
+ */
+export async function runMCPServer(client, config) {
+    const server = createMCPServer(client, config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Handle graceful shutdown
+    process.on('SIGINT', async () => {
+        await server.close();
+        process.exit(0);
+    });
+    process.on('SIGTERM', async () => {
+        await server.close();
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=server.js.map

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

@@ -0,0 +1,173 @@
+/**
+ * Simple Programmatic API for Agent Relay MCP Tools
+ *
+ * Dead simple access to relay tools without MCP protocol overhead.
+ *
+ * @example
+ * ```typescript
+ * import { createTools } from '@agent-relay/mcp/simple';
+ *
+ * const tools = await createTools('MyAgent');
+ *
+ * await tools.send('Bob', 'Hello!');
+ * const messages = await tools.inbox();
+ * const agents = await tools.who();
+ * ```
+ */
+import { createRelayClient, type RelayClient, type RelayClientOptions } from './client.js';
+export interface Message {
+    id: string;
+    from: string;
+    content: string;
+    channel?: string;
+    thread?: string;
+}
+export interface Agent {
+    name: string;
+    cli: string;
+    idle?: boolean;
+    parent?: string;
+}
+export interface Status {
+    connected: boolean;
+    agentName: string;
+    project: string;
+    socketPath: string;
+    daemonVersion?: string;
+    uptime?: string;
+}
+export interface SpawnResult {
+    success: boolean;
+    error?: string;
+}
+export interface RelayTools {
+    /** Send a message to an agent, channel, or broadcast */
+    send(to: string, message: string, options?: {
+        thread?: string;
+    }): Promise<void>;
+    /** Send a message and wait for acknowledgment */
+    sendAndWait(to: string, message: string, options?: {
+        thread?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        from: string;
+        content: string;
+        thread?: string;
+    }>;
+    /** Check inbox for messages */
+    inbox(options?: {
+        limit?: number;
+        unread_only?: boolean;
+        from?: string;
+        channel?: string;
+    }): Promise<Message[]>;
+    /** List online agents */
+    who(options?: {
+        include_idle?: boolean;
+    }): Promise<Agent[]>;
+    /** Spawn a worker agent */
+    spawn(options: {
+        name: string;
+        cli: 'claude' | 'codex' | 'gemini' | 'droid' | 'opencode';
+        task: string;
+        model?: string;
+        cwd?: string;
+    }): Promise<SpawnResult>;
+    /** Release a worker agent */
+    release(name: string, reason?: string): Promise<SpawnResult>;
+    /** Get connection status */
+    status(): Promise<Status>;
+    /** The underlying client (for advanced use) */
+    readonly client: RelayClient;
+}
+export interface ToolsConfig {
+    /** Socket path for daemon connection */
+    socketPath?: string;
+    /** Project name */
+    project?: string;
+    /** Request timeout in ms (default: 5000) */
+    timeout?: number;
+}
+/**
+ * Create relay tools for programmatic use.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const tools = await createTools('MyAgent');
+ *
+ * // Send messages
+ * await tools.send('OtherAgent', 'Hello!');
+ * await tools.send('#general', 'Channel message');
+ * await tools.send('*', 'Broadcast to everyone');
+ *
+ * // Check inbox
+ * const messages = await tools.inbox();
+ * for (const msg of messages) {
+ *   console.log(`${msg.from}: ${msg.content}`);
+ * }
+ *
+ * // List agents
+ * const agents = await tools.who();
+ * console.log('Online:', agents.map(a => a.name).join(', '));
+ * ```
+ *
+ * @example Spawn Workers
+ * ```typescript
+ * const tools = await createTools('Lead');
+ *
+ * // Spawn a worker
+ * const result = await tools.spawn({
+ *   name: 'Worker1',
+ *   cli: 'claude',
+ *   task: 'Run the test suite',
+ * });
+ *
+ * // Release when done
+ * await tools.release('Worker1', 'Tests complete');
+ * ```
+ */
+export declare function createTools(agentName: string, config?: ToolsConfig): RelayTools;
+/**
+ * Convenience function for one-off messages.
+ *
+ * @example
+ * ```typescript
+ * import { send } from '@agent-relay/mcp/simple';
+ *
+ * await send('MyAgent', 'Bob', 'Hello!');
+ * ```
+ */
+export declare function send(fromAgent: string, to: string, message: string, options?: {
+    thread?: string;
+} & ToolsConfig): Promise<void>;
+/**
+ * Convenience function to check inbox.
+ *
+ * @example
+ * ```typescript
+ * import { inbox } from '@agent-relay/mcp/simple';
+ *
+ * const messages = await inbox('MyAgent');
+ * ```
+ */
+export declare function inbox(agentName: string, options?: {
+    limit?: number;
+    unread_only?: boolean;
+    from?: string;
+    channel?: string;
+} & ToolsConfig): Promise<Message[]>;
+/**
+ * Convenience function to list agents.
+ *
+ * @example
+ * ```typescript
+ * import { who } from '@agent-relay/mcp/simple';
+ *
+ * const agents = await who();
+ * ```
+ */
+export declare function who(options?: {
+    include_idle?: boolean;
+} & ToolsConfig): Promise<Agent[]>;
+export { createRelayClient, type RelayClient, type RelayClientOptions };
+//# sourceMappingURL=simple.d.ts.map