agent-relay 2.3.13 → 2.4.0

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

@@ -1,142 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient, MetricsResponse } from '../client-adapter.js';
-
-type AgentMetric = MetricsResponse['agents'][number];
-
-export const relayMetricsSchema = z.object({
-  agent: z.string().optional().describe('Filter metrics to a specific agent'),
-});
-
-export type RelayMetricsInput = z.infer<typeof relayMetricsSchema>;
-
-export const relayMetricsTool: Tool = {
-  name: 'relay_metrics',
-  description: `Get memory and resource metrics for agents.
-
-Use this to:
-- Monitor memory usage across agents
-- Detect resource-heavy workers
-- Identify memory leaks or runaway processes
-- Make informed decisions about spawning new workers
-
-Returns CPU/memory usage per agent plus system totals.
-
-Example: Get all agent metrics
-  {}
-
-Example: Get metrics for specific agent
-  { "agent": "Worker1" }`,
-  inputSchema: {
-    type: 'object',
-    properties: {
-      agent: {
-        type: 'string',
-        description: 'Filter metrics to a specific agent',
-      },
-    },
-    required: [],
-  },
-};
-
-/**
- * Format bytes to human readable string.
- */
-function formatBytes(bytes: number): string {
-  if (bytes === 0) return '0 B';
-  const k = 1024;
-  const sizes = ['B', 'KB', 'MB', 'GB'];
-  const i = Math.floor(Math.log(Math.abs(bytes)) / Math.log(k));
-  return `${(bytes / Math.pow(k, i)).toFixed(1)} ${sizes[i]}`;
-}
-
-/**
- * Format uptime in milliseconds to human readable string.
- */
-function formatUptime(ms: number): string {
-  if (ms < 60000) return `${Math.floor(ms / 1000)}s`;
-  if (ms < 3600000) return `${Math.floor(ms / 60000)}m`;
-  return `${Math.floor(ms / 3600000)}h ${Math.floor((ms % 3600000) / 60000)}m`;
-}
-
-/**
- * Get memory and resource metrics for agents.
- */
-export async function handleRelayMetrics(
-  client: RelayClient,
-  input: RelayMetricsInput
-): Promise<string> {
-  try {
-    const data: MetricsResponse = await client.getMetrics({ agent: input.agent });
-    let agents = data.agents;
-
-    // Filter to specific agent if requested
-    if (input.agent) {
-      agents = agents.filter((a: AgentMetric) => a.name === input.agent);
-      if (agents.length === 0) {
-        const available = data.agents.map((a: AgentMetric) => a.name).join(', ');
-        return `Agent "${input.agent}" not found.\n\nAvailable agents: ${available || 'none'}`;
-      }
-    }
-
-    if (agents.length === 0) {
-      return 'No agents with metrics data.';
-    }
-
-    // Build output
-    const lines: string[] = [];
-    lines.push('AGENT METRICS');
-    lines.push('═'.repeat(60));
-    lines.push('');
-
-    // System summary
-    lines.push(`System: ${formatBytes(data.system.heapUsed)} heap used / ${formatBytes(data.system.freeMemory)} free`);
-    lines.push('');
-
-    // Per-agent metrics
-    lines.push('NAME                 MEMORY      CPU     UPTIME    STATUS');
-    lines.push('─'.repeat(60));
-
-    for (const agent of agents) {
-      const name = agent.name.padEnd(20).substring(0, 20);
-      const memory = agent.rssBytes ? formatBytes(agent.rssBytes).padEnd(10) : 'N/A'.padEnd(10);
-      const cpu = agent.cpuPercent !== undefined ? `${agent.cpuPercent.toFixed(1)}%`.padEnd(7) : 'N/A'.padEnd(7);
-      const uptime = agent.uptimeMs ? formatUptime(agent.uptimeMs).padEnd(9) : 'N/A'.padEnd(9);
-      const status = agent.status;
-
-      let statusIndicator = '';
-      if (agent.alertLevel === 'critical') {
-        statusIndicator = ' [CRITICAL]';
-      } else if (agent.alertLevel === 'warning') {
-        statusIndicator = ' [WARNING]';
-      } else if (agent.trend === 'rising') {
-        statusIndicator = ' [↑]';
-      }
-
-      lines.push(`${name} ${memory} ${cpu} ${uptime} ${status}${statusIndicator}`);
-    }
-
-    // Add recommendations for high resource usage
-    const criticalAgents = agents.filter((a: AgentMetric) => a.alertLevel === 'critical');
-    const warningAgents = agents.filter((a: AgentMetric) => a.alertLevel === 'warning');
-
-    if (criticalAgents.length > 0 || warningAgents.length > 0) {
-      lines.push('');
-      lines.push('ALERTS:');
-      for (const agent of criticalAgents) {
-        lines.push(`  🔴 ${agent.name}: Critical memory usage (${formatBytes(agent.rssBytes || 0)})`);
-      }
-      for (const agent of warningAgents) {
-        lines.push(`  🟡 ${agent.name}: High memory usage (${formatBytes(agent.rssBytes || 0)})`);
-      }
-    }
-
-    return lines.join('\n');
-  } catch (err: unknown) {
-    const error = err as Error & { code?: string };
-    if (error.code === 'ECONNREFUSED' || error.code === 'ENOENT') {
-      return `Cannot connect to daemon. Is the daemon running?\n\nRun 'agent-relay up' to start the daemon.`;
-    }
-    return `Failed to fetch metrics: ${error.message || String(err)}`;
-  }
-}

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

