@roj-ai/sdk 0.1.31 → 0.1.33

package/src/index.ts

@@ -53,6 +53,7 @@ export type { AgentPauseReason, AgentState, LLMMessage } from '~/core/agents/sta
 export type { DomainEvent } from '~/core/events/types.js'
 export type { FactoryEventType } from '~/core/events/types.js'
 export { isDomainEvent } from '~/core/events/types.js'
+export type { CacheTtl, CacheTtlConfig } from '~/core/llm/cache-breakpoints.js'
 export type { ChatMessageContentItem, LLMCallLogEntry, LLMCallMessage, ToolResultContent } from '~/core/llm/llm-log-types.js'
 export { contentToString } from '~/core/llm/llm-log-types.js'
 export { applyMiddleware, useProvider, withAnthropic, withMaxTokens, withOpenRouter, withTemperature } from '~/core/llm/middleware.js'
@@ -98,7 +99,7 @@ export type { EvictionAgentConfig, EvictionConfig } from '~/plugins/result-evict
 export { servicePlugin } from '~/plugins/services/plugin.js'
 export type { ServiceAgentConfig, ServiceStatusChangedEvent } from '~/plugins/services/plugin.js'
 export { selectSessionStats, sessionStatsPlugin } from '~/plugins/session-stats/plugin.js'
-export type { SessionStatsState } from '~/plugins/session-stats/plugin.js'
+export type { AgentStats, ProviderStats, SessionStatsState } from '~/plugins/session-stats/plugin.js'
 export { sessionStatePlugin } from '~/plugins/session-state/plugin.js'
 export type { SessionStatePluginConfig } from '~/plugins/session-state/plugin.js'
 export { presetsPlugin, sessionLifecyclePlugin } from '~/plugins/session-lifecycle/plugin.js'

package/src/plugins/result-eviction/plugin.ts

@@ -6,6 +6,7 @@
  * head + tail + file path is returned instead.
  */
 
+import { type ChatMessageContentItem, contentToString, type ToolResultContent } from '~/core/llm/llm-log-types.js'
 import { truncateByTokens } from '~/core/llm/tokens.js'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
 
@@ -23,6 +24,21 @@ export interface EvictionAgentConfig {
 
 const DEFAULT_MAX_TOKENS = 20_000
 
+const isImage = (item: ChatMessageContentItem): boolean => item.type === 'image_url'
+
+/**
+ * Rebuild a multi-part result with its text collapsed to `preview` and every
+ * image part preserved in order.
+ *
+ * Images are kept rather than truncated because there is no partial image — the
+ * alternative to keeping it is dropping the observation entirely. Text is the
+ * part that both dominates the payload and survives being summarised.
+ */
+const withTextReplaced = (content: ChatMessageContentItem[], preview: string): ChatMessageContentItem[] => [
+	{ type: 'text', text: preview },
+	...content.filter(isImage),
+]
+
 export const resultEvictionPlugin = definePlugin('result-eviction')
 	.agentConfig<EvictionAgentConfig>()
 	.hook('afterToolCall', async (ctx) => {
@@ -34,31 +50,30 @@ export const resultEvictionPlugin = definePlugin('result-eviction')
 		}
 
 		const { content } = ctx.result
-
-		// Only evict string content
-		if (typeof content !== 'string') {
-			return null
-		}
-
 		const maxTokens = agentConfig?.config?.maxTokens ?? DEFAULT_MAX_TOKENS
 
-		const truncation = truncateByTokens(content, maxTokens)
+		// Multi-part results (e.g. a page snapshot returning JSON + a screenshot)
+		// used to bail out here, so no threshold could ever evict them however
+		// large the text grew. Measure the text, evict the text, keep the images.
+		const text = contentToString(content)
+		const truncation = truncateByTokens(text, maxTokens)
 		if (!truncation) {
 			return null
 		}
 
-		// Write full content to file via FileStore
+		// Write full text to file via FileStore
 		const fileName = `${ctx.toolCall.id}.txt`
 		const filePath = `.results/${fileName}`
-		await ctx.files.session.write(filePath, content)
+		await ctx.files.session.write(filePath, text)
 
-		const truncatedContent = `${truncation.content}\n\n[Full output saved to: ${filePath}]`
+		const preview = `${truncation.content}\n\n[Full output saved to: ${filePath}]`
+		const evicted: ToolResultContent = typeof content === 'string' ? preview : withTextReplaced(content, preview)
 
 		return {
 			action: 'modify',
 			result: {
 				isError: false,
-				content: truncatedContent,
+				content: evicted,
 			},
 		}
 	})

