mcp-google-multi 6.0.0-alpha.23 → 6.0.0-alpha.25

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/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/index.js

@@ -9,7 +9,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { GENERATED_SERVICES } from './tools/generated/index.js';
 import { GENERATED_GATES, SERVICES } from './services.js';
-import { ToolRegistry } from './registry.js';
+import { ToolRegistry, resolveDiscoveryMode } from './registry.js';
 import { registerDiscoverTools } from './discover.js';
 import { registerEscapeTools } from './tools/google-api.js';
 import { registerAccountTools } from './tools/accounts-tool.js';
@@ -21,12 +21,15 @@ import { buildIdentityContext } from './identity.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
 import { argNormalizationEnabled, withArgNormalization } from './arg-normalize.js';
+import { envValueSource } from './env-load.js';
+import { loadConfigFile } from './config-file.js';
+import { initUsageMetrics, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
-function buildRegistry(server, ctx, mode) {
+function buildRegistry(server, ctx, mode, metrics = null) {
     const policy = ctx.policy;
-    const registry = new ToolRegistry(server, policy, mode);
+    const registry = new ToolRegistry(server, policy, mode, metrics);
     const toolsets = getToolsets();
     if (toolsets !== 'all') {
         const known = new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)]);
@@ -183,11 +186,43 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
+    // Local usage metrics: fail-closed resolve, self-announcing source, null
+    // when off (no wrapper, no dir, nothing initializes). One instance per
+    // transport so `boots` keys stay honest under `both`.
+    const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
+    const metricsState = resolveUsageMetrics(process.env, loadConfigFile()?.usageMetrics, envSrc?.kind === 'file' ? envSrc.file : undefined);
+    if (metricsState.warning)
+        process.stderr.write(metricsState.warning);
+    const metricsInstances = [];
+    const initMetricsFor = (transport, mode) => {
+        const m = initUsageMetrics(metricsState, { version: pkg.version, mode, transport });
+        if (m) {
+            metricsInstances.push(m);
+            process.stderr.write(`local usage metrics: on ${sourceLabel(metricsState.source)} -> ${m.statusLine()}\n`);
+        }
+        return m;
+    };
+    if (!metricsState.enabled && metricsState.source.kind !== 'default') {
+        process.stderr.write(`local usage metrics: off ${sourceLabel(metricsState.source)}\n`);
+    }
+    const flushMetrics = () => { for (const m of metricsInstances)
+        m.shutdown(); };
+    process.on('exit', flushMetrics);
+    if (metricsState.enabled) {
+        for (const sig of ['SIGTERM', 'SIGINT']) {
+            process.once(sig, () => {
+                flushMetrics();
+                // stdio has no other signal handler; preserve terminate-on-signal.
+                if (!wantHttp)
+                    process.exit(sig === 'SIGINT' ? 130 : 143);
+            });
+        }
+    }
     // Build one McpServer + registry per transport at boot (P1 / BV gap #4:
     // never rebuilt per request); `both` runs the two concurrently.
     if (wantStdio) {
         const server = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
-        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }));
+        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }), undefined, initMetricsFor('stdio', resolveDiscoveryMode()));
         registry.installListHandler();
         registerSetupPrompt(server);
         const stdioTransport = new StdioServerTransport();
@@ -208,7 +243,7 @@ async function main() {
             process.stderr.write(`GOOGLE_DISCOVERY="${configuredMode}" is ignored over HTTP; the stateless transport forces "curated".\n`);
         }
         const httpServer = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
-        const registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated');
+        const registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated', initMetricsFor('http', 'curated'));
         registry.installListHandler();
         registerSetupPrompt(httpServer);
         // B13: mount the OAuth 2.1 AS (legs A + B) + the Bearer authenticator.

package/dist/registry.d.ts

@@ -2,6 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { type Policy } from './write-control.js';
 import type { ArgShape } from './arg-normalize.js';
+import type { Metrics } from './usage-metrics.js';
 export type Cud = 'read' | 'create' | 'update' | 'delete';
 export type DiscoveryMode = 'lazy' | 'curated' | 'eager';
 export declare function resolveDiscoveryMode(env?: NodeJS.ProcessEnv): DiscoveryMode;
