melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/tools/credentialHosts.d.ts

@@ -0,0 +1,88 @@
+/**
+ * lib/tools/credentialHosts.ts — the operator's credential host allowlist:
+ * which hosts the value of each static credential variable may be sent to
+ * (ADR 0122).
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names a credential variable
+ *   and, beside it, the host its value goes to: an OpenAPI `auth` sends
+ *   `bearer_env` or `api_key.env` to the spec's server (or `base_url`), and
+ *   an `oauth2` block sends `client_secret_env` to its `token_url`.
+ *   credentialEnvProblem (lib/tools/credentialEnv.ts) keeps the framework's
+ *   own secrets out of reach, and the OAuth host allowlist (ADR 0114) binds
+ *   a provider's tokens, but nothing bound a static secret to its API: a
+ *   YAML that names TRACKER_TOKEN could aim it at a host of its own. The
+ *   binding is the operator's, never the YAML's: an environment variable or
+ *   `createA2AApp({ credentialHosts })`.
+ *
+ * THE RULE (ADR 0122):
+ *   - With no allowlist configured, nothing changes: a credential goes to
+ *     the host the YAML names, as before. The doctor and the server binary
+ *     name every credential variable a served YAML sends, as unbound.
+ *   - With an allowlist configured, it is the whole list: every credential
+ *     variable a YAML sends must be on it, and every host its value goes to
+ *     must be one of that variable's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends the value.
+ *
+ * WHAT IT COVERS: `bearer_env`, `api_key.env` and `client_secret_env` (both
+ *   grants: the client-credentials token request, the consent step's code
+ *   exchange and its refresh). Not `client_id_env`: a client id is not a
+ *   secret. Not MCP_BEARER_TOKENS: it maps each token to its host already,
+ *   and the operator writes both.
+ *
+ * THE FORMAT: `MELCHIZEDEK_CREDENTIAL_HOSTS="TRACKER_TOKEN=api.tracker.example.com;WEATHER_KEY=api.weather.example.com,*.weather.example.com"`.
+ *   Entries are separated by `;` (or a newline), a variable from its hosts by
+ *   `=`, hosts by `,`. A host is what the OAuth host allowlist takes
+ *   (lib/tools/oauthHosts.ts): a hostname, `*.example.com`, IPv4 or
+ *   `[IPv6]`, with no scheme, port or path.
+ *
+ * Nothing here reads or prints a credential's value: variable names and
+ * hosts only. No regular expression here can backtrack: the separators are
+ * single characters, and a variable name is one bounded character class.
+ */
+/** The environment variable the allowlist is read from when no option sets it. */
+export declare const CREDENTIAL_HOSTS_ENV = "MELCHIZEDEK_CREDENTIAL_HOSTS";
+/** Credential variable name → the hosts its value may be sent to. */
+export type CredentialHostAllowlist = Readonly<Record<string, readonly string[]>>;
+/**
+ * The allowlist, checked and normalized (hosts lowercased, duplicates
+ * dropped). Throws, naming the variable and the host, on anything malformed.
+ */
+export declare function checkCredentialHosts(allowlist: Record<string, readonly string[]>, source?: string): Record<string, string[]>;
+/** The allowlist from its text form (MELCHIZEDEK_CREDENTIAL_HOSTS). Throws on a malformed entry. */
+export declare function parseCredentialHosts(text: string): Record<string, string[]>;
+/**
+ * Sets this process's allowlist (createA2AApp's `credentialHosts` does),
+ * which wins over the environment variable. `undefined` returns to the
+ * variable.
+ */
+export declare function setCredentialHosts(allowlist: Record<string, readonly string[]> | undefined): void;
+/**
+ * The allowlist in force: the one set by `setCredentialHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export declare function credentialHosts(env?: NodeJS.ProcessEnv): CredentialHostAllowlist | undefined;
+/**
+ * Why the value of credential variable `name` may not be sent to `url`, or
+ * null. `role` names the URL in the message (`server`, `token_url`).
+ * `allowlist` defaults to the one in force; `null` means none is
+ * configured, which allows (the behaviour before ADR 0122).
+ */
+export declare function credentialHostProblem(name: string, url: string, role?: string, allowlist?: CredentialHostAllowlist | null | undefined): string | null;
+/**
+ * The call-time check: why the value of `name` may not be sent to
+ * `destination` now, or null. A malformed allowlist refuses.
+ */
+export declare function credentialCallProblem(name: string, destination: string): string | null;
+/**
+ * Marks an OAuth client config (lib/tools/oauthConsent.ts) with the
+ * variable its client secret came from, so the consent step's code exchange
+ * and the refresh hook can check the token endpoint at call time. Set by
+ * oauthClientsFor (lib/tools/oauthTools.ts); a client built by hand carries
+ * none and is not checked.
+ */
+export declare const CLIENT_SECRET_ENV: unique symbol;
+/** The variable a client config's secret came from, when oauthClientsFor marked it. */
+export declare function clientSecretEnvOf(client: object): string | undefined;

