diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a50a9b..e54c478 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.0] - 2026-08-17 + +### Added + +- **A run interrupted mid-flight can be resumed from the entry command.** A long + workflow will be interrupted: a session limit, a closed laptop, a crash. Its + state was already intact and already pointed at the step it was about to take, + and SPEC section 3.5 already said "one static command therefore serves both a + fresh run and a run resumed at any node", which is how gate resume has always + worked. Nothing was wired to it for an interrupted run, so the work was simply + lost. Running the entry command again now picks the run up where it stopped and + reports what it resumed. + + Resuming is the default, because the expensive mistake is redoing work rather + than continuing it. `--new` starts a fresh run and leaves the stopped one + alone. The auto flag is carried rather than re-read, so a run cannot change + halfway about whether a human is behind it. A run whose graph hash no longer + matches is refused rather than resumed against nodes that may have moved, and + several stopped runs are named rather than guessed between. A run stopped + mid-ask is reported as needing its answers, not resumed past them. + +- The entry command now always carries an `argument-hint`, since every workflow + can be interrupted and therefore resumed. + ## [0.1.4] - 2026-08-17 ### Fixed @@ -168,7 +192,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 Vitest test suite, and GitHub Actions for CI and publishing. - Placeholder release reserving the `minflow` package name on npm. -[Unreleased]: https://github.com/minlayer/minflow/compare/v0.1.4...HEAD +[Unreleased]: https://github.com/minlayer/minflow/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/minlayer/minflow/compare/v0.1.4...v0.2.0 [0.1.4]: https://github.com/minlayer/minflow/compare/v0.1.3...v0.1.4 [0.1.3]: https://github.com/minlayer/minflow/compare/v0.1.2...v0.1.3 [0.1.2]: https://github.com/minlayer/minflow/compare/v0.1.1...v0.1.2 diff --git a/README.md b/README.md index 5636696..a9c7d74 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,23 @@ Every compiled workflow also accepts `--auto` on its entry command, which answer its own questions and runs unattended. It is the same mechanism either way, so an unattended run exercises the real ask path rather than a mode that skips it. +### A run you can pick back up + +A long workflow will be interrupted. A session limit, a closed laptop, a crash. +Running the entry command again **resumes where it stopped** and says so, rather +than starting over: + +``` +resuming run run-20260817045146-b71a96 at step "draft-findings", 12 steps in. +Everything already finished is kept. Pass --new to start over instead. +``` + +Resuming is the default because the expensive mistake is redoing work, not +continuing it. `--new` starts fresh and leaves the stopped run alone. A run whose +graph has changed underneath it is refused rather than resumed against nodes that +may have moved, and when several runs are stopped it names them instead of +guessing. + ### Sign-off that actually blocks `wf.gate()` parks the run and waits for a human to release it, across sessions if @@ -205,9 +222,10 @@ registrations are scoped so that nothing fires during unrelated work. ## Status Working: the builder, the IR, the graph lint, the transition evaluator, run -context interpolation, command nodes, interactive asks, auto mode, skills shipped -inside the plugin, skill validation, Mermaid output, generated tests, and the -Claude Code backend. 640 tests, none of which need a model. +context interpolation, command nodes, interactive asks, auto mode, resuming an +interrupted run, skills shipped inside the plugin, skill validation, Mermaid +output, generated tests, and the Claude Code backend. 646 tests, none of which +need a model. A compiled workflow runs: the transition cycle, a judge verdict, a gate parked in one session and released in another, a retry to its limit, a command node routing diff --git a/package-lock.json b/package-lock.json index 2a10a82..ee35ae9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "minflow", - "version": "0.1.4", + "version": "0.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "minflow", - "version": "0.1.4", + "version": "0.2.0", "license": "MIT", "dependencies": { "randexp": "^0.5.3", diff --git a/package.json b/package.json index 7952d1e..28ebca8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "minflow", - "version": "0.1.4", + "version": "0.2.0", "description": "A workflow compiler for coding agents. Describe a graph of steps in TypeScript; get a plugin the agent installs and runs.", "keywords": [ "minflow", diff --git a/src/emit/claude-code.ts b/src/emit/claude-code.ts index b9f650b..f391028 100644 --- a/src/emit/claude-code.ts +++ b/src/emit/claude-code.ts @@ -990,16 +990,23 @@ function askProtocolSection(pluginName: string): string { } function runCommandFile(ir: Graph, pluginName: string): string { + // `--new` is always offered, unlike `--auto`: every workflow can be + // interrupted, so every workflow can be resumed, and the flag is how you say + // you meant to start over rather than continue. + const hints = graphAsks(ir) + ? "[--auto to answer the run's own questions instead of asking you] [--new to start over " + + "instead of resuming]" + : "[--new to start over instead of resuming]"; return commandFor( - `Start the "${ir.name}" workflow.`, + `Start or resume the "${ir.name}" workflow.`, spawnRunnerBody( pluginName, - `Start the **${oneLine(ir.name)}** workflow, which begins at \`${ir.entry}\`.`, + `Start the **${oneLine(ir.name)}** workflow, which begins at \`${ir.entry}\`.\n\n` + + "If a previous run stopped part way through, this picks it up where it left off " + + "instead of starting again, and says so. Everything already finished is kept.", graphAsks(ir), ), - // Only offered when there is something to answer. A flag advertised on a - // workflow that never asks is a flag that does nothing. - graphAsks(ir) ? "[--auto to answer the run's own questions instead of asking you]" : undefined, + hints, ); } @@ -2107,6 +2114,10 @@ const ASK_MARKER = "MINFLOW-ASK"; // answers nobody is coming to give. const AUTO_FLAG = /(^|\s)--auto\b/; +// Forces a fresh run when one is sitting there half finished. The default is to +// resume, because the expensive mistake is redoing work, not continuing it. +const NEW_FLAG = /(^|\s)--new\b/; + // A test seam, and the only one in this file. // // Set to a path, it answers observations from that file instead of resolving @@ -2262,6 +2273,83 @@ function linkSession(sessionId, runId) { // Every run parked at a gate, which is how a resume finds its run from a session // that never started it. Reading a directory of small JSON files is the whole // index: there is no second one to keep consistent with the state files. +// Runs whose session went away mid-flight. +// +// The state is intact and its node already points at the step the run was about to +// take, so such a run is exactly as resumable as one parked at a gate. Nothing +// was ever wired to pick it up, which is how ninety minutes of work became +// unrecoverable the first time a session limit was hit. +// +// Only "running" is claimed here. "awaiting" is a gate and has its own command. +// "asking" put questions in front of a session that is now gone, and resuming it +// means asking again rather than continuing, so it is reported rather than +// silently resumed into a destination whose answers never arrived. +function resumableRuns() { + let entries = []; + try { + entries = fs.readdirSync(path.join(DATA, "runs")); + } catch (error) { + return []; + } + const found = []; + for (const entry of entries) { + if (entry.slice(-5) !== ".json") continue; + const state = readJson(path.join(DATA, "runs", entry)); + if (state === null || state.status !== "running") continue; + found.push(state); + } + return found; +} + +/** Runs stalled mid-ask, which need answers rather than a resume. */ +function askingRuns() { + let entries = []; + try { + entries = fs.readdirSync(path.join(DATA, "runs")); + } catch (error) { + return []; + } + const found = []; + for (const entry of entries) { + if (entry.slice(-5) !== ".json") continue; + const state = readJson(path.join(DATA, "runs", entry)); + if (state === null || state.status !== "asking") continue; + found.push(state); + } + return found; +} + +/** + * Which stalled run the entry command meant, when it meant one at all. + * + * The same order of preference gate resume uses, and for the same reason: + * resuming the wrong run is worse than asking which. + */ +function resumableRunFor(event, sessionId) { + const named = commandArgument(event).replace(AUTO_FLAG, "").replace(NEW_FLAG, "").trim(); + const candidates = resumableRuns(); + if (candidates.length === 0) return { none: true }; + if (named !== "") { + for (const state of candidates) { + if (state.runId === named) return { state: state }; + } + return { none: true }; + } + const linked = runIdForSession(sessionId); + for (const state of candidates) { + if (state.runId === linked) return { state: state }; + } + if (candidates.length === 1) return { state: candidates[0] }; + const ids = candidates.map(function (state) { + return state.runId + ' at step "' + state.node + '"'; + }); + return { + error: + candidates.length + " runs stopped part way through: " + ids.join(", ") + + ". Name the one to resume, or pass --new to start a fresh run.", + }; +} + function parkedRuns(gate) { let entries = []; try { @@ -3137,11 +3225,40 @@ function startRun(event, sessionId) { ); return; } + const argument = commandArgument(event); + + // SPEC section 3.5: one static command serves both a fresh run and a run + // resumed at any node, which is why the command body tells the runner to stand + // by rather than naming a step. Gate resume has always used that. A run whose + // session died mid-flight can use it too, and until now nothing did, so the + // work was simply lost. + if (!NEW_FLAG.test(argument)) { + const stalled = askingRuns(); + if (stalled.length > 0 && resumableRuns().length === 0) { + const one = stalled[0]; + report( + "run " + one.runId + ' is waiting on answers before step "' + one.node + + '", so it needs those answers rather than a resume. Answer it, or pass --new to start ' + + "a fresh run.", + ); + return; + } + const found = resumableRunFor(event, sessionId); + if (found.error) { + report(found.error); + return; + } + if (found.state) { + resumeRun(found.state, graph, sessionId); + return; + } + } + const runId = mintRunId(); // Read once, at the start, and carried for the life of the run. A run cannot // become unattended halfway through, and every later decision can see that the // answers behind it were invented. - const auto = AUTO_FLAG.test(commandArgument(event)); + const auto = AUTO_FLAG.test(argument); const state = { runId: runId, graphHash: PLUGIN.graphHash, @@ -3175,6 +3292,48 @@ function startRun(event, sessionId) { }); } +/** + * Pick a stalled run back up where it stopped. + * + * The same three steps gate resume takes, for the same reason: the state already + * names the node to continue into, so resuming is flipping the status and letting + * the command's own body spawn a fresh runner. + * + * The auto flag is carried, never re-read from the arguments. A run cannot change its + * mind halfway about whether a human is behind it, and the answers already + * recorded were given under whichever mode was in force. + */ +function resumeRun(parked, graph, sessionId) { + if (parked.graphHash !== graph.hash) { + report( + "run " + parked.runId + " started against graph " + parked.graphHash + ", but " + + PLUGIN.graphFile + " now hashes to " + graph.hash + + ". Refusing to resume it: its nodes may have moved. Pass --new to start a fresh run.", + ); + return; + } + if (needsAgent(parked.node) && typeof PLUGIN.agents[parked.node] !== "string") { + report('no agent is registered for node "' + parked.node + '". Regenerate the plugin.'); + return; + } + const state = Object.assign({}, parked, { status: "running" }); + delete state.host; + saveState(withScratch(state, startingScratch(state))); + linkSession(sessionId, state.runId); + appendTrace(state.runId, { + at: new Date().toISOString(), + decision: "resume", + session: sessionId, + run: state.runId, + node: state.node, + steps: state.steps, + }); + report( + "resuming run " + state.runId + ' at step "' + state.node + '", ' + state.steps + + " steps in. Everything already finished is kept. Pass --new to start over instead.", + ); +} + // A gate resume may arrive in a session that never started the run, which is the // whole point of parking on a run id rather than a session (SPEC D11). The run is // named explicitly if the user named it, then taken from this session, then from diff --git a/src/index.ts b/src/index.ts index 6b97316..47779e7 100644 --- a/src/index.ts +++ b/src/index.ts @@ -164,4 +164,4 @@ export type { export { isCommandNode } from "./ir.js"; /** The current package version. */ -export const VERSION = "0.1.4"; +export const VERSION = "0.2.0"; diff --git a/tests/emit-claude-code.test.ts b/tests/emit-claude-code.test.ts index 87f7cc6..7159229 100644 --- a/tests/emit-claude-code.test.ts +++ b/tests/emit-claude-code.test.ts @@ -1354,6 +1354,14 @@ interface Harness { trace(): Record[]; /** Rewrites the compiled graph, as an editor recompiling mid-run would. */ editGraph(change: (graph: Record) => void): void; + /** + * Edit a saved run's state in place. + * + * For the one thing no sequence of hook fires can produce: a run whose own + * recorded graph hash is stale while the plugin and the graph file agree, + * which is what regenerating a plugin under a stopped run leaves behind. + */ + patchRun(runId: string, change: (state: Record) => void): void; /** * Starts a run the way the platform actually starts one, in two beats. * @@ -1498,6 +1506,12 @@ async function withPlugin( change(graph); sync.writeFileSync(graphFile, JSON.stringify(graph, null, 2), "utf8"); }, + patchRun(runId, change) { + const file = path.join(dataDir, "runs", `${runId}.json`); + const state = JSON.parse(sync.readFileSync(file, "utf8")) as Record; + change(state); + sync.writeFileSync(file, JSON.stringify(state, null, 2), "utf8"); + }, }; body(harness); @@ -2042,6 +2056,128 @@ describe("a run, driven through the emitted dispatcher", () => { // Run context, interpolated at spawn time // --------------------------------------------------------------------------- +describe("a run whose session went away, resumed from the entry command", () => { + it("picks the run up where it stopped instead of starting a second one", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin(); + // One real step, then the session simply stops existing. Nothing marks the + // run as finished or parked: its status stays "running", which is exactly + // the state a session limit or a closed laptop leaves behind. + plugin.fire(stopped(reported({ done: true }))); + const stalled = plugin.onlyRun(); + expect(stalled.status).toBe("running"); + expect(stalled.node).toBe("build"); + expect(stalled.steps).toBe(1); + + // The entry command again, in a session that never started the run. SPEC + // section 3.5 always said one static command serves a fresh run and a + // resumed one; gate resume used that and this did not, so the work was + // simply lost. + const again = plugin.fire(typed("drivable:run-drivable", "session-2")); + expect(again.decision).toBeNull(); + expect(again.stderr).toContain("resuming run"); + expect(again.stderr).toContain('"build"'); + + // The same run, not a second one, and no work was rewound. + const resumed = plugin.onlyRun(); + expect(resumed.runId).toBe(stalled.runId); + expect(resumed.node).toBe("build"); + expect(resumed.steps).toBe(1); + expect(resumed.outputs).toEqual(stalled.outputs); + + // And it continues, rather than re-running the entry step. + const fired = plugin.fire(stopped("Standing by.", "session-2")); + expect(fired.reason).toContain("drivable:step-build"); + expect(plugin.trace().some((entry) => entry.decision === "resume")).toBe(true); + }); + }); + + it("carries the auto flag rather than re-reading it, so a run cannot change mode", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin("session-1", "--auto"); + plugin.fire(stopped(reported({ done: true }))); + expect(plugin.onlyRun().auto).toBe(true); + + // Resumed without the flag. The answers already recorded were given under + // auto, so quietly promoting the run to attended would misdescribe them. + plugin.fire(typed("drivable:run-drivable", "session-2")); + expect(plugin.onlyRun().auto).toBe(true); + }); + }); + + it("starts a fresh run when told to, leaving the stalled one alone", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin(); + plugin.fire(stopped(reported({ done: true }))); + const stalled = plugin.onlyRun(); + + plugin.fire(typed("drivable:run-drivable", "session-2", "--new")); + const runs = plugin.runs(); + expect(runs).toHaveLength(2); + const fresh = runs.find((run) => run.runId !== stalled.runId); + expect(fresh?.node).toBe("draft"); + expect(fresh?.steps).toBe(0); + // The old one is untouched, so nothing was destroyed by asking for a new run. + expect(runs.find((run) => run.runId === stalled.runId)?.node).toBe("build"); + }); + }); + + it("refuses to guess which of several stalled runs was meant, and names them", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin("session-1"); + plugin.fire(stopped(reported({ done: true }))); + plugin.fire(typed("drivable:run-drivable", "session-2", "--new")); + plugin.fire(stopped("Standing by.", "session-2")); + plugin.fire(stopped(reported({ done: true }), "session-2")); + expect(plugin.runs()).toHaveLength(2); + + // A third session knows about neither, so there is no link to fall back on. + const asked = plugin.fire(typed("drivable:run-drivable", "session-3")); + expect(asked.stderr).toContain("2 runs stopped part way through"); + expect(asked.stderr).toContain("--new"); + // Nothing was resumed and nothing was started. + expect(plugin.runs()).toHaveLength(2); + }); + }); + + it("resumes the run this session started, when several are stalled", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin("session-1"); + plugin.fire(stopped(reported({ done: true }))); + const mine = plugin.onlyRun().runId; + plugin.fire(typed("drivable:run-drivable", "session-2", "--new")); + plugin.fire(stopped("Standing by.", "session-2")); + plugin.fire(stopped(reported({ done: true }), "session-2")); + + const again = plugin.fire(typed("drivable:run-drivable", "session-1")); + expect(again.stderr).toContain(mine); + }); + }); + + it("refuses to resume a run whose graph moved underneath it", async () => { + await withPlugin(drivableIr(), (plugin) => { + plugin.begin(); + plugin.fire(stopped(reported({ done: true }))); + const stalled = plugin.onlyRun(); + + // The plugin and the graph file still agree, so the dispatcher's own hash + // check passes and the resume path is actually reached. Only the stopped + // run remembers the older graph, which is what regenerating a plugin under + // a stopped run leaves behind. + plugin.patchRun(stalled.runId, (state) => { + state.graphHash = "0000000000000000"; + }); + + const again = plugin.fire(typed("drivable:run-drivable", "session-2")); + expect(again.stderr).toContain("Refusing to resume"); + expect(again.stderr).toContain("its nodes may have moved"); + // Not resumed, and not quietly replaced by a fresh run either. + expect(plugin.runs()).toHaveLength(1); + expect(plugin.onlyRun().node).toBe("build"); + }); + }); +}); + describe("a prompt's run context, resolved by the emitted dispatcher", () => { it("puts an earlier step's value into the next step's instruction", async () => { await withPlugin(interpolatingIr(), (plugin) => { @@ -2345,13 +2481,16 @@ describe("the step wrappers", () => { const described: [where: string, markdown: string, fields: number][] = [ ["the runner", fileOf(files, RUNNER_PATH), 3], ["the step wrapper", fileOf(files, "agents/step-first-second.md"), 3], - ["the run command", fileOf(files, `${COMMANDS_DIR}/run-multi-line.md`), 1], + // Two: a description, and the argument hint the run command always carries + // now that every workflow can be resumed. + ["the run command", fileOf(files, `${COMMANDS_DIR}/run-multi-line.md`), 2], ]; for (const [where, markdown, fields] of described) { // One physical line per field: nothing spilled into a line of its own. const lines = frontmatterLinesOf(markdown); expect(`${where}: ${lines.length}`).toBe(`${where}: ${fields}`); - for (const line of lines) expect(line).toMatch(/^[A-Za-z]+: \S/); + // Hyphens are legal in a key, and `argument-hint` is one of them. + for (const line of lines) expect(line).toMatch(/^[A-Za-z][A-Za-z-]*: \S/); // And the value the resolver hands back is a single line too. It arrives // double-quoted because the interpolated names carry quotes, and a @@ -2940,11 +3079,14 @@ describe("a small compiled workflow", () => { - End your final message with your JSON payload as a single fenced \`json\` block, with nothing after it. It is read from the message itself, so anything following it is noise the parser has to survive. ", "commands/run-tiny-flow.md": "--- - description: "Start the \\"tiny-flow\\" workflow." + description: "Start or resume the \\"tiny-flow\\" workflow." + argument-hint: "[--new to start over instead of resuming]" --- Start the **tiny-flow** workflow, which begins at \`draft\`. + If a previous run stopped part way through, this picks it up where it left off instead of starting again, and says so. Everything already finished is kept. + Spawn the subagent \`tiny-flow:runner\` with the Agent tool, and give it exactly this instruction, verbatim: