mcp-google-multi 6.0.0-alpha.9 → 6.0.0-beta.2

package/dist/metrics-cli.js

@@ -0,0 +1,206 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { describeMetricsDir, mergeDay } from './usage-metrics.js';
+function loadDayDocs(dir, sinceDays) {
+    const aggDir = path.join(dir, 'agg');
+    let files;
+    try {
+        files = fs.readdirSync(aggDir).filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f)).sort();
+    }
+    catch {
+        return [];
+    }
+    const cutoff = sinceDays !== undefined ? Date.now() - sinceDays * 86_400_000 : undefined;
+    const docs = [];
+    for (const f of files) {
+        if (cutoff !== undefined && Date.parse(`${f.slice(0, 10)}T00:00:00Z`) < cutoff)
+            continue;
+        try {
+            const doc = JSON.parse(fs.readFileSync(path.join(aggDir, f), 'utf-8'));
+            if (doc && doc.v === 1)
+                docs.push(doc);
+        }
+        catch { /* unreadable day file: skip, the report is best-effort */ }
+    }
+    return docs;
+}
+function sum(docs) {
+    return docs.reduce((a, b) => mergeDay(a, b));
+}
+function parseSince(argv) {
+    const i = argv.indexOf('--since');
+    if (i === -1 || !argv[i + 1])
+        return undefined;
+    const m = argv[i + 1].match(/^(\d+)d$/);
+    return m ? Number(m[1]) : undefined;
+}
+const pct = (num, den) => (den === 0 ? '-' : `${Math.round((num / den) * 100)}%`);
+const top = (m, n) => Object.entries(m).filter(([k]) => k !== '_overflow').sort((a, b) => b[1] - a[1]).slice(0, n);
+function renderReport(merged, days, out) {
+    out(`local usage metrics: ${days} day file(s), ${merged.calls} calls, node ${merged.node}`);
+    out(`boots: ${Object.entries(merged.boots).map(([k, v]) => `${k}=${v}`).join('  ') || '(none)'}`);
+    out('');
+    out('tool                              calls   err  err%  hint  top slug');
+    for (const [name, t] of Object.entries(merged.tools).sort((a, b) => b[1].n - a[1].n).slice(0, 30)) {
+        const errs = Object.values(t.err).reduce((s, v) => s + v, 0);
+        const slug = top(t.err, 1)[0]?.[0] ?? '';
+        out(`${name.padEnd(34)}${String(t.n).padStart(5)}${String(errs).padStart(6)}${pct(errs, t.n).padStart(6)}${String(t.hint).padStart(6)}  ${slug}`);
+    }
+    const hintRows = Object.entries(merged.hints);
+    if (hintRows.length > 0) {
+        out('');
+        out('hint coverage per error class (hinted/total)');
+        for (const [slug, h] of hintRows.sort((a, b) => b[1].hinted + b[1].unhinted - a[1].hinted - a[1].unhinted)) {
+            out(`  ${slug.padEnd(24)}${h.hinted}/${h.hinted + h.unhinted} (${pct(h.hinted, h.hinted + h.unhinted)})`);
+        }
+    }
+    const retryRows = Object.entries(merged.retries);
+    if (retryRows.length > 0) {
+        out('');
+        out('retry self-correction per error class (ok/total after hinted vs unhinted errors)');
+        for (const [slug, r] of retryRows) {
+            out(`  ${slug.padEnd(24)}hinted ${r.hintedOk}/${r.hintedOk + r.hintedFail} (${pct(r.hintedOk, r.hintedOk + r.hintedFail)})  unhinted ${r.unhintedOk}/${r.unhintedOk + r.unhintedFail} (${pct(r.unhintedOk, r.unhintedOk + r.unhintedFail)})`);
+        }
+    }
+    const esc = merged.escape;
+    if (Object.keys(esc.methods).length > 0 || esc.unknown_method > 0 || esc.unknown_api > 0) {
+        out('');
+        out(`escape hatch: unknown_method=${esc.unknown_method} unknown_api=${esc.unknown_api} overflow=${esc._overflow}`);
+        for (const [id, n] of top(esc.methods, 20))
+            out(`  ${id.padEnd(50)}${n}`);
+        const apis = top(esc.apis_searched, 10).map(([k, v]) => `${k}=${v}`).join('  ');
+        if (apis)
+            out(`  searched: ${apis}`);
+    }
+    if (Object.keys(merged.validation).length > 0) {
+        out('');
+        out('schema validation rejections (never reached a handler)');
+        for (const [tool, n] of top(merged.validation, 15))
+            out(`  ${tool.padEnd(34)}${n}`);
+    }
+    const bigrams = top(merged.bigrams, 10);
+    if (bigrams.length > 0) {
+        out('');
+        out('top tool bigrams');
+        for (const [pair, n] of bigrams)
+            out(`  ${pair.padEnd(50)}${n}`);
+    }
+}
+const tail = (id) => id.split('.').slice(1).join('.');
+/** The promotion-queue view: ranked evidence, a human decides (spec section 5). */
+export function classifyPromotion(merged, data) {
+    const curated = new Set();
+    for (const id of data.curatedIds) {
+        curated.add(id);
+        curated.add(tail(id));
+    }
+    const byId = new Map();
+    const byTail = new Map();
+    const toolToId = new Map();
+    for (const [id, tool] of Object.entries(data.methodMap)) {
+        byId.set(id, tool);
+        byTail.set(tail(id), tool);
+        toolToId.set(tool, id);
+    }
+    const rows = [];
+    // (a) generated tools with real traffic = curation candidates.
+    for (const [tool, t] of Object.entries(merged.tools)) {
+        const id = toolToId.get(tool);
+        if (id && !curated.has(id) && !curated.has(tail(id))) {
+            rows.push({ methodId: id, tool, calls: t.n, kind: 'curation-candidate' });
+        }
+    }
+    // (b)/(c) escape methodIds; the tail join covers legacy doc prefixes.
+    for (const [id, calls] of Object.entries(merged.escape.methods)) {
+        if (curated.has(id) || curated.has(tail(id)))
+            continue; // already curated: drops out
+        const twin = byId.get(id) ?? byTail.get(tail(id));
+        rows.push(twin
+            ? { methodId: id, tool: twin, calls, kind: 'visibility-failure' }
+            : { methodId: id, calls, kind: 'generation-gap' });
+    }
+    return rows.sort((a, b) => b.calls - a.calls);
+}
+function renderPromotion(rows, out) {
+    const section = (kind, title, note) => {
+        const list = rows.filter((r) => r.kind === kind);
+        if (list.length === 0)
+            return;
+        out(`### ${title}`);
+        out(note);
+        out('');
+        out('| methodId | tool | calls |');
+        out('|---|---|---|');
+        for (const r of list)
+            out(`| ${r.methodId} | ${r.tool ?? '(none)'} | ${r.calls} |`);
+        out('');
+    };
+    if (rows.length === 0) {
+        out('No promotion evidence yet: no generated-tool traffic and no escape-hatch methodIds recorded.');
+        return;
+    }
+    section('curation-candidate', 'Curation candidates', 'Generated tools with real traffic; a curated wrapper may be earned.');
+    section('visibility-failure', 'Visibility failures', 'The escape hatch was used where a generated tool exists; discovery/naming problem, not a coverage gap.');
+    section('generation-gap', 'Generation gaps', 'Escape methodIds with no tool at all.');
+}
+export function runMetricsCli(argv, deps) {
+    const out = deps.out ?? ((l) => process.stdout.write(`${l}\n`));
+    const env = deps.env ?? process.env;
+    const json = argv.includes('--json');
+    const sub = argv.includes('merge') ? 'merge' : 'report';
+    let merged;
+    let dayCount = 0;
+    if (sub === 'merge') {
+        const files = argv.slice(argv.indexOf('merge') + 1).filter((a) => !a.startsWith('--'));
+        if (files.length === 0) {
+            out('usage: mcp-google-multi metrics merge <file...> [--json]');
+            return 2;
+        }
+        const docs = [];
+        for (const f of files) {
+            let parsed;
+            try {
+                parsed = JSON.parse(fs.readFileSync(f, 'utf-8'));
+            }
+            catch (e) {
+                out(`cannot read ${f}: ${e.message}`);
+                return 2;
+            }
+            // A report wrapper carries {v, days, agg}; a raw day doc carries tools.
+            const doc = parsed.agg?.v === 1 ? parsed.agg : parsed.v === 1 && parsed.tools ? parsed : undefined;
+            if (!doc || doc.v !== 1) {
+                out(`${f} is neither a day aggregate nor a metrics report --json output`);
+                return 2;
+            }
+            docs.push(doc);
+            dayCount += 1;
+        }
+        merged = sum(docs);
+    }
+    else {
+        const dir = describeMetricsDir(env).dir;
+        const docs = loadDayDocs(dir, parseSince(argv));
+        if (docs.length === 0) {
+            out(deps.enabled
+                ? `local usage metrics are on but no day files exist yet under ${dir}`
+                : 'local usage metrics are off (default); enable with GOOGLE_USAGE_METRICS=on');
+            return 0;
+        }
+        merged = sum(docs);
+        dayCount = docs.length;
+    }
+    if (argv.includes('--promotion')) {
+        const rows = classifyPromotion(merged, deps.promotion);
+        if (json)
+            out(JSON.stringify({ v: 1, days: dayCount, promotion: rows }));
+        else
+            renderPromotion(rows, out);
+        return 0;
+    }
+    if (json) {
+        out(JSON.stringify({ v: 1, days: dayCount, agg: merged }));
+        return 0;
+    }
+    renderReport(merged, dayCount, out);
+    return 0;
+}

