@velum-labs/routekit-gateway 0.16.6 → 0.16.7

package/dist/backend.d.ts

@@ -72,7 +72,10 @@ export type Backend = {
     /** Release any owned resources (e.g. a managed model process). Optional. */
     close?(): Promise<void> | void;
 };
+export type BackendResponseMode = "buffered" | "streaming";
 export type BackendRequestOptions = {
+    /** Original downstream response mode, before any provider forces upstream SSE. */
+    responseMode?: BackendResponseMode;
     modelCallId?: string;
     reasoningCapabilities?: ModelReasoningCapabilities;
     /** Request-local, sanitized attribution updates from routing/backends. */

package/dist/backend.js

@@ -7,7 +7,14 @@ export function joinPath(baseUrl, path) {
     return `${base}${suffix}`;
 }
 function invalidReasoningControlResponse(message, metadata = false, path) {
-    return Response.json({ error: { type: "invalid_request_error", code: metadata ? "invalid_reasoning_metadata" : "invalid_reasoning_control", ...(path !== undefined ? { param: path } : {}), message } }, { status: 400 });
+    return Response.json({
+        error: {
+            type: "invalid_request_error",
+            code: metadata ? "invalid_reasoning_metadata" : "invalid_reasoning_control",
+            ...(path !== undefined ? { param: path } : {}),
+            message
+        }
+    }, { status: 400 });
 }
 /** An OpenAI HTTP backend supporting Chat Completions and native Responses. */
 export class OpenAiBackend {
@@ -32,7 +39,10 @@ export class OpenAiBackend {
         };
     }
     chat(body, signal, options = {}) {
-        const routed = this.#forceModel !== undefined && typeof body === "object" && body !== null && !Array.isArray(body)
+        const routed = this.#forceModel !== undefined &&
+            typeof body === "object" &&
+            body !== null &&
+            !Array.isArray(body)
             ? { ...body, model: this.#forceModel }
             : body;
         const validationError = routeKitRequestValidationErrorOf(routed);
@@ -49,18 +59,22 @@ export class OpenAiBackend {
                 }
             }, { status: 400 }));
         }
-        const canonicalSelection = routed !== null && typeof routed === "object" && !Array.isArray(routed) &&
+        const canonicalSelection = routed !== null &&
+            typeof routed === "object" &&
+            !Array.isArray(routed) &&
             (routed[REASONING_SELECTION] !== undefined ||
                 routed.x_routekit?.selection !== undefined);
-        const selectedPayload = canonicalSelection && routed !== null &&
-            typeof routed === "object" && !Array.isArray(routed)
+        const selectedPayload = canonicalSelection && routed !== null && typeof routed === "object" && !Array.isArray(routed)
             ? {
                 ...routed,
                 ...(selection.mode === "effort" ? { reasoning_effort: selection.effort } : {})
             }
             : routed;
