@hebo-ai/gateway 0.4.0-alpha.2 → 0.4.0-alpha.3

package/README.md

@@ -349,8 +349,8 @@ const gw = gateway({
      * @returns Modified result, or undefined to keep original.
      */
     after: async (ctx: {
-      result: ChatCompletions  | ReadableStream<ChatCompletionsChunk | OpenAIError> | Embeddings | object
-    }): Promise<ChatCompletions  | ReadableStream<ChatCompletionsChunk | OpenAIError> | Embeddings | object | void> => {
+      result: ChatCompletions  | ReadableStream<ChatCompletionsChunk | OpenAIError> | Embeddings
+    }): Promise<ChatCompletions  | ReadableStream<ChatCompletionsChunk | OpenAIError> | Embeddings | void> => {
       // Example Use Cases:
       // - Transform result
       // - Result logging
@@ -555,6 +555,15 @@ Reasoning output is surfaced as extension to the `completion` object.
 
 Most SDKs handle these fields out-of-the-box.
 
+#### Thinking Blocks & Context Preservation
+
+Advanced models (like Anthropic Claude 3.7 or Gemini 3) surface structured reasoning steps and signatures that act as a "save state" for the model's internal reasoning process. To maintain this context across multi-turn conversations and tool-calling workflows, you should pass back the following extensions in subsequent messages:
+
+- **reasoning_details**: Standardized array of reasoning steps and generic signatures.
+- **extra_content**: Provider-specific extensions, such as **Google's thought signatures** on Vertex AI.
+
+For **Gemini 3** models, returning the thought signature via `extra_content` is mandatory to resume the chain-of-thought; failing to do so may result in errors or degraded performance.
+
 ## 🧪 Advanced Usage
 
 ### Logger Settings
@@ -573,7 +582,6 @@ const gw = gateway({
 ```
 
 If you provide a custom logger, it must implement `trace`, `debug`, `info`, `warn`, and `error` methods.
-For production workloads, we recommend `pino` for better logging performance and lower overhead.
 
 Example with **pino**:
 
@@ -591,6 +599,9 @@ const gw = gateway({
 });
 ```
 
+> [!TIP]
+> For production workloads, we recommend `pino` for better logging performance and lower overhead.
+
 ### Telemetry Settings
 
 Hebo Gateway can forward telemetry settings via the `telemetry` config field.
@@ -610,6 +621,9 @@ const gw = gateway({
 });
 ```
 
+> [!TIP]
+> For observability integration that is not otel compliant (for example, Langfuse), you can disable built-in telemetry and manually instrument requests during `before` / `after` hooks.
+
 ### Passing Framework State to Hooks
 
 You can pass per-request info from your framework into the gateway via the second `state` argument on the handler, then read it in hooks through `ctx.state`.

package/dist/endpoints/chat-completions/converters.d.ts

@@ -1,6 +1,6 @@
 import type { SharedV3ProviderOptions, SharedV3ProviderMetadata } from "@ai-sdk/provider";
-import type { GenerateTextResult, StreamTextResult, FinishReason, ToolChoice, ToolSet, ModelMessage, UserContent, LanguageModelUsage, Output, TextStreamPart, AssistantModelMessage, ToolModelMessage, UserModelMessage } from "ai";
-import type { ChatCompletionsToolCall, ChatCompletionsTool, ChatCompletionsToolChoice, ChatCompletionsContentPart, ChatCompletionsMessage, ChatCompletionsUserMessage, ChatCompletionsAssistantMessage, ChatCompletionsToolMessage, ChatCompletionsFinishReason, ChatCompletionsUsage, ChatCompletionsInputs, ChatCompletions, ChatCompletionsChunk } from "./schema";
+import type { GenerateTextResult, StreamTextResult, FinishReason, ToolChoice, ToolSet, ModelMessage, UserContent, LanguageModelUsage, Output, TextStreamPart, ReasoningOutput, AssistantModelMessage, ToolModelMessage, UserModelMessage } from "ai";
+import type { ChatCompletionsToolCall, ChatCompletionsTool, ChatCompletionsToolChoice, ChatCompletionsContentPart, ChatCompletionsMessage, ChatCompletionsUserMessage, ChatCompletionsAssistantMessage, ChatCompletionsToolMessage, ChatCompletionsFinishReason, ChatCompletionsUsage, ChatCompletionsInputs, ChatCompletions, ChatCompletionsChunk, ChatCompletionsReasoningDetail } from "./schema";
 import { OpenAIError } from "../../errors/openai";
 export type TextCallOptions = {
     messages: ModelMessage[];
@@ -31,6 +31,7 @@ export declare class ChatCompletionsStream extends TransformStream<TextStreamPar
     constructor(model: string);
 }
 export declare const toChatCompletionsAssistantMessage: (result: GenerateTextResult<ToolSet, Output.Output>) => ChatCompletionsAssistantMessage;
+export declare function toReasoningDetail(reasoning: ReasoningOutput, id: string, index: number): ChatCompletionsReasoningDetail;
 export declare function toChatCompletionsUsage(usage: LanguageModelUsage): ChatCompletionsUsage;
 export declare function toChatCompletionsToolCall(id: string, name: string, args: unknown, providerMetadata?: SharedV3ProviderMetadata): ChatCompletionsToolCall;
 export declare const toChatCompletionsFinishReason: (finishReason: FinishReason) => ChatCompletionsFinishReason;

package/dist/endpoints/chat-completions/converters.js

@@ -61,33 +61,67 @@ export function fromChatCompletionsUserMessage(message) {
     };
 }
 export function fromChatCompletionsAssistantMessage(message) {
-    const { tool_calls, role, content, extra_content } = message;
-    if (!tool_calls?.length) {
-        const out = {
-            role: role,
-            content: content ?? "",
-        };
-        if (extra_content) {
-            out.providerOptions = extra_content;
+    const { tool_calls, role, content, extra_content, reasoning_details } = message;
+    const parts = [];
+    if (Array.isArray(parts)) {
+        if (reasoning_details?.length) {
+            for (const detail of reasoning_details) {
+                if (detail.text && detail.type === "reasoning.text") {
+                    parts.push({
+                        type: "reasoning",
+                        text: detail.text,
+                        providerOptions: detail.signature
+                            ? {
+                                unknown: {
+                                    signature: detail.signature,
+                                },
+                            }
+                            : undefined,
+                    });
+                }
+                else if (detail.type === "reasoning.encrypted" && detail.data) {
+                    parts.push({
+                        type: "reasoning",
+                        text: "",
+                        providerOptions: {
+                            unknown: {
+                                redactedData: detail.data,
+                            },
+                        },
+                    });
+                }
+            }
+        }
+        if (tool_calls?.length) {
+            for (const tc of tool_calls) {
+                const { id, function: fn, extra_content } = tc;
+                const out = {
+                    type: "tool-call",
+                    toolCallId: id,
+                    toolName: fn.name,
+                    input: parseToolOutput(fn.arguments).value,
+                };
+                if (extra_content) {
+                    out.providerOptions = extra_content;
+                }
+                parts.push(out);
+            }
+        }
+        else if (content !== undefined && content !== null) {
+            parts.push({
+                type: "text",
+                text: content,
+            });
         }
-        return out;
     }
-    return {
+    const out = {
         role: role,
-        content: tool_calls.map((tc) => {
-            const { id, function: fn, extra_content } = tc;
-            const out = {
-                type: "tool-call",
-                toolCallId: id,
-                toolName: fn.name,
-                input: parseToolOutput(fn.arguments).value,
-            };
-            if (extra_content) {
-                out.providerOptions = extra_content;
-            }
-            return out;
-        }),
+        content: Array.isArray(parts) && parts.length > 0 ? parts : (content ?? ""),
     };
+    if (extra_content) {
+        out.providerOptions = extra_content;
+    }
+    return out;
 }
 export function fromChatCompletionsToolResultMessage(message, toolById) {
     const toolCalls = message.tool_calls ?? [];
@@ -251,6 +285,7 @@ export class ChatCompletionsStream extends TransformStream {
         const streamId = `chatcmpl-${crypto.randomUUID()}`;
         const creationTime = Math.floor(Date.now() / 1000);
         let toolCallIndexCounter = 0;
+        const reasoningIdToIndex = new Map();
         const createChunk = (delta, provider_metadata, finish_reason, usage) => {
             if (provider_metadata) {
                 delta.extra_content = provider_metadata;
@@ -278,7 +313,21 @@ export class ChatCompletionsStream extends TransformStream {
                         break;
                     }
                     case "reasoning-delta": {
-                        controller.enqueue(createChunk({ reasoning_content: part.text }, part.providerMetadata));
+                        let index = reasoningIdToIndex.get(part.id);
+                        if (index === undefined) {
+                            index = reasoningIdToIndex.size;
+                            reasoningIdToIndex.set(part.id, index);
+                        }
+                        controller.enqueue(createChunk({
+                            reasoning_content: part.text,
+                            reasoning_details: [
+                                toReasoningDetail({
+                                    type: "reasoning",
+                                    text: part.text,
+                                    providerMetadata: part.providerMetadata,
+                                }, part.id, index),
+                            ],
+                        }, part.providerMetadata));
                         break;
                     }
                     case "tool-call": {
@@ -316,20 +365,63 @@ export const toChatCompletionsAssistantMessage = (result) => {
     if (result.toolCalls && result.toolCalls.length > 0) {
         message.tool_calls = result.toolCalls.map((toolCall) => toChatCompletionsToolCall(toolCall.toolCallId, toolCall.toolName, toolCall.input, toolCall.providerMetadata));
     }
+    const reasoningDetails = [];
     for (const part of result.content) {
         if (part.type === "text") {
-            message.content = part.text;
-            if (part.providerMetadata) {
-                message.extra_content = part.providerMetadata;
+            if (message.content === null) {
+                message.content = part.text;
+                if (part.providerMetadata) {
+                    message.extra_content = part.providerMetadata;
+                }
             }
-            break;
+        }
+        else if (part.type === "reasoning") {
+            reasoningDetails.push(toReasoningDetail(part, `reasoning-${crypto.randomUUID()}`, reasoningDetails.length));
         }
     }
     if (result.reasoningText) {
         message.reasoning_content = result.reasoningText;
+        if (reasoningDetails.length === 0) {
+            reasoningDetails.push(toReasoningDetail({ type: "reasoning", text: result.reasoningText }, `reasoning-${crypto.randomUUID()}`, 0));
+        }
+    }
+    if (reasoningDetails.length > 0) {
+        message.reasoning_details = reasoningDetails;
     }
     return message;
 };
+export function toReasoningDetail(reasoning, id, index) {
+    const providerMetadata = reasoning.providerMetadata ?? {};
+    let redactedData;
+    let signature;
+    for (const metadata of Object.values(providerMetadata)) {
+        if (metadata && typeof metadata === "object") {
+            if ("redactedData" in metadata && typeof metadata["redactedData"] === "string") {
+                redactedData = metadata["redactedData"];
+            }
+            if ("signature" in metadata && typeof metadata["signature"] === "string") {
+                signature = metadata["signature"];
+            }
+        }
+    }
+    if (redactedData) {
+        return {
+            id,
+            index,
+            type: "reasoning.encrypted",
+            data: redactedData,
+            format: "unknown",
+        };
+    }
+    return {
+        id,
+        index,
+        type: "reasoning.text",
+        text: reasoning.text,
+        signature,
+        format: "unknown",
+    };
+}
 export function toChatCompletionsUsage(usage) {
     const out = {};
     const prompt = usage.inputTokens;

package/dist/endpoints/chat-completions/schema.d.ts

@@ -57,6 +57,17 @@ export declare const ChatCompletionsUserMessageSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ChatCompletionsUserMessage = z.infer<typeof ChatCompletionsUserMessageSchema>;
+export declare const ChatCompletionsReasoningDetailSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    index: z.ZodInt;
+    type: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    signature: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChatCompletionsReasoningDetail = z.infer<typeof ChatCompletionsReasoningDetailSchema>;
 export declare const ChatCompletionsAssistantMessageSchema: z.ZodObject<{
     role: z.ZodLiteral<"assistant">;
     content: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
@@ -71,6 +82,16 @@ export declare const ChatCompletionsAssistantMessageSchema: z.ZodObject<{
         extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>>>;
     reasoning_content: z.ZodOptional<z.ZodString>;
+    reasoning_details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        index: z.ZodInt;
+        type: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
+        signature: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, z.core.$strip>;
 export type ChatCompletionsAssistantMessage = z.infer<typeof ChatCompletionsAssistantMessageSchema>;
@@ -118,6 +139,16 @@ export declare const ChatCompletionsMessageSchema: z.ZodUnion<readonly [z.ZodObj
         extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>>>;
     reasoning_content: z.ZodOptional<z.ZodString>;
+    reasoning_details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        index: z.ZodInt;
+        type: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
+        signature: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, z.core.$strip>, z.ZodObject<{
     role: z.ZodLiteral<"tool">;
@@ -189,6 +220,16 @@ declare const ChatCompletionsInputsSchema: z.ZodObject<{
             extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         }, z.core.$strip>>>;
         reasoning_content: z.ZodOptional<z.ZodString>;
+        reasoning_details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            index: z.ZodInt;
+            type: z.ZodString;
+            text: z.ZodOptional<z.ZodString>;
+            signature: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>, z.ZodObject<{
         role: z.ZodLiteral<"tool">;
@@ -265,6 +306,16 @@ export declare const ChatCompletionsBodySchema: z.ZodObject<{
             extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         }, z.core.$strip>>>;
         reasoning_content: z.ZodOptional<z.ZodString>;
+        reasoning_details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            index: z.ZodInt;
+            type: z.ZodString;
+            text: z.ZodOptional<z.ZodString>;
+            signature: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>, z.ZodObject<{
         role: z.ZodLiteral<"tool">;
@@ -322,6 +373,16 @@ export declare const ChatCompletionsChoiceSchema: z.ZodObject<{
             extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         }, z.core.$strip>>>;
         reasoning_content: z.ZodOptional<z.ZodString>;
+        reasoning_details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            index: z.ZodInt;
+            type: z.ZodString;
+            text: z.ZodOptional<z.ZodString>;
+            signature: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>;
     finish_reason: z.ZodUnion<readonly [z.ZodLiteral<"stop">, z.ZodLiteral<"length">, z.ZodLiteral<"content_filter">, z.ZodLiteral<"tool_calls">]>;
@@ -361,6 +422,16 @@ export declare const ChatCompletionsSchema: z.ZodObject<{
                 extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             }, z.core.$strip>>>;
             reasoning_content: z.ZodOptional<z.ZodString>;
+            reasoning_details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodOptional<z.ZodString>;
+                index: z.ZodInt;
+                type: z.ZodString;
+                text: z.ZodOptional<z.ZodString>;
+                signature: z.ZodOptional<z.ZodString>;
+                data: z.ZodOptional<z.ZodString>;
+                summary: z.ZodOptional<z.ZodString>;
+                format: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
             extra_content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         }, z.core.$strip>;
         finish_reason: z.ZodUnion<readonly [z.ZodLiteral<"stop">, z.ZodLiteral<"length">, z.ZodLiteral<"content_filter">, z.ZodLiteral<"tool_calls">]>;
@@ -396,6 +467,16 @@ export declare const ChatCompletionsAssistantMessageDeltaSchema: z.ZodObject<{
     content: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>>;
     name: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     reasoning_content: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    reasoning_details: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        index: z.ZodInt;
+        type: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
+        signature: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>;
     extra_content: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>>;
     tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodOptional<z.ZodLiteral<"function">>;
@@ -416,6 +497,16 @@ export declare const ChatCompletionsChoiceDeltaSchema: z.ZodObject<{
         content: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>>;
         name: z.ZodOptional<z.ZodOptional<z.ZodString>>;
         reasoning_content: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        reasoning_details: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            index: z.ZodInt;
+            type: z.ZodString;
+            text: z.ZodOptional<z.ZodString>;
+            signature: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>>;
         extra_content: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>>;
         tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodOptional<z.ZodLiteral<"function">>;
@@ -444,6 +535,16 @@ export declare const ChatCompletionsChunkSchema: z.ZodObject<{
             content: z.ZodOptional<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>>;
             name: z.ZodOptional<z.ZodOptional<z.ZodString>>;
             reasoning_content: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            reasoning_details: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodOptional<z.ZodString>;
+                index: z.ZodInt;
+                type: z.ZodString;
+                text: z.ZodOptional<z.ZodString>;
+                signature: z.ZodOptional<z.ZodString>;
+                data: z.ZodOptional<z.ZodString>;
+                summary: z.ZodOptional<z.ZodString>;
+                format: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>>;
             extra_content: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>>;
             tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 type: z.ZodOptional<z.ZodLiteral<"function">>;

package/dist/endpoints/chat-completions/schema.js

@@ -44,6 +44,16 @@ export const ChatCompletionsUserMessageSchema = z.object({
     ]),
     name: z.string().optional(),
 });
+export const ChatCompletionsReasoningDetailSchema = z.object({
+    id: z.string().optional(),
+    index: z.int().nonnegative(),
+    type: z.string(),
+    text: z.string().optional(),
+    signature: z.string().optional(),
+    data: z.string().optional(),
+    summary: z.string().optional(),
+    format: z.string().optional(),
+});
 export const ChatCompletionsAssistantMessageSchema = z.object({
     role: z.literal("assistant"),
     // FUTURE: this should support arrays of TextContentPart and RefusalContentPart
@@ -53,6 +63,10 @@ export const ChatCompletionsAssistantMessageSchema = z.object({
     tool_calls: z.array(ChatCompletionsToolCallSchema).optional(),
     // Extensions
     reasoning_content: z.string().optional().meta({ extension: true }),
+    reasoning_details: z
+        .array(ChatCompletionsReasoningDetailSchema)
+        .optional()
+        .meta({ extension: true }),
     extra_content: z.record(z.string(), z.any()).optional().meta({ extension: true }),
 });
 export const ChatCompletionsToolMessageSchema = z.object({

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import type { ProviderV3 } from "@ai-sdk/provider";
 import type { Tracer } from "@opentelemetry/api";
 import type { ChatCompletions, ChatCompletionsBody, ChatCompletionsChunk } from "./endpoints/chat-completions/schema";
 import type { Embeddings, EmbeddingsBody } from "./endpoints/embeddings/schema";
+import type { Model, ModelList } from "./endpoints/models";
 import type { OpenAIError } from "./errors/openai";
 import type { Logger, LoggerConfig } from "./logger";
 import type { ModelCatalog, ModelId } from "./models/types";
@@ -66,7 +67,7 @@ export type GatewayContext = {
     /**
      * Result returned by the handler (pre-response).
      */
-    result?: ChatCompletions | ReadableStream<ChatCompletionsChunk | OpenAIError> | Embeddings | object;
+    result?: ChatCompletions | ReadableStream<ChatCompletionsChunk | OpenAIError> | Embeddings | Model | ModelList;
     /**
      * Final response returned by the lifecycle.
      */

package/dist/utils/request.js

@@ -5,9 +5,7 @@ export const prepareRequestHeaders = (request) => {
     const existingRequestId = request.headers.get(REQUEST_ID_HEADER);
     if (existingRequestId)
         return;
-    const requestId = request.headers.get("x-correlation-id") ??
-        request.headers.get("x-trace-id") ??
-        crypto.randomUUID();
+    const requestId = "req_" + crypto.getRandomValues(new Uint32Array(2)).reduce((s, n) => s + n.toString(36), "");
     const headers = new Headers(request.headers);
     headers.set(REQUEST_ID_HEADER, requestId);
     return headers;
@@ -27,7 +25,6 @@ export const prepareForwardHeaders = (request) => {
         ? `${userAgent} @hebo-ai/gateway/${GATEWAY_VERSION}`
         : `@hebo-ai/gateway/${GATEWAY_VERSION}`;
     return {
-        [REQUEST_ID_HEADER]: request.headers.get(REQUEST_ID_HEADER),
         "user-agent": appendedUserAgent,
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hebo-ai/gateway",
-  "version": "0.4.0-alpha.2",
+  "version": "0.4.0-alpha.3",
   "description": "AI gateway as a framework. For full control over models, routing & lifecycle. OpenAI-compatible /chat/completions, /embeddings & /models.",
   "keywords": [
     "ai",

package/src/config.ts

@@ -41,16 +41,16 @@ export const parseConfig = (config: GatewayConfig): GatewayConfigParsed => {
   const parsedModels = {} as typeof models;
   const warnings = new Set<string>();
   for (const id in models) {
-    const model = models[id!];
+    const model = models[id]!;
 
     const kept: string[] = [];
 
-    for (const p of model!.providers) {
+    for (const p of model.providers) {
       if (p in parsedProviders) kept.push(p);
       else warnings.add(p);
     }
 
-    if (kept.length > 0) parsedModels[id] = { ...model!, providers: kept };
+    if (kept.length > 0) parsedModels[id] = { ...model, providers: kept };
   }
   for (const warning of warnings) {
     logger.warn(`[config] ${warning} provider removed (not configured)`);

package/src/endpoints/chat-completions/converters.test.ts

@@ -2,7 +2,11 @@ import type { GenerateTextResult, ToolSet, Output } from "ai";
 
 import { describe, expect, test } from "bun:test";
 
-import { convertToTextCallOptions, toChatCompletionsAssistantMessage } from "./converters";
+import {
+  convertToTextCallOptions,
+  toChatCompletionsAssistantMessage,
+  fromChatCompletionsAssistantMessage,
+} from "./converters";
 
 describe("Chat Completions Converters", () => {
   describe("toChatCompletionsAssistantMessage", () => {
@@ -52,6 +56,152 @@ describe("Chat Completions Converters", () => {
         vertex: { thought_signature: "tool-signature" },
       });
     });
+
+    test("should extract reasoning_details from reasoning parts", () => {
+      const mockResult: GenerateTextResult<ToolSet, Output.Output> = {
+        content: [
+          {
+            type: "reasoning",
+            text: "I am thinking...",
+            providerMetadata: {
+              anthropic: {
+                signature: "sig-123",
+              },
+            },
+          } as any,
+          {
+            type: "text",
+            text: "Final answer.",
+          } as any,
+        ],
+        reasoningText: "I am thinking...",
+        toolCalls: [],
+      };
+
+      const message = toChatCompletionsAssistantMessage(mockResult);
+
+      expect(message.reasoning_content).toBe("I am thinking...");
+      expect(message.reasoning_details![0]).toMatchObject({
+        type: "reasoning.text",
+        text: "I am thinking...",
+        signature: "sig-123",
+        format: "unknown",
+        index: 0,
+      });
+      expect(message.reasoning_details![0].id).toStartWith("reasoning-");
+      expect(message.content).toBe("Final answer.");
+    });
+
+    test("should fallback to reasoningText if no reasoning parts in content", () => {
+      const mockResult: GenerateTextResult<ToolSet, Output.Output> = {
+        content: [
+          {
+            type: "text",
+            text: "Hello",
+          } as any,
+        ],
+        reasoningText: "Thinking via text...",
+        toolCalls: [],
+      };
+
+      const message = toChatCompletionsAssistantMessage(mockResult);
+
+      expect(message.reasoning_content).toBe("Thinking via text...");
+      expect(message.reasoning_details![0]).toMatchObject({
+        type: "reasoning.text",
+        text: "Thinking via text...",
+        index: 0,
+      });
+      expect(message.reasoning_details![0].id).toStartWith("reasoning-");
+    });
+
+    test("should handle redacted/encrypted reasoning", () => {
+      const mockResult: GenerateTextResult<ToolSet, Output.Output> = {
+        content: [
+          {
+            type: "reasoning",
+            text: "",
+            providerMetadata: {
+              anthropic: {
+                redactedData: "encrypted-content",
+              },
+            },
+          } as any,
+        ],
+        toolCalls: [],
+      };
+
+      const message = toChatCompletionsAssistantMessage(mockResult);
+
+      expect(message.reasoning_details![0]).toMatchObject({
+        type: "reasoning.encrypted",
+        data: "encrypted-content",
+      });
+      expect((message.reasoning_details![0] as any).text).toBeUndefined();
+      expect(message.reasoning_details![0].signature).toBeUndefined();
+    });
+  });
+
+  describe("fromChatCompletionsAssistantMessage", () => {
+    test("should convert reasoning_details back to reasoning parts with unknown providerOptions", () => {
+      const message = fromChatCompletionsAssistantMessage({
+        role: "assistant",
+        content: "The result is 42.",
+        reasoning_details: [
+          {
+            type: "reasoning.text",
+            text: "Thinking hard...",
+            signature: "sig-xyz",
+            format: "unknown",
+            index: 0,
+          },
+        ],
+      });
+
+      expect(Array.isArray(message.content)).toBe(true);
+      const content = message.content as any[];
+      expect(content).toHaveLength(2);
+      expect(content[0]).toEqual({
+        type: "reasoning",
+        text: "Thinking hard...",
+        providerOptions: {
+          unknown: {
+            signature: "sig-xyz",
+          },
+        },
+      });
+      expect(content[1]).toEqual({
+        type: "text",
+        text: "The result is 42.",
+      });
+    });
+
+    test("should convert reasoning.encrypted back to reasoning parts", () => {
+      const message = fromChatCompletionsAssistantMessage({
+        role: "assistant",
+        content: "Hello",
+        reasoning_details: [
+          {
+            type: "reasoning.encrypted",
+            data: "secret-data",
+            format: "unknown",
+            index: 0,
+          },
+        ],
+      });
+
+      expect(Array.isArray(message.content)).toBe(true);
+      const content = message.content as any[];
+      expect(content[0]).toEqual({
+        type: "reasoning",
+        text: "",
+        providerOptions: {
+          unknown: {
+            redactedData: "secret-data",
+          },
+        },
+      });
+    });
   });
 
   describe("convertToTextCallOptions", () => {

package/src/endpoints/chat-completions/converters.ts

@@ -9,9 +9,11 @@ import type {
   ToolSet,
   ModelMessage,
   UserContent,
+  AssistantContent,
   LanguageModelUsage,
   Output,
   TextStreamPart,
+  ReasoningOutput,
   AssistantModelMessage,
   ToolModelMessage,
   UserModelMessage,
@@ -41,6 +43,7 @@ import type {
   ChatCompletionsToolCallDelta,
   ChatCompletionsReasoningEffort,
   ChatCompletionsReasoningConfig,
+  ChatCompletionsReasoningDetail,
 } from "./schema";
 
 import { GatewayError } from "../../errors/gateway";
@@ -147,35 +150,71 @@ export function fromChatCompletionsUserMessage(
 export function fromChatCompletionsAssistantMessage(
   message: ChatCompletionsAssistantMessage,
 ): AssistantModelMessage {
-  const { tool_calls, role, content, extra_content } = message;
+  const { tool_calls, role, content, extra_content, reasoning_details } = message;
+
+  const parts: AssistantContent = [];
+
+  if (Array.isArray(parts)) {
+    if (reasoning_details?.length) {
+      for (const detail of reasoning_details) {
+        if (detail.text && detail.type === "reasoning.text") {
+          parts.push({
+            type: "reasoning",
+            text: detail.text,
+            providerOptions: detail.signature
+              ? {
+                  unknown: {
+                    signature: detail.signature,
+                  },
+                }
+              : undefined,
+          });
+        } else if (detail.type === "reasoning.encrypted" && detail.data) {
+          parts.push({
+            type: "reasoning",
+            text: "",
+            providerOptions: {
+              unknown: {
+                redactedData: detail.data,
+              },
+            },
+          });
+        }
+      }
+    }
 
-  if (!tool_calls?.length) {
-    const out: AssistantModelMessage = {
-      role: role,
-      content: content ?? "",
-    };
-    if (extra_content) {
-      out.providerOptions = extra_content;
+    if (tool_calls?.length) {
+      for (const tc of tool_calls) {
+        const { id, function: fn, extra_content } = tc;
+        const out: ToolCallPart = {
+          type: "tool-call",
+          toolCallId: id,
+          toolName: fn.name,
+          input: parseToolOutput(fn.arguments).value,
+        };
+        if (extra_content) {
+          out.providerOptions = extra_content;
+        }
+        parts.push(out);
+      }
+    } else if (content !== undefined && content !== null) {
+      parts.push({
+        type: "text",
+        text: content,
+      });
     }
-    return out;
   }
 
-  return {
+  const out: AssistantModelMessage = {
     role: role,
-    content: tool_calls.map((tc: ChatCompletionsToolCall) => {
-      const { id, function: fn, extra_content } = tc;
-      const out: ToolCallPart = {
-        type: "tool-call",
-        toolCallId: id,
-        toolName: fn.name,
-        input: parseToolOutput(fn.arguments).value,
-      };
-      if (extra_content) {
-        out.providerOptions = extra_content;
-      }
-      return out;
-    }),
+    content: Array.isArray(parts) && parts.length > 0 ? parts : (content ?? ""),
   };
+
+  if (extra_content) {
+    out.providerOptions = extra_content;
+  }
+
+  return out;
 }
 
 export function fromChatCompletionsToolResultMessage(
@@ -388,6 +427,7 @@ export class ChatCompletionsStream extends TransformStream<
     const streamId = `chatcmpl-${crypto.randomUUID()}`;
     const creationTime = Math.floor(Date.now() / 1000);
     let toolCallIndexCounter = 0;
+    const reasoningIdToIndex = new Map<string, number>();
 
     const createChunk = (
       delta: ChatCompletionsAssistantMessageDelta,
@@ -425,8 +465,30 @@ export class ChatCompletionsStream extends TransformStream<
           }
 
           case "reasoning-delta": {
+            let index = reasoningIdToIndex.get(part.id);
+            if (index === undefined) {
+              index = reasoningIdToIndex.size;
+              reasoningIdToIndex.set(part.id, index);
+            }
+
             controller.enqueue(
-              createChunk({ reasoning_content: part.text }, part.providerMetadata),
+              createChunk(
+                {
+                  reasoning_content: part.text,
+                  reasoning_details: [
+                    toReasoningDetail(
+                      {
+                        type: "reasoning",
+                        text: part.text,
+                        providerMetadata: part.providerMetadata,
+                      },
+                      part.id,
+                      index,
+                    ),
+                  ],
+                },
+                part.providerMetadata,
+              ),
             );
             break;
           }
@@ -502,23 +564,85 @@ export const toChatCompletionsAssistantMessage = (
     );
   }
 
+  const reasoningDetails: ChatCompletionsReasoningDetail[] = [];
+
   for (const part of result.content) {
     if (part.type === "text") {
-      message.content = part.text;
-      if (part.providerMetadata) {
-        message.extra_content = part.providerMetadata;
+      if (message.content === null) {
+        message.content = part.text;
+        if (part.providerMetadata) {
+          message.extra_content = part.providerMetadata;
+        }
       }
-      break;
+    } else if (part.type === "reasoning") {
+      reasoningDetails.push(
+        toReasoningDetail(part, `reasoning-${crypto.randomUUID()}`, reasoningDetails.length),
+      );
     }
   }
 
   if (result.reasoningText) {
     message.reasoning_content = result.reasoningText;
+
+    if (reasoningDetails.length === 0) {
+      reasoningDetails.push(
+        toReasoningDetail(
+          { type: "reasoning", text: result.reasoningText },
+          `reasoning-${crypto.randomUUID()}`,
+          0,
+        ),
+      );
+    }
+  }
+
+  if (reasoningDetails.length > 0) {
+    message.reasoning_details = reasoningDetails;
   }
 
   return message;
 };
 
+export function toReasoningDetail(
+  reasoning: ReasoningOutput,
+  id: string,
+  index: number,
+): ChatCompletionsReasoningDetail {
+  const providerMetadata = reasoning.providerMetadata ?? {};
+
+  let redactedData: string | undefined;
+  let signature: string | undefined;
+
+  for (const metadata of Object.values(providerMetadata)) {
+    if (metadata && typeof metadata === "object") {
+      if ("redactedData" in metadata && typeof metadata["redactedData"] === "string") {
+        redactedData = metadata["redactedData"];
+      }
+      if ("signature" in metadata && typeof metadata["signature"] === "string") {
+        signature = metadata["signature"];
+      }
+    }
+  }
+
+  if (redactedData) {
+    return {
+      id,
+      index,
+      type: "reasoning.encrypted",
+      data: redactedData,
+      format: "unknown",
+    };
+  }
+
+  return {
+    id,
+    index,
+    type: "reasoning.text",
+    text: reasoning.text,
+    signature,
+    format: "unknown",
+  };
+}
+
 export function toChatCompletionsUsage(usage: LanguageModelUsage): ChatCompletionsUsage {
   const out: ChatCompletionsUsage = {};
 

package/src/endpoints/chat-completions/schema.ts

@@ -62,6 +62,18 @@ export const ChatCompletionsUserMessageSchema = z.object({
 });
 export type ChatCompletionsUserMessage = z.infer<typeof ChatCompletionsUserMessageSchema>;
 
+export const ChatCompletionsReasoningDetailSchema = z.object({
+  id: z.string().optional(),
+  index: z.int().nonnegative(),
+  type: z.string(),
+  text: z.string().optional(),
+  signature: z.string().optional(),
+  data: z.string().optional(),
+  summary: z.string().optional(),
+  format: z.string().optional(),
+});
+export type ChatCompletionsReasoningDetail = z.infer<typeof ChatCompletionsReasoningDetailSchema>;
+
 export const ChatCompletionsAssistantMessageSchema = z.object({
   role: z.literal("assistant"),
   // FUTURE: this should support arrays of TextContentPart and RefusalContentPart
@@ -71,6 +83,10 @@ export const ChatCompletionsAssistantMessageSchema = z.object({
   tool_calls: z.array(ChatCompletionsToolCallSchema).optional(),
   // Extensions
   reasoning_content: z.string().optional().meta({ extension: true }),
+  reasoning_details: z
+    .array(ChatCompletionsReasoningDetailSchema)
+    .optional()
+    .meta({ extension: true }),
   extra_content: z.record(z.string(), z.any()).optional().meta({ extension: true }),
 });
 export type ChatCompletionsAssistantMessage = z.infer<typeof ChatCompletionsAssistantMessageSchema>;

package/src/lifecycle.ts

@@ -37,7 +37,7 @@ export const winterCgHandler = (
       if (onResponse) ctx.response = onResponse;
     } catch (error) {
       logger.error({
-        requestId: resolveRequestId(ctx.request)!,
+        requestId: resolveRequestId(ctx.request),
         err: error instanceof Error ? error : new Error(String(error)),
       });
       ctx.response = toOpenAIErrorResponse(error, prepareResponseInit(ctx.request));

package/src/types.ts

@@ -7,6 +7,7 @@ import type {
   ChatCompletionsChunk,
 } from "./endpoints/chat-completions/schema";
 import type { Embeddings, EmbeddingsBody } from "./endpoints/embeddings/schema";
+import type { Model, ModelList } from "./endpoints/models";
 import type { OpenAIError } from "./errors/openai";
 import type { Logger, LoggerConfig } from "./logger";
 import type { ModelCatalog, ModelId } from "./models/types";
@@ -77,7 +78,8 @@ export type GatewayContext = {
     | ChatCompletions
     | ReadableStream<ChatCompletionsChunk | OpenAIError>
     | Embeddings
-    | object;
+    | Model
+    | ModelList;
   /**
    * Final response returned by the lifecycle.
    */

package/src/utils/request.ts

@@ -10,9 +10,7 @@ export const prepareRequestHeaders = (request: Request) => {
   if (existingRequestId) return;
 
   const requestId =
-    request.headers.get("x-correlation-id") ??
-    request.headers.get("x-trace-id") ??
-    crypto.randomUUID();
+    "req_" + crypto.getRandomValues(new Uint32Array(2)).reduce((s, n) => s + n.toString(36), "");
 
   const headers = new Headers(request.headers);
   headers.set(REQUEST_ID_HEADER, requestId);
@@ -38,7 +36,6 @@ export const prepareForwardHeaders = (request: Request): Record<string, string>
     : `@hebo-ai/gateway/${GATEWAY_VERSION}`;
 
   return {
-    [REQUEST_ID_HEADER]: request.headers.get(REQUEST_ID_HEADER)!,
     "user-agent": appendedUserAgent,
   };
 };