@roj-ai/sdk 0.0.2

package/src/core/agents/agent-config.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from 'bun:test'
+import type { DebounceContext } from '~/core/agents/debounce.js'
+import {
+	aggressiveDebounceCallback,
+	batchingDebounceCallback,
+	defaultDebounceCallback,
+	waitForResponseDebounceCallback,
+} from '~/core/agents/debounce.js'
+import { MailboxMessage, MessageId } from '../../plugins/mailbox/schema'
+import { PendingToolResult, ToolCallId } from '../tools/schema'
+import { AgentId } from './schema'
+
+describe('Debounce Callbacks', () => {
+	const createMessage = (timestampOffset = 0): MailboxMessage => ({
+		id: MessageId('msg-1'),
+		from: AgentId('agent-1'),
+		content: 'Test message',
+		timestamp: Date.now() - timestampOffset,
+		consumed: false,
+	})
+
+	const createToolResult = (
+		toolName: string,
+		timestampOffset = 0,
+		isError = false,
+	): PendingToolResult => ({
+		toolCallId: ToolCallId('tc-1'),
+		toolName,
+		timestamp: Date.now() - timestampOffset,
+		isError,
+		content: '',
+	})
+
+	const createContext = (
+		messageCount: number,
+		oldestWaitingMs: number,
+		pendingToolResults: PendingToolResult[] = [],
+	): DebounceContext => ({
+		messages: Array.from({ length: messageCount }, () => createMessage()),
+		oldestWaitingMs,
+		totalPending: messageCount,
+		pendingToolResults,
+	})
+
+	describe('defaultDebounceCallback', () => {
+		test("returns 'wait' when oldest message is less than 500ms old", () => {
+			const context = createContext(1, 400)
+			expect(defaultDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'wait' when oldest message is exactly 500ms old", () => {
+			const context = createContext(1, 500)
+			expect(defaultDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'process_now' when oldest message is more than 500ms old", () => {
+			const context = createContext(1, 501)
+			expect(defaultDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'process_now' regardless of message count", () => {
+			const context = createContext(10, 600)
+			expect(defaultDebounceCallback(context)).toBe('process_now')
+		})
+	})
+
+	describe('aggressiveDebounceCallback', () => {
+		test("returns 'wait' when oldest message is less than 100ms old", () => {
+			const context = createContext(1, 50)
+			expect(aggressiveDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'wait' when oldest message is exactly 100ms old", () => {
+			const context = createContext(1, 100)
+			expect(aggressiveDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'process_now' when oldest message is more than 100ms old", () => {
+			const context = createContext(1, 101)
+			expect(aggressiveDebounceCallback(context)).toBe('process_now')
+		})
+
+		test('processes faster than default callback', () => {
+			const context = createContext(1, 150)
+			// Aggressive should process, default should wait
+			expect(aggressiveDebounceCallback(context)).toBe('process_now')
+			expect(defaultDebounceCallback(context)).toBe('wait')
+		})
+	})
+
+	describe('batchingDebounceCallback', () => {
+		test("returns 'wait' with few messages and short wait time", () => {
+			const context = createContext(2, 500)
+			expect(batchingDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'process_now' when 5 or more messages", () => {
+			const context = createContext(5, 100)
+			expect(batchingDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'process_now' when more than 5 messages", () => {
+			const context = createContext(10, 50)
+			expect(batchingDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'wait' when oldest message is exactly 2000ms old with few messages", () => {
+			const context = createContext(2, 2000)
+			expect(batchingDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'process_now' when oldest message is more than 2000ms old", () => {
+			const context = createContext(1, 2001)
+			expect(batchingDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'process_now' at threshold of 5 messages", () => {
+			const context = createContext(5, 0)
+			expect(batchingDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'wait' just below message threshold", () => {
+			const context = createContext(4, 1500)
+			expect(batchingDebounceCallback(context)).toBe('wait')
+		})
+	})
+
+	describe('waitForResponseDebounceCallback', () => {
+		test("returns 'process_now' when there are new mailbox messages", () => {
+			const context = createContext(1, 100, [
+				createToolResult('send_message', 1000),
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'wait' when all pending tool results are communication tools", () => {
+			const context = createContext(0, 0, [
+				createToolResult('send_message', 1000),
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'wait' for start_* agent tool", () => {
+			const context = createContext(0, 0, [
+				createToolResult('start_researcher', 1000),
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'wait' for tell_user tool", () => {
+			const context = createContext(0, 0, [
+				createToolResult('tell_user', 1000),
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'wait' for ask_user tool", () => {
+			const context = createContext(0, 0, [
+				createToolResult('ask_user', 1000),
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'wait' when multiple communication tools are pending", () => {
+			const context = createContext(0, 0, [
+				createToolResult('send_message', 1000),
+				createToolResult('start_helper', 500),
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'process_now' when ANY tool result is not a communication tool", () => {
+			const context = createContext(0, 0, [
+				createToolResult('send_message', 1000),
+				createToolResult('reveal_secret', 500), // Not a communication tool
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'process_now' for non-communication tool alone", () => {
+			const context = createContext(0, 0, [
+				createToolResult('get_my_info', 1000),
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'process_now' when any tool result has isError=true", () => {
+			const context = createContext(0, 0, [
+				createToolResult('send_message', 1000, true), // Error!
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'process_now' when mixed success and error results", () => {
+			const context = createContext(0, 0, [
+				createToolResult('send_message', 2000, false), // Success
+				createToolResult('start_worker', 1000, true), // Error - should trigger immediate processing
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'process_now' after 60s timeout for communication tools", () => {
+			const context = createContext(0, 0, [
+				createToolResult('send_message', 61000), // 61 seconds ago
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('process_now')
+		})
+
+		test("returns 'wait' just before 60s timeout", () => {
+			const context = createContext(0, 0, [
+				createToolResult('send_message', 59000), // 59 seconds ago
+			])
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+		})
+
+		test("returns 'wait' when no messages and no tool results", () => {
+			const context = createContext(0, 0, [])
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+		})
+
+		test('uses oldest tool result timestamp for timeout calculation', () => {
+			// One tool result at 59s, one at 30s - should use 59s (oldest)
+			const now = Date.now()
+			const context: DebounceContext = {
+				messages: [],
+				oldestWaitingMs: 0,
+				totalPending: 0,
+				pendingToolResults: [
+					{ toolCallId: ToolCallId('tc-1'), toolName: 'send_message', timestamp: now - 59000, isError: false, content: '' },
+					{ toolCallId: ToolCallId('tc-2'), toolName: 'send_message', timestamp: now - 30000, isError: false, content: '' },
+				],
+			}
+			expect(waitForResponseDebounceCallback(context)).toBe('wait')
+
+			// Now make oldest one 61s old
+			context.pendingToolResults[0].timestamp = now - 61000
+			expect(waitForResponseDebounceCallback(context)).toBe('process_now')
+		})
+	})
+})

package/src/core/agents/agent-roles.ts

@@ -0,0 +1,41 @@
+/**
+ * Agent role constants.
+ *
+ * These constants define the special agent roles in the system:
+ * - ORCHESTRATOR: The main agent that coordinates work and spawns sub-agents
+ * - COMMUNICATOR: Optional agent that handles user communication in communication-agent mode
+ */
+
+/** Orchestrator agent role - the main coordinating agent */
+export const ORCHESTRATOR_ROLE = 'orchestrator' as const
+
+/** Communicator agent role - handles user communication */
+export const COMMUNICATOR_ROLE = 'communicator' as const
+
+/** Type for special agent roles */
+export type AgentRole = typeof ORCHESTRATOR_ROLE | typeof COMMUNICATOR_ROLE
+
+/**
+ * Prompt-level role classification for system prompt composition.
+ * - 'entry': Orchestrator without communicator (talks to user directly)
+ * - 'orchestrator': Orchestrator with communicator (talks to communicator, not user)
+ * - 'child': Spawned by parent, reports results back
+ * - 'communicator': Handles user communication, relays to orchestrator
+ */
+export type PromptRole = 'entry' | 'orchestrator' | 'child' | 'communicator'
+
+/**
+ * Determine an agent's prompt role from its state and session context.
+ */
+export function getAgentRole(
+	agentState: { definitionName: string; parentId: string | null },
+	sessionState: { agents: Map<string, { definitionName: string }> },
+): PromptRole {
+	if (agentState.definitionName === COMMUNICATOR_ROLE) return 'communicator'
+	const hasCommunicator = Array.from(sessionState.agents.values())
+		.some(a => a.definitionName === COMMUNICATOR_ROLE)
+	if (agentState.definitionName === ORCHESTRATOR_ROLE) {
+		return hasCommunicator ? 'orchestrator' : 'entry'
+	}
+	return 'child'
+}

package/src/core/agents/agent-shutdown.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Tests for Agent shutdown behavior - verifying that session close
+ * prevents re-scheduling and aborts in-flight work.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { MemoryEventStore } from '~/core/events'
+import { withSessionId } from '~/core/events/test-helpers.js'
+import { MockLLMProvider } from '~/core/llm/index.js'
+import type { InferenceResponse } from '~/core/llm/provider.js'
+import { ModelId } from '~/core/llm/schema.js'
+import { createApplyEvent } from '~/core/sessions/apply-event.js'
+import type { SessionContext } from '~/core/sessions/context.js'
+import { SessionId } from '~/core/sessions/schema.js'
+import { sessionEvents } from '~/core/sessions/state.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { mailboxPlugin } from '~/plugins/mailbox/plugin.js'
+import { generateTestMessageId } from '~/plugins/mailbox/schema.js'
+import { mailboxEvents } from '~/plugins/mailbox/state.js'
+import { createNodePlatform } from '~/testing/node-platform.js'
+import { ConsoleLogger } from '../../lib/logger/console.js'
+import { SessionFileStore } from '../file-store/file-store.js'
+import { SessionStore } from '../sessions/session-store.js'
+import { ToolExecutor } from '../tools/executor.js'
+import { Agent, type AgentConfig, type AgentDependencies } from './agent.js'
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+const TEST_SESSION_ID = SessionId('test-session')
+const TEST_AGENT_ID = AgentId('test-agent-1')
+
+function createLogger() {
+	return new ConsoleLogger({ level: 'error' })
+}
+
+async function createTestAgent(
+	config: Partial<AgentConfig> = {},
+	llmResponse?: Partial<InferenceResponse>,
+): Promise<{ agent: Agent; store: SessionStore; eventStore: MemoryEventStore; llmProvider: MockLLMProvider }> {
+	const eventStore = new MemoryEventStore()
+	const logger = createLogger()
+
+	// Create session
+	const sessionCreatedEvent = withSessionId(TEST_SESSION_ID, sessionEvents.create('session_created', { presetId: 'test-preset' }))
+	await eventStore.append(TEST_SESSION_ID, sessionCreatedEvent)
+
+	// Spawn agent
+	const agentSpawnedEvent = withSessionId(
+		TEST_SESSION_ID,
+		agentEvents.create('agent_spawned', {
+			agentId: TEST_AGENT_ID,
+			definitionName: 'test-agent',
+			parentId: null,
+		}),
+	)
+	await eventStore.append(TEST_SESSION_ID, agentSpawnedEvent)
+
+	const composedReducer = createApplyEvent([mailboxPlugin.create({})])
+	const store = await SessionStore.load(TEST_SESSION_ID, eventStore, composedReducer)
+	if (!store) {
+		throw new Error('Failed to create SessionStore')
+	}
+
+	const defaultConfig: AgentConfig = {
+		systemPrompt: 'Test system prompt',
+		tools: [],
+		model: ModelId('test-model'),
+		spawnableAgents: [],
+		debounceMs: 0,
+		...config,
+	}
+
+	const llmProvider = MockLLMProvider.withFixedResponse({
+		content: llmResponse?.content ?? 'Test response',
+		toolCalls: llmResponse?.toolCalls ?? [],
+		finishReason: llmResponse?.finishReason ?? 'stop',
+	})
+
+	const fileStore = new SessionFileStore('/tmp/test', undefined, false, createNodePlatform().fs)
+
+	const sessionContext: SessionContext = {
+		sessionId: TEST_SESSION_ID,
+		sessionState: store.getState(),
+		sessionInput: undefined,
+		environment: { sessionDir: '/tmp/test', sandboxed: false },
+		llm: llmProvider,
+		files: fileStore,
+		eventStore,
+		platform: createNodePlatform(),
+		logger,
+		emitEvent: async (event) => {
+			await store.emit(withSessionId(TEST_SESSION_ID, event))
+		},
+		notify: () => {},
+	}
+
+	const deps: AgentDependencies = {
+		id: TEST_AGENT_ID,
+		sessionContext,
+		store,
+		llmProvider,
+		toolExecutor: new ToolExecutor(logger),
+		logger,
+		config: defaultConfig,
+		plugins: [mailboxPlugin.create({})],
+		environment: { sessionDir: '/tmp/test', sandboxed: false },
+		fileStore,
+	}
+
+	const agent = new Agent(deps)
+	return { agent, store, eventStore, llmProvider }
+}
+
+async function addMailboxMessage(store: SessionStore, content: string) {
+	await store.emit(withSessionId(
+		TEST_SESSION_ID,
+		mailboxEvents.create('mailbox_message', {
+			toAgentId: TEST_AGENT_ID,
+			message: {
+				id: generateTestMessageId(),
+				from: 'user',
+				content,
+				timestamp: Date.now(),
+				consumed: false,
+			},
+		}),
+	))
+}
+
+async function closeSession(store: SessionStore) {
+	await store.emit(withSessionId(TEST_SESSION_ID, sessionEvents.create('session_closed', {})))
+}
+
+/**
+ * Wait for any scheduled timers to fire.
+ */
+async function flushTimers() {
+	await new Promise<void>((resolve) => setTimeout(resolve, 10))
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('Agent Shutdown', () => {
+	it('continue() is no-op when session is closed', async () => {
+		const { agent, store, llmProvider, eventStore } = await createTestAgent()
+
+		await addMailboxMessage(store, 'Hello')
+		await closeSession(store)
+
+		await agent.continue()
+
+		expect(llmProvider.getCallCount()).toBe(0)
+
+		const events = await eventStore.load(TEST_SESSION_ID)
+		const inferenceStarted = events.filter(e => e.type === 'inference_started')
+		expect(inferenceStarted).toHaveLength(0)
+	})
+
+	it('agent does not continue after session closes', async () => {
+		const { agent, store, llmProvider } = await createTestAgent()
+
+		await addMailboxMessage(store, 'Hello')
+		// While loop runs full cycle: onStart → inference → onComplete
+		await agent.continue()
+		expect(llmProvider.getCallCount()).toBe(1)
+
+		// Close session
+		await closeSession(store)
+
+		// Add another message that would trigger work if continue() ran
+		await addMailboxMessage(store, 'Another message')
+
+		// Let any scheduled timers fire
+		await flushTimers()
+
+		// No additional inference should have occurred — isClosed() guard blocks re-entry
+		expect(llmProvider.getCallCount()).toBe(1)
+	})
+
+	it('agent does not run additional inference after session is closed', async () => {
+		const { agent, store, llmProvider } = await createTestAgent(
+			{},
+			{ toolCalls: [{ id: ToolCallId('tc-1'), name: 'test_tool', input: {} }] },
+		)
+
+		await addMailboxMessage(store, 'Hello')
+		// While loop runs full cycle: inference → tool_exec → scheduleProcessing
+		await agent.continue()
+		expect(llmProvider.getCallCount()).toBe(1)
+
+		// Close session — any scheduled timer will find isClosed() and stop
+		await closeSession(store)
+
+		// Calling continue() again is a no-op when session is closed
+		await agent.continue()
+
+		// No additional inference should have occurred
+		expect(llmProvider.getCallCount()).toBe(1)
+	})
+
+	it('scheduleProcessing() is no-op when session is closed', async () => {
+		const { agent, store } = await createTestAgent()
+
+		await addMailboxMessage(store, 'Hello')
+		await closeSession(store)
+
+		agent.scheduleProcessing()
+
+		expect(agent.isScheduled()).toBe(false)
+	})
+
+	it('shutdown() stops scheduled processing', async () => {
+		const { agent, store, llmProvider } = await createTestAgent({
+			debounceMs: 100,
+		})
+
+		await addMailboxMessage(store, 'Hello')
+		agent.scheduleProcessing()
+		expect(agent.isScheduled()).toBe(true)
+
+		agent.shutdown()
+		expect(agent.isScheduled()).toBe(false)
+
+		// Wait longer than the debounce time
+		await new Promise<void>((resolve) => setTimeout(resolve, 150))
+
+		// LLM should never have been called
+		expect(llmProvider.getCallCount()).toBe(0)
+	})
+})