brownian-code 2026.2.10

package/src/model/llm.ts

@@ -0,0 +1,233 @@
+import { AIMessage } from '@langchain/core/messages';
+import { ChatOpenAI } from '@langchain/openai';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
+import { ChatOllama } from '@langchain/ollama';
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { StructuredToolInterface } from '@langchain/core/tools';
+import { Runnable } from '@langchain/core/runnables';
+import { z } from 'zod';
+import { DEFAULT_SYSTEM_PROMPT } from '@/agent/prompts';
+import type { TokenUsage } from '@/agent/types';
+import { logger } from '@/utils';
+import { resolveProvider, getProviderById } from '@/providers';
+
+export const DEFAULT_PROVIDER = 'anthropic';
+export const DEFAULT_MODEL = 'claude-sonnet-4-5';
+
+/**
+ * Gets the fast model variant for the given provider.
+ * Falls back to the provided model if no fast variant is configured (e.g., Ollama).
+ */
+export function getFastModel(modelProvider: string, fallbackModel: string): string {
+  return getProviderById(modelProvider)?.fastModel ?? fallbackModel;
+}
+
+// Generic retry helper with exponential backoff
+async function withRetry<T>(fn: () => Promise<T>, provider: string, maxAttempts = 3): Promise<T> {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      logger.error(`[${provider} API] error (attempt ${attempt + 1}/${maxAttempts}): ${message}`);
+
+      if (attempt === maxAttempts - 1) {
+        throw new Error(`[${provider} API] ${message}`);
+      }
+      await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+    }
+  }
+  throw new Error('Unreachable');
+}
+
+// Model provider configuration
+interface ModelOpts {
+  streaming: boolean;
+}
+
+type ModelFactory = (name: string, opts: ModelOpts) => BaseChatModel;
+
+function getApiKey(envVar: string): string {
+  const apiKey = process.env[envVar];
+  if (!apiKey || apiKey.trim().startsWith('your-')) {
+    throw new Error(`API key not configured. Add ${envVar}=<your-key> to your .env file`);
+  }
+  return apiKey;
+}
+
+// Factories keyed by provider id — prefix routing is handled by resolveProvider()
+const MODEL_FACTORIES: Record<string, ModelFactory> = {
+  anthropic: (name, opts) =>
+    new ChatAnthropic({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('ANTHROPIC_API_KEY'),
+    }),
+  google: (name, opts) =>
+    new ChatGoogleGenerativeAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('GOOGLE_API_KEY'),
+    }),
+  xai: (name, opts) =>
+    new ChatOpenAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('XAI_API_KEY'),
+      configuration: {
+        baseURL: 'https://api.x.ai/v1',
+      },
+    }),
+  openrouter: (name, opts) =>
+    new ChatOpenAI({
+      model: name.replace(/^openrouter:/, ''),
+      ...opts,
+      apiKey: getApiKey('OPENROUTER_API_KEY'),
+      configuration: {
+        baseURL: 'https://openrouter.ai/api/v1',
+      },
+    }),
+  moonshot: (name, opts) =>
+    new ChatOpenAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('MOONSHOT_API_KEY'),
+      configuration: {
+        baseURL: 'https://api.moonshot.cn/v1',
+      },
+    }),
+  deepseek: (name, opts) =>
+    new ChatOpenAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('DEEPSEEK_API_KEY'),
+      configuration: {
+        baseURL: 'https://api.deepseek.com',
+      },
+    }),
+  ollama: (name, opts) =>
+    new ChatOllama({
+      model: name.replace(/^ollama:/, ''),
+      ...opts,
+      ...(process.env.OLLAMA_BASE_URL ? { baseUrl: process.env.OLLAMA_BASE_URL } : {}),
+    }),
+};
+
+const DEFAULT_FACTORY: ModelFactory = (name, opts) =>
+  new ChatOpenAI({
+    model: name,
+    ...opts,
+    apiKey: getApiKey('OPENAI_API_KEY'),
+  });
+
+export function getChatModel(
+  modelName: string = DEFAULT_MODEL,
+  streaming: boolean = false
+): BaseChatModel {
+  const opts: ModelOpts = { streaming };
+  const provider = resolveProvider(modelName);
+  const factory = MODEL_FACTORIES[provider.id] ?? DEFAULT_FACTORY;
+  return factory(modelName, opts);
+}
+
+interface CallLlmOptions {
+  model?: string;
+  systemPrompt?: string;
+  outputSchema?: z.ZodType<unknown>;
+  tools?: StructuredToolInterface[];
+  signal?: AbortSignal;
+}
+
+export interface LlmResult {
+  response: AIMessage | string;
+  usage?: TokenUsage;
+}
+
+function extractUsage(result: unknown): TokenUsage | undefined {
+  if (!result || typeof result !== 'object') return undefined;
+  const msg = result as Record<string, unknown>;
+
+  const usageMetadata = msg.usage_metadata;
+  if (usageMetadata && typeof usageMetadata === 'object') {
+    const u = usageMetadata as Record<string, unknown>;
+    const input = typeof u.input_tokens === 'number' ? u.input_tokens : 0;
+    const output = typeof u.output_tokens === 'number' ? u.output_tokens : 0;
+    const total = typeof u.total_tokens === 'number' ? u.total_tokens : input + output;
+    return { inputTokens: input, outputTokens: output, totalTokens: total };
+  }
+
+  const responseMetadata = msg.response_metadata;
+  if (responseMetadata && typeof responseMetadata === 'object') {
+    const rm = responseMetadata as Record<string, unknown>;
+    if (rm.usage && typeof rm.usage === 'object') {
+      const u = rm.usage as Record<string, unknown>;
+      const input = typeof u.prompt_tokens === 'number' ? u.prompt_tokens : 0;
+      const output = typeof u.completion_tokens === 'number' ? u.completion_tokens : 0;
+      const total = typeof u.total_tokens === 'number' ? u.total_tokens : input + output;
+      return { inputTokens: input, outputTokens: output, totalTokens: total };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Build messages with Anthropic cache_control on the system prompt.
+ * Marks the system prompt as ephemeral so Anthropic caches the prefix,
+ * reducing input token costs by ~90% on subsequent calls.
+ */
+function buildAnthropicMessages(systemPrompt: string, userPrompt: string) {
+  return [
+    new SystemMessage({
+      content: [
+        {
+          type: 'text' as const,
+          text: systemPrompt,
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+    }),
+    new HumanMessage(userPrompt),
+  ];
+}
+
+export async function callLlm(prompt: string, options: CallLlmOptions = {}): Promise<LlmResult> {
+  const { model = DEFAULT_MODEL, systemPrompt, outputSchema, tools, signal } = options;
+  const finalSystemPrompt = systemPrompt || DEFAULT_SYSTEM_PROMPT;
+
+  const llm = getChatModel(model, false);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let runnable: Runnable<any, any> = llm;
+
+  if (outputSchema) {
+    runnable = llm.withStructuredOutput(outputSchema, { strict: false });
+  } else if (tools && tools.length > 0 && llm.bindTools) {
+    runnable = llm.bindTools(tools);
+  }
+
+  const invokeOpts = signal ? { signal } : undefined;
+  const provider = resolveProvider(model);
+  let result;
+
+  if (provider.id === 'anthropic') {
+    // Anthropic: use explicit messages with cache_control for prompt caching (~90% savings)
+    const messages = buildAnthropicMessages(finalSystemPrompt, prompt);
+    result = await withRetry(() => runnable.invoke(messages, invokeOpts), provider.displayName);
+  } else {
+    // Other providers: use direct messages to avoid ChatPromptTemplate parsing
+    // literal {} in the system prompt (JSON examples) as template variables
+    const messages = [new SystemMessage(finalSystemPrompt), new HumanMessage(prompt)];
+    result = await withRetry(() => runnable.invoke(messages, invokeOpts), provider.displayName);
+  }
+  const usage = extractUsage(result);
+
+  // If no outputSchema and no tools, extract content from AIMessage
+  // When tools are provided, return the full AIMessage to preserve tool_calls
+  if (!outputSchema && !tools && result && typeof result === 'object' && 'content' in result) {
+    return { response: (result as { content: string }).content, usage };
+  }
+  return { response: result as AIMessage, usage };
+}

package/src/providers.ts

@@ -0,0 +1,94 @@
+/**
+ * Canonical provider registry — single source of truth for all provider metadata.
+ * When adding a new provider, add a single entry here; all other modules derive from this.
+ */
+
+export interface ProviderDef {
+  /** Slug used in config/settings (e.g., 'anthropic') */
+  id: string;
+  /** Human-readable name (e.g., 'Anthropic') */
+  displayName: string;
+  /** Model name prefix used for routing (e.g., 'claude-'). Empty string for default (OpenAI). */
+  modelPrefix: string;
+  /** Environment variable name for API key. Omit for local providers (e.g., Ollama). */
+  apiKeyEnvVar?: string;
+  /** Fast model variant for lightweight tasks like summarization. */
+  fastModel?: string;
+}
+
+export const PROVIDERS: ProviderDef[] = [
+  {
+    id: 'openai',
+    displayName: 'OpenAI',
+    modelPrefix: '',
+    apiKeyEnvVar: 'OPENAI_API_KEY',
+    fastModel: 'gpt-4.1',
+  },
+  {
+    id: 'anthropic',
+    displayName: 'Anthropic',
+    modelPrefix: 'claude-',
+    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+    fastModel: 'claude-haiku-4-5',
+  },
+  {
+    id: 'google',
+    displayName: 'Google',
+    modelPrefix: 'gemini-',
+    apiKeyEnvVar: 'GOOGLE_API_KEY',
+    fastModel: 'gemini-3-flash-preview',
+  },
+  {
+    id: 'xai',
+    displayName: 'xAI',
+    modelPrefix: 'grok-',
+    apiKeyEnvVar: 'XAI_API_KEY',
+    fastModel: 'grok-4-1-fast-reasoning',
+  },
+  {
+    id: 'moonshot',
+    displayName: 'Moonshot',
+    modelPrefix: 'kimi-',
+    apiKeyEnvVar: 'MOONSHOT_API_KEY',
+    fastModel: 'kimi-k2-5',
+  },
+  {
+    id: 'deepseek',
+    displayName: 'DeepSeek',
+    modelPrefix: 'deepseek-',
+    apiKeyEnvVar: 'DEEPSEEK_API_KEY',
+    fastModel: 'deepseek-chat',
+  },
+  {
+    id: 'openrouter',
+    displayName: 'OpenRouter',
+    modelPrefix: 'openrouter:',
+    apiKeyEnvVar: 'OPENROUTER_API_KEY',
+    fastModel: 'openrouter:openai/gpt-4o-mini',
+  },
+  {
+    id: 'ollama',
+    displayName: 'Ollama',
+    modelPrefix: 'ollama:',
+  },
+];
+
+const defaultProvider = PROVIDERS.find((p) => p.id === 'anthropic')!;
+
+/**
+ * Resolve the provider for a given model name based on its prefix.
+ * Falls back to OpenAI when no prefix matches.
+ */
+export function resolveProvider(modelName: string): ProviderDef {
+  return (
+    PROVIDERS.find((p) => p.modelPrefix && modelName.startsWith(p.modelPrefix)) ??
+    defaultProvider
+  );
+}
+
+/**
+ * Look up a provider by its slug (e.g., 'anthropic', 'google').
+ */
+export function getProviderById(id: string): ProviderDef | undefined {
+  return PROVIDERS.find((p) => p.id === id);
+}

package/src/skills/index.ts

@@ -0,0 +1,17 @@
+// Skill types
+export type { SkillMetadata, Skill, SkillSource } from './types.js';
+
+// Skill registry functions
+export {
+  discoverSkills,
+  getSkill,
+  buildSkillMetadataSection,
+  clearSkillCache,
+} from './registry.js';
+
+// Skill loader functions
+export {
+  parseSkillFile,
+  loadSkillFromPath,
+  extractSkillMetadata,
+} from './loader.js';

package/src/skills/loader.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from 'fs';
+import matter from 'gray-matter';
+import type { Skill, SkillSource } from './types.js';
+
+/**
+ * Parse a SKILL.md file content into a Skill object.
+ * Extracts YAML frontmatter (name, description) and the markdown body (instructions).
+ *
+ * @param content - Raw file content
+ * @param path - Absolute path to the file (for reference)
+ * @param source - Where this skill came from
+ * @returns Parsed Skill object
+ * @throws Error if required frontmatter fields are missing
+ */
+export function parseSkillFile(content: string, path: string, source: SkillSource): Skill {
+  const { data, content: instructions } = matter(content);
+
+  // Validate required frontmatter fields
+  if (!data.name || typeof data.name !== 'string') {
+    throw new Error(`Skill at ${path} is missing required 'name' field in frontmatter`);
+  }
+  if (!data.description || typeof data.description !== 'string') {
+    throw new Error(`Skill at ${path} is missing required 'description' field in frontmatter`);
+  }
+
+  return {
+    name: data.name,
+    description: data.description,
+    path,
+    source,
+    instructions: instructions.trim(),
+  };
+}
+
+/**
+ * Load a skill from a file path.
+ *
+ * @param path - Absolute path to the SKILL.md file
+ * @param source - Where this skill came from
+ * @returns Parsed Skill object
+ * @throws Error if file cannot be read or parsed
+ */
+export function loadSkillFromPath(path: string, source: SkillSource): Skill {
+  const content = readFileSync(path, 'utf-8');
+  return parseSkillFile(content, path, source);
+}
+
+/**
+ * Extract just the metadata from a skill file without loading full instructions.
+ * Used for lightweight discovery at startup.
+ *
+ * @param path - Absolute path to the SKILL.md file
+ * @param source - Where this skill came from
+ * @returns Skill metadata (name, description, path, source)
+ */
+export function extractSkillMetadata(path: string, source: SkillSource): { name: string; description: string; path: string; source: SkillSource } {
+  const content = readFileSync(path, 'utf-8');
+  const { data } = matter(content);
+
+  if (!data.name || typeof data.name !== 'string') {
+    throw new Error(`Skill at ${path} is missing required 'name' field in frontmatter`);
+  }
+  if (!data.description || typeof data.description !== 'string') {
+    throw new Error(`Skill at ${path} is missing required 'description' field in frontmatter`);
+  }
+
+  return {
+    name: data.name,
+    description: data.description,
+    path,
+    source,
+  };
+}

package/src/skills/registry.ts

@@ -0,0 +1,125 @@
+import { existsSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import type { SkillMetadata, Skill, SkillSource } from './types.js';
+import { extractSkillMetadata, loadSkillFromPath } from './loader.js';
+
+// Get the directory of this file to locate builtin skills
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Skill directories in order of precedence (later overrides earlier).
+ */
+const SKILL_DIRECTORIES: { path: string; source: SkillSource }[] = [
+  { path: __dirname, source: 'builtin' },
+  { path: join(homedir(), '.brownian', 'skills'), source: 'user' },
+  { path: join(process.cwd(), '.brownian', 'skills'), source: 'project' },
+];
+
+// Cache for discovered skills (metadata only)
+let skillMetadataCache: Map<string, SkillMetadata> | null = null;
+
+/**
+ * Scan a directory for SKILL.md files and return their metadata.
+ * Looks for directories containing SKILL.md files.
+ *
+ * @param dirPath - Directory to scan
+ * @param source - Source type for discovered skills
+ * @returns Array of skill metadata
+ */
+function scanSkillDirectory(dirPath: string, source: SkillSource): SkillMetadata[] {
+  if (!existsSync(dirPath)) {
+    return [];
+  }
+
+  const skills: SkillMetadata[] = [];
+  const entries = readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const skillFilePath = join(dirPath, entry.name, 'SKILL.md');
+      if (existsSync(skillFilePath)) {
+        try {
+          const metadata = extractSkillMetadata(skillFilePath, source);
+          skills.push(metadata);
+        } catch {
+          // Skip invalid skill files silently
+        }
+      }
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Discover all available skills from all skill directories.
+ * Later sources (project > user > builtin) override earlier ones.
+ *
+ * @returns Array of skill metadata, deduplicated by name
+ */
+export function discoverSkills(): SkillMetadata[] {
+  if (skillMetadataCache) {
+    return Array.from(skillMetadataCache.values());
+  }
+
+  skillMetadataCache = new Map();
+
+  for (const { path, source } of SKILL_DIRECTORIES) {
+    const skills = scanSkillDirectory(path, source);
+    for (const skill of skills) {
+      // Later sources override earlier ones (by name)
+      skillMetadataCache.set(skill.name, skill);
+    }
+  }
+
+  return Array.from(skillMetadataCache.values());
+}
+
+/**
+ * Get a skill by name, loading full instructions.
+ *
+ * @param name - Name of the skill to load
+ * @returns Full skill definition or undefined if not found
+ */
+export function getSkill(name: string): Skill | undefined {
+  // Ensure cache is populated
+  if (!skillMetadataCache) {
+    discoverSkills();
+  }
+
+  const metadata = skillMetadataCache?.get(name);
+  if (!metadata) {
+    return undefined;
+  }
+
+  // Load full skill with instructions
+  return loadSkillFromPath(metadata.path, metadata.source);
+}
+
+/**
+ * Build the skill metadata section for the system prompt.
+ * Only includes name and description (lightweight).
+ *
+ * @returns Formatted string for system prompt injection
+ */
+export function buildSkillMetadataSection(): string {
+  const skills = discoverSkills();
+
+  if (skills.length === 0) {
+    return 'No skills available.';
+  }
+
+  return skills
+    .map((s) => `- **${s.name}**: ${s.description}`)
+    .join('\n');
+}
+
+/**
+ * Clear the skill cache. Useful for testing or when skills are added/removed.
+ */
+export function clearSkillCache(): void {
+  skillMetadataCache = null;
+}

package/src/skills/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Source of a skill definition.
+ * - builtin: Shipped with Brownian Code (src/skills/builtin/)
+ * - user: User-level skills (~/.brownian/skills/)
+ * - project: Project-level skills (.brownian/skills/)
+ */
+export type SkillSource = 'builtin' | 'user' | 'project';
+
+/**
+ * Skill metadata - lightweight info loaded at startup for system prompt injection.
+ * Only contains the name and description from YAML frontmatter.
+ */
+export interface SkillMetadata {
+  /** Unique skill name (e.g., "dcf") */
+  name: string;
+  /** Description of when to use this skill */
+  description: string;
+  /** Absolute path to the SKILL.md file */
+  path: string;
+  /** Where this skill was discovered from */
+  source: SkillSource;
+}
+
+/**
+ * Full skill definition with instructions loaded on-demand.
+ * Extends metadata with the full SKILL.md body content.
+ */
+export interface Skill extends SkillMetadata {
+  /** Full instructions from SKILL.md body (loaded when skill is invoked) */
+  instructions: string;
+}

package/src/test-utils/mocks.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared test utilities and mock factories for Brownian Code tests.
+ */
+import { tmpdir } from 'os';
+import { mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import type { AIMessage } from '@langchain/core/messages';
+
+/**
+ * Create a minimal AIMessage-compatible object.
+ * Use for mocking callLlm responses that include tool calls.
+ */
+export function createMockAIMessage(
+  content: string,
+  toolCalls?: Array<{ name: string; args: Record<string, unknown> }>
+): AIMessage {
+  return {
+    content,
+    tool_calls: toolCalls ?? [],
+    // Minimal AIMessage-compatible shape
+    lc_namespace: ['langchain_core', 'messages'],
+    lc_serializable: true,
+    _getType: () => 'ai',
+  } as unknown as AIMessage;
+}
+
+/**
+ * Create a mock tool compatible with StructuredToolInterface.
+ * @param name - Tool name
+ * @param resultOrFn - Static string result, or a function that receives args and returns a result
+ */
+export function createMockTool(
+  name: string,
+  resultOrFn: string | ((args: Record<string, unknown>) => string | Promise<string>)
+) {
+  return {
+    name,
+    description: `Mock tool: ${name}`,
+    schema: {},
+    invoke: async (args: Record<string, unknown>) => {
+      if (typeof resultOrFn === 'function') {
+        return resultOrFn(args);
+      }
+      return resultOrFn;
+    },
+    lc_namespace: ['langchain_core', 'tools'],
+  };
+}
+
+/**
+ * Create a callLlm mock that yields scripted responses in sequence.
+ * Each call pops the next response from the array.
+ *
+ * - string → treated as plain text response (no tools)
+ * - AIMessage → returned as-is (may include tool_calls)
+ */
+export function createMockCallLlm(
+  responses: Array<string | AIMessage>
+) {
+  let index = 0;
+  return async (_prompt: string, _options?: unknown) => {
+    if (index >= responses.length) {
+      return { response: 'No more scripted responses', usage: undefined };
+    }
+    const resp = responses[index++];
+    return {
+      response: resp,
+      usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+    };
+  };
+}
+
+/**
+ * Run a function with CWD set to a unique temp directory.
+ * Restores CWD and cleans up the temp dir afterward.
+ */
+export async function withTempCwd<T>(fn: (tmpDir: string) => T | Promise<T>): Promise<T> {
+  const originalCwd = process.cwd();
+  const tmpDir = mkdtempSync(join(tmpdir(), 'brownian-test-'));
+
+  try {
+    process.chdir(tmpDir);
+    return await fn(tmpDir);
+  } finally {
+    process.chdir(originalCwd);
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // Best effort cleanup
+    }
+  }
+}
+
+/**
+ * Create a unique temp directory and return its path + cleanup function.
+ * Useful when you need to set up once in beforeAll.
+ */
+export function createTempDir(): { path: string; cleanup: () => void } {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'brownian-test-'));
+  return {
+    path: tmpDir,
+    cleanup: () => {
+      try {
+        rmSync(tmpDir, { recursive: true, force: true });
+      } catch {
+        // Best effort
+      }
+    },
+  };
+}