@tensorcost/sdk 1.4.0 → 1.5.0

package/dist/proxy-client.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Applied-mode proxy HTTP client.
+ *
+ * This is the single place that combines retries, timeouts, typed errors,
+ * telemetry hooks, and the fail-open circuit breaker. The provider wrappers
+ * (openai.ts, anthropic.ts) call `proxyRequest()` instead of hitting the
+ * proxy directly.
+ *
+ * The contract:
+ *   - Returns the parsed response body on success.
+ *   - On all non-success outcomes, throws a subclass of TensorCostError.
+ *   - Never swallows errors — the provider wrapper's fail-open logic
+ *     (fall back to direct call on proxy failure) lives in the provider
+ *     wrapper, not here.
+ *
+ * Timeout handling:
+ *   - `headersTimeoutMs` (default 2s): abort if the proxy never returns
+ *     response headers (TCP accepted but wedged). Fail-open to direct.
+ *   - `timeoutMs` (default 60s): wall-clock budget for the full response
+ *     body after headers (model time through the proxy).
+ *   - Streaming through steer is refused at the provider wrapper; proxy
+ *     server supports SSE but the SDK client does not consume streams yet.
+ *
+ * Retry logic:
+ *   - Retries on 5xx + network errors + 429.
+ *   - Respects Retry-After on 429.
+ *   - Stops at maxAttempts.
+ *   - Does not retry on 4xx (except 429).
+ *   - Never retries a TensorCost refusal, whatever its status.
+ *
+ * How a non-2xx response is classified (unchanged split from 1.4.0, plus
+ * the refusal check in front of it):
+ *   - 4xx whose body carries a TensorCost refusal code, or whose
+ *     x-tc-decision says action=refuse → a TensorCostRefusedError
+ *     subclass. Terminal. Not a circuit failure.
+ *   - 429 otherwise → TensorCostQuotaError (TensorCost's rate limit).
+ *   - 402 otherwise → TensorCostQuotaError, status 402 (the plan's monthly
+ *     proxy-request ceiling). Not retried.
+ *   - 5xx → TensorCostProxyError (proxy or upstream unavailable).
+ *   - any other 4xx with a JSON body → TensorCostProviderError: the
+ *     provider's own error, relayed verbatim by the proxy. The wrappers
+ *     rethrow it as the provider SDK's own error type when they can.
+ *   - any other 4xx without one (HTML, text, empty) →
+ *     TensorCostGatewayRejectedError: turned away before TensorCost.
+ *
+ * Circuit breaker:
+ *   - Maintained on the CircuitBreaker instance passed in.
+ *   - When open, throws TensorCostProxyError immediately with a clear
+ *     message so the provider wrapper can activate the direct-provider
+ *     fallback.
+ */
+import { TensorCostError } from "./errors.js";
+import type { RetryConfig } from "./retry.js";
+import type { CircuitBreaker } from "./circuit.js";
+import type { LifecycleEventCallback } from "./telemetry.js";
+import type { Provider } from "./telemetry.js";
+import { type ControlLayer } from "./layer.js";
+export interface ProxyRequestOptions {
+    proxyUrl: string;
+    bearerToken: string;
+    providerUrl: string;
+    providerAuth: string;
+    body: Record<string, unknown>;
+    model: string;
+    provider: Provider;
+    operation: string;
+    correlationId: string;
+    environment: string | null;
+    /**
+     * Per-agent-run attribution, forwarded as `x-tc-agent-id` /
+     * `x-tc-workflow-id`. These are what let the proxy scope a spend cap to
+     * a run; without the workflow id it has no run to cap. Same values the
+     * observation envelope carries as `agent_id` / `workflow_id`.
+     */
+    agentId?: string | undefined;
+    workflowId?: string | undefined;
+    /** A-04 chargeback → `x-tc-customer`. */
+    customer?: string | undefined;
+    /** A-04 chargeback → `x-tc-feature`. */
+    feature?: string | undefined;
+    /** Routing-policy application scope → `x-tc-application`. */
+    application?: string | null | undefined;
+    /** Routing-policy tags → comma-separated `x-tc-tags`. */
+    tags?: string[] | undefined;
+    /** Compliance team scope → `x-tc-team-id`. */
+    teamId?: string | undefined;
+    retry?: RetryConfig;
+    timeoutMs?: number;
+    /** Max wait for proxy response headers before fail-open. Default 2s. */
+    headersTimeoutMs?: number;
+    onLifecycleEvent?: LifecycleEventCallback;
+    circuit: CircuitBreaker;
+    maxLayer?: ControlLayer;
+    /**
+     * When true (steer fail-open), do not retry proxy *network* errors —
+     * fail immediately so the wrapper can go direct. 429/5xx still retry.
+     * Timeouts still retry: a timeout usually means the upstream model is slow.
+     */
+    failOpenFast?: boolean;
+    /** Injected fetch implementation (for testing). Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface ProxyRequestResult {
+    body: unknown;
+    decisionHeader: string | null;
+}
+/**
+ * Execute a single proxied request with retries, timeouts, telemetry,
+ * and circuit-breaker integration.
+ *
+ * Throws a `TensorCostError` subclass on any failure.
+ * Returns the parsed JSON body on success.
+ */
+export declare function proxyRequest(opts: ProxyRequestOptions): Promise<ProxyRequestResult>;
+/**
+ * Should a failed proxy attempt fall back to calling the provider
+ * directly?
+ *
+ * Only when TensorCost itself is unavailable. Fail-open exists so that
+ * TensorCost being down never takes the customer's inference down with
+ * it, so the answer is yes for exactly these, and no for everything else:
+ *
+ *   - TensorCostNetworkError   couldn't connect, DNS, connection refused
+ *   - TensorCostTimeoutError   no headers, or no body inside the budget
+ *   - TensorCostProxyError     5xx from the proxy, or the circuit is open
+ *   - TensorCostQuotaError     429 (rate limit) or 402 (plan ceiling) from
+ *                              the proxy, with no refusal body
+ *
+ * This is an allow-list on purpose. 1.4.0 had the inverse, a list of
+ * refusal classes that must NOT fall back, and every refusal code missing
+ * from it fell back by default. That is how a money budget's hard cap
+ * (BUDGET_HARD_CAP) got routed around. Now a refusal this SDK has never
+ * heard of is terminal, a relayed provider 4xx surfaces as itself, and an
+ * error the SDK didn't classify at all is surfaced rather than retried
+ * against the provider.
+ */
+export declare function shouldFallBackToProvider(err: unknown): boolean;
+export interface ProxyStreamResult {
+    /** Raw SSE body from the proxy — same wire shape as the upstream provider. */
+    stream: ReadableStream<Uint8Array>;
+    decisionHeader: string | null;
+}
+/** Abort SSE consumption when no chunk arrives within idleTimeoutMs. */
+export declare function wrapStreamWithIdleTimeout(body: ReadableStream<Uint8Array>, idleTimeoutMs: number): ReadableStream<Uint8Array>;
+/**
+ * Steer/route a streaming request through the inference proxy.
+ * Uses the short headers timeout; no JSON body read. Retries only before
+ * headers arrive (5xx/429/network). Once SSE starts, the stream is returned
+ * as-is for the provider wrapper to consume.
+ */
+export declare function proxyRequestStream(opts: ProxyRequestOptions & {
+    idleTimeoutMs?: number;
+}): Promise<ProxyStreamResult>;
+/** Parse OpenAI-compatible SSE into an async iterable for streaming wrappers. */
+export declare function sseChunksFromStream(body: ReadableStream<Uint8Array>): AsyncIterable<Record<string, unknown>>;
+export { TensorCostError };
+//# sourceMappingURL=proxy-client.d.ts.map

package/dist/proxy-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"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"}

package/dist/proxy-client.js

@@ -26,6 +26,22 @@
  *   - Respects Retry-After on 429.
  *   - Stops at maxAttempts.
  *   - Does not retry on 4xx (except 429).
+ *   - Never retries a TensorCost refusal, whatever its status.
+ *
+ * How a non-2xx response is classified (unchanged split from 1.4.0, plus
+ * the refusal check in front of it):
+ *   - 4xx whose body carries a TensorCost refusal code, or whose
+ *     x-tc-decision says action=refuse → a TensorCostRefusedError
+ *     subclass. Terminal. Not a circuit failure.
+ *   - 429 otherwise → TensorCostQuotaError (TensorCost's rate limit).
+ *   - 402 otherwise → TensorCostQuotaError, status 402 (the plan's monthly
+ *     proxy-request ceiling). Not retried.
+ *   - 5xx → TensorCostProxyError (proxy or upstream unavailable).
+ *   - any other 4xx with a JSON body → TensorCostProviderError: the
+ *     provider's own error, relayed verbatim by the proxy. The wrappers
+ *     rethrow it as the provider SDK's own error type when they can.
+ *   - any other 4xx without one (HTML, text, empty) →
+ *     TensorCostGatewayRejectedError: turned away before TensorCost.
  *
  * Circuit breaker:
  *   - Maintained on the CircuitBreaker instance passed in.
@@ -33,7 +49,8 @@
  *     message so the provider wrapper can activate the direct-provider
  *     fallback.
  */
-import { TensorCostError, TensorCostNetworkError, TensorCostTimeoutError, TensorCostProxyError, TensorCostQuotaError, TensorCostProviderError, TensorCostRunBudgetExceededError, TensorCostRunStoppedError, TensorCostPeriodBudgetExceededError, TensorCostModelGovernanceDeniedError, TensorCostGuardrailHardStopError, TensorCostComplianceDeniedError, TensorCostComplianceTeamMismatchError, } from "./errors.js";
+import { TensorCostError, TensorCostNetworkError, TensorCostTimeoutError, TensorCostProxyError, TensorCostQuotaError, TensorCostProviderError, TensorCostGatewayRejectedError, TensorCostKeyRejectedError, TensorCostRefusedError, } from "./errors.js";
+import { decisionSaysRefuse, parseRefusalBody, providerMessageFrom, refusalError, } from "./refusal.js";
 import { DEFAULT_RETRY_CONFIG, computeDelay, retryAfterMs, sleep, } from "./retry.js";
 import { emitEvent } from "./telemetry.js";
 import { PROXY_HEADERS_TIMEOUT_MS, proxyPathForOperation, } from "./layer.js";
@@ -256,6 +273,53 @@ export async function proxyRequest(opts) {
                 decisionHeader: resp.headers.get("x-tc-decision"),
             };
         }
+        // 4xx — read the body once. A TensorCost refusal is terminal whatever
+        // its status (a 429 refusal included), so it is checked before the
+        // quota arm and is never retried or counted against the circuit: the
+        // proxy is healthy and answered. Counting it would eventually trip the
+        // breaker and route the customer straight past their own cap.
+        let errorBody = null;
+        if (resp.status >= 400 && resp.status < 500) {
+            errorBody = await readErrorBody(resp, bodyDeadline);
+            const refusal = parseRefusalBody(errorBody);
+            if (refusal !== null || decisionSaysRefuse(resp.headers.get("x-tc-decision"))) {
+                const tcErr = refusalError(refusal, {
+                    status: resp.status,
+                    requestId,
+                    attempt: attempt + 1,
+                    retryAfterHeader: resp.headers.get("retry-after"),
+                });
+                emitEvent(opts.onLifecycleEvent, {
+                    kind: "on_error",
+                    provider: opts.provider,
+                    model: opts.model,
+                    operation: opts.operation,
+                    attemptNumber: attempt + 1,
+                    elapsedMs: Date.now() - callStart,
+                    errorClass: tcErr.constructor.name,
+                    status: resp.status,
+                });
+                throw tcErr;
+            }
+        }
+        // 402 without a refusal body — the plan's monthly proxy-request ceiling
+        // (Scale COGS gate). TensorCost declining to carry the call is not a
+        // refusal of the call, and the server means for it to go direct, so it
+        // is an outage for fail-open purposes. Not retried: it won't clear soon.
+        if (resp.status === 402) {
+            const tcErr = new TensorCostQuotaError("tensorcost: proxy returned 402 (plan request ceiling reached)", retryAfterMs(resp) ?? null, { status: 402, requestId, attempt: attempt + 1 });
+            emitEvent(opts.onLifecycleEvent, {
+                kind: "on_error",
+                provider: opts.provider,
+                model: opts.model,
+                operation: opts.operation,
+                attemptNumber: attempt + 1,
+                elapsedMs: Date.now() - callStart,
+                errorClass: tcErr.constructor.name,
+                status: 402,
+            });
+            throw tcErr;
+        }
         // 429 — quota error, may have Retry-After.
         if (resp.status === 429) {
             const raMs = retryAfterMs(resp);
@@ -323,141 +387,11 @@ export async function proxyRequest(opts) {
             });
             throw tcErr;
         }
