Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* ComposedHandler — composes a ProviderTransport + ModelAdapter to implement ModelHandler.
*
* This is the universal handler that replaces all 11 monolithic handlers.
* The Provider owns transport (auth, endpoint, headers, rate limiting).
* The Adapter owns transforms (messages, tools, payload, text post-processing).
*
* Flow:
* 1. transformOpenAIToClaude(payload) — normalize incoming request
* 1a. hook request stage A — system / message / tool-set actions
* 2. adapter.convertMessages(claudeRequest) — Claude → target format
* 3. adapter.convertTools(claudeRequest) — tool schema conversion
* 3a. hook request stage B — tool descriptions, both representations
* 3b. raw providerRequest hooks — unsafe tier, on committed clones
* 4. adapter.buildPayload(...) — assemble full request body
* 5. adapter.prepareRequest(payload, original) — tool name truncation, etc.
* 6. fetch via provider (with optional queue) — HTTP request
* 7. stream parser by provider.streamFormat — response → Claude SSE
*
* Steps 3a and 3b must stay ahead of step 4: buildPayload does not reliably
* alias `messages`/`tools`, so anything that runs after it is silently
* discarded on the Codex/Responses path. Stage A runs BEFORE conversion so a
* system note reaches chat-completions routes, whose payload is built from the
* converted `messages` alone; stage B runs AFTER `convertTools` so
* `summarizeTools` can never cut a description append. The hook stages run only
* when `withHooks` (hooks/response-seam.ts) put the request hooks on the context.
*/
import type { Context } from "hono";
import {
type BaseAPIFormat,
DefaultAPIFormat,
type EffortLevel,
} from "../adapters/base-api-format.js";
import { MiniMaxModelDialect } from "../adapters/minimax-model-dialect.js";
import type { AuthBinding, ProviderTransport, StreamFormat } from "../providers/transport/types.js";
import type { ModelHandler } from "./types.js";
// Alias for readability within this file
type BaseModelAdapter = BaseAPIFormat;
import { lookupModelAcceptsImages, lookupModelForProvider } from "../adapters/model-catalog.js";
import type { QuotaAdapter } from "../auth/quota/adapter.js";
import { resolveQuotaAdapter } from "../auth/quota/registry.js";
import { PLAN_POLL_INTERVAL_MS } from "../auth/quota/types.js";
import { accountKeyFromBinding } from "../code-mode/ids.js";
import { type CodeModeSetting, DEFAULT_CODE_MODE_SETTING } from "../code-mode/policy.js";
import { createCodeModeTurnHooks } from "../code-mode/relay.js";
import {
type CodeModePayloadContext,
type PreparedCodeMode,
isLiteRejection,
prepareCodeModeRequest,
rebuildAsClassic,
withoutLiteHeader,
} from "../code-mode/request.js";
import { resumeFromToolResults } from "../code-mode/resume.js";
import { loadQuickJSModule } from "../code-mode/sandbox/quickjs-loader.js";
import { getCodeModeStores, peekCodeModeStores } from "../code-mode/stores.js";
import { conversationMessages } from "../code-mode/types.js";
import { getHookEngine } from "../hooks/index.js";
import { type RawStreamTap, statsNames } from "../hooks/raw.js";
import type { UpstreamFacts } from "../hooks/registry.js";
import { type HookRequestScope, isNativeRoute, requestHooksOf } from "../hooks/request-stage.js";
import {
getLogLevel,
log,
logRecovery,
logStderr,
logStructured,
truncateContent,
} from "../logger.js";
import { deepMergeParams } from "../model-params.js";
import type { ResolvedConnection } from "../providers/connection-resolver.js";
import type { WireHeader } from "../providers/connection-wire.js";
import { describeSiblingKeys, getProviderByName } from "../providers/provider-definitions.js";
import { isTerminal429 } from "../providers/transport/openai.js";
import { wireMarkerContext } from "../providers/wire-markers.js";
import {
type WireChoices,
type WireMode,
type WireSpeed,
mergeWireHeaders,
recoverBorrowedWireFields,
shapeRequestFromWire,
wireChoicesFromClaudeRequest,
} from "../providers/wire-request.js";
import { recoveryClock } from "../recovery/clock.js";
import {
type RecoveryOutcome,
episodeCount,
noteTargetReachable,
uiLeaseValid,
} from "../recovery/coordinator.js";
import { resolveRecoveryEnabled, resolveTier1DeadlineMs } from "../recovery/settings.js";
import { redactForClient } from "../redact.js";
import {
type OpenAIImageBlock,
type VisionProxyAuthHeaders,
describeImages,
} from "../services/vision-proxy.js";
import { type SessionEventRegistry, extractSessionId } from "../session-events/index.js";
import { applyProInjection, isUltracodeMainTurn } from "../session-events/pro-injection.js";
import type { StatsEvent } from "../stats-otlp.js";
import { recordStats } from "../stats.js";
import { classifyError, reportError } from "../telemetry.js";
import { transformOpenAIToClaude } from "../transform.js";
import {
buildSurfacedErrorMessage,
ensureAnthropicErrorFormat,
extractProviderMessage,
isTerminalError,
wrapAnthropicError,
} from "./shared/anthropic-error.js";
import {
authVerdictHeaders,
classifyAuthFailure,
isCredentialRejection,
respondAuthFailure,
} from "./shared/auth-failure.js";
import {
type HopAttempt,
abortedResponse,
addSigningSecrets,
callAbortError,
callAbortSignal,
callAborted,
credentialValuesFromRequest,
raceCallAbort,
recordHopEntry,
sleepUnlessAborted,
withCallSignal,
} from "./shared/call-context.js";
import { sseResponseToJson } from "./shared/collect-sse-message.js";
import type { ConnectionErrorKind } from "./shared/connection-error.js";
import {
buildConnectionErrorMessage,
buildRecoveryHoldMessage,
classifyConnectionError,
} from "./shared/connection-error.js";
import { sniffDevinStreamHead } from "./shared/devin-stream-head-sniffer.js";
import { hasActionableLink, hasModelUnsupportedWording } from "./shared/model-unsupported.js";
import { filterIdentity } from "./shared/openai-compat.js";
import { hasPlanLimitWording, isQuotaExhaustionError } from "./shared/quota-exhaustion.js";
import { connectionFaultHeaders, recoveryHoldHeaders } from "./shared/recovery-marker.js";
import {
CREDENTIAL_DECIDED_PROVIDERS,
type RequestBilling,
isSubscriptionProvider,
} from "./shared/remote-provider-types.js";
import {
CONTEXT_OVERFLOW_PHRASE,
isContextOverflowError,
isRequestShapeError,
} from "./shared/request-shape.js";
import {
type LegAuthBinding,
createLegIssuer,
isSameCredentialSilo,
} from "./shared/responses-leg-issuer.js";
import { sniffResponsesStreamHead } from "./shared/stream-head-sniffer.js";
import { createAnthropicPassthroughStream } from "./shared/stream-parsers/anthropic-sse.js";
import { createDevinConnectStream } from "./shared/stream-parsers/devin-connect.js";
import { createGeminiSseStream } from "./shared/stream-parsers/gemini-sse.js";
import { createOllamaJsonlStream } from "./shared/stream-parsers/ollama-jsonl.js";
import {
type CodeModeTurnHooks,
type ResponsesRetryOptions,
createResponsesStreamHandler,
createSyntheticToolUseReply,
resolveStallPolicy,
} from "./shared/stream-parsers/openai-responses-sse.js";
import { createStreamingResponseHandler } from "./shared/stream-parsers/openai-sse.js";
import { notifyOnDownstreamCancel } from "./shared/stream-parsers/upstream-cancel.js";
import { TokenTracker, type UsageCacheDetail } from "./shared/token-tracker.js";
import {
type ConnectionErrorInfo,
MIN_ATTEMPT_SLOT_MS,
deadlineClamp,
inboundStartedAtPerf,
mergeSignalIntoInit,
refreshDeadlineAt,
tier1DeadlineAt,
withConnectionRetry,
} from "./shared/transient-retry.js";
import { captureUpstreamError } from "./shared/upstream-error-capture.js";
/**
* Backoff schedule for a retryable error that arrived inside an HTTP 200 stream.
* Progressive rather than tight: the Codex capacity outage that motivated this
* lasted minutes, so the useful attempts are the late ones.
*/
const STREAM_RETRY_DELAYS_MS = [3_000, 15_000, 30_000];
/**
* A retry leg's binding: the request's `AuthBinding` plus the account it names
* (`accountKeyFromBinding`), which the leg issuer compares between legs.
*/
type LegBinding = AuthBinding & LegAuthBinding;
/** What `handle()` builds for a Responses turn and `handleStream` hands the parser. */
interface ResponsesTurnWiring {
retry: ResponsesRetryOptions;
onTurnSummary: (s: { legs: number; legRetries: number }) => void;
/** Code mode for this turn (`openai-codex`, decided at 5d). */
codeMode?: CodeModeTurnHooks;
}
/**
* One request's running account of what network recovery cost it. Mutable, and
* mutated only by `recoverConnection`.
*
* Every field is REQUEST-scoped even though the episode behind them is not.
* See `ComposedHandler.newRecoveryTally` for why that distinction is the whole
* point, and `transient-retry.ts`'s `ConnectionRetryTally` for where the
* request-scoped figures come from.
*/
interface RecoveryTally {
/** Re-issues this request made. Not counting the failure that started it. */
retries: number;
/** Ms of this request's own latency spent inside the ladder. */
recoveryMs: number;
/** Set once an episode exists. Its presence is what makes the rest real. */
episodeId?: string;
/** Which tier-2 re-entry this request is. 0 = the original. */
clientRetry: number;
/** How the episode ended for this request, once it has. */
outcome?: RecoveryOutcome;
}
function extractAuthHeaders(c: Context): VisionProxyAuthHeaders {
const headers = c.req.header();
const auth: VisionProxyAuthHeaders = {};
if (headers["x-api-key"]) auth["x-api-key"] = headers["x-api-key"];
return auth;
}
export interface ComposedHandlerOptions {
/** Override format selection — use this specific APIFormat instance */
adapter?: BaseAPIFormat;
/** Tool schemas for validation (enables buffered tool call validation) */
toolSchemas?: any[];
/** Token tracking strategy */
tokenStrategy?: "standard" | "accumulate-both" | "delta-aware" | "actual-cost" | "local";
/** Summarize tool descriptions (for models with small context) */
summarizeTools?: boolean;
/** Whether the Gemini SSE stream wraps chunks in {response: {...}} (CodeAssist) */
unwrapGeminiResponse?: boolean;
/** Whether the current session is interactive (gates consent prompt). */
isInteractive?: boolean;
/**
* Treat this route as FOREIGN for hooks (`RouteInfo.native` false) regardless
* of the model's name, so foreign-scoped built-in hooks stay armed.
*
* The default rule reads `claude-*` as "native Claude, already follows these
* conventions" — a naming rule that holds for models reached through
* Anthropic's own harness. A third party re-serving `claude-sonnet-5-medium`
* over a reverse-engineered endpoint has no such measurement behind it, so a
* provider whose uids merely LOOK like Claude's would silently disarm the
* supervisor for exactly the models most likely to need it. Set by the
* provider profile; every other provider leaves it undefined and is untouched.
*/
forceForeignModel?: boolean;
/** How this handler was invoked (for stats). */
invocationMode?: "profile" | "explicit-model" | "auto-route" | "env-var" | "model-map";
/**
* `--effort <level>`: pin the reasoning effort verbatim, skipping the
* per-model catalog clamp. Installed on this handler's dialect(s) at
* construction; undefined leaves the clamped mapping untouched.
*/
effortOverride?: EffortLevel;
/**
* `--model-params k=v[,...]`: extra request params deep-merged into the
* outbound payload at step 5a — AFTER every adapter has shaped it, so these
* win over adapter defaults AND over the step 5a-pre preset injection.
*/
modelParams?: Record<string, unknown>;
/**
* `--pro-on-ultracode`: apply this model's catalog provider-preset while the
* Claude Code session is in ultracode. Opt-in; when falsy the session-event
* layer is never consulted and does no filesystem work.
*/
proOnUltracode?: boolean;
/**
* Code mode for `openai-codex` (`auto` | `on` | `off`), resolved by the CLI
* from `--code-mode` > `CLAUDISH_CODE_MODE` > `codeMode` config. Absent ⇒
* `DEFAULT_CODE_MODE_SETTING` (`auto`). Read only on the `openai-codex` request path.
*/
codeMode?: CodeModeSetting;
/**
* Test seam for the session-event registry. Defaults to the process-wide
* singleton. Only tests should pass this.
*/
sessionEventRegistry?: SessionEventRegistry;
/**
* Test seam for the model-catalog cache path used by preset resolution.
* Defaults to ~/.claudish/cloud-models-catalog-v3.json. Only tests should pass this.
*/
catalogCachePath?: string;
/**
* The catalog connection this handler calls, with its `wire` (catalog 3.7.0).
* When its wire is known, step 5w shapes the output limit, reasoning, mode and
* speed from it alone, after every adapter and dialect has run.
*/
connection?: ResolvedConnection;
/**
* A model-family dialect the PROFILE chose for a provider that serves one
* family (the Grok subscription). Never chosen from the model name.
*/
dialect?: BaseAPIFormat;
/** `+pro` on the model spec: request mode pro, refused where the wire does not publish it. */
wireMode?: WireMode;
/** `#<speed>` on the model spec, refused where the wire does not publish it. */
wireSpeed?: WireSpeed;
/**
* Who issues requests through this handler. `"advisor"` marks a handler built
* for `--advisor` panel and collector calls, which claudish issues itself:
* it writes no status-line token file (the main session owns it), skips the
* plan-usage scrape and poll (that reading belongs on the main status line
* too), runs no hooks (a panel call is not a harness turn), and
* tags every stats event `request_role: "advisor"`. Absent on every handler
* that serves Claude Code's own requests.
*/
requestRole?: "advisor";
}
export class ComposedHandler implements ModelHandler {
private provider: ProviderTransport;
/** The dialect resolved for this model, or the OpenAI-shaped default. */
private resolvedDialect: BaseAPIFormat;
private explicitAdapter?: BaseModelAdapter;
/** Model-specific adapter (GLM, Grok, etc.) — handles model quirks independent of provider */
private modelAdapter?: BaseModelAdapter;
private tokenTracker: TokenTracker;
/** Full routed model string (e.g. "[email protected]"). Used for provider routing and display echo. */
private targetModel: string;
/**
* Bare model name (e.g. "glm-4.7"), provider prefix stripped. Used for model identity:
* dialect selection, catalog lookup, raw-hook routing, context tracking. Never contains '@'.
* @invariant !bareModelName.includes("@")
*/
private readonly bareModelName: string;
private options: ComposedHandlerOptions;
private isInteractive: boolean;
/** Fallback metadata set by FallbackHandler before calling handle() */
private pendingFallbackMeta?: { chain: string[]; attempts: number };
/**
* When this handler last polled a provider's usage endpoint. A handler is
* cached per model and can serve overlapping requests, so this throttle is
* per-handler rather than global — two providers refresh independently.
*/
private lastPlanPollAt = 0;
constructor(
provider: ProviderTransport,
targetModel: string,
modelName: string,
port: number,
options: ComposedHandlerOptions = {}
) {
// Enforce the bare-name invariant — modelName must not contain provider routing
// syntax. This prevents #102-class bugs where a routed string leaks into dialect
// selection (e.g. "[email protected]" falsely matching GLMModelDialect via the "@glm"
// substring). Callers must strip the provider prefix before passing modelName.
if (modelName.includes("@")) {
throw new Error(
`ComposedHandler: modelName must not contain '@' (got "${modelName}"). Strip the provider routing prefix before passing modelName. If you need the full routed form, pass it as targetModel.`
);
}
this.provider = provider;
this.targetModel = targetModel;
this.bareModelName = modelName;
this.options = options;
this.explicitAdapter = options.adapter;
this.isInteractive = options.isInteractive ?? false;
// The dialect is never picked by model name. A catalog connection's `wire`
// (or a custom endpoint's declared one) decides every reasoning and limit
// field (step 5w); a profile that genuinely serves one model family names
// its dialect explicitly (`options.dialect`: the Grok subscription). The
// name-ordered dialect factory this replaced picked, for example, the GLM
// dialect for any id containing "glm", whatever host or API served it.
//
// The dialect gets the REQUEST wire format, which only this class knows:
// the Layer 1 converter decides the request shape, so its getStreamFormat()
// is the signal — NOT provider.overrideStreamFormat(), which only re-labels
// the RESPONSE for aggregators.
//
// One quirk is the MODEL's on every host and no wire field describes it:
// MiniMax rejects a temperature outside its range. It keys on the catalog's
// vendor field (data), and the MiniMax dialect's reasoning fields are then
// overwritten by the wire like any other (step 5w runs after it).
this.resolvedDialect =
options.dialect ??
(options.connection?.vendor === "minimax"
? new MiniMaxModelDialect(this.bareModelName, this.explicitAdapter?.getStreamFormat())
: new DefaultAPIFormat(this.bareModelName, this.explicitAdapter?.getStreamFormat()));
const resolvedModelAdapter = this.resolvedDialect;
if (options.connection) {
for (const adapter of [this.explicitAdapter, this.resolvedDialect]) {
adapter?.setUpstreamVendor(options.connection.vendor ?? "");
}
}
if (resolvedModelAdapter.getName() !== "DefaultAPIFormat") {
this.modelAdapter = resolvedModelAdapter;
}
// Tell every adapter which PARSER will read the response.
//
// This is the only place that knows: `resolveStreamFormat()` consults
// `provider.overrideStreamFormat()` FIRST, and no adapter can see that. The
// pairing it exists for is `{transport:"openai", streamFormat:"anthropic-sse"}`
// — an OpenAI-shaped REQUEST answered in Anthropic SSE. The request shape
// armed the 64-char tool-name encoder while the Anthropic passthrough parser
// takes no decode map, so Claude Code received a tool name it never
// advertised and its allowlist dropped the call with no error anywhere.
// `getToolNameLimit()` now returns null for any wire whose parser cannot
// decode. See `wireDecodesToolNames`.
//
// Set once, here, because it is a property of the COMPOSITION:
// `resolveStreamFormat()` never looks at the request, so this carries none
// of the per-request race that made the tool-name bindings per-request.
// `resolvedDialect`, not `modelAdapter`: an unrecognized model leaves
// `modelAdapter` unset and `getAdapter()` then returns the dialect, which is
// the instance that would do the encoding.
const responseWire = this.resolveStreamFormat() as StreamFormat;
this.resolvedDialect.setResponseWireFormat(responseWire);
this.explicitAdapter?.setResponseWireFormat(responseWire);
// `--effort`: install the pin on EVERY dialect this handler can route
// through. getAdapter() picks explicitAdapter or resolvedDialect at request
// time and modelAdapter runs in addition to it, so pinning only one leaves
// the flag working on some models and silently not on others. Safe to
// mutate: the dialect is built per handler by its profile, and
// an explicit adapter is built per handler by its profile.
if (options.effortOverride) {
for (const dialect of new Set(
[this.explicitAdapter, this.resolvedDialect, this.modelAdapter].filter(Boolean)
)) {
(dialect as BaseAPIFormat).setEffortOverride(options.effortOverride);
}
log(
`[ComposedHandler] --effort ${options.effortOverride} pinned for ${this.targetModel} (catalog clamp skipped)`
);
}
// Initialize token tracker — model adapter knows the real context window
this.tokenTracker = new TokenTracker(port, {
contextWindow: this.getModelContextWindow(),
providerName: provider.name,
modelName: this.bareModelName,
providerDisplayName: provider.displayName,
...(options.requestRole === "advisor" ? { writesTokenFile: false } : {}),
});
}
/**
* The endpoint a binding signs for, read only for its credential query
* parameters (Gemini's `?key=`). Never throws: a transport that cannot name
* its endpoint here simply contributes no query value.
*/
private signedEndpoint(binding: AuthBinding | undefined): string | undefined {
try {
return this.provider.getEndpoint(this.targetModel, binding);
} catch {
return undefined;
}
}
/**
* The route hooks are scoped by. `native` is the exact rule the plan-mode
* supervisor has always used: `claude-*` names and the `anthropic` provider,
* unless the provider profile sets `forceForeignModel`.
*/
private routeInfo(): { modelId: string; provider: string; native: boolean } {
return {
modelId: this.bareModelName,
provider: this.provider.name,
native: isNativeRoute(this.bareModelName, this.provider.name, this.options.forceForeignModel),
};
}
/**
* `middleware_names` for stats: the built-in raw hooks (the Gemini
* thought-signature hook, today) that apply to this route. User hooks never
* appear, so the OTLP `llm.middleware` attribute is unchanged for them.
*/
private rawStatsNames(): string[] {
return statsNames(getHookEngine(), this.routeInfo(), this.upstreamFacts());
}
/**
* What the catalog says about this handler's upstream, for built-ins selected
* from data rather than by model name (`BuiltinHook.selectByUpstream`). Only
* with a catalog connection: without one the hooks' name globs decide.
*/
private upstreamFacts(): UpstreamFacts | undefined {
const connection = this.options.connection;
if (!connection) return undefined;
return {
wireApi: connection.wire.status === "known" ? connection.wire.api : null,
vendor: connection.vendor ?? null,
};
}
/** Provider adapter — handles transport format (messages, tools, payload) */
private getAdapter(): BaseModelAdapter {
return this.explicitAdapter || this.resolvedDialect;
}
/** Model context window — model adapter wins over provider adapter */
private getModelContextWindow(): number {
return this.modelAdapter?.getContextWindow() ?? this.getAdapter().getContextWindow();
}
/** Model vision support — model adapter wins over provider adapter */
private getModelSupportsVision(): boolean {
// A catalog connection asks the catalog's data about the MODEL (not a
// dialect's default by name). Unknown is not "no": an image the user
// attached is sent, and the upstream's own answer is what they see.
const connection = this.options.connection;
if (connection) {
if (connection.generationId === "declared") return true;
try {
return lookupModelAcceptsImages(connection.modelId, this.options.catalogCachePath) ?? true;
} catch {
return true;
}
}
return this.modelAdapter?.supportsVision() ?? this.getAdapter().supportsVision();
}
/** Get the active adapter name for stats reporting. */
private getActiveAdapterName(): string {
// Model-specific dialect takes precedence (GLMModelDialect, GrokModelDialect, etc.)
if (this.modelAdapter) return this.modelAdapter.getName();
return this.getAdapter().getName();
}
/**
* Which host to name in a connection-failure message.
*
* A connect failure raised while MINTING A TOKEN happened against the auth
* host, not the inference endpoint — for `gk@` those are `auth.x.ai` and
* `api.x.ai`. A transport that knows better attaches `claudishEndpoint` to the
* error it rethrows; otherwise fall back to the request endpoint, and finally
* to the provider name so the sentence is never blank.
*/
private connectionEndpointFor(error: unknown, requestEndpoint?: string): string {
const attached = (error as { claudishEndpoint?: unknown })?.claudishEndpoint;
if (typeof attached === "string" && attached.length > 0) return attached;
if (requestEndpoint) return requestEndpoint;
try {
return this.provider.getEndpoint(this.targetModel);
} catch {
return this.provider.displayName;
}
}
/**
* What one REQUEST did inside the retry ladder, accumulated across every site
* in that request that could enter it.
*
* One per `handle()` call, never on `this` — a `ComposedHandler` instance is
* reused for the life of the process and serves concurrent requests, so an
* instance field here would report one request's outage on another request's
* record. The cost of getting that wrong is not a wrong number in a log: it
* is a wrong number in the only stream that can answer "how often does this
* happen", which is what the feature was measured by.
*
* ACCUMULATION IS PER-REQUEST AND LAST-EPISODE-WINS. A request can hit an
* auth-path episode and then a fetch-path episode. Attempts and waits ADD
* (they are both this request's own time, and there is exactly one record per
* request), while `episodeId` and `clientRetry` are overwritten — so the id
* that survives is the one belonging to the episode that DECIDED THE STATUS,
* which is the only reading under which a scalar correlation id is
* well-defined.
*/
private static newRecoveryTally(): RecoveryTally {
return { retries: 0, recoveryMs: 0, clientRetry: 0 };
}
/**
* The recovery half of a stats event — spread into every `recordStats` on a
* path a recovery could precede.
*
* Empty unless an episode actually happened, which is what keeps a healthy
* request's record byte-identical to what it was before this feature existed.
* `retry_attempts: 0` IS emitted when an episode existed and this request
* added no re-issue to it; that is a different fact from "no recovery", and
* only the presence of `recovery_episode_id` distinguishes them.
*/
private recoveryStats(tally: RecoveryTally | undefined): Partial<StatsEvent> {
if (!tally?.episodeId) return {};
return {
retry_attempts: tally.retries,
recovery_ms: tally.recoveryMs,
recovery_episode_id: tally.episodeId,
recovery_client_retry: tally.clientRetry,
...(tally.outcome ? { recovery_outcome: tally.outcome } : {}),
};
}
/**
* The ONE writer of this handler's stats events. Every `recordStats` call in
* this class goes through here, so a field that must be on every event (the
* request role of an advisor handler) is added in one place and cannot be
* missed by a site added later.
*/
private emitStats(event: Parameters<typeof recordStats>[0]): void {
recordStats(
this.options.requestRole ? { ...event, request_role: this.options.requestRole } : event
);
}
/**
* Fill a hop-log entry once the request is signed: the arm from the
* binding the credential half returned (`RequestAuth.arm`, never inferred
* from a resolved object's truthiness), and the billing.
*
* For a provider whose billing the signing credential decides
* (`CREDENTIAL_DECIDED_PROVIDERS`, i.e. `openai-codex`) the billing is THIS
* request's arm: `oauth` is the subscription, anything else (absent
* included) is metered. It is never `isSubscriptionProvider(name)`, whose
* probe reads a process-wide last-signed arm that a concurrent main request
* can overwrite between this request's refresh and this line. Every other
* provider's billing is its fixed category (`SUBSCRIPTION_PROVIDERS`
* membership), whatever arm signs: a flat-rate key is still flat-rate.
*/
private markHopSigned(hop: HopAttempt, binding: AuthBinding | undefined): void {
hop.arm = binding?.auth?.arm ?? null;
hop.billing = this.signedBilling(binding).subscription ? "subscription" : "metered";
}
/**
* The billing of a request signed with `binding`, by the rule above: the
* signing arm for a credential-decided provider, the fixed category for
* every other one. The ONE derivation shared by the hop label
* (`markHopSigned`) and the request's cost updates (`handleStream`), so the
* two cannot disagree.
*/
private signedBilling(binding: AuthBinding | undefined): RequestBilling {
const name = this.provider.name.toLowerCase();
return {
subscription: CREDENTIAL_DECIDED_PROVIDERS.has(name)
? binding?.auth?.arm === "oauth"
: isSubscriptionProvider(name),
};
}
/**
* The answer when an internal call's deadline passed (`call-context.ts`).
* No classification, no recovery, nothing on stderr: the caller has already
* stopped waiting and reports the timeout itself. One failure stats event,
* so the attempt is still counted. Unreachable on a main request, which
* never carries a call signal.
*/
private respondCallAborted(
startTime: number,
fallbackMeta?: { chain: string[]; attempts: number }
): Response {
log(`[${this.provider.displayName}] call stopped: its deadline passed`);
try {
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - startTime),
success: false,
http_status: 408,
error_class: "timeout",
error_code: "call_aborted",
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
});
} catch {
// Stats must never crash claudish
}
return abortedResponse();
}
/**
* The ONE response shape for "claudish could not reach the host".
*
* Every outbound call in this handler that can throw without a Response must
* classify first and come here, or rethrow unchanged. None may invent a
* status of its own — that is the rule this method exists to make cheap to
* follow, because the two statuses a hand-written site reaches for are both
* wrong:
*
* - **401** (what the auth catches returned) is read by
* `fallback-handler.ts`'s `isRetryableError` as retryable, so a network
* outage during a token refresh ADVANCES THE CHAIN — silently moving a
* subscription user onto a per-token provider, during an outage, for a
* fault that had nothing to do with their credentials.
* - **500** (what an unclassified throw becomes at `proxy-server.ts`) hides
* the actionable sentence behind a stack dump.
*
* 400 with type `connection_error` is neither: `isRetryableError` stops the
* chain, Claude Code renders it inline instead of behind "API error ·
* Retrying", and `probe-live`'s classifier keys off the TYPE (status-agnostic)
* to report "network error".
*/
private respondConnectionError(
c: Context,
error: unknown,
conn: { kind: ConnectionErrorKind; code: string },
endpoint: string,
ctx: {
startTime: number;
fallbackMeta?: { chain: string[]; attempts: number };
/**
* This request's ladder account, if it ran one. Absent means the ladder
* was skipped, which is today's immediate-400 behaviour.
*/
recovery?: RecoveryTally;
/**
* A retry this request made BEFORE the ladder — the parameter-recovery
* re-fetch and the forced-auth re-fetch both are one. OR'd with the
* ladder's own count rather than replaced by it, because both are true
* answers to "did claudish retry before reporting this".
*/
retriedBeforeLadder?: boolean;
authType?: "api-key" | "oauth" | "none";
/** Where the failure happened, for the debug log only. */
site?: string;
}
): Response {
const msg = buildConnectionErrorMessage(conn.kind, this.provider.displayName, endpoint);
log(
`[${this.provider.displayName}] ${msg} (code=${conn.code}${ctx.site ? `, site=${ctx.site}` : ""})`
);
logStderr(`Error: ${msg}`);
reportError({
error,
providerName: this.provider.name,
providerDisplayName: this.provider.displayName,
streamFormat: this.provider.streamFormat,
modelId: this.targetModel,
httpStatus: undefined,
isStreaming: false,
// DERIVED, never hand-set. This field had been a literal `false` on this
// path since before the ladder existed, so every recovered-then-failed
// outage was reported as a first-and-only attempt. It is true exactly
// when this request re-issued the operation at least once, from either
// source.
retryAttempted: (ctx.retriedBeforeLadder ?? false) || (ctx.recovery?.retries ?? 0) > 0,
isInteractive: this.isInteractive,
...(ctx.authType ? { authType: ctx.authType } : {}),
});
try {
const { error_class, error_code } = classifyError(error, undefined);
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - ctx.startTime),
success: false,
http_status: 0,
error_class,
error_code,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: ctx.fallbackMeta !== undefined,
fallback_chain: ctx.fallbackMeta?.chain,
fallback_attempts: ctx.fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(ctx.recovery),
});
} catch {
// Stats must never crash claudish
}
// The chain-safety marker, on THIS arm as well as on the 503.
//
// It is the third argument rather than a `c.header()` call, because `c` is
// SHARED across every candidate in a fallback chain and a sticky header set
// here would ride out on `formatCombinedError`'s response — the same
// invariant `respondRecoveryHold` obeys by building a standalone Response.
// Hono's `newResponse` applies this bag to the returned Response only; it
// never touches the context's own header store.
//
// Without it, chain-safety existed exactly where a banner did. A headless
// exhaustion answered an unmarked 400, `isRetryableError` fell through to
// its status-agnostic quota-wording match, and a host whose NAME contained
// "quota" advanced the chain onto a metered provider mid-outage. See
// `recovery-marker.ts`.
return c.json(
wrapAnthropicError(400, msg, "connection_error"),
400 as any,
connectionFaultHeaders()
);
}
/**
* The OTHER response shape: "claudish could not reach the host YET, and a
* surface is painting that fact, so the retry is handed back to the client."
*
* This is tier 2. The episode stays open for its grace window, Claude Code's
* own backoff elapses, it re-POSTs, and `joinEpisode` finds the open episode —
* same `episodeId`, same ladder position, `clientRetries` incremented. One
* banner, one attempt counter, one episode across both tiers.
*
* ── WHY `new Response` AND NEVER `c.header()` + `c.json()` ──────────────────
*
* `fallback-handler.ts` carries an explicit invariant: each candidate handler
* must NOT mutate the Hono `Context` (e.g. `c.header()`) before returning a
* non-ok Response. `c` is SHARED across every candidate in a chain, so a
* sticky `x-should-retry` set here would ride out on
* `formatCombinedError`'s `c.json(..., exhaustedChainStatus(errors))` — a
* terminal 400 telling Claude Code to retry it, which reintroduces exactly
* the buried-reason failure the whole 400-not-503 doctrine exists to prevent.
* A standalone `Response` cannot do that. The file's one `c.header()` call
* (`X-Dropped-Params`) is safe only because it sits after the `!response.ok`
* early returns; this arm has no such luck and must not acquire any.
*
* ── WHY 503 AND NOT 529 ─────────────────────────────────────────────────────
*
* `exhaustedChainStatus`'s transient set already contains 503 and does not
* contain 529, and `isRetryableError`'s remap-recovery check already scopes
* to 429/503. 529 would add a status this codebase has never carried and
* re-open every `status ===` under `handlers/`. 503 is the status the house
* already owns for "transient after our own retries, do not switch the user's
* provider".
*
* No `reportError` and no `logStderr("Error: …")` on this arm, deliberately.
* This is a handoff, not a verdict: with the retry watchdog enabled the
* client may re-ask hundreds of times during one outage, and a terminal-shaped
* error line per handoff would drown the pane's own account of the same
* fault. The 400 arm — lease gone, or the user pressed give-up — is where the
* failure is finally reported, once.
*/
private respondRecoveryHold(
error: unknown,
conn: { kind: ConnectionErrorKind; code: string },
endpoint: string,
ctx: {
/** EPISODE-scoped, and deliberately so: these two are what the SENTENCE
* quotes, and the sentence is about the outage rather than about this
* socket. The request-scoped figures the stats record are in
* `recovery`. */
startTime: number;
attempts: number;
recoveryMs: number;
fallbackMeta?: { chain: string[]; attempts: number };
recovery?: RecoveryTally;
}
): Response {
const reason = buildConnectionErrorMessage(conn.kind, this.provider.displayName, endpoint);
const msg = buildRecoveryHoldMessage(reason, ctx.attempts, ctx.recoveryMs);
try {
const { error_class, error_code } = classifyError(error, undefined);
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - ctx.startTime),
success: false,
http_status: 503,
error_class,
error_code,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: ctx.fallbackMeta !== undefined,
fallback_chain: ctx.fallbackMeta?.chain,
fallback_attempts: ctx.fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(ctx.recovery),
});
} catch {
// Stats must never crash claudish
}
return new Response(JSON.stringify(wrapAnthropicError(503, msg, "overloaded_error")), {
status: 503,
headers: recoveryHoldHeaders(),
});
}
/**
* The inbound client's abort signal, or one that never fires.
*
* It fires sub-millisecond when Claude Code goes away — measured at
* 0.49–0.86 ms across twelve trials, in the HELD shape (handler awaiting, no
* headers sent) as well as the streaming one. Nothing in this codebase read
* it before recovery existed, which is also why a fallback matters: a caller
* that builds a Context without a real `Request` must get a signal that never
* aborts rather than a crash.
*/
private clientSignal(c: Context): AbortSignal {
try {
const signal = c.req?.raw?.signal;
if (signal) return signal;
} catch {
// A synthesised Context. Fall through.
}
return new AbortController().signal;
}
/**
* Should the retry ladder be skipped entirely, answering today's immediate
* 400? Returns the REASON, or null to proceed.
*
* FOUR GATES, AND DELIBERATELY NO FIFTH. Each is a fact available at this
* instant — a request header, configuration, the user's explicit give-up,
* and the clock.
*
* There is NO special case for a refused loopback address, and that absence
* is a decision rather than an omission. An earlier design skipped the ladder
* for `refused` + loopback when the recovery UI was off, on the reasoning
* that a stopped local server will not start itself. It was cut for two
* reasons. The narrow one: the predicate was a regression generator — every
* revision of it either fired universally (skipping recovery everywhere) or
* fired never, and both times the defect was invisible because the SAME rule
* decided the tests. The broad one, which is the real one: this is not a
* feature for Ollama. It is the general answer to "claudish could not reach
* the host", and a general rule that carves out one address family stops
* being general. A user who restarts their server mid-ladder gets their turn
* back, exactly as a user whose VPN reconnects does.
*/
private shouldSkipTier1(c: Context, deadlineAt: number): string | null {
// Probes MUST fail fast. Every probe POSTs through this handler, so
// without this gate `--probe` and the config TUI's Test All would each
// hold an unreachable link open for the full deadline and then misreport
// it as a timeout — breaking the two tools that diagnose this exact fault.
//
// `advisor` is the panel gateway's own value. An advisor call has a 60 s
// budget a multi-minute hold cannot fit, and a tier-2 503 means nothing to
// an internal caller; it is named for itself so the skip line in the log
// says which kind of request skipped the ladder.
const noRecovery = c.req.header("x-claudish-no-recovery");
if (noRecovery === "1") return "probe";
if (noRecovery === "advisor") return "advisor";
// The CI / scripted-`-p` master switch. Off restores today's behaviour
// everywhere, byte for byte.
if (!resolveRecoveryEnabled()) return "recovery-disabled";
// Attempt 1 already spent the budget. A guard, not a hope.
if (recoveryClock().now() + MIN_ATTEMPT_SLOT_MS > deadlineAt) return "no-budget";
return null;
}
/**
* Answer a failure at a credential site that is NOT a connection fault
* (`auth-failure.ts`): a terminal one (a dead or unsubscribed login, as the
* producer marked it) as 400 with the terminal verdict, so the chain stops and
* the message lands inline; a transient one — and any unclassifiable one of a
* SUBSCRIPTION — as 503/429 with the transient verdict, retried on the same
* hop, never 401.
*
* An unclassifiable failure of a METERED provider gets 401 only where
* `meteredUnknown` is `"401"` (the refreshAuth and forceRefreshAuth catches,
* which always answered it, so the chain may try another credential).
* Everywhere else it returns null and the caller rethrows it unchanged:
* classify first or rethrow — never invent a status.
*/
private answerAuthFailure(
c: Context,
err: unknown,
meteredUnknown: "401" | "rethrow"
): Response | null {
const failure = classifyAuthFailure(err);
const isSubscription = isSubscriptionProvider(this.provider.name);
if (failure.kind === "connection") return null;
if (failure.kind === "unknown" && !isSubscription && meteredUnknown === "rethrow") return null;
return respondAuthFailure(c, failure, {
isSubscription,
providerDisplayName: this.provider.displayName,
});
}
/**
* {@link recoverConnection} at a credential site. A failure the ladder could
* not classify as a connection fault (its `"threw"` outcome, e.g. a token
* refresh that timed out and was then answered "login expired") is answered by
* {@link answerAuthFailure} instead of escaping `handle()` — where
* FallbackHandler would record status 0 and advance the chain.
*/
private async recoverAtAuthSite<T>(
c: Context,
first: unknown,
conn: ConnectionErrorInfo,
endpoint: string,
op: (signal: AbortSignal) => Promise<T>,
ctx: Parameters<ComposedHandler["recoverConnection"]>[5],
meteredUnknown: "401" | "rethrow"
): Promise<{ kind: "value"; value: T } | { kind: "respond"; response: Response }> {
try {
return await this.recoverConnection<T>(c, first, conn, endpoint, op, ctx);
} catch (thrown) {
const response = this.answerAuthFailure(c, thrown, meteredUnknown);
if (response) return { kind: "respond", response };
throw thrown;
}
}
/**
* Run tier-1 recovery for one classified connection failure.
*
* Callers reach this from inside their own `catch`, never before, and only
* after `classifyConnectionError` returned non-null. `value` means the
* operation eventually succeeded and the caller carries on with it;
* `respond` means the caller returns that Response immediately. An
* unclassifiable failure on a LATER attempt is rethrown from here, exactly as
* an unclassifiable first failure is rethrown by the caller.
*/
private async recoverConnection<T>(
c: Context,
first: unknown,
conn: ConnectionErrorInfo,
endpoint: string,
op: (signal: AbortSignal) => Promise<T>,
ctx: {
startTime: number;
deadlineAt: number;
fallbackMeta?: { chain: string[]; attempts: number };
authType?: "api-key" | "oauth" | "none";
site: string;
/** True at the two sites that are THEMSELVES a retry. See the field of
* the same name on `respondConnectionError`. */
retriedBeforeLadder?: boolean;
/**
* THIS REQUEST'S tally, created once per `handle()` and threaded through
* every site that can enter the ladder. Mutated here and nowhere else.
*/
recovery: RecoveryTally;
}
): Promise<{ kind: "value"; value: T } | { kind: "respond"; response: Response }> {
const skip = this.shouldSkipTier1(c, ctx.deadlineAt);
if (skip) {
log(
`[Recovery] skipped (${skip}) — ${this.provider.displayName} at ${endpoint}, site=${ctx.site}`
);
return {
kind: "respond",
response: this.respondConnectionError(c, first, conn, endpoint, ctx),
};
}
// Lift Bun's per-request idle timeout so the hold is bounded by OUR
// deadline rather than by the server's. `c.env` IS the Bun `Server` and
// `c.env.timeout` is a real two-arity function — measured: a request given
// `0` survived SIX times its `idleTimeout` where the un-disarmed control
// died at 1.6×. Called HERE, inside the catch, and never on a healthy
// request.
try {
(c.env as { timeout?: (req: Request, seconds: number) => void } | undefined)?.timeout?.(
c.req.raw,
0
);
} catch {
// An older Bun, or a synthesised Context. The deadline still holds; only
// the server's own ceiling might cut it short, and that is today's
// behaviour rather than a regression.
}
const result = await withConnectionRetry(op, first, {
providerName: this.provider.name,
providerDisplayName: this.provider.displayName,
resolveEndpoint: (err) => this.connectionEndpointFor(err, endpoint),
deadlineAt: ctx.deadlineAt,
signal: this.clientSignal(c),
});
// Fold this ladder run into the request's account BEFORE any arm below can
// return. A request that recovers at the auth site and then exhausts at the
// fetch site must report BOTH sets of attempts and BOTH waits — they were
// all its own latency — under the id of the episode that decided its
// status, which is the later one. Both halves of that are this statement.
ctx.recovery.retries += result.requestRetries;
ctx.recovery.recoveryMs += result.requestRecoveryMs;
ctx.recovery.episodeId = result.episodeId;
ctx.recovery.clientRetry = result.clientRetry;
switch (result.kind) {
case "ok":
ctx.recovery.outcome = "recovered";
return { kind: "value", value: result.value };
case "threw":
// Classification runs on every attempt. Something that is not a
// connection failure must keep its own route out of here.
throw result.error;
case "client_gone":
ctx.recovery.outcome = "client_gone";
this.recordClientGone(
ctx.startTime,
ctx.fallbackMeta,
result.episodeId,
result.attempts,
ctx.recovery
);
// Nobody reads this. It exists so Hono has an object to return for a
// socket that is already gone.
return { kind: "respond", response: new Response(null, { status: 499 }) };
default: {
// THE LEASE IS READ HERE AND NOWHERE ELSE, at the instant the status is
// chosen — never cached off the result object, which would be stale by
// the time it was destructured. That staleness is exactly how the
// superseded `uiAttached` latch could report a banner that had been
// killed, closed or frozen minutes earlier, and then answer a retryable
// status with the reason visible nowhere: the one outcome strictly
// worse than the terminal 400 this feature exists to remove.
//
// THE RULE THE TWO ARMS ENCODE. A retryable status is permissible
// exactly when claudish still has a surface on which the reason is
// legible. Absent such a surface, the reason must ride the status,
// which means 400.
const leased = uiLeaseValid(result.episodeId);
// `gave_up` is NOT eligible, and the guard is `result.kind` rather than
// the lease. `[q] give up` is the user saying stop; a lease may well
// still be valid at that instant (the pane that took the keystroke is
// by definition alive), so a lease-only test would answer a retryable
// 503 and Claude Code would immediately re-ask — turning the give-up
// key into a no-op with a banner still on screen.
ctx.recovery.outcome = result.kind === "exhausted" ? "handoff" : "gave_up";
if (result.kind === "exhausted" && leased) {
logRecovery(
`[Recovery] ${this.provider.displayName} exhausted after ${result.attempts} attempts ` +
`in ${result.recoveryMs}ms (episode ${result.episodeId}, ui_lease=true) — ` +
"handing the retry back to the client (503, tier 2)"
);
return {
kind: "respond",
response: this.respondRecoveryHold(result.error, result.conn, result.endpoint, {
startTime: ctx.startTime,
attempts: result.attempts,
recoveryMs: result.recoveryMs,
fallbackMeta: ctx.fallbackMeta,
recovery: ctx.recovery,
}),
};
}
logRecovery(
`[Recovery] ${this.provider.displayName} exhausted after ${result.attempts} attempts ` +
`in ${result.recoveryMs}ms (episode ${result.episodeId}, outcome ${result.kind}, ` +
`ui_lease=${leased}) — answering connection_error`
);
return {
kind: "respond",
response: this.respondConnectionError(c, result.error, result.conn, result.endpoint, ctx),
};
}
}
}
/** Stats for a request whose client went away mid-recovery. */
private recordClientGone(
startTime: number,
fallbackMeta: { chain: string[]; attempts: number } | undefined,
episodeId: string,
attempts: number,
recovery?: RecoveryTally
): void {
log(
`[Recovery] client disconnected after ${attempts} attempts (episode ${episodeId}) — ` +
"releasing the request"
);
try {
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - startTime),
success: false,
http_status: 0,
error_class: "network",
error_code: "client_disconnected",
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(recovery),
});
} catch {
// Stats must never crash claudish
}
}
/**
* One request. Once it has been SIGNED (its headers fetched), every answer —
* the stream, the JSON form, and an upstream error such as a 5xx or a
* remapped 400 — names the credential that signed it, so `--probe` reports
* the signer even when the request then failed for another reason. A request
* that failed before it was signed (no usable login) names nothing.
*/
async handle(c: Context, payload: any): Promise<Response> {
const signing: { headers?: Record<string, string> } = {};
const response = await this.handleSigned(c, payload, signing);
if (!signing.headers || !this.provider.signingCredential) return response;
return withSignerHeader(response, this.provider.signingCredential(signing.headers));
}
private async handleSigned(
c: Context,
payload: any,
signing: { headers?: Record<string, string> }
): Promise<Response> {
const startTime = performance.now();
// Stamp the recovery deadline's ZERO POINT here, and not wherever something
// first asks for it.
//
// `inboundStartedAtPerf` memoises on `c.req.raw`, so before this line the
// zero point was set by the FIRST caller — which on the fetch path is
// `tier1DeadlineAt(c)` inside the `catch`, i.e. AFTER attempt 1 has already
// failed. MEASURED against an unrouted address: attempt 1 burned macOS's
// 75 s connect timeout, the deadline's clock then started from there, and a
// request with a 30 s budget answered at 108 s — the budget was not
// exceeded, it was never applied. A ladder cannot bound a request whose
// clock starts after the overrun it was supposed to bound.
//
// One `performance.now()` and one `WeakMap.set` per request; nothing else
// on the healthy path reads it. A later candidate in a fallback chain finds
// the value already there and inherits it, which is the documented intent —
// the deadline belongs to the inbound request, not to a candidate.
inboundStartedAtPerf(c);
// latency_ms = time-to-first-byte (from request send to successful response).
// Captured here so it is available to the post-stream stats callback below.
let latencyMs = 0;
// Capture and consume fallback metadata (set by FallbackHandler before calling handle).
// Used in all stats recording paths so a single event carries complete info.
const fallbackMeta = this.pendingFallbackMeta;
this.pendingFallbackMeta = undefined;
// This request's network-recovery account. A local, like `fallbackMeta` and
// for the same reason: the handler instance outlives the request and serves
// several at once. It stays all-zero and contributes NOTHING to any stats
// record unless a classified connection failure actually occurs.
const recoveryTally = ComposedHandler.newRecoveryTally();
// An internal call's deadline (the advisor panel gateway installs it).
// Undefined on every request from Claude Code, and then every use below
// collapses to the expression that ran before it existed.
const callSignal = callAbortSignal(c);
// This hop's entry in an internal call's hop log (advisor gateway only):
// pushed on entry, so the log lists every hop whose handle() ran, and
// filled with the signing arm once 5b has signed.
const hop = recordHopEntry(c, this.provider.name, this.bareModelName);
if (callSignal?.aborted) return this.respondCallAborted(startTime, fallbackMeta);
// 1. Transform incoming Claude-format request
const transformed = transformOpenAIToClaude(payload);
const { droppedParams } = transformed;
// `let`: a raw `providerRequest` hook's committed copies replace it (3b).
let claudeRequest = transformed.claudeRequest;
// 1a. Hook request stage A, on this attempt's own deep copy (each
// FallbackHandler candidate gets a fresh one, so nothing leaks between
// attempts). Before conversion, so a system note reaches every route:
// chat-completions adapters copy `system` into messages[0] at step 2 and
// build their payload from `messages` alone.
// An advisor handler runs none: a panel call is not a harness turn, and its
// request carries no session id whose pending notes it could consume. The
// panel gateway's never-served context carries no hooks either; this check
// keeps that true if an advisor handler is ever reached another way.
const hooks = this.options.requestRole === "advisor" ? undefined : requestHooksOf(c);
const hookScope: HookRequestScope | undefined = hooks
? await hooks.beginAttempt(c, {
claudeRequest,
route: this.routeInfo(),
upstream: this.upstreamFacts(),
model: typeof payload?.model === "string" ? payload.model : this.bareModelName,
stream: payload?.stream === true,
})
: undefined;
// 2. Get adapter and reset state
const adapter = this.getAdapter();
if (typeof adapter.reset === "function") adapter.reset();
// 3. Convert messages and tools
let messages = adapter.convertMessages(claudeRequest, filterIdentity);
let tools = adapter.convertTools(claudeRequest, this.options.summarizeTools);
// Per-API tool-count cap (e.g. OpenAI Chat Completions hard-caps `tools` at
// 128 — exceeding it fails the WHOLE request with HTTP 400 "array too long").
// Head-slice to the limit: Claude Code emits its built-in agentic tools
// first and appends MCP-server tools after, so keeping the first N preserves
// the load-bearing built-ins and drops the tail-most MCP tools. Truncating
// is recoverable; failing the whole request is not.
const maxToolCount = adapter.getMaxToolCount();
if (maxToolCount && tools.length > maxToolCount) {
log(
`[ComposedHandler] Capping tools from ${tools.length} to ${maxToolCount} for ${this.targetModel} (API limit)`
);
tools = tools.slice(0, maxToolCount);
}
// Handle image content for models that don't support vision
if (!this.getModelSupportsVision()) {
// Collect all image blocks from all messages with their positions.
// Supports both OpenAI format (image_url) and Anthropic format (type:"image"|"document").
const imageBlocks: Array<{ msgIdx: number; partIdx: number; block: OpenAIImageBlock }> = [];
for (let msgIdx = 0; msgIdx < messages.length; msgIdx++) {
const msg = messages[msgIdx];
if (Array.isArray(msg.content)) {
for (let partIdx = 0; partIdx < msg.content.length; partIdx++) {
const part = msg.content[partIdx];
if (part.type === "image_url" || part.type === "image" || part.type === "document") {
imageBlocks.push({ msgIdx, partIdx, block: part as OpenAIImageBlock });
}
}
}
}
if (imageBlocks.length > 0) {
log(
`[ComposedHandler] Non-vision model received ${imageBlocks.length} image(s), calling vision proxy`
);
// Only attempt vision proxy for OpenAI-format image_url blocks (proxy expects that format).
// Anthropic-format image/document blocks are stripped directly.
const openAIImageBlocks = imageBlocks.filter((b) => (b.block as any).type === "image_url");
let descriptions: string[] | null = null;
if (openAIImageBlocks.length > 0) {
const auth = extractAuthHeaders(c);
descriptions = await describeImages(
openAIImageBlocks.map((b) => b.block),
auth
);
}
if (descriptions !== null && openAIImageBlocks.length > 0) {
// Replace image_url blocks with [Image Description: ...] text blocks
for (let i = 0; i < openAIImageBlocks.length; i++) {
const { msgIdx, partIdx } = openAIImageBlocks[i];
messages[msgIdx].content[partIdx] = {
type: "text",
text: `[Image Description: ${descriptions[i]}]`,
};
}
log(`[ComposedHandler] Vision proxy described ${descriptions.length} image(s)`);
// Strip any remaining Anthropic-format image/document blocks
for (const msg of messages) {
if (Array.isArray(msg.content)) {
msg.content = msg.content.filter(
(part: any) => part.type !== "image" && part.type !== "document"
);
if (msg.content.length === 1 && msg.content[0].type === "text") {
msg.content = msg.content[0].text;
} else if (msg.content.length === 0) {
msg.content = "";
}
}
}
} else {
// Vision proxy failed or not applicable — strip all unsupported image/document blocks
log("[ComposedHandler] Stripping image/document blocks (vision not supported)");
for (const msg of messages) {
if (Array.isArray(msg.content)) {
msg.content = msg.content.filter(
(part: any) =>
part.type !== "image_url" && part.type !== "image" && part.type !== "document"
);
if (msg.content.length === 1 && msg.content[0].type === "text") {
msg.content = msg.content[0].text;
} else if (msg.content.length === 0) {
msg.content = "";
}
}
}
}
}
}
// Log request summary
const systemPromptLength =
typeof claudeRequest.system === "string" ? claudeRequest.system.length : 0;
logStructured(`${this.provider.displayName} Request`, {
targetModel: this.targetModel,
originalModel: payload.model,
messageCount: messages.length,
toolCount: tools.length,
systemPromptLength,
maxTokens: claudeRequest.max_tokens,
});
// Debug logging
if (getLogLevel() === "debug") {
const lastUserMsg = messages.filter((m: any) => m.role === "user").pop();
if (lastUserMsg) {
const content =
typeof lastUserMsg.content === "string"
? lastUserMsg.content
: JSON.stringify(lastUserMsg.content);
log(`[${this.provider.displayName}] Last user message: ${truncateContent(content, 500)}`);
}
if (tools.length > 0) {
const toolNames = tools.map((t: any) => t.function?.name || t.name).join(", ");
log(`[${this.provider.displayName}] Tools: ${toolNames}`);
}
}
// 3a. Hook request stage B: tool-description actions, on the Claude-format
// tools AND the converted ones, after convertTools (so `summarizeTools`,
// which keeps only a description's first sentence, cannot cut an append)
// and after the tool-count cap (a description action on a capped tool
// changes the Claude-format copy only, journaled `capped`). It runs before
// the raw tier on purpose: a raw `providerRequest` hook sees the request the
// closed actions produced.
hookScope?.applyToolDescriptions(claudeRequest.tools ?? [], tools);
// 3b. Raw `providerRequest` hooks (the unsafe tier; the Gemini
// thought-signature built-in lives here), after stage B so they see the
// request the closed actions produced.
//
// MUST run before buildPayload. buildPayload is not guaranteed to keep a
// reference to `messages`/`tools`: the Chat Completions adapter assigns them
// straight onto the payload, but the Codex/Responses adapter deep-copies
// both and lifts the system prompt out of `claudeRequest.system` into
// `payload.instructions`. A hook run after buildPayload would lose every
// change on exactly the path gpt-5.x uses.
//
// Each hook works on clones, committed only when its call succeeds within
// its timeout; a throw, rejection or timeout leaves the request as it was.
if (hookScope) {
({ claudeRequest, messages, tools } = await hookScope.raw.providerRequest({
claudeRequest,
messages,
tools,
}));
}
// 4. Build request payload
let requestPayload = adapter.buildPayload(claudeRequest, messages, tools);
// Merge provider-specific extra fields
const extraFields = this.provider.getExtraPayloadFields?.();
if (extraFields) {
Object.assign(requestPayload, extraFields);
}
// 5. Adapter post-processing (tool name truncation, reasoning params, etc.)
adapter.prepareRequest(requestPayload, claudeRequest);
// Model adapter may also need to post-process (e.g., strip unsupported thinking params)
if (this.modelAdapter && this.modelAdapter !== adapter) {
this.modelAdapter.prepareRequest(requestPayload, claudeRequest);
}
const toolNameMap = adapter.getToolNameMap();
// 5a-pre. Ultracode → catalog provider-preset injection (opt-in).
//
// Runs BEFORE the 5a --model-params merge, and that order IS the
// precedence rule: an explicit user `--model-params reasoning.mode=x` wins
// only because the merge lands last. Swap these two blocks and the
// injection silently overrides what the user asked for.
//
// Both blocks sit after step 5 (prepareRequest) and before 5c
// (transformPayload) on purpose: after, so they beat every adapter default;
// before, so they write into the payload itself rather than into a
// provider envelope that 5c may wrap around it.
// 5w. A known catalog wire decides the output limit, reasoning, mode and
// speed — nothing else does. It runs after every adapter and dialect (it
// removes whatever they emitted for those decisions) and before
// --model-params, which stays the user's last word.
let wireHeaders: WireHeader[] = [];
let wireBorrowed: string[] = [];
const wire = this.options.connection?.wire;
if (wire?.status === "known") {
const choices: WireChoices = {
...wireChoicesFromClaudeRequest(claudeRequest, this.options.effortOverride),
catalogMaxOutputTokens: this.options.connection?.maxOutputTokens,
// `--accept-served-model` (or CLAUDISH_ACCEPT_SERVED_MODEL=1): the user
// named the swap, so a part the catalog warns about may be sent.
acceptServedModelChange: process.env.CLAUDISH_ACCEPT_SERVED_MODEL === "1",
};
const markers = wireMarkerContext.getStore();
const wireMode = this.options.wireMode ?? markers?.mode;
const wireSpeed = this.options.wireSpeed ?? markers?.speed;
if (wireMode) {
choices.mode = { value: wireMode, explicit: true };
} else if (
this.options.proOnUltracode &&
isUltracodeMainTurn({
enabled: true,
sessionId: extractSessionId(claudeRequest?.metadata),
outputConfig: claudeRequest?.output_config,
registry: this.options.sessionEventRegistry,
})
) {
choices.mode = { value: "pro", explicit: false };
}
if (wireSpeed) choices.speed = { value: wireSpeed, explicit: true };
const shaped = shapeRequestFromWire(
requestPayload,
wire,
choices,
this.options.connection?.ownerWire
);
wireBorrowed = shaped.borrowed;
const where = `${this.options.connection?.route.routeId}/${this.options.connection?.route.routeProfileId} · ${this.options.connection?.externalModelId}`;
for (const note of shaped.notes) log(`[Wire] ${where}: ${note}`);
if (shaped.refusal) {
return c.json(
wrapAnthropicError(
400,
`claudish: ${shaped.refusal} (${where})`,
"invalid_request_error"
),
400 as any
);
}
wireHeaders = shaped.headers;
} else if (
this.options.wireMode ||
this.options.wireSpeed ||
wireMarkerContext.getStore()?.mode ||
wireMarkerContext.getStore()?.speed
) {
// A marker asks for something only a connection's wire can grant; without
// one there is nothing that says how, or whether, to send it.
return c.json(
wrapAnthropicError(
400,
`claudish: ${this.targetModel} has no catalog wire, so a +mode or #speed marker cannot be applied`,
"invalid_request_error"
),
400 as any
);
} else if (this.options.proOnUltracode) {
applyProInjection(requestPayload, {
enabled: true,
sessionId: extractSessionId(claudeRequest?.metadata),
bareModelName: this.bareModelName,
provider: this.provider.name,
targetModel: this.targetModel,
outputConfig: claudeRequest?.output_config,
registry: this.options.sessionEventRegistry,
cachePath: this.options.catalogCachePath,
});
}
// 5a. --model-params: the user's last word on the payload.
if (this.options.modelParams) {
deepMergeParams(requestPayload, this.options.modelParams);
log(
`[ComposedHandler] Merged --model-params (${Object.keys(this.options.modelParams).join(", ")}) for ${this.targetModel}`
);
}
// 5b. Refresh auth / health check (must happen before transformPayload, which may use auth state)
//
// `binding` is THIS request's auth: a transport that mints a per-request
// artifact (`openai-codex`) returns it, and every later auth-dependent call
// of this request (5c, the endpoint, every header fetch, the 401 retry, the
// retry legs) is handed it back, so a concurrent request's refresh on the
// same handler can never change what this one signs with. Undefined for a
// transport that returns nothing (every other one), which then behaves
// exactly as before.
let binding: AuthBinding | undefined;
if (this.provider.refreshAuth) {
try {
// Raced, not cancelled: a refresh is single-flight and shared with
// other requests, so an aborted call stops WAITING for it and nothing
// more.
binding = (await raceCallAbort(this.provider.refreshAuth(), callSignal)) || undefined;
// Quota is DELIBERATELY not fetched here.
//
// This used to await getQuotaRemaining with a 2s cap on every single
// request, purely so a status line could show usage — i.e. it could
// add up to two seconds of latency to a turn before the upstream call
// had even started. Quota is now published by the adapters in
// auth/quota: Codex scrapes it from response headers that arrive
// anyway, and Antigravity polls a free endpoint off the request path.
// Neither can delay a turn, because neither does any work during one.
} catch (err: any) {
// CLASSIFY FIRST — before `err.terminal`, before anything invents a
// status. `refreshAuth()` is a NETWORK call for most transports
// (Antigravity makes three, Vertex mints a token, a local provider
// probes its own server), so "the refresh threw" and "the credential is
// bad" are two different facts and only one of them is this catch's
// subject. Answering 401 for the network one is not a cosmetic
// mislabel: `fallback-handler.ts`'s `isRetryableError` treats 401 as
// retryable, so a DNS or refused-connection failure here walked the
// user across every provider in the chain — off a subscription onto
// metered billing — for an outage on their own machine.
//
// A stopped call is not a failure to classify: no verdict, no stderr.
if (callAborted(c)) return this.respondCallAborted(startTime, fallbackMeta);
const conn = classifyConnectionError(err);
if (conn) {
// The refresh path's deadline is DELIBERATELY earlier than the fetch
// path's. Both live in the same request and share one budget; if a
// refresh recovers at the very end of it and then succeeds, the flow
// proceeds to the primary fetch — byte-identical to today's
// expression and therefore unclamped — and a maximal connect hang
// would land the response write a whole connect timeout past the
// deadline.
const outcome = await this.recoverAtAuthSite(
c,
err,
conn,
this.connectionEndpointFor(err),
() => this.provider.refreshAuth!(),
{
startTime,
deadlineAt: refreshDeadlineAt(tier1DeadlineAt(c)),
fallbackMeta,
authType: "oauth",
site: "refreshAuth",
recovery: recoveryTally,
},
"401"
);
if (outcome.kind === "respond") return outcome.response;
// Recovered: fall through as if the first refresh had succeeded,
// bound to the artifact the successful attempt minted.
binding = outcome.value || undefined;
} else {
log(`[${this.provider.displayName}] Auth/health check failed: ${err.message}`);
logStderr(
`Error [${this.provider.displayName}]: Auth/health check failed — ${err.message}. Check credentials and server.`
);
reportError({
error: err,
providerName: this.provider.name,
providerDisplayName: this.provider.displayName,
streamFormat: this.provider.streamFormat,
modelId: this.targetModel,
httpStatus: 401,
isStreaming: false,
retryAttempted: false,
isInteractive: this.isInteractive,
authType: "oauth",
});
// One classifier for every credential site (`auth-failure.ts`):
// - terminal (misconfiguration, revoked entitlement, expired login)
// → 400 with the terminal verdict. Answering 401 sent the client
// into ~11 retries over two minutes of backoff with the message
// hidden behind "API error · Retrying", and walked the chain.
// - transient (the token host answered 5xx/429) → 503/429 with the
// transient verdict, never 401: the same hop answers on retry.
// - unclassifiable: a SUBSCRIPTION → 503 with the transient verdict
// (retried, never walked; a dead login is marked terminal by its
// producer, `credential-error.ts`); a METERED provider → 401 as
// before, so the chain may try a provider with another credential.
const answered = this.answerAuthFailure(c, err, "401");
if (answered) return answered;
throw err;
}
}
// Update display name in case auth resolved it (e.g., Gemini tier
// detection). Moved out of the `try` so it runs after a RECOVERED
// refresh too — a refresh that only succeeded on attempt four resolved
// the same names as one that succeeded on attempt one.
if (this.provider.displayName) {
this.tokenTracker.setProviderDisplayName(this.provider.displayName);
}
}
if (hop) this.markHopSigned(hop, binding);
// Update context window if provider dynamically discovered it
// (e.g., from OpenRouter model catalog or local model API).
//
// Only a POSITIVE number is applied. A transport returns 0 to mean "I have
// no opinion" — OpenRouterProviderTransport says so in as many words, and
// OpenAICodexTransport falls back to 0 on a catalog miss. Applying that 0
// unconditionally overwrote the window the model dialect had already
// resolved from the catalog, so every OpenRouter-routed model wrote
// `"context_window": "unknown"` and lost its context field in the status
// line. 0 must be a no-op, not a reset.
if (this.provider.getContextWindow) {
const providerWindow = this.provider.getContextWindow();
if (providerWindow > 0) {
this.tokenTracker.setContextWindow(providerWindow);
}
}
// 5r. Code-mode resume (`openai-codex`): tool_results answering a suspended
// exec script's batch feed the script. After 5b, so the account is THIS
// request's; after 3b, so a synthetic reply gets the same raw hooks (the
// response seam above this handler applies the closed tool hooks to it).
// Synchronous from record lookup to state transition. A script that
// blocked again is answered here with its next batch — no upstream call,
// no further auth, no stats record (nothing was billed) — through the same
// exit as step 8. Anything else continues. A store that was never created
// (no code-mode request in this process) is created here only when the
// last message answers nested ids — the first request after a restart —
// so the lost script's tombstone exists before 5d builds the input.
if (this.provider.name === "openai-codex") {
const resume = (mayRequestModule: boolean) =>
resumeFromToolResults(
claudeRequest,
binding,
peekCodeModeStores(),
claudeRequest?.tool_choice,
{
setting: this.options.codeMode ?? DEFAULT_CODE_MODE_SETTING,
createStores: getCodeModeStores,
mayRequestModule,
}
);
let resumed = resume(true);
if (resumed.kind === "needs-module") {
// A lost script can replay, but its module was dropped (retired,
// poisoned, recycled). 5r never awaits: load here, then run 5r once
// more — never a third time, so a failed load ends in the tombstone.
await loadQuickJSModule();
resumed = resume(false);
}
if (resumed.kind === "reply") {
const sse = createSyntheticToolUseReply(resumed.blocks, {
modelName: this.bareModelName,
priorInputTokens: this.tokenTracker.getLastInputTokens(),
onToolCallObserved: (name: string) => this.tokenTracker.recordToolUse(name),
raw: hookScope?.raw.streamTap(),
});
return payload?.stream === true ? sse : sseResponseToJson(sse, this.bareModelName);
}
}
// 5c. Provider payload transformation (e.g., CodeAssist envelope wrapping)
if (this.provider.transformPayload) {
requestPayload = this.provider.transformPayload(requestPayload, claudeRequest, binding);
}
// 5d. Code mode (`openai-codex` only; by default `auto`, on where
// discovery reports `code_mode_only`; `--code-mode` / CLAUDISH_CODE_MODE /
// `codeMode` override it). After 5c, so the Codex fields 5c added are
// kept; decided from THIS request's binding. A lite
// request's header joins `wireHeaders`, so every header fetch below
// carries it. Never throws: a failed decision or build leaves the request
// exactly as 5c produced it.
//
// `codeModeShape` is the shape actually sent (`lite` falls back to
// `classic` in the 4xx block when the backend rejects it); the clone and
// context are what that fallback rebuilds from.
let codeModeShape: "lite" | "classic" | undefined;
let codeModePrePayload: any;
let codeModeContext: CodeModePayloadContext | undefined;
let codeModeTurn: PreparedCodeMode["turn"];
if (this.provider.name === "openai-codex") {
const prepared = await prepareCodeModeRequest({
providerName: this.provider.name,
setting: this.options.codeMode ?? DEFAULT_CODE_MODE_SETTING,
binding,
api:
wire?.status === "known"
? wire.api
: this.resolveStreamFormat() === "openai-responses-sse"
? "responses"
: undefined,
claudeRequest,
payload: requestPayload,
});
if (prepared.request) {
requestPayload = prepared.request.payload;
codeModeShape = prepared.request.shape;
codeModePrePayload = prepared.prePayload;
codeModeContext = prepared.context;
codeModeTurn = prepared.turn;
wireHeaders = [...wireHeaders, ...prepared.request.headers];
// 5a'. --model-params again, only for a code-mode payload: the user's
// explicit fields still win over what 5d wrote (idempotent deep merge).
if (this.options.modelParams) deepMergeParams(requestPayload, this.options.modelParams);
}
}
// (Raw providerRequest hooks ran at step 3b, before buildPayload — see the
// note there for why they cannot run at this point.)
// `let`: the 401 branch replaces `binding` and recomputes the endpoint from it.
let endpoint = this.provider.getEndpoint(this.targetModel, binding);
// The ORIGINAL inbound body, not the normalized `claudeRequest` clone: a
// header carrying conversation identity must see what Claude Code sent.
//
// `getHeaders()` sat outside EVERY try, and for some transports it is the
// request's first network touch — `gk@` reaches
// `resolveGrokAccessToken()` → `fetch(auth.x.ai/oauth2/token)` from here
// when the cached token has expired. An unclassified throw escaped `handle()`
// entirely and landed in one of two places, neither of which says anything
// true: `fallback-handler.ts`'s catch, which records `status: 0` and
// ADVANCES THE CHAIN with not even the per-token cost warning (that warning
// sits on the non-throwing branch), or — for a single-candidate route, where
// no FallbackHandler exists — `proxy-server.ts`'s bare 500.
//
// The touch is refresh-conditional, which makes this rare, not safe.
// Every header fetch below goes through this, so a header the wire requires
// (a beta token next to the field it wrote) survives the auth retries too.
//
// Signed by the binding passed, never by shared transport state: the
// primary fetch and parameter retry pass this request's `binding`, the 401
// retry the one `forceRefreshAuth` just returned, a retry leg its own.
//
// The headers of THIS request's latest attempt — the one whose answer is
// returned (primary, parameter re-fetch or auth retry), recorded on this
// call's own `signing` record so a concurrent request on the same handler
// cannot replace it. `handle` names the signer from them (`signingCredential`).
//
// Every attempt's credential values are registered for redaction right
// here, before any of them can be echoed back: the primary fetch, the
// parameter re-fetch, the 401 retry's fresh token and every Responses leg
// sign through this one function. From now until the inbound request's
// body ends, every log sink and every `redactSecrets` caller replaces them.
//
// A transport's out-of-header secrets (`redactionSecrets`: Devin's key reads
// env, config and a file) are read once per binding of this request: a
// forced refresh returns a new binding and is read again (Antigravity's
// access token changes with it), the post-serialize registration below
// reuses the read.
let transportSecretsRead = false;
let transportSecretsBinding: AuthBinding | undefined;
let transportSecretsValue: string[] = [];
const transportSecrets = (b: AuthBinding | undefined): string[] => {
if (!this.provider.redactionSecrets) return [];
if (transportSecretsRead && transportSecretsBinding === b) return transportSecretsValue;
transportSecretsRead = true;
transportSecretsBinding = b;
transportSecretsValue = this.provider.redactionSecrets();
return transportSecretsValue;
};
const fetchHeaders = async (b: AuthBinding | undefined): Promise<Record<string, string>> => {
const fetched = await this.provider.getHeaders(payload, b);
mergeWireHeaders(fetched, wireHeaders);
addSigningSecrets(c, credentialValuesFromRequest(fetched, this.signedEndpoint(b)));
addSigningSecrets(c, transportSecrets(b));
signing.headers = fetched;
return fetched;
};
let headers: Record<string, string>;
try {
headers = await raceCallAbort(fetchHeaders(binding), callSignal);
} catch (err: any) {
if (callAborted(c)) return this.respondCallAborted(startTime, fallbackMeta);
const conn = classifyConnectionError(err);
if (!conn) {
// A credential failure this site can place is answered here — terminal
// as 400; transient, or a subscription's unclassifiable one, as 503/429.
// Anything else (a metered provider's unclassifiable throw) keeps its
// existing route out of here untouched.
const answered = this.answerAuthFailure(c, err, "rethrow");
if (answered) return answered;
throw err;
}
const outcome = await this.recoverAtAuthSite<Record<string, string>>(
c,
err,
conn,
this.connectionEndpointFor(err, endpoint),
() => fetchHeaders(binding),
{
startTime,
// An auth site with the unclamped primary fetch still ahead of it —
// same reservation as the refreshAuth catch, same reason.
deadlineAt: refreshDeadlineAt(tier1DeadlineAt(c)),
fallbackMeta,
authType: "oauth",
site: "getHeaders",
recovery: recoveryTally,
},
"rethrow"
);
if (outcome.kind === "respond") return outcome.response;
headers = outcome.value;
}
// 6a. The body is NOT necessarily JSON. A transport may serialize the
// payload itself (Devin encodes Connect-protobuf, credential and all).
// Computed ONCE — retries must re-send identical bytes — and
// default-preserving: a transport that leaves `serializeBody` undefined
// yields `undefined` here and every expression below collapses to exactly
// what it was before this hook existed.
// Always the encoding of the CURRENT `requestPayload`: parameter recovery
// replaces the payload and re-encodes it here, so the 401 auth retry below
// never resends bytes the provider already rejected.
let serialized = this.provider.serializeBody?.(requestPayload);
// A credential the transport put in the BODY (Devin) is registered as soon
// as the bytes exist (the read `fetchHeaders` made for this binding).
addSigningSecrets(c, transportSecrets(binding));
headers["Content-Type"] = serialized?.contentType ?? "application/json";
log(`[${this.provider.displayName}] Calling API: ${endpoint}`);
// Merge provider-specific fetch options (e.g., undici dispatcher, abort signal)
const requestInit = this.provider.getRequestInit?.() || {};
// THE REQUEST'S OWN CEILING — the one thing outside the `catch` that this
// feature adds to a healthy request, and the reason it is here rather than
// in the ladder: an unclamped attempt 1 could outlive the whole derived
// deadline (measured: 75 s of macOS connect against a 30 s budget, answered
// at 108 s), which makes the budget a suggestion. It is absolute, it fires
// at `deadlineAt` and never earlier, and it is disarmed the instant the
// call settles — see `deadlineClamp` for why both of those are what keep it
// from turning a slow answer into a re-issued one.
const deadlineAt = tier1DeadlineAt(c);
const clamp = deadlineClamp(deadlineAt);
//
// An internal call's deadline reaches this closure twice: a pre-start
// check, so a queue that admits it late (or a transport retry that calls it
// again) never starts a fetch, and the signal on the fetch, which also
// governs the body read after `clamp.disarm()`.
const doFetch = () => {
if (callSignal?.aborted) return Promise.reject(callAbortError());
return fetch(
endpoint,
mergeSignalIntoInit(
{
method: "POST",
headers,
body: serialized?.body ?? JSON.stringify(requestPayload),
...requestInit,
},
withCallSignal(clamp.signal, callSignal)
)
);
};
// Every queue admission of this request: with the call's signal when one
// is installed, so a queue that honours it drops the call while it waits;
// called exactly as before otherwise.
const enqueue = (fn: () => Promise<Response>): Promise<Response> =>
callSignal
? this.provider.enqueueRequest!(fn, { signal: callSignal })
: this.provider.enqueueRequest!(fn);
let response: Response;
try {
try {
response = this.provider.enqueueRequest ? await enqueue(doFetch) : await doFetch();
} finally {
// Before a byte of the body is read, so the ceiling can only ever bound
// connect-and-headers — never cut a response already arriving.
clamp.disarm();
}
} catch (error: any) {
// A stopped call first: no classification, no stderr, no recovery.
if (callAborted(c)) return this.respondCallAborted(startTime, fallbackMeta);
// A failure to even REACH the provider (DNS can't resolve, connection
// refused, host unreachable) is a LOCAL network problem, not an upstream
// server error. Surface it as a connection_error with an honest,
// actionable message so Claude Code and the config probe show "can't reach
// host — check your network/DNS" instead of a mystifying 500. (A Tailscale
// MagicDNS outage making chatgpt.com unresolvable is what motivated this.)
const conn = classifyConnectionError(error);
if (!conn) {
// Not a connection fault: answer it the way the other credential sites
// do. A transport's `enqueueRequest` can mint or refresh a credential
// here (`muse@` mints its key per request), so a dead login (terminal
// 400), a token host's 429/5xx (transient) or a SUBSCRIPTION's
// unclassified throw (transient 503) lands as a response. Escaping
// `handle()` instead is the five-sites bug: FallbackHandler records
// status 0 and advances a subscription onto a metered hop. A METERED
// unknown is still rethrown unchanged ("rethrow").
const answered = this.answerAuthFailure(c, error, "rethrow");
if (answered) return answered;
throw error;
}
// Every construct below is built HERE, inside the catch, after
// classification returned non-null. A successful request never executes
// one line of it, and the expression above is byte-identical to what it
// was before recovery existed — including its `enqueueRequest` ternary.
//
// The re-issue must go through that SAME ternary. Six transports
// implement `enqueueRequest`, and what they implement is not decoration:
// a bounded 429 loop with `Retry-After`, a model-fallback chain drawn
// from the dynamic models catalog, and the local concurrency gate that
// stops `[email protected]:3` running four inferences at once. Skipping it
// would make the attempt that finally CONNECTS behave differently from
// the one that failed — and at the moment a network returns, N woken
// waiters would stampede unqueued into a provider that has just come back.
//
// `getRequestInit()` IS CALLED AGAIN, PER ATTEMPT, and that is not a
// tidiness preference. A transport may return a ONE-SHOT signal from it —
// `vertex-oauth.ts` returns `AbortSignal.timeout(30000)`, `local.ts` a
// ten-minute one — and `mergeSignalIntoInit` composes it with the clamp
// via `AbortSignal.any`. Re-using the hoisted object meant that from 30 s
// after the FIRST call, every ladder attempt was handed an
// already-aborted signal and rejected instantly without touching the
// network: tier 1 silently dead past t+30 s, the request held for the
// full ~270 s deadline making ZERO real connect attempts, while the
// `[Recovery]` log and the pane both reported attempts that never left
// the process. A transport ceiling that must survive across attempts has
// to be RE-MINTED, never re-used. `doParamRetry` and `doAuthRetry` below
// already call it freshly per attempt; this is the same rule.
const doFetchWith = (sig: AbortSignal) =>
fetch(
endpoint,
mergeSignalIntoInit(
{
method: "POST",
headers,
body: serialized?.body ?? JSON.stringify(requestPayload),
...(this.provider.getRequestInit?.() || {}),
},
sig
)
);
const reissue = (sig: AbortSignal) => {
const attempt = () => doFetchWith(sig);
return this.provider.enqueueRequest
? this.provider.enqueueRequest(attempt, { signal: sig })
: attempt();
};
// Through the auth-site wrapper: a re-issue that fails with something
// other than a connection fault is classified like any credential
// failure, not rethrown out of `handle()` into a status-0 chain advance.
const outcome = await this.recoverAtAuthSite<Response>(
c,
error,
conn,
endpoint,
reissue,
{
startTime,
// The SAME value the primary attempt was bounded by, not a fresh read.
deadlineAt,
fallbackMeta,
site: "fetch",
recovery: recoveryTally,
},
"rethrow"
);
if (outcome.kind === "respond") return outcome.response;
response = outcome.value;
}
// We reached the host. ANY status proves that — a 401 is a conversation, a
// refused socket is not — so this is the moment an episode parked in
// `handoff` for this target learns that its outage is over.
//
// It has to be said here rather than left to the grace timer because tier
// 2's rejoin is not what happens when the network comes back. Claude Code's
// re-POST enters the byte-identical primary fetch ABOVE, which succeeds
// outright: no catch, no `joinEpisode`, no rejoin — and the pane would go
// on painting "waiting for Claude Code to retry" over a working session for
// the rest of the 120-second grace.
//
// `episodeCount()` is a `Map.size` read and is 0 on every machine that has
// never had an outage, so the healthy path pays one integer comparison for
// a banner that stops lying.
if (episodeCount() > 0) noteTargetReachable(this.provider.name, endpoint);
// Check if the transport fell back to a different model (e.g., capacity exhaustion)
if (this.provider.getActiveModelName?.()) {
const activeModel = this.provider.getActiveModelName()!;
this.tokenTracker.setActiveModelName(activeModel);
log(`[ComposedHandler] Transport fell back to model: ${activeModel}`);
}
log(`[${this.provider.displayName}] Response status: ${response.status}`);
// Harvest plan usage BEFORE the error branches, because every one of them
// returns early. A 429 is the single most valuable moment to read Codex's
// usage headers — it is the turn where the user just hit their limit, and
// capturing only on success would report 90% and then go quiet at 100%.
// Idempotent: this runs again after the response settles, and the later,
// fresher reading simply overwrites this one.
this.capturePlanUsage(response);
if (!response.ok) {
// 4xx caused by an OPTIONAL parameter the model dialect added
// speculatively: let the dialect rewrite the payload and retry ONCE.
//
// This is what lets a dialect send a capability parameter optimistically
// instead of withholding it from every model it cannot prove supports it.
// Withholding fails silently — the user's setting vanishes and the only
// symptom is different model behaviour — whereas sending fails here,
// loudly, and is repaired in one round-trip that is then remembered.
// Motivating case: grok-4.6 accepts `reasoning_effort` but postdated the
// allowlist, so it silently ran at the provider's default (near-`high`)
// tier and blew a 900s team deadline.
//
// Bounded to a single attempt on purpose: the dialect records the verdict,
// so a second failure means the error was never about that parameter.
//
// BOTH ADAPTERS ARE ASKED, in Layer order. This used to call
// `this.modelAdapter` alone, which silently excluded every model that
// resolves to `DefaultAPIFormat`: `resolveModelDialect` returns it for any
// model no dialect recognises, and the constructor above deliberately
// leaves `modelAdapter` unset for exactly that value. So an unrecognized
// model on a custom OpenAI-compatible endpoint — a brand-new
// `vendor/new-model`, which is the population most likely to meet a strict
// relay — reached a 400 `Unknown parameter: 'stop'` with no recovery at
// all, even though `BaseAPIFormat.recoverFromRejection` is written to
// repair precisely that. The Layer 1 converter is also the adapter that
// BUILT the payload (`getAdapter()` is `explicitAdapter || resolvedDialect`),
// so it is the one that added the optional parameter in the first place.
//
// Deduped by identity, first non-null wins. Every implementation is
// stateless with respect to the payload — it returns a NEW object and
// mutates nothing — so asking a second one after the first declines costs
// nothing and cannot corrupt the retry.
if (response.status >= 400 && response.status < 500) {
const candidates = [this.modelAdapter, this.getAdapter()].filter(
(a, i, all): a is BaseModelAdapter => !!a?.recoverFromRejection && all.indexOf(a) === i
);
const errorText =
candidates.length > 0 || wireBorrowed.length > 0 || codeModeShape === "lite"
? await response.clone().text()
: "";
let recovery: { payload: any; note: string } | null = null;
// A code-mode LITE request the backend rejects for the lite header or
// `reasoning.context` (the raw upstream status, before the terminal
// remap): resend it once in the code-mode CLASSIC shape — the same exec
// tool and input, never the non-code-mode function tools — without the
// header (a classic body with it is itself a 400, variant D). The model
// stays on classic for the discovery TTL. Checked first: nothing else
// in this request is suspect yet.
if (
codeModeShape === "lite" &&
codeModeContext &&
codeModePrePayload !== undefined &&
isLiteRejection(response.status, errorText)
) {
wireHeaders = withoutLiteHeader(wireHeaders);
const classic = rebuildAsClassic(
codeModePrePayload,
codeModeContext,
typeof requestPayload?.model === "string" ? requestPayload.model : this.targetModel
);
codeModeShape = classic.shape;
if (this.options.modelParams) deepMergeParams(classic.payload, this.options.modelParams);
recovery = { payload: classic.payload, note: "lite request rejected; classic shape" };
}
// Fields borrowed from the owner's connection (this connection's own
// value is unknown) are the first suspects: tried in turn, dropped on the
// 400 that names them. Only those fields — never one the wire published.
if (!recovery) {
recovery = recoverBorrowedWireFields(requestPayload, wireBorrowed, errorText);
if (recovery) wireBorrowed = [];
}
for (const candidate of recovery ? [] : candidates) {
recovery = candidate.recoverFromRejection(requestPayload, errorText);
if (recovery) break;
}
if (recovery) {
log(`[${this.provider.displayName}] Parameter rejected — retrying: ${recovery.note}`);
requestPayload = recovery.payload;
// Re-serialize: a transport that owns its own encoding (Devin) must
// re-encode the changed payload rather than resend the stale bytes.
serialized = this.provider.serializeBody?.(requestPayload);
const retrySerialized = serialized;
// This re-fetch had NO `try` at all. A connection throw therefore
// escaped handle() entirely and landed in `fallback-handler.ts`'s
// catch, which pushes `{ status: 0 }` and advances the chain
// unconditionally — the same silent move onto metered billing the
// auth catches make, reached from a different direction.
//
// A classified failure answers with the network truth rather than
// re-reporting the original parameter complaint: the parameter is no
// longer what is wrong, and repeating it would send the chain hunting
// for a provider that accepts it while the machine is offline. An
// UNCLASSIFIED throw is rethrown unchanged, so the existing 500 route
// out of here is untouched.
const doParamRetry = async (sig?: AbortSignal): Promise<Response> => {
if (callSignal?.aborted) throw callAbortError();
const retryHeaders = await raceCallAbort(fetchHeaders(binding), callSignal);
retryHeaders["Content-Type"] = retrySerialized?.contentType ?? "application/json";
return fetch(
endpoint,
mergeSignalIntoInit(
{
method: "POST",
headers: retryHeaders,
body: retrySerialized?.body ?? JSON.stringify(requestPayload),
...(this.provider.getRequestInit?.() || {}),
},
withCallSignal(sig, callSignal)
)
);
};
let retryResp: Response;
try {
retryResp = await doParamRetry();
} catch (err: any) {
if (callAborted(c)) return this.respondCallAborted(startTime, fallbackMeta);
const conn = classifyConnectionError(err);
if (!conn) {
// The re-fetch re-reads the headers, so a credential failure can
// surface here too; one this site can place is answered.
const answered = this.answerAuthFailure(c, err, "rethrow");
if (answered) return answered;
throw err;
}
const outcome = await this.recoverAtAuthSite<Response>(
c,
err,
conn,
this.connectionEndpointFor(err, endpoint),
doParamRetry,
{
startTime,
// The full budget: this site runs AFTER the primary fetch, so
// there is no unclamped attempt left ahead of it to reserve for.
deadlineAt: tier1DeadlineAt(c),
fallbackMeta,
retriedBeforeLadder: true,
site: "parameter-recovery",
recovery: recoveryTally,
},
"rethrow"
);
if (outcome.kind === "respond") return outcome.response;
retryResp = outcome.value;
}
if (retryResp.ok) {
response = retryResp;
} else if (isCredentialRejection(retryResp.status, await retryResp.clone().text())) {
// The re-fetch's credential was REJECTED (401/403 that is not a
// model, quota or region answer). That is the newer, decisive fact:
// the parameter is fixed and the login is what is wrong now. It
// replaces the original 400 and takes the normal error path, so a
// 401 still gets the forced refresh, and a subscription's rejection
// answers the terminal 400 with the verdict and the
// `claudish login …` line (D10). Reporting the parameter 400
// instead dropped both, and a metered key could not advance.
log(
`[${this.provider.displayName}] Retry after ${recovery.note} was rejected ` +
`(HTTP ${retryResp.status}); reporting the credential rejection`
);
response = retryResp;
} else {
// Fall through to the normal error path with the ORIGINAL response,
// so the user sees the real upstream complaint rather than the
// artefact of our retry.
log(
`[${this.provider.displayName}] Retry after ${recovery.note} still failed ` +
`(HTTP ${retryResp.status})`
);
}
}
}
}
if (!response.ok) {
// 401: retry with forced auth refresh (OAuth token expiry)
// Only for a request with no binding (every transport but `openai-codex`,
// unchanged) or one bound to the OAuth arm: a forced OAuth refresh cannot
// fix an API key, so an `openai-codex` api-key request takes the ordinary
// error path below.
if (
response.status === 401 &&
this.provider.forceRefreshAuth &&
(binding === undefined || binding.auth?.arm === "oauth")
) {
log(`[${this.provider.displayName}] Got 401, forcing auth refresh and retrying`);
// The forced refresh AND the retry fetch that follows it, as one
// re-issuable operation. Both are network calls and either can fail
// transiently, so a ladder that could only re-run one of them would
// leave the other exactly as exposed as it was.
/** Answers that never reached the upstream (another credential silo): reported as such. */
const notResentResponses = new WeakSet<Response>();
const doAuthRetry = async (sig?: AbortSignal): Promise<Response> => {
// A returned binding replaces this request's: the retry, and every
// retry leg after it, sign with the artifact just minted. The headers
// of the request the upstream rejected go with it, so a transport can
// tell a stale failure from one naming the credential it holds now.
if (callSignal?.aborted) throw callAbortError();
const refreshed = await raceCallAbort(
this.provider.forceRefreshAuth!({ rejectedHeaders: headers }),
callSignal
);
if (refreshed) {
// The body was built for THIS binding's account (code mode renders
// its encrypted reasoning and keys its records by it): a refresh
// onto another arm or account must not resend it. Answered with
// the upstream's own 401, never a throw: inside the recovery
// ladder an unclassified throw escapes `handle()`.
if (
binding &&
!isSameCredentialSilo(
{ auth: binding.auth, accountKey: accountKeyFromBinding(binding) },
{ auth: refreshed.auth, accountKey: accountKeyFromBinding(refreshed) }
)
) {
log(`[${this.provider.displayName}] sign-in changed during the request; not resent`);
const notResent = new Response(
"Codex sign-in changed during the request; it was not resent",
{ status: response.status }
);
notResentResponses.add(notResent);
return notResent;
}
binding = refreshed;
// A re-sign replaces the arm on this hop's entry in place.
if (hop) this.markHopSigned(hop, binding);
endpoint = this.provider.getEndpoint(this.targetModel, binding);
}
const retryHeaders = await raceCallAbort(fetchHeaders(binding), callSignal);
// Same serialization as the primary request — this is a separate call
// site and the easy one to forget, which is why both are pinned by
// the same assertion.
retryHeaders["Content-Type"] = serialized?.contentType ?? "application/json";
const retryInit = this.provider.getRequestInit?.() || {};
return fetch(
endpoint,
mergeSignalIntoInit(
{
method: "POST",
headers: retryHeaders,
body: serialized?.body ?? JSON.stringify(requestPayload),
...retryInit,
},
withCallSignal(sig, callSignal)
)
);
};
/** Returns a Response to answer with, or null to carry on streaming. */
const settleAuthRetry = async (retryResp: Response): Promise<Response | null> => {
if (retryResp.ok) {
response = retryResp; // fall through to stream handling below
} else {
// Redacted at the read, so the returned body, the logs, the capture
// and the stats classification all see the same credential-free text.
const errorText = redactForClient(await retryResp.text());
// Not resent: the refresh signed in another account. No key is
// wrong and no retry went out, so neither message may say so.
const resent = !notResentResponses.has(retryResp);
log(
`[${this.provider.displayName}] ${resent ? "Retry failed" : "Not resent"}: ${errorText}`
);
logStderr(
resent
? `Error [${this.provider.displayName}]: HTTP ${retryResp.status} after auth retry. Check API key.`
: `Error [${this.provider.displayName}]: HTTP ${retryResp.status}; the sign-in changed to another account during the request, so it was not resent.`
);
reportError({
error: new Error(errorText),
providerName: this.provider.name,
providerDisplayName: this.provider.displayName,
streamFormat: this.provider.streamFormat,
modelId: this.targetModel,
httpStatus: retryResp.status,
isStreaming: false,
retryAttempted: resent,
isInteractive: this.isInteractive,
authType: "oauth",
});
try {
const { error_class, error_code } = classifyError(
new Error(errorText),
retryResp.status,
errorText
);
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - startTime),
success: false,
http_status: retryResp.status,
error_class,
error_code,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(recoveryTally),
});
} catch {
// Stats must never crash claudish
}
// A 401/403 that SURVIVED a fresh credential is terminal for a
// subscription, or wherever the transport says so: answered 400 with
// the terminal verdict and the same hint and wording as the generic
// remap below, so the login line lands inline and the chain stops.
// 401/403 ONLY: Antigravity's terminal 429 keeps its own route.
// A RESENT request only: a not-resent answer (the refresh signed in
// another account) proves nothing about the login, so it keeps its
// own 401 and message rather than "the login was rejected".
if (resent && (retryResp.status === 401 || retryResp.status === 403)) {
const transportTerminal = this.provider.classifyTerminalError?.(
retryResp.status,
errorText
);
// The subscription stop is for a credential rejection only; a model
// or allowance miss keeps its pass-through route (`isCredentialRejection`).
if (
(isSubscriptionProvider(this.provider.name) &&
isCredentialRejection(retryResp.status, errorText)) ||
transportTerminal === true
) {
const hint = getRecoveryHint(
retryResp.status,
errorText,
this.provider.displayName,
transportTerminal,
this.provider.name
);
let parsed: unknown;
try {
parsed = JSON.parse(errorText);
} catch {
parsed = undefined;
}
const providerMsg = extractProviderMessage(parsed ?? errorText);
const surfaced = buildSurfacedErrorMessage({
providerDisplayName: this.provider.displayName,
status: retryResp.status,
hint,
providerMessage: providerMsg,
});
return c.json(
wrapAnthropicError(
400,
surfaced,
"invalid_request_error",
retryResp.status,
providerMsg
),
400 as any,
authVerdictHeaders("terminal")
);
}
}
return c.json(wrapAnthropicError(retryResp.status, errorText), retryResp.status as any);
}
return null;
};
try {
const answered = await settleAuthRetry(await doAuthRetry());
if (answered) return answered;
} catch (err: any) {
if (callAborted(c)) return this.respondCallAborted(startTime, fallbackMeta);
// CLASSIFY FIRST, exactly as in the refreshAuth catch above, and for a
// sharper reason: this path covers BOTH `forceRefreshAuth()` AND the
// raw retry `fetch` that follows it, so "the network dropped while we
// were re-signing a request" arrives here and left as an unconditional
// `authentication_error` 401. `isRetryableError` reads 401 as
// retryable, so the upstream's 401 plus a network blip got relabelled
// as an auth failure and ADVANCED THE CHAIN — a subscription user
// moved onto a metered candidate mid-outage, which is the one outcome
// this whole area exists to prevent.
const conn = classifyConnectionError(err);
if (conn) {
const outcome = await this.recoverAtAuthSite<Response>(
c,
err,
conn,
this.connectionEndpointFor(err, endpoint),
doAuthRetry,
{
startTime,
deadlineAt: tier1DeadlineAt(c),
fallbackMeta,
retriedBeforeLadder: true,
authType: "oauth",
site: "forceRefreshAuth",
recovery: recoveryTally,
},
"401"
);
if (outcome.kind === "respond") return outcome.response;
const answered = await settleAuthRetry(outcome.value);
if (answered) return answered;
// Recovered and streaming: `response` was reassigned by
// settleAuthRetry. Fall through to the shared stream handling.
} else {
log(`[${this.provider.displayName}] Auth refresh failed: ${err.message}`);
logStderr(
`Error [${this.provider.displayName}]: Authentication failed — ${err.message}. Check API key.`
);
reportError({
error: err,
providerName: this.provider.name,
providerDisplayName: this.provider.displayName,
streamFormat: this.provider.streamFormat,
modelId: this.targetModel,
httpStatus: 401,
isStreaming: false,
retryAttempted: true,
isInteractive: this.isInteractive,
authType: "oauth",
});
try {
const { error_class, error_code } = classifyError(err, 401, err.message);
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - startTime),
success: false,
http_status: 401,
error_class,
error_code,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(recoveryTally),
});
} catch {
// Stats must never crash claudish
}
// The same classifier as the refreshAuth catch: terminal → 400 with
// the terminal verdict; transient, or a subscription's
// unclassifiable failure → 503/429 with the transient verdict; a
// metered provider's unclassifiable failure → 401 as before.
const answered = this.answerAuthFailure(c, err, "401");
if (answered) return answered;
throw err;
}
}
} else {
// Redacted at the read: the returned body, the logs, the capture and the
// stats classification below all use this one credential-free text.
const errorText = redactForClient(await response.text());
log(`[${this.provider.displayName}] Error: ${errorText}`);
// Durable copy, opt-in via CLAUDISH_UPSTREAM_ERROR_LOG. `log()` only
// persists under --debug, so without this the body that distinguishes a
// retryable rate limit from a hard quota wall is gone the moment it is
// classified. No-op and non-throwing when the env var is unset.
captureUpstreamError({
provider: this.provider.displayName,
model: this.bareModelName,
status: response.status,
body: errorText,
});
// A transport that parses its provider's structured errors outranks the
// shared substring heuristics — computed ONCE here so the user-facing
// hint and the terminal/retryable remap below cannot disagree about what
// happened. `undefined` (the default for every transport without the
// hook) leaves the generic rules exactly as they were.
const transportTerminal = this.provider.classifyTerminalError?.(response.status, errorText);
const hint = getRecoveryHint(
response.status,
errorText,
this.provider.displayName,
transportTerminal,
// The INTERNAL name, beside the display name: the catalog is keyed by
// it, and an auth failure on a vendor with sibling-tier keys needs
// that lookup to say which other key exists. A transport whose name
// is not a catalog entry (a custom endpoint) simply finds nothing and
// gets today's sentence unchanged.
this.provider.name
);
let parsedErrorBody: any;
try {
parsedErrorBody = JSON.parse(errorText);
} catch {
parsedErrorBody = undefined;
}
const providerMsg = extractProviderMessage(parsedErrorBody ?? errorText);
// Richer stderr line: provider + status + hint + the real upstream message,
// so the cause is findable in scrollback even when Claude Code only shows
// its own "API error · Retrying" banner.
//
// "One tidy line" used to be bounded by LENGTH alone, which is a different
// promise: `extractProviderMessage` returns a non-JSON body verbatim, and a
// provider may answer an error as an SSE frame rather than a document —
// Alibaba Model Studio answers a denied model with `event:error\ndata:{…}`.
// 200 characters of that is still three lines, and three lines written into
// a terminal a TUI is painting tears the frame. Collapsing whitespace FIRST
// is what makes the sentence true; the slice then bounds what is already
// one line.
const oneLineMsg = providerMsg.replace(/\s+/g, " ").trim();
const msgTail = oneLineMsg
? ` (${oneLineMsg.length > 200 ? `${oneLineMsg.slice(0, 200)}…` : oneLineMsg})`
: "";
logStderr(
`Error [${this.provider.displayName}]: HTTP ${response.status}. ${hint}${msgTail}`
);
// Extract structured error type from provider response body if present
let providerErrorType: string | undefined;
try {
const parsed = JSON.parse(errorText);
providerErrorType = parsed?.error?.type || parsed?.type || parsed?.code || undefined;
// Only keep short, clearly-typed values (not freeform messages)
if (typeof providerErrorType === "string" && providerErrorType.length > 50) {
providerErrorType = undefined;
}
} catch {
// Not JSON — no structured error type available
}
reportError({
error: new Error(errorText),
providerName: this.provider.name,
providerDisplayName: this.provider.displayName,
streamFormat: this.provider.streamFormat,
modelId: this.targetModel,
httpStatus: response.status,
isStreaming: false,
retryAttempted: false,
isInteractive: this.isInteractive,
providerErrorType,
});
try {
const { error_class, error_code } = classifyError(
new Error(errorText),
response.status,
errorText
);
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - startTime),
success: false,
http_status: response.status,
error_class,
error_code,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(recoveryTally),
});
} catch {
// Stats must never crash claudish
}
// Reuse the body parsed above (avoid double-JSON-encoding — errorText is
// already JSON when parseable).
const errorBody: any = parsedErrorBody ?? {
error: { type: "api_error", message: errorText },
};
// Terminal errors (auth / quota / billing / model-unsupported) won't
// resolve on retry. Leaving a retryable status (429/5xx) makes Claude
// Code silently retry, showing only "API error · Retrying · attempt N/10"
// and hiding the real reason. Remap terminal errors to 400
// (invalid_request_error) — a status Claude Code surfaces verbatim — and
// attach a rich message (provider + status + hint + upstream message) so
// the user sees WHY it failed, right in the chat.
if (
isTerminalError(response.status, errorText, transportTerminal ?? isTerminal429(errorText))
) {
const surfaced = buildSurfacedErrorMessage({
providerDisplayName: this.provider.displayName,
status: response.status,
hint,
providerMessage: providerMsg,
// The one phrase an Anthropic client recognises for an oversized
// prompt. Providers state the same fact in their own words, which
// no client matches — see CONTEXT_OVERFLOW_PHRASE.
leadPhrase: isContextOverflowError(response.status, errorText)
? CONTEXT_OVERFLOW_PHRASE
: undefined,
});
// A SUBSCRIPTION's rejected credential carries the terminal verdict
// (`auth-failure.ts`): an explicit spec stops with the login hint, and
// a routing chain moves to its next hop with a notice naming that
// hop's billing (`FallbackHandler`). A spent allowance (402/429) is
// not a credential failure and advances with its own warning.
// A model the provider does not carry (Zen Go's 401 "Model <id> is not
// supported") is NOT a credential rejection and keeps advancing.
const verdictHeaders =
isSubscriptionProvider(this.provider.name) &&
isCredentialRejection(response.status, errorText)
? authVerdictHeaders("terminal")
: undefined;
// Carry the ORIGINAL upstream status as a structured field so
// machine consumers (probe classification) can tell a remapped
// auth failure from a genuine 400.
return c.json(
wrapAnthropicError(
400,
surfaced,
"invalid_request_error",
response.status,
// The upstream's own sentence, kept whole and separate. `surfaced`
// leads with claudish's hint, which is correct for Claude Code and
// useless to a probe row that clips.
providerMsg
),
400 as any,
verdictHeaders
);
}
return c.json(
ensureAnthropicErrorFormat(response.status, errorBody),
response.status as any
);
}
}
if (droppedParams.length > 0) {
c.header("X-Dropped-Params", droppedParams.join(", "));
}
// 7b. Codex-class backends report capacity faults INSIDE a 200 stream, past
// every status-code retry hook (see stream-head-sniffer.ts). Peek at the head
// while the status is still ours to choose: retry transient faults, and only
// when all of them fail hand back a 503 the client will retry itself. Without
// this, `server_is_overloaded` became an assistant text block with
// stop_reason end_turn — a retryable failure frozen into the transcript.
// The stall guard's zero: when the response the parser will read had its
// headers. Stamped here (a 200 reaches this line the moment its fetch
// resolved) and again by each 7b re-issue, so the sniff window counts
// against the guard rather than adding to it.
let responseHeadersAt = Date.now();
if (this.resolveStreamFormat() === "openai-responses-sse") {
const settled = await this.settleResponsesStreamHead(
response,
async () => {
const next = await (this.provider.enqueueRequest ? enqueue(doFetch) : doFetch());
responseHeadersAt = Date.now();
return next;
},
// Ends the backoff wait when an internal call's deadline passes.
callSignal
);
if (callAborted(c)) {
if (settled.kind === "ok") await settled.response.body?.cancel().catch(() => {});
return this.respondCallAborted(startTime, fallbackMeta);
}
if (settled.kind === "exhausted") {
const waited = STREAM_RETRY_DELAYS_MS.slice(0, settled.attempts).reduce(
(sum, ms) => sum + ms,
0
);
// The upstream's own text, before it reaches any body sent to Claude
// Code: an error frame can echo the credential this request signed with.
const upstreamCode = redactForClient(settled.code);
const upstreamMessage = redactForClient(settled.message);
const surfaced =
`${this.provider.displayName} is overloaded upstream (${upstreamCode}): ${upstreamMessage} ` +
`claudish retried ${settled.attempts}× over ${Math.round(waited / 1000)}s without success.`;
logStderr(`Error: ${surfaced}`);
try {
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - startTime),
success: false,
http_status: 503,
error_class: "server_error",
error_code: upstreamCode,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(recoveryTally),
});
} catch {
// Stats must never crash claudish
}
// `upstreamMessage` is the upstream's own text; `surfaced` wraps it in
// claudish's retry narration. Both travel, so a probe row can lead with
// the provider's words.
return c.json(
wrapAnthropicError(503, surfaced, "overloaded_error", undefined, upstreamMessage),
503 as any,
settled.unreachable ? connectionFaultHeaders() : undefined
);
}
response = settled.response;
}
// 7c. Devin has the same shape of fault in a different encoding: the
// Connect transport returns 200 and the error rides a `flags=2` frame. Same
// doctrine as 7b — retry the transient class, and surface the terminal class
// as a 400 rendered inline rather than a status Claude Code silently retries.
if (this.resolveStreamFormat() === "connect-proto") {
const settled = await this.settleDevinStreamHead(response, () =>
this.provider.enqueueRequest ? enqueue(doFetch) : doFetch()
);
if (callAborted(c)) {
if (settled.kind === "ok") await settled.response.body?.cancel().catch(() => {});
return this.respondCallAborted(startTime, fallbackMeta);
}
if (settled.kind !== "ok") {
const isTerminal = settled.kind === "terminal";
const httpStatus = isTerminal ? 400 : 503;
// Redacted before any body, log line or report is composed from it.
const upstreamCode = redactForClient(settled.code);
const upstreamMessage = redactForClient(settled.message);
const surfaced = isTerminal
? `${this.provider.displayName} rejected the request (${upstreamCode}): ${upstreamMessage}`
: `${this.provider.displayName} is overloaded upstream (${upstreamCode}): ${upstreamMessage} ` +
`claudish retried ${settled.attempts}× over ` +
`${Math.round(
STREAM_RETRY_DELAYS_MS.slice(0, settled.attempts).reduce((sum, ms) => sum + ms, 0) /
1000
)}s without success.`;
logStderr(`Error: ${surfaced}`);
reportError({
error: new Error(upstreamMessage),
providerName: this.provider.name,
providerDisplayName: this.provider.displayName,
streamFormat: this.provider.streamFormat,
modelId: this.targetModel,
httpStatus,
isStreaming: true,
retryAttempted: !isTerminal,
isInteractive: this.isInteractive,
providerErrorType: upstreamCode,
});
try {
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: Math.round(performance.now() - startTime),
success: false,
http_status: httpStatus,
error_class: isTerminal ? "client_error" : "server_error",
error_code: upstreamCode,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(recoveryTally),
});
} catch {
// Stats must never crash claudish
}
return isTerminal
? c.json(
wrapAnthropicError(
400,
surfaced,
"invalid_request_error",
undefined,
upstreamMessage
),
400 as any
)
: c.json(
wrapAnthropicError(503, surfaced, "overloaded_error", undefined, upstreamMessage),
503 as any,
settled.kind === "exhausted" && settled.unreachable
? connectionFaultHeaders()
: undefined
);
}
response = settled.response;
}
// 8. Parse streaming response based on provider's format
// latency_ms = time-to-first-byte (response received before stream consumed).
// When 7b retried a transient in-stream fault this also covers the backoff
// waits — that is deliberate: the honest figure is time-to-USABLE-response,
// and a turn that silently cost 48s of retries should not report 2s.
latencyMs = Math.round(performance.now() - startTime);
const httpStatus = response.status;
// Harvest plan usage from the response we just received. Placed here, after
// retries and the 7b stream sniff have settled on a final response, so a
// retried turn reports the headers of the attempt that actually succeeded.
this.capturePlanUsage(response);
// 9. Record stats AFTER stream completes (tokens are populated by onTokenUpdate during streaming).
// Pass an onComplete callback into handleStream; it fires at the end of the stream after
// onTokenUpdate, so token counts are available.
// fallbackMeta was captured at the top of handle() and is available via closure.
// Terminal errors that ride an HTTP 200 stream (e.g. the Responses backend's
// `context_length_exceeded`) are invisible to the status code. The stream
// parser reports them via onApiError; capture it here so the turn is recorded
// as a failure, not a success. Per-request local — safe under concurrency.
let streamApiError: { code: string; message: string } | null = null;
// Set when Claude Code cancels the response body. A parser's cancelled
// finalize still reports usage the provider had sent (what was billed is
// billed), which fires onStreamComplete; this keeps that record from
// reading as a completed turn. Per-request local, like streamApiError.
let clientCancelled = false;
// Legs 2..n of a Responses turn: a degenerate `parallel` wrapper is retried
// inside the same downstream message (responses-turn.ts). Built from THIS
// request's header builder, body and transport hooks, so a leg is the
// primary fetch again, with its own ceiling and the turn's abort signal.
// Per-request locals — safe under concurrency on a shared handler.
let legRetries = 0;
let responsesTurn: ResponsesTurnWiring | undefined;
if (this.resolveStreamFormat() === "openai-responses-sse") {
// Each leg is bound like the primary fetch: the issuer re-runs
// `refreshAuth`, refuses a binding whose arm or account differs from the
// turn's ("Codex sign-in changed during the turn"), and signs the leg
// with the binding it just checked. A transport that returns no binding
// keeps the no-binding path, which is exactly the primary fetch's.
// biome-ignore lint/suspicious/noConfusingVoidType: refreshAuth() and forceRefreshAuth() resolve to `AuthBinding | void`
const toLegBinding = (b: AuthBinding | void): LegBinding | undefined =>
b ? { auth: b.auth, accountKey: accountKeyFromBinding(b) } : undefined;
let legBinding = toLegBinding(binding);
const refreshAuth = this.provider.refreshAuth?.bind(this.provider);
// Same gate as the primary 401 branch; the arm cannot change mid-turn
// (the issuer refuses a leg on another arm), so it is decided once here.
const forceRefreshAuth =
binding === undefined || binding.auth?.arm === "oauth"
? this.provider.forceRefreshAuth?.bind(this.provider)
: undefined;
const issueLeg = createLegIssuer<LegBinding>({
providerDisplayName: this.provider.displayName,
getBinding: () => legBinding,
setBinding: (b) => {
legBinding = b;
},
refreshAuth: refreshAuth ? async () => toLegBinding(await refreshAuth()) : undefined,
forceRefreshAuth: forceRefreshAuth
? async () => toLegBinding(await forceRefreshAuth())
: undefined,
getEndpoint: (b) => this.provider.getEndpoint(this.targetModel, b),
fetchHeaders: (b) => fetchHeaders(b),
// `requestPayload` as it stands now: parameter recovery may have
// dropped fields, and a leg re-sends the body that was accepted.
serializeBody: (body) => {
const b = body ?? requestPayload;
const s = this.provider.serializeBody?.(b);
return {
body: s?.body ?? JSON.stringify(b),
contentType: s?.contentType ?? "application/json",
};
},
getRequestInit: () => (this.provider.getRequestInit?.() || {}) as Record<string, unknown>,
enqueueRequest: this.provider.enqueueRequest
? (fn, o) => this.provider.enqueueRequest!(fn, o)
: undefined,
settleStreamHead: (res, reissue, signal) =>
this.settleResponsesStreamHead(res, reissue, signal),
legDeadlineAt: () => recoveryClock().now() + resolveTier1DeadlineMs(),
});
responsesTurn = {
retry: {
// A leg composes its turn signal with an internal call's deadline,
// and the issuer returns `aborted` before it starts once either fired.
issueLeg: callSignal
? (body, turnSignal) => issueLeg(body, AbortSignal.any([turnSignal, callSignal]))
: issueLeg,
// Default scope: `openai-codex` on the subscription arm, the only
// backend the stall data comes from; CLAUDISH_RESPONSES_STALL_MS
// overrides it everywhere.
stall: resolveStallPolicy({
env: process.env,
providerName: this.provider.name,
arm: binding?.auth?.arm,
}),
firstHeadersAt: responseHeadersAt,
// A code-mode continuation leg appends to the body that was accepted.
primaryBody: () => requestPayload,
},
onTurnSummary: (s) => {
legRetries = s.legRetries;
},
// Code mode (decided at 5d): exec calls run in the sandbox and their
// batches are relayed as tool_use blocks; `codeModeShape` is read at
// exec time because the lite → classic fallback may have changed it.
codeMode: codeModeTurn
? createCodeModeTurnHooks({
stores: getCodeModeStores(),
accountKey: codeModeTurn.accountKey,
sessionKey: codeModeTurn.sessionKey,
shape: () => codeModeShape ?? "classic",
names: codeModeTurn.names,
allTools: codeModeTurn.allTools,
defaultMaxOutputTokens: codeModeTurn.defaultMaxOutputTokens,
// The last user/assistant message, as the input builder reads
// the message before a text-only answer (a trailing system
// message would anchor the turn record where no render looks).
previousMessage: conversationMessages(claudeRequest?.messages).at(-1),
})
: undefined,
};
}
const onStreamComplete = () => {
try {
const isFreeModel = this.tokenTracker.getTotalCost() === 0;
this.emitStats({
model_id: this.targetModel,
provider_name: this.provider.name,
stream_format: this.provider.streamFormat,
latency_ms: latencyMs,
success: streamApiError === null && !clientCancelled,
http_status: httpStatus,
// A turn the client abandoned is not a completed one; the existing
// error pair marks it, so no new StatsEvent field is needed.
...(clientCancelled ? { error_class: "cancelled", error_code: "client_cancelled" } : {}),
input_tokens: this.tokenTracker.getInputTokens(),
output_tokens: this.tokenTracker.getOutputTokens(),
estimated_cost: this.tokenTracker.getTotalCost(),
is_free_model: isFreeModel,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
invocation_mode: this.options.invocationMode ?? "auto-route",
...this.recoveryStats(recoveryTally),
// Absent on a turn that needed no retry, like the recovery fields.
...(legRetries > 0 ? { leg_retries: legRetries } : {}),
});
} catch {
// Stats must never crash claudish
}
try {
// Hook telemetry's turn denominator. getInputTokens() is the FULL
// conversation context for this request (assignment, not accumulation
// — see the context-tracking note in CLAUDE.md), which is exactly the
// figure the context bucket wants. No-op unless behaviour telemetry is
// opted in.
hookScope?.noteTurnComplete(this.tokenTracker.getInputTokens());
} catch {
// Telemetry must never crash claudish
}
};
const streamed = notifyOnDownstreamCancel(
this.handleStream(
c,
response,
adapter,
claudeRequest,
// Decided from the binding this request was finally signed with (a 401
// re-sign replaced it above); every leg of a Responses turn signs on
// that same arm, or the leg issuer refuses it.
this.signedBilling(binding),
toolNameMap,
onStreamComplete,
(code, message) => {
streamApiError = { code, message };
},
hookScope?.raw.streamTap(),
responsesTurn
),
() => {
clientCancelled = true;
}
);
// A client that did not ask for a stream gets the single JSON message the
// Messages API defines, not SSE. `=== true` rather than `!== false` because
// the API treats an absent `stream` as false, and NativeHandler already
// behaves that way — it forwards the payload verbatim and Anthropic decides
// — so anything looser would leave proxied models disagreeing with native
// ones, which is the bug being fixed. Claudish's own internal callers
// (mcp-server.ts:235, probe-live.ts:139) both send `stream: true`
// explicitly, so this changes nothing for them.
if (payload?.stream === true) return streamed;
return sseResponseToJson(streamed, this.bareModelName);
}
/**
* Settle a Responses-format stream head: retry transient upstream faults that
* arrive inside an HTTP 200 body, before any of it reaches the client.
*
* Backoff is progressive (3s → 15s → 30s). The Codex outage this was built for
* ran ~6.5 minutes, so tight retries would only have burned attempts; the long
* tail is where recovery actually happens.
*
* Returns `exhausted` when every attempt failed — the caller turns that into a
* 503. For a pinned `provider@model` there is no FallbackHandler, so the 503
* reaches Claude Code, which runs its own retry loop against the same model.
* Inside a bare-name chain, fallback-handler's isRetryableError advances on it
* to the next candidate: this provider stayed overloaded through every retry.
*/
private async settleResponsesStreamHead(
initial: Response,
reissue: () => Promise<Response>,
/** A retry leg's turn signal: an abort ends the backoff wait at once. */
signal?: AbortSignal
): Promise<
| { kind: "ok"; response: Response }
| { kind: "exhausted"; code: string; message: string; attempts: number; unreachable?: true }
> {
let response = initial;
for (let attempt = 0; ; attempt++) {
const verdict = await sniffResponsesStreamHead(response, { log });
if (verdict.kind === "clean") return { kind: "ok", response: verdict.response };
const delayMs = STREAM_RETRY_DELAYS_MS[attempt];
if (delayMs === undefined) {
log(
`[${this.provider.displayName}] in-stream ${verdict.code} persisted after ` +
`${attempt} retries — surfacing 503 so the client can retry`
);
return {
kind: "exhausted",
code: verdict.code,
message: verdict.message,
attempts: attempt,
};
}
log(
`[${this.provider.displayName}] in-stream ${verdict.code} before any output — ` +
`retry ${attempt + 1}/${STREAM_RETRY_DELAYS_MS.length} in ${delayMs / 1000}s`
);
if (await sleepUnlessAborted(delayMs, signal)) {
return { kind: "exhausted", code: verdict.code, message: "aborted", attempts: attempt };
}
let next: Response;
try {
next = await reissue();
} catch (error) {
log(`[${this.provider.displayName}] retry fetch failed: ${error}`);
return {
kind: "exhausted",
code: verdict.code,
message: `${verdict.message} (retry could not reach the provider: ${error})`,
attempts: attempt + 1,
// A connection fault, not the provider's answer. The caller marks the
// 503 with the connection-fault header, so a routing chain HOLDS here
// instead of advancing onto the next (possibly metered) candidate.
unreachable: true,
};
}
// The fault graduated to a status-level failure. The !response.ok handling
// is already behind us, so stop here rather than re-entering it.
if (!next.ok) {
const body = redactForClient(await next.text().catch(() => ""));
log(`[${this.provider.displayName}] retry returned HTTP ${next.status}`);
return {
kind: "exhausted",
code: `http_${next.status}`,
message: body.slice(0, 500) || `HTTP ${next.status}`,
attempts: attempt + 1,
};
}
response = next;
}
}
/**
* Settle a Devin Connect stream head — the `connect-proto` twin of
* {@link settleResponsesStreamHead}, sharing its backoff schedule.
*
* It differs in one way, and the difference is the point: the sniffer
* distinguishes TERMINAL faults from transient ones, so an unserved model uid
* or a revoked entitlement is answered immediately with the real reason
* instead of burning 48s of backoff first. Only the transient class is
* retried; only an exhausted retry chain becomes a 503.
*
* Terminal messages pass through the transport's rewrite when it offers one.
* That rewrite checks the dynamic models catalog, which is what turns an
* opaque backend string into "that uid is not served by your subscription;
* here is what is".
*/
private async settleDevinStreamHead(
initial: Response,
reissue: () => Promise<Response>
): Promise<
| { kind: "ok"; response: Response }
| { kind: "terminal"; code: string; message: string }
| { kind: "exhausted"; code: string; message: string; attempts: number; unreachable?: true }
> {
// Optional-method probe rather than a `ProviderTransport` member: this whole
// branch is Devin-specific by construction, and widening the shared
// interface for one consumer would invite the next provider to add another.
const rewrite = (
this.provider as { rewriteInStreamError?: (code: string, message: string) => string }
).rewriteInStreamError?.bind(this.provider);
let response = initial;
for (let attempt = 0; ; attempt++) {
const verdict = await sniffDevinStreamHead(response, { log });
if (verdict.kind === "clean") return { kind: "ok", response: verdict.response };
if (verdict.kind === "terminal") {
const message = rewrite?.(verdict.code, verdict.message) ?? verdict.message;
log(`[${this.provider.displayName}] terminal in-stream error ${verdict.code}`);
return { kind: "terminal", code: verdict.code, message };
}
const delayMs = STREAM_RETRY_DELAYS_MS[attempt];
if (delayMs === undefined) {
log(
`[${this.provider.displayName}] in-stream ${verdict.code} persisted after ` +
`${attempt} retries — surfacing 503 so the client can retry`
);
return {
kind: "exhausted",
code: verdict.code,
message: verdict.message,
attempts: attempt,
};
}
log(
`[${this.provider.displayName}] in-stream ${verdict.code} before any output — ` +
`retry ${attempt + 1}/${STREAM_RETRY_DELAYS_MS.length} in ${delayMs / 1000}s`
);
await new Promise((resolve) => setTimeout(resolve, delayMs));
let next: Response;
try {
next = await reissue();
} catch (error) {
log(`[${this.provider.displayName}] retry fetch failed: ${error}`);
return {
kind: "exhausted",
code: verdict.code,
message: `${verdict.message} (retry could not reach the provider: ${error})`,
attempts: attempt + 1,
// A connection fault, not the provider's answer. The caller marks the
// 503 with the connection-fault header, so a routing chain HOLDS here
// instead of advancing onto the next (possibly metered) candidate.
unreachable: true,
};
}
// The fault graduated to a status-level failure. The !response.ok handling
// is already behind us, so stop here rather than re-entering it.
if (!next.ok) {
const body = redactForClient(await next.text().catch(() => ""));
log(`[${this.provider.displayName}] retry returned HTTP ${next.status}`);
return {
kind: "exhausted",
code: `http_${next.status}`,
message: body.slice(0, 500) || `HTTP ${next.status}`,
attempts: attempt + 1,
};
}
response = next;
}
}
/**
* Resolve which stream parser this request's bytes should go to.
*
* Priority:
* 1. Transport override (aggregators like LiteLLM/OpenRouter normalize server-side)
* 2. Explicit format adapter (provider profile passes it, e.g. AnthropicAPIFormat
* for Z.AI, CodexAPIFormat for OpenAI Codex) — this is the layer that KNOWS
* the wire protocol.
* 3. Model dialect — only reached if no explicit adapter was passed. Dialects like
* GLMModelDialect/GrokModelDialect handle model quirks (context window, thinking
* block stripping), NOT wire format. Their inherited default "openai-sse" must
* NOT override the explicit adapter — that was #102.
*
* Previous ordering (pre-fix) put modelAdapter at tier 2, causing GLMModelDialect's
* inherited "openai-sse" to silently override AnthropicAPIFormat's "anthropic-sse"
* for zai@glm-* — the Anthropic SSE was then fed to the OpenAI parser and dropped.
*
* Resolved in one place because handle() needs it BEFORE handleStream() runs, to
* decide whether the response head is worth sniffing for retryable errors.
*/
/**
* Introspection seam — the three facts that define this handler's composition,
* without going through a live request.
*
* Exists because a mis-composed handler is invisible until it hits the wire: the
* Zen Go MiniMax bug shipped an Anthropic format+transport pointed at an
* `/v1/chat/completions` endpoint, and that pairing was only observable as a 400
* from the upstream vendor. `endpoint` is included precisely because the failure
* was a format/endpoint MISMATCH — neither field alone would have caught it.
*/
describeComposition(): { transport: string; streamFormat: string; endpoint: string } {
return {
transport: this.provider.name,
streamFormat: this.resolveStreamFormat(),
endpoint: this.provider.getEndpoint(this.bareModelName),
};
}
private resolveStreamFormat(): string {
return (
this.provider.overrideStreamFormat?.() ??
this.explicitAdapter?.getStreamFormat() ??
this.modelAdapter?.getStreamFormat() ??
this.getAdapter().getStreamFormat()
);
}
private handleStream(
c: Context,
response: Response,
adapter: BaseModelAdapter,
claudeRequest: any,
billing: RequestBilling,
toolNameMap?: Map<string, string>,
onComplete?: () => void,
onApiError?: (code: string, message: string) => void,
/** The raw `providerChunk`/`providerStreamEnd` tap for this stream, when one applies. */
raw?: RawStreamTap,
responsesTurn?: ResponsesTurnWiring
): Response {
// Local mutable copy so we can null it out after firing (prevents double-firing)
// without reassigning the function parameter.
let pendingOnComplete = onComplete;
// `input` is the FULL context size, always — never the cache-reduced figure
// that rides on the wire. `detail` is the optional cached breakdown of that
// same number and is used for COST ONLY; see UsageCacheDetail and
// `context-window.md`, which records what happens when a reduced count
// reaches the context accounting (auto-compaction silently disarms).
//
// `billing` is THIS request's signing decision, passed into every cost
// update rather than read from the tracker's pricing lookup, whose
// credential-decided answer is the process-wide last-signed arm.
const onTokenUpdate = (input: number, output: number, detail?: UsageCacheDetail) => {
const strategy = this.options.tokenStrategy || "standard";
switch (strategy) {
case "accumulate-both":
this.tokenTracker.accumulateBoth(input, output, detail, billing);
break;
case "delta-aware":
this.tokenTracker.updateWithDelta(input, output, detail, billing);
break;
case "local":
this.tokenTracker.updateLocal(input, output, detail);
break;
default:
this.tokenTracker.update(input, output, detail, billing);
break;
}
// Fire onComplete after token update so recordStats() sees the final token counts.
if (pendingOnComplete) {
try {
pendingOnComplete();
} catch {
// Stats must never crash claudish
}
// Prevent double-firing if onTokenUpdate is called more than once
pendingOnComplete = undefined;
}
};
const streamFormat = this.resolveStreamFormat();
// Stream parsers receive bareModelName: it is the value echoed in
// `message_start.message.model` for display. Passing the routed form here was the
// latent second part of #102 — the parameter was named `modelName` but received
// the full routed string.
// Seed for message_start.usage — the previous request's context size. A
// parser cannot know the real count until the stream ends, and Claude Code
// keeps whatever message_start carried whenever the closing delta omits it.
const priorInputTokens = this.tokenTracker.getLastInputTokens();
/**
* The ONE place a completed tool call is observed. Tool counting feeds the
* end-of-session summary, which must work for every model on every wire, so
* every parser below gets it unconditionally.
*
* The parsers carry no tool buffering, argument repair or output
* observation: tool interception is the hook response seam's job, above
* every parser (`hooks/response-seam.ts`).
*/
const observeToolCall = (name: string): void => {
this.tokenTracker.recordToolUse(name);
};
switch (streamFormat) {
case "openai-sse":
return createStreamingResponseHandler(
c,
response,
adapter,
this.bareModelName,
raw,
onTokenUpdate,
claudeRequest.tools,
toolNameMap,
priorInputTokens,
// Always pass the options object: without it `onToolCallObserved` is not
// installed on the busiest wire in claudish (GLM, Kimi, Grok, DeepSeek,
// Qwen, OpenRouter, LiteLLM).
{ onToolCallObserved: observeToolCall }
);
case "openai-responses-sse":
return createResponsesStreamHandler(c, response, {
modelName: this.bareModelName,
onTokenUpdate,
// The map THIS request captured right after prepareRequest — not a
// fresh read. This runs after an awaited fetch, and on a handler
// shared by two conversations the adapter's own map may already
// belong to the next request by now.
toolNameMap,
// Claude Code's own tool names: a function_call named `parallel` is the
// parallel wrapper only when none of these is called that.
declaredToolNames: Array.isArray(claudeRequest?.tools)
? claudeRequest.tools
.map((t: { name?: unknown } | null) => t?.name)
.filter((n: unknown): n is string => typeof n === "string")
: [],
contextWindow: lookupModelForProvider(this.bareModelName, this.provider.name),
onApiError,
priorInputTokens,
raw,
onToolCallObserved: observeToolCall,
retry: responsesTurn?.retry,
// Earlier legs of a retried turn: cost only, before the stats snapshot
// that onTokenUpdate fires.
onExtraBilledInput: (input, detail) =>
this.tokenTracker.addBilledInputTokens(input, detail, billing),
onTurnSummary: responsesTurn?.onTurnSummary,
codeMode: responsesTurn?.codeMode,
});
case "anthropic-sse":
return createAnthropicPassthroughStream(c, response, {
modelName: this.bareModelName,
onTokenUpdate,
// Layer 2 dialect wins over the Layer 1 converter — the same
// precedence as getModelContextWindow()/getModelSupportsVision().
// This opt is consulted for ONE thing, shouldFilterThinking(), and
// that is a per-MODEL/per-wire fact only the dialect knows. Every
// anthropic-sse provider passes an explicit AnthropicAPIFormat, so
// `adapter` here is always Layer 1 and always answers the base
// default `false` — which silently made the one dialect override of
// it (MiniMaxModelDialect's `true`) unreachable dead code, and would
// do the same to the base's wire-keyed `true` for every other model
// on this wire (qtoken@'s qwen / glm / deepseek models).
adapter: (this.modelAdapter ?? adapter) as BaseAPIFormat,
onToolCallObserved: observeToolCall,
});
case "gemini-sse": {
// Build onToolCall callback to register tool calls + thoughtSignatures on the adapter
const onToolCall = (toolId: string, name: string, thoughtSignature?: string) => {
if (typeof (adapter as any).registerToolCall === "function") {
(adapter as any).registerToolCall(toolId, name, thoughtSignature);
}
};
return createGeminiSseStream(c, response, {
modelName: this.bareModelName,
adapter,
raw,
onTokenUpdate,
onToolCall,
onToolCallObserved: observeToolCall,
unwrapResponse: this.options.unwrapGeminiResponse,
priorInputTokens,
});
}
case "connect-proto":
return createDevinConnectStream(c, response, {
modelName: this.bareModelName,
onTokenUpdate,
priorInputTokens,
onApiError,
toolNameMap,
// The backend reports which uid actually answered (`claude-opus-5`
// resolves to `claude-opus-5-high`), so the status line names the real
// model instead of the family the user typed.
onServedModel: (uid) => {
if (uid !== this.bareModelName) this.tokenTracker.setActiveModelName(uid);
},
onToolCallObserved: observeToolCall,
});
case "ollama-jsonl":
return createOllamaJsonlStream(c, response, {
modelName: this.bareModelName,
onTokenUpdate,
priorInputTokens,
});
default:
throw new Error(`Unknown stream format: ${streamFormat}`);
}
}
/** Expose token tracker for advanced use cases */
getTokenTracker(): TokenTracker {
return this.tokenTracker;
}
/**
* The claudish provider this handler signs for (`provider.name`): the name
* its hop-log entries carry (`recordHopEntry`), so a caller that built the
* handler can map those entries back to its own plan.
*/
getProviderName(): string {
return this.provider.name;
}
/**
* Read plan usage out of a response the session already received.
*
* Synchronous and I/O-free by construction: the headers are in hand, so
* there is nothing to await and nothing to time out. That is what makes this
* safe to call on the response path, unlike the per-request quota fetch it
* replaced. Any throw is swallowed — a usage reading is never worth
* disturbing a turn over.
*/
private capturePlanUsage(response: Response): void {
// The plan reading feeds the main status line; an advisor handler has none.
if (this.options.requestRole === "advisor") return;
try {
const adapter = resolveQuotaAdapter(this.provider.name);
if (!adapter) return;
// Preferred: the numbers rode in on a response we already have.
const plan = adapter.scrape?.(response);
if (plan) {
this.tokenTracker.setPlanUsage(plan);
return;
}
// Otherwise the provider may have a free usage endpoint to poll.
this.maybePollPlanUsage(adapter);
} catch {
// Non-fatal, always.
}
}
/**
* Refresh plan usage from a provider's free usage endpoint.
*
* Fire-and-forget and rate-limited. It is deliberately NOT awaited: the
* whole point of retiring the old step-5b probe was that a turn must never
* wait on a quota reading. The result lands in the tracker whenever it
* arrives and is published by the next token write.
*/
private maybePollPlanUsage(adapter: QuotaAdapter): void {
if (!adapter.poll) return;
const now = Date.now();
if (now - this.lastPlanPollAt < PLAN_POLL_INTERVAL_MS) return;
// Stamped BEFORE the call, not after: concurrent turns on this handler
// would otherwise all see a stale timestamp and stampede the endpoint.
this.lastPlanPollAt = now;
void adapter
.poll({ modelId: this.bareModelName })
.then((plan) => {
if (plan) this.tokenTracker.setPlanUsage(plan);
})
.catch(() => {
// A failed usage reading is not a session problem.
});
}
/**
* Called by FallbackHandler before handle() when this handler is the winning provider
* after one or more failed attempts. Stores fallback metadata for inclusion in stats.
*/
setFallbackMeta(chain: string[], attempts: number): void {
this.pendingFallbackMeta = { chain, attempts };
}
async shutdown(): Promise<void> {
if (this.provider.shutdown) {
await this.provider.shutdown();
}
}
}
/**
* Name the credential that signed THIS request on its response, as
* `x-claudish-signed-with` (URI-encoded: a tier name need not be a valid
* header byte string), for a provider with several login sources (muse@: own
* login, borrowed copy, Keychain). Per response, so `--probe` names the signer
* of its own request and never a process-wide guess.
*
* Set on the returned Response, not through `c.header()`: the Responses stream
* parser builds its own `new Response`, which never sees the context's headers.
* Headers a stream parser built are mutable; a frozen set is copied instead.
*/
function withSignerHeader(response: Response, signer: string | undefined): Response {
if (!signer) return response;
const value = encodeURIComponent(signer);
try {
response.headers.set("x-claudish-signed-with", value);
return response;
} catch {
const headers = new Headers(response.headers);
headers.set("x-claudish-signed-with", value);
return new Response(response.body, {
status: response.status,
statusText: response.statusText,
headers,
});
}
}
/**
* Return a human-readable recovery hint based on HTTP status and error body.
*
* `transportTerminal429` is the transport's own verdict on a 429 when it can
* read its provider's structured errors (see
* `ProviderTransport.classifyTerminalError`). It OVERRIDES the wording
* heuristics below, which are pattern-matching prose and cannot tell a spent
* plan from a per-minute throttle when the provider phrases both identically.
* `undefined` — every transport without the hook — keeps the original behaviour.
*
* `providerUid` is the INTERNAL provider name (`ProviderTransport.name`, e.g.
* `qwen-token-plan`), not the display name, because it is what the provider
* catalog is keyed by. It is optional and every branch below is unchanged
* without it: it only lets the auth branch look up whether this vendor ships a
* SECOND, non-interchangeable key for another tier (`siblingKeyEnvVars`).
* Nothing is inferred from the credential itself — see the branch for why the
* key's own bytes are deliberately not read.
*/
export function getRecoveryHint(
status: number,
errorText: string,
providerName: string,
transportTerminal429?: boolean,
providerUid?: string
): string {
const lower = errorText.toLowerCase();
if (status === 503 || lower.includes("overloaded")) {
return "Provider overloaded. Retry or use a different model.";
}
if (status === 429 && (transportTerminal429 ?? isTerminal429(errorText))) {
// Terminal, but WHICH terminal? "Out of quota — check your plan & billing
// details" tells a flat-rate subscriber their money ran out when the real
// state is a billing cycle that has not reset, sending them to a billing
// page to fix a plan that is working. MiniMax Coding is the measured case:
// `429 "Token Plan usage limit reached: Upgrade your Token Plan or purchase
// Credits for more usage. (2056)"`.
//
// Same predicate the probe's `plan-limit` state uses, so this hint and the
// TUI row cannot disagree about one response — the recurring failure mode
// this file already guards against for auth vs model-unsupported.
if (hasPlanLimitWording(errorText)) {
return "Plan limit reached — your allowance is spent for this cycle and refills on the provider's own schedule (see the message below). Wait, upgrade the plan, or switch provider.";
}
return "Out of quota — check your plan & billing details. This won't recover on retry.";
}
// The transport has positively identified this 429 as transient. Return the
// throttling advice here rather than falling through, because the
// exhaustion-wording branch below would otherwise claim it: Google stamps
// "Resource has been exhausted (e.g. check quota)." on every RESOURCE_EXHAUSTED
// reply, so a per-minute rate limit matches "quota" and gets described as a
// spent subscription allowance that "refills on the provider's own schedule".
if (status === 429 && transportTerminal429 === false) {
return "Rate limited. Wait, reduce concurrency, or check plan limits.";
}
// A spent SUBSCRIPTION allowance also arrives as 429, and the generic
// rate-limit advice below is actively wrong for it: "reduce concurrency" does
// nothing about an allowance that refills on a clock. Zen Go's real body is
// `429 "5-hour usage limit reached. Resets in 3hr 17min"` — the useful reply
// names the plan and the wait, not the request rate.
if (isQuotaExhaustionError(status, errorText)) {
return "Subscription allowance spent — this refills on the provider's own schedule (see the message below). Reducing concurrency won't help; switch model/provider or wait.";
}
if (status === 429 || lower.includes("rate limit")) {
return "Rate limited. Wait, reduce concurrency, or check plan limits.";
}
if (status === 401 || status === 403) {
// Some providers (e.g. OpenCode Zen Go) return 401 for a model they do not
// carry, not for a bad credential. Shared with probe-live's state
// classifier — see shared/model-unsupported.ts for why one predicate rather
// than two: this hint said "model not supported" while the probe state said
// `auth-failed`, so the two surfaces disagreed about the same response.
if (hasModelUnsupportedWording(errorText)) {
return "Model not supported by this provider. Verify model name.";
}
// A plan that has run out is not an auth failure, but some providers report
// it as one — see shared/quota-exhaustion.ts for why this is shared with the
// fallback gate rather than duplicated here.
if (isQuotaExhaustionError(status, errorText)) {
// Kimi's coding plan is exactly this shape: `403 permission_error
// "You've reached your usage limit for this billing cycle"`. It is a spent
// ALLOWANCE arriving on an auth status, so it takes the plan wording, not
// the balance wording — same split as the 429 branch above.
if (hasPlanLimitWording(errorText)) {
return "Plan limit reached — your allowance is spent for this cycle and refills on the provider's own schedule (see the message below). Wait, upgrade the plan, or switch provider.";
}
return "Out of quota — check your plan & billing details. This won't recover on retry.";
}
// The provider already said what to do, and it is not "check your key".
// Measured: Zen Go answers a model the account has not opted into with
// `403 RegionError … requires explicit opt in: <url>`. The route, the
// credential and the model are all fine — so telling the user to audit a
// working credential talks over the fix sitting in the same sentence.
// Checked LAST, so a genuine auth failure that happens to cite a docs link
// still reaches the credential advice above via its own wording.
if (hasActionableLink(errorText)) {
return "Provider rejected the request and gave a specific fix — follow the link in the message below.";
}
// Reached only when the credential really is the most likely cause. For a
// vendor that sells the SAME models under several plans, "check your key"
// is still not the whole story: the plans' keys are isolated and rejected
// by each other's hosts with a near-identical 401, so "right key, wrong
// silo" is at least as likely as "bad key". Measured 2026-09-17 with one
// real Alibaba Token Plan key: 200 on `token-plan…`, 401 `invalid access
// token or token expired` on `coding-intl…`, 401 `Incorrect API key
// provided` on `dashscope-intl…`.
//
// Driven by `siblingKeyEnvVars`, so it is a property of any vendor that
// declares one (`opencode-zen-go` does today) rather than an Alibaba
// special case — and the variable names come from the catalog via
// `describeSiblingKeys`, the same sentence `describeMissingCredential`
// emits, so the two cannot drift into saying different things about one
// pair of keys.
//
// What this deliberately does NOT do is look at the key. A Token Plan key
// can match `sk-sp-`, which Alibaba's own Coding Plan docs call their
// format, so a prefix hint would confidently mislabel a working
// credential. The key's bytes are never read, which also keeps a failed
// secret operation out of a status line.
// "Access denied" for a MODEL is not a credential fault. Alibaba's Model
// Studio answers `403 Model.AccessDenied "Model access denied."` while the
// SAME key lists 169 models on the same host, and it answers that way for
// every model, including ids taken from the account's own list (measured
// 2026-09-19 on dashscope-intl). Sending the reader to check a key that the
// provider just accepted wastes the one clue they have: the account, not the
// credential, is what lacks access.
if (status === 403 && /access denied|accessdenied/i.test(lower)) {
return "The provider accepted the credential but denied access to this model — check model access or activation for this account in the provider's console, not the key.";
}
// A SUBSCRIPTION that signs with claudish's own login: the rejected
// credential is that login, so the fix is a new login, not a key audit.
// Only providers that declare `oauthLoginSlug` get the command (muse@,
// kc@, gk@, Antigravity); a subscription signed by a key or by another
// CLI's login (Devin, the Alibaba plans) keeps the generic advice below.
// `openai-codex` is not in SUBSCRIPTION_PROVIDERS (its arm is decided by
// the credential that signed), so a metered cx@ key is never told to log in.
const loginSlug = providerUid ? getProviderByName(providerUid)?.oauthLoginSlug : undefined;
if (
loginSlug &&
providerUid &&
isSubscriptionProvider(providerUid) &&
isCredentialRejection(status, errorText)
) {
return `The ${providerName} login was rejected (HTTP ${status}). Run \`claudish login ${loginSlug}\` to sign in again.`;
}
const siblingNote = providerUid ? describeSiblingKeys(getProviderByName(providerUid)) : "";
if (siblingNote) {
return `Check API key / OAuth credentials. This vendor sells several plans whose keys are isolated, so a ${status} can also mean the right key on the wrong plan's host.${siblingNote}`;
}
return "Check API key / OAuth credentials.";
}
if (status === 404) {
return "Verify model name is correct.";
}
if (status === 400) {
if (lower.includes("unsupported content type") || lower.includes("unsupported_content_type")) {
return "Model doesn't support this content format. Try a different model.";
}
// Read the provider's own attribution BEFORE guessing from prose. The size
// test below is a substring match on "token", and OpenAI's parameter NAMES
// contain that word — `max_output_tokens`, `max_completion_tokens` — so a
// parameter-shape rejection matched it and was reported as a size problem.
// Measured against `oai@gpt-6-astra`, 6.7 KB of input against a 1.05M
// window:
//
// 400 unknown_parameter — "Unknown parameter: 'max_output_tokens'."
// rendered as → "Input too large. Reduce message history or use a
// larger-context model."
//
// The hint and the body it quotes then disagreed inside one line, and the
// advice sent the reader to shrink a prompt that was never the problem.
if (isRequestShapeError(errorText)) {
return "Wrong request shape for this endpoint — the provider named the parameter it rejected (see the message below). Nothing was too large; a shorter prompt will not help.";
}
// A model the provider does not carry also arrives as a 400 — Alibaba's
// silos answer an id outside the plan with a bare `Model not exist`. Same
// predicate the 401/403 branch above uses, for the same reason it exists:
// one reading of "the MODEL is the problem", so the hint cannot say
// something different depending on which status the provider chose.
//
// Placed AFTER `isRequestShapeError` (a provider that names a parameter has
// stated the fact, and a heuristic must not talk over it) and BEFORE the
// size test, which is a bare `includes("token")` and would otherwise claim
// any model-unsupported body that happens to spell "tokens".
if (hasModelUnsupportedWording(errorText)) {
return "Model not supported by this provider. Verify model name.";
}
if (lower.includes("context") || lower.includes("too long") || lower.includes("token")) {
return "Input too large. Reduce message history or use a larger-context model.";
}
return "Request format may be incompatible with provider.";
}
// 413 is "Payload Too Large" by definition, and until now fell through to
// "Unexpected HTTP 413 from <provider>" — a status name where the actionable
// advice already exists three lines above. Gated on the narrow predicate, so a
// 413 about something other than the prompt keeps the generic line.
if (isContextOverflowError(status, errorText)) {
return "Input too large. Reduce message history or use a larger-context model.";
}
if (status >= 500) {
return "Server error — retry after a brief wait.";
}
return `Unexpected HTTP ${status} from ${providerName}.`;
}