@suveren/gateway 0.37.0 → 0.38.0

package/dist/mcp-server/http.mjs

@@ -3600,7 +3600,6 @@ function setAsBaseUrl(url) {
   AS_BASE = url.replace(/\/$/, "");
 }
 var OPERATOR_NAME = process.env.SUVEREN_OPERATOR_NAME ?? "Suveren";
-var HAP_URL = "https://www.humanagencyprotocol.org/";
 var FOOTER_RE = /\n*(?:—|--) (?:Sent|Published) by (?:an AI agent|[^\n]+?'s AI agent)[\s\S]*$/;
 function shouldAttachFooter() {
   return true;
@@ -3608,16 +3607,11 @@ function shouldAttachFooter() {
 function receiptUrl(receiptId) {
   return `${AS_BASE}/t/${receiptId}`;
 }
-function hapLine() {
-  return `-- ${OPERATOR_NAME} implements HAP, the open Human Agency Protocol: ${HAP_URL}`;
-}
 function footerText(receiptId, verb, subject) {
   const identity = deriveIdentityLine(subject, { operatorName: OPERATOR_NAME }).replace(/^Sent\b/, verb);
   return `
 
--- ${identity}. Ticket: ${receiptUrl(receiptId)}
-
-${hapLine()}`;
+-- ${identity}. Ticket: ${receiptUrl(receiptId)}`;
 }
 function detectContentField(tool) {
   return tool.gating?.message?.text ?? null;
@@ -3650,6 +3644,8 @@ import { getProfile } from "@hap/core";
 // src/lib/tool-gating-types.ts
 var MAX_PREVIEW_READS = 10;
 var MAX_FOREACH_ELEMENTS = 50;
+var CHECK_STATUSES = ["pass", "fail", "notice", "not_checked"];
+var MAX_CHECKS_PER_TOOL = 12;
 var MAX_RECORD_KEY_STEPS = 2;
 
 // src/lib/scope-specificity.ts
@@ -3937,8 +3933,28 @@ function invalidReadConfigReason(toolName, idx, entry) {
   if (p.kind !== void 0 && p.kind !== "document") {
     return `${label}.kind must be "document" (the only recognized value)`;
   }
+  if (p.when !== void 0 && (typeof p.when !== "string" || !PLAIN_PATH_RE.test(p.when))) {
+    return `${label}.when must be a dotted argument path (e.g. "uid" or "item_id")`;
+  }
+  if (p.displayOnly !== void 0 && typeof p.displayOnly !== "boolean") {
+    return `${label}.displayOnly must be a boolean`;
+  }
+  if (p.as !== void 0) {
+    if (typeof p.as !== "string" || !/^[A-Za-z_][\w-]*$/.test(p.as)) return `${label}.as must be a plain name`;
+    if (p.attach !== void 0 || p.forEach !== void 0 || p.kind !== void 0) {
+      return `${label}.as cannot be combined with attach, forEach or kind`;
+    }
+  }
+  if (p.label !== void 0 && (typeof p.label !== "string" || p.label.trim().length === 0 || p.label.length > 60)) {
+    return `${label}.label must be a non-empty string of at most 60 characters`;
+  }
+  if (p.displayOnly === true && p.version !== void 0) {
+    return `${label} cannot be both displayOnly and version-checked \u2014 a versioned read is the record the action changes`;
+  }
   return null;
 }
+var PLAIN_PATH_RE = /^[A-Za-z_][\w-]*(\.[A-Za-z_][\w-]*)*$/;
+var CHECK_PATH_RE = /^(?:[A-Za-z_][\w-]*(?:\.(?:[A-Za-z_][\w-]*|\$version))*|[A-Za-z_][\w-]*\[\](?:\.[A-Za-z_][\w-]*)+)$/;
 function invalidPreviewReason(toolName, entry) {
   if (entry === null || typeof entry !== "object") return null;
   const preview = entry.preview;
@@ -3990,12 +4006,30 @@ function invalidDisplayHintsReason(toolName, entry) {
       }
     }
   }
+  if (d.compare !== void 0) {
+    if (d.compare === null || typeof d.compare !== "object" || Array.isArray(d.compare)) {
+      return `override "${toolName}".display.compare must be an object mapping arguments to paths`;
+    }
+    for (const [arg, path] of Object.entries(d.compare)) {
+      if (typeof path !== "string" || !PLAIN_PATH_RE.test(path) || !path.includes(".")) {
+        return `override "${toolName}".display.compare.${arg} must be "<attach>.<field>"`;
+      }
+    }
+  }
+  if (d.names !== void 0) {
+    if (d.names === null || typeof d.names !== "object" || Array.isArray(d.names) || !Object.values(d.names).every((v) => typeof v === "string" && PLAIN_PATH_RE.test(v))) {
+      return `override "${toolName}".display.names must map attach keys to dotted paths`;
+    }
+  }
+  if (d.verb !== void 0 && d.verb !== "created" && d.verb !== "changed") {
+    return `override "${toolName}".display.verb must be "created" or "changed"`;
+  }
   if (d.aiText !== void 0 && (typeof d.aiText !== "string" || d.aiText.length === 0)) {
     return `override "${toolName}".display.aiText must be a non-empty string naming an argument`;
   }
   return null;
 }
-var SUMMARY_FORMATS = ["money", "percent", "list", "short", "date"];
+var SUMMARY_FORMATS = ["money", "percent", "list", "short", "date", "ref"];
 function invalidSummaryReason(toolName, entry) {
   if (entry === null || typeof entry !== "object") return null;
   const summary = entry.summary;
@@ -4029,6 +4063,170 @@ function invalidSummaryReason(toolName, entry) {
   }
   return null;
 }
+var CHECK_KEYS = /* @__PURE__ */ new Set([
+  "key",
+  "label",
+  "path",
+  "when",
+  "forEach",
+  "pass",
+  "fail",
+  "notice",
+  "notChecked",
+  "compare",
+  "onTrue",
+  "onFalse",
+  "missing",
+  "detail",
+  "details",
+  "blocking",
+  "present",
+  "absent",
+  "showOnly"
+]);
+var CHECK_LISTS = ["pass", "fail", "notice", "notChecked"];
+var DETAIL_FORMATS = ["money", "percent", "list", "short", "date"];
+function checkPathReason(at, path, forEach) {
+  if (typeof path !== "string" || !CHECK_PATH_RE.test(path)) return `${at} has an invalid path ${JSON.stringify(path)}`;
+  const b = path.indexOf("[]");
+  if (b >= 0 && path.slice(0, b) !== forEach) return `${at} path "${path}" reads an element but forEach is not "${path.slice(0, b)}"`;
+  return null;
+}
+function checkDetailReason(at, detail, forEach) {
+  if (typeof detail !== "string" || detail.trim().length === 0) return `${at}.detail must be a non-empty string`;
+  if (detail.length > 200) return `${at}.detail must be at most 200 characters`;
+  let brace = 0;
+  let bracket = 0;
+  for (const ch of detail) {
+    if (ch === "{") {
+      brace += 1;
+      if (brace > 1) return `${at}.detail has nested { }`;
+      continue;
+    }
+    if (ch === "}") {
+      brace -= 1;
+      if (brace < 0) return `${at}.detail has unbalanced { }`;
+      continue;
+    }
+    if (brace > 0) continue;
+    if (ch === "[") {
+      bracket += 1;
+      if (bracket > 1) return `${at}.detail has nested [ ]`;
+    }
+    if (ch === "]") {
+      bracket -= 1;
+      if (bracket < 0) return `${at}.detail has unbalanced [ ]`;
+    }
+  }
+  if (brace !== 0 || bracket !== 0) return `${at}.detail has unbalanced brackets`;
+  for (const m of detail.matchAll(/\{([^{}]+)\}/g)) {
+    const [path, fmt, extra] = m[1].split("|").map((x) => x.trim());
+    if (extra !== void 0) return `${at}.detail {${m[1]}} has more than one format`;
+    if (path === "#") {
+      if (typeof forEach !== "string") return `${at}.detail uses {#} without forEach`;
+    } else {
+      const r = checkPathReason(`${at}.detail`, path, forEach);
+      if (r) return r;
+    }
+    const isCount = fmt !== void 0 && /^count:[^/{}|]+\/[^/{}|]+$/.test(fmt);
+    if (fmt !== void 0 && !DETAIL_FORMATS.includes(fmt) && !isCount) return `${at}.detail {${m[1]}} has unknown format "${fmt}"`;
+  }
+  return null;
+}
+function checkWhenReason(at, when, forEach) {
+  if (when === void 0) return null;
+  if (typeof when === "string") return checkPathReason(`${at}.when`, when, forEach);
+  if (when === null || typeof when !== "object" || Array.isArray(when)) return `${at}.when must be a path or {path, in}`;
+  const w = when;
+  const extra = Object.keys(w).find((k) => k !== "path" && k !== "in");
+  if (extra) return `${at}.when has unknown key "${extra}"`;
+  return checkPathReason(`${at}.when.path`, w.path, forEach) ?? checkValueListReason(`${at}.when.in`, w.in);
+}
+function checkValueListReason(at, list) {
+  if (!Array.isArray(list) || list.length === 0) return `${at} must be a non-empty list of values`;
+  const ok = list.every((v) => v === null || ["string", "boolean"].includes(typeof v) || typeof v === "number" && Number.isFinite(v));
+  return ok ? null : `${at} may hold only strings, numbers, booleans or null`;
+}
+function invalidCheckReason(at, raw, seen) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return `${at} must be an object`;
+  const c = raw;
+  const unknownKey = Object.keys(c).find((k) => !CHECK_KEYS.has(k));
+  if (unknownKey) return `${at} has unknown key "${unknownKey}"`;
+  if (typeof c.key !== "string" || c.key.length === 0) return `${at}.key must be a non-empty string`;
+  if (seen.has(c.key)) return `${at}.key "${c.key}" is declared twice`;
+  seen.add(c.key);
+  if (typeof c.label !== "string" || c.label.trim().length === 0 || c.label.length > 80) {
+    return `${at}.label must be a non-empty string of at most 80 characters`;
+  }
+  if (c.forEach !== void 0 && (typeof c.forEach !== "string" || !/^[A-Za-z_][\w-]*$/.test(c.forEach))) {
+    return `${at}.forEach must name an array argument`;
+  }
+  const pathReason = checkPathReason(`${at}.path`, c.path, c.forEach) ?? checkWhenReason(at, c.when, c.forEach);
+  if (pathReason) return pathReason;
+  const hasList = CHECK_LISTS.some((k) => c[k] !== void 0);
+  const hasCompare = c.compare !== void 0;
+  const hasPresence = c.present !== void 0 || c.absent !== void 0;
+  if ([hasList, hasCompare, hasPresence].filter(Boolean).length !== 1) {
+    return `${at} must declare exactly one form: value lists (pass/fail/notice/notChecked), compare, or present/absent`;
+  }
+  if (hasPresence) {
+    for (const k of ["present", "absent"]) {
+      if (!CHECK_STATUSES.includes(c[k])) return `${at}.${k} must be one of ${CHECK_STATUSES.join(", ")} (both required)`;
+    }
+  }
+  for (const k of CHECK_LISTS) {
+    if (c[k] === void 0) continue;
+    const r = checkValueListReason(`${at}.${k}`, c[k]);
+    if (r) return r;
+  }
+  if (hasCompare) {
+    const cmp = c.compare;
+    if (cmp === null || typeof cmp !== "object" || Array.isArray(cmp)) return `${at}.compare must be an object`;
+    if (!["eq", "ne", "gt", "lt"].includes(cmp.op)) return `${at}.compare.op must be one of eq, ne, gt, lt`;
+    if (typeof cmp.to === "number") {
+      if (!Number.isFinite(cmp.to)) return `${at}.compare.to must be a finite number or a path`;
+    } else {
+      const r = checkPathReason(`${at}.compare.to`, cmp.to, c.forEach);
+      if (r) return r;
+    }
+    const extra = Object.keys(cmp).find((k) => k !== "op" && k !== "to");
+    if (extra) return `${at}.compare has unknown key "${extra}"`;
+  }
+  for (const k of ["onTrue", "onFalse"]) {
+    if (c[k] === void 0) continue;
+    if (!hasCompare) return `${at}.${k} applies to compare only`;
+    if (!CHECK_STATUSES.includes(c[k])) return `${at}.${k} must be one of ${CHECK_STATUSES.join(", ")}`;
+  }
+  if (c.blocking !== void 0 && typeof c.blocking !== "boolean") return `${at}.blocking must be a boolean`;
+  if (c.showOnly !== void 0 && c.showOnly !== "fail" && c.showOnly !== "notice") return `${at}.showOnly must be "fail" or "notice"`;
+  if (c.missing !== void 0 && c.missing !== "skip" && c.missing !== "not_checked") {
+    return `${at}.missing must be "skip" or "not_checked"`;
+  }
+  if (c.details !== void 0) {
+    if (c.details === null || typeof c.details !== "object" || Array.isArray(c.details)) return `${at}.details must map a status to a detail`;
+    for (const [status, d] of Object.entries(c.details)) {
+      if (!CHECK_STATUSES.includes(status)) return `${at}.details.${status} is not a status (${CHECK_STATUSES.join(", ")})`;
+      const r = checkDetailReason(`${at}.details.${status}`, d, c.forEach);
+      if (r) return r;
+    }
+  }
+  if (c.detail !== void 0) return checkDetailReason(at, c.detail, c.forEach);
+  return null;
+}
+function invalidChecksReason(toolName, entry) {
+  if (entry === null || typeof entry !== "object") return null;
+  const checks = entry.checks;
+  if (checks === void 0) return null;
+  const base = `override "${toolName}".checks`;
+  if (!Array.isArray(checks) || checks.length === 0) return `${base} must be a non-empty list`;
+  if (checks.length > MAX_CHECKS_PER_TOOL) return `${base} declares ${checks.length} checks \u2014 max ${MAX_CHECKS_PER_TOOL}`;
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, raw] of checks.entries()) {
+    const reason = invalidCheckReason(`${base}[${i}]`, raw, seen);
+    if (reason) return reason;
+  }
+  return null;
+}
 function invalidInternalReason(toolName, entry) {
   if (entry === null || typeof entry !== "object") return null;
   const internal = entry.internal;
@@ -4092,7 +4290,7 @@ function invalidManifestMessageReason(manifest) {
 function invalidManifestPreviewReason(manifest) {
   const overrides = manifest.toolGating?.overrides ?? {};
   for (const [toolName, entry] of Object.entries(overrides)) {
-    const reason = invalidPreviewReason(toolName, entry) ?? invalidDisplayHintsReason(toolName, entry) ?? invalidSummaryReason(toolName, entry);
+    const reason = invalidPreviewReason(toolName, entry) ?? invalidDisplayHintsReason(toolName, entry) ?? invalidSummaryReason(toolName, entry) ?? invalidChecksReason(toolName, entry);
     if (reason) return reason;
   }
   return null;
@@ -4448,6 +4646,36 @@ function invalidManifestReadGateReason(manifest) {
   }
   return null;
 }
+function invalidNetworkReason(manifest) {
+  const network = manifest.network;
+  if (network === void 0) return null;
+  if (!Array.isArray(network) || network.length === 0) return "network must be a non-empty list of outside calls";
+  for (const [i, raw] of network.entries()) {
+    const at = `network[${i}]`;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return `${at} must be an object`;
+    const n = raw;
+    const extra = Object.keys(n).find((k) => !["modes", "host", "purpose", "sends"].includes(k));
+    if (extra) return `${at} has unknown key "${extra}"`;
+    if (typeof n.host !== "string" || !/^(?=.{1,253}$)[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/.test(n.host)) {
+      return `${at}.host must be a bare host name, e.g. "api.example.com"`;
+    }
+    for (const k of ["purpose", "sends"]) {
+      if (typeof n[k] !== "string" || n[k].trim().length === 0 || n[k].length > 200) {
+        return `${at}.${k} must be a non-empty string of at most 200 characters`;
+      }
+    }
+    if (n.modes !== void 0) {
+      if (n.modes === null || typeof n.modes !== "object" || Array.isArray(n.modes) || Object.keys(n.modes).length === 0) {
+        return `${at}.modes must be an object mapping a mode to true or a list of adapters`;
+      }
+      for (const [mode, v] of Object.entries(n.modes)) {
+        const ok = v === true || Array.isArray(v) && v.length > 0 && v.every((a) => typeof a === "string" && a.length > 0);
+        if (!ok) return `${at}.modes.${mode} must be true or a non-empty list of adapter names`;
+      }
+    }
+  }
+  return null;
+}
 function invalidModeLabelsReason(manifest) {
   if (!manifest.modeLabels) return null;
   if (manifest.modeLabels === null || typeof manifest.modeLabels !== "object" || Array.isArray(manifest.modeLabels)) {
@@ -4558,6 +4786,11 @@ function loadManifests(integrationsDir) {
         console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${valuesReason}`);
         continue;
       }
+      const networkReason = invalidNetworkReason(manifest);
+      if (networkReason) {
+        console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${networkReason}`);
+        continue;
+      }
       const modeLabelsReason = invalidModeLabelsReason(manifest) ?? (manifest.modeNotes ? invalidModeLabelsReason({ ...manifest, modeLabels: manifest.modeNotes })?.replace(/modeLabels/g, "modeNotes") ?? null : null);
       if (modeLabelsReason) {
         console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${modeLabelsReason}`);
@@ -4727,6 +4960,241 @@ function candidatesAllowingAttachments(candidates, refs, profileOf) {
 
 // src/lib/preview.ts
 import { computeContentHash } from "@hap/core";
+
+// src/lib/checks.ts
+var ABSENT = { ok: false, why: "absent" };
+var NO_ANSWER = { ok: false, why: "no_answer" };
+function isPlainRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function fromOutcome(outcome, rest) {
+  if (!outcome || outcome.status !== "ok") return outcome?.status === "none" ? ABSENT : NO_ANSWER;
+  const body = structuredOrJsonText(outcome.body);
+  if (!body) return NO_ANSWER;
+  const v = digNullAware(body, rest);
+  return v === void 0 ? ABSENT : { ok: true, value: v };
+}
+function digNullAware(source, segs) {
+  let cur = source;
+  for (const part of segs) {
+    if (cur === null) return null;
+    if (typeof cur !== "object" || Array.isArray(cur)) return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function resolveCheckPath(path, scope2) {
+  const { ctx, reads, element } = scope2;
+  const sections = ctx.sections ?? [];
+  const bracket = path.indexOf("[]");
+  if (bracket >= 0) {
+    const arrayName = path.slice(0, bracket);
+    const segs2 = path.slice(bracket + 3).split(".").filter(Boolean);
+    if (!element || element.forEach !== arrayName || segs2.length === 0) return ABSENT;
+    const readIdx = reads.findIndex((r) => r.forEach === arrayName && r.attach === segs2[0]);
+    if (readIdx >= 0) {
+      return fromOutcome(sections[readIdx]?.elements?.[element.readIndex], segs2.slice(1));
+    }
+    const v2 = valueAtPath(element.value, segs2.join("."));
+    return v2 === void 0 ? ABSENT : { ok: true, value: v2 };
+  }
+  const segs = path.split(".");
+  if (segs.length > 1) {
+    const readIdx = reads.findIndex((r) => !r.forEach && (r.attach === segs[0] || r.as === segs[0]));
+    if (readIdx >= 0 && segs[1] === "$version") {
+      const version = sections[readIdx]?.version;
+      if (!version) return ABSENT;
+      const v2 = valueAtPath({ approved: version.approved, current: version.current, stale: version.stale }, segs.slice(2).join("."));
+      return v2 === void 0 ? ABSENT : { ok: true, value: v2 };
+    }
+    if (readIdx >= 0) return fromOutcome(sections[readIdx]?.result, segs.slice(1));
+  }
+  const v = valueAtPath(ctx.args, path);
+  return v === void 0 ? ABSENT : { ok: true, value: v };
+}
+function sameValue(a, b) {
+  if (typeof a === "number" && typeof b === "number") return Math.abs(a - b) < 1e-9;
+  return a === b;
+}
+function inList(list, v) {
+  return Array.isArray(list) && list.some((x) => sameValue(x, v));
+}
+function show(v) {
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+function statusFor(decl, value, scope2) {
+  if (decl.compare) {
+    let to = decl.compare.to;
+    if (typeof decl.compare.to === "string") {
+      const r = resolveCheckPath(decl.compare.to, scope2);
+      if (!r.ok) return r;
+      to = r.value;
+    }
+    if (value === null || to === null) return ABSENT;
+    let result;
+    switch (decl.compare.op) {
+      case "eq":
+        result = sameValue(value, to);
+        break;
+      case "ne":
+        result = !sameValue(value, to);
+        break;
+      case "gt":
+      case "lt":
+        if (typeof value !== "number" || typeof to !== "number") {
+          return { status: "not_checked", reason: `unexpected value ${show(value)}` };
+        }
+        result = decl.compare.op === "gt" ? value > to : value < to;
+        break;
+    }
+    return { status: result ? decl.onTrue ?? "pass" : decl.onFalse ?? "fail" };
+  }
+  if (decl.present !== void 0 || decl.absent !== void 0) {
+    return { status: isPresentForWhen(value) || value === false ? decl.present : decl.absent };
+  }
+  if (inList(decl.fail, value)) return { status: "fail" };
+  if (inList(decl.pass, value)) return { status: "pass" };
+  if (inList(decl.notChecked, value)) return { status: "not_checked" };
+  if (inList(decl.notice, value)) return { status: "notice" };
+  return { status: "not_checked", reason: `unexpected value ${show(value)}` };
+}
+function evaluateOne(decl, scope2) {
+  if (typeof decl.when === "string") {
+    const w = resolveCheckPath(decl.when, scope2);
+    if (!w.ok || !isPresentForWhen(w.value)) return null;
+  } else if (decl.when !== void 0) {
+    const w = resolveCheckPath(decl.when.path, scope2);
+    if (!w.ok || !inList(decl.when.in, w.value)) return null;
+  }
+  const base = {
+    key: decl.key,
+    label: decl.label,
+    status: "not_checked",
+    ...decl.blocking ? { blocking: true } : {},
+    ...scope2.element ? { index: scope2.element.position } : {}
+  };
+  const missing = (why) => {
+    if ((decl.missing ?? "skip") === "skip" || decl.showOnly) return null;
+    return { ...base, status: "not_checked", reason: why === "no_answer" ? "no answer from the connector" : "no value to check" };
+  };
+  const v = resolveCheckPath(decl.path, scope2);
+  if (!v.ok) return missing(v.why);
+  const outcome = statusFor(decl, v.value, scope2);
+  if ("ok" in outcome) return outcome.ok || decl.showOnly ? null : missing(outcome.why);
+  if (decl.showOnly === "fail" && outcome.status !== "fail") return null;
+  if (decl.showOnly === "notice" && outcome.status !== "fail" && outcome.status !== "notice") return null;
+  const template = decl.details?.[outcome.status] ?? decl.detail;
+  const detail = template !== void 0 ? renderCheckDetail(template, scope2) : null;
+  const tested = v.value;
+  const plain = tested === null || ["string", "number", "boolean"].includes(typeof tested);
+  return {
+    ...base,
+    ...plain ? { value: tested } : {},
+    status: outcome.status,
+    ...outcome.reason ? { reason: outcome.reason } : {},
+    ...detail ? { detail } : {}
+  };
+}
+function evaluateChecks(checks, ctx) {
+  if (!checks || checks.length === 0) return [];
+  const reads = ctx.declaration === void 0 ? [] : Array.isArray(ctx.declaration) ? ctx.declaration : [];
+  const out = [];
+  for (const decl of checks) {
+    if (!decl.forEach) {
+      const r = evaluateOne(decl, { ctx, reads });
+      if (r) out.push(r);
+      continue;
+    }
+    const source = ctx.args[decl.forEach];
+    const list = Array.isArray(source) ? source.slice(0, MAX_FOREACH_ELEMENTS) : [];
+    let readIndex = 0;
+    list.forEach((el, i) => {
+      if (!isPlainRecord(el)) return;
+      const r = evaluateOne(decl, { ctx, reads, element: { forEach: decl.forEach, value: el, readIndex, position: i + 1 } });
+      readIndex += 1;
+      if (r) out.push(r);
+    });
+  }
+  return out;
+}
+var PLACEHOLDER = /\{([^{}]+)\}/g;
+function formatValue(v, fmt, currency) {
+  if (fmt === "money") {
+    const n = typeof v === "number" ? v : Number(v);
+    if (!Number.isFinite(n)) return show(v);
+    return currency ? `${n.toFixed(2)} ${currency}` : n.toFixed(2);
+  }
+  if (fmt === "percent") return `${show(v)}%`;
+  if (fmt === "date") {
+    const d = new Date(String(v));
+    return Number.isNaN(d.getTime()) ? show(v) : d.toISOString().slice(0, 10);
+  }
+  if (fmt === "list" && Array.isArray(v)) return v.map(show).join(", ");
+  if (fmt?.startsWith("count:")) {
+    const [one, many] = fmt.slice("count:".length).split("/");
+    return `${show(v)} ${Number(v) === 1 ? one : many}`;
+  }
+  const s = show(v);
+  if (fmt === "short" && s.length > 60) return `${s.slice(0, 59).trimEnd()}\u2026`;
+  return s;
+}
+function fillDetail(text, scope2, currency) {
+  let missing = false;
+  const out = text.replace(PLACEHOLDER, (_m, inner) => {
+    const [path, fmt] = inner.split("|").map((x) => x.trim());
+    if (path === "#") {
+      if (!scope2.element) {
+        missing = true;
+        return "";
+      }
+      return String(scope2.element.position);
+    }
+    const r = resolveCheckPath(path, scope2);
+    if (!r.ok || !isPresentForWhen(r.value) && r.value !== false) {
+      missing = true;
+      return "";
+    }
+    return formatValue(r.value, fmt, currency);
+  });
+  return missing ? null : out;
+}
+function renderCheckDetail(template, scope2) {
+  const curPath = scope2.ctx.currencyField ?? "currency";
+  const cur = resolveCheckPath(curPath, scope2);
+  const currency = cur.ok && typeof cur.value === "string" ? cur.value : void 0;
+  const segments = [{ text: "", optional: false }];
+  let depth = 0;
+  for (const ch of template) {
+    if (ch === "{") depth += 1;
+    if (ch === "}") depth -= 1;
+    const last = segments[segments.length - 1];
+    if (depth === 0 && ch === "[" && !last.optional) {
+      segments.push({ text: "", optional: true });
+      continue;
+    }
+    if (depth === 0 && ch === "]" && last.optional) {
+      segments.push({ text: "", optional: false });
+      continue;
+    }
+    last.text += ch;
+  }
+  let out = "";
+  for (const seg of segments) {
+    const filled = fillDetail(seg.text, scope2, currency);
+    if (filled === null && !seg.optional) return null;
+    out += filled ?? "";
+  }
+  const clean = out.replace(/\s+/g, " ").trim().replace(/^[—–,;:\s]+/, "").replace(/[—–,;:\s]+$/, "");
+  return clean.length > 0 ? clean : null;
+}
+function blockingFailures(results) {
+  return results.filter((r) => r.blocking === true && r.status === "fail");
+}
+function blockingRefusalReason(failures) {
+  return failures.map((f) => `${f.label}${f.index !== void 0 ? ` (line ${f.index})` : ""}: failed${f.value !== void 0 ? ` (${f.value === null ? "none" : String(f.value)})` : ""}${f.detail ? ` \u2014 ${f.detail}` : ""}`).join("; ");
+}
+
+// src/lib/preview.ts
 var PREVIEW_READ_TIMEOUT_MS = 5e3;
 var PREVIEW_MESSAGE_CAP = 500;
 function capText(text, max = PREVIEW_MESSAGE_CAP) {
@@ -4749,16 +5217,39 @@ function getToolDisplayHints(integrationManager2, integrationId, toolName) {
   const entry = overrides[toolName];
   return entry?.display;
 }
+function getToolChecks(integrationManager2, integrationId, toolName) {
+  if (integrationManager2.isBuiltin?.(integrationId)) return void 0;
+  const entry = getManifest(integrationId)?.toolGating?.overrides?.[toolName];
+  return entry?.checks;
+}
 function mapPreviewArgs(preview, actionArgs) {
   const mapped = {};
   for (const [targetArg, sourceArg] of Object.entries(preview.args)) {
-    if (sourceArg in actionArgs) mapped[targetArg] = actionArgs[sourceArg];
+    const value = actionArgs[sourceArg];
+    if (value !== void 0 && value !== null) mapped[targetArg] = value;
   }
   return mapped;
 }
+function isPresentForWhen(v) {
+  if (v === void 0 || v === null || v === false) return false;
+  if (typeof v === "string") return v.trim().length > 0;
+  if (Array.isArray(v)) return v.length > 0;
+  return true;
+}
+function valueAtPath(source, path) {
+  let cur = source;
+  for (const part of path.split(".")) {
+    if (cur === null || typeof cur !== "object" || Array.isArray(cur)) return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
 function previewHasNoTarget(preview, mapped) {
   return Object.keys(preview.args).length > 0 && Object.keys(mapped).length === 0;
 }
+function whenAbsent(config, source) {
+  return config.when !== void 0 && !isPresentForWhen(valueAtPath(source, config.when));
+}
 var PreviewTimeoutError = class extends Error {
 };
 function withTimeout(p, ms) {
@@ -4780,7 +5271,7 @@ async function readPreview(integrationManager2, integrationId, previewTool, args
     );
     const text = result.content?.[0]?.text;
     if (result.isError) {
-      return { status: "not_found", message: capText(text) };
+      return /^\s*Refused\b/i.test(text ?? "") ? { status: "refused", message: capText(text) } : { status: "not_found", message: capText(text) };
     }
     return {
       status: "ok",
@@ -4816,7 +5307,7 @@ function hashPreviewBody(body) {
   }
   return computeContentHash({ kind: "text", version: "1" }, body.text ?? "");
 }
-function isPlainRecord(v) {
+function isPlainRecord2(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function planPreviewReads(declaration, actionArgs) {
@@ -4828,13 +5319,16 @@ function planPreviewReads(declaration, actionArgs) {
       fields: config.fields,
       version: config.version,
       kind: config.kind,
-      argsMapping: config.args
+      argsMapping: config.args,
+      ...config.displayOnly ? { displayOnly: true } : {},
+      ...config.as ? { as: config.as } : {},
+      ...config.label ? { label: config.label } : {}
     };
     if (config.forEach) {
       const source = actionArgs[config.forEach];
       const list = Array.isArray(source) ? source : [];
       const capped = list.slice(0, MAX_FOREACH_ELEMENTS);
-      const elements = capped.filter(isPlainRecord).map((el) => ({ args: mapPreviewArgs(config, el) }));
+      const elements = capped.filter(isPlainRecord2).map((el) => config.when !== void 0 && !isPresentForWhen(valueAtPath(el, config.when)) ? { args: {}, skip: true } : { args: mapPreviewArgs(config, el) });
       return {
         ...base,
         forEach: config.forEach,
@@ -4842,6 +5336,9 @@ function planPreviewReads(declaration, actionArgs) {
         ...list.length > MAX_FOREACH_ELEMENTS ? { overflow: { shown: MAX_FOREACH_ELEMENTS, total: list.length } } : {}
       };
     }
+    if (config.when !== void 0 && !isPresentForWhen(valueAtPath(actionArgs, config.when))) {
+      return { ...base, args: {}, rawSource: actionArgs, noTarget: true };
+    }
     const mapped = mapPreviewArgs(config, actionArgs);
     return { ...base, args: mapped, rawSource: actionArgs, noTarget: previewHasNoTarget(config, mapped) };
   });
@@ -4855,12 +5352,15 @@ async function runPreviewReadPlan(integrationManager2, integrationId, plan) {
       ...item.attach ? { attach: item.attach } : {},
       ...sourceArgNames.length === 1 ? { sourceArg: sourceArgNames[0] } : {},
       ...item.fields ? { fields: item.fields } : {},
-      ...item.kind ? { kind: item.kind } : {}
+      ...item.kind ? { kind: item.kind } : {},
+      ...item.displayOnly ? { displayOnly: true } : {},
+      ...item.as ? { as: item.as } : {},
+      ...item.label ? { label: item.label } : {}
     };
     if (item.elements !== void 0) {
       const elements = [];
       for (const el of item.elements) {
-        elements.push(await readPreview(integrationManager2, integrationId, item.tool, el.args));
+        elements.push(el.skip ? { status: "none", reason: "no_target" } : await readPreview(integrationManager2, integrationId, item.tool, el.args));
       }
       sections.push({
         ...base,
@@ -4887,11 +5387,12 @@ async function runPreviewReadPlan(integrationManager2, integrationId, plan) {
     const { [item.version.arg]: _omit, ...withoutVersion } = item.rawSource;
     const mappedCurrentArgs = mapPreviewArgs({ args: item.argsMapping }, withoutVersion);
     const read2 = await readPreview(integrationManager2, integrationId, item.tool, mappedCurrentArgs);
-    if (read2.status !== "ok" || read2.body.structured === void 0) {
+    const current2 = read2.status === "ok" ? structuredOrJsonText(read2.body) : void 0;
+    if (current2 === void 0) {
       sections.push({ ...base, result: read1 });
       continue;
     }
-    const current = read2.body.structured[item.version.field];
+    const current = current2[item.version.field];
     if (typeof current !== "string" && typeof current !== "number") {
       sections.push({ ...base, result: read1 });
       continue;
@@ -4905,7 +5406,7 @@ async function runPreviewReadPlan(integrationManager2, integrationId, plan) {
         approved,
         current,
         stale,
-        ...stale ? { currentBody: read2.body } : {}
+        ...stale && read2.status === "ok" ? { currentBody: read2.body } : {}
       }
     });
   }
@@ -4916,9 +5417,9 @@ async function computeSubmissionPreviewHash(integrationManager2, integrationId,
   const preview = getToolPreviewConfig(integrationManager2, integrationId, toolName);
   if (!preview) return void 0;
   if (Array.isArray(preview)) return combinedPreviewReadsHash(integrationManager2, integrationId, preview, actionArgs);
-  if (preview.version) return void 0;
+  if (preview.version || preview.displayOnly) return void 0;
   const mapped = mapPreviewArgs(preview, actionArgs);
-  if (previewHasNoTarget(preview, mapped)) return void 0;
+  if (previewHasNoTarget(preview, mapped) || whenAbsent(preview, actionArgs)) return void 0;
   const read = await readPreview(integrationManager2, integrationId, preview.tool, mapped);
   if (read.status !== "ok") return void 0;
   return hashPreviewBody(read.body);
@@ -4937,11 +5438,12 @@ async function previewChangedSinceSubmission(integrationManager2, integrationId,
   return hashPreviewBody(read.body) !== previousHash;
 }
 async function combinedPreviewReadsHash(integrationManager2, integrationId, reads, actionArgs) {
-  const plan = planPreviewReads(reads, actionArgs).filter((item) => !item.version);
+  const plan = planPreviewReads(reads, actionArgs).filter((item) => !item.version && !item.displayOnly);
   const hashes = [];
   for (const item of plan) {
     if (item.elements !== void 0) {
       for (const el of item.elements) {
+        if (el.skip) continue;
         const read2 = await readPreview(integrationManager2, integrationId, item.tool, el.args);
         if (read2.status !== "ok") return void 0;
         hashes.push(hashPreviewBody(read2.body));
@@ -4957,6 +5459,32 @@ async function combinedPreviewReadsHash(integrationManager2, integrationId, read
   return computeContentHash({ kind: "jcs", version: "1" }, { reads: hashes });
 }
 async function buildInternalPreview(integrationManager2, integrationId, toolName, actionArgs) {
+  const result = await buildPreviewReads(integrationManager2, integrationId, toolName, actionArgs);
+  const checks = getToolChecks(integrationManager2, integrationId, toolName);
+  if (!checks || checks.length === 0) return result;
+  const display = getToolDisplayHints(integrationManager2, integrationId, toolName);
+  return {
+    ...result,
+    checks: evaluateChecks(checks, {
+      args: actionArgs,
+      declaration: getToolPreviewConfig(integrationManager2, integrationId, toolName),
+      sections: "reads" in result ? result.reads : void 0,
+      currencyField: display?.currencyField
+    })
+  };
+}
+async function failedBlockingChecks(integrationManager2, integrationId, toolName, actionArgs) {
+  const declared = getToolChecks(integrationManager2, integrationId, toolName);
+  if (!declared?.some((c) => c.blocking === true)) return [];
+  try {
+    const result = await buildInternalPreview(integrationManager2, integrationId, toolName, actionArgs);
+    return blockingFailures(result.checks ?? []);
+  } catch (err) {
+    console.error(`[Suveren MCP] blocking checks for ${integrationId}__${toolName} could not run:`, err);
+    return [];
+  }
+}
+async function buildPreviewReads(integrationManager2, integrationId, toolName, actionArgs) {
   const preview = getToolPreviewConfig(integrationManager2, integrationId, toolName);
   if (!preview) return { status: "none" };
   if (Array.isArray(preview)) {
@@ -4965,7 +5493,7 @@ async function buildInternalPreview(integrationManager2, integrationId, toolName
     return { status: "ok", integration: integrationId, reads, ...display ? { display } : {} };
   }
   const mappedArgs = mapPreviewArgs(preview, actionArgs);
-  if (previewHasNoTarget(preview, mappedArgs)) return { status: "none", reason: "no_target" };
+  if (previewHasNoTarget(preview, mappedArgs) || whenAbsent(preview, actionArgs)) return { status: "none", reason: "no_target" };
   const read1 = await readPreview(integrationManager2, integrationId, preview.tool, mappedArgs);
   if (read1.status !== "ok") return read1;
   const ok = (extra = {}) => ({
@@ -4986,10 +5514,11 @@ async function buildInternalPreview(integrationManager2, integrationId, toolName
   const { [preview.version.arg]: _omit, ...withoutVersion } = actionArgs;
   const mappedCurrentArgs = mapPreviewArgs(preview, withoutVersion);
   const read2 = await readPreview(integrationManager2, integrationId, preview.tool, mappedCurrentArgs);
-  if (read2.status !== "ok" || read2.body.structured === void 0) {
+  const current2 = read2.status === "ok" ? structuredOrJsonText(read2.body) : void 0;
+  if (current2 === void 0) {
     return ok();
   }
-  const current = read2.body.structured[preview.version.field];
+  const current = current2[preview.version.field];
   if (typeof current !== "string" && typeof current !== "number") {
     return ok();
   }
@@ -5000,7 +5529,7 @@ async function buildInternalPreview(integrationManager2, integrationId, toolName
       approved,
       current,
       stale,
-      ...stale ? { currentBody: read2.body } : {}
+      ...stale && read2.status === "ok" ? { currentBody: read2.body } : {}
     }
   });
 }
@@ -5190,7 +5719,7 @@ async function readContextRecord(integrationManager2, connectorId, tool, args) {
     if (record === void 0) return { status: "unavailable", reason: "connector_error" };
     return { status: "ok", record };
   }
-  if (read.status === "not_found") return { status: "not_found" };
+  if (read.status === "not_found" || read.status === "refused") return { status: "not_found" };
   return { status: "unavailable", reason: read.reason };
 }
 function parseExplicitSourceLink(raw) {
@@ -5466,7 +5995,7 @@ async function resolveDocumentReference(integrationManager2, ref) {
   }
   const args = substitute(docConfig.args, { id: ref.id });
   const read = await readPreview(integrationManager2, ref.connector, docConfig.tool, args);
-  if (read.status === "not_found") {
+  if (read.status === "not_found" || read.status === "refused") {
     return { ok: false, error: { code: "NOT_FOUND", message: read.message ?? `No document "${ref.kind}"/"${ref.id}" on "${ref.connector}".` } };
   }
   if (read.status !== "ok") {
@@ -5548,7 +6077,7 @@ async function resolveInsertValue(integrationManager2, ref) {
   }
   const args = substitute(valueConfig.args, { id: ref.id });
   const read = await readPreview(integrationManager2, ref.connector, valueConfig.tool, args);
-  if (read.status === "not_found") {
+  if (read.status === "not_found" || read.status === "refused") {
     return { ok: false, error: { code: "NOT_FOUND", message: read.message ?? `No value "${ref.kind}"/"${ref.id}" on "${ref.connector}".` } };
   }
   if (read.status !== "ok") {
@@ -6680,6 +7209,24 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
       return { content: [{ type: "text", text: noMandateRefusal(tool.namespacedName, mandateLabel) }], isError: true };
     }
     if (matchingAuths.length === 0) return noEligibleMandate(refusals);
+    const blockingFails = await failedBlockingChecks(integrationManager2, tool.integrationId, tool.originalName, args);
+    if (blockingFails.length > 0) {
+      recordBlocked(state2, tool, {
+        kind: "check",
+        // A sentence without content: the check's own label only.
+        detail: `Check failed: ${blockingFails.map((f) => f.label).join("; ")}.`,
+        field: blockingFails[0].key,
+        who: "gateway",
+        code: "CHECK_FAILED"
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `Refused: ${blockingRefusalReason(blockingFails)}. Nothing was proposed and nothing ran. This check reads the system's own data, so an approval cannot override it \u2014 correct the request (or the data in the system) and try again.`
+        }],
+        isError: true
+      };
+    }
     const errors = [];
     const passers = [];
     const structuredRefusals = [];