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

package/dist/usage-metrics.d.ts

@@ -86,6 +86,26 @@ export interface InitOptions {
     now?: () => number;
     monotonic?: () => number;
     log?: (line: string) => void;
+    /** Default true. Three chains correlate CONSECUTIVE calls, which is only
+     * meaningful when one caller owns the whole process: the retry and bigram
+     * chains, and pendingMid (the escape hatch's resolved methodId, attached to
+     * the next google_api_call event's `mid`). A host serving several callers
+     * sets false so none of the three ever cross-link a call between tenants.
+     * DayAgg shape is unchanged (retries/bigrams stay empty maps);
+     * escape.methods still counts every resolved call either way. */
+    sequencingEnabled?: boolean;
+    /** Default true. When false, no events.jsonl / events.1.jsonl is ever
+     * created or appended to; only agg/ exists. A host serving several callers
+     * sets false: each event line carries a minute timestamp, the boot id and a
+     * per-process sequence number, which can be joined against a per-caller log
+     * such as an audit trail; the day aggregate keeps the same counters without
+     * order. */
+    eventLog?: boolean;
+    /** Default none. A host's own closed slug set, unioned with
+     * KNOWN_ERROR_SLUGS for this instance only; each entry must match
+     * /^[A-Za-z][A-Za-z0-9_]{0,63}$/ or it is dropped silently. Absent,
+     * behavior is byte-identical to today. */
+    extraErrorSlugs?: readonly string[];
 }
 /** Deep-add b into a for the DayAgg shape (numbers add, maps union). */
 export declare function mergeDay(a: DayAgg, b: DayAgg): DayAgg;
@@ -108,6 +128,9 @@ export declare class Metrics {
     private dirty;
     private failures;
     private disabled;
+    private readonly sequencing;
+    private readonly eventLog;
+    private readonly errorSlugs;
     constructor(opts: InitOptions);
     private day;
     private initStorage;

package/dist/usage-metrics.js

@@ -4,14 +4,8 @@ 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.
+// Local usage metrics, default OFF; zero network egress is structural (a
+// tested import allowlist). See docs/usage-metrics.md.
 export const METRICS_DIR_NAME = 'metrics';
 const FLUSH_MS = 60_000;
 const RETRY_WINDOW_MS = 10 * 60_000;
@@ -26,17 +20,18 @@ 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).
+// arbitrary strings into recorded values.
 const METHOD_ID_RE = /^[a-z][a-zA-Z0-9]*(\.[a-zA-Z0-9]+)+$/;
 const METHOD_ID_MAX = 128;
 const TOOL_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
 // Declared argument keys are camelCase identifiers, some dotted
 // (groupKey.id, debugOptions.enableDebugging).
 const ARG_KEY_RE = /^[A-Za-z][A-Za-z0-9_.]{0,63}$/;
