agent-relay 2.0.28 → 2.0.32

package/packages/utils/src/logger.ts

@@ -0,0 +1,107 @@
+/**
+ * Lightweight DIY Logger for Agent Relay
+ *
+ * Minimal logging utility (~50 lines) with:
+ * - JSON output for easy parsing with jq
+ * - Configurable via environment variables
+ * - Debug-only verbose logging
+ * - No external dependencies
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+
+interface LogEntry {
+  ts: string;
+  level: LogLevel;
+  component: string;
+  msg: string;
+  [key: string]: unknown;
+}
+
+// Configuration from environment
+const LOG_FILE = process.env.AGENT_RELAY_LOG_FILE;
+const LOG_LEVEL = (process.env.AGENT_RELAY_LOG_LEVEL ?? 'INFO').toUpperCase() as LogLevel;
+const LOG_JSON = process.env.AGENT_RELAY_LOG_JSON === '1';
+const _DEBUG = process.env.DEBUG === '1' || LOG_LEVEL === 'DEBUG';
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+};
+
+// Ensure log directory exists if file logging enabled
+if (LOG_FILE) {
+  const logDir = path.dirname(LOG_FILE);
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[LOG_LEVEL];
+}
+
+function formatMessage(entry: LogEntry): string {
+  if (LOG_JSON) {
+    return JSON.stringify(entry);
+  }
+  const { ts, level, component, msg, ...extra } = entry;
+  const extraStr = Object.keys(extra).length > 0
+    ? ' ' + Object.entries(extra).map(([k, v]) => `${k}=${v}`).join(' ')
+    : '';
+  return `${ts} [${level}] [${component}] ${msg}${extraStr}`;
+}
+
+function log(level: LogLevel, component: string, msg: string, extra?: Record<string, unknown>): void {
+  if (!shouldLog(level)) return;
+
+  const entry: LogEntry = {
+    ts: new Date().toISOString(),
+    level,
+    component,
+    msg,
+    ...extra,
+  };
+
+  const formatted = formatMessage(entry);
+
+  // Write to file if configured
+  if (LOG_FILE) {
+    fs.appendFileSync(LOG_FILE, formatted + '\n');
+    // When logging to file, skip console output to avoid polluting TUI terminals
+    return;
+  }
+
+  // Only write to console if no log file is configured (fallback mode)
+  if (level === 'ERROR' || level === 'WARN') {
+    console.error(formatted);
+  } else {
+    console.log(formatted);
+  }
+}
+
+/**
+ * Create a logger for a specific component.
+ * @param component - Component name (e.g., 'daemon', 'router', 'connection')
+ */
+export function createLogger(component: string) {
+  return {
+    debug: (msg: string, extra?: Record<string, unknown>) => log('DEBUG', component, msg, extra),
+    info: (msg: string, extra?: Record<string, unknown>) => log('INFO', component, msg, extra),
+    warn: (msg: string, extra?: Record<string, unknown>) => log('WARN', component, msg, extra),
+    error: (msg: string, extra?: Record<string, unknown>) => log('ERROR', component, msg, extra),
+  };
+}
+
+// Pre-created loggers for common components
+export const daemonLog = createLogger('daemon');
+export const routerLog = createLogger('router');
+export const connectionLog = createLogger('connection');
+
+// Default export for simple usage
+export default createLogger;

