brownian-code 2026.2.10

package/src/tools/types.ts

@@ -0,0 +1,53 @@
+export interface ToolResult {
+  data: unknown;
+  sourceUrls?: string[];
+}
+
+export function formatToolResult(data: unknown, sourceUrls?: string[]): string {
+  const result: ToolResult = { data };
+  if (sourceUrls?.length) {
+    result.sourceUrls = sourceUrls;
+  }
+  return JSON.stringify(result);
+}
+
+/**
+ * Parse search results from a search provider response.
+ * Handles both string and object responses, extracting URLs from results.
+ * Supports multiple response shapes from different providers.
+ */
+export function parseSearchResults(result: unknown): { parsed: unknown; urls: string[] } {
+  // Safely parse JSON strings
+  let parsed: unknown;
+  if (typeof result === 'string') {
+    try {
+      parsed = JSON.parse(result);
+    } catch {
+      // If parsing fails, treat the string as the result itself
+      parsed = result;
+    }
+  } else {
+    parsed = result;
+  }
+
+  // Extract URLs from multiple possible response shapes
+  let urls: string[] = [];
+
+  // Shape 1: { results: [{ url: string }] } (Exa format)
+  if (parsed && typeof parsed === 'object' && 'results' in parsed) {
+    const results = (parsed as { results?: unknown[] }).results;
+    if (Array.isArray(results)) {
+      urls = results
+        .map((r) => (r && typeof r === 'object' && 'url' in r ? (r as { url?: string }).url : null))
+        .filter((url): url is string => Boolean(url));
+    }
+  }
+  // Shape 2: [{ url: string }] (direct array, Tavily format)
+  else if (Array.isArray(parsed)) {
+    urls = parsed
+      .map((r) => (r && typeof r === 'object' && 'url' in r ? (r as { url?: string }).url : null))
+      .filter((url): url is string => Boolean(url));
+  }
+
+  return { parsed, urls };
+}

package/src/utils/ai-message.ts

@@ -0,0 +1,26 @@
+import { AIMessage } from '@langchain/core/messages';
+
+/**
+ * Extract text content from an AIMessage
+ */
+export function extractTextContent(message: AIMessage): string {
+  if (typeof message.content === 'string') {
+    return message.content;
+  }
+
+  if (Array.isArray(message.content)) {
+    return message.content
+      .filter(block => typeof block === 'object' && 'type' in block && block.type === 'text')
+      .map(block => (block as { text: string }).text)
+      .join('\n');
+  }
+
+  return '';
+}
+
+/**
+ * Check if an AIMessage has tool calls
+ */
+export function hasToolCalls(message: AIMessage): boolean {
+  return Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+}

