@flumecode/runner 0.5.0 → 0.7.0

package/dist/cli.js

@@ -225,10 +225,16 @@ var SERVER_NAME2 = "flume_plan";
 var SUBMIT_PLAN = "submit_plan";
 var PLAN_TOOL_NAME = `mcp__${SERVER_NAME2}__${SUBMIT_PLAN}`;
 var PLAN_MARKER = "<!-- flumecode:end-of-plan -->";
+var pseudoCodeEntrySchema = z2.object({
+  file: z2.string().min(1),
+  pseudoCode: z2.string().min(1)
+});
 var stepSchema = z2.object({
-  change: z2.string().min(1).describe("What changes, with concrete file references."),
-  why: z2.string().min(1).describe("The reason for this step."),
-  files: z2.array(z2.string()).optional().describe("Affected file paths.")
+  title: z2.string().min(1).describe("A concise imperative title for this step."),
+  description: z2.string().min(1).describe("What changes and why \u2014 the rationale for this step."),
+  pseudoCode: z2.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: z2.string().min(1).max(120).describe(
@@ -260,12 +266,20 @@ function renderPlan(plan) {
     }
   }
   lines.push("");
-  lines.push("**Steps**");
+  lines.push("## Steps");
   for (const [i, step] of plan.steps.entries()) {
-    lines.push(`${i + 1}. **${step.change}** \u2014 ${step.why}`);
-    if (step.files && step.files.length > 0) {
-      for (const file of step.files) {
-        lines.push(`   - \`${file}\``);
+    lines.push("");
+    lines.push(`### ${i + 1}. ${step.title}`);
+    lines.push("");
+    lines.push(step.description);
+    if (step.pseudoCode && step.pseudoCode.length > 0) {
+      for (const entry of step.pseudoCode) {
+        lines.push("");
+        lines.push(`\`${entry.file}\``);
+        lines.push("");
+        lines.push("```");
+        lines.push(entry.pseudoCode);
+        lines.push("```");
       }
     }
   }
@@ -572,6 +586,33 @@ function buildRepairPrompt(ctx, hookLog) {
   ];
   return lines.join("\n");
 }
+function buildReleasePrompt(ctx) {
+  const task = `Use the \`flumecode:create-release\` skill to handle this turn. You are driving a release: first analyse commits since the last tag, propose version bumps, and ask the user to confirm via widgets (Phase 1); once the user's widget answers appear in the thread, apply the bumps to package.json files and update CHANGELOG.md (Phase 2). Do NOT commit or push \u2014 the runner handles that and opens the bump PR.`;
+  const orient = `Before investigating raw source, check for a FlumeCode wiki at \`.flumecode/wiki/\`. If it exists, read \`.flumecode/wiki/README.md\` first \u2014 it is the index \u2014 and follow its links to the pages and source paths relevant to this release. If there is no wiki, work from the code directly.`;
+  const widgets = `When you need the user to choose, ask it as a widget rather than writing the options as prose: call \`single_select\` for a one-of-N choice (radio buttons) or \`multi_select\` for a "select all that apply" choice (checkboxes). Don't add your own "Other" option \u2014 the UI always provides one. After calling a widget tool, end your turn \u2014 the user's answer comes back as their next message and starts a fresh run.`;
+  const lines = [
+    `You are "${ctx.agentName}", an autonomous coding agent driving a FlumeCode release.`,
+    `The repository ${ctx.repo.fullName} is checked out in your current working directory on the release bump branch "${ctx.repo.checkoutBranch}".`,
+    task,
+    orient,
+    widgets,
+    "",
+    "These coding guidelines apply to all code produced in this run:",
+    "",
+    loadRule("coding-guideline"),
+    "",
+    `# Release: ${ctx.request?.title ?? ""}`
+  ];
+  if (ctx.request?.body) {
+    lines.push("", ctx.request.body);
+  }
+  appendThread(lines, ctx);
+  lines.push(
+    "",
+    "Your final reply is posted verbatim as your comment in the release thread \u2014 if you called widgets (Phase 1), your reply text accompanies the questions; if you applied the bumps (Phase 2), make it the report the skill produced. The runner appends the pull-request link."
+  );
+  return lines.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.`,
@@ -761,14 +802,15 @@ async function rebaseOntoMergeBranch(ctx, dir) {
   if (!mergeBranch) return;
   await git(["-C", dir, "fetch", "--quiet", "origin", mergeBranch]);
   try {
-    await git(["-C", dir, "rebase", "FETCH_HEAD"]);
-  } catch {
+    await git(["-C", dir, "rebase", "--empty=drop", "FETCH_HEAD"]);
+  } catch (err) {
     const conflicted = await git(["-C", dir, "diff", "--name-only", "--diff-filter=U"]).catch(
       () => ({ stdout: "" })
     );
     const files = conflicted.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
     await git(["-C", dir, "rebase", "--abort"]).catch(() => {
     });
+    if (files.length === 0) throw err;
     throw new RebaseConflictError(mergeBranch, files);
   }
 }
@@ -854,11 +896,44 @@ var HEARTBEAT_MS = 5 * 6e4;
 async function pushAndOpenPr(ctx, dir, abort, opts = { rebase: true }) {
   if (abort.signal.aborted) throw new Error("Run canceled by user");
   const committed = await commitWithRepair(ctx, dir, abort);
-  if (!committed) return { kind: "none" };
-  if (opts.rebase) await rebaseOntoMergeBranch(ctx, dir);
+  if (!committed) return { outcome: { kind: "none" }, autoMerged: false };
+  let autoMerged = false;
+  if (opts.rebase) {
+    try {
+      await rebaseOntoMergeBranch(ctx, dir);
+    } catch (err) {
+      if (!(err instanceof RebaseConflictError)) throw err;
+      if (abort.signal.aborted) throw new Error("Run canceled by user");
+      console.warn(
+        `  rebase onto ${ctx.repo.mergeBranch} conflicted \u2014 merging it in and resolving with the agent\u2026`
+      );
+      await mergeAndResolveConflicts(ctx, dir, abort);
+      await commitWithRepair(ctx, dir, abort);
+      autoMerged = true;
+    }
+  }
   await pushBranch(ctx, dir);
   const pr = await openPullRequest(ctx);
-  return pr ? { kind: "pr", pr } : { kind: "pushed" };
+  return { outcome: pr ? { kind: "pr", pr } : { kind: "pushed" }, autoMerged };
+}
+async function mergeAndResolveConflicts(ctx, dir, abort) {
+  const { conflicted } = await mergeInMergeBranch(ctx, dir);
+  if (!conflicted) return { resolved: false, text: null };
+  const result = await runClaudeCode({
+    cwd: dir,
+    prompt: buildResolvePrompt(ctx),
+    permissionMode: ctx.permissionMode,
+    model: ORCHESTRATOR_MODEL,
+    maxTurns: ORCHESTRATOR_MAX_TURNS,
+    abortController: abort
+  });
+  const unresolved = await listUnmergedPaths(dir);
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Could not fully resolve the merge \u2014 ${unresolved.length} file(s) still conflict: ${unresolved.join(", ")}`
+    );
+  }
+  return { resolved: true, text: result.text.trim() || null };
 }
 async function commitWithRepair(ctx, dir, abort) {
   for (let attempt = 1; ; attempt++) {
@@ -882,17 +957,18 @@ async function commitWithRepair(ctx, dir, abort) {
 }
 function outcomeBanner(outcome, opts) {
   const wikiNote = opts.documented ? " (with wiki updates)" : "";
+  const mergeNote = opts.autoMerged ? "\n\u{1F500} The base branch had advanced with conflicting changes \u2014 merged it in and resolved the conflicts automatically." : "";
   switch (outcome.kind) {
     case "pr":
       return `
 
 ---
-\u2705 Opened pull request from \`${opts.branch}\`${wikiNote} \xB7 [View pull request](${outcome.pr.url})`;
+\u2705 Opened pull request from \`${opts.branch}\`${wikiNote} \xB7 [View pull request](${outcome.pr.url})${mergeNote}`;
     case "pushed":
       return `
 
 ---
-\u26A0\uFE0F Pushed \`${opts.branch}\`${wikiNote}, but couldn't open a pull request (no diff against the base branch, or one is already open).`;
+\u26A0\uFE0F Pushed \`${opts.branch}\`${wikiNote}, but couldn't open a pull request (no diff against the base branch, or one is already open).${mergeNote}`;
     case "none":
       return `
 
@@ -924,6 +1000,11 @@ async function processJob(ctx, abort = new AbortController()) {
       prepared = true;
       return await processResolveJob(ctx, dir, abort);
     }
+    if (ctx.kind === "release") {
+      const { resumed } = await prepareResumingBranch(ctx, dir, reused);
+      prepared = true;
+      return await processReleaseJob(ctx, dir, resumed, abort);
+    }
     await prepareAtSha(ctx, dir, reused);
     prepared = true;
     return await processChatJob(ctx, dir, abort);
@@ -947,10 +1028,11 @@ async function processInitJob(ctx, dir, abort) {
     abortController: abort
   })).text.trim();
   let reply = summary || "(the agent produced no summary)";
-  const outcome = await pushAndOpenPr(ctx, dir, abort);
+  const { outcome, autoMerged } = await pushAndOpenPr(ctx, dir, abort);
   reply += outcomeBanner(outcome, {
     branch: ctx.repo.checkoutBranch,
-    noChange: "no files were generated; the wiki may already exist."
+    noChange: "no files were generated; the wiki may already exist.",
+    autoMerged
   });
   return { text: reply, widgets: [] };
 }
@@ -996,8 +1078,8 @@ async function processChatJob(ctx, dir, abort) {
       console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
     }
   }
-  const outcome = await pushAndOpenPr(ctx, dir, abort);
-  reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
+  const { outcome, autoMerged } = await pushAndOpenPr(ctx, dir, abort);
+  reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented, autoMerged });
   return { text: reply, widgets: [] };
 }
 async function processImplementJob(ctx, dir, resumed, abort) {
@@ -1034,8 +1116,8 @@ async function processImplementJob(ctx, dir, resumed, abort) {
       console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
     }
   }
-  const outcome = await pushAndOpenPr(ctx, dir, abort, { rebase: !resumed });
-  reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
+  const { outcome, autoMerged } = await pushAndOpenPr(ctx, dir, abort, { rebase: !resumed });
+  reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented, autoMerged });
   return { text: reply, widgets: [], ...outcome.kind === "pr" ? { pr: outcome.pr } : {} };
 }
 async function processReviseJob(ctx, dir, resumed, abort) {
@@ -1078,9 +1160,9 @@ async function processReviseJob(ctx, dir, resumed, abort) {
       console.warn(`  wiki update skipped: ${errorMessage2(err)}`);
     }
   }
-  const outcome = await pushAndOpenPr(ctx, dir, abort, { rebase: !resumed });
+  const { outcome, autoMerged } = await pushAndOpenPr(ctx, dir, abort, { rebase: !resumed });
   if (outcome.kind !== "none") {
-    reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented });
+    reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented, autoMerged });
   }
   return {
     text: reply,
@@ -1093,27 +1175,8 @@ async function processResolveJob(ctx, dir, abort) {
   console.log(`
 \u25B6 Resolve ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
   const installResult = await installDependencies(dir);
-  const { conflicted } = await mergeInMergeBranch(ctx, dir);
-  let reply;
-  if (conflicted) {
-    const result = await runClaudeCode({
-      cwd: dir,
-      prompt: buildResolvePrompt(ctx),
-      permissionMode: ctx.permissionMode,
-      model: ORCHESTRATOR_MODEL,
-      maxTurns: ORCHESTRATOR_MAX_TURNS,
-      abortController: abort
-    });
-    reply = result.text.trim() || "(the agent produced no report)";
-    const unresolved = await listUnmergedPaths(dir);
-    if (unresolved.length > 0) {
-      throw new Error(
-        `Could not fully resolve the merge \u2014 ${unresolved.length} file(s) still conflict: ${unresolved.join(", ")}`
-      );
-    }
-  } else {
-    reply = `Merged \`${ctx.repo.mergeBranch ?? "the merge branch"}\` into \`${ctx.repo.checkoutBranch}\` cleanly \u2014 there were no conflicts to resolve.`;
-  }
+  const { resolved, text } = await mergeAndResolveConflicts(ctx, dir, abort);
+  let reply = resolved ? text || "(the agent produced no report)" : `Merged \`${ctx.repo.mergeBranch ?? "the merge branch"}\` into \`${ctx.repo.checkoutBranch}\` cleanly \u2014 there were no conflicts to resolve.`;
   if (installResult.status === "failed") {
     reply += `
 
@@ -1127,6 +1190,40 @@ async function processResolveJob(ctx, dir, abort) {
   reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch });
   return { text: reply, widgets: [], ...pr ? { pr } : {} };
 }
+async function processReleaseJob(ctx, dir, resumed, abort) {
+  console.log(`
+\u25B6 Release ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
+  const installResult = await installDependencies(dir);
+  const result = await runClaudeCode({
+    cwd: dir,
+    prompt: buildReleasePrompt(ctx),
+    permissionMode: ctx.permissionMode,
+    model: ORCHESTRATOR_MODEL,
+    maxTurns: ORCHESTRATOR_MAX_TURNS,
+    abortController: abort
+  });
+  let reply = result.text.trim() || "(the agent produced no reply)";
+  if (installResult.status === "failed") {
+    reply += `
+
+> \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
+  }
+  if (result.widgets.length > 0) {
+    console.log(
+      `  \u2026release ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`
+    );
+    return { text: reply, widgets: result.widgets };
+  }
+  const { outcome, autoMerged } = await pushAndOpenPr(ctx, dir, abort, { rebase: !resumed });
+  if (outcome.kind !== "none") {
+    reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, autoMerged });
+  }
+  return {
+    text: reply,
+    widgets: [],
+    ...outcome.kind === "pr" ? { pr: outcome.pr } : {}
+  };
+}
 async function heartbeat(config) {
   const health = await checkClaudeCode();
   if (health.ready) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {

package/skills-plugin/skills/create-release/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: create-release
+description: >-
+  Draft release notes and version suggestions for a release, then (after the
+  user confirms) open a bump PR that updates package.json version(s) and
+  CHANGELOG.md. Two-turn flow: first turn asks the user to confirm versions via
+  widgets; second turn (answers in thread) writes the bumps and opens the PR.
+---
+
+# create-release
+
+You are driving a FlumeCode release. This skill has two distinct phases; detect
+which one applies before acting.
+
+## Phase detection
+
+Check the thread (`# Conversation so far` in the prompt). If **no widget answers**
+appear in any prior agent turn, this is **Phase 1** — propose versions and ask.
+If a prior turn contains widget-answer selections (the user picked a version), this
+is **Phase 2** — apply the bumps and report.
+
+---
+
+## Phase 1 — Propose versions and ask
+
+### 1. Find the last release tags
+
+For `@flumecode/web`, find the most recent `v*` tag:
+
+```
+git tag -l --sort=-version:refname 'v*' | head -1
+```
+
+For `@flumecode/runner`, find the most recent `runner-v*` tag:
+
+```
+git tag -l --sort=-version:refname 'runner-v*' | head -1
+```
+
+If no matching tag exists for a package, treat the current version in that
+package's `package.json` as the baseline.
+
+### 2. List commits since the last tag, split by package
+
+Get all commits since the tag (or all commits if no tag):
+
+```
+git log <lastWebTag>..HEAD --oneline
+```
+
+Then split by what they touch:
+
+```
+# web + shared packages
+git log <lastWebTag>..HEAD --oneline -- apps/web/ packages/
+
+# runner only
+git log <lastRunnerTag>..HEAD --oneline -- apps/runner/
+```
+
+If a package has no commits, mark it **unchanged** — do not bump it.
+
+### 3. Infer bump level per package
+
+For each package that has commits:
+
+- `feat:` in a commit subject, or any breaking change → **minor** (or major if
+  explicitly breaking).
+- `fix:`, `chore:`, `docs:`, `refactor:`, `test:` → **patch**.
+- When in doubt, default to **patch**.
+
+### 4. Compute suggested next versions
+
+Read current versions from `apps/web/package.json` and `apps/runner/package.json`.
+Apply the inferred bump (semver: patch = last digit +1, minor = middle digit +1 +
+reset patch to 0). For unchanged packages, keep the current version.
+
+### 5. Draft concise release notes
+
+3–10 user-readable bullet points summarising what changed. Group by theme; skip
+internal chore commits unless they affect the user.
+
+### 6. Ask the user to confirm
+
+For **each package that has commits** (skip unchanged ones), call
+`mcp__flume_widgets__single_select` with:
+
+- `question`: e.g. `@flumecode/web version for this release?`
+- `options`: the suggested next version, plus the two sibling semver levels (e.g.
+  if patch suggested: also offer minor and major), plus the current version as
+  "No change (keep X.Y.Z)".
+
+Also present the drafted release notes in your reply text so the user can read
+them, then call `mcp__flume_widgets__single_select` for a confirmatory question:
+`Do the release notes look correct?` with options `Yes, use these notes` and
+`I'll edit them in the PR`.
+
+**After calling widgets, end your turn.** Do NOT open a PR in Phase 1.
+
+---
+
+## Phase 2 — Apply the bumps and report
+
+### 1. Read the widget answers
+
+The user's confirmed version selections appear in the `# Conversation so far`
+thread as agent messages (the widget-answer turn). Extract the chosen version for
+each package from those selections.
+
+### 2. Update package.json files
+
+For each package whose version changed, edit the `"version"` field in:
+
+- `apps/web/package.json` — for `@flumecode/web`
+- `apps/runner/package.json` — for `@flumecode/runner`
+
+Change only the `"version"` line; do not reformat the file.
+
+### 3. Update CHANGELOG.md
+
+Edit (or create) `CHANGELOG.md` at the repo root. Insert a new section at the
+top, below any existing `# Changelog` title line:
+
+```
+## [X.Y.Z / runner-X.Y.Z] - YYYY-MM-DD
+
+- Bullet point from release notes
+- Another bullet point
+```
+
+Use the ISO date format (`YYYY-MM-DD`). Preserve all existing entries — do not
+delete or rewrite prior sections.
+
+If both packages are bumped, list both versions in the heading (e.g.
+`## [0.9.0 / runner-0.5.0] - 2026-06-06`). If only one package is bumped, list
+only that version in the heading.
+
+### 4. Stop — do not commit or push
+
+Leave the edited files in the working tree. The runner commits them and opens the
+pull request.
+
+### 5. End with this exact report format
+
+Your final message must match this shape (adjust versions and files to match what
+actually changed):
+
+```
+**Bumped versions:**
+- `@flumecode/web`: `0.8.0` → `0.9.0`
+- `@flumecode/runner`: `0.4.0` → `0.5.0`
+
+**CHANGELOG updated** with release notes.
+
+**Files changed:** `apps/web/package.json`, `apps/runner/package.json`, `CHANGELOG.md`
+
+<!-- flumecode:versions {"@flumecode/web":"0.9.0","@flumecode/runner":"0.5.0"} -->
+```
+
+The `<!-- flumecode:versions {...} -->` comment is machine-readable and **must be
+the last line** of your message body (before any trailing newline). The runner
+reads it to persist the confirmed versions on the release entity. Use the exact
+JSON key names `@flumecode/web` and `@flumecode/runner`; omit a package if its
+version did not change.
+
+---
+
+## Notes
+
+- **Runner-only bump:** if only `apps/runner/` has commits, bump only
+  `apps/runner/package.json`. Leave `apps/web/package.json` unchanged.
+- **Clear Phase 1 text:** be explicit about what changed since the last tag so the
+  user can confidently confirm or override your suggestions.
+- **Never edit** any file other than `apps/web/package.json`,
+  `apps/runner/package.json`, and `CHANGELOG.md`.
+- **Never commit, push, or open a PR** — the runner does that.

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

@@ -66,9 +66,10 @@ Field-by-field guidance:
   and nothing more.
 - **`assumptions`** — anything you decided during investigation (including
   unanswered defaults from Phase 1).
-- **`steps`** — an ordered list. For each step: what changes (`change`), why
-  (`why`), and optionally which files are affected (`files`). Use concrete file
-  references (`path/to/file.ts`) and name the functions/symbols involved.
+- **`steps`** — an ordered list. For each step provide:
+  - **`title`** — a concise imperative phrase naming the step (e.g. "Add submit_plan schema to plan.ts").
+  - **`description`** — what changes and why: the concrete change being made and the rationale for it. Use concrete file references (`path/to/file.ts`) and name the functions/symbols involved.
+  - **`pseudoCode`** — an array of `{ file, pseudoCode }` entries. Provide an entry for every file the step touches **except** documentation files (SKILL.md, README.md, wiki pages, etc.). `pseudoCode` is optional in the schema but expected for all non-documentation files. Each entry names the file path and contains pseudo code that precisely describes the changes to make in that file.
 - **`acceptanceCriteria`** — **required; at least 2 items.** Each criterion must
   be an observable condition you could check after the work is done: a behavior,
   a test result, or a verifiable state. Together they must fully define "done" —