@almightygpt/core 0.2.0

package/src/adapters/gemini.ts

@@ -0,0 +1,183 @@
+/**
+ * Google / Gemini adapter — third real provider.
+ *
+ * Reads GOOGLE_API_KEY (or GEMINI_API_KEY as a fallback) from the
+ * environment. Never stores or logs the key.
+ *
+ * Default model: gemini-2.5-pro. Configurable per-call. Earlier
+ * gemini-1.5-* models have been retired from the v1beta API as of
+ * late 2025/early 2026.
+ *
+ * Pricing (USD per 1M tokens, approximate as of 2026-05):
+ *   gemini-2.5-pro:    1.25 in / 10.00 out
+ *   gemini-2.5-flash:  0.30 in / 2.50 out
+ *   gemini-2.0-flash:  0.10 in / 0.40 out
+ *   gemini-3.x-*:      pricing TBD — falls back to conservative defaults
+ *
+ * Pricing changes frequently — verify at ai.google.dev/pricing if cost
+ * accuracy matters for a given run.
+ *
+ * Note on system prompts: the @google/generative-ai SDK accepts a
+ * `systemInstruction` field on getGenerativeModel(). We use that
+ * instead of stitching system text into the user message.
+ */
+
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import {
+  AdapterError,
+  type Adapter,
+  type AdapterInput,
+  type AdapterOutput,
+} from "./types.js";
+
+const PRICING_USD_PER_1M: Record<string, { input: number; output: number }> = {
+  "gemini-2.5-pro": { input: 1.25, output: 10.0 },
+  "gemini-2.5-flash": { input: 0.3, output: 2.5 },
+  "gemini-2.0-flash": { input: 0.1, output: 0.4 },
+  // Older models kept for reproducibility on saved runs:
+  "gemini-1.5-pro": { input: 1.25, output: 5.0 },
+  "gemini-1.5-flash": { input: 0.075, output: 0.3 },
+};
+
+// Defaulting to flash, not pro, because Google's free tier typically has
+// zero quota on the pro models but allows real usage on flash. Users with
+// paid billing can override via the `model` field in config.yaml (when that
+// field lands in v0.3) or by constructing the adapter directly. For code
+// review of typical-sized diffs, flash quality is sufficient — pro pays for
+// itself only on very large diffs or complex reasoning chains.
+const DEFAULT_MODEL = "gemini-2.5-flash";
+
+export interface GeminiAdapterOptions {
+  apiKey?: string;
+  defaultModel?: string;
+  defaultMaxOutputTokens?: number;
+  defaultTimeoutMs?: number;
+}
+
+export class GeminiAdapter implements Adapter {
+  readonly name: string;
+  readonly provider = "google";
+
+  private readonly client: GoogleGenerativeAI | null;
+  private readonly defaultModel: string;
+  private readonly defaultMaxOutputTokens: number;
+  private readonly defaultTimeoutMs: number;
+
+  constructor(name = "gemini", options: GeminiAdapterOptions = {}) {
+    this.name = name;
+    this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+    // Bigger than other adapters by design: gemini-2.5-* spends a portion
+    // of the output budget on internal "thinking" tokens before producing
+    // visible output. 8192 leaves ~4-6k for the actual response after the
+    // model finishes its reasoning. We also disable thinking explicitly
+    // below to make sure the visible response gets the full budget.
+    this.defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? 8192;
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? 120_000;
+
+    const apiKey =
+      options.apiKey ??
+      process.env["GOOGLE_API_KEY"] ??
+      process.env["GEMINI_API_KEY"];
+    this.client = apiKey ? new GoogleGenerativeAI(apiKey) : null;
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.client !== null;
+  }
+
+  async execute(input: AdapterInput): Promise<AdapterOutput> {
+    if (!this.client) {
+      throw new AdapterError(
+        "GOOGLE_API_KEY (or GEMINI_API_KEY) is not set. " +
+          "Export one in your environment.",
+        this.name,
+      );
+    }
+
+    const model = input.model ?? this.defaultModel;
+    const maxOutputTokens = input.maxOutputTokens ?? this.defaultMaxOutputTokens;
+    const timeoutMs = input.timeoutMs ?? this.defaultTimeoutMs;
+
+    // gemini-2.5-* "thinks" before responding. Without an explicit cap the
+    // model can consume most/all of maxOutputTokens on internal reasoning
+    // tokens, leaving the user-facing response truncated mid-sentence. We
+    // pass thinkingConfig via a type-relaxed cast because @google/generative-ai
+    // 0.21 doesn't declare it on GenerationConfig yet, but the v1beta REST
+    // API accepts it.
+    const generationConfig: Record<string, unknown> = {
+      maxOutputTokens,
+      thinkingConfig: { thinkingBudget: 0 },
+    };
+    if (input.responseFormat === "json_object") {
+      generationConfig["responseMimeType"] = "application/json";
+    }
+
+    const generative = this.client.getGenerativeModel({
+      model,
+      systemInstruction: input.systemPrompt,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      generationConfig: generationConfig as any,
+    });
+
+    const start = Date.now();
+    let response;
+    try {
+      // The SDK doesn't expose a per-call timeout option, so we race manually.
+      response = await Promise.race([
+        generative.generateContent(input.userMessage),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () =>
+              reject(
+                new Error(`Gemini call exceeded timeout of ${timeoutMs}ms`),
+              ),
+            timeoutMs,
+          ),
+        ),
+      ]);
+    } catch (err) {
+      throw new AdapterError(
+        `Gemini call failed: ${err instanceof Error ? err.message : String(err)}`,
+        this.name,
+        err,
+      );
+    }
+
+    const content = response.response.text();
+    if (!content) {
+      throw new AdapterError(
+        "Gemini returned no text content (filtered, empty, or tool-only response).",
+        this.name,
+      );
+    }
+
+    const usage = response.response.usageMetadata;
+    const tokensIn = usage?.promptTokenCount ?? 0;
+    const tokensOut = usage?.candidatesTokenCount ?? 0;
+    const costUsd = estimateCostUsd(model, tokensIn, tokensOut);
+
+    return {
+      content,
+      tokensIn,
+      tokensOut,
+      costUsd,
+      latencyMs: Date.now() - start,
+      modelUsed: 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/adapters/index.ts

@@ -0,0 +1,21 @@
+/**
+ * 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)
+ */
+
+export type {
+  Adapter,
+  AdapterInput,
+  AdapterOutput,
+  AgentRole,
+} from "./types.js";
+export { AdapterError } from "./types.js";
+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";

package/src/adapters/mock.ts

@@ -0,0 +1,125 @@
+/**
+ * Mock adapter — produces deterministic, realistic-shaped output without
+ * calling any external API. Used for end-to-end testing, demos without
+ * API keys, and to exercise the review pipeline in CI.
+ *
+ * The mock is deliberately "good enough to look real" so we can spot
+ * format problems. It is not a substitute for real model output.
+ */
+
+import type { Adapter, AdapterInput, AdapterOutput } from "./types.js";
+
+export class MockAdapter implements Adapter {
+  readonly name = "mock";
+  readonly provider = "mock";
+
+  constructor(
+    private readonly opts: {
+      /** Optional simulated latency in ms. Default 50. */
+      latencyMs?: number;
+    } = {},
+  ) {}
+
+  async isAvailable(): Promise<boolean> {
+    return true;
+  }
+
+  async execute(input: AdapterInput): Promise<AdapterOutput> {
+    const start = Date.now();
+    const latency = this.opts.latencyMs ?? 50;
+    await new Promise((r) => setTimeout(r, latency));
+
+    const content =
+      input.role === "reviewer"
+        ? this.mockReview(input.userMessage)
+        : this.mockWork(input.userMessage);
+
+    // Token counts are rough — 4 chars/token heuristic. Cost is always 0
+    // because the mock never bills anyone.
+    const tokensIn = Math.ceil(
+      (input.systemPrompt.length + input.userMessage.length) / 4,
+    );
+    const tokensOut = Math.ceil(content.length / 4);
+
+    return {
+      content,
+      tokensIn,
+      tokensOut,
+      costUsd: 0,
+      latencyMs: Date.now() - start,
+      modelUsed: "mock-1",
+      provider: "mock",
+    };
+  }
+
+  private mockReview(userMessage: string): string {
+    // Extract any file paths the user mentioned to make the mock look at-the-code.
+    const fileHints = Array.from(
+      userMessage.matchAll(/[\w./-]+\.(ts|js|tsx|jsx|py|go|rb|md|json|yaml)/g),
+    )
+      .slice(0, 3)
+      .map((m) => m[0]);
+    const refs = fileHints.length
+      ? fileHints
+      : ["src/index.ts", "src/lib/foo.ts", "src/utils/bar.ts"];
+
+    return [
+      "## Decision Required",
+      "Needs changes before merge. Three concrete issues identified.",
+      "",
+      "## Highest-Risk Findings",
+      "",
+      `### 1. (mock) Missing input validation in ${refs[0]}`,
+      "**Severity:** High",
+      "**Where:** entry point of the diff",
+      "**Why:** Untrusted input flows into a parser without bounds checks.",
+      "**Suggested fix:** Add a Zod schema at the boundary; reject malformed input early.",
+      "",
+      `### 2. (mock) Unhandled rejection in ${refs[1] ?? refs[0]}`,
+      "**Severity:** Medium",
+      "**Where:** the awaited call without try/catch",
+      "**Why:** A network failure here will surface as an uncaught promise rejection.",
+      "**Suggested fix:** Wrap in try/catch, log to the audit channel, return a typed error.",
+      "",
+      `### 3. (mock) Missing test coverage on ${refs[2] ?? refs[0]}`,
+      "**Severity:** Medium",
+      "**Where:** the branch added in this diff",
+      "**Why:** The new conditional has no exercise in the test suite.",
+      "**Suggested fix:** Add a unit test that exercises the new branch with a representative payload.",
+      "",
+      "## Concrete Weaknesses",
+      `1. ${refs[0]}: input validation gap (see Finding 1).`,
+      `2. ${refs[1] ?? refs[0]}: unhandled promise rejection (see Finding 2).`,
+      `3. ${refs[2] ?? refs[0]}: no test coverage for the new branch (see Finding 3).`,
+      "",
+      "## Test Plan",
+      "- Run the existing unit suite; expect no regressions.",
+      "- Add the test described in Finding 3 and verify it fails before fix, passes after.",
+      "- Manually trigger the network-error path described in Finding 2.",
+      "",
+      "## Human Decision",
+      "_(blank — record via `almightygpt decide`)_",
+      "",
+      "---",
+      "_Mock adapter output — no real model was invoked. Replace `--reviewer mock` with `--reviewer codex` or another real adapter for production review._",
+    ].join("\n");
+  }
+
+  private mockWork(userMessage: string): string {
+    return [
+      "## Plan",
+      "1. Understand the change requested.",
+      "2. Identify affected files and surfaces.",
+      "3. Write the implementation in small, testable steps.",
+      "4. Add or update tests.",
+      "5. Verify locally.",
+      "",
+      "## Notes",
+      "_(mock worker output — real Worker adapters produce code or detailed plans here.)_",
+      "",
+      `## Echo of input (first 200 chars):`,
+      "",
+      "> " + userMessage.slice(0, 200) + (userMessage.length > 200 ? "…" : ""),
+    ].join("\n");
+  }
+}

package/src/adapters/openai.ts

@@ -0,0 +1,150 @@
+/**
+ * OpenAI adapter — first real provider in MVP 1.
+ *
+ * Reads OPENAI_API_KEY from the environment. Never stores or logs the key.
+ * Default model: gpt-4o (best balance of quality and structured-output maturity
+ * for the Reviewer's JSON schema needs in later tasks). Configurable per-call.
+ *
+ * Pricing as of 2026-05 (USD per 1M tokens, gpt-4o):
+ *   input:  2.50
+ *   output: 10.00
+ * These are recorded in PRICING_USD_PER_1M below. Update when OpenAI changes
+ * their published rates.
+ */
+
+import OpenAI from "openai";
+import { AdapterError, type Adapter, type AdapterInput, type AdapterOutput } from "./types.js";
+
+/** USD per 1M tokens, by model. Lowercased keys. */
+const PRICING_USD_PER_1M: Record<string, { input: number; output: number }> = {
+  "gpt-4o": { input: 2.5, output: 10.0 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10.0, output: 30.0 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+};
+
+const DEFAULT_MODEL = "gpt-4o";
+
+export interface OpenAIAdapterOptions {
+  /** Override the API key source. Defaults to process.env.OPENAI_API_KEY. */
+  apiKey?: string;
+  /** Default model used when execute() does not supply one. */
+  defaultModel?: string;
+  /** Default response token cap. */
+  defaultMaxOutputTokens?: number;
+  /** Default wall-clock timeout. */
+  defaultTimeoutMs?: number;
+  /** OpenAI organization id (optional). */
+  organization?: string;
+}
+
+export class OpenAIAdapter implements Adapter {
+  readonly name: string;
+  readonly provider = "openai";
+
+  private readonly client: OpenAI | null;
+  private readonly defaultModel: string;
+  private readonly defaultMaxOutputTokens: number;
+  private readonly defaultTimeoutMs: number;
+
+  constructor(
+    name = "codex",
+    options: OpenAIAdapterOptions = {},
+  ) {
+    this.name = name;
+    this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+    this.defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? 4096;
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? 120_000;
+
+    const apiKey = options.apiKey ?? process.env["OPENAI_API_KEY"];
+    if (apiKey && apiKey.length > 0) {
+      this.client = new OpenAI({
+        apiKey,
+        ...(options.organization ? { organization: options.organization } : {}),
+      });
+    } else {
+      this.client = null;
+    }
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.client !== null;
+  }
+
+  async execute(input: AdapterInput): Promise<AdapterOutput> {
+    if (!this.client) {
+      throw new AdapterError(
+        "OPENAI_API_KEY is not set. Export it in your environment or pass it " +
+          "via the adapter constructor.",
+        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 this.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(
+        `OpenAI 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(
+        "OpenAI returned an empty response (no choices or empty content).",
+        this.name,
+      );
+    }
+
+    const content = choice.message.content;
+    const tokensIn = response.usage?.prompt_tokens ?? 0;
+    const tokensOut = response.usage?.completion_tokens ?? 0;
+    const costUsd = estimateCostUsd(model, tokensIn, tokensOut);
+
+    return {
+      content,
+      tokensIn,
+      tokensOut,
+      costUsd,
+      latencyMs: Date.now() - start,
+      modelUsed: response.model ?? model,
+      provider: this.provider,
+    };
+  }
+}
+
+function estimateCostUsd(
+  model: string,
+  tokensIn: number,
+  tokensOut: number,
+): number {
+  // Match by prefix so versioned model names (gpt-4o-2024-08-06) still resolve.
+  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/adapters/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Adapter interface — every provider implementation satisfies this.
+ *
+ * Memory files (CLAUDE.md, CODEX_AGENT.md, AGENTS.md) and rule files
+ * (.almightygpt/rules.md) are assembled by the review pipeline into the
+ * `systemPrompt` field. Adapters do not read filesystem state themselves;
+ * they take a fully-assembled prompt and return a fully-typed result.
+ *
+ * This keeps adapters thin and testable, and means swapping providers is
+ * a single-file change.
+ */
+
+export type AgentRole = "worker" | "reviewer";
+
+export interface AdapterInput {
+  /** worker | reviewer — drives the default system framing if a custom prompt is not supplied. */
+  role: AgentRole;
+  /** Fully assembled system prompt (memory file + rules + role framing). */
+  systemPrompt: string;
+  /** The actual task or critique target. */
+  userMessage: string;
+  /** Optional structured output mode. Defaults to text. */
+  responseFormat?: "text" | "json_object";
+  /** Optional override of the model name. Falls back to the adapter's default. */
+  model?: string;
+  /** Hard upper bound on response tokens. Adapters should pass this through. */
+  maxOutputTokens?: number;
+  /** Hard wall-clock timeout in ms. Adapter aborts if exceeded. */
+  timeoutMs?: number;
+}
+
+export interface AdapterOutput {
+  /** The model's text response. */
+  content: string;
+  /** Input token count (prompt). */
+  tokensIn: number;
+  /** Output token count (completion). */
+  tokensOut: number;
+  /** Estimated USD cost based on the model's published rates. */
+  costUsd: number;
+  /** Wall-clock latency in milliseconds. */
+  latencyMs: number;
+  /** Concrete model name used (e.g. "gpt-4o-2024-08-06"). */
+  modelUsed: string;
+  /** Provider name (e.g. "openai", "anthropic"). */
+  provider: string;
+}
+
+export interface Adapter {
+  /** Identifier used in config.yaml (e.g. "codex", "claude", "mock"). */
+  readonly name: string;
+  /** Underlying provider family (e.g. "openai", "anthropic", "mock"). */
+  readonly provider: string;
+  /** True if credentials are available and the adapter can be invoked. */
+  isAvailable(): Promise<boolean>;
+  /** Execute one model call. */
+  execute(input: AdapterInput): Promise<AdapterOutput>;
+}
+
+/**
+ * Thrown when an adapter cannot complete the call. Callers should treat this
+ * as a recoverable run failure (record the error, do not crash the orchestrator).
+ */
+export class AdapterError extends Error {
+  override readonly name = "AdapterError";
+  constructor(
+    message: string,
+    public readonly adapterName: string,
+    public override readonly cause?: unknown,
+  ) {
+    super(message);
+  }
+}

package/src/config/load.ts

@@ -0,0 +1,61 @@
+/**
+ * Load and validate .almightygpt/config.yaml from a repo root.
+ *
+ * Returns a fully-typed Config object. Throws a ConfigError with a useful
+ * message if the file is missing, malformed, or fails schema validation.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ConfigSchema, type Config } from "./schema.js";
+
+export class ConfigError extends Error {
+  override readonly name = "ConfigError";
+  constructor(
+    message: string,
+    public readonly path: string,
+    public override readonly cause?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+export async function loadConfig(repoRoot: string): Promise<Config> {
+  const path = join(repoRoot, ".almightygpt", "config.yaml");
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    throw new ConfigError(
+      `Could not read AlmightyGPT config. Run \`almightygpt init\` first.`,
+      path,
+      err,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (err) {
+    throw new ConfigError(
+      `Config YAML is malformed: ${err instanceof Error ? err.message : String(err)}`,
+      path,
+      err,
+    );
+  }
+
+  const result = ConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+      .join("\n");
+    throw new ConfigError(
+      `Config validation failed:\n${issues}`,
+      path,
+      result.error,
+    );
+  }
+
+  return result.data;
+}

package/src/config/schema.ts

@@ -0,0 +1,64 @@
+/**
+ * Zod schema for .almightygpt/config.yaml.
+ *
+ * The schema is intentionally permissive on unknown fields (passthrough) so
+ * future features can land without forcing a config-bump. Required fields
+ * are minimal — most behavior has sensible defaults.
+ */
+
+import { z } from "zod";
+
+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"]),
+    mode: z.enum(["api", "cli"]).default("api"),
+    role: AgentRoleSchema.default("optional"),
+    memoryFile: z.string().min(1),
+  })
+  .passthrough();
+
+export const ConfigSchema = z
+  .object({
+    version: z.literal(1),
+    reviewsDir: z.string().min(1).default("docs/codex-reviews"),
+    runsDir: z.string().min(1).default(".almightygpt/runs"),
+    agents: z.record(z.string(), AgentConfigSchema).default({}),
+    defaults: z
+      .object({
+        worker: z.string().min(1).optional(),
+        reviewer: z.string().min(1).optional(),
+      })
+      .default({}),
+    context: z
+      .object({
+        include: z.array(z.string()).default([]),
+        exclude: z.array(z.string()).default([]),
+        maxFileBytes: z.number().int().positive().default(120_000),
+      })
+      .default({}),
+    security: z
+      .object({
+        redactSecrets: z.boolean().default(true),
+        requireExternalProviderConfirmation: z.boolean().default(true),
+      })
+      .default({}),
+    budget: z
+      .object({
+        maxCostPerRunUsd: z.number().positive().default(0.5),
+        maxTokensPerRun: z.number().int().positive().default(100_000),
+      })
+      .default({}),
+    review: z
+      .object({
+        requireConcreteWeaknesses: z.number().int().nonnegative().default(3),
+        warnOnZeroFileReferences: z.boolean().default(true),
+      })
+      .default({}),
+  })
+  .passthrough();
+
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+export type Config = z.infer<typeof ConfigSchema>;