package/dist/lib/tools/credentialHosts.js

@@ -0,0 +1,165 @@
+/**
+ * lib/tools/credentialHosts.ts — the operator's credential host allowlist:
+ * which hosts the value of each static credential variable may be sent to
+ * (ADR 0122).
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names a credential variable
+ *   and, beside it, the host its value goes to: an OpenAPI `auth` sends
+ *   `bearer_env` or `api_key.env` to the spec's server (or `base_url`), and
+ *   an `oauth2` block sends `client_secret_env` to its `token_url`.
+ *   credentialEnvProblem (lib/tools/credentialEnv.ts) keeps the framework's
+ *   own secrets out of reach, and the OAuth host allowlist (ADR 0114) binds
+ *   a provider's tokens, but nothing bound a static secret to its API: a
+ *   YAML that names TRACKER_TOKEN could aim it at a host of its own. The
+ *   binding is the operator's, never the YAML's: an environment variable or
+ *   `createA2AApp({ credentialHosts })`.
+ *
+ * THE RULE (ADR 0122):
+ *   - With no allowlist configured, nothing changes: a credential goes to
+ *     the host the YAML names, as before. The doctor and the server binary
+ *     name every credential variable a served YAML sends, as unbound.
+ *   - With an allowlist configured, it is the whole list: every credential
+ *     variable a YAML sends must be on it, and every host its value goes to
+ *     must be one of that variable's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends the value.
+ *
+ * WHAT IT COVERS: `bearer_env`, `api_key.env` and `client_secret_env` (both
+ *   grants: the client-credentials token request, the consent step's code
+ *   exchange and its refresh). Not `client_id_env`: a client id is not a
+ *   secret. Not MCP_BEARER_TOKENS: it maps each token to its host already,
+ *   and the operator writes both.
+ *
+ * THE FORMAT: `MELCHIZEDEK_CREDENTIAL_HOSTS="TRACKER_TOKEN=api.tracker.example.com;WEATHER_KEY=api.weather.example.com,*.weather.example.com"`.
+ *   Entries are separated by `;` (or a newline), a variable from its hosts by
+ *   `=`, hosts by `,`. A host is what the OAuth host allowlist takes
+ *   (lib/tools/oauthHosts.ts): a hostname, `*.example.com`, IPv4 or
+ *   `[IPv6]`, with no scheme, port or path.
+ *
+ * Nothing here reads or prints a credential's value: variable names and
+ * hosts only. No regular expression here can backtrack: the separators are
+ * single characters, and a variable name is one bounded character class.
+ */
+import { hostAllowed, hostPatternProblem } from './oauthHosts.js';
+/** The environment variable the allowlist is read from when no option sets it. */
+export const CREDENTIAL_HOSTS_ENV = 'MELCHIZEDEK_CREDENTIAL_HOSTS';
+/** A credential variable's name, as a YAML may write it (lib/syndicateSchema.ts), bounded. */
+const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
+/**
+ * The allowlist, checked and normalized (hosts lowercased, duplicates
+ * dropped). Throws, naming the variable and the host, on anything malformed.
+ */
+export function checkCredentialHosts(allowlist, source = 'credentialHosts') {
+    if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist))
+        throw new Error(`${source} must map each credential variable to its hosts.`);
+    const out = {};
+    for (const [name, hosts] of Object.entries(allowlist)) {
+        if (!ENV_NAME.test(name))
+            throw new Error(`${source}: "${name.slice(0, 64)}" is not an environment variable name (A–Z, 0–9, _).`);
+        if (!Array.isArray(hosts) || hosts.length === 0)
+            throw new Error(`${source}: ${name} needs at least one host.`);
+        const seen = new Set();
+        for (const raw of hosts) {
+            const host = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+            const problem = host ? hostPatternProblem(host) : 'is empty';
+            if (problem)
+                throw new Error(`${source}: ${name}: host "${String(raw).slice(0, 80)}" ${problem}.`);
+            seen.add(host);
+        }
+        out[name] = [...seen];
+    }
+    return out;
+}
+/** The allowlist from its text form (MELCHIZEDEK_CREDENTIAL_HOSTS). Throws on a malformed entry. */
+export function parseCredentialHosts(text) {
+    const parsed = {};
+    for (const entry of text.split(/[;\n]/)) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            throw new Error(`${CREDENTIAL_HOSTS_ENV}: each entry is VARIABLE=host,host (got "${trimmed.slice(0, 80)}").`);
+        const name = trimmed.slice(0, eq).trim();
+        if (Object.hasOwn(parsed, name))
+            throw new Error(`${CREDENTIAL_HOSTS_ENV}: ${name.slice(0, 64)} is listed twice.`);
+        parsed[name] = trimmed.slice(eq + 1).split(',').map((h) => h.trim()).filter((h) => h !== '');
+    }
+    return checkCredentialHosts(parsed, CREDENTIAL_HOSTS_ENV);
+}
+let configured;
+let envCache;
+/**
+ * Sets this process's allowlist (createA2AApp's `credentialHosts` does),
+ * which wins over the environment variable. `undefined` returns to the
+ * variable.
+ */
+export function setCredentialHosts(allowlist) {
+    configured = allowlist === undefined ? undefined : checkCredentialHosts(allowlist);
+}
+/**
+ * The allowlist in force: the one set by `setCredentialHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export function credentialHosts(env = process.env) {
+    if (configured)
+        return configured;
+    const raw = env[CREDENTIAL_HOSTS_ENV];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    if (envCache?.raw !== raw)
+        envCache = { raw, value: parseCredentialHosts(raw) };
+    return envCache.value;
+}
+/**
+ * Why the value of credential variable `name` may not be sent to `url`, or
+ * null. `role` names the URL in the message (`server`, `token_url`).
+ * `allowlist` defaults to the one in force; `null` means none is
+ * configured, which allows (the behaviour before ADR 0122).
+ */
+export function credentialHostProblem(name, url, role = 'server', allowlist = credentialHosts()) {
+    const list = allowlist ?? undefined;
+    if (!list)
+        return null;
+    if (!Object.hasOwn(list, name)) {
+        return `${name} is not on the operator's credential host allowlist (${CREDENTIAL_HOSTS_ENV} or createA2AApp's credentialHosts), so it is sent nowhere`;
+    }
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return `${role} '${url.slice(0, 200)}' is not a URL`;
+    }
+    const hosts = list[name];
+    if (hostAllowed(hosts, hostname))
+        return null;
+    return `${name} may be sent only to ${hosts.join(', ')}; ${hostname} (${role}) is not one of them`;
+}
+/**
+ * The call-time check: why the value of `name` may not be sent to
+ * `destination` now, or null. A malformed allowlist refuses.
+ */
+export function credentialCallProblem(name, destination) {
+    try {
+        return credentialHostProblem(name, destination, 'server', credentialHosts() ?? null);
+    }
+    catch {
+        return `the credential host allowlist (${CREDENTIAL_HOSTS_ENV}) is malformed`;
+    }
+}
+/**
+ * Marks an OAuth client config (lib/tools/oauthConsent.ts) with the
+ * variable its client secret came from, so the consent step's code exchange
+ * and the refresh hook can check the token endpoint at call time. Set by
+ * oauthClientsFor (lib/tools/oauthTools.ts); a client built by hand carries
+ * none and is not checked.
+ */
+export const CLIENT_SECRET_ENV = Symbol.for('melchizedek.clientSecretEnv');
+/** The variable a client config's secret came from, when oauthClientsFor marked it. */
+export function clientSecretEnvOf(client) {
+    const name = client[CLIENT_SECRET_ENV];
+    return typeof name === 'string' ? name : undefined;
+}

