@kontourai/flow-agents 3.11.0 → 3.12.1

package/dist/kiro/build/src/builder-flow-runtime.js

@@ -2,11 +2,11 @@ import * as fs from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { flowAgentsPackageVersion } from "./lib/package-version.js";
 import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
-import { expectationsForGate, lifecycleRequestMatches, openGates, } from "@kontourai/flow";
+import { deriveBuilderGateActionEnvelope, deriveBuilderGateActionProgressSnapshot } from "./builder-gate-action-envelope.js";
+import { evaluateGate, expectationsForGate, lifecycleRequestMatches, openGates, } from "@kontourai/flow";
 import { assertAuthorizationUnused, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
 import { assignmentFilePath, performLocalReleaseUnderLock, readLocalAssignmentStatus, resolveCurrentAssignmentActor, withSubjectLock } from "./cli/assignment-provider.js";
 import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, cancelBuilderFlowRun, evaluateBuilderFlowRun, loadBuilderFlowRun, pauseBuilderFlowRun, resumeBuilderFlowRun, startBuilderFlowRun, } from "./builder-flow-run-adapter.js";
@@ -61,13 +61,15 @@ export async function recoverBuilderFlowSession(input) {
         runId: context.slug,
     });
     assertRunSubjectBinding(run, subject);
-    const projection = projectFlowRun(context, run, sidecarSnapshot.state);
+    const { projection, gateActionEnvelope, progressSnapshot } = projectFlowRun(context, run, sidecarSnapshot.state);
     writeProjection(context, projection, sidecarSnapshot.raw, "recovery");
     return {
         sessionDir: context.sessionDir,
         projectRoot: context.projectRoot,
         run,
         projection,
+        gateActionEnvelope,
+        progressSnapshot,
         attached: false,
     };
 }
@@ -77,11 +79,14 @@ export async function inspectBuilderFlowSession(input) {
     const subject = workflowSubject(sidecarSnapshot.state);
     const run = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
     assertRunSubjectBinding(run, subject);
+    const { projection, gateActionEnvelope, progressSnapshot } = projectFlowRun(context, run, sidecarSnapshot.state);
     return {
         sessionDir: context.sessionDir,
         projectRoot: context.projectRoot,
         run,
-        projection: projectFlowRun(context, run, sidecarSnapshot.state),
+        projection,
+        gateActionEnvelope,
+        progressSnapshot,
         attached: false,
     };
 }
@@ -102,10 +107,10 @@ export async function cancelBuilderFlowSession(input) {
             reason: `canonical Flow run canceled by ${prepared.authorization.request.authority.request_ref}`,
             tolerateNoActiveClaim: true,
         });
-        const projection = projectFlowRun(prepared.context, changed, prepared.sidecarSnapshot.state);
+        const { projection, gateActionEnvelope, progressSnapshot } = projectFlowRun(prepared.context, changed, prepared.sidecarSnapshot.state);
         writeProjection(prepared.context, projection, prepared.sidecarSnapshot.raw, "cancellation projection");
         recordAuthorizationConsumed(prepared.context.artifactRoot, prepared.authorization);
