@kontourai/flow-agents 3.5.0 → 3.7.0

package/build/src/cli/builder-run.js

@@ -1,35 +1,72 @@
 import { flagString, parseArgs } from "../lib/args.js";
-import { recoverBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import { cancelBuilderFlowSession, archiveBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, } from "../builder-flow-runtime.js";
+const USAGE = "Usage: flow-agents builder-run <recover|pause|resume|cancel|release-assignment|archive> --session-dir <path> [--reason <text> | --authorization-file <path>]";
 export async function main(argv) {
     const parsed = parseArgs(argv);
     const action = parsed.positionals[0];
     const sessionDir = flagString(parsed.flags, "session-dir");
+    const authorizationFile = flagString(parsed.flags, "authorization-file");
+    const reason = flagString(parsed.flags, "reason");
     const validRecoveryArguments = parsed.positionals.length === 1
         && Object.keys(parsed.flags).length === 1
         && typeof parsed.flags["session-dir"] === "string";
     if (action === "recover" && !validRecoveryArguments) {
-        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+        console.error(USAGE);
         return 64;
     }
     if (!sessionDir) {
         console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
         return 64;
     }
-    if (action !== "start" && action !== "sync" && action !== "recover") {
-        console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+    if (!action || !["recover", "pause", "resume", "cancel", "release-assignment", "archive"].includes(action)) {
+        console.error(USAGE);
         return 64;
     }
-    const result = action === "start"
-        ? await startBuilderFlowSession({ sessionDir })
-        : action === "sync"
-            ? await syncBuilderFlowSession({ sessionDir })
-            : await recoverBuilderFlowSession({ sessionDir });
+    const agentLifecycle = action === "pause" || action === "resume" || action === "release-assignment";
+    const authorizedLifecycle = action === "cancel" || action === "archive";
+    const lifecycle = agentLifecycle || authorizedLifecycle;
+    const allowedLifecycleFlag = (name) => name === "session-dir" || (agentLifecycle ? name === "reason" : name === "authorization-file");
+    if (lifecycle && (parsed.positionals.length !== 1 || Object.keys(parsed.flags).some((name) => !allowedLifecycleFlag(name)))) {
+        console.error(USAGE);
+        return 64;
+    }
+    if (agentLifecycle && !reason) {
+        console.error(`builder-run ${action} requires --reason <text>`);
+        return 64;
+    }
+    if (authorizedLifecycle && !authorizationFile) {
+        console.error(`builder-run ${action} requires a signed --authorization-file <path>`);
+        return 64;
+    }
+    if (!lifecycle && (authorizationFile || reason)) {
+        console.error(USAGE);
+        return 64;
+    }
+    const result = action === "recover"
+        ? await recoverBuilderFlowSession({ sessionDir })
+        : action === "pause"
+            ? await pauseBuilderFlowSession({ sessionDir, reason: reason })
+            : action === "resume"
+                ? await resumeBuilderFlowSession({ sessionDir, reason: reason })
+                : action === "cancel"
+                    ? await cancelBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile })
+                    : action === "release-assignment"
+                        ? await releaseBuilderFlowAssignment({ sessionDir, reason: reason })
+                        : await archiveBuilderFlowSession({ sessionDir, authorizationFile: authorizationFile });
     console.log(JSON.stringify({
         run_id: result.run.runId,
         definition_id: result.run.definitionId,
         current_step: result.run.state.current_step,
         status: result.run.state.status,
         attached: result.attached,
+        ...(action === "cancel" ? {
+            assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+            idempotent: "idempotent" in result ? result.idempotent : false,
+        } : action === "release-assignment" ? {
+            assignment_released: "assignmentReleased" in result ? result.assignmentReleased : false,
+        } : action === "archive" ? {
+            archive_dir: "archiveDir" in result ? result.archiveDir : null,
+        } : {}),
         next_action: result.projection.next_action,
     }));
     return 0;

package/build/src/cli/workflow-artifact-cleanup-audit.js

@@ -255,6 +255,9 @@ function classifyWorkflow(slug, workflowPath) {
     if (status === "verified" && nextStatus === "done") {
         return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
     }
+    if (status === "canceled" && phase === "done") {
+        return { ...base, classification: "terminal_done", reasons: ["canceled workflow retains its artifacts without requiring delivery promotion"] };
+    }
     if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
         if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
             return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow reached phase done without a promotion claim; ${PROMOTE_REMEDY}`] };

package/build/src/cli/workflow-sidecar.d.ts

@@ -6,6 +6,7 @@ export declare const phases: string[];
 export declare const checkKinds: Set<string>;
 export declare const checkStatuses: Set<string>;
 export declare const verdicts: Set<string>;
+export declare const WORKFLOW_WRITER_CONTRACT_VERSION = "1.0";
 export declare function writeJson(file: string, payload: AnyObj): void;
 export declare function loadJson(file: string, fallback?: AnyObj): AnyObj;
 export declare function appendJsonl(file: string, payload: AnyObj): void;
@@ -173,10 +174,13 @@ export declare function reduceCaptureLogByCommand(commandLog: AnyObj[] | undefin
  * @param timestamp  ISO-8601 timestamp for createdAt / updatedAt / observedAt
  * @param checks     Normalized check objects (from record-evidence --check-json / --surface-trust-json)
  * @param criteria   Acceptance criteria objects (from acceptance.json .criteria array)
- * @param critiques  Critique objects (from critique.json .critiques array)
+ * @param critiques  Critique objects reconstructed from trust.bundle claims
  * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
  */
-export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string, actorKey?: string): Promise<AnyObj | null>;
+export declare function buildTrustBundle(slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], commandLog?: AnyObj[], flowAgentsDir?: string, actorKey?: string, exactFlowContext?: {
+    flowId: string;
+    stepId: string;
+}): Promise<AnyObj | null>;
 /**
  * Fail-open wrapper: builds (via Surface), validates, and writes a trust.bundle.
  * Accepts raw check/criterion/critique inputs directly (ADR 0010 Phase 4a).
@@ -190,13 +194,34 @@ export declare function buildTrustBundle(slug: string, timestamp: string, checks
  * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
  * @param critiques  Critique objects (same as buildTrustBundle)
  */
-export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], actorKey?: string): Promise<{
+export declare function writeTrustBundle(dir: string, slug: string, timestamp: string, checks: AnyObj[], criteria: AnyObj[], critiques: AnyObj[], actorKey?: string, exactFlowContext?: {
+    flowId: string;
+    stepId: string;
+}): Promise<{
     written: boolean;
     errors: string[];
 }>;
 export declare function sidecarBase(slug: string): AnyObj;
+export declare function currentWorkflowSessionDir(root: string): string | null;
 export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
 export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
+/** Validate test-evidence command shape without executing it. */
+type TestExecutionProof = {
+    kind: "local-process-exit";
+    runner: string;
+    static_test_units: number;
+};
+/**
+ * Produce evidence from the locally executed command and statically reviewable
+ * test units. Runner stdout is deliberately excluded: any executable can print
+ * a Vitest/Jest-looking success summary, but it cannot turn a non-test script
+ * into a supported test workflow or supply this locally-created proof.
+ */
+export declare function testExecutionProof(command: string, projectRoot: string, seenScripts?: Set<string>, packageScriptBody?: boolean): TestExecutionProof | null;
+/** Validate test-evidence command shape without executing it. */
+export declare function isMeaningfulTestCommand(command: string, projectRoot: string, seenScripts?: Set<string>, packageScriptBody?: boolean): boolean;
+export declare function observedExecutedTestCount(output: string): number;
+export declare function inferExecutedTestCount(command: string, projectRoot: string, output: string, seenScripts?: Set<string>): number;
 export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>): AnyObj;
 /**
  * Derive kit identity from a parsed trust.bundle by structurally reading the
@@ -622,3 +647,5 @@ export declare function buildGateInquiryRecords(bundle: BundleFile, blockSignal:
 export declare const LIVENESS_TERMINAL: Set<string>;
 export { buildClaimExplanation } from "./sidecar-claim-explain.js";
 export type { ClaimEvidenceItem, ClaimExplanation } from "./sidecar-claim-explain.js";
+export declare function mainFromPublicWorkflow(argv: string[]): Promise<number>;
+export declare function main(argv?: string[], authority?: symbol): Promise<number>;