@kontourai/flow-agents 3.3.0 → 3.4.0

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

@@ -0,0 +1,241 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { attachEvidence, evaluateRun, expectationsForGate, loadRun, normalizeTrustBundle, openGates, readJson, 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 class BuilderBuildRunInputError extends Error {
+    code = "BUILDER_BUILD_RUN_INVALID_INPUT";
+    field;
+    constructor(field, reason) {
+        super(`invalid Builder build run input for ${field}: ${reason}`);
+        this.name = "BuilderBuildRunInputError";
+        this.field = field;
+    }
+}
+export class BuilderBuildRunIdentityError extends Error {
+    code = "BUILDER_BUILD_RUN_IDENTITY_MISMATCH";
+    expectedDefinitionId;
+    expectedDefinitionVersion;
+    actualDefinitionId;
+    actualDefinitionVersion;
+    mismatch;
+    runId;
+    constructor(runId, expectedDefinition, actualDefinition, mismatch) {
+        super(`expected canonical ${expectedDefinition.id}@${expectedDefinition.version} run, received ${actualDefinition.id}@${actualDefinition.version} for ${runId}`);
+        this.name = "BuilderBuildRunIdentityError";
+        this.expectedDefinitionId = expectedDefinition.id;
+        this.expectedDefinitionVersion = expectedDefinition.version;
+        this.actualDefinitionId = actualDefinition.id;
+        this.actualDefinitionVersion = actualDefinition.version;
+        this.mismatch = mismatch;
+        this.runId = runId;
+    }
+}
+export function resolveBuilderBuildFlowDefinitionPath(startDir = moduleDirectory()) {
+    const root = findPackageRoot(startDir);
+    return path.join(root, BUILDER_BUILD_FLOW_RELATIVE_PATH);
+}
+export async function startBuilderBuildRun(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 started = await startRun(runtimeDefinitionPath, {
+        cwd,
+        runId: input.runId,
+        params: {
+            ...(input.params ?? {}),
+            subject: input.subject,
+        },
+    });
+    const run = await loadCanonicalBuilderBuildRun(started.runId, cwd, definition);
+    return resultFromRun(run, started.runId);
+}
+export async function evaluateBuilderBuildRun(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());
+    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)));
+        assertBundleSubjects(normalized.bundle, run.state.subject, openGates(run.definition, run.state)[0]);
+        attachedEvidence = [await attachEvidence(input.runId, trustBundleAttachOptions(cwd, evidence))];
+    }
+    const evaluated = await evaluateRun(input.runId, { cwd });
+    return {
+        definitionId: evaluated.definition.id,
+        definitionVersion: evaluated.definition.version,
+        runId: input.runId,
+        dir: evaluated.dir,
+        state: evaluated.state,
+        attachedEvidence,
+        outcomes: evaluated.outcomes,
+        manifest: evaluated.manifest,
+        freshnessTransitions: evaluated.freshness_transitions,
+    };
+}
+export async function loadBuilderBuildRun(input) {
+    assertRuntimeInput(input, ["evidence", "now", "gate"]);
+    const cwd = input.cwd ?? process.cwd();
+    const run = await loadRun(input.runId, cwd);
+    const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+    assertCanonicalDefinition(input.runId, definition, run.definition);
+    return resultFromRun(run, input.runId);
+}
+function resultFromRun(run, runId) {
+    return {
+        definitionId: run.definition.id,
+        definitionVersion: run.definition.version,
+        runId,
+        dir: run.dir,
+        state: run.state,
+        attachedEvidence: [],
+        outcomes: [],
+        manifest: run.manifest,
+        freshnessTransitions: [],
+    };
+}
+async function loadCanonicalBuilderBuildRun(runId, cwd, definition) {
+    const run = await loadRun(runId, cwd);
+    assertCanonicalDefinition(runId, definition, run.definition);
+    return run;
+}
+async function loadShippedBuilderBuildDefinition(definitionPath) {
+    const packageRoot = findPackageRoot(path.dirname(definitionPath));
+    const effective = resolveEffectiveFlowDefinition(BUILDER_BUILD_FLOW_ID, 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}`);
+    }
+    return definition;
+}
+function materializeRuntimeDefinition(cwd, 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`);
+    if (!existsSync(file))
+        writeFileSync(file, content);
+    return file;
+}
+function assertCanonicalDefinition(runId, expectedDefinition, actualDefinition) {
+    if (isDeepStrictEqual(actualDefinition, expectedDefinition))
+        return;
+    const mismatch = actualDefinition.id !== expectedDefinition.id
+        ? "definition-id"
+        : actualDefinition.version !== expectedDefinition.version
+            ? "definition-version"
+            : "definition-content";
+    throw new BuilderBuildRunIdentityError(runId, expectedDefinition, actualDefinition, mismatch);
+}
+function assertRuntimeInput(input, forbiddenFields) {
+    if (!isRecord(input)) {
+        throw new BuilderBuildRunInputError("input", "must be an object");
+    }
+    for (const field of forbiddenFields) {
+        if (field in input) {
+            throw new BuilderBuildRunInputError(field, "is not supported by this API");
+        }
+    }
+}
+function validateEvidenceInput(evidence) {
+    if (!isRecord(evidence)) {
+        throw new BuilderBuildRunInputError("evidence", "must be an object");
+    }
+    if (!isNonEmptyString(evidence.gate)) {
+        throw new BuilderBuildRunInputError("evidence.gate", "must be a non-empty string");
+    }
+    if (!isNonEmptyString(evidence.file)) {
+        throw new BuilderBuildRunInputError("evidence.file", "must be a non-empty string");
+    }
+    if (evidence.status !== undefined && evidence.status !== "passed" && evidence.status !== "failed") {
+        throw new BuilderBuildRunInputError("evidence.status", "must be passed or failed");
+    }
+    return evidence;
+}
+function assertCurrentOpenGate(definition, state, evidenceGate) {
+    const gates = openGates(definition, state);
+    if (gates.length !== 1) {
+        throw new BuilderBuildRunInputError("evidence.gate", "requires exactly one current open gate");
+    }
+    if (gates[0].id !== evidenceGate) {
+        throw new BuilderBuildRunInputError("evidence.gate", "must target the persisted current open gate");
+    }
+}
+function assertBundleSubjects(bundle, subject, gate) {
+    if (!isRecord(bundle) || !Array.isArray(bundle.claims)) {
+        throw new BuilderBuildRunInputError("evidence", "contains no normalized claims");
+    }
+    const selectors = expectationsForGate(gate).map((expectation) => expectation.bundle_claim);
+    const relevant = bundle.claims.filter((claim) => isRecord(claim)
+        && selectors.some((selector) => selector.claimType === claim.claimType
+            && (!selector.subjectType || selector.subjectType === claim.subjectType)));
+    if (relevant.length === 0) {
+        throw new BuilderBuildRunInputError("evidence.claims", "contains no claim matching the persisted current open gate");
+    }
+    for (const claim of relevant) {
+        const metadata = isRecord(claim.metadata) ? claim.metadata : null;
+        if (!metadata || metadata.workflow_subject_ref !== subject) {
+            throw new BuilderBuildRunInputError("evidence.claims.metadata.workflow_subject_ref", "must match the persisted run subject");
+        }
+    }
+}
+function trustBundleAttachOptions(cwd, evidence) {
+    return {
+        cwd,
+        gate: evidence.gate,
+        file: evidence.file,
+        kind: "trust.bundle",
+        bundle: true,
+        ...(evidence.status ? { status: evidence.status } : {}),
+        ...(evidence.producer ? { producer: evidence.producer } : {}),
+        ...(evidence.authorityTrace ? { authorityTrace: evidence.authorityTrace } : {}),
+        ...(evidence.routeReason ? { route_reason: evidence.routeReason } : {}),
+        ...(evidence.expectationIds ? { expectation_ids: evidence.expectationIds } : {}),
+        ...(evidence.supersede ? { supersede: evidence.supersede } : {}),
+        ...(evidence.classifier ? { classifier: evidence.classifier } : {}),
+        ...(evidence.diagnostics ? { diagnostics: evidence.diagnostics } : {}),
+        ...(evidence.analytics ? { analytics: evidence.analytics } : {}),
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function moduleDirectory() {
+    return path.dirname(fileURLToPath(import.meta.url));
+}
+function findPackageRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (existsSync(path.join(dir, "package.json")) && existsSync(path.join(dir, BUILDER_BUILD_FLOW_RELATIVE_PATH))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error(`unable to locate ${BUILDER_BUILD_FLOW_RELATIVE_PATH} from ${startDir}`);
+        }
+        dir = parent;
+    }
+}

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

