Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
81.8 KB
Raw Blame
import { createHash } from "node:crypto"
import { isEnterpriseMcpLifecycleDeadline } from "@omnirush/enterprise-mcp-client"
import { PrivateUrlError } from "./url-guard.js"

export const EXTERNAL_MCP_DIAGNOSTIC_PHASES = [
  "CONFIGURATION",
  "NETWORK_DNS",
  "NETWORK_TCP",
  "NETWORK_TLS",
  "HTTP_ROUTING",
  "AUTH_RESOURCE_DISCOVERY",
  "AUTH_ISSUER_DISCOVERY",
  "AUTH_CLIENT_REGISTRATION",
  "AUTH_USER_OR_WORKLOAD",
  "AUTH_TOKEN_ACQUISITION",
  "AUTH_RESOURCE_VALIDATION",
  "MCP_TRANSPORT",
  "MCP_VERSION",
  "MCP_INITIALIZE",
  "MCP_INITIALIZED",
  "MCP_TOOL_DISCOVERY",
  "MCP_TOOL_EXECUTION",
  "PROVIDER_AUTHORIZATION",
  "PROVIDER_EXECUTION",
  "CONTINUITY_REFRESH",
  "CONTINUITY_SESSION",
  "SHUTDOWN",
] as const

export type ExternalMcpDiagnosticPhase = (typeof EXTERNAL_MCP_DIAGNOSTIC_PHASES)[number]

export type ExternalMcpHealthLevel =
  | "configured"
  | "reachable"
  | "authorized"
  | "protocol_ready"
  | "catalog_ready"
  | "operation_ready"

export type ExternalMcpDiagnostic = {
  referenceId: string
  phase: ExternalMcpDiagnosticPhase
  category: string
  code: string
  highestPassed: ExternalMcpHealthLevel
  retryable: boolean
  actionOwner: "omnirush" | "network_admin" | "provider_admin" | "organization_admin" | "member"
  operatorAction: string
  message: string
  httpStatus?: number
  operationPhase?: ExternalMcpDiagnosticPhase
  outbound?: ExternalMcpSafeOutbound
  providerRequestId?: string
  providerStatus?: number
  providerCode?: string
  payloadBytes?: number
  jsonRpcCode?: number
  connectUrl?: string
  providerErrorMessage?: string
  providerErrorData?: string
  providerResponseExcerpt?: string
}

export type ExternalMcpSafeOutbound = {
  origin: string
  pathHash: string
}

export type ExternalMcpSafeCause = {
  name: string
  code?: string
  errno?: string | number
  syscall?: string
}

type FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>

