@roj-ai/sdk 0.0.2

package/src/testing/node-platform.ts

@@ -0,0 +1,80 @@
+/**
+ * Test-only Platform impl backed by `node:fs/promises` + `node:child_process`.
+ *
+ * Mirrors the production adapter from `@roj-ai/sdk/bun-platform` but lives in this
+ * package so tests don't create a workspace cycle. Production SDK code MUST
+ * NOT import from here — use injected `Platform` from the caller instead.
+ */
+
+import { type ChildProcess, execFile as execFileCb, spawn as nodeSpawn } from 'node:child_process'
+import * as fsp from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { promisify } from 'node:util'
+import type { FileSystem, Platform, ProcessRunner } from '~/platform/index.js'
+
+const execFileP = promisify(execFileCb)
+
+export function createNodeFileSystem(): FileSystem {
+	return {
+		readFile: ((path: string, encoding?: 'utf-8' | 'utf8') =>
+			encoding ? fsp.readFile(path, encoding) : fsp.readFile(path)) as FileSystem['readFile'],
+
+		writeFile: (path, data) => fsp.writeFile(path, data),
+		appendFile: (path, data) => fsp.appendFile(path, data),
+
+		mkdir: async (path, options) => {
+			await fsp.mkdir(path, options)
+		},
+
+		readdir: ((path: string, options?: { withFileTypes: true }) =>
+			options?.withFileTypes
+				? fsp.readdir(path, { withFileTypes: true })
+				: fsp.readdir(path)) as FileSystem['readdir'],
+
+		stat: (path) => fsp.stat(path),
+		access: (path, mode) => fsp.access(path, mode),
+
+		unlink: (path) => fsp.unlink(path),
+		rm: (path, options) => fsp.rm(path, options),
+		cp: async (source, dest, options) => {
+			await fsp.cp(source, dest, options)
+		},
+
+		open: (path, flags) => fsp.open(path, flags),
+
+		exists: async (path) => {
+			try {
+				await fsp.access(path)
+				return true
+			} catch {
+				return false
+			}
+		},
+
+		realpath: (path) => fsp.realpath(path),
+	}
+}
+
+export function createNodeProcessRunner(): ProcessRunner {
+	return {
+		async execFile(file, args, options) {
+			const { stdout, stderr } = await execFileP(file, args, options ?? {})
+			return {
+				stdout: typeof stdout === 'string' ? stdout : Buffer.from(stdout).toString(),
+				stderr: typeof stderr === 'string' ? stderr : Buffer.from(stderr).toString(),
+			}
+		},
+
+		spawn(command, args, options): ChildProcess {
+			return nodeSpawn(command, args, options ?? {})
+		},
+	}
+}
+
+export function createNodePlatform(): Platform {
+	return {
+		fs: createNodeFileSystem(),
+		process: createNodeProcessRunner(),
+		tmpDir: tmpdir(),
+	}
+}

package/src/testing/notification-collector.ts

@@ -0,0 +1,100 @@
+import type { PluginNotification } from '~/core/plugins/plugin-builder.js'
+
+/**
+ * In-memory notification collector for testing.
+ * Captures PluginNotification instances emitted during session execution.
+ */
+export class NotificationCollector {
+	private notifications: PluginNotification[] = []
+	private waiters: Array<{
+		predicate: (n: PluginNotification) => boolean
+		resolve: (n: PluginNotification) => void
+		reject: (err: Error) => void
+		timer: ReturnType<typeof setTimeout>
+	}> = []
+
+	/**
+	 * Push a notification into the collector.
+	 * Wired to SessionManager's onUserOutput callback.
+	 */
+	push(notification: PluginNotification): void {
+		this.notifications.push(notification)
+
+		// Check waiters
+		for (let i = this.waiters.length - 1; i >= 0; i--) {
+			const waiter = this.waiters[i]
+			if (waiter.predicate(notification)) {
+				clearTimeout(waiter.timer)
+				this.waiters.splice(i, 1)
+				waiter.resolve(notification)
+			}
+		}
+	}
+
+	/**
+	 * Get all collected notifications.
+	 */
+	getAll(): PluginNotification[] {
+		return [...this.notifications]
+	}
+
+	/**
+	 * Get notifications from a specific plugin.
+	 */
+	getByPlugin(pluginName: string): PluginNotification[] {
+		return this.notifications.filter((n) => n.pluginName === pluginName)
+	}
+
+	/**
+	 * Get notifications matching plugin name and type.
+	 */
+	getByType(pluginName: string, type: string): PluginNotification[] {
+		return this.notifications.filter((n) => n.pluginName === pluginName && n.type === type)
+	}
+
+	/**
+	 * Get agent messages (user-chat.agentMessage notifications) with extracted payload.
+	 */
+	getAgentMessages(): Array<{ content: string; format: string; sessionId: string }> {
+		return this.getByType('user-chat', 'agentMessage').map((n) => {
+			const payload = n.payload as { content: string; format: string; sessionId: string }
+			return {
+				content: payload.content,
+				format: payload.format,
+				sessionId: payload.sessionId,
+			}
+		})
+	}
+
+	/**
+	 * Wait for a notification matching the predicate.
+	 * Checks already-collected notifications first, then waits for new ones.
+	 */
+	waitFor(
+		predicate: (n: PluginNotification) => boolean,
+		opts?: { timeoutMs?: number },
+	): Promise<PluginNotification> {
+		// Check already-collected
+		const existing = this.notifications.find(predicate)
+		if (existing) return Promise.resolve(existing)
+
+		const timeoutMs = opts?.timeoutMs ?? 5000
+
+		return new Promise<PluginNotification>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				const idx = this.waiters.findIndex((w) => w.resolve === resolve)
+				if (idx !== -1) this.waiters.splice(idx, 1)
+				reject(new Error(`waitFor timed out after ${timeoutMs}ms`))
+			}, timeoutMs)
+
+			this.waiters.push({ predicate, resolve, reject, timer })
+		})
+	}
+
+	/**
+	 * Clear all collected notifications.
+	 */
+	clear(): void {
+		this.notifications = []
+	}
+}

