agent-relay 2.0.28 → 2.0.32

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

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relayContinuitySchema = z.object({
+  action: z.enum(['save', 'load', 'uncertain']).describe('Action: save state, load previous state, or mark uncertainty'),
+  current_task: z.string().optional().describe('Current task being worked on (for save)'),
+  completed: z.string().optional().describe('Completed work summary (for save)'),
+  in_progress: z.string().optional().describe('In-progress work summary (for save)'),
+  key_decisions: z.string().optional().describe('Key decisions made (for save)'),
+  files: z.string().optional().describe('Files being worked on (for save)'),
+  item: z.string().optional().describe('Item to mark as uncertain (for uncertain action)'),
+});
+
+export type RelayContinuityInput = z.infer<typeof relayContinuitySchema>;
+
+export const relayContinuityTool: Tool = {
+  name: 'relay_continuity',
+  description: `Manage session continuity for agent recovery.
+
+Use this to:
+- Save your current state before long operations or session end
+- Load previous context when starting a new session
+- Mark items that need future verification
+
+Examples:
+- Save state: action="save", current_task="Implementing auth", completed="User model done"
+- Load state: action="load"
+- Mark uncertain: action="uncertain", item="API rate limit handling unclear"`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['save', 'load', 'uncertain'],
+        description: 'Action: save state, load previous state, or mark uncertainty',
+      },
+      current_task: {
+        type: 'string',
+        description: 'Current task being worked on (for save)',
+      },
+      completed: {
+        type: 'string',
+        description: 'Completed work summary (for save)',
+      },
+      in_progress: {
+        type: 'string',
+        description: 'In-progress work summary (for save)',
+      },
+      key_decisions: {
+        type: 'string',
+        description: 'Key decisions made (for save)',
+      },
+      files: {
+        type: 'string',
+        description: 'Files being worked on (for save)',
+      },
+      item: {
+        type: 'string',
+        description: 'Item to mark as uncertain (for uncertain action)',
+      },
+    },
+    required: ['action'],
+  },
+};
+
+// Extended client interface for continuity features
+interface ExtendedRelayClient extends RelayClient {
+  saveContinuity?: (state: {
+    currentTask?: string;
+    completed?: string;
+    inProgress?: string;
+    keyDecisions?: string;
+    files?: string;
+  }) => Promise<void>;
+  loadContinuity?: () => Promise<void>;
+  markUncertain?: (item: string) => Promise<void>;
+}
+
+/**
+ * Handle continuity actions for session recovery.
+ */
+export async function handleRelayContinuity(
+  client: RelayClient,
+  input: RelayContinuityInput
+): Promise<string> {
+  const extClient = client as ExtendedRelayClient;
+  const { action, current_task, completed, in_progress, key_decisions, files, item } = input;
+
+  switch (action) {
+    case 'save': {
+      if (!extClient.saveContinuity) {
+        return 'Continuity save not supported by this client';
+      }
+      await extClient.saveContinuity({
+        currentTask: current_task,
+        completed,
+        inProgress: in_progress,
+        keyDecisions: key_decisions,
+        files,
+      });
+      return 'Session state saved for recovery';
+    }
+
+    case 'load': {
+      if (!extClient.loadContinuity) {
+        return 'Continuity load not supported by this client';
+      }
+      await extClient.loadContinuity();
+      return 'Previous session context loaded';
+    }
+
+    case 'uncertain': {
+      if (!extClient.markUncertain) {
+        return 'Mark uncertain not supported by this client';
+      }
+      if (!item) {
+        return 'Item required for uncertain action';
+      }
+      await extClient.markUncertain(item);
+      return `Marked as uncertain: ${item}`;
+    }
+
+    default:
+      return `Unknown action: ${action}`;
+  }
+}

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

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient, HealthResponse } from '../client.js';
+
+export const relayHealthSchema = z.object({
+  include_crashes: z.boolean().optional().default(true).describe('Include recent crash history'),
+  include_alerts: z.boolean().optional().default(true).describe('Include unacknowledged alerts'),
+});
+
+export type RelayHealthInput = z.infer<typeof relayHealthSchema>;
+
+export const relayHealthTool: Tool = {
+  name: 'relay_health',
+  description: `Get system health, crash insights, and recommendations.
+
+Use this to:
+- Check overall system health score
+- View recent agent crashes and their causes
+- Get recommendations for improving stability
+- Identify recurring issues
+
+Returns health score (0-100), issues, recommendations, and crash history.
+
+Example: Full health check
+  {}
+
+Example: Health check without crash history
+  { "include_crashes": false }`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      include_crashes: {
+        type: 'boolean',
+        description: 'Include recent crash history',
+        default: true,
+      },
+      include_alerts: {
+        type: 'boolean',
+        description: 'Include unacknowledged alerts',
+        default: true,
+      },
+    },
+    required: [],
+  },
+};
+
+/**
+ * Get system health, crash insights, and recommendations.
+ */
+export async function handleRelayHealth(
+  client: RelayClient,
+  input: RelayHealthInput
+): Promise<string> {
+  try {
+    const data: HealthResponse = await client.getHealth({
+      include_crashes: input.include_crashes,
+      include_alerts: input.include_alerts,
+    });
+
+    const lines: string[] = [];
+
+    // Health score header
+    const scoreEmoji = data.healthScore >= 80 ? '✅' :
+                       data.healthScore >= 50 ? '⚠️' : '🔴';
+
+    lines.push('═'.repeat(60));
+    lines.push(`  SYSTEM HEALTH: ${scoreEmoji} ${data.healthScore}/100`);
+    lines.push('═'.repeat(60));
+    lines.push('');
+    lines.push(`  ${data.summary}`);
+    lines.push('');
+
+    // Stats
+    lines.push(`  Agents: ${data.stats.agentCount}`);
+    lines.push(`  Crashes (24h): ${data.stats.totalCrashes24h}`);
+    lines.push(`  Alerts (24h): ${data.stats.totalAlerts24h}`);
+    lines.push('');
+
+    // Issues
+    if (data.issues.length > 0) {
+      lines.push('ISSUES:');
+      for (const issue of data.issues) {
+        const icon = issue.severity === 'critical' ? '🔴' :
+                     issue.severity === 'high' ? '🟠' :
+                     issue.severity === 'medium' ? '🟡' : '🔵';
+        lines.push(`  ${icon} ${issue.message}`);
+      }
+      lines.push('');
+    }
+
+    // Recommendations
+    if (data.recommendations.length > 0) {
+      lines.push('RECOMMENDATIONS:');
+      for (const rec of data.recommendations) {
+        lines.push(`  → ${rec}`);
+      }
+      lines.push('');
+    }
+
+    // Crashes
+    if (input.include_crashes && data.crashes.length > 0) {
+      lines.push('RECENT CRASHES:');
+      lines.push('─'.repeat(60));
+      for (const crash of data.crashes.slice(0, 5)) {
+        const time = new Date(crash.crashedAt).toLocaleString();
+        lines.push(`  ${crash.agentName} - ${time}`);
+        lines.push(`    Cause: ${crash.likelyCause}`);
+        if (crash.summary) {
+          lines.push(`    Summary: ${crash.summary.substring(0, 80)}${crash.summary.length > 80 ? '...' : ''}`);
+        }
+        lines.push('');
+      }
+      if (data.crashes.length > 5) {
+        lines.push(`  ... and ${data.crashes.length - 5} more crashes`);
+        lines.push('');
+      }
+    }
+
+    // Alerts
+    if (input.include_alerts && data.alerts.length > 0) {
+      lines.push('UNACKNOWLEDGED ALERTS:');
+      lines.push('─'.repeat(60));
+      for (const alert of data.alerts.slice(0, 5)) {
+        const time = new Date(alert.createdAt).toLocaleString();
+        lines.push(`  [${alert.alertType}] ${alert.agentName} - ${time}`);
+        lines.push(`    ${alert.message}`);
+        lines.push('');
+      }
+      if (data.alerts.length > 5) {
+        lines.push(`  ... and ${data.alerts.length - 5} more alerts`);
+        lines.push('');
+      }
+    }
+
+    // No issues message
+    if (data.issues.length === 0 && data.crashes.length === 0 && data.alerts.length === 0) {
+      lines.push('No issues detected. System is healthy.');
+    }
+
+    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 health data: ${error.message || String(err)}`;
+  }
+}

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

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+
+export const relayInboxSchema = z.object({
+  limit: z.number().optional().default(10).describe('Max messages to return'),
+  unread_only: z.boolean().optional().default(true).describe('Only return unread messages'),
+  from: z.string().optional().describe('Filter by sender'),
+  channel: z.string().optional().describe('Filter by channel'),
+});
+
+export type RelayInboxInput = z.infer<typeof relayInboxSchema>;
+
+export const relayInboxTool: Tool = {
+  name: 'relay_inbox',
+  description: `Check your inbox for pending messages.
+
+Returns messages sent to you by other agents or in channels you're subscribed to.
+
+Examples:
+- Get all unread: (no params)
+- From specific agent: from="Alice"
+- From channel: channel="#general"`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Max messages to return',
+        default: 10,
+      },
+      unread_only: {
+        type: 'boolean',
+        description: 'Only return unread messages',
+        default: true,
+      },
+      from: {
+        type: 'string',
+        description: 'Filter by sender',
+      },
+      channel: {
+        type: 'string',
+        description: 'Filter by channel',
+      },
+    },
+    required: [],
+  },
+};
+
+/**
+ * Retrieve inbox messages from the relay daemon with optional filtering.
+ */
+export async function handleRelayInbox(
+  client: RelayClient,
+  input: RelayInboxInput
+): Promise<string> {
+  const messages = await client.getInbox(input);
+
+  if (messages.length === 0) {
+    return 'No messages in inbox.';
+  }
+
+  const formatted = messages.map((m) => {
+    const channel = m.channel ? ` [${m.channel}]` : '';
+    const thread = m.thread ? ` (thread: ${m.thread})` : '';
+    return `[${m.id}] From ${m.from}${channel}${thread}:\n${m.content}`;
+  });
+
+  return `${messages.length} message(s):\n\n${formatted.join('\n\n---\n\n')}`;
+}

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

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient } from '../client.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { exec } from 'node:child_process';
+import { getProjectPaths } from '@agent-relay/config';
+
+const execAsync = promisify(exec);
+
+export const relayLogsSchema = z.object({
+  agent: z.string().describe('Name of the agent to get logs for'),
+  lines: z.number().optional().default(50).describe('Number of lines to retrieve (default: 50)'),
+});
+
+export type RelayLogsInput = z.infer<typeof relayLogsSchema>;
+
+export const relayLogsTool: Tool = {
+  name: 'relay_logs',
+  description: `Read recent output logs from another agent.
+
+Use this to:
+- Monitor worker progress on tasks
+- Debug issues with spawned agents
+- Check what an agent has been outputting
+
+Returns the last N lines of the agent's output log.
+
+Example: Get last 100 lines from Worker1
+  { "agent": "Worker1", "lines": 100 }`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      agent: {
+        type: 'string',
+        description: 'Name of the agent to get logs for',
+      },
+      lines: {
+        type: 'number',
+        description: 'Number of lines to retrieve (default: 50)',
+        default: 50,
+      },
+    },
+    required: ['agent'],
+  },
+};
+
+/**
+ * Get the worker logs directory path.
+ * Uses getProjectPaths from @agent-relay/config to match the bridge package.
+ */
+function getWorkerLogsDir(projectRoot: string): string {
+  const paths = getProjectPaths(projectRoot);
+  return path.join(paths.teamDir, 'worker-logs');
+}
+
+/**
+ * Read recent logs from an agent's output file.
+ */
+export async function handleRelayLogs(
+  client: RelayClient,
+  input: RelayLogsInput
+): Promise<string> {
+  const { agent, lines = 50 } = input;
+
+  // Get project root from client status
+  const status = await client.getStatus();
+  const projectRoot = status.project || process.cwd();
+
+  const logsDir = getWorkerLogsDir(projectRoot);
+  const logFile = path.join(logsDir, `${agent}.log`);
+
+  if (!fs.existsSync(logFile)) {
+    // Try to list available log files
+    let availableAgents: string[] = [];
+    try {
+      if (fs.existsSync(logsDir)) {
+        availableAgents = fs.readdirSync(logsDir)
+          .filter(f => f.endsWith('.log'))
+          .map(f => f.replace('.log', ''));
+      }
+    } catch {
+      // Ignore errors listing directory
+    }
+
+    if (availableAgents.length > 0) {
+      return `No logs found for agent "${agent}".\n\nAvailable agents with logs:\n${availableAgents.map(a => `- ${a}`).join('\n')}`;
+    }
+    return `No logs found for agent "${agent}". The agent may not have been spawned yet or has no output.`;
+  }
+
+  try {
+    const { stdout } = await execAsync(`tail -n ${lines} "${logFile}"`);
+    const logContent = stdout.trim();
+
+    if (!logContent) {
+      return `Logs for ${agent} (last ${lines} lines):\n(empty - no output yet)`;
+    }
+
+    return `Logs for ${agent} (last ${lines} lines):\n${'─'.repeat(50)}\n${logContent}`;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return `Failed to read logs for "${agent}": ${message}`;
+  }
+}

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

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RelayClient, MetricsResponse } from '../client.js';
+
+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 => a.name === input.agent);
+      if (agents.length === 0) {
+        const available = data.agents.map(a => 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 => a.alertLevel === 'critical');
+    const warningAgents = agents.filter(a => 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

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