mcp-google-multi 6.0.0-alpha.9 → 6.0.0-beta.2

package/dist/arg-strict.js

@@ -0,0 +1,163 @@
+// Unknown-argument screening (backlog item 14). zod strips undeclared keys
+// before a handler runs, so a misremembered argument name used to produce a
+// SUCCESS response with wrong behavior: `parentId` on drive_create_folder was
+// dropped and the folder landed in My Drive root. Field-reported, then
+// reproduced: the typo, the correct name and a wholly invented key all
+// returned byte-identical responses.
+//
+// This module is pure and holds no registry reference. It never rewrites a key
+// and never touches a VALUE: it only decides that a key is undeclared, and
+// suggests what the caller probably meant. Rewriting would risk sending a real
+// value to Google on a guess, which is strictly worse than refusing.
+import { editDistance } from './scope-catalog.js';
+/**
+ * `GOOGLE_ARG_UNKNOWN`: reject | warn | off. A typo in the VALUE still falls
+ * back to `warn`, not to the default: an operator who misspells the setting
+ * has said nothing about which behavior they want, and guessing the strict
+ * one would turn a config typo into failing tool calls.
+ */
+export function unknownArgMode(env = process.env) {
+    const raw = (env.GOOGLE_ARG_UNKNOWN ?? '').trim().toLowerCase();
+    if (raw === '')
+        return DEFAULT_MODE;
+    if (raw === 'reject' || raw === 'warn' || raw === 'off')
+        return raw;
+    process.stderr.write(`GOOGLE_ARG_UNKNOWN="${raw}" is not valid (reject | warn | off); using warn\n`);
+    return 'warn';
+}
+// The staged rollout is over: `warn` shipped first as pure observability, and
+// this is the flip it was staging for. An undeclared argument is dropped by
+// zod before the handler runs, so `warn` means the CLIENT sees a confident
+// success for a call the server did not perform: drive_list with a misspelled
+// folder key returned the My Drive root, byte-identical to no argument at all.
+// A wrong answer that reads as right is the failure mode agents recover from
+// worst, so the default refuses the call and says what it probably meant.
+const DEFAULT_MODE = 'reject';
+/** Tools that legitimately accept open-ended top-level keys. Empty at 6.0.0:
+ * the escape hatch is NOT one, because its open-endedness lives in the VALUES
+ * of queryParams/body, never in its six fixed top-level keys. */
+export const STRICT_EXEMPT_TOOLS = new Set();
+/** Keys a CLIENT adds on its own, not keys the model chose. `random_string`
+ * is the long-standing probe some clients send to a tool they read as taking
+ * no arguments; the others are call-plumbing that bridges and proxies have
+ * been observed to fold into `arguments` instead of `params._meta`, where the
+ * spec puts them. Rejecting these would fail a call the model got right.
+ * Measured against the full 978-tool surface: none is a declared key. */
+const CLIENT_ARTIFACT_KEYS = new Set([
+    'random_string',
+    'toolCallId',
+    'tool_call_id',
+    'tool_call_description',
+]);
+/** Metadata a client may legitimately attach. Measured against all registered
+ * tools: no declared key starts with `_` or contains `/`, so neither rule can
+ * shadow a real parameter. */
+export function isExemptKey(key) {
+    return key.startsWith('_') || key.includes('/') || CLIENT_ARTIFACT_KEYS.has(key);
+}
+/** Generic words that must never be offered as a suggestion on containment
+ * alone; they match far too much to be useful. */
+const GENERIC = new Set(['id', 'name', 'title', 'body', 'parent', 'text', 'content', 'type', 'value', 'key', 'data']);
+const flatten = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+function tokens(s) {
+    return s
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[\s_\-.]+/)
+        .map((t) => t.toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * Rank declared keys for an unknown key. Tiers, best non-empty tier wins:
+ *   0 same key modulo case and separators
+ *   1 every token of the unknown key appears in the declared key
+ *   2 substring containment of the flattened forms
+ *   3 a genuine typo by edit distance
+ * Plain edit distance alone cannot carry this: parentid -> parentfolderid is
+ * distance 6, well past any sane threshold, which is why tier 1 exists.
+ */
+export function suggestKeys(unknown, declared, limit = 2) {
+    const uFlat = flatten(unknown);
+    const uTok = tokens(unknown);
+    const tiers = [[], [], [], []];
+    for (const key of declared) {
+        const kFlat = flatten(key);
+        const kTok = tokens(key);
+        if (kFlat === uFlat) {
+            tiers[0].push({ key, rank: 0 });
+            continue;
+        }
+        if (uTok.length >= 2 && uTok.every((t) => kTok.includes(t))) {
+            tiers[1].push({ key, rank: Math.abs(kTok.length - uTok.length) });
+            continue;
+        }
+        if (uFlat.length >= 4 && !GENERIC.has(kFlat) && (kFlat.includes(uFlat) || uFlat.includes(kFlat))) {
+            tiers[2].push({ key, rank: Math.abs(kFlat.length - uFlat.length) });
+            continue;
+        }
+        const d = editDistance(uFlat, kFlat);
+        if (d <= Math.max(1, Math.floor(uFlat.length / 4)))
+            tiers[3].push({ key, rank: d });
+    }
+    const tier = tiers.find((t) => t.length > 0);
+    if (!tier)
+        return [];
+    // Stable: declaration order breaks rank ties.
+    return tier
+        .map((e, i) => ({ ...e, i }))
+        .sort((a, b) => a.rank - b.rank || a.i - b.i)
+        .slice(0, limit)
+        .map((e) => e.key);
+}
+/**
+ * Split a call's post-rename keys into declared, redundant-duplicate and
+ * genuinely unknown. `declared` is the tool's full declared key list.
+ */
+export function screenArguments(tool, args, declared) {
+    const out = { unknown: [], redundant: [] };
+    if (STRICT_EXEMPT_TOOLS.has(tool) || declared.length === 0)
+        return out;
+    const declaredSet = new Set(declared);
+    for (const key of Object.keys(args)) {
+        if (declaredSet.has(key) || isExemptKey(key))
+            continue;
+        const suggestions = suggestKeys(key, declared);
+        // The caller sent both spellings, so the declared one already won and the
+        // outcome is what it has always been. Never fail a call that works today.
+        if (suggestions.some((s) => s in args)) {
+            out.redundant.push(key);
+            continue;
+        }
+        out.unknown.push({ sent: key, suggestions });
+    }
+    return out;
+}
+/** The agent-facing envelope. Values are never included, only key names. */
+export function unknownArgEnvelope(tool, unknown, declared, account, siblings = []) {
+    const names = unknown.map((u) => `"${u.sent}"`).join(', ');
+    const accepts = `This tool accepts: ${declared.join(', ')}.`;
+    const suggested = unknown.flatMap((u) => u.suggestions);
+    let hint;
+    if (suggested.length > 0) {
+        const did = unknown
+            .filter((u) => u.suggestions.length > 0)
+            .map((u) => u.suggestions.map((s) => `"${s}"`).join(' or '))
+            .join(', ');
+        hint = `Did you mean ${did}? ${accepts}`;
+    }
+    else if (siblings.length > 0) {
+        const spelled = siblings
+            .map((s) => `"${s.key}" (${s.tools.slice(0, 3).join(', ')})`)
+            .join(' and ');
+        hint = `${accepts} Other tools in this service spell a similar argument ${spelled}.`;
+    }
+    else {
+        hint = accepts;
+    }
+    return {
+        error: 'unknown_argument',
+        message: `${tool} does not accept ${names}. Nothing was sent to Google.`,
+        hint,
+        retriable: false,
+        ...(account !== undefined ? { account } : {}),
+    };
+}

package/dist/auth.js

@@ -1,12 +1,10 @@
-import { OAuth2Client } from 'googleapis-common';
-import http from 'node:http';
-import { URL } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { openUrl } from './open-url.js';
 import { ACCOUNTS, getAccountSet } from './accounts.js';
 import { ADMIN_SCOPES, BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
 import { resolveMasterKey } from './master-key.js';
 import { writeToken } from './token-store.js';
+import { buildConsentClient, openLoopbackConsent, TESTING_MODE_WARNING } from './oauth-consent.js';
 // Personal (non-Workspace) accounts 403 on admin scopes; ADMIN_SCOPES stays per-account opt-in, never granted by default.
 export const BASE_SCOPES = [
     'https://www.googleapis.com/auth/gmail.modify',
@@ -134,7 +132,11 @@ export async function runAuthFlow(args) {
     // Auto-provisions on a fresh install (env > keychain > file > generate);
     // resolves eagerly so a provisioning failure surfaces before the browser opens.
     resolveMasterKey();
-    const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
+    // Shared ephemeral-port loopback flow (oauth-consent.ts): listen first, then
+    // build the auth URL from the assigned redirect. CLI gets a patient timeout;
+    // errors propagate to main()'s fatal handler like every other CLI failure.
+    const loop = await openLoopbackConsent({ timeoutMs: 10 * 60_000 });
+    const oauth2Client = buildConsentClient(loop.redirect);
     // CSRF protection for the OAuth callback (RFC 6749 §10.12).
     const expectedState = randomBytes(32).toString('hex');
     const authorizeUrl = oauth2Client.generateAuthUrl({
@@ -149,72 +151,13 @@ export async function runAuthFlow(args) {
     if (getAdminAccounts().includes(alias)) {
         console.log('  ⚠ Admin scopes included — this account will be granted Workspace admin access.');
     }
-    console.log(`Opening browser for authorization...`);
-    return new Promise((resolve, reject) => {
-        const server = http
-            .createServer(async (req, res) => {
-            try {
-                if (req.url && req.url.startsWith('/oauth2callback')) {
-                    const qs = new URL(req.url, 'http://localhost:4242').searchParams;
-                    const error = qs.get('error');
-                    if (error) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end(`Authorization denied: ${error}`);
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error(`Authorization denied: ${error}`));
-                        return;
-                    }
-                    const code = qs.get('code');
-                    if (!code) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end('No authorization code received.');
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error('No authorization code received'));
-                        return;
-                    }
-                    const returnedState = qs.get('state');
-                    if (returnedState !== expectedState) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end('State mismatch — possible CSRF attempt. Aborting.');
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error('OAuth state token mismatch'));
-                        return;
-                    }
-                    const { tokens } = await oauth2Client.getToken(code);
-                    writeToken(alias, tokens);
-                    res.writeHead(200, { 'Content-Type': 'text/html' });
-                    res.end('<h2>Authentication successful!</h2><p>You can close this tab.</p>');
-                    server.close();
-                    server.closeAllConnections();
-                    console.log(`Token saved (encrypted) for ${alias}.`);
-                    console.log('Next: authenticate your other aliases, then verify with: mcp-google-multi config check');
-                    resolve();
-                }
-            }
-            catch (e) {
-                res.writeHead(500, { 'Content-Type': 'text/plain' });
-                res.end('Internal error during authentication.');
-                server.close();
-                server.closeAllConnections();
-                reject(e);
-            }
-        })
-            // Bind to loopback only — never expose the OAuth callback to the local network.
-            .listen(4242, '127.0.0.1', () => {
-            // Always print the URL first: the browser launch is best-effort and
-            // silently does nothing on headless/SSH sessions.
-            console.log(`Opening your browser to authorize "${alias}". If nothing opens, visit:\n${authorizeUrl}`);
-            openUrl(authorizeUrl);
-        });
-        server.on('error', (err) => {
-            if (err.code === 'EADDRINUSE') {
-                console.error('Port 4242 is already in use. Close the process using it and retry.');
-                process.exit(1);
-            }
-            reject(err);
-        });
-    });
+    // Always print the URL first: the browser launch is best-effort and
+    // silently does nothing on headless/SSH sessions.
+    console.log(`Opening your browser to authorize "${alias}". If nothing opens, visit:\n${authorizeUrl}`);
+    openUrl(authorizeUrl);
+    const tokens = await loop.finish(oauth2Client, expectedState);
+    writeToken(alias, tokens);
+    console.log(`Token saved (encrypted) for ${alias}.`);
+    console.log(TESTING_MODE_WARNING);
+    console.log('Next: authenticate your other aliases, then verify with: mcp-google-multi config check');
 }

