loom-agent 1.2.0

package/src/mcp/mcp-manager.js

@@ -0,0 +1,193 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const LOOM_DIR = path.join(os.homedir(), '.loom');
+
+// Re-evaluated on every call (like the other stores) so tests/CI can isolate
+// with LOOM_CONFIG_DIR; the exported MCP_FILE keeps the default for display.
+function mcpFile() {
+  return path.join(process.env.LOOM_CONFIG_DIR || LOOM_DIR, 'mcp.json');
+}
+const MCP_FILE = path.join(LOOM_DIR, 'mcp.json');
+
+function loadServers() {
+  if (!fs.existsSync(mcpFile())) return { servers: {}, seeded: false };
+  try {
+    const raw = fs.readFileSync(mcpFile(), 'utf8');
+    const data = JSON.parse(raw);
+    return { servers: data.servers || {}, seeded: data.seeded === true };
+  } catch {
+    return { servers: {}, seeded: false };
+  }
+}
+
+function saveServers(data) {
+  const dir = path.dirname(mcpFile());
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(mcpFile(), JSON.stringify(data, null, 2));
+}
+
+function listServers() {
+  const { servers } = loadServers();
+  return Object.entries(servers).map(([name, cfg]) => ({
+    name,
+    command: cfg.command || '',
+    args: cfg.args || [],
+    enabled: cfg.enabled !== false,
+  }));
+}
+
+function clearMcpCache() {
+  try { require('./mcp-client').clearCache(); } catch {}
+}
+
+function addServer(name, command, args, opts) {
+  if (!name || !command) return { error: 'Usage: /mcp add <name> <command> [args...]' };
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+    return { error: 'Invalid server name "' + name + '": use only letters, digits, - and _' };
+  }
+  // buildToolName joins with '__' and callTool splits on the last one — a name
+  // containing '__' would make tool names unparseable.
+  if (name.indexOf('__') >= 0) return { error: 'Server name cannot contain "__"' };
+  const data = loadServers();
+  data.servers[name] = {
+    name,
+    command,
+    args: args || [],
+    enabled: !opts || opts.enabled !== false,
+  };
+  if (opts && opts.env) data.servers[name].env = opts.env;
+  saveServers(data);
+  clearMcpCache();
+  return { added: name, command, args: data.servers[name].args };
+}
+
+// Parse the claude-compatible add syntax:
+//   /mcp add [-e KEY=V]... <name> [--] <command> [args...]
+// The `--` separator is optional (kept for muscle memory from `claude mcp add`).
+// Env flags may appear before the name or right before the command.
+/**
+ * @param {string[]} argv
+ * @returns {{name: string, command: string, args: string[], env?: Record<string,string>} | {error: string}}
+ */
+function parseMcpAddArgs(argv) {
+  const usage = 'Usage: /mcp add [-e KEY=V]... <name> [--] <command> [args...]';
+  /** @type {Record<string, string>} */
+  const env = {};
+  const takeEnv = (i) => {
+    const pair = argv[i + 1];
+    if (!pair || pair.indexOf('=') < 1) return null;
+    const eq = pair.indexOf('=');
+    env[pair.slice(0, eq)] = pair.slice(eq + 1);
+    return i + 2;
+  };
+  let i = 0;
+  while (argv[i] === '-e' || argv[i] === '--env') {
+    const ni = takeEnv(i);
+    if (ni === null) return { error: 'Usage: -e KEY=VALUE (got "' + (argv[i + 1] || '') + '")' };
+    i = ni;
+  }
+  if (i >= argv.length) return { error: usage };
+  const name = argv[i];
+  i += 1;
+  while (argv[i] === '-e' || argv[i] === '--env') {
+    const ni = takeEnv(i);
+    if (ni === null) return { error: 'Usage: -e KEY=VALUE (got "' + (argv[i + 1] || '') + '")' };
+    i = ni;
+  }
+  if (argv[i] === '--') i += 1;
+  if (i >= argv.length) return { error: usage };
+  const command = argv[i];
+  const args = argv.slice(i + 1);
+  return Object.keys(env).length ? { name, command, args, env } : { name, command, args };
+}
+
+function seedDefaults() {
+  const data = loadServers();
+  if (data.seeded) return { skipped: true };
+  const isWin = process.platform === 'win32';
+  // npx on Windows must be wrapped: cmd /c npx -y <pkg>
+  const npx = (pkg) => (isWin ? { command: 'cmd', args: ['/c', 'npx', '-y', pkg] } : { command: 'npx', args: ['-y', pkg] });
+  // Key-free servers — enabled out of the box. Minimal on purpose: models
+  // speculate with thinking/time tools and waste turns, so they start disabled.
+  const enabled = {
+    fetch: npx('@modelcontextprotocol/server-fetch'),
+    memory: npx('@modelcontextprotocol/server-memory'),
+  };
+  // Servers that need a key/token/path or invite speculative calls — installed
+  // but disabled, toggle on after setup (/mcp toggle <name>).
+  const optional = {
+    time: npx('@modelcontextprotocol/server-time'),
+    'sequential-thinking': npx('@modelcontextprotocol/server-sequential-thinking'),
+    github: {
+      command: 'docker',
+      args: ['run', '-i', '--rm', '-e', 'GITHUB_PERSONAL_ACCESS_TOKEN', 'ghcr.io/github/github-mcp-server'],
+      env: { GITHUB_PERSONAL_ACCESS_TOKEN: '' },
+    },
+    filesystem: {
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
+    },
+    'brave-search': {
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-brave-search'],
+      env: { BRAVE_API_KEY: '' },
+    },
+  };
+  const count = Object.keys(enabled).length + Object.keys(optional).length;
+  for (const [name, cfg] of Object.entries(enabled)) {
+    if (data.servers[name]) continue;
+    data.servers[name] = Object.assign({ name, enabled: true }, cfg);
+  }
+  for (const [name, cfg] of Object.entries(optional)) {
+    if (data.servers[name]) continue;
+    data.servers[name] = Object.assign({ name, enabled: false }, cfg);
+  }
+  data.seeded = true;
+  saveServers(data);
+  clearMcpCache();
+  return { seeded: count };
+}
+
+function removeServer(name) {
+  const data = loadServers();
+  if (!data.servers[name]) return { error: 'MCP server not found: ' + name };
+  delete data.servers[name];
+  saveServers(data);
+  clearMcpCache();
+  return { removed: name };
+}
+
+function toggleServer(name) {
+  const data = loadServers();
+  if (!data.servers[name]) return { error: 'MCP server not found: ' + name };
+  data.servers[name].enabled = data.servers[name].enabled === false;
+  saveServers(data);
+  return { name, enabled: data.servers[name].enabled };
+}
+
+function stdioClient(cfg) {
+  const child = spawn(cfg.command, cfg.args || [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: Object.assign({}, process.env, cfg.env || {}),
+    // No console window for stdio MCP servers on Windows (avoids the popup
+    // nagging the user while the chat is running).
+    windowsHide: true,
+  });
+  return child;
+}
+
+module.exports = {
+  loadServers,
+  saveServers,
+  listServers,
+  addServer,
+  parseMcpAddArgs,
+  removeServer,
+  toggleServer,
+  stdioClient,
+  seedDefaults,
+  MCP_FILE,
+};

