open-managed-agents 0.1.0

package/dist/src/control-plane/sessions/pi/mcp/bridge.js

@@ -0,0 +1,527 @@
+// MCP tool bridge (plan 0122 §4.4) — modeled on the tool-permission path:
+// the `sevt_*` id is bound BEFORE the tool executes (via
+// PiToolPermissionBridge.publishMcpToolUse, which also owns confirmations),
+// and every persisted `agent.mcp_tool_use` gets exactly one terminal
+// `agent.mcp_tool_result` — success, in-band error, deny, confirmation
+// timeout, abort, call timeout, or transport failure.
+//
+// The custom-tool bridge contributes only the `defineTool` registration
+// shape and text-block content mapping; its resolve-on-user-round-trip event
+// pattern is NOT the MCP model (review finding, plan §9 cluster A).
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { scrubKnownSecrets } from "../../../logging.js";
+import { isMcpAuthError } from "./client.js";
+import { getMcpAuthSnapshot, } from "./credential.js";
+export const DEFAULT_MCP_OUTPUT_CAP_BYTES = 400 * 1024;
+// Upstream default for MCP toolsets is always_ask (mcp-connector.md Tip) —
+// unlike the builtin toolset's always_allow.
+const DEFAULT_MCP_ACCESS = { enabled: true, permission: "ask" };
+/**
+ * The model-visible Pi name. A convention, not a guarantee — collisions
+ * (with custom tools, or `a`+`b__c` vs `a__b`+`c`) are rejected at session
+ * build (runner collision assert), never silently shadowed.
+ */
+export function mcpPiToolName(serverName, toolName) {
+    return `mcp__${serverName}__${toolName}`;
+}
+/**
+ * Build Pi ToolDefinitions for one connected server's discovered tools,
+ * filtered by the mcp_toolset config. Registration-disabled tools are absent
+ * from Pi's surface entirely.
+ */
+export function createMcpToolDefinitions(opts) {
+    const capBytes = opts.outputCapBytes ?? DEFAULT_MCP_OUTPUT_CAP_BYTES;
+    const out = [];
+    for (const tool of opts.connection.tools) {
+        // Discovery output is server-controlled too (review #170, Opus): the
+        // bearer rides the listTools request, so a hostile server can echo the
+        // credential into tool metadata that reaches the model WITHOUT any
+        // call. Descriptions are free text → scrubbed. A NAME carrying the
+        // credential cannot be scrubbed without breaking call routing — it is
+        // an exfil attempt, not a tool: refuse to register it.
+        if (scrub(tool.name, knownSecrets(opts)) !== tool.name)
+            continue;
+        const access = opts.access?.(opts.workspaceId, opts.sessionId, opts.connection.serverName, tool.name, opts.agentContext) ?? DEFAULT_MCP_ACCESS;
+        if (!access.enabled)
+            continue;
+        const piName = mcpPiToolName(opts.connection.serverName, tool.name);
+        out.push({
+            ...defineTool({
+                name: piName,
+                label: piName,
+                description: scrub(tool.description ?? tool.name, knownSecrets(opts)),
+                // Arbitrary third-party JSON Schema; Pi validates with TypeBox.
+                // Servers re-validate in-band anyway (probe 46), so a permissive
+                // fallback at execute time keeps a hostile schema from wedging the
+                // call — see executeMcpTool.
+                parameters: tool.inputSchema,
+                execute: async (piToolCallId, params, signal) => executeMcpTool({
+                    opts,
+                    bareName: tool.name,
+                    permission: access.permission,
+                    piToolCallId,
+                    params,
+                    signal,
+                    capBytes,
+                }),
+            }),
+            executionMode: "parallel",
+        });
+    }
+    return out;
+}
+async function executeMcpTool(args) {
+    const { opts, bareName, permission, piToolCallId, signal, capBytes } = args;
+    const input = isRecord(args.params) ? args.params : {};
+    // 1+2: emit oma.mcp_tool_use; the sevt_* id binds before execution and the
+    // ask-path registers in the shared pending-confirmation store.
+    const materialized = await opts.permissionBridge.publishMcpToolUse({
+        workspaceId: opts.workspaceId,
+        sessionId: opts.sessionId,
+        mcpServerName: opts.connection.serverName,
+        toolName: bareName,
+        piToolCallId,
+        input,
+        permission,
+        signal,
+        getEmitter: opts.getEmitter,
+    });
+    // Terminal-result rule caveat: if the handle was already evicted (runtime
+    // loss mid-flight), getEmitter() is undefined and the result cannot be
+    // persisted — same recovery contract as builtin tools (the lost-runtime
+    // terminalization path synthesizes agent.mcp_tool_result later).
+    const emitResult = (content, isError) => {
+        opts.getEmitter()?.({
+            type: "oma.mcp_tool_result",
+            mcpToolUseId: materialized.toolUseId,
+            content,
+            isError,
+        });
+    };
+    const failWith = (message, outcome) => {
+        emitResult([{ type: "text", text: message }], true);
+        opts.onToolCall?.(outcome);
+        throw new Error(message);
+    };
+    // 3: permission gate.
+    if (permission === "deny") {
+        failWith(`MCP tool ${bareName} is denied by policy`, "denied");
+    }
+    if (permission === "ask") {
+        if (!materialized.confirmation) {
+            failWith(`MCP tool ${bareName} confirmation was not registered`, "error");
+        }
+        let confirmation;
+        try {
+            confirmation = await materialized.confirmation;
+        }
+        catch (error) {
+            const timedOut = error.omaConfirmationTimeout ===
+                true;
+            failWith(toError(error).message, timedOut ? "timeout" : "error");
+            throw error; // unreachable; failWith throws
+        }
+        if (confirmation.result === "deny") {
+            failWith(confirmation.denyMessage ?? `MCP tool ${bareName} was denied`, "denied");
+        }
+    }
+    // 4: the call. In-band failures resolve with isError (probe 46); a
+    // rejection here is transport-class and also marks the connection failed —
+    // UNLESS the Pi signal aborted (user interrupt): that is not a server
+    // failure and must not tear down the warm handle or hit the retry budget
+    // (review 0122-M1, Opus finding 2).
+    let outcome;
+    try {
+        outcome = await opts.connection.callTool(bareName, input, signal);
+    }
+    catch (error) {
+        let err = toError(error);
+        const rejected = getMcpAuthSnapshot(err);
+        if (rejected?.identity.authType === "mcp_oauth" &&
+            opts.connection.credential !== undefined &&
+            isMcpAuthError(err)) {
+            let refreshed;
+            try {
+                refreshed = await opts.connection.credential.forceRefresh(rejected);
+            }
+            catch {
+                refreshed = { status: "failed", reason: "refresh_adapter_error" };
+            }
+            if (refreshed.status === "ready") {
+                if (signal?.aborted === true) {
+                    err = Object.assign(new Error(`MCP tool ${bareName} aborted`), {
+                        name: "AbortError",
+                    });
+                }
+                else {
+                    try {
+                        outcome = await opts.connection.callTool(bareName, input, signal);
+                    }
+                    catch (retryError) {
+                        err = toError(retryError);
+                    }
+                }
+            }
+        }
+        if (outcome !== undefined) {
+            // Continue through the normal success/in-band-error path below. The
+            // first auth rejection is deliberately invisible to failure accounting.
+        }
+        else {
+            const aborted = signal?.aborted === true || err.name === "AbortError";
+            if (!aborted) {
+                opts.onTransportFailure?.(opts.connection.serverName, err);
+            }
+            const timedOut = err.code === -32001; // McpError RequestTimeout
+            // The SDK embeds server response bodies in rejection messages (probe
+            // 49's captured message contains the fixture's 401 body verbatim), so
+            // this string is server-controlled: scrub before it persists/throws.
+            failWith(scrub(`MCP tool ${bareName} failed: ${err.message}`, knownSecrets(opts)), aborted ? "aborted" : timedOut ? "timeout" : "error");
+            throw err; // unreachable
+        }
+    }
+    // 5: terminal result — scrubbed (server-controlled content) then capped
+    // over ALL normalized blocks (review C). Scrub BEFORE the cap: truncation
+    // could split a token and leave an unmatchable prefix behind.
+    const blocks = capContent(scrubContentBlocks(normalizeMcpContent(outcome.content), knownSecrets(opts)), capBytes);
+    emitResult(blocks, outcome.isError);
+    if (outcome.isError) {
+        opts.onToolCall?.("error");
+        throw new Error(textOf(blocks) || `MCP tool ${bareName} returned an error`);
+    }
+    opts.onToolCall?.("ok");
+    // 6: model-facing return — same text-block contract as custom tools.
+    return {
+        content: blocks.map((block) => block.type === "text" && typeof block.text === "string"
+            ? { type: "text", text: block.text }
+            : { type: "text", text: JSON.stringify(block) }),
+        details: {},
+    };
+}
+/** text blocks pass through; anything else is JSON-stringified text. */
+export function normalizeMcpContent(content) {
+    return content.map((block) => {
+        if (isRecord(block) &&
+            block.type === "text" &&
+            typeof block.text === "string") {
+            return { type: "text", text: block.text };
+        }
+        return { type: "text", text: JSON.stringify(block) };
+    });
+}
+function scrub(text, knownSecrets) {
+    return knownSecrets === undefined || knownSecrets.length === 0
+        ? text
+        : scrubKnownSecrets(text, knownSecrets);
+}
+/** Normalization flattens every block to text, so scrubbing `.text` covers
+ * the whole result surface (incl. stringified non-text blocks). */
+function scrubContentBlocks(blocks, knownSecrets) {
+    if (knownSecrets === undefined || knownSecrets.length === 0)
+        return blocks;
+    return blocks.map((block) => block.type === "text" && typeof block.text === "string"
+        ? { type: "text", text: scrubKnownSecrets(block.text, knownSecrets) }
+        : block);
+}
+/**
+ * Byte cap applied after normalization, over every block (text and
+ * stringified non-text alike), before persistence AND the model-visible
+ * return. Truncation is explicit, never silent.
+ */
+export function capContent(blocks, capBytes) {
+    let total = 0;
+    for (const block of blocks) {
+        total += Buffer.byteLength(block.type === "text" && typeof block.text === "string"
+            ? block.text
+            : JSON.stringify(block), "utf8");
+    }
+    if (total <= capBytes)
+        return blocks;
+    const out = [];
+    let budget = capBytes;
+    for (const block of blocks) {
+        if (budget <= 0)
+            break;
+        const text = block.type === "text" && typeof block.text === "string"
+            ? block.text
+            : JSON.stringify(block);
+        const bytes = Buffer.from(text, "utf8");
+        if (bytes.byteLength <= budget) {
+            out.push({ type: "text", text });
+            budget -= bytes.byteLength;
+            continue;
+        }
+        out.push({ type: "text", text: bytes.subarray(0, budget).toString("utf8") });
+        budget = 0;
+    }
+    out.push({ type: "text", text: `[truncated by oma: ${total} bytes total]` });
+    return out;
+}
+function textOf(blocks) {
+    return blocks
+        .map((block) => block.type === "text" && typeof block.text === "string" ? block.text : "")
+        .join("\n")
+        .trim();
+}
+/**
+ * Store-backed access resolver from the agent's mcp_toolset config
+ * (mirrors createStoreBackedBuiltinToolAccessResolver). `configs[].name`
+ * matching is by bare tool name, case-sensitive; a config entry naming a
+ * tool the server doesn't expose is silently ignored by construction (it
+ * simply never matches a discovered tool).
+ */
+export function createStoreBackedMcpToolAccessResolver(opts) {
+    return (workspaceId, sessionId, mcpServerName, toolName, context) => {
+        const session = opts.sessions.retrieveAny(workspaceId, sessionId);
+        const agentId = session?.agent.id ?? context?.agentId;
+        const agentVersion = session?.agent.version ?? context?.agentVersion;
+        if (!agentId || agentVersion === undefined) {
+            return { enabled: false, permission: "deny" };
+        }
+        const agent = opts.agents.retrieveVersion(workspaceId, agentId, agentVersion);
+        if (!agent)
+            return { enabled: false, permission: "deny" };
+        const toolset = agent.tools.find((tool) => tool.type === "mcp_toolset" && tool.mcp_server_name === mcpServerName);
+        if (!toolset)
+            return { enabled: false, permission: "deny" };
+        const config = toolset.configs?.find((item) => item.name === toolName);
+        return {
+            enabled: config?.enabled ?? toolset.default_config?.enabled ?? true,
+            permission: mcpPolicyToPermission(config?.permission_policy?.type ??
+                toolset.default_config?.permission_policy?.type ??
+                "always_ask"),
+        };
+    };
+}
+function mcpPolicyToPermission(policy) {
+    if (policy === "always_allow")
+        return "allow";
+    if (policy === "always_ask")
+        return "ask";
+    if (policy === "never_allow")
+        return "deny";
+    return "deny";
+}
+export function createStoreBackedMcpServersProvider(opts) {
+    return (workspaceId, sessionId, context) => {
+        const session = opts.sessions.retrieveAny(workspaceId, sessionId);
+        const agentId = session?.agent.id ?? context?.agentId;
+        const agentVersion = session?.agent.version ?? context?.agentVersion;
+        if (!agentId || agentVersion === undefined)
+            return [];
+        const agent = opts.agents.retrieveVersion(workspaceId, agentId, agentVersion);
+        if (!agent)
+            return [];
+        // Only servers referenced by an mcp_toolset are connectable; validation
+        // guarantees the cross-reference for new agents, and pre-0122 rows with
+        // dangling entries degrade to "declared but toolset-less" = skipped.
+        const referenced = new Set(agent.tools
+            .filter((tool) => tool.type === "mcp_toolset")
+            .map((tool) => tool.mcp_server_name));
+        return agent.mcp_servers
+            .filter((server) => referenced.has(server.name))
+            .map((server) => ({ name: server.name, url: server.url }));
+    };
+}
+export function createStoreBackedMcpCredentialResolver(opts) {
+    return async (workspaceId, sessionId, serverUrl, context) => {
+        const session = opts.sessions.retrieveAny(workspaceId, sessionId);
+        const vaultIds = session?.vault_ids ?? context?.vaultIds ?? [];
+        if (vaultIds.length === 0)
+            return undefined;
+        const resolved = opts.vaults.resolveCredential(workspaceId, vaultIds, serverUrl);
+        if (!resolved)
+            return undefined;
+        return createRuntimeCredentialBinding({
+            workspaceId,
+            vaultIds,
+            serverUrl,
+            initial: resolved,
+            vaults: opts.vaults,
+            ...(opts.refresh === undefined ? {} : { refresh: opts.refresh }),
+            now: opts.now ?? (() => new Date()),
+        });
+    };
+}
+function createRuntimeCredentialBinding(args) {
+    let current = args.initial;
+    let closed = false;
+    const retained = new Set();
+    const snapshot = () => {
+        if (closed)
+            throw new Error("MCP credential is no longer active");
+        const authorization = `Bearer ${current.token}`;
+        retained.add(authorization);
+        retained.add(current.token);
+        return { authorization, identity: identityOf(args.workspaceId, current) };
+    };
+    const resolveCurrent = () => {
+        const resolved = args.vaults.resolveCredential(args.workspaceId, args.vaultIds, args.serverUrl);
+        if (resolved !== undefined &&
+            (resolved.vaultId !== current.vaultId ||
+                resolved.credentialId !== current.credentialId)) {
+            return undefined;
+        }
+        if (resolved !== undefined)
+            current = resolved;
+        return resolved;
+    };
+    const refreshAndResolve = async (force, expectedAuthVersion) => {
+        if (args.refresh === undefined || current.authType !== "mcp_oauth")
+            return undefined;
+        try {
+            const result = await args.refresh.refreshCredential({
+                workspaceId: args.workspaceId,
+                vaultId: current.vaultId,
+                credentialId: current.credentialId,
+                ...(force ? { force: true } : {}),
+                ...(expectedAuthVersion === undefined ? {} : { expectedAuthVersion }),
+            });
+            return result;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        get fingerprint() {
+            return `${current.credentialId}:${current.authVersion}`;
+        },
+        get identity() {
+            return identityOf(args.workspaceId, current);
+        },
+        async authorize() {
+            if (closed)
+                throw new Error("MCP credential is no longer active");
+            let latest = args.vaults.readCredentialRuntimeMetadata(args.workspaceId, current.vaultId, current.credentialId);
+            if (latest === undefined) {
+                closed = true;
+                throw new Error("MCP credential is no longer active");
+            }
+            if (latest.authVersion !== current.authVersion) {
+                if (resolveCurrent() === undefined) {
+                    closed = true;
+                    throw new Error("MCP credential is no longer active");
+                }
+                latest = args.vaults.readCredentialRuntimeMetadata(args.workspaceId, current.vaultId, current.credentialId);
+                if (latest === undefined) {
+                    closed = true;
+                    throw new Error("MCP credential is no longer active");
+                }
+            }
+            const refreshMode = admittedRefreshMode(latest, args.now());
+            if (refreshMode !== undefined && args.refresh !== undefined) {
+                const refreshResult = await refreshAndResolve(refreshMode === "forced", refreshMode === "forced" ? latest.authVersion : undefined);
+                if (refreshResult?.outcome === "skipped" &&
+                    refreshResult.reason === "forced_refresh_floor") {
+                    return snapshot();
+                }
+                if (refreshResult === undefined)
+                    return snapshot();
+                if (resolveCurrent() === undefined) {
+                    closed = true;
+                    throw new Error("MCP credential is no longer active");
+                }
+            }
+            return snapshot();
+        },
+        async forceRefresh(rejected) {
+            if (closed || current.authType !== "mcp_oauth" || args.refresh === undefined) {
+                return { status: "failed", reason: "not_refreshable" };
+            }
+            const hintAt = args.now().toISOString();
+            try {
+                args.refresh.recordAuthHint({
+                    workspaceId: rejected.identity.workspaceId,
+                    vaultId: rejected.identity.vaultId,
+                    credentialId: rejected.identity.credentialId,
+                    expectedAuthVersion: rejected.identity.authVersion,
+                    authHintAt: hintAt,
+                });
+            }
+            catch {
+                return { status: "failed", reason: "hint_adapter_error" };
+            }
+            if (resolveCurrent() === undefined) {
+                closed = true;
+                return { status: "failed", reason: "missing" };
+            }
+            if (changedFrom(current, rejected)) {
+                return { status: "ready", authorization: snapshot() };
+            }
+            const result = await refreshAndResolve(true, rejected.identity.authVersion);
+            if (result?.outcome === "skipped" && result.reason === "forced_refresh_floor") {
+                if (resolveCurrent() === undefined) {
+                    closed = true;
+                    return { status: "failed", reason: "missing" };
+                }
+                if (changedFrom(current, rejected)) {
+                    return { status: "ready", authorization: snapshot() };
+                }
+                return { status: "skipped_floor" };
+            }
+            if (result === undefined || resolveCurrent() === undefined) {
+                return { status: "failed", reason: "missing" };
+            }
+            if (changedFrom(current, rejected)) {
+                return { status: "ready", authorization: snapshot() };
+            }
+            return {
+                status: "failed",
+                ...(result.outcome === "ok" ? {} : { reason: result.reason }),
+            };
+        },
+        knownSecrets: () => [...retained],
+        close: () => {
+            closed = true;
+            retained.clear();
+        },
+    };
+}
+function identityOf(workspaceId, resolved) {
+    return {
+        workspaceId,
+        vaultId: resolved.vaultId,
+        credentialId: resolved.credentialId,
+        authVersion: resolved.authVersion,
+        authType: resolved.authType,
+    };
+}
+function changedFrom(resolved, rejected) {
+    return (resolved.credentialId !== rejected.identity.credentialId ||
+        resolved.authVersion !== rejected.identity.authVersion ||
+        `Bearer ${resolved.token}` !== rejected.authorization);
+}
+const OAUTH_RUNTIME_EXPIRY_SKEW_MS = 60_000;
+function admittedRefreshMode(metadata, now) {
+    if (metadata.authType !== "mcp_oauth" || !metadata.hasRefresh) {
+        return undefined;
+    }
+    if (metadata.refreshStatus === "invalid")
+        return undefined;
+    if (metadata.authHintAt !== null)
+        return "forced";
+    if (metadata.nextRefreshAt !== null &&
+        new Date(metadata.nextRefreshAt).getTime() > now.getTime()) {
+        return undefined;
+    }
+    return metadata.expiresAt !== undefined &&
+        new Date(metadata.expiresAt).getTime() <=
+            now.getTime() + OAUTH_RUNTIME_EXPIRY_SKEW_MS
+        ? "lazy"
+        : undefined;
+}
+function knownSecrets(opts) {
+    const configured = opts.knownSecrets;
+    if (typeof configured === "function")
+        return configured();
+    if (configured !== undefined)
+        return configured;
+    return opts.connection.credential?.knownSecrets();
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist/src/control-plane/sessions/pi/mcp/client.js

@@ -0,0 +1,157 @@
+// Control-plane MCP client (plan 0122 §4.2). One connection per
+// (session, declared server), streamable HTTP only, dialed through the
+// SSRF-guarded fetch. The sandbox never dials MCP servers and (from M2)
+// never sees credentials — connections live control-plane-side by design
+// (architecture.md placement decision).
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { isJsonObject } from "../../../../types/json.js";
+import { attachMcpAuthSnapshot, getMcpAuthSnapshot, recordRejectedMcpAuthorization, runMcpAuthOperation, } from "./credential.js";
+export const DEFAULT_MCP_OPERATION_TIMEOUT_MS = 60_000;
+// Discovery bounds (review 0122-M1, Codex-adv HIGH): the tool list is
+// attacker-influenced input parsed in the shared control plane, so a hostile
+// or broken server must not be able to dictate unbounded work. Exceeding any
+// bound fails the whole connection deterministically (surfaces as the
+// structured mcp_connection_failed_error), never a silent partial register.
+const MAX_DISCOVERED_TOOLS = 256;
+const MAX_TOOL_NAME_LENGTH = 256;
+const MAX_TOOL_DESCRIPTION_LENGTH = 4_096;
+const MAX_TOOL_SCHEMA_BYTES = 64 * 1024;
+const MAX_TOOL_LIST_PAGES = 16;
+export class McpConnection {
+    serverName;
+    tools;
+    client;
+    timeoutMs;
+    credential;
+    constructor(serverName, tools, client, timeoutMs, credential) {
+        this.serverName = serverName;
+        this.tools = tools;
+        this.client = client;
+        this.timeoutMs = timeoutMs;
+        this.credential = credential;
+    }
+    /** Connect + discover in one step; both share the operation timeout. */
+    static async connect(declaration, opts) {
+        const timeoutMs = opts.operationTimeoutMs ?? DEFAULT_MCP_OPERATION_TIMEOUT_MS;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const client = new Client({ name: "open-managed-agents", version: "0" });
+            const transport = new StreamableHTTPClientTransport(new URL(declaration.url), { fetch: credentialFetch(opts.fetch, opts.credential) });
+            try {
+                const tools = await runMcpAuthOperation(async () => {
+                    try {
+                        await client.connect(transport, { timeout: timeoutMs });
+                        return await discoverTools(client, declaration.name, timeoutMs);
+                    }
+                    catch (error) {
+                        throw attachMcpAuthSnapshot(error);
+                    }
+                });
+                return new McpConnection(declaration.name, tools, client, timeoutMs, opts.credential);
+            }
+            catch (error) {
+                const annotated = attachMcpAuthSnapshot(error);
+                await client.close().catch(() => undefined);
+                const rejectedSnapshot = getMcpAuthSnapshot(annotated);
+                if (attempt === 0 &&
+                    opts.credential !== undefined &&
+                    rejectedSnapshot !== undefined &&
+                    isMcpAuthError(annotated)) {
+                    try {
+                        const refreshed = await opts.credential.forceRefresh(rejectedSnapshot);
+                        if (refreshed.status === "ready")
+                            continue;
+                    }
+                    catch {
+                        // Adapter failure does not replace the reached server's structured
+                        // auth rejection; the caller classifies the original final error.
+                    }
+                }
+                opts.credential?.close?.();
+                throw annotated;
+            }
+        }
+        throw new Error("MCP connection retry exhausted");
+    }
+    async callTool(name, args, signal) {
+        const result = await runMcpAuthOperation(async () => {
+            try {
+                return await this.client.callTool({ name, arguments: args }, undefined, {
+                    timeout: this.timeoutMs,
+                    ...(signal === undefined ? {} : { signal }),
+                });
+            }
+            catch (error) {
+                throw attachMcpAuthSnapshot(error);
+            }
+        });
+        return {
+            content: Array.isArray(result.content) ? result.content : [],
+            isError: result.isError === true,
+        };
+    }
+    async close() {
+        await this.client.close().catch(() => undefined);
+        this.credential?.close?.();
+    }
+}
+function credentialFetch(fetch, credential) {
+    if (credential === undefined)
+        return fetch;
+    return async (url, init) => {
+        const snapshot = await credential.authorize();
+        const headers = new Headers(init?.headers);
+        if (snapshot === undefined)
+            headers.delete("authorization");
+        else
+            headers.set("authorization", snapshot.authorization);
+        const response = await fetch(url, { ...init, headers });
+        if (snapshot !== undefined && (response.status === 401 || response.status === 403)) {
+            recordRejectedMcpAuthorization(snapshot);
+        }
+        return response;
+    };
+}
+export function isMcpAuthError(error) {
+    const code = error?.code;
+    return code === 401 || code === 403;
+}
+/** Paginated discovery (review: nextCursor was silently dropped) + bounds. */
+async function discoverTools(client, serverName, timeoutMs) {
+    const tools = [];
+    let cursor;
+    for (let page = 0; page < MAX_TOOL_LIST_PAGES; page += 1) {
+        const listed = await client.listTools(cursor === undefined ? undefined : { cursor }, { timeout: timeoutMs });
+        for (const tool of listed.tools) {
+            if (tools.length >= MAX_DISCOVERED_TOOLS) {
+                throw discoveryBoundError(serverName, `more than ${MAX_DISCOVERED_TOOLS} tools`);
+            }
+            if (tool.name.length > MAX_TOOL_NAME_LENGTH) {
+                throw discoveryBoundError(serverName, `tool name over ${MAX_TOOL_NAME_LENGTH} chars`);
+            }
+            const description = tool.description;
+            if (description !== undefined &&
+                description.length > MAX_TOOL_DESCRIPTION_LENGTH) {
+                throw discoveryBoundError(serverName, `tool ${tool.name} description over ${MAX_TOOL_DESCRIPTION_LENGTH} chars`);
+            }
+            const inputSchema = isJsonObject(tool.inputSchema)
+                ? tool.inputSchema
+                : { type: "object" };
+            if (JSON.stringify(inputSchema).length > MAX_TOOL_SCHEMA_BYTES) {
+                throw discoveryBoundError(serverName, `tool ${tool.name} schema over ${MAX_TOOL_SCHEMA_BYTES} bytes`);
+            }
+            tools.push({
+                name: tool.name,
+                ...(description === undefined ? {} : { description }),
+                inputSchema,
+            });
+        }
+        cursor = listed.nextCursor ?? undefined;
+        if (cursor === undefined)
+            return tools;
+    }
+    throw discoveryBoundError(serverName, `more than ${MAX_TOOL_LIST_PAGES} tools/list pages`);
+}
+function discoveryBoundError(serverName, detail) {
+    return new Error(`MCP server ${serverName} exceeded discovery bounds: ${detail}`);
+}