@remodex/rmx 1.0.2

package/src/lib/destination-policy.ts

@@ -0,0 +1,316 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { getProviderRegistryEntry } from "../providers/registry";
+import type { OcxProviderConfig } from "../types";
+
+const BLOCKED_METADATA_HOSTS = new Set([
+  "instance-data.ec2.internal",
+  "metadata.azure.internal",
+  "metadata.google.internal",
+]);
+
+const BLOCKED_METADATA_IPV4 = new Set([
+  "100.100.100.200",
+  "169.254.169.254",
+  "169.254.170.2",
+]);
+
+const BLOCKED_METADATA_IPV6 = new Set([
+  "fd00:ec2::254",
+]);
+
+export type DestinationKind =
+  | "public"
+  | "hostname"
+  | "localhost"
+  | "loopback"
+  | "private"
+  | "link-local"
+  | "unspecified"
+  | "metadata";
+
+interface DestinationAssessment {
+  kind: DestinationKind;
+  detail: string;
+}
+
+function normalizeHostname(hostname: string): string {
+  const trimmed = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  return trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+}
+
+function parseIpv4(hostname: string): number[] | null {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) return null;
+  const octets = parts.map(part => Number(part));
+  return octets.every(octet => Number.isInteger(octet) && octet >= 0 && octet <= 255) ? octets : null;
+}
+
+function classifyIpv4(hostname: string): DestinationAssessment {
+  if (BLOCKED_METADATA_IPV4.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+  const octets = parseIpv4(hostname);
+  if (!octets) return { kind: "public", detail: "public IP" };
+  const [a, b, c] = octets;
+  if (a === 127) return { kind: "loopback", detail: "loopback address" };
+  if (a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127)) {
+    return { kind: "private", detail: "private-network address" };
+  }
+  if (a === 169 && b === 254) return { kind: "link-local", detail: "link-local address" };
+  if (a === 0) return { kind: "unspecified", detail: "unspecified address" };
+  // Reserved / non-public ranges (review finding, PR #96): protocol-assignment,
+  // documentation, benchmark, multicast, and reserved-future space never name a
+  // legitimate provider endpoint.
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return { kind: "private", detail: "reserved address" };
+  if (a === 198 && (b === 18 || b === 19)) return { kind: "private", detail: "benchmark address" };
+  if (a === 198 && b === 51 && c === 100) return { kind: "private", detail: "documentation address" };
+  if (a === 203 && b === 0 && c === 113) return { kind: "private", detail: "documentation address" };
+  if (a >= 224) return { kind: "private", detail: "multicast/reserved address" };
+  return { kind: "public", detail: "public IP" };
+}
+
+function firstIpv6Hextet(hostname: string): number | null {
+  const head = hostname.split(":")[0];
+  if (!head) return 0;
+  const parsed = Number.parseInt(head, 16);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+function classifyIpv6(hostname: string): DestinationAssessment {
+  if (BLOCKED_METADATA_IPV6.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+  const mappedIpv4 = hostname.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)?.[1];
+  if (mappedIpv4) return classifyIpv4(mappedIpv4);
+  // Decode hex IPv4-mapped IPv6: ::ffff:7f00:1 → 127.0.0.1
+  // The dotted-decimal regex above only matches ::ffff:127.0.0.1; without this,
+  // hex form bypasses all private/loopback checks (hextet is 0 → classified "public").
+  const hexMapped = hostname.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+  if (hexMapped) {
+    const hi = Number.parseInt(hexMapped[1], 16);
+    const lo = Number.parseInt(hexMapped[2], 16);
+    const ipv4 = `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
+    return classifyIpv4(ipv4);
+  }
+  if (hostname === "::1") return { kind: "loopback", detail: "loopback address" };
+  if (hostname === "::") return { kind: "unspecified", detail: "unspecified address" };
+  const hextet = firstIpv6Hextet(hostname);
+  if (hextet === null) return { kind: "private", detail: "non-global address" };
+  // Multicast ff00::/8, deprecated site-local fec0::/10, ULA fc00::/7, link-local fe80::/10.
+  if (hextet >= 0xff00) return { kind: "private", detail: "multicast address" };
+  if (hextet >= 0xfe80 && hextet <= 0xfebf) return { kind: "link-local", detail: "link-local address" };
+  if (hextet >= 0xfec0 && hextet <= 0xfeff) return { kind: "private", detail: "site-local address" };
+  if (hextet >= 0xfc00 && hextet <= 0xfdff) return { kind: "private", detail: "private-network address" };
+  // Documentation 2001:db8::/32 (inside global-unicast 2000::/3).
+  if (hextet === 0x2001) {
+    const second = Number.parseInt(hostname.split(":")[1] || "0", 16);
+    if (second === 0xdb8) return { kind: "private", detail: "documentation address" };
+  }
+  // Only global unicast 2000::/3 is treated as a public image/CDN peer.
+  if (hextet >= 0x2000 && hextet <= 0x3fff) return { kind: "public", detail: "public IP" };
+  return { kind: "private", detail: "non-global address" };
+}
+
+function assessDestination(baseUrl: string): DestinationAssessment | null {
+  try {
+    const parsed = new URL(baseUrl.trim());
+    const hostname = normalizeHostname(parsed.hostname);
+    if (!hostname) return null;
+    if (BLOCKED_METADATA_HOSTS.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+    if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+      return { kind: "localhost", detail: "localhost destination" };
+    }
+    const ipKind = isIP(hostname);
+    if (ipKind === 4) return classifyIpv4(hostname);
+    if (ipKind === 6) return classifyIpv6(hostname);
+    return { kind: "hostname", detail: "hostname destination" };
+  } catch {
+    return null;
+  }
+}
+
+function registryAllowsPrivateNetwork(name: string): boolean {
+  return getProviderRegistryEntry(name)?.allowPrivateNetworkByDefault === true;
+}
+
+/**
+ * Whether a provider may reach loopback/private addresses.
+ *
+ * Two sources, and both have to be consulted at every boundary: the operator's explicit
+ * `allowPrivateNetwork`, and the registry's `allowPrivateNetworkByDefault` for entries that are
+ * local BY DEFINITION (Ollama, vLLM, LM Studio, LiteLLM). Config validation already read both;
+ * outbound discovery read only the first, so a stock Ollama entry passed validation and was then
+ * refused at the fetch (#758).
+ *
+ * This grants nothing new. Metadata, link-local and unspecified destinations are rejected before
+ * this is consulted, and a provider without either source still cannot reach a private address.
+ */
+export function providerAllowsPrivateNetwork(
+  name: string,
+  provider: Pick<OcxProviderConfig, "allowPrivateNetwork">,
+): boolean {
+  return provider.allowPrivateNetwork === true || registryAllowsPrivateNetwork(name);
+}
+
+export function providerDestinationConfigError(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): string | null {
+  const assessment = assessDestination(provider.baseUrl);
+  if (!assessment) return null;
+  if (assessment.kind === "public" || assessment.kind === "hostname") return null;
+  if (assessment.kind === "metadata") return "baseUrl targets a blocked metadata endpoint";
+  if (providerAllowsPrivateNetwork(name, provider)) return null;
+  return `baseUrl points to a ${assessment.detail}; set allowPrivateNetwork:true only for intentionally local/self-hosted providers`;
+}
+
+export function assertProviderDestinationAllowed(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): void {
+  const error = providerDestinationConfigError(name, provider);
+  if (error) throw new Error(`provider ${name} ${error}`);
+}
+
+/**
+ * Async companion to {@link providerDestinationConfigError} for hostname destinations:
+ * resolves A/AAAA records and classifies every address, so a hostname that points at
+ * loopback/private/metadata space is caught at provider write time (review finding,
+ * PR #96 — the sync path must stay literal-only because the router hot path and
+ * config load are synchronous). DNS failures return null: config-time validation is
+ * advisory and must not hard-fail offline startups. DNS rebinding after validation is
+ * a recorded residual for this loopback proxy (devlog 260712_pr_batch_landing 000).
+ *
+ * `allowBenchmarkAddresses` is only for the exact canonical ChatGPT Codex seed under
+ * Clash fake-IP DNS (198.18.0.0/15). Every other non-public answer — including mixed
+ * benchmark + private/metadata sets — still fails.
+ */
+export async function providerDestinationResolvedError(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">,
+  options?: { allowBenchmarkAddresses?: boolean },
+): Promise<string | null> {
+  const syncError = providerDestinationConfigError(name, provider);
+  if (syncError) return syncError;
+  let hostname: string;
+  try {
+    hostname = normalizeHostname(new URL(provider.baseUrl.trim()).hostname);
+  } catch {
+    return null;
+  }
+  if (!hostname || isIP(hostname) !== 0 || hostname === "localhost" || hostname.endsWith(".localhost")) {
+    return null; // literals and localhost are fully handled by the sync path
+  }
+  if (providerAllowsPrivateNetwork(name, provider)) return null;
+  let addresses: { address: string }[];
+  try {
+    addresses = await lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    return null; // unresolvable now ≠ malicious; the provider simply won't connect
+  }
+  for (const { address } of addresses) {
+    const ipKind = isIP(address);
+    const assessment = ipKind === 4 ? classifyIpv4(address) : ipKind === 6 ? classifyIpv6(normalizeHostname(address)) : null;
+    if (!assessment || assessment.kind === "public") continue;
+    // Clash fake-IP only: 198.18/19 benchmark detail. Mixed dangerous sets still reject.
+    if (
+      options?.allowBenchmarkAddresses
+      && assessment.kind === "private"
+      && assessment.detail === "benchmark address"
+    ) {
+      continue;
+    }
+    if (assessment.kind === "metadata") return `baseUrl hostname ${hostname} resolves to a blocked metadata endpoint (${address})`;
+    return `baseUrl hostname ${hostname} resolves to a ${assessment.detail} (${address}); set allowPrivateNetwork:true only for intentionally local/self-hosted providers`;
+  }
+  return null;
+}
+
+export interface UrlDestinationAssessment {
+  kind: DestinationKind;
+  detail: string;
+}
+
+export class DestinationDnsResolutionError extends Error {
+  override readonly name = "DestinationDnsResolutionError";
+}
+
+/**
+ * Synchronous literal URL destination assessment — classifies the hostname
+ * without DNS resolution. Returns null for unparseable URLs.
+ */
+export function assessUrlDestination(url: string): UrlDestinationAssessment | null {
+  return assessDestination(url);
+}
+
+/**
+ * Async DNS-resolved URL safety check. By default, rejects every non-public
+ * address. Provider diagnostics may explicitly admit loopback/private answers;
+ * metadata, link-local, and unspecified addresses remain unconditionally denied.
+ * Returns the validated addresses so direct callers can pin the connect peer and
+ * avoid a second, rebindable resolution. DNS failures remain fail-closed here;
+ * the provider proxy wrapper alone may recognize that typed failure and degrade.
+ */
+export async function resolvePublicAddresses(
+  url: string,
+  options?: string | { context?: string; allowPrivateNetwork?: boolean },
+): Promise<{
+  hostname: string;
+  addresses: { address: string; family: number }[];
+  privateNetwork: boolean;
+}> {
+  const context = typeof options === "string"
+    ? `${options.trim() || "image"} URL`
+    : options?.context?.trim() || "image URL";
+  const privateNetworkAllowed = typeof options === "object" && options?.allowPrivateNetwork === true;
+  let hostname: string;
+  try {
+    hostname = normalizeHostname(new URL(url.trim()).hostname);
+  } catch {
+    throw new Error(`${context} is not a valid URL`);
+  }
+  if (!hostname) throw new Error(`${context} has no hostname`);
+  const literalAssessment = assessDestination(url);
+  let privateNetwork = false;
+  if (literalAssessment && literalAssessment.kind !== "public" && literalAssessment.kind !== "hostname") {
+    const allowedPrivateLiteral = privateNetworkAllowed
+      && (literalAssessment.kind === "localhost"
+        || literalAssessment.kind === "loopback"
+        || literalAssessment.kind === "private");
+    if (!allowedPrivateLiteral) throw new Error(`${context} targets ${literalAssessment.detail}`);
+    privateNetwork = true;
+  }
+  // Literal public IPs: no DNS round-trip; pin the literal itself.
+  const literalKind = isIP(hostname);
+  if (literalKind !== 0) {
+    return { hostname, addresses: [{ address: hostname, family: literalKind }], privateNetwork };
+  }
+  let addresses: { address: string; family: number }[];
+  try {
+    addresses = await lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    // If DNS fails, we can't verify — fail-closed (unlike provider config-time validation,
+    // this is a runtime fetch to an untrusted URL, so be conservative).
+    throw new DestinationDnsResolutionError(`${context} hostname ${hostname} could not be resolved`);
+  }
+  if (addresses.length === 0) {
+    throw new DestinationDnsResolutionError(`${context} hostname ${hostname} could not be resolved`);
+  }
+  const validatedAddresses: { address: string; family: number }[] = [];
+  for (const { address, family } of addresses) {
+    // Prefer classifying from the address string itself — do not trust a mislabeled
+    // resolver `family` that could skip IPv4/IPv6 private checks.
+    const ipKind = isIP(address) || (family === 4 || family === 6 ? family : 0);
+    const assessment = ipKind === 4 ? classifyIpv4(address) : ipKind === 6 ? classifyIpv6(normalizeHostname(address)) : null;
+    if (!assessment || assessment.kind !== "public") {
+      const allowedPrivateAddress = privateNetworkAllowed
+        && assessment
+        && (assessment.kind === "loopback" || assessment.kind === "private");
+      if (!allowedPrivateAddress) {
+        throw new Error(`${context} hostname ${hostname} resolves to ${assessment?.detail ?? "an unsafe address"} (${address})`);
+      }
+      privateNetwork = true;
+    }
+    validatedAddresses.push({ address, family: ipKind === 4 || ipKind === 6 ? ipKind : (family || 4) });
+  }
+  return { hostname, addresses: validatedAddresses, privateNetwork };
+}
+
+/**
+ * Void assertion wrapper around {@link resolvePublicAddresses} for call sites
+ * that only need the safety check.
+ */
+export async function assertUrlResolvesPublic(url: string): Promise<void> {
+  await resolvePublicAddresses(url);
+}

package/src/lib/errors.ts

@@ -0,0 +1,364 @@
+export interface OcxErrorPayload {
+  message: string;
+  type: string;
+  code: string | null;
+}
+
+/** OpenAI / Codex hard block for high-risk cybersecurity activity (HTTP 400 or mid-stream). */
+export const CYBER_POLICY_ERROR_CODE = "cyber_policy";
+
+export function isCyberPolicyCode(code: string | null | undefined): boolean {
+  return code === CYBER_POLICY_ERROR_CODE;
+}
+
+/**
+ * Detect OpenAI cyber-policy refusals from message text when structured `code` was stripped.
+ * Matches Codex fallback copy and Cursor/API agent wording (session evidence 2026-07-24).
+ * Does not treat a bare `cyber_policy` token as conclusive — model ids / routing errors can
+ * include that substring without being a policy refusal.
+ */
+export function isCyberPolicyMessage(text: string): boolean {
+  const lower = text.toLowerCase();
+  // Serialized error-code signatures only (not bare model-id collisions).
+  if (/"code"\s*:\s*"cyber_policy"/.test(lower)) return true;
+  if (/\bcode\s*[:=]\s*["']?cyber_policy\b/.test(lower)) return true;
+  if (lower.includes("high-risk cybersecurity")) return true;
+  if (lower.includes("high-risk cyber activity") || lower.includes("high-risk cyber ")) return true;
+  if (lower.includes("possible cybersecurity risk")) return true;
+  if (lower.includes("flagged") && lower.includes("cybersecurity")) return true;
+  if (lower.includes("flagged") && lower.includes("cyber activity")) return true;
+  return false;
+}
+
+function isSubscriptionGateMessage(text: string): boolean {
+  return (
+    text.includes("requires a subscription") ||
+    text.includes("requires subscription") ||
+    text.includes("subscription required") ||
+    text.includes("upgrade for access") ||
+    text.includes("upgrade to pro") ||
+    text.includes("pro subscription") ||
+    text.includes("ollama.com/upgrade") ||
+    (text.includes("upgrade") && text.includes("subscription"))
+  );
+}
+
+function isAuthenticationMessage(text: string): boolean {
+  const accessDeniedWithCredentialCue = (
+    text.includes("access denied") ||
+    text.includes("accessdeniedexception")
+  ) && (
+    text.includes("authentication") ||
+    text.includes("credential") ||
+    text.includes("api key") ||
+    text.includes("token") ||
+    text.includes("signature")
+  );
+  return (
+    text.includes("authentication failed") ||
+    text.includes("authentication") ||
+    text.includes("invalid_api_key") ||
+    text.includes("invalid api key") ||
+    text.includes("invalid token") ||
+    text.includes("unauthorizedexception") ||
+    text.includes("unrecognizedclientexception") ||
+    text.includes("unrecognizedclient") ||
+    text.includes("expired token") ||
+    text.includes("expiredtoken") ||
+    text.includes("unauthenticated") ||
+    text.includes("unauthorized") ||
+    accessDeniedWithCredentialCue
+  );
+}
+
+function isPermissionMessage(text: string): boolean {
+  return (
+    text.includes("permission_denied") ||
+    text.includes("permission denied") ||
+    text.includes("forbidden") ||
+    text.includes("access denied") ||
+    text.includes("accessdeniedexception") ||
+    text.includes("not allowed to use") ||
+    text.includes("model access")
+  );
+}
+
+/**
+ * Client cancelled / closed the turn. Matches ONLY abort phrases this codebase
+ * produces — "client closed request during web-search" (src/web-search/loop.ts),
+ * "Client cancelled request" (src/server/responses.ts) — plus the explicit
+ * "request cancel(l)ed by client" forms. Deliberately narrow: bare "client closed"
+ * would also swallow legitimate upstream failures like "upstream HTTP client
+ * closed idle connection" and turn a real 502 into a 499.
+ */
+export function isClientClosedMessage(text: string): boolean {
+  const lower = text.toLowerCase();
+  return (
+    lower.includes("client closed request") ||
+    lower.includes("client cancelled request") ||
+    lower.includes("client canceled request") ||
+    lower.includes("request canceled by client") ||
+    lower.includes("request cancelled by client")
+  );
+}
+
+export function classifyError(status: number, type: string, message: string): OcxErrorPayload {
+  const text = message.toLowerCase();
+  if (type === "previous_response_not_found") {
+    return { message, type: "invalid_request_error", code: "previous_response_not_found" };
+  }
+  // Preserve explicit cancel types used by compact/combo JSON errors; unify message-inferred
+  // client closes (web-search abort text) onto client_closed_request for /api/logs.
+  if (type === "client_cancelled") {
+    return { message, type: "client_cancelled", code: "client_cancelled" };
+  }
+  if (
+    status === 499 ||
+    type === "client_closed_request" ||
+    isClientClosedMessage(text)
+  ) {
+    return { message, type: "invalid_request_error", code: "client_closed_request" };
+  }
+  // Codex only shows the dedicated cyber UI when error.code === "cyber_policy".
+  // Prefer that code (and invalid_request_error) over generic remaps / 502 upstream_server_error.
+  if (type === CYBER_POLICY_ERROR_CODE || isCyberPolicyMessage(text)) {
+    return { message, type: "invalid_request_error", code: CYBER_POLICY_ERROR_CODE };
+  }
+  if (
+    text.includes("context_length_exceeded") ||
+    text.includes("context window") ||
+    text.includes("context length") ||
+    text.includes("maximum context") ||
+    text.includes("too many tokens")
+  ) {
+    return { message, type: "invalid_request_error", code: "context_length_exceeded" };
+  }
+  // "Cursor resource limit exceeded" is emitted only for explicit request-size overflow
+  // details (isCursorRequestTooLargeDetail in cursor-errors.ts); quota-style resource
+  // exhaustion arrives as "Cursor rate limit exceeded" and falls through to 429 below.
+  if (text.includes("cursor resource limit exceeded")) {
+    return { message, type: "invalid_request_error", code: "tool_catalog_too_large" };
+  }
+  // The Cursor adapter's classified rate-limit prefix is authoritative: its DETAIL may echo
+  // quota wording ("... quota exhausted") that would otherwise hit the insufficient_quota
+  // branch below and break the planned retry-with-backoff contract (WP3 review blocker 1).
+  if (text.includes("cursor rate limit exceeded")) {
+    return { message, type: "rate_limit_error", code: "rate_limit_exceeded" };
+  }
+  if (
+    text.includes("insufficient_quota") ||
+    text.includes("exceeded your current quota") ||
+    text.includes("quota exhausted") ||
+    text.includes("account quota exceeded") ||
+    text.includes("monthly quota exceeded") ||
+    text.includes("daily quota exceeded")
+  ) {
+    return { message, type: "insufficient_quota", code: "insufficient_quota" };
+  }
+  if (
+    status === 429 ||
+    text.includes("rate limit") ||
+    text.includes("rate limited") ||
+    text.includes("too many requests") ||
+    text.includes("resource_exhausted") ||
+    text.includes("resource exhausted") ||
+    text.includes("throttlingexception") ||
+    text.includes("throttling")
+  ) {
+    return { message, type: "rate_limit_error", code: "rate_limit_exceeded" };
+  }
+  if (type === "origin_rejected") {
+    return { message, type: "invalid_request_error", code: "origin_rejected" };
+  }
+  // HTTP 401 and explicit auth failures are authoritative even when provider text
+  // also advertises an upgrade or subscription.
+  if (
+    status === 401 ||
+    type === "authentication_error" ||
+    isAuthenticationMessage(text)
+  ) {
+    return { message, type: "authentication_error", code: "invalid_api_key" };
+  }
+  // Subscription labels are valid only in a known permission context.
+  if (
+    (status === 403 || type === "permission_error") &&
+    isSubscriptionGateMessage(text)
+  ) {
+    return { message, type: "permission_error", code: "subscription_required" };
+  }
+  if (
+    status === 403 ||
+    type === "permission_error" ||
+    isPermissionMessage(text)
+  ) {
+    return { message, type: "permission_error", code: "permission_denied" };
+  }
+  if (
+    status === 503 ||
+    text.includes("overloaded") ||
+    text.includes("server is busy") ||
+    text.includes("temporarily unavailable")
+  ) {
+    // Codex recognizes "server_is_overloaded" and applies retry-after backoff
+    // (responses.rs is_server_overloaded_error); generic "upstream_server_error" is not recognized.
+    return { message, type: "server_error", code: "server_is_overloaded" };
+  }
+  if (
+    text.includes("validationexception") ||
+    text.includes("invalid request") ||
+    text.includes("model unavailable") ||
+    text.includes("model not found") ||
+    text.includes("unsupported model") ||
+    text.includes("profile arn") ||
+    text.includes("wrong region") ||
+    text.includes("invalid region")
+  ) {
+    return { message, type: "invalid_request_error", code: "invalid_request_error" };
+  }
+  if (status >= 500) {
+    return { message, type: "server_error", code: "upstream_server_error" };
+  }
+  if (status === 400 || type === "invalid_request_error") {
+    return { message, type: "invalid_request_error", code: "invalid_request_error" };
+  }
+  return { message, type, code: type || null };
+}
+
+/**
+ * True when a provider failure should participate in rate-limit / quota health blocking.
+ * Reuses {@link classifyError} so generic 429 wording and quota phrases stay aligned.
+ */
+export function isRateLimitOrQuotaFailureMessage(message: string): boolean {
+  const normalized = String(message ?? "").trim();
+  if (!normalized) return false;
+  const numericStatus = Number(normalized);
+  if (numericStatus === 429 || numericStatus === 402) return true;
+  const statusHint = Number.isInteger(numericStatus) && numericStatus > 0 ? numericStatus : 0;
+  const classified = classifyError(statusHint, "", normalized);
+  if (
+    classified.type === "rate_limit_error"
+    || classified.code === "rate_limit_exceeded"
+    || classified.type === "insufficient_quota"
+    || classified.code === "insufficient_quota"
+  ) {
+    return true;
+  }
+  // Retained quota cue used by subagent health before classifyError covered it.
+  return normalized.toLowerCase().includes("usage limit");
+}
+
+/** Best-effort parse of a retry delay embedded in an upstream error message. */
+export function parseRetryAfterFromMessage(message: string): number | undefined {
+  const patterns = [
+    /try again in (\d+(?:\.\d+)?)\s*s(?:ec(?:ond)?s?)?/i,
+    /retry after (\d+(?:\.\d+)?)\s*s(?:ec(?:ond)?s?)?/i,
+    /retry[- ]after[:\s]+(\d+)/i,
+  ];
+  for (const pattern of patterns) {
+    const match = message.match(pattern);
+    if (!match?.[1]) continue;
+    const seconds = Number.parseFloat(match[1]);
+    if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds);
+  }
+  return undefined;
+}
+
+/** Infer HTTP status from adapter terminal error text (provider-agnostic keyword matching). */
+export function inferHttpStatusFromAdapterMessage(message: string): number {
+  const lower = message.toLowerCase();
+  // Client aborts (e.g. mid web-search loop) must not look like upstream 502s in /api/logs.
+  if (isClientClosedMessage(lower)) return 499;
+  // Codex Transport maps cyber_policy only on HTTP 400 (SSE is code-based).
+  if (isCyberPolicyMessage(lower)) return 400;
+  // See classifyError: this prefix now only means explicit request-size overflow (400);
+  // quota-style Cursor resource exhaustion carries the rate-limit prefix and maps to 429.
+  if (lower.includes("cursor resource limit exceeded")) return 400;
+  if (
+    lower.includes("resource_exhausted") ||
+    lower.includes("resource exhausted") ||
+    lower.includes("rate limit") ||
+    lower.includes("too many requests") ||
+    lower.includes("throttling")
+  ) return 429;
+  // Strong authentication signals win when a message contains mixed auth and
+  // subscription/permission wording.
+  if (isAuthenticationMessage(lower)) return 401;
+  if (isSubscriptionGateMessage(lower) || isPermissionMessage(lower)) return 403;
+  if (
+    lower.includes("unavailable") ||
+    lower.includes("overloaded") ||
+    lower.includes("temporarily") ||
+    lower.includes("server is busy")
+  ) return 503;
+  if (
+    lower.includes("invalid") ||
+    lower.includes("not found") ||
+    lower.includes("unsupported") ||
+    lower.includes("malformed") ||
+    lower.includes("unimplemented")
+  ) return 400;
+  if (
+    lower.includes("timed out") ||
+    lower.includes("timeout") ||
+    lower.includes("etimedout") ||
+    lower.includes("deadline")
+  ) return 504;
+  return 502;
+}
+
+/** Map an adapter terminal error message to HTTP status + classified Codex error payload. */
+export function adapterFailureFromMessage(message: string): { httpStatus: number; error: OcxErrorPayload } {
+  const httpStatus = inferHttpStatusFromAdapterMessage(message);
+  let finalMessage = message;
+  const retryAfterSeconds = parseRetryAfterFromMessage(message);
+  if (retryAfterSeconds && !/please try again in /i.test(message)) {
+    finalMessage = `${message} Please try again in ${retryAfterSeconds}s.`;
+  }
+  const errorType = httpStatus === 499
+    ? "client_closed_request"
+    : httpStatus === 429
+      ? "rate_limit_error"
+      : httpStatus === 401
+        ? "authentication_error"
+        : httpStatus === 403
+          ? "permission_error"
+          : httpStatus === 503 || httpStatus === 504
+            ? "server_error"
+            : httpStatus === 400
+              ? "invalid_request_error"
+              : "upstream_error";
+  return {
+    httpStatus,
+    error: classifyError(httpStatus, errorType, finalMessage),
+  };
+}
+
+/** Map a terminal Responses error object to the HTTP status we record in /api/logs. */
+export function httpStatusFromTerminalError(error: {
+  type?: string;
+  code?: string | null;
+  message?: string;
+} | undefined): number {
+  if (!error) return 502;
+  if (error.code === "client_closed_request" || error.code === "client_cancelled") return 499;
+  if (isCyberPolicyCode(error.code) || (error.message ? isCyberPolicyMessage(error.message) : false)) {
+    return 400;
+  }
+  if (error.type === "rate_limit_error" || error.code === "rate_limit_exceeded") return 429;
+  if (error.type === "authentication_error" || error.code === "invalid_api_key") return 401;
+  if (
+    error.type === "permission_error" ||
+    error.code === "permission_denied" ||
+    error.code === "subscription_required"
+  ) return 403;
+  if (error.type === "insufficient_quota" || error.code === "insufficient_quota") return 429;
+  if (error.type === "server_error" && error.code === "server_is_overloaded") return 503;
+  // Client-closed messages often arrive as invalid_request_error after classifyError; check message
+  // before treating every invalid_request_error as HTTP 400.
+  const message = error.message ?? "";
+  if (message && isClientClosedMessage(message)) return 499;
+  if (error.type === "invalid_request_error") return 400;
+  if (error.type === "proxy_error") return 500;
+  if (message) return inferHttpStatusFromAdapterMessage(message);
+  return 502;
+}