package/src/plugins/result-eviction/result-eviction.integration.test.ts

@@ -19,6 +19,18 @@ const bigOutputPlugin = definePlugin('big-output')
 			input: z.object({ size: z.number() }),
 			execute: async (input) => Ok('x'.repeat(input.size)),
 		}),
+		// Mirrors a page-snapshot style result: a large JSON/text block plus an
+		// image part. These used to bypass eviction entirely.
+		createTool({
+			name: 'generate_snapshot',
+			description: 'Generate a text + image result of a given text size',
+			input: z.object({ size: z.number() }),
+			execute: async (input) =>
+				Ok([
+					{ type: 'text' as const, text: 'x'.repeat(input.size) },
+					{ type: 'image_url' as const, imageUrl: { url: 'data:image/png;base64,AAAA' } },
+				]),
+		}),
 	])
 	.build()
 
@@ -100,6 +112,82 @@ describe('result-eviction plugin', () => {
 		await harness.shutdown()
 	})
 
+	it('large multi-part output → text evicted, image part kept', async () => {
+		let toolContent: unknown = null
+		const harness = createEvictionHarness({
+			presets: [createEvictionPreset()],
+			mockHandler: (request) => {
+				const callCount = harness.llmProvider.getCallCount()
+				if (callCount === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'generate_snapshot', input: { size: 250_000 } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				for (const msg of request.messages) {
+					if (msg.role === 'tool' && Array.isArray(msg.content)) {
+						toolContent = msg.content
+					}
+				}
+				return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Generate large snapshot')
+
+		expect(Array.isArray(toolContent)).toBe(true)
+		const parts = toolContent as Array<{ type: string; text?: string }>
+
+		// Text collapsed to a preview that names the spill file...
+		const textParts = parts.filter((p) => p.type === 'text')
+		expect(textParts).toHaveLength(1)
+		expect(textParts[0].text).toContain('truncated')
+		expect(textParts[0].text).toContain('.results/')
+		expect(textParts[0].text!.length).toBeLessThan(250_000)
+
+		// ...and the image survives, because there is no partial image: the only
+		// alternative to keeping it is losing the observation.
+		expect(parts.filter((p) => p.type === 'image_url')).toHaveLength(1)
+
+		await harness.shutdown()
+	})
+
+	it('small multi-part output → returned unchanged', async () => {
+		let toolContent: unknown = null
+		const harness = createEvictionHarness({
+			presets: [createEvictionPreset()],
+			mockHandler: (request) => {
+				const callCount = harness.llmProvider.getCallCount()
+				if (callCount === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'generate_snapshot', input: { size: 100 } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				for (const msg of request.messages) {
+					if (msg.role === 'tool' && Array.isArray(msg.content)) {
+						toolContent = msg.content
+					}
+				}
+				return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Generate small snapshot')
+
+		const parts = toolContent as Array<{ type: string; text?: string }>
+		expect(parts.filter((p) => p.type === 'text')[0].text).toBe('x'.repeat(100))
+		expect(parts.filter((p) => p.type === 'image_url')).toHaveLength(1)
+
+		await harness.shutdown()
+	})
+
 	it('full output saved to .results/<toolCallId>.txt', async () => {
 		const harness = createEvictionHarness({
 			presets: [createEvictionPreset()],

package/src/plugins/session-stats/index.ts

@@ -1,3 +1,3 @@
 export { sessionStatsPlugin } from './plugin.js'
-export type { SessionStatsState } from './plugin.js'
+export type { AgentStats, ProviderStats, SessionStatsState } from './plugin.js'
 export { selectSessionStats } from './plugin.js'

package/src/plugins/session-stats/plugin.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { contextEvents } from '~/core/context/state.js'
+import { withSessionId } from '~/core/events/test-helpers.js'
+import type { DomainEvent } from '~/core/events/types.js'
+import type { LLMMetrics } from '~/core/llm/state.js'
+import { llmEvents } from '~/core/llm/state.js'
+import { createApplyEvent } from '~/core/sessions/apply-event.js'
+import { SessionId } from '~/core/sessions/schema.js'
+import { createSessionState } from '~/core/sessions/state.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { toolEvents } from '~/core/tools/state.js'
+import { userChatEvents } from '~/plugins/user-chat/plugin.js'
+import { ChatMessageId } from '~/plugins/user-chat/schema.js'
+import { selectSessionStats, sessionStatsPlugin } from './plugin.js'
+
+const sessionId = SessionId('session-stats-test')
+const orchestrator = AgentId('orchestrator-1')
+const worker = AgentId('worker-1')
+
+const applyEvent = createApplyEvent([sessionStatsPlugin.create()])
+
+const metrics = (overrides: Partial<LLMMetrics> = {}): LLMMetrics => ({
+	promptTokens: 100,
+	completionTokens: 20,
+	totalTokens: 120,
+	latencyMs: 10,
+	model: 'test-model',
+	provider: 'anthropic',
+	cost: 0.5,
+	...overrides,
+})
+
+const spawn = (agentId: AgentId, definitionName: string) =>
+	withSessionId(sessionId, agentEvents.create('agent_spawned', { agentId, definitionName, parentId: null }))
+
+const inference = (agentId: AgentId, m: LLMMetrics) =>
+	withSessionId(sessionId, llmEvents.create('inference_completed', {
+		agentId,
+		consumedMessageIds: [],
+		response: { content: 'ok', toolCalls: [] },
+		metrics: m,
+	}))
+
+const reduce = (events: DomainEvent[]) => selectSessionStats(events.reduce(applyEvent, createSessionState(sessionId, 'test-preset', 0)))
+
+describe('session-stats plugin', () => {
+	it('starts from zeroed counters', () => {
+		const stats = reduce([])
+		expect(stats.userMessages).toBe(0)
+		expect(stats.compactions).toBe(0)
+		expect(stats.cacheReadTokens).toBe(0)
+		expect(stats.cacheWriteTokens).toBe(0)
+		expect(stats.byAgent).toEqual({})
+	})
+
+	it('counts user chat messages', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			withSessionId(sessionId, userChatEvents.create('user_chat_message_received', {
+				agentId: orchestrator,
+				messageId: ChatMessageId('m1'),
+				content: 'hello',
+				timestamp: 1,
+			})),
+			withSessionId(sessionId, userChatEvents.create('user_chat_message_received', {
+				agentId: orchestrator,
+				messageId: ChatMessageId('m2'),
+				content: 'again',
+				timestamp: 2,
+			})),
+		])
+		expect(stats.userMessages).toBe(2)
+	})
+
+	it('counts context compactions', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			withSessionId(sessionId, contextEvents.create('context_compacted', {
+				agentId: orchestrator,
+				compactedContent: 'summary',
+				newConversationHistory: [],
+				originalTokens: 1000,
+				compactedTokens: 100,
+				messagesRemoved: 8,
+			})),
+		])
+		expect(stats.compactions).toBe(1)
+	})
+
+	it('sums cache read and write tokens across main and auxiliary inferences', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			inference(orchestrator, metrics({ cachedTokens: 800, cacheWriteTokens: 200 })),
+			withSessionId(sessionId, llmEvents.create('auxiliary_inference_completed', {
+				agentId: orchestrator,
+				metrics: metrics({ cachedTokens: 50, cacheWriteTokens: 10 }),
+			})),
+			// Providers that report no cache usage must not break the totals.
+			inference(orchestrator, metrics()),
+		])
+		expect(stats.cacheReadTokens).toBe(850)
+		expect(stats.cacheWriteTokens).toBe(210)
+		expect(stats.llmCalls).toBe(3)
+	})
+
+	it('breaks LLM usage down by agent definition name', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			spawn(worker, 'coder'),
+			inference(orchestrator, metrics({ promptTokens: 100, completionTokens: 20, cost: 0.5 })),
+			inference(worker, metrics({ promptTokens: 300, completionTokens: 40, cost: 1.25 })),
+			inference(worker, metrics({ promptTokens: 200, completionTokens: 10, cost: 0.25 })),
+			withSessionId(sessionId, llmEvents.create('auxiliary_inference_completed', {
+				agentId: worker,
+				metrics: metrics({ promptTokens: 10, completionTokens: 1, cost: 0.05 }),
+			})),
+		])
+		expect(stats.byAgent).toEqual({
+			orchestrator: { llmCalls: 1, promptTokens: 100, completionTokens: 20, totalCost: 0.5 },
+			coder: { llmCalls: 3, promptTokens: 510, completionTokens: 51, totalCost: 1.55 },
+		})
+		expect(stats.totalCost).toBeCloseTo(2.05, 10)
+	})
+
+	it('keeps existing counters working', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			inference(orchestrator, metrics()),
+			withSessionId(sessionId, llmEvents.create('inference_failed', { agentId: orchestrator, error: 'boom' })),
+			withSessionId(sessionId, toolEvents.create('tool_started', {
+				agentId: orchestrator,
+				toolCallId: ToolCallId('tc-1'),
+				toolName: 'read_file',
+				input: {},
+			})),
+			withSessionId(sessionId, toolEvents.create('tool_failed', {
+				agentId: orchestrator,
+				toolCallId: ToolCallId('tc-1'),
+				error: 'ENOENT',
+			})),
+		])
+		expect(stats.agentCount).toBe(1)
+		expect(stats.llmCalls).toBe(1)
+		expect(stats.llmErrors).toBe(1)
+		expect(stats.toolCalls).toBe(1)
+		expect(stats.toolErrors).toBe(1)
+		expect(stats.totalTokens).toBe(120)
+		expect(stats.promptTokens).toBe(100)
+		expect(stats.completionTokens).toBe(20)
+		expect(stats.byProvider.anthropic).toEqual({
+			llmCalls: 1,
+			totalTokens: 120,
+			promptTokens: 100,
+			completionTokens: 20,
+			totalCost: 0.5,
+		})
+	})
+})

