@vaudience/aigentflow-flow-validator 0.24.0 → 0.26.0

package/dist/index.cjs

@@ -459,6 +459,7 @@ var aigentflow_spec_default = {
     "ai",
     "aiv",
     "async",
+    "atlas",
     "browser",
     "chart",
     "db",
@@ -988,6 +989,85 @@ 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, empty or not a string.",
+      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."
+    },
+    modelNotLiteral: {
+      code: "atlas_model_not_literal",
+      messageFormat: "step %s computes a value of query.model from a template. The provider, model and reasoning_effort must be fixed literals, never derived from input.",
+      suggestion: "Write the model choice out as literals. Data may go into the prompt or the inputs instead."
+    },
+    paramRefused: {
+      code: "atlas_param_refused",
+      messageFormat: "step %s sets %s under query. Atlas decides these itself, so a step may not set them.",
+      suggestion: "Remove these keys from the query.",
+      agentKeys: [
+        "api_key",
+        "attribution",
+        "base_url",
+        "host",
+        "idempotency_key",
+        "org_id",
+        "person",
+        "untrusted_input",
+        "untrusted_input_override",
+        "url",
+        "user_id"
+      ],
+      capabilityKeys: [
+        "attribution",
+        "idempotency_key",
+        "untrusted_input",
+        "untrusted_input_override"
+      ]
+    }
+  },
+  reservedInputNames: {
+    prefix: "__",
+    code: "reserved_input_name",
+    messageFormat: "the input %s starts with two underscores. That namespace belongs to the platform (the acting person, the credential manifest, the untrusted-input marker): a flow cannot declare an input there, and a value or default written under such a name is never delivered.",
+    suggestion: 'Rename the input so it does not start with "__".',
+    queryFieldFormat: "query.%s",
+    schemaFieldFormat: "input_schema.fields.%s"
+  },
   flowDataReservedKeys: {
     code: "flow_data_key_reserved",
     fieldFormat: "data.%s",
@@ -2030,6 +2110,37 @@ 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,
+  modelNotLiteral: atlas.modelNotLiteral,
+  paramRefused: {
+    code: atlas.paramRefused.code,
+    messageFormat: atlas.paramRefused.messageFormat,
+    suggestion: atlas.paramRefused.suggestion,
+    agentKeys: atlas.paramRefused.agentKeys,
+    capabilityKeys: atlas.paramRefused.capabilityKeys
+  }
+};
+var RESERVED_INPUT_NAMES = {
+  prefix: aigentflow_spec_default.reservedInputNames.prefix,
+  code: aigentflow_spec_default.reservedInputNames.code,
+  messageFormat: aigentflow_spec_default.reservedInputNames.messageFormat,
+  suggestion: aigentflow_spec_default.reservedInputNames.suggestion,
+  queryFieldFormat: aigentflow_spec_default.reservedInputNames.queryFieldFormat,
+  schemaFieldFormat: aigentflow_spec_default.reservedInputNames.schemaFieldFormat
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
@@ -2093,6 +2204,63 @@ 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 prefix = `${ATLAS_EXECUTOR.scheme}://`;
+  if (!executor.startsWith(prefix)) return;
+  const rest = executor.slice(prefix.length);
+  const slash = rest.indexOf("/");
+  const provider = slash < 0 ? rest : rest.slice(0, slash);
+  const resource = slash < 0 ? "" : rest.slice(slash + 1);
+  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 : {};
+  let refusedKeys = ATLAS_EXECUTOR.paramRefused.capabilityKeys;
+  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) {
+    refusedKeys = ATLAS_EXECUTOR.paramRefused.agentKeys;
+    const agent = q2.agent;
+    if (typeof agent !== "string" || agent.trim() === "") {
+      report(ATLAS_EXECUTOR.agentMissing);
+    } else if (agent.includes(TEMPLATE_ACTION_OPEN)) {
+      report(ATLAS_EXECUTOR.agentNotLiteral);
+    }
+    const hasPrompt = atlasTextPresent(q2.prompt);
+    const hasTemplate = atlasTextPresent(q2.prompt_template);
+    if (!hasPrompt && !hasTemplate) report(ATLAS_EXECUTOR.promptMissing);
+    else if (hasPrompt && hasTemplate) report(ATLAS_EXECUTOR.promptBoth);
+    if (anyTemplate(q2.model)) report(ATLAS_EXECUTOR.modelNotLiteral);
+  } else {
+    report(ATLAS_EXECUTOR.operationUnknown, executor);
+    return;
+  }
+  if (anyTemplate(q2.capabilities)) report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
+  const refused = refusedKeys.filter((key) => Object.prototype.hasOwnProperty.call(q2, key)).sort();
+  if (refused.length > 0) report(ATLAS_EXECUTOR.paramRefused, refused.join(", "));
+}
+function anyTemplate(v) {
+  if (typeof v === "string") return v.includes(TEMPLATE_ACTION_OPEN);
+  if (Array.isArray(v)) return v.some(anyTemplate);
+  if (isRecord(v)) return Object.values(v).some(anyTemplate);
+  return false;
+}
+function atlasTextPresent(v) {
+  if (v === void 0 || v === null) return false;
+  return typeof v !== "string" || v.trim() !== "";
+}
 function checkFunctionOperation(executor, field, stepID, templated, issues) {
   if (templated) return;
   const m = EXECUTOR_URL_PATTERN.exec(executor);
@@ -2117,6 +2285,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 +2302,7 @@ function validateExecutors(flow, issues) {
             `${stepID}.${subID}`,
             issues
           );
+          checkAtlasStep(subExecutor, subStep.query, subPath, `${stepID}.${subID}`, issues);
         }
       });
     }