package/src/testing/preset-helpers.ts

@@ -0,0 +1,57 @@
+import type { AgentDefinition } from '~/core/agents/config.js'
+import { ModelId } from '~/core/llm/schema.js'
+import type { AgentPluginConfig, SessionPluginConfig } from '~/core/plugins/plugin-builder.js'
+import type { Preset } from '~/core/preset/index.js'
+
+/** AgentDefinition with model optional — defaults to ModelId('mock') in test helpers. */
+export type TestAgentDefinition<TInput = unknown> = Omit<AgentDefinition<TInput>, 'model'> & { model?: ReturnType<typeof ModelId> }
+
+/**
+ * Create a minimal test preset with sensible defaults.
+ * All agents get debounceMs: 0 and model: ModelId('mock').
+ */
+export function createTestPreset(overrides?: {
+	id?: string
+	orchestratorSystem?: string
+	agents?: TestAgentDefinition[]
+	plugins?: SessionPluginConfig[]
+	orchestratorPlugins?: AgentPluginConfig[]
+}): Preset {
+	const agents = overrides?.agents ?? []
+
+	return {
+		id: overrides?.id ?? 'test',
+		name: 'Test Preset',
+		orchestrator: {
+			system: overrides?.orchestratorSystem ?? 'You are a test agent.',
+			model: ModelId('mock'),
+			tools: [],
+			agents: agents.map((a) => a.name),
+			debounceMs: 0,
+			plugins: overrides?.orchestratorPlugins,
+		},
+		agents: agents.map((a) => ({
+			...a,
+			model: a.model ?? ModelId('mock'),
+			debounceMs: a.debounceMs ?? 0,
+		})),
+		plugins: overrides?.plugins,
+	}
+}
+
+/**
+ * Create a multi-agent test preset from agent definitions.
+ * The orchestrator can spawn all provided agents.
+ */
+export function createMultiAgentPreset(
+	agents: TestAgentDefinition[],
+	overrides?: {
+		id?: string
+		orchestratorSystem?: string
+	},
+): Preset {
+	return createTestPreset({
+		...overrides,
+		agents,
+	})
+}

package/src/testing/test-harness.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'bun:test'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { createTestPreset, TestHarness } from './index.js'
+
+describe('TestHarness', () => {
+	it('sendMessage → tell_user → notification', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withSequence([
+				{
+					content: null,
+					toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hello!' } }],
+				},
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hi')
+
+		const messages = harness.notifications.getAgentMessages()
+		expect(messages).toHaveLength(1)
+		expect(messages[0].content).toBe('Hello!')
+
+		await harness.shutdown()
+	})
+
+	it('creates session with correct state', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+		})
+
+		const session = await harness.createSession('test')
+
+		expect(session.state.status).toBe('active')
+		expect(session.state.presetId).toBe('test')
+		expect(session.getEntryAgentId()).not.toBeNull()
+
+		await harness.shutdown()
+	})
+
+	it('captures events from event store', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withFixedResponse({
+				content: 'Done',
+				toolCalls: [],
+			}),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Test')
+
+		const events = await session.getEvents()
+		const sessionCreated = await session.getEventsByType('session_created')
+
+		expect(events.length).toBeGreaterThan(0)
+		expect(sessionCreated).toHaveLength(1)
+
+		await harness.shutdown()
+	})
+})

