@roj-ai/sdk 0.0.2

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

@@ -0,0 +1,71 @@
+import type { DomainEvent, FactoryEventType } from '~/core/events/types.js'
+import type { SessionId } from '~/core/sessions/schema.js'
+import type { toolEvents } from '~/core/tools/state.js'
+import type { SessionCreatedEvent } from './state.js'
+import { isSessionCreatedEvent } from './state.js'
+
+/**
+ * Rewrite events for a fork: slice to eventIndex (inclusive), rewrite sessionId,
+ * and add forkedFrom to the session_created event.
+ */
+export function rewriteEventsForFork(
+	sourceEvents: DomainEvent[],
+	eventIndex: number,
+	newSessionId: SessionId,
+	sourceSessionId: SessionId,
+): DomainEvent[] {
+	const sliced = sourceEvents.slice(0, eventIndex + 1)
+
+	return sliced.map((event) => {
+		if (isSessionCreatedEvent(event)) {
+			return {
+				...event,
+				sessionId: newSessionId,
+				forkedFrom: { sessionId: sourceSessionId, eventIndex },
+			} satisfies SessionCreatedEvent
+		}
+		return { ...event, sessionId: newSessionId }
+	})
+}
+
+/**
+ * Snapshot refs found at a given event index.
+ */
+export interface SnapshotRefsAtIndex {
+	sessionRef?: string
+	workspaceRef?: string
+}
+
+type SnapshotRefEvent = FactoryEventType<typeof toolEvents>
+
+/**
+ * Scan backwards from eventIndex to find the most recent sessionRef and workspaceRef
+ * from tool_completed or tool_failed events.
+ */
+export function findSnapshotRefsAtIndex(
+	events: DomainEvent[],
+	eventIndex: number,
+): SnapshotRefsAtIndex {
+	let sessionRef: string | undefined
+	let workspaceRef: string | undefined
+
+	for (let i = eventIndex; i >= 0; i--) {
+		const event = events[i] as SnapshotRefEvent
+
+		if (
+			event.type === 'tool_completed'
+			|| event.type === 'tool_failed'
+		) {
+			if (!sessionRef && event.sessionRef) {
+				sessionRef = event.sessionRef
+			}
+			if (!workspaceRef && event.workspaceRef) {
+				workspaceRef = event.workspaceRef
+			}
+
+			if (sessionRef && workspaceRef) break
+		}
+	}
+
+	return { sessionRef, workspaceRef }
+}

package/src/core/sessions/reducer.ts

@@ -0,0 +1,95 @@
+import type { DomainEvent } from '~/core/events/types.js'
+import type { BaseEvent } from '~/core/events/types.js'
+import type { SessionState } from './state.js'
+
+// ============================================================================
+// Session reducer types
+// ============================================================================
+
+export type SessionReducer = (state: SessionState, event: DomainEvent) => SessionState
+
+/**
+ * Structural supertype for any EventsFactory — used to infer event types from factories.
+ */
+type EventSourceRef = {
+	create(type: string, input: unknown): unknown
+	EventType: unknown
+	Events: unknown
+}
+
+// ============================================================================
+// State slice
+// ============================================================================
+
+export interface StateSlice<TKey extends string = string, TState = unknown> {
+	key: TKey
+	initialState: () => TState
+	select: (state: SessionState) => TState
+	reducer: SessionReducer
+}
+
+/**
+ * Create a typed state slice that owns a specific key on SessionState.
+ *
+ * Each slice stores its state under a dynamic key on SessionState.
+ * Use `selectPluginState()` to read plugin state from outside the plugin.
+ *
+ * The `events` field declares which EventsFactory instances this reducer depends on.
+ * The event type for `apply` is inferred from the factories — use a switch on
+ * `event.type` for TypeScript narrowing.
+ */
+export function createStateSlice<TKey extends string, TState, const TFactories extends readonly EventSourceRef[]>(config: {
+	key: TKey
+	events: TFactories
+	initialState: () => TState
+	apply: (state: TState, event: TFactories[number]['EventType'] & BaseEvent<string>, sessionState: SessionState) => TState
+}): StateSlice<TKey, TState> {
+	// Dynamic key access requires Record cast — plugin keys are added via module augmentation
+	// but TypeScript can't correlate the generic TKey with augmented properties
+	const stateRecord = (state: SessionState) => state as unknown as Record<string, unknown>
+	return {
+		key: config.key,
+		initialState: config.initialState,
+		select: (state) => stateRecord(state)[config.key] as TState,
+		reducer: (state, event) => {
+			const record = stateRecord(state)
+			const keyExists = config.key in record
+			const sliceState = keyExists
+				? record[config.key] as TState
+				: config.initialState()
+			const newSliceState = config.apply(sliceState, event as TFactories[number]['EventType'] & BaseEvent<string>, state)
+			// Only skip update when key already exists and value is unchanged
+			if (keyExists && newSliceState === sliceState) return state
+			return { ...state, [config.key]: newSliceState }
+		},
+	}
+}
+
+/**
+ * Create a typed session reducer that narrows DomainEvent to the union of events
+ * from the provided factories. Same casting pattern as createStateSlice.
+ */
+export function createTypedReducer<const TFactories extends readonly EventSourceRef[]>(
+	events: TFactories,
+	apply: (state: SessionState, event: TFactories[number]['EventType'] & BaseEvent<string>) => SessionState,
+): SessionReducer {
+	return (state, event) => apply(state, event as TFactories[number]['EventType'] & BaseEvent<string>)
+}
+
+// ============================================================================
+// Reducer composition
+// ============================================================================
+
+/**
+ * Read a plugin-owned state slice from SessionState by dynamic key.
+ *
+ * Plugin state is stored under dynamic keys (e.g. 'todos', 'workers') that are
+ * not part of the core SessionState interface. This helper performs the same
+ * dynamic record access that createStateSlice uses internally.
+ */
+export function selectPluginState<TState>(state: SessionState, key: string): TState | undefined {
+	const record = state as unknown as Record<string, unknown>
+	return record[key] as TState | undefined
+}
+
+export const composeReducers = (...reducers: SessionReducer[]): SessionReducer => (state, event) => reducers.reduce((s, r) => r(s, event), state)

