one-code-extension 0.1.0

package/extensions/workflow/run-manager.ts

@@ -0,0 +1,306 @@
+/**
+ * Run lifecycle: registry of live/finished runs, background execution,
+ * abort layering, journaling glue, and resume seeding.
+ *
+ * Each run persists under `<sessionDir>/workflows/<runId>/` — `script.js`
+ * (the exact source executed) and `journal.jsonl` (completed agent calls).
+ * The directory is keyed by cwd via pi's session dir, so `resumeFromRunId`
+ * works across sessions and restarts. Background runs do NOT survive the
+ * process: session_shutdown aborts them (index.ts wires that); the journal
+ * makes an aborted run cheap to resume.
+ */
+
+import { EventEmitter } from "node:events";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { AgentRunner } from "./agent-session.ts";
+import { createScriptGlobals, MAX_CONCURRENCY, MAX_AGENTS_PER_RUN, type ScriptRunState } from "./globals.ts";
+import { appendJournal, readJournal, ReplayCursor } from "./journal.ts";
+import { findSavedWorkflow } from "./saved-workflows.ts";
+import { parseWorkflowScript } from "./script-source.ts";
+import { runWorkflowScript } from "./vm-runtime.ts";
+import type { RunProgressEvent, RunStatus, WorkflowMeta } from "./types.ts";
+import { WorkflowScriptError } from "./types.ts";
+
+const WALL_CLOCK_CAP_MS = 30 * 60 * 1000;
+const RECENT_EVENTS_CAP = 200;
+const RESULT_CAP = 30_000;
+
+export interface StartRunOptions {
+	script: string;
+	args: unknown;
+	tokenBudget: number | null;
+	resumeFromRunId?: string;
+	cwd: string;
+	sessionDir: string;
+	defaultModel: unknown;
+	configuredDefaultModel?: string;
+	defaultEffort?: string;
+}
+
+export class RunHandle extends EventEmitter {
+	status: RunStatus = "running";
+	result?: unknown;
+	errorMessage?: string;
+	readonly startedAt = Date.now();
+	finishedAt?: number;
+	readonly recentEvents: string[] = [];
+	state?: ScriptRunState;
+	/** Settles when the run reaches a terminal status (never rejects). */
+	finished!: Promise<RunHandle>;
+	private controller = new AbortController();
+	private resolveFinished!: (handle: RunHandle) => void;
+
+	readonly runId: string;
+	readonly meta: WorkflowMeta;
+	readonly runDir: string;
+	readonly scriptPath: string;
+	readonly resumed: boolean;
+
+	constructor(runId: string, meta: WorkflowMeta, runDir: string, scriptPath: string, resumed: boolean) {
+		super();
+		this.runId = runId;
+		this.meta = meta;
+		this.runDir = runDir;
+		this.scriptPath = scriptPath;
+		this.resumed = resumed;
+		this.finished = new Promise((resolve) => {
+			this.resolveFinished = resolve;
+		});
+	}
+
+	get signal(): AbortSignal {
+		return this.controller.signal;
+	}
+
+	record(event: RunProgressEvent): void {
+		const line = formatEvent(event);
+		if (line) {
+			this.recentEvents.push(line);
+			if (this.recentEvents.length > RECENT_EVENTS_CAP) this.recentEvents.shift();
+		}
+		this.emit("progress", event);
+	}
+
+	abort(reason: string): void {
+		if (this.status !== "running") return;
+		// First reason wins — a user stop shouldn't be masked by the script's
+		// consequent "aborted" error.
+		this.errorMessage ??= reason;
+		this.controller.abort();
+	}
+
+	finish(status: RunStatus, result?: unknown, errorMessage?: string): void {
+		if (this.status !== "running") return;
+		this.status = status;
+		this.result = result;
+		this.errorMessage ??= errorMessage;
+		this.finishedAt = Date.now();
+		this.emit("done", this);
+		this.resolveFinished(this);
+	}
+}
+
+function formatEvent(event: RunProgressEvent): string | undefined {
+	switch (event.type) {
+		case "log":
+			return `• ${event.text}`;
+		case "phase":
+			return `— ${event.phase} —`;
+		case "agentStart":
+			return `⏳ ${event.label}${event.phase ? ` [${event.phase}]` : ""}`;
+		case "agentEnd":
+			if (event.text) return `✗ ${event.label}: ${event.text}`;
+			return `✓ ${event.label}${event.replayed ? " (replayed)" : ""}${event.tokens ? ` · ${event.tokens.output} out` : ""}`;
+		default:
+			return undefined;
+	}
+}
+
+export class WorkflowRunManager {
+	private runs = new Map<string, RunHandle>();
+
+	list(): RunHandle[] {
+		return [...this.runs.values()];
+	}
+
+	get(runId: string): RunHandle | undefined {
+		return this.runs.get(runId);
+	}
+
+	abort(runId: string, reason: string): boolean {
+		const handle = this.runs.get(runId);
+		if (!handle || handle.status !== "running") return false;
+		handle.abort(reason);
+		return true;
+	}
+
+	abortAll(reason: string): void {
+		for (const handle of this.runs.values()) handle.abort(reason);
+	}
+
+	hasActiveRuns(): boolean {
+		return this.list().some((h) => h.status === "running");
+	}
+
+	/** Parse, persist, and launch a run. Throws synchronously on a bad script/resume id. */
+	start(options: StartRunOptions): RunHandle {
+		const { meta, body } = parseWorkflowScript(options.script);
+
+		const resumed = Boolean(options.resumeFromRunId);
+		const runId = options.resumeFromRunId ?? `wf_${randomBytes(5).toString("hex")}`;
+		if (!/^wf_[a-z0-9-]{6,}$/.test(runId)) {
+			throw new WorkflowScriptError(`Invalid runId "${runId}"`);
+		}
+		const runDir = join(options.sessionDir, "workflows", runId);
+		const journalPath = join(runDir, "journal.jsonl");
+
+		let replay: ReplayCursor | undefined;
+		if (resumed) {
+			if (this.runs.get(runId)?.status === "running") {
+				throw new WorkflowScriptError(`Run ${runId} is still running — stop it before resuming`);
+			}
+			if (!existsSync(runDir)) {
+				throw new WorkflowScriptError(`resumeFromRunId ${runId} not found under ${join(options.sessionDir, "workflows")}`);
+			}
+			replay = new ReplayCursor(readJournal(journalPath));
+		}
+		mkdirSync(runDir, { recursive: true });
+		const scriptPath = join(runDir, "script.js");
+		writeFileSync(scriptPath, options.script, "utf8");
+
+		const handle = new RunHandle(runId, meta, runDir, scriptPath, resumed);
+		this.runs.set(runId, handle);
+		void this.execute(handle, body, options, journalPath, replay);
+		return handle;
+	}
+
+	private async execute(
+		handle: RunHandle,
+		body: string,
+		options: StartRunOptions,
+		journalPath: string,
+		replay: ReplayCursor | undefined,
+	): Promise<void> {
+		const wallClock = setTimeout(
+			() => handle.abort(`wall-clock cap reached (${WALL_CLOCK_CAP_MS / 60000} minutes)`),
+			WALL_CLOCK_CAP_MS,
+		);
+		wallClock.unref?.();
+
+		let runner: AgentRunner | undefined;
+		try {
+			runner = await AgentRunner.create({
+				cwd: options.cwd,
+				defaultModel: options.defaultModel,
+				configuredDefaultModel: options.configuredDefaultModel,
+				defaultEffort: options.defaultEffort as never,
+				onNotice: (message) => handle.record({ type: "log", text: `⚠ ${message}` }),
+			});
+
+			const { globals, state } = createScriptGlobals({
+				agentCall: (prompt, opts) => runner!.run(prompt, opts, handle.signal),
+				args: options.args,
+				budgetTotal: options.tokenBudget,
+				concurrency: defaultConcurrency(),
+				signal: handle.signal,
+				onEvent: (event) => handle.record(event),
+				onJournal: (entry) => appendJournal(journalPath, entry),
+				replay,
+				runWorkflow: (nameOrRef, childArgs) => this.runChild(handle, runner!, options, nameOrRef, childArgs, () => state),
+			});
+			handle.state = state;
+
+			const result = await runWorkflowScript(body, globals, `${handle.meta.name}.js`);
+			handle.finish(handle.signal.aborted ? "aborted" : "completed", result);
+		} catch (error) {
+			const aborted = handle.signal.aborted;
+			// Stop in-flight sibling agents instead of letting a doomed batch run on.
+			handle.abort((error as Error).message);
+			handle.finish(aborted ? "aborted" : "failed", undefined, (error as Error).message);
+		} finally {
+			clearTimeout(wallClock);
+			runner?.dispose();
+		}
+	}
+
+	/** One level of workflow() nesting: child shares the runner/signal, gets the remaining caps. */
+	private async runChild(
+		parent: RunHandle,
+		runner: AgentRunner,
+		options: StartRunOptions,
+		nameOrRef: unknown,
+		childArgs: unknown,
+		parentState: () => ScriptRunState,
+	): Promise<unknown> {
+		let source: string;
+		let label: string;
+		if (typeof nameOrRef === "string") {
+			const saved = findSavedWorkflow(options.cwd, os.homedir(), nameOrRef);
+			if (!saved) throw new WorkflowScriptError(`workflow("${nameOrRef}"): no saved workflow with that name`);
+			source = readFileSync(saved.path, "utf8");
+			label = nameOrRef;
+		} else if (nameOrRef && typeof nameOrRef === "object" && typeof (nameOrRef as { scriptPath?: unknown }).scriptPath === "string") {
+			const path = (nameOrRef as { scriptPath: string }).scriptPath;
+			if (!existsSync(path)) throw new WorkflowScriptError(`workflow({scriptPath}): ${path} does not exist`);
+			source = readFileSync(path, "utf8");
+			label = path;
+		} else {
+			throw new WorkflowScriptError("workflow() takes a saved-workflow name or {scriptPath}");
+		}
+
+		const { meta, body } = parseWorkflowScript(source);
+		const state = parentState();
+		const remainingAgents = Math.max(0, MAX_AGENTS_PER_RUN - state.agentCount());
+		const remainingBudget =
+			options.tokenBudget === null ? null : Math.max(0, options.tokenBudget - state.outputTokens());
+
+		// Child calls are not journaled in v1: resume replays the parent's own
+		// agent() prefix only. Progress is forwarded under a "▸ name" phase.
+		const { globals } = createScriptGlobals({
+			agentCall: (prompt, opts) => runner.run(prompt, opts, parent.signal),
+			args: childArgs,
+			budgetTotal: remainingBudget,
+			concurrency: defaultConcurrency(),
+			maxAgents: remainingAgents,
+			signal: parent.signal,
+			onEvent: (event) => parent.record({ ...event, phase: `▸ ${meta.name}${event.phase ? ` · ${event.phase}` : ""}` }),
+		});
+		return runWorkflowScript(body, globals, `${label}.js`);
+	}
+}
+
+export function defaultConcurrency(): number {
+	return Math.min(MAX_CONCURRENCY, Math.max(1, os.cpus().length - 2));
+}
+
+/** Human/LLM-facing completion report, delivered as the followUp message. */
+export function buildRunReport(handle: RunHandle): string {
+	const state = handle.state;
+	const duration = handle.finishedAt ? Math.round((handle.finishedAt - handle.startedAt) / 1000) : 0;
+	const statsLine = state
+		? `${state.agentCount()} agent(s), ${state.outputTokens()} output tokens, $${state.cost().toFixed(4)}, ${duration}s`
+		: `${duration}s`;
+
+	if (handle.status === "completed") {
+		let resultText: string;
+		if (typeof handle.result === "string") {
+			resultText = handle.result;
+		} else if (handle.result === undefined) {
+			resultText = "(script returned no value)";
+		} else {
+			try {
+				resultText = JSON.stringify(handle.result, null, 2);
+			} catch {
+				resultText = String(handle.result);
+			}
+		}
+		if (resultText.length > RESULT_CAP) resultText = `${resultText.slice(0, RESULT_CAP)}\n… (truncated)`;
+		return `Workflow **${handle.meta.name}** (${handle.runId}) completed — ${statsLine}.\n\nResult:\n${resultText}`;
+	}
+
+	const tail = handle.recentEvents.slice(-5).join("\n");
+	return `Workflow **${handle.meta.name}** (${handle.runId}) ${handle.status} — ${statsLine}.\nReason: ${handle.errorMessage ?? "unknown"}${tail ? `\nRecent progress:\n${tail}` : ""}\nCompleted agent calls are journaled; re-invoke the workflow tool with resumeFromRunId: "${handle.runId}" to continue from where it stopped.`;
+}

