@roj-ai/sdk 0.1.20 → 0.1.22

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

@@ -400,6 +400,40 @@ describe('AnthropicProvider buildHttpRequest cache placement', () => {
 		expect(last.content[1].cache_control).toBeUndefined()
 	})
 
+	test('stable prefix + tail: TWO cache_control blocks survive into the HTTP body', async () => {
+		// Mirrors the agent flow: an immutable preamble followed by a churning
+		// conversation tail. applyCacheBreakpoint with cachedPrefixCount marks
+		// BOTH the last preamble message and the tail — both must reach the wire.
+		// Roles alternate so mergeConsecutiveMessages doesn't fold them together.
+		const messages = applyCacheBreakpoint(
+			[
+				{ role: 'user', content: 'preamble part A' },
+				{ role: 'assistant', content: 'preamble part B' }, // last preamble msg → prefix breakpoint
+				{ role: 'user', content: 'conversation turn' },
+				{ role: 'assistant', content: 'tail reply' }, // tail breakpoint
+			],
+			0, // no uncached suffix → tailIdx = 3
+			undefined,
+			2, // cachedPrefixCount → prefixIdx = 1
+		)
+
+		const http = await createProvider().buildHttpRequest(buildRequest(messages))
+		const msgs = getBodyMessages(http.body)
+
+		expect(msgs.length).toBe(4)
+		// Prefix breakpoint on the last preamble message
+		const prefix = msgs[1]
+		expect(prefix.role).toBe('assistant')
+		expect(prefix.content[prefix.content.length - 1].cache_control).toEqual({ type: 'ephemeral' })
+		// Tail breakpoint on the final message
+		const tail = msgs[3]
+		expect(tail.role).toBe('assistant')
+		expect(tail.content[tail.content.length - 1].cache_control).toEqual({ type: 'ephemeral' })
+		// Messages between the two breakpoints stay uncached
+		expect(msgs[0].content[msgs[0].content.length - 1].cache_control).toBeUndefined()
+		expect(msgs[2].content[msgs[2].content.length - 1].cache_control).toBeUndefined()
+	})
+
 	test('no flag on any message: only system prompt has cache_control', async () => {
 		const http = await createProvider().buildHttpRequest(buildRequest([
 			{ role: 'user', content: 'What is 2+2?' },

package/src/core/llm/cache-breakpoints.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test'
+import type { LLMMessage } from '~/core/agents/state.js'
+import { applyCacheBreakpoint } from './cache-breakpoints.js'
+
+const userMessages = (count: number): LLMMessage[] =>
+	Array.from({ length: count }, (_, i) => ({ role: 'user', content: `m${i}` }))
+
+const cachedIndices = (messages: LLMMessage[]): number[] =>
+	messages.flatMap((m, i) => ('cacheControl' in m && m.cacheControl ? [i] : []))
+
+describe('applyCacheBreakpoint', () => {
+	test('cachedPrefixCount = 0 → single tail breakpoint only (unchanged behaviour)', () => {
+		const messages = userMessages(5)
+		const result = applyCacheBreakpoint(messages, 1)
+		// tail = length - 1 - suffix = 5 - 1 - 1 = 3
+		expect(cachedIndices(result)).toEqual([3])
+	})
+
+	test('cachedPrefixCount > 0 → two breakpoints: prefix end and tail', () => {
+		const messages = userMessages(10)
+		const result = applyCacheBreakpoint(messages, 1, undefined, 3)
+		// prefix = 3 - 1 = 2, tail = 10 - 1 - 1 = 8
+		expect(cachedIndices(result)).toEqual([2, 8])
+	})
+
+	test('prefixIdx === tailIdx → only one breakpoint, no duplicate', () => {
+		// preamble is the whole list, no suffix: tail = 3 - 1 - 0 = 2, prefix = 3 - 1 = 2
+		const messages = userMessages(3)
+		const result = applyCacheBreakpoint(messages, 0, undefined, 3)
+		expect(cachedIndices(result)).toEqual([2])
+	})
+
+	test('cachedPrefixCount larger than messages.length → out-of-range prefix ignored, tail still applied', () => {
+		const messages = userMessages(4)
+		const result = applyCacheBreakpoint(messages, 0, undefined, 99)
+		// prefix = 98 (out of range, ignored), tail = 4 - 1 - 0 = 3
+		expect(cachedIndices(result)).toEqual([3])
+	})
+
+	test('ttl is propagated onto the marked messages', () => {
+		const messages = userMessages(6)
+		const result = applyCacheBreakpoint(messages, 0, '1h', 2)
+		// prefix = 1, tail = 5
+		for (const idx of [1, 5]) {
+			const m = result[idx]
+			expect('cacheControl' in m && m.cacheControl).toEqual({ type: 'ephemeral', ttl: '1h' })
+		}
+	})
+
+	test('does not mutate the input array', () => {
+		const messages = userMessages(5)
+		applyCacheBreakpoint(messages, 0, undefined, 2)
+		expect(cachedIndices(messages)).toEqual([])
+	})
+})

package/src/core/llm/cache-breakpoints.ts

@@ -1,7 +1,7 @@
 import type { LLMMessage, LLMMessageCacheControl } from '~/core/agents/state.js'
 
 /**
- * Mark the prompt cache breakpoint on a message list.
+ * Mark the prompt cache breakpoints on a message list.
  *
  * Flag-based: the target message gets a `cacheControl` marker. Providers that
  * support ephemeral prompt caching (anthropic, openrouter) react to the flag
@@ -10,9 +10,23 @@ import type { LLMMessage, LLMMessageCacheControl } from '~/core/agents/state.js'
  * (text / tool_use / tool_result / image). This matches the API semantics
  * "cache the prefix up to and including this block".
  *
- * Target index is `messages.length - 1 - uncachedSuffixCount`. The suffix is
- * the tail of messages that must remain fresh (e.g. ephemeral session context
- * rebuilt each inference).
+ * Up to two breakpoints are set:
+ *
+ * 1. **Tail breakpoint** at `messages.length - 1 - uncachedSuffixCount`. The
+ *    suffix is the tail of messages that must remain fresh (e.g. ephemeral
+ *    session context rebuilt each inference).
+ *
+ * 2. **Stable prefix breakpoint** at `cachedPrefixCount - 1` (the last preamble
+ *    message), set only when `cachedPrefixCount > 0`. The preamble is byte-
+ *    identical on every call, but the prefix before the tail breakpoint churns
+ *    turn-to-turn for compacting agents (regenerated summary, sliding recent
+ *    window), so the tail breakpoint never produces a stable cache entry for
+ *    the large immutable preamble. Pinning a second breakpoint at the end of
+ *    the preamble lets Anthropic cache that prefix once and read it at 0.1× on
+ *    every inference AND compaction call. Anthropic allows up to 4 breakpoints
+ *    and matches the longest cached prefix, so the two coexist.
+ *
+ * If the prefix and tail indices coincide, only one breakpoint is set.
  *
  * `ttl` opts into Anthropic's 1-hour cache tier (write cost 2× input, read
  * still 0.1×). Useful for long-lived agents where the default 5-minute TTL
@@ -22,26 +36,30 @@ export function applyCacheBreakpoint(
 	messages: LLMMessage[],
 	uncachedSuffixCount: number,
 	ttl?: '5m' | '1h',
+	cachedPrefixCount = 0,
 ): LLMMessage[] {
-	const idx = messages.length - 1 - uncachedSuffixCount
-	if (idx < 0) return messages
-
 	const cacheControl: LLMMessageCacheControl = ttl ? { type: 'ephemeral', ttl } : { type: 'ephemeral' }
-	const target = messages[idx]
 	const result = [...messages]
-	switch (target.role) {
-		case 'user':
-			result[idx] = { ...target, cacheControl }
-			break
-		case 'assistant':
-			result[idx] = { ...target, cacheControl }
-			break
-		case 'system':
-			result[idx] = { ...target, cacheControl }
-			break
-		case 'tool':
-			result[idx] = { ...target, cacheControl }
-			break
+
+	const mark = (idx: number) => {
+		if (idx < 0 || idx >= result.length) return
+		const target = result[idx]
+		switch (target.role) {
+			case 'user':
+			case 'assistant':
+			case 'system':
+			case 'tool':
+				result[idx] = { ...target, cacheControl }
+		}
 	}
+
+	const tailIdx = messages.length - 1 - uncachedSuffixCount
+	// Stable prefix breakpoint at the last preamble message. Pins a cache entry
+	// that survives turn-to-turn churn in the conversation tail (regenerated
+	// summary, sliding recent window), so the immutable preamble is read at 0.1×
+	// on every inference AND compaction call instead of being re-billed each turn.
+	const prefixIdx = cachedPrefixCount - 1
+	if (prefixIdx !== tailIdx) mark(prefixIdx)
+	mark(tailIdx)
 	return result
 }

package/src/core/llm/state.ts

@@ -48,6 +48,18 @@ export type LLMMetrics = {
 // LLM events
 // ============================================================================
 
+const llmMetricsSchema = z4.object({
+	promptTokens: z4.number(),
+	completionTokens: z4.number(),
+	totalTokens: z4.number(),
+	latencyMs: z4.number(),
+	model: z4.string(),
+	provider: z4.string().optional(),
+	cost: z4.number().optional(),
+	cachedTokens: z4.number().optional(),
+	cacheWriteTokens: z4.number().optional(),
+})
+
 export const llmEvents = createEventsFactory({
 	events: {
 		inference_started: z4.object({
@@ -66,19 +78,20 @@ export const llmEvents = createEventsFactory({
 					input: z4.unknown(),
 				})),
 			}),
-			metrics: z4.object({
-				promptTokens: z4.number(),
-				completionTokens: z4.number(),
-				totalTokens: z4.number(),
-				latencyMs: z4.number(),
-				model: z4.string(),
-				provider: z4.string().optional(),
-				cost: z4.number().optional(),
-				cachedTokens: z4.number().optional(),
-				cacheWriteTokens: z4.number().optional(),
-			}),
+			metrics: llmMetricsSchema,
 			llmCallId: llmCallIdSchema.optional(),
 		}),
+		/**
+		 * A side-channel ("auxiliary") inference completed — e.g. the context-compact
+		 * plugin asking the model for a summary. Unlike `inference_completed`, this
+		 * does NOT touch conversation state; it exists purely so the call's token
+		 * usage and cost are still accounted in session stats and metadata. Without
+		 * it, compaction (and any other auxiliary call) would be billed but invisible.
+		 */
+		auxiliary_inference_completed: z4.object({
+			agentId: agentIdSchema,
+			metrics: llmMetricsSchema,
+		}),
 		inference_failed: z4.object({
 			agentId: agentIdSchema,
 			error: z4.string(),
@@ -89,4 +102,5 @@ export const llmEvents = createEventsFactory({
 
 export type InferenceStartedEvent = (typeof llmEvents)['Events']['inference_started']
 export type InferenceCompletedEvent = (typeof llmEvents)['Events']['inference_completed']
+export type AuxiliaryInferenceCompletedEvent = (typeof llmEvents)['Events']['auxiliary_inference_completed']
 export type InferenceFailedEvent = (typeof llmEvents)['Events']['inference_failed']

package/src/index.ts

@@ -82,14 +82,15 @@ export type { BuiltinEvent } from './builtin-events.js'
 export type { AgentChatMessage, AskUserChatMessage, ChatMessage, UserChatMessage } from '~/plugins/user-chat/index.js'
 
 // Plugins
-export { agentStatusPlugin } from '~/plugins/agent-status/plugin.js'
+export { agentStatusPlugin, agentStoppedNotificationSchema } from '~/plugins/agent-status/plugin.js'
+export type { AgentStoppedNotification } from '~/plugins/agent-status/plugin.js'
 export { agentsPlugin } from '~/plugins/agents/plugin.js'
 export type { AgentsPluginConfig } from '~/plugins/agents/plugin.js'
 export { contextCompactPlugin } from '~/plugins/context-compact/plugin.js'
 export type { ContextCompactPluginConfig } from '~/plugins/context-compact/plugin.js'
-export { limitsGuardPlugin, selectAgentCounters } from '~/plugins/limits-guard/plugin.js'
-export type { AgentCounters, LimitsAgentConfig } from '~/plugins/limits-guard/plugin.js'
-export type { AgentLimits } from '~/plugins/limits-guard/config.js'
+export { limitsGuardPlugin, selectAgentCounters, sumSessionSpend } from '~/plugins/limits-guard/plugin.js'
+export type { AgentCounters, BudgetExceededEvent, LimitsAgentConfig } from '~/plugins/limits-guard/plugin.js'
+export type { AgentLimits, LimitsSessionConfig } from '~/plugins/limits-guard/config.js'
 export { mailboxPlugin } from '~/plugins/mailbox/plugin.js'
 export type { MailboxAgentConfig, MailboxPresetConfig } from '~/plugins/mailbox/plugin.js'
 export { resultEvictionPlugin } from '~/plugins/result-eviction/plugin.js'

package/src/plugins/agent-status/agent-status.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import type { PluginNotification } from '~/core/plugins/plugin-builder.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { limitsGuardPlugin } from '~/plugins/limits-guard/plugin.js'
+import { createMultiAgentPreset, createTestPreset, type TestSession, TestHarness } from '~/testing/index.js'
+import { type AgentStoppedNotification, agentStatusPlugin } from './plugin.js'
+
+type StatusPayload = { sessionId: string; agentId: string; status: string; definitionName?: string; timestamp: number }
+
+const agentStatusNotifications = (session: TestSession): StatusPayload[] =>
+	session.getNotifications()
+		.filter((n: PluginNotification) => n.pluginName === 'agent-status' && n.type === 'agentStatus')
+		.map((n) => n.payload as StatusPayload)
+
+const agentStoppedNotifications = (session: TestSession): AgentStoppedNotification[] =>
+	session.getNotifications()
+		.filter((n: PluginNotification) => n.pluginName === 'agent-status' && n.type === 'agentStopped')
+		.map((n) => n.payload as AgentStoppedNotification)
+
+async function waitForAgentStatus(session: TestSession, agentId: AgentId, status: string, timeoutMs = 5000): Promise<void> {
+	const deadline = Date.now() + timeoutMs
+	while (Date.now() < deadline) {
+		const agentState = session.state.agents.get(agentId)
+		if (agentState?.status === status) return
+		await new Promise((r) => setTimeout(r, 10))
+	}
+	throw new Error(`waitForAgentStatus timed out after ${timeoutMs}ms (wanted ${status}) for agent ${agentId}`)
+}
+
+describe('agent-status plugin', () => {
+	describe('agentStatus (existing behavior)', () => {
+		it('emits thinking on start and idle on completion', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				systemPlugins: [agentStatusPlugin],
+				llmProvider: MockLLMProvider.withFixedResponse({ content: 'Done', toolCalls: [] }),
+			})
+
+			const session = await harness.createSession('test')
+			const entryAgentId = session.getEntryAgentId()!
+			await session.sendAndWaitForIdle('Hello')
+
+			const statuses = agentStatusNotifications(session).map((p) => p.status)
+			expect(statuses).toContain('thinking')
+			expect(statuses).toContain('idle')
+
+			// No abnormal-terminal notification for a normal completion.
+			expect(agentStoppedNotifications(session)).toHaveLength(0)
+
+			await harness.shutdown()
+		})
+	})
+
+	describe('agentStopped on pause', () => {
+		it('manual pause → agentStopped kind:paused reason:manual with message', async () => {
+			let orchestratorCalls = 0
+			const harness = new TestHarness({
+				presets: [createMultiAgentPreset(
+					[{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] }],
+					{ orchestratorSystem: 'Orchestrator agent.' },
+				)],
+				systemPlugins: [agentStatusPlugin],
+				mockHandler: (request) => {
+					if (request.systemPrompt.includes('Orchestrator')) {
+						orchestratorCalls++
+						if (orchestratorCalls === 1) {
+							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')
+
+			// Manual pause via Session.pauseAgent — the real manual-pause API that
+			// runs onPause hooks (agents.pause only emits the event, no hooks).
+			const innerSession = (session as unknown as { session: { pauseAgent: (id: AgentId, message?: string) => Promise<{ ok: boolean }> } }).session
+			const result = await innerSession.pauseAgent(AgentId('worker_1'), 'Pausing for review')
+			expect(result.ok).toBe(true)
+
+			const stopped = agentStoppedNotifications(session).filter((n) => n.agentId === 'worker_1')
+			expect(stopped).toHaveLength(1)
+			expect(stopped[0].kind).toBe('paused')
+			expect(stopped[0].reason).toBe('manual')
+			expect(stopped[0].message).toBe('Pausing for review')
+			expect(stopped[0].definitionName).toBe('worker')
+			expect(typeof stopped[0].timestamp).toBe('number')
+
+			// idle agentStatus still emitted alongside.
+			expect(agentStatusNotifications(session).some((p) => p.agentId === 'worker_1' && p.status === 'idle')).toBe(true)
+
+			await harness.shutdown()
+		})
+
+		it('limits-guard hard limit → agentStopped kind:paused with reason and message', async () => {
+			let inferenceCount = 0
+			const harness = new TestHarness({
+				presets: [createTestPreset({
+					orchestratorSystem: 'Test agent.',
+					orchestratorPlugins: [limitsGuardPlugin.configureAgent({ limits: { maxTurns: 2 } })],
+				})],
+				systemPlugins: [agentStatusPlugin, limitsGuardPlugin],
+				mockHandler: () => {
+					inferenceCount++
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId(`tc${inferenceCount}`), name: 'tell_user', input: { message: `Turn ${inferenceCount}` } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+			const entryAgentId = session.getEntryAgentId()!
+			await session.sendMessage('Start')
+			await waitForAgentStatus(session, entryAgentId, 'paused')
+
+			const stopped = agentStoppedNotifications(session).filter((n) => n.agentId === String(entryAgentId))
+			expect(stopped.length).toBeGreaterThanOrEqual(1)
+			expect(stopped[0].kind).toBe('paused')
+			// limits-guard pauses via beforeInference {action:'pause'} → reason 'handler',
+			// with the human-readable budget detail in `message`.
+			expect(stopped[0].reason).toBe('handler')
+			expect(stopped[0].message).toBeTruthy()
+
+			await harness.shutdown()
+		})
+	})
+
+	describe('agentStopped on error', () => {
+		it('non-retryable LLM error → agentStopped kind:errored with message', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				systemPlugins: [agentStatusPlugin],
+				llmProvider: MockLLMProvider.withError({ type: 'invalid_request', message: 'Bad request' }),
+			})
+
+			const session = await harness.createSession('test')
+			const entryAgentId = session.getEntryAgentId()!
+			await session.sendMessage('Trigger error')
+			await waitForAgentStatus(session, entryAgentId, 'errored')
+
+			const stopped = agentStoppedNotifications(session).filter((n) => n.agentId === String(entryAgentId))
+			expect(stopped).toHaveLength(1)
+			expect(stopped[0].kind).toBe('errored')
+			expect(stopped[0].reason).toBeUndefined()
+			expect(stopped[0].message).toBe('Bad request')
+			expect(stopped[0].definitionName).toBeDefined()
+
+			await harness.shutdown()
+		})
+	})
+})

package/src/plugins/agent-status/plugin.ts

@@ -14,6 +14,11 @@
  * `idle` fires on `onComplete`, `onError`, and `onPause` — covers every terminal
  * state of an agent turn, including hard-limit pauses (limits-guard) and manual
  * `Session.pauseAgent` calls that would otherwise leave the indicator hung.
+ *
+ * Alongside the `idle` status, abnormal terminal states (pause / error) also emit
+ * a dedicated `agentStopped` notification carrying the pause reason / error detail,
+ * so consumers (e.g. a Cloudflare worker) can alert on a budget pause or crash —
+ * which the coarse `idle` status alone can't distinguish from a normal completion.
  */
 
 import z from 'zod/v4'
@@ -21,6 +26,24 @@ import { agentIdSchema, protocolAgentStatusSchema } from '~/core/agents/schema.j
 import { definePlugin } from '~/core/plugins/index.js'
 import { sessionIdSchema } from '~/core/sessions/schema.js'
 
+/**
+ * Payload for the `agentStopped` notification — emitted when an agent reaches an
+ * abnormal terminal state (paused or errored), as opposed to a normal idle.
+ */
+export const agentStoppedNotificationSchema = z.object({
+	sessionId: sessionIdSchema,
+	agentId: agentIdSchema,
+	definitionName: z.string().optional(),
+	kind: z.enum(['paused', 'errored']),
+	/** Present when kind === 'paused' — why the agent was paused. */
+	reason: z.enum(['limit', 'handler', 'manual']).optional(),
+	/** Human-readable detail (budget message / error message). */
+	message: z.string().optional(),
+	timestamp: z.number(),
+})
+
+export type AgentStoppedNotification = z.infer<typeof agentStoppedNotificationSchema>
+
 export const agentStatusPlugin = definePlugin('agent-status')
 	.notification('agentStatus', {
 		schema: z.object({
@@ -31,6 +54,9 @@ export const agentStatusPlugin = definePlugin('agent-status')
 			timestamp: z.number(),
 		}),
 	})
+	.notification('agentStopped', {
+		schema: agentStoppedNotificationSchema,
+	})
 	.hook('onStart', async (ctx) => {
 		ctx.notify('agentStatus', {
 			sessionId: ctx.sessionId,
@@ -82,6 +108,15 @@ export const agentStatusPlugin = definePlugin('agent-status')
 			definitionName: ctx.agentState.definitionName,
 			timestamp: Date.now(),
 		})
+		// Additive abnormal-terminal signal for alerting (e.g. worker crash alert).
+		ctx.notify('agentStopped', {
+			sessionId: ctx.sessionId,
+			agentId: ctx.agentId,
+			definitionName: ctx.agentState.definitionName,
+			kind: 'errored',
+			message: ctx.error,
+			timestamp: Date.now(),
+		})
 		return null
 	})
 	.hook('onPause', async (ctx) => {
@@ -95,6 +130,20 @@ export const agentStatusPlugin = definePlugin('agent-status')
 			definitionName: ctx.agentState.definitionName,
 			timestamp: Date.now(),
 		})
+		// Additive abnormal-terminal signal carrying the structured pause reason and
+		// message. Read from agentState (set by the agent_paused reducer) rather than
+		// the loosely-typed `ctx.reason`, which actually carries the message string.
+		// A budget breach surfaces as reason:'handler' with the budget detail in
+		// `message` (limits-guard pauses via beforeInference `{action:'pause'}`).
+		ctx.notify('agentStopped', {
+			sessionId: ctx.sessionId,
+			agentId: ctx.agentId,
+			definitionName: ctx.agentState.definitionName,
+			kind: 'paused',
+			reason: ctx.agentState.pauseReason,
+			message: ctx.agentState.pauseMessage,
+			timestamp: Date.now(),
+		})
 		return null
 	})
 	.build()

package/src/plugins/agents/plugin.ts

@@ -127,6 +127,11 @@ function buildChildrenStatus(sessionAgents: Map<AgentId, AgentState>, parentId:
 		const last = previewLastAssistant(c)
 
 		const parts: string[] = [c.id, c.status]
+		// Surface why a child paused (e.g. budget/limit exhaustion) so the parent can
+		// react — bump the budget and resume, reassign the work, or stop.
+		if (c.status === 'paused' && c.pauseMessage) {
+			parts.push(`reason: ${c.pauseMessage.replaceAll('"', "'")}`)
+		}
 		parts.push(`${tools} tools`)
 		parts.push(`${llm} llm`)
 		if (subs > 0) parts.push(`${subs} sub${subs === 1 ? '' : 's'}`)
@@ -414,7 +419,8 @@ 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.`
+- 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.`
 
 		// Only include supervision instructions if supervision is actually enabled
 		// for this session — otherwise the section is misleading bloat.

package/src/plugins/context-compact/context-compact.integration.test.ts

@@ -1,12 +1,14 @@
 import { describe, expect, it } from 'bun:test'
 import z from 'zod/v4'
 import { contextEvents } from '~/core/context/state.js'
+import { llmEvents } from '~/core/llm/state.js'
 import { MockLLMProvider } from '~/core/llm/mock.js'
 import type { InferenceRequest } from '~/core/llm/provider.js'
 import { ModelId } from '~/core/llm/schema.js'
 import type { Preset } from '~/core/preset/index.js'
 import { createTool } from '~/core/tools/definition.js'
 import { ToolCallId } from '~/core/tools/schema.js'
+import { selectSessionStats, sessionStatsPlugin } from '~/plugins/session-stats/index.js'
 import { createTestPreset, TestHarness } from '~/testing/index.js'
 import { contextCompactPlugin } from './index.js'
 
@@ -336,4 +338,64 @@ describe('context-compact plugin', () => {
 			await harness.shutdown()
 		})
 	})
+
+	// =========================================================================
+	// Cost accounting — the compaction summarization call is a real, billed LLM
+	// call. Its tokens/cost must land in session stats, not vanish. (Regression:
+	// runAuxiliaryInference used to skip emitting any stats event.)
+	// =========================================================================
+
+	describe('compaction cost accounting', () => {
+		it('summarization call cost is counted in session stats', async () => {
+			const REGULAR_COST = 0.01
+			const SUMMARY_COST = 0.05
+
+			const harness = new TestHarness({
+				systemPlugins: [contextCompactPlugin, sessionStatsPlugin],
+				presets: [createCompactPreset(10)],
+				mockHandler: (request) => {
+					if (isSummarizationRequest(request)) {
+						return {
+							content: 'Summary of conversation so far.',
+							toolCalls: [],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetricsWithCost(SUMMARY_COST),
+						}
+					}
+					return {
+						content: 'Agent response with some content to increase token count.',
+						toolCalls: [],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetricsWithCost(REGULAR_COST),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('First message')
+			await session.sendAndWaitForIdle('Second message')
+			await session.sendAndWaitForIdle('Third message to trigger actual compaction')
+
+			// Compaction actually ran and made a billed summarization call.
+			const auxEvents = await session.getEventsByType(llmEvents, 'auxiliary_inference_completed')
+			expect(auxEvents.length).toBeGreaterThanOrEqual(1)
+			expect(auxEvents.some((e) => e.metrics.cost === SUMMARY_COST)).toBe(true)
+
+			// Session stats must include both the regular turns AND the summarization
+			// call — in count, tokens, and cost.
+			const inferEvents = await session.getEventsByType(llmEvents, 'inference_completed')
+			const allLlmEvents = [...inferEvents, ...auxEvents]
+			const expectedCost = allLlmEvents.reduce((sum, e) => sum + (e.metrics.cost ?? 0), 0)
+			const expectedTokens = allLlmEvents.reduce((sum, e) => sum + e.metrics.totalTokens, 0)
+
+			const stats = selectSessionStats(session.state)
+			expect(stats.llmCalls).toBe(allLlmEvents.length)
+			expect(stats.totalCost).toBeCloseTo(expectedCost, 10)
+			expect(stats.totalTokens).toBe(expectedTokens)
+			// And the summarization cost is genuinely part of the total (not zero).
+			expect(stats.totalCost).toBeGreaterThanOrEqual(SUMMARY_COST)
+
+			await harness.shutdown()
+		})
+	})
 })

package/src/plugins/context-compact/context-compactor.test.ts

@@ -291,6 +291,7 @@ describe('createContextCompactedEvent', () => {
 				{ role: 'system', content: 'summary' },
 				{ role: 'user', content: 'recent' },
 			],
+			originalMessages: [{ role: 'user', content: 'old message' }],
 			summary: 'The summary',
 			originalTokens: 1000,
 			compactedTokens: 200,
@@ -309,6 +310,8 @@ describe('createContextCompactedEvent', () => {
 		expect(event.newConversationHistory.length).toBe(2)
 		expect(event.newConversationHistory[0].role).toBe('system')
 		expect(event.newConversationHistory[0].content).toBe('summary')
+		expect(event.originalMessages?.length).toBe(1)
+		expect(event.originalMessages?.[0].content).toBe('old message')
 		expect(event.timestamp).toBeDefined()
 	})
 
@@ -318,6 +321,7 @@ describe('createContextCompactedEvent', () => {
 		const toolCallId = generateToolCallId()
 		const result: CompactionResult = {
 			compactedMessages: [{ role: 'tool', content: 'tool result', toolCallId }],
+			originalMessages: [],
 			summary: '',
 			originalTokens: 100,
 			compactedTokens: 50,
@@ -852,6 +856,7 @@ describe('createContextCompactedEvent with historyPath', () => {
 			compactedMessages: [
 				{ role: 'system', content: 'summary' },
 			],
+			originalMessages: [],
 			summary: 'The summary',
 			originalTokens: 1000,
 			compactedTokens: 200,
@@ -871,6 +876,7 @@ describe('createContextCompactedEvent with historyPath', () => {
 			compactedMessages: [
 				{ role: 'system', content: 'summary' },
 			],
+			originalMessages: [],
 			summary: 'The summary',
 			originalTokens: 1000,
 			compactedTokens: 200,