@roj-ai/sdk 0.1.28 → 0.1.30

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/services/plugin.ts

@@ -468,7 +468,10 @@ export const servicePlugin = definePlugin('services')
 					})
 					if (!result.ok) return Err({ message: result.error.message, recoverable: false })
 
-					return Ok(JSON.stringify(result.value))
+					// Strip cwd: a real host path, meaningless (and misleading) inside
+					// the agent's virtual-root namespace.
+					const { cwd: _cwd, ...agentSafe } = result.value
+					return Ok(JSON.stringify(agentSafe))
 				},
 			}),
 			createTool({

package/src/plugins/services/prompt.ts

@@ -42,9 +42,9 @@ export function buildServiceStatusMessage(
 		if (entry?.error) {
 			line += ` (error: ${entry.error})`
 		}
-		if (entry?.cwd) {
-			line += ` (cwd: ${entry.cwd})`
-		}
+		// Deliberately no cwd: it is a real host path, while sandboxed agents see the
+		// world through virtual roots — leaking it sends them chasing paths that
+		// don't exist in their namespace (see webmaster path-identity incident).
 
 		lines.push(line)
 	}

package/src/plugins/services/schema.ts

@@ -103,6 +103,14 @@ export interface ServiceConfig {
 	startupTimeoutMs?: number
 	/** Auto-pause configuration (interface prepared, not yet implemented) */
 	autoPause?: { inactivityMs: number }
+	/**
+	 * When false, the service is hidden from the owning agent: excluded from its
+	 * service_* tools and the session-context status block. It still runs at the
+	 * session level and stays fully controllable via the services.* methods —
+	 * for infrastructure services (e.g. a CMS sidecar) driven by the platform,
+	 * not by agents. Default: true.
+	 */
+	agentVisible?: boolean
 }
 
 // ============================================================================

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

@@ -13,6 +13,7 @@ import { createTestPreset, TestHarness } from '~/testing/index.js'
 import { serviceEvents, servicePlugin } from './plugin.js'
 import type { ServiceAgentConfig, ServicePluginConfig } from './plugin.js'
 import { PortPool } from './port-pool.js'
+import { buildServiceStatusMessage } from './prompt.js'
 import type { ServiceCommandArgs, ServiceConfig, ServiceCwdArgs, ServiceEntry, ServiceStatus } from './schema.js'
 import { ServiceExecutor } from './service.js'
 
@@ -821,4 +822,132 @@ describe('services plugin', () => {
 			}
 		})
 	})
+
+	// =========================================================================
+	// agentVisible: false — infrastructure services hidden from agents
+	// =========================================================================
+
+	describe('agentVisible: false services', () => {
+		const hiddenService: ServiceConfig = {
+			type: 'hidden-svc',
+			description: 'Infra service driven by the platform, not agents',
+			command: 'sleep 60',
+			agentVisible: false,
+		}
+
+		it('auto-wired agent visibility excludes it: no tool mention, no status line, still method-controllable', async () => {
+			const portPool = new PortPool()
+			const base = createTestPreset({
+				plugins: [servicePlugin.configure({ services: [quickService, hiddenService], portPool })],
+			})
+			// Services attached on the agent definition (defineAgent-style auto-wiring),
+			// NOT via explicit configureAgent — exercises the getAgentConfig filter.
+			const preset = { ...base, orchestrator: { ...base.orchestrator, services: [quickService, hiddenService] } }
+			const harness = createServicesHarness({
+				presets: [preset],
+				llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Hi')
+
+			// Service tools exist (quick is visible) but never mention the hidden service
+			const lastRequest = harness.llmProvider.getLastRequest()
+			const serviceStart = lastRequest?.tools?.find((t) => t.name === 'service_start')
+			expect(serviceStart).toBeDefined()
+			expect(serviceStart?.description).toContain('quick')
+			expect(serviceStart?.description).not.toContain('hidden-svc')
+
+			// The session-context status block skips it too
+			const serialized = JSON.stringify(lastRequest?.messages ?? [])
+			expect(serialized).not.toContain('hidden-svc')
+
+			// Still fully controllable at the session level via services.* methods
+			const entryAgentId = session.getEntryAgentId()!
+			const startResult = await session.callPluginMethod('services.start', {
+				sessionId: String(session.sessionId),
+				agentId: String(entryAgentId),
+				serviceType: 'hidden-svc',
+			})
+			expect(startResult).toMatchObject({ ok: true })
+			await waitForServiceStatus(session, 'hidden-svc', 'ready')
+
+			const statusResult = await session.callPluginMethod('services.status', {
+				sessionId: String(session.sessionId),
+				agentId: String(entryAgentId),
+				serviceType: 'hidden-svc',
+			})
+			expect(statusResult).toMatchObject({ ok: true, value: { status: 'ready' } })
+		})
+	})
+
+	// =========================================================================
+	// Real host paths must not leak into agent-facing surfaces
+	// =========================================================================
+
+	describe('host path hygiene', () => {
+		it('status block omits cwd even when the entry tracks one', () => {
+			const message = buildServiceStatusMessage(
+				[{
+					serviceType: 'quick',
+					status: 'ready',
+					port: 4321,
+					cwd: '/home/user/sessions/0000-real-host-path/packages/web',
+				}],
+				[quickService],
+			)
+			expect(message).toContain('quick')
+			expect(message).toContain('port 4321')
+			expect(message).not.toContain('real-host-path')
+			expect(message).not.toContain('cwd')
+		})
+
+		it('service_status tool output strips cwd', async () => {
+			const portPool = new PortPool()
+			// Absolute cwd so the tracked entry actually carries a host path to leak.
+			const cwdService: ServiceConfig = {
+				type: 'cwd-svc',
+				description: 'Service with a resolved host cwd',
+				command: 'sleep 60',
+				cwd: tmpdir(),
+			}
+			const harness = createServicesHarness({
+				presets: [createServicesPreset([cwdService], ['cwd-svc'], portPool)],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [{
+							id: ToolCallId('tc-start'),
+							name: 'service_start',
+							input: { serviceType: 'cwd-svc' },
+						}],
+					},
+					{
+						toolCalls: [{
+							id: ToolCallId('tc-status'),
+							name: 'service_status',
+							input: { serviceType: 'cwd-svc' },
+						}],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Check the service')
+			await waitForServiceStatus(session, 'cwd-svc', 'ready')
+
+			// The service_status tool result (fed back as a message) must not carry cwd,
+			// while the session-level method keeps returning it for platform callers.
+			const serialized = JSON.stringify(harness.llmProvider.getLastRequest()?.messages ?? [])
+			expect(serialized).not.toContain('"cwd"')
+
+			const entryAgentId = session.getEntryAgentId()!
+			const statusResult = await session.callPluginMethod('services.status', {
+				sessionId: String(session.sessionId),
+				agentId: String(entryAgentId),
+				serviceType: 'cwd-svc',
+			})
+			expect(statusResult).toMatchObject({ ok: true, value: { cwd: expect.any(String) } })
+		})
+	})
 })

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,