agent-relay 2.3.13 → 2.4.0

package/packages/mcp/src/simple.ts

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

@@ -1,155 +0,0 @@
-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 {
-  relaySetModelTool,
-  relaySetModelSchema,
-  handleRelaySetModel,
-  type RelaySetModelInput,
-} from './relay-set-model.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,
-  relayAdminChannelJoinTool,
-  relayAdminChannelJoinSchema,
-  handleRelayAdminChannelJoin,
-  type RelayAdminChannelJoinInput,
-  relayAdminRemoveMemberTool,
-  relayAdminRemoveMemberSchema,
-  handleRelayAdminRemoveMember,
-  type RelayAdminRemoveMemberInput,
-} 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';
-
-export {
-  relayQueryMessagesTool,
-  relayQueryMessagesSchema,
-  handleRelayQueryMessages,
-  type RelayQueryMessagesInput,
-} from './relay-messages.js';

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

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

@@ -1,151 +0,0 @@
-/**
- * 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-adapter.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}"`;
-}
-
-// Admin join channel
-export const relayAdminChannelJoinSchema = z.object({
-  channel: z.string().describe('The channel name'),
-  member: z.string().describe('The agent name to add to the channel'),
-});
-
-export type RelayAdminChannelJoinInput = z.infer<typeof relayAdminChannelJoinSchema>;
-
-export const relayAdminChannelJoinTool: Tool = {
-  name: 'relay_admin_channel_join',
-  description: 'Admin operation: Add any agent to a channel (does not require the agent to be connected).',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      channel: { type: 'string', description: 'The channel name' },
-      member: { type: 'string', description: 'The agent name to add to the channel' },
-    },
-    required: ['channel', 'member'],
-  },
-};
-
-export async function handleRelayAdminChannelJoin(client: RelayClient, input: RelayAdminChannelJoinInput): Promise<string> {
-  const result = await client.adminJoinChannel(input.channel, input.member);
-  if (result.success) {
-    return `Added "${input.member}" to channel "${input.channel}"`;
-  }
-  return `Failed to add member: ${result.error}`;
-}
-
-// Admin remove member
-export const relayAdminRemoveMemberSchema = z.object({
-  channel: z.string().describe('The channel name'),
-  member: z.string().describe('The agent name to remove from the channel'),
-});
-
-export type RelayAdminRemoveMemberInput = z.infer<typeof relayAdminRemoveMemberSchema>;
-
-export const relayAdminRemoveMemberTool: Tool = {
-  name: 'relay_admin_remove_member',
-  description: 'Admin operation: Remove any agent from a channel.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      channel: { type: 'string', description: 'The channel name' },
-      member: { type: 'string', description: 'The agent name to remove from the channel' },
-    },
-    required: ['channel', 'member'],
-  },
-};
-
-export async function handleRelayAdminRemoveMember(client: RelayClient, input: RelayAdminRemoveMemberInput): Promise<string> {
-  const result = await client.adminRemoveMember(input.channel, input.member);
-  if (result.success) {
-    return `Removed "${input.member}" from channel "${input.channel}"`;
-  }
-  return `Failed to remove member: ${result.error}`;
-}

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

@@ -1,67 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient } from '../client-adapter.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> {
-  let agents: Awaited<ReturnType<typeof client.listConnectedAgents>>;
-
-  try {
-    agents = await client.listConnectedAgents(input);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return `Failed to list connected agents: ${message}`;
-  }
-
-  // Defensive check: ensure agents is an array
-  if (!agents || !Array.isArray(agents)) {
-    if (process.env.DEBUG || process.env.RELAY_DEBUG) {
-      console.error('[relay_connected] listConnectedAgents returned non-array:', typeof agents, agents);
-    }
-    return 'Failed to list connected agents: unexpected response format';
-  }
-
-  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')}`;
-}