@@ -0,0 +1,16 @@
+import { type BuilderBuildRunResult } from "./builder-flow-run-adapter.js";
+type AnyRecord = Record<string, any>;
+export interface BuilderFlowSessionInput {
+    sessionDir: string;
+}
+export interface BuilderFlowSessionResult {
+    sessionDir: string;
+    projectRoot: string;
+    run: BuilderBuildRunResult;
+    projection: AnyRecord;
+    attached: boolean;
+}
+export declare function startBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
+export declare function syncBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
+export declare function syncBuilderFlowSessionIfPresent(sessionDir: string): Promise<BuilderFlowSessionResult | null>;
+export {};

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

@@ -0,0 +1,290 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expectationsForGate, openGates, readJson, runDir, sha256File, } from "@kontourai/flow";
+import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, evaluateBuilderBuildRun, loadBuilderBuildRun, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
+export async function startBuilderFlowSession(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    const sidecarState = readSidecarState(context);
+    const subject = workflowSubject(sidecarState);
+    let run;
+    try {
+        run = await loadBuilderBuildRun({
+            cwd: context.projectRoot,
+            runId: context.slug,
+        });
+    }
+    catch (error) {
+        if (!isRunNotFound(error))
+            throw error;
+        run = await startBuilderBuildRun({
+            cwd: context.projectRoot,
+            runId: context.slug,
+            subject,
+            params: {
+                subject,
+            },
+        });
+    }
+    return syncAndProject(context, run);
+}
+export async function syncBuilderFlowSession(input) {
+    const context = resolveSessionContext(input.sessionDir);
+    const run = await loadBuilderBuildRun({
+        cwd: context.projectRoot,
+        runId: context.slug,
+    });
+    return syncAndProject(context, run);
+}
+export async function syncBuilderFlowSessionIfPresent(sessionDir) {
+    let context;
+    try {
+        context = resolveSessionContext(sessionDir);
+    }
+    catch (error) {
+        if (error instanceof BuilderBuildRunInputError && error.field === "sessionDir")
+            return null;
+        throw error;
+    }
+    if (!fs.existsSync(runDir(context.slug, context.projectRoot)))
+        return null;
+    return syncBuilderFlowSession({ sessionDir });
+}
+async function syncAndProject(context, initial) {
+    let run = initial;
+    let attached = false;
+    const gates = openGatesForResult(run);
+    if (run.state.status === "active" && gates.length !== 1) {
+        throw new BuilderBuildRunInputError("flow_run.open_gates", `expected exactly one gate for active step ${run.state.current_step}, found ${gates.length}`);
+    }
+    if (gates.length === 1 && fs.existsSync(context.bundleFile)) {
+        const rawBundle = await readJson(context.bundleFile);
+        const gateEvidence = bundleGateEvidence(rawBundle, gates[0], run.state.subject);
+        if (gateEvidence) {
+            const digest = await sha256File(context.bundleFile);
+            const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id && entry.sha256 === digest);
+            if (!alreadyAttached) {
+                run = await evaluateBuilderBuildRun({
+                    cwd: context.projectRoot,
+                    runId: context.slug,
+                    evidence: {
+                        gate: gates[0].id,
+                        file: path.relative(context.projectRoot, context.bundleFile),
+                        ...(gateEvidence.failed ? { status: "failed" } : {}),
+                        ...(gateEvidence.routeReason ? { routeReason: gateEvidence.routeReason } : {}),
+                    },
+                });
+                attached = true;
+            }
+        }
+    }
+    const projection = projectFlowRun(context, run);
+    writeProjection(context, projection);
+    return {
+        sessionDir: context.sessionDir,
+        projectRoot: context.projectRoot,
+        run,
+        projection,
+        attached,
+    };
+}
+function resolveSessionContext(sessionDirInput) {
+    const sessionDir = path.resolve(sessionDirInput);
+    const artifactRoot = path.dirname(sessionDir);
+    const kontouraiRoot = path.dirname(artifactRoot);
+    if (path.basename(artifactRoot) !== "flow-agents" || path.basename(kontouraiRoot) !== ".kontourai") {
+        throw new BuilderBuildRunInputError("sessionDir", "must be .kontourai/flow-agents/<slug>");
+    }
+    const slug = path.basename(sessionDir);
+    if (!slug || slug === "." || slug === "..") {
+        throw new BuilderBuildRunInputError("sessionDir", "must name a session");
+    }
+    const stateFile = path.join(sessionDir, "state.json");
+    if (!fs.existsSync(stateFile)) {
+        throw new BuilderBuildRunInputError("sessionDir", "must contain state.json");
+    }
+    return {
+        sessionDir,
+        artifactRoot,
+        projectRoot: path.dirname(kontouraiRoot),
+        slug,
+        stateFile,
+        bundleFile: path.join(sessionDir, "trust.bundle"),
+    };
+}
+function readSidecarState(context) {
+    const value = JSON.parse(fs.readFileSync(context.stateFile, "utf8"));
+    if (!isRecord(value) || value.task_slug !== context.slug) {
+        throw new BuilderBuildRunInputError("sessionDir", "state.json task_slug must match the session directory");
+    }
+    return value;
+}
+function workflowSubject(state) {
+    const refs = Array.isArray(state.work_item_refs)
+        ? state.work_item_refs.filter((value) => typeof value === "string" && value.length > 0)
+        : [];
+    if (refs.length !== 1) {
+        throw new BuilderBuildRunInputError("state.work_item_refs", "must contain exactly one selected Work Item for builder.build");
+    }
+    return refs[0];
+}
+function openGatesForResult(run) {
+    return openGates(JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8")), run.state);
+}
+function bundleGateEvidence(bundle, gate, subject) {
+    if (!isRecord(bundle) || !Array.isArray(bundle.claims))
+        return null;
+    const selectors = expectationsForGate(gate).map((expectation) => expectation.bundle_claim);
+    const relevant = bundle.claims.filter((claim) => {
+        if (!isRecord(claim))
+            return false;
+        return selectors.some((candidate) => candidate.claimType === claim.claimType
+            && (!candidate.subjectType || candidate.subjectType === claim.subjectType));
+    });
+    if (relevant.length === 0)
+        return null;
+    if (relevant.some((claim) => workflowSubjectRef(claim) !== subject)) {
+        throw new BuilderBuildRunInputError("evidence.claims.metadata.workflow_subject_ref", "must match the persisted run subject");
+    }
+    const failed = relevant.some((claim) => claim.value === "fail" || claim.status === "disputed");
+    const routeReasons = [...new Set(relevant.flatMap((claim) => {
+            const metadata = isRecord(claim.metadata) ? claim.metadata : null;
+            const gateClaim = metadata && isRecord(metadata.gate_claim) ? metadata.gate_claim : null;
+            return gateClaim && typeof gateClaim.route_reason === "string" ? [gateClaim.route_reason] : [];
+        }))];
+    if (routeReasons.length > 1) {
+        throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "must agree across current-gate claims");
+    }
+    const routeReason = routeReasons[0] ?? null;
+    if (routeReason && !failed) {
+        throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "requires failed current-gate evidence");
+    }
+    const routeMap = isRecord(gate.on_route_back) ? gate.on_route_back : null;
+    if (routeReason && (!routeMap || typeof routeMap[routeReason] !== "string")) {
+        throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", `is not declared by gate ${String(gate.id ?? "<unknown>")}`);
+    }
+    return { failed, routeReason };
+}
+function workflowSubjectRef(claim) {
+    const metadata = isRecord(claim.metadata) ? claim.metadata : null;
+    return metadata && typeof metadata.workflow_subject_ref === "string"
+        ? metadata.workflow_subject_ref
+        : null;
+}
+function manifestEvidence(manifest) {
+    return Array.isArray(manifest.evidence) ? manifest.evidence.filter(isRecord) : [];
+}
+function projectFlowRun(context, run) {
+    const sidecar = readSidecarState(context);
+    const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
+    const gates = openGates(definition, run.state);
+    const complete = run.state.status === "completed";
+    const action = complete ? { skills: [], operations: [] } : stepAction(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)
+        .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 syncCommand = `flow-agents builder-run sync --session-dir .kontourai/flow-agents/${context.slug}`;
+    const routeBack = latestRouteBack(run.state);
+    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
+        ? `Complete ${gates.map((gate) => `\`${gate.id}\``).join(", ")} by recording: ${required.join(", ") || "its declared evidence"}.`
+        : "No Flow gate is open.";
+    const routeText = routeBack
+        ? ` Route-back history: attempt ${routeBack.attempt ?? "n/a"}${routeBack.max_attempts ? `/${routeBack.max_attempts}` : ""} returned to \`${routeBack.route_back_to ?? "an earlier step"}\`${routeBack.route_reason ? ` for \`${routeBack.route_reason}\`` : ""}.`
+        : "";
+    const nextAction = complete
+        ? { status: "done", summary: "Canonical Flow run is complete." }
+        : {
+            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" : (run.state.transitions.length > 0 ? "in_progress" : sidecar.status),
+        phase: complete ? "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) {
+    fs.writeFileSync(context.stateFile, `${JSON.stringify(projection, null, 2)}\n`);
+    const pointerFiles = [path.join(context.artifactRoot, "current.json")];
+    const actorRoot = path.join(context.artifactRoot, "current");
+    if (fs.existsSync(actorRoot)) {
+        pointerFiles.push(...fs.readdirSync(actorRoot)
+            .filter((name) => name.endsWith(".json"))
+            .map((name) => path.join(actorRoot, name)));
+    }
+    for (const file of pointerFiles) {
+        if (!fs.existsSync(file))
+            continue;
+        const pointer = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!isRecord(pointer) || pointer.active_slug !== context.slug)
+            continue;
+        pointer.active_flow_id = BUILDER_BUILD_FLOW_ID;
+        pointer.active_step_id = projection.flow_run.current_step;
+        pointer.updated_at = projection.updated_at;
+        fs.writeFileSync(file, `${JSON.stringify(pointer, null, 2)}\n`);
+    }
+}
+function stepAction(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 === BUILDER_BUILD_FLOW_ID
+        && 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;
+    return Object.entries(phaseMap).find(([, step]) => step === stepId)?.[0] ?? (stepId === "design-probe" ? "pickup" : null);
+}
+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")));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/build/src/cli/builder-run.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

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

@@ -0,0 +1,27 @@
+import { flagString, parseArgs } from "../lib/args.js";
+import { startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+export async function main(argv) {
+    const parsed = parseArgs(argv);
+    const action = parsed.positionals[0];
+    const sessionDir = flagString(parsed.flags, "session-dir");
+    if (!sessionDir) {
+        console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
+        return 64;
+    }
+    if (action !== "start" && action !== "sync") {
+        console.error("Usage: flow-agents builder-run <start|sync> --session-dir <path>");
+        return 64;
+    }
+    const result = action === "start"
+        ? await startBuilderFlowSession({ sessionDir })
+        : await syncBuilderFlowSession({ sessionDir });
+    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,
+        next_action: result.projection.next_action,
+    }));
+    return 0;
+}