brownian-code 2026.2.10

package/src/mcp/cache.ts

@@ -0,0 +1,205 @@
+/**
+ * TTL-based response cache for Hive MCP tool calls.
+ *
+ * Different tool categories have different TTLs based on data freshness needs:
+ * - Category/schema discovery: 1 hour (static metadata)
+ * - Historical data (OHLCV, charts): 5 minutes
+ * - Real-time data (prices, balances): 30 seconds
+ * - Security checks: 2 minutes
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+import { logger } from '../utils/logger.js';
+
+const MCP_CACHE_DIR = '.brownian/mcp-cache';
+
+// TTL values in milliseconds
+const TTL = {
+  CATEGORY: 60 * 60 * 1000,      // 1 hour
+  SCHEMA: 60 * 60 * 1000,        // 1 hour
+  HISTORICAL: 5 * 60 * 1000,     // 5 minutes
+  REALTIME: 30 * 1000,           // 30 seconds
+  SECURITY: 2 * 60 * 1000,       // 2 minutes
+  DEFAULT: 2 * 60 * 1000,        // 2 minutes
+} as const;
+
+interface MCPCacheEntry {
+  toolName: string;
+  args: Record<string, unknown>;
+  result: string;
+  cachedAt: number; // epoch ms
+}
+
+/**
+ * Determine TTL for a given tool name based on its category.
+ */
+function getTTLForTool(toolName: string): number {
+  // Category discovery endpoints
+  if (toolName.startsWith('get_') && toolName.endsWith('_endpoints')) {
+    return TTL.CATEGORY;
+  }
+
+  // Schema endpoints
+  if (toolName === 'get_api_endpoint_schema') {
+    return TTL.SCHEMA;
+  }
+
+  // For invoke_api_endpoint, look at the endpoint_name arg (handled by caller)
+  // Default for invocations
+  return TTL.DEFAULT;
+}
+
+/**
+ * Determine TTL for invoke_api_endpoint based on the endpoint being invoked.
+ */
+export function getTTLForEndpoint(endpointName: string): number {
+  const lower = endpointName.toLowerCase();
+
+  // Real-time price data
+  if (lower.includes('price') || lower.includes('balance') || lower.includes('portfolio')) {
+    return TTL.REALTIME;
+  }
+
+  // Security checks
+  if (lower.includes('security') || lower.includes('risk') || lower.includes('honeypot')) {
+    return TTL.SECURITY;
+  }
+
+  // Historical/chart data
+  if (lower.includes('ohlcv') || lower.includes('chart') || lower.includes('historical')) {
+    return TTL.HISTORICAL;
+  }
+
+  return TTL.DEFAULT;
+}
+
+/**
+ * Build a cache key from tool name and args.
+ */
+function buildKey(toolName: string, args: Record<string, unknown>): string {
+  const sorted = JSON.stringify(args, Object.keys(args).sort());
+  const raw = `${toolName}:${sorted}`;
+  return createHash('md5').update(raw).digest('hex').slice(0, 16);
+}
+
+/**
+ * Read a cached MCP response if it exists and hasn't expired.
+ */
+export function readMCPCache(
+  toolName: string,
+  args: Record<string, unknown>,
+): string | null {
+  const key = buildKey(toolName, args);
+  const filepath = join(MCP_CACHE_DIR, `${key}.json`);
+
+  if (!existsSync(filepath)) return null;
+
+  try {
+    const content = readFileSync(filepath, 'utf-8');
+    const entry: MCPCacheEntry = JSON.parse(content);
+
+    // Determine TTL
+    let ttl: number;
+    if (toolName === 'invoke_api_endpoint' && typeof args.endpoint_name === 'string') {
+      ttl = getTTLForEndpoint(args.endpoint_name);
+    } else {
+      ttl = getTTLForTool(toolName);
+    }
+
+    // Check expiry
+    const age = Date.now() - entry.cachedAt;
+    if (age > ttl) {
+      // Expired — remove and miss
+      try { unlinkSync(filepath); } catch { /* best-effort */ }
+      return null;
+    }
+
+    return entry.result;
+  } catch {
+    // Corrupted — remove
+    try { unlinkSync(filepath); } catch { /* best-effort */ }
+    return null;
+  }
+}
+
+/**
+ * Write an MCP response to the cache.
+ */
+export function writeMCPCache(
+  toolName: string,
+  args: Record<string, unknown>,
+  result: string,
+): void {
+  const key = buildKey(toolName, args);
+  const filepath = join(MCP_CACHE_DIR, `${key}.json`);
+
+  const entry: MCPCacheEntry = {
+    toolName,
+    args,
+    result,
+    cachedAt: Date.now(),
+  };
+
+  try {
+    const dir = dirname(filepath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filepath, JSON.stringify(entry));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`MCP cache write error: ${message}`);
+  }
+}
+
+/**
+ * Clear ALL cached MCP entries. Use after fixing bugs or clearing stale errors.
+ */
+export function clearAllMCPCache(): number {
+  if (!existsSync(MCP_CACHE_DIR)) return 0;
+
+  let cleared = 0;
+  try {
+    const files = readdirSync(MCP_CACHE_DIR).filter((f) => f.endsWith('.json'));
+    for (const file of files) {
+      try { unlinkSync(join(MCP_CACHE_DIR, file)); cleared++; } catch { /* best-effort */ }
+    }
+  } catch { /* directory read error */ }
+  return cleared;
+}
+
+/**
+ * Clean up expired cache entries. Called periodically or on startup.
+ */
+export function cleanExpiredMCPCache(): number {
+  if (!existsSync(MCP_CACHE_DIR)) return 0;
+
+  let cleaned = 0;
+  try {
+    const files = readdirSync(MCP_CACHE_DIR).filter((f) => f.endsWith('.json'));
+
+    for (const file of files) {
+      const filepath = join(MCP_CACHE_DIR, file);
+      try {
+        const content = readFileSync(filepath, 'utf-8');
+        const entry: MCPCacheEntry = JSON.parse(content);
+        const ttl = entry.toolName === 'invoke_api_endpoint' && typeof entry.args.endpoint_name === 'string'
+          ? getTTLForEndpoint(entry.args.endpoint_name)
+          : getTTLForTool(entry.toolName);
+
+        if (Date.now() - entry.cachedAt > ttl) {
+          unlinkSync(filepath);
+          cleaned++;
+        }
+      } catch {
+        // Corrupted file — remove
+        try { unlinkSync(filepath); cleaned++; } catch { /* */ }
+      }
+    }
+  } catch {
+    // Directory read error — skip
+  }
+
+  return cleaned;
+}

