agent-relay 2.0.29 → 2.0.32

package/packages/mcp/src/tools/relay-remove-agent.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relayRemoveAgentSchema = z.object({
+  name: z.string().describe('Name of the agent to remove from the registry'),
+  remove_messages: z.boolean().optional().default(false).describe('Also remove all messages from/to this agent'),
+});
+
+export type RelayRemoveAgentInput = z.infer<typeof relayRemoveAgentSchema>;
+
+export const relayRemoveAgentTool: Tool = {
+  name: 'relay_remove_agent',
+  description: `Remove a stale agent from the relay registry.
+
+Use this to clean up agents that are no longer needed or have become stale.
+This removes the agent from:
+- The agent registry (agents.json)
+- The sessions table in storage
+- Optionally, all messages from/to this agent
+
+WARNING: This permanently removes the agent's history. Use with caution.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Name of the agent to remove',
+      },
+      remove_messages: {
+        type: 'boolean',
+        description: 'Also remove all messages from/to this agent',
+        default: false,
+      },
+    },
+    required: ['name'],
+  },
+};
+
+/**
+ * Remove an agent from the registry.
+ */
+export async function handleRelayRemoveAgent(
+  client: RelayClient,
+  input: RelayRemoveAgentInput
+): Promise<string> {
+  const result = await client.removeAgent(input.name, {
+    removeMessages: input.remove_messages,
+  });
+
+  if (result.success && result.removed) {
+    return `✓ ${result.message}`;
+  } else if (result.success && !result.removed) {
+    return `Agent "${input.name}" was not found in registry or storage.`;
+  } else {
+    return `✗ Failed to remove agent: ${result.message}`;
+  }
+}

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

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relaySendSchema = z.object({
+  to: z.string().describe('Target: agent name, #channel, or * for broadcast'),
+  message: z.string().describe('Message content'),
+  thread: z.string().optional().describe('Optional thread ID for threaded conversations'),
+  await_response: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe('If true, wait for a response (blocks until reply or timeout)'),
+  timeout_ms: z
+    .number()
+    .optional()
+    .default(30000)
+    .describe('Timeout in milliseconds when await_response is true'),
+});
+
+export type RelaySendInput = z.infer<typeof relaySendSchema>;
+
+export const relaySendTool: Tool = {
+  name: 'relay_send',
+  description: `Send a message via Agent Relay.
+
+Examples:
+- Direct message: to="Alice", message="Hello"
+- Channel: to="#general", message="Team update"
+- Broadcast: to="*", message="System notice"
+- Threaded: to="Bob", message="Follow up", thread="task-123"
+- Await reply: to="Worker", message="Process this", await_response=true`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      to: {
+        type: 'string',
+        description: 'Target: agent name, #channel, or * for broadcast',
+      },
+      message: {
+        type: 'string',
+        description: 'Message content',
+      },
+      thread: {
+        type: 'string',
+        description: 'Optional thread ID for threaded conversations',
+      },
+      await_response: {
+        type: 'boolean',
+        description: 'If true, wait for a response',
+        default: false,
+      },
+      timeout_ms: {
+        type: 'number',
+        description: 'Timeout in ms when await_response is true',
+        default: 30000,
+      },
+    },
+    required: ['to', 'message'],
+  },
+};
+
+/**
+ * Send a message via the relay daemon, optionally waiting for a response.
+ */
+export async function handleRelaySend(
+  client: RelayClient,
+  input: RelaySendInput
+): Promise<string> {
+  const { to, message, thread, await_response, timeout_ms } = input;
+
+  if (await_response) {
+    const ack = await client.sendAndWait(to, message, {
+      thread,
+      timeoutMs: timeout_ms,
+    });
+    // Extract response from AckPayload
+    const responseText = ack.response || ack.responseData ? String(ack.responseData || ack.response) : 'OK';
+    return `Response from ${to}: ${responseText}`;
+  }
+
+  await client.send(to, message, { thread });
+  return `Message sent to ${to}`;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * relay_shadow_bind / relay_shadow_unbind - Shadow agent operations
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+// Bind as shadow
+export const relayShadowBindSchema = z.object({
+  primary_agent: z.string().describe('The name of the primary agent to shadow'),
+  speak_on: z.array(z.string()).optional().describe('Events that trigger the shadow to speak (e.g., ["SESSION_END", "CODE_WRITTEN"])'),
+});
+
+export type RelayShadowBindInput = z.infer<typeof relayShadowBindSchema>;
+
+export const relayShadowBindTool: Tool = {
+  name: 'relay_shadow_bind',
+  description: 'Bind as a shadow agent to monitor another agent. Shadows can observe and optionally respond to specific events.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      primary_agent: { type: 'string', description: 'The name of the primary agent to shadow' },
+      speak_on: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Events that trigger the shadow to speak (e.g., ["SESSION_END", "CODE_WRITTEN", "REVIEW_REQUEST"])',
+      },
+    },
+    required: ['primary_agent'],
+  },
+};
+
+export async function handleRelayShadowBind(client: RelayClient, input: RelayShadowBindInput): Promise<string> {
+  const result = await client.bindAsShadow(input.primary_agent, { speakOn: input.speak_on });
+  if (result.success) {
+    return `Now shadowing agent "${input.primary_agent}"`;
+  }
+  return `Failed to bind as shadow: ${result.error}`;
+}
+
+// Unbind from shadow
+export const relayShadowUnbindSchema = z.object({
+  primary_agent: z.string().describe('The name of the primary agent to stop shadowing'),
+});
+
+export type RelayShadowUnbindInput = z.infer<typeof relayShadowUnbindSchema>;
+
+export const relayShadowUnbindTool: Tool = {
+  name: 'relay_shadow_unbind',
+  description: 'Stop shadowing an agent.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      primary_agent: { type: 'string', description: 'The name of the primary agent to stop shadowing' },
+    },
+    required: ['primary_agent'],
+  },
+};
+
+export async function handleRelayShadowUnbind(client: RelayClient, input: RelayShadowUnbindInput): Promise<string> {
+  const result = await client.unbindAsShadow(input.primary_agent);
+  if (result.success) {
+    return `Stopped shadowing agent "${input.primary_agent}"`;
+  }
+  return `Failed to unbind from shadow: ${result.error}`;
+}

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

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+/**
+ * Supported CLI tools for spawning workers.
+ * This list should be kept in sync with CliType in packages/wrapper/src/shared.ts
+ * Note: 'cursor', 'spawned', 'other' are excluded as they're not valid spawn targets.
+ */
+export const SPAWNABLE_CLIS = ['claude', 'codex', 'gemini', 'droid', 'opencode'] as const;
+export type SpawnableCli = typeof SPAWNABLE_CLIS[number];
+
+export const relaySpawnSchema = z.object({
+  name: z.string().describe('Unique name for the worker agent'),
+  cli: z.enum(SPAWNABLE_CLIS).describe(
+    'CLI tool to use for the worker (claude, codex, gemini, droid, opencode)'
+  ),
+  task: z.string().describe('Task description/prompt for the worker'),
+  model: z.string().optional().describe('Model override (e.g., "claude-3-5-sonnet")'),
+  cwd: z.string().optional().describe('Working directory for the worker'),
+});
+
+export type RelaySpawnInput = z.infer<typeof relaySpawnSchema>;
+
+export const relaySpawnTool: Tool = {
+  name: 'relay_spawn',
+  description: `Spawn a worker agent to handle a subtask.
+
+The worker runs in a separate process with its own CLI instance.
+You'll receive a confirmation when the worker is ready.
+
+Example:
+  name="TestRunner"
+  cli="claude"
+  task="Run the test suite and report failures"`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Unique name for the worker agent',
+      },
+      cli: {
+        type: 'string',
+        enum: SPAWNABLE_CLIS as unknown as string[],
+        description: 'CLI tool to use (claude, codex, gemini, droid, opencode)',
+      },
+      task: {
+        type: 'string',
+        description: 'Task description for the worker',
+      },
+      model: {
+        type: 'string',
+        description: 'Optional model override',
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory for the worker',
+      },
+    },
+    required: ['name', 'cli', 'task'],
+  },
+};
+
+/**
+ * Spawn a worker agent using the relay client.
+ */
+export async function handleRelaySpawn(
+  client: RelayClient,
+  input: RelaySpawnInput
+): Promise<string> {
+  const { name, cli, task, model, cwd } = input;
+
+  const result = await client.spawn({
+    name,
+    cli,
+    task,
+    model,
+    cwd,
+  });
+
+  if (result.success) {
+    return `Worker "${name}" spawned successfully. It will message you when ready.`;
+  } else {
+    return `Failed to spawn worker: ${result.error}`;
+  }
+}

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

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relayStatusSchema = z.object({});
+
+export type RelayStatusInput = z.infer<typeof relayStatusSchema>;
+
+export const relayStatusTool: Tool = {
+  name: 'relay_status',
+  description: `Show connection and daemon status for Agent Relay.`,
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: [],
+  },
+};
+
+/**
+ * Retrieve relay daemon status and format a human-readable summary.
+ */
+export async function handleRelayStatus(
+  client: RelayClient,
+  _input: RelayStatusInput
+): Promise<string> {
+  const status = await client.getStatus();
+  const connected = status.connected ? 'Yes' : 'No';
+
+  let agentCount: string | number = 'unknown';
+  if (typeof (client as any).listAgents === 'function') {
+    try {
+      const agents = await (client as any).listAgents({});
+      agentCount = Array.isArray(agents) ? agents.length : 'unknown';
+    } catch {
+      agentCount = 'unknown';
+    }
+  }
+
+  const lines = [
+    `Connected: ${connected}`,
+    `Agent Name: ${status.agentName}`,
+    `Project: ${status.project}`,
+    `Socket: ${status.socketPath}`,
+  ];
+
+  if (status.daemonVersion) {
+    lines.push(`Daemon Version: ${status.daemonVersion}`);
+  }
+
+  if (status.uptime) {
+    lines.push(`Uptime: ${status.uptime}`);
+  }
+
+  lines.push(`Agent Count: ${agentCount}`);
+
+  return lines.join('\n');
+}

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

@@ -0,0 +1,61 @@
+/**
+ * relay_subscribe / relay_unsubscribe - Pub/Sub topic subscription
+ */
+
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+// Subscribe schema and tool
+export const relaySubscribeSchema = z.object({
+  topic: z.string().describe('The topic to subscribe to'),
+});
+
+export type RelaySubscribeInput = z.infer<typeof relaySubscribeSchema>;
+
+export const relaySubscribeTool: Tool = {
+  name: 'relay_subscribe',
+  description: 'Subscribe to a topic to receive messages published to that topic.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      topic: { type: 'string', description: 'The topic to subscribe to' },
+    },
+    required: ['topic'],
+  },
+};
+
+export async function handleRelaySubscribe(client: RelayClient, input: RelaySubscribeInput): Promise<string> {
+  const result = await client.subscribe(input.topic);
+  if (result.success) {
+    return `Subscribed to topic "${input.topic}"`;
+  }
+  return `Failed to subscribe: ${result.error}`;
+}
+
+// Unsubscribe schema and tool
+export const relayUnsubscribeSchema = z.object({
+  topic: z.string().describe('The topic to unsubscribe from'),
+});
+
+export type RelayUnsubscribeInput = z.infer<typeof relayUnsubscribeSchema>;
+
+export const relayUnsubscribeTool: Tool = {
+  name: 'relay_unsubscribe',
+  description: 'Unsubscribe from a topic to stop receiving messages from it.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      topic: { type: 'string', description: 'The topic to unsubscribe from' },
+    },
+    required: ['topic'],
+  },
+};
+
+export async function handleRelayUnsubscribe(client: RelayClient, input: RelayUnsubscribeInput): Promise<string> {
+  const result = await client.unsubscribe(input.topic);
+  if (result.success) {
+    return `Unsubscribed from topic "${input.topic}"`;
+  }
+  return `Failed to unsubscribe: ${result.error}`;
+}

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

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relayWhoSchema = z.object({
+  include_idle: z.boolean().optional().default(true).describe('Include idle agents'),
+  project: z.string().optional().describe('Filter by project (for multi-project setups)'),
+});
+
+export type RelayWhoInput = z.infer<typeof relayWhoSchema>;
+
+export const relayWhoTool: Tool = {
+  name: 'relay_who',
+  description: `List online agents in the relay network.
+
+Shows agent names, their CLI type, and current status.
+
+Example output:
+- Alice (claude) - active
+- Bob (codex) - idle
+- TestRunner (claude) - active [worker of: Alice]`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      include_idle: {
+        type: 'boolean',
+        description: 'Include idle agents',
+        default: true,
+      },
+      project: {
+        type: 'string',
+        description: 'Filter by project',
+      },
+    },
+    required: [],
+  },
+};
+
+/**
+ * List online agents with status and optional project filtering.
+ */
+export async function handleRelayWho(
+  client: RelayClient,
+  input: RelayWhoInput
+): Promise<string> {
+  const agents = await client.listAgents(input);
+
+  if (agents.length === 0) {
+    return 'No agents online.';
+  }
+
+  const formatted = agents.map((a) => {
+    const status = a.idle ? 'idle' : 'active';
+    const worker = a.parent ? ` [worker of: ${a.parent}]` : '';
+    return `- ${a.name} (${a.cli}) - ${status}${worker}`;
+  });
+
+  return `${agents.length} agent(s) online:\n${formatted.join('\n')}`;
+}