@suveren/gateway 0.28.0 → 0.29.0

package/dist/mcp-server/http.mjs

@@ -3180,7 +3180,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z2 } from "zod";
 
 // src/lib/mandate-brief.ts
-import { getProfile as getProfile3 } from "@hap/core";
+import { getProfile as getProfile4 } from "@hap/core";
 
 // src/lib/consumption.ts
 import { boundActionTypes } from "@hap/core";
@@ -3473,6 +3473,7 @@ import { join as join14, resolve } from "path";
 // src/lib/tool-gating-types.ts
 var MAX_PREVIEW_READS = 10;
 var MAX_FOREACH_ELEMENTS = 50;
+var MAX_RECORD_KEY_STEPS = 2;
 
 // 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-]+)*)?$/;
@@ -3597,6 +3598,231 @@ function invalidManifestPreviewReason(manifest) {
   }
   return null;
 }
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+var VALID_FIELD_PATH_PARSE = ["address.name", "address.email", "epoch-ms"];
+function invalidFieldPathReason(label, value) {
+  if (isNonEmptyString(value)) return null;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return `${label} must be a non-empty string or a field-path object`;
+  }
+  const f = value;
+  if (!isNonEmptyString(f.path)) return `${label}.path must be a non-empty string`;
+  if (f.where !== void 0) {
+    if (f.where === null || typeof f.where !== "object" || Array.isArray(f.where)) {
+      return `${label}.where must be an object`;
+    }
+    for (const [k, v] of Object.entries(f.where)) {
+      if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean") {
+        return `${label}.where.${k} must be a string, number, or boolean`;
+      }
+    }
+  }
+  if (f.pick !== void 0 && !isNonEmptyString(f.pick)) {
+    return `${label}.pick must be a non-empty string`;
+  }
+  if (f.parse !== void 0 && !VALID_FIELD_PATH_PARSE.includes(f.parse)) {
+    return `${label}.parse must be one of ${VALID_FIELD_PATH_PARSE.join(", ")}`;
+  }
+  return null;
+}
+function invalidContextReadReason(label, entry) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return `${label} must be an object`;
+  }
+  const r = entry;
+  if (!isNonEmptyString(r.tool)) return `${label}.tool must be a non-empty string`;
+  if (r.args === void 0 || r.args === null || typeof r.args !== "object" || Array.isArray(r.args)) {
+    return `${label}.args must be an object`;
+  }
+  for (const [k, v] of Object.entries(r.args)) {
+    if (typeof v !== "string" || v.length === 0) {
+      return `${label}.args.${k} must be a non-empty string`;
+    }
+  }
+  return null;
+}
+function invalidContextSourceReason(toolName, entry) {
+  const label = `context.sources.${toolName}`;
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return `${label} must be an object`;
+  }
+  const s = entry;
+  const readReason = invalidContextReadReason(`${label}.read`, s.read);
+  if (readReason) return readReason;
+  for (const field of ["title", "author", "at", "body"]) {
+    if (s[field] !== void 0) {
+      const reason = invalidFieldPathReason(`${label}.${field}`, s[field]);
+      if (reason) return reason;
+    }
+  }
+  if (s.keys !== void 0) {
+    if (s.keys === null || typeof s.keys !== "object" || Array.isArray(s.keys)) {
+      return `${label}.keys must be an object`;
+    }
+    for (const [k, v] of Object.entries(s.keys)) {
+      if (k !== "email") return `${label}.keys.${k}: only "email" is a recognized identity key type`;
+      const reason = invalidFieldPathReason(`${label}.keys.${k}`, v);
+      if (reason) return reason;
+    }
+  }
+  if (s.chain !== void 0) {
+    if (s.chain === null || typeof s.chain !== "object" || Array.isArray(s.chain)) {
+      return `${label}.chain must be an object`;
+    }
+    const c = s.chain;
+    if (!isNonEmptyString(c.field)) return `${label}.chain.field must be a non-empty string`;
+    if (typeof c.max !== "number" || c.max <= 0) return `${label}.chain.max must be a positive number`;
+  }
+  return null;
+}
+function invalidContextHistoryReason(history) {
+  const label = "context.history";
+  if (history === null || typeof history !== "object" || Array.isArray(history)) {
+    return `${label} must be an object`;
+  }
+  const h = history;
+  const isKeyType = (v) => v === "email" || v === "email_domain";
+  if (Array.isArray(h.byKey)) {
+    if (h.byKey.length === 0) return `${label}.byKey must not be an empty array`;
+    for (const [i, v] of h.byKey.entries()) {
+      if (!isKeyType(v)) return `${label}.byKey[${i}] must be "email" or "email_domain"`;
+    }
+  } else if (!isKeyType(h.byKey)) {
+    return `${label}.byKey must be "email" or "email_domain" (or an array of those, in preference order)`;
+  }
+  const readReason = invalidContextReadReason(`${label}.read`, h.read);
+  if (readReason) return readReason;
+  if (typeof h.limit !== "number" || h.limit <= 0) return `${label}.limit must be a positive number`;
+  if (typeof h.maxAgeDays !== "number" || h.maxAgeDays <= 0) return `${label}.maxAgeDays must be a positive number`;
+  if (h.item === null || typeof h.item !== "object" || Array.isArray(h.item)) {
+    return `${label}.item must be an object`;
+  }
+  for (const [k, v] of Object.entries(h.item)) {
+    if (k === "kind") {
+      if (!isNonEmptyString(v)) return `${label}.item.kind must be a non-empty string`;
+      continue;
+    }
+    const reason = invalidFieldPathReason(`${label}.item.${k}`, v);
+    if (reason) return reason;
+  }
+  return null;
+}
+function invalidContextRecordKeyReason(name, entry) {
+  const label = `context.recordKeys.${name}`;
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return `${label} must be an object`;
+  }
+  const rk = entry;
+  const readReason = invalidContextReadReason(`${label}.read`, rk.read);
+  if (readReason) return readReason;
+  if (rk.keys !== void 0) {
+    if (rk.keys === null || typeof rk.keys !== "object" || Array.isArray(rk.keys)) {
+      return `${label}.keys must be an object`;
+    }
+    for (const [k, v] of Object.entries(rk.keys)) {
+      if (k !== "email") return `${label}.keys.${k}: only "email" is a recognized identity key type`;
+      const reason = invalidFieldPathReason(`${label}.keys.${k}`, v);
+      if (reason) return reason;
+    }
+  }
+  if (rk.next !== void 0) {
+    if (rk.next === null || typeof rk.next !== "object" || Array.isArray(rk.next)) {
+      return `${label}.next must be an object`;
+    }
+    const next = rk.next;
+    if (!isNonEmptyString(next.recordKey)) return `${label}.next.recordKey must be a non-empty string`;
+    if (!isNonEmptyString(next.field)) return `${label}.next.field must be a non-empty string`;
+  }
+  if (rk.keys === void 0 && rk.next === void 0) {
+    return `${label} must declare "keys", "next", or both \u2014 an entry with neither learns nothing from the record it reads`;
+  }
+  return null;
+}
+function recordKeyChainLength(name, recordKeys, seen) {
+  if (seen.has(name)) return "cycle";
+  const entry = recordKeys[name];
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return "missing";
+  const next = entry.next;
+  if (!next || typeof next !== "object") return 1;
+  const nextName = next.recordKey;
+  if (typeof nextName !== "string" || !(nextName in recordKeys)) return "missing";
+  const rest = recordKeyChainLength(nextName, recordKeys, /* @__PURE__ */ new Set([...seen, name]));
+  if (rest === "cycle" || rest === "missing") return rest;
+  return 1 + rest;
+}
+function invalidManifestContextReason(manifest) {
+  const ctx = manifest.context;
+  const recordKeyNames = new Set(Object.keys(ctx?.recordKeys ?? {}));
+  if (ctx) {
+    if (ctx.sources !== void 0) {
+      if (ctx.sources === null || typeof ctx.sources !== "object" || Array.isArray(ctx.sources)) {
+        return "context.sources must be an object";
+      }
+      for (const [kind, entry] of Object.entries(ctx.sources)) {
+        const reason = invalidContextSourceReason(kind, entry);
+        if (reason) return reason;
+      }
+    }
+    if (ctx.history !== void 0) {
+      const reason = invalidContextHistoryReason(ctx.history);
+      if (reason) return reason;
+    }
+    if (ctx.recordKeys !== void 0) {
+      if (ctx.recordKeys === null || typeof ctx.recordKeys !== "object" || Array.isArray(ctx.recordKeys)) {
+        return "context.recordKeys must be an object";
+      }
+      for (const [name, entry] of Object.entries(ctx.recordKeys)) {
+        const reason = invalidContextRecordKeyReason(name, entry);
+        if (reason) return reason;
+      }
+      for (const name of Object.keys(ctx.recordKeys)) {
+        const length = recordKeyChainLength(name, ctx.recordKeys, /* @__PURE__ */ new Set());
+        if (length === "cycle") {
+          return `context.recordKeys.${name}.next forms a cycle`;
+        }
+        if (length === "missing") {
+          return `context.recordKeys.${name}.next.recordKey names an entry this manifest does not declare`;
+        }
+        if (length > MAX_RECORD_KEY_STEPS) {
+          return `context.recordKeys.${name}.next chain is ${length} steps long \u2014 max ${MAX_RECORD_KEY_STEPS}`;
+        }
+      }
+    }
+  }
+  const sourceKinds = new Set(Object.keys(ctx?.sources ?? {}));
+  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.contextKeys !== void 0) {
+      if (e.contextKeys === null || typeof e.contextKeys !== "object" || Array.isArray(e.contextKeys)) {
+        return `override "${toolName}".contextKeys must be an object`;
+      }
+      for (const [name, argName] of Object.entries(e.contextKeys)) {
+        if (!isNonEmptyString(argName)) {
+          return `override "${toolName}".contextKeys.${name} must be a non-empty string naming an action argument`;
+        }
+        if (name !== "email" && !recordKeyNames.has(name)) {
+          return `override "${toolName}".contextKeys.${name}: "${name}" is neither "email" nor a context.recordKeys entry on this manifest`;
+        }
+      }
+    }
+    if (e.sourceFromArg !== void 0) {
+      if (e.sourceFromArg === null || typeof e.sourceFromArg !== "object" || Array.isArray(e.sourceFromArg)) {
+        return `override "${toolName}".sourceFromArg must be an object`;
+      }
+      const sfa = e.sourceFromArg;
+      if (!isNonEmptyString(sfa.kind)) return `override "${toolName}".sourceFromArg.kind must be a non-empty string`;
+      if (!isNonEmptyString(sfa.arg)) return `override "${toolName}".sourceFromArg.arg must be a non-empty string`;
+      if (!sourceKinds.has(sfa.kind)) {
+        return `override "${toolName}".sourceFromArg.kind "${String(sfa.kind)}" is not declared in this manifest's context.sources`;
+      }
+    }
+  }
+  return null;
+}
 var manifests = /* @__PURE__ */ new Map();
 function loadManifests(integrationsDir) {
   const dir = resolve(
@@ -3629,6 +3855,11 @@ function loadManifests(integrationsDir) {
         console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${previewReason}`);
         continue;
       }
+      const contextReason = invalidManifestContextReason(manifest);
+      if (contextReason) {
+        console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${contextReason}`);
+        continue;
+      }
       manifests.set(id, manifest);
       loaded++;
     } catch (err) {
@@ -3887,30 +4118,629 @@ async function buildInternalPreview(integrationManager2, integrationId, toolName
   if (!preview.version) {
     return ok();
   }
-  const approved = actionArgs[preview.version.arg];
-  if (typeof approved !== "string" && typeof approved !== "number") {
-    return ok();
+  const approved = actionArgs[preview.version.arg];
+  if (typeof approved !== "string" && typeof approved !== "number") {
+    return ok();
+  }
+  const { [preview.version.arg]: _omit, ...withoutVersion } = actionArgs;
+  const mappedCurrentArgs = mapPreviewArgs(preview, withoutVersion);
+  const read2 = await readPreview(integrationManager2, integrationId, preview.tool, mappedCurrentArgs);
+  if (read2.status !== "ok" || read2.body.structured === void 0) {
+    return ok();
+  }
+  const current = read2.body.structured[preview.version.field];
+  if (typeof current !== "string" && typeof current !== "number") {
+    return ok();
+  }
+  const stale = String(current) !== String(approved);
+  return ok({
+    version: {
+      field: preview.version.field,
+      approved,
+      current,
+      stale,
+      ...stale ? { currentBody: read2.body } : {}
+    }
+  });
+}
+
+// src/lib/scope-specificity.ts
+function tokenSet(value) {
+  if (value === void 0 || value === null) return /* @__PURE__ */ new Set();
+  return new Set(
+    String(value).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)
+  );
+}
+function subsetOrEqual(a, b) {
+  if (b.size === 0) return true;
+  if (a.size === 0) return false;
+  for (const x of a) if (!b.has(x)) return false;
+  return true;
+}
+function atLeastAsSpecific(keys, a, b) {
+  for (const k of keys) {
+    if (!subsetOrEqual(tokenSet(a[k]), tokenSet(b[k]))) return false;
+  }
+  return true;
+}
+function strictlyMoreSpecific(keys, a, b) {
+  return atLeastAsSpecific(keys, a, b) && !atLeastAsSpecific(keys, b, a);
+}
+function selectAuthorization(contextKeys, passers) {
+  if (passers.length === 1) {
+    return { chosen: passers[0], superseded: [], reason: "sole" };
+  }
+  const dominators = passers.filter(
+    (a) => passers.every((b) => b === a || strictlyMoreSpecific(contextKeys, a.context, b.context))
+  );
+  if (dominators.length === 1) {
+    const chosen2 = dominators[0];
+    return { chosen: chosen2, superseded: passers.filter((p) => p !== chosen2), reason: "most-specific" };
+  }
+  const approvers = passers.filter((p) => p.requiresApproval);
+  const pool = approvers.length > 0 ? approvers : passers;
+  const chosen = pool.slice().sort((a, b) => a.id.localeCompare(b.id))[0];
+  return {
+    chosen,
+    superseded: passers.filter((p) => p !== chosen),
+    reason: approvers.length > 0 ? "fail-safe-approval" : "fail-safe-tiebreak"
+  };
+}
+
+// src/lib/read-gate.ts
+function boundsSatisfyReadGate(bounds, gate) {
+  if (!gate.boundField) return true;
+  const actual = bounds?.[gate.boundField];
+  return actual !== void 0 && String(actual) === gate.requiredValue;
+}
+function readToolIsGoverned(g) {
+  if (!g) return false;
+  return Boolean(g.boundField) || g.read != null || g.readGovernance === "none";
+}
+function allowedResources(contexts, boundField) {
+  const out = /* @__PURE__ */ new Set();
+  for (const ctx of contexts) {
+    for (const v of tokenSet(ctx?.[boundField])) out.add(v);
+  }
+  return out;
+}
+function deniedResources(requested, allowed) {
+  return requested.filter((r) => !allowed.has(r));
+}
+function filterItemsByResource(items, idPath, allowed) {
+  return items.filter((it) => {
+    const id = getByDottedPath(it, idPath);
+    return typeof id === "string" && allowed.has(id);
+  });
+}
+function hasBlockedValue(item, valuesPath, blocked) {
+  const v = getByDottedPath(item, valuesPath);
+  const arr = Array.isArray(v) ? v : v != null ? [v] : [];
+  return arr.some((x) => typeof x === "string" && blocked.has(x));
+}
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+function parseMessageTimestamp(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+    const iso = Date.parse(value);
+    if (Number.isFinite(iso)) return iso;
+  }
+  return null;
+}
+function ageInDays(timestampMs, nowMs) {
+  return Math.floor((nowMs - timestampMs) / MS_PER_DAY);
+}
+function maxReadAgeDays(boundsList, field) {
+  let max = null;
+  for (const b of boundsList) {
+    const raw = b?.[field];
+    const n = typeof raw === "number" ? raw : raw !== void 0 ? Number(raw) : NaN;
+    if (Number.isFinite(n)) max = max === null ? n : Math.max(max, n);
+  }
+  return max;
+}
+function isOlderThanMaxAge(timestampMs, maxAgeDays, nowMs) {
+  if (timestampMs === null) return true;
+  return ageInDays(timestampMs, nowMs) > maxAgeDays;
+}
+var TRAILING_OPERATOR = /(?:^|\s)(?:OR|AND|NOT)$|[-+|&:]$/i;
+function parensBalanced(s) {
+  let depth = 0;
+  let inQuote = false;
+  for (const c of s) {
+    if (c === '"') {
+      inQuote = !inQuote;
+      continue;
+    }
+    if (inQuote) continue;
+    if (c === "(") depth++;
+    else if (c === ")" && --depth < 0) return false;
+  }
+  return !inQuote && depth === 0;
+}
+function composeReadQuery(agentQuery, clauses) {
+  const injected = clauses.filter((c) => typeof c === "string" && c.trim() !== "").map((c) => c.trim());
+  const base = (agentQuery ?? "").trim();
+  if (base === "") return { ok: true, query: injected.join(" ") };
+  if (!parensBalanced(base)) {
+    return { ok: false, reason: "the requested search query has unbalanced parentheses" };
+  }
+  if (TRAILING_OPERATOR.test(base)) {
+    return { ok: false, reason: "the requested search query ends in a dangling operator" };
+  }
+  if (injected.length === 0) return { ok: true, query: base };
+  return { ok: true, query: `(${base}) ${injected.join(" ")}` };
+}
+function detectAgeConflict(agentQuery, conflictPattern, maxAgeDays) {
+  if (!agentQuery || !conflictPattern || maxAgeDays === null) return null;
+  let re;
+  try {
+    re = new RegExp(conflictPattern, "gi");
+  } catch {
+    return null;
+  }
+  let worst = null;
+  for (const match of agentQuery.matchAll(re)) {
+    const days = Number(match[1]);
+    if (!Number.isFinite(days)) continue;
+    if (days >= maxAgeDays && (worst === null || days > worst)) worst = days;
+  }
+  return worst;
+}
+function resolveAgeBoundField(boundsSchema, ageExecField) {
+  const fields = boundsSchema?.fields;
+  if (!fields) return null;
+  for (const [name, def] of Object.entries(fields)) {
+    if (def?.boundType?.kind === "per_transaction" && def.boundType.of === ageExecField) return name;
+  }
+  return null;
+}
+function getByDottedPath(obj, path) {
+  return path.split(".").reduce(
+    (o, k) => o == null ? void 0 : o[k],
+    obj
+  );
+}
+function firstParsableDate(obj, paths) {
+  for (const path of Array.isArray(paths) ? paths : [paths]) {
+    const parsed = parseMessageTimestamp(getByDottedPath(obj, path));
+    if (parsed !== null) return parsed;
+  }
+  return null;
+}
+function renderAgeConstraint(template, maxAgeDays, nowMs) {
+  const floorIso = new Date(nowMs - maxAgeDays * MS_PER_DAY).toISOString();
+  return template.replace(/\{days\}/g, String(maxAgeDays)).replace(/\{date\}/g, floorIso.slice(0, 10));
+}
+function ageFloorValue(maxAgeDays, nowMs, format = "iso") {
+  const floorMs = nowMs - maxAgeDays * MS_PER_DAY;
+  if (format === "epoch_ms") return floorMs;
+  if (format === "epoch_s") return String(Math.floor(floorMs / 1e3));
+  return new Date(floorMs).toISOString();
+}
+function clampAgeFloor(requested, maxAgeDays, nowMs, format = "iso") {
+  const floorMs = nowMs - maxAgeDays * MS_PER_DAY;
+  const asked = parseMessageTimestamp(requested);
+  if (asked !== null && asked >= floorMs) return requested;
+  return ageFloorValue(maxAgeDays, nowMs, format);
+}
+
+// src/lib/field-path.ts
+function matchesWhere(element, where) {
+  if (element === null || typeof element !== "object" || Array.isArray(element)) return false;
+  const row = element;
+  return Object.entries(where).every(([key, expected]) => {
+    const actual = row[key];
+    if (typeof expected === "string" && typeof actual === "string") {
+      return expected.toLowerCase() === actual.toLowerCase();
+    }
+    return actual === expected;
+  });
+}
+function parseAddress(value, which) {
+  const m = value.match(/^(.*?)<([^<>]+)>\s*$/);
+  if (m) {
+    const email = m[2].trim();
+    if (which === "address.email") return email || void 0;
+    const name = m[1].trim().replace(/^"(.*)"$/, "$1").trim();
+    return name || void 0;
+  }
+  if (which === "address.email") return value.trim() || void 0;
+  return void 0;
+}
+function parseEpochMs(value) {
+  const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  if (!Number.isFinite(n)) return void 0;
+  return new Date(n).toISOString();
+}
+function applyParse(value, parse2) {
+  if (value === void 0 || value === null) return void 0;
+  if (parse2 === "epoch-ms") return parseEpochMs(value);
+  if (typeof value !== "string") return void 0;
+  return parseAddress(value, parse2);
+}
+function resolveFieldPath(record, fieldPath) {
+  if (fieldPath === void 0) return void 0;
+  if (typeof fieldPath === "string") return getByDottedPath(record, fieldPath);
+  let value = getByDottedPath(record, fieldPath.path);
+  if (fieldPath.where) {
+    if (!Array.isArray(value)) return void 0;
+    value = value.find((el) => matchesWhere(el, fieldPath.where));
+    if (value === void 0) return void 0;
+  }
+  if (fieldPath.pick !== void 0) {
+    value = getByDottedPath(value, fieldPath.pick);
+  }
+  if (fieldPath.parse) {
+    value = applyParse(value, fieldPath.parse);
+  }
+  return value;
+}
+
+// src/lib/request-context.ts
+var SOURCE_LINK_ARG = "_source";
+function withSourceLink(schema) {
+  const props = schema.properties ?? {};
+  if ("_source" in props) return schema;
+  return {
+    ...schema,
+    properties: {
+      ...props,
+      _source: {
+        type: "object",
+        description: 'Optional. Link the request you are answering \u2014 the ONE record (e.g. an inbound email) this action responds to, so the human approver can see why it was proposed. Only a reference: {"connector": "<integration id>", "kind": "<declared kind>", "id": "<record id>"}. Example: {"connector":"mail","kind":"message","id":"m-17"}. The gateway reads the record itself \u2014 never write a summary or quote here.',
+        properties: {
+          connector: { type: "string" },
+          kind: { type: "string" },
+          id: { type: "string" }
+        }
+      }
+    }
+  };
+}
+function stripSourceLink(args) {
+  if (!(SOURCE_LINK_ARG in args)) return args;
+  const { [SOURCE_LINK_ARG]: _omit, ...rest } = args;
+  return rest;
+}
+var FREE_MAIL_DOMAINS = /* @__PURE__ */ new Set([
+  "gmail.com",
+  "googlemail.com",
+  "outlook.com",
+  "hotmail.com",
+  "hotmail.co.uk",
+  "hotmail.fr",
+  "hotmail.de",
+  "live.com",
+  "msn.com",
+  "yahoo.com",
+  "yahoo.co.uk",
+  "yahoo.de",
+  "yahoo.fr",
+  "ymail.com",
+  "rocketmail.com",
+  "gmx.de",
+  "gmx.net",
+  "gmx.at",
+  "gmx.ch",
+  "gmx.com",
+  "web.de",
+  "t-online.de",
+  "icloud.com",
+  "me.com",
+  "mac.com",
+  "aol.com",
+  "protonmail.com",
+  "proton.me",
+  "mail.com",
+  "zoho.com",
+  "yandex.com"
+]);
+function isFreeMailDomain(domain) {
+  return FREE_MAIL_DOMAINS.has(domain.toLowerCase());
+}
+function deriveIdentityKeysFromEmail(email) {
+  const lower = email.toLowerCase().trim();
+  const at = lower.lastIndexOf("@");
+  if (at <= 0 || at === lower.length - 1) return [];
+  const domain = lower.slice(at + 1);
+  const keys = [{ type: "email", value: lower }];
+  if (!isFreeMailDomain(domain)) keys.push({ type: "email_domain", value: domain });
+  return keys;
+}
+function deriveIdentityKeysFromValue(value) {
+  if (typeof value === "string") return deriveIdentityKeysFromEmail(value);
+  if (Array.isArray(value)) {
+    return value.flatMap((v) => typeof v === "string" ? deriveIdentityKeysFromEmail(v) : []);
+  }
+  return [];
+}
+function dedupeKeys(keys) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const k of keys) {
+    const sig = `${k.type}:${k.value}`;
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    out.push(k);
+  }
+  return out;
+}
+function substitute(template, values) {
+  const out = {};
+  for (const [arg, token] of Object.entries(template)) {
+    if (token.startsWith("$")) {
+      const key = token.slice(1);
+      if (key in values) out[arg] = values[key];
+    } else {
+      out[arg] = token;
+    }
+  }
+  return out;
+}
+function parseContextBody(body) {
+  if (body.structured !== void 0) return body.structured;
+  if (body.text !== void 0) {
+    try {
+      return JSON.parse(body.text);
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+async function readContextRecord(integrationManager2, connectorId, tool, args) {
+  const read = await readPreview(integrationManager2, connectorId, tool, args);
+  if (read.status === "ok") {
+    const record = parseContextBody(read.body);
+    if (record === void 0) return { status: "unavailable", reason: "connector_error" };
+    return { status: "ok", record };
+  }
+  if (read.status === "not_found") return { status: "not_found" };
+  return { status: "unavailable", reason: read.reason };
+}
+function parseExplicitSourceLink(raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (typeof raw !== "object" || Array.isArray(raw)) return "invalid";
+  const o = raw;
+  if (typeof o.connector !== "string" || !o.connector) return "invalid";
+  if (typeof o.kind !== "string" || !o.kind) return "invalid";
+  if (typeof o.id !== "string" || !o.id) return "invalid";
+  return { connector: o.connector, kind: o.kind, id: o.id };
+}
+function resolveSourceLink(toolArgs, connectorId, sourceFromArg) {
+  const explicit = parseExplicitSourceLink(toolArgs._source);
+  if (explicit !== void 0) return explicit;
+  if (sourceFromArg) {
+    const argVal = toolArgs[sourceFromArg.arg];
+    if (typeof argVal === "string" && argVal) {
+      return { connector: connectorId, kind: sourceFromArg.kind, id: argVal };
+    }
+  }
+  return void 0;
+}
+async function readSourceOnce(integrationManager2, link, sourceConfig) {
+  const args = substitute(sourceConfig.read.args, { id: link.id });
+  const read = await readContextRecord(integrationManager2, link.connector, sourceConfig.read.tool, args);
+  if (read.status === "not_found") return { status: "not_found" };
+  if (read.status === "unavailable") return { status: "unreadable", reason: read.reason };
+  const keys = [];
+  if (sourceConfig.keys?.email) {
+    const v = resolveFieldPath(read.record, sourceConfig.keys.email);
+    if (typeof v === "string" && v) keys.push(...deriveIdentityKeysFromEmail(v));
+  }
+  return { record: read.record, keys };
+}
+async function resolveRequestContext(integrationManager2, toolArgs, actionConnectorId, sourceFromArg, configuredConnectorIds) {
+  const link = resolveSourceLink(toolArgs, actionConnectorId, sourceFromArg);
+  if (link === void 0) return { result: { status: "none" }, keys: [] };
+  if (link === "invalid") {
+    return { result: { status: "unreadable", reason: "malformed link" }, keys: [] };
+  }
+  if (!configuredConnectorIds.has(link.connector)) {
+    return { result: { status: "unreadable", reason: "connector not installed" }, keys: [] };
+  }
+  const connectorManifest = getManifest(link.connector);
+  if (!connectorManifest) {
+    return { result: { status: "unreadable", reason: "connector not installed" }, keys: [] };
+  }
+  const sourceConfig = connectorManifest.context?.sources?.[link.kind];
+  if (!sourceConfig) {
+    return { result: { status: "unreadable", reason: `connector "${link.connector}" declares no "${link.kind}" source` }, keys: [] };
+  }
+  const primary = await readSourceOnce(integrationManager2, link, sourceConfig);
+  if ("status" in primary) {
+    if (primary.status === "not_found") return { result: { status: "not_found" }, keys: [] };
+    return { result: { status: "unreadable", reason: primary.reason ?? "connector unreachable" }, keys: [] };
+  }
+  const implicit = toolArgs._source === void 0;
+  const base = {
+    connector: link.connector,
+    kind: link.kind,
+    implicit,
+    ...sourceConfig.title ? { title: asString(resolveFieldPath(primary.record, sourceConfig.title)) } : {},
+    ...sourceConfig.author ? { author: asString(resolveFieldPath(primary.record, sourceConfig.author)) } : {},
+    ...sourceConfig.at ? { at: asString(resolveFieldPath(primary.record, sourceConfig.at)) } : {},
+    ...sourceConfig.body ? { body: asBody(resolveFieldPath(primary.record, sourceConfig.body)) } : {}
+  };
+  const chain = [];
+  if (sourceConfig.chain) {
+    let currentId = asString(getByDottedPath(primary.record, sourceConfig.chain.field));
+    let hops = 0;
+    const seen = /* @__PURE__ */ new Set([link.id]);
+    while (currentId && hops < sourceConfig.chain.max && !seen.has(currentId)) {
+      seen.add(currentId);
+      const hopLink = { connector: link.connector, kind: link.kind, id: currentId };
+      const hop = await readSourceOnce(integrationManager2, hopLink, sourceConfig);
+      hops++;
+      if ("status" in hop) break;
+      chain.push({
+        ...sourceConfig.author ? { author: asString(resolveFieldPath(hop.record, sourceConfig.author)) } : {},
+        ...sourceConfig.at ? { at: asString(resolveFieldPath(hop.record, sourceConfig.at)) } : {},
+        ...sourceConfig.title ? { title: asString(resolveFieldPath(hop.record, sourceConfig.title)) } : {},
+        ...sourceConfig.body ? { body: asBody(resolveFieldPath(hop.record, sourceConfig.body)) } : {}
+      });
+      currentId = sourceConfig.chain ? asString(getByDottedPath(hop.record, sourceConfig.chain.field)) : void 0;
+    }
+  }
+  return { result: { status: "ok", ...base, chain }, keys: primary.keys };
+}
+function asString(v) {
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+var REQUEST_BODY_CAP = 2e4;
+function asBody(v) {
+  const s = asString(v);
+  return s === void 0 ? void 0 : s.length > REQUEST_BODY_CAP ? s.slice(0, REQUEST_BODY_CAP) : s;
+}
+async function resolveRecordKeyChain(integrationManager2, connectorId, manifest, recordKeyName, idValue, stepsLeft) {
+  if (stepsLeft <= 0) return [];
+  const recordKey = manifest.context?.recordKeys?.[recordKeyName];
+  if (!recordKey) return [];
+  const args = substitute(recordKey.read.args, { id: idValue });
+  const read = await readContextRecord(integrationManager2, connectorId, recordKey.read.tool, args);
+  if (read.status !== "ok") return [];
+  const out = [];
+  const emailField = recordKey.keys?.email;
+  if (emailField) {
+    const v = resolveFieldPath(read.record, emailField);
+    if (typeof v === "string" && v) out.push(...deriveIdentityKeysFromEmail(v));
+  }
+  if (recordKey.next) {
+    const nextId = asString(getByDottedPath(read.record, recordKey.next.field));
+    if (nextId) {
+      out.push(
+        ...await resolveRecordKeyChain(
+          integrationManager2,
+          connectorId,
+          manifest,
+          recordKey.next.recordKey,
+          nextId,
+          stepsLeft - 1
+        )
+      );
+    }
+  }
+  return out;
+}
+async function gatherContextKeysFromAction(integrationManager2, connectorId, contextKeys, toolArgs) {
+  if (!contextKeys) return [];
+  const manifest = getManifest(connectorId);
+  const out = [];
+  for (const [name, argName] of Object.entries(contextKeys)) {
+    const raw = toolArgs[argName];
+    if (raw === void 0 || raw === null) continue;
+    if (name === "email") {
+      out.push(...deriveIdentityKeysFromValue(raw));
+      continue;
+    }
+    if (!manifest?.context?.recordKeys?.[name] || typeof raw !== "string" || !raw) continue;
+    out.push(...await resolveRecordKeyChain(integrationManager2, connectorId, manifest, name, raw, MAX_RECORD_KEY_STEPS));
   }
-  const { [preview.version.arg]: _omit, ...withoutVersion } = actionArgs;
-  const mappedCurrentArgs = mapPreviewArgs(preview, withoutVersion);
-  const read2 = await readPreview(integrationManager2, integrationId, preview.tool, mappedCurrentArgs);
-  if (read2.status !== "ok" || read2.body.structured === void 0) {
-    return ok();
+  return out;
+}
+function mapHistoryItem(raw, mapping) {
+  return {
+    // `kind` is a literal label, copied as-is — never a path (doc §8.1).
+    ...mapping.kind ? { kind: mapping.kind } : {},
+    ...mapping.title ? { title: asString(resolveFieldPath(raw, mapping.title)) } : {},
+    ...mapping.body ? { body: asBody(resolveFieldPath(raw, mapping.body)) } : {},
+    ...mapping.at ? { at: asString(resolveFieldPath(raw, mapping.at)) } : {},
+    ...mapping.author ? { author: asString(resolveFieldPath(raw, mapping.author)) } : {},
+    ...mapping.type ? { type: asString(resolveFieldPath(raw, mapping.type)) } : {}
+  };
+}
+function withinWindow(at, cutoffMs) {
+  if (!at) return true;
+  const ms = Date.parse(at);
+  if (Number.isNaN(ms)) return true;
+  return ms >= cutoffMs;
+}
+function chooseHistoryKey(byKey, keys) {
+  const order = Array.isArray(byKey) ? byKey : [byKey];
+  for (const type of order) {
+    const found = keys.find((k) => k.type === type);
+    if (found) return found;
   }
-  const current = read2.body.structured[preview.version.field];
-  if (typeof current !== "string" && typeof current !== "number") {
-    return ok();
+  return void 0;
+}
+function resolveHistoryArgsTemplate(template, keyType) {
+  const out = {};
+  for (const [argName, token] of Object.entries(template)) {
+    out[argName === "$keyType" ? keyType : argName] = token;
   }
-  const stale = String(current) !== String(approved);
-  return ok({
-    version: {
-      field: preview.version.field,
-      approved,
-      current,
-      stale,
-      ...stale ? { currentBody: read2.body } : {}
-    }
+  return out;
+}
+async function readConnectorHistory(integrationManager2, connectorId, history, keys, executionJournal) {
+  const key = chooseHistoryKey(history.byKey, keys);
+  if (!key) return { status: "no_match" };
+  const sinceMs = Date.now() - history.maxAgeDays * 24 * 60 * 60 * 1e3;
+  const args = substitute(resolveHistoryArgsTemplate(history.read.args, key.type), {
+    key: key.value,
+    since: new Date(sinceMs).toISOString(),
+    limit: history.limit
   });
+  const read = await readContextRecord(integrationManager2, connectorId, history.read.tool, args);
+  if (read.status !== "ok") return { status: "unreachable" };
+  const rows = Array.isArray(read.record) ? read.record : [];
+  const items = [];
+  for (const row of rows.slice(0, history.limit)) {
+    const item = mapHistoryItem(row, history.item);
+    if (!withinWindow(item.at, sinceMs)) continue;
+    if (history.item.ticket) {
+      const ticketId = asString(resolveFieldPath(row, history.item.ticket));
+      if (ticketId) {
+        const entry = executionJournal.get(ticketId);
+        if (entry?.state === "done") {
+          item.aiWritten = { at: entry.finishedAt ? entry.finishedAt * 1e3 : void 0 };
+        }
+      }
+    }
+    items.push(item);
+  }
+  return { status: "ok", match: { connectorId, matchedKeyType: key.type, matchedKeyValue: key.value, items } };
+}
+async function buildHistory(integrationManager2, keys, executionJournal, configuredConnectorIds) {
+  if (keys.length === 0) return { status: "no_customer_link" };
+  const connectors = getAllManifests().filter((m) => m.context?.history && configuredConnectorIds.has(m.id));
+  if (connectors.length === 0) return { status: "no_match" };
+  const matches = [];
+  const unreachable = [];
+  let anyMatchedType = false;
+  for (const manifest of connectors) {
+    const history = manifest.context.history;
+    const outcome = await readConnectorHistory(integrationManager2, manifest.id, history, keys, executionJournal);
+    if (outcome.status === "no_match") continue;
+    anyMatchedType = true;
+    if (outcome.status === "unreachable") {
+      unreachable.push(manifest.id);
+      continue;
+    }
+    matches.push(outcome.match);
+  }
+  if (!anyMatchedType) return { status: "no_match" };
+  if (matches.length === 0 && unreachable.length > 0) return { status: "unreachable", connectorIds: unreachable };
+  return { status: "ok", matches, unreachableConnectorIds: unreachable };
+}
+async function buildRequestContext(integrationManager2, executionJournal, actionConnectorId, toolArgs, actionGating, configuredConnectorIds) {
+  const { result: request, keys: sourceKeys } = await resolveRequestContext(
+    integrationManager2,
+    toolArgs,
+    actionConnectorId,
+    actionGating?.sourceFromArg,
+    configuredConnectorIds
+  );
+  const actionKeys = await gatherContextKeysFromAction(
+    integrationManager2,
+    actionConnectorId,
+    actionGating?.contextKeys,
+    toolArgs
+  );
+  const keys = dedupeKeys([...actionKeys, ...sourceKeys]);
+  const history = await buildHistory(integrationManager2, keys, executionJournal, configuredConnectorIds);
+  return { request, history };
 }
 
 // src/lib/ticket-verify.ts
@@ -4116,191 +4946,34 @@ function normalizeIncomingArgs(tool, args) {
   return out ?? args;
 }
 
-// src/lib/scope-specificity.ts
-function tokenSet(value) {
-  if (value === void 0 || value === null) return /* @__PURE__ */ new Set();
-  return new Set(
-    String(value).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)
-  );
-}
-function subsetOrEqual(a, b) {
-  if (b.size === 0) return true;
-  if (a.size === 0) return false;
-  for (const x of a) if (!b.has(x)) return false;
-  return true;
-}
-function atLeastAsSpecific(keys, a, b) {
-  for (const k of keys) {
-    if (!subsetOrEqual(tokenSet(a[k]), tokenSet(b[k]))) return false;
-  }
-  return true;
-}
-function strictlyMoreSpecific(keys, a, b) {
-  return atLeastAsSpecific(keys, a, b) && !atLeastAsSpecific(keys, b, a);
-}
-function selectAuthorization(contextKeys, passers) {
-  if (passers.length === 1) {
-    return { chosen: passers[0], superseded: [], reason: "sole" };
-  }
-  const dominators = passers.filter(
-    (a) => passers.every((b) => b === a || strictlyMoreSpecific(contextKeys, a.context, b.context))
-  );
-  if (dominators.length === 1) {
-    const chosen2 = dominators[0];
-    return { chosen: chosen2, superseded: passers.filter((p) => p !== chosen2), reason: "most-specific" };
-  }
-  const approvers = passers.filter((p) => p.requiresApproval);
-  const pool = approvers.length > 0 ? approvers : passers;
-  const chosen = pool.slice().sort((a, b) => a.id.localeCompare(b.id))[0];
-  return {
-    chosen,
-    superseded: passers.filter((p) => p !== chosen),
-    reason: approvers.length > 0 ? "fail-safe-approval" : "fail-safe-tiebreak"
-  };
-}
-
-// src/lib/read-gate.ts
-function boundsSatisfyReadGate(bounds, gate) {
-  if (!gate.boundField) return true;
-  const actual = bounds?.[gate.boundField];
-  return actual !== void 0 && String(actual) === gate.requiredValue;
-}
-function readToolIsGoverned(g) {
-  if (!g) return false;
-  return Boolean(g.boundField) || g.read != null || g.readGovernance === "none";
-}
-function allowedResources(contexts, boundField) {
+// src/lib/numeric-execution.ts
+import { getProfile as getProfile2 } from "@hap/core";
+function parseNumericString(value) {
+  if (!/^-?\d+(\.\d+)?$/.test(value)) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function declaredNumericFields(profile) {
   const out = /* @__PURE__ */ new Set();
-  for (const ctx of contexts) {
-    for (const v of tokenSet(ctx?.[boundField])) out.add(v);
-  }
-  return out;
-}
-function deniedResources(requested, allowed) {
-  return requested.filter((r) => !allowed.has(r));
-}
-function filterItemsByResource(items, idPath, allowed) {
-  return items.filter((it) => {
-    const id = getByDottedPath(it, idPath);
-    return typeof id === "string" && allowed.has(id);
-  });
-}
-function hasBlockedValue(item, valuesPath, blocked) {
-  const v = getByDottedPath(item, valuesPath);
-  const arr = Array.isArray(v) ? v : v != null ? [v] : [];
-  return arr.some((x) => typeof x === "string" && blocked.has(x));
-}
-var MS_PER_DAY = 24 * 60 * 60 * 1e3;
-function parseMessageTimestamp(value) {
-  if (typeof value === "number" && Number.isFinite(value)) return value;
-  if (typeof value === "string" && value.trim() !== "") {
-    const n = Number(value);
-    if (Number.isFinite(n)) return n;
-    const iso = Date.parse(value);
-    if (Number.isFinite(iso)) return iso;
-  }
-  return null;
-}
-function ageInDays(timestampMs, nowMs) {
-  return Math.floor((nowMs - timestampMs) / MS_PER_DAY);
-}
-function maxReadAgeDays(boundsList, field) {
-  let max = null;
-  for (const b of boundsList) {
-    const raw = b?.[field];
-    const n = typeof raw === "number" ? raw : raw !== void 0 ? Number(raw) : NaN;
-    if (Number.isFinite(n)) max = max === null ? n : Math.max(max, n);
-  }
-  return max;
-}
-function isOlderThanMaxAge(timestampMs, maxAgeDays, nowMs) {
-  if (timestampMs === null) return true;
-  return ageInDays(timestampMs, nowMs) > maxAgeDays;
-}
-var TRAILING_OPERATOR = /(?:^|\s)(?:OR|AND|NOT)$|[-+|&:]$/i;
-function parensBalanced(s) {
-  let depth = 0;
-  let inQuote = false;
-  for (const c of s) {
-    if (c === '"') {
-      inQuote = !inQuote;
-      continue;
-    }
-    if (inQuote) continue;
-    if (c === "(") depth++;
-    else if (c === ")" && --depth < 0) return false;
-  }
-  return !inQuote && depth === 0;
-}
-function composeReadQuery(agentQuery, clauses) {
-  const injected = clauses.filter((c) => typeof c === "string" && c.trim() !== "").map((c) => c.trim());
-  const base = (agentQuery ?? "").trim();
-  if (base === "") return { ok: true, query: injected.join(" ") };
-  if (!parensBalanced(base)) {
-    return { ok: false, reason: "the requested search query has unbalanced parentheses" };
-  }
-  if (TRAILING_OPERATOR.test(base)) {
-    return { ok: false, reason: "the requested search query ends in a dangling operator" };
-  }
-  if (injected.length === 0) return { ok: true, query: base };
-  return { ok: true, query: `(${base}) ${injected.join(" ")}` };
-}
-function detectAgeConflict(agentQuery, conflictPattern, maxAgeDays) {
-  if (!agentQuery || !conflictPattern || maxAgeDays === null) return null;
-  let re;
-  try {
-    re = new RegExp(conflictPattern, "gi");
-  } catch {
-    return null;
-  }
-  let worst = null;
-  for (const match of agentQuery.matchAll(re)) {
-    const days = Number(match[1]);
-    if (!Number.isFinite(days)) continue;
-    if (days >= maxAgeDays && (worst === null || days > worst)) worst = days;
-  }
-  return worst;
-}
-function resolveAgeBoundField(boundsSchema, ageExecField) {
-  const fields = boundsSchema?.fields;
-  if (!fields) return null;
+  const fields = profile?.executionContextSchema?.fields;
+  if (!fields) return out;
   for (const [name, def] of Object.entries(fields)) {
-    if (def?.boundType?.kind === "per_transaction" && def.boundType.of === ageExecField) return name;
+    if (def.source === "declared" && def.constraint?.type === "number") out.add(name);
   }
-  return null;
-}
-function getByDottedPath(obj, path) {
-  return path.split(".").reduce(
-    (o, k) => o == null ? void 0 : o[k],
-    obj
-  );
+  return out;
 }
-function firstParsableDate(obj, paths) {
-  for (const path of Array.isArray(paths) ? paths : [paths]) {
-    const parsed = parseMessageTimestamp(getByDottedPath(obj, path));
-    if (parsed !== null) return parsed;
+function coerceDeclaredNumericFields(profileId, execution) {
+  const fields = declaredNumericFields(getProfile2(profileId));
+  for (const field of fields) {
+    const value = execution[field];
+    if (typeof value !== "string") continue;
+    const parsed = parseNumericString(value);
+    if (parsed !== void 0) execution[field] = parsed;
   }
-  return null;
-}
-function renderAgeConstraint(template, maxAgeDays, nowMs) {
-  const floorIso = new Date(nowMs - maxAgeDays * MS_PER_DAY).toISOString();
-  return template.replace(/\{days\}/g, String(maxAgeDays)).replace(/\{date\}/g, floorIso.slice(0, 10));
-}
-function ageFloorValue(maxAgeDays, nowMs, format = "iso") {
-  const floorMs = nowMs - maxAgeDays * MS_PER_DAY;
-  if (format === "epoch_ms") return floorMs;
-  if (format === "epoch_s") return String(Math.floor(floorMs / 1e3));
-  return new Date(floorMs).toISOString();
-}
-function clampAgeFloor(requested, maxAgeDays, nowMs, format = "iso") {
-  const floorMs = nowMs - maxAgeDays * MS_PER_DAY;
-  const asked = parseMessageTimestamp(requested);
-  if (asked !== null && asked >= floorMs) return requested;
-  return ageFloorValue(maxAgeDays, nowMs, format);
 }
 
 // src/lib/tool-proxy.ts
-import { getProfile as getProfile2, ContentBindingError, boundActionTypes as boundActionTypes2 } from "@hap/core";
+import { getProfile as getProfile3, ContentBindingError, boundActionTypes as boundActionTypes2 } from "@hap/core";
 import { readFile } from "fs/promises";
 import { extname } from "path";
 import { randomUUID } from "crypto";
@@ -4372,7 +5045,7 @@ function profileMatches(profileId, shortName2) {
   return profileId === shortName2 || profileId.includes("/" + shortName2 + "@") || profileId.endsWith("/" + shortName2);
 }
 function wireExecutionContext(profileId, execution) {
-  const profile = getProfile2(profileId);
+  const profile = getProfile3(profileId);
   const allowed = /* @__PURE__ */ new Set(["action_type"]);
   const fields = profile?.boundsSchema?.fields;
   if (fields) {
@@ -4390,7 +5063,7 @@ function wireExecutionContext(profileId, execution) {
   return out;
 }
 function countBoundsFor(profileId, actionType) {
-  const fields = getProfile2(profileId)?.boundsSchema?.fields;
+  const fields = getProfile3(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);
@@ -4409,8 +5082,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;
@@ -4463,7 +5138,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(getProfile2(pick.profileId)?.scopeSchema?.fields?.[pick.field]) : false;
+  const scoped = pick.field ? Boolean(getProfile3(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",
@@ -4642,7 +5317,7 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
           );
         }
       }
-      const readProfile = readAdapter ? getProfile2(matchingAuths[0].profileId) : void 0;
+      const readProfile = readAdapter ? getProfile3(matchingAuths[0].profileId) : void 0;
       const boundsSchema = readProfile?.boundsSchema;
       const ageBoundField = readAdapter?.ageField ? resolveAgeBoundField(boundsSchema, readAdapter.ageField) : null;
       const hasAgeDimension = Boolean(readAdapter?.ageField);
@@ -4787,6 +5462,7 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
         }
       }
     }
+    coerceDeclaredNumericFields(profile, execution);
     const declaredActionType = typeof execution.action_type === "string" && execution.action_type.length > 0 ? execution.action_type : void 0;
     if (!declaredActionType) {
       recordBlocked(state2, tool, {
@@ -4805,7 +5481,7 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
       };
     }
     {
-      const profileDef = getProfile2(profile);
+      const profileDef = getProfile3(profile);
       const registry = profileDef?.boundsSchema?.actionTypes;
       if (Array.isArray(registry) && registry.length > 0 && !registry.includes(declaredActionType)) {
         recordBlocked(state2, tool, {
@@ -4826,6 +5502,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 = [];
@@ -4878,7 +5566,7 @@ function createGatedToolHandlerInner(tool, integrationManager2, state2) {
         isError: true
       };
     }
-    const contextKeys = getProfile2(passers[0].profileId)?.scopeSchema?.keyOrder ?? [];
+    const contextKeys = getProfile3(passers[0].profileId)?.scopeSchema?.keyOrder ?? [];
     return attemptWithCandidates(passers);
     async function attemptWithCandidates(candidates) {
       const selection = selectAuthorization(
@@ -5180,6 +5868,7 @@ Proposal ID: ${proposal.id}. Use check-pending-commitments to track status.` + a
       let outgoingArgs = shouldAttachFooter() && receiptId ? appendVerificationFooter(tool, args, receiptId, auth.subjects?.[0]) : args;
       if (receiptId) outgoingArgs = attachTicketId(tool, outgoingArgs, receiptId);
       outgoingArgs = encodeOutgoingArgs(tool, outgoingArgs);
+      outgoingArgs = stripSourceLink(outgoingArgs);
       if (receiptId) {
         const begun = state2.executionJournal.begin({
           ticketId: receiptId,
@@ -5256,7 +5945,8 @@ function agentVisibleAuthorizations(authorizations, integrationManager2) {
 // src/lib/agent-rules.ts
 var AGENT_RULES = [
   "Never open or operate the Suveren Gateway's web page \u2014 not in a browser you control, not with computer use. Never ask for, read or type the person's API key. Never approve a proposal: approvals are the person's alone.",
-  "Use only the Suveren tools. No terminal, HTTP or browser calls to the gateway's ports (for example `curl localhost:3500/mcp`)."
+  "Use only the Suveren tools. No terminal, HTTP or browser calls to the gateway's ports (for example `curl localhost:3500/mcp`).",
+  "When a tool offers an optional `_source` argument, set it to link the ONE record (e.g. an inbound email) you are acting on \u2014 just the reference ({connector, kind, id}), never a summary or quote; the gateway reads the record itself for the approver."
 ];
 
 // src/lib/mandate-brief.ts
@@ -5336,7 +6026,7 @@ function buildMandateBrief(opts) {
       const parts = [];
       if (boundsDesc) parts.push(boundsDesc);
       if (executionLog) {
-        const profile = getProfile3(auth.profileId) ?? getProfile3(shortName2);
+        const profile = getProfile4(auth.profileId) ?? getProfile4(shortName2);
         const consumption = getConsumptionState(auth, executionLog, profile);
         const compact = formatConsumptionCompact(consumption);
         if (compact) parts.push(compact);
@@ -5374,7 +6064,7 @@ function buildMandateBrief(opts) {
 }
 
 // src/tools/authorizations.ts
-import { getProfile as getProfile4 } from "@hap/core";
+import { getProfile as getProfile5 } from "@hap/core";
 function shortProfileName2(profileId) {
   const withoutVersion = profileId.replace(/@.*$/, "");
   const parts = withoutVersion.split("/");
@@ -5492,7 +6182,7 @@ function listAuthorizationsHandler(state2, integrationManager2, contextDir) {
         } catch {
         }
         const shortName2 = shortProfileName2(auth.profileId);
-        const profile = getProfile4(auth.profileId) ?? getProfile4(shortName2);
+        const profile = getProfile5(auth.profileId) ?? getProfile5(shortName2);
         if (profile) {
           const consumption = getConsumptionState(auth, state2.executionLog, profile);
           const consumptionText = formatConsumptionFull(consumption);
@@ -5552,7 +6242,7 @@ function listAuthorizationsHandler(state2, integrationManager2, contextDir) {
           lines.push("    Mode: review (each action requires your approval)");
         }
         const shortName2 = shortProfileName2(auth.profileId);
-        const profile = getProfile4(auth.profileId) ?? getProfile4(shortName2);
+        const profile = getProfile5(auth.profileId) ?? getProfile5(shortName2);
         if (profile) {
           const consumption = getConsumptionState(auth, state2.executionLog, profile);
           const compact = formatConsumptionCompact(consumption);
@@ -6006,6 +6696,7 @@ async function executeCommitted(proposal, state2, integrationManager2) {
       outgoingArgs = attachTicketId(discovered, outgoingArgs, receiptId);
       outgoingArgs = encodeOutgoingArgs(discovered, outgoingArgs);
     }
+    outgoingArgs = stripSourceLink(outgoingArgs);
     let result;
     try {
       result = await integrationManager2.callTool(integrationId, toolName, outgoingArgs);
@@ -7104,19 +7795,19 @@ var IntegrationManager = class {
     const profileGating = config.toolGating ?? null;
     const tools = (toolsResult.tools ?? []).map((tool) => {
       const gating = this.resolveToolGating(config.profile, profileGating, tool.name);
+      let inputSchema = withoutBlockedArgs(
+        tool.inputSchema ?? {},
+        gating?.blockedArgs
+      );
+      if (gating && gating.category !== "read" && gating.category !== "disabled") {
+        inputSchema = withSourceLink(inputSchema);
+      }
       return {
         originalName: tool.name,
         namespacedName: `${config.id}__${tool.name}`,
         integrationId: config.id,
         description: tool.description ?? "",
-        // A downstream schema otherwise reaches the agent verbatim, so a
-        // connector can offer a control-bypassing argument and we would pass it
-        // straight on. Anything the manifest blocks is removed here, before the
-        // agent ever sees it exists.
-        inputSchema: withoutBlockedArgs(
-          tool.inputSchema ?? {},
-          gating?.blockedArgs
-        ),
+        inputSchema,
         outputSchema: tool.outputSchema,
         gating
       };
@@ -7493,6 +8184,7 @@ var IntegrationManager = class {
           readGovernanceReason: ext.readGovernanceReason,
           blockedArgs: ext.blockedArgs,
           hideUnlessAuthorized: ext.hideUnlessAuthorized,
+          simulationOnly: ext.simulationOnly,
           approvalView: ext.approvalView
         };
       }
@@ -7509,7 +8201,10 @@ var IntegrationManager = class {
         argEncoding: ext.argEncoding,
         argNormalization: ext.argNormalization,
         hideUnlessAuthorized: ext.hideUnlessAuthorized,
-        approvalView: ext.approvalView
+        simulationOnly: ext.simulationOnly,
+        approvalView: ext.approvalView,
+        contextKeys: ext.contextKeys,
+        sourceFromArg: ext.sourceFromArg
       };
     }
     return {
@@ -7640,7 +8335,7 @@ async function buildTicketDetails(archive, ticketIds) {
 }
 
 // src/lib/report/window.ts
-import { getProfile as getProfile5 } from "@hap/core";
+import { getProfile as getProfile6 } from "@hap/core";
 var REPORT_AGE_FIELD = "read_age_days";
 var REPORTING_PROFILE = "reporting";
 var END_SKEW_SECONDS = 120;
@@ -7654,7 +8349,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) => getProfile5(id);
+var defaultLookup = (id) => getProfile6(id);
 function reportingMandateRefusal(m, lookup = defaultLookup) {
   const schema = lookup(m.profileId)?.boundsSchema;
   const field = resolveAgeBoundField(schema, REPORT_AGE_FIELD);
@@ -8392,7 +9087,7 @@ function unifiedLineDiff(before, after) {
 }
 
 // src/lib/builtins/setup.ts
-import { getProfile as getProfile6 } from "@hap/core";
+import { getProfile as getProfile7 } 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.",
@@ -8444,7 +9139,7 @@ function delegationItselfRefusal(args) {
 }
 function delegationMandateRefusal(auth) {
   if (isSimulationMode()) return void 0;
-  const profile = getProfile6(auth.profileId);
+  const profile = getProfile7(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.`;
 }
@@ -8502,7 +9197,7 @@ function delegationChecks(deps, args, targetShortName, targetDisplayName) {
   );
   const first = governing[0];
   if (first) {
-    const delegationProfile = getProfile6(first.profileId);
+    const delegationProfile = getProfile7(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}`);
@@ -8512,7 +9207,7 @@ function delegationChecks(deps, args, targetShortName, targetDisplayName) {
 }
 function resolveTargetProfile(input) {
   if (typeof input !== "string" || !input.trim()) return void 0;
-  const profile = getProfile6(input.trim());
+  const profile = getProfile7(input.trim());
   if (!profile) return void 0;
   return { profile, shortName: shortName(profile.id) };
 }
@@ -8663,7 +9358,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: getProfile6(s.profile) }))),
+            limits: () => limitsSection(systems.map((s) => ({ id: s.id, profile: getProfile7(s.profile) }))),
             package: () => packageSection(
               deps.integrationManager.getAllTools().find((t) => !deps.integrationManager.isBuiltin(t.integrationId) && t.originalName === "load_simulation")
             )
@@ -9150,6 +9845,32 @@ app.post("/internal/preview", internalOnly, async (req, res) => {
   });
   res.json(result);
 });
+app.post("/internal/request-context", internalOnly, async (req, res) => {
+  const { tool, toolArgs } = req.body;
+  if (!tool || typeof toolArgs !== "object" || toolArgs === null) {
+    res.status(400).json({ error: "Missing tool or toolArgs" });
+    return;
+  }
+  const sep = tool.indexOf("__");
+  if (sep < 0) {
+    res.status(400).json({ error: `Invalid tool name: ${tool}` });
+    return;
+  }
+  const integrationId = tool.slice(0, sep);
+  const toolName = tool.slice(sep + 2);
+  const manifest = getManifest(integrationId);
+  const actionGating = manifest?.toolGating?.overrides?.[toolName];
+  const configuredConnectorIds = new Set(integrationRegistry.getAll().map((c) => c.id));
+  const result = await buildRequestContext(
+    integrationManager,
+    state.executionJournal,
+    integrationId,
+    toolArgs,
+    actionGating ?? void 0,
+    configuredConnectorIds
+  );
+  res.json(result);
+});
 app.post("/internal/add-integration", internalOnly, async (req, res) => {
   try {
     const config = req.body;