@vaudience/aigentflow-flow-validator 0.23.0 → 0.25.0

package/dist/index.js

@@ -457,6 +457,7 @@ var aigentflow_spec_default = {
     "ai",
     "aiv",
     "async",
+    "atlas",
     "browser",
     "chart",
     "db",
@@ -986,6 +987,48 @@ var aigentflow_spec_default = {
       "utils/parse-date"
     ]
   },
+  atlasExecutor: {
+    scheme: "atlas",
+    providerAgent: "agent",
+    providerCapability: "capability",
+    agentResource: "run",
+    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
+    operationUnknown: {
+      code: "atlas_operation_unknown",
+      messageFormat: "step %s uses %s, which is not an Atlas operation. The providers are agent (resource run) and capability (resource: a capability reference).",
+      suggestion: "Use atlas://agent/run or atlas://capability/<capability-ref>."
+    },
+    agentMissing: {
+      code: "atlas_agent_missing",
+      messageFormat: "step %s runs an Atlas agent but query.agent is missing or empty.",
+      suggestion: "Set query.agent to the agent to run, written out as a literal such as @acme/reporter."
+    },
+    agentNotLiteral: {
+      code: "atlas_agent_not_literal",
+      messageFormat: "step %s computes query.agent from a template. The agent must be a fixed literal, never derived from input.",
+      suggestion: "Write the agent out as a literal such as @acme/reporter. Data may go into the prompt or the inputs instead."
+    },
+    capabilitiesNotLiteral: {
+      code: "atlas_capabilities_not_literal",
+      messageFormat: "step %s computes an entry of query.capabilities from a template. Capabilities must be fixed literals, never derived from input.",
+      suggestion: "Write each capability out as a literal. Data may go into the prompt or the inputs instead."
+    },
+    promptMissing: {
+      code: "atlas_prompt_missing",
+      messageFormat: "step %s runs an Atlas agent with neither query.prompt nor query.prompt_template.",
+      suggestion: "Set exactly one of query.prompt or query.prompt_template."
+    },
+    promptBoth: {
+      code: "atlas_prompt_both",
+      messageFormat: "step %s sets both query.prompt and query.prompt_template.",
+      suggestion: "Keep exactly one of query.prompt or query.prompt_template."
+    },
+    capabilityRefInvalid: {
+      code: "atlas_capability_ref_invalid",
+      messageFormat: "step %s uses atlas://capability/%s, which is not a valid capability reference.",
+      suggestion: "A capability reference starts with a letter or digit and continues with letters, digits and _ . : - up to 128 characters in all."
+    }
+  },
   flowDataReservedKeys: {
     code: "flow_data_key_reserved",
     fieldFormat: "data.%s",
@@ -2028,6 +2071,21 @@ var FUNCTION_OPERATIONS = {
   operations: new Set(aigentflow_spec_default.functionOperations.operations),
   sorted: aigentflow_spec_default.functionOperations.operations
 };
+var atlas = aigentflow_spec_default.atlasExecutor;
+var ATLAS_EXECUTOR = {
+  scheme: atlas.scheme,
+  providerAgent: atlas.providerAgent,
+  providerCapability: atlas.providerCapability,
+  agentResource: atlas.agentResource,
+  capabilityRefPattern: new RegExp(atlas.capabilityRefPattern),
+  operationUnknown: atlas.operationUnknown,
+  agentMissing: atlas.agentMissing,
+  agentNotLiteral: atlas.agentNotLiteral,
+  capabilitiesNotLiteral: atlas.capabilitiesNotLiteral,
+  promptMissing: atlas.promptMissing,
+  promptBoth: atlas.promptBoth,
+  capabilityRefInvalid: atlas.capabilityRefInvalid
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
@@ -2091,6 +2149,51 @@ function checkExecutor(executor, field, stepID, issues) {
   }
   checkFunctionOperation(executor, field, stepID, templated, issues);
 }
+function checkAtlasStep(executor, query, stepField, stepID, issues) {
+  if (executor.includes(TEMPLATE_ACTION_OPEN)) return;
+  const m = EXECUTOR_URL_PATTERN.exec(executor);
+  if (m === null || m[1] !== ATLAS_EXECUTOR.scheme) return;
+  const provider = m[2];
+  const resource = m[3];
+  const quoted = JSON.stringify(stepID);
+  const report = (rule, ...args) => {
+    let message = rule.messageFormat.replace("%s", () => quoted);
+    for (const a of args) message = message.replace("%s", () => a);
+    issues.error({
+      field: stepField,
+      message,
+      code: rule.code,
+      stepId: stepID,
+      suggestion: rule.suggestion
+    });
+  };
+  const q2 = isRecord(query) ? query : {};
+  if (provider === ATLAS_EXECUTOR.providerCapability) {
+    if (!ATLAS_EXECUTOR.capabilityRefPattern.test(resource)) {
+      report(ATLAS_EXECUTOR.capabilityRefInvalid, resource);
+    }
+  } else if (provider === ATLAS_EXECUTOR.providerAgent && resource === ATLAS_EXECUTOR.agentResource) {
+    const agent = q2.agent;
+    if (typeof agent !== "string" || agent === "") {
+      report(ATLAS_EXECUTOR.agentMissing);
+    } else if (agent.includes(TEMPLATE_ACTION_OPEN)) {
+      report(ATLAS_EXECUTOR.agentNotLiteral);
+    }
+    const prompt = q2.prompt;
+    const promptTemplate = q2.prompt_template;
+    const hasPrompt = prompt !== void 0 && prompt !== null && prompt !== "";
+    const hasTemplate = promptTemplate !== void 0 && promptTemplate !== null && promptTemplate !== "";
+    if (!hasPrompt && !hasTemplate) report(ATLAS_EXECUTOR.promptMissing);
+    else if (hasPrompt && hasTemplate) report(ATLAS_EXECUTOR.promptBoth);
+  } else {
+    report(ATLAS_EXECUTOR.operationUnknown, executor);
+    return;
+  }
+  const caps = q2.capabilities;
+  if (Array.isArray(caps) && caps.some((c) => typeof c === "string" && c.includes(TEMPLATE_ACTION_OPEN))) {
+    report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
+  }
+}
 function checkFunctionOperation(executor, field, stepID, templated, issues) {
   if (templated) return;
   const m = EXECUTOR_URL_PATTERN.exec(executor);
@@ -2115,6 +2218,7 @@ function validateExecutors(flow, issues) {
     const executor = issues.stringOf(step, "executor", `steps.${stepID}`);
     if (executor !== null && executor !== "") {
       checkExecutor(executor, `steps.${stepID}.executor`, stepID, issues);
+      checkAtlasStep(executor, step.query, `steps.${stepID}`, stepID, issues);
     }
     const loop = step.loop;
     if (isRecord(loop) && Array.isArray(loop.steps)) {
@@ -2131,6 +2235,7 @@ function validateExecutors(flow, issues) {
             `${stepID}.${subID}`,
             issues
           );
+          checkAtlasStep(subExecutor, subStep.query, subPath, `${stepID}.${subID}`, issues);
         }
       });
     }
