@suveren/gateway 0.27.2 → 0.28.1

package/content/integrations/crm.json

@@ -54,7 +54,17 @@
         "staticExecution": {
           "action_type": "write"
         },
-        "actionLabel": "Contact created"
+        "actionLabel": "Contact created",
+        "preview": [
+          { "tool": "find_contacts", "args": { "query": "email" } }
+        ],
+        "display": {
+          "order": ["name", "email", "company", "role", "type", "stage", "tags", "notes"],
+          "labels": {
+            "name": "Name", "email": "Email", "company": "Company", "role": "Role",
+            "type": "Type", "stage": "Stage", "tags": "Tags", "notes": "Notes"
+          }
+        }
       },
       "update_contact": {
         "executionMapping": {
@@ -330,7 +340,8 @@
           "action_type": "setup"
         },
         "actionLabel": "Test data loaded",
-        "hideUnlessAuthorized": true
+        "hideUnlessAuthorized": true,
+        "simulationOnly": true
       },
       "clear_simulation": {
         "executionMapping": {},
@@ -339,7 +350,8 @@
           "action_type": "setup"
         },
         "actionLabel": "Test data cleared",
-        "hideUnlessAuthorized": true
+        "hideUnlessAuthorized": true,
+        "simulationOnly": true
       }
     }
   },

package/content/integrations/erp.json

@@ -95,7 +95,29 @@
         "staticExecution": {
           "action_type": "quote"
         },
-        "actionLabel": "Quote drafted"
+        "actionLabel": "Quote drafted",
+        "preview": [
+          { "tool": "get_customer", "args": { "id": "customer_id" }, "attach": "customer_id" },
+          { "tool": "get_item", "forEach": "lines", "args": { "id": "item_id" }, "attach": "item" }
+        ],
+        "display": {
+          "order": ["customer_id", "lines", "discount_pct", "value", "valid_until", "notes"],
+          "money": ["value", "customer_id.credit_limit", "customer_id.open_balance", "customer_id.available_credit", "lines[].item.list_price"],
+          "percent": ["discount_pct"],
+          "currencyField": "currency",
+          "labels": {
+            "customer_id": "Customer",
+            "discount_pct": "Discount",
+            "value": "Total (net)",
+            "customer_id.credit_limit": "Credit limit",
+            "customer_id.open_balance": "Open balance",
+            "customer_id.available_credit": "Available credit",
+            "customer_id.payment_terms": "Payment terms",
+            "lines[].item": "Item",
+            "lines[].item.list_price": "List price",
+            "lines[].item.stock": "In stock"
+          }
+        }
       },
       "update_quote": {
         "executionMapping": {
@@ -106,7 +128,23 @@
         "staticExecution": {
           "action_type": "quote"
         },
-        "actionLabel": "Quote updated"
+        "actionLabel": "Quote updated",
+        "preview": [
+          { "tool": "get_item", "forEach": "lines", "args": { "id": "item_id" }, "attach": "item" }
+        ],
+        "display": {
+          "order": ["lines", "discount_pct", "value", "valid_until", "notes"],
+          "money": ["value", "lines[].item.list_price"],
+          "percent": ["discount_pct"],
+          "currencyField": "currency",
+          "labels": {
+            "discount_pct": "Discount",
+            "value": "Total (net)",
+            "lines[].item": "Item",
+            "lines[].item.list_price": "List price",
+            "lines[].item.stock": "In stock"
+          }
+        }
       },
       "send_quote": {
         "executionMapping": {
@@ -148,7 +186,8 @@
           "action_type": "setup"
         },
         "actionLabel": "Test data loaded",
-        "hideUnlessAuthorized": true
+        "hideUnlessAuthorized": true,
+        "simulationOnly": true
       },
       "clear_simulation": {
         "executionMapping": {},
@@ -156,7 +195,8 @@
           "action_type": "setup"
         },
         "actionLabel": "Test data cleared",
-        "hideUnlessAuthorized": true
+        "hideUnlessAuthorized": true,
+        "simulationOnly": true
       }
     }
   },

