gogcli-mcp 2.23.1 → 2.24.0

package/tests/gmail-results.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
+import * as runner from '../src/runner.js';
+import { finalizeGmailSearch, fetchGmailPages } from '../src/gmail-results.js';
+
+vi.mock('../src/runner.js');
+
+beforeEach(() => vi.clearAllMocks());
+
+const THREADS = (nextPageToken: string) => JSON.stringify({
+  threads: [
+    { id: 'a', internalDateIso: '2026-08-01T09:00:00-04:00' },
+    { id: 'b', internalDateIso: '2026-08-12T12:36:00-04:00' },
+    { id: 'c', internalDateIso: '2026-08-05T09:00:00-04:00' },
+  ],
+  nextPageToken,
+});
+
+const THREAD_OPTS = { itemsKey: 'threads', method: 'users.threads.list', query: 'x' } as const;
+
+const parse = (r: { content: { type: string; text?: string }[] }) =>
+  JSON.parse(r.content[0].text as string);
+
+describe('finalizeGmailSearch — ordering', () => {
+  it('sorts newest-first by internalDateIso', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('')), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['b', 'c', 'a']);
+  });
+
+  it('falls back to date when internalDateIso is absent', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'a', date: '2026-08-01T09:00:00-04:00' },
+        { id: 'b', date: '2026-08-09T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['b', 'a']);
+  });
+
+  it('puts undated and unparseable items last, in their original order', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'nodate' },
+        { id: 'empty', internalDateIso: '' },
+        { id: 'bad', internalDateIso: 'not-a-date' },
+        { id: 'dated', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['dated', 'nodate', 'empty', 'bad']);
+  });
+
+  it('ignores a non-string date field', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'weird', internalDateIso: 12345 },
+        { id: 'dated', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['dated', 'weird']);
+  });
+
+  it('keeps equal timestamps in their original relative order', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'first', internalDateIso: '2026-08-05T09:00:00-04:00' },
+        { id: 'second', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['first', 'second']);
+  });
+
+  it('sorts the messages key too', async () => {
+    const raw = JSON.stringify({
+      messages: [
+        { id: 'a', internalDateIso: '2026-08-01T09:00:00-04:00' },
+        { id: 'b', internalDateIso: '2026-08-12T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), {
+      itemsKey: 'messages', method: 'users.messages.list', query: 'x',
+    }));
+    expect(out.messages.map((t: { id: string }) => t.id)).toEqual(['b', 'a']);
+  });
+});
+
+describe('finalizeGmailSearch — truncation metadata', () => {
+  const countReply = (ids: number, more: boolean) => JSON.stringify({
+    threads: Array.from({ length: ids }, (_, i) => ({ id: `t${i}` })),
+    ...(more ? { nextPageToken: 'more' } : {}),
+  });
+
+  it('omits every truncation field when the result set is complete', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('')), THREAD_OPTS));
+    expect(out).not.toHaveProperty('truncated');
+    expect(out).not.toHaveProperty('returned');
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out).not.toHaveProperty('warning');
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+
+  it('omits them when gog reports no nextPageToken field at all', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult('{"threads":[{"id":"a"}]}'), THREAD_OPTS));
+    expect(out).not.toHaveProperty('truncated');
+  });
+
+  it('reports an EXACT total when the count probe reaches the end', async () => {
+    vi.mocked(runner.run).mockResolvedValue(countReply(21, false));
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), {
+      itemsKey: 'threads', method: 'users.threads.list', query: 'invoice', account: 'me@x.com',
+    }));
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(3);
+    expect(out.totalMatches).toBe(21);
+    expect(out).not.toHaveProperty('totalMatchesAtLeast');
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 3 of 21 matches. Do not report an absence of results ' +
+      'based on this response. Page with nextPageToken or narrow the query.',
+    );
+  });
+
+  it('reports a LOWER BOUND when the count probe fills its page', async () => {
+    vi.mocked(runner.run).mockResolvedValue(countReply(500, true));
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out.totalMatchesAtLeast).toBe(500);
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 3 of at least 500 matches. Do not report an absence of ' +
+      'results based on this response. Page with nextPageToken or narrow the query.',
+    );
+  });
+
+  it('counts bare ids for one maximal page, scoped to the matching items key', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"messages":[{"id":"a"}]}');
+    const raw = JSON.stringify({ messages: [{ id: 'a' }], nextPageToken: 'tok' });
+    await finalizeGmailSearch(rawTextResult(raw), {
+      itemsKey: 'messages', method: 'users.messages.list', query: 'invoice', account: 'me@x.com',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['api', 'call', 'gmail', 'v1', 'users.messages.list',
+        `--params=${JSON.stringify({ userId: 'me', q: 'invoice', maxResults: 500, fields: 'messages/id,nextPageToken' })}`],
+      { account: 'me@x.com' },
+    );
+  });
+
+  it('still warns, without a count, when the count probe fails', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('nope'));
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(3);
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out).not.toHaveProperty('totalMatchesAtLeast');
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 3 matches and MORE EXIST beyond this page. Do not report ' +
+      'an absence of results based on this response. Page with nextPageToken or narrow the query.',
+    );
+  });
+
+  it('omits the count when the probe output is not JSON', async () => {
+    vi.mocked(runner.run).mockResolvedValue('not json');
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out).not.toHaveProperty('totalMatches');
+  });
+
+  it('omits the count when the probe returns no items array', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"nextPageToken":"x"}');
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out).not.toHaveProperty('totalMatchesAtLeast');
+  });
+
+  it('treats an empty nextPageToken on the probe as the end of the set', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"threads":[{"id":"a"}],"nextPageToken":""}');
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out.totalMatches).toBe(1);
+  });
+
+  it('skips the count probe when the query gog ran cannot be reproduced', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), {
+      ...THREAD_OPTS, queryIsExact: false,
+    }));
+    expect(runner.run).not.toHaveBeenCalled();
+    expect(out.truncated).toBe(true);
+    expect(out).not.toHaveProperty('totalMatches');
+  });
+});
+
+describe('finalizeGmailSearch — pass-through', () => {
+  it('passes an error result through untouched', async () => {
+    const err = errorResult('Error: boom');
+    expect(await finalizeGmailSearch(err, THREAD_OPTS)).toBe(err);
+  });
+
+  it('passes non-JSON output through untouched', async () => {
+    const text = rawTextResult('No results');
+    expect(await finalizeGmailSearch(text, THREAD_OPTS)).toBe(text);
+  });
+
+  it('passes JSON without the expected items array through untouched', async () => {
+    const text = rawTextResult('{"somethingElse":1}');
+    expect(await finalizeGmailSearch(text, THREAD_OPTS)).toBe(text);
+  });
+
+  it('passes a result with no text content through untouched', async () => {
+    const empty = { content: [] } as unknown as Parameters<typeof finalizeGmailSearch>[0];
+    expect(await finalizeGmailSearch(empty, THREAD_OPTS)).toBe(empty);
+  });
+
+  it('handles an empty result set without adding truncation fields', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult('{"threads":[],"nextPageToken":""}'), THREAD_OPTS));
+    expect(out.threads).toEqual([]);
+    expect(out).not.toHaveProperty('truncated');
+  });
+});
+
+describe('fetchGmailPages', () => {
+  const page = (ids: string[], token?: string) => rawTextResult(JSON.stringify({
+    threads: ids.map((id) => ({ id })),
+    ...(token === undefined ? {} : { nextPageToken: token }),
+  }));
+
+  it('merges pages and drops the cursor when it reaches the end', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(page(['b'], 'T2'))
+      .mockResolvedValueOnce(page(['c']));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 5, undefined)).content[0].text as string);
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['a', 'b', 'c']);
+    expect(out).not.toHaveProperty('nextPageToken');
+    expect(runPage.mock.calls.map((c) => c[0])).toEqual([undefined, 'T1', 'T2']);
+  });
+
+  it('treats an empty-string cursor as the end', async () => {
+    const runPage = vi.fn().mockResolvedValueOnce(page(['a'], ''));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 5, undefined)).content[0].text as string);
+    expect(out).not.toHaveProperty('nextPageToken');
+    expect(runPage).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the cursor when the page cap is reached first', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(page(['b'], 'T2'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 2, undefined)).content[0].text as string);
+    expect(out.threads).toHaveLength(2);
+    expect(out.nextPageToken).toBe('T2');
+    expect(runPage).toHaveBeenCalledTimes(2);
+  });
+
+  it('starts from a caller-supplied cursor', async () => {
+    const runPage = vi.fn().mockResolvedValue(page(['a']));
+    await fetchGmailPages(runPage, 'threads', 3, 'START');
+    expect(runPage).toHaveBeenCalledWith('START');
+  });
+
+  it('surfaces a failure on the FIRST page as-is', async () => {
+    const err = errorResult('Error: boom');
+    const runPage = vi.fn().mockResolvedValue(err);
+    expect(await fetchGmailPages(runPage, 'threads', 3, undefined)).toBe(err);
+  });
+
+  it('keeps pages already collected when a LATER page fails, still marked truncated', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(errorResult('Error: boom'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 3, undefined)).content[0].text as string);
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['a']);
+    expect(out.nextPageToken).toBe('T1');
+  });
+
+  it('bails on output it cannot parse or that has no items array', async () => {
+    for (const bad of [rawTextResult('not json'), rawTextResult('"scalar"'), rawTextResult('{"other":1}')]) {
+      const runPage = vi.fn().mockResolvedValue(bad);
+      expect(await fetchGmailPages(runPage, 'threads', 3, undefined)).toBe(bad);
+    }
+  });
+});

