cartethyia 2.7.8 → 2.8.0

package/src/transport/dispatch/streaming/finalize.ts

@@ -23,7 +23,7 @@ import type { AdmissionLease } from "../../../security/admission/contracts";
 import type { Reservation } from "../../routing/route-model";
 import { repriceUsage } from "../../../providers/provider-usage";
 import { metrics } from "../../../observability/metrics";
-import { flagPoolBlocked, flagPoolCooldown } from "../../../network/pool-health";
+import { flagPoolOnEgressFailure } from "../../../network/pool-health";
 import { classifyEgressFailure } from "../../../network/rate-limit-verdict";
 import { releaseAttemptLeases } from "../leases";
 import type { AttemptLeaseOwnership } from "../leases";
@@ -581,11 +581,14 @@ export class StreamFinalizer {
     this.streamSettled = true;
     if (candidate.networkPoolId && !cancelled && deps.poolSelector && err instanceof GatewayError) {
       const egressVerdict = classifyEgressFailure(err, candidate.providerId);
-      if (egressVerdict.kind === "cooldown") {
-        flagPoolCooldown(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
-      } else if (egressVerdict.kind === "blocked") {
-        flagPoolBlocked(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
-      }
+      flagPoolOnEgressFailure(
+        deps.poolSelector,
+        deps.db,
+        candidate.networkPoolId,
+        candidate.providerId,
+        err,
+        egressVerdict,
+      );
     }
     if (!cancelled) metrics.proxy_requests_total.inc(1, { status: "failed" });
     else metrics.proxy_requests_total.inc(1, { status: "cancelled" });

package/src/transport/dispatch/streaming/stream.ts

@@ -43,17 +43,11 @@ import type { AdmissionLease } from "../../../security/admission/contracts";
 import type { NetworkPoolSelector } from "../../../network/pool/selector";
 import type { TelemetryBatchBuffer } from "../../../observability/telemetry-buffer";
 import type { ProviderExchangeCapture } from "../attempt-finalize";
-import { captureProviderExchange } from "../attempt-finalize";
-import {
-  providerCaptureMaxBytes,
-  resolveCaptureDepthForRequest,
-  resolveCaptureModeForRequest,
-  shouldCaptureProviderBodyForRequest,
-} from "../capture-policy";
+import { resolveCaptureModeForRequest } from "../capture-policy";
 import { resolveTenantImageClampMaxBytes, readTenantSystemPromptsForDispatch } from "../../request/tenant-preferences";
 import { resolveTenantSystemPrompt } from "../../request/system-prompt-injection";
 import { isWrappedInjectionProvider } from "../../../console/system-prompt/contracts";
-import { proxySuccessHeaders, buildUpstreamDispatchContext } from "../upstream";
+import { proxySuccessHeaders, buildUpstreamDispatchContext, buildDispatchNetworkBindings } from "../upstream";
 import type { AttemptLeaseOwnership } from "../leases";
 import type { ProviderContinuationScope } from "../../../providers/provider-contracts";
 import { resolveStreamFirstChunkTimeoutMs, resolveStreamStallTimeoutMs, resolveUpstreamTimeoutMs } from "../../../config/timeouts";
@@ -170,18 +164,13 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
     continuationScope,
   } = input;
 
-  const outboundFetch = deps.networkBindingFactory?.fetch(
+  const bindings = await buildDispatchNetworkBindings({
+    deps,
     networkPoolId,
-    prepared.authorization.snapshot.tenant_id,
-  );
-  const captureBody = outboundFetch
-    ? await shouldCaptureProviderBodyForRequest(deps.db, prepared.authorization.snapshot.tenant_id, state)
-    : false;
-  const captureDepth = await resolveCaptureDepthForRequest(
-    deps.db,
-    prepared.authorization.snapshot.tenant_id,
+    tenantId: prepared.authorization.snapshot.tenant_id,
+    providerCapture,
     state,
-  );
+  });
   // Resolved once, before the pipeline exists: the pipeline's diagnostics are
   // gated on it from construction, so `none`/`metadata` tenants never pay the
   // transcript serialization or the client-response copy for any event.
@@ -190,14 +179,6 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
     prepared.authorization.snapshot.tenant_id,
     state,
   );
-  const wrappedOutboundFetch = outboundFetch
-    ? captureProviderExchange(
-        outboundFetch,
-        providerCapture,
-        captureBody,
-        providerCaptureMaxBytes(captureDepth),
-      )
-    : undefined;
   // Same memoized ceiling the non-streaming path resolves, read before the
   // dispatch context is built so a stream gets the same limit as a normal
   // request rather than silently falling back to the deployment default.
@@ -237,18 +218,10 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
       return text === undefined ? {} : { tenantSystemPrompt: text };
     })()),
     ...(candidate.user_agent === undefined ? {} : { userAgent: candidate.user_agent }),
