@jini-ai/mcp 0.3.3 → 0.4.0

package/dist/federation/approvals/ports.d.ts

@@ -0,0 +1,107 @@
+import type { Clock } from "@jini-ai/core/primitives";
+import type { FederationMessages } from "../messages.js";
+import type { FederatedCallConfirmationRequest } from "../ports.js";
+import type { ConversationToolApprovalStore, ExternalMcpToolApprovalRepoPort } from "../tool-approvals.js";
+/** Minimal execution identity; the application may pass its richer context unchanged. */
+export interface FederatedConfirmationContext {
+    readonly principal: {
+        readonly id: string;
+    };
+    readonly run: {
+        readonly id: string;
+    };
+}
+/** Presentation data only. Rendering and exchange lifecycle belong to host adapters. */
+export interface FederatedConfirmationSpec {
+    readonly toolId: string;
+    readonly errorCode: string;
+    readonly title: string;
+    readonly description: string;
+    readonly details: readonly {
+        readonly label: string;
+        readonly value: string;
+        readonly format?: "code";
+    }[];
+    readonly warning: string;
+    readonly danger: boolean;
+    readonly confirmLabel: string;
+    readonly alternatives?: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly choice: "chat" | "always";
+    }[];
+}
+export interface FederatedCardOffers {
+    readonly offerChat: boolean;
+    readonly offerAlways: boolean;
+}
+export type FederatedHumanConfirmOutcome = {
+    readonly confirmed: true;
+    readonly choice?: string;
+} | {
+    readonly confirmed: false;
+    readonly result: Readonly<Record<string, unknown>>;
+};
+/** The host binds its exchange store and maps cancelled/expired/abandoned answers to results.
+ * Adapters must bind the answer to this principal, tool and execution, and accept it only once.
+ */
+export interface FederatedHumanConfirmPort<Context extends FederatedConfirmationContext, Exchanges> {
+    ask(required: {
+        context: Context;
+        surfaceExchanges: Exchanges;
+        spec: FederatedConfirmationSpec;
+    }): Promise<FederatedHumanConfirmOutcome>;
+}
+/** Optional remembered scopes; a missing store or conversation removes that choice. */
+export interface FederatedApprovalDeps {
+    readonly mayAlwaysAllow: (required: {
+        principalId: string;
+    }, optional?: {
+        scope?: string;
+    }) => Promise<boolean>;
+    readonly clock: Clock;
+    readonly always?: ExternalMcpToolApprovalRepoPort;
+    readonly chat?: ConversationToolApprovalStore;
+    readonly conversationIdForRun?: (required: {
+        runId: string;
+    }) => string | undefined;
+}
+/** Host can enqueue durable webhooks; no transport or webhook package is imported here. */
+export interface FederatedApprovalWebhookPort {
+    approvalRemembered(required: {
+        principalId: string;
+        connectionId: string;
+        toolName: string;
+        fingerprint: string;
+        scope: "chat" | "always";
+        grantedAt: string;
+    }, optional?: {
+        scope?: string;
+    }): Promise<void>;
+}
+export interface FederatedApprovalDiagnostic {
+    readonly toolId: string;
+    readonly choice: string;
+    readonly stage: "store" | "webhook";
+    readonly error: unknown;
+}
+export interface FederatedCallConfirmerRequired<Context extends FederatedConfirmationContext, Exchanges> {
+    readonly messages: FederationMessages;
+    readonly fingerprintDomain: string;
+    readonly errorCode: string;
+    readonly surfaceExchanges: Exchanges;
+    readonly humanConfirm: FederatedHumanConfirmPort<Context, Exchanges>;
+}
+export interface FederatedCallConfirmerOptions {
+    /** Opaque host storage partition; never interpreted by federation. */
+    readonly scope?: string;
+    readonly approvals?: FederatedApprovalDeps;
+    readonly webhooks?: FederatedApprovalWebhookPort;
+    readonly onPersistenceError?: (required: FederatedApprovalDiagnostic) => void;
+}
+/** Used by adapters without depending on a tool runtime's callback signature. */
+export interface FederatedConfirmCallInput<Context extends FederatedConfirmationContext> {
+    readonly context: Context;
+    readonly request: FederatedCallConfirmationRequest;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/federation/approvals/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/federation/approvals/revocation.d.ts

@@ -0,0 +1,61 @@
+import type { FederatedCallTarget } from "../ports.js";
+export type ExternalMcpRevocationReason = "removed" | "turned-off" | "disconnected" | "changed" | "tool-not-allowed" | "write-not-allowed" | "unverifiable";
+/** Host projection of the current row; revision derivation and credential status stay in adapters. */
+export interface ConnectionRosterSnapshot {
+    readonly label: string | null;
+    readonly enabled: boolean;
+    readonly admissionRevision: string;
+    readonly disconnected: boolean;
+    readonly grants: {
+        readonly allowedToolNames: readonly string[];
+        readonly writeAllowedToolNames: readonly string[];
+    };
+}
+/** A primary-key read per call. The host implements this over its ExternalMcpServerRepoPort. */
+export interface ConnectionRosterReader {
+    findByServerId(required: {
+        serverId: string;
+    }, optional?: {
+        scope?: string;
+    }): Promise<ConnectionRosterSnapshot | null>;
+}
+export interface FederatedConnectionRefusal {
+    readonly serverId: string;
+    readonly label: string | null;
+    readonly remoteName: string;
+    readonly reason: ExternalMcpRevocationReason;
+}
+/** Host preserves its error subclass, validation classification and exact model-facing wording. */
+export interface FederatedRevocationErrorFactoryPort {
+    create(required: FederatedConnectionRefusal): Error;
+}
+export interface FederatedRevocationWebhookPort {
+    connectionRefused(required: FederatedConnectionRefusal, optional?: {
+        scope?: string;
+    }): Promise<void>;
+}
+export interface FederatedRevocationDiagnostic {
+    readonly connectionId: string;
+    readonly stage: "store" | "webhook";
+    readonly error: unknown;
+}
+/** Pure current-row check. Ordering matches admission semantics: identity before mutable grants. */
+export declare function rosterRefusalFor({ record, call }: {
+    record: ConnectionRosterSnapshot | null;
+    call: FederatedCallTarget;
+}): ExternalMcpRevocationReason | null;
+/** Revocation half of a connection gate; credential refresh/reauth checks are composed by the host.
+ * Presets have no roster row. Reads and notification failures never disclose driver errors.
+ */
+export declare function createFederatedConnectionRevocationGate(required: {
+    roster: ConnectionRosterReader;
+    errorFactory: FederatedRevocationErrorFactoryPort;
+}, optional?: {
+    scope?: string;
+    webhooks?: FederatedRevocationWebhookPort;
+    onDiagnostic?: (required: FederatedRevocationDiagnostic) => void;
+}): (required: {
+    connectionId: string;
+    call: FederatedCallTarget;
+}) => Promise<void>;
+//# sourceMappingURL=revocation.d.ts.map

package/dist/federation/approvals/revocation.js

@@ -0,0 +1,52 @@
+import { refusalForAdmittedToolUnderCurrentGrants } from "../trust.js";
+/** Pure current-row check. Ordering matches admission semantics: identity before mutable grants. */
+export function rosterRefusalFor({ record, call }) {
+    if (call.origin === undefined || call.origin.kind === "preset")
+        return "unverifiable";
+    if (record === null)
+        return "removed";
+    if (record.admissionRevision !== call.origin.admissionRevision)
+        return "changed";
+    if (!record.enabled)
+        return "turned-off";
+    if (record.disconnected)
+        return "disconnected";
+    const refusal = refusalForAdmittedToolUnderCurrentGrants({ tool: call, grants: record.grants });
+    return refusal === null ? null : refusal === "remote-declares-not-read-only" ? "write-not-allowed" : "tool-not-allowed";
+}
+/** Revocation half of a connection gate; credential refresh/reauth checks are composed by the host.
+ * Presets have no roster row. Reads and notification failures never disclose driver errors.
+ */
+export function createFederatedConnectionRevocationGate(required, optional = {}) {
+    const report = (diagnostic) => {
+        try {
+            optional.onDiagnostic?.(diagnostic);
+        }
+        catch { /* Diagnostics cannot bypass refusal. */ }
+    };
+    return async ({ connectionId, call }) => {
+        if (call.origin?.kind === "preset")
+            return;
+        let record = null;
+        let reason;
+        try {
+            record = await required.roster.findByServerId({ serverId: connectionId }, optional.scope === undefined ? {} : { scope: optional.scope });
+            reason = rosterRefusalFor({ record, call });
+        }
+        catch (error) {
+            report({ connectionId, stage: "store", error });
+            reason = "unverifiable";
+        }
+        if (reason === null)
+            return;
+        const refusal = { serverId: connectionId, label: record?.label ?? null, remoteName: call.remoteName, reason };
+        try {
+            await optional.webhooks?.connectionRefused(refusal, optional.scope === undefined ? {} : { scope: optional.scope });
+        }
+        catch (error) {
+            report({ connectionId, stage: "webhook", error });
+        }
+        throw required.errorFactory.create(refusal);
+    };
+}
+//# sourceMappingURL=revocation.js.map

package/dist/federation/bootstrap.d.ts

@@ -0,0 +1,100 @@
+import { type Logger } from "@jini-ai/core/primitives";
+import type { ToolRegistry } from "@jini-ai/core";
+import type { ResolvedFederatedConnection } from "./config.js";
+import type { McpSessionPort } from "./ports.js";
+import { type FederationDeps } from "./registrations.js";
+import type { FederatedAdmissionReport } from "./trust.js";
+export interface AttachFederatedToolsResult {
+    /** Ids actually registered. Empty when federation is off or every attempt failed. */
+    readonly registeredToolIds: readonly string[];
+    /** Live sessions, for the caller to close at shutdown. */
+    readonly sessions: readonly McpSessionPort[];
+    /**
+     * One entry per connection that reached admission — i.e. every connection whose session
+     * connected and listed tools, whether or not any tool was ultimately registered. A connection
+     * that failed before `federateSession` ran (a bad spawn, a timed-out handshake, a collision) has
+     * no admission decision to report and contributes no entry here — see
+     * {@link attachOneFederatedConnection}'s catch branch.
+     *
+     * This is the same accounting `logFederatedAdmissionReport` already turns into stderr lines and
+     * then discards. Kept here so a caller (today, `agent-daemon-server.ts`, over `GET
+     * /api/federation/admissions`) can serve it to an operator instead of it only ever reaching
+     * whoever happens to be tailing the daemon's terminal at boot. See the write-tools implementation
+     * outline,.
+   * See docs/decisions/DR-001-federation-admission.md.
+   */
+    readonly reports: readonly {
+        readonly connectionId: string;
+        readonly report: FederatedAdmissionReport;
+        /**
+         * Whether this connection came from `presets.ts`'s registry rather than the operator-editable
+         * roster (`extraConnections` below). Threaded through so a consumer — today, the admin admissions
+         * banner (`external-mcp-admissions-rules.ts`) — can tell "no roster card because this is a preset,
+         * by design" apart from "no roster card because the operator just deleted it". Both looked
+         * identical before this field existed (`connectionId` absent from the roster either way), which
+         * is exactly why a genuinely-deleted-but-still-live roster connection was silently reported as
+         * agreeing instead of as drift (2026-09-07, the follow-on ADM-001 left open).
+         */
+        readonly isPreset: boolean;
+    }[];
+    /**
+     * One entry per connection that failed BEFORE reaching admission — a bad spawn, a timed-out
+     * handshake, a malformed tool listing, or a native-id collision (2026-09-24). This is the
+     * connection-level counterpart to `reports` above: `reports` never carries an entry for one of
+     * these (see {@link attachOneFederatedConnection}'s catch branch), which used to mean the
+     * connection was simply invisible everywhere an operator could look — `GET
+     * /api/federation/admissions` showed no row for it and `configFailures` (a SEPARATE, boot-time
+     * config-resolution channel — see `external-mcp-connection-source.ts`) has no way to know about a
+     * failure that happens deeper, inside `connect()` itself. `reason` is `messageOf(error)` — the
+     * same text `logger.warn` already prints for this exact failure, so this field discloses nothing
+     * that was not already reaching this process's own stderr; it is never a raw env value or secret,
+     * since nothing in this file's `connect`/`spawn` error paths ever formats one into a message.
+     */
+    readonly connectFailures: readonly {
+        readonly connectionId: string;
+        readonly reason: string;
+    }[];
+}
+/**
+ * Connects every configured federated MCP server, registers whatever clears the trust tier into
+ * `registry`, and returns what happened.
+ *
+ * Must be awaited BEFORE `buildToolCatalogQuery(registry)` runs: that function snapshots
+ * `registry.list({})` into an FTS index once, so a tool registered afterwards would be executable but
+ * invisible to `search_tools`/`describe_tool`.
+ *
+ * @param params.registry - The daemon's registry, already populated with the native catalog.
+ * @param params.deps - `permissionGate` + an optional opaque `scope`, the slice federated handlers gate against.
+ * @param params.connections - Defaults to whatever the presets registered with `presets.ts` resolve
+ * from the environment.
+ * @param params.connect - Session factory, injected so tests substitute a double for the real
+ * `spawn` + handshake.
+ * @returns The registered ids, the open sessions, and one admission report per connection that
+ *   reached admission. Never rejects.
+ * @complexity O(c · t) in connections and their advertised tools.
+ */
+export interface AttachFederatedMcpToolsParams {
+    registry: ToolRegistry;
+    deps: FederationDeps;
+    connections?: readonly ResolvedFederatedConnection[] | undefined;
+    /**
+     * Connections from a config source that is not the preset registry — today, the operator-editable
+     * roster in `assistant/external-mcp-store.ts`.
+     *
+     * A second parameter rather than a second preset, because `FederatedMcpPresetResolver` cannot
+     * express this source: it is synchronous (a DB read plus an unseal are not) and returns at most
+     * one connection (a roster returns N). Appended AFTER the presets so a preset keeps first claim on
+     * a contested tool id under R1, which preserves the existing behaviour of every already-configured
+     * deployment — an operator adding a row cannot displace a vendor preset that was already working.
+     */
+    extraConnections?: readonly ResolvedFederatedConnection[] | undefined;
+    connect: (request: {
+        connection: ResolvedFederatedConnection;
+    }) => Promise<McpSessionPort>;
+    logger?: Logger | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+}
+export type AttachFederatedMcpToolsRequiredArgs = Pick<AttachFederatedMcpToolsParams, "registry" | "deps" | "connect">;
+export type AttachFederatedMcpToolsOptions = Omit<AttachFederatedMcpToolsParams, "registry" | "deps" | "connect">;
+export declare function attachFederatedMcpTools(requiredArgs: AttachFederatedMcpToolsRequiredArgs, optionalArgs?: AttachFederatedMcpToolsOptions): Promise<AttachFederatedToolsResult>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/federation/bootstrap.js

@@ -0,0 +1,182 @@
+import { createConsoleLogger } from "@jini-ai/core/primitives";
+import { listFederatedMcpPresets } from "./presets.js";
+import { federateSession } from "./registrations.js";
+/**
+ * @file The composition root for outbound MCP federation: the one function
+ * `agent-daemon-server.ts` calls, and the only place in this subtree that performs I/O it was not
+ * handed.
+ *
+ * Split out of `agent-daemon-server.ts` for the reason `tool-catalog-query.ts` and `daemon-auth.ts`
+ * were: that file is a top-level side-effecting script which opens a real port and a real DB
+ * connection on import, so nothing in it can be imported by a test. Everything here can be.
+ *
+ * FAIL-OPEN, and deliberately the opposite of `daemon-auth.ts`'s fail-closed gate. The two are
+ * answering different questions. `requireAgentDaemonToken` guards ACCESS TO host app, where failing
+ * open would admit unauthenticated callers, so an unconfigured gate must refuse to serve. This
+ * guards an OPTIONAL OUTBOUND CONVENIENCE, where failing closed would mean a third party's server
+ * being slow, broken, or absent takes host app's own assistant down with it. A vendor host app does not
+ * control must never be on the critical path of host app booting. So every failure here — unreachable
+ * server, timed-out handshake, malformed tool list, invalid config — is logged and stepped over,
+ * and the daemon continues with its native catalog exactly as it did before this capability
+ * existed.
+ *
+ * The one thing that is NOT stepped over is a native id collision (`trust.ts` R1): that throws out
+ * of `federateSession` and is caught here like any other failure, so the connection is dropped
+ * whole rather than partially registered. Dropping the connection is the safe direction — the
+ * failure mode it prevents is a remote shadowing a host app tool, and "no federated tools" is always an
+ * acceptable outcome.
+ *
+ * VENDOR-BLIND. Nothing in this file names a vendor: which servers exist is whatever registered
+ * itself with `presets.ts` (none today: the Supabase env preset was retired on 2026-09-29), plus the
+ * stored roster. Before 2026-07-30 this file imported
+ * Supabase's resolver directly, which meant adding a second vendor was an edit to core federation.
+ * See `presets.ts` for the seam's rationale.
+ */
+/** Where the admission report goes. Injected so tests assert on it instead of scraping stdout, and
+ * so a future structured logger is a parameter change rather than an edit. */
+const consoleLogger = createConsoleLogger({ prefix: "agent-daemon" });
+/** Resolves the defaulted inputs `attachFederatedMcpTools` needs — `logger`, `connect`, and the
+ *  merged connection list (presets or an injected override, plus any extra roster connections),
+ *  each tagged with its origin. Split out purely to keep that function under the shop complexity
+ *  ceiling.
+ *
+ *  `params.connections` (an injected override, used throughout this file's own tests) stands in for
+ *  the preset list, not the roster — it replaces `resolveRegisteredPresets`'s result, and
+ *  `extraConnections` is documented on {@link AttachFederatedMcpToolsParams} as specifically the
+ *  operator-editable roster. So the origin tag is exactly which of the two arrays a connection came
+ *  from, unchanged from before this field existed. */
+/** Stamps a preset-sourced connection's config with `origin: {kind:"preset"}`, so
+ *  `external-mcp-revocation.ts`'s per-call gate can tell it apart from a roster connection (which
+ *  carries its OWN origin already, stamped by `external-mcp-store.ts`'s
+ *  `toResolvedFederatedConnections`) and skip the row re-check a preset has no row to support. Split
+ *  out purely to keep {@link resolveFederationAttachInputs} under the shop complexity ceiling. */
+function withPresetOrigin(connection) {
+    return { ...connection, config: { ...connection.config, origin: { kind: "preset" } } };
+}
+function resolveFederationAttachInputs(params) {
+    const logger = params.logger ?? consoleLogger;
+    const connect = params.connect;
+    const presetConnections = params.connections ?? resolveRegisteredPresets(params.env ?? process.env, logger);
+    const connections = [
+        ...presetConnections.map((connection) => ({ connection: withPresetOrigin(connection), isPreset: true })),
+        ...(params.extraConnections ?? []).map((connection) => ({ connection, isPreset: false })),
+    ];
+    return { logger, connect, connections };
+}
+export async function attachFederatedMcpTools(requiredArgs, optionalArgs = {}) {
+    const params = { ...requiredArgs, ...optionalArgs };
+    const { logger, connect, connections } = resolveFederationAttachInputs(params);
+    if (connections.length === 0)
+        return { registeredToolIds: [], sessions: [], reports: [], connectFailures: [] };
+    const registeredToolIds = [];
+    const sessions = [];
+    const reports = [];
+    const connectFailures = [];
+    for (const { connection, isPreset } of connections) {
+        const attached = await attachOneFederatedConnection({ connection, registry: params.registry, deps: params.deps, connect, logger });
+        registeredToolIds.push(...attached.registeredToolIds);
+        if (attached.session)
+            sessions.push(attached.session);
+        if (attached.report)
+            reports.push({ connectionId: connection.config.connectionId, report: attached.report, isPreset });
+        if (attached.connectFailureReason !== undefined) {
+            connectFailures.push({ connectionId: connection.config.connectionId, reason: attached.connectFailureReason });
+        }
+    }
+    return { registeredToolIds, sessions, reports, connectFailures };
+}
+/** Registers every admitted tool from one connection's {@link federateSession} pass into
+ *  `registry`, returning the ids actually registered. Split out of
+ *  {@link attachOneFederatedConnection} purely to keep that function's complexity under the shop
+ *  ceiling. */
+function registerFederatedTools(registry, registrations) {
+    const registeredToolIds = [];
+    for (const registration of registrations) {
+        registry.register(registration);
+        registeredToolIds.push(registration.descriptor.id);
+    }
+    return registeredToolIds;
+}
+/** Logs one connection's full admission accounting. Refusals are reported, never silent —
+ *  `buildDomainRegistrations`'s own "silence is never the outcome" discipline. An operator
+ *  debugging a missing tool needs the reason, and an operator reading logs after an incident needs
+ *  to see what a remote TRIED to expose. Split out of {@link attachOneFederatedConnection} purely
+ *  to keep that function's complexity under the shop ceiling.
+ *
+ *  The two `writeAuthorized`/`writeAllowedButNotAllowlisted` lines are WARN, not INFO, on purpose:
+ *  an operator-authorized write tool entering the model's catalog — or an operator's write
+ *  authorization silently doing nothing because the same name is missing from the allowlist — is a
+ *  security-relevant boot event, not routine informational noise. See the write-tools
+ *  implementation outline §9. */
+function logFederatedAdmissionReport(connectionId, report, logger) {
+    for (const refusal of report.refused) {
+        logger.warn({ message: `mcp-federation: '${connectionId}' refused remote tool '${refusal.remoteName}' — ${refusal.reason}` });
+    }
+    for (const admitted of report.admitted) {
+        if (admitted.writeAuthorized) {
+            logger.warn({ message: `mcp-federation: '${connectionId}' admitted WRITE tool '${admitted.remoteName}' (operator-authorized)` });
+        }
+    }
+    for (const absent of report.allowlistedButAbsent) {
+        logger.warn({ message: `mcp-federation: '${connectionId}' allowlists '${absent}' but the server never advertised it — check the allowlist for a typo, or the server's --features` });
+    }
+    for (const drift of report.writeAllowedButNotAllowlisted) {
+        logger.warn({ message: `mcp-federation: '${connectionId}' write-authorizes '${drift}' but it is not in the allowlist — it will never be admitted until it is added to both` });
+    }
+}
+/** One iteration of {@link attachFederatedMcpTools}'s original inline loop body — connect, list,
+ *  admit, register, log — extracted purely to keep that function's complexity under the shop
+ *  ceiling. Fail-open per connection: any failure (connect, list, or admission) is logged and
+ *  swallowed here rather than propagated, matching this file's own fail-open doc. A session that
+ *  connected but failed later still gets closed. */
+async function attachOneFederatedConnection(params) {
+    const { connection, registry, deps, connect, logger } = params;
+    const { connectionId } = connection.config;
+    let session;
+    try {
+        session = await connect({ connection });
+        // Snapshotted here, immediately before the admission check, so the collision assertion sees
+        // every native tool AND every tool an earlier connection in this same loop already claimed.
+        const nativeToolIds = new Set(registry.list({}).map((descriptor) => descriptor.id));
+        const { registrations, report } = await federateSession({ session, config: connection.config, deps, nativeToolIds });
+        const registeredToolIds = registerFederatedTools(registry, registrations);
+        logger.info({ message: `mcp-federation: '${connectionId}' registered ${registrations.length} federated tool(s): ${registrations.map((r) => r.descriptor.id).join(", ") || "(none)"}` });
+        logFederatedAdmissionReport(connectionId, report, logger);
+        return { registeredToolIds, session, report };
+    }
+    catch (error) {
+        logger.warn({ message: `mcp-federation: '${connectionId}' failed, continuing without its tools — ${messageOf(error)}` });
+        // A session that connected but failed during listing/admission still owns a child process.
+        await session?.close({}).catch(() => undefined);
+        return { registeredToolIds: [], session: null, report: null, connectFailureReason: messageOf(error) };
+    }
+}
+/**
+ * Asks every registered preset for a connection, in registration order.
+ *
+ * Errors are isolated PER PRESET rather than abandoning the whole resolution pass: an enabled-but-
+ * invalid Supabase config must not also disable a correctly-configured second vendor that happens to
+ * be registered after it. Each failure is loud — the operator meant to have that connection and does
+ * not — and still non-fatal, because host app's own assistant is unaffected either way.
+ *
+ * A preset that declines (`null`) is silent: "not configured" is the expected default state, and
+ * logging it every boot would train operators to ignore this channel.
+ */
+function resolveRegisteredPresets(env, logger) {
+    const connections = [];
+    for (const preset of listFederatedMcpPresets()) {
+        try {
+            const connection = preset.resolve({ env: env });
+            if (connection)
+                connections.push(connection);
+        }
+        catch (error) {
+            logger.warn({ message: `mcp-federation: preset '${preset.presetId}' configuration is invalid, continuing without federated tools — ${messageOf(error)}` });
+        }
+    }
+    return connections;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/federation/config.d.ts

@@ -0,0 +1,68 @@
+import type { FederatedMcpConnectionConfig, McpLaunchSpec } from "./ports.js";
+/**
+ * @file GENERIC configuration-resolution scaffolding for federated MCP connections — the parts every
+ * vendor preset needs and none of which names a vendor.
+ *
+ * What this file deliberately does NOT contain, as of 2026-07-30: any specific vendor's preset. The
+ * Supabase preset this capability was designed and verified against used to live here; it moved to
+ * `src/features/plugins/supabase-mcp/` on 2026-07-30 and was retired on 2026-09-29 (Supabase is now
+ * the `content/agent-plugins/supabase` Agent Plugin). The reasoning is the same one that keeps `store-plugin.ts` and `deploy-plugin.ts` out
+ * of `src/server` proper: a concrete vendor integration that ships by default is still an OPTIONAL
+ * module, and a reader who finds it inside `src/assistant/` reasonably concludes the assistant
+ * REQUIRES it. Nothing in `mcp-federation/` should be readable as "host app's assistant needs Supabase".
+ *
+ * What stays here is the scaffolding a SECOND preset would otherwise have to duplicate: the
+ * resolved-connection shape, the shared timeout/size ceilings, and the three env-parsing helpers
+ * (enabled-flag, comma list, positive int). Their semantics are the load-bearing part — see each
+ * one's own comment — and having exactly one implementation of them is what makes two presets behave
+ * the same way about the same kind of setting.
+ *
+ * Architectural role:
+ * Configuration resolution. Pure apart from reading an injected env bag. No I/O.
+ */
+/**
+ * One fully-resolved federated connection: how to reach it, and the policy to hold it to.
+ *
+ * This is the whole contract between a vendor preset and core federation. A preset's entire job is
+ * to produce one of these (or `null`); everything downstream — `presets.ts`, `bootstrap.ts`,
+ * `trust.ts`, `registrations.ts` — is vendor-blind and works off this shape alone.
+ *
+ * `launch` is TRANSPORT-BLIND too: a local command or a hosted endpoint, and every policy field
+ * beside it applies identically to both. That is what lets an operator move a connection from a
+ * locally-launched server to the vendor's hosted one without any of the trust machinery noticing.
+ */
+export interface ResolvedFederatedConnection {
+    readonly config: FederatedMcpConnectionConfig;
+    readonly launch: McpLaunchSpec;
+}
+/**
+ * Shared ceilings, so two presets do not disagree about what a reasonable bound is.
+ *
+ * A preset may override any of them when it has a vendor-specific reason (and should say why); the
+ * point of a shared default is that "no particular reason" resolves to the same number everywhere.
+ */
+export declare const FEDERATED_CONNECTION_DEFAULTS: {
+    readonly connectTimeoutMs: 60000;
+    readonly callTimeoutMs: 30000;
+    readonly maxResultBytes: number;
+    readonly maxTools: 32;
+};
+/** `1`/`true`/`yes`/`on`, case-insensitive. Anything else — including unset — is off, because the
+ * default for connecting an assistant to a third party must be "no". */
+export declare function isFederationEnabled({ value }: {
+    value: string | undefined;
+}): boolean;
+/** `undefined` (use the preset's default) is distinguished from `""` (an operator explicitly
+ * allowing nothing), so setting the variable empty is a working way to disable every tool without
+ * unsetting the connection. */
+export declare function parseAllowedToolNames({ value }: {
+    value: string | undefined;
+}): string[] | null;
+/** Malformed and non-positive values fall back rather than throw: a mistyped timeout should not be
+ * the difference between having federation and not, whereas a mistyped credential or project scope
+ * (which a preset validates itself) should be. */
+export declare function positiveIntOrDefault({ value, fallback }: {
+    value: string | undefined;
+    fallback: number;
+}): number;
+//# sourceMappingURL=config.d.ts.map

package/dist/federation/config.js

@@ -0,0 +1,40 @@
+/**
+ * Shared ceilings, so two presets do not disagree about what a reasonable bound is.
+ *
+ * A preset may override any of them when it has a vendor-specific reason (and should say why); the
+ * point of a shared default is that "no particular reason" resolves to the same number everywhere.
+ */
+export const FEDERATED_CONNECTION_DEFAULTS = {
+    connectTimeoutMs: 60_000,
+    callTimeoutMs: 30_000,
+    maxResultBytes: 64 * 1024,
+    maxTools: 32,
+};
+/** `1`/`true`/`yes`/`on`, case-insensitive. Anything else — including unset — is off, because the
+ * default for connecting an assistant to a third party must be "no". */
+export function isFederationEnabled({ value }) {
+    if (typeof value !== "string")
+        return false;
+    return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+/** `undefined` (use the preset's default) is distinguished from `""` (an operator explicitly
+ * allowing nothing), so setting the variable empty is a working way to disable every tool without
+ * unsetting the connection. */
+export function parseAllowedToolNames({ value }) {
+    if (typeof value !== "string")
+        return null;
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+/** Malformed and non-positive values fall back rather than throw: a mistyped timeout should not be
+ * the difference between having federation and not, whereas a mistyped credential or project scope
+ * (which a preset validates itself) should be. */
+export function positiveIntOrDefault({ value, fallback }) {
+    if (typeof value !== "string")
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+//# sourceMappingURL=config.js.map

package/dist/federation/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./ports.js";
+export * from "./mcp-protocol.js";
+export * from "./adapter.http.js";
+export * from "./config.js";
+export * from "./presets.js";
+export * from "./trust.js";
+export * from "./refusal-notice.js";
+export * from "./registrations.js";
+export * from "./bootstrap.js";
+export * from "./reload.js";
+export * from "./tool-approvals.js";
+export * from "./approvals/index.js";
+export * from "./messages.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/federation/index.js

@@ -0,0 +1,14 @@
+export * from "./ports.js";
+export * from "./mcp-protocol.js";
+export * from "./adapter.http.js";
+export * from "./config.js";
+export * from "./presets.js";
+export * from "./trust.js";
+export * from "./refusal-notice.js";
+export * from "./registrations.js";
+export * from "./bootstrap.js";
+export * from "./reload.js";
+export * from "./tool-approvals.js";
+export * from "./approvals/index.js";
+export * from "./messages.js";
+//# sourceMappingURL=index.js.map