Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
54.4 KB
Raw Blame
import { and, eq, isNull } from "@omnirush-ee/den-db/drizzle"
import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js"
import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import {
  OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_KIND,
  OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_SOURCE,
  OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_VERSION,
} from "@omnirush/types/den/mcp-connection-action"
import { normalizeDenTypeId, type DenTypeId } from "@omnirush-ee/utils/typeid"
import {
  getExternalMcpConnection,
  listUsableExternalMcpConnections,
  memberCanUseExternalMcpConnection,
  type ExternalMcpConnectionRow,
} from "../capability-sources/external-mcp-connections.js"
import { callExternalMcpTool, listExternalMcpTools } from "../capability-sources/external-mcp-client-runtime.js"
import {
  EXTERNAL_MCP_TOOL_LIFECYCLE_TIMEOUT_MS,
  createExternalMcpLifecycleDeadline,
  type ExternalMcpLifecycleDeadline,
} from "../capability-sources/external-mcp-client.js"
import {
  ExternalMcpDiagnosticError,
  externalMcpDiagnosticForLog,
  safeExternalMcpEndpointForLog,
  type ExternalMcpDiagnostic,
} from "../capability-sources/external-mcp-diagnostics.js"
import { getConnectedAccount } from "../capability-sources/oauth-credentials.js"
import {
  evaluateToolPolicy,
  isToolDisabled,
} from "../capability-sources/external-mcp-tool-policy.js"
import { cache } from "../cache.js"
import { db } from "../db.js"
import { listTeamsForMember } from "../orgs.js"
import { omnirushOrganizationConnectionsUrl, omnirushYourConnectionsUrl } from "./connection-navigation.js"
import {
  externalMcpToolSchemaDigest,
  validateExternalMcpToolArguments,
  type ExternalMcpArgumentIssue,
} from "./external-mcp-tool-arguments.js"
import { compareCapabilityMatches, tokenize } from "./search.js"
import type { CapabilityMatch } from "./search.js"
import {
  codemodeScriptPath,
  resolveCodemodeConnectionNamespaceContext,
  type CodemodeConnectionNamespaceContext,
} from "./codemode-namespaces.js"
import {
  getExternalToolsSearchCache,
  setExternalToolsSearchCache,
  type ExternalToolsSearchCacheKey,
} from "./external-tools-search-cache.js"

/**
 * Merges org-level External MCP Connections (capability-sources/) into the
 * same search_capabilities/execute_capability surface as the REST-derived
 * catalog (catalog.ts), without touching that catalog or the rich `/mcp`
 * endpoint at all. A connected external tool is namespaced
 * `mcp:<connectionId>:<toolName>` so execute_capability can tell it apart
 * from a REST operation name and dispatch to the real MCP client
 * (external-mcp-client.ts) instead of invokeMcpOperation.
 *
 * Everything here is scoped to the CALLING MEMBER, not just the org:
 * - Only connections the member has been granted (org-wide, direct, or via
 *   a team) are searchable/executable. Access is never implicit.
 * - For credentialMode "per_member" connections, calls run with the
 *   member's own connected account; if they haven't connected one yet,
 *   search surfaces the connection as needs_connection (so the agent can
 *   tell the human what to do) instead of silently hiding it.
 */

const EXTERNAL_CAPABILITY_PREFIX = "mcp:"
export const EXTERNAL_MCP_SEARCH_CONNECTION_LIMIT = 16
export const EXTERNAL_MCP_SEARCH_CONCURRENCY = 8
export const EXTERNAL_MCP_SEARCH_MATCH_LIMIT = 20
const EXTERNAL_MCP_SEARCH_REQUEST_TIMEOUT_MS = 5_000
const EXTERNAL_MCP_SEARCH_LIFECYCLE_TIMEOUT_MS = 8_000

export function buildExternalCapabilityName(connectionId: string, toolName: string): string {
  return `${EXTERNAL_CAPABILITY_PREFIX}${connectionId}:${toolName}`
}

export function parseExternalCapabilityName(name: string): { connectionId: string; toolName: string } | null {
  if (!name.startsWith(EXTERNAL_CAPABILITY_PREFIX)) return null
  const rest = name.slice(EXTERNAL_CAPABILITY_PREFIX.length)
  const separatorIndex = rest.indexOf(":")
  if (separatorIndex <= 0) return null
  return {
    connectionId: rest.slice(0, separatorIndex),
    toolName: rest.slice(separatorIndex + 1),
  }
}

export type McpMemberIdentity = {
  orgMembershipId: DenTypeId<"member">
  teamIds: DenTypeId<"team">[]
}

/**
 * Resolves the MCP principal (userId + organizationId from the bearer
 * token) to the member identity the grant checks need. Returns null when
 * the user has no active membership — callers should treat that as
 * zero external-capability access, not an error.
 */
export async function resolveMcpMemberIdentity(input: {
  userId: string
  organizationId: string
}): Promise<McpMemberIdentity | null> {
  const organizationId = normalizeDenTypeId("organization", input.organizationId)
  const member = await cache.org.membership({
    organizationId,
    userId: normalizeDenTypeId("user", input.userId),
  })
  if (!member) return null
  const teams = await listTeamsForMember({ organizationId, memberId: member.id })
  return { orgMembershipId: member.id, teamIds: teams.map((team) => team.id) }
}

function hasSharedCredential(connection: ExternalMcpConnectionRow): boolean {
  if (connection.oauthIssuerReviewRequiredAt) return false
  if (connection.authType === "oauth") return Boolean(connection.accessToken)
  if (connection.authType === "apikey") return Boolean(connection.apiKey)
  return true
}

function redirectUriFor(redirectUriBase: string, connectionId: string): string {
  return `${redirectUriBase}/v1/mcp-connections/${encodeURIComponent(connectionId)}/connect/callback`
}

function scoreText(nameTokens: string[], summaryTokens: string[], queryTokens: string[]): number {
  let score = 0
  for (const queryToken of queryTokens) {
    if (nameTokens.includes(queryToken)) {
      score += 5
    } else if (nameTokens.some((token) => token.startsWith(queryToken) || queryToken.startsWith(token))) {
      score += 3
    }
    if (summaryTokens.includes(queryToken)) {
      score += 2
    }
  }
  return score
}

/**
 * A capability search must never turn an unbounded org connection list into
 * unbounded remote handshakes. Prefer connections whose names match the
 * query, keep source order as the deterministic tiebreaker, and enforce one
 * hard fanout ceiling before any provider network request is started.
 */
export function selectExternalMcpSearchConnections<T extends { name: string }>(
  connections: readonly T[],
  queryTokens: string[],
  limit = EXTERNAL_MCP_SEARCH_CONNECTION_LIMIT,
): T[] {
  return connections
    .map((connection, index) => ({
      connection,
      index,
      score: scoreText(tokenize(connection.name), tokenize(connection.name), queryTokens),
    }))
    .sort((left, right) => right.score - left.score || left.index - right.index)
    .slice(0, Math.max(0, Math.min(limit, EXTERNAL_MCP_SEARCH_CONNECTION_LIMIT)))
    .map(({ connection }) => connection)
}

