@suveren/gateway 0.17.0 → 0.18.0

package/content/guides/1-interview.md

@@ -0,0 +1,31 @@
+# Interview
+
+Learn the company, the team and the work, and collect real cases. Nothing is loaded or proposed in this step.
+
+You ask; the person answers and checks. Ask one topic at a time and write down what you learn.
+
+## 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.
+2. **Department and team:** who does the work today, what a normal day looks like, what must never happen.
+3. **The work to test:** which requests come in (for example quote requests, orders, questions), how many, how fast they are answered today, and what a good answer looks like.
+4. **Order of systems:** whether the team follows a fixed sequence across systems — for example: always look up the customer in the CRM before quoting in the ERP, and log the reply in the CRM after sending. Which step must come first, which may be skipped. This becomes the agent's process and a rule in its brief.
+5. **Real cases:** 5–10 recent examples, each with the request as it arrived and the reply that was actually sent. The person pastes or forwards them.
+6. **Rules that are not written down:** discounts, credit limits, who may promise delivery dates, when to escalate and to whom.
+
+## Renaming
+
+Before anything else happens, propose new names for every person, company and email domain in the cases. Keep amounts, products and dates realistic. Use `.example` domains (for example `einkauf@huber.example`). The person checks the renamed cases; change them until they agree.
+
+## Result of this step
+
+- A short written summary: company, team, the work, the order of systems, the rules.
+- The renamed cases.
+
+Both confirmed by the person. The summary feeds the agent brief and the mandates; the cases feed the test data.
+
+## Ask, don't guess
+
+If a rule or a step is unclear, ask the person. Never invent a rule, a limit or a step to fill a gap.
+
+Next: **package**.

package/content/guides/2-package.md

@@ -0,0 +1,30 @@
+# Package
+
+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).
+
+- 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.
+- Show the person the package before loading it; load only after they agree.
+
+## Load
+
+- Loading needs a setup mandate for each system (see **mandates**). The working AI's mandates must never allow loading.
+- Call `load_simulation` in each simulated system with the same package.
+- A load only works into an empty system. Incoming requests are dated within the hour before the load, in case order.
+
+## Run again
+
+To run the same cases again under a different setup, or other cases under the same setup:
+
+1. `clear_simulation` in each system — this deletes all test data, including the record of what happened.
+2. `load_simulation` again.
+
+Clear and load each count against the setup mandate's daily limit, so one re-run costs two per system. If the limit is too small, propose a new setup mandate with a higher limit.
+
+The real replies stay inside the simulated email system. They are never shown to the working AI; they exist for comparing afterwards.
+
+Next: **mandates**.

package/content/guides/3-mandates.md

@@ -0,0 +1,34 @@
+# Mandates
+
+Propose the mandates the setup and the working AI need. You propose with `create_mandate`; the person approves each one on its own; only then is it created.
+
+## Ask first
+
+Before proposing any mandate, ask the person which steps they want to approve themselves. Their answer wins over everything below.
+
+## The standard (when the person has no preference)
+
+- **Steps the customer would see** — replies, sent quotes, orders — start in **review** mode: each one waits for the person's approval.
+- **Internal steps** — looking up and noting things in the CRM, drafting quotes, loading test data — run **automatically** within limits.
+
+Apply this to whatever systems are connected: the header above lists each system with its action types and tools. Judge from the action type and its tools whether the customer would see the result. When unsure, ask.
+
+## Rules
+
+- **One mandate per system.** Split a system into several mandates only when the team has different rules for different tasks. A mode applies to a whole mandate, so different modes for different steps of one system mean separate mandates (for example: drafting quotes automatically, sending quotes in review).
+- **Setup and work are separate.** Setup mandates allow loading and clearing test data and nothing else. The working AI's mandates allow no loading or clearing (setup limit 0).
+- **Start strict.** Where the team has not said otherwise, propose review mode or low caps. The person can loosen a mandate later by replacing it.
+- **Limits come from the interview:** amounts, discounts, daily counts, allowed recipients. Do not invent them; ask.
+- **Intent:** write why, goal and watch-outs in the person's words, in the language the team uses. It is signed with the mandate and the working AI follows it.
+- **Teams:** in a team, the person must be an approver for the profile. `create_mandate` refuses at once if not; tell the person who can fix it (a team admin).
+- **Reporting:** never propose a `reporting` mandate for the working AI during a run (see **risks**).
+
+## Example (only an example)
+
+- Setup, per system: automatic, setup limit 4–6 per day, everything else 0.
+- CRM: automatic, with daily limits.
+- Sales, drafting quotes: automatic, within value and discount caps.
+- Sales, sending quotes and orders: review.
+- Email replies: review, recipients limited to the customers' domains.
+
+Next: **brief**.

package/content/guides/4-brief.md

