@vaudience/aigentflow-flow-validator 0.25.0 → 0.26.0

package/dist/index.js

@@ -992,7 +992,7 @@ var aigentflow_spec_default = {
     providerAgent: "agent",
     providerCapability: "capability",
     agentResource: "run",
-    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
+    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).",
@@ -1000,7 +1000,7 @@ var aigentflow_spec_default = {
     },
     agentMissing: {
       code: "atlas_agent_missing",
-      messageFormat: "step %s runs an Atlas agent but query.agent is missing or empty.",
+      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: {
@@ -1026,9 +1026,46 @@ var aigentflow_spec_default = {
     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."
+      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",
@@ -2084,7 +2121,23 @@ var ATLAS_EXECUTOR = {
   capabilitiesNotLiteral: atlas.capabilitiesNotLiteral,
   promptMissing: atlas.promptMissing,
   promptBoth: atlas.promptBoth,
-  capabilityRefInvalid: atlas.capabilityRefInvalid
+  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
@@ -2151,10 +2204,12 @@ function checkExecutor(executor, field, stepID, 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 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);
@@ -2168,31 +2223,41 @@ function checkAtlasStep(executor, query, stepField, stepID, issues) {
     });
   };
   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 === "") {
+    if (typeof agent !== "string" || agent.trim() === "") {
       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 !== "";
+    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;
   }
-  const caps = q2.capabilities;
-  if (Array.isArray(caps) && caps.some((c) => typeof c === "string" && c.includes(TEMPLATE_ACTION_OPEN))) {
-    report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
-  }
+  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;
@@ -3878,6 +3943,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;
@@ -4992,7 +5088,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++] ?? "");
 }
@@ -5010,7 +5106,7 @@ function validateServerOwnedQueryKeys(flow, issues) {
           issues,
           stepID,
           key,
-          formatField(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
+          formatField2(SERVER_OWNED_QUERY_KEYS.stepFieldFormat, stepID, key)
         );
       }
     }
@@ -5024,7 +5120,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)
         );
       }
     }
@@ -5291,7 +5387,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++] ?? "");
 }
@@ -5313,14 +5409,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)
       });
     }
   }
@@ -5384,7 +5480,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) {
@@ -5431,7 +5527,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
@@ -5444,7 +5540,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)
         };
       }
     }
@@ -5470,13 +5566,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;
@@ -7187,6 +7283,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);