@aaronsb/google-workspace-mcp 4.6.1 → 4.8.0

package/build/services/gmail/labels.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Label changes, in words. Shared by the two previews that describe a label change before
+ * it happens: a filter's (on each message as it arrives) and a query-scoped bulk change's
+ * (on every message the preview counted). ADR-309, ADR-310.
+ */
+export interface Effect {
+    /** What happens, in a clause: "skips the inbox". */
+    text: string;
+    /** Why it is worth a second look, shown in full previews only. */
+    detail?: string;
+    /** A consequence worth a second look before approving: disposal, or mail leaving the account. */
+    warn?: boolean;
+}
+export interface LabelChange {
+    addLabelIds?: string[];
+    removeLabelIds?: string[];
+}
+/** When the change lands: as each future match arrives, or now on the set already there. */
+export type Timing = 'arrival' | 'now';
+/** Comma-separated (or array) label ids, trimmed, deduplicated and sorted; undefined when none. */
+export declare function parseLabelIds(value: unknown): string[] | undefined;
+/** Label id → name, for every label on the account, system labels included. */
+export declare function labelNames(account: string): Promise<Map<string, string>>;
+/**
+ * One error per label id the account does not have. A label NAME passed where an id
+ * belongs is the common mistake, so it is answered with the id.
+ */
+export declare function labelIdErrors(change: LabelChange, names: Map<string, string>): string[];
+export declare function describeLabelChanges(change: LabelChange, names: Map<string, string>, timing: Timing): Effect[];
+/** A bullet for a preview: the warning mark, the effect, and its detail. */
+export declare function effectLine(e: Effect): string;

package/build/services/gmail/labels.js

