@jini-ai/mcp 0.3.4 → 0.4.1

package/dist/federation/mcp-protocol.d.ts

@@ -0,0 +1,115 @@
+import type { RemoteToolDescriptor, RemoteToolResult, McpClientInfo } from "./ports.js";
+/**
+ * @file The transport-INDEPENDENT half of host app's minimal MCP client: the JSON-RPC envelope shapes,
+ * the handshake constants, and the narrowing of everything a remote server sends back.
+ *
+ * Why this file exists:
+ * `adapter.stdio.ts` and `adapter.http.ts` differ only in how bytes move. Every decision about what
+ * a `tools/list` page means, which cursor to follow, how many pages to follow, what a `tools/call`
+ * result is allowed to look like, and which fields survive narrowing is identical across both —
+ * because it is the PROTOCOL, not the pipe. Duplicating it into the second adapter would have
+ * created two copies of this codebase's untrusted-input narrowing that could silently disagree,
+ * which is the failure mode the narrowing exists to prevent.
+ *
+ * Everything here treats its input as HOSTILE. A remote server controls every byte parsed by this
+ * file: tool names, descriptions, schemas, annotations, cursors, results. This file's job is to
+ * turn that into well-typed values or drop it — never to trust it, and never to throw on it where
+ * dropping would do. The trust decisions themselves belong to `trust.ts`; see `ports.ts`'s header
+ * for the split.
+ *
+ * Architectural role:
+ * Pure functions and constants. No I/O, no state, no transport knowledge.
+ */
+/** The MCP revision this client negotiates. A server replying with a different one is accepted —
+ * MCP's own rule is that the server names the version it will actually speak — but the value is
+ * carried on the session so a mismatch is visible in logs rather than silent. */
+export declare const CLIENT_PROTOCOL_VERSION = "2025-06-18";
+/** Bound on `tools/list` cursor-following. A server that returns a fresh `nextCursor` forever would
+ * otherwise pin the daemon's boot at 100% CPU; `trust.ts`'s `maxTools` caps what is admitted, but
+ * that check runs after this loop, so the loop needs its own bound. */
+export declare const MAX_LIST_TOOLS_PAGES = 20;
+/** One JSON-RPC 2.0 frame as received. Every field optional because a remote may omit any of them,
+ *  and a missing field must be a narrowing failure rather than a crash. */
+export interface JsonRpcResponse {
+    jsonrpc?: string | undefined;
+    id?: unknown | undefined;
+    result?: unknown | undefined;
+    error?: {
+        code?: number | undefined;
+        message?: string | undefined;
+        data?: unknown | undefined;
+    } | undefined;
+    method?: string | undefined;
+    params?: unknown | undefined;
+}
+/** Every failure raised by an MCP client adapter, whatever the transport. Distinct from a plain
+ *  `Error` so `bootstrap.ts`'s fail-open handler can tell "the protocol went wrong" from "the code
+ *  went wrong" when it logs. */
+export declare class McpProtocolError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, options?: ErrorOptions);
+}
+/**
+ * A `McpProtocolError` specifically caused by the remote's token having expired or been revoked
+ * (HTTP 401 today — see `adapter.http.ts`'s `assertOkStatus`; a 403 is a scope/permission refusal,
+ * not this). Kept as a distinguishable
+ * subtype, rather than a generic `McpProtocolError` a caller would have to pattern-match on message
+ * text, so a layer that DOES know what "authorization" means for one connection (an OAuth-backed
+ * row, at `assistant/external-mcp-oauth.ts`) can react to it — without this module, which is
+ * transport-independent protocol plumbing, knowing anything about OAuth.
+ */
+export declare class McpAuthFailedError extends McpProtocolError {
+}
+/** The server's half of a completed handshake. Untrusted, like everything else it sends — recorded
+ *  for diagnostics and audit, never acted on. */
+export interface McpServerIdentity {
+    readonly protocolVersion: string;
+    readonly info: {
+        name?: string | undefined;
+        version?: string | undefined;
+    };
+}
+export declare function asRecord({ value }: {
+    value: unknown;
+}): Record<string, unknown> | null;
+/** Builds the `initialize` params. One function so both transports negotiate identically — a
+ *  capability advertised on one and not the other would mean a remote could ask one of host app's two
+ *  clients for something the other refuses. */
+export declare function buildInitializeParams({ clientInfo }: {
+    clientInfo: McpClientInfo;
+}): Record<string, unknown>;
+/** Narrows an `initialize` result into the server's self-reported identity. */
+export declare function parseInitializeResult({ result }: {
+    result: unknown;
+}): McpServerIdentity;
+/** Narrows a `tools/call` result. A non-object result is carried through as `content` rather than
+ *  discarded: a server returning a bare string is out of spec but harmless, and the untrusted
+ *  envelope (`trust.ts` R7) is where it lands either way. */
+export declare function parseCallToolResult({ result }: {
+    result: unknown;
+}): RemoteToolResult;
+/** Narrows one `tools/list` response page into its usable descriptors plus the cursor for the next
+ *  page (`undefined` when there is none). A malformed entry is dropped rather than thrown on — one
+ *  bad descriptor must not cost the operator every other tool on the same server; `trust.ts`
+ *  refuses anything that survives this and still fails its own checks. */
+export declare function parseToolsListPage({ result }: {
+    result: unknown;
+}): {
+    readonly tools: RemoteToolDescriptor[];
+    readonly nextCursor: string | undefined;
+};
+/**
+ * Drains a paginated `tools/list` for one session, whatever the transport.
+ *
+ * @param requestPage - Issues one `tools/list` request and returns its raw result.
+ * @throws {McpProtocolError} When the remote keeps producing cursors past
+ * {@link MAX_LIST_TOOLS_PAGES}.
+ * @complexity O(p) in pages, bounded by {@link MAX_LIST_TOOLS_PAGES}.
+ */
+export declare function drainToolsList({ requestPage }: {
+    requestPage: (required: {
+        params: Record<string, unknown>;
+    }) => Promise<unknown>;
+}): Promise<RemoteToolDescriptor[]>;
+//# sourceMappingURL=mcp-protocol.d.ts.map

package/dist/federation/mcp-protocol.js

@@ -0,0 +1,151 @@
+/**
+ * @file The transport-INDEPENDENT half of host app's minimal MCP client: the JSON-RPC envelope shapes,
+ * the handshake constants, and the narrowing of everything a remote server sends back.
+ *
+ * Why this file exists:
+ * `adapter.stdio.ts` and `adapter.http.ts` differ only in how bytes move. Every decision about what
+ * a `tools/list` page means, which cursor to follow, how many pages to follow, what a `tools/call`
+ * result is allowed to look like, and which fields survive narrowing is identical across both —
+ * because it is the PROTOCOL, not the pipe. Duplicating it into the second adapter would have
+ * created two copies of this codebase's untrusted-input narrowing that could silently disagree,
+ * which is the failure mode the narrowing exists to prevent.
+ *
+ * Everything here treats its input as HOSTILE. A remote server controls every byte parsed by this
+ * file: tool names, descriptions, schemas, annotations, cursors, results. This file's job is to
+ * turn that into well-typed values or drop it — never to trust it, and never to throw on it where
+ * dropping would do. The trust decisions themselves belong to `trust.ts`; see `ports.ts`'s header
+ * for the split.
+ *
+ * Architectural role:
+ * Pure functions and constants. No I/O, no state, no transport knowledge.
+ */
+/** The MCP revision this client negotiates. A server replying with a different one is accepted —
+ * MCP's own rule is that the server names the version it will actually speak — but the value is
+ * carried on the session so a mismatch is visible in logs rather than silent. */
+export const CLIENT_PROTOCOL_VERSION = "2025-06-18";
+/** Bound on `tools/list` cursor-following. A server that returns a fresh `nextCursor` forever would
+ * otherwise pin the daemon's boot at 100% CPU; `trust.ts`'s `maxTools` caps what is admitted, but
+ * that check runs after this loop, so the loop needs its own bound. */
+export const MAX_LIST_TOOLS_PAGES = 20;
+/** Every failure raised by an MCP client adapter, whatever the transport. Distinct from a plain
+ *  `Error` so `bootstrap.ts`'s fail-open handler can tell "the protocol went wrong" from "the code
+ *  went wrong" when it logs. */
+export class McpProtocolError extends Error {
+    constructor({ message }, options = {}) {
+        super(message, options);
+    }
+}
+/**
+ * A `McpProtocolError` specifically caused by the remote's token having expired or been revoked
+ * (HTTP 401 today — see `adapter.http.ts`'s `assertOkStatus`; a 403 is a scope/permission refusal,
+ * not this). Kept as a distinguishable
+ * subtype, rather than a generic `McpProtocolError` a caller would have to pattern-match on message
+ * text, so a layer that DOES know what "authorization" means for one connection (an OAuth-backed
+ * row, at `assistant/external-mcp-oauth.ts`) can react to it — without this module, which is
+ * transport-independent protocol plumbing, knowing anything about OAuth.
+ */
+export class McpAuthFailedError extends McpProtocolError {
+}
+export function asRecord({ value }) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    return value;
+}
+/** Builds the `initialize` params. One function so both transports negotiate identically — a
+ *  capability advertised on one and not the other would mean a remote could ask one of host app's two
+ *  clients for something the other refuses. */
+export function buildInitializeParams({ clientInfo }) {
+    return { protocolVersion: CLIENT_PROTOCOL_VERSION, capabilities: {}, clientInfo };
+}
+/** Narrows an `initialize` result into the server's self-reported identity. */
+export function parseInitializeResult({ result }) {
+    const record = asRecord({ value: result });
+    const info = asRecord({ value: record?.serverInfo });
+    return {
+        protocolVersion: typeof record?.protocolVersion === "string" ? record.protocolVersion : "",
+        info: {
+            name: typeof info?.name === "string" ? info.name : undefined,
+            version: typeof info?.version === "string" ? info.version : undefined,
+        },
+    };
+}
+/** Narrows a `tools/call` result. A non-object result is carried through as `content` rather than
+ *  discarded: a server returning a bare string is out of spec but harmless, and the untrusted
+ *  envelope (`trust.ts` R7) is where it lands either way. */
+export function parseCallToolResult({ result }) {
+    const record = asRecord({ value: result });
+    if (!record)
+        return { content: result };
+    return {
+        content: record.content,
+        structuredContent: record.structuredContent,
+        // The remote's own claim about its own outcome. Surfaced to the model inside the untrusted
+        // envelope (`trust.ts` R7); never used to decide anything on this side.
+        isError: record.isError === true,
+    };
+}
+/** Narrows one `tools/list` response's `annotations` block. Shape only — the trust decisions all
+ *  live in `trust.ts`. Split out of {@link asRemoteToolDescriptor} purely to keep that function's
+ *  complexity under the shop ceiling. */
+function asRemoteToolAnnotations(record) {
+    if (!record)
+        return undefined;
+    return {
+        title: typeof record.title === "string" ? record.title : undefined,
+        readOnlyHint: typeof record.readOnlyHint === "boolean" ? record.readOnlyHint : undefined,
+        destructiveHint: typeof record.destructiveHint === "boolean" ? record.destructiveHint : undefined,
+        idempotentHint: typeof record.idempotentHint === "boolean" ? record.idempotentHint : undefined,
+        openWorldHint: typeof record.openWorldHint === "boolean" ? record.openWorldHint : undefined,
+    };
+}
+/** Narrows one `tools/list` entry, discarding anything without a usable `name`. Shape only — the
+ * trust decisions all live in `trust.ts`. */
+function asRemoteToolDescriptor(value) {
+    const record = asRecord({ value: value });
+    if (!record || typeof record.name !== "string" || record.name.length === 0)
+        return null;
+    return {
+        name: record.name,
+        description: typeof record.description === "string" ? record.description : undefined,
+        inputSchema: record.inputSchema,
+        annotations: asRemoteToolAnnotations(asRecord({ value: record.annotations })),
+    };
+}
+/** Narrows one `tools/list` response page into its usable descriptors plus the cursor for the next
+ *  page (`undefined` when there is none). A malformed entry is dropped rather than thrown on — one
+ *  bad descriptor must not cost the operator every other tool on the same server; `trust.ts`
+ *  refuses anything that survives this and still fails its own checks. */
+export function parseToolsListPage({ result }) {
+    const record = asRecord({ value: result });
+    const rawTools = record && Array.isArray(record.tools) ? record.tools : [];
+    const tools = [];
+    for (const tool of rawTools) {
+        const descriptor = asRemoteToolDescriptor(tool);
+        if (descriptor)
+            tools.push(descriptor);
+    }
+    const next = record?.nextCursor;
+    return { tools, nextCursor: typeof next === "string" && next.length > 0 ? next : undefined };
+}
+/**
+ * Drains a paginated `tools/list` for one session, whatever the transport.
+ *
+ * @param requestPage - Issues one `tools/list` request and returns its raw result.
+ * @throws {McpProtocolError} When the remote keeps producing cursors past
+ * {@link MAX_LIST_TOOLS_PAGES}.
+ * @complexity O(p) in pages, bounded by {@link MAX_LIST_TOOLS_PAGES}.
+ */
+export async function drainToolsList({ requestPage }) {
+    const collected = [];
+    let cursor;
+    for (let page = 0; page < MAX_LIST_TOOLS_PAGES; page += 1) {
+        const result = await requestPage({ params: cursor === undefined ? {} : { cursor } });
+        const { tools, nextCursor } = parseToolsListPage({ result: result });
+        collected.push(...tools);
+        if (nextCursor === undefined)
+            return collected;
+        cursor = nextCursor;
+    }
+    throw new McpProtocolError({ message: `mcp-federation: the remote server kept returning a tools/list nextCursor past ${MAX_LIST_TOOLS_PAGES} pages — refusing to follow it further` });
+}
+//# sourceMappingURL=mcp-protocol.js.map

