@flumecode/runner 0.19.0 → 0.20.0

package/dist/cli.js

@@ -26,8 +26,8 @@ function writeConfig(config) {
 }
 
 // src/run.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { join as join4 } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import { join as join5 } from "node:path";
 
 // src/version.ts
 import { readFileSync as readFileSync2 } from "node:fs";
@@ -203,51 +203,59 @@ var WIDGET_TOOL_NAMES = [
 ];
 var optionsSchema = z.array(z.string().min(1)).min(2).max(8).describe("2\u20138 short, distinct choices for the user to pick from. " + WIDGET_LANGUAGE_HINT);
 var TAIL = "Do NOT add an 'Other' or 'None of these' catch-all \u2014 the UI always offers an 'Other' free-text option automatically. " + WIDGET_LANGUAGE_HINT + " After calling this, END YOUR TURN and wait: the user's answer arrives as their next message and starts a fresh run.";
+var singleSelectShape = {
+  question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+var multiSelectShape = {
+  question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+function buildSingleSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "single_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionId: null,
+    customAnswer: null
+  };
+}
+function buildMultiSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "multi_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionIds: null,
+    customAnswer: null
+  };
+}
 function createWidgetTooling() {
   const collected = [];
   const singleSelect = tool(
     SINGLE_SELECT,
     "Ask the user a single-select (radio-button) question \u2014 exactly one answer. Use this for a genuine either/or choice (competing approaches, scope decisions, yes/no) instead of writing the options as prose. " + TAIL,
-    {
-      question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
-      body: z.string().optional().describe(
-        "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
-      ),
-      options: optionsSchema
-    },
+    singleSelectShape,
     async (args) => {
-      collected.push({
-        id: randomUUID(),
-        type: "single_select",
-        question: args.question,
-        body: args.body,
-        options: args.options.map((label) => ({ id: randomUUID(), label })),
-        selectedOptionId: null,
-        customAnswer: null
-      });
+      collected.push(buildSingleSelectWidget(args));
       return widgetPosted("single-select");
     }
   );
   const multiSelect = tool(
     MULTI_SELECT,
     "Ask the user a multi-select (checkbox) question \u2014 they may pick any number of options, including none of the presets if they use 'Other'. Use this for 'select all that apply' questions (which features to include, which files to touch). " + TAIL,
-    {
-      question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
-      body: z.string().optional().describe(
-        "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
-      ),
-      options: optionsSchema
-    },
+    multiSelectShape,
     async (args) => {
-      collected.push({
-        id: randomUUID(),
-        type: "multi_select",
-        question: args.question,
-        body: args.body,
-        options: args.options.map((label) => ({ id: randomUUID(), label })),
-        selectedOptionIds: null,
-        customAnswer: null
-      });
+      collected.push(buildMultiSelectWidget(args));
       return widgetPosted("multi-select");
     }
   );
@@ -321,6 +329,9 @@ var planInputSchema = {
   rootCause: z2.string().optional().describe(
     'For bug fixes (scope === "fix"): the underlying cause of the bug \u2014 the specific code, logic, or condition that produces the incorrect behavior, not just the symptom. Required when scope is "fix"; omit for all other scopes. ' + INLINE_CODE_HINT
   ),
+  motivation: z2.string().optional().describe(
+    "Why the user is making this request \u2014 the underlying motivation or problem the change addresses. Fill this especially when the request content/context does NOT already state the why (ask the user in the Clarify phase); omit when there is no additional motivation to record. Useful for future understanding of the system. " + INLINE_CODE_HINT
+  ),
   assumptions: z2.array(z2.string()).describe("Anything decided during planning, including unanswered defaults."),
   requirements: z2.array(z2.string().min(1)).min(1).describe(
     "Required, human-readable statements of what this change must accomplish and why, in plain language a non-technical reader can follow. Distinct from acceptanceCriteria: requirements explain intent/rationale; acceptance criteria are the machine-checkable proof. At least 1 required. " + INLINE_CODE_HINT
@@ -351,6 +362,11 @@ function renderPlan(plan) {
   lines2.push(`**Scope** \u2014 \`${plan.scope}\``);
   lines2.push("");
   lines2.push(`**Goal** \u2014 ${plan.goal}`);
+  if (plan.motivation && plan.motivation.trim().length > 0) {
+    lines2.push("");
+    lines2.push("## Motivation");
+    lines2.push(plan.motivation);
+  }
   if (plan.assumptions.length > 0) {
     lines2.push("");
     lines2.push("**Assumptions**");
@@ -426,7 +442,7 @@ function createPlanTooling() {
   let renderedPlans = null;
   const submitPlan = tool2(
     SUBMIT_PLAN,
-    `Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable Accept-as-plan draft. Do NOT call submit_plan more than once. acceptanceCriteria is required in each plan and must contain at least 2 observable, verifiable conditions. The 'title' field names each specific plan \u2014 make it concise and distinct from the request title and from sibling plan titles. requirements is required in each plan: at least 1 plain-language statement of what the change must accomplish and why (human-readable intent), separate from the machine-checkable acceptanceCriteria. When a plan's scope is "fix", rootCause is required: a non-empty explanation of the underlying cause of the bug (not just the symptom). `,
+    `Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable Accept-as-plan draft. Do NOT call submit_plan more than once. acceptanceCriteria is required in each plan and must contain at least 2 observable, verifiable conditions. The 'title' field names each specific plan \u2014 make it concise and distinct from the request title and from sibling plan titles. requirements is required in each plan: at least 1 plain-language statement of what the change must accomplish and why (human-readable intent), separate from the machine-checkable acceptanceCriteria. When a plan's scope is "fix", rootCause is required: a non-empty explanation of the underlying cause of the bug (not just the symptom). motivation is optional: the user's stated or asked-for reason for the request. `,
     submitPlanInputSchema,
     async (args) => {
       const parsed = submitPlanSchema.parse(args);
@@ -709,6 +725,87 @@ async function runClaudeCode(opts) {
   return { text: finalText, widgets: collected, plans: getPlans(), report: getReport() };
 }
 
+// src/codex.ts
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+var MCP_ENTRY = fileURLToPath3(new URL("./mcp-stdio.js", import.meta.url));
+async function runCodex(opts) {
+  const tmpDir = mkdtempSync(join2(tmpdir(), "flume-codex-"));
+  const outFile = join2(tmpDir, "flume-mcp.jsonl");
+  writeFileSync2(outFile, "");
+  const child = spawn(
+    "codex",
+    [
+      "exec",
+      "--cwd",
+      opts.cwd,
+      "-c",
+      `mcp_servers.flume.command=node`,
+      "-c",
+      `mcp_servers.flume.args=${JSON.stringify([MCP_ENTRY])}`,
+      opts.prompt
+    ],
+    {
+      cwd: opts.cwd,
+      env: { ...process.env, FLUME_MCP_OUTPUT: outFile },
+      // stdin is inherited (codex may read from it), stdout/stderr are piped for streaming
+      stdio: ["inherit", "pipe", "pipe"]
+    }
+  );
+  child.stdout?.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stdout.write(text);
+    logEvent("agent", text);
+  });
+  child.stderr?.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stderr.write(text);
+    logEvent("agent", text);
+  });
+  const onAbort = () => {
+    child.kill("SIGTERM");
+  };
+  opts.abortController?.signal.addEventListener("abort", onAbort, { once: true });
+  await new Promise((resolve, reject) => {
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        reject(
+          new Error(
+            "codex CLI not found. Install it with `npm install -g @openai/codex` and log in before running plan-mode jobs with an openai agent."
+          )
+        );
+      } else {
+        reject(err);
+      }
+    });
+    child.on("close", () => resolve());
+  });
+  opts.abortController?.signal.removeEventListener("abort", onAbort);
+  if (opts.abortController?.signal.aborted) {
+    throw new Error("Run canceled by user");
+  }
+  const raw = existsSync2(outFile) ? readFileSync3(outFile, "utf8") : "";
+  const records = raw.split("\n").filter(Boolean).map(parseJsonLine).filter((r) => r !== null);
+  const plans = records.filter((r) => r.kind === "plans").flatMap((r) => r.plans ?? []);
+  const widgets = records.filter((r) => r.kind === "widget").map((r) => r.widget);
+  return {
+    text: "",
+    widgets,
+    plans: plans.length > 0 ? plans : null,
+    report: null
+  };
+}
+function parseJsonLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
 // src/health.ts
 import { query as query2 } from "@anthropic-ai/claude-agent-sdk";
 var PROBE_TIMEOUT_MS = 6e4;
@@ -758,18 +855,23 @@ function errorMessage(err) {
 }
 
 // src/rules.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import { join as join2 } from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
-var RULES_DIR = fileURLToPath3(new URL("../skills-plugin/rules", import.meta.url));
+import { readFileSync as readFileSync4 } from "node:fs";
+import { join as join3 } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+var RULES_DIR = fileURLToPath4(new URL("../skills-plugin/rules", import.meta.url));
 function loadRule(name) {
-  const raw = readFileSync3(join2(RULES_DIR, `${name}.md`), "utf8");
+  const raw = readFileSync4(join3(RULES_DIR, `${name}.md`), "utf8");
   return stripFrontMatter(raw).trim();
 }
 function stripFrontMatter(raw) {
   const match = raw.match(/^---\n.*?\n---\n/s);
   return match ? raw.slice(match[0].length) : raw;
 }
+var SKILLS_DIR = fileURLToPath4(new URL("../skills-plugin/skills", import.meta.url));
+function loadSkill(name) {
+  const raw = readFileSync4(join3(SKILLS_DIR, name, "SKILL.md"), "utf8");
+  return stripFrontMatter(raw).trim();
+}
 
 // src/prompt.ts
 function appendRule(lines2, intro, ruleName) {
@@ -992,6 +1094,12 @@ function buildReleasePrompt(ctx, baseChecks) {
   );
   return lines2.join("\n");
 }
+function buildCodexPrompt(ctx) {
+  const skill = loadSkill("request-to-plan");
+  return ["# request-to-plan skill (follow these instructions)", skill, "", buildPrompt(ctx)].join(
+    "\n"
+  );
+}
 function buildInitPrompt(ctx) {
   return [
     `You are "${ctx.agentName}" initializing FlumeCode for the repository ${ctx.repo.fullName}, checked out in your current working directory.`,
@@ -1008,10 +1116,10 @@ function jobTitle(ctx) {
 
 // src/workspace.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 import { mkdtemp, readdir, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join as join3 } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join4 } from "node:path";
 import { promisify } from "node:util";
 var exec = promisify(execFile);
 var WORKSPACE_PREFIX = "flume-runner-";
@@ -1037,11 +1145,11 @@ function cloneUrl(ctx) {
   return `https://x-access-token:${cloneToken}@github.com/${owner}/${name}.git`;
 }
 function detectPackageManager(dir) {
-  if (!existsSync2(join3(dir, "package.json"))) return null;
-  if (existsSync2(join3(dir, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync2(join3(dir, "yarn.lock"))) return "yarn";
-  if (existsSync2(join3(dir, "package-lock.json"))) return "npm";
-  if (existsSync2(join3(dir, "bun.lockb"))) return "bun";
+  if (!existsSync3(join4(dir, "package.json"))) return null;
+  if (existsSync3(join4(dir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync3(join4(dir, "yarn.lock"))) return "yarn";
+  if (existsSync3(join4(dir, "package-lock.json"))) return "npm";
+  if (existsSync3(join4(dir, "bun.lockb"))) return "bun";
   return "npm";
 }
 async function installDependencies(dir) {
@@ -1067,13 +1175,13 @@ async function installDependencies(dir) {
   }
 }
 async function makeWorkspace() {
-  return mkdtemp(join3(tmpdir(), WORKSPACE_PREFIX));
+  return mkdtemp(join4(tmpdir2(), WORKSPACE_PREFIX));
 }
 var MAX_WORKSPACES = 8;
 var workspaceRegistry = /* @__PURE__ */ new Map();
 async function acquireWorkspace(key) {
   const existing = workspaceRegistry.get(key);
-  if (existing !== void 0 && existsSync2(existing)) {
+  if (existing !== void 0 && existsSync3(existing)) {
     workspaceRegistry.delete(key);
     workspaceRegistry.set(key, existing);
     return { dir: existing, reused: true };
@@ -1125,7 +1233,7 @@ async function prepareResumingBranch(ctx, dir, reused) {
   return { resumed: true };
 }
 async function sweepWorkspaces() {
-  const base = tmpdir();
+  const base = tmpdir2();
   let entries;
   try {
     entries = await readdir(base);
@@ -1136,7 +1244,7 @@ async function sweepWorkspaces() {
   for (const entry of entries) {
     if (!entry.startsWith(WORKSPACE_PREFIX)) continue;
     try {
-      await rm(join3(base, entry), { recursive: true, force: true });
+      await rm(join4(base, entry), { recursive: true, force: true });
       removed++;
     } catch {
     }
@@ -1533,8 +1641,14 @@ async function processChatJob(ctx, dir, config, abort) {
   console.log(`
 \u25B6 Job ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
   const orchestrating = ctx.permissionMode !== "plan";
+  const provider = ctx.provider ?? "anthropic";
+  if (provider === "openai" && orchestrating) {
+    throw new Error(
+      "Codex backend currently supports plan mode only. implement/revise/resolve/release jobs with an openai agent are not yet supported."
+    );
+  }
   const installResult = orchestrating ? await installDependencies(dir) : null;
-  const result = await runClaudeCode({
+  const result = provider === "openai" ? await runCodex({ cwd: dir, prompt: buildCodexPrompt(ctx), abortController: abort }) : await runClaudeCode({
     cwd: dir,
     prompt: buildPrompt(ctx),
     permissionMode: ctx.permissionMode,
@@ -1555,7 +1669,7 @@ async function processChatJob(ctx, dir, config, abort) {
     console.log(`  \u2026job ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync3(join4(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
   let documented = false;
   if (ctx.permissionMode !== "plan" && wikiExists && await hasChanges(dir)) {
     try {
@@ -1644,7 +1758,7 @@ ${reply}`;
 
 > \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
   }
-  const wikiExists = existsSync3(join4(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {
@@ -1700,7 +1814,7 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
     console.log(`  \u2026revise ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync3(join4(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {

package/dist/mcp-stdio.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/mcp-stdio.ts
+import { appendFileSync, writeFileSync, existsSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { toJSONSchema } from "zod/v4/core";
+import { z as z3 } from "zod";
+
+// src/plan.ts
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+
+// src/code-lang.ts
+var EXT_TO_LANG = {
+  ts: "typescript",
+  tsx: "tsx",
+  js: "javascript",
+  jsx: "jsx",
+  json: "json",
+  css: "css",
+  md: "markdown",
+  sh: "bash",
+  py: "python",
+  yaml: "yaml",
+  yml: "yaml",
+  html: "markup",
+  xml: "markup",
+  sql: "sql"
+};
+function langFromPath(path) {
+  const ext = path.split(".").pop()?.toLowerCase();
+  return ext ? EXT_TO_LANG[ext] : void 0;
+}
+
+// src/schema-hints.ts
+var INLINE_CODE_HINT = "Wrap code identifiers (function, variable, type, and file names, commands, and flags) in inline backticks, e.g. `getCodingSessionsForRequest`.";
+var WIDGET_LANGUAGE_HINT = "Write this in the same natural language as the incoming thread (the request body and the user's messages). If the thread is in English, keep it in English; do not switch languages. Keep code identifiers, file paths, and quoted code verbatim.";
+
+// src/plan.ts
+var SERVER_NAME = "flume_plan";
+var SUBMIT_PLAN = "submit_plan";
+var PLAN_TOOL_NAME = `mcp__${SERVER_NAME}__${SUBMIT_PLAN}`;
+var PLAN_MARKER = "<!-- flumecode:end-of-plan -->";
+var pseudoCodeEntrySchema = z.object({
+  file: z.string().min(1),
+  pseudoCode: z.string().min(1)
+});
+var stepSchema = z.object({
+  title: z.string().min(1).describe("A concise imperative title for this step."),
+  description: z.array(z.string().min(1)).min(1).describe(
+    "Bullet points that explain this step's change so a reviewer can judge whether the design is correct. Each array item is one short, self-contained bullet \u2014 not a single paragraph, and not a restatement of the pseudo code. " + INLINE_CODE_HINT
+  ),
+  pseudoCode: z.array(pseudoCodeEntrySchema).optional().describe(
+    "Per-file pseudo code. Provide an entry for every non-documentation file this step touches. Each entry contains the file path and pseudo code describing the changes to that file."
+  )
+});
+var planInputSchema = {
+  title: z.string().min(1).max(120).describe(
+    "A concise, descriptive name for THIS plan. Must be distinct from the request title and from any sibling plans on the same request. Keep it under 120 characters."
+  ),
+  scope: z.enum(["feat", "fix", "chore", "docs", "test", "refactor"]).describe("The primary intent of the change."),
+  goal: z.string().min(1).describe("One or two sentences stating the outcome. " + INLINE_CODE_HINT),
+  rootCause: z.string().optional().describe(
+    'For bug fixes (scope === "fix"): the underlying cause of the bug \u2014 the specific code, logic, or condition that produces the incorrect behavior, not just the symptom. Required when scope is "fix"; omit for all other scopes. ' + INLINE_CODE_HINT
+  ),
+  motivation: z.string().optional().describe(
+    "Why the user is making this request \u2014 the underlying motivation or problem the change addresses. Fill this especially when the request content/context does NOT already state the why (ask the user in the Clarify phase); omit when there is no additional motivation to record. Useful for future understanding of the system. " + INLINE_CODE_HINT
+  ),
+  assumptions: z.array(z.string()).describe("Anything decided during planning, including unanswered defaults."),
+  requirements: z.array(z.string().min(1)).min(1).describe(
+    "Required, human-readable statements of what this change must accomplish and why, in plain language a non-technical reader can follow. Distinct from acceptanceCriteria: requirements explain intent/rationale; acceptance criteria are the machine-checkable proof. At least 1 required. " + INLINE_CODE_HINT
+  ),
+  steps: z.array(stepSchema).min(1).describe("Ordered list of changes. Each step says what and why, with file references."),
+  acceptanceCriteria: z.array(z.string().min(1)).min(2).describe(
+    "Concrete, deterministically-checkable conditions that together define done. Each names a trigger/precondition and the exact observable result (run X -> output Y; file Z contains W; f(a) returns b) \u2014 no vague adjectives, not a restatement of a step. The set must collectively cover every step's change. At least 2 required. " + INLINE_CODE_HINT
+  ),
+  risks: z.array(z.string()).describe("Anything that could change the approach."),
+  outOfScope: z.array(z.string()).describe("What is deliberately not being done.")
+};
+function requireRootCauseForFix(schema) {
+  return schema.superRefine((plan, ctx) => {
+    if (plan.scope === "fix" && (plan.rootCause === void 0 || plan.rootCause.trim() === "")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["rootCause"],
+        message: 'rootCause is required and must be non-empty when scope is "fix".'
+      });
+    }
+  });
+}
+var planSchema = requireRootCauseForFix(z.object(planInputSchema));
+function renderPlan(plan) {
+  const lines = [];
+  lines.push(`# ${plan.title}`);
+  lines.push("");
+  lines.push(`**Scope** \u2014 \`${plan.scope}\``);
+  lines.push("");
+  lines.push(`**Goal** \u2014 ${plan.goal}`);
+  if (plan.motivation && plan.motivation.trim().length > 0) {
+    lines.push("");
+    lines.push("## Motivation");
+    lines.push(plan.motivation);
+  }
+  if (plan.assumptions.length > 0) {
+    lines.push("");
+    lines.push("**Assumptions**");
+    for (const assumption of plan.assumptions) {
+      lines.push(`- ${assumption}`);
+    }
+  }
+  if (plan.rootCause && plan.rootCause.trim().length > 0) {
+    lines.push("");
+    lines.push("## Root cause");
+    lines.push(plan.rootCause);
+  }
+  lines.push("");
+  lines.push("## Requirements");
+  for (const requirement of plan.requirements) {
+    lines.push(`- ${requirement}`);
+  }
+  lines.push("");
+  lines.push("## Steps");
+  for (const [i, step] of plan.steps.entries()) {
+    lines.push("");
+    lines.push(`### ${i + 1}. ${step.title}`);
+    lines.push("");
+    for (const bullet of step.description) {
+      lines.push(`- ${bullet}`);
+    }
+    if (step.pseudoCode && step.pseudoCode.length > 0) {
+      for (const entry of step.pseudoCode) {
+        lines.push("");
+        lines.push(`\`${entry.file}\``);
+        lines.push("");
+        const lang = langFromPath(entry.file);
+        lines.push(lang ? "```" + lang : "```");
+        lines.push(entry.pseudoCode);
+        lines.push("```");
+      }
+    }
+  }
+  lines.push("");
+  lines.push("## Acceptance criteria");
+  for (const criterion of plan.acceptanceCriteria) {
+    lines.push(`- [ ] ${criterion}`);
+  }
+  if (plan.risks.length > 0) {
+    lines.push("");
+    lines.push("**Risks / open questions**");
+    for (const risk of plan.risks) {
+      lines.push(`- ${risk}`);
+    }
+  }
+  if (plan.outOfScope.length > 0) {
+    lines.push("");
+    lines.push("**Out of scope**");
+    for (const item of plan.outOfScope) {
+      lines.push(`- ${item}`);
+    }
+  }
+  lines.push("");
+  lines.push(PLAN_MARKER);
+  return lines.join("\n");
+}
+var submitPlanInputSchema = {
+  plans: z.array(requireRootCauseForFix(z.object(planInputSchema))).min(1).refine(
+    (arr) => {
+      const titles = arr.map((p) => p.title.trim()).filter((t) => t.length > 0);
+      return new Set(titles).size === titles.length;
+    },
+    { message: "Each plan must have a distinct non-empty title" }
+  )
+};
+var submitPlanSchema = z.object(submitPlanInputSchema);
+
+// src/widgets.ts
+import { randomUUID } from "node:crypto";
+import { createSdkMcpServer as createSdkMcpServer2, tool as tool2 } from "@anthropic-ai/claude-agent-sdk";
+import { z as z2 } from "zod";
+var SERVER_NAME2 = "flume_widgets";
+var SINGLE_SELECT = "single_select";
+var MULTI_SELECT = "multi_select";
+var WIDGET_TOOL_NAMES = [
+  `mcp__${SERVER_NAME2}__${SINGLE_SELECT}`,
+  `mcp__${SERVER_NAME2}__${MULTI_SELECT}`
+];
+var optionsSchema = z2.array(z2.string().min(1)).min(2).max(8).describe("2\u20138 short, distinct choices for the user to pick from. " + WIDGET_LANGUAGE_HINT);
+var TAIL = "Do NOT add an 'Other' or 'None of these' catch-all \u2014 the UI always offers an 'Other' free-text option automatically. " + WIDGET_LANGUAGE_HINT + " After calling this, END YOUR TURN and wait: the user's answer arrives as their next message and starts a fresh run.";
+var singleSelectShape = {
+  question: z2.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z2.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+var multiSelectShape = {
+  question: z2.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z2.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+function buildSingleSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "single_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionId: null,
+    customAnswer: null
+  };
+}
+function buildMultiSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "multi_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionIds: null,
+    customAnswer: null
+  };
+}
+
+// src/mcp-stdio.ts
+var OUT = process.env.FLUME_MCP_OUTPUT;
+if (!OUT) {
+  console.error("FLUME_MCP_OUTPUT env var not set");
+  process.exit(1);
+}
+if (!existsSync(OUT)) {
+  writeFileSync(OUT, "");
+}
+function emit(rec) {
+  appendFileSync(OUT, JSON.stringify(rec) + "\n");
+}
+function ack(text) {
+  return { content: [{ type: "text", text }] };
+}
+function shapeToJsonSchema(shape) {
+  return toJSONSchema(z3.object(shape));
+}
+var TOOLS = [
+  {
+    name: "submit_plan",
+    description: "Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable plan draft. Do NOT call submit_plan more than once.",
+    inputSchema: toJSONSchema(submitPlanSchema)
+  },
+  {
+    name: "single_select",
+    description: "Ask the user a single-select (radio-button) question \u2014 exactly one answer.",
+    inputSchema: shapeToJsonSchema(singleSelectShape)
+  },
+  {
+    name: "multi_select",
+    description: "Ask the user a multi-select (checkbox) question \u2014 they may pick any number of options.",
+    inputSchema: shapeToJsonSchema(multiSelectShape)
+  }
+];
+var server = new Server({ name: "flume", version: "1" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  if (name === "submit_plan") {
+    const parsed = submitPlanSchema.parse(args);
+    emit({ kind: "plans", plans: parsed.plans.map(renderPlan) });
+    return ack("Plan(s) submitted. End your turn.");
+  }
+  if (name === "single_select") {
+    const parsed = z3.object(singleSelectShape).parse(args);
+    emit({ kind: "widget", widget: buildSingleSelectWidget(parsed) });
+    return ack("Question posted as a single-select widget. End your turn.");
+  }
+  if (name === "multi_select") {
+    const parsed = z3.object(multiSelectShape).parse(args);
+    emit({ kind: "widget", widget: buildMultiSelectWidget(parsed) });
+    return ack("Question posted as a multi-select widget. End your turn.");
+  }
+  throw new Error(`Unknown tool: ${name}`);
+});
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {
@@ -18,7 +18,7 @@
     "provenance": false
   },
   "scripts": {
-    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --packages=external --outfile=dist/cli.js --banner:js=\"#!/usr/bin/env node\"",
+    "build": "esbuild src/cli.ts src/mcp-stdio.ts --bundle --platform=node --format=esm --target=node20 --packages=external --outdir=dist --banner:js=\"#!/usr/bin/env node\"",
     "dev": "tsx src/cli.ts",
     "login": "tsx src/cli.ts login",
     "start": "tsx src/cli.ts start",
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
+    "@modelcontextprotocol/sdk": "^1",
     "zod": "4.4.3"
   },
   "devDependencies": {

package/skills-plugin/skills/request-to-plan/SKILL.md

@@ -34,7 +34,10 @@ and determine which phase you are in:**
    If the request is a bug fix, investigate deeply enough to identify the **root cause** (the specific code or condition producing the incorrect behavior) before proceeding to Plan — you will need it for the `rootCause` field.
 2. Identify genuine ambiguity only: scope, intended behavior, edge cases,
    competing approaches, acceptance criteria. Skip anything you can reasonably
-   decide yourself.
+   decide yourself. One high-leverage question is the user's motivation — **why** they
+   are making this request — but only when the request title/body and context don't
+   already explain it. Never re-ask what the thread already answers (consistent with
+   "Never ask what the code answers").
 3. End your turn with **2–5 specific, high-leverage questions**, each with a
    recommended default so the user can reply "all defaults" if they want. Group
    them; keep it short. Do **not** include a plan yet.
@@ -66,6 +69,7 @@ Field-by-field guidance:
   answers the request's title and body. Must be achievable by the steps below
   and nothing more.
 - **`rootCause`** — required when `scope` is `fix`; omit for all other scopes. Identify the underlying cause of the bug — the specific code, logic, or condition that produces the incorrect behavior, **not** the symptom. To fill this accurately, you must investigate the codebase deeply enough to find the root cause before writing the plan.
+- **`motivation`** — optional. The user's stated or asked-for reason for making this request — the underlying motivation or problem the change addresses. Fill this when the request content/context does NOT already state the why (ask during Phase 1 — Clarify if needed); omit when there is no additional motivation to record. Useful for future understanding of the system.
 - **`assumptions`** — anything you decided during investigation (including
   unanswered defaults from Phase 1).
 - **`requirements`** — **required; at least 1 item.** Plain-language statements of what this change must accomplish and why, written so a non-technical reader can follow them. Distinct from `acceptanceCriteria`: requirements explain intent and rationale; acceptance criteria are the machine-checkable proof. At least 1 item required.