package/src/plugins/session-stats/plugin.ts

@@ -1,9 +1,11 @@
 import { agentEvents } from '~/core/agents/state.js'
+import { contextEvents } from '~/core/context/state.js'
 import { llmEvents } from '~/core/llm/state.js'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
 import { selectPluginState } from '~/core/sessions/reducer.js'
 import type { SessionState } from '~/core/sessions/state.js'
 import { toolEvents } from '~/core/tools/state.js'
+import { userChatEvents } from '~/plugins/user-chat/plugin.js'
 
 // ============================================================================
 // Session stats state
@@ -17,35 +19,57 @@ export interface ProviderStats {
 	totalCost: number
 }
 
+export interface AgentStats {
+	llmCalls: number
+	promptTokens: number
+	completionTokens: number
+	totalCost: number
+}
+
 export interface SessionStatsState {
 	totalTokens: number
 	promptTokens: number
 	completionTokens: number
+	/** Prompt tokens served from the provider cache (a subset of promptTokens) */
+	cacheReadTokens: number
+	/** Prompt tokens written to the provider cache */
+	cacheWriteTokens: number
 	totalCost: number
 	llmCalls: number
 	llmErrors: number
 	toolCalls: number
 	toolErrors: number
+	/** Chat messages received from the user */
+	userMessages: number
+	/** Context compactions performed in this session */
+	compactions: number
 	agentCount: number
 	firstEventAt: number | null
 	lastEventAt: number | null
 	/** Per-provider breakdown of LLM usage */
 	byProvider: Record<string, ProviderStats>
+	/** Per agent-definition breakdown of LLM usage (keyed by definition name, not agent id) */
+	byAgent: Record<string, AgentStats>
 }
 
 const createInitialStats = (): SessionStatsState => ({
 	totalTokens: 0,
 	promptTokens: 0,
 	completionTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0,
 	totalCost: 0,
 	llmCalls: 0,
 	llmErrors: 0,
 	toolCalls: 0,
 	toolErrors: 0,
+	userMessages: 0,
+	compactions: 0,
 	agentCount: 0,
 	firstEventAt: null,
 	lastEventAt: null,
 	byProvider: {},
+	byAgent: {},
 })
 
 const PLUGIN_STATE_KEY = 'sessionStats'
