@roj-ai/sdk 0.1.29 → 0.1.31

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

@@ -20,6 +20,7 @@ export interface ResolvedAgentLimits {
 	softLimitRatio: number
 	maxRepeatedToolCalls: number
 	maxRepeatedResponses: number
+	maxConsecutiveNoProgressTurns: number
 	maxCost: number
 	maxTokens: number
 	maxCompactions: number
@@ -34,6 +35,7 @@ const DEFAULTS: ResolvedAgentLimits = {
 	softLimitRatio: 0.8,
 	maxRepeatedToolCalls: 3,
 	maxRepeatedResponses: 3,
+	maxConsecutiveNoProgressTurns: 3,
 	// Budgets and the compaction cap are opt-in: unset means unlimited.
 	maxCost: Number.POSITIVE_INFINITY,
 	maxTokens: Number.POSITIVE_INFINITY,
@@ -51,6 +53,8 @@ export function resolveAgentLimits(config?: AgentLimits): ResolvedAgentLimits {
 		softLimitRatio: config.softLimitRatio ?? DEFAULTS.softLimitRatio,
 		maxRepeatedToolCalls: config.maxRepeatedToolCalls ?? DEFAULTS.maxRepeatedToolCalls,
 		maxRepeatedResponses: config.maxRepeatedResponses ?? DEFAULTS.maxRepeatedResponses,
+		maxConsecutiveNoProgressTurns:
+			config.maxConsecutiveNoProgressTurns ?? DEFAULTS.maxConsecutiveNoProgressTurns,
 		maxCost: config.maxCost ?? DEFAULTS.maxCost,
 		maxTokens: config.maxTokens ?? DEFAULTS.maxTokens,
 		maxCompactions: config.maxCompactions ?? DEFAULTS.maxCompactions,
@@ -165,16 +169,24 @@ export function checkLimits(counters: AgentCounters, limits: ResolvedAgentLimits
 		{ name: 'maxSpawnedAgents', current: counters.spawnedAgentCount, max: limits.maxSpawnedAgents },
 		{ name: 'maxMessagesSent', current: counters.messagesSentCount, max: limits.maxMessagesSent },
 		{ name: 'maxCompactions', current: counters.compactionCount, max: limits.maxCompactions },
+		{
+			name: 'maxConsecutiveNoProgressTurns',
+			current: counters.consecutiveNoProgressTurns,
+			max: limits.maxConsecutiveNoProgressTurns,
+		},
 	]
 
 	for (const check of hardChecks) {
 		if (check.current >= check.max) {
+			const reason = check.name === 'maxConsecutiveNoProgressTurns'
+				? `No progress detected: ${check.current} consecutive turns used only outbound communication without new input`
+				: `${check.name} reached: ${check.current}/${check.max}`
 			return {
 				status: 'hard_limit',
 				limitName: check.name,
 				currentValue: check.current,
 				hardLimit: check.max,
-				reason: `${check.name} reached: ${check.current}/${check.max}`,
+				reason,
 			}
 		}
 	}

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

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'bun:test'
+import z from 'zod/v4'
 import { AgentId } from '~/core/agents/schema.js'
 import { agentEvents } from '~/core/agents/state.js'
 import { MockLLMProvider } from '~/core/llm/mock.js'
@@ -6,7 +7,10 @@ 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 { createTool } from '~/core/tools/definition.js'
 import { ToolCallId } from '~/core/tools/schema.js'
+import { toolEvents } from '~/core/tools/state.js'
+import { Ok } from '~/lib/utils/result.js'
 import { contextCompactPlugin } from '~/plugins/context-compact/index.js'
 import { getAgentMailbox, selectMailboxState } from '~/plugins/mailbox/query.js'
 import { mailboxEvents } from '~/plugins/mailbox/state.js'
@@ -34,6 +38,15 @@ async function waitForAgentPaused(session: TestSession, agentId: AgentId, timeou
 	throw new Error(`waitForAgentPaused timed out after ${timeoutMs}ms for agent ${agentId}`)
 }
 
+async function waitUntil(predicate: () => boolean, timeoutMs = 10000): Promise<void> {
+	const deadline = Date.now() + timeoutMs
+	while (Date.now() < deadline) {
+		if (predicate()) return
+		await new Promise((resolve) => setTimeout(resolve, 10))
+	}
+	throw new Error(`waitUntil timed out after ${timeoutMs}ms`)
+}
+
 /**
  * Wait for all agents to be either idle (pending with no work) or paused.
  */
@@ -179,6 +192,236 @@ describe('limits-guard plugin', () => {
 
 			await harness.shutdown()
 		})
+
+		it('communication-only loop without new inbound work → soft-stops and remains wakeable', async () => {
+			let inferenceCount = 0
+
+			const harness = createLimitsHarness({
+				presets: [createTestPreset({
+					orchestratorSystem: 'Test agent.',
+					orchestratorPlugins: [limitsGuardPlugin.configureAgent({
+						limits: { maxConsecutiveNoProgressTurns: 3, maxTurns: 100 },
+					})],
+				})],
+				mockHandler: () => {
+					inferenceCount++
+					if (inferenceCount > 4) {
+						return {
+							content: 'Recovered for new work',
+							toolCalls: [],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return {
+						content: null,
+						toolCalls: [{
+							id: ToolCallId(`tc${inferenceCount}`),
+							name: 'tell_user',
+							input: { message: `Still waiting, update ${inferenceCount}` },
+						}],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+			const entryAgentId = session.getEntryAgentId()!
+			await session.sendAndWaitForIdle('Start')
+
+			// The response to "Start" had inbound work. The next three turns were
+			// driven only by the previous tell_user result, so the fourth inference
+			// reaches the limit and its redundant tool call is suppressed.
+			expect(inferenceCount).toBe(4)
+			const toolStarted = await session.getEventsByType(toolEvents, 'tool_started')
+			expect(toolStarted).toHaveLength(3)
+
+			const pauseEvents = await session.getEventsByType(agentEvents, 'agent_paused')
+			expect(pauseEvents.some((event) => event.agentId === entryAgentId)).toBe(false)
+
+			const warningEvents = await session.getEventsByType(limitsEvents, 'limit_warning')
+			const noProgressEvent = warningEvents.find((event) =>
+				event.agentId === entryAgentId
+				&& event.limitName === 'maxConsecutiveNoProgressTurns'
+			)
+			expect(noProgressEvent?.currentValue).toBe(3)
+			expect(noProgressEvent?.message).toContain('until new input arrives')
+			expect(session.state.agents.get(entryAgentId)?.status).toBe('pending')
+
+			// The stop is recoverable without agents.resume or human intervention.
+			await session.sendAndWaitForIdle('Now do real work')
+			expect(inferenceCount).toBe(5)
+			expect(session.state.agents.get(entryAgentId)?.status).toBe('pending')
+
+			await harness.shutdown()
+		})
+
+		it('communication-only replies to distinct user messages do not count as no progress', async () => {
+			let inferenceCount = 0
+			let allowProcessing = false
+			const preset = createTestPreset({
+				orchestratorSystem: 'Test agent.',
+				orchestratorPlugins: [limitsGuardPlugin.configureAgent({
+					limits: { maxConsecutiveNoProgressTurns: 3, maxTurns: 100 },
+				})],
+			})
+			preset.orchestrator.debounceCallback = () => {
+				if (!allowProcessing) return 'wait'
+				allowProcessing = false
+				return 'process_now'
+			}
+			preset.orchestrator.checkIntervalMs = 1
+
+			const harness = createLimitsHarness({
+				presets: [preset],
+				mockHandler: () => {
+					inferenceCount++
+					return {
+						content: null,
+						toolCalls: [{
+							id: ToolCallId(`reply-${inferenceCount}`),
+							name: 'tell_user',
+							input: { message: `Reply ${inferenceCount}` },
+						}],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+			const entryAgentId = session.getEntryAgentId()!
+
+			for (let messageNumber = 1; messageNumber <= 3; messageNumber++) {
+				await session.sendMessage(`User message ${messageNumber}`)
+				allowProcessing = true
+				await waitUntil(() => {
+					const state = session.state.agents.get(entryAgentId)
+					return inferenceCount === messageNumber && state?.pendingToolResults.length === 1
+				})
+
+				const counters = selectPluginState<Map<AgentId, AgentCounters>>(
+					session.state,
+					'agentLimits',
+				)?.get(entryAgentId)
+				expect(counters?.consecutiveNoProgressTurns).toBe(0)
+			}
+
+			const consumedEvents = await session.getEventsByType(agentEvents, 'agent_input_consumed')
+			expect(consumedEvents).toHaveLength(3)
+			expect(consumedEvents.every((event) => event.sourcePlugins.includes('user-chat'))).toBe(true)
+
+			const pauseEvents = await session.getEventsByType(agentEvents, 'agent_paused')
+			expect(pauseEvents.some((event) => event.agentId === entryAgentId)).toBe(false)
+			const warningEvents = await session.getEventsByType(limitsEvents, 'limit_warning')
+			expect(warningEvents.some((event) => event.limitName === 'maxConsecutiveNoProgressTurns')).toBe(false)
+
+			await harness.shutdown()
+		})
+
+		it('send_message followed by non-communication work does not trip the no-progress limit', async () => {
+			let workerInferenceCount = 0
+			let workCount = 0
+
+			const recordWork = createTool({
+				name: 'record_work',
+				description: 'Record one unit of real work.',
+				input: z.object({}),
+				execute: async () => {
+					workCount++
+					return Ok('work recorded')
+				},
+			})
+
+			const harness = createLimitsHarness({
+				presets: [createMultiAgentPreset([
+					{
+						name: 'worker',
+						system: 'Worker agent.',
+						tools: [recordWork],
+						agents: [],
+						plugins: [limitsGuardPlugin.configureAgent({
+							limits: { maxConsecutiveNoProgressTurns: 2, maxTurns: 100 },
+						})],
+					},
+				], { orchestratorSystem: 'Orchestrator agent.' })],
+				mockHandler: (request) => {
+					if (request.systemPrompt.endsWith('Orchestrator agent.')) {
+						const hasStartedWorker = request.messages.some((message) =>
+							message.role === 'assistant'
+							&& message.toolCalls?.some((toolCall) => toolCall.name === 'start_worker')
+						)
+						if (!hasStartedWorker) {
+							return {
+								content: null,
+								toolCalls: [{ id: ToolCallId('start-worker'), name: 'start_worker', input: { message: 'Do the work' } }],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						}
+						return {
+							content: 'Orchestration complete',
+							toolCalls: [],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+
+					workerInferenceCount++
+					switch (workerInferenceCount) {
+						case 1:
+							return {
+								content: null,
+								toolCalls: [{
+									id: ToolCallId('worker-progress'),
+									name: 'send_message',
+									input: { to: 'parent', message: 'Starting real work' },
+								}],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						case 2:
+							return {
+								content: null,
+								toolCalls: [{ id: ToolCallId('worker-work'), name: 'record_work', input: {} }],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						case 3:
+							return {
+								content: null,
+								toolCalls: [{
+									id: ToolCallId('worker-result'),
+									name: 'send_message',
+									input: { to: 'parent', message: 'Real work complete' },
+								}],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+						default:
+							return {
+								content: 'WAITING',
+								toolCalls: [],
+								finishReason: 'stop',
+								metrics: MockLLMProvider.defaultMetrics(),
+							}
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Start', { timeoutMs: 10_000 })
+
+			expect(workCount).toBe(1)
+			expect(workerInferenceCount).toBe(4)
+			expect(session.state.agents.get(AgentId('worker_1'))?.status).toBe('pending')
+
+			const pauseEvents = await session.getEventsByType(agentEvents, 'agent_paused')
+			expect(pauseEvents.some((event) => event.agentId === AgentId('worker_1'))).toBe(false)
+
+			await harness.shutdown()
+		})
 	})
 
 	// =========================================================================
@@ -193,7 +436,9 @@ describe('limits-guard plugin', () => {
 			const harness = createLimitsHarness({
 				presets: [createTestPreset({
 					orchestratorSystem: 'Test agent.',
-					orchestratorPlugins: [limitsGuardPlugin.configureAgent({ limits: { maxTurns: 5 } })],
+					orchestratorPlugins: [limitsGuardPlugin.configureAgent({
+						limits: { maxTurns: 5, maxConsecutiveNoProgressTurns: 100 },
+					})],
 				})],
 				mockHandler: (request) => {
 					inferenceCount++

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

@@ -1,4 +1,4 @@
-import type { AgentId } from '~/core/agents/schema.js'
+import { 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'
@@ -27,6 +27,8 @@ export interface AgentCounters {
 	toolCallCount: number
 	spawnedAgentCount: number
 	messagesSentCount: number
+	/** Consecutive outbound-only turns with no newly consumed inbound work. */
+	consecutiveNoProgressTurns: number
 	/** Number of context compaction events for this agent. */
 	compactionCount: number
 	/** Cumulative LLM cost (USD) summed from inference metrics. NOT reset on resume. */
@@ -46,6 +48,7 @@ export const createAgentCounters = (): AgentCounters => ({
 	toolCallCount: 0,
 	spawnedAgentCount: 0,
 	messagesSentCount: 0,
+	consecutiveNoProgressTurns: 0,
 	compactionCount: 0,
 	costSpent: 0,
 	tokensUsed: 0,
@@ -65,6 +68,12 @@ export function sumSessionSpend(limits: Map<AgentId, AgentCounters>): BudgetSpen
 	return { costSpent, tokensUsed }
 }
 
+const OUTBOUND_COMMUNICATION_TOOLS = new Set(['send_message', 'tell_user'])
+
+function isOutboundCommunicationOnly(toolCalls: Array<{ name: string }>): boolean {
+	return toolCalls.length > 0 && toolCalls.every((toolCall) => OUTBOUND_COMMUNICATION_TOOLS.has(toolCall.name))
+}
+
 /**
  * Extract agent counters from session state (for external consumers).
  */
@@ -166,22 +175,35 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 						: null
 					if (!senderAgentId) return limits
 
-					const senderCounters = limits.get(senderAgentId as AgentId)
+					const senderCounters = limits.get(AgentId(senderAgentId))
 					if (!senderCounters) return limits
 
 					const newLimits = new Map(limits)
-					newLimits.set(senderAgentId as AgentId, {
+					newLimits.set(AgentId(senderAgentId), {
 						...senderCounters,
 						messagesSentCount: senderCounters.messagesSentCount + 1,
 					})
 					return newLimits
 				}
 
+				case 'agent_input_consumed': {
+					const counters = limits.get(event.agentId)
+					if (!counters?.consecutiveNoProgressTurns) return limits
+
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						consecutiveNoProgressTurns: 0,
+					})
+					return newLimits
+				}
+
 				case 'inference_completed': {
 					const counters = limits.get(event.agentId)
 					if (!counters) return limits
 
 					const hasToolCalls = event.response.toolCalls.length > 0
+					const communicationOnly = isOutboundCommunicationOnly(event.response.toolCalls)
 					let newRecentResponseHashes = counters.recentResponseHashes
 
 					if (!hasToolCalls) {
@@ -198,6 +220,9 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 						inferenceCount: counters.inferenceCount + 1,
 						costSpent: counters.costSpent + (event.metrics.cost ?? 0),
 						tokensUsed: counters.tokensUsed + (event.metrics.totalTokens ?? 0),
+						consecutiveNoProgressTurns: communicationOnly
+							? counters.consecutiveNoProgressTurns + 1
+							: 0,
 						recentResponseHashes: newRecentResponseHashes,
 					})
 					return newLimits
@@ -296,6 +321,7 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 						toolCallCount: 0,
 						spawnedAgentCount: 0,
 						messagesSentCount: 0,
+						consecutiveNoProgressTurns: 0,
 						compactionCount: 0,
 						consecutiveToolFailures: {},
 						recentToolCallHashes: [],
@@ -368,9 +394,14 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 		// The inference_completed event hasn't been emitted yet, so project
 		// what the counters will be after it's processed by the reducer.
 		const hasToolCalls = ctx.response.toolCalls.length > 0
+		const communicationOnly = isOutboundCommunicationOnly(ctx.response.toolCalls)
+		const hasInboundWork = ctx.dequeuedSourcePlugins.length > 0
 		const projected: AgentCounters = {
 			...counters,
 			inferenceCount: counters.inferenceCount + 1,
+			consecutiveNoProgressTurns: communicationOnly && !hasInboundWork
+				? counters.consecutiveNoProgressTurns + 1
+				: 0,
 			recentResponseHashes: hasToolCalls
 				? counters.recentResponseHashes
 				: [...counters.recentResponseHashes, responseFingerprint(ctx.response.content)].slice(-10),
@@ -379,6 +410,25 @@ export const limitsGuardPlugin = definePlugin('limits-guard')
 		const limitCheck = checkLimits(projected, resolvedLimits)
 
 		if (limitCheck.status === 'hard_limit') {
+			if (limitCheck.limitName === 'maxConsecutiveNoProgressTurns') {
+				const message = `${limitCheck.reason}; suppressing redundant outbound communication until new input arrives`
+				await ctx.emitEvent(limitsEvents.create('limit_warning', {
+					agentId: ctx.agentId,
+					limitName: limitCheck.limitName,
+					currentValue: limitCheck.currentValue,
+					hardLimit: limitCheck.hardLimit,
+					message,
+				}))
+				ctx.logger.warn('Communication-only agent loop stopped', {
+					agentId: ctx.agentId,
+					consecutiveTurns: limitCheck.currentValue,
+					dequeuedSourcePlugins: ctx.dequeuedSourcePlugins,
+				})
+				return {
+					action: 'modify',
+					response: { content: 'WAITING', toolCalls: [] },
+				}
+			}
 			return { action: 'pause', reason: limitCheck.reason }
 		}
 

package/src/plugins/uploads/plugin.ts

@@ -3,6 +3,7 @@ import { ValidationErrors } from '~/core/errors.js'
 import type { FileStore } from '~/core/file-store/types.js'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
 import { SessionId } from '~/core/sessions/schema.js'
+import { getEntryAgentId } from '~/core/sessions/state.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { PreprocessorRegistry } from './preprocessor.js'
 import { generateUploadId, type MessageAttachment, UploadId, type UploadMetadata } from './schema.js'
@@ -430,6 +431,11 @@ export const uploadsPlugin = definePlugin('uploads')
 				error: result.error,
 			}))
 
+			const entryAgentId = getEntryAgentId(ctx.sessionState)
+			if (result.status === 'ready' && entryAgentId) {
+				ctx.scheduleAgent(entryAgentId)
+			}
+
 			return Ok({
 				uploadId: String(uploadId),
 				status: result.status,
@@ -501,8 +507,9 @@ export const uploadsPlugin = definePlugin('uploads')
 			// Capture refs from ctx before the handler returns — `notify`/`emitEvent`
 			// closures stay valid for the lifetime of the session, which in roj
 			// outlives any single handler call.
-			const { emitEvent, notify, logger } = ctx
+			const { emitEvent, notify, logger, scheduleAgent } = ctx
 			const sessionId = ctx.sessionId
+			const entryAgentId = getEntryAgentId(ctx.sessionState)
 
 			void (async () => {
 				try {
@@ -528,6 +535,9 @@ export const uploadsPlugin = definePlugin('uploads')
 						derivedPaths: result.derivedPaths,
 						error: result.error,
 					}))
+					if (result.status === 'ready' && entryAgentId) {
+						scheduleAgent(entryAgentId)
+					}
 					notify('uploadStatusChanged', {
 						sessionId: input.sessionId,
 						uploadId: uploadIdStr,