package/extensions/workflow/saved-workflows.ts

@@ -0,0 +1,45 @@
+/**
+ * Saved-workflow discovery (pure). Named workflow scripts live in
+ * `.claude/workflows/` (project) and `~/.claude/workflows/` (user) as `.js`
+ * files, matching Claude Code's layout; the file's basename is the invocation
+ * name and the leading `export const meta` supplies the description. Project
+ * definitions shadow user ones of the same name.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parseWorkflowScript } from "./script-source.ts";
+import type { SavedWorkflow } from "./types.ts";
+
+function scanDir(dir: string, source: SavedWorkflow["source"]): SavedWorkflow[] {
+	if (!existsSync(dir)) return [];
+	const found: SavedWorkflow[] = [];
+	for (const file of readdirSync(dir).sort()) {
+		if (!file.endsWith(".js") && !file.endsWith(".mjs")) continue;
+		const path = join(dir, file);
+		const workflow: SavedWorkflow = { name: basename(file).replace(/\.(js|mjs)$/, ""), path, source };
+		try {
+			workflow.meta = parseWorkflowScript(readFileSync(path, "utf8")).meta;
+		} catch {
+			// Listed anyway; the parse error surfaces if the user runs it.
+		}
+		found.push(workflow);
+	}
+	return found;
+}
+
+export function workflowDirs(cwd: string, home: string): { project: string; user: string } {
+	return { project: join(cwd, ".claude", "workflows"), user: join(home, ".claude", "workflows") };
+}
+
+export function discoverSavedWorkflows(cwd: string, home: string): SavedWorkflow[] {
+	const dirs = workflowDirs(cwd, home);
+	const project = scanDir(dirs.project, "project");
+	const names = new Set(project.map((w) => w.name));
+	const user = scanDir(dirs.user, "user").filter((w) => !names.has(w.name));
+	return [...project, ...user];
+}
+
+export function findSavedWorkflow(cwd: string, home: string, name: string): SavedWorkflow | undefined {
+	return discoverSavedWorkflows(cwd, home).find((w) => w.name === name);
+}

package/extensions/workflow/script-source.ts

@@ -0,0 +1,201 @@
+/**
+ * Workflow script source handling (pure).
+ *
+ * A workflow script is plain JavaScript that must begin with a pure-literal
+ * `export const meta = {...}`. acorn parses the whole script once; the meta
+ * literal is evaluated structurally (no code execution), the export statement
+ * is spliced out, and the remainder is wrapped in an async IIFE behind a
+ * prelude that makes wall-clock/randomness calls throw. The wrap is what makes
+ * top-level `await` and bare top-level `return` work: both become ordinary
+ * inside the IIFE.
+ *
+ * The vm context this produces code for is a determinism guard for resume
+ * replay, not a security sandbox — the injected `agent()` does real work on
+ * the host either way.
+ */
+
+import { parse } from "acorn";
+import { type WorkflowMeta, WorkflowScriptError } from "./types.ts";
+
+/** Property keys that would let a "literal" reach into prototypes. */
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** Names destructured off the injected `__workflow__` binding inside the vm. */
+export const SCRIPT_GLOBALS = [
+	"agent",
+	"parallel",
+	"pipeline",
+	"workflow",
+	"phase",
+	"log",
+	"console",
+	"args",
+	"budget",
+] as const;
+
+const DETERMINISM_PRELUDE = `
+Math.random = () => { throw new Error("Math.random() is unavailable in a workflow (it breaks resume); vary agent prompts by index or pass randomness in via args"); };
+globalThis.Date = new Proxy(Date, {
+	construct(target, ctorArgs, newTarget) {
+		if (ctorArgs.length === 0) throw new Error("new Date() with no arguments is unavailable in a workflow (it breaks resume); pass timestamps in via args");
+		return Reflect.construct(target, ctorArgs, newTarget);
+	},
+	apply() { throw new Error("Date() is unavailable in a workflow (it breaks resume); pass timestamps in via args"); },
+	get(target, prop, receiver) {
+		if (prop === "now") return () => { throw new Error("Date.now() is unavailable in a workflow (it breaks resume); pass timestamps in via args"); };
+		return Reflect.get(target, prop, receiver);
+	},
+});
+`;
+
+export interface ParsedScript {
+	meta: WorkflowMeta;
+	/** Script source with the meta export spliced out. */
+	body: string;
+}
+
+interface Node {
+	type: string;
+	start: number;
+	end: number;
+	[key: string]: unknown;
+}
+
+/** Structurally evaluate an object/array/primitive literal AST — no code runs. */
+function evaluateLiteral(node: Node, path: string): unknown {
+	switch (node.type) {
+		case "Literal":
+			return (node as { value?: unknown }).value;
+		case "TemplateLiteral": {
+			const expressions = node.expressions as Node[];
+			const quasis = node.quasis as Array<{ value: { cooked?: string } }>;
+			if (expressions.length > 0) {
+				throw new WorkflowScriptError(`\`${path}\` must be a pure literal: template interpolation is not allowed`);
+			}
+			return quasis.map((q) => q.value.cooked ?? "").join("");
+		}
+		case "UnaryExpression": {
+			const operator = node.operator as string;
+			const argument = node.argument as Node;
+			const literal = (argument as { value?: unknown }).value;
+			if (operator === "-" && argument.type === "Literal" && typeof literal === "number") {
+				return -literal;
+			}
+			throw new WorkflowScriptError(`\`${path}\` must be a pure literal: unsupported expression`);
+		}
+		case "ArrayExpression":
+			return (node.elements as (Node | null)[]).map((el, i) => {
+				if (!el) throw new WorkflowScriptError(`\`${path}[${i}]\` must not be a hole`);
+				if (el.type === "SpreadElement") {
+					throw new WorkflowScriptError(`\`${path}\` must be a pure literal: spread is not allowed`);
+				}
+				return evaluateLiteral(el, `${path}[${i}]`);
+			});
+		case "ObjectExpression": {
+			const out: Record<string, unknown> = {};
+			for (const prop of node.properties as Node[]) {
+				if (prop.type !== "Property") {
+					throw new WorkflowScriptError(`\`${path}\` must be a pure literal: spread/methods are not allowed`);
+				}
+				if (prop.computed) {
+					throw new WorkflowScriptError(`\`${path}\` must be a pure literal: computed keys are not allowed`);
+				}
+				const key = prop.key as Node;
+				const name =
+					key.type === "Identifier" ? (key.name as string) : key.type === "Literal" ? String((key as { value?: unknown }).value) : undefined;
+				if (name === undefined) {
+					throw new WorkflowScriptError(`\`${path}\` must be a pure literal: unsupported key`);
+				}
+				if (FORBIDDEN_KEYS.has(name)) {
+					throw new WorkflowScriptError(`\`${path}\` must not contain the key "${name}"`);
+				}
+				out[name] = evaluateLiteral(prop.value as Node, `${path}.${name}`);
+			}
+			return out;
+		}
+		default:
+			throw new WorkflowScriptError(`\`${path}\` must be a pure literal (objects, arrays, strings, numbers, booleans)`);
+	}
+}
+
+function validateMeta(value: unknown): WorkflowMeta {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new WorkflowScriptError("`meta` must be an object literal");
+	}
+	const meta = value as Record<string, unknown>;
+	if (typeof meta.name !== "string" || !meta.name.trim()) {
+		throw new WorkflowScriptError("`meta.name` must be a non-empty string");
+	}
+	if (typeof meta.description !== "string" || !meta.description.trim()) {
+		throw new WorkflowScriptError("`meta.description` must be a non-empty string");
+	}
+	if (meta.whenToUse !== undefined && typeof meta.whenToUse !== "string") {
+		throw new WorkflowScriptError("`meta.whenToUse` must be a string");
+	}
+	if (meta.phases !== undefined) {
+		if (!Array.isArray(meta.phases)) throw new WorkflowScriptError("`meta.phases` must be an array");
+		for (const phase of meta.phases) {
+			if (typeof phase !== "object" || phase === null || typeof (phase as { title?: unknown }).title !== "string") {
+				throw new WorkflowScriptError("each entry of `meta.phases` needs a `title` string");
+			}
+		}
+	}
+	return meta as unknown as WorkflowMeta;
+}
+
+/** Parse a workflow script: lift + validate `meta`, splice its export out. */
+export function parseWorkflowScript(source: string): ParsedScript {
+	let ast: { body: Node[] };
+	try {
+		ast = parse(source, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: true,
+		}) as unknown as { body: Node[] };
+	} catch (error) {
+		throw new WorkflowScriptError(`Workflow script does not parse: ${(error as Error).message}`);
+	}
+
+	const first = ast.body[0];
+	if (!first || first.type !== "ExportNamedDeclaration") {
+		throw new WorkflowScriptError("Workflow scripts must begin with `export const meta = {...}`");
+	}
+	const declaration = first.declaration as Node | null;
+	if (!declaration || declaration.type !== "VariableDeclaration" || (declaration.kind as string) !== "const") {
+		throw new WorkflowScriptError("Workflow scripts must begin with `export const meta = {...}`");
+	}
+	const declarators = declaration.declarations as Node[];
+	const declarator = declarators[0];
+	if (
+		declarators.length !== 1 ||
+		(declarator.id as Node).type !== "Identifier" ||
+		((declarator.id as Node).name as string) !== "meta"
+	) {
+		throw new WorkflowScriptError("The first statement must export exactly one binding named `meta`");
+	}
+	const init = declarator.init as Node | null;
+	if (!init || init.type !== "ObjectExpression") {
+		throw new WorkflowScriptError("`meta` must be an object literal — no variables, calls, or spreads");
+	}
+
+	for (const node of ast.body.slice(1)) {
+		if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration" || node.type === "ImportDeclaration") {
+			throw new WorkflowScriptError("Workflow scripts cannot use import/export beyond the leading `export const meta`");
+		}
+	}
+
+	const meta = validateMeta(evaluateLiteral(init, "meta"));
+	const body = source.slice(0, first.start) + source.slice(first.end);
+	return { meta, body };
+}
+
+/**
+ * Wrap a spliced script body for `vm.Script`. The async IIFE is the final
+ * expression statement, so `runInContext()`'s completion value is the promise
+ * of the script's own (possibly top-level-returned) result.
+ */
+export function wrapScriptBody(body: string): string {
+	const bindings = SCRIPT_GLOBALS.join(", ");
+	return `"use strict";\n${DETERMINISM_PRELUDE}\nconst { ${bindings} } = __workflow__;\n(async () => {\n${body}\n})();`;
+}

