@roj-ai/sdk 0.1.35 → 0.2.1

package/src/core/llm/anthropic.ts

@@ -17,7 +17,9 @@ import type {
 	RawInferenceRequest,
 	RawToolSpec,
 } from './provider.js'
-import { ProviderMessageValidationError, sanitizeProviderMessages } from './message-sanitization.js'
+import { mapProviderError } from './provider.js'
+import { ProviderRequestAbortError, runProviderRequest } from './provider-request.js'
+import { sanitizeProviderMessages } from './message-sanitization.js'
 import type { RoutableLLMProvider } from './routing-provider.js'
 
 // ============================================================================
@@ -48,6 +50,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 +67,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 +153,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 {
@@ -245,18 +292,8 @@ export class AnthropicProvider implements RoutableLLMProvider {
 			}
 
 			const httpRequest = await this.buildHttpRequest(rawRequest, context)
-
-			const controller = new AbortController()
-			const timeoutId = setTimeout(() => controller.abort(), this.timeout)
-
-			// Combine with external signal if provided
-			if (context?.signal) {
-				context.signal.addEventListener('abort', () => controller.abort(), { once: true })
-			}
-
-			let response: Response
-			try {
-				response = await this.fetchFn(httpRequest.url, {
+			return await runProviderRequest({ callerSignal: context?.signal, timeoutMs: this.timeout }, async (signal) => {
+				const response = await this.fetchFn(httpRequest.url, {
 					method: httpRequest.method,
 					headers: {
 						...httpRequest.headers,
@@ -264,60 +301,70 @@ export class AnthropicProvider implements RoutableLLMProvider {
 						'anthropic-dangerous-direct-browser-access': 'true',
 					},
 					body: JSON.stringify(httpRequest.body),
-					signal: controller.signal,
+					signal,
 				})
-			} finally {
-				clearTimeout(timeoutId)
-			}
 
-			if (!response.ok) {
-				const body = await response.text()
-				return Err(this.mapHttpError(response.status, body))
-			}
+				if (!response.ok) {
+					const body = await response.text()
+					return Err(this.mapHttpError(response.status, body))
+				}
 
-			const data = await response.json() as AnthropicMessageResponse
-			const latencyMs = Date.now() - startTime
-
-			const textContent = data.content
-				.filter((block): block is AnthropicTextBlock => block.type === 'text')
-				.map((block) => block.text)
-				.join('')
-
-			const reasoning = data.content
-				.filter((block): block is AnthropicThinkingBlock => block.type === 'thinking')
-				.map((block) => block.thinking)
-				.join('')
-
-			const toolCalls: ToolCall[] = data.content
-				.filter((block): block is AnthropicToolUseBlock => block.type === 'tool_use')
-				.map((block) => ({
-					id: ToolCallId(block.id),
-					name: block.name,
-					input: block.input,
-				}))
-
-			const metrics: LLMMetrics = {
-				promptTokens: data.usage.input_tokens,
-				completionTokens: data.usage.output_tokens,
-				totalTokens: data.usage.input_tokens + data.usage.output_tokens,
-				latencyMs,
-				model: data.model,
-				provider: this.name,
-				cost: this.calculateCost(data.model, data.usage),
-				cachedTokens: data.usage.cache_read_input_tokens || undefined,
-				cacheWriteTokens: data.usage.cache_creation_input_tokens || undefined,
-			}
+				const data = await response.json() as AnthropicMessageResponse
+				const latencyMs = Date.now() - startTime
+
+				const textContent = data.content
+					.filter((block): block is AnthropicTextBlock => block.type === 'text')
+					.map((block) => block.text)
+					.join('')
+
+				// 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('')
+
+				const toolCalls: ToolCall[] = data.content
+					.filter((block): block is AnthropicToolUseBlock => block.type === 'tool_use')
+					.map((block) => ({
+						id: ToolCallId(block.id),
+						name: block.name,
+						input: block.input,
+					}))
+
+				const metrics: LLMMetrics = {
+					promptTokens: data.usage.input_tokens,
+					completionTokens: data.usage.output_tokens,
+					totalTokens: data.usage.input_tokens + data.usage.output_tokens,
+					latencyMs,
+					model: data.model,
+					provider: this.name,
+					cost: this.calculateCost(data.model, data.usage),
+					cachedTokens: data.usage.cache_read_input_tokens || undefined,
+					cacheWriteTokens: data.usage.cache_creation_input_tokens || undefined,
+				}
 
-			return Ok({
-				content: textContent || null,
-				toolCalls,
-				finishReason: this.mapStopReason(data.stop_reason),
-				metrics,
-				providerRequestId: data.id,
-				reasoning: reasoning || undefined,
+				return Ok({
+					content: textContent || null,
+					toolCalls,
+					finishReason: this.mapStopReason(data.stop_reason),
+					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))
+			if (error instanceof ProviderRequestAbortError) {
+				return Err({
+					type: error.abortCause === 'caller' ? 'aborted' : 'timeout',
+					message: error.message,
+				})
+			}
+			return Err(mapProviderError(error))
 		}
 	}
 
@@ -399,6 +446,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 })
 				}
@@ -581,16 +638,4 @@ export class AnthropicProvider implements RoutableLLMProvider {
 		return { type: 'server_error', message, statusCode: status, responseBody: body }
 	}
 
-	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' }
-		}
-		if (err instanceof TypeError && (err.message.includes('fetch') || err.message.includes('network'))) {
-			return { type: 'network_error', message: err.message, cause: err }
-		}
-		return { type: 'network_error', message: err instanceof Error ? err.message : String(err), cause: err }
-	}
 }

