gogcli-mcp 2.24.0 → 2.26.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -110,7 +110,7 @@
     },
     {
       "name": "gog_gmail_send",
-      "description": "Send an email"
+      "description": "Send an email, with attachments from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)"
     },
     {
       "name": "gog_gmail_run",
@@ -423,6 +423,86 @@
     {
       "name": "gog_slides_run",
       "description": "Run any gog slides subcommand (escape hatch)"
+    },
+    {
+      "name": "gog_chat_spaces_list",
+      "description": "List the Google Chat spaces the account belongs to, with their resource names"
+    },
+    {
+      "name": "gog_chat_spaces_find",
+      "description": "Find Chat spaces by display name (substring by default, or exact)"
+    },
+    {
+      "name": "gog_chat_spaces_create",
+      "description": "Create a named Chat space, optionally seeding its membership"
+    },
+    {
+      "name": "gog_chat_threads_list",
+      "description": "List the threads in a Chat space"
+    },
+    {
+      "name": "gog_chat_messages_list",
+      "description": "Read messages in a space, with mentions and reaction summaries"
+    },
+    {
+      "name": "gog_chat_messages_send",
+      "description": "Post a message to a Chat space (immediately visible; supports attachments)"
+    },
+    {
+      "name": "gog_chat_dm_send",
+      "description": "Send a direct message to one person by email address"
+    },
+    {
+      "name": "gog_chat_dm_space",
+      "description": "Resolve the DM space resource name for an email address"
+    },
+    {
+      "name": "gog_chat_reactions_list",
+      "description": "List the emoji reactions on a message, with who reacted"
+    },
+    {
+      "name": "gog_chat_reactions_create",
+      "description": "React to a Chat message with an emoji"
+    },
+    {
+      "name": "gog_chat_reactions_delete",
+      "description": "Remove one emoji reaction by its resource name"
+    },
+    {
+      "name": "gog_chat_run",
+      "description": "Run any gog chat subcommand not covered by the other tools"
+    },
+    {
+      "name": "gog_appscript_get",
+      "description": "Get an Apps Script project's metadata"
+    },
+    {
+      "name": "gog_appscript_content",
+      "description": "Read a project's source files and manifest inline"
+    },
+    {
+      "name": "gog_appscript_pull",
+      "description": "Write a project's files into a directory on the machine where gog runs"
+    },
+    {
+      "name": "gog_appscript_create",
+      "description": "Create a new, empty Apps Script project (optionally bound to a Drive file)"
+    },
+    {
+      "name": "gog_appscript_deployments",
+      "description": "List a project's deployments"
+    },
+    {
+      "name": "gog_appscript_versions",
+      "description": "List a project's saved versions"
+    },
+    {
+      "name": "gog_appscript_run_function",
+      "description": "Execute a function in a deployed Apps Script project"
+    },
+    {
+      "name": "gog_appscript_run",
+      "description": "Run any gog appscript subcommand not covered by the other tools"
     }
   ],
   "compatibility": {

package/mint.yaml

@@ -0,0 +1,106 @@
+version: 1
+name: gogcli (Google Workspace)
+slug: gogcli-mcp
+summary: >-
+  MCP server wrapping gogcli for Google service access
+command:
+  # This package publishes a single bin; naming it keeps the install
+  # unambiguous alongside its eight sibling packages.
+  bin: gogcli-mcp
+env:
+  - name: GOG_CLIENT_ID
+    required: false
+    help: >-
+      Google OAuth client id. NOTE: on the local-spawn path the child `gog`
+      receives a sanitized env — runner.ts drops GOG_ACCESS_TOKEN and every
+      *_TOKEN / *_SECRET / *_API_KEY / *_PRIVATE_KEY variable — so the CLI
+      authenticates from its own stored credentials under $HOME (see
+      state.dataDir), not from these variables being passed through.
+  - name: GOG_CLIENT_SECRET
+    secret: true
+    required: false
+    help: >-
+      Google OAuth client secret. Stripped from the spawned CLI's environment
+      by runner.ts's *_SECRET rule — see GOG_CLIENT_ID.
+  - name: GOG_REFRESH_TOKEN
+    secret: true
+    required: false
+    help: >-
+      Google OAuth refresh token. Stripped from the spawned CLI's environment
+      by runner.ts's *_TOKEN rule — see GOG_CLIENT_ID. A hosted deployment must
+      therefore carry gog's authorised-account state in its persisted data dir,
+      or drive a remote runner via GOG_RUNNER_URL.
+  - name: GOG_ACCESS_TOKEN
+    secret: true
+    required: false
+    help: >-
+      Deliberately removed from the spawned CLI's environment by runner.ts, so
+      that a stale directly-passed token cannot shadow gog's stored refresh
+      credential. Leave unset.
+  - name: GOG_ACCOUNT
+    required: false
+    help: >-
+      Which configured Google account to act as, when more than one is
+      authorised. Defaults to the single/most recent account.
+  - name: GOG_READONLY
+    required: false
+    help: >-
+      Set to 1 to refuse every mutating operation. Recommended when the
+      connector is shared or you only need reads.
+  - name: GOG_PATH
+    required: false
+    help: >-
+      Path to the `gog` binary. Leave unset when the dependency below supplies
+      it; set it only to point at a binary you manage yourself.
+  - name: GOG_RUNNER_URL
+    required: false
+    help: >-
+      URL of a remote gog runner to execute against instead of spawning the
+      local binary. If you set this, add its host to egress.allow.
+  - name: GOG_RUNNER_KEY
+    secret: true
+    required: false
+    help: >-
+      Shared key authenticating calls to GOG_RUNNER_URL. Required whenever that
+      is set.
+  - name: GOG_TIMEZONE
+    required: false
+    help: >-
+      The IANA zone gog itself formats its naive timestamps in. The wrapper
+      reads it (naiveSourceTimeZone) to re-attach the correct offset, so it
+      should match gog's own configuration. Falls back to DISPLAY_TZ, then to
+      America/New_York.
+  - name: DISPLAY_TZ
+    required: false
+    help: >-
+      The IANA zone every rendered *Display field uses (displayTimeZone,
+      default America/New_York). It does not read GOG_TIMEZONE — the fallback
+      runs the other way, so this is also what GOG_TIMEZONE falls back to. An
+      invalid value degrades to the default rather than throwing.
+dependencies:
+  # Every tool shells out to the `gog` CLI; without it the server starts and
+  # then fails on the first call. This tag must track
+  # packages/gogcli-mcp/src/runner.ts's MIN_GOG_VERSION (the floor the tools
+  # assume) and the fly-gog-runner/Dockerfile GOG_VERSION build arg. See
+  # CLAUDE.md "Required gog version" — bumping the floor means bumping these
+  # nine pins too.
+  - kind: github-release
+    repo: openclaw/gogcli
+    tag: v0.38.1
+    asset: "gogcli_*_linux_amd64.tar.gz"
+    bin: [gog]
+state:
+  dataDir: true
+  reason: >-
+    `gog` keeps its authorised-account state and token cache under $HOME.
+    Without a persistent data dir every cold start has no account configured and
+    every tool call fails until the credentials are re-supplied.
+egress:
+  allow:
+    # Google OAuth token exchange and the Google REST APIs the CLI calls.
+    - oauth2.googleapis.com
+    - www.googleapis.com
+    - googleapis.com
+    #
+    # NOTE: if you set GOG_RUNNER_URL to run against a remote gog runner, add
+    # that host here too — it is supplied at runtime and cannot be declared.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -41,15 +41,15 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.15.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@vitest/coverage-v8": "^4.1.8",
-    "esbuild": "^0.28.1",
+    "esbuild": "^0.28.2",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   }
 }

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "2.24.0",
+  "version": "2.26.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "2.24.0",
+      "version": "2.26.0",
       "transport": {
         "type": "stdio"
       },

