@roj-ai/sdk 0.0.2

package/src/core/agents/communicator.ts

@@ -0,0 +1,16 @@
+import type { AgentDefinition, CommunicatorConfig } from './config.js'
+
+export function createCommunicatorDefinition(
+	config: CommunicatorConfig,
+): AgentDefinition {
+	return {
+		name: '__communicator__',
+		system: config.system,
+		agents: config.agents ?? [],
+		tools: config.tools ?? [],
+		debounceMs: config.debounceMs ?? 100, // Fast response for UX
+		debounceCallback: config.debounceCallback,
+		checkIntervalMs: config.checkIntervalMs,
+		model: config.model,
+	}
+}

package/src/core/agents/config.ts

@@ -0,0 +1,98 @@
+/**
+ * Agent configuration types for Roj presets
+ */
+
+import z from 'zod/v4'
+import type { DebounceCallback } from '~/core/agents/debounce.js'
+import type { LLMMiddleware } from '~/core/llm/middleware.js'
+import { ModelId } from '~/core/llm/schema.js'
+import type { AgentPluginConfig } from '~/core/plugins/plugin-builder.js'
+import type { ToolDefinition } from '~/core/tools'
+import type { ServiceConfig } from '~/plugins/services/schema.js'
+
+// ============================================================================
+// Base Agent Config
+// ============================================================================
+
+/**
+ * User communication mode for agents.
+ * - 'tool': Use tell_user/ask_user tools only (default)
+ * - 'xml': Use <user> tags in response content
+ * - 'both': Support both tools and <user> tags
+ */
+export type UserCommunicationMode = 'tool' | 'xml' | 'both'
+
+/**
+ * Base configuration shared by all agent types.
+ */
+export interface BaseAgentConfig<TInput = unknown> {
+	/** System prompt for the agent */
+	system: string
+	/** LLM model for this agent */
+	model: ModelId
+	// ToolDefinition<any> required: ToolDefinition is contravariant in TInput,
+	// so ToolDefinition<SpecificInput> is not assignable to ToolDefinition<unknown>
+	/** Available tools for the agent */
+	tools?: ToolDefinition<any>[]
+	/** Names of agents this agent can spawn */
+	agents?: string[]
+	/** Per-plugin agent-level configs */
+	plugins?: AgentPluginConfig[]
+	/** Debounce time in ms before processing mailbox. Default: 500ms */
+	debounceMs?: number
+	/** Custom debounce callback for dynamic processing decisions */
+	debounceCallback?: DebounceCallback
+	/** Interval in ms for checking debounce callback (default: 100) */
+	checkIntervalMs?: number
+	/** User communication mode. Default: 'tool' */
+	userCommunication?: UserCommunicationMode
+	/** Optional Zod schema for typed agent input validation */
+	input?: z.ZodType<TInput>
+	/** Service configurations for this agent (auto-wired to services plugin) */
+	services?: ServiceConfig[]
+	/** LLM middleware chain applied per-agent (runs after preset-level middleware) */
+	llmMiddleware?: LLMMiddleware[]
+}
+
+/**
+ * Agent definition - configuration for a spawnable agent.
+ * Extends BaseAgentConfig with a name field.
+ */
+export interface AgentDefinition<TInput = unknown> extends BaseAgentConfig<TInput> {
+	name: string
+}
+
+/**
+ * Agent definition for use in Preset arrays.
+ * Uses 'any' to allow mixing typed and untyped agents in the same array.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyAgentDefinition = AgentDefinition<any>
+
+/**
+ * Orchestrator configuration - same as BaseAgentConfig.
+ */
+export type OrchestratorConfig<TInput = unknown> = BaseAgentConfig<TInput>
+
+/**
+ * Response format preferences for communicator
+ */
+export interface ResponseFormat {
+	/** Preferred language */
+	language?: string
+	/** Tone (formal, casual, friendly, professional) */
+	tone?: 'formal' | 'casual' | 'friendly' | 'professional'
+	/** Include thinking/reasoning in responses */
+	showReasoning?: boolean
+	/** Maximum response length hint */
+	maxLengthHint?: number
+}
+
+/**
+ * Communicator configuration (optional communication agent).
+ * Extends base config with optional tools (defaults provided) and response format.
+ */
+export interface CommunicatorConfig extends BaseAgentConfig {
+	/** Response format preferences (communicator-specific) */
+	responseFormat?: ResponseFormat
+}