@@ -0,0 +1,108 @@
+/**
+ * Label changes, in words. Shared by the two previews that describe a label change before
+ * it happens: a filter's (on each message as it arrives) and a query-scoped bulk change's
+ * (on every message the preview counted). ADR-309, ADR-310.
+ */
+import { call } from '../../google/client.js';
+const TRASH_DETAIL = 'Gmail deletes trash permanently after 30 days';
+const SPAM_DETAIL = 'Gmail deletes spam permanently after 30 days';
+/** System labels a label change cannot add or remove; Gmail refuses them. */
+const UNCHANGEABLE = new Set(['SENT', 'DRAFT', 'CHAT']);
+const SYSTEM_LABEL_EFFECTS = {
+    INBOX: {
+        add: { arrival: { text: 'kept in the inbox' }, now: { text: 'put in the inbox' } },
+        remove: { arrival: { text: 'skips the inbox: archived on arrival' }, now: { text: 'archived: removed from the inbox' } },
+    },
+    UNREAD: {
+        add: { arrival: { text: 'marked unread' }, now: { text: 'marked unread' } },
+        remove: { arrival: { text: 'marked read on arrival' }, now: { text: 'marked read' } },
+    },
+    STARRED: {
+        add: { arrival: { text: 'starred' }, now: { text: 'starred' } },
+        remove: { arrival: { text: 'never starred' }, now: { text: 'unstarred' } },
+    },
+    IMPORTANT: {
+        add: { arrival: { text: 'marked important' }, now: { text: 'marked important' } },
+        remove: { arrival: { text: 'never marked important' }, now: { text: 'marked not important' } },
+    },
+    TRASH: {
+        add: {
+            arrival: { text: 'moved to trash on arrival', detail: `${TRASH_DETAIL}, so matching mail nobody looks at is gone after that`, warn: true },
+            now: {
+                text: 'moved to trash',
+                detail: `This is a bulk trash. ${TRASH_DETAIL}; until then, preview the same query with \`in:trash\` added and removeLabelIds TRASH to restore them`,
+                warn: true,
+            },
+        },
+        remove: { arrival: { text: 'kept out of trash' }, now: { text: 'restored from trash' } },
+    },
+    SPAM: {
+        add: {
+            arrival: { text: 'sent to spam on arrival', detail: SPAM_DETAIL, warn: true },
+            now: { text: 'moved to spam', detail: SPAM_DETAIL, warn: true },
+        },
+        remove: { arrival: { text: 'never sent to spam' }, now: { text: 'taken out of spam' } },
+    },
+};
+/** Comma-separated (or array) label ids, trimmed, deduplicated and sorted; undefined when none. */
+export function parseLabelIds(value) {
+    const items = Array.isArray(value) ? value.map(String) : String(value ?? '').split(',');
+    const ids = [...new Set(items.map((s) => s.trim()).filter(Boolean))].sort();
+    return ids.length ? ids : undefined;
+}
+/** Label id → name, for every label on the account, system labels included. */
+export async function labelNames(account) {
+    const raw = await call('gmail', 'users.labels.list', { userId: 'me' }, { account });
+    const labels = (raw?.labels ?? []);
+    return new Map(labels.filter((l) => l.id).map((l) => [String(l.id), String(l.name ?? l.id)]));
+}
+/**
+ * One error per label id the account does not have. A label NAME passed where an id
+ * belongs is the common mistake, so it is answered with the id.
+ */
+export function labelIdErrors(change, names) {
+    const byName = new Map([...names].map(([id, n]) => [n.toLowerCase(), id]));
+    const errors = [];
+    for (const id of [...(change.addLabelIds ?? []), ...(change.removeLabelIds ?? [])]) {
+        if (UNCHANGEABLE.has(id)) {
+            errors.push(`${id} is set by Gmail itself; a label change cannot add or remove it.`);
+            continue;
+        }
+        if (names.has(id))
+            continue;
+        const hint = byName.get(id.toLowerCase());
+        errors.push(hint
+            ? `'${id}' is a label name; this takes its id, ${hint}.`
+            : `No label with id '${id}' on this account. Create it with \`createLabel\`, or see ids with \`labels\`.`);
+    }
+    return errors;
+}
+export function describeLabelChanges(change, names, timing) {
+    const effects = [];
+    const name = (id) => names.get(id) ?? id;
+    const category = (id) => id.slice('CATEGORY_'.length).toLowerCase();
+    for (const id of change.addLabelIds ?? []) {
+        const system = SYSTEM_LABEL_EFFECTS[id]?.add?.[timing];
+        if (system)
+            effects.push(system);
+        else if (id.startsWith('CATEGORY_'))
+            effects.push({ text: `sorted into the ${category(id)} category` });
+        else
+            effects.push({ text: `labeled "${name(id)}"` });
+    }
+    for (const id of change.removeLabelIds ?? []) {
+        const system = SYSTEM_LABEL_EFFECTS[id]?.remove?.[timing];
+        if (system)
+            effects.push(system);
+        else if (id.startsWith('CATEGORY_'))
+            effects.push({ text: `${timing === 'arrival' ? 'kept out of' : 'taken out of'} the ${category(id)} category` });
+        else
+            effects.push({ text: `"${name(id)}" label removed` });
+    }
+    return effects;
+}
+/** A bullet for a preview: the warning mark, the effect, and its detail. */
+export function effectLine(e) {
+    return `- ${e.warn ? '⚠ ' : ''}${e.text}${e.detail ? `. ${e.detail}` : ''}`;
+}
+//# sourceMappingURL=labels.js.map

package/build/services/gmail/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","sourceRoot":"","sources":["../../../src/services/gmail/labels.ts"],"names":[],"mappings":"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"}