@@ -34,6 +35,7 @@ export interface CatalogOperation {
 export declare function inferCud(name: string): Cud;
 export declare class ToolRegistry {
     private readonly server;
+    private readonly metrics;
     readonly tools: ToolEntry[];
     readonly policy: Policy;
     readonly registerTool: McpServer['registerTool'];
@@ -47,7 +49,7 @@ export declare class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     private expanded;
-    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode);
+    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode, metrics?: Metrics | null);
     registerMeta: McpServer['registerTool'];
     services(): string[];
     /** Declared input-schema keys + scalar kinds for one tool (tools/call arg

package/dist/registry.js

@@ -81,6 +81,7 @@ export function inferCud(name) {
 }
 export class ToolRegistry {
     server;
+    metrics;
     tools = [];
     policy;
     registerTool;
@@ -94,8 +95,9 @@ export class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     expanded = false;
-    constructor(server, policy, mode = resolveDiscoveryMode()) {
+    constructor(server, policy, mode = resolveDiscoveryMode(), metrics = null) {
         this.server = server;
+        this.metrics = metrics;
         this.policy = policy;
         this.mode = mode;
         this.registerTool = ((name, config, handler) => {
@@ -194,8 +196,21 @@ export class ToolRegistry {
             const finalHandler = this.compactOutput
                 ? async (...args) => compactResult(await withDefault(...args))
                 : withDefault;
+            // Usage metrics wrap OUTERMOST and only when enabled: off means no
+            // wrapper exists and the chain is byte-identical to the pre-metrics
+            // chain. Fan-out width is derived here (bucketed in the module) so the
+            // metrics module never imports fanout.
+            const instrumented = this.metrics
+                ? this.metrics.wrap({ name, service, meta: this.registeringMeta, generated: config.cud !== undefined }, finalHandler, (a) => {
+                    const v = a?.account;
+                    if (typeof v !== 'string' || (v !== '*' && !v.includes(',')))
+                        return 1;
+                    const sel = parseAccountSelector(v);
+                    return sel.ok ? sel.aliases.length : 1;
+                })
+                : finalHandler;
             const { cud: _cud, ...sdkConfig } = config;
-            return server.registerTool(name, { ...sdkConfig, inputSchema: inputShape, annotations }, finalHandler);
+            return server.registerTool(name, { ...sdkConfig, inputSchema: inputShape, annotations }, instrumented);
         });
     }
     registerMeta = ((name, config, handler) => {

package/dist/tools/_coerce.d.ts

@@ -1,4 +1,8 @@
 import { z } from 'zod';
 export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<T>>;
 export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
+/** Numeric args arrive string-encoded from some clients; over stdio the SDK
+ * validates the schema directly (the HTTP transport's arg-normalization layer
+ * never runs), so the coercion must live in the schema itself. */
+export declare function coerceNumber<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
 export declare const coerceBoolean: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>;

package/dist/tools/_coerce.js

@@ -22,6 +22,16 @@ export function coerceArray(element) {
 export function coerceJson(schema) {
     return z.preprocess((val) => (typeof val === 'string' ? parseJsonLoose(val) : val), schema);
 }
+/** Numeric args arrive string-encoded from some clients; over stdio the SDK
+ * validates the schema directly (the HTTP transport's arg-normalization layer
+ * never runs), so the coercion must live in the schema itself. */
+export function coerceNumber(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === 'string' && val.trim() !== '' && !Number.isNaN(Number(val)))
+            return Number(val);
+        return val;
+    }, schema);
+}
 export const coerceBoolean = z.preprocess((val) => {
     if (typeof val === 'boolean')
         return val;

package/dist/tools/drive.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { coerceArray, coerceBoolean } from './_coerce.js';
+import { coerceArray, coerceBoolean, coerceNumber } from './_coerce.js';
 import { drive as driveClient } from '@googleapis/drive';
 import { accountAliasSchema, getAccountSet } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -129,7 +129,7 @@ export function registerDriveTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             query: z.string().describe('A plain keyword (full-text search) or Drive query syntax, e.g. "name contains \'MoU\'"'),
-            maxResults: z.number().min(1).max(100).default(10).optional()
+            maxResults: coerceNumber(z.number().min(1).max(100)).optional()
                 .describe('Max results to return (default: 10, max: 100)'),
             driveId: z.string().optional().describe('Optional shared drive ID'),
         },

package/dist/tools/gmail.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { coerceArray, coerceBoolean, coerceJson } from './_coerce.js';
+import { coerceArray, coerceBoolean, coerceJson, coerceNumber } from './_coerce.js';
 import { gmail as gmailClient } from '@googleapis/gmail';
 import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -442,7 +442,7 @@ export function registerGmailTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             query: z.string().describe('Gmail search syntax, e.g. "from:monaam is:unread"'),
-            maxResults: z.number().min(1).max(100).default(20).optional()
+            maxResults: coerceNumber(z.number().min(1).max(100)).optional()
                 .describe('Max results to return (default: 20, max: 100)'),
             full: coerceBoolean.optional().describe('Return the full row shape instead of the compact default'),
         },

