@roj-ai/sdk 0.0.2

package/src/core/preset/config.ts

@@ -0,0 +1,110 @@
+import type { AnyAgentDefinition, CommunicatorConfig, OrchestratorConfig } from '~/core/agents/config.js'
+import type { LLMMiddleware } from '~/core/llm/middleware.js'
+import type { SessionPluginConfig } from '~/core/plugins/plugin-builder.js'
+import type { CreatePresetInput } from './preset-builder.js'
+import { collectFromTree } from './preset-builder.js'
+
+/**
+ * Preset - complete configuration for a Roj session
+ */
+export interface PresetDefinition {
+	id: string
+	name: string
+	description?: string
+
+	/** Default workspace directory path. Can be overridden per session. */
+	workspaceDir?: string
+
+	/** When true, agents see virtual paths (/home/user/session, /home/user/workspace) instead of real filesystem paths */
+	sandboxed?: boolean
+
+	/**
+	 * Session-level plugin configurations.
+	 * Created via `pluginDefinition.configure(config)`.
+	 */
+	plugins?: SessionPluginConfig[]
+
+	/** Orchestrator configuration (always exists) */
+	orchestrator: OrchestratorConfig
+
+	/**
+	 * Communication agent configuration.
+	 * When present, user messages are routed through communicator first.
+	 * When absent, messages go directly to orchestrator.
+	 */
+	communicator?: CommunicatorConfig
+
+	/** Definitions of spawnable agents (accepts both typed and untyped agents) */
+	agents: AnyAgentDefinition[]
+
+	/** LLM middleware chain applied to all agents in this preset (runs before agent-level middleware) */
+	llmMiddleware?: LLMMiddleware[]
+
+	/**
+	 * Platform resource slugs to inject into sessions by default.
+	 * The init workflow resolves these slugs to resource files and injects them
+	 * into the workspace when no explicit resourceIds are provided.
+	 */
+	defaultResourceSlugs?: string[]
+}
+
+/**
+ * Create a preset with automatic collection.
+ *
+ * Recursively walks the orchestrator (and communicator) tree to collect
+ * all agents. Then validates with `validatePreset()`.
+ *
+ * @throws Error if preset validation fails
+ */
+export function createPreset(input: CreatePresetInput): PresetDefinition {
+	const collected = collectFromTree(input.orchestrator)
+
+	if (input.communicator) {
+		const commCollected = collectFromTree(input.communicator)
+		for (const a of commCollected.agents) {
+			if (!collected.agents.includes(a)) collected.agents.push(a)
+		}
+	}
+
+	const preset: PresetDefinition = {
+		...input,
+		agents: collected.agents,
+	}
+
+	const errors = validatePreset(preset)
+	if (errors.length > 0) {
+		throw new Error(`Invalid preset "${preset.id}":\n${errors.map((e) => `  - ${e}`).join('\n')}`)
+	}
+
+	return preset
+}
+
+/**
+ * Validates a preset configuration, checking that all referenced agents, and services exist.
+ * @param preset The preset to validate
+ * @returns Array of error messages (empty if valid)
+ */
+export const validatePreset = (preset: PresetDefinition): string[] => {
+	const errors: string[] = []
+
+	// Collect all defined agent names
+	const agentNames = new Set(preset.agents.map((a) => a.name))
+
+	// Check orchestrator spawnable agents
+	for (const name of preset.orchestrator.agents ?? []) {
+		if (!agentNames.has(name)) {
+			errors.push(`Orchestrator references unknown agent: ${name}`)
+		}
+	}
+
+	// Check each agent's spawnable agents and workers
+	for (const agent of preset.agents) {
+		for (const name of agent.agents ?? []) {
+			if (!agentNames.has(name)) {
+				errors.push(`Agent '${agent.name}' references unknown agent: ${name}`)
+			}
+		}
+	}
+
+	return errors
+}

package/src/core/preset/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Preset module - type-safe preset builder and configuration
+ */
+
+// Re-export from config
+export type { PresetDefinition as Preset } from './config.js'
+export { createPreset, validatePreset } from './config.js'
+
+// Re-export from preset-builder
+export type { CreateOrchestratorInput, DefineAgentInput } from './preset-builder.js'
+export { createOrchestrator, defineAgent } from './preset-builder.js'

package/src/core/preset/preset-builder.ts

