@roj-ai/sdk 0.1.19 → 0.1.21

package/src/plugins/limits-guard/limits-guard.integration.test.ts

@@ -2,11 +2,17 @@ import { describe, expect, it } from 'bun:test'
 import { AgentId } from '~/core/agents/schema.js'
 import { agentEvents } from '~/core/agents/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 { llmEvents } from '~/core/llm/state.js'
 import { selectPluginState } from '~/core/sessions/reducer.js'
 import { ToolCallId } from '~/core/tools/schema.js'
+import { contextCompactPlugin } from '~/plugins/context-compact/index.js'
+import { getAgentMailbox, selectMailboxState } from '~/plugins/mailbox/query.js'
+import { mailboxEvents } from '~/plugins/mailbox/state.js'
 import { createMultiAgentPreset, createTestPreset, TestHarness } from '~/testing/index.js'
 import type { AgentCounters } from './plugin.js'
-import { limitsGuardPlugin } from './plugin.js'
+import { limitsEvents, limitsGuardPlugin } from './plugin.js'
 
 function createLimitsHarness(options: Omit<ConstructorParameters<typeof TestHarness>[0], 'systemPlugins'>) {
 	return new TestHarness({ ...options, systemPlugins: [limitsGuardPlugin] })
@@ -434,4 +440,328 @@ describe('limits-guard plugin', () => {
 			await harness.shutdown()
 		})
 	})
