@namzu/sdk 59.0.0 → 60.1.0

package/src/execution/workflow/runtime.ts

@@ -9,6 +9,7 @@ import { preview, sha256 } from './journal.js'
 import { splitWorkflowScript } from './meta.js'
 import { type PhaseAgentView, PhaseRegistry, summarizeWorkflowPhases } from './phases.js'
 import { buildPrelude, preludeLineCount } from './prelude.js'
+import { workflowCallContent, workflowCallKey } from './resume.js'
 import { parseJsonText, validateAgainstSchema } from './schema.js'
 import type {
 	WorkflowAgentEvent,
@@ -83,7 +84,9 @@ export function resolveWorkflowLimits(limits: WorkflowLimits = {}): WorkflowReso
 			16 * 1024 * 1024,
 		),
 		...(limits.tokenBudget !== undefined
-			? { tokenBudget: integer('tokenBudget', limits.tokenBudget, 1, Number.MAX_SAFE_INTEGER) }
+			? {
+					tokenBudget: integer('tokenBudget', limits.tokenBudget, 1, Number.MAX_SAFE_INTEGER),
+				}
 			: {}),
 		maxDurationMs: integer(
 			'maxDurationMs',
@@ -198,6 +201,14 @@ interface AgentRecord {
 	error?: string
 	skipped: boolean
 	userSkipped: boolean
+	key?: string
+	/** Set when the result came from an earlier pass instead of a run. */
+	cached?: {
+		readonly pass: number
+		readonly index: number
+		readonly childSessionId?: string
+	}
+	childSessionId?: string
 }
 
 interface Waiter {
@@ -283,6 +294,10 @@ export class WorkflowRuntime {
 		const runId =
 			options.runId ?? `w${[...randomBytes(8)].map((b) => (b % 36).toString(36)).join('')}`
 		const startedAt = now()
+		const pass = options.resume?.pass ?? 1
+		const resume = options.resume
+		let latch = false
+		const seenContent = new Map<string, number>()
 		const phases = new PhaseRegistry()
 		const agents = new Map<number, AgentRecord>()
 		const inFlight = new Set<Promise<unknown>>()
@@ -335,7 +350,13 @@ export class WorkflowRuntime {
 					declared,
 					at,
 				})
-				journal({ type: 'phase', at, index: phase.index, title: phase.title, declared })
+				journal({
+					type: 'phase',
+					at,
+					index: phase.index,
+					title: phase.title,
+					declared,
+				})
 			}
 			return phase
 		}
@@ -361,6 +382,7 @@ export class WorkflowRuntime {
 			...(agent.resultPreview !== undefined ? { resultPreview: agent.resultPreview } : {}),
 			...(agent.error !== undefined ? { error: agent.error } : {}),
 			...(agent.skipped ? { skipped: true } : {}),
+			...(agent.cached !== undefined ? { cached: true } : {}),
 		})
 
 		// FIFO admission: an agent starts when fewer than maxConcurrency run.
