@kontourai/flow-agents 3.8.0 → 3.9.0

package/src/cli/builder-flow-runtime.test.mjs

@@ -18,9 +18,11 @@ import {
   syncBuilderFlowSession,
 } from "../../build/src/builder-flow-runtime.js";
 import { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization, recordAuthorizationConsumed } from "../../build/src/builder-lifecycle-authority.js";
+import { driveBuilderFlowSession } from "../../build/src/continuation-driver.js";
 import { cancelBuilderBuildRun } from "../../build/src/builder-flow-run-adapter.js";
 import { performLocalClaim, performLocalRelease, readLocalAssignmentStatus, resolveCurrentAssignmentActor } from "../../build/src/cli/assignment-provider.js";
 import { main as builderRunMain } from "../../build/src/cli/builder-run.js";
+import { main as workflowMain } from "../../build/src/cli/workflow.js";
 import { buildTrustBundle, inferExecutedTestCount, main as workflowSidecarMain } from "../../build/src/cli/workflow-sidecar.js";
 
 const SUBJECT = "local:work-item/runtime-projection";
@@ -88,7 +90,7 @@ function claimSessionAssignment(session) {
     ttlSeconds: 1800,
     actorKey: ACTOR_KEY,
     branch: `agent/${session.slug}`,
-    artifactDir: session.sessionDir,
+    artifactDir: session.slug,
     workItemRef: SUBJECT,
     reason: "test",
   });
@@ -100,7 +102,7 @@ function claimAmbientSessionAssignment(session) {
     ttlSeconds: 1800,
     actorKey: ambient.actorKey,
     branch: `agent/${session.slug}`,
-    artifactDir: session.sessionDir,
+    artifactDir: session.slug,
     workItemRef: SUBJECT,
     reason: "test",
   });
@@ -365,6 +367,130 @@ test("small-model client can start and advance from projected actions without ch
   assert.equal(duplicate.run.manifest.evidence.length, advanced.run.manifest.evidence.length);
 });
 
