@vaudience/aigentflow-flow-validator 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -304,6 +304,17 @@ function isValidGoDuration(input) {
 var RESERVED_STEP_ID_CHAR = ".";
 var RESERVED_STEP_ID_ORCHESTRATOR = "orchestrator";
 var DISPLAY_NAME_MAX_LEN = 80;
+var YAML11_BOOL_WORDS = new Set(
+  ["y", "yes", "on", "n", "no", "off"].flatMap((w) => [
+    w,
+    w.toUpperCase(),
+    w[0].toUpperCase() + w.slice(1)
+  ])
+);
+function isBoolLike(v) {
+  if (v === null || typeof v === "boolean") return true;
+  return typeof v === "string" && YAML11_BOOL_WORDS.has(v);
+}
 function validateBasicStructure(flow, issues) {
   if (!issues.nonEmptyStringOf(flow, "aigentflow_version", "")) {
     issues.error({
@@ -333,6 +344,14 @@ function validateBasicStructure(flow, issues) {
       });
     }
   }
+  if (flow.strict_templates !== void 0 && !isBoolLike(flow.strict_templates)) {
+    issues.error({
+      field: "strict_templates",
+      message: "strict_templates must be a boolean (true or false)",
+      code: "invalid_type",
+      suggestion: "Write 'strict_templates: true' or remove the key"
+    });
+  }
   const start = issues.stringOf(flow, "start", "");
   if (start === null || start === "") {
     issues.error({
@@ -432,7 +451,7 @@ function validateBasicStructure(flow, issues) {
 
 // src/spec/aigentflow-spec.json
 var aigentflow_spec_default = {
-  specVersion: "2.821.0",
+  specVersion: "2.828.0",
   inputSchemaVersion: 1,
   executorSchemes: [
     "a2a",
@@ -456,6 +475,7 @@ var aigentflow_spec_default = {
     "geocoding",
     "geovisualize",
     "getmd",
+    "here",
     "homeassistant",
     "hosting",
     "http",
@@ -928,6 +948,33 @@ var aigentflow_spec_default = {
     stepFieldFormat: "steps.%s.query.%s",
     loopStepFieldFormat: "steps.%s.loop.steps.%s.query.%s"
   },
+  flowDataReservedKeys: {
+    code: "flow_data_key_reserved",
+    fieldFormat: "data.%s",
+    messageFormat: "data: key %s is reserved: %s. It would write into the engine's own state, so it is not seeded.",
+    suggestion: "Rename the key (no leading `_` or `.`, and not one of the engine namespaces memory., orchestrator., campaign., voiceagent.).",
+    exact: {
+      org_id: "the mission's organization, set by the engine for Thalamus/Engram calls",
+      memory: "the memory scope namespace",
+      orchestrator: "the orchestrator's state namespace",
+      campaign: "the campaign's state namespace",
+      voiceagent: "the voice agent's state namespace",
+      current_flow: "engine bookkeeping (the current flow definition)",
+      modified_flow: "engine bookkeeping (dynamic flow modification)",
+      modification_history: "engine bookkeeping (dynamic flow modification)",
+      modification_pending: "engine bookkeeping (dynamic flow modification)",
+      modification_requests: "engine bookkeeping (dynamic flow modification)",
+      bottleneck_state: "engine bookkeeping (bottleneck analysis)"
+    },
+    prefixes: [
+      { prefix: "_", reason: "keys starting with `_` are engine bookkeeping (current flow, loop and for_each context, taint lists such as `__untrusted_*`)" },
+      { prefix: ".", reason: "keys starting with `.` are engine step-response slots" },
+      { prefix: "memory.", reason: "the `memory.` namespace belongs to the engine" },
+      { prefix: "orchestrator.", reason: "the `orchestrator.` namespace belongs to the orchestrator" },
+      { prefix: "campaign.", reason: "the `campaign.` namespace belongs to the campaign engine" },
+      { prefix: "voiceagent.", reason: "the `voiceagent.` namespace belongs to the voice agent" }
+    ]
+  },
   credentialEndpointPairing: {
     stepFieldFormat: "steps.%s.query.%s",
     loopStepFieldFormat: "steps.%s.loop.steps.%s.query.%s",
@@ -1257,6 +1304,11 @@ var aigentflow_spec_default = {
       }
     }
   },
+  templateDefaultPiped: {
+    code: "template_default_piped",
+    messageFormat: "`default` takes the value FIRST, and a pipe passes the piped value LAST: `%s` is `default <fallback> <value>`, so the fallback is always the result",
+    suggestion: 'write the value first and the fallback second, as a call: `{{ default .x "fallback" }}`'
+  },
   complianceResidency: {
     code: "compliance_residency_unenforced",
     euResidencyCodes: ["EU", "DE", "FR", "IE", "NL", "IT", "ES"],
@@ -1555,6 +1607,7 @@ var aigentflow_spec_default = {
         rate_limit: "FlowRateLimitConfig",
         start: "scalar",
         steps: "map<StepDefinition>",
+        strict_templates: "scalar",
         tags: "list<scalar>",
         template: "FlowTemplateMetadata",
         tool_discovery: "scalar",
@@ -1859,6 +1912,14 @@ var SERVER_OWNED_QUERY_KEYS = {
   stepFieldFormat: aigentflow_spec_default.serverOwnedQueryKeys.stepFieldFormat,
   loopStepFieldFormat: aigentflow_spec_default.serverOwnedQueryKeys.loopStepFieldFormat
 };
+var FLOW_DATA_RESERVED_KEYS = {
+  code: aigentflow_spec_default.flowDataReservedKeys.code,
+  fieldFormat: aigentflow_spec_default.flowDataReservedKeys.fieldFormat,
+  messageFormat: aigentflow_spec_default.flowDataReservedKeys.messageFormat,
+  suggestion: aigentflow_spec_default.flowDataReservedKeys.suggestion,
+  exact: aigentflow_spec_default.flowDataReservedKeys.exact,
+  prefixes: aigentflow_spec_default.flowDataReservedKeys.prefixes
+};
 var CREDENTIAL_ENDPOINT_PAIRING = {
   stepFieldFormat: aigentflow_spec_default.credentialEndpointPairing.stepFieldFormat,
   loopStepFieldFormat: aigentflow_spec_default.credentialEndpointPairing.loopStepFieldFormat,
@@ -1916,6 +1977,11 @@ var EXAMPLES = {
     name: p.name,
     re: new RegExp(p.expr, p.flags)
   }))};
+var TEMPLATE_DEFAULT_PIPED = {
+  code: aigentflow_spec_default.templateDefaultPiped.code,
+  messageFormat: aigentflow_spec_default.templateDefaultPiped.messageFormat,
+  suggestion: aigentflow_spec_default.templateDefaultPiped.suggestion
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
@@ -3773,16 +3839,16 @@ function skipSpaces(src, idx) {
   }
   return i;
 }
-function scanString(src, start, quote) {
+function scanString(src, start, quote2) {
   let i = start + 1;
-  const raw = quote === "`";
+  const raw = quote2 === "`";
   while (i < src.length) {
     const c = src[i];
     if (!raw && c === "\\") {
       i += 2;
       continue;
     }
-    if (c === quote) return i;
+    if (c === quote2) return i;
     i += 1;
   }
   return -1;
@@ -3879,6 +3945,117 @@ function splitPipeline(body) {
   return stages;
 }
 
+// src/template/gotmpl-default.ts
+var FUNCTION_NAME = "default";
+var PIPE = "|";
+var OPEN_PAREN = "(";
+var CLOSE_PAREN = ")";
+var MAX_NESTING_DEPTH = 100;
+var PIPELINE_KEYWORDS = /^(?:else\s+if|else\s+with|if|range|with|template|block)(?![\w$.])/;
+var NO_PIPELINE = /^(?:define|else|end|break|continue)(?![\w$.])/;
+var DECLARATION = /^\$\w*(?:\s*,\s*\$\w*)*\s*:?=/;
+function pipedDefaultPipelines(src) {
+  const { actions, fatal } = lexActions(src);
+  if (fatal) return [];
+  const found = /* @__PURE__ */ new Set();
+  try {
+    for (const action of actions) {
+      if (action.isComment || action.body === "") continue;
+      scanAction(action.body, found);
+    }
+  } catch (err) {
+    if (!(err instanceof RangeError)) throw err;
+    return [];
+  }
+  return [...found].sort();
+}
+function scanAction(body, found) {
+  let rest = body;
+  const kw = PIPELINE_KEYWORDS.exec(rest);
+  if (!kw && NO_PIPELINE.test(rest)) return;
+  if (kw) {
+    rest = rest.slice(kw[0].length).trimStart();
+    const keyword = kw[0].replace(/\s+/g, " ");
+    if (keyword === "template" || keyword === "block") {
+      const q2 = rest[0];
+      if (q2 === '"' || q2 === "`") {
+        const end = scanString(rest, 0, q2);
+        if (end === -1) return;
+        rest = rest.slice(end + 1).trimStart();
+      }
+    }
+  }
+  if (rest === "") return;
+  parsePipeline(rest, 0, false, found, 0);
+}
+function parsePipeline(src, start, nested, found, depth) {
+  if (depth > MAX_NESTING_DEPTH) return { text: src.slice(start), end: src.length };
+  let i = start;
+  const n = src.length;
+  let decl = "";
+  const decMatch = DECLARATION.exec(src.slice(i));
+  if (decMatch) {
+    decl = decMatch[0].replace(/\s+/g, " ") + " ";
+    i += decMatch[0].length;
+  }
+  const commands = [];
+  let current = [];
+  let firstWords = [];
+  let pipedDefault = false;
+  const pushCommand = () => {
+    if (current.length > 0) {
+      commands.push(current);
+      firstWords.push(current[0]);
+    }
+    current = [];
+  };
+  while (i < n) {
+    const c = src[i];
+    if (c === " " || c === "	" || c === "\n" || c === "\r") {
+      i += 1;
+      continue;
+    }
+    if (c === '"' || c === "`" || c === "'") {
+      const end = scanString(src, i, c);
+      const stop = end === -1 ? n - 1 : end;
+      current.push(src.slice(i, stop + 1));
+      i = stop + 1;
+      continue;
+    }
+    if (c === OPEN_PAREN) {
+      const inner = parsePipeline(src, i + 1, true, found, depth + 1);
+      current.push(`(${inner.text})`);
+      i = inner.end;
+      continue;
+    }
+    if (c === CLOSE_PAREN) {
+      if (nested) {
+        i += 1;
+        break;
+      }
+      i += 1;
+      continue;
+    }
+    if (c === PIPE) {
+      pushCommand();
+      i += 1;
+      continue;
+    }
+    let j = i;
+    while (j < n && !/[\s|()"`']/.test(src[j])) j += 1;
+    if (j === i) j = i + 1;
+    current.push(src.slice(i, j));
+    i = j;
+  }
+  pushCommand();
+  firstWords.forEach((word, idx) => {
+    if (idx > 0 && word === FUNCTION_NAME) pipedDefault = true;
+  });
+  const text = decl + commands.map((cmd) => cmd.join(" ")).join(` ${PIPE} `);
+  if (pipedDefault) found.add(text);
+  return { text, end: i };
+}
+
 // src/validators/processingOperations.ts
 var PROCESSING_OP_GUARD_KEY = PROCESSING_OPERATIONS.guardKey;
 var PROCESSING_PHASES = ["pre_processing", "post_processing"];
@@ -4025,6 +4202,17 @@ function checkTemplateString(value, field, stepID, issues, stats, opts, demote =
       });
     }
   }
+  if (errors.length > 0) return;
+  for (const pipe of pipedDefaultPipelines(value)) {
+    report({
+      field,
+      message: TEMPLATE_DEFAULT_PIPED.messageFormat.replace("%s", () => pipe),
+      code: TEMPLATE_DEFAULT_PIPED.code,
+      stepId: stepID,
+      context: `Template: ${value}`,
+      suggestion: TEMPLATE_DEFAULT_PIPED.suggestion
+    });
+  }
 }
 function walkStrings2(basePath, value, stepID, issues, stats, opts, check, demote = false) {
   if (isString(value)) {
@@ -4263,6 +4451,35 @@ function validateRetiredKeys(flow, issues) {
   }
 }
 
+// src/validators/flowDataKeys.ts
+var KEY_DATA = "data";
+function quote(key) {
+  return JSON.stringify(key);
+}
+function flowDataKeyReservation(key) {
+  if (Object.prototype.hasOwnProperty.call(FLOW_DATA_RESERVED_KEYS.exact, key)) {
+    return FLOW_DATA_RESERVED_KEYS.exact[key];
+  }
+  for (const p of FLOW_DATA_RESERVED_KEYS.prefixes) {
+    if (key.startsWith(p.prefix)) return p.reason;
+  }
+  return void 0;
+}
+function validateFlowDataKeys(flow, issues) {
+  const data = flow[KEY_DATA];
+  if (!isRecord(data)) return;
+  for (const key of Object.keys(data).sort()) {
+    const reason = flowDataKeyReservation(key);
+    if (reason === void 0) continue;
+    issues.error({
+      field: FLOW_DATA_RESERVED_KEYS.fieldFormat.replace("%s", () => key),
+      message: FLOW_DATA_RESERVED_KEYS.messageFormat.replace("%s", () => quote(key)).replace("%s", () => reason),
+      code: FLOW_DATA_RESERVED_KEYS.code,
+      suggestion: FLOW_DATA_RESERVED_KEYS.suggestion
+    });
+  }
+}
+
 // src/validators/saveDoor.ts
 var TOOL_DISCOVERY_MODES = /* @__PURE__ */ new Set(["eager", "lazy", "off"]);
 var TEMPLATE_ACTION_OPEN2 = "{{";
@@ -6725,6 +6942,7 @@ function validateParsed(flow, opts, sources) {
   validateSaveDoorExtras(f, issues);
   validateExecutorConfigEnvScopes(f, issues);
   validateServerOwnedQueryKeys(f, issues);
+  validateFlowDataKeys(f, issues);
   validateCredentialEndpointPairing(f, issues);
   validateExamples(f, issues);
   validateOrchestratorExons(f, issues);