-    ...(wrappedOutboundFetch ? { outboundFetch: wrappedOutboundFetch } : {}),
-    ...(outboundFetch ? { outboundAttachmentFetch: outboundFetch } : {}),
-    ...(deps.networkBindingFactory
-      ? {
-          outboundHttp2: deps.networkBindingFactory.http2Bidi(
-            networkPoolId,
-            prepared.authorization.snapshot.tenant_id,
-          ),
-        }
-      : {}),
+    ...bindings,
     ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
     ...(continuationScope === undefined ? {} : { continuationScope }),
+    ...(providerCapture ? { providerCapture } : {}),
   });
   // `ProviderAdapter.dispatch` is declared to return a non-nullable
   // `AsyncIterable`, so an adapter that returned `undefined` would be a

package/src/transport/dispatch/systemone.ts

@@ -4,6 +4,7 @@ import { metrics } from "../../observability/metrics";
 import { estimatedUsage, nativeCompletionBase, completeAttempt } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
 import {
+  forwardUpstreamResponse,
   networkFetchContext,
   requireRecordBody,
   resolveAttemptCredential,
@@ -164,14 +165,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           responseBody: null,
         });
         metrics.proxy_requests_total.inc(1, { status: "completed" });
-        return new Response(response.body, {
-          status: response.status,
-          headers: {
-            "content-type": response.headers.get("content-type") ?? "application/json",
-            "cache-control": "no-store",
-            "x-request-id": state.requestId,
-          },
-        });
+        return forwardUpstreamResponse(response, state.requestId);
       },
     });
   };

package/src/transport/dispatch/token-count.ts

@@ -43,7 +43,7 @@ import type { PreparedNativeRequest } from "../request/preparer";
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { finalizeRequestTelemetry } from "../guards/error-lifecycle";
 import { runAttemptLoop } from "./attempt-loop";
-import { hasScope, networkFetchContext, requireRecordBody, resolveAttemptCredential } from "./native-shared";
+import { forwardUpstreamResponse, hasScope, networkFetchContext, requireRecordBody, resolveAttemptCredential } from "./native-shared";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
@@ -189,11 +189,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
 
         // Verbatim: the client reads the provider's own number, and the
         // provider's own error when it refuses to produce one.
-        const contentType = upstream.headers.get("content-type") ?? "application/json";
-        return new Response(upstream.body, {
-          status: upstream.status,
-          headers: { "content-type": contentType, "cache-control": "no-store", "x-request-id": state.requestId },
-        });
+        return forwardUpstreamResponse(upstream, state.requestId);
       },
     });
   };

package/src/transport/dispatch/upstream.ts

@@ -1,7 +1,16 @@
 import type { CanonicalEvent } from "../../protocol/canonical-model";
 import type { AttemptLeaseOwnership, ValidatedOutboundFetch, ValidatedOutboundHttp2Bidi } from "../../providers/provider-contracts";
-import type { ProviderContinuationScope } from "../../providers/provider-contracts";
+import type { ProviderCaptureExchange, ProviderContinuationScope } from "../../providers/provider-contracts";
 import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
