@kontourai/flow-agents 3.8.0 → 3.10.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 { assertLoadedContinuationAdapterIntegrity, 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,69 @@ 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);
+    assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
+    const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
+    const result = await withContinuationDriverLock(sessionDir, async (lock) => {
+        assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
+        return driveBuilderFlowSession({
+            sessionDir,
+            maxTurns,
+            adapterCommandIdentity: adapterCommand.identity,
+            authorizeTurn: async () => { assertOrdinaryMatchingAssignmentActor(sessionDir, slug); },
+            issueTurnAuthority: async (request) => {
+                const currentAssignment = assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
+                assertLoadedContinuationAdapterIntegrity(adapterCommand);
+                const authority = loadContinuationTurnAuthority();
+                return authority.issueActiveTurnAuthority({
+                    sessionDir,
+                    runId: request.run_id,
+                    definitionId: request.definition_id,
+                    currentStep: request.current_step,
+                    iteration: request.iteration,
+                    maxTurns: request.max_turns,
+                    adapterCommandIdentity: adapterCommand.identity,
+                    assignmentActor: currentAssignment.actorKey,
+                    assignmentActorStruct: currentAssignment.actor,
+                    lock,
+                    timeoutMs: turnTimeoutMs,
+                });
+            },
+            execute: async (request, context) => executeLoadedContinuationAdapter(adapterCommand, request, {
+                cwd: projectRoot,
+                timeoutMs: turnTimeoutMs,
+                continuationTurnSecret: context?.continuationTurnSecret,
+                continuationRunId: context?.continuationRunId,
+            }),
+            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;
+}
+function loadContinuationTurnAuthority() {
+    return REQUIRE(path.resolve(PACKAGE_ROOT, "scripts", "hooks", "lib", "continuation-turn-authority.js"));
+}
 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");
@@ -518,14 +579,35 @@ function readAssignment(sessionDir, slug) {
     return readJsonFile(file, "workflow assignment");
 }
 function assertMatchingAssignmentActor(sessionDir, slug) {
-    const assignment = readActiveAssignment(sessionDir, slug);
-    const caller = resolveCurrentAssignmentActor();
-    const normalizeActor = (value) => value && typeof value === "object" ? { ...value, human: value.human ?? null } : null;
-    if (assignment.actor_key !== caller.actorKey || !isDeepStrictEqual(normalizeActor(assignment.actor), normalizeActor(caller.actor))) {
-        throw new Error("workflow mutation requires the session's active, matching assignment actor");
+    const { assignment, caller, matches } = assignmentActorContext(sessionDir, slug);
+    if (matches)
+        return caller;
+    const authority = loadContinuationTurnAuthority().validateSignedActiveTurnAssignmentAuthority({
+        sessionDir,
+        runId: process.env.FLOW_AGENTS_CONTINUATION_RUN_ID,
+        turnSecret: process.env.FLOW_AGENTS_CONTINUATION_TURN_SECRET,
+    });
+    if (authority.valid && authority.record
+        && assignment.actor_key === authority.record.assignment_actor
+        && isDeepStrictEqual(normalizeAssignmentActor(assignment.actor), normalizeAssignmentActor(authority.record.assignment_actor_struct))) {
+        return { actorKey: authority.record.assignment_actor, actor: normalizeAssignmentActor(authority.record.assignment_actor_struct) };
     }
+    throw new Error("workflow mutation requires the session's active, matching assignment actor");
+}
+function assertOrdinaryMatchingAssignmentActor(sessionDir, slug) {
+    const { caller, matches } = assignmentActorContext(sessionDir, slug);
+    if (!matches)
+        throw new Error("workflow mutation requires the session's active, matching assignment actor");
     return caller;
 }
+function assignmentActorContext(sessionDir, slug) {
+    const assignment = readActiveAssignment(sessionDir, slug);
+    const caller = resolveCurrentAssignmentActor();
+    return { assignment, caller, matches: assignment.actor_key === caller.actorKey && isDeepStrictEqual(normalizeAssignmentActor(assignment.actor), normalizeAssignmentActor(caller.actor)) };
+}
+function normalizeAssignmentActor(value) {
+    return value && typeof value === "object" ? { ...value, human: value.human ?? null } : null;
+}
 function readActiveAssignment(sessionDir, slug) {
     const assignment = readAssignment(sessionDir, slug);
     if (assignment.status !== "claimed" || assignment.artifact_dir !== slug || typeof assignment.actor_key !== "string" || !assignment.actor_key || !assignment.actor || typeof assignment.actor !== "object" || Array.isArray(assignment.actor)) {
@@ -610,6 +692,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,116 @@
+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 declare class ContinuationAdapterTimeoutError extends Error {
+    readonly code = "CONTINUATION_ADAPTER_TIMEOUT";
+    constructor(timeoutMs: number);
+}
+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;
+    active_turn_step?: string | null;
+    active_turn_public_key_digest?: string | null;
+    pending_barrier: ContinuationBarrier | null;
+    updated_at: string;
+};
+export type ContinuationDriverEvent = {
+    schema_version: "1.0";
+    type: "started" | "turn_started" | "turn_completed" | "gate_not_advanced" | "turn_failed" | "authority_cleanup_failed" | "parked" | "resumed" | "done" | "budget_exhausted";
+    run_id: string;
+    definition_id: string;
+    current_step: string;
+    turns_started: number;
+    at: string;
+    barrier?: ContinuationBarrier;
+    summary?: string;
+    failure_kind?: "adapter_error" | "timeout";
+};
+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, context?: ContinuationTurnContext): Promise<ContinuationTurnResult>;
+}
+export type ContinuationTurnContext = {
+    continuationTurnSecret?: string;
+    continuationRunId?: string;
+};
+export type ContinuationDriverLockLease = {
+    pid: number;
+    token: string;
+    created_at: string;
+};
+export type ContinuationTurnAuthority = {
+    runId: string;
+    turnSecret: string;
+    publicKeyDigest: string;
+    cleanup(): boolean;
+};
+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>;
+    issueTurnAuthority?: (request: ContinuationTurnRequest) => Promise<ContinuationTurnAuthority>;
+    now?: () => Date;
+}
+export interface DriveBuilderFlowSessionInput {
+    sessionDir: string;
+    maxTurns: number;
+    adapterCommandIdentity?: string;
+    execute: ContinuationRuntimePort["execute"];
+    waitForBarrier?: RunContinuationDriverInput["waitForBarrier"];
+    authorizeTurn?: RunContinuationDriverInput["authorizeTurn"];
+    issueTurnAuthority?: RunContinuationDriverInput["issueTurnAuthority"];
+    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: (lease: ContinuationDriverLockLease) => Promise<T>): Promise<T>;
+export declare function createFileContinuationStore(sessionDirInput: string): ContinuationStateStore;