package/src/providers/anthropic.js

@@ -0,0 +1,243 @@
+const { getApiKey, getBaseUrl } = require('../config/settings');
+
+function getKey() {
+  return getApiKey('anthropic') || process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_API_KEY;
+}
+
+function getApiUrl() {
+  const base = getBaseUrl('anthropic') || process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com';
+  return base.replace(/\/$/, '') + '/v1/messages';
+}
+
+function formatContentText(text) {
+  return Array.isArray(text)
+    ? text
+    : [{ type: 'text', text: typeof text === 'string' ? text : JSON.stringify(text) }];
+}
+
+/**
+ * @typedef {Object} AnthropicBody
+ * @property {string} model
+ * @property {number} max_tokens
+ * @property {Array<Object>} messages
+ * @property {string|Array<{type: string, text: string, cache_control?: {type: string}}>=} system
+ * @property {number=} temperature
+ * @property {Array<Object>=} tools
+ * @property {{ type: 'enabled', budget_tokens: number }=} thinking
+ * @property {boolean=} cache
+ */
+
+/**
+ * @param {Array<Object>} messages
+ * @param {Object} options
+ * @returns {AnthropicBody}
+ */
+function buildBody(messages, options) {
+  const systemMsgs = [];
+  const out = [];
+  // Prompt-caching opt-out (on by default — cache_control is ignored by
+  // providers that don't support it and billed at write once, read cheap).
+  const useCache = options.cache !== false;
+
+  // System prompt comes from options.system (session.systemPrompt); also
+  // accept role:'system' entries in the message history.
+  if (options.system) systemMsgs.push(options.system);
+
+  for (const m of messages) {
+    if (m.role === 'system') { systemMsgs.push(m.content); continue; }
+    if (m.role === 'user') {
+      out.push({ role: 'user', content: formatContentText(m.content) });
+      continue;
+    }
+    if (m.role === 'tool') {
+      out.push({
+        role: 'user',
+        content: [{ type: 'tool_result', tool_use_id: m.toolCallId, content: String(m.content) }],
+      });
+      continue;
+    }
+    if (m.role === 'assistant') {
+      const blocks = [];
+      // History may carry raw Anthropic content blocks (e.g. from a
+      // restored session): keep thinking blocks (with their signature)
+      // so the extended-thinking tool-use flow can resend them.
+      if (Array.isArray(m.content)) {
+        for (const b of m.content) {
+          if (b.type === 'text') blocks.push({ type: 'text', text: b.text });
+          else if (b.type === 'thinking') blocks.push({ type: 'thinking', thinking: b.thinking, signature: b.signature });
+          else if (b.type === 'tool_use') blocks.push({ type: 'tool_use', id: b.id, name: b.name, input: b.input || {} });
+        }
+      } else if (m.content) {
+        blocks.push({ type: 'text', text: m.content });
+      }
+      for (const tc of m.toolCalls || []) {
+        blocks.push({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.input || {} });
+      }
+      out.push({ role: 'assistant', content: blocks });
+    }
+  }
+
+  /** @type {AnthropicBody} */
+  const body = {
+    model: options.model,
+    max_tokens: options.maxTokens || 8192,
+    messages: out,
+    ...(systemMsgs.length && {
+      system: useCache
+        ? [{ type: 'text', text: systemMsgs.join('\n\n'), cache_control: { type: 'ephemeral' } }]
+        : systemMsgs.join('\n\n'),
+    }),
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+  };
+
+  // Prompt caching (Anthropic): a cache breakpoint on the system prompt and
+  // on the LAST message means each turn re-reads the stable prefix from the
+  // cache instead of re-paying full input cost. Opt out with options.cache === false.
+  // cache_control is NOT valid on thinking blocks — skip those when picking
+  // the breakpoint block, else the API 400s and the turn dies mid-session.
+  if (useCache && out.length) {
+    const last = out[out.length - 1];
+    if (Array.isArray(last.content) && last.content.length) {
+      for (let ci = last.content.length - 1; ci >= 0; ci--) {
+        const lb = last.content[ci];
+        if (!lb || lb.type === 'thinking') continue;
+        if (!lb.cache_control) lb.cache_control = { type: 'ephemeral' };
+        break;
+      }
+    } else if (typeof last.content === 'string' && last.content) {
+      last.content = [{ type: 'text', text: last.content, cache_control: { type: 'ephemeral' } }];
+    }
+  }
+
+  // Extended thinking (Claude reasons BEFORE every reply, including after
+  // each tool result — the opencode-style multi-pass thinking). Only enabled
+  // when the active model supports it (options.reasoning set by the session
+  // from the model's 'reasoning' tag). Anthropic requires temperature unset
+  // and max_tokens comfortably above the budget.
+  if (options.reasoning) {
+    let maxTokens = options.maxTokens || 8192;
+    // Explicit per-turn budget (/think low|medium|high) wins over the default.
+    const budget = options.thinkingBudget
+      ? Math.min(32768, Math.max(1024, Number(options.thinkingBudget)))
+      : Math.min(8192, Math.max(1024, maxTokens - 4096));
+    // budget_tokens must be strictly less than max_tokens (API requirement),
+    // so lift max_tokens when a small configured limit would collide.
+    if (budget >= maxTokens) maxTokens = budget + 1;
+    body.max_tokens = maxTokens;
+    body.thinking = { type: 'enabled', budget_tokens: budget };
+    delete body.temperature;
+  }
+
+  if (options.tools && options.tools.length) {
+    body.tools = options.tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.input_schema || { type: 'object', properties: {} },
+    }));
+  }
+
+  return body;
+}
+
+function normalizeBlocks(contentBlocks) {
+  const textParts = [];
+  const toolCalls = [];
+  for (const block of contentBlocks) {
+    if (block.type === 'text') textParts.push(block.text);
+    else if (block.type === 'tool_use') {
+      toolCalls.push({ id: block.id, name: block.name, input: block.input || {} });
+    }
+  }
+  return { content: textParts.join(''), toolCalls };
+}
+
+async function post(body, options) {
+  const key = getKey();
+  if (!key) throw new Error("Anthropic API key not set. Use /connect anthropic or set ANTHROPIC_API_KEY.");
+  const apiUrl = getApiUrl();
+  const resp = await fetch(apiUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': key,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify(body),
+    signal: options.signal,
+  });
+  if (!resp.ok) {
+    /** @type {any} */
+    const err = await resp.json().catch(() => ({}));
+    const detail = err.error?.message || resp.statusText;
+    if (resp.status === 401) throw new Error("Anthropic 401 Unauthorized: the API key is invalid or expired. Run /connect anthropic and paste a new key.");
+    if (resp.status === 403) throw new Error("Anthropic 403 Forbidden: the API key is not authorized for this model. Check the model name and your account access.");
+    throw new Error(`Anthropic API error ${resp.status}: ${detail}`);
+  }
+  return resp;
+}
+
+async function chat(messages, options = {}) {
+  const body = buildBody(messages, options);
+  const resp = await post(body, options);
+  /** @type {any} */
+  const data = await resp.json();
+  return { ...normalizeBlocks(data.content || []), usage: data.usage };
+}
+
+async function stream(messages, options = {}, onDelta, onReasoning) {
+  const body = { ...buildBody(messages, options), stream: true };
+  const resp = await post(body, options);
+  if (!resp.body) throw new Error('Anthropic stream: empty response body');
+  const decoder = new TextDecoder('utf-8');
+  let buf = '';
+  let content = '';
+  let reasoning = '';
+  let usage = null;
+  const toolAcc = new Map();
+
+  for await (const chunk of resp.body) {
+    buf += decoder.decode(chunk, { stream: true });
+    const lines = buf.split('\n');
+    buf = lines.pop() || '';
+    for (const line of lines) {
+      if (!line.startsWith('data: ')) continue;
+      const raw = line.slice(6);
+      if (raw === '[DONE]') continue;
+      let evt;
+      try { evt = JSON.parse(raw); } catch { continue; }
+      if (evt.type === 'message_delta' && evt.usage) usage = evt.usage;
+      if (evt.type === 'content_block_start' && evt.content_block?.type === 'tool_use') {
+        toolAcc.set(evt.index, { id: evt.content_block.id, name: evt.content_block.name, input: '' });
+      } else if (evt.type === 'content_block_delta') {
+        const d = evt.delta || {};
+        if (d.type === 'text_delta') {
+          content += d.text;
+          if (onDelta) onDelta(d.text);
+        } else if (d.type === 'thinking_delta') {
+          reasoning += d.thinking || '';
+          if (onReasoning) onReasoning(d.thinking || '');
+        } else if (d.type === 'input_json_delta') {
+          if (!toolAcc.has(evt.index)) toolAcc.set(evt.index, { id: '', name: '', input: '' });
+          toolAcc.get(evt.index).input += d.partial_json;
+        }
+      }
+    }
+  }
+
+  const toolCalls = [];
+  for (const acc of toolAcc.values()) {
+    let input = {};
+    try { input = JSON.parse(acc.input || '{}'); } catch {}
+    toolCalls.push({ id: acc.id, name: acc.name, input });
+  }
+
+  return { content, reasoning, toolCalls, usage };
+}
+
+const models = [
+  { id: 'claude-sonnet-4-20250514', name: 'Claude Sonnet 4', provider: 'anthropic', context: 200000, priceIn: 3, priceOut: 15, tags: ['reasoning'] },
+  { id: 'claude-opus-4-20250514', name: 'Claude Opus 4', provider: 'anthropic', context: 200000, priceIn: 15, priceOut: 75, tags: ['reasoning'] },
+  { id: 'claude-3-5-haiku-20241022', name: 'Claude 3.5 Haiku', provider: 'anthropic', context: 200000, priceIn: 0.8, priceOut: 4 },
+];
+
+module.exports = { chat, stream, models, buildBody, normalizeBlocks };

