@kontourai/flow-agents 3.7.0 → 3.9.0

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");
@@ -200,7 +235,7 @@ async function evidence(sessionDir, argv, json) {
         // session state cannot change mid-invocation.
         const caller = assertMatchingAssignmentActor(sessionDir, slug);
         const repaired = await recoverBuilderFlowSession({ sessionDir });
-        const beforeEvidence = manifestEvidenceDigests(repaired.run.manifest);
+        const beforeEvidence = manifestEvidenceIdentity(repaired.run.manifest);
         await mainFromPublicWorkflow([
             "record-gate-claim",
             sessionDir,
@@ -208,27 +243,34 @@ async function evidence(sessionDir, argv, json) {
             "--actor",
             caller.actorKey,
         ]);
-        await syncBuilderFlowSession({ sessionDir });
+        const synchronized = await syncBuilderFlowSession({ sessionDir });
         const digest = fileSha256(path.join(sessionDir, "trust.bundle"));
         const run = await loadBuilderFlowRun({ cwd: repaired.projectRoot, runId: slug });
-        const afterEvidence = manifestEvidenceDigests(run.manifest);
-        const newEvidence = afterEvidence.filter((value) => !beforeEvidence.includes(value));
-        if (newEvidence.length !== 1 || newEvidence[0] !== digest) {
+        const afterEvidence = manifestEvidenceIdentity(run.manifest);
+        const beforeIds = new Set(beforeEvidence.map((entry) => entry.id));
+        const newEvidence = afterEvidence.filter((entry) => !beforeIds.has(entry.id));
+        if (synchronized.attached && (newEvidence.length !== 1 || newEvidence[0]?.sha256 !== digest)) {
             throw new Error("workflow evidence did not attach exactly this invocation's resulting trust.bundle digest");
         }
+        if (!synchronized.attached && newEvidence.length !== 0) {
+            throw new Error("workflow evidence changed the canonical manifest while synchronization reported no attachment");
+        }
         const updatedSidecar = readBoundSession(sessionDir).sidecar;
         return immutableReport({
             run_id: run.runId,
             status: run.state.status,
             current_step: run.state.current_step,
-            attached: true,
+            attached: synchronized.attached,
+            awaiting_evidence: !synchronized.attached,
             next_action: updatedSidecar.next_action ?? null,
         });
     });
     if (json)
         console.log(JSON.stringify(report));
     else
-        console.log(`Recorded evidence; canonical run is ${report.status} at ${report.current_step}.`);
+        console.log(report.attached
+            ? `Recorded evidence; canonical run is ${report.status} at ${report.current_step}.`
+            : `Recorded evidence; canonical run is awaiting the remaining gate expectations at ${report.current_step}.`);
     return 0;
 }
 async function critique(sessionDir, argv, json) {
@@ -541,11 +583,14 @@ function immutableReport(value) {
         immutableReport(nested);
     return Object.freeze(value);
 }
-function manifestEvidenceDigests(manifest) {
+function manifestEvidenceIdentity(manifest) {
     const evidence = Array.isArray(manifest.evidence) ? manifest.evidence : [];
     return evidence
-        .map((entry) => entry && typeof entry === "object" ? entry.sha256 : null)
-        .filter((digest) => typeof digest === "string");
+        .flatMap((entry) => entry && typeof entry === "object"
+        && typeof entry.id === "string"
+        && typeof entry.sha256 === "string"
+        ? [{ id: String(entry.id), sha256: String(entry.sha256) }]
+        : []);
 }
 function optionalFileDigest(file) {
     try {
@@ -600,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;