package/dist/client.js

@@ -2,22 +2,32 @@ import { OAuth2Client } from 'googleapis-common';
 import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
 import { readToken, updateToken } from './token-store.js';
 import { reauthHint } from './reauth-hint.js';
+/** A local precondition failure, carrying a code the error mapper classifies
+ * on. Without it these land on the generic floor and read as Google errors. */
+function tagged(message, code) {
+    return Object.assign(new Error(message), { code });
+}
 export async function getClient(account) {
     // BR-7: lazy cross-process reload — one stat per dispatch, no watcher;
     // reload failures keep the last-good registry, never kill the server.
     refreshAccountSetIfStale();
     const config = getAccountSet().configs[account];
     if (!config) {
-        throw new Error(`Unknown account "${account}". Valid aliases: ${getAccountSet().aliases.join(', ')}`);
+        // Tagged so mapGoogleError can classify it. Untagged, a caller's typo in
+        // an alias came back as `upstream_error` with "Unclassified error", i.e.
+        // the server blaming Google for a local argument mistake.
+        throw tagged(`Unknown account "${account}". Valid aliases: ${getAccountSet().aliases.join(', ')}`, 'E_UNKNOWN_ACCOUNT');
     }
     if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
-        throw new Error('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
-            'Check that .env exists in the project root or pass them as env vars.');
+        throw tagged('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
+            'Check that .env exists in the project root or pass them as env vars.', 'E_NO_OAUTH_CLIENT');
     }
