agent-relay 2.0.28 → 2.0.32

package/packages/mcp/src/simple.ts

@@ -0,0 +1,214 @@
+/**
+ * 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';
+import type { AckPayload } from '@agent-relay/protocol';
+
+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<AckPayload>;
+
+  /** 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 function createTools(agentName: string, config: ToolsConfig = {}): RelayTools {
+  const client = createRelayClient({
+    agentName,
+    socketPath: config.socketPath,
+    project: config.project,
+    timeout: config.timeout,
+  });
+
+  return {
+    send: (to, message, options) => client.send(to, message, options),
+    sendAndWait: (to, message, options) => client.sendAndWait(to, message, options),
+    inbox: (options) => client.getInbox(options),
+    who: (options) => client.listAgents(options),
+    spawn: (options) => client.spawn(options),
+    release: (name, reason) => client.release(name, reason),
+    status: () => client.getStatus(),
+    get client() {
+      return client;
+    },
+  };
+}
+
+/**
+ * Convenience function for one-off messages.
+ *
+ * @example
+ * ```typescript
+ * import { send } from '@agent-relay/mcp/simple';
+ *
+ * await send('MyAgent', 'Bob', 'Hello!');
+ * ```
+ */
+export async function send(
+  fromAgent: string,
+  to: string,
+  message: string,
+  options?: { thread?: string } & ToolsConfig
+): Promise<void> {
+  const tools = createTools(fromAgent, options);
+  await tools.send(to, message, { thread: options?.thread });
+}
+
+/**
+ * Convenience function to check inbox.
+ *
+ * @example
+ * ```typescript
+ * import { inbox } from '@agent-relay/mcp/simple';
+ *
+ * const messages = await inbox('MyAgent');
+ * ```
+ */
+export async function inbox(
+  agentName: string,
+  options?: { limit?: number; unread_only?: boolean; from?: string; channel?: string } & ToolsConfig
+): Promise<Message[]> {
+  const tools = createTools(agentName, options);
+  return tools.inbox(options);
+}
+
+/**
+ * Convenience function to list agents.
+ *
+ * @example
+ * ```typescript
+ * import { who } from '@agent-relay/mcp/simple';
+ *
+ * const agents = await who();
+ * ```
+ */
+export async function who(options?: { include_idle?: boolean } & ToolsConfig): Promise<Agent[]> {
+  const tools = createTools('_query', options);
+  return tools.who(options);
+}
+
+// Re-export client for advanced use
+export { createRelayClient, type RelayClient, type RelayClientOptions };

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