package/src/mcp/client.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect, beforeEach, mock } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// extractMCPText (tested via callHiveTool internals — we test the export behavior)
+// ---------------------------------------------------------------------------
+
+// We test the module's exported functions. Since the module connects to a real
+// server, we mock the MCP Client class at the module level.
+
+// Create mock client
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mockCallTool = mock(async (): Promise<any> => ({
+  content: [
+    { type: 'text', text: 'Hello' },
+    { type: 'text', text: 'World' },
+  ],
+}));
+const mockClose = mock(async () => {});
+const mockConnect = mock(async () => {});
+const mockListTools = mock(async () => ({
+  tools: [
+    { name: 'tool_a', description: 'Tool A' },
+    { name: 'tool_b', description: 'Tool B' },
+  ],
+}));
+
+// Mock the MCP SDK
+mock.module('@modelcontextprotocol/sdk/client/index.js', () => ({
+  Client: class MockClient {
+    callTool = mockCallTool;
+    close = mockClose;
+    connect = mockConnect;
+    listTools = mockListTools;
+  },
+}));
+
+mock.module('@modelcontextprotocol/sdk/client/streamableHttp.js', () => ({
+  StreamableHTTPClientTransport: class MockTransport {
+    constructor() {}
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('MCP client', () => {
+  beforeEach(() => {
+    mockCallTool.mockClear();
+    mockClose.mockClear();
+    mockConnect.mockClear();
+  });
+
+  test('callHiveTool returns joined text content', async () => {
+    // Need a fresh import each test to reset singleton
+    // but mock.module handles the client constructor
+    const { callHiveTool } = await import('./client.js');
+    const result = await callHiveTool('test_tool', { arg: 'value' });
+    expect(result).toBe('Hello\nWorld');
+  });
+
+  test('callHiveTool passes correct arguments', async () => {
+    const { callHiveTool } = await import('./client.js');
+    await callHiveTool('my_tool', { key: 'val' });
+
+    expect(mockCallTool).toHaveBeenCalledWith({
+      name: 'my_tool',
+      arguments: { key: 'val' },
+    });
+  });
+
+  test('callHiveTool handles empty content array', async () => {
+    mockCallTool.mockResolvedValueOnce({ content: [] });
+    const { callHiveTool } = await import('./client.js');
+    const result = await callHiveTool('empty_tool');
+    expect(result).toBe('');
+  });
+
+  test('callHiveTool handles missing content field', async () => {
+    mockCallTool.mockResolvedValueOnce({ someOther: 'data' });
+    const { callHiveTool } = await import('./client.js');
+    const result = await callHiveTool('no_content_tool');
+    // Should JSON.stringify the result as fallback
+    expect(result).toContain('someOther');
+  });
+
+  test('callHiveTool filters non-text blocks', async () => {
+    mockCallTool.mockResolvedValueOnce({
+      content: [
+        { type: 'text', text: 'visible' },
+        { type: 'image', data: 'binary' },
+        { type: 'text', text: 'also visible' },
+      ],
+    });
+    const { callHiveTool } = await import('./client.js');
+    const result = await callHiveTool('mixed_tool');
+    expect(result).toBe('visible\nalso visible');
+  });
+
+  test('listHiveTools returns tool list', async () => {
+    const { listHiveTools } = await import('./client.js');
+    const tools = await listHiveTools();
+    expect(tools.length).toBe(2);
+    expect(tools[0].name).toBe('tool_a');
+    expect(tools[1].description).toBe('Tool B');
+  });
+
+  test('disconnectHiveMCP calls close and resets', async () => {
+    const { disconnectHiveMCP, callHiveTool } = await import('./client.js');
+    // Ensure client is connected first
+    await callHiveTool('setup');
+    mockClose.mockClear();
+
+    await disconnectHiveMCP();
+    expect(mockClose).toHaveBeenCalled();
+  });
+
+  test('disconnectHiveMCP is a no-op when not connected', async () => {
+    // Import fresh module — but singleton may already exist
+    const { disconnectHiveMCP } = await import('./client.js');
+    // Call disconnect twice — second should be noop
+    await disconnectHiveMCP();
+    await disconnectHiveMCP();
+    // Should not throw
+  });
+});

package/src/mcp/client.ts

@@ -0,0 +1,145 @@
+/**
+ * Hive MCP Client - connects to Hive Intelligence MCP server over HTTP.
+ *
+ * Singleton pattern with lazy connection.
+ * Uses StreamableHTTPClientTransport for HTTP-based MCP communication.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { logger } from '../utils/logger.js';
+
+const HIVE_MCP_URL = process.env.HIVE_MCP_URL ?? 'https://hiveintelligence.xyz/mcp';
+const CONNECT_TIMEOUT_MS = 18_000;
+const CALL_TIMEOUT_MS = 22_000;
+const MAX_RETRIES = 2;
+
+let clientInstance: Client | null = null;
+let connectionPromise: Promise<Client> | null = null;
+
+/**
+ * Create and connect the MCP client to Hive Intelligence.
+ */
+async function createClient(): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(new URL(HIVE_MCP_URL));
+
+  const client = new Client({
+    name: 'brownian-code',
+    version: '1.0.0',
+  });
+
+  const timeoutSignal = AbortSignal.timeout(CONNECT_TIMEOUT_MS);
+
+  try {
+    await client.connect(transport, { signal: timeoutSignal });
+    logger.info(`Connected to Hive MCP at ${HIVE_MCP_URL}`);
+    return client;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Failed to connect to Hive MCP: ${message}`);
+    throw new Error(
+      `Could not connect to crypto data service (hiveintelligence.xyz). ` +
+      `Check your internet connection. Crypto tools will be unavailable.`
+    );
+  }
+}
+
+/**
+ * Get the singleton Hive MCP client.
+ * Lazy-connects on first use.
+ */
+export async function getHiveMCPClient(): Promise<Client> {
+  if (clientInstance) return clientInstance;
+
+  // Prevent parallel connection attempts
+  if (!connectionPromise) {
+    connectionPromise = createClient().then(
+      (client) => {
+        clientInstance = client;
+        connectionPromise = null;
+        return client;
+      },
+      (error) => {
+        connectionPromise = null;
+        throw error;
+      },
+    );
+  }
+
+  return connectionPromise;
+}
+
+/**
+ * Extract text content from MCP tool response.
+ * MCP responses contain a `content` array of typed blocks.
+ */
+function extractMCPText(result: Awaited<ReturnType<Client['callTool']>>): string {
+  if (!result.content || !Array.isArray(result.content)) {
+    return JSON.stringify(result);
+  }
+
+  const textParts = result.content
+    .filter((block: { type: string }) => block.type === 'text')
+    .map((block: { type: string; text?: string }) => block.text ?? '');
+
+  return textParts.join('\n');
+}
+
+/**
+ * Call a Hive MCP tool by name with arguments.
+ * Includes timeout and retry logic.
+ */
+export async function callHiveTool(
+  name: string,
+  args: Record<string, unknown> = {},
+): Promise<string> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const client = await getHiveMCPClient();
+      const timeoutMs = attempt === 0 ? CONNECT_TIMEOUT_MS : CALL_TIMEOUT_MS;
+
+      const result = await Promise.race([
+        client.callTool({ name, arguments: args }),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error(`Hive MCP call timed out after ${timeoutMs}ms`)), timeoutMs),
+        ),
+      ]);
+
+      return extractMCPText(result);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      logger.warn(`Hive MCP call '${name}' attempt ${attempt + 1} failed: ${lastError.message}`);
+
+      if (attempt < MAX_RETRIES) {
+        await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+      }
+    }
+  }
+
+  throw lastError ?? new Error(`Hive MCP call '${name}' failed after ${MAX_RETRIES + 1} attempts`);
+}
+
+/**
+ * List all available Hive MCP tools.
+ * Useful for startup validation and discovery.
+ */
+export async function listHiveTools(): Promise<{ name: string; description?: string }[]> {
+  const client = await getHiveMCPClient();
+  const result = await client.listTools();
+  return result.tools.map((t) => ({ name: t.name, description: t.description }));
+}
+
+/**
+ * Disconnect the MCP client. Call during graceful shutdown.
+ */
+export async function disconnectHiveMCP(): Promise<void> {
+  if (clientInstance) {
+    try {
+      await clientInstance.close();
+    } catch {
+      // Best-effort cleanup
+    }
+    clientInstance = null;
+  }
+}

package/src/mcp/index.ts

@@ -0,0 +1,2 @@
+export { getHiveMCPClient, callHiveTool, listHiveTools, disconnectHiveMCP } from './client.js';
+export { readMCPCache, writeMCPCache, cleanExpiredMCPCache, clearAllMCPCache, getTTLForEndpoint } from './cache.js';

package/src/model/llm.test.ts

@@ -0,0 +1,158 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+
+// Test provider routing and fast model resolution through the providers module
+// (which is never mocked by other test files), plus the LLM module constants.
+import { resolveProvider, getProviderById, PROVIDERS } from '../providers.js';
+
+// ---------------------------------------------------------------------------
+// Provider routing (underlies getChatModel)
+// ---------------------------------------------------------------------------
+
+describe('resolveProvider (model routing)', () => {
+  test('routes claude- prefix to anthropic', () => {
+    expect(resolveProvider('claude-sonnet-4-5').id).toBe('anthropic');
+    expect(resolveProvider('claude-opus-4-6').id).toBe('anthropic');
+    expect(resolveProvider('claude-haiku-4-5').id).toBe('anthropic');
+  });
+
+  test('routes gemini- prefix to google', () => {
+    expect(resolveProvider('gemini-2.0-flash').id).toBe('google');
+    expect(resolveProvider('gemini-1.5-pro').id).toBe('google');
+  });
+
+  test('routes grok- prefix to xai', () => {
+    expect(resolveProvider('grok-beta').id).toBe('xai');
+  });
+
+  test('routes deepseek- prefix to deepseek', () => {
+    expect(resolveProvider('deepseek-chat').id).toBe('deepseek');
+  });
+
+  test('routes ollama: prefix to ollama', () => {
+    expect(resolveProvider('ollama:llama3').id).toBe('ollama');
+  });
+
+  test('routes openrouter: prefix to openrouter', () => {
+    expect(resolveProvider('openrouter:openai/gpt-4o-mini').id).toBe('openrouter');
+  });
+
+  test('routes kimi- prefix to moonshot', () => {
+    expect(resolveProvider('kimi-k2-5').id).toBe('moonshot');
+  });
+
+  test('defaults to anthropic for unknown prefix', () => {
+    // The default provider is anthropic (per providers.ts line 76)
+    expect(resolveProvider('unknown-model').id).toBe('anthropic');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getFastModel (via getProviderById)
+// ---------------------------------------------------------------------------
+
+describe('getFastModel (via providers)', () => {
+  test('anthropic fast model is claude-haiku-4-5', () => {
+    expect(getProviderById('anthropic')?.fastModel).toBe('claude-haiku-4-5');
+  });
+
+  test('openai fast model is gpt-4.1', () => {
+    expect(getProviderById('openai')?.fastModel).toBe('gpt-4.1');
+  });
+
+  test('google fast model is gemini-3-flash-preview', () => {
+    expect(getProviderById('google')?.fastModel).toBe('gemini-3-flash-preview');
+  });
+
+  test('xai fast model is grok-4-1-fast-reasoning', () => {
+    expect(getProviderById('xai')?.fastModel).toBe('grok-4-1-fast-reasoning');
+  });
+
+  test('deepseek fast model is deepseek-chat', () => {
+    expect(getProviderById('deepseek')?.fastModel).toBe('deepseek-chat');
+  });
+
+  test('ollama has no fast model', () => {
+    expect(getProviderById('ollama')?.fastModel).toBeUndefined();
+  });
+
+  test('unknown provider returns undefined', () => {
+    expect(getProviderById('nonexistent')).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Provider registry completeness
+// ---------------------------------------------------------------------------
+
+describe('provider registry', () => {
+  test('has all expected providers', () => {
+    const ids = PROVIDERS.map(p => p.id);
+    expect(ids).toContain('openai');
+    expect(ids).toContain('anthropic');
+    expect(ids).toContain('google');
+    expect(ids).toContain('xai');
+    expect(ids).toContain('moonshot');
+    expect(ids).toContain('deepseek');
+    expect(ids).toContain('openrouter');
+    expect(ids).toContain('ollama');
+  });
+
+  test('each provider has required fields', () => {
+    for (const provider of PROVIDERS) {
+      expect(provider.id).toBeDefined();
+      expect(provider.displayName).toBeDefined();
+      expect(typeof provider.modelPrefix).toBe('string');
+    }
+  });
+
+  test('all providers except ollama have API key env var', () => {
+    for (const provider of PROVIDERS) {
+      if (provider.id !== 'ollama') {
+        expect(provider.apiKeyEnvVar).toBeDefined();
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// API key validation (test the pattern, not getChatModel directly)
+// ---------------------------------------------------------------------------
+
+describe('API key validation patterns', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in originalEnv)) {
+        delete process.env[key];
+      }
+    }
+    Object.assign(process.env, originalEnv);
+  });
+
+  test('provider API key env vars are correctly named', () => {
+    const anthropic = getProviderById('anthropic')!;
+    expect(anthropic.apiKeyEnvVar).toBe('ANTHROPIC_API_KEY');
+
+    const openai = getProviderById('openai')!;
+    expect(openai.apiKeyEnvVar).toBe('OPENAI_API_KEY');
+
+    const google = getProviderById('google')!;
+    expect(google.apiKeyEnvVar).toBe('GOOGLE_API_KEY');
+  });
+
+  test('placeholder keys start with "your-"', () => {
+    // This tests the validation pattern used in llm.ts getApiKey()
+    const placeholders = ['your-api-key', 'your-key-here', 'your-anthropic-key'];
+    for (const key of placeholders) {
+      expect(key.trim().startsWith('your-')).toBe(true);
+    }
+  });
+
+  test('valid keys do not start with "your-"', () => {
+    const validKeys = ['sk-abc123', 'anthropic-key-xyz', 'real-api-key'];
+    for (const key of validKeys) {
+      expect(key.trim().startsWith('your-')).toBe(false);
+    }
+  });
+});