package/tests/page-cursor-contract.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { createTestHarness } from '@chrischall/mcp-utils/test';
+import { BASE_TOOL_REGISTRARS } from '../src/server.js';
+
+// The bug this guards against was a NAME mismatch: the cursor was called `page`
+// while every response reports `nextPageToken`, and MCP inputs are zod objects
+// that silently strip unknown keys — so a client guessing the name from the
+// response got page 1 forever, with no error. Prose that steers a caller back
+// to the deprecated alias re-creates exactly that trap, one tool at a time.
+
+type ToolDef = { name: string; description?: string; inputSchema?: { properties?: Record<string, unknown> } };
+
+async function allTools(): Promise<ToolDef[]> {
+  const harness = await createTestHarness((server) => {
+    for (const register of BASE_TOOL_REGISTRARS) register(server);
+  });
+  const { tools } = await harness.client.listTools();
+  await harness.close();
+  return tools as ToolDef[];
+}
+
+describe('page-cursor contract across every base tool', () => {
+  it('never tells a caller to pass the cursor as the deprecated `page`', async () => {
+    // The alias as its own token: `page` closed immediately, which `pageToken`
+    // can never match. A looser pattern matches the correct name's prefix and
+    // fails on a description that is already right.
+    const offenders = (await allTools())
+      .filter((t) => /`page`|\bas page\b/i.test(t.description ?? ''))
+      .map((t) => t.name);
+    expect(offenders).toEqual([]);
+  });
+
+  it('always offers the `page` alias wherever `pageToken` is accepted', async () => {
+    const mismatched = (await allTools())
+      .filter((t) => {
+        const props = t.inputSchema?.properties ?? {};
+        return 'pageToken' in props && !('page' in props);
+      })
+      .map((t) => t.name);
+    expect(mismatched).toEqual([]);
+  });
+
+  it('names the cursor after the response field wherever one is paginated', async () => {
+    const tools = await allTools();
+    const withCursor = tools.filter((t) => 'pageToken' in (t.inputSchema?.properties ?? {}));
+    // Guards the audit itself: if this ever drops to zero the two tests above
+    // pass vacuously and the contract stops being checked at all.
+    expect(withCursor.length).toBeGreaterThan(0);
+  });
+});

