@suveren/gateway 0.4.1 → 0.6.0

package/bin/suveren-gateway.js

@@ -11,6 +11,7 @@
  */
 
 import { spawn, spawnSync } from 'node:child_process';
+import { createConnection } from 'node:net';
 import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -60,6 +61,24 @@ async function start(args) {
     process.exit(1);
   }
 
+  // The PID file only knows about instances THIS CLI started. A gateway
+  // started by the login service — or from another shell — leaves none, so the
+  // check above passes, we spawn, the child dies instantly with EADDRINUSE,
+  // and its error goes only to the log. The user gets "started (pid N)" for a
+  // process that is already dead. Ask the port, not just the file.
+  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`);
+    process.exit(1);
+  }
+
   ensureDataDir();
 
   if (detach) {
@@ -71,6 +90,24 @@ async function start(args) {
     });
     writeFileSync(PID_FILE, String(child.pid), 'utf8');
     child.unref();
+
+    // "started" must mean SERVING. A detached child that dies on startup takes
+    // its error to the log, so reporting success on spawn alone hands the user
+    // a pid that no longer exists and a browser tab that will not connect.
+    const serving = await waitForListening(SUVEREN_PORT, 20_000);
+    if (!serving) {
+      safeUnlink(PID_FILE);
+      console.error(`suveren-gateway failed to start — nothing is listening on ${SUVEREN_PORT}.`);
+      console.error(``);
+      console.error(`  Log:  ${LOG_FILE}`);
+      console.error(`  Last lines:`);
+      try {
+        const tail = readFileSync(LOG_FILE, 'utf8').trimEnd().split('\n').slice(-8);
+        for (const line of tail) console.error(`    ${line}`);
+      } catch { /* no log yet */ }
+      process.exit(1);
+    }
+
     console.log(`suveren-gateway started (pid ${child.pid})`);
     console.log(``);
     console.log(`  → Open in your browser:  http://localhost:${SUVEREN_PORT}`);
@@ -313,14 +350,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(``);
@@ -358,7 +411,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
@@ -532,6 +591,28 @@ function serviceImplFor(os) {
   }
 }
 
