@namzu/sdk 50.1.0 → 51.1.0

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
+}

package/src/execution/workflow/phases.ts

@@ -0,0 +1,91 @@
+import { normalizePhaseTitle } from './meta.js'
+import type {
+	WorkflowAgentState,
+	WorkflowPhaseMeta,
+	WorkflowPhaseStatus,
+	WorkflowPhaseSummary,
+} from './types.js'
+
+export interface PhaseRecord {
+	readonly index: number
+	readonly title: string
+	readonly declared: boolean
+}
+
+/**
+ * Phase titles of one run. A title is the only grouping key: the same title
+ * is the same group. Indexes are 1-based first-seen order, declared titles
+ * first. `register` reports whether the title was announced just now.
+ */
+export class PhaseRegistry {
+	private readonly byTitle = new Map<string, PhaseRecord>()
+
+	register(rawTitle: string, declared = false): { phase: PhaseRecord; isNew: boolean } {
+		const title = normalizePhaseTitle(rawTitle)
+		const existing = this.byTitle.get(title)
+		if (existing) return { phase: existing, isNew: false }
+		const phase = { index: this.byTitle.size + 1, title, declared }
+		this.byTitle.set(title, phase)
+		return { phase, isNew: true }
+	}
+
+	all(): PhaseRecord[] {
+		return [...this.byTitle.values()]
+	}
+}
+
+export interface PhaseAgentView {
+	readonly phaseIndex?: number
+	readonly state: WorkflowAgentState
+	readonly tokens: number
+}
+
+function statusOf(total: number, done: number, failed: number): WorkflowPhaseStatus {
+	if (total === 0) return 'not-started'
+	if (done + failed === total) return failed > 0 ? 'failed' : 'done'
+	return 'running'
+}
+
+/**
+ * Per-phase status from the agents seen so far, in phase order. A phase with
+ * no agent yet is `not-started`. When no agent belongs to any phase (and
+ * nothing is declared) the run shows one derived group, "Agents"; agents
+ * without a phase next to phased ones also land in "Agents", listed last.
+ */
+export function summarizeWorkflowPhases(
+	declared: readonly WorkflowPhaseMeta[],
+	phases: readonly PhaseRecord[],
+	agents: readonly PhaseAgentView[],
+): WorkflowPhaseSummary[] {
+	const detail = new Map(declared.map((p) => [normalizePhaseTitle(p.title), p.detail]))
+	const summarize = (
+		index: number,
+		title: string,
+		members: readonly PhaseAgentView[],
+		extra?: string,
+	): WorkflowPhaseSummary => {
+		const done = members.filter((a) => a.state === 'done').length
+		const failed = members.filter((a) => a.state === 'error').length
+		return {
+			index,
+			title,
+			...(extra !== undefined ? { detail: extra } : {}),
+			status: statusOf(members.length, done, failed),
+			agents: members.length,
+			done,
+			failed,
+			tokens: members.reduce((sum, a) => sum + a.tokens, 0),
+		}
+	}
+	const out = phases.map((p) =>
+		summarize(
+			p.index,
+			p.title,
+			agents.filter((a) => a.phaseIndex === p.index),
+			detail.get(p.title),
+		),
+	)
+	const ungrouped = agents.filter((a) => a.phaseIndex === undefined)
+	if (ungrouped.length > 0) out.push(summarize(0, 'Agents', ungrouped))
+	return out
+}

package/src/execution/workflow/prelude.ts

