@suveren/gateway 0.5.0 → 0.6.1

package/bin/suveren-gateway.js

@@ -69,13 +69,22 @@ async function start(args) {
   if (await isPortListening(SUVEREN_PORT)) {
     console.error(`Port ${SUVEREN_PORT} is already in use.`);
     console.error(``);
-    console.error(`Something is already serving there — most likely a gateway started by the`);
-    console.error(`login service or from another terminal, which leaves no PID file for this`);
-    console.error(`CLI to find.`);
-    console.error(``);
-    console.error(`  Check what it is:      suveren-gateway status`);
-    console.error(`  Stop a login service:  suveren-gateway service uninstall`);
-    console.error(`  Or use another port:   SUVEREN_CP_PORT=3410 suveren-gateway start`);
+    if (serviceRunning()) {
+      // Do not suggest uninstalling autostart: that removes a feature the user
+      // asked for in order to solve a problem that needs a restart. After an
+      // upgrade the files on disk are new and the running process is not.
+      console.error(`The login service is already running the gateway, so there is nothing to start.`);
+      console.error(``);
+      console.error(`  Pick up an update:     suveren-gateway restart`);
+      console.error(`  Check what is running: suveren-gateway status`);
+      console.error(`  Remove autostart:      suveren-gateway service uninstall`);
+    } else {
+      console.error(`Something is already serving there — most likely a gateway started from`);
+      console.error(`another terminal, which leaves no PID file for this CLI to find.`);
+      console.error(``);
+      console.error(`  Check what it is:      suveren-gateway status`);
+      console.error(`  Or use another port:   SUVEREN_CP_PORT=3410 suveren-gateway start`);
+    }
     process.exit(1);
   }
 
@@ -134,6 +143,16 @@ async function start(args) {
 
 async function stop() {
   const pid = readPid();
+  // A service-managed gateway writes no PID file. Reporting "not running" while
+  // it serves requests is the most misleading thing this CLI can say, and it is
+  // what sent an upgrade into a port conflict it could not explain.
+  if (!pid && serviceRunning()) {
+    console.error('suveren-gateway is running under the login service, which this command does not manage.');
+    console.error('');
+    console.error('  To pick up an update:   suveren-gateway restart');
+    console.error('  To stop it for good:    suveren-gateway service uninstall');
+    process.exit(1);
+  }
   if (!pid) {
     console.error('suveren-gateway is not running (no PID file).');
     process.exit(1);
@@ -242,6 +261,14 @@ async function status() {
 }
 
 async function restart() {
+  // The service manager owns the process when autostart is installed, and it
+  // leaves no PID file — so this must be asked FIRST or the checks below all
+  // conclude, wrongly, that nothing is running.
+  if (serviceRestart()) {
+    console.log('suveren-gateway: restarted via the login service.');
+    console.log(`  The vault is locked after a restart — unlock at http://localhost:${SUVEREN_PORT}`);
+    return;
+  }
   if (readPid() && isPidAlive(readPid())) {
     await stop();
   }
@@ -279,6 +306,52 @@ async function logs(args) {
 
 const LAUNCH_AGENT_LABEL = 'ai.suveren.gateway';
 
+/**
+ * Is the login service currently running the gateway?
+ *
+ * `stop`, `start` and `restart` were all written before autostart existed and
+ * all reason from the PID file — which a service-managed gateway never writes.
+ * The result was that installing autostart silently broke the update path:
+ * `stop` reported "not running", and `start` then hit a port held by a process
+ * it could not see. Every command has to know about the service the same CLI
+ * installs.
+ */
+function serviceRunning() {
+  const os = platform();
+  if (os === 'darwin') {
+    const p = runQuiet('launchctl', ['print', `gui/${process.getuid()}/${LAUNCH_AGENT_LABEL}`]);
+    return p.status === 0 && /state = running/.test(p.stdout || '');
+  }
+  if (os === 'win32') {
+    const p = runQuiet('schtasks', ['/Query', '/TN', WIN_TASK_NAME, '/FO', 'LIST']);
+    return p.status === 0 && /Status:\s+Running/i.test(p.stdout || '');
+  }
+  const p = runQuiet('systemctl', ['--user', 'is-active', SYSTEMD_UNIT]);
+  return (p.stdout || '').trim() === 'active';
+}
+
+/**
+ * Restart through whichever service manager owns the process.
+ *
+ * Returns false when no service is running, so callers fall back to the manual
+ * path. Restarting is what an upgrade needs: npm replaces the files on disk,
+ * but the running process loaded them once at start and keeps serving the old
+ * code until it is replaced.
+ */
+function serviceRestart() {
+  if (!serviceRunning()) return false;
+  const os = platform();
+  if (os === 'darwin') {
+    runQuiet('launchctl', ['kickstart', '-k', `gui/${process.getuid()}/${LAUNCH_AGENT_LABEL}`]);
+  } else if (os === 'win32') {
+    runQuiet('schtasks', ['/End', '/TN', WIN_TASK_NAME]);
+    runQuiet('schtasks', ['/Run', '/TN', WIN_TASK_NAME]);
+  } else {
+    runQuiet('systemctl', ['--user', 'restart', SYSTEMD_UNIT]);
+  }
+  return true;
+}
+
 async function service(args) {
   const sub = args[0] ?? 'help';
   const os = platform();
@@ -350,14 +423,30 @@ async function serviceInstallMac() {
 
   const uid = process.getuid();
   // Clear any prior "disabled" mark from a previous uninstall, so the agent is
-  // eligible again — but do NOT bootstrap it now: that would start a second
-  // gateway alongside the running one and fight over the port.
+  // eligible again.
   runQuiet('launchctl', ['enable', `gui/${uid}/${LAUNCH_AGENT_LABEL}`]);
 
+  // Bootstrap NOW only when nothing is already serving. With a gateway running,
+  // loading the agent starts a second one that loses the port race and then
+  // crash-loops under KeepAlive — so in that case the agent waits for the next
+  // login, when the manual instance is gone. With nothing running there is no
+  // conflict, and waiting would leave the user with a "service" that isn't
+  // running and no obvious reason why.
+  const running = await isAlreadyRunning();
+  let loadedNow = false;
+  if (!running) {
+    const r = runQuiet('launchctl', ['bootstrap', `gui/${uid}`, plistPath]);
+    loadedNow = r.status === 0;
+  }
+
   console.log(`✓ Suveren gateway installed as a login service.`);
   console.log(``);
-  console.log(`  It starts automatically from your NEXT login, and restarts if it crashes.`);
-  console.log(`  Your current gateway keeps running — nothing was interrupted.`);
+  if (loadedNow) {
+    console.log(`  It is running now, starts automatically at login, and restarts if it crashes.`);
+  } else {
+    console.log(`  It starts automatically from your NEXT login, and restarts if it crashes.`);
+    if (running) console.log(`  Your current gateway keeps running — nothing was interrupted.`);
+  }
   console.log(`  After a reboot it comes up LOCKED — open http://localhost:${SUVEREN_PORT} and`);
   console.log(`  enter your Suveren API key once to unlock it (your key is never stored).`);
   console.log(``);
@@ -395,7 +484,13 @@ async function serviceStatusMac() {
     const state = /state = (\w+)/.exec(p.stdout || '');
     console.log(`  launchd: loaded${state ? ` (${state[1]})` : ''}`);
   } else if (installed) {
-    console.log(`  launchd: not loaded (run \`suveren-gateway service install\` to (re)load)`);
+    // Do NOT point at `service install` here: install deliberately does not
+    // bootstrap while a gateway is already running (two would fight over the
+    // port), so re-running it would change nothing and the advice would be a
+    // dead end. Say plainly when it becomes active, and give the command that
+    // actually loads it now.
+    console.log(`  launchd: not loaded — starts at your next login`);
+    console.log(`           to activate now: suveren-gateway stop && launchctl bootstrap gui/$(id -u) "${plistPath}"`);
   }
   console.log('');
   await status(); // process/health/vault line

package/content/integrations/deploy-github.json

@@ -0,0 +1,164 @@
+{
+  "id": "deploy-github",
+  "name": "Deploy (GitHub)",
+  "version": "1.0.0",
+  "description": "Make an already-built version live, under signed authority",
+  "icon": "wrench",
+  "profile": "deploy",
+  "npmPackage": "@humanagencyp/deploy-mcp",
+  "mcp": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@humanagencyp/deploy-mcp@latest"
+    ]
+  },
+  "credentials": {
+    "fields": [
+      {
+        "key": "githubToken",
+        "label": "GitHub token",
+        "type": "password",
+        "placeholder": "github_pat_..."
+      }
+    ],
+    "envMapping": {
+      "GITHUB_TOKEN": "githubToken"
+    }
+  },
+  "oauth": null,
+  "toolGating": {
+    "default": {
+      "executionMapping": {},
+      "staticExecution": {},
+      "category": "disabled"
+    },
+    "overrides": {
+      "list_deployments": {
+        "category": "read",
+        "readGovernance": "none",
+        "readGovernanceReason": "Returns build metadata and the host's own deployment URLs. No source, no build output, no user content. Scoped to permitted repositories.",
+        "read": {
+          "resourceBound": "allowed_repos",
+          "resourceArg": "repo"
+        }
+      },
+      "get_deployment": {
+        "category": "read",
+        "readGovernance": "none",
+        "readGovernanceReason": "Returns metadata for one build — state, commit, URL. No build output.",
+        "read": {
+          "resourceBound": "allowed_repos",
+          "resourceArg": "repo"
+        }
+      },
+      "resolve_ref": {
+        "category": "read",
+        "readGovernance": "none",
+        "readGovernanceReason": "Returns a commit pointer only. Repository metadata, not user content.",
+        "read": {
+          "resourceBound": "allowed_repos",
+          "resourceArg": "repo"
+        }
+      },
+      "list_environments": {
+        "category": "read",
+        "readGovernance": "none",
+        "readGovernanceReason": "Returns environment names only. Repository configuration, needed so the owner can pick a target that exists.",
+        "read": {
+          "resourceBound": "allowed_repos",
+          "resourceArg": "repo"
+        }
+      },
+      "release": {
+        "executionMapping": {
+          "repo": "allowed_repos",
+          "environment": "allowed_environments",
+          "workflow": "allowed_workflows"
+        },
+        "staticExecution": {
+          "action_type": "release"
+        },
+        "contentField": "deployment_url"
+      }
+    }
+  },
+  "templates": [
+    {
+      "name": "Watch deployments",
+      "description": "See builds and their URLs. Cannot make anything live.",
+      "risk": "low",
+      "mode": "automatic",
+      "bounds": {
+        "release_daily_max": "0",
+        "rollback_allowed": "no"
+      },
+      "context": {
+        "allowed_repos": "",
+        "allowed_environments": "",
+        "allowed_workflows": "",
+        "allowed_branches": ""
+      },
+      "intent": "Let the agent see what has been built and whether it succeeded. It may not make anything live: a daily maximum of zero is a real limit, not an unset one. Fill in allowed_repos with the repositories it may look at.",
+      "ttl": 2592000,
+      "tags": [
+        "read-only",
+        "30 days"
+      ]
+    },
+    {
+      "name": "Release to production, review",
+      "description": "Make an existing build live after approval. Three a day, no rollback.",
+      "risk": "high",
+      "mode": "review",
+      "bounds": {
+        "release_daily_max": "3",
+        "rollback_allowed": "no"
+      },
+      "context": {
+        "allowed_repos": "",
+        "allowed_environments": "production",
+        "allowed_workflows": "deploy-website.yml",
+        "allowed_branches": "main"
+      },
+      "intent": "The agent may propose making a specific build live; nothing runs until I approve it. Open the build URL in the proposal and look at it before approving — that is the point of reviewing a release rather than a commit. Fill in allowed_repos, and check allowed_environments matches what the host actually calls it.",
+      "ttl": 2592000,
+      "tags": [
+        "review",
+        "production",
+        "30 days"
+      ]
+    }
+  ],
+  "setupHint": "Use a fine-grained token, scoped to one repository.",
+  "setupGuide": [
+    {
+      "title": "Create a fine-grained token",
+      "description": "GitHub Settings, Developer settings, Personal access tokens, Fine-grained. Not a classic token — those reach everything you own.",
+      "link": "https://github.com/settings/personal-access-tokens/new"
+    },
+    {
+      "title": "Scope it to one repository",
+      "description": "Under Repository access pick Only select repositories, then the repo to deploy."
+    },
+    {
+      "title": "Grant three permissions",
+      "description": "Actions: Read and write. Environments: Read. Contents: Read. Not Contents: Write — the agent ships commits, it never writes them."
+    },
+    {
+      "title": "Paste the token below",
+      "description": "Encrypted in your local vault. The agent never sees it."
+    }
+  ],
+  "proposalLinks": [
+    {
+      "label": "Open this build",
+      "template": "{deployment_url}",
+      "description": "Look at exactly what would go live"
+    },
+    {
+      "label": "View repository",
+      "template": "https://github.com/{repo}"
+    }
+  ]
+}

package/content/integrations/gmail.json

@@ -83,7 +83,10 @@
         },
         "staticExecution": {
           "action_type": "send"
-        }
+        },
+        "blockedArgs": [
+          "raw"
+        ]
       },
       "create_draft": {
         "executionMapping": {
@@ -104,7 +107,10 @@
         },
         "staticExecution": {
           "action_type": "send"
-        }
+        },
+        "blockedArgs": [
+          "raw"
+        ]
       },
       "send_draft": {
         "executionMapping": {},
@@ -187,7 +193,7 @@
       "get_profile": {
         "category": "read",
         "readGovernance": "none",
-        "readGovernanceReason": "Returns the account's own address and message counts — the connector's own identity, no correspondence content."
+        "readGovernanceReason": "Returns the account's own address and message counts \u2014 the connector's own identity, no correspondence content."
       }
     }
   },
@@ -230,7 +236,7 @@
         "allowed_recipients": "",
         "allowed_domains": ""
       },