+
+	// =========================================================================
+	// budgets (cost / tokens)
+	// =========================================================================
+
+	describe('budgets', () => {
+		it('agent exceeding cost budget → paused with budget_exceeded event', async () => {
+			let n = 0
+			const harness = createLimitsHarness({
+				presets: [createTestPreset({
+					orchestratorSystem: 'Test agent.',
+					// $0.50 per call, $1.00 budget → pauses before the 3rd call.
+					orchestratorPlugins: [limitsGuardPlugin.configureAgent({ limits: { maxCost: 1.0, maxTurns: 100 } })],
+				})],
+				mockHandler: () => {
+					n++
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId(`tc${n}`), name: 'tell_user', input: { message: `Turn ${n}` } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetricsWithCost(0.5),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+			const entryAgentId = session.getEntryAgentId()!
+			await session.sendMessage('Start')
+			await waitForAgentPaused(session, entryAgentId)
+
+			expect(session.state.agents.get(entryAgentId)!.status).toBe('paused')
+
+			const counters = selectPluginState<Map<AgentId, AgentCounters>>(session.state, 'agentLimits')?.get(entryAgentId)
+			expect(counters!.costSpent).toBeGreaterThanOrEqual(1.0)
+
+			const budgetEvents = await session.getEventsByType(limitsEvents, 'budget_exceeded')
+			const evt = budgetEvents.find(e => e.agentId === entryAgentId)
+			expect(evt).toBeDefined()
+			expect(evt!.scope).toBe('agent')
+			expect(evt!.limitName).toBe('maxCost')
+
+			await harness.shutdown()
+		})
+
+		it('costSpent is preserved across resume — budget cannot be bypassed by pausing', async () => {
+			let n = 0
+			const harness = createLimitsHarness({
+				presets: [createTestPreset({
+					orchestratorSystem: 'Test agent.',
+					orchestratorPlugins: [limitsGuardPlugin.configureAgent({ limits: { maxCost: 1.0, maxTurns: 100 } })],
+				})],
+				mockHandler: () => {
+					n++
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId(`tc${n}`), name: 'tell_user', input: { message: `Turn ${n}` } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetricsWithCost(0.5),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+			const entryAgentId = session.getEntryAgentId()!
+			await session.sendMessage('Start')
+			await waitForAgentPaused(session, entryAgentId)
+
+			const before = selectPluginState<Map<AgentId, AgentCounters>>(session.state, 'agentLimits')?.get(entryAgentId)
+			expect(before).toBeDefined()
+			expect(before!.costSpent).toBeGreaterThanOrEqual(1.0)
+
+			await session.callPluginMethod('agents.resume', { agentId: String(entryAgentId) })
+			// Budget is still exhausted → agent pauses again immediately without inferring.
+			await waitForAgentPaused(session, entryAgentId)
+
+			const after = selectPluginState<Map<AgentId, AgentCounters>>(session.state, 'agentLimits')?.get(entryAgentId)
+			expect(after).toBeDefined()
+			// Anti-looping counter reset…
+			expect(after!.inferenceCount).toBe(0)
+			// …but spend preserved, so the cap is not bypassable.
+			expect(after!.costSpent).toBeGreaterThanOrEqual(before!.costSpent)
+
+			await harness.shutdown()
+		})
+
+		it('child pausing on budget → parent is notified via a child-paused message', async () => {
+			let orchestratorCalls = 0
+			let workerCalls = 0
+			const harness = createLimitsHarness({
+				presets: [createTestPreset({
+					orchestratorSystem: 'Orchestrator agent.',
+					agents: [{
+						name: 'worker',
+						system: 'Worker agent.',
+						tools: [],
+						agents: [],
+						// $0.50 per call, $0.50 budget → pauses at the 2nd inference's
+						// beforeInference (after one completed call spent the budget).
+						plugins: [limitsGuardPlugin.configureAgent({ limits: { maxCost: 0.5, maxTurns: 100 } })],
+					}],
+				})],
+				mockHandler: (request) => {
+					// Worker: keep spending until the budget pauses it.
+					if (request.systemPrompt.includes('Worker agent.')) {
+						workerCalls++
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId(`w${workerCalls}`), name: 'tell_user', input: { message: `Work ${workerCalls}` } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetricsWithCost(0.5),
+						}
+					}
+					// Orchestrator: spawn the worker exactly once, then idle.
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('spawn'), name: 'start_worker', input: { message: 'Do work' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'Waiting', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				},
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendMessage('Start')
+			await waitForAgentPaused(session, AgentId('worker_1'))
+
+			const orchestratorId = session.getEntryAgentId()!
+			// The mailbox plugin's onPause hook reports the pause to the parent.
+			// onPause runs *after* the agent_paused event (which flips status to
+			// 'paused'), so poll for the notification.
+			const findNotice = async () =>
+				(await session.getEventsByType(mailboxEvents, 'mailbox_message')).find(m =>
+					m.toAgentId === orchestratorId
+					&& m.message.from === AgentId('worker_1')
+					&& m.message.content.includes('<child-paused')
+					&& m.message.content.includes('worker_1'),
+				)
+			let notice = await findNotice()
+			const deadline = Date.now() + 5000
+			while (!notice && Date.now() < deadline) {
+				await new Promise(r => setTimeout(r, 20))
+				notice = await findNotice()
+			}
+			expect(notice).toBeDefined()
+
+			await harness.shutdown()
+		})
+
+		it('child-paused notice is actually consumed by a parent that already went idle', async () => {
+			// Regression guard for the lifecycle: a parent that finished its work is
+			// NOT in a terminal "complete" state — it's persisted as `pending` with an
+			// empty mailbox. When the child pauses and delivers <child-paused>, the
+			// dequeue check flips the parent's decide() from "complete" back to "infer",
+			// so the parent wakes and reads the message rather than leaving it unconsumed.
+			let workerCalls = 0
+			let orchestratorSawChildPaused = false
+
+			const requestHasChildPaused = (request: InferenceRequest): boolean =>
+				request.messages.some((m) => {
+					const c = typeof m.content === 'string' ? m.content : JSON.stringify(m.content)
+					return c.includes('<child-paused')
+				})
+
+			const harness = createLimitsHarness({
+				presets: [createTestPreset({
+					orchestratorSystem: 'Orchestrator agent.',
+					agents: [{
+						name: 'worker',
+						system: 'Worker agent.',
+						tools: [],
+						agents: [],
+						plugins: [limitsGuardPlugin.configureAgent({ limits: { maxCost: 0.5, maxTurns: 100 } })],
+					}],
+				})],
+				mockHandler: (request) => {
+					if (request.systemPrompt.includes('Worker agent.')) {
+						workerCalls++
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId(`w${workerCalls}`), name: 'tell_user', input: { message: `Work ${workerCalls}` } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetricsWithCost(0.5),
+						}
+					}
+					// Orchestrator: spawn the worker once, then go idle. Any later wake-up
+					// is driven by an incoming message — record if it carried the notice.
+					if (requestHasChildPaused(request)) orchestratorSawChildPaused = true
+					if (workerCalls === 0) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('spawn'), name: 'start_worker', input: { message: 'Do work' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'Acknowledged', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				},
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendMessage('Start')
+			await waitForAgentPaused(session, AgentId('worker_1'))
+
+			// The parent should wake from idle and run an inference that includes the
+			// <child-paused> message — proving the notice is consumed, not orphaned.
+			const deadline = Date.now() + 5000
+			while (!orchestratorSawChildPaused && Date.now() < deadline) {
+				await new Promise(r => setTimeout(r, 20))
+			}
+			expect(orchestratorSawChildPaused).toBe(true)
+
+			// And the message is marked consumed in the parent's mailbox.
+			const orchestratorId = session.getEntryAgentId()!
+			const mailbox = getAgentMailbox(selectMailboxState(session.state), orchestratorId)
+			const childPausedMsg = mailbox.find((m) => m.content.includes('<child-paused'))
+			expect(childPausedMsg).toBeDefined()
+			expect(childPausedMsg!.consumed).toBe(true)
+
+			await harness.shutdown()
+		})
+
+		it('compaction (auxiliary inference) cost counts toward the budget', async () => {
+			// The compaction summarization is a real, billed LLM call routed through
+			// runAuxiliaryInference → auxiliary_inference_completed. It must be charged
+			// against the cost budget, otherwise an agent could spend unboundedly on
+			// compaction without ever tripping its cap.
+			const REGULAR_COST = 0.1
+			const SUMMARY_COST = 5.0
+
+			// Compaction request detection: inline compaction appends a trailing user
+			// message containing the summarization marker.
+			const isSummarizationRequest = (request: InferenceRequest): boolean => {
+				const last = request.messages[request.messages.length - 1]
+				if (!last || last.role !== 'user') return false
+				const content = typeof last.content === 'string' ? last.content : JSON.stringify(last.content)
+				return content.includes('[CONTEXT COMPACTION REQUEST]')
+			}
+
+			const harness = new TestHarness({
+				systemPlugins: [contextCompactPlugin, limitsGuardPlugin],
+				presets: [createTestPreset({
+					orchestratorSystem: 'Test agent.',
+					plugins: [
+						contextCompactPlugin.configure({
+							compaction: { model: ModelId('mock'), maxTokens: 10, keepRecentMessages: 2 },
+						}),
+					],
+					// Budget large enough to survive the cheap regular turns but small
+					// enough that one expensive summarization call blows past it.
+					orchestratorPlugins: [
+						limitsGuardPlugin.configureAgent({ limits: { maxCost: 2.0, maxTurns: 100 } }),
+					],
+				})],
+				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')
+			const entryAgentId = session.getEntryAgentId()!
+
+			// Returns once the agent is either idle or paused — used because we don't
+			// know up front whether the compaction cost trips the budget on the same
+			// turn (depends on beforeInference hook ordering) or on the next one.
+			const waitForIdleOrPaused = async (timeoutMs = 10000): Promise<'idle' | 'paused'> => {
+				const deadline = Date.now() + timeoutMs
+				while (Date.now() < deadline) {
+					const st = session.state.agents.get(entryAgentId)
+					if (st?.status === 'paused') return 'paused'
+					if (st?.status === 'pending' && st.pendingToolCalls.length === 0 && st.pendingToolResults.length === 0) {
+						return 'idle'
+					}
+					await new Promise(r => setTimeout(r, 10))
+				}
+				throw new Error('waitForIdleOrPaused timed out')
+			}
+
+			await session.sendAndWaitForIdle('First message')
+			await session.sendAndWaitForIdle('Second message')
+			// Third message triggers compaction (the expensive summarization call).
+			// It may pause on this turn or settle idle and pause on the next one.
+			await session.sendMessage('Third message to trigger compaction')
+			if (await waitForIdleOrPaused() === 'idle') {
+				await session.sendMessage('Fourth message')
+			}
+			await waitForAgentPaused(session, entryAgentId)
+
+			// Compaction genuinely ran and was billed.
+			const auxEvents = await session.getEventsByType(llmEvents, 'auxiliary_inference_completed')
+			expect(auxEvents.some((e) => e.metrics.cost === SUMMARY_COST)).toBe(true)
+
+			// The summarization cost is reflected in the agent's tracked spend…
+			const counters = selectPluginState<Map<AgentId, AgentCounters>>(session.state, 'agentLimits')?.get(entryAgentId)
+			expect(counters).toBeDefined()
+			expect(counters!.costSpent).toBeGreaterThanOrEqual(SUMMARY_COST)
+
+			// …and it tripped the cost budget (the regular turns alone, at 0.1 each,
+			// could never reach the 2.0 cap on their own here).
+			const budgetEvents = await session.getEventsByType(limitsEvents, 'budget_exceeded')
+			const evt = budgetEvents.find((e) => e.agentId === entryAgentId)
+			expect(evt).toBeDefined()
+			expect(evt!.scope).toBe('agent')
+			expect(evt!.limitName).toBe('maxCost')
+
+			await harness.shutdown()
+		})
+	})
 })

package/src/plugins/limits-guard/plugin.ts

@@ -1,5 +1,6 @@
 import type { AgentId } from '~/core/agents/schema.js'
 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'
@@ -7,8 +8,15 @@ import type { SessionState } from '~/core/sessions/state.js'
 import { toolEvents } from '~/core/tools/state.js'
 import { responseFingerprint, toolCallFingerprint } from '~/lib/utils/hash.js'
 import { mailboxEvents } from '~/plugins/mailbox/state.js'
-import type { AgentLimits } from './config.js'
-import { checkLimits, countConsecutiveTailDuplicates, resolveAgentLimits } from './limit-guard.js'
+import type { AgentLimits, LimitsSessionConfig } from './config.js'
+import {
+	type BudgetSpend,
+	checkBudget,
+	checkLimits,
+	countConsecutiveTailDuplicates,
+	resolveAgentLimits,
+	resolveSessionLimits,
+} from './limit-guard.js'
 
 // ============================================================================
 // Agent counters (state)
@@ -19,6 +27,12 @@ export interface AgentCounters {
 	toolCallCount: number
 	spawnedAgentCount: number
 	messagesSentCount: number
+	/** Number of context compaction events for this agent. */
+	compactionCount: number
+	/** Cumulative LLM cost (USD) summed from inference metrics. NOT reset on resume. */
+	costSpent: number
+	/** Cumulative total tokens (prompt + completion). NOT reset on resume. */
+	tokensUsed: number
 	/** Tool name → consecutive failure count + last error message. Reset on success. */
 	consecutiveToolFailures: Record<string, { count: number; lastError: string }>
 	/** Ring buffer of last 20 tool call fingerprints ("toolName:inputHash") */
@@ -32,11 +46,25 @@ export const createAgentCounters = (): AgentCounters => ({
 	toolCallCount: 0,
 	spawnedAgentCount: 0,
 	messagesSentCount: 0,
+	compactionCount: 0,
+	costSpent: 0,
+	tokensUsed: 0,
 	consecutiveToolFailures: {},
 	recentToolCallHashes: [],
 	recentResponseHashes: [],
 })
 
+/** Sum cost + tokens across all agents in the session (for the session-wide budget). */
+export function sumSessionSpend(limits: Map<AgentId, AgentCounters>): BudgetSpend {
+	let costSpent = 0
+	let tokensUsed = 0
+	for (const counters of limits.values()) {
+		costSpent += counters.costSpent
+		tokensUsed += counters.tokensUsed
+	}
+	return { costSpent, tokensUsed }
+}
+
 /**
  * Extract agent counters from session state (for external consumers).
  */
@@ -61,10 +89,21 @@ export const limitsEvents = createEventsFactory({
 			hardLimit: z.number(),
 			message: z.string(),
 		}),
+		budget_exceeded: z.object({
+			agentId: agentIdSchema,
+			/** Whether the per-agent or the session-wide budget was hit. */
+			scope: z.enum(['agent', 'session']),
+			/** Which limit tripped: maxCost / maxTokens / maxSessionCost / maxSessionTokens. */
+			limitName: z.string(),
+			spent: z.number(),
+			limit: z.number(),
+			message: z.string(),
+		}),
 	},
 })
 
 export type LimitWarningEvent = (typeof limitsEvents)['Events']['limit_warning']
+export type BudgetExceededEvent = (typeof limitsEvents)['Events']['budget_exceeded']
 
 // ============================================================================
 // Helper
@@ -95,7 +134,8 @@ export interface LimitsAgentConfig {
 }
 
 export const limitsGuardPlugin = definePlugin('limits-guard')
-	.events([agentEvents, llmEvents, toolEvents, mailboxEvents])
+	.events([agentEvents, llmEvents, toolEvents, mailboxEvents, contextEvents, limitsEvents])
+	.pluginConfig<LimitsSessionConfig>()
 	.state({
 		key: 'agentLimits',
 		initial: (): Map<AgentId, AgentCounters> => new Map(),
@@ -156,11 +196,41 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 					newLimits.set(event.agentId, {
 						...counters,
 						inferenceCount: counters.inferenceCount + 1,
+						costSpent: counters.costSpent + (event.metrics.cost ?? 0),
+						tokensUsed: counters.tokensUsed + (event.metrics.totalTokens ?? 0),
 						recentResponseHashes: newRecentResponseHashes,
 					})
 					return newLimits
 				}
 
+				case 'auxiliary_inference_completed': {
+					// Side-channel calls (e.g. context compaction) are billed but don't
+					// touch conversation state, so they count toward cost/token budgets
+					// but NOT toward inferenceCount or the anti-looping response hashes.
+					const counters = limits.get(event.agentId)
+					if (!counters) return limits
+
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						costSpent: counters.costSpent + (event.metrics.cost ?? 0),
+						tokensUsed: counters.tokensUsed + (event.metrics.totalTokens ?? 0),
+					})
+					return newLimits
+				}
+
+				case 'context_compacted': {
+					const counters = limits.get(event.agentId)
+					if (!counters) return limits
+
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						compactionCount: counters.compactionCount + 1,
+					})
+					return newLimits
+				}
+
 				case 'tool_started': {
 					const counters = limits.get(event.agentId)
 					if (!counters) return limits
@@ -214,6 +284,11 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 					const counters = limits.get(event.agentId)
 					if (!counters) return limits
 
+					// Reset the anti-looping counters so the agent can make progress
+					// again. Budget spend (costSpent/tokensUsed) is deliberately NOT
+					// reset — otherwise a per-agent or session cost cap could be bypassed
+					// by repeatedly pausing and resuming. To grant more budget, raise the
+					// configured limit instead.
 					const newLimits = new Map(limits)
 					newLimits.set(event.agentId, {
 						...counters,
@@ -221,6 +296,7 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 						toolCallCount: 0,
 						spawnedAgentCount: 0,
 						messagesSentCount: 0,
+						compactionCount: 0,
 						consecutiveToolFailures: {},
 						recentToolCallHashes: [],
 						recentResponseHashes: [],
@@ -234,6 +310,56 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 		},
 	})
 	.agentConfig<LimitsAgentConfig>()
+	.hook('beforeInference', async (ctx) => {
+		// Budgets are enforced here (before the call) so an exhausted agent is
+		// paused before spending more — cost/tokens of a call aren't known until
+		// after it returns, so we stop the *next* call once the threshold is hit.
+		const counters = ctx.pluginState.get(ctx.agentId)
+		if (!counters) return null
+
+		const agentLimits = resolveAgentLimits(ctx.pluginAgentConfig?.limits)
+		const agentCheck = checkBudget(
+			counters,
+			agentLimits.maxCost,
+			agentLimits.maxTokens,
+			agentLimits.softLimitRatio,
+			{ cost: 'maxCost', tokens: 'maxTokens' },
+		)
+		if (agentCheck.status === 'hard_limit') {
+			await ctx.emitEvent(limitsEvents.create('budget_exceeded', {
+				agentId: ctx.agentId,
+				scope: 'agent',
+				limitName: agentCheck.limitName,
+				spent: agentCheck.currentValue,
+				limit: agentCheck.hardLimit,
+				message: agentCheck.reason,
+			}))
+			return { action: 'pause', reason: `Agent budget exceeded — ${agentCheck.reason}` }
+		}
+
+		const sessionLimits = resolveSessionLimits(ctx.pluginConfig)
+		const sessionSpend = sumSessionSpend(ctx.pluginState)
+		const sessionCheck = checkBudget(
+			sessionSpend,
+			sessionLimits.maxSessionCost,
+			sessionLimits.maxSessionTokens,
+			sessionLimits.softLimitRatio,
+			{ cost: 'maxSessionCost', tokens: 'maxSessionTokens' },
+		)
+		if (sessionCheck.status === 'hard_limit') {
+			await ctx.emitEvent(limitsEvents.create('budget_exceeded', {
+				agentId: ctx.agentId,
+				scope: 'session',
+				limitName: sessionCheck.limitName,
+				spent: sessionCheck.currentValue,
+				limit: sessionCheck.hardLimit,
+				message: sessionCheck.reason,
+			}))
+			return { action: 'pause', reason: `Session budget exceeded — ${sessionCheck.reason}` }
+		}
+
+		return null
+	})
 	.hook('afterInference', async (ctx) => {
 		const resolvedLimits = resolveAgentLimits(ctx.pluginAgentConfig?.limits)
 		const counters = ctx.pluginState.get(ctx.agentId)
@@ -301,6 +427,30 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 			)
 		}
 
+		// Budget soft warnings — per-agent spend, then the session-wide budget.
+		const agentBudget = checkBudget(
+			counters,
+			resolvedLimits.maxCost,
+			resolvedLimits.maxTokens,
+			resolvedLimits.softLimitRatio,
+			{ cost: 'maxCost', tokens: 'maxTokens' },
+		)
+		if (agentBudget.status === 'soft_warning') {
+			parts.push(`⚠️ ${agentBudget.message}. You will be paused when the budget is reached — wrap up.`)
+		}
+
+		const sessionLimits = resolveSessionLimits(ctx.pluginConfig)
+		const sessionBudget = checkBudget(
+			sumSessionSpend(ctx.pluginState),
+			sessionLimits.maxSessionCost,
+			sessionLimits.maxSessionTokens,
+			sessionLimits.softLimitRatio,
+			{ cost: 'maxSessionCost', tokens: 'maxSessionTokens' },
+		)
+		if (sessionBudget.status === 'soft_warning') {
+			parts.push(`⚠️ Session-wide ${sessionBudget.message}.`)
+		}
+
 		return parts.length > 0 ? parts.join('\n\n') : null
 	})
 	.build()

package/src/plugins/mailbox/plugin.ts

@@ -228,6 +228,24 @@ export const mailboxPlugin = definePlugin("mailbox")
 		});
 		return null;
 	})
