@roj-ai/sdk 0.1.36 → 0.2.2

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

@@ -19,6 +19,15 @@ import { getAgentState, reconstructSessionState } from '~/core/sessions/state.js
 // SessionStore
 // ============================================================================
 
+/** Thrown when a disposed runtime tries to append — see {@link SessionStore.detach}. */
+export class SessionRuntimeDetachedError extends Error {
+	constructor(readonly sessionId: SessionId, events: readonly DomainEvent[]) {
+		const types = [...new Set(events.map((event) => event.type))].join(', ')
+		super(`Session runtime for '${sessionId}' is disposed and cannot append events: ${types}`)
+		this.name = 'SessionRuntimeDetachedError'
+	}
+}
+
 /**
  * SessionStore wraps EventStore and provides:
  * - Event emission with automatic state updates
@@ -29,6 +38,7 @@ export class SessionStore {
 	private _state: SessionState
 	private readonly eventListeners: Array<(event: DomainEvent) => void> = []
 	private readonly applyEvent: SessionReducer
+	private detached = false
 
 	constructor(
 		readonly sessionId: SessionId,
@@ -59,6 +69,22 @@ export class SessionStore {
 		this.eventListeners.length = 0
 	}
 
+	/**
+	 * Fence the store off from its disposed runtime — later emits fail instead of writing.
+	 *
+	 * The manager rebuilds an evicted session from the log, so a late write from the
+	 * old runtime (an abandoned worker, a timer, a settled effect) would land durably
+	 * while only the dead projection saw it, and the live one would never catch up.
+	 */
+	detach(): void {
+		this.detached = true
+	}
+
+	/** True once the owning runtime was disposed and the store stopped accepting writes. */
+	isDetached(): boolean {
+		return this.detached
+	}
+
 	/**
 	 * Create a new SessionStore by loading events from EventStore.
 	 * Also validates and reconciles metadata if out of sync (e.g., after crash).
@@ -69,6 +95,16 @@ export class SessionStore {
 		applyEvent?: SessionReducer,
 	): Promise<SessionStore | null> {
 		const events = await eventStore.load(sessionId)
+		return SessionStore.fromEvents(sessionId, eventStore, events, applyEvent)
+	}
+
+	/** Build a store from an event log that the caller already loaded. */
+	static async fromEvents(
+		sessionId: SessionId,
+		eventStore: EventStore,
+		events: DomainEvent[],
+		applyEvent?: SessionReducer,
+	): Promise<SessionStore | null> {
 		if (events.length === 0) return null
 
 		const state = reconstructSessionState(events, applyEvent ?? coreApplyEvent)
@@ -84,6 +120,7 @@ export class SessionStore {
 	 * Emit a single event - writes to EventStore and applies to state.
 	 */
 	async emit(event: DomainEvent): Promise<void> {
+		if (this.detached) throw new SessionRuntimeDetachedError(this.sessionId, [event])
 		await this.eventStore.append(this.sessionId, event)
 		this._state = this.applyEvent(this._state, event)
 		this.notifyListeners(event)
@@ -96,6 +133,7 @@ export class SessionStore {
 	 */
 	async emitBatch(events: DomainEvent[]): Promise<void> {
 		if (events.length === 0) return
+		if (this.detached) throw new SessionRuntimeDetachedError(this.sessionId, events)
 
 		await this.eventStore.appendBatch(this.sessionId, events)
 		for (const event of events) {

package/src/core/sessions/session.ts

@@ -18,12 +18,12 @@ import type { DomainEvent } from '~/core/events/types.js'
 import type { LLMLogger } from '~/core/llm/logger.js'
 import { applyMiddleware, type LLMMiddleware } from '~/core/llm/middleware.js'
 import type { LLMProvider } from '~/core/llm/provider.js'
-import type { AgentPluginConfig, BaseSessionHookContext, CallerContext, ConfiguredPlugin } from '~/core/plugins/plugin-builder.js'
+import type { AgentPluginConfig, BaseSessionHookContext, CallerContext, ConfiguredPlugin, SessionCloseReason } from '~/core/plugins/plugin-builder.js'
 import { AGENT_CALLER, DEFAULT_CALLER, buildPluginDeps, type PluginNotification } from '~/core/plugins/plugin-builder.js'
 import type { Preset } from '~/core/preset/index.js'
 import type { SessionId } from '~/core/sessions/schema.js'
 import type { SessionOverridesPatch, SessionState } from '~/core/sessions/state.js'
-import { getEntryAgentId, getNextAgentSeq, sessionEvents } from '~/core/sessions/state.js'
+import { agentSequenceKey, getEntryAgentId, getNextAgentSeq, sessionEvents } from '~/core/sessions/state.js'
 import type { Logger } from '~/lib/logger/logger.js'
 import type { Platform } from '~/platform/index.js'
 import type { Result } from '~/lib/utils/result.js'
@@ -40,17 +40,35 @@ import type { SessionContext } from '../sessions/context.js'
 import type { SessionEnvironment } from '../sessions/session-environment.js'
 import type { ToolExecutor } from '../tools/executor.js'
 import { SessionStore } from './session-store.js'
+import { type RuntimeLeaseRelease, SessionRuntimeActivityController } from './runtime-activity.js'
 
 // ============================================================================
 // Types
 // ============================================================================
 
+/** Sequence name behind reserveMailboxMessageSequence. */
+const MAILBOX_MESSAGE_SEQUENCE = 'mailbox.message'
+
+/** Disposal waits for aborted turns to unwind, but never pins on a wedged one. */
+const AGENT_DRAIN_TIMEOUT_MS = 5_000
+
 /**
  * Callback for user-facing output.
  * Receives plugin notifications that are broadcast to connected clients.
  */
 export type UserOutputCallback = (notification: PluginNotification) => void
 
+export interface SessionReopenRegistration {
+	complete(): Promise<void>
+	abort(error: unknown): void
+}
+
+class SessionReopenError extends Error {
+	constructor(readonly domainError: DomainError) {
+		super(domainError.message)
+	}
+}
+
 /**
  * Dependencies for creating a Session.
  */
@@ -73,6 +91,9 @@ export interface SessionDependencies {
 	llmLogger?: LLMLogger
 	/** Host-environment adapters (filesystem, process). */
 	platform: Platform
+	/** Lifecycle guard shared by the manager, agents, and plugins. */
+	runtimeActivity: SessionRuntimeActivityController
+	registerReopenedSession?: (session: Session) => Result<SessionReopenRegistration | undefined, DomainError>
 }
 
 // ============================================================================
@@ -96,10 +117,16 @@ export class Session {
 	private readonly eventStore: EventStore
 	private readonly llmLogger?: LLMLogger
 	private readonly platform: Platform
+	private readonly runtimeActivity: SessionRuntimeActivityController
+	private readonly registerReopenedSession?: SessionDependencies['registerReopenedSession']
+	/** Named counters, seeded lazily from replayed state — see SessionContext.reserveSequence. */
+	private readonly sequences = new Map<string, number>()
 
 	private readonly agents = new Map<AgentId, Agent>()
 	/** Cached plugin contexts created by plugin.createContext() */
 	private readonly pluginContexts = new Map<string, unknown>()
+	private disposalPromise?: Promise<void>
+	private reopenPromise?: Promise<Result<void, DomainError>>
 
 	constructor(deps: SessionDependencies) {
 		this.id = deps.store.sessionId
@@ -115,6 +142,8 @@ export class Session {
 		this.eventStore = deps.eventStore
 		this.llmLogger = deps.llmLogger
 		this.platform = deps.platform
+		this.runtimeActivity = deps.runtimeActivity
+		this.registerReopenedSession = deps.registerReopenedSession
 		// Initialize agents from state
 		this.initializeAgents()
 
@@ -189,7 +218,7 @@ export class Session {
 
 	/**
 	 * Close the session.
-	 * Emits session_closed event — hooks and agent shutdown are handled reactively by handleSessionClosed().
+	 * Emits session_closed, then awaits the shared runtime disposal path.
 	 */
 	async close(): Promise<Result<void, DomainError>> {
 		if (this.store.isClosed()) {
@@ -197,6 +226,7 @@ export class Session {
 		}
 
 		await this.store.emit(withSessionId(this.id, sessionEvents.create('session_closed', {})))
+		await this.dispose('closed')
 
 		return Ok(undefined)
 	}
@@ -208,10 +238,7 @@ export class Session {
 		if (!this.store.isClosed()) {
 			return Err(ValidationErrors.invalid('Session is not closed'))
 		}
-
-		await this.store.emit(withSessionId(this.id, sessionEvents.create('session_reopened', {})))
-
-		return Ok(undefined)
+		return this.reopenWithEvent(sessionEvents.create('session_reopened', {}))
 	}
 
 	/**
@@ -379,7 +406,7 @@ export class Session {
 			}
 		}
 
-		const seq = getNextAgentSeq(this.state, definitionName)
+		const seq = this.reserveSequence(agentSequenceKey(definitionName), () => getNextAgentSeq(this.state, definitionName))
 		const agentId = generateAgentId(definitionName, seq)
 		const now = Date.now()
 
@@ -396,11 +423,13 @@ export class Session {
 		]
 
 		if (message) {
-			const messageId = generateMessageId(getNextMessageSeq(selectMailboxState(this.state)) + 1)
+			const sequence = this.reserveMailboxMessageSequence()
+			const messageId = generateMessageId(sequence)
 			events.push(withSessionId(
 				this.id,
 				mailboxEvents.create('mailbox_message', {
 					toAgentId: agentId,
+					sequence,
 					message: {
 						id: messageId,
 						from: parentId,
@@ -425,16 +454,27 @@ export class Session {
 	}
 
 	/**
-	 * Shutdown the session - stop all agent processing.
+	 * Dispose runtime resources without changing persisted session state.
+	 *
+	 * `reason` reaches every `onSessionClose` hook, and disposal is idempotent, so
+	 * the first caller's reason is the one the hooks see. It defaults to `evicted`
+	 * because a bare dispose only drops the runtime — the session survives and the
+	 * next access rebuilds it. The paths that really end a session pass `closed`.
 	 */
-	shutdown(): void {
-		for (const agent of this.agents.values()) {
-			try {
-				agent.shutdown()
-			} catch {
-				// Suppress errors during shutdown
-			}
-		}
+	dispose(reason: SessionCloseReason = 'evicted'): Promise<void> {
+		this.runtimeActivity.beginForcedUnload()
+		this.disposalPromise ??= Promise.resolve().then(() => this.performDisposal(reason))
+		return this.disposalPromise
+	}
+
+	/**
+	 * Take a runtime lease from outside the session; the caller must release it.
+	 *
+	 * Returns null once the runtime stopped being `ready`, so losing the race with
+	 * eviction reads as "this runtime is gone" instead of resurrecting it.
+	 */
+	tryAcquireRuntimeLease(reason: string): RuntimeLeaseRelease | null {
+		return this.runtimeActivity.tryAcquire(reason)
 	}
 
 	/**
@@ -474,6 +514,22 @@ export class Session {
 		input: unknown,
 		agentId?: AgentId,
 		caller?: CallerContext,
+	): Promise<Result<unknown, DomainError>> {
+		if (this.store.isClosed()) return this.executePluginMethod(method, input, agentId, caller)
+		const release = this.runtimeActivity.tryAcquire(`plugin:${method}`)
+		if (!release) return Err(SessionErrors.notFound(String(this.id)))
+		try {
+			return await this.executePluginMethod(method, input, agentId, caller)
+		} finally {
+			release()
+		}
+	}
+
+	private async executePluginMethod(
+		method: string,
+		input: unknown,
+		agentId?: AgentId,
+		caller?: CallerContext,
 	): Promise<Result<unknown, DomainError>> {
 		// Find the plugin and method by parsing "pluginName.methodName"
 		const dotIndex = method.indexOf('.')
@@ -539,9 +595,12 @@ export class Session {
 			deps,
 		}
 
-		const result = await methodDef.handler(ctx, parsed.data)
-
-		return result
+		try {
+			return await methodDef.handler(ctx, parsed.data)
+		} catch (error) {
+			if (error instanceof SessionReopenError) return Err(error.domainError)
+			throw error
+		}
 	}
 
 	// ============================================================================
@@ -587,24 +646,7 @@ export class Session {
 
 		return new Agent({
 			id: agentState.id,
-			sessionContext: {
-				sessionId: this.id,
-				sessionState: this.store.getState(),
-				sessionInput: undefined,
-				environment: env,
-				llm: this.llmProvider,
-				files: fileStore,
-				eventStore: this.eventStore,
-				llmLogger: this.llmLogger,
-				platform: this.platform,
-				logger: this.logger,
-				emitEvent: async (event) => {
-					await this.store.emit(withSessionId(this.id, event))
-				},
-				notify: (type, payload) => {
-					this.onUserOutput?.({ pluginName: '_agent', type, payload })
-				},
-			},
+			getSessionContext: () => this.buildSessionContext('_agent'),
 			store: this.store,
 			llmProvider,
 			llmProviders: this.llmProviders,
@@ -634,8 +676,8 @@ export class Session {
 				break
 			}
 			case 'session_closed': {
-				this.handleSessionClosed().catch((err) => {
-					this.logger.error('Unhandled error in handleSessionClosed()', err instanceof Error ? err : undefined, { sessionId: this.id })
+				this.dispose('closed').catch((err) => {
+					this.logger.error('Unhandled error in session disposal', err instanceof Error ? err : undefined, { sessionId: this.id })
 				})
 				break
 			}
@@ -643,20 +685,20 @@ export class Session {
 	}
 
 	/**
-	 * Handle session_closed event — call close hooks and shutdown agents.
+	 * Call close hooks and release all in-memory runtime state.
 	 *
 	 * Unlike onSessionReady (which re-throws), onSessionClose intentionally
 	 * swallows per-plugin errors so that all plugins get a chance to clean up
 	 * and agents are always shut down, even if one plugin's close hook fails.
 	 */
-	private async handleSessionClosed(): Promise<void> {
+	private async performDisposal(reason: SessionCloseReason): Promise<void> {
 		// Call onSessionClose for all plugins in REVERSE order (per-plugin isolation)
 		const reversedPlugins = [...this.plugins].reverse()
 		for (const plugin of reversedPlugins) {
 			if (plugin.sessionHooks?.onSessionClose) {
 				try {
 					const ctx = this.buildSessionHookContext(plugin)
-					await plugin.sessionHooks.onSessionClose(ctx)
+					await plugin.sessionHooks.onSessionClose({ ...ctx, reason })
 				} catch (err) {
 					this.logger.error(`Session plugin '${plugin.name}' onSessionClose failed`, err instanceof Error ? err : new Error(String(err)), {
 						sessionId: this.id,
@@ -675,12 +717,43 @@ export class Session {
 			}
 		}
 
+		// The shutdown above only aborts; a turn still inside a tool call keeps
+		// running against the agents and plugin contexts cleared below.
+		await this.drainAgents()
+
 		// Clean up references to prevent memory leaks
 		this.agents.clear()
 		this.pluginContexts.clear()
 		this.store.clearListeners()
+		// Fence the log last: everything above may still emit legitimately, but
+		// whatever outlives disposal now fails instead of writing behind the
+		// replacement runtime the manager builds from the same log.
+		this.store.detach()
+		this.runtimeActivity.markDisposed()
 
-		this.logger.info('Session closed', { sessionId: this.id })
+		this.logger.info('Session runtime disposed', { sessionId: this.id, reason })
+	}
+
+	/** Await every in-flight turn, bounded — a wedged one must not hold disposal open. */
+	private async drainAgents(): Promise<void> {
+		const drains = [...this.agents.values()].map((agent) => agent.waitForIdle())
+		if (drains.length === 0) return
+
+		let timer: ReturnType<typeof setTimeout> | undefined
+		const expiry = new Promise<'expired'>((resolve) => {
+			timer = setTimeout(() => resolve('expired'), AGENT_DRAIN_TIMEOUT_MS)
+		})
+		try {
+			const outcome = await Promise.race([Promise.all(drains).then(() => 'drained' as const), expiry])
+			if (outcome === 'expired') {
+				this.logger.warn('Agent turns did not settle before disposal', {
+					sessionId: this.id,
+					timeoutMs: AGENT_DRAIN_TIMEOUT_MS,
+				})
+			}
+		} finally {
+			if (timer) clearTimeout(timer)
+		}
 	}
 
 	/**
@@ -736,12 +809,13 @@ export class Session {
 	/**
 	 * Build a SessionContext from current session state.
 	 */
-	private buildSessionContext(): SessionContext {
+	private buildSessionContext(notificationPluginName = '_session'): SessionContext {
 		const env = this.getSessionEnvironment()
 		const fileStore = new SessionFileStore(env.sessionDir, env.workspaceDir, env.sandboxed, this.platform.fs)
 		return {
 			sessionId: this.id,
 			sessionState: this.store.getState(),
+			getSessionState: () => this.store.getState(),
 			sessionInput: undefined,
 			environment: env,
 			llm: this.llmProvider,
@@ -750,12 +824,73 @@ export class Session {
 			llmLogger: this.llmLogger,
 			platform: this.platform,
 			logger: this.logger,
+			runtimeActivity: this.runtimeActivity,
+			reserveSequence: (name, seed) => this.reserveSequence(name, seed),
+			reserveMailboxMessageSequence: () => this.reserveMailboxMessageSequence(),
 			emitEvent: async (event) => {
+				if (event.type === 'session_reopened') {
+					const reopened = await this.reopenWithEvent(event)
+					if (!reopened.ok) throw new SessionReopenError(reopened.error)
+					return
+				}
 				await this.store.emit(withSessionId(this.id, event))
 			},
+			emitEvents: async (events) => {
+				await this.store.emitBatch(events.map((event) => withSessionId(this.id, event)))
+			},
 			notify: (type, payload) => {
-				this.onUserOutput?.({ pluginName: '_session', type, payload })
+				this.onUserOutput?.({ pluginName: notificationPluginName, type, payload })
+			},
+		}
+	}
+
+	private reserveSequence(name: string, seed: () => number): number {
+		const activity = this.runtimeActivity.getSnapshot()
+		if (this.store.isClosed() || activity.state !== 'ready') {
+			throw new Error(`Cannot reserve sequence "${name}" on a closed or disposed session runtime`)
+		}
+		const sequence = this.sequences.get(name) ?? seed()
+		this.sequences.set(name, sequence + 1)
+		return sequence
+	}
+
+	private reserveMailboxMessageSequence(): number {
+		return this.reserveSequence(MAILBOX_MESSAGE_SEQUENCE, () => getNextMessageSeq(selectMailboxState(this.store.getState())))
+	}
+
+	private reopenWithEvent(event: Omit<BaseEvent<string>, 'sessionId'>): Promise<Result<void, DomainError>> {
+		if (this.reopenPromise) return this.reopenPromise
+		const operation = this.performReopen(event)
+		this.reopenPromise = operation
+		void operation.then(
+			() => {
+				if (this.reopenPromise === operation) this.reopenPromise = undefined
 			},
+			() => {
+				if (this.reopenPromise === operation) this.reopenPromise = undefined
+			},
+		)
+		return operation
+	}
+
+	private async performReopen(event: Omit<BaseEvent<string>, 'sessionId'>): Promise<Result<void, DomainError>> {
+		if (!this.store.isClosed()) return Err(ValidationErrors.invalid('Session is not closed'))
+		// A disposed runtime cannot host the reopened session — the manager refuses to
+		// re-register it — so reopen through a freshly loaded one instead of writing
+		// the event from a handle that is already dead.
+		if (this.store.isDetached()) {
+			return Err(ValidationErrors.invalid('Session runtime is disposed; load the session again to reopen it'))
+		}
+		const registrationResult = this.registerReopenedSession?.(this) ?? Ok(undefined)
+		if (!registrationResult.ok) return registrationResult
+		const registration = registrationResult.value
+		try {
+			await this.store.emit(withSessionId(this.id, event))
+			await registration?.complete()
+			return Ok(undefined)
+		} catch (error) {
+			registration?.abort(error)
+			throw error
 		}
 	}
 
@@ -795,6 +930,11 @@ export class Session {
 		}
 	}
 
+	/** What plugins and tools see. Read-only, so a host can assert the posture it resolved. */
+	get environment(): SessionEnvironment {
+		return this.getSessionEnvironment()
+	}
+
 	/**
 	 * Get session environment for tool context.
 	 */

package/src/core/sessions/state.ts

@@ -279,6 +279,7 @@ export const coreReducer = createTypedReducer(
 						lastInferenceMetrics: event.metrics,
 						consecutiveInferenceFailures: 0,
 						lastInferenceFailureAt: undefined,
+						turnNumber: (agent.turnNumber ?? 0) + 1,
 					}
 				})
 			}
@@ -643,3 +644,13 @@ export const getAgentState = (state: SessionState, agentId: AgentId): AgentState
 export const getNextAgentSeq = (state: SessionState, definitionName: string): number => {
 	return (state.agentCounters.get(definitionName) ?? 0) + 1
 }
+
+/**
+ * Reservation key for the per-definition agent sequence.
+ *
+ * Both spawn paths reserve through `SessionContext.reserveSequence` — deriving the
+ * sequence from the projection instead lets two concurrent spawns read the same
+ * counter and mint the same agent id, and the second one then overwrites the first
+ * in the agent map while both callers are told they spawned an agent.
+ */
+export const agentSequenceKey = (definitionName: string): string => `agent.${definitionName}`

package/src/core/system.ts

@@ -9,6 +9,7 @@
 
 import type z4 from 'zod/v4'
 import type { Logger } from '~/lib/logger/logger.js'
+import type { ArchiveLimitOverrides } from '~/lib/archive/index.js'
 import type { Platform } from '~/platform/index.js'
 import type { ServicePidRegistry } from '~/plugins/services/pid-registry.js'
 import type { PortPool } from '~/plugins/services/port-pool.js'
@@ -119,11 +120,19 @@ export interface CreateSystemOptions<TPlugins extends readonly PluginDefinition<
 	dataFileStore: FileStore
 	onUserOutput?: UserOutputCallback
 	preprocessorRegistry?: PreprocessorRegistry
+	uploadArchiveLimits?: ArchiveLimitOverrides
+	resourceArchiveLimits?: ArchiveLimitOverrides
 	llmLogger?: LLMLogger
 	portPool?: PortPool
 	pidRegistry?: ServicePidRegistry
 	/** Host-environment adapters (filesystem, process). */
 	platform: Platform
+	/**
+	 * Evict a resident session runtime after this long idle. Absent or `0` keeps
+	 * every runtime resident, which is the default for programmatic SDK use.
+	 * An evicted runtime is rebuilt from its event log and re-runs `onSessionReady`.
+	 */
+	sessionIdleTimeoutMs?: number
 }
 
 // ============================================================================
@@ -145,10 +154,13 @@ export function createSystem<const TPlugins extends readonly PluginDefinition<st
 		dataFileStore,
 		onUserOutput,
 		preprocessorRegistry,
+		uploadArchiveLimits,
+		resourceArchiveLimits,
 		llmLogger,
 		portPool,
 		pidRegistry,
 		platform,
+		sessionIdleTimeoutMs,
 	} = options
 
 	// Build plugins accessor — typed record keyed by plugin name
@@ -168,10 +180,13 @@ export function createSystem<const TPlugins extends readonly PluginDefinition<st
 		dataFileStore,
 		onUserOutput,
 		preprocessorRegistry,
+		uploadArchiveLimits,
+		resourceArchiveLimits,
 		llmLogger,
 		portPool,
 		pidRegistry,
 		platform,
+		sessionIdleTimeoutMs,
 		systemPlugins: [...plugins],
 	})
 

package/src/core/wake-key.ts

@@ -0,0 +1,65 @@
+/**
+ * Routing keys for scheduler wakes.
+ *
+ * A wake must be dispatchable after the process that armed it is gone, so it
+ * carries no closure: the key is the whole routing table. `SessionManager`
+ * mints and reads them, and `dispatchWake` turns one back into a session.
+ *
+ * Their own module because both the agent loop and the plugins that arm wakes
+ * need them, and neither should have to import the other to mint one.
+ */
+
+import { AgentId } from '~/core/agents/schema.js'
+import { isValidSessionId, SessionId } from '~/core/sessions/schema.js'
+
+/** Which delayed re-entry an agent wake stands for. */
+export type AgentWakeKind = 'debounce' | 'retry'
+
+export interface AgentWake {
+	sessionId: SessionId
+	agentId: AgentId
+	kind: AgentWakeKind
+}
+
+export interface PluginWake {
+	sessionId: SessionId
+	pluginName: string
+	method: string
+	agentId: AgentId | undefined
+}
+
+/** `agent:<sessionId>:<agentId>:<kind>` */
+export function agentWakeKey(sessionId: SessionId, agentId: AgentId, kind: AgentWakeKind): string {
+	return `agent:${sessionId}:${agentId}:${kind}`
+}
+
+/** Read a key back, or null when it is not one `agentWakeKey` minted. */
+export function parseAgentWakeKey(key: string): AgentWake | null {
+	const parts = key.split(':')
+	if (parts.length !== 4 || parts[0] !== 'agent') return null
+	const [, sessionId, agentId, kind] = parts
+	if (kind !== 'debounce' && kind !== 'retry') return null
+	if (agentId === '' || !isValidSessionId(sessionId)) return null
+	return { sessionId: SessionId(sessionId), agentId: AgentId(agentId), kind }
+}
+
+/** `plugin:<sessionId>:<pluginName>:<method>[:<agentId>]` */
+export function pluginWakeKey(sessionId: SessionId, pluginName: string, method: string, agentId?: AgentId): string {
+	const base = `plugin:${sessionId}:${pluginName}:${method}`
+	return agentId === undefined ? base : `${base}:${agentId}`
+}
+
+/** Read a key back, or null when it is not one `pluginWakeKey` minted. */
+export function parsePluginWakeKey(key: string): PluginWake | null {
+	const parts = key.split(':')
+	if (parts.length !== 4 && parts.length !== 5) return null
+	const [prefix, sessionId, pluginName, method, agentId] = parts
+	if (prefix !== 'plugin' || pluginName === '' || method === '') return null
+	if (agentId === '' || !isValidSessionId(sessionId)) return null
+	return {
+		sessionId: SessionId(sessionId),
+		pluginName,
+		method,
+		agentId: agentId === undefined ? undefined : AgentId(agentId),
+	}
+}