@roj-ai/sdk 0.0.2

package/src/core/llm/routing-provider.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from 'bun:test'
+import type { Result } from '~/lib/utils/result.js'
+import { Ok } from '~/lib/utils/result.js'
+import type { InferenceContext, InferenceRequest, InferenceResponse, LLMError, LLMProvider } from './provider.js'
+import type { RoutableLLMProvider } from './routing-provider.js'
+import { RoutingLLMProvider } from './routing-provider.js'
+import { ModelId } from './schema.js'
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const createRequest = (model: string): InferenceRequest => ({
+	model: ModelId(model),
+	systemPrompt: 'test',
+	messages: [{ role: 'user', content: 'Hello' }],
+})
+
+const createMockProvider = (name: string, prefix: string): RoutableLLMProvider & { lastModel?: string } => {
+	const provider: RoutableLLMProvider & { lastModel?: string } = {
+		name,
+		canHandle: (model: string) => model.startsWith(prefix),
+		normalizeModel: (model: string) => model.startsWith(`${prefix}/`) ? model.slice(prefix.length + 1) : model,
+		async inference(request: InferenceRequest): Promise<Result<InferenceResponse, LLMError>> {
+			provider.lastModel = request.model
+			return Ok({
+				content: `Response from ${name}`,
+				toolCalls: [],
+				finishReason: 'stop',
+				metrics: { promptTokens: 10, completionTokens: 5, totalTokens: 15, latencyMs: 100, model: request.model },
+			})
+		},
+	}
+	return provider
+}
+
+const createMockFallback = (name: string): LLMProvider & { lastModel?: string } => {
+	const provider: LLMProvider & { lastModel?: string } = {
+		name,
+		async inference(request: InferenceRequest): Promise<Result<InferenceResponse, LLMError>> {
+			provider.lastModel = request.model
+			return Ok({
+				content: `Response from ${name}`,
+				toolCalls: [],
+				finishReason: 'stop',
+				metrics: { promptTokens: 10, completionTokens: 5, totalTokens: 15, latencyMs: 100, model: request.model },
+			})
+		},
+	}
+	return provider
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('RoutingLLMProvider', () => {
+	test('routes to matching provider', async () => {
+		const anthropic = createMockProvider('anthropic', 'anthropic')
+		const fallback = createMockFallback('openrouter')
+
+		const router = new RoutingLLMProvider([anthropic], fallback)
+		const result = await router.inference(createRequest('anthropic/claude-sonnet-4.5'))
+
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.content).toBe('Response from anthropic')
+		}
+		// Model should be normalized (prefix stripped)
+		expect(anthropic.lastModel).toBe('claude-sonnet-4.5')
+	})
+
+	test('falls back to fallback provider when no match', async () => {
+		const anthropic = createMockProvider('anthropic', 'anthropic')
+		const fallback = createMockFallback('openrouter')
+
+		const router = new RoutingLLMProvider([anthropic], fallback)
+		const result = await router.inference(createRequest('openai/gpt-4o'))
+
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.content).toBe('Response from openrouter')
+		}
+		// Model should be passed through unchanged to fallback
+		expect(fallback.lastModel).toBe('openai/gpt-4o')
+	})
+
+	test('returns error when no provider matches and no fallback', async () => {
+		const anthropic = createMockProvider('anthropic', 'anthropic')
+
+		const router = new RoutingLLMProvider([anthropic])
+		const result = await router.inference(createRequest('openai/gpt-4o'))
+
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.type).toBe('invalid_request')
+		}
+	})
+
+	test('first matching provider wins', async () => {
+		const provider1 = createMockProvider('provider1', 'claude')
+		const provider2 = createMockProvider('provider2', 'claude')
+		const fallback = createMockFallback('fallback')
+
+		const router = new RoutingLLMProvider([provider1, provider2], fallback)
+		const result = await router.inference(createRequest('claude-sonnet-4.5'))
+
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.content).toBe('Response from provider1')
+		}
+	})
+})

