@raybase/core 0.0.2 → 0.3.3

package/dist/agent-remote-mcp.js

@@ -0,0 +1,681 @@
+import { actionAudienceAllows, evaluateActionPolicy } from "./actions.js";
+import { safeAgentToolSegment } from "./agent-skills.js";
+import { sha256Hex, stableJson } from "./internal.js";
+import { validateOutboundHttpsUrl } from "./outbound-https.js";
+import { id, integer, longText, raybaseSystemTable, text } from "./schema.js";
+import { nowIso, randomId } from "./sql.js";
+import { RemoteMcpCredentialStore, remoteMcpCredentialSystemTables, remoteMcpKeyFromEnv } from "./agent-remote-mcp-credentials.js";
+import { RemoteMcpCredentialError } from "./agent-remote-mcp-crypto.js";
+import { refreshRemoteMcpOAuth } from "./agent-remote-mcp-oauth.js";
+import { remoteMcpRequest, RemoteMcpTransportError } from "./agent-remote-mcp-transport.js";
+/** The closed shape a runtime-installed server's secret name must have. */
+export const remoteMcpSecretNamePattern = /^RAYBASE_MCP_[A-Z0-9_]+_TOKEN$/;
+/** The conventional secret name for an installed server, e.g. `weather` → `RAYBASE_MCP_WEATHER_TOKEN`. */
+export function remoteMcpSecretNameFor(serverName) {
+    const segment = serverName.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+    if (!segment)
+        throw new Error(`Cannot derive a remote MCP secret name from server name "${serverName}"`);
+    return `RAYBASE_MCP_${segment}_TOKEN`;
+}
+export const raybaseRemoteMcpSystemTables = [
+    ...remoteMcpCredentialSystemTables,
+    raybaseSystemTable("_agent_remote_mcp_events", {
+        id: id(),
+        agentName: text({ required: true }),
+        conversationId: text({ required: true }),
+        runId: text({ required: true }),
+        requestId: text({ required: true }),
+        toolCallId: text({ required: true }),
+        principalKind: text({ required: true }),
+        userId: text(),
+        publicScopeHash: text(),
+        organizationId: text(),
+        serverName: text({ required: true }),
+        remoteToolName: text({ required: true }),
+        modelToolName: text({ required: true }),
+        endpointHost: text({ required: true }),
+        argumentsHash: text({ required: true }),
+        argumentsPreviewJson: longText(),
+        resultStatus: text({ required: true }),
+        resultPreviewJson: longText(),
+        httpStatus: integer(),
+        latencyMs: integer({ required: true }),
+        error: longText(),
+        createdAt: text({ required: true })
+    }, {
+        indexes: [
+            ["agentName", "createdAt"],
+            ["conversationId", "createdAt"],
+            ["serverName", "remoteToolName", "createdAt"],
+            ["resultStatus", "createdAt"]
+        ]
+    }),
+    // Runtime-installed servers. `credentialRefJson` holds a *name* and never a
+    // value; `toolsJson` holds the descriptors pinned at the operator's
+    // discovery; `policyJson` holds the operator's per-tool access rule, which
+    // the server never supplies.
+    raybaseSystemTable("_agent_remote_mcp_servers", {
+        id: id(),
+        name: text({ required: true }),
+        endpoint: text({ required: true }),
+        credentialRefJson: longText({ required: true }),
+        // Added after the table first shipped (2026-08-23). Optional on purpose:
+        // a system table only auto-adds plain optional columns, and a required
+        // one here failed every queue message of an app whose table predates it
+        // (Birch, local). Readers treat a missing transport as "stateless", a
+        // missing discoveryState as "pinned", a missing serverRevision as 0.
+        transport: text(),
+        discoveryState: text(),
+        oauthMetadataJson: longText(),
+        serverRevision: integer(),
+        toolsJson: longText({ required: true }),
+        policyJson: longText({ required: true }),
+        discoveredAt: text({ required: true }),
+        discoveryHash: text({ required: true }),
+        status: text({ required: true }),
+        createdBy: text({ required: true }),
+        createdAt: text({ required: true }),
+        updatedAt: text({ required: true })
+    }, {
+        indexes: [
+            { columns: ["name"], unique: true },
+            ["status", "name"]
+        ]
+    }),
+    raybaseSystemTable("_agent_remote_mcp_bindings", {
+        id: id(),
+        agentName: text({ required: true }),
+        serverName: text({ required: true }),
+        toolNamesJson: longText({ required: true }),
+        // A binding whose pinned tool disappeared at rediscovery is disabled and
+        // kept, never silently dropped: the operator sees why it stopped.
+        status: text({ required: true }),
+        disabledReason: text(),
+        createdBy: text({ required: true }),
+        createdAt: text({ required: true })
+    }, {
+        indexes: [
+            { columns: ["agentName", "serverName"], unique: true },
+            ["serverName"]
+        ]
+    })
+];
+export function defineRemoteMcpServer(definition) {
+    validateRemoteMcpServerName(definition.name);
+    validateRemoteMcpEndpoint(definition.endpoint);
+    validateRemoteMcpCredential(definition.credentials, definition.name);
+    if (definition.transport !== undefined && definition.transport !== "stateless" && definition.transport !== "sessioned") {
+        throw new Error(`Raybase remote MCP server ${definition.name} transport must be stateless or sessioned`);
+    }
+    validateRemoteMcpTools(definition.name, definition.tools);
+    return {
+        name: definition.name,
+        endpoint: definition.endpoint,
+        ...(definition.transport ? { transport: definition.transport } : {}),
+        ...(definition.credentials ? { credentials: definition.credentials } : {}),
+        tools: Object.fromEntries(Object.entries(definition.tools).map(([toolName, descriptor]) => [toolName, normalizeRemoteMcpToolDescriptor(definition.name, toolName, descriptor)]))
+    };
+}
+export function defineRemoteMcpServers(definitions) {
+    const normalized = {};
+    const seen = new Set();
+    for (const [key, definition] of Object.entries(definitions)) {
+        const name = definition.name || key;
+        validateRemoteMcpServerName(name);
+        if (seen.has(name))
+            throw new Error(`Duplicate Raybase remote MCP server name: ${name}`);
+        seen.add(name);
+        normalized[key] = defineRemoteMcpServer({ ...definition, name });
+    }
+    return normalized;
+}
+export function validateAgentRemoteMcpBindings(agent) {
+    agentRemoteMcpToolBindings(agent);
+}
+export function agentRemoteMcpToolBindings(agent) {
+    const entries = agent.remoteMcpServers ?? [];
+    if (!Array.isArray(entries))
+        throw new Error(`Raybase agent ${agent.name} remoteMcpServers must be an array`);
+    const bindings = [];
+    const seenModelTools = new Map();
+    for (const [index, entry] of entries.entries()) {
+        const binding = normalizeAgentRemoteMcpBinding(agent.name, entry, index);
+        for (const toolName of binding.tools) {
+            const descriptor = binding.server.tools[toolName];
+            if (!descriptor) {
+                throw new Error(`Raybase agent ${agent.name} remote MCP binding for ${binding.server.name} references undeclared tool ${toolName}`);
+            }
+            const modelToolName = remoteMcpModelToolName(binding.server.name, toolName);
+            const existing = seenModelTools.get(modelToolName);
+            if (existing) {
+                throw new Error(`Raybase agent ${agent.name} has duplicate remote MCP runtime tool name "${modelToolName}" from ${existing} and ${binding.server.name}/${toolName}`);
+            }
+            seenModelTools.set(modelToolName, `${binding.server.name}/${toolName}`);
+            bindings.push({ server: binding.server, toolName, descriptor, modelToolName });
+        }
+    }
+    return bindings;
+}
+/**
+ * Model-facing tools for one set of bindings. Callers pass the code-declared
+ * set by default; the runtime-installed resolver passes the installed set so
+ * both sources produce byte-identical tool shapes.
+ */
+export function agentRemoteMcpRuntimeTools(input, bindings = agentRemoteMcpToolBindings(input.agent)) {
+    const audience = input.principal.kind === "public" ? "public" : "signed-in";
+    return bindings
+        .filter((binding) => remoteMcpAudienceAllowsForTool(binding.descriptor, audience, input.principal))
+        .map((binding) => ({
+        name: binding.modelToolName,
+        displayName: `${binding.server.name}/${binding.toolName}`,
+        description: binding.descriptor.description,
+        parameters: binding.descriptor.inputSchema,
+        dataChange: remoteMcpDataChangeDescriptor(binding),
+        run: (args, toolCallId) => runRemoteMcpRuntimeTool({
+            input,
+            binding,
+            args,
+            toolCallId
+        })
+    }));
+}
+export function remoteMcpServerSummaries(servers) {
+    const byName = new Map();
+    for (const server of servers)
+        byName.set(server.name, server);
+    return [...byName.values()]
+        .map((server) => ({
+        name: server.name,
+        endpointHost: remoteMcpEndpointHost(server.endpoint),
+        toolNames: Object.keys(server.tools).sort((left, right) => left.localeCompare(right)),
+        credentialRefs: credentialRefs(server.credentials)
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+export function agentRemoteMcpBindingSummaries(agents) {
+    return agents.flatMap((agent) => {
+        const grouped = new Map();
+        for (const binding of agentRemoteMcpToolBindings(agent)) {
+            grouped.set(binding.server.name, [...(grouped.get(binding.server.name) ?? []), binding]);
+        }
+        return [...grouped.entries()].map(([serverName, bindings]) => ({
+            agentName: agent.name,
+            serverName,
+            toolNames: bindings.map((binding) => binding.toolName).sort((left, right) => left.localeCompare(right)),
+            modelToolNames: bindings.map((binding) => binding.modelToolName).sort((left, right) => left.localeCompare(right))
+        }));
+    });
+}
+export function remoteMcpModelToolName(serverName, toolName) {
+    return `${safeAgentToolSegment(serverName)}__${safeAgentToolSegment(toolName)}`;
+}
+export function validateRemoteMcpEndpoint(endpoint) {
+    try {
+        validateOutboundHttpsUrl(endpoint);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(message.replace(/^Outbound URL/, "Remote MCP endpoint"));
+    }
+}
+export async function callRemoteMcpTool(input) {
+    const timeoutMs = boundedRemoteTimeout(input.descriptor.timeoutMs);
+    const maxResultBytes = boundedRemoteResultBytes(input.descriptor.maxResultBytes);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const abort = () => controller.abort();
+    input.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const stored = input.server.credentials?.type === "stored";
+        const store = stored
+            ? new RemoteMcpCredentialStore(requiredControl(input.control), remoteMcpKeyFromEnv(input.env))
+            : null;
+        const authorization = async () => {
+            if (store) {
+                const resolved = await store.resolveAuthorization(input.server.name);
+                return { header: resolved.header.reveal(), generation: resolved.generation, revision: resolved.revision };
+            }
+            return { header: resolveRemoteMcpCredential(input.server.credentials, input.env), generation: 0 };
+        };
+        let payload;
+        let authRecovery = 0;
+        const recoveryBudget = { sessionRecoveries: 0 };
+        for (;;) {
+            try {
+                if (store) {
+                    const oauth = await store.readOAuth(input.server.name);
+                    if (oauth?.status.state === "ready" && oauth.status.expiresAt && Date.parse(oauth.status.expiresAt) <= Date.now() + 30_000) {
+                        let refreshed;
+                        try {
+                            refreshed = await refreshRemoteMcpOAuth({
+                                control: requiredControl(input.control), key: remoteMcpKeyFromEnv(input.env), serverName: input.server.name,
+                                expectedRevision: oauth.status.revision, fetcher: input.fetcher, signal: controller.signal
+                            });
+                        }
+                        catch (error) {
+                            if (error instanceof RemoteMcpCredentialError) {
+                                const current = await store.status(input.server.name);
+                                if (current?.revision !== oauth.status.revision)
+                                    continue;
+                            }
+                            throw error;
+                        }
+                        if (refreshed.state !== "ready") {
+                            input.sessionCoordinator?.evict(input.server.name);
+                            throw new RemoteMcpRuntimeError("Remote MCP credential needs reconnection", "denied", 401);
+                        }
+                    }
+                }
+                payload = await remoteMcpRequest({
+                    serverName: input.server.name,
+                    endpoint: input.server.endpoint,
+                    transport: input.server.transport,
+                    method: "tools/call",
+                    params: { name: input.toolName, arguments: input.args ?? {} },
+                    authorization,
+                    coordinator: input.sessionCoordinator,
+                    fetcher: input.fetcher,
+                    signal: controller.signal,
+                    timeoutMs,
+                    maxBytes: Math.min(2_000_000, Math.max(maxResultBytes * 4, maxResultBytes + 64_000)),
+                    recoveryBudget
+                });
+                break;
+            }
+            catch (error) {
+                if (store && error instanceof RemoteMcpTransportError && error.httpStatus === 401 && authRecovery === 0) {
+                    const oauth = await store.readOAuth(input.server.name);
+                    if (!oauth || oauth.status.kind !== "oauth")
+                        throw new RemoteMcpRuntimeError("Remote MCP credential was rejected", "denied", 401);
+                    const failedRevision = error.authorization?.revision;
+                    if (failedRevision !== undefined && oauth.status.revision !== failedRevision) {
+                        throw new RemoteMcpRuntimeError("Remote MCP credential changed while the request was in flight; retry the call", "denied", 401);
+                    }
+                    authRecovery += 1;
+                    const refreshed = await refreshRemoteMcpOAuth({
+                        control: requiredControl(input.control), key: remoteMcpKeyFromEnv(input.env), serverName: input.server.name,
+                        expectedRevision: failedRevision, fetcher: input.fetcher, signal: controller.signal
+                    });
+                    if (refreshed.state !== "ready") {
+                        input.sessionCoordinator?.evict(input.server.name);
+                        throw new RemoteMcpRuntimeError("Remote MCP credential needs reconnection", "denied", 401);
+                    }
+                    continue;
+                }
+                if (store && error instanceof RemoteMcpTransportError && error.httpStatus === 401 && authRecovery > 0) {
+                    const failedRevision = error.authorization?.revision;
+                    try {
+                        await store.markReauthRequired(input.server.name, "runtime", failedRevision);
+                    }
+                    catch (transitionError) {
+                        const current = await store.status(input.server.name);
+                        if (failedRevision !== undefined && current?.revision !== failedRevision) {
+                            throw new RemoteMcpRuntimeError("Remote MCP credential changed while the request was in flight; retry the call", "denied", 401);
+                        }
+                        throw transitionError;
+                    }
+                    input.sessionCoordinator?.evict(input.server.name);
+                    throw new RemoteMcpRuntimeError("Remote MCP credential needs reconnection", "denied", 401);
+                }
+                if (error instanceof RemoteMcpTransportError)
+                    throw new RemoteMcpRuntimeError(error.message, error.httpStatus === 401 ? "denied" : "error", error.httpStatus);
+                throw error;
+            }
+        }
+        const bounded = boundRemoteResult(payload, maxResultBytes, input.descriptor.redactionKeys);
+        return {
+            ok: true,
+            server: input.server.name,
+            tool: input.toolName,
+            result: bounded.value,
+            truncated: bounded.truncated
+        };
+    }
+    catch (error) {
+        if (error instanceof RemoteMcpRuntimeError)
+            throw error;
+        if (error instanceof RemoteMcpCredentialError)
+            throw new RemoteMcpRuntimeError(error.message, "denied");
+        if (controller.signal.aborted)
+            throw new RemoteMcpRuntimeError("Remote MCP tool timed out", "timeout");
+        throw new RemoteMcpRuntimeError("Remote MCP tool call failed", "error");
+    }
+    finally {
+        clearTimeout(timeout);
+        input.signal?.removeEventListener("abort", abort);
+    }
+}
+function requiredControl(control) {
+    if (!control)
+        throw new RemoteMcpRuntimeError("Remote MCP stored credentials require the control database", "denied");
+    return control;
+}
+export async function recordAgentRemoteMcpEvent(control, event) {
+    if (!control)
+        return;
+    try {
+        await control.run(`INSERT INTO "_agent_remote_mcp_events" (
+        "id", "agentName", "conversationId", "runId", "requestId", "toolCallId",
+        "principalKind", "userId", "publicScopeHash", "organizationId",
+        "serverName", "remoteToolName", "modelToolName", "endpointHost",
+        "argumentsHash", "argumentsPreviewJson", "resultStatus", "resultPreviewJson",
+        "httpStatus", "latencyMs", "error", "createdAt"
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+            randomId("remote_mcp_event"),
+            event.agentName,
+            event.conversationId,
+            event.runId,
+            event.requestId,
+            event.toolCallId,
+            event.principal.kind,
+            event.principal.kind === "user" ? event.principal.user.id : null,
+            event.principal.kind === "public" ? event.principal.id : null,
+            event.organizationId ?? null,
+            event.serverName,
+            event.remoteToolName,
+            event.modelToolName,
+            remoteMcpEndpointHost(event.endpoint),
+            await sha256Hex(stableJson(redactRemoteMcpValue(event.arguments))),
+            previewJson(event.arguments),
+            event.resultStatus,
+            event.result === undefined ? null : previewJson(event.result),
+            event.httpStatus ?? null,
+            Math.max(0, Math.floor(event.latencyMs)),
+            event.error ?? null,
+            nowIso()
+        ]);
+    }
+    catch {
+        // Remote MCP audit must not make the Agent turn fail if a newly deployed
+        // Durable Object has not applied the manifest table yet.
+    }
+}
+export class RemoteMcpRuntimeError extends Error {
+    status;
+    httpStatus;
+    remoteError;
+    constructor(message, status, httpStatus, remoteError) {
+        super(message);
+        this.status = status;
+        this.httpStatus = httpStatus;
+        this.remoteError = remoteError;
+        this.name = "RemoteMcpRuntimeError";
+    }
+}
+async function runRemoteMcpRuntimeTool(input) {
+    const { descriptor, server, toolName, modelToolName } = input.binding;
+    const started = Date.now();
+    try {
+        assertRemoteMcpPolicyAllows(descriptor, input.input.principal);
+        const result = await callRemoteMcpTool({
+            server,
+            toolName,
+            descriptor,
+            args: input.args,
+            env: input.input.env,
+            control: input.input.control,
+            sessionCoordinator: input.input.remoteMcpSessions,
+            signal: input.input.abortSignal
+        });
+        await recordAgentRemoteMcpEvent(input.input.control, {
+            agentName: input.input.agent.name,
+            conversationId: input.input.conversationId,
+            runId: input.input.runId,
+            requestId: input.input.requestId,
+            toolCallId: input.toolCallId,
+            principal: input.input.principal,
+            organizationId: input.input.organizationId ?? null,
+            serverName: server.name,
+            remoteToolName: toolName,
+            modelToolName,
+            endpoint: server.endpoint,
+            arguments: input.args,
+            resultStatus: "ok",
+            result,
+            latencyMs: Date.now() - started
+        });
+        return result;
+    }
+    catch (error) {
+        const remoteError = error instanceof RemoteMcpRuntimeError ? error : new RemoteMcpRuntimeError("Remote MCP tool call failed", "error");
+        await recordAgentRemoteMcpEvent(input.input.control, {
+            agentName: input.input.agent.name,
+            conversationId: input.input.conversationId,
+            runId: input.input.runId,
+            requestId: input.input.requestId,
+            toolCallId: input.toolCallId,
+            principal: input.input.principal,
+            organizationId: input.input.organizationId ?? null,
+            serverName: server.name,
+            remoteToolName: toolName,
+            modelToolName,
+            endpoint: server.endpoint,
+            arguments: input.args,
+            resultStatus: remoteError.status,
+            httpStatus: remoteError.httpStatus ?? null,
+            latencyMs: Date.now() - started,
+            error: remoteError.message
+        });
+        throw remoteError;
+    }
+}
+function assertRemoteMcpPolicyAllows(descriptor, principal) {
+    if (principal.kind !== "user")
+        return;
+    if (!descriptor.policy || !evaluateActionPolicy(descriptor.policy, principal.user)) {
+        throw new RemoteMcpRuntimeError("Remote MCP tool denied by policy", "denied");
+    }
+}
+function remoteMcpAudienceAllowsForTool(descriptor, audience, principal) {
+    if (!actionAudienceAllows(descriptor.audience, audience))
+        return false;
+    if (principal.kind === "user")
+        return descriptor.policy ? evaluateActionPolicy(descriptor.policy, principal.user) : false;
+    return descriptor.audience === "public" || (Array.isArray(descriptor.audience) && descriptor.audience.includes("public"));
+}
+function remoteMcpDataChangeDescriptor(binding) {
+    if (binding.descriptor.annotations?.readOnlyHint === true)
+        return null;
+    return {
+        actionName: `remoteMcp:${binding.server.name}/${binding.toolName}`,
+        effects: []
+    };
+}
+function normalizeAgentRemoteMcpBinding(agentName, entry, index) {
+    if (!entry || typeof entry !== "object")
+        throw new Error(`Raybase agent ${agentName} remote MCP binding at index ${index} must be an object`);
+    const maybeBinding = entry;
+    const server = "server" in maybeBinding ? maybeBinding.server : entry;
+    if (!server || typeof server !== "object" || typeof server.name !== "string") {
+        throw new Error(`Raybase agent ${agentName} remote MCP binding at index ${index} requires a server`);
+    }
+    if (server.credentials?.type === "stored")
+        throw new Error("Stored remote MCP credentials are internal to runtime-installed servers");
+    const normalizedServer = defineRemoteMcpServer(server);
+    const tools = "server" in maybeBinding ? maybeBinding.tools : Object.keys(normalizedServer.tools);
+    if (!Array.isArray(tools) || tools.length === 0) {
+        throw new Error(`Raybase agent ${agentName} remote MCP binding for ${normalizedServer.name} must allow at least one tool`);
+    }
+    const uniqueTools = Array.from(new Set(tools));
+    if (uniqueTools.length !== tools.length)
+        throw new Error(`Raybase agent ${agentName} remote MCP binding for ${normalizedServer.name} declares duplicate tools`);
+    for (const toolName of uniqueTools) {
+        validateRemoteMcpToolName(toolName, normalizedServer.name);
+        if (!normalizedServer.tools[toolName]) {
+            throw new Error(`Raybase agent ${agentName} remote MCP binding for ${normalizedServer.name} references undeclared tool ${toolName}`);
+        }
+    }
+    return { server: normalizedServer, tools: uniqueTools };
+}
+function validateRemoteMcpTools(serverName, tools) {
+    if (!tools || typeof tools !== "object" || Array.isArray(tools) || Object.keys(tools).length === 0) {
+        throw new Error(`Raybase remote MCP server ${serverName} must declare at least one tool`);
+    }
+    const seen = new Set();
+    for (const [toolName, descriptor] of Object.entries(tools)) {
+        validateRemoteMcpToolName(toolName, serverName);
+        const modelToolName = remoteMcpModelToolName(serverName, toolName);
+        if (seen.has(modelToolName))
+            throw new Error(`Raybase remote MCP server ${serverName} has duplicate runtime tool name "${modelToolName}"`);
+        seen.add(modelToolName);
+        normalizeRemoteMcpToolDescriptor(serverName, toolName, descriptor);
+    }
+}
+function normalizeRemoteMcpToolDescriptor(serverName, toolName, descriptor) {
+    if (!descriptor || typeof descriptor !== "object" || Array.isArray(descriptor)) {
+        throw new Error(`Raybase remote MCP server ${serverName} tool ${toolName} must be an object`);
+    }
+    if (typeof descriptor.description !== "string" || !descriptor.description.trim()) {
+        throw new Error(`Raybase remote MCP server ${serverName} tool ${toolName} requires a description`);
+    }
+    if (!descriptor.inputSchema || typeof descriptor.inputSchema !== "object" || Array.isArray(descriptor.inputSchema)) {
+        throw new Error(`Raybase remote MCP server ${serverName} tool ${toolName} requires an inputSchema`);
+    }
+    if (descriptor.timeoutMs !== undefined && (!Number.isFinite(descriptor.timeoutMs) || descriptor.timeoutMs <= 0)) {
+        throw new Error(`Raybase remote MCP server ${serverName} tool ${toolName} timeoutMs must be positive`);
+    }
+    if (descriptor.maxResultBytes !== undefined && (!Number.isFinite(descriptor.maxResultBytes) || descriptor.maxResultBytes <= 0)) {
+        throw new Error(`Raybase remote MCP server ${serverName} tool ${toolName} maxResultBytes must be positive`);
+    }
+    const audience = descriptor.audience ?? "signed-in";
+    const audiences = Array.isArray(audience) ? audience : [audience];
+    if (audiences.includes("signed-in") && !descriptor.policy) {
+        throw new Error(`Raybase remote MCP server ${serverName} tool ${toolName} requires a policy for signed-in Agent use`);
+    }
+    if (audiences.includes("public") && descriptor.annotations?.readOnlyHint !== true) {
+        throw new Error(`Raybase remote MCP server ${serverName} tool ${toolName} must be explicitly read-only for public Agent use`);
+    }
+    return {
+        ...descriptor,
+        description: descriptor.description.trim(),
+        timeoutMs: descriptor.timeoutMs === undefined ? undefined : Math.floor(descriptor.timeoutMs),
+        maxResultBytes: descriptor.maxResultBytes === undefined ? undefined : Math.floor(descriptor.maxResultBytes)
+    };
+}
+function validateRemoteMcpServerName(name) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/.test(name)) {
+        throw new Error(`Invalid Raybase remote MCP server name "${name}". Use letters, numbers, "_", "-", ".", or ":".`);
+    }
+}
+export function validateRemoteMcpToolName(name, serverName) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/.test(name)) {
+        throw new Error(`Invalid Raybase remote MCP tool name "${name}" on server ${serverName}. Use letters, numbers, "_", "-", ".", or ":".`);
+    }
+}
+function validateRemoteMcpCredential(credential, serverName) {
+    if (credential === undefined)
+        return;
+    if (!credential || typeof credential !== "object" || Array.isArray(credential)) {
+        throw new Error(`Raybase remote MCP server ${serverName} credentials must be an object`);
+    }
+    if (credential.type === "env") {
+        if (!validEnvVarName(credential.envVar))
+            throw new Error(`Raybase remote MCP server ${serverName} credential envVar must be an uppercase env var name`);
+        if (credential.scheme !== undefined && credential.scheme !== "bearer" && credential.scheme !== "raw") {
+            throw new Error(`Raybase remote MCP server ${serverName} credential scheme must be bearer or raw`);
+        }
+        return;
+    }
+    if (credential.type === "secret") {
+        if (typeof credential.name !== "string" || !remoteMcpSecretNamePattern.test(credential.name)) {
+            throw new Error(`Raybase remote MCP server ${serverName} credential name must match RAYBASE_MCP_<NAME>_TOKEN`);
+        }
+        if (credential.scheme !== undefined && credential.scheme !== "bearer" && credential.scheme !== "raw") {
+            throw new Error(`Raybase remote MCP server ${serverName} credential scheme must be bearer or raw`);
+        }
+        return;
+    }
+    if (credential.type === "none")
+        return;
+    if (credential.type === "oauth") {
+        throw new Error(`Raybase remote MCP server ${serverName} uses oauth credentials, which are not implemented in Core v1`);
+    }
+    throw new Error(`Raybase remote MCP server ${serverName} has unsupported credential type`);
+}
+export function resolveRemoteMcpCredential(credential, env) {
+    if (!credential || credential.type === "none")
+        return undefined;
+    if (credential.type === "secret") {
+        // Re-check the closed name space at resolve time: a row edited outside the
+        // install path must never be able to read an arbitrary app binding.
+        if (!remoteMcpSecretNamePattern.test(credential.name)) {
+            throw new RemoteMcpRuntimeError("Remote MCP credential name is outside the RAYBASE_MCP_<NAME>_TOKEN name space", "error");
+        }
+        return authorizationHeader(credential.name, credential.scheme, env);
+    }
+    if (credential.type !== "env")
+        throw new RemoteMcpRuntimeError("Remote MCP credential type is not implemented in Core", "error");
+    return authorizationHeader(credential.envVar, credential.scheme, env);
+}
+function authorizationHeader(name, scheme, env) {
+    const value = env && typeof env === "object" ? env[name] : undefined;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new RemoteMcpRuntimeError(`Remote MCP credential env var ${name} is not configured`, "error");
+    }
+    return scheme === "raw" ? value.trim() : `Bearer ${value.trim()}`;
+}
+function credentialRefs(credential) {
+    if (!credential)
+        return [];
+    if (credential.type === "env")
+        return [credential.envVar];
+    if (credential.type === "secret")
+        return [credential.name];
+    if (credential.type === "stored")
+        return ["stored"];
+    return [];
+}
+function validEnvVarName(value) {
+    return /^[A-Z][A-Z0-9_]{1,127}$/.test(value);
+}
+function remoteMcpEndpointHost(endpoint) {
+    try {
+        return new URL(endpoint).hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+function boundedRemoteTimeout(timeoutMs) {
+    return Math.min(Math.max(Math.floor(timeoutMs ?? 5_000), 100), 30_000);
+}
+function boundedRemoteResultBytes(maxResultBytes) {
+    return Math.min(Math.max(Math.floor(maxResultBytes ?? 16_000), 1_000), 128_000);
+}
+function boundRemoteResult(value, maxBytes, extraRedactionKeys) {
+    const redacted = redactRemoteMcpValue(value, extraRedactionKeys);
+    const json = JSON.stringify(redacted);
+    if (new TextEncoder().encode(json).byteLength <= maxBytes)
+        return { value: redacted, truncated: false };
+    return {
+        value: {
+            truncated: true,
+            preview: json.slice(0, maxBytes)
+        },
+        truncated: true
+    };
+}
+function previewJson(value) {
+    const redacted = redactRemoteMcpValue(value);
+    const json = stableJson(redacted);
+    return json.length > 2_048 ? `${json.slice(0, 2_048)}...` : json;
+}
+function redactRemoteMcpValue(value, extraKeys = []) {
+    if (Array.isArray(value))
+        return value.map((item) => redactRemoteMcpValue(item, extraKeys));
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        isRemoteMcpSensitiveKey(key, extraKeys) ? "[redacted]" : redactRemoteMcpValue(item, extraKeys)
+    ]));
+}
+function isRemoteMcpSensitiveKey(key, extraKeys) {
+    const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const builtIn = new Set([
+        "authorization", "proxyauthorization", "cookie", "setcookie", "token", "accesstoken", "refreshtoken", "idtoken",
+        "secret", "clientsecret", "password", "apikey", "codeverifier", "authorizationcode"
+    ]);
+    return builtIn.has(normalized) || extraKeys.some((candidate) => candidate.toLowerCase().replace(/[^a-z0-9]/g, "") === normalized);
+}
+//# sourceMappingURL=agent-remote-mcp.js.map