@@ -0,0 +1,111 @@
+/**
+ * Type-safe preset builder for Roj SDK.
+ *
+ * Replaces string-based cross-references (spawnableAgents)
+ * with object references, catching typos and renames at compile time.
+ *
+ * `createPreset` recursively collects agents from the orchestrator tree.
+ */
+
+import type { Preset } from '~/core/preset/index.js'
+import type { AgentDefinition, AnyAgentDefinition, BaseAgentConfig, OrchestratorConfig } from '../agents/config.js'
+
+// ============================================================================
+// Helper types
+// ============================================================================
+
+interface ObjectRefs {
+	agents?: AnyAgentDefinition[]
+}
+
+/**
+ * Replace string ref fields with short object-ref fields.
+ * `agents: string[]` → `agents: AnyAgentDefinition[]`
+ */
+type WithObjectRefs<T> =
+	& Omit<T, 'spawnableAgents' | 'agents'>
+	& ObjectRefs
+
+// ============================================================================
+// Public input types
+// ============================================================================
+
+/** Input type for defineAgent - uses object refs instead of string names */
+export type DefineAgentInput<TInput = unknown> = WithObjectRefs<AgentDefinition<TInput>>
+
+/** Input type for createOrchestrator - uses object refs instead of string names */
+export type CreateOrchestratorInput = WithObjectRefs<BaseAgentConfig>
+
+/** Input type for createPreset - agents are auto-collected from the tree */
+export type CreatePresetInput = Omit<Preset, 'agents'>
+
+// ============================================================================
+// Internal: ref storage & resolution
+// ============================================================================
+
+/** Stores original object refs for each resolved config, keyed by identity */
+const refStore = new WeakMap<object, ObjectRefs>()
+
+function resolveAndStore<T extends object>(
+	refs: ObjectRefs,
+	resolved: T,
+): T {
+	refStore.set(resolved, refs)
+	return resolved
+}
+
+interface ResolvedRefs {
+	agents: string[]
+}
+
+function resolveRefs(refs: ObjectRefs): ResolvedRefs {
+	return {
+		agents: (refs.agents ?? []).map((a) => a.name),
+	}
+}
+
+/** Recursively collect agents from a config node */
+export function collectFromTree(root: object): { agents: AnyAgentDefinition[] } {
+	const agents = new Set<AnyAgentDefinition>()
+
+	function visit(node: object) {
+		const refs = refStore.get(node)
+		if (!refs) return
+
+		for (const agent of refs.agents ?? []) {
+			if (!agents.has(agent)) {
+				agents.add(agent)
+				visit(agent)
+			}
+		}
+	}
+
+	visit(root)
+	return { agents: [...agents] }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Define an agent with type-safe object references.
+ *
+ * Accepts `agents`  as object references
+ * and resolves them to string names for the runtime.
+ */
+export function defineAgent<TInput = unknown>(input: DefineAgentInput<TInput>): AgentDefinition<TInput> {
+	const { agents, ...rest } = input
+	return resolveAndStore({ agents }, { ...rest, ...resolveRefs({ agents }) })
+}
+
+/**
+ * Create an orchestrator config with type-safe object references.
+ *
+ * Accepts `agents` as object references
+ * and resolves them to string names for the runtime.
+ */
+export function createOrchestrator(input: CreateOrchestratorInput): OrchestratorConfig {
+	const { agents, ...rest } = input
+	return resolveAndStore({ agents }, { ...rest, ...resolveRefs({ agents }) })
+}

package/src/core/session-lifecycle.integration.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { ModelId } from '~/core/llm/schema.js'
+import { SessionId } from '~/core/sessions/schema.js'
+import { sessionEvents } from '~/core/sessions/state.js'
+import { createTestPreset, TestHarness } from '~/testing/index.js'
+
+describe('core: session lifecycle', () => {
+	it('create session → session_created event emitted', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+
+		const events = await session.getEventsByType(sessionEvents, 'session_created')
+		expect(events).toHaveLength(1)
+		expect(events[0].presetId).toBe('test')
+
+		await harness.shutdown()
+	})
+
+	it('create session → orchestrator agent spawned automatically', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+
+		const spawnEvents = await session.getEventsByType(agentEvents, 'agent_spawned')
+		expect(spawnEvents.length).toBeGreaterThanOrEqual(1)
+
+		// The orchestrator should be the entry agent
+		const entryAgentId = session.getEntryAgentId()
+		expect(entryAgentId).not.toBeNull()
+
+		const agentState = session.state.agents.get(entryAgentId!)
+		expect(agentState).toBeDefined()
+
+		await harness.shutdown()
+	})
+
+	it('create session with communicator config → both communicator and orchestrator spawned', async () => {
+		const harness = new TestHarness({
+			presets: [{
+				id: 'test-comm',
+				name: 'Test with communicator',
+				orchestrator: {
+					system: 'Orchestrator.',
+					model: ModelId('mock'),
+					tools: [],
+					agents: [],
+					debounceMs: 0,
+				},
+				communicator: {
+					system: 'Communicator.',
+					model: ModelId('mock'),
+					debounceMs: 0,
+				},
+				agents: [],
+			}],
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test-comm')
+
+		const spawnEvents = await session.getEventsByType(agentEvents, 'agent_spawned')
+		// Should have both communicator and orchestrator
+		expect(spawnEvents.length).toBeGreaterThanOrEqual(2)
+
+		// Entry agent should be the communicator
+		const entryAgentId = session.getEntryAgentId()
+		expect(entryAgentId).not.toBeNull()
+
+		// Both agents should exist in state
+		expect(session.state.agents.size).toBeGreaterThanOrEqual(2)
+
+		await harness.shutdown()
+	})
+
+	it('close session → session_closed event → status becomes closed', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hi')
+
+		await session.close()
+
+		// Reload the session to check state
+		const reloaded = await harness.sessionManager.getSession(session.sessionId)
+		expect(reloaded.ok).toBe(true)
+		if (reloaded.ok) {
+			expect(reloaded.value.state.status).toBe('closed')
+
+			const closedEvents = await harness.eventStore.getEventsByType(session.sessionId, 'session_closed')
+			expect(closedEvents).toHaveLength(1)
+		}
+
+		await harness.shutdown()
+	})
+
+	it('reopen session → session_reopened event → agents can process again', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hi')
+
+		// Close
+		await session.close()
+
+		// Reopen via plugin method (need to reload first)
+		const reloaded = await harness.sessionManager.getSession(session.sessionId)
+		expect(reloaded.ok).toBe(true)
+		if (reloaded.ok) {
+			const reopenResult = await reloaded.value.callPluginMethod('sessions.reopen', {})
+			expect(reopenResult.ok).toBe(true)
+
+			const reopenedEvents = await harness.eventStore.getEventsByType(session.sessionId, 'session_reopened')
+			expect(reopenedEvents).toHaveLength(1)
+
+			// Session should be active again
+			expect(reloaded.value.state.status).toBe('active')
+		}
+
+		await harness.shutdown()
+	})
+
+	it('session state reconstructed correctly from events', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hello')
+
+		const originalState = session.state
+		const originalAgentCount = originalState.agents.size
+		const originalPresetId = originalState.presetId
+
+		// Reload session from event store (simulates restart)
+		const reloaded = await harness.sessionManager.getSession(session.sessionId)
+		expect(reloaded.ok).toBe(true)
+		if (reloaded.ok) {
+			const reloadedState = reloaded.value.state
+			expect(reloadedState.presetId).toBe(originalPresetId)
+			expect(reloadedState.agents.size).toBe(originalAgentCount)
+			expect(reloadedState.status).toBe('active')
+		}
+
+		await harness.shutdown()
+	})
+
+	it('fork session → new session with events up to fork point, independent processing', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Message 1')
+		await session.sendAndWaitForIdle('Message 2')
+
+		const originalEvents = await session.getEvents()
+		// Fork at roughly half the events
+		const forkIndex = Math.floor(originalEvents.length / 2)
+
+		const forkResult = await harness.sessionManager.callManagerMethod('sessions.fork', {
+			sessionId: String(session.sessionId),
+			eventIndex: forkIndex,
+		})
+
+		expect(forkResult.ok).toBe(true)
+		if (forkResult.ok) {
+			expect(forkResult.value).toMatchObject({ sessionId: expect.any(String) })
+		}
+
+		if (forkResult.ok && typeof forkResult.value === 'object' && forkResult.value !== null && 'sessionId' in forkResult.value) {
+			const forkedSessionId = SessionId(String(forkResult.value.sessionId))
+
+			// Forked session should have fewer events than the original
+			const forkedEvents = await harness.eventStore.load(forkedSessionId)
+			expect(forkedEvents.length).toBeLessThan(originalEvents.length)
+
+			// Original session should be unaffected
+			const originalEventsAfter = await session.getEvents()
+			expect(originalEventsAfter.length).toBe(originalEvents.length)
+		}
+
+		await harness.shutdown()
+	})
+})