package/tests/pagination.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
+import {
+  stripConsumedPageToken,
+  annotateTruncatedList,
+  truncationWarning,
+  hasMorePages,
+} from '../src/pagination.js';
+
+describe('stripConsumedPageToken', () => {
+  it('removes an exhausted cursor so the key means "another page exists"', () => {
+    expect(stripConsumedPageToken('{"threads":[{"id":"a"}],"nextPageToken":""}'))
+      .toBe('{"threads":[{"id":"a"}]}');
+  });
+
+  it('keeps a live cursor untouched, byte for byte', () => {
+    const live = '{"threads":[{"id":"a"}],"nextPageToken":"tok"}';
+    expect(stripConsumedPageToken(live)).toBe(live);
+  });
+
+  it('preserves --pretty indentation when it has to re-serialize', () => {
+    const pretty = '{\n  "threads": [],\n  "nextPageToken": ""\n}';
+    expect(stripConsumedPageToken(pretty)).toBe('{\n  "threads": []\n}');
+  });
+
+  it('treats a tab indent as two spaces, matching the timestamp seam', () => {
+    expect(stripConsumedPageToken('{\n\t"a": 1,\n\t"nextPageToken": ""\n}'))
+      .toBe('{\n  "a": 1\n}');
+  });
+
+  it('leaves a payload with no cursor field alone', () => {
+    const plain = '{"threads":[]}';
+    expect(stripConsumedPageToken(plain)).toBe(plain);
+  });
+
+  it('only touches the top level — a nested cursor is another resource\'s', () => {
+    const nested = '{"thread":{"nextPageToken":""}}';
+    expect(stripConsumedPageToken(nested)).toBe(nested);
+  });
+
+  it('passes through non-JSON, empty, array and scalar output untouched', () => {
+    for (const text of ['No results', '', '   ', '[{"nextPageToken":""}]', '"a string"', '{not json']) {
+      expect(stripConsumedPageToken(text)).toBe(text);
+    }
+  });
+
+  it('passes through a JSON null without dereferencing it', () => {
+    expect(stripConsumedPageToken('null')).toBe('null');
+  });
+});
+
+describe('truncationWarning', () => {
+  it('names an exact total when one is known', () => {
+    expect(truncationWarning(3, { total: 21 })).toContain('returned 3 of 21 matches');
+  });
+
+  it('says "at least" for a lower bound', () => {
+    expect(truncationWarning(3, { atLeast: 500 })).toContain('returned 3 of at least 500 matches');
+  });
+
+  it('still forbids a negative conclusion when no count is available', () => {
+    const w = truncationWarning(3, {});
+    expect(w).toContain('returned 3 matches and MORE EXIST beyond this page');
+    expect(w).toContain('Do not report an absence of results');
+  });
+});
+
+describe('hasMorePages', () => {
+  it('is true only for a live cursor', () => {
+    expect(hasMorePages({ nextPageToken: 'tok' })).toBe(true);
+    expect(hasMorePages({ nextPageToken: '' })).toBe(false);
+    expect(hasMorePages({})).toBe(false);
+    expect(hasMorePages({ nextPageToken: 7 })).toBe(false);
+  });
+});
+
+describe('annotateTruncatedList', () => {
+  it('adds the block when a live cursor remains', () => {
+    const out = JSON.parse(annotateTruncatedList(
+      rawTextResult('{"events":[{"id":"a"},{"id":"b"}],"nextPageToken":"tok"}'), 'events',
+    ).content[0].text as string);
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(2);
+    expect(out.warning).toContain('INCOMPLETE RESULT SET');
+  });
+
+  it('returns the result untouched when the set is complete', () => {
+    const complete = rawTextResult('{"events":[{"id":"a"}]}');
+    expect(annotateTruncatedList(complete, 'events')).toBe(complete);
+  });
+
+  it('passes errors, non-JSON, missing arrays and empty content through untouched', () => {
+    const err = errorResult('boom');
+    expect(annotateTruncatedList(err, 'events')).toBe(err);
+    const text = rawTextResult('No results');
+    expect(annotateTruncatedList(text, 'events')).toBe(text);
+    const other = rawTextResult('{"somethingElse":1,"nextPageToken":"tok"}');
+    expect(annotateTruncatedList(other, 'events')).toBe(other);
+    const empty = { content: [] } as unknown as Parameters<typeof annotateTruncatedList>[0];
+    expect(annotateTruncatedList(empty, 'events')).toBe(empty);
+  });
+});