package/packages/utils/src/model-mapping.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import { mapModelToCli, getBaseCli } from './model-mapping.js';
+
+describe('mapModelToCli', () => {
+  describe('Claude models', () => {
+    it('maps claude-sonnet-4 to claude:sonnet', () => {
+      expect(mapModelToCli('claude-sonnet-4')).toBe('claude:sonnet');
+    });
+
+    it('maps claude-opus-4 to claude:opus', () => {
+      expect(mapModelToCli('claude-opus-4')).toBe('claude:opus');
+    });
+
+    it('maps claude-opus-4.5 to claude:opus', () => {
+      expect(mapModelToCli('claude-opus-4.5')).toBe('claude:opus');
+    });
+
+    it('maps sonnet to claude:sonnet', () => {
+      expect(mapModelToCli('sonnet')).toBe('claude:sonnet');
+    });
+
+    it('maps opus to claude:opus', () => {
+      expect(mapModelToCli('opus')).toBe('claude:opus');
+    });
+
+    it('maps haiku to claude:haiku', () => {
+      expect(mapModelToCli('haiku')).toBe('claude:haiku');
+    });
+  });
+
+  describe('case insensitivity', () => {
+    it('handles uppercase input', () => {
+      expect(mapModelToCli('OPUS')).toBe('claude:opus');
+    });
+
+    it('handles mixed case input', () => {
+      expect(mapModelToCli('Sonnet')).toBe('claude:sonnet');
+    });
+
+    it('handles CLAUDE-OPUS-4 uppercase', () => {
+      expect(mapModelToCli('CLAUDE-OPUS-4')).toBe('claude:opus');
+    });
+  });
+
+  describe('whitespace handling', () => {
+    it('trims leading whitespace', () => {
+      expect(mapModelToCli('  opus')).toBe('claude:opus');
+    });
+
+    it('trims trailing whitespace', () => {
+      expect(mapModelToCli('opus  ')).toBe('claude:opus');
+    });
+
+    it('trims both leading and trailing whitespace', () => {
+      expect(mapModelToCli('  sonnet  ')).toBe('claude:sonnet');
+    });
+  });
+
+  describe('Codex/OpenAI models', () => {
+    it('maps codex to codex', () => {
+      expect(mapModelToCli('codex')).toBe('codex');
+    });
+
+    it('maps gpt-4o to codex', () => {
+      expect(mapModelToCli('gpt-4o')).toBe('codex');
+    });
+  });
+
+  describe('Gemini models', () => {
+    it('maps gemini to gemini', () => {
+      expect(mapModelToCli('gemini')).toBe('gemini');
+    });
+
+    it('maps gemini-2.0-flash to gemini', () => {
+      expect(mapModelToCli('gemini-2.0-flash')).toBe('gemini');
+    });
+  });
+
+  describe('default behavior', () => {
+    it('returns claude:sonnet for undefined', () => {
+      expect(mapModelToCli(undefined)).toBe('claude:sonnet');
+    });
+
+    it('returns claude:sonnet for empty string', () => {
+      expect(mapModelToCli('')).toBe('claude:sonnet');
+    });
+
+    it('returns claude:sonnet for unknown model', () => {
+      expect(mapModelToCli('unknown-model-xyz')).toBe('claude:sonnet');
+    });
+
+    it('returns claude:sonnet for whitespace-only string', () => {
+      expect(mapModelToCli('   ')).toBe('claude:sonnet');
+    });
+  });
+});
+
+describe('getBaseCli', () => {
+  it('extracts base CLI from variant with colon', () => {
+    expect(getBaseCli('claude:opus')).toBe('claude');
+  });
+
+  it('extracts base CLI from sonnet variant', () => {
+    expect(getBaseCli('claude:sonnet')).toBe('claude');
+  });
+
+  it('extracts base CLI from haiku variant', () => {
+    expect(getBaseCli('claude:haiku')).toBe('claude');
+  });
+
+  it('returns CLI as-is when no colon present', () => {
+    expect(getBaseCli('codex')).toBe('codex');
+  });
+
+  it('returns CLI as-is for gemini', () => {
+    expect(getBaseCli('gemini')).toBe('gemini');
+  });
+
+  it('handles multiple colons by splitting on first', () => {
+    expect(getBaseCli('claude:opus:extra')).toBe('claude');
+  });
+});

package/packages/utils/src/model-mapping.ts

@@ -0,0 +1,58 @@
+/**
+ * Model Mapping
+ *
+ * Maps agent profile model identifiers to CLI variants.
+ * Used for cost tracking and model selection when spawning agents.
+ */
+
+/**
+ * Mapping from model identifiers to CLI command variants.
+ * Keys are normalized model names, values are CLI command variants.
+ */
+const MODEL_TO_CLI: Record<string, string> = {
+  // Claude models
+  'claude-sonnet-4': 'claude:sonnet',
+  'claude-opus-4': 'claude:opus',
+  'claude-opus-4.5': 'claude:opus',
+  'sonnet': 'claude:sonnet',
+  'opus': 'claude:opus',
+  'haiku': 'claude:haiku',
+  // Codex (OpenAI)
+  'codex': 'codex',
+  'gpt-4o': 'codex',
+  // Gemini (Google)
+  'gemini': 'gemini',
+  'gemini-2.0-flash': 'gemini',
+};
+
+/**
+ * Convert a model identifier into the CLI command variant.
+ * Defaults to 'claude:sonnet' when no match is found.
+ *
+ * @param model - Model identifier from agent profile (e.g., 'claude-opus-4', 'sonnet')
+ * @returns CLI command variant (e.g., 'claude:opus', 'claude:sonnet')
+ *
+ * @example
+ * mapModelToCli('claude-opus-4')     // Returns 'claude:opus'
+ * mapModelToCli('sonnet')            // Returns 'claude:sonnet'
+ * mapModelToCli('gpt-4o')            // Returns 'codex'
+ * mapModelToCli(undefined)           // Returns 'claude:sonnet'
+ */
+export function mapModelToCli(model?: string): string {
+  if (!model) {
+    return 'claude:sonnet';
+  }
+
+  const normalized = model.trim().toLowerCase();
+  return MODEL_TO_CLI[normalized] ?? 'claude:sonnet';
+}
+
+/**
+ * Extract the base CLI name from a model-mapped CLI variant.
+ *
+ * @param cliVariant - CLI variant (e.g., 'claude:opus', 'claude', 'codex')
+ * @returns Base CLI name (e.g., 'claude', 'codex')
+ */
+export function getBaseCli(cliVariant: string): string {
+  return cliVariant.split(':')[0];
+}

