@vimhead.dev/norn-cli 0.1.0-tip.0

package/assets/packages/cli/src/internal/engine.ts

@@ -0,0 +1,501 @@
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { initializeRunResources } from "./run-resources.ts";
+import { createRunFileCoordinator } from "@vimhead.dev/norn/files";
+import {
+	type NornAnyWorkflowDeclaration,
+	type NornAnyWorkflowPluginManifest,
+	type NornDispose,
+	type NornRunStartOptions,
+	type NornInterruptedRunResult,
+	type NornRunResult,
+	type NornRunCheckpoint,
+	type NornRunInfo,
+	type NornWorkflowPlugin,
+	type NornWorkflowPluginImplementation,
+	type NornWorkflowPluginImplementationInput,
+	type NornRunNext,
+} from "@vimhead.dev/norn";
+import { NornAgentResponseCollector } from "./agent-response-tool.ts";
+import { NornArtifacts } from "./artifacts.ts";
+import { errorMessage, NornRunStoppedError } from "./errors.ts";
+import { NornRunLogs } from "./logs.ts";
+import { clearRunResumeRequest, matchesRunResumeRequest, readOptionalRunResumeRequest, RESUME_START_GRACE_MS, type NornRunResumeRequest } from "./launch-request.ts";
+import { NornRunLease } from "./run-lease.ts";
+import { NornRunLogger } from "./run-log.ts";
+import { NornRunStore, runCurrentRoot } from "./run-store.ts";
+import { NornRunStateStore, getRunInfo, mergeInterruptedWorkflowParams, resolveRunRoot, type NornRunState } from "./run-state.ts";
+import { NornRunContext } from "./run.ts";
+import { NornMemoryWorkflowState } from "./state-store.ts";
+import { NornWorkflowRegistry, type NornRegisteredWorkflow, type NornWorkflowStepResult } from "./workflow-registry.ts";
+
+const RUNS_DIR_NAME = ".norn";
+const MANIFEST_FILE_NAME = "manifest.json";
+
+export type NornEngineInput = {
+	readonly cwd: string;
+	readonly agentDir?: string;
+	readonly signal?: AbortSignal;
+	readonly responseCollector?: NornAgentResponseCollector;
+	readonly gateMode?: "auto" | "pause";
+	readonly config?: Record<string, unknown>;
+};
+
+type RunSession = {
+	readonly runRoot: string;
+	readonly run: NornRunContext;
+	readonly state: NornRunStateStore;
+	readonly lease: NornRunLease;
+	readonly runStore: NornRunStore;
+	readonly logger: NornRunLogger;
+	readonly activeRun: ActiveRun;
+};
+
+type ActiveRun = {
+	readonly controller: AbortController;
+	readonly finished: Promise<void>;
+	readonly finish: () => void;
+	readonly dispose: () => void;
+};
+
+type WorkflowStep = {
+	readonly workflow: NornAnyWorkflowDeclaration;
+	readonly params: unknown;
+	readonly interruption?: NonNullable<NornRunState["current"]>["interruption"];
+};
+
+export class NornEngine {
+	private readonly registry = new NornWorkflowRegistry();
+	private readonly registrarState = new NornMemoryWorkflowState();
+	private readonly disposersByPlugin = new Map<string, NornDispose[]>();
+	private readonly responseCollector: NornAgentResponseCollector;
+	private readonly activeRuns = new Map<string, ActiveRun>();
+
+	constructor(private readonly input: NornEngineInput) {
+		this.responseCollector = input.responseCollector ?? new NornAgentResponseCollector();
+	}
+
+	registerPlugin<TManifest extends NornAnyWorkflowPluginManifest>(plugin: NornWorkflowPlugin<TManifest>): NornDispose {
+		this.disposePlugin(plugin.manifest.id);
+		const implementation = this.resolvePluginImplementation(plugin.implementation);
+		const disposers = Object.entries(plugin.manifest.workflows).map(([key, workflow]) => {
+			const workflowImplementation = implementation.workflows[key];
+			if (!workflowImplementation) throw new Error(`Missing implementation for workflow ${plugin.manifest.id}.${key}`);
+			return this.registry.register(workflow, workflowImplementation, { plugin: { id: plugin.manifest.id }, configSchema: plugin.manifest.config, config: this.input.config?.[plugin.manifest.id] });
+		});
+		this.disposersByPlugin.set(plugin.manifest.id, disposers);
+		return () => {
+			if (this.disposersByPlugin.get(plugin.manifest.id) === disposers) this.disposePlugin(plugin.manifest.id);
+		};
+	}
+
+	listWorkflows() {
+		return this.registry.list();
+	}
+
+	visibleWorkflowEntries(): NornRegisteredWorkflow[] {
+		return this.registry.launchableEntries();
+	}
+
+	private resolvePluginImplementation<TManifest extends NornAnyWorkflowPluginManifest>(
+		implementationInput: NornWorkflowPluginImplementationInput<TManifest>,
+	): NornWorkflowPluginImplementation<TManifest> {
+		return typeof implementationInput === "function"
+			? implementationInput({ cwd: this.input.cwd, state: this.registrarState })
+			: implementationInput;
+	}
+
+	async runWorkflow<TWorkflow extends NornAnyWorkflowDeclaration>(
+		workflow: TWorkflow,
+		params: unknown,
+		options: NornRunStartOptions | undefined,
+	): Promise<NornRunResult> {
+		const session = await this.createRunSession(workflow, params, options);
+		const current = session.state.currentState().current;
+		if (!current) throw new Error("New run is missing its initial workflow step");
+		return this.runScheduler(session, toWorkflowStep(workflow, current));
+	}
+
+	async listRunCheckpoints(path: string): Promise<NornRunCheckpoint[]> {
+		const runRoot = await resolveRunRoot(this.input.cwd, path);
+		return (await NornRunStore.open(runRoot)).listCheckpoints();
+	}
+
+	async rollbackRun(path: string, checkpointId: string): Promise<NornRunInfo> {
+		const runRoot = await resolveRunRoot(this.input.cwd, path);
+		const lease = await NornRunLease.acquire(runRoot);
+		try {
+			const pendingRequest = await readOptionalRunResumeRequest(runRoot);
+			if (pendingRequest && Date.now() - Date.parse(pendingRequest.createdAt) < RESUME_START_GRACE_MS) throw new Error(`Resume request is still pending: ${runRoot}`);
+			const runStore = await NornRunStore.open(runRoot);
+			await runStore.restoreSnapshot(checkpointId, async (stagedRunRoot) => {
+				const state = await NornRunStateStore.load(stagedRunRoot);
+				await state.prepareForResumeAfterRollback();
+			});
+			if (pendingRequest) await clearRunResumeRequest({ runRoot, request: pendingRequest, lease });
+			return getRunInfo(runRoot);
+		} finally {
+			await lease.release();
+		}
+	}
+
+	async resumeWorkflow(path: string, params?: unknown): Promise<NornRunResult> {
+		return this.resumeWorkflowExecution({ path, params, expectedRequest: undefined });
+	}
+
+	async resumeRequestedWorkflow(input: { readonly runRoot: string; readonly request: NornRunResumeRequest }): Promise<NornRunResult> {
+		return this.resumeWorkflowExecution({ path: input.runRoot, params: input.request.params, expectedRequest: input.request });
+	}
+
+	private async resumeWorkflowExecution(input: { readonly path: string; readonly params: unknown; readonly expectedRequest: NornRunResumeRequest | undefined }): Promise<NornRunResult> {
+		const { params, expectedRequest } = input;
+		const runRoot = await resolveRunRoot(this.input.cwd, input.path);
+		const initialStateStore = await NornRunStateStore.load(runRoot);
+		const initialState = initialStateStore.currentState();
+		if (initialState.status === "interrupted" && params === undefined) throw new Error(`Interrupted workflow resume requires params: ${runRoot}`);
+		if (initialState.status === "pendingResume" && params !== undefined) throw new Error(`Pending-resume workflows do not accept params: ${runRoot}`);
+		if (initialState.status !== "interrupted" && initialState.status !== "pendingResume") throw new Error(`Run must be rolled back before resuming: ${runRoot}`);
+
+		const lease = await NornRunLease.acquire(runRoot);
+		let isLeaseOwnedByScheduler = false;
+		let session: RunSession | undefined;
+		try {
+			const pendingRequest = await readOptionalRunResumeRequest(runRoot);
+			if (expectedRequest ? !matchesRunResumeRequest(pendingRequest, expectedRequest) : pendingRequest !== undefined) throw new Error(`Resume request changed or belongs to another executor: ${runRoot}`);
+			session = await this.openRunSession(runRoot, lease);
+			const state = session.state.currentState();
+			const current = state.current;
+			if (!current) throw new Error(`Run is not resumable: ${runRoot}`);
+			const workflow = this.registry.workflowById(current.workflowId);
+			if (!workflow) throw new Error(`Unknown workflow for resumed run: ${current.workflowId}`);
+			if (state.status === "interrupted") {
+				const parsedParams = workflow.params.parse(mergeInterruptedWorkflowParams(current.params, params, current.interruption?.fields));
+				await session.state.replaceCurrentParams(parsedParams);
+				await recordRunEvent(session, { type: "run.resumed", workflowId: workflow.id, cwd: session.run.cwd });
+				const resumedCurrent = session.state.currentState().current;
+				if (!resumedCurrent) throw new Error(`Run is not resumable: ${runRoot}`);
+				isLeaseOwnedByScheduler = true;
+				return this.runScheduler(session, toWorkflowStep(workflow, resumedCurrent));
+			}
+			if (state.status !== "pendingResume") throw new Error(`Run must be rolled back before resuming: ${runRoot}`);
+			await recordRunEvent(session, { type: "run.resumed", workflowId: workflow.id, cwd: session.run.cwd });
+			isLeaseOwnedByScheduler = true;
+			return this.runScheduler(session, toWorkflowStep(workflow, current));
+		} finally {
+			if (!isLeaseOwnedByScheduler) {
+				try {
+					await lease.release();
+				} finally {
+					if (session) this.failActiveRun(runRoot, session.activeRun);
+				}
+			}
+		}
+	}
+
+	private async runScheduler(session: RunSession, initialStep: WorkflowStep): Promise<NornRunResult> {
+		let currentStep = initialStep;
+		try {
+			for (let step = 1; step <= 1_000; step++) {
+				throwIfRunAborted(session.activeRun);
+				const stepRuntime = session.run.forWorkflow(currentStep.workflow);
+				if (shouldPauseForGate(currentStep)) {
+					const parsedParams = currentStep.workflow.params.parse(currentStep.params);
+					const description = await this.registry.describeGate(currentStep.workflow, stepRuntime, parsedParams, session.state.currentState().configOverride);
+					const interruption = { description, fields: currentStep.workflow.gate?.fields };
+					await session.state.interruptCurrent(parsedParams, interruption);
+					await recordRunEvent(session, { type: "run.interrupted", workflowId: currentStep.workflow.id });
+					await commitRunBoundary(session, `run interrupted: ${currentStep.workflow.id}`);
+					return interruptedLaunchResult({ id: stepRuntime.id, name: session.state.currentState().name, workspace: stepRuntime.workspace, cwd: stepRuntime.cwd }, currentStep.workflow, parsedParams, interruption);
+				}
+				await session.state.startStep(toRunStateStep(currentStep));
+				const stepResult = await this.executeWorkflowStep(session, currentStep, stepRuntime);
+				throwIfRunAborted(session.activeRun);
+				if (stepResult.type === "complete") {
+					await session.state.completeRun(stepResult.workflow.id, stepResult.metadata);
+					await recordRunEvent(session, { type: "run.completed", workflowId: stepResult.workflow.id, metadata: stepResult.metadata });
+					await commitRunBoundary(session, `run completed: ${stepResult.workflow.id}`);
+					return { status: "completed", id: stepRuntime.id, name: session.state.currentState().name, workspace: stepRuntime.workspace, cwd: stepRuntime.cwd, workflowId: stepResult.workflow.id, metadata: stepResult.metadata };
+				}
+				if (stepResult.type === "fail") {
+					await session.state.failRun(stepResult.workflow.id, stepResult.metadata);
+					await recordRunEvent(session, { type: "run.failed", workflowId: stepResult.workflow.id, metadata: stepResult.metadata });
+					return { status: "failed", id: stepRuntime.id, name: session.state.currentState().name, workspace: stepRuntime.workspace, cwd: stepRuntime.cwd, workflowId: stepResult.workflow.id, metadata: stepResult.metadata };
+				}
+				const nextStep = this.nextWorkflowStep(stepResult);
+				await session.state.completeWithNext(currentStep.workflow.id, toRunStateStep(nextStep));
+				await recordRunEvent(session, { type: "run.transitioned", fromWorkflowId: currentStep.workflow.id, toWorkflowId: nextStep.workflow.id });
+				await commitRunBoundary(session, `transition: ${currentStep.workflow.id} -> ${nextStep.workflow.id}`);
+				currentStep = nextStep;
+			}
+			throw new Error("Run exceeded 1000 scheduler steps");
+		} catch (error) {
+			if (isRunStopped(session, error)) {
+				await session.state.stopCurrent();
+				await recordRunEvent(session, { type: "run.stopped", workflowId: currentStep.workflow.id });
+				return { status: "stopped", id: session.run.id, name: session.state.currentState().name, workspace: session.run.workspace, cwd: session.run.cwd, workflowId: currentStep.workflow.id };
+			}
+			await session.state.failCurrent(errorMessage(error));
+			await recordRunEvent(session, { type: "run.failed", workflowId: currentStep.workflow.id, error: errorMessage(error) });
+			throw error;
+		} finally {
+			await session.lease.release();
+			this.finishActiveRun(session.runRoot, session.activeRun);
+		}
+	}
+
+	private async executeWorkflowStep(session: RunSession, step: WorkflowStep, run: NornRunContext): Promise<NornWorkflowStepResult> {
+		const startedAtMs = Date.now();
+		try {
+			await assertWorkspaceBoundary(session, run.workspace);
+			await recordRunEvent(session, { type: "workflow.started", workflowId: step.workflow.id });
+			const result = await this.registry.execute(step.workflow, run, step.params, session.state.currentState().configOverride);
+			await assertWorkspaceBoundary(session, run.workspace);
+			const durationMs = Date.now() - startedAtMs;
+			if (result.type === "complete") await recordRunEvent(session, { type: "workflow.completed", workflowId: result.workflow.id, durationMs, metadata: result.metadata });
+			else if (result.type === "fail") await recordRunEvent(session, { type: "workflow.failed", workflowId: result.workflow.id, durationMs, metadata: result.metadata });
+			else await recordRunEvent(session, { type: "workflow.transitioned", fromWorkflowId: step.workflow.id, toWorkflowId: result.workflowId, durationMs });
+			return result;
+		} catch (error) {
+			await recordRunEvent(session, {
+				type: isRunStopped(session, error) ? "workflow.stopped" : "workflow.failed",
+				workflowId: step.workflow.id,
+				durationMs: Date.now() - startedAtMs,
+				...(isRunStopped(session, error) ? {} : { error: errorMessage(error) }),
+			});
+			throw error;
+		}
+	}
+
+	private nextWorkflowStep(next: NornRunNext): WorkflowStep {
+		const workflow = this.registry.workflowById(next.workflowId);
+		if (!workflow) throw new Error(`Unknown next workflow: ${next.workflowId}`);
+		return {
+			workflow,
+			params: next.params,
+			interruption: this.input.gateMode === "pause" && workflow.gate ? { status: "pending" } : undefined,
+		};
+	}
+
+	private async createRunSession<TWorkflow extends NornAnyWorkflowDeclaration>(
+		workflow: TWorkflow,
+		params: unknown,
+		options: NornRunStartOptions | undefined,
+	): Promise<RunSession> {
+		const id = options?.id ?? randomUUID();
+		const name = options?.name ?? id;
+		const runRoot = defaultRunRoot(this.input.cwd, id);
+		const currentRoot = runCurrentRoot(runRoot);
+		const workspace = join(currentRoot, "workspace");
+		const cwd = workflowDefaultCwd(this.input.cwd, workspace, workflow);
+		const startedAt = new Date().toISOString();
+		await mkdir(runRoot, { recursive: true });
+		const lease = await NornRunLease.acquire(runRoot);
+		const activeRun = this.startActiveRun(runRoot);
+		try {
+			const runStore = await NornRunStore.initialize(runRoot);
+			await mkdir(workspace, { recursive: true });
+			const logger = new NornRunLogger({ manifestPath: join(currentRoot, MANIFEST_FILE_NAME), files: createRunFileCoordinator(runRoot), manifest: {
+				id,
+				name,
+				workflowId: workflow.id,
+				runRoot,
+				workspace,
+				initialCwd: cwd,
+				startedAt,
+			} });
+			const run = await this.buildRun({ id, currentRoot, workspace, cwd, isolationMode: workflow.isolation.mode, signal: activeRun.controller.signal, logger });
+			const state = await NornRunStateStore.create(runRoot, {
+				id,
+				name,
+				entrypointWorkflowId: workflow.id,
+				workspace,
+				configOverride: options?.configOverride,
+				current: {
+					workflowId: workflow.id, params, cwd, env: {},
+					interruption: this.input.gateMode === "pause" && workflow.gate ? { status: "pending" } : undefined,
+				},
+				startedAt,
+			});
+			const session = { runRoot, run, state, lease, runStore, logger, activeRun };
+			await logger.record({ type: "run.started", workflowId: workflow.id, cwd, workspace });
+			await commitRunBoundary(session, `run started: ${workflow.id}`);
+			return session;
+		} catch (error) {
+			await lease.release();
+			this.failActiveRun(runRoot, activeRun);
+			throw error;
+		}
+	}
+
+	private async openRunSession(runRoot: string, lease: NornRunLease): Promise<RunSession> {
+		const activeRun = this.startActiveRun(runRoot);
+		try {
+			const state = await NornRunStateStore.load(runRoot);
+			const currentState = state.currentState();
+			if (currentState.status === "completed") throw new Error(`Run is already completed: ${runRoot}`);
+			const runStore = await NornRunStore.open(runRoot);
+			const currentRoot = runCurrentRoot(runRoot);
+			const logger = await NornRunLogger.load(join(currentRoot, MANIFEST_FILE_NAME), createRunFileCoordinator(runRoot));
+			const workflow = currentState.current ? this.registry.workflowById(currentState.current.workflowId) : undefined;
+			const isolationMode = workflow?.isolation.mode ?? "runWorkspace";
+			const cwd = workflowDefaultCwd(this.input.cwd, currentState.workspace, workflow);
+			const run = await this.buildRun({ id: currentState.id, currentRoot, workspace: currentState.workspace, cwd, isolationMode, signal: activeRun.controller.signal, logger });
+			return { runRoot, run, state, lease, runStore, logger, activeRun };
+		} catch (error) {
+			this.failActiveRun(runRoot, activeRun);
+			throw error;
+		}
+	}
+
+	private async buildRun(input: {
+		readonly id: string;
+		readonly currentRoot: string;
+		readonly workspace: string;
+		readonly cwd: string;
+		readonly isolationMode: "runWorkspace" | "project";
+		readonly signal: AbortSignal;
+		readonly logger: NornRunLogger;
+	}): Promise<NornRunContext> {
+		const artifactsRoot = join(input.currentRoot, "artifacts");
+		const logsRoot = join(input.currentRoot, "logs");
+		await mkdir(input.workspace, { recursive: true });
+		await mkdir(artifactsRoot, { recursive: true });
+		await mkdir(logsRoot, { recursive: true });
+		const { resources, state } = await initializeRunResources(dirname(input.currentRoot));
+		return new NornRunContext({
+			id: input.id,
+			runRoot: input.currentRoot,
+			workspace: input.workspace,
+			projectRoot: this.input.cwd,
+			cwd: input.cwd,
+			isolationMode: input.isolationMode,
+			signal: input.signal,
+			agentDir: this.input.agentDir,
+			responseCollector: this.responseCollector,
+			resources,
+			state,
+			logger: input.logger,
+			artifacts: new NornArtifacts(artifactsRoot, resources.files),
+			logs: new NornRunLogs(logsRoot, resources.files),
+		});
+	}
+
+	private startActiveRun(runRoot: string): ActiveRun {
+		if (this.activeRuns.has(runRoot)) throw new Error(`Run is already active in this engine: ${runRoot}`);
+		const controller = new AbortController();
+		let finish: () => void;
+		const finished = new Promise<void>((resolvePromise) => {
+			finish = resolvePromise;
+		});
+		const abortFromParent = () => controller.abort(this.input.signal?.reason);
+		if (this.input.signal?.aborted) abortFromParent();
+		else this.input.signal?.addEventListener("abort", abortFromParent, { once: true });
+		const activeRun: ActiveRun = {
+			controller,
+			finished,
+			finish: () => finish(),
+			dispose: () => this.input.signal?.removeEventListener("abort", abortFromParent),
+		};
+		this.activeRuns.set(runRoot, activeRun);
+		return activeRun;
+	}
+
+	private finishActiveRun(runRoot: string, activeRun: ActiveRun): void {
+		if (this.activeRuns.get(runRoot) !== activeRun) return;
+		this.activeRuns.delete(runRoot);
+		activeRun.dispose();
+		activeRun.finish();
+	}
+
+	private failActiveRun(runRoot: string, activeRun: ActiveRun): void {
+		if (this.activeRuns.get(runRoot) === activeRun) this.activeRuns.delete(runRoot);
+		activeRun.dispose();
+		activeRun.finish();
+	}
+
+	private disposePlugin(pluginId: string): void {
+		const disposers = this.disposersByPlugin.get(pluginId) ?? [];
+		for (const dispose of [...disposers].reverse()) dispose();
+		this.disposersByPlugin.delete(pluginId);
+	}
+}
+
+function defaultRunRoot(cwd: string, id: string): string {
+	return join(cwd, RUNS_DIR_NAME, "runs", id);
+}
+
+function workflowDefaultCwd(projectRoot: string, workspace: string, workflow: NornAnyWorkflowDeclaration | undefined): string {
+	return workflow?.isolation.mode === "project" ? projectRoot : workspace;
+}
+
+function toWorkflowStep(workflow: NornAnyWorkflowDeclaration, step: NonNullable<NornRunState["current"]>): WorkflowStep {
+	return {
+		workflow,
+		params: step.params,
+		interruption: step.interruption,
+	};
+}
+
+function toRunStateStep(step: WorkflowStep): NonNullable<NornRunState["current"]> {
+	return {
+		workflowId: step.workflow.id,
+		params: step.params,
+		cwd: "",
+		env: {},
+		interruption: step.interruption,
+	};
+}
+
+function shouldPauseForGate(step: WorkflowStep): boolean {
+	return step.interruption?.status === "pending" && step.workflow.gate !== undefined;
+}
+
+function throwIfRunAborted(activeRun: ActiveRun): void {
+	if (!activeRun.controller.signal.aborted) return;
+	const reason: unknown = activeRun.controller.signal.reason;
+	if (reason instanceof Error) throw reason;
+	throw new Error(typeof reason === "string" && reason.length > 0 ? reason : "Run aborted");
+}
+
+function isRunStopped(session: RunSession, error: unknown): boolean {
+	return error instanceof NornRunStoppedError || session.activeRun.controller.signal.reason instanceof NornRunStoppedError;
+}
+
+function interruptedLaunchResult(run: RunIdentity, workflow: NornAnyWorkflowDeclaration, params: unknown, interruption: { readonly description?: string; readonly fields?: readonly string[] }): NornInterruptedRunResult {
+	if (!workflow.gate) throw new Error(`Workflow is not gated: ${workflow.id}`);
+	if (!interruption.description) throw new Error(`Interrupted workflow is missing description: ${workflow.id}`);
+	return {
+		status: "interrupted",
+		id: run.id,
+		name: run.name,
+		workspace: run.workspace,
+		cwd: run.cwd,
+		workflowId: workflow.id,
+		interruption: { workflowId: workflow.id, params, description: interruption.description, fields: interruption.fields },
+	};
+}
+
+type RunIdentity = {
+	readonly id: string;
+	readonly name: string;
+	readonly workspace: string;
+	readonly cwd: string;
+};
+
+async function recordRunEvent(
+	session: RunSession,
+	event: { readonly type: string; readonly [key: string]: unknown },
+): Promise<void> {
+	await session.logger.record(event);
+}
+
+async function commitRunBoundary(session: RunSession, message: string): Promise<void> {
+	await session.lease.assertOwned();
+	await session.runStore.snapshotCurrent(message);
+}
+
+async function assertWorkspaceBoundary(session: RunSession, workspace: string): Promise<void> {
+	await session.lease.assertOwned();
+	await session.runStore.assertWorkspaceCanBeSnapshotted(workspace);
+}