package/src/providers/google.js

@@ -0,0 +1,29 @@
+const { createOpenAICompatProvider } = require('./openai-compat');
+const { getApiKey } = require('../config/settings');
+
+function getKey() {
+  return getApiKey('google') || process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY;
+}
+
+const provider = {
+  ...createOpenAICompatProvider({
+    getKey,
+    providerId: 'google',
+    envKeyHint: 'GOOGLE',
+  }),
+  models: [
+  // ── Frontier ──
+  { id: 'gemini-2.5-pro', name: 'Gemini 2.5 Pro', provider: 'google', tags: ['frontier'], context: 1000000, priceIn: 1.25, priceOut: 10 },
+  { id: 'gemini-2.5-flash', name: 'Gemini 2.5 Flash', provider: 'google', tags: ['fast'], context: 1000000, priceIn: 0.3, priceOut: 2.5 },
+  // ── Flash ──
+  { id: 'gemini-2.0-flash', name: 'Gemini 2.0 Flash', provider: 'google', tags: [], context: 1000000, priceIn: 0.1, priceOut: 0.4 },
+  { id: 'gemini-2.0-flash-lite', name: 'Gemini 2.0 Flash Lite', provider: 'google', tags: ['free', 'fast'], context: 1000000, priceIn: 0.075, priceOut: 0.3 },
+  // ── Legacy ──
+  { id: 'gemini-1.5-flash', name: 'Gemini 1.5 Flash', provider: 'google', tags: [], context: 1000000, priceIn: 0.075, priceOut: 0.3 },
+  { id: 'gemini-1.5-pro', name: 'Gemini 1.5 Pro', provider: 'google', tags: [], context: 2000000, priceIn: 1.25, priceOut: 5 },
+  // ── Gemma (Local / On-device) ──
+  { id: 'gemma-4-31b-it', name: 'Gemma 4 31B IT', provider: 'google', tags: ['small'], context: 32768, priceIn: 0.2, priceOut: 0.8 },
+  ],
+};
+
+module.exports = provider;

