@kontourai/flow-agents 3.8.0 → 3.9.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [3.9.0](https://github.com/kontourai/flow-agents/compare/v3.8.0...v3.9.0) (2026-07-12)
+
+
+### Features
+
+* **workflow:** add bounded continuation driver ([#560](https://github.com/kontourai/flow-agents/issues/560)) ([e6365ab](https://github.com/kontourai/flow-agents/commit/e6365aba324c76ee164681c987d20916c315444e))
+
 ## [3.8.0](https://github.com/kontourai/flow-agents/compare/v3.7.0...v3.8.0) (2026-07-12)
 
 

package/build/src/builder-flow-runtime.js

@@ -760,7 +760,9 @@ function projectFlowRun(context, run, sidecar) {
     const complete = run.state.status === "completed";
     const paused = run.state.status === "paused";
     const canceled = run.state.status === "canceled";
-    const action = complete || paused || canceled ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
+    const needsDecision = run.state.status === "needs_decision";
+    const failed = run.state.status === "failed";
+    const action = complete || paused || canceled || needsDecision || failed ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
     if (!action) {
         throw new BuilderBuildRunInputError("kit.flow_step_actions", `does not declare Builder step ${run.state.current_step}`);
     }
@@ -785,18 +787,22 @@ function projectFlowRun(context, run, sidecar) {
             ? { status: "done", summary: "Canonical Flow run was canceled by an authorized external request. Artifacts are retained until separately archived." }
             : paused
                 ? { status: "blocked", summary: "Canonical Flow run is paused. The current assignment actor may resume it with a reason." }
-                : {
-                    status: "continue",
-                    summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
-                    skills,
-                    operations,
-                    command: syncCommand,
-                };
+                : needsDecision
+                    ? { status: "blocked", summary: "Canonical Flow requires an external decision before continuation." }
+                    : failed
+                        ? { status: "failed", summary: "Canonical Flow run failed; no continuation turn is allowed." }
+                        : {
+                            status: "continue",
+                            summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
+                            skills,
+                            operations,
+                            command: syncCommand,
+                        };
     const phase = phaseForStep(definition.phase_map, run.state.current_step) ?? sidecar.phase;
     return {
         ...sidecar,
-        status: complete ? "delivered" : canceled ? "canceled" : paused ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
-        phase: complete || canceled ? "done" : phase,
+        status: complete ? "delivered" : canceled ? "canceled" : failed ? "failed" : (paused || needsDecision) ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+        phase: complete || canceled || failed ? "done" : phase,
         updated_at: run.state.updated_at,
         flow_run: {
             run_id: run.runId,

package/build/src/cli/continuation-adapter.d.ts

@@ -0,0 +1,24 @@
+import type { ContinuationBarrier, ContinuationTurnRequest, ContinuationTurnResult } from "../continuation-driver.js";
+export type ContinuationAdapterCommand = {
+    argv: string[];
+    identity: string;
+    integrity: Array<{
+        file: string;
+        sha256: string;
+    }>;
+};
+export declare function loadContinuationAdapterCommand(commandFileInput: string): ContinuationAdapterCommand;
+export declare function executeContinuationAdapter(commandFileInput: string, request: ContinuationTurnRequest, options: {
+    cwd: string;
+    timeoutMs: number;
+}): Promise<ContinuationTurnResult>;
+export declare function executeLoadedContinuationAdapter(command: ContinuationAdapterCommand, request: ContinuationTurnRequest, options: {
+    cwd: string;
+    timeoutMs: number;
+}): Promise<ContinuationTurnResult>;
+export declare function waitForContinuationBarrier(barrier: ContinuationBarrier, options: {
+    maxWaitMs: number;
+    pollMs: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<"ready" | "pending">;

package/build/src/cli/continuation-adapter.js

@@ -0,0 +1,225 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+export function loadContinuationAdapterCommand(commandFileInput) {
+    const commandFile = path.resolve(commandFileInput);
+    const command = validateAdapterCommand(JSON.parse(readRegularFileNoFollow(commandFile, "continuation adapter command file")));
+    if (!path.isAbsolute(command.argv[0]))
+        throw new Error("continuation adapter executable must be an absolute path");
+    const integrity = [...new Set(command.argv.filter((entry) => path.isAbsolute(entry) && regularFileExists(entry)))]
+        .map((file) => ({ file, sha256: sha256File(file, "continuation adapter integrity file") }));
+    if (!integrity.some((entry) => entry.file === command.argv[0]))
+        throw new Error("continuation adapter executable must be a regular file");
+    const identity = createHash("sha256").update(JSON.stringify({ ...command, integrity })).digest("hex");
+    return { ...command, identity, integrity };
+}
+export async function executeContinuationAdapter(commandFileInput, request, options) {
+    const command = loadContinuationAdapterCommand(commandFileInput);
+    return executeLoadedContinuationAdapter(command, request, options);
+}
+export async function executeLoadedContinuationAdapter(command, request, options) {
+    for (const entry of command.integrity) {
+        if (sha256File(entry.file, "continuation adapter integrity file") !== entry.sha256) {
+            throw new Error(`continuation adapter integrity changed after mission binding: ${entry.file}`);
+        }
+    }
+    assertPositiveInteger(options.timeoutMs, "continuation adapter timeoutMs", 1, 86_400_000);
+    return await spawnAdapter(command, request, options);
+}
+export async function waitForContinuationBarrier(barrier, options) {
+    assertPositiveInteger(options.maxWaitMs, "continuation barrier maxWaitMs", 0, 86_400_000);
+    assertPositiveInteger(options.pollMs, "continuation barrier pollMs", 1, 60_000);
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const stopAt = now() + options.maxWaitMs;
+    if (barrier.kind === "deadline") {
+        const deadline = Date.parse(barrier.at);
+        if (deadline <= now())
+            return "ready";
+        const waitMs = Math.min(deadline - now(), Math.max(0, stopAt - now()));
+        if (waitMs > 0)
+            await sleep(waitMs);
+        return Date.parse(barrier.at) <= now() ? "ready" : "pending";
+    }
+    while (pidAlive(barrier.pid)) {
+        const remaining = stopAt - now();
+        if (remaining <= 0)
+            return "pending";
+        await sleep(Math.min(options.pollMs, remaining));
+    }
+    return "ready";
+}
+function spawnAdapter(command, request, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command.argv[0], command.argv.slice(1), {
+            cwd: options.cwd,
+            env: process.env,
+            detached: process.platform !== "win32",
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        let forcedKill;
+        let terminationError;
+        const maxBytes = 4 * 1024 * 1024;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            terminationError = new Error(`continuation adapter timed out after ${options.timeoutMs}ms`);
+            terminateProcessGroup(child.pid, "SIGTERM");
+            forcedKill = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 250);
+        }, options.timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > maxBytes) {
+                if (!terminationError) {
+                    terminationError = new Error("continuation adapter stdout exceeded 4 MiB");
+                    clearTimeout(timeout);
+                    terminateProcessGroup(child.pid, "SIGTERM");
+                    forcedKill = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 250);
+                }
+                return;
+            }
+            stdout.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderrBytes += chunk.length;
+            if (stderrBytes <= maxBytes)
+                stderr.push(chunk);
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (forcedKill)
+                clearTimeout(forcedKill);
+            reject(error);
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (forcedKill)
+                clearTimeout(forcedKill);
+            if (terminationError) {
+                reject(terminationError);
+                return;
+            }
+            const stderrText = Buffer.concat(stderr).toString("utf8").trim();
+            if (code !== 0) {
+                scheduleProcessGroupTermination(child.pid);
+                reject(new Error(`continuation adapter exited ${code ?? signal ?? "unknown"}${stderrText ? `: ${stderrText}` : ""}`));
+                return;
+            }
+            const output = Buffer.concat(stdout).toString("utf8").trim();
+            try {
+                const result = JSON.parse(output);
+                if (!isValidWaitResult(result))
+                    scheduleProcessGroupTermination(child.pid);
+                resolve(result);
+            }
+            catch {
+                scheduleProcessGroupTermination(child.pid);
+                reject(new Error("continuation adapter must emit exactly one JSON result on stdout"));
+            }
+        });
+        child.stdin.on("error", (error) => {
+            if (error.code !== "EPIPE" && !settled) {
+                settled = true;
+                clearTimeout(timeout);
+                if (forcedKill)
+                    clearTimeout(forcedKill);
+                scheduleProcessGroupTermination(child.pid);
+                reject(error);
+            }
+        });
+        child.stdin.end(`${JSON.stringify(request)}\n`);
+    });
+}
+function validateAdapterCommand(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("continuation adapter command file must contain an object");
+    const argv = value.argv;
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > 128 || argv.some((entry) => typeof entry !== "string" || entry.length === 0 || entry.includes("\0"))) {
+        throw new Error("continuation adapter command argv must contain 1 through 128 non-empty strings");
+    }
+    return { argv: [...argv] };
+}
+function assertRegularFile(file, label) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`${label} must be a regular file`);
+}
+function readRegularFileNoFollow(file, label) {
+    return readRegularFileBufferNoFollow(file, label).toString("utf8");
+}
+function readRegularFileBufferNoFollow(file, label) {
+    assertRegularFile(file, label);
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+    try {
+        if (!fs.fstatSync(fd).isFile())
+            throw new Error(`${label} must be a regular file`);
+        return fs.readFileSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function assertPositiveInteger(value, label, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new Error(`${label} must be an integer from ${min} through ${max}`);
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function terminateProcessGroup(pid, signal) {
+    if (!pid)
+        return;
+    try {
+        process.kill(process.platform === "win32" ? pid : -pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+function isValidWaitResult(result) {
+    if (result?.status !== "wait" || !result.barrier || typeof result.barrier !== "object")
+        return false;
+    if (result.barrier.kind === "pid")
+        return Number.isSafeInteger(result.barrier.pid) && result.barrier.pid > 0;
+    return result.barrier.kind === "deadline" && typeof result.barrier.at === "string" && Number.isFinite(Date.parse(result.barrier.at));
+}
+function scheduleProcessGroupTermination(pid) {
+    terminateProcessGroup(pid, "SIGTERM");
+    const forcedKill = setTimeout(() => terminateProcessGroup(pid, "SIGKILL"), 250);
+    forcedKill.unref();
+}
+function regularFileExists(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        return !stat.isSymbolicLink() && stat.isFile();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function sha256File(file, label) {
+    return createHash("sha256").update(readRegularFileBufferNoFollow(file, label)).digest("hex");
+}

package/build/src/cli/workflow.js

@@ -6,6 +6,7 @@ import { isDeepStrictEqual } from "node:util";
 import { fileURLToPath } from "node:url";
 import { validateDefinition } from "@kontourai/flow";
 import { loadBuilderFlowRun } from "../builder-flow-run-adapter.js";
+import { driveBuilderFlowSession, withContinuationDriverLock } from "../continuation-driver.js";
 import { inspectBuilderFlowSession, recoverBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
 import { flowAgentsPackageRoot, flowAgentsPackageVersion } from "../lib/package-version.js";
 import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
@@ -14,12 +15,13 @@ import { flagBool, flagList, flagString, parseArgs } from "../lib/args.js";
 import { main as builderRun } from "./builder-run.js";
 import { currentWorkflowSessionDir, isMeaningfulTestCommand, mainFromPublicWorkflow, WORKFLOW_WRITER_CONTRACT_VERSION } from "./workflow-sidecar.js";
 import { resolveCurrentAssignmentActor, withSubjectLock } from "./assignment-provider.js";
+import { executeLoadedContinuationAdapter, loadContinuationAdapterCommand, waitForContinuationBarrier } from "./continuation-adapter.js";
 export const WORKFLOW_CONTRACT_VERSION = "1.0";
 const PACKAGE_ROOT = flowAgentsPackageRoot();
 const REQUIRE = createRequire(import.meta.url);
 const PACKAGE_METADATA = readJsonFile(path.join(PACKAGE_ROOT, "package.json"), "Flow Agents package metadata");
 const CLI_VERSION = flowAgentsPackageVersion();
-const PUBLIC_VERBS = ["start", "status", "evidence", "critique", "pause", "resume", "release", "cancel", "archive", "doctor"];
+const PUBLIC_VERBS = ["start", "status", "evidence", "critique", "drive", "pause", "resume", "release", "cancel", "archive", "doctor"];
 function usage() {
     console.log(`Usage: flow-agents workflow <verb> [options]
 
@@ -28,6 +30,7 @@ Public workflow verbs:
   status              Show the current canonical run and projected next action.
   evidence            Record evidence for the current Flow gate and synchronize it.
   critique            Record review critique directly into the current trust bundle.
+  drive               Continue the canonical run through an explicit runtime adapter.
   pause               Pause the current run as its assignment actor.
   resume              Resume the current paused run as its assignment actor.
   release             Release the current assignment without canceling the run.
@@ -60,11 +63,43 @@ export async function main(argv) {
         return evidence(sessionDir, argv.slice(1), flagBool(parsed.flags, "json"));
     if (verb === "critique")
         return critique(sessionDir, argv.slice(1), flagBool(parsed.flags, "json"));
+    if (verb === "drive")
+        return drive(sessionDir, argv.slice(1), flagBool(parsed.flags, "json"));
     const forwarded = stripPublicFlags(argv.slice(1), new Set(["artifact-root", "session-dir", "json"]));
     if (verb === "release" && !flagString(parsed.flags, "reason"))
         throw new Error("workflow release requires --reason <text>");
     return builderRun([verb === "release" ? "release-assignment" : verb, "--session-dir", sessionDir, ...forwarded]);
 }
+async function drive(sessionDir, argv, json) {
+    const parsed = parseArgs(argv);
+    assertOnlyFlags(parsed.flags, new Set(["artifact-root", "session-dir", "json", "adapter-command-file", "max-turns", "turn-timeout-ms", "barrier-wait-ms", "barrier-poll-ms"]), "workflow drive");
+    const adapterCommandFile = flagString(parsed.flags, "adapter-command-file");
+    if (!adapterCommandFile)
+        throw new Error("workflow drive requires --adapter-command-file <path>");
+    const maxTurns = integerFlag(parsed.flags, "max-turns", 4, 1, 100);
+    const turnTimeoutMs = integerFlag(parsed.flags, "turn-timeout-ms", 900_000, 1, 86_400_000);
+    const barrierWaitMs = integerFlag(parsed.flags, "barrier-wait-ms", 300_000, 0, 86_400_000);
+    const barrierPollMs = integerFlag(parsed.flags, "barrier-poll-ms", 1_000, 1, 60_000);
+    const { slug, projectRoot } = readBoundSession(sessionDir);
+    assertMatchingAssignmentActor(sessionDir, slug);
+    const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
+    const result = await withContinuationDriverLock(sessionDir, async () => {
+        assertMatchingAssignmentActor(sessionDir, slug);
+        return driveBuilderFlowSession({
+            sessionDir,
+            maxTurns,
+            adapterCommandIdentity: adapterCommand.identity,
+            authorizeTurn: async () => { assertMatchingAssignmentActor(sessionDir, slug); },
+            execute: async (request) => executeLoadedContinuationAdapter(adapterCommand, request, { cwd: projectRoot, timeoutMs: turnTimeoutMs }),
+            waitForBarrier: async (barrier) => waitForContinuationBarrier(barrier, { maxWaitMs: barrierWaitMs, pollMs: barrierPollMs }),
+        });
+    });
+    if (json)
+        console.log(JSON.stringify(result));
+    else
+        console.log(`Continuation driver ${result.outcome} after ${result.turns_started} turn(s); canonical Flow is ${result.snapshot.status} at ${result.snapshot.current_step}.`);
+    return 0;
+}
 async function start(argv) {
     const parsed = parseArgs(argv);
     assertOnlyFlags(parsed.flags, new Set(["flow", "work-item", "task-slug", "artifact-root", "source-request", "summary", "title", "criterion", "assignment-provider", "effective-state-json"]), "workflow start");
@@ -610,6 +645,17 @@ function assertOnlyFlags(flags, allowed, command) {
     if (unsupported)
         throw new Error(`${command} does not support --${unsupported}`);
 }
+function integerFlag(flags, name, fallback, min, max) {
+    const raw = flagString(flags, name);
+    if (raw === undefined)
+        return fallback;
+    if (!/^(0|[1-9][0-9]*)$/.test(raw))
+        throw new Error(`workflow drive --${name} must be an integer from ${min} through ${max}`);
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new Error(`workflow drive --${name} must be an integer from ${min} through ${max}`);
+    return value;
+}
 function isWithin(candidate, root) {
     const relative = path.relative(root, candidate);
     return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));

package/build/src/continuation-driver.d.ts

@@ -0,0 +1,92 @@
+export type ContinuationBarrier = {
+    kind: "pid";
+    pid: number;
+} | {
+    kind: "deadline";
+    at: string;
+};
+export type ContinuationSnapshot = {
+    run_id: string;
+    definition_id: string;
+    status: string;
+    disposition: "continue" | "waiting" | "done" | "failed";
+    current_step: string;
+    next_action: Record<string, unknown> | null;
+};
+export type ContinuationTurnRequest = {
+    schema_version: "1.0";
+    run_id: string;
+    definition_id: string;
+    current_step: string;
+    iteration: number;
+    max_turns: number;
+    next_action: Record<string, unknown> | null;
+};
+export type ContinuationTurnResult = {
+    status: "completed";
+    summary?: string;
+} | {
+    status: "wait";
+    barrier: ContinuationBarrier;
+    summary?: string;
+};
+export type ContinuationDriverState = {
+    schema_version: "1.0";
+    run_id: string;
+    definition_id: string;
+    max_turns: number;
+    adapter_command_identity: string | null;
+    status: "active" | "waiting" | "done" | "failed" | "budget_exhausted";
+    turns_started: number;
+    pending_barrier: ContinuationBarrier | null;
+    updated_at: string;
+};
+export type ContinuationDriverEvent = {
+    schema_version: "1.0";
+    type: "started" | "turn_started" | "turn_completed" | "turn_failed" | "parked" | "resumed" | "done" | "budget_exhausted";
+    run_id: string;
+    definition_id: string;
+    current_step: string;
+    turns_started: number;
+    at: string;
+    barrier?: ContinuationBarrier;
+    summary?: string;
+};
+export interface ContinuationStateStore {
+    load(): ContinuationDriverState | null;
+    save(state: ContinuationDriverState): void;
+    append(event: ContinuationDriverEvent): void;
+}
+export interface ContinuationRuntimePort {
+    inspect(): Promise<ContinuationSnapshot>;
+    synchronize(): Promise<ContinuationSnapshot>;
+    execute(request: ContinuationTurnRequest): Promise<ContinuationTurnResult>;
+}
+export type ContinuationDriverOutcome = {
+    outcome: "done" | "waiting" | "failed" | "budget_exhausted";
+    turns_started: number;
+    snapshot: ContinuationSnapshot;
+    barrier?: ContinuationBarrier;
+};
+export interface RunContinuationDriverInput {
+    maxTurns: number;
+    adapterCommandIdentity?: string;
+    runtime: ContinuationRuntimePort;
+    store: ContinuationStateStore;
+    waitForBarrier?: (barrier: ContinuationBarrier) => Promise<"ready" | "pending">;
+    authorizeTurn?: () => Promise<void>;
+    now?: () => Date;
+}
+export interface DriveBuilderFlowSessionInput {
+    sessionDir: string;
+    maxTurns: number;
+    adapterCommandIdentity?: string;
+    execute: ContinuationRuntimePort["execute"];
+    waitForBarrier?: RunContinuationDriverInput["waitForBarrier"];
+    authorizeTurn?: RunContinuationDriverInput["authorizeTurn"];
+    now?: () => Date;
+}
+export declare function runContinuationDriver(input: RunContinuationDriverInput): Promise<ContinuationDriverOutcome>;
+export declare function driveBuilderFlowSession(input: DriveBuilderFlowSessionInput): Promise<ContinuationDriverOutcome>;
+export declare function withContinuationDriverLock<T>(sessionDirInput: string, body: () => Promise<T>): Promise<T>;
+export declare function createFileContinuationStore(sessionDirInput: string): ContinuationStateStore;