Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
38.7 KB
Raw Blame
import {
  runtimeDiagnosticFetch,
  runtimeDiagnosticTransportInfo,
  type RuntimeDiagnosticRuntimeFamily,
  type RuntimeDiagnosticTransport,
} from "./server-fetch.js";

const REQUEST_TIMEOUT_MS = 12_000;
const MAX_RESPONSE_BYTES = 64 * 1024;
const MAX_TOOL_COUNT = 100;
const MAX_TOOL_ID_LENGTH = 160;
const MAX_AUTHORIZATION_LENGTH = 8 * 1024;
const MAX_ENDPOINT_LENGTH = 2 * 1024;
const MAX_SESSION_HEADER_LENGTH = 1024;
const MAX_PROTOCOL_HEADER_LENGTH = 128;
const MAX_STEP_SUMMARIES = 12;
const MAX_ACTIVE_PROBES = 16;
const STALE_ENGINE_EVIDENCE_MS = 60_000;
const MCP_ACCEPT = "application/json, text/event-stream";
const MCP_PROTOCOL_VERSION = "2025-06-18";
const INITIALIZE_REQUEST_ID = "omnirush-agent-diagnostics-initialize";
const TOOL_ID = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
const SAFE_RESPONSE_HEADER = /^[!-~]+$/;
const SAFE_REFERENCE_ID = /^[A-Za-z0-9._:-]{1,64}$/;
const REQUIRED_TOOL_IDS = ["search_capabilities", "execute_capability"] as const;
const BEARER = /^Bearer [A-Za-z0-9\-._~+/]+=*$/;
const REQUEST_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
const REQUIRED_TERMINAL_PATH = "/mcp/agent";

export type CloudCatalogProbeStatus = "observed" | "not-performed" | "failed";

export type CloudCatalogProbeStage =
  | "eligibility"
  | "dns"
  | "connect"
  | "tls"
  | "proxy"
  | "initialize_request"
  | "initialize_http"
  | "initialize_protocol"
  | "initialized_notification"
  | "tools_list_request"
  | "tools_list_http"
  | "tools_list_protocol"
  | "catalog_validation"
  | "session_cleanup"
  | "complete";

export type CloudCatalogProbeNetworkCode =
  | "ENOTFOUND"
  | "EAI_AGAIN"
  | "ECONNREFUSED"
  | "ECONNRESET"
  | "ETIMEDOUT"
  | "UND_ERR_CONNECT_TIMEOUT"
  | "CERT_HAS_EXPIRED"
  | "SELF_SIGNED_CERT_IN_CHAIN"
  | "DEPTH_ZERO_SELF_SIGNED_CERT"
  | "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
  | "ERR_TLS_CERT_ALTNAME_INVALID"
  | "PROXY_ERROR"
  | "UNKNOWN_NETWORK_ERROR";

export type CloudCatalogProbeCode =
  | "catalog_observed"
  | "runtime_config_unavailable"
  | "remote_workspace_unavailable"
  | "cloud_mcp_missing"
  | "cloud_mcp_not_remote"
  | "cloud_mcp_disabled"
  | "invalid_endpoint"
  | "untrusted_endpoint"
  | "credential_missing"
  | "duplicate_authorization"
  | "probe_busy"
  | "timeout"
  | "network_error"
  | "dns_error"
  | "connection_refused"
  | "connection_reset"
  | "tls_error"
  | "proxy_error"
  | "redirect_rejected"
  | "unauthorized"
  | "forbidden"
  | "mcp_route_not_found"
  | "rate_limited"
  | "gateway_unavailable"
  | "http_error"
  | "response_too_large"
  | "invalid_content_type"
  | "invalid_utf8"
  | "invalid_json"
  | "invalid_jsonrpc_envelope"
  | "request_id_mismatch"
  | "jsonrpc_error"
  | "unsupported_protocol_version"
  | "invalid_session_header"
  | "pagination_unsupported"
  | "invalid_catalog"
  | "required_tools_missing";

export type CloudEngineRegistrationStatus =
  | "connected"
  | "disabled"
  | "failed"
  | "needs-auth"
  | "needs-client-registration"
  | "not-recorded";

/**
 * Cached engine-side evidence for the exact managed OmniRush.ai Cloud entry.
 * This is a comparison input for the differential verdict; it never gates
 * whether the independent runtime probe is allowed to run.
 */
export type CloudEngineRegistrationEvidence = {
  status: CloudEngineRegistrationStatus;
  source: "transport_failure" | "engine_status" | null;
  recordAgeMs: number | null;
};

export type CloudRuntimeEngineDifferential =
  | "runtime_and_engine_connected"
  | "runtime_connected_engine_failed"
  | "runtime_failed_engine_connected"
  | "runtime_and_engine_failed"
  | "runtime_probe_not_performed"
  | "engine_evidence_stale_or_unavailable";

/**
 * Which allowlist entry authorized the credentialed request, or why none did.
 * Reported instead of the origin itself so an administrator can distinguish
 * "this install is not enterprise activated" from "it is activated, but
 * against a different origin than the configured Cloud MCP" — a real
 * misconfiguration — without the report ever carrying a hostname.
 */
export type CloudEndpointTrustSource =
  | "loopback"
  | "administrator-env"
  | "enterprise-activation"
  | "untrusted"
  /** The endpoint was absent or structurally invalid, so trust never applied. */
  | "not-evaluated";