@@ -2631,31 +2736,81 @@ function validateConnectivity(flow, issues) {
       });
     }
   }
-  const visited = /* @__PURE__ */ new Set();
-  const recStack = /* @__PURE__ */ new Set();
-  const hasCycle = (stepID) => {
-    if (recStack.has(stepID)) return true;
-    if (visited.has(stepID)) return false;
-    visited.add(stepID);
-    recStack.add(stepID);
-    const step = steps[stepID];
-    if (isRecord(step) && isRecord(step.next)) {
-      const next = step.next;
-      for (const target of cycleTargets(next, `steps.${stepID}.next`, issues)) {
-        if (hasCycle(target)) return true;
-      }
-    }
-    recStack.delete(stepID);
-    return false;
-  };
-  if (hasCycle(start)) {
+  if (cycleWithoutExit(steps, start, issues)) {
     issues.warn({
       field: "steps",
-      message: "Potential infinite loop detected in step flow",
+      message: "Potential infinite loop detected in step flow: a cycle of steps has no way out",
       code: "potential_infinite_loop",
-      suggestion: "Review your step transitions to ensure they eventually terminate"
+      suggestion: "Give one step in the cycle a `next.conditions` branch that leaves it (or end the flow there)"
+    });
+  }
+}
+function cycleEdges(step, stepID, issues) {
+  if (!isRecord(step) || !isRecord(step.next)) return [];
+  const next = step.next;
+  const nextPath = `steps.${stepID}.next`;
+  const out = [];
+  const def = issues.stringOf(next, "default", nextPath);
+  if (def !== null && def !== "") out.push(def);
+  if (Array.isArray(next.conditions)) {
+    next.conditions.forEach((cond, i) => {
+      if (!isRecord(cond)) return;
+      const goto = issues.stringOf(cond, "goto", `${nextPath}.conditions[${i}]`);
+      if (goto !== null && goto !== "") out.push(goto);
     });
   }
+  return out;
+}
+function stepLeavesCycle(steps, stepID, inCycle, issues) {
+  const step = steps[stepID];
+  if (!isRecord(step) || !isRecord(step.next)) return true;
+  const next = step.next;
+  if (next.parallel !== void 0 && next.parallel !== null) return true;
+  const def = issues.stringOf(next, "default", `steps.${stepID}.next`);
+  if (def === null || def === "") return true;
+  for (const target of cycleEdges(step, stepID, issues)) {
+    if (isMarker(target) || !inCycle.has(target)) return true;
+  }
+  return false;
+}
+function cycleWithoutExit(steps, start, issues) {
+  let index = 0;
+  const indices = /* @__PURE__ */ new Map();
+  const low = /* @__PURE__ */ new Map();
+  const onStack = /* @__PURE__ */ new Set();
+  const stack = [];
+  let found = false;
+  const strong = (id) => {
+    indices.set(id, index);
+    low.set(id, index);
+    index++;
+    stack.push(id);
+    onStack.add(id);
+    for (const target of cycleEdges(steps[id], id, issues)) {
+      if (isMarker(target) || !Object.prototype.hasOwnProperty.call(steps, target)) continue;
+      if (!indices.has(target)) {
+        strong(target);
+        low.set(id, Math.min(low.get(id), low.get(target)));
+      } else if (onStack.has(target)) {
+        low.set(id, Math.min(low.get(id), indices.get(target)));
+      }
+    }
+    if (low.get(id) !== indices.get(id)) return;
+    const component = [];
+    for (; ; ) {
+      const top = stack.pop();
+      onStack.delete(top);
+      component.push(top);
+      if (top === id) break;
+    }
+    const inCycle = new Set(component);
+    const cyclic = component.length > 1 || cycleEdges(steps[id], id, issues).includes(id);
+    if (!cyclic) return;
+    if (component.some((member) => stepLeavesCycle(steps, member, inCycle, issues))) return;
+    found = true;
+  };
+  if (Object.prototype.hasOwnProperty.call(steps, start)) strong(start);
+  return found;
 }
 
 // src/validators/nextLogic.ts