@almightygpt/core 0.9.1 → 0.10.0

package/src/auth/validator.ts

@@ -13,26 +13,41 @@
  *   - Google:    tiny generateContent call against gemini-2.5-flash
  *
  * Cost is fractions of a cent per call. Latency is ~1-3 seconds.
- * Failure surfaces the provider's exact error message so the user
- * can fix it.
+ *
+ * **Error handling (per Codex v0.8 P2 #6):** failure responses are
+ * parsed into a short user-safe message + status code. We never
+ * return the raw provider body to the user — those bodies can include
+ * request IDs, billing/account state, org/project details, quota
+ * metadata, or other account information that's too noisy for CLI
+ * logs. The raw body is available via the `rawBody` field for callers
+ * that explicitly want it (e.g. debug mode).
+ *
+ * **Default models (per Codex v0.8 P2 #5):** sourced from
+ * `adapters/defaults.ts` — the single source of truth — so the
+ * validator can't drift from the adapters.
  */
 
 import type { ProviderId } from "./types.js";
+import { DEFAULT_MODELS } from "../adapters/defaults.js";
 
 export interface ValidationResult {
   ok: boolean;
   /** Provider-reported model used (e.g. "gpt-4o-2024-08-06"). */
   model?: string;
-  /** Provider's error message verbatim if ok === false. */
+  /** Short user-safe message — never includes raw provider body. */
   error?: string;
+  /** HTTP status code from the provider, if applicable. */
+  statusCode?: number;
+  /** Latency in ms — useful for `auth status --validate` JSON output. */
+  latencyMs?: number;
+  /**
+   * Raw provider response body. Present iff a request was made and
+   * returned non-OK. Callers should NOT surface this to users without
+   * explicit debug intent; it may contain account metadata.
+   */
+  rawBody?: string;
 }
 
-const DEFAULT_VALIDATION_MODELS: Record<ProviderId, string> = {
-  openai: "gpt-4o",
-  anthropic: "claude-sonnet-4-6",
-  google: "gemini-2.5-flash",
-};
-
 const VALIDATION_TIMEOUT_MS = 15_000;
 
 /**
@@ -44,25 +59,33 @@ export async function validateKey(
   provider: ProviderId,
   key: string,
 ): Promise<ValidationResult> {
+  const start = Date.now();
   try {
+    let result: ValidationResult;
     switch (provider) {
       case "openai":
-        return await validateOpenAI(key);
+        result = await validateOpenAI(key);
+        break;
       case "anthropic":
-        return await validateAnthropic(key);
+        result = await validateAnthropic(key);
+        break;
       case "google":
-        return await validateGoogle(key);
+        result = await validateGoogle(key);
+        break;
     }
+    result.latencyMs = Date.now() - start;
+    return result;
   } catch (err) {
     return {
       ok: false,
-      error: err instanceof Error ? err.message : String(err),
+      error: friendlyNetworkError(err),
+      latencyMs: Date.now() - start,
     };
   }
 }
 
 async function validateOpenAI(key: string): Promise<ValidationResult> {
-  const model = DEFAULT_VALIDATION_MODELS.openai;
+  const model = DEFAULT_MODELS.openai;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
   try {
@@ -80,7 +103,13 @@ async function validateOpenAI(key: string): Promise<ValidationResult> {
       signal: controller.signal,
     });
     if (!res.ok) {
-      return { ok: false, error: await res.text().catch(() => res.statusText) };
+      const rawBody = await res.text().catch(() => "");
+      return {
+        ok: false,
+        statusCode: res.status,
+        error: normalizeOpenAIError(res.status, rawBody),
+        rawBody,
+      };
     }
     const data = (await res.json()) as { model?: string };
     return { ok: true, model: data.model ?? model };
@@ -90,7 +119,7 @@ async function validateOpenAI(key: string): Promise<ValidationResult> {
 }
 
 async function validateAnthropic(key: string): Promise<ValidationResult> {
-  const model = DEFAULT_VALIDATION_MODELS.anthropic;
+  const model = DEFAULT_MODELS.anthropic;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
   try {
@@ -109,7 +138,13 @@ async function validateAnthropic(key: string): Promise<ValidationResult> {
       signal: controller.signal,
     });
     if (!res.ok) {
-      return { ok: false, error: await res.text().catch(() => res.statusText) };
+      const rawBody = await res.text().catch(() => "");
+      return {
+        ok: false,
+        statusCode: res.status,
+        error: normalizeAnthropicError(res.status, rawBody),
+        rawBody,
+      };
     }
     const data = (await res.json()) as { model?: string };
     return { ok: true, model: data.model ?? model };
@@ -119,16 +154,12 @@ async function validateAnthropic(key: string): Promise<ValidationResult> {
 }
 
 async function validateGoogle(key: string): Promise<ValidationResult> {
-  const model = DEFAULT_VALIDATION_MODELS.google;
+  const model = DEFAULT_MODELS.google;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
   try {
-    // Use x-goog-api-key header rather than ?key= URL parameter. URLs
-    // leak into proxy logs, HTTP tooling, crash diagnostics. The header
-    // path is supported by all v1beta endpoints. Codex's v0.8 security
-    // review flagged the URL-key approach as a P1.
-    const url =
-      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+    // x-goog-api-key header (per v0.9.1 fix) — never the URL query.
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
     const res = await fetch(url, {
       method: "POST",
       headers: {
@@ -142,10 +173,103 @@ async function validateGoogle(key: string): Promise<ValidationResult> {
       signal: controller.signal,
     });
     if (!res.ok) {
-      return { ok: false, error: await res.text().catch(() => res.statusText) };
+      const rawBody = await res.text().catch(() => "");
+      return {
+        ok: false,
+        statusCode: res.status,
+        error: normalizeGoogleError(res.status, rawBody, key),
+        rawBody,
+      };
     }
     return { ok: true, model };
   } finally {
     clearTimeout(timer);
   }
 }
+
+// ─── Error normalization (Codex v0.8 P2 #6) ──────────────────────────
+//
+// Parse known provider JSON error shapes into short, user-safe messages.
+// Never echo the raw key back even by accident (defense in depth: we
+// also redact anything that looks like the submitted key).
+
+function normalizeOpenAIError(status: number, rawBody: string): string {
+  // OpenAI shape: { "error": { "message": "...", "type": "...", "code": "..." } }
+  try {
+    const parsed = JSON.parse(rawBody) as {
+      error?: { message?: string; type?: string; code?: string };
+    };
+    const msg = parsed.error?.message;
+    if (msg) return `[${status}] OpenAI: ${truncate(msg, 200)}`;
+  } catch {
+    /* fall through */
+  }
+  return statusOnlyMessage("OpenAI", status);
+}
+
+function normalizeAnthropicError(status: number, rawBody: string): string {
+  // Anthropic shape: { "type": "error", "error": { "type": "...", "message": "..." } }
+  try {
+    const parsed = JSON.parse(rawBody) as {
+      error?: { type?: string; message?: string };
+    };
+    const msg = parsed.error?.message;
+    if (msg) return `[${status}] Anthropic: ${truncate(msg, 200)}`;
+  } catch {
+    /* fall through */
+  }
+  return statusOnlyMessage("Anthropic", status);
+}
+
+function normalizeGoogleError(
+  status: number,
+  rawBody: string,
+  submittedKey: string,
+): string {
+  // Google shape: { "error": { "code": N, "message": "...", "status": "..." } }
+  try {
+    const parsed = JSON.parse(rawBody) as {
+      error?: { code?: number; message?: string; status?: string };
+    };
+    let msg = parsed.error?.message ?? "";
+    // Belt-and-braces redaction: Google sometimes echoes the key in
+    // error messages (e.g. "API key not valid. Pass a valid API key.")
+    // — we don't ship the actual key value if it ever ends up here.
+    if (submittedKey && msg.includes(submittedKey)) {
+      msg = msg.replace(submittedKey, "<redacted-key>");
+    }
+    if (msg) return `[${status}] Google: ${truncate(msg, 200)}`;
+  } catch {
+    /* fall through */
+  }
+  return statusOnlyMessage("Google", status);
+}
+
+function statusOnlyMessage(provider: string, status: number): string {
+  if (status === 401 || status === 403) {
+    return `[${status}] ${provider} rejected the key (unauthorized).`;
+  }
+  if (status === 429) {
+    return `[${status}] ${provider} rate-limited or quota exceeded.`;
+  }
+  if (status >= 500) {
+    return `[${status}] ${provider} returned a server error; try again.`;
+  }
+  return `[${status}] ${provider} returned an unrecognized error.`;
+}
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}
+
+function friendlyNetworkError(err: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (msg.includes("abort")) {
+    return "Validation timed out (network or provider too slow).";
+  }
+  if (msg.includes("ENOTFOUND") || msg.includes("ECONNREFUSED")) {
+    return "Could not reach the provider (network issue).";
+  }
+  // Generic — but never include random stack data; just the message.
+  return `Network error: ${truncate(msg, 200)}`;
+}

