@nimbus-dev/connectors 0.11.0 → 0.12.0

package/connectors/gmail/src/tool-scope-policy.ts

@@ -0,0 +1,38 @@
+/**
+ * Which Gmail tools need an OAuth scope beyond the connector's default grant, and whether the token
+ * the gateway passes holds it. The gateway sets `GOOGLE_OAUTH_SCOPES` (space-separated, the full
+ * scope URIs Google returns) from the `google.oauth` Vault entry.
+ *
+ * Unlike Outlook's policy, an ABSENT env does NOT register a scope-gated tool: a gateway that does
+ * not pass scopes (every gateway before the one that pins this release) never lists a write its
+ * token cannot perform. Every tool without an entry below registers as before.
+ */
+const GMAIL_MODIFY = "https://www.googleapis.com/auth/gmail.modify";
+/** The full-mailbox scope, a superset of `gmail.modify`. */
+const GMAIL_FULL = "https://mail.google.com/";
+
+const GMAIL_TOOL_MIN_SCOPES: Readonly<Record<string, readonly string[]>> = {
+  gmail_thread_archive: [GMAIL_MODIFY],
+};
+
+function scopeSatisfied(granted: ReadonlySet<string>, required: string): boolean {
+  if (granted.has(required)) return true;
+  return required === GMAIL_MODIFY && granted.has(GMAIL_FULL);
+}
+
+/** The scopes in `GOOGLE_OAUTH_SCOPES`, or `undefined` when it is unset or blank. */
+export function parseGoogleOAuthScopesFromEnv(): string[] | undefined {
+  const raw = process.env["GOOGLE_OAUTH_SCOPES"];
+  if (raw === undefined) return undefined;
+  const parts = raw.split(/\s+/).filter((s) => s.length > 0);
+  return parts.length === 0 ? undefined : parts;
+}
+
+/** Whether `toolId` registers for a token holding `granted` (`undefined`: scopes unknown). */
+export function gmailToolShouldRegister(toolId: string, granted: string[] | undefined): boolean {
+  const reqs = GMAIL_TOOL_MIN_SCOPES[toolId];
+  if (reqs === undefined) return true;
+  if (granted === undefined) return false;
+  const g = new Set(granted);
+  return reqs.every((r) => scopeSatisfied(g, r));
+}

package/connectors/gmail/src/tools.ts

@@ -12,6 +12,7 @@ import {
   makeRestToolRegistrar,
   makeRestWriteToolRegistrar,
 } from "../../../shared/rest-tool-kit.ts";
+import { gmailToolShouldRegister, parseGoogleOAuthScopesFromEnv } from "./tool-scope-policy.ts";
 
 const GMAIL_BASE = "https://gmail.googleapis.com/gmail/v1/users/me";
 
@@ -67,7 +68,7 @@ export function registerGmailTools(
   const registerWriteTool = createWriteToolRegistrar(server, {
     connector: "gmail",
     scopeEnv: "NIMBUS_MCP_GMAIL_WRITE_SCOPE",
-    scopeKinds: ["recipient", "draft"],
+    scopeKinds: ["recipient", "draft", "thread"],
   });
 
   /**
@@ -206,4 +207,26 @@ export function registerGmailTools(
     () => `${GMAIL_BASE}/messages/send`,
     (data) => jsonPost({ raw: rawMessage(data) }),
   );
+
+  // Registered only when the token holds `gmail.modify` (or the full-mailbox scope): the default
+  // grant is read + compose, and a fresh `nimbus connector auth gmail` is what adds it.
+  if (gmailToolShouldRegister("gmail_thread_archive", parseGoogleOAuthScopesFromEnv())) {
+    const gmailThreadArchiveArgs = z.object({
+      // Gmail thread ids are hex; anything else is refused before any request.
+      threadId: z.string().regex(/^[A-Za-z0-9]{1,64}$/, "threadId must be a Gmail thread id"),
+    });
+
+    registerGmailWriteTool(
+      "gmail_thread_archive",
+      {
+        mutates: "gmail.thread.archive",
+        recoverable: true,
+        scopeTargetOf: (p) => ({ kind: "thread", value: p.threadId }),
+      },
+      "Archive a Gmail thread: remove it from the inbox (every message keeps its other labels; nothing is deleted). Requires Gateway HITL gmail.thread.archive.",
+      gmailThreadArchiveArgs,
+      (data) => `${GMAIL_BASE}/threads/${encodeURIComponent(data.threadId)}/modify`,
+      () => jsonPost({ removeLabelIds: ["INBOX"] }),
+    );
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "publishConfig": {
     "access": "public"
   },