package/dist/federation/messages.d.ts

@@ -0,0 +1,54 @@
+import type { ToolRefusalReason } from "./trust.js";
+import type { FederatedCallConfirmationRequest } from "./ports.js";
+/** Host-owned refusal wording; reason codes and sanitized data remain independent of presentation. */
+export interface FederationRefusalMessages {
+    readonly refusalExplanations: Readonly<Record<ToolRefusalReason, string>>;
+    readonly unprintableName: string;
+    readonly absentExplanation: string;
+    readonly inertWriteGrantExplanation: string;
+    readonly prefixHeading: string;
+    readonly prefixInstruction: string;
+    refusalBullet(required: {
+        remoteName: string;
+        connectionId: string;
+        explanation: string;
+    }): string;
+    omittedRefusals(required: {
+        omitted: number;
+        total: number;
+    }): string;
+}
+/** Shared federation presentation. Hosts replace the complete object, including confirmation and launch copy. */
+export interface FederationMessages extends FederationRefusalMessages {
+    authenticationRefused(required: {
+        method: string;
+        status: number;
+    }): string;
+    readonly closedByHost: string;
+    nativeCollision(required: {
+        toolId: string;
+    }): string;
+    /** Hosts can distinguish uvx/docker/general commands by basename (including Windows suffixes
+     * and absolute paths), preserving remediation appropriate to their installed toolchain. */
+    launchUnavailable(required: {
+        command: string;
+        searchedDirs: readonly string[];
+    }): string;
+    confirmationTitle(required: {
+        request: FederatedCallConfirmationRequest;
+    }): string;
+    confirmationWarning(required: {
+        request: FederatedCallConfirmationRequest;
+    }): string;
+    readonly confirmationDescription: string;
+    readonly serviceLabel: string;
+    readonly toolLabel: string;
+    readonly argumentsLabel: string;
+    readonly noArguments: string;
+    readonly confirmLabel: string;
+    readonly allowChatLabel: string;
+    readonly allowAlwaysLabel: string;
+}
+/** Neutral English defaults are explicit host choices, never implicit branding or wire defaults. */
+export declare const defaultFederationMessages: FederationMessages;
+//# sourceMappingURL=messages.d.ts.map