package/src/index.ts

@@ -13,7 +13,7 @@
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
 
-export const VERSION = "0.9.1";
+export const VERSION = "0.10.0";
 
 // MCP server (v0.9.0+) — exposes AlmightyGPT's review surface as MCP tools.
 export { startMcpServer } from "./mcp/server.js";
@@ -143,6 +143,18 @@ export {
   type KeychainAdapter,
 } from "./auth/keychain.js";
 export { validateKey, type ValidationResult } from "./auth/validator.js";
+// Plan subsystem (v0.10.0+) — Worker plan + Reviewer plan-review
+export {
+  runWorkerPlan,
+  type PlanOptions,
+  type PlanResult,
+} from "./plan/run-plan.js";
+export {
+  runPlanReview,
+  type PlanReviewOptions,
+  type PlanReviewResult,
+} from "./plan/run-plan-review.js";
+
 export {
   AuthMissingError,
   PROVIDER_ENV_VARS,

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

@@ -0,0 +1,302 @@
+/**
+ * `almightygpt review --plan <file>` — Reviewer AI critiques a PLAN
+ * doc (not a git diff). Same review primitives as runDiffReview but
+ * the input is the plan markdown and the framing tells the Reviewer
+ * to critique the plan's structure, completeness, and risks rather
+ * than line-by-line code.
+ *
+ * Output lands at `<reviewsDir>/plan-<topic>.md` (prefix distinguishes
+ * plan reviews from diff reviews when they share the same topic name).
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig } from "../config/load.js";
+import { makeAdapter } from "../adapters/factory.js";
+import { AdapterError } from "../adapters/types.js";
+import { assembleMemory } from "../review/memory.js";
+import {
+  createRunFolder,
+  writeRunMetadata,
+  writeRunInput,
+  writeAgentOutput,
+  collectGitContext,
+} from "../runs/folder.js";
+import {
+  writeHumanReviewFile,
+  preflightReviewFileCollision,
+} from "../review/write.js";
+
+export interface PlanReviewOptions {
+  repoRoot: string;
+  topic: string;
+  /** Path (relative to repoRoot) to the plan markdown to review. */
+  planPath: string;
+  reviewer?: string;
+  force?: boolean;
+}
+
+export interface PlanReviewResult {
+  reviewPath: string;
+  reviewBytes: number;
+  reviewer: string;
+  provider: string;
+  modelUsed: string;
+  tokensIn: number;
+  cachedTokensIn: number;
+  tokensOut: number;
+  costUsd: number;
+  latencyMs: number;
+  memorySources: { path: string; bytes: number }[];
+  memoryMissing: string[];
+  runId: string;
+  runFolder: string;
+  shallowWarning?: string;
+}
+
+const PLAN_REVIEW_SYSTEM_FRAMING = [
+  "You are the Reviewer AI in an AlmightyGPT Plan-review stage.",
+  "",
+  "WHAT YOU ARE REVIEWING: the PLAN markdown supplied below. NOT a git",
+  "diff and NOT code — a plan that a Worker AI drafted in response to a",
+  "human's requirement. The plan has not been implemented yet. Your job",
+  "is to find what's WRONG with the plan: missing steps, hidden",
+  "dependencies, risks the Worker didn't surface, ambiguous decisions,",
+  "things that will break in production, edge cases the test plan misses.",
+  "",
+  "WHAT THE ORCHESTRATOR OWNS (do NOT include these in your response):",
+  "  - The H1 title (orchestrator prepends `# Plan Review: <topic>`).",
+  "  - The header block with model / tokens / cost.",
+  "  - The `## Cost and Latency` and `## Appendix: Raw Outputs` sections.",
+  "",
+  "WHAT YOU MUST PRODUCE — start with `## Decision Required` and emit",
+  "ONLY these sections in this order:",
+  "  ## Decision Required",
+  "  ## Highest-Risk Findings",
+  "  ## Concrete Weaknesses",
+  "  ## Worker Plan Summary",
+  "  ## Test Plan",
+  "  ## Human Decision",
+  "",
+  "ANTI-SYCOPHANCY (non-negotiable):",
+  "  - Find at least 3 concrete weaknesses with specific file / step / line",
+  "    references from the plan.",
+  "  - A finding without a specific anchor is too vague.",
+  "  - 'Looks good, minor suggestions' is a FAILED review — recalibrate.",
+  "",
+  "REVIEW LENS — focus on what plans commonly get wrong:",
+  "  - Steps assume capabilities that don't exist yet",
+  "  - Risks section underweights production blast radius",
+  "  - Test plan is generic ('add tests') instead of named cases",
+  "  - Open questions are missing things the human will actually need to",
+  "    decide before implementation",
+  "  - Affected modules list is incomplete (the plan touches more surfaces",
+  "    than it admits)",
+  "  - Migration / rollback story is missing or hand-wavy",
+].join("\n");
+
+function buildPlanReviewUserMessage(
+  topic: string,
+  planContent: string,
+): string {
+  return [
+    `# Plan-review request — topic: \`${topic}\``,
+    "",
+    "## The plan to review",
+    "",
+    "```markdown",
+    planContent.trim(),
+    "```",
+    "",
+    "## Your task",
+    "",
+    "Critique the plan above using the structure in your system prompt.",
+    "Start your response with `## Decision Required` (no H1, no preamble).",
+  ].join("\n");
+}
+
+export async function runPlanReview(
+  opts: PlanReviewOptions,
+): Promise<PlanReviewResult> {
+  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. Set the provider's API key.`,
+      reviewerName,
+    );
+  }
+
+  // Plan reviews land at <reviewsDir>/plan-<topic>.md so they don't
+  // collide with diff reviews on the same topic.
+  const planReviewTopic = `plan-${opts.topic}`;
+  await preflightReviewFileCollision(
+    opts.repoRoot,
+    config.reviewsDir,
+    planReviewTopic,
+    opts.force ?? false,
+  );
+
+  // Load the plan to review.
+  let planContent: string;
+  try {
+    planContent = await readFile(join(opts.repoRoot, opts.planPath), "utf8");
+  } catch (err) {
+    throw new Error(
+      `Could not read plan file at ${opts.planPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const runFolder = await createRunFolder({
+    repoRoot: opts.repoRoot,
+    runsDir: config.runsDir,
+    topic: planReviewTopic,
+    type: "review-plan",
+  });
+  const createdAt = new Date().toISOString();
+
+  const memory = await assembleMemory(opts.repoRoot, agentConfig.memoryFile);
+  const systemPrompt = PLAN_REVIEW_SYSTEM_FRAMING + "\n\n" + memory.text;
+  const userMessage = buildPlanReviewUserMessage(opts.topic, planContent);
+
+  await writeRunInput(runFolder.absPath, userMessage);
+
+  const adapterOut = await adapter.execute({
+    role: "reviewer",
+    systemPrompt,
+    userMessage,
+  });
+
+  await writeAgentOutput(runFolder.absPath, "reviewer", adapterOut.content);
+
+  // Shallow detection: same rule as diff reviews — need N concrete
+  // weaknesses with anchors.
+  const shallowWarning = detectShallowPlanReview(
+    adapterOut.content,
+    config.review.requireConcreteWeaknesses,
+  );
+
+  const writeOpts: Parameters<typeof writeHumanReviewFile>[0] = {
+    repoRoot: opts.repoRoot,
+    reviewsDir: config.reviewsDir,
+    topic: planReviewTopic,
+    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 git = await collectGitContext(opts.repoRoot);
+  await writeRunMetadata(runFolder.absPath, {
+    id: runFolder.id,
+    type: "review-plan",
+    createdAt,
+    finishedAt: new Date().toISOString(),
+    workspacePath: opts.repoRoot,
+    topic: planReviewTopic,
+    git,
+    input: { source: "requirement-file", path: opts.planPath },
+    agents: [
+      {
+        name: reviewerName,
+        role: "reviewer",
+        provider: agentConfig.provider,
+        enabled: true,
+      },
+    ],
+    adapterVersions: [],
+    status: "completed",
+    metrics: [
+      {
+        agent: reviewerName,
+        role: "reviewer",
+        provider: adapter.provider,
+        model: adapterOut.modelUsed,
+        tokensIn: adapterOut.tokensIn,
+        cachedTokensIn: adapterOut.cachedTokensIn ?? 0,
+        tokensOut: adapterOut.tokensOut,
+        costUsd: adapterOut.costUsd,
+        latencyMs: adapterOut.latencyMs,
+      },
+    ],
+    totals: {
+      tokensIn: adapterOut.tokensIn,
+      tokensOut: adapterOut.tokensOut,
+      costUsd: adapterOut.costUsd,
+      latencyMs: adapterOut.latencyMs,
+    },
+    reviewPath: written.path,
+    budget: {
+      maxCostPerRunUsd: config.budget.maxCostPerRunUsd,
+      maxTokensPerRun: config.budget.maxTokensPerRun,
+    },
+  });
+
+  const result: PlanReviewResult = {
+    reviewPath: written.path,
+    reviewBytes: written.bytes,
+    reviewer: reviewerName,
+    provider: adapter.provider,
+    modelUsed: adapterOut.modelUsed,
+    tokensIn: adapterOut.tokensIn,
+    cachedTokensIn: adapterOut.cachedTokensIn ?? 0,
+    tokensOut: adapterOut.tokensOut,
+    costUsd: adapterOut.costUsd,
+    latencyMs: adapterOut.latencyMs,
+    memorySources: memory.sources,
+    memoryMissing: memory.missing,
+    runId: runFolder.id,
+    runFolder: runFolder.relPath,
+  };
+  if (shallowWarning) result.shallowWarning = shallowWarning;
+  return result;
+}
+
+/** Same shallow heuristic as diff reviews — count file/step/line anchors. */
+function detectShallowPlanReview(
+  content: string,
+  requireConcreteWeaknesses: number,
+): string | undefined {
+  const anchorPattern = /\b(?:file|step|line|section)[:\s][\w\-./]+/gi;
+  const anchors = content.match(anchorPattern) ?? [];
+  const weaknessesSection = content.match(
+    /## Concrete Weaknesses([\s\S]*?)(?=##|$)/i,
+  );
+  const weaknessBullets =
+    weaknessesSection?.[1]?.match(/^\s*[-*\d.]/gm)?.length ?? 0;
+
+  if (anchors.length === 0) {
+    return "Plan review has zero anchored references (file / step / line). The Reviewer may not have engaged with specifics — consider re-running.";
+  }
+  if (weaknessBullets < requireConcreteWeaknesses) {
+    return `Plan review listed ${weaknessBullets} concrete weaknesses, fewer than the configured minimum of ${requireConcreteWeaknesses}. Output may be shallow — consider re-running with a more rigorous Reviewer.`;
+  }
+  return undefined;
+}