-        return { sessionDir: prepared.context.sessionDir, projectRoot: prepared.context.projectRoot, run: changed, projection, attached: false, assignmentReleased: released !== null, idempotent: changed.idempotent };
+        return { sessionDir: prepared.context.sessionDir, projectRoot: prepared.context.projectRoot, run: changed, projection, gateActionEnvelope, progressSnapshot, attached: false, assignmentReleased: released !== null, idempotent: changed.idempotent };
     });
 }
 export async function releaseBuilderFlowAssignment(input) {
@@ -114,7 +119,8 @@ export async function releaseBuilderFlowAssignment(input) {
         const prepared = prepareAgentLifecycleChange(input, context);
         const run = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
         const released = performLocalReleaseUnderLock(context.artifactRoot, context.slug, prepared.actor, { actorKey: prepared.actorKey, reason: input.reason });
-        return { sessionDir: context.sessionDir, projectRoot: context.projectRoot, run, projection: prepared.sidecarSnapshot.state, attached: false, assignmentReleased: released !== null };
+        const { progressSnapshot } = projectFlowRun(context, run, prepared.sidecarSnapshot.state);
+        return { sessionDir: context.sessionDir, projectRoot: context.projectRoot, run, projection: prepared.sidecarSnapshot.state, gateActionEnvelope: null, progressSnapshot, attached: false, assignmentReleased: released !== null };
     });
 }
 export async function archiveBuilderFlowSession(input) {
@@ -151,12 +157,15 @@ export async function archiveBuilderFlowSession(input) {
             clearCurrentPointers(prepared.context.artifactRoot, prepared.context.slug);
             recordAuthorizationConsumed(prepared.context.artifactRoot, prepared.authorization);
         }
+        const { progressSnapshot } = projectFlowRun(prepared.context, run, prepared.sidecarSnapshot.state);
         fs.renameSync(prepared.context.sessionDir, archiveDir);
         return {
             sessionDir: archiveDir,
             projectRoot: prepared.context.projectRoot,
             run,
             projection: archivedState,
+            gateActionEnvelope: null,
+            progressSnapshot,
             attached: false,
             archiveDir,
         };
@@ -173,13 +182,15 @@ async function changeBuilderFlowSessionLifecycle(input, operation) {
             runId: context.slug,
             request: { reason: input.reason, authority: { kind: "operator_request", actor: prepared.actorKey, request_ref: `flow-agents://assignment/${context.slug}/${operation}/${at}`, requested_at: at } },
         });
-        const projection = projectFlowRun(context, run, prepared.sidecarSnapshot.state);
+        const { projection, gateActionEnvelope, progressSnapshot } = projectFlowRun(context, run, prepared.sidecarSnapshot.state);
         writeProjection(context, projection, prepared.sidecarSnapshot.raw, `${operation} projection`);
         return {
             sessionDir: context.sessionDir,
             projectRoot: context.projectRoot,
             run,
             projection,
+            gateActionEnvelope,
+            progressSnapshot,
             attached: false,
         };
     });
