@roj-ai/sdk 0.1.35 → 0.2.1

package/src/core/llm/openrouter.ts

@@ -1,4 +1,4 @@
-import type { ToolCall } from '~/core/agents/state.js'
+import type { ReasoningDetails, ToolCall } from '~/core/agents/state.js'
 import type { ImageProcessor } from '~/core/image/types.js'
 import type { ChatMessageContentItem } from '~/core/llm/llm-log-types.js'
 import { ToolCallId } from '~/core/tools/schema.js'
@@ -14,10 +14,13 @@ import type {
 	LLMMetrics,
 	LLMProvider,
 	OpenRouterProviderRouting,
+	OpenRouterReasoningOptions,
 	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
@@ -52,6 +55,9 @@ interface OpenRouterChoice {
 	message: {
 		content: string | null | Array<{ type: string; text?: string }>
 		tool_calls?: OpenRouterToolCall[]
+		/** Plaintext chain of thought, when the model exposes one. Display only — the round trip goes through reasoning_details. */
+		reasoning?: string
+		reasoning_details?: ReasoningDetails
 	}
 	finish_reason: string | null
 }
@@ -107,6 +113,7 @@ interface OpenRouterMessage {
 	content: string | OpenRouterContentItem[]
 	tool_calls?: OpenRouterToolCall[]
 	tool_call_id?: string
+	reasoning_details?: ReasoningDetails
 }
 
 /**
@@ -160,6 +167,8 @@ interface OpenRouterRequestBody {
 	stream_options: { include_usage: true }
 	/** Provider routing preferences */
 	provider?: OpenRouterProviderRouting
+	/** Reasoning budget */
+	reasoning?: OpenRouterReasoningOptions
 	/** Routing strategy */
 	route?: 'fallback'
 	/** Model transforms */
@@ -206,76 +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,
+				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))
 		}
 	}
 
@@ -317,6 +324,9 @@ export class OpenRouterProvider implements LLMProvider {
 			if (orOpts.providers) {
 				body.provider = orOpts.providers
 			}
+			if (orOpts.reasoning) {
+				body.reasoning = orOpts.reasoning
+			}
 			if (orOpts.route) {
 				body.route = orOpts.route
 			}
@@ -366,19 +376,22 @@ export class OpenRouterProvider implements LLMProvider {
 					tool_call_id: msg.toolCallId,
 				}
 			}
-			case 'assistant':
+			case 'assistant': {
+				const mapped: OpenRouterMessage = { role: 'assistant', content: msg.content }
 				if (msg.toolCalls?.length) {
-					return {
-						role: 'assistant',
-						content: msg.content,
-						tool_calls: msg.toolCalls.map((tc): OpenRouterToolCall => ({
-							id: tc.id,
-							type: 'function',
-							function: { name: tc.name, arguments: JSON.stringify(tc.input) },
-						})),
-					}
+					mapped.tool_calls = msg.toolCalls.map((tc): OpenRouterToolCall => ({
+						id: tc.id,
+						type: 'function',
+						function: { name: tc.name, arguments: JSON.stringify(tc.input) },
+					}))
+				}
+				// Echoed verbatim and only when present: the provider rejects an edited or reordered
+				// sequence, and adding the key for a non-reasoning model would rewrite the cached prefix.
+				if (msg.reasoningDetails?.length) {
+					mapped.reasoning_details = msg.reasoningDetails
 				}
-				return { role: 'assistant', content: msg.content }
+				return mapped
+			}
 			case 'system':
 				return { role: 'system', content: msg.content }
 			case 'user':
@@ -468,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

@@ -1,13 +1,23 @@
-import type { AssistantLLMMessage, LLMMessage, SystemLLMMessage, ToolCall, ToolLLMMessage, UserLLMMessage } from '~/core/agents/state.js'
+import type {
+	AssistantLLMMessage,
+	LLMMessage,
+	ReasoningDetails,
+	SystemLLMMessage,
+	ThinkingBlocks,
+	ToolCall,
+	ToolLLMMessage,
+	UserLLMMessage,
+} from '~/core/agents/state.js'
 import type { FileStore } from '~/core/file-store/types.js'
 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
