@lanes-sh/link 0.1.0

package/src/providers/google/docs/index.ts

@@ -0,0 +1,45 @@
+import { defineProvider } from '#connectivity';
+import { DRIVE_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+
+/**
+ * Docs, on the same reasoning as `sheets`.
+ *
+ * One difference worth knowing: Docs has no `values`-style shortcut. Every edit,
+ * from inserting a word to restyling a heading, is a `batchUpdate` request, so
+ * that single operation is the entire write surface rather than the advanced
+ * half of it.
+ */
+const DOCS_SCOPES = [
+  'https://www.googleapis.com/auth/drive.readonly',
+  'https://www.googleapis.com/auth/drive.file',
+  'https://www.googleapis.com/auth/documents',
+];
+
+export const docs = defineProvider({
+  id: 'docs',
+  name: 'Google Docs',
+  description:
+    'Read a document\'s structure and edit its content — insert, replace, and format text — via the Docs REST API.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://docs.googleapis.com',
+    openapi: specPath('docs.v1.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: GOOGLE_APP,
+    scopes: DOCS_SCOPES,
+    ...GOOGLE_OAUTH,
+  },
+  identity: DRIVE_IDENTITY,
+  setup: googleSetup('Docs', DOCS_SCOPES, {
+    apis: ['docs.googleapis.com', 'drive.googleapis.com'],
+  }),
+  // `requests` carries the text being written, so only the document id is kept.
+  redact: {
+    'documents.get': ['documentId', 'suggestionsViewMode'],
+    'documents.batchUpdate': ['documentId'],
+  },
+});

package/src/providers/google/drive/hints.ts

@@ -0,0 +1,28 @@
+/**
+ * The three jobs `files.update` does that its name does not suggest.
+ *
+ * Drive spells "move", "rename", "trash", and "star" as one PATCH, and the
+ * generated description is the vendor's field list. So an agent asked to move
+ * or delete a file reads a tool list containing `files_update` and concludes
+ * neither is possible — which is exactly what happened.
+ */
+export const DRIVE_HINTS: Record<string, string> = {
+  'files.update': [
+    'This is also how a file is moved, renamed, and deleted.',
+    'Move it by passing `addParents` with the destination folder id and `removeParents`',
+    'with the current one — a Drive file has no path, only parents.',
+    'Rename it with `name`. Delete it with `trashed: true`, which is recoverable;',
+    'there is deliberately no permanent-delete tool here, because Drive has a trash',
+    'and an agent should not be able to bypass it. Restore with `trashed: false`.',
+  ].join(' '),
+
+  'files.create': [
+    'This also creates the Google-native file types, which have no create tool of their own:',
+    'pass `mimeType: "application/vnd.google-apps.spreadsheet"` for a spreadsheet,',
+    '`.document` for a Doc, `.presentation` for Slides, or `.folder` for a folder,',
+    'and leave the body empty. The file comes back with an id the Sheets and Docs tools',
+    'then work on directly — creating a spreadsheet and filling it is this call followed by',
+    '`sheets_spreadsheets_values_update`.',
+    'Place it by passing `parents` with a folder id.',
+  ].join(' '),
+};

package/src/providers/google/drive/index.ts

@@ -0,0 +1,34 @@
+import { defineProvider } from '#connectivity';
+import { DRIVE_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+import { DRIVE_HINTS } from './hints.ts';
+import { DRIVE_REDACT } from './redact.ts';
+
+/** Drive over the REST API. Same reasoning as `gmail` — no preview gate. */
+export const DRIVE_SCOPES = [
+  'https://www.googleapis.com/auth/drive.readonly',
+  'https://www.googleapis.com/auth/drive.file',
+];
+
+export const drive = defineProvider({
+  id: 'drive',
+  name: 'Google Drive',
+  description:
+    'Search, read, and export files, and organise the ones this app created — rename, move, trash, copy, and share — via the Drive REST API.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://www.googleapis.com/drive/v3',
+    openapi: specPath('drive.v3.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: GOOGLE_APP,
+    scopes: DRIVE_SCOPES,
+    ...GOOGLE_OAUTH,
+  },
+  identity: DRIVE_IDENTITY,
+  setup: googleSetup('Drive', DRIVE_SCOPES),
+  redact: DRIVE_REDACT,
+  hints: DRIVE_HINTS,
+});

package/src/providers/google/drive/redact.ts

@@ -0,0 +1,39 @@
+/**
+ * What survives into the audit log when a file is read or changed.
+ *
+ * Drive shipped without a redaction block, which meant `files.create` recorded
+ * that a file had been made and nothing about which one. Three write operations
+ * beside it make the gap worth closing rather than noting.
+ *
+ * `name` is withheld on `files.create` and `files.update` — the same call as
+ * Gmail's `labels.create`, where the name is the user's own words. `q` is
+ * withheld on `files.list` on the same ground Gmail withholds a search: the
+ * query is a question someone asked, not a record of what happened. Everything
+ * kept is an identifier or a flag: which file, which parents it moved between,
+ * whether it went to the trash.
+ *
+ * `permissions.create` keeps `emailAddress` and `domain`, and that departs from
+ * the withhold-addresses rule on purpose. Gmail withholds recipients because
+ * they are part of a message the log already refuses to record. Here the
+ * grantee *is* the change: an access log that can say a file was shared with
+ * somebody as a writer, but not with whom, has failed at the single question it
+ * exists to answer.
+ */
+export const DRIVE_REDACT: Record<string, string[]> = {
+  'files.list': ['pageSize', 'orderBy', 'spaces', 'includeItemsFromAllDrives'],
+  'files.get': ['fileId', 'acknowledgeAbuse'],
+  'files.export': ['fileId', 'mimeType'],
+  'permissions.list': ['fileId'],
+  'files.create': ['mimeType', 'parents'],
+  'files.update': ['fileId', 'addParents', 'removeParents', 'trashed', 'starred', 'mimeType'],
+  'files.copy': ['fileId', 'parents'],
+  'permissions.create': [
+    'fileId',
+    'role',
+    'type',
+    'domain',
+    'emailAddress',
+    'sendNotificationEmail',
+    'transferOwnership',
+  ],
+};

package/src/providers/google/drive-mcp/index.ts

@@ -0,0 +1,21 @@
+import { defineProvider } from '#connectivity';
+import { DRIVE_IDENTITY, GOOGLE_APP } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+import { DRIVE_SCOPES } from '../drive/index.ts';
+
+/**
+ * Drive via Google's MCP server. Workspace Developer Preview members only.
+ *
+ * Same story as Gmail. `drivemcp` advertises `auth/drive` too — full read-write
+ * over every file in the account — and granting it did not help either.
+ */
+export const driveMcp = defineProvider({
+  id: 'drive_mcp',
+  name: 'Google Drive (Google MCP)',
+  description:
+    'Search, read, and create files via Google\'s official Drive MCP server. Requires Workspace Developer Preview enrolment — use "drive" otherwise.',
+  connector: { kind: 'mcp', endpoint: 'https://drivemcp.googleapis.com/mcp/v1' },
+  auth: { kind: 'oauth', registration: 'manual', app: GOOGLE_APP, scopes: DRIVE_SCOPES },
+  identity: DRIVE_IDENTITY,
+  setup: googleSetup('Drive', DRIVE_SCOPES, { preview: true }),
+});

package/src/providers/google/gmail/api.ts

@@ -0,0 +1,42 @@
+/**
+ * Where Gmail is, in the two shapes it comes in.
+ *
+ * One file so the manifest's `base_url` and the authored send capability cannot
+ * drift apart — `tools.test.ts` asserts the manifest matches the vendored spec's
+ * server, and a second copy of the host is how a change satisfies that test while
+ * breaking the hand-written call beside it.
+ */
+
+export const GMAIL_HOST = 'https://gmail.googleapis.com';
+
+/** What the generated tools use, and what an ordinary JSON call goes to. */
+export const GMAIL_API = `${GMAIL_HOST}/gmail/v1/users/me`;
+
+/**
+ * The media-upload host, for a message too large to carry as a JSON string.
+ *
+ * A separate path rather than a query parameter: Google exposes uploads under
+ * `/upload/...`, and posting a large body to the ordinary endpoint does not fail
+ * loudly so much as get slower and then stop working.
+ */
+export const GMAIL_UPLOAD = `${GMAIL_HOST}/upload/gmail/v1/users/me`;
+
+/**
+ * The largest message Gmail will send, from its discovery document
+ * (`users.messages.send`, `maxSize: 36700160`).
+ *
+ * Note this is the *send* ceiling; `messages.import` allows 150 MiB. So it is a
+ * limit on putting mail into the world, not on storing it, which is why it is
+ * named for sending.
+ */
+export const GMAIL_MAX_MESSAGE_BYTES = 36_700_160;
+
+/**
+ * Above this, submit through the upload host instead of as a JSON field.
+ *
+ * Google's guidance calls `uploadType=media` the route for files over roughly
+ * this size, and the arithmetic agrees: `raw` is base64url inside a JSON string,
+ * so a message near the 35 MiB ceiling would be ~47 MiB of text in a request body
+ * and would meet a generic limit long before Gmail's own.
+ */
+export const GMAIL_JSON_LIMIT_BYTES = 5 * 1024 * 1024;

package/src/providers/google/gmail/attachment.ts

@@ -0,0 +1,142 @@
+import type { MailboxAttachmentSource } from '#connectivity/mail';
+import { GMAIL_API } from './api.ts';
+
+/**
+ * Re-attaching an attachment that is already in the mailbox.
+ *
+ * Two round trips rather than one, deliberately. `attachments.get` returns
+ * `{attachmentId, size, data}` and nothing else — no filename, no MIME type — so
+ * fetching only the bytes would produce an attachment called "attachment" of no
+ * particular type. The message metadata is where the part headers live, so it is
+ * read first, and it also lets a caller name the attachment by filename or omit
+ * the id when there is only one.
+ *
+ * The sharp edge here is the encoding. Gmail returns `data` as base64**url** (RFC
+ * 4648 §5), not standard base64. Handing that to a MIME composer that expects the
+ * standard alphabet corrupts any file containing a byte that encodes to `-` or
+ * `_` — which is most of them — and the result still arrives, still has the right
+ * length, and still opens as a file. It is a silent, plausible failure, and it is
+ * a known trap in other implementations of this same feature.
+ */
+export function gmailAttachments(input: {
+  readonly authorize: (request: Request) => Promise<Request>;
+  readonly fetch?: typeof globalThis.fetch | undefined;
+  readonly signal?: AbortSignal | undefined;
+}): MailboxAttachmentSource {
+  const doFetch = input.fetch ?? globalThis.fetch;
+
+  const get = async (path: string): Promise<Record<string, unknown>> => {
+    const request = await input.authorize(
+      new Request(`${GMAIL_API}${path}`, {
+        headers: { accept: 'application/json' },
+        ...(input.signal ? { signal: input.signal } : {}),
+      }),
+    );
+
+    const response = await doFetch(request);
+    if (!response.ok) {
+      throw new Error(`Gmail answered ${response.status} for ${path}: ${await response.text()}`);
+    }
+    return (await response.json()) as Record<string, unknown>;
+  };
+
+  return async ({ messageId, attachmentId }) => {
+    const message = await get(`/messages/${encodeURIComponent(messageId)}?format=full`);
+    const parts = attachmentParts(message['payload']);
+
+    if (parts.length === 0) throw new Error(`Message ${messageId} has no attachments.`);
+
+    const chosen = pick(parts, attachmentId, messageId);
+    const body = await get(
+      `/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(chosen.attachmentId)}`,
+    );
+
+    const data = body['data'];
+    if (typeof data !== 'string') {
+      throw new Error(`Gmail returned no content for attachment ${chosen.attachmentId}.`);
+    }
+
+    return {
+      // base64url in, bytes out. See the note above.
+      bytes: new Uint8Array(Buffer.from(data, 'base64url')),
+      filename: chosen.filename,
+      contentType: chosen.mimeType,
+    };
+  };
+}
+
+interface AttachmentPart {
+  readonly attachmentId: string;
+  readonly filename: string | null;
+  readonly mimeType: string | null;
+}
+
+/**
+ * Every part that is a file, from anywhere in the tree.
+ *
+ * Recursive because a message with both a body and attachments nests them —
+ * `multipart/mixed` holding a `multipart/alternative` holding the text — so the
+ * files are rarely at the top level.
+ */
+function attachmentParts(payload: unknown): AttachmentPart[] {
+  if (payload === null || typeof payload !== 'object') return [];
+
+  const part = payload as {
+    filename?: unknown;
+    mimeType?: unknown;
+    body?: { attachmentId?: unknown };
+    parts?: unknown;
+  };
+
+  const found: AttachmentPart[] = [];
+
+  const attachmentId = part.body?.attachmentId;
+  if (typeof attachmentId === 'string' && attachmentId !== '') {
+    found.push({
+      attachmentId,
+      filename: typeof part.filename === 'string' && part.filename !== '' ? part.filename : null,
+      mimeType: typeof part.mimeType === 'string' ? part.mimeType : null,
+    });
+  }
+
+  if (Array.isArray(part.parts)) {
+    for (const child of part.parts) found.push(...attachmentParts(child));
+  }
+
+  return found;
+}
+
+/** By filename, by position, or by there being only one. Mirrors the IMAP side. */
+function pick(
+  parts: readonly AttachmentPart[],
+  attachmentId: string | undefined,
+  messageId: string,
+): AttachmentPart {
+  const names = parts.map((part, index) => part.filename ?? `#${index + 1}`);
+
+  if (attachmentId === undefined) {
+    if (parts.length === 1) return parts[0]!;
+    throw new Error(
+      `Message ${messageId} has ${parts.length} attachments, so attachment_id is needed. They are: ${names.join(', ')}.`,
+    );
+  }
+
+  // Gmail's own opaque id, which is what `get_message` reports, so it is the
+  // most likely thing a caller passes.
+  const byId = parts.find((part) => part.attachmentId === attachmentId);
+  if (byId) return byId;
+
+  const byName = parts.find(
+    (part) => part.filename?.toLowerCase() === attachmentId.toLowerCase(),
+  );
+  if (byName) return byName;
+
+  const position = Number(attachmentId);
+  if (Number.isInteger(position) && position >= 1 && position <= parts.length) {
+    return parts[position - 1]!;
+  }
+
+  throw new Error(
+    `Message ${messageId} has no attachment "${attachmentId}". They are: ${names.join(', ')}.`,
+  );
+}

package/src/providers/google/gmail/hints.ts

@@ -0,0 +1,55 @@
+/**
+ * What Gmail's own document does not say about Gmail.
+ *
+ * Every mail-organising verb an agent is asked for — mark unread, archive, move
+ * to a folder, report spam — is the same operation with a different label id,
+ * and the generated description for that operation says only that
+ * `addLabelIds` is "a list of IDs of labels to add". Nothing names the ids, and
+ * nothing says that the ids *are* the feature.
+ *
+ * The cost of that omission is not a worse tool, it is a tool nobody finds. An
+ * operator asked for these four capabilities to be built; all four already
+ * existed and had for months. This file is the fix for that, and it is why the
+ * text below spells out the label ids rather than pointing at Google's docs:
+ * the reader is a model choosing a tool, and a pointer is a page it will not
+ * open.
+ */
+const LABEL_VERBS = [
+  'Gmail has no separate verb for read-state, archiving, or spam — each one is a label edit,',
+  'and this is the operation that makes it:',
+  '`addLabelIds: ["UNREAD"]` marks unread and `removeLabelIds: ["UNREAD"]` marks read;',
+  '`removeLabelIds: ["INBOX"]` archives;',
+  '`addLabelIds: ["SPAM"], removeLabelIds: ["INBOX"]` reports spam;',
+  '`addLabelIds: ["STARRED"]` stars.',
+  'Moving a message into a folder is the same shape — add that folder\'s label id and remove',
+  '"INBOX" — because a Gmail folder *is* a label. Call `labels_list` for the ids of the',
+  'ones the user made; the capitalised ones above are system labels and always exist.',
+  'To delete mail, use the `trash` operation rather than a label: it is recoverable and',
+  'there is no permanent-delete tool here by design.',
+].join(' ');
+
+export const GMAIL_HINTS: Record<string, string> = {
+  'users.messages.modify': LABEL_VERBS,
+  // The same text, deliberately. A model that finds one of these and not the
+  // others should not have to infer that the batch form works identically —
+  // and the batch form is the one worth reaching for on a mailbox sweep.
+  'users.messages.batchModify': `${LABEL_VERBS} This is the batch form: pass up to 1000 message ids in \`ids\`.`,
+  'users.threads.modify': `${LABEL_VERBS} This applies to every message in the thread at once.`,
+
+  // The distinction Gmail's UI draws with two buttons and its API draws not at
+  // all. Getting it wrong is silent in both directions: reporting spam when
+  // asked to block leaves the sender arriving tomorrow, and installing a filter
+  // when asked to report spam leaves a rule nobody remembers creating.
+  'users.settings.filters.create': [
+    'This is how a sender is blocked, as opposed to reported.',
+    'Reporting spam is a one-off label edit on messages that already exist —',
+    'use `messages_modify` with `addLabelIds: ["SPAM"]` for that.',
+    'A filter is a standing rule applied to mail that has not arrived yet:',
+    '`criteria: {from: "someone@example.com"}` with',
+    '`action: {addLabelIds: ["TRASH"]}` to bin it on arrival, or',
+    '`action: {addLabelIds: ["SPAM"]}` to route it to spam.',
+    '`criteria` also matches on `to`, `subject`, `query`, and `hasAttachment`.',
+    'The rule keeps running until it is deleted — it outlives this session,',
+    'so prefer the one-off label edit unless a standing rule is what was asked for.',
+  ].join(' '),
+};

package/src/providers/google/gmail/index.ts

@@ -0,0 +1,112 @@
+import { defineProvider, defineProviderWithCapabilities } from '#connectivity';
+import { GMAIL_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+import { GMAIL_HOST } from './api.ts';
+import { GMAIL_HINTS } from './hints.ts';
+import { GMAIL_REDACT } from './redact.ts';
+import { gmailSendMessage } from './send.ts';
+
+/**
+ * Gmail over the REST API — the one that works for everybody.
+ *
+ * `gmail-mcp` proxies Google's own MCP server, which is the nicer thing on
+ * paper: their tools, their maintenance. It is also gated behind a Workspace
+ * Developer Preview that a personal @gmail.com account cannot enrol in, and the
+ * failure is silent — consent succeeds, tools/list succeeds, every call returns
+ * "The caller does not have permission".
+ *
+ * So the plain name is the working one. The REST API has no preview gate, no
+ * enrolment, and the same scopes; what it costs is that the tool list is
+ * generated from an OpenAPI document rather than curated by Google.
+ */
+
+/**
+ * What the REST provider needs to read, draft, and organise mail.
+ *
+ * `gmail.modify` is here for organising, and it is not a preference: Gmail has
+ * no verb for read-state, spam, or archive. Each one is a label edit on a
+ * message — remove `UNREAD`, add `SPAM`, remove `INBOX` — and `modify` is the
+ * only scope that permits editing a message's labels. `gmail.labels` sounds
+ * narrower and is not a substitute: it governs the label vocabulary, not its
+ * application. So the choice is `modify` or no organising at all.
+ *
+ * It is marked broad in `../shared/scopes.ts` and should stay marked, because it
+ * also grants send and trash. What it does not grant is permanent delete — that
+ * is `mail.google.com`, which nothing here asks for. Policy is what keeps the
+ * granted-but-unwanted verbs unreachable: the token can send, the tool surface
+ * cannot, and `lanes link policy deny` narrows it further.
+ */
+/**
+ * `gmail.settings.basic` is here for blocking a sender, and it is the one scope
+ * in this list that buys a *kind* of reach the others do not.
+ *
+ * Adding `SPAM` to a message trains Gmail against that sender and is what the
+ * Report-spam button does; it is already reachable under `modify`. Blocking is
+ * the other button, and it is a filter — a standing rule, created once, that
+ * keeps acting on mail that does not exist yet. `filters.create` and
+ * `filters.delete` accept no other scope. (`filters.list` accepts `readonly`,
+ * so seeing what exists costs nothing extra; only changing it costs this.)
+ *
+ * That standing quality is why it is marked broad in `../shared/scopes.ts`
+ * rather than waved through as narrower than `modify`. Every other write here
+ * acts on a message that already exists, and stops when the session does. A
+ * filter with `addLabelIds: ['TRASH']` keeps trashing mail after the token
+ * expires and after the connection is disabled — `lanes link policy deny`
+ * removes the tool, and cannot uninstall the rule. It is the argument that
+ * refuses `messages.delete`, one step removed.
+ *
+ * What it deliberately does not reach: `delegates.create` and
+ * `forwardingAddresses.create` are `gmail.settings.sharing`, so the two
+ * settings that silently exfiltrate a mailbox stay out, and a filter's
+ * `action.forward` only accepts an address already verified by hand.
+ */
+export const GMAIL_SCOPES = [
+  'https://www.googleapis.com/auth/gmail.readonly',
+  'https://www.googleapis.com/auth/gmail.compose',
+  'https://www.googleapis.com/auth/gmail.modify',
+  'https://www.googleapis.com/auth/gmail.settings.basic',
+];
+
+const manifest = defineProvider({
+  id: 'gmail',
+  name: 'Gmail',
+  description:
+    'Read, search, send, draft, and organise mail — labels, read-state, spam, and trash — via the Gmail REST API.',
+  connector: {
+    kind: 'http',
+    base_url: GMAIL_HOST,
+    // Vendored, not fetched: a spec decides which paths are called with a real
+    // mailbox token, and `connect` grants everything a provider discovers.
+    openapi: specPath('gmail.v1.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: GOOGLE_APP,
+    scopes: GMAIL_SCOPES,
+    ...GOOGLE_OAUTH,
+  },
+  // The REST API rather than the MCP server: it answers with the address under
+  // scopes we already hold, so labelling a connection costs no extra consent.
+  identity: GMAIL_IDENTITY,
+  setup: googleSetup('Gmail', GMAIL_SCOPES),
+  redact: GMAIL_REDACT,
+  hints: GMAIL_HINTS,
+  // Named here because an `http` connector otherwise assigns bundles by HTTP
+  // method during discovery, and an authored capability is never discovered.
+  bundles: [{ name: 'write', capabilities: ['send_message'] }],
+});
+
+/**
+ * Almost all data, and one capability that has to be code.
+ *
+ * The exception is sending. Gmail's API takes a whole assembled RFC 2822 message
+ * as one base64url field, and no OpenAPI document describes composing one — so the
+ * generated tools leave that to the caller, which makes attaching a file
+ * impossible in practice rather than merely awkward. `send.ts` says the rest.
+ * Everything else about this provider is still the manifest above.
+ */
+export const gmail = defineProviderWithCapabilities({
+  manifest,
+  capabilities: [gmailSendMessage],
+});

package/src/providers/google/gmail/redact.ts

@@ -0,0 +1,56 @@
+/**
+ * Only the organising capabilities, and only their identifiers.
+ *
+ * The default withholds every value, which is right for the reads — `q` is a
+ * search query, and "who did I email about the diagnosis" is the whole message.
+ * But it makes a write log useless: it records that a message was modified
+ * without recording which one, or into what. These keys are the difference
+ * between "something was marked spam" and "this was".
+ *
+ * Label *ids* are safe to keep and are the point of the entry — `UNREAD`,
+ * `SPAM`, `INBOX`, or an opaque `Label_12`. Label *names* are the user's own
+ * words, so `labels.create` logs that a label was made and not what it says.
+ */
+export const GMAIL_REDACT: Record<string, string[]> = {
+  'users.messages.modify': ['userId', 'id', 'addLabelIds', 'removeLabelIds'],
+  'users.messages.batchModify': ['userId', 'ids', 'addLabelIds', 'removeLabelIds'],
+  'users.messages.trash': ['userId', 'id'],
+  'users.messages.untrash': ['userId', 'id'],
+  'users.threads.modify': ['userId', 'id', 'addLabelIds', 'removeLabelIds'],
+  'users.threads.trash': ['userId', 'id'],
+  'users.threads.untrash': ['userId', 'id'],
+  'users.labels.create': ['userId'],
+  // `pathId` for the same reason as `drafts.update` below — the `Label` body
+  // carries an `id` too. This said `id` until the argument-name check in
+  // `cli/tools.test.ts` was written, which meant every label edit was logged
+  // without saying which label.
+  'users.labels.update': ['userId', 'pathId'],
+  'users.labels.delete': ['userId', 'id'],
+  'users.drafts.delete': ['userId', 'id'],
+  'users.settings.filters.list': ['userId'],
+  'users.settings.filters.delete': ['userId', 'id'],
+  // `criteria` kept, which is the same call as `drive.permissions.create`
+  // keeping `emailAddress`: a log saying a filter was installed but not against
+  // whom has failed at the only question it exists to answer. `action` is the
+  // effect — the label ids, and `forward`, which is an address worth naming on
+  // the one occasion it is set.
+  //
+  // The cost, stated rather than hidden: `criteria` also carries `query`,
+  // `subject`, and `negatedQuery`, so a filter built on words instead of a
+  // sender logs those words — the class Gmail's reads withhold on the "who did
+  // I email about the diagnosis" ground. The tiebreak is durability. A search
+  // is a question asked once; a filter is a rule that keeps running after the
+  // credential stops working, and this log is then the only record of who
+  // installed it. `annotate` would express the split properly, but it needs an
+  // authored capability and these are generated.
+  'users.settings.filters.create': ['userId', 'id', 'criteria', 'action'],
+  // Nothing. The recipients and the body *are* the message, and `attachments` is
+  // the one argument that may literally contain a file — keeping it verbatim
+  // would put base64 in the audit log. What was attached is recorded by the send
+  // path itself through `audit.annotate`: filename, size, type, SHA-256, and
+  // where the bytes came from. Identifiers, not content.
+  //
+  // Unprefixed because this capability is authored rather than generated, so its
+  // name has no `gmail.` to strip.
+  send_message: [],
+};