mcp-google-multi 6.0.0-beta.3 → 6.0.0-beta.4

package/dist/tools/_errors.js

@@ -25,10 +25,8 @@ function headerOf(error, name) {
     const key = Object.keys(h).find((k) => k.toLowerCase() === name);
     return key === undefined ? undefined : String(h[key]);
 }
-/** gaxios hands `response.data` back as a STRING whenever it could not parse
- * JSON, and on every non-2xx of a responseType:'stream' call (drive_download,
- * drive_export), where it buffers the whole body to utf8 before throwing. So
- * the JSON error of a failed download is invisible to a plain property read. */
+// gaxios hands response.data back as a STRING whenever it can't parse JSON,
+// including every non-2xx of a responseType:'stream' call (drive_download/export).
 function errorPayload(error) {
     const data = error?.response?.data;
     if (data && typeof data === 'object')
@@ -48,9 +46,8 @@ function errorPayload(error) {
         return undefined;
     }
 }
-/** AIP-193 google.rpc.ErrorInfo. Modern Workspace APIs (Chat, Meet, Workspace
- * Events, Analytics Data, People) put the machine-readable reason here and
- * leave errors[0].reason empty, which is why their 403s used to fall through. */
+// AIP-193 google.rpc.ErrorInfo: modern Workspace APIs put the machine-readable
+// reason here and leave errors[0].reason empty, which is why their 403s used to fall through.
 function errorInfoOf(payload) {
     const details = payload?.error?.details;
     if (!Array.isArray(details))
@@ -71,10 +68,8 @@ function reasonOf(error, payload) {
         payload?.error?.status);
 }
 const MARKUP_START_RE = /^\uFEFF?\s*(?:<!--|<!\s*doctype\b|<\?xml\b|<\/?(?:html|head|body|meta|title|style|script|h[1-6]|div|p|pre|center|table|font)\b)/i;
-/** True when error.message is a response BODY rather than an error sentence.
- * Content-Type first, shape second, markup sniff last, anchored at the start.
- * NEVER matches page TEXT: the same URL answers "Page introuvable" to a
- * French-locale account and "Page not found" to anonymous curl. */
+// True when error.message is a response BODY, not an error sentence; never
+// matches page TEXT (a localized "Page introuvable" must still pass through).
 function isRawBody(error, message) {
     const ct = headerOf(error, 'content-type')?.toLowerCase();
     if (ct)
@@ -108,17 +103,15 @@ export function safeMessage(error, payload = errorPayload(error), status = statu
     const raw = typeof error?.message === 'string' ? error.message : String(error);
     return isRawBody(error, raw) ? bodyPlaceholder(error, status, raw.length) : capMessage(raw);
 }
-// Connect/DNS syscall codes. ENOTFOUND (no such name) is the one non-transient
-// member. node-fetch flattens the happy-eyeballs AggregateError to a bare code
-// with an empty message, so the code is the only surviving signal to surface.
+// Connect/DNS syscall codes; ENOTFOUND is the one non-transient member. The
+// code is the only surviving signal once node-fetch flattens the AggregateError.
 const RETRIABLE_NET_CODES = new Set([
     'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'ENETUNREACH',
     'EHOSTUNREACH', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET',
 ]);
 const NET_CODES = new Set([...RETRIABLE_NET_CODES, 'ENOTFOUND']);
-// Local-filesystem syscall codes from caller-supplied paths (localPath/savePath).
-// String codes, so they never collide with Google's numeric statuses; the
-// network codes above are deliberately excluded.
+// Local-filesystem syscall codes (never collide with Google's numeric
+// statuses); the network codes above are deliberately excluded.
 const LOCAL_FS_CODES = new Set(['ENOENT', 'EACCES', 'EISDIR', 'ENOTDIR', 'EPERM', 'ELOOP', 'ENAMETOOLONG', 'ENOSPC']);
 /** First known network code on the error or its cause chain (GaxiosError.cause
  * -> FetchError; undici TypeError.cause -> AggregateError.errors). */
@@ -134,7 +127,7 @@ function netCodeOf(error) {
     }
     return undefined;
 }
-/** Console deep-link to enable one API (noob-proofing hint, B10). */
+/** Console deep-link to enable one API (noob-proofing hint). */
 function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
 }
@@ -156,8 +149,7 @@ const FORBIDDEN_RATE_REASONS = new Set([
     'sharingRateLimitExceeded', 'quotaExceeded', 'RATE_LIMIT_EXCEEDED', 'RESOURCE_EXHAUSTED',
 ]);
 // Google already answered correctly: the file type is wrong for the tool, not