export type ExternalCapabilityMatch = CapabilityMatch & {
  /** Exact MCP arguments schema returned by the provider's live tools/list. */
  argumentsSchema?: unknown
  /** Stable digest used to detect a schema change between search and execute. */
  schemaDigest?: string
  /** Tells the generic execute facade where MCP arguments must be supplied. */
  invocation?: { argumentsField: "body" }
  /** Distinguishes a connection-health result from a callable capability. */
  kind?: "connection_status" | "mcp_app"
  /** Set for connection-level status rows: the tool exists but needs a human/admin fix before real tools can be listed. */
  status?: "needs_connection" | "error"
  hint?: string
  connectionStatus?: ExternalConnectionStatus
}

export type ExternalMcpAppLaunch = {
  connectionId: string
  toolName: string
  resourceUri: string
  arguments: Record<string, unknown>
}

export type ExternalConnectionStatus = {
  version: typeof OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_VERSION
  kind: typeof OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_KIND
  source: typeof OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_SOURCE
  layer: "mcp_connection" | "downstream_provider"
  connectionId: string
  connectionName: string
  authType: "oauth" | "apikey" | "none"
  credentialMode: "shared" | "per_member"
  state: "needs_connection" | "reauth_required" | "provider_error"
  errorCode: "not_connected" | "invalid_refresh_token" | "invalid_grant" | "unauthorized" | "provider_error"
  message: string
  actor: ExternalMcpDiagnostic["actionOwner"]
  action: {
    type: "connect" | "reconnect" | "update_credentials" | "inspect_connection" | "fix_provider" | "fix_network" | "contact_omnirush"
    label: string
    surface: "omnirush_your_connections" | "omnirush_organization_connections" | "provider_admin_console" | "network_infrastructure" | "omnirush_support"
    retry: "search_capabilities"
    url?: string
  }
}

type ConnectionStatusIdentity = {
  id: string
  name: string
  authType: ExternalConnectionStatus["authType"]
  credentialMode: ExternalConnectionStatus["credentialMode"]
}

const ERROR_MESSAGE_LIMIT = 300
const LIVE_PROBE_HINT = "This is a live probe, not a cached result — repeating the same search without changing anything will return the same error."
const INVALID_REFRESH_TOKEN_PATTERN = /\binvalid[ _-]?refresh[ _-]?token\b/i
const INVALID_GRANT_PATTERN = /\binvalid[ _-]?grant\b/i
const UNAUTHORIZED_PATTERN = /\b(?:unauthori[sz]ed|invalid[ _-]?token|token (?:is )?expired|expired (?:access )?token)\b/i
const PROVIDER_ADMIN_ACTION_PATTERN = /\b(?:app (?:is )?not installed|admin(?:istrator)? (?:consent|approval)|approval required)\b/i

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value)
}

export function externalMcpAppResourceUri(tool: { _meta?: unknown }): string | null {
  const meta = isRecord(tool._meta) ? tool._meta : {}
  const ui = isRecord(meta.ui) ? meta.ui : {}
  const resourceUri = typeof ui.resourceUri === "string"
    ? ui.resourceUri
    : typeof meta["ui/resourceUri"] === "string"
      ? meta["ui/resourceUri"]
      : null
  return resourceUri?.startsWith("ui://") ? resourceUri : null
}

function cappedErrorMessage(message: string): string {
  return message.length > ERROR_MESSAGE_LIMIT ? `${message.slice(0, ERROR_MESSAGE_LIMIT)}...` : message
}

function parsedErrorMessage(value: unknown): string | null {
  if (!isRecord(value)) return null
  const nestedError = value.error
  if (isRecord(nestedError) && typeof nestedError.message === "string") {
    return typeof nestedError.code === "number"
      ? `${nestedError.message} (JSON-RPC ${nestedError.code})`
      : nestedError.message
  }
  if (typeof value.message === "string") return value.message
  if (typeof nestedError === "string") return nestedError
  return null
}

function errorCauseChain(error: unknown): unknown[] {
  const chain: unknown[] = []
  let current: unknown = error
  for (let depth = 0; depth < 6; depth += 1) {
    chain.push(current)
    if (!isRecord(current) || !("cause" in current) || current.cause === undefined) break
    current = current.cause
  }
  return chain
}

export function upstreamErrorMessage(error: unknown): string {
  const chain = errorCauseChain(error)
  const diagnosticError = chain.find((current) => current instanceof ExternalMcpDiagnosticError)
  if (diagnosticError instanceof ExternalMcpDiagnosticError) return diagnosticError.diagnostic.message
  for (const current of [...chain].reverse()) {
    const message = current instanceof Error ? current.message : String(current)
    const jsonStart = message.indexOf("{")
    if (jsonStart >= 0) {
      try {
        const parsed: unknown = JSON.parse(message.slice(jsonStart))
        const parsedMessage = parsedErrorMessage(parsed)
        if (parsedMessage) return parsedMessage
      } catch {
        // Try the next cause when the SDK wrapper contains partial or invalid JSON.
      }
    }
    if (message.trim()) return cappedErrorMessage(message)
  }
  return "Unknown MCP provider error."
}

export function externalMcpAuthErrorCode(
  error: unknown,
  message = upstreamErrorMessage(error),
): ExternalConnectionStatus["errorCode"] | null {
  const diagnosticError = errorCauseChain(error)
    .find((current) => current instanceof ExternalMcpDiagnosticError)
  if (diagnosticError instanceof ExternalMcpDiagnosticError) {
    if (diagnosticError.diagnostic.code === "MCP_OAUTH_INVALID_GRANT") return "invalid_grant"
    if (
      diagnosticError.diagnostic.phase === "AUTH_TOKEN_ACQUISITION"
      || diagnosticError.diagnostic.phase === "AUTH_RESOURCE_VALIDATION"
      || diagnosticError.diagnostic.phase === "CONTINUITY_REFRESH"
    ) return "unauthorized"
  }
  if (INVALID_REFRESH_TOKEN_PATTERN.test(message)) return "invalid_refresh_token"
  if (INVALID_GRANT_PATTERN.test(message)) return "invalid_grant"
  if (
    errorCauseChain(error).some((current) => (
      current instanceof UnauthorizedError
      || (current instanceof StreamableHTTPError && (current.code === 401 || current.code === 403))
    ))
    || UNAUTHORIZED_PATTERN.test(message)
  ) return "unauthorized"
  return null
}

export function isExternalMcpAuthError(error: unknown): boolean {
  return externalMcpAuthErrorCode(error) !== null
}