@@ -3775,6 +3945,37 @@ function validateInputSchema(flow, issues) {
   validateSchemaDefinition(flow.input_schema, "input_schema", issues);
 }
 
+// src/validators/reservedInputs.ts
+function formatField(format, name) {
+  return format.replace("%s", () => name);
+}
+function validateReservedInputNames(flow, issues) {
+  const rule = RESERVED_INPUT_NAMES;
+  const report = (name, fieldFormat) => {
+    issues.error({
+      field: formatField(fieldFormat, name),
+      message: rule.messageFormat.replace("%s", () => JSON.stringify(name)),
+      code: rule.code,
+      suggestion: rule.suggestion
+    });
+  };
+  const query = flow.query;
+  if (isRecord(query)) {
+    for (const name of Object.keys(query).sort()) {
+      if (name.startsWith(rule.prefix)) report(name, rule.queryFieldFormat);
+    }
+  }
+  const schema = flow.input_schema;
+  const fields = isRecord(schema) ? schema.fields : void 0;
+  if (!Array.isArray(fields)) return;
+  for (const f of fields) {
+    if (!isRecord(f)) continue;
+    if (typeof f.name === "string" && f.name.startsWith(rule.prefix)) {
+      report(f.name, rule.schemaFieldFormat);
+    }
+  }
+}
+
 // src/validators/outputSchema.ts
 function validateOutputSchemas(flow, issues) {
   const steps = flow.steps;
@@ -4889,7 +5090,7 @@ var CODE2 = "server_owned_query_key";
 var KEY_QUERY = "query";
 var KEY_ID = "id";
 var SERVER_OWNED = new Set(SERVER_OWNED_QUERY_KEYS.keys);
-function formatField(format, ...args) {
+function formatField2(format, ...args) {
   let i = 0;
   return format.replace(/%s/g, () => args[i++] ?? "");
 }
@@ -4907,7 +5108,7 @@ function validateServerOwnedQueryKeys(flow, issues) {
           issues,
           stepID,
           key,
-          formatField(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
+          formatField2(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
         );
       }
     }
@@ -4921,7 +5122,7 @@ function validateServerOwnedQueryKeys(flow, issues) {
           issues,
           stepID,
           key,
-          formatField(SERVER_OWNED_QUERY_KEYS.loopStepFieldFormat, stepID, subID, key)
+          formatField2(SERVER_OWNED_QUERY_KEYS.loopStepFieldFormat, stepID, subID, key)
         );
       }
     }