@@ -0,0 +1,135 @@
+/**
+ * The interpreter-side half of the workflow language: `agent`, `parallel`,
+ * `pipeline`, `phase`, `log`, `args` and `budget`.
+ *
+ * This text runs INSIDE the QuickJS interpreter, ahead of the script body,
+ * and is the only place those names are defined. It captures the two bridge
+ * natives (`call`, `print`) in its own closure and deletes them from the
+ * global object, so the script reaches the host only through `agent()`, and
+ * `phase()`/`log()` can only emit well-formed records. None of this is a
+ * security boundary: the host re-validates every request and treats every
+ * printed line as untrusted text. The boundary is the interpreter itself.
+ *
+ * Written with String.raw and no backticks or substitutions so no escaping
+ * layer can change what the interpreter parses.
+ */
+const PRELUDE_SOURCE = String.raw`(function (config) {
+	'use strict';
+	var rawCall = globalThis.call;
+	var rawPrint = globalThis.print;
+	delete globalThis.call;
+	delete globalThis.print;
+	var stringify = JSON.stringify;
+	var spent = { tokensUsed: 0 };
+	var cursor = null;
+	function emit(record) { rawPrint(stringify(record)); }
+	function clean(value, limit) {
+		return String(value).replace(/\s+/g, ' ').trim().slice(0, limit);
+	}
+	function phase(title) {
+		var t = clean(title, 120);
+		if (!t) throw new TypeError('phase() needs a non-empty title.');
+		cursor = t;
+		emit({ k: 'phase', title: t });
+	}
+	function log(message) {
+		emit({ k: 'log', message: String(message).slice(0, 2000) });
+	}
+	function kind(value) {
+		if (value === null) return 'null';
+		if (value === '') return 'an empty string';
+		if (Array.isArray(value)) return 'an array';
+		var t = typeof value;
+		if (t === 'undefined') return 'undefined';
+		if (t === 'object') return typeof value.then === 'function' ? 'a promise' : 'an object';
+		return 'a ' + t;
+	}
+	async function agent(prompt, opts) {
+		if (typeof prompt !== 'string' || prompt.length === 0) {
+			throw new TypeError('agent(prompt, options?): the prompt must be a non-empty string, got ' + kind(prompt));
+		}
+		var o = opts == null ? {} : opts;
+		if (typeof o !== 'object' || Array.isArray(o)) {
+			throw new TypeError('agent(prompt, options?): options must be an object, got ' + kind(o));
+		}
+		var request = { prompt: prompt, cursor: cursor };
+		if (o.label != null) request.label = clean(o.label, 120);
+		if (o.phase != null) request.phase = clean(o.phase, 120);
+		if (o.schema != null) request.schema = o.schema;
+		if (o.agentType != null) request.agentType = clean(o.agentType, 120);
+		if (o.model != null) request.model = clean(o.model, 120);
+		if (o.effort != null) request.effort = clean(o.effort, 32);
+		var reply = await rawCall('agent', request);
+		spent.tokensUsed = reply.t;
+		return reply.v;
+	}
+	async function parallel(thunks) {
+		if (!Array.isArray(thunks)) {
+			throw new TypeError('parallel(thunks): the argument must be an array of functions, got ' + kind(thunks));
+		}
+		for (var p = 0; p < thunks.length; p++) {
+			if (typeof thunks[p] !== 'function') {
+				throw new TypeError('parallel(thunks): item ' + (p + 1) + ' must be a function (wrap the work as () => agent(...)), got ' + kind(thunks[p]));
+			}
+		}
+		return Promise.all(thunks.map(function (t) { return t(); }));
+	}
+	async function pipeline(items) {
+		if (!Array.isArray(items)) {
+			throw new TypeError('pipeline(items, ...stages): the first argument must be an array, got ' + kind(items));
+		}
+		var stages = Array.prototype.slice.call(arguments, 1);
+		for (var s = 0; s < stages.length; s++) {
+			if (typeof stages[s] !== 'function') {
+				throw new TypeError('pipeline(items, ...stages): stage ' + (s + 1) + ' must be a function, got ' + kind(stages[s]));
+			}
+		}
+		return Promise.all(items.map(async function (item, index) {
+			var value = item;
+			for (var i = 0; i < stages.length; i++) {
+				value = await stages[i](value, index, item);
+				if (value === null || value === undefined) return null;
+			}
+			return value;
+		}));
+	}
+	var budget = Object.freeze({
+		get tokensUsed() { return spent.tokensUsed; },
+		get tokenLimit() { return config.tokenLimit === null ? undefined : config.tokenLimit; },
+	});
+	function install(name, value) {
+		Object.defineProperty(globalThis, name, { value: value, writable: false, configurable: false, enumerable: true });
+	}
+	install('agent', agent);
+	install('parallel', parallel);
+	install('pipeline', pipeline);
+	install('phase', phase);
+	install('log', log);
+	install('budget', budget);
+	install('args', config.args);
+})`
+
+/**
+ * Lines the prelude occupies in the interpreter source, plus the newline that
+ * joins it to the script body: subtract this from an interpreter line number
+ * to get the line in the script the author wrote.
+ */
+export function preludeLineCount(config: {
+	args: unknown
+	tokenLimit: number | null
+}): number {
+	return buildPrelude(config).split('\n').length
+}
+
+/** Source that installs the workflow globals, ready to prepend to a script body. */
+export function buildPrelude(config: {
+	args: unknown
+	tokenLimit: number | null
+}): string {
+	const literal = JSON.stringify(config)
+		.split(String.fromCharCode(0x2028))
+		.join('\\u2028')
+		.split(String.fromCharCode(0x2029))
+		.join('\\u2029')
+	return `${PRELUDE_SOURCE}(${literal});`
+}