@kontourai/flow-agents 3.8.0 → 3.10.0

package/src/cli/public-api.test.mjs

@@ -37,6 +37,7 @@ test("public API retains the documented native-host compatibility surface", asyn
     "startBuilderBuildRun", "evaluateBuilderBuildRun", "startBuilderFlowSession",
     "pauseBuilderFlowSession", "resumeBuilderFlowSession", "cancelBuilderFlowSession",
     "archiveBuilderFlowSession", "recoverBuilderFlowSession", "releaseBuilderFlowAssignment",
+    "ContinuationAdapterTimeoutError",
     "writeJson", "appendJsonl", "sidecarBase", "writeState", "writeSidecar",
   ]) {
     assert.equal(typeof lib[name], "function", `${name} must remain package-root exported`);

package/src/cli/validate-workflow-artifacts.ts

@@ -22,6 +22,10 @@ const sidecarSchemas: Record<string, string> = {
   "release.json": "schemas/workflow-release.schema.json",
   "learning.json": "schemas/workflow-learning.schema.json",
 };
+// Runtime coordination records live below a session but are not workflow
+// sidecars. Recursing into them would validate continuation-driver/state.json
+// against the public workflow-state schema and turn an active driver into a
+// false Goal Fit hard block.
 
 function readText(file: string): string {
   return fs.readFileSync(file, "utf8");
@@ -91,11 +95,25 @@ function hasExplicitAcceptance(text: string): boolean {
   return /explicitly accepted|accepted by user|user accepted|accepted gap/i.test(text);
 }
 
+function isPrivateRuntimeChild(dir: string): boolean {
+  if (path.basename(dir) !== "continuation-driver") return false;
+  const sessionDir = path.dirname(dir);
+  const sessionState = path.join(sessionDir, "state.json");
+  try {
+    const stat = fs.lstatSync(sessionState);
+    if (stat.isSymbolicLink() || !stat.isFile()) return false;
+    const state = JSON.parse(readText(sessionState)) as { task_slug?: unknown };
+    return state.task_slug === path.basename(sessionDir);
+  } catch {
+    return false;
+  }
+}
+
 function walk(dir: string): string[] {
   const out: string[] = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walk(p));
+    if (entry.isDirectory() && !isPrivateRuntimeChild(p)) out.push(...walk(p));
     else out.push(p);
   }
   return out;

package/src/cli/workflow-sidecar.ts

@@ -275,7 +275,9 @@ function resolveEnsureSessionActor(p: ReturnType<typeof parseArgs>): { actorStru
     die("ensure-session --actor value strips to empty under the allowed actor charset ([A-Za-z0-9_.-]) — pass a value containing at least one letter, digit, underscore, period, or hyphen.");
   }
   const explicitActor = explicitActorRaw ? helper.sanitizeSegment(explicitActorRaw) : "";
-  const resolved = explicitActor ? { actor: explicitActor, source: "explicit-override" } : helper.resolveActor(process.env);
+  const resolved = explicitActor
+    ? { actor: explicitActor, source: "explicit-override", actorStruct: { runtime: "explicit-override", session_id: explicitActor, host: os.hostname() } }
+    : helper.resolveActorIdentity(process.env);
   const unresolved = helper.isUnresolvedActor(resolved.actor);
   const branchActorKey = unresolved ? `unknown-actor-${unknownDisambiguator(resolved.actor)}` : resolved.actor;
 
@@ -286,17 +288,8 @@ function resolveEnsureSessionActor(p: ReturnType<typeof parseArgs>): { actorStru
     return { actorStruct: { runtime: "unresolved", session_id: branchActorKey, host: os.hostname() }, actorKey: resolved.actor, branchActorKey, unresolved: true };
   }
 
-  // #398: the CI-runtime tier must reconstruct the SAME struct resolveActor serialized, or
-  // `serializeActor(actorStruct)` would diverge from `resolved.actor` (the else-branch would rebuild
-  // an ANCESTRY struct — detectRuntime→unknown, runtimeSessionId→'' — so the claim's stored
-  // actor_key would not match the CI actor at publish → self not recognized → false-block, the exact
-  // bug this issue removes). Uses the SAME helper.detectCiActor as resolveActor, single-sourced.
-  const ciActor = resolved.source.startsWith("ci-runtime") ? helper.detectCiActor(process.env) : null;
-  const actorStruct: ActorStruct = resolved.source === "explicit-override"
-    ? { runtime: "explicit-override", session_id: resolved.actor, host: os.hostname() }
-    : ciActor && ciActor.session_id
-      ? { runtime: ciActor.runtime, session_id: ciActor.session_id, host: os.hostname() }
-      : { runtime: helper.detectRuntime(process.env), session_id: helper.runtimeSessionId(process.env) || (() => { const seed = helper.ancestorActorSeed(); return seed ? `anc-${seed}` : ""; })(), host: os.hostname() };
+  if (!resolved.actorStruct) die("ensure-session could not resolve a canonical actor struct");
+  const actorStruct: ActorStruct = resolved.actorStruct;
   const actorKey = helper.serializeActor(actorStruct);
   return { actorStruct, actorKey, branchActorKey, unresolved: false };
 }
