@roj-ai/sdk 0.1.35 → 0.1.36

package/src/core/llm/openrouter.ts

@@ -1,4 +1,4 @@
-import type { ToolCall } from '~/core/agents/state.js'
+import type { ReasoningDetails, ToolCall } from '~/core/agents/state.js'
 import type { ImageProcessor } from '~/core/image/types.js'
 import type { ChatMessageContentItem } from '~/core/llm/llm-log-types.js'
 import { ToolCallId } from '~/core/tools/schema.js'
@@ -14,6 +14,7 @@ import type {
 	LLMMetrics,
 	LLMProvider,
 	OpenRouterProviderRouting,
+	OpenRouterReasoningOptions,
 	ProviderHttpRequest,
 	RawInferenceRequest,
 } from './provider.js'
@@ -52,6 +53,9 @@ interface OpenRouterChoice {
 	message: {
 		content: string | null | Array<{ type: string; text?: string }>
 		tool_calls?: OpenRouterToolCall[]
+		/** Plaintext chain of thought, when the model exposes one. Display only — the round trip goes through reasoning_details. */
+		reasoning?: string
+		reasoning_details?: ReasoningDetails
 	}
 	finish_reason: string | null
 }
@@ -107,6 +111,7 @@ interface OpenRouterMessage {
 	content: string | OpenRouterContentItem[]
 	tool_calls?: OpenRouterToolCall[]
 	tool_call_id?: string
+	reasoning_details?: ReasoningDetails
 }
 
 /**
@@ -160,6 +165,8 @@ interface OpenRouterRequestBody {
 	stream_options: { include_usage: true }
 	/** Provider routing preferences */
 	provider?: OpenRouterProviderRouting
+	/** Reasoning budget */
+	reasoning?: OpenRouterReasoningOptions
 	/** Routing strategy */
 	route?: 'fallback'
 	/** Model transforms */