+const EXTRA_ERROR_SLUG_RE = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
 /** 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_ALIAS_EXISTS', 'E_CIMD_INVALID', 'E_ENV_ACCOUNTS_MODE', 'E_MCP_TOKEN_INVALID',
+    'E_ALIAS_EXISTS', 'E_CIMD_INVALID', 'E_CIMD_SSRF_BLOCKED', 'E_ENV_ACCOUNTS_MODE', 'E_MCP_TOKEN_INVALID',
     'E_NO_DEFAULT_ACCOUNT', 'E_UNKNOWN_BUNDLE', 'E_VALIDATION', 'ambiguous',
     'api_not_enabled', 'auth_required', 'bad_request', 'binary', 'binary_unsupported',
     'confirmation_declined', 'diagnose_failed', 'discovery_unavailable', 'dispatch_timeout',
@@ -44,7 +39,7 @@ export const KNOWN_ERROR_SLUGS = new Set([
     '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', 'recipient_not_allowed', 'too_large', 'toolset_disabled', 'unknown_api',
+    'reauth_required', 'recipient_not_allowed', 'temporarily_unavailable', 'tenant_not_found', 'too_large', 'toolset_disabled', 'unknown_api',
     'unknown_argument', 'unknown_method', 'unsupported_grant_type', 'unsupported_type',
     'untrusted_host', 'upstream_error', 'validation_error', 'write_disabled',
 ]);
@@ -221,7 +216,14 @@ export class Metrics {
     dirty = false;
     failures = 0;
     disabled = false;
+    sequencing;
+    eventLog;
+    errorSlugs;
     constructor(opts) {
+        this.sequencing = opts.sequencingEnabled !== false;
+        this.eventLog = opts.eventLog !== false;
+        const extras = (opts.extraErrorSlugs ?? []).filter((s) => EXTRA_ERROR_SLUG_RE.test(s));
+        this.errorSlugs = extras.length ? new Set([...KNOWN_ERROR_SLUGS, ...extras]) : KNOWN_ERROR_SLUGS;
         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');
@@ -250,7 +252,8 @@ export class Metrics {
                 }
             }
             this.pruneAggs();
-            this.pruneEventAge(this.eventsFile);
+            if (this.eventLog)
+                this.pruneEventAge(this.eventsFile);
         }
         catch (e) {
             this.log(`local usage metrics: init failed (${e.message}); disabled for this process\n`);
@@ -318,7 +321,7 @@ export class Metrics {
                 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';
+                        slug = this.errorSlugs.has(env.error) ? env.error : 'other';
                     hinted = typeof env.hint === 'string' && env.hint.length > 0;
                 }
             }
@@ -357,45 +360,50 @@ export class Metrics {
             f.calls += 1;
             addInto(f, fan);
         }
-        // retry self-correction chain (spec section 1): in-memory only.
+        // retry self-correction chain, in-memory only; links consecutive calls,
+        // so it only runs when one caller owns the process (sequencingEnabled).
         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}`);
+        if (this.sequencing) {
+            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 };
         }
-        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;
+        if (this.eventLog) {
+            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 (this.sequencing && entry.name === 'google_api_call' && this.pendingMid) {
+                event.mid = this.pendingMid;
+                this.pendingMid = undefined;
+            }
+            this.events.push(JSON.stringify(event));
         }
-        this.events.push(JSON.stringify(event));
         this.dirty = true;
     }
     /** Escape hatch: only the RESOLVED methodId (double-gated) or a miss. */
@@ -407,7 +415,8 @@ export class Metrics {
             }
             else if (idOrNull.length <= METHOD_ID_MAX && METHOD_ID_RE.test(idOrNull)) {
                 addInto(this.deltas.escape.methods, idOrNull);
-                this.pendingMid = idOrNull;
+                if (this.sequencing)
+                    this.pendingMid = idOrNull;
             }
             this.dirty = true;
         }
@@ -475,12 +484,14 @@ export class Metrics {
             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 && TOOL_NAME_RE.test(tool) ? tool : 'other',
-                ok: false, ms: 0, chars: 'le64', src: 'rpc',
-            }));
+            if (this.eventLog) {
+                this.events.push(JSON.stringify({
+                    ts: new Date(this.now()).toISOString().slice(0, 16) + ':00Z',
+                    boot: this.bootId, seq: this.seq++,
+                    tool: tool && TOOL_NAME_RE.test(tool) ? tool : 'other',
+                    ok: false, ms: 0, chars: 'le64', src: 'rpc',
+                }));
+            }
             this.dirty = true;
         }
         catch { /* never throws outward */ }

package/dist/write-control.d.ts

