@namzu/sdk 50.1.0 → 51.0.0

package/src/execution/code-runtime/types.ts

@@ -83,11 +83,47 @@ export interface RunCodeOptions {
 	 */
 	readonly maxOutputBytes: number
 	readonly signal?: AbortSignal
+	/**
+	 * Replace the single wall-clock interrupt with a CPU budget.
+	 *
+	 * By default `timeoutMs` bounds synchronous interpreter execution as well
+	 * as the whole run, so a program waiting on slow host calls is stopped at
+	 * the same deadline as one spinning in a loop. A host that legitimately
+	 * awaits long host operations (a workflow awaiting subagents) sets this:
+	 * the interpreter is then interrupted when ONE synchronous slice (the time
+	 * between entering the interpreter and handing control back) exceeds
+	 * `sliceMs`, or all slices together exceed `totalMs`. Time spent awaiting
+	 * the host is not counted. `timeoutMs` still bounds the run's wall clock.
+	 */
+	readonly cpuLimits?: { readonly sliceMs: number; readonly totalMs: number }
+	/**
+	 * Called with each line the program prints, in order, as it is printed and
+	 * within `maxOutputBytes`. A line is data, not a capability: the callback
+	 * must treat it as untrusted text.
+	 */
+	readonly onOutput?: (line: string) => void
+}
+
+export interface CodeFrame {
+	readonly line: number
+	readonly column: number
 }
 
 export type CodeRunOutcome =
 	| { readonly status: 'completed'; readonly result: unknown }
-	| { readonly status: 'failed'; readonly error: string }
+	| {
+			readonly status: 'failed'
+			readonly error: string
+			/** The thrown value's `name`, when it was an error object. */
+			readonly errorName?: string
+			/**
+			 * Where the interpreter says the program failed: innermost first, line and
+			 * column counted in the submitted `source` (1-based). Absent when the
+			 * interpreter gave no location (a non-error was thrown, or the failure was
+			 * not in the program).
+			 */
+			readonly frames?: readonly CodeFrame[]
+	  }
 	| { readonly status: 'timed-out' }
 	| { readonly status: 'cancelled' }
 

package/src/execution/code-runtime/worker-program.ts

