@almightygpt/core 0.2.0

package/src/review/memory.ts

@@ -0,0 +1,57 @@
+/**
+ * Load and assemble the agent memory + project context that gets fed to an
+ * adapter as its system prompt.
+ *
+ * For a Reviewer call, the assembled prompt is:
+ *   1. AGENTS.md (shared canonical context)
+ *   2. The agent's memory file (e.g. CODEX_AGENT.md)
+ *   3. .almightygpt/rules.md (project-wide invariants)
+ *
+ * Files are concatenated with clear section dividers so the model can tell
+ * which guidance comes from where.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface MemoryAssembly {
+  text: string;
+  sources: { path: string; bytes: number }[];
+  /** Paths that were expected but missing. Surfaces to the user as a warning. */
+  missing: string[];
+}
+
+const SECTION_DIVIDER =
+  "\n\n---\n# Section: %SOURCE%\n# (loaded by AlmightyGPT)\n---\n\n";
+
+export async function assembleMemory(
+  repoRoot: string,
+  memoryFile: string,
+): Promise<MemoryAssembly> {
+  const candidates = [
+    "AGENTS.md",
+    memoryFile,
+    join(".almightygpt", "rules.md"),
+  ];
+
+  const parts: string[] = [];
+  const sources: { path: string; bytes: number }[] = [];
+  const missing: string[] = [];
+
+  for (const rel of candidates) {
+    const abs = join(repoRoot, rel);
+    try {
+      const content = await readFile(abs, "utf8");
+      parts.push(SECTION_DIVIDER.replace("%SOURCE%", rel) + content.trim());
+      sources.push({ path: rel, bytes: content.length });
+    } catch {
+      missing.push(rel);
+    }
+  }
+
+  return {
+    text: parts.join("\n").trim(),
+    sources,
+    missing,
+  };
+}

package/src/review/prompts.ts