package/src/core/llm/routing-provider.ts

@@ -0,0 +1,86 @@
+/**
+ * RoutingLLMProvider - Routes requests to the appropriate provider based on model ID.
+ *
+ * Each registered provider declares which models it can handle via `canHandle()`.
+ * The last registered provider acts as the fallback (typically OpenRouter).
+ */
+
+import type { Result } from '~/lib/utils/result.js'
+import { Err } from '~/lib/utils/result.js'
+import type {
+	InferenceContext,
+	InferenceRequest,
+	InferenceResponse,
+	LLMError,
+	LLMProvider,
+	ProviderHttpRequest,
+	RawInferenceRequest,
+} from './provider.js'
+import { ModelId } from './schema.js'
+
+/**
+ * A provider that can declare which models it supports.
+ */
+export interface RoutableLLMProvider extends LLMProvider {
+	/** Returns true if this provider can handle the given model ID. */
+	canHandle(model: string): boolean
+	/** Normalizes the model ID for this provider (e.g. strips vendor prefix). */
+	normalizeModel(model: string): string
+}
+
+/**
+ * Routes inference requests to the appropriate provider based on model ID.
+ * Providers are checked in order; first match wins.
+ * If no provider matches, the fallback provider is used.
+ */
+export class RoutingLLMProvider implements LLMProvider {
+	readonly name = 'routing'
+
+	constructor(
+		private readonly providers: RoutableLLMProvider[],
+		private readonly fallback?: LLMProvider,
+	) {}
+
+	async inference(
+		request: InferenceRequest,
+		context?: InferenceContext,
+	): Promise<Result<InferenceResponse, LLMError>> {
+		const model = request.model
+
+		for (const provider of this.providers) {
+			if (provider.canHandle(model)) {
+				const normalizedModel = ModelId(provider.normalizeModel(model))
+				return provider.inference({ ...request, model: normalizedModel }, context)
+			}
+		}
+
+		if (this.fallback) {
+			return this.fallback.inference(request, context)
+		}
+
+		return Err({
+			type: 'invalid_request',
+			message: `No provider available for model: ${model}`,
+		})
+	}
+
+	async buildHttpRequest(
+		request: RawInferenceRequest,
+		context?: InferenceContext,
+	): Promise<ProviderHttpRequest> {
+		const model = request.model
+
+		for (const provider of this.providers) {
+			if (provider.canHandle(model) && provider.buildHttpRequest) {
+				const normalizedModel = ModelId(provider.normalizeModel(model))
+				return provider.buildHttpRequest({ ...request, model: normalizedModel }, context)
+			}
+		}
+
+		if (this.fallback?.buildHttpRequest) {
+			return this.fallback.buildHttpRequest(request, context)
+		}
+
+		throw new Error(`No provider with buildHttpRequest available for model: ${model}`)
+	}
+}

package/src/core/llm/schema.ts

@@ -0,0 +1,47 @@
+/**
+ * LLM domain types and schemas
+ *
+ * Contains all types related to LLM:
+ * - Branded ID types and constructors (LLMCallId, ModelId)
+ * - LLM response types
+ * - Zod schemas for validation
+ */
+
+import { uuidv7 } from 'uuidv7'
+import z from 'zod/v4'
+import type { LLMToolCall } from './state'
+
+// ============================================================================
+// LLMCallId - Branded type
+// ============================================================================
+
+/** LLMCallId schema - validates any string and brands as LLMCallId. */
+export const llmCallIdSchema = z.string().brand('LLMCallId')
+
+/** Branded LLMCallId type */
+export type LLMCallId = z.infer<typeof llmCallIdSchema>
+
+/** Constructor for LLMCallId */
+export const LLMCallId = (id: string): LLMCallId => id as LLMCallId
+
+/** Generate a new LLMCallId (UUIDv7) */
+export const generateLLMCallId = (): LLMCallId => LLMCallId(uuidv7())
+
+// ============================================================================
+// LLMCallId - Zod schemas
+// ============================================================================
+
+// ============================================================================
+// ModelId - Branded type
+// ============================================================================
+
+/** ModelId schema - validates any string and brands as ModelId. */
+export const modelIdSchema = z.string().brand('ModelId')
+
+/** Branded ModelId type */
+export type ModelId = z.infer<typeof modelIdSchema>
+
+/** Constructor for ModelId */
+export const ModelId = (id: string): ModelId => id as ModelId
+
+// LLMResponse, LLMMetrics, and LLMToolCall are now defined in ./state.ts