@@ -1,54 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient } from '../client-adapter.js';
-
-export const relayReleaseSchema = z.object({
-  name: z.string().describe('Name of the worker to release'),
-  reason: z.string().optional().describe('Optional reason for release'),
-});
-
-export type RelayReleaseInput = z.infer<typeof relayReleaseSchema>;
-
-export const relayReleaseTool: Tool = {
-  name: 'relay_release',
-  description: `Release (terminate) a worker agent.
-
-Use this when a worker has completed its task or is no longer needed.
-The worker will be gracefully terminated.
-
-Example:
-  name="TestRunner"
-  reason="Tests completed successfully"`,
-  inputSchema: {
-    type: 'object',
-    properties: {
-      name: {
-        type: 'string',
-        description: 'Name of the worker to release',
-      },
-      reason: {
-        type: 'string',
-        description: 'Optional reason for release',
-      },
-    },
-    required: ['name'],
-  },
-};
-
-/**
- * Release a worker agent via the relay client.
- */
-export async function handleRelayRelease(
-  client: RelayClient,
-  input: RelayReleaseInput
-): Promise<string> {
-  const { name, reason } = input;
-
-  const result = await client.release(name, reason);
-
-  if (result.success) {
-    return `Worker "${name}" released.`;
-  } else {
-    return `Failed to release worker: ${result.error}`;
-  }
-}

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

@@ -1,58 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient } from '../client-adapter.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

@@ -1,84 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient } from '../client-adapter.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-set-model.ts

@@ -1,62 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient } from '../client-adapter.js';
-
-export const relaySetModelSchema = z.object({
-  name: z.string().describe('Name of the worker agent to change model for'),
-  model: z.string().describe('Target model (e.g., "opus", "sonnet", "haiku")'),
-  timeout_ms: z.number().optional().describe('Max time (ms) to wait for agent to become idle (default: 30000)'),
-});
-
-export type RelaySetModelInput = z.infer<typeof relaySetModelSchema>;
-
-export const relaySetModelTool: Tool = {
-  name: 'relay_set_model',
-  description: `Change the model of a running worker agent.
-
-Waits for the agent to be idle (not mid-generation), then sends the model switch command.
-Currently supported for Claude Code agents only (opus, sonnet, haiku).
-
-Example:
-  name="Worker1"
-  model="opus"`,
-  inputSchema: {
-    type: 'object',
-    properties: {
-      name: {
-        type: 'string',
-        description: 'Name of the worker agent',
-      },
-      model: {
-        type: 'string',
-        description: 'Target model (e.g., "opus", "sonnet", "haiku")',
-      },
-      timeout_ms: {
-        type: 'number',
-        description: 'Max wait time for agent idle (ms, default: 30000)',
-      },
-    },
-    required: ['name', 'model'],
-  },
-};
-
-/**
- * Change the model of a running worker agent.
- */
-export async function handleRelaySetModel(
-  client: RelayClient,
-  input: RelaySetModelInput,
-): Promise<string> {
-  const { name, model, timeout_ms } = input;
-
-  const result = await client.setWorkerModel(name, model, {
-    timeoutMs: timeout_ms,
-  });
-
-  if (result.success) {
-    const prev = result.previousModel ? ` (was: ${result.previousModel})` : '';
-    return `Model for "${name}" switched to "${model}"${prev}.`;
-  } else {
-    return `Failed to switch model for "${name}": ${result.error}`;
-  }
-}

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

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

@@ -1,87 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient } from '../client-adapter.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

@@ -1,57 +0,0 @@
-import { z } from 'zod';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { RelayClient } from '../client-adapter.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

@@ -1,61 +0,0 @@
-/**
- * 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-adapter.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}`;
-}