package/packages/utils/src/name-generator.test.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect } from 'vitest';
+import { generateAgentName, generateUniqueAgentName, isValidAgentName } from './name-generator.js';
+
+describe('generateAgentName', () => {
+  it('returns a non-empty string', () => {
+    const name = generateAgentName();
+    expect(name).toBeTruthy();
+    expect(typeof name).toBe('string');
+    expect(name.length).toBeGreaterThan(0);
+  });
+
+  it('returns AdjectiveNoun format with capital letters and no spaces', () => {
+    const name = generateAgentName();
+    // Should start with an uppercase letter
+    expect(name[0]).toMatch(/[A-Z]/);
+    // Should not contain spaces
+    expect(name).not.toContain(' ');
+    // Should contain at least one more uppercase letter (the noun's first letter)
+    expect(name.slice(1)).toMatch(/[A-Z]/);
+  });
+
+  it('generates different names on multiple calls', () => {
+    const names = new Set<string>();
+    const iterations = 50;
+
+    for (let i = 0; i < iterations; i++) {
+      names.add(generateAgentName());
+    }
+
+    // With 64 adjectives and 64 nouns (4096 combinations),
+    // we should get at least some variety in 50 calls
+    expect(names.size).toBeGreaterThan(1);
+  });
+
+  it('generates names that match the validation pattern', () => {
+    const iterations = 20;
+
+    for (let i = 0; i < iterations; i++) {
+      const name = generateAgentName();
+      expect(isValidAgentName(name)).toBe(true);
+    }
+  });
+
+  it('generates names within valid length constraints', () => {
+    const iterations = 20;
+
+    for (let i = 0; i < iterations; i++) {
+      const name = generateAgentName();
+      expect(name.length).toBeGreaterThanOrEqual(2);
+      expect(name.length).toBeLessThanOrEqual(32);
+    }
+  });
+});
+
+describe('generateUniqueAgentName', () => {
+  it('returns a name not in the existing set', () => {
+    const existingNames = new Set(['BlueFox', 'RedWolf', 'GreenEagle']);
+    const name = generateUniqueAgentName(existingNames);
+
+    expect(existingNames.has(name)).toBe(false);
+    expect(typeof name).toBe('string');
+    expect(name.length).toBeGreaterThan(0);
+  });
+
+  it('handles an empty existing set', () => {
+    const existingNames = new Set<string>();
+    const name = generateUniqueAgentName(existingNames);
+
+    expect(typeof name).toBe('string');
+    expect(name.length).toBeGreaterThan(0);
+    expect(isValidAgentName(name)).toBe(true);
+  });
+
+  it('falls back to suffix after maxAttempts', () => {
+    // Create a set with all possible combinations minus one
+    // We'll use a small maxAttempts to force the fallback
+    const existingNames = new Set<string>();
+
+    // Add a bunch of names to increase collision likelihood
+    for (let i = 0; i < 100; i++) {
+      existingNames.add(generateAgentName());
+    }
+
+    // Force fallback by setting maxAttempts to 0
+    const name = generateUniqueAgentName(existingNames, 0);
+
+    // Should have a numeric suffix
+    expect(name).toMatch(/\d+$/);
+    expect(typeof name).toBe('string');
+    expect(name.length).toBeGreaterThan(0);
+  });
+
+  it('works with a large existing set', () => {
+    const existingNames = new Set<string>();
+
+    // Add 500 names to the set
+    for (let i = 0; i < 500; i++) {
+      existingNames.add(`Agent${i}`);
+    }
+
+    const name = generateUniqueAgentName(existingNames);
+
+    expect(existingNames.has(name)).toBe(false);
+    expect(typeof name).toBe('string');
+    expect(name.length).toBeGreaterThan(0);
+  });
+
+  it('generates multiple unique names successfully', () => {
+    const existingNames = new Set<string>();
+
+    for (let i = 0; i < 10; i++) {
+      const name = generateUniqueAgentName(existingNames);
+      expect(existingNames.has(name)).toBe(false);
+      existingNames.add(name);
+    }
+
+    // Should have 10 unique names
+    expect(existingNames.size).toBe(10);
+  });
+
+  it('respects custom maxAttempts parameter', () => {
+    const existingNames = new Set<string>();
+
+    // Add many names to make collisions likely
+    for (let i = 0; i < 200; i++) {
+      existingNames.add(generateAgentName());
+    }
+
+    // Should still work with custom maxAttempts
+    const name = generateUniqueAgentName(existingNames, 50);
+
+    expect(typeof name).toBe('string');
+    expect(name.length).toBeGreaterThan(0);
+  });
+});
+
+describe('isValidAgentName', () => {
+  describe('valid names', () => {
+    it('accepts "BlueFox"', () => {
+      expect(isValidAgentName('BlueFox')).toBe(true);
+    });
+
+    it('accepts "A1"', () => {
+      expect(isValidAgentName('A1')).toBe(true);
+    });
+
+    it('accepts "Agent_1"', () => {
+      expect(isValidAgentName('Agent_1')).toBe(true);
+    });
+
+    it('accepts "test-agent"', () => {
+      expect(isValidAgentName('test-agent')).toBe(true);
+    });
+
+    it('accepts names with mixed case', () => {
+      expect(isValidAgentName('CamelCase')).toBe(true);
+      expect(isValidAgentName('lowercase')).toBe(true);
+      expect(isValidAgentName('UPPERCASE')).toBe(true);
+    });
+
+    it('accepts names with underscores', () => {
+      expect(isValidAgentName('my_agent')).toBe(true);
+      expect(isValidAgentName('agent_with_underscores')).toBe(true);
+    });
+
+    it('accepts names with hyphens', () => {
+      expect(isValidAgentName('my-agent')).toBe(true);
+      expect(isValidAgentName('agent-with-hyphens')).toBe(true);
+    });
+
+    it('accepts names at exactly 32 characters', () => {
+      const name = 'a' + '1'.repeat(31); // 32 chars total
+      expect(name.length).toBe(32);
+      expect(isValidAgentName(name)).toBe(true);
+    });
+  });
+
+  describe('invalid names', () => {
+    it('rejects empty string', () => {
+      expect(isValidAgentName('')).toBe(false);
+    });
+
+    it('rejects single character', () => {
+      expect(isValidAgentName('a')).toBe(false);
+    });
+
+    it('rejects name starting with number', () => {
+      expect(isValidAgentName('123')).toBe(false);
+      expect(isValidAgentName('1agent')).toBe(false);
+    });
+
+    it('rejects names over 32 characters', () => {
+      const name = 'a' + '1'.repeat(32); // 33 chars total
+      expect(name.length).toBe(33);
+      expect(isValidAgentName(name)).toBe(false);
+    });
+
+    it('rejects names with spaces', () => {
+      expect(isValidAgentName('Blue Fox')).toBe(false);
+      expect(isValidAgentName('my agent')).toBe(false);
+    });
+
+    it('rejects names with special characters', () => {
+      expect(isValidAgentName('agent!')).toBe(false);
+      expect(isValidAgentName('agent@home')).toBe(false);
+      expect(isValidAgentName('agent#1')).toBe(false);
+      expect(isValidAgentName('agent$')).toBe(false);
+      expect(isValidAgentName('agent%')).toBe(false);
+      expect(isValidAgentName('agent^')).toBe(false);
+      expect(isValidAgentName('agent&')).toBe(false);
+      expect(isValidAgentName('agent*')).toBe(false);
+      expect(isValidAgentName('agent(')).toBe(false);
+      expect(isValidAgentName('agent)')).toBe(false);
+    });
+
+    it('rejects names starting with underscore', () => {
+      expect(isValidAgentName('_agent')).toBe(false);
+    });
+
+    it('rejects names starting with hyphen', () => {
+      expect(isValidAgentName('-agent')).toBe(false);
+    });
+
+    it('rejects names with dots', () => {
+      expect(isValidAgentName('agent.1')).toBe(false);
+      expect(isValidAgentName('my.agent')).toBe(false);
+    });
+
+    it('rejects names with slashes', () => {
+      expect(isValidAgentName('agent/1')).toBe(false);
+      expect(isValidAgentName('agent\\1')).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles names at boundary lengths correctly', () => {
+      // Minimum valid length (2 chars)
+      expect(isValidAgentName('ab')).toBe(true);
+
+      // Maximum valid length (32 chars)
+      const maxValid = 'a' + 'b'.repeat(31);
+      expect(maxValid.length).toBe(32);
+      expect(isValidAgentName(maxValid)).toBe(true);
+
+      // One character too long (33 chars)
+      const tooLong = maxValid + 'c';
+      expect(tooLong.length).toBe(33);
+      expect(isValidAgentName(tooLong)).toBe(false);
+    });
+
+    it('validates all generated names', () => {
+      // Run a batch test to ensure generated names always pass validation
+      for (let i = 0; i < 50; i++) {
+        const name = generateAgentName();
+        expect(isValidAgentName(name)).toBe(true);
+      }
+    });
+  });
+});

