mcp-google-multi 6.0.0-beta.1 → 6.0.0-beta.2

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;

package/dist/doctor.js

@@ -5,8 +5,11 @@ import { getAccountSet } from './accounts.js';
 import { deriveAccountHealth } from './tools/accounts-tool.js';
 import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
 import { hasToken } from './token-store.js';
-import { configDir } from './config-file.js';
+import { configDir, loadConfigFile } from './config-file.js';
+import { envValueSource } from './env-load.js';
+import { describeMetricsDir, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 import { probeApiEnablement } from './api-probe.js';
+import { safeMessage, stringifyEnvelope } from './tools/_errors.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
 const MIN_NODE_MAJOR = 22;
@@ -114,8 +117,24 @@ function sectionConfig(deps, set) {
             hint = (hint ? `${hint} ` : '') + `Move it: \`mv ${envFile} ${target}\`.`;
         }
     }
+    lines.push(usageMetricsStatusLine(deps.env));
     return { id: 2, title: 'Config', verdict, lines, ...(hint ? { hint } : {}), ...(slug ? { slug } : {}) };
 }
+/** One line, state AND source, so the people being measured can see both
+ * here and in `diagnose` (metrics spec section 2). Read-only. */
+export function usageMetricsStatusLine(env) {
+    const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
+    let configValue;
+    try {
+        configValue = loadConfigFile(undefined, 'throw')?.usageMetrics;
+    }
+    catch { /* invalid config is section 2's business, not this line's */ }
+    const state = resolveUsageMetrics(env, configValue, envSrc?.kind === 'file' ? envSrc.file : undefined);
+    if (!state.enabled)
+        return `local usage metrics: off ${sourceLabel(state.source)}`;
+    const d = describeMetricsDir(env);
+    return `local usage metrics: on ${sourceLabel(state.source)} -> ${d.dir} (${d.files} files, ${d.kb} KB)`;
+}
 function sectionKeys(deps, aliases) {
     const provenance = deps.masterKeyProvenance();
     const tokensExist = deps.anyTokensExist(aliases);
@@ -338,9 +357,14 @@ export function exitCodeFor(report, strict) {
     return 0;
 }
 /** 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 function registerDiagnoseTool(registry) {
-    registry.registerTool('diagnose', {
+    registry.registerMeta('diagnose', {
         annotations: { readOnlyHint: true, openWorldHint: true },
         description: 'Health report for this server: runtime, config, keys, per-account token status, scope grants, and API enablement. Read-only; returns copy-pasteable fixes for anything wrong. Call this to diagnose auth/config failures.',
         inputSchema: {},
@@ -350,7 +374,11 @@ export function registerDiagnoseTool(registry) {
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (e) {
-            return { content: [{ type: 'text', text: JSON.stringify({ error: 'diagnose_failed', message: e?.message ?? String(e) }) }], isError: true };
+            return { content: [{ type: 'text', text: stringifyEnvelope({
+                            error: 'diagnose_failed',
+                            message: safeMessage(e),
+                            retriable: false,
+                        }) }], isError: true };
         }
     });
 }

package/dist/env-load.d.ts

@@ -9,3 +9,14 @@ export interface EnvLoadPaths {
     configDir?: string;
 }
 export declare function loadEnvFiles(paths?: EnvLoadPaths): EnvLoadResult;
+/**
+ * Which layer supplied `key`: the real process env, or the first loaded .env
+ * file defining it (autoload never overwrites, so first wins). undefined when
+ * the key is unset. Powers self-announcing enablement sources (usage metrics).
+ */
+export declare function envValueSource(key: string): {
+    kind: 'process';
+} | {
+    kind: 'file';
+    file: string;
+} | undefined;

package/dist/env-load.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -48,5 +48,27 @@ export function loadEnvFiles(paths = {}) {
     }
     for (const [k, v] of boot)
         process.env[k] = v;
+    lastLoad = { bootKeys: new Set(boot.keys()), loaded };
     return { loaded, searched: candidates };
 }
+let lastLoad;
+/**
+ * Which layer supplied `key`: the real process env, or the first loaded .env
+ * file defining it (autoload never overwrites, so first wins). undefined when
+ * the key is unset. Powers self-announcing enablement sources (usage metrics).
+ */
+export function envValueSource(key) {
+    if (process.env[key] === undefined)
+        return undefined;
+    if (!lastLoad || lastLoad.bootKeys.has(key))
+        return { kind: 'process' };
+    const re = new RegExp(`^\\s*${key}\\s*=`, 'm');
+    for (const p of lastLoad.loaded) {
+        try {
+            if (re.test(readFileSync(p, 'utf-8')))
+                return { kind: 'file', file: p };
+        }
+        catch { /* file vanished since load: fall through */ }
+    }
+    return { kind: 'process' };
+}

package/dist/executor.js

@@ -1,7 +1,9 @@
 import { getClient } from './client.js';
+import { sliceEncoded } from './trim.js';
 import { expandPath, isGoogleApiUrl } from './discovery-client.js';
 import { handleGoogleApiError } from './tools/_errors.js';
 import { scopeHintForMethod } from './scope-observability.js';
+import { checkOutboundForMethod } from './outbound-allowlist.js';
 export const MAX_RESPONSE_CHARS = 100_000;
 export function jsonResult(payload, isError = false) {
     const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -29,6 +31,11 @@ export function resolveRequestBody(httpMethod, body) {
     return body ?? undefined;
 }
 export async function executeApiMethod(method, args, deps = {}) {
+    // Outbound allowlist: no-op when off; with it active, structured bodies are
+    // inspected for recipient fields and raw-compose methods are refused.
+    const outbound = checkOutboundForMethod(method.id, args.body, args.account);
+    if (outbound)
+        return outbound;
     if (args.queryParams?.alt === 'media') {
         return jsonResult({
             error: 'binary_unsupported',
@@ -82,10 +89,14 @@ export async function executeApiMethod(method, args, deps = {}) {
         });
         const text = JSON.stringify(res.data ?? null);
         if (text.length > MAX_RESPONSE_CHARS) {
+            // Budget the ENCODED head: jsonResult re-stringifies it, so every quote
+            // and backslash inside doubles. Slicing raw characters made the emitted
+            // result exceed the cap this tool advertises, by up to 15 percent on a
+            // quote-dense listing.
             return jsonResult({
                 truncated: true,
                 totalChars: text.length,
-                head: text.slice(0, MAX_RESPONSE_CHARS),
+                head: sliceEncoded(text, MAX_RESPONSE_CHARS),
                 hint: 'Narrow the request (fields mask, pageSize) to get complete JSON.',
             });
         }