@raybase/core 0.0.1 → 0.3.3

package/dist/agent-remote-mcp-install.js

@@ -0,0 +1,785 @@
+import { agentRemoteMcpRuntimeTools, agentRemoteMcpToolBindings, remoteMcpModelToolName, remoteMcpSecretNamePattern, validateRemoteMcpEndpoint, validateRemoteMcpToolName } from "./agent-remote-mcp.js";
+import { RemoteMcpCredentialStore, remoteMcpKeyFromEnv } from "./agent-remote-mcp-credentials.js";
+import { remoteMcpRequest } from "./agent-remote-mcp-transport.js";
+import { sha256Hex, stableJson } from "./internal.js";
+import { role } from "./policies.js";
+import { nowIso, q, randomId } from "./sql.js";
+export const raybaseRemoteMcpInstallLimits = {
+    /** Descriptors Core will pin from one `tools/list`. */
+    maxTools: 64,
+    /** Bytes Core will read from one `tools/list` response. */
+    maxDiscoveryBytes: 256_000,
+    maxDescriptionChars: 4_000,
+    maxInputSchemaBytes: 32_000,
+    discoveryTimeoutMs: 10_000
+};
+const defaultRemoteMcpToolPolicy = { kind: "role", role: "user" };
+/* -------------------------------------------------------------------------- */
+/* Discovery                                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * Reads a server's `tools/list` once over stateless Streamable HTTP. This is
+ * the only moment Core talks to an installed server outside a tool call, and
+ * it only ever happens on an operator's install or rediscover.
+ */
+export async function discoverRemoteMcpTools(input) {
+    validateRemoteMcpEndpoint(input.endpoint);
+    const credential = input.credential ?? { type: "none" };
+    validateInstalledCredential(credential);
+    try {
+        const store = credential.type === "stored"
+            ? new RemoteMcpCredentialStore(requiredControl(input.control), remoteMcpKeyFromEnv(input.env))
+            : null;
+        const payload = await remoteMcpRequest({
+            serverName: input.serverName ?? "discovery",
+            endpoint: input.endpoint,
+            transport: input.transport,
+            method: "tools/list",
+            params: {},
+            authorization: async () => {
+                if (store) {
+                    const resolved = await store.resolveAuthorization(input.serverName ?? "");
+                    return { header: resolved.header.reveal(), generation: resolved.generation };
+                }
+                return { header: installedCredentialHeader(credential, input.env), generation: 0 };
+            },
+            coordinator: input.coordinator,
+            fetcher: input.fetcher,
+            timeoutMs: input.timeoutMs ?? raybaseRemoteMcpInstallLimits.discoveryTimeoutMs,
+            maxBytes: raybaseRemoteMcpInstallLimits.maxDiscoveryBytes
+        });
+        const listed = payload?.tools;
+        if (!Array.isArray(listed))
+            throw new Error("Remote MCP tools/list did not return a tools array");
+        if (listed.length > raybaseRemoteMcpInstallLimits.maxTools) {
+            throw new Error(`Remote MCP server listed ${listed.length} tools; Core pins at most ${raybaseRemoteMcpInstallLimits.maxTools}`);
+        }
+        const tools = {};
+        const rejected = [];
+        for (const entry of listed) {
+            const record = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : null;
+            const name = record && typeof record.name === "string" ? record.name : "";
+            try {
+                if (!record)
+                    throw new Error("descriptor must be an object");
+                validateRemoteMcpToolName(name, "(discovered)");
+                if (tools[name])
+                    throw new Error("duplicate tool name");
+                tools[name] = pinnedToolFrom(record);
+            }
+            catch (error) {
+                rejected.push({ name: name || "(unnamed)", reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        if (!Object.keys(tools).length)
+            throw new Error("Remote MCP server listed no tool Core is willing to pin");
+        return {
+            endpointHost: endpointHost(input.endpoint),
+            tools,
+            hash: await pinnedToolsHash(tools),
+            discoveredAt: nowIso(),
+            rejected
+        };
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+}
+function pinnedToolFrom(record) {
+    const description = typeof record.description === "string" ? record.description.trim() : "";
+    if (!description)
+        throw new Error("description is required");
+    if (description.length > raybaseRemoteMcpInstallLimits.maxDescriptionChars)
+        throw new Error("description is too long");
+    const schema = record.inputSchema;
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        throw new Error("inputSchema must be a JSON-schema object");
+    const schemaRecord = schema;
+    if (schemaRecord.type !== undefined && schemaRecord.type !== "object")
+        throw new Error("inputSchema must describe an object");
+    if (JSON.stringify(schemaRecord).length > raybaseRemoteMcpInstallLimits.maxInputSchemaBytes)
+        throw new Error("inputSchema is too large");
+    const annotations = record.annotations && typeof record.annotations === "object" && !Array.isArray(record.annotations)
+        ? record.annotations
+        : undefined;
+    const hints = annotations
+        ? {
+            ...(typeof annotations.readOnlyHint === "boolean" ? { readOnlyHint: annotations.readOnlyHint } : {}),
+            ...(typeof annotations.destructiveHint === "boolean" ? { destructiveHint: annotations.destructiveHint } : {}),
+            ...(typeof annotations.idempotentHint === "boolean" ? { idempotentHint: annotations.idempotentHint } : {})
+        }
+        : undefined;
+    return {
+        description,
+        inputSchema: { ...schemaRecord, type: "object" },
+        ...(hints && Object.keys(hints).length ? { annotations: hints } : {})
+    };
+}
+export async function pinnedToolsHash(tools) {
+    return sha256Hex(stableJson(tools));
+}
+export function remoteMcpDiscoveryDiff(current, next) {
+    const added = Object.keys(next).filter((name) => !current[name]).sort();
+    const removed = Object.keys(current).filter((name) => !next[name]).sort();
+    const shared = Object.keys(next).filter((name) => current[name]);
+    const changed = shared.filter((name) => stableJson(current[name]) !== stableJson(next[name])).sort();
+    const unchanged = shared.filter((name) => !changed.includes(name)).sort();
+    return { added, removed, changed, unchanged };
+}
+/* -------------------------------------------------------------------------- */
+/* Store                                                                       */
+/* -------------------------------------------------------------------------- */
+export async function listInstalledRemoteMcpServerRows(control) {
+    return control.all(`SELECT * FROM ${q("_agent_remote_mcp_servers")} ORDER BY "name"`);
+}
+export async function findInstalledRemoteMcpServerRow(control, name) {
+    return control.first(`SELECT * FROM ${q("_agent_remote_mcp_servers")} WHERE "name"=?`, [name]);
+}
+export async function listAgentRemoteMcpBindingRows(control, agentName) {
+    return agentName
+        ? control.all(`SELECT * FROM ${q("_agent_remote_mcp_bindings")} WHERE "agentName"=? ORDER BY "serverName"`, [agentName])
+        : control.all(`SELECT * FROM ${q("_agent_remote_mcp_bindings")} ORDER BY "agentName","serverName"`);
+}
+export async function installRemoteMcpServer(input) {
+    const name = input.name;
+    validateRemoteMcpEndpoint(input.endpoint);
+    const credential = input.credential ?? { type: "none" };
+    validateInstalledCredential(credential);
+    if ((input.reservedServerNames ?? []).includes(name)) {
+        throw new Error(`Remote MCP server ${name} is already declared in code; installed and code-declared servers share one namespace`);
+    }
+    if (await findInstalledRemoteMcpServerRow(input.control, name)) {
+        throw new Error(`Remote MCP server ${name} is already installed; rediscover or disable it instead`);
+    }
+    const discovery = input.oauthDiscovery || input.deferDiscovery ? null : await discoverRemoteMcpTools({
+        serverName: name, endpoint: input.endpoint, credential, control: input.control,
+        transport: input.transport, env: input.env, fetcher: input.fetcher
+    });
+    const access = resolveToolAccess(discovery?.tools ?? {}, input.access);
+    const now = input.now ?? nowIso();
+    const row = {
+        id: randomId("remote_mcp_server"),
+        name,
+        endpoint: input.endpoint,
+        credentialRefJson: JSON.stringify(credential),
+        transport: input.transport ?? "stateless",
+        discoveryState: input.oauthDiscovery || input.deferDiscovery ? "awaiting_credential" : "pinned",
+        oauthMetadataJson: input.oauthDiscovery ? JSON.stringify(input.oauthDiscovery) : null,
+        serverRevision: 1,
+        toolsJson: JSON.stringify(discovery?.tools ?? {}),
+        policyJson: JSON.stringify(access),
+        discoveredAt: discovery?.discoveredAt ?? now,
+        discoveryHash: discovery?.hash ?? await pinnedToolsHash({}),
+        status: "installed",
+        createdBy: input.actor,
+        createdAt: now,
+        updatedAt: now
+    };
+    // Validate through the same definition path a code-declared server takes,
+    // so an installed row can never produce a shape v1 would have refused.
+    const server = installedRemoteMcpServerFor(row);
+    await input.control.run(`INSERT INTO ${q("_agent_remote_mcp_servers")} ("id","name","endpoint","credentialRefJson","transport","discoveryState","oauthMetadataJson","serverRevision","toolsJson","policyJson","discoveredAt","discoveryHash","status","createdBy","createdAt","updatedAt") VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [row.id, row.name, row.endpoint, row.credentialRefJson, row.transport, row.discoveryState, row.oauthMetadataJson, row.serverRevision, row.toolsJson, row.policyJson, row.discoveredAt, row.discoveryHash, row.status, row.createdBy, row.createdAt, row.updatedAt]);
+    return {
+        row,
+        server: remoteMcpServerView(row, server),
+        discovery: discovery ?? { endpointHost: endpointHost(input.endpoint), tools: {}, hash: row.discoveryHash, discoveredAt: now, rejected: [] },
+        secretName: credential.type === "secret" ? credential.name : null
+    };
+}
+export async function rediscoverRemoteMcpServer(input) {
+    const row = await requireServerRow(input.control, input.name);
+    const credential = parseCredentialRef(row.credentialRefJson);
+    const discovery = await discoverRemoteMcpTools({
+        serverName: row.name, endpoint: row.endpoint, credential, control: input.control,
+        transport: row.transport === "sessioned" ? "sessioned" : "stateless", env: input.env, fetcher: input.fetcher
+    });
+    const current = parsePinnedTools(row.toolsJson);
+    const diff = remoteMcpDiscoveryDiff(current, discovery.tools);
+    if (!input.confirm)
+        return { diff, applied: false, discovery, disabledBindings: [] };
+    // The operator's access rules survive rediscovery for every tool that
+    // survived it; a new tool starts at the closed default.
+    const previousAccess = parseToolAccess(row.policyJson);
+    const access = resolveToolAccess(discovery.tools, Object.fromEntries(Object.entries(previousAccess).filter(([toolName]) => discovery.tools[toolName])));
+    const now = input.now ?? nowIso();
+    const next = {
+        ...row,
+        toolsJson: JSON.stringify(discovery.tools),
+        policyJson: JSON.stringify(access),
+        discoveredAt: discovery.discoveredAt,
+        discoveryHash: discovery.hash,
+        discoveryState: "pinned",
+        serverRevision: Number(row.serverRevision || 0) + 1,
+        updatedAt: now
+    };
+    const server = installedRemoteMcpServerFor(next);
+    await input.control.run(`UPDATE ${q("_agent_remote_mcp_servers")} SET "toolsJson"=?,"policyJson"=?,"discoveredAt"=?,"discoveryHash"=?,"discoveryState"='pinned',"serverRevision"=?,"updatedAt"=? WHERE "id"=?`, [next.toolsJson, next.policyJson, next.discoveredAt, next.discoveryHash, next.serverRevision, next.updatedAt, next.id]);
+    const disabledBindings = [];
+    if (diff.removed.length) {
+        for (const binding of await listAgentRemoteMcpBindingRows(input.control)) {
+            if (binding.serverName !== row.name || binding.status !== "active")
+                continue;
+            const bound = parseToolNames(binding.toolNamesJson);
+            const missing = bound.filter((toolName) => diff.removed.includes(toolName));
+            if (!missing.length)
+                continue;
+            const reason = `Pinned tool(s) ${missing.join(", ")} disappeared at rediscovery on ${now}`;
+            await input.control.run(`UPDATE ${q("_agent_remote_mcp_bindings")} SET "status"='disabled',"disabledReason"=? WHERE "id"=?`, [reason, binding.id]);
+            disabledBindings.push({ agentName: binding.agentName, serverName: binding.serverName, reason });
+        }
+    }
+    return { diff, applied: true, discovery, disabledBindings, server: remoteMcpServerView(next, server) };
+}
+export async function setInstalledRemoteMcpServerStatus(input) {
+    const row = await requireServerRow(input.control, input.name);
+    const now = input.now ?? nowIso();
+    await input.control.run(`UPDATE ${q("_agent_remote_mcp_servers")} SET "status"=?,"updatedAt"=? WHERE "id"=?`, [input.status, now, row.id]);
+    return { ...row, status: input.status, updatedAt: now };
+}
+export async function bindAgentRemoteMcpServer(input) {
+    const row = await requireServerRow(input.control, input.serverName);
+    if (row.status !== "installed")
+        throw new Error(`Remote MCP server ${input.serverName} is disabled`);
+    if ((row.discoveryState ?? "pinned") !== "pinned")
+        throw new Error(`Remote MCP server ${input.serverName} must finish credential setup and tool discovery before binding`);
+    const pinned = parsePinnedTools(row.toolsJson);
+    const toolNames = [...new Set(input.toolNames.map((value) => value.trim()).filter(Boolean))];
+    if (!toolNames.length)
+        throw new Error("A remote MCP binding must allow at least one tool");
+    for (const toolName of toolNames) {
+        if (!pinned[toolName])
+            throw new Error(`Remote MCP server ${input.serverName} has no pinned tool ${toolName}`);
+    }
+    const reserved = new Set(input.reservedModelToolNames ?? []);
+    for (const toolName of toolNames) {
+        const modelToolName = remoteMcpModelToolName(input.serverName, toolName);
+        if (reserved.has(modelToolName)) {
+            throw new Error(`Agent ${input.agentName} already offers runtime tool "${modelToolName}"; refusing a duplicate remote MCP binding`);
+        }
+    }
+    const now = input.now ?? nowIso();
+    const existing = await input.control.first(`SELECT * FROM ${q("_agent_remote_mcp_bindings")} WHERE "agentName"=? AND "serverName"=?`, [input.agentName, input.serverName]);
+    if (existing) {
+        await input.control.run(`UPDATE ${q("_agent_remote_mcp_bindings")} SET "toolNamesJson"=?,"status"='active',"disabledReason"=NULL WHERE "id"=?`, [JSON.stringify(toolNames), existing.id]);
+        return { ...existing, toolNamesJson: JSON.stringify(toolNames), status: "active", disabledReason: null };
+    }
+    const binding = {
+        id: randomId("remote_mcp_binding"),
+        agentName: input.agentName,
+        serverName: input.serverName,
+        toolNamesJson: JSON.stringify(toolNames),
+        status: "active",
+        disabledReason: null,
+        createdBy: input.actor,
+        createdAt: now
+    };
+    await input.control.run(`INSERT INTO ${q("_agent_remote_mcp_bindings")} ("id","agentName","serverName","toolNamesJson","status","disabledReason","createdBy","createdAt") VALUES (?,?,?,?,?,?,?,?)`, [binding.id, binding.agentName, binding.serverName, binding.toolNamesJson, binding.status, binding.disabledReason, binding.createdBy, binding.createdAt]);
+    return binding;
+}
+export async function unbindAgentRemoteMcpServer(input) {
+    const existing = await input.control.first(`SELECT * FROM ${q("_agent_remote_mcp_bindings")} WHERE "agentName"=? AND "serverName"=?`, [input.agentName, input.serverName]);
+    if (!existing)
+        return false;
+    await input.control.run(`DELETE FROM ${q("_agent_remote_mcp_bindings")} WHERE "id"=?`, [existing.id]);
+    return true;
+}
+/* -------------------------------------------------------------------------- */
+/* Projection                                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * The `RaybaseRemoteMcpServer` an installed row stands for — exactly the shape
+ * a code-declared server has, so `callRemoteMcpTool` and the event recorder
+ * are unchanged.
+ */
+export function installedRemoteMcpServerFor(row) {
+    const pinned = parsePinnedTools(row.toolsJson);
+    const access = parseToolAccess(row.policyJson);
+    const credential = parseCredentialRef(row.credentialRefJson);
+    const tools = {};
+    for (const [toolName, descriptor] of Object.entries(pinned)) {
+        const rule = access[toolName];
+        tools[toolName] = {
+            description: descriptor.description,
+            inputSchema: descriptor.inputSchema,
+            ...(descriptor.annotations ? { annotations: descriptor.annotations } : {}),
+            ...(descriptor.timeoutMs !== undefined ? { timeoutMs: descriptor.timeoutMs } : {}),
+            ...(descriptor.maxResultBytes !== undefined ? { maxResultBytes: descriptor.maxResultBytes } : {}),
+            ...(descriptor.redactionKeys ? { redactionKeys: descriptor.redactionKeys } : {}),
+            policy: parsePolicyExpression(rule?.policy ?? defaultRemoteMcpToolPolicy),
+            audience: rule?.audience ?? "signed-in"
+        };
+    }
+    validateRemoteMcpEndpoint(row.endpoint);
+    validateInstalledCredential(credential);
+    return {
+        name: row.name,
+        endpoint: row.endpoint,
+        transport: row.transport === "sessioned" ? "sessioned" : "stateless",
+        ...(credential.type === "none" ? {} : credential.type === "stored"
+            ? { credentials: { type: "stored", serverName: row.name } }
+            : { credentials: credential }),
+        tools
+    };
+}
+export function remoteMcpServerView(row, server = installedRemoteMcpServerFor(row), credentialStatus = null) {
+    const access = parseToolAccess(row.policyJson);
+    const credential = parseCredentialRef(row.credentialRefJson);
+    return {
+        name: row.name,
+        endpoint: row.endpoint,
+        endpointHost: endpointHost(row.endpoint),
+        status: row.status === "disabled" ? "disabled" : "installed",
+        credential,
+        secretName: credential.type === "secret" ? credential.name : null,
+        transport: row.transport === "sessioned" ? "sessioned" : "stateless",
+        discoveryState: row.discoveryState === "awaiting_credential" ? "awaiting_credential" : row.discoveryState === "rediscovery_required" ? "rediscovery_required" : "pinned",
+        credentialStatus,
+        oauth: parseOAuthMetadata(row.oauthMetadataJson),
+        tools: Object.entries(server.tools).map(([toolName, descriptor]) => ({
+            name: toolName,
+            modelToolName: remoteMcpModelToolName(row.name, toolName),
+            description: descriptor.description,
+            policy: access[toolName]?.policy ?? defaultRemoteMcpToolPolicy,
+            audience: descriptor.audience ?? "signed-in",
+            ...(descriptor.annotations ? { annotations: descriptor.annotations } : {}),
+            ...(descriptor.timeoutMs !== undefined ? { timeoutMs: descriptor.timeoutMs } : {}),
+            ...(descriptor.maxResultBytes !== undefined ? { maxResultBytes: descriptor.maxResultBytes } : {})
+        })).sort((left, right) => left.name.localeCompare(right.name)),
+        discoveredAt: row.discoveredAt,
+        discoveryHash: row.discoveryHash,
+        createdBy: row.createdBy,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt
+    };
+}
+export function remoteMcpBindingView(row) {
+    const toolNames = parseToolNames(row.toolNamesJson);
+    return {
+        agentName: row.agentName,
+        serverName: row.serverName,
+        toolNames,
+        modelToolNames: toolNames.map((toolName) => remoteMcpModelToolName(row.serverName, toolName)),
+        status: row.status === "disabled" ? "disabled" : "active",
+        disabledReason: row.disabledReason ?? null,
+        createdBy: row.createdBy,
+        createdAt: row.createdAt
+    };
+}
+/** Installed servers and bindings, projected for admin/doctor/operator surfaces. */
+export async function installedRemoteMcpOverview(control) {
+    const rows = await listInstalledRemoteMcpServerRows(control);
+    let statuses = new Map();
+    try {
+        // Status reads are safe by construction and do not decrypt envelopes.
+        const raw = await control.all(`SELECT "serverName","kind","state","scheme","revision","generation","expiresAt","scopesJson","subject","createdBy","createdAt","updatedAt" FROM ${q("_agent_remote_mcp_credentials")}`);
+        statuses = new Map(raw.map((row) => [String(row.serverName), {
+                serverName: String(row.serverName), kind: row.kind === "oauth" ? "oauth" : "static",
+                state: row.state === "reauth_required" ? "reauth_required" : row.state === "cleared" ? "cleared" : "ready",
+                scheme: row.scheme === "raw" ? "raw" : "bearer", revision: Number(row.revision), generation: Number(row.generation),
+                expiresAt: typeof row.expiresAt === "string" ? row.expiresAt : null,
+                scopes: parseStringArray(typeof row.scopesJson === "string" ? row.scopesJson : null),
+                subject: typeof row.subject === "string" ? row.subject : null, createdBy: String(row.createdBy), createdAt: String(row.createdAt), updatedAt: String(row.updatedAt)
+            }]));
+    }
+    catch { /* tables may not have reconciled yet */ }
+    const servers = [];
+    for (const row of rows) {
+        let view;
+        try {
+            view = remoteMcpServerView(row, undefined, statuses.get(row.name) ?? null);
+        }
+        catch (error) {
+            throw new Error(`Installed remote MCP server ${row.name} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        view.toolsHash = await pinnedToolsHash(parsePinnedTools(row.toolsJson));
+        servers.push(view);
+    }
+    const bindings = (await listAgentRemoteMcpBindingRows(control)).map(remoteMcpBindingView);
+    return { servers, bindings };
+}
+/** Summaries in the same shape the code-declared surfaces use, for admin/doctor. */
+export async function installedRemoteMcpServerSummaries(control) {
+    const { servers } = await installedRemoteMcpOverview(control);
+    return servers.map((server) => ({
+        name: server.name,
+        endpointHost: server.endpointHost,
+        toolNames: server.tools.map((tool) => tool.name).sort((left, right) => left.localeCompare(right)),
+        credentialRefs: server.secretName ? [server.secretName] : []
+    }));
+}
+export async function installedAgentRemoteMcpBindingSummaries(control) {
+    return (await listAgentRemoteMcpBindingRows(control))
+        .filter((row) => row.status !== "disabled")
+        .map((row) => {
+        const view = remoteMcpBindingView(row);
+        return {
+            agentName: view.agentName,
+            serverName: view.serverName,
+            toolNames: [...view.toolNames].sort((left, right) => left.localeCompare(right)),
+            modelToolNames: [...view.modelToolNames].sort((left, right) => left.localeCompare(right))
+        };
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Runtime resolution                                                          */
+/* -------------------------------------------------------------------------- */
+const installedBindingCache = new WeakMap();
+/**
+ * The installed bindings this agent may use, read once per invocation. Rows are
+ * read straight from the database and never re-validated against the server:
+ * the model's tool list is exactly the set the operator pinned.
+ */
+export async function resolveInstalledAgentRemoteMcpToolBindings(input) {
+    if (!input.control)
+        return [];
+    const key = `${input.agent.name}:${input.conversationId}:${input.runId || input.requestId}`;
+    let requestCache = input.request ? installedBindingCache.get(input.request) : undefined;
+    if (input.request && !requestCache) {
+        requestCache = new Map();
+        installedBindingCache.set(input.request, requestCache);
+    }
+    const existing = requestCache?.get(key);
+    if (existing)
+        return existing;
+    const pending = resolveInstalledAgentRemoteMcpToolBindingsUncached(input);
+    requestCache?.set(key, pending);
+    return pending;
+}
+async function resolveInstalledAgentRemoteMcpToolBindingsUncached(input) {
+    let bindingRows;
+    try {
+        bindingRows = await listAgentRemoteMcpBindingRows(input.control, input.agent.name);
+    }
+    catch {
+        // A newly deployed Durable Object may not have applied the manifest tables
+        // yet. An unreadable install table means no installed tools, never a
+        // failed turn.
+        return [];
+    }
+    const active = bindingRows.filter((row) => row.status !== "disabled");
+    if (!active.length)
+        return [];
+    const reserved = new Set();
+    try {
+        for (const binding of agentRemoteMcpToolBindings(input.agent))
+            reserved.add(binding.modelToolName);
+    }
+    catch {
+        // Code-declared validation failures surface elsewhere; they must not stop
+        // installed tools from resolving.
+    }
+    const bindings = [];
+    for (const row of active) {
+        const serverRow = await findInstalledRemoteMcpServerRow(input.control, row.serverName);
+        if (!serverRow || serverRow.status !== "installed")
+            continue;
+        let server;
+        try {
+            server = installedRemoteMcpServerFor(serverRow);
+        }
+        catch (error) {
+            console.warn(`Raybase agent ${input.agent.name} skipped installed remote MCP server ${row.serverName}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        for (const toolName of parseToolNames(row.toolNamesJson)) {
+            const descriptor = server.tools[toolName];
+            if (!descriptor)
+                continue;
+            const modelToolName = remoteMcpModelToolName(server.name, toolName);
+            if (reserved.has(modelToolName)) {
+                console.warn(`Raybase agent ${input.agent.name} skipped installed remote MCP tool ${modelToolName}: the name is already taken`);
+                continue;
+            }
+            reserved.add(modelToolName);
+            bindings.push({ server, toolName, descriptor, modelToolName });
+        }
+    }
+    return bindings;
+}
+/**
+ * Code-declared plus installed bindings, merged. `agentRemoteMcpToolBindings`
+ * stays synchronous for definition-time validation.
+ */
+export async function resolveAgentRemoteMcpToolBindings(input) {
+    return [...agentRemoteMcpToolBindings(input.agent), ...(await resolveInstalledAgentRemoteMcpToolBindings(input))];
+}
+/** Model-facing tools for the installed half of the merged set. */
+export async function installedAgentRemoteMcpRuntimeTools(input) {
+    const bindings = await resolveInstalledAgentRemoteMcpToolBindings(input);
+    if (!bindings.length)
+        return [];
+    return agentRemoteMcpRuntimeTools(input, bindings);
+}
+/**
+ * What an app may show a member about an agent's installed servers: names,
+ * host and tool descriptions. No endpoint path, no credential reference, no
+ * policy internals. Members never install.
+ */
+export async function agentRemoteMcpCapabilities(control, agentName) {
+    const bindings = (await listAgentRemoteMcpBindingRows(control, agentName)).filter((row) => row.status !== "disabled");
+    const capabilities = [];
+    for (const binding of bindings) {
+        const row = await findInstalledRemoteMcpServerRow(control, binding.serverName);
+        if (!row || row.status !== "installed")
+            continue;
+        const pinned = parsePinnedTools(row.toolsJson);
+        const tools = parseToolNames(binding.toolNamesJson)
+            .filter((toolName) => pinned[toolName])
+            .map((toolName) => ({ name: toolName, description: pinned[toolName].description }));
+        if (!tools.length)
+            continue;
+        capabilities.push({ serverName: row.name, endpointHost: endpointHost(row.endpoint), tools });
+    }
+    return capabilities.sort((left, right) => left.serverName.localeCompare(right.serverName));
+}
+/* -------------------------------------------------------------------------- */
+/* Doctor                                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * Findings an operator can act on. `env` is the worker environment when the
+ * caller has one: a deployed app can see whether the secret is bound, a static
+ * caller cannot and gets the "check wrangler secret list" advice instead.
+ */
+export async function remoteMcpInstallFindings(input) {
+    const { servers, bindings } = await installedRemoteMcpOverview(input.control);
+    const findings = [];
+    const canReadEnv = input.canReadEnv ?? input.env !== undefined;
+    const byName = new Map(servers.map((server) => [server.name, server]));
+    for (const server of servers) {
+        if (server.credential.type === "stored") {
+            try {
+                remoteMcpKeyFromEnv(input.env);
+            }
+            catch {
+                findings.push({
+                    level: "error", check: "remote-mcp-store-key", serverName: server.name,
+                    message: `Installed remote MCP server ${server.name} uses runtime credential storage, but RAYBASE_REMOTE_MCP_KEY is missing or invalid.`,
+                    fix: "Run raybase mcp keys enable, then configure the same Worker secret before deployment."
+                });
+            }
+            if (!server.credentialStatus || server.credentialStatus.state === "cleared") {
+                findings.push({ level: "warning", check: "remote-mcp-credential", serverName: server.name, message: `Installed remote MCP server ${server.name} has no usable stored credential.`, fix: `Set a credential or connect OAuth for ${server.name}.` });
+            }
+            else if (server.credentialStatus.state === "reauth_required") {
+                findings.push({ level: "error", check: "remote-mcp-reauth", serverName: server.name, message: `Installed remote MCP server ${server.name} needs OAuth reconnection.`, fix: `Run raybase mcp connect ${server.name}.` });
+            }
+            else if (server.credentialStatus.kind === "oauth" && server.credentialStatus.expiresAt && Date.parse(server.credentialStatus.expiresAt) <= Date.now()) {
+                findings.push({ level: "warning", check: "remote-mcp-oauth-expired", serverName: server.name, message: `Installed remote MCP server ${server.name} has an expired OAuth access token.`, fix: `Call the server to trigger refresh, or run raybase mcp connect ${server.name} if refresh is unavailable.` });
+            }
+        }
+        if (server.secretName && canReadEnv) {
+            const value = input.env && typeof input.env === "object" ? input.env[server.secretName] : undefined;
+            if (typeof value !== "string" || !value.trim()) {
+                findings.push({
+                    level: "error",
+                    check: "remote-mcp-secret",
+                    serverName: server.name,
+                    secretName: server.secretName,
+                    message: `Installed remote MCP server ${server.name} needs ${server.secretName}, which is not set in this environment.`,
+                    fix: `Run wrangler secret put ${server.secretName} for the deployed worker, or add ${server.secretName} to .dev.vars locally.`
+                });
+            }
+        }
+        if (server.status === "installed" && server.discoveryHash !== server.toolsHash) {
+            findings.push({
+                level: "error",
+                check: "remote-mcp-discovery-hash",
+                serverName: server.name,
+                message: `Installed remote MCP server ${server.name} has pinned descriptors that no longer match its last discovery hash.`,
+                fix: `Run raybase mcp rediscover ${server.name} and confirm the diff so the pinned set and its hash agree again.`
+            });
+        }
+    }
+    try {
+        const stalePending = await input.control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_remote_mcp_oauth_pending")} WHERE "expiresAt"<=?`, [nowIso()]);
+        const staleUploads = await input.control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_remote_mcp_credential_uploads")} WHERE "expiresAt"<=?`, [nowIso()]);
+        const count = Number(stalePending?.count ?? 0) + Number(staleUploads?.count ?? 0);
+        if (count)
+            findings.push({ level: "info", check: "remote-mcp-stale-credentials", message: `${count} expired remote MCP OAuth state or upload ticket row(s) await pruning.`, fix: "A credential lifecycle operation prunes these rows opportunistically; no secret values are stored in tickets." });
+    }
+    catch { /* newly reconciled tables may not exist yet */ }
+    for (const binding of bindings) {
+        const server = byName.get(binding.serverName);
+        if (!server) {
+            findings.push({
+                level: "error",
+                check: "remote-mcp-binding",
+                serverName: binding.serverName,
+                message: `Agent ${binding.agentName} is bound to remote MCP server ${binding.serverName}, which is not installed.`,
+                fix: `Run raybase mcp unbind ${binding.agentName} ${binding.serverName}, or install the server again.`
+            });
+            continue;
+        }
+        if (server.status === "disabled") {
+            findings.push({
+                level: "warning",
+                check: "remote-mcp-binding",
+                serverName: binding.serverName,
+                message: `Agent ${binding.agentName} is bound to remote MCP server ${binding.serverName}, which is disabled; its tools are not offered.`,
+                fix: `Re-enable the server, or run raybase mcp unbind ${binding.agentName} ${binding.serverName}.`
+            });
+        }
+        if (binding.status === "disabled") {
+            findings.push({
+                level: "warning",
+                check: "remote-mcp-binding",
+                serverName: binding.serverName,
+                message: `Agent ${binding.agentName}'s binding to ${binding.serverName} is disabled: ${binding.disabledReason ?? "a pinned tool disappeared"}.`,
+                fix: `Run raybase mcp bind ${binding.agentName} ${binding.serverName} --tools … with the tools that still exist.`
+            });
+        }
+    }
+    return findings;
+}
+/* -------------------------------------------------------------------------- */
+/* Parsing helpers                                                             */
+/* -------------------------------------------------------------------------- */
+export function parsePinnedTools(value) {
+    const parsed = safeJson(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    return parsed;
+}
+export function parseToolAccess(value) {
+    const parsed = safeJson(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    return parsed;
+}
+export function parseCredentialRef(value) {
+    const parsed = safeJson(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Installed remote MCP credential reference is malformed");
+    const record = parsed;
+    if (record.type === "none")
+        return { type: "none" };
+    if (record.type === "stored")
+        return { type: "stored" };
+    if (record.type !== "secret")
+        throw new Error("Installed remote MCP credential reference type is unsupported");
+    return {
+        type: "secret",
+        name: String(record.name ?? ""),
+        ...(record.scheme === "raw" ? { scheme: "raw" } : record.scheme === "bearer" ? { scheme: "bearer" } : {})
+    };
+}
+export function parseToolNames(value) {
+    const parsed = safeJson(value);
+    return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+}
+/**
+ * `role:user`, `operator`, `deny`, or `public`. `public` is the only spelling
+ * that reaches the public principal, and it forces the read-only hint v1
+ * requires for public Agent use.
+ */
+export function parseRemoteMcpAccessSpec(spec) {
+    const value = spec.trim();
+    if (value === "operator")
+        return { policy: { kind: "operator" }, audience: "signed-in" };
+    if (value === "deny")
+        return { policy: { kind: "denyAll" }, audience: "signed-in" };
+    if (value === "public")
+        return { policy: { kind: "role", role: "user" }, audience: ["signed-in", "public"] };
+    const match = /^role:([A-Za-z][A-Za-z0-9_-]*)$/.exec(value);
+    if (match)
+        return { policy: { kind: "role", role: match[1] }, audience: "signed-in" };
+    throw new Error(`Unsupported remote MCP access rule "${spec}". Use role:<name>, operator, deny, or public.`);
+}
+export function validateInstalledCredential(credential) {
+    if (credential.type === "none" || credential.type === "stored")
+        return;
+    if (credential.type !== "secret")
+        throw new Error("Installed remote MCP credentials must be stored, a secret reference, or none");
+    if (!remoteMcpSecretNamePattern.test(credential.name)) {
+        throw new Error(`Remote MCP secret name ${credential.name} must match RAYBASE_MCP_<NAME>_TOKEN`);
+    }
+}
+function installedCredentialHeader(credential, env) {
+    if (credential.type !== "secret")
+        return undefined;
+    const value = env && typeof env === "object" ? env[credential.name] : undefined;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Remote MCP credential ${credential.name} is not configured in this environment`);
+    }
+    return credential.scheme === "raw" ? value.trim() : `Bearer ${value.trim()}`;
+}
+function requiredControl(control) {
+    if (!control)
+        throw new Error("Remote MCP stored credentials require the control database");
+    return control;
+}
+function parseOAuthMetadata(value) {
+    if (!value)
+        return null;
+    const parsed = safeJson(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+}
+function parseStringArray(value) {
+    if (!value)
+        return [];
+    const parsed = safeJson(value);
+    return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+}
+function resolveToolAccess(tools, access) {
+    const resolved = {};
+    // "*" is the operator's rule for every tool without one of its own.
+    const fallback = access?.["*"];
+    for (const [toolName, rule] of Object.entries(access ?? {})) {
+        if (toolName === "*")
+            continue;
+        if (!tools[toolName])
+            throw new Error(`Access rule references unpinned tool ${toolName}`);
+        resolved[toolName] = { policy: rule.policy ?? defaultRemoteMcpToolPolicy, ...(rule.audience ? { audience: rule.audience } : {}) };
+    }
+    for (const toolName of Object.keys(tools)) {
+        if (resolved[toolName])
+            continue;
+        resolved[toolName] = fallback
+            ? { policy: fallback.policy ?? defaultRemoteMcpToolPolicy, ...(fallback.audience ? { audience: fallback.audience } : {}) }
+            : { policy: defaultRemoteMcpToolPolicy, audience: "signed-in" };
+    }
+    return resolved;
+}
+async function requireServerRow(control, name) {
+    const row = await findInstalledRemoteMcpServerRow(control, name);
+    if (!row)
+        throw new Error(`Remote MCP server ${name} is not installed`);
+    return row;
+}
+function parsePolicyExpression(value) {
+    switch (value?.kind) {
+        case "allowAll":
+        case "denyAll":
+        case "operator":
+            return { kind: value.kind };
+        case "role":
+            return role(String(value.role));
+        case "servicePrincipal":
+            return { kind: "servicePrincipal", service: String(value.service) };
+        case "anyOf":
+        case "allOf":
+            return { kind: value.kind, policies: (value.policies ?? []).map(parsePolicyExpression) };
+        case "not":
+            return { kind: "not", policy: parsePolicyExpression(value.policy) };
+        default:
+            // `owns` needs a row and cannot describe a remote tool call.
+            throw new Error(`Unsupported remote MCP access rule kind "${String(value?.kind)}"`);
+    }
+}
+function safeJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function endpointHost(endpoint) {
+    try {
+        return new URL(endpoint).hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=agent-remote-mcp-install.js.map