package/dist/metrics-tap.d.ts

@@ -0,0 +1,12 @@
+import type { Transport } from "@modelcontextprotocol/server";
+import type { Metrics } from './usage-metrics.js';
+import { isSchemaValidationText } from './arg-normalize.js';
+export { isSchemaValidationText };
+/**
+ * @param isKnownTool membership test against the REGISTERED tool set. The
+ * name on a `tools/call` frame is client-supplied, so a shape check alone
+ * would let a shape-valid but invented name reach disk and break the
+ * closed-vocabulary guarantee. A validation failure against a name the server
+ * never registered is a not-found, and is counted as one.
+ */
+export declare function tapUsageMetrics(transport: Transport, metrics: Metrics, isKnownTool?: (name: string) => boolean): Transport;

package/dist/metrics-tap.js

@@ -0,0 +1,95 @@
+import { isSchemaValidationText } from './arg-normalize.js';
+const PENDING_CAP = 1_000;
+// The detector lives next to the rewriter that consumes the same frames, so
+// the two can never drift apart. This tap sees the ORIGINAL prose:
+// withValidationEnvelope sits BELOW it and converts that same frame into an
+// envelope for the client, so classification here and the contract on the wire
+// stay independent.
+export { isSchemaValidationText };
+/**
+ * @param isKnownTool membership test against the REGISTERED tool set. The
+ * name on a `tools/call` frame is client-supplied, so a shape check alone
+ * would let a shape-valid but invented name reach disk and break the
+ * closed-vocabulary guarantee. A validation failure against a name the server
+ * never registered is a not-found, and is counted as one.
+ */
+export function tapUsageMetrics(transport, metrics, isKnownTool = () => false) {
+    const pending = new Map();
+    const recordValidation = (tool) => {
+        if (tool !== undefined && isKnownTool(tool))
+            metrics.recordRpc('schema_validation', tool);
+        else
+            metrics.recordRpc('tool_not_found');
+    };
+    const wrapper = {
+        start: () => transport.start(),
+        send: (message, options) => {
+            try {
+                const m = message;
+                // Responses only: a server-initiated REQUEST carries an id from a
+                // different id space, and evicting on it would drop a real pending call.
+                if (m.id !== undefined && message.method === undefined) {
+                    const tool = pending.get(m.id);
+                    pending.delete(m.id);
+                    if (m.error && typeof m.error.code === 'number') {
+                        if (m.error.code === -32602) {
+                            if (/unknown tool|not found/i.test(m.error.message ?? ''))
+                                metrics.recordRpc('tool_not_found');
+                            else
+                                recordValidation(tool);
+                        }
+                        else {
+                            metrics.recordRpc(m.error.code);
+                        }
+                    }
+                    else if (m.result?.isError === true) {
+                        const first = m.result.content?.[0]?.text;
+                        if (typeof first === 'string' && isSchemaValidationText(first)) {
+                            recordValidation(tool);
+                        }
+                    }
+                }
+            }
+            catch { /* the tap may never break the wire */ }
+            return transport.send(message, options);
+        },
+        close: () => transport.close(),
+    };
+    Object.defineProperty(wrapper, 'onmessage', {
+        get: () => transport.onmessage,
+        set: (handler) => {
+            transport.onmessage = handler
+                ? (message, extra) => {
+                    try {
+                        const m = message;
+                        if (m.id !== undefined && m.method === 'tools/call' && typeof m.params?.name === 'string') {
+                            if (pending.size >= PENDING_CAP)
+                                pending.clear();
+                            pending.set(m.id, m.params.name);
+                        }
+                    }
+                    catch { /* never break the wire */ }
+                    handler(message, extra);
+                }
+                : undefined;
+        },
+    });
+    for (const prop of ['onclose', 'onerror']) {
+        Object.defineProperty(wrapper, prop, {
+            get: () => transport[prop],
+            set: (v) => {
+                transport[prop] = v;
+            },
+        });
+    }
+    Object.defineProperty(wrapper, 'sessionId', { get: () => transport.sessionId });
+    if (transport.setProtocolVersion) {
+        wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
+    }
+    // v2-only; see the same forward in arg-normalize.ts. Both proxies compose,
+    // so a member dropped by either layer never reaches the real transport.
+    if (transport.setSupportedProtocolVersions) {
+        wrapper.setSupportedProtocolVersions = (v) => transport.setSupportedProtocolVersions(v);
+    }
+    return wrapper;
+}