package/src/core/llm/snapshot-fetch.ts

@@ -0,0 +1,158 @@
+/**
+ * Snapshot-caching fetch wrapper for integration tests.
+ *
+ * On first run (or when request changes), makes a real HTTP call and saves
+ * the request+response pair to a JSON snapshot file. On subsequent runs
+ * with the same request, returns the cached response without making a call.
+ *
+ * Usage:
+ *   const fetch = createSnapshotFetch(snapshotsDir)
+ *   const provider = new AnthropicProvider({ ..., fetch })
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+interface SnapshotEntry {
+	requestHash: string
+	request: {
+		url: string
+		method: string
+		headers: Record<string, string>
+		body: unknown
+	}
+	response: {
+		status: number
+		headers: Record<string, string>
+		body: unknown
+	}
+}
+
+/**
+ * Deterministic hash of a request (URL + method + body).
+ * Headers are excluded because auth headers change between runs.
+ */
+function hashRequest(url: string, method: string, body: string): string {
+	const hash = createHash('sha256')
+	hash.update(method)
+	hash.update(url)
+	hash.update(stableStringify(JSON.parse(body)))
+	return hash.digest('hex').slice(0, 16)
+}
+
+/**
+ * JSON.stringify with sorted keys for deterministic output.
+ */
+function stableStringify(value: unknown): string {
+	return JSON.stringify(value, (_key, val) => {
+		if (val && typeof val === 'object' && !Array.isArray(val)) {
+			return Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b)))
+		}
+		return val
+	})
+}
+
+/**
+ * Strip sensitive headers (auth) from a headers object for snapshot storage.
+ */
+function sanitizeHeaders(headers: Record<string, string>): Record<string, string> {
+	const result: Record<string, string> = {}
+	for (const [key, value] of Object.entries(headers)) {
+		const lower = key.toLowerCase()
+		if (lower === 'authorization' || lower === 'x-api-key') continue
+		result[key] = value
+	}
+	return result
+}
+
+/**
+ * Create a fetch function that caches request/response pairs as JSON snapshots.
+ *
+ * @param snapshotsDir - Directory to store snapshot files
+ * @param testName - Test name used as the snapshot filename
+ */
+type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>
+
+export function createSnapshotFetch(
+	snapshotsDir: string,
+	testName: string,
+): FetchFn {
+	const snapshotPath = join(snapshotsDir, `${testName}.json`)
+
+	return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+		const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
+		const method = init?.method ?? 'GET'
+		const body = typeof init?.body === 'string' ? init.body : ''
+
+		const currentHash = hashRequest(url, method, body)
+
+		// Try loading existing snapshot
+		let snapshot: SnapshotEntry | null = null
+		try {
+			const content = await readFile(snapshotPath, 'utf-8')
+			snapshot = JSON.parse(content) as SnapshotEntry
+		} catch {
+			// No snapshot yet
+		}
+
+		// If snapshot exists and hash matches, return cached response
+		if (snapshot && snapshot.requestHash === currentHash) {
+			return new Response(JSON.stringify(snapshot.response.body), {
+				status: snapshot.response.status,
+				headers: snapshot.response.headers,
+			})
+		}
+
+		// Make real request
+		const response = await globalThis.fetch(input, init)
+		const responseBody = await response.json()
+
+		// Extract response headers
+		const responseHeaders: Record<string, string> = {}
+		response.headers.forEach((value, key) => {
+			responseHeaders[key] = value
+		})
+
+		// Extract request headers
+		const requestHeaders: Record<string, string> = {}
+		if (init?.headers) {
+			if (init.headers instanceof Headers) {
+				init.headers.forEach((value, key) => {
+					requestHeaders[key] = value
+				})
+			} else if (Array.isArray(init.headers)) {
+				for (const [key, value] of init.headers) {
+					requestHeaders[key] = value
+				}
+			} else {
+				Object.assign(requestHeaders, init.headers)
+			}
+		}
+
+		// Save snapshot
+		const entry: SnapshotEntry = {
+			requestHash: currentHash,
+			request: {
+				url,
+				method,
+				headers: sanitizeHeaders(requestHeaders),
+				body: body ? JSON.parse(body) : null,
+			},
+			response: {
+				status: response.status,
+				headers: sanitizeHeaders(responseHeaders),
+				body: responseBody,
+			},
+		}
+
+		await mkdir(snapshotsDir, { recursive: true })
+		await writeFile(snapshotPath, JSON.stringify(entry, null, '\t'))
+
+		// Return a new Response from the parsed body (original was consumed)
+		return new Response(JSON.stringify(responseBody), {
+			status: response.status,
+			headers: responseHeaders,
+		})
+	}
+}