export function externalConnectionErrorHint(
  connectionName: string,
  error: unknown,
  message = upstreamErrorMessage(error),
  credentialMode: ExternalMcpConnectionRow["credentialMode"] = "shared",
): string {
  if (error instanceof ExternalMcpDiagnosticError) {
    return `${error.diagnostic.message} Ask the named action owner to inspect this layer. ${error.diagnostic.operatorAction} Diagnostic reference: ${error.diagnostic.referenceId}. ${LIVE_PROBE_HINT}`
  }
  if (externalMcpAuthErrorCode(error, message)) {
    const destination = credentialMode === "per_member"
      ? "OmniRush.ai Cloud -> Your Connections"
      : "the OmniRush.ai Cloud dashboard -> Connections"
    return `The stored credential for "${connectionName}" is invalid or expired. Reconnect "${connectionName}" from ${destination}, then search again. OmniRush.ai Cloud itself is still connected. ${LIVE_PROBE_HINT}`
  }
  if (PROVIDER_ADMIN_ACTION_PATTERN.test(message)) {
    return `The provider's server rejected the request for "${connectionName}": ${message}. A provider admin must fix it in the provider's own admin console, then search again. OmniRush.ai Cloud itself is still connected. ${LIVE_PROBE_HINT}`
  }
  return `The downstream provider for "${connectionName}" returned an error: ${message}. Ask an org admin to inspect "${connectionName}" in the OmniRush.ai Cloud dashboard -> Connections, then search again. OmniRush.ai Cloud itself is still connected. ${LIVE_PROBE_HINT}`
}

function diagnosticConnectionAction(input: {
  connection: Pick<ExternalMcpConnectionRow, "authType">
  state: ExternalConnectionStatus["state"]
  diagnostic: ExternalMcpDiagnostic
}): Pick<ExternalConnectionStatus, "actor" | "action"> {
  const actor = input.diagnostic.actionOwner
  let type: ExternalConnectionStatus["action"]["type"]
  let surface: ExternalConnectionStatus["action"]["surface"]
  if (actor === "omnirush") {
    type = "contact_omnirush"
    surface = "omnirush_support"
  } else if (actor === "network_admin") {
    type = "fix_network"
    surface = "network_infrastructure"
  } else if (actor === "provider_admin") {
    type = "fix_provider"
    surface = "provider_admin_console"
  } else if (actor === "member") {
    type = input.state === "needs_connection" ? "connect" : "reconnect"
    surface = "omnirush_your_connections"
  } else {
    type = input.state === "reauth_required"
      ? input.connection.authType === "apikey" ? "update_credentials" : "reconnect"
      : "inspect_connection"
    surface = "omnirush_organization_connections"
  }
  return {
    actor,
    action: {
      type,
      surface,
      label: input.diagnostic.operatorAction,
      retry: "search_capabilities",
    },
  }
}

function actionNavigationUrl(input: {
  connectionId: string
  surface: ExternalConnectionStatus["action"]["surface"]
}) {
  if (input.surface === "omnirush_your_connections") return omnirushYourConnectionsUrl(input.connectionId)
  if (input.surface === "omnirush_organization_connections") return omnirushOrganizationConnectionsUrl()
  return undefined
}

function addConnectionActionUrl(input: {
  action: ExternalConnectionStatus["action"]
  connectionId: string
}): ExternalConnectionStatus["action"] {
  const url = actionNavigationUrl({ connectionId: input.connectionId, surface: input.action.surface })
  return url ? { ...input.action, url } : input.action
}

function relayableProviderConnectUrl(connectUrl: string | undefined, connectionUrl: string): string | undefined {
  if (!connectUrl) return undefined
  try {
    const candidate = new URL(connectUrl)
    const connection = new URL(connectionUrl)
    if (candidate.host !== connection.host) return undefined
    return candidate.protocol === "http:" || candidate.protocol === "https:" ? candidate.toString() : undefined
  } catch {
    return undefined
  }
}

function providerAuthorizationDiagnosticForConnection(input: {
  diagnostic: ExternalMcpDiagnostic
  connectionUrl: string
}): ExternalMcpDiagnostic {
  if (!input.diagnostic.connectUrl) return input.diagnostic
  const connectUrl = relayableProviderConnectUrl(input.diagnostic.connectUrl, input.connectionUrl)
  if (!connectUrl) {
    const diagnostic = { ...input.diagnostic }
    delete diagnostic.connectUrl
    return diagnostic
  }
  return connectUrl === input.diagnostic.connectUrl
    ? input.diagnostic
    : { ...input.diagnostic, connectUrl }
}

function providerAuthorizationConnectionStatus(input: {
  connection: Pick<ExternalMcpConnectionRow, "id" | "name" | "authType" | "credentialMode">
  diagnostic: ExternalMcpDiagnostic
  message: string
}): ExternalConnectionStatus {
  const status = buildExternalConnectionStatus({
    connection: input.connection,
    state: "needs_connection",
    errorCode: "not_connected",
    message: input.message,
    diagnostic: input.diagnostic,
    actionOwner: "member",
    layer: "downstream_provider",
  })
  return {
    ...status,
    actor: "member",
    action: {
      type: "connect",
      label: "Connect your provider account",
      surface: "omnirush_your_connections",
      retry: "search_capabilities",
      ...(input.diagnostic.connectUrl ? { url: input.diagnostic.connectUrl } : {}),
    },
  }
}

