@roj-ai/sdk 0.1.34 → 0.1.36

package/src/core/agents/agent.ts

@@ -10,7 +10,7 @@
 import z from 'zod/v4'
 import { DebounceCallback } from '~/core/agents/debounce.js'
 import type { AgentId } from '~/core/agents/schema.js'
-import type { AgentState, HandlerResult } from '~/core/agents/state.js'
+import type { AgentState, HandlerResult, ReasoningDetails, ThinkingBlocks } from '~/core/agents/state.js'
 import { agentEvents } from '~/core/agents/state.js'
 import { withSessionId } from '~/core/events/test-helpers.js'
 import type { FileStore } from '~/core/file-store/types.js'
@@ -51,6 +51,7 @@ import type { Logger } from '../../lib/logger/logger.js'
 import type { SessionContext } from '../sessions/context.js'
 import type { SessionStore } from '../sessions/session-store.js'
 import type { SessionState } from '../sessions/state.js'
+import { resolveAgentOverrides } from '../sessions/state.js'
 import type { SessionEnvironment, ToolExecutor } from '../tools/index.js'
 import type { AgentContext } from './context.js'
 import { sanitizeLLMResponse } from './response-sanitizer.js'
@@ -200,6 +201,22 @@ export class Agent {
 		return this.store.getAgentState(this.id)
 	}
 
+	/**
+	 * Model for the next inference: the session override if one is set, else the
+	 * model from the preset definition.
+	 *
+	 * Resolved per inference rather than frozen at construction so that changing
+	 * the override applies to agents that are already running. Applying it in
+	 * `Session.getAgentConfig()` instead would only reach agents created after the
+	 * change, and catching up the rest would mean rebuilding live Agent instances
+	 * mid-turn — abort controllers, debounce timers and mailbox state included.
+	 */
+	private resolveModel(): ModelId {
+		const definitionName = this.state?.definitionName
+		if (definitionName === undefined) return this.config.model
+		return resolveAgentOverrides(this.store.getState(), definitionName).model ?? this.config.model
+	}
+
 	// ============================================================================
 	// Public API
 	// ============================================================================