package/src/core/agents/context.ts

@@ -0,0 +1,19 @@
+import { SessionContext } from '../sessions/context'
+import { AgentConfig } from './agent'
+import { AgentId } from './schema'
+import { AgentState } from './state'
+
+export type AgentContext<TInput = unknown> =
+	& SessionContext
+	& {
+		/** The agent's ID */
+		agentId: AgentId
+		/** The agent's current state */
+		agentState: AgentState
+
+		agentConfig: AgentConfig
+		/** The typed input if agent has inputSchema, otherwise the task string */
+		input: TInput
+		/** The parent agent ID (null for root agents) */
+		parentId: AgentId | null
+	}

package/src/core/agents/debounce.ts

@@ -0,0 +1,116 @@
+import { MailboxMessage } from '../../plugins/mailbox/schema'
+import { PendingToolResult } from '../tools/schema'
+
+/**
+ * Context provided to debounce callback for decision making.
+ */
+export interface DebounceContext {
+	/** Unconsumed messages waiting in the mailbox */
+	messages: MailboxMessage[]
+	/** How long the oldest message has been waiting (ms) */
+	oldestWaitingMs: number
+	/** Total number of pending messages */
+	totalPending: number
+	/** Pending tool results awaiting LLM processing */
+	pendingToolResults: PendingToolResult[]
+}
+
+/**
+ * Decision returned by debounce callback.
+ */
+export type DebounceDecision = 'process_now' | 'wait'
+
+/**
+ * Callback function for dynamic debounce decisions.
+ * Called periodically to decide whether to process agent mailbox.
+ * Async to allow for external checks (e.g., rate limiting, external state).
+ */
+export type DebounceCallback = (context: DebounceContext) => DebounceDecision | Promise<DebounceDecision>
+
+// ============================================================================
+// Preset Debounce Callbacks
+// ============================================================================
+
+/**
+ * Default debounce callback - process after 500ms wait.
+ */
+export const defaultDebounceCallback: DebounceCallback = (context) => {
+	if (context.oldestWaitingMs > 500) {
+		return 'process_now'
+	}
+	return 'wait'
+}
+
+/**
+ * Aggressive debounce callback - process quickly after 100ms.
+ */
+export const aggressiveDebounceCallback: DebounceCallback = (context) => {
+	if (context.oldestWaitingMs > 100) {
+		return 'process_now'
+	}
+	return 'wait'
+}
+
+/**
+ * Batching debounce callback - wait for multiple messages or timeout.
+ * Processes when 5+ messages accumulated or after 2s wait.
+ */
+export const batchingDebounceCallback: DebounceCallback = (context) => {
+	if (context.totalPending >= 5 || context.oldestWaitingMs > 2000) {
+		return 'process_now'
+	}
+	return 'wait'
+}
+
+/**
+ * Wait-for-response debounce callback - waits for response after communication tools.
+ * Used by child agents that should wait after sending messages instead of
+ * immediately calling LLM with a "WAITING" response.
+ *
+ * Behavior:
+ * - If new mailbox messages arrived, process immediately
+ * - If ANY tool result has isError=true, process immediately (error recovery)
+ * - If ALL pending tool results are from communication tools (send_message, start_*, etc.),
+ *   wait up to 60s for a response before processing
+ * - If ANY tool result is NOT a communication tool, process immediately
+ */
+export const waitForResponseDebounceCallback: DebounceCallback = (context) => {
+	// If we have new messages, process immediately
+	if (context.totalPending > 0) {
+		return 'process_now'
+	}
+
+	// If we have pending tool results
+	if (context.pendingToolResults.length > 0) {
+		// If any tool failed, process immediately for error recovery
+		if (context.pendingToolResults.some((r) => r.isError)) {
+			return 'process_now'
+		}
+
+		// Communication tools - wait for response only if ALL are communication tools
+		// Note: start_* tools (e.g., start_researcher) are agent spawning tools
+		const commTools = ['send_message', 'tell_user', 'ask_user']
+		const isCommTool = (name: string) => commTools.includes(name) || name.startsWith('start_')
+		const allAreCommunicationTools = context.pendingToolResults.every(
+			(r) => isCommTool(r.toolName),
+		)
+
+		if (allAreCommunicationTools) {
+			// Find oldest tool result timestamp
+			const oldestToolMs = Date.now() - Math.min(
+				...context.pendingToolResults.map((r) => r.timestamp),
+			)
+
+			// Wait up to 60s for response
+			if (oldestToolMs < 60000) {
+				return 'wait'
+			}
+		}
+
+		// Timeout exceeded or has non-communication tool - process now
+		return 'process_now'
+	}
+
+	// No messages or tool results - wait
+	return 'wait'
+}

