@roj-ai/sdk 0.1.36 → 0.2.1

package/src/core/llm/openrouter.ts

@@ -18,7 +18,9 @@ import type {
 	ProviderHttpRequest,
 	RawInferenceRequest,
 } from './provider.js'
-import { ProviderMessageValidationError, sanitizeProviderMessages } from './message-sanitization.js'
+import { mapProviderError } from './provider.js'
+import { ProviderRequestAbortError, runProviderRequest } from './provider-request.js'
+import { sanitizeProviderMessages } from './message-sanitization.js'
 
 // ============================================================================
 // Configuration
@@ -213,79 +215,74 @@ export class OpenRouterProvider implements LLMProvider {
 			}
 
 			const httpRequest = await this.buildHttpRequest(rawRequest, context)
-
-			const controller = new AbortController()
-			const timeoutId = setTimeout(() => controller.abort(), this.timeout)
-
-			if (context?.signal) {
-				context.signal.addEventListener('abort', () => controller.abort(), { once: true })
-			}
-
-			let response: Response
-			try {
-				response = await this.fetchFn(httpRequest.url, {
+			return await runProviderRequest({ callerSignal: context?.signal, timeoutMs: this.timeout }, async (signal) => {
+				const response = await this.fetchFn(httpRequest.url, {
 					method: httpRequest.method,
 					headers: {
 						...httpRequest.headers,
 						'Authorization': `Bearer ${this.apiKey}`,
 					},
 					body: JSON.stringify(httpRequest.body),
-					signal: controller.signal,
+					signal,
 				})
-			} finally {
-				clearTimeout(timeoutId)
-			}
 
-			if (!response.ok) {
-				const body = await response.text()
-				return Err(this.mapHttpError(response.status, body))
-			}
+				if (!response.ok) {
+					const body = await response.text()
+					return Err(this.mapHttpError(response.status, body))
+				}
 
-			const data = await response.json() as OpenRouterResponse
-			const latencyMs = Date.now() - startTime
+				const data = await response.json() as OpenRouterResponse
+				const latencyMs = Date.now() - startTime
 
-			const choice = data.choices[0]
-			if (!choice) {
-				return Err({ type: 'server_error', message: 'No choices returned from LLM' })
-			}
+				const choice = data.choices[0]
+				if (!choice) {
+					return Err({ type: 'server_error', message: 'No choices returned from LLM' })
+				}
 
-			const toolCalls: ToolCall[] = (choice.message.tool_calls ?? []).map(
-				(tc) => ({
-					id: ToolCallId(tc.id),
-					name: tc.function.name,
-					input: this.parseToolArguments(tc.function.arguments),
-				}),
-			)
-
-			const promptTokens = data.usage?.prompt_tokens ?? 0
-			const completionTokens = data.usage?.completion_tokens ?? 0
-			const cost = data.usage?.cost
-
-			const metrics: LLMMetrics = {
-				promptTokens,
-				completionTokens,
-				totalTokens: data.usage?.total_tokens ?? 0,
-				latencyMs,
-				model: data.model,
-				provider: this.name,
-				cost,
-				cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens || undefined,
-				cacheWriteTokens: data.usage?.prompt_tokens_details?.cache_write_tokens || undefined,
-				reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens || undefined,
-			}
+				const toolCalls: ToolCall[] = (choice.message.tool_calls ?? []).map(
+					(tc) => ({
+						id: ToolCallId(tc.id),
+						name: tc.function.name,
+						input: this.parseToolArguments(tc.function.arguments),
+					}),
+				)
+
+				const promptTokens = data.usage?.prompt_tokens ?? 0
+				const completionTokens = data.usage?.completion_tokens ?? 0
+				const cost = data.usage?.cost
+
+				const metrics: LLMMetrics = {
+					promptTokens,
+					completionTokens,
+					totalTokens: data.usage?.total_tokens ?? 0,
+					latencyMs,
+					model: data.model,
+					provider: this.name,
+					cost,
+					cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens || undefined,
+					cacheWriteTokens: data.usage?.prompt_tokens_details?.cache_write_tokens || undefined,
+					reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens || undefined,
+				}
 
-			return Ok({
-				content: this.extractContent(choice.message.content),
-				toolCalls,
-				finishReason: this.mapFinishReason(choice.finish_reason),
-				metrics,
-				providerRequestId: data.id,
-				reasoning: choice.message.reasoning || undefined,
-				// Normalized to undefined here so an empty array never reaches the wire on the way back.
-				reasoningDetails: choice.message.reasoning_details?.length ? choice.message.reasoning_details : undefined,
+				return Ok({
+					content: this.extractContent(choice.message.content),
+					toolCalls,
+					finishReason: this.mapFinishReason(choice.finish_reason),
+					metrics,
+					providerRequestId: data.id,
+					reasoning: choice.message.reasoning || undefined,
+					// Normalized to undefined here so an empty array never reaches the wire on the way back.
+					reasoningDetails: choice.message.reasoning_details?.length ? choice.message.reasoning_details : undefined,
+				})
 			})
 		} catch (error) {
-			return Err(this.mapError(error))
+			if (error instanceof ProviderRequestAbortError) {
+				return Err({
+					type: error.abortCause === 'caller' ? 'aborted' : 'timeout',
+					message: error.message,
+				})
+			}
+			return Err(mapProviderError(error))
 		}
 	}
 
@@ -484,16 +481,4 @@ export class OpenRouterProvider implements LLMProvider {
 		return { type: 'server_error', message, statusCode: status, responseBody: body }
 	}
 
-	private mapError(err: unknown): LLMError {
-		if (err instanceof ProviderMessageValidationError) {
-			return { type: 'invalid_request', message: err.message }
-		}
-		if (err instanceof Error && err.name === 'AbortError') {
-			return { type: 'aborted', message: 'Request was aborted' }
-		}
-		if (err instanceof TypeError && (err.message.includes('fetch') || err.message.includes('network'))) {
-			return { type: 'network_error', message: err.message, cause: err }
-		}
-		return { type: 'network_error', message: err instanceof Error ? err.message : String(err), cause: err }
-	}
 }

package/src/core/llm/provider-request.ts

@@ -0,0 +1,40 @@
+export type ProviderRequestAbortCause = 'caller' | 'timeout'
+
+export class ProviderRequestAbortError extends Error {
+	constructor(readonly abortCause: ProviderRequestAbortCause) {
+		super(abortCause === 'caller' ? 'Request was aborted' : 'Request timed out')
+		this.name = 'ProviderRequestAbortError'
+	}
+}
+
+export async function runProviderRequest<T>(
+	options: { callerSignal?: AbortSignal; timeoutMs: number },
+	run: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+	if (options.callerSignal?.aborted) throw new ProviderRequestAbortError('caller')
+
+	const controller = new AbortController()
+	let abortCause: ProviderRequestAbortCause | undefined
+	const abort = (cause: ProviderRequestAbortCause) => {
+		if (abortCause) return
+		abortCause = cause
+		controller.abort()
+	}
+	const abortFromCaller = () => abort('caller')
+	const timeoutId = setTimeout(() => abort('timeout'), options.timeoutMs)
+	options.callerSignal?.addEventListener('abort', abortFromCaller, {
+		once: true,
+	})
+
+	try {
+		const response = await run(controller.signal)
+		if (abortCause) throw new ProviderRequestAbortError(abortCause)
+		return response
+	} catch (error) {
+		if (abortCause) throw new ProviderRequestAbortError(abortCause)
+		throw error
+	} finally {
+		clearTimeout(timeoutId)
+		options.callerSignal?.removeEventListener('abort', abortFromCaller)
+	}
+}

package/src/core/llm/provider.ts

@@ -13,6 +13,7 @@ import type { ToolResultContent } from '~/core/llm/llm-log-types.js'
 import type { ToolDefinition } from '~/core/tools/definition.js'
 import type { ToolCallId } from '~/core/tools/schema.js'
 import type { Result } from '~/lib/utils/result.js'
+import { ProviderMessageValidationError } from './message-sanitization.js'
 import { ModelId } from './schema.js'
 
 // Re-export LLMMessage types from agents/state for backwards compatibility
@@ -281,3 +282,30 @@ export const LLMMessageFactory = {
 
 	system: (content: string): SystemLLMMessage => ({ role: 'system', content }),
 }
+
+// ============================================================================
+// Error mapping
+// ============================================================================
+
+/**
+ * Maps a thrown provider error onto an LLMError.
+ *
+ * `timedOut` distinguishes our own request timeout from a caller-initiated
+ * cancel: both abort the same controller and surface as an indistinguishable
+ * AbortError, but only the timeout is retryable. Mapping a timeout to 'aborted'
+ * makes Agent.runInference bail silently and leave the agent stuck 'inferring'.
+ */
+export function mapProviderError(err: unknown, opts?: { timedOut?: boolean }): LLMError {
+	if (err instanceof ProviderMessageValidationError) {
+		return { type: 'invalid_request', message: err.message }
+	}
+	if (err instanceof Error && err.name === 'AbortError') {
+		return opts?.timedOut
+			? { type: 'timeout', message: 'Request timed out', cause: err }
+			: { type: 'aborted', message: 'Request was aborted' }
+	}
+	if (err instanceof TypeError && (err.message.includes('fetch') || err.message.includes('network'))) {
+		return { type: 'network_error', message: err.message, cause: err }
+	}
+	return { type: 'network_error', message: err instanceof Error ? err.message : String(err), cause: err }
+}

package/src/core/plugins/plugin-builder.ts

@@ -60,7 +60,7 @@ type ManagerMethodEntry = { input: unknown; output: unknown }
 
 /**
  * Notification entry — registered via .notification() on PluginBuilder.
- * Schema is stored for documentation/validation but not enforced at runtime.
+ * The schema is enforced at runtime: see `guardNotify`.
  */
 type NotificationEntry = { schema: z4.ZodType }
 
@@ -129,6 +129,10 @@ export type DepsFromPlugins<TPlugins extends readonly PluginDefinition<string, a
  * - 'agent': called via agent tool (ctx.self)
  * - 'client': called via SPA RPC (user-initiated)
  * - 'system': called via backend/webhook (trusted)
+ *
+ * `beforeMethod` gates branch on this, so it is an authority claim, not an input:
+ * a host must stamp it from what it authenticated and must never take it from a
+ * request body an untrusted caller can write.
  */
 export type CallerContext = {
 	source: 'agent' | 'client' | 'system'
@@ -238,9 +242,27 @@ type HookMap<TCtx> = {
 	onPause: (ctx: TCtx & { reason?: string }) => Promise<OnPauseResult>
 }
 
+/**
+ * Why a resident session runtime is being closed.
+ *
+ * `evicted` parks an idle runtime that will be rebuilt on the next access, so
+ * close hooks must keep anything the session still needs; `closed` and
+ * `shutdown` end it for good.
+ */
+export type SessionCloseReason = 'closed' | 'evicted' | 'shutdown'
+
 type SessionHookMap<TCtx> = {
+	/**
+	 * Runs once per resident runtime lifetime, not once per session — an evicted
+	 * runtime is rebuilt from its event log and runs this hook again.
+	 */
 	onSessionReady: (ctx: TCtx) => Promise<void>
-	onSessionClose: (ctx: TCtx) => Promise<void>
+	/**
+	 * Runs once per resident runtime lifetime, not once per session — an idle
+	 * eviction runs it too, and the next access runs `onSessionReady` again.
+	 * Check `reason` before destroying anything the session still needs.
+	 */
+	onSessionClose: (ctx: TCtx & { reason: SessionCloseReason }) => Promise<void>
 	beforeMethod: (ctx: TCtx & { method: string; input: unknown; agentId?: AgentId }) => Promise<BeforeMethodResult>
 }
 
@@ -316,8 +338,10 @@ type ErasedAgentHookMap = {
  * Session-level hook map with proper return types but erased context.
  */
 type ErasedSessionHookMap = {
+	/** Fires once per resident runtime lifetime — a rebuilt runtime runs it again. */
 	onSessionReady: (ctx: BaseSessionHookContext) => Promise<void>
-	onSessionClose: (ctx: BaseSessionHookContext) => Promise<void>
+	/** Fires once per resident runtime lifetime — `reason` says whether the session ends or is only parked. */
+	onSessionClose: (ctx: BaseSessionHookContext & { reason: SessionCloseReason }) => Promise<void>
 	beforeMethod: (ctx: BaseSessionHookContext & { method: string; input: unknown; agentId?: AgentId }) => Promise<BeforeMethodResult>
 }
 
@@ -329,8 +353,16 @@ type ErasedSessionHookMap = {
  * ConfiguredPlugin — runtime-ready plugin instance with config bound.
  * This is the shape that session/runtime code consumes.
  */
+/**
+ * Hook precedence for a plugin that declares none. Sorts after every built-in,
+ * so preset and third-party plugins keep running in registration order.
+ */
+export const DEFAULT_PLUGIN_ORDER = 1000
+
 export interface ConfiguredPlugin {
 	name: string
+	/** Hook precedence — see PluginBuilder.order(). Absent means DEFAULT_PLUGIN_ORDER. */
+	order?: number
 	methods: Record<string, {
 		input: z4.ZodType
 		output: z4.ZodType
@@ -391,6 +423,8 @@ export interface PluginDefinition<
 	TMethods extends Record<string, MethodEntry> = {},
 > {
 	name: TName
+	/** Hook precedence — see PluginBuilder.order(). Absent means DEFAULT_PLUGIN_ORDER. */
+	order?: number
 	create(...args: TConfig extends void ? [] : [config: TConfig]): ConfiguredPlugin
 	configure(...args: TConfig extends void ? [] : [config: TConfig]): SessionPluginConfig<TName, TConfig>
 	configureAgent(...args: TAgentConfig extends void ? [] : [config: TAgentConfig]): AgentPluginConfig<TName, TAgentConfig>
@@ -420,6 +454,8 @@ interface StaticToolSpec {
 
 interface BuilderConfig {
 	name: string
+	/** Hook precedence — see PluginBuilder.order(). */
+	order: number | undefined
 	events: readonly EventSourceRef[]
 	/** Names of dependency plugins — stored for runtime wiring */
 	dependencyNames: string[]
@@ -481,6 +517,7 @@ export class PluginBuilder<
 		this._name = name
 		this._cfg = cfg ?? {
 			name,
+			order: undefined,
 			events: [],
 			dependencyNames: [],
 			stateConfig: undefined,
@@ -503,6 +540,16 @@ export class PluginBuilder<
 
 	// --- Setup ---
 
+	/**
+	 * Declare where this plugin sits in hook order. Lower runs first, which for the
+	 * agent hooks — first non-null result wins — decides who gets to act. Built-ins
+	 * occupy 10…150; anything without an order runs after them, in registration order.
+	 */
+	order(value: number): this {
+		this._cfg.order = value
+		return this
+	}
+
 	pluginConfig<T>(): PluginBuilder<TName, T, TContext, TState, TMethods, TManagerMethods, TAgentConfig, TFactories, TNotifications, TDeps> {
 		return this as unknown as PluginBuilder<TName, T, TContext, TState, TMethods, TManagerMethods, TAgentConfig, TFactories, TNotifications, TDeps>
 	}
@@ -713,6 +760,16 @@ export class PluginBuilder<
 		return this
 	}
 
+	/**
+	 * Register a session-level hook.
+	 *
+	 * `onSessionReady` and `onSessionClose` bracket one *resident runtime*, not
+	 * one session: an idle runtime is evicted (close hook runs with
+	 * `reason: 'evicted'`) and rebuilt from the event log on the next access,
+	 * which runs `onSessionReady` again. Only `reason: 'closed'` / `'shutdown'`
+	 * mean the session is really over — anything destructive belongs behind that
+	 * check.
+	 */
 	sessionHook<TName extends keyof SessionHookMap<PluginSessionHookContext<TConfig, TMethods, TContext, TState, TNotifications, TDeps>>>(
 		name: TName,
 		fn: SessionHookMap<PluginSessionHookContext<TConfig, TMethods, TContext, TState, TNotifications, TDeps>>[TName],
@@ -789,6 +846,7 @@ export class PluginBuilder<
 
 		const def: PluginDefinition<TName, TConfig, TAgentConfig, TManagerMethods, TMethods> = {
 			name,
+			order: cfg.order,
 			create: ((...args: unknown[]) => {
 				const pluginConfig = args[0]
 				return buildConfiguredPlugin(cfg, pluginConfig)
@@ -813,7 +871,40 @@ export class PluginBuilder<
 // Build configured plugin — binds config into all closures
 // ============================================================================
 
+type NotifyFn = (type: string, payload: unknown) => void
+
+/**
+ * Hold `ctx.notify` to the contract the plugin declared with `.notification()`:
+ * an undeclared type or a payload that fails its schema is logged and dropped
+ * rather than broadcast, so clients never see a shape nothing promised.
+ */
+function guardNotify(
+	pluginName: string,
+	notifications: Record<string, { schema: z4.ZodType }>,
+	ctx: { notify: NotifyFn; logger: Logger },
+): NotifyFn {
+	return (type, payload) => {
+		const declared = notifications[type]
+		if (!declared) {
+			ctx.logger.error(`Plugin "${pluginName}" emitted undeclared notification "${type}"`)
+			return
+		}
+
+		const parsed = declared.schema.safeParse(payload)
+		if (!parsed.success) {
+			ctx.logger.error(`Plugin "${pluginName}" notification "${type}" does not match its declared schema`, undefined, {
+				issues: parsed.error.message,
+			})
+			return
+		}
+
+		ctx.notify(type, payload)
+	}
+}
+
 function buildConfiguredPlugin(cfg: BuilderConfig, pluginConfig: unknown): ConfiguredPlugin {
+	const notifyFor = (ctx: { notify: NotifyFn; logger: Logger }): NotifyFn => guardNotify(cfg.name, cfg.notifications, ctx)
+
 	let slice: StateSlice | undefined
 	if (cfg.stateConfig) {
 		const stateReduce = cfg.stateConfig.reduce
@@ -832,7 +923,7 @@ function buildConfiguredPlugin(cfg: BuilderConfig, pluginConfig: unknown): Confi
 				name,
 				// Agent.ts provides the full context with extra fields (pendingMessages, turnNumber, etc.)
 				// — this wrapper just injects pluginConfig at the boundary
-				(ctx: BasePluginHookContext) => fn({ ...ctx, pluginConfig }),
+				(ctx: BasePluginHookContext) => fn({ ...ctx, pluginConfig, notify: notifyFor(ctx) }),
 			]),
 		) as Partial<ErasedAgentHookMap>
 		: undefined
@@ -844,7 +935,7 @@ function buildConfiguredPlugin(cfg: BuilderConfig, pluginConfig: unknown): Confi
 				name,
 				// Session.ts provides the full context with extra fields (method, input,
 				// agentId for beforeMethod) — this wrapper just injects pluginConfig.
-				(ctx: BaseSessionHookContext) => fn({ ...ctx, pluginConfig }),
+				(ctx: BaseSessionHookContext) => fn({ ...ctx, pluginConfig, notify: notifyFor(ctx) }),
 			]),
 		) as Partial<ErasedSessionHookMap>
 		: undefined
@@ -855,7 +946,7 @@ function buildConfiguredPlugin(cfg: BuilderConfig, pluginConfig: unknown): Confi
 	let getTools: ((ctx: BasePluginHookContext) => ToolDefinition<any>[]) | undefined
 	if (staticToolSpecs.length > 0 || dynamicToolsFn) {
 		getTools = (ctx: BasePluginHookContext) => {
-			const enrichedCtx: BasePluginHookContext = { ...ctx, pluginConfig }
+			const enrichedCtx: BasePluginHookContext = { ...ctx, pluginConfig, notify: notifyFor(ctx) }
 			const tools: ToolDefinition<any>[] = []
 			// Static tools — create ToolDefinition from StaticToolSpec using closure
 			for (const spec of staticToolSpecs) {
@@ -877,32 +968,32 @@ function buildConfiguredPlugin(cfg: BuilderConfig, pluginConfig: unknown): Confi
 	// Wrap createContext to pass pluginConfig
 	const contextFactory = cfg.contextFactory
 	const wrappedContextFactory = contextFactory
-		? (ctx: SessionContext) => contextFactory(ctx, pluginConfig)
+		? (ctx: SessionContext) => contextFactory({ ...ctx, notify: notifyFor(ctx) }, pluginConfig)
 		: undefined
 
 	// Wrap status/systemPrompt/dequeue to inject pluginConfig
 	const statusFn = cfg.statusFn
 	const wrappedStatus = statusFn
-		? (ctx: BasePluginHookContext) => statusFn({ ...ctx, pluginConfig })
+		? (ctx: BasePluginHookContext) => statusFn({ ...ctx, pluginConfig, notify: notifyFor(ctx) })
 		: undefined
 
 	const systemPromptFn = cfg.systemPromptFn
 	const wrappedSystemPrompt = systemPromptFn
-		? (ctx: BasePluginHookContext) => systemPromptFn({ ...ctx, pluginConfig })
+		? (ctx: BasePluginHookContext) => systemPromptFn({ ...ctx, pluginConfig, notify: notifyFor(ctx) })
 		: undefined
 
 	const dequeueHook = cfg.dequeueHook
 	const wrappedDequeue = dequeueHook
 		? {
-			hasPendingMessages: (ctx: BasePluginHookContext) => dequeueHook.hasPendingMessages({ ...ctx, pluginConfig }),
-			getPendingMessages: (ctx: BasePluginHookContext) => dequeueHook.getPendingMessages({ ...ctx, pluginConfig }),
-			markConsumed: (ctx: BasePluginHookContext, token: unknown) => dequeueHook.markConsumed({ ...ctx, pluginConfig }, token),
+			hasPendingMessages: (ctx: BasePluginHookContext) => dequeueHook.hasPendingMessages({ ...ctx, pluginConfig, notify: notifyFor(ctx) }),
+			getPendingMessages: (ctx: BasePluginHookContext) => dequeueHook.getPendingMessages({ ...ctx, pluginConfig, notify: notifyFor(ctx) }),
+			markConsumed: (ctx: BasePluginHookContext, token: unknown) => dequeueHook.markConsumed({ ...ctx, pluginConfig, notify: notifyFor(ctx) }, token),
 		}
 		: undefined
 
 	const beforeDequeueFn = cfg.beforeDequeueFn
 	const wrappedBeforeDequeue = beforeDequeueFn
-		? (ctx: BasePluginHookContext & { sourcePlugin: string }) => beforeDequeueFn({ ...ctx, pluginConfig })
+		? (ctx: BasePluginHookContext & { sourcePlugin: string }) => beforeDequeueFn({ ...ctx, pluginConfig, notify: notifyFor(ctx) })
 		: undefined
 
 	// Wrap isEnabled to pass pluginConfig
@@ -925,12 +1016,13 @@ function buildConfiguredPlugin(cfg: BuilderConfig, pluginConfig: unknown): Confi
 		wrappedMethods[name] = {
 			input: method.input,
 			output: method.output,
-			handler: (ctx, input) => method.handler({ ...ctx, pluginConfig }, input),
+			handler: (ctx, input) => method.handler({ ...ctx, pluginConfig, notify: notifyFor(ctx) }, input),
 		}
 	}
 
 	return {
 		name: cfg.name,
+		order: cfg.order,
 		methods: wrappedMethods,
 		notifications: cfg.notifications,
 		dependencyNames: cfg.dependencyNames,

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

@@ -9,6 +9,7 @@
 
 import type { Preset } from '~/core/preset/index.js'
 import type { AgentDefinition, AnyAgentDefinition, BaseAgentConfig, OrchestratorConfig } from '../agents/config.js'
+import { childAgentRefs } from '../agents/config.js'
 
 // ============================================================================
 // Helper types
@@ -23,7 +24,7 @@ interface ObjectRefs {
  * `agents: string[]` → `agents: AnyAgentDefinition[]`
  */
 type WithObjectRefs<T> =
-	& Omit<T, 'spawnableAgents' | 'agents'>
+	& Omit<T, 'spawnableAgents' | 'agents' | typeof childAgentRefs>
 	& ObjectRefs
 
 // ============================================================================
@@ -40,39 +41,28 @@ export type CreateOrchestratorInput = WithObjectRefs<BaseAgentConfig>
 export type CreatePresetInput = Omit<Preset, 'agents'>
 
 // ============================================================================
-// Internal: ref storage & resolution
+// Internal: ref 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[]
+	readonly [childAgentRefs]: readonly AnyAgentDefinition[]
 }
 
 function resolveRefs(refs: ObjectRefs): ResolvedRefs {
+	const agents = refs.agents ?? []
 	return {
-		agents: (refs.agents ?? []).map((a) => a.name),
+		agents: agents.map((a) => a.name),
+		[childAgentRefs]: agents,
 	}
 }
 
 /** Recursively collect agents from a config node */
-export function collectFromTree(root: object): { agents: AnyAgentDefinition[] } {
+export function collectFromTree(root: BaseAgentConfig): { 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 ?? []) {
+	function visit(node: BaseAgentConfig) {
+		for (const agent of node[childAgentRefs] ?? []) {
 			if (!agents.has(agent)) {
 				agents.add(agent)
 				visit(agent)
@@ -96,7 +86,7 @@ export function collectFromTree(root: object): { agents: AnyAgentDefinition[] }
  */
 export function defineAgent<TInput = unknown>(input: DefineAgentInput<TInput>): AgentDefinition<TInput> {
 	const { agents, ...rest } = input
-	return resolveAndStore({ agents }, { ...rest, ...resolveRefs({ agents }) })
+	return { ...rest, ...resolveRefs({ agents }) }
 }
 
 /**
@@ -107,5 +97,5 @@ export function defineAgent<TInput = unknown>(input: DefineAgentInput<TInput>):
  */
 export function createOrchestrator(input: CreateOrchestratorInput): OrchestratorConfig {
 	const { agents, ...rest } = input
-	return resolveAndStore({ agents }, { ...rest, ...resolveRefs({ agents }) })
+	return { ...rest, ...resolveRefs({ agents }) }
 }

package/src/core/sessions/context.ts

@@ -7,12 +7,15 @@ import type { Platform } from '~/platform/index.js'
 import type { FileStore } from '../file-store/types.js'
 import type { SessionId } from './schema.js'
 import type { SessionEnvironment } from './session-environment.js'
+import type { SessionRuntimeActivity } from './runtime-activity.js'
 import type { SessionState } from './state.js'
 
 export type SessionContext<TSessionInput = unknown> = {
 	readonly sessionId: SessionId
 	/** The full session state (readonly) */
 	readonly sessionState: SessionState
+	/** Read current session state after the hook snapshot was created. */
+	readonly getSessionState: () => SessionState
 	/** The typed input if agent has inputSchema, otherwise the task string */
 	readonly sessionInput: TSessionInput
 	/** Session environment directories */
@@ -29,8 +32,23 @@ export type SessionContext<TSessionInput = unknown> = {
 	readonly platform: Platform
 
 	readonly logger: Logger
+	/** Keeps the resident session runtime alive while asynchronous work is pending. */
+	readonly runtimeActivity: SessionRuntimeActivity
+	/**
+	 * Reserve the next value of a named per-session counter, synchronously.
+	 *
+	 * `seed` supplies the starting value and runs at most once per resident
+	 * runtime, on the first reservation after the runtime is built. Deriving the
+	 * seed from replayed state is what stops an evicted-and-rebuilt runtime from
+	 * restarting the counter and minting ids that collide with the log.
+	 */
+	readonly reserveSequence: (name: string, seed: () => number) => number
+	/** Reserve the next live-runtime mailbox sequence synchronously. */
+	readonly reserveMailboxMessageSequence: () => number
 
 	emitEvent: (event: Omit<BaseEvent<string>, 'sessionId'>) => Promise<void>
+	/** Atomically persist and apply related domain events. */
+	emitEvents: (events: Array<Omit<BaseEvent<string>, 'sessionId'>>) => Promise<void>
 	/** Send a notification to connected clients via transport (ephemeral, not persisted) */
 	notify: (type: string, payload: unknown) => void
 }