package/src/core/sessions/apply-event.ts

@@ -0,0 +1,46 @@
+/**
+ * Composed event reducer — core reducer + plugin state slices.
+ *
+ * This file is the composition root for the event-sourced reducer.
+ * Core SessionState stays free of plugin imports; each plugin owns a
+ * dynamic state slice accessed via `selectPluginState()`.
+ *
+ * The default `applyEvent` includes core + always-enabled plugins (mailbox).
+ * Additional plugin reducers are composed via `createApplyEvent()`.
+ */
+
+import type { ConfiguredPlugin } from '~/core/plugins/plugin-builder.js'
+import { mailboxPlugin } from '~/plugins/mailbox/plugin.js'
+import type { SessionReducer } from './reducer.js'
+import { composeReducers } from './reducer.js'
+import { coreReducer } from './state.js'
+
+/**
+ * Base reducer: core events + always-enabled plugin state slices (mailbox).
+ * Mailbox is always enabled, has no config, and is fundamental to all sessions.
+ */
+const mailboxConfigured = mailboxPlugin.create({})
+const baseReducer: SessionReducer = mailboxConfigured.slice
+	? composeReducers(coreReducer, mailboxConfigured.slice.reducer)
+	: coreReducer
+
+export const applyEvent: SessionReducer = baseReducer
+
+/**
+ * Create a composed reducer that handles core + all plugin events.
+ * Use this when additional plugins are available (e.g. in SessionStore).
+ */
+export const createApplyEvent = (plugins: ConfiguredPlugin[]): SessionReducer => {
+	const pluginReducers: SessionReducer[] = []
+	for (const plugin of plugins) {
+		// Skip mailbox — already included in baseReducer
+		if (plugin.name === 'mailbox') continue
+		if (plugin.slice !== undefined) {
+			pluginReducers.push(plugin.slice.reducer)
+		}
+	}
+
+	if (pluginReducers.length === 0) return baseReducer
+
+	return composeReducers(baseReducer, ...pluginReducers)
+}