@@ -0,0 +1,133 @@
+export {
+  relaySendTool,
+  relaySendSchema,
+  handleRelaySend,
+  type RelaySendInput,
+} from './relay-send.js';
+
+export {
+  relayInboxTool,
+  relayInboxSchema,
+  handleRelayInbox,
+  type RelayInboxInput,
+} from './relay-inbox.js';
+
+export { relayWhoTool, relayWhoSchema, handleRelayWho, type RelayWhoInput } from './relay-who.js';
+
+export {
+  relaySpawnTool,
+  relaySpawnSchema,
+  handleRelaySpawn,
+  type RelaySpawnInput,
+} from './relay-spawn.js';
+
+export {
+  relayReleaseTool,
+  relayReleaseSchema,
+  handleRelayRelease,
+  type RelayReleaseInput,
+} from './relay-release.js';
+
+export {
+  relayStatusTool,
+  relayStatusSchema,
+  handleRelayStatus,
+  type RelayStatusInput,
+} from './relay-status.js';
+
+export {
+  relayLogsTool,
+  relayLogsSchema,
+  handleRelayLogs,
+  type RelayLogsInput,
+} from './relay-logs.js';
+
+export {
+  relayMetricsTool,
+  relayMetricsSchema,
+  handleRelayMetrics,
+  type RelayMetricsInput,
+} from './relay-metrics.js';
+
+export {
+  relayHealthTool,
+  relayHealthSchema,
+  handleRelayHealth,
+  type RelayHealthInput,
+} from './relay-health.js';
+
+export {
+  relayContinuityTool,
+  relayContinuitySchema,
+  handleRelayContinuity,
+  type RelayContinuityInput,
+} from './relay-continuity.js';
+
+export {
+  relayConnectedTool,
+  relayConnectedSchema,
+  handleRelayConnected,
+  type RelayConnectedInput,
+} from './relay-connected.js';
+
+export {
+  relayRemoveAgentTool,
+  relayRemoveAgentSchema,
+  handleRelayRemoveAgent,
+  type RelayRemoveAgentInput,
+} from './relay-remove-agent.js';
+
+export {
+  relayBroadcastTool,
+  relayBroadcastSchema,
+  handleRelayBroadcast,
+  type RelayBroadcastInput,
+} from './relay-broadcast.js';
+
+export {
+  relaySubscribeTool,
+  relaySubscribeSchema,
+  handleRelaySubscribe,
+  type RelaySubscribeInput,
+  relayUnsubscribeTool,
+  relayUnsubscribeSchema,
+  handleRelayUnsubscribe,
+  type RelayUnsubscribeInput,
+} from './relay-subscribe.js';
+
+export {
+  relayChannelJoinTool,
+  relayChannelJoinSchema,
+  handleRelayChannelJoin,
+  type RelayChannelJoinInput,
+  relayChannelLeaveTool,
+  relayChannelLeaveSchema,
+  handleRelayChannelLeave,
+  type RelayChannelLeaveInput,
+  relayChannelMessageTool,
+  relayChannelMessageSchema,
+  handleRelayChannelMessage,
+  type RelayChannelMessageInput,
+} from './relay-channel.js';
+
+export {
+  relayShadowBindTool,
+  relayShadowBindSchema,
+  handleRelayShadowBind,
+  type RelayShadowBindInput,
+  relayShadowUnbindTool,
+  relayShadowUnbindSchema,
+  handleRelayShadowUnbind,
+  type RelayShadowUnbindInput,
+} from './relay-shadow.js';
+
+export {
+  relayProposalTool,
+  relayProposalSchema,
+  handleRelayProposal,
+  type RelayProposalInput,
+  relayVoteTool,
+  relayVoteSchema,
+  handleRelayVote,
+  type RelayVoteInput,
+} from './relay-consensus.js';

package/packages/mcp/src/tools/relay-broadcast.ts