export function buildExternalConnectionStatus(input: {
  connection: ConnectionStatusIdentity
  state: ExternalConnectionStatus["state"]
  errorCode: ExternalConnectionStatus["errorCode"]
  message: string
  diagnostic?: ExternalMcpDiagnostic
  actionOwner?: "member" | "organization_admin"
  layer?: ExternalConnectionStatus["layer"]
}): ExternalConnectionStatus {
  const connectionName = input.connection.name
  const actionContract = {
    version: OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_VERSION,
    kind: OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_KIND,
    source: OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_SOURCE,
  } as const
  // Once the failure is classified as reauthentication, credential ownership
  // is the source of truth for who can repair it. A generic HTTP 400 during a
  // refresh may classify the raw diagnostic as provider_admin, but routing a
  // per-member expired token to a provider console contradicts the
  // reauth_required state and prevents the client from offering reconnect.
  const diagnosticAction = input.diagnostic && input.state !== "reauth_required"
    ? diagnosticConnectionAction({ connection: input.connection, state: input.state, diagnostic: input.diagnostic })
    : null
  if (input.state === "provider_error") {
    const providerAdminAction = PROVIDER_ADMIN_ACTION_PATTERN.test(input.message)
    return {
      ...actionContract,
      layer: input.layer ?? (input.diagnostic ? "mcp_connection" : "downstream_provider"),
      connectionId: input.connection.id,
      connectionName,
      authType: input.connection.authType,
      credentialMode: input.connection.credentialMode,
      state: input.state,
      errorCode: input.errorCode,
      message: input.message,
      actor: diagnosticAction?.actor ?? (providerAdminAction ? "provider_admin" : "organization_admin"),
      action: diagnosticAction
        ? addConnectionActionUrl({ action: diagnosticAction.action, connectionId: input.connection.id })
        : addConnectionActionUrl({
          connectionId: input.connection.id,
          action: {
            type: providerAdminAction ? "fix_provider" : "inspect_connection",
            label: providerAdminAction
              ? `Fix ${connectionName} in the provider admin console`
              : `Inspect the ${connectionName} connection`,
            surface: providerAdminAction ? "provider_admin_console" : "omnirush_organization_connections",
            retry: "search_capabilities",
          },
        }),
    }
  }

  const actor = input.actionOwner
    ?? (input.connection.credentialMode === "per_member" ? "member" : "organization_admin")
  const surface = actor === "member"
    ? "omnirush_your_connections"
    : "omnirush_organization_connections"
  const actionType = input.state === "needs_connection"
    ? "connect"
    : input.connection.authType === "oauth"
      ? "reconnect"
      : input.connection.authType === "apikey"
        ? "update_credentials"
        : "inspect_connection"
  const actionVerb = actionType === "connect"
    ? "Connect"
    : actionType === "reconnect"
      ? "Reconnect"
      : actionType === "update_credentials"
        ? "Update credentials for"
        : "Inspect"
  return {
    ...actionContract,
    layer: input.layer ?? (input.diagnostic ? "mcp_connection" : "downstream_provider"),
    connectionId: input.connection.id,
    connectionName,
    authType: input.connection.authType,
    credentialMode: input.connection.credentialMode,
    state: input.state,
    errorCode: input.errorCode,
    message: input.message,
    actor: diagnosticAction?.actor ?? actor,
    action: diagnosticAction
      ? addConnectionActionUrl({ action: diagnosticAction.action, connectionId: input.connection.id })
      : addConnectionActionUrl({
        connectionId: input.connection.id,
        action: {
          type: actionType,
          label: `${actionVerb} ${connectionName}`,
          surface,
          retry: "search_capabilities",
        },
      }),
  }
}

function statusMatch(input: {
  connection: ExternalMcpConnectionRow
  score: number
  summary: string
  status: ExternalCapabilityMatch["status"]
  hint: string
  connectionStatus: ExternalConnectionStatus
}): ExternalCapabilityMatch {
  return {
    name: buildExternalCapabilityName(input.connection.id, "*"),
    method: "MCP",
    path: input.connection.url,
    score: input.score,
    summary: input.summary,
    pathParams: [],
    queryParams: [],
    hasBody: false,
    kind: "connection_status",
    status: input.status,
    hint: input.hint,
    connectionStatus: input.connectionStatus,
  }
}

export function mergeBoundedExternalCapabilityMatches(
  retained: ExternalCapabilityMatch[],
  candidates: readonly ExternalCapabilityMatch[],
  limit: number,
): ExternalCapabilityMatch[] {
  const boundedLimit = Number.isFinite(limit)
    ? Math.max(0, Math.min(Math.floor(limit), EXTERNAL_MCP_SEARCH_MATCH_LIMIT))
    : 0
  if (boundedLimit === 0) {
    retained.splice(0)
    return retained
  }
  for (const candidate of candidates) {
    retained.push(candidate)
    retained.sort(compareCapabilityMatches)
    if (retained.length > boundedLimit) retained.splice(boundedLimit)
  }
  return retained
}

export async function collectBoundedExternalMcpSearchMatches<T>(input: {
  connections: readonly T[]
  deadline: ExternalMcpLifecycleDeadline
  limit: number
  concurrency?: number
  probe: (connection: T, deadline: ExternalMcpLifecycleDeadline) => Promise<ExternalCapabilityMatch[]>
}): Promise<ExternalCapabilityMatch[]> {
  const retained: ExternalCapabilityMatch[] = []
  const boundedLimit = Number.isFinite(input.limit)
    ? Math.max(0, Math.min(Math.floor(input.limit), EXTERNAL_MCP_SEARCH_MATCH_LIMIT))
    : 0
  if (boundedLimit === 0 || input.connections.length === 0) return retained

  const concurrency = Math.max(1, Math.min(
    Math.floor(input.concurrency ?? EXTERNAL_MCP_SEARCH_CONCURRENCY),
    EXTERNAL_MCP_SEARCH_CONCURRENCY,
    input.connections.length,
  ))
  let nextIndex = 0
  let acceptingResults = true
  const worker = async () => {
    while (Date.now() < input.deadline.expiresAt) {
      const index = nextIndex
      nextIndex += 1
      if (index >= input.connections.length) return
      const candidates = await input.probe(input.connections[index]!, input.deadline)
      if (acceptingResults) mergeBoundedExternalCapabilityMatches(retained, candidates, boundedLimit)
    }
  }
  const workers = Promise.all(Array.from({ length: concurrency }, () => worker()))
  const remaining = Math.max(0, input.deadline.expiresAt - Date.now())
  let deadlineTimer: ReturnType<typeof setTimeout> | undefined
  const deadlineReached = new Promise<void>((resolve) => {
    deadlineTimer = setTimeout(resolve, remaining)
  })
  try {
    await Promise.race([workers, deadlineReached])
  } finally {
    acceptingResults = false
    if (deadlineTimer) clearTimeout(deadlineTimer)
    // Active MCP requests receive the same absolute deadline and abort their
    // fetch at this point. Keep a rejection observer on the worker pool for
    // the smaller class of non-fetch operations that cannot be cancelled.
    void workers.catch(() => undefined)
  }
  return retained
}

export type ExternalMcpSearchCoverage = {
  eligibleConnections: number
  probedConnections: number
  truncated: boolean
}

export function externalMcpSearchCoverageHint(coverage: ExternalMcpSearchCoverage): string | undefined {
  if (!coverage.truncated) return undefined
  return `External MCP search inspected ${coverage.probedConnections} of ${coverage.eligibleConnections} eligible connections. Results may be incomplete; narrow the query using a connection name and search again.`
}

const CONNECTION_CARD_HINT = "Execute this exact capability name once: it returns the live status, renders an actionable connection card for the member in compatible hosts, and includes the action to relay in text."