package/src/core/sessions/context.ts

@@ -0,0 +1,36 @@
+import type { EventStore } from '~/core/events/event-store'
+import type { BaseEvent } from '~/core/events/types'
+import type { LLMLogger } from '~/core/llm/logger'
+import type { LLMProvider } from '~/core/llm/provider'
+import type { Logger } from '~/lib/logger/logger'
+import type { Platform } from '~/platform/index.js'
+import type { FileStore } from '../file-store/types'
+import type { SessionId } from './schema'
+import type { SessionEnvironment } from './session-environment'
+import type { SessionState } from './state'
+
+export type SessionContext<TSessionInput = unknown> = {
+	readonly sessionId: SessionId
+	/** The full session state (readonly) */
+	readonly sessionState: SessionState
+	/** The typed input if agent has inputSchema, otherwise the task string */
+	readonly sessionInput: TSessionInput
+	/** Session environment directories */
+	readonly environment: SessionEnvironment
+	/** LLM inference client for handlers that need LLM access */
+	readonly llm: LLMProvider
+	/** FileStore with full access - resolves agent-visible paths */
+	readonly files: FileStore
+	/** Event store for loading/querying events */
+	readonly eventStore: EventStore
+	/** LLM call logger for debugging and audit */
+	readonly llmLogger?: LLMLogger
+	/** Host-environment adapters (filesystem, process). */
+	readonly platform: Platform
+
+	readonly logger: Logger
+
+	emitEvent: (event: Omit<BaseEvent<string>, 'sessionId'>) => Promise<void>
+	/** Send a notification to connected clients via transport (ephemeral, not persisted) */
+	notify: (type: string, payload: unknown) => void
+}

package/src/core/sessions/fork-utils.test.ts

