@jini-ai/mcp 0.3.4 → 0.4.1

package/dist/federation/registrations.d.ts

@@ -0,0 +1,171 @@
+import type { FederationMessages } from "./messages.js";
+import { type ToolExecutionContext, type ToolExecutionOptions, type ToolRegistration } from "@jini-ai/core";
+import { McpAuthFailedError } from "./mcp-protocol.js";
+import type { FederatedCallConfirmationOutcome, FederatedCallConfirmationRequest, FederatedCallTarget, FederatedMcpConnectionConfig, McpSessionPort } from "./ports.js";
+import { admitRemoteTools, type FederatedAdmissionReport } from "./trust.js";
+/**
+ * @file Turns one connected external MCP server into `ToolRegistration`s — the federated
+ * counterpart of a domain's `tool-registrations.ts`, and deliberately NOT one of them.
+ *
+ * The structural point of this file is what it does not do. It does not call
+ * `buildDomainRegistrations`, it does not appear in `assistant/tool-registrations.ts`'s
+ * `DOMAIN_SLICES`, and it contributes nothing to `DERIVED_RISK_BY_TOOL_ID`. Those three mechanisms
+ * are the native tier's guarantees — a reviewed static catalog, an independently-derived risk
+ * classification, a build that fails on any entry that is neither wired nor explicitly excused —
+ * and a runtime-discovered third-party tool can satisfy none of them. Routing federated tools
+ * through them would not extend those guarantees to federated tools; it would only stop them
+ * meaning anything for the native ones. So federation gets its own construction path, with its own
+ * gates (`trust.ts`), and the two surfaces stay separable by id, by permission, and by audit source.
+ *
+ * They do converge in exactly one place, and it is unavoidable: the single `ToolRegistry` the
+ * daemon's `ToolExecutor` executes against (`agent-daemon-server.ts`). A tool the executor cannot
+ * see cannot be called. Convergence there is mechanical, and everything that makes the tiers
+ * distinct — namespacing, the operator allowlist, the one-way hint rule, the untrusted-data
+ * envelope, the coarse `admin.integrations.manage` gate — is applied on this side of it, before
+ * anything is handed over. The audit trail stays separable for free: `tool-executor-audit.ts` wraps
+ * the executor, so federated attempts are recorded like any other, distinguishable by their
+ * `mcp__` id prefix.
+ *
+ * Authorization shape, in this file's own terms (the question every domain file answers): the
+ * remote has no `authorize` call of its own and never will, so the handler here performs the
+ * check itself via the host's `permissionGate` — the same shape as
+ * `features/database/tool-registrations.ts`'s read handlers, which gate inline because their domain
+ * functions carry no gate to inherit. It is one evaluator, not two.
+ * See docs/decisions/DR-003-trusted-federation-composition.md.
+ */
+/** What `federate` needs from a composition root. A narrow slice of `RouteDeps`, deliberately —
+ * federation touches no repo, no clock, no id generator, and asking for the whole bag would imply
+ * otherwise. */
+/** The host's one permission evaluator. Throws to deny; checked before a remote sees arguments.
+ * @complexity Determined by the injected evaluator.
+ */
+export type FederatedToolPermissionGate = (request: {
+    readonly context: ToolExecutionContext;
+    readonly permission: string;
+    readonly entityType: string;
+    readonly entityId: string;
+}, optional?: {
+    scope?: string;
+}) => void | Promise<void>;
+export interface FederationDeps {
+    readonly permissionGate: FederatedToolPermissionGate;
+    readonly messages: FederationMessages;
+    readonly errorCode: string;
+    readonly scope?: string;
+    /**
+     * A LIVENESS gate, checked before every federated call. Optional; when absent, behaviour is
+     * exactly what it was before this existed.
+     *
+     * ## Why a gate rather than unregistering the tools
+     *
+     * Nothing in this subtree unregisters anything, and that is structural rather than an omission:
+     * `buildToolCatalogQuery` snapshots `registry.list({})` into a ONE-SHOT FTS index at boot, so a tool
+     * removed from the registry afterwards would still be discoverable by `search_tools` and
+     * `describe_tool` while no longer being executable — strictly worse than leaving it registered.
+     * `trust.ts` R5's "frozen at connect" guarantee rests on the same snapshot.
+     *
+     * So a connection that dies mid-run cannot be taken out of the catalog. What it CAN do is refuse
+     * at the call, with an error the model can act on. Without that, the failure surfaces as
+     * `mcp-federation: session is closed (<reason>)` — which reads like a transient fault, so the
+     * model searches, selects the same tool, fails, and searches again, burning the rest of the run on
+     * a server that cannot work until a human re-authorizes it.
+     *
+     * The gate is checked BEFORE the permission check for one reason: "this server is disconnected"
+     * is true regardless of who is asking, and reporting a permission failure to a principal who does
+     * have the permission would send them looking in the wrong place.
+     *
+     * This is ALSO where operator REVOCATION is enforced, not just liveness: a connection deleted,
+     * disabled, narrowed (allowlist or write list), or otherwise changed since admission has no way to
+     * be un-registered (see this doc's own paragraph above), so every one of those must be caught here
+     * instead, on every call, by re-reading the connection's current row.
+     * `assistant/external-mcp-oauth.ts`'s `createExternalMcpConnectionGate` is the composition root
+     * that does both jobs — the original liveness check plus this revocation re-check
+     * (`assistant/external-mcp-revocation.ts`'s `rosterRefusalFor`) — and it is NOT a `ToolPolicy` deny:
+     * see that gate's own doc for why a handler-side refusal, not a policy one, is what lets the model
+     * see WHY rather than a fixed "denied by policy" string.
+     *
+     * @param call - The tool's identity as admitted (remote name, declared annotations) plus the
+     *   connection's origin, so the gate can tell a preset (no row to compare against) from a roster
+     *   connection (re-checked against its current row every call).
+     * @throws Whatever the composition root's terminal error is — for OAuth connections,
+     * `assistant/external-mcp-oauth.ts`'s `ExternalMcpReauthRequiredError`, whose message tells the
+     * model in words not to retry. For a revoked roster connection,
+     * `assistant/external-mcp-revocation.ts`'s `ExternalMcpConnectionRevokedError`.
+     */
+    readonly assertConnectionUsable?: ((required: {
+        connectionId: string;
+        call: FederatedCallTarget;
+    }) => void | Promise<void>) | undefined;
+    /**
+     * Called when a live call throws {@link McpAuthFailedError} — the remote itself rejected our
+     * authentication (HTTP 401), discovered mid-session rather than at boot. HTTP 403 is a call-level
+     * authorization refusal and does not invalidate credentials. Optional; when absent,
+     * the `McpAuthFailedError` propagates unchanged, which is a `McpProtocolError` and reads to a
+     * model like any other transient transport fault (see `assertConnectionUsable` above for why that
+     * shape invites a retry loop).
+     *
+     * A composition root that KNOWS what "authorization" means for this connection (an OAuth-backed
+     * row, today — `assistant/external-mcp-oauth.ts`) wires this to record the durable state — so
+     * `assertConnectionUsable`'s cheap row read catches the NEXT call instead of this module reaching
+     * the network again — and to throw the same terminal, non-retryable error that path already uses.
+     * Always throws; this module does not decide what replaces the original error.
+     */
+    readonly onAuthFailed?: ((required: {
+        connectionId: string;
+        error: McpAuthFailedError;
+    }) => Promise<never>) | undefined;
+    /**
+     * G3 (`trust.ts` R3): asks a human to Confirm or Cancel ONE call to a tool that is not marked
+     * read-only, before anything reaches the remote. Wired by the composition root to the held-open
+     * MCP-UI card (`assistant/external-mcp-call-confirmation.ts`).
+     *
+     * Optional only so a root with no human in the loop still type-checks: when it is absent, every
+     * tool whose confirmation is not `"none"` is refused at the call and nothing is sent — fail closed,
+     * never "run it anyway".
+     */
+    readonly confirmCall?: ((required: {
+        context: ToolExecutionContext & ToolExecutionOptions;
+        request: FederatedCallConfirmationRequest;
+    }) => Promise<FederatedCallConfirmationOutcome>) | undefined;
+}
+export interface FederatedRegistrationResult {
+    readonly registrations: ToolRegistration[];
+    /** The full accounting of what was admitted and refused, for the caller to log. */
+    readonly report: FederatedAdmissionReport;
+}
+/**
+ * Builds the `ToolRegistration`s for one federated connection from its already-listed tool surface.
+ *
+ * Split from the connect/list I/O on purpose: this function is pure given a session, so every trust
+ * rule and every handler behaviour is testable without a transport.
+ *
+ * @param params.tools - The remote's advertised surface, verbatim and untrusted.
+ * @param params.session - The live session, used only to forward `tools/call`.
+ * @param params.config - The site owner's connection config — the trusted side of admission.
+ * @param params.nativeToolIds - Every id already registered natively, for the R1 collision assertion.
+ * @throws {Error} If a federated id would collide with a native one, or the connection id is invalid.
+ * @complexity O(t) in the advertised tool count.
+ */
+export declare function buildFederatedMcpRegistrations(params: {
+    tools: Parameters<typeof admitRemoteTools>[0]["tools"];
+    session: McpSessionPort;
+    config: FederatedMcpConnectionConfig;
+    deps: FederationDeps;
+    nativeToolIds: ReadonlySet<string>;
+}): FederatedRegistrationResult;
+/**
+ * Connects nothing and lists nothing itself — takes a session, drains its tool list, and returns
+ * registrations. The one place `listTools` is called, so `trust.ts` R5's "frozen at connect" is a
+ * property of the code rather than a convention: there is no other path that could re-list.
+ *
+ * @throws {Error} If `listTools` rejects — a connection that cannot enumerate is not usable, and
+ * `bootstrap.ts` is where that is turned into "carry on without federation".
+ * @complexity O(t) in the advertised tool count.
+ */
+export declare function federateSession(params: {
+    session: McpSessionPort;
+    config: FederatedMcpConnectionConfig;
+    deps: FederationDeps;
+    nativeToolIds: ReadonlySet<string>;
+}): Promise<FederatedRegistrationResult>;
+//# sourceMappingURL=registrations.d.ts.map