@@ -411,7 +433,13 @@ export class WorkflowRuntime {
 
 		const settle = (
 			agent: AgentRecord,
-			outcome: { state: 'done' | 'error'; skipped?: boolean; value?: unknown; error?: string },
+			outcome: {
+				state: 'done' | 'error'
+				skipped?: boolean
+				value?: unknown
+				error?: string
+				interrupted?: boolean
+			},
 		): HostCallResult => {
 			const at = now()
 			agent.state = outcome.state
@@ -434,11 +462,25 @@ export class WorkflowRuntime {
 				value = null
 			}
 			emit(agentEvent(agent))
+			const finalState = agent.state === 'error' ? 'error' : agent.skipped ? 'skipped' : 'done'
+			let saved: { result: unknown } | { unsaved: true } | undefined
+			if (finalState === 'done' && value !== null && agent.cached === undefined) {
+				try {
+					saved = { result: JSON.parse(JSON.stringify(value)) as unknown }
+				} catch {
+					saved = { unsaved: true }
+					journal({
+						type: 'log',
+						at,
+						message: "An agent's result could not be saved, so a resume will run it again.",
+					})
+				}
+			}
 			journal({
 				type: 'agent_outcome',
 				at,
 				index: agent.index,
-				state: agent.state === 'error' ? 'error' : agent.skipped ? 'skipped' : 'done',
+				state: finalState,
 				tokens: agent.tokens,
 				toolCalls: agent.toolCalls,
 				queuedAt: agent.queuedAt,
@@ -446,6 +488,22 @@ export class WorkflowRuntime {
 				finishedAt: at,
 				...(agent.resultPreview !== undefined ? { resultPreview: agent.resultPreview } : {}),
 				...(agent.error !== undefined ? { error: agent.error } : {}),
+				...(agent.key !== undefined ? { key: agent.key } : {}),
+				pass,
+				...(agent.cached !== undefined
+					? {
+							cached: true as const,
+							resultFrom: {
+								pass: agent.cached.pass,
+								index: agent.cached.index,
+							},
+						}
+					: {}),
+				...(saved ?? {}),
+				...(outcome.interrupted === true && finalState === 'error'
+					? { interrupted: true as const }
+					: {}),
+				...(agent.childSessionId !== undefined ? { childSessionId: agent.childSessionId } : {}),
 			})
 			return { ok: true, value: { v: value, t: totalTokens() } }
 		}
@@ -457,6 +515,7 @@ export class WorkflowRuntime {
 		): HostCallResult => {
 			agent.tokens = count(outcome.tokens)
 			agent.toolCalls = count(outcome.toolCalls)
+			if (outcome.sessionId !== undefined) agent.childSessionId = outcome.sessionId
 			if (agent.userSkipped || outcome.state === 'skipped') {
 				return settle(agent, { state: 'done', skipped: true })
 			}
@@ -464,10 +523,14 @@ export class WorkflowRuntime {
 				return settle(agent, {
 					state: 'error',
 					error: 'The workflow was stopped before this agent finished.',
+					interrupted: true,
 				})
 			}
 			if (outcome.state === 'error') {
-				return settle(agent, { state: 'error', error: outcome.error ?? 'The agent failed.' })
+				return settle(agent, {
+					state: 'error',
+					error: outcome.error ?? 'The agent failed.',
+				})
 			}
 			if (call.schema === undefined) {
 				return settle(agent, { state: 'done', value: outcome.text ?? '' })
@@ -503,6 +566,18 @@ export class WorkflowRuntime {
 				return { ok: false, error: reason }
 			}
 			const index = ++requested
+			const contentId = workflowCallContent(call.prompt, call)
+			const ordinal = seenContent.get(contentId) ?? 0
+			seenContent.set(contentId, ordinal + 1)
+			const key = workflowCallKey(call.prompt, call, ordinal)
+			const hit = latch ? undefined : resume?.results.get(key)
+			if (
+				resume !== undefined &&
+				hit === undefined &&
+				!(resume.seen.has(key) && !resume.failed.has(key) && !resume.demoted.has(key))
+			) {
+				latch = true
+			}
 			const phaseTitle = call.phase ?? call.cursor
 			const phase = phaseTitle?.trim() ? announce(phaseTitle, false) : undefined
 			const queuedAt = now()
@@ -521,13 +596,26 @@ export class WorkflowRuntime {
 				toolCalls: 0,
 				skipped: false,
 				userSkipped: false,
+				key,
 			}
 			agents.set(index, agent)
+			if (hit !== undefined) {
+				agent.cached = {
+					pass: hit.pass,
+					index: hit.index,
+					...(hit.childSessionId !== undefined ? { childSessionId: hit.childSessionId } : {}),
+				}
+				if (hit.childSessionId !== undefined) agent.childSessionId = hit.childSessionId
+				agent.startedAt = queuedAt
+			}
 			emit(agentEvent(agent))
 			journal({
 				type: 'agent_request',
 				at: queuedAt,
 				index,
+				key,
+				pass,
+				...(hit !== undefined ? { cached: true as const } : {}),
 				label: agent.label,
 				...(phase ? { phaseIndex: phase.index, phaseTitle: phase.title } : {}),
 				promptPreview: preview(call.prompt),
@@ -540,6 +628,12 @@ export class WorkflowRuntime {
 				},
 			})
 
+			if (hit !== undefined) {
+				return settle(agent, {
+					state: 'done',
+					value: structuredClone(hit.value),
+				})
+			}
 			const admitted = await acquire(agent)
 			if (!admitted) {
 				return agent.userSkipped
@@ -547,6 +641,7 @@ export class WorkflowRuntime {
 					: settle(agent, {
 							state: 'error',
 							error: 'The workflow was stopped before this agent started.',
+							interrupted: true,
 						})
 			}
 			try {
@@ -554,6 +649,7 @@ export class WorkflowRuntime {
 					return settle(agent, {
 						state: 'error',
 						error: `Not started: the token budget for this workflow (${limits.tokenBudget} tokens) is spent.`,
+						interrupted: true,
 					})
 				}
 				if (controller.signal.aborted || agent.userSkipped) {
@@ -562,6 +658,7 @@ export class WorkflowRuntime {
 						: settle(agent, {
 								state: 'error',
 								error: 'The workflow was stopped before this agent started.',
+								interrupted: true,
 							})
 				}
 				agent.startedAt = now()
@@ -630,7 +727,7 @@ export class WorkflowRuntime {
 		// --- start ---
 		if (options.journal?.writeScript) {
 			try {
-				await options.journal.writeScript(options.script, sha256(options.script))
+				await options.journal.writeScript(options.script, sha256(options.script), pass)
 			} catch (error) {
 				journalError = error instanceof Error ? error.message : String(error)
 			}
@@ -644,6 +741,17 @@ export class WorkflowRuntime {
 			meta,
 			args,
 			limits,
+			...(resume !== undefined
+				? {
+						resume: {
+							pass,
+							previousFinish: resume.previousFinish,
+							scriptSha256Changed:
+								resume.scriptSha256 !== undefined && resume.scriptSha256 !== sha256(options.script),
+						},
+					}
+				: {}),
+			...(options.scriptPath !== undefined ? { scriptPath: options.scriptPath } : {}),
 		})
 		emit({
 			type: 'workflow_started',
@@ -665,7 +773,11 @@ export class WorkflowRuntime {
 				maxPendingHostCalls: limits.maxAgents + 100,
 			})
 
-		const preludeConfig = { args, tokenLimit: limits.tokenBudget ?? null }
+		const preludeConfig = {
+			args,
+			tokenLimit: limits.tokenBudget ?? null,
+			deterministic: options.deterministic === true,
+		}
 		const runResult = await codeRuntime.run({
 			source: `${buildPrelude(preludeConfig)}\n${body}`,
 			allowedCalls: [WORKFLOW_HOST_CALL],
@@ -676,7 +788,10 @@ export class WorkflowRuntime {
 			onOutput,
 			onHostCall: (request) => {
 				if (request.name !== WORKFLOW_HOST_CALL) {
-					return Promise.resolve({ ok: false, error: `Unknown host call "${request.name}".` })
+					return Promise.resolve({
+						ok: false,
+						error: `Unknown host call "${request.name}".`,
+					})
 				}
 				let call: AgentCall
 				try {
@@ -738,7 +853,7 @@ export class WorkflowRuntime {
 			const progress =
 				begun.length === 0
 					? 'No agent had started.'
-					: `Before it failed: ${begun.length} agent${begun.length === 1 ? '' : 's'} started, ${finished} finished, ${failedAgents} failed. A rerun starts the whole script again, so finished agents run again.`
+					: `Before it failed: ${begun.length} agent${begun.length === 1 ? '' : 's'} started, ${finished} finished, ${failedAgents} failed. ${options.canResume === true ? 'Resume the run to continue: agents whose prompt and options are unchanged return their saved results.' : 'A rerun starts the whole script again, so finished agents run again.'}`
 			error = `${describeScriptFailure(outcome, body, preludeLineCount(preludeConfig))}\n${progress}${scriptPhase !== undefined ? ` Last phase: "${scriptPhase}".` : ''}`
 		}
 
@@ -751,6 +866,9 @@ export class WorkflowRuntime {
 			tokens: all.reduce((sum, a) => sum + a.tokens, 0),
 			toolCalls: all.reduce((sum, a) => sum + a.toolCalls, 0),
 			elapsedMs: Math.max(0, now() - startedAt),
+			...(all.some((a) => a.cached !== undefined)
+				? { cachedAgents: all.filter((a) => a.cached !== undefined).length }
+				: {}),
 		}
 		const at = now()
 		emit({

package/src/execution/workflow/types.ts

@@ -53,6 +53,8 @@ export interface WorkflowAgentOutcome {
 	readonly tokens: number
 	readonly toolCalls: number
 	readonly error?: string
+	/** The id of the child session the host ran this agent in, recorded in the journal. */
+	readonly sessionId?: string
 }
 
 /**
@@ -113,6 +115,8 @@ export interface WorkflowAgentEvent {
 	readonly resultPreview?: string
 	readonly error?: string
 	readonly skipped?: boolean
+	/** True when the agent did not run: a resumed run returned the result it saved earlier. */
+	readonly cached?: boolean
 }
 
 export interface WorkflowLogEvent {
@@ -133,6 +137,8 @@ export interface WorkflowUsage {
 	readonly tokens: number
 	readonly toolCalls: number
 	readonly elapsedMs: number
+	/** Agents that returned a result saved by an earlier pass instead of running (a subset of `agentsDone`). */
+	readonly cachedAgents?: number
 }
 
 export interface WorkflowFinishedEvent {
@@ -177,6 +183,14 @@ export type WorkflowJournalRecord =
 			readonly meta: WorkflowMeta
 			readonly args: unknown
 			readonly limits: WorkflowResolvedLimits
+			/** Present on every pass after the first; a resumed run keeps its run id and journal. */
+			readonly resume?: {
+				readonly pass: number
+				readonly previousFinish: WorkflowFinishStatus | 'unfinished'
+				readonly scriptSha256Changed: boolean
+			}
+			/** Where the script came from when the host read it from a file. */
+			readonly scriptPath?: string
 	  }
 	| {
 			readonly type: 'phase'
@@ -200,6 +214,12 @@ export type WorkflowJournalRecord =
 				readonly effort?: string
 				readonly schema: boolean
 			}
+			/** Identifies the call across passes; see `workflowCallKey`. */
+			readonly key?: string
+			/** 1 for the first pass. A record from an older pass than the latest `run_started` is stale. */
+			readonly pass?: number
+			/** The agent did not run; its result came from an earlier pass. */
+			readonly cached?: true
 	  }
 	| {
 			readonly type: 'agent_outcome'
@@ -213,6 +233,18 @@ export type WorkflowJournalRecord =
 			readonly finishedAt: number
 			readonly resultPreview?: string
 			readonly error?: string
+			readonly key?: string
+			readonly pass?: number
+			readonly cached?: true
+			/** The agent's full value (after schema validation); present only for a finished, non-null result. */
+			readonly result?: unknown
+			/** A value existed but could not be saved; a resume runs this agent again. */
+			readonly unsaved?: true
+			/** The run or the agent was stopped before the agent finished; a resume runs it again and keeps its saved results valid. */
+			readonly interrupted?: true
+			/** Where a cached result was first recorded. */
+			readonly resultFrom?: { readonly pass: number; readonly index: number }
+			readonly childSessionId?: string
 	  }
 	| { readonly type: 'log'; readonly at: number; readonly message: string }
 	| {
@@ -222,12 +254,14 @@ export type WorkflowJournalRecord =
 			readonly result?: unknown
 			readonly error?: string
 			readonly usage: WorkflowUsage
+			/** Written by a later session for a run whose process ended without finishing it. */
+			readonly recovered?: true
 	  }
 
 /** Where a run's audit trail goes. Injected so the SDK stays host-agnostic. */
 export interface WorkflowJournal {
 	/** Called once, before the first record, with the exact script text. */
-	writeScript?(source: string, sha256: string): Promise<void> | void
+	writeScript?(source: string, sha256: string, pass?: number): Promise<void> | void
 	append(record: WorkflowJournalRecord): Promise<void> | void
 }
 
@@ -283,6 +317,80 @@ export interface WorkflowRunOptions {
 	readonly onControl?: (control: WorkflowControl) => void
 	/** Default: a fresh `w` + 8 base36 id. */
 	readonly runId?: string
+	/**
+	 * Continue an earlier run: agents whose prompt and options are unchanged
+	 * return the result saved in the journal instead of running. Build it with
+	 * `loadWorkflowResume`, and pass the same `runId`.
+	 */
+	readonly resume?: WorkflowResumeState
+	/**
+	 * Make the script repeatable, which resuming needs: `Date.now()`,
+	 * `new Date()` with no argument and `Math.random()` throw, and `eval` is
+	 * removed. Default false.
+	 */
+	readonly deterministic?: boolean
+	/** Say in a failure that the run can be resumed. Default false. */
+	readonly canResume?: boolean
+	/** Recorded in `run_started` when the host read the script from a file. */
+	readonly scriptPath?: string
+}
+
+/** Everything a resumed pass needs from the earlier passes of one run. */
+export interface WorkflowResumeState {
+	/** The number of the pass about to run (2 for the first resume). */
+	readonly pass: number
+	readonly results: ReadonlyMap<
+		string,
+		{
+			readonly value: unknown
+			readonly pass: number
+			readonly index: number
+			readonly childSessionId?: string
+		}
+	>
+	/** Keys the earlier passes asked for, finished or not. */
+	readonly seen: ReadonlySet<string>
+	/** Keys whose last outcome was a failure or a skip. */
+	readonly failed: ReadonlySet<string>
+	/** Keys that were asked for again after a result was saved and never finished since. */
+	readonly demoted: ReadonlySet<string>
+	readonly scriptSha256?: string
+	readonly previousFinish: WorkflowFinishStatus | 'unfinished'
+	/** Plain-language findings about the journal (changed, cut short, saved before resuming existed). */
+	readonly problems: readonly string[]
+	readonly resumable: boolean
+	/** First line (1-based) the integrity check could not trust, when any. */
+	readonly brokenAt?: number
+}
+
+/** A journal that can be read back, with its integrity checked. */
+export interface WorkflowJournalReader {
+	read(): Promise<CheckedWorkflowJournal>
+}
+
+/** A journal record as written by `FileWorkflowJournal`: numbered and chained to the line before it. */
+export type ChainedWorkflowJournalRecord = WorkflowJournalRecord & {
+	readonly seq: number
+	readonly prev: string
+}
+
+/** What reading a journal found. Only `records` can be trusted. */
+export interface CheckedWorkflowJournal {
+	/** Records that passed the integrity check, in order. */
+	readonly records: readonly ChainedWorkflowJournalRecord[]
+	/** The journal was written before records were chained; it can be shown but not resumed. */
+	readonly legacy: boolean
+	/** The last write was cut off mid-line and was ignored. */
+	readonly tornTail: boolean
+	/** First line (1-based) that failed the check, when lines were changed, removed or cut short. */
+	readonly brokenAt?: number
+	/** Sequence number and hash the next record must chain from. */
+	readonly lastSeq: number
+	readonly lastHash: string
+	/** The file ends in a newline (false after a torn write). */
+	readonly endsWithNewline: boolean
+	/** Records of a legacy journal, for display only. */
+	readonly untrusted: readonly WorkflowJournalRecord[]
 }
 
 export interface WorkflowRunResult {

package/src/index.ts

@@ -41,10 +41,27 @@ export type {
 	MonitorStreamOptions,
 	MonitorStreamStats,
 } from './runtime/jobs/monitor-stream.js'
+export { WakeBudget, wakeBudgetFromEnv } from './runtime/jobs/wake-budget.js'
 export {
 	createBackgroundJobId,
 	isBackgroundJobId,
 } from './runtime/jobs/job-id.js'
+// Three facts about a running item (where it is, when it last progressed,
+// whether it is alive) and the one verdict derived from them.
+export {
+	LIVENESS_QUIET_MS,
+	LIVENESS_STALLED_MS,
+	formatLivenessAge,
+	formatLivenessLine,
+	judgeLiveness,
+} from './runtime/jobs/liveness.js'
+export type {
+	Liveness,
+	LivenessInput,
+	LivenessKind,
+	LivenessThresholds,
+	LivenessVerdict,
+} from './runtime/jobs/liveness.js'
 export type {
 	BackgroundJob,
 	ForegroundCommand,

package/src/manager/session/turn-recorder.ts

@@ -130,6 +130,7 @@ const TURN_BOUND_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<SessionEve
 	'hosted_tool',
 	'provider_retry',
 	'provider_fallback',
+	'model_refusal',
 	'tool_completed',
 	'user_question_asked',
 	'user_question_answered',

package/src/plugin/compat.ts

@@ -0,0 +1,173 @@
+import type { PluginManifest } from '../types/plugin/index.js'
+
+/**
+ * Whether a plugin can run on this machine and this runtime, decided from what
+ * its manifest declares. A manifest that declares nothing is compatible with
+ * everything, so every plugin written before these fields existed loads as it did.
+ */
+
+type Triple = readonly [number, number, number]
+
+interface Parsed {
+	readonly triple: Triple
+	/** The prerelease tag (`rc.1`), or undefined for a release. */
+	readonly pre: string | undefined
+	/** How many numeric parts were written: `1` is 1, `1.4` is 2, `1.4.2` is 3. */
+	readonly written: number
+}
+
+const VERSION_PATTERN =
+	/^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/i
+
+function parseVersion(text: string): Parsed | undefined {
+	const match = VERSION_PATTERN.exec(text.trim())
+	if (!match) return undefined
+	const part = (value: string | undefined): number =>
+		value === undefined || value === 'x' || value === '*' ? 0 : Number(value)
+	const written = [match[1], match[2], match[3]].filter(
+		(p) => p !== undefined && p !== 'x' && p !== '*',
+	).length
+	return {
+		triple: [Number(match[1]), part(match[2]), part(match[3])],
+		pre: match[4],
+		written,
+	}
+}
+
+function compareTriples(a: Triple, b: Triple): number {
+	for (let i = 0; i < 3; i++) {
+		const diff = (a[i] as number) - (b[i] as number)
+		if (diff !== 0) return diff
+	}
+	return 0
+}
+
+/** Full precedence: a release is above any prerelease of the same numbers. */
+function compare(a: Parsed, b: Parsed): number {
+	const order = compareTriples(a.triple, b.triple)
+	if (order !== 0) return order
+	if (a.pre === b.pre) return 0
+	if (a.pre === undefined) return 1
+	if (b.pre === undefined) return -1
+	return a.pre < b.pre ? -1 : 1
+}
+
+/**
+ * The first version a `^` or `~` range excludes, from how many parts were
+ * written. `^1` and `~1` stop below 2.0.0; `~1.4` and `~1.4.2` below 1.5.0;
+ * `^0` below 1.0.0, `^0.2` below 0.3.0, `^0.0.3` below 0.0.4.
+ */
+function upperBound(operator: '^' | '~', target: Parsed): Triple {
+	const [major, minor, patch] = target.triple
+	if (operator === '~') return target.written <= 1 ? [major + 1, 0, 0] : [major, minor + 1, 0]
+	if (major > 0 || target.written <= 1) return [major + 1, 0, 0]
+	if (minor > 0 || target.written === 2) return [0, minor + 1, 0]
+	return [0, 0, patch + 1]
+}
+
+/** One comparator such as `>=1.2.0`, `^2`, `~1.4` or `3.1.0`; undefined when unreadable. */
+function satisfiesComparator(version: Parsed, token: string): boolean | undefined {
+	const op = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(token)
+	if (!op) return undefined
+	const operator = op[1] ?? '='
+	const target = parseVersion(op[2] as string)
+	if (!target) return undefined
+	const order = compare(version, target)
+	switch (operator) {
+		case '>=':
+			return order >= 0
+		case '<=':
+			return order <= 0
+		case '>':
+			return order > 0
+		case '<':
+			return order < 0
+		case '^':
+		case '~':
+			// The upper bound is compared on the numbers alone, so a prerelease of the
+			// next major (`2.0.0-rc.1`) is not inside `^1`.
+			return order >= 0 && compareTriples(version.triple, upperBound(operator, target)) < 0
+		default: {
+			// A bare `1` or `1.4` names a whole major or minor.
+			if (version.pre !== target.pre) return false
+			const written = (op[2] as string).replace(/^v/i, '').split(/[-+]/)[0] as string
+			const parts = written.split('.').filter((p) => p !== 'x' && p !== '*')
+			return parts.every((p, i) => Number(p) === version.triple[i])
+		}
+	}
+}
+
+/**
+ * Whether `version` satisfies `range`. Supports space-separated comparators
+ * that must all hold, `||` between alternatives, and the operators `>=`, `>`,
+ * `<=`, `<`, `=`, `^` and `~`. Returns undefined when the range cannot be read.
+ */
+export function versionSatisfies(versionText: string, range: string): boolean | undefined {
+	const version = parseVersion(versionText)
+	if (!version) return undefined
+	let readable = true
+	let any = false
+	for (const alternative of range.split('||')) {
+		// Join an operator written apart from its number (">= 1.2") first.
+		const tokens = alternative
+			.trim()
+			.replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1')
+			.split(/\s+/)
+			.filter(Boolean)
+		if (tokens.length === 0) {
+			readable = false
+			continue
+		}
+		let all = true
+		for (const token of tokens) {
+			const ok = satisfiesComparator(version, token)
+			if (ok === undefined) {
+				readable = false
+				all = false
+				break
+			}
+			if (!ok) all = false
+		}
+		if (all) any = true
+	}
+	if (any) return true
+	return readable ? false : undefined
+}
+
+export interface PluginHostFacts {
+	/** The operating system, as `process.platform` names it. Default: this process. */
+	readonly platform?: string
+	/** The Namzu runtime version. Default: this package's own version. */
+	readonly namzuVersion?: string
+}
+
+/**
+ * Refuse a plugin that declares it does not support this platform or this
+ * Namzu version. The reason names the plugin, what it declares and what this
+ * machine is, so a person can act on it without reading the manifest.
+ *
+ * A runtime whose own version is unknown (`0.0.0`, the placeholder a bundle
+ * reports when it cannot read its package file) is not held against the range:
+ * refusing every plugin on a guess would be worse than admitting one.
+ */
+export function assertCompatible(manifest: PluginManifest, host: Required<PluginHostFacts>): void {
+	const platforms = manifest.platforms
+	if (platforms && platforms.length > 0 && !platforms.includes(host.platform)) {
+		throw new Error(
+			`Plugin "${manifest.name}" supports only ${platforms.join(', ')}, and this machine runs ${host.platform}, so it was not loaded.`,
+		)
+	}
+	const range = manifest.engines?.namzu
+	if (range === undefined || host.namzuVersion === '0.0.0') return
+	const ok = versionSatisfies(host.namzuVersion, range)
+	if (ok === undefined) {
+		throw new Error(
+			`Plugin "${manifest.name}" declares the Namzu version range "${range}", which cannot be read, so it was not loaded. Write it like ">=60.0.0" or "^60.1.0".`,
+		)
+	}
+	if (!ok) {
+		throw new Error(
+			`Plugin "${manifest.name}" needs Namzu ${range}, and this is Namzu ${host.namzuVersion}, so it was not loaded. Update Namzu or use a plugin version made for this one.`,
+		)
+	}
+}