+test("Builder projection preserves Flow continuation semantics for exceptional statuses", async () => {
+  const session = makeSession("continuation-status-projection");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const stateFile = path.join(runDir(session.slug, session.projectRoot), "state.json");
+  const original = readJson(stateFile);
+  for (const [status, expected] of [
+    ["blocked", "continue"],
+    ["accepted_by_exception", "continue"],
+    ["needs_decision", "blocked"],
+    ["failed", "failed"],
+  ]) {
+    writeJson(stateFile, { ...original, status, next_action: `fixture ${status}` });
+    const recovered = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+    assert.equal(recovered.projection.next_action.status, expected, status);
+  }
+});
+
+test("continuation driver advances two real FlowDefinition steps unattended", async () => {
+  const session = makeSession("continuation-driver-two-steps");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const visited = [];
+
+  const result = await driveBuilderFlowSession({
+    sessionDir: session.sessionDir,
+    maxTurns: 2,
+    execute: async (request) => {
+      visited.push(request.current_step);
+      if (request.current_step === "pull-work") {
+        writeBundle(session.sessionDir, [bundleClaim({
+          expectation: "selected-work",
+          claimType: "builder.pull-work.selected",
+          subjectType: "work-item",
+        })]);
+      } else if (request.current_step === "design-probe") {
+        writeBundle(session.sessionDir, [
+          bundleClaim({
+            expectation: "pickup-probe-readiness",
+            claimType: "builder.design-probe.pickup-readiness",
+            subjectType: "work-item",
+          }),
+          bundleClaim({
+            expectation: "probe-decisions-or-accepted-gaps",
+            claimType: "builder.design-probe.decisions",
+            subjectType: "decision",
+          }),
+        ]);
+      } else {
+        assert.fail(`unexpected continuation step ${request.current_step}`);
+      }
+      return { status: "completed", summary: `completed ${request.current_step}` };
+    },
+  });
+
+  assert.equal(result.outcome, "budget_exhausted");
+  assert.equal(result.turns_started, 2);
+  assert.deepEqual(visited, ["pull-work", "design-probe"]);
+  assert.equal(result.snapshot.current_step, "plan");
+  assert.equal(result.snapshot.next_action.skills[0], "plan-work");
+  const driverState = readJson(path.join(session.sessionDir, "continuation-driver", "state.json"));
+  assert.equal(driverState.status, "budget_exhausted");
+  assert.equal(driverState.turns_started, 2);
+  const events = fs.readFileSync(path.join(session.sessionDir, "continuation-driver", "events.jsonl"), "utf8").trim().split("\n").map(JSON.parse);
+  assert.deepEqual(events.filter((event) => event.type === "turn_started").map((event) => event.current_step), ["pull-work", "design-probe"]);
+});
+
+test("public workflow drive invokes an explicit adapter but preserves canonical completion authority", async () => {
+  const session = makeSession("continuation-driver-cli");
+  claimAmbientSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const adapter = path.join(session.projectRoot, "adapter.mjs");
+  const commandFile = path.join(session.projectRoot, "adapter-command.json");
+  fs.writeFileSync(adapter, `
+    import fs from "node:fs";
+    let input = "";
+    for await (const chunk of process.stdin) input += chunk;
+    fs.writeFileSync("adapter-request.json", input);
+    process.stdout.write(JSON.stringify({ status: "completed", summary: "adapter says done" }));
+  `);
+  writeJson(commandFile, { argv: [process.execPath, adapter] });
+
+  const rc = await workflowMain([
+    "drive",
+    "--session-dir", session.sessionDir,
+    "--adapter-command-file", commandFile,
+    "--max-turns", "1",
+    "--turn-timeout-ms", "5000",
+    "--barrier-wait-ms", "0",
+    "--json",
+  ]);
+
+  assert.equal(rc, 0);
+  const request = readJson(path.join(session.projectRoot, "adapter-request.json"));
+  assert.equal(request.current_step, "pull-work");
+  assert.deepEqual(request.next_action.skills, ["pull-work"]);
+  assert.equal(Object.hasOwn(request, "system_prompt"), false);
+  const driverState = readJson(path.join(session.sessionDir, "continuation-driver", "state.json"));
+  assert.equal(driverState.status, "budget_exhausted");
+  const canonical = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+  assert.equal(canonical.run.state.status, "active");
+  assert.equal(canonical.run.state.current_step, "pull-work");
+});
+
+test("public workflow drive rejects a non-owner before adapter execution", async () => {
+  const session = makeSession("continuation-driver-owner");
+  claimSessionAssignment(session);
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const marker = path.join(session.projectRoot, "adapter-ran");
+  const adapter = path.join(session.projectRoot, "adapter.mjs");
+  const commandFile = path.join(session.projectRoot, "adapter-command.json");
+  fs.writeFileSync(adapter, `
+    import fs from "node:fs";
+    fs.writeFileSync(${JSON.stringify(marker)}, "ran");
+    process.stdout.write(JSON.stringify({ status: "completed" }));
+  `);
+  writeJson(commandFile, { argv: [process.execPath, adapter] });
+
+  await assert.rejects(
+    workflowMain(["drive", "--session-dir", session.sessionDir, "--adapter-command-file", commandFile]),
+    /active, matching assignment actor/,
+  );
+  assert.equal(fs.existsSync(marker), false);
+  assert.equal(fs.existsSync(path.join(session.sessionDir, "continuation-driver")), false);
+});
+
 test("sync attaches the staged trust.bundle bytes when the session bundle is replaced", async () => {
   const session = makeSession("snapshot-attachment");
   await startBuilderFlowSession({ sessionDir: session.sessionDir });

package/src/cli/continuation-adapter.ts

@@ -0,0 +1,239 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import type { ContinuationBarrier, ContinuationTurnRequest, ContinuationTurnResult } from "../continuation-driver.js";
+
+export type ContinuationAdapterCommand = {
+  argv: string[];
+  identity: string;
+  integrity: Array<{ file: string; sha256: string }>;
+};
+
+export function loadContinuationAdapterCommand(commandFileInput: string): ContinuationAdapterCommand {
+  const commandFile = path.resolve(commandFileInput);
+  const command = validateAdapterCommand(JSON.parse(readRegularFileNoFollow(commandFile, "continuation adapter command file")) as unknown);
+  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: string,
+  request: ContinuationTurnRequest,
+  options: { cwd: string; timeoutMs: number },
+): Promise<ContinuationTurnResult> {
+  const command = loadContinuationAdapterCommand(commandFileInput);
+  return executeLoadedContinuationAdapter(command, request, options);
+}
+
+export async function executeLoadedContinuationAdapter(
+  command: ContinuationAdapterCommand,
+  request: ContinuationTurnRequest,
+  options: { cwd: string; timeoutMs: number },
+): Promise<ContinuationTurnResult> {
+  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: ContinuationBarrier,
+  options: { maxWaitMs: number; pollMs: number; now?: () => number; sleep?: (ms: number) => Promise<void> },
+): Promise<"ready" | "pending"> {
+  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: number) => new Promise<void>((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: ContinuationAdapterCommand,
+  request: ContinuationTurnRequest,
+  options: { cwd: string; timeoutMs: number },
+): Promise<ContinuationTurnResult> {
+  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: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    let forcedKill: NodeJS.Timeout | undefined;
+    let terminationError: Error | undefined;
+    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: Buffer) => {
+      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: Buffer) => {
+      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) as ContinuationTurnResult;
+        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 as NodeJS.ErrnoException).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: unknown): Pick<ContinuationAdapterCommand, "argv"> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("continuation adapter command file must contain an object");
+  const argv = (value as { argv?: unknown }).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] as string[] };
+}
+
+function assertRegularFile(file: string, label: string): void {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${label} must be a regular file`);
+}
+
+function readRegularFileNoFollow(file: string, label: string): string {
+  return readRegularFileBufferNoFollow(file, label).toString("utf8");
+}
+
+function readRegularFileBufferNoFollow(file: string, label: string): Buffer {
+  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: number, label: string, min: number, max: number): void {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer from ${min} through ${max}`);
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function terminateProcessGroup(pid: number | undefined, signal: NodeJS.Signals): void {
+  if (!pid) return;
+  try {
+    process.kill(process.platform === "win32" ? pid : -pid, signal);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+  }
+}
+
+function isValidWaitResult(result: ContinuationTurnResult): boolean {
+  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: number | undefined): void {
+  terminateProcessGroup(pid, "SIGTERM");
+  const forcedKill = setTimeout(() => terminateProcessGroup(pid, "SIGKILL"), 250);
+  forcedKill.unref();
+}
+
+function regularFileExists(file: string): boolean {
+  try {
+    const stat = fs.lstatSync(file);
+    return !stat.isSymbolicLink() && stat.isFile();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function sha256File(file: string, label: string): string {
+  return createHash("sha256").update(readRegularFileBufferNoFollow(file, label)).digest("hex");
+}