package/src/core/llm/snapshot-middleware.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Err, Ok, isErr, isOk } from '~/lib/utils/result.js'
+import { applyMiddleware } from './middleware.js'
+import { MockLLMProvider } from './mock.js'
+import type { InferenceRequest, InferenceResponse } from './provider.js'
+import { ModelId } from './schema.js'
+import { createSnapshotLLMMiddleware } from './snapshot-middleware.js'
+
+describe('SnapshotLLMMiddleware', () => {
+	let dir: string
+
+	beforeEach(() => {
+		dir = mkdtempSync(join(tmpdir(), 'roj-snap-'))
+	})
+
+	afterEach(() => {
+		rmSync(dir, { recursive: true, force: true })
+	})
+
+	const request = (overrides: Partial<InferenceRequest> = {}): InferenceRequest => ({
+		model: ModelId('test-model'),
+		systemPrompt: 'You are a test assistant.',
+		messages: [{ role: 'user', content: 'Hello' }],
+		...overrides,
+	})
+
+	const fixedResponse: InferenceResponse = {
+		content: 'Recorded response',
+		toolCalls: [],
+		finishReason: 'stop',
+		metrics: MockLLMProvider.defaultMetrics(),
+	}
+
+	test('records on miss and replays on hit without calling next', async () => {
+		const downstream = new MockLLMProvider(() => fixedResponse)
+		const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })])
+
+		const first = await wrapped.inference(request())
+		expect(isOk(first)).toBe(true)
+		expect(downstream.getCallCount()).toBe(1)
+
+		// Snapshot file created
+		const files = readdirSync(dir)
+		expect(files.length).toBe(1)
+		expect(files[0]).toMatch(/^[0-9a-f]{16}\.json$/)
+
+		// Replay — downstream NOT called again
+		const second = await wrapped.inference(request())
+		expect(isOk(second)).toBe(true)
+		if (isOk(second)) {
+			expect(second.value.content).toBe('Recorded response')
+		}
+		expect(downstream.getCallCount()).toBe(1)
+	})
+
+	test('distinct requests produce distinct snapshot files', async () => {
+		const downstream = new MockLLMProvider(() => fixedResponse)
+		const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })])
+
+		await wrapped.inference(request({ messages: [{ role: 'user', content: 'A' }] }))
+		await wrapped.inference(request({ messages: [{ role: 'user', content: 'B' }] }))
+
+		expect(readdirSync(dir).length).toBe(2)
+		expect(downstream.getCallCount()).toBe(2)
+	})
+
+	test('hash is stable across key-order differences', async () => {
+		const downstream = new MockLLMProvider(() => fixedResponse)
+		const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })])
+
+		// Two requests identical in content but constructed with different key order
+		await wrapped.inference({
+			model: ModelId('m'),
+			systemPrompt: 's',
+			messages: [{ role: 'user', content: 'x' }],
+			temperature: 0.5,
+			maxTokens: 100,
+		})
+		await wrapped.inference({
+			maxTokens: 100,
+			temperature: 0.5,
+			messages: [{ role: 'user', content: 'x' }],
+			systemPrompt: 's',
+			model: ModelId('m'),
+		})
+
+		// Same hash → single snapshot file → downstream called once
+		expect(readdirSync(dir).length).toBe(1)
+		expect(downstream.getCallCount()).toBe(1)
+	})
+
+	test('replay mode errors on miss', async () => {
+		const downstream = new MockLLMProvider(() => fixedResponse)
+		const wrapped = applyMiddleware(downstream, [
+			createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'replay' }),
+		])
+
+		const result = await wrapped.inference(request())
+		expect(isErr(result)).toBe(true)
+		if (isErr(result)) {
+			expect(result.error.type).toBe('invalid_request')
+			expect(result.error.message).toContain('Snapshot not found')
+		}
+		expect(downstream.getCallCount()).toBe(0)
+	})
+
+	test('replay mode serves existing snapshot', async () => {
+		// Pre-seed a snapshot by running once in auto mode
+		const downstream1 = new MockLLMProvider(() => fixedResponse)
+		const recording = applyMiddleware(downstream1, [createSnapshotLLMMiddleware({ snapshotsDir: dir })])
+		await recording.inference(request())
+
+		// Now a replay-only chain must hit it
+		const downstream2 = new MockLLMProvider(() => {
+			throw new Error('should not be called')
+		})
+		const replaying = applyMiddleware(downstream2, [
+			createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'replay' }),
+		])
+		const result = await replaying.inference(request())
+		expect(isOk(result)).toBe(true)
+		if (isOk(result)) {
+			expect(result.value.content).toBe('Recorded response')
+		}
+	})
+
+	test('record mode overwrites existing snapshot', async () => {
+		// Seed with response A
+		const downstream1 = new MockLLMProvider(() => ({ ...fixedResponse, content: 'A' }))
+		const first = applyMiddleware(downstream1, [createSnapshotLLMMiddleware({ snapshotsDir: dir })])
+		await first.inference(request())
+
+		// Force re-record with response B
+		const downstream2 = new MockLLMProvider(() => ({ ...fixedResponse, content: 'B' }))
+		const second = applyMiddleware(downstream2, [
+			createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'record' }),
+		])
+		await second.inference(request())
+
+		// Read back
+		const downstream3 = new MockLLMProvider(() => {
+			throw new Error('should not be called')
+		})
+		const third = applyMiddleware(downstream3, [
+			createSnapshotLLMMiddleware({ snapshotsDir: dir, mode: 'replay' }),
+		])
+		const result = await third.inference(request())
+		expect(isOk(result)).toBe(true)
+		if (isOk(result)) {
+			expect(result.value.content).toBe('B')
+		}
+	})
+
+	test('does not persist error responses', async () => {
+		const downstream = new MockLLMProvider(() => {
+			const err = { type: 'rate_limit' as const, message: 'throttled' }
+			throw err
+		})
+		const wrapped = applyMiddleware(downstream, [createSnapshotLLMMiddleware({ snapshotsDir: dir })])
+
+		const result = await wrapped.inference(request())
+		expect(isErr(result)).toBe(true)
+		expect(readdirSync(dir).length).toBe(0)
+	})
+})