// JSON MCP responses are expected to be compact. Event streams need more
// headroom because a single request can carry multiple protocol messages, but
// still need an absolute byte ceiling so a provider cannot grow Den memory
// without bound.
export const EXTERNAL_MCP_JSON_RESPONSE_LIMIT_BYTES = 4 * 1024 * 1024
export const EXTERNAL_MCP_SSE_RESPONSE_LIMIT_BYTES = 16 * 1024 * 1024
const EXTERNAL_MCP_PROVIDER_DECLARED_ERROR_SNIFF_LIMIT_BYTES = 64 * 1024
const EXTERNAL_MCP_PROVIDER_RESPONSE_EXCERPT_CHARS = 600
const EXTERNAL_MCP_OAUTH_PROVIDER_DETAIL_CHARS = 300
const SENSITIVE_TEXT_PAIR = /((?:token|secret|password|assertion|code|key|authorization)[\w-]*\s*[=:]\s*)[^\s&"',;)]+/gi
const SENSITIVE_QUOTED_TEXT_PAIR = /(["'][\w-]*(?:token|secret|password|assertion|code|key|authorization)[\w-]*["']\s*:\s*["'])[^"']*(["'])/gi
const JWT_CREDENTIAL = /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g
const SLACK_CREDENTIAL = /\bxox[a-z]-[A-Za-z0-9-]+|\bxoxe(?:-\d)?-[A-Za-z0-9-]+/gi
const BEARER_CREDENTIAL = /(\bBearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi
const GITHUB_CREDENTIAL = /\bgh[pousr]_[A-Za-z0-9]{20,}/gi
const LONG_OPAQUE_CREDENTIAL = /[A-Za-z0-9_~+/=-]{40,}/g
const PROVIDER_RESPONSE_STRING_FIELDS = ["error_description", "error_uri", "message"]
const PROVIDER_RESPONSE_CONTENT_TYPE_CHARS = 120

type ProviderResponseLog = {
  contentType: string
  bodyChars: number
  excerpt?: string
}

export class ExternalMcpLifecycleDeadlineError extends Error {
  constructor() {
    super("External MCP lifecycle deadline exceeded.")
    this.name = "ExternalMcpLifecycleDeadlineError"
  }
}

class ExternalMcpResponseBodyLimitError extends Error {
  constructor() {
    super("External MCP response body exceeded its byte limit.")
    this.name = "ExternalMcpResponseBodyLimitError"
  }
}

const HEALTH_RANK: Record<ExternalMcpHealthLevel, number> = {
  configured: 0,
  reachable: 1,
  authorized: 2,
  protocol_ready: 3,
  catalog_ready: 4,
  operation_ready: 5,
}

const TLS_ERROR_CODES = new Set([
  "CERT_HAS_EXPIRED",
  "DEPTH_ZERO_SELF_SIGNED_CERT",
  "ERR_TLS_CERT_ALTNAME_INVALID",
  "SELF_SIGNED_CERT_IN_CHAIN",
  "UNABLE_TO_GET_ISSUER_CERT",
  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
])

const TCP_ERROR_CODES = new Set([
  "ECONNREFUSED",
  "ECONNRESET",
  "EHOSTUNREACH",
  "ENETUNREACH",
  "ETIMEDOUT",
  "UND_ERR_CONNECT_TIMEOUT",
  "UND_ERR_HEADERS_TIMEOUT",
])

const SAFE_NATIVE_ERROR_CODES = new Set([
  ...TLS_ERROR_CODES,
  ...TCP_ERROR_CODES,
  "ENOTFOUND",
  "EAI_AGAIN",
  "ConnectionRefused",
  "ConnectionReset",
  "ConnectionTimedOut",
  "Timeout",
])

const SAFE_ERROR_NAMES = new Set([
  "Error",
  "TypeError",
  "SyntaxError",
  "AggregateError",
  "AbortError",
  "FetchError",
  "McpError",
  "UnauthorizedError",
  "StreamableHTTPError",
  "OAuthError",
  "CustomOAuthError",
  "InvalidClientError",
  "UnauthorizedClientError",
  "InvalidClientMetadataError",
  "InvalidGrantError",
  "InvalidRequestError",
  "InvalidScopeError",
  "InvalidTargetError",
  "InvalidTokenError",
  "InsufficientScopeError",
  "MethodNotAllowedError",
  "TooManyRequestsError",
  "UnsupportedTokenTypeError",
  "AccessDeniedError",
  "UnsupportedGrantTypeError",
  "UnsupportedResponseTypeError",
  "TemporarilyUnavailableError",
  "ServerError",
])

const SAFE_PROVIDER_TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/
const SAFE_PROVIDER_REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:/-]*$/
const PROVIDER_STATUS_FIELDS = ["status", "statusCode", "httpStatus"]
const PROVIDER_CODE_FIELDS = ["code", "error"]
const PROVIDER_REQUEST_ID_FIELDS = ["requestId", "request_id", "transactionId", "transaction_id"]
const URL_ELICITATION_REQUIRED_JSON_RPC_CODE = -32042

const TYPED_OAUTH_ERROR_NAMES = new Set([
  "InvalidClientError",
  "UnauthorizedClientError",
  "InvalidClientMetadataError",
  "InvalidGrantError",
  "InvalidRequestError",
  "InvalidScopeError",
  "InvalidTargetError",
  "InvalidTokenError",
  "InsufficientScopeError",
  "MethodNotAllowedError",
  "TooManyRequestsError",
  "UnsupportedTokenTypeError",
  "AccessDeniedError",
  "UnsupportedGrantTypeError",
  "UnsupportedResponseTypeError",
  "TemporarilyUnavailableError",
  "ServerError",
])

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

function redactSensitiveString(value: string): string {
  return value
    .replace(SENSITIVE_QUOTED_TEXT_PAIR, "$1[redacted]$2")
    .replace(SENSITIVE_TEXT_PAIR, "$1[redacted]")
    .replace(JWT_CREDENTIAL, "[redacted]")
    .replace(SLACK_CREDENTIAL, "[redacted]")
    .replace(BEARER_CREDENTIAL, "$1[redacted]")
    .replace(GITHUB_CREDENTIAL, "[redacted]")
    .replace(LONG_OPAQUE_CREDENTIAL, "[redacted]")
}

function isOAuthTokenPhase(phase: ExternalMcpDiagnosticPhase): boolean {
  return phase === "AUTH_TOKEN_ACQUISITION" || phase === "CONTINUITY_REFRESH"
}

function isProviderTokenErrorExcerpt(excerpt: string): boolean {
  try {
    const parsed: unknown = JSON.parse(excerpt)
    return isRecord(parsed) && parsed.ok === false && typeof parsed.error === "string"
  } catch {
    return false
  }
}

function structuredProviderResponseExcerpt(text: string): string | undefined {
  try {
    const parsed: unknown = JSON.parse(text)
    if (!isRecord(parsed)) return undefined
    const allowed: Record<string, unknown> = {}
    if (typeof parsed.ok === "boolean") allowed.ok = parsed.ok
    if (typeof parsed.error === "string") {
      allowed.error = redactSensitiveString(parsed.error)
    } else if (isRecord(parsed.error)) {
      if (
        typeof parsed.error.code === "number"
        && Number.isSafeInteger(parsed.error.code)
        && String(parsed.error.code).length <= 16
      ) {
        allowed.error_code = parsed.error.code
      }
      if (typeof parsed.error.message === "string") {
        allowed.error_message = redactSensitiveString(parsed.error.message)
      }
    }
    for (const field of PROVIDER_RESPONSE_STRING_FIELDS) {
      const value = parsed[field]
      if (typeof value === "string") allowed[field] = redactSensitiveString(value)
    }
    if (Object.keys(allowed).length === 0) return undefined
    return JSON.stringify(allowed).slice(0, EXTERNAL_MCP_PROVIDER_RESPONSE_EXCERPT_CHARS)
  } catch {
    return undefined
  }
}

function providerResponseContentType(contentType: string): string {
  const bounded = contentType.slice(0, PROVIDER_RESPONSE_CONTENT_TYPE_CHARS)
  return /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i.test(bounded) ? bounded : "unknown"
}

function stringProperty(value: unknown, key: string): string | undefined {
  if (!isRecord(value)) return undefined
  const property = value[key]
  return typeof property === "string" ? property : undefined
}

function stringOrNumberProperty(value: unknown, key: string): string | number | undefined {
  if (!isRecord(value)) return undefined
  const property = value[key]
  return typeof property === "string" || typeof property === "number" ? property : undefined
}

function errorCause(value: unknown): unknown {
  return isRecord(value) ? value.cause : undefined
}

function errorCode(value: unknown): string | undefined {
  let current: unknown = value
  for (let depth = 0; depth < 5 && current; depth += 1) {
    const code = stringProperty(current, "code")
    if (code) return code
    current = errorCause(current)
  }
  return undefined
}

function numericErrorCode(value: unknown): number | undefined {
  let current: unknown = value
  for (let depth = 0; depth < 5 && current; depth += 1) {
    const code = isRecord(current) ? current.code : undefined
    // MCP/JSON-RPC protocol errors use negative integer codes. Positive
    // values on SDK errors are commonly HTTP statuses and are already
    // represented by httpStatus, so do not mislabel them as JSON-RPC.
    if (typeof code === "number" && Number.isSafeInteger(code) && code < 0) return code
    current = errorCause(current)
  }
  return undefined
}

type ProviderAuthorizationRequired = {
  connectUrl: string
  provider?: string
}

type ProviderDeclaredErrorEvidence = {
  phase: ExternalMcpDiagnosticPhase
  jsonRpcCode: number
  connectUrl?: string
  provider?: string
  message?: string
  dataExcerpt?: string
}

function validatedProviderConnectUrl(value: string | undefined): string | undefined {
  if (!value) return undefined
  try {
    const url = new URL(value)
    return url.protocol === "http:" || url.protocol === "https:" ? url.toString() : undefined
  } catch {
    return undefined
  }
}

function providerAuthorizationRequired(value: unknown): ProviderAuthorizationRequired | null {
  let current: unknown = value
  for (let depth = 0; depth < 5 && current; depth += 1) {
    const data = isRecord(current) ? current.data : undefined
    if (isRecord(data)) {
      const connectUrl = validatedProviderConnectUrl(stringProperty(data, "connect_url"))
      if (connectUrl) {
        const provider = stringProperty(data, "provider")
        return { connectUrl, ...(provider ? { provider } : {}) }
      }

      const code = isRecord(current) ? current.code : undefined
      if (code === URL_ELICITATION_REQUIRED_JSON_RPC_CODE) {
        const url = validatedProviderConnectUrl(stringProperty(data, "url"))
        if (url) {
          const provider = stringProperty(data, "provider")
          return { connectUrl: url, ...(provider ? { provider } : {}) }
        }
      }
    }
    current = errorCause(current)
  }
  return null
}

function localRequestTimeout(value: unknown): boolean {
  let current: unknown = value
  for (let depth = 0; depth < 5 && current; depth += 1) {
    const data = isRecord(current) ? current.data : undefined
    if (isRecord(data) && typeof data.timeout === "number") return true
    current = errorCause(current)
  }
  return false
}

function validProviderDeclaredJsonRpcId(envelope: Record<string, unknown>): boolean {
  if (!("id" in envelope)) return true
  const id = envelope.id
  return id === null || typeof id === "string" || typeof id === "number"
}

function providerDeclaredDataExcerpt(data: Record<string, unknown> | null, connectUrl: string | undefined): string | undefined {
  if (!data) return undefined
  const entries = Object.entries(data)
  if (connectUrl && entries.length === 1) {
    const onlyEntry = entries[0]
    if (onlyEntry) {
      const [key, value] = onlyEntry
      if ((key === "connect_url" || key === "url") && validatedProviderConnectUrl(typeof value === "string" ? value : undefined) === connectUrl) {
        return undefined
      }
    }
  }
  try {
    const serialized = JSON.stringify(data)
    return typeof serialized === "string" ? sanitizedProviderTextExcerpt(serialized) : undefined
  } catch {
    return undefined
  }
}

function providerDeclaredErrorFromEnvelope(
  value: unknown,
  phase: ExternalMcpDiagnosticPhase,
): ProviderDeclaredErrorEvidence | null {
  if (!isRecord(value) || !validProviderDeclaredJsonRpcId(value)) return null
  const error = value.error
  if (!isRecord(error) || typeof error.code !== "number" || !Number.isSafeInteger(error.code)) return null
  const jsonRpcCode = error.code
  const data = isRecord(error.data) ? error.data : null
  const provider = data ? stringProperty(data, "provider") : undefined
  const message = sanitizedProviderTextExcerpt(stringProperty(error, "message") ?? "")

  const connectUrl = data ? validatedProviderConnectUrl(stringProperty(data, "connect_url")) : undefined
  const elicitedUrl = jsonRpcCode === URL_ELICITATION_REQUIRED_JSON_RPC_CODE && data
    ? validatedProviderConnectUrl(stringProperty(data, "url"))
    : undefined
  const dataExcerpt = providerDeclaredDataExcerpt(data, connectUrl ?? elicitedUrl)
  const evidence = {
    phase,
    jsonRpcCode,
    ...(provider ? { provider } : {}),
    ...(message ? { message } : {}),
    ...(dataExcerpt ? { dataExcerpt } : {}),
  }
  if (connectUrl) return { ...evidence, connectUrl }
  if (elicitedUrl) return { ...evidence, connectUrl: elicitedUrl }

  if (value.jsonrpc === "2.0" && jsonRpcCode < 0) {
    return evidence
  }
  return null
}

function providerDeclaredErrorFromError(
  value: unknown,
  phase: ExternalMcpDiagnosticPhase,
): ProviderDeclaredErrorEvidence | null {
  let current: unknown = value
  for (let depth = 0; depth < 5 && current; depth += 1) {
    const code = isRecord(current) ? current.code : undefined
    if (typeof code === "number" && Number.isSafeInteger(code) && code < 0) {
      const data = isRecord(current) && isRecord(current.data) ? current.data : null
      const connectUrl = data ? validatedProviderConnectUrl(stringProperty(data, "connect_url")) : undefined
      const elicitedUrl = code === URL_ELICITATION_REQUIRED_JSON_RPC_CODE && data
        ? validatedProviderConnectUrl(stringProperty(data, "url"))
        : undefined
      const dataExcerpt = providerDeclaredDataExcerpt(data, connectUrl ?? elicitedUrl)
      const message = current instanceof Error
        ? sanitizedProviderTextExcerpt(current.message)
        : sanitizedProviderTextExcerpt(stringProperty(current, "message") ?? "")
      const providerConnectUrl = connectUrl ?? elicitedUrl
      return {
        phase,
        jsonRpcCode: code,
        ...(providerConnectUrl ? { connectUrl: providerConnectUrl } : {}),
        ...(message ? { message } : {}),
        ...(dataExcerpt ? { dataExcerpt } : {}),
      }
    }
    current = errorCause(current)
  }
  return null
}

function providerDeclaredErrorFromJson(
  value: unknown,
  phase: ExternalMcpDiagnosticPhase,
): ProviderDeclaredErrorEvidence | null {
  if (Array.isArray(value)) {
    for (const item of value) {
      const evidence = providerDeclaredErrorFromEnvelope(item, phase)
      if (evidence) return evidence
    }
    return null
  }
  return providerDeclaredErrorFromEnvelope(value, phase)
}

function providerAuthorizationClassification(connectUrl: string): Classification {
  return {
    phase: "PROVIDER_AUTHORIZATION",
    category: "provider_authorization_required",
    code: "MCP_PROVIDER_AUTH_REQUIRED",
    retryable: false,
    actionOwner: "member",
    operatorAction: "Connect your account for this provider using its sign-in link, then retry this capability.",
    connectUrl,
  }
}

function providerDeclaredErrorClassification(): Classification {
  return {
    phase: "PROVIDER_EXECUTION",
    category: "provider_declared_error",
    code: "MCP_PROVIDER_DECLARED_ERROR",
    retryable: false,
    actionOwner: "provider_admin",
    operatorAction: "Look up the provider-declared JSON-RPC error code with the provider, then correct the downstream condition and retry.",
  }
}

function safeNativeToken(value: string | undefined, pattern: RegExp, maxLength = 64): string | undefined {
  if (!value || value.length > maxLength || !pattern.test(value)) return undefined
  return value
}

function safeProviderToken(value: unknown, maxLength = 64): string | undefined {
  return typeof value === "string" ? safeNativeToken(value, SAFE_PROVIDER_TOKEN_PATTERN, maxLength) : undefined
}

function safeProviderRequestId(value: unknown): string | undefined {
  return typeof value === "string" ? safeNativeToken(value, SAFE_PROVIDER_REQUEST_ID_PATTERN, 128) : undefined
}

function validProviderStatus(value: unknown): number | undefined {
  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 400 || value > 599) return undefined
  return value
}

function providerStatusFromRecord(value: Record<string, unknown>): number | undefined {
  for (const field of PROVIDER_STATUS_FIELDS) {
    const status = validProviderStatus(value[field])
    if (status !== undefined) return status
  }
  return undefined
}

function providerCodeFromRecord(value: Record<string, unknown>): string | undefined {
  for (const field of PROVIDER_CODE_FIELDS) {
    const code = safeProviderToken(value[field])
    if (code) return code
  }
  return undefined
}

function providerRequestIdFromRecord(value: Record<string, unknown>): string | undefined {
  for (const field of PROVIDER_REQUEST_ID_FIELDS) {
    const requestId = safeProviderRequestId(value[field])
    if (requestId) return requestId
  }
  return undefined
}

function providerStatusFromLeadingText(value: string): number | undefined {
  const text = value.trimStart()
  const statusMatch = /^(?:HTTP[ /])?([45]\d\d)\b/.exec(text) ?? /^([45]\d\d)\s+[A-Za-z]/.exec(text)
  const statusText = statusMatch?.[1]
  if (!statusText) return undefined
  return validProviderStatus(Number(statusText))
}

function parsedTextRecord(value: string): Record<string, unknown> | null {
  try {
    const parsed: unknown = JSON.parse(value)
    return isRecord(parsed) ? parsed : null
  } catch {
    return null
  }
}

function providerToolContentArray(result: unknown): unknown[] | null {
  if (!isRecord(result) || !Array.isArray(result.content)) return null
  return result.content
}

function isProviderToolTextContent(value: unknown): value is { type: "text"; text: string } {
  return isRecord(value) && value.type === "text" && typeof value.text === "string"
}

function serializedContentPayloadBytes(content: unknown[] | null): number {
  if (!content || content.length === 0) return 0
  try {
    const serialized = JSON.stringify(content)
    return typeof serialized === "string" ? Buffer.byteLength(serialized, "utf8") : 0
  } catch {
    return 0
  }
}

function sanitizedProviderTextExcerpt(text: string): string | undefined {
  const sanitized = text
    .replace(/[\u0000-\u001F\u007F-\u009F]/g, " ")
    .replace(/\s+/g, " ")
    .trim()
  if (!sanitized) return undefined
  return sanitized.length > 512 ? sanitized.slice(0, 512) : sanitized
}

function sanitizedProviderToolExcerpt(texts: string[]): string | undefined {
  return sanitizedProviderTextExcerpt(texts.join("\n"))
}

type ProviderToolContentEvidence = {
  providerStatus?: number
  providerCode?: string
  providerRequestId?: string
  payloadBytes: number
  excerpt?: string
}

function providerToolContentEvidence(result: unknown): ProviderToolContentEvidence {
  const content = providerToolContentArray(result)
  const payloadBytes = serializedContentPayloadBytes(content)
  if (!content) return { payloadBytes }

  let providerStatus: number | undefined
  let providerCode: string | undefined
  let providerRequestId: string | undefined
  const texts: string[] = []

  for (const item of content) {
    if (!isProviderToolTextContent(item)) continue
    texts.push(item.text)
    const parsed = parsedTextRecord(item.text)
    if (parsed) {
      providerStatus ??= providerStatusFromRecord(parsed)
      providerCode ??= providerCodeFromRecord(parsed)
      providerRequestId ??= providerRequestIdFromRecord(parsed)
    }
    providerStatus ??= providerStatusFromLeadingText(item.text)
  }

  const excerpt = sanitizedProviderToolExcerpt(texts)
  return {
    payloadBytes,
    ...(providerStatus === undefined ? {} : { providerStatus }),
    ...(providerCode ? { providerCode } : {}),
    ...(providerRequestId ? { providerRequestId } : {}),
    ...(excerpt ? { excerpt } : {}),
  }
}

function isProviderInputValidationExcerpt(value: string | undefined): boolean {
  if (!value) return false
  return /^Input validation error:\s*Invalid arguments for tool\b/i.test(value)
    || /^Invalid (?:tool )?(?:arguments|params)\b/i.test(value)
}

function errorName(value: unknown): string {
  const name = value instanceof Error && value.name === "Error" && SAFE_ERROR_NAMES.has(value.constructor.name)
    ? value.constructor.name
    : value instanceof Error
      ? value.name
      : stringProperty(value, "name")
  return name && SAFE_ERROR_NAMES.has(name) ? name : "Error"
}

function oauthProviderDetail(error: unknown): string | undefined {
  let current: unknown = error
  const seen = new Set<unknown>()
  for (let depth = 0; depth < 5 && current && !seen.has(current); depth += 1) {
    seen.add(current)
    const name = errorName(current)
    if (TYPED_OAUTH_ERROR_NAMES.has(name) || name === "OAuthError" || name === "CustomOAuthError") {
      const description = stringProperty(current, "error_description")
        ?? (current instanceof Error ? current.message : stringProperty(current, "message"))
      if (!description) return name
      const prefix = `${name}: `
      const redacted = redactSensitiveString(description).slice(
        0,
        Math.max(0, EXTERNAL_MCP_OAUTH_PROVIDER_DETAIL_CHARS - prefix.length),
      )
      return `${prefix}${redacted}`.slice(0, EXTERNAL_MCP_OAUTH_PROVIDER_DETAIL_CHARS)
    }
    current = errorCause(current)
  }
  return undefined
}

function hasUnsupportedVersionMessage(value: unknown): boolean {
  let current: unknown = value
  const seen = new Set<unknown>()
  for (let depth = 0; depth < 5 && current && !seen.has(current); depth += 1) {
    seen.add(current)
    const message = current instanceof Error ? current.message : stringProperty(current, "message")
    if (message && message.length <= 1_000) {
      const normalized = message.toLowerCase()
      if (
        (normalized.includes("protocol version") || normalized.includes("mcp version"))
        && (normalized.includes("unsupported") || normalized.includes("not supported") || normalized.includes("incompatible"))
      ) return true
    }
    current = errorCause(current)
  }
  return false
}

function hasForbiddenPortMessage(value: unknown): boolean {
  const outerMessage = value instanceof Error ? value.message : stringProperty(value, "message")
  const outerName = value instanceof Error ? value.name : stringProperty(value, "name")
  if (outerName !== "TypeError" || outerMessage?.toLowerCase() !== "fetch failed") return false

  let current: unknown = errorCause(value)
  const seen = new Set<unknown>()
  for (let depth = 0; depth < 5 && current && !seen.has(current); depth += 1) {
    seen.add(current)
    const message = current instanceof Error ? current.message : stringProperty(current, "message")
    if (message && ["bad port", "forbidden port"].includes(message.trim().toLowerCase())) return true
    current = errorCause(current)
  }
  return false
}

export function safeExternalMcpCauseChain(error: unknown): ExternalMcpSafeCause[] {
  const causes: ExternalMcpSafeCause[] = []
  let current: unknown = error
  const seen = new Set<unknown>()
  for (let depth = 0; depth < 5 && current && !seen.has(current); depth += 1) {
    seen.add(current)
    const rawCode = stringOrNumberProperty(current, "code")
    const code = typeof rawCode === "number" && Number.isSafeInteger(rawCode)
      ? String(rawCode).slice(0, 16)
      : typeof rawCode === "string" && SAFE_NATIVE_ERROR_CODES.has(rawCode)
        ? rawCode
        : undefined
    const errno = stringOrNumberProperty(current, "errno")
    const safeErrno = typeof errno === "number" && Number.isSafeInteger(errno)
      ? errno
      : typeof errno === "string"
        ? safeNativeToken(errno, /^-?\d+$/, 16)
        : undefined
    const syscall = safeNativeToken(stringProperty(current, "syscall"), /^(connect|read|write|getaddrinfo|lookup|request)$/)
    causes.push({
      name: errorName(current),
      ...(code ? { code } : {}),
      ...(safeErrno !== undefined ? { errno: safeErrno } : {}),
      ...(syscall ? { syscall } : {}),
    })
    current = errorCause(current)
  }
  return causes
}

function safeMessageFor(input: {
  phase: ExternalMcpDiagnosticPhase
  category: string
  code: string
  highestPassed?: ExternalMcpHealthLevel
  providerStatus?: number
  providerCode?: string
  jsonRpcCode?: number
  providerErrorMessage?: string
  providerDetail?: string
}): string {
  const baseMessage = safeBaseMessageFor(input)
  const message = input.providerDetail
    ? `${baseMessage} Provider detail (untrusted): "${input.providerDetail}".`
    : baseMessage
  const details = [
    ...(input.providerStatus === undefined ? [] : [`provider status ${input.providerStatus}`]),
    ...(input.providerCode ? [`code ${input.providerCode}`] : []),
  ]
  return details.length === 0 ? message : `${message} Provider evidence: ${details.join(", ")}.`
}

function safeBaseMessageFor(input: {
  phase: ExternalMcpDiagnosticPhase
  category: string
  code: string
  highestPassed?: ExternalMcpHealthLevel
  jsonRpcCode?: number
  providerErrorMessage?: string
}): string {
  if (input.code === "MCP_LIFECYCLE_DEADLINE") {
    return input.phase === "MCP_TOOL_EXECUTION"
      ? "The capability did not finish within the time OmniRush.ai allows a single tool call."
      : "The MCP lifecycle exceeded OmniRush.ai's bounded diagnostic deadline."
  }
  if (input.code === "MCP_REQUEST_TIMEOUT") {
    return "The MCP server did not answer the current protocol request within its bounded timeout."
  }
  if (input.code === "MCP_PROVIDER_AUTH_REQUIRED") {
    const message = "The provider answered but requires this user to authorize the downstream account before the tool can run."
    return input.providerErrorMessage
      ? `${message} Provider-declared message (untrusted): "${input.providerErrorMessage}".`
      : message
  }
  if (input.code === "MCP_INVALID_PARAMS" || input.code === "MCP_PROVIDER_INVALID_PARAMS") {
    // The provider's own rejection names the offending argument; without it a
    // member cannot correct a launch input that omits a required field.
    const message = "The provider rejected the tool arguments."
    return input.providerErrorMessage
      ? `${message} Provider-declared message (untrusted): "${input.providerErrorMessage}".`
      : message
  }
  if (input.code === "MCP_PROVIDER_DECLARED_ERROR") {
    const message = input.jsonRpcCode === undefined
      ? "The provider answered with a JSON-RPC error OmniRush.ai does not recognize."
      : `The provider answered with a JSON-RPC error OmniRush.ai does not recognize (code ${input.jsonRpcCode}).`
    return input.providerErrorMessage
      ? `${message} Provider-declared message (untrusted): "${input.providerErrorMessage}".`
      : message
  }
  if (input.code === "MCP_RESPONSE_BODY_LIMIT") {
    return "The MCP server returned a response body larger than OmniRush.ai can safely process."
  }
  if (input.highestPassed && HEALTH_RANK[input.highestPassed] >= HEALTH_RANK.protocol_ready && isUninformativeClassification(input)) {
    return "The MCP server answered, but OmniRush.ai could not interpret its response for the current request."
  }
  if (input.category === "security_blocked") {
    return "Den blocked the MCP URL because it violates the outbound network safety policy."
  }
  if (input.code === "MCP_FETCH_FORBIDDEN_PORT") {
    return "The MCP URL uses a port that server-side HTTP clients are not permitted to access."
  }
  if (input.phase === "NETWORK_DNS") {
    return "Den could not resolve the MCP host from its server network."
  }
  if (input.phase === "NETWORK_TCP") {
    return "Den resolved the MCP host but could not establish a network connection."
  }
  if (input.phase === "NETWORK_TLS") {
    return "Den reached the MCP host but could not verify or complete TLS."
  }
  if (input.phase === "AUTH_RESOURCE_DISCOVERY") {
    return "The MCP endpoint did not provide usable protected-resource metadata."
  }
  if (input.phase === "AUTH_ISSUER_DISCOVERY") {
    return "The authorization server did not provide usable OAuth metadata."
  }
  if (input.phase === "AUTH_CLIENT_REGISTRATION") {
    return "OmniRush.ai could not register or identify its OAuth client with the authorization server."
  }
  if (input.code === "MCP_OAUTH_CLIENT_REJECTED") {
    return "The authorization server rejected the OAuth client configured for this connection; the saved client was kept for an administrator to review."
  }
  if (input.phase === "AUTH_TOKEN_ACQUISITION" || input.phase === "CONTINUITY_REFRESH") {
    return "The authorization server rejected the code or token refresh exchange."
  }
  if (input.phase === "AUTH_USER_OR_WORKLOAD") {
    return input.code === "MCP_OAUTH_ACCESS_DENIED"
      ? "The provider did not grant authorization for this MCP connection."
      : "The provider rejected the authorization request before issuing a code."
  }
  if (input.phase === "AUTH_RESOURCE_VALIDATION") {
    return "The MCP resource rejected the supplied authorization."
  }
  if (input.phase === "MCP_VERSION") {
    return "The MCP client and server could not agree on a supported protocol version."
  }
  if (input.phase === "MCP_INITIALIZE" || input.phase === "MCP_INITIALIZED") {
    return "The MCP lifecycle failed during initialization."
  }
  if (input.phase === "MCP_TOOL_DISCOVERY") {
    return input.code === "MCP_CATALOG_CURSOR_LOOP"
      ? "The MCP server repeated a tool-catalog cursor, so OmniRush.ai stopped safely."
      : "OmniRush.ai could not retrieve a complete, valid MCP tool catalog."
  }
  if (input.phase === "MCP_TOOL_EXECUTION" || input.phase === "PROVIDER_EXECUTION") {
    return "The MCP connection is established, but the requested provider operation failed."
  }
  if (input.phase === "PROVIDER_AUTHORIZATION") {
    return "The MCP connection is established, but provider policy denied the requested operation."
  }
  if (input.phase === "CONTINUITY_SESSION") {
    return "The MCP session expired or was rejected and must be initialized again."
  }
  if (input.phase === "HTTP_ROUTING") {
    return "Den reached the host, but the configured path did not behave like the intended MCP endpoint."
  }
  if (input.category === "mcp_tool_input_invalid") {
    if (input.code === "MCP_TOOL_ARGUMENT_INVALID_JSON") {
      return "OmniRush.ai rejected the tool arguments before contacting the provider because they are not valid JSON data (for example an undefined field, a non-finite number, or a non-plain object)."
    }
    if (input.code === "MCP_TOOL_ARGUMENT_SIZE_LIMIT") {
      return "OmniRush.ai rejected the tool arguments before contacting the provider because they exceed the 1 MiB argument limit."
    }
    if (input.code === "MCP_TOOL_ARGUMENT_DEPTH_LIMIT") {
      return "OmniRush.ai rejected the tool arguments before contacting the provider because they are nested too deeply."
    }
    if (input.code === "MCP_TOOL_ARGUMENT_CYCLE") {
      return "OmniRush.ai rejected the tool arguments before contacting the provider because they contain a circular reference."
    }
    return "OmniRush.ai rejected the tool arguments before contacting the provider because they are invalid."
  }
  return "The MCP connection failed before OmniRush.ai could complete the protocol lifecycle."
}

type Classification = Omit<ExternalMcpDiagnostic, "referenceId" | "highestPassed" | "message">

function isUninformativeClassification(input: Pick<Classification, "phase" | "category" | "code">): boolean {
  return input.code === `MCP_${input.phase}` && (
    input.category === "oauth_failure"
    || input.category === "mcp_protocol_failure"
    || input.category === "connection_failure"
  )
}

function logProviderToolEvidence(input: {
  referenceId: string
  evidence: ProviderToolContentEvidence
  diagnosticCode: string
  providerStatus?: number
  providerCode?: string
  providerRequestId?: string
}): void {
  if (!input.evidence.excerpt) return
  console.error("external_mcp_provider_tool_evidence", {
    referenceId: input.referenceId,
    diagnosticCode: input.diagnosticCode,
    excerpt: input.evidence.excerpt,
    payloadBytes: input.evidence.payloadBytes,
    ...(input.providerStatus === undefined ? {} : { providerStatus: input.providerStatus }),
    ...(input.providerCode ? { providerCode: input.providerCode } : {}),
    ...(input.providerRequestId ? { providerRequestId: input.providerRequestId } : {}),
  })
}

function httpClassification(input: {
  phase: ExternalMcpDiagnosticPhase
  status: number
  hasAuthorization: boolean
  bearerChallenge: boolean
  insufficientScope: boolean
  hasSession: boolean
  contentType: string
}): Classification | null {
  const { phase, status } = input
  if (status === 404 && input.hasSession) {
    return {
      phase: "CONTINUITY_SESSION",
      category: "mcp_session_expired",
      code: "MCP_SESSION_NOT_FOUND",
      retryable: true,
      actionOwner: "omnirush",
      operatorAction: "Reinitialize the MCP session, then retry the operation once.",
    }
  }
  if (status === 404 && phase.startsWith("MCP_")) {
    return {
      phase: "HTTP_ROUTING",
      category: "endpoint_not_found",
      code: "MCP_HTTP_404",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Verify the complete MCP endpoint path, including any provider tenant or instance prefix.",
    }
  }
  if ((status === 406 || status === 415) && phase.startsWith("MCP_")) {
    return {
      phase: "MCP_TRANSPORT",
      category: "mcp_transport_negotiation",
      code: `MCP_HTTP_${status}`,
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Verify Streamable HTTP content negotiation and the provider's supported MCP transport.",
    }
  }
  if (status === 429) {
    return {
      phase,
      category: "provider_throttled",
      code: "MCP_HTTP_429",
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: "Wait for the provider rate limit to reset, then retry with bounded backoff.",
    }
  }
  if (status >= 500) {
    return {
      phase,
      category: "provider_unavailable",
      code: `MCP_HTTP_${status}`,
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: "Check provider availability and reverse-proxy logs using the diagnostic reference, then retry.",
    }
  }
  if ((status === 401 || status === 403) && phase.startsWith("MCP_") && input.hasAuthorization) {
    // A 401 is itself an authentication challenge. A 403 is ambiguous for
    // enterprise providers: only a Bearer/insufficient_scope challenge means
    // token validation; an ordinary tools/* 403 is usually an ACL/role denial.
    if (status === 401 || input.bearerChallenge || input.insufficientScope) {
      return {
        phase: "AUTH_RESOURCE_VALIDATION",
        category: input.insufficientScope ? "oauth_insufficient_scope" : "oauth_resource_rejected",
        code: input.insufficientScope ? "MCP_OAUTH_INSUFFICIENT_SCOPE" : `MCP_OAUTH_HTTP_${status}`,
        retryable: status === 401,
        actionOwner: input.insufficientScope ? "organization_admin" : "member",
        operatorAction: input.insufficientScope
          ? "Grant the provider scopes required by this MCP resource and reconnect."
          : "Reconnect the provider account and verify token audience, tenant, and resource binding.",
      }
    }
    if (status === 403 && (phase === "MCP_TOOL_DISCOVERY" || phase === "MCP_TOOL_EXECUTION")) {
      return {
        phase: "PROVIDER_AUTHORIZATION",
        category: "provider_policy_denied",
        code: "MCP_PROVIDER_HTTP_403",
        retryable: false,
        actionOwner: "provider_admin",
        operatorAction: "Grant the provider role, ACL, or application permission required for this operation.",
      }
    }
  }
  if (status >= 400) {
    return {
      phase,
      category: "http_failure",
      code: `MCP_HTTP_${status}`,
      retryable: status === 408,
      actionOwner: "provider_admin",
      operatorAction: "Inspect provider and proxy logs for the failing HTTP request using the diagnostic reference.",
    }
  }
  if (phase.startsWith("MCP_") && input.contentType === "text/html") {
    return {
      phase: "HTTP_ROUTING",
      category: "unexpected_html",
      code: "MCP_HTTP_HTML_RESPONSE",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Verify the MCP path is not a sign-in page, portal route, or proxy-generated HTML response.",
    }
  }
  if (phase === "MCP_INITIALIZED" && (status === 202 || status === 204)) return null
  if (phase.startsWith("MCP_") && input.contentType !== "application/json" && input.contentType !== "text/event-stream") {
    return {
      phase: "MCP_TRANSPORT",
      category: "unexpected_content_type",
      code: "MCP_HTTP_CONTENT_TYPE",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Return an MCP JSON or event-stream response with a standards-compliant Content-Type header.",
    }
  }
  return null
}

function classifyByCode(code: string): Classification | null {
  if (code === "MCP_OAUTH_AUTHORIZATION_ID_REQUIRED") {
    return {
      phase: "CONFIGURATION",
      category: "oauth_authorization_transaction_invalid",
      code,
      retryable: false,
      actionOwner: "omnirush",
      operatorAction: "Start OAuth through Den so the callback is bound to a signed, expiring authorization transaction.",
    }
  }
  if (code === "MCP_OAUTH_AUTHORIZATION_MISSING" || code === "MCP_OAUTH_AUTHORIZATION_EXPIRED") {
    return {
      phase: "AUTH_TOKEN_ACQUISITION",
      category: "oauth_authorization_transaction_expired",
      code,
      retryable: true,
      actionOwner: "member",
      operatorAction: "Start Connect again and complete provider authorization before the signed transaction expires.",
    }
  }
  if (code === "MCP_OAUTH_AUTHORIZATION_CLIENT_CHANGED") {
    return {
      phase: "AUTH_CLIENT_REGISTRATION",
      category: "oauth_client_registration_changed",
      code,
      retryable: true,
      actionOwner: "organization_admin",
      operatorAction: "Retry Connect using the OAuth client registration that won the concurrent update.",
    }
  }
  if (code === "MCP_OAUTH_CLIENT_EXPIRED") {
    return {
      phase: "AUTH_CLIENT_REGISTRATION",
      category: "oauth_client_registration_expired",
      code,
      retryable: true,
      actionOwner: "organization_admin",
      operatorAction: "Renew the provider client secret or client registration, then start Connect again.",
    }
  }
  if (code === "MCP_OAUTH_CLIENT_REJECTED") {
    return {
      phase: "AUTH_TOKEN_ACQUISITION",
      category: "oauth_client_rejected",
      code,
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Compare the saved OAuth client ID, secret, and token endpoint authentication method with the provider application, then start Connect again.",
    }
  }
  if (code === "MCP_OAUTH_CREDENTIAL_EXPIRED") {
    return {
      phase: "CONTINUITY_REFRESH",
      category: "oauth_credential_expired",
      code,
      retryable: true,
      actionOwner: "member",
      operatorAction: "Reconnect the provider account because the access token expired without a usable refresh token.",
    }
  }
  if (code === "MCP_OAUTH_CREDENTIAL_CHANGED") {
    return {
      phase: "CONTINUITY_REFRESH",
      category: "oauth_credential_changed",
      code,
      retryable: true,
      actionOwner: "omnirush",
      operatorAction: "Retry with the newer OAuth credential after the concurrent refresh completes.",
    }
  }
  if (code === "MCP_OAUTH_CONFIGURATION_CHANGED") {
    return {
      phase: "AUTH_CLIENT_REGISTRATION",
      category: "oauth_configuration_changed",
      code,
      retryable: true,
      actionOwner: "omnirush",
      operatorAction: "Reload the MCP connection and retry client registration against its current OAuth issuer.",
    }
  }
  if (code === "MCP_OAUTH_CONFIGURATION_REQUIRED") {
    return {
      phase: "AUTH_CLIENT_REGISTRATION",
      category: "oauth_configuration_required",
      code,
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Create a provider OAuth application, allowlist the shared callback, and save its client ID and optional secret before reconnecting.",
    }
  }
  if (code === "MCP_OAUTH_ISSUER_MISMATCH") {
    return {
      phase: "AUTH_ISSUER_DISCOVERY",
      category: "oauth_issuer_mismatch",
      code,
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Repeat requirements discovery and select an authorization server advertised by the protected resource.",
    }
  }
  if (code === "MCP_OAUTH_PERSISTENCE_INVALID") {
    return {
      phase: "CONFIGURATION",
      category: "oauth_persistence_invalid",
      code,
      retryable: false,
      actionOwner: "omnirush",
      operatorAction: "Inspect the encrypted OAuth record and adapter validation using the diagnostic reference.",
    }
  }
  if (code === "MCP_LIFECYCLE_DEADLINE") {
    return {
      phase: "CONTINUITY_REFRESH",
      category: "lifecycle_deadline",
      code,
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: "Retry after provider latency allows the credential transaction to commit within its lifecycle deadline.",
    }
  }
  if (
    code === "MCP_TOOL_ARGUMENT_SIZE_LIMIT"
    || code === "MCP_TOOL_ARGUMENT_DEPTH_LIMIT"
    || code === "MCP_TOOL_ARGUMENT_CYCLE"
    || code === "MCP_TOOL_ARGUMENT_INVALID_JSON"
  ) {
    return {
      phase: "CONFIGURATION",
      category: "mcp_tool_input_invalid",
      code,
      retryable: false,
      actionOwner: "omnirush",
      operatorAction: "Correct and bound the tool arguments before attempting the provider operation again.",
    }
  }
  const normalizedCode = code === "ConnectionRefused"
    ? "ECONNREFUSED"
    : code === "ConnectionReset"
      ? "ECONNRESET"
      : code === "ConnectionTimedOut" || code === "Timeout"
        ? "ETIMEDOUT"
        : code
  if (normalizedCode === "ENOTFOUND" || normalizedCode === "EAI_AGAIN") {
    return {
      phase: "NETWORK_DNS",
      category: "dns_failure",
      code: `MCP_${normalizedCode}`,
      retryable: normalizedCode === "EAI_AGAIN",
      actionOwner: "network_admin",
      operatorAction: "Verify DNS resolution and Den egress for the MCP host.",
    }
  }
  if (TLS_ERROR_CODES.has(normalizedCode)) {
    return {
      phase: "NETWORK_TLS",
      category: "tls_failure",
      code: `MCP_${normalizedCode}`,
      retryable: false,
      actionOwner: "network_admin",
      operatorAction: "Verify the provider certificate chain, hostname, and Den trust store.",
    }
  }
  if (TCP_ERROR_CODES.has(normalizedCode)) {
    return {
      phase: "NETWORK_TCP",
      category: "network_failure",
      code: `MCP_${normalizedCode}`,
      retryable: normalizedCode === "ECONNRESET" || normalizedCode === "ETIMEDOUT" || normalizedCode.startsWith("UND_ERR_"),
      actionOwner: "network_admin",
      operatorAction: "Verify provider allowlists, firewall rules, proxy requirements, and service availability from Den.",
    }
  }
  return null
}

function classifyError(error: unknown, fallbackPhase: ExternalMcpDiagnosticPhase): Classification {
  // The enterprise client aborts with a RequestTimeout MCP error of its own, so
  // check for our marker before any JSON-RPC code is read as the provider's.
  if (error instanceof ExternalMcpLifecycleDeadlineError || isEnterpriseMcpLifecycleDeadline(error)) {
    return {
      phase: fallbackPhase,
      category: "lifecycle_deadline",
      code: "MCP_LIFECYCLE_DEADLINE",
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: fallbackPhase === "MCP_TOOL_EXECUTION"
        ? "Retry the capability, and reduce provider latency for this tool if it keeps running past the bounded deadline."
        : "Reduce provider latency or catalog pagination so the complete MCP lifecycle finishes within the bounded deadline, then retry.",
    }
  }
  if (error instanceof ExternalMcpResponseBodyLimitError) {
    return {
      phase: fallbackPhase,
      category: "response_too_large",
      code: "MCP_RESPONSE_BODY_LIMIT",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Reduce the provider response size, tool catalog, or event-stream payload before retrying.",
    }
  }
  if (error instanceof PrivateUrlError) {
    return {
      phase: "CONFIGURATION",
      category: "security_blocked",
      code: "MCP_URL_BLOCKED",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Use a public HTTPS MCP URL or change the deployment's private-network policy through security review.",
    }
  }
  if (hasForbiddenPortMessage(error)) {
    return {
      phase: "CONFIGURATION",
      category: "unsupported_endpoint_port",
      code: "MCP_FETCH_FORBIDDEN_PORT",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Use the provider's supported HTTPS MCP port or place the endpoint behind a standard HTTPS listener.",
    }
  }

  const code = errorCode(error)
  if (code) {
    const classified = classifyByCode(code)
    if (classified) return classified
  }

  const providerAuthorization = providerAuthorizationRequired(error)
  if (providerAuthorization) {
    return providerAuthorizationClassification(providerAuthorization.connectUrl)
  }

  const numericCode = numericErrorCode(error)
  if (numericCode === -32001) {
    if (!localRequestTimeout(error)) return providerDeclaredErrorClassification()
    return {
      phase: fallbackPhase,
      category: "request_timeout",
      code: "MCP_REQUEST_TIMEOUT",
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: "Check provider latency and retry after the current MCP request can complete within its bounded timeout.",
    }
  }
  if (numericCode === -32602 && fallbackPhase === "MCP_TOOL_EXECUTION") {
    return {
      phase: "MCP_TOOL_EXECUTION",
      category: "mcp_tool_input_invalid",
      code: "MCP_INVALID_PARAMS",
      retryable: false,
      actionOwner: "omnirush",
      operatorAction: "Correct the tool arguments using the latest advertised input schema; do not retry the same arguments unchanged.",
    }
  }
  if (numericCode !== undefined) return providerDeclaredErrorClassification()

  const name = errorName(error)
  if (name === "InvalidClientError" || name === "UnauthorizedClientError" || name === "InvalidClientMetadataError") {
    return {
      phase: "AUTH_CLIENT_REGISTRATION",
      category: "oauth_client_registration",
      code: "MCP_OAUTH_CLIENT_REJECTED",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Verify the client registration, redirect URI, client type, and token endpoint authentication method.",
    }
  }
  if (name === "InvalidGrantError") {
    return {
      phase: fallbackPhase === "CONTINUITY_REFRESH" ? fallbackPhase : "AUTH_TOKEN_ACQUISITION",
      category: "oauth_token_failure",
      code: "MCP_OAUTH_INVALID_GRANT",
      retryable: false,
      actionOwner: "member",
      operatorAction: "Restart authorization; if it repeats, verify redirect URI and PKCE state.",
    }
  }
  if (name === "InvalidScopeError") {
    return {
      phase: "AUTH_USER_OR_WORKLOAD",
      category: "oauth_invalid_scope",
      code: "MCP_OAUTH_INVALID_SCOPE",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Correct the configured provider scopes and restart authorization.",
    }
  }
  if (name === "InvalidTargetError") {
    return {
      phase: "AUTH_RESOURCE_VALIDATION",
      category: "oauth_invalid_target",
      code: "MCP_OAUTH_INVALID_TARGET",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Correct the configured MCP resource or token audience and restart authorization.",
    }
  }
  if (name === "InsufficientScopeError") {
    return {
      phase: "AUTH_RESOURCE_VALIDATION",
      category: "oauth_insufficient_scope",
      code: "MCP_OAUTH_INSUFFICIENT_SCOPE",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Grant the MCP resource scopes required by the provider and restart authorization.",
    }
  }
  if (name === "InvalidTokenError") {
    return {
      phase: "AUTH_RESOURCE_VALIDATION",
      category: "oauth_invalid_token",
      code: "MCP_OAUTH_INVALID_TOKEN",
      retryable: false,
      actionOwner: "member",
      operatorAction: "Reconnect the MCP account to obtain a token for the configured resource.",
    }
  }
  if (name === "UnsupportedTokenTypeError") {
    return {
      phase: fallbackPhase,
      category: "oauth_unsupported_token_type",
      code: "MCP_OAUTH_UNSUPPORTED_TOKEN_TYPE",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Configure the authorization server to issue a token type supported by the MCP client and resource.",
    }
  }
  if (name === "MethodNotAllowedError") {
    return {
      phase: fallbackPhase,
      category: "oauth_method_not_allowed",
      code: "MCP_OAUTH_METHOD_NOT_ALLOWED",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Verify the provider OAuth endpoint path and its supported HTTP method.",
    }
  }
  if (name === "TooManyRequestsError") {
    return {
      phase: fallbackPhase,
      category: "oauth_provider_throttled",
      code: "MCP_OAUTH_TOO_MANY_REQUESTS",
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: "Wait for the provider rate limit to reset, then retry with bounded backoff.",
    }
  }
  if (name === "AccessDeniedError") {
    return {
      phase: "AUTH_USER_OR_WORKLOAD",
      category: "oauth_access_denied",
      code: "MCP_OAUTH_ACCESS_DENIED",
      retryable: false,
      actionOwner: "member",
      operatorAction: "Restart authorization and grant consent; if policy blocks consent, contact the provider administrator.",
    }
  }
  if (name === "InvalidRequestError" || name === "UnsupportedGrantTypeError" || name === "UnsupportedResponseTypeError") {
    return {
      phase: fallbackPhase,
      category: "oauth_request_rejected",
      code: name === "UnsupportedGrantTypeError"
        ? "MCP_OAUTH_UNSUPPORTED_GRANT_TYPE"
        : name === "UnsupportedResponseTypeError"
          ? "MCP_OAUTH_UNSUPPORTED_RESPONSE_TYPE"
          : "MCP_OAUTH_INVALID_REQUEST",
      retryable: false,
      actionOwner: "organization_admin",
      operatorAction: "Verify the provider OAuth flow, redirect URI, PKCE, and registered grant/response types.",
    }
  }
  if (name === "TemporarilyUnavailableError" || name === "ServerError") {
    return {
      phase: fallbackPhase,
      category: "oauth_provider_unavailable",
      code: name === "TemporarilyUnavailableError" ? "MCP_OAUTH_TEMPORARILY_UNAVAILABLE" : "MCP_OAUTH_SERVER_ERROR",
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: "Check authorization-server availability and retry with bounded backoff.",
    }
  }
  if (hasUnsupportedVersionMessage(error)) {
    return {
      phase: "MCP_VERSION",
      category: "mcp_version_mismatch",
      code: "MCP_UNSUPPORTED_VERSION",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Configure the provider to support an MCP protocol version compatible with OmniRush.ai.",
    }
  }

  const phase = fallbackPhase
  const category = phase.startsWith("AUTH_")
    ? "oauth_failure"
    : phase.startsWith("MCP_") || phase.startsWith("CONTINUITY_")
      ? "mcp_protocol_failure"
      : "connection_failure"
  return {
    phase,
    category,
    code: `MCP_${phase}`,
    retryable: phase === "NETWORK_TCP" || phase === "MCP_TRANSPORT",
    actionOwner: phase.startsWith("AUTH_") ? "organization_admin" : "provider_admin",
    operatorAction: phase.startsWith("AUTH_")
      ? "Verify the endpoint's OAuth metadata and provider application configuration."
      : "Inspect the provider's MCP logs using the diagnostic reference and retry after correcting the named layer.",
  }
}

export class ExternalMcpDiagnosticError extends Error {
  readonly diagnostic: ExternalMcpDiagnostic
  readonly safeCauseChain: ExternalMcpSafeCause[]
  #providerResponseLog: ProviderResponseLog | undefined

  constructor(diagnostic: ExternalMcpDiagnostic, cause?: unknown, providerResponseLog?: ProviderResponseLog) {
    super(diagnostic.message, cause === undefined ? undefined : { cause })
    this.name = "ExternalMcpDiagnosticError"
    this.diagnostic = diagnostic
    this.safeCauseChain = cause === undefined ? [] : safeExternalMcpCauseChain(cause)
    this.#providerResponseLog = providerResponseLog
  }

  providerResponseForLog(): ProviderResponseLog | undefined {
    return this.#providerResponseLog
  }
}

export class ExternalMcpDiagnosticTracker {
  readonly referenceId: string
  private readonly credentialContext?: {
    authType: "oauth" | "apikey" | "none"
    credentialMode: "shared" | "per_member"
  }
  private phase: ExternalMcpDiagnosticPhase = "CONFIGURATION"
  private highestPassed: ExternalMcpHealthLevel = "configured"
  private lastFailedPhase: ExternalMcpDiagnosticPhase | null = null
  private capturedFailure: { phase: ExternalMcpDiagnosticPhase; error: unknown } | null = null
  private lastHttpStatus: number | null = null
  private forcedClassification: Classification | null = null
  private outbound: ExternalMcpSafeOutbound | null = null
  private providerRequestId: string | null = null
  private providerDeclaredError: ProviderDeclaredErrorEvidence | null = null
  private providerResponseExcerpt: string | null = null
  private providerResponseLog: ProviderResponseLog | null = null
  private providerResponseExcerptPhase: ExternalMcpDiagnosticPhase | null = null
  private backgroundFailure: { phase: ExternalMcpDiagnosticPhase; error: unknown } | null = null

  constructor(referenceId: string, credentialContext?: {
    authType: "oauth" | "apikey" | "none"
    credentialMode: "shared" | "per_member"
  }) {
    this.referenceId = referenceId
    this.credentialContext = credentialContext
  }

  get activePhase(): ExternalMcpDiagnosticPhase {
    return this.phase
  }

  begin(phase: ExternalMcpDiagnosticPhase): void {
    this.phase = phase
    this.lastFailedPhase = null
    this.capturedFailure = null
    this.lastHttpStatus = null
    this.forcedClassification = null
    this.providerRequestId = null
    this.providerDeclaredError = null
    this.providerResponseExcerpt = null
    this.providerResponseLog = null
    this.providerResponseExcerptPhase = null
    this.backgroundFailure = null
  }

  passed(phase: ExternalMcpDiagnosticPhase, health?: ExternalMcpHealthLevel): void {
    this.phase = phase
    this.lastFailedPhase = null
    this.capturedFailure = null
    this.forcedClassification = null
    if (health && HEALTH_RANK[health] > HEALTH_RANK[this.highestPassed]) {
      this.highestPassed = health
    }
  }

  failed(phase: ExternalMcpDiagnosticPhase, classification?: Classification): void {
    this.phase = phase
    this.lastFailedPhase = phase
    this.forcedClassification = classification ?? null
  }

  captureFailure(phase: ExternalMcpDiagnosticPhase, error: unknown): void {
    this.failed(phase)
    this.capturedFailure = { phase, error }
  }

  captureBackgroundFailure(phase: ExternalMcpDiagnosticPhase, error: unknown): void {
    this.backgroundFailure = { phase, error }
  }

  captureResponseBodyLimit(phase: ExternalMcpDiagnosticPhase, error: unknown): void {
    const classification = classifyError(error, phase)
    this.failed(phase, classification)
    this.capturedFailure = { phase, error }
  }

  captureBackgroundResponseBodyLimit(phase: ExternalMcpDiagnosticPhase, error: unknown): void {
    this.backgroundFailure = { phase, error }
  }

  recordHttpStatus(status: number): void {
    this.lastHttpStatus = status
  }

  recordOutbound(rawUrl: string | URL): void {
    this.outbound = safeExternalMcpOutbound(rawUrl)
  }

  recordProviderRequestId(headers: Headers): void {
    for (const name of [
      "x-ms-request-id",
      "x-ms-correlation-request-id",
      "x-servicenow-request-id",
      "x-correlation-id",
      "x-transaction-id",
      "request-id",
      "x-request-id",
    ]) {
      const value = safeProviderRequestId(headers.get(name))
      if (value) {
        this.providerRequestId = value
        return
      }
    }
  }

  recordProviderDeclaredError(evidence: ProviderDeclaredErrorEvidence): void {
    this.providerDeclaredError = evidence
  }

  recordProviderResponseExcerpt(input: {
    memberExcerpt?: string
    log: ProviderResponseLog
    phase: ExternalMcpDiagnosticPhase
  }): void {
    this.providerResponseExcerpt = input.memberExcerpt ?? null
    this.providerResponseLog = input.log
    this.providerResponseExcerptPhase = input.phase
  }

  providerToolError(result?: unknown): ExternalMcpDiagnosticError {
    const structuredContent = isRecord(result) && isRecord(result.structuredContent)
      ? result.structuredContent
      : null
    const structuredProviderStatus = validProviderStatus(structuredContent?.providerStatus)
    const providerCategory = typeof structuredContent?.category === "string" ? structuredContent.category : undefined
    const evidence = providerToolContentEvidence(result)
    const providerStatus = structuredProviderStatus ?? evidence.providerStatus
    const providerCode = evidence.providerCode
    const requestId = safeProviderRequestId(structuredContent?.requestId) ?? evidence.providerRequestId
    if (requestId) this.providerRequestId = requestId

    const providerInvalidArguments = [
      "invalid_arguments",
      "invalid_params",
      "validation_error",
    ].includes(providerCategory ?? "") || isProviderInputValidationExcerpt(evidence.excerpt)
    const providerPolicyDenied = structuredProviderStatus === 403
      ? providerCategory === "provider_policy"
      : evidence.providerStatus === 403
    const classificationBase: Classification = providerInvalidArguments
      ? {
          phase: "MCP_TOOL_EXECUTION",
          category: "mcp_tool_input_invalid",
          code: "MCP_PROVIDER_INVALID_PARAMS",
          retryable: false,
          actionOwner: "omnirush",
          operatorAction: "Correct the tool arguments using the latest advertised input schema; do not retry the same arguments unchanged.",
        }
      : providerPolicyDenied
      ? {
          phase: "PROVIDER_AUTHORIZATION",
          category: "provider_policy_denied",
          code: "MCP_PROVIDER_HTTP_403",
          retryable: false,
          actionOwner: "provider_admin",
          operatorAction: "Grant the provider role, ACL, or application permission required for this operation.",
        }
      : providerStatus === 429
        ? {
            phase: "PROVIDER_EXECUTION",
            category: "provider_throttled",
            code: "MCP_PROVIDER_HTTP_429",
            retryable: true,
            actionOwner: "provider_admin",
            operatorAction: "Wait for the provider rate limit to reset, then retry with bounded backoff.",
          }
        : {
            phase: "PROVIDER_EXECUTION",
            category: "provider_tool_error",
            code: "MCP_PROVIDER_TOOL_ERROR",
            retryable: false,
            actionOwner: "provider_admin",
            operatorAction: "Inspect the provider operation result and provider logs using the diagnostic reference.",
          }
    const classification: Classification = {
      ...classificationBase,
      ...(providerStatus === undefined ? {} : { providerStatus }),
      ...(providerCode ? { providerCode } : {}),
      payloadBytes: evidence.payloadBytes,
      ...(evidence.excerpt ? { providerErrorMessage: evidence.excerpt } : {}),
    }
    logProviderToolEvidence({
      referenceId: this.referenceId,
      evidence,
      diagnosticCode: classification.code,
      ...(providerStatus === undefined ? {} : { providerStatus }),
      ...(providerCode ? { providerCode } : {}),
      ...(requestId ? { providerRequestId: requestId } : {}),
    })
    this.failed(classification.phase, classification)
    return this.error(new Error("Provider returned an MCP tool error result."), classification.phase)
  }

  error(error: unknown, fallbackPhase = this.lastFailedPhase ?? this.phase): ExternalMcpDiagnosticError {
    if (error instanceof ExternalMcpDiagnosticError) return error
    let source = { phase: fallbackPhase, error }
    let inferredClassification = classifyError(error, fallbackPhase)
    const thrownProviderEvidence = providerDeclaredErrorFromError(error, fallbackPhase)
    const thrownClassificationIsUninformative = isUninformativeClassification(inferredClassification)
    if (thrownClassificationIsUninformative && this.providerDeclaredError) {
      const evidence = this.providerDeclaredError
      source = { phase: evidence.phase, error }
      inferredClassification = evidence.connectUrl
        ? providerAuthorizationClassification(evidence.connectUrl)
        : providerDeclaredErrorClassification()
    } else if (thrownClassificationIsUninformative && this.capturedFailure) {
      const capturedClassification = classifyError(this.capturedFailure.error, this.capturedFailure.phase)
      if (!isUninformativeClassification(capturedClassification)) {
        source = this.capturedFailure
        inferredClassification = capturedClassification
      } else if (this.backgroundFailure) {
        source = this.backgroundFailure
        inferredClassification = classifyError(this.backgroundFailure.error, this.backgroundFailure.phase)
      }
    }
    const sourceCode = errorCode(source.error)
    const sourceIsApplicationOwnedOAuthFailure = sourceCode?.startsWith("MCP_OAUTH_") === true
      || sourceCode === "MCP_LIFECYCLE_DEADLINE"
    const classified = this.forcedClassification
      && !TYPED_OAUTH_ERROR_NAMES.has(errorName(source.error))
      && !sourceIsApplicationOwnedOAuthFailure
      && inferredClassification.phase !== "MCP_VERSION"
      ? this.forcedClassification
      : inferredClassification
    const classification: Classification = classified.actionOwner === "member"
      && this.credentialContext
      && (classified.phase.startsWith("AUTH_") || classified.phase === "CONTINUITY_REFRESH")
      && this.credentialContext.credentialMode === "shared"
      ? {
          ...classified,
          actionOwner: "organization_admin",
          operatorAction: this.credentialContext.authType === "apikey"
            ? "Update the organization-managed API key for this MCP connection, then retry."
            : "Reconnect the organization-managed provider account, then retry.",
        }
      : classified
    const jsonRpcCode = numericErrorCode(error)
      ?? this.providerDeclaredError?.jsonRpcCode
      ?? numericErrorCode(source.error)
    const providerEvidence = this.providerDeclaredError
      ?? thrownProviderEvidence
      ?? providerDeclaredErrorFromError(source.error, source.phase)
    const capturedOAuthProviderDetail = this.providerResponseExcerpt
      && this.providerResponseExcerptPhase
      && isOAuthTokenPhase(this.providerResponseExcerptPhase)
      ? this.providerResponseExcerpt.slice(0, EXTERNAL_MCP_OAUTH_PROVIDER_DETAIL_CHARS)
      : undefined
    const safeOAuthProviderDetail = oauthProviderDetail(error)
      ?? oauthProviderDetail(source.error)
      ?? capturedOAuthProviderDetail
    const providerErrorMessage = providerEvidence?.message ?? safeOAuthProviderDetail
    const providerErrorData = providerEvidence?.dataExcerpt
    const diagnosticWithoutMessage = {
      referenceId: this.referenceId,
      highestPassed: this.highestPassed,
      ...classification,
      ...(jsonRpcCode === undefined ? {} : { jsonRpcCode }),
      ...(providerErrorMessage ? { providerErrorMessage } : {}),
      ...(providerErrorData ? { providerErrorData } : {}),
    }
    const diagnostic: ExternalMcpDiagnostic = {
      ...diagnosticWithoutMessage,
      message: safeMessageFor({
        ...diagnosticWithoutMessage,
        ...(safeOAuthProviderDetail ? { providerDetail: safeOAuthProviderDetail } : {}),
      }),
      ...(this.lastHttpStatus === null ? {} : { httpStatus: this.lastHttpStatus }),
      ...(classification.phase === source.phase ? {} : { operationPhase: source.phase }),
      ...(this.outbound ? { outbound: this.outbound } : {}),
      ...(this.providerRequestId ? { providerRequestId: this.providerRequestId } : {}),
      ...(this.providerResponseExcerpt ? { providerResponseExcerpt: this.providerResponseExcerpt } : {}),
    }
    return new ExternalMcpDiagnosticError(
      diagnostic,
      error,
      this.providerResponseLog ?? undefined,
    )
  }
}

function requestBodyText(init?: RequestInit): string | null {
  if (typeof init?.body === "string") return init.body
  if (init?.body instanceof URLSearchParams) return init.body.toString()
  return null
}

function requestHeader(init: RequestInit | undefined, name: string): string | null {
  if (!init?.headers) return null
  return new Headers(init.headers).get(name)
}

function jsonRpcMethod(body: string | null): string | null {
  if (!body || body.length > 64_000) return null
  try {
    const parsed: unknown = JSON.parse(body)
    return isRecord(parsed) && typeof parsed.method === "string" ? parsed.method : null
  } catch {
    return null
  }
}

function requestPhase(input: string | URL, init: RequestInit | undefined, endpoint: URL): ExternalMcpDiagnosticPhase {
  const url = new URL(String(input))
  const path = url.pathname
  if (path.includes("/.well-known/oauth-protected-resource")) return "AUTH_RESOURCE_DISCOVERY"
  if (path.includes("/.well-known/oauth-authorization-server") || path.includes("/.well-known/openid-configuration")) {
    return "AUTH_ISSUER_DISCOVERY"
  }

  const body = requestBodyText(init)
  const contentType = requestHeader(init, "content-type") ?? ""
  if (contentType.includes("application/x-www-form-urlencoded") && body) {
    const form = new URLSearchParams(body)
    return form.get("grant_type") === "refresh_token" ? "CONTINUITY_REFRESH" : "AUTH_TOKEN_ACQUISITION"
  }
  if (contentType.includes("application/json") && body?.includes("\"redirect_uris\"")) {
    return "AUTH_CLIENT_REGISTRATION"
  }

  if (url.origin === endpoint.origin && url.pathname === endpoint.pathname) {
    const method = jsonRpcMethod(body)
    // server/discover is the modern wire's protocol negotiation; it shares
    // the initialize phase so its unauthenticated bearer challenge is
    // suppressed the same way.
    if (method === "server/discover" || method === "initialize") return "MCP_INITIALIZE"
    if (method === "notifications/initialized") return "MCP_INITIALIZED"
    if (method === "tools/list") return "MCP_TOOL_DISCOVERY"
    if (method === "tools/call") return "MCP_TOOL_EXECUTION"
    return "MCP_TRANSPORT"
  }
  return "HTTP_ROUTING"
}

function healthForPhase(phase: ExternalMcpDiagnosticPhase): ExternalMcpHealthLevel | undefined {
  if (phase === "HTTP_ROUTING" || phase === "AUTH_RESOURCE_DISCOVERY" || phase === "AUTH_ISSUER_DISCOVERY" || phase === "AUTH_CLIENT_REGISTRATION") {
    return "reachable"
  }
  // An HTTP response proves reachability only. Higher health levels are
  // advanced by parsed OAuth/MCP operations after schema, lifecycle, and
  // pagination checks succeed; a 200 HTML page must never become
  // protocol_ready or catalog_ready.
  if (phase.startsWith("MCP_") || phase === "AUTH_RESOURCE_VALIDATION") return "reachable"
  return undefined
}

function responseBodyLimit(contentType: string): number {
  return contentType === "text/event-stream"
    ? EXTERNAL_MCP_SSE_RESPONSE_LIMIT_BYTES
    : EXTERNAL_MCP_JSON_RESPONSE_LIMIT_BYTES
}

function preserveResponseMetadata(target: Response, source: Response): void {
  for (const key of ["url", "redirected", "type"] as const) {
    try {
      Object.defineProperty(target, key, { configurable: true, value: source[key] })
    } catch {
      // These properties are diagnostic conveniences only. The status,
      // headers, and bounded body are the protocol-relevant fields.
    }
  }
}

function requestMethod(init: RequestInit | undefined): string {
  return (init?.method ?? "GET").toUpperCase()
}

function isMcpEndpointRequest(input: string | URL, endpoint: URL): boolean {
  const url = new URL(String(input))
  return url.origin === endpoint.origin && url.pathname === endpoint.pathname
}

function isBackgroundMcpEndpointRequest(input: string | URL, init: RequestInit | undefined, endpoint: URL): boolean {
  if (!isMcpEndpointRequest(input, endpoint)) return false
  const method = requestMethod(init)
  return (method === "GET" || method === "DELETE") && jsonRpcMethod(requestBodyText(init)) === null
}

function isProviderDeclaredErrorSniffEligible(input: {
  url: string | URL
  init: RequestInit | undefined
  endpoint: URL
  phase: ExternalMcpDiagnosticPhase
  response: Response
  contentType: string
}): boolean {
  return input.phase.startsWith("MCP_")
    && requestMethod(input.init) === "POST"
    && isMcpEndpointRequest(input.url, input.endpoint)
    && input.response.ok
    && input.contentType === "application/json"
}

function advertisedContentLength(response: Response): number | null {
  const advertisedLength = response.headers.get("content-length")
  if (!advertisedLength || !/^\d+$/.test(advertisedLength)) return null
  const length = Number(advertisedLength)
  return Number.isSafeInteger(length) ? length : null
}

async function responseTextWithinLimit(response: Response, limit: number): Promise<string | null> {
  if (!response.body) return null
  const reader = response.body.getReader()
  const chunks: Uint8Array[] = []
  let bytesRead = 0
  try {
    while (true) {
      const next = await reader.read()
      if (next.done) break
      bytesRead += next.value.byteLength
      if (bytesRead > limit) {
        void reader.cancel().catch(() => undefined)
        return null
      }
      chunks.push(next.value)
    }
  } catch {
    return null
  }
  const bytes = new Uint8Array(bytesRead)
  let offset = 0
  for (const chunk of chunks) {
    bytes.set(chunk, offset)
    offset += chunk.byteLength
  }
  return new TextDecoder().decode(bytes)
}

async function responseTextExcerptWithinLimit(response: Response, limit: number): Promise<string | null> {
  if (!response.body) return null
  const reader = response.body.getReader()
  const decoder = new TextDecoder()
  let text = ""
  try {
    while (text.length < limit) {
      const next = await reader.read()
      if (next.done) {
        text += decoder.decode()
        return text.slice(0, limit)
      }
      text += decoder.decode(next.value, { stream: true })
      if (text.length >= limit) {
        void reader.cancel().catch(() => undefined)
        return text.slice(0, limit)
      }
    }
    return text.slice(0, limit)
  } catch {
    return null
  }
}

async function providerResponseExcerpts(response: Response): Promise<{
  memberExcerpt?: string
  log: ProviderResponseLog
} | null> {
  try {
    const text = await responseTextExcerptWithinLimit(
      response.clone(),
      EXTERNAL_MCP_PROVIDER_RESPONSE_EXCERPT_CHARS,
    )
    if (text === null) return null
    const memberExcerpt = structuredProviderResponseExcerpt(text)
    return {
      ...(memberExcerpt ? { memberExcerpt } : {}),
      log: {
        contentType: providerResponseContentType(
          (response.headers.get("content-type") ?? "").split(";", 1)[0]?.trim().toLowerCase() ?? "",
        ),
        bodyChars: text.length,
        ...(memberExcerpt ? { excerpt: memberExcerpt } : {}),
      },
    }
  } catch {
    return null
  }
}

async function sniffProviderDeclaredError(input: {
  response: Response
  phase: ExternalMcpDiagnosticPhase
  tracker: ExternalMcpDiagnosticTracker
}): Promise<void> {
  const contentLength = advertisedContentLength(input.response)
  if (contentLength !== null && contentLength > EXTERNAL_MCP_PROVIDER_DECLARED_ERROR_SNIFF_LIMIT_BYTES) return
  let clone: Response
  try {
    clone = input.response.clone()
  } catch {
    return
  }
  const text = await responseTextWithinLimit(clone, EXTERNAL_MCP_PROVIDER_DECLARED_ERROR_SNIFF_LIMIT_BYTES)
  if (text === null) return
  try {
    const parsed: unknown = JSON.parse(text)
    const evidence = providerDeclaredErrorFromJson(parsed, input.phase)
    if (evidence) input.tracker.recordProviderDeclaredError(evidence)
  } catch {
    // Sniffing is best-effort diagnostic evidence; the SDK still receives the original body.
  }
}

async function boundedExternalMcpResponse(input: {
  response: Response
  contentType: string
  phase: ExternalMcpDiagnosticPhase
  tracker: ExternalMcpDiagnosticTracker
  background: boolean
  sniffProviderDeclaredError: boolean
}): Promise<Response> {
  if (input.sniffProviderDeclaredError) {
    // Clone before any original .body getter access. Bun breaks the tee if the
    // original body getter is touched before clone(), which would empty the SDK body.
    await sniffProviderDeclaredError({
      response: input.response,
      phase: input.phase,
      tracker: input.tracker,
    })
  }
  if (!input.response.body) return input.response
  const limit = responseBodyLimit(input.contentType)
  const contentLength = advertisedContentLength(input.response)
  if (contentLength !== null && contentLength > limit) {
    const error = new ExternalMcpResponseBodyLimitError()
    if (input.background) {
      input.tracker.captureBackgroundResponseBodyLimit(input.phase, error)
      throw error
    }
    input.tracker.captureResponseBodyLimit(input.phase, error)
    throw input.tracker.error(error, input.phase)
  }

  const reader = input.response.body.getReader()
  let bytesRead = 0
  const body = new ReadableStream<Uint8Array>({
    async pull(controller) {
      try {
        const next = await reader.read()
        if (next.done) {
          controller.close()
          return
        }
        bytesRead += next.value.byteLength
        if (bytesRead > limit) {
          const error = new ExternalMcpResponseBodyLimitError()
          if (input.background) {
            input.tracker.captureBackgroundResponseBodyLimit(input.phase, error)
          } else {
            input.tracker.captureResponseBodyLimit(input.phase, error)
          }
          await reader.cancel(error).catch(() => undefined)
          controller.error(error)
          return
        }
        controller.enqueue(next.value)
      } catch (error) {
        controller.error(error)
      }
    },
    cancel(reason) {
      return reader.cancel(reason)
    },
  })
  const bounded = new Response(body, {
    status: input.response.status,
    statusText: input.response.statusText,
    headers: input.response.headers,
  })
  preserveResponseMetadata(bounded, input.response)
  return bounded
}

export function createExternalMcpDiagnosticFetch(input: {
  fetch: FetchLike
  endpoint: string
  tracker: ExternalMcpDiagnosticTracker
}): FetchLike {
  const endpoint = new URL(input.endpoint)
  return async (url, init) => {
    let phase: ExternalMcpDiagnosticPhase
    try {
      phase = requestPhase(url, init, endpoint)
    } catch (error) {
      input.tracker.failed("CONFIGURATION")
      throw input.tracker.error(error, "CONFIGURATION")
    }
    const background = isBackgroundMcpEndpointRequest(url, init, endpoint)
    if (!background) {
      input.tracker.begin(phase)
      input.tracker.recordOutbound(url)
    }
    try {
      const response = await input.fetch(url, init)
      const contentType = (response.headers.get("content-type") ?? "").split(";", 1)[0]?.trim().toLowerCase() ?? ""
      if (background) {
        return await boundedExternalMcpResponse({
          response,
          contentType,
          phase,
          tracker: input.tracker,
          background,
          sniffProviderDeclaredError: false,
        })
      }
      input.tracker.recordHttpStatus(response.status)
      input.tracker.recordProviderRequestId(response.headers)
      if (!response.ok || (response.ok && isOAuthTokenPhase(phase) && contentType === "application/json")) {
        const excerpts = await providerResponseExcerpts(response)
        if (excerpts && (!response.ok || (excerpts.memberExcerpt && isProviderTokenErrorExcerpt(excerpts.memberExcerpt)))) {
          input.tracker.recordProviderResponseExcerpt({
            ...excerpts,
            phase,
          })
        }
      }
      const challenge = response.headers.get("www-authenticate") ?? ""
      const hasAuthorization = Boolean(requestHeader(init, "authorization"))
      const unauthenticatedChallenge = phase === "MCP_INITIALIZE"
        && response.status === 401
        && !hasAuthorization
        && /\bbearer\b/i.test(challenge)
      const classification = unauthenticatedChallenge
        ? null
        : httpClassification({
            phase,
            status: response.status,
            hasAuthorization,
            bearerChallenge: /\bbearer\b/i.test(challenge),
            insufficientScope: /\binsufficient_scope\b/i.test(challenge),
            hasSession: Boolean(requestHeader(init, "mcp-session-id")),
            contentType,
          })
      input.tracker.passed(phase, "reachable")
      if (classification) {
        input.tracker.failed(classification.phase, {
          ...classification,
          ...(classification.phase === phase ? {} : { operationPhase: phase }),
        })
      } else if (response.ok || unauthenticatedChallenge) {
        input.tracker.passed(phase, healthForPhase(phase))
      } else {
        input.tracker.failed(phase)
      }
      return await boundedExternalMcpResponse({
        response,
        contentType,
        phase,
        tracker: input.tracker,
        background,
        sniffProviderDeclaredError: isProviderDeclaredErrorSniffEligible({
          url,
          init,
          endpoint,
          phase,
          response,
          contentType,
        }),
      })
    } catch (error) {
      if (background) {
        input.tracker.captureBackgroundFailure(phase, error)
      } else {
        input.tracker.captureFailure(phase, error)
      }
      throw error
    }
  }
}

export function externalMcpDiagnosticForResponse(error: unknown, referenceId: string, fallbackPhase: ExternalMcpDiagnosticPhase): ExternalMcpDiagnostic {
  if (error instanceof ExternalMcpDiagnosticError) return error.diagnostic
  return new ExternalMcpDiagnosticTracker(referenceId).error(error, fallbackPhase).diagnostic
}

const OAUTH_CALLBACK_ERROR_NAMES: Record<string, string> = {
  access_denied: "AccessDeniedError",
  invalid_client: "InvalidClientError",
  invalid_request: "InvalidRequestError",
  invalid_scope: "InvalidScopeError",
  invalid_target: "InvalidTargetError",
  invalid_token: "InvalidTokenError",
  insufficient_scope: "InsufficientScopeError",
  method_not_allowed: "MethodNotAllowedError",
  too_many_requests: "TooManyRequestsError",
  unsupported_token_type: "UnsupportedTokenTypeError",
  server_error: "ServerError",
  temporarily_unavailable: "TemporarilyUnavailableError",
  unauthorized_client: "UnauthorizedClientError",
  unsupported_response_type: "UnsupportedResponseTypeError",
}

export function externalMcpOAuthCallbackError(referenceId: string, providerErrorCode: string): ExternalMcpDiagnosticError {
  const tracker = new ExternalMcpDiagnosticTracker(referenceId)
  tracker.begin("AUTH_USER_OR_WORKLOAD")
  const error = new Error("OAuth provider returned an authorization error.")
  error.name = OAUTH_CALLBACK_ERROR_NAMES[providerErrorCode] ?? "Error"
  return tracker.error(error, "AUTH_USER_OR_WORKLOAD")
}

export function externalMcpDiagnosticForLog(error: unknown, referenceId: string, fallbackPhase: ExternalMcpDiagnosticPhase) {
  const diagnosticError = error instanceof ExternalMcpDiagnosticError
    ? error
    : new ExternalMcpDiagnosticTracker(referenceId).error(error, fallbackPhase)
  const providerResponseLog = diagnosticError.providerResponseForLog()
  return {
    diagnostic: diagnosticError.diagnostic,
    causeChain: diagnosticError.safeCauseChain,
    ...(providerResponseLog
      ? { providerResponseLog }
      : {}),
  }
}

export function safeExternalMcpOutbound(rawUrl: string | URL): ExternalMcpSafeOutbound {
  const url = new URL(String(rawUrl))
  return {
    origin: url.origin,
    pathHash: `sha256:${createHash("sha256").update(url.pathname).digest("hex").slice(0, 16)}`,
  }
}

export function safeExternalMcpEndpointForLog(rawUrl: string): ExternalMcpSafeOutbound | { invalid: true } {
  try {
    return safeExternalMcpOutbound(rawUrl)
  } catch {
    return { invalid: true }
  }
}

export function catalogDiagnosticError(input: {
  tracker: ExternalMcpDiagnosticTracker
  code:
    | "MCP_CATALOG_CURSOR_LOOP"
    | "MCP_CATALOG_PAGE_LIMIT"
    | "MCP_CATALOG_ITEM_LIMIT"
    | "MCP_CATALOG_DUPLICATE_TOOL"
    | "MCP_CATALOG_DUPLICATE_RESOURCE"
    | "MCP_CATALOG_TOOL_NAME_LIMIT"
    | "MCP_CATALOG_TOOL_DESCRIPTION_LIMIT"
    | "MCP_CATALOG_TOOL_TITLE_LIMIT"
    | "MCP_CATALOG_SCHEMA_SIZE_LIMIT"
    | "MCP_CATALOG_SCHEMA_DEPTH_LIMIT"
    | "MCP_CATALOG_SCHEMA_CYCLE"
    | "MCP_CATALOG_CURSOR_SIZE_LIMIT"
    | "MCP_CATALOG_BYTE_LIMIT"
    | "MCP_RESOURCE_URI_LIMIT"
    | "MCP_RESOURCE_DESCRIPTOR_LIMIT"
    | "MCP_RESOURCE_RESULT_LIMIT"
  operatorAction: string
}): ExternalMcpDiagnosticError {
  input.tracker.failed("MCP_TOOL_DISCOVERY")
  const diagnostic: ExternalMcpDiagnostic = {
    referenceId: input.tracker.referenceId,
    phase: "MCP_TOOL_DISCOVERY",
    category: "mcp_catalog",
    code: input.code,
    highestPassed: "protocol_ready",
    retryable: false,
    actionOwner: "provider_admin",
    operatorAction: input.operatorAction,
    message: safeMessageFor({ phase: "MCP_TOOL_DISCOVERY", category: "mcp_catalog", code: input.code }),
  }
  return new ExternalMcpDiagnosticError(diagnostic)
}

export function lifecycleDeadlineDiagnosticError(input: {
  tracker: ExternalMcpDiagnosticTracker
  phase: ExternalMcpDiagnosticPhase
}): ExternalMcpDiagnosticError {
  return input.tracker.error(new ExternalMcpLifecycleDeadlineError(), input.phase)
}

export function providerToolDiagnosticError(input: {
  tracker: ExternalMcpDiagnosticTracker
  result?: unknown
}): ExternalMcpDiagnosticError {
  return input.tracker.providerToolError(input.result)
}