@kontourai/flow-agents 3.11.0 → 3.12.0

package/dist/pi/build/src/flow-kit/validate.js

@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import * as path from "node:path";
 import { readJson } from "../lib/fs.js";
+import { parseKitFlowStepActions, workflowTriggerIdentifier } from "./action-metadata.js";
+import { validateActionRepositoryMetadata } from "./action-repository-validation.js";
+export { isObservableBuilderArtifactRef, isSafeBuilderArtifactRef, parseKitFlowStepActions } from "./action-metadata.js";
 // Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
 const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"];
 // Core container fields owned by kontourai/flow (flow-kit-container.schema.json).
@@ -15,88 +18,6 @@ const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals",
 // and first_party is legacy catalog/marketplace metadata. It does not grant runtime
 // capability or steering privilege.
 const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party"]);
-const MAX_FLOW_DEFINITION_BYTES = 1024 * 1024;
-function sameFileIdentity(left, right) {
-    return left.dev === right.dev && left.ino === right.ino;
-}
-function lstatSafePath(root, relativePath) {
-    const parts = relativePath.split(path.sep);
-    let current = root;
-    for (const [index, part] of parts.entries()) {
-        if (!part || part === "." || part === "..")
-            return { error: "path must stay inside the kit directory" };
-        current = path.join(current, part);
-        const stat = fs.lstatSync(current);
-        if (stat.isSymbolicLink())
-            return { error: "path must not traverse a symbolic link" };
-        if (index < parts.length - 1 && !stat.isDirectory())
-            return { error: "path component must be a directory" };
-        if (index === parts.length - 1)
-            return { file: current, stat };
-    }
-    return { error: "path must reference a regular file" };
-}
-function readSafeFlowDefinition(kitDir, relativePath) {
-    const root = path.resolve(kitDir);
-    if (path.isAbsolute(relativePath))
-        return { error: "path must be relative" };
-    const lexicalFile = path.resolve(root, relativePath);
-    if (lexicalFile === root || !lexicalFile.startsWith(`${root}${path.sep}`))
-        return { error: "path must stay inside the kit directory" };
-    let rootDescriptor;
-    let descriptor;
-    try {
-        const realRoot = fs.realpathSync.native(root);
-        rootDescriptor = fs.openSync(realRoot, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY);
-        const rootIdentity = fs.fstatSync(rootDescriptor);
-        if (!rootIdentity.isDirectory() || !sameFileIdentity(rootIdentity, fs.lstatSync(realRoot)))
-            return { error: "kit directory identity changed while opening flow definition" };
-        const initialPath = lstatSafePath(realRoot, relativePath);
-        if (!initialPath.file || !initialPath.stat)
-            return { error: initialPath.error };
-        if (!initialPath.stat.isFile())
-            return { error: "path must reference a regular file" };
-        if (initialPath.stat.size > MAX_FLOW_DEFINITION_BYTES)
-            return { error: `file exceeds ${MAX_FLOW_DEFINITION_BYTES} bytes` };
-        // O_NOFOLLOW protects the terminal component. Identity checks before and after
-        // opening make a race on any intermediate component fail closed on macOS/Node,
-        // where openat-style traversal from a directory descriptor is not exposed.
-        descriptor = fs.openSync(initialPath.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
-        const stat = fs.fstatSync(descriptor);
-        if (!stat.isFile())
-            return { error: "path must reference a regular file" };
-        if (!sameFileIdentity(initialPath.stat, stat))
-            return { error: "flow definition identity changed while opening" };
-        if (stat.size > MAX_FLOW_DEFINITION_BYTES)
-            return { error: `file exceeds ${MAX_FLOW_DEFINITION_BYTES} bytes` };
-        const verifiedPath = lstatSafePath(realRoot, relativePath);
-        if (!verifiedPath.stat || !sameFileIdentity(stat, verifiedPath.stat))
-            return { error: "flow definition identity changed while opening" };
-        const buffer = Buffer.alloc(stat.size);
-        let offset = 0;
-        while (offset < buffer.length) {
-            const read = fs.readSync(descriptor, buffer, offset, buffer.length - offset, offset);
-            if (read === 0)
-                break;
-            offset += read;
-        }
-        const finalStat = fs.fstatSync(descriptor);
-        if (offset !== stat.size || finalStat.size !== stat.size || !sameFileIdentity(stat, finalStat))
-            return { error: "file changed while being read" };
-        return { definition: JSON.parse(buffer.toString("utf8")) };
-    }
-    catch (error) {
-        if (error.code === "ELOOP")
-            return { error: "path must not reference a symbolic link" };
-        return { error: `path is not readable: ${error.message}` };
-    }
-    finally {
-        if (descriptor !== undefined)
-            fs.closeSync(descriptor);
-        if (rootDescriptor !== undefined)
-            fs.closeSync(rootDescriptor);
-    }
-}
 /**
  * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
  * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
@@ -155,10 +76,6 @@ export function parseKitDependencies(manifest, manifestPath) {
 function nonEmptyStringList(value) {
     return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && item.trim().length > 0);
 }
-const WORKFLOW_TRIGGER_IDENTIFIER_RE = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
-function workflowTriggerIdentifier(value) {
-    return typeof value === "string" && WORKFLOW_TRIGGER_IDENTIFIER_RE.test(value);
-}
 function optionalWorkflowTriggerIdentifier(value) {
     return value === undefined || workflowTriggerIdentifier(value);
 }
@@ -304,76 +221,6 @@ export function parseKitHookInfluenceExpectations(manifest, manifestPath) {
     });
     return { entries, errors };
 }
-export function parseKitFlowStepActions(manifest, manifestPath) {
-    const entries = [];
-    const errors = [];
-    const raw = manifest.flow_step_actions;
-    if (raw === undefined)
-        return { entries, errors };
-    if (!Array.isArray(raw)) {
-        errors.push(`${manifestPath}: .flow_step_actions must be a list`);
-        return { entries, errors };
-    }
-    const seen = new Set();
-    raw.forEach((entry, index) => {
-        if (typeof entry !== "object" || entry === null) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}] must be an object`);
-            return;
-        }
-        const record = entry;
-        if (!workflowTriggerIdentifier(record.flow_id)) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].flow_id must be a Flow identifier`);
-            return;
-        }
-        if (!workflowTriggerIdentifier(record.step_id)) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].step_id must be a step identifier`);
-            return;
-        }
-        const skills = record.skills;
-        const operations = record.operations ?? [];
-        const expectationIds = record.expectation_ids;
-        const artifacts = record.artifacts ?? [];
-        if (!Array.isArray(skills) || !skills.every(workflowTriggerIdentifier)) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].skills must be an identifier list`);
-            return;
-        }
-        if (new Set(skills).size !== skills.length) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].skills must not contain duplicates`);
-            return;
-        }
-        if (!Array.isArray(operations) || !operations.every(workflowTriggerIdentifier)) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].operations must be an identifier list when present`);
-            return;
-        }
-        if (new Set(operations).size !== operations.length) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].operations must not contain duplicates`);
-            return;
-        }
-        if (expectationIds !== undefined && (!Array.isArray(expectationIds) || !expectationIds.every(workflowTriggerIdentifier) || new Set(expectationIds).size !== expectationIds.length)) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].expectation_ids must be a unique identifier list when present`);
-            return;
-        }
-        if (!Array.isArray(artifacts) || !artifacts.every((artifact) => typeof artifact === "string" && artifact.trim().length > 0) || new Set(artifacts).size !== artifacts.length) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}].artifacts must be a unique non-empty string list when present`);
-            return;
-        }
-        const key = `${record.flow_id}/${record.step_id}`;
-        if (seen.has(key)) {
-            errors.push(`${manifestPath}: flow_step_actions[${index}] duplicates '${key}'`);
-            return;
-        }
-        seen.add(key);
-        entries.push({
-            flow_id: record.flow_id,
-            step_id: record.step_id,
-            skills: skills,
-            operations: operations,
-            artifacts: artifacts,
-            ...(Array.isArray(expectationIds) ? { expectation_ids: expectationIds } : {}),
-        });
-    });
-    return { entries, errors };
-}
 export function parseKitSkillRoles(manifest, manifestPath) {
     const entries = [];
     const errors = [];
@@ -556,15 +403,15 @@ export async function validateKitRepository(kitDir) {
         errors.push(`${manifestPath}: invalid JSON: ${error.message}`);
         return errors;
     }
-    // Delegate core container validation (schema_version, id, name, flows including file
-    // existence) to @kontourai/flow — the container contract lives once, in Flow.
-    // This enforces the degradation invariant: a Flow Agents Kit must remain a valid
-    // core Flow Kit container when extension fields are stripped.
-    const coreErrors = await delegateCoreContainerValidation(kitDir, manifest);
-    for (const err of coreErrors)
-        errors.push(err);
-    // Flow Agents extension validation: skills, docs, adapters, evals, assets.
-    // Flows are validated above by @kontourai/flow; only extension classes are checked here.
+    errors.push(...await delegateCoreContainerValidation(kitDir, manifest));
+    errors.push(...validateExtensionAssets(kitDir, manifestPath, manifest));
+    errors.push(...validateAgentMetadata(kitDir, manifestPath, manifest));
+    if (manifest.first_party !== undefined && typeof manifest.first_party !== "boolean")
+        errors.push(`${manifestPath}: .first_party must be a boolean when present`);
+    return errors;
+}
+function validateExtensionAssets(kitDir, manifestPath, manifest) {
+    const errors = [];
     for (const section of EXTENSION_ASSET_CLASSES) {
         const entries = manifest[section];
         if (entries === undefined)
@@ -606,9 +453,10 @@ export async function validateKitRepository(kitDir) {
             }
         });
     }
-    // Flow Agents metadata: cross-kit dependency declarations (extension-layer;
-    // see docs/adr/0019-kit-dependency-ownership.md). Shape-only here — presence is
-    // checked separately (non-blocking at install, hard error at activation).
+    return errors;
+}
+function validateAgentMetadata(kitDir, manifestPath, manifest) {
+    const errors = [];
     const depResult = parseKitDependencies(manifest, manifestPath);
     for (const err of depResult.errors)
         errors.push(err);
@@ -624,183 +472,8 @@ export async function validateKitRepository(kitDir) {
     const skillRoleResult = parseKitSkillRoles(manifest, manifestPath);
     for (const err of skillRoleResult.errors)
         errors.push(err);
-    if (manifest.skill_roles !== undefined && skillRoleResult.errors.length === 0) {
-        const declaredSkillIds = new Set(Array.isArray(manifest.skills)
-            ? manifest.skills.flatMap((entry) => typeof entry === "object" && entry !== null && typeof entry.id === "string" ? [entry.id] : [])
-            : []);
-        const roleSkillIds = new Set(skillRoleResult.entries.map((entry) => entry.skill_id));
-        for (const id of declaredSkillIds)
-            if (!roleSkillIds.has(id))
-                errors.push(`${manifestPath}: skill_roles is missing declared skill '${id}'`);
-        for (const id of roleSkillIds)
-            if (!declaredSkillIds.has(id))
-                errors.push(`${manifestPath}: skill_roles references undeclared skill '${id}'`);
-        const flows = new Map();
-        if (Array.isArray(manifest.flows)) {
-            for (const entry of manifest.flows) {
-                if (typeof entry !== "object" || entry === null)
-                    continue;
-                const flow = entry;
-                if (typeof flow.id !== "string" || typeof flow.path !== "string")
-                    continue;
-                const safeDefinition = readSafeFlowDefinition(kitDir, flow.path);
-                if (!safeDefinition.definition) {
-                    errors.push(`${manifestPath}: flows '${flow.id}' ${safeDefinition.error}`);
-                    continue;
-                }
-                try {
-                    const definition = safeDefinition.definition;
-                    const steps = new Set(Array.isArray(definition.steps) ? definition.steps.flatMap((step) => typeof step === "object" && step !== null && typeof step.id === "string" ? [step.id] : []) : []);
-                    const usesFlowByStep = new Map();
-                    if (Array.isArray(definition.steps)) {
-                        for (const step of definition.steps) {
-                            if (typeof step !== "object" || step === null)
-                                continue;
-                            const stepRecord = step;
-                            if (typeof stepRecord.id === "string" && typeof stepRecord.uses_flow === "string")
-                                usesFlowByStep.set(stepRecord.id, stepRecord.uses_flow);
-                        }
-                    }
-                    const expectationsByStep = new Map();
-                    if (typeof definition.gates === "object" && definition.gates !== null) {
-                        for (const gate of Object.values(definition.gates)) {
-                            if (typeof gate !== "object" || gate === null)
-                                continue;
-                            const gateRecord = gate;
-                            if (typeof gateRecord.step !== "string" || !Array.isArray(gateRecord.expects))
-                                continue;
-                            const expectations = expectationsByStep.get(gateRecord.step) ?? new Map();
-                            for (const expectation of gateRecord.expects) {
-                                if (typeof expectation !== "object" || expectation === null)
-                                    continue;
-                                const expectationRecord = expectation;
-                                if (typeof expectationRecord.id !== "string")
-                                    continue;
-                                const exportKeys = new Set([expectationRecord.id]);
-                                const claimType = expectationRecord.bundle_claim?.claimType;
-                                if (typeof claimType === "string")
-                                    exportKeys.add(claimType);
-                                expectations.set(expectationRecord.id, { id: expectationRecord.id, exportKeys });
-                            }
-                            expectationsByStep.set(gateRecord.step, expectations);
-                        }
-                    }
-                    flows.set(flow.id, {
-                        steps,
-                        expectationsByStep,
-                        usesFlowByStep,
-                        exports: new Set(Array.isArray(definition.exports) ? definition.exports.filter((entry) => typeof entry === "string" && entry.length > 0) : []),
-                    });
-                }
-                catch {
-                    // Core Flow validation reports missing or malformed definitions.
-                }
-            }
-        }
-        const resolveEffectiveFlowStep = (flowId, stepId, seen = new Set()) => {
-            const cycleKey = `${flowId}\u0000${stepId}`;
-            if (seen.has(cycleKey))
-                return undefined;
-            seen.add(cycleKey);
-            const flow = flows.get(flowId);
-            if (!flow)
-                return undefined;
-            const direct = flow.expectationsByStep.get(stepId);
-            if (direct)
-                return { sourceFlowId: flowId, stepId, expectations: direct, flowIds: new Set([flowId]) };
-            const childFlowId = flow.usesFlowByStep.get(stepId);
-            if (!childFlowId)
-                return { sourceFlowId: flowId, stepId, expectations: new Map(), flowIds: new Set([flowId]) };
-            const child = resolveEffectiveFlowStep(childFlowId, stepId, seen);
-            const childFlow = flows.get(childFlowId);
-            if (!child || !childFlow || [...child.expectations.values()].some((expectation) => ![...expectation.exportKeys].some((key) => childFlow.exports.has(key))))
-                return undefined;
-            child.flowIds.add(flowId);
-            return child;
-        };
-        for (const row of skillRoleResult.entries) {
-            if (!row.flow_id)
-                continue;
-            const flow = flows.get(row.flow_id);
-            if (!flow) {
-                errors.push(`${manifestPath}: skill_roles '${row.skill_id}' references unknown flow '${row.flow_id}'`);
-                continue;
-            }
-            for (const stepId of row.step_ids)
-                if (!flow.steps.has(stepId))
-                    errors.push(`${manifestPath}: skill_roles '${row.skill_id}' references unknown step '${row.flow_id}/${stepId}'`);
-            const allowedExpectations = new Set(row.step_ids.flatMap((stepId) => [...(resolveEffectiveFlowStep(row.flow_id, stepId)?.expectations.keys() ?? [])]));
-            for (const expectationId of row.expectation_ids)
-                if (!allowedExpectations.has(expectationId))
-                    errors.push(`${manifestPath}: skill_roles '${row.skill_id}' expectation '${expectationId}' is not owned by its bound step(s)`);
-        }
-        const roleByShortId = new Map(skillRoleResult.entries.map((entry) => [entry.skill_id.replace(`${String(manifest.id)}.`, ""), entry]));
-        const producerOwners = new Map();
-        for (const row of skillRoleResult.entries) {
-            if (row.role !== "step" || !row.flow_id)
-                continue;
-            for (const stepId of row.step_ids) {
-                const effectiveStep = resolveEffectiveFlowStep(row.flow_id, stepId);
-                if (!effectiveStep)
-                    continue;
-                for (const expectationId of row.expectation_ids) {
-                    if (!effectiveStep.expectations.has(expectationId))
-                        continue;
-                    const key = `${effectiveStep.sourceFlowId}\u0000${effectiveStep.stepId}\u0000${expectationId}`;
-                    producerOwners.set(key, [...(producerOwners.get(key) ?? []), `skill:${row.skill_id}`]);
-                }
-            }
-        }
-        for (const action of flowStepActionResult.entries) {
-            const containingFlow = flows.get(action.flow_id);
-            if (!containingFlow || !containingFlow.steps.has(action.step_id)) {
-                errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' references an unknown flow step`);
-                continue;
-            }
-            const effectiveStep = resolveEffectiveFlowStep(action.flow_id, action.step_id);
-            if (!effectiveStep) {
-                errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' cannot resolve its composed Flow step`);
-                continue;
-            }
-            const expectedAtStep = effectiveStep.expectations;
-            for (const expectationId of action.expectation_ids ?? []) {
-                if (!expectedAtStep.has(expectationId))
-                    errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' operation expectation '${expectationId}' is not owned by its resolved Flow step`);
-            }
-            if (action.skills.length === 0 && action.operations.length > 0 && expectedAtStep.size > 0 && !(action.expectation_ids?.length)) {
-                errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' operation-only action must explicitly declare expectation_ids`);
-            }
-            const actionRows = [];
-            for (const skill of action.skills) {
-                const row = roleByShortId.get(skill);
-                if (!row || row.role !== "step" || !row.flow_id || !effectiveStep.flowIds.has(row.flow_id) || !row.step_ids.includes(action.step_id)) {
-                    errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' skill '${skill}' must match one step-role binding`);
-                }
-                else {
-                    actionRows.push(row);
-                }
-            }
-            for (const expectationId of expectedAtStep.keys()) {
-                const key = `${effectiveStep.sourceFlowId}\u0000${effectiveStep.stepId}\u0000${expectationId}`;
-                const owners = producerOwners.get(key) ?? [];
-                if (action.operations.length > 0 && action.expectation_ids?.includes(expectationId))
-                    owners.push(`operation:${action.flow_id}/${action.step_id}`);
-                producerOwners.set(key, owners);
-            }
-        }
-        for (const [flowId, flow] of flows) {
-            for (const [stepId, expectations] of flow.expectationsByStep) {
-                for (const expectationId of expectations.keys()) {
-                    const owners = producerOwners.get(`${flowId}\u0000${stepId}\u0000${expectationId}`) ?? [];
-                    if (owners.length !== 1) {
-                        errors.push(`${manifestPath}: flow expectation '${flowId}/${stepId}/${expectationId}' must have exactly one producer owner; found ${owners.length}`);
-                    }
-                }
-            }
-        }
-    }
-    if (manifest.first_party !== undefined && typeof manifest.first_party !== "boolean") {
-        errors.push(`${manifestPath}: .first_party must be a boolean when present`);
+    if ((manifest.skill_roles !== undefined || manifest.flow_step_actions !== undefined) && skillRoleResult.errors.length === 0) {
+        errors.push(...validateActionRepositoryMetadata({ kitDir, manifestPath, manifest, actions: flowStepActionResult.entries, skillRoles: skillRoleResult.entries }));
     }
     return errors;
 }

package/dist/pi/build/src/index.d.ts

@@ -2,8 +2,10 @@ export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRu
 export type { BuilderBuildRunResult, BuilderBuildRunIdentityMismatch, BuilderBuildTrustBundleEvidenceInput, EvaluateBuilderBuildRunInput, LoadBuilderBuildRunInput, StartBuilderBuildRunInput, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } from "./builder-flow-runtime.js";
-export { ContinuationAdapterTimeoutError, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
-export type { ContinuationBarrier, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnAuthority, ContinuationTurnContext, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
+export { deriveBuilderGateActionEnvelope, gateActionProgressSnapshot, withGateActionPriorProgress, } from "./builder-gate-action-envelope.js";
+export type { BuilderGateActionEnvelopeInput, GateActionEnvelope, GateActionInterfaceParameter, GateActionPriorProgress, GateActionProgressSnapshot, GateActionPublicMutation, } from "./builder-gate-action-envelope.js";
+export { ContinuationAdapterTimeoutError, MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES, MAX_CONTINUATION_TURN_RESULT_BYTES, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
+export type { ContinuationBarrier, ContinuationAcceptedTurn, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnAuthority, ContinuationTurnContext, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export type { BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";

package/dist/pi/build/src/index.js

@@ -15,7 +15,8 @@ import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
-export { ContinuationAdapterTimeoutError, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
+export { deriveBuilderGateActionEnvelope, gateActionProgressSnapshot, withGateActionPriorProgress, } from "./builder-gate-action-envelope.js";
+export { ContinuationAdapterTimeoutError, MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES, MAX_CONTINUATION_TURN_RESULT_BYTES, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
 // Pure serialization contract used by external lifecycle authorities when
 // signing requests. This does not load, create, or mutate a Flow run.
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";

package/dist/pi/docs/public-workflow-cli.md

@@ -90,9 +90,10 @@ Critique derives reviewer identity from the calling runtime actor. An active
 implementation assignment is required, and its actor cannot review its own
 work; the delegated reviewer invokes the command directly under a distinct
 identity. The public interface does not accept a caller-selected reviewer
-label. Every critique includes an explicit verdict, at least one substantive
-`--lane-json`, and local reviewed `--artifact-ref` values. Passing critiques
-require every lane to pass; reviewed files and the workspace snapshot are
+label. Every critique includes an explicit `pass`, `fail`, or `not_verified`
+verdict and at least one substantive `--lane-json`. Passing critiques additionally
+require local reviewed `--artifact-ref` values and every lane to pass; reviewed
+files and the workspace snapshot are
 hashed into the stored review target so later implementation changes invalidate
 stale clean critiques.
 
@@ -173,7 +174,13 @@ flow_agents workflow drive \
 Driver state and its append-only event stream live under
 `.kontourai/flow-agents/<slug>/continuation-driver/`. The mission turn count survives reinvocation;
 subsequent invocations must use the same `--max-turns` value. The request contains the
-canonical run id, definition id, current step, projected `next_action`, iteration, and budget. It
+canonical run id, definition id, current step, projected `next_action`, iteration, and budget. Builder
+turns additionally carry one bounded top-level `gate_action_envelope` with immutable skill identities,
+declared artifacts/evidence, requirement satisfaction and unresolved ids, typed public
+`workflow.evidence`/`workflow.critique` argv or product-operation bindings, one-turn stop semantics,
+product-declared implementation policy, and prior canonical progress/stagnation. Parameter values are
+appended as separate argv entries; adapters must not perform string substitution into a shell command. The
+envelope is request-only and is not duplicated in projected `next_action` or durable `state.json`. It
 does not mutate or replace the runtime system prompt. Adapter errors are recorded as failed turns
 and fail open to canonical resynchronization and the next bounded turn; they cannot bypass the
 persisted mission budget. The Builder Flow projection supplies the canonical continue/wait/done/failed
@@ -188,6 +195,15 @@ state rollback or deletion is rejected when its append-only event history proves
 started. These local coordination records detect accidental or in-process rollback; they are not a
 cryptographic boundary against a process that can rewrite the entire artifact directory.
 
+An operation mutation is a structured product protocol, not necessarily a directly executable CLI
+command. In particular, `publish-change` identifies the provider capability `pull_request.create`,
+its bounded parameters, the required provider result, and `publish-change.result.json` as its dedicated
+result artifact. This release has no authenticated ChangeProvider executor. The operation therefore
+reports `external_capability_required` and `external_verification_required`, exposes no completion
+mutation, and parks the continuation. A locally authored result is not provider evidence. The installed
+`flow-agents publish-change` helper renders and validates publish artifacts and provider checks; it does
+not create a pull request and must not be treated as the operation executor.
+
 Immediately before spawning an adapter turn, the driver writes a transient, schema-versioned
 `active-turn.json` beside its mission state and passes a raw 32-byte turn secret plus the path-safe,
 signed run id in `FLOW_AGENTS_CONTINUATION_TURN_SECRET` and
@@ -230,7 +246,27 @@ The event stream records `turn_completed`, `gate_not_advanced`, `turn_failed`, a
 outcome. Failed turns carry
 `failure_kind` of `timeout` or `adapter_error`; a completed adapter turn whose canonical run remains
 active at the same current step records `gate_not_advanced`. These events describe driver execution only and do not
-change canonical Flow state.
+change canonical Flow state. Adapter-returned `evidence` is not interpreted as gate evidence; only
+the public `workflow evidence` path can attach evidence for Flow evaluation. Same-step canonical
+evidence or declared-artifact hash changes are recorded as progress, while repeated no-progress turns are
+classified as possible stagnation and then stagnant without fabricating a gate outcome.
+Progress uses run-wide canonical evidence/artifact manifests and resumes
+from the durable `last_progress` baseline after interruption or reinvocation. Kit metadata, skill source,
+and observed artifact reads are bounded descriptor-stable regular-file reads that reject symlinks and
+identity changes.
+Request-facing declared and required artifacts exclude control `state.json`, even where legacy kit
+ownership metadata retains it.
+Kit validation and envelope construction both cap an action at 16 skills and a flow at 128 distinct
+observable file artifacts, excluding virtual trust-bundle refs and control artifacts consistently.
+Synchronization measures an interrupted, waiting, terminal, or callback-failed turn before clearing
+its recovery marker. Evidence-free canonical gate evaluation is limited to accepted exceptions and
+gates whose effective expectations are all optional; ordinary missing-required gates remain unevaluated.
+Signed drives reserve aggregate attestation capacity before adapter execution when another bounded
+signed result cannot fit.
+The complete serialized adapter result is capped at 74,000 bytes, and preflight reserves that exact
+maximum plus the actual request and JSON structure. Accepted request/result pairs and measured progress
+are journaled durably before the active marker is cleared. Restart idempotently completes missing audit
+writes, and signed attestation fails closed when persisted accepted events lack journal coverage.
 
 ## Compatibility Doctor
 

package/dist/pi/docs/spec/builder-flow-runtime.md

@@ -153,6 +153,123 @@ composed steps that have no legacy sidecar phase (`merge-ready-ci` and `learn`).
 Both the legacy `current.json` pointer and every matching per-actor pointer are
 updated from that canonical step; `phase_map` is presentation metadata, not the
 authority for pointer navigation.
+
+### Gate-Action Envelope
+
+Every active Builder continuation request includes a bounded
+`gate_action_envelope` with schema version `1.0`. Flow Agents derives it from
+the persisted canonical Flow run and effective Flow Definition, then joins it
+to the installed Builder Kit's validated `flow_step_actions` record. It is an
+execution context, not a second gate evaluator: Flow remains the only authority
+that evaluates requirements, advances steps, routes back, or consumes attempt
+budget.
+
+The envelope provides the current gate ids and claim shapes, including each
+expectation's required flag and `satisfied`, `accepted_exception`, or `unresolved`
+status. Accepted exceptions are identified separately. Flow Agents evaluates
+these statuses with the run's effective Flow config, including gate overrides,
+so waived, satisfied, and optional work is never mislabeled as required. Skill
+identities bind package, version, stable package-relative source
+path, and SHA-256, so durable attestations never retain a stale absolute install path.
+Requirement status comes from Flow's canonical gate evaluation and therefore
+uses the expectation's trust-bundle selector, Surface-derived claim status,
+supersession, freshness, and current gate visit; `expectation_ids` labels alone
+never mark a requirement satisfied.
+Declared operations, artifacts, and evidence expectation ids come from product
+metadata. `implementation_allowed` is also product metadata; the shipped Builder
+Kit declares it true only for `builder.build/execute`.
+
+The read-only status interface is an exact version-pinned command. Mutation
+interfaces are typed per expectation: `workflow.evidence`, `workflow.critique`,
+or a named product operation such as `publish-change`. Evidence and critique
+interfaces expose fixed argv plus typed required parameters and allowed values;
+they do not publish shell strings with substitution placeholders. Consumers add
+parameter values as distinct argv entries.
+
+`publish-change` is a provider-capability protocol, not a claim that the local
+`flow-agents publish-change` helper opens a pull request. Its envelope binds the
+exact `pull_request.create` capability, bounded structured inputs, the required
+provider result, and the dedicated session-relative
+`publish-change.result.json` artifact. No authenticated ChangeProvider executor
+ships in this issue, so the operation is explicitly unavailable locally and has
+an `external_verification_required` completion state. It exposes no
+`record_completion` mutation, a self-authored result cannot satisfy
+`pull-request-opened`, and the projection waits instead of scheduling repeated
+adapter turns. The protocol remains the future provider contract. The local
+publish-change helper only renders and validates publish artifacts and provider
+checks; it is not the provider action executor.
+
+`flow_step_actions` must explicitly declare `artifacts`, `artifact_bindings`,
+`expectation_ids`, `expectation_bindings`, and `implementation_allowed`, including
+empty lists for terminal actions. Expectation ids must exactly equal the resolved
+Flow expectation set. Artifact bindings map each artifact to its owning
+expectations, allowing optional artifacts to remain declared without appearing
+under `stop_condition.required`. Operation bindings must resolve through the
+canonical public operation catalog, not merely a self-declared string. Artifact
+refs are either lexically safe session-relative paths or validated
+`trust.bundle#<safe-id>` virtual refs; absolute paths, traversal, and arbitrary
+fragments fail closed. Malformed,
+unknown-field, duplicate, oversized, unmatched, symlinked, or otherwise
+unbounded action metadata fails closed before an adapter is launched. The
+runtime verifies every named skill against the installed Builder package and
+binds its contents by SHA-256. Kit JSON, skill source, and artifact identity/hash
+reads open the final path once with `O_NOFOLLOW`, bound size from `fstat`, read
+through that descriptor, and recheck descriptor/path identity after the read.
+Run-wide artifact observation deduplicates refs and enforces count plus aggregate
+byte/hash budgets before reading file contents. Product validation and runtime
+both cap each action at 16 skills and each flow at 128 distinct observable file
+artifacts; virtual trust-bundle refs and control artifacts are excluded using the
+same classification in both layers.
+
+After every successful or failed adapter turn, Flow Agents synchronizes the
+canonical run and records a delta: step advancement, newly attached canonical
+evidence, changed hashes of declared artifacts (`artifact_changes`), or no
+progress. Evidence identities and the artifact manifest are run-wide rather
+than selected-step scoped, so the evidence/artifact that advances a gate remains
+attributable and files already present for later steps are part of the baseline.
+Control `state.json` is excluded from both request-facing declared/required
+artifacts and artifact progress. Legacy kit ownership metadata may retain it,
+but the envelope never instructs an adapter to produce Flow Agents control
+state or observes its own hash. Repeated
+no-progress deltas are classified as `possible` and then `stagnant`; they never
+invent evidence, auto-pass a gate, or change Flow state. A same-step evidence
+attachment is recorded as progress even though the legacy `gate_not_advanced`
+event remains for compatibility. Adapter-returned `evidence` remains optional
+adapter telemetry only and is never gate evidence.
+
+The durable `last_progress` snapshot is the recovery baseline. A durable active
+turn phase and pre-turn snapshot identify an adapter turn interrupted before its
+post-turn measurement. Reinvocation compares freshly synchronized canonical
+state with that snapshot, counts an unchanged started turn as no progress exactly
+once, records any delta, and clears the recovery marker. Synchronization and this
+reconciliation occur before waiting or terminal disposition handling, so the
+turn's audit and progress survive either outcome. Accepted turns, wait turns, and
+callback failures are likewise synchronized and measured before their durable
+turn marker is cleared. Signed workflow drives preflight the aggregate attestation
+capacity before launching an adapter when another bounded signed result cannot fit.
+Accepted request/result pairs and their measured progress are first stored in a
+durable idempotent journal while the active turn remains in `measured` phase.
+Only after journal and completion-event persistence does the driver clear that
+marker. Restart completes either write exactly once. Signed attestations reload
+the journal and fail closed if an accepted event lacks request/result coverage.
+The complete serialized turn result is capped at 74,000 bytes; signed preflight
+reserves that exact maximum in addition to the actual request and JSON structure.
+The authoritative envelope
+exists only at top-level in the turn request; projected `next_action` and durable
+`state.json` do not contain a duplicate.
+
+Canonical synchronization normally waits for attached bundle evidence before
+evaluating a gate. It may evaluate an evidence-free gate only when the run's
+effective config proves the gate can pass without new evidence: an accepted
+exception applies, or every effective expectation is optional. This advances
+those gates without prematurely evaluating ordinary missing-required gates, and
+once the run advances no obsolete action skill remains required.
+
+The envelope and its prior-turn delta are additive fields of
+`ContinuationTurnRequest` schema `1.0`; adapters that only consume the existing
+request fields remain compatible. When `workflow drive` produces its optional
+signed request/result attestation, the exact request object (including the
+envelope) is included in the signed payload without transformation.
 # Builder Lifecycle Authority
 
 The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may