package/dist/federation/registrations.js

@@ -0,0 +1,181 @@
+import { ToolInputError } from "@jini-ai/core";
+import { McpAuthFailedError } from "./mcp-protocol.js";
+import { admitRemoteTools, isOperatorDeclaredReadOnly, assertNoNativeCollision, extractFederatedImageBlocks, FEDERATED_ENTITY_TYPE, FEDERATED_TOOL_PERMISSION, wrapUntrustedResult, writeShapedInputNames, federatedCallConfirmationForAction, } from "./trust.js";
+/**
+ * Builds the `ToolRegistration`s for one federated connection from its already-listed tool surface.
+ *
+ * Split from the connect/list I/O on purpose: this function is pure given a session, so every trust
+ * rule and every handler behaviour is testable without a transport.
+ *
+ * @param params.tools - The remote's advertised surface, verbatim and untrusted.
+ * @param params.session - The live session, used only to forward `tools/call`.
+ * @param params.config - The site owner's connection config — the trusted side of admission.
+ * @param params.nativeToolIds - Every id already registered natively, for the R1 collision assertion.
+ * @throws {Error} If a federated id would collide with a native one, or the connection id is invalid.
+ * @complexity O(t) in the advertised tool count.
+ */
+export function buildFederatedMcpRegistrations(params) {
+    const { session, config, deps } = params;
+    const report = admitRemoteTools({ tools: params.tools, config });
+    assertNoNativeCollision({ federatedToolIds: report.admitted.map((tool) => tool.toolId), nativeToolIds: params.nativeToolIds, messages: deps.messages });
+    const registrations = report.admitted.map((tool) => {
+        const handler = async (ctx, options = {}) => {
+            // Liveness AND revocation first — see `FederationDeps.assertConnectionUsable` for why this
+            // precedes the permission check rather than following it.
+            await deps.assertConnectionUsable?.({ connectionId: config.connectionId, call: {
+                    remoteName: tool.remoteName,
+                    declaredAnnotations: tool.declaredAnnotations,
+                    origin: config.origin,
+                } });
+            // ONE evaluator, run before anything crosses the network — not after, so a denied principal's
+            // arguments are never even sent to a third party. `entityId` is the connection, so a
+            // deployment can grant per-connection rather than all-or-nothing.
+            await deps.permissionGate({
+                context: ctx,
+                permission: FEDERATED_TOOL_PERMISSION,
+                entityType: FEDERATED_ENTITY_TYPE,
+                entityId: config.connectionId,
+            }, deps.scope === undefined ? {} : { scope: deps.scope });
+            // Fixed ONCE, before any card is drawn: the frozen copy the human sees is the same object that
+            // is sent, so nothing that happens to `ctx.input` while the card waits can change what runs.
+            const args = frozenArguments(ctx.input);
+            const declined = await askBeforeCall({ ...ctx, ...options }, deps, config, tool, args);
+            if (declined)
+                return declined;
+            let result;
+            try {
+                result = await session.callTool({ name: tool.remoteName, arguments: args }, { signal: ctx.signal });
+            }
+            catch (error) {
+                // A token valid at boot can die mid-session; nothing here re-probes it proactively (no
+                // periodic refresh exists), so this is where that discovery actually happens. Handed to
+                // `onAuthFailed` so the SAME durable state and terminal, non-retryable error this file's
+                // `assertConnectionUsable` doc already promises apply here too — not just to a connection
+                // already known dead at the call's start.
+                if (error instanceof McpAuthFailedError && deps.onAuthFailed)
+                    await deps.onAuthFailed({ connectionId: config.connectionId, error: error });
+                throw error;
+            }
+            // R7's media carve-out (trust.ts): image blocks are pulled out of `result.content` BEFORE the
+            // untrusted-data envelope is built, so they reach the model through the daemon's typed
+            // `media` channel (`extractResultMedia`) intact — see `extractFederatedImageBlocks`'s own doc
+            // for why stringifying them into the byte-capped text boundary instead would corrupt them.
+            const { images, remainder } = extractFederatedImageBlocks({
+                content: result.content,
+                maxResultBytes: config.maxResultBytes,
+            });
+            // R7. Every federated result reaches the model inside an untrusted-data boundary, including
+            // the remote's own `isError` claim — which is reported as data rather than acted on, because
+            // a remote lying about its own success is not a case this side can adjudicate.
+            return {
+                federated: { connectionId: config.connectionId, tool: tool.remoteName, remoteReportedError: result.isError === true },
+                untrusted: wrapUntrustedResult({
+                    connectionLabel: config.label,
+                    remoteName: tool.remoteName,
+                    result: { content: remainder, structuredContent: result.structuredContent },
+                    maxResultBytes: config.maxResultBytes,
+                }),
+                // The ONLY field `@jini-ai/daemon`'s `extractResultMedia` reads to hoist inline media onto
+                // the `tool_result` wire event — see `demo-image-tool.ts` for the identical shape proven
+                // end to end through the chat pane. Omitted (not an empty array) when there is nothing to
+                // hoist, so a text-only result's return shape is byte-identical to before this existed.
+                ...(images.length > 0 ? { content: images } : {}),
+            };
+        };
+        return {
+            descriptor: {
+                id: tool.toolId,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                ...(isOperatorDeclaredReadOnly({ remoteName: tool.remoteName, annotations: tool.declaredAnnotations, readList: config.readOnlyRemoteNames }) ? { readOnly: true } : {}),
+            },
+            // Pass-through, matching `buildDomainRegistrations`'s identical choice and for the identical
+            // §2 reason: the handler above IS this tool's one gate, and a `ToolPolicy` check would. See docs/decisions/DR-003-trusted-federation-composition.md.
+            // be a second evaluator of the same rule.
+            policy: { authorize: () => "allow" },
+            handler,
+        };
+    });
+    return { registrations, report };
+}
+/**
+ * Connects nothing and lists nothing itself — takes a session, drains its tool list, and returns
+ * registrations. The one place `listTools` is called, so `trust.ts` R5's "frozen at connect" is a
+ * property of the code rather than a convention: there is no other path that could re-list.
+ *
+ * @throws {Error} If `listTools` rejects — a connection that cannot enumerate is not usable, and
+ * `bootstrap.ts` is where that is turned into "carry on without federation".
+ * @complexity O(t) in the advertised tool count.
+ */
+export async function federateSession(params) {
+    const tools = await params.session.listTools();
+    return buildFederatedMcpRegistrations({ ...params, tools });
+}
+/**
+ * G3: the per-call human gate for protected actions (`trust.ts` R3): permanent deletion, delivery
+ * to people, and changes to assistant privacy/instructions/access. Write-shaped input names
+ * (`WRITE_SHAPED_INPUT_WORDS`) describe required cards without independently requiring one. Returns
+ * `null` when the call may proceed — an ordinary action, or an explicit Confirm — and otherwise the
+ * model-facing result that replaces the call. One card per call: the card is opened here, inside the
+ * call it guards, and closes when answered, so one Confirm authorizes exactly one call.
+ *
+ * @throws {ToolInputError} `${errorCode}_NO_CONFIRMATION_CHANNEL` when the root wired no confirmer —
+ *   nothing is sent.
+ * @complexity O(1) plus the wait for the human.
+ */
+async function askBeforeCall(ctx, deps, config, tool, args) {
+    const confirmation = federatedCallConfirmationForAction({ remoteName: tool.remoteName, annotations: tool.declaredAnnotations, args: args });
+    if (confirmation === "none")
+        return null;
+    const writeShapedInputs = [...new Set([...tool.writeShapedInputs, ...writeShapedInputNames({ args: args })])].sort();
+    if (!deps.confirmCall) {
+        throw new ToolInputError({ message: `${deps.errorCode}_NO_CONFIRMATION_CHANNEL: ${tool.toolId}: this protected action requires confirmation, ` +
+                "and nothing here can ask a person. Nothing was sent." });
+    }
+    const outcome = await deps.confirmCall({ context: ctx, request: {
+            toolId: tool.toolId,
+            remoteName: tool.remoteName,
+            connectionId: config.connectionId,
+            connectionLabel: config.label,
+            arguments: args,
+            destructive: confirmation === "confirm-destructive",
+            declaredAnnotations: tool.declaredAnnotations,
+            origin: config.origin,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            writeShapedInputs,
+        } });
+    if (outcome.confirmed)
+        return null;
+    return { federated: { connectionId: config.connectionId, tool: tool.remoteName }, ran: false, ...outcome.result };
+}
+/** {@link normalizeArguments}, then a deep, frozen copy — the one object both shown and sent (G3). */
+function frozenArguments(input) {
+    return deepFreeze(structuredClone(normalizeArguments(input)));
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * Narrows `ToolExecutionContext.input` to the `arguments` object a `tools/call` carries.
+ *
+ * Undefined and `{}` both become `{}` — MCP servers routinely publish parameterless tools, and the
+ * kit's own `requireNoInput` establishes that "omit it or pass `{}`" is this codebase's convention
+ * for one. Anything else is refused rather than coerced: forwarding an array or a string as
+ * `arguments` would produce a remote-side error the model cannot act on, and silently dropping it
+ * would teach the model its argument was accepted.
+ */
+function normalizeArguments(input) {
+    if (input === undefined || input === null)
+        return {};
+    if (typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("input must be an object — federated MCP tools take a JSON object of arguments, or omit input entirely");
+    }
+    return input;
+}
+//# sourceMappingURL=registrations.js.map

package/dist/federation/reload.d.ts

@@ -0,0 +1,112 @@
+import type { Logger } from "@jini-ai/core/primitives";
+import { attachFederatedMcpTools, type AttachFederatedMcpToolsParams, type AttachFederatedToolsResult } from "./bootstrap.js";
+import type { ResolvedFederatedConnection } from "./config.js";
+import type { FederationDeps } from "./registrations.js";
+/**
+ * @file Hot re-admission of federated MCP connections — the piece that lets an owner who finishes an
+ * external MCP sign-in (or an operator who saves a ready, non-OAuth connection) see its tools without
+ * restarting the daemon. Before this file existed, `agent-daemon-server.ts`'s `start()` called
+ * `attachFederatedMcpTools` exactly once, at boot; a connection that did not exist (or was not yet
+ * authorized) at that moment contributed no tools until the whole process restarted — see that file's
+ * `registerFederationReloadRoute` call site for how an operator-authorized event now reaches here.
+ *
+ * ## What this does NOT do, on purpose
+ *
+ * `trust.ts` R5 freezes an ALREADY-ADMITTED connection's tool set at connect, forever, for this
+ * process's lifetime — the rug-pull protection that file's own header explains. This module never
+ * re-lists, re-classifies, or re-admits a connectionId that has already gone through
+ * {@link attachFederatedMcpTools} once, whether that pass ran at boot or at an earlier reload
+ * ({@link selectUnadmittedConnections} is the whole enforcement mechanism: a connectionId already in
+ * `admittedConnectionIds` is filtered out before `attach` is ever called on it again). It only ever
+ * widens the set of connections that have been admitted AT ALL — new rows, never revised ones — which
+ * is the same guarantee a fresh boot already gives, just applied to a connection that did not exist
+ * yet when this process started. `ToolRegistry` (`@jini-ai/core`) is deliberately append-only with no
+ * unregister, so this module still has no way to revise or drop an admitted tool even if it wanted to.
+ *
+ * That admission freeze no longer means an operator's edit is inert until restart, though —
+ * `external-mcp-revocation.ts`'s per-call gate (`mcp-federation/registrations.ts`'s
+ * `FederationDeps.assertConnectionUsable`) re-reads the connection's row on every call, independent of
+ * this reload path. Turning a connection off, deleting it, disconnecting its OAuth, or narrowing its
+ * allowlist or write list all take effect on the very NEXT call, with no restart and no reload
+ * required. Widening the allowlist, or changing the server's address, command, args or sign-in method,
+ * still needs a real restart: the new tools are never registered, and the old ones refuse as
+ * `"changed"` (the row's admission revision no longer matches what the tool was admitted under) until
+ * the process restarts and re-admits the connection fresh.
+ *
+ * ## Concurrency
+ *
+ * {@link createFederationReloadCoordinator} is the single owner of "which connectionIds have been
+ * admitted so far" and serializes every reload attempt through one coalesced, trailing-edge
+ * single-flight queue — see {@link FederationReloadCoordinator.reload}'s own doc for why a NAIVE
+ * single-flight (return the already-in-flight promise to every caller) is wrong here: it can report
+ * success to a caller whose own just-committed connection the in-flight pass never saw. Two operator
+ * actions landing close together (two OAuth callbacks finishing within the same tick, or a callback
+ * racing an admin PUT) can never interleave into a half-updated `ToolRegistry`, and neither can ever
+ * cause the append-only registry's "already registered" throw by attempting the same connectionId
+ * twice concurrently.
+ */
+/**
+ * Every roster connection not yet admitted, in roster order. Pure — no I/O — so it is testable in
+ * isolation from the I/O `createFederationReloadCoordinator` performs.
+ *
+ * @complexity O(n) in the roster size.
+ */
+export declare function selectUnadmittedConnections({ allConnections, admittedConnectionIds }: {
+    allConnections: readonly ResolvedFederatedConnection[];
+    admittedConnectionIds: ReadonlySet<string>;
+}): readonly ResolvedFederatedConnection[];
+export interface FederationReloadResult {
+    /** Ids newly admitted by THIS reload pass — empty when nothing in the roster was unadmitted. */
+    readonly newlyAdmittedConnectionIds: readonly string[];
+    /** This pass's own admission reports only, in `attachFederatedMcpTools`'s own shape — the caller
+     *  (`agent-daemon-server.ts`) merges these into the running, boot-plus-every-reload accounting
+     *  `GET /api/federation/admissions` serves; this module holds no history beyond `admittedConnectionIds`. */
+    readonly reports: AttachFederatedToolsResult["reports"];
+    /** This pass's own connect failures only (2026-09-24) — a connection the reload attempted that
+     *  never reached admission, same shape and same merge-at-the-caller discipline as `reports`. A
+     *  connectionId that fails a reload is NOT added to `admittedConnectionIds`, so the next reload
+     *  attempts it again rather than treating one failed attempt as permanent. */
+    readonly connectFailures: AttachFederatedToolsResult["connectFailures"];
+}
+export interface FederationReloadCoordinatorDeps {
+    readonly registry: AttachFederatedMcpToolsParams["registry"];
+    readonly deps: FederationDeps;
+    readonly connect: AttachFederatedMcpToolsParams["connect"];
+    /** Reads the operator's current roster fresh. Called once per actual reload PASS — never once per
+     *  `reload()` caller; see the coalescing doc on {@link FederationReloadCoordinator.reload}. */
+    readonly resolveConnections: () => Promise<readonly ResolvedFederatedConnection[]>;
+    /** Test seam — defaults to the real {@link attachFederatedMcpTools}. */
+    readonly attach?: typeof attachFederatedMcpTools | undefined;
+    readonly logger?: Logger | undefined;
+}
+export interface FederationReloadCoordinator {
+    /**
+     * Re-admits every roster connection not yet admitted.
+     *
+     * Coalesced trailing-edge single-flight: if a pass is already running, this does NOT hand back
+     * that pass's own result (its `resolveConnections()` snapshot may predate whatever made THIS call
+     * happen — a just-committed OAuth completion or admin save — so reporting it as this caller's
+     * answer could claim success for a connection the running pass never saw), and it does NOT start a
+     * second CONCURRENT pass either (two passes racing could both see the same connectionId as
+     * unadmitted and both call `registry.register()` for it, tripping the append-only registry's
+     * "already registered" throw). Instead it queues exactly one follow-up pass, run after the
+     * in-flight one finishes, shared by every caller that arrives while one is already queued — so N
+     * callers arriving close together cost at most two real passes: the one already running, plus one
+     * guaranteed to read the roster after every one of those callers' own writes committed.
+     */
+    reload(required: Record<string, never>): Promise<FederationReloadResult>;
+    /** Every connectionId admitted so far, boot-time seed included. A live read of the coordinator's
+     *  own bookkeeping, not a snapshot — reflects the most recently SETTLED reload pass. */
+    admittedConnectionIds(): ReadonlySet<string>;
+}
+/**
+ * @param initiallyAdmitted - The connectionIds `start()`'s own boot-time `attachFederatedMcpTools`
+ * call already admitted — seeded in so the first reload never re-attempts them.
+ * @complexity `reload()` is O(c · t) in the unadmitted connection count and their advertised tools
+ * (the underlying `attachFederatedMcpTools` cost); `admittedConnectionIds()` is O(1).
+ */
+export declare function createFederationReloadCoordinator({ coordDeps, initiallyAdmitted }: {
+    coordDeps: FederationReloadCoordinatorDeps;
+    initiallyAdmitted: Iterable<string>;
+}): FederationReloadCoordinator;
+//# sourceMappingURL=reload.d.ts.map

package/dist/federation/reload.js

@@ -0,0 +1,110 @@
+import { attachFederatedMcpTools } from "./bootstrap.js";
+/**
+ * @file Hot re-admission of federated MCP connections — the piece that lets an owner who finishes an
+ * external MCP sign-in (or an operator who saves a ready, non-OAuth connection) see its tools without
+ * restarting the daemon. Before this file existed, `agent-daemon-server.ts`'s `start()` called
+ * `attachFederatedMcpTools` exactly once, at boot; a connection that did not exist (or was not yet
+ * authorized) at that moment contributed no tools until the whole process restarted — see that file's
+ * `registerFederationReloadRoute` call site for how an operator-authorized event now reaches here.
+ *
+ * ## What this does NOT do, on purpose
+ *
+ * `trust.ts` R5 freezes an ALREADY-ADMITTED connection's tool set at connect, forever, for this
+ * process's lifetime — the rug-pull protection that file's own header explains. This module never
+ * re-lists, re-classifies, or re-admits a connectionId that has already gone through
+ * {@link attachFederatedMcpTools} once, whether that pass ran at boot or at an earlier reload
+ * ({@link selectUnadmittedConnections} is the whole enforcement mechanism: a connectionId already in
+ * `admittedConnectionIds` is filtered out before `attach` is ever called on it again). It only ever
+ * widens the set of connections that have been admitted AT ALL — new rows, never revised ones — which
+ * is the same guarantee a fresh boot already gives, just applied to a connection that did not exist
+ * yet when this process started. `ToolRegistry` (`@jini-ai/core`) is deliberately append-only with no
+ * unregister, so this module still has no way to revise or drop an admitted tool even if it wanted to.
+ *
+ * That admission freeze no longer means an operator's edit is inert until restart, though —
+ * `external-mcp-revocation.ts`'s per-call gate (`mcp-federation/registrations.ts`'s
+ * `FederationDeps.assertConnectionUsable`) re-reads the connection's row on every call, independent of
+ * this reload path. Turning a connection off, deleting it, disconnecting its OAuth, or narrowing its
+ * allowlist or write list all take effect on the very NEXT call, with no restart and no reload
+ * required. Widening the allowlist, or changing the server's address, command, args or sign-in method,
+ * still needs a real restart: the new tools are never registered, and the old ones refuse as
+ * `"changed"` (the row's admission revision no longer matches what the tool was admitted under) until
+ * the process restarts and re-admits the connection fresh.
+ *
+ * ## Concurrency
+ *
+ * {@link createFederationReloadCoordinator} is the single owner of "which connectionIds have been
+ * admitted so far" and serializes every reload attempt through one coalesced, trailing-edge
+ * single-flight queue — see {@link FederationReloadCoordinator.reload}'s own doc for why a NAIVE
+ * single-flight (return the already-in-flight promise to every caller) is wrong here: it can report
+ * success to a caller whose own just-committed connection the in-flight pass never saw. Two operator
+ * actions landing close together (two OAuth callbacks finishing within the same tick, or a callback
+ * racing an admin PUT) can never interleave into a half-updated `ToolRegistry`, and neither can ever
+ * cause the append-only registry's "already registered" throw by attempting the same connectionId
+ * twice concurrently.
+ */
+/**
+ * Every roster connection not yet admitted, in roster order. Pure — no I/O — so it is testable in
+ * isolation from the I/O `createFederationReloadCoordinator` performs.
+ *
+ * @complexity O(n) in the roster size.
+ */
+export function selectUnadmittedConnections({ allConnections, admittedConnectionIds }) {
+    return allConnections.filter((connection) => !admittedConnectionIds.has(connection.config.connectionId));
+}
+/**
+ * @param initiallyAdmitted - The connectionIds `start()`'s own boot-time `attachFederatedMcpTools`
+ * call already admitted — seeded in so the first reload never re-attempts them.
+ * @complexity `reload()` is O(c · t) in the unadmitted connection count and their advertised tools
+ * (the underlying `attachFederatedMcpTools` cost); `admittedConnectionIds()` is O(1).
+ */
+export function createFederationReloadCoordinator({ coordDeps, initiallyAdmitted }) {
+    const admitted = new Set(initiallyAdmitted);
+    const attach = coordDeps.attach ?? attachFederatedMcpTools;
+    let inFlight = null;
+    let queuedNext = null;
+    async function runOnePass() {
+        const allConnections = await coordDeps.resolveConnections();
+        const unadmitted = selectUnadmittedConnections({ allConnections: allConnections, admittedConnectionIds: admitted });
+        if (unadmitted.length === 0)
+            return { newlyAdmittedConnectionIds: [], reports: [], connectFailures: [] };
+        // Empty, not omitted: omission resolves presets from the environment again, even though the
+        // boot pass already admitted them. Reload concerns only the operator-editable roster;
+        // environment presets cannot change without a real restart.
+        const attached = await attach({ registry: coordDeps.registry, deps: coordDeps.deps, connect: coordDeps.connect }, { connections: [], extraConnections: unadmitted, ...(coordDeps.logger ? { logger: coordDeps.logger } : {}) });
+        for (const entry of attached.reports)
+            admitted.add(entry.connectionId);
+        return {
+            newlyAdmittedConnectionIds: attached.reports.map((entry) => entry.connectionId),
+            reports: attached.reports,
+            connectFailures: attached.connectFailures,
+        };
+    }
+    function reload(_required) {
+        if (!inFlight) {
+            inFlight = runOnePass().finally(() => {
+                inFlight = null;
+            });
+            return inFlight;
+        }
+        if (!queuedNext) {
+            // Chained off the CURRENTLY running pass, not reassigned into `inFlight` until it actually
+            // starts — a third caller arriving while this follow-up is still only QUEUED (the running pass
+            // hasn't settled yet) shares this same queued promise instead of queuing a third pass.
+            // `.catch(() => undefined)` first so a broken run (`resolveConnections`/`attach` throwing,
+            // possible only via test-injected overrides — the real ones this repo wires are documented
+            // "never rejects") cannot wedge every future caller behind a permanently-rejected chain link.
+            const runningPass = inFlight;
+            queuedNext = runningPass.catch(() => undefined).then(() => {
+                const nextPass = runOnePass().finally(() => {
+                    inFlight = null;
+                });
+                inFlight = nextPass;
+                queuedNext = null;
+                return nextPass;
+            });
+        }
+        return queuedNext;
+    }
+    return { reload, admittedConnectionIds: () => admitted };
+}
+//# sourceMappingURL=reload.js.map