@suveren/gateway 0.16.1 → 0.18.0

package/dist/mcp-server/http.mjs

@@ -2984,7 +2984,7 @@ function createGatedToolHandler(tool, integrationManager2, state2) {
   const gateable = !!tool.gating?.profile && tool.gating.category !== "disabled";
   const inner = async (args) => {
     const normalized = normalizeIncomingArgs(tool, args);
-    const refusal = gateable ? integrationManager2.precheckBuiltin?.(tool, normalized) : null;
+    const refusal = gateable ? await integrationManager2.precheckBuiltin?.(tool, normalized) : null;
     if (refusal) return { content: [{ type: "text", text: refusal }], isError: true };
     return gated(normalized);
   };
@@ -5248,6 +5248,18 @@ var IntegrationManager = class {
       available: !def.simulationOnly || isSimulationMode()
     }));
   }
+  /**
+   * What the approval screen needs to show a proposal for each tool: its argument
+   * schema (labels from the descriptions) and the optional approvalView hints.
+   * Keyed by the namespaced tool name a proposal carries.
+   */
+  getToolDisplay() {
+    const out = {};
+    for (const t of this.getAllTools()) {
+      out[t.namespacedName] = { inputSchema: t.inputSchema, ...t.gating?.approvalView ? { approvalView: t.gating.approvalView } : {} };
+    }
+    return out;
+  }
   /** Whether `id` names a built-in (in-process) integration. */
   isBuiltin(id) {
     return this.builtins.has(id);
@@ -5266,14 +5278,14 @@ var IntegrationManager = class {
    * no ticket): `simulationOnly` outside simulation mode, then the tool's `validate`.
    * Null for connector tools and for calls that may proceed.
    */
-  precheckBuiltin(tool, args) {
+  async precheckBuiltin(tool, args) {
     const builtin = this.builtins.get(tool.integrationId);
     if (!builtin) return null;
     if (builtin.def.simulationOnly && !isSimulationMode()) {
       return `Refused: "${tool.namespacedName}" is not available. No ticket was requested.`;
     }
     const def = builtin.def.tools.find((t) => t.name === tool.originalName);
-    const refusal = def?.validate?.(args);
+    const refusal = await def?.validate?.(args);
     return refusal ? `Refused: ${refusal} No ticket was requested.` : null;
   }
   /**
@@ -5484,7 +5496,8 @@ var IntegrationManager = class {
           readGovernance: ext.readGovernance,
           readGovernanceReason: ext.readGovernanceReason,
           blockedArgs: ext.blockedArgs,
-          hideUnlessAuthorized: ext.hideUnlessAuthorized
+          hideUnlessAuthorized: ext.hideUnlessAuthorized,
+          approvalView: ext.approvalView
         };
       }
       return {
@@ -5499,7 +5512,8 @@ var IntegrationManager = class {
         blockedArgs: ext.blockedArgs,
         argEncoding: ext.argEncoding,
         argNormalization: ext.argNormalization,
-        hideUnlessAuthorized: ext.hideUnlessAuthorized
+        hideUnlessAuthorized: ext.hideUnlessAuthorized,
+        approvalView: ext.approvalView
       };
     }
     return {
@@ -5606,6 +5620,98 @@ function builtinText(text) {
   return { content: [{ type: "text", text }] };
 }
 
+// src/lib/cp-mandate.ts
+var CP_PORT2 = process.env.SUVEREN_CP_PORT ?? "3402";
+var CP_BASE2 = process.env.SUVEREN_CP_INTERNAL_URL ?? `http://127.0.0.1:${CP_PORT2}`;
+async function controlPlaneMandate(dryRun, request) {
+  const secret = process.env.SUVEREN_INTERNAL_SECRET ?? "";
+  if (!secret) return { ok: false, message: "the gateway is not fully started (no control plane connection)." };
+  try {
+    const res = await fetch(`${CP_BASE2}/internal/mandate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Internal-Secret": secret },
+      body: JSON.stringify({ dryRun, request }),
+      signal: AbortSignal.timeout(3e4)
+    });
+    const body = await res.json().catch(() => ({}));
+    if (res.ok) return { ok: true, ...body };
+    return { ok: false, message: typeof body.message === "string" ? body.message : `control plane answered ${res.status}` };
+  } catch (err) {
+    return { ok: false, message: `the control plane could not be reached (${err instanceof Error ? err.message : String(err)}).` };
+  }
+}
+
+// src/lib/guides.ts
+import { existsSync as existsSync16, readdirSync, readFileSync as readFileSync17 } from "fs";
+import { dirname as dirname11, join as join16 } from "path";
+var FILE_RE = /^(?:(\d+)-)?([a-z0-9][a-z0-9-]*)\.md$/;
+function builtinGuidesDir() {
+  if (process.env.SUVEREN_BUILTIN_GUIDES_DIR) return process.env.SUVEREN_BUILTIN_GUIDES_DIR;
+  let dir = import.meta.dirname ?? __dirname;
+  for (let i = 0; i < 8; i++) {
+    const candidate = join16(dir, "content", "guides");
+    if (existsSync16(candidate)) return candidate;
+    const parent = dirname11(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join16(import.meta.dirname ?? __dirname, "content", "guides");
+}
+function parse(body) {
+  const lines = body.split(/\r?\n/);
+  const titleLine = lines.find((l) => l.startsWith("# ")) ?? "";
+  const title = titleLine.slice(2).trim();
+  const after = lines.slice(lines.indexOf(titleLine) + 1);
+  const summary = after.find((l) => l.trim() !== "" && !l.startsWith("#"))?.trim() ?? "";
+  return { title, summary };
+}
+function readDir(dir, source) {
+  if (!dir || !existsSync16(dir)) return [];
+  const out = [];
+  for (const file of readdirSync(dir)) {
+    const m = FILE_RE.exec(file);
+    if (!m) continue;
+    let body;
+    try {
+      body = readFileSync17(join16(dir, file), "utf8");
+    } catch {
+      continue;
+    }
+    const { title, summary } = parse(body);
+    out.push({ topic: m[2], order: m[1] ? Number(m[1]) : Number.POSITIVE_INFINITY, title: title || m[2], summary, body, source });
+  }
+  return out;
+}
+function loadGuides(builtinDir = builtinGuidesDir(), overrideDir = process.env.SUVEREN_GUIDES_DIR) {
+  const byTopic = /* @__PURE__ */ new Map();
+  for (const g of readDir(builtinDir, "default")) byTopic.set(g.topic, g);
+  for (const g of readDir(overrideDir, "override")) {
+    const replaced = byTopic.get(g.topic);
+    byTopic.set(g.topic, { ...g, order: Number.isFinite(g.order) ? g.order : replaced?.order ?? Number.POSITIVE_INFINITY });
+  }
+  return [...byTopic.values()].sort((a, b) => a.order - b.order || a.topic.localeCompare(b.topic));
+}
+function guideHeader(systems) {
+  const lines = [
+    "> This guide is in English. Talk to the person in their language, and write the brief and mandate intents in the language the team uses.",
+    "",
+    "**Systems connected to this gateway:**",
+    ""
+  ];
+  if (systems.length === 0) {
+    lines.push("- none yet \u2014 ask the person to connect the systems the work needs before you continue.");
+  } else {
+    for (const s of systems) {
+      const parts = [`profile \`${s.profile}\``];
+      if (s.actionTypes.length) parts.push(`action types ${s.actionTypes.map((a) => `\`${a}\``).join(", ")}`);
+      if (s.writeTools.length) parts.push(`changes via ${s.writeTools.map((t) => `\`${t}\``).join(", ")}`);
+      if (s.readTools.length) parts.push(`reads via ${s.readTools.map((t) => `\`${t}\``).join(", ")}`);
+      lines.push(`- **${s.id}** \u2014 ${parts.join("; ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/lib/builtins/setup.ts
 var DELEGATION_PROFILE = "github.com/humanagencyprotocol/hap-profiles/delegation@0.1";
 function briefRefusal(args) {
@@ -5614,11 +5720,27 @@ function briefRefusal(args) {
   if (bytes > CONTEXT_MAX_BYTES) return `the brief is ${bytes} bytes; the limit is ${CONTEXT_MAX_BYTES}. Shorten it.`;
   return void 0;
 }
-function setupBuiltin(_deps) {
+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 (t.gating.category === "read") {
+      s.readTools.push(t.originalName);
+    } else {
+      s.writeTools.push(t.originalName);
+      const at = t.gating.staticExecution?.action_type;
+      if (typeof at === "string" && !s.actionTypes.includes(at)) s.actionTypes.push(at);
+    }
+    byId.set(t.integrationId, s);
+  }
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+function setupBuiltin(deps) {
   return {
     id: "setup",
     name: "Test setup",
-    description: "Your AI proposes its own setup for a test \u2014 for now its agent brief. Every proposal waits for your approval. Simulation mode only.",
+    description: "Your AI sets up a test of itself: it reads the setup guides and proposes its agent brief and its mandates. Every proposal waits for your approval. Simulation mode only.",
     profile: DELEGATION_PROFILE,
     simulation: true,
     simulationOnly: true,
@@ -5627,11 +5749,67 @@ function setupBuiltin(_deps) {
         set_agent_brief: {
           executionMapping: {},
           staticExecution: { action_type: "brief" },
-          hideUnlessAuthorized: true
+          hideUnlessAuthorized: true,
+          approvalView: { content: { label: "New agent brief", kind: "markdown" } }
+        },
+        get_guide: {
+          category: "read",
+          boundField: "read_access",
+          requiredValue: "unlimited"
+        },
+        create_mandate: {
+          executionMapping: {},
+          staticExecution: { action_type: "mandate" },
+          hideUnlessAuthorized: true,
+          // Shown like the mandate screen: limits and scope by the profile's own names.
+          approvalView: {
+            team: { label: "Team" },
+            profile: { label: "Profile", kind: "profile" },
+            limits: { label: "Limits", kind: "profile-limits", profileArg: "profile" },
+            scope: { label: "Scope", kind: "profile-scope", profileArg: "profile" },
+            intent: { label: "Intent", kind: "markdown" },
+            mode: { label: "Mode" },
+            duration_hours: { label: "Valid for (hours)" },
+            title: { label: "Title" }
+          }
         }
       }
     },
     tools: [
+      {
+        name: "get_guide",
+        description: "Simulation mode only: the setup guides \u2014 how to interview the person, build the test data, propose mandates and the agent brief, set up the working AI's process, and what can make a test misleading. Call without `topic` for the list and the order to follow; then read each topic before doing that step.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            topic: { type: "string", description: 'The guide to read, e.g. "interview". Omit for the list of topics.' }
+          },
+          required: []
+        },
+        handler: async (args) => {
+          if (!isSimulationMode()) return { ...builtinText("Refused: not available outside simulation mode."), isError: true };
+          const guides = loadGuides();
+          const header = guideHeader(connectedSystems(deps.integrationManager));
+          const topic = typeof args.topic === "string" ? args.topic.trim().toLowerCase() : "";
+          if (!topic) {
+            const list = guides.map((g, i) => `${i + 1}. **${g.topic}** \u2014 ${g.summary}`).join("\n");
+            return builtinText(`${header}
+
+**Setup guides, in order:**
+
+${list || "- none installed"}
+
+Read each topic with get_guide(topic) before doing that step.`);
+          }
+          const guide = guides.find((g) => g.topic === topic);
+          if (!guide) {
+            return { ...builtinText(`Unknown topic "${topic}". Topics: ${guides.map((g) => g.topic).join(", ") || "none installed"}.`), isError: true };
+          }
+          return builtinText(`${header}
+
+${guide.body.trim()}`);
+        }
+      },
       {
         name: "set_agent_brief",
         description: "Simulation mode only: propose a new agent brief \u2014 the standing instructions every agent session starts with. `content` replaces the whole brief (markdown, at most 16 KB). A person approves or rejects the proposal; only after approval is the brief replaced, and it applies from the next session. Write the complete brief, not a change to the current one.",
@@ -5656,10 +5834,56 @@ function setupBuiltin(_deps) {
             `Agent brief replaced (${Buffer.byteLength(args.content, "utf-8")} bytes). It applies from the next agent session.`
           );
         }
+      },
+      {
+        name: "create_mandate",
+        description: "Simulation mode only: propose a new mandate for the person running this gateway \u2014 the authority another tool needs (e.g. sales quotes up to a value). A person approves or rejects the proposal; only after approval is the mandate created, exactly as if they had signed it on the mandate screen. Checked against the profile before the proposal: unknown limits, a mode the profile does not allow, or a team where the person may not give this mandate are refused at once. Create only.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            team: { type: "string", description: "Team name or id. Omit for the personal workspace." },
+            profile: { type: "string", description: 'Profile, e.g. "sales" (newest version) or a full profile id.' },
+            limits: { type: "object", description: "The limits (bounds) by field name, as the profile defines them." },
+            scope: { type: "object", description: "The scope (context) by field name, as the profile defines it." },
+            intent: { type: "string", description: "Why, goal and watch-outs \u2014 signed with the mandate (at most 2000 characters)." },
+            mode: { type: "string", enum: ["review", "automatic"], description: "review = each action needs approval; automatic = within the limits." },
+            duration_hours: { type: "number", description: "How long the mandate is valid, in hours. Omit for the profile default." },
+            title: { type: "string", description: "A short name for the mandate." },
+            receipt_id: {
+              type: "string",
+              description: "Authorization reference for this call, set by the governing gateway \u2014 agents do not set this."
+            }
+          },
+          required: ["profile", "limits", "intent", "mode"]
+        },
+        validate: async (args) => {
+          const check = await controlPlaneMandate(true, mandateRequest(args));
+          return check.ok ? void 0 : check.message;
+        },
+        handler: async (args) => {
+          if (!isSimulationMode()) return { ...builtinText("Refused: not available outside simulation mode."), isError: true };
+          const r = await controlPlaneMandate(false, mandateRequest(args));
+          if (!r.ok) return { ...builtinText(`Refused: ${r.message}`), isError: true };
+          return builtinText(
+            `Mandate created: ${r.authorizationId} \u2014 profile ${r.profileId}, ${r.groupName}, mode ${r.mode}, valid for ${Math.round((r.ttlSeconds ?? 0) / 3600)} h. It is active now.`
+          );
+        }
       }
     ]
   };
 }
