gogcli-mcp 2.24.0 → 2.26.0

package/src/tools/chat.ts

@@ -0,0 +1,253 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import {
+  accountParam,
+  runOrDiagnose,
+  registerRunTool,
+  paginationParams,
+  pushPaginationFlags,
+} from './utils.js';
+import type { GogArg } from '../runner.js';
+import { attachInlineParam, inlineAttachmentArgs } from '../attachments.js';
+
+// Google Chat (gog >= 0.38.0 for the mention/reaction metadata in
+// `messages list`; the rest of the surface is older).
+//
+// TWO NAMING SYSTEMS MEET HERE, and mixing them is the mistake this module's
+// descriptions exist to prevent. Chat identifies everything by RESOURCE NAME —
+// `spaces/AAAA`, `spaces/AAAA/messages/BBBB`, `spaces/AAAA/threads/CCCC` — and
+// those names are what every tool below wants. A bare ID (`BBBB`) is accepted
+// for a message only when `space` says which space it lives in, which is why
+// the reaction tools carry that extra parameter.
+//
+// gog_chat_spaces_find / gog_chat_dm_space are the bridges from human words
+// ("the launch room", "alice@example.com") to those names; reach for one of
+// them first rather than guessing a resource name.
+//
+// WORKSPACE-ONLY, AND THAT IS NOT A SCOPE PROBLEM: gog refuses every chat call
+// on a consumer @gmail.com account with "chat requires a Google Workspace
+// account (non-gmail.com)" — verified live against gog 0.38.0 — no matter which
+// scopes the token carries. Re-authorizing cannot fix it, so the note below is
+// appended to every description here: a model that reads "permission error" as
+// "missing scope" would otherwise burn a re-auth round trip on an account that
+// can never work.
+export function registerChatTools(server: McpServer): void {
+  const workspaceOnlyNote =
+    ' WORKSPACE ONLY: Google Chat has no API for consumer accounts, so this fails on an @gmail.com '
+    + 'account with "chat requires a Google Workspace account". That is the ACCOUNT, not the token — '
+    + 're-authorizing or adding scopes will not help.';
+  const spaceParam = z.string().describe(
+    'Space resource name, e.g. "spaces/AAAAsomeID" (from gog_chat_spaces_list, gog_chat_spaces_find or gog_chat_dm_space)',
+  );
+  const threadParam = z.string().optional().describe(
+    'Thread resource name, e.g. "spaces/AAAA/threads/CCCC" — reply inside that thread instead of starting a new one',
+  );
+
+  server.registerTool('gog_chat_spaces_list', {
+    description:
+      'List the Google Chat spaces the account belongs to — named rooms and DMs alike — with their resource names. '
+      + 'Start here when you do not yet have a space name; gog_chat_spaces_find is faster when you know the room\'s title.'
+      + workspaceOnlyNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      ...paginationParams,
+      account: accountParam,
+    },
+  }, async ({ max, pageToken, page, all, account }) => {
+    const args = ['chat', 'spaces', 'list'];
+    pushPaginationFlags(args, { max, pageToken, page, all });
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_spaces_find', {
+    description:
+      'Find spaces whose display name matches. Substring and case-insensitive by default, which is what you want when the '
+      + 'user names a room approximately ("the launch room"); pass exact=true to require the whole title. DMs have no '
+      + 'display name — use gog_chat_dm_space to reach a person.' + workspaceOnlyNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      displayName: z.string().describe('Space display name, or part of one'),
+      exact: z.boolean().optional().describe('Require an exact (still case-insensitive) match on the whole display name'),
+      max: z.number().int().optional().describe('Max results per page'),
+      account: accountParam,
+    },
+  }, async ({ displayName, exact, max, account }) => {
+    const args = ['chat', 'spaces', 'find', displayName];
+    if (exact) args.push('--exact');
+    if (max !== undefined) args.push(`--max=${max}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_spaces_create', {
+    description:
+      'Create a named Chat space, optionally seeding its membership. Members are added immediately and are notified — this '
+      + 'is visible to other people the moment it runs, so confirm the member list before calling it.' + workspaceOnlyNote,
+    inputSchema: {
+      displayName: z.string().describe('Display name for the new space'),
+      members: z.array(z.string()).optional().describe('Initial members, as email addresses or "users/..." resource names'),
+      account: accountParam,
+    },
+  }, async ({ displayName, members, account }) => {
+    const args = ['chat', 'spaces', 'create', displayName];
+    if (members) for (const member of members) args.push(`--member=${member}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_threads_list', {
+    description:
+      'List the threads in a space, so a reply can be targeted at an existing conversation rather than starting a new one. '
+      + 'Pass a thread name from here as `thread` to gog_chat_messages_send.' + workspaceOnlyNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      space: spaceParam,
+      ...paginationParams,
+      account: accountParam,
+    },
+  }, async ({ space, max, pageToken, page, all, account }) => {
+    const args = ['chat', 'threads', 'list', space];
+    pushPaginationFlags(args, { max, pageToken, page, all });
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_messages_list', {
+    description:
+      'Read messages in a space. The JSON carries each message\'s @-mentions and a summary of its emoji reactions '
+      + '(gog >= 0.38.0) alongside the text, so "who was tagged" and "did anyone react" are answerable without extra calls. '
+      + 'unread=true returns only what arrived after the account last read the space — the cheap way to answer "what did I '
+      + 'miss". Newest-first needs an explicit order="createTime desc"; Chat\'s own default is oldest-first.'
+      + workspaceOnlyNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      space: spaceParam,
+      thread: threadParam,
+      unread: z.boolean().optional().describe('Only messages posted after the account last read this space'),
+      order: z.enum(['createTime asc', 'createTime desc', 'lastUpdateTime asc', 'lastUpdateTime desc'])
+        .optional().describe('Sort order (Chat default: "createTime asc", i.e. OLDEST first — ask for "createTime desc" when you want the latest messages)'),
+      ...paginationParams,
+      account: accountParam,
+    },
+  }, async ({ space, thread, unread, order, max, pageToken, page, all, account }) => {
+    const args = ['chat', 'messages', 'list', space];
+    if (thread) args.push(`--thread=${thread}`);
+    if (unread) args.push('--unread');
+    if (order) args.push(`--order=${order}`);
+    pushPaginationFlags(args, { max, pageToken, page, all });
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_messages_send', {
+    description:
+      'Post a message to a Chat space. THIS IS IMMEDIATELY VISIBLE TO EVERYONE IN THE SPACE and cannot be unsent through '
+      + 'this tool, so treat it like sending mail, not like saving a draft. Pass `thread` to reply inside an existing '
+      + 'conversation (from gog_chat_threads_list or a message\'s thread field); omit it to start a new one. Text supports '
+      + 'Chat\'s markdown-ish formatting (*bold*, _italic_, `code`).' + workspaceOnlyNote,
+    inputSchema: {
+      space: spaceParam,
+      text: z.string().optional().describe('Message text. Optional only when an attachment is supplied.'),
+      thread: threadParam,
+      attach: z.array(z.string()).optional().describe(
+        'Attachment file paths, read WHERE GOG RUNS. On a hosted or remote deployment that is not your machine — use '
+        + 'attachInline there instead.',
+      ),
+      attachInline: attachInlineParam,
+      account: accountParam,
+    },
+  }, async ({ space, text, thread, attach, attachInline, account }) => {
+    if (text === undefined && !attach?.length && !attachInline?.length) {
+      throw new Error('A Chat message needs text, an attachment, or both.');
+    }
+    const args: GogArg[] = ['chat', 'messages', 'send', space];
+    if (text !== undefined) args.push(`--text=${text}`);
+    if (thread) args.push(`--thread=${thread}`);
+    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. `args` is passed so the size check sees the whole
+    // request, not just the attachments.
+    args.push(...inlineAttachmentArgs('attach', attachInline, args));
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_dm_send', {
+    description:
+      'Send a direct message to one person by email address, creating the DM space if this is the first message. Delivered '
+      + 'immediately and cannot be unsent through this tool. For a room rather than a person, use gog_chat_messages_send.'
+      + workspaceOnlyNote,
+    inputSchema: {
+      email: z.string().describe('Recipient email address'),
+      text: z.string().describe('Message text'),
+      thread: threadParam,
+      account: accountParam,
+    },
+  }, async ({ email, text, thread, account }) => {
+    const args = ['chat', 'dm', 'send', email, `--text=${text}`];
+    if (thread) args.push(`--thread=${thread}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_dm_space', {
+    description:
+      'Resolve the DM space for an email address — the bridge from a person to the "spaces/..." name the message tools '
+      + 'want. Creates the space if none exists yet, which is silent: it does not message the person.' + workspaceOnlyNote,
+    inputSchema: {
+      email: z.string().describe('The other person\'s email address'),
+      account: accountParam,
+    },
+  }, async ({ email, account }) => {
+    return runOrDiagnose(['chat', 'dm', 'space', email], { account });
+  });
+
+  server.registerTool('gog_chat_reactions_list', {
+    description:
+      'List the emoji reactions on one message, with who reacted. gog_chat_messages_list already returns a reaction '
+      + 'SUMMARY per message; come here when you need the individual reactors, or the reaction resource names that '
+      + 'gog_chat_reactions_delete takes.' + workspaceOnlyNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      message: z.string().describe('Message resource name ("spaces/AAAA/messages/BBBB"), or a bare message ID together with `space`'),
+      space: z.string().optional().describe('Space resource name — required only when `message` is a bare ID'),
+      ...paginationParams,
+      account: accountParam,
+    },
+  }, async ({ message, space, max, pageToken, page, all, account }) => {
+    const args = ['chat', 'messages', 'reactions', 'list', message];
+    if (space) args.push(`--space=${space}`);
+    pushPaginationFlags(args, { max, pageToken, page, all });
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_reactions_create', {
+    description:
+      'React to a message with an emoji. Visible to the space immediately. Pass the emoji itself ("👍"), not a :shortcode:.'
+      + workspaceOnlyNote,
+    inputSchema: {
+      message: z.string().describe('Message resource name ("spaces/AAAA/messages/BBBB"), or a bare message ID together with `space`'),
+      emoji: z.string().describe('The emoji character to react with, e.g. "👍"'),
+      space: z.string().optional().describe('Space resource name — required only when `message` is a bare ID'),
+      account: accountParam,
+    },
+  }, async ({ message, emoji, space, account }) => {
+    const args = ['chat', 'messages', 'reactions', 'create', message, emoji];
+    if (space) args.push(`--space=${space}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_chat_reactions_delete', {
+    description:
+      'Remove one emoji reaction. Takes the REACTION\'s own resource name ("spaces/.../messages/.../reactions/..."), not '
+      + 'the message\'s and not the emoji — get it from gog_chat_reactions_list. An account can only remove its own reaction.'
+      + workspaceOnlyNote,
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      reaction: z.string().describe('Reaction resource name, e.g. "spaces/AAAA/messages/BBBB/reactions/CCCC"'),
+      account: accountParam,
+    },
+  }, async ({ reaction, account }) => {
+    return runOrDiagnose(['chat', 'messages', 'reactions', 'delete', reaction], { account });
+  });
+
+  registerRunTool(server, {
+    service: 'chat',
+    examples: '"spaces", "messages", "dm"',
+    note: 'Google Chat has no API for consumer accounts: every chat subcommand fails on an @gmail.com account regardless of scopes.',
+  });
+}

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.26.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/gmail-results.test.ts