@@ -7,12 +7,11 @@ export interface Policy {
     allow: string[];
     deny: string[];
     /**
-     * B14 reserved seam (cc-write-control "HTTP posture", LOCKED to OQ-5
-     * "annotations only"): the dispatch transport is threaded into the resolved
-     * policy for the EE/future seam, but in v6 alpha it does NOT stiffen the
+     * Reserved seam (HTTP posture is "annotations only"): the dispatch
+     * transport is threaded into the resolved policy for a future seam, but in v6 alpha it does NOT stiffen the
      * profile or alter any `isAllowed` verdict. "Stricter on HTTP" is achieved
      * entirely by the `anthropic/requiresUserInteraction` annotation on the
-     * irreversible set (A12), emitted identically on both transports.
+     * irreversible set, emitted identically on both transports.
      * Optional so existing Policy literals (codegen/tests) need no change;
      * resolvePolicy always populates it.
      */
@@ -22,12 +21,9 @@ interface ToolRef {
     name: string;
     service: string;
     cud: Cud;
-    /** The method's required OAuth scopes, when the caller knows them. Absent
-     * means "unknown", which is treated as not privileged: a missing scope list
-     * must not silently widen the gate OR silently break an ordinary write. */
     scopes?: readonly string[];
 }
-/** The irreversible set (frozen, cc-write-control): real sends leave the
+/** The irreversible set (frozen): real sends leave the
  * user's (or org's) identity unrecallably; permanent deletes bypass Trash.
  * Includes the callable GENERATED twins of the curated ops — the surface is
  * always callable by name, so a prompt-free twin would defeat the layer.

package/dist/write-control.js

@@ -1,5 +1,6 @@
+import { hints } from './hint-provider.js';
 const PROFILES = ['read-only', 'safe-writes', 'full-writes'];
-/** The irreversible set (frozen, cc-write-control): real sends leave the
+/** The irreversible set (frozen): real sends leave the
  * user's (or org's) identity unrecallably; permanent deletes bypass Trash.
  * Includes the callable GENERATED twins of the curated ops — the surface is
  * always callable by name, so a prompt-free twin would defeat the layer.
@@ -63,9 +64,8 @@ function firstMatch(tool, globs) {
 function matchesAny(tool, globs) {
     return firstMatch(tool, globs) !== undefined;
 }
-/** Scopes that authorize acting on the whole organization, on legal holds, on
- * billing, or on deployed code. A write behind one of these is not a "safe"
- * write in any useful sense of the word, whatever its HTTP verb. */
+// Scopes that authorize acting on the whole organization, legal holds,
+// billing, or deployed code: not a "safe" write, whatever its HTTP verb.
 const PRIVILEGED_SCOPE_RE = /\/auth\/(admin\.directory|admin\.datatransfer|cloud-identity|apps\.licensing|apps\.order|apps\.groups\.settings|apps\.groups\.migration|ediscovery|script\.projects|script\.deployments)/;
 /** Registering a push channel hands this account's activity to an external URL.
  * It is shaped like a create and behaves like an export, so the verb hides it. */
@@ -155,10 +155,17 @@ export function writeDisabledResult(tool, policy, account) {
     // Recomputed rather than passed in: every call site has already run
     // isAllowed, and a hint that disagrees with the verdict is worse than none.
     const reason = denyReason(tool, policy) ?? { rule: 'profile', profile: policy.profile };
+    const rendered = hints()?.render({
+        kind: 'write_denied',
+        tool: { name: tool.name, service: tool.service, cud: tool.cud },
+        reason,
+        policy,
+    });
     const envelope = {
         error: 'write_disabled',
-        message: `"${tool.name}" (${tool.cud}) is disabled by the current write-control policy (profile: ${policy.profile}${policy.readOnly ? ', GOOGLE_READ_ONLY=true' : ''}).`,
-        hint: denyHint(tool, reason),
+        message: rendered?.message ??
+            `"${tool.name}" (${tool.cud}) is disabled by the current write-control policy (profile: ${policy.profile}${policy.readOnly ? ', GOOGLE_READ_ONLY=true' : ''}).`,
+        hint: rendered?.hint ?? denyHint(tool, reason),
         retriable: false,
         ...(account ? { account } : {}),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-beta.2",
+  "version": "6.0.0-beta.4",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "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",
@@ -9,6 +9,32 @@
     "mcp-google-multi": "dist/index.js"
   },
   "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./identity": "./dist/identity.js",
+    "./compose": "./dist/compose.js",
+    "./registry": "./dist/registry.js",
+    "./oauth-as": "./dist/oauth-as.js",
+    "./accounts": "./dist/accounts.js",
+    "./token-store": "./dist/token-store.js",
+    "./http-transport": "./dist/http-transport.js",
+    "./http-config": "./dist/http-config.js",
+    "./client": "./dist/client.js",
+    "./config-file": "./dist/config-file.js",
+    "./fs-atomic": "./dist/fs-atomic.js",
+    "./master-key": "./dist/master-key.js",
+    "./mcp-token": "./dist/mcp-token.js",
+    "./boot-gates": "./dist/boot-gates.js",
+    "./tenant-purge": "./dist/tenant-purge.js",
+    "./doctor": "./dist/doctor.js",
+    "./write-control": "./dist/write-control.js",
+    "./scope-catalog": "./dist/scope-catalog.js",
+    "./auth": "./dist/auth.js",
+    "./usage-metrics": "./dist/usage-metrics.js",
+    "./metrics-tap": "./dist/metrics-tap.js",
+    "./hint-provider": "./dist/hint-provider.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist"
   ],
@@ -65,29 +91,29 @@
     "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"
   },
   "dependencies": {
-    "@googleapis/admin": "^37.0.0",
-    "@googleapis/analyticsadmin": "^22.0.0",
-    "@googleapis/analyticsdata": "^10.0.0",
-    "@googleapis/calendar": "^20.0.0",
-    "@googleapis/chat": "^51.0.0",
-    "@googleapis/docs": "^14.0.0",
-    "@googleapis/drive": "^26.0.0",
-    "@googleapis/forms": "^11.0.0",
-    "@googleapis/gmail": "^22.0.0",
-    "@googleapis/meet": "^9.0.0",
-    "@googleapis/people": "^12.0.0",
-    "@googleapis/searchconsole": "^11.0.0",
-    "@googleapis/sheets": "^18.0.0",
-    "@googleapis/slides": "^10.0.0",
-    "@googleapis/tasks": "^17.0.0",
-    "@googleapis/webmasters": "^9.0.0",
+    "@googleapis/admin": "^37.0.2",
+    "@googleapis/analyticsadmin": "^22.0.1",
+    "@googleapis/analyticsdata": "^10.1.0",
+    "@googleapis/calendar": "^20.1.0",
+    "@googleapis/chat": "^51.2.0",
+    "@googleapis/docs": "^14.1.0",
+    "@googleapis/drive": "^26.0.2",
+    "@googleapis/forms": "^11.0.1",
+    "@googleapis/gmail": "^22.0.1",
+    "@googleapis/meet": "^9.1.0",
+    "@googleapis/people": "^12.0.1",
+    "@googleapis/searchconsole": "^11.0.1",
+    "@googleapis/sheets": "^18.1.1",
+    "@googleapis/slides": "^10.1.1",
+    "@googleapis/tasks": "^17.0.1",
+    "@googleapis/webmasters": "^9.0.1",
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
-    "googleapis-common": "^9.0.0",
+    "googleapis-common": "^9.3.0",
     "jose": "^6.2.8",
-    "markdown-it": "15.0.0",
+    "markdown-it": "15.0.2",
     "mime-types": "^3.0.2",
-    "nodemailer": "9.1.1",
+    "nodemailer": "10.1.0",
     "turndown": "7.2.4",
     "turndown-plugin-gfm": "1.0.2",
     "zod": "^4.3.6"
@@ -109,7 +135,7 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.1",
-    "vitest": "^3.2.6"
+    "vitest": "^5.0.4"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0"