+import type { ValidatedNetworkBindingFactory } from "../../network/pool/resolver";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { captureProviderExchange, type ProviderExchangeCapture } from "./attempt-finalize";
+import {
+  providerCaptureMaxBytes,
+  resolveCaptureDepthForRequest,
+  shouldCaptureProviderBodyForRequest,
+  type CapturePreferenceState,
+} from "./capture-policy";
 
 const FORWARDED_REQUEST_HEADERS = new Set([
   "user-agent",
@@ -34,6 +43,60 @@ export function proxySuccessHeaders(state: { requestId: string }): Record<string
   };
 }
 
+/** The three validated egress bindings shared by every dispatch attempt. */
+export interface DispatchNetworkBindings {
+  readonly outboundFetch?: ValidatedOutboundFetch;
+  readonly outboundAttachmentFetch?: ValidatedOutboundFetch;
+  readonly outboundHttp2?: ValidatedOutboundHttp2Bidi;
+}
+
+/**
+ * Builds the outbound network bindings for one attempt's dispatch context,
+ * shared by the non-streaming proxy path and the streaming branch.
+ *
+ * Both previously assembled the same three objects by hand (wrapped fetch,
+ * attachment fetch, HTTP/2 bidi), which drifted in the capture wrap. The
+ * capture-body gating is preserved exactly: the DB-backed capture-preference
+ * read is skipped when no network binding exists (`outboundFetch ? ... :
+ * false`), so a request that can never tee a provider exchange does not pay
+ * for the preference read. The reads are memoized on the request state, so
+ * resolving them here costs no extra DB reads.
+ */
+export async function buildDispatchNetworkBindings(input: {
+  readonly deps: {
+    readonly networkBindingFactory?: ValidatedNetworkBindingFactory | undefined;
+    readonly db: CartethyiaDatabase;
+  };
+  readonly networkPoolId: string | undefined;
+  readonly tenantId: string | null;
+  readonly providerCapture: ProviderExchangeCapture;
+  readonly state: CapturePreferenceState;
+}): Promise<DispatchNetworkBindings> {
+  const factory = input.deps.networkBindingFactory;
+  if (factory === undefined) return {};
+  const outboundFetch = factory.fetch(input.networkPoolId, input.tenantId ?? undefined);
+  const captureBody = await shouldCaptureProviderBodyForRequest(
+    input.deps.db,
+    input.tenantId,
+    input.state,
+  );
+  const captureDepth = await resolveCaptureDepthForRequest(
+    input.deps.db,
+    input.tenantId,
+    input.state,
+  );
+  return {
+    outboundFetch: captureProviderExchange(
+      outboundFetch,
+      input.providerCapture,
+      captureBody,
+      providerCaptureMaxBytes(captureDepth),
+    ),
+    outboundAttachmentFetch: factory.fetch(input.networkPoolId, input.tenantId ?? undefined),
+    outboundHttp2: factory.http2Bidi(input.networkPoolId, input.tenantId ?? undefined),
+  };
+}
+
 export function buildUpstreamDispatchContext(input: {
   readonly credential: unknown;
   readonly deadline: number;
@@ -42,6 +105,8 @@ export function buildUpstreamDispatchContext(input: {
   readonly requestId?: string;
   readonly userAgent?: string;
   readonly outboundFetch?: ValidatedOutboundFetch;
+  /** Capture sink for provider exchanges not visible to the HTTP fetch wrapper. */
+  readonly providerCapture?: ProviderCaptureExchange;
   /** Validated attachment egress that must not be wrapped by provider payload capture. */
   readonly outboundAttachmentFetch?: ValidatedOutboundFetch;
   /** Validated bidirectional HTTP/2 egress bound to the same selected pool. */
@@ -100,6 +165,7 @@ export function buildUpstreamDispatchContext(input: {
     ...(userAgent ? { user_agent: userAgent } : {}),
     ...(Object.keys(input.headers).length > 0 ? { request_headers: input.headers } : {}),
     ...(outboundFetch ? { outbound_fetch: outboundFetch } : {}),
+    ...(input.providerCapture ? { provider_capture: input.providerCapture } : {}),
     ...(input.outboundAttachmentFetch
       ? { outbound_attachment_fetch: input.outboundAttachmentFetch }
       : {}),

package/src/transport/drain-endpoint.ts

@@ -50,14 +50,41 @@ export function tokenMatches(provided: string | null, expected: string): boolean
   return a.length === b.length && timingSafeEqual(a, b);
 }
 
+interface LoopbackAdminGate {
+  /** Peer address of the request, resolved by the composition root. */
+  readonly peer: string | null;
+  /** Shared secret; the route is registered only when this is set. */
+  readonly token: string;
+  /** `policy_rejected` (403) message, preserved per surface. */
+  readonly policyRejectedMessage: string;
+  /** `authentication_failed` (401) message, preserved per surface. */
+  readonly authenticationFailedMessage: string;
+}
+
+/**
+ * The shared security gate for host-local admin operations: the request must
+ * come from loopback, then it must carry the drain token compared in constant
+ * time. The peer check is independent of the secret, so a leaked token alone
+ * cannot reach a remote surface. The peer refusal comes first, then the token,
+ * with the codes and messages preserved verbatim per caller.
+ */
+export function requireLoopbackAdmin(request: Request, gate: LoopbackAdminGate): void {
+  if (!isLoopbackPeer(gate.peer))
+    throw new GatewayError("policy_rejected", 403, gate.policyRejectedMessage);
+  if (!tokenMatches(request.headers.get("x-drain-token"), gate.token))
+    throw new GatewayError("authentication_failed", 401, gate.authenticationFailedMessage);
+}
+
 export function createDrainHandler(
   deps: DrainEndpointDeps,
 ): (context: { request: Request }) => Promise<Response> {
   return async ({ request }) => {
-    if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError("policy_rejected", 403, "drain is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂");
-    if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
-      throw new GatewayError("authentication_failed", 401, "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑");
+    requireLoopbackAdmin(request, {
+      peer: deps.resolvePeerAddress(request),
+      token: deps.token,
+      policyRejectedMessage: "drain is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
+      authenticationFailedMessage: "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑",
+    });
     // Acknowledge first, then drain: the response must be on the wire before the
     // shutdown path starts closing sockets, or the caller sees a dropped
     // connection instead of a 202.

package/src/transport/failure-policy.ts

@@ -2,7 +2,6 @@ import { GatewayError, type GatewayErrorCode, type GatewayErrorOrigin } from "..
 import { isRecord } from "../protocol/codecs";
 import { resolveFallbackRetryBaseMs, resolveFallbackRetryCapMs } from "../config/timeouts";
 import { parseUpstreamBackoff } from "../protocol/upstream-parsing";
-import { resolveAccountQuotaCooldownMs } from "../config/cooldowns";
 
 /**
  * How much of the upstream's error body is kept and surfaced.
@@ -14,6 +13,7 @@ import { resolveAccountQuotaCooldownMs } from "../config/cooldowns";
  * runs a few KB; 4000 keeps the whole thing while bounding a hostile body.
  */
 const MAX_UPSTREAM_ERROR_BYTES = 4000;
+export { MAX_UPSTREAM_ERROR_BYTES };
 export {
   parseRetryAfter,
   parseRateLimitReset,
@@ -22,6 +22,32 @@ export {
   parseProviderResetDuration,
   parseAbsoluteResetTimestamp,
 } from "../protocol/upstream-parsing";
+/**
+ * Extracts only the human-readable text from an upstream error body —
+ * `message`/`msg`/`error` fields — deliberately skipping `code`/identifier
+ * values. Used by `upstreamMessageAsIs` to decide whether the upstream
+ * actually supplied a message: a symbolic code like `"permission_error"` is
+ * an identifier, not prose, so it must not count as passthrough text.
+ */
+export function extractUpstreamMessageText(body: unknown): string {
+  let raw = "";
+  if (typeof body === "string") raw = body;
+  else if (isRecord(body)) {
+    if (typeof body.error === "string" && body.error.trim()) raw = body.error;
+    else {
+      const envelope = isRecord(body.error) ? body.error : body;
+      const message = (envelope as Record<string, unknown>).message;
+      if (typeof message === "string" && message.trim()) raw = message;
+      else if (typeof body.msg === "string" && body.msg.trim()) raw = body.msg;
+      else if (typeof (envelope as Record<string, unknown>).msg === "string" && String((envelope as Record<string, unknown>).msg).trim())
+        raw = String((envelope as Record<string, unknown>).msg);
+      else if (typeof (envelope as Record<string, unknown>).error === "string" && String((envelope as Record<string, unknown>).error).trim())
+        raw = String((envelope as Record<string, unknown>).error);
+    }
+  }
+  return raw.replace(/[\r\n]+/g, " ").trim();
+}
+
 /** Extracts a bounded, newline-free provider message from any error envelope. */
 export function extractUpstreamMessage(body: unknown): string {
   let raw = "";
@@ -233,31 +259,6 @@ export function classifyUpstreamFailure(error: unknown): UpstreamFailurePolicy {
   // DNS failure. Failing the client request instead of failing over is the wrong
   // outcome for a whole class the table already names as platform-wide.
   const statusCode = error.status;
-  // Qoder answers an exhausted quota by closing the stream with an upstream 499
-  // (nginx client-close style). That is a refusal from the upstream — the
-  // gateway's own aborts are `transport_closed`, produced locally, and never
-  // carry a qoder providerId — so a 499 scoped to qoder is quota, not a
-  // malformed request. Without this it fell through to `invalid_request`
-  // (non-retryable, no cooldown) and the account was re-dialled on every
-  // request inside the exhausted window until a late 429 finally classified it.
-  if (
-    error.origin === "upstream" &&
-    statusCode === 499 &&
-    (providerId === "qoder" || providerId === "qodercn")
-  ) {
-    const cooldownMs = resolveAccountQuotaCooldownMs();
-    return {
-      retryable: true,
-      mutatesAccount: true,
-      category: "quota_exceeded",
-      scope: "account",
-      origin: error.origin,
-      ...(providerCode ? { providerCode } : {}),
-      ...(providerId ? { providerId } : {}),
-      cooldownMs,
-      statusCode,
-    };
-  }
   const retryableByStatus =
     statusCode === 401 ||
     statusCode === 403 ||
@@ -657,10 +658,8 @@ const QUOTA_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   // quota (a cooldown) instead of `auth_invalidated`.
   "110",
   // Qoder also reports quota exhaustion as `{"code":116,"error":"quota
-  // exceeded"}` (seen on the IDE model-server surface with a 499/stream
-  // close). The 499 special-case below already treats qoder 499 as quota;
-  // naming the code here makes any status that carries it classify as quota
-  // instead of `invalid_request`/`authentication_failed`.
+  // exceeded"}`. Naming the code here makes any status that carries it classify
+  // as quota instead of `invalid_request`/`authentication_failed`.
   "116",
   // InferHub publishes its own vocabulary in `error.code`. The two 403s below
   // are deliberate absences: `account_blocked` means the account was blocked
@@ -696,6 +695,25 @@ const AUTH_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   "insufficient_key_scope",
   "model_not_allowed_for_key",
 ]);
+
+/**
+ * Qoder job-token verdicts that are NOT credential evidence.
+ *
+ * A PAT (`pt-…`) is exchanged for a short-lived job token (`jt-…`). When the
+ * job token expires mid-flight the upstream answers `{"code":"105","message":
+ * "Login expired"}` (403). The PAT is still valid — re-exchanging it mints a
+ * fresh job token — so treating this as `auth_invalidated` parked a healthy
+ * account as "Re-login required". It stays `authentication_failed` (retryable;
+ * the next attempt re-runs the PAT exchange) but without `credentialEvidence`,
+ * so the account is never disabled or cooled on it.
+ */
+const QODER_JOB_TOKEN_EXPIRED: ReadonlySet<string> = new Set([
+  "105",
+  "login expired",
+  "login_expired",
+  "job token expired",
+  "jobtoken expired",
+]);
 const PLATFORM_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   "server_error",
   "internal_error",
@@ -800,6 +818,20 @@ export function classifyUpstreamError(
     return { code: "proxy_auth_required", status: 407, origin: "network" };
   if (normalized === "11140")
     return { code: "policy_rejected", status: 403, origin: "upstream" };
+  // ZCode plan-lane envelope codes (verified live 2026-10-30 by the donor and
+  // mirrored by the zcode-start provider). `3009` is model concurrency
+  // (transient, retried in place), `3008` user concurrency (the desktop client
+  // is busy on that account — switchable), `3012` is the identity/prompt-shape
+  // gate, `1113` the paid-lane "insufficient balance or no resource package"
+  // (a request that was not recognized as start-plan traffic).
+  if (normalized === "3009")
+    return { code: "rate_limited", status: 429, origin: "upstream" };
+  if (normalized === "3008")
+    return { code: "accounts_rate_limited", status: 429, origin: "upstream" };
+  if (normalized === "3012")
+    return { code: "policy_rejected", status: 405, origin: "upstream" };
+  if (normalized === "1113")
+    return { code: "quota_exceeded", status: 429, origin: "upstream", rateLimitScope: "provider" };
   if (normalized !== undefined && CONTEXT_LENGTH_CODES.has(normalized))
     return { code: "context_length_exceeded", status: 413, origin: "upstream" };
   if (normalized !== undefined && QUOTA_ERROR_IDENTIFIERS.has(normalized))
@@ -809,6 +841,16 @@ export function classifyUpstreamError(
       origin: "upstream",
       rateLimitScope: "provider",
     };
+  // Qoder job-token expiry (`105` / "Login expired") is recoverable by
+  // re-exchanging the PAT — never credential evidence (see
+  // `QODER_JOB_TOKEN_EXPIRED`).
+  if (normalized !== undefined && QODER_JOB_TOKEN_EXPIRED.has(normalized)) {
+    return {
+      code: "authentication_failed",
+      status: status === 403 || status === 401 ? status : 403,
+      origin: "upstream",
+    };
+  }
   if (normalized !== undefined && AUTH_ERROR_IDENTIFIERS.has(normalized)) {
     let authStatus: number;
     if (status === 401 || status === 403) authStatus = status;
@@ -919,17 +961,15 @@ export async function mapUpstreamHttpError(response: Response, providerId: strin
     : isContextLengthFailure(parsedBody)
       ? { code: "context_length_exceeded" as const, status: 413, origin: "upstream" as const }
       : classifyUpstreamError(response.status, identifier);
-  const extracted = extractUpstreamMessage(parsedBody ?? text);
-  let message =
-    extracted.length > 0
-      ? extracted
-      : text.trim() || `Provider returned HTTP ${response.status}.`;
+  const upstreamText = upstreamMessageAsIs(parsedBody ?? text, "");
+  let message = upstreamText.message || `Provider returned HTTP ${response.status}.`;
   // A bare "Provider returned HTTP <5xx>" tells the operator nothing actionable;
   // platform-unavailable fallbacks get the same human sign-off every other
-  // gateway error carries. The raw upstream body stays in `details.raw` for
-  // diagnostics either way.
+  // gateway error carries — but only when the upstream supplied no text of its
+  // own. The raw upstream body stays in `details.raw` for diagnostics either way.
   if (
     classification.code === "platform_unavailable" &&
+    !upstreamText.hadUpstreamText &&
     message === `Provider returned HTTP ${response.status}.`
   ) {
     message = `The provider's service is temporarily unavailable (HTTP ${response.status}) (request {requestId}). Your request did not go through — wait a moment and try again. Hold tight ☁️`;
@@ -949,6 +989,7 @@ export async function mapUpstreamHttpError(response: Response, providerId: strin
     ...(reportedProviderCode ? { providerCode: reportedProviderCode } : {}),
     ...(requestId ? { upstreamRequestId: requestId } : {}),
     raw: text.slice(0, MAX_UPSTREAM_ERROR_BYTES),
+    ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
     ...(retryAfterMs === null || retryAfterMs === undefined ? {} : { retryAfterMs }),
     ...(queuedWaitMs !== undefined
       ? { reason: "upstream-queued", cooldownMs: queuedWaitMs }
@@ -971,6 +1012,57 @@ export function extractHtmlTitle(html: string): string {
   return html.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 160);
 }
 
+/** The public bound on an upstream message surface. */
+export const MAX_UPSTREAM_MESSAGE_LENGTH = 500;
+
+/**
+ * Extracts the upstream's own text from an error body, "as-is".
+ *
+ * The upstream error passthrough contract: when a failure is unknown or
+ * unparseable, the client should see whatever the upstream actually said,
+ * not a generalized 502 sentence. Structured JSON envelopes already flow
+ * through `extractUpstreamMessage`; this helper extends the same idea to the
+ * shapes that used to lose the text entirely — HTML error pages (their
+ * `<title>` is often the only readable thing) and plain-text bodies.
+ *
+ * The returned message is bounded to 500 chars (D44) and newline-collapsed,
+ * matching `sanitizePublicDetail` per-string bound; `details.raw` keeps the
+ * full 4000. `hadUpstreamText` distinguishes "the upstream said something"
+ * from "we synthesized a fallback", so callers can keep their human sign-off
+ * only when there is genuinely no upstream text.
+ */
+export function upstreamMessageAsIs(
+  body: unknown,
+  fallback: string,
+): { message: string; hadUpstreamText: boolean } {
+  const raw = typeof body === "string" ? body : "";
+  const looksLikeHtml = raw.includes("<") && raw.includes(">");
+  // HTML error pages first: the structured extractor passes a string through
+  // verbatim, which would surface raw markup instead of the readable `<title>`
+  // (or a tag-stripped excerpt when the page has no title).
+  if (looksLikeHtml) {
+    const title = extractHtmlTitle(raw);
+    if (title.length > 0) {
+      return {
+        message: title.replace(/[\r\n]+/g, " ").trim().slice(0, MAX_UPSTREAM_MESSAGE_LENGTH),
+        hadUpstreamText: true,
+      };
+    }
+  }
+  const structured = extractUpstreamMessageText(body);
+  if (structured.length > 0) {
+    return { message: structured.slice(0, MAX_UPSTREAM_MESSAGE_LENGTH), hadUpstreamText: true };
+  }
+  const text = raw.trim();
+  if (text.length > 0) {
+    return {
+      message: text.replace(/[\r\n]+/g, " ").trim().slice(0, MAX_UPSTREAM_MESSAGE_LENGTH),
+      hadUpstreamText: true,
+    };
+  }
+  return { message: fallback, hadUpstreamText: false };
+}
+
 /** Throws a typed transport error when an upstream returns an HTML error page. */
 export async function throwIfHtmlResponse(response: Response): Promise<void> {
   const contentType = response.headers.get("content-type") ?? "";

package/src/transport/guards/body-policy.ts

@@ -58,8 +58,14 @@ export function isProxyDispatchRoute(path: string | undefined): path is string {
   return path !== undefined && isJsonProxyRoute(path);
 }
 
+/**
+ * The same canonical JSON-route membership as `isProxyDispatchRoute`, kept as
+ * a non-narrowing alias for callers that already hold a string path. One
+ * predicate, two spellings, so a route-table change cannot diverge between
+ * the body-read policy and the canonical-parse gate.
+ */
 export function isJsonProxyRoutePath(path: string): boolean {
-  return isJsonProxyRoute(path);
+  return isProxyDispatchRoute(path);
 }
 
 interface IngressPolicyOptions {

package/src/transport/guards/error-lifecycle.ts

@@ -77,8 +77,20 @@ export function createErrorNormalizationMiddleware(deps: {
     .error(({ request, error, set }) => {
       const state = deps.stateStore.get(request as Request);
       const gateway = error instanceof GatewayError ? error : undefined;
+      // Elysia's built-in errors (NotFound, ValidationError, ParseError,
+      // InternalServerError) always carry a numeric `status` **and** a code.
+      // A raw runtime error can carry a `.code` on its own — Bun's fetch
+      // surfaces `TypeError` with `code: "ECONNRESET"` when an upstream socket
+      // dies mid-response — so a `code` alone is not evidence of an Elysia
+      // built-in. Requiring the numeric status keeps that raw error from
+      // leaking into the public envelope as a fake code/400; the dispatch loop
+      // already normalizes socket drops to `transport_unavailable`/502 before
+      // they reach here.
       const builtin =
-        !gateway && typeof error === "object" && error !== null
+        !gateway &&
+        typeof error === "object" &&
+        error !== null &&
+        typeof (error as ElysiaBuiltinError).status === "number"
           ? (error as ElysiaBuiltinError)
           : undefined;
       const builtinStatus = typeof builtin?.status === "number" ? builtin.status : undefined;

package/src/transport/guards/request-context.ts

@@ -12,7 +12,7 @@ import { resolveClientIdentity } from "../../security/ip-boundary";
 import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
 import { pushStructuredConsoleLog } from "../../observability/log-ring";
 import { log } from "../../observability/logger";
-import { isJsonProxyRoutePath, isProxyDispatchRoute } from "./body-policy";
+import { isProxyDispatchRoute } from "./body-policy";
 import { isOpaqueBodyRoute } from "../contracts";
 import { peerAddressUnavailableError } from "./guard-errors";
 
@@ -24,6 +24,24 @@ interface RequestApp {
   ): RequestApp;
 }
 
+/**
+ * Whether this request falls outside the canonical JSON-proxy pipeline the
+ * canonical-parse and route-preparation stages serve.
+ *
+ * Shared gate, applied in the exact order both middlewares historically
+ * checked: non-`/v1/` paths, GET/HEAD (which carry no body to parse), then
+ * the JSON route table with opaque-body routes excluded — `/v1/completions`
+ * needs no separate arm because it is already in the JSON routes table, and
+ * native routes (compact, System One, token count) read a body but are never
+ * parsed into a canonical request, their bodies being opaque by contract.
+ */
+function skipNonCanonicalProxyRequest(request: Request): boolean {
+  const path = fastPathname(request.url);
+  if (!path.startsWith("/v1/")) return true;
+  if (request.method === "GET" || request.method === "HEAD") return true;
+  return !isProxyDispatchRoute(path) || isOpaqueBodyRoute(path);
+}
+
 interface RequestContextDeps {
   readonly stateStore: ProxyRequestStateStore;
   readonly clock?: () => number;
@@ -141,15 +159,9 @@ export function createCanonicalRequestMiddleware(deps: {
 }): Elysia {
   return new Elysia()
     .beforeHandle(async ({ request }) => {
-      const path = fastPathname(request.url);
-      if (!path.startsWith("/v1/")) return;
-      if (request.method === "GET" || request.method === "HEAD") return;
-      // `/v1/completions` needs no separate arm: it is already in
-      // the JSON routes table, so the body-policy predicate covers it.
-      // Native routes (compact, System One) read a body but are never parsed
-      // into a canonical request — their bodies are opaque by contract.
-      if (!isJsonProxyRoutePath(path) || isOpaqueBodyRoute(path)) return;
       // Model discovery and other GET/multimodal routes must not go through canonical parsing.
+      if (skipNonCanonicalProxyRequest(request)) return;
+      const path = fastPathname(request.url);
       const state = deps.stateStore.require(request);
       // Single-read invariant: the ingress policy middleware already decoded the
       // body once into `state.ingressBody`. Never re-read `request.body` here —
@@ -216,11 +228,7 @@ export function createProxyRoutePreparationMiddleware(deps: {
 }): Elysia {
   return new Elysia()
     .beforeHandle(async ({ request }) => {
-      const path = fastPathname(request.url);
-      if (!path.startsWith("/v1/")) return;
-      if (request.method === "GET" || request.method === "HEAD") return;
-      const isJsonRoute = isJsonProxyRoutePath(path);
-      if (!isJsonRoute || isOpaqueBodyRoute(path)) return;
+      if (skipNonCanonicalProxyRequest(request)) return;
       const state = deps.stateStore.require(request);
       if (!state.authorization || !state.canonicalRequest)
         throw new GatewayError("route_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");