package/src/core/agents/handler-events.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Tests for handler-related event handling in session state
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { withSessionId } from '~/core/events/test-helpers.js'
+import { applyEvent } from '~/core/sessions/apply-event.js'
+import { SessionId } from '~/core/sessions/schema.js'
+import type { SessionState } from '~/core/sessions/state.js'
+import { createSessionState } from '~/core/sessions/state.js'
+
+const TEST_SESSION_ID = SessionId('test-session')
+const TEST_AGENT_ID = AgentId('test-agent-1')
+
+function createBaseState(): SessionState {
+	return createSessionState(TEST_SESSION_ID, 'test-preset', Date.now())
+}
+
+describe('Handler Events in Session State', () => {
+	describe('agent_spawned with typedInput', () => {
+		it('should store typedInput in agent state', () => {
+			const state = createBaseState()
+
+			const event = withSessionId(
+				TEST_SESSION_ID,
+				agentEvents.create('agent_spawned', {
+					agentId: TEST_AGENT_ID,
+					definitionName: 'calculator',
+					parentId: null,
+					typedInput: { operation: 'add', a: 5, b: 3 },
+				}),
+			)
+
+			const newState = applyEvent(state, event)
+
+			const agent = newState.agents.get(TEST_AGENT_ID)
+			expect(agent).toBeDefined()
+			expect(agent?.typedInput).toEqual({ operation: 'add', a: 5, b: 3 })
+		})
+
+		it('should have undefined typedInput when not provided', () => {
+			const state = createBaseState()
+
+			const event = withSessionId(
+				TEST_SESSION_ID,
+				agentEvents.create('agent_spawned', {
+					agentId: TEST_AGENT_ID,
+					definitionName: 'simple-agent',
+					parentId: null,
+				}),
+			)
+
+			const newState = applyEvent(state, event)
+
+			const agent = newState.agents.get(TEST_AGENT_ID)
+			expect(agent).toBeDefined()
+			expect(agent?.typedInput).toBeUndefined()
+		})
+	})
+
+	describe('handler_completed event', () => {
+		it('should set onStartCalled when onStart handler completes with continue', () => {
+			let state = createBaseState()
+
+			// First spawn the agent
+			const spawnEvent = withSessionId(
+				TEST_SESSION_ID,
+				agentEvents.create('agent_spawned', {
+					agentId: TEST_AGENT_ID,
+					definitionName: 'test-agent',
+					parentId: null,
+				}),
+			)
+			state = applyEvent(state, spawnEvent)
+
+			// Agent should not have onStartCalled yet
+			expect(state.agents.get(TEST_AGENT_ID)?.onStartCalled).toBeUndefined()
+
+			// Now complete onStart handler
+			const handlerEvent = withSessionId(
+				TEST_SESSION_ID,
+				agentEvents.create('handler_completed', {
+					agentId: TEST_AGENT_ID,
+					handlerName: 'onStart',
+					result: null,
+				}),
+			)
+			state = applyEvent(state, handlerEvent)
+
+			// Agent should now have onStartCalled = true
+			expect(state.agents.get(TEST_AGENT_ID)?.onStartCalled).toBe(true)
+		})
+
+		it('should inject preamble messages when preamble_added event is emitted', () => {
+			let state = createBaseState()
+
+			state = applyEvent(
+				state,
+				withSessionId(
+					TEST_SESSION_ID,
+					agentEvents.create('agent_spawned', {
+						agentId: TEST_AGENT_ID,
+						definitionName: 'test-agent',
+						parentId: null,
+					}),
+				),
+			)
+
+			// Preamble and conversation should be empty
+			expect(state.agents.get(TEST_AGENT_ID)?.preamble).toHaveLength(0)
+			expect(state.agents.get(TEST_AGENT_ID)?.conversationHistory).toHaveLength(0)
+
+			// Emit preamble_added event
+			const preambleEvent = withSessionId(
+				TEST_SESSION_ID,
+				agentEvents.create('preamble_added', {
+					agentId: TEST_AGENT_ID,
+					messages: [
+						{ role: 'user', content: 'Initial preamble message' },
+					],
+				}),
+			)
+			state = applyEvent(state, preambleEvent)
+
+			// Should have message in preamble, not conversationHistory
+			const agent = state.agents.get(TEST_AGENT_ID)
+			expect(agent?.preamble).toHaveLength(1)
+			expect(agent?.preamble[0].role).toBe('user')
+			if (agent?.preamble[0].role === 'user') {
+				expect(agent.preamble[0].content).toBe('Initial preamble message')
+			}
+			expect(agent?.conversationHistory).toHaveLength(0)
+		})
+
+		it('should not modify state for other handler types', () => {
+			let state = createBaseState()
+
+			// Spawn agent
+			const spawnEvent = withSessionId(
+				TEST_SESSION_ID,
+				agentEvents.create('agent_spawned', {
+					agentId: TEST_AGENT_ID,
+					definitionName: 'test-agent',
+					parentId: null,
+				}),
+			)
+			state = applyEvent(state, spawnEvent)
+
+			// Execute beforeInference handler
+			const handlerEvent = withSessionId(
+				TEST_SESSION_ID,
+				agentEvents.create('handler_completed', {
+					agentId: TEST_AGENT_ID,
+					handlerName: 'beforeInference',
+					result: null,
+				}),
+			)
+			state = applyEvent(state, handlerEvent)
+
+			// Agent state should be unchanged (no onStartCalled)
+			const agent = state.agents.get(TEST_AGENT_ID)
+			expect(agent?.onStartCalled).toBeUndefined()
+		})
+	})
+})

