@kontourai/flow-agents 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [3.7.0](https://github.com/kontourai/flow-agents/compare/v3.6.0...v3.7.0) (2026-07-12)
+
+
+### Features
+
+* **builder:** align kit skills with canonical Flow ([#552](https://github.com/kontourai/flow-agents/issues/552)) ([2d672ed](https://github.com/kontourai/flow-agents/commit/2d672ede2dc16f96ef2d5186a3f0b6fc1c9d162f))
+
 ## [3.6.0](https://github.com/kontourai/flow-agents/compare/v3.5.0...v3.6.0) (2026-07-11)
 
 

package/build/src/builder-flow-run-adapter.d.ts

@@ -1,6 +1,9 @@
 import { type FlowEvidenceEntry, type FlowLifecycleRequest, type FlowRunState, type GateOutcome, type JsonObject } from "@kontourai/flow";
 export declare const BUILDER_BUILD_FLOW_ID = "builder.build";
 export declare const BUILDER_BUILD_FLOW_RELATIVE_PATH = "kits/builder/flows/build.flow.json";
+export declare const BUILDER_SHAPE_FLOW_ID = "builder.shape";
+export declare const BUILDER_SHAPE_FLOW_RELATIVE_PATH = "kits/builder/flows/shape.flow.json";
+export type BuilderFlowId = typeof BUILDER_BUILD_FLOW_ID | typeof BUILDER_SHAPE_FLOW_ID;
 export interface BuilderBuildTrustBundleEvidenceInput {
     gate: string;
     /**
@@ -8,6 +11,8 @@ export interface BuilderBuildTrustBundleEvidenceInput {
      * Callers must not pass raw user-controlled paths to this local runtime API.
      */
     file: string;
+    /** SHA-256 of the immutable snapshot validated by Flow Agents before Flow attaches it. */
+    expectedSha256?: string;
     status?: "passed" | "failed";
     producer?: string;
     authorityTrace?: string;
@@ -28,6 +33,9 @@ export interface StartBuilderBuildRunInput {
     cwd?: string;
     runId?: string;
 }
+export interface StartBuilderFlowRunInput extends StartBuilderBuildRunInput {
+    flowId: BuilderFlowId;
+}
 export interface EvaluateBuilderBuildRunInput {
     runId: string;
     /**
@@ -45,8 +53,8 @@ export interface ChangeBuilderBuildRunLifecycleInput extends LoadBuilderBuildRun
     request: FlowLifecycleRequest;
     at?: string;
 }
-export interface BuilderBuildRunResult {
-    definitionId: typeof BUILDER_BUILD_FLOW_ID;
+export interface BuilderFlowRunResult {
+    definitionId: BuilderFlowId;
     definitionVersion: string;
     runId: string;
     dir: string;
@@ -56,6 +64,9 @@ export interface BuilderBuildRunResult {
     manifest: JsonObject;
     freshnessTransitions: JsonObject[];
 }
+export interface BuilderBuildRunResult extends Omit<BuilderFlowRunResult, "definitionId"> {
+    definitionId: typeof BUILDER_BUILD_FLOW_ID;
+}
 export type BuilderBuildRunIdentityMismatch = "definition-id" | "definition-version" | "definition-content";
 export declare class BuilderBuildRunInputError extends Error {
     readonly code: "BUILDER_BUILD_RUN_INVALID_INPUT";
@@ -80,10 +91,19 @@ export declare class BuilderBuildRunIdentityError extends Error {
 }
 export declare function resolveBuilderBuildFlowDefinitionPath(startDir?: string): string;
 export declare function startBuilderBuildRun(input: StartBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
+export declare function resolveBuilderFlowDefinitionPath(flowId: BuilderFlowId, startDir?: string): string;
+export declare function startBuilderFlowRun(input: StartBuilderFlowRunInput): Promise<BuilderFlowRunResult>;
 export declare function evaluateBuilderBuildRun(input: EvaluateBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
+export declare function evaluateBuilderFlowRun(input: EvaluateBuilderBuildRunInput): Promise<BuilderFlowRunResult>;
 export declare function loadBuilderBuildRun(input: LoadBuilderBuildRunInput): Promise<BuilderBuildRunResult>;
+export declare function loadBuilderFlowRun(input: LoadBuilderBuildRunInput): Promise<BuilderFlowRunResult>;
 export declare function pauseBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult>;
 export declare function resumeBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult>;
 export declare function cancelBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult & {
     idempotent: boolean;
 }>;
+export declare function pauseBuilderFlowRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderFlowRunResult>;
+export declare function resumeBuilderFlowRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderFlowRunResult>;
+export declare function cancelBuilderFlowRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderFlowRunResult & {
+    idempotent: boolean;
+}>;

package/build/src/builder-flow-run-adapter.js

@@ -1,12 +1,14 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
-import { attachEvidence, cancelRun, evaluateRun, expectationsForGate, loadRun, normalizeTrustBundle, openGates, pauseRun, readJson, resumeRun, startRun, validateDefinition, } from "@kontourai/flow";
+import { attachEvidence, cancelRun, evaluateRun, expectationsForGate, loadRun, normalizeTrustBundle, openGates, pauseRun, resumeRun, startRun, validateDefinition, } from "@kontourai/flow";
 import { resolveEffectiveFlowDefinition } from "./lib/flow-resolver.js";
 export const BUILDER_BUILD_FLOW_ID = "builder.build";
 export const BUILDER_BUILD_FLOW_RELATIVE_PATH = "kits/builder/flows/build.flow.json";
+export const BUILDER_SHAPE_FLOW_ID = "builder.shape";
+export const BUILDER_SHAPE_FLOW_RELATIVE_PATH = "kits/builder/flows/shape.flow.json";
 export class BuilderBuildRunInputError extends Error {
     code = "BUILDER_BUILD_RUN_INVALID_INPUT";
     field;
@@ -36,18 +38,25 @@ export class BuilderBuildRunIdentityError extends Error {
     }
 }
 export function resolveBuilderBuildFlowDefinitionPath(startDir = moduleDirectory()) {
-    const root = findPackageRoot(startDir);
-    return path.join(root, BUILDER_BUILD_FLOW_RELATIVE_PATH);
+    return resolveBuilderFlowDefinitionPath(BUILDER_BUILD_FLOW_ID, startDir);
 }
 export async function startBuilderBuildRun(input) {
+    const result = await startBuilderFlowRun({ ...input, flowId: BUILDER_BUILD_FLOW_ID });
+    return asBuilderBuildResult(result, input.runId ?? result.runId);
+}
+export function resolveBuilderFlowDefinitionPath(flowId, startDir = moduleDirectory()) {
+    const root = findPackageRoot(startDir);
+    return path.join(root, flowRelativePath(flowId));
+}
+export async function startBuilderFlowRun(input) {
     assertRuntimeInput(input, ["evidence", "now", "gate"]);
     if (!isNonEmptyString(input.subject)) {
         throw new BuilderBuildRunInputError("subject", "must be a non-empty string");
     }
     const cwd = input.cwd ?? process.cwd();
-    const definitionPath = resolveBuilderBuildFlowDefinitionPath();
-    const definition = await loadShippedBuilderBuildDefinition(definitionPath);
-    const runtimeDefinitionPath = materializeRuntimeDefinition(cwd, definition);
+    const definitionPath = resolveBuilderFlowDefinitionPath(input.flowId);
+    const definition = await loadShippedBuilderFlowDefinition(input.flowId, definitionPath);
+    const runtimeDefinitionPath = materializeRuntimeDefinition(cwd, input.flowId, definition);
     const started = await startRun(runtimeDefinitionPath, {
         cwd,
         runId: input.runId,
@@ -56,25 +65,39 @@ export async function startBuilderBuildRun(input) {
             subject: input.subject,
         },
     });
-    const run = await loadCanonicalBuilderBuildRun(started.runId, cwd, definition);
+    const run = await loadCanonicalBuilderFlowRun(started.runId, cwd, definition);
     return resultFromRun(run, started.runId);
 }
 export async function evaluateBuilderBuildRun(input) {
+    const result = await evaluateBuilderFlowRun(input);
+    return asBuilderBuildResult(result, input.runId);
+}
+export async function evaluateBuilderFlowRun(input) {
     assertRuntimeInput(input, ["now", "gate"]);
     if (Array.isArray(input.evidence)) {
         throw new BuilderBuildRunInputError("evidence", "must be zero or one evidence object, not an array");
     }
     const cwd = input.cwd ?? process.cwd();
     const run = await loadRun(input.runId, cwd);
-    const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+    const definition = await loadShippedBuilderFlowDefinitionForRun(input.runId, run.definition);
     assertCanonicalDefinition(input.runId, definition, run.definition);
     let attachedEvidence = [];
     if (input.evidence !== undefined) {
         const evidence = validateEvidenceInput(input.evidence);
         assertCurrentOpenGate(run.definition, run.state, evidence.gate);
-        const normalized = normalizeTrustBundle(await readJson(path.resolve(cwd, evidence.file)));
+        const source = path.resolve(cwd, evidence.file);
+        const bytes = readFileSync(source);
+        const validatedSha256 = createHash("sha256").update(bytes).digest("hex");
+        if (evidence.expectedSha256 && evidence.expectedSha256 !== validatedSha256) {
+            throw new BuilderBuildRunInputError("evidence.expectedSha256", "does not match the bytes presented for validation");
+        }
+        const normalized = normalizeTrustBundle(JSON.parse(bytes.toString("utf8")));
         assertBundleSubjects(normalized.bundle, run.state.subject, openGates(run.definition, run.state)[0]);
-        attachedEvidence = [await attachEvidence(input.runId, trustBundleAttachOptions(cwd, evidence))];
+        const attached = await attachEvidence(input.runId, trustBundleAttachOptions(cwd, evidence, validatedSha256));
+        if (attached.sha256 !== validatedSha256) {
+            throw new BuilderBuildRunInputError("evidence.file", "changed after validation before Flow attachment");
+        }
+        attachedEvidence = [attached];
     }
     const evaluated = await evaluateRun(input.runId, { cwd });
     return {
@@ -90,35 +113,51 @@ export async function evaluateBuilderBuildRun(input) {
     };
 }
 export async function loadBuilderBuildRun(input) {
+    const result = await loadBuilderFlowRun(input);
+    return asBuilderBuildResult(result, input.runId);
+}
+export async function loadBuilderFlowRun(input) {
     assertRuntimeInput(input, ["evidence", "now", "gate"]);
     const cwd = input.cwd ?? process.cwd();
     const run = await loadRun(input.runId, cwd);
-    const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+    const definition = await loadShippedBuilderFlowDefinitionForRun(input.runId, run.definition);
     assertCanonicalDefinition(input.runId, definition, run.definition);
     return resultFromRun(run, input.runId);
 }
 export async function pauseBuilderBuildRun(input) {
-    return changeBuilderBuildRunLifecycle(input, pauseRun);
+    const result = await pauseBuilderFlowRun(input);
+    return asBuilderBuildResult(result, input.runId);
 }
 export async function resumeBuilderBuildRun(input) {
-    return changeBuilderBuildRunLifecycle(input, resumeRun);
+    const result = await resumeBuilderFlowRun(input);
+    return asBuilderBuildResult(result, input.runId);
 }
 export async function cancelBuilderBuildRun(input) {
-    const changed = await changeBuilderBuildRunLifecycleResult(input, cancelRun);
+    const changed = await changeBuilderFlowRunLifecycleResult(input, cancelRun);
+    return { ...asBuilderBuildResult(resultFromRun(changed, input.runId), input.runId), idempotent: changed.idempotent };
+}
+export async function pauseBuilderFlowRun(input) {
+    return changeBuilderFlowRunLifecycle(input, pauseRun);
+}
+export async function resumeBuilderFlowRun(input) {
+    return changeBuilderFlowRunLifecycle(input, resumeRun);
+}
+export async function cancelBuilderFlowRun(input) {
+    const changed = await changeBuilderFlowRunLifecycleResult(input, cancelRun);
     return { ...resultFromRun(changed, input.runId), idempotent: changed.idempotent };
 }
-async function changeBuilderBuildRunLifecycle(input, operation) {
-    const changed = await changeBuilderBuildRunLifecycleResult(input, operation);
+async function changeBuilderFlowRunLifecycle(input, operation) {
+    const changed = await changeBuilderFlowRunLifecycleResult(input, operation);
     return resultFromRun(changed, input.runId);
 }
-async function changeBuilderBuildRunLifecycleResult(input, operation) {
+async function changeBuilderFlowRunLifecycleResult(input, operation) {
     assertRuntimeInput(input, []);
     if (!isRecord(input.request))
         throw new BuilderBuildRunInputError("request", "must be a lifecycle request object");
     const cwd = input.cwd ?? process.cwd();
-    const before = await loadBuilderBuildRun({ runId: input.runId, cwd });
+    const before = await loadBuilderFlowRun({ runId: input.runId, cwd });
     const changed = await operation(input.runId, { cwd, ...input.request, ...(input.at ? { at: input.at } : {}) });
-    const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+    const definition = await loadShippedBuilderFlowDefinitionForRun(input.runId, changed.definition);
     assertCanonicalDefinition(input.runId, definition, changed.definition);
     if (changed.state.subject !== before.state.subject) {
         throw new BuilderBuildRunInputError("flow_run.state.subject", "changed during lifecycle transition");
@@ -138,33 +177,55 @@ function resultFromRun(run, runId) {
         freshnessTransitions: [],
     };
 }
-async function loadCanonicalBuilderBuildRun(runId, cwd, definition) {
+async function loadCanonicalBuilderFlowRun(runId, cwd, definition) {
     const run = await loadRun(runId, cwd);
     assertCanonicalDefinition(runId, definition, run.definition);
     return run;
 }
-async function loadShippedBuilderBuildDefinition(definitionPath) {
+async function loadShippedBuilderFlowDefinition(flowId, definitionPath) {
     const packageRoot = findPackageRoot(path.dirname(definitionPath));
-    const effective = resolveEffectiveFlowDefinition(BUILDER_BUILD_FLOW_ID, packageRoot, { allowOverride: false });
+    const effective = resolveEffectiveFlowDefinition(flowId, packageRoot, { allowOverride: false });
     if (!effective) {
         throw new BuilderBuildRunInputError("definition", "could not compile the shipped uses_flow composition");
     }
     const definition = validateDefinition(effective);
-    if (definition.id !== BUILDER_BUILD_FLOW_ID) {
-        throw new BuilderBuildRunInputError("definition", `expected shipped definition id ${BUILDER_BUILD_FLOW_ID}`);
+    if (definition.id !== flowId) {
+        throw new BuilderBuildRunInputError("definition", `expected shipped definition id ${flowId}`);
     }
     return definition;
 }
-function materializeRuntimeDefinition(cwd, definition) {
+async function loadShippedBuilderFlowDefinitionForRun(runId, actualDefinition) {
+    const flowId = actualDefinition.id;
+    if (!isBuilderFlowId(flowId)) {
+        throw new BuilderBuildRunIdentityError(runId, { id: BUILDER_BUILD_FLOW_ID, version: "unknown" }, actualDefinition, "definition-id");
+    }
+    return loadShippedBuilderFlowDefinition(flowId, resolveBuilderFlowDefinitionPath(flowId));
+}
+function materializeRuntimeDefinition(cwd, flowId, definition) {
     const content = `${JSON.stringify(definition, null, 2)}\n`;
     const digest = createHash("sha256").update(content).digest("hex").slice(0, 16);
     const directory = path.join(cwd, ".kontourai", "flow-agents", "runtime-definitions");
     mkdirSync(directory, { recursive: true });
-    const file = path.join(directory, `builder-build-${digest}.flow.json`);
+    const file = path.join(directory, `${flowId.replace(".", "-")}-${digest}.flow.json`);
     if (!existsSync(file))
         writeFileSync(file, content);
     return file;
 }
+function flowRelativePath(flowId) {
+    return flowId === BUILDER_BUILD_FLOW_ID ? BUILDER_BUILD_FLOW_RELATIVE_PATH : BUILDER_SHAPE_FLOW_RELATIVE_PATH;
+}
+function isBuilderFlowId(value) {
+    return value === BUILDER_BUILD_FLOW_ID || value === BUILDER_SHAPE_FLOW_ID;
+}
+function assertExpectedFlow(runId, actual, expected) {
+    if (actual === expected)
+        return;
+    throw new BuilderBuildRunIdentityError(runId, { id: expected, version: "unknown" }, { id: actual, version: "unknown" }, "definition-id");
+}
+function asBuilderBuildResult(result, runId) {
+    assertExpectedFlow(runId, result.definitionId, BUILDER_BUILD_FLOW_ID);
+    return result;
+}
 function assertCanonicalDefinition(runId, expectedDefinition, actualDefinition) {
     if (isDeepStrictEqual(actualDefinition, expectedDefinition))
         return;
@@ -195,6 +256,9 @@ function validateEvidenceInput(evidence) {
     if (!isNonEmptyString(evidence.file)) {
         throw new BuilderBuildRunInputError("evidence.file", "must be a non-empty string");
     }
+    if (evidence.expectedSha256 !== undefined && (!isNonEmptyString(evidence.expectedSha256) || !/^[a-f0-9]{64}$/i.test(evidence.expectedSha256))) {
+        throw new BuilderBuildRunInputError("evidence.expectedSha256", "must be a SHA-256 hex digest");
+    }
     if (evidence.status !== undefined && evidence.status !== "passed" && evidence.status !== "failed") {
         throw new BuilderBuildRunInputError("evidence.status", "must be passed or failed");
     }
@@ -227,11 +291,12 @@ function assertBundleSubjects(bundle, subject, gate) {
         }
     }
 }
-function trustBundleAttachOptions(cwd, evidence) {
+function trustBundleAttachOptions(cwd, evidence, expectedSha256) {
     return {
         cwd,
         gate: evidence.gate,
         file: evidence.file,
+        expectedSha256,
         kind: "trust.bundle",
         bundle: true,
         ...(evidence.status ? { status: evidence.status } : {}),

package/build/src/builder-flow-runtime.d.ts

@@ -1,7 +1,8 @@
-import { type BuilderBuildRunResult } from "./builder-flow-run-adapter.js";
+import { type BuilderFlowId, type BuilderFlowRunResult } from "./builder-flow-run-adapter.js";
 type AnyRecord = Record<string, any>;
 export interface BuilderFlowSessionInput {
     sessionDir: string;
+    flowId?: BuilderFlowId;
 }
 export interface BuilderFlowAuthorizedLifecycleInput extends BuilderFlowSessionInput {
     authorizationFile: string;
@@ -12,13 +13,14 @@ export interface BuilderFlowAgentLifecycleInput extends BuilderFlowSessionInput
 export interface BuilderFlowSessionResult {
     sessionDir: string;
     projectRoot: string;
-    run: BuilderBuildRunResult;
+    run: BuilderFlowRunResult;
     projection: AnyRecord;
     attached: boolean;
 }
 export declare function startBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function syncBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function recoverBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
+export declare function inspectBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function pauseBuilderFlowSession(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult>;
 export declare function resumeBuilderFlowSession(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult>;
 export declare function cancelBuilderFlowSession(input: BuilderFlowAuthorizedLifecycleInput): Promise<BuilderFlowSessionResult & {
@@ -31,5 +33,8 @@ export declare function releaseBuilderFlowAssignment(input: BuilderFlowAgentLife
 export declare function archiveBuilderFlowSession(input: BuilderFlowAuthorizedLifecycleInput): Promise<BuilderFlowSessionResult & {
     archiveDir: string;
 }>;
-export declare function syncBuilderFlowSessionIfPresent(sessionDir: string): Promise<BuilderFlowSessionResult | null>;
+export declare function captureReviewWorkspaceSnapshot(projectRoot: string, reviewedFiles: Array<{
+    file: string;
+    sha256: string;
+}>): AnyRecord;
 export {};