async function probeExternalMcpConnection(input: {
  connection: ExternalMcpConnectionRow
  member: McpMemberIdentity
  queryTokens: string[]
  redirectUriBase: string
  limit: number
  deadline: ExternalMcpLifecycleDeadline
  scriptNamespace?: string
}): Promise<ExternalCapabilityMatch[]> {
  const matches: ExternalCapabilityMatch[] = []
  const add = (match: ExternalCapabilityMatch) => {
    mergeBoundedExternalCapabilityMatches(matches, [match], input.limit)
  }
  const connection = input.connection
  if (connection.toolPolicy?.allDisabled) return matches
  if (connection.oauthIssuerReviewRequiredAt) {
    const nameTokens = tokenize(connection.name)
    const score = scoreText(nameTokens, nameTokens, input.queryTokens)
    if (score > 0) {
      const message = `${connection.name} is blocked until an organization admin reviews its changed OAuth issuer.`
      add(statusMatch({
        connection,
        score,
        summary: `[${connection.name}] OAuth provider settings changed and require administrator review.`,
        status: "error",
        hint: `Ask an org admin to open OmniRush.ai Cloud -> Connectors, review the live OAuth issuer for "${connection.name}", and reconnect if requested. ${CONNECTION_CARD_HINT}`,
        connectionStatus: buildExternalConnectionStatus({
          connection,
          state: "reauth_required",
          errorCode: "unauthorized",
          message,
          actionOwner: "organization_admin",
        }),
      }))
    }
    return matches
  }
  if (connection.credentialMode === "per_member") {
    const account = await getConnectedAccount({
      organizationId: connection.organizationId,
      orgMembershipId: input.member.orgMembershipId,
      providerId: connection.id,
    })
    if (!account?.accessToken) {
      // Granted but not yet connected: surface the connection itself (not
      // its tools — we can't list them without the member's credential) so
      // the agent can tell the human exactly what to do.
      const nameTokens = tokenize(connection.name)
      const score = scoreText(nameTokens, nameTokens, input.queryTokens)
      if (score > 0) {
        const message = `You haven't connected your ${connection.name} account yet.`
        add(statusMatch({
          connection,
          score,
          summary: `[${connection.name}] Available to you, but you haven't connected your ${connection.name} account yet.`,
          status: "needs_connection",
          hint: `Ask the user to click Connect on the "${connection.name}" card in OmniRush.ai desktop, then search again. In clients without inline connection controls, use OmniRush.ai Cloud -> Your Connections. ${CONNECTION_CARD_HINT}`,
          connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
        }))
      }
      return matches
    }
  } else if (!hasSharedCredential(connection)) {
    const nameTokens = tokenize(connection.name)
    const score = scoreText(nameTokens, nameTokens, input.queryTokens)
    if (score > 0) {
      const message = `${connection.name} is not connected yet.`
      add(statusMatch({
        connection,
        score,
        summary: `[${connection.name}] Available to your organization, but an admin hasn't connected it yet.`,
        status: "needs_connection",
        hint: `Ask an org admin to open the OmniRush.ai Cloud dashboard -> Connections and connect "${connection.name}", then search again. ${CONNECTION_CARD_HINT}`,
        connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
      }))
    }
    return matches
  }

  const member = connection.credentialMode === "per_member"
    ? { orgMembershipId: input.member.orgMembershipId }
    : undefined
  let tools: Awaited<ReturnType<typeof listExternalMcpTools>>
  const cacheKey: ExternalToolsSearchCacheKey = {
    organizationId: connection.organizationId,
    connectionId: connection.id,
    updatedAt: connection.updatedAt,
    credentialMode: connection.credentialMode,
    ...(connection.credentialMode === "per_member" ? { orgMembershipId: input.member.orgMembershipId } : {}),
  }
  const cachedProbe = getExternalToolsSearchCache(cacheKey)
  try {
    if (cachedProbe?.outcome === "failure") throw cachedProbe.error
    if (cachedProbe?.outcome === "success") {
      tools = cachedProbe.tools
    } else {
      tools = await listExternalMcpTools(
        connection,
        redirectUriFor(input.redirectUriBase, connection.id),
        member,
        undefined,
        input.deadline,
        EXTERNAL_MCP_SEARCH_REQUEST_TIMEOUT_MS,
      )
      setExternalToolsSearchCache(cacheKey, { outcome: "success", tools })
    }
  } catch (error) {
    if (!cachedProbe) setExternalToolsSearchCache(cacheKey, { outcome: "failure", error })
    const message = upstreamErrorMessage(error)
    const diagnostic = error instanceof ExternalMcpDiagnosticError ? error.diagnostic : undefined
    const nameTokens = tokenize(connection.name)
    const score = scoreText(nameTokens, nameTokens, input.queryTokens)
    if (score > 0) {
      if (diagnostic) {
        console.error("external_mcp_capability_search_probe_failed", {
          connectionId: connection.id,
          organizationId: connection.organizationId,
          connectionEndpoint: safeExternalMcpEndpointForLog(connection.url),
          ...externalMcpDiagnosticForLog(error, diagnostic.referenceId, "MCP_TOOL_DISCOVERY"),
        })
      }
      const authErrorCode = externalMcpAuthErrorCode(error, message)
      const state = authErrorCode ? "reauth_required" : "provider_error"
      add(statusMatch({
        connection,
        score,
        summary: `[${connection.name}] This connection is set up but returned an error (${message}).`,
        status: "error",
        hint: `${externalConnectionErrorHint(connection.name, error, message, connection.credentialMode)} ${CONNECTION_CARD_HINT}`,
        connectionStatus: buildExternalConnectionStatus({
          connection,
          state,
          errorCode: authErrorCode ?? "provider_error",
          message,
          diagnostic,
        }),
      }))
    }
    return matches
  }

  for (const tool of tools) {
    if (isToolDisabled(connection.toolPolicy, tool.name)) continue
    const summary = tool.description ?? tool.title ?? tool.name
    const nameTokens = tokenize(`${connection.name} ${tool.name}`)
    const summaryTokens = tokenize(summary)
    const score = scoreText(nameTokens, summaryTokens, input.queryTokens)
    if (score <= 0) continue
    const resourceUri = externalMcpAppResourceUri(tool)
    add({
      name: buildExternalCapabilityName(connection.id, tool.name),
      method: "MCP",
      path: connection.url,
      score,
      summary: `[${connection.name}] ${summary}`,
      pathParams: [],
      queryParams: [],
      hasBody: true,
      argumentsSchema: tool.inputSchema,
      schemaDigest: externalMcpToolSchemaDigest(tool.inputSchema),
      invocation: { argumentsField: "body" },
      ...(resourceUri ? { kind: "mcp_app" as const, mcpApp: { resourceUri } } : {}),
      ...(input.scriptNamespace ? { scriptPath: codemodeScriptPath(input.scriptNamespace, tool.name) } : {}),
    })
  }
  return matches
}

/**
 * Live-lists tools for a bounded set of external MCP connections the calling
 * member has been granted. All probes share one absolute deadline and run in
 * a small worker pool; one unreachable server cannot serialize the latency of
 * every other provider or let matches grow beyond the requested top-K.
 */
