@suveren/gateway 0.34.0 → 0.35.1

package/dist/mcp-server/http.mjs

@@ -3411,7 +3411,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z2 } from "zod";
 
 // src/lib/mandate-brief.ts
-import { getProfile as getProfile5 } from "@hap/core";
+import { getProfile as getProfile6 } from "@hap/core";
 
 // src/lib/consumption.ts
 import { boundActionTypes } from "@hap/core";
@@ -3530,8 +3530,11 @@ function isSimulationMode() {
   if (policySimulation !== void 0) return policySimulation;
   return process.env.SUVEREN_SIMULATION === "1";
 }
-function manifestIsSimulated(manifest) {
-  return Boolean(manifest?.simulation);
+function connectorCurrentlySimulated(manifest, fields) {
+  const decl = manifest?.simulation;
+  if (!decl) return false;
+  const value = (fields?.[decl.field] ?? "").trim().toLowerCase() || decl.default.trim().toLowerCase();
+  return value === "simulation";
 }
 var SIMULATION_BLOCK_REASON = "blocked: simulation mode \u2014 real systems are off";
 
@@ -3647,67 +3650,17 @@ function appendVerificationFooter(tool, args, receiptId, subject) {
 
 // src/lib/content-binding.ts
 import {
-  computeContentHash,
+  computeContentHash as computeContentHash2,
   selectBoundFields,
   isFieldBinding,
   bindingAppliesTo,
-  getProfile
+  getProfile as getProfile3
 } from "@hap/core";
-function getContentBinding(profileId) {
-  return getProfile(profileId)?.content_binding;
-}
-function computeContentBinding(profileId, tool, toolArgs, actionType) {
-  const binding = getContentBinding(profileId);
-  if (!binding) return void 0;
-  if (isFieldBinding(binding)) {
-    if (!bindingAppliesTo(binding, actionType)) {
-      if (!actionType && binding.appliesTo) {
-        console.error(
-          `[Suveren MCP] Warning: ${tool?.namespacedName ?? profileId} has no action_type in staticExecution, so the ${profileId} content binding (${binding.appliesTo.join(", ")}) does not apply and the receipt will bind no content. Fix the integration manifest.`
-        );
-      }
-      return void 0;
-    }
-    const bound = selectBoundFields(binding, toolArgs);
-    return {
-      contentHash: computeContentHash(binding, bound),
-      contentBinding: { version: binding.version, kind: binding.kind, fields: binding.fields },
-      boundContent: bound
-    };
-  }
-  let contentHash;
-  let boundContent;
-  if (binding.kind === "jcs") {
-    contentHash = computeContentHash(binding, toolArgs);
-    boundContent = toolArgs;
-  } else {
-    const declared = tool?.gating?.contentField;
-    const field = declared ?? (tool ? detectContentField(tool) : null);
-    if (!field) return void 0;
-    const raw = typeof toolArgs[field] === "string" ? toolArgs[field] : "";
-    if (raw === "") return void 0;
-    contentHash = computeContentHash(binding, raw);
-    boundContent = raw;
-  }
-  return {
-    contentHash,
-    contentBinding: { version: binding.version, kind: binding.kind },
-    boundContent
-  };
-}
-function attachTicketId(tool, args, ticketId) {
-  const schema = tool.inputSchema;
-  if (!schema?.properties || !("ticket_id" in schema.properties)) return args;
-  return { ...args, ticket_id: ticketId };
-}
-
-// src/lib/preview.ts
-import { computeContentHash as computeContentHash2 } from "@hap/core";
 
 // src/lib/manifest-loader.ts
 import { readFileSync as readFileSync16, existsSync as existsSync15 } from "fs";
 import { join as join15, resolve } from "path";
-import { getProfile as getProfile2 } from "@hap/core";
+import { getProfile } from "@hap/core";
 
 // src/lib/tool-gating-types.ts
 var MAX_PREVIEW_READS = 10;
@@ -3765,6 +3718,7 @@ function boundsSatisfyReadGate(bounds, gate) {
 }
 function readToolIsGoverned(g) {
   if (!g) return false;
+  if (g.internal === true) return true;
   return Boolean(g.boundField) || g.read != null || g.readGovernance === "none";
 }
 function allowedResources(contexts, boundField) {
@@ -3888,6 +3842,7 @@ function uncoveredReadSwitchReason(overrides, boundsSchema) {
     if (entry !== null && typeof entry !== "object") continue;
     const e = entry ?? {};
     if (entry !== null && e.category !== "read") continue;
+    if (e.internal === true) continue;
     if (e.readGovernance === "none") {
       if (!e.readGovernanceReason) {
         return `override "${toolName}" declares readGovernance:"none" with no readGovernanceReason \u2014 an exemption from this profile's switch(es) [${anySwitch.join(", ")}] needs a written reason`;
@@ -3994,6 +3949,9 @@ function invalidReadConfigReason(toolName, idx, entry) {
       }
     }
   }
+  if (p.kind !== void 0 && p.kind !== "document") {
+    return `${label}.kind must be "document" (the only recognized value)`;
+  }
   return null;
 }
 function invalidPreviewReason(toolName, entry) {
@@ -4047,6 +4005,9 @@ function invalidDisplayHintsReason(toolName, entry) {
       }
     }
   }
+  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"];
@@ -4083,6 +4044,21 @@ function invalidSummaryReason(toolName, entry) {
   }
   return null;
 }
+function invalidInternalReason(toolName, entry) {
+  if (entry === null || typeof entry !== "object") return null;
+  const internal = entry.internal;
+  if (internal === void 0) return null;
+  if (typeof internal !== "boolean") return `override "${toolName}".internal must be a boolean`;
+  return null;
+}
+function invalidManifestInternalReason(manifest) {
+  const overrides = manifest.toolGating?.overrides ?? {};
+  for (const [toolName, entry] of Object.entries(overrides)) {
+    const reason = invalidInternalReason(toolName, entry);
+    if (reason) return reason;
+  }
+  return null;
+}
 function invalidManifestPreviewReason(manifest) {
   const overrides = manifest.toolGating?.overrides ?? {};
   for (const [toolName, entry] of Object.entries(overrides)) {
@@ -4316,6 +4292,92 @@ function invalidManifestContextReason(manifest) {
   }
   return null;
 }
+function invalidDocumentSourceReason(kind, entry, overrides) {
+  const label = `documents.${kind}`;
+  const readReason = invalidContextReadReason(label, entry);
+  if (readReason) return readReason;
+  const tool = entry.tool;
+  const toolEntry = overrides[tool];
+  if (toolEntry?.internal !== true) {
+    return `${label}.tool "${tool}" must be marked "internal: true" on this manifest's toolGating.overrides \u2014 a document read must never be directly callable by the AI`;
+  }
+  const docLabel = entry.label;
+  if (docLabel !== void 0 && (typeof docLabel !== "string" || docLabel.length === 0)) {
+    return `${label}.label must be a non-empty string`;
+  }
+  return null;
+}
+function invalidAttachmentTransportReason(entry) {
+  const label = "attachments";
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return `${label} must be an object`;
+  const a = entry;
+  if (a.transport !== "field" && a.transport !== "mime-raw") {
+    return `${label}.transport must be "field" or "mime-raw"`;
+  }
+  if (!isNonEmptyString(a.arg)) return `${label}.arg must be a non-empty string`;
+  return null;
+}
+function invalidInsertValueSourceReason(kind, entry) {
+  const label = `values.${kind}`;
+  const readReason = invalidContextReadReason(label, entry);
+  if (readReason) return readReason;
+  const v = entry;
+  if (!isNonEmptyString(v.path)) return `${label}.path must be a non-empty string`;
+  if (!Array.isArray(v.allowedHosts) || v.allowedHosts.length === 0) {
+    return `${label}.allowedHosts must be a non-empty array of hostnames`;
+  }
+  for (const [i, h] of v.allowedHosts.entries()) {
+    if (typeof h !== "string" || h.length === 0) return `${label}.allowedHosts[${i}] must be a non-empty string`;
+  }
+  return null;
+}
+function invalidManifestDocumentsReason(manifest) {
+  if (!manifest.documents) return null;
+  const overrides = manifest.toolGating?.overrides ?? {};
+  for (const [kind, entry] of Object.entries(manifest.documents)) {
+    const reason = invalidDocumentSourceReason(kind, entry, overrides);
+    if (reason) return reason;
+  }
+  return null;
+}
+function invalidManifestAttachmentsReason(manifest) {
+  if (manifest.attachments !== void 0) {
+    const reason = invalidAttachmentTransportReason(manifest.attachments);
+    if (reason) return reason;
+  }
+  const overrides = manifest.toolGating?.overrides ?? {};
+  for (const [toolName, entry] of Object.entries(overrides)) {
+    if (entry === null || typeof entry !== "object") continue;
+    const e = entry;
+    if (e.attachmentsArg !== void 0) {
+      if (typeof e.attachmentsArg !== "string" || e.attachmentsArg.length === 0) {
+        return `override "${toolName}".attachmentsArg must be a non-empty string`;
+      }
+      if (!manifest.attachments) {
+        return `override "${toolName}" declares "attachmentsArg" but this manifest declares no top-level "attachments" transport`;
+      }
+    }
+    if (e.insertFields !== void 0) {
+      if (!Array.isArray(e.insertFields) || e.insertFields.length === 0) {
+        return `override "${toolName}".insertFields must be a non-empty array of argument names`;
+      }
+      for (const [i, f] of e.insertFields.entries()) {
+        if (typeof f !== "string" || f.length === 0) {
+          return `override "${toolName}".insertFields[${i}] must be a non-empty string`;
+        }
+      }
+    }
+  }
+  return null;
+}
+function invalidManifestValuesReason(manifest) {
+  if (!manifest.values) return null;
+  for (const [kind, entry] of Object.entries(manifest.values)) {
+    const reason = invalidInsertValueSourceReason(kind, entry);
+    if (reason) return reason;
+  }
+  return null;
+}
 function overrideProfile(entry) {
   if (entry === null || typeof entry !== "object") return void 0;
   const p = entry.profile;
@@ -4334,8 +4396,8 @@ function invalidManifestOverrideProfilesReason(manifest) {
   for (const [toolName, entry] of Object.entries(overrides)) {
     const profile = overrideProfile(entry);
     if (!profile) continue;
-    if (!getProfile2(manifest.profile) && !getProfile2(profile)) continue;
-    if (!getProfile2(profile)) {
+    if (!getProfile(manifest.profile) && !getProfile(profile)) continue;
+    if (!getProfile(profile)) {
       return `override "${toolName}".profile "${profile}" does not resolve to a known profile (full id or short name) \u2014 area-per-tool overrides must name a real profile, same as the manifest's own "profile"`;
     }
   }
@@ -4344,7 +4406,7 @@ function invalidManifestOverrideProfilesReason(manifest) {
 function invalidManifestReadGateReason(manifest) {
   const allOverrides = manifest.toolGating?.overrides ?? {};
   for (const profileId of distinctProfilesOf(manifest)) {
-    const profileDef = getProfile2(profileId);
+    const profileDef = getProfile(profileId);
     if (!profileDef) continue;
     const ownOverrides = {};
     for (const [toolName, entry] of Object.entries(allOverrides)) {
@@ -4356,6 +4418,39 @@ function invalidManifestReadGateReason(manifest) {
   }
   return null;
 }
+function invalidModeLabelsReason(manifest) {
+  if (!manifest.modeLabels) return null;
+  if (manifest.modeLabels === null || typeof manifest.modeLabels !== "object" || Array.isArray(manifest.modeLabels)) {
+    return "modeLabels must be an object mapping mode values to labels";
+  }
+  if (!manifest.simulation) {
+    return 'modeLabels is set but this manifest declares no "simulation" marker \u2014 mode labels need a mode field to key off';
+  }
+  const fieldKeys = new Set(manifest.credentials?.fields?.map((f) => f.key) ?? []);
+  let needsAdapterField = false;
+  for (const [mode, label] of Object.entries(manifest.modeLabels)) {
+    if (typeof label === "string") {
+      if (label.length === 0) return `modeLabels.${mode} must be a non-empty string`;
+      continue;
+    }
+    if (label === null || typeof label !== "object" || Array.isArray(label)) {
+      return `modeLabels.${mode} must be a non-empty string or an object keyed by adapter value`;
+    }
+    needsAdapterField = true;
+    for (const [adapter, adapterLabel] of Object.entries(label)) {
+      if (typeof adapterLabel !== "string" || adapterLabel.length === 0) {
+        return `modeLabels.${mode}.${adapter} must be a non-empty string`;
+      }
+    }
+  }
+  if (needsAdapterField && !manifest.adapterField) {
+    return 'modeLabels has an adapter-keyed entry but "adapterField" is missing \u2014 name the credential field holding the adapter';
+  }
+  if (manifest.adapterField && !fieldKeys.has(manifest.adapterField)) {
+    return `adapterField "${manifest.adapterField}" does not name a declared credential field`;
+  }
+  return null;
+}
 var manifests = /* @__PURE__ */ new Map();
 function loadManifests(integrationsDir) {
   const dir = resolve(
@@ -4388,6 +4483,11 @@ function loadManifests(integrationsDir) {
         console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${previewReason}`);
         continue;
       }
+      const internalReason = invalidManifestInternalReason(manifest);
+      if (internalReason) {
+        console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${internalReason}`);
+        continue;
+      }
       const contextReason = invalidManifestContextReason(manifest);
       if (contextReason) {
         console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${contextReason}`);
@@ -4403,6 +4503,26 @@ function loadManifests(integrationsDir) {
         console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${readGateReason}`);
         continue;
       }
+      const documentsReason = invalidManifestDocumentsReason(manifest);
+      if (documentsReason) {
+        console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${documentsReason}`);
+        continue;
+      }
+      const attachmentsReason = invalidManifestAttachmentsReason(manifest);
+      if (attachmentsReason) {
+        console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${attachmentsReason}`);
+        continue;
+      }
+      const valuesReason = invalidManifestValuesReason(manifest);
+      if (valuesReason) {
+        console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${valuesReason}`);
+        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}`);
+        continue;
+      }
       manifests.set(id, manifest);
       loaded++;
     } catch (err) {
@@ -4419,7 +4539,154 @@ function getAllManifests() {
   return Array.from(manifests.values());
 }
 
+// src/lib/attachment-resolution.ts
+import { getProfile as getProfile2 } from "@hap/core";
+
+// src/lib/attachment-reference.ts
+var REF_KEYS = ["connector", "kind", "id"];
+var INSERT_KEYS = ["placeholder", "connector", "kind", "id"];
+var ATTACHMENT_REFERENCE_SCHEMA = {
+  type: "object",
+  description: "A reference to a document already known to a connector \u2014 never file bytes. The gateway fetches, shows, and seals the file; it is never carried here.",
+  properties: {
+    connector: { type: "string", description: 'The integration id that can provide this document (e.g. "erp").' },
+    kind: { type: "string", description: 'The document kind that connector declares (e.g. "invoice-pdf").' },
+    id: { type: "string", description: "The id of the specific record (e.g. the invoice id)." }
+  },
+  required: ["connector", "kind", "id"],
+  additionalProperties: false
+};
+var INSERT_REFERENCE_SCHEMA = {
+  type: "object",
+  description: "A value read from another system to insert into this text \u2014 never typed here. The gateway reads it, checks its source, and replaces the placeholder before sending.",
+  properties: {
+    placeholder: { type: "string", description: "The exact {{placeholder}} token in the text to replace." },
+    connector: { type: "string", description: 'The integration id that can provide this value (e.g. "mollie").' },
+    kind: { type: "string", description: 'The value kind that connector declares (e.g. "payment-link").' },
+    id: { type: "string", description: "The id of the specific record (e.g. the payment link id)." }
+  },
+  required: ["placeholder", "connector", "kind", "id"],
+  additionalProperties: false
+};
+function withAttachmentAndInsertSchema(schema, gating) {
+  if (!gating?.attachmentsArg && !gating?.insertFields?.length) return schema;
+  const props = { ...schema.properties ?? {} };
+  if (gating.attachmentsArg) {
+    props[gating.attachmentsArg] = {
+      type: "array",
+      description: "Attachments by reference only \u2014 see items.",
+      items: ATTACHMENT_REFERENCE_SCHEMA
+    };
+  }
+  if (gating.insertFields?.length) {
+    props.insert = {
+      type: "array",
+      description: "Values to insert into this call\u2019s text by reference only \u2014 see items.",
+      items: INSERT_REFERENCE_SCHEMA
+    };
+  }
+  return { ...schema, properties: props };
+}
+function validateOne(value, index, keys) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      error: { code: "NOT_AN_OBJECT", index, message: `item ${index} must be an object with exactly ${keys.join(", ")}` }
+    };
+  }
+  const obj = value;
+  const extra = Object.keys(obj).filter((k) => !keys.includes(k));
+  if (extra.length > 0) {
+    return {
+      ok: false,
+      error: {
+        code: "EXTRA_FIELD",
+        index,
+        field: extra[0],
+        message: `item ${index} carries "${extra[0]}", which this reference does not accept. Only ${keys.join(", ")} are allowed \u2014 a reference never carries file bytes or a typed value.`
+      }
+    };
+  }
+  for (const k of keys) {
+    if (typeof obj[k] !== "string" || obj[k].length === 0) {
+      return {
+        ok: false,
+        error: { code: "MISSING_FIELD", index, field: k, message: `item ${index}.${k} must be a non-empty string` }
+      };
+    }
+  }
+  return { ok: true, value: obj };
+}
+function validateDocumentReferences(value) {
+  if (value === void 0) return { ok: true, refs: [] };
+  if (!Array.isArray(value)) {
+    return { ok: false, error: { code: "NOT_AN_ARRAY", message: "attachments must be an array of references" } };
+  }
+  const refs = [];
+  for (let i = 0; i < value.length; i++) {
+    const r = validateOne(value[i], i, REF_KEYS);
+    if (!r.ok) return r;
+    refs.push(r.value);
+  }
+  return { ok: true, refs };
+}
+function validateInsertReferences(value) {
+  if (value === void 0) return { ok: true, refs: [] };
+  if (!Array.isArray(value)) {
+    return { ok: false, error: { code: "NOT_AN_ARRAY", message: "insert must be an array of references" } };
+  }
+  const refs = [];
+  for (let i = 0; i < value.length; i++) {
+    const r = validateOne(value[i], i, INSERT_KEYS);
+    if (!r.ok) return r;
+    refs.push(r.value);
+  }
+  return { ok: true, refs };
+}
+
+// src/lib/attachment-policy.ts
+var ATTACHMENT_SOURCES_FIELD = "allowed_attachment_sources";
+function attachmentSourcesFieldDeclared(profile) {
+  return !!profile?.scopeSchema?.fields?.[ATTACHMENT_SOURCES_FIELD];
+}
+function isAttachmentSourceAllowed(profileId, profile, allowedSourcesValue, ref) {
+  if (!attachmentSourcesFieldDeclared(profile)) {
+    return {
+      allowed: false,
+      reason: `Profile "${profileId}" does not yet declare "${ATTACHMENT_SOURCES_FIELD}" \u2014 no mandate can authorize an attachment \u2014 a mandate on a newer email profile that lists the source is needed.`
+    };
+  }
+  const allowedSet = new Set(
+    (allowedSourcesValue ?? "").split(",").map((s) => s.trim()).filter(Boolean)
+  );
+  const key = `${ref.connector}:${ref.kind}`;
+  if (!allowedSet.has(key)) {
+    return {
+      allowed: false,
+      reason: `"${key}" is not in this mandate's "${ATTACHMENT_SOURCES_FIELD}" (${allowedSourcesValue || "(none)"}).`
+    };
+  }
+  return { allowed: true, reason: "" };
+}
+function candidatesAllowingAttachments(candidates, refs, profileOf) {
+  if (refs.length === 0) return { allowed: candidates };
+  let refusal;
+  const allowed = candidates.filter((c) => {
+    const value = typeof c.context?.[ATTACHMENT_SOURCES_FIELD] === "string" ? c.context[ATTACHMENT_SOURCES_FIELD] : void 0;
+    for (const ref of refs) {
+      const check = isAttachmentSourceAllowed(c.profileId, profileOf(c.profileId), value, ref);
+      if (!check.allowed) {
+        refusal ??= check.reason;
+        return false;
+      }
+    }
+    return true;
+  });
+  return { allowed, refusal: allowed.length ? void 0 : refusal };
+}
+
 // src/lib/preview.ts
+import { computeContentHash } from "@hap/core";
 var PREVIEW_READ_TIMEOUT_MS = 5e3;
 var PREVIEW_MESSAGE_CAP = 500;
 function capText(text, max = PREVIEW_MESSAGE_CAP) {
@@ -4496,9 +4763,9 @@ async function readPreview(integrationManager2, integrationId, previewTool, args
 }
 function hashPreviewBody(body) {
   if (body.structured !== void 0) {
-    return computeContentHash2({ kind: "jcs", version: "1" }, body.structured);
+    return computeContentHash({ kind: "jcs", version: "1" }, body.structured);
   }
-  return computeContentHash2({ kind: "text", version: "1" }, body.text ?? "");
+  return computeContentHash({ kind: "text", version: "1" }, body.text ?? "");
 }
 function isPlainRecord(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -4511,6 +4778,7 @@ function planPreviewReads(declaration, actionArgs) {
       attach: config.attach,
       fields: config.fields,
       version: config.version,
+      kind: config.kind,
       argsMapping: config.args
     };
     if (config.forEach) {
@@ -4537,7 +4805,8 @@ async function runPreviewReadPlan(integrationManager2, integrationId, plan) {
       tool: item.tool,
       ...item.attach ? { attach: item.attach } : {},
       ...sourceArgNames.length === 1 ? { sourceArg: sourceArgNames[0] } : {},
-      ...item.fields ? { fields: item.fields } : {}
+      ...item.fields ? { fields: item.fields } : {},
+      ...item.kind ? { kind: item.kind } : {}
     };
     if (item.elements !== void 0) {
       const elements = [];
@@ -4636,7 +4905,7 @@ async function combinedPreviewReadsHash(integrationManager2, integrationId, read
     hashes.push(hashPreviewBody(read.body));
   }
   if (hashes.length === 0) return void 0;
-  return computeContentHash2({ kind: "jcs", version: "1" }, { reads: hashes });
+  return computeContentHash({ kind: "jcs", version: "1" }, { reads: hashes });
 }
 async function buildInternalPreview(integrationManager2, integrationId, toolName, actionArgs) {
   const preview = getToolPreviewConfig(integrationManager2, integrationId, toolName);
@@ -4686,6 +4955,20 @@ async function buildInternalPreview(integrationManager2, integrationId, toolName
     }
   });
 }
+function structuredOrJsonText(body) {
+  if (body.structured && typeof body.structured === "object") return body.structured;
+  const t = body.text?.trim();
+  if (!t || !t.startsWith("{")) return void 0;
+  try {
+    const parsed = JSON.parse(t);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/lib/document-source.ts
+import { createHash as createHash3 } from "crypto";
 
 // src/lib/field-path.ts
 function matchesWhere(element, where) {
@@ -5103,6 +5386,447 @@ async function buildRequestContext(integrationManager2, executionJournal, action
   return { request, history };
 }
 
+// src/lib/document-source.ts
+function sha256Hex(buf) {
+  return createHash3("sha256").update(buf).digest("hex");
+}
+async function resolveDocumentReference(integrationManager2, ref) {
+  const manifest = getManifest(ref.connector);
+  if (!manifest) {
+    return { ok: false, error: { code: "UNKNOWN_CONNECTOR", message: `"${ref.connector}" is not a known connector.` } };
+  }
+  const docConfig = manifest.documents?.[ref.kind];
+  if (!docConfig) {
+    return {
+      ok: false,
+      error: {
+        code: "UNDECLARED_KIND",
+        message: `Connector "${ref.connector}" declares no document kind "${ref.kind}".`
+      }
+    };
+  }
+  const toolEntry = manifest.toolGating?.overrides?.[docConfig.tool];
+  if (!toolEntry?.internal) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_INTERNAL",
+        message: `Connector "${ref.connector}"'s document read "${docConfig.tool}" is not marked internal \u2014 refusing to call it for a document reference.`
+      }
+    };
+  }
+  const args = substitute(docConfig.args, { id: ref.id });
+  const read = await readPreview(integrationManager2, ref.connector, docConfig.tool, args);
+  if (read.status === "not_found") {
+    return { ok: false, error: { code: "NOT_FOUND", message: read.message ?? `No document "${ref.kind}"/"${ref.id}" on "${ref.connector}".` } };
+  }
+  if (read.status !== "ok") {
+    return { ok: false, error: { code: "UNAVAILABLE", message: read.message ?? `Connector "${ref.connector}" could not be reached.` } };
+  }
+  const body = structuredOrJsonText(read.body);
+  if (!body || typeof body !== "object") {
+    return { ok: false, error: { code: "MALFORMED_RESULT", message: `Document read for "${ref.connector}:${ref.kind}" returned no structured result.` } };
+  }
+  const { filename, contentType, contentBase64, sha256: claimedSha256 } = body;
+  if (typeof filename !== "string" || !filename) {
+    return { ok: false, error: { code: "MALFORMED_RESULT", message: 'Document result is missing "filename".' } };
+  }
+  if (typeof contentType !== "string" || !contentType) {
+    return { ok: false, error: { code: "MALFORMED_RESULT", message: 'Document result is missing "contentType".' } };
+  }
+  if (typeof contentBase64 !== "string" || !contentBase64) {
+    return { ok: false, error: { code: "MALFORMED_RESULT", message: 'Document result is missing "contentBase64".' } };
+  }
+  let bytes;
+  try {
+    bytes = Buffer.from(contentBase64, "base64");
+  } catch {
+    return { ok: false, error: { code: "MALFORMED_RESULT", message: '"contentBase64" is not valid base64.' } };
+  }
+  const computedSha256 = sha256Hex(bytes);
+  if (typeof claimedSha256 === "string" && claimedSha256.length > 0 && claimedSha256 !== computedSha256) {
+    return {
+      ok: false,
+      error: {
+        code: "HASH_MISMATCH",
+        message: `Connector "${ref.connector}" claimed sha256 ${claimedSha256} for "${ref.kind}:${ref.id}" but the bytes hash to ${computedSha256}.`
+      }
+    };
+  }
+  return { ok: true, doc: { filename, contentType, contentBase64, sha256: computedSha256, bytes: bytes.byteLength } };
+}
+async function resolveAttachmentPreview(integrationManager2, ref, sealedSha256) {
+  const result = await resolveDocumentReference(integrationManager2, ref);
+  if (!result.ok) {
+    switch (result.error.code) {
+      case "NOT_FOUND":
+        return { status: "not_found", message: result.error.message };
+      case "UNKNOWN_CONNECTOR":
+      case "UNDECLARED_KIND":
+      case "NOT_INTERNAL":
+        return { status: "error", message: result.error.message };
+      default:
+        return { status: "unavailable", message: result.error.message };
+    }
+  }
+  if (result.doc.sha256 !== sealedSha256) {
+    return {
+      status: "changed",
+      message: `"${result.doc.filename}" (${ref.connector}:${ref.kind}/${ref.id}) changed since it was sealed \u2014 its fingerprint no longer matches.`
+    };
+  }
+  return { status: "ok", ...result.doc };
+}
+
+// src/lib/insert-values.ts
+function hostAllowed(host, allowed) {
+  const h = host.toLowerCase();
+  const a = allowed.toLowerCase();
+  return h === a || h.endsWith(`.${a}`);
+}
+async function resolveInsertValue(integrationManager2, ref) {
+  const manifest = getManifest(ref.connector);
+  if (!manifest) {
+    return { ok: false, error: { code: "UNKNOWN_CONNECTOR", message: `"${ref.connector}" is not a known connector.` } };
+  }
+  const valueConfig = manifest.values?.[ref.kind];
+  if (!valueConfig) {
+    return {
+      ok: false,
+      error: { code: "UNDECLARED_KIND", message: `Connector "${ref.connector}" declares no insertable value kind "${ref.kind}".` }
+    };
+  }
+  const args = substitute(valueConfig.args, { id: ref.id });
+  const read = await readPreview(integrationManager2, ref.connector, valueConfig.tool, args);
+  if (read.status === "not_found") {
+    return { ok: false, error: { code: "NOT_FOUND", message: read.message ?? `No value "${ref.kind}"/"${ref.id}" on "${ref.connector}".` } };
+  }
+  if (read.status !== "ok") {
+    return { ok: false, error: { code: "UNAVAILABLE", message: read.message ?? `Connector "${ref.connector}" could not be reached.` } };
+  }
+  const body = structuredOrJsonText(read.body);
+  if (!body || typeof body !== "object") {
+    return { ok: false, error: { code: "MALFORMED_RESULT", message: `Value read for "${ref.connector}:${ref.kind}" returned no structured result.` } };
+  }
+  const raw = getByDottedPath(body, valueConfig.path);
+  if (typeof raw !== "string" || !raw) {
+    return { ok: false, error: { code: "MALFORMED_RESULT", message: `Value read for "${ref.connector}:${ref.kind}" has nothing at "${valueConfig.path}".` } };
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, error: { code: "NOT_HTTPS", message: `Value "${raw}" is not a valid URL.` } };
+  }
+  if (url.protocol !== "https:") {
+    return { ok: false, error: { code: "NOT_HTTPS", message: `Value "${raw}" is not an https URL.` } };
+  }
+  if (!valueConfig.allowedHosts.some((h) => hostAllowed(url.hostname, h))) {
+    return {
+      ok: false,
+      error: {
+        code: "DISALLOWED_HOST",
+        message: `Value "${raw}" is on host "${url.hostname}", which "${ref.connector}:${ref.kind}" does not allow (allowed: ${valueConfig.allowedHosts.join(", ")}).`
+      }
+    };
+  }
+  return { ok: true, insert: { placeholder: ref.placeholder, value: raw, connector: ref.connector, kind: ref.kind } };
+}
+function placeholdersIn(text) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(/\{\{[^{}]+\}\}/g)) {
+    if (!seen.has(m[0])) {
+      seen.add(m[0]);
+      found.push(m[0]);
+    }
+  }
+  return found;
+}
+function applyInserts(fields, inserts) {
+  const allPlaceholders = /* @__PURE__ */ new Set();
+  for (const text of Object.values(fields)) {
+    for (const p of placeholdersIn(text)) allPlaceholders.add(p);
+  }
+  const insertByPlaceholder = new Map(inserts.map((i) => [i.placeholder, i]));
+  for (const p of allPlaceholders) {
+    if (!insertByPlaceholder.has(p)) {
+      return {
+        ok: false,
+        error: {
+          code: "UNMATCHED_PLACEHOLDER",
+          placeholder: p,
+          message: `The text contains "${p}" but no "insert" entry names that placeholder.`
+        }
+      };
+    }
+  }
+  for (const insert of inserts) {
+    if (!allPlaceholders.has(insert.placeholder)) {
+      return {
+        ok: false,
+        error: {
+          code: "PLACEHOLDER_NOT_FOUND",
+          placeholder: insert.placeholder,
+          message: `"insert" names placeholder "${insert.placeholder}", which does not appear in the text.`
+        }
+      };
+    }
+  }
+  const out = {};
+  for (const [field, text] of Object.entries(fields)) {
+    let replaced = text;
+    for (const insert of inserts) {
+      replaced = replaced.split(insert.placeholder).join(insert.value);
+    }
+    out[field] = replaced;
+  }
+  return { ok: true, fields: out };
+}
+
+// src/lib/mime-message.ts
+var CRLF = "\r\n";
+function isAscii(s) {
+  return /^[\x20-\x7e]*$/.test(s);
+}
+function rfc2047Encode(value) {
+  if (isAscii(value)) return value;
+  const b64 = Buffer.from(value, "utf8").toString("base64");
+  return `=?UTF-8?B?${b64}?=`;
+}
+function wrapBase64(b64) {
+  const lines = [];
+  for (let i = 0; i < b64.length; i += 76) lines.push(b64.slice(i, i + 76));
+  return lines.join(CRLF);
+}
+function makeBoundary() {
+  const random = Buffer.from(
+    Array.from({ length: 16 }, () => Math.floor(Math.random() * 256))
+  ).toString("hex");
+  return `----=_SuverenPart_${random}`;
+}
+function addressHeader(name, addresses) {
+  if (!addresses?.length) return "";
+  return `${name}: ${addresses.join(", ")}${CRLF}`;
+}
+function buildMimeMessage(input) {
+  const boundary = makeBoundary();
+  const headers = `MIME-Version: 1.0${CRLF}` + addressHeader("To", input.to) + addressHeader("Cc", input.cc) + `Subject: ${rfc2047Encode(input.subject)}${CRLF}Content-Type: multipart/mixed; boundary="${boundary}"${CRLF}`;
+  const textPart = `--${boundary}${CRLF}Content-Type: text/plain; charset="UTF-8"${CRLF}Content-Transfer-Encoding: base64${CRLF}${CRLF}` + wrapBase64(Buffer.from(input.bodyText, "utf8").toString("base64")) + CRLF;
+  const attachmentParts = input.attachments.map((att) => {
+    const name = rfc2047Encode(att.filename);
+    return `--${boundary}${CRLF}Content-Type: ${att.contentType}; name="${name}"${CRLF}Content-Disposition: attachment; filename="${name}"${CRLF}Content-Transfer-Encoding: base64${CRLF}${CRLF}` + wrapBase64(att.contentBase64) + CRLF;
+  });
+  return headers + CRLF + [textPart, ...attachmentParts].join("") + `--${boundary}--${CRLF}`;
+}
+function toBase64Url(mime) {
+  return Buffer.from(mime, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// src/lib/attachment-resolution.ts
+async function resolveAttachmentsAndInserts(integrationManager2, tool, profileId, args, allowedSourcesValue) {
+  const attachmentsArg = tool.gating?.attachmentsArg;
+  const insertFields = tool.gating?.insertFields;
+  if (!attachmentsArg && !insertFields?.length) return { ok: true, args };
+  const refsResult = attachmentsArg ? validateDocumentReferences(args[attachmentsArg]) : { ok: true, refs: [] };
+  if (!refsResult.ok) {
+    return { ok: false, message: `Refused: ${tool.namespacedName}'s attachments ${refsResult.error.message}` };
+  }
+  const insertResult = validateInsertReferences(args.insert);
+  if (!insertResult.ok) {
+    return { ok: false, message: `Refused: ${tool.namespacedName}'s insert ${insertResult.error.message}` };
+  }
+  const sealedAttachments = [];
+  if (refsResult.refs.length > 0) {
+    const profile = getProfile2(profileId);
+    for (const ref of refsResult.refs) {
+      const policy = isAttachmentSourceAllowed(profileId, profile, allowedSourcesValue, ref);
+      if (!policy.allowed) {
+        return { ok: false, message: `Refused: attachment "${ref.connector}:${ref.kind}" is not allowed. ${policy.reason}` };
+      }
+      const resolved = await resolveDocumentReference(integrationManager2, ref);
+      if (!resolved.ok) {
+        return { ok: false, message: `Refused: could not resolve attachment "${ref.connector}:${ref.kind}/${ref.id}" \u2014 ${resolved.error.message}` };
+      }
+      sealedAttachments.push({
+        connector: ref.connector,
+        kind: ref.kind,
+        id: ref.id,
+        filename: resolved.doc.filename,
+        contentType: resolved.doc.contentType,
+        sha256: resolved.doc.sha256,
+        bytes: resolved.doc.bytes
+      });
+    }
+  }
+  const sealedInserts = [];
+  const resolvedInserts = [];
+  if (insertResult.refs.length > 0) {
+    for (const ref of insertResult.refs) {
+      const resolved = await resolveInsertValue(integrationManager2, ref);
+      if (!resolved.ok) {
+        return { ok: false, message: `Refused: could not resolve insert "${ref.connector}:${ref.kind}/${ref.id}" for "${ref.placeholder}" \u2014 ${resolved.error.message}` };
+      }
+      resolvedInserts.push(resolved.insert);
+      sealedInserts.push({ placeholder: ref.placeholder, connector: ref.connector, kind: ref.kind, id: ref.id, value: resolved.insert.value });
+    }
+  }
+  let outgoing = { ...args };
+  if (insertFields?.length) {
+    const fields = {};
+    for (const field of insertFields) {
+      fields[field] = typeof args[field] === "string" ? args[field] : "";
+    }
+    const applied = applyInserts(fields, resolvedInserts);
+    if (!applied.ok) {
+      return { ok: false, message: `Refused: ${tool.namespacedName}'s insert \u2014 ${applied.error.message}` };
+    }
+    outgoing = { ...outgoing, ...applied.fields };
+  } else if (insertResult.refs.length > 0) {
+    return { ok: false, message: `Refused: ${tool.namespacedName} does not declare any insertable text fields.` };
+  }
+  if (attachmentsArg) delete outgoing[attachmentsArg];
+  delete outgoing.insert;
+  return {
+    ok: true,
+    args: outgoing,
+    ...sealedAttachments.length > 0 || sealedInserts.length > 0 ? { sealed: { attachments: sealedAttachments, inserts: sealedInserts } } : {}
+  };
+}
+function toStringArray(value) {
+  if (Array.isArray(value)) return value.map((v) => String(v));
+  if (typeof value === "string" && value) return [value];
+  return [];
+}
+async function finalizeAttachmentsForExecution(integrationManager2, integrationId, args) {
+  const sealed = args[ATTACHMENTS_SEALED_META_KEY];
+  if (!sealed || sealed.attachments.length === 0 && sealed.inserts.length === 0) {
+    return { ok: true, args };
+  }
+  const resolvedDocs = [];
+  for (const a of sealed.attachments) {
+    const resolved = await resolveDocumentReference(integrationManager2, { connector: a.connector, kind: a.kind, id: a.id });
+    if (!resolved.ok) {
+      return {
+        ok: false,
+        message: `Refused: could not re-resolve attachment "${a.filename}" (${a.connector}:${a.kind}/${a.id}) at execution \u2014 ${resolved.error.message}`
+      };
+    }
+    if (resolved.doc.sha256 !== a.sha256) {
+      return {
+        ok: false,
+        message: `Refused: attachment "${a.filename}" (${a.connector}:${a.kind}/${a.id}) changed since this was approved \u2014 its fingerprint no longer matches.`
+      };
+    }
+    resolvedDocs.push(resolved.doc);
+  }
+  for (const i of sealed.inserts) {
+    const resolved = await resolveInsertValue(integrationManager2, { connector: i.connector, kind: i.kind, id: i.id, placeholder: i.placeholder });
+    if (!resolved.ok) {
+      return {
+        ok: false,
+        message: `Refused: could not re-resolve the inserted value for "${i.placeholder}" (${i.connector}:${i.kind}/${i.id}) at execution \u2014 ${resolved.error.message}`
+      };
+    }
+    if (resolved.insert.value !== i.value) {
+      return {
+        ok: false,
+        message: `Refused: the value inserted for "${i.placeholder}" (${i.connector}:${i.kind}/${i.id}) changed since this was approved.`
+      };
+    }
+  }
+  let outgoing = { ...args };
+  if (resolvedDocs.length > 0) {
+    const manifest = getManifest(integrationId);
+    const transport = manifest?.attachments;
+    if (!transport) {
+      return { ok: false, message: `Refused: "${integrationId}" declares no attachments transport.` };
+    }
+    if (transport.transport === "field") {
+      outgoing[transport.arg] = resolvedDocs.map((d) => ({
+        filename: d.filename,
+        contentType: d.contentType,
+        contentBase64: d.contentBase64
+      }));
+    } else {
+      const to = toStringArray(outgoing.to);
+      const cc = toStringArray(outgoing.cc);
+      const subject = typeof outgoing.subject === "string" ? outgoing.subject : "";
+      const bodyText = typeof outgoing.body === "string" ? outgoing.body : "";
+      const mime = buildMimeMessage({
+        to,
+        cc,
+        subject,
+        bodyText,
+        attachments: resolvedDocs.map((d) => ({ filename: d.filename, contentType: d.contentType, contentBase64: d.contentBase64 }))
+      });
+      outgoing[transport.arg] = toBase64Url(mime);
+    }
+  }
+  return { ok: true, args: outgoing };
+}
+var ATTACHMENTS_SEALED_META_KEY = "_attachmentsSealed";
+function stripAttachmentsSealedMeta(args) {
+  if (!(ATTACHMENTS_SEALED_META_KEY in args)) return args;
+  const { [ATTACHMENTS_SEALED_META_KEY]: _omit, ...rest } = args;
+  return rest;
+}
+
+// src/lib/content-binding.ts
+function getContentBinding(profileId) {
+  return getProfile3(profileId)?.content_binding;
+}
+function computeContentBinding(profileId, tool, toolArgs, actionType) {
+  const binding = getContentBinding(profileId);
+  if (!binding) return void 0;
+  if (isFieldBinding(binding)) {
+    if (!bindingAppliesTo(binding, actionType)) {
+      if (!actionType && binding.appliesTo) {
+        console.error(
+          `[Suveren MCP] Warning: ${tool?.namespacedName ?? profileId} has no action_type in staticExecution, so the ${profileId} content binding (${binding.appliesTo.join(", ")}) does not apply and the receipt will bind no content. Fix the integration manifest.`
+        );
+      }
+      return void 0;
+    }
+    let effectiveArgs = toolArgs;
+    if (binding.fields?.includes("attachments")) {
+      const sealed = toolArgs[ATTACHMENTS_SEALED_META_KEY];
+      const fingerprints = (sealed?.attachments ?? []).map((a) => ({ filename: a.filename, sha256: a.sha256 }));
+      effectiveArgs = { ...toolArgs, attachments: fingerprints };
+    }
+    const bound = selectBoundFields(binding, effectiveArgs);
+    return {
+      contentHash: computeContentHash2(binding, bound),
+      contentBinding: { version: binding.version, kind: binding.kind, fields: binding.fields },
+      boundContent: bound
+    };
+  }
+  let contentHash;
+  let boundContent;
+  if (binding.kind === "jcs") {
+    contentHash = computeContentHash2(binding, toolArgs);
+    boundContent = toolArgs;
+  } else {
+    const declared = tool?.gating?.contentField;
+    const field = declared ?? (tool ? detectContentField(tool) : null);
+    if (!field) return void 0;
+    const raw = typeof toolArgs[field] === "string" ? toolArgs[field] : "";
+    if (raw === "") return void 0;
+    contentHash = computeContentHash2(binding, raw);
+    boundContent = raw;
+  }
+  return {
+    contentHash,
+    contentBinding: { version: binding.version, kind: binding.kind },
+    boundContent
+  };
+}
+function attachTicketId(tool, args, ticketId) {
+  const schema = tool.inputSchema;
+  if (!schema?.properties || !("ticket_id" in schema.properties)) return args;
+  return { ...args, ticket_id: ticketId };
+}
+
 // src/lib/ticket-verify.ts
 import { verifyTicketSignature } from "@hap/core";
 var TicketBindingMismatchError = class extends Error {
@@ -5200,7 +5924,7 @@ async function resolveWhoLabel(archive, domainKey, userId) {
 }
 
 // src/lib/arg-encoding.ts
-function rfc2047Encode(value) {
+function rfc2047Encode2(value) {
   if (!/[^\x00-\x7F]/.test(value)) return value;
   const CHARSET = "=?UTF-8?Q?";
   const SUFFIX = "?=";
@@ -5234,7 +5958,7 @@ function rfc2047Encode(value) {
   return words.join(" ");
 }
 var ENCODERS = {
-  rfc2047: rfc2047Encode
+  rfc2047: rfc2047Encode2
 };
 function encodeOutgoingArgs(tool, args) {
   const declared = tool?.gating?.argEncoding;
@@ -5307,7 +6031,7 @@ function normalizeIncomingArgs(tool, args) {
 }
 
 // src/lib/numeric-execution.ts
-import { getProfile as getProfile3 } from "@hap/core";
+import { getProfile as getProfile4 } from "@hap/core";
 function parseNumericString(value) {
   if (!/^-?\d+(\.\d+)?$/.test(value)) return void 0;
   const parsed = Number(value);
@@ -5323,7 +6047,7 @@ function declaredNumericFields(profile) {
   return out;
 }
 function coerceDeclaredNumericFields(profileId, execution) {
-  const fields = declaredNumericFields(getProfile3(profileId));
+  const fields = declaredNumericFields(getProfile4(profileId));
   for (const field of fields) {
     const value = execution[field];
     if (typeof value !== "string") continue;
@@ -5333,7 +6057,7 @@ function coerceDeclaredNumericFields(profileId, execution) {
 }
 
 // src/lib/tool-proxy.ts
-import { getProfile as getProfile4, ContentBindingError, boundActionTypes as boundActionTypes2 } from "@hap/core";
+import { getProfile as getProfile5, ContentBindingError, boundActionTypes as boundActionTypes2 } from "@hap/core";
 import { readFile } from "fs/promises";
 import { extname } from "path";
 import { randomUUID } from "crypto";
@@ -5405,7 +6129,7 @@ function profileMatches(profileId, shortName2) {
   return profileId === shortName2 || profileId.includes("/" + shortName2 + "@") || profileId.endsWith("/" + shortName2);
 }
 function wireExecutionContext(profileId, execution) {
-  const profile = getProfile4(profileId);
+  const profile = getProfile5(profileId);
   const allowed = /* @__PURE__ */ new Set(["action_type"]);
   const fields = profile?.boundsSchema?.fields;
   if (fields) {
@@ -5423,7 +6147,7 @@ function wireExecutionContext(profileId, execution) {
   return out;
 }
 function countBoundsFor(profileId, actionType) {
-  const fields = getProfile4(profileId)?.boundsSchema?.fields;
+  const fields = getProfile5(profileId)?.boundsSchema?.fields;
   if (!fields) return null;
   return Object.entries(fields).filter(([, def]) => def.boundType?.kind === "cumulative_count").filter(([name, def]) => {
     const applies = boundActionTypes2(name, def);
@@ -5498,7 +6222,7 @@ function recordBlocked(state2, tool, rec) {
 function recordGatekeeperRefusal(state2, tool, refusals) {
   if (refusals.length === 0) return;
   const pick = refusals.find((r) => r.bound !== void 0 && r.actual !== void 0) ?? refusals[0];
-  const scoped = pick.field ? Boolean(getProfile4(pick.profileId)?.scopeSchema?.fields?.[pick.field]) : false;
+  const scoped = pick.field ? Boolean(getProfile5(pick.profileId)?.scopeSchema?.fields?.[pick.field]) : false;
   const asValueOrString = (v) => typeof v === "number" || typeof v === "string" ? v : void 0;
   recordBlocked(state2, tool, {
     kind: scoped ? "scope" : "bound",
@@ -5677,7 +6401,7 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
           );
         }
       }
-      const readProfile = readAdapter ? getProfile4(matchingAuths[0].profileId) : void 0;
+      const readProfile = readAdapter ? getProfile5(matchingAuths[0].profileId) : void 0;
       const boundsSchema = readProfile?.boundsSchema;
       const ageBoundField = readAdapter?.ageField ? resolveAgeBoundField(boundsSchema, readAdapter.ageField) : null;
       const hasAgeDimension = Boolean(readAdapter?.ageField);
@@ -5808,6 +6532,20 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
     });
   }
   return lockedGuard(async (args) => {
+    let attachmentSourcesForExecution;
+    if (tool.gating?.attachmentsArg || tool.gating?.insertFields?.length) {
+      const refsResult = tool.gating.attachmentsArg ? validateDocumentReferences(args[tool.gating.attachmentsArg]) : { ok: true, refs: [] };
+      if (!refsResult.ok) {
+        return { content: [{ type: "text", text: `Refused: ${tool.namespacedName}'s attachments ${refsResult.error.message}` }], isError: true };
+      }
+      const insertResult = validateInsertReferences(args.insert);
+      if (!insertResult.ok) {
+        return { content: [{ type: "text", text: `Refused: ${tool.namespacedName}'s insert ${insertResult.error.message}` }], isError: true };
+      }
+      if (refsResult.refs.length > 0) {
+        attachmentSourcesForExecution = [...new Set(refsResult.refs.map((r) => `${r.connector}:${r.kind}`))].join(",");
+      }
+    }
     const execution = { ...staticExecution };
     for (const [argName, mapping] of Object.entries(executionMapping)) {
       const value = args[argName];
@@ -5824,6 +6562,9 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
         }
       }
     }
+    if (attachmentSourcesForExecution) {
+      execution[ATTACHMENT_SOURCES_FIELD] = attachmentSourcesForExecution;
+    }
     coerceDeclaredNumericFields(profile, execution);
     const declaredActionType = typeof execution.action_type === "string" && execution.action_type.length > 0 ? execution.action_type : void 0;
     if (!declaredActionType) {
@@ -5843,7 +6584,7 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
       };
     }
     {
-      const profileDef = getProfile4(profile);
+      const profileDef = getProfile5(profile);
       const registry = profileDef?.boundsSchema?.actionTypes;
       if (Array.isArray(registry) && registry.length > 0 && !registry.includes(declaredActionType)) {
         recordBlocked(state2, tool, {
@@ -5947,8 +6688,21 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
         isError: true
       };
     }
-    const contextKeys = getProfile4(passers[0].profileId)?.scopeSchema?.keyOrder ?? [];
-    return attemptWithCandidates(passers);
+    const contextKeys = getProfile5(passers[0].profileId)?.scopeSchema?.keyOrder ?? [];
+    let pool = passers;
+    if (tool.gating?.attachmentsArg) {
+      const raw = args[tool.gating.attachmentsArg];
+      const refs = Array.isArray(raw) ? raw.filter((r) => !!r && typeof r === "object" && typeof r.connector === "string" && typeof r.kind === "string") : [];
+      const narrowed = candidatesAllowingAttachments(passers, refs, (id) => getProfile5(id));
+      if (narrowed.allowed.length === 0) {
+        return {
+          content: [{ type: "text", text: `Refused: attachment not allowed by any ${tool.gating.profile ?? ""} mandate. ${narrowed.refusal ?? ""}`.trim() }],
+          isError: true
+        };
+      }
+      pool = narrowed.allowed;
+    }
+    return attemptWithCandidates(pool);
     async function attemptWithCandidates(candidates) {
       const selection = selectAuthorization(
         contextKeys,
@@ -5975,9 +6729,18 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
           isError: true
         };
       }
+      let callArgs = args;
+      if (tool.gating?.attachmentsArg || tool.gating?.insertFields?.length) {
+        const allowedSourcesValue = typeof auth.context?.[ATTACHMENT_SOURCES_FIELD] === "string" ? auth.context[ATTACHMENT_SOURCES_FIELD] : void 0;
+        const resolved = await resolveAttachmentsAndInserts(integrationManager2, tool, auth.profileId, args, allowedSourcesValue);
+        if (!resolved.ok) {
+          return { content: [{ type: "text", text: resolved.message }], isError: true };
+        }
+        callArgs = resolved.sealed ? { ...resolved.args, [ATTACHMENTS_SEALED_META_KEY]: resolved.sealed } : resolved.args;
+      }
       if ((auth.deferredCommitmentDomains ?? []).length > 0) {
         try {
-          const enrichedArgs = await attachImagePreview(args);
+          const enrichedArgs = await attachImagePreview(callArgs);
           const wireExecCtx = wireExecutionContext(auth.profileId, execution);
           let recipientUserIds = auth.deferredCommitmentDomains.filter((d) => d !== "owner");
           try {
@@ -6031,10 +6794,18 @@ Proposal ID: ${proposal.id}. Check status with check-pending-commitments(proposa
           };
         }
       }
+      let finalArgs = callArgs;
+      if (tool.gating?.attachmentsArg || tool.gating?.insertFields?.length) {
+        const finalized = await finalizeAttachmentsForExecution(integrationManager2, tool.integrationId, callArgs);
+        if (!finalized.ok) {
+          return { content: [{ type: "text", text: finalized.message }], isError: true };
+        }
+        finalArgs = finalized.args;
+      }
       let receiptId;
       try {
         const actionType = declaredActionType;
-        const binding = computeContentBinding(auth.profileId, tool, args, actionType);
+        const binding = computeContentBinding(auth.profileId, tool, finalArgs, actionType);
         const idempotencyKey = randomUUID();
         const wireExecCtx = wireExecutionContext(auth.profileId, execution);
         const { receipt } = await state2.spClient.postReceipt({
@@ -6077,10 +6848,12 @@ Proposal ID: ${proposal.id}. Check status with check-pending-commitments(proposa
           // would hold a hash of content it cannot reproduce.
           boundContent: binding?.boundContent,
           // UI spec §14 — what this call sends, exactly the object the
-          // journal's argsHash is computed from below (`hashToolArgs(args)`),
-          // so the ticket view can show it and check it. Same write, so it
-          // is as fail-closed and as encrypted as the rest of the entry.
-          sentArgs: args
+          // journal's argsHash is computed from below
+          // (`hashToolArgs(finalArgs)`), so the ticket view can show it and
+          // check it (incl. any attachments' sealed fingerprints — UI spec
+          // §15.2). Same write, so it is as fail-closed and as encrypted
+          // as the rest of the entry.
+          sentArgs: finalArgs
         });
       } catch (err) {
         if (err instanceof AsKeyMismatchError || err instanceof TicketBindingMismatchError) {
@@ -6172,7 +6945,7 @@ Proposal ID: ${proposal.id}. Check status with check-pending-commitments(proposa
           const uniqueApprovers = [...new Set(pendingApprovers)];
           const recipientUserIds = ownerId ? [.../* @__PURE__ */ new Set([ownerId, ...uniqueApprovers])] : uniqueApprovers;
           try {
-            const enrichedArgs = await attachImagePreview(args);
+            const enrichedArgs = await attachImagePreview(callArgs);
             const wireExecCtx = wireExecutionContext(auth.profileId, execution);
             const { proposal, unreadableFor } = await state2.spClient.submitProposal({
               authorizationId: authzId,
@@ -6256,15 +7029,16 @@ Proposal ID: ${proposal.id}. Use check-pending-commitments to track status.` + a
         execution: { ...execution },
         timestamp: Math.floor(Date.now() / 1e3)
       });
-      let outgoingArgs = shouldAttachFooter() && receiptId ? appendVerificationFooter(tool, args, receiptId, auth.subjects?.[0]) : args;
+      let outgoingArgs = shouldAttachFooter() && receiptId ? appendVerificationFooter(tool, finalArgs, receiptId, auth.subjects?.[0]) : finalArgs;
       if (receiptId) outgoingArgs = attachTicketId(tool, outgoingArgs, receiptId);
       outgoingArgs = encodeOutgoingArgs(tool, outgoingArgs);
       outgoingArgs = stripSourceLink(outgoingArgs);
+      outgoingArgs = stripAttachmentsSealedMeta(outgoingArgs);
       if (receiptId) {
         const begun = state2.executionJournal.begin({
           ticketId: receiptId,
           tool: tool.namespacedName,
-          argsHash: hashToolArgs(args)
+          argsHash: hashToolArgs(finalArgs)
         });
         if (!begun.ok) {
           return {
@@ -6433,7 +7207,7 @@ function buildMandateBrief(opts) {
       const parts = [];
       if (boundsDesc) parts.push(boundsDesc);
       if (executionLog) {
-        const profile = getProfile5(auth.profileId) ?? getProfile5(shortName2);
+        const profile = getProfile6(auth.profileId) ?? getProfile6(shortName2);
         const consumption = getConsumptionState(auth, executionLog, profile);
         const compact = formatConsumptionCompact(consumption);
         if (compact) parts.push(compact);
@@ -6471,7 +7245,7 @@ function buildMandateBrief(opts) {
 }
 
 // src/tools/authorizations.ts
-import { getProfile as getProfile6 } from "@hap/core";
+import { getProfile as getProfile7 } from "@hap/core";
 function shortProfileName2(profileId) {
   const withoutVersion = profileId.replace(/@.*$/, "");
   const parts = withoutVersion.split("/");
@@ -6590,7 +7364,7 @@ function listAuthorizationsHandler(state2, integrationManager2, contextDir) {
         } catch {
         }
         const shortName2 = shortProfileName2(auth.profileId);
-        const profile = getProfile6(auth.profileId) ?? getProfile6(shortName2);
+        const profile = getProfile7(auth.profileId) ?? getProfile7(shortName2);
         if (profile) {
           const consumption = getConsumptionState(auth, state2.executionLog, profile);
           const consumptionText = formatConsumptionFull(consumption);
@@ -6650,7 +7424,7 @@ function listAuthorizationsHandler(state2, integrationManager2, contextDir) {
           lines.push("    Mode: review (each action requires your approval)");
         }
         const shortName2 = shortProfileName2(auth.profileId);
-        const profile = getProfile6(auth.profileId) ?? getProfile6(shortName2);
+        const profile = getProfile7(auth.profileId) ?? getProfile7(shortName2);
         if (profile) {
           const consumption = getConsumptionState(auth, state2.executionLog, profile);
           const compact = formatConsumptionCompact(consumption);
@@ -6793,12 +7567,12 @@ function listIntegrationsHandler(state2, integrationManager2) {
 import { ContentBindingError as ContentBindingError2 } from "@hap/core";
 
 // src/lib/proposal-content.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { canonicalize } from "@hap/core";
 var ProposalContentError = class extends Error {
 };
 function computeProposalContentHash(toolArgs) {
-  return `sha256:${createHash3("sha256").update(canonicalize(toolArgs)).digest("hex")}`;
+  return `sha256:${createHash4("sha256").update(canonicalize(toolArgs)).digest("hex")}`;
 }
 async function resolveProposalToolArgs(proposal) {
   if (proposal.toolArgs) return proposal.toolArgs;
@@ -7108,8 +7882,23 @@ async function executeCommitted(proposal, state2, integrationManager2) {
       };
     }
   }
+  let finalToolArgs = toolArgs;
+  {
+    const finalized = await finalizeAttachmentsForExecution(integrationManager2, integrationId, toolArgs);
+    if (!finalized.ok) {
+      state2.executionJournal.complete(receiptId, "failed", "changed", finalized.message);
+      recordExecutionOutcome(state2, proposal.id, receiptId, false, finalized.message);
+      logExecutionOutcome(proposal.id, false, "attachment or inserted value changed since approval");
+      void notifyControlPlane("execution-failed");
+      return {
+        text: `Proposal ${proposal.id} was approved, but ${finalized.message} Nothing was sent.`,
+        isError: true
+      };
+    }
+    finalToolArgs = finalized.args;
+  }
   try {
-    let outgoingArgs = toolArgs;
+    let outgoingArgs = finalToolArgs;
     if (discovered && receiptId) {
       if (shouldAttachFooter()) {
         outgoingArgs = appendVerificationFooter(discovered, outgoingArgs, receiptId, cachedAuth?.subjects?.[0]);
@@ -7118,6 +7907,7 @@ async function executeCommitted(proposal, state2, integrationManager2) {
       outgoingArgs = encodeOutgoingArgs(discovered, outgoingArgs);
     }
     outgoingArgs = stripSourceLink(outgoingArgs);
+    outgoingArgs = stripAttachmentsSealedMeta(outgoingArgs);
     let result;
     try {
       result = await integrationManager2.callTool(integrationId, toolName, outgoingArgs);
@@ -8179,7 +8969,7 @@ var IntegrationManager = class {
       if (opts.skipIfRunning) return existing.tools;
       await this.stopIntegrationLocked(config.id);
     }
-    if (isSimulationMode() && !manifestIsSimulated(getManifest(config.id))) {
+    if (isSimulationMode() && !this.isSimulationSafe(config.id)) {
       throw new Error(`${config.id}: ${SIMULATION_BLOCK_REASON}`);
     }
     if (config.npmPackage) {
@@ -8254,6 +9044,7 @@ var IntegrationManager = class {
       if (gating && gating.category !== "read" && gating.category !== "disabled") {
         inputSchema = withSourceLink(inputSchema);
       }
+      inputSchema = withAttachmentAndInsertSchema(inputSchema, gating ?? void 0);
       return {
         originalName: tool.name,
         namespacedName: `${config.id}__${tool.name}`,
@@ -8261,6 +9052,13 @@ var IntegrationManager = class {
         description: tool.description ?? "",
         inputSchema,
         outputSchema: tool.outputSchema,
+        // A connector's own `internal: true` override (tool-gating-types.ts
+        // `ProfileToolGatingEntry.internal`) — same meaning and enforcement
+        // as a built-in's `BuiltinTool.internal` above: never registered
+        // with the MCP server (index.ts), never callable directly
+        // (tool-proxy.ts); only the gateway's own code (e.g. a document
+        // preview read — preview.ts) calls it, via `callTool` directly.
+        ...gating?.internal ? { internal: true } : {},
         gating
       };
     });
@@ -8361,7 +9159,8 @@ var IntegrationManager = class {
         ...t.gating?.approvalView ? { approvalView: t.gating.approvalView } : {},
         // UI spec §14.1 — which sent values the signed ticket also carries
         // (arg → executionContext field), for the "in the ticket" tag.
-        ...mapping && Object.keys(mapping).length > 0 ? { executionMapping: mapping } : {}
+        ...mapping && Object.keys(mapping).length > 0 ? { executionMapping: mapping } : {},
+        ...t.gating?.aiTextArg ? { aiTextArg: t.gating.aiTextArg } : {}
       };
     }
     return out;
@@ -8390,13 +9189,24 @@ var IntegrationManager = class {
     return this.builtins.get(id)?.def.alwaysListed === true;
   }
   /**
-   * Whether `id` may run while simulation mode is on: a connector whose manifest
-   * carries the `simulation` marker, or a built-in that declares `simulation: true`.
+   * Whether `id` may run while simulation mode is on: a built-in that
+   * declares `simulation: true`, or a connector whose CURRENT setting (the
+   * credential/setting field its manifest's `simulation.field` names,
+   * defaulting per `simulation.default` when unset) resolves to simulated —
+   * NOT merely a connector whose manifest supports a simulated mode at all.
+   * A connector set to a real mode (e.g. ERP's `mode=live`) is refused here
+   * exactly like one with no simulation capability at all.
+   *
+   * Reads `serviceCredentials` directly, keyed by `id` — the same convention
+   * `resolveEnvKeys`'s manifest-mapping fallback and `getServiceCredentials`
+   * already rely on: a connector's OWN credential fields (mode, liveAdapter,
+   * …) are pushed to this gateway under its own id (control-plane's
+   * `pushServiceCredentials(id, fields)`), never a shared/other service id.
    */
   isSimulationSafe(id) {
     const builtin = this.builtins.get(id);
     if (builtin) return builtin.def.simulation === true;
-    return manifestIsSimulated(getManifest(id));
+    return connectorCurrentlySimulated(getManifest(id), this.serviceCredentials.get(id));
   }
   /**
    * The built-in's own refusal for this call, checked before the gate (no proposal,
@@ -8558,15 +9368,17 @@ var IntegrationManager = class {
             toolCount: 0,
             readAgeDays: readAgeOf(config),
             // Computed fresh, not cached: true whenever simulation mode is on
-            // AND this connector has no manifest `simulation` marker, which is
-            // exactly the condition startIntegrationLocked refuses under — so
-            // the UI always reflects why a real connector never started,
-            // without needing a separate tracking path for this one reason.
-            // This is `paused`, NOT `error`: it is not a problem, it's the
-            // mode working as designed (see IntegrationStatus.paused). Genuine
+            // AND this connector is not currently simulation-safe (see
+            // `isSimulationSafe` — no capability at all, OR capability
+            // declared but currently SET to a real mode), which is exactly
+            // the condition startIntegrationLocked refuses under — so the UI
+            // always reflects why a real connector never started, without
+            // needing a separate tracking path for this one reason. This is
+            // `paused`, NOT `error`: it is not a problem, it's the mode
+            // working as designed (see IntegrationStatus.paused). Genuine
             // start failures still surface via the one-shot `warning` string
             // returned by /internal/add-integration — they never land here.
-            paused: isSimulationMode() && !manifestIsSimulated(getManifest(config.id)) ? "simulation" : void 0
+            paused: isSimulationMode() && !this.isSimulationSafe(config.id) ? "simulation" : void 0
           });
         }
       }
@@ -8671,7 +9483,8 @@ var IntegrationManager = class {
           blockedArgs: ext.blockedArgs,
           hideUnlessAuthorized: ext.hideUnlessAuthorized,
           simulationOnly: ext.simulationOnly,
-          approvalView: ext.approvalView
+          approvalView: ext.approvalView,
+          internal: ext.internal
         };
       }
       return {
@@ -8701,7 +9514,11 @@ var IntegrationManager = class {
         // this, boundField/requiredValue on a non-"read" override was silently
         // discarded here — the config in the manifest existed but did nothing.
         boundField: ext.boundField,
-        requiredValue: ext.requiredValue
+        requiredValue: ext.requiredValue,
+        internal: ext.internal,
+        attachmentsArg: ext.attachmentsArg,
+        insertFields: ext.insertFields,
+        aiTextArg: ext.display?.aiText
       };
     }
     return {
@@ -8832,7 +9649,7 @@ async function buildTicketDetails(archive, ticketIds) {
 }
 
 // src/lib/report/window.ts
-import { getProfile as getProfile7 } from "@hap/core";
+import { getProfile as getProfile8 } from "@hap/core";
 var REPORT_AGE_FIELD = "read_age_days";
 var REPORTING_PROFILE = "reporting";
 var END_SKEW_SECONDS = 120;
@@ -8846,7 +9663,7 @@ function windowLabel(start, days, loadedAt) {
   if (loadedAt !== null && loadedAt === start) return `${since} (when the test data was loaded)`;
   return `${since} (the last ${days} ${days === 1 ? "day" : "days"})`;
 }
-var defaultLookup = (id) => getProfile7(id);
+var defaultLookup = (id) => getProfile8(id);
 function reportingMandateRefusal(m, lookup = defaultLookup) {
   const schema = lookup(m.profileId)?.boundsSchema;
   const field = resolveAgeBoundField(schema, REPORT_AGE_FIELD);
@@ -9597,7 +10414,7 @@ function unifiedLineDiff(before, after) {
 }
 
 // src/lib/builtins/setup.ts
-import { getProfile as getProfile8 } from "@hap/core";
+import { getProfile as getProfile9 } from "@hap/core";
 var DELEGATION_PROFILE = "delegation";
 var DELEGATION_INTENT_HINT = [
   "Why \u2014 With test data only, I want to find out which routine parts of my work an AI could take over, so people gain time \u2014 before anything touches real systems.",
@@ -9620,8 +10437,9 @@ function briefRefusal(args) {
 function connectedSystems(im) {
   const byId = /* @__PURE__ */ new Map();
   for (const t of im.getAllTools()) {
-    if (im.isBuiltin(t.integrationId) || !t.gating?.profile || t.gating.category === "disabled") continue;
-    const s = byId.get(t.integrationId) ?? { id: t.integrationId, profile: t.gating.profile, actionTypes: [], writeTools: [], readTools: [] };
+    if (im.isBuiltin(t.integrationId) || t.internal || !t.gating?.profile || t.gating.category === "disabled") continue;
+    const key = `${t.integrationId}|${t.gating.profile}`;
+    const s = byId.get(key) ?? { id: t.integrationId, profile: t.gating.profile, actionTypes: [], writeTools: [], readTools: [] };
     if (t.gating.category === "read") {
       s.readTools.push(t.originalName);
     } else {
@@ -9629,9 +10447,9 @@ function connectedSystems(im) {
       const at = t.gating.staticExecution?.action_type;
       if (typeof at === "string" && !s.actionTypes.includes(at)) s.actionTypes.push(at);
     }
-    byId.set(t.integrationId, s);
+    byId.set(key, s);
   }
-  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id) || a.profile.localeCompare(b.profile));
 }
 function shortName(idOrName) {
   const stripped = idOrName.replace(/@.*$/, "").split("/").pop() ?? idOrName;
@@ -9649,7 +10467,7 @@ function delegationItselfRefusal(args) {
 }
 function delegationMandateRefusal(auth) {
   if (isSimulationMode()) return void 0;
-  const profile = getProfile8(auth.profileId);
+  const profile = getProfile9(auth.profileId);
   if (profile?.scopeSchema?.fields?.allowed_profiles) return void 0;
   return `your Delegation mandate (${shortName(auth.profileId)} ${versionOf(auth.profileId)}) does not declare which profiles or modes you may propose \u2014 only a Delegation mandate on delegation 0.4 or later works outside simulation mode. Ask the person to give a current Delegation mandate.`;
 }
@@ -9707,7 +10525,7 @@ function delegationChecks(deps, args, targetShortName, targetDisplayName) {
   );
   const first = governing[0];
   if (first) {
-    const delegationProfile = getProfile8(first.profileId);
+    const delegationProfile = getProfile9(first.profileId);
     const entry = getConsumptionState(first, deps.state.executionLog, delegationProfile).find((e) => e.field === "mandate_daily_max");
     if (entry && entry.limit !== null) {
       checks.push(`Proposals today: ${entry.current} of ${entry.limit}`);
@@ -9717,7 +10535,7 @@ function delegationChecks(deps, args, targetShortName, targetDisplayName) {
 }
 function resolveTargetProfile(input) {
   if (typeof input !== "string" || !input.trim()) return void 0;
-  const profile = getProfile8(input.trim());
+  const profile = getProfile9(input.trim());
   if (!profile) return void 0;
   return { profile, shortName: shortName(profile.id) };
 }
@@ -9852,7 +10670,7 @@ function setupBuiltin(deps) {
           const guides = loadGuides();
           const systems = connectedSystems(deps.integrationManager);
           const running = new Set(systems.map((s) => s.id));
-          const inactive = getAllManifests().filter((m) => manifestIsSimulated(m) && !running.has(m.id)).map((m) => m.name);
+          const inactive = getAllManifests().filter((m) => deps.integrationManager.isSimulationSafe(m.id) && !running.has(m.id)).map((m) => m.name);
           const header = guideHeader(systems, inactive);
           const topic = typeof args.topic === "string" ? args.topic.trim().toLowerCase() : "";
           if (!topic) {
@@ -9870,7 +10688,7 @@ Read each topic with get_guide(topic) before doing that step.`);
             return { ...builtinText(`Unknown topic "${topic}". Topics: ${guides.map((g) => g.topic).join(", ") || "none installed"}.`), isError: true };
           }
           const body = fillGenerated(guide.body.trim(), {
-            limits: () => limitsSection(systems.map((s) => ({ id: s.id, profile: getProfile8(s.profile) }))),
+            limits: () => limitsSection(systems.map((s) => ({ id: s.id, profile: getProfile9(s.profile) }))),
             package: () => packageSection(
               deps.integrationManager.getAllTools().find((t) => !deps.integrationManager.isBuiltin(t.integrationId) && t.originalName === "load_simulation")
             )
@@ -10404,6 +11222,15 @@ app.post("/internal/preview", internalOnly, async (req, res) => {
   });
   res.json(result);
 });
+app.post("/internal/document-preview", internalOnly, async (req, res) => {
+  const { connector, kind, id, sha256 } = req.body;
+  if (!connector || !kind || !id || !sha256) {
+    res.status(400).json({ error: "Missing connector, kind, id, or sha256" });
+    return;
+  }
+  const result = await resolveAttachmentPreview(integrationManager, { connector, kind, id }, sha256);
+  res.json(result);
+});
 app.post("/internal/request-context", internalOnly, async (req, res) => {
   const { tool, toolArgs } = req.body;
   if (!tool || typeof toolArgs !== "object" || toolArgs === null) {