-        // 403 with our own budget code — the run hit its spend cap.
-        //
-        // Checked before the generic 4xx arm because it is NOT a provider
-        // error and, critically, must not lead to the direct-provider
-        // fallback. The body is read defensively: a 403 that is not ours
-        // (e.g. an auth failure) falls through to the generic arm below.
-        if (resp.status === 403) {
-            let code;
-            let detail;
-            try {
-                const parsed = (await resp.clone().json());
-                const errObj = parsed?.["error"];
-                if (errObj && typeof errObj["code"] === "string") {
-                    code = errObj["code"];
-                    detail = errObj;
-                }
-            }
-            catch {
-                /* non-JSON 403 — fall through to the generic 4xx arm */
-            }
-            if (code === "RUN_BUDGET_EXCEEDED" || code === "PERIOD_BUDGET_EXCEEDED") {
-                const numOrNull = (v) => typeof v === "number" ? v : null;
-                const payload = detail;
-                const tcErr = code === "PERIOD_BUDGET_EXCEEDED"
-                    ? new TensorCostPeriodBudgetExceededError(typeof payload?.["message"] === "string"
-                        ? `tensorcost: ${payload["message"]}`
-                        : "tensorcost: agent period spend cap reached", typeof payload?.["scope"] === "string" ? payload["scope"] : null, typeof payload?.["period"] === "string" ? payload["period"] : null, numOrNull(payload?.["cap_cents"]), numOrNull(payload?.["spent_cents"]), { status: 403, requestId, attempt: attempt + 1 })
-                    : new TensorCostRunBudgetExceededError(typeof payload?.["message"] === "string"
-                        ? `tensorcost: ${payload["message"]}`
-                        : "tensorcost: agent run spend cap reached", typeof payload?.["workflow_id"] === "string"
-                        ? payload["workflow_id"]
-                        : null, numOrNull(payload?.["cap_cents"]), numOrNull(payload?.["spent_cents"]), { status: 403, requestId, attempt: attempt + 1 });
-                // Not a circuit failure — the proxy is healthy and answered
-                // correctly. Counting this would eventually trip the breaker and
-                // route the customer straight past their own cap.
-                emitEvent(opts.onLifecycleEvent, {
-                    kind: "on_error",
-                    provider: opts.provider,
-                    model: opts.model,
-                    operation: opts.operation,
-                    attemptNumber: attempt + 1,
-                    elapsedMs: Date.now() - callStart,
-                    errorClass: tcErr.constructor.name,
-                    status: 403,
-                });
-                throw tcErr;
-            }
-            if (code === "RUN_STOPPED") {
-                const tcErr = runStoppedError(detail, {
-                    status: 403,
-                    requestId,
-                    attempt: attempt + 1,
-                });
-                // Healthy proxy, correct answer — not a circuit failure.
-                emitEvent(opts.onLifecycleEvent, {
-                    kind: "on_error",
-                    provider: opts.provider,
-                    model: opts.model,
-                    operation: opts.operation,
-                    attemptNumber: attempt + 1,
-                    elapsedMs: Date.now() - callStart,
-                    errorClass: tcErr.constructor.name,
-                    status: 403,
-                });
-                throw tcErr;
-            }
-            if (code === "MODEL_GOVERNANCE_DENIED") {
-                const tcErr = new TensorCostModelGovernanceDeniedError(typeof detail?.["message"] === "string"
-                    ? `tensorcost: ${detail["message"]}`
-                    : "tensorcost: model denied by tenant governance", typeof detail?.["provider"] === "string" ? detail["provider"] : null, typeof detail?.["model"] === "string" ? detail["model"] : null, typeof detail?.["governance_status"] === "string"
-                    ? detail["governance_status"]
-                    : null, { status: 403, requestId, attempt: attempt + 1 });
-                emitEvent(opts.onLifecycleEvent, {
-                    kind: "on_error",
-                    provider: opts.provider,
-                    model: opts.model,
-                    operation: opts.operation,
-                    attemptNumber: attempt + 1,
-                    elapsedMs: Date.now() - callStart,
-                    errorClass: tcErr.constructor.name,
-                    status: 403,
-                });
-                throw tcErr;
-            }
-            if (code === "GUARDRAIL_HARD_STOP") {
-                const tcErr = new TensorCostGuardrailHardStopError(typeof detail?.["message"] === "string"
-                    ? `tensorcost: ${detail["message"]}`
-                    : "tensorcost: request blocked by hard_stop guardrail", typeof detail?.["policy_id"] === "string" ? detail["policy_id"] : null, { status: 403, requestId, attempt: attempt + 1 });
-                emitEvent(opts.onLifecycleEvent, {
-                    kind: "on_error",
-                    provider: opts.provider,
-                    model: opts.model,
-                    operation: opts.operation,
-                    attemptNumber: attempt + 1,
-                    elapsedMs: Date.now() - callStart,
-                    errorClass: tcErr.constructor.name,
-                    status: 403,
-                });
-                throw tcErr;
-            }
-            if (code === "COMPLIANCE_DENIED") {
-                const tcErr = new TensorCostComplianceDeniedError(typeof detail?.["message"] === "string"
-                    ? `tensorcost: ${detail["message"]}`
-                    : "tensorcost: request refused by compliance policy", code, { status: 403, requestId, attempt: attempt + 1 });
-                emitEvent(opts.onLifecycleEvent, {
-                    kind: "on_error",
-                    provider: opts.provider,
-                    model: opts.model,
-                    operation: opts.operation,
-                    attemptNumber: attempt + 1,
-                    elapsedMs: Date.now() - callStart,
-                    errorClass: tcErr.constructor.name,
-                    status: 403,
-                });
-                throw tcErr;
-            }
-            if (code === "COMPLIANCE_TEAM_MISMATCH") {
-                const tcErr = new TensorCostComplianceTeamMismatchError(typeof detail?.["message"] === "string"
-                    ? `tensorcost: ${detail["message"]}`
-                    : "tensorcost: SDK team scope does not match token binding", { status: 403, requestId, attempt: attempt + 1 });
-                emitEvent(opts.onLifecycleEvent, {
-                    kind: "on_error",
-                    provider: opts.provider,
-                    model: opts.model,
-                    operation: opts.operation,
-                    attemptNumber: attempt + 1,
-                    elapsedMs: Date.now() - callStart,
-                    errorClass: tcErr.constructor.name,
-                    status: 403,
-                });
-                throw tcErr;
-            }
-        }
-        // 4xx (not 429) — provider error forwarded by the proxy. Non-retriable.
-        const tcErr = new TensorCostProviderError(`tensorcost: upstream provider returned ${resp.status}`, { status: resp.status, requestId, attempt: attempt + 1 });
+        // Any other status — the provider's own error, relayed by the proxy
+        // (always JSON), or, when the body isn't JSON, something in front of
+        // TensorCost turning the request away. Non-retriable, and never a
+        // fallback: the provider would answer the same way again.
+        const tcErr = nonRefusal4xx(resp, errorBody, requestId, attempt + 1);
         emitEvent(opts.onLifecycleEvent, {
             kind: "on_error",
             provider: opts.provider,
@@ -473,31 +407,85 @@ export async function proxyRequest(opts) {
     // Should be unreachable — every loop arm either returns or throws.
     throw lastError ?? new TensorCostProxyError("tensorcost: max attempts reached");
 }
-/** Build the terminal error for a `RUN_STOPPED` 403 from the proxy's body. */
-function runStoppedError(detail, opts) {
-    return TensorCostRunStoppedError.fromProxyBody(detail, opts);
+/**
+ * A non-refusal 4xx: the provider's relayed error when the body is JSON, a
+ * gateway rejection when it isn't (HTML, plain text, or empty).
+ */
+function nonRefusal4xx(resp, errorBody, requestId, attempt) {
+    if (errorBody === null || typeof errorBody === "string") {
+        return new TensorCostGatewayRejectedError(resp.status, typeof errorBody === "string" ? errorBody.slice(0, 500) : null, { requestId, attempt });
+    }
+    // NestJS's own error body ({ statusCode, message, error: "Unauthorized" })
+    // is TensorCost's, not a provider's: providers never send `statusCode`.
+    // A 401 there is the proxy rejecting the TensorCost token.
+    const nest = errorBody;
+    if (typeof nest["statusCode"] === "number" && typeof nest["error"] !== "object") {
+        if (resp.status === 401)
+            return new TensorCostKeyRejectedError(401, { requestId, attempt });
+        const msg = typeof nest["message"] === "string" ? nest["message"] : null;
+        return new TensorCostRefusedError(`tensorcost: the proxy rejected the request (${resp.status}${msg ? `: ${msg}` : ""})`, { code: null, detail: nest }, { status: resp.status, requestId, attempt });
+    }
+    const providerMsg = providerMessageFrom(errorBody);
+    const headers = {};
+    resp.headers.forEach((v, k) => {
+        headers[k] = v;
+    });
+    return new TensorCostProviderError(`tensorcost: upstream provider returned ${resp.status}` +
+        (providerMsg !== null ? `: ${providerMsg}` : ""), { status: resp.status, requestId, attempt, body: errorBody, headers });
+}
+/**
+ * Read a non-2xx body as JSON when it is JSON, else as text, inside the
+ * call's body deadline. Error bodies are small; this only guards against a
+ * proxy that sends headers and then stalls.
+ */
+async function readErrorBody(resp, deadlineMs) {
+    const remaining = Math.max(1, deadlineMs - Date.now());
+    let timer;
+    const text = await Promise.race([
+        resp.text().catch(() => ""),
+        new Promise((resolve) => {
+            timer = setTimeout(() => {
+                void resp.body?.cancel().catch(() => undefined);
+                resolve("");
+            }, remaining);
+        }),
+    ]).finally(() => clearTimeout(timer));
+    if (text === "")
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
 }
 /**
  * Should a failed proxy attempt fall back to calling the provider
  * directly?
  *
- * The applied-mode fail-open contract exists so that TensorCost being
- * down never takes the customer's inference down with it. Every transport
- * failure — timeout, network error, 5xx, open circuit — is therefore a
- * "go around us" signal and returns true.
+ * Only when TensorCost itself is unavailable. Fail-open exists so that
+ * TensorCost being down never takes the customer's inference down with
+ * it, so the answer is yes for exactly these, and no for everything else:
+ *
+ *   - TensorCostNetworkError   couldn't connect, DNS, connection refused
+ *   - TensorCostTimeoutError   no headers, or no body inside the budget
+ *   - TensorCostProxyError     5xx from the proxy, or the circuit is open
+ *   - TensorCostQuotaError     429 (rate limit) or 402 (plan ceiling) from
+ *                              the proxy, with no refusal body
  *
- * A policy refusal (run budget, model governance, guardrail hard_stop) is
- * when the proxy is healthy and the refusal IS the product. Falling back
- * would issue the provider call anyway and turn enforcement into a log line.
+ * This is an allow-list on purpose. 1.4.0 had the inverse, a list of
+ * refusal classes that must NOT fall back, and every refusal code missing
+ * from it fell back by default. That is how a money budget's hard cap
+ * (BUDGET_HARD_CAP) got routed around. Now a refusal this SDK has never
+ * heard of is terminal, a relayed provider 4xx surfaces as itself, and an
+ * error the SDK didn't classify at all is surfaced rather than retried
+ * against the provider.
  */
 export function shouldFallBackToProvider(err) {
-    return !(err instanceof TensorCostRunBudgetExceededError ||
-        err instanceof TensorCostRunStoppedError ||
-        err instanceof TensorCostPeriodBudgetExceededError ||
-        err instanceof TensorCostModelGovernanceDeniedError ||
-        err instanceof TensorCostGuardrailHardStopError ||
-        err instanceof TensorCostComplianceDeniedError ||
-        err instanceof TensorCostComplianceTeamMismatchError);
+    return (err instanceof TensorCostNetworkError ||
+        err instanceof TensorCostTimeoutError ||
+        err instanceof TensorCostProxyError ||
+        err instanceof TensorCostQuotaError);
 }
 /** Abort SSE consumption when no chunk arrives within idleTimeoutMs. */
 export function wrapStreamWithIdleTimeout(body, idleTimeoutMs) {
@@ -661,59 +649,58 @@ export async function proxyRequestStream(opts) {
                 decisionHeader: resp.headers.get("x-tc-decision"),
             };
         }
-        if (resp.status === 429 && attempt + 1 < retryConfig.maxAttempts) {
-            await sleep(computeDelay(attempt, retryConfig, retryAfterMs(resp)));
-            continue;
-        }
-        if (resp.status >= 500 && attempt + 1 < retryConfig.maxAttempts) {
-            opts.circuit.recordFailure();
-            await sleep(computeDelay(attempt, retryConfig));
-            continue;
-        }
-        // Policy refusals and 4xx — reuse proxyRequest error mapping via body read.
-        const errBody = await resp.text().catch(() => "");
-        let detail;
-        try {
-            const parsed = JSON.parse(errBody);
-            const errObj = parsed?.["error"];
-            detail =
-                errObj && typeof errObj["code"] === "string" ? errObj : undefined;
-        }
-        catch {
-            detail = undefined;
-        }
-        const code = typeof detail?.["code"] === "string" ? detail["code"] : null;
-        if (code === "RUN_BUDGET_EXCEEDED" || code === "PERIOD_BUDGET_EXCEEDED") {
-            const numOrNull = (v) => typeof v === "number" ? v : null;
-            if (code === "PERIOD_BUDGET_EXCEEDED") {
-                throw new TensorCostPeriodBudgetExceededError(typeof detail?.["message"] === "string"
-                    ? `tensorcost: ${detail["message"]}`
-                    : "tensorcost: period budget exceeded", typeof detail?.["scope"] === "string" ? detail["scope"] : null, typeof detail?.["period"] === "string" ? detail["period"] : null, numOrNull(detail?.["cap_cents"]), numOrNull(detail?.["spent_cents"]), { status: 403, requestId, attempt: attempt + 1 });
+        // Same classification as proxyRequest: refusal first (terminal, never
+        // retried), then 429 / 5xx (outages, retried), then the provider's
+        // own relayed error.
+        let errorBody = null;
+        if (resp.status >= 400 && resp.status < 500) {
+            errorBody = await readErrorBody(resp, callStart + timeoutMs);
+            const refusal = parseRefusalBody(errorBody);
+            if (refusal !== null || decisionSaysRefuse(resp.headers.get("x-tc-decision"))) {
+                const tcErr = refusalError(refusal, {
+                    status: resp.status,
+                    requestId,
+                    attempt: attempt + 1,
+                    retryAfterHeader: resp.headers.get("retry-after"),
+                });
+                emitEvent(opts.onLifecycleEvent, {
+                    kind: "on_error",
+                    provider: opts.provider,
+                    model: opts.model,
+                    operation: opts.operation,
+                    attemptNumber: attempt + 1,
+                    elapsedMs: Date.now() - callStart,
+                    errorClass: tcErr.constructor.name,
+                    status: resp.status,
+                });
+                throw tcErr;
             }
-            throw new TensorCostRunBudgetExceededError(typeof detail?.["message"] === "string"
-                ? `tensorcost: ${detail["message"]}`
-                : "tensorcost: run budget exceeded", typeof detail?.["workflow_id"] === "string" ? detail["workflow_id"] : null, numOrNull(detail?.["cap_cents"]), numOrNull(detail?.["spent_cents"]), { status: 403, requestId, attempt: attempt + 1 });
-        }
-        if (code === "RUN_STOPPED") {
-            throw runStoppedError(detail, { status: 403, requestId, attempt: attempt + 1 });
         }
-        if (code === "MODEL_GOVERNANCE_DENIED") {
-            throw new TensorCostModelGovernanceDeniedError("tensorcost: model denied by tenant governance", null, null, null, { status: 403, requestId, attempt: attempt + 1 });
+        if (resp.status === 402) {
+            throw new TensorCostQuotaError("tensorcost: proxy returned 402 (plan request ceiling reached)", retryAfterMs(resp) ?? null, { status: 402, requestId, attempt: attempt + 1 });
         }
-        if (code === "GUARDRAIL_HARD_STOP") {
-            throw new TensorCostGuardrailHardStopError("tensorcost: request blocked by hard_stop guardrail", null, { status: 403, requestId, attempt: attempt + 1 });
-        }
-        if (code === "COMPLIANCE_DENIED") {
-            throw new TensorCostComplianceDeniedError(typeof detail?.["message"] === "string"
-                ? `tensorcost: ${detail["message"]}`
-                : "tensorcost: request refused by compliance policy", code, { status: 403, requestId, attempt: attempt + 1 });
+        if (resp.status === 429) {
+            const raMs = retryAfterMs(resp);
+            if (attempt + 1 < retryConfig.maxAttempts) {
+                await sleep(computeDelay(attempt, retryConfig, raMs));
+                continue;
+            }
+            throw new TensorCostQuotaError("tensorcost: proxy returned 429 Too Many Requests", raMs ?? null, { status: 429, requestId, attempt: attempt + 1 });
         }
-        if (code === "COMPLIANCE_TEAM_MISMATCH") {
-            throw new TensorCostComplianceTeamMismatchError(typeof detail?.["message"] === "string"
-                ? `tensorcost: ${detail["message"]}`
-                : "tensorcost: SDK team scope does not match token binding", { status: 403, requestId, attempt: attempt + 1 });
+        if (resp.status >= 500) {
+            opts.circuit.recordFailure();
+            void resp.body?.cancel().catch(() => undefined);
+            if (attempt + 1 < retryConfig.maxAttempts) {
+                await sleep(computeDelay(attempt, retryConfig));
+                continue;
+            }
+            throw new TensorCostProxyError(`tensorcost: proxy returned ${resp.status}`, {
+                status: resp.status,
+                requestId,
+                attempt: attempt + 1,
+            });
         }
-        throw new TensorCostProviderError(`tensorcost: upstream provider returned ${resp.status}`, { status: resp.status, requestId, attempt: attempt + 1 });
+        throw nonRefusal4xx(resp, errorBody, requestId, attempt + 1);
     }
     throw lastError ?? new TensorCostProxyError("tensorcost: max attempts reached");
 }