package/content/integrations/mail.json

@@ -83,7 +83,8 @@
           "action_type": "setup"
         },
         "actionLabel": "Test data loaded",
-        "hideUnlessAuthorized": true
+        "hideUnlessAuthorized": true,
+        "simulationOnly": true
       },
       "clear_simulation": {
         "executionMapping": {},
@@ -91,7 +92,8 @@
           "action_type": "setup"
         },
         "actionLabel": "Test data cleared",
-        "hideUnlessAuthorized": true
+        "hideUnlessAuthorized": true,
+        "simulationOnly": true
       }
     }
   },

package/dist/mcp-server/http.mjs

@@ -3469,6 +3469,12 @@ import { computeContentHash as computeContentHash2 } from "@hap/core";
 // src/lib/manifest-loader.ts
 import { readFileSync as readFileSync15, existsSync as existsSync14 } from "fs";
 import { join as join14, resolve } from "path";
+
+// src/lib/tool-gating-types.ts
+var MAX_PREVIEW_READS = 10;
+var MAX_FOREACH_ELEMENTS = 50;
+
+// src/lib/manifest-loader.ts
 var EXACT_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 function isExactSemver(value) {
   return typeof value === "string" && EXACT_SEMVER_RE.test(value);
@@ -3483,44 +3489,101 @@ function invalidNpmPinReason(manifest) {
   }
   return null;
 }