@@ -62,11 +86,11 @@ export function selectSessionStats(sessionState: SessionState): SessionStatsStat
 // ============================================================================
 
 export const sessionStatsPlugin = definePlugin('session-stats')
-	.events([agentEvents, llmEvents, toolEvents])
+	.events([agentEvents, llmEvents, toolEvents, contextEvents, userChatEvents])
 	.state({
 		key: PLUGIN_STATE_KEY,
 		initial: createInitialStats,
-		reduce: (stats, event) => {
+		reduce: (stats, event, sessionState) => {
 			const now = event.timestamp
 			const withTimestamp = (partial: Partial<SessionStatsState>): SessionStatsState => ({
 				...stats,
@@ -97,13 +121,29 @@ export const sessionStatsPlugin = definePlugin('session-stats')
 							},
 						}
 						: stats.byProvider
+					// Core reducer runs before plugin slices, so the spawning agent is already in state.
+					const definitionName = sessionState.agents.get(event.agentId)?.definitionName
+					const byAgent = definitionName
+						? {
+							...stats.byAgent,
+							[definitionName]: {
+								llmCalls: (stats.byAgent[definitionName]?.llmCalls ?? 0) + 1,
+								promptTokens: (stats.byAgent[definitionName]?.promptTokens ?? 0) + event.metrics.promptTokens,
+								completionTokens: (stats.byAgent[definitionName]?.completionTokens ?? 0) + event.metrics.completionTokens,
+								totalCost: (stats.byAgent[definitionName]?.totalCost ?? 0) + (event.metrics.cost ?? 0),
+							},
+						}
+						: stats.byAgent
 					return withTimestamp({
 						llmCalls: stats.llmCalls + 1,
 						totalTokens: stats.totalTokens + event.metrics.totalTokens,
 						promptTokens: stats.promptTokens + event.metrics.promptTokens,
 						completionTokens: stats.completionTokens + event.metrics.completionTokens,
+						cacheReadTokens: stats.cacheReadTokens + (event.metrics.cachedTokens ?? 0),
+						cacheWriteTokens: stats.cacheWriteTokens + (event.metrics.cacheWriteTokens ?? 0),
 						totalCost: stats.totalCost + (event.metrics.cost ?? 0),
 						byProvider,
+						byAgent,
 					})
 				}
 
@@ -116,6 +156,12 @@ export const sessionStatsPlugin = definePlugin('session-stats')
 				case 'tool_failed':
 					return withTimestamp({ toolErrors: stats.toolErrors + 1 })
 
+				case 'user_chat_message_received':
+					return withTimestamp({ userMessages: stats.userMessages + 1 })
+
+				case 'context_compacted':
+					return withTimestamp({ compactions: stats.compactions + 1 })
+
 				default:
 					return stats
 			}