package/src/providers/index.js

@@ -0,0 +1,175 @@
+const AnthropicProvider = require('./anthropic');
+const OpenAIProvider = require('./openai');
+const NVIDIAProvider = require('./nvidia');
+const GoogleProvider = require('./google');
+const OpenRouterProvider = require('./openrouter');
+const TokenRouterProvider = require('./tokenrouter');
+const LocalProvider = require('./local');
+const { createOpenAICompatProvider } = require('./openai-compat');
+const { loadRegistry, fetchRegistry, isRegistryFresh, envNamesFor, SDK_BASE_URLS } = require('./registry');
+const { loadConfig, getApiKey } = require('../config/settings');
+
+const PROVIDERS = {
+  anthropic: AnthropicProvider,
+  openai: OpenAIProvider,
+  nvidia: NVIDIAProvider,
+  google: GoogleProvider,
+  openrouter: OpenRouterProvider,
+  tokenrouter: TokenRouterProvider,
+  local: LocalProvider,
+};
+
+// Providers shipped in code (always available, always listed in /models even
+// without a key). Everything else comes from the models.dev registry.
+const BUILTIN_PROVIDERS = Object.keys(PROVIDERS);
+const PROVIDER_ORDER = ['anthropic', 'openai', 'nvidia', 'google', 'openrouter', 'tokenrouter', 'local'];
+const PROVIDER_LABELS = {
+  anthropic: 'Anthropic (Claude)',
+  openai: 'OpenAI (GPT)',
+  nvidia: 'NVIDIA NIM',
+  google: 'Google Gemini',
+  openrouter: 'OpenRouter',
+  tokenrouter: 'Token Router',
+  local: 'Local (Ollama/LM Studio)',
+};
+
+// ── models.dev registry providers ──
+// Fetched once and cached at ~/.loom/models-dev.json (opencode uses the same
+// dataset for its 75+ providers). Each provider becomes an OpenAI-compatible
+// runtime provider with its real model list, prices, and context windows.
+// Built-in providers always win the merge; registry entries without models
+// are skipped.
+
+/**
+ * @param {import('./registry').RegistryProvider} rp
+ * @returns {import('./openai-compat').Provider}
+ */
+function makeDynamicProvider(rp) {
+  const provider = createOpenAICompatProvider({
+    getKey: () => getApiKey(rp.id),
+    providerId: rp.id,
+    envKeyHint: rp.name,
+    defaultBaseUrl: rp.baseURL || SDK_BASE_URLS[rp.npm] || undefined,
+  });
+  provider.models = rp.models.map((m) => ({
+    id: m.id,
+    name: m.name,
+    provider: rp.id,
+    context: m.context,
+    priceIn: m.priceIn,
+    priceOut: m.priceOut,
+    tags: m.tags,
+  }));
+  return provider;
+}
+
+/**
+ * Merge the cached registry into PROVIDERS/PROVIDER_ORDER/PROVIDER_LABELS
+ * (in place, so existing imports keep working). Returns the number of
+ * providers added.
+ * @returns {number}
+ */
+function mergeRegistry() {
+  const reg = loadRegistry();
+  if (!reg) return 0;
+  let added = 0;
+  for (const [id, rp] of Object.entries(reg)) {
+    if (PROVIDERS[id] || PROVIDER_LABELS[id]) continue;
+    if (!rp.models.length) continue;
+    PROVIDERS[id] = makeDynamicProvider(rp);
+    PROVIDER_LABELS[id] = rp.name;
+    PROVIDER_ORDER.push(id);
+    added++;
+  }
+  PROVIDER_ORDER.sort((a, b) => {
+    const ai = BUILTIN_PROVIDERS.indexOf(a);
+    const bi = BUILTIN_PROVIDERS.indexOf(b);
+    if (ai >= 0 && bi >= 0) return ai - bi;
+    if (ai >= 0) return -1;
+    if (bi >= 0) return 1;
+    return String(a).localeCompare(String(b));
+  });
+  return added;
+}
+
+let registryPromise = null;
+
+/**
+ * Make sure the models.dev registry is available: reuse a fresh cache, else
+ * fetch once (background-friendly, never throws). Returns the number of
+ * providers currently merged.
+ * @param {boolean=} force  bypass the freshness check
+ * @returns {Promise<number>}
+ */
+function ensureRegistry(force = false) {
+  if (!force && isRegistryFresh()) return Promise.resolve(mergeRegistry());
+  if (!registryPromise) {
+    registryPromise = fetchRegistry().then((count) => {
+      registryPromise = null;
+      if (count) mergeRegistry();
+      return count;
+    });
+  }
+  return registryPromise;
+}
+
+// Merge whatever cache exists at boot (first run has none — ensureRegistry()
+// fetches it the first time the provider picker opens).
+mergeRegistry();
+
+class ProviderRouter {
+  constructor() {
+    this.providers = {};
+    this.active = null;
+  }
+
+  init(providerName) {
+    const config = loadConfig();
+    const name = providerName || config.provider || 'anthropic';
+    if (!PROVIDERS[name]) {
+      throw new Error(`Unknown provider: ${name}. Available: ${PROVIDER_ORDER.join(', ')}`);
+    }
+    return this.use(name);
+  }
+
+  // Transient switch: activate a provider without persisting anything to the
+  // config (the budget router swaps providers per turn; setModel() persists).
+  use(providerName) {
+    if (!PROVIDERS[providerName]) return null;
+    this.providers[providerName] = PROVIDERS[providerName];
+    this.active = { name: providerName, key: getApiKey(providerName) };
+    return this.active;
+  }
+
+  getChatFn() {
+    if (!this.active) this.init();
+    const active = this.active;
+    if (!active) throw new Error('No active provider');
+    return this.providers[active.name].chat;
+  }
+
+  getStreamFn() {
+    if (!this.active) this.init();
+    const active = this.active;
+    if (!active) throw new Error('No active provider');
+    return this.providers[active.name].stream;
+  }
+
+  getModels(providerName) {
+    const name = providerName || this.active?.name || 'anthropic';
+    if (!PROVIDERS[name]) return [];
+    return PROVIDERS[name].models || [];
+  }
+}
+
+// Look up model metadata (context window, $/1M token prices) for pricing/billing display.
+function getModelMeta(providerName, modelId) {
+  if (!providerName || !modelId) return null;
+  const list = (PROVIDERS[providerName] && PROVIDERS[providerName].models) || [];
+  return list.find((m) => m.id === modelId) || null;
+}
+
+module.exports = {
+  ProviderRouter, PROVIDERS, PROVIDER_ORDER, PROVIDER_LABELS, BUILTIN_PROVIDERS,
+  getModelMeta, ensureRegistry, mergeRegistry, envNamesFor,
+};