-// the permissions. The escape hatch has said this for years (executor.ts); the
-// curated pair used to discard it and blame sharing instead.
+// the permissions; the curated pair used to discard that and blame sharing instead.
 const WRONG_TOOL_HINTS = {
     fileNotDownloadable: 'This is a Google Workspace native file (Doc, Sheet, Slides): it has no binary content to download. Use drive_export with a target mimeType such as application/pdf.',
     fileNotExportable: 'Export only works on Google Workspace native files. This one already has binary content: use drive_download to save it as is.',
@@ -194,9 +186,8 @@ function rateLimited(error, message, account, reason) {
         account,
     };
 }
-/** Prefer AIP metadata (service + consumer) over scraping the message: the
- * scrape stays as the fallback because Google's JSON error text is English
- * only, unlike its localized HTML pages. */
+// Prefer AIP metadata over scraping the message: the scrape stays as fallback
+// since Google's JSON error text is English only, unlike its localized HTML pages.
 function enableHint(info, message) {
     const service = info?.metadata?.service;
     const project = info?.metadata?.consumer?.replace(/^projects\//, '');
@@ -216,9 +207,7 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
     const message = safeMessage(error, payload, status);
     const hints = normalizeHints(serviceHints);
     // 7-day Testing-mode trap: a BYO OAuth client in "Testing" status expires
-    // refresh tokens weekly; the dead token surfaces as invalid_grant. Name the
-    // real fix (publish to production) so the agent stops looping on re-auth.
-    // Checked before the generic 401 so it wins on either 400 or 401.
+    // refresh tokens weekly; checked before the generic 401 so it wins on either 400 or 401.
     const rawError = payload?.error;
     const grantHaystack = [message, reason, typeof rawError === 'string' ? rawError : '', payload?.error_description]
         .filter(Boolean)
@@ -266,9 +255,8 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             });
             return { error: 'api_not_enabled', message, hint: rendered?.hint ?? enableHint(info, message), retriable: false, account };
         }
-        // The scope hint fires ONLY on the machine-readable token. A coarse AIP
-        // status of PERMISSION_DENIED is equally true of a resource denial, and
-        // branching on it is what told callers to add a bundle they already had.
+        // Fires ONLY on the machine-readable token: a coarse PERMISSION_DENIED is
+        // equally true of a resource denial, and branching on it told callers to add a bundle they already had.
         const scopeIssue = reason === 'ACCESS_TOKEN_SCOPE_INSUFFICIENT' ||
             reason === 'insufficientPermissions' ||
             /\bACCESS_TOKEN_SCOPE_INSUFFICIENT\b/.test(message);
@@ -334,9 +322,8 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             account,
         };
     }
-    // A caller-side 4xx and a Google outage used to share `upstream_error`, so a
-    // consumer keying on the slug could not tell "your request is wrong, never
-    // retry" from "Google is having a bad minute, do retry".
+    // Used to share `upstream_error` with a 5xx, so a consumer keying on the
+    // slug couldn't tell "never retry" from "do retry".
     if (status !== undefined && status >= 400) {
         return {
             error: 'bad_request',
@@ -397,18 +384,14 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
                 hint: rendered?.hint ??
                     (`Network failure (${netCode}) before reaching Google - not an auth or API problem. Usually transient: retry. ` +
                         'If it persists on a high-latency or broken-IPv6 link, raise the happy-eyeballs budget: NODE_OPTIONS=--network-family-autoselection-attempt-timeout=4000 (server default 2000ms), and check connectivity with curl.'),
-                // Not an override site (C5 is the only kind whose retriable the host
-                // may flip): a multi-tenant host keeps core's retriable codes for
-                // network_error.
+                // Not an override site: a multi-tenant host keeps core's retriable codes for network_error.
                 retriable: RETRIABLE_NET_CODES.has(netCode),
                 account,
             };
         }
     }
