@almightygpt/core 0.10.1 → 0.11.1

package/dist/index.js

@@ -12,7 +12,7 @@
  *   - review/     ✅ task #11 diff review pipeline (with #12/#13/#14 wiring)
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
-export const VERSION = "0.10.0";
+export const VERSION = "0.11.0";
 // MCP server (v0.9.0+) — exposes AlmightyGPT's review surface as MCP tools.
 export { startMcpServer } from "./mcp/server.js";
 // Git safety primitives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almightygpt/core",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Core orchestrator, adapters, config, runs, and review logic for AlmightyGPT",
   "license": "MIT",
   "type": "module",

package/src/adapters/claude.ts

@@ -75,6 +75,14 @@ export class ClaudeAdapter implements Adapter {
     const opts = this.explicitApiKey ? { explicit: this.explicitApiKey } : {};
     const result = await resolveApiKey("anthropic", opts);
     if (result.source === "missing") return null;
+    if (result.source === "keychain_error") {
+      throw new AdapterError(
+        `Keychain read failed for Anthropic: ${result.keychainError ?? "unknown error"}. ` +
+          "Set ANTHROPIC_API_KEY in your environment to override, or fix the " +
+          "keychain state.",
+        this.name,
+      );
+    }
     this.client = new Anthropic({ apiKey: result.key! });
     return this.client;
   }

package/src/adapters/defaults.ts

