@namzu/sdk 50.1.0 → 51.0.0

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});`
+}