agent-relay 2.3.13 → 2.4.0

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

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

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

@@ -1,164 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-/**
- * 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-adapter.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

@@ -1,21 +0,0 @@
-/**
- * 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-adapter.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

@@ -1,3 +0,0 @@
-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

@@ -1,29 +0,0 @@
-/**
- * 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-adapter.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

@@ -1,475 +0,0 @@
-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-adapter.js';
-import {
-  relaySendTool,
-  relaySendSchema,
-  handleRelaySend,
-  relayInboxTool,
-  relayInboxSchema,
-  handleRelayInbox,
-  relayWhoTool,
-  relayWhoSchema,
-  handleRelayWho,
-  relaySpawnTool,
-  relaySpawnSchema,
-  handleRelaySpawn,
-  relayReleaseTool,
-  relayReleaseSchema,
-  handleRelayRelease,
-  relaySetModelTool,
-  relaySetModelSchema,
-  handleRelaySetModel,
-  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,
-  relayAdminChannelJoinTool,
-  relayAdminChannelJoinSchema,
-  handleRelayAdminChannelJoin,
-  relayAdminRemoveMemberTool,
-  relayAdminRemoveMemberSchema,
-  handleRelayAdminRemoveMember,
-  relayShadowBindTool,
-  relayShadowBindSchema,
-  handleRelayShadowBind,
-  relayShadowUnbindTool,
-  relayShadowUnbindSchema,
-  handleRelayShadowUnbind,
-  relayProposalTool,
-  relayProposalSchema,
-  handleRelayProposal,
-  relayVoteTool,
-  relayVoteSchema,
-  handleRelayVote,
-  relayQueryMessagesTool,
-  relayQueryMessagesSchema,
-  handleRelayQueryMessages,
-} 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,
-  relaySetModelTool,
-  relayRemoveAgentTool,
-  relayStatusTool,
-  relayLogsTool,
-  relayMetricsTool,
-  relayHealthTool,
-  relayContinuityTool,
-  relayBroadcastTool,
-  relaySubscribeTool,
-  relayUnsubscribeTool,
-  relayChannelJoinTool,
-  relayChannelLeaveTool,
-  relayChannelMessageTool,
-  relayAdminChannelJoinTool,
-  relayAdminRemoveMemberTool,
-  relayShadowBindTool,
-  relayShadowUnbindTool,
-  relayProposalTool,
-  relayVoteTool,
-  relayQueryMessagesTool,
-];
-
-/**
- * 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;
-  agentName?: string;
-  project?: string;
-  projectRoot?: string;
-  socketPath?: 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_set_model': {
-          const input = relaySetModelSchema.parse(args);
-          result = await handleRelaySetModel(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_admin_channel_join': {
-          const input = relayAdminChannelJoinSchema.parse(args);
-          result = await handleRelayAdminChannelJoin(client, input);
-          break;
-        }
-
-        case 'relay_admin_remove_member': {
-          const input = relayAdminRemoveMemberSchema.parse(args);
-          result = await handleRelayAdminRemoveMember(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;
-        }
-
-        case 'relay_query_messages': {
-          const input = relayQueryMessagesSchema.parse(args);
-          result = await handleRelayQueryMessages(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);
-  });
-}