@@ -1613,6 +1606,7 @@ function resolveFirstStep(flowId: string, repoRoot: string): string | null {
 function loadCurrentPointerHelper(): {
   perActorCurrentFile: (flowAgentsDir: string, actorKey: string) => string;
   readCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
+  readOwnCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
   writePerActorCurrent: (flowAgentsDir: string, actorKey: string, payload: AnyObj) => void;
 } {
   const _req = createRequire(import.meta.url);
@@ -1620,6 +1614,7 @@ function loadCurrentPointerHelper(): {
   return _req(helperPath) as {
     perActorCurrentFile: (flowAgentsDir: string, actorKey: string) => string;
     readCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
+    readOwnCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: AnyObj | null; source: "per-actor" | "legacy" | "none"; file: string | null };
     writePerActorCurrent: (flowAgentsDir: string, actorKey: string, payload: AnyObj) => void;
   };
 }
@@ -1758,9 +1753,15 @@ function updateCurrentAgent(root: string, dir: string, agentId: string, status:
 
   if (actorKey && !loadActorIdentityHelper().isUnresolvedActor(actorKey)) {
     const helper = loadCurrentPointerHelper();
-    const perActorFile = helper.perActorCurrentFile(root, actorKey);
-    let perActor: AnyObj | null = null;
-    try { perActor = fs.existsSync(perActorFile) ? (JSON.parse(fs.readFileSync(perActorFile, "utf8")) as AnyObj) : null; } catch { perActor = null; }
+    // #440 fix-wave 3: read through the legacy-aware path (readOwnCurrentPointer tries the new
+    // collision-resistant filename first, then falls back to the pre-fix-wave-2 legacy filename)
+    // instead of a direct fs read of perActorCurrentFile() alone — a direct read of ONLY the new
+    // filename would silently skip this active_agents/updated_at projection for a pointer a
+    // still-running pre-fix-wave-2 sidecar wrote under the old name. The write below always goes
+    // through writePerActorCurrent (new filename only), so the pointer migrates to the new name
+    // on first touch.
+    const pointer = helper.readOwnCurrentPointer(root, actorKey);
+    const perActor = pointer.payload;
     if (perActor && path.resolve(root, perActor.artifact_dir ?? "") === path.resolve(dir)) {
       helper.writePerActorCurrent(root, actorKey, applyAgentUpdate(perActor));
     }
@@ -6088,6 +6089,7 @@ export const LIVENESS_TERMINAL = new Set(["delivered", "canceled", "accepted", "
  */
 function loadActorIdentityHelper(): {
   resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+  resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
   sanitizeSegment: (value: unknown) => string;
   isUnresolvedActor: (actor: string) => boolean;
   // #291 Wave 2 Task 2.1: widened (additive only — every existing caller above keeps using only
@@ -6097,22 +6099,15 @@ function loadActorIdentityHelper(): {
   // assignment-claim identity (a DIFFERENT identity concept from the flat actorKey used for
   // branch-naming/liveness — see resolveEnsureSessionActor's doc comment for why both exist).
   serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
-  detectRuntime: (env: NodeJS.ProcessEnv) => string;
-  runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
-  detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
-  ancestorActorSeed: () => string;
 } {
   const _req = createRequire(import.meta.url);
   const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/actor-identity.js");
   return _req(helperPath) as {
     resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+    resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
     sanitizeSegment: (value: unknown) => string;
     isUnresolvedActor: (actor: string) => boolean;
     serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
-    detectRuntime: (env: NodeJS.ProcessEnv) => string;
-    runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
-    detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
-    ancestorActorSeed: () => string;
   };
 }
 function resolveLivenessActor(): string {

package/src/cli/workflow.ts

@@ -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,6 +15,7 @@ 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";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -22,7 +24,7 @@ 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"] as const;
+const PUBLIC_VERBS = ["start", "status", "evidence", "critique", "drive", "pause", "resume", "release", "cancel", "archive", "doctor"] as const;
 
 function usage(): void {
   console.log(`Usage: flow-agents workflow <verb> [options]
@@ -32,6 +34,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.
@@ -61,12 +64,74 @@ export async function main(argv: string[]): Promise<number> {
   if (verb === "status") return status(sessionDir, flagBool(parsed.flags, "json"));
   if (verb === "evidence") 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: string, argv: string[], json: boolean): Promise<number> {
+  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(): {
+  issueActiveTurnAuthority(input: Record<string, unknown>): { runId: string; turnSecret: string; publicKeyDigest: string; cleanup(): boolean };
+  validateSignedActiveTurnAssignmentAuthority(input: Record<string, unknown>): { valid: boolean; record?: { assignment_actor: string; assignment_actor_struct: Record<string, unknown> } };
+} {
+  return REQUIRE(path.resolve(PACKAGE_ROOT, "scripts", "hooks", "lib", "continuation-turn-authority.js")) as {
+    issueActiveTurnAuthority(input: Record<string, unknown>): { runId: string; turnSecret: string; publicKeyDigest: string; cleanup(): boolean };
+    validateSignedActiveTurnAssignmentAuthority(input: Record<string, unknown>): { valid: boolean; record?: { assignment_actor: string; assignment_actor_struct: Record<string, unknown> } };
+  };
+}
+
 async function start(argv: string[]): Promise<number> {
   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");
@@ -486,15 +551,42 @@ function readAssignment(sessionDir: string, slug: string): JsonRecord {
 }
 
 function assertMatchingAssignmentActor(sessionDir: string, slug: string): ReturnType<typeof resolveCurrentAssignmentActor> {
-  const assignment = readActiveAssignment(sessionDir, slug);
-  const caller = resolveCurrentAssignmentActor();
-  const normalizeActor = (value: unknown): JsonRecord | null => value && typeof value === "object" ? { ...(value as JsonRecord), human: (value as JsonRecord).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)! as ReturnType<typeof resolveCurrentAssignmentActor>["actor"] };
   }
+  throw new Error("workflow mutation requires the session's active, matching assignment actor");
+}
+
+function assertOrdinaryMatchingAssignmentActor(sessionDir: string, slug: string): ReturnType<typeof resolveCurrentAssignmentActor> {
+  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: string, slug: string): {
+  assignment: JsonRecord;
+  caller: ReturnType<typeof resolveCurrentAssignmentActor>;
+  matches: boolean;
+} {
+  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: unknown): JsonRecord | null {
+  return value && typeof value === "object" ? { ...(value as JsonRecord), human: (value as JsonRecord).human ?? null } : null;
+}
+
 function readActiveAssignment(sessionDir: string, slug: string): JsonRecord {
   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)) {
@@ -570,6 +662,21 @@ function assertOnlyFlags(flags: ReturnType<typeof parseArgs>["flags"], allowed:
   if (unsupported) throw new Error(`${command} does not support --${unsupported}`);
 }
 
+function integerFlag(
+  flags: ReturnType<typeof parseArgs>["flags"],
+  name: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  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: string, root: string): boolean {
   const relative = path.relative(root, candidate);
   return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));