@@ -273,6 +280,9 @@ export class OpenRouterProvider implements LLMProvider {
 				finishReason: this.mapFinishReason(choice.finish_reason),
 				metrics,
 				providerRequestId: data.id,
+				reasoning: choice.message.reasoning || undefined,
+				// Normalized to undefined here so an empty array never reaches the wire on the way back.
+				reasoningDetails: choice.message.reasoning_details?.length ? choice.message.reasoning_details : undefined,
 			})
 		} catch (error) {
 			return Err(this.mapError(error))
@@ -317,6 +327,9 @@ export class OpenRouterProvider implements LLMProvider {
 			if (orOpts.providers) {
 				body.provider = orOpts.providers
 			}
+			if (orOpts.reasoning) {
+				body.reasoning = orOpts.reasoning
+			}
 			if (orOpts.route) {
 				body.route = orOpts.route
 			}
@@ -366,19 +379,22 @@ export class OpenRouterProvider implements LLMProvider {
 					tool_call_id: msg.toolCallId,
 				}
 			}
-			case 'assistant':
+			case 'assistant': {
+				const mapped: OpenRouterMessage = { role: 'assistant', content: msg.content }
 				if (msg.toolCalls?.length) {
-					return {
-						role: 'assistant',
-						content: msg.content,
-						tool_calls: msg.toolCalls.map((tc): OpenRouterToolCall => ({
-							id: tc.id,
-							type: 'function',
-							function: { name: tc.name, arguments: JSON.stringify(tc.input) },
-						})),
-					}
+					mapped.tool_calls = msg.toolCalls.map((tc): OpenRouterToolCall => ({
+						id: tc.id,
+						type: 'function',
+						function: { name: tc.name, arguments: JSON.stringify(tc.input) },
+					}))
 				}
-				return { role: 'assistant', content: msg.content }
+				// Echoed verbatim and only when present: the provider rejects an edited or reordered
+				// sequence, and adding the key for a non-reasoning model would rewrite the cached prefix.
+				if (msg.reasoningDetails?.length) {
+					mapped.reasoning_details = msg.reasoningDetails
+				}
+				return mapped
+			}
 			case 'system':
 				return { role: 'system', content: msg.content }
 			case 'user':

package/src/core/llm/provider.ts

@@ -1,4 +1,13 @@
-import type { AssistantLLMMessage, LLMMessage, SystemLLMMessage, ToolCall, ToolLLMMessage, UserLLMMessage } from '~/core/agents/state.js'
+import type {
+	AssistantLLMMessage,
+	LLMMessage,
+	ReasoningDetails,
+	SystemLLMMessage,
+	ThinkingBlocks,
+	ToolCall,
+	ToolLLMMessage,
+	UserLLMMessage,
+} from '~/core/agents/state.js'
 import type { FileStore } from '~/core/file-store/types.js'
 import type { ToolResultContent } from '~/core/llm/llm-log-types.js'
 import type { ToolDefinition } from '~/core/tools/definition.js'
@@ -7,7 +16,7 @@ import type { Result } from '~/lib/utils/result.js'
 import { ModelId } from './schema.js'
 
 // Re-export LLMMessage types from agents/state for backwards compatibility
-export type { AssistantLLMMessage, LLMMessage, SystemLLMMessage, ToolCall, ToolLLMMessage, UserLLMMessage }
+export type { AssistantLLMMessage, LLMMessage, ReasoningDetails, SystemLLMMessage, ThinkingBlocks, ToolCall, ToolLLMMessage, UserLLMMessage }
 
 // ============================================================================
 // Request types
@@ -41,9 +50,37 @@ export interface OpenRouterProviderRouting {
 	quantizations?: string[]
 }
 
+/**
+ * Reasoning controls.
+ *
+ * Without these the model's own default applies, and several of the defaults are expensive:
+ * `high` on Claude Sonnet 5, Opus 5 and Grok 4.5, `max` on Kimi K3. Reasoning is also
+ * `mandatory` on Gemini 3.6 Flash, Grok 4.5 and Kimi K2.7 Code — those cannot be turned off,
+ * only turned down.
+ *
+ * **Which efforts a model accepts differs per model.** The catalog's
+ * `reasoning.supported_efforts` is the authority: Kimi K3 has no `medium`, `minimal` exists
+ * only on Gemini, `xhigh`/`none` only on the OpenAI and newer Anthropic models. The union here
+ * is every value seen across them, not a set any single model takes.
+ *
+ * @see https://openrouter.ai/docs/use-cases/reasoning-tokens
+ */
+export interface OpenRouterReasoningOptions {
+	/** Relative budget. Mutually exclusive with `max_tokens` — set one. */
+	effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+	/** Absolute token budget, for models that take one instead of an effort. */
+	max_tokens?: number
+	/** Explicitly enable reasoning at the model's default effort. */
+	enabled?: boolean
+	/** Reason, but omit the blocks from the response. Note this breaks the round trip. */
+	exclude?: boolean
+}
+
 export interface OpenRouterRequestOptions {
 	/** Provider routing preferences */
 	providers?: OpenRouterProviderRouting
+	/** Reasoning budget. Omitted: the model's own default, which is often `high`. */
+	reasoning?: OpenRouterReasoningOptions
 	/** Routing strategy */
 	route?: 'fallback'
 	/** Model transforms */
@@ -141,8 +178,12 @@ export interface InferenceResponse {
 	metrics: LLMMetrics
 	/** Provider-specific request ID (e.g., OpenRouter generation ID for fetching stats) */
 	providerRequestId?: string
-	/** Extended thinking / reasoning content (for models that support it) */
+	/** Extended thinking / reasoning content (for models that support it) — human-readable, for logs and the debug UI. */
 	reasoning?: string
+	/** Opaque reasoning blocks to echo back on the next request. Absent for models that do not reason. */
+	reasoningDetails?: ReasoningDetails
+	/** Anthropic thinking blocks to replay on the next request. Absent unless extended thinking is enabled. */
+	thinkingBlocks?: ThinkingBlocks
 }
 
 /**

package/src/core/llm/reasoning-details.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from 'bun:test'
+import type { LLMMessage } from '~/core/agents/state.js'
+import { isOk } from '~/lib/utils/result.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { OpenRouterProvider } from './openrouter.js'
+import type { InferenceRequest, RawInferenceRequest } from './provider.js'
+import { ModelId } from './schema.js'
+
+// ============================================================================
+// reasoning_details round trip
+// ============================================================================
+//
+// OpenRouter returns `reasoning_details` on an assistant message and expects the
+// exact sequence back on the following requests, or a reasoning model loses its
+// chain of thought at every tool call. The blocks are opaque, so what matters is
+// that they come back byte-identical — and that a model which never reasons
+// keeps producing the same request bytes, since the prompt cache is keyed on them.
+
+const testModel = ModelId('openai/gpt-5.6-luna')
+
+/** Shape taken from the OpenRouter docs; treated as opaque everywhere in the SDK. */
+const REASONING_DETAILS = [
+	{
+		type: 'reasoning.summary',
+		summary: 'Analyzed the problem by breaking it into components',
+		id: 'reasoning-summary-1',
+		format: 'anthropic-claude-v1',
+		index: 0,
+	},
+	{
+		type: 'reasoning.encrypted',
+		data: 'EroBCkYIBRgCKkCr0hZ0opaque',
+		id: 'reasoning-encrypted-1',
+		format: 'openai-responses-v1',
+		index: 1,
+	},
+]
+
+type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>
+
+const createProvider = (fetchFn?: FetchFn) =>
+	new OpenRouterProvider({
+		apiKey: 'test-key',
+		imageProcessor: { resolveContent: async (content) => content },
+		defaultModel: String(testModel),
+		fetch: fetchFn,
+	})
+
+const respondWith = (message: Record<string, unknown>): FetchFn => async () =>
+	new Response(
+		JSON.stringify({
+			id: 'gen-1',
+			model: String(testModel),
+			choices: [{ message, finish_reason: 'stop' }],
+			usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+		}),
+		{ status: 200, headers: { 'content-type': 'application/json' } },
+	)
+
+const inferenceRequest = (): InferenceRequest => ({
+	model: testModel,
+	systemPrompt: 'You are helpful.',
+	messages: [{ role: 'user', content: 'What is the weather?' }],
+})
+
+const rawRequest = (messages: LLMMessage[]): RawInferenceRequest => ({
+	model: testModel,
+	systemPrompt: 'You are helpful.',
+	messages,
+})
+
+describe('OpenRouter reasoning_details capture', () => {
+	test('captures the blocks and the plaintext reasoning from a response', async () => {
+		const provider = createProvider(respondWith({
+			content: 'It is sunny.',
+			reasoning: 'The user asked about weather, so I check the tool first.',
+			reasoning_details: REASONING_DETAILS,
+		}))
+
+		const result = await provider.inference(inferenceRequest())
+
+		expect(isOk(result)).toBe(true)
+		if (!isOk(result)) return
+		expect(result.value.reasoningDetails).toEqual(REASONING_DETAILS)
+		expect(result.value.reasoning).toBe('The user asked about weather, so I check the tool first.')
+	})
+
+	test('leaves both fields unset for a model that does not reason', async () => {
+		const provider = createProvider(respondWith({ content: 'It is sunny.' }))
+
+		const result = await provider.inference(inferenceRequest())
+
+		expect(isOk(result)).toBe(true)
+		if (!isOk(result)) return
+		expect(result.value.reasoningDetails).toBeUndefined()
+		expect(result.value.reasoning).toBeUndefined()
+	})
+
+	test('normalizes an empty block list to undefined, so nothing is echoed back', async () => {
+		const provider = createProvider(respondWith({ content: 'It is sunny.', reasoning_details: [] }))
+
+		const result = await provider.inference(inferenceRequest())
+
+		expect(isOk(result)).toBe(true)
+		if (!isOk(result)) return
+		expect(result.value.reasoningDetails).toBeUndefined()
+	})
+})
+
+describe('OpenRouter reasoning_details echo', () => {
+	test('sends the blocks back verbatim on the assistant message', async () => {
+		const http = await createProvider().buildHttpRequest(rawRequest([
+			{ role: 'user', content: 'What is the weather?' },
+			{
+				role: 'assistant',
+				content: '',
+				toolCalls: [{ id: ToolCallId('call_1'), name: 'get_weather', input: { city: 'Prague' } }],
+				reasoningDetails: REASONING_DETAILS,
+			},
+			{ role: 'tool', toolCallId: ToolCallId('call_1'), content: 'Sunny' },
+		]))
+
+		// Serialized comparison, because "verbatim" is a claim about the bytes on the
+		// wire — a deep-equal check would pass even if the blocks were rebuilt.
+		const assistant = '{"role":"assistant","content":"","tool_calls":['
+			+ '{"id":"call_1","type":"function","function":{"name":"get_weather","arguments":"{\\"city\\":\\"Prague\\"}"}}'
+			+ `],"reasoning_details":${JSON.stringify(REASONING_DETAILS)}}`
+		expect(JSON.stringify(http.body)).toContain(assistant)
+	})
+
+	test('echoes the blocks on an assistant message that made no tool call', async () => {
+		const http = await createProvider().buildHttpRequest(rawRequest([
+			{ role: 'user', content: 'Think about it.' },
+			{ role: 'assistant', content: 'Thought about it.', reasoningDetails: REASONING_DETAILS },
+			{ role: 'user', content: 'And now?' },
+		]))
+
+		expect(JSON.stringify(http.body)).toContain(
+			`{"role":"assistant","content":"Thought about it.","reasoning_details":${JSON.stringify(REASONING_DETAILS)}}`,
+		)
+	})
+})
+
+describe('OpenRouter request bytes without reasoning', () => {
+	// The prompt cache is keyed on the serialized prefix, so a key that appears
+	// even as `null`/`undefined` for a non-reasoning model would rewrite it.
+	test('adds nothing to a plain assistant message', async () => {
+		const http = await createProvider().buildHttpRequest(rawRequest([
+			{ role: 'user', content: 'What is 2+2?' },
+			{ role: 'assistant', content: '4' },
+			{ role: 'user', content: 'And 3+3?' },
+		]))
+
+		const body = JSON.stringify(http.body)
+		expect(body).toContain('{"role":"assistant","content":"4"}')
+		expect(body).not.toContain('reasoning')
+	})
+
+	test('adds nothing to an assistant message with tool calls', async () => {
+		const http = await createProvider().buildHttpRequest(rawRequest([
+			{ role: 'user', content: 'What is the weather?' },
+			{
+				role: 'assistant',
+				content: '',
+				toolCalls: [{ id: ToolCallId('call_1'), name: 'get_weather', input: { city: 'Prague' } }],
+			},
+			{ role: 'tool', toolCallId: ToolCallId('call_1'), content: 'Sunny' },
+		]))
+
+		const body = JSON.stringify(http.body)
+		expect(body).toContain(
+			'{"role":"assistant","content":"","tool_calls":['
+			+ '{"id":"call_1","type":"function","function":{"name":"get_weather","arguments":"{\\"city\\":\\"Prague\\"}"}}]}',
+		)
+		expect(body).not.toContain('reasoning')
+	})
+})

package/src/core/llm/state.ts

@@ -48,6 +48,9 @@ export type LLMMetrics = {
 // LLM events
 // ============================================================================
 
+/** Opaque by design — provider chain-of-thought blocks are stored and echoed verbatim, never inspected. */
+const opaqueBlocksSchema = z4.array(z4.unknown())
+
 const llmMetricsSchema = z4.object({
 	promptTokens: z4.number(),
 	completionTokens: z4.number(),
@@ -77,6 +80,15 @@ export const llmEvents = createEventsFactory({
 					name: z4.string(),
 					input: z4.unknown(),
 				})),
+				/**
+				 * Opaque provider reasoning blocks (see ReasoningDetails). Carried by the
+				 * event, not just by the live response, because a session rebuilt from the
+				 * log would otherwise resume without the chain of thought the provider
+				 * expects to get back.
+				 */
+				reasoningDetails: opaqueBlocksSchema.optional(),
+				/** Anthropic thinking blocks (see ThinkingBlocks). Carried for the same reason. */
+				thinkingBlocks: opaqueBlocksSchema.optional(),
 			}),
 			metrics: llmMetricsSchema,
 			llmCallId: llmCallIdSchema.optional(),