@velum-labs/routekit-gateway 1.0.8 → 1.0.9

package/dist/adapters/responses-codec.js

@@ -740,17 +740,26 @@ function buildOutput(message, toolRegistry) {
     return output;
 }
 export function chatToResponses(openai, model, toolRegistry = EMPTY_TOOL_REGISTRY, searches = []) {
-    const message = openai.choices?.[0]?.message;
+    const choice = openai.choices?.[0];
+    const message = choice?.message;
+    const incompleteReason = choice?.finish_reason === "length" ||
+        choice?.finish_reason === "max_tokens" ||
+        choice?.finish_reason === "max_output_tokens"
+        ? "max_output_tokens"
+        : choice?.finish_reason === "content_filter"
+            ? "content_filter"
+            : undefined;
     // Gateway-executed searches happened before the terminal step's output.
     const output = [...searches.map(executedSearchItem), ...buildOutput(message, toolRegistry)];
     return {
         id: `resp_${openai.id ?? randomId()}`,
         object: "response",
         created_at: Math.floor(Date.now() / 1000),
-        status: "completed",
+        status: incompleteReason === undefined ? "completed" : "incomplete",
         model,
         output,
         usage: chatUsageToResponses(openai.usage),
+        ...(incompleteReason === undefined ? {} : { incomplete_details: { reason: incompleteReason } }),
         ...(openai.provider_cost !== undefined ? { provider_cost: openai.provider_cost } : {})
     };
 }

package/dist/adapters/responses-stream.js

@@ -123,7 +123,7 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
     let nextOutputIndex = 0;
     let messageOutputIndex = -1;
     let finished = false;
-    let sawFinishReason = false;
+    let finishReason;
     let usage;
     let providerCost;
     let sequenceNumber = 0;
@@ -136,7 +136,7 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
     // search, completed items collected for the terminal response payload.
     const openSearches = new Map();
     const completedSearchItems = [];
-    const baseResponse = (status, output) => ({
+    const baseResponse = (status, output, incompleteReason) => ({
         id: responseId,
         object: "response",
         created_at: Math.floor(Date.now() / 1000),
@@ -144,6 +144,9 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
         model,
         output,
         usage: status === "completed" ? chatUsageToResponses(usage) : null,
+        ...(status === "incomplete" && incompleteReason !== undefined
+            ? { incomplete_details: { reason: incompleteReason } }
+            : {}),
         ...(status === "completed" && providerCost !== undefined ? { provider_cost: providerCost } : {})
     });
     const ensureCreated = (controller) => {
@@ -341,7 +344,7 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
         }
         return indexed.sort((a, b) => a.outputIndex - b.outputIndex).map(({ item }) => item);
     };
-    const finalize = (controller, terminal = "completed") => {
+    const finalize = (controller, terminal = "completed", incompleteReason) => {
         if (finished)
             return;
         finished = true;
@@ -410,7 +413,22 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
         // as incomplete.
         controller.enqueue(terminal === "completed"
             ? emit("response.completed", { response: baseResponse("completed", assembleOutput()) })
-            : emit("response.incomplete", { response: baseResponse("incomplete", assembleOutput()) }));
+            : emit("response.incomplete", {
+                response: baseResponse("incomplete", assembleOutput(), incompleteReason)
+            }));
+    };
+    const finalizeFromFinishReason = (controller) => {
+        if (finishReason === "length" ||
+            finishReason === "max_tokens" ||
+            finishReason === "max_output_tokens") {
+            finalize(controller, "incomplete", "max_output_tokens");
+            return;
+        }
+        if (finishReason === "content_filter") {
+            finalize(controller, "incomplete", "content_filter");
+            return;
+        }
+        finalize(controller, finishReason === undefined ? "incomplete" : "completed");
     };
     // A mid-stream provider failure (`data: {"error": {...}}` — e.g. the
     // router's classified provider_error) becomes a `response.failed` event
@@ -590,9 +608,9 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
         }
         if (choice.finish_reason !== null && choice.finish_reason !== undefined) {
             // OpenAI can emit token usage/provider cost in a later choices:[] chunk.
-            // Record that the turn ended cleanly, but wait for [DONE] or EOF before
-            // emitting the one terminal Responses event.
-            sawFinishReason = true;
+            // Record how the turn ended, but wait for [DONE] or EOF before emitting
+            // the one terminal Responses event.
+            finishReason = choice.finish_reason;
         }
     };
     const handleEvent = (controller, data) => {
@@ -601,7 +619,7 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
         if (data === "[DONE]") {
             // A `[DONE]` with no prior finish_reason is truncation, not a clean stop.
             if (!finished)
-                finalize(controller, sawFinishReason ? "completed" : "incomplete");
+                finalizeFromFinishReason(controller);
             return;
         }
         let chunk;
@@ -639,7 +657,7 @@ export function openAiSseToResponses(upstream, model, toolRegistry = new Map())
         },
         onEnd(controller) {
             if (!finished)
-                finalize(controller, sawFinishReason ? "completed" : "incomplete");
+                finalizeFromFinishReason(controller);
         }
     });
 }