@@ -0,0 +1,208 @@
+/**
+ * Prompt assembly for review runs.
+ *
+ * The Reviewer's job is constrained by its memory file (CODEX_AGENT.md) and
+ * the project rules (.almightygpt/rules.md), which are assembled into the
+ * system prompt by review/memory.ts. The user message here supplies the
+ * concrete task.
+ */
+
+export interface ReviewerUserMessageOptions {
+  topic: string;
+  diff: string;
+  files: string[];
+  /** Optional repo-relative path the user pointed at (e.g. for path reviews). */
+  scope?: string;
+}
+
+export interface WorkerUserMessageOptions {
+  topic: string;
+  diff: string;
+  files: string[];
+}
+
+export interface ReviewerOfWorkerUserMessageOptions {
+  topic: string;
+  diff: string;
+  files: string[];
+  workerOutput: string;
+  workerAgent: string;
+  workerProvider: string;
+}
+
+export function buildReviewerSystemFraming(): string {
+  // Brief framing that goes in front of the assembled memory text. The
+  // assembled memory contains the anti-sycophancy rules and the format spec.
+  // We use this top-level framing to (a) anchor the model on THIS diff,
+  // not the whole repo, and (b) clarify which sections the orchestrator
+  // owns vs which the model must produce.
+  return [
+    "You are the Reviewer AI in an AlmightyGPT cross-review run.",
+    "",
+    "WHAT YOU ARE REVIEWING: only the diff supplied below.",
+    "Do not audit unchanged code, unchanged docs, or the project structure",
+    "as a whole. The assembled project memory below is BACKGROUND CONTEXT",
+    "for interpreting the diff — it is not the review target. If a finding",
+    "could apply equally to any commit in the repo, it is too broad for",
+    "this review.",
+    "",
+    "WHAT THE ORCHESTRATOR OWNS (do NOT include these in your response):",
+    "  - The H1 title (the orchestrator prepends `# Review: <topic>`).",
+    "  - The header block with model / tokens / cost / latency.",
+    "  - The `## Cost and Latency` section.",
+    "  - The `## Appendix: Raw Outputs` section.",
+    "",
+    "WHAT YOU MUST PRODUCE — start your response with `## Decision Required`",
+    "and emit only these sections in this order:",
+    "  ## Decision Required",
+    "  ## Highest-Risk Findings",
+    "  ## Concrete Weaknesses",
+    "  ## Test Plan",
+    "  ## Human Decision",
+    "",
+    "Anti-sycophancy is non-negotiable: list at least three concrete",
+    "weaknesses with file:line references taken from the diff hunks (the",
+    "`@@ -X,Y +N,M @@` markers tell you starting line numbers — use real",
+    "ones, do not invent). If you cannot find three real weaknesses in",
+    "this diff, say so explicitly; your output will be flagged shallow.",
+  ].join("\n");
+}
+
+export function buildWorkerSystemFraming(): string {
+  return [
+    "You are the Worker AI in an AlmightyGPT cross-review run.",
+    "Read the assembled project memory below, then read the diff and produce",
+    "a thorough plan that the Reviewer AI will critique. Your job is to be",
+    "honest about uncertainty and explicit about risks. The Reviewer will",
+    "find what you missed — make their job easier by being precise about",
+    "what you considered and what you did not.",
+  ].join(" ");
+}
+
+export function buildWorkerUserMessage(opts: WorkerUserMessageOptions): string {
+  const filesList = opts.files.length
+    ? opts.files.map((f) => `- ${f}`).join("\n")
+    : "(no files reported)";
+
+  return [
+    `# Worker Task`,
+    "",
+    `**Topic:** \`${opts.topic}\``,
+    "",
+    `## Files in this diff`,
+    "",
+    filesList,
+    "",
+    `## Diff`,
+    "",
+    "```diff",
+    opts.diff.trim() || "(empty diff)",
+    "```",
+    "",
+    `## Your Instructions`,
+    "",
+    "Produce a markdown response with these sections in order:",
+    "",
+    "1. `## Change Summary` — one paragraph: what does this diff do, and why?",
+    "2. `## Affected Modules / Surfaces` — bulleted list, each with one-line impact.",
+    "3. `## Risks` — bulleted list. Each risk: what could go wrong, where, and how likely. Be specific.",
+    "4. `## Test Plan` — what to verify before merging. Each item: scope + acceptance criterion.",
+    "5. `## Open Questions` — things you are not sure about. List them honestly. The Reviewer needs to know where to look hardest.",
+    "",
+    "Output markdown only. Do not wrap the whole response in a code block.",
+    "Do not produce a Reviewer-style critique — that is the Reviewer's job in",
+    "the next stage.",
+  ].join("\n");
+}
+
+export function buildReviewerOfWorkerUserMessage(
+  opts: ReviewerOfWorkerUserMessageOptions,
+): string {
+  const filesList = opts.files.length
+    ? opts.files.map((f) => `- ${f}`).join("\n")
+    : "(no files reported)";
+
+  return [
+    `# Critique This Worker Output`,
+    "",
+    `**Topic:** \`${opts.topic}\``,
+    `**Worker:** \`${opts.workerAgent}\` (${opts.workerProvider})`,
+    "",
+    `## Files in this diff`,
+    "",
+    filesList,
+    "",
+    `## Diff (what the Worker analyzed — this is the change in question)`,
+    "",
+    "```diff",
+    opts.diff.trim() || "(empty diff)",
+    "```",
+    "",
+    `## Worker Output (this is what you are critiquing)`,
+    "",
+    opts.workerOutput.trim(),
+    "",
+    `## Reminders`,
+    "",
+    "- Start your response with `## Decision Required` — the orchestrator",
+    "  owns the H1 title and the cost header.",
+    "- Findings must point at the diff or at specific claims/omissions in",
+    "  the Worker's output. Do not audit unchanged code or unchanged docs.",
+    "- File:line references must come from the diff's `@@ -X,Y +N,M @@`",
+    "  hunk markers. Do not invent line numbers.",
+    "- Required sections in order:",
+    "  - `## Decision Required`",
+    "  - `## Highest-Risk Findings`",
+    "  - `## Concrete Weaknesses` (at least 3 with file:line refs; missing",
+    "    Worker considerations count if specific)",
+    "  - `## Worker Plan Summary` (condensed)",
+    "  - `## Test Plan`",
+    "  - `## Human Decision` (leave body blank)",
+    "- Do NOT include `## Cost and Latency` or `## Appendix: Raw Outputs`",
+    "  — the orchestrator emits those after you.",
+    "- The Worker is not the user; the Worker is what you are critiquing.",
+    "  Disagree where they are wrong, do not soften.",
+    "- Markdown only. No code-block wrapper around the whole response.",
+  ].join("\n");
+}
+
+export function buildReviewerUserMessage(
+  opts: ReviewerUserMessageOptions,
+): string {
+  const filesList = opts.files.length
+    ? opts.files.map((f) => `- ${f}`).join("\n")
+    : "(no files reported)";
+
+  return [
+    `# Review This Diff`,
+    "",
+    `**Topic:** \`${opts.topic}\``,
+    opts.scope ? `**Scope:** \`${opts.scope}\`` : "",
+    "",
+    `## Files in this diff`,
+    "",
+    filesList,
+    "",
+    `## Diff (this is the ONLY thing you are reviewing)`,
+    "",
+    "```diff",
+    opts.diff.trim() || "(empty diff)",
+    "```",
+    "",
+    `## Reminders`,
+    "",
+    "- Start your response with `## Decision Required` — the orchestrator",
+    "  owns the H1 title and the cost header.",
+    "- Findings must point at the diff above, not at unchanged code or",
+    "  unchanged docs.",
+    "- File:line references must come from the diff's `@@ -X,Y +N,M @@`",
+    "  hunk markers. Do not invent line numbers.",
+    "- If this diff is small or routine, say so plainly in Decision Required.",
+    "  Honest small reviews beat padded long ones.",
+    "- Do NOT include `## Cost and Latency` or `## Appendix: Raw Outputs`",
+    "  sections — the orchestrator emits those after you.",
+    "- Markdown only. No code-block wrapper around the whole response.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/src/review/run-diff-review.ts

@@ -0,0 +1,353 @@
+/**
+ * Orchestrate a diff review (now with dual artifact output, redaction, and
+ * budget enforcement).
+ *
+ * Pipeline:
+ *   1. Load config + create run folder.
+ *   2. Resolve the reviewer adapter.
+ *   3. Collect the git diff.
+ *   4. Redact secrets from the diff (config.security.redactSecrets).
+ *   5. Build context manifest, write input.md + context-manifest.json.
+ *   6. Assemble the reviewer's system prompt (AGENTS.md + memory + rules).
+ *   7. Pre-flight budget check.
+ *   8. Call the adapter.
+ *   9. Record adapter call against the budget (post-call check).
+ *  10. Detect shallow review.
+ *  11. Write outputs/reviewer.md (machine) and the human review file.
+ *  12. Write run.json with totals + status.
+ */
+
+import { type Adapter, AdapterError } from "../adapters/types.js";
+import { MockAdapter } from "../adapters/mock.js";
+import { OpenAIAdapter } from "../adapters/openai.js";
+import { ClaudeAdapter } from "../adapters/claude.js";
+import { GeminiAdapter } from "../adapters/gemini.js";
+import { loadConfig } from "../config/load.js";
+import { redactSecrets } from "../context/redact.js";
+import {
+  buildContextManifest,
+  writeContextManifest,
+} from "../context/manifest.js";
+import {
+  collectGitContext,
+  createRunFolder,
+  writeAgentOutput,
+  writeRunInput,
+  writeRunMetadata,
+} from "../runs/folder.js";
+import type { RunMetadata } from "../runs/types.js";
+import { collectGitDiff } from "./diff.js";
+import { assembleMemory } from "./memory.js";
+import {
+  buildReviewerSystemFraming,
+  buildReviewerUserMessage,
+} from "./prompts.js";
+import { writeHumanReviewFile } from "./write.js";
+import { BudgetTracker, BudgetExceededError } from "./budget.js";
+
+export interface DiffReviewOptions {
+  repoRoot: string;
+  topic: string;
+  /** Override the reviewer agent name from config defaults. */
+  reviewer?: string;
+  /** Optional git range like "HEAD~1..HEAD". */
+  range?: string;
+  /** Bypass the git status safety check. */
+  force?: boolean;
+}
+
+export interface DiffReviewResult {
+  reviewPath: string;
+  reviewBytes: number;
+  reviewer: string;
+  provider: string;
+  modelUsed: string;
+  tokensIn: number;
+  tokensOut: number;
+  costUsd: number;
+  latencyMs: number;
+  diffEmpty: boolean;
+  filesReviewed: string[];
+  memorySources: { path: string; bytes: number }[];
+  memoryMissing: string[];
+  runId: string;
+  runFolder: string;
+  redactionsTotal: number;
+  shallowWarning?: string;
+}
+
+export async function runDiffReview(
+  opts: DiffReviewOptions,
+): Promise<DiffReviewResult> {
+  const config = await loadConfig(opts.repoRoot);
+
+  const reviewerName = opts.reviewer ?? config.defaults.reviewer;
+  if (!reviewerName) {
+    throw new Error(
+      "No reviewer specified. Pass --reviewer <name> or set defaults.reviewer in .almightygpt/config.yaml.",
+    );
+  }
+
+  const agentConfig = config.agents[reviewerName];
+  if (!agentConfig) {
+    throw new Error(
+      `Reviewer "${reviewerName}" not found in .almightygpt/config.yaml agents map.`,
+    );
+  }
+  if (!agentConfig.enabled) {
+    throw new Error(
+      `Reviewer "${reviewerName}" is disabled in .almightygpt/config.yaml.`,
+    );
+  }
+
+  const adapter = makeAdapter(reviewerName, agentConfig.provider);
+  if (!(await adapter.isAvailable())) {
+    throw new AdapterError(
+      `Adapter "${reviewerName}" (${agentConfig.provider}) is not available. ` +
+        envHintForProvider(agentConfig.provider),
+      reviewerName,
+    );
+  }
+
+  // Create run folder up front so partial failures still leave an artifact.
+  const runFolder = await createRunFolder({
+    repoRoot: opts.repoRoot,
+    runsDir: config.runsDir,
+    topic: opts.topic,
+    type: "review-diff",
+  });
+
+  const git = await collectGitContext(opts.repoRoot);
+
+  const baseMeta: RunMetadata = {
+    id: runFolder.id,
+    type: "review-diff",
+    createdAt: new Date().toISOString(),
+    workspacePath: opts.repoRoot,
+    topic: opts.topic,
+    git,
+    input: opts.range
+      ? { source: "diff-range", range: opts.range }
+      : { source: "diff" },
+    agents: Object.entries(config.agents).map(([name, a]) => ({
+      name,
+      role: a.role,
+      provider: a.provider,
+      enabled: a.enabled,
+    })),
+    adapterVersions: [{ adapter: adapter.name, version: "0.0.0" }],
+    status: "running",
+    metrics: [],
+    totals: { tokensIn: 0, tokensOut: 0, costUsd: 0, latencyMs: 0 },
+    budget: config.budget,
+  };
+  // Persist the running state so external tools / dashboards can poll.
+  await writeRunMetadata(runFolder.absPath, baseMeta);
+
+  try {
+    const diffArgs: { range?: string } = {};
+    if (opts.range) diffArgs.range = opts.range;
+    const diffResult = await collectGitDiff(opts.repoRoot, diffArgs);
+    if (diffResult.empty && !opts.range) {
+      throw new Error(
+        "No uncommitted changes to review. Stage some changes, pick a range with " +
+          "--range, or pass --topic to a non-empty diff.",
+      );
+    }
+
+    const redaction = config.security.redactSecrets
+      ? redactSecrets(diffResult.diff)
+      : { text: diffResult.diff, redactions: [], totalCount: 0 };
+
+    const manifest = buildContextManifest({
+      inputSource: opts.range ? "diff-range" : "diff",
+      filesIncluded: diffResult.files.map((p) => ({ path: p, bytes: 0 })),
+      filesSkipped: [],
+      diffText: redaction.text,
+      redaction: {
+        enabled: config.security.redactSecrets,
+        totalCount: redaction.totalCount,
+        byKind: redaction.redactions,
+      },
+    });
+    const manifestRelPath = await writeContextManifest(
+      runFolder.absPath,
+      manifest,
+    );
+    await writeRunInput(runFolder.absPath, redaction.text);
+
+    const memory = await assembleMemory(opts.repoRoot, agentConfig.memoryFile);
+    const systemPrompt =
+      buildReviewerSystemFraming() + "\n\n" + memory.text;
+    const userMessage = buildReviewerUserMessage({
+      topic: opts.topic,
+      diff: redaction.text,
+      files: diffResult.files,
+    });
+
+    const budget = new BudgetTracker(config.budget);
+    const estimatedTokensIn = Math.ceil(
+      (systemPrompt.length + userMessage.length) / 4,
+    );
+    budget.preflightCheck({
+      model: "gpt-4o", // estimator only; adapter resolves real model
+      estimatedTokensIn,
+      maxOutputTokens: 4096,
+    });
+
+    const adapterOut = await adapter.execute({
+      role: "reviewer",
+      systemPrompt,
+      userMessage,
+    });
+
+    budget.record({
+      tokensIn: adapterOut.tokensIn,
+      tokensOut: adapterOut.tokensOut,
+      costUsd: adapterOut.costUsd,
+    });
+
+    await writeAgentOutput(runFolder.absPath, "reviewer", adapterOut.content);
+
+    const shallowWarning = detectShallowReview(
+      adapterOut.content,
+      config.review.requireConcreteWeaknesses,
+    );
+
+    const writeOpts: Parameters<typeof writeHumanReviewFile>[0] = {
+      repoRoot: opts.repoRoot,
+      reviewsDir: config.reviewsDir,
+      topic: opts.topic,
+      reviewerName,
+      reviewerProvider: adapter.provider,
+      modelUsed: adapterOut.modelUsed,
+      body: adapterOut.content,
+      metrics: {
+        tokensIn: adapterOut.tokensIn,
+        tokensOut: adapterOut.tokensOut,
+        costUsd: adapterOut.costUsd,
+        latencyMs: adapterOut.latencyMs,
+      },
+      runFolder: runFolder.relPath,
+    };
+    if (shallowWarning) writeOpts.shallowWarning = shallowWarning;
+    if (opts.force) writeOpts.force = opts.force;
+    const written = await writeHumanReviewFile(writeOpts);
+
+    const finalMeta: RunMetadata = {
+      ...baseMeta,
+      finishedAt: new Date().toISOString(),
+      status: "completed",
+      contextManifestPath: manifestRelPath,
+      reviewPath: written.path,
+      metrics: [
+        {
+          agent: reviewerName,
+          role: "reviewer",
+          provider: adapter.provider,
+          model: adapterOut.modelUsed,
+          tokensIn: adapterOut.tokensIn,
+          tokensOut: adapterOut.tokensOut,
+          costUsd: adapterOut.costUsd,
+          latencyMs: adapterOut.latencyMs,
+        },
+      ],
+      totals: {
+        tokensIn: adapterOut.tokensIn,
+        tokensOut: adapterOut.tokensOut,
+        costUsd: adapterOut.costUsd,
+        latencyMs: adapterOut.latencyMs,
+      },
+    };
+    await writeRunMetadata(runFolder.absPath, finalMeta);
+
+    return {
+      reviewPath: written.path,
+      reviewBytes: written.bytes,
+      reviewer: reviewerName,
+      provider: adapter.provider,
+      modelUsed: adapterOut.modelUsed,
+      tokensIn: adapterOut.tokensIn,
+      tokensOut: adapterOut.tokensOut,
+      costUsd: adapterOut.costUsd,
+      latencyMs: adapterOut.latencyMs,
+      diffEmpty: diffResult.empty,
+      filesReviewed: diffResult.files,
+      memorySources: memory.sources,
+      memoryMissing: memory.missing,
+      runId: runFolder.id,
+      runFolder: runFolder.relPath,
+      redactionsTotal: redaction.totalCount,
+      ...(shallowWarning ? { shallowWarning } : {}),
+    };
+  } catch (err) {
+    const failedMeta: RunMetadata = {
+      ...baseMeta,
+      finishedAt: new Date().toISOString(),
+      status: err instanceof BudgetExceededError ? "aborted_budget" : "failed",
+      error: {
+        name: err instanceof Error ? err.name : "Error",
+        message: err instanceof Error ? err.message : String(err),
+      },
+    };
+    await writeRunMetadata(runFolder.absPath, failedMeta);
+    throw err;
+  }
+}
+
+function makeAdapter(name: string, provider: string): Adapter {
+  switch (provider) {
+    case "openai":
+      return new OpenAIAdapter(name);
+    case "anthropic":
+      return new ClaudeAdapter(name);
+    case "google":
+      return new GeminiAdapter(name);
+    case "mock":
+      return new MockAdapter();
+    default:
+      throw new Error(
+        `Provider "${provider}" not supported. ` +
+          `Use "openai", "anthropic", "google", or "mock".`,
+      );
+  }
+}
+
+function envHintForProvider(provider: string): string {
+  switch (provider) {
+    case "openai":
+      return "Export OPENAI_API_KEY in your environment.";
+    case "anthropic":
+      return "Export ANTHROPIC_API_KEY in your environment.";
+    case "google":
+      return "Export GOOGLE_API_KEY (or GEMINI_API_KEY) in your environment.";
+    default:
+      return "";
+  }
+}
+
+function detectShallowReview(
+  content: string,
+  minWeaknesses: number,
+): string | undefined {
+  const fileRefs = content.match(/[\w./_-]+\.(ts|tsx|js|jsx|py|go|rb|md|json|yaml|yml)(?::\d+)?/g);
+  const fileRefCount = fileRefs ? fileRefs.length : 0;
+
+  const weaknessSection = content.match(
+    /##\s+Concrete\s+Weaknesses\s*\n([\s\S]*?)(\n##|$)/i,
+  );
+  const weaknessCount = weaknessSection
+    ? (weaknessSection[1]!.match(/^\s*\d+\.\s+/gm) ?? []).length
+    : 0;
+
+  if (fileRefCount === 0) {
+    return `Reviewer output contains zero file/line references. Likely shallow.`;
+  }
+  if (weaknessCount < minWeaknesses) {
+    return (
+      `Reviewer listed ${weaknessCount} concrete weaknesses; config requires ${minWeaknesses}. ` +
+      `Output may be shallow.`
+    );
+  }
+  return undefined;
+}