@@ -0,0 +1,158 @@
+import { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { withSessionId } from '~/core/events/test-helpers.js'
+import type { DomainEvent, FactoryEventType } from '~/core/events/types.js'
+import { SessionId } from '~/core/sessions/schema.js'
+import { sessionEvents } from '~/core/sessions/state.js'
+import type { SessionCreatedEvent } from '~/core/sessions/state.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { toolEvents } from '~/core/tools/state.js'
+
+type ToolEvent = FactoryEventType<typeof toolEvents>
+import { describe, expect, it } from 'bun:test'
+import { findSnapshotRefsAtIndex, rewriteEventsForFork } from './fork-utils.js'
+
+const sourceSessionId = SessionId('source-session-id')
+const newSessionId = SessionId('new-session-id')
+const agentId = AgentId('agent-1')
+
+function makeEvents(): DomainEvent[] {
+	return [
+		{
+			...withSessionId(
+				sourceSessionId,
+				sessionEvents.create('session_created', {
+					presetId: 'test-preset',
+					workspaceDir: '/workspace/source',
+				}),
+			),
+			timestamp: 1000,
+		},
+		{
+			...withSessionId(
+				sourceSessionId,
+				agentEvents.create('agent_spawned', {
+					agentId,
+					definitionName: 'orchestrator',
+					parentId: null,
+				}),
+			),
+			timestamp: 1001,
+		},
+		{
+			...withSessionId(
+				sourceSessionId,
+				toolEvents.create('tool_completed', {
+					agentId,
+					toolCallId: ToolCallId('tc-1'),
+					result: 'done',
+					sessionRef: 'session-ref-1',
+					workspaceRef: 'workspace-ref-1',
+				}),
+			),
+			timestamp: 1002,
+		},
+		{
+			...withSessionId(
+				sourceSessionId,
+				toolEvents.create('tool_completed', {
+					agentId,
+					toolCallId: ToolCallId('tc-2'),
+					result: 'done again',
+					sessionRef: 'session-ref-2',
+				}),
+			),
+			timestamp: 1003,
+		},
+		{
+			...withSessionId(
+				sourceSessionId,
+				toolEvents.create('tool_failed', {
+					agentId,
+					toolCallId: ToolCallId('tc-3'),
+					error: 'oops',
+					workspaceRef: 'workspace-ref-3',
+					sessionRef: 'session-ref-3',
+				}),
+			),
+			timestamp: 1004,
+		},
+	]
+}
+
+describe('rewriteEventsForFork', () => {
+	it('slices events up to eventIndex inclusive', () => {
+		const events = makeEvents()
+		const result = rewriteEventsForFork(events, 2, newSessionId, sourceSessionId)
+		expect(result).toHaveLength(3)
+	})
+
+	it('rewrites sessionId on all events', () => {
+		const events = makeEvents()
+		const result = rewriteEventsForFork(events, 2, newSessionId, sourceSessionId)
+		for (const event of result) {
+			expect(event.sessionId).toBe(newSessionId)
+		}
+	})
+
+	it('adds forkedFrom to session_created event', () => {
+		const events = makeEvents()
+		const result = rewriteEventsForFork(events, 2, newSessionId, sourceSessionId)
+		const created = result[0] as SessionCreatedEvent
+		expect(created.type).toBe('session_created')
+		expect(created.forkedFrom).toEqual({
+			sessionId: sourceSessionId,
+			eventIndex: 2,
+		})
+	})
+
+	it('preserves all other event fields', () => {
+		const events = makeEvents()
+		const result = rewriteEventsForFork(events, 2, newSessionId, sourceSessionId)
+		const toolEvent = result[2] as ToolEvent
+		expect(toolEvent.type).toBe('tool_completed')
+		if (toolEvent.type === 'tool_completed') {
+			expect(toolEvent.sessionRef).toBe('session-ref-1')
+			expect(toolEvent.workspaceRef).toBe('workspace-ref-1')
+			expect(toolEvent.result).toBe('done')
+		}
+	})
+
+	it('handles eventIndex 0 (only session_created)', () => {
+		const events = makeEvents()
+		const result = rewriteEventsForFork(events, 0, newSessionId, sourceSessionId)
+		expect(result).toHaveLength(1)
+		expect(result[0].type).toBe('session_created')
+	})
+})
+
+describe('findSnapshotRefsAtIndex', () => {
+	it('finds the most recent refs scanning backwards', () => {
+		const events = makeEvents()
+		const refs = findSnapshotRefsAtIndex(events, 4)
+		expect(refs.sessionRef).toBe('session-ref-3')
+		expect(refs.workspaceRef).toBe('workspace-ref-3')
+	})
+
+	it('finds refs at exact index', () => {
+		const events = makeEvents()
+		const refs = findSnapshotRefsAtIndex(events, 2)
+		expect(refs.sessionRef).toBe('session-ref-1')
+		expect(refs.workspaceRef).toBe('workspace-ref-1')
+	})
+
+	it('falls back to earlier events for missing refs', () => {
+		const events = makeEvents()
+		// Event 3 has sessionRef but no workspaceRef, should fall back to event 2 for workspaceRef
+		const refs = findSnapshotRefsAtIndex(events, 3)
+		expect(refs.sessionRef).toBe('session-ref-2')
+		expect(refs.workspaceRef).toBe('workspace-ref-1')
+	})
+
+	it('returns undefined refs when no events have them', () => {
+		const events = makeEvents()
+		const refs = findSnapshotRefsAtIndex(events, 1)
+		expect(refs.sessionRef).toBeUndefined()
+		expect(refs.workspaceRef).toBeUndefined()
+	})
+})