package/build/services/gmail/modify-matching.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Label changes over everything a query matches, with no ids in the conversation (ADR-310, #206).
+ *
+ * `previewModifyMatching` resolves the query to the full set of message ids, holds it
+ * server-side under the preview token, and returns the exact count, a sample, and what the
+ * change does to each message. `modifyMatching` applies the change to exactly that set, in
+ * `batchModify` chunks, and reports how many it changed. The set is used once.
+ *
+ * Mail that starts matching after the preview is untouched: routing future mail is a
+ * filter's job (filters.ts).
+ */
+import { type HandlerResponse } from '../../server/formatting/markdown.js';
+/** `previewModifyMatching` — count, sample and describe the change, and hold the set. */
+export declare function handlePreviewModifyMatching(params: Record<string, unknown>, account: string): Promise<HandlerResponse>;
+/** `modifyMatching` — apply the previewed change to exactly the previewed set. */
+export declare function handleModifyMatching(params: Record<string, unknown>, account: string): Promise<HandlerResponse>;

package/build/services/gmail/modify-matching.js

@@ -0,0 +1,149 @@
+/**
+ * Label changes over everything a query matches, with no ids in the conversation (ADR-310, #206).
+ *
+ * `previewModifyMatching` resolves the query to the full set of message ids, holds it
+ * server-side under the preview token, and returns the exact count, a sample, and what the
+ * change does to each message. `modifyMatching` applies the change to exactly that set, in
+ * `batchModify` chunks, and reports how many it changed. The set is used once.
+ *
+ * Mail that starts matching after the preview is untouched: routing future mail is a
+ * filter's job (filters.ts).
+ */
+import { call } from '../../google/client.js';
+import { formatShortDate, truncate } from '../../server/formatting/markdown.js';
+import { requireString } from '../../server/handlers/validate.js';
+import { PREVIEW_TTL_MS, checkPreviewToken, describeTokenFailure, mintPreviewToken, } from '../../server/preview-gate.js';
+import { MAX_SET_SIZE, heldSet, holdSet, releaseSet, setDigest } from '../../server/preview-sets.js';
+import { hydrateMessages } from './hydrate.js';
+import { describeLabelChanges, effectLine, labelIdErrors, labelNames, parseLabelIds } from './labels.js';
+const KIND = 'manage_email.modifyMatching';
+/** Why the write is gated, for the refusal when no token is given. */
+const GATED_BECAUSE = 'It changes every message a query matched, a set the caller never sees row by row';
+/** `users.messages.batchModify` takes at most this many ids per call. */
+const BATCH_LIMIT = 1000;
+const PAGE_SIZE = 500;
+const SAMPLE_SIZE = 5;
+/** The query and the change a call describes. Throws a sentence naming what is wrong. */
+function buildRequest(params) {
+    const query = requireString(params, 'query').trim();
+    const change = {};
+    const add = parseLabelIds(params.addLabelIds);
+    const remove = parseLabelIds(params.removeLabelIds);
+    if (add)
+        change.addLabelIds = add;
+    if (remove)
+        change.removeLabelIds = remove;
+    if (!add && !remove) {
+        throw new Error('Give at least one change: addLabelIds, or removeLabelIds (e.g. INBOX to archive, UNREAD to mark read).');
+    }
+    const both = (add ?? []).filter((id) => remove?.includes(id));
+    if (both.length)
+        throw new Error(`A label cannot be both added and removed: ${both.join(', ')}.`);
+    return { query, change };
+}
+/** Every id the query matches, or the first MAX_SET_SIZE + 1 when there are more. */
+async function resolveQuery(account, q) {
+    const ids = [];
+    let pageToken;
+    do {
+        const page = await call('gmail', 'users.messages.list', {
+            userId: 'me', q, maxResults: PAGE_SIZE, ...(pageToken ? { pageToken } : {}),
+        }, { account });
+        ids.push(...(page?.messages ?? []).map((m) => m.id));
+        pageToken = typeof page?.nextPageToken === 'string' && page.nextPageToken ? page.nextPageToken : undefined;
+    } while (pageToken && ids.length <= MAX_SET_SIZE);
+    return ids.length > MAX_SET_SIZE ? { ids: [], over: true } : { ids, over: false };
+}
+const plural = (n) => `${n.toLocaleString('en-US')} message${n === 1 ? '' : 's'}`;
+function refused(text, refs = {}) {
+    return { text, refs: { ...refs, blocked: true } };
+}
+/** `previewModifyMatching` — count, sample and describe the change, and hold the set. */
+export async function handlePreviewModifyMatching(params, account) {
+    const { query, change } = buildRequest(params);
+    const [names, resolved] = await Promise.all([labelNames(account), resolveQuery(account, query)]);
+    const { ids } = resolved;
+    const errors = labelIdErrors(change, names);
+    if (resolved.over) {
+        errors.push(`More than ${MAX_SET_SIZE.toLocaleString('en-US')} messages match, more than one preview holds. ` +
+            'Narrow the query, for example with after: and before: dates, and preview each part.');
+    }
+    const sample = ids.length ? await hydrateMessages(ids.slice(0, SAMPLE_SIZE).map((id) => ({ id })), account) : [];
+    const lines = [`## Preview: change every message matching \`${query}\``, ''];
+    lines.push(resolved.over
+        ? `**Matches:** more than ${plural(MAX_SET_SIZE)}.`
+        : `**Matches:** ${ids.length === 0 ? 'none' : plural(ids.length)}.`);
+    lines.push('**Each is:**', ...describeLabelChanges(change, names, 'now').map(effectLine));
+    if (sample.length) {
+        lines.push('', 'Most recent matches:');
+        for (const m of sample) {
+            lines.push(m.error
+                ? `${String(m.id)} | ⚠ ${String(m.error)}`
+                : `${String(m.id)} | ${truncate(String(m.from ?? ''), 30)} | ${truncate(String(m.subject ?? '(no subject)'), 50)} | ${formatShortDate(m.date)}`);
+        }
+    }
+    // Gmail leaves spam and trash out of a search unless the query names them.
+    const namesSpamOrTrash = /\bin:(trash|spam|anywhere)\b/i.test(query);
+    lines.push('', (namesSpamOrTrash ? '' : 'Spam and trash are not included. ') +
+        'Mail that starts matching after this preview is not changed; to route it as it arrives, preview a filter with `previewFilter`.');
+    const refs = { query, matchCount: resolved.over ? undefined : ids.length };
+    if (!errors.length && ids.length === 0) {
+        lines.push('', 'Nothing matches, so there is nothing to change and no previewToken.');
+        return { text: lines.join('\n'), refs };
+    }
+    if (errors.length) {
+        lines.push('', '### Cannot apply this change', ...errors.map((e) => `- ${e}`), '', 'No previewToken issued. Fix the parameters and preview again.');
+        return { text: lines.join('\n'), refs: { ...refs, errors } };
+    }
+    const token = mintPreviewToken(KIND, account, { query, change, digest: setDigest(ids) });
+    holdSet(token, account, ids);
+    lines.push('', 'To apply it, call `modifyMatching` with the same parameters and previewToken:', `\`${token}\``, `Good for ${PREVIEW_TTL_MS / 60_000} minutes and once. It changes exactly the ${plural(ids.length)} counted here.`);
+    return { text: lines.join('\n'), refs: { ...refs, previewToken: token } };
+}
+/** `modifyMatching` — apply the previewed change to exactly the previewed set. */
+export async function handleModifyMatching(params, account) {
+    const { query, change } = buildRequest(params);
+    const token = params.previewToken;
+    const ids = typeof token === 'string' ? heldSet(token.trim(), account) : undefined;
+    if (!ids) {
+        // No set to check against. A token that is absent, not ours, or for another operation
+        // says so; anything else was a real preview whose set is gone.
+        const check = checkPreviewToken(token, KIND, account, { query, change, digest: '' });
+        if (!check.ok && (check.failure === 'missing' || check.failure === 'malformed' || check.failure === 'wrong-kind')) {
+            return refused(`**Nothing changed.** ${describeTokenFailure(check, 'modifyMatching', 'previewModifyMatching', GATED_BECAUSE)}`);
+        }
+        return refused('**Nothing changed.** This preview is no longer held: it was applied already, expired after ' +
+            `${PREVIEW_TTL_MS / 60_000} minutes, was displaced by newer previews, or the server restarted. ` +
+            'Call `previewModifyMatching` with these parameters and pass the previewToken it returns.');
+    }
+    const check = checkPreviewToken(token, KIND, account, { query, change, digest: setDigest(ids) });
+    if (!check.ok) {
+        return refused(`**Nothing changed.** ${describeTokenFailure(check, 'modifyMatching', 'previewModifyMatching', GATED_BECAUSE)}`);
+    }
+    // Fetched before the set is released, so a failure here leaves the preview usable and
+    // nothing changed, rather than a completed write reported as a failure.
+    const names = await labelNames(account);
+    // Used once, whatever happens next: a retry resolves the query again.
+    releaseSet(token.trim());
+    let changed = 0;
+    for (let i = 0; i < ids.length; i += BATCH_LIMIT) {
+        const chunk = ids.slice(i, i + BATCH_LIMIT);
+        try {
+            await call('gmail', 'users.messages.batchModify', { userId: 'me', ids: chunk, ...change }, { account });
+        }
+        catch (err) {
+            // Thrown, so a queue with onError 'bail' stops here.
+            const why = err instanceof Error ? err.message : String(err);
+            throw new Error(`modifyMatching stopped part way: changed ${changed} of ${ids.length} messages, then the batch starting at ` +
+                `message ${i + 1} failed (${why}). The preview is used up. Preview again to finish; the query now resolves ` +
+                'against the mailbox as it is, without any message deleted since.');
+        }
+        changed += chunk.length;
+    }
+    return {
+        text: [`Changed ${plural(changed)} matching \`${query}\`. Each was:`,
+            ...describeLabelChanges(change, names, 'now').map((e) => `- ${e.text}`)].join('\n'),
+        refs: { query, changed },
+    };
+}
+//# sourceMappingURL=modify-matching.js.map

package/build/services/gmail/modify-matching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modify-matching.js","sourceRoot":"","sources":["../../../src/services/gmail/modify-matching.ts"],"names":[],"mappings":"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"}

package/build/services/gmail/patch.js

@@ -9,119 +9,14 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { call } from '../../google/client.js';
-import { GoogleApiError } from '../../google/errors.js';
 import { formatEmailList, formatEmailDetail, extractBodyFromPayload, extractAttachments, decodeSnippet, truncate, formatShortDate } from '../../server/formatting/markdown.js';
-import { requireString } from '../../server/handlers/validate.js';
+import { requireString, clamp } from '../../server/handlers/validate.js';
 import { ensureWorkspaceDir, resolveWorkspacePath, verifyPathSafety } from '../../executor/workspace.js';
 import { handleGetAttachment, handleViewAttachment } from './attachments.js';
+import { hydrateMessages, hydrateDrafts } from './hydrate.js';
+import { handleListFilters, handleGetFilter, handlePreviewFilter, handleCreateFilter, handleUpdateFilter, handleDeleteFilter, } from './filters.js';
+import { handlePreviewModifyMatching, handleModifyMatching } from './modify-matching.js';
 import { sendMail, replyMail, forwardMail } from './mail.js';
-/**
- * Hydrate message IDs with metadata (From, Subject, Date, snippet).
- * Reused from the original email handler.
- */
-async function hydrateMessages(messageIds, account) {
-    // Google throttles per USER, not per process, so this burst competes with every
-    // other client signed in to the same account. Firing all 50 at once is the surest
-    // way to be told no. A modest window is barely slower — the calls still overlap —
-    // and it is far less likely to be throttled in the first place.
-    return mapLimited(messageIds, HYDRATE_CONCURRENCY, async (msg) => {
-        try {
-            const data = await call('gmail', 'users.messages.get', {
-                userId: 'me',
-                id: msg.id,
-                format: 'metadata',
-                metadataHeaders: ['From', 'Subject', 'Date'],
-            }, { account });
-            const headers = (data.payload?.headers ?? []);
-            const getHeader = (name) => headers.find(h => h.name.toLowerCase() === name.toLowerCase())?.value;
-            return {
-                id: data.id,
-                threadId: data.threadId,
-                from: getHeader('from'),
-                subject: getHeader('subject'),
-                date: getHeader('date'),
-                snippet: data.snippet,
-            };
-        }
-        catch (err) {
-            // A message we could not READ must never look like a message with NOTHING IN IT.
-            //
-            // This used to `catch { return { id: msg.id } }` — every failure became a row
-            // with no sender, no subject and no date, indistinguishable from a genuinely
-            // empty message. Under rate limiting the tail of an inbox silently rendered as
-            // blank lines, and the tool reported success while showing the user nothing.
-            //
-            // The client retries a 429 now, so reaching here means it did not recover. Say
-            // so, in the row, where the person reading the list will actually see it.
-            return {
-                id: msg.id,
-                error: err instanceof GoogleApiError
-                    ? `could not load (${err.status}${err.reason ? ' ' + err.reason : ''})`
-                    : `could not load (${err instanceof Error ? err.message : String(err)})`,
-            };
-        }
-    });
-}
-/** Concurrent, but bounded. */
-const HYDRATE_CONCURRENCY = 8;
-/**
- * Hydrate draft resources with message metadata (From, To, Subject, Date, snippet).
- *
- * users.drafts.list returns one bare {id: draftId, message: {id, threadId}} per draft —
- * enough to identify a draft, nothing to tell drafts apart. Each draft's message is
- * fetched (metadata format, exactly like the search/triage hydration) and the DRAFT id
- * stays on the row, because it — not the message id — is what deleteDraft addresses.
- */
-async function hydrateDrafts(drafts, account) {
-    return mapLimited(drafts, HYDRATE_CONCURRENCY, async (draft) => {
-        const draftId = draft.id;
-        const messageId = draft.message?.id;
-        if (!messageId) {
-            return { draftId, error: 'draft carries no message id' };
-        }
-        try {
-            const data = await call('gmail', 'users.messages.get', {
-                userId: 'me',
-                id: messageId,
-                format: 'metadata',
-                metadataHeaders: ['From', 'To', 'Subject', 'Date'],
-            }, { account });
-            const headers = (data.payload?.headers ?? []);
-            const getHeader = (name) => headers.find(h => h.name.toLowerCase() === name.toLowerCase())?.value;
-            return {
-                draftId,
-                messageId: data.id,
-                threadId: data.threadId,
-                to: getHeader('to'),
-                from: getHeader('from'),
-                subject: getHeader('subject'),
-                date: getHeader('date'),
-                snippet: data.snippet,
-            };
-        }
-        catch (err) {
-            return {
-                draftId,
-                messageId,
-                error: err instanceof GoogleApiError
-                    ? `could not load (${err.status}${err.reason ? ' ' + err.reason : ''})`
-                    : `could not load (${err instanceof Error ? err.message : String(err)})`,
-            };
-        }
-    });
-}
-async function mapLimited(items, limit, fn) {
-    const results = new Array(items.length);
-    let next = 0;
-    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-        while (next < items.length) {
-            const i = next++;
-            results[i] = await fn(items[i]); // fn never rejects — it catches internally
-        }
-    });
-    await Promise.all(workers);
-    return results;
-}
 /** "Tue, 19 Aug 2026 ..." -> "2026-08-19"; '' when the header is not parseable. */
 const MONTH_TO_MM = {
     Jan: '01', Feb: '02', Mar: '03', Apr: '04', May: '05', Jun: '06',
@@ -281,26 +176,81 @@ function formatThreadDetail(data) {
         },
     };
 }