export type CloudCatalogProbe = {
  performed: boolean;
  trustSource: CloudEndpointTrustSource;
  enterpriseActivationPresent: boolean;
  status: CloudCatalogProbeStatus;
  stage: CloudCatalogProbeStage;
  code: CloudCatalogProbeCode;
  networkCode: CloudCatalogProbeNetworkCode | null;
  retryable: boolean;
  runtimeFamily: RuntimeDiagnosticRuntimeFamily;
  transport: RuntimeDiagnosticTransport;
  httpStatus: number | null;
  durationMs: number;
  toolsListPerformed: boolean;
  sessionEstablished: boolean;
  cleanupAttempted: boolean;
  cleanupSucceeded: boolean | null;
  toolIds: string[];
  totalToolCount: number | null;
  requiredToolsPresent: boolean | null;
  referenceId: string | null;
  proxyConfigured: boolean;
  extraCaConfigured: boolean;
  steps: string[];
  engineRegistrationStatus: CloudEngineRegistrationStatus;
  engineEvidenceSource: "transport_failure" | "engine_status" | null;
  engineEvidenceAgeMs: number | null;
};

export type CloudCatalogProbeFetch = (
  input: string | URL | Request,
  init?: RequestInit,
) => Promise<Response>;

export type ProbeOmniRushCloudCatalogInput = {
  workspaceId: string;
  workspaceType: "local" | "remote";
  runtimeConfigAvailable?: boolean;
  config: Record<string, unknown> | null | undefined;
  engineRegistration: CloudEngineRegistrationEvidence;
  requestId: string;
  fetchImpl?: CloudCatalogProbeFetch;
  clock?: () => number;
  /** Backward-compatible name used by the analyzer dependency seam. */
  now?: () => number;
  /** Test seam; production callers cannot extend the 12-second ceiling. */
  timeoutMs?: number;
  /** Overall diagnostics deadline; aborting it prevents or cancels egress. */
  signal?: AbortSignal;
  /** Test seam for proxy and extra-CA presence detection. */
  env?: Record<string, string | undefined>;
  /**
   * Exact origin of the enterprise/on-prem Den control plane this install is
   * activated against, resolved by the caller from administrator-provisioned
   * desktop activation state. Null when the install is not enterprise
   * activated; never a renderer- or request-supplied value.
   */
  activatedEnterpriseOrigin?: string | null;
};

type PreparedProbe = {
  endpoint: string;
  authorization: string;
};

class SafeProbeFailure extends Error {
  constructor(readonly code: CloudCatalogProbeCode) {
    super(code);
  }
}

class ProbeHttpFailure extends SafeProbeFailure {
  constructor(code: CloudCatalogProbeCode, readonly httpStatus: number) {
    super(code);
  }
}

class CatalogRequiredToolsFailure extends SafeProbeFailure {
  constructor(readonly totalToolCount: number) {
    super("required_tools_missing");
  }
}

class ProbeTimeout extends Error {}

type ProbeDeadline = {
  signal: AbortSignal;
  race: <T>(operation: Promise<T>) => Promise<T>;
  timedOut: () => boolean;
  dispose: () => void;
};

type ProbeResponseBudget = {
  remaining: number;
};

type ProbeBaseFacts = {
  runtimeFamily: RuntimeDiagnosticRuntimeFamily;
  transport: RuntimeDiagnosticTransport;
  proxyConfigured: boolean;
  extraCaConfigured: boolean;
  trustSource: CloudEndpointTrustSource;
  enterpriseActivationPresent: boolean;
  engineRegistrationStatus: CloudEngineRegistrationStatus;
  engineEvidenceSource: "transport_failure" | "engine_status" | null;
  engineEvidenceAgeMs: number | null;
};

/** Classifies which allowlist entry authorized this exact endpoint origin. */
function resolveTrustSource(
  endpoint: URL,
  activatedEnterpriseOrigin?: string | null,
): CloudEndpointTrustSource {
  if (isLoopbackHostname(endpoint.hostname)) return "loopback";
  if (activatedEnterpriseOrigin && endpoint.origin === activatedEnterpriseOrigin) {
    return "enterprise-activation";
  }
  if (configuredTrustedOrigins(activatedEnterpriseOrigin).has(endpoint.origin)) {
    return "administrator-env";
  }
  return "untrusted";
}

const activeProbes = new Set<Promise<CloudCatalogProbe>>();

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

function elapsed(startedAt: number, clock: () => number): number {
  const value = clock() - startedAt;
  return Number.isFinite(value) ? Math.max(0, Math.round(value)) : 0;
}

function cloneResult(value: CloudCatalogProbe): CloudCatalogProbe {
  return { ...value, toolIds: [...value.toolIds], steps: [...value.steps] };
}

function isLoopbackHostname(hostname: string): boolean {
  const value = hostname.toLowerCase();
  if (value === "localhost" || value === "::1" || value === "[::1]") return true;
  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(value);
  if (!match) return false;
  return Number(match[1]) === 127 && match.slice(1).every((part) => Number(part) <= 255);
}

/**
 * Origins the credentialed diagnostic request may reach: the activated
 * enterprise/on-prem Den origin plus exact administrator-configured diagnostic
 * origins. There are no built-in hosted origins: omnirush.ai runs no hosted
 * Den, and the retired hosted Den domains are not ours to send credentials to.
 */