-    const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
+    // Redirect URI is unused on the refresh-token grant; consent flows bind an
+    // ephemeral loopback port at auth time (oauth-consent.ts).
+    const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost/oauth2callback');
     const tokenData = readToken(account);
     if (!tokenData) {
-        throw new Error(`No token found for account "${account}" (${config.email}). ${reauthHint(account)}`);
+        throw tagged(`No token found for account "${account}" (${config.email}). ${reauthHint(account)}`, 'E_NO_TOKEN');
     }
     oauth2Client.setCredentials(tokenData);
     oauth2Client.on('tokens', (tokens) => {

package/dist/config-file.d.ts

@@ -17,6 +17,7 @@ export interface ConfigFile {
     defaultAccount?: string;
     discovery?: 'lazy' | 'curated' | 'eager';
     toolsets?: string;
+    usageMetrics?: boolean;
 }
 export declare function failStartup(slug: string, message: string): never;
 export declare class ConfigFileError extends Error {

package/dist/config-file.js

@@ -36,6 +36,10 @@ const configSchema = z.strictObject({
     defaultAccount: z.string().optional(),
     discovery: z.enum(['lazy', 'curated', 'eager']).optional(),
     toolsets: z.string().optional(),
+    // Local usage metrics (metrics-feature-spec): absent = off. Downgrade rule:
+    // a pre-6.0 build reading a config carrying this key fails E_CONFIG_INVALID
+    // (strictObject); remove the key first.
+    usageMetrics: z.boolean().optional(),
 });
 export function failStartup(slug, message) {
     process.stderr.write(`${slug}: ${message}\n`);

package/dist/discover.js

@@ -1,8 +1,32 @@
 import { z } from 'zod';
 import { describePolicy } from './write-control.js';
+// The description budget is the whole point of lazy mode: a full op list per
+// service put lazy tools/list at ~11.5k tokens (RQ2), so descriptions carry a
+// CAPPED vocabulary and the complete catalog stays in this tool's RESULT.
+const CURATED_OPS_CAP = 10;
+const GENERATED_GROUPS_CAP = 6;
 function opVocabulary(registry, service) {
-    const ops = registry.catalog(service).map((o) => o.tool.startsWith(`${service}_`) ? o.tool.slice(service.length + 1) : o.tool);
-    return [...new Set(ops)].join(', ');
+    const { curated, generated } = registry.opNames(service);
+    const parts = [];
+    if (curated.length > 0) {
+        const shown = curated.slice(0, CURATED_OPS_CAP);
+        const more = curated.length - shown.length;
+        parts.push(`${shown.join(', ')}${more > 0 ? ` +${more} more` : ''}`);
+    }
+    if (generated.length > 0) {
+        // The generated long tail compresses to its resource groups: denser and
+        // more selective than any truncated name list.
+        const counts = new Map();
+        for (const op of generated) {
+            const group = op.split('_')[0];
+            counts.set(group, (counts.get(group) ?? 0) + 1);
+        }
+        const groups = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+        const shown = groups.slice(0, GENERATED_GROUPS_CAP).map(([g]) => g);
+        const more = groups.length - shown.length;
+        parts.push(`${generated.length} generated ops: ${shown.join(', ')}${more > 0 ? ` +${more} areas` : ''}`);
+    }
+    return parts.join('; ');
 }
 export function registerDiscoverTools(registry, policy) {
     const registerMeta = registry.registerMeta;
@@ -11,9 +35,8 @@ export function registerDiscoverTools(registry, policy) {
     // name/schema context budget after. stdio-only semantics — over stateless
     // HTTP the mode is forced curated and these are no-ops.
     registerMeta('discover_all', {
-        description: 'Reveal ALL curated Google tools at once (instead of per-service discovery). ' +
-            'Use when starting substantial Google work so the shaped, high-quality tools are ' +
-            'directly callable; prefer them over google_api_call. Pair with discover_reset when done.',
+        description: 'Reveal ALL curated Google tools at once (instead of per-service discovery). Use when ' +
+            'starting substantial Google work; prefer these over google_api_call. Pair with discover_reset.',
         inputSchema: {},
         _meta: { 'anthropic/alwaysLoad': true },
     }, async () => {
@@ -35,9 +58,8 @@ export function registerDiscoverTools(registry, policy) {
         };
     });
     registerMeta('discover_reset', {
-        description: 'Collapse the tool surface back to the configured default (lean meta-tools-only under the ' +
-            'default lazy mode), reclaiming context budget after heavy Google work. All tools remain ' +
-            'callable by name after collapsing.',
+        description: 'Collapse the tool surface back to the configured default, reclaiming context budget ' +
+            'after heavy Google work. All tools remain callable by name after collapsing.',
         inputSchema: {},
         _meta: { 'anthropic/alwaysLoad': true },
     }, async () => {
@@ -58,13 +80,12 @@ export function registerDiscoverTools(registry, policy) {
     });
     for (const service of registry.services()) {
         registerMeta(`${service}_discover`, {
-            description: `List the available ${service} operations. ` +
-                (registry.mode === 'lazy'
-                    ? `Operational ${service} tools are hidden until discovered — call this first, then call the tool you need by name. `
-                    : `Returns the ${service} catalog (and reveals any still-hidden ${service} tools). `) +
-                `Operations: ${opVocabulary(registry, service)}.`,
+            description: (registry.mode === 'lazy'
+                ? `Discover ${service}: lists the catalog and reveals its hidden tools; call first, then call the tool by name. `
+                : `List the ${service} catalog (reveals any still-hidden ${service} tools). `) +
+                `Ops: ${opVocabulary(registry, service)}.`,
             inputSchema: {
-                query: z.string().optional().describe('Keyword to filter the returned operations'),
+                query: z.string().optional().describe('Filter keyword'),
             },
             _meta: { 'anthropic/alwaysLoad': true },
         }, async ({ query }) => {

package/dist/discovery-client.d.ts

@@ -1,7 +1,14 @@
-export declare const WORKSPACE_APIS: Record<string, {
+export declare const SUPPORTED_APIS: Record<string, {
     id: string;
     version: string;
 }>;
+export declare const API_ALIASES: Record<string, string[]>;
+/**
+ * Resolve an `api` argument to real SUPPORTED_APIS keys: exact match, then
+ * case/punctuation-normalized ("Search-Console" -> searchconsole), then the
+ * alias map. null = genuinely unknown.
+ */
+export declare function resolveApiAliases(api: string): string[] | null;
 export interface DiscoveryParam {
     location: 'path' | 'query';
     required?: boolean;

package/dist/discovery-client.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-export const WORKSPACE_APIS = {
+export const SUPPORTED_APIS = {
     gmail: { id: 'gmail', version: 'v1' },
     drive: { id: 'drive', version: 'v3' },
     calendar: { id: 'calendar', version: 'v3' },
@@ -20,6 +20,8 @@ export const WORKSPACE_APIS = {
     admin_reports: { id: 'admin', version: 'reports_v1' },
     admin_datatransfer: { id: 'admin', version: 'datatransfer_v1' },
     groupssettings: { id: 'groupssettings', version: 'v1' },
+    analyticsadmin: { id: 'analyticsadmin', version: 'v1beta' },
+    analyticsdata: { id: 'analyticsdata', version: 'v1beta' },
     appsmarket: { id: 'appsmarket', version: 'v2' },
     classroom: { id: 'classroom', version: 'v1' },
     cloudidentity: { id: 'cloudidentity', version: 'v1' },
@@ -33,6 +35,38 @@ export const WORKSPACE_APIS = {
     vault: { id: 'vault', version: 'v1' },
     workspaceevents: { id: 'workspaceevents', version: 'v1' },
 };
+// Names agents actually type for an API, mapped to real SUPPORTED_APIS keys.
+// Motivated by observed escape-hatch misses ("analytics" is two Discovery
+// APIs, the Admin SDK is three); keep entries plural-target only when the
+// split is real.
+export const API_ALIASES = {
+    analytics: ['analyticsadmin', 'analyticsdata'],
+    ga4: ['analyticsadmin', 'analyticsdata'],
+    googleanalytics: ['analyticsadmin', 'analyticsdata'],
+    admin: ['admin_directory', 'admin_reports', 'admin_datatransfer'],
+    adminsdk: ['admin_directory', 'admin_reports', 'admin_datatransfer'],
+    directory: ['admin_directory'],
+    webmasters: ['searchconsole'],
+    gsc: ['searchconsole'],
+    contacts: ['people'],
+    appsscript: ['script'],
+    appscript: ['script'],
+    gmailpostmastertools: ['postmaster'],
+};
+/**
+ * Resolve an `api` argument to real SUPPORTED_APIS keys: exact match, then
+ * case/punctuation-normalized ("Search-Console" -> searchconsole), then the
+ * alias map. null = genuinely unknown.
+ */
+export function resolveApiAliases(api) {
+    if (SUPPORTED_APIS[api])
+        return [api];
+    const norm = api.trim().toLowerCase().replace(/[^a-z0-9]/g, '');
+    const direct = Object.keys(SUPPORTED_APIS).find((k) => k.replace(/[^a-z0-9]/g, '') === norm);
+    if (direct)
+        return [direct];
+    return API_ALIASES[norm] ?? null;
+}
 const TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const STALE_RETRY_MS = 5 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 10_000;
@@ -96,9 +130,9 @@ export async function loadMethodIndex(api, deps = {}) {
     const cached = memoryCache.get(api);
     if (cached && now() < cached.refreshAfter)
         return cached.index;
-    const spec = WORKSPACE_APIS[api];
+    const spec = SUPPORTED_APIS[api];
     if (!spec) {
-        throw new Error(`Unknown api "${api}". Known: ${Object.keys(WORKSPACE_APIS).join(', ')}`);
+        throw new Error(`Unknown api "${api}". Known: ${Object.keys(SUPPORTED_APIS).join(', ')}`);
     }
     const fetchFn = deps.fetchFn ?? ((url) => fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) }));
     const cacheDir = deps.cacheDir ?? discoveryCacheDir();
@@ -124,20 +158,34 @@ export async function loadMethodIndex(api, deps = {}) {
     if (cacheFresh())
         doc = readCache();
     if (!doc) {
-        const url = `https://www.googleapis.com/discovery/v1/apis/${spec.id}/${spec.version}/rest`;
-        try {
-            const res = await fetchFn(url);
-            if (!res.ok)
-                throw new Error(`HTTP ${res.status}`);
-            doc = (await res.json());
-            fs.mkdirSync(cacheDir, { recursive: true });
-            fs.writeFileSync(cacheFile, JSON.stringify(doc), { mode: 0o600 });
+        // Newer APIs (analyticsadmin/analyticsdata) are absent from the central
+        // discovery directory (404); each service's own $discovery endpoint is
+        // authoritative, so try both — same fallback as scripts/fetch-discovery.
+        const urls = [
+            `https://www.googleapis.com/discovery/v1/apis/${spec.id}/${spec.version}/rest`,
+            `https://${spec.id}.googleapis.com/$discovery/rest?version=${spec.version}`,
+        ];
+        let fetchError;
+        for (const url of urls) {
+            try {
+                const res = await fetchFn(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                doc = (await res.json());
+                fs.mkdirSync(cacheDir, { recursive: true });
+                fs.writeFileSync(cacheFile, JSON.stringify(doc), { mode: 0o600 });
+                break;
+            }
+            catch (err) {
+                fetchError = err;
+                doc = undefined;
+            }
         }
-        catch (err) {
+        if (!doc) {
             doc = readCache();
             staleFallback = true;
             if (!doc) {
-                throw new Error(`Could not fetch the Google API Discovery document for "${api}" and no local cache exists (${err.message}). Retry when online.`, { cause: err });
+                throw new Error(`Could not fetch the Google API Discovery document for "${api}" and no local cache exists (${fetchError?.message ?? 'fetch failed'}). Retry when online.`, { cause: fetchError });
             }
         }
     }
@@ -148,9 +196,24 @@ export async function loadMethodIndex(api, deps = {}) {
 export function clearDiscoveryMemoryCache() {
     memoryCache.clear();
 }
-const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect)/i;
-const POST_UPDATE_VERB = /^(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format)/i;
-const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout)/i;
+// GA4-style report execution (runReport, batchRunPivotReports, runAccessReport)
+// and check* predicates are POSTs purely for the request-body size — reads.
+const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect|check|suggest|(batch)?run\w*report)/i;
+// `cancelWipe` must be matched here, BEFORE `cancel` reaches the delete list:
+// it calls off a pending wipe, which is the opposite of one. Update is tested
+// before delete for exactly that reason.
+// State transitions on something that already exists: reversible, and none of
+// them creates anything, so `create` was both wrong and the most permissive
+// class available. `(batch)?` mirrors the delete list, without which every
+// `batchUpdate*` POST fell through to `create`.
+const POST_UPDATE_VERB = /^(cancelWipe|(batch)?(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format|change|close|reopen|enable|disable|hide|unhide|accept|approve|decline|reassign|reactivate|renew|mark|turn|suspend|activate|make|return|reclaim|complete))/i;
+// archive sits with the deletes: in GA4 archiving a custom dimension/metric is
+// permanent, so the most restrictive write class is the safe classification.
+// So do the teardown verbs: `stop` and `cancel` tear down a push channel or a
+// long-running operation, `wipe`/`invalidate`/`signOut` destroy device data,
+// codes and sessions, `reset` discards a configuration, and `end` terminates a
+// live conference. Each removes something that existed.
+const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout|archive|wipe|invalidate|signOut|stop|cancel|unregister|unreserve|reset|end)/i;
 export function cudFromMethod(method) {
     switch (method.httpMethod) {
         case 'GET':
@@ -181,7 +244,23 @@ export function expandPath(template, pathParams) {
         if (value === undefined) {
             throw new Error(`Missing required path parameter "${name}"`);
         }
-        return plus ? String(value).split('/').map(encodeURIComponent).join('/') : encodeURIComponent(String(value));
+        // A blank segment collapses the path and Google routes the resulting
+        // trailing-slash URL to the COLLECTION: `sites.get` with siteUrl:"" came
+        // back as the whole site LIST, reported as success. Dot segments resolve
+        // at URL-parse time, so `../v1/contactGroups` retargets the call at a
+        // different endpoint and returns ITS response as success. Both are
+        // silent-wrong, so refuse locally rather than send a different request.
+        // `{+param}` keeps its slashes, so every segment has to be checked.
+        const segments = plus ? String(value).split('/') : [String(value)];
+        for (const segment of segments) {
+            if (segment.trim() === '') {
+                throw new Error(`Path parameter "${name}" is empty. An empty value addresses the collection, not one resource, so nothing was sent to Google.`);
+            }
+            if (segment === '.' || segment === '..') {
+                throw new Error(`Path parameter "${name}" contains a "${segment}" path segment, which would retarget the request at a different endpoint. Nothing was sent to Google.`);
+            }
+        }
+        return segments.map(encodeURIComponent).join('/');
     });
 }
 export function searchMethods(index, query, limit = 10) {

package/dist/doctor.d.ts

@@ -53,6 +53,9 @@ export interface HttpProbeResult {
 }
 /** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
 export declare function apiEnableLink(api: string): string;
+/** One line, state AND source, so the people being measured can see both
+ * here and in `diagnose` (metrics spec section 2). Read-only. */
+export declare function usageMetricsStatusLine(env: Record<string, string | undefined>): string;
 /** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
 export declare function overallVerdict(sections: DiagnosticSection[]): Verdict;
 export declare function runDiagnostics(deps?: DiagnosticsDeps): Promise<DiagnosticsReport>;
@@ -64,7 +67,12 @@ export declare function renderReport(report: DiagnosticsReport, version: string)
 /** Exit non-zero when any section FAILs; with strict, WARN counts too. */
 export declare function exitCodeFor(report: DiagnosticsReport, strict: boolean): number;
 /** Agent-callable structured health report (read-only). Mirrors `doctor`'s
- * engine; NOT alwaysLoad (the agent asks for it when diagnosing). */
+ * engine. Registered as a META tool, like `account_list`: it introspects this
+ * server rather than Google data, and as a normal tool it became a service of
+ * its own with no `{service}_discover` to reveal it (discover tools are built
+ * from already-registered services, and this runs after that), so it was
+ * advertised only once something else expanded the surface. The README sends
+ * people here when they are stuck, so it has to be findable. */
 export declare function registerDiagnoseTool(registry: ToolRegistry): void;
 export interface ResetOptions {
     account?: string;