+/** Is something accepting TCP connections on this port? */
+function isPortListening(port, timeoutMs = 1_000) {
+  return new Promise(resolve => {
+    const socket = createConnection({ host: '127.0.0.1', port: Number(port) });
+    const done = (result) => { socket.destroy(); resolve(result); };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
+/** Poll until the port accepts connections, or give up. */
+async function waitForListening(port, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isPortListening(port, 500)) return true;
+    await sleep(300);
+  }
+  return false;
+}
+
 /** Run a command capturing output, never throwing. */
 function runQuiet(bin, args) {
   const r = spawnSync(bin, args, { encoding: 'utf8' });

package/content/integrations/calendar.json

@@ -5,6 +5,9 @@
   "description": "List, create, update, and delete events in Google Calendar",
   "icon": "calendar",
   "profile": "calendar",
+  "readPolicy": {
+    "defaultAgeDays": 30
+  },
   "npmPackage": "@humanagencyp/google-calendar-mcp",
   "mcp": {
     "command": "google-calendar-mcp",
@@ -12,8 +15,18 @@
   },
   "credentials": {
     "fields": [
-      { "key": "clientId", "label": "Client ID", "type": "text", "placeholder": "From Google Cloud Console" },
-      { "key": "clientSecret", "label": "Client Secret", "type": "password", "placeholder": "OAuth2 client secret" }
+      {
+        "key": "clientId",
+        "label": "Client ID",
+        "type": "text",
+        "placeholder": "From Google Cloud Console"
+      },
+      {
+        "key": "clientSecret",
+        "label": "Client Secret",
+        "type": "password",
+        "placeholder": "OAuth2 client secret"
+      }
     ],
     "envMapping": {
       "GOOGLE_CLIENT_ID": "clientId",
@@ -30,9 +43,15 @@
       "https://www.googleapis.com/auth/calendar.events",
       "https://www.googleapis.com/auth/calendar.readonly"
     ],
-    "credentialKeys": { "clientId": "clientId", "clientSecret": "clientSecret" },
+    "credentialKeys": {
+      "clientId": "clientId",
+      "clientSecret": "clientSecret"
+    },
     "tokenStorage": "refreshToken",
-    "extraParams": { "access_type": "offline", "prompt": "consent" }
+    "extraParams": {
+      "access_type": "offline",
+      "prompt": "consent"
+    }
   },
   "contextDiscovery": {
     "allowed_calendars": {
@@ -53,52 +72,103 @@
   "toolGating": {
     "default": {
       "executionMapping": {},
-      "staticExecution": { "duration": 0, "lookahead": 0 }
+      "staticExecution": {
+        "duration": 0,
+        "lookahead": 0
+      }
     },
     "overrides": {
       "list_calendars": {
         "category": "read",
-        "read": { "resourceBound": "allowed_calendars", "resultResourcePath": "id" }
+        "read": {
+          "resourceBound": "allowed_calendars",
+          "resultResourcePath": "id"
+        }
       },
       "list_events": {
         "category": "read",
-        "read": { "resourceBound": "allowed_calendars", "resourceArg": "calendarId", "resourceDefault": "primary" }
+        "read": {
+          "resourceBound": "allowed_calendars",
+          "resourceArg": "calendarId",
+          "resourceDefault": "primary",
+          "ageField": "read_age_days",
+          "ageFloorArg": "timeMin",
+          "ageFloorFormat": "iso"
+        }
       },
       "get_event": {
         "category": "read",
-        "read": { "resourceBound": "allowed_calendars", "resourceArg": "calendarId", "resourceDefault": "primary" }
+        "read": {
+          "resourceBound": "allowed_calendars",
+          "resourceArg": "calendarId",
+          "resourceDefault": "primary",
+          "ageField": "read_age_days",
+          "resultDatePath": [
+            "start.dateTime",
+            "start.date"
+          ]
+        }
       },
       "free_busy": {
         "category": "read",
-        "read": { "resourceBound": "allowed_calendars", "resourceArrayArg": "calendarIds", "resourceDefault": "primary" }
+        "read": {
+          "resourceBound": "allowed_calendars",
+          "resourceArrayArg": "calendarIds",
+          "resourceDefault": "primary",
+          "ageField": "read_age_days",
+          "ageFloorArg": "timeMin",
+          "ageFloorFormat": "iso"
+        }
       },
       "create_event": {
         "executionMapping": {
           "duration_minutes": "duration",
           "lookahead_days": "lookahead",
           "attendees": [
-            { "field": "allowed_attendees", "transform": "join" },
-            { "field": "allowed_domains", "transform": "join_domains" }
+            {
+              "field": "allowed_attendees",
+              "transform": "join"
+            },
+            {
+              "field": "allowed_domains",
+              "transform": "join_domains"
+            }
           ],
           "calendarId": "allowed_calendars"
         },
-        "staticExecution": { "action_type": "booking" }
+        "staticExecution": {
+          "action_type": "booking"
+        }
       },
       "update_event": {
         "executionMapping": {
           "attendees": [
-            { "field": "allowed_attendees", "transform": "join" },
-            { "field": "allowed_domains", "transform": "join_domains" }
+            {
+              "field": "allowed_attendees",
+              "transform": "join"
+            },
+            {
+              "field": "allowed_domains",
+              "transform": "join_domains"
+            }
           ],
           "calendarId": "allowed_calendars"
         },
-        "staticExecution": { "action_type": "booking", "duration": 0, "lookahead": 0 }
+        "staticExecution": {
+          "action_type": "booking",
+          "duration": 0,
+          "lookahead": 0
+        }
       },
       "delete_event": {
         "executionMapping": {
           "calendarId": "allowed_calendars"
         },
-        "staticExecution": { "action_type": "delete", "duration": 0, "lookahead": 0 }
+        "staticExecution": {
+          "action_type": "delete",
+          "duration": 0,
+          "lookahead": 0
+        }
       }
     }
   },
@@ -108,22 +178,46 @@
       "description": "List and read events, check free/busy. No create, update, or delete.",
       "risk": "low",
       "mode": "automatic",
-      "bounds": { "booking_daily_max": "0", "booking_duration_max": "0", "lookahead_days_max": "0" },
-      "context": { "allowed_calendars": "primary", "allowed_attendees": "", "allowed_domains": "" },
+      "bounds": {
+        "booking_daily_max": "0",
+        "booking_duration_max": "0",
+        "lookahead_days_max": "0"
+      },
+      "context": {
+        "allowed_calendars": "primary",
+        "allowed_attendees": "",
+        "allowed_domains": ""
+      },
       "intent": "Allow the agent to read the primary calendar (only) to help with scheduling suggestions. No create or modify. To read other calendars, add them to allowed_calendars.",
       "ttl": 2592000,
-      "tags": ["read-only", "30 days"]
+      "tags": [
+        "read-only",
+        "30 days"
+      ]
     },
     {
       "name": "Book with Review",
       "description": "Read events and propose new bookings. Every create/update/delete requires your approval.",
       "risk": "high",
       "mode": "review",
-      "bounds": { "booking_daily_max": "3", "booking_duration_max": "120", "lookahead_days_max": "30" },
-      "context": { "allowed_calendars": "primary", "allowed_attendees": "", "allowed_domains": "" },
+      "bounds": {
+        "booking_daily_max": "3",
+        "booking_duration_max": "120",
+        "lookahead_days_max": "30"
+      },
+      "context": {
+        "allowed_calendars": "primary",
+        "allowed_attendees": "",
+        "allowed_domains": ""
+      },
       "intent": "Read my calendar and propose bookings. Every create, update, or delete requires my review — I see the title, time, duration, and attendees before it goes through.",
       "ttl": 2592000,
-      "tags": ["3 bookings/day", "2h max", "30d lookahead", "review mode"]
+      "tags": [
+        "3 bookings/day",
+        "2h max",
+        "30d lookahead",
+        "review mode"
+      ]
     }
   ],
   "setupHint": "Create OAuth credentials at Google Cloud Console and enable the Google Calendar API.",

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

@@ -6,6 +6,9 @@
   "icon": "mail",
   "profile": "email",
   "npmPackage": "@shinzolabs/gmail-mcp",
+  "readPolicy": {
+    "defaultAgeDays": 30
+  },
   "mcp": {
     "command": "gmail-mcp",
     "args": [],
@@ -80,7 +83,10 @@
         },
         "staticExecution": {
           "action_type": "send"
-        }
+        },
+        "blockedArgs": [
+          "raw"
+        ]
       },
       "create_draft": {
         "executionMapping": {
@@ -101,7 +107,10 @@
         },
         "staticExecution": {
           "action_type": "send"
-        }
+        },
+        "blockedArgs": [
+          "raw"
+        ]
       },
       "send_draft": {
         "executionMapping": {},
@@ -184,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."
       }
     }
   },
@@ -227,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"
   }
 }