package/assets/packages/cli/src/internal/errors.ts

@@ -0,0 +1,39 @@
+import type { NornPluginDiagnostic } from "@vimhead.dev/norn";
+
+export class NornProjectLoadError extends Error {
+	readonly code = "NORN_PROJECT_INVALID";
+	readonly isComplete = false;
+	readonly diagnostics: readonly NornPluginDiagnostic[];
+
+	constructor(input: { readonly diagnostics: readonly NornPluginDiagnostic[] }) {
+		const details = input.diagnostics.map(diagnostic =>
+			`${diagnostic.stage}: ${diagnostic.pluginPath} (declared in ${diagnostic.configPath}${diagnostic.workflowId ? `; workflow ${diagnostic.workflowId}` : ""}): ${diagnostic.message}`,
+		);
+		super(`Norn project is incomplete (${input.diagnostics.length} diagnostics); execution is blocked.\n${details.join("\n")}`);
+		this.name = "NornProjectLoadError";
+		this.diagnostics = input.diagnostics;
+	}
+}
+
+export class NornRunStoppedError extends Error {
+	constructor() {
+		super("Stopped by user");
+		this.name = "NornRunStoppedError";
+	}
+}
+
+export function zodErrorMessage(error: unknown): string {
+	const issues = (error as { issues?: Array<{ path?: unknown[]; message?: string }> }).issues;
+	if (!Array.isArray(issues) || issues.length === 0) return errorMessage(error);
+	return issues
+		.slice(0, 3)
+		.map((issue) => {
+			const path = Array.isArray(issue.path) && issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+			return `${path}${issue.message ?? "Invalid workflow response"}`;
+		})
+		.join("; ");
+}
+
+export function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/assets/packages/cli/src/internal/file-names.ts