package/packages/utils/src/name-generator.ts

@@ -0,0 +1,56 @@
+/**
+ * Auto-generate memorable agent names using adjective+noun combinations.
+ * Inspired by mcp_agent_mail's approach.
+ */
+
+const ADJECTIVES = [
+  'Blue', 'Green', 'Red', 'Purple', 'Golden', 'Silver', 'Crystal', 'Amber',
+  'Coral', 'Jade', 'Ruby', 'Sapphire', 'Emerald', 'Onyx', 'Pearl', 'Copper',
+  'Bronze', 'Iron', 'Steel', 'Velvet', 'Silk', 'Cotton', 'Linen', 'Marble',
+  'Granite', 'Cobalt', 'Crimson', 'Azure', 'Indigo', 'Scarlet', 'Violet',
+  'Olive', 'Teal', 'Cyan', 'Magenta', 'Ochre', 'Rustic', 'Misty', 'Stormy',
+  'Sunny', 'Frosty', 'Dusty', 'Mossy', 'Rocky', 'Sandy', 'Snowy', 'Windy',
+  'Swift', 'Calm', 'Bold', 'Brave', 'Clever', 'Eager', 'Gentle', 'Happy',
+  'Jolly', 'Kind', 'Lively', 'Merry', 'Noble', 'Proud', 'Quick', 'Quiet',
+];
+
+const NOUNS = [
+  'Mountain', 'River', 'Forest', 'Ocean', 'Valley', 'Canyon', 'Desert', 'Island',
+  'Lake', 'Meadow', 'Prairie', 'Glacier', 'Volcano', 'Waterfall', 'Creek', 'Pond',
+  'Hill', 'Peak', 'Ridge', 'Cliff', 'Cave', 'Reef', 'Marsh', 'Grove',
+  'Fox', 'Wolf', 'Bear', 'Eagle', 'Hawk', 'Owl', 'Deer', 'Elk',
+  'Falcon', 'Raven', 'Swan', 'Crane', 'Heron', 'Otter', 'Beaver', 'Badger',
+  'Castle', 'Tower', 'Bridge', 'Harbor', 'Haven', 'Shelter', 'Beacon', 'Anchor',
+  'Stone', 'Pebble', 'Boulder', 'Crystal', 'Gem', 'Prism', 'Spark', 'Ember',
+  'Star', 'Moon', 'Sun', 'Comet', 'Cloud', 'Storm', 'Thunder', 'Lightning',
+];
+
+/**
+ * Generate a random agent name (AdjectiveNoun format).
+ */
+export function generateAgentName(): string {
+  const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+  const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+  return `${adjective}${noun}`;
+}
+
+/**
+ * Generate a unique agent name, checking against existing names.
+ */
+export function generateUniqueAgentName(existingNames: Set<string>, maxAttempts = 100): string {
+  for (let i = 0; i < maxAttempts; i++) {
+    const name = generateAgentName();
+    if (!existingNames.has(name)) {
+      return name;
+    }
+  }
+  // Fallback: append random suffix
+  return `${generateAgentName()}${Math.floor(Math.random() * 1000)}`;
+}
+
+/**
+ * Validate an agent name (must be alphanumeric, 2-32 chars).
+ */
+export function isValidAgentName(name: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9_-]{1,31}$/.test(name);
+}