-function invalidPreviewReason(toolName, entry) {
-  if (entry === null || typeof entry !== "object") return null;
-  const preview = entry.preview;
-  if (preview === void 0) return null;
-  if (preview === null || typeof preview !== "object" || Array.isArray(preview)) {
-    return `override "${toolName}".preview must be an object`;
+function invalidReadConfigReason(toolName, idx, entry) {
+  const label = idx === null ? `override "${toolName}".preview` : `override "${toolName}".preview[${idx}]`;
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return `${label} must be an object`;
   }
-  const p = preview;
+  const p = entry;
   if (typeof p.tool !== "string" || p.tool.length === 0) {
-    return `override "${toolName}".preview.tool must be a non-empty string`;
+    return `${label}.tool must be a non-empty string`;
   }
   if (p.args === void 0 || p.args === null || typeof p.args !== "object" || Array.isArray(p.args)) {
-    return `override "${toolName}".preview.args must be an object mapping preview-tool arg names to action arg names`;
+    return `${label}.args must be an object mapping preview-tool arg names to action arg names`;
   }
   for (const [argName, source] of Object.entries(p.args)) {
     if (typeof source !== "string" || source.length === 0) {
-      return `override "${toolName}".preview.args.${argName} must name a non-empty source argument (string)`;
+      return `${label}.args.${argName} must name a non-empty source argument (string)`;
     }
   }
+  if (p.forEach !== void 0 && (typeof p.forEach !== "string" || p.forEach.length === 0)) {
+    return `${label}.forEach must be a non-empty string naming an action argument`;
+  }
+  if (p.attach !== void 0 && (typeof p.attach !== "string" || p.attach.length === 0)) {
+    return `${label}.attach must be a non-empty string`;
+  }
   if (p.version !== void 0) {
     if (p.version === null || typeof p.version !== "object" || Array.isArray(p.version)) {
-      return `override "${toolName}".preview.version must be an object`;
+      return `${label}.version must be an object`;
     }
     const v = p.version;
     if (typeof v.arg !== "string" || v.arg.length === 0) {
-      return `override "${toolName}".preview.version.arg must be a non-empty string`;
+      return `${label}.version.arg must be a non-empty string`;
     }
     if (typeof v.field !== "string" || v.field.length === 0) {
-      return `override "${toolName}".preview.version.field must be a non-empty string`;
+      return `${label}.version.field must be a non-empty string`;
     }
   }
   if (p.fields !== void 0) {
     if (!Array.isArray(p.fields)) {
-      return `override "${toolName}".preview.fields must be an array of field names`;
+      return `${label}.fields must be an array of field names`;
     }
     for (const [i, f] of p.fields.entries()) {
       if (typeof f !== "string" || f.length === 0) {
-        return `override "${toolName}".preview.fields[${i}] must be a non-empty string`;
+        return `${label}.fields[${i}] must be a non-empty string`;
+      }
+    }
+  }
+  return null;
+}
+function invalidPreviewReason(toolName, entry) {
+  if (entry === null || typeof entry !== "object") return null;
+  const preview = entry.preview;
+  if (preview === void 0) return null;
+  if (Array.isArray(preview)) {
+    if (preview.length === 0) {
+      return `override "${toolName}".preview must not be an empty list \u2014 omit it, or use the single-object form`;
+    }
+    if (preview.length > MAX_PREVIEW_READS) {
+      return `override "${toolName}".preview declares ${preview.length} reads \u2014 max ${MAX_PREVIEW_READS}`;
+    }
+    for (const [i, read] of preview.entries()) {
+      const reason = invalidReadConfigReason(toolName, i, read);
+      if (reason) return reason;
+    }
+    return null;
+  }
+  return invalidReadConfigReason(toolName, null, preview);
+}
+function invalidDisplayHintsReason(toolName, entry) {
+  if (entry === null || typeof entry !== "object") return null;
+  const display = entry.display;
+  if (display === void 0) return null;
+  if (display === null || typeof display !== "object" || Array.isArray(display)) {
+    return `override "${toolName}".display must be an object`;
+  }
+  const d = display;
+  for (const key of ["order", "money", "percent", "hidden"]) {
+    if (d[key] === void 0) continue;
+    if (!Array.isArray(d[key])) {
+      return `override "${toolName}".display.${key} must be an array of field paths`;
+    }
+    for (const [i, v] of d[key].entries()) {
+      if (typeof v !== "string" || v.length === 0) {
+        return `override "${toolName}".display.${key}[${i}] must be a non-empty string`;
+      }
+    }
+  }
+  if (d.currencyField !== void 0 && (typeof d.currencyField !== "string" || d.currencyField.length === 0)) {
+    return `override "${toolName}".display.currencyField must be a non-empty string`;
+  }
+  if (d.labels !== void 0) {
+    if (d.labels === null || typeof d.labels !== "object" || Array.isArray(d.labels)) {
+      return `override "${toolName}".display.labels must be an object mapping field paths to labels`;
+    }
+    for (const [path, label] of Object.entries(d.labels)) {
+      if (typeof label !== "string" || label.length === 0) {
+        return `override "${toolName}".display.labels.${path} must be a non-empty string`;
       }
     }
   }
@@ -3529,7 +3592,7 @@ function invalidPreviewReason(toolName, entry) {
 function invalidManifestPreviewReason(manifest) {
   const overrides = manifest.toolGating?.overrides ?? {};
   for (const [toolName, entry] of Object.entries(overrides)) {
-    const reason = invalidPreviewReason(toolName, entry);
+    const reason = invalidPreviewReason(toolName, entry) ?? invalidDisplayHintsReason(toolName, entry);
     if (reason) return reason;
   }
   return null;
@@ -3598,6 +3661,13 @@ function getToolPreviewConfig(integrationManager2, integrationId, toolName) {
   const entry = overrides[toolName];
   return entry?.preview;
 }
+function getToolDisplayHints(integrationManager2, integrationId, toolName) {
+  if (integrationManager2.isBuiltin(integrationId)) return void 0;
+  const manifest = getManifest(integrationId);
+  const overrides = manifest?.toolGating?.overrides ?? {};
+  const entry = overrides[toolName];
+  return entry?.display;
+}
 function mapPreviewArgs(preview, actionArgs) {
   const mapped = {};
   for (const [targetArg, sourceArg] of Object.entries(preview.args)) {
@@ -3656,10 +3726,105 @@ function hashPreviewBody(body) {
   }
   return computeContentHash2({ kind: "text", version: "1" }, body.text ?? "");
 }
+function isPlainRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function planPreviewReads(declaration, actionArgs) {
+  const reads = Array.isArray(declaration) ? declaration : [declaration];
+  return reads.map((config) => {
+    const base = {
+      tool: config.tool,
+      attach: config.attach,
+      fields: config.fields,
+      version: config.version,
+      argsMapping: config.args
+    };
+    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) }));
+      return {
+        ...base,
+        forEach: config.forEach,
+        elements,
+        ...list.length > MAX_FOREACH_ELEMENTS ? { overflow: { shown: MAX_FOREACH_ELEMENTS, total: list.length } } : {}
+      };
+    }
+    const mapped = mapPreviewArgs(config, actionArgs);
+    return { ...base, args: mapped, rawSource: actionArgs, noTarget: previewHasNoTarget(config, mapped) };
+  });
+}
+async function runPreviewReadPlan(integrationManager2, integrationId, plan) {
+  const sections = [];
+  for (const item of plan) {
+    const sourceArgNames = Object.values(item.argsMapping);
+    const base = {
+      tool: item.tool,
+      ...item.attach ? { attach: item.attach } : {},
+      ...sourceArgNames.length === 1 ? { sourceArg: sourceArgNames[0] } : {},
+      ...item.fields ? { fields: item.fields } : {}
+    };
+    if (item.elements !== void 0) {
+      const elements = [];
+      for (const el of item.elements) {
+        elements.push(await readPreview(integrationManager2, integrationId, item.tool, el.args));
+      }
+      sections.push({
+        ...base,
+        forEach: item.forEach,
+        elements,
+        ...item.overflow ? { overflow: item.overflow } : {}
+      });
+      continue;
+    }
+    if (item.noTarget) {
+      sections.push({ ...base, result: { status: "none", reason: "no_target" } });
+      continue;
+    }
+    const read1 = await readPreview(integrationManager2, integrationId, item.tool, item.args);
+    if (read1.status !== "ok" || !item.version) {
+      sections.push({ ...base, result: read1 });
+      continue;
+    }
+    const approved = item.rawSource?.[item.version.arg];
+    if (typeof approved !== "string" && typeof approved !== "number") {
+      sections.push({ ...base, result: read1 });
+      continue;
+    }
+    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) {
+      sections.push({ ...base, result: read1 });
+      continue;
+    }
+    const current = read2.body.structured[item.version.field];
+    if (typeof current !== "string" && typeof current !== "number") {
+      sections.push({ ...base, result: read1 });
+      continue;
+    }
+    const stale = String(current) !== String(approved);
+    sections.push({
+      ...base,
+      result: read1,
+      version: {
+        field: item.version.field,
+        approved,
+        current,
+        stale,
+        ...stale ? { currentBody: read2.body } : {}
+      }
+    });
+  }
+  return sections;
+}
 async function computeSubmissionPreviewHash(integrationManager2, integrationId, toolName, actionArgs) {
   if (integrationManager2.isBuiltin(integrationId)) return void 0;
   const preview = getToolPreviewConfig(integrationManager2, integrationId, toolName);
-  if (!preview || preview.version) return void 0;
+  if (!preview) return void 0;
+  if (Array.isArray(preview)) return combinedPreviewReadsHash(integrationManager2, integrationId, preview, actionArgs);
+  if (preview.version) return void 0;
   const mapped = mapPreviewArgs(preview, actionArgs);
   if (previewHasNoTarget(preview, mapped)) return void 0;
   const read = await readPreview(integrationManager2, integrationId, preview.tool, mapped);
@@ -3669,14 +3834,44 @@ async function computeSubmissionPreviewHash(integrationManager2, integrationId,
 async function previewChangedSinceSubmission(integrationManager2, integrationId, toolName, actionArgs, previousHash) {
   const preview = getToolPreviewConfig(integrationManager2, integrationId, toolName);
   if (!preview) return true;
+  if (Array.isArray(preview)) {
+    const hash = await combinedPreviewReadsHash(integrationManager2, integrationId, preview, actionArgs);
+    if (hash === void 0) return true;
+    return hash !== previousHash;
+  }
   const mapped = mapPreviewArgs(preview, actionArgs);
   const read = await readPreview(integrationManager2, integrationId, preview.tool, mapped);
   if (read.status !== "ok") return true;
   return hashPreviewBody(read.body) !== previousHash;
 }
+async function combinedPreviewReadsHash(integrationManager2, integrationId, reads, actionArgs) {
+  const plan = planPreviewReads(reads, actionArgs).filter((item) => !item.version);
+  const hashes = [];
+  for (const item of plan) {
+    if (item.elements !== void 0) {
+      for (const el of item.elements) {
+        const read2 = await readPreview(integrationManager2, integrationId, item.tool, el.args);
+        if (read2.status !== "ok") return void 0;
+        hashes.push(hashPreviewBody(read2.body));
+      }
+      continue;
+    }
+    if (item.noTarget) continue;
+    const read = await readPreview(integrationManager2, integrationId, item.tool, item.args);
+    if (read.status !== "ok") return void 0;
+    hashes.push(hashPreviewBody(read.body));
+  }
+  if (hashes.length === 0) return void 0;
+  return computeContentHash2({ kind: "jcs", version: "1" }, { reads: hashes });
+}
 async function buildInternalPreview(integrationManager2, integrationId, toolName, actionArgs) {
   const preview = getToolPreviewConfig(integrationManager2, integrationId, toolName);
   if (!preview) return { status: "none" };
+  if (Array.isArray(preview)) {
+    const reads = await runPreviewReadPlan(integrationManager2, integrationId, planPreviewReads(preview, actionArgs));
+    const display = getToolDisplayHints(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" };
   const read1 = await readPreview(integrationManager2, integrationId, preview.tool, mappedArgs);
@@ -4214,8 +4409,10 @@ function zeroCappedBound(profileId, bounds, actionType) {
 }
 function toolAlwaysListed(tool, isBuiltin) {
   if (tool.internal || !tool.gating?.profile) return false;
-  if (tool.gating.hideUnlessAuthorized || tool.gating.category === "disabled") return false;
-  return !isBuiltin(tool.integrationId);
+  if (tool.gating.category === "disabled") return false;
+  if (isBuiltin(tool.integrationId)) return false;
+  if (!tool.gating.hideUnlessAuthorized) return true;
+  return Boolean(tool.gating.simulationOnly) && isSimulationMode();
 }
 function toolIsAuthorizedForDisplay(tool, matchingAuths) {
   if (!tool.gating?.hideUnlessAuthorized) return true;
@@ -4631,6 +4828,18 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
       }
     }
     const { matching: matchingAuths, refusals } = eligibleMandates();
+    if (tool.gating?.simulationOnly && isSimulationMode() && !toolIsAuthorizedForDisplay(tool, matchingAuths)) {
+      const actionType = staticExecution?.action_type;
+      const mandateLabel = typeof actionType === "string" ? actionType : profile;
+      recordBlocked(state2, tool, {
+        kind: "not_authorized",
+        detail: `No active authorization grants "${mandateLabel}" under profile "${profile}".`,
+        field: mandateLabel,
+        who: "gateway",
+        code: "NO_MATCHING_MANDATE"
+      });
+      return { content: [{ type: "text", text: noMandateRefusal(tool.namespacedName, mandateLabel) }], isError: true };
+    }
     if (matchingAuths.length === 0) return noEligibleMandate(refusals);
     const errors = [];
     const passers = [];
@@ -7298,6 +7507,7 @@ var IntegrationManager = class {
           readGovernanceReason: ext.readGovernanceReason,
           blockedArgs: ext.blockedArgs,
           hideUnlessAuthorized: ext.hideUnlessAuthorized,
+          simulationOnly: ext.simulationOnly,
           approvalView: ext.approvalView
         };
       }
@@ -7314,6 +7524,7 @@ var IntegrationManager = class {
         argEncoding: ext.argEncoding,
         argNormalization: ext.argNormalization,
         hideUnlessAuthorized: ext.hideUnlessAuthorized,
+        simulationOnly: ext.simulationOnly,
         approvalView: ext.approvalView
       };
     }