@kontourai/flow-agents 3.12.1 → 4.0.0

package/src/cli/workflow.ts

@@ -74,7 +74,7 @@ export async function main(argv: string[]): Promise<number> {
 
 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", "evidence-signing-key-file", "max-turns", "turn-timeout-ms", "barrier-wait-ms", "barrier-poll-ms"]), "workflow drive");
+  assertOnlyFlags(parsed.flags, new Set(["artifact-root", "session-dir", "json", "adapter-command-file", "evidence-signing-key-file", "max-turns", "turn-timeout-ms", "barrier-wait-ms", "barrier-poll-ms", "context-policy"]), "workflow drive");
   const adapterCommandFile = flagString(parsed.flags, "adapter-command-file");
   if (!adapterCommandFile) throw new Error("workflow drive requires --adapter-command-file <path>");
   const evidenceSigningKeyFile = flagString(parsed.flags, "evidence-signing-key-file");
@@ -83,6 +83,7 @@ async function drive(sessionDir: string, argv: string[], json: boolean): Promise
   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 contextPolicy = enumFlag(parsed.flags, "context-policy", ["warm", "fresh"] as const, "warm");
   const { slug, projectRoot } = readBoundSession(sessionDir);
   assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
   const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
@@ -97,6 +98,7 @@ async function drive(sessionDir: string, argv: string[], json: boolean): Promise
       store: continuationStore,
       maxTurns,
       adapterCommandIdentity: adapterCommand.identity,
+      contextPolicy,
       authorizeTurn: async () => { assertOrdinaryMatchingAssignmentActor(sessionDir, slug); },
       issueTurnAuthority: async (request) => {
         const currentAssignment = assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
@@ -793,6 +795,18 @@ function integerFlag(
   return value;
 }
 
+function enumFlag<const T extends readonly string[]>(
+  flags: ReturnType<typeof parseArgs>["flags"],
+  name: string,
+  allowed: T,
+  fallback: T[number],
+): T[number] {
+  const raw = flagString(flags, name);
+  if (raw === undefined) return fallback;
+  if (!allowed.includes(raw)) throw new Error(`workflow drive --${name} must be one of: ${allowed.join(", ")}`);
+  return raw;
+}
+
 function isWithin(candidate: string, root: string): boolean {
   const relative = path.relative(root, candidate);
   return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));

package/src/cli/writer-observed-execution.test.mjs

@@ -0,0 +1,102 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+import { appendWriterObservedCommands, WRITER_OBSERVATION_SOURCE } from "../../build/src/cli/workflow-sidecar.js";
+
+const require = createRequire(import.meta.url);
+const repoRoot = path.resolve(import.meta.dirname, "../..");
+const { verifyCommandLogChain } = require(path.join(repoRoot, "scripts/hooks/stop-goal-fit.js"));
+const chain = require(path.join(repoRoot, "scripts/lib/command-log-chain.js"));
+
+const NOW = "2026-07-14T14:00:00.000Z";
+
+function tempSession(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "writer-observed-"));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+function readEntries(dir) {
+  return fs.readFileSync(path.join(dir, "command-log.jsonl"), "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+
+function hookEntry(prevHash, seq, record) {
+  const full = { ...record, source: "postToolUse-capture" };
+  const hash = chain.computeChainHash(prevHash, full);
+  return { entry: { ...full, _chain: { seq, prevHash, hash } }, hash };
+}
+
+test("appendWriterObservedCommands extends an existing hook chain with verifiable links", (t) => {
+  const dir = tempSession(t);
+  const { entry, hash } = hookEntry(chain.CHAIN_GENESIS, 0, { command: "echo hi", observedResult: "ambiguous", exitCode: null, capturedAt: NOW });
+  fs.writeFileSync(path.join(dir, "command-log.jsonl"), `${JSON.stringify(entry)}\n`);
+
+  appendWriterObservedCommands(dir, [
+    { command: "npm run test:unit", exit_code: 0, output_sha256: "a".repeat(64), test_count: 5, execution_proof: { kind: "local-process-exit", pid: 123 } },
+    { command: "npm run validate:source", exit_code: 0, output_sha256: "b".repeat(64) },
+  ], NOW);
+
+  const entries = readEntries(dir);
+  assert.equal(entries.length, 3);
+  assert.equal(entries[1].source, WRITER_OBSERVATION_SOURCE);
+  assert.equal(entries[1].observedResult, "pass");
+  assert.equal(entries[1].exitCode, 0);
+  assert.equal(entries[1].writer.output_sha256, "a".repeat(64));
+  assert.equal(entries[1].writer.test_count, 5);
+  assert.equal(entries[1]._chain.prevHash, hash);
+  assert.equal(entries[2]._chain.prevHash, entries[1]._chain.hash);
+
+  const verdict = verifyCommandLogChain(dir);
+  assert.equal(verdict.status, "ok");
+});
+
+test("a nonzero writer exit code records an observed fail", (t) => {
+  const dir = tempSession(t);
+  appendWriterObservedCommands(dir, [{ command: "npm run test:unit", exit_code: 1, output_sha256: "c".repeat(64) }], NOW);
+  const entries = readEntries(dir);
+  assert.equal(entries[0].observedResult, "fail");
+  assert.equal(entries[0].exitCode, 1);
+});
+
+test("chain verification tolerates writer/hook fork siblings but rejects any third source", (t) => {
+  const dir = tempSession(t);
+  const { entry: base, hash: baseHash } = hookEntry(chain.CHAIN_GENESIS, 0, { command: "echo hi", observedResult: "ambiguous", exitCode: null, capturedAt: NOW });
+
+  const hookSibling = { command: "npm test", observedResult: "ambiguous", exitCode: null, capturedAt: NOW, source: "postToolUse-capture" };
+  hookSibling._chain = { seq: 1, prevHash: baseHash, hash: chain.computeChainHash(baseHash, { command: hookSibling.command, observedResult: hookSibling.observedResult, exitCode: hookSibling.exitCode, capturedAt: hookSibling.capturedAt, source: hookSibling.source }) };
+  const writerSibling = { command: "npm test", observedResult: "pass", exitCode: 0, capturedAt: NOW, source: WRITER_OBSERVATION_SOURCE, writer: { output_sha256: "d".repeat(64) } };
+  writerSibling._chain = { seq: 1, prevHash: baseHash, hash: chain.computeChainHash(baseHash, { command: writerSibling.command, observedResult: writerSibling.observedResult, exitCode: writerSibling.exitCode, capturedAt: writerSibling.capturedAt, source: writerSibling.source, writer: writerSibling.writer }) };
+
+  const writeLog = (entries) => fs.writeFileSync(path.join(dir, "command-log.jsonl"), entries.map((e) => JSON.stringify(e)).join("\n") + "\n");
+  writeLog([base, hookSibling, writerSibling]);
+  assert.equal(verifyCommandLogChain(dir).status, "forked");
+
+  // The benign set is EXACTLY {postToolUse-capture, canonical-writer-execution}: any other
+  // source on a shared parent is tamper, however plausible its name (review finding — a
+  // single pinned name would not catch the set being widened further).
+  for (const source of ["manual-injection", "canonical-writer-execution-v2", "postToolUse-capture2", "orchestrator-attest", ""]) {
+    const forged = { command: "npm test", observedResult: "pass", exitCode: 0, capturedAt: NOW, source };
+    forged._chain = { seq: 1, prevHash: baseHash, hash: chain.computeChainHash(baseHash, { command: forged.command, observedResult: forged.observedResult, exitCode: forged.exitCode, capturedAt: forged.capturedAt, source: forged.source }) };
+    writeLog([base, hookSibling, forged]);
+    assert.equal(verifyCommandLogChain(dir).status, "broken", `source "${source}" must poison the fork`);
+  }
+});
+
+test("mutating writer metadata after the fact breaks the entry's self-hash", (t) => {
+  const dir = tempSession(t);
+  appendWriterObservedCommands(dir, [{ command: "npm run test:unit", exit_code: 0, output_sha256: "f".repeat(64) }], NOW);
+  assert.equal(verifyCommandLogChain(dir).status, "ok");
+  const entries = readEntries(dir);
+  // An attacker upgrading the recorded observation (or its provenance) cannot keep the hash.
+  entries[0].writer.output_sha256 = "0".repeat(64);
+  fs.writeFileSync(path.join(dir, "command-log.jsonl"), entries.map((e) => JSON.stringify(e)).join("\n") + "\n");
+  assert.equal(verifyCommandLogChain(dir).status, "broken");
+});
+
+test("append is fail-open: an unwritable session dir does not throw", () => {
+  assert.doesNotThrow(() => appendWriterObservedCommands("/nonexistent/definitely-missing", [{ command: "x", exit_code: 0, output_sha256: "e".repeat(64) }], NOW));
+});

package/src/cli.ts

@@ -11,12 +11,15 @@ import { main as init } from "./cli/init.js";
 import { main as promoteWorkflowArtifact } from "./cli/promote-workflow-artifact.js";
 import { main as publishChange } from "./cli/publish-change-helper.js";
 import { main as pullWorkProvider } from "./cli/pull-work-provider.js";
+import { main as narrativeRender } from "./cli/narrative-render.js";
+import { main as narrativeSources } from "./cli/narrative-sources.js";
 import { main as telemetryDoctor } from "./cli/telemetry-doctor.js";
 import { main as usageFeedback } from "./cli/usage-feedback.js";
 import { main as veritasGovernance } from "./cli/veritas-governance.js";
 import { main as workflowArtifactCleanupAudit } from "./cli/workflow-artifact-cleanup-audit.js";
 import { main as workflow } from "./cli/workflow.js";
 import { main as buildBundles } from "./tools/build-universal-bundles.js";
+import { main as capabilityMatrix } from "./tools/generate-capability-matrix.js";
 import { main as contextMap } from "./tools/generate-context-map.js";
 import { main as validateSource } from "./tools/validate-source-tree.js";
 import { main as validatePackage } from "./tools/validate-package.js";
@@ -29,6 +32,7 @@ import { main as verify } from "./cli/verify.js";
 const availableCommands = new Map<string, (argv: string[]) => number | Promise<number>>([
   ["build-bundles", () => buildBundles()],
   ["builder-run", builderRun],
+  ["capability-matrix", capabilityMatrix],
   ["console-learning-projection", consoleLearningProjection],
   ["context-map", contextMap],
   ["assignment-provider", assignmentProvider],
@@ -36,6 +40,8 @@ const availableCommands = new Map<string, (argv: string[]) => number | Promise<n
   ["effective-backlog-settings", effectiveBacklogSettings],
   ["fixture-retirement-audit", fixtureRetirementAudit],
   ["kit", kit],
+  ["narrative-render", narrativeRender],
+  ["narrative-sources", narrativeSources],
   ["init", init],
   ["promote-workflow-artifact", promoteWorkflowArtifact],
   ["publish-change", publishChange],
@@ -56,6 +62,7 @@ const availableCommands = new Map<string, (argv: string[]) => number | Promise<n
 
 const aliases = new Map<string, string>([
   ["flow-agents-build-bundles", "build-bundles"],
+  ["flow-agents-capability-matrix", "capability-matrix"],
   ["flow-agents-console-learning-projection", "console-learning-projection"],
   ["flow-agents-context-map", "context-map"],
   ["flow-agents-assignment-provider", "assignment-provider"],
@@ -63,6 +70,7 @@ const aliases = new Map<string, string>([
   ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
   ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
   ["flow-agents-kit", "kit"],
+  ["flow-agents-narrative-render", "narrative-render"],
   ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],
   ["flow-agents-publish-change", "publish-change"],
   ["flow-agents-pull-work-provider", "pull-work-provider"],

package/src/continuation-driver.ts

@@ -40,6 +40,16 @@ export type ContinuationTurnRequest = {
   next_action: Record<string, unknown> | null;
   /** Additive schema-1.0 field; older external adapters remain valid. */
   gate_action_envelope?: GateActionEnvelope;
+  /** Product-owned context routing; adapters must not infer this from model names. */
+  context_strategy?: ContinuationContextStrategy;
+};
+
+export type ContinuationContextPolicy = "warm" | "fresh";
+
+export type ContinuationContextStrategy = {
+  thread: "new" | "resume";
+  handoff: "canonical";
+  reason: "mission_start" | "configured_policy";
 };
 
 export type ContinuationTurnResult =
@@ -62,6 +72,8 @@ export type ContinuationDriverState = {
   definition_id: string;
   max_turns: number;
   adapter_command_identity: string | null;
+  /** Additive to schema 1.0. Missing legacy values mean warm. */
+  context_policy?: ContinuationContextPolicy;
   status: "active" | "waiting" | "done" | "failed" | "budget_exhausted";
   turns_started: number;
   // Added after schema 1.0 shipped. Legacy state files may omit it.
@@ -154,6 +166,7 @@ export type ContinuationDriverOutcome = {
 export interface RunContinuationDriverInput {
   maxTurns: number;
   adapterCommandIdentity?: string;
+  contextPolicy?: ContinuationContextPolicy;
   runtime: ContinuationRuntimePort;
   store: ContinuationStateStore;
   waitForBarrier?: (barrier: ContinuationBarrier) => Promise<"ready" | "pending">;
@@ -168,6 +181,7 @@ export interface DriveBuilderFlowSessionInput {
   sessionDir: string;
   maxTurns: number;
   adapterCommandIdentity?: string;
+  contextPolicy?: ContinuationContextPolicy;
   execute: ContinuationRuntimePort["execute"];
   waitForBarrier?: RunContinuationDriverInput["waitForBarrier"];
   authorizeTurn?: RunContinuationDriverInput["authorizeTurn"];
@@ -182,10 +196,12 @@ export async function runContinuationDriver(input: RunContinuationDriverInput):
   assertMaxTurns(input.maxTurns);
   const now = input.now ?? (() => new Date());
   const adapterCommandIdentity = input.adapterCommandIdentity ?? null;
+  const contextPolicy = input.contextPolicy ?? "warm";
   const inspected = validateSnapshot(await input.runtime.inspect());
-  let state = loadOrCreateState(input.store, inspected, input.maxTurns, adapterCommandIdentity, now);
+  let state = loadOrCreateState(input.store, inspected, input.maxTurns, adapterCommandIdentity, contextPolicy, now);
   if (state.max_turns !== input.maxTurns) throw new Error(`continuation maxTurns ${input.maxTurns} does not match the persisted mission budget ${state.max_turns}`);
   if (state.adapter_command_identity !== adapterCommandIdentity) throw new Error("continuation adapter command identity does not match the persisted mission adapter");
+  if ((state.context_policy ?? "warm") !== contextPolicy) throw new Error("continuation context policy does not match the persisted mission policy");
   let settled = await settleMissionStart(input, state, now);
   if (settled.outcome) return settled.outcome;
   ({ state } = settled);
@@ -288,9 +304,19 @@ function continuationTurnRequest(input: RunContinuationDriverInput, state: Conti
     max_turns: input.maxTurns,
     next_action: snapshot.next_action ? structuredClone(snapshot.next_action) : null,
     ...(envelope ? { gate_action_envelope: envelope } : {}),
+    context_strategy: contextStrategy(input.contextPolicy ?? "warm", state.turns_started + 1),
   });
 }
 
+function contextStrategy(policy: ContinuationContextPolicy, iteration: number): ContinuationContextStrategy {
+  const missionStart = iteration === 1;
+  return {
+    thread: missionStart || policy === "fresh" ? "new" : "resume",
+    handoff: "canonical",
+    reason: missionStart ? "mission_start" : "configured_policy",
+  };
+}
+
 function beginContinuationTurn(store: ContinuationStateStore, state: ContinuationDriverState, snapshot: ContinuationSnapshot, iteration: number, now: () => Date): ContinuationDriverState {
   let started = saveState(store, state, {
     status: "active", turns_started: iteration, active_turn_step: snapshot.current_step,
@@ -474,8 +500,9 @@ export async function driveBuilderFlowSession(input: DriveBuilderFlowSessionInpu
     execute: input.execute,
   };
   return runContinuationDriver({
-      maxTurns: input.maxTurns,
-      ...(input.adapterCommandIdentity ? { adapterCommandIdentity: input.adapterCommandIdentity } : {}),
+    maxTurns: input.maxTurns,
+    ...(input.adapterCommandIdentity ? { adapterCommandIdentity: input.adapterCommandIdentity } : {}),
+    ...(input.contextPolicy ? { contextPolicy: input.contextPolicy } : {}),
     runtime,
     store: input.store ?? createFileContinuationStore(sessionDir),
     ...(input.waitForBarrier ? { waitForBarrier: input.waitForBarrier } : {}),
@@ -508,6 +535,7 @@ function loadOrCreateState(
   snapshot: ContinuationSnapshot,
   maxTurns: number,
   adapterCommandIdentity: string | null,
+  contextPolicy: ContinuationContextPolicy,
   now: () => Date,
 ): ContinuationDriverState {
   const existing = store.load();
@@ -522,6 +550,7 @@ function loadOrCreateState(
     definition_id: snapshot.definition_id,
     max_turns: maxTurns,
     adapter_command_identity: adapterCommandIdentity,
+    context_policy: contextPolicy,
     status: "active",
     turns_started: 0,
     active_turn_step: null,