-      "intent": "Read my inbox and compose emails. Every send requires my review — I see the recipient, subject, and body before it goes out.",
+      "intent": "Read my inbox and compose emails. Every send requires my review \u2014 I see the recipient, subject, and body before it goes out.",
       "ttl": 2592000,
       "tags": [
         "5 recipients/email",

package/content/integrations/index.json

@@ -5,6 +5,7 @@
     "crm": "crm.json",
     "records": "records.json",
     "linkedin": "linkedin.json",
-    "calendar": "calendar.json"
+    "calendar": "calendar.json",
+    "deploy-github": "deploy-github.json"
   }
 }

package/dist/control-plane/index.mjs

@@ -1600,16 +1600,23 @@ function createAutostartRouter() {
 }
 
 // src/lib/desktop-notify.ts
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 function osaQuote(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 function psQuote(value) {
   return `'${value.replace(/'/g, "''")}'`;
 }
-function buildNotifyCommand(platform, title, message) {
+function buildNotifyCommand(platform, title, message, options = {}) {
+  const { url, hasTerminalNotifier: hasTerminalNotifier2 = false } = options;
   switch (platform) {
     case "darwin":
+      if (url && hasTerminalNotifier2) {
+        return {
+          cmd: "terminal-notifier",
+          args: ["-title", title, "-message", message, "-open", url, "-group", "ai.suveren.gateway"]
+        };
+      }
       return {
         cmd: "osascript",
         args: ["-e", `display notification ${osaQuote(message)} with title ${osaQuote(title)}`]
@@ -1631,13 +1638,30 @@ function buildNotifyCommand(platform, title, message) {
   }
 }
 function lockedNotification(port2) {
+  const url = `http://localhost:${port2}`;
   return {
     title: "Suveren is running but locked",
-    message: `Your agent has no authority until you unlock it. Open http://localhost:${port2} and enter your API key.`
+    message: `Your agent has no authority until you unlock it. Open ${url} and enter your API key.`,
+    url
   };
 }
-function notify(title, message, platform = process.platform) {
-  const command = buildNotifyCommand(platform, title, message);
+var terminalNotifierCache = null;
+function hasTerminalNotifier() {
+  if (terminalNotifierCache !== null) return terminalNotifierCache;
+  try {
+    const probe = spawnSync("terminal-notifier", ["-help"], { stdio: "ignore" });
+    terminalNotifierCache = probe.error === void 0;
+  } catch {
+    terminalNotifierCache = false;
+  }
+  return terminalNotifierCache;
+}
+function notify(title, message, platform = process.platform, url) {
+  const command = buildNotifyCommand(platform, title, message, {
+    url,
+    // Only probe when a URL could actually be attached.
+    hasTerminalNotifier: url !== void 0 && platform === "darwin" ? hasTerminalNotifier() : false
+  });
   if (!command) return;
   try {
     const child = spawn(command.cmd, command.args, { detached: true, stdio: "ignore" });
@@ -2546,8 +2570,8 @@ if (existsSync5(UI_DIST)) {
 app.listen(port, "0.0.0.0", () => {
   console.error(`[Control Plane] Listening on http://0.0.0.0:${port}`);
   if (process.env.SUVEREN_AUTOSTART === "1" && !vault.isUnlocked()) {
-    const { title, message } = lockedNotification(port);
-    notify(title, message);
+    const { title, message, url } = lockedNotification(port);
+    notify(title, message, process.platform, url);
   }
   console.error(`[Control Plane]   SP proxy: ${SP_URL2}`);
   console.error(`[Control Plane]   UI dist:  ${UI_DIST}`);

package/dist/mcp-server/http.mjs

@@ -1157,9 +1157,11 @@ function computeContentBinding(profileId, tool, toolArgs) {
   if (binding.kind === "jcs") {
     contentHash = computeContentHash(binding, toolArgs);
   } else {
-    const field = tool ? detectContentField(tool) : null;
+    const declared = tool?.gating?.contentField;
+    const field = declared ?? (tool ? detectContentField(tool) : null);
     if (!field) return void 0;
     const raw = typeof toolArgs[field] === "string" ? toolArgs[field] : "";
+    if (raw === "") return void 0;
     contentHash = computeContentHash(binding, raw);
   }
   return {
@@ -1445,6 +1447,22 @@ function denyRead(state2, tool, reason, detail, target) {
   return { content: [{ type: "text", text: `Read blocked by Gatekeeper: ${detail}` }], isError: true };
 }
 function createGatedToolHandler(tool, integrationManager2, state2) {
+  const inner = createGatedToolHandlerInner(tool, integrationManager2, state2);
+  const blocked = tool.gating?.blockedArgs ?? [];
+  if (blocked.length === 0) return inner;
+  return async (args) => {
+    const present = blocked.filter((a) => a in (args ?? {}));
+    if (present.length === 0) return inner(args);
+    return {
+      content: [{
+        type: "text",
+        text: `Refused: "${tool.namespacedName}" was called with ${present.map((b) => `"${b}"`).join(", ")}, which the integration manifest blocks. That argument carries the whole request in one opaque value, so the recipients, the content and the limits on this authorization cannot be read from it \u2014 the call could not be shown to stay in scope, and could not be shown to a human for approval in any form they could judge. Use the individual arguments instead.`
+      }],
+      isError: true
+    };
+  };
+}
+function createGatedToolHandlerInner(tool, integrationManager2, state2) {
   if (!tool.gating || !tool.gating.profile) {
     return async () => {
       return {
@@ -2611,6 +2629,19 @@ function readAgeOf(config) {
   const days = config.readAgeDays;
   return typeof days === "number" && Number.isFinite(days) && days >= 0 ? days : null;
 }
+function withoutBlockedArgs(schema, blocked) {
+  if (!blocked?.length) return schema;
+  const props = schema.properties;
+  if (!props) return schema;
+  const kept = Object.fromEntries(Object.entries(props).filter(([k]) => !blocked.includes(k)));
+  const out = { ...schema, properties: kept };
+  if (Array.isArray(schema.required)) {
+    out.required = schema.required.filter(
+      (r) => typeof r !== "string" || !blocked.includes(r)
+    );
+  }
+  return out;
+}
 var RESPAWN_DELAYS = [2e3, 4e3, 6e3];
 var MAX_RESPAWN_ATTEMPTS = 3;
 var CONNECT_TIMEOUT_MS = 3e4;
@@ -2806,7 +2837,14 @@ var IntegrationManager = class {
         namespacedName: `${config.id}__${tool.name}`,
         integrationId: config.id,
         description: tool.description ?? "",
-        inputSchema: tool.inputSchema ?? {},
+        // 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
+        ),
         gating
       };
     });
@@ -3011,13 +3049,20 @@ var IntegrationManager = class {
           requiredValue: ext.requiredValue,
           read: ext.read,
           readGovernance: ext.readGovernance,
-          readGovernanceReason: ext.readGovernanceReason
+          readGovernanceReason: ext.readGovernanceReason,
+          blockedArgs: ext.blockedArgs
         };
       }
       return {
         profile: profileId,
         executionMapping: override.executionMapping,
-        staticExecution: override.staticExecution
+        staticExecution: override.staticExecution,
+        // Which argument the receipt binds to. This resolver is an explicit
+        // whitelist, so a field added to the manifest and the type but not
+        // copied here is silently dropped — the receipt is still issued and
+        // simply carries no binding, which only surfaces when a verifier asks.
+        contentField: ext.contentField,
+        blockedArgs: ext.blockedArgs
       };
     }
     return {