fix(ai): preserve early reasoning details

closes #5114

packages/ai/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed OpenAI-compatible streaming to preserve encrypted `reasoning_details` that arrive before matching tool call deltas ([#5114](https://github.com/earendil-works/pi/issues/5114)).
+
 ## [0.79.9] - 2026-06-20
 
 ### Added

packages/ai/src/providers/openai-completions.ts

@@ -78,6 +78,20 @@ function isImageContentBlock(block: { type: string }): block is ImageContent {
 	return block.type === "image";
 }
 
+function isEncryptedReasoningDetail(detail: unknown): detail is OpenAIEncryptedReasoningDetail {
+	if (typeof detail !== "object" || detail === null) {
+		return false;
+	}
+	const candidate = detail as Record<string, unknown>;
+	return (
+		candidate.type === "reasoning.encrypted" &&
+		typeof candidate.id === "string" &&
+		candidate.id.length > 0 &&
+		typeof candidate.data === "string" &&
+		candidate.data.length > 0
+	);
+}
+
 export interface OpenAICompletionsOptions extends StreamOptions {
 	toolChoice?: "auto" | "none" | "required" | { type: "function"; function: { name: string } };
 	reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
@@ -96,6 +110,12 @@ type ResolvedChatTemplateKwargValue = string | number | boolean | null;
 
 type ChatCompletionInstructionMessageParam = ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam;
 
+type OpenAIEncryptedReasoningDetail = {
+	type: "reasoning.encrypted";
+	id: string;
+	data: string;
+};
+
 type ChatCompletionTextPartWithCacheControl = ChatCompletionContentPartText & {
 	cache_control?: OpenAICompatCacheControl;
 };
@@ -177,6 +197,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions", OpenA
 			let hasFinishReason = false;
 			const toolCallBlocksByIndex = new Map<number, StreamingToolCallBlock>();
 			const toolCallBlocksById = new Map<string, StreamingToolCallBlock>();
+			const pendingReasoningDetailsByToolCallId = new Map<string, string>();
 			const blocks = output.content as StreamingBlock[];
 			const getContentIndex = (block: StreamingBlock) => blocks.indexOf(block);
 			const finishBlock = (block: StreamingBlock) => {
@@ -232,6 +253,16 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions", OpenA
 				}
 				return thinkingBlock;
 			};
+			const applyPendingReasoningDetail = (block: StreamingToolCallBlock) => {
+				if (!block.id) {
+					return;
+				}
+				const pendingReasoningDetail = pendingReasoningDetailsByToolCallId.get(block.id);
+				if (pendingReasoningDetail) {
+					block.thoughtSignature = pendingReasoningDetail;
+					pendingReasoningDetailsByToolCallId.delete(block.id);
+				}
+			};
 			const ensureToolCallBlock = (toolCall: StreamingToolCallDelta) => {
 				const streamIndex = typeof toolCall.index === "number" ? toolCall.index : undefined;
 				let block = streamIndex !== undefined ? toolCallBlocksByIndex.get(streamIndex) : undefined;
@@ -267,6 +298,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions", OpenA
 				if (toolCall.id) {
 					toolCallBlocksById.set(toolCall.id, block);
 				}
+				applyPendingReasoningDetail(block);
 				return block;
 			};
 
@@ -376,15 +408,16 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions", OpenA
 						}
 					}
 
