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

package/dist/tools/_errors.js

@@ -1,5 +1,6 @@
 import { reauthHint } from '../reauth-hint.js';
 import { sliceClean, sliceEncoded } from '../trim.js';
+import { hints as hintProvider } from '../hint-provider.js';
 const MAX_ERROR_MESSAGE_CHARS = 1000;
 const MAX_ERROR_ENVELOPE_CHARS = 4000;
 const MAX_BODY_PARSE_CHARS = 64_000;
@@ -175,10 +176,11 @@ function rateLimited(error, message, account, reason) {
         };
     }
     if (reason === 'dailyLimitExceeded') {
+        const rendered = hintProvider()?.render({ kind: 'daily_quota' });
         return {
             error: 'rate_limited',
             message,
-            hint: 'A per-day project quota, not a burst limit: it resets at midnight Pacific. Reduce call volume or raise the quota in the Cloud Console; a tight retry loop will not clear it.',
+            hint: rendered?.hint ?? 'A per-day project quota, not a burst limit: it resets at midnight Pacific. Reduce call volume or raise the quota in the Cloud Console; a tight retry loop will not clear it.',
             retriable: true,
             account,
         };
@@ -222,21 +224,24 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         .filter(Boolean)
         .join(' ');
     if ((status === 400 || status === 401) && /invalid_grant/i.test(grantHaystack)) {
+        const rendered = hintProvider()?.render({ kind: 'dead_refresh_token', account });
         return {
             error: 'reauth_required',
             message,
-            hint: `Refresh token for "${account}" is dead (often the 7-day Testing-mode trap). ` +
-                'Set Publishing status to In production at https://console.cloud.google.com/auth/audience, ' +
-                `then ${reauthHint(account)}`,
+            hint: rendered?.hint ??
+                (`Refresh token for "${account}" is dead (often the 7-day Testing-mode trap). ` +
+                    'Set Publishing status to In production at https://console.cloud.google.com/auth/audience, ' +
+                    `then ${reauthHint(account)}`),
             retriable: false,
             account,
         };
     }
     if (status === 401) {
+        const rendered = hintProvider()?.render({ kind: 'reauth', account });
         return {
             error: 'auth_required',
             message: `Authentication failed for account "${account}".`,
-            hint: reauthHint(account),
+            hint: rendered?.hint ?? reauthHint(account),
             retriable: false,
             account,
         };
@@ -252,7 +257,14 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             reason === 'SERVICE_DISABLED' ||
             /has not been used in project|accessNotConfigured|SERVICE_DISABLED|it is disabled/i.test(message);
         if (notEnabled) {
-            return { error: 'api_not_enabled', message, hint: enableHint(info, message), retriable: false, account };
+            const rendered = hintProvider()?.render({
+                kind: 'api_not_enabled',
+                api: disabledApiId(message) ?? undefined,
+                service: info?.metadata?.service,
+                project: info?.metadata?.consumer?.replace(/^projects\//, ''),
+                googleMessage: message,
+            });
+            return { error: 'api_not_enabled', message, hint: rendered?.hint ?? enableHint(info, message), retriable: false, account };
         }
         // The scope hint fires ONLY on the machine-readable token. A coarse AIP
         // status of PERMISSION_DENIED is equally true of a resource denial, and
@@ -262,10 +274,13 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             /\bACCESS_TOKEN_SCOPE_INSUFFICIENT\b/.test(message);
         if (scopeIssue) {
             const enriched = scopeContext?.() ?? null;
+            const fallback = enriched
+                ? null
+                : hintProvider()?.render({ kind: 'scope_unknown', account, serviceText: hints.scope, bundle: hints.bundle });
             return {
                 error: 'insufficient_scope',
                 message,
-                hint: enriched?.hint ?? hints.scope ?? `Re-auth "${account}" with the scope this operation needs. ${reauthHint(account)}`,
+                hint: enriched?.hint ?? fallback?.hint ?? hints.scope ?? `Re-auth "${account}" with the scope this operation needs. ${reauthHint(account)}`,
                 retriable: enriched?.retriable ?? false,
                 account,
             };
@@ -274,7 +289,8 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             return { error: 'forbidden', message, hint: `Drive storage for "${account}" is full. Free space or use another account; retrying will not help.`, retriable: false, account };
         }
         if (reason === 'CONSUMER_SUSPENDED' || reason === 'accountSuspended') {
-            return { error: 'forbidden', message, hint: `Google has suspended the project or the account behind "${account}". Check the Cloud Console notifications; no change to the request will fix this.`, retriable: false, account };
+            const rendered = hintProvider()?.render({ kind: 'project_suspended', account });
+            return { error: 'forbidden', message, hint: rendered?.hint ?? `Google has suspended the project or the account behind "${account}". Check the Cloud Console notifications; no change to the request will fix this.`, retriable: false, account };
         }
         if (reason === 'domainPolicy' || reason === 'ORG_RESTRICTION_VIOLATION') {
             return { error: 'forbidden', message, hint: `A Workspace admin policy blocks this operation for the domain of "${account}". A super-admin has to allow the app or the feature; re-auth will not change it.`, retriable: false, account };
@@ -289,10 +305,11 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         };
     }
     if (status === 400 && /invalid[_ ]scope/i.test(message)) {
+        const rendered = hintProvider()?.render({ kind: 'invalid_scope', account });
         return {
             error: 'invalid_scope',
             message,
-            hint: 'One of the requested OAuth scopes is malformed or unavailable to this client. Run `config check` to review the account scope profile, fix it, then re-auth.',
+            hint: rendered?.hint ?? 'One of the requested OAuth scopes is malformed or unavailable to this client. Run `config check` to review the account scope profile, fix it, then re-auth.',
             retriable: false,
             account,
         };
@@ -335,13 +352,15 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         // The server's own preconditions, tagged at the throw site in client.ts.
         // Untagged they reached the floor and were reported as Google failures.
         if (error?.code === 'E_NO_TOKEN') {
-            return { error: 'auth_required', message, hint: reauthHint(account), retriable: false, account };
+            const rendered = hintProvider()?.render({ kind: 'reauth', account });
+            return { error: 'auth_required', message, hint: rendered?.hint ?? reauthHint(account), retriable: false, account };
         }
         if (error?.code === 'E_NO_OAUTH_CLIENT') {
+            const rendered = hintProvider()?.render({ kind: 'no_oauth_client' });
             return {
                 error: 'invalid_client',
                 message,
-                hint: 'Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (see docs/google-cloud-setup.md), then restart the server.',
+                hint: rendered?.hint ?? 'Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (see docs/google-cloud-setup.md), then restart the server.',
                 retriable: false,
                 account,
             };
@@ -357,23 +376,30 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         }
         const fsCode = typeof error?.code === 'string' && LOCAL_FS_CODES.has(error.code) ? error.code : undefined;
         if (fsCode) {
-            const p = typeof error?.path === 'string' ? ` "${error.path}"` : '';
+            const p = typeof error?.path === 'string' ? error.path : undefined;
+            const rendered = hintProvider()?.render({ kind: 'local_path', code: fsCode, path: p });
             return {
                 error: 'invalid_params',
-                message: `Cannot access local path${p}: ${fsCode}`,
-                hint: 'The path must exist on the machine running this server and be accessible to it. ' +
-                    'When the server runs remotely (HTTP transport), paths on your own machine are not visible to it.',
+                message: rendered?.message ?? `Cannot access local path${p ? ` "${p}"` : ''}: ${fsCode}`,
+                hint: rendered?.hint ??
+                    ('The path must exist on the machine running this server and be accessible to it. ' +
+                        'When the server runs remotely (HTTP transport), paths on your own machine are not visible to it.'),
                 retriable: false,
                 account,
             };
         }
         const netCode = netCodeOf(error);
         if (netCode) {
+            const rendered = hintProvider()?.render({ kind: 'network_error', code: netCode });
             return {
                 error: 'network_error',
                 message: message.includes(netCode) ? message : message.endsWith('reason: ') ? `${message}${netCode}` : `${message} (${netCode})`,
-                hint: `Network failure (${netCode}) before reaching Google - not an auth or API problem. Usually transient: retry. ` +
-                    'If it persists on a high-latency or broken-IPv6 link, raise the happy-eyeballs budget: NODE_OPTIONS=--network-family-autoselection-attempt-timeout=4000 (server default 2000ms), and check connectivity with curl.',
+                hint: rendered?.hint ??
+                    (`Network failure (${netCode}) before reaching Google - not an auth or API problem. Usually transient: retry. ` +
+                        'If it persists on a high-latency or broken-IPv6 link, raise the happy-eyeballs budget: NODE_OPTIONS=--network-family-autoselection-attempt-timeout=4000 (server default 2000ms), and check connectivity with curl.'),
+                // Not an override site (C5 is the only kind whose retriable the host
+                // may flip): a multi-tenant host keeps core's retriable codes for
+                // network_error.
                 retriable: RETRIABLE_NET_CODES.has(netCode),
                 account,
             };
@@ -392,13 +418,16 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             account,
         };
     }
-    return {
-        error: 'internal',
-        message,
-        hint: 'This failed inside the MCP server, before any request was sent. The message above is the signal: it is most often a configuration problem such as a missing key or credential. Retrying the same call will fail the same way.',
-        retriable: false,
-        account,
-    };
+    {
+        const rendered = hintProvider()?.render({ kind: 'internal', account });
+        return {
+            error: 'internal',
+            message: rendered?.message ?? message,
+            hint: rendered?.hint ?? 'This failed inside the MCP server, before any request was sent. The message above is the signal: it is most often a configuration problem such as a missing key or credential. Retrying the same call will fail the same way.',
+            retriable: false,
+            account,
+        };
+    }
 }
 /** Bound the SERIALIZED envelope, not just the message: an authored hint can
  * be long too, and the error path had no cap at all before this. */

package/dist/tools/_local-files.d.ts

@@ -1,3 +1,12 @@
 import * as fs from 'fs';
+/** Refusal for a host-file argument on a context that may not touch the
+ * server's disk: the host belongs to its operator, not to every caller. */
+export declare function hostFilesRefused(account: string | undefined, what: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
 export declare function prepareLocalDest(savePath: string, filename: string): string;
 export declare function openLocalReadStream(localPath: string): Promise<fs.ReadStream>;

package/dist/tools/_local-files.js

@@ -1,5 +1,23 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { stringifyEnvelope } from './_errors.js';
+/** Refusal for a host-file argument on a context that may not touch the
+ * server's disk: the host belongs to its operator, not to every caller. */
+export function hostFilesRefused(account, what) {
+    return {
+        content: [{
+                type: 'text',
+                text: stringifyEnvelope({
+                    error: 'forbidden',
+                    message: `${what}: this caller may not read files on the machine running the server.`,
+                    hint: 'Put the file in Drive first and work from its Drive id.',
+                    retriable: false,
+                    account,
+                }),
+            }],
+        isError: true,
+    };
+}
 // path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
 export function prepareLocalDest(savePath, filename) {
     const name = path.basename(filename);

package/dist/tools/account-wizard.d.ts

@@ -53,4 +53,13 @@ export declare function argsToAddForm(a: {
 /** Scopes requested by the profile but NOT granted at consent (granular
  * consent / unchecked bundles). Pure. */
 export declare function scopeGrantDiff(requested: string[], grantedScope: string | undefined): string[];
-export declare function registerAccountWizardTools(registry: ToolRegistry, server: McpServer): void;
+/** HTTP-transport consent context (S1.20): set by the HTTP bootstrap. When
+ * present, runConsent NEVER binds a server-side loopback listener — the
+ * user's browser cannot reach the daemon's loopback — and instead hands out
+ * a clientless AS consent URL. The injector decides the flow (single-owner =
+ * the legacy alias_reauth link). */
+export interface WizardHttpConsent {
+    mintConsentUrl: (alias: string) => Promise<string> | string;
+}
+export declare function setWizardHttpConsent(ctx: WizardHttpConsent | null): void;
+export declare function registerAccountWizardTools(registry: ToolRegistry, server: McpServer, awaitingRestart?: () => string[]): void;

package/dist/tools/account-wizard.js

@@ -1,21 +1,14 @@
 import { z } from 'zod';
-import { getAccountSet, invalidateAccountSet } from '../accounts.js';
-import { mutateConfigFile } from '../config-file.js';
+import { getAccountSet, invalidateAccountSet, refreshAccountSetIfStale } from '../accounts.js';
+import { ALIAS_RE, mutateConfigFile } from '../config-file.js';
 import { writeToken } from '../token-store.js';
 import { resolveScopesForAccount } from '../auth.js';
-import { BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from '../scope-catalog.js';
+import { BUNDLE_CATALOG, closestBundle, isKnownBundle, resolveBundleAliases } from '../scope-catalog.js';
 import { openUrl } from '../open-url.js';
 import { coerceBoolean } from './_coerce.js';
 import { safeMessage, stringifyEnvelope } from './_errors.js';
 import { buildConsentClient, openLoopbackConsent, hasClientCredentials, TESTING_MODE_WARNING, } from '../oauth-consent.js';
 import { detectClients, buildServerEntry, renderInstruction, applyFileEntry, resolveMode, DEFAULT_SERVER_NAME, } from '../client-config.js';
-// B7: the elicitation-driven account_add / account_reauth wizard. It rebuilds
-// interactive account management on the mutable config.json registry so a
-// running server can add an account without the deployer editing env + running
-// a CLI. Google consent reuses the loopback flow (leg C); the HTTP-transport
-// consent path (${BASE}/authorize) is owned by the OAuth AS and lands with that
-// cluster. account_add over http is gated behind it.
-const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
 // The common optional bundles get their own checkbox (MCP elicitation has no
 // multi-select, so a boolean per bundle IS the checklist); the long tail stays
 // a comma-separated field for power users, and `allBundles` grants every one.
@@ -65,7 +58,7 @@ export function validateAddForm(input, existingAliases) {
         if (b === 'admin') {
             return { ok: false, slug: 'E_UNKNOWN_BUNDLE', message: '"admin" is not a scope bundle.', hint: 'Use the admin checkbox instead, or pass "admin": true.', alias };
         }
-        if (!(b in BUNDLE_CATALOG)) {
+        if (!isKnownBundle(b)) {
             const closest = closestBundle(b);
             const known = Object.keys(BUNDLE_CATALOG).filter((n) => n !== 'admin').join(', ');
             return {
@@ -143,6 +136,25 @@ function errorResult(slug, message, hint, account) {
         isError: true,
     };
 }
+let httpConsent = null;
+export function setWizardHttpConsent(ctx) {
+    httpConsent = ctx;
+}
+/** Services register their tools at startup, so one first enabled by this
+ * account stays unregistered until a restart; say so rather than claim the
+ * whole account works without one. */
+function restartNote(pending) {
+    if (pending.length === 0)
+        return '';
+    const names = pending.map((s) => `"${s}"`).join(', ');
+    const what = pending.length > 1 ? `services ${names} register their` : `service ${names} registers its`;
+    return `\nThe ${what} tools when the server starts: restart the server to use them. Until then, google_api_call can reach the same API.`;
+}
+function pendingText(alias, url, pending) {
+    return (`Account "${alias}" is ready to authorize. Open this link in a browser (it belongs to whoever owns the Google account):\n${url}\n` +
+        `On completion the token is stored server-side and the account is usable immediately — no restart. ` +
+        `If the link expires, run account_reauth for a fresh one.${restartNote(pending)}\n${TESTING_MODE_WARNING}`);
+}
 /** Run Google consent for `alias` and persist the token. Opens the browser via
  * URL-mode elicitation when the client supports it, else server-side + prints
  * the URL. Returns the granted-scope diff for the S4 report. */
@@ -157,6 +169,29 @@ async function runConsent(server, alias) {
             hint: 'Accounts sourced from GOOGLE_ACCOUNTS are not editable here. Run `mcp-google-multi migrate-config` to move them into config.json.',
         };
     }
+    // HTTP transport: consent completes OUT OF BAND at the AS /callback. Never
+    // bind a loopback listener here; try URL-mode elicitation as a convenience
+    // but surface the URL UP FRONT either way (not only on failure).
+    const http = httpConsent;
+    if (http) {
+        let url;
+        try {
+            url = await http.mintConsentUrl(alias);
+        }
+        catch (e) {
+            return { ok: false, slug: 'internal', message: safeMessage(e) };
+        }
+        const caps = server.server.getClientCapabilities?.();
+        if (caps?.elicitation?.url !== undefined) {
+            try {
+                await server.server.elicitInput(urlElicitationParams(alias, url, randomBytes(16).toString('hex')));
+            }
+            catch {
+                // the URL in the pending text is the recovery
+            }
+        }
+        return { ok: 'pending', url };
+    }
     // Bind the ephemeral loopback listener BEFORE building the auth URL: the
     // redirect URI needs the assigned port, and listening first means the
     // callback can't race the browser.
@@ -211,14 +246,14 @@ async function runConsent(server, alias) {
     writeToken(alias, tokens);
     return { ok: true, missing: scopeGrantDiff(scopes, typeof tokens.scope === 'string' ? tokens.scope : undefined) };
 }
-function s4Text(alias, missing) {
+function s4Text(alias, missing, pending) {
     const outcome = missing.length === 0
         ? `✔ "${alias}" authenticated; all requested scopes granted. It is now usable without a restart.`
         : `⚠ "${alias}" authenticated, but ${missing.length} requested scope(s) were NOT granted (E_SCOPE_NOT_GRANTED). You may have unchecked some on the consent screen. Re-run account_reauth to grant them. The account is usable for the granted scopes.`;
-    return `${outcome}\n${TESTING_MODE_WARNING}`;
+    return `${outcome}${restartNote(pending)}\n${TESTING_MODE_WARNING}`;
 }
 const REQUIRES_INTERACTION = { 'anthropic/requiresUserInteraction': true };
-export function registerAccountWizardTools(registry, server) {
+export function registerAccountWizardTools(registry, server, awaitingRestart = () => []) {
     // Registered as META (always-visible, like account_list) so onboarding tools
     // are reachable in lazy mode without discover_all first; registerMeta still
     // preserves the requiresUserInteraction clientMeta and skips the fan-out path.
@@ -226,7 +261,7 @@ export function registerAccountWizardTools(registry, server) {
     registerMeta('account_add', {
         _meta: REQUIRES_INTERACTION,
         annotations: { openWorldHint: true },
-        description: 'Add a new Google account: pass alias + email directly (plus optional bundles/allBundles/admin), or pass nothing for an interactive form where the client supports elicitation. Writes the registry and runs Google consent in the browser. No file editing or restart needed. Requires GOOGLE_CLIENT_ID/SECRET (run the `setup` prompt first if missing).',
+        description: 'Add a new Google account: pass alias + email directly (plus optional bundles/allBundles/admin), or pass nothing for an interactive form where the client supports elicitation. Writes the registry and runs Google consent in the browser. No file editing or restart needed to use the account (tools of a service it newly enables register at the next restart). Requires GOOGLE_CLIENT_ID/SECRET (run the `setup` prompt first if missing).',
         inputSchema: {
             alias: z.string().optional().describe('Account alias (letters, digits, _ or -). Pass with email to add directly, skipping the form.'),
             account: z.string().optional().describe('Alias for the new account (same as `alias`; every other tool spells it `account`)'),
@@ -272,12 +307,23 @@ export function registerAccountWizardTools(registry, server) {
             // S2: atomic write + make the alias callable without a restart (BR3).
             writeAccountRow(validated.alias, validated.email, validated.bundles, validated.admin);
             invalidateAccountSet();
+            // Live account args validate against the refreshed registry already;
+            // the list_changed nudge makes clients re-fetch tools/list, where the
+            // advertised account enums are rebuilt from the live set.
+            try {
+                server.sendToolListChanged();
+            }
+            catch {
+                // a client that cannot receive notifications loses nothing but the nudge
+            }
             // S3 + S4: consent + validate.
             const consent = await runConsent(server, validated.alias);
+            if (consent.ok === 'pending')
+                return textResult(pendingText(validated.alias, consent.url, awaitingRestart()));
             if (!consent.ok)
                 return errorResult(consent.slug, consent.message, consent.hint, validated.alias);
             // B15: offer to register the server with another MCP client.
-            return textResult(`${s4Text(validated.alias, consent.missing)}\nTip: run account_write_config to register this server with another MCP client (Claude Desktop / Cursor / Claude Code).`);
+            return textResult(`${s4Text(validated.alias, consent.missing, awaitingRestart())}\nTip: run account_write_config to register this server with another MCP client (Claude Desktop / Cursor / Claude Code).`);
         }
         catch (e) {
             // safeMessage, not error.message: an arbitrary throw here can carry a
@@ -303,6 +349,9 @@ export function registerAccountWizardTools(registry, server) {
         try {
             const a = args;
             const alias = a.alias ?? a.account ?? '';
+            // No default-account wrapper runs for this tool, so pick up a
+            // hand-edited config.json here: that edit is why a re-auth is asked for.
+            refreshAccountSetIfStale();
             if (!hasClientCredentials()) {
                 return errorResult('invalid_client', 'GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are not set, so there is no OAuth client to run consent against.', 'Run the `setup` prompt (/mcp__google-multi__setup) to create an OAuth client, then set them. See docs/google-cloud-setup.md.');
             }
@@ -310,9 +359,11 @@ export function registerAccountWizardTools(registry, server) {
                 return errorResult('validation_error', `Unknown account "${alias}".`, `Pass one of the configured aliases: ${getAccountSet().aliases.join(', ')}. Use account_add to create a new one.`, alias);
             }
             const consent = await runConsent(server, alias);
+            if (consent.ok === 'pending')
+                return textResult(pendingText(alias, consent.url, awaitingRestart()));
             if (!consent.ok)
                 return errorResult(consent.slug, consent.message, consent.hint, alias);
-            return textResult(s4Text(alias, consent.missing));
+            return textResult(s4Text(alias, consent.missing, awaitingRestart()));
         }
         catch (e) {
             return errorResult('internal', `account_reauth failed: ${safeMessage(e)}`);
@@ -360,6 +411,12 @@ export function registerAccountWizardTools(registry, server) {
                 if (client.managed === 'cli') {
                     blocks.push(`${client.label}: run\n  ${instr.text}`);
                 }
+                else if (a.write && mode === 'http') {
+                    // Over HTTP this tool runs on the DAEMON, whose homedir is not the
+                    // caller's machine: write:true would edit the operator's own client
+                    // configs (a cross-tenant hazard under tenancy). Snippet only.
+                    blocks.push(`${client.label}: write:true is ignored over HTTP — this tool runs on the server, not your machine. Add to ${instr.path}\n${instr.text}`);
+                }
                 else if (a.write) {
                     const res = applyFileEntry(client, name, entry);
                     blocks.push(res.ok

package/dist/tools/accounts-tool.d.ts

@@ -1,5 +1,7 @@
 import type { ToolRegistry } from '../registry.js';
+import { type AccountSet } from '../accounts.js';
 import { type ScopesReport } from '../scope-observability.js';
+import { type TokenStore } from '../token-store.js';
 export interface AccountHealthDeps {
     hasToken: (alias: string) => boolean;
     readToken: (alias: string) => {
@@ -13,7 +15,12 @@ export interface AccountHealthDeps {
      * "registered but not requestable" view (B9). account_list stays compact:
      * its report universe is profile ∪ granted only. */
     registeredScopes?: () => string[];
+    /** Account view health is derived against; absent = the global registry. */
+    accounts?: () => AccountSet;
 }
+/** Health deps over one context's token store (and, optionally, its account
+ * view); the module-level functions are the single owner's store. */
+export declare function accountHealthDepsFor(store: Pick<TokenStore, 'hasToken' | 'readToken'>, accounts?: () => AccountSet): AccountHealthDeps;
 export type TokenStatus = 'ok' | 'expired_refreshable' | 'needs_reauth' | 'missing' | 'decrypt_error';
 export interface AccountHealth {
     alias: string;

package/dist/tools/accounts-tool.js

@@ -1,18 +1,27 @@
+import { reauthHint } from '../reauth-hint.js';
 import * as fs from 'node:fs';
 import { getAccountSet, refreshAccountSetIfStale } from '../accounts.js';
 import { buildScopesReport } from '../scope-observability.js';
 import { getAdminAccounts, resolveScopesForAccount } from '../auth.js';
 import { hasToken, readToken } from '../token-store.js';
-const DEFAULT_DEPS = {
-    hasToken,
-    readToken,
-    fileExists: fs.existsSync,
-    now: Date.now,
-};
+import { hints } from '../hint-provider.js';
+/** Health deps over one context's token store (and, optionally, its account
+ * view); the module-level functions are the single owner's store. */
+export function accountHealthDepsFor(store, accounts) {
+    return {
+        hasToken: store.hasToken,
+        readToken: store.readToken,
+        fileExists: fs.existsSync,
+        now: Date.now,
+        ...(accounts ? { accounts } : {}),
+    };
+}
+const DEFAULT_DEPS = accountHealthDepsFor({ hasToken, readToken });
 export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
-    const config = getAccountSet().configs[alias];
-    const admin = getAdminAccounts().includes(alias);
-    const configured = resolveScopesForAccount(alias);
+    const set = (deps.accounts ?? getAccountSet)();
+    const config = set.configs[alias];
+    const admin = getAdminAccounts(set).includes(alias);
+    const configured = resolveScopesForAccount(alias, set);
     // BR-10: env-sourced accounts are not persisted in config.json, so the
     // account wizard cannot edit them — the deployer edits env instead.
     const base = {
@@ -29,13 +38,17 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
     const noScopes = buildScopesReport(new Set(), profileSet, registered);
     if (!deps.hasToken(alias)) {
         const legacy = deps.fileExists(config.tokenPath);
+        const rendered = legacy
+            ? hints()?.render({ kind: 'legacy_plaintext_token', account: alias })
+            : hints()?.render({ kind: 'reauth', account: alias });
         return {
             ...base,
             token: {
                 status: 'missing',
-                hint: legacy
-                    ? 'Plaintext token.json found — run: npx mcp-google-multi migrate-tokens'
-                    : `Run: npx mcp-google-multi auth --account ${alias}`,
+                hint: rendered?.hint ??
+                    (legacy
+                        ? 'Plaintext token.json found — run: npx mcp-google-multi migrate-tokens'
+                        : reauthHint(alias)),
             },
             scopes: noScopes,
         };
@@ -45,9 +58,10 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
         token = deps.readToken(alias);
     }
     catch {
+        const rendered = hints()?.render({ kind: 'token_unreadable', account: alias });
         return {
             ...base,
-            token: { status: 'decrypt_error', hint: 'Wrong MASTER_KEY or corrupt token file — re-auth or restore the key.' },
+            token: { status: 'decrypt_error', hint: rendered?.hint ?? 'Wrong MASTER_KEY or corrupt token file — re-auth or restore the key.' },
             scopes: noScopes,
         };
     }
@@ -69,9 +83,9 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
             status,
             expiryDate: expiry !== undefined ? new Date(expiry).toISOString() : undefined,
             hint: status === 'needs_reauth'
-                ? `Run: npx mcp-google-multi auth --account ${alias}`
+                ? (hints()?.render({ kind: 'reauth', account: alias })?.hint ?? reauthHint(alias))
                 : missing.length > 0
-                    ? 'Re-auth to grant the missing scopes'
+                    ? (hints()?.render({ kind: 'scopes_missing', account: alias })?.hint ?? 'Re-auth to grant the missing scopes')
                     : undefined,
         },
         scopes: report,
@@ -87,14 +101,16 @@ export function registerAccountTools(registry, deps = DEFAULT_DEPS) {
         _meta: { 'anthropic/alwaysLoad': true },
     }, async () => {
         refreshAccountSetIfStale();
+        const set = registry.accountSet();
+        const health = { ...deps, accounts: () => set };
         return {
             content: [
                 {
                     type: 'text',
                     text: JSON.stringify({
-                        defaultAccount: getAccountSet().defaultAccount ?? null,
-                        defaultAccountSource: getAccountSet().defaultAccountSource ?? null,
-                        accounts: getAccountSet().aliases.map((alias) => deriveAccountHealth(alias, deps)),
+                        defaultAccount: set.defaultAccount ?? null,
+                        defaultAccountSource: set.defaultAccountSource ?? null,
+                        accounts: set.aliases.map((alias) => deriveAccountHealth(alias, health)),
                     }),
                 },
             ],

package/dist/tools/admin.d.ts

@@ -1,2 +1,11 @@
 import type { ToolRegistry } from '../registry.js';
-export declare function registerAdminTools(server: ToolRegistry): void;
+import type { Account } from '../accounts.js';
+import { type CuratedToolDeps } from '../client.js';
+export declare function registerAdminTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
+export declare function handleAdminError(error: any, account: Account): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/admin.js

@@ -1,12 +1,16 @@
 import { z } from 'zod';
 import { coerceBoolean } from './_coerce.js';
 import { admin as adminClient } from '@googleapis/admin';
-import { accountAliasSchema } from '../accounts.js';
+import { accountArgLive } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError, invalidParams } from './_errors.js';
-const accountEnum = accountAliasSchema.optional();
 // Admin SDK requires Workspace super-admin (or delegated admin) on the account — personal @gmail.com accounts 403 on every endpoint.
-export function registerAdminTools(server) {
+export function registerAdminTools(server, deps = {}) {
+    // Per-registry, LIVE account enum + injectable client (S1.10): the
+    // schema follows the registry's account view at parse time, and the
+    // custody path is the context's, not the process global.
+    const accountEnum = accountArgLive(() => server.accountAliases()).optional();
+    const getClientFn = deps.getClientFn ?? getClient;
     // ─── Reports / audit log ───────────────────────────────────────────────
     server.registerTool('reports_activities_list', {
         description: 'List Admin Activity audit log entries. Filter by application (login, drive, gmail, admin, token, etc.), user, date range, event. The single most useful admin endpoint for SMB visibility.',
@@ -34,7 +38,7 @@ export function registerAdminTools(server) {
         },
     }, async ({ account, applicationName, userKey, startTime, endTime, eventName, actorIpAddress, filters, orgUnitID, groupIdFilter, customerId, maxResults, pageToken }) => {
         try {
-            const auth = await getClient(account);
+            const auth = await getClientFn(account);
             const reports = adminClient({ version: 'reports_v1', auth });
             const res = await reports.activities.list({
                 applicationName,
@@ -74,7 +78,7 @@ export function registerAdminTools(server) {
         },
     }, async ({ account, customer, domain, query, maxResults, pageToken, orderBy, showDeleted, projection }) => {
         try {
-            const auth = await getClient(account);
+            const auth = await getClientFn(account);
             const directory = adminClient({ version: 'directory_v1', auth });
             const res = await directory.users.list({
                 customer: customer ?? 'my_customer',
@@ -103,7 +107,7 @@ export function registerAdminTools(server) {
         },
     }, async ({ account, userKey, projection }) => {
         try {
-            const auth = await getClient(account);
+            const auth = await getClientFn(account);
             const directory = adminClient({ version: 'directory_v1', auth });
             const res = await directory.users.get({
                 userKey,
@@ -131,7 +135,7 @@ export function registerAdminTools(server) {
         },
     }, async ({ account, userKey, givenName, familyName, suspended, password, changePasswordAtNextLogin, orgUnitPath }) => {
         try {
-            const auth = await getClient(account);
+            const auth = await getClientFn(account);
             const directory = adminClient({ version: 'directory_v1', auth });
             const requestBody = {};
             if (givenName !== undefined || familyName !== undefined) {
@@ -175,7 +179,7 @@ export function registerAdminTools(server) {
         },
     }, async ({ account, customer, domain, userKey, query, maxResults, pageToken }) => {
         try {
-            const auth = await getClient(account);
+            const auth = await getClientFn(account);
             const directory = adminClient({ version: 'directory_v1', auth });
             const res = await directory.groups.list({
                 customer: customer ?? 'my_customer',
@@ -205,7 +209,7 @@ export function registerAdminTools(server) {
         },
     }, async ({ account, groupKey, roles, includeDerivedMembership, maxResults, pageToken }) => {
         try {
-            const auth = await getClient(account);
+            const auth = await getClientFn(account);
             const directory = adminClient({ version: 'directory_v1', auth });
             const res = await directory.members.list({
                 groupKey,
@@ -223,7 +227,7 @@ export function registerAdminTools(server) {
         }
     });
 }
-function handleAdminError(error, account) {
+export function handleAdminError(error, account) {
     const admin = 'Admin tools require Workspace super-admin privileges AND the account must be listed as an admin account (then re-authenticated). Personal Gmail accounts cannot use these endpoints.';
-    return handleGoogleApiError(error, account, { scope: admin, resource: admin });
+    return handleGoogleApiError(error, account, { scope: admin, resource: admin, bundle: 'admin' });
 }