package/dist/oauth-consent.d.ts

@@ -1,6 +1,4 @@
 import { OAuth2Client } from 'googleapis-common';
-export declare const LOOPBACK_PORT = 4242;
-export declare const LOOPBACK_REDIRECT = "http://localhost:4242/oauth2callback";
 /** GOOGLE_CLIENT_ID/SECRET absent — caller maps to E_CLIENT_CREDENTIALS_MISSING. */
 export declare class ClientCredentialsMissingError extends Error {
     constructor();
@@ -14,15 +12,32 @@ export declare class ConsentTimeoutError extends Error {
 export declare class ConsentDeniedError extends Error {
     constructor(reason: string);
 }
+export declare const TESTING_MODE_WARNING: string;
 export declare function hasClientCredentials(): boolean;
-/** Build the loopback OAuth2 client from env credentials (throws if unset). */
-export declare function buildConsentClient(): OAuth2Client;
 /**
- * Start the loopback server, await the OAuth redirect, validate the CSRF
- * `state` (RFC 6749 §10.12), and exchange the code. Returns the token set for
- * the caller to persist. Never process.exit's (safe inside a live server) and
- * times out so a stalled consent can't wedge a tool call.
+ * Build the loopback OAuth2 client from env credentials (throws if unset).
+ * `redirect` comes from openLoopbackConsent(): the port is only known once the
+ * listener is bound.
  */
-export declare function awaitLoopbackConsent(client: OAuth2Client, expectedState: string, opts?: {
+export declare function buildConsentClient(redirect: string): OAuth2Client;
+export interface LoopbackConsent {
+    /** `http://localhost:<ephemeral port>/oauth2callback` — build the auth URL from this. */
+    redirect: string;
+    /**
+     * Await the OAuth redirect, validate the CSRF `state` (RFC 6749 §10.12), and
+     * exchange the code. Returns the token set for the caller to persist.
+     */
+    finish(client: OAuth2Client, expectedState: string): Promise<Record<string, unknown>>;
+    /**
+     * Abandon the consent: shuts the listener down WITHOUT settling finish(), so
+     * an abandoned flow can never surface as an unhandled rejection later.
+     */
+    close(): void;
+}
+/**
+ * Bind the loopback listener first (ephemeral port), so the redirect URI is
+ * known before the auth URL is built and the callback can't race the browser.
+ */
+export declare function openLoopbackConsent(opts?: {
     timeoutMs?: number;
-}): Promise<Record<string, unknown>>;
+}): Promise<LoopbackConsent>;

package/dist/oauth-consent.js

@@ -2,13 +2,11 @@ import { OAuth2Client } from 'googleapis-common';
 import http from 'node:http';
 import { URL } from 'node:url';
 // Shared loopback OAuth consent (leg C of cc-auth), used by the account wizard
-// (B7). The `auth --account` CLI keeps its own inline copy for now; this module
-// is the reusable, live-server-safe form (throws typed errors instead of
-// process.exit, and times out so a never-completed consent can't wedge a tool
-// call forever). The redirect matches the CLI exactly so an existing registered
-// Desktop client keeps working.
-export const LOOPBACK_PORT = 4242;
-export const LOOPBACK_REDIRECT = `http://localhost:${LOOPBACK_PORT}/oauth2callback`;
+// (B7) and the `auth --account` CLI. Live-server-safe: typed errors instead of
+// process.exit, and a timeout so a never-completed consent can't wedge a tool
+// call forever. The listener binds an EPHEMERAL loopback port (RFC 8252 §7.3;
+// Google Desktop clients accept any http://localhost:<port> redirect), so a
+// second local process on a fixed port can never break auth.
 /** GOOGLE_CLIENT_ID/SECRET absent — caller maps to E_CLIENT_CREDENTIALS_MISSING. */
 export class ClientCredentialsMissingError extends Error {
     constructor() {
@@ -17,7 +15,7 @@ export class ClientCredentialsMissingError extends Error {
 }
 export class LoopbackPortInUseError extends Error {
     constructor() {
-        super(`E_LOOPBACK_PORT_IN_USE: port ${LOOPBACK_PORT} is already in use; close the other process and retry.`);
+        super('E_LOOPBACK_PORT_IN_USE: the loopback consent listener could not bind a port; retry.');
     }
 }
 export class ConsentTimeoutError extends Error {
@@ -30,80 +28,128 @@ export class ConsentDeniedError extends Error {
         super(`E_CONSENT_DENIED: ${reason}`);
     }
 }
+// Surfaced after every successful consent: the expiry is invisible until the
+// token dies a week later as reauth_required, so the moment of success is the
+// one place the warning is guaranteed to be seen. Full walkthrough in
+// docs/google-cloud-setup.md.
+export const TESTING_MODE_WARNING = 'Heads-up: while your OAuth client\'s Publishing status is "Testing", Google expires refresh tokens after 7 days (weekly re-auth for every account). ' +
+    'When your setup works, set it to "In production" at https://console.cloud.google.com/auth/audience. ' +
+    'No verification review is needed for personal use; see docs/google-cloud-setup.md.';
 export function hasClientCredentials() {
     return Boolean(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET);
 }
-/** Build the loopback OAuth2 client from env credentials (throws if unset). */
-export function buildConsentClient() {
+/**
+ * Build the loopback OAuth2 client from env credentials (throws if unset).
+ * `redirect` comes from openLoopbackConsent(): the port is only known once the
+ * listener is bound.
+ */
+export function buildConsentClient(redirect) {
     if (!hasClientCredentials())
         throw new ClientCredentialsMissingError();
-    return new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, LOOPBACK_REDIRECT);
+    return new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, redirect);
 }
 /**
- * Start the loopback server, await the OAuth redirect, validate the CSRF
- * `state` (RFC 6749 §10.12), and exchange the code. Returns the token set for
- * the caller to persist. Never process.exit's (safe inside a live server) and
- * times out so a stalled consent can't wedge a tool call.
+ * Bind the loopback listener first (ephemeral port), so the redirect URI is
+ * known before the auth URL is built and the callback can't race the browser.
  */
-export function awaitLoopbackConsent(client, expectedState, opts = {}) {
+export function openLoopbackConsent(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 5 * 60_000;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolveOpen, rejectOpen) => {
+        let redirect = '';
         let timer;
+        let closed = false;
+        let pending;
+        const shutdown = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            server.close();
+            server.closeAllConnections();
+        };
+        const fail = (err) => {
+            const p = pending;
+            pending = undefined;
+            shutdown();
+            p?.reject(err);
+        };
         const server = http.createServer(async (req, res) => {
             if (!req.url || !req.url.startsWith('/oauth2callback')) {
                 res.writeHead(404).end();
                 return;
             }
+            if (!pending) {
+                // Only reachable if something other than our own browser launch hit
+                // the port before finish() armed the exchange; nothing to do with it.
+                res.writeHead(503).end();
+                return;
+            }
+            const p = pending;
             const done = (code, body) => {
                 res.writeHead(code, { 'Content-Type': 'text/html' });
                 res.end(body);
-                if (timer)
-                    clearTimeout(timer);
-                server.close();
-                server.closeAllConnections();
             };
             try {
-                const qs = new URL(req.url, LOOPBACK_REDIRECT).searchParams;
+                const qs = new URL(req.url, redirect).searchParams;
                 const error = qs.get('error');
                 if (error) {
                     done(400, `<p>Authorization denied: ${error}</p>`);
-                    reject(new ConsentDeniedError(error));
+                    fail(new ConsentDeniedError(error));
                     return;
                 }
                 const returnedState = qs.get('state');
-                if (returnedState !== expectedState) {
-                    done(400, '<p>State mismatch — possible CSRF attempt. Aborting.</p>');
-                    reject(new Error('E_OAUTH_STATE_MISMATCH: OAuth state token mismatch'));
+                if (returnedState !== p.expectedState) {
+                    done(400, '<p>State mismatch: possible CSRF attempt. Aborting.</p>');
+                    fail(new Error('E_OAUTH_STATE_MISMATCH: OAuth state token mismatch'));
                     return;
                 }
                 const code = qs.get('code');
                 if (!code) {
                     done(400, '<p>No authorization code received.</p>');
-                    reject(new ConsentDeniedError('no authorization code received'));
+                    fail(new ConsentDeniedError('no authorization code received'));
                     return;
                 }
-                const { tokens } = await client.getToken(code);
+                const { tokens } = await p.client.getToken(code);
                 done(200, '<h2>Authentication successful!</h2><p>You can close this tab.</p>');
-                resolve(tokens);
+                pending = undefined;
+                shutdown();
+                p.resolve(tokens);
             }
             catch (e) {
                 done(500, '<p>Internal error during authentication.</p>');
-                reject(e);
+                fail(e);
             }
         });
         server.on('error', (err) => {
-            if (timer)
-                clearTimeout(timer);
-            reject(err.code === 'EADDRINUSE' ? new LoopbackPortInUseError() : err);
+            const mapped = err.code === 'EADDRINUSE' ? new LoopbackPortInUseError() : err;
+            if (pending) {
+                fail(mapped);
+            }
+            else {
+                shutdown();
+                rejectOpen(mapped);
+            }
         });
-        server.listen(LOOPBACK_PORT, '127.0.0.1', () => {
-            timer = setTimeout(() => {
-                server.close();
-                server.closeAllConnections();
-                reject(new ConsentTimeoutError());
-            }, timeoutMs);
+        // Bind to loopback only — never expose the OAuth callback to the local network.
+        server.listen(0, '127.0.0.1', () => {
+            redirect = `http://localhost:${server.address().port}/oauth2callback`;
+            timer = setTimeout(() => fail(new ConsentTimeoutError()), timeoutMs);
             // unref so a pending consent never keeps the process alive on its own.
             timer.unref?.();
+            resolveOpen({
+                redirect,
+                finish(client, expectedState) {
+                    return new Promise((resolve, reject) => {
+                        if (closed) {
+                            reject(new ConsentTimeoutError());
+                            return;
+                        }
+                        pending = { client, expectedState, resolve, reject };
+                    });
+                },
+                close: shutdown,
+            });
         });
     });
 }

package/dist/outbound-allowlist.d.ts

@@ -0,0 +1,34 @@
+export interface OutboundAllowlist {
+    entries: string[];
+    allows(email: string): boolean;
+}
+/** Parse GOOGLE_OUTBOUND_ALLOWLIST: comma-separated addresses and @domain
+ * suffixes ("a@b.com, @company.com"). null = feature off (nothing gated). */
+export declare function resolveOutboundAllowlist(env?: NodeJS.ProcessEnv): OutboundAllowlist | null;
+/** The addresses in `emails` the active allowlist rejects; [] when off. */
+export declare function outboundViolations(emails: string[], env?: NodeJS.ProcessEnv): string[];
+/** The standard error envelope for a blocked outbound target. */
+export declare function outboundDeniedEnvelope(kind: string, blocked: string[], account: string, env?: NodeJS.ProcessEnv): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+/** Convenience: envelope when violations exist, else null. */
+export declare function checkOutbound(kind: string, emails: string[], account: string, env?: NodeJS.ProcessEnv): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | null;
+export declare function collectBodyRecipients(body: unknown): string[];
+/** Gate one escape-hatch/generated dispatch; envelope when blocked, else null. */
+export declare function checkOutboundForMethod(methodId: string, body: unknown, account: string, env?: NodeJS.ProcessEnv): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | null;