-					const reasoningDetails = (choice.delta as any).reasoning_details;
-					if (reasoningDetails && Array.isArray(reasoningDetails)) {
+					const reasoningDetails = (choice.delta as { reasoning_details?: unknown }).reasoning_details;
+					if (Array.isArray(reasoningDetails)) {
 						for (const detail of reasoningDetails) {
-							if (detail.type === "reasoning.encrypted" && detail.id && detail.data) {
-								const matchingToolCall = output.content.find(
-									(b) => b.type === "toolCall" && b.id === detail.id,
-								) as ToolCall | undefined;
+							if (isEncryptedReasoningDetail(detail)) {
+								const serializedDetail = JSON.stringify(detail);
+								const matchingToolCall = toolCallBlocksById.get(detail.id);
 								if (matchingToolCall) {
-									matchingToolCall.thoughtSignature = JSON.stringify(detail);
+									matchingToolCall.thoughtSignature = serializedDetail;
+								} else {
+									pendingReasoningDetailsByToolCallId.set(detail.id, serializedDetail);
 								}
 							}
 						}

packages/ai/test/openai-completions-reasoning-details.test.ts

@@ -0,0 +1,118 @@
+import { Type } from "typebox";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { streamOpenAICompletions } from "../src/providers/openai-completions.ts";
+import type { AssistantMessage, Model, Tool } from "../src/types.ts";
+
+const mockState = vi.hoisted(() => ({
+	chunkSets: [] as unknown[][],
+	payloads: [] as unknown[],
+}));
+
+vi.mock("openai", () => {
+	class FakeOpenAI {
+		chat = {
+			completions: {
+				create: (payload: unknown) => {
+					mockState.payloads.push(payload);
+					const chunks = mockState.chunkSets.shift() ?? [];
+					const stream = {
+						async *[Symbol.asyncIterator]() {
+							for (const chunk of chunks) {
+								yield chunk;
+							}
+						},
+					};
+					const result = Promise.resolve(stream) as Promise<typeof stream> & {
+						withResponse: () => Promise<{ data: typeof stream; response: { status: number; headers: Headers } }>;
+					};
+					result.withResponse = async () => ({
+						data: stream,
+						response: { status: 200, headers: new Headers() },
+					});
+					return result;
+				},
+			},
+		};
+	}
+	return { default: FakeOpenAI };
+});
+
+const reasoningDetail = { type: "reasoning.encrypted", id: "call_1", data: "encrypted-signature" };
+const readTool: Tool = {
+	name: "read",
+	description: "Read a file",
+	parameters: Type.Object({ path: Type.String() }),
+};
+
+function model(): Model<"openai-completions"> {
+	return {
+		id: "google/gemini-test",
+		name: "Gemini Test",
+		api: "openai-completions",
+		provider: "openrouter",
+		baseUrl: "https://openrouter.ai/api/v1",
+		reasoning: true,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 100_000,
+		maxTokens: 4096,
+	};
+}
+
+function chunk(delta: Record<string, unknown>, finishReason: string | null = null): unknown {
+	return {
+		id: "chatcmpl-test",
+		model: "google/gemini-test",
+		choices: [{ index: 0, delta, finish_reason: finishReason }],
+	};
+}
+
+function toolCallChunk(): unknown {
+	return chunk({
+		tool_calls: [
+			{
+				index: 0,
+				id: "call_1",
+				type: "function",
+				function: { name: "read", arguments: '{"path":"README.md"}' },
+			},
+		],
+	});
+}
+
+async function runOpenAICompletionsStream(messages: AssistantMessage[] = []): Promise<AssistantMessage> {
+	return await streamOpenAICompletions(model(), { messages, tools: [readTool] }, { apiKey: "test" }).result();
+}
+
+function getAssistantPayload(payload: unknown): { reasoning_details?: unknown } | undefined {
+	const messages = (payload as { messages?: Array<{ role?: string; reasoning_details?: unknown }> }).messages ?? [];
+	return messages.find((message) => message.role === "assistant");
+}
+
+describe("openai-completions reasoning_details streaming", () => {
+	beforeEach(() => {
+		mockState.chunkSets = [];
+		mockState.payloads = [];
+	});
+
+	it("preserves reasoning_details that arrive before their matching tool call", async () => {
+		mockState.chunkSets = [
+			[chunk({ reasoning_details: [reasoningDetail] }), toolCallChunk(), chunk({}, "tool_calls")],
+			[chunk({ content: "ok" }), chunk({}, "stop")],
+		];
+
+		const assistantMessage = await runOpenAICompletionsStream();
+		const toolCall = assistantMessage.content.find((block) => block.type === "toolCall");
+		expect(toolCall).toMatchObject({
+			type: "toolCall",
+			id: "call_1",
+			name: "read",
+			arguments: { path: "README.md" },
+			thoughtSignature: JSON.stringify(reasoningDetail),
+		});
+
+		await runOpenAICompletionsStream([assistantMessage]);
+
+		expect(getAssistantPayload(mockState.payloads[1])?.reasoning_details).toEqual([reasoningDetail]);
+	});
+});