@suveren/gateway 0.19.3 → 0.19.5

package/content/guides/1-interview.md

@@ -4,6 +4,12 @@ Learn the company, the team and the work, and collect real cases. Nothing is loa
 
 You ask; the person answers and checks. Ask one topic at a time and write down what you learn.
 
+## Before you start: the systems
+
+Look at the systems in the header above. If a system the work needs is listed under **Available but not activated**, ask the person to activate it first (Integrations → its card → Activate) and read this guide again. Do not plan around a system you cannot see.
+
+Plan the test only with the actions the connected systems offer — the header lists each system's changes and reads. If the work needs an action no system offers (for example a refund when the ERP has only quotes and orders), say so and agree with the person on what to test instead. Never pretend a system can do more than it does.
+
 ## What to ask, in this order
 
 1. **Company:** what it sells, to whom, in which currency, and which systems it uses. The systems connected to this gateway are listed in the header above; ask about the ones that matter for the work.

package/content/guides/2-package.md

@@ -4,7 +4,7 @@ Turn the confirmed cases into test data and load it into the simulated systems.
 
 ## Build the package
 
-One package feeds every simulated system. Its format, and how to build a good one, is described in the `load_simulation` tool of each simulated system — read it there; it is the authority. In short: the company's `name` and `currency`, the `customers`, `products` and `contacts` the cases need, and the `cases` themselves (each request as it arrived and the reply that was actually sent).
+One package feeds every simulated system. Its exact format is at the end of this guide (read from the simulated systems themselves), and how to build a good one is described there too. In short: the company's `name` and `currency`, the `customers`, `products` and `contacts` the cases need, and the `cases` themselves (each request as it arrived and the reply that was actually sent).
 
 - Include every customer, product and contact a case mentions, with stock, prices and credit limits that make each case answerable the way it really was.
 - Use only the renamed cases.
@@ -27,4 +27,7 @@ Clear and load each count against the setup mandate's daily limit, so one re-run
 
 The real replies stay inside the simulated email system. They are never shown to the working AI; they exist for comparing afterwards.
 
+
+<!-- generated: package -->
+
 Next: **mandates**.

package/content/guides/3-mandates.md

@@ -32,4 +32,7 @@ Apply this to whatever systems are connected: the header above lists each system
 - Sales, sending quotes and orders: review.
 - Email replies: review, recipients limited to the customers' domains.
 
+
+<!-- generated: limits -->
+
 Next: **brief**.

package/content/guides/6-risks.md

@@ -10,5 +10,7 @@ What can make a test say more than it should, and what to do about each. Read th
 | Mandates too loose | A wrong result can look like success | Start in review mode or with low caps; loosen by replacing the mandate |
 | Proposals are stored readable on the Authority Server | The content of every proposal, including intents, can be read there | Test data and renamed cases only — never real customer data in a setup |
 | Setup limit too low | A clear without the following load leaves empty systems | Use a setup limit of 4–6 per day; clear and load in one go |
+| An AI that can control a browser or the screen | It could open the gateway's page, read the API key there and approve its own proposals — the person would no longer decide | Never open or operate the gateway's page, never handle the API key, never approve. Tell the person to approve themselves, and to keep the gateway page out of any browser an AI controls |
+| Calls around the Suveren tools | A terminal, HTTP or browser call to the gateway's ports is not governed by a mandate | Use only the Suveren tools. If something is missing, tell the person what — do not probe the gateway |
 
 Next: start a run — the person asks the working AI to work the new requests.

package/dist/mcp-server/http.mjs