export async function searchExternalCapabilities(input: {
  organizationId: string
  member: McpMemberIdentity | null
  query: string
  redirectUriBase: string
  limit?: number
  namespaceContext?: CodemodeConnectionNamespaceContext
  reportCoverage?: (coverage: ExternalMcpSearchCoverage) => void
}): Promise<ExternalCapabilityMatch[]> {
  if (!input.member) return []
  const queryTokens = tokenize(input.query)
  if (queryTokens.length === 0) return []
  const requestedLimit = input.limit ?? 5
  if (!Number.isFinite(requestedLimit) || requestedLimit <= 0) return []
  const limit = Math.min(Math.max(1, Math.trunc(requestedLimit)), EXTERNAL_MCP_SEARCH_MATCH_LIMIT)
  const deadline = createExternalMcpLifecycleDeadline(EXTERNAL_MCP_SEARCH_LIFECYCLE_TIMEOUT_MS)
  const namespaceContext = input.namespaceContext ?? await resolveCodemodeConnectionNamespaceContext({
    organizationId: input.organizationId,
    member: input.member,
  })
  const connections = namespaceContext?.externalMcpConnections ?? await listUsableExternalMcpConnections({
    organizationId: normalizeDenTypeId("organization", input.organizationId),
    orgMembershipId: input.member.orgMembershipId,
    teamIds: input.member.teamIds,
  })
  const scriptNamespaces = namespaceContext?.namespaces.externalMcp
  const selectedConnections = selectExternalMcpSearchConnections(connections, queryTokens)
  input.reportCoverage?.({
    eligibleConnections: connections.length,
    probedConnections: selectedConnections.length,
    truncated: selectedConnections.length < connections.length,
  })
  return await collectBoundedExternalMcpSearchMatches({
    connections: selectedConnections,
    deadline,
    limit,
    probe: (connection, sharedDeadline) => probeExternalMcpConnection({
      connection,
      member: input.member!,
      queryTokens,
      redirectUriBase: input.redirectUriBase,
      limit,
      deadline: sharedDeadline,
      scriptNamespace: scriptNamespaces?.get(connection.id),
    }),
  })
}

export type ExternalMcpSchemaWarning =
  | {
      code: "arguments_schema_mismatch"
      message: string
      issues: ExternalMcpArgumentIssue[]
      suggestedAction: string
    }
  | {
      code: "arguments_schema_unavailable"
      message: string
      suggestedAction: string
    }
  | {
      code: "capability_schema_changed"
      message: string
      searchedSchemaDigest: string
      currentSchemaDigest: string
      suggestedAction: string
    }

export type ExternalMcpSchemaGuidance = {
  advisory: true
  providerCallAttempted: true
  message: string
  warnings: ExternalMcpSchemaWarning[]
}

export type ExternalCapabilityExecuteResult =
  | {
      ok: true
      result: Awaited<ReturnType<typeof callExternalMcpTool>>
      schemaGuidance?: ExternalMcpSchemaGuidance
      mcpApp?: ExternalMcpAppLaunch
    }
  | {
      ok: false
      error:
        | "unknown_capability"
        | "forbidden"
        | "connection_not_connected"
        | "needs_connection"
        | "connection_failed"
        | "provider_error"
        | "invalid_capability_arguments"
        | "policy_blocked"
      message: string
      referenceId?: string
      retryable?: boolean
      providerError?: ExternalMcpProviderError
      connectionStatus?: ExternalConnectionStatus
      capability?: string
      issues?: ExternalMcpArgumentIssue[]
      schemaDigest?: string
      sameArgumentsRetryable?: false
      retry?: {
        action: "correct_arguments" | "search_capabilities"
        searchRequired: boolean
      }
      schemaGuidance?: ExternalMcpSchemaGuidance
    }

export type ExternalMcpProviderError = {
  jsonRpcCode?: number
  message?: string
  data?: string
}

function providerErrorFromDiagnostic(diagnostic: ExternalMcpDiagnostic): ExternalMcpProviderError | undefined {
  if (
    diagnostic.jsonRpcCode === undefined
    && !diagnostic.providerErrorMessage
    && !diagnostic.providerErrorData
  ) return undefined
  return {
    ...(diagnostic.jsonRpcCode === undefined ? {} : { jsonRpcCode: diagnostic.jsonRpcCode }),
    ...(diagnostic.providerErrorMessage ? { message: diagnostic.providerErrorMessage } : {}),
    ...(diagnostic.providerErrorData ? { data: diagnostic.providerErrorData } : {}),
  }
}

function diagnosticAgentMessage(diagnostic: ExternalMcpDiagnostic): string {
  return `${diagnostic.message} ${diagnostic.operatorAction} Diagnostic reference: ${diagnostic.referenceId}.`
}

function diagnosticAgentFields(diagnostic: ExternalMcpDiagnostic) {
  const providerError = providerErrorFromDiagnostic(diagnostic)
  return {
    referenceId: diagnostic.referenceId,
    retryable: diagnostic.retryable,
    ...(providerError ? { providerError } : {}),
  }
}

function invalidCapabilityArguments(input: {
  capability: string
  schemaDigest?: string
  issues?: ExternalMcpArgumentIssue[]
  diagnostic?: ExternalMcpDiagnostic
  schemaGuidance?: ExternalMcpSchemaGuidance
}): Exclude<ExternalCapabilityExecuteResult, { ok: true }> {
  return {
    ok: false,
    error: "invalid_capability_arguments",
    capability: input.capability,
    message: input.diagnostic
      ? diagnosticAgentMessage(input.diagnostic)
      : "The capability arguments do not match the remote MCP tool's advertised argumentsSchema.",
    issues: input.issues ?? [{
      path: "/",
      keyword: "schema_validation",
      message: "The remote MCP rejected these arguments as invalid. Correct them using the latest argumentsSchema.",
    }],
    ...(input.schemaDigest ? { schemaDigest: input.schemaDigest } : {}),
    sameArgumentsRetryable: false,
    retry: { action: "correct_arguments", searchRequired: false },
    ...(input.schemaGuidance ? { schemaGuidance: input.schemaGuidance } : {}),
    ...(input.diagnostic ? diagnosticAgentFields(input.diagnostic) : {}),
  }
}

function advisorySchemaGuidance(
  warnings: ExternalMcpSchemaWarning[],
): ExternalMcpSchemaGuidance | undefined {
  if (warnings.length === 0) return undefined
  return {
    advisory: true,
    providerCallAttempted: true,
    message: "OmniRush.ai forwarded the call to the provider. These local schema checks are guidance only; use the provider result as the source of truth.",
    warnings,
  }
}

export type ExternalConnectionProbe =
  | { ok: true; connected: true; connection: { id: string; name: string } }
  | { ok: true; connected: false; status: ExternalConnectionStatus }
  | { ok: false; error: "forbidden" | "unknown_capability"; message: string }

/**
 * Probes one connection's live credential state without calling provider
 * tools. Backs the connection_status capability execution and the app-only
 * connection_action tool, so the same check renders the connection card and
 * refreshes it after the member fixes the connection.
 */