package/dist/federation/messages.js

@@ -0,0 +1,35 @@
+/** Neutral English defaults are explicit host choices, never implicit branding or wire defaults. */
+export const defaultFederationMessages = {
+    refusalExplanations: {
+        "not-in-operator-allowlist": "the administrator has not allowed this tool for this connection. Fix: ask the administrator to allow this tool for this connection.",
+        "remote-declares-not-read-only": "the server says this tool makes changes, but the connection has no write grant for it. Fix: ask the administrator to allow this tool and its changes for this connection.",
+        "remote-declares-destructive": "the server marks this tool as destructive and the admission policy refused it. Fix: ask the administrator to review the connection's destructive-tool policy.",
+        "missing-or-invalid-input-schema": "the server published no usable input schema, so arguments would be guesswork. Fix: ask the administrator to report the missing contract to the server vendor.",
+        "invalid-remote-tool-name": "the server advertised a name that cannot be registered (letters, digits, '.', '-' or '_', at most 64 characters). Fix: ask the administrator to report the invalid name to the server vendor.",
+        "duplicate-remote-tool-name": "the server advertised the same tool name twice; the repeat cannot overwrite the first definition. Fix: ask the administrator to report the duplicate to the server vendor.",
+        "connection-tool-cap-reached": "the connection reached its maximum number of tools. Fix: ask the administrator to limit the connection to the tools that are needed, then restart the assistant.",
+    },
+    unprintableName: "(an invalid tool name sent by this server)",
+    absentExplanation: "the administrator allowed this tool, but the server does not offer that name. Ask the administrator to check the name and the server's enabled features.",
+    inertWriteGrantExplanation: "this tool has a write grant but no tool grant, so the write grant cannot take effect. Fix: ask the administrator to allow this tool for this connection.",
+    prefixHeading: "EXTERNAL TOOL AVAILABILITY — read this before explaining a missing capability.",
+    prefixInstruction: "These tools were withheld when the assistant started. They are absent from `search_tools` and `describe_tool` and cannot be called. Explain the listed reason and fix without inventing another cause. This snapshot stays fixed until the assistant restarts.",
+    refusalBullet: ({ remoteName, connectionId, explanation }) => `- '${remoteName}' on external server '${connectionId}': ${explanation}`,
+    omittedRefusals: ({ omitted, total }) => `- …and ${omitted} more, for ${total} withheld in total. Ask the administrator for the complete admission report.`,
+    authenticationRefused: ({ method, status }) => `mcp-federation: the server refused '${method}' with ${status} — its authorization has expired or been revoked; ask the administrator to reconnect this connection`,
+    closedByHost: "closed by the host",
+    nativeCollision: ({ toolId }) => `mcp-federation: federated tool id '${toolId}' collides with a natively-registered tool — an external server must never be able to shadow the host's own catalog`,
+    launchUnavailable: ({ command }) => `This server's command "${command}" is unavailable. Ask the administrator to install or configure the required executable.`,
+    confirmationTitle: ({ request }) => `Run ${request.remoteName} on ${request.connectionLabel}?`,
+    confirmationWarning: ({ request }) => {
+        const base = request.destructive
+            ? `${request.connectionLabel} marks this tool as destructive: it can delete or overwrite data, and that may not be undoable.`
+            : `This can change things in ${request.connectionLabel}.`;
+        return request.writeShapedInputs.length
+            ? `${base} Its input ${request.writeShapedInputs.join(", ")} looks like it can change data, so the host asks every time.` : base;
+    },
+    confirmationDescription: "The assistant wants to run this with exactly the values below. Nothing runs until you allow it.",
+    serviceLabel: "Service", toolLabel: "Tool", argumentsLabel: "Arguments", noArguments: "(none)",
+    confirmLabel: "Allow", allowChatLabel: "Allow for this chat", allowAlwaysLabel: "Always allow",
+};
+//# sourceMappingURL=messages.js.map

