@roj-ai/sdk 0.1.35 → 0.2.1

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
 }

package/src/core/sessions/runtime-activity.ts

@@ -0,0 +1,78 @@
+export type RuntimeLeaseRelease = () => void
+
+export interface SessionRuntimeActivitySnapshot {
+	state: 'ready' | 'unloading' | 'disposed'
+	activeCount: number
+	reasons: Readonly<Record<string, number>>
+	lastActivityAt: number
+}
+
+/** Session-scoped guard that keeps a resident runtime alive while work is active. */
+export interface SessionRuntimeActivity {
+	/**
+	 * Take a lease, or throw when the runtime is no longer `ready`.
+	 *
+	 * Release it in a `finally` — an unreleased lease pins the runtime resident
+	 * forever. Prefer `tryAcquire` wherever losing the race is a normal outcome.
+	 */
+	acquire(reason: string): RuntimeLeaseRelease
+	/** Take a lease, or return null when the runtime is no longer `ready`. */
+	tryAcquire(reason: string): RuntimeLeaseRelease | null
+	getSnapshot(): SessionRuntimeActivitySnapshot
+}
+
+export class SessionRuntimeActivityController implements SessionRuntimeActivity {
+	private state: SessionRuntimeActivitySnapshot['state'] = 'ready'
+	private activeCount = 0
+	private readonly reasons = new Map<string, number>()
+	private lastActivityAt = performance.now()
+
+	acquire(reason: string): RuntimeLeaseRelease {
+		const release = this.tryAcquire(reason)
+		if (!release) {
+			throw new Error(`Session runtime is ${this.state}`)
+		}
+		return release
+	}
+
+	tryAcquire(reason: string): RuntimeLeaseRelease | null {
+		if (this.state !== 'ready') return null
+
+		this.lastActivityAt = performance.now()
+		this.activeCount++
+		this.reasons.set(reason, (this.reasons.get(reason) ?? 0) + 1)
+		let released = false
+		return () => {
+			if (released) return
+			released = true
+			this.lastActivityAt = performance.now()
+			this.activeCount--
+			const count = this.reasons.get(reason) ?? 0
+			if (count <= 1) this.reasons.delete(reason)
+			else this.reasons.set(reason, count - 1)
+		}
+	}
+
+	tryBeginUnload(): boolean {
+		if (this.state !== 'ready' || this.activeCount !== 0) return false
+		this.state = 'unloading'
+		return true
+	}
+
+	beginForcedUnload(): void {
+		if (this.state === 'ready') this.state = 'unloading'
+	}
+
+	markDisposed(): void {
+		this.state = 'disposed'
+	}
+
+	getSnapshot(): SessionRuntimeActivitySnapshot {
+		return {
+			state: this.state,
+			activeCount: this.activeCount,
+			reasons: Object.fromEntries(this.reasons),
+			lastActivityAt: this.lastActivityAt,
+		}
+	}
+}

package/src/core/sessions/schema.ts

@@ -9,20 +9,46 @@
 
 import { uuidv7 } from 'uuidv7'
 import z from 'zod/v4'
+import { type DomainError, ValidationErrors } from '~/core/errors.js'
+import { Err, Ok } from '~/lib/utils/result.js'
+import type { Result } from '~/lib/utils/result.js'
 
 // ============================================================================
 // SessionId - Branded type
 // ============================================================================
 
-/** SessionId schema - validates any string and brands as SessionId. */
-export const sessionIdSchema = z.string().brand('SessionId')
+/**
+ * Characters a session id may contain.
+ *
+ * A session id is interpolated straight into filesystem paths (the session dir,
+ * the event log, the file logger target), so anything that could traverse or
+ * escape the data root has to be rejected before a path is derived from it.
+ * Generated ids are UUIDv7; callers may supply their own, and both known
+ * platform consumers mint `crypto.randomUUID()`, which fits.
+ */
+export const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/
+
+/** True when the value is safe to interpolate into a path. */
+export const isValidSessionId = (id: string): boolean => SESSION_ID_PATTERN.test(id)
+
+/** SessionId schema - validates the id shape and brands as SessionId. */
+export const sessionIdSchema = z.string().regex(SESSION_ID_PATTERN, 'Invalid session id').brand('SessionId')
 
 /** Branded SessionId type */
 export type SessionId = z.infer<typeof sessionIdSchema>
 
-/** Constructor for SessionId */
+/**
+ * Unchecked brand — only for ids already known to match `SESSION_ID_PATTERN`.
+ *
+ * It does not validate, so it must never see untrusted input: the id is
+ * interpolated into filesystem paths. Use `parseSessionId` at every boundary.
+ */
 export const SessionId = (id: string): SessionId => id as SessionId
 
+/** Checked SessionId constructor — the form to use on untrusted input. */
+export const parseSessionId = (value: string): Result<SessionId, DomainError> =>
+	isValidSessionId(value) ? Ok(SessionId(value)) : Err(ValidationErrors.invalid('Invalid session id'))
+
 /** Generate a new SessionId (UUIDv7) */
 export const generateSessionId = (): SessionId => SessionId(uuidv7())