@roj-ai/sdk 0.1.29 → 0.1.30

package/src/core/error-recovery.integration.test.ts

@@ -0,0 +1,343 @@
+import { describe, expect, it } from 'bun:test'
+import z from 'zod/v4'
+import type { AgentStatus } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { llmEvents } from '~/core/llm/state.js'
+import { definePlugin } from '~/core/plugins/plugin-builder.js'
+import { createTool } from '~/core/tools/definition.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { toolEvents } from '~/core/tools/state.js'
+import { Ok } from '~/lib/utils/result.js'
+import type { TestSession } from '~/testing/index.js'
+import { createTestPreset, TestHarness } from '~/testing/index.js'
+
+/** Poll until the entry agent reaches the given status (or time out). */
+async function waitForAgentStatus(session: TestSession, status: AgentStatus, timeoutMs = 5000): Promise<void> {
+	const agentId = session.getEntryAgentId()!
+	const deadline = Date.now() + timeoutMs
+	while (Date.now() < deadline) {
+		if (session.state.agents.get(agentId)?.status === status) return
+		await new Promise((r) => setTimeout(r, 10))
+	}
+	throw new Error(`Agent did not reach status '${status}' within ${timeoutMs}ms`)
+}
+
+/** Count conversation-history messages whose content mentions the given text. */
+function countHistoryMentions(session: TestSession, text: string): number {
+	const agentId = session.getEntryAgentId()!
+	const history = session.state.agents.get(agentId)!.conversationHistory
+	return history.filter((m) => JSON.stringify(m.content).includes(text)).length
+}
+
+describe('core: error recovery', () => {
+	// =========================================================================
+	// Retryable LLM errors — outer error-resume backoff
+	// =========================================================================
+
+	describe('retryable LLM error exhaustion', () => {
+		it('backs off between error-resume cycles, notifies parent hook once, and recovers without losing the message', async () => {
+			// Fail 10 LLM calls (2 inference cycles × 5 withLLMRetry attempts), then succeed.
+			let llmCalls = 0
+			const llmProvider = new MockLLMProvider(() => {
+				llmCalls++
+				if (llmCalls <= 10) {
+					throw { type: 'server_error', message: 'boom', retryAfterMs: 1 }
+				}
+				return {
+					content: 'Recovered',
+					toolCalls: [],
+					finishReason: 'stop' as const,
+					metrics: MockLLMProvider.defaultMetrics(),
+				}
+			})
+
+			let onErrorCalls = 0
+			const errorTracker = definePlugin('error-tracker')
+				.hook('onError', async () => {
+					onErrorCalls++
+					return null
+				})
+				.build()
+
+			const preset = createTestPreset()
+			preset.orchestrator.errorResumeBackoff = { baseDelayMs: 50, maxDelayMs: 100 }
+
+			const harness = new TestHarness({
+				presets: [preset],
+				llmProvider,
+				systemPlugins: [errorTracker],
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Trigger outage', { timeoutMs: 10_000 })
+
+			// The message survived the outage: delivered to the LLM exactly once, answered.
+			expect(countHistoryMentions(session, 'Trigger outage')).toBe(1)
+			expect(countHistoryMentions(session, 'Recovered')).toBe(1)
+			expect(llmCalls).toBe(11)
+
+			// Two failed cycles, each resumed exactly once — no unbounded spin.
+			const failed = await session.getEventsByType(llmEvents, 'inference_failed')
+			expect(failed).toHaveLength(2)
+			const resumed = await session.getEventsByType(agentEvents, 'agent_resumed')
+			expect(resumed).toHaveLength(2)
+
+			// The resume waited for the backoff: 50ms after the 1st failure, 100ms after the 2nd.
+			expect(resumed[0].timestamp - failed[0].timestamp).toBeGreaterThanOrEqual(45)
+			expect(resumed[1].timestamp - failed[1].timestamp).toBeGreaterThanOrEqual(90)
+
+			// onError hooks fired once per episode, not once per cycle.
+			expect(onErrorCalls).toBe(1)
+
+			await harness.shutdown()
+		})
+	})
+
+	// =========================================================================
+	// afterInference retry — token consumption deferred to commit
+	// =========================================================================
+
+	describe('afterInference retry', () => {
+		it('pure-message turn: retry re-delivers the message instead of stranding the agent', async () => {
+			const retryOnV1 = definePlugin('retry-on-v1')
+				.hook('afterInference', async (ctx) => {
+					if (ctx.response.content === 'v1') return { action: 'retry' as const }
+					return null
+				})
+				.build()
+
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withSequence([
+					{ content: 'v1' },
+					{ content: 'v2' },
+				]),
+				systemPlugins: [retryOnV1],
+			})
+
+			const session = await harness.createSession('test')
+			// Before the fix this stranded the agent in 'inferring' (mapped to idle) forever.
+			await session.sendAndWaitForIdle('Retry me')
+
+			expect(harness.llmProvider.getCallCount()).toBe(2)
+			const retried = await session.getEventsByType(llmEvents, 'inference_retried')
+			expect(retried).toHaveLength(1)
+
+			// The user message was staged exactly once and the retried response won.
+			expect(countHistoryMentions(session, 'Retry me')).toBe(1)
+			expect(countHistoryMentions(session, 'v2')).toBe(1)
+			expect(countHistoryMentions(session, 'v1')).toBe(0)
+
+			await harness.shutdown()
+		})
+
+		it('tool-result turn: retry does not duplicate tool results in history or in the LLM request', async () => {
+			const retryOnV1 = definePlugin('retry-on-v1')
+				.hook('afterInference', async (ctx) => {
+					if (ctx.response.content === 'v1') return { action: 'retry' as const }
+					return null
+				})
+				.build()
+
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withSequence([
+					{ toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hi!' } }] },
+					{ content: 'v1' },
+					{ content: 'v2' },
+				]),
+				systemPlugins: [retryOnV1],
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Run a tool')
+
+			expect(harness.llmProvider.getCallCount()).toBe(3)
+
+			// The retried request carries the tool result exactly once.
+			const lastRequest = harness.llmProvider.getLastRequest()!
+			expect(lastRequest.messages.filter((m) => m.role === 'tool')).toHaveLength(1)
+
+			// And so does the committed history — duplicates would 400 on the next turn.
+			const agentId = session.getEntryAgentId()!
+			const history = session.state.agents.get(agentId)!.conversationHistory
+			expect(history.filter((m) => m.role === 'tool')).toHaveLength(1)
+			expect(countHistoryMentions(session, 'Run a tool')).toBe(1)
+
+			await harness.shutdown()
+		})
+	})
+
+	// =========================================================================
+	// Pause from tool hooks — turn stops, nothing re-executes
+	// =========================================================================
+
+	describe('pause from tool hooks', () => {
+		const makeCountingTool = (name: string, counter: { count: number }) =>
+			createTool({
+				name,
+				description: `Counting tool ${name}`,
+				input: z.unknown(),
+				execute: async () => {
+					counter.count++
+					return Ok(`${name} done`)
+				},
+			})
+
+		it('beforeToolCall pause stops the multi-tool turn; resume runs every tool exactly once', async () => {
+			const aRuns = { count: 0 }
+			const bRuns = { count: 0 }
+
+			let pausedOnce = false
+			const pauser = definePlugin('pauser')
+				.hook('beforeToolCall', async (ctx) => {
+					if (ctx.toolCall.name === 'tool_a' && !pausedOnce) {
+						pausedOnce = true
+						return { action: 'pause' as const, reason: 'gate' }
+					}
+					return null
+				})
+				.build()
+
+			const preset = createTestPreset()
+			preset.orchestrator.tools = [makeCountingTool('tool_a', aRuns), makeCountingTool('tool_b', bRuns)]
+
+			const harness = new TestHarness({
+				presets: [preset],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [
+							{ id: ToolCallId('ta'), name: 'tool_a', input: {} },
+							{ id: ToolCallId('tb'), name: 'tool_b', input: {} },
+						],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+				systemPlugins: [pauser],
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendMessage('Run tools')
+			await waitForAgentStatus(session, 'paused')
+
+			// Neither tool ran: tool_a was gated pre-start, tool_b must not run while paused.
+			const agentId = session.getEntryAgentId()!
+			expect(aRuns.count).toBe(0)
+			expect(bRuns.count).toBe(0)
+			expect(session.state.agents.get(agentId)!.pendingToolCalls).toHaveLength(2)
+
+			await session.resumeAgent(agentId)
+			await session.waitForIdle()
+
+			// After resume the whole turn ran exactly once per tool.
+			expect(aRuns.count).toBe(1)
+			expect(bRuns.count).toBe(1)
+			const completed = await session.getEventsByType(toolEvents, 'tool_completed')
+			expect(completed).toHaveLength(2)
+
+			await harness.shutdown()
+		})
+
+		it('afterToolCall pause commits the executed tool result and does not re-run it on resume', async () => {
+			const aRuns = { count: 0 }
+			const bRuns = { count: 0 }
+
+			let pausedOnce = false
+			const pauser = definePlugin('pauser')
+				.hook('afterToolCall', async (ctx) => {
+					if (ctx.toolCall.name === 'tool_a' && !pausedOnce) {
+						pausedOnce = true
+						return { action: 'pause' as const, reason: 'checkpoint' }
+					}
+					return null
+				})
+				.build()
+
+			const preset = createTestPreset()
+			preset.orchestrator.tools = [makeCountingTool('tool_a', aRuns), makeCountingTool('tool_b', bRuns)]
+
+			const harness = new TestHarness({
+				presets: [preset],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [
+							{ id: ToolCallId('ta'), name: 'tool_a', input: {} },
+							{ id: ToolCallId('tb'), name: 'tool_b', input: {} },
+						],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+				systemPlugins: [pauser],
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendMessage('Run tools')
+			await waitForAgentStatus(session, 'paused')
+
+			// tool_a ran and its result committed (paired tool_use); tool_b is still pending.
+			const agentId = session.getEntryAgentId()!
+			const agentState = session.state.agents.get(agentId)!
+			expect(aRuns.count).toBe(1)
+			expect(bRuns.count).toBe(0)
+			expect(agentState.pendingToolCalls.map((tc) => tc.name)).toEqual(['tool_b'])
+			expect(agentState.pendingToolResults.map((r) => r.toolName)).toEqual(['tool_a'])
+
+			await session.resumeAgent(agentId)
+			await session.waitForIdle()
+
+			// tool_a's side effects were NOT repeated after resume.
+			expect(aRuns.count).toBe(1)
+			expect(bRuns.count).toBe(1)
+
+			await harness.shutdown()
+		})
+	})
+
+	// =========================================================================
+	// Manual pause during an in-flight inference
+	// =========================================================================
+
+	describe('manual pause during inference', () => {
+		it('pause landing mid-inference is preserved after the turn commits', async () => {
+			let firstCall = true
+			const llmProvider = new MockLLMProvider(async () => {
+				if (firstCall) {
+					firstCall = false
+					await new Promise((r) => setTimeout(r, 150))
+					return { content: 'Late reply', toolCalls: [], finishReason: 'stop' as const, metrics: MockLLMProvider.defaultMetrics() }
+				}
+				return { content: 'After resume', toolCalls: [], finishReason: 'stop' as const, metrics: MockLLMProvider.defaultMetrics() }
+			})
+
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider,
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendMessage('Slow question')
+			await waitForAgentStatus(session, 'inferring')
+
+			const agentId = session.getEntryAgentId()!
+			await session.pauseAgent(agentId, 'user hit pause')
+
+			// Let the in-flight LLM call resolve and the turn commit.
+			await new Promise((r) => setTimeout(r, 300))
+
+			// The pause survived the inference_completed reducer — previously it was
+			// silently clobbered and the agent kept running.
+			const agentState = session.state.agents.get(agentId)!
+			expect(agentState.status).toBe('paused')
+			// The turn itself committed (the response is in history, message consumed).
+			expect(countHistoryMentions(session, 'Late reply')).toBe(1)
+			expect(countHistoryMentions(session, 'Slow question')).toBe(1)
+
+			await session.resumeAgent(agentId)
+			await session.waitForIdle()
+			expect(session.state.agents.get(agentId)!.status).toBe('pending')
+
+			await harness.shutdown()
+		})
+	})
+})

package/src/core/llm/anthropic.test.ts

@@ -354,12 +354,14 @@ describe('AnthropicProvider buildHttpRequest cache placement', () => {
 					{ id: ToolCallId('call_2'), name: 'search', input: { query: 'weather' } },
 				],
 			},
-		], 0)
+			{ role: 'tool', toolCallId: ToolCallId('call_1'), content: 'Sunny' },
+			{ role: 'tool', toolCallId: ToolCallId('call_2'), content: 'Found results' },
+		], 2)
 
 		const http = await createProvider().buildHttpRequest(buildRequest(messages))
 		const msgs = getBodyMessages(http.body)
 
-		const assistant = msgs[msgs.length - 1]
+		const assistant = msgs[msgs.length - 2]
 		expect(assistant.role).toBe('assistant')
 		expect(assistant.content.length).toBe(3) // text + 2 tool_use
 		expect(assistant.content[0].type).toBe('text')
@@ -411,8 +413,9 @@ describe('AnthropicProvider buildHttpRequest cache placement', () => {
 				{ role: 'assistant', content: 'preamble part B' }, // last preamble msg → prefix breakpoint
 				{ role: 'user', content: 'conversation turn' },
 				{ role: 'assistant', content: 'tail reply' }, // tail breakpoint
+				{ role: 'user', content: 'tail continuation' },
 			],
-			0, // no uncached suffix → tailIdx = 3
+			1, // one uncached user suffix → tailIdx = 3
 			undefined,
 			2, // cachedPrefixCount → prefixIdx = 1
 		)
@@ -420,7 +423,7 @@ describe('AnthropicProvider buildHttpRequest cache placement', () => {
 		const http = await createProvider().buildHttpRequest(buildRequest(messages))
 		const msgs = getBodyMessages(http.body)
 
-		expect(msgs.length).toBe(4)
+		expect(msgs.length).toBe(5)
 		// Prefix breakpoint on the last preamble message
 		const prefix = msgs[1]
 		expect(prefix.role).toBe('assistant')

package/src/core/llm/anthropic.ts

@@ -17,6 +17,7 @@ import type {
 	RawInferenceRequest,
 	RawToolSpec,
 } from './provider.js'
+import { ProviderMessageValidationError, sanitizeProviderMessages } from './message-sanitization.js'
 import type { RoutableLLMProvider } from './routing-provider.js'
 
 // ============================================================================
@@ -321,7 +322,8 @@ export class AnthropicProvider implements RoutableLLMProvider {
 	}
 
 	async buildHttpRequest(request: RawInferenceRequest, context?: InferenceContext): Promise<ProviderHttpRequest> {
-		const mappedMessages = await Promise.all(request.messages.map((m) => this.mapMessage(m, context)))
+		const sanitizedMessages = sanitizeProviderMessages(request.messages, this.name, this.logger)
+		const mappedMessages = await Promise.all(sanitizedMessages.map((m) => this.mapMessage(m, context)))
 		const mergedMessages = this.mergeConsecutiveMessages(mappedMessages)
 
 		const body: AnthropicRequestBody = {
@@ -574,6 +576,9 @@ export class AnthropicProvider implements RoutableLLMProvider {
 	}
 
 	private mapError(err: unknown): LLMError {
+		if (err instanceof ProviderMessageValidationError) {
+			return { type: 'invalid_request', message: err.message }
+		}
 		if (err instanceof Error && err.name === 'AbortError') {
 			return { type: 'aborted', message: 'Request was aborted' }
 		}

package/src/core/llm/message-sanitization.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from 'bun:test'
+import type { LLMMessage } from '~/core/agents/state.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import type { LogContext, Logger } from '~/lib/logger/logger.js'
+import { AnthropicProvider } from './anthropic.js'
+import { sanitizeProviderMessages } from './message-sanitization.js'
+import { OpenRouterProvider } from './openrouter.js'
+import type { RawInferenceRequest } from './provider.js'
+import { ModelId } from './schema.js'
+
+type CapturedWarning = {
+	message: string
+	context?: LogContext
+}
+
+const createCapturingLogger = (): { logger: Logger; warnings: CapturedWarning[] } => {
+	const warnings: CapturedWarning[] = []
+	const logger: Logger = {
+		debug: () => {},
+		info: () => {},
+		warn: (message, context) => warnings.push({ message, context }),
+		error: () => {},
+		child: () => logger,
+		level: 'debug',
+	}
+	return { logger, warnings }
+}
+
+const createOpenRouterProvider = (logger?: Logger) =>
+	new OpenRouterProvider({
+		apiKey: 'test-key',
+		imageProcessor: { resolveContent: async (content) => content },
+		logger,
+	})
+
+const createAnthropicProvider = (logger?: Logger) =>
+	new AnthropicProvider({
+		apiKey: 'test-key',
+		imageProcessor: { resolveContent: async (content) => content },
+		logger,
+	})
+
+const buildRequest = (messages: LLMMessage[]): RawInferenceRequest => ({
+	model: ModelId('test-model'),
+	systemPrompt: 'You are helpful.',
+	messages,
+})
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === 'object' && value !== null
+
+const getBodyMessages = (body: unknown): Record<string, unknown>[] => {
+	if (!isRecord(body) || !Array.isArray(body.messages)) {
+		throw new Error('Expected a request body with messages')
+	}
+	return body.messages.map((message) => {
+		if (!isRecord(message)) {
+			throw new Error('Expected each request message to be an object')
+		}
+		return message
+	})
+}
+
+const getContentBlocks = (message: Record<string, unknown>): Record<string, unknown>[] => {
+	if (!Array.isArray(message.content)) {
+		throw new Error('Expected message content blocks')
+	}
+	return message.content.map((block) => {
+		if (!isRecord(block)) {
+			throw new Error('Expected each content block to be an object')
+		}
+		return block
+	})
+}
+
+const wellFormedToolHistory = (): LLMMessage[] => [
+	{ role: 'user', content: 'Check the weather' },
+	{
+		role: 'assistant',
+		content: '',
+		toolCalls: [{ id: ToolCallId('call_1'), name: 'get_weather', input: { city: 'Prague' } }],
+	},
+	{
+		role: 'tool',
+		toolCallId: ToolCallId('call_1'),
+		toolName: 'get_weather',
+		content: 'Sunny',
+	},
+]
+
+const orphanedToolHistory = (): LLMMessage[] => [
+	{ role: 'user', content: 'Check the weather' },
+	{ role: 'assistant', content: 'I will check.' },
+	{
+		role: 'tool',
+		toolCallId: ToolCallId('orphan_1'),
+		toolName: 'get_weather',
+		content: 'Sunny',
+		cacheControl: { type: 'ephemeral' },
+	},
+]
+
+describe('sanitizeProviderMessages', () => {
+	test('returns a well-formed history unchanged', () => {
+		const messages = wellFormedToolHistory()
+		const result = sanitizeProviderMessages(messages, 'test')
+
+		expect(result).toBe(messages)
+		expect(result).toEqual(messages)
+	})
+
+	test('preserves an orphaned tool result as a marked user message and warns', () => {
+		const { logger, warnings } = createCapturingLogger()
+		const result = sanitizeProviderMessages(orphanedToolHistory(), 'test', logger)
+
+		expect(result[result.length - 1]).toEqual({
+			role: 'user',
+			content: '[Orphaned tool result from "get_weather"; tool call ID: orphan_1]\nSunny',
+			cacheControl: { type: 'ephemeral' },
+		})
+		expect(warnings).toEqual([{
+			message: 'Orphaned tool result converted to user message',
+			context: {
+				provider: 'test',
+				messageIndex: 2,
+				toolCallId: 'orphan_1',
+				toolName: 'get_weather',
+			},
+		}])
+	})
+
+	test('rejects a history ending in an assistant message', () => {
+		expect(() => sanitizeProviderMessages([
+			{ role: 'user', content: 'Hello' },
+			{ role: 'assistant', content: 'Hello back' },
+		], 'test')).toThrow('test request history ends with an assistant message after sanitation')
+	})
+})
+
+describe('OpenRouterProvider message sanitation', () => {
+	test('converts a trailing orphan to user without moving its cache breakpoint', async () => {
+		const { logger, warnings } = createCapturingLogger()
+		const request = await createOpenRouterProvider(logger).buildHttpRequest(buildRequest(orphanedToolHistory()))
+		const messages = getBodyMessages(request.body)
+		const last = messages[messages.length - 1]
+		const blocks = getContentBlocks(last)
+
+		expect(last.role).toBe('user')
+		expect(blocks).toEqual([{
+			type: 'text',
+			text: '[Orphaned tool result from "get_weather"; tool call ID: orphan_1]\nSunny',
+			cache_control: { type: 'ephemeral' },
+		}])
+		expect(warnings).toHaveLength(1)
+	})
+
+	test('keeps a matched tool result as a tool message', async () => {
+		const request = await createOpenRouterProvider().buildHttpRequest(buildRequest(wellFormedToolHistory()))
+		const messages = getBodyMessages(request.body)
+		const last = messages[messages.length - 1]
+
+		expect(last).toEqual({
+			role: 'tool',
+			content: 'Sunny',
+			tool_call_id: 'call_1',
+		})
+	})
+
+	test('rejects an assistant tail before issuing a request', async () => {
+		const promise = createOpenRouterProvider().buildHttpRequest(buildRequest([
+			{ role: 'user', content: 'Hello' },
+			{ role: 'assistant', content: 'Hello back' },
+		]))
+
+		await expect(promise).rejects.toThrow('openrouter request history ends with an assistant message after sanitation')
+	})
+})
+
+describe('AnthropicProvider message sanitation', () => {
+	test('converts a trailing orphan to user without moving its cache breakpoint', async () => {
+		const { logger, warnings } = createCapturingLogger()
+		const request = await createAnthropicProvider(logger).buildHttpRequest(buildRequest(orphanedToolHistory()))
+		const messages = getBodyMessages(request.body)
+		const last = messages[messages.length - 1]
+		const blocks = getContentBlocks(last)
+
+		expect(last.role).toBe('user')
+		expect(blocks).toEqual([{
+			type: 'text',
+			text: '[Orphaned tool result from "get_weather"; tool call ID: orphan_1]\nSunny',
+			cache_control: { type: 'ephemeral' },
+		}])
+		expect(warnings).toHaveLength(1)
+	})
+
+	test('keeps a matched tool result as a tool_result block', async () => {
+		const request = await createAnthropicProvider().buildHttpRequest(buildRequest(wellFormedToolHistory()))
+		const messages = getBodyMessages(request.body)
+		const last = messages[messages.length - 1]
+
+		expect(last.role).toBe('user')
+		expect(getContentBlocks(last)).toEqual([{
+			type: 'tool_result',
+			tool_use_id: 'call_1',
+			content: 'Sunny',
+		}])
+	})
+
+	test('rejects an assistant tail before issuing a request', async () => {
+		const promise = createAnthropicProvider().buildHttpRequest(buildRequest([
+			{ role: 'user', content: 'Hello' },
+			{ role: 'assistant', content: 'Hello back' },
+		]))
+
+		await expect(promise).rejects.toThrow('anthropic request history ends with an assistant message after sanitation')
+	})
+})

package/src/core/llm/message-sanitization.ts

@@ -0,0 +1,70 @@
+import type { LLMMessage, ToolLLMMessage, UserLLMMessage } from '~/core/agents/state.js'
+import type { ChatMessageContentItem } from '~/core/llm/llm-log-types.js'
+import type { Logger } from '~/lib/logger/logger.js'
+
+export class ProviderMessageValidationError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'ProviderMessageValidationError'
+	}
+}
+
+const convertOrphanedToolResult = (message: ToolLLMMessage): UserLLMMessage => {
+	const toolName = message.toolName ? ` from "${message.toolName}"` : ''
+	const errorMarker = message.isError ? ' (error)' : ''
+	const marker = `[Orphaned tool result${toolName}; tool call ID: ${message.toolCallId}${errorMarker}]`
+	const markerItem: ChatMessageContentItem = { type: 'text', text: marker }
+	const content = typeof message.content === 'string'
+		? `${marker}\n${message.content}`
+		: [markerItem, ...message.content]
+
+	return {
+		role: 'user',
+		content,
+		cacheControl: message.cacheControl,
+	}
+}
+
+/**
+ * Preserve orphaned tool results as user messages and reject assistant-prefill requests.
+ */
+export const sanitizeProviderMessages = (
+	messages: LLMMessage[],
+	provider: string,
+	logger?: Logger,
+): LLMMessage[] => {
+	const declaredToolCallIds = new Set<string>()
+	let sanitizedMessages: LLMMessage[] | undefined
+
+	for (const [messageIndex, message] of messages.entries()) {
+		if (message.role === 'assistant') {
+			for (const toolCall of message.toolCalls ?? []) {
+				declaredToolCallIds.add(toolCall.id)
+			}
+		}
+
+		if (message.role === 'tool' && !declaredToolCallIds.has(message.toolCallId)) {
+			sanitizedMessages ??= messages.slice(0, messageIndex)
+			sanitizedMessages.push(convertOrphanedToolResult(message))
+			logger?.warn('Orphaned tool result converted to user message', {
+				provider,
+				messageIndex,
+				toolCallId: message.toolCallId,
+				toolName: message.toolName,
+			})
+			continue
+		}
+
+		sanitizedMessages?.push(message)
+	}
+
+	const result = sanitizedMessages ?? messages
+	const lastMessage = result[result.length - 1]
+	if (lastMessage?.role === 'assistant') {
+		throw new ProviderMessageValidationError(
+			`${provider} request history ends with an assistant message after sanitation`,
+		)
+	}
+
+	return result
+}