@@ -255,6 +255,53 @@ describe('fetchGmailPages', () => {
     expect(runPage).toHaveBeenCalledTimes(2);
   });
 
+  // A REPEATED CURSOR IS A STALL, and gog 0.38.0 fixed the same class on its own
+  // side (openclaw/gogcli#1004) — but that fix covers gog's `--all`, and this
+  // walk is our own: it makes N separate single-page gog calls, so a cursor
+  // Google repeats comes straight back to this loop. Without a guard the walk
+  // re-fetches the same page and merges its items again on every remaining
+  // iteration, so the caller gets DUPLICATES presented as more results, which is
+  // worse than a short answer because nothing about the payload looks wrong.
+  it('stops when Google repeats a cursor, instead of re-fetching the same page', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(page(['b'], 'T1'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 10, undefined)).content[0].text as string);
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['a', 'b']);
+    // Stopped after the repeat was seen — NOT after burning all 10 pages.
+    expect(runPage).toHaveBeenCalledTimes(2);
+  });
+
+  it('still reads as truncated after a repeated cursor', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(page(['b'], 'T1'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 10, undefined)).content[0].text as string);
+    // The walk could not reach the end, so the cursor STAYS. Dropping it would
+    // claim completeness we never established, and a set that reads complete is
+    // exactly how "that email doesn't exist" gets reported about mail that does.
+    expect(out.nextPageToken).toBe('T1');
+  });
+
+  it('detects a cursor that repeats the caller-supplied one', async () => {
+    const runPage = vi.fn().mockResolvedValueOnce(page(['a'], 'START'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 10, 'START')).content[0].text as string);
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['a']);
+    expect(out.nextPageToken).toBe('START');
+    expect(runPage).toHaveBeenCalledTimes(1);
+  });
+
+  it('detects a cursor that repeats a token from earlier in the walk, not just the previous one', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(page(['b'], 'T2'))
+      .mockResolvedValueOnce(page(['c'], 'T1'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 10, undefined)).content[0].text as string);
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['a', 'b', 'c']);
+    expect(out.nextPageToken).toBe('T1');
+    expect(runPage).toHaveBeenCalledTimes(3);
+  });
+
   it('starts from a caller-supplied cursor', async () => {
     const runPage = vi.fn().mockResolvedValue(page(['a']));
     await fetchGmailPages(runPage, 'threads', 3, 'START');