package/src/testing/test-harness.ts

@@ -0,0 +1,279 @@
+import type { AgentId } from '~/core/agents/schema.js'
+import type { DomainError } from '~/core/errors.js'
+import { MemoryEventStore } from '~/core/events/memory.js'
+import type { DomainEvent } from '~/core/events/types.js'
+import { SessionFileStore } from '~/core/file-store/file-store.js'
+import type { LLMLogger } from '~/core/llm/logger.js'
+import { LoggingLLMProvider } from '~/core/llm/logging-provider.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import type { MockInferenceHandler } from '~/core/llm/mock.js'
+import type { PluginDefinition, PluginNotification } from '~/core/plugins/plugin-builder.js'
+import type { Preset } from '~/core/preset/index.js'
+import type { SessionId } from '~/core/sessions/schema.js'
+import { SessionManager } from '~/core/sessions/session-manager.js'
+import type { Session } from '~/core/sessions/session.js'
+import type { SessionState } from '~/core/sessions/state.js'
+import { ToolExecutor } from '~/core/tools/executor.js'
+import { silentLogger } from '~/lib/logger/logger.js'
+import { createNodePlatform } from './node-platform.js'
+import type { Result } from '~/lib/utils/result.js'
+import { agentsPlugin } from '~/plugins/agents/plugin.js'
+import { filesystemPlugin } from '~/plugins/filesystem/index.js'
+import { llmDebugPlugin } from '~/plugins/llm-debug/plugin.js'
+import { logsPlugin } from '~/plugins/logs/index.js'
+import { mailboxPlugin } from '~/plugins/mailbox/plugin.js'
+import { presetsPlugin, sessionLifecyclePlugin } from '~/plugins/session-lifecycle/index.js'
+import { uploadsPlugin } from '~/plugins/uploads/plugin.js'
+import { userChatPlugin } from '~/plugins/user-chat/plugin.js'
+import { NotificationCollector } from './notification-collector.js'
+import { waitForAllAgentsIdle } from './wait-helpers.js'
+
+/**
+ * Default system plugins for testing — same as builtinPlugins in bootstrap.ts.
+ */
+const defaultSystemPlugins: readonly PluginDefinition<string, any, any, any, any>[] = [
+	sessionLifecyclePlugin,
+	presetsPlugin,
+	mailboxPlugin,
+	agentsPlugin,
+	userChatPlugin,
+	uploadsPlugin,
+	llmDebugPlugin,
+	filesystemPlugin,
+	logsPlugin,
+]
+
+/**
+ * TestHarness — boots a real SessionManager with MemoryEventStore,
+ * MockLLMProvider, and in-memory notification collection.
+ *
+ * Enables full-flow integration tests without external dependencies.
+ */
+export class TestHarness {
+	readonly eventStore: MemoryEventStore
+	readonly llmProvider: MockLLMProvider
+	readonly notifications: NotificationCollector
+	readonly sessionManager: SessionManager
+
+	constructor(options: {
+		presets: Preset[]
+		llmProvider?: MockLLMProvider
+		mockHandler?: MockInferenceHandler
+		/** Additional system plugins to register (merged with built-in defaults) */
+		systemPlugins?: readonly PluginDefinition<string, any, any, any, any>[]
+		/** Optional LLM logger — when provided, wraps the mock provider with LoggingLLMProvider */
+		llmLogger?: LLMLogger
+		/** Optional pre-existing event store — lets multiple harnesses share persisted state (simulates server restart) */
+		eventStore?: MemoryEventStore
+	}) {
+		this.eventStore = options.eventStore ?? new MemoryEventStore()
+
+		if (options.llmProvider) {
+			this.llmProvider = options.llmProvider
+		} else if (options.mockHandler) {
+			this.llmProvider = new MockLLMProvider(options.mockHandler)
+		} else {
+			// Default: echo back content with no tool calls
+			this.llmProvider = MockLLMProvider.withFixedResponse({
+				content: 'Mock response',
+				toolCalls: [],
+			})
+		}
+
+		this.notifications = new NotificationCollector()
+
+		const presetsMap = new Map(options.presets.map((p) => [p.id, p]))
+
+		// Override debounceMs: 0 on all preset agents for instant processing
+		for (const preset of presetsMap.values()) {
+			preset.orchestrator.debounceMs = 0
+			if (preset.communicator) {
+				preset.communicator.debounceMs = 0
+			}
+			for (const agent of preset.agents) {
+				agent.debounceMs = 0
+			}
+		}
+
+		const basePath = `/tmp/roj-test-${Math.random().toString(36).slice(2)}`
+		const toolExecutor = new ToolExecutor(silentLogger)
+		const platform = createNodePlatform()
+		const dataFileStore = new SessionFileStore(basePath, undefined, false, platform.fs, 'session')
+
+		// When llmLogger is provided, wrap the mock provider so calls get logged
+		const effectiveProvider = options.llmLogger
+			? new LoggingLLMProvider(this.llmProvider, options.llmLogger)
+			: this.llmProvider
+
+		this.sessionManager = new SessionManager({
+			eventStore: this.eventStore,
+			llmProvider: effectiveProvider,
+			toolExecutor,
+			presets: presetsMap,
+			logger: silentLogger,
+			basePath,
+			dataFileStore,
+			onUserOutput: (n: PluginNotification) => this.notifications.push(n),
+			llmLogger: options.llmLogger,
+			platform,
+			systemPlugins: [...defaultSystemPlugins, ...(options.systemPlugins ?? [])],
+		})
+	}
+
+	/**
+	 * Create a session and return a TestSession wrapper.
+	 */
+	async createSession(presetId: string): Promise<TestSession> {
+		const result = await this.sessionManager.createSession(presetId)
+		if (!result.ok) {
+			throw new Error(`Failed to create session: ${result.error.type} — ${result.error.message}`)
+		}
+		return new TestSession(result.value, this)
+	}
+
+	/**
+	 * Open an existing session from the event store (replays events, runs onSessionReady hooks).
+	 * Used to simulate server restart by pairing with another harness over the same eventStore.
+	 */
+	async openSession(sessionId: SessionId): Promise<TestSession> {
+		const result = await this.sessionManager.getSession(sessionId)
+		if (!result.ok) {
+			throw new Error(`Failed to open session: ${result.error.type} — ${result.error.message}`)
+		}
+		return new TestSession(result.value, this)
+	}
+
+	/**
+	 * Shutdown all sessions.
+	 */
+	async shutdown(): Promise<void> {
+		await this.sessionManager.shutdown()
+	}
+}
+
+/**
+ * TestSession — convenience wrapper around Session for integration tests.
+ */
+export class TestSession {
+	readonly sessionId: SessionId
+
+	constructor(
+		private readonly session: Session,
+		private readonly harness: TestHarness,
+	) {
+		this.sessionId = session.id
+	}
+
+	/**
+	 * Send a message to the entry agent (communicator or orchestrator).
+	 */
+	async sendMessage(content: string): Promise<void> {
+		const entryAgentId = this.session.getEntryAgentId()
+		if (!entryAgentId) {
+			throw new Error('No entry agent found')
+		}
+		await this.sendMessageToAgent(entryAgentId, content)
+	}
+
+	/**
+	 * Send a message to a specific agent.
+	 */
+	async sendMessageToAgent(agentId: AgentId, content: string): Promise<void> {
+		const result = await this.session.callPluginMethod('user-chat.sendMessage', {
+			sessionId: String(this.sessionId),
+			content,
+			agentId: String(agentId),
+		})
+		if (!result.ok) {
+			throw new Error(`sendMessage failed: ${result.error.type} — ${result.error.message}`)
+		}
+	}
+
+	/**
+	 * Wait for all agents to become idle.
+	 */
+	async waitForIdle(opts?: { timeoutMs?: number }): Promise<void> {
+		await waitForAllAgentsIdle(this.session, opts)
+	}
+
+	/**
+	 * Send a message and wait for all agents to become idle.
+	 */
+	async sendAndWaitForIdle(content: string, opts?: { timeoutMs?: number }): Promise<void> {
+		await this.sendMessage(content)
+		await this.waitForIdle(opts)
+	}
+
+	/**
+	 * Get all events from the event store for this session.
+	 */
+	async getEvents(): Promise<DomainEvent[]> {
+		return this.harness.eventStore.load(this.sessionId)
+	}
+
+	/**
+	 * Get events filtered by type.
+	 * When called with an EventsFactory, returns fully typed events.
+	 */
+	async getEventsByType(type: string): Promise<DomainEvent[]>
+	async getEventsByType<TEventsMap extends Record<string, DomainEvent>, K extends string & keyof TEventsMap>(
+		factory: { Events: TEventsMap },
+		type: K,
+	): Promise<TEventsMap[K][]>
+	async getEventsByType(factoryOrType: string | { Events: Record<string, DomainEvent> }, maybeType?: string): Promise<DomainEvent[]> {
+		const type = typeof factoryOrType === 'string' ? factoryOrType : maybeType!
+		return this.harness.eventStore.getEventsByType(this.sessionId, type)
+	}
+
+	/**
+	 * Get notifications for this session.
+	 */
+	getNotifications(): PluginNotification[] {
+		return this.harness.notifications.getAll()
+	}
+
+	/**
+	 * Get the current session state.
+	 */
+	get state(): SessionState {
+		return this.session.state
+	}
+
+	/**
+	 * Get the entry agent ID.
+	 */
+	getEntryAgentId(): AgentId | null {
+		return this.session.getEntryAgentId()
+	}
+
+	/**
+	 * Close the session.
+	 */
+	async close(): Promise<void> {
+		const result = await this.session.close()
+		if (!result.ok) {
+			throw new Error(`close failed: ${result.error.type} — ${result.error.message}`)
+		}
+	}
+
+	/**
+	 * Call a plugin method on the underlying session.
+	 */
+	async callPluginMethod(method: string, input: unknown): Promise<Result<unknown, DomainError>> {
+		return this.session.callPluginMethod(method, input)
+	}
+
+	/**
+	 * Answer a user-chat question (convenience wrapper around callPluginMethod).
+	 */
+	async answerQuestion(agentId: AgentId, questionId: string, answer: unknown): Promise<void> {
+		const result = await this.session.callPluginMethod('user-chat.answerQuestion', {
+			agentId: String(agentId),
+			questionId,
+			answer,
+		})
+		if (!result.ok) {
+			throw new Error(`answerQuestion failed: ${result.error.type} — ${result.error.message}`)
+		}
+	}
+}

