agent-relay 2.0.29 → 2.0.32

package/packages/mcp/src/prompts/index.ts

@@ -0,0 +1 @@
+export { protocolPrompt, getProtocolPrompt, PROTOCOL_DOCUMENTATION } from './protocol.js';

package/packages/mcp/src/prompts/protocol.ts

@@ -0,0 +1,164 @@
+/**
+ * Protocol Documentation Prompt
+ *
+ * Provides the full Agent Relay protocol documentation as an MCP prompt.
+ * This is included automatically when an agent connects.
+ */
+
+import type { Prompt } from '@modelcontextprotocol/sdk/types.js';
+
+export const protocolPrompt: Prompt = {
+  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!
+\`\`\`
+
+### Optional: ACK/DONE Convention
+Some applications use ACK/DONE conventions for task tracking. If your application uses this pattern:
+1. Send ACK when starting: "ACK: Starting work on X"
+2. Send progress updates as needed
+3. Send DONE when complete: "DONE: Completed X with result Y"
+
+Note: This is an application-level convention, not a protocol requirement. Check your application's documentation for expected message formats.
+
+## 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
+- Respond promptly when receiving tasks
+- Send progress updates for long tasks
+- Report 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(): string {
+  return PROTOCOL_DOCUMENTATION;
+}

package/packages/mcp/src/resources/agents.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 const agentsResource: Resource = {
+  uri: 'relay://agents',
+  name: 'Online Agents',
+  description: 'Live list of agents currently connected to relay',
+  mimeType: 'application/json',
+};
+
+export async function getAgentsResource(client: RelayClient): Promise<string> {
+  const agents = await client.listAgents({ include_idle: true });
+  return JSON.stringify(agents, null, 2);
+}

package/packages/mcp/src/resources/inbox.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 const inboxResource: Resource = {
+  uri: 'relay://inbox',
+  name: 'Message Inbox',
+  description: 'Your pending messages',
+  mimeType: 'application/json',
+};
+
+export async function getInboxResource(client: RelayClient): Promise<string> {
+  const messages = await client.getInbox({ unread_only: true, limit: 50 });
+  return JSON.stringify(messages, null, 2);
+}

package/packages/mcp/src/resources/index.ts

@@ -0,0 +1,3 @@
+export { agentsResource, getAgentsResource } from './agents.js';
+export { inboxResource, getInboxResource } from './inbox.js';
+export { projectResource, getProjectResource } from './project.js';

package/packages/mcp/src/resources/project.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 const projectResource: Resource = {
+  uri: 'relay://project',
+  name: 'Project Info',
+  description: 'Current relay project configuration',
+  mimeType: 'application/json',
+};
+
+export async function getProjectResource(client: RelayClient): Promise<string> {
+  const status = await client.getStatus();
+  return JSON.stringify(
+    {
+      project: status.project,
+      socketPath: status.socketPath,
+      daemonVersion: status.daemonVersion,
+    },
+    null,
+    2
+  );
+}

package/packages/mcp/src/server.ts

@@ -0,0 +1,431 @@
+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 type { RelayClient } from './client.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,
+  relayContinuityTool,
+  relayContinuitySchema,
+  handleRelayContinuity,
+  relayConnectedTool,
+  relayConnectedSchema,
+  handleRelayConnected,
+  relayRemoveAgentTool,
+  relayRemoveAgentSchema,
+  handleRelayRemoveAgent,
+  relayBroadcastTool,
+  relayBroadcastSchema,
+  handleRelayBroadcast,
+  relaySubscribeTool,
+  relaySubscribeSchema,
+  handleRelaySubscribe,
+  relayUnsubscribeTool,
+  relayUnsubscribeSchema,
+  handleRelayUnsubscribe,
+  relayChannelJoinTool,
+  relayChannelJoinSchema,
+  handleRelayChannelJoin,
+  relayChannelLeaveTool,
+  relayChannelLeaveSchema,
+  handleRelayChannelLeave,
+  relayChannelMessageTool,
+  relayChannelMessageSchema,
+  handleRelayChannelMessage,
+  relayShadowBindTool,
+  relayShadowBindSchema,
+  handleRelayShadowBind,
+  relayShadowUnbindTool,
+  relayShadowUnbindSchema,
+  handleRelayShadowUnbind,
+  relayProposalTool,
+  relayProposalSchema,
+  handleRelayProposal,
+  relayVoteTool,
+  relayVoteSchema,
+  handleRelayVote,
+} 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,
+  relayConnectedTool,
+  relaySpawnTool,
+  relayReleaseTool,
+  relayRemoveAgentTool,
+  relayStatusTool,
+  relayLogsTool,
+  relayMetricsTool,
+  relayHealthTool,
+  relayContinuityTool,
+  relayBroadcastTool,
+  relaySubscribeTool,
+  relayUnsubscribeTool,
+  relayChannelJoinTool,
+  relayChannelLeaveTool,
+  relayChannelMessageTool,
+  relayShadowBindTool,
+  relayShadowUnbindTool,
+  relayProposalTool,
+  relayVoteTool,
+];
+
+/**
+ * All available prompts
+ */
+const PROMPTS = [protocolPrompt];
+
+/**
+ * All available resources
+ */
+const RESOURCES = [agentsResource, inboxResource, projectResource];
+
+/**
+ * MCP Server configuration options
+ */
+export interface MCPServerConfig {
+  name?: string;
+  version?: string;
+}
+
+/**
+ * Create and configure an MCP server for Agent Relay
+ */
+export function createMCPServer(client: RelayClient, config?: MCPServerConfig): Server {
+  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: string;
+
+      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_connected': {
+          const input = relayConnectedSchema.parse(args);
+          result = await handleRelayConnected(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_remove_agent': {
+          const input = relayRemoveAgentSchema.parse(args);
+          result = await handleRelayRemoveAgent(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;
+        }
+
+        case 'relay_continuity': {
+          const input = relayContinuitySchema.parse(args);
+          result = await handleRelayContinuity(client, input);
+          break;
+        }
+
+        case 'relay_broadcast': {
+          const input = relayBroadcastSchema.parse(args);
+          result = await handleRelayBroadcast(client, input);
+          break;
+        }
+
+        case 'relay_subscribe': {
+          const input = relaySubscribeSchema.parse(args);
+          result = await handleRelaySubscribe(client, input);
+          break;
+        }
+
+        case 'relay_unsubscribe': {
+          const input = relayUnsubscribeSchema.parse(args);
+          result = await handleRelayUnsubscribe(client, input);
+          break;
+        }
+
+        case 'relay_channel_join': {
+          const input = relayChannelJoinSchema.parse(args);
+          result = await handleRelayChannelJoin(client, input);
+          break;
+        }
+
+        case 'relay_channel_leave': {
+          const input = relayChannelLeaveSchema.parse(args);
+          result = await handleRelayChannelLeave(client, input);
+          break;
+        }
+
+        case 'relay_channel_message': {
+          const input = relayChannelMessageSchema.parse(args);
+          result = await handleRelayChannelMessage(client, input);
+          break;
+        }
+
+        case 'relay_shadow_bind': {
+          const input = relayShadowBindSchema.parse(args);
+          result = await handleRelayShadowBind(client, input);
+          break;
+        }
+
+        case 'relay_shadow_unbind': {
+          const input = relayShadowUnbindSchema.parse(args);
+          result = await handleRelayShadowUnbind(client, input);
+          break;
+        }
+
+        case 'relay_proposal': {
+          const input = relayProposalSchema.parse(args);
+          result = await handleRelayProposal(client, input);
+          break;
+        }
+
+        case 'relay_vote': {
+          const input = relayVoteSchema.parse(args);
+          result = await handleRelayVote(client, input);
+          break;
+        }
+
+        default:
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `Unknown tool: ${name}`,
+              },
+            ],
+            isError: true,
+          };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: result,
+          },
+        ],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            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' as const,
+            content: { type: 'text' as const, 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: RelayClient, config?: MCPServerConfig): Promise<void> {
+  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);
+  });
+}