package/src/core/sessions/schema.ts

@@ -0,0 +1,91 @@
+/**
+ * Session domain types and schemas
+ *
+ * Contains all types related to sessions:
+ * - Branded ID type and constructor
+ * - Session metadata schemas
+ * - Zod schemas for validation
+ */
+
+import { uuidv7 } from 'uuidv7'
+import z from 'zod/v4'
+
+// ============================================================================
+// SessionId - Branded type
+// ============================================================================
+
+/** SessionId schema - validates any string and brands as SessionId. */
+export const sessionIdSchema = z.string().brand('SessionId')
+
+/** Branded SessionId type */
+export type SessionId = z.infer<typeof sessionIdSchema>
+
+/** Constructor for SessionId */
+export const SessionId = (id: string): SessionId => id as SessionId
+
+/** Generate a new SessionId (UUIDv7) */
+export const generateSessionId = (): SessionId => SessionId(uuidv7())
+
+// ============================================================================
+// SessionId - Zod schemas
+// ============================================================================
+
+// ============================================================================
+// Session metadata schemas
+// ============================================================================
+
+export const sessionMetadataMetricsSchema = z.object({
+	totalEvents: z.number().int().min(0),
+	totalAgents: z.number().int().min(0),
+	totalTokens: z.number().int().min(0),
+	totalLLMCalls: z.number().int().min(0),
+	inputTokens: z.number().int().min(0).optional(),
+	outputTokens: z.number().int().min(0).optional(),
+	totalCost: z.number().min(0).optional(),
+	totalMessages: z.number().int().min(0).optional(),
+	totalToolCalls: z.number().int().min(0).optional(),
+})
+
+export const sessionMetadataSchema = z.object({
+	sessionId: sessionIdSchema,
+	presetId: z.string(),
+	createdAt: z.number(),
+	lastActivityAt: z.number(),
+	status: z.enum(['active', 'closed', 'errored']),
+	name: z.string().optional(),
+	tags: z.array(z.string()).optional(),
+	metrics: sessionMetadataMetricsSchema.optional(),
+	custom: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const listSessionsOptionsSchema = z.object({
+	status: z.enum(['active', 'closed', 'errored']).optional(),
+	tags: z.array(z.string()).optional(),
+	limit: z.number().int().min(1).max(100).optional(),
+	offset: z.number().int().min(0).optional(),
+	orderBy: z.enum(['createdAt', 'lastActivityAt']).optional(),
+	order: z.enum(['asc', 'desc']).optional(),
+})
+
+// ============================================================================
+// Type exports (inferred from schemas)
+// ============================================================================
+
+export type SessionMetadata = z.infer<typeof sessionMetadataSchema>
+export type SessionMetadataMetrics = z.infer<typeof sessionMetadataMetricsSchema>
+export type ListSessionsOptions = z.infer<typeof listSessionsOptionsSchema>
+
+// ============================================================================
+// Domain event schema (for loading from file)
+// ============================================================================
+
+export const domainEventSchema = z
+	.object({
+		type: z.string(),
+		sessionId: z.string(),
+		timestamp: z.number(),
+	})
+	.passthrough()
+
+export type DomainEventInput = z.infer<typeof domainEventSchema>
+export type SessionMetadataInput = z.infer<typeof sessionMetadataSchema>

package/src/core/sessions/session-environment.ts

@@ -0,0 +1,12 @@
+/**
+ * Session environment directories.
+ * Shared between agent-server tools and handler contexts.
+ */
+export interface SessionEnvironment {
+	/** Absolute path to the session directory */
+	sessionDir: string
+	/** Absolute path to the workspace directory (optional) */
+	workspaceDir?: string
+	/** When true, agents see virtual paths instead of real filesystem paths */
+	sandboxed: boolean
+}