@@ -31,6 +31,9 @@ export const DEFAULT_MODELS: Record<ProviderId, string> = {
   openai: "gpt-4o",
   anthropic: "claude-sonnet-4-6",
   google: "gemini-2.5-flash",
+  // v0.12.0+ — meta-providers
+  openrouter: "deepseek/deepseek-chat",
+  ollama: "llama3.3:70b",
 };
 
 /**
@@ -41,4 +44,6 @@ export const PROVIDER_PRETTY_NAME: Record<ProviderId, string> = {
   openai: "OpenAI",
   anthropic: "Anthropic",
   google: "Google",
+  openrouter: "OpenRouter",
+  ollama: "Ollama (local)",
 };

package/src/adapters/factory.ts

@@ -12,6 +12,8 @@ import { MockAdapter } from "./mock.js";
 import { OpenAIAdapter } from "./openai.js";
 import { ClaudeAdapter } from "./claude.js";
 import { GeminiAdapter } from "./gemini.js";
+import { OpenRouterAdapter } from "./openrouter.js";
+import { OllamaAdapter } from "./ollama.js";
 
 export function makeAdapter(name: string, provider: string): Adapter {
   switch (provider) {
@@ -21,12 +23,16 @@ export function makeAdapter(name: string, provider: string): Adapter {
       return new ClaudeAdapter(name);
     case "google":
       return new GeminiAdapter(name);
+    case "openrouter":
+      return new OpenRouterAdapter(name);
+    case "ollama":
+      return new OllamaAdapter(name);
     case "mock":
       return new MockAdapter();
     default:
       throw new Error(
         `Provider "${provider}" not supported. ` +
-          `Use "openai", "anthropic", "google", or "mock".`,
+          `Use "openai", "anthropic", "google", "openrouter", "ollama", or "mock".`,
       );
   }
 }
@@ -39,6 +45,10 @@ export function envHintForProvider(provider: string): string {
       return "Export ANTHROPIC_API_KEY in your environment.";
     case "google":
       return "Export GOOGLE_API_KEY (or GEMINI_API_KEY) in your environment.";
+    case "openrouter":
+      return "Export OPENROUTER_API_KEY in your environment.";
+    case "ollama":
+      return "Install Ollama (https://ollama.ai) and run `ollama serve` locally.";
     default:
       return "";
   }

package/src/adapters/gemini.ts

@@ -88,6 +88,14 @@ export class GeminiAdapter implements Adapter {
     const opts = this.explicitApiKey ? { explicit: this.explicitApiKey } : {};
     const result = await resolveApiKey("google", opts);
     if (result.source === "missing") return null;
+    if (result.source === "keychain_error") {
+      throw new AdapterError(
+        `Keychain read failed for Google: ${result.keychainError ?? "unknown error"}. ` +
+          "Set GOOGLE_API_KEY (or GEMINI_API_KEY) in your environment to " +
+          "override, or fix the keychain state.",
+        this.name,
+      );
+    }
     this.client = new GoogleGenerativeAI(result.key!);
     return this.client;
   }

package/src/adapters/index.ts

@@ -1,11 +1,13 @@
 /**
  * Adapter exports.
  *
- * Add new adapters here as they're implemented:
- *   - Claude (Anthropic) — task #15
- *   - Gemini — post-MVP 1
- *   - OpenRouter — post-MVP 1 (for cost-conscious users; see
- *     docs/claude/competitor-ai-council.md)
+ * Currently shipped adapters:
+ *   - OpenAI (gpt-4o family)
+ *   - Anthropic (Claude Sonnet 4.x family)
+ *   - Google (Gemini 2.5 family)
+ *   - OpenRouter — v0.12.0+, meta-provider unlocking 100+ models
+ *   - Ollama — v0.12.0+, local models, no cloud calls
+ *   - Mock — for testing without API keys
  */
 
 export type {
@@ -19,3 +21,5 @@ export { MockAdapter } from "./mock.js";
 export { OpenAIAdapter, type OpenAIAdapterOptions } from "./openai.js";
 export { ClaudeAdapter, type ClaudeAdapterOptions } from "./claude.js";
 export { GeminiAdapter, type GeminiAdapterOptions } from "./gemini.js";
+export { OpenRouterAdapter, type OpenRouterAdapterOptions } from "./openrouter.js";
+export { OllamaAdapter, type OllamaAdapterOptions } from "./ollama.js";

package/src/adapters/ollama.ts

@@ -0,0 +1,157 @@
+/**
+ * Ollama adapter (v0.12.0+).
+ *
+ * Ollama runs LLMs locally — no cloud calls, no API key, code never
+ * leaves the machine. Opens AlmightyGPT to regulated / government /
+ * air-gapped enterprise users who can't use cloud AI but want the
+ * Worker/Reviewer convention.
+ *
+ * Ollama exposes an OpenAI-compatible API at http://localhost:11434/v1,
+ * so this adapter is a thin wrapper around the OpenAI SDK with a
+ * custom baseURL.
+ *
+ * Requires the user to have Ollama installed + running locally. See
+ * https://ollama.ai. The adapter does NOT install Ollama or pull
+ * models — that's the user's setup step.
+ *
+ * Default model: llama3.3:70b (large, very capable for code review).
+ * Users with smaller machines should override via config:
+ *   - llama3.2:3b           (3B parameter, runs on most laptops)
+ *   - qwen2.5-coder:7b      (7B, code-tuned, decent for review)
+ *   - qwen2.5-coder:32b     (32B, much stronger for code, needs ~24GB RAM)
+ *   - deepseek-r1:14b       (14B, reasoning-tuned)
+ *
+ * No auth, no API key, no pricing — local model.
+ */
+
+import OpenAI from "openai";
+import { AdapterError, type Adapter, type AdapterInput, type AdapterOutput } from "./types.js";
+import { DEFAULT_MODELS } from "./defaults.js";
+
+const DEFAULT_BASE_URL = "http://localhost:11434/v1";
+const DEFAULT_MODEL = DEFAULT_MODELS.ollama;
+
+export interface OllamaAdapterOptions {
+  /** Override the local Ollama base URL. Defaults to http://localhost:11434/v1. */
+  baseUrl?: string;
+  defaultModel?: string;
+  defaultMaxOutputTokens?: number;
+  defaultTimeoutMs?: number;
+}
+
+export class OllamaAdapter implements Adapter {
+  readonly name: string;
+  readonly provider = "ollama";
+
+  private readonly client: OpenAI;
+  readonly defaultModel: string;
+  private readonly defaultMaxOutputTokens: number;
+  private readonly defaultTimeoutMs: number;
+  private readonly baseUrl: string;
+
+  constructor(name = "ollama", options: OllamaAdapterOptions = {}) {
+    this.name = name;
+    this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+    // Larger default — local models often run slower than cloud, and
+    // shorter responses are rarely the bottleneck.
+    this.defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? 8192;
+    // Longer default — large local models can take 30-90s on CPU/GPU.
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? 300_000;
+    this.baseUrl =
+      options.baseUrl ?? process.env["OLLAMA_BASE_URL"] ?? DEFAULT_BASE_URL;
+
+    // OpenAI SDK requires SOMETHING for apiKey even when the server
+    // doesn't validate it. "ollama" is the documented sentinel.
+    this.client = new OpenAI({
+      apiKey: "ollama",
+      baseURL: this.baseUrl,
+    });
+  }
+
+  /** Ollama is "available" if the local daemon responds. */
+  async isAvailable(): Promise<boolean> {
+    try {
+      // Cheap probe — Ollama's /api/tags lists local models. If the
+      // daemon isn't running, this throws / times out fast.
+      const probeUrl = this.baseUrl.replace(/\/v1\/?$/, "") + "/api/tags";
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 2000);
+      try {
+        const res = await fetch(probeUrl, { signal: controller.signal });
+        return res.ok;
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch {
+      return false;
+    }
+  }
+
+  async execute(input: AdapterInput): Promise<AdapterOutput> {
+    const model = input.model ?? this.defaultModel;
+    const maxOutputTokens = input.maxOutputTokens ?? this.defaultMaxOutputTokens;
+    const timeoutMs = input.timeoutMs ?? this.defaultTimeoutMs;
+
+    const start = Date.now();
+    let response: OpenAI.Chat.Completions.ChatCompletion;
+    try {
+      response = await this.client.chat.completions.create(
+        {
+          model,
+          max_tokens: maxOutputTokens,
+          messages: [
+            { role: "system", content: input.systemPrompt },
+            { role: "user", content: input.userMessage },
+          ],
+        },
+        { timeout: timeoutMs },
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // Common failure: Ollama daemon isn't running.
+      if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
+        throw new AdapterError(
+          `Ollama daemon unreachable at ${this.baseUrl}. ` +
+            "Is Ollama installed and running? Try `ollama serve` or " +
+            "open the Ollama app.",
+          this.name,
+          err,
+        );
+      }
+      // Common failure: model not pulled locally.
+      if (message.includes("model") && message.includes("not found")) {
+        throw new AdapterError(
+          `Ollama model "${model}" not found locally. Pull it first: ` +
+            `\`ollama pull ${model}\``,
+          this.name,
+          err,
+        );
+      }
+      throw new AdapterError(
+        `Ollama call failed: ${message}`,
+        this.name,
+        err,
+      );
+    }
+
+    const choice = response.choices[0];
+    if (!choice || !choice.message.content) {
+      throw new AdapterError(
+        "Ollama returned an empty response.",
+        this.name,
+      );
+    }
+
+    return {
+      content: choice.message.content,
+      tokensIn: response.usage?.prompt_tokens ?? 0,
+      cachedTokensIn: 0,
+      tokensOut: response.usage?.completion_tokens ?? 0,
+      // Local models are $0. Always.
+      costUsd: 0,
+      latencyMs: Date.now() - start,
+      modelUsed: response.model ?? model,
+      provider: this.provider,
+    };
+  }
+}

package/src/adapters/openai.ts

@@ -72,6 +72,17 @@ export class OpenAIAdapter implements Adapter {
     const opts = this.explicitApiKey ? { explicit: this.explicitApiKey } : {};
     const result = await resolveApiKey("openai", opts);
     if (result.source === "missing") return null;
+    // v0.12.1 (per Codex): if the keychain entry exists but the OS
+    // denied / failed the read, surface that diagnostic — don't
+    // construct a client with an undefined key.
+    if (result.source === "keychain_error") {
+      throw new AdapterError(
+        `Keychain read failed for OpenAI: ${result.keychainError ?? "unknown error"}. ` +
+          "Set OPENAI_API_KEY in your environment to override, or fix the " +
+          "keychain state.",
+        this.name,
+      );
+    }
     this.client = new OpenAI({
       apiKey: result.key!,
       ...(this.organization ? { organization: this.organization } : {}),

package/src/adapters/openrouter.ts

@@ -0,0 +1,202 @@
+/**
+ * OpenRouter adapter (v0.12.0+).
+ *
+ * OpenRouter is a meta-provider that fronts 100+ models behind a single
+ * OpenAI-compatible API. Adding it unlocks DeepSeek, Mistral, Codestral,
+ * Llama (hosted), Grok, Qwen, and many others without us shipping one
+ * adapter per provider.
+ *
+ * Reads OPENROUTER_API_KEY from the environment (resolver: explicit →
+ * env → keychain → missing).
+ *
+ * Default model: deepseek/deepseek-chat — cheap, capable, popular OR
+ * pick. Users override via the `model` field in their config's agents
+ * map, e.g. `model: "anthropic/claude-haiku-4-5"`.
+ *
+ * Model naming: `<provider>/<model>` as required by OpenRouter
+ * (e.g. `deepseek/deepseek-chat`, `meta-llama/llama-3.3-70b-instruct`).
+ *
+ * Pricing: passed through from OpenRouter's response. Their `usage`
+ * object includes a `cost` field (USD) when available; otherwise we
+ * estimate from a small pricing table for popular models.
+ */
+
+import OpenAI from "openai";
+import { AdapterError, type Adapter, type AdapterInput, type AdapterOutput } from "./types.js";
+import { resolveApiKey } from "../auth/resolver.js";
+import { DEFAULT_MODELS } from "./defaults.js";
+
+const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+
+/**
+ * Fallback pricing for popular OpenRouter models in case the API doesn't
+ * return cost. USD per 1M tokens. Match by prefix (startsWith).
+ *
+ * Source: https://openrouter.ai/models (verify periodically).
+ */
+const PRICING_USD_PER_1M: Record<string, { input: number; output: number }> = {
+  "deepseek/deepseek-chat": { input: 0.27, output: 1.1 },
+  "deepseek/deepseek-coder": { input: 0.27, output: 1.1 },
+  "anthropic/claude-haiku-4-5": { input: 1.0, output: 5.0 },
+  "anthropic/claude-sonnet-4-6": { input: 3.0, output: 15.0 },
+  "openai/gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "openai/gpt-4o": { input: 2.5, output: 10.0 },
+  "meta-llama/llama-3.3-70b-instruct": { input: 0.59, output: 0.79 },
+  "qwen/qwen-2.5-coder-32b-instruct": { input: 0.07, output: 0.16 },
+  "mistralai/codestral-2508": { input: 0.3, output: 0.9 },
+  "x-ai/grok-2": { input: 2.0, output: 10.0 },
+};
+
+const DEFAULT_MODEL = DEFAULT_MODELS.openrouter;
+
+export interface OpenRouterAdapterOptions {
+  apiKey?: string;
+  defaultModel?: string;
+  defaultMaxOutputTokens?: number;
+  defaultTimeoutMs?: number;
+  /** Optional HTTP-Referer for OR's stats / leaderboards. */
+  appUrl?: string;
+  /** Optional X-Title for OR's stats / leaderboards. */
+  appTitle?: string;
+}
+
+export class OpenRouterAdapter implements Adapter {
+  readonly name: string;
+  readonly provider = "openrouter";
+
+  private client: OpenAI | null = null;
+  private resolved = false;
+  private readonly explicitApiKey: string | undefined;
+  private readonly appUrl: string | undefined;
+  private readonly appTitle: string | undefined;
+  readonly defaultModel: string;
+  private readonly defaultMaxOutputTokens: number;
+  private readonly defaultTimeoutMs: number;
+
+  constructor(name = "openrouter", options: OpenRouterAdapterOptions = {}) {
+    this.name = name;
+    this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+    this.defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? 4096;
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? 120_000;
+    this.explicitApiKey = options.apiKey;
+    this.appUrl = options.appUrl ?? "https://github.com/roxjayanath/almightygpt";
+    this.appTitle = options.appTitle ?? "AlmightyGPT";
+  }
+
+  private async ensureClient(): Promise<OpenAI | null> {
+    if (this.resolved) return this.client;
+    this.resolved = true;
+    const opts = this.explicitApiKey ? { explicit: this.explicitApiKey } : {};
+    const result = await resolveApiKey("openrouter", opts);
+    if (result.source === "missing") return null;
+    if (result.source === "keychain_error") {
+      throw new AdapterError(
+        `Keychain read failed for OpenRouter: ${result.keychainError ?? "unknown error"}. ` +
+          "Set OPENROUTER_API_KEY in your environment to override, or fix the " +
+          "keychain state.",
+        this.name,
+      );
+    }
+    this.client = new OpenAI({
+      apiKey: result.key!,
+      baseURL: OPENROUTER_BASE_URL,
+      defaultHeaders: {
+        ...(this.appUrl ? { "HTTP-Referer": this.appUrl } : {}),
+        ...(this.appTitle ? { "X-Title": this.appTitle } : {}),
+      },
+    });
+    return this.client;
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return (await this.ensureClient()) !== null;
+  }
+
+  async execute(input: AdapterInput): Promise<AdapterOutput> {
+    const client = await this.ensureClient();
+    if (!client) {
+      throw new AdapterError(
+        'No OpenRouter API key found. Run "almightygpt auth openrouter" ' +
+          "or export OPENROUTER_API_KEY in your environment.",
+        this.name,
+      );
+    }
+
+    const model = input.model ?? this.defaultModel;
+    const maxOutputTokens = input.maxOutputTokens ?? this.defaultMaxOutputTokens;
+    const timeoutMs = input.timeoutMs ?? this.defaultTimeoutMs;
+
+    const start = Date.now();
+    let response: OpenAI.Chat.Completions.ChatCompletion;
+    try {
+      response = await client.chat.completions.create(
+        {
+          model,
+          max_tokens: maxOutputTokens,
+          messages: [
+            { role: "system", content: input.systemPrompt },
+            { role: "user", content: input.userMessage },
+          ],
+          ...(input.responseFormat === "json_object"
+            ? { response_format: { type: "json_object" } }
+            : {}),
+        },
+        { timeout: timeoutMs },
+      );
+    } catch (err) {
+      throw new AdapterError(
+        `OpenRouter call failed: ${err instanceof Error ? err.message : String(err)}`,
+        this.name,
+        err,
+      );
+    }
+
+    const choice = response.choices[0];
+    if (!choice || !choice.message.content) {
+      throw new AdapterError(
+        "OpenRouter returned an empty response.",
+        this.name,
+      );
+    }
+
+    const content = choice.message.content;
+    const usage = response.usage as
+      | (typeof response.usage & {
+          /** OpenRouter returns the actual cost in USD when available. */
+          cost?: number;
+        })
+      | undefined;
+    const tokensIn = usage?.prompt_tokens ?? 0;
+    const tokensOut = usage?.completion_tokens ?? 0;
+    // Prefer OR's reported cost (real, billed); fall back to estimate.
+    const costUsd =
+      typeof usage?.cost === "number"
+        ? usage.cost
+        : estimateCostUsd(model, tokensIn, tokensOut);
+
+    return {
+      content,
+      tokensIn,
+      cachedTokensIn: 0,
+      tokensOut,
+      costUsd,
+      latencyMs: Date.now() - start,
+      modelUsed: response.model ?? model,
+      provider: this.provider,
+    };
+  }
+}
+
+function estimateCostUsd(
+  model: string,
+  tokensIn: number,
+  tokensOut: number,
+): number {
+  const key = Object.keys(PRICING_USD_PER_1M).find((k) =>
+    model.toLowerCase().startsWith(k),
+  );
+  if (!key) return 0;
+  const rates = PRICING_USD_PER_1M[key];
+  if (!rates) return 0;
+  return (tokensIn / 1_000_000) * rates.input + (tokensOut / 1_000_000) * rates.output;
+}

package/src/auth/__tests__/resolver.test.ts

@@ -25,6 +25,8 @@ const PROVIDER_ENV_VAR = {
   openai: "OPENAI_API_KEY",
   anthropic: "ANTHROPIC_API_KEY",
   google: "GOOGLE_API_KEY",
+  openrouter: "OPENROUTER_API_KEY", // added v0.12.0
+  // ollama has no env var (local, no auth)
 } as const;
 
 function makeKeychainStub(behavior: {
@@ -168,6 +170,28 @@ describe("resolveApiKey — priority order", () => {
     expect(r.key).toBe("primary");
   });
 
+  it("OpenRouter provider reads OPENROUTER_API_KEY (v0.12.0+)", async () => {
+    process.env.OPENROUTER_API_KEY = "from-or";
+    vi.mocked(getKeychain).mockResolvedValue(
+      makeKeychainStub({ available: false }),
+    );
+    const r = await resolveApiKey("openrouter");
+    expect(r.source).toBe("env");
+    expect(r.key).toBe("from-or");
+    expect(r.envVar).toBe("OPENROUTER_API_KEY");
+  });
+
+  it("Ollama has no env vars and falls straight to keychain → missing", async () => {
+    vi.mocked(getKeychain).mockResolvedValue(
+      makeKeychainStub({ available: true }),
+    );
+    // Ollama has no API key — PROVIDER_ENV_VARS["ollama"] is empty.
+    // The resolver should skip the env loop entirely and check
+    // keychain → return "missing" since the keychain stub is empty.
+    const r = await resolveApiKey("ollama");
+    expect(r.source).toBe("missing");
+  });
+
   it("empty env var is treated as not set (falls through to keychain)", async () => {
     process.env.OPENAI_API_KEY = "";
     vi.mocked(getKeychain).mockResolvedValue(

package/src/auth/types.ts

@@ -17,7 +17,13 @@
  * a stale keychain copy. See docs/claude/v0.8-auth-plan.md.
  */
 
-export type ProviderId = "openai" | "anthropic" | "google";
+export type ProviderId =
+  | "openai"
+  | "anthropic"
+  | "google"
+  // v0.12.0+ meta-providers
+  | "openrouter"
+  | "ollama";
 
 /**
  * Where a resolved API key came from.
@@ -74,6 +80,11 @@ export const PROVIDER_ENV_VARS: Record<ProviderId, readonly string[]> = {
   anthropic: ["ANTHROPIC_API_KEY"],
   // Google's SDK historically accepted both names; honor both.
   google: ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+  openrouter: ["OPENROUTER_API_KEY"],
+  // Ollama is local — no key. The empty list signals "no auth"
+  // to the resolver (it just falls through to keychain → missing,
+  // and the Ollama adapter bypasses the resolver entirely).
+  ollama: [],
 };
 
 /**
@@ -84,4 +95,7 @@ export const PROVIDER_KEY_URLS: Record<ProviderId, string> = {
   openai: "https://platform.openai.com/api-keys",
   anthropic: "https://console.anthropic.com/settings/keys",
   google: "https://aistudio.google.com/apikey",
+  openrouter: "https://openrouter.ai/keys",
+  // Ollama is local — no keys page. Linked instead to install docs.
+  ollama: "https://ollama.ai/download",
 };