-        if (canonicalSelection && selection.mode !== "effort" && selectedPayload !== null &&
-            typeof selectedPayload === "object" && !Array.isArray(selectedPayload)) {
+        if (canonicalSelection &&
+            selection.mode !== "effort" &&
+            selectedPayload !== null &&
+            typeof selectedPayload === "object" &&
+            !Array.isArray(selectedPayload)) {
             delete selectedPayload.reasoning_effort;
         }
         const payload = options.reasoningCapabilities?.wireShape === "openrouter" &&
@@ -148,7 +162,10 @@ export class ModelRoutedBackend {
         return model !== undefined && this.#routedIds.has(model) ? this.#routed : this.#primary;
     }
     listModelIds() {
-        const ids = [...(this.#primary.listModelIds?.() ?? (this.defaultModel !== undefined ? [this.defaultModel] : []))];
+        const ids = [
+            ...(this.#primary.listModelIds?.() ??
+                (this.defaultModel !== undefined ? [this.defaultModel] : []))
+        ];
         for (const id of this.#routedIds) {
             if (!ids.includes(id))
                 ids.push(id);
@@ -168,7 +185,9 @@ export class ModelRoutedBackend {
         return backend.reasoningWireShape?.(delegatedModel);
     }
     chat(body, signal, options = {}) {
-        const model = typeof body === "object" && body !== null && typeof body.model === "string"
+        const model = typeof body === "object" &&
+            body !== null &&
+            typeof body.model === "string"
             ? body.model
             : undefined;
         return this.#backendFor(model).chat(body, signal, options);
@@ -176,8 +195,7 @@ export class ModelRoutedBackend {
     supportsResponses(model) {
         const backend = this.#backendFor(model);
         const delegatedModel = backend.resolveModel?.(model) ?? backend.defaultModel ?? model;
-        return (backend.responses !== undefined &&
-            (backend.supportsResponses?.(delegatedModel) ?? true));
+        return backend.responses !== undefined && (backend.supportsResponses?.(delegatedModel) ?? true);
     }
     responses(body, signal, options = {}) {
         const model = typeof body === "object" &&

package/dist/index.d.ts

@@ -4,13 +4,13 @@ export type { Gateway, GatewayOptions, ProviderRelay, ProviderRelayDialect } fro
 export { startSwitchingGatewayProxy } from "./switching-proxy.js";
 export type { SwitchingGatewayProxy } from "./switching-proxy.js";
 export { joinPath, ModelRoutedBackend, OpenAiBackend } from "./backend.js";
-export type { Backend, BackendModelRoute, BackendRequestOptions, RequestAttributionUpdate, ModelRoutedBackendOptions, OpenAiBackendOptions } from "./backend.js";
+export type { Backend, BackendModelRoute, BackendRequestOptions, BackendResponseMode, RequestAttributionUpdate, ModelRoutedBackendOptions, OpenAiBackendOptions } from "./backend.js";
 export { AnthropicBackend, CodexResponsesBackend, GoogleGenAiBackend } from "./provider-backends.js";
 export type { ProviderBackendOptions, ProviderTransport } from "./provider-backends.js";
 export { BedrockProviderSource, fromBedrockConverseOutput, toBedrockConverseInput } from "./bedrock-source.js";
 export type { BedrockControlClient, BedrockProviderSourceOptions, BedrockRuntime } from "./bedrock-source.js";
 export { CatalogBackend, DEFAULT_LEADERBOARD_DURABLE_RETENTION_DAYS, DEFAULT_LEADERBOARD_LIVE_LIMIT, DEFAULT_LEADERBOARD_LIVE_TTL_HOURS, isSubscriptionProvider, leaderboardConfigSchema, NoModelAvailableError, modelPolicyAllowsModel, modelPolicyRuleMatches, normalizeRouterConfigAliases, parseRouterConfig, resolveLeaderboardConfig, routerConfigSchema, splitNamespacedModel, UnknownModelError } from "./router.js";
-export type { CatalogBackendOptions, CatalogModelInfo, LeaderboardConfig, ModelPolicy, ProviderPolicy, RouterConfig, } from "./router.js";
+export type { CatalogBackendOptions, CatalogModelInfo, LeaderboardConfig, ModelPolicy, ProviderPolicy, RouterConfig } from "./router.js";
 export { API_PROVIDER_IDS, ApiProviderSource, parseDiscoveredModels, parseReasoningCapabilities, PROVIDER_IDS, SUBSCRIPTION_PROVIDER_IDS } from "./provider-source.js";
 export type { ApiProviderId, ApiProviderSourceOptions, DiscoveredModel, ProviderId, ProviderSource, ProviderSourceTransport, SubscriptionProviderId } from "./provider-source.js";
 export { endpointHealthProbe, probeEndpointHealth, providerAuthHeaders } from "./endpoint-health.js";

package/dist/provenance.js

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { artifactHash, requestHash, responseHash } from "@velum-labs/routekit-contracts";
 import { meterCall, parseUsage, parseUsageFromSse } from "./cost.js";
+import { decodeBufferedSse } from "./sse/parse.js";
 export const MODEL_CALL_ID_HEADER = "x-routekit-model-call-id";
 export const UNKNOWN_GIT_SHA = "unknown";
 const GIT_SHA_PATTERN = /^[a-f0-9]{40}$/;
@@ -87,23 +88,56 @@ function providerRequestId(body) {
     const id = asRecord(parseJson(body))?.id;
     return typeof id === "string" && id.length > 0 ? id : undefined;
 }
+function streamedProviderError(body) {
+    const text = responseText(body);
+    if (!text.includes("response.failed") && !text.includes("response.incomplete"))
+        return undefined;
+    for (const event of decodeBufferedSse(text)) {
+        let payload;
+        try {
+            payload = asRecord(JSON.parse(event.data));
+        }
+        catch {
+            continue;
+        }
+        const eventType = event.event ?? payload?.type;
+        if (eventType !== "response.failed" &&
+            eventType !== "response.incomplete" &&
+            eventType !== "error") {
+            continue;
+        }
+        const response = asRecord(payload?.response);
+        return (asRecord(payload?.error) ??
+            asRecord(response?.error) ??
+            asRecord(response?.incomplete_details));
+    }
+    return undefined;
+}
 function providerError(result) {
-    if (result.error === undefined && result.statusCode >= 200 && result.statusCode < 400) {
+    const streamError = streamedProviderError(result.responseBody);
+    if (result.error === undefined &&
+        result.statusCode >= 200 &&
+        result.statusCode < 400 &&
+        streamError === undefined) {
         return undefined;
     }
-    const responseError = asRecord(asRecord(parseJson(result.responseBody))?.error);
+    const responseError = asRecord(asRecord(parseJson(result.responseBody))?.error) ?? streamError;
     const noModelAvailable = result.statusCode === 503 &&
         responseError?.type === "unavailable" &&
         responseError.message === "no model is available; configure a provider";
+    const streamErrorIdentity = `${responseError?.type ?? ""} ${responseError?.error_type ?? ""} ${responseError?.code ?? ""}`.toLowerCase();
+    const streamRateLimited = /usage[_ ]?limit|rate[_ ]?limit|quota|insufficient_quota/.test(streamErrorIdentity);
     const kind = noModelAvailable
         ? "capability_missing"
-        : result.statusCode === 408
-            ? "timeout"
-            : result.statusCode === 429
-                ? "rate_limited"
-                : result.statusCode === 400 || result.statusCode === 422
-                    ? "validation_error"
-                    : "provider_error";
+        : streamRateLimited
+            ? "rate_limited"
+            : result.statusCode === 408
+                ? "timeout"
+                : result.statusCode === 429
+                    ? "rate_limited"
+                    : result.statusCode === 400 || result.statusCode === 422
+                        ? "validation_error"
+                        : "provider_error";
     const message = kind === "capability_missing"
         ? "no model route is configured"
         : kind === "timeout"
@@ -117,7 +151,10 @@ function providerError(result) {
         kind,
         message,
         retryable: !noModelAvailable &&
-            (result.statusCode === 408 || result.statusCode === 429 || result.statusCode >= 500)
+            (streamRateLimited ||
+                result.statusCode === 408 ||
+                result.statusCode === 429 ||
+                result.statusCode >= 500)
     };
 }
 export function buildModelCallRecord(context, result) {

package/dist/provider-backends.js

@@ -1120,6 +1120,27 @@ function codexCompletionResponse(model, payload) {
         ? jsonResponse(chatCompletion(model, message, normalizedOpenAiUsage(payload.usage)))
         : jsonResponse({ error: CODEX_EMPTY_RESPONSE_ERROR }, 502);
 }
+function codexTerminalError(payload) {
+    const record = typeof payload === "object" && payload !== null
+        ? payload
+        : {};
+    const response = typeof record.response === "object" && record.response !== null
+        ? record.response
+        : undefined;
+    const raw = typeof record.error === "object" && record.error !== null
+        ? record.error
+        : typeof response?.error === "object" && response.error !== null
+            ? response.error
+            : undefined;
+    const details = typeof response?.incomplete_details === "object" && response.incomplete_details !== null
+        ? response.incomplete_details
+        : undefined;
+    return {
+        ...(raw ?? {}),
+        type: raw?.type ?? raw?.error_type ?? details?.reason ?? "upstream_error",
+        message: typeof raw?.message === "string" ? raw.message : "Codex response did not complete"
+    };
+}
 export class CodexResponsesBackend extends HttpProviderBackend {
     #accountId;
     #forceStream;
@@ -1326,14 +1347,7 @@ export class CodexResponsesBackend extends HttpProviderBackend {
                 if (eventType === "response.failed" ||
                     eventType === "response.incomplete" ||
                     eventType === "error") {
-                    return [
-                        {
-                            error: {
-                                message: "Codex response did not complete",
-                                type: "upstream_error"
-                            }
-                        }
-                    ];
+                    return [{ error: codexTerminalError(item) }];
                 }
                 return [];
             });
@@ -1346,6 +1360,7 @@ export class CodexResponsesBackend extends HttpProviderBackend {
             ];
             const completedOutput = new Map();
             let completedResponse;
+            let terminalFailure;
             for (const event of events) {
                 let payload;
                 try {
@@ -1375,6 +1390,9 @@ export class CodexResponsesBackend extends HttpProviderBackend {
                     record.response !== null) {
                     completedResponse = record.response;
                 }
+                if (eventType === "response.failed" || eventType === "response.incomplete" || eventType === "error") {
+                    terminalFailure = codexTerminalError(record);
+                }
             }
             if (completedResponse !== undefined) {
                 const terminalOutput = Array.isArray(completedResponse.output)
@@ -1388,6 +1406,8 @@ export class CodexResponsesBackend extends HttpProviderBackend {
                 const payload = { ...completedResponse, output: terminalOutput };
                 return codexCompletionResponse(model, payload);
             }
+            if (terminalFailure !== undefined)
+                return jsonResponse({ error: terminalFailure }, 502);
             throw new SseParseError("provider SSE stream ended without response.completed");
         }
         const payload = (await response.json());

package/dist/server.d.ts

@@ -31,7 +31,7 @@ export type ProviderRelayDialect = "anthropic" | "codex";
 export type ProviderRelay = {
     readonly dialect: ProviderRelayDialect;
     shouldRelay(headers: IncomingMessage["headers"], model: string | undefined, servesLocally: (model: string) => boolean): boolean;
-    relay(headers: IncomingMessage["headers"], body: AnthropicRequest | ResponsesRequest, signal?: AbortSignal, options?: Pick<BackendRequestOptions, "onAttribution">): Promise<Response>;
+    relay(headers: IncomingMessage["headers"], body: AnthropicRequest | ResponsesRequest, signal?: AbortSignal, options?: Pick<BackendRequestOptions, "onAttribution" | "responseMode">): Promise<Response>;
     models?(headers: IncomingMessage["headers"], search: string, signal?: AbortSignal): Promise<Response>;
     countTokens?(headers: IncomingMessage["headers"], body: AnthropicRequest, signal?: AbortSignal): Promise<Response>;
     mergedCatalog?(headers: IncomingMessage["headers"], search: string): Promise<{

package/dist/server.js

@@ -382,6 +382,7 @@ export async function startGateway(options) {
                 invoke: (callId, signal, onAttribution) => backend.chat(body, signal, {
                     modelCallId: callId,
                     requestContext,
+                    responseMode: isStream(body) ? "streaming" : "buffered",
                     onAttribution
                 })
             });
@@ -438,6 +439,7 @@ export async function startGateway(options) {
                 invoke: (callId, signal, onAttribution) => backend.chat(body, signal, {
                     modelCallId: callId,
                     requestContext,
+                    responseMode: isStream(body) ? "streaming" : "buffered",
                     onAttribution
                 })
             });
@@ -456,6 +458,7 @@ export async function startGateway(options) {
                 invoke: (callId, signal, onAttribution) => backend.embeddings(body, signal, {
                     modelCallId: callId,
                     requestContext,
+                    responseMode: isStream(body) ? "streaming" : "buffered",
                     onAttribution
                 })
             });
@@ -549,6 +552,7 @@ export async function startGateway(options) {
                         billing_mode: "subscription"
                     },
                     invoke: (_callId, signal, onAttribution) => anthropicRelay.relay(req.headers, relayBody, signal, {
+                        responseMode: isStream(body) ? "streaming" : "buffered",
                         onAttribution
                     })
                 });
@@ -570,6 +574,7 @@ export async function startGateway(options) {
                         billing_mode: "subscription"
                     },
                     invoke: (_callId, signal, onAttribution) => anthropicRelay.relay(req.headers, body, signal, {
+                        responseMode: isStream(body) ? "streaming" : "buffered",
                         onAttribution
                     })
                 });
@@ -582,6 +587,7 @@ export async function startGateway(options) {
                 attribution: initialAttribution(backend, resolvedModel, "claude-code"),
                 invoke: (callId, signal, onAttribution) => handleAnthropicMessages(backend, body, callId, signal, {
                     requestContext,
+                    responseMode: isStream(body) ? "streaming" : "buffered",
                     onAttribution
                 })
             });
@@ -637,6 +643,7 @@ export async function startGateway(options) {
                         billing_mode: "subscription"
                     },
                     invoke: (_callId, signal, onAttribution) => codexProviderRelay.relay(req.headers, relayBody, signal, {
+                        responseMode: isStream(body) ? "streaming" : "buffered",
                         onAttribution
                     })
                 });
@@ -660,6 +667,7 @@ export async function startGateway(options) {
                         billing_mode: "client_auth"
                     },
                     invoke: (_callId, signal, onAttribution) => codexRequestRelay.relay(req.headers, body, signal, {
+                        responseMode: isStream(body) ? "streaming" : "buffered",
                         onAttribution
                     })
                 });
@@ -672,6 +680,7 @@ export async function startGateway(options) {
                 attribution: initialAttribution(backend, requestedModel, codexProviderRelay !== undefined ? "codex" : undefined),
                 invoke: (callId, signal, onAttribution) => handleResponses(backend, canonicalBody, callId, signal, {
                     requestContext,
+                    responseMode: isStream(body) ? "streaming" : "buffered",
                     onAttribution
                 })
             });