@@ -0,0 +1,30 @@
+# Brief
+
+Propose the agent brief — the standing instructions the working AI starts every session with. You propose with `set_agent_brief`; the person approves; it applies from the working AI's next session.
+
+## What goes in
+
+From the interview:
+
+- **Who the AI works for:** the company, the team, the person.
+- **The job:** which requests it handles and what a good outcome is.
+- **The process:** the steps in order, including the order of systems from the interview, written as a rule (for example: "Always look up the customer in the CRM before preparing a quote.").
+- **House rules:** tone, language, discounts, credit, what to escalate and to whom.
+- **Hard lines:** what it must never do, even where a mandate would allow it.
+- **When unsure, ask:** a missing rule or an unclear step goes to the person, never to a guess.
+
+Write the brief in the language the team uses.
+
+## What stays out
+
+- Anything that reveals a test: no "simulation", "test case", "expected reply" or similar words.
+- The real replies from the cases.
+- Secrets, passwords, keys.
+
+## Limits
+
+- At most 16 KB.
+- It replaces the whole brief each time — always write the complete brief, not a change.
+- The person approves every version.
+
+Next: **agent-process**.

package/content/guides/5-agent-process.md

@@ -0,0 +1,39 @@
+# Agent process
+
+Help the person set up the working AI's process in its own client. The process is the working AI's work, not the gateway's: the gateway only grants and checks what it may do.
+
+## Write the process as steps
+
+From the interview, for example:
+
+1. Read new messages in the inbox.
+2. Look up the customer in the CRM.
+3. Check stock and price in the ERP.
+4. Prepare the quote.
+5. Reply to the customer.
+
+Keep a fixed order of systems from the interview exactly as given; it is also a rule in the brief. The person confirms the steps.
+
+## Where it lives
+
+- In the working AI's client, as its standing instructions for this work, connected to this gateway.
+- In a separate conversation or project from this setup conversation.
+
+## What starts a run
+
+- The person asks (for example: "Work the new requests.").
+- Or a scheduled or triggered run, if the client offers one. Check what the person's client offers today; do not assume.
+
+## When a step is unclear
+
+The working AI stops and asks the person. It never fills a gap by guessing.
+
+## Claude Desktop
+
+Help the person connect the client to this gateway (the gateway's MCP address) and put the steps into the client's standing instructions for this work. Check the client's current settings with the person; menus change between versions.
+
+## ChatGPT
+
+Same as above: connect the gateway if the person's plan and client support custom MCP connectors, and add the steps as instructions. If connecting is not possible, say so — the working AI cannot be tested without the gateway.
+
+Next: **risks**, then start a run.

package/content/guides/6-risks.md

@@ -0,0 +1,14 @@
+# Risks
+
+What can make a test say more than it should, and what to do about each. Read this once at the start and again before every run.
+
+| Risk | Why it matters | What to do |
+| --- | --- | --- |
+| The client remembers earlier runs | A re-run of the same cases is no longer a fresh test | Start every run in a new conversation; turn the client's memory off for the working AI |
+| The working AI learns it is a test | It may behave differently | Never give it a `reporting` mandate during a run — its tools list the cases. Grant `reporting` only after the run, or to a separate AI session that only writes the report. Keep test words out of the brief |
+| Setup and work in the same session | Setup tools and the real replies stay in the working AI's context | Use separate conversations for setup and for work |
+| 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 |
+
+Next: start a run — the person asks the working AI to work the new requests.

package/dist/mcp-server/http.mjs

@@ -5641,6 +5641,77 @@ async function controlPlaneMandate(dryRun, request) {
   }
 }
 
+// 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) {
@@ -5649,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 its agent brief and its mandates. 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,
@@ -5665,6 +5752,11 @@ function setupBuiltin(_deps) {
           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" },
@@ -5684,6 +5776,40 @@ function setupBuiltin(_deps) {
       }
     },
     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.",
@@ -5779,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;
@@ -5808,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() {
@@ -5816,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;
@@ -5840,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;
@@ -5860,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;
@@ -5880,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);
@@ -6419,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suveren/gateway",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Suveren gateway — local agent gateway built in compliance with the Human Agency Protocol (HAP). Runs the UI, control plane, and MCP server in one Node process.",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -168,6 +168,8 @@ const UI_DIST = process.env.HAP_UI_DIST ?? join(__dirname, 'dist', 'ui');
 // win for advanced users / Docker.
 const MANIFESTS_DIR = process.env.SUVEREN_MANIFESTS_DIR ?? join(__dirname, 'content', 'integrations');
 const PROFILES_DIR = process.env.SUVEREN_PROFILES_DIR ?? join(__dirname, 'profiles');
+// Default setup guides; SUVEREN_GUIDES_DIR (an override folder) is read on top.
+const BUILTIN_GUIDES_DIR = process.env.SUVEREN_BUILTIN_GUIDES_DIR ?? join(__dirname, 'content', 'guides');
 
 const env = {
   ...process.env,
@@ -183,6 +185,7 @@ const env = {
   HAP_UI_DIST: UI_DIST,
   SUVEREN_MANIFESTS_DIR: MANIFESTS_DIR,
   SUVEREN_PROFILES_DIR: PROFILES_DIR,
+  SUVEREN_BUILTIN_GUIDES_DIR: BUILTIN_GUIDES_DIR,
   // Single shared internal secret so CP↔MCP authenticate the bridge.
   SUVEREN_INTERNAL_SECRET: process.env.SUVEREN_INTERNAL_SECRET ?? randomHex(32),
   // Simulation mode — IT policy (see lib/policy.mjs) wins UNCONDITIONALLY,