package/src/attachments.ts

@@ -0,0 +1,263 @@
+import { z } from 'zod';
+import type { GogArg, GogFileArg } from './runner.js';
+
+/**
+ * Caller-supplied attachment BYTES, for hosts that share no filesystem with gog.
+ *
+ * ## Why this exists
+ *
+ * Every attachment input gog offers is a PATH — `gmail send --attach`,
+ * `gmail drafts create --attach`, `drive upload <localPath>` — and those paths
+ * resolve wherever gog runs. On the local stdio transport that is the caller's
+ * own machine and everything works. On the hosted connector, and on any host
+ * that reaches a backend through GOG_RUNNER_URL, gog runs somewhere else
+ * entirely: no path the caller can name exists there, so outbound attachments
+ * were simply impossible — including via Drive, whose upload takes a path too.
+ *
+ * The seam that fixes it already existed. `GogFileArg` writes a payload to a
+ * private temp file NEXT TO GOG — on the runner for the remote path, in a
+ * mkdtemp dir for the local one — and passes the resulting path. It was built
+ * for oversized text (a long HTML mail body) that could not fit in argv; all
+ * binary attachments need on top of that is a base64 spelling and control of
+ * the basename, both of which are now `GogFileArg` fields.
+ *
+ * So an inline attachment is not a new transport. It is the same temp-file
+ * hand-off, carrying bytes instead of prose.
+ */
+
+// Ceiling for ONE attachment's decoded bytes.
+//
+// Pinned to the Fly runner's own MAX_FILE_ARG_BYTES (fly-gog-runner/server.mjs)
+// so the two agree. That matters: without a check here the local stdio path
+// would accept any size while the remote path refused at 8 MiB, and the caller
+// would meet the limit as a transport rejection from a layer they cannot see.
+// Checked in the TOOL so the error names the file and the limit instead.
+export const MAX_INLINE_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+
+// The Fly runner caps an ENTIRE /run request body at 32 MiB
+// (fly-gog-runner/server.mjs MAX_BODY_BYTES). Restated rather than imported:
+// that package is not a dependency of this one, and the Worker bundle must not
+// pull it in. Keep the two in sync.
+const RUNNER_MAX_BODY_BYTES = 32 * 1024 * 1024;
+
+// Room inside that body for the JSON structure alone — key names, quoting,
+// commas, the accessToken, and the short flag strings (`--to=…`, `--subject=…`).
+// It does NOT have to cover the mail body: a large body is a GogFileArg, and
+// GogFileArgs are measured explicitly below rather than absorbed here.
+const RUNNER_BODY_JSON_RESERVE_BYTES = 256 * 1024;
+
+/**
+ * How many bytes of PAYLOAD one `/run` request can carry, counted as they are
+ * spelled on the wire.
+ *
+ * The binding constraint on a message is its wire size, not the decoded size of
+ * its files, and it is tighter than Gmail's own 25 MB limit: connector-runtime
+ * sends every payload inside one `JSON.stringify({ args, accessToken })` body,
+ * where binary rides as base64 (4/3 inflation) and text rides verbatim. A limit
+ * expressed in decoded bytes must absorb that inflation or it documents a size
+ * the runner rejects with "request body too large" — a rejection from a layer
+ * the caller cannot see, which is exactly what pinning the per-file ceiling to
+ * MAX_FILE_ARG_BYTES exists to prevent.
+ */
+export const MAX_REQUEST_PAYLOAD_WIRE_BYTES = RUNNER_MAX_BODY_BYTES - RUNNER_BODY_JSON_RESERVE_BYTES;
+
+// Ceiling for all inline attachments on one message, in DECODED bytes — the
+// units a caller thinks in, derived from the wire budget above.
+//
+// This is the ceiling for attachments ALONE. Anything else large in the same
+// request spends the same budget — most of all the mail body, which `payloadArg`
+// turns into a GogFileArg past 4 KiB and which then rides in the same JSON body
+// at roughly 1:1. `inlineAttachmentArgs` therefore measures the actual sibling
+// args rather than trusting this number, so a 23 MiB attachment set plus a
+// multi-MiB HTML body is refused here, with an error naming the body, instead of
+// arriving as a bare transport rejection.
+//
+// Neither bound is hypothetical at the edges: three attachments at the
+// documented 8 MiB per-file maximum is 24 MiB, which alone encodes to exactly
+// MAX_BODY_BYTES, leaving nothing for anything else.
+export const MAX_INLINE_ATTACHMENT_TOTAL_BYTES = Math.floor((MAX_REQUEST_PAYLOAD_WIRE_BYTES * 3) / 4);
+
+/**
+ * Bytes one already-assembled arg occupies in the `/run` JSON body.
+ *
+ * A plain string costs its UTF-8 length; a file arg costs the length of its
+ * `contents` as spelled on the wire — the base64 text for binary, the UTF-8
+ * text itself otherwise. JSON quoting and key names are covered by the reserve.
+ */
+function wireBytesOf(arg: GogArg): number {
+  if (typeof arg === 'string') return Buffer.byteLength(arg, 'utf8');
+  return arg.encoding === 'base64' ? arg.contents.length : Buffer.byteLength(arg.contents, 'utf8');
+}
+
+// FLOOR, never round: this number is published to callers as a limit, so it has
+// to be one they can actually send. Rounding 23.25 MiB up to "24 MiB" would
+// document a size that gets rejected.
+const formatMiB = (bytes: number): string => `${Math.floor(bytes / (1024 * 1024))} MiB`;
+
+/** Human-readable ceilings, for tool descriptions — so the docs cannot drift. */
+export const INLINE_ATTACHMENT_LIMITS_TEXT =
+  `up to ${formatMiB(MAX_INLINE_ATTACHMENT_BYTES)} per file and ` +
+  `${formatMiB(MAX_INLINE_ATTACHMENT_TOTAL_BYTES)} in total`;
+
+/**
+ * One attachment supplied as bytes rather than as a path.
+ *
+ * `mimeType` is deliberately ABSENT. gog derives an attachment's MIME type from
+ * the filename extension (`mailmime.PrepareAttachments`) and exposes no flag to
+ * override it, so a `mimeType` field here could only ever be accepted and
+ * ignored. Naming the file `chart.png` is what sets the type; a parameter that
+ * silently does nothing is worse than no parameter. (`gog_drive_upload` DOES
+ * take a real `mimeType`, because `drive upload --mime-type` exists.)
+ */
+export const inlineAttachmentSchema = z.object({
+  filename: z.string().min(1).describe(
+    'Filename the recipient will see, e.g. "pendant-layouts.png". gog infers the attachment\'s MIME '
+    + 'type from this extension, so give it the right one — a .png sent as "layouts" arrives as an '
+    + 'untyped blob. Must be a single filename, not a path.',
+  ),
+  contentBase64: z.string().min(1).describe(
+    'The file\'s bytes, base64-encoded (standard alphabet, with padding). This is the whole point of '
+    + 'this parameter: the bytes travel with the request, so nothing needs to exist on the gog server\'s '
+    + 'filesystem.',
+  ),
+});
+
+export type InlineAttachmentInput = z.infer<typeof inlineAttachmentSchema>;
+
+/** Reusable tool parameter — the same field on send, drafts create and update. */
+export const attachInlineParam = z.array(inlineAttachmentSchema).optional().describe(
+  'Attachments supplied as BYTES rather than as server-side paths — use this whenever you hold a file '
+  + 'and the gog server does not, which is always the case on the hosted connector and on any remote '
+  + `deployment. Each entry is {filename, contentBase64} (${INLINE_ATTACHMENT_LIMITS_TEXT}). `
+  + 'Can be combined with `attach`: the two name disjoint files (paths read on the server vs. bytes sent '
+  + 'with the call), and both end up as ordinary attachments on the message.',
+);
+
+/**
+ * Reject a filename that is a path, a traversal, or otherwise not one plain
+ * segment. It becomes both the temp file's basename and the name the recipient
+ * sees, so the two things it must not do are escape the temp directory and
+ * arrive misleading.
+ */
+function validateFilename(filename: string, where: string): void {
+  if (/[/\\]/.test(filename)) {
+    throw new Error(
+      `${where}: filename ${JSON.stringify(filename)} must be a bare filename, not a path. `
+      + 'Pass just the name the recipient should see, e.g. "report.pdf".',
+    );
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1f]/.test(filename) || /^\.+$/.test(filename) || filename.length > 200) {
+    throw new Error(
+      `${where}: filename ${JSON.stringify(filename)} is not a usable filename `
+      + '(no control characters, not "."/"..", 200 characters max).',
+    );
+  }
+}
+
+/**
+ * Decoded byte length of a base64 string, or null when it is not valid base64.
+ *
+ * `Buffer.from(…, 'base64')` never throws — it silently DROPS characters it does
+ * not recognise — so a truncated or whitespace-mangled payload would otherwise
+ * be written to disk as a corrupt file and mailed out as one. The round trip is
+ * what turns that into an error the caller can act on, at the boundary where
+ * their input arrived rather than in the recipient's inbox.
+ */
+function decodedLength(contentBase64: string): number | null {
+  const buf = Buffer.from(contentBase64, 'base64');
+  return buf.toString('base64') === contentBase64 ? buf.length : null;
+}
+
+/**
+ * Validate ONE caller-supplied file and turn it into a `GogFileArg`, which the
+ * executor materializes to a temp file beside gog.
+ *
+ * Throws with an actionable message on anything invalid. The MCP layer turns a
+ * thrown handler error into an `isError` result, so every rejection here reaches
+ * the caller as a readable sentence naming the file — rather than as a base64
+ * decode producing a silently corrupt upload, or as a transport-layer size
+ * rejection from a layer the caller cannot see.
+ *
+ * `positional` emits the path as a bare argv element instead of `--flag=path`,
+ * for subcommands that take the file as a positional argument
+ * (`gog drive upload <localPath>`).
+ *
+ * @returns the arg, and the file's decoded size so callers can total it.
+ */
+export function inlineFileArg(
+  flag: string,
+  attachment: InlineAttachmentInput,
+  opts: { positional?: boolean; where?: string } = {},
+): { arg: GogFileArg; bytes: number } {
+  const { filename, contentBase64 } = attachment;
+  const where = opts.where ?? `attachInline entry ${JSON.stringify(filename)}`;
+  validateFilename(filename, where);
+  const bytes = decodedLength(contentBase64);
+  if (bytes === null) {
+    throw new Error(
+      `${where}: contents are not valid base64. Send the standard alphabet with padding and no `
+      + 'line breaks — the value must survive a decode/re-encode round trip unchanged.',
+    );
+  }
+  if (bytes > MAX_INLINE_ATTACHMENT_BYTES) {
+    throw new Error(
+      `${where}: ${bytes} bytes exceeds the ${MAX_INLINE_ATTACHMENT_BYTES}-byte `
+      + `(${formatMiB(MAX_INLINE_ATTACHMENT_BYTES)}) per-file limit for inline content. `
+      + 'Upload it to Drive and link to it instead, or send it from a local (stdio) deployment '
+      + 'using a real server-side path.',
+    );
+  }
+  // `filename` (not `ext`) is what makes the delivered copy carry the caller's
+  // name: gog reads an attachment's MIME filename, and Drive's default title,
+  // off the path it is handed.
+  const arg: GogFileArg = { kind: 'file', flag, contents: contentBase64, encoding: 'base64', filename };
+  if (opts.positional) arg.positional = true;
+  return { arg, bytes };
+}
+
+/**
+ * Validate inline attachments and turn them into `GogFileArg`s for `flag`
+ * (repeatable — one arg per attachment), enforcing the per-message total on top
+ * of each file's own ceiling.
+ */
+export function inlineAttachmentArgs(
+  flag: string,
+  attachments: readonly InlineAttachmentInput[] | undefined,
+  siblingArgs: readonly GogArg[] = [],
+): GogArg[] {
+  if (!attachments?.length) return [];
+  const args: GogArg[] = [];
+  // What the rest of the request already spends. Overwhelmingly this is the mail
+  // body — small when inline, up to 8 MiB once payloadArg has made it a file arg
+  // — and measuring it is what keeps "every input was within its own documented
+  // limit" from still adding up to a rejected request.
+  const siblingWire = siblingArgs.reduce((sum, arg) => sum + wireBytesOf(arg), 0);
+  let attachmentWire = 0;
+  let decodedTotal = 0;
+  for (const attachment of attachments) {
+    const { arg, bytes } = inlineFileArg(flag, attachment);
+    attachmentWire += arg.contents.length;
+    decodedTotal += bytes;
+    if (siblingWire + attachmentWire > MAX_REQUEST_PAYLOAD_WIRE_BYTES) {
+      // Report in the units the caller supplied — decoded file bytes — and say
+      // so explicitly when the attachments would have fit on their own, because
+      // then it is the body that tipped the balance and shrinking the files is
+      // the wrong response.
+      const blame = attachmentWire <= MAX_REQUEST_PAYLOAD_WIRE_BYTES
+        ? ` These attachments would fit on their own; the rest of the message (its body, mostly) `
+          + `spends ${siblingWire} bytes of the same budget.`
+        : '';
+      throw new Error(
+        `This message is too large to send: ${decodedTotal} bytes of attachments `
+        + `(${attachmentWire} bytes once base64-encoded for transit) exceed the `
+        + `${MAX_REQUEST_PAYLOAD_WIRE_BYTES}-byte request limit.${blame} The ceiling for attachments `
+        + `alone is ${MAX_INLINE_ATTACHMENT_TOTAL_BYTES} bytes `
+        + `(${formatMiB(MAX_INLINE_ATTACHMENT_TOTAL_BYTES)}); a long body lowers it. Send fewer or `
+        + 'smaller files per message, shorten the body, or upload the large files to Drive and link them.',
+      );
+    }
+    args.push(arg);
+  }
+  return args;
+}