package/dist/federation/ports.d.ts

@@ -0,0 +1,287 @@
+export interface RemoteToolAnnotations {
+    readonly title?: string | undefined;
+    readonly readOnlyHint?: boolean | undefined;
+    readonly destructiveHint?: boolean | undefined;
+    readonly idempotentHint?: boolean | undefined;
+    readonly openWorldHint?: boolean | undefined;
+}
+/** One entry of a remote server's `tools/list` response. Every field is attacker-controlled. */
+export interface RemoteToolDescriptor {
+    readonly name: string;
+    readonly description?: string | undefined;
+    /** JSON Schema, as published by the remote. `trust.ts` refuses any tool whose schema is not a
+     * JSON-Schema object — a schema-less tool is refused for federated tools for the same reason
+     * `buildDomainRegistrations` refuses one for native tools. */
+    readonly inputSchema?: unknown | undefined;
+    readonly annotations?: RemoteToolAnnotations | undefined;
+}
+/** One `tools/call` response. `isError` is the remote's own claim about its own outcome. */
+export interface RemoteToolResult {
+    readonly content?: unknown | undefined;
+    readonly structuredContent?: unknown | undefined;
+    readonly isError?: boolean | undefined;
+}
+/**
+ * An established MCP client session against one remote server.
+ *
+ * Intentionally three methods and no more: this is the entire surface federation needs. MCP's
+ * resources/prompts/sampling/roots are all deliberately out of scope — sampling in particular would
+ * let a remote server drive inference on host app's account, which is a far larger grant than "expose
+ * some tools" and is not something this pass builds a trust story for.
+ */
+export interface McpSessionPort {
+    /** The remote's advertised tool surface, already paginated to completion by the adapter. */
+    listTools(): Promise<RemoteToolDescriptor[]>;
+    callTool(request: McpToolCallRequiredArgs, options?: McpToolCallOptions): Promise<RemoteToolResult>;
+    close(required: Record<string, never>): Promise<void>;
+}
+/**
+ * The byte-level seam under `adapter.stdio.ts`: a bidirectional stream of newline-delimited
+ * JSON-RPC 2.0 messages.
+ *
+ * Deliberately dumb — it knows about lines, not about MCP. All protocol knowledge (handshake
+ * ordering, id correlation, pagination, timeouts) lives in the adapter above it, which is what
+ * makes that knowledge testable without a child process.
+ */
+export interface McpStdioChannel {
+    /** Writes one JSON-RPC message. Implementations append the framing newline themselves. */
+    send({ message }: {
+        message: string;
+    }): void;
+    /** Registers the sink for inbound messages, one complete JSON value per call. */
+    onMessage({ listener }: {
+        listener: (required: {
+            message: string;
+        }) => void;
+    }): void;
+    /** Registers the sink for "this channel is gone" — process exit, stream error, explicit close. */
+    onClose({ listener }: {
+        listener: (required: {
+            reason: string;
+        }) => void;
+    }): void;
+    close(required: Record<string, never>): void;
+}
+/**
+ * One site owner's configured federated connection.
+ *
+ * `allowedToolNames` is the load-bearing field and has NO safe default at this layer: an empty
+ * allowlist yields zero federated tools, which is the correct behaviour for a misconfigured
+ * connection. A DEFAULT is a per-vendor judgement and therefore belongs to a vendor preset, not
+ * here — an Agent Plugin's `mcp.json` `defaultTools` is the current example, authored from the
+ * server's real tool surface, which is what makes it an independent classification rather than a
+ * restatement of the remote's own claims.
+ */
+/**
+ * Where one connection's config came from — stamped once, at admission, and carried unchanged into
+ * every later `tools/call`. `external-mcp-revocation.ts`'s per-call gate is the one consumer: a
+ * preset gets only the legacy OAuth `needs_reauth` check (it has no roster row to compare against);
+ * a roster connection is re-checked against its CURRENT row every call, keyed by
+ * `admissionRevision` — see that file's `rosterRefusalFor`.
+ */
+export type FederatedConnectionOrigin = {
+    readonly kind: "preset";
+} | {
+    readonly kind: "roster";
+    readonly admissionRevision: string;
+};
+export interface FederatedMcpConnectionConfig {
+    /** Operator-chosen, stable, `[a-z0-9-]`. Becomes part of every federated tool id, so renaming it
+     * renames every tool the model sees — pick once. */
+    readonly connectionId: string;
+    /** Human-readable, shown to the model as provenance on every federated tool description. */
+    readonly label: string;
+    /** DEFAULT-DENY allowlist of REMOTE tool names (pre-namespacing). */
+    readonly allowedToolNames: readonly string[];
+    /** Remote names reviewed in a bundled plugin's mcp.json, independent of admission grants.
+     * Remote readOnlyHint:false or destructiveHint:true vetoes each declaration. */
+    readonly readOnlyRemoteNames?: ReadonlySet<string> | undefined;
+    /**
+     * SECOND list of REMOTE tool names (pre-namespacing) the operator has separately declared as
+     * writes. Kept for configuration compatibility and admission reports, independently of
+     * {@link allowedToolNames}. The allowlist alone gates admission; this list does not grant or
+     * refuse calls. Descriptor read-only classification and host permissions remain separate gates.
+     *
+     * Same "no safe default at this layer" rule as {@link allowedToolNames}: every connection that has
+     * never been told to allow a write must resolve to an empty list here, and a vendor preset that
+     * wants a non-empty default authors it itself, on purpose, the same way
+     * an Agent Plugin's `defaultTools.write` is authored rather than inherited from the remote.
+     *
+     * Destructive tools may be admitted from the allowlist, but protected actions still require
+     * per-call confirmation. Ordinary writes and absent annotations do not require a card. See
+     * `trust.ts` R3: hints cannot grant admission, and input names alone are not consent evidence.
+     */
+    readonly writeAllowedToolNames: readonly string[];
+    /** How long the initialize+list handshake may take before federation is abandoned for this boot. */
+    readonly connectTimeoutMs: number;
+    /** Per-`tools/call` ceiling. */
+    readonly callTimeoutMs: number;
+    /** UTF-8 cap on the serialized text payload before wrapping, and separately on the aggregate
+     * serialized image array per result. Wrapper text is outside these two budgets. */
+    readonly maxResultBytes: number;
+    /** Hard cap on how many tools this connection may contribute, whatever the remote advertises. */
+    readonly maxTools: number;
+    /** Stamped by `bootstrap.ts` (presets, via `withPresetOrigin`) or `external-mcp-store.ts`'s
+     *  `toResolvedFederatedConnections` (roster rows) — never by anything else. Optional only so a
+     *  fixture predating this field still type-checks; `external-mcp-revocation.ts`'s gate treats a
+     *  non-preset call with no origin as `unverifiable` rather than assuming either source. */
+    readonly origin?: FederatedConnectionOrigin | undefined;
+}
+/** One federated tool call's identity, as `mcp-federation/registrations.ts`'s handler hands it to
+ *  `FederationDeps.assertConnectionUsable` — everything `external-mcp-revocation.ts`'s per-call gate
+ *  needs to re-check an admitted tool against the connection's CURRENT row, without re-deriving any
+ *  of it from the registry. Keys are required (may be `undefined`) rather than optional, so the
+ *  shape is safe to build under `exactOptionalPropertyTypes`. */
+export interface FederatedCallTarget {
+    /** The remote's own tool name (pre-namespacing) — what the operator's allowlist and write list
+     *  name. */
+    readonly remoteName: string;
+    /** Exactly what was recorded at admission (`AdmittedFederatedTool.declaredAnnotations`) — never
+     *  re-read from the remote on this path. */
+    readonly declaredAnnotations: RemoteToolDescriptor["annotations"] | undefined;
+    readonly origin: FederatedConnectionOrigin | undefined;
+}
+/** How a locally-launched federated connection is started.
+ *
+ * See {@link McpHttpLaunchSpec} for the hosted counterpart, and {@link McpLaunchSpec} for why the
+ * two are a union rather than one shape with optional halves. */
+export interface McpStdioLaunchSpec {
+    readonly command: string;
+    readonly args: readonly string[];
+    /** Child-process-only environment. Secrets belong here and NOWHERE else — never in `args`, which
+     * are world-readable in `/proc/<pid>/cmdline` on Linux and in `ps` output everywhere. */
+    readonly env: Readonly<Record<string, string>>;
+    readonly cwd?: string | undefined;
+}
+/**
+ * How a HOSTED federated connection is reached: one URL, plus the headers that authenticate to it.
+ *
+ * `headers` is where an OAuth access token arrives, as `Authorization: Bearer ...`, and it is the
+ * hosted analogue of {@link McpStdioLaunchSpec.env}'s "secrets belong here and NOWHERE else" rule —
+ * never in `url`, which is logged by proxies, kept in browser history when an operator pastes it,
+ * and stored in plaintext on the connection row.
+ *
+ * Deliberately a plain header bag rather than a token field: this layer should not know that OAuth
+ * exists. It is handed headers and sends them. Which credential produced them, whether it can be
+ * refreshed, and what to do when it expires are all `assistant/external-mcp-oauth.ts`'s questions,
+ * decided before a launch spec is ever built.
+ */
+export interface McpHttpLaunchSpec {
+    /** Absolute `https:` URL of the server's MCP endpoint (`http:` only for loopback — enforced at
+     * save time by `external-mcp-store.ts`, not here). */
+    readonly url: string;
+    /** Sent on every request to the endpoint. Carries the bearer token, when there is one. */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/**
+ * How a federated connection is reached, whichever transport it uses.
+ *
+ * A union rather than one struct with optional `command`/`url`, because the two are genuinely
+ * exclusive: a spec carrying both is not a degraded configuration to be tolerated, it is a bug, and
+ * a union makes that unrepresentable instead of a runtime check somebody has to remember to write.
+ *
+ * Narrow with {@link isHttpLaunchSpec}.
+ */
+export type McpLaunchSpec = McpStdioLaunchSpec | McpHttpLaunchSpec;
+/** Narrows a {@link McpLaunchSpec} to its hosted arm. */
+export declare function isHttpLaunchSpec(input: {
+    spec: McpLaunchSpec;
+}): input is {
+    spec: McpHttpLaunchSpec;
+};
+/**
+ * The byte-level seam under `adapter.http.ts`, and the hosted counterpart to
+ * {@link McpStdioChannel}: one request/response exchange against the server's MCP endpoint.
+ *
+ * Deliberately narrower than `fetch`: a function that takes a body and returns a status, a content
+ * type, a couple of named headers, and text. That is everything the Streamable HTTP transport
+ * needs, and shrinking the seam is what lets the adapter's real protocol behaviour — handshake
+ * ordering, session-id propagation, SSE framing, pagination, error mapping — be tested against a
+ * scripted double instead of a live server, exactly as the stdio adapter's channel seam does.
+ */
+export interface McpHttpExchange {
+    send(request: McpHttpRequestRequiredArgs, options?: McpHttpRequestOptions): Promise<McpHttpResponse>;
+}
+/** One response from an {@link McpHttpExchange}. */
+export interface McpHttpResponse {
+    readonly status: number;
+    /** Lowercased `content-type`, value only — parameters such as `; charset=utf-8` may be present
+     * and the adapter matches on the prefix. */
+    readonly contentType: string;
+    /** The server's `Mcp-Session-Id`, when it issued one. */
+    readonly sessionId?: string | undefined;
+    /** The full body. Bounded by the adapter's own cap before it is parsed. */
+    readonly text: string;
+    readonly wwwAuthenticate?: string | undefined;
+}
+/**
+ * What a per-call confirmation card (G3, `trust.ts` R3) is asked to show, as
+ * `mcp-federation/registrations.ts`'s handler hands it to `FederationDeps.confirmCall`.
+ *
+ * `arguments` is the exact, already-frozen object that will be sent on Confirm — the handler builds it
+ * once, before the card is drawn, and sends that same object afterwards, so the card can never show
+ * one thing while the remote receives another.
+ */
+export interface FederatedCallConfirmationRequest {
+    /** The namespaced registry id (`mcp__<connection>__<name>`) — the card's clicks are routed back to it. */
+    readonly toolId: string;
+    readonly remoteName: string;
+    readonly connectionId: string;
+    /** The operator's label for the connection, e.g. "Supabase" — the "target" the card names. */
+    readonly connectionLabel: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+    /** The remote declared `destructiveHint: true` — the card carries the stronger, danger-styled warning. */
+    readonly destructive: boolean;
+    /**
+     * The hints recorded when the tool was admitted, and where its connection came from — the tool
+     * identity a remembered approval ("Allow for this chat", "Always allow") is pinned to
+     * (`assistant/external-mcp-tool-approvals.ts`), so a changed server, name or hints asks again.
+     */
+    readonly declaredAnnotations: RemoteToolDescriptor["annotations"] | undefined;
+    readonly origin: FederatedConnectionOrigin | undefined;
+    /** The description the model reads (`AdmittedFederatedTool.description`) and the input schema, as
+     *  admitted — also part of that identity, so a drifted description or schema asks again. */
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /**
+     * Input names, in the schema or in this call's arguments, that look like writes (`trust.ts`
+     * `WRITE_SHAPED_INPUT_WORDS`), sorted. These names describe an already-required protected-action
+     * card; names alone do not require one. On such a card, non-empty names disable remembered
+     * approval so the person reviews the actual input for that call.
+     */
+    readonly writeShapedInputs: readonly string[];
+}
+/**
+ * The human's answer. Only an explicit Confirm is `{ confirmed: true }`; anything else carries the
+ * model-facing result that replaces the call (cancelled, expired, or the run ended).
+ */
+export type FederatedCallConfirmationOutcome = {
+    readonly confirmed: true;
+} | {
+    readonly confirmed: false;
+    readonly result: Readonly<Record<string, unknown>>;
+};
+/** Host identity sent during initialization; there is no product default. */
+export interface McpClientInfo {
+    readonly name: string;
+    readonly version: string;
+}
+export type RemoteToolDescriptorAnnotations = RemoteToolDescriptor["annotations"];
+/** Required wire payload and optional per-call cancellation. */
+export interface McpToolCallRequiredArgs {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+export interface McpToolCallOptions {
+    readonly signal?: AbortSignal | undefined;
+}
+export interface McpHttpRequestRequiredArgs {
+    readonly url: string;
+    readonly method: "POST" | "DELETE";
+    readonly headers: Readonly<Record<string, string>>;
+}
+export interface McpHttpRequestOptions {
+    readonly body?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/federation/ports.js

@@ -0,0 +1,5 @@
+/** Narrows a {@link McpLaunchSpec} to its hosted arm. */
+export function isHttpLaunchSpec(input) {
+    return "url" in input.spec;
+}
+//# sourceMappingURL=ports.js.map