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

package/dist/registry.js

@@ -1,17 +1,17 @@
 import { z } from 'zod';
 import { isAllowed, writeDisabledResult, IRREVERSIBLE_TOOLS } from './write-control.js';
-import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
+import { getAccountSet, isLiveAccountField, refreshAccountSetIfStale } from './accounts.js';
 import { compactResult, trimEnabled } from './trim.js';
-import { fanoutAccountField, invalidAccountsResult, parseAccountSelector, runFanout } from './fanout.js';
+import { fanoutAccountField, invalidAccountsResult, noAccountsResult, parseAccountSelector, runFanout } from './fanout.js';
 import { MAX_RESPONSE_CHARS } from './executor.js';
-import { suggestKeys } from './arg-strict.js';
+import { MAX_SUGGESTED_KEYS, suggestKeys } from './arg-strict.js';
 import { classifyScope } from './scope-observability.js';
+import { hints } from './hint-provider.js';
 /** Nothing granted, no profile: asks the BUNDLE CATALOG whether a scope is
  * reachable at all, independently of any account. */
 const EMPTY_SCOPES = new Set();
-// Client-side result budget advertised for tools that do not declare their own
-// (fat readers do; see trim.ts). ~50k chars stays well inside a default client
-// context limit while leaving room for real list payloads.
+// Client-side result budget for tools that do not declare their own (fat
+// readers do; see trim.ts); stays well inside a default client context limit.
 const DEFAULT_MAX_RESULT_CHARS = 50_000;
 const DISCOVERY_MODES = ['lazy', 'curated', 'eager'];
 export function resolveDiscoveryMode(env = process.env) {
@@ -28,9 +28,8 @@ const CUD_OVERRIDES = {
     drive_transfer: 'create',
     // read-only resolver; the name's "resolve" verb would otherwise infer update.
     contacts_resolve: 'read',
-    // Account management is gated by anthropic/requiresUserInteraction (forced
-    // human approval), NOT the Google-data write-control profile — so onboarding
-    // works under any profile. cud=read also keeps them off the fan-out path.
+    // Gated by anthropic/requiresUserInteraction, not write-control, so
+    // onboarding works under any profile; cud=read also keeps them off fan-out.
     account_add: 'read',
     account_reauth: 'read',
     // Writes a LOCAL MCP-client config, not Google data; gated by
@@ -40,12 +39,17 @@ const CUD_OVERRIDES = {
 const SERVICE_OVERRIDES = {
     reports_activities_list: 'admin',
 };
+/** The service a tool name belongs to: its prefix, unless overridden. */
+export function serviceOf(name) {
+    return Object.hasOwn(SERVICE_OVERRIDES, name) ? SERVICE_OVERRIDES[name] : name.includes('_') ? name.slice(0, name.indexOf('_')) : name;
+}
 // read tools that write local files — same savePath fanned across accounts would clobber
 const FANOUT_EXCLUDE = new Set(['gmail_download_attachment', 'drive_download', 'drive_export']);
-/** Account-management tools: the `account` they take is the SUBJECT of the
- * operation, not the identity it runs as, so injecting the configured default
- * would silently retarget them. `account_add` would adopt the default as the
- * new alias, and `account_reauth` would re-authenticate the wrong account. */
+// cud=read for gating/fan-out, yet they write (local files, the account
+// registry, config): advertised as writes so annotation-keyed clients prompt.
+const WRITES_DESPITE_READ = new Set([...FANOUT_EXCLUDE, 'account_add', 'account_reauth', 'account_write_config']);
+// Their `account` is the SUBJECT of the operation (e.g. the new alias to add),
+// not the identity to run as, so injecting the configured default would retarget them.
 const DEFAULT_ACCOUNT_EXCLUDE = new Set(['account_add', 'account_reauth']);
 /** Unwrap optional/default/nullable to the declared scalar kind (zod 4 defs). */
 function scalarKindOf(field) {
@@ -64,11 +68,15 @@ function scalarKindOf(field) {
     }
     return 'other';
 }
-function isAccountEnum(field) {
+/** A field naming one of the registry's accounts: a baked enum or a live
+ * account check (curated tools and generated tools both validate live). */
+function isAccountSelector(field) {
+    if (isLiveAccountField(field))
+        return true;
     const def = field?._zod?.def;
     if (!def)
         return false;
-    // A2 made account enums .optional(); unwrap it or fan-out silently dies.
+    // Account enums are .optional(); unwrap it or fan-out silently dies.
     if (def.type === 'optional')
         return def.innerType?._zod?.def?.type === 'enum';
     return def.type === 'enum';
@@ -91,14 +99,14 @@ export function inferCud(name) {
 export class ToolRegistry {
     server;
     metrics;
+    accounts;
     tools = [];
     policy;
     registerTool;
     revealed = new Set();
     jsonSchemaCache = new Map();
     argShapeCache = new Map();
-    /** Memoized isUngrantable verdict per tool: the answer depends on the frozen
-     * bundle catalog only, so it never changes within a process. */
+    // Memoized isUngrantable verdict: depends on the frozen bundle catalog only.
     ungrantable = new Map();
     compactOutput = trimEnabled();
     registeringMeta = false;
@@ -107,30 +115,29 @@ 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(), metrics = null) {
+    constructor(server, policy, mode = resolveDiscoveryMode(), metrics = null, 
+    // The registry's OWN account view, so one built over a subset never
+    // observes (or leaks) the global set.
+    accounts = getAccountSet) {
         this.server = server;
         this.metrics = metrics;
+        this.accounts = accounts;
         this.policy = policy;
         this.mode = mode;
         this.registerTool = ((name, config, handler) => {
-            const service = SERVICE_OVERRIDES[name] ?? (name.includes('_') ? name.slice(0, name.indexOf('_')) : name);
+            const service = serviceOf(name);
             const cud = config.cud ?? inferCud(name);
-            // destructiveHint=false claims "additive only" (MCP spec) — updates overwrite, so they stay true.
-            // idempotent: reads trivially, deletes (already-gone = same), updates
-            // (overwrite converges); creates are not (send twice = two emails).
+            // Every write is destructive (a create is no less consequential than an
+            // update); idempotent iff not a create (send twice = two emails).
+            const writes = cud !== 'read' || WRITES_DESPITE_READ.has(name);
             const annotations = {
-                readOnlyHint: cud === 'read',
-                destructiveHint: cud === 'delete' || cud === 'update',
+                readOnlyHint: !writes,
+                destructiveHint: writes,
                 idempotentHint: cud !== 'create',
                 ...config.annotations,
             };
-            // A12: forced per-call human approval on the irreversible set, even in
-            // bypass mode. Client-enforced via the wire _meta (Claude Code reads
-            // anthropic/* ONLY there); the server verdict stays separate.
-            // Every tool also advertises a result-size budget: fat readers declare
-            // their own, everything else inherits the default, so an uncapped tool
-            // can never blow past a client's context limit. Generated tools align
-            // with the executor's server-side cap.
+            // Irreversible-set approval and the result-size budget are both
+            // client-enforced via the wire _meta (anthropic/*); the server verdict stays separate.
             const clientMeta = {
                 'anthropic/maxResultSizeChars': config.cud !== undefined ? MAX_RESPONSE_CHARS : DEFAULT_MAX_RESULT_CHARS,
                 ...config._meta,
@@ -140,14 +147,16 @@ export class ToolRegistry {
             let inputShape = config.inputSchema ?? {};
             let baseHandler = handler;
             const hasAccountField = 'account' in inputShape && !DEFAULT_ACCOUNT_EXCLUDE.has(name);
-            if (cud === 'read' && !this.registeringMeta && !FANOUT_EXCLUDE.has(name) && isAccountEnum(inputShape.account)) {
+            if (cud === 'read' && !this.registeringMeta && !FANOUT_EXCLUDE.has(name) && isAccountSelector(inputShape.account)) {
                 const description = inputShape.account.description ?? 'Google account alias';
-                inputShape = { ...inputShape, account: fanoutAccountField(description) };
+                inputShape = { ...inputShape, account: fanoutAccountField(description, () => this.accounts().aliases) };
                 baseHandler = async (...args) => {
                     const first = args[0];
-                    const parsed = parseAccountSelector(typeof first?.account === 'string' ? first.account : '');
+                    const parsed = parseAccountSelector(typeof first?.account === 'string' ? first.account : '', this.accounts().aliases);
                     if (!parsed.ok)
-                        return invalidAccountsResult(parsed.invalid);
+                        return invalidAccountsResult(parsed.invalid, this.accounts().aliases);
+                    if (parsed.aliases.length === 0)
+                        return noAccountsResult();
                     if (!parsed.fanout)
                         return handler({ ...first, account: parsed.aliases[0] }, ...args.slice(1));
                     return runFanout(handler, args, parsed.aliases);
@@ -173,10 +182,8 @@ export class ToolRegistry {
                     : writeDisabledResult({ name, service, cud, scopes: config.requiredScopes }, policy, 
                     // Concrete by here: default-account injection wraps this.
                     args[0]?.account);
-            // A2: the ONE default-account injection site — outside the CUD gate and
-            // the fan-out parse so both observe a concrete alias; NOT meta-skipped
-            // (that is what covers google_api_call with zero bespoke code). Explicit
-            // aliases, "*" and CSV pass through untouched.
+            // The ONE default-account injection site, outside the CUD gate and the
+            // fan-out parse (not meta-skipped, which is what covers google_api_call).
             const withDefault = !hasAccountField
                 ? guarded
                 : (...args) => {
@@ -184,12 +191,13 @@ export class ToolRegistry {
                     const value = first?.account;
                     if (value != null && value !== '')
                         return guarded(...args);
-                    // Refresh here or the unset->configured default transition never
-                    // heals for a client that always omits account (this branch never
-                    // reaches getClient's probe). One stat, only on omission.
+                    // Refresh here, or a client that always omits account never heals
+                    // the unset->configured default transition (getClient's probe is unreached).
                     refreshAccountSetIfStale();
-                    const def = getAccountSet().defaultAccount;
+                    const def = this.accounts().defaultAccount;
                     if (!def) {
+                        const aliases = this.accounts().aliases;
+                        const rendered = hints()?.render({ kind: 'no_default_account', aliases });
                         return {
                             content: [
                                 {
@@ -197,7 +205,7 @@ export class ToolRegistry {
                                     text: JSON.stringify({
                                         error: 'E_NO_DEFAULT_ACCOUNT',
                                         message: 'No "account" given and no default account is configured.',
-                                        hint: `Pass account explicitly (valid: ${getAccountSet().aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
+                                        hint: rendered?.hint ?? `Pass account explicitly (valid: ${aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
                                         retriable: false,
                                     }),
                                 },
@@ -210,16 +218,14 @@ 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.
+            // Usage metrics wrap outermost, only when enabled (off = byte-identical
+            // to the pre-metrics chain); fan-out width is derived here 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);
+                    const sel = parseAccountSelector(v, this.accounts().aliases);
                     return sel.ok ? sel.aliases.length : 1;
                 })
                 : finalHandler;
@@ -239,6 +245,16 @@ export class ToolRegistry {
     services() {
         return [...new Set(this.tools.filter((t) => !t.meta).map((t) => t.service))];
     }
+    /** The registry's OWN alias list: registration-time schema builders (the
+     * generated account enums) read this, never the process global. */
+    accountAliases() {
+        return this.accounts().aliases;
+    }
+    /** The registry's OWN account set: handlers needing an account's email or
+     * profile read this, never the process global. */
+    accountSet() {
+        return this.accounts();
+    }
     /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
      * normalization; the kind drives value coercion on renamed keys). */
     argShape(name) {
@@ -272,10 +288,8 @@ export class ToolRegistry {
         const declared = new Set(Object.keys(self.inputShape));
         const byKey = new Map();
         for (const t of this.tools) {
-            // Only tools the agent can actually see in tools/list. A hint naming a
-            // registered-but-unadvertised generated tool turns a recoverable error
-            // into a dead end: in curated mode 353 tools are registered and 181 are
-            // advertised, and the hint used to reach for any of them.
+            // Only tools visible in tools/list: a hint naming a hidden generated
+            // tool would turn a recoverable error into a dead end.
             if (t.service !== self.service || t.name === tool || !this.isVisible(t))
                 continue;
             for (const key of Object.keys(t.inputShape)) {
@@ -289,11 +303,10 @@ export class ToolRegistry {
             }
         }
         const candidates = [...byKey.entries()].filter(([, e]) => e.tools.length >= 2 || e.curated);
-        // Reuse the tiered matcher rather than a substring test: the motivating
-        // case (parentId against parentFolderId) fails containment and edit
-        // distance alike, which is the whole reason that matcher exists.
+        // The tiered matcher, not a substring test: parentId vs parentFolderId
+        // fails both containment and edit distance.
         const keys = candidates.map(([key]) => key);
-        const hits = new Set(unknownKeys.flatMap((k) => suggestKeys(k, keys)));
+        const hits = new Set(unknownKeys.slice(0, MAX_SUGGESTED_KEYS).flatMap((k) => suggestKeys(k, keys)));
         return candidates
             .filter(([key]) => hits.has(key))
             .slice(0, 2)
@@ -357,7 +370,7 @@ export class ToolRegistry {
         return true;
     }
     /** discover_reset: back to the lean meta-only surface. Clears reveals too.
-     * BV-8: if a client mishandles a SHRINKING tools/list, this degrades to a
+     * If a client mishandles a SHRINKING tools/list, this degrades to a
      * no-op for that session — tools stay callable regardless (graceful
      * dispatch), zero correctness impact. */
     collapse() {
@@ -387,11 +400,8 @@ export class ToolRegistry {
         const cached = this.ungrantable.get(tool.name);
         if (cached !== undefined)
             return cached;
-        // EVERY alternative must be ungrantable. `classifyMethodScopes` cannot
-        // answer this: `add_bundle` and `unknown_scope` share the
-        // `not_requestable` rank, so its first-best match hides a grantable
-        // alternative that appears later in the list. Discovery scope lists are
-        // ANY-OF, so one grantable alternative makes the method reachable.
+        // EVERY alternative must be ungrantable (scope lists are ANY-OF); a
+        // first-best classifyScope match would hide a grantable one later in the list.
         const verdict = tool.requiredScopes.every((scope) => {
             const c = classifyScope(scope, EMPTY_SCOPES, EMPTY_SCOPES);
             return c.state === 'not_requestable' && c.reason === 'unknown_scope';
@@ -401,10 +411,8 @@ export class ToolRegistry {
     }
     isVisible(tool) {
         const mode = this.effectiveMode();
-        // Advertising a tool that can never succeed spends context budget to hand
-        // the agent a dead end. It stays registered and callable, so calling it by
-        // name still produces the real scope error plus its remediation, and
-        // {service}_discover still lists it, marked.
+        // Hidden, not unregistered: calling an ungrantable tool by name still
+        // produces the real scope error, and {service}_discover still lists it, marked.
         if (!tool.meta && this.isUngrantable(tool))
             return false;
         return (tool.meta ||
@@ -424,10 +432,7 @@ export class ToolRegistry {
             throw new Error('installListHandler() requires at least one registered tool');
         }
         this.server.server.setRequestHandler('tools/list', async () => ({
-            // The wire Tool is hand-built because the SDK's own types drop the
-            // anthropic/* _meta keys honoring clients read. z.toJSONSchema emits a
-            // valid draft-7 object schema by construction, which the SDK's recursive
-            // JSON-Schema type cannot infer from our cached `unknown`.
+            // Hand-built: the SDK's own Tool type drops the anthropic/* _meta keys honoring clients read.
             tools: this.tools.filter((t) => this.isVisible(t)).map((t) => this.toToolJson(t)),
         }));
     }
@@ -440,9 +445,32 @@ export class ToolRegistry {
         return {
             name: tool.name,
             description: tool.description,
-            inputSchema,
+            inputSchema: this.withLiveAccountEnum(tool, inputSchema),
             annotations: tool.annotations,
             ...(tool.clientMeta ? { _meta: tool.clientMeta } : {}),
         };
     }
+    // Refreshes the account enum's values per call (structural schema stays
+    // cached), so a cached boot-time list doesn't go stale once account_add runs mid-session.
+    withLiveAccountEnum(tool, schema) {
+        if (DEFAULT_ACCOUNT_EXCLUDE.has(tool.name))
+            return schema;
+        const s = schema;
+        const account = s?.properties?.account;
+        if (!account)
+            return schema;
+        const aliases = this.accounts().aliases;
+        if (aliases.length === 0)
+            return schema;
+        if (Array.isArray(account.anyOf)) {
+            // fan-out union: advertise '*' + the live aliases on the selector branch
+            // (the one without the CSV pattern), keep the CSV branch as is
+            const isSelector = (b) => b.pattern === undefined;
+            if (!account.anyOf.some(isSelector))
+                return schema;
+            const anyOf = account.anyOf.map((b) => (isSelector(b) ? { ...b, enum: ['*', ...aliases] } : b));
+            return { ...s, properties: { ...s.properties, account: { ...account, anyOf } } };
+        }
+        return { ...s, properties: { ...s.properties, account: { ...account, enum: [...aliases] } } };
+    }
 }

package/dist/scope-catalog.d.ts

@@ -8,13 +8,29 @@ export interface BundleCatalogEntry {
     description: string;
     risk: 'low' | 'medium' | 'high';
     workspaceOnly?: boolean;
+    personalRefused?: boolean;
 }
 export declare const ADMIN_SCOPES: string[];
 export declare const BUNDLE_CATALOG: Record<string, BundleCatalogEntry>;
 /** One-way soft-rename map (UD5): empty at 6.0.0; the mechanism ships now so a
  * future rename is a deprecation warning, never a breaking config change. */
 export declare const BUNDLE_ALIASES: Record<string, string>;
+/** Bundle names are user input: an Object.prototype member ("constructor",
+ * "toString") passes a plain `in` or index lookup, so membership is own-key only. */
+export declare function isKnownBundle(name: string): boolean;
+/** A gmail.com or googlemail.com address, which is always a personal Google account. */
+export declare function isPersonalGoogleAddress(email: string): boolean;
+/** The bundles in `bundles` that Google refuses on the consent screen of the account at `email`. */
+export declare function refusedBundlesFor(email: string, bundles: readonly string[]): string[];
 export declare function resolveBundleAliases(bundles: string[]): string[];
 /** Closest catalog key for E_UNKNOWN_BUNDLE remediation (edit distance <= 2). */
 export declare function closestBundle(name: string): string | undefined;
+/** Longest input any did-you-mean compares. Every name it suggests (tool,
+ * argument key, bundle, Discovery method id) is far shorter, and the inputs
+ * are caller-controlled: an unbounded comparison let one oversized name block
+ * the event loop for minutes. */
+export declare const SUGGEST_MAX_INPUT = 128;
+/** Levenshtein distance. Past SUGGEST_MAX_INPUT it returns the longer length
+ * without comparing: an upper bound on the true distance, and above every
+ * caller's accept threshold, so a capped pair is never suggested. */
 export declare function editDistance(a: string, b: string): number;

package/dist/scope-catalog.js

@@ -1,7 +1,5 @@
-// The curated bundle catalog: ONE source of truth consumed by the wizard
-// picker, scope observability (#114) hints, and docs. Keys are a frozen
-// public API (config.json references them by name) — renames go through
-// BUNDLE_ALIASES, never in place.
+// The curated bundle catalog: ONE source of truth for the wizard, scope
+// observability, and docs. Keys are a frozen public API; rename via BUNDLE_ALIASES only.
 export const ADMIN_SCOPES = [
     'https://www.googleapis.com/auth/admin.reports.audit.readonly',
     'https://www.googleapis.com/auth/admin.directory.user',
@@ -63,6 +61,7 @@ export const BUNDLE_CATALOG = {
         ],
         description: 'Manage Cloud Identity groups and devices across the directory.',
         risk: 'high',
+        personalRefused: true,
     },
     cloudsearch: {
         scopes: ['https://www.googleapis.com/auth/cloud_search'],
@@ -79,6 +78,7 @@ export const BUNDLE_CATALOG = {
         scopes: ['https://www.googleapis.com/auth/keep'],
         description: 'Read and edit Google Keep notes.',
         risk: 'low',
+        personalRefused: true,
     },
     driveactivity: {
         scopes: ['https://www.googleapis.com/auth/drive.activity.readonly'],
@@ -113,9 +113,8 @@ export const BUNDLE_CATALOG = {
         description: 'Read Google Analytics (GA4): run reports and inspect accounts, properties and their configuration.',
         risk: 'low',
     },
-    // Includes readonly so it is self-sufficient: analytics.edit alone does not
-    // authorize Data API reads. The smaller `analytics` bundle stays the hint
-    // target for read scopes (scope-observability sorts bundles by size).
+    // Includes readonly so it's self-sufficient: analytics.edit alone doesn't
+    // authorize Data API reads.
     analytics_write: {
         scopes: [
             'https://www.googleapis.com/auth/analytics.readonly',
@@ -160,9 +159,25 @@ export const BUNDLE_CATALOG = {
  * future rename is a deprecation warning, never a breaking config change. */
 export const BUNDLE_ALIASES = {};
 const warnedAliases = new Set();
+/** Bundle names are user input: an Object.prototype member ("constructor",
+ * "toString") passes a plain `in` or index lookup, so membership is own-key only. */
+export function isKnownBundle(name) {
+    return Object.hasOwn(BUNDLE_CATALOG, name);
+}
+const PERSONAL_ADDRESS_RE = /@(?:gmail|googlemail)\.com$/i;
+/** A gmail.com or googlemail.com address, which is always a personal Google account. */
+export function isPersonalGoogleAddress(email) {
+    return PERSONAL_ADDRESS_RE.test(email.trim());
+}
+/** The bundles in `bundles` that Google refuses on the consent screen of the account at `email`. */
+export function refusedBundlesFor(email, bundles) {
+    if (!isPersonalGoogleAddress(email))
+        return [];
+    return bundles.filter((b) => isKnownBundle(b) && BUNDLE_CATALOG[b].personalRefused === true);
+}
 export function resolveBundleAliases(bundles) {
     return bundles.map((name) => {
-        const target = BUNDLE_ALIASES[name];
+        const target = Object.hasOwn(BUNDLE_ALIASES, name) ? BUNDLE_ALIASES[name] : undefined;
         if (!target)
             return name;
         if (!warnedAliases.has(name)) {
@@ -177,6 +192,8 @@ export function closestBundle(name) {
     let best;
     let bestDist = 3;
     for (const key of Object.keys(BUNDLE_CATALOG)) {
+        if (Math.abs(name.length - key.length) >= bestDist)
+            continue;
         const d = editDistance(name.toLowerCase(), key);
         if (d < bestDist) {
             bestDist = d;
@@ -185,14 +202,24 @@ export function closestBundle(name) {
     }
     return best;
 }
+/** Longest input any did-you-mean compares. Every name it suggests (tool,
+ * argument key, bundle, Discovery method id) is far shorter, and the inputs
+ * are caller-controlled: an unbounded comparison let one oversized name block
+ * the event loop for minutes. */
+export const SUGGEST_MAX_INPUT = 128;
+/** Levenshtein distance. Past SUGGEST_MAX_INPUT it returns the longer length
+ * without comparing: an upper bound on the true distance, and above every
+ * caller's accept threshold, so a capped pair is never suggested. */
 export function editDistance(a, b) {
-    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
-    for (let j = 1; j <= b.length; j++)
-        dp[0][j] = j;
+    if (a.length > SUGGEST_MAX_INPUT || b.length > SUGGEST_MAX_INPUT)
+        return Math.max(a.length, b.length);
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
     for (let i = 1; i <= a.length; i++) {
+        const row = [i];
         for (let j = 1; j <= b.length; j++) {
-            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
         }
+        prev = row;
     }
-    return dp[a.length][b.length];
+    return prev[b.length];
 }

package/dist/scope-observability.d.ts

@@ -1,4 +1,3 @@
-import { resolveScopesForAccount } from './auth.js';
 import { readToken } from './token-store.js';
 export type ScopeState = 'callable' | 'requestable_not_granted' | 'not_requestable';
 export type NotRequestableReason = 'add_bundle' | 'account_type' | 'unknown_scope';
@@ -35,12 +34,15 @@ export interface AccountScopeSets {
     granted: Set<string>;
     profile: Set<string>;
 }
+/** Where a scope hint reads the granted token and the configured profile;
+ * absent = the single-owner token store and global registry. */
+export interface ScopeSetDeps {
+    readTokenFn?: typeof readToken;
+    profileFn?: (alias: string) => string[];
+}
 /** Best-effort per-account sets; null when the token/profile is unreadable
  * (decrypt error, missing token) — callers fall back to generic hints. */
-export declare function accountScopeSets(alias: string, deps?: {
-    readTokenFn?: typeof readToken;
-    profileFn?: typeof resolveScopesForAccount;
-}): AccountScopeSets | null;
+export declare function accountScopeSets(alias: string, deps?: ScopeSetDeps): AccountScopeSets | null;
 /**
  * Runtime enrichment for a scope 403 on a method whose required scopes are
  * known (escape hatch: runtime Discovery; generated tools: baked). The
@@ -48,7 +50,7 @@ export declare function accountScopeSets(alias: string, deps?: {
  * profile means Google refuses it for this account type (personal Gmail),
  * so re-auth would loop — report the dead end instead.
  */
-export declare function scopeHintForMethod(required: readonly string[], alias: string, deps?: Parameters<typeof accountScopeSets>[1]): {
+export declare function scopeHintForMethod(required: readonly string[], alias: string, deps?: ScopeSetDeps): {
     hint: string;
     retriable: boolean;
 } | null;
@@ -63,7 +65,7 @@ export interface ScopesReport {
             bundle: string;
         }[];
         /** Runtime-signal bucket: static classification cannot prove account
-         * type; doctor (B9) fills it from observed persistent admin 403s. */
+         * type; doctor fills it from observed persistent admin 403s. */
         accountType: string[];
         unknown: string[];
     };
@@ -71,8 +73,7 @@ export interface ScopesReport {
 }
 /**
  * The account_list / doctor block. Universe = profile ∪ granted ∪ the scopes
- * required by REGISTERED tools ("registered but not requestable" is the
- * original #114 ask).
+ * required by REGISTERED tools ("registered but not requestable" included).
  */
 export declare function buildScopesReport(granted: ReadonlySet<string>, profile: ReadonlySet<string>, registeredScopes?: Iterable<string>): ScopesReport;
 export declare function clearScopeIndexForTest(): void;

package/dist/scope-observability.js

@@ -1,9 +1,10 @@
 import { ADMIN_SCOPES, BUNDLE_CATALOG } from './scope-catalog.js';
 import { BASE_SCOPES, resolveScopesForAccount } from './auth.js';
 import { readToken } from './token-store.js';
-// Reverse index scope -> bundles offering it, narrowest bundle first (fewest
-// scopes) so the remediation names the smallest grant. BASE_SCOPES map to the
-// pseudo-bundle "base" (outside a profile only via includesBase:false).
+import { reauthHint } from './reauth-hint.js';
+import { hints } from './hint-provider.js';
+// Reverse index scope -> bundles offering it, narrowest first, so the
+// remediation names the smallest grant.
 let reverseIndex = null;
 function scopeIndex() {
     if (reverseIndex)
@@ -71,40 +72,51 @@ export function classifyMethodScopes(alternatives, granted, profile) {
  */
 export function scopeHint(scope, c, alias) {
     switch (c.state) {
-        case 'requestable_not_granted':
+        case 'requestable_not_granted': {
+            const rendered = hints()?.render({ kind: 'scope_not_granted', account: alias, scope });
             return {
-                hint: `Scope ${scope} is in ${alias}'s profile but not granted (you unchecked it at consent). ` +
-                    `Re-grant: npx mcp-google-multi auth --account ${alias}`,
-                retriable: true,
+                hint: rendered?.hint ??
+                    (`Scope ${scope} is in ${alias}'s profile but not granted (you unchecked it at consent). ` +
+                        reauthHint(alias)),
+                // The ONE kind whose retriable the host may flip, since the fix needs the user in a browser.
+                retriable: rendered?.retriable ?? true,
             };
+        }
         case 'not_requestable':
             if (c.reason === 'add_bundle') {
-                // "base" is a pseudo-bundle (BASE_SCOPES excluded by includesBase:
-                // false), NOT a catalog key — telling users to add it to bundles[]
-                // would fail boot with E_UNKNOWN_BUNDLE.
+                // "base" is a pseudo-bundle, not a catalog key: telling users to add
+                // it to bundles[] would fail boot with E_UNKNOWN_BUNDLE.
                 if (c.bundle === 'base') {
+                    const rendered = hints()?.render({ kind: 'scope_base_excluded', account: alias, scope });
                     return {
-                        hint: `Scope ${scope} is a base scope excluded by "includesBase": false in ${alias}'s profile. ` +
-                            `Set includesBase back to true (or remove it) in config.json, then npx mcp-google-multi auth --account ${alias}`,
+                        hint: rendered?.hint ??
+                            (`Scope ${scope} is a base scope excluded by "includesBase": false in ${alias}'s profile. ` +
+                                `Set includesBase back to true (or remove it) in config.json, then npx mcp-google-multi auth --account ${alias}`),
                         retriable: false,
                     };
                 }
+                const rendered = hints()?.render({ kind: 'scope_needs_bundle', account: alias, scope, bundle: c.bundle });
                 return {
-                    hint: `Scope ${scope} needs the "${c.bundle}" bundle, which is not in ${alias}'s profile. ` +
-                        `Add it: set ${alias}'s profile bundles to include "${c.bundle}" in config.json, then npx mcp-google-multi auth --account ${alias}`,
+                    hint: rendered?.hint ??
+                        (`Scope ${scope} needs the "${c.bundle}" bundle, which is not in ${alias}'s profile. ` +
+                            `Add it: set ${alias}'s profile bundles to include "${c.bundle}" in config.json, then npx mcp-google-multi auth --account ${alias}`),
                     retriable: false,
                 };
             }
             if (c.reason === 'account_type') {
+                const rendered = hints()?.render({ kind: 'scope_account_type', account: alias, scope });
                 return {
-                    hint: `Scope ${scope} requires a Google Workspace account; ${alias} is a personal account and will 403. Use a Workspace alias. Do not retry.`,
+                    hint: rendered?.hint ?? `Scope ${scope} requires a Google Workspace account; ${alias} is a personal account and will 403. Use a Workspace alias. Do not retry.`,
+                    retriable: false,
+                };
+            }
+            {
+                const rendered = hints()?.render({ kind: 'scope_unknown_scope', scope });
+                return {
+                    hint: rendered?.hint ?? `Scope ${scope} is not offered by this server (no bundle grants it). Not requestable. Do not retry.`,
                     retriable: false,
                 };
             }
-            return {
-                hint: `Scope ${scope} is not offered by this server (no bundle grants it). Not requestable. Do not retry.`,
-                retriable: false,
-            };
         default:
             return { hint: '', retriable: true };
     }
@@ -137,9 +149,8 @@ export function scopeHintForMethod(required, alias, deps = {}) {
     if (!best || best.state === 'callable')
         return null; // 403 despite grants: not a scope-classification problem
     const base = scopeHint(best.scope, best.classification, alias);
-    // Hedged, never fabricated: an in-profile admin scope that 403s is EITHER a
-    // Workspace account needing re-auth OR a personal account that can never be
-    // granted admin — the inputs cannot distinguish, so say both.
+    // Hedged, never fabricated: the inputs can't distinguish a Workspace account
+    // needing re-auth from a personal account that can never grant admin, so say both.
     if (best.state === 'requestable_not_granted' && ADMIN_SCOPES.includes(best.scope)) {
         return {
             hint: `${base.hint} Note: personal (non-Workspace) accounts can never grant admin scopes — if ${alias} is a personal Gmail account, use a Workspace alias instead.`,
@@ -150,8 +161,7 @@ export function scopeHintForMethod(required, alias, deps = {}) {
 }
 /**
  * The account_list / doctor block. Universe = profile ∪ granted ∪ the scopes
- * required by REGISTERED tools ("registered but not requestable" is the
- * original #114 ask).
+ * required by REGISTERED tools ("registered but not requestable" included).
  */
 export function buildScopesReport(granted, profile, registeredScopes = []) {
     const callable = [];