gogcli-mcp 2.23.2 → 2.25.0

package/src/tools/auth.ts

@@ -13,6 +13,20 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     `Default: "${defaultServices}". Prefer the narrowest set you need — requesting a service whose ` +
     `Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request ` +
     `with invalid_scope.`;
+  // Additional raw OAuth scope URIs, appended after the service scopes gog
+  // derives from `services`. This exists for scopes no service selection can
+  // ask for: notably bigquery.readonly, which Google demands whenever a Sheets
+  // response CONTAINS BigQuery Connected Sheets data (gog_sheets_datasource_*)
+  // and which ordinary `sheets` authorization deliberately does not request.
+  // Same invalid_scope caveat as `services`: Google rejects the WHOLE request
+  // if the scope's API is not enabled on the OAuth client's project, and that
+  // happens in the user's browser, so this wrapper cannot catch it.
+  const extraScopesDescribe =
+    'Additional raw OAuth scope URIs to request, comma-separated, on top of the ones `services` implies. ' +
+    'Use for scopes no service covers — e.g. https://www.googleapis.com/auth/bigquery.readonly, required ' +
+    'before gog_sheets_datasource_* can read BigQuery-backed Connected Sheets. Leave unset otherwise: an ' +
+    'extra scope whose API is not enabled on the OAuth client project makes Google reject the WHOLE ' +
+    'authorization with invalid_scope.';
   server.registerTool('gog_auth_list', {
     description:
       'List the Google accounts stored in gogcli, with their scopes. This reads local ' +
@@ -91,10 +105,19 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     inputSchema: {
       email: z.string().describe('Google account email to authorize'),
       services: z.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: z.string().optional().describe(extraScopesDescribe),
     },
-  }, async ({ email, services = defaultServices }) => {
+  }, async ({ email, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(['auth', 'add', email, '--services', services], {
+      const args = ['auth', 'add', email, '--services', services];
+      // --force-consent rides along with extraScopes and only with them. Google
+      // re-prompts for a NEW scope only when consent is forced; without it the
+      // account can come back still missing the scope, with a success message —
+      // the exact shape of failure the caller cannot see. The other two tools
+      // force consent unconditionally; this one does not, so it must be added
+      // here rather than assumed.
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`, '--force-consent');
+      return rawTextResult(await run(args, {
         interactive: true,
         timeout: 300_000,
       }));
@@ -115,17 +138,17 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     inputSchema: {
       email: z.string().describe('Google account email to authorize'),
       services: z.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: z.string().optional().describe(`${extraScopesDescribe} Pass the SAME value to gog_auth_add_complete.`),
     },
-  }, async ({ email, services = defaultServices }) => {
+  }, async ({ email, services = defaultServices, extraScopes }) => {
     try {
       // --force-consent guarantees a refresh token even if a prior grant exists
       // (the whole point when recovering from a dead one). redactMode 'tokens'
       // keeps the consent URL's scope names intact (the shared redactor mangles
       // them) while still stripping any real token — a step-1 URL carries none.
-      return rawTextResult(await run(
-        ['auth', 'add', email, '--remote', '--step', '1', '--services', services, '--force-consent'],
-        { redactMode: 'tokens' },
-      ));
+      const args = ['auth', 'add', email, '--remote', '--step', '1', '--services', services, '--force-consent'];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args, { redactMode: 'tokens' }));
     } catch (err) {
       return errorResult(errorText(err));
     }
@@ -147,13 +170,17 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
       services: z.string().optional().default(defaultServices).describe(
         `Services authorized — MUST match the value passed to gog_auth_add_url. Default: "${defaultServices}".`,
       ),
+      extraScopes: z.string().optional().describe(
+        'Extra OAuth scope URIs — MUST match the value passed to gog_auth_add_url, for the same reason `services` must: ' +
+        'the two steps have to describe the same grant.',
+      ),
     },
-  }, async ({ email, redirectUrl, services = defaultServices }) => {
+  }, async ({ email, redirectUrl, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        ['auth', 'add', email, '--remote', '--step', '2', '--auth-url', redirectUrl,
-          '--services', services, '--force-consent'],
-      ));
+      const args = ['auth', 'add', email, '--remote', '--step', '2', '--auth-url', redirectUrl,
+        '--services', services, '--force-consent'];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args));
     } catch (err) {
       return errorResult(errorText(err));
     }

package/src/tools/calendar.ts

@@ -5,15 +5,22 @@ import { annotateTruncatedList } from '../pagination.js';
 
 export function registerCalendarTools(server: McpServer): void {
   server.registerTool('gog_calendar_events', {
-    description: 'List calendar events. Filters can be combined (e.g. --from + --to for a range, or --today for just today). '
+    description: 'List calendar events. Describe the window ONE way and one way only (gog >= 0.36.0 rejects the rest as ambiguous rather than silently discarding a flag): '
+      + 'today on its own; or from + to; or from + days; or days on its own (a window of that many days starting today). today cannot be combined with from, to or days, and days cannot be combined with to. '
       + 'gog returns only 10 events by default, so a wide date range is USUALLY INCOMPLETE: raise max, or page with pageToken until the response carries no nextPageToken. '
       + 'A response carrying "truncated": true is an incomplete view — never conclude an event does not exist from one.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       calendarId: z.string().optional().describe('Calendar ID (default: primary calendar)'),
       from: z.string().optional().describe('Start time filter (RFC3339, date, or natural language)'),
-      to: z.string().optional().describe('End time filter (RFC3339, date, or natural language)'),
-      today: z.boolean().optional().describe('Only show today\'s events'),
+      to: z.string().optional().describe('End time filter (RFC3339, date, or natural language). Mutually exclusive with today and with days.'),
+      // gog >= 0.36.0 (openclaw/gogcli#981). Before that release --days sat in
+      // a switch arm evaluated ahead of --from, so `--from 2026-09-25 --days 5`
+      // silently threw --from away and answered for today instead — at exit 0,
+      // in a well-formed table. It is only exposed here now that it means what
+      // it says.
+      days: z.number().int().positive().optional().describe('Window LENGTH in days (calendar days, DST-aware), measured from `from` when one is given and from today otherwise. Use from + days for "the week of the 25th"; days alone for "the next N days". Mutually exclusive with to and with today.'),
+      today: z.boolean().optional().describe('Only show today\'s events. A complete window on its own — mutually exclusive with from, to and days.'),
       query: z.string().optional().describe('Free text search within events'),
       max: z.number().int().optional().describe('Max events to return. gog defaults to 10, which silently hides the rest — raise it, or page with pageToken.'),
       pageToken: pageTokenParam,
@@ -23,11 +30,12 @@ export function registerCalendarTools(server: McpServer): void {
       timezone: z.string().optional().describe('Display timezone for event times (IANA name, e.g. America/New_York, or "local" for the system timezone). Default: each event\'s timezone, then its calendar\'s timezone.'),
       account: accountParam,
     },
-  }, async ({ calendarId, from, to, today, query, max, pageToken, page, all, eventTypes, timezone, account }) => {
+  }, async ({ calendarId, from, to, days, today, query, max, pageToken, page, all, eventTypes, timezone, account }) => {
     const args = ['calendar', 'events'];
     if (calendarId) args.push(calendarId);
     if (from) args.push(`--from=${from}`);
     if (to) args.push(`--to=${to}`);
+    if (days !== undefined) args.push(`--days=${days}`);
     if (today) args.push('--today');
     if (query) args.push(`--query=${query}`);
     if (max !== undefined) args.push(`--max=${max}`);

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', {
@@ -46,21 +47,33 @@ export function registerGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_get', {
-    description: 'Get a Gmail message by ID.',
+    description: 'Get a Gmail message by ID. For a long message, sanitizeContent is the cheapest way to keep it in context: it drops the raw MIME payload and the HTML part, which are usually the bulk of the response.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       messageId: z.string().describe('Message ID'),
       format: z.enum(['full', 'metadata', 'raw']).optional().describe('Message format (default: full)'),
+      // Requires gog >= 0.37.0. Before that (openclaw/gogcli#992) the JSON
+      // carried the headers and body TWICE — once inside `message`, once
+      // copied to the top level — so the flag meant to shrink the payload
+      // enlarged it. MIN_GOG_VERSION is the guard; there is no runtime check.
+      sanitizeContent: z.boolean().optional().describe('Return agent-oriented sanitized content: HTML stripped, HTTP(S) URLs removed, raw Gmail payloads omitted from the JSON. The largest payload-size reduction available here. Note the URL removal is lossy — omit this when you need to follow a link out of the message.'),
       account: accountParam,
     },
-  }, async ({ messageId, format, account }) => {
+  }, async ({ messageId, format, sanitizeContent, account }) => {
     const args = ['gmail', 'get', messageId];
     if (format) args.push(`--format=${format}`);
+    if (sanitizeContent) args.push('--sanitize-content');
     return runOrDiagnose(args, { account });
   });
 
   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'),
@@ -70,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.
@@ -83,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.23.2'; // 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.

package/tests/attachments.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect } from 'vitest';
+import {
+  inlineFileArg,
+  inlineAttachmentArgs,
+  inlineAttachmentSchema,
+  MAX_INLINE_ATTACHMENT_BYTES,
+  MAX_INLINE_ATTACHMENT_TOTAL_BYTES,
+  MAX_REQUEST_PAYLOAD_WIRE_BYTES,
+  INLINE_ATTACHMENT_LIMITS_TEXT,
+} from '../src/attachments.js';
+import type { GogFileArg } from '../src/runner.js';
+
+const b64 = (s: string): string => Buffer.from(s, 'utf8').toString('base64');
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+describe('inlineFileArg', () => {
+  it('turns bytes into a base64 GogFileArg carrying the caller filename', () => {
+    const { arg, bytes } = inlineFileArg('attach', {
+      filename: 'pendant-layouts.png',
+      contentBase64: PNG.toString('base64'),
+    });
+    expect(arg).toEqual<GogFileArg>({
+      kind: 'file',
+      flag: 'attach',
+      contents: PNG.toString('base64'),
+      encoding: 'base64',
+      filename: 'pendant-layouts.png',
+    });
+    expect(bytes).toBe(PNG.length);
+  });
+
+  it('marks a positional arg so the path is emitted bare, not as --flag=path', () => {
+    const { arg } = inlineFileArg('localPath', { filename: 'notes.md', contentBase64: b64('hi') }, { positional: true });
+    expect(arg.positional).toBe(true);
+  });
+
+  it('leaves positional unset by default, preserving the --flag=path shape', () => {
+    const { arg } = inlineFileArg('attach', { filename: 'a.txt', contentBase64: b64('hi') });
+    expect(arg.positional).toBeUndefined();
+  });
+
+  // Filenames with spaces and non-ASCII characters are the shapes the original
+  // report blamed for the inline-delivery failure. They must pass through here
+  // completely untouched — the name is what the recipient sees.
+  it.each([
+    'Screenshot 2026-06-13 152500.png',
+    'Reçu — étude, final (v2).pdf',
+    'ファイル 名前.png',
+    "quote'and\"double.txt",
+  ])('accepts %j verbatim', (filename) => {
+    const { arg } = inlineFileArg('attach', { filename, contentBase64: b64('x') });
+    expect(arg.filename).toBe(filename);
+  });
+
+  it('rejects a filename that is a path rather than a bare name', () => {
+    expect(() => inlineFileArg('attach', { filename: '../../etc/passwd', contentBase64: b64('x') }))
+      .toThrow(/must be a bare filename, not a path/);
+    expect(() => inlineFileArg('attach', { filename: 'dir\\file.txt', contentBase64: b64('x') }))
+      .toThrow(/must be a bare filename, not a path/);
+  });
+
+  it('rejects a traversal, a control character, and an over-long name', () => {
+    expect(() => inlineFileArg('attach', { filename: '..', contentBase64: b64('x') })).toThrow(/not a usable filename/);
+    expect(() => inlineFileArg('attach', { filename: 'a\u0000b.txt', contentBase64: b64('x') })).toThrow(/not a usable filename/);
+    expect(() => inlineFileArg('attach', { filename: `${'n'.repeat(201)}.txt`, contentBase64: b64('x') })).toThrow(/not a usable filename/);
+  });
+
+  it('rejects content that is not valid base64 instead of writing a corrupt file', () => {
+    // Buffer.from is lenient and would silently DROP the bad characters, mailing
+    // out a truncated file. The round-trip check is what turns that into an error.
+    expect(() => inlineFileArg('attach', { filename: 'a.png', contentBase64: 'not!valid!base64!' }))
+      .toThrow(/not valid base64/);
+  });
+
+  it('names the offending file and the limit when one file is too large', () => {
+    const tooBig = Buffer.alloc(MAX_INLINE_ATTACHMENT_BYTES + 1).toString('base64');
+    expect(() => inlineFileArg('attach', { filename: 'huge.bin', contentBase64: tooBig }))
+      .toThrow(/huge\.bin[\s\S]*exceeds the \d+-byte \(8 MiB\) per-file limit/);
+  });
+
+  it('accepts a file exactly at the ceiling', () => {
+    const exact = Buffer.alloc(MAX_INLINE_ATTACHMENT_BYTES).toString('base64');
+    expect(() => inlineFileArg('attach', { filename: 'exact.bin', contentBase64: exact })).not.toThrow();
+  });
+
+  it('uses a caller-supplied label in the error, for tools whose param is not attachInline', () => {
+    expect(() => inlineFileArg('localPath', { filename: 'a.png', contentBase64: '!!!' }, { where: 'content' }))
+      .toThrow(/^content: contents are not valid base64/);
+  });
+});
+
+describe('inlineAttachmentArgs', () => {
+  it('returns nothing for undefined or an empty list, so nothing is appended', () => {
+    expect(inlineAttachmentArgs('attach', undefined)).toEqual([]);
+    expect(inlineAttachmentArgs('attach', [])).toEqual([]);
+  });
+
+  it('produces one repeatable arg per attachment, in order', () => {
+    const args = inlineAttachmentArgs('attach', [
+      { filename: 'a.png', contentBase64: b64('aaa') },
+      { filename: 'b.pdf', contentBase64: b64('bbb') },
+    ]);
+    expect(args).toHaveLength(2);
+    expect(args.map((a) => (a as GogFileArg).filename)).toEqual(['a.png', 'b.pdf']);
+    expect(args.every((a) => (a as GogFileArg).flag === 'attach')).toBe(true);
+  });
+
+  it('allows two attachments with the SAME name (each gets its own temp dir)', () => {
+    const args = inlineAttachmentArgs('attach', [
+      { filename: 'chart.png', contentBase64: b64('first') },
+      { filename: 'chart.png', contentBase64: b64('second') },
+    ]);
+    expect(args).toHaveLength(2);
+    expect((args[0] as GogFileArg).contents).not.toBe((args[1] as GogFileArg).contents);
+  });
+
+  it('enforces a per-message total on top of the per-file ceiling', () => {
+    // Each file is individually legal; together they are not.
+    const chunk = Buffer.alloc(MAX_INLINE_ATTACHMENT_BYTES).toString('base64');
+    const four = Array.from({ length: 4 }, (_, i) => ({ filename: `f${i}.bin`, contentBase64: chunk }));
+    expect(() => inlineAttachmentArgs('attach', four))
+      .toThrow(/This message is too large to send/);
+  });
+
+  // The budget belongs to the REQUEST, not to the attachments. `payloadArg`
+  // turns any body over 4 KiB into a GogFileArg that rides in the same JSON
+  // body at ~1:1, so a near-max attachment set plus a multi-MiB body overruns
+  // the runner even though each input is inside its own documented limit. That
+  // is the same invisible-transport-rejection failure the ceiling exists to
+  // prevent, so the sibling args are measured rather than assumed small.
+  it('counts the message body against the same budget as the attachments', () => {
+    // Three files just under the 8 MiB per-file cap, summing to just under the
+    // per-message total — i.e. every input inside its own documented limit.
+    const each = Buffer.alloc(Math.floor((MAX_INLINE_ATTACHMENT_TOTAL_BYTES - 4096) / 3)).toString('base64');
+    const attachments = Array.from({ length: 3 }, (_, i) => ({ filename: `big${i}.bin`, contentBase64: each }));
+
+    // Alone: fits.
+    expect(() => inlineAttachmentArgs('attach', attachments)).not.toThrow();
+
+    // With a 2 MiB HTML body — itself well under the 8 MiB per-file cap — it
+    // does not, and the error says the body is implicated.
+    const body: GogFileArg = { kind: 'file', flag: 'body-html-file', contents: 'x'.repeat(2 * 1024 * 1024) };
+    expect(() => inlineAttachmentArgs('attach', attachments, ['gmail', 'send', body]))
+      .toThrow(/would fit on their own; the rest of the message \(its body, mostly\) spends \d+ bytes/);
+  });
+
+  it('blames the files, not the body, when the attachments alone overrun', () => {
+    const chunk = Buffer.alloc(MAX_INLINE_ATTACHMENT_BYTES).toString('base64');
+    const four = Array.from({ length: 4 }, (_, i) => ({ filename: `f${i}.bin`, contentBase64: chunk }));
+    expect(() => inlineAttachmentArgs('attach', four, ['gmail', 'send'])).toThrow(/too large to send/);
+    expect(() => inlineAttachmentArgs('attach', four, ['gmail', 'send'])).not.toThrow(/would fit on their own/);
+  });
+
+  it('measures a base64 sibling at its wire length, not its decoded length', () => {
+    // A sibling that is itself binary costs its base64 spelling, which is what
+    // actually travels — counting decoded bytes would under-report by 25%.
+    const sibling: GogFileArg = {
+      kind: 'file',
+      flag: 'attach',
+      contents: Buffer.alloc(MAX_INLINE_ATTACHMENT_BYTES).toString('base64'),
+      encoding: 'base64',
+      filename: 'already-counted.bin',
+    };
+    const each = Buffer.alloc(Math.floor((MAX_INLINE_ATTACHMENT_TOTAL_BYTES - 4096) / 3)).toString('base64');
+    const attachments = Array.from({ length: 3 }, (_, i) => ({ filename: `f${i}.bin`, contentBase64: each }));
+    expect(() => inlineAttachmentArgs('attach', attachments, ['gmail', 'send', sibling]))
+      .toThrow(/too large to send/);
+  });
+
+  it('ignores small sibling args, which the JSON reserve already covers', () => {
+    const chunk = Buffer.alloc(Math.floor(MAX_INLINE_ATTACHMENT_TOTAL_BYTES / 4)).toString('base64');
+    const two = Array.from({ length: 2 }, (_, i) => ({ filename: `f${i}.bin`, contentBase64: chunk }));
+    const flags = ['gmail', 'send', '--to=a@b.com', '--subject=Hi', '--body=short'];
+    expect(() => inlineAttachmentArgs('attach', two, flags)).not.toThrow();
+  });
+
+  // THE INVARIANT behind the per-message ceiling, asserted rather than trusted.
+  //
+  // connector-runtime sends every payload base64-encoded inside ONE JSON body,
+  // and the Fly runner caps that body at MAX_BODY_BYTES. Base64 inflates by 4/3,
+  // so a ceiling expressed in decoded bytes has to be derived from the wire cap
+  // or it documents a size that gets rejected as "request body too large" — a
+  // transport rejection from a layer the caller cannot see, which is the exact
+  // failure the tool-layer check exists to prevent. A 25 MiB total encoded to
+  // 34,952,536 chars against a 33,554,432 cap, so the limit was unreachable.
+  it('keeps a full message under the Fly runner request-body cap once base64-inflated', () => {
+    const RUNNER_MAX_BODY_BYTES = 32 * 1024 * 1024; // fly-gog-runner/server.mjs
+    const encodedLength = (decoded: number): number => 4 * Math.ceil(decoded / 3);
+
+    // The payload budget must leave the JSON structure room inside the cap…
+    expect(MAX_REQUEST_PAYLOAD_WIRE_BYTES).toBeLessThan(RUNNER_MAX_BODY_BYTES);
+    expect(RUNNER_MAX_BODY_BYTES - MAX_REQUEST_PAYLOAD_WIRE_BYTES).toBeGreaterThanOrEqual(128 * 1024);
+    // …and a full attachment set must fit inside that budget once inflated.
+    expect(encodedLength(MAX_INLINE_ATTACHMENT_TOTAL_BYTES)).toBeLessThanOrEqual(MAX_REQUEST_PAYLOAD_WIRE_BYTES);
+    // The advertised number must itself be sendable — floor, not round.
+    const advertised = Number(/(\d+) MiB in total/.exec(INLINE_ATTACHMENT_LIMITS_TEXT)![1]) * 1024 * 1024;
+    expect(advertised).toBeLessThanOrEqual(MAX_INLINE_ATTACHMENT_TOTAL_BYTES);
+  });
+
+  it('reports the ceilings it actually enforces', () => {
+    expect(MAX_INLINE_ATTACHMENT_BYTES).toBe(8 * 1024 * 1024);
+    expect(MAX_REQUEST_PAYLOAD_WIRE_BYTES).toBe(32 * 1024 * 1024 - 256 * 1024);
+    expect(MAX_INLINE_ATTACHMENT_TOTAL_BYTES).toBe(24_969_216); // wire budget × 3/4
+    // The documented text is derived from the constants, so it cannot drift.
+    expect(INLINE_ATTACHMENT_LIMITS_TEXT).toBe('up to 8 MiB per file and 23 MiB in total');
+  });
+
+  it('accepts a message at the advertised total', () => {
+    // 23 MiB across three files — the number the tool description publishes.
+    const chunk = Buffer.alloc(Math.floor((23 * 1024 * 1024) / 3)).toString('base64');
+    const three = Array.from({ length: 3 }, (_, i) => ({ filename: `f${i}.bin`, contentBase64: chunk }));
+    expect(() => inlineAttachmentArgs('attach', three)).not.toThrow();
+  });
+});
+
+describe('inlineAttachmentSchema', () => {
+  it('requires both filename and contentBase64', () => {
+    expect(inlineAttachmentSchema.safeParse({ filename: 'a.png' }).success).toBe(false);
+    expect(inlineAttachmentSchema.safeParse({ contentBase64: b64('x') }).success).toBe(false);
+    expect(inlineAttachmentSchema.safeParse({ filename: 'a.png', contentBase64: b64('x') }).success).toBe(true);
+  });
+
+  it('rejects empty strings, which would produce a nameless or empty attachment', () => {
+    expect(inlineAttachmentSchema.safeParse({ filename: '', contentBase64: b64('x') }).success).toBe(false);
+    expect(inlineAttachmentSchema.safeParse({ filename: 'a.png', contentBase64: '' }).success).toBe(false);
+  });
+});

package/tests/runner-file-args-failure.test.ts

@@ -8,11 +8,13 @@ import type { Spawner } from '../src/runner.js';
 // its own file because the mock would defeat the byte-level round-trip
 // assertions in runner-file-args.test.ts.
 const mkdtemp = vi.fn(async () => '/tmp/gogcli-mcp-fake');
+const mkdir = vi.fn(async () => undefined);
 const writeFile = vi.fn(async () => {});
 const rm = vi.fn(async () => {});
 
 vi.mock('node:fs/promises', () => ({
   mkdtemp: (...args: unknown[]) => mkdtemp(...(args as [])),
+  mkdir: (...args: unknown[]) => mkdir(...(args as [])),
   writeFile: (...args: unknown[]) => writeFile(...(args as [])),
   rm: (...args: unknown[]) => rm(...(args as [])),
 }));
@@ -36,9 +38,11 @@ const fileArg = { kind: 'file', flag: 'body-file', contents: 'payload' } as cons
 describe('temp-file materialization failures', () => {
   beforeEach(() => {
     mkdtemp.mockClear();
+    mkdir.mockClear();
     writeFile.mockClear();
     rm.mockClear();
     rm.mockImplementation(async () => {});
+    mkdir.mockImplementation(async () => undefined);
     writeFile.mockImplementation(async () => {});
   });
 
@@ -83,12 +87,53 @@ describe('temp-file materialization failures', () => {
     await expect(run(['gmail', 'send', fileArg], { spawner })).rejects.toThrow('gog: invalid draft');
   });
 
-  it('writes the payload with mode 0600 and utf8 encoding', async () => {
+  it('writes the payload as owner-only utf8 bytes', async () => {
     await run(['gmail', 'send', fileArg], { spawner: okSpawner() });
     expect(writeFile).toHaveBeenCalledWith(
       expect.stringContaining('body-file.txt'),
-      'payload',
-      { encoding: 'utf8', mode: 0o600 },
+      Buffer.from('payload', 'utf8'),
+      { mode: 0o600 },
     );
+    // Each payload lands in its own numbered subdirectory of the temp dir, so a
+    // caller-chosen basename can never clobber another payload's.
+    expect(mkdir).toHaveBeenCalledWith('/tmp/gogcli-mcp-fake/0', { recursive: true, mode: 0o700 });
+  });
+
+  it('decodes a base64 payload to real bytes and honours a caller filename', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    await run([
+      'gmail', 'send',
+      { kind: 'file', flag: 'attach', contents: png.toString('base64'), encoding: 'base64', filename: 'Screenshot 2026-06-13 152500.png' },
+    ], { spawner: okSpawner() });
+    expect(writeFile).toHaveBeenCalledWith(
+      '/tmp/gogcli-mcp-fake/0/Screenshot 2026-06-13 152500.png',
+      png,
+      { mode: 0o600 },
+    );
+  });
+
+  it('gives each file arg its own subdirectory so identical basenames survive', async () => {
+    const spawner = okSpawner();
+    await run([
+      'gmail', 'send',
+      { kind: 'file', flag: 'attach', contents: 'YQ==', encoding: 'base64', filename: 'chart.png' },
+      { kind: 'file', flag: 'attach', contents: 'Yg==', encoding: 'base64', filename: 'chart.png' },
+    ], { spawner });
+    const written = writeFile.mock.calls.map((c) => c[0]);
+    expect(written).toEqual(['/tmp/gogcli-mcp-fake/0/chart.png', '/tmp/gogcli-mcp-fake/1/chart.png']);
+    // Both survive as distinct --attach values rather than one clobbering the other.
+    const argv = (spawner as unknown as { mock: { calls: [string, string[]][] } }).mock.calls[0][1];
+    expect(argv.filter((a) => a.startsWith('--attach='))).toHaveLength(2);
+  });
+
+  it('emits a positional file arg as a bare path, not --flag=path', async () => {
+    const spawner = okSpawner();
+    await run([
+      'drive', 'upload',
+      { kind: 'file', flag: 'localPath', contents: 'YQ==', encoding: 'base64', filename: 'notes.md', positional: true },
+    ], { spawner });
+    const argv = (spawner as unknown as { mock: { calls: [string, string[]][] } }).mock.calls[0][1];
+    expect(argv).toContain('/tmp/gogcli-mcp-fake/0/notes.md');
+    expect(argv.some((a) => a.startsWith('--localPath='))).toBe(false);
   });
 });