@roj-ai/sdk 0.0.2

package/src/core/event-sourcing.integration.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from 'bun:test'
+import { agentEvents } from '~/core/agents/state.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { llmEvents } from '~/core/llm/state.js'
+import { applyEvent } from '~/core/sessions/apply-event.js'
+import { reconstructSessionState } from '~/core/sessions/state.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { toolEvents } from '~/core/tools/state.js'
+import { createTestPreset, TestHarness } from '~/testing/index.js'
+
+describe('core: event sourcing correctness', () => {
+	it('all events from a full flow persisted in event store in correct order', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withSequence([
+				{
+					toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hi!' } }],
+				},
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hello')
+
+		const events = await session.getEvents()
+
+		// Should start with session_created
+		expect(events[0].type).toBe('session_created')
+
+		// Extract event types in order
+		const types = events.map((e) => e.type)
+
+		// session_created must come first
+		expect(types.indexOf('session_created')).toBe(0)
+
+		// agent_spawned after session_created
+		expect(types.indexOf('agent_spawned')).toBeGreaterThan(types.indexOf('session_created'))
+
+		// inference_started before inference_completed
+		const inferStartIdx = types.indexOf('inference_started')
+		const inferCompleteIdx = types.indexOf('inference_completed')
+		expect(inferStartIdx).toBeGreaterThan(-1)
+		expect(inferCompleteIdx).toBeGreaterThan(inferStartIdx)
+
+		// tool_started before tool_completed
+		const toolStartIdx = types.indexOf('tool_started')
+		const toolCompleteIdx = types.indexOf('tool_completed')
+		expect(toolStartIdx).toBeGreaterThan(-1)
+		expect(toolCompleteIdx).toBeGreaterThan(toolStartIdx)
+
+		// tool events between first and second inference cycles
+		expect(toolStartIdx).toBeGreaterThan(inferCompleteIdx)
+
+		await harness.shutdown()
+	})
+
+	it('session state after replay matches live state', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withSequence([
+				{
+					toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hi!' } }],
+				},
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hello')
+
+		const liveState = session.state
+		const events = await session.getEvents()
+
+		// Replay state from events using the base reducer (core + mailbox)
+		const replayedState = reconstructSessionState(events, applyEvent)
+
+		expect(replayedState).not.toBeNull()
+		expect(replayedState!.id).toEqual(liveState.id)
+		expect(replayedState!.presetId).toBe(liveState.presetId)
+		expect(replayedState!.status).toBe(liveState.status)
+		expect(replayedState!.agents.size).toBe(liveState.agents.size)
+
+		// Verify each agent's status matches
+		for (const [agentId, liveAgent] of liveState.agents) {
+			const replayedAgent = replayedState!.agents.get(agentId)
+			expect(replayedAgent).toBeDefined()
+			expect(replayedAgent!.status).toBe(liveAgent.status)
+			expect(replayedAgent!.definitionName).toBe(liveAgent.definitionName)
+			expect(replayedAgent!.conversationHistory.length).toBe(liveAgent.conversationHistory.length)
+		}
+
+		await harness.shutdown()
+	})
+
+	it('event types include expected core events from a full flow', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withSequence([
+				{
+					toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hi!' } }],
+				},
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hello')
+
+		const events = await session.getEvents()
+		const eventTypes = new Set(events.map((e) => e.type))
+
+		// Core lifecycle events
+		expect(eventTypes.has('session_created')).toBe(true)
+		expect(eventTypes.has('agent_spawned')).toBe(true)
+
+		// LLM events
+		expect(eventTypes.has('inference_started')).toBe(true)
+		expect(eventTypes.has('inference_completed')).toBe(true)
+
+		// Tool events
+		expect(eventTypes.has('tool_started')).toBe(true)
+		expect(eventTypes.has('tool_completed')).toBe(true)
+
+		// User chat events
+		expect(eventTypes.has('user_chat_message_received')).toBe(true)
+
+		await harness.shutdown()
+	})
+
+	it('event timestamps are monotonically increasing', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withSequence([
+				{
+					toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hi!' } }],
+				},
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hello')
+
+		const events = await session.getEvents()
+
+		for (let i = 1; i < events.length; i++) {
+			expect(events[i].timestamp).toBeGreaterThanOrEqual(events[i - 1].timestamp)
+		}
+
+		await harness.shutdown()
+	})
+
+	it('events have correct agentId references', async () => {
+		const harness = new TestHarness({
+			presets: [createTestPreset()],
+			llmProvider: MockLLMProvider.withSequence([
+				{
+					toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hi!' } }],
+				},
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hello')
+
+		const entryAgentId = session.getEntryAgentId()!
+
+		// All agent-scoped events should reference the entry agent
+		const inferenceStarted = await session.getEventsByType(llmEvents, 'inference_started')
+		const inferenceCompleted = await session.getEventsByType(llmEvents, 'inference_completed')
+		const toolStarted = await session.getEventsByType(toolEvents, 'tool_started')
+		const toolCompleted = await session.getEventsByType(toolEvents, 'tool_completed')
+		const agentScopedEvents = [...inferenceStarted, ...inferenceCompleted, ...toolStarted, ...toolCompleted]
+
+		expect(agentScopedEvents.length).toBeGreaterThan(0)
+		for (const event of agentScopedEvents) {
+			expect(event.agentId).toBe(entryAgentId)
+		}
+
+		// agent_spawned should also reference the correct agent
+		const spawnedEvents = await session.getEventsByType(agentEvents, 'agent_spawned')
+		expect(spawnedEvents.length).toBeGreaterThan(0)
+		for (const e of spawnedEvents) {
+			expect(session.state.agents.has(e.agentId)).toBe(true)
+		}
+
+		await harness.shutdown()
+	})
+})

package/src/core/events/base-event-store.ts

@@ -0,0 +1,264 @@
+import type { DomainEvent } from '~/core/events/types.js'
+import type { ListSessionsOptions, SessionId, SessionMetadata } from '~/core/sessions/schema.js'
+import { EventStoreError, type EventStore, type LoadRangeOptions, type LoadRangeResult } from './event-store.js'
+import type { MetadataEvent } from './metadata-utils.js'
+import { computeMetadataFromEvents, needsReconciliation } from './metadata-utils.js'
+
+/**
+ * Event types that must never be emitted on a closed session.
+ * See guardWriteToClosed for rationale.
+ */
+function isForbiddenOnClosed(event: DomainEvent): boolean {
+	return event.type === 'session_handler_started' || event.type === 'session_handler_completed'
+}
+
+/**
+ * Abstract base class for EventStore implementations.
+ *
+ * Provides shared logic for metadata processing, filtering/sorting/pagination,
+ * and reconciliation. Subclasses only implement storage primitives.
+ */
+export abstract class BaseEventStore implements EventStore {
+	// === Public append API (with closed-session guard) ===
+
+	async append(sessionId: SessionId, event: DomainEvent): Promise<void> {
+		if (isForbiddenOnClosed(event)) {
+			await this.guardWriteToClosed(sessionId, [event])
+		}
+		await this.doAppend(sessionId, event)
+	}
+
+	async appendBatch(sessionId: SessionId, events: DomainEvent[]): Promise<void> {
+		if (events.length === 0) return
+		if (events.some(isForbiddenOnClosed)) {
+			await this.guardWriteToClosed(sessionId, events)
+		}
+		await this.doAppendBatch(sessionId, events)
+	}
+
+	// === Storage primitives (subclasses implement) ===
+
+	protected abstract doAppend(sessionId: SessionId, event: DomainEvent): Promise<void>
+	protected abstract doAppendBatch(sessionId: SessionId, events: DomainEvent[]): Promise<void>
+	abstract load(sessionId: SessionId): Promise<DomainEvent[]>
+	abstract loadRange(sessionId: SessionId, options?: LoadRangeOptions): Promise<LoadRangeResult>
+	abstract exists(sessionId: SessionId): Promise<boolean>
+	abstract listSessions(): Promise<SessionId[]>
+
+	// === Metadata storage primitives (subclasses implement) ===
+
+	protected abstract readMetadata(sessionId: SessionId): Promise<SessionMetadata | null>
+	protected abstract writeMetadata(sessionId: SessionId, metadata: SessionMetadata): Promise<void>
+	protected abstract getAllSessionMetadata(): Promise<SessionMetadata[]>
+
+	// === Shared implementations ===
+
+	async getMetadata(sessionId: SessionId): Promise<SessionMetadata | null> {
+		return this.readMetadata(sessionId)
+	}
+
+	async updateMetadata(
+		sessionId: SessionId,
+		update: Partial<SessionMetadata>,
+	): Promise<void> {
+		const existing = await this.readMetadata(sessionId)
+		const metadata: SessionMetadata = {
+			...existing,
+			...update,
+			sessionId,
+			lastActivityAt: update.lastActivityAt ?? Date.now(),
+		} as SessionMetadata
+
+		await this.writeMetadata(sessionId, metadata)
+	}
+
+	async listSessionsWithMetadata(
+		options?: ListSessionsOptions,
+	): Promise<{ sessions: SessionMetadata[]; total: number }> {
+		let sessions = await this.getAllSessionMetadata()
+
+		// Filter by status
+		if (options?.status) {
+			sessions = sessions.filter((s) => s.status === options.status)
+		}
+
+		// Filter by tags
+		if (options?.tags && options.tags.length > 0) {
+			sessions = sessions.filter((s) => options.tags!.every((tag) => s.tags?.includes(tag)))
+		}
+
+		const total = sessions.length
+
+		// Sort
+		const orderBy = options?.orderBy ?? 'createdAt'
+		const order = options?.order ?? 'desc'
+		sessions.sort((a, b) => {
+			const aVal = a[orderBy] ?? 0
+			const bVal = b[orderBy] ?? 0
+			return order === 'asc' ? aVal - bVal : bVal - aVal
+		})
+
+		// Pagination
+		const offset = options?.offset ?? 0
+		const limit = options?.limit ?? sessions.length
+		sessions = sessions.slice(offset, offset + limit)
+
+		return { sessions, total }
+	}
+
+	async reconcileMetadata(
+		sessionId: SessionId,
+		events: DomainEvent[],
+	): Promise<boolean> {
+		if (events.length === 0) return false
+
+		const computed = computeMetadataFromEvents(sessionId, events)
+		if (!computed) return false
+
+		const stored = await this.readMetadata(sessionId)
+
+		if (!needsReconciliation(stored, computed)) {
+			return false
+		}
+
+		// Metadata is out of sync - update with computed values
+		// Preserve name, tags, and custom data from stored metadata
+		const reconciled: SessionMetadata = {
+			...computed,
+			name: stored?.name,
+			tags: stored?.tags,
+			custom: stored?.custom,
+		}
+
+		await this.writeMetadata(sessionId, reconciled)
+		return true
+	}
+
+	/**
+	 * Update metadata incrementally from events.
+	 * Aggregates all metric deltas and writes once.
+	 */
+	protected async updateMetadataFromEvents(
+		sessionId: SessionId,
+		events: DomainEvent[],
+	): Promise<void> {
+		if (events.length === 0) return
+
+		const metadata = await this.readMetadata(sessionId)
+
+		// Start with current metrics or defaults
+		let metrics = metadata?.metrics ?? {
+			totalEvents: 0,
+			totalAgents: 0,
+			totalTokens: 0,
+			totalLLMCalls: 0,
+			inputTokens: 0,
+			outputTokens: 0,
+			totalCost: 0,
+			totalMessages: 0,
+			totalToolCalls: 0,
+		}
+
+		const update: Partial<SessionMetadata> = {}
+
+		// Process all events and aggregate metrics
+		for (const event of events as MetadataEvent[]) {
+			update.lastActivityAt = event.timestamp
+
+			switch (event.type) {
+				case 'session_created':
+					update.createdAt = event.timestamp
+					update.presetId = event.presetId
+					update.status = 'active'
+					metrics = {
+						totalEvents: 1,
+						totalAgents: 0,
+						totalTokens: 0,
+						totalLLMCalls: 0,
+						inputTokens: 0,
+						outputTokens: 0,
+						totalCost: 0,
+						totalMessages: 0,
+						totalToolCalls: 0,
+					}
+					break
+
+				case 'session_closed':
+					update.status = 'closed'
+					metrics.totalEvents += 1
+					break
+
+				case 'session_reopened':
+					update.status = 'active'
+					metrics.totalEvents += 1
+					break
+
+				case 'agent_spawned':
+					metrics.totalAgents += 1
+					metrics.totalEvents += 1
+					break
+
+				case 'inference_completed':
+					if (event.metrics) {
+						metrics.totalTokens += event.metrics.totalTokens ?? 0
+						metrics.inputTokens = (metrics.inputTokens ?? 0) + (event.metrics.promptTokens ?? 0)
+						metrics.outputTokens = (metrics.outputTokens ?? 0) + (event.metrics.completionTokens ?? 0)
+						metrics.totalCost = (metrics.totalCost ?? 0) + (event.metrics.cost ?? 0)
+						metrics.totalLLMCalls += 1
+					}
+					metrics.totalEvents += 1
+					break
+
+				case 'mailbox_message':
+					metrics.totalMessages = (metrics.totalMessages ?? 0) + 1
+					metrics.totalEvents += 1
+					break
+
+				case 'tool_started':
+					metrics.totalToolCalls = (metrics.totalToolCalls ?? 0) + 1
+					metrics.totalEvents += 1
+					break
+
+				default:
+					metrics.totalEvents += 1
+			}
+		}
+
+		update.metrics = metrics
+		await this.updateMetadata(sessionId, update)
+	}
+
+	/**
+	 * Reject session-level hook events on closed sessions.
+	 *
+	 * Closed sessions must be prevented from re-running session-level plugin hooks
+	 * (the `session_handler_*` events) because those hooks have no place operating
+	 * on an immutable artifact — and when they do, every read / restart of the closed
+	 * session appends two events, which is how we observed 7866 handler_started events
+	 * on a single closed session over 4.9 days in production.
+	 *
+	 * Other event types are deliberately allowed even after session_closed:
+	 *   - in-flight agent events (inference_*, tool_*) finishing after close
+	 *   - mailbox_message deliveries racing close
+	 *   - service_status_changed from cleanup hooks stopping services
+	 *
+	 * The invariant we guard is narrow: "session-level plugin hooks never emit on
+	 * closed sessions." See the loadSession / skipReadyHooks path in session-manager
+	 * for the primary fix; this is the storage-boundary backup that catches any
+	 * future code path that somehow slips through.
+	 */
+	protected async guardWriteToClosed(sessionId: SessionId, events: DomainEvent[]): Promise<void> {
+		const forbidden = events.filter(isForbiddenOnClosed)
+		if (forbidden.length === 0) return
+
+		const metadata = await this.readMetadata(sessionId)
+		if (metadata?.status !== 'closed') return
+
+		const forbiddenTypes = forbidden.map((e) => e.type).join(', ')
+		throw new EventStoreError(
+			`Refusing to append session-level hook event(s) to closed session ${sessionId} (types: ${forbiddenTypes}). `
+				+ `Closed sessions must not re-run plugin session hooks — see session-manager.ts:loadSession closed branch.`,
+			sessionId,
+		)
+	}
+}

package/src/core/events/event-store.ts

@@ -0,0 +1,143 @@
+import type { DomainEvent } from '~/core/events/types.js'
+import type { ListSessionsOptions, SessionId, SessionMetadata } from '~/core/sessions/schema.js'
+
+export type { ListSessionsOptions, SessionMetadata }
+
+/**
+ * Options for loading a range of events.
+ */
+export interface LoadRangeOptions {
+	/** Skip events with index <= since (0-indexed). Default: -1 (load from start) */
+	since?: number
+	/** Max events to return. Default: no limit */
+	limit?: number
+}
+
+/**
+ * Result of loading a range of events.
+ */
+export interface LoadRangeResult {
+	events: DomainEvent[]
+	/** Index of first returned event (-1 if no events returned) */
+	fromIndex: number
+	/** Index of last event in the store, used as cursor for polling (-1 only if store is empty) */
+	toIndex: number
+}
+
+/**
+ * EventStore interface pro persistenci domain events.
+ *
+ * Implementace:
+ * - FileEventStore - JSONL soubory (production)
+ * - MemoryEventStore - in-memory (testy)
+ */
+export interface EventStore {
+	/**
+	 * Přidá jeden event do store.
+	 */
+	append(sessionId: SessionId, event: DomainEvent): Promise<void>
+
+	/**
+	 * Přidá více eventů atomicky.
+	 * Všechny eventy musí být uloženy, nebo žádný.
+	 */
+	appendBatch(sessionId: SessionId, events: DomainEvent[]): Promise<void>
+
+	/**
+	 * Načte všechny eventy pro session.
+	 * Eventy jsou vráceny v pořadí jak byly uloženy.
+	 */
+	load(sessionId: SessionId): Promise<DomainEvent[]>
+
+	/**
+	 * Zkontroluje zda session existuje.
+	 */
+	exists(sessionId: SessionId): Promise<boolean>
+
+	/**
+	 * Vrátí seznam všech session IDs.
+	 * Použito při restartu pro načtení všech sessions.
+	 */
+	listSessions(): Promise<SessionId[]>
+
+	/**
+	 * Načte metadata session.
+	 * Vrátí null pokud session neexistuje nebo nemá metadata.
+	 */
+	getMetadata(sessionId: SessionId): Promise<SessionMetadata | null>
+
+	/**
+	 * Aktualizuje metadata session.
+	 * Merge s existujícími hodnotami.
+	 */
+	updateMetadata(
+		sessionId: SessionId,
+		update: Partial<SessionMetadata>,
+	): Promise<void>
+
+	/**
+	 * Vrátí seznam sessions s metadata.
+	 * Podporuje filtrování, řazení a paginaci.
+	 */
+	listSessionsWithMetadata(
+		options?: ListSessionsOptions,
+	): Promise<{ sessions: SessionMetadata[]; total: number }>
+
+	/**
+	 * Načte rozsah eventů pro session.
+	 * Optimalizováno pro polling - čte z konce souboru pokud je to efektivní.
+	 */
+	loadRange(
+		sessionId: SessionId,
+		options?: LoadRangeOptions,
+	): Promise<LoadRangeResult>
+
+	/**
+	 * Validates and reconciles metadata against actual events.
+	 * If metadata is out of sync (e.g., after crash), recomputes it from events.
+	 * Returns true if metadata was reconciled (was out of sync).
+	 */
+	reconcileMetadata(
+		sessionId: SessionId,
+		events: DomainEvent[],
+	): Promise<boolean>
+}
+
+/**
+ * EventStore s podporou pro streaming (optional rozšíření).
+ */
+export interface StreamingEventStore extends EventStore {
+	/**
+	 * Streamuje eventy pro session.
+	 * Užitečné pro velké sessions.
+	 */
+	stream(sessionId: SessionId): AsyncIterable<DomainEvent>
+}
+
+/**
+ * Error types pro EventStore
+ */
+export class EventStoreError extends Error {
+	constructor(
+		message: string,
+		public readonly sessionId: SessionId,
+		public readonly cause?: unknown,
+	) {
+		super(message)
+		this.name = 'EventStoreError'
+	}
+}
+
+export class SessionNotFoundError extends EventStoreError {
+	constructor(sessionId: SessionId) {
+		super(`Session not found: ${sessionId}`, sessionId)
+		this.name = 'SessionNotFoundError'
+	}
+}
+
+export class EventAppendError extends EventStoreError {
+	constructor(sessionId: SessionId, cause?: unknown) {
+		super(`Failed to append event to session: ${sessionId}`, sessionId, cause)
+		this.name = 'EventAppendError'
+	}
+}