package/extensions/workflow/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared shapes for the workflow extension. Pure types only — no runtime
+ * logic, no pi imports — so every module (pure and wiring alike) can depend
+ * on this file without dragging anything else in.
+ */
+
+/** The `export const meta = {...}` literal every workflow script must start with. */
+export interface WorkflowMeta {
+	name: string;
+	description: string;
+	whenToUse?: string;
+	phases?: WorkflowPhase[];
+}
+
+export interface WorkflowPhase {
+	title: string;
+	detail?: string;
+	model?: string;
+}
+
+/** Reasoning-effort subset shared with the subagent tool. */
+export type AgentEffort = "off" | "minimal" | "low" | "medium" | "high";
+
+/** Options accepted by the script-visible `agent(prompt, opts)` hook. */
+export interface AgentCallOptions {
+	label?: string;
+	phase?: string;
+	/** JSON Schema (top-level object) forcing structured output. */
+	schema?: Record<string, unknown>;
+	model?: string;
+	/** Confirms a `model` that costs more per token than the session model. */
+	allowExpensive?: boolean;
+	effort?: AgentEffort;
+	isolation?: "worktree";
+	agentType?: string;
+}
+
+export interface AgentTokens {
+	input: number;
+	output: number;
+	total: number;
+}
+
+/** What a completed agent call produced, as stored in the journal. */
+export interface AgentCallResult {
+	/** Final assistant text, or the validated structured object when `schema` was given. */
+	value: unknown;
+	tokens: AgentTokens;
+	cost: number;
+	/** Path of a kept worktree (uncommitted changes were left behind), if any. */
+	worktreePath?: string;
+}
+
+/** The one injection point globals.ts needs: something that runs a real agent. */
+export type AgentCallFn = (prompt: string, opts: AgentCallOptions) => Promise<AgentCallResult>;
+
+/** One line of journal.jsonl. */
+export interface JournalEntry {
+	callIndex: number;
+	hash: string;
+	result: AgentCallResult;
+	timestamp: number;
+}
+
+/** The frozen `budget` global exposed to scripts. */
+export interface BudgetSnapshot {
+	total: number | null;
+	spent(): number;
+	remaining(): number;
+}
+
+export type RunStatus = "running" | "completed" | "failed" | "aborted";
+
+/** Progress events a run emits (consumed by the widget, /workflows, onUpdate). */
+export interface RunProgressEvent {
+	type: "log" | "phase" | "agentStart" | "agentEnd";
+	text?: string;
+	phase?: string;
+	label?: string;
+	callIndex?: number;
+	tokens?: AgentTokens;
+	cost?: number;
+	replayed?: boolean;
+}
+
+/** A saved workflow discovered in .claude/workflows/ or ~/.claude/workflows/. */
+export interface SavedWorkflow {
+	name: string;
+	path: string;
+	meta?: WorkflowMeta;
+	source: "project" | "user";
+}
+
+export class WorkflowScriptError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "WorkflowScriptError";
+	}
+}