package/dist/test/provenance.test.js

@@ -174,3 +174,18 @@ test("model-call provenance meters aggregate buffered and Responses SSE usage",
     assert.deepEqual(streamed.usage, buffered.usage);
     assert.equal(streamed.metadata?.cost_estimate_usd, 0.0001575);
 });
+test("HTTP 200 Codex terminal SSE quota failure is rate-limited provenance", () => {
+    const body = Buffer.from('event: response.failed\ndata: {"response":{"error":{"type":"usage_limit_reached","code":"weekly","message":"spent"}}}\n\n');
+    const record = buildModelCallRecord({
+        callId: "call_sse_quota",
+        dialect: "openai-responses",
+        requestedModel: "codex/gpt-5.5",
+        model: "codex/gpt-5.5",
+        stream: true,
+        requestBody: { model: "codex/gpt-5.5", input: "hi", stream: true },
+        startedAt: "2026-07-29T00:00:00.000Z"
+    }, { statusCode: 200, durationMs: 5, responseBody: body });
+    assert.equal(record.status, "failed");
+    assert.equal(record.error?.kind, "rate_limited");
+    assert.equal(record.error?.retryable, true);
+});

package/dist/test/provider-backends.test.js

@@ -1848,3 +1848,28 @@ test("ordinary OpenAI Chat egress strips RouteKit provider-only envelopes", asyn
         globalThis.fetch = original;
     }
 });