package/src/gmail-results.ts

@@ -177,6 +177,16 @@ export async function finalizeGmailSearch(
 // The merged payload keeps a nextPageToken only if pages remain when the cap is
 // hit, so finalizeGmailSearch still marks it truncated — running out of budget
 // is not the same as reaching the end, and must not read like it.
+//
+// A REPEATED CURSOR ENDS THE WALK TOO. Google can hand back a nextPageToken it
+// has already issued, and gog 0.38.0 fixed exactly that for its own `--all`
+// (openclaw/gogcli#1004) — but this walk is not gog's: it makes N separate
+// single-page calls, so a repeated cursor arrives here untouched. Following it
+// re-fetches a page already merged, so the caller gets the same threads twice
+// over, presented as more results and looking perfectly well-formed. The token
+// is KEPT when that happens, for the same reason the cap keeps it: the walk
+// never established an end, and a set that reads complete is precisely how mail
+// that exists gets reported as missing.
 export async function fetchGmailPages(
   runPage: (token: string | undefined) => Promise<CallToolResult>,
   itemsKey: 'threads' | 'messages',
@@ -186,6 +196,10 @@ export async function fetchGmailPages(
   const merged: unknown[] = [];
   let base: Record<string, unknown> | undefined;
   let token = startToken;
+  // Every cursor this walk has already fetched with, so one Google repeats is
+  // recognised rather than followed. Seeded with the caller's own cursor: a
+  // response echoing that back would re-fetch the page just merged.
+  const fetched = new Set<string>(startToken === undefined ? [] : [startToken]);
 
   for (let pages = 0; pages < maxPages; pages++) {
     const result = await runPage(token);
@@ -199,10 +213,23 @@ export async function fetchGmailPages(
     }
     base = parsed;
     merged.push(...(parsed[itemsKey] as unknown[]));
-    token = typeof parsed.nextPageToken === 'string' && parsed.nextPageToken !== ''
+    const next = typeof parsed.nextPageToken === 'string' && parsed.nextPageToken !== ''
       ? parsed.nextPageToken
       : undefined;
-    if (token === undefined) break;
+    if (next === undefined) {
+      token = undefined;
+      break;
+    }
+    // Checked BEFORE the next fetch, so the duplicate page is never requested
+    // and never merged. `token` keeps the repeated cursor so the result still
+    // reads as truncated — it is the honest answer, and handing it back lets a
+    // caller retry later rather than concluding there is nothing more.
+    if (fetched.has(next)) {
+      token = next;
+      break;
+    }
+    fetched.add(next);
+    token = next;
   }
 
   return finish(base as Record<string, unknown>, itemsKey, merged, token);

package/src/lib.ts

@@ -2,9 +2,11 @@ export {
   BASE_TOOL_REGISTRARS,
   VERSION,
   registerApiTools,
+  registerAppScriptTools,
   registerAuthTools,
   authToolsFor,
   registerCalendarTools,
+  registerChatTools,
   registerClassroomTools,
   registerContactsTools,
   registerDocsTools,
@@ -27,6 +29,20 @@ export { finalizeGmailSearch, fetchGmailPages } from './gmail-results.js';
 export type { FinalizeOptions, GmailListMethod } from './gmail-results.js';
 export { useRemoteGogRunner } from './remote-runner.js';
 export type { RunOptions, Spawner, GogExecutor, GogArg, GogFileArg } from './runner.js';
+// Caller-supplied attachment bytes — the only outbound attachment path that
+// works when the caller and gog share no filesystem (hosted connector, or any
+// GOG_RUNNER_URL backend). See src/attachments.ts.
+export {
+  attachInlineParam,
+  inlineAttachmentSchema,
+  inlineAttachmentArgs,
+  inlineFileArg,
+  INLINE_ATTACHMENT_LIMITS_TEXT,
+  MAX_INLINE_ATTACHMENT_BYTES,
+  MAX_INLINE_ATTACHMENT_TOTAL_BYTES,
+  MAX_REQUEST_PAYLOAD_WIRE_BYTES,
+} from './attachments.js';
+export type { InlineAttachmentInput } from './attachments.js';
 export {
   PAYLOAD_INLINE_MAX,
   payloadArg,