package/dist/usage-metrics.d.ts

@@ -0,0 +1,98 @@
+export declare const METRICS_DIR_NAME = "metrics";
+/** Union of every `error:` slug literal emitted anywhere in src/ (kept honest
+ * by a set-equality grep test). Anything outside buckets to `other`. */
+export declare const KNOWN_ERROR_SLUGS: ReadonlySet<string>;
+export declare function stateDir(env?: NodeJS.ProcessEnv): string;
+export declare function latBucket(ms: number): string;
+export declare function charsBucket(n: number): string;
+export declare function fanBucket(width: number): string | undefined;
+export type MetricsSource = {
+    kind: 'default';
+} | {
+    kind: 'config';
+} | {
+    kind: 'process-env';
+} | {
+    kind: 'env-file';
+    file: string;
+};
+export interface UsageMetricsState {
+    enabled: boolean;
+    source: MetricsSource;
+    /** exactly one stderr warning on a malformed non-empty env value (fail-closed) */
+    warning?: string;
+}
+/**
+ * Fail-closed resolution (mirror of resolveDiscoveryMode's fail-open: here the
+ * safe state is off). Env wins over config; empty env value = unset, silent;
+ * any other value = one warning, off. `envFile` is the .env path that supplied
+ * the variable when it did not come from the real process env (attribution
+ * is computed by the caller; this module never reads env files).
+ */
+export declare function resolveUsageMetrics(env: NodeJS.ProcessEnv, configValue: boolean | undefined, envFile?: string): UsageMetricsState;
+export declare function sourceLabel(source: MetricsSource): string;
+export interface ToolEntryInfo {
+    name: string;
+    service: string;
+    meta: boolean;
+    generated: boolean;
+}
+export interface InitOptions {
+    dir?: string;
+    version: string;
+    mode: string;
+    transport: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    monotonic?: () => number;
+    log?: (line: string) => void;
+}
+export declare class Metrics {
+    private readonly dir;
+    private readonly aggDir;
+    private readonly eventsFile;
+    private readonly now;
+    private readonly mono;
+    private readonly log;
+    private readonly bootKey;
+    private readonly bootId;
+    private seq;
+    private deltas;
+    private events;
+    private lastError;
+    private lastTool;
+    private pendingMid;
+    private timer;
+    private dirty;
+    private failures;
+    private disabled;
+    constructor(opts: InitOptions);
+    private day;
+    private initStorage;
+    private pruneAggs;
+    private day2ms;
+    private pruneEventAge;
+    /** Outermost dispatch wrapper; a throw inside recording never affects the call. */
+    wrap<A extends unknown[], R>(entry: ToolEntryInfo, handler: (...args: A) => Promise<R> | R, widthOf?: (args: unknown) => number): (...args: A) => Promise<R>;
+    private record;
+    /** Escape hatch: only the RESOLVED methodId (double-gated) or a miss. */
+    recordEscapeMethod(idOrNull: string | null): void;
+    /** Search instrument: post-resolution SUPPORTED_APIS keys, or null on failure. */
+    recordSearchApi(resolvedApis: string[] | null): void;
+    recordArgFix(tool: string): void;
+    /** Protocol-level failures (no handler ran); wired by the transport tap. */
+    recordRpc(kind: 'schema_validation' | 'tool_not_found' | number, tool?: string): void;
+    private rolloverIfNeeded;
+    /** Merge deltas into the day file under lock; append buffered events. */
+    flush(): void;
+    private rotateIfNeeded;
+    /** Best-effort synchronous flush for shutdown paths. */
+    shutdown(): void;
+    /** For the doctor/diagnose status line. */
+    statusLine(): string;
+}
+/**
+ * null when off: no directory, no file, no timer, nothing initializes; setting
+ * USAGE_METRICS_PATH alone never enables anything and never creates anything.
+ */
+export declare function initUsageMetrics(state: UsageMetricsState, opts: InitOptions): Metrics | null;

package/dist/usage-metrics.js