-    // A gaxios-shaped error carries `response` or `config`, so the request left
-    // this process. Anything else threw INSIDE the server (a TypeError in a
-    // handler, a missing key), and calling that `upstream_error` blamed Google
-    // for our own bug: an empty messageId used to surface exactly that way.
+    // A gaxios-shaped error means the request left this process; anything else
+    // threw INSIDE the server, and calling that `upstream_error` blamed Google for our own bug.
     if (error?.response !== undefined || error?.config !== undefined) {
         return {
             error: 'upstream_error',

package/dist/tools/_local-files.js

@@ -21,19 +21,15 @@ export function hostFilesRefused(account, what) {
 // path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
 export function prepareLocalDest(savePath, filename) {
     const name = path.basename(filename);
-    // Agents routinely pass the intended FILE path as savePath and repeat the
-    // name in `filename`; a blind join would mkdir a directory named like the
-    // file and bury the download inside it, so strip the duplicated leaf.
+    // Agents routinely repeat the leaf in both savePath and filename; a blind
+    // join would bury the download in a directory named like the file itself.
     const dir = path.basename(savePath) === name ? path.dirname(savePath) : savePath;
     const dest = path.join(dir, name);
     fs.mkdirSync(dir, { recursive: true });
     return dest;
 }
-// fs.createReadStream() reports an unopenable path as an async 'error' EVENT;
-// with no listener attached, that single event kills the whole process — fatal
-// for the shared HTTP transport. Opening the fd first turns the open-failure
-// class (ENOENT/EACCES/...) into a normal rejection the caller's try/catch can
-// map to an error envelope.
+// createReadStream's open failure surfaces as an unhandled 'error' event that
+// kills the process; opening the fd first turns it into a normal rejection.
 export async function openLocalReadStream(localPath) {
     const handle = await fs.promises.open(localPath, 'r');
     // open() succeeds on a directory; fail it here rather than as an async read error.

package/dist/tools/account-wizard.d.ts

@@ -9,8 +9,9 @@ export interface AddForm {
     otherBundles: string;
     admin: boolean;
 }
-/** Every optional bundle (admin is granted via its own checkbox, not here). */
-export declare function allOptionalBundles(): string[];
+/** Every optional bundle (admin is granted via its own checkbox, not here),
+ * less those Google refuses for the account at `email` when one is given. */
+export declare function allOptionalBundles(email?: string): string[];
 /** elicitation/create form schema (flat primitives only, per the MCP spec). */
 export declare function addFormSchema(): Record<string, unknown>;
 export type AddValidation = {
@@ -53,7 +54,7 @@ export declare function argsToAddForm(a: {
 /** Scopes requested by the profile but NOT granted at consent (granular
  * consent / unchecked bundles). Pure. */
 export declare function scopeGrantDiff(requested: string[], grantedScope: string | undefined): string[];
-/** HTTP-transport consent context (S1.20): set by the HTTP bootstrap. When
+/** HTTP-transport consent context: set by the HTTP bootstrap. When
  * present, runConsent NEVER binds a server-side loopback listener — the
  * user's browser cannot reach the daemon's loopback — and instead hands out
  * a clientless AS consent URL. The injector decides the flow (single-owner =

package/dist/tools/account-wizard.js

@@ -3,19 +3,23 @@ import { getAccountSet, invalidateAccountSet, refreshAccountSetIfStale } from '.
 import { ALIAS_RE, mutateConfigFile } from '../config-file.js';
 import { writeToken } from '../token-store.js';
 import { resolveScopesForAccount } from '../auth.js';
-import { BUNDLE_CATALOG, closestBundle, isKnownBundle, resolveBundleAliases } from '../scope-catalog.js';
+import { BUNDLE_CATALOG, closestBundle, isKnownBundle, refusedBundlesFor, resolveBundleAliases } from '../scope-catalog.js';
 import { openUrl } from '../open-url.js';
 import { coerceBoolean } from './_coerce.js';
 import { safeMessage, stringifyEnvelope } from './_errors.js';
 import { buildConsentClient, openLoopbackConsent, hasClientCredentials, TESTING_MODE_WARNING, } from '../oauth-consent.js';
 import { detectClients, buildServerEntry, renderInstruction, applyFileEntry, resolveMode, DEFAULT_SERVER_NAME, } from '../client-config.js';
-// The common optional bundles get their own checkbox (MCP elicitation has no
-// multi-select, so a boolean per bundle IS the checklist); the long tail stays
-// a comma-separated field for power users, and `allBundles` grants every one.
+// Each common bundle gets its own checkbox since MCP elicitation has no
+// multi-select; the long tail stays a comma-separated field, `allBundles` grants all.
 const CHECKBOX_BUNDLES = ['forms', 'chat'];
-/** Every optional bundle (admin is granted via its own checkbox, not here). */
-export function allOptionalBundles() {
-    return Object.keys(BUNDLE_CATALOG).filter((n) => n !== 'admin');
+/** Every optional bundle (admin is granted via its own checkbox, not here),
+ * less those Google refuses for the account at `email` when one is given. */
+export function allOptionalBundles(email) {
+    const all = Object.keys(BUNDLE_CATALOG).filter((n) => n !== 'admin');
+    if (email === undefined)
+        return all;
+    const refused = new Set(refusedBundlesFor(email, all));
+    return all.filter((n) => !refused.has(n));
 }
 /** elicitation/create form schema (flat primitives only, per the MCP spec). */
 export function addFormSchema() {
@@ -48,8 +52,7 @@ export function validateAddForm(input, existingAliases) {
         return { ok: false, slug: 'E_VALIDATION', message: 'Email is required.', hint: "It is used as the Google login hint, so it must be the account's real Google address.", alias };
     }
     if (input.allBundles === true) {
-        // "All optional scopes" supersedes the individual picks.
-        return { ok: true, alias, email, bundles: allOptionalBundles(), admin: input.admin === true };
+        return { ok: true, alias, email, bundles: allOptionalBundles(email), admin: input.admin === true };
     }
     const picked = CHECKBOX_BUNDLES.filter((b) => input[b] === true);
     const rawOther = (input.otherBundles ?? '').split(',').map((s) => s.trim()).filter(Boolean);
@@ -70,6 +73,16 @@ export function validateAddForm(input, existingAliases) {
             };
         }
     }
+    const refused = refusedBundlesFor(email, bundles);
+    if (refused.length > 0) {
+        return {
+            ok: false,
+            slug: 'E_VALIDATION',
+            message: `Google does not let a personal account grant ${refused.map((b) => `"${b}"`).join(', ')}.`,
+            hint: 'Leave it out, or link a Google Workspace account for it.',
+            alias,
+        };
+    }
     return { ok: true, alias, email, bundles, admin: input.admin === true };
 }
 /** URL-mode elicitation params. `elicitationId` is REQUIRED by the spec
@@ -102,8 +115,6 @@ export function scopeGrantDiff(requested, grantedScope) {
     const granted = new Set((grantedScope ?? '').split(' ').filter(Boolean));
     return requested.filter((s) => !granted.has(s));
 }
-/** Persist a new account row (+ a per-account scope profile when bundles/admin
- * were chosen) through the atomic registry mutation path (BR2). */
 function writeAccountRow(alias, email, bundles, admin) {
     mutateConfigFile((current) => {
         const next = { ...current, accounts: { ...(current.accounts ?? {}) } };
@@ -121,9 +132,8 @@ function writeAccountRow(alias, email, bundles, admin) {
 function textResult(text) {
     return { content: [{ type: 'text', text }] };
 }
-/** Wizard failures carry the same envelope as every other tool's, so a client
- * can branch on the slug and metrics can classify them. Success stays prose:
- * it is a human-readable onboarding report, not data. */
+// Errors use the shared envelope so clients can branch on slug; success stays
+// plain prose (a human-readable report, not data).
 function errorResult(slug, message, hint, account) {
     return {
         content: [{ type: 'text', text: stringifyEnvelope({
@@ -140,9 +150,8 @@ let httpConsent = null;
 export function setWizardHttpConsent(ctx) {
     httpConsent = ctx;
 }
-/** Services register their tools at startup, so one first enabled by this
- * account stays unregistered until a restart; say so rather than claim the
- * whole account works without one. */
+// Services register tools at startup: an account's first-enabled service
+// stays unregistered until a restart, so say so rather than claim it just works.
 function restartNote(pending) {
     if (pending.length === 0)
         return '';
@@ -155,9 +164,6 @@ function pendingText(alias, url, pending) {
         `On completion the token is stored server-side and the account is usable immediately — no restart. ` +
         `If the link expires, run account_reauth for a fresh one.${restartNote(pending)}\n${TESTING_MODE_WARNING}`);
 }
-/** Run Google consent for `alias` and persist the token. Opens the browser via
- * URL-mode elicitation when the client supports it, else server-side + prints
- * the URL. Returns the granted-scope diff for the S4 report. */
 async function runConsent(server, alias) {
     const { randomBytes } = await import('node:crypto');
     const cfg = getAccountSet().configs[alias];
@@ -169,9 +175,8 @@ async function runConsent(server, alias) {
             hint: 'Accounts sourced from GOOGLE_ACCOUNTS are not editable here. Run `mcp-google-multi migrate-config` to move them into config.json.',
         };
     }
-    // HTTP transport: consent completes OUT OF BAND at the AS /callback. Never
-    // bind a loopback listener here; try URL-mode elicitation as a convenience
-    // but surface the URL UP FRONT either way (not only on failure).
+    // HTTP: consent completes out-of-band at the AS /callback; never bind a
+    // loopback listener; surface the URL up front, elicitation is just a convenience.
     const http = httpConsent;
     if (http) {
         let url;
@@ -187,14 +192,13 @@ async function runConsent(server, alias) {
                 await server.server.elicitInput(urlElicitationParams(alias, url, randomBytes(16).toString('hex')));
             }
             catch {
-                // the URL in the pending text is the recovery
+                // pending text has the recovery URL
             }
         }
         return { ok: 'pending', url };
     }
-    // Bind the ephemeral loopback listener BEFORE building the auth URL: the
-    // redirect URI needs the assigned port, and listening first means the
-    // callback can't race the browser.
+    // Bind the loopback listener before building the auth URL: the redirect URI
+    // needs the assigned port, and listening first avoids a race with the callback.
     const loop = await openLoopbackConsent();
     const client = buildConsentClient(loop.redirect);
     const expectedState = randomBytes(32).toString('hex');
@@ -207,9 +211,8 @@ async function runConsent(server, alias) {
     let opened = false;
     if (caps?.elicitation?.url !== undefined) {
         try {
-            // elicitationId is REQUIRED by the spec schema; omitting it made every
-            // url-mode request fail client-side validation, so this branch always
-            // fell through to the server-side browser open.
+            // elicitationId is REQUIRED by the spec; omitting it silently fails
+            // client-side validation, falling through to the server-side browser open.
             const r = await server.server.elicitInput(urlElicitationParams(alias, url, randomBytes(16).toString('hex')));
             if (r.action !== 'accept') {
                 loop.close();
@@ -254,9 +257,8 @@ function s4Text(alias, missing, pending) {
 }
 const REQUIRES_INTERACTION = { 'anthropic/requiresUserInteraction': true };
 export function registerAccountWizardTools(registry, server, awaitingRestart = () => []) {
-    // Registered as META (always-visible, like account_list) so onboarding tools
-    // are reachable in lazy mode without discover_all first; registerMeta still
-    // preserves the requiresUserInteraction clientMeta and skips the fan-out path.
+    // Registered as meta (like account_list) so onboarding tools are reachable in
+    // lazy mode without discover_all; this still preserves requiresUserInteraction and skips fan-out.
     const registerMeta = registry.registerMeta;
     registerMeta('account_add', {
         _meta: REQUIRES_INTERACTION,
@@ -272,18 +274,16 @@ export function registerAccountWizardTools(registry, server, awaitingRestart = (
         },
     }, async (args) => {
         try {
-            // Env-sourced registry: GOOGLE_ACCOUNTS is the exclusive source and
-            // config.json accounts are ignored, so a wizard add would be a phantom
-            // write. Refuse up front (BR-10) rather than write a row nothing reads.
+            // GOOGLE_ACCOUNTS is the exclusive registry source when set; config.json
+            // is ignored, so refuse here rather than write a row nothing reads.
             if (process.env.GOOGLE_ACCOUNTS?.trim()) {
                 return errorResult('E_ENV_ACCOUNTS_MODE', 'Accounts are defined by the GOOGLE_ACCOUNTS environment variable, so a new account cannot be added interactively: config.json is ignored while it is set, and the row would be written where nothing reads it.', 'Either add the alias to GOOGLE_ACCOUNTS and run account_reauth, or run `mcp-google-multi migrate-config` to move accounts into config.json and unset GOOGLE_ACCOUNTS.');
             }
             if (!hasClientCredentials()) {
                 return errorResult('invalid_client', 'GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are not set, so there is no OAuth client to run consent against.', 'Run the `setup` prompt (/mcp__google-multi__setup) to create an OAuth client, then set them. See docs/google-cloud-setup.md.');
             }
-            // S1: collect the registry row. Arguments win over the form so the
-            // wizard still works in clients without form elicitation (where the
-            // interactive path used to dead-end).
+            // Arguments win over the form so the wizard still works for clients
+            // without form elicitation support.
             const a = (args ?? {});
             let input;
             if (a.alias?.trim() || a.account?.trim() || a.email?.trim()) {
@@ -304,25 +304,22 @@ export function registerAccountWizardTools(registry, server, awaitingRestart = (
             const validated = validateAddForm(input, getAccountSet().aliases);
             if (!validated.ok)
                 return errorResult(validated.slug, validated.message, validated.hint, validated.alias);
-            // S2: atomic write + make the alias callable without a restart (BR3).
+            // Atomic write + make the alias callable without a restart.
             writeAccountRow(validated.alias, validated.email, validated.bundles, validated.admin);
             invalidateAccountSet();
-            // Live account args validate against the refreshed registry already;
-            // the list_changed nudge makes clients re-fetch tools/list, where the
-            // advertised account enums are rebuilt from the live set.
+            // Account args already validate against the refreshed registry; the
+            // nudge just gets clients to re-fetch tools/list for the new account enum.
             try {
                 server.sendToolListChanged();
             }
             catch {
-                // a client that cannot receive notifications loses nothing but the nudge
+                // harmless if unsupported
             }
-            // S3 + S4: consent + validate.
             const consent = await runConsent(server, validated.alias);
             if (consent.ok === 'pending')
                 return textResult(pendingText(validated.alias, consent.url, awaitingRestart()));
             if (!consent.ok)
                 return errorResult(consent.slug, consent.message, consent.hint, validated.alias);
-            // B15: offer to register the server with another MCP client.
             return textResult(`${s4Text(validated.alias, consent.missing, awaitingRestart())}\nTip: run account_write_config to register this server with another MCP client (Claude Desktop / Cursor / Claude Code).`);
         }
         catch (e) {
@@ -339,10 +336,8 @@ export function registerAccountWizardTools(registry, server, awaitingRestart = (
             // Plain string (NOT the account enum) so this never joins the
             // multi-account fan-out path; validated against the registry below.
             alias: z.string().min(1).optional().describe('Existing account alias to re-authenticate'),
-            // Every other tool in the server spells this `account`, so that is
-            // what a caller reaches for. Accepting both removes a dead end that
-            // no did-you-mean can rescue: `account` is 5 edits from `alias`, so
-            // the matcher cannot bridge them.
+            // Every other tool spells this `account`; accepting both avoids a dead
+            // end no did-you-mean can bridge (too many edits from `alias`).
             account: z.string().min(1).optional().describe('Alias of the account to re-authenticate (same as `alias`)'),
         },
     }, async (args) => {
@@ -391,7 +386,7 @@ export function registerAccountWizardTools(registry, server, awaitingRestart = (
                 resourceUri = m.resourceUri;
             }
             catch {
-                // stdio fallback on any config error
+                // fallback to stdio on error
             }
             let entry;
             try {
@@ -412,9 +407,8 @@ export function registerAccountWizardTools(registry, server, awaitingRestart = (
                     blocks.push(`${client.label}: run\n  ${instr.text}`);
                 }
                 else if (a.write && mode === 'http') {
-                    // Over HTTP this tool runs on the DAEMON, whose homedir is not the
-                    // caller's machine: write:true would edit the operator's own client
-                    // configs (a cross-tenant hazard under tenancy). Snippet only.
+                    // Over HTTP this runs on the daemon, not the caller's machine: write:true
+                    // would edit the operator's own client configs (a tenancy hazard), so snippet only.
                     blocks.push(`${client.label}: write:true is ignored over HTTP — this tool runs on the server, not your machine. Add to ${instr.path}\n${instr.text}`);
                 }
                 else if (a.write) {

package/dist/tools/accounts-tool.d.ts

@@ -12,7 +12,7 @@ export interface AccountHealthDeps {
     fileExists: (p: string) => boolean;
     now: () => number;
     /** Scopes required by registered tools — feeds doctor's tool-grained
-     * "registered but not requestable" view (B9). account_list stays compact:
+     * "registered but not requestable" view. account_list stays compact:
      * its report universe is profile ∪ granted only. */
     registeredScopes?: () => string[];
     /** Account view health is derived against; absent = the global registry. */

package/dist/tools/accounts-tool.js

@@ -22,7 +22,7 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
     const config = set.configs[alias];
     const admin = getAdminAccounts(set).includes(alias);
     const configured = resolveScopesForAccount(alias, set);
-    // BR-10: env-sourced accounts are not persisted in config.json, so the
+    // Env-sourced accounts are not persisted in config.json, so the
     // account wizard cannot edit them — the deployer edits env instead.
     const base = {
         alias,

package/dist/tools/admin.js

@@ -6,9 +6,8 @@ import { getClient } from '../client.js';
 import { handleGoogleApiError, invalidParams } from './_errors.js';
 // Admin SDK requires Workspace super-admin (or delegated admin) on the account — personal @gmail.com accounts 403 on every endpoint.
 export function registerAdminTools(server, deps = {}) {
-    // Per-registry, LIVE account enum + injectable client (S1.10): the
-    // schema follows the registry's account view at parse time, and the
-    // custody path is the context's, not the process global.
+    // Per-registry, live account enum + injectable client: the schema follows
+    // the registry's account view at parse time, not a process-global default.
     const accountEnum = accountArgLive(() => server.accountAliases()).optional();
     const getClientFn = deps.getClientFn ?? getClient;
     // ─── Reports / audit log ───────────────────────────────────────────────

package/dist/tools/analytics.js

@@ -105,9 +105,8 @@ const propertySchema = z
     .string()
     .describe('GA4 property: numeric ID like "213025502" or "properties/213025502" — NOT a "G-..." measurement ID and not "UA-...". Find yours with analytics_account_summaries.');
 export function registerAnalyticsTools(server, deps = {}) {
-    // Per-registry, LIVE account enum + injectable client (S1.10): the
-    // schema follows the registry's account view at parse time, and the
-    // custody path is the context's, not the process global.
+    // Per-registry, live account enum + injectable client: the schema follows
+    // the registry's account view at parse time, not a process-global default.
     const accountEnum = accountArgLive(() => server.accountAliases()).optional();
     const getClientFn = deps.getClientFn ?? getClient;
     server.registerTool('analytics_account_summaries', {
@@ -281,8 +280,8 @@ function invalidProperty(hint, account) {
 export function handleAnalyticsError(error, account) {
     return handleGoogleApiError(error, account, {
         scope: 'Needs the "analytics" bundle on this account: add it to the scope profile, then re-auth.',
-        // GA4 answers PERMISSION_DENIED for a property ACL too, and the old
-        // combined hint sent those callers to re-auth a scope they already had.
+        // GA4 returns PERMISSION_DENIED for a property-access issue too, not just
+        // a missing scope; keep the hints distinct, or callers get sent to re-auth a scope they already have.
         resource: 'The scope is not the problem: this Google account has no access to that GA4 property. Grant it in GA4 Admin > Property Access Management, or call analytics_account_summaries to see the properties it can read.',
         bundle: 'analytics',
     });

package/dist/tools/calendar.js

@@ -7,9 +7,8 @@ import { checkOutbound } from '../outbound-allowlist.js';
 import { handleGoogleApiError, invalidParams } from './_errors.js';
 import { listResult, sliceClean } from '../trim.js';
 export function registerCalendarTools(server, deps = {}) {
-    // Per-registry, LIVE account enum + injectable client (S1.10): the
-    // schema follows the registry's account view at parse time, and the
-    // custody path is the context's, not the process global.
+    // Per-registry, live account enum + injectable client: the schema follows
+    // the registry's account view at parse time, not a process-global default.
     const accountEnum = accountArgLive(() => server.accountAliases()).optional();
     const getClientFn = deps.getClientFn ?? getClient;
     server.registerTool('calendar_list_calendars', {
@@ -382,10 +381,8 @@ export function registerCalendarTools(server, deps = {}) {
                 },
             });
             return {
-                // freebusy answers 200 with NO `calendars` key on an empty items
-                // list, and JSON.stringify(undefined) returns undefined, not a
-                // string: the SDK then rejected our own result with -32602. The
-                // value is a map keyed by calendar id, so the fallback is {}.
+                // Empty items returns 200 with no `calendars` key; JSON.stringify(undefined)
+                // would make the SDK reject our own result, so fall back to {}.
                 content: [{ type: 'text', text: JSON.stringify(res.data.calendars ?? {}, null, 2) }],
             };
         }

package/dist/tools/chat.js

@@ -5,9 +5,8 @@ import { accountArgLive } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError, invalidParams } from './_errors.js';
 export function registerChatTools(server, deps = {}) {
-    // Per-registry, LIVE account enum + injectable client (S1.10): the
-    // schema follows the registry's account view at parse time, and the
-    // custody path is the context's, not the process global.
+    // Per-registry, live account enum + injectable client: the schema follows
+    // the registry's account view at parse time, not a process-global default.
     const accountEnum = accountArgLive(() => server.accountAliases()).optional();
     const getClientFn = deps.getClientFn ?? getClient;
     server.registerTool('chat_spaces_list', {

package/dist/tools/contacts.js

@@ -34,7 +34,7 @@ function formatContact(person) {
         photo: person.photos?.[0]?.url ?? '',
     };
 }
-/** Accent-fold + lowercase for name comparison ("Rym" == "Rÿm"). */
+/** Accent-fold + lowercase for name comparison ("Zoe" == "Zoë"). */
 const foldName = (s) => s.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLowerCase().trim();
 /** Canonical-address preference within one contact: explicit primary, then
  * People type order work > home > other. */
@@ -52,7 +52,7 @@ function pickEmail(c) {
     return [...c.emails].sort((a, b) => emailRank(b) - emailRank(a))[0];
 }
 /** Deterministic rank tuple; higher wins, compared lexicographically so the
- * first discriminating rule decides (A10 tie-break table). */
+ * first discriminating rule decides. */
 function scoreTuple(c, foldedQuery) {
     const exact = foldName(c.displayName) === foldedQuery ? 1 : 0; // 1. exact over prefix
     const saved = c.source === 'contacts' ? 1 : 0; // 2. saved over other-contact
@@ -123,9 +123,8 @@ function dedupeCandidates(list) {
     return [...byResource.values()];
 }
 export function registerContactsTools(server, deps = {}) {
-    // Per-registry, LIVE account enum + injectable client (S1.10): the
-    // schema follows the registry's account view at parse time, and the
-    // custody path is the context's, not the process global.
+    // Per-registry, live account enum + injectable client: the schema follows
+    // the registry's account view at parse time, not a process-global default.
     const accountEnum = accountArgLive(() => server.accountAliases()).optional();
     const getClientFn = deps.getClientFn ?? getClient;
     server.registerTool('contacts_search', {
@@ -170,7 +169,7 @@ export function registerContactsTools(server, deps = {}) {
         description: 'Resolve a free-text name/alias to ONE canonical email address (ranked + tie-broken), so you need not hand-expand transliteration OR-queries. Returns a single confident match, an explicit ambiguous candidate list, or null when nothing matches. For picking a recipient before gmail_send.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            name: z.string().min(1).describe('Free-text name or alias to resolve (e.g. "Rym")'),
+            name: z.string().min(1).describe('Free-text name or alias to resolve (e.g. "Zoe")'),
             maxCandidates: z.number().min(1).max(10).default(5).optional()
                 .describe('Max candidates to return when ambiguous (1-10, default: 5)'),
             includeOtherContacts: coerceBoolean.optional()
@@ -197,7 +196,7 @@ export function registerContactsTools(server, deps = {}) {
                     candidates.push(...(other.data.results ?? []).map((r) => toCandidate(r.person, 'otherContacts')));
                 }
                 catch {
-                    // otherContacts unavailable (scope/5xx): degrade to saved-contacts only.
+                    // otherContacts unavailable: degrade silently
                 }
             }
             const result = resolveContacts(dedupeCandidates(candidates), name, maxCandidates ?? 5);
@@ -453,8 +452,8 @@ export function registerContactsTools(server, deps = {}) {
             const members = [];
             let fetchFailures = 0;
             let firstError;
-            // getBatchGet caps at 200 names while maxMembers goes to 1000, so a
-            // large group used to fail outright rather than come back in pages.
+            // getBatchGet caps at 200 names while maxMembers goes to 1000, so fetch
+            // in chunks rather than fail outright on a large group.
             for (let i = 0; i < memberResourceNames.length; i += BATCH_GET_LIMIT) {
                 const chunk = memberResourceNames.slice(i, i + BATCH_GET_LIMIT);
                 try {

package/dist/tools/docs.js

@@ -5,12 +5,8 @@ import { accountArgLive } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError, invalidParams } from './_errors.js';
 import { capText } from '../trim.js';
-// A single very large insertText has been observed to apply only partially while
-// the request still returns success, silently dropping the tail. Split a large
-// insert into bounded pieces sent as sequential insertText requests in one atomic
-// batchUpdate: small inserts keep the exact single-request path, and a large one
-// can no longer be silently truncated. Docs indices are UTF-16 code units (= JS
-// string length), so index math advances by `.length`; never split a surrogate pair.
+// A single large insertText can silently apply only partially despite returning
+// success; split into <=DOCS_INSERT_CHUNK sequential inserts in one atomic batchUpdate (UTF-16-safe, no split surrogate pairs).
 export const DOCS_INSERT_CHUNK = 5000;
 export function splitInsertText(text, maxLen = DOCS_INSERT_CHUNK) {
     if (text.length === 0)
@@ -170,9 +166,8 @@ export function listTabs(tabs) {
     return out;
 }
 export function registerDocsTools(server, deps = {}) {
-    // Per-registry, LIVE account enum + injectable client (S1.10): the
-    // schema follows the registry's account view at parse time, and the
-    // custody path is the context's, not the process global.
+    // Per-registry, live account enum + injectable client: the schema follows
+    // the registry's account view at parse time, not a process-global default.
     const accountEnum = accountArgLive(() => server.accountAliases()).optional();
     const getClientFn = deps.getClientFn ?? getClient;
     server.registerTool('docs_create', {