@@ -18,7 +18,33 @@ async function main() {
 	const runtime = module.newRuntime()
 	runtime.setMemoryLimit(limits.memoryLimitBytes)
 	runtime.setMaxStackSize(512 * 1024)
-	runtime.setInterruptHandler(() => Date.now() >= workerData.deadline)
+	// Two ways to bound a program's synchronous execution. Default: one wall
+	// deadline for the whole run. With \`cpu\`: a budget per synchronous slice
+	// (each entry into the interpreter) and a total across slices, so a program
+	// that spends hours AWAITING the host is not stopped, but a busy loop is.
+	const cpu = workerData.cpu
+	let sliceDepth = 0
+	let sliceStart = 0
+	let cpuUsed = 0
+	let interrupted = false
+	function inSlice(fn) {
+		if (!cpu) return fn()
+		if (sliceDepth === 0) sliceStart = Date.now()
+		sliceDepth++
+		try { return fn() }
+		finally {
+			sliceDepth--
+			if (sliceDepth === 0) cpuUsed += Date.now() - sliceStart
+		}
+	}
+	runtime.setInterruptHandler(() => {
+		const now = Date.now()
+		const stop = cpu
+			? sliceDepth > 0 && (now - sliceStart >= cpu.sliceMs || cpuUsed + (now - sliceStart) >= cpu.totalMs)
+			: now >= workerData.deadline
+		if (stop) interrupted = true
+		return stop
+	})
 	const vm = runtime.newContext()
 	const pending = new Map()
 	let nextId = 0
@@ -68,6 +94,8 @@ async function main() {
 	const decode = keep(vm.evalCode('(function () { const parse = JSON.parse; return function(value) { return parse(value); }; })()'))
 	const errorText = keep(vm.evalCode('(function () { const string = String; return function(error) { try { return typeof error.message === "string" ? error.message : string(error); } catch { return "The program failed."; } }; })()'))
 
+	const errorMeta = keep(vm.evalCode('(function () { const string = String; const stringify = JSON.stringify; return function(error) { try { return stringify({ name: typeof error.name === "string" ? error.name : "", stack: typeof error.stack === "string" ? error.stack : "" }); } catch { return "{}"; } }; })()'))
+
 	function textValue(handle, maximum) {
 		const length = vm.getProp(handle, 'length')
 		try {
@@ -97,6 +125,24 @@ async function main() {
 		catch { return 'The program failed with an oversized error.' }
 		finally { result.value.dispose() }
 	}
+	// The guest error's message plus its name and stack, so the host can say
+	// where in the program it failed. Stack text is untrusted and only parsed
+	// for line and column numbers.
+	function failureError(handle) {
+		const error = new Error(failureText(handle))
+		try {
+			const result = vm.callFunction(errorMeta, vm.undefined, handle)
+			if (result.error) result.error.dispose()
+			else {
+				try {
+					const meta = JSON.parse(textValue(result.value, 4096))
+					error.guestName = String(meta.name || '').slice(0, 64)
+					error.guestStack = String(meta.stack || '').slice(0, 3072)
+				} finally { result.value.dispose() }
+			}
+		} catch {}
+		return error
+	}
 	function dispose() {
 		for (const deferred of pending.values()) deferred.dispose()
 		pending.clear()
@@ -114,9 +160,9 @@ async function main() {
 		parentPort.postMessage(message)
 	}
 	function fail(error) {
-		finish(Date.now() >= workerData.deadline
+		finish(interrupted || Date.now() >= workerData.deadline
 			? { kind: 'timed-out' }
-			: { kind: 'error', error: String(error && error.message || error).slice(0, 4096) })
+			: { kind: 'error', error: String(error && error.message || error).slice(0, 4096), name: error && error.guestName, stack: error && error.guestStack })
 	}
 	function schedule() {
 		if (ended || scheduled) return
@@ -125,13 +171,22 @@ async function main() {
 	}
 	function pump() {
 		if (ended || pumping) return
+		inSlice(pumpOnce)
+	}
+	function pumpOnce() {
 		pumping = true
 		try {
+			// A program that never lets one slice run long (a loop of awaited
+			// microtasks) is still bounded by the total CPU budget.
+			if (cpu && cpuUsed >= cpu.totalMs) {
+				interrupted = true
+				throw new Error('The program used its CPU budget.')
+			}
 			const jobs = runtime.executePendingJobs(32)
 			if (jobs.error) {
-				const error = failureText(jobs.error)
+				const error = failureError(jobs.error)
 				jobs.error.dispose()
-				throw new Error(error)
+				throw error
 			}
 			const state = vm.getPromiseState(program)
 			if (state.type === 'fulfilled') {
@@ -141,9 +196,9 @@ async function main() {
 				finish({ kind: 'done', json })
 			} else if (state.type === 'rejected') {
 				let error
-				try { error = failureText(state.error) }
+				try { error = failureError(state.error) }
 				finally { state.error.dispose() }
-				fail(new Error(error))
+				fail(error)
 			} else if (runtime.hasPendingJob()) schedule()
 		} catch (error) { fail(error) }
 		finally { pumping = false }
@@ -207,6 +262,7 @@ async function main() {
 		if (!deferred) return
 		pending.delete(message.id)
 		try {
+			inSlice(() => {
 			if (message.ok) {
 				let value = vm.undefined
 				if (message.json !== undefined) {
@@ -223,16 +279,19 @@ async function main() {
 				error.dispose()
 			}
 			deferred.dispose()
+			})
 			schedule()
 		} catch (error) { deferred.dispose(); fail(error) }
 	})
 	try {
-		const result = vm.evalCode('(async () => {\\n' + workerData.source + '\\n})()', 'model-program.js')
-		if (result.error) {
-			const error = failureText(result.error)
-			result.error.dispose()
-			fail(new Error(error))
-		} else { program = result.value; pump() }
+		inSlice(() => {
+			const result = vm.evalCode('(async () => {\\n' + workerData.source + '\\n})()', 'model-program.js')
+			if (result.error) {
+				const error = failureError(result.error)
+				result.error.dispose()
+				fail(error)
+			} else { program = result.value; pump() }
+		})
 	} catch (error) { fail(error) }
 }
 main().catch((error) => parentPort.postMessage({ kind: 'error', error: String(error && error.message || error).slice(0, 4096) }))

package/src/execution/code-runtime/worker.ts

@@ -3,6 +3,7 @@ import { Worker } from 'node:worker_threads'
 
 import { encodeCodeValue } from './json-value.js'
 import {
+	type CodeFrame,
 	type CodeRunResult,
 	type CodeRuntime,
 	HostCallDeniedError,
@@ -10,6 +11,30 @@ import {
 } from './types.js'
 import { QUICKJS_WORKER_SOURCE } from './worker-program.js'
 
+/** The worker wraps the program in `(async () => {` plus a newline: one line. */
+const WRAPPER_LINES = 1
+const FRAME_PATTERN = /model-program\.js:(\d+):(\d+)/g
+
+function failureLocation(
+	name: unknown,
+	stack: unknown,
+	sourceLines: number,
+): { errorName?: string; frames?: readonly CodeFrame[] } {
+	const frames: CodeFrame[] = []
+	if (typeof stack === 'string') {
+		for (const match of stack.matchAll(FRAME_PATTERN)) {
+			const line = Number(match[1]) - WRAPPER_LINES
+			// The wrapper's own lines (its opening, and the closing after the source)
+			// are not in what the caller submitted.
+			if (line >= 1 && line <= sourceLines) frames.push({ line, column: Number(match[2]) })
+		}
+	}
+	return {
+		...(typeof name === 'string' && name !== '' ? { errorName: name } : {}),
+		...(frames.length > 0 ? { frames } : {}),
+	}
+}
+
 const requireFromSdk = createRequire(import.meta.url)
 
 /** Resource policy for one fresh QuickJS worker execution. */
@@ -74,6 +99,10 @@ export class WorkerCodeRuntime implements CodeRuntime {
 	async run(options: RunCodeOptions): Promise<CodeRunResult> {
 		validateInteger('timeoutMs', options.timeoutMs, 1, 2_147_483_647)
 		validateInteger('maxOutputBytes', options.maxOutputBytes, 0, 16 * 1024 * 1024)
+		if (options.cpuLimits) {
+			validateInteger('cpuLimits.sliceMs', options.cpuLimits.sliceMs, 1, 2_147_483_647)
+			validateInteger('cpuLimits.totalMs', options.cpuLimits.totalMs, 1, 2_147_483_647)
+		}
 		const allowed = new Set(options.allowedCalls)
 		const calls: { name: string; ok: boolean }[] = []
 		let output = ''
@@ -120,6 +149,11 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				}
 				output = next
 				printCount++
+				try {
+					options.onOutput?.(line)
+				} catch {
+					// A listener bug must not decide the program's outcome.
+				}
 			}
 		}
 
@@ -131,6 +165,7 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				variantPath: requireFromSdk.resolve('@jitl/quickjs-wasmfile-release-sync'),
 				limits: this.limits,
 				maxOutputBytes: options.maxOutputBytes,
+				cpu: options.cpuLimits,
 				deadline: Date.now() + options.timeoutMs,
 			},
 			// Trusted bootstrap requires Node; guest code runs only inside QuickJS.
@@ -344,7 +379,11 @@ export class WorkerCodeRuntime implements CodeRuntime {
 
 				if (message.kind === 'error') {
 					finish({
-						outcome: { status: 'failed', error: String(message.error) },
+						outcome: {
+							status: 'failed',
+							error: String(message.error),
+							...failureLocation(message.name, message.stack, options.source.split('\n').length),
+						},
 						output,
 						outputTruncated: truncated,
 						calls,

package/src/execution/workflow/errors.ts

@@ -0,0 +1,7 @@
+/** A script that cannot run: bad `meta`, too large, bad `args`. Nothing started. */
+export class WorkflowScriptError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'WorkflowScriptError'
+	}
+}

package/src/execution/workflow/index.ts

@@ -0,0 +1,8 @@
+export { WorkflowScriptError } from './errors.js'
+export { FileWorkflowJournal } from './journal.js'
+export { parseWorkflowMeta } from './meta.js'
+export { summarizeWorkflowPhases } from './phases.js'
+export type { PhaseAgentView, PhaseRecord } from './phases.js'
+export { resolveWorkflowLimits, WORKFLOW_HOST_CALL, WorkflowRuntime } from './runtime.js'
+export type { WorkflowRuntimeOptions } from './runtime.js'
+export type * from './types.js'

package/src/execution/workflow/journal.ts

@@ -0,0 +1,46 @@
+import { createHash } from 'node:crypto'
+import { appendFile, mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { WorkflowJournal, WorkflowJournalRecord } from './types.js'
+
+export function sha256(text: string): string {
+	return createHash('sha256').update(text).digest('hex')
+}
+
+/** The first `max` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export function preview(text: string, max = 500): string {
+	if (text.length <= max) return text
+	let end = max
+	const last = text.charCodeAt(end - 1)
+	if (last >= 0xd800 && last <= 0xdbff) end--
+	return `${text.slice(0, end)}…`
+}
+
+/**
+ * A journal in a directory: `script.js` (the exact script text, mode 0600)
+ * and `journal.jsonl` (one JSON record per line, append-only). The caller
+ * chooses the directory, normally `<session>/runs/<runId>/workflow/`.
+ */
+export class FileWorkflowJournal implements WorkflowJournal {
+	private ready: Promise<void> | undefined
+
+	constructor(private readonly dir: string) {}
+
+	private ensure(): Promise<void> {
+		this.ready ??= mkdir(this.dir, { recursive: true, mode: 0o700 }).then(() => undefined)
+		return this.ready
+	}
+
+	async writeScript(source: string): Promise<void> {
+		await this.ensure()
+		await writeFile(join(this.dir, 'script.js'), source, { mode: 0o600 })
+	}
+
+	async append(record: WorkflowJournalRecord): Promise<void> {
+		await this.ensure()
+		await appendFile(join(this.dir, 'journal.jsonl'), `${JSON.stringify(record)}\n`, {
+			mode: 0o600,
+		})
+	}
+}

package/src/execution/workflow/meta.ts

@@ -0,0 +1,316 @@
+import { WorkflowScriptError } from './errors.js'
+import type { WorkflowMeta, WorkflowPhaseMeta } from './types.js'
+
+const MAX_META_BYTES = 16 * 1024
+const MAX_DEPTH = 8
+const MAX_PHASES = 50
+const KEYWORD = /export\s+const\s+meta\s*=/y
+
+type Literal = string | number | boolean | null | Literal[] | { [key: string]: Literal }
+
+/**
+ * Reads the `export const meta = {...}` literal WITHOUT running the script.
+ *
+ * The statement must be the first one in the file (comments and blank lines
+ * before it are fine) and its value must be a pure literal: strings, numbers,
+ * booleans, null, arrays and objects. Variables, calls, spreads, template
+ * substitutions and computed keys are refused with a plain message, because
+ * the operator reviews this literal BEFORE the script is allowed to run.
+ */
+class LiteralParser {
+	pos = 0
+
+	constructor(private readonly source: string) {}
+
+	fail(what: string): never {
+		const before = this.source.slice(0, this.pos)
+		const line = before.split('\n').length
+		const column = this.pos - before.lastIndexOf('\n')
+		throw new WorkflowScriptError(`${what} (line ${line}, column ${column}).`)
+	}
+
+	skipTrivia(): void {
+		const s = this.source
+		for (;;) {
+			const c = s[this.pos]
+			if (c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '') this.pos++
+			else if (c === '/' && s[this.pos + 1] === '/') {
+				while (this.pos < s.length && s[this.pos] !== '\n') this.pos++
+			} else if (c === '/' && s[this.pos + 1] === '*') {
+				const end = s.indexOf('*/', this.pos + 2)
+				if (end === -1) this.fail('Unterminated comment')
+				this.pos = end + 2
+			} else return
+		}
+	}
+
+	private describe(): string {
+		const snippet = this.source.slice(this.pos, this.pos + 24).split('\n')[0]
+		return snippet ? `"${snippet}"` : 'the end of the script'
+	}
+
+	private notLiteral(): never {
+		return this.fail(
+			`\`meta\` must be a pure literal (no variables, calls, spreads or expressions); found ${this.describe()}`,
+		)
+	}
+
+	value(depth: number): Literal {
+		if (depth > MAX_DEPTH) this.fail('`meta` is nested too deeply')
+		this.skipTrivia()
+		const c = this.source[this.pos]
+		if (c === '{') return this.object(depth)
+		if (c === '[') return this.array(depth)
+		if (c === '"' || c === "'") return this.string(c)
+		if (c === '`') return this.string('`')
+		if (c === '-' || c === '.' || (c !== undefined && c >= '0' && c <= '9')) return this.number()
+		for (const [word, value] of [
+			['true', true],
+			['false', false],
+			['null', null],
+		] as const) {
+			if (
+				this.source.startsWith(word, this.pos) &&
+				!/[\w$]/.test(this.source[this.pos + word.length] ?? '')
+			) {
+				this.pos += word.length
+				return value
+			}
+		}
+		return this.notLiteral()
+	}
+
+	private number(): number {
+		const match = /-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/y
+		match.lastIndex = this.pos
+		const found = match.exec(this.source)
+		if (!found) return this.notLiteral()
+		this.pos += found[0].length
+		if (/[\w$]/.test(this.source[this.pos] ?? '')) return this.notLiteral()
+		return Number(found[0])
+	}
+
+	private string(quote: string): string {
+		const s = this.source
+		this.pos++
+		let out = ''
+		for (;;) {
+			const c = s[this.pos]
+			if (c === undefined) return this.fail('Unterminated string in `meta`')
+			if (c === quote) {
+				this.pos++
+				return out
+			}
+			if (c === '\n' && quote !== '`') return this.fail('Unterminated string in `meta`')
+			if (quote === '`' && c === '$' && s[this.pos + 1] === '{') {
+				return this.fail('`meta` strings cannot use `${...}` substitutions')
+			}
+			if (c !== '\\') {
+				out += c
+				this.pos++
+				continue
+			}
+			const e = s[this.pos + 1]
+			this.pos += 2
+			const simple: Record<string, string> = {
+				n: '\n',
+				t: '\t',
+				r: '\r',
+				b: '\b',
+				f: '\f',
+				v: '\v',
+				'0': '\0',
+				'\\': '\\',
+				"'": "'",
+				'"': '"',
+				'`': '`',
+				$: '$',
+			}
+			if (e !== undefined && e in simple) out += simple[e]
+			else if (e === '\n') continue
+			else if (e === 'u' && s[this.pos] === '{') {
+				const end = s.indexOf('}', this.pos)
+				const hex = s.slice(this.pos + 1, end)
+				if (end === -1 || !/^[0-9a-fA-F]{1,6}$/.test(hex) || Number.parseInt(hex, 16) > 0x10ffff) {
+					return this.fail('Bad escape in a `meta` string')
+				}
+				out += String.fromCodePoint(Number.parseInt(hex, 16))
+				this.pos = end + 1
+			} else if (e === 'u' || e === 'x') {
+				const len = e === 'u' ? 4 : 2
+				const hex = s.slice(this.pos, this.pos + len)
+				if (!new RegExp(`^[0-9a-fA-F]{${len}}$`).test(hex))
+					return this.fail('Bad escape in a `meta` string')
+				out += String.fromCharCode(Number.parseInt(hex, 16))
+				this.pos += len
+			} else return this.fail('Bad escape in a `meta` string')
+		}
+	}
+
+	private array(depth: number): Literal[] {
+		this.pos++
+		const out: Literal[] = []
+		for (;;) {
+			this.skipTrivia()
+			if (this.source[this.pos] === ']') {
+				this.pos++
+				return out
+			}
+			out.push(this.value(depth + 1))
+			this.skipTrivia()
+			if (this.source[this.pos] === ',') this.pos++
+			else if (this.source[this.pos] !== ']') return this.notLiteral()
+		}
+	}
+
+	private object(depth: number): { [key: string]: Literal } {
+		this.pos++
+		const out: { [key: string]: Literal } = Object.create(null)
+		for (;;) {
+			this.skipTrivia()
+			const c = this.source[this.pos]
+			if (c === '}') {
+				this.pos++
+				return out
+			}
+			let key: string
+			if (c === '"' || c === "'") key = this.string(c)
+			else {
+				const ident = /[A-Za-z_$][\w$]*/y
+				ident.lastIndex = this.pos
+				const found = ident.exec(this.source)
+				if (!found) return this.notLiteral()
+				key = found[0]
+				this.pos += key.length
+			}
+			if (key === '__proto__') this.fail('`meta` cannot define `__proto__`')
+			if (key in out) this.fail(`\`meta\` repeats the key "${key}"`)
+			this.skipTrivia()
+			if (this.source[this.pos] !== ':') return this.notLiteral()
+			this.pos++
+			out[key] = this.value(depth + 1)
+			this.skipTrivia()
+			if (this.source[this.pos] === ',') this.pos++
+			else if (this.source[this.pos] !== '}') return this.notLiteral()
+		}
+	}
+}
+
+function text(
+	value: Literal | undefined,
+	field: string,
+	max: number,
+	required: boolean,
+): string | undefined {
+	if (value === undefined) {
+		if (required) throw new WorkflowScriptError(`\`meta.${field}\` is required.`)
+		return undefined
+	}
+	if (typeof value !== 'string' || value.trim() === '') {
+		throw new WorkflowScriptError(`\`meta.${field}\` must be a non-empty string.`)
+	}
+	if (value.length > max) {
+		throw new WorkflowScriptError(`\`meta.${field}\` is longer than ${max} characters.`)
+	}
+	return value
+}
+
+function onlyKeys(
+	object: { [key: string]: Literal },
+	allowed: readonly string[],
+	where: string,
+): void {
+	for (const key of Object.keys(object)) {
+		if (!allowed.includes(key)) {
+			throw new WorkflowScriptError(
+				`\`${where}\` has an unknown key "${key}". Allowed: ${allowed.join(', ')}.`,
+			)
+		}
+	}
+}
+
+function isRecord(value: Literal | undefined): value is { [key: string]: Literal } {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function normalizePhaseTitle(value: string): string {
+	return value.replace(/\s+/g, ' ').trim().slice(0, 120)
+}
+
+function toMeta(literal: Literal): WorkflowMeta {
+	if (!isRecord(literal)) throw new WorkflowScriptError('`meta` must be an object literal.')
+	onlyKeys(literal, ['name', 'description', 'whenToUse', 'phases'], 'meta')
+	const name = text(literal.name, 'name', 80, true) as string
+	const description = text(literal.description, 'description', 500, true) as string
+	const whenToUse = text(literal.whenToUse, 'whenToUse', 500, false)
+	const phases: WorkflowPhaseMeta[] = []
+	if (literal.phases !== undefined) {
+		if (!Array.isArray(literal.phases)) {
+			throw new WorkflowScriptError('`meta.phases` must be an array of { title, detail?, model? }.')
+		}
+		if (literal.phases.length > MAX_PHASES) {
+			throw new WorkflowScriptError(`\`meta.phases\` lists more than ${MAX_PHASES} phases.`)
+		}
+		const seen = new Set<string>()
+		for (const [i, entry] of literal.phases.entries()) {
+			if (!isRecord(entry)) {
+				throw new WorkflowScriptError(`\`meta.phases[${i}]\` must be an object with a title.`)
+			}
+			onlyKeys(entry, ['title', 'detail', 'model'], `meta.phases[${i}]`)
+			const raw = text(entry.title, `phases[${i}].title`, 120, true) as string
+			const title = normalizePhaseTitle(raw)
+			if (seen.has(title)) {
+				throw new WorkflowScriptError(`\`meta.phases\` repeats the title "${title}".`)
+			}
+			seen.add(title)
+			const detail = text(entry.detail, `phases[${i}].detail`, 300, false)
+			const model = text(entry.model, `phases[${i}].model`, 120, false)
+			phases.push({
+				title,
+				...(detail !== undefined ? { detail } : {}),
+				...(model !== undefined ? { model } : {}),
+			})
+		}
+	}
+	return {
+		name,
+		description,
+		...(whenToUse !== undefined ? { whenToUse } : {}),
+		phases,
+	}
+}
+
+/**
+ * Split a script into its `meta` and its body. The body keeps the script's
+ * line breaks (the meta statement is blanked, not removed) so an error line
+ * still points at the author's text.
+ */
+export function splitWorkflowScript(source: string): { meta: WorkflowMeta; body: string } {
+	const parser = new LiteralParser(source)
+	parser.skipTrivia()
+	KEYWORD.lastIndex = parser.pos
+	const found = KEYWORD.exec(source)
+	if (!found) {
+		throw new WorkflowScriptError(
+			'A workflow script must start with `export const meta = { name, description, phases? }`.',
+		)
+	}
+	const start = parser.pos
+	parser.pos = start + found[0].length
+	const literal = parser.value(0)
+	parser.skipTrivia()
+	if (source[parser.pos] === ';') parser.pos++
+	if (Buffer.byteLength(source.slice(start, parser.pos)) > MAX_META_BYTES) {
+		throw new WorkflowScriptError(`\`meta\` is larger than ${MAX_META_BYTES} bytes.`)
+	}
+	const meta = toMeta(literal)
+	return {
+		meta,
+		body: source.slice(0, parser.pos).replace(/[^\n]/g, ' ') + source.slice(parser.pos),
+	}
+}
+
+/** Parse `meta` from a script without executing it. Throws {@link WorkflowScriptError}. */
+export function parseWorkflowMeta(source: string): WorkflowMeta {
+	return splitWorkflowScript(source).meta
+}