package/tests/tools/auth.test.ts

@@ -124,6 +124,35 @@ describe('gog_auth_add', () => {
     );
   });
 
+  // gog 0.37.0's Connected Sheets reads need bigquery.readonly, which no
+  // `services` selection covers. --force-consent is not optional alongside it:
+  // Google re-prompts for a NEW scope only when consent is forced, so without
+  // it the grant can come back missing the scope AND reporting success.
+  it('passes --extra-scopes with --force-consent', async () => {
+    vi.mocked(runner.run).mockResolvedValue('Authorization successful');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add', {
+      email: 'user@gmail.com',
+      services: 'sheets',
+      extraScopes: 'https://www.googleapis.com/auth/bigquery.readonly',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--services', 'sheets',
+        '--extra-scopes=https://www.googleapis.com/auth/bigquery.readonly', '--force-consent'],
+      { interactive: true, timeout: 300_000 },
+    );
+  });
+
+  it('does not force consent when no extra scopes are asked for', async () => {
+    vi.mocked(runner.run).mockResolvedValue('Authorization successful');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add', { email: 'user@gmail.com' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--services', 'all'],
+      { interactive: true, timeout: 300_000 },
+    );
+  });
+
   it('returns error text on failure', async () => {
     vi.mocked(runner.run).mockRejectedValue(new Error('Auth cancelled by user'));
     const harness = await setupHandlers();
@@ -215,6 +244,21 @@ describe('gog_auth_add_url', () => {
     );
   });
 
+  it('appends --extra-scopes after the service scopes', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"auth_url":"https://x"}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add_url', {
+      email: 'user@gmail.com',
+      services: 'sheets',
+      extraScopes: 'https://www.googleapis.com/auth/bigquery.readonly',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--remote', '--step', '1', '--services', 'sheets', '--force-consent',
+        '--extra-scopes=https://www.googleapis.com/auth/bigquery.readonly'],
+      { redactMode: 'tokens' },
+    );
+  });
+
   it('returns error text on failure', async () => {
     vi.mocked(runner.run).mockRejectedValue(new Error('client not configured'));
     const harness = await setupHandlers();
@@ -252,6 +296,22 @@ describe('gog_auth_add_complete', () => {
     );
   });
 
+  it('carries the same --extra-scopes as step 1', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"stored":true}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_auth_add_complete', {
+      email: 'user@gmail.com',
+      redirectUrl: 'http://127.0.0.1/cb?code=c&state=s',
+      services: 'sheets',
+      extraScopes: 'https://www.googleapis.com/auth/bigquery.readonly',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--remote', '--step', '2', '--auth-url',
+        'http://127.0.0.1/cb?code=c&state=s', '--services', 'sheets', '--force-consent',
+        '--extra-scopes=https://www.googleapis.com/auth/bigquery.readonly'],
+    );
+  });
+
   it('returns error text on failure (e.g. expired state)', async () => {
     vi.mocked(runner.run).mockRejectedValue(new Error('no matching manual auth state'));
     const harness = await setupHandlers();

package/tests/tools/calendar.test.ts

@@ -17,23 +17,50 @@ describe('gog_calendar_events', () => {
     expect(runner.run).toHaveBeenCalledWith(['calendar', 'events'], { account: undefined });
   });
 
-  it('appends calendarId and filters when provided', async () => {
+  // The window flags are pinned as SEPARATE cases on purpose: gog >= 0.36.0
+  // (openclaw/gogcli#981) rejects a fixed preset combined with from/to/days,
+  // and days combined with to, so one test passing them all at once would
+  // assert an arg array gog refuses to run.
+  it('appends calendarId and an explicit from/to range', async () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
     await harness.callTool('gog_calendar_events', {
       calendarId: 'primary',
       from: '2026-01-01',
       to: '2026-01-31',
-      today: true,
       query: 'standup',
       all: true,
     });
     expect(runner.run).toHaveBeenCalledWith(
-      ['calendar', 'events', 'primary', '--from=2026-01-01', '--to=2026-01-31', '--today', '--query=standup', '--all'],
+      ['calendar', 'events', 'primary', '--from=2026-01-01', '--to=2026-01-31', '--query=standup', '--all'],
       { account: undefined },
     );
   });
 
+  it('appends --today on its own', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { today: true });
+    expect(runner.run).toHaveBeenCalledWith(['calendar', 'events', '--today'], { account: undefined });
+  });
+
+  it('anchors --days at --from when both are given', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { from: '2026-09-25', days: 5 });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['calendar', 'events', '--from=2026-09-25', '--days=5'],
+      { account: undefined },
+    );
+  });
+
+  it('passes --days alone as a today-anchored window', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { days: 7 });
+    expect(runner.run).toHaveBeenCalledWith(['calendar', 'events', '--days=7'], { account: undefined });
+  });
+
   it('repeats --event-types for each requested type', async () => {
     vi.mocked(runner.run).mockResolvedValue('{}');
     const harness = await setupHandlers();
@@ -379,3 +406,54 @@ describe('gog_calendar_run', () => {
   });
 });
 