@@ -0,0 +1,32 @@
+/**
+ * relay_broadcast - Broadcast a message to all connected agents
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relayBroadcastSchema = z.object({
+  message: z.string().describe('The message to broadcast to all agents'),
+  kind: z.enum(['message', 'action', 'state', 'thinking']).optional().describe('Message kind (default: message)'),
+});
+
+export type RelayBroadcastInput = z.infer<typeof relayBroadcastSchema>;
+
+export const relayBroadcastTool: Tool = {
+  name: 'relay_broadcast',
+  description: 'Broadcast a message to ALL connected agents at once. Use this when you need to send the same message to everyone.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      message: { type: 'string', description: 'The message to broadcast to all agents' },
+      kind: { type: 'string', enum: ['message', 'action', 'state', 'thinking'], description: 'Message kind (default: message)' },
+    },
+    required: ['message'],
+  },
+};
+
+export async function handleRelayBroadcast(client: RelayClient, input: RelayBroadcastInput): Promise<string> {
+  await client.broadcast(input.message, { kind: input.kind });
+  return 'Message broadcast to all agents';
+}

package/packages/mcp/src/tools/relay-channel.ts

@@ -0,0 +1,93 @@
+/**
+ * relay_channel_join / relay_channel_leave / relay_channel_message - Channel operations
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+// Join channel
+export const relayChannelJoinSchema = z.object({
+  channel: z.string().describe('The channel name to join (e.g., "#general")'),
+  display_name: z.string().optional().describe('Optional display name to use in the channel'),
+});
+
+export type RelayChannelJoinInput = z.infer<typeof relayChannelJoinSchema>;
+
+export const relayChannelJoinTool: Tool = {
+  name: 'relay_channel_join',
+  description: 'Join a channel to participate in group conversations. Channels start with #.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      channel: { type: 'string', description: 'The channel name to join (e.g., "#general")' },
+      display_name: { type: 'string', description: 'Optional display name to use in the channel' },
+    },
+    required: ['channel'],
+  },
+};
+
+export async function handleRelayChannelJoin(client: RelayClient, input: RelayChannelJoinInput): Promise<string> {
+  const result = await client.joinChannel(input.channel, input.display_name);
+  if (result.success) {
+    return `Joined channel "${input.channel}"`;
+  }
+  return `Failed to join channel: ${result.error}`;
+}
+
+// Leave channel
+export const relayChannelLeaveSchema = z.object({
+  channel: z.string().describe('The channel name to leave'),
+  reason: z.string().optional().describe('Optional reason for leaving'),
+});
+
+export type RelayChannelLeaveInput = z.infer<typeof relayChannelLeaveSchema>;
+
+export const relayChannelLeaveTool: Tool = {
+  name: 'relay_channel_leave',
+  description: 'Leave a channel you are currently in.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      channel: { type: 'string', description: 'The channel name to leave' },
+      reason: { type: 'string', description: 'Optional reason for leaving' },
+    },
+    required: ['channel'],
+  },
+};
+
+export async function handleRelayChannelLeave(client: RelayClient, input: RelayChannelLeaveInput): Promise<string> {
+  const result = await client.leaveChannel(input.channel, input.reason);
+  if (result.success) {
+    return `Left channel "${input.channel}"`;
+  }
+  return `Failed to leave channel: ${result.error}`;
+}
+
+// Send channel message
+export const relayChannelMessageSchema = z.object({
+  channel: z.string().describe('The channel to send the message to'),
+  message: z.string().describe('The message content'),
+  thread: z.string().optional().describe('Optional thread ID for threaded conversations'),
+});
+
+export type RelayChannelMessageInput = z.infer<typeof relayChannelMessageSchema>;
+
+export const relayChannelMessageTool: Tool = {
+  name: 'relay_channel_message',
+  description: 'Send a message to a channel. You must be a member of the channel.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      channel: { type: 'string', description: 'The channel to send the message to' },
+      message: { type: 'string', description: 'The message content' },
+      thread: { type: 'string', description: 'Optional thread ID for threaded conversations' },
+    },
+    required: ['channel', 'message'],
+  },
+};
+
+export async function handleRelayChannelMessage(client: RelayClient, input: RelayChannelMessageInput): Promise<string> {
+  await client.sendChannelMessage(input.channel, input.message, { thread: input.thread });
+  return `Message sent to channel "${input.channel}"`;
+}

package/packages/mcp/src/tools/relay-connected.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relayConnectedSchema = z.object({
+  project: z.string().optional().describe('Filter by project (for multi-project setups)'),
+});
+
+export type RelayConnectedInput = z.infer<typeof relayConnectedSchema>;
+
+export const relayConnectedTool: Tool = {
+  name: 'relay_connected',
+  description: `List only currently connected agents in the relay network.
+
+Unlike relay_who which includes historical/registered agents, this only shows
+agents that are actively connected right now. Use this for accurate liveness checks.
+
+Example output:
+- Alice (claude) - connected
+- Bob (codex) - connected`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      project: {
+        type: 'string',
+        description: 'Filter by project',
+      },
+    },
+    required: [],
+  },
+};
+
+/**
+ * List only currently connected agents (not historical/registered).
+ */
+export async function handleRelayConnected(
+  client: RelayClient,
+  input: RelayConnectedInput
+): Promise<string> {
+  const agents = await client.listConnectedAgents(input);
+
+  if (agents.length === 0) {
+    return 'No agents currently connected.';
+  }
+
+  const formatted = agents.map((a: { name: string; cli?: string; parent?: string }) => {
+    const worker = a.parent ? ` [worker of: ${a.parent}]` : '';
+    return `- ${a.name} (${a.cli || 'unknown'}) - connected${worker}`;
+  });
+
+  return `${agents.length} agent(s) currently connected:\n${formatted.join('\n')}`;
+}