function configuredTrustedOrigins(activatedEnterpriseOrigin?: string | null): Set<string> {
  const origins = new Set<string>();
  // The activated enterprise/on-prem control-plane origin is administrator
  // provisioned (written only after a signed activation claim verifies), so
  // it joins the allowlist as an exact origin without an explicit override.
  if (activatedEnterpriseOrigin) origins.add(activatedEnterpriseOrigin);
  const configured = process.env.OMNIRUSH_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS ?? "";
  for (const entry of configured.split(",")) {
    const raw = entry.trim().replace(/\/+$/u, "");
    if (!raw || raw.includes("?") || raw.includes("#")) continue;
    try {
      const url = new URL(raw);
      if (url.username || url.password || url.pathname !== "/") continue;
      if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) continue;
      if (raw !== url.origin) continue;
      origins.add(url.origin);
    } catch {
      // Invalid administrator entries fail closed.
    }
  }
  return origins;
}

function safeCatalogEndpoint(rawValue: unknown): URL | null {
  if (typeof rawValue !== "string") return null;
  const raw = rawValue.trim();
  if (!raw || raw.length > MAX_ENDPOINT_LENGTH || raw.includes("?") || raw.includes("#")) return null;
  if (/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/iu.test(raw)) return null;
  try {
    const url = new URL(raw);
    if (url.username || url.password || url.search || url.hash) return null;
    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) return null;
    // Deployments can mount Den below an origin-specific prefix, but the MCP
    // route itself must be the final two path segments. The report therefore
    // describes this as terminal-path evidence, not a canonical full URL.
    if (!url.pathname.endsWith(REQUIRED_TERMINAL_PATH) || url.pathname.endsWith(REQUIRED_TERMINAL_PATH + "/")) return null;
    if (url.origin !== raw.slice(0, raw.length - url.pathname.length)) return null;
    return url;
  } catch {
    return null;
  }
}

function authorizationHeader(config: Record<string, unknown>): { value: string | null; duplicate: boolean } {
  if (!isRecord(config.headers)) return { value: null, duplicate: false };
  const matches = Object.entries(config.headers)
    .filter(([name]) => name.toLowerCase() === "authorization");
  if (matches.length > 1) return { value: null, duplicate: true };
  const value = matches[0]?.[1];
  if (typeof value !== "string" || value.length > MAX_AUTHORIZATION_LENGTH || !BEARER.test(value)) {
    return { value: null, duplicate: false };
  }
  return { value, duplicate: false };
}

/**
 * Eligibility is deliberately independent of cached OpenCode registration
 * state and of agent tool policy: the probe exists to diagnose engine-side
 * failures, and tool visibility is a separate diagnostic dimension reported
 * by its own check. Only structural, trust, credential, and privacy
 * boundaries can skip the probe.
 */
function prepare(input: ProbeOmniRushCloudCatalogInput): PreparedProbe | CloudCatalogProbeCode {
  if (input.workspaceType !== "local") return "remote_workspace_unavailable";
  if (input.runtimeConfigAvailable === false) return "runtime_config_unavailable";
  if (!isRecord(input.config)) return "cloud_mcp_missing";
  if (input.config.type !== "remote") return "cloud_mcp_not_remote";
  if (input.config.enabled !== true) return "cloud_mcp_disabled";
  const endpoint = safeCatalogEndpoint(input.config.url);
  if (!endpoint) return "invalid_endpoint";
  if (
    !isLoopbackHostname(endpoint.hostname)
    && !configuredTrustedOrigins(input.activatedEnterpriseOrigin).has(endpoint.origin)
  ) {
    return "untrusted_endpoint";
  }
  const authorization = authorizationHeader(input.config);
  if (authorization.duplicate) return "duplicate_authorization";
  if (!authorization.value) return "credential_missing";
  if (!REQUEST_ID.test(input.requestId)) return "invalid_endpoint";
  return {
    endpoint: endpoint.toString(),
    authorization: authorization.value,
  };
}

function createDeadline(timeoutMs: number, parentSignal?: AbortSignal): ProbeDeadline {
  const controller = new AbortController();
  let timeout: ReturnType<typeof setTimeout> | undefined;
  let expired = false;
  let disposed = false;
  let rejectDeadline: ((reason: ProbeTimeout) => void) | undefined;
  const deadlinePromise = new Promise<never>((_, reject) => {
    rejectDeadline = reject;
  });
  // A parent can abort in the tiny window before the first race is installed.
  // Mark the promise handled while preserving its rejection for every race.
  void deadlinePromise.catch(() => undefined);
  const expire = () => {
    if (expired || disposed) return;
    expired = true;
    // Settle the deadline before aborting the underlying operation so an
    // abort-aware fetch/stream cannot win the race with a generic error.
    rejectDeadline?.(new ProbeTimeout());
    controller.abort();
  };
  const parentAbort = () => expire();
  if (parentSignal?.aborted) {
    expire();
  } else {
    parentSignal?.addEventListener("abort", parentAbort, { once: true });
  }
  timeout = setTimeout(expire, timeoutMs);
  return {
    signal: controller.signal,
    race: <T>(operation: Promise<T>) => Promise.race([operation, deadlinePromise]),
    timedOut: () => expired,
    dispose: () => {
      disposed = true;
      if (timeout) clearTimeout(timeout);
      parentSignal?.removeEventListener("abort", parentAbort);
    },
  };
}