+/** Largest page `messages.list` returns; the ids-only page size. */
+const IDS_ONLY_PAGE = 500;
+function isIdsOnly(ctx) {
+    return ctx.operation === 'search' && (ctx.params.idsOnly === true || ctx.params.idsOnly === 'true');
+}
+/** The paging fields of a Gmail list response, kept through hydration. */
+function pagingFrom(raw) {
+    return {
+        ...(typeof raw?.nextPageToken === 'string' && raw.nextPageToken ? { nextPageToken: raw.nextPageToken } : {}),
+        ...(typeof raw?.resultSizeEstimate === 'number' ? { resultSizeEstimate: raw.resultSizeEstimate } : {}),
+    };
+}
+/**
+ * Say when a list stopped before the end (ADR-309).
+ *
+ * A full page and a complete result look identical otherwise: 50 rows of 50 and 50 rows
+ * of 400 render the same, and the reader sizes the problem from the wrong one.
+ */
+function withPaging(response, data, ctx) {
+    const raw = (data ?? {});
+    const nextPageToken = typeof raw.nextPageToken === 'string' ? raw.nextPageToken : '';
+    if (!nextPageToken)
+        return response;
+    const estimate = typeof raw.resultSizeEstimate === 'number' ? raw.resultSizeEstimate : undefined;
+    const sized = estimate !== undefined
+        ? ` Google estimates about ${estimate} in total; that figure is an estimate and is often wrong.`
+        : '';
+    return {
+        text: `${response.text}\n\nMore results exist.${sized} Call \`${ctx.operation}\` again with the same parameters and pageToken: ${nextPageToken}`,
+        refs: { ...response.refs, nextPageToken, ...(estimate !== undefined ? { resultSizeEstimate: estimate } : {}) },
+    };
+}
+/** An ids-only search page: the ids, comma-separated, ready for bulk_operations batch. */
+function formatIdList(data) {
+    const ids = (data?.ids ?? []);
+    if (ids.length === 0)
+        return { text: 'No messages found.', refs: { count: 0, ids: [] } };
+    return {
+        text: `## Message ids (${ids.length})\n\n${ids.join(',')}`,
+        refs: { count: ids.length, ids },
+    };
+}
 export const gmailPatch = {
+    beforeExecute: {
+        // An ids-only page costs one call however long it is, so it pages at the API's own
+        // limit rather than at the cap that exists to bound hydration.
+        search: (callParams, ctx) => isIdsOnly(ctx)
+            ? { ...callParams, maxResults: clamp(ctx.params.maxResults, IDS_ONLY_PAGE, IDS_ONLY_PAGE) }
+            : callParams,
+    },
     afterExecute: {
         // triage IS search, with a different default query. Same raw Google shape
         // (messages.list -> bare ids), same hydrate, same formatter.
         triage: async (result, ctx) => gmailPatch.afterExecute.search(result, ctx),
         search: async (result, ctx) => {
-            // messages.list returns bare IDs — hydrate with metadata
+            // messages.list returns bare IDs. idsOnly hands them back as they are, which is what
+            // makes walking thousands of matches cheap; otherwise each row is hydrated.
             const raw = result;
             const ids = (raw?.messages ?? []);
+            const paging = pagingFrom(raw);
+            if (isIdsOnly(ctx)) {
+                return { ids: ids.map((m) => m.id), idsOnly: true, ...paging };
+            }
             if (ids.length === 0) {
                 // Preserve resultSizeEstimate so formatters can distinguish
                 // "search ran, no matches" from unexpected empty responses
                 return {
                     messages: [],
+                    ...paging,
                     resultSizeEstimate: raw?.resultSizeEstimate ?? 0,
                     query: ctx.params.query ?? '',
                 };
             }
             const messages = await hydrateMessages(ids, ctx.account);
-            return { messages, resultSizeEstimate: raw?.resultSizeEstimate };
+            return { messages, ...paging };
         },
         // users.drafts.list returns bare draft resources ({id, message:{id}}) — hydrate
         // each with metadata so listDrafts shows recipient/subject/date, not just ids.
@@ -308,10 +258,10 @@ export const gmailPatch = {
             const raw = result;
             const drafts = (raw?.drafts ?? []);
             if (drafts.length === 0) {
-                return { drafts: [], resultSizeEstimate: raw?.resultSizeEstimate ?? 0 };
+                return { drafts: [], ...pagingFrom(raw), resultSizeEstimate: raw?.resultSizeEstimate ?? 0 };
             }
             const hydrated = await hydrateDrafts(drafts, ctx.account);
-            return { drafts: hydrated, resultSizeEstimate: raw?.resultSizeEstimate };
+            return { drafts: hydrated, ...pagingFrom(raw) };
         },
     },
     formatList: (data, ctx) => {
@@ -319,11 +269,11 @@ export const gmailPatch = {
             case 'labels':
                 return formatLabelList(data);
             case 'threads':
-                return formatThreadList(data);
+                return withPaging(formatThreadList(data), data, ctx);
             case 'listDrafts':
-                return formatDraftList(data);
+                return withPaging(formatDraftList(data), data, ctx);
             default:
-                return formatEmailList(data);
+                return withPaging(isIdsOnly(ctx) ? formatIdList(data) : formatEmailList(data), data, ctx);
         }
     },
     formatDetail: (data, ctx) => {
@@ -492,6 +442,16 @@ export const gmailPatch = {
         },
         getAttachment: handleGetAttachment,
         viewAttachment: handleViewAttachment,
+        // Filters — the lifecycle and its preview gate live in filters.ts (ADR-309).
+        filters: handleListFilters,
+        getFilter: handleGetFilter,
+        previewFilter: handlePreviewFilter,
+        createFilter: handleCreateFilter,
+        updateFilter: handleUpdateFilter,
+        deleteFilter: handleDeleteFilter,
+        // Label changes over a whole query, ids held server-side (ADR-310).
+        previewModifyMatching: handlePreviewModifyMatching,
+        modifyMatching: handleModifyMatching,
         /**
          * Delete a draft — permanently discard an unsent message.
          *