@almightygpt/core 0.10.1 → 0.11.0

package/src/adapters/openrouter.ts

@@ -0,0 +1,194 @@
+/**
+ * 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;
+    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",
 };

package/src/auth/validator.ts

@@ -72,6 +72,20 @@ export async function validateKey(
       case "google":
         result = await validateGoogle(key);
         break;
+      case "openrouter":
+        result = await validateOpenRouter(key);
+        break;
+      case "ollama":
+        // Ollama has no key — "validation" means probing the local
+        // daemon. The key arg is ignored.
+        result = await validateOllama();
+        break;
+      default: {
+        // Exhaustiveness check — TypeScript will error here if a new
+        // ProviderId is added without a switch case.
+        const _exhaustive: never = provider;
+        throw new Error(`Unknown provider: ${String(_exhaustive)}`);
+      }
     }
     result.latencyMs = Date.now() - start;
     return result;
@@ -187,6 +201,76 @@ async function validateGoogle(key: string): Promise<ValidationResult> {
   }
 }
 
+async function validateOpenRouter(key: string): Promise<ValidationResult> {
+  // OpenRouter is OpenAI-compatible at https://openrouter.ai/api/v1.
+  // Same chat-completions shape — point fetch at OR's base URL.
+  const model = DEFAULT_MODELS.openrouter;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
+  try {
+    const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+        "HTTP-Referer": "https://github.com/roxjayanath/almightygpt",
+        "X-Title": "AlmightyGPT validation",
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: "hi" }],
+        max_tokens: 1,
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const rawBody = await res.text().catch(() => "");
+      return {
+        ok: false,
+        statusCode: res.status,
+        error: normalizeOpenRouterError(res.status, rawBody, key),
+        rawBody,
+      };
+    }
+    const data = (await res.json()) as { model?: string };
+    return { ok: true, model: data.model ?? model };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function validateOllama(): Promise<ValidationResult> {
+  // No key. Probe the local daemon at /api/tags — cheap, no model
+  // invocation. If the user has Ollama running, this confirms the
+  // adapter can reach it. Doesn't confirm the default model is
+  // pulled — that surfaces on the first real call.
+  const baseUrl = process.env["OLLAMA_BASE_URL"] ?? "http://localhost:11434";
+  const probeUrl = baseUrl.replace(/\/v1\/?$/, "") + "/api/tags";
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 3000);
+  try {
+    const res = await fetch(probeUrl, { signal: controller.signal });
+    if (!res.ok) {
+      return {
+        ok: false,
+        statusCode: res.status,
+        error: `[${res.status}] Ollama daemon at ${baseUrl} responded with an error.`,
+      };
+    }
+    return { ok: true, model: DEFAULT_MODELS.ollama };
+  } catch (err) {
+    return {
+      ok: false,
+      error:
+        `Ollama daemon unreachable at ${baseUrl}. Is Ollama installed ` +
+        `and running? Try \`ollama serve\` or open the Ollama app.`,
+      rawBody: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // ─── Error normalization (Codex v0.8 P2 #6) ──────────────────────────
 //
 // Parse known provider JSON error shapes into short, user-safe messages.
@@ -258,6 +342,28 @@ function redactKey(msg: string, key: string): string {
   return msg.split(key).join("<redacted-key>");
 }
 
+function normalizeOpenRouterError(
+  status: number,
+  rawBody: string,
+  submittedKey: string,
+): string {
+  // OpenRouter forwards provider errors but wraps them; shape is
+  // typically { "error": { "message": "...", "code": N } }.
+  try {
+    const parsed = JSON.parse(rawBody) as {
+      error?: { message?: string; code?: number };
+    };
+    let msg = parsed.error?.message ?? "";
+    if (submittedKey && msg.includes(submittedKey)) {
+      msg = msg.replace(submittedKey, "<redacted-key>");
+    }
+    if (msg) return `[${status}] OpenRouter: ${truncate(msg, 200)}`;
+  } catch {
+    /* fall through */
+  }
+  return statusOnlyMessage("OpenRouter", status);
+}
+
 function statusOnlyMessage(provider: string, status: number): string {
   if (status === 401 || status === 403) {
     return `[${status}] ${provider} rejected the key (unauthorized).`;

package/src/config/schema.ts

@@ -13,7 +13,14 @@ export const AgentRoleSchema = z.enum(["worker", "reviewer", "both", "optional"]
 export const AgentConfigSchema = z
   .object({
     enabled: z.boolean().default(true),
-    provider: z.enum(["openai", "anthropic", "google", "mock"]),
+    provider: z.enum([
+      "openai",
+      "anthropic",
+      "google",
+      "openrouter",
+      "ollama",
+      "mock",
+    ]),
     mode: z.enum(["api", "cli"]).default("api"),
     role: AgentRoleSchema.default("optional"),
     memoryFile: z.string().min(1),

package/src/index.ts

@@ -13,7 +13,7 @@
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
 
-export const VERSION = "0.10.1";
+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";