async function cancelBody(response: Response, deadline?: ProbeDeadline): Promise<void> {
  try {
    const cancellation = response.body?.cancel();
    if (cancellation) await (deadline ? deadline.race(cancellation) : cancellation);
  } catch {
    // Cancellation is best effort and its error is never reported.
  }
}

async function readBoundedBody(
  response: Response,
  deadline: ProbeDeadline,
  budget: ProbeResponseBudget,
): Promise<string> {
  const declared = Number(response.headers.get("content-length"));
  if (Number.isFinite(declared) && declared > budget.remaining) {
    await cancelBody(response, deadline);
    throw new SafeProbeFailure("response_too_large");
  }
  const reader = response.body?.getReader();
  if (!reader) return "";
  const chunks: Uint8Array[] = [];
  let size = 0;
  try {
    while (true) {
      const next = await deadline.race(reader.read());
      if (next.done) break;
      size += next.value.byteLength;
      if (next.value.byteLength > budget.remaining) {
        await deadline.race(reader.cancel());
        throw new SafeProbeFailure("response_too_large");
      }
      budget.remaining -= next.value.byteLength;
      chunks.push(next.value);
    }
  } catch (error) {
    if (error instanceof SafeProbeFailure) throw error;
    // Invoke cancellation even after the deadline has fired. Do not await it:
    // a hostile stream can ignore both AbortSignal and cancellation.
    void reader.cancel().catch(() => undefined);
    if (error instanceof ProbeTimeout || deadline.timedOut()) throw new ProbeTimeout();
    // Mid-body transport failures keep their original cause so the outer
    // classifier can attribute them to the network layer, not the protocol.
    throw error;
  }
  const bytes = new Uint8Array(size);
  let offset = 0;
  for (const chunk of chunks) {
    bytes.set(chunk, offset);
    offset += chunk.byteLength;
  }
  try {
    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  } catch {
    throw new SafeProbeFailure("invalid_utf8");
  }
}

function parseJson(text: string): unknown {
  try {
    return JSON.parse(text);
  } catch {
    throw new SafeProbeFailure("invalid_json");
  }
}

function parseSse(text: string): unknown {
  const messages: unknown[] = [];
  let event = "";
  let data: string[] = [];
  const dispatch = () => {
    if (data.length === 0) {
      event = "";
      return;
    }
    if (event && event !== "message") throw new SafeProbeFailure("invalid_json");
    messages.push(parseJson(data.join("\n")));
    event = "";
    data = [];
  };
  for (const line of text.split(/\r\n|\r|\n/u)) {
    if (line === "") {
      dispatch();
      continue;
    }
    if (line.startsWith(":")) continue;
    const colon = line.indexOf(":");
    const field = colon < 0 ? line : line.slice(0, colon);
    const rawValue = colon < 0 ? "" : line.slice(colon + 1);
    const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
    if (field === "event") event = value;
    if (field === "data") data.push(value);
  }
  dispatch();
  if (messages.length !== 1) throw new SafeProbeFailure("invalid_json");
  return messages[0];
}

function parseJsonRpcResult(payload: unknown, requestId: string): Record<string, unknown> {
  if (!isRecord(payload) || payload.jsonrpc !== "2.0") {
    throw new SafeProbeFailure("invalid_jsonrpc_envelope");
  }
  if (Object.hasOwn(payload, "error")) throw new SafeProbeFailure("jsonrpc_error");
  if (payload.id !== requestId) throw new SafeProbeFailure("request_id_mismatch");
  if (!isRecord(payload.result)) throw new SafeProbeFailure("invalid_jsonrpc_envelope");
  return payload.result;
}

function requireSupportedProtocolVersion(initializeResult: Record<string, unknown>): void {
  const version = initializeResult.protocolVersion;
  if (typeof version !== "string" || version.length === 0 || version.length > MAX_PROTOCOL_HEADER_LENGTH) {
    throw new SafeProbeFailure("invalid_jsonrpc_envelope");
  }
  if (version !== MCP_PROTOCOL_VERSION) throw new SafeProbeFailure("unsupported_protocol_version");
}

function validateCatalog(rpcResult: Record<string, unknown>): { toolIds: string[]; totalToolCount: number } {
  if (rpcResult.nextCursor !== undefined && rpcResult.nextCursor !== null) {
    throw new SafeProbeFailure("pagination_unsupported");
  }
  if (!Array.isArray(rpcResult.tools) || rpcResult.tools.length > MAX_TOOL_COUNT) {
    throw new SafeProbeFailure("invalid_catalog");
  }
  const seen = new Set<string>();
  for (const tool of rpcResult.tools) {
    if (!isRecord(tool) || typeof tool.name !== "string" || tool.name.length > MAX_TOOL_ID_LENGTH || !TOOL_ID.test(tool.name)) {
      throw new SafeProbeFailure("invalid_catalog");
    }
    if (seen.has(tool.name)) throw new SafeProbeFailure("invalid_catalog");
    seen.add(tool.name);
  }
  // Additional provider tools are forward-compatible and allowed, but never
  // reflect provider-controlled catalog names into the diagnostic report. In
  // particular, a compromised trusted endpoint must not be able to echo the
  // bearer token back as a syntactically valid tool identifier. Only the
  // expected allowlisted IDs and the aggregate count are exported.
  const missing = REQUIRED_TOOL_IDS.filter((toolId) => !seen.has(toolId));
  if (missing.length > 0) throw new CatalogRequiredToolsFailure(rpcResult.tools.length);
  return { toolIds: [...REQUIRED_TOOL_IDS], totalToolCount: rpcResult.tools.length };
}

