gogcli-mcp 2.24.0 → 2.25.0

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/lib.ts

@@ -27,6 +27,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,

package/src/runner.ts

@@ -18,12 +18,43 @@ export type Spawner = (
 export interface GogFileArg {
   /** Discriminant separating this from a plain argv string. */
   kind: 'file';
-  /** Flag NAME without leading dashes, e.g. 'body-html-file'. */
+  /**
+   * Flag NAME without leading dashes, e.g. 'body-html-file'. The materialized
+   * path is passed as `--<flag>=<path>`, EXCEPT when `positional` is set, where
+   * this names the temp file's parent directory and nothing else.
+   */
   flag: string;
-  /** The large payload, verbatim. */
+  /**
+   * The payload. Text verbatim when `encoding` is 'utf8' (the default); the
+   * base64 spelling of the bytes when it is 'base64'.
+   */
   contents: string;
   /** Temp-file extension without the dot, e.g. 'html'. Defaults to 'txt'. */
   ext?: string;
+  /**
+   * How to interpret `contents` when writing it. 'utf8' (default) preserves the
+   * existing text-payload behaviour exactly; 'base64' decodes first, which is
+   * what lets a caller hand over a PNG or a PDF without a shared filesystem.
+   */
+  encoding?: 'utf8' | 'base64';
+  /**
+   * Exact basename for the temp file, overriding the `<flag>.<ext>` default.
+   *
+   * Load-bearing for attachments: gog reads the MIME part's filename off the
+   * path it is given, so a file materialized as `attach.txt` would arrive in the
+   * recipient's mailbox named `attach.txt` no matter what the caller called it.
+   * Callers MUST pass an already-sanitized single path segment.
+   */
+  filename?: string;
+  /**
+   * Emit the materialized path as a BARE argv element instead of `--flag=path`.
+   *
+   * For subcommands taking the file as a positional argument — `gog drive
+   * upload <localPath>` is the only one today. Argument ORDER is preserved by
+   * every executor, so a positional file arg lands exactly where it sat in the
+   * caller's array.
+   */
+  positional?: boolean;
 }
 
 export type GogArg = string | GogFileArg;
@@ -157,6 +188,25 @@ export interface RunOptions {
   // carries no token, so stripping only real token shapes keeps it intact while
   // still catching any token that unexpectedly appears.
   redactMode?: 'full' | 'tokens';
+  // JSON string fields whose values are OPAQUE binary payloads this wrapper
+  // asked for by name — `contentBase64` from `gog gmail attachment --inline`
+  // being the only one today. Their values are lifted out before redaction runs
+  // and put back verbatim afterwards.
+  //
+  // Redaction exists to catch a credential that leaked into PROSE. A base64
+  // blob is not prose: it is uniformly-distributed bytes over a 64-character
+  // alphabet, so given enough of them it will eventually contain the literal
+  // spelling of any short secret shape by chance alone — `1//` at ~30% per
+  // attachment (see TOKEN_LEFT_BOUNDARY), and `AIza…` at ~0.2% even after that
+  // anchor lands. Boundary-anchoring the patterns fixes the common case;
+  // exempting the field fixes the CLASS, and keeps a future pattern added to
+  // mcp-utils from silently re-breaking attachments.
+  //
+  // Deliberately narrow in three ways: it is opt-in per call, only the named
+  // key is exempt, and only a value that is ENTIRELY base64 alphabet qualifies
+  // (see OPAQUE_FIELD_VALUE) — so a field carrying real prose, which is where a
+  // real leaked token would live, still gets redacted normally.
+  opaqueFields?: readonly string[];
 }
 
 const TIMEOUT_MS = 30_000;
@@ -197,6 +247,43 @@ function sanitizedEnv(): NodeJS.ProcessEnv {
   return result;
 }
 
+// The LEFT boundary every Google token shape below is anchored on, and the
+// reason this file has a regression test named after a PNG.
+//
+// `1//` is three characters drawn entirely from the standard base64 alphabet,
+// so the unanchored pattern `1\/\/[A-Za-z0-9._-]+` matches inside ANY base64
+// blob that happens to contain that run — and then eats forward to the next
+// `+` or `/`, deleting a slab out of the middle of the payload. `gog gmail
+// attachment --inline` returns the attachment bytes as base64 in its JSON, that
+// JSON goes through `run()`, and `run()` redacts. The result was a mangled
+// `contentBase64` and an MCP protocol error at the client ("Invalid Base64
+// string") on roughly a THIRD of all attachments — measured, not estimated: a
+// 72 KiB file is ~97k base64 chars and the expected number of `1//` runs is
+// n/64³ ≈ 0.37, i.e. P(corrupt) ≈ 30%.
+//
+// That coin-flip is what made the bug look like it was about FILENAMES: it
+// correlates with nothing a reader can see, so two attachments in one thread
+// differing only in name would land on opposite sides of it. It is content, not
+// name — the runner has always spawned with an argv array and never a shell, so
+// spaces in a filename were never able to split anything.
+//
+// A real token never appears WELDED to base64 text: it is delimited by a quote,
+// whitespace, `=`, `:`, `&`, a bracket, or the start of the string. So requiring
+// a non-base64 character (or nothing) to its left keeps every genuine detection
+// and drops the mid-blob false positives, which by construction are always
+// preceded by another base64 character.
+//
+// The class is EXACTLY the standard base64 alphabet, and no wider. Every
+// character omitted from it is a delimiter a real token is found after, so each
+// one added would silently cost a detection: `=` in particular would stop
+// `refresh_token=1//0e…` and `access_token=ya29.…` — the form-encoded spelling,
+// which the shared redactor's query-param rule does not catch without a
+// preceding `?`/`&` — from being redacted at all. `=` is also unnecessary here,
+// since base64 padding is terminal and can never precede a mid-blob `1//`.
+// Likewise `.`, `_` and `-`: none occurs in standard base64, and `1//` cannot
+// occur in base64url (which has no `/`), so neither alphabet needs them.
+const TOKEN_LEFT_BOUNDARY = '(?<![A-Za-z0-9+/])';
+
 // Redact bearer/refresh-token patterns from error text before surfacing
 // it back to the MCP client. If gog ever emits a token in stderr (e.g.
 // from a verbose log mode), this prevents it from leaking to the model.
@@ -204,8 +291,8 @@ function sanitizedEnv(): NodeJS.ProcessEnv {
 // cookies, well-known key shapes (incl. Google AIza… API keys), and secret
 // query params — but not Google's OAuth2 token shapes, so those stay here.
 const GOOGLE_TOKEN_PATTERNS: RegExp[] = [
-  /ya29\.[A-Za-z0-9._\-]+/g,           // OAuth2 access tokens
-  /1\/\/[A-Za-z0-9._\-]+/g,            // OAuth2 refresh tokens
+  new RegExp(`${TOKEN_LEFT_BOUNDARY}ya29\\.[A-Za-z0-9._\\-]+`, 'g'),  // OAuth2 access tokens
+  new RegExp(`${TOKEN_LEFT_BOUNDARY}1//[A-Za-z0-9._\\-]+`, 'g'),      // OAuth2 refresh tokens
 ];
 // Strip only Google's OAuth2 token shapes. Precise enough to leave an OAuth
 // consent URL (client_id, scope names, state, code_challenge) untouched.
@@ -220,6 +307,55 @@ export function redactSecrets(text: string): string {
   return redactGoogleTokens(redactSharedSecrets(text));
 }
 
+// A JSON string value that is ENTIRELY standard/URL-safe base64 (plus padding),
+// and long enough to be a payload rather than a flag. Anything else — a path, a
+// MIME type, a sentence, an OAuth token sitting in prose — fails this and is
+// redacted normally, which is what keeps the exemption from becoming a hole.
+const OPAQUE_FIELD_VALUE = '[A-Za-z0-9+/_-]{16,}={0,2}';
+
+// Placeholder standing in for a lifted value while redaction runs.
+//
+// NUL-delimited because NUL cannot occur in gog's output: stdout is decoded as
+// UTF-8 text and JSON escapes it as a backslash-u escape, so the placeholder can never
+// collide with real content the way a printable sentinel could. The body
+// contains no character any redaction pattern keys on, and the index keeps each
+// one unique so two blobs can never be swapped on restore.
+const opaquePlaceholder = (i: number): string => `\u0000gogOpaque${i}\u0000`;
+
+/**
+ * Redact `text` while leaving the values of `fields` untouched.
+ *
+ * Lift each `"field":"<base64>"` value out to a placeholder, redact what
+ * remains, then put the values back. Splicing rather than parsing keeps this on
+ * the raw string: `run()` returns text, gog's output is not always JSON, and a
+ * parse/re-serialize round trip would rewrite key order and number formatting
+ * in output the caller may be matching on.
+ */
+export function redactPreservingOpaqueFields(
+  text: string,
+  fields: readonly string[],
+  redact: (input: string) => string,
+): string {
+  const lifted: string[] = [];
+  let staged = text;
+  for (const field of fields) {
+    // The key is escaped because it reaches a RegExp; the value class is fixed
+    // above, so a base64 payload can never terminate its own string early.
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`("${escaped}"\\s*:\\s*")(${OPAQUE_FIELD_VALUE})(")`, 'g');
+    staged = staged.replace(re, (_m, open: string, value: string, close: string) => {
+      lifted.push(value);
+      return `${open}${opaquePlaceholder(lifted.length - 1)}${close}`;
+    });
+  }
+  if (lifted.length === 0) return redact(text);
+  let redacted = redact(staged);
+  lifted.forEach((value, i) => {
+    redacted = redacted.split(opaquePlaceholder(i)).join(value);
+  });
+  return redacted;
+}
+
 // MCP desktop clients often spawn servers with a stripped PATH that excludes
 // Homebrew, user-local, and Go's default install dirs — so even when gog is
 // installed, the spawned server can't find it. Augment the child's PATH with
@@ -266,7 +402,7 @@ async function spawnWithTempFiles(
   args: GogArg[],
   opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
 ): Promise<string> {
-  const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
+  const { mkdtemp, mkdir, writeFile, rm } = await import('node:fs/promises');
   const { tmpdir } = await import('node:os');
 
   // mkdtemp creates the directory with mode 0700 (owner-only) on POSIX, so the
@@ -275,17 +411,30 @@ async function spawnWithTempFiles(
   const dir = await mkdtemp(join(tmpdir(), 'gogcli-mcp-'));
   try {
     const argv: string[] = [];
+    let seq = 0;
     for (const arg of args) {
       if (!isGogFileArg(arg)) {
         argv.push(arg);
         continue;
       }
-      // Name the file after the flag: one command can carry two payloads
-      // (e.g. --body-file and --signature-file, both .txt), and a fixed
-      // basename would have the second silently clobber the first.
-      const path = join(dir, `${arg.flag}.${arg.ext ?? 'txt'}`);
-      await writeFile(path, arg.contents, { encoding: 'utf8', mode: 0o600 });
-      argv.push(`--${arg.flag}=${path}`);
+      // Each payload gets its own numbered SUBDIRECTORY, so the basename is free
+      // to be whatever the caller needs without any risk of one payload
+      // clobbering another. That matters twice over now: `--attach` is
+      // repeatable, so a single send can carry several files whose real names
+      // are chosen by the caller and may well collide (two `chart.png`s from
+      // different folders), and an attachment's basename is what the recipient
+      // sees, so it cannot be uniquified by mangling it.
+      const sub = join(dir, String(seq));
+      seq += 1;
+      await mkdir(sub, { recursive: true, mode: 0o700 });
+      const path = join(sub, arg.filename ?? `${arg.flag}.${arg.ext ?? 'txt'}`);
+      // 'base64' decodes to the real bytes; 'utf8' writes the string as-is,
+      // which is the pre-existing behaviour for every text payload.
+      const data = arg.encoding === 'base64'
+        ? Buffer.from(arg.contents, 'base64')
+        : Buffer.from(arg.contents, 'utf8');
+      await writeFile(path, data, { mode: 0o600 });
+      argv.push(arg.positional ? path : `--${arg.flag}=${path}`);
     }
     return await spawnGog(argv, opts);
   } finally {
@@ -406,8 +555,14 @@ function assembleArgs(
 }
 
 export async function run(args: GogArg[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full' } = options;
-  const redact = redactMode === 'tokens' ? redactGoogleTokens : redactSecrets;
+  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full', opaqueFields } = options;
+  const base = redactMode === 'tokens' ? redactGoogleTokens : redactSecrets;
+  // Only OUTPUT carries opaque payloads. An error message is prose by
+  // definition, so it always takes the plain redactor — exempting a field there
+  // would be exempting exactly the text a leaked token would appear in.
+  const redact = opaqueFields?.length
+    ? (text: string): string => redactPreservingOpaqueFields(text, opaqueFields, base)
+    : base;
 
   const fullArgs = assembleArgs(args, { account, interactive, readonly });
 
@@ -433,7 +588,7 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
     // A thrown non-Error would make `.message` undefined and redact() blow up
     // with a TypeError, masking the real failure. Same instanceof guard the
     // codebase already uses in errorText() (tools/utils.ts).
-    const message = redact(err instanceof Error ? err.message : String(err));
+    const message = base(err instanceof Error ? err.message : String(err));
     // Redaction must not cost the error its TYPE. `RunnerTransportError` is the
     // structural claim "this failure was ours, not Google's"; flattening it to a
     // bare Error here would put diagnose() straight back to guessing from prose,

package/src/tools/gmail.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool, payloadArg, pageTokenParam, pageAliasParam, resolvePageToken } from './utils.js';
 import { finalizeGmailSearch, fetchGmailPages } from '../gmail-results.js';
 import type { GogArg } from '../runner.js';
+import { attachInlineParam, inlineAttachmentArgs } from '../attachments.js';
 
 export function registerGmailTools(server: McpServer): void {
   server.registerTool('gog_gmail_search', {
@@ -66,7 +67,13 @@ export function registerGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_send', {
-    description: 'Send an email. When attach is used, the JSON result echoes the attached filenames and byte sizes — check it to confirm the files were found and embedded.',
+    description:
+      'Send an email. Two ways to attach a file: `attach` takes paths READ ON THE GOG SERVER, and '
+      + '`attachInline` takes the bytes themselves. Use attachInline unless you know the file exists on '
+      + 'the same machine gog runs on — on the hosted connector and any remote deployment there is no '
+      + 'shared filesystem, so no path you can name resolves there and `attach` will fail with '
+      + '"no such file or directory". When either is used, the JSON result echoes the attached filenames '
+      + 'and byte sizes — check it to confirm the files were embedded.',
     annotations: { destructiveHint: true },
     inputSchema: {
       to: z.string().describe('Recipient(s), comma-separated'),
@@ -76,10 +83,11 @@ export function registerGmailTools(server: McpServer): void {
       bcc: z.string().optional().describe('BCC recipients, comma-separated'),
       replyToMessageId: z.string().optional().describe('Message ID to reply to'),
       threadId: z.string().optional().describe('Thread ID to reply within'),
-      attach: z.array(z.string()).optional().describe('Local file paths to attach (repeatable). Each file is read on the gog server (not this client), base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment. Keep the total under Gmail\'s ~35 MB inline-upload limit.'),
+      attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on the hosted connector or any GOG_RUNNER_URL backend these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Each file is read on the server, base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment.'),
+      attachInline: attachInlineParam,
       account: accountParam,
     },
-  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, attach, account }) => {
+  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, attach, attachInline, account }) => {
     // A long body cannot ride in argv: the hosted runner caps a single arg and
     // Linux caps MAX_ARG_STRLEN at 128 KiB. payloadArg swaps it for --body-file
     // past the shared threshold; the executor materializes the temp file.
@@ -89,6 +97,12 @@ export function registerGmailTools(server: McpServer): void {
     if (replyToMessageId) args.push(`--reply-to-message-id=${replyToMessageId}`);
     if (threadId) args.push(`--thread-id=${threadId}`);
     if (attach) for (const path of attach) args.push(`--attach=${path}`);
+    // Same repeatable --attach flag; the executor materializes each payload to a
+    // temp file beside gog and substitutes its path. `args` is passed so the
+    // size check sees the whole request — chiefly the body, which is itself a
+    // file arg once it passes payloadArg's threshold and spends the same budget.
+    const inline = inlineAttachmentArgs('attach', attachInline, args);
+    args.push(...inline);
     return runOrDiagnose(args, { account });
   });
 

package/src/worker.ts

@@ -38,7 +38,7 @@ import { gogAuth, CONNECTOR_INSTRUCTIONS, type GogProps } from './connector-auth
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.24.0'; // x-release-please-version
+const VERSION = '2.25.0'; // x-release-please-version
 
 // Build an McpAgent subclass whose init() registers `registrars` onto its server,
 // each handler wrapped in the ALS scope carrying the per-session Fly executor.