+	.hook("onPause", async (ctx) => {
+		// Notify the parent immediately when a child pauses (budget/limit exhaustion,
+		// manual pause, …) so it can react: resume after addressing the cause,
+		// reassign the work, or stop. Lives here (not in the agents plugin) because
+		// the agents plugin is disabled on leaf agents that can't spawn — but those
+		// are exactly the agents that pause and need to report upward. mailbox is
+		// enabled on every agent, and self.send wakes the parent. Root agents
+		// (no parent) have no one to notify.
+		const parentId = ctx.agentState.parentId;
+		if (!parentId || !ctx.sessionState.agents.has(parentId)) return null;
+
+		await ctx.self.send({
+			fromAgentId: ctx.agentId,
+			toAgentId: parentId,
+			content: `<child-paused agent="${ctx.agentId}">${ctx.reason ?? "no reason given"}</child-paused>`,
+		});
+		return null;
+	})
 	.systemPrompt((ctx) => {
 		const role = getAgentRole(ctx.agentState, ctx.sessionState);
 		switch (role) {

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

@@ -79,7 +79,11 @@ export const sessionStatsPlugin = definePlugin('session-stats')
 				case 'agent_spawned':
 					return withTimestamp({ agentCount: stats.agentCount + 1 })
 
-				case 'inference_completed': {
+				// inference_completed = main agent turns; auxiliary_inference_completed =
+				// side-channel calls (e.g. context compaction). Both are billed LLM
+				// calls, so both feed the same usage/cost accounting.
+				case 'inference_completed':
+				case 'auxiliary_inference_completed': {
 					const provider = event.metrics.provider
 					const byProvider = provider
 						? {