+
+describe('gog_calendar_events — pagination (previously absent entirely)', () => {
+  // gog defaults this command to --max=10 and the tool exposed NEITHER max nor
+  // a cursor, so a wide date range silently returned 10 events with a live
+  // token the caller could not use. Measured live: 2025-01-01..2026-08-01 gave
+  // 10 of 12.
+  it('passes --max and --page through to gog', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[]}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { max: 100, pageToken: 'CURSOR' });
+    const args = vi.mocked(runner.run).mock.calls[0][0] as string[];
+    expect(args).toContain('--max=100');
+    expect(args).toContain('--page=CURSOR');
+  });
+
+  it('accepts the deprecated page alias', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[]}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { page: 'CURSOR' });
+    expect(vi.mocked(runner.run).mock.calls[0][0]).toContain('--page=CURSOR');
+  });
+
+  it('keeps --all meaning ALL CALENDARS, not all pages', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[]}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { all: true });
+    expect(vi.mocked(runner.run).mock.calls[0][0]).toContain('--all');
+  });
+
+  it('marks a capped range truncated, with no fabricated total', async () => {
+    vi.mocked(runner.run).mockResolvedValue(JSON.stringify({
+      events: [{ id: 'e1' }, { id: 'e2' }],
+      nextPageToken: 'MORE',
+    }));
+    const harness = await setupHandlers();
+    const out = JSON.parse((await harness.callTool('gog_calendar_events',
+      { from: '2025-01-01', to: '2026-08-01' })).content[0].text as string);
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(2);
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out.warning).toContain('INCOMPLETE RESULT SET: returned 2 matches and MORE EXIST');
+  });
+
+  it('leaves a complete range unannotated', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[{"id":"e1"}],"nextPageToken":""}');
+    const harness = await setupHandlers();
+    const out = JSON.parse((await harness.callTool('gog_calendar_events', {})).content[0].text as string);
+    expect(out).not.toHaveProperty('truncated');
+    expect(out).not.toHaveProperty('nextPageToken');
+  });
+});