agent-relay 2.0.29 → 2.0.32

package/packages/utils/src/client-helpers.ts

@@ -0,0 +1,221 @@
+/**
+ * Shared client helpers for SDK and MCP implementations
+ *
+ * This module provides common request/response handling and type aliases
+ * to ensure SDK and MCP clients stay in lockstep and avoid inconsistencies.
+ */
+
+import { createConnection, type Socket } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import {
+  type Envelope,
+  type MessageType,
+  type AckPayload,
+  type SpawnResultPayload,
+  type ReleaseResultPayload,
+  encodeFrameLegacy,
+  FrameParser,
+  PROTOCOL_VERSION,
+} from '@agent-relay/protocol';
+
+/**
+ * Common return type aliases to ensure consistency between SDK and MCP
+ */
+export type SpawnResult = {
+  success: boolean;
+  error?: string;
+  pid?: number;
+  name?: string;
+};
+
+export type ReleaseResult = {
+  success: boolean;
+  error?: string;
+  name?: string;
+};
+
+/**
+ * Options for request/response operations
+ */
+export interface RequestOptions {
+  /** Custom timeout in milliseconds */
+  timeoutMs?: number;
+  /** Payload metadata (for sync operations) */
+  payloadMeta?: {
+    sync?: {
+      blocking?: boolean;
+      correlationId?: string;
+      timeoutMs?: number;
+    };
+  };
+  /** Envelope properties (from/to) */
+  envelopeProps?: {
+    from?: string;
+    to?: string;
+  };
+}
+
+/**
+ * Response matching logic for request/response operations
+ */
+export function isMatchingResponse(
+  response: Envelope,
+  requestId: string,
+  correlationId?: string
+): boolean {
+  const responsePayload = response.payload as {
+    replyTo?: string;
+    correlationId?: string;
+  };
+
+  // For ACK messages, match by correlationId
+  const ackPayload = response.type === 'ACK' ? (response.payload as AckPayload) : null;
+
+  return (
+    response.id === requestId ||
+    responsePayload?.replyTo === requestId ||
+    (!!correlationId &&
+      (responsePayload?.correlationId === correlationId ||
+        ackPayload?.correlationId === correlationId))
+  );
+}
+
+/**
+ * Handle response resolution/rejection logic
+ */
+export function handleResponse<T>(
+  response: Envelope,
+  resolve: (value: T) => void,
+  reject: (error: Error) => void
+): void {
+  const responsePayload = response.payload as {
+    error?: string;
+    message?: string;
+    code?: string;
+    success?: boolean;
+  };
+
+  if (response.type === 'ERROR') {
+    reject(
+      new Error(responsePayload?.message || responsePayload?.code || 'Unknown error')
+    );
+  } else if (
+    response.type === 'ACK' ||
+    response.type === 'SPAWN_RESULT' ||
+    response.type === 'RELEASE_RESULT'
+  ) {
+    // ACK, SPAWN_RESULT, and RELEASE_RESULT are valid responses even if they contain error info
+    // For ACK, the error is in response field; for spawn/release, it's in error field
+    resolve(response.payload as T);
+  } else if (responsePayload?.error && !responsePayload?.success) {
+    // For other response types, reject if there's an error and no success flag
+    reject(new Error(responsePayload.error));
+  } else {
+    resolve(response.payload as T);
+  }
+}
+
+/**
+ * Create a request envelope
+ */
+export function createRequestEnvelope(
+  type: MessageType,
+  payload: Record<string, unknown>,
+  requestId: string,
+  options?: RequestOptions
+): Envelope {
+  const envelope: Envelope = {
+    v: PROTOCOL_VERSION,
+    type,
+    id: requestId,
+    ts: Date.now(),
+    payload,
+    from: options?.envelopeProps?.from,
+    to: options?.envelopeProps?.to,
+  };
+
+  if (options?.payloadMeta) {
+    (envelope as unknown as Record<string, unknown>).payload_meta =
+      options.payloadMeta;
+  }
+
+  return envelope;
+}
+
+/**
+ * Convert SpawnResultPayload to SpawnResult
+ */
+export function toSpawnResult(payload: SpawnResultPayload): SpawnResult {
+  return {
+    success: payload.success,
+    error: payload.error,
+    pid: payload.pid,
+    name: payload.name,
+  };
+}
+
+/**
+ * Convert ReleaseResultPayload to ReleaseResult
+ */
+export function toReleaseResult(payload: ReleaseResultPayload): ReleaseResult {
+  return {
+    success: payload.success,
+    error: payload.error,
+    name: payload.name,
+  };
+}
+
+/**
+ * Create a request/response handler using a socket connection
+ * This is the core logic shared between SDK and MCP clients
+ */
+export function createRequestHandler<T>(
+  socketPath: string,
+  envelope: Envelope,
+  options: RequestOptions & { timeout: number }
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const correlationId = options.payloadMeta?.sync?.correlationId;
+    let timedOut = false;
+    const parser = new FrameParser();
+    parser.setLegacyMode(true); // Use legacy 4-byte header format
+
+    const socket: Socket = createConnection(socketPath);
+
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      socket.destroy();
+      reject(new Error(`Request timeout after ${options.timeout}ms`));
+    }, options.timeout);
+
+    socket.on('connect', () => {
+      socket.write(encodeFrameLegacy(envelope));
+    });
+
+    socket.on('data', (data) => {
+      if (timedOut) return;
+
+      const frames = parser.push(data);
+      for (const response of frames) {
+        if (isMatchingResponse(response, envelope.id, correlationId)) {
+          clearTimeout(timeoutId);
+          socket.end();
+          handleResponse(response, resolve, reject);
+          return;
+        }
+      }
+    });
+
+    socket.on('error', (err) => {
+      clearTimeout(timeoutId);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Generate a unique request ID
+ */
+export function generateRequestId(prefix = ''): string {
+  return `${prefix}${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+}

package/packages/utils/src/command-resolver.ts

@@ -0,0 +1,82 @@
+/**
+ * Command Path Resolver
+ *
+ * Resolves full paths for CLI commands to avoid posix_spawnp failures
+ * when PATH isn't properly inherited in spawned processes.
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+
+/**
+ * Resolve the full path of a command using 'which' and resolve any symlinks
+ * Returns the full path if found, or the original command if not found
+ * (letting the spawn fail with a clearer error)
+ */
+export function resolveCommand(command: string): string {
+  // If already an absolute path, just resolve symlinks
+  if (command.startsWith('/')) {
+    return resolveSymlinks(command);
+  }
+
+  try {
+    const output = execSync(`which ${command}`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      // Ensure we have a reasonable PATH
+      env: {
+        ...process.env,
+        PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin',
+      },
+    });
+    const resolvedPath = output.trim();
+    if (resolvedPath) {
+      // Resolve any symlinks to get the actual binary path
+      // This fixes posix_spawnp issues with symlinked binaries
+      return resolveSymlinks(resolvedPath);
+    }
+  } catch (err: any) {
+    // Command not found in PATH - log for debugging
+    console.warn(`[command-resolver] 'which ${command}' failed:`, err.message?.split('\n')[0] || 'unknown error');
+  }
+
+  // Return original command - spawn will fail with a clearer error
+  return command;
+}
+
+/**
+ * Resolve symlinks to get the actual file path
+ * Uses fs.realpathSync which handles all symlink levels
+ */
+function resolveSymlinks(filePath: string): string {
+  try {
+    const resolved = fs.realpathSync(filePath);
+    // Debug log only - symlink resolution is noisy
+    if (resolved !== filePath && process.env.DEBUG_SPAWN === '1') {
+      console.log(`[command-resolver] Resolved symlink: ${filePath} -> ${resolved}`);
+    }
+    return resolved;
+  } catch (err: any) {
+    // If realpath fails, return original (spawn will give clearer error)
+    // Only warn in debug mode - this is common and not actionable
+    if (process.env.DEBUG_SPAWN === '1') {
+      console.warn(`[command-resolver] realpath failed for ${filePath}:`, err.message);
+    }
+    return filePath;
+  }
+}
+
+/**
+ * Check if a command exists in PATH
+ */
+export function commandExists(command: string): boolean {
+  try {
+    execSync(`which ${command}`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/utils/src/error-tracking.ts

@@ -0,0 +1,189 @@
+/**
+ * Error Tracking Utilities
+ *
+ * Provides traceable error IDs that users can report to support.
+ * Support can then search logs for the error ID to find full context.
+ *
+ * Error ID format: ERR-{timestamp}-{random}
+ * Example: ERR-1706012345-a7f3
+ *
+ * Usage:
+ *   const error = createTraceableError('Failed to spawn agent', { agentName, cli });
+ *   console.error(error.logMessage); // Full details for logs
+ *   return { error: error.userMessage }; // Safe message with ID for user
+ */
+
+import { randomBytes } from 'node:crypto';
+
+export interface TraceableError {
+  /** Unique error ID for support lookup (e.g., ERR-1706012345-a7f3) */
+  errorId: string;
+  /** User-facing message with error ID (safe to display) */
+  userMessage: string;
+  /** Full log message with all context (for server logs) */
+  logMessage: string;
+  /** ISO timestamp when error occurred */
+  timestamp: string;
+  /** Original error message */
+  message: string;
+  /** Additional context data */
+  context: Record<string, unknown>;
+}
+
+/**
+ * Generate a unique error ID.
+ * Format: ERR-{unix_timestamp}-{4_random_hex_chars}
+ */
+export function generateErrorId(): string {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const random = randomBytes(2).toString('hex');
+  return `ERR-${timestamp}-${random}`;
+}
+
+/**
+ * Create a traceable error with ID for support lookup.
+ *
+ * @param message - Human-readable error description
+ * @param context - Additional context (agentName, workspaceId, etc.)
+ * @param originalError - Original error object if wrapping
+ * @returns TraceableError with ID, user message, and log message
+ *
+ * @example
+ * ```typescript
+ * const error = createTraceableError('Failed to spawn agent', {
+ *   agentName: 'Worker1',
+ *   cli: 'claude',
+ *   reason: 'timeout'
+ * });
+ *
+ * // Log full details for support
+ * console.error(error.logMessage);
+ * // => [ERR-1706012345-a7f3] Failed to spawn agent | agentName=Worker1 cli=claude reason=timeout
+ *
+ * // Return safe message to user
+ * res.status(500).json({ error: error.userMessage });
+ * // => "Failed to spawn agent (Error ID: ERR-1706012345-a7f3 - share this with support)"
+ * ```
+ */
+export function createTraceableError(
+  message: string,
+  context: Record<string, unknown> = {},
+  originalError?: Error
+): TraceableError {
+  const errorId = generateErrorId();
+  const timestamp = new Date().toISOString();
+
+  // Build context string for logging
+  const contextPairs = Object.entries(context)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${k}=${typeof v === 'object' ? JSON.stringify(v) : v}`)
+    .join(' ');
+
+  // Include original error stack if available
+  const stackInfo = originalError?.stack
+    ? `\n  Original error: ${originalError.message}\n  Stack: ${originalError.stack}`
+    : '';
+
+  const logMessage = `[${errorId}] ${message}${contextPairs ? ` | ${contextPairs}` : ''}${stackInfo}`;
+  const userMessage = `${message} (Error ID: ${errorId} - share this with support)`;
+
+  return {
+    errorId,
+    userMessage,
+    logMessage,
+    timestamp,
+    message,
+    context: {
+      ...context,
+      originalError: originalError?.message,
+    },
+  };
+}
+
+/**
+ * Log a traceable error and return user-safe response.
+ * Convenience wrapper that logs and returns in one call.
+ *
+ * @example
+ * ```typescript
+ * const { userMessage, errorId } = logAndTraceError(
+ *   'Workspace creation failed',
+ *   { workspaceId, userId },
+ *   err
+ * );
+ * res.status(500).json({ error: userMessage, errorId });
+ * ```
+ */
+export function logAndTraceError(
+  message: string,
+  context: Record<string, unknown> = {},
+  originalError?: Error
+): TraceableError {
+  const error = createTraceableError(message, context, originalError);
+  console.error(error.logMessage);
+  return error;
+}
+
+/**
+ * Wrap an async function to automatically trace errors.
+ * Useful for API handlers.
+ *
+ * @example
+ * ```typescript
+ * app.post('/api/spawn', withErrorTracing(async (req, res) => {
+ *   // ... handler code
+ *   // Errors automatically get traced
+ * }, { endpoint: '/api/spawn' }));
+ * ```
+ */
+export function withErrorTracing<T extends (...args: unknown[]) => Promise<unknown>>(
+  fn: T,
+  baseContext: Record<string, unknown> = {}
+): T {
+  return (async (...args: unknown[]) => {
+    try {
+      return await fn(...args);
+    } catch (err) {
+      const error = logAndTraceError(
+        err instanceof Error ? err.message : 'Unknown error',
+        baseContext,
+        err instanceof Error ? err : undefined
+      );
+      throw new TracedError(error);
+    }
+  }) as T;
+}
+
+/**
+ * Error class that includes trace information.
+ * Thrown by withErrorTracing wrapper.
+ */
+export class TracedError extends Error {
+  public readonly errorId: string;
+  public readonly userMessage: string;
+  public readonly context: Record<string, unknown>;
+
+  constructor(traced: TraceableError) {
+    super(traced.message);
+    this.name = 'TracedError';
+    this.errorId = traced.errorId;
+    this.userMessage = traced.userMessage;
+    this.context = traced.context;
+  }
+}
+
+/**
+ * Search hint for support: how to find errors in logs.
+ * Include this in documentation or support portal.
+ */
+export const ERROR_SEARCH_HINT = `
+To find error details in logs, search for the error ID:
+
+  grep "ERR-1706012345-a7f3" /var/log/agent-relay/*.log
+
+Or in cloud logging:
+
+  fly logs -a agent-relay-cloud | grep "ERR-1706012345-a7f3"
+
+The log entry will include full context: user ID, workspace ID, agent name, etc.
+`;

package/packages/utils/src/git-remote.ts

@@ -0,0 +1,143 @@
+/**
+ * Git Remote Detection Utility
+ *
+ * Detects the git remote URL from a working directory and parses it
+ * to extract the repository full name (owner/repo).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+
+/**
+ * Parse a git remote URL to extract owner/repo format.
+ *
+ * Supports:
+ * - git@github.com:owner/repo.git
+ * - https://github.com/owner/repo.git
+ * - https://github.com/owner/repo
+ * - git://github.com/owner/repo.git
+ */
+export function parseGitRemoteUrl(url: string): string | null {
+  if (!url) return null;
+
+  // SSH format: git@github.com:owner/repo.git
+  const sshMatch = url.match(/git@[^:]+:([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (sshMatch) {
+    return sshMatch[1];
+  }
+
+  // HTTPS/Git format: https://github.com/owner/repo.git
+  const httpsMatch = url.match(/(?:https?|git):\/\/[^/]+\/([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (httpsMatch) {
+    return httpsMatch[1];
+  }
+
+  return null;
+}
+
+/**
+ * Get the git remote URL from a directory.
+ *
+ * @param workingDirectory The directory to check for git remote
+ * @param remoteName The remote name to use (default: 'origin')
+ * @returns The remote URL or null if not found
+ */
+export function getGitRemoteUrl(workingDirectory: string, remoteName = 'origin'): string | null {
+  try {
+    // First check if it's a git repository
+    const gitDir = path.join(workingDirectory, '.git');
+    if (!fs.existsSync(gitDir)) {
+      return null;
+    }
+
+    // Try to get the remote URL using git command
+    const result = execSync(`git remote get-url ${remoteName}`, {
+      cwd: workingDirectory,
+      encoding: 'utf-8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    return result.trim() || null;
+  } catch {
+    // Git command failed - try parsing .git/config directly
+    try {
+      const configPath = path.join(workingDirectory, '.git', 'config');
+      if (!fs.existsSync(configPath)) {
+        return null;
+      }
+
+      const config = fs.readFileSync(configPath, 'utf-8');
+
+      // Parse git config to find remote URL
+      const remoteSection = new RegExp(
+        `\\[remote\\s+"${remoteName}"\\][^\\[]*url\\s*=\\s*([^\\n]+)`,
+        'i'
+      );
+      const match = config.match(remoteSection);
+
+      return match?.[1]?.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Get the repository full name (owner/repo) from a working directory.
+ *
+ * @param workingDirectory The directory to check
+ * @returns The repo full name (e.g., "AgentWorkforce/relay") or null
+ */
+export function getRepoFullName(workingDirectory: string): string | null {
+  const remoteUrl = getGitRemoteUrl(workingDirectory);
+  if (!remoteUrl) {
+    return null;
+  }
+
+  return parseGitRemoteUrl(remoteUrl);
+}
+
+/**
+ * Find the git root directory from a given path.
+ * Walks up the directory tree looking for .git folder.
+ *
+ * @param startPath The path to start searching from
+ * @returns The git root directory or null if not in a git repo
+ */
+export function findGitRoot(startPath: string): string | null {
+  let currentPath = path.resolve(startPath);
+  const root = path.parse(currentPath).root;
+
+  while (currentPath !== root) {
+    if (fs.existsSync(path.join(currentPath, '.git'))) {
+      return currentPath;
+    }
+    currentPath = path.dirname(currentPath);
+  }
+
+  return null;
+}
+
+/**
+ * Get repository full name, walking up to find git root if needed.
+ *
+ * @param workingDirectory The directory to start from
+ * @returns The repo full name or null
+ */
+export function getRepoFullNameFromPath(workingDirectory: string): string | null {
+  // First try the exact directory
+  let repoName = getRepoFullName(workingDirectory);
+  if (repoName) {
+    return repoName;
+  }
+
+  // Walk up to find git root
+  const gitRoot = findGitRoot(workingDirectory);
+  if (gitRoot && gitRoot !== workingDirectory) {
+    repoName = getRepoFullName(gitRoot);
+  }
+
+  return repoName;
+}

package/packages/utils/src/index.ts

@@ -0,0 +1,10 @@
+export * from './name-generator.js';
+export * from './logger.js';
+export * from './precompiled-patterns.js';
+export * from './command-resolver.js';
+export * from './git-remote.js';
+export * from './update-checker.js';
+export * from './error-tracking.js';
+export * from './model-mapping.js';
+export * from './relay-pty-path.js';
+export * from './client-helpers.js';