@kontourai/flow-agents 3.11.0 → 3.12.0

package/dist/codex/build/src/flow-kit/action-repository-validation.js

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import * as path from "node:path";
+import { sameStringSet } from "./action-metadata.js";
+const MAX_FLOW_DEFINITION_BYTES = 1_048_576;
+export function validateActionRepositoryMetadata(input) {
+    const errors = [];
+    validateDeclaredSkills(input.manifest, input.skillRoles, input.manifestPath, errors);
+    const flows = loadFlowMetadata(input.kitDir, input.manifest, input.manifestPath, errors);
+    const resolve = effectiveStepResolver(flows);
+    validateRoleReferences(input.skillRoles, flows, resolve, input.manifestPath, errors);
+    const owners = seedSkillOwners(input.skillRoles, resolve);
+    validateActions(input.actions, input.skillRoles, flows, resolve, owners, input.manifest, input.manifestPath, errors);
+    validateOwnerCardinality(flows, owners, input.manifestPath, errors);
+    return errors;
+}
+function validateDeclaredSkills(manifest, roles, manifestPath, errors) {
+    const declared = new Set(Array.isArray(manifest.skills) ? manifest.skills.flatMap((entry) => typeof entry === "object" && entry !== null && typeof entry.id === "string" ? [entry.id] : []) : []);
+    const bound = new Set(roles.map((entry) => entry.skill_id));
+    for (const id of declared)
+        if (!bound.has(id))
+            errors.push(`${manifestPath}: skill_roles is missing declared skill '${id}'`);
+    for (const id of bound)
+        if (!declared.has(id))
+            errors.push(`${manifestPath}: skill_roles references undeclared skill '${id}'`);
+}
+function loadFlowMetadata(kitDir, manifest, manifestPath, errors) {
+    const flows = new Map();
+    if (!Array.isArray(manifest.flows))
+        return 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 safe = readSafeFlowDefinition(kitDir, flow.path);
+        if (!safe.definition) {
+            errors.push(`${manifestPath}: flows '${flow.id}' ${safe.error}`);
+            continue;
+        }
+        const definition = safe.definition;
+        const steps = Array.isArray(definition.steps) ? definition.steps.filter(isRecord) : [];
+        const stepIds = new Set(steps.flatMap((step) => typeof step.id === "string" ? [step.id] : []));
+        const usesFlowByStep = new Map(steps.flatMap((step) => typeof step.id === "string" && typeof step.uses_flow === "string" ? [[step.id, step.uses_flow]] : []));
+        flows.set(flow.id, { steps: stepIds, usesFlowByStep, expectationsByStep: expectationsByStep(definition), exports: new Set(Array.isArray(definition.exports) ? definition.exports.filter((value) => typeof value === "string" && value.length > 0) : []) });
+    }
+    return flows;
+}
+function expectationsByStep(definition) {
+    const result = new Map();
+    if (!isRecord(definition.gates))
+        return result;
+    for (const gate of Object.values(definition.gates)) {
+        if (!isRecord(gate) || typeof gate.step !== "string" || !Array.isArray(gate.expects))
+            continue;
+        const expectations = result.get(gate.step) ?? new Map();
+        for (const value of gate.expects) {
+            if (!isRecord(value) || typeof value.id !== "string")
+                continue;
+            const exportKeys = new Set([value.id]);
+            if (isRecord(value.bundle_claim) && typeof value.bundle_claim.claimType === "string")
+                exportKeys.add(value.bundle_claim.claimType);
+            expectations.set(value.id, { id: value.id, exportKeys });
+        }
+        result.set(gate.step, expectations);
+    }
+    return result;
+}
+function effectiveStepResolver(flows) {
+    const resolve = (flowId, stepId, seen = new Set()) => {
+        const cycleKey = `${flowId}\0${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 = resolve(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;
+    };
+    return resolve;
+}
+function validateRoleReferences(roles, flows, resolve, manifestPath, errors) {
+    for (const row of roles) {
+        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 allowed = new Set(row.step_ids.flatMap((stepId) => [...(resolve(row.flow_id, stepId)?.expectations.keys() ?? [])]));
+        for (const expectationId of row.expectation_ids)
+            if (!allowed.has(expectationId))
+                errors.push(`${manifestPath}: skill_roles '${row.skill_id}' expectation '${expectationId}' is not owned by its bound step(s)`);
+    }
+}
+function seedSkillOwners(roles, resolve) {
+    const owners = new Map();
+    for (const row of roles) {
+        if (row.role !== "step" || !row.flow_id)
+            continue;
+        for (const stepId of row.step_ids) {
+            const effective = resolve(row.flow_id, stepId);
+            if (!effective)
+                continue;
+            for (const expectationId of row.expectation_ids)
+                if (effective.expectations.has(expectationId)) {
+                    const key = `${effective.sourceFlowId}\0${effective.stepId}\0${expectationId}`;
+                    owners.set(key, [...(owners.get(key) ?? []), `skill:${row.skill_id}`]);
+                }
+        }
+    }
+    return owners;
+}
+function validateActions(actions, roles, flows, resolve, owners, manifest, manifestPath, errors) {
+    const roleByShortId = new Map(roles.map((entry) => [entry.skill_id.replace(`${String(manifest.id)}.`, ""), entry]));
+    for (const action of actions) {
+        const flow = flows.get(action.flow_id);
+        if (!flow || !flow.steps.has(action.step_id)) {
+            errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' references an unknown flow step`);
+            continue;
+        }
+        const effective = resolve(action.flow_id, action.step_id);
+        if (!effective) {
+            errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' cannot resolve its composed Flow step`);
+            continue;
+        }
+        for (const id of action.expectation_ids)
+            if (!effective.expectations.has(id))
+                errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' operation expectation '${id}' is not owned by its resolved Flow step`);
+        if (!sameStringSet(action.expectation_ids, [...effective.expectations.keys()]))
+            errors.push(`${manifestPath}: flow_step_actions '${action.flow_id}/${action.step_id}' expectation_ids must exactly equal its resolved Flow expectation set`);
+        for (const skill of action.skills) {
+            const row = roleByShortId.get(skill);
+            if (!row || row.role !== "step" || !row.flow_id || !effective.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`);
+        }
+        for (const expectationId of effective.expectations.keys()) {
+            const binding = action.expectation_bindings.find((entry) => entry.expectation_id === expectationId);
+            if (binding?.interface !== "operation")
+                continue;
+            const key = `${effective.sourceFlowId}\0${effective.stepId}\0${expectationId}`;
+            owners.set(key, [...(owners.get(key) ?? []), `operation:${action.flow_id}/${action.step_id}`]);
+        }
+    }
+}
+function validateOwnerCardinality(flows, owners, manifestPath, errors) {
+    for (const [flowId, flow] of flows)
+        for (const [stepId, expectations] of flow.expectationsByStep)
+            for (const expectationId of expectations.keys()) {
+                const found = owners.get(`${flowId}\0${stepId}\0${expectationId}`) ?? [];
+                if (found.length !== 1)
+                    errors.push(`${manifestPath}: flow expectation '${flowId}/${stepId}/${expectationId}' must have exactly one producer owner; found ${found.length}`);
+            }
+}
+function readSafeFlowDefinition(kitDir, relativePath) {
+    const root = path.resolve(kitDir);
+    if (path.isAbsolute(relativePath))
+        return { error: "path must be relative" };
+    const lexical = path.resolve(root, relativePath);
+    if (lexical === root || !lexical.startsWith(`${root}${path.sep}`))
+        return { error: "path must stay inside the kit directory" };
+    let fd;
+    try {
+        const realRoot = fs.realpathSync(root);
+        const initial = lstatSafePath(realRoot, relativePath);
+        if (!initial.file || !initial.stat)
+            return { error: initial.error };
+        if (!initial.stat.isFile())
+            return { error: "path must reference a regular file" };
+        if (initial.stat.size > MAX_FLOW_DEFINITION_BYTES)
+            return { error: `file exceeds ${MAX_FLOW_DEFINITION_BYTES} bytes` };
+        if (typeof fs.constants.O_NOFOLLOW !== "number")
+            return { error: "O_NOFOLLOW is unavailable" };
+        fd = fs.openSync(initial.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile() || !sameIdentity(initial.stat, opened))
+            return { error: "flow definition identity changed while opening" };
+        const verified = lstatSafePath(realRoot, relativePath);
+        if (!verified.stat || !sameIdentity(opened, verified.stat))
+            return { error: "flow definition identity changed while opening" };
+        const bytes = Buffer.alloc(opened.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        const after = fs.fstatSync(fd);
+        if (offset !== opened.size || after.size !== opened.size || !sameIdentity(opened, after))
+            return { error: "file changed while being read" };
+        return { definition: JSON.parse(bytes.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 (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+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 sameIdentity(left, right) { return left.dev === right.dev && left.ino === right.ino; }
+function isRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/dist/codex/build/src/flow-kit/validate.d.ts

@@ -1,3 +1,5 @@
+export { isObservableBuilderArtifactRef, isSafeBuilderArtifactRef, parseKitFlowStepActions } from "./action-metadata.js";
+export type { KitFlowStepActionEntry, KitFlowStepArtifactBinding, KitFlowStepExpectationBinding } from "./action-metadata.js";
 export interface KitDependencyEntry {
     kit_id: string;
     reason?: string;
@@ -23,16 +25,6 @@ export interface KitHookInfluenceExpectationEntry {
     must_include_guidance: string[];
     must_include_actions: string[];
 }
-export interface KitFlowStepActionEntry {
-    flow_id: string;
-    step_id: string;
-    skills: string[];
-    operations: string[];
-    /** Gate expectations produced by this action's explicit operation(s). */
-    expectation_ids?: string[];
-    /** Durable artifacts produced by an operation-only action. */
-    artifacts: string[];
-}
 export type KitSkillRole = "entrypoint" | "profile" | "step" | "shared-primitive" | "extension";
 export interface KitSkillRoleEntry {
     skill_id: string;
@@ -69,10 +61,6 @@ export declare function parseKitHookInfluenceExpectations(manifest: Record<strin
     entries: KitHookInfluenceExpectationEntry[];
     errors: string[];
 };
-export declare function parseKitFlowStepActions(manifest: Record<string, unknown>, manifestPath: string): {
-    entries: KitFlowStepActionEntry[];
-    errors: string[];
-};
 export declare function parseKitSkillRoles(manifest: Record<string, unknown>, manifestPath: string): {
     entries: KitSkillRoleEntry[];
     errors: string[];