@@ -0,0 +1,538 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { withFileLock, atomicWriteFileSync } from './fs-atomic.js';
+// Local usage metrics (metrics-feature-spec.md). Default OFF at every layer;
+// when off, nothing here initializes and the dispatch chain carries no wrapper.
+// Zero network egress is structural: this module's import set is a tested
+// allowlist (fs/path/os/crypto/perf_hooks/fs-atomic), so egress code cannot
+// even be expressed here. Every string persisted is a member of a server-owned
+// closed vocabulary, matches a pinned shape regex, or is other/unknown_*/
+// _overflow; free text is unrepresentable in the file format. No identity
+// dimension of any kind: no aliases, hashes, emails, or exact account counts.
+export const METRICS_DIR_NAME = 'metrics';
+const FLUSH_MS = 60_000;
+const RETRY_WINDOW_MS = 10 * 60_000;
+const BIGRAM_GAP_MS = 5 * 60_000;
+const BIGRAM_CAP = 1_500;
+const ERR_SLUG_CAP = 32;
+const ESCAPE_CAP = 500;
+const EVENTS_ROTATE_BYTES = 4 * 1024 * 1024;
+const RETENTION_DAYS = 180;
+const WRITE_FAILURE_LIMIT = 3;
+const LAT_BOUNDS = [100, 250, 500, 1000, 2500, 5000, 10000, 30000];
+const CHARS_BOUNDS = [64, 256, 1024, 4096, 16384, 65536];
+// methodId backstop shape gate: even a tampered discovery cache cannot turn
+// arbitrary strings into recorded values (spec section 1).
+const METHOD_ID_RE = /^[a-z][a-zA-Z0-9]*(\.[a-zA-Z0-9]+)+$/;
+const METHOD_ID_MAX = 128;
+/** Union of every `error:` slug literal emitted anywhere in src/ (kept honest
+ * by a set-equality grep test). Anything outside buckets to `other`. */
+export const KNOWN_ERROR_SLUGS = new Set([
+    'E_CIMD_INVALID', 'E_MCP_TOKEN_INVALID', 'E_NO_DEFAULT_ACCOUNT', 'ambiguous',
+    'api_not_enabled', 'auth_required', 'binary', 'binary_unsupported',
+    'diagnose_failed', 'discovery_unavailable', 'dispatch_timeout', 'forbidden',
+    'insufficient_scope', 'internal', 'invalid_client', 'invalid_client_metadata',
+    'invalid_grant', 'invalid_params', 'invalid_query', 'invalid_request',
+    'invalid_scope', 'network_error', 'not_found', 'rate_limited',
+    'reauth_required', 'too_large', 'toolset_disabled', 'unknown_api',
+    'unknown_method', 'unsupported_grant_type', 'unsupported_type',
+    'untrusted_host', 'upstream_error', 'validation_error', 'write_disabled',
+]);
+const RPC_CODES = new Set([-32700, -32600, -32601, -32603]);
+export function stateDir(env = process.env) {
+    return path.join(env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'), 'mcp-google-multi');
+}
+export function latBucket(ms) {
+    for (const b of LAT_BOUNDS)
+        if (ms <= b)
+            return `le${b}`;
+    return 'gt30000';
+}
+export function charsBucket(n) {
+    for (const b of CHARS_BOUNDS)
+        if (n <= b)
+            return `le${b}`;
+    return 'gt65536';
+}
+export function fanBucket(width) {
+    if (width <= 1)
+        return undefined;
+    if (width === 2)
+        return 'w2';
+    if (width <= 4)
+        return 'w3to4';
+    return 'w5plus';
+}
+const ON = new Set(['on', '1', 'true', 'yes']);
+const OFF = new Set(['off', '0', 'false', 'no']);
+/**
+ * Fail-closed resolution (mirror of resolveDiscoveryMode's fail-open: here the
+ * safe state is off). Env wins over config; empty env value = unset, silent;
+ * any other value = one warning, off. `envFile` is the .env path that supplied
+ * the variable when it did not come from the real process env (attribution
+ * is computed by the caller; this module never reads env files).
+ */
+export function resolveUsageMetrics(env, configValue, envFile) {
+    const raw = env.GOOGLE_USAGE_METRICS;
+    if (raw !== undefined && raw.trim() !== '') {
+        const v = raw.trim().toLowerCase();
+        const source = envFile ? { kind: 'env-file', file: envFile } : { kind: 'process-env' };
+        if (ON.has(v))
+            return { enabled: true, source };
+        if (OFF.has(v))
+            return { enabled: false, source };
+        return {
+            enabled: false,
+            source: { kind: 'default' },
+            warning: `GOOGLE_USAGE_METRICS="${raw}" is not a valid value (on|1|true|yes / off|0|false|no); local usage metrics stay OFF\n`,
+        };
+    }
+    if (configValue === true)
+        return { enabled: true, source: { kind: 'config' } };
+    return { enabled: false, source: { kind: 'default' } };
+}
+export function sourceLabel(source) {
+    switch (source.kind) {
+        case 'config': return '(config)';
+        case 'process-env': return '(process env)';
+        case 'env-file': return `(env file: ${source.file})`;
+        default: return '(default)';
+    }
+}
+function emptyDay(day) {
+    return {
+        v: 1, day, boots: {}, node: process.version, calls: 0, tools: {},
+        hints: {}, retries: {},
+        escape: { methods: {}, _overflow: 0, unknown_method: 0, apis_searched: {}, unknown_api: 0 },
+        validation: {}, rpc: {}, bigrams: {},
+    };
+}
+function addInto(target, key, by = 1) {
+    target[key] = (target[key] ?? 0) + by;
+}
+/** Deep-add b into a for the DayAgg shape (numbers add, maps union). */
+function mergeDay(a, b) {
+    const num = (x, y) => (x ?? 0) + (y ?? 0);
+    const map = (x = {}, y = {}) => {
+        const out = { ...x };
+        for (const [k, v] of Object.entries(y))
+            out[k] = (out[k] ?? 0) + v;
+        return out;
+    };
+    const out = emptyDay(a.day);
+    out.node = b.node || a.node;
+    out.boots = map(a.boots, b.boots);
+    out.calls = num(a.calls, b.calls);
+    const toolNames = new Set([...Object.keys(a.tools), ...Object.keys(b.tools)]);
+    for (const name of toolNames) {
+        const x = a.tools[name];
+        const y = b.tools[name];
+        const t = { n: num(x?.n, y?.n), err: map(x?.err, y?.err), hint: num(x?.hint, y?.hint), lat: map(x?.lat, y?.lat) };
+        if (x?.fanout || y?.fanout)
+            t.fanout = map(x?.fanout, y?.fanout);
+        const argfix = num(x?.argfix, y?.argfix);
+        if (argfix > 0)
+            t.argfix = argfix;
+        out.tools[name] = t;
+    }
+    const slugSet = new Set([...Object.keys(a.hints), ...Object.keys(b.hints)]);
+    for (const s of slugSet) {
+        out.hints[s] = {
+            hinted: num(a.hints[s]?.hinted, b.hints[s]?.hinted),
+            unhinted: num(a.hints[s]?.unhinted, b.hints[s]?.unhinted),
+        };
+    }
+    const retrySet = new Set([...Object.keys(a.retries), ...Object.keys(b.retries)]);
+    for (const s of retrySet) {
+        out.retries[s] = {
+            hintedOk: num(a.retries[s]?.hintedOk, b.retries[s]?.hintedOk),
+            hintedFail: num(a.retries[s]?.hintedFail, b.retries[s]?.hintedFail),
+            unhintedOk: num(a.retries[s]?.unhintedOk, b.retries[s]?.unhintedOk),
+            unhintedFail: num(a.retries[s]?.unhintedFail, b.retries[s]?.unhintedFail),
+        };
+    }
+    out.escape = {
+        methods: map(a.escape.methods, b.escape.methods),
+        _overflow: num(a.escape._overflow, b.escape._overflow),
+        unknown_method: num(a.escape.unknown_method, b.escape.unknown_method),
+        apis_searched: map(a.escape.apis_searched, b.escape.apis_searched),
+        unknown_api: num(a.escape.unknown_api, b.escape.unknown_api),
+    };
+    out.validation = map(a.validation, b.validation);
+    out.rpc = map(a.rpc, b.rpc);
+    out.bigrams = map(a.bigrams, b.bigrams);
+    return out;
+}
+/** Cap open maps at write time (the file may never exceed the caps). */
+function applyCaps(day) {
+    const cap = (m, limit, overflowInto) => {
+        const entries = Object.entries(m);
+        if (entries.length <= limit)
+            return m;
+        entries.sort((x, y) => y[1] - x[1]);
+        const kept = Object.fromEntries(entries.slice(0, limit));
+        const dropped = entries.slice(limit).reduce((s, [, v]) => s + v, 0);
+        if (overflowInto)
+            overflowInto(dropped);
+        else
+            kept.other = (kept.other ?? 0) + dropped;
+        return kept;
+    };
+    for (const t of Object.values(day.tools))
+        t.err = cap(t.err, ERR_SLUG_CAP);
+    day.escape.methods = cap(day.escape.methods, ESCAPE_CAP, (n) => { day.escape._overflow += n; });
+    day.bigrams = cap(day.bigrams, BIGRAM_CAP, (n) => { day.bigrams._overflow = (day.bigrams._overflow ?? 0) + n; });
+    return day;
+}
+export class Metrics {
+    dir;
+    aggDir;
+    eventsFile;
+    now;
+    mono;
+    log;
+    bootKey;
+    bootId = randomBytes(3).toString('hex');
+    seq = 0;
+    deltas;
+    events = [];
+    lastError = new Map();
+    lastTool;
+    pendingMid;
+    timer;
+    dirty = false;
+    failures = 0;
+    disabled = false;
+    constructor(opts) {
+        this.dir = opts.dir ?? path.join(stateDir(opts.env), METRICS_DIR_NAME);
+        this.aggDir = path.join(this.dir, 'agg');
+        this.eventsFile = path.join(this.dir, 'events.jsonl');
+        this.now = opts.now ?? Date.now;
+        this.mono = opts.monotonic ?? (() => performance.now());
+        this.log = opts.log ?? ((l) => process.stderr.write(l));
+        this.bootKey = `${opts.version}/${opts.mode}/${opts.transport}`;
+        this.deltas = emptyDay(this.day());
+        this.deltas.boots[this.bootKey] = 1;
+        this.dirty = true;
+        this.initStorage();
+        this.timer = setInterval(() => this.flush(), FLUSH_MS);
+        this.timer.unref?.();
+    }
+    day() {
+        return new Date(this.now()).toISOString().slice(0, 10);
+    }
+    initStorage() {
+        try {
+            const existed = fs.existsSync(this.dir);
+            fs.mkdirSync(this.aggDir, { recursive: true, mode: 0o700 });
+            if (existed) {
+                const mode = fs.statSync(this.dir).mode & 0o777;
+                if ((mode & 0o077) !== 0) {
+                    this.log(`local usage metrics: ${this.dir} has mode ${mode.toString(8)} (wider than 0700); not changing it, but the files record activity\n`);
+                }
+            }
+            this.pruneAggs();
+            this.pruneEventAge(this.eventsFile);
+        }
+        catch (e) {
+            this.log(`local usage metrics: init failed (${e.message}); disabled for this process\n`);
+            this.disabled = true;
+        }
+    }
+    pruneAggs() {
+        const cutoff = this.day2ms(this.day()) - RETENTION_DAYS * 86_400_000;
+        for (const f of fs.readdirSync(this.aggDir)) {
+            const m = f.match(/^(\d{4}-\d{2}-\d{2})\.json$/);
+            if (m && this.day2ms(m[1]) < cutoff) {
+                try {
+                    fs.rmSync(path.join(this.aggDir, f));
+                }
+                catch { /* prune is best-effort */ }
+            }
+        }
+    }
+    day2ms(day) {
+        return Date.parse(`${day}T00:00:00Z`);
+    }
+    pruneEventAge(file) {
+        if (!fs.existsSync(file))
+            return;
+        const cutoff = this.now() - RETENTION_DAYS * 86_400_000;
+        const lines = fs.readFileSync(file, 'utf-8').split('\n');
+        const kept = lines.filter((l) => {
+            if (!l.trim())
+                return false;
+            try {
+                const ts = JSON.parse(l).ts;
+                return typeof ts === 'string' && Date.parse(ts) >= cutoff;
+            }
+            catch {
+                return false; // torn or corrupt line: drop
+            }
+        });
+        if (kept.length !== lines.filter((l) => l.trim()).length) {
+            atomicWriteFileSync(file, kept.join('\n') + (kept.length ? '\n' : ''));
+        }
+    }
+    /** Outermost dispatch wrapper; a throw inside recording never affects the call. */
+    wrap(entry, handler, widthOf) {
+        return async (...args) => {
+            const started = this.mono();
+            const result = await handler(...args);
+            try {
+                this.record(entry, args[0], result, this.mono() - started, widthOf);
+            }
+            catch { /* metrics may never fail a tool call */ }
+            return result;
+        };
+    }
+    record(entry, firstArg, result, ms, widthOf) {
+        if (this.disabled)
+            return;
+        this.rolloverIfNeeded();
+        const r = result;
+        const ok = !r?.isError;
+        let slug;
+        let hinted;
+        if (!ok) {
+            try {
+                const first = r?.content?.[0]?.text;
+                if (typeof first === 'string' && first.length < 65_536) {
+                    const env = JSON.parse(first);
+                    if (typeof env.error === 'string')
+                        slug = KNOWN_ERROR_SLUGS.has(env.error) ? env.error : 'other';
+                    hinted = typeof env.hint === 'string' && env.hint.length > 0;
+                }
+            }
+            catch {
+                slug = 'other';
+            }
+            slug ??= 'other';
+        }
+        const chars = (r?.content ?? []).reduce((s, c) => s + (typeof c.text === 'string' ? c.text.length : 0), 0);
+        let width = 1;
+        if (widthOf) {
+            try {
+                width = widthOf(firstArg);
+            }
+            catch {
+                width = 1;
+            }
+        }
+        const fan = fanBucket(width);
+        const t = (this.deltas.tools[entry.name] ??= { n: 0, err: {}, hint: 0, lat: {} });
+        t.n += 1;
+        this.deltas.calls += 1;
+        addInto(t.lat, latBucket(ms));
+        if (slug) {
+            addInto(t.err, slug);
+            if (hinted)
+                t.hint += 1;
+            const h = (this.deltas.hints[slug] ??= { hinted: 0, unhinted: 0 });
+            if (hinted)
+                h.hinted += 1;
+            else
+                h.unhinted += 1;
+        }
+        if (fan) {
+            const f = (t.fanout ??= { calls: 0 });
+            f.calls += 1;
+            addInto(f, fan);
+        }
+        // retry self-correction chain (spec section 1): in-memory only.
+        const nowM = this.mono();
+        const prev = this.lastError.get(entry.name);
+        if (prev && nowM - prev.at <= RETRY_WINDOW_MS) {
+            const rr = (this.deltas.retries[prev.slug] ??= { hintedOk: 0, hintedFail: 0, unhintedOk: 0, unhintedFail: 0 });
+            const key = `${prev.hinted ? 'hinted' : 'unhinted'}${ok ? 'Ok' : 'Fail'}`;
+            rr[key] += 1;
+            this.lastError.delete(entry.name);
+        }
+        if (!ok && slug)
+            this.lastError.set(entry.name, { slug, hinted: hinted === true, at: nowM });
+        // bigrams: ordered pairs within the process, 5-minute gap breaks the chain.
+        if (this.lastTool && nowM - this.lastTool.at <= BIGRAM_GAP_MS) {
+            addInto(this.deltas.bigrams, `${this.lastTool.name}>${entry.name}`);
+        }
+        this.lastTool = { name: entry.name, at: nowM };
+        const event = {
+            ts: new Date(this.now()).toISOString().slice(0, 16) + ':00Z',
+            boot: this.bootId,
+            seq: this.seq++,
+            tool: entry.name,
+            ok,
+            ms: Math.round(ms),
+            chars: charsBucket(chars),
+            src: 'handler',
+        };
+        if (slug)
+            event.err = slug;
+        if (hinted !== undefined)
+            event.hint = hinted;
+        if (fan)
+            event.fan = fan;
+        // mid: set mid-dispatch by recordEscapeMethod, attached to the escape
+        // call's own event line (per-event field, never a synthetic event).
+        if (entry.name === 'google_api_call' && this.pendingMid) {
+            event.mid = this.pendingMid;
+            this.pendingMid = undefined;
+        }
+        this.events.push(JSON.stringify(event));
+        this.dirty = true;
+    }
+    /** Escape hatch: only the RESOLVED methodId (double-gated) or a miss. */
+    recordEscapeMethod(idOrNull) {
+        try {
+            this.rolloverIfNeeded();
+            if (idOrNull === null) {
+                this.deltas.escape.unknown_method += 1;
+            }
+            else if (idOrNull.length <= METHOD_ID_MAX && METHOD_ID_RE.test(idOrNull)) {
+                addInto(this.deltas.escape.methods, idOrNull);
+                this.pendingMid = idOrNull;
+            }
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    /** Search instrument: post-resolution SUPPORTED_APIS keys, or null on failure. */
+    recordSearchApi(resolvedApis) {
+        try {
+            this.rolloverIfNeeded();
+            if (resolvedApis === null)
+                this.deltas.escape.unknown_api += 1;
+            else
+                for (const k of resolvedApis)
+                    addInto(this.deltas.escape.apis_searched, k);
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    recordArgFix(tool) {
+        try {
+            this.rolloverIfNeeded();
+            const t = (this.deltas.tools[tool] ??= { n: 0, err: {}, hint: 0, lat: {} });
+            t.argfix = (t.argfix ?? 0) + 1;
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    /** Protocol-level failures (no handler ran); wired by the transport tap. */
+    recordRpc(kind, tool) {
+        try {
+            this.rolloverIfNeeded();
+            if (kind === 'schema_validation') {
+                if (tool)
+                    addInto(this.deltas.validation, tool);
+            }
+            else if (kind === 'tool_not_found') {
+                addInto(this.deltas.rpc, 'tool_not_found');
+            }
+            else {
+                addInto(this.deltas.rpc, RPC_CODES.has(kind) ? `rpc_error_${kind}` : 'rpc_error_other');
+            }
+            this.events.push(JSON.stringify({
+                ts: new Date(this.now()).toISOString().slice(0, 16) + ':00Z',
+                boot: this.bootId, seq: this.seq++,
+                tool: tool ?? 'other', ok: false, ms: 0, chars: 'le64', src: 'rpc',
+            }));
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    rolloverIfNeeded() {
+        const today = this.day();
+        if (this.deltas.day !== today) {
+            this.flush();
+            this.deltas = emptyDay(today);
+            this.pruneAggs();
+            this.dirty = false;
+        }
+    }
+    /** Merge deltas into the day file under lock; append buffered events. */
+    flush() {
+        if (!this.dirty || this.disabled)
+            return;
+        const deltas = this.deltas;
+        const events = this.events;
+        try {
+            const file = path.join(this.aggDir, `${deltas.day}.json`);
+            withFileLock(file, () => {
+                let current = emptyDay(deltas.day);
+                try {
+                    const onDisk = JSON.parse(fs.readFileSync(file, 'utf-8'));
+                    if (onDisk && onDisk.v === 1 && onDisk.day === deltas.day)
+                        current = onDisk;
+                }
+                catch {
+                    if (fs.existsSync(file))
+                        this.log(`local usage metrics: unreadable day file ${file}; starting fresh\n`);
+                }
+                atomicWriteFileSync(file, JSON.stringify(applyCaps(mergeDay(current, deltas))));
+            });
+            if (events.length > 0) {
+                fs.appendFileSync(this.eventsFile, events.join('\n') + '\n', { mode: 0o600 });
+                this.rotateIfNeeded();
+            }
+            this.deltas = emptyDay(deltas.day);
+            this.events = [];
+            this.dirty = false;
+            this.failures = 0;
+        }
+        catch (e) {
+            this.failures += 1;
+            if (this.failures >= WRITE_FAILURE_LIMIT) {
+                this.disabled = true;
+                if (this.timer)
+                    clearInterval(this.timer);
+                this.log(`local usage metrics: ${WRITE_FAILURE_LIMIT} consecutive write failures (${e.message}); disabled for this process\n`);
+            }
+        }
+    }
+    rotateIfNeeded() {
+        try {
+            if (fs.statSync(this.eventsFile).size < EVENTS_ROTATE_BYTES)
+                return;
+            this.pruneEventAge(this.eventsFile);
+            if (fs.statSync(this.eventsFile).size < EVENTS_ROTATE_BYTES)
+                return;
+            fs.renameSync(this.eventsFile, path.join(this.dir, 'events.1.jsonl'));
+        }
+        catch { /* rotation is best-effort */ }
+    }
+    /** Best-effort synchronous flush for shutdown paths. */
+    shutdown() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.flush();
+    }
+    /** For the doctor/diagnose status line. */
+    statusLine() {
+        try {
+            const files = [
+                ...fs.readdirSync(this.aggDir).map((f) => path.join(this.aggDir, f)),
+                this.eventsFile, path.join(this.dir, 'events.1.jsonl'),
+            ].filter((f) => fs.existsSync(f));
+            const bytes = files.reduce((s, f) => s + fs.statSync(f).size, 0);
+            return `${this.dir} (${files.length} files, ${Math.round(bytes / 1024)} KB)`;
+        }
+        catch {
+            return this.dir;
+        }
+    }
+}
+/**
+ * null when off: no directory, no file, no timer, nothing initializes; setting
+ * USAGE_METRICS_PATH alone never enables anything and never creates anything.
+ */
+export function initUsageMetrics(state, opts) {
+    if (!state.enabled)
+        return null;
+    return new Metrics({
+        ...opts,
+        dir: opts.dir ?? (opts.env ?? process.env).USAGE_METRICS_PATH ?? undefined,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.23",
+  "version": "6.0.0-alpha.25",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,7 @@
     "gen:discovery": "tsx scripts/fetch-discovery.ts",
     "gen:tools": "tsx scripts/gen-tools.ts",
     "gen:coverage": "tsx scripts/gen-coverage.ts",
+    "eval:contract": "npx --yes promptfoo@0.123.1 eval -c eval/contract/promptfooconfig.yaml --no-progress-bar",
     "measure:lazy": "node scripts/measure-tools.mjs",
     "pack:mcpb": "mcpb pack . mcp-google-multi.mcpb",
     "bundle": "esbuild dist/index.js --bundle --platform=node --format=esm --outfile=bundle/index.js --external:@napi-rs/keyring --banner:js=\"import{createRequire as __dockerCR}from'node:module';var require=__dockerCR(import.meta.url);\" --log-level=warning"