@@ -4079,6 +4079,12 @@ 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`)."
+];
+
 // src/lib/mandate-brief.ts
 function shortProfileName(profileId) {
   const withoutVersion = profileId.replace(/@.*$/, "");
@@ -4165,6 +4171,10 @@ function buildMandateBrief(opts) {
     lines.push(canSetUp ? "If the person asks how to start with Suveren or how to set up their work with it: call setup__get_guide first and follow its steps in order." : `If the person asks how to start with Suveren: they first create a "Delegation" mandate in the Suveren Gateway at ${uiUrl()}. With it you can read the setup guide and lead them through the setup.`);
     lines.push("");
   }
+  lines.push("=== RULES ===");
+  lines.push("");
+  for (const r of AGENT_RULES) lines.push(`- ${r}`);
+  lines.push("");
   lines.push("When you receive a task, call list-authorizations(domain) to load full details for the relevant domain.");
   return lines.join("\n");
 }
@@ -5821,6 +5831,7 @@ var IntegrationManager = class {
       name: def.name,
       description: def.description ?? "",
       profile: def.profile,
+      ...def.intentHint ? { intentHint: def.intentHint } : {},
       available: !def.simulationOnly || isSimulationMode()
     }));
   }
@@ -6861,7 +6872,7 @@ function loadGuides(builtinDir = builtinGuidesDir(), overrideDir = process.env.S
   }
   return [...byTopic.values()].sort((a, b) => a.order - b.order || a.topic.localeCompare(b.topic));
 }
-function guideHeader(systems) {
+function guideHeader(systems, inactive = []) {
   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.",
     "",
@@ -6879,13 +6890,75 @@ function guideHeader(systems) {
       lines.push(`- **${s.id}** \u2014 ${parts.join("; ")}`);
     }
   }
+  if (inactive.length) {
+    lines.push("");
+    lines.push("**Available but not activated:** " + inactive.map((n) => `**${n}**`).join(", ") + ". Before anything else, ask the person to activate the ones the work needs: in the Suveren Gateway, Integrations \u2192 the system's card \u2192 Activate. Then read this guide again \u2014 a system you cannot see here does not exist for the test.");
+  }
   lines.push("");
   lines.push(`**Approvals:** every mandate and brief you propose waits until the person approves it in the Suveren Gateway at ${uiUrl()}/approvals. Tell them each time you propose one.`);
+  lines.push("");
+  lines.push("**Rules:**");
+  for (const r of AGENT_RULES) lines.push(`- ${r}`);
   return lines.join("\n");
 }
+function scopeFieldsOf(profile) {
+  return profile.scopeSchema ?? profile.contextSchema;
+}
+function fieldLine(name, f) {
+  const kind = [];
+  const values = f.boundType?.values ?? f.enum;
+  if (Array.isArray(values)) kind.push(`one of ${values.map((v) => `\`${String(v)}\``).join(", ")}`);
+  else if (f.type) kind.push(f.type);
+  if (f.unit) kind.push(f.unit);
+  if (f.boundType?.window) kind.push(`per ${f.boundType.window === "daily" ? "day" : f.boundType.window}`);
+  if (typeof f.maximum === "number") kind.push(`at most ${f.maximum}`);
+  if (f.default !== void 0) kind.push(`default \`${String(f.default)}\``);
+  const label = f.displayName ? ` (${f.displayName})` : "";
+  return `- \`${name}\`${label} \u2014 ${kind.join(", ") || "value"}${f.description ? `. ${f.description}` : ""}`;
+}
+function fieldLines(schema) {
+  const fields = schema?.fields ?? {};
+  const order = (schema?.keyOrder ?? Object.keys(fields)).filter((k) => k !== "profile" && k !== "path" && fields[k]);
+  return order.map((k) => fieldLine(k, fields[k]));
+}
+function limitsSection(systems) {
+  const out = ["## Limits and scope per system", "", "From the profiles \u2014 use exactly these names in `create_mandate` (`limits` and `scope`). Every limit must be set.", ""];
+  for (const s of systems) {
+    if (!s.profile) continue;
+    out.push(`### ${s.id} \u2014 profile \`${s.profile.id}\``, "", "**Limits:**", ...fieldLines(s.profile.boundsSchema));
+    const scope2 = fieldLines(scopeFieldsOf(s.profile));
+    out.push("", "**Scope:**", ...scope2.length ? scope2 : ["- none"], "");
+  }
+  return out.join("\n");
+}
+function packageSection(tool) {
+  if (!tool?.inputSchema) return "## The package format\n\nNo simulated system with `load_simulation` is active \u2014 ask the person to activate one first.";
+  const pkg = tool.inputSchema.properties?.package ?? tool.inputSchema;
+  return [
+    "## The package format",
+    "",
+    ...tool.description ? ["What the simulated systems say about it:", "", `> ${tool.description}`, ""] : [],
+    "The `package` argument of `load_simulation` \u2014 the same package for every simulated system:",
+    "",
+    "```json",
+    JSON.stringify(pkg, null, 2),
+    "```"
+  ].join("\n");
+}
+function fillGenerated(body, sections) {
+  return body.replace(/<!--\s*generated:\s*([a-z-]+)\s*-->/g, (m, key) => sections[key] ? sections[key]() : m);
+}
 
 // src/lib/builtins/setup.ts
-var DELEGATION_PROFILE = "github.com/humanagencyprotocol/hap-profiles/delegation@0.1";
+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.",
+  "",
+  "Goal \u2014 Follow the setup guide: interview me about the company, the team and the work; prepare test data from real cases, renamed to .example names; propose the mandates and the working instructions (agent brief) that the AI doing the work will need.",
+  "",
+  "Watch out \u2014 You only propose; nothing happens until I approve it in the Suveren Gateway. Ask, don't guess: never invent a rule, a limit or a step. One proposal at a time. Steps customers would see start with my review. Never use real names or customer data \u2014 proposals are stored readable on the Suveren server. Never give the working AI a reporting mandate during a test run. Keep the setup and the working AI in separate conversations."
+].join("\n");
 function briefRefusal(args) {
   if (typeof args.content !== "string" || args.content.trim() === "") return "`content` must be the complete new brief (markdown text).";
   const bytes = Buffer.byteLength(args.content, "utf-8");
@@ -6917,6 +6990,7 @@ function setupBuiltin(deps) {
     // card), not the internal "test setup" framing. Description is unchanged.
     name: "Delegation",
     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.",
+    intentHint: DELEGATION_INTENT_HINT,
     profile: DELEGATION_PROFILE,
     simulation: true,
     simulationOnly: true,
@@ -6965,7 +7039,10 @@ function setupBuiltin(deps) {
         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 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 header = guideHeader(systems, inactive);
           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");
@@ -6981,9 +7058,15 @@ Read each topic with get_guide(topic) before doing that step.`);
           if (!guide) {
             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: getProfile7(s.profile) }))),
+            package: () => packageSection(
+              deps.integrationManager.getAllTools().find((t) => !deps.integrationManager.isBuiltin(t.integrationId) && t.originalName === "load_simulation")
+            )
+          });
           return builtinText(`${header}
 
-${guide.body.trim()}`);
+${body}`);
         }
       },
       {