@@ -5188,7 +5389,7 @@ function own(m, key) {
   if (!isRecord(m) || !Object.prototype.hasOwnProperty.call(m, key)) return void 0;
   return m[key];
 }
-function formatField2(format, ...args) {
+function formatField3(format, ...args) {
   let i = 0;
   return format.replace(/%s/g, () => args[i++] ?? "");
 }
@@ -5210,14 +5411,14 @@ function credentialEndpointSteps(flow, issues) {
     out.push({
       executor: issues.stringOf(step, KEY_EXECUTOR, `steps.${stepId}`) ?? "",
       query: own(step, KEY_QUERY2),
-      field: (key) => formatField2(CREDENTIAL_ENDPOINT_PAIRING.stepFieldFormat, stepId, key)
+      field: (key) => formatField3(CREDENTIAL_ENDPOINT_PAIRING.stepFieldFormat, stepId, key)
     });
     for (const sub of loopSubStepsOfStep(stepId, step)) {
       const subId = issues.stringOf(sub.raw, KEY_ID2, sub.basePath) ?? "";
       out.push({
         executor: issues.stringOf(sub.raw, KEY_EXECUTOR, sub.basePath) ?? "",
         query: own(sub.raw, KEY_QUERY2),
-        field: (key) => formatField2(CREDENTIAL_ENDPOINT_PAIRING.loopStepFieldFormat, stepId, subId, key)
+        field: (key) => formatField3(CREDENTIAL_ENDPOINT_PAIRING.loopStepFieldFormat, stepId, subId, key)
       });
     }
   }
@@ -5281,7 +5482,7 @@ function validateAI(flow, steps, issues) {
     if ((stepsUsing.get(provider) ?? 0) > 0 && (stepsWithoutOwnKey.get(provider) ?? 0) === 0) {
       continue;
     }
-    warnStoredShape(issues, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, provider), provider);
+    warnStoredShape(issues, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, provider), provider);
   }
 }
 function warnStoredShape(issues, field, provider) {
@@ -5328,7 +5529,7 @@ function familySecret(flow, family, step, issues) {
     if (apiKey !== "" && listHas(family.secretParams, family.configApiKeyParam)) {
       return {
         envName: serverEnvRef(family, apiKey),
-        field: formatField2(
+        field: formatField3(
           CREDENTIAL_ENDPOINT_PAIRING.executorConfigKeyFieldFormat,
           configKey,
           CREDENTIAL_ENDPOINT_PAIRING.executorConfigApiKeyField
@@ -5341,7 +5542,7 @@ function familySecret(flow, family, step, issues) {
       if (v !== null) {
         return {
           envName: serverEnvRef(family, v),
-          field: formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key)
+          field: formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key)
         };
       }
     }
@@ -5367,13 +5568,13 @@ function familyAuthorEndpoint(flow, family, step, issues) {
     if (inst === null) continue;
     const baseUrl = configStringField(inst, configKey, CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlField, issues);
     if (baseUrl !== "" && listHas(family.endpointParams, family.configBaseUrlParam)) {
-      return decide(baseUrl, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, configKey));
+      return decide(baseUrl, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigBaseUrlFieldFormat, configKey));
     }
     const extra = own(inst, EXECUTOR_CONFIG_ENV_SCOPES.extraKey);
     for (const key of family.endpointParams) {
       const v = nonEmptyEndpoint(extra, key);
       if (v !== null)
-        return decide(v, formatField2(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key));
+        return decide(v, formatField3(CREDENTIAL_ENDPOINT_PAIRING.executorConfigExtraFieldFormat, configKey, key));
     }
   }
   return null;
@@ -7084,6 +7285,7 @@ function validateParsed(flow, opts, sources) {
   validateOrchestratorCampaign(f, issues, opts);
   validateCredentialBindings(f, issues);
   validateInputSchema(f, issues);
+  validateReservedInputNames(f, issues);
   validateOutputSchemas(f, issues);
   validateQualityGates(f, issues);
   validateProcessingOperations(f, issues);