package/extensions/workflow/vm-runtime.ts

@@ -0,0 +1,31 @@
+/**
+ * Executes a parsed workflow script body inside a fresh `node:vm` context.
+ *
+ * The context gets exactly one host binding — `__workflow__`, the globals
+ * object — and none of the host's intrinsics (the vm realm supplies its own
+ * Math/Date/Promise/etc., which the prelude then neuters for determinism).
+ * The vm `timeout` only bounds the synchronous prefix of execution (up to the
+ * first await); async runaway is bounded by the agent/budget caps inside the
+ * injected agent(), not here.
+ */
+
+import vm from "node:vm";
+import type { ScriptGlobals } from "./globals.ts";
+import { wrapScriptBody } from "./script-source.ts";
+import { WorkflowScriptError } from "./types.ts";
+
+const SYNC_TIMEOUT_MS = 5_000;
+
+export async function runWorkflowScript(body: string, globals: ScriptGlobals, filename = "workflow.js"): Promise<unknown> {
+	const context = vm.createContext({ __workflow__: globals }, { codeGeneration: { strings: false, wasm: false } });
+	let completion: unknown;
+	try {
+		const script = new vm.Script(wrapScriptBody(body), { filename });
+		completion = script.runInContext(context, { timeout: SYNC_TIMEOUT_MS });
+	} catch (error) {
+		throw error instanceof WorkflowScriptError ? error : new WorkflowScriptError(`Workflow script failed: ${(error as Error).message}`);
+	}
+	// The wrap's final statement is the async IIFE, so the completion value is
+	// the promise of the script's own result (including a top-level `return`).
+	return await Promise.resolve(completion);
+}