Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Durable capture of upstream error bodies.
*
* A non-ok upstream response short-circuits before the stream parser, so
* `response-capture` never sees it. The body is read once in ComposedHandler,
* handed to the classifier, and then dropped:
*
* const errorText = await response.text();
* log(`[${this.provider.displayName}] Error: ${errorText}`);
*
* `log()` persists nothing unless `--debug` set a log file, so on a normal run
* that body is gone the instant it has been classified. That is the one piece
* of evidence that distinguishes a rate limit you should retry from a hard
* quota wall you should not, and by the time anyone wants to look at it there
* is nothing to look at.
*
* Reported by @jsboige in #184, from a real incident: a GLM coding-plan 5h cap
* saturated, the shape was reconstructable from request counts, and the literal
* 429 body was unrecoverable.
*
* Opt-in, because this writes provider error text — which can carry account
* identifiers — to a path the user names. Off by default, no directory is ever
* created, and nothing here can throw into the request path.
*/
import { appendFileSync } from "node:fs";
import { redactSecrets } from "../../redact.js";
/** Env var naming the capture file. Unset = feature off. */
export const UPSTREAM_ERROR_LOG_ENV = "CLAUDISH_UPSTREAM_ERROR_LOG";
/**
* Bytes of upstream body kept per record.
*
* An error body is normally a short JSON object, but a misconfigured gateway
* can return a full HTML page, and this file is appended to on every failure.
* 2KB keeps the useful head of any real error while bounding a pathological
* one. Truncation is marked so a reader never mistakes a cut body for the
* whole of it.
*/
export const MAX_CAPTURED_BODY_BYTES = 2048;
export interface UpstreamErrorRecord {
provider: string;
model: string;
status: number;
body: string;
/** ISO timestamp; injectable so tests need no clock control. */
at?: string;
}
/**
* Append one JSON line describing a failed upstream response.
*
* Returns true when a record was written, false when the feature is off or the
* write failed. The boolean is for tests and callers that want to log their own
* diagnostic — nothing in the request path should branch on it.
*
* NEVER THROWS. A capture facility that can break a request is worse than no
* capture facility, and this runs on the error path, where the process is
* already handling something going wrong.
*/
export function captureUpstreamError(record: UpstreamErrorRecord): boolean {
const path = process.env[UPSTREAM_ERROR_LOG_ENV];
if (!path) return false;
try {
// Redacted BEFORE truncation, and before the bytes hit disk.
//
// A 401/403 body routinely echoes the credential that failed, and this file
// is no longer only a path a user opted into: MCP sessions now point
// every child at `<sessionDir>/upstream-errors.jsonl` and `get_diagnostics`
// hands its contents to an agent. Redacting at write time is the only point
// that covers every reader — the same rule and the same reason as team's
// error log (team-orchestrator.ts:1070) and an MCP session's `events.jsonl`.
//
// Before truncation specifically, so the cut cannot fall inside a key and
// leave a usable prefix of it in the file.
const raw = redactSecrets(record.body ?? "");
const truncated = raw.length > MAX_CAPTURED_BODY_BYTES;
const line = JSON.stringify({
at: record.at ?? new Date().toISOString(),
provider: record.provider,
model: record.model,
status: record.status,
body: truncated ? raw.slice(0, MAX_CAPTURED_BODY_BYTES) : raw,
// Present only when it happened, so a reader who does not see the key can
// trust the body is complete.
...(truncated ? { truncated: true, original_bytes: raw.length } : {}),
});
appendFileSync(path, `${line}\n`);
return true;
} catch {
// Unwritable path, full disk, permissions — all of which mean the user does
// not get their capture, and none of which mean the request should fail.
return false;
}
}