@roj-ai/sdk 0.1.30 → 0.1.32

package/src/core/llm/openrouter.ts

@@ -89,11 +89,17 @@ interface OpenRouterErrorResponse {
 // Request body types
 // ============================================================================
 
+interface OpenRouterCacheControl {
+	type: 'ephemeral'
+	/** Omitted = the provider default 5-minute tier. */
+	ttl?: '5m' | '1h'
+}
+
 interface OpenRouterContentItem {
 	type: string
 	text?: string
 	image_url?: { url: string; detail?: string }
-	cache_control?: { type: 'ephemeral' }
+	cache_control?: OpenRouterCacheControl
 }
 
 interface OpenRouterMessage {
@@ -104,18 +110,34 @@ interface OpenRouterMessage {
 }
 
 /**
- * Add `cache_control: { type: 'ephemeral' }` to the LAST content block of an
- * OpenRouterMessage, converting string content to an array text block first
- * so the mark has a place to live.
+ * Add `cache_control` to the LAST content block of an OpenRouterMessage,
+ * converting string content to an array text block first so the mark has a
+ * place to live.
+ *
+ * `ttl` reaches Anthropic through the Chat Completions surface. It is NOT
+ * expressible on the Responses API, where a breakpoint is downgraded to the
+ * default 5-minute tier — so this must stay on `/chat/completions`.
  */
-function applyCacheControlToLastBlock(msg: OpenRouterMessage): void {
+function applyCacheControlToLastBlock(msg: OpenRouterMessage, cacheControl: OpenRouterCacheControl): void {
 	if (typeof msg.content === 'string') {
-		msg.content = [{ type: 'text', text: msg.content, cache_control: { type: 'ephemeral' } }]
+		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: { type: 'ephemeral' } }
+	msg.content[lastIdx] = { ...msg.content[lastIdx], cache_control: cacheControl }
+}
+
+/**
+ * Longest TTL requested anywhere in the message list, or undefined when none.
+ *
+ * The system prompt precedes every message, and Anthropic requires a longer TTL
+ * to come BEFORE a shorter one. So when any breakpoint asks for 1h, the system
+ * block has to carry 1h too — otherwise the order is 5m → 1h → 5m and the
+ * longer entry is invalid.
+ */
+function longestCacheTtl(messages: LLMMessage[]): '1h' | undefined {
+	return messages.some((m) => m.cacheControl?.ttl === '1h') ? '1h' : undefined
 }
 
 interface OpenRouterToolDefinition {
@@ -261,8 +283,10 @@ export class OpenRouterProvider implements LLMProvider {
 		const sanitizedMessages = sanitizeProviderMessages(request.messages, this.name, this.logger)
 		const mappedMessages = await Promise.all(sanitizedMessages.map((m) => this.mapMessage(m, context)))
 
+		const systemTtl = longestCacheTtl(sanitizedMessages)
+		const systemCacheControl: OpenRouterCacheControl = systemTtl ? { type: 'ephemeral', ttl: systemTtl } : { type: 'ephemeral' }
 		const messages: OpenRouterMessage[] = [
-			{ role: 'system', content: [{ type: 'text', text: request.systemPrompt, cache_control: { type: 'ephemeral' } }] },
+			{ role: 'system', content: [{ type: 'text', text: request.systemPrompt, cache_control: systemCacheControl }] },
 			...mappedMessages,
 		]
 
@@ -317,7 +341,9 @@ export class OpenRouterProvider implements LLMProvider {
 	private async mapMessage(msg: LLMMessage, context?: InferenceContext): Promise<OpenRouterMessage> {
 		const mapped = await this.mapMessageContent(msg, context)
 		if (msg.cacheControl) {
-			applyCacheControlToLastBlock(mapped)
+			const cacheControl: OpenRouterCacheControl = { type: 'ephemeral' }
+			if (msg.cacheControl.ttl) cacheControl.ttl = msg.cacheControl.ttl
+			applyCacheControlToLastBlock(mapped, cacheControl)
 		}
 		return mapped
 	}

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'

package/src/plugins/agents/agents.integration.test.ts

@@ -805,4 +805,172 @@ describe('agents plugin', () => {
 			await harness.shutdown()
 		})
 	})
+
+	// =========================================================================
+	// resume_agent tool
+	// =========================================================================
+
+	describe('resume_agent tool', () => {
+		// A paused child never becomes idle, so waitForAllAgentsIdle can't be used here —
+		// wait for the effect instead.
+		const waitFor = async (predicate: () => boolean, timeoutMs = 5000): Promise<void> => {
+			const deadline = Date.now() + timeoutMs
+			while (Date.now() < deadline) {
+				if (predicate()) return
+				await new Promise(resolve => setTimeout(resolve, 10))
+			}
+			throw new Error('waitFor timed out')
+		}
+
+		const workerPreset = () => createMultiAgentPreset([
+			{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+		], { orchestratorSystem: 'Orchestrator agent.' })
+
+		it('is offered to an agent that can spawn, and not to a leaf', async () => {
+			const toolNames = new Map<string, string[]>()
+
+			const harness = new TestHarness({
+				presets: [workerPreset()],
+				mockHandler: (request) => {
+					const role = request.systemPrompt.includes('Orchestrator') ? 'orchestrator' : 'worker'
+					toolNames.set(role, (request.tools ?? []).map(tool => tool.name))
+					if (role === 'orchestrator' && !toolNames.has('worker')) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Work' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				},
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Start')
+
+			expect(toolNames.get('orchestrator')).toContain('resume_agent')
+			expect(toolNames.get('worker')).not.toContain('resume_agent')
+
+			await harness.shutdown()
+		})
+
+		it('orchestrator resumes its paused child', async () => {
+			let started = false
+			let resumeIssued = false
+
+			const harness = new TestHarness({
+				presets: [workerPreset()],
+				mockHandler: (request) => {
+					if (request.systemPrompt.includes('Orchestrator')) {
+						const asked = JSON.stringify(request.messages).includes('Resume the worker')
+						if (asked && !resumeIssued) {
+							resumeIssued = true
+							return {
+								content: null,
+								toolCalls: [{ id: ToolCallId('tc2'), name: 'resume_agent', input: { agentId: 'worker_1' } }],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						}
+						if (!started) {
+							started = true
+							return {
+								content: null,
+								toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Work' } }],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						}
+						return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+					}
+					return { content: 'Worker done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				},
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Start')
+
+			const pauseResult = await session.callPluginMethod('agents.pause', { agentId: 'worker_1' })
+			expect(pauseResult.ok).toBe(true)
+			expect(session.state.agents.get(AgentId('worker_1'))!.status).toBe('paused')
+
+			await session.sendMessage('Resume the worker')
+			await waitFor(() => session.state.agents.get(AgentId('worker_1'))!.status !== 'paused')
+
+			const resumedEvents = await session.getEventsByType(agentEvents, 'agent_resumed')
+			expect(resumedEvents.filter(e => e.agentId === AgentId('worker_1'))).toHaveLength(1)
+			expect(session.state.agents.get(AgentId('worker_1'))!.status).not.toBe('paused')
+
+			await harness.shutdown()
+		})
+
+		it('refuses an agent that is not the caller\'s child', async () => {
+			let delegated = false
+			let subDelegated = false
+			let resumeIssued = false
+			let toolResult = ''
+
+			const harness = new TestHarness({
+				presets: [createMultiAgentPreset([
+					{ name: 'worker_a', system: 'Worker A agent.', tools: [], agents: ['worker_b'] },
+					{ name: 'worker_b', system: 'Worker B agent.', tools: [], agents: [] },
+				], { orchestratorSystem: 'Orchestrator agent.' })],
+				mockHandler: (request) => {
+					if (request.systemPrompt.includes('Orchestrator')) {
+						const last = request.messages[request.messages.length - 1]
+						if (last?.role === 'tool' && resumeIssued) toolResult = JSON.stringify(last.content)
+
+						const asked = JSON.stringify(request.messages).includes('Resume the grandchild')
+						if (asked && !resumeIssued) {
+							resumeIssued = true
+							// worker_b is a grandchild — spawned by worker_a, not by the orchestrator
+							return {
+								content: null,
+								toolCalls: [{ id: ToolCallId('tc3'), name: 'resume_agent', input: { agentId: 'worker_b_1' } }],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						}
+						if (!delegated) {
+							delegated = true
+							return {
+								content: null,
+								toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker_a', input: { message: 'Delegate' } }],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						}
+						return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+					}
+
+					if (request.systemPrompt.includes('Worker A')) {
+						if (subDelegated) {
+							return { content: 'Worker A done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+						}
+						subDelegated = true
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc2'), name: 'start_worker_b', input: { message: 'Sub-task' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'Worker done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				},
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Start', { timeoutMs: 15_000 })
+
+			await session.callPluginMethod('agents.pause', { agentId: 'worker_b_1' })
+			await session.sendMessage('Resume the grandchild')
+			await waitFor(() => toolResult !== '')
+
+			expect(toolResult).toContain('not your child')
+			expect(session.state.agents.get(AgentId('worker_b_1'))!.status).toBe('paused')
+
+			await harness.shutdown()
+		}, 20_000)
+	})
 })

package/src/plugins/agents/plugin.ts

@@ -420,7 +420,7 @@ export const agentsPlugin = definePlugin('agents')
 - **New task** → spawn a new agent using \`start_<agent_name>\`. You will receive the agent's ID in the result — use it with \`send_message\` for follow-up communication.
 - **Follow-up on an existing task** → send a message to the existing agent via \`send_message\` with the agent's ID. Do NOT spawn a new agent for feedback, corrections, or additional instructions on a task already assigned.
 - Spawned agents communicate back to you via \`send_message\`. Check your incoming messages for their results and progress updates.
-- If a child pauses early it sends you a \`<child-paused agent="…">reason</child-paused>\` message (e.g. it hit a cost/limit budget). Decide what to do: resume it (after addressing the cause), reassign or drop the work, or stop.`
+- If a child pauses early it sends you a \`<child-paused agent="…">reason</child-paused>\` message (e.g. it hit a cost/limit budget). Decide what to do: resume it with \`resume_agent\` **after addressing the cause**, reassign or drop the work, or stop. Resuming does not grant more budget — a child that hit a cost or token limit will stop again immediately, so don't retry it in a loop.`
 
 		// Only include supervision instructions if supervision is actually enabled
 		// for this session — otherwise the section is misleading bloat.
@@ -438,7 +438,41 @@ Do NOT act on a supervision tick unless something is genuinely wrong (a child ha
 		const spawnableAgents = ctx.agentConfig.spawnableAgents
 		const agentDefs = ctx.pluginConfig.agentDefinitions
 
-		return spawnableAgents.map((agentName) => {
+		// The parent is told (see the `<child-paused>` line in the system prompt above) that it
+		// may resume a paused child. Without this tool that instruction had nothing behind it:
+		// `resume` existed only as a plugin method, reachable from outside the session via
+		// `agents.resume`, so a child that paused stayed paused until something external
+		// intervened. Only offered to agents that can actually have children.
+		const resumeTool = createTool({
+			name: 'resume_agent',
+			description:
+				'Resume one of your own child agents after it paused (you receive a <child-paused> message when that happens). '
+				+ 'Address the cause first — resuming does not grant more budget, so a child that hit a cost or token limit '
+				+ 'will stop again immediately unless the limit itself is raised.',
+			input: z.object({
+				agentId: agentIdSchema.describe('ID of the paused child agent, as given in the <child-paused> message'),
+			}),
+			execute: async (input, context) => {
+				const target = context.sessionState.agents.get(input.agentId)
+				if (!target) {
+					return Err({ message: `No agent "${input.agentId}" in this session.`, recoverable: false })
+				}
+				if (target.parentId !== context.agentId) {
+					return Err({ message: `Agent "${input.agentId}" is not your child — you can only resume agents you spawned.`, recoverable: false })
+				}
+				if (target.status !== 'paused' && target.status !== 'errored') {
+					return Err({ message: `Agent "${input.agentId}" is ${target.status}, not paused — nothing to resume.`, recoverable: false })
+				}
+
+				const result = await ctx.self.resume({ agentId: input.agentId })
+				if (!result.ok) {
+					return Err({ message: result.error.message, recoverable: false })
+				}
+				return Ok(`Agent "${input.agentId}" resumed.`)
+			},
+		})
+
+		const startTools = spawnableAgents.map((agentName) => {
 			const agentInfo = agentDefs.get(agentName) ?? { name: agentName }
 			const toolName = `start_${agentInfo.name}`
 			const description = agentInfo.description
@@ -469,5 +503,8 @@ Do NOT act on a supervision tick unless something is genuinely wrong (a child ha
 				},
 			})
 		})
+
+		// An agent with nothing to spawn has no children to resume either.
+		return spawnableAgents.length > 0 ? [...startTools, resumeTool] : []
 	})
 	.build()

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()],