export async function probeExternalConnectionStatus(input: {
  organizationId: string
  member: McpMemberIdentity | null
  connectionId: string
}): Promise<ExternalConnectionProbe> {
  if (!input.member) {
    return { ok: false, error: "forbidden", message: "No active org membership for this token." }
  }
  let connection: Awaited<ReturnType<typeof getExternalMcpConnection>>
  let connectionId: DenTypeId<"externalMcpConnection">
  try {
    connectionId = normalizeDenTypeId("externalMcpConnection", input.connectionId)
    connection = await getExternalMcpConnection({
      organizationId: normalizeDenTypeId("organization", input.organizationId),
      connectionId,
    })
  } catch {
    connection = null
    connectionId = input.connectionId as DenTypeId<"externalMcpConnection">
  }
  if (!connection || connection.kind !== "external_mcp") {
    return { ok: false, error: "unknown_capability", message: `No external MCP connection "${input.connectionId}" in this organization.` }
  }
  const canUse = await memberCanUseExternalMcpConnection({
    connectionId,
    orgMembershipId: input.member.orgMembershipId,
    teamIds: input.member.teamIds,
  })
  if (!canUse) {
    return { ok: false, error: "forbidden", message: `You have not been granted access to "${connection.name}".` }
  }
  if (connection.oauthIssuerReviewRequiredAt) {
    const message = `"${connection.name}" is blocked until an organization admin reviews its changed OAuth issuer.`
    return {
      ok: true,
      connected: false,
      status: buildExternalConnectionStatus({
        connection,
        state: "reauth_required",
        errorCode: "unauthorized",
        message,
        actionOwner: "organization_admin",
      }),
    }
  }
  if (connection.credentialMode === "per_member") {
    const account = await getConnectedAccount({
      organizationId: connection.organizationId,
      orgMembershipId: input.member.orgMembershipId,
      providerId: connection.id,
    })
    if (!account?.accessToken) {
      const message = `You haven't connected your ${connection.name} account yet.`
      return {
        ok: true,
        connected: false,
        status: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
      }
    }
  } else if (!hasSharedCredential(connection)) {
    const message = `"${connection.name}" is not connected yet.`
    return {
      ok: true,
      connected: false,
      status: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
    }
  }
  return { ok: true, connected: true, connection: { id: connection.id, name: connection.name } }
}

/**
 * Executes a namespaced external capability, scoped to the calling
 * principal's org AND member: the member must hold a grant (org-wide,
 * direct, or team), and for per-member connections must have connected
 * their own account — the call then runs as them.
 */