package/dist/observability/provenance.js

@@ -165,19 +165,55 @@ function streamedProviderError(body) {
         const response = asRecord(payload?.response);
         return (asRecord(payload?.error) ??
             asRecord(response?.error) ??
-            asRecord(response?.incomplete_details));
+            asRecord(response?.incomplete_details) ?? {
+            type: eventType === "response.incomplete" ? "response_incomplete" : "response_failed"
+        });
     }
     return undefined;
 }
-function providerError(result) {
-    const streamError = streamedProviderError(result.responseBody);
+function bufferedProviderError(body) {
+    const response = asRecord(parseJson(body));
+    if (response?.status === "incomplete") {
+        return asRecord(response.incomplete_details) ?? { type: "response_incomplete" };
+    }
+    if (response?.status === "failed") {
+        return asRecord(response.error) ?? { type: "response_failed" };
+    }
+    return undefined;
+}
+function requestedMaximumOutputTokens(body) {
+    const request = asRecord(body);
+    for (const field of ["max_output_tokens", "max_completion_tokens", "max_tokens"]) {
+        const value = request?.[field];
+        if (typeof value === "number" && Number.isInteger(value) && value > 0)
+            return value;
+    }
+    return undefined;
+}
+function terminalStopReason(context, result, usage) {
+    const terminalError = bufferedProviderError(result.responseBody) ?? streamedProviderError(result.responseBody);
+    const reason = terminalError?.reason ?? terminalError?.code;
+    if (typeof reason === "string" && reason.length > 0)
+        return reason;
+    const maximumOutputTokens = requestedMaximumOutputTokens(context.requestBody);
+    return maximumOutputTokens !== undefined &&
+        usage?.completion_tokens !== undefined &&
+        usage.completion_tokens >= maximumOutputTokens
+        ? "max_output_tokens"
+        : undefined;
+}
+function providerError(result, stopReason) {
+    const terminalError = bufferedProviderError(result.responseBody) ?? streamedProviderError(result.responseBody);
     if (result.error === undefined &&
         result.statusCode >= 200 &&
         result.statusCode < 400 &&
-        streamError === undefined) {
+        terminalError === undefined &&
+        stopReason === undefined) {
         return undefined;
     }
-    const responseError = asRecord(asRecord(parseJson(result.responseBody))?.error) ?? streamError;
+    const responseError = asRecord(asRecord(parseJson(result.responseBody))?.error) ??
+        terminalError ??
+        (stopReason === undefined ? undefined : { reason: stopReason });
     const noModelAvailable = result.statusCode === 503 &&
         responseError?.type === "unavailable" &&
         responseError.message === "no model is available; configure a provider";
@@ -196,13 +232,15 @@ function providerError(result) {
                         : "provider_error";
     const message = kind === "capability_missing"
         ? "no model route is configured"
-        : kind === "timeout"
-            ? "provider request timed out"
-            : kind === "rate_limited"
-                ? "provider rate limited the request"
-                : kind === "validation_error"
-                    ? "provider rejected the request"
-                    : "provider request failed";
+        : responseError?.reason === "max_output_tokens"
+            ? "provider response reached the maximum output token limit"
+            : kind === "timeout"
+                ? "provider request timed out"
+                : kind === "rate_limited"
+                    ? "provider rate limited the request"
+                    : kind === "validation_error"
+                        ? "provider rejected the request"
+                        : "provider request failed";
     return {
         kind,
         message,
@@ -225,13 +263,15 @@ export function buildModelCallRecord(context, result) {
                 totalTokens: usage.total_tokens
             }
     });
-    const error = providerError(result);
+    const stopReason = terminalStopReason(context, result, usage);
+    const error = providerError(result, stopReason);
     const metadata = {
         dialect: context.dialect,
         stream: context.stream,
         http_status: result.statusCode,
         duration_ms: result.durationMs,
         requested_model: context.requestedModel ?? null,
+        ...(stopReason === undefined ? {} : { stop_reason: stopReason }),
         unknown_usage: callCost.unknownUsage,
         unknown_cost: callCost.unknownCost,
         ...(context.attribution !== undefined

package/dist/test/provenance.test.js

@@ -261,3 +261,65 @@ test("HTTP 200 Codex terminal SSE quota failure is rate-limited provenance", ()
     assert.equal(record.error?.kind, "rate_limited");
     assert.equal(record.error?.retryable, true);
 });
+test("HTTP 200 incomplete Responses output is failed provenance", () => {
+    const record = buildModelCallRecord({
+        callId: "call_response_incomplete",
+        dialect: "openai-responses",
+        requestedModel: "claude-code/claude-opus-5",
+        model: "claude-code/claude-opus-5",
+        stream: false,
+        requestBody: { input: "author twenty evaluation cases" },
+        startedAt: "2026-08-20T13:00:00.000Z"
+    }, {
+        statusCode: 200,
+        durationMs: 5,
+        responseBody: Buffer.from(JSON.stringify({
+            status: "incomplete",
+            incomplete_details: { reason: "max_output_tokens" },
+            usage: { input_tokens: 31_533, output_tokens: 16_384 }
+        }))
+    });
+    assert.equal(record.status, "failed");
+    assert.equal(record.error?.message, "provider response reached the maximum output token limit");
+    assert.equal(record.usage?.completion_tokens, 16_384);
+    assert.equal(record.metadata?.stop_reason, "max_output_tokens");
+});
+test("an exact requested output-token cap is failed provenance", () => {
+    const record = buildModelCallRecord({
+        callId: "call_response_exact_cap",
+        dialect: "openai-responses",
+        requestedModel: "claude-code/claude-opus-5",
+        model: "claude-code/claude-opus-5",
+        stream: false,
+        requestBody: {
+            input: "author twenty evaluation cases",
+            max_output_tokens: 32_768
+        },
+        startedAt: "2026-08-20T13:00:00.000Z"
+    }, {
+        statusCode: 200,
+        durationMs: 5,
+        responseBody: Buffer.from(JSON.stringify({
+            status: "completed",
+            usage: { input_tokens: 31_533, output_tokens: 32_768 }
+        }))
+    });
+    assert.equal(record.status, "failed");
+    assert.equal(record.metadata?.stop_reason, "max_output_tokens");
+});
+test("HTTP 200 Responses stream without a finish reason is failed provenance", () => {
+    const record = buildModelCallRecord({
+        callId: "call_response_stream_truncated",
+        dialect: "openai-responses",
+        requestedModel: "openai/model",
+        model: "openai/model",
+        stream: true,
+        requestBody: { input: "answer", stream: true },
+        startedAt: "2026-08-20T13:00:00.000Z"
+    }, {
+        statusCode: 200,
+        durationMs: 5,
+        responseBody: Buffer.from('event: response.incomplete\ndata: {"type":"response.incomplete","response":{"status":"incomplete"}}\n\n')
+    });
+    assert.equal(record.status, "failed");
+});

package/dist/test/responses-streaming-catalog.test.js

@@ -4,7 +4,7 @@ import { runRouteKitEffect } from "@velum-labs/routekit-runtime/effect";
 import { Effect } from "effect";
 import { reasoningSelectionOf } from "../adapters/openai-chat-wire.js";
 import { parseResponsesEncryptedContent, wrapResponsesEncryptedContent } from "../adapters/openai-responses-wire.js";
-import { openAiSseToResponses } from "../adapters/responses.js";
+import { chatToResponses, openAiSseToResponses } from "../adapters/responses.js";
 import { RoutingBackend } from "../routing/router.js";
 import { startGateway } from "../gateway-service.js";
 import { testProviderSource } from "./provider-source-fixture.js";
@@ -26,6 +26,37 @@ test("a mid-stream provider error event becomes response.failed with the upstrea
     assert.ok(text.includes("openrouter call failed (unknown)"));
     assert.ok(!text.includes("event: response.completed"));
 });
+test("max-token Chat completion becomes an incomplete Responses result", () => {
+    for (const finishReason of ["length", "max_tokens"]) {
+        const response = chatToResponses({
+            choices: [
+                {
+                    message: { role: "assistant", content: '{"cases":[{"id":"truncated' },
+                    finish_reason: finishReason
+                }
+            ]
+        }, "claude-code/claude-opus-5");
+        assert.equal(response.status, "incomplete");
+        assert.deepEqual(response.incomplete_details, { reason: "max_output_tokens" });
+    }
+});
+test("max-token Chat stream becomes response.incomplete with its reason", async () => {
+    const stream = openAiSseToResponses(sseStream(`data: ${JSON.stringify({
+        choices: [
+            {
+                index: 0,
+                delta: { content: '{"cases":[{"id":"truncated' },
+                finish_reason: null
+            }
+        ]
+    })}\n\n`, `data: ${JSON.stringify({
+        choices: [{ index: 0, delta: {}, finish_reason: "length" }]
+    })}\n\n`, "data: [DONE]\n\n"), "claude-code/claude-opus-5");
+    const text = await new Response(stream).text();
+    assert.match(text, /event: response\.incomplete/u);
+    assert.match(text, /"incomplete_details":\{"reason":"max_output_tokens"\}/u);
+    assert.doesNotMatch(text, /event: response\.completed/u);
+});
 test("translates a streamed Responses event sequence", async () => {
     const mock = await startMock();
     const gateway = await startGateway({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-gateway",
   "private": false,
-  "version": "1.0.8",
+  "version": "1.0.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -45,12 +45,12 @@
     "@aws-sdk/client-bedrock": "3.1095.0",
     "@aws-sdk/client-bedrock-runtime": "3.1095.0",
     "effect": "4.0.0-rc.108",
-    "@velum-labs/routekit-config-core": "1.0.8",
-    "@velum-labs/routekit-contracts": "1.0.8",
-    "@velum-labs/routekit-eval-contracts": "1.0.8",
-    "@velum-labs/routekit-eval-core": "1.0.8",
-    "@velum-labs/routekit-registry": "1.0.8",
-    "@velum-labs/routekit-runtime": "1.0.8"
+    "@velum-labs/routekit-config-core": "1.0.9",
+    "@velum-labs/routekit-contracts": "1.0.9",
+    "@velum-labs/routekit-eval-contracts": "1.0.9",
+    "@velum-labs/routekit-eval-core": "1.0.9",
+    "@velum-labs/routekit-registry": "1.0.9",
+    "@velum-labs/routekit-runtime": "1.0.9"
   },
   "keywords": [
     "routekit",