@almightygpt/core 0.10.0 → 0.11.0

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/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__/keychain.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Keychain adapter tests.
+ *
+ * Strategy (addresses Codex's v0.8 plan-review R3 — "KeychainAdapter
+ * dependency injection"): we mock the dynamic import of
+ * `@napi-rs/keyring` itself, replacing the Entry class with a fake
+ * we control per test. This sidesteps needing to refactor the real
+ * code to accept an injected adapter — the dynamic-import boundary
+ * IS the seam we test against.
+ *
+ * Codex's main concern (P2 #4) was that read failures were silently
+ * converted into "absent". These tests prove the new behavior:
+ *   - found    → { kind: "found", key }
+ *   - absent   → { kind: "absent" }
+ *   - throws   → { kind: "error", message }  (was: silently dropped)
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { _resetKeychainCache } from "../keychain.js";
+
+// Track the entry methods per test so we can rewire mid-suite.
+let mockGetPassword: () => string | null;
+let mockSetPassword: (key: string) => void;
+let mockDeletePassword: () => boolean;
+let constructorThrows = false;
+let importThrows = false;
+
+vi.mock("@napi-rs/keyring", () => ({
+  get Entry() {
+    if (importThrows) throw new Error("synthetic import failure");
+    return class FakeEntry {
+      constructor(_service: string, _account: string) {
+        if (constructorThrows) {
+          throw new Error("native binding refused to initialize");
+        }
+      }
+      getPassword() {
+        return mockGetPassword();
+      }
+      setPassword(p: string) {
+        mockSetPassword(p);
+      }
+      deletePassword() {
+        return mockDeletePassword();
+      }
+    };
+  },
+}));
+
+import { getKeychain } from "../keychain.js";
+
+beforeEach(() => {
+  _resetKeychainCache();
+  mockGetPassword = () => null;
+  mockSetPassword = () => {};
+  mockDeletePassword = () => true;
+  constructorThrows = false;
+  importThrows = false;
+});
+
+describe("keychain adapter — availability", () => {
+  it("reports available=true when native binding loads cleanly", async () => {
+    const kc = await getKeychain();
+    expect(kc.available).toBe(true);
+    expect(kc.describeBackend()).not.toContain("unavailable");
+  });
+
+  it("reports available=false + reason when native binding throws on init", async () => {
+    constructorThrows = true;
+    const kc = await getKeychain();
+    expect(kc.available).toBe(false);
+    expect(kc.describeBackend()).toContain("unavailable");
+    expect(kc.describeBackend()).toMatch(/initialize|native/i);
+  });
+
+  it("get on unavailable adapter returns { kind: 'absent' } (not throw)", async () => {
+    constructorThrows = true;
+    const kc = await getKeychain();
+    const r = await kc.get("openai");
+    expect(r).toEqual({ kind: "absent" });
+  });
+
+  it("set on unavailable adapter throws with a clear hint", async () => {
+    constructorThrows = true;
+    const kc = await getKeychain();
+    await expect(kc.set("openai", "x")).rejects.toThrow(/unavailable|environment/i);
+  });
+});
+
+describe("keychain adapter — get behavior (Codex P2 #4 regression coverage)", () => {
+  it("found path returns { kind: 'found', key }", async () => {
+    mockGetPassword = () => "stored-secret";
+    const kc = await getKeychain();
+    const r = await kc.get("anthropic");
+    expect(r).toEqual({ kind: "found", key: "stored-secret" });
+  });
+
+  it("absent path returns { kind: 'absent' } when getPassword returns null", async () => {
+    mockGetPassword = () => null;
+    const kc = await getKeychain();
+    const r = await kc.get("openai");
+    expect(r).toEqual({ kind: "absent" });
+  });
+
+  it("error path returns { kind: 'error', message } when getPassword throws — NOT silently absent", async () => {
+    mockGetPassword = () => {
+      throw new Error("keyring locked by OS");
+    };
+    const kc = await getKeychain();
+    const r = await kc.get("openai");
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") {
+      expect(r.message).toContain("keyring locked");
+    }
+  });
+
+  it("error path preserves non-Error throws via String(err)", async () => {
+    mockGetPassword = () => {
+      throw "raw string error";
+    };
+    const kc = await getKeychain();
+    const r = await kc.get("openai");
+    expect(r.kind).toBe("error");
+    if (r.kind === "error") {
+      expect(r.message).toContain("raw string error");
+    }
+  });
+});
+
+describe("keychain adapter — set / remove", () => {
+  it("set forwards the key to the underlying Entry", async () => {
+    const writes: string[] = [];
+    mockSetPassword = (p) => writes.push(p);
+    const kc = await getKeychain();
+    await kc.set("google", "new-key");
+    expect(writes).toEqual(["new-key"]);
+  });
+
+  it("remove returns true when entry existed", async () => {
+    mockDeletePassword = () => true;
+    const kc = await getKeychain();
+    const removed = await kc.remove("openai");
+    expect(removed).toBe(true);
+  });
+
+  it("remove returns false (not throws) when entry didn't exist", async () => {
+    mockDeletePassword = () => {
+      throw new Error("not found");
+    };
+    const kc = await getKeychain();
+    const removed = await kc.remove("openai");
+    expect(removed).toBe(false);
+  });
+});
+
+describe("keychain adapter — caching", () => {
+  it("getKeychain returns the same instance across calls (singleton)", async () => {
+    const a = await getKeychain();
+    const b = await getKeychain();
+    expect(a).toBe(b);
+  });
+
+  it("_resetKeychainCache forces a fresh load on next getKeychain", async () => {
+    const a = await getKeychain();
+    _resetKeychainCache();
+    constructorThrows = true; // change behavior between loads
+    const b = await getKeychain();
+    expect(a.available).toBe(true);
+    expect(b.available).toBe(false);
+  });
+});