package/src/core/llm/logger.ts

@@ -5,13 +5,20 @@
  * Per spec.md 9.1: "Pro debugging a audit se bude logovat kompletní LLM komunikace"
  *
  * Calls are stored in the session folder: {dataPath}/sessions/{sessionId}/calls/
+ *
+ * A host that has a table for them ({@link LLMCallStore}) gets rows instead: the
+ * same entries, but `completeCall` stops reading the whole entry back to rewrite
+ * it and `listCalls` stops being a `readdir` plus one read per row of the page.
+ * Without a store nothing changes — same directory, same files, same content.
  */
 
 import { join } from 'node:path'
-import type { AgentId } from '~/core/agents/schema.js'
+import { AgentId } from '~/core/agents/schema.js'
 import { generateLLMCallId, LLMCallId } from '~/core/llm/schema.js'
 import type { SessionId } from '~/core/sessions/schema.js'
+import { readTextFilesOrUndefined } from '~/lib/utils/fs-batch.js'
 import type { FileSystem } from '~/platform/fs.js'
+import type { LLMCallRow, LLMCallStore } from '~/platform/llm-call-log.js'
 import type { LLMCallError, LLMCallLogEntry, LLMCallMessage, LLMCallMetrics, LLMCallRequest, LLMCallResponse } from './llm-log-types.js'
 import type { InferenceRequest, InferenceResponse, LLMError } from './provider.js'
 
@@ -27,6 +34,70 @@ export interface LLMLoggerConfig {
 	basePath: string
 	enabled: boolean
 	fs: FileSystem
+	/** Rows instead of files, where the host has a table for them. */
+	store?: LLMCallStore
+}
+
+const ENCODER = new TextEncoder()
+
+/** UTF-8 length; the SDK cannot assume `Buffer`. */
+function byteLength(text: string): number {
+	return ENCODER.encode(text).byteLength
+}
+
+/**
+ * Fit a request inside the host's column ceiling.
+ *
+ * Everything in a request is bounded by the agent definition except the message
+ * history, which grows with the session and carries whole tool results. Over the
+ * ceiling the store would reject the row and, because `createCall` is awaited on
+ * the inference path, turn a logged call into a failed one.
+ */
+function clampRequest(request: LLMCallRequest, maxBytes: number | undefined): string {
+	const json = JSON.stringify(request)
+	// UTF-8 is at most 3 bytes per UTF-16 unit, so the common case never encodes.
+	if (maxBytes === undefined || json.length * 3 <= maxBytes) return json
+
+	const bytes = byteLength(json)
+	if (bytes <= maxBytes) return json
+
+	const dropped: LLMCallRequest = {
+		...request,
+		messages: [{
+			role: 'system',
+			content: `[${request.messages.length} messages, ${bytes} B, dropped: over the host's ${maxBytes} B column limit]`,
+		}],
+		tools: undefined,
+	}
+	const withoutMessages = JSON.stringify(dropped)
+	if (byteLength(withoutMessages) <= maxBytes) return withoutMessages
+
+	// A system prompt alone past the ceiling is pathological; keep only what a listing shows.
+	const minimal: LLMCallRequest = {
+		model: request.model,
+		systemPrompt: `[${byteLength(request.systemPrompt)} B, dropped]`,
+		messages: [],
+		toolsCount: request.tools?.length ?? 0,
+	}
+	return JSON.stringify(minimal)
+}
+
+/** JSON this logger wrote itself; annotated rather than cast, and never validated on read. */
+function parseJson<T>(json: string): T {
+	return JSON.parse(json)
+}
+
+function parseOptionalJson<T>(json: string | undefined): T | undefined {
+	return json === undefined ? undefined : parseJson<T>(json)
+}
+
+/** One stored entry, or null when the file stopped being JSON. */
+function parseEntry(content: string): LLMCallLogEntry | null {
+	try {
+		return parseJson<LLMCallLogEntry>(content)
+	} catch {
+		return null
+	}
 }
 
 // ============================================================================