package/src/utils/config.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+const SETTINGS_FILE = '.brownian/settings.json';
+
+interface Config {
+  provider?: string;
+  modelId?: string;  // Selected model ID (e.g., "gpt-5.2", "ollama:llama3.1")
+  model?: string;    // Legacy key, kept for migration
+  [key: string]: unknown;
+}
+
+export function loadConfig(): Config {
+  if (!existsSync(SETTINGS_FILE)) {
+    return {};
+  }
+
+  try {
+    const content = readFileSync(SETTINGS_FILE, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config: Config): boolean {
+  try {
+    const dir = dirname(SETTINGS_FILE);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(SETTINGS_FILE, JSON.stringify(config, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getSetting<T>(key: string, defaultValue: T): T {
+  const config = loadConfig();
+  return (config[key] as T) ?? defaultValue;
+}
+
+export function setSetting(key: string, value: unknown): boolean {
+  const config = loadConfig();
+  config[key] = value;
+  
+  // If setting provider, remove legacy model key
+  if (key === 'provider' && config.model) {
+    delete config.model;
+  }
+  
+  return saveConfig(config);
+}

package/src/utils/cost-calculator.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect } from 'bun:test';
+import { estimateCost, formatCost } from './cost-calculator.js';
+
+// ---------------------------------------------------------------------------
+// estimateCost
+// ---------------------------------------------------------------------------
+
+describe('estimateCost', () => {
+  test('calculates cost for a known model (claude-sonnet-4-5)', () => {
+    // claude-sonnet-4-5: input=$3/1M, output=$15/1M
+    const result = estimateCost('claude-sonnet-4-5', 1_000_000, 1_000_000);
+    expect(result.inputCost).toBe(3);
+    expect(result.outputCost).toBe(15);
+    expect(result.totalCost).toBe(18);
+  });
+
+  test('calculates cost for small token counts', () => {
+    // 1000 input tokens, 500 output tokens at claude-sonnet-4-5 rates
+    const result = estimateCost('claude-sonnet-4-5', 1000, 500);
+    expect(result.inputCost).toBeCloseTo(0.003, 6);
+    expect(result.outputCost).toBeCloseTo(0.0075, 6);
+    expect(result.totalCost).toBeCloseTo(0.0105, 6);
+  });
+
+  test('calculates cost for gpt-5.2', () => {
+    // gpt-5.2: input=$5/1M, output=$15/1M
+    const result = estimateCost('gpt-5.2', 100_000, 50_000);
+    expect(result.inputCost).toBeCloseTo(0.5, 6);
+    expect(result.outputCost).toBeCloseTo(0.75, 6);
+    expect(result.totalCost).toBeCloseTo(1.25, 6);
+  });
+
+  test('calculates cost for claude-opus-4-6', () => {
+    // claude-opus-4-6: input=$15/1M, output=$75/1M
+    const result = estimateCost('claude-opus-4-6', 10_000, 5_000);
+    expect(result.inputCost).toBeCloseTo(0.15, 6);
+    expect(result.outputCost).toBeCloseTo(0.375, 6);
+  });
+
+  test('calculates cost for claude-haiku-4-5', () => {
+    // claude-haiku-4-5: input=$0.8/1M, output=$4/1M
+    const result = estimateCost('claude-haiku-4-5', 1_000_000, 1_000_000);
+    expect(result.inputCost).toBe(0.8);
+    expect(result.outputCost).toBe(4);
+  });
+
+  test('uses default pricing for unknown model', () => {
+    // Default: input=$3/1M, output=$15/1M
+    const result = estimateCost('unknown-model-xyz', 1_000_000, 1_000_000);
+    expect(result.inputCost).toBe(3);
+    expect(result.outputCost).toBe(15);
+    expect(result.totalCost).toBe(18);
+  });
+
+  test('strips date suffix to match model pricing', () => {
+    // 'claude-sonnet-4-5-20250929' should strip '-20250929' → 'claude-sonnet-4-5'
+    const result = estimateCost('claude-sonnet-4-5-20250929', 1_000_000, 0);
+    expect(result.inputCost).toBe(3);
+  });
+
+  test('returns zero cost for zero tokens', () => {
+    const result = estimateCost('claude-sonnet-4-5', 0, 0);
+    expect(result.inputCost).toBe(0);
+    expect(result.outputCost).toBe(0);
+    expect(result.totalCost).toBe(0);
+  });
+
+  test('handles empty model string', () => {
+    const result = estimateCost('', 1000, 1000);
+    // Should use default pricing without crashing
+    expect(result.totalCost).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatCost
+// ---------------------------------------------------------------------------
+
+describe('formatCost', () => {
+  test('formats very small costs with 4 decimal places', () => {
+    expect(formatCost(0.0042)).toBe('$0.0042');
+    expect(formatCost(0.001)).toBe('$0.0010');
+    expect(formatCost(0.0001)).toBe('$0.0001');
+  });
+
+  test('formats medium costs with 3 decimal places', () => {
+    expect(formatCost(0.05)).toBe('$0.050');
+    expect(formatCost(0.123)).toBe('$0.123');
+    expect(formatCost(0.999)).toBe('$0.999');
+  });
+
+  test('formats large costs with 2 decimal places', () => {
+    expect(formatCost(1.5)).toBe('$1.50');
+    expect(formatCost(10.123)).toBe('$10.12');
+    expect(formatCost(100)).toBe('$100.00');
+  });
+
+  test('formats zero cost', () => {
+    expect(formatCost(0)).toBe('$0.0000');
+  });
+});

package/src/utils/cost-calculator.ts

@@ -0,0 +1,74 @@
+/**
+ * Simple per-model pricing table for cost estimation.
+ * Prices are per 1M tokens in USD.
+ */
+const PRICING: Record<string, { input: number; output: number }> = {
+  // Anthropic
+  'claude-sonnet-4-5': { input: 3, output: 15 },
+  'claude-sonnet-4-5-20250929': { input: 3, output: 15 },
+  'claude-opus-4-6': { input: 15, output: 75 },
+  'claude-haiku-4-5': { input: 0.8, output: 4 },
+  'claude-haiku-4-5-20251001': { input: 0.8, output: 4 },
+  // OpenAI
+  'gpt-5.2': { input: 5, output: 15 },
+  'gpt-4.1': { input: 2, output: 8 },
+  'gpt-4.1-mini': { input: 0.4, output: 1.6 },
+  'gpt-4.1-nano': { input: 0.1, output: 0.4 },
+  'o3': { input: 10, output: 40 },
+  'o4-mini': { input: 1.1, output: 4.4 },
+  // Google
+  'gemini-3-flash-preview': { input: 0.15, output: 0.6 },
+  'gemini-2.5-pro-preview': { input: 1.25, output: 10 },
+  // xAI
+  'grok-4-1-fast-reasoning': { input: 3, output: 15 },
+  // DeepSeek
+  'deepseek-chat': { input: 0.27, output: 1.1 },
+  'deepseek-reasoner': { input: 0.55, output: 2.19 },
+  // Moonshot
+  'kimi-k2-5': { input: 0.6, output: 2.4 },
+};
+
+/** Default pricing for unknown models */
+const DEFAULT_PRICING = { input: 3, output: 15 };
+
+export interface CostEstimate {
+  inputCost: number;
+  outputCost: number;
+  totalCost: number;
+}
+
+/**
+ * Estimate cost for a given model and token usage.
+ */
+export function estimateCost(
+  model: string,
+  inputTokens: number,
+  outputTokens: number
+): CostEstimate {
+  // Try exact match, then try stripping version suffixes
+  const pricing = PRICING[model] ??
+    PRICING[model.replace(/-\d{8}$/, '')] ??
+    DEFAULT_PRICING;
+
+  const inputCost = (inputTokens / 1_000_000) * pricing.input;
+  const outputCost = (outputTokens / 1_000_000) * pricing.output;
+
+  return {
+    inputCost,
+    outputCost,
+    totalCost: inputCost + outputCost,
+  };
+}
+
+/**
+ * Format a cost value as a string (e.g., "$0.0042").
+ */
+export function formatCost(cost: number): string {
+  if (cost < 0.01) {
+    return `$${cost.toFixed(4)}`;
+  }
+  if (cost < 1) {
+    return `$${cost.toFixed(3)}`;
+  }
+  return `$${cost.toFixed(2)}`;
+}

package/src/utils/env.ts

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { config } from 'dotenv';
+import { getProviderById } from '@/providers';
+
+// Load .env on module import
+config({ quiet: true });
+
+export function getApiKeyNameForProvider(providerId: string): string | undefined {
+  return getProviderById(providerId)?.apiKeyEnvVar;
+}
+
+export function getProviderDisplayName(providerId: string): string {
+  return getProviderById(providerId)?.displayName ?? providerId;
+}
+
+export function checkApiKeyExistsForProvider(providerId: string): boolean {
+  const apiKeyName = getApiKeyNameForProvider(providerId);
+  if (!apiKeyName) return true;
+  return checkApiKeyExists(apiKeyName);
+}
+
+export function checkApiKeyExists(apiKeyName: string): boolean {
+  const value = process.env[apiKeyName];
+  if (value && value.trim() && !value.trim().startsWith('your-')) {
+    return true;
+  }
+
+  // Also check .env file directly
+  if (existsSync('.env')) {
+    const envContent = readFileSync('.env', 'utf-8');
+    const lines = envContent.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#') && trimmed.includes('=')) {
+        const [key, ...valueParts] = trimmed.split('=');
+        if (key.trim() === apiKeyName) {
+          const val = valueParts.join('=').trim();
+          if (val && !val.startsWith('your-')) {
+            return true;
+          }
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+export function saveApiKeyToEnv(apiKeyName: string, apiKeyValue: string): boolean {
+  try {
+    let lines: string[] = [];
+    let keyUpdated = false;
+
+    if (existsSync('.env')) {
+      const existingContent = readFileSync('.env', 'utf-8');
+      const existingLines = existingContent.split('\n');
+
+      for (const line of existingLines) {
+        const stripped = line.trim();
+        if (!stripped || stripped.startsWith('#')) {
+          lines.push(line);
+        } else if (stripped.includes('=')) {
+          const key = stripped.split('=')[0].trim();
+          if (key === apiKeyName) {
+            lines.push(`${apiKeyName}=${apiKeyValue}`);
+            keyUpdated = true;
+          } else {
+            lines.push(line);
+          }
+        } else {
+          lines.push(line);
+        }
+      }
+
+      if (!keyUpdated) {
+        if (lines.length > 0 && !lines[lines.length - 1].endsWith('\n')) {
+          lines.push('');
+        }
+        lines.push(`${apiKeyName}=${apiKeyValue}`);
+      }
+    } else {
+      lines.push('# LLM API Keys');
+      lines.push(`${apiKeyName}=${apiKeyValue}`);
+    }
+
+    writeFileSync('.env', lines.join('\n'));
+
+    // Reload environment variables
+    config({ override: true, quiet: true });
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function saveApiKeyForProvider(providerId: string, apiKey: string): boolean {
+  const apiKeyName = getApiKeyNameForProvider(providerId);
+  if (!apiKeyName) return false;
+  return saveApiKeyToEnv(apiKeyName, apiKey);
+}

package/src/utils/error-classifier.test.ts

@@ -0,0 +1,146 @@
+import { describe, test, expect } from 'bun:test';
+import { classifyError } from './error-classifier.js';
+
+describe('classifyError', () => {
+  // -------------------------------------------------------------------------
+  // Rate limit errors
+  // -------------------------------------------------------------------------
+  test('classifies rate limit error (429)', () => {
+    const result = classifyError('Request failed with status code 429');
+    expect(result.category).toBe('Rate Limit');
+    expect(result.suggestions.length).toBeGreaterThan(0);
+    expect(result.suggestions.some(s => s.toLowerCase().includes('wait'))).toBe(true);
+  });
+
+  test('classifies "rate limit" text', () => {
+    const result = classifyError('Rate limit exceeded. Please try again later.');
+    expect(result.category).toBe('Rate Limit');
+  });
+
+  test('classifies "too many requests"', () => {
+    const result = classifyError('Too many requests, slow down');
+    expect(result.category).toBe('Rate Limit');
+  });
+
+  // -------------------------------------------------------------------------
+  // Authentication errors
+  // -------------------------------------------------------------------------
+  test('classifies 401 authentication error', () => {
+    const result = classifyError('Request failed with status code 401');
+    expect(result.category).toBe('Authentication Error');
+    expect(result.suggestions.some(s => s.toLowerCase().includes('api key'))).toBe(true);
+  });
+
+  test('classifies "unauthorized" error', () => {
+    const result = classifyError('Unauthorized: invalid API key');
+    expect(result.category).toBe('Authentication Error');
+  });
+
+  test('classifies 403 forbidden', () => {
+    const result = classifyError('403 Forbidden');
+    expect(result.category).toBe('Authentication Error');
+  });
+
+  test('classifies "invalid key" error', () => {
+    const result = classifyError('Invalid API key provided');
+    expect(result.category).toBe('Authentication Error');
+  });
+
+  // -------------------------------------------------------------------------
+  // Context too long errors
+  // -------------------------------------------------------------------------
+  test('classifies context length error', () => {
+    const result = classifyError('This model\'s maximum context length is 128000 tokens');
+    expect(result.category).toBe('Context Too Long');
+    expect(result.suggestions.some(s => s.includes('/compact'))).toBe(true);
+  });
+
+  test('classifies token limit error', () => {
+    const result = classifyError('Token limit exceeded');
+    expect(result.category).toBe('Context Too Long');
+  });
+
+  test('classifies "context window" error', () => {
+    const result = classifyError('Exceeded context window for this model');
+    expect(result.category).toBe('Context Too Long');
+  });
+
+  // -------------------------------------------------------------------------
+  // Network errors
+  // -------------------------------------------------------------------------
+  test('classifies ECONNREFUSED', () => {
+    const result = classifyError('connect ECONNREFUSED 127.0.0.1:11434');
+    expect(result.category).toBe('Network Error');
+    expect(result.suggestions.some(s => s.toLowerCase().includes('connection'))).toBe(true);
+  });
+
+  test('classifies timeout error', () => {
+    const result = classifyError('Request timeout after 30000ms');
+    expect(result.category).toBe('Network Error');
+  });
+
+  test('classifies ENOTFOUND', () => {
+    const result = classifyError('getaddrinfo ENOTFOUND api.openai.com');
+    expect(result.category).toBe('Network Error');
+  });
+
+  test('classifies fetch failure', () => {
+    const result = classifyError('fetch failed: network error');
+    expect(result.category).toBe('Network Error');
+  });
+
+  // -------------------------------------------------------------------------
+  // Model not found errors
+  // -------------------------------------------------------------------------
+  test('classifies model not found', () => {
+    const result = classifyError('The model `gpt-99` does not exist');
+    expect(result.category).toBe('Model Not Found');
+    expect(result.suggestions.some(s => s.includes('/model'))).toBe(true);
+  });
+
+  test('classifies unknown model', () => {
+    const result = classifyError('Unknown model: fake-model');
+    expect(result.category).toBe('Model Not Found');
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool errors
+  // -------------------------------------------------------------------------
+  test('classifies tool error', () => {
+    const result = classifyError('Tool error: web_fetch failed with status 500');
+    expect(result.category).toBe('Tool Error');
+  });
+
+  test('classifies tool execution error', () => {
+    const result = classifyError('Execution error in tool handler');
+    expect(result.category).toBe('Tool Error');
+  });
+
+  // -------------------------------------------------------------------------
+  // Billing errors
+  // -------------------------------------------------------------------------
+  test('classifies insufficient funds', () => {
+    const result = classifyError('Insufficient funds in your account');
+    expect(result.category).toBe('Billing Error');
+    expect(result.suggestions.some(s => s.toLowerCase().includes('billing'))).toBe(true);
+  });
+
+  test('classifies quota exceeded', () => {
+    const result = classifyError('You have exceeded your quota');
+    expect(result.category).toBe('Billing Error');
+  });
+
+  // -------------------------------------------------------------------------
+  // Unknown errors (fallback)
+  // -------------------------------------------------------------------------
+  test('classifies unknown error with fallback suggestions', () => {
+    const result = classifyError('Something completely unexpected happened');
+    expect(result.category).toBe('Unknown Error');
+    expect(result.suggestions.length).toBeGreaterThan(0);
+  });
+
+  test('classifies empty error string', () => {
+    const result = classifyError('');
+    expect(result.category).toBe('Unknown Error');
+  });
+});

package/src/utils/error-classifier.ts

@@ -0,0 +1,91 @@
+export interface ErrorClassification {
+  category: string;
+  suggestions: string[];
+}
+
+const ERROR_PATTERNS: Array<{
+  pattern: RegExp;
+  category: string;
+  suggestions: string[];
+}> = [
+  {
+    pattern: /rate.?limit|429|too many requests/i,
+    category: 'Rate Limit',
+    suggestions: [
+      'Wait 30 seconds and try again',
+      'Switch to a different model with /model',
+      'Use /compact to reduce context size',
+    ],
+  },
+  {
+    pattern: /auth|401|403|api.?key|unauthorized|forbidden|invalid.*key/i,
+    category: 'Authentication Error',
+    suggestions: [
+      'Check your API key is set correctly',
+      'Run /model to switch provider or re-enter key',
+      'Verify your API key has the required permissions',
+    ],
+  },
+  {
+    pattern: /context.*length|token.*limit|too.*long|maximum.*context|context.*window/i,
+    category: 'Context Too Long',
+    suggestions: [
+      'Use /compact to summarize and reduce context',
+      'Use /clear to start a fresh conversation',
+      'Try a model with a larger context window',
+    ],
+  },
+  {
+    pattern: /tool.*error|tool.*fail|execution.*error/i,
+    category: 'Tool Error',
+    suggestions: [
+      'Try rephrasing your question',
+      'The tool may be temporarily unavailable',
+    ],
+  },
+  {
+    pattern: /network|ECONNREFUSED|ENOTFOUND|timeout|ETIMEDOUT|fetch.*fail|socket/i,
+    category: 'Network Error',
+    suggestions: [
+      'Check your internet connection',
+      'Try again in a few seconds',
+      'If using Ollama, ensure the server is running',
+    ],
+  },
+  {
+    pattern: /model.*not.*found|does not exist|invalid.*model|unknown.*model/i,
+    category: 'Model Not Found',
+    suggestions: [
+      'Run /model to select a valid model',
+      'Check the model name for typos',
+    ],
+  },
+  {
+    pattern: /insufficient.*funds|billing|payment|quota/i,
+    category: 'Billing Error',
+    suggestions: [
+      'Check your account billing status',
+      'Switch to a free or cheaper model with /model',
+    ],
+  },
+];
+
+/**
+ * Classify an error message and return actionable suggestions.
+ */
+export function classifyError(errorMessage: string): ErrorClassification {
+  for (const { pattern, category, suggestions } of ERROR_PATTERNS) {
+    if (pattern.test(errorMessage)) {
+      return { category, suggestions };
+    }
+  }
+
+  return {
+    category: 'Unknown Error',
+    suggestions: [
+      'Try rephrasing your question',
+      'Use /clear to start fresh',
+      'Switch models with /model',
+    ],
+  };
+}