+test("Codex backend preserves structured forced-stream terminal failure", async () => {
+    const backend = new CodexResponsesBackend({
+        baseUrl: "https://codex.test", apiKey: "x", defaultModel: "m", forceStream: true,
+        transport: async () => sse([{ event: "response.failed", data: { response: { error: {
+                            type: "usage_limit_reached", code: "weekly", message: "spent", resets_at: 1775000000
+                        } } } }])
+    });
+    const response = await backend.chat({ model: "m", messages: [] });
+    assert.equal(response.status, 502);
+    assert.deepEqual(await response.json(), { error: {
+            type: "usage_limit_reached", code: "weekly", message: "spent", resets_at: 1775000000
+        } });
+});
+test("Codex streaming backend preserves terminal provider error fields", async () => {
+    const backend = new CodexResponsesBackend({
+        baseUrl: "https://codex.test", apiKey: "x", defaultModel: "m",
+        transport: async () => sse([{ event: "response.failed", data: { response: { error: {
+                            type: "usage_limit_reached", code: "weekly", message: "spent", resets_at: 1775000000
+                        } } } }])
+    });
+    const text = await (await backend.chat({ model: "m", messages: [], stream: true })).text();
+    assert.match(text, /usage_limit_reached/);
+    assert.match(text, /weekly/);
+    assert.match(text, /1775000000/);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-gateway",
   "private": false,
-  "version": "0.16.6",
+  "version": "0.16.7",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -29,10 +29,10 @@
     "@aws-sdk/client-bedrock": "3.1095.0",
     "@aws-sdk/client-bedrock-runtime": "3.1095.0",
     "zod": "4.4.3",
-    "@velum-labs/routekit-contracts": "0.16.6",
-    "@velum-labs/routekit-registry": "0.16.6",
-    "@velum-labs/routekit-runtime": "0.16.6",
-    "@velum-labs/routekit-tracing": "0.16.6"
+    "@velum-labs/routekit-contracts": "0.16.7",
+    "@velum-labs/routekit-registry": "0.16.7",
+    "@velum-labs/routekit-runtime": "0.16.7",
+    "@velum-labs/routekit-tracing": "0.16.7"
   },
   "keywords": [
     "routekit",