@kontourai/flow-agents 3.11.0 → 3.12.1

package/dist/pi/build/src/cli/workflow.js

@@ -6,7 +6,8 @@ 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 { parseKitFlowStepActions } from "../flow-kit/validate.js";
+import { MAX_CONTINUATION_TURN_RESULT_BYTES, createFileContinuationStore, 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";
@@ -87,12 +88,14 @@ async function drive(sessionDir, argv, json) {
     assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
     const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
     let evidenceSigner = null;
-    const observedAdapterTurns = [];
+    let observedAdapterTurns = [];
     const result = await withContinuationDriverLock(sessionDir, async (lock) => {
         assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
         evidenceSigner = evidenceSigningKeyFile ? consumeEvidenceSigningKey(evidenceSigningKeyFile) : null;
-        return driveBuilderFlowSession({
+        const continuationStore = createFileContinuationStore(sessionDir);
+        const outcome = await driveBuilderFlowSession({
             sessionDir,
+            store: continuationStore,
             maxTurns,
             adapterCommandIdentity: adapterCommand.identity,
             authorizeTurn: async () => { assertOrdinaryMatchingAssignmentActor(sessionDir, slug); },
@@ -120,18 +123,14 @@ async function drive(sessionDir, argv, json) {
                 continuationTurnSecret: context?.continuationTurnSecret,
                 continuationRunId: context?.continuationRunId,
             }),
-            ...(evidenceSigningKeyFile ? { onTurnAccepted: async (request, adapterResult) => {
-                    const next = [...observedAdapterTurns, {
-                            request: structuredClone(request),
-                            result: structuredClone(adapterResult),
-                        }];
-                    if (Buffer.byteLength(JSON.stringify(next), "utf8") > 1_048_576) {
-                        throw new Error("continuation accepted-turn evidence must not exceed 1048576 aggregate bytes");
-                    }
-                    observedAdapterTurns.push(next.at(-1));
+            ...(evidenceSigningKeyFile ? { preflightTurn: async (request) => {
+                    assertAcceptedTurnEvidenceCapacity(attestationTurns(continuationStore.acceptedTurns()), request);
                 } } : {}),
             waitForBarrier: async (barrier) => waitForContinuationBarrier(barrier, { maxWaitMs: barrierWaitMs, pollMs: barrierPollMs }),
         });
+        if (evidenceSigningKeyFile)
+            observedAdapterTurns = attestationTurns(continuationStore.acceptedTurns());
+        return outcome;
     });
     const output = evidenceSigner
         ? { ...result, evidence_attestation: signDriveEvidence(evidenceSigner, adapterCommand.identity, maxTurns, result, observedAdapterTurns) }
@@ -142,6 +141,21 @@ async function drive(sessionDir, argv, json) {
         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 attestationTurns(turns) {
+    const covered = turns.map((turn) => ({ request: structuredClone(turn.request), result: structuredClone(turn.result) }));
+    if (Buffer.byteLength(JSON.stringify(covered), "utf8") > 1_048_576) {
+        throw new Error("continuation accepted-turn evidence must not exceed 1048576 aggregate bytes");
+    }
+    return covered;
+}
+export function assertAcceptedTurnEvidenceCapacity(observedTurns, request) {
+    const base = [...observedTurns, { request: structuredClone(request), result: null }];
+    const bytesWithPlaceholder = Buffer.byteLength(JSON.stringify(base), "utf8");
+    const exactReservedBytes = bytesWithPlaceholder - Buffer.byteLength("null", "utf8") + MAX_CONTINUATION_TURN_RESULT_BYTES;
+    if (exactReservedBytes > 1_048_576) {
+        throw new Error("continuation accepted-turn evidence lacks capacity for another bounded result");
+    }
+}
 function consumeEvidenceSigningKey(fileInput) {
     if (!path.isAbsolute(fileInput) || fileInput !== path.normalize(fileInput)) {
         throw new Error("workflow drive evidence signing key file must be an absolute canonical path");
@@ -326,6 +340,15 @@ async function evidence(sessionDir, argv, json) {
     if (Object.hasOwn(parsed.flags, "command") && commands.length === 0) {
         throw new Error("workflow evidence --command requires a shell command value");
     }
+    const expectation = flagString(parsed.flags, "expectation");
+    // Operation-bound expectations deliberately have no generic evidence writer.
+    // Check before recovery, locking, or actor resolution so a locally authored
+    // operation result cannot cause any canonical or projection mutation.
+    const inspected = await inspectBuilderFlowSession({ sessionDir });
+    const operation = builderOperationForExpectation(inspected.run.definitionId, expectation);
+    if (operation) {
+        throw new Error(`workflow evidence cannot satisfy operation-bound expectation ${expectation}; ${operation} requires authenticated external ChangeProvider completion`);
+    }
     const requiresTestEvidence = flagString(parsed.flags, "expectation") === "tests-evidence" && flagString(parsed.flags, "status") === "pass";
     // Argument and command-shape rejection must be read-only. Recovery below may
     // repair stale projections, so it runs only after every command is accepted.
@@ -374,6 +397,20 @@ async function evidence(sessionDir, argv, json) {
             : `Recorded evidence; canonical run is awaiting the remaining gate expectations at ${report.current_step}.`);
     return 0;
 }
+function builderOperationForExpectation(flowId, expectationId) {
+    const kit = readJsonFile(path.join(PACKAGE_ROOT, "kits", "builder", "kit.json"), "Builder kit metadata");
+    const parsed = parseKitFlowStepActions(kit, "kits/builder/kit.json");
+    if (parsed.errors.length)
+        throw new Error(`Builder kit metadata is invalid: ${parsed.errors.join("; ")}`);
+    for (const action of parsed.entries) {
+        if (action.flow_id !== flowId)
+            continue;
+        const binding = action.expectation_bindings.find((candidate) => candidate.expectation_id === expectationId);
+        if (binding?.interface === "operation")
+            return binding.operation ?? "the declared external operation";
+    }
+    return null;
+}
 async function critique(sessionDir, argv, json) {
     const parsed = parseArgs(argv);
     assertOnlyFlags(parsed.flags, new Set(["artifact-root", "session-dir", "json", "id", "verdict", "summary", "artifact-ref", "finding-json", "lane-json", "timestamp"]), "workflow critique");

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

@@ -1,3 +1,6 @@
+import { type GateActionEnvelope, type GateActionPriorProgress, type GateActionProgressSnapshot } from "./builder-gate-action-envelope.js";
+export { MAX_CONTINUATION_TURNS, createFileContinuationStore, withContinuationDriverLock } from "./continuation-persistence.js";
+export { MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES, MAX_CONTINUATION_TURN_RESULT_BYTES } from "./continuation-validation.js";
 export type ContinuationBarrier = {
     kind: "pid";
     pid: number;
@@ -12,6 +15,10 @@ export type ContinuationSnapshot = {
     disposition: "continue" | "waiting" | "done" | "failed";
     current_step: string;
     next_action: Record<string, unknown> | null;
+    /** Additive Builder-specific execution context. Generic adapters may ignore it. */
+    gate_action_envelope?: GateActionEnvelope;
+    /** Canonical progress observation, available even when no action envelope is emitted. */
+    progress_snapshot?: GateActionProgressSnapshot;
 };
 export type ContinuationTurnRequest = {
     schema_version: "1.0";
@@ -21,6 +28,8 @@ export type ContinuationTurnRequest = {
     iteration: number;
     max_turns: number;
     next_action: Record<string, unknown> | null;
+    /** Additive schema-1.0 field; older external adapters remain valid. */
+    gate_action_envelope?: GateActionEnvelope;
 };
 export type ContinuationTurnResult = {
     status: "completed";
@@ -45,12 +54,20 @@ export type ContinuationDriverState = {
     turns_started: number;
     active_turn_step?: string | null;
     active_turn_public_key_digest?: string | null;
+    /** Durable recovery marker for an adapter turn without a post-turn measurement. */
+    active_turn_phase?: "prepared" | "started" | "measured" | null;
+    active_turn_progress?: GateActionProgressSnapshot | null;
+    /** Crash-recovery journal entry retained until capture and audit are durable. */
+    active_turn_capture?: ContinuationAcceptedTurn | null;
+    /** Last canonical progress observed after an adapter turn. Additive to state schema 1.0. */
+    last_progress?: GateActionProgressSnapshot | null;
+    prior_progress?: GateActionPriorProgress | 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";
+    type: "started" | "turn_started" | "turn_completed" | "turn_recovered" | "gate_not_advanced" | "turn_failed" | "authority_cleanup_failed" | "parked" | "resumed" | "done" | "budget_exhausted";
     run_id: string;
     definition_id: string;
     current_step: string;
@@ -59,12 +76,31 @@ export type ContinuationDriverEvent = {
     barrier?: ContinuationBarrier;
     summary?: string;
     failure_kind?: "adapter_error" | "timeout";
+    progress?: GateActionPriorProgress;
+    turn_id?: string;
+};
+export type ContinuationAcceptedTurn = {
+    schema_version: "1.0";
+    turn_id: string;
+    iteration: number;
+    request: ContinuationTurnRequest;
+    result: ContinuationTurnResult;
+    progress: GateActionPriorProgress | null;
+    captured_at: string;
 };
 export interface ContinuationStateStore {
     load(): ContinuationDriverState | null;
     save(state: ContinuationDriverState): void;
     append(event: ContinuationDriverEvent): void;
 }
+/**
+ * Optional durable accepted-turn journal. Kept separate so existing stores that
+ * only implement load/save/append remain valid continuation drivers.
+ */
+export interface ContinuationAcceptedTurnJournal {
+    captureAcceptedTurn(turn: ContinuationAcceptedTurn): void;
+    acceptedTurns(): ContinuationAcceptedTurn[];
+}
 export interface ContinuationRuntimePort {
     inspect(): Promise<ContinuationSnapshot>;
     synchronize(): Promise<ContinuationSnapshot>;
@@ -99,6 +135,7 @@ export interface RunContinuationDriverInput {
     waitForBarrier?: (barrier: ContinuationBarrier) => Promise<"ready" | "pending">;
     authorizeTurn?: () => Promise<void>;
     issueTurnAuthority?: (request: ContinuationTurnRequest) => Promise<ContinuationTurnAuthority>;
+    preflightTurn?: (request: ContinuationTurnRequest) => void | Promise<void>;
     onTurnAccepted?: (request: ContinuationTurnRequest, result: ContinuationTurnResult) => void | Promise<void>;
     now?: () => Date;
 }
@@ -110,10 +147,10 @@ export interface DriveBuilderFlowSessionInput {
     waitForBarrier?: RunContinuationDriverInput["waitForBarrier"];
     authorizeTurn?: RunContinuationDriverInput["authorizeTurn"];
     issueTurnAuthority?: RunContinuationDriverInput["issueTurnAuthority"];
+    preflightTurn?: RunContinuationDriverInput["preflightTurn"];
     onTurnAccepted?: RunContinuationDriverInput["onTurnAccepted"];
     now?: () => Date;
+    store?: ContinuationStateStore;
 }
 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;