package/dist/lib/tools/credentialStore.js

@@ -24,10 +24,17 @@
  *     row: a provider's own error is reported by kind, not by message,
  *     since a provider may echo the token it refused.
  */
-import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { INVALID_SPAN_CONTEXT, SpanStatusCode, trace } from '@opentelemetry/api';
+import { turnUntraced } from '../runtime/turnControl.js';
 import { scopeHashOf } from '../observability/audit.js';
 import { PROVIDER_NAME, ToolCredentialError } from './auth.js';
 const tracer = () => trace.getTracer('melchizedek.credentials');
+/** `credential.refresh` as an active span; in a turn that opted out of tracing, a non-recording one. */
+function withRefreshSpan(provider, fn) {
+    if (turnUntraced())
+        return fn(trace.wrapSpanContext(INVALID_SPAN_CONTEXT));
+    return tracer().startActiveSpan('credential.refresh', { attributes: { 'credential.provider': provider } }, fn);
+}
 /** The AAD a field is sealed under: its app, user, provider and field, NUL-separated. */
 export function credentialContext(key, field) {
     return `${key.appName}\0${key.userId}\0${key.provider}\0${field}`;
@@ -107,7 +114,7 @@ export function credentialStore(options) {
             throw new ToolCredentialError('expired', key.provider);
         }
         const refreshToken = await open(row.refreshTokenEnc, key, 'refresh');
-        return tracer().startActiveSpan('credential.refresh', { attributes: { 'credential.provider': key.provider } }, async (span) => {
+        return withRefreshSpan(key.provider, async (span) => {
             try {
                 let issued;
                 try {

package/dist/lib/tools/credentialUses.d.ts

@@ -0,0 +1,92 @@
+/**
+ * lib/tools/credentialUses.ts — every static credential variable a syndicate
+ * YAML sends somewhere, and where (ADR 0122).
+ *
+ * A YAML sends a static credential in three places: an OpenAPI entry's
+ * `auth.bearer_env` or `auth.api_key.env` (to the spec's server, or
+ * `base_url`), and an `oauth2` block's `client_secret_env` (to its
+ * `token_url`; the OpenAPI entry's or the MCP server's `mcp_auth`). The
+ * operator's credential host allowlist (lib/tools/credentialHosts.ts) is
+ * checked against them when a served syndicate loads
+ * (`syndicateCredentialHostProblems`), and the doctor and the server binary
+ * name each variable no allowlist binds (`unboundCredentialEnvs`).
+ *
+ * Names and hosts only: no value is read here.
+ */
+import type { CredentialHostAllowlist } from './credentialHosts.ts';
+/** One credential variable a YAML sends, and to what. */
+export interface CredentialUse {
+    /** The agent that holds the tools ("Parent › Child" inside a nested file). */
+    agent: string;
+    /** `openapi <spec>` or `mcp <url>`. */
+    tools: string;
+    /** The variable's name. */
+    env: string;
+    /** Where the YAML names it. */
+    role: 'bearer_env' | 'api_key' | 'client_secret_env';
+    /**
+     * The URLs its value goes to: the token endpoint for a client secret,
+     * `base_url` for an OpenAPI entry that sets one. Absent for an OpenAPI
+     * entry whose server is in its spec (read only when checked, by
+     * `syndicateCredentialHostProblems`).
+     */
+    destinations?: string[];
+    /** The OpenAPI entry, for its spec's servers. */
+    openapi?: OpenApiEntryLike;
+}
+/** The parts of an `oauth2` block read here. */
+interface OAuth2Like {
+    token_url: string;
+    client_secret_env?: string;
+}
+/** The parts of an `openapi:` entry read here. */
+interface OpenApiEntryLike {
+    spec?: string;
+    base_url?: string;
+    auth?: {
+        bearer_env?: string;
+        api_key?: {
+            env?: string;
+        };
+        oauth2?: OAuth2Like;
+    };
+}
+interface AgentLike {
+    name?: string;
+    openapi?: OpenApiEntryLike[];
+    mcp_server_url?: string;
+    mcp_auth?: {
+        oauth2?: OAuth2Like;
+    };
+    yaml_reference?: string;
+}
+/** The parts of a syndicate config read here. */
+export interface SyndicateLike {
+    orchestrator?: AgentLike;
+    subagents?: AgentLike[];
+}
+/** The credential variables one agent's tools send. */
+export declare function agentCredentialUses(agent: AgentLike, prefix?: string): CredentialUse[];
+/**
+ * Every credential variable these syndicates send, orchestrators and
+ * subagents, following a nested `yaml_reference:` through `load` when given
+ * (once per file; agent names then read "Parent › Child").
+ */
+export declare function syndicateCredentialUses(configs: readonly SyndicateLike[], load?: (ref: string) => SyndicateLike): CredentialUse[];
+/**
+ * Why these syndicates may not be served here, one line per refusal
+ * (ADR 0122): each credential variable they send, against the operator's
+ * credential host allowlist. With none configured, nothing is refused. The
+ * A2A server checks every syndicate it loads to serve; the compile checks
+ * again, and each call once more.
+ */
+export declare function syndicateCredentialHostProblems(configs: readonly SyndicateLike[], options?: {
+    load?: (ref: string) => SyndicateLike;
+    allowlist?: CredentialHostAllowlist | null;
+}): string[];
+/**
+ * The credential variables these uses send that no allowlist binds, sorted
+ * and once each: every one of them when none is configured. Names only.
+ */
+export declare function unboundCredentialEnvs(uses: readonly CredentialUse[], allowlist: CredentialHostAllowlist | null | undefined): string[];
+export {};

package/dist/lib/tools/credentialUses.js

@@ -0,0 +1,112 @@
+/**
+ * lib/tools/credentialUses.ts — every static credential variable a syndicate
+ * YAML sends somewhere, and where (ADR 0122).
+ *
+ * A YAML sends a static credential in three places: an OpenAPI entry's
+ * `auth.bearer_env` or `auth.api_key.env` (to the spec's server, or
+ * `base_url`), and an `oauth2` block's `client_secret_env` (to its
+ * `token_url`; the OpenAPI entry's or the MCP server's `mcp_auth`). The
+ * operator's credential host allowlist (lib/tools/credentialHosts.ts) is
+ * checked against them when a served syndicate loads
+ * (`syndicateCredentialHostProblems`), and the doctor and the server binary
+ * name each variable no allowlist binds (`unboundCredentialEnvs`).
+ *
+ * Names and hosts only: no value is read here.
+ */
+import { resolve } from 'node:path';
+import { credentialHostProblem, credentialHosts } from './credentialHosts.js';
+import { openApiServers } from './openapiTools.js';
+/** The credential variables one agent's tools send. */
+export function agentCredentialUses(agent, prefix = '') {
+    const name = `${prefix}${agent.name ?? ''}`;
+    const out = [];
+    for (const entry of agent.openapi ?? []) {
+        const tools = `openapi ${entry?.spec ?? ''}`;
+        const auth = entry?.auth;
+        if (!auth)
+            continue;
+        const servers = entry.base_url ? { destinations: [entry.base_url] } : {};
+        if (auth.bearer_env)
+            out.push({ agent: name, tools, env: auth.bearer_env, role: 'bearer_env', ...servers, openapi: entry });
+        if (auth.api_key?.env)
+            out.push({ agent: name, tools, env: auth.api_key.env, role: 'api_key', ...servers, openapi: entry });
+        if (auth.oauth2?.client_secret_env)
+            out.push({ agent: name, tools, env: auth.oauth2.client_secret_env, role: 'client_secret_env', destinations: [auth.oauth2.token_url] });
+    }
+    const mcp = agent.mcp_auth?.oauth2;
+    if (mcp?.client_secret_env)
+        out.push({ agent: name, tools: `mcp ${agent.mcp_server_url ?? ''}`, env: mcp.client_secret_env, role: 'client_secret_env', destinations: [mcp.token_url] });
+    return out;
+}
+/**
+ * Every credential variable these syndicates send, orchestrators and
+ * subagents, following a nested `yaml_reference:` through `load` when given
+ * (once per file; agent names then read "Parent › Child").
+ */
+export function syndicateCredentialUses(configs, load) {
+    const out = [];
+    const seen = new Set();
+    const visit = (config, prefix) => {
+        const agents = [config.orchestrator, ...(config.subagents ?? [])].filter((a) => !!a);
+        for (const agent of agents) {
+            if (agent.yaml_reference) {
+                if (!load || seen.has(agent.yaml_reference))
+                    continue;
+                seen.add(agent.yaml_reference);
+                visit(load(agent.yaml_reference), `${prefix}${agent.name ?? agent.yaml_reference} › `);
+                continue;
+            }
+            out.push(...agentCredentialUses(agent, prefix));
+        }
+    };
+    for (const config of configs)
+        visit(config, '');
+    return out;
+}
+/** The URLs a use's value goes to; an OpenAPI spec that cannot be read gives none (its compile fails on its own). */
+function destinationsOf(use) {
+    if (use.destinations)
+        return use.destinations;
+    if (!use.openapi?.spec)
+        return [];
+    try {
+        return openApiServers(use.openapi, resolve(process.cwd()));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Why these syndicates may not be served here, one line per refusal
+ * (ADR 0122): each credential variable they send, against the operator's
+ * credential host allowlist. With none configured, nothing is refused. The
+ * A2A server checks every syndicate it loads to serve; the compile checks
+ * again, and each call once more.
+ */
+export function syndicateCredentialHostProblems(configs, options = {}) {
+    const allowlist = options.allowlist === undefined ? credentialHosts() ?? null : options.allowlist;
+    if (!allowlist)
+        return [];
+    const out = new Set();
+    for (const use of syndicateCredentialUses(configs, options.load)) {
+        const role = use.role === 'client_secret_env' ? 'token_url' : 'server';
+        const where = `${use.agent} · ${use.tools} · ${use.role}`;
+        if (!Object.hasOwn(allowlist, use.env)) {
+            out.add(`${where}: ${credentialHostProblem(use.env, '', role, allowlist)}`);
+            continue;
+        }
+        for (const url of destinationsOf(use)) {
+            const problem = credentialHostProblem(use.env, url, role, allowlist);
+            if (problem)
+                out.add(`${where}: ${problem}`);
+        }
+    }
+    return [...out];
+}
+/**
+ * The credential variables these uses send that no allowlist binds, sorted
+ * and once each: every one of them when none is configured. Names only.
+ */
+export function unboundCredentialEnvs(uses, allowlist) {
+    return [...new Set(uses.map((u) => u.env))].filter((name) => !allowlist || !Object.hasOwn(allowlist, name)).sort();
+}

package/dist/lib/tools/mcpToolFactory.d.ts

@@ -1,5 +1,6 @@
 import type { ToolDeclaration } from '../models/contract.ts';
 import type { RedirectPolicy } from '../net/redirects.ts';
+import type { OAuth2AuthConfig } from './oauthTools.ts';
 import type { Tool } from './tool.ts';
 export declare function assertSafeMcpUrl(raw: string, env?: NodeJS.ProcessEnv): Promise<URL>;
 export declare function mcpAuthHeaders(url: URL, env?: NodeJS.ProcessEnv): Record<string, string>;
@@ -41,11 +42,33 @@ export declare function mcpToolParameters(inputSchema: {
     properties?: Record<string, unknown>;
     required?: string[];
 } | undefined): ToolDeclaration['parameters'];
+/** How an agent reaches its MCP server: which tools it may use, and the OAuth grant the server takes. */
+export interface McpToolOptions {
+    /** `mcp_tools`: the names this agent may use. Required with an authorization_code grant. */
+    tools?: string[];
+    /** `mcp_auth.oauth2` (ADR 0112). Without it, MCP_BEARER_TOKENS applies. */
+    oauth2?: OAuth2AuthConfig;
+}
+/** Per-user connections at most per authorization-code server; the least recently used is closed first. */
+export declare const MAX_MCP_USER_CONNECTIONS = 64;
 /**
  * The tools a remote MCP server offers, as own Tools, or none when the
  * server cannot be reached or refuses (logged, never thrown). The
  * connection stays open for the tools' calls; closeMcpConnections ends it.
+ *
+ * With `oauth2` (ADR 0112):
+ *   - client_credentials: one connection, every request carrying the
+ *     server's own token for the provider (lib/tools/oauthTools.ts).
+ *   - authorization_code: the token is each user's, so there is no
+ *     connection at compile time. Each name in `tools` becomes a Tool whose
+ *     call reads the run's user's token (`ctx.accessToken`, which asks for
+ *     consent when the user has not granted it) and runs on that user's own
+ *     connection. The parameters are the server's, learned from the first
+ *     listing any user's connection makes; until then a call connects and
+ *     asks the model to call again with them, rather than call blind.
+ * A missing variable or a refused URL fails the compile (thrown), naming
+ * the variable, never a value.
  */
-export declare function loadMcpTools(mcpServerUrl: string): Promise<Tool[]>;
+export declare function loadMcpTools(mcpServerUrl: string, options?: McpToolOptions): Promise<Tool[]>;
 /** The server's tools, as the compiler lists them on an agent: loadMcpTools' own Tools. */
-export declare function createMcpTools(mcpServerUrl: string): Promise<Tool[]>;
+export declare function createMcpTools(mcpServerUrl: string, options?: McpToolOptions): Promise<Tool[]>;