@@ -0,0 +1,3 @@
+export function safeFileName(value: string): string {
+	return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "workflow";
+}

package/assets/packages/cli/src/internal/launch-request.ts

@@ -0,0 +1,94 @@
+import { randomUUID } from "node:crypto";
+import { link, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { writeJsonAtomically } from "@vimhead.dev/norn-core/atomic-files";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import type { NornRunLease } from "./run-lease.ts";
+
+export const LAUNCH_REQUEST_FILE_NAME = "launch-request.json";
+export const RESUME_REQUEST_FILE_NAME = "resume-request.json";
+export const RESUME_START_GRACE_MS = 60_000;
+
+export type NornRunLaunchRequest = {
+	readonly version: 1;
+	readonly type: "run";
+	readonly id: string;
+	readonly name: string;
+	readonly workflowId: string;
+	readonly params: unknown;
+	readonly configOverride?: unknown;
+	readonly createdAt: string;
+};
+
+export type NornRunResumeRequest = {
+	readonly version: 1;
+	readonly type: "resume";
+	readonly id: string;
+	readonly requestId?: string;
+	readonly params?: unknown;
+	readonly createdAt: string;
+};
+
+export async function writeRunLaunchRequest(runRoot: string, request: NornRunLaunchRequest): Promise<void> {
+	await writeJsonAtomically(join(runRoot, LAUNCH_REQUEST_FILE_NAME), request);
+}
+
+export async function readRunLaunchRequest(runRoot: string): Promise<NornRunLaunchRequest> {
+	return parseRunLaunchRequest(JSON.parse(await readFile(join(runRoot, LAUNCH_REQUEST_FILE_NAME), "utf8")));
+}
+
+export async function writeRunResumeRequest(runRoot: string, request: NornRunResumeRequest): Promise<void> {
+	const path = join(runRoot, RESUME_REQUEST_FILE_NAME);
+	const stagedPath = `${path}.${randomUUID()}.tmp`;
+	try {
+		await writeJsonAtomically(stagedPath, request);
+		await link(stagedPath, path);
+	} finally {
+		await rm(stagedPath, { force: true }).catch(() => undefined);
+	}
+}
+
+export async function readRunResumeRequest(runRoot: string): Promise<NornRunResumeRequest> {
+	return parseRunResumeRequest(JSON.parse(await readFile(join(runRoot, RESUME_REQUEST_FILE_NAME), "utf8")));
+}
+
+export async function readOptionalRunResumeRequest(runRoot: string): Promise<NornRunResumeRequest | undefined> {
+	try {
+		return await readRunResumeRequest(runRoot);
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+export function matchesRunResumeRequest(actual: NornRunResumeRequest | undefined, expected: NornRunResumeRequest): boolean {
+	return actual?.id === expected.id && (actual.requestId ?? actual.createdAt) === (expected.requestId ?? expected.createdAt);
+}
+
+export async function clearRunResumeRequest(input: { readonly runRoot: string; readonly request: NornRunResumeRequest; readonly lease: NornRunLease }): Promise<void> {
+	await input.lease.assertOwned();
+	if (matchesRunResumeRequest(await readOptionalRunResumeRequest(input.runRoot), input.request)) {
+		await rm(join(input.runRoot, RESUME_REQUEST_FILE_NAME), { force: true });
+	}
+}
+
+function parseRunLaunchRequest(value: unknown): NornRunLaunchRequest {
+	if (!value || typeof value !== "object") throw new Error("Invalid workflow launch request");
+	const request = value as Partial<NornRunLaunchRequest>;
+	if (request.version !== 1 || request.type !== "run") throw new Error("Unsupported workflow launch request");
+	if (typeof request.id !== "string" || request.id.length === 0) throw new Error("Invalid workflow launch request id");
+	if (typeof request.name !== "string" || request.name.length === 0) throw new Error("Invalid workflow launch request name");
+	if (typeof request.workflowId !== "string" || request.workflowId.length === 0) throw new Error("Invalid workflow launch request workflow id");
+	if (typeof request.createdAt !== "string" || Number.isNaN(Date.parse(request.createdAt))) throw new Error("Invalid workflow launch request timestamp");
+	return request as NornRunLaunchRequest;
+}
+
+function parseRunResumeRequest(value: unknown): NornRunResumeRequest {
+	if (!value || typeof value !== "object") throw new Error("Invalid workflow resume request");
+	const request = value as Partial<NornRunResumeRequest>;
+	if (request.version !== 1 || request.type !== "resume") throw new Error("Unsupported workflow resume request");
+	if (typeof request.id !== "string" || request.id.length === 0) throw new Error("Invalid workflow resume request id");
+	if (request.requestId !== undefined && (typeof request.requestId !== "string" || request.requestId.length === 0)) throw new Error("Invalid workflow resume request token");
+	if (typeof request.createdAt !== "string" || Number.isNaN(Date.parse(request.createdAt))) throw new Error("Invalid workflow resume request timestamp");
+	return request as NornRunResumeRequest;
+}

package/assets/packages/cli/src/internal/logs.ts

@@ -0,0 +1,41 @@
+import { createWriteStream, type WriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import type { NornFileCoordinator } from "@vimhead.dev/norn/files";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { NornLogRef } from "@vimhead.dev/norn";
+
+export type NornLogWriteStream = {
+	readonly log: NornLogRef;
+	readonly stream: WriteStream;
+};
+
+export class NornRunLogs {
+	constructor(private readonly logsRoot: string, private readonly files: NornFileCoordinator) {}
+
+	async write(path: string, content: string): Promise<void> {
+		await this.files.writeText(this.resolveLogPath(path), content);
+	}
+
+	async read(log: NornLogRef): Promise<string> {
+		return this.files.readText(this.resolveLogPath(`${log.id}.log`));
+	}
+
+	async createWriteStream(log: NornLogRef): Promise<NornLogWriteStream> {
+		const absolutePath = this.resolveLogPath(`${log.id}.log`);
+		await mkdir(dirname(absolutePath), { recursive: true });
+		return {
+			log,
+			stream: createWriteStream(absolutePath, { encoding: "utf8" }),
+		};
+	}
+
+	private resolveLogPath(path: string): string {
+		if (isAbsolute(path)) throw new Error(`Log path must be relative: ${path}`);
+		const resolvedPath = resolve(this.logsRoot, path);
+		const relativePath = relative(this.logsRoot, resolvedPath);
+		if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+			throw new Error(`Log path escapes logs directory: ${path}`);
+		}
+		return resolvedPath;
+	}
+}