package/packages/mcp/src/tools/relay-consensus.ts

@@ -0,0 +1,92 @@
+/**
+ * relay_proposal / relay_vote - Consensus/voting operations
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+// Create proposal
+export const relayProposalSchema = z.object({
+  id: z.string().describe('Unique identifier for the proposal'),
+  description: z.string().describe('Description of what is being proposed'),
+  options: z.array(z.string()).describe('List of voting options'),
+  voting_method: z.enum(['majority', 'supermajority', 'unanimous', 'weighted', 'quorum']).optional()
+    .describe('Voting method (default: majority)'),
+  deadline: z.number().optional().describe('Optional deadline timestamp in milliseconds'),
+});
+
+export type RelayProposalInput = z.infer<typeof relayProposalSchema>;
+
+export const relayProposalTool: Tool = {
+  name: 'relay_proposal',
+  description: 'Create a new proposal for agents to vote on. Use this to coordinate decisions among multiple agents.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Unique identifier for the proposal' },
+      description: { type: 'string', description: 'Description of what is being proposed' },
+      options: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'List of voting options',
+      },
+      voting_method: {
+        type: 'string',
+        enum: ['majority', 'supermajority', 'unanimous', 'weighted', 'quorum'],
+        description: 'Voting method (default: majority)',
+      },
+      deadline: { type: 'number', description: 'Optional deadline timestamp in milliseconds' },
+    },
+    required: ['id', 'description', 'options'],
+  },
+};
+
+export async function handleRelayProposal(client: RelayClient, input: RelayProposalInput): Promise<string> {
+  const result = await client.createProposal({
+    id: input.id,
+    description: input.description,
+    options: input.options,
+    votingMethod: input.voting_method,
+    deadline: input.deadline,
+  });
+  if (result.success) {
+    return `Proposal "${input.id}" created successfully. Options: ${input.options.join(', ')}`;
+  }
+  return `Failed to create proposal: ${result.error}`;
+}
+
+// Vote on proposal
+export const relayVoteSchema = z.object({
+  proposal_id: z.string().describe('The ID of the proposal to vote on'),
+  vote: z.string().describe('Your vote (must be one of the proposal options, or "approve"/"reject"/"abstain")'),
+  reason: z.string().optional().describe('Optional reason for your vote'),
+});
+
+export type RelayVoteInput = z.infer<typeof relayVoteSchema>;
+
+export const relayVoteTool: Tool = {
+  name: 'relay_vote',
+  description: 'Cast a vote on an existing proposal.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      proposal_id: { type: 'string', description: 'The ID of the proposal to vote on' },
+      vote: { type: 'string', description: 'Your vote (must be one of the proposal options, or "approve"/"reject"/"abstain")' },
+      reason: { type: 'string', description: 'Optional reason for your vote' },
+    },
+    required: ['proposal_id', 'vote'],
+  },
+};
+
+export async function handleRelayVote(client: RelayClient, input: RelayVoteInput): Promise<string> {
+  const result = await client.vote({
+    proposalId: input.proposal_id,
+    vote: input.vote,
+    reason: input.reason,
+  });
+  if (result.success) {
+    return `Vote "${input.vote}" cast on proposal "${input.proposal_id}"`;
+  }
+  return `Failed to vote: ${result.error}`;
+}