-export type { AssistantLLMMessage, LLMMessage, SystemLLMMessage, ToolCall, ToolLLMMessage, UserLLMMessage }
+export type { AssistantLLMMessage, LLMMessage, ReasoningDetails, SystemLLMMessage, ThinkingBlocks, ToolCall, ToolLLMMessage, UserLLMMessage }
 
 // ============================================================================
 // Request types
@@ -41,9 +51,37 @@ export interface OpenRouterProviderRouting {
 	quantizations?: string[]
 }
 
+/**
+ * Reasoning controls.
+ *
+ * Without these the model's own default applies, and several of the defaults are expensive:
+ * `high` on Claude Sonnet 5, Opus 5 and Grok 4.5, `max` on Kimi K3. Reasoning is also
+ * `mandatory` on Gemini 3.6 Flash, Grok 4.5 and Kimi K2.7 Code — those cannot be turned off,
+ * only turned down.
+ *
+ * **Which efforts a model accepts differs per model.** The catalog's
+ * `reasoning.supported_efforts` is the authority: Kimi K3 has no `medium`, `minimal` exists
+ * only on Gemini, `xhigh`/`none` only on the OpenAI and newer Anthropic models. The union here
+ * is every value seen across them, not a set any single model takes.
+ *
+ * @see https://openrouter.ai/docs/use-cases/reasoning-tokens
+ */
+export interface OpenRouterReasoningOptions {
+	/** Relative budget. Mutually exclusive with `max_tokens` — set one. */
+	effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+	/** Absolute token budget, for models that take one instead of an effort. */
+	max_tokens?: number
+	/** Explicitly enable reasoning at the model's default effort. */
+	enabled?: boolean
+	/** Reason, but omit the blocks from the response. Note this breaks the round trip. */
+	exclude?: boolean
+}
+
 export interface OpenRouterRequestOptions {
 	/** Provider routing preferences */
 	providers?: OpenRouterProviderRouting
+	/** Reasoning budget. Omitted: the model's own default, which is often `high`. */
+	reasoning?: OpenRouterReasoningOptions
 	/** Routing strategy */
 	route?: 'fallback'
 	/** Model transforms */
@@ -141,8 +179,12 @@ export interface InferenceResponse {
 	metrics: LLMMetrics
 	/** Provider-specific request ID (e.g., OpenRouter generation ID for fetching stats) */
 	providerRequestId?: string
-	/** Extended thinking / reasoning content (for models that support it) */
+	/** Extended thinking / reasoning content (for models that support it) — human-readable, for logs and the debug UI. */
 	reasoning?: string
+	/** Opaque reasoning blocks to echo back on the next request. Absent for models that do not reason. */
+	reasoningDetails?: ReasoningDetails
+	/** Anthropic thinking blocks to replay on the next request. Absent unless extended thinking is enabled. */
+	thinkingBlocks?: ThinkingBlocks
 }
 
 /**
@@ -240,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/llm/state.ts

@@ -48,6 +48,9 @@ export type LLMMetrics = {
 // LLM events
 // ============================================================================
 
+/** Opaque by design — provider chain-of-thought blocks are stored and echoed verbatim, never inspected. */
+const opaqueBlocksSchema = z4.array(z4.unknown())
+
 const llmMetricsSchema = z4.object({
 	promptTokens: z4.number(),
 	completionTokens: z4.number(),
@@ -77,6 +80,15 @@ export const llmEvents = createEventsFactory({
 					name: z4.string(),
 					input: z4.unknown(),
 				})),
+				/**
+				 * Opaque provider reasoning blocks (see ReasoningDetails). Carried by the
+				 * event, not just by the live response, because a session rebuilt from the
+				 * log would otherwise resume without the chain of thought the provider
+				 * expects to get back.
+				 */
+				reasoningDetails: opaqueBlocksSchema.optional(),
+				/** Anthropic thinking blocks (see ThinkingBlocks). Carried for the same reason. */
+				thinkingBlocks: opaqueBlocksSchema.optional(),
 			}),
 			metrics: llmMetricsSchema,
 			llmCallId: llmCallIdSchema.optional(),

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,