package/src/testing/wait-helpers.ts

@@ -0,0 +1,84 @@
+import type { AgentId } from '~/core/agents/schema.js'
+import type { Session } from '~/core/sessions/session.js'
+
+const DEFAULT_TIMEOUT_MS = 5000
+const POLL_INTERVAL_MS = 10
+
+/**
+ * Wait for a specific agent to become idle.
+ * An agent is "idle" when: status === 'pending', no pendingToolCalls,
+ * no pendingToolResults, and not scheduled for processing.
+ */
+export async function waitForAgentIdle(
+	session: Session,
+	agentId: AgentId,
+	opts?: { timeoutMs?: number },
+): Promise<void> {
+	const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS
+	const deadline = Date.now() + timeoutMs
+
+	while (Date.now() < deadline) {
+		if (isAgentIdle(session, agentId)) {
+			// Double-check after one poll interval to account for queueMicrotask re-entry
+			await sleep(POLL_INTERVAL_MS)
+			if (isAgentIdle(session, agentId)) {
+				return
+			}
+		}
+		await sleep(POLL_INTERVAL_MS)
+	}
+
+	throw new Error(`waitForAgentIdle timed out after ${timeoutMs}ms for agent ${agentId}`)
+}
+
+/**
+ * Wait for all agents in a session to become idle.
+ */
+export async function waitForAllAgentsIdle(
+	session: Session,
+	opts?: { timeoutMs?: number },
+): Promise<void> {
+	const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS
+	const deadline = Date.now() + timeoutMs
+
+	while (Date.now() < deadline) {
+		if (areAllAgentsIdle(session)) {
+			// Double-check after one poll interval
+			await sleep(POLL_INTERVAL_MS)
+			if (areAllAgentsIdle(session)) {
+				return
+			}
+		}
+		await sleep(POLL_INTERVAL_MS)
+	}
+
+	throw new Error(`waitForAllAgentsIdle timed out after ${timeoutMs}ms`)
+}
+
+function isAgentIdle(session: Session, agentId: AgentId): boolean {
+	const agent = session.getAgent(agentId)
+	if (!agent) return true // Agent doesn't exist, consider idle
+
+	const agentState = agent.state
+	if (!agentState) return true
+
+	return (
+		agentState.status === 'pending'
+		&& agentState.pendingToolCalls.length === 0
+		&& agentState.pendingToolResults.length === 0
+		&& !agent.isScheduled()
+	)
+}
+
+function areAllAgentsIdle(session: Session): boolean {
+	for (const [agentId] of session.state.agents) {
+		if (!isAgentIdle(session, agentId)) {
+			return false
+		}
+	}
+	return true
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}