@vaudience/aigentflow-flow-validator 0.24.0 → 0.25.0

package/PARITY.md

@@ -6,6 +6,29 @@ discipline for keeping the two in sync.
 
 **Tracks AIgentFlow flow schema: `v2.831.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which adds the rule `unknown_function_operation` and a clearer `unknown_executor_scheme` message (package 0.23.0, below). Earlier: the rule `flow_data_key_reserved` (package 0.22.0). Earlier: the `here` executor scheme, the `strict_templates` flow key and the rule `template_default_piped` (package 0.21.0). Earlier: the warning `compliance_residency_unenforced` (package 0.20.0). `orchestrator.region` / `orchestrator.enforce_region` (package 0.19.0). Earlier: the AigentChat executor was removed (package 0.18.0). Earlier additions: the `examples:` block (package 0.17.0), `server_owned_query_key` (package 0.15.1) from the AIgentFlow release after v2.790.0, `credential_endpoint_unpaired` (package 0.15.2) from AIgentFlow v2.793.0 and the release after it, and `display_name_too_long` (package 0.15.3) from AIgentFlow v2.802.0.
 
+> package 0.25.0 — **the `atlas://` executor scheme and seven rules**. `atlas` becomes a known
+> scheme (no `unknown_executor_scheme` warning). The URL form is `atlas://<provider>/<resource>`:
+> provider `agent` has the single resource `run`, provider `capability` takes a capability reference
+> as its resource. Seven new **errors**, all with the step as `field` (a loop sub-step reports its
+> sub-step path and the composite `parent.child` step id):
+> `atlas_operation_unknown` (any other provider, or `agent` with a resource other than `run`);
+> `atlas_agent_missing` (an agent run whose `query.agent` is absent, empty or not a string);
+> `atlas_agent_not_literal` (`query.agent` contains `{{`: the agent is always written out, never
+> computed from input); `atlas_capabilities_not_literal` (a string entry of `query.capabilities`
+> contains `{{`); `atlas_prompt_missing` and `atlas_prompt_both` (an agent run takes exactly one of
+> `query.prompt` and `query.prompt_template`; an empty string counts as absent);
+> `atlas_capability_ref_invalid` (the reference fails `^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$`).
+> Templates in `prompt`, in `inputs` values and in a capability's `args` are fine. A templated
+> executor is skipped, an unparsable URL stays `invalid_executor_url`'s, and the scheme match is
+> exact (`ATLAS://` is a known scheme but gets none of these rules). The shape check runs first, so
+> a reference containing a character outside letters, digits, `_`, `-` and `/` (for example a dot
+> or colon) is reported as `invalid_executor_url` and never reaches the reference pattern.
+> `specVersion` is unchanged (`2.831.0`). Module: `validators/executors.ts`; spec block
+> `atlasExecutor`. Gates: thirteen `invalid-atlas-*` / `valid-atlas-*` fixtures (the valid ones
+> forbid every atlas code and `unknown_executor_scheme`), shared byte for byte with the Go port, and
+> `test/v0250-atlas-executor.test.ts`. On the 227 bundled example flows both ports report no new
+> findings.
+
 > package 0.24.0 — **`potential_infinite_loop` fires only on a cycle with no way out**, in step
 > with the reference. It used to fire on every cycle reachable from the start step, so a deliberate
 > ask-again loop (a step that routes back until a condition sends it onward) carried a warning that

package/dist/cli.js

@@ -463,6 +463,7 @@ var aigentflow_spec_default = {
     "ai",
     "aiv",
     "async",
+    "atlas",
     "browser",
     "chart",
     "db",
@@ -1006,6 +1007,49 @@ var aigentflow_spec_default = {
       "utils/parse-date"
     ]
   },
+  atlasExecutor: {
+    $comment: "atlas://<provider>/<resource>: calls into the Atlas platform. Providers are agent (the one resource is run) and capability (the resource is a capability reference). All findings are ERRORS, field = the step (loop sub-steps use the composite step id and the sub-step path). Templated executors, unparsable URLs and other schemes are skipped. A literal agent and literal capabilities keep a step from being steered by data: query.agent and every string in query.capabilities may not contain templateActionOpen, while prompt, inputs and capability args may. A message format takes the quoted step id first.",
+    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: {
     $comment: "flow_data_key_reserved (ERROR, no loop demotion): a key of the top-level data: map that names engine state. data: is seeded into the mission's .data namespace, where the engine keeps its own bookkeeping, so a flow declaring such a key would forge it. Matching is exact and case-sensitive. A key is reserved when it is one of exact (each with its reason), or starts with one of prefixes (checked in order, first wins; each with its reason). The finding's field is fieldFormat with the key; the message is messageFormat with the key (JSON-quoted, as Go's %q) then the reason; the suggestion is verbatim. Findings are sorted by key. Reference: FlowDataKeyReservation, validateFlowDataKeysAreNotReserved (aigentflow#247 review).",
     code: "flow_data_key_reserved",
@@ -2129,6 +2173,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 = "://";
@@ -2192,6 +2251,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);
@@ -2216,6 +2320,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)) {
@@ -2232,6 +2337,7 @@ function validateExecutors(flow, issues) {
             `${stepID}.${subID}`,
             issues
           );
+          checkAtlasStep(subExecutor, subStep.query, subPath, `${stepID}.${subID}`, issues);
         }
       });
     }

package/dist/index.cjs

@@ -459,6 +459,7 @@ var aigentflow_spec_default = {
     "ai",
     "aiv",
     "async",
+    "atlas",
     "browser",
     "chart",
     "db",
@@ -988,6 +989,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",
@@ -2030,6 +2073,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 = "://";
@@ -2093,6 +2151,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);
@@ -2117,6 +2220,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)) {
@@ -2133,6 +2237,7 @@ function validateExecutors(flow, issues) {
             `${stepID}.${subID}`,
             issues
           );
+          checkAtlasStep(subExecutor, subStep.query, subPath, `${stepID}.${subID}`, issues);
         }
       });
     }