function httpFailureCode(status: number): CloudCatalogProbeCode {
  if (status === 401) return "unauthorized";
  if (status === 403) return "forbidden";
  if (status === 404) return "mcp_route_not_found";
  if (status === 429) return "rate_limited";
  if (status === 502 || status === 503 || status === 504) return "gateway_unavailable";
  if (status >= 300 && status < 400) return "redirect_rejected";
  return "http_error";
}

function classifyNetworkError(error: unknown): { code: CloudCatalogProbeCode; networkCode: CloudCatalogProbeNetworkCode } {
  const cause = isRecord(error) && isRecord(error.cause) ? error.cause : null;
  const code = cause && typeof cause.code === "string" ? cause.code.toUpperCase() : "";
  if (code === "ENOTFOUND") return { code: "dns_error", networkCode: "ENOTFOUND" };
  if (code === "EAI_AGAIN") return { code: "dns_error", networkCode: "EAI_AGAIN" };
  if (code === "ECONNREFUSED") return { code: "connection_refused", networkCode: "ECONNREFUSED" };
  if (code === "ECONNRESET" || code === "EPIPE") return { code: "connection_reset", networkCode: "ECONNRESET" };
  if (code === "ETIMEDOUT") return { code: "timeout", networkCode: "ETIMEDOUT" };
  if (code === "UND_ERR_CONNECT_TIMEOUT") return { code: "timeout", networkCode: "UND_ERR_CONNECT_TIMEOUT" };
  if (code.includes("PROXY")) return { code: "proxy_error", networkCode: "PROXY_ERROR" };
  if (code === "CERT_HAS_EXPIRED") return { code: "tls_error", networkCode: "CERT_HAS_EXPIRED" };
  if (code === "SELF_SIGNED_CERT_IN_CHAIN") return { code: "tls_error", networkCode: "SELF_SIGNED_CERT_IN_CHAIN" };
  if (code === "DEPTH_ZERO_SELF_SIGNED_CERT") return { code: "tls_error", networkCode: "DEPTH_ZERO_SELF_SIGNED_CERT" };
  if (code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") return { code: "tls_error", networkCode: "UNABLE_TO_VERIFY_LEAF_SIGNATURE" };
  if (code === "ERR_TLS_CERT_ALTNAME_INVALID") return { code: "tls_error", networkCode: "ERR_TLS_CERT_ALTNAME_INVALID" };
  if (code.startsWith("ERR_TLS_") || code.startsWith("CERT_") || code.includes("CERTIFICATE")) {
    return { code: "tls_error", networkCode: "UNKNOWN_NETWORK_ERROR" };
  }
  return { code: "network_error", networkCode: "UNKNOWN_NETWORK_ERROR" };
}

function networkStageFor(networkCode: CloudCatalogProbeNetworkCode): CloudCatalogProbeStage | null {
  if (networkCode === "ENOTFOUND" || networkCode === "EAI_AGAIN") return "dns";
  if (
    networkCode === "ECONNREFUSED"
    || networkCode === "ECONNRESET"
    || networkCode === "ETIMEDOUT"
    || networkCode === "UND_ERR_CONNECT_TIMEOUT"
  ) return "connect";
  if (networkCode === "PROXY_ERROR") return "proxy";
  if (networkCode === "UNKNOWN_NETWORK_ERROR") return null;
  return "tls";
}

/**
 * Retryability is derived only from the closed code sets, never from raw
 * error message text: transient DNS, timeouts, resets, rate limits, gateway
 * availability, and local probe-capacity exhaustion are retryable; TLS
 * validation, credential, route, protocol, and catalog failures are not.
 */
function retryableFor(code: CloudCatalogProbeCode, networkCode: CloudCatalogProbeNetworkCode | null): boolean {
  if (networkCode === "EAI_AGAIN" || networkCode === "ETIMEDOUT" || networkCode === "UND_ERR_CONNECT_TIMEOUT" || networkCode === "ECONNRESET") {
    return true;
  }
  switch (code) {
    case "timeout":
    case "connection_reset":
    case "rate_limited":
    case "gateway_unavailable":
    case "probe_busy":
      return true;
    default:
      return false;
  }
}

function stepPhaseFor(stage: CloudCatalogProbeStage): string {
  if (stage === "initialize_request" || stage === "initialize_http" || stage === "initialize_protocol") return "initialize";
  if (stage === "tools_list_request" || stage === "tools_list_http" || stage === "tools_list_protocol") return "tools_list";
  return stage;
}

function proxyEnvConfigured(env: Record<string, string | undefined>): boolean {
  return Boolean(
    env.HTTPS_PROXY?.trim()
    || env.https_proxy?.trim()
    || env.HTTP_PROXY?.trim()
    || env.http_proxy?.trim()
    || env.ALL_PROXY?.trim()
    || env.all_proxy?.trim(),
  );
}

function extraCaEnvConfigured(env: Record<string, string | undefined>): boolean {
  return Boolean(env.NODE_EXTRA_CA_CERTS?.trim());
}

function baseProbeHeaders(authorization: string): Record<string, string> {
  return {
    Accept: MCP_ACCEPT,
    Authorization: authorization,
    "Content-Type": "application/json",
  };
}

function returnedSessionHeader(response: Response, name: string, maxLength: number): string | undefined {
  const value = response.headers.get(name);
  if (value === null) return undefined;
  if (value.length === 0 || value.length > maxLength || !SAFE_RESPONSE_HEADER.test(value)) {
    throw new SafeProbeFailure("invalid_session_header");
  }
  return value;
}

function captureReferenceId(response: Response, current: string | null): string | null {
  const value = response.headers.get("x-request-id");
  if (value !== null && SAFE_REFERENCE_ID.test(value)) return value;
  return current;
}

type ProbeSession = {
  headers: Record<string, string>;
  sessionId: string | undefined;
  protocolVersion: string | undefined;
};

function sessionProbe(response: Response, authorization: string): ProbeSession {
  const sessionId = returnedSessionHeader(response, "mcp-session-id", MAX_SESSION_HEADER_LENGTH);
  const protocolVersion = returnedSessionHeader(response, "mcp-protocol-version", MAX_PROTOCOL_HEADER_LENGTH);
  return {
    headers: {
      ...baseProbeHeaders(authorization),
      ...(sessionId ? { "mcp-session-id": sessionId } : {}),
      ...(protocolVersion ? { "mcp-protocol-version": protocolVersion } : {}),
    },
    sessionId,
    protocolVersion,
  };
}

async function postJsonRpc(
  prepared: PreparedProbe,
  headers: Record<string, string>,
  body: Record<string, unknown>,
  fetchImpl: CloudCatalogProbeFetch,
  deadline: ProbeDeadline,
): Promise<Response> {
  if (deadline.timedOut()) throw new ProbeTimeout();
  return deadline.race(fetchImpl(prepared.endpoint, {
    method: "POST",
    // Manual mode applies to every handshake phase so credentials and MCP
    // session headers never reach a redirect target.
    redirect: "manual",
    headers,
    body: JSON.stringify(body),
    signal: deadline.signal,
  }));
}

async function requireHttpStatus(
  response: Response,
  deadline: ProbeDeadline,
  accepted: (status: number) => boolean,
): Promise<void> {
  if (accepted(response.status)) return;
  await cancelBody(response, deadline);
  throw new ProbeHttpFailure(httpFailureCode(response.status), response.status);
}

async function readJsonRpcPayload(
  response: Response,
  deadline: ProbeDeadline,
  budget: ProbeResponseBudget,
): Promise<unknown> {
  const mediaType = (response.headers.get("content-type") ?? "").split(";", 1)[0]?.trim().toLowerCase();
  if (mediaType !== "application/json" && mediaType !== "text/event-stream") {
    await cancelBody(response, deadline);
    throw new SafeProbeFailure("invalid_content_type");
  }
  const body = await readBoundedBody(response, deadline, budget);
  return mediaType === "text/event-stream" ? parseSse(body) : parseJson(body);
}

/**
 * Bounded best-effort termination of the diagnostic MCP session. Failure here
 * is reported but never converts a successful availability observation into
 * a failed one.
 */
async function terminateSession(
  prepared: PreparedProbe,
  session: ProbeSession,
  fetchImpl: CloudCatalogProbeFetch,
  deadline: ProbeDeadline,
): Promise<boolean> {
  try {
    const response = await deadline.race(fetchImpl(prepared.endpoint, {
      method: "DELETE",
      redirect: "manual",
      headers: {
        Accept: MCP_ACCEPT,
        Authorization: prepared.authorization,
        ...(session.sessionId ? { "mcp-session-id": session.sessionId } : {}),
        ...(session.protocolVersion ? { "mcp-protocol-version": session.protocolVersion } : {}),
      },
      signal: deadline.signal,
    }));
    await cancelBody(response, deadline);
    return response.status >= 200 && response.status < 300;
  } catch {
    return false;
  }
}

async function performProbe(
  prepared: PreparedProbe,
  requestId: string,
  fetchImpl: CloudCatalogProbeFetch,
  base: ProbeBaseFacts,
  startedAt: number,
  clock: () => number,
  timeoutMs: number,
  parentSignal?: AbortSignal,
): Promise<CloudCatalogProbe> {
  const deadline = createDeadline(timeoutMs, parentSignal);
  const budget: ProbeResponseBudget = { remaining: MAX_RESPONSE_BYTES };
  const steps: string[] = [];
  const record = (label: string) => {
    if (steps.length < MAX_STEP_SUMMARIES) steps.push(label);
  };
  let stage: CloudCatalogProbeStage = "initialize_request";
  let currentHttpStatus: number | null = null;
  let toolsListPerformed = false;
  let session: ProbeSession | null = null;
  let referenceId: string | null = null;
  let totalToolCount: number | null = null;
  let requiredToolsPresent: boolean | null = null;
  let toolIds: string[] = [];
  let failure: {
    stage: CloudCatalogProbeStage;
    code: CloudCatalogProbeCode;
    networkCode: CloudCatalogProbeNetworkCode | null;
    httpStatus: number | null;
  } | null = null;
  let phaseStart = clock();
  const phaseMs = () => `${elapsed(phaseStart, clock)}ms`;
  try {
    let initialized = await postJsonRpc(
      prepared,
      baseProbeHeaders(prepared.authorization),
      {
        jsonrpc: "2.0",
        id: INITIALIZE_REQUEST_ID,
        method: "initialize",
        params: {
          capabilities: {},
          clientInfo: { name: "omnirush-server-agent-context-diagnostics", version: "1.0.0" },
          protocolVersion: MCP_PROTOCOL_VERSION,
        },
      },
      fetchImpl,
      deadline,
    );
    currentHttpStatus = initialized.status;
    referenceId = captureReferenceId(initialized, referenceId);
    if (initialized.status === 401) {
      await cancelBody(initialized, deadline);
      record(`initialize transient 401 observed ${phaseMs()}`);
      currentHttpStatus = null;
      initialized = await postJsonRpc(
        prepared,
        baseProbeHeaders(prepared.authorization),
        {
          jsonrpc: "2.0",
          id: INITIALIZE_REQUEST_ID,
          method: "initialize",
          params: {
            capabilities: {},
            clientInfo: { name: "omnirush-server-agent-context-diagnostics", version: "1.0.0" },
            protocolVersion: MCP_PROTOCOL_VERSION,
          },
        },
        fetchImpl,
        deadline,
      );
      currentHttpStatus = initialized.status;
      referenceId = captureReferenceId(initialized, referenceId);
      if (initialized.status === 200) record(`initialize recovered after transient 401 ${phaseMs()}`);
    }
    stage = "initialize_http";
    await requireHttpStatus(initialized, deadline, (status) => status === 200);
    stage = "initialize_protocol";
    const initializeResult = parseJsonRpcResult(
      await readJsonRpcPayload(initialized, deadline, budget),
      INITIALIZE_REQUEST_ID,
    );
    requireSupportedProtocolVersion(initializeResult);
    session = sessionProbe(initialized, prepared.authorization);
    record(`initialize ok ${initialized.status} ${phaseMs()}`);

    phaseStart = clock();
    stage = "initialized_notification";
    currentHttpStatus = null;
    const acknowledged = await postJsonRpc(
      prepared,
      session.headers,
      { jsonrpc: "2.0", method: "notifications/initialized", params: {} },
      fetchImpl,
      deadline,
    );
    currentHttpStatus = acknowledged.status;
    referenceId = captureReferenceId(acknowledged, referenceId);
    await requireHttpStatus(acknowledged, deadline, (status) => status >= 200 && status < 300);
    await readBoundedBody(acknowledged, deadline, budget);
    record(`initialized_notification ok ${acknowledged.status} ${phaseMs()}`);

    phaseStart = clock();
    stage = "tools_list_request";
    currentHttpStatus = null;
    toolsListPerformed = true;
    const listed = await postJsonRpc(
      prepared,
      session.headers,
      { jsonrpc: "2.0", id: requestId, method: "tools/list", params: {} },
      fetchImpl,
      deadline,
    );
    currentHttpStatus = listed.status;
    referenceId = captureReferenceId(listed, referenceId);
    stage = "tools_list_http";
    await requireHttpStatus(listed, deadline, (status) => status === 200);
    stage = "tools_list_protocol";
    const listResult = parseJsonRpcResult(await readJsonRpcPayload(listed, deadline, budget), requestId);
    stage = "catalog_validation";
    const catalog = validateCatalog(listResult);
    toolIds = catalog.toolIds;
    totalToolCount = catalog.totalToolCount;
    requiredToolsPresent = true;
    record(`tools_list ok ${listed.status} ${phaseMs()}`);
    stage = "complete";
  } catch (error) {
    const timedOut = error instanceof ProbeTimeout || deadline.timedOut();
    if (error instanceof CatalogRequiredToolsFailure) {
      totalToolCount = error.totalToolCount;
      requiredToolsPresent = false;
    }
    let code: CloudCatalogProbeCode;
    let networkCode: CloudCatalogProbeNetworkCode | null = null;
    let failureStage: CloudCatalogProbeStage = stage;
    if (timedOut) {
      code = "timeout";
    } else if (error instanceof SafeProbeFailure) {
      code = error.code;
    } else {
      const classified = classifyNetworkError(error);
      code = classified.code;
      networkCode = classified.networkCode;
      failureStage = networkStageFor(classified.networkCode) ?? stage;
    }
    failure = {
      stage: failureStage,
      code,
      networkCode,
      httpStatus: error instanceof ProbeHttpFailure
        ? error.httpStatus
        : timedOut || error instanceof SafeProbeFailure
          ? currentHttpStatus
          : null,
    };
    record(`${stepPhaseFor(stage)} failed ${code} ${phaseMs()}`);
  }

  let cleanupAttempted = false;
  let cleanupSucceeded: boolean | null = null;
  if (session?.sessionId !== undefined && !deadline.timedOut()) {
    phaseStart = clock();
    cleanupAttempted = true;
    cleanupSucceeded = await terminateSession(prepared, session, fetchImpl, deadline);
    record(`session_cleanup ${cleanupSucceeded ? "ok" : "failed"} ${phaseMs()}`);
  }
  deadline.dispose();

  const common = {
    performed: true,
    toolsListPerformed,
    sessionEstablished: session?.sessionId !== undefined,
    cleanupAttempted,
    cleanupSucceeded,
    totalToolCount,
    requiredToolsPresent,
    referenceId,
    steps,
    durationMs: elapsed(startedAt, clock),
    ...base,
  };
  if (failure) {
    return {
      ...common,
      status: "failed",
      stage: failure.stage,
      code: failure.code,
      networkCode: failure.networkCode,
      retryable: retryableFor(failure.code, failure.networkCode),
      httpStatus: failure.httpStatus,
      toolIds: [],
    };
  }
  return {
    ...common,
    status: "observed",
    stage: "complete",
    code: "catalog_observed",
    networkCode: null,
    retryable: false,
    httpStatus: currentHttpStatus,
    toolIds,
  };
}

/**
 * Compares the independent runtime observation with the engine's cached
 * registration evidence for the same managed entry, so a report can implicate
 * the correct runtime boundary instead of collapsing both into one failure.
 */
export function differentialCloudVerdict(
  probe: CloudCatalogProbe,
  engineReachableNow: boolean,
): CloudRuntimeEngineDifferential {
  if (!probe.performed) return "runtime_probe_not_performed";
  if (probe.engineRegistrationStatus === "not-recorded") return "engine_evidence_stale_or_unavailable";
  const engineConnected = probe.engineRegistrationStatus === "connected";
  // A connected record is the engine's standing state and ages naturally
  // between syncs, so it stays trustworthy. Only a failure record the
  // reachable engine could already have refreshed is downgraded, mirroring
  // the mcp_registration_stale_failure rule on the sync check.
  if (
    !engineConnected
    && engineReachableNow
    && probe.engineEvidenceAgeMs !== null
    && probe.engineEvidenceAgeMs > STALE_ENGINE_EVIDENCE_MS
  ) {
    return "engine_evidence_stale_or_unavailable";
  }
  const runtimeConnected = probe.status === "observed";
  if (runtimeConnected && engineConnected) return "runtime_and_engine_connected";
  if (runtimeConnected) return "runtime_connected_engine_failed";
  if (engineConnected) return "runtime_failed_engine_connected";
  return "runtime_and_engine_failed";
}

/**
 * Performs one credential-safe direct verification of the exact
 * runtime-managed OmniRush.ai Cloud entry supplied by the caller, running the
 * complete bounded MCP handshake (initialize, initialized notification,
 * tools/list, best-effort session termination) on the OmniRush.ai runtime's own
 * fetch stack. This function never discovers another MCP, follows redirects,
 * calls a tool, mutates configuration, or returns endpoint, credential,
 * header, response-body, or caught-error values.
 */
export async function probeOmniRushCloudCatalog(
  input: ProbeOmniRushCloudCatalogInput,
): Promise<CloudCatalogProbe> {
  const clock = input.clock ?? input.now ?? Date.now;
  const startedAt = clock();
  const env = input.env ?? process.env;
  const transportInfo = input.fetchImpl
    ? { runtimeFamily: runtimeDiagnosticTransportInfo().runtimeFamily, transport: "test-seam" as const }
    : runtimeDiagnosticTransportInfo();
  const endpointForTrust = isRecord(input.config) ? safeCatalogEndpoint(input.config.url) : null;
  const base: ProbeBaseFacts = {
    runtimeFamily: transportInfo.runtimeFamily,
    transport: transportInfo.transport,
    proxyConfigured: proxyEnvConfigured(env),
    extraCaConfigured: extraCaEnvConfigured(env),
    trustSource: endpointForTrust
      ? resolveTrustSource(endpointForTrust, input.activatedEnterpriseOrigin)
      : "not-evaluated",
    enterpriseActivationPresent: Boolean(input.activatedEnterpriseOrigin),
    engineRegistrationStatus: input.engineRegistration.status,
    engineEvidenceSource: input.engineRegistration.source,
    engineEvidenceAgeMs: input.engineRegistration.recordAgeMs,
  };
  const notPerformed = (code: CloudCatalogProbeCode): CloudCatalogProbe => ({
    performed: false,
    status: "not-performed",
    stage: "eligibility",
    code,
    networkCode: null,
    retryable: retryableFor(code, null),
    httpStatus: null,
    durationMs: elapsed(startedAt, clock),
    toolsListPerformed: false,
    sessionEstablished: false,
    cleanupAttempted: false,
    cleanupSucceeded: null,
    toolIds: [],
    totalToolCount: null,
    requiredToolsPresent: null,
    referenceId: null,
    steps: [`eligibility ${code}`],
    ...base,
  });
  if (input.signal?.aborted) return notPerformed("timeout");
  const prepared = prepare(input);
  if (typeof prepared === "string") return notPerformed(prepared);
  if (activeProbes.size >= MAX_ACTIVE_PROBES) return notPerformed("probe_busy");

  const task = performProbe(
    prepared,
    input.requestId,
    input.fetchImpl ?? runtimeDiagnosticFetch,
    base,
    startedAt,
    clock,
    Math.min(REQUEST_TIMEOUT_MS, Math.max(1, Math.round(input.timeoutMs ?? REQUEST_TIMEOUT_MS))),
    input.signal,
  );
  activeProbes.add(task);
  try {
    return cloneResult(await task);
  } finally {
    activeProbes.delete(task);
  }
}