+function mandateRequest(args) {
+  return {
+    team: typeof args.team === "string" && args.team.trim() ? args.team.trim() : void 0,
+    profile: args.profile,
+    limits: args.limits,
+    scope: args.scope,
+    intent: args.intent,
+    mode: args.mode,
+    durationHours: args.duration_hours,
+    title: args.title
+  };
+}
 
 // src/lib/builtins/index.ts
 var BUILTIN_FACTORIES = [setupBuiltin];
@@ -5681,8 +5905,8 @@ function registerBuiltins(deps, factories = BUILTIN_FACTORIES) {
 import { decodeAttestationBlob as decodeAttestationBlob3 } from "@hap/core";
 
 // src/lib/committed-executor.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync12, readFileSync as readFileSync17, unlinkSync as unlinkSync6, writeFileSync as writeFileSync12 } from "fs";
-import { dirname as dirname11, join as join16 } from "path";
+import { existsSync as existsSync17, mkdirSync as mkdirSync12, readFileSync as readFileSync18, unlinkSync as unlinkSync6, writeFileSync as writeFileSync12 } from "fs";
+import { dirname as dirname12, join as join17 } from "path";
 var CommittedExecutor = class {
   constructor(run) {
     this.run = run;
@@ -5710,7 +5934,7 @@ var ExecutorLock = class {
   path;
   held = false;
   constructor(dataDir2) {
-    this.path = join16(dataDir2, "executor.lock");
+    this.path = join17(dataDir2, "executor.lock");
   }
   /** Try to take the lock. Returns the holder's pid when someone else has it. */
   acquire() {
@@ -5718,7 +5942,7 @@ var ExecutorLock = class {
     if (current && current.pid !== process.pid && isAlive(current.pid)) {
       return { held: false, holderPid: current.pid };
     }
-    mkdirSync12(dirname11(this.path), { recursive: true, mode: 448 });
+    mkdirSync12(dirname12(this.path), { recursive: true, mode: 448 });
     const lock = { pid: process.pid, startedAt: Math.floor(Date.now() / 1e3) };
     writeFileSync12(this.path, JSON.stringify(lock), { mode: 384 });
     this.held = true;
@@ -5742,9 +5966,9 @@ var ExecutorLock = class {
     }
   }
   read() {
-    if (!existsSync16(this.path)) return null;
+    if (!existsSync17(this.path)) return null;
     try {
-      const parsed = JSON.parse(readFileSync17(this.path, "utf8"));
+      const parsed = JSON.parse(readFileSync18(this.path, "utf8"));
       return typeof parsed?.pid === "number" ? parsed : null;
     } catch {
       return null;
@@ -5762,19 +5986,19 @@ function isAlive(pid) {
 
 // bin/http.ts
 import { homedir as homedir10 } from "os";
-import { join as join18 } from "path";
+import { join as join19 } from "path";
 
 // src/lib/mcp-as-tracker.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync13, readFileSync as readFileSync18, writeFileSync as writeFileSync13 } from "fs";
-import { dirname as dirname12, join as join17 } from "path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync13, readFileSync as readFileSync19, writeFileSync as writeFileSync13 } from "fs";
+import { dirname as dirname13, join as join18 } from "path";
 function trackerPath(dataDir2) {
-  return join17(dataDir2, "mcp-as-pairing.json");
+  return join18(dataDir2, "mcp-as-pairing.json");
 }
 function readMcpPairedAsUrl(dataDir2) {
   const path = trackerPath(dataDir2);
-  if (!existsSync17(path)) return null;
+  if (!existsSync18(path)) return null;
   try {
-    const data = JSON.parse(readFileSync18(path, "utf-8"));
+    const data = JSON.parse(readFileSync19(path, "utf-8"));
     return typeof data.asUrl === "string" ? data.asUrl : null;
   } catch {
     return null;
@@ -5782,12 +6006,12 @@ function readMcpPairedAsUrl(dataDir2) {
 }
 function writeMcpPairedAsUrl(dataDir2, asUrl) {
   const path = trackerPath(dataDir2);
-  mkdirSync13(dirname12(path), { recursive: true, mode: 448 });
+  mkdirSync13(dirname13(path), { recursive: true, mode: 448 });
   writeFileSync13(path, JSON.stringify({ asUrl }, null, 2), { encoding: "utf-8", mode: 384 });
 }
 
 // bin/http.ts
-var dataDir = process.env.SUVEREN_DATA_DIR ?? join18(homedir10(), ".suveren");
+var dataDir = process.env.SUVEREN_DATA_DIR ?? join19(homedir10(), ".suveren");
 var spUrl = resolveAsUrl(dataDir);
 validatePinTlsForUrl(resolvePinTls(dataDir), spUrl);
 var port = parseInt(process.env.SUVEREN_MCP_PORT ?? "3430", 10);
@@ -6151,6 +6375,9 @@ app.get("/health", (_req, res) => {
     builtins: integrationManager.getBuiltins()
   });
 });
+app.get("/internal/tool-display", internalOnly, (_req, res) => {
+  res.json({ tools: integrationManager.getToolDisplay() });
+});
 app.get("/internal/gate-content", internalOnly, (req, res) => {
   const path = req.query.path;
   const gates = state.gateStore.getAll();
@@ -6318,7 +6545,7 @@ app.listen(port, "0.0.0.0", () => {
     (proposal) => executeCommitted(proposal, state, integrationManager)
   );
   installCommittedExecutor(committedExecutor);
-  const dataDir2 = process.env.SUVEREN_DATA_DIR ?? join18(homedir10(), ".suveren");
+  const dataDir2 = process.env.SUVEREN_DATA_DIR ?? join19(homedir10(), ".suveren");
   const executorLock = new ExecutorLock(dataDir2);
   const lock = executorLock.acquire();
   if (!lock.held) {