@roj-ai/sdk 0.1.20 → 0.1.22

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

@@ -131,6 +131,8 @@ export const DEFAULT_SUMMARY_INSTRUCTION =
 export interface CompactionResult {
 	/** New messages to use (summary + kept messages) */
 	compactedMessages: LLMMessage[]
+	/** The older messages that were summarized away (the compaction input) */
+	originalMessages: LLMMessage[]
 	/** Generated summary text */
 	summary: string
 	/** Token count before compaction */
@@ -274,6 +276,7 @@ export class ContextCompactor {
 			this.logger.warn('No messages to compact', { sessionId, agentId })
 			return Ok({
 				compactedMessages: messages,
+				originalMessages: [],
 				summary: '',
 				originalTokens,
 				compactedTokens: originalTokens,
@@ -349,6 +352,7 @@ export class ContextCompactor {
 
 		return Ok({
 			compactedMessages,
+			originalMessages: toCompact,
 			summary,
 			originalTokens,
 			compactedTokens,
@@ -378,6 +382,7 @@ export function createContextCompactedEvent(
 		contextEvents.create('context_compacted', {
 			agentId,
 			compactedContent: result.summary,
+			originalMessages: result.originalMessages.map(toDisplayMessage),
 			newConversationHistory,
 			originalTokens: result.originalTokens,
 			compactedTokens: result.compactedTokens,
@@ -386,3 +391,29 @@ export function createContextCompactedEvent(
 		}),
 	)
 }
+
+/**
+ * Convert an LLM message into a display-only conversation message, preserving
+ * tool-call and tool-result detail in the rendered content. Used for the
+ * compaction "input" snapshot shown in the debug UI — not for reconstruction.
+ */
+function toDisplayMessage(msg: LLMMessage): CompactedConversationMessage {
+	if (msg.role === 'assistant') {
+		const parts: string[] = []
+		if (msg.content) parts.push(msg.content)
+		if (msg.toolCalls?.length) {
+			for (const tc of msg.toolCalls) {
+				parts.push(`[tool call: ${tc.name}(${JSON.stringify(tc.input)})]`)
+			}
+		}
+		return { role: 'assistant', content: parts.join('\n') }
+	}
+	if (msg.role === 'tool') {
+		const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
+		return { role: 'system', content: `[tool result${msg.toolName ? `: ${msg.toolName}` : ''}]\n${content}` }
+	}
+	return {
+		role: msg.role,
+		content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+	}
+}

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

@@ -23,4 +23,39 @@ export interface AgentLimits {
 	maxRepeatedToolCalls?: number
 	/** Maximum consecutive identical text-only responses. Default: 3 */
 	maxRepeatedResponses?: number
+	/**
+	 * Maximum cumulative LLM cost (USD) this agent may spend before it is paused.
+	 * Spend is summed from `inference_completed` metrics and, unlike the counter
+	 * limits, is NOT reset on resume. Default: unlimited.
+	 */
+	maxCost?: number
+	/**
+	 * Maximum cumulative total tokens (prompt + completion) this agent may consume
+	 * before it is paused. Useful as a fallback when providers don't report cost.
+	 * Not reset on resume. Default: unlimited.
+	 */
+	maxTokens?: number
+	/**
+	 * Maximum number of context compaction events for this agent before it is paused.
+	 * Guards against pathological compaction loops. Reset on resume. Default: unlimited.
+	 */
+	maxCompactions?: number
+}
+
+// ============================================================================
+// Session Limits (budget across all agents)
+// ============================================================================
+
+/**
+ * Session-wide budget, summed across every agent in the session. Configured via
+ * the plugin's session-level config (`pluginConfig`), independent of per-agent
+ * limits. All fields optional - defaults applied via resolveSessionLimits().
+ */
+export interface LimitsSessionConfig {
+	/** Maximum cumulative LLM cost (USD) across all agents. Default: unlimited */
+	maxSessionCost?: number
+	/** Maximum cumulative total tokens across all agents. Default: unlimited */
+	maxSessionTokens?: number
+	/** Ratio of the session budget at which a soft warning is emitted. Default: 0.8 */
+	softLimitRatio?: number
 }

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

@@ -1,4 +1,4 @@
-export type { AgentLimits } from './config.js'
+export type { AgentLimits, LimitsSessionConfig } from './config.js'
 export { limitsGuardPlugin } from './plugin.js'
-export type { AgentCounters, LimitsAgentConfig, LimitWarningEvent } from './plugin.js'
-export { createAgentCounters, limitsEvents } from './plugin.js'
+export type { AgentCounters, BudgetExceededEvent, LimitsAgentConfig, LimitWarningEvent } from './plugin.js'
+export { createAgentCounters, limitsEvents, sumSessionSpend } from './plugin.js'

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'bun:test'
-import { checkLimits, resolveAgentLimits } from './limit-guard.js'
+import { checkBudget, checkLimits, resolveAgentLimits, resolveSessionLimits } from './limit-guard.js'
 import { createAgentCounters } from './plugin.js'
 import type { AgentCounters } from './plugin.js'
 
@@ -14,6 +14,10 @@ describe('resolveAgentLimits', () => {
 		expect(limits.softLimitRatio).toBe(0.8)
 		expect(limits.maxRepeatedToolCalls).toBe(3)
 		expect(limits.maxRepeatedResponses).toBe(3)
+		// Budgets and compaction cap are opt-in (unlimited by default)
+		expect(limits.maxCost).toBe(Number.POSITIVE_INFINITY)
+		expect(limits.maxTokens).toBe(Number.POSITIVE_INFINITY)
+		expect(limits.maxCompactions).toBe(Number.POSITIVE_INFINITY)
 	})
 
 	it('returns defaults when empty config', () => {
@@ -158,4 +162,79 @@ describe('checkLimits', () => {
 		)
 		expect(result.status).toBe('hard_limit')
 	})
+
+	// --- Compaction limit ---
+
+	it('detects maxCompactions hard limit', () => {
+		const limits = resolveAgentLimits({ maxCompactions: 5 })
+		const result = checkLimits(makeCounters({ compactionCount: 5 }), limits)
+		expect(result.status).toBe('hard_limit')
+		if (result.status === 'hard_limit') {
+			expect(result.limitName).toBe('maxCompactions')
+		}
+	})
+
+	it('does not cap compactions by default (unlimited)', () => {
+		const result = checkLimits(makeCounters({ compactionCount: 9999 }), defaultLimits)
+		expect(result.status).toBe('ok')
+	})
+})
+
+describe('checkBudget', () => {
+	const names = { cost: 'maxCost', tokens: 'maxTokens' }
+
+	it('returns ok when under budget', () => {
+		const result = checkBudget({ costSpent: 1, tokensUsed: 100 }, 5, 1000, 0.8, names)
+		expect(result.status).toBe('ok')
+	})
+
+	it('returns ok when unlimited (Infinity)', () => {
+		const result = checkBudget(
+			{ costSpent: 1_000_000, tokensUsed: 1_000_000 },
+			Number.POSITIVE_INFINITY,
+			Number.POSITIVE_INFINITY,
+			0.8,
+			names,
+		)
+		expect(result.status).toBe('ok')
+	})
+
+	it('detects cost hard limit', () => {
+		const result = checkBudget({ costSpent: 5.01, tokensUsed: 0 }, 5, Number.POSITIVE_INFINITY, 0.8, names)
+		expect(result.status).toBe('hard_limit')
+		if (result.status === 'hard_limit') expect(result.limitName).toBe('maxCost')
+	})
+
+	it('detects token hard limit', () => {
+		const result = checkBudget({ costSpent: 0, tokensUsed: 1000 }, Number.POSITIVE_INFINITY, 1000, 0.8, names)
+		expect(result.status).toBe('hard_limit')
+		if (result.status === 'hard_limit') expect(result.limitName).toBe('maxTokens')
+	})
+
+	it('emits soft warning approaching cost budget', () => {
+		const result = checkBudget({ costSpent: 4.2, tokensUsed: 0 }, 5, Number.POSITIVE_INFINITY, 0.8, names)
+		expect(result.status).toBe('soft_warning')
+		if (result.status === 'soft_warning') expect(result.limitName).toBe('maxCost')
+	})
+
+	it('handles sub-dollar budgets without spurious warnings', () => {
+		// floor-based logic would warn at $0 for a $0.50 budget — float-aware must not.
+		const result = checkBudget({ costSpent: 0.1, tokensUsed: 0 }, 0.5, Number.POSITIVE_INFINITY, 0.8, names)
+		expect(result.status).toBe('ok')
+	})
+})
+
+describe('resolveSessionLimits', () => {
+	it('defaults to unlimited', () => {
+		const limits = resolveSessionLimits()
+		expect(limits.maxSessionCost).toBe(Number.POSITIVE_INFINITY)
+		expect(limits.maxSessionTokens).toBe(Number.POSITIVE_INFINITY)
+		expect(limits.softLimitRatio).toBe(0.8)
+	})
+
+	it('overrides specific values', () => {
+		const limits = resolveSessionLimits({ maxSessionCost: 10 })
+		expect(limits.maxSessionCost).toBe(10)
+		expect(limits.maxSessionTokens).toBe(Number.POSITIVE_INFINITY)
+	})
 })

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

@@ -4,7 +4,7 @@
  * Returns the worst result: hard_limit > soft_warning > ok.
  */
 
-import type { AgentLimits } from '~/plugins/limits-guard/config.js'
+import type { AgentLimits, LimitsSessionConfig } from '~/plugins/limits-guard/config.js'
 import type { AgentCounters } from './plugin.js'
 
 // ============================================================================
@@ -20,6 +20,9 @@ export interface ResolvedAgentLimits {
 	softLimitRatio: number
 	maxRepeatedToolCalls: number
 	maxRepeatedResponses: number
+	maxCost: number
+	maxTokens: number
+	maxCompactions: number
 }
 
 const DEFAULTS: ResolvedAgentLimits = {
@@ -31,6 +34,10 @@ const DEFAULTS: ResolvedAgentLimits = {
 	softLimitRatio: 0.8,
 	maxRepeatedToolCalls: 3,
 	maxRepeatedResponses: 3,
+	// Budgets and the compaction cap are opt-in: unset means unlimited.
+	maxCost: Number.POSITIVE_INFINITY,
+	maxTokens: Number.POSITIVE_INFINITY,
+	maxCompactions: Number.POSITIVE_INFINITY,
 }
 
 export function resolveAgentLimits(config?: AgentLimits): ResolvedAgentLimits {
@@ -44,9 +51,98 @@ export function resolveAgentLimits(config?: AgentLimits): ResolvedAgentLimits {
 		softLimitRatio: config.softLimitRatio ?? DEFAULTS.softLimitRatio,
 		maxRepeatedToolCalls: config.maxRepeatedToolCalls ?? DEFAULTS.maxRepeatedToolCalls,
 		maxRepeatedResponses: config.maxRepeatedResponses ?? DEFAULTS.maxRepeatedResponses,
+		maxCost: config.maxCost ?? DEFAULTS.maxCost,
+		maxTokens: config.maxTokens ?? DEFAULTS.maxTokens,
+		maxCompactions: config.maxCompactions ?? DEFAULTS.maxCompactions,
 	}
 }
 
+// ============================================================================
+// Session budget
+// ============================================================================
+
+export interface ResolvedSessionLimits {
+	maxSessionCost: number
+	maxSessionTokens: number
+	softLimitRatio: number
+}
+
+const SESSION_DEFAULTS: ResolvedSessionLimits = {
+	maxSessionCost: Number.POSITIVE_INFINITY,
+	maxSessionTokens: Number.POSITIVE_INFINITY,
+	softLimitRatio: 0.8,
+}
+
+export function resolveSessionLimits(config?: LimitsSessionConfig): ResolvedSessionLimits {
+	if (!config) return SESSION_DEFAULTS
+	return {
+		maxSessionCost: config.maxSessionCost ?? SESSION_DEFAULTS.maxSessionCost,
+		maxSessionTokens: config.maxSessionTokens ?? SESSION_DEFAULTS.maxSessionTokens,
+		softLimitRatio: config.softLimitRatio ?? SESSION_DEFAULTS.softLimitRatio,
+	}
+}
+
+/** Cumulative spend, either for a single agent or summed across the session. */
+export interface BudgetSpend {
+	costSpent: number
+	tokensUsed: number
+}
+
+/**
+ * Budget check (cost + tokens) shared by per-agent and session-wide budgets.
+ *
+ * Kept separate from {@link checkLimits} so it can run in `beforeInference` —
+ * blocking the *next* call once the budget is exhausted — without also tripping
+ * the counter/pattern limits (those are enforced in `afterInference`). Uses
+ * float-aware comparisons (no flooring) so sub-dollar budgets behave correctly.
+ */
+export function checkBudget(
+	spend: BudgetSpend,
+	costLimit: number,
+	tokenLimit: number,
+	softLimitRatio: number,
+	names: { cost: string; tokens: string },
+): LimitCheckResult {
+	const checks: Array<{ name: string; current: number; max: number }> = [
+		{ name: names.cost, current: spend.costSpent, max: costLimit },
+		{ name: names.tokens, current: spend.tokensUsed, max: tokenLimit },
+	]
+
+	// Hard limits
+	for (const check of checks) {
+		if (check.current >= check.max) {
+			return {
+				status: 'hard_limit',
+				limitName: check.name,
+				currentValue: check.current,
+				hardLimit: check.max,
+				reason: `${check.name} reached: ${formatBudget(check.current)}/${formatBudget(check.max)}`,
+			}
+		}
+	}
+
+	// Soft warnings
+	for (const check of checks) {
+		if (check.max !== Number.POSITIVE_INFINITY && check.current >= check.max * softLimitRatio) {
+			return {
+				status: 'soft_warning',
+				limitName: check.name,
+				currentValue: check.current,
+				hardLimit: check.max,
+				message: `Approaching ${check.name} limit: ${formatBudget(check.current)}/${formatBudget(check.max)}`,
+			}
+		}
+	}
+
+	return { status: 'ok' }
+}
+
+/** Format a budget value compactly — 4 decimals for fractional (cost), integer otherwise. */
+function formatBudget(value: number): string {
+	if (value === Number.POSITIVE_INFINITY) return '∞'
+	return Number.isInteger(value) ? String(value) : value.toFixed(4)
+}
+
 // ============================================================================
 // Check result
 // ============================================================================
@@ -68,6 +164,7 @@ export function checkLimits(counters: AgentCounters, limits: ResolvedAgentLimits
 		{ name: 'maxToolCalls', current: counters.toolCallCount, max: limits.maxToolCalls },
 		{ name: 'maxSpawnedAgents', current: counters.spawnedAgentCount, max: limits.maxSpawnedAgents },
 		{ name: 'maxMessagesSent', current: counters.messagesSentCount, max: limits.maxMessagesSent },
+		{ name: 'maxCompactions', current: counters.compactionCount, max: limits.maxCompactions },
 	]
 
 	for (const check of hardChecks) {

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()
+		})
+	})
 })