@@ -449,7 +466,7 @@ export class Agent {
 		const cachedMessages = applyCacheBreakpoint(messages, extraMessages.length, this.config.cacheTtl, agentState.preamble.length)
 
 		const request: InferenceRequest = {
-			model: this.config.model,
+			model: this.resolveModel(),
 			systemPrompt: this.buildSystemPrompt(),
 			messages: cachedMessages,
 			tools: this.tools.size > 0 ? [...this.tools.values()] : undefined,
@@ -628,7 +645,7 @@ export class Agent {
 
 		// 5. LLM inference (with retry)
 		const request: InferenceRequest = {
-			model: this.config.model,
+			model: this.resolveModel(),
 			systemPrompt: this.buildSystemPrompt(),
 			messages: cachedMessages,
 			tools: this.tools.size > 0 ? [...this.tools.values()] : undefined,
@@ -793,7 +810,7 @@ export class Agent {
 		if (afterResult !== null) {
 			if (afterResult.action === 'pause') {
 				// Commit the turn before pausing so pendingMessages move to conversationHistory.
-				await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics)
+				await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics, llmResponse.value.reasoningDetails, llmResponse.value.thinkingBlocks)
 				await this.consumeDequeuedTokens(pluginDequeued)
 				await this.emitHandlerPause(afterResult.reason)
 				return
@@ -827,7 +844,9 @@ export class Agent {
 
 		// 4d. Inference completed
 		// Tool calls will be executed in the next continue() cycle
-		await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics)
+		// Reasoning travels beside `response`, not inside it: an afterInference handler may
+		// rewrite the text, but the blocks stay the model's own and go back untouched.
+		await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics, llmResponse.value.reasoningDetails, llmResponse.value.thinkingBlocks)
 
 		// Consume dequeue tokens after the commit: a crash in the gap re-delivers the
 		// message on restart (at-least-once) instead of dropping it (consume-first
@@ -852,6 +871,8 @@ export class Agent {
 			cachedTokens?: number
 			cacheWriteTokens?: number
 		},
+		reasoningDetails?: ReasoningDetails,
+		thinkingBlocks?: ThinkingBlocks,
 	): Promise<void> {
 		await this.store.emit(withSessionId(
 			this.store.sessionId,
@@ -865,6 +886,8 @@ export class Agent {
 						name: tc.name,
 						input: tc.input,
 					})),
+					reasoningDetails,
+					thinkingBlocks,
 				},
 				metrics: metrics ?? {
 					promptTokens: 0,

package/src/core/agents/state.ts

@@ -136,6 +136,28 @@ export interface UserLLMMessage {
 	cacheControl?: LLMMessageCacheControl
 }
 
+/**
+ * Provider chain-of-thought blocks, kept opaque (OpenRouter `reasoning_details`).
+ *
+ * The provider requires the exact sequence it produced to come back verbatim, so
+ * these are never parsed, reordered or normalized — only stored and echoed. The
+ * shape is provider- and model-specific and changes without notice; nothing in
+ * the SDK may depend on it.
+ */
+export type ReasoningDetails = unknown[]
+
+/**
+ * Anthropic extended-thinking blocks (`thinking` and `redacted_thinking`), kept opaque
+ * for the same reason as {@link ReasoningDetails}: each carries a `signature` the API
+ * verifies, so an edited block is worse than a missing one.
+ *
+ * Deliberately a separate field rather than sharing `reasoningDetails`. A session can
+ * change model mid-conversation, so one field would eventually put Anthropic-shaped
+ * blocks in front of OpenRouter or the reverse. Two fields make that case degrade to
+ * "absent", which both providers accept, instead of "wrong shape", which neither does.
+ */
+export type ThinkingBlocks = unknown[]
+
 /**
  * Assistant message - LLM response.
  */
@@ -143,6 +165,10 @@ export interface AssistantLLMMessage {
 	role: 'assistant'
 	content: string
 	toolCalls?: ToolCall[]
+	/** Reasoning blocks to echo back on later requests, so the model keeps its chain of thought across tool calls. */
+	reasoningDetails?: ReasoningDetails
+	/** Anthropic thinking blocks to replay on later requests. Required by the API during tool use. */
+	thinkingBlocks?: ThinkingBlocks
 	/** Marks this message as a prompt cache breakpoint. */
 	cacheControl?: LLMMessageCacheControl
 }

package/src/core/context/state.ts

@@ -56,6 +56,10 @@ export const compactedConversationMessageSchema: z4.ZodType<LLMMessage> = z4.dis
 			name: z4.string(),
 			input: z4.unknown(),
 		})).optional(),
+		/** Opaque provider reasoning blocks — retained turns keep them, see ReasoningDetails. */
+		reasoningDetails: z4.array(z4.unknown()).optional(),
+		/** Anthropic thinking blocks — same. */
+		thinkingBlocks: z4.array(z4.unknown()).optional(),
 		cacheControl: cacheControlSchema.optional(),
 	}),
 	z4.object({

package/src/core/llm/anthropic.ts

@@ -48,6 +48,14 @@ interface AnthropicTextBlock {
 interface AnthropicThinkingBlock {
 	type: 'thinking'
 	thinking: string
+	/** Verified by the API when the block is replayed. An edited block is rejected. */
+	signature: string
+}
+
+/** Thinking the API withheld. Opaque, and must still be replayed — see AnthropicThinkingBlock. */
+interface AnthropicRedactedThinkingBlock {
+	type: 'redacted_thinking'
+	data: string
 }
 
 interface AnthropicToolUseBlock {
@@ -57,7 +65,29 @@ interface AnthropicToolUseBlock {
 	input: unknown
 }
 
-type AnthropicContentBlock = AnthropicTextBlock | AnthropicThinkingBlock | AnthropicToolUseBlock
+type AnthropicContentBlock =
+	| AnthropicTextBlock
+	| AnthropicThinkingBlock
+	| AnthropicRedactedThinkingBlock
+	| AnthropicToolUseBlock
+
+const isThinkingBlock = (block: AnthropicContentBlock): block is AnthropicThinkingBlock | AnthropicRedactedThinkingBlock =>
+	block.type === 'thinking' || block.type === 'redacted_thinking'
+
+/**
+ * Narrow a stored block back to a thinking block on the way out.
+ *
+ * `AssistantLLMMessage.thinkingBlocks` is `unknown[]` — the domain layer does not model
+ * provider shapes. This provider wrote those blocks, so it is entitled to recognise them,
+ * but it validates every field it declares rather than assuming. Anything else the API
+ * added travels along untouched, because the block is passed by reference and never rebuilt.
+ */
+const isEchoableThinkingBlock = (value: unknown): value is AnthropicThinkingBlock | AnthropicRedactedThinkingBlock => {
+	if (typeof value !== 'object' || value === null || !('type' in value)) return false
+	if (value.type === 'thinking') return 'thinking' in value && 'signature' in value && typeof value.signature === 'string'
+	if (value.type === 'redacted_thinking') return 'data' in value && typeof value.data === 'string'
+	return false
+}
 
 interface AnthropicMessageResponse {
 	id: string
@@ -121,31 +151,46 @@ interface AnthropicToolResultBlockParam {
 	cache_control?: AnthropicCacheControl
 }
 
-type AnthropicContentBlockParam =
+/** Blocks the API accepts `cache_control` on — everything except a replayed thinking block. */
+type AnthropicCacheableBlockParam =
 	| AnthropicTextBlockParam
 	| AnthropicImageBlockParam
 	| AnthropicToolUseBlockParam
 	| AnthropicToolResultBlockParam
 
+type AnthropicContentBlockParam =
+	| AnthropicCacheableBlockParam
+	| AnthropicThinkingBlock
+	| AnthropicRedactedThinkingBlock
+
+const isCacheableBlock = (block: AnthropicContentBlockParam): block is AnthropicCacheableBlockParam =>
+	block.type !== 'thinking' && block.type !== 'redacted_thinking'
+
 interface AnthropicMessageParam {
 	role: 'user' | 'assistant'
 	content: string | AnthropicContentBlockParam[]
 }
 
 /**
- * Add `cache_control` to the LAST content block of an AnthropicMessageParam,
- * regardless of block type. Converts string content to a single text block
- * first so the mark has a place to live. Mutates in place so the cache
- * breakpoint survives subsequent `mergeConsecutiveMessages`.
+ * Add `cache_control` to the LAST content block of an AnthropicMessageParam that can carry
+ * it. Converts string content to a single text block first so the mark has a place to live.
+ * Mutates in place so the cache breakpoint survives subsequent `mergeConsecutiveMessages`.
+ *
+ * Thinking blocks are skipped: they are replayed byte-for-byte and the API rejects an extra
+ * key on them. They lead the assistant message, so the only case where none of the blocks is
+ * cacheable is a message made of nothing but thinking — which then gets no breakpoint.
  */
 function applyCacheControlToLastBlock(msg: AnthropicMessageParam, cacheControl: AnthropicCacheControl): void {
 	if (typeof msg.content === 'string') {
 		msg.content = [{ type: 'text', text: msg.content, cache_control: cacheControl }]
 		return
 	}
-	if (msg.content.length === 0) return
-	const lastIdx = msg.content.length - 1
-	msg.content[lastIdx] = { ...msg.content[lastIdx], cache_control: cacheControl }
+	for (let i = msg.content.length - 1; i >= 0; i--) {
+		const block = msg.content[i]
+		if (!isCacheableBlock(block)) continue
+		msg.content[i] = { ...block, cache_control: cacheControl }
+		return
+	}
 }
 
 interface AnthropicToolParam {
@@ -283,7 +328,11 @@ export class AnthropicProvider implements RoutableLLMProvider {
 				.map((block) => block.text)
 				.join('')
 
-			const reasoning = data.content
+			// Kept whole, in order, signatures included: the API verifies them on replay.
+			// `redacted_thinking` has no readable text but still has to travel.
+			const thinkingBlocks = data.content.filter(isThinkingBlock)
+
+			const reasoning = thinkingBlocks
 				.filter((block): block is AnthropicThinkingBlock => block.type === 'thinking')
 				.map((block) => block.thinking)
 				.join('')
@@ -315,6 +364,8 @@ export class AnthropicProvider implements RoutableLLMProvider {
 				metrics,
 				providerRequestId: data.id,
 				reasoning: reasoning || undefined,
+				// Normalized to undefined so an empty array never reaches the wire on the way back.
+				thinkingBlocks: thinkingBlocks.length > 0 ? thinkingBlocks : undefined,
 			})
 		} catch (error) {
 			return Err(this.mapError(error))
@@ -399,6 +450,16 @@ export class AnthropicProvider implements RoutableLLMProvider {
 			}
 			case 'assistant': {
 				const contentBlocks: AnthropicContentBlockParam[] = []
+				// Thinking goes first — the API requires the block order the model produced, and
+				// during tool use it requires the blocks to be there at all. All or nothing: a
+				// partial sequence is rejected, so anything unrecognisable drops the whole set
+				// rather than sending a truncated one.
+				const thinking = msg.thinkingBlocks ?? []
+				if (thinking.length > 0 && thinking.every(isEchoableThinkingBlock)) {
+					contentBlocks.push(...thinking)
+				} else if (thinking.length > 0) {
+					this.logger?.warn('Dropping unrecognisable thinking blocks from an assistant message', { count: thinking.length })
+				}
 				if (msg.content) {
 					contentBlocks.push({ type: 'text', text: msg.content })
 				}