@@ -277,7 +288,7 @@ async function syncAndProject(context, initial, sidecarSnapshot) {
         const snapshot = stageTrustBundleSnapshot(context);
         try {
             const rawBundle = JSON.parse(snapshot.raw.toString("utf8"));
-            const gateEvidence = await bundleGateEvidence(rawBundle, gates[0], run.state, run.state.subject, context.projectRoot, manifestEvidence(run.manifest));
+            const gateEvidence = await bundleGateEvidence(rawBundle, gates[0], run.state, run.state.subject, context.projectRoot, manifestEvidence(run.manifest), run.config);
             if (gateEvidence) {
                 const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id
                     && entry.sha256 === snapshot.sha256
@@ -309,16 +320,28 @@ async function syncAndProject(context, initial, sidecarSnapshot) {
             removeTrustBundleSnapshot(snapshot);
         }
     }
-    const projection = projectFlowRun(context, run, sidecarSnapshot.state);
+    if (!attached && gates.length === 1 && gateCanPassWithoutNewEvidence(run, gates[0])) {
+        run = await evaluateBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
+    }
+    const { projection, gateActionEnvelope, progressSnapshot } = projectFlowRun(context, run, sidecarSnapshot.state);
     writeProjection(context, projection, sidecarSnapshot.raw, "projection");
     return {
         sessionDir: context.sessionDir,
         projectRoot: context.projectRoot,
         run,
         projection,
+        gateActionEnvelope,
+        progressSnapshot,
         attached,
     };
 }
+function gateCanPassWithoutNewEvidence(run, gate) {
+    const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
+    const expectations = expectationsForGate(gate, run.config);
+    const outcome = evaluateGate(definition, run.state, run.manifest, gate.id, run.config);
+    return outcome.status === "pass"
+        && (typeof outcome.accepted_exception_id === "string" || expectations.every((expectation) => !expectation.required));
+}
 function assertRunSubjectBinding(run, subject) {
     if (run.state.subject !== subject) {
         throw new BuilderBuildRunInputError("flow_run.state.subject", "must match the selected Work Item");
@@ -382,10 +405,10 @@ function persistedFlowId(state) {
 function openGatesForResult(run) {
     return openGates(JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8")), run.state);
 }
-async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, manifest) {
+async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, manifest, config) {
     if (!isRecord(bundle) || !Array.isArray(bundle.claims))
         return null;
-    const expectations = expectationsForGate(gate);
+    const expectations = expectationsForGate(gate, config);
     const visit = currentGateVisit(state, String(gate.step));
     const enteredAt = visit.enteredAt;
     const synchronizedAt = Date.now();
@@ -762,17 +785,32 @@ function projectFlowRun(context, run, sidecar) {
     const canceled = run.state.status === "canceled";
     const needsDecision = run.state.status === "needs_decision";
     const failed = run.state.status === "failed";
-    const action = complete || paused || canceled || needsDecision || failed ? { skills: [], operations: [] } : stepAction(run.definitionId, run.state.current_step);
-    if (!action) {
-        throw new BuilderBuildRunInputError("kit.flow_step_actions", `does not declare Builder step ${run.state.current_step}`);
-    }
-    const required = gates.flatMap((gate) => expectationsForGate(gate)
+    const progressSnapshot = deriveBuilderGateActionProgressSnapshot({
+        sessionDir: context.sessionDir,
+        projectRoot: context.projectRoot,
+        run,
+        definition: definition,
+    });
+    const envelope = complete || paused || canceled || needsDecision || failed
+        ? null
+        : deriveBuilderGateActionEnvelope({
+            sessionDir: context.sessionDir,
+            projectRoot: context.projectRoot,
+            run,
+            definition: definition,
+        });
+    const action = envelope ? {
+        skills: envelope.action.skills.map((skill) => skill.id),
+        operations: envelope.action.operations,
+    } : { skills: [], operations: [] };
+    const required = gates.flatMap((gate) => expectationsForGate(gate, run.config)
         .filter((expectation) => expectation.required)
         .map((expectation) => `${expectation.id} (${expectation.bundle_claim.claimType}/${expectation.bundle_claim.subjectType ?? "any"})`));
-    const skills = action?.skills ?? [];
-    const operations = action?.operations ?? [];
+    const skills = action.skills;
+    const operations = action.operations;
     const syncCommand = pinnedFlowAgentsCommand(flowAgentsPackageVersion(), ["workflow", "status", "--session-dir", `.kontourai/flow-agents/${context.slug}`, "--json"]);
     const routeBack = latestRouteBack(run.state);
+    const externalCapability = envelope?.stop_condition.external_capability;
     const skillText = skills.length ? `Activate ${skills.map((skill) => `\`${skill}\``).join(" then ")}.` : "No Builder skill is required.";
     const operationText = operations.length ? ` Perform ${operations.map((operation) => `\`${operation}\``).join(" then ")}.` : "";
     const gateText = gates.length
@@ -791,32 +829,40 @@ function projectFlowRun(context, run, sidecar) {
                     ? { status: "blocked", summary: "Canonical Flow requires an external decision before continuation." }
                     : failed
                         ? { status: "failed", summary: "Canonical Flow run failed; no continuation turn is allowed." }
-                        : {
-                            status: "continue",
-                            summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
-                            skills,
-                            operations,
-                            command: syncCommand,
-                        };
+                        : externalCapability
+                            ? {
+                                status: "blocked",
+                                summary: `Flow step \`${run.state.current_step}\` is waiting for external capability \`${externalCapability.capability}\`. Flow Agents has no authenticated executor and cannot record provider completion.`,
+                                skills,
+                                operations,
+                                external_capability: externalCapability,
+                            }
+                            : {
+                                status: "continue",
+                                summary: `Flow step \`${run.state.current_step}\`: ${skillText}${operationText} ${gateText}${routeText} Then synchronize the recorded evidence.`,
+                                skills,
+                                operations,
+                                command: syncCommand,
+                            };
     const phase = phaseForStep(definition.phase_map, run.state.current_step) ?? sidecar.phase;
-    return {
-        ...sidecar,
-        status: complete ? "delivered" : canceled ? "canceled" : failed ? "failed" : (paused || needsDecision) ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
-        phase: complete || canceled || failed ? "done" : phase,
-        updated_at: run.state.updated_at,
-        flow_run: {
-            run_id: run.runId,
-            definition_id: run.definitionId,
-            definition_version: run.definitionVersion,
-            status: run.state.status,
-            current_step: run.state.current_step,
-            run_ref: path.relative(context.projectRoot, run.dir),
-            open_gate_ids: gates.map((gate) => gate.id),
-            ...(typeof routeBack?.attempt === "number" ? { route_back_attempt: routeBack.attempt } : {}),
-            ...(typeof routeBack?.max_attempts === "number" ? { route_back_max_attempts: routeBack.max_attempts } : {}),
-        },
-        next_action: nextAction,
-    };
+    return { gateActionEnvelope: envelope, progressSnapshot, projection: {
+            ...sidecar,
+            status: complete ? "delivered" : canceled ? "canceled" : failed ? "failed" : (paused || needsDecision) ? "blocked" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+            phase: complete || canceled || failed ? "done" : phase,
+            updated_at: run.state.updated_at,
+            flow_run: {
+                run_id: run.runId,
+                definition_id: run.definitionId,
+                definition_version: run.definitionVersion,
+                status: run.state.status,
+                current_step: run.state.current_step,
+                run_ref: path.relative(context.projectRoot, run.dir),
+                open_gate_ids: gates.map((gate) => gate.id),
+                ...(typeof routeBack?.attempt === "number" ? { route_back_attempt: routeBack.attempt } : {}),
+                ...(typeof routeBack?.max_attempts === "number" ? { route_back_max_attempts: routeBack.max_attempts } : {}),
+            },
+            next_action: nextAction,
+        } };
 }
 function writeProjection(context, projection, expectedStateRaw, operation) {
     const prepared = prepareProjectionWrites(context, projection, expectedStateRaw, operation);
@@ -964,20 +1010,6 @@ function writeExistingFileNoFollow(file, content) {
         fs.closeSync(descriptor);
     }
 }
-function stepAction(flowId, stepId) {
-    const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot(), "kits", "builder", "kit.json"), "utf8"));
-    const actions = Array.isArray(manifest.flow_step_actions) ? manifest.flow_step_actions : [];
-    const action = actions.find((candidate) => isRecord(candidate)
-        && candidate.flow_id === flowId
-        && candidate.step_id === stepId);
-    if (!isRecord(action) || !Array.isArray(action.skills) || !action.skills.every((skill) => typeof skill === "string")) {
-        return null;
-    }
-    const operations = Array.isArray(action.operations) && action.operations.every((operation) => typeof operation === "string")
-        ? action.operations
-        : [];
-    return { skills: action.skills, operations };
-}
 function phaseForStep(phaseMap, stepId) {
     if (!isRecord(phaseMap))
         return stepId === "design-probe" ? "pickup" : null;
@@ -987,16 +1019,6 @@ function latestRouteBack(state) {
     const outcomes = Array.isArray(state.gate_outcomes) ? state.gate_outcomes : [];
     return [...outcomes].reverse().find((outcome) => isRecord(outcome) && outcome.status === "route-back") ?? null;
 }
-function packageRoot() {
-    let directory = path.dirname(fileURLToPath(import.meta.url));
-    while (!fs.existsSync(path.join(directory, "package.json"))) {
-        const parent = path.dirname(directory);
-        if (parent === directory)
-            throw new Error("unable to locate Flow Agents package root");
-        directory = parent;
-    }
-    return directory;
-}
 function isRunNotFound(error) {
     return isRecord(error) && (error.code === "flow.run_location.not_found"
         || (typeof error.message === "string" && error.message.includes("flow.run_location.not_found")));

package/dist/kiro/build/src/builder-gate-action-envelope.d.ts

@@ -0,0 +1,152 @@
+import { type FlowRunState } from "@kontourai/flow";
+import { PUBLIC_OPERATION_CONTRACTS } from "./cli/public-contracts.js";
+type AnyRecord = Record<string, unknown>;
+export type GateActionInterfaceParameter = {
+    name: string;
+    flag: string;
+    required: boolean;
+    allowed_values?: string[];
+    repeatable?: boolean;
+    required_when?: {
+        parameter: string;
+        equals: string;
+    };
+};
+export type GateActionWorkflowMutation = {
+    expectation_id: string;
+    interface: "workflow.evidence" | "workflow.critique";
+    package: {
+        name: "@kontourai/flow-agents";
+        version: string;
+    };
+    command: "flow-agents";
+    argv: string[];
+    parameters: GateActionInterfaceParameter[];
+};
+export type GateActionPublicMutation = GateActionWorkflowMutation | {
+    expectation_id: string;
+    interface: "operation";
+    operation: string;
+    protocol: (typeof PUBLIC_OPERATION_CONTRACTS)[keyof typeof PUBLIC_OPERATION_CONTRACTS];
+    completion: {
+        status: "external_verification_required";
+        executable_by_flow_agents: false;
+        gate_evidence_interface: null;
+    };
+};
+export type GateActionEnvelope = {
+    schema_version: "2.0";
+    flow: {
+        run_id: string;
+        definition_id: string;
+        definition_version: string;
+        status: string;
+        current_step: string;
+        gate_ids: string[];
+    };
+    gate: {
+        requirements: Array<{
+            id: string;
+            gate_id: string;
+            required: boolean;
+            description: string;
+            claim_type: string;
+            subject_type: string | null;
+            status: "satisfied" | "accepted_exception" | "unresolved";
+        }>;
+        unresolved_requirement_ids: string[];
+        accepted_exceptions: Array<{
+            gate_id: string;
+            exception_id: string;
+        }>;
+    };
+    action: {
+        skills: Array<{
+            id: string;
+            package: {
+                name: "@kontourai/flow-agents";
+                version: string;
+            };
+            /** Stable package-relative source path, bound to package version and SHA-256. */
+            path: string;
+            sha256: string;
+        }>;
+        operations: string[];
+        declared_artifacts: string[];
+        declared_evidence: string[];
+        implementation_allowed: boolean;
+    };
+    public_interfaces: {
+        status: {
+            command: string;
+        };
+        mutations: GateActionPublicMutation[];
+    };
+    stop_condition: {
+        kind: "one_turn";
+        scope: {
+            run_id: string;
+            current_step: string;
+            gate_ids: string[];
+            current_gate_only: true;
+        };
+        required: {
+            skill_ids: string[];
+            artifact_refs: string[];
+            unresolved_evidence_ids: string[];
+        };
+        sequence: ["activate_required_skills", "produce_declared_artifacts", "record_bound_evidence", "synchronize_canonical_flow", "return_adapter_result"];
+        after: "return_adapter_result";
+        synchronize_canonical_flow: true;
+        adapter_evidence_is_gate_evidence: false;
+        external_capability?: {
+            status: "waiting";
+            operation: string;
+            capability: string;
+            completion: "external_verification_required";
+        };
+    };
+    progress: {
+        canonical_evidence: string[];
+        observed_artifacts: string[];
+        prior_turn?: GateActionPriorProgress;
+    };
+};
+export type GateActionProgressSnapshot = Pick<GateActionEnvelope["progress"], "canonical_evidence" | "observed_artifacts"> & {
+    current_step: string;
+    /** Optional for compatibility with snapshots persisted before terminal status capture. */
+    canonical_status?: string;
+};
+export type GateActionPriorProgress = {
+    step_advanced: boolean;
+    evidence_added: string[];
+    artifact_changes: string[];
+    no_progress: boolean;
+    consecutive_no_progress: number;
+    stagnation: "none" | "possible" | "stagnant";
+};
+export type BuilderGateActionEnvelopeInput = {
+    sessionDir: string;
+    projectRoot: string;
+    run: {
+        runId: string;
+        definitionId: string;
+        definitionVersion: string;
+        state: FlowRunState;
+        manifest: AnyRecord;
+        config: AnyRecord;
+    };
+    definition: AnyRecord;
+};
+/** Derive bounded adapter context without trusting adapter telemetry. */
+export declare function deriveBuilderGateActionEnvelope(input: BuilderGateActionEnvelopeInput): GateActionEnvelope;
+/**
+ * Canonical progress is useful after a run becomes terminal, when no adapter
+ * action envelope may be emitted. Keep this deliberately separate from the
+ * request-only envelope so terminal snapshots cannot be mistaken for work.
+ */
+export declare function deriveBuilderGateActionProgressSnapshot(input: BuilderGateActionEnvelopeInput): GateActionProgressSnapshot;
+export declare function gateActionProgressSnapshot(envelope: GateActionEnvelope): GateActionProgressSnapshot;
+export declare function withGateActionPriorProgress(envelope: GateActionEnvelope, priorTurn: GateActionPriorProgress): GateActionEnvelope;
+export declare function observeBuilderArtifactsForProgress(sessionDir: string, artifacts: string[]): string[];
+export {};