export async function executeExternalCapability(input: {
  organizationId: string
  member: McpMemberIdentity | null
  connectionId: string
  toolName: string
  args: unknown
  schemaDigest?: string
  redirectUriBase: string
  /** Fail closed unless the live provider catalog still marks this exact tool read-only. */
  requireReadOnly?: boolean
  /** Fail closed when the live input schema no longer matches schemaDigest. */
  requireSchemaMatch?: boolean
}): Promise<ExternalCapabilityExecuteResult> {
  if (!input.member) {
    return { ok: false, error: "forbidden", message: "No active org membership for this token." }
  }

  let connection: Awaited<ReturnType<typeof getExternalMcpConnection>>
  let connectionId: DenTypeId<"externalMcpConnection">
  try {
    connectionId = normalizeDenTypeId("externalMcpConnection", input.connectionId)
    connection = await getExternalMcpConnection({
      organizationId: normalizeDenTypeId("organization", input.organizationId),
      connectionId,
    })
  } catch {
    // A malformed connectionId (e.g. hand-typed by an agent) isn't a server
    // error — it's the same "no such capability" outcome as a valid-shaped
    // but nonexistent id, so surface the same clean error either way.
    connection = null
    connectionId = input.connectionId as DenTypeId<"externalMcpConnection">
  }
  if (!connection) {
    return { ok: false, error: "unknown_capability", message: `No external MCP connection "${input.connectionId}" in this organization.` }
  }
  if (connection.kind !== "external_mcp") {
    return { ok: false, error: "unknown_capability", message: `Connection "${input.connectionId}" is a native provider connector and does not expose MCP tools.` }
  }

  const canUse = await memberCanUseExternalMcpConnection({
    connectionId,
    orgMembershipId: input.member.orgMembershipId,
    teamIds: input.member.teamIds,
  })
  if (!canUse) {
    return { ok: false, error: "forbidden", message: `You have not been granted access to "${connection.name}".` }
  }

  const policyDecision = evaluateToolPolicy(connection.toolPolicy, input.toolName)
  if (policyDecision.blocked) {
    return {
      ok: false,
      error: "policy_blocked",
      capability: buildExternalCapabilityName(connectionId, input.toolName),
      message: `${input.toolName} is disabled for your organization${policyDecision.disabledBy ? ` by ${policyDecision.disabledBy}` : ""}.`,
      sameArgumentsRetryable: false,
      retry: { action: "search_capabilities", searchRequired: true },
    }
  }

  if (connection.oauthIssuerReviewRequiredAt) {
    const message = `"${connection.name}" is blocked until an organization admin reviews its changed OAuth issuer.`
    return {
      ok: false,
      error: "needs_connection",
      message,
      connectionStatus: buildExternalConnectionStatus({
        connection,
        state: "reauth_required",
        errorCode: "unauthorized",
        message,
        actionOwner: "organization_admin",
      }),
    }
  }

  if (input.toolName === "*") {
    const message = `"${connection.name}" was surfaced as a connection status entry, not a callable tool. Fix the connection first (see the search hint), then search again for its real tools.`
    return {
      ok: false,
      error: "needs_connection",
      message,
      connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
    }
  }

  let member: { orgMembershipId: DenTypeId<"member"> } | undefined
  if (connection.credentialMode === "per_member") {
    const account = await getConnectedAccount({
      organizationId: connection.organizationId,
      orgMembershipId: input.member.orgMembershipId,
      providerId: connection.id,
    })
    if (!account?.accessToken) {
      return {
        ok: false,
        error: "needs_connection",
        message: `You haven't connected your ${connection.name} account yet. Open OmniRush.ai Cloud -> Your Connections and click Connect on "${connection.name}".`,
        connectionStatus: buildExternalConnectionStatus({
          connection,
          state: "needs_connection",
          errorCode: "not_connected",
          message: `You haven't connected your ${connection.name} account yet.`,
        }),
      }
    }
    member = { orgMembershipId: input.member.orgMembershipId }
  } else if (!hasSharedCredential(connection)) {
    const message = `"${connection.name}" is not connected yet.`
    return {
      ok: false,
      error: "connection_not_connected",
      message,
      connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
    }
  }

  let currentSchemaDigest: string | undefined
  let schemaGuidance: ExternalMcpSchemaGuidance | undefined
  const deadline = createExternalMcpLifecycleDeadline(EXTERNAL_MCP_TOOL_LIFECYCLE_TIMEOUT_MS)
  try {
    const redirectUri = redirectUriFor(input.redirectUriBase, connection.id)
    const tools = await listExternalMcpTools(connection, redirectUri, member, undefined, deadline)
    const tool = tools.find((candidate) => candidate.name === input.toolName)
    if (!tool) {
      return {
        ok: false,
        error: "unknown_capability",
        capability: buildExternalCapabilityName(connection.id, input.toolName),
        message: `No current tool named "${input.toolName}" exists on "${connection.name}". Call search_capabilities again.`,
        sameArgumentsRetryable: false,
        retry: { action: "search_capabilities", searchRequired: true },
      }
    }

    if (input.requireReadOnly && (tool.annotations?.readOnlyHint !== true || tool.annotations?.destructiveHint === true)) {
      return {
        ok: false,
        error: "policy_blocked",
        capability: buildExternalCapabilityName(connection.id, input.toolName),
        message: `${input.toolName} is no longer advertised as strictly read-only, so OmniRush.ai blocked the Remote MCP App call.`,
        sameArgumentsRetryable: false,
        retry: { action: "search_capabilities", searchRequired: true },
      }
    }

    const schemaDigest = externalMcpToolSchemaDigest(tool.inputSchema)
    currentSchemaDigest = schemaDigest
    if (input.requireSchemaMatch && input.schemaDigest && input.schemaDigest !== schemaDigest) {
      return {
        ok: false,
        error: "policy_blocked",
        capability: buildExternalCapabilityName(connection.id, input.toolName),
        message: `${input.toolName} now advertises a different input schema, so OmniRush.ai blocked the Remote MCP App call until its cached revision is refreshed.`,
        sameArgumentsRetryable: false,
        retry: { action: "search_capabilities", searchRequired: true },
      }
    }
    const schemaWarnings: ExternalMcpSchemaWarning[] = []
    if (input.schemaDigest && input.schemaDigest !== schemaDigest) {
      schemaWarnings.push({
        code: "capability_schema_changed",
        message: "The provider advertised a different capability schema after discovery, but OmniRush.ai still forwarded the call.",
        searchedSchemaDigest: input.schemaDigest,
        currentSchemaDigest: schemaDigest,
        suggestedAction: "If the provider call failed, call search_capabilities again and retry with the latest argumentsSchema. Do not retry solely because of this warning when the provider call succeeded.",
      })
    }

    // MCP tool arguments are always an object at the protocol boundary. Start
    // the provider call before advisory validation so a provider with an
    // inaccurate or unsupported advertised schema still gets the request.
    const forwardedArguments = isRecord(input.args) ? input.args : {}
    const providerCall = callExternalMcpTool({
      connection,
      redirectUri,
      toolName: input.toolName,
      args: forwardedArguments,
      member,
      lifecycleDeadline: deadline,
    })

    const validation = validateExternalMcpToolArguments(tool.inputSchema, input.args)
    if (!validation.ok && validation.error === "invalid_arguments") {
      schemaWarnings.push({
        code: "arguments_schema_mismatch",
        message: "The arguments do not match the provider's advertised argumentsSchema, but OmniRush.ai still forwarded the call because the provider may accept them.",
        issues: validation.issues,
        suggestedAction: "If the provider call failed, correct the listed issues and retry with changed arguments. Do not retry solely because of this warning when the provider call succeeded.",
      })
    } else if (!validation.ok) {
      schemaWarnings.push({
        code: "arguments_schema_unavailable",
        message: validation.message,
        suggestedAction: "Use the provider result as the source of truth. If the call failed, the provider administrator may need to repair the advertised inputSchema.",
      })
    }

    schemaGuidance = advisorySchemaGuidance(schemaWarnings)
    const result = await providerCall
    const resourceUri = externalMcpAppResourceUri(tool)
    return {
      ok: true,
      result,
      ...(schemaGuidance ? { schemaGuidance } : {}),
      ...(resourceUri
        ? {
            mcpApp: {
              connectionId: connection.id,
              toolName: tool.name,
              resourceUri,
              arguments: forwardedArguments,
            },
          }
        : {}),
    }
  } catch (error) {
    const message = upstreamErrorMessage(error)
    const authErrorCode = externalMcpAuthErrorCode(error, message)
    if (error instanceof ExternalMcpDiagnosticError) {
      const diagnostic = error.diagnostic.code === "MCP_PROVIDER_AUTH_REQUIRED"
        ? providerAuthorizationDiagnosticForConnection({ diagnostic: error.diagnostic, connectionUrl: connection.url })
        : error.diagnostic
      const log = externalMcpDiagnosticForLog(error, error.diagnostic.referenceId, "MCP_TOOL_EXECUTION")
      console.error("external_mcp_capability_execute_failed", {
        connectionId: connection.id,
        organizationId: connection.organizationId,
        connectionEndpoint: safeExternalMcpEndpointForLog(connection.url),
        ...log,
        diagnostic,
      })
      if (diagnostic.code === "MCP_INVALID_PARAMS" || diagnostic.code === "MCP_PROVIDER_INVALID_PARAMS") {
        return invalidCapabilityArguments({
          capability: buildExternalCapabilityName(connection.id, input.toolName),
          schemaDigest: currentSchemaDigest ?? input.schemaDigest,
          diagnostic,
          schemaGuidance,
        })
      }
      if (diagnostic.code === "MCP_PROVIDER_AUTH_REQUIRED") {
        const resultMessage = diagnosticAgentMessage(diagnostic)
        return {
          ok: false,
          error: "needs_connection",
          message: resultMessage,
          ...diagnosticAgentFields(diagnostic),
          connectionStatus: providerAuthorizationConnectionStatus({
            connection,
            diagnostic,
            message: resultMessage,
          }),
          ...(schemaGuidance ? { schemaGuidance } : {}),
        }
      }
      return {
        ok: false,
        error: diagnostic.phase === "PROVIDER_EXECUTION" || diagnostic.phase === "PROVIDER_AUTHORIZATION"
          ? "provider_error"
          : "connection_failed",
        message: diagnosticAgentMessage(diagnostic),
        ...diagnosticAgentFields(diagnostic),
        ...(schemaGuidance ? { schemaGuidance } : {}),
        ...(authErrorCode
          ? {
              connectionStatus: buildExternalConnectionStatus({
                connection,
                state: "reauth_required",
                errorCode: authErrorCode,
                message,
                diagnostic,
              }),
            }
          : {}),
      }
    }
    if (authErrorCode) {
      return {
        ok: false,
        error: "connection_failed",
        message,
        ...(schemaGuidance ? { schemaGuidance } : {}),
        connectionStatus: buildExternalConnectionStatus({
          connection,
          state: "reauth_required",
          errorCode: authErrorCode,
          message,
        }),
      }
    }
    throw error
  }
}