@roj-ai/sdk 0.1.36 → 0.2.1

package/src/plugins/session-lifecycle/plugin.ts

@@ -12,15 +12,22 @@ import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '~/core/agents/agent-roles.
 import { type DomainError, PresetErrors, SessionErrors, ValidationErrors } from '~/core/errors.js'
 import { definePlugin } from '~/core/plugins/index.js'
 import { knownDefinitionNames, unknownOverrideTargets } from '~/core/preset/overrides.js'
-import { SessionId, sessionIdSchema } from '~/core/sessions/schema.js'
+import { SessionId, sessionIdSchema, sessionMetadataSchema } from '~/core/sessions/schema.js'
 import { agentOverridesSchema, getEntryAgentId, sessionEvents, sessionOverridesPatchSchema } from '~/core/sessions/state.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 
+/** Events returned by `sessions.getEvents` when the caller passes no `limit`. */
+const DEFAULT_EVENT_PAGE_SIZE = 100
+
+/** How far `sessions.getEvents` reads to fill that page when given no `limit`. */
+const DEFAULT_EVENT_READ_WINDOW = 1000
+
 // ============================================================================
 // Presets Plugin — provides presets.list
 // ============================================================================
 
 export const presetsPlugin = definePlugin('presets')
+	.order(20)
 	.managerMethod('list', {
 		input: z4.object({}),
 		output: z4.object({
@@ -111,6 +118,7 @@ export const presetsPlugin = definePlugin('presets')
 // ============================================================================
 
 export const sessionLifecyclePlugin = definePlugin('sessions')
+	.order(10)
 	.managerMethod('create', {
 		input: z4.object({
 			presetId: z4.string().min(1),
@@ -158,7 +166,10 @@ export const sessionLifecyclePlugin = definePlugin('sessions')
 			order: z4.enum(['asc', 'desc']).optional(),
 		}),
 		output: z4.object({
-			sessions: z4.array(z4.unknown()),
+			// The handler returns SessionMetadata[]; z.unknown() used to hide that
+			// from every caller, which is how standalone-server's sessions.list
+			// drifted from the platform contract unnoticed.
+			sessions: z4.array(sessionMetadataSchema),
 			total: z4.number(),
 		}),
 		handler: async (ctx, input) => {
@@ -227,31 +238,30 @@ export const sessionLifecyclePlugin = definePlugin('sessions')
 			const sm = ctx.sessionManager
 			const sessionId = SessionId(input.sessionId)
 
-			const sessionResult = await sm.getSession(sessionId)
-			if (!sessionResult.ok) return sessionResult
-			const session = sessionResult.value
+			return sm.withSessionLease(sessionId, 'manager:sessions.setOverrides', async (session) => {
+				const preset = ctx.presets.get(session.state.presetId)
+				if (!preset) return Err(PresetErrors.notFound(session.state.presetId))
 
-			const preset = ctx.presets.get(session.state.presetId)
-			if (!preset) return Err(PresetErrors.notFound(session.state.presetId))
-
-			const unknown = unknownOverrideTargets(preset, input.overrides)
-			if (unknown.length > 0) {
-				return Err(ValidationErrors.invalid(
-					`Unknown agent definitions in overrides: ${unknown.join(', ')}. Preset '${preset.id}' defines: ${knownDefinitionNames(preset).join(', ')}`,
-				))
-			}
+				const unknown = unknownOverrideTargets(preset, input.overrides)
+				if (unknown.length > 0) {
+					return Err(ValidationErrors.invalid(
+						`Unknown agent definitions in overrides: ${unknown.join(', ')}. Preset '${preset.id}' defines: ${knownDefinitionNames(preset).join(', ')}`,
+					))
+				}
 
-			await session.setOverrides(input.overrides)
+				const setResult = await session.setOverrides(input.overrides)
+				if (!setResult.ok) return setResult
 
-			// Agents already mid-turn finish on the model they started with: the
-			// override is read when the next inference request is built, not applied
-			// retroactively to one in flight.
-			ctx.logger.info('Session overrides set', { sessionId, overrides: input.overrides })
+				// Agents already mid-turn finish on the model they started with: the
+				// override is read when the next inference request is built, not applied
+				// retroactively to one in flight.
+				ctx.logger.info('Session overrides set', { sessionId, overrides: input.overrides })
 
-			const state = session.state
-			return Ok({
-				agents: Object.fromEntries(state.overrides.agents),
-				defaults: state.overrides.defaults,
+				const state = session.state
+				return Ok({
+					agents: Object.fromEntries(state.overrides.agents),
+					defaults: state.overrides.defaults,
+				})
 			})
 		},
 	})
@@ -326,34 +336,39 @@ export const sessionLifecyclePlugin = definePlugin('sessions')
 			lastIndex: z4.number(),
 		}),
 		handler: async (ctx, input) => {
-			// Use loadRange for efficient partial loading
-			const { events: loadedEvents, toIndex } = await ctx.eventStore.loadRange(
+			const limit = input.limit ?? DEFAULT_EVENT_PAGE_SIZE
+			// Offset pagination (only when not using since) slices after the read.
+			const offset = input.since === undefined ? (input.offset ?? 0) : 0
+			// Read past the page: type/agentId filter after the read, so a window
+			// only as wide as the page starves a filtered query. `offset` counts
+			// matches, so it is covered here only when nothing is filtered out.
+			const readLimit = Math.max(input.limit ?? DEFAULT_EVENT_READ_WINDOW, offset + limit)
+
+			const { events: loadedEvents, fromIndex, toIndex } = await ctx.eventStore.loadRange(
 				ctx.sessionId,
 				{
 					since: input.since,
-					limit: input.limit ?? 1000,
+					limit: readLimit,
 				},
 			)
 
-			// Filter by type/agentId
-			let filtered = loadedEvents
-			if (input.type) {
-				filtered = filtered.filter((e) => e.type === input.type)
-			}
-			if (input.agentId) {
-				filtered = filtered.filter(
-					(e) => 'agentId' in e && e.agentId === input.agentId,
+			// Filter by type/agentId, keeping each event's absolute index
+			const matched = loadedEvents
+				.map((event, i) => ({ event, index: fromIndex + i }))
+				.filter(({ event }) =>
+					(!input.type || event.type === input.type)
+					&& (!input.agentId || ('agentId' in event && event.agentId === input.agentId))
 				)
-			}
 
-			// Offset pagination (only when not using since)
-			const offset = input.since === undefined ? (input.offset ?? 0) : 0
-			const paginated = filtered.slice(offset, offset + (input.limit ?? 100))
+			const page = matched.slice(offset, offset + limit)
+			const truncated = matched.length > offset + limit
+			const lastOnPage = page[page.length - 1]
 
 			return Ok({
-				events: paginated,
-				total: filtered.length,
-				lastIndex: toIndex,
+				events: page.map(({ event }) => event),
+				total: matched.length,
+				// A truncated page must not report a cursor past the events it dropped.
+				lastIndex: truncated && lastOnPage !== undefined ? lastOnPage.index : toIndex,
 			})
 		},
 	})

package/src/plugins/session-state/plugin.ts

@@ -1,29 +1,44 @@
 /**
- * Session State Plugin
- *
- * Provides a typed, persistent state object per session that can be updated by:
- * - Agent (via tool)
- * - Client/SPA (via RPC method)
- * - Backend/system (via RPC method with system caller context)
- *
- * State changes are broadcast as notifications and can trigger agent dequeue.
- * A preset-defined validate function controls write permissions per caller.
+ * Typed persistent state shared by agents, clients, and system callers.
  */
 import z from 'zod/v4'
+import { ValidationErrors } from '~/core/errors.js'
+import { createEventsFactory } from '~/core/events/types.js'
 import type { CallerContext } from '~/core/plugins/plugin-builder.js'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
-import { createEventsFactory } from '~/core/events/types.js'
+import { selectPluginState } from '~/core/sessions/reducer.js'
 import { getEntryAgentId } from '~/core/sessions/state.js'
 import { Err, Ok } from '~/lib/utils/result.js'
-import { ValidationErrors } from '~/core/errors.js'
+
+export const DEFAULT_SESSION_STATE_MAX_BYTES = 256 * 1024
+
+const stateRecordSchema = z.record(z.string(), z.unknown())
+
+function isStateRecord(value: unknown): value is Record<string, unknown> {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+	const prototype = Object.getPrototypeOf(value)
+	return prototype === Object.prototype || prototype === null
+}
 
 export const sessionStateEvents = createEventsFactory({
 	events: {
+		// Legacy full snapshots remain readable for existing event logs.
 		session_state_updated: z.object({
-			state: z.record(z.string(), z.unknown()),
+			state: stateRecordSchema,
+			callerSource: z.enum(['agent', 'client', 'system']),
+		}),
+		session_state_patched: z.object({
+			set: stateRecordSchema,
+			deletedKeys: z.array(z.string()),
 			callerSource: z.enum(['agent', 'client', 'system']),
+			externalRevision: z.number().int().nonnegative().optional(),
+		}),
+		session_state_external_consumed: z.object({
+			updates: z.array(z.object({
+				key: z.string(),
+				revision: z.number().int().nonnegative(),
+			})).optional(),
 		}),
-		session_state_external_consumed: z.object({}),
 	},
 })
 
@@ -31,149 +46,288 @@ export interface SessionStatePluginConfig {
 	schema: z.ZodType
 	initial: Record<string, unknown>
 	validate?: (current: Record<string, unknown>, proposed: Record<string, unknown>, caller: CallerContext) => true | string
+	/** Maximum UTF-8 JSON size of the resulting full state. */
+	maxSerializedBytes?: number
+}
+
+interface PendingExternalUpdate {
+	key: string
+	revision: number
 }
 
 interface SessionStatePluginState {
 	state: Record<string, unknown>
-	pendingExternalUpdate: boolean
+	pendingExternalUpdates: Map<string, number>
+	nextExternalRevision: number
+	initialized: boolean
+}
+
+type StateValidationResult =
+	| { ok: true; state: Record<string, unknown> }
+	| { ok: false; message: string }
+
+function validateState(config: SessionStatePluginConfig, input: unknown): StateValidationResult {
+	const configuredResult = config.schema.safeParse(input)
+	if (!configuredResult.success) {
+		return { ok: false, message: `Schema validation failed: ${configuredResult.error.message}` }
+	}
+
+	if (!isStateRecord(configuredResult.data)) {
+		return { ok: false, message: `Schema validation failed: session state must be an object` }
+	}
+
+	let serialized: string
+	try {
+		serialized = JSON.stringify(configuredResult.data, (_key, value: unknown) => {
+			if (value === undefined || typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+				throw new Error(`Unsupported JSON value: ${value === undefined ? 'undefined' : typeof value}`)
+			}
+			if (typeof value === 'number' && !Number.isFinite(value)) {
+				throw new Error('Unsupported JSON value: non-finite number')
+			}
+			return value
+		})
+	} catch (error) {
+		return { ok: false, message: `Session state is not JSON serializable: ${error instanceof Error ? error.message : String(error)}` }
+	}
+
+	const maxBytes = config.maxSerializedBytes ?? DEFAULT_SESSION_STATE_MAX_BYTES
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+		return { ok: false, message: 'Session state byte limit must be a non-negative safe integer' }
+	}
+	const actualBytes = new TextEncoder().encode(serialized).byteLength
+	if (actualBytes > maxBytes) {
+		return { ok: false, message: `Session state exceeds ${maxBytes} byte limit (${actualBytes} bytes)` }
+	}
+
+	const canonical: unknown = JSON.parse(serialized)
+	if (!isStateRecord(canonical)) {
+		return { ok: false, message: 'Session state JSON must decode to an object' }
+	}
+	return { ok: true, state: canonical }
+}
+
+function initializeState(config: SessionStatePluginConfig): SessionStatePluginState {
+	const result = validateState(config, config.initial)
+	if (!result.ok) {
+		throw new Error(`Invalid initial session state: ${result.message}`)
+	}
+	return {
+		state: result.state,
+		pendingExternalUpdates: new Map(),
+		nextExternalRevision: 0,
+		initialized: true,
+	}
+}
+
+function valuesEqual(left: unknown, right: unknown): boolean {
+	if (Object.is(left, right)) return true
+	return JSON.stringify(left) === JSON.stringify(right)
+}
+
+function changedKeys(current: Record<string, unknown>, next: Record<string, unknown>): string[] {
+	const keys = new Set([...Object.keys(current), ...Object.keys(next)])
+	return [...keys].filter((key) => {
+		const currentHasKey = Object.hasOwn(current, key)
+		const nextHasKey = Object.hasOwn(next, key)
+		return currentHasKey !== nextHasKey || !valuesEqual(current[key], next[key])
+	})
+}
+
+function createPatch(current: Record<string, unknown>, next: Record<string, unknown>) {
+	const entries: Array<[string, unknown]> = []
+	const deletedKeys: string[] = []
+	for (const key of changedKeys(current, next)) {
+		if (Object.hasOwn(next, key)) entries.push([key, next[key]])
+		else deletedKeys.push(key)
+	}
+	return { set: Object.fromEntries(entries), deletedKeys }
+}
+
+function applyPatch(
+	state: Record<string, unknown>,
+	patch: { set: Record<string, unknown>; deletedKeys: string[] },
+): Record<string, unknown> {
+	const next = { ...state, ...patch.set }
+	for (const key of patch.deletedKeys) delete next[key]
+	return next
+}
+
+function addPendingUpdates(
+	current: SessionStatePluginState,
+	keys: string[],
+	revision: number,
+): Map<string, number> {
+	const pending = new Map(current.pendingExternalUpdates)
+	for (const key of keys) pending.set(key, revision)
+	return pending
 }
 
 export const sessionStatePlugin = definePlugin('sessionState')
+	.order(140)
 	.pluginConfig<SessionStatePluginConfig>()
 	.isSessionEnabled(({ pluginConfig }) => pluginConfig !== undefined)
 	.events([sessionStateEvents])
 	.state({
 		key: 'sessionState',
-		initial: (): SessionStatePluginState => ({ state: {}, pendingExternalUpdate: false }),
-		reduce: (current, event, _sessionState, pluginConfig) => {
+		initial: (): SessionStatePluginState => ({
+			state: {},
+			pendingExternalUpdates: new Map(),
+			nextExternalRevision: 0,
+			initialized: false,
+		}),
+		reduce: (uninitialized, event, _sessionState, pluginConfig) => {
+			const current = uninitialized.initialized ? uninitialized : initializeState(pluginConfig)
 			switch (event.type) {
-				case 'session_state_updated':
+				case 'session_state_updated': {
+					const keys = changedKeys(current.state, event.state)
+					if (event.callerSource === 'agent' || keys.length === 0) {
+						return { ...current, state: event.state }
+					}
+					const revision = current.nextExternalRevision + 1
 					return {
-						state: event.state as Record<string, unknown>,
-						pendingExternalUpdate: event.callerSource !== 'agent',
+						...current,
+						state: event.state,
+						pendingExternalUpdates: addPendingUpdates(current, keys, revision),
+						nextExternalRevision: revision,
 					}
-				case 'session_state_external_consumed':
-					return { ...current, pendingExternalUpdate: false }
-				default:
-					// Initialize with config defaults if state is empty and config is available
-					if (pluginConfig && Object.keys(current.state).length === 0) {
-						return { ...current, state: (pluginConfig as SessionStatePluginConfig).initial }
+				}
+				case 'session_state_patched': {
+					const state = applyPatch(current.state, event)
+					const keys = [...Object.keys(event.set), ...event.deletedKeys]
+					if (event.callerSource === 'agent' || keys.length === 0) {
+						return { ...current, state }
+					}
+					const revision = event.externalRevision ?? current.nextExternalRevision + 1
+					return {
+						...current,
+						state,
+						pendingExternalUpdates: addPendingUpdates(current, keys, revision),
+						nextExternalRevision: Math.max(current.nextExternalRevision, revision),
+					}
+				}
+				case 'session_state_external_consumed': {
+					if (!event.updates) return { ...current, pendingExternalUpdates: new Map() }
+					const pending = new Map(current.pendingExternalUpdates)
+					for (const update of event.updates) {
+						if (pending.get(update.key) === update.revision) pending.delete(update.key)
 					}
+					return { ...current, pendingExternalUpdates: pending }
+				}
+				default:
 					return current
 			}
 		},
 	})
+	.context(async (ctx) => {
+		const state = selectPluginState<SessionStatePluginState>(ctx.getSessionState(), 'sessionState')
+		let nextExternalRevision = state?.nextExternalRevision ?? 0
+		// `update` reads the committed state, validates a full merge and appends a
+		// patch. Interleaving two of those merges the patches behind the validator,
+		// so concurrent updates could land above the byte cap or break a cross-field
+		// refinement that each of them satisfied on its own.
+		let updateTail: Promise<unknown> = Promise.resolve()
+		return {
+			reserveExternalRevision: () => ++nextExternalRevision,
+			runExclusive: <T>(operation: () => Promise<T>): Promise<T> => {
+				const run = updateTail.then(operation, operation)
+				updateTail = run.then(() => undefined, () => undefined)
+				return run
+			},
+		}
+	})
 	.notification('sessionStateChanged', {
 		schema: z.object({
 			sessionId: z.string(),
-			state: z.record(z.string(), z.unknown()),
+			state: stateRecordSchema,
 		}),
 	})
 	.method('get', {
 		input: z.object({ sessionId: z.string() }),
-		output: z.object({ state: z.record(z.string(), z.unknown()) }),
-		handler: async (ctx) => {
-			const currentState = ctx.pluginState.state
-			const config = ctx.pluginConfig
-			const state = Object.keys(currentState).length === 0 && config ? config.initial : currentState
-			return Ok({ state })
-		},
+		output: z.object({ state: stateRecordSchema }),
+		handler: async (ctx) => Ok({ state: ctx.pluginState.state }),
 	})
 	.method('update', {
 		input: z.object({
 			sessionId: z.string(),
-			updates: z.record(z.string(), z.unknown()),
+			updates: stateRecordSchema,
 		}),
-		output: z.object({ state: z.record(z.string(), z.unknown()) }),
-		handler: async (ctx, input) => {
-			const config = ctx.pluginConfig
-			if (!config) return Err(ValidationErrors.invalid('Session state plugin not configured'))
-
-			const currentState = Object.keys(ctx.pluginState.state).length === 0
-				? config.initial
-				: ctx.pluginState.state
-
-			const proposed = { ...currentState, ...input.updates }
+		output: z.object({ state: stateRecordSchema }),
+		handler: async (ctx, input) => ctx.pluginContext.runExclusive(async () => {
+			// Re-read inside the critical section: `ctx.pluginState` is a snapshot
+			// taken before the handler ran, so an update that committed while this
+			// call waited its turn would otherwise be merged away.
+			const committed = selectPluginState<SessionStatePluginState>(ctx.getSessionState(), 'sessionState')?.state
+				?? ctx.pluginState.state
+			const proposed = { ...committed, ...input.updates }
+			const parsed = validateState(ctx.pluginConfig, proposed)
+			if (!parsed.ok) return Err(ValidationErrors.invalid(parsed.message))
 
-			// Validate against schema
-			const parsed = config.schema.safeParse(proposed)
-			if (!parsed.success) {
-				return Err(ValidationErrors.invalid(`Schema validation failed: ${parsed.error.message}`))
+			if (ctx.pluginConfig.validate) {
+				const result = ctx.pluginConfig.validate(committed, parsed.state, ctx.caller)
+				if (result !== true) return Err(ValidationErrors.invalid(result))
 			}
 
-			// Run custom validate function
-			if (config.validate) {
-				const result = config.validate(currentState, proposed, ctx.caller)
-				if (result !== true) {
-					return Err(ValidationErrors.invalid(result))
-				}
-			}
+			const patch = createPatch(committed, parsed.state)
+			const keys = [...Object.keys(patch.set), ...patch.deletedKeys]
+			if (keys.length === 0) return Ok({ state: parsed.state })
 
-			// Emit event
-			await ctx.emitEvent(sessionStateEvents.create('session_state_updated', {
-				state: proposed,
+			const externalRevision = ctx.caller.source === 'agent'
+				? undefined
+				: ctx.pluginContext.reserveExternalRevision()
+			await ctx.emitEvent(sessionStateEvents.create('session_state_patched', {
+				...patch,
 				callerSource: ctx.caller.source,
+				externalRevision,
 			}))
 
-			// Notify connected clients
 			ctx.notify('sessionStateChanged', {
 				sessionId: String(ctx.sessionId),
-				state: proposed,
+				state: parsed.state,
 			})
 
-			// Schedule agent if external update
 			if (ctx.caller.source !== 'agent') {
 				const entryAgentId = getEntryAgentId(ctx.sessionState)
-				if (entryAgentId) {
-					ctx.scheduleAgent(entryAgentId)
-				}
+				if (entryAgentId) ctx.scheduleAgent(entryAgentId)
 			}
 
-			return Ok({ state: proposed })
-		},
+			return Ok({ state: parsed.state })
+		}),
 	})
 	.tool('update_session_state', {
 		description: 'Update the session state. Use this to signal status changes (e.g., file ready for download, phase transitions).',
 		input: z.object({
-			updates: z.record(z.string(), z.unknown()).describe('Key-value pairs to merge into the current session state'),
+			updates: stateRecordSchema.describe('Key-value pairs to merge into the current session state'),
 		}),
 		execute: async (input, _toolCtx, ctx) => {
 			const result = await ctx.self.update({
 				sessionId: String(ctx.sessionId),
 				updates: input.updates,
 			})
-
-			if (typeof result === 'object' && result !== null && 'ok' in result && !(result as { ok: boolean }).ok) {
-				const err = result as { ok: false; error: { message: string } }
-				return { ok: false, error: { message: err.error.message, recoverable: true } }
+			if (!result.ok) {
+				return { ok: false, error: { message: result.error.message, recoverable: true } }
 			}
-
-			return { ok: true, value: [{ type: 'text' as const, text: 'Session state updated.' }] }
+			return { ok: true, value: [{ type: 'text', text: 'Session state updated.' }] }
 		},
 	})
-	.dequeue({
-		hasPendingMessages: (ctx) => ctx.pluginState.pendingExternalUpdate,
+	.dequeue<PendingExternalUpdate[]>({
+		hasPendingMessages: (ctx) => ctx.pluginState.pendingExternalUpdates.size > 0,
 		getPendingMessages: (ctx) => {
-			if (!ctx.pluginState.pendingExternalUpdate) return null
-			const stateStr = JSON.stringify(ctx.pluginState.state, null, 2)
+			if (ctx.pluginState.pendingExternalUpdates.size === 0) return null
+			const updates = [...ctx.pluginState.pendingExternalUpdates].map(([key, revision]) => ({ key, revision }))
 			return {
 				messages: [{
-					role: 'user' as const,
-					content: `<system>Session state was updated externally. Current state:\n${stateStr}</system>`,
+					role: 'user',
+					content: `<system>Session state was updated externally. Changed keys: ${updates.map((update) => update.key).join(', ')}.</system>`,
 				}],
-				token: true,
+				token: updates,
 			}
 		},
-		markConsumed: async (ctx) => {
-			await ctx.emitEvent(sessionStateEvents.create('session_state_external_consumed', {}))
+		markConsumed: async (ctx, updates) => {
+			await ctx.emitEvent(sessionStateEvents.create('session_state_external_consumed', { updates }))
 		},
 	})
 	.systemPrompt((ctx) => {
-		const config = ctx.pluginConfig
-		if (!config) return null
-		const state = Object.keys(ctx.pluginState.state).length === 0
-			? config.initial
-			: ctx.pluginState.state
-		return `## Session State\n\nCurrent session state:\n\`\`\`json\n${JSON.stringify(state, null, 2)}\n\`\`\`\n\nUse the \`update_session_state\` tool to update state values.`
+		return `## Session State\n\nCurrent session state:\n\`\`\`json\n${JSON.stringify(ctx.pluginState.state, null, 2)}\n\`\`\`\n\nUse the \`update_session_state\` tool to update state values.`
 	})
 	.build()

package/src/plugins/session-stats/plugin.ts

@@ -86,6 +86,7 @@ export function selectSessionStats(sessionState: SessionState): SessionStatsStat
 // ============================================================================
 
 export const sessionStatsPlugin = definePlugin('session-stats')
+	.order(130)
 	.events([agentEvents, llmEvents, toolEvents, contextEvents, userChatEvents])
 	.state({
 		key: PLUGIN_STATE_KEY,