@roj-ai/sdk 0.1.12 → 0.1.14

package/src/plugins/agents/supervision.integration.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { agentsPlugin } from '~/plugins/agents/plugin.js'
+import { mailboxEvents } from '~/plugins/mailbox/index.js'
+import { createMultiAgentPreset, TestHarness, type TestSession } from '~/testing/index.js'
+
+/**
+ * Helper — wait until at least one supervision message has landed in the parent's
+ * mailbox (or timeout). We poll because supervision ticks fire on real timers.
+ */
+async function waitForSupervisorMessage(
+	session: TestSession,
+	toAgentId: AgentId,
+	timeoutMs = 2000,
+): Promise<{ message: { from: unknown; content: string } } | undefined> {
+	const deadline = Date.now() + timeoutMs
+	while (Date.now() < deadline) {
+		const events = await session.getEventsByType(mailboxEvents, 'mailbox_message')
+		const found = events.find((e) =>
+			e.message.from === 'supervisor'
+			&& e.toAgentId === toAgentId
+			&& typeof e.message.content === 'string',
+		)
+		if (found) return found
+		await new Promise((r) => setTimeout(r, 25))
+	}
+	return undefined
+}
+
+describe('agents plugin supervision', () => {
+	it('parent with active children receives a periodic <children-status> snapshot', async () => {
+		let orchestratorCalls = 0
+		let workerCalls = 0
+
+		const harness = new TestHarness({
+			presets: [{
+				...createMultiAgentPreset([
+					{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+				], { orchestratorSystem: 'Orchestrator agent.' }),
+				plugins: [{ pluginName: 'agents', definition: agentsPlugin, config: { superviseChildrenIntervalMs: 100 } }],
+			}],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Long-running task' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					// Subsequent calls: orchestrator does nothing more, just acknowledges.
+					return { content: 'noted', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				// Worker: takes a long time — say something but never reports back.
+				workerCalls++
+				return { content: `Working on step ${workerCalls}`, toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendMessage('Start')
+
+		// Orchestrator is the entry agent in this preset. Wait for a tick.
+		const orchestratorId = session.getEntryAgentId()!
+		const supervisorMsg = await waitForSupervisorMessage(session as never, orchestratorId)
+
+		expect(supervisorMsg).toBeDefined()
+		expect(supervisorMsg!.message.content).toContain('<children-status>')
+		expect(supervisorMsg!.message.content).toContain('worker_1')
+		// Cumulative LLM call count should be present
+		expect(supervisorMsg!.message.content).toMatch(/worker_1[^,\n]*,[^,\n]*,\s*\d+ tools,\s*\d+ llm/)
+
+		await harness.shutdown()
+	})
+
+	it('default (no config) → supervision disabled, no tick fires', async () => {
+		const harness = new TestHarness({
+			presets: [createMultiAgentPreset([
+				{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+			], { orchestratorSystem: 'Orchestrator agent.' })],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Do work' } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				return { content: 'Working', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendMessage('Start')
+
+		// Wait long enough for ticks if they were enabled (they shouldn't).
+		await new Promise((r) => setTimeout(r, 300))
+
+		const events = await session.getEventsByType(mailboxEvents, 'mailbox_message')
+		const supervisorMessages = events.filter(e => e.message.from === 'supervisor')
+		expect(supervisorMessages).toHaveLength(0)
+
+		await harness.shutdown()
+	})
+
+	it('parent without children → no tick fires', async () => {
+		const harness = new TestHarness({
+			presets: [{
+				...createMultiAgentPreset([
+					{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+				], { orchestratorSystem: 'Orchestrator agent.' }),
+				plugins: [{ pluginName: 'agents', definition: agentsPlugin, config: { superviseChildrenIntervalMs: 100 } }],
+			}],
+			mockHandler: (request) => {
+				// Orchestrator never spawns anyone.
+				if (request.systemPrompt.includes('Orchestrator')) {
+					return { content: 'Done without spawning', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				return { content: 'unused', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Start')
+
+		// Give supervision plenty of room to fire (it shouldn't).
+		await new Promise((r) => setTimeout(r, 300))
+
+		const events = await session.getEventsByType(mailboxEvents, 'mailbox_message')
+		const supervisorMessages = events.filter(e => e.message.from === 'supervisor')
+		expect(supervisorMessages).toHaveLength(0)
+
+		await harness.shutdown()
+	})
+
+	it('snapshot includes "first words..last words" preview of last assistant turn', async () => {
+		let orchestratorCalls = 0
+
+		const harness = new TestHarness({
+			presets: [{
+				...createMultiAgentPreset([
+					{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+				], { orchestratorSystem: 'Orchestrator agent.' }),
+				plugins: [{ pluginName: 'agents', definition: agentsPlugin, config: { superviseChildrenIntervalMs: 100 } }],
+			}],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Long task' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'ack', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				// Worker says a long sentence that should be truncated to first..last words
+				return {
+					content: 'Started fetching data and now I am running through the pipeline analyzing the response carefully',
+					toolCalls: [],
+					finishReason: 'stop',
+					metrics: MockLLMProvider.defaultMetrics(),
+				}
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendMessage('Start')
+
+		const orchestratorId = session.getEntryAgentId()!
+		const msg = await waitForSupervisorMessage(session as never, orchestratorId)
+
+		expect(msg).toBeDefined()
+		// Should contain both head (first 5 words) and tail (last 5 words), joined by ".."
+		expect(msg!.message.content).toContain('Started fetching data and now')
+		expect(msg!.message.content).toContain('pipeline analyzing the response carefully')
+		expect(msg!.message.content).toMatch(/\.\.pipeline/)
+
+		await harness.shutdown()
+	})
+
+	it('server restart re-establishes timers via onSessionReady', async () => {
+		const sharedEventStore = new (await import('~/core/events/memory.js')).MemoryEventStore()
+
+		// Counter shared across phases — phase 1 spawns once, then orchestrator goes idle;
+		// phase 2 just acknowledges any wake-up triggered by the supervision tick.
+		let orchestratorCalls = 0
+
+		const buildHarness = (intervalMs: number | undefined) => new TestHarness({
+			eventStore: sharedEventStore,
+			presets: [{
+				...createMultiAgentPreset([
+					{ name: 'worker', system: 'Worker agent.', tools: [], agents: [] },
+				], { orchestratorSystem: 'Orchestrator agent.' }),
+				...(intervalMs !== undefined && {
+					plugins: [{ pluginName: 'agents', definition: agentsPlugin, config: { superviseChildrenIntervalMs: intervalMs } }],
+				}),
+			}],
+			mockHandler: (request) => {
+				if (request.systemPrompt.includes('Orchestrator')) {
+					orchestratorCalls++
+					if (orchestratorCalls === 1) {
+						return {
+							content: null,
+							toolCalls: [{ id: ToolCallId('tc1'), name: 'start_worker', input: { message: 'Long task' } }],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+					return { content: 'noted', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+				}
+				return { content: 'still working', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		// Phase 1: create session with supervision DISABLED (default) so no ticks pre-restart.
+		const harness1 = buildHarness(undefined)
+		const session1 = await harness1.createSession('test')
+		await session1.sendAndWaitForIdle('Start')
+		const hasWorker = () => {
+			for (const agent of session1.state.agents.values()) {
+				if (agent.definitionName === 'worker') return true
+			}
+			return false
+		}
+		expect(hasWorker()).toBe(true)
+		const sessionId = session1.sessionId
+		await harness1.shutdown()
+
+		// Phase 2: restart with supervision enabled. onSessionReady should
+		// re-arm the orchestrator's tick because it has a child.
+		const harness2 = buildHarness(100)
+		const session2 = await harness2.openSession(sessionId)
+
+		const orchestratorId = session2.getEntryAgentId()!
+		const msg = await waitForSupervisorMessage(session2, orchestratorId, 1500)
+		expect(msg).toBeDefined()
+		expect(msg!.message.content).toContain('worker_1')
+
+		await harness2.shutdown()
+	})
+})

package/src/plugins/mailbox/plugin.ts

@@ -90,11 +90,31 @@ export const mailboxPlugin = definePlugin("mailbox")
 			toAgentId: agentIdSchema,
 			content: z.string(),
 			debug: z.boolean().optional(),
+			fromSupervisor: z.boolean().optional(),
 		}),
 		output: z.object({ messageId: z.string() }),
 		handler: async (ctx, input) => {
 			const { toAgentId, content } = input;
 
+			if (input.fromSupervisor) {
+				// System-emitted supervision status — bypasses communication validation.
+				const messageId = generateMessageId(getNextMessageSeq(ctx.pluginState));
+				await ctx.emitEvent(
+					mailboxEvents.create("mailbox_message", {
+						toAgentId,
+						message: {
+							id: messageId,
+							from: "supervisor",
+							content,
+							timestamp: Date.now(),
+							consumed: false,
+						},
+					}),
+				);
+				ctx.scheduleAgent(toAgentId);
+				return Ok({ messageId });
+			}
+
 			if (input.debug) {
 				// Debug messages bypass communication validation
 				const messageId = generateMessageId(getNextMessageSeq(ctx.pluginState));

package/src/plugins/mailbox/schema.ts

@@ -58,6 +58,7 @@ export type MailboxMessageSender =
 	| WorkerId
 	| 'user'
 	| 'debug'
+	| 'supervisor'
 	| typeof ORCHESTRATOR_ROLE
 	| typeof COMMUNICATOR_ROLE
 

package/src/plugins/mailbox/state.ts

@@ -11,6 +11,7 @@ export type MailboxMessageSender =
 	| WorkerId
 	| 'user'
 	| 'debug'
+	| 'supervisor'
 	| typeof ORCHESTRATOR_ROLE
 	| typeof COMMUNICATOR_ROLE
 
@@ -23,7 +24,7 @@ export const mailboxEvents = createEventsFactory({
 				from: z4.union([
 					agentIdSchema,
 					workerIdSchema,
-					z4.enum(['user', 'debug', COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE]),
+					z4.enum(['user', 'debug', 'supervisor', COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE]),
 				]),
 				content: z4.string(),
 				timestamp: z4.number(),

package/src/plugins/uploads/plugin.ts

@@ -2,11 +2,24 @@ import z from 'zod/v4'
 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 { Err, Ok } from '~/lib/utils/result.js'
 import type { PreprocessorRegistry } from './preprocessor.js'
 import { generateUploadId, type MessageAttachment, UploadId, type UploadMetadata } from './schema.js'
 import { type PendingUpload, uploadEvents, type UploadsState } from './state.js'
 
+// ============================================================================
+// Notification schemas
+// ============================================================================
+
+const statusChangedSchema = z.object({
+	sessionId: z.string(),
+	uploadId: z.string(),
+	status: z.enum(['processing', 'ready', 'failed']),
+	extractedContent: z.string().optional(),
+	error: z.string().optional(),
+})
+
 // ============================================================================
 // Constants
 // ============================================================================
@@ -66,6 +79,69 @@ function formatUploadsForLLM(uploads: PendingUpload[], sessionRoot: string): str
 	return blocks.join('\n')
 }
 
+/**
+ * Run preprocessor (with timeout) and persist final upload metadata to disk.
+ * Returns the resolved status + extracted/derived data for the caller to emit.
+ */
+async function runPreprocessAndPersist(args: {
+	uploadId: string
+	sessionId: SessionId
+	uploadStore: FileStore
+	filePath: string
+	filename: string
+	mimeType: string
+	size: number
+	createdAt: number
+	preprocessorRegistry?: PreprocessorRegistry
+}): Promise<{
+	status: 'ready' | 'failed'
+	extractedContent?: string
+	derivedPaths?: string[]
+	error?: string
+}> {
+	const preprocessor = args.preprocessorRegistry?.getForMimeType(args.mimeType)
+
+	let status: 'ready' | 'failed' = 'ready'
+	let extractedContent: string | undefined
+	let derivedPaths: string[] | undefined
+	let errorMessage: string | undefined
+
+	if (preprocessor) {
+		const processPromise = preprocessor.process(args.filePath, args.mimeType, {
+			files: args.uploadStore,
+		})
+		const timeoutPromise = sleep(PROCESSING_TIMEOUT_MS).then(() => ({
+			ok: false as const,
+			error: new Error('Processing timeout'),
+		}))
+		const result = await Promise.race([processPromise, timeoutPromise])
+		if (result.ok) {
+			extractedContent = result.value.extractedContent
+			derivedPaths = result.value.derivedPaths
+		} else {
+			status = 'failed'
+			errorMessage = result.error.message
+		}
+	}
+
+	const metadata: UploadMetadata = {
+		uploadId: UploadId(args.uploadId),
+		sessionId: args.sessionId,
+		filename: args.filename,
+		mimeType: args.mimeType,
+		size: args.size,
+		path: args.filePath,
+		status,
+		extractedContent,
+		derivedPaths,
+		createdAt: args.createdAt,
+		completedAt: Date.now(),
+	}
+	await args.uploadStore.write('meta.json', JSON.stringify(metadata, null, 2))
+
+	return { status, extractedContent, derivedPaths, error: errorMessage }
+}
+
 // ============================================================================
 // Plugin
 // ============================================================================
@@ -73,6 +149,7 @@ function formatUploadsForLLM(uploads: PendingUpload[], sessionRoot: string): str
 export const uploadsPlugin = definePlugin('uploads')
 	.pluginConfig<UploadsPluginConfig>()
 	.events([uploadEvents])
+	.notification('uploadStatusChanged', { schema: statusChangedSchema })
 	.state<UploadsState>({
 		key: 'uploads',
 		initial: (): UploadsState => ({ pending: [] }),
@@ -315,91 +392,179 @@ export const uploadsPlugin = definePlugin('uploads')
 		handler: async (ctx, input) => {
 			const { dataFileStore, preprocessorRegistry } = ctx.pluginConfig
 
-			// Validate
 			if (input.size > MAX_FILE_SIZE) {
 				return Err(ValidationErrors.invalid(`File too large: max ${MAX_FILE_SIZE / (1024 * 1024)}MB`))
 			}
-
 			if (!isAllowedMimeType(input.mimeType)) {
 				return Err(ValidationErrors.invalid(`Unsupported file type: ${input.mimeType}`))
 			}
 
-			// Generate upload ID and scoped store
 			const uploadId = generateUploadId()
 			const uploadStore = dataFileStore.scoped(`sessions/${input.sessionId}/uploads/${uploadId}`)
 
-			// Write file to disk
 			const writeResult = await uploadStore.write(input.filename, input.fileBuffer)
-
 			if (!writeResult.ok) {
 				return Err(ValidationErrors.invalid('Failed to write file'))
 			}
 
-			const filePath = writeResult.value.path
-
-			// Run preprocessor (with timeout)
-			let processingResult: 'success' | 'failed' | 'skipped' = 'skipped'
-			let extractedContent: string | undefined
-			let derivedPaths: string[] | undefined
+			const result = await runPreprocessAndPersist({
+				uploadId: String(uploadId),
+				sessionId: ctx.sessionId,
+				uploadStore,
+				filePath: writeResult.value.path,
+				filename: input.filename,
+				mimeType: input.mimeType,
+				size: input.size,
+				createdAt: Date.now(),
+				preprocessorRegistry,
+			})
 
-			const preprocessor = preprocessorRegistry?.getForMimeType(input.mimeType)
+			await ctx.emitEvent(uploadEvents.create('attachment_uploaded', {
+				uploadId,
+				filename: input.filename,
+				mimeType: input.mimeType,
+				size: input.size,
+				status: result.status,
+				extractedContent: result.extractedContent,
+				derivedPaths: result.derivedPaths,
+				error: result.error,
+			}))
 
-			if (preprocessor) {
-				const processPromise = preprocessor.process(filePath, input.mimeType, {
-					files: uploadStore,
-				})
+			return Ok({
+				uploadId: String(uploadId),
+				status: result.status,
+				extractedContent: result.extractedContent,
+			})
+		},
+	})
+	.method('uploadAsync', {
+		input: z.object({
+			sessionId: z.string(),
+			filename: z.string(),
+			mimeType: z.string(),
+			size: z.number(),
+			fileBuffer: z.custom<Buffer>(),
+		}),
+		output: z.object({
+			uploadId: z.string(),
+			status: z.enum(['processing']),
+		}),
+		handler: async (ctx, input) => {
+			const { dataFileStore, preprocessorRegistry } = ctx.pluginConfig
 
-				const timeoutPromise = sleep(PROCESSING_TIMEOUT_MS).then(() => ({
-					ok: false as const,
-					error: new Error('Processing timeout'),
-				}))
+			if (input.size > MAX_FILE_SIZE) {
+				return Err(ValidationErrors.invalid(`File too large: max ${MAX_FILE_SIZE / (1024 * 1024)}MB`))
+			}
+			if (!isAllowedMimeType(input.mimeType)) {
+				return Err(ValidationErrors.invalid(`Unsupported file type: ${input.mimeType}`))
+			}
 
-				const result = await Promise.race([processPromise, timeoutPromise])
+			const uploadId = generateUploadId()
+			const uploadIdStr = String(uploadId)
+			const uploadStore = dataFileStore.scoped(`sessions/${input.sessionId}/uploads/${uploadId}`)
 
-				if (result.ok) {
-					processingResult = 'success'
-					extractedContent = result.value.extractedContent
-					derivedPaths = result.value.derivedPaths
-				} else {
-					processingResult = 'failed'
-				}
+			const writeResult = await uploadStore.write(input.filename, input.fileBuffer)
+			if (!writeResult.ok) {
+				return Err(ValidationErrors.invalid('Failed to write file'))
 			}
 
-			// Create upload metadata
-			const now = Date.now()
-			const uploadStatus = processingResult === 'failed' ? 'failed' as const : 'ready' as const
-			const metadata: UploadMetadata = {
+			const filePath = writeResult.value.path
+			const createdAt = Date.now()
+
+			// Persist initial 'processing' metadata so listPending sees it before preprocessor finishes.
+			const processingMeta: UploadMetadata = {
 				uploadId,
 				sessionId: ctx.sessionId,
 				filename: input.filename,
 				mimeType: input.mimeType,
 				size: input.size,
 				path: filePath,
-				status: uploadStatus,
-				extractedContent,
-				derivedPaths,
-				createdAt: now,
-				completedAt: now,
+				status: 'processing',
+				createdAt,
+				completedAt: createdAt,
 			}
+			await uploadStore.write('meta.json', JSON.stringify(processingMeta, null, 2))
 
-			// Save metadata
-			await uploadStore.write('meta.json', JSON.stringify(metadata, null, 2))
-
-			// Emit event
 			await ctx.emitEvent(uploadEvents.create('attachment_uploaded', {
 				uploadId,
 				filename: input.filename,
 				mimeType: input.mimeType,
 				size: input.size,
-				status: uploadStatus,
-				extractedContent,
-				derivedPaths,
+				status: 'processing',
 			}))
+			ctx.notify('uploadStatusChanged', {
+				sessionId: input.sessionId,
+				uploadId: uploadIdStr,
+				status: 'processing',
+			})
+
+			// 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 sessionId = ctx.sessionId
+
+			void (async () => {
+				try {
+					const result = await runPreprocessAndPersist({
+						uploadId: uploadIdStr,
+						sessionId,
+						uploadStore,
+						filePath,
+						filename: input.filename,
+						mimeType: input.mimeType,
+						size: input.size,
+						createdAt,
+						preprocessorRegistry,
+					})
+
+					await emitEvent(uploadEvents.create('attachment_uploaded', {
+						uploadId,
+						filename: input.filename,
+						mimeType: input.mimeType,
+						size: input.size,
+						status: result.status,
+						extractedContent: result.extractedContent,
+						derivedPaths: result.derivedPaths,
+						error: result.error,
+					}))
+					notify('uploadStatusChanged', {
+						sessionId: input.sessionId,
+						uploadId: uploadIdStr,
+						status: result.status,
+						extractedContent: result.extractedContent,
+						error: result.error,
+					})
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err)
+					logger.error('Async upload processing crashed', err instanceof Error ? err : undefined, {
+						uploadId: uploadIdStr,
+						filename: input.filename,
+					})
+					try {
+						await emitEvent(uploadEvents.create('attachment_uploaded', {
+							uploadId,
+							filename: input.filename,
+							mimeType: input.mimeType,
+							size: input.size,
+							status: 'failed',
+							error: message,
+						}))
+					} catch {
+						// Even event emission failed — best-effort; nothing useful left to do.
+					}
+					notify('uploadStatusChanged', {
+						sessionId: input.sessionId,
+						uploadId: uploadIdStr,
+						status: 'failed',
+						error: message,
+					})
+				}
+			})()
 
 			return Ok({
-				uploadId: String(uploadId),
-				status: uploadStatus,
-				extractedContent,
+				uploadId: uploadIdStr,
+				status: 'processing' as const,
 			})
 		},
 	})