package/src/providers/local.js

@@ -0,0 +1,27 @@
+const { createOpenAICompatProvider } = require('./openai-compat');
+const { getApiKey } = require('../config/settings');
+
+function getKey() {
+  return getApiKey('local') || process.env.LOCAL_API_KEY || 'local';
+}
+
+const provider = {
+  ...createOpenAICompatProvider({
+    getKey,
+    providerId: 'local',
+    envKeyHint: 'LOCAL',
+  }),
+  models: [
+  { id: 'llama3.2', name: 'Llama 3.2 (local)', provider: 'local', tags: ['local'], context: 131072, priceIn: 0, priceOut: 0 },
+  { id: 'llama3.2:1b', name: 'Llama 3.2 1B (local)', provider: 'local', tags: ['local', 'small'], context: 131072, priceIn: 0, priceOut: 0 },
+  { id: 'mistral', name: 'Mistral 7B (local)', provider: 'local', tags: ['local'], context: 32768, priceIn: 0, priceOut: 0 },
+  { id: 'codellama', name: 'CodeLlama 7B (local)', provider: 'local', tags: ['local', 'coding'], context: 16384, priceIn: 0, priceOut: 0 },
+  { id: 'gemma2', name: 'Gemma 2 (local)', provider: 'local', tags: ['local'], context: 8192, priceIn: 0, priceOut: 0 },
+  { id: 'phi4', name: 'Phi-4 14B (local)', provider: 'local', tags: ['local'], context: 16384, priceIn: 0, priceOut: 0 },
+  { id: 'deepseek-coder', name: 'DeepSeek-Coder 6.7B (local)', provider: 'local', tags: ['local', 'coding'], context: 16384, priceIn: 0, priceOut: 0 },
+  { id: 'qwen2.5-coder', name: 'Qwen 2.5 Coder 14B (local)', provider: 'local', tags: ['local', 'coding'], context: 131072, priceIn: 0, priceOut: 0 },
+  { id: 'starcoder2', name: 'StarCoder2 7B (local)', provider: 'local', tags: ['local', 'coding'], context: 16384, priceIn: 0, priceOut: 0 },
+  ],
+};
+
+module.exports = provider;