@@ -35,14 +106,17 @@ export interface LLMLoggerConfig {
 
 /**
  * Logger for LLM requests and responses.
- * Stores individual JSON files per LLM call in the session folder.
+ * One JSON file per call in the session folder, or one row per call in a
+ * {@link LLMCallStore} where the host has one.
  */
 export class LLMLogger {
 	private dirCache = new Set<string>()
 	private readonly fs: FileSystem
+	private readonly store?: LLMCallStore
 
 	constructor(private config: LLMLoggerConfig) {
 		this.fs = config.fs
+		this.store = config.store
 	}
 
 	/**
@@ -138,6 +212,18 @@ export class LLMLogger {
 			providerOptions,
 		}
 
+		if (this.store !== undefined) {
+			await this.store.create(sessionId, {
+				callId,
+				agentId,
+				createdAt: now,
+				status: 'running',
+				model: request.model,
+				request: clampRequest(callRequest, this.store.maxBlobBytes),
+			})
+			return callId
+		}
+
 		const entry: LLMCallLogEntry = {
 			id: callId,
 			sessionId,
@@ -163,17 +249,6 @@ export class LLMLogger {
 		response: InferenceResponse,
 		durationMs: number,
 	): Promise<void> {
-		const filePath = this.getCallFilePath(sessionId, callId)
-
-		let entry: LLMCallLogEntry
-		try {
-			const content = await this.fs.readFile(filePath, 'utf-8')
-			entry = JSON.parse(content) as LLMCallLogEntry
-		} catch {
-			// File doesn't exist or is invalid - skip update
-			return
-		}
-
 		const callResponse: LLMCallResponse = {
 			content: response.content,
 			toolCalls: response.toolCalls.map((tc) => ({
@@ -199,6 +274,25 @@ export class LLMLogger {
 			reasoningTokens: response.metrics.reasoningTokens,
 		}
 
+		if (this.store !== undefined) {
+			// The whole reason for splitting the row: no read-back, and the request
+			// column is not in the SET list.
+			await this.store.complete(sessionId, callId, {
+				status: 'success',
+				completedAt: Date.now(),
+				durationMs,
+				providerRequestId: response.providerRequestId,
+				response: JSON.stringify(callResponse),
+				metrics: JSON.stringify(callMetrics),
+			})
+			return
+		}
+
+		const filePath = this.getCallFilePath(sessionId, callId)
+		const entry = await this.readEntry(filePath)
+		// File doesn't exist or is invalid - skip update
+		if (entry === null) return
+
 		entry.status = 'success'
 		entry.completedAt = Date.now()
 		entry.durationMs = durationMs
@@ -218,17 +312,6 @@ export class LLMLogger {
 		error: LLMError,
 		durationMs: number,
 	): Promise<void> {
-		const filePath = this.getCallFilePath(sessionId, callId)
-
-		let entry: LLMCallLogEntry
-		try {
-			const content = await this.fs.readFile(filePath, 'utf-8')
-			entry = JSON.parse(content) as LLMCallLogEntry
-		} catch {
-			// File doesn't exist or is invalid - skip update
-			return
-		}
-
 		const callError: LLMCallError = {
 			type: error.type,
 			message: error.message,
@@ -237,6 +320,21 @@ export class LLMLogger {
 			responseBody: error.responseBody,
 		}
 
+		if (this.store !== undefined) {
+			await this.store.complete(sessionId, callId, {
+				status: 'error',
+				completedAt: Date.now(),
+				durationMs,
+				error: JSON.stringify(callError),
+			})
+			return
+		}
+
+		const filePath = this.getCallFilePath(sessionId, callId)
+		const entry = await this.readEntry(filePath)
+		// File doesn't exist or is invalid - skip update
+		if (entry === null) return
+
 		entry.status = 'error'
 		entry.completedAt = Date.now()
 		entry.durationMs = durationMs
@@ -252,11 +350,18 @@ export class LLMLogger {
 		sessionId: SessionId,
 		callId: LLMCallId,
 	): Promise<LLMCallLogEntry | null> {
-		const filePath = this.getCallFilePath(sessionId, callId)
+		if (this.store !== undefined) {
+			const row = await this.store.get(sessionId, callId)
+			return row === null ? null : toEntry(sessionId, row)
+		}
+
+		return this.readEntry(this.getCallFilePath(sessionId, callId))
+	}
 
+	/** One stored entry, or null when the file has gone or stopped being JSON. */
+	private async readEntry(filePath: string): Promise<LLMCallLogEntry | null> {
 		try {
-			const content = await this.fs.readFile(filePath, 'utf-8')
-			return JSON.parse(content) as LLMCallLogEntry
+			return parseEntry(await this.fs.readFile(filePath, 'utf-8'))
 		} catch {
 			return null
 		}
@@ -269,6 +374,17 @@ export class LLMLogger {
 		sessionId: SessionId,
 		options?: { limit?: number; offset?: number },
 	): Promise<{ calls: LLMCallLogEntry[]; total: number }> {
+		const offset = options?.offset ?? 0
+		const limit = options?.limit ?? 100
+
+		if (this.store !== undefined) {
+			// One indexed query where the file path listed a directory, sorted the
+			// names and read the page's files one at a time. Same order, same page
+			// boundaries — see LLMCallStore.list.
+			const page = await this.store.list(sessionId, { limit, offset })
+			return { calls: page.calls.map((row) => toEntry(sessionId, row)), total: page.total }
+		}
+
 		const callsDir = join(this.config.basePath, 'sessions', sessionId, 'calls')
 
 		let files: string[]
@@ -286,21 +402,43 @@ export class LLMLogger {
 			.reverse() // Most recent first
 
 		const total = jsonFiles.length
-		const offset = options?.offset ?? 0
-		const limit = options?.limit ?? 100
 		const paginated = jsonFiles.slice(offset, offset + limit)
 
+		// The page is a known set of paths, so it is asked for as one where the
+		// platform takes one — the same read the store branch above replaces with
+		// a single query.
+		const contents = await readTextFilesOrUndefined(this.fs, paginated.map((file) => join(callsDir, file)))
+
 		const calls: LLMCallLogEntry[] = []
-		for (const file of paginated) {
-			try {
-				const filePath = join(callsDir, file)
-				const content = await this.fs.readFile(filePath, 'utf-8')
-				calls.push(JSON.parse(content) as LLMCallLogEntry)
-			} catch {
-				// Skip invalid files
-			}
+		for (const content of contents) {
+			// Skip invalid files
+			const entry = content === undefined ? null : parseEntry(content)
+			if (entry !== null) calls.push(entry)
 		}
 
 		return { calls, total }
 	}
 }
+
+/**
+ * Reassemble a stored row into the entry every reader is typed against.
+ *
+ * `sessionId` comes from the key rather than the row: it is what the caller
+ * looked the row up by, so storing it again would only be a second copy.
+ */
+function toEntry(sessionId: SessionId, row: LLMCallRow): LLMCallLogEntry {
+	return {
+		id: LLMCallId(row.callId),
+		sessionId,
+		agentId: AgentId(row.agentId),
+		createdAt: row.createdAt,
+		completedAt: row.completedAt,
+		durationMs: row.durationMs,
+		status: row.status,
+		request: parseJson<LLMCallRequest>(row.request),
+		response: parseOptionalJson<LLMCallResponse>(row.response),
+		metrics: parseOptionalJson<LLMCallMetrics>(row.metrics),
+		error: parseOptionalJson<LLMCallError>(row.error),
+		providerRequestId: row.providerRequestId,
+	}
+}