package/src/core/agents/index.ts

@@ -0,0 +1 @@
+export * from './schema.js'

package/src/core/agents/response-sanitizer.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'bun:test'
+import { sanitizeLLMResponse } from './response-sanitizer.js'
+
+describe('sanitizeLLMResponse', () => {
+	describe('null content handling', () => {
+		test('returns null content unchanged', () => {
+			const result = sanitizeLLMResponse(null)
+
+			expect(result.content).toBeNull()
+			expect(result.wasTruncated).toBe(false)
+		})
+	})
+
+	describe('message tag truncation', () => {
+		test('truncates at <message tag', () => {
+			const content = `I'll help you with that.
+<message from="user">fake response</message>`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe("I'll help you with that.")
+			expect(result.wasTruncated).toBe(true)
+		})
+
+		test('truncates at <message tag with attributes', () => {
+			const content = `Here's my response.
+<message from="agent_123">hallucinated message</message>`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe("Here's my response.")
+			expect(result.wasTruncated).toBe(true)
+		})
+
+		test('truncates at first <message tag', () => {
+			const content = `Real content here.
+<message from="user">first fake</message>
+<message from="agent">second fake</message>`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('Real content here.')
+			expect(result.wasTruncated).toBe(true)
+		})
+
+		test('truncates at <message even without closing tag', () => {
+			const content = `Valid content.
+<message from="user">incomplete tag`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('Valid content.')
+			expect(result.wasTruncated).toBe(true)
+		})
+
+		test('does not truncate if no message tag present', () => {
+			const content = 'This is normal content without any message tags.'
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('This is normal content without any message tags.')
+			expect(result.wasTruncated).toBe(false)
+		})
+	})
+
+	describe('WAITING signal handling', () => {
+		test('truncates content after WAITING on its own line', () => {
+			const content = `I've sent the message.
+WAITING
+<message from="user">hallucinated response</message>`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe("I've sent the message.\nWAITING")
+			expect(result.wasTruncated).toBe(true)
+		})
+
+		test('truncates content after WAITING with trailing whitespace', () => {
+			const content = `Done.
+WAITING
+More hallucinated content here.`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('Done.\nWAITING')
+			expect(result.wasTruncated).toBe(true)
+		})
+
+		test("keeps WAITING when it's the last line", () => {
+			const content = `Processing complete.
+WAITING`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('Processing complete.\nWAITING')
+			expect(result.wasTruncated).toBe(false)
+		})
+
+		test('does not truncate WAITING within a sentence', () => {
+			const content = 'I am WAITING for the response to arrive.'
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('I am WAITING for the response to arrive.')
+			expect(result.wasTruncated).toBe(false)
+		})
+
+		test('handles WAITING with leading spaces on the line', () => {
+			const content = `Done processing.
+  WAITING
+Hallucinated content.`
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('Done processing.\n  WAITING')
+			expect(result.wasTruncated).toBe(true)
+		})
+	})
+
+	describe('edge cases', () => {
+		test('handles empty string', () => {
+			const result = sanitizeLLMResponse('')
+
+			expect(result.content).toBeNull()
+			expect(result.wasTruncated).toBe(false)
+		})
+
+		test('preserves content with angle brackets that are not tags', () => {
+			const content = 'If a < b and b > c, then a < c.'
+
+			const result = sanitizeLLMResponse(content)
+
+			expect(result.content).toBe('If a < b and b > c, then a < c.')
+			expect(result.wasTruncated).toBe(false)
+		})
+	})
+})

package/src/core/agents/response-sanitizer.ts

@@ -0,0 +1,67 @@
+/**
+ * Response sanitization utilities for LLM outputs.
+ *
+ * Prevents hallucination by:
+ * - Truncating at <message tags (system-generated only)
+ * - Truncating after WAITING signal
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Result of sanitizing an LLM response.
+ */
+export interface SanitizedResponse {
+	/** Sanitized content (truncated at message tags, WAITING) */
+	content: string | null
+	/** Whether the response was truncated */
+	wasTruncated: boolean
+}
+
+// ============================================================================
+// Sanitization
+// ============================================================================
+
+/**
+ * Sanitize LLM response content to prevent hallucination.
+ * - Truncates at any `<message` tag (LLM should not generate these)
+ * - Truncates content after `WAITING` signal
+ *
+ * @param content - Raw LLM response content
+ */
+export function sanitizeLLMResponse(
+	content: string | null,
+): SanitizedResponse {
+	if (content === null) {
+		return { content: null, wasTruncated: false }
+	}
+
+	let result = content
+	let wasTruncated = false
+
+	// 1. Truncate at any <message tag (hallucination prevention)
+	const messageTagIndex = result.indexOf('<message')
+	if (messageTagIndex !== -1) {
+		result = result.slice(0, messageTagIndex).trimEnd()
+		wasTruncated = true
+	}
+
+	// 2. Truncate content after WAITING signal (on its own line)
+	// WAITING means "I'm done, waiting for response" - anything after is likely hallucination
+	const waitingMatch = result.match(/\n\s*WAITING\s*(?:\n|$)/)
+	if (waitingMatch && waitingMatch.index !== undefined) {
+		const endOfWaiting = waitingMatch.index + waitingMatch[0].length
+		const contentAfterWaiting = result.slice(endOfWaiting).trim()
+		if (contentAfterWaiting.length > 0) {
+			result = result.slice(0, endOfWaiting).trimEnd()
+			wasTruncated = true
+		}
+	}
+
+	return {
+		content: result || null,
+		wasTruncated,
+	}
+}