@almightygpt/core 0.9.1 → 0.10.0

package/src/plan/run-plan.ts

@@ -0,0 +1,247 @@
+/**
+ * `almightygpt plan` — Worker AI reads a free-text requirement +
+ * project memory, produces a structured plan markdown.
+ *
+ * Distinct from the review pipeline because the INPUT is a
+ * requirement (a sentence or paragraph from the user describing
+ * what they want), not a git diff. Output is a plan doc with
+ * required sections — same shape on every run so the Reviewer
+ * downstream knows what to expect.
+ *
+ * Plans land at `docs/<worker>-plans/<topic>.md`. The Reviewer step
+ * then runs against this plan via the `review --plan <file>` mode
+ * (see run-plan-review.ts).
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, 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 { assertSafeToWrite } from "../git/status.js";
+
+export interface PlanOptions {
+  repoRoot: string;
+  topic: string;
+  requirement: string;
+  worker?: string;
+  force?: boolean;
+}
+
+export interface PlanResult {
+  planPath: string;
+  planBytes: number;
+  worker: 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;
+}
+
+const PLAN_SYSTEM_FRAMING = [
+  "You are the Worker AI in an AlmightyGPT Plan stage.",
+  "",
+  "WHAT YOU ARE DOING: turning a free-text requirement (the user message",
+  "below) into a structured plan markdown that a Reviewer AI will then",
+  "critique. You are NOT writing code — only the plan. The human will",
+  "approve / reject / refine the plan, and only then will implementation",
+  "happen (in a separate tool).",
+  "",
+  "WHAT THE ORCHESTRATOR OWNS (do NOT include these in your response):",
+  "  - The H1 title (the orchestrator prepends `# Plan: <topic>`).",
+  "  - The header block with model / tokens / cost.",
+  "",
+  "WHAT YOU MUST PRODUCE — emit exactly these sections in this order:",
+  "  ## Goal",
+  "  ## Affected modules / surfaces",
+  "  ## Step-by-step approach",
+  "  ## Risks",
+  "  ## Test plan",
+  "  ## Open questions",
+  "",
+  "STYLE:",
+  "  - Be concrete. Name specific files, classes, functions, env vars.",
+  "  - Write so the Reviewer can find concrete things to critique.",
+  "  - Open questions are not a weakness; they're the things you'd ask",
+  "    the human if you could. Surface them.",
+].join("\n");
+
+function buildPlanUserMessage(topic: string, requirement: string): string {
+  return [
+    `# Plan request — topic: \`${topic}\``,
+    "",
+    "## Requirement (from human)",
+    "",
+    requirement.trim(),
+    "",
+    "## Your task",
+    "",
+    "Produce the plan markdown using the structure in your system prompt.",
+    "Start your response with `## Goal` (no H1, no preamble).",
+  ].join("\n");
+}
+
+export async function runWorkerPlan(opts: PlanOptions): Promise<PlanResult> {
+  const config = await loadConfig(opts.repoRoot);
+
+  const workerName = opts.worker ?? config.defaults.worker;
+  if (!workerName) {
+    throw new Error(
+      "No worker specified. Pass --worker <name> or set defaults.worker in .almightygpt/config.yaml.",
+    );
+  }
+  const agentConfig = config.agents[workerName];
+  if (!agentConfig) {
+    throw new Error(
+      `Worker "${workerName}" not found in .almightygpt/config.yaml agents map.`,
+    );
+  }
+  if (!agentConfig.enabled) {
+    throw new Error(`Worker "${workerName}" is disabled in .almightygpt/config.yaml.`);
+  }
+
+  const adapter = makeAdapter(workerName, agentConfig.provider);
+  if (!(await adapter.isAvailable())) {
+    throw new AdapterError(
+      `Adapter "${workerName}" (${agentConfig.provider}) is not available. Set the provider's API key.`,
+      workerName,
+    );
+  }
+
+  // Plans land at docs/<worker>-plans/<topic>.md — symmetric with reviews.
+  const plansDir = `docs/${workerName}-plans`;
+  const planRel = `${plansDir}/${opts.topic}.md`;
+  await assertSafeToWrite(opts.repoRoot, planRel, opts.force ?? false);
+
+  const runFolder = await createRunFolder({
+    repoRoot: opts.repoRoot,
+    runsDir: config.runsDir,
+    topic: opts.topic,
+    type: "plan",
+  });
+  const createdAt = new Date().toISOString();
+
+  const memory = await assembleMemory(opts.repoRoot, agentConfig.memoryFile);
+  const systemPrompt = PLAN_SYSTEM_FRAMING + "\n\n" + memory.text;
+  const userMessage = buildPlanUserMessage(opts.topic, opts.requirement);
+
+  await writeRunInput(runFolder.absPath, userMessage);
+
+  const adapterOut = await adapter.execute({
+    role: "worker",
+    systemPrompt,
+    userMessage,
+  });
+
+  await writeAgentOutput(runFolder.absPath, "worker", adapterOut.content);
+
+  // Compose the final plan file: orchestrator-owned header + worker body.
+  const header = [
+    `# Plan: ${opts.topic}`,
+    "",
+    `> Worker: \`${workerName}\` (${adapter.provider}, ${adapterOut.modelUsed})`,
+    `> Generated: ${new Date().toISOString()}`,
+    `> Tokens: ${adapterOut.tokensIn} in / ${adapterOut.tokensOut} out`,
+    `> Cost: $${adapterOut.costUsd.toFixed(4)} USD`,
+    `> Run folder: \`${runFolder.relPath}\``,
+    "",
+  ].join("\n");
+
+  const footer = [
+    "",
+    "---",
+    "",
+    "## How this plan was produced",
+    "",
+    `The AlmightyGPT Plan stage produced this. Worker (\`${workerName}\`)`,
+    `read the requirement above + the project's memory files.`,
+    "",
+    "**Next stage:** cross-AI review with `almightygpt review --plan",
+    `${planRel} --reviewer codex --topic ${opts.topic}\` (Reviewer critiques`,
+    "this plan), then human approval, then implementation in your",
+    "preferred coding tool.",
+  ].join("\n");
+
+  const planContent = header + adapterOut.content.trim() + footer;
+  const planAbs = join(opts.repoRoot, planRel);
+  await mkdir(dirname(planAbs), { recursive: true });
+  await writeFile(planAbs, planContent, "utf8");
+
+  const gitContext = await collectGitContext(opts.repoRoot);
+  await writeRunMetadata(runFolder.absPath, {
+    id: runFolder.id,
+    type: "plan",
+    createdAt,
+    finishedAt: new Date().toISOString(),
+    workspacePath: opts.repoRoot,
+    topic: opts.topic,
+    git: gitContext,
+    input: { source: "requirement-file" },
+    agents: [
+      {
+        name: workerName,
+        role: "worker",
+        provider: agentConfig.provider,
+        enabled: true,
+      },
+    ],
+    adapterVersions: [],
+    status: "completed",
+    metrics: [
+      {
+        agent: workerName,
+        role: "worker",
+        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: planRel,
+    budget: {
+      maxCostPerRunUsd: config.budget.maxCostPerRunUsd,
+      maxTokensPerRun: config.budget.maxTokensPerRun,
+    },
+  });
+
+  return {
+    planPath: planRel,
+    planBytes: planContent.length,
+    worker: workerName,
+    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,
+  };
+}

package/src/runs/types.ts

@@ -14,7 +14,9 @@ export type RunType =
   | "review-diff"
   | "review-path"
   | "review-requirement"
-  | "review-worker-reviewer";
+  | "review-worker-reviewer"
+  | "plan"
+  | "review-plan";
 
 export type RunStatus = "running" | "completed" | "failed" | "aborted_budget";