evalution 1.0.2 → 1.0.4

package/dist/cli/index.js

@@ -1,4 +1,4 @@
-import { a as MemoryTraceProvider, i as setupStepCommand, r as CONFIG_FILE_RELATIVE_PATH, t as VercelAISDK } from "../vercel-ai-sdk-CareWPDM.js";
+import { a as MemoryTraceProvider, i as setupStepCommand, r as CONFIG_FILE_RELATIVE_PATH, t as VercelAISDK } from "../vercel-ai-sdk-B8ivuOzP.js";
 import module from "node:module";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -74,123 +74,15 @@ var PromptRegistry = class {
 	}
 };
 //#endregion
-//#region src/sdk/registry.ts
-/**
-* Every AI SDK offered in manual onboarding, in display order. This is the
-* single source of truth for which SDKs exist and their task ids — adding one
-* to onboarding means giving its adapter a static `setupTask` and listing it
-* here.
-*/
-const AI_SDK_REGISTRY = [VercelAISDK];
-/** Look up a {@link SetupTask} by its id, or `undefined` if none matches. */
-function findSetupTask(taskId) {
-	for (const cls of AI_SDK_REGISTRY) if (cls.setupTask.id === taskId) return cls.setupTask;
-}
-/**
-* Look up a step within a task by both ids, or `undefined` if either is
-* unknown.
-*/
-function findSetupStep(taskId, stepId) {
-	return findSetupTask(taskId)?.steps.find((s) => s.id === stepId);
-}
-//#endregion
-//#region src/server/setup-tasks.ts
-/**
-* Thrown when a requested task or step id does not exist in the registry. The
-* route layer maps this to a 404, distinguishing it from execution failures.
-*/
-var SetupStepNotFoundError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "SetupStepNotFoundError";
-	}
-};
-/**
-* Executes a single onboarding step, resolved from the server-side registry by
-* `taskId`/`stepId`.
-*
-* The client only sends ids; the step definition (file contents, command, ...)
-* comes entirely from {@link AI_SDK_REGISTRY}, so a request can never write
-* arbitrary files or run arbitrary commands.
-*
-* @param rootPath - Absolute path to the project root.
-* @param taskId - Id of the {@link SetupTask} to run a step from.
-* @param stepId - Id of the step within that task.
-* @throws {SetupStepNotFoundError} if the task or step id is unknown.
-* @throws if the step kind is unsupported or execution fails (e.g. the config
-*   file already exists).
-*/
-async function executeSetupStep(rootPath, taskId, stepId) {
-	const step = findSetupStep(taskId, stepId);
-	if (!step) throw new SetupStepNotFoundError(`Unknown step '${stepId}' for task '${taskId}'`);
-	switch (step.kind) {
-		case "create_config": return { path: await writeConfigFile(rootPath, step) };
-		case "run_command":
-		case "install_package": throw new Error(`${step.kind} steps are not yet supported`);
-	}
-}
-/**
-* Returns the onboarding tasks with each step's runtime
-* {@link SetupStepBase.completed | completion status} resolved against the
-* project at `rootPath` (config file present, package installed).
-*
-* @param rootPath - Absolute path to the project root.
-*/
-function resolveSetupTasks(rootPath) {
-	return AI_SDK_REGISTRY.map((cls) => ({
-		...cls.setupTask,
-		steps: cls.setupTask.steps.map((step) => resolveStepStatus(rootPath, step))
-	}));
-}
-/** Adds the runtime `completed` flag to a single step where determinable. */
-function resolveStepStatus(rootPath, step) {
-	switch (step.kind) {
-		case "install_package": return {
-			...step,
-			completed: isPackageInstalled(rootPath, step.package)
-		};
-		case "create_config": return {
-			...step,
-			completed: fs$1.existsSync(path.join(rootPath, step.path))
-		};
-		case "run_command": return step;
-	}
-}
-/**
-* Whether `pkg` is installed for the project at `rootPath`, walking up the
-* directory tree to honour hoisted/workspace `node_modules`.
-*
-* @param rootPath - Absolute path to start the search from.
-* @param pkg - The npm package name to look for.
-*/
-function isPackageInstalled(rootPath, pkg) {
-	let dir = rootPath;
-	while (true) {
-		if (fs$1.existsSync(path.join(dir, "node_modules", pkg, "package.json"))) return true;
-		const parent = path.dirname(dir);
-		if (parent === dir) return false;
-		dir = parent;
-	}
-}
-/**
-* Writes the config file for a `create_config` step, creating parent
-* directories as needed. Refuses to clobber an existing file.
-*/
-async function writeConfigFile(rootPath, step) {
-	const filePath = path.join(rootPath, step.path);
-	try {
-		await fs.access(filePath);
-		throw new Error(`${step.path} already exists`);
-	} catch (err) {
-		if (err?.code !== "ENOENT") throw err;
-	}
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	await fs.writeFile(filePath, step.contents, "utf8");
-	return step.path;
-}
-//#endregion
 //#region src/server/api-routes.ts
-function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hotReloadSubscribers, rootPath, hasConfig, tracer, defaultTraceProviderId }) {
+/** Decodes a URL-safe base64 prompt id produced by `encodePromptId`. Uses the
+* Web `atob` (rather than Node's `Buffer`) so it works in browser/worker
+* bundles too. */
+function decodePromptId(encoded) {
+	const b64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+	return atob(b64);
+}
+function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hotReloadSubscribers, rootPath, hasConfig, tracer, defaultTraceProviderId, setupTasks, executeDisabledMessage }) {
 	const resolveSpanPrompt = (span) => {
 		if (!span.prompt) return span;
 		const resolved = promptRegistry.resolve(span.prompt.id, span.prompt.providerId);
@@ -207,13 +99,17 @@ function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hot
 		rootPath,
 		configured: hasConfig
 	}));
-	app.get("/api/setup-tasks", (c) => c.json(resolveSetupTasks(rootPath)));
+	app.get("/api/setup-tasks", (c) => c.json(setupTasks ? setupTasks.resolve(rootPath) : {
+		agent: [],
+		sdk: []
+	}));
 	app.post("/api/setup-tasks/:taskId/steps/:stepId/execute", async (c) => {
+		if (!setupTasks) return c.json({ error: "Setup tasks are not available" }, 404);
 		const { taskId, stepId } = c.req.param();
 		try {
-			return c.json(await executeSetupStep(rootPath, taskId, stepId));
+			return c.json(await setupTasks.executeStep(rootPath, taskId, stepId));
 		} catch (error) {
-			const status = error instanceof SetupStepNotFoundError ? 404 : 400;
+			const status = error?.name === "SetupStepNotFoundError" ? 404 : 400;
 			return c.json({ error: error.message }, status);
 		}
 	});
@@ -270,7 +166,7 @@ function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hot
 			const { providerId, id } = c.req.param();
 			const provider = promptProviders.get(providerId);
 			if (!provider) return c.json({ error: "Provider not found" }, 404);
-			const decodedId = Buffer.from(id, "base64url").toString("utf8");
+			const decodedId = decodePromptId(id);
 			const prompt = await provider.getPrompt(decodedId);
 			if (!prompt) return c.json({ error: "Prompt not found" }, 404);
 			return c.json({
@@ -288,7 +184,7 @@ function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hot
 			const provider = promptProviders.get(providerId);
 			if (!provider) return c.json({ error: "Provider not found" }, 404);
 			if (!provider.renamePrompt) return c.json({ error: "This provider does not support renaming" }, 405);
-			const decodedId = Buffer.from(id, "base64url").toString("utf8");
+			const decodedId = decodePromptId(id);
 			const updatedPrompt = await provider.renamePrompt(decodedId, newName);
 			return c.json({
 				...updatedPrompt,
@@ -304,7 +200,7 @@ function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hot
 			const provider = promptProviders.get(providerId);
 			if (!provider) return c.json({ error: "Provider not found" }, 404);
 			if (!provider.updatePromptProperties) return c.json({ error: "This provider does not support editing" }, 405);
-			const decodedId = Buffer.from(id, "base64url").toString("utf8");
+			const decodedId = decodePromptId(id);
 			const updatedPrompt = await provider.updatePromptProperties(decodedId, await c.req.json());
 			return c.json({
 				...updatedPrompt,
@@ -316,16 +212,17 @@ function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hot
 	});
 	app.post("/api/prompts/:providerId/:id/execute", async (c) => {
 		try {
+			if (executeDisabledMessage) return c.json({ error: executeDisabledMessage }, 400);
 			const { providerId, id } = c.req.param();
 			const provider = promptProviders.get(providerId);
 			if (!provider) return c.json({ error: "Provider not found" }, 404);
-			const decodedId = Buffer.from(id, "base64url").toString("utf8");
+			const decodedId = decodePromptId(id);
 			const { functionParams = [] } = await c.req.json().catch(() => ({}));
 			const prompt = await provider.getPrompt(decodedId);
 			if (!prompt) return c.json({ error: "Prompt not found" }, 404);
 			const response = tracer.startActiveSpan(prompt.name, (span) => {
 				const { traceId } = span.spanContext();
-				provider.execute(decodedId, functionParams, false).then(() => {
+				provider.execute(decodedId, functionParams).then(() => {
 					span.setStatus({ code: SpanStatusCode.OK });
 				}, (err) => {
 					console.error("prompt execution failed:", err);
@@ -420,10 +317,210 @@ function setupRoutes({ app, promptProviders, traceProviders, promptRegistry, hot
 	}));
 }
 //#endregion
+//#region src/agent/registry.ts
+const AGENT_SETUP_DOMAIN = "evalut.io";
+/** The prompt handed to a coding agent */
+const AGENT_SETUP_PROMPT = `Follow manual setup steps from ${`https://${AGENT_SETUP_DOMAIN}/n/docs/setup.md`}`;
+/**
+* Every coding agent offered a one-click launcher in onboarding, in display
+* order. This is the single source of truth for which agents exist and their
+* task ids — each is a {@link SetupTask} whose lone {@link SetupStep} runs the
+* agent's CLI with the setup prompt queued up in an interactive terminal.
+*
+* Mirrors {@link AI_SDK_REGISTRY} in `../sdk/registry.ts`, but agents have no
+* adapter class, so they live here as plain tasks. `icon` keys into the
+* client's `ProviderIcon`.
+*/
+const AGENT_REGISTRY = [{
+	id: "claude-code",
+	label: "Claude Code",
+	icon: "Anthropic",
+	steps: [{
+		kind: "run_command",
+		id: "launch",
+		command: `claude "${AGENT_SETUP_PROMPT}" --allowedTools "WebFetch(domain:${AGENT_SETUP_DOMAIN})"`,
+		label: "Claude Code"
+	}]
+}, {
+	id: "codex",
+	label: "Codex",
+	icon: "OpenAI",
+	steps: [{
+		kind: "run_command",
+		id: "launch",
+		command: `codex -c 'features.network_proxy.enabled=true' -c 'features.network_proxy.domains={ "${AGENT_SETUP_DOMAIN}" = "allow" }' -c 'sandbox_workspace_write.network_access=true' "${AGENT_SETUP_PROMPT}"`,
+		label: "Codex"
+	}]
+}];
+/** Look up an agent {@link SetupTask} by its id, or `undefined` if none matches. */
+function findSetupTask$1(taskId) {
+	return AGENT_REGISTRY.find((task) => task.id === taskId);
+}
+/**
+* Look up a step within an agent task by both ids, or `undefined` if either is
+* unknown.
+*/
+function findSetupStep$2(taskId, stepId) {
+	return findSetupTask$1(taskId)?.steps.find((s) => s.id === stepId);
+}
+//#endregion
+//#region src/sdk/registry.ts
+/**
+* Every AI SDK offered in manual onboarding, in display order. This is the
+* single source of truth for which SDKs exist and their task ids — adding one
+* to onboarding means giving its adapter a static `setupTask` and listing it
+* here.
+*/
+const AI_SDK_REGISTRY = [VercelAISDK];
+/** Look up a {@link SetupTask} by its id, or `undefined` if none matches. */
+function findSetupTask(taskId) {
+	for (const cls of AI_SDK_REGISTRY) if (cls.setupTask.id === taskId) return cls.setupTask;
+}
+/**
+* Look up a step within a task by both ids, or `undefined` if either is
+* unknown.
+*/
+function findSetupStep$1(taskId, stepId) {
+	return findSetupTask(taskId)?.steps.find((s) => s.id === stepId);
+}
+//#endregion
+//#region src/server/setup-tasks.ts
+/**
+* Resolves a setup step across both the agent and SDK registries by its
+* `taskId`/`stepId`, or `undefined` if neither knows it.
+*/
+function findSetupStep(taskId, stepId) {
+	return findSetupStep$1(taskId, stepId) ?? findSetupStep$2(taskId, stepId);
+}
+/**
+* Thrown when a requested task or step id does not exist in the registry. The
+* route layer maps this to a 404, distinguishing it from execution failures.
+*/
+var SetupStepNotFoundError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SetupStepNotFoundError";
+	}
+};
+/**
+* Executes a single onboarding step, resolved from the server-side registry by
+* `taskId`/`stepId`.
+*
+* The client only sends ids; the step definition (file contents, command, ...)
+* comes entirely from {@link AI_SDK_REGISTRY}, so a request can never write
+* arbitrary files or run arbitrary commands.
+*
+* @param rootPath - Absolute path to the project root.
+* @param taskId - Id of the {@link SetupTask} to run a step from.
+* @param stepId - Id of the step within that task.
+* @throws {SetupStepNotFoundError} if the task or step id is unknown.
+* @throws if the step kind is unsupported or execution fails (e.g. the config
+*   file already exists).
+*/
+async function executeSetupStep(rootPath, taskId, stepId) {
+	const step = findSetupStep(taskId, stepId);
+	if (!step) throw new SetupStepNotFoundError(`Unknown step '${stepId}' for task '${taskId}'`);
+	switch (step.kind) {
+		case "create_config": return { path: await writeConfigFile(rootPath, step) };
+		case "run_command":
+		case "install_package": throw new Error(`${step.kind} steps are not yet supported`);
+		default: throw new Error();
+	}
+}
+/**
+* Returns the onboarding tasks — coding agents and AI SDKs — with each step's
+* runtime {@link SetupStepBase.completed | completion status} resolved against
+* the project at `rootPath` (config file present, package installed).
+*
+* @param rootPath - Absolute path to the project root.
+*/
+function resolveSetupTasks(rootPath) {
+	const resolve = (task) => ({
+		...task,
+		steps: task.steps.map((step) => resolveStepStatus(rootPath, step))
+	});
+	return {
+		agent: AGENT_REGISTRY.map(resolve),
+		sdk: AI_SDK_REGISTRY.map((cls) => resolve(cls.setupTask))
+	};
+}
+/** Adds the runtime `completed` flag to a single step where determinable. */
+function resolveStepStatus(rootPath, step) {
+	switch (step.kind) {
+		case "create_config": return {
+			...step,
+			completed: fs$1.existsSync(path.join(rootPath, step.path))
+		};
+		case "install_package":
+		case "run_command": {
+			const result = { ...step };
+			if (step.kind === "install_package") result.completed = isPackageInstalled(rootPath, step.package);
+			const bin = setupStepCommand(step).split(/\s+/)[0];
+			if (bin && !isBinaryOnPath(bin)) result.disabledReason = `${bin} not found in PATH`;
+			return result;
+		}
+		default: throw new Error();
+	}
+}
+/**
+* Whether an executable named `bin` is resolvable on the current `PATH`. Used
+* to disable coding-agent launchers whose CLI isn't installed. Honours
+* `PATHEXT` on Windows; elsewhere it requires the file to be executable.
+*
+* @param bin - The bare executable name to look for, e.g. `claude`.
+*/
+function isBinaryOnPath(bin) {
+	const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+	const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+	for (const dir of dirs) for (const ext of exts) try {
+		fs$1.accessSync(path.join(dir, bin + ext), fs$1.constants.X_OK);
+		return true;
+	} catch {}
+	return false;
+}
+/**
+* Whether `pkg` is installed for the project at `rootPath`, walking up the
+* directory tree to honour hoisted/workspace `node_modules`.
+*
+* @param rootPath - Absolute path to start the search from.
+* @param pkg - The npm package name to look for.
+*/
+function isPackageInstalled(rootPath, pkg) {
+	let dir = rootPath;
+	while (true) {
+		if (fs$1.existsSync(path.join(dir, "node_modules", pkg, "package.json"))) return true;
+		const parent = path.dirname(dir);
+		if (parent === dir) return false;
+		dir = parent;
+	}
+}
+/**
+* Writes the config file for a `create_config` step, creating parent
+* directories as needed. Refuses to clobber an existing file.
+*/
+async function writeConfigFile(rootPath, step) {
+	const filePath = path.join(rootPath, step.path);
+	try {
+		await fs.access(filePath);
+		throw new Error(`${step.path} already exists`);
+	} catch (err) {
+		if (err?.code !== "ENOENT") throw err;
+	}
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, step.contents, "utf8");
+	return step.path;
+}
+//#endregion
 //#region src/server/terminal.ts
 /** Shell used to run a resolved step command, so shell syntax in it works. */
 const SHELL = process.env.SHELL || (process.platform === "win32" ? "powershell.exe" : "bash");
 /**
+* How long a session's PTY is kept alive after its WebSocket drops, waiting for
+* the client to reconnect. Covers the brief gap while the server restarts
+* itself once a config file appears, so the coding agent isn't killed mid-task.
+*/
+const GRACE_PERIOD_MS = 1e4;
+/**
 * Arguments to run `command` in {@link SHELL}, skipping the user's startup files
 * where the shell allows it. Those rc files (e.g. nvm in `~/.zshrc`) can add
 * seconds of latency before the command even begins, and they are unnecessary
@@ -456,56 +553,184 @@ function resolveTerminalCommand(taskId, stepId) {
 	if (!step || step.kind === "create_config") return null;
 	return setupStepCommand(step);
 }
-function send(ws, message) {
-	ws.send(JSON.stringify(message));
+/** Spawns a real `node-pty` PTY running the command in {@link SHELL}. */
+function defaultSpawn(options) {
+	return pty.spawn(SHELL, shellCommandArgs(options.command), {
+		name: "xterm-color",
+		cols: options.cols || 80,
+		rows: options.rows || 24,
+		cwd: options.cwd,
+		env: options.env
+	});
+}
+/**
+* A single onboarding terminal: one PTY plus the WebSocket currently attached to
+* it. The PTY outlives any one socket so it can survive the server restart that
+* happens when a config file appears — while a client is attached, output is
+* streamed live; while it is detached, output is buffered and a grace timer
+* reaps the PTY if no client reconnects in time.
+*/
+var TerminalSession = class {
+	/** While detached: PTY output accumulated to replay on reconnect. */
+	buffer = null;
+	graceTimer;
+	socket = null;
+	exited = false;
+	child;
+	onReap;
+	gracePeriodMs;
+	/**
+	* @param child - The PTY this session owns.
+	* @param onReap - Called once the session is done (exit, grace expiry, or
+	*   intentional kill) so the registry can drop it.
+	* @param gracePeriodMs - How long to keep the PTY alive after the socket drops.
+	*/
+	constructor(child, onReap, gracePeriodMs = GRACE_PERIOD_MS) {
+		this.child = child;
+		this.onReap = onReap;
+		this.gracePeriodMs = gracePeriodMs;
+		child.onData((data) => this.handleData(data));
+		child.onExit(({ exitCode }) => this.handleExit(exitCode));
+	}
+	send(message) {
+		this.socket?.send(JSON.stringify(message));
+	}
+	handleData(data) {
+		if (this.socket) this.send({
+			type: "data",
+			data
+		});
+		else this.buffer?.push(data);
+	}
+	handleExit(code) {
+		this.exited = true;
+		this.send({
+			type: "exit",
+			code
+		});
+		this.socket?.close();
+		this.clearGrace();
+		this.onReap();
+	}
+	/**
+	* Attach a (re)connected socket. Replays any output buffered while detached,
+	* then resumes live streaming. Cancels a pending grace-period reap.
+	*/
+	attach(ws) {
+		this.clearGrace();
+		this.socket = ws;
+		if (this.buffer) {
+			for (const data of this.buffer) this.send({
+				type: "data",
+				data
+			});
+			this.buffer = null;
+		}
+	}
+	/**
+	* The attached socket dropped (e.g. the server is restarting). Start buffering
+	* output and a grace timer; if no client reattaches in time, reap the PTY.
+	*/
+	detach() {
+		if (this.exited || !this.socket) return;
+		this.socket = null;
+		this.buffer = [];
+		this.graceTimer = setTimeout(() => {
+			this.buffer = null;
+			if (!this.exited) this.child.kill();
+			this.onReap();
+		}, this.gracePeriodMs);
+	}
+	/** The client intentionally left: kill the PTY now, skipping the grace wait. */
+	kill() {
+		this.clearGrace();
+		this.socket = null;
+		this.buffer = null;
+		if (!this.exited) this.child.kill();
+		this.onReap();
+	}
+	/** Forward the user's keystrokes to the PTY. */
+	write(data) {
+		this.child.write(data);
+	}
+	/** Resize the PTY to match the client's terminal. */
+	resize(cols, rows) {
+		this.child.resize(cols || 80, rows || 24);
+	}
+	clearGrace() {
+		if (this.graceTimer) {
+			clearTimeout(this.graceTimer);
+			this.graceTimer = void 0;
+		}
+	}
+};
+/**
+* Holds the live {@link TerminalSession | terminal sessions} keyed by a
+* client-supplied session id. Owned by the CLI process (not by any one server
+* instance) so sessions — and the PTYs they wrap — survive the server restart
+* that happens when a config file appears.
+*/
+var TerminalSessionRegistry = class {
+	sessions = /* @__PURE__ */ new Map();
+	spawn;
+	gracePeriodMs;
+	/**
+	* @param spawn - PTY spawner; overridable in tests.
+	* @param gracePeriodMs - Reconnect grace window passed to each session.
+	*/
+	constructor(spawn = defaultSpawn, gracePeriodMs = GRACE_PERIOD_MS) {
+		this.spawn = spawn;
+		this.gracePeriodMs = gracePeriodMs;
+	}
+	/** The session for `id`, if one is still live. */
+	get(id) {
+		return this.sessions.get(id);
+	}
+	/** Spawn a PTY and register a new session under `id`. */
+	create(id, options) {
+		const session = new TerminalSession(this.spawn(options), () => this.sessions.delete(id), this.gracePeriodMs);
+		this.sessions.set(id, session);
+		return session;
+	}
+};
+function sendError(ws, message) {
+	ws.send(JSON.stringify({
+		type: "error",
+		message
+	}));
 }
 /**
 * Registers the interactive-terminal WebSocket route at `/api/terminal`.
 *
-* The client connects with `taskId` and `stepId` query params identifying a
-* setup step; the server resolves the actual command from its own registry
-* (never from the request body) and, once the client signals `start`, spawns it
-* in a PTY rooted at the project. Output is streamed to the client and the
-* client's keystrokes are written to the process, so prompts (e.g. npm's
-* "Ok to proceed?") work. The trust boundary mirrors the step-execute route:
-* the client can only ask to run a step that already exists server-side.
+* The client connects with `taskId`, `stepId`, and a client-generated
+* `sessionId` query param. The server resolves the actual command from its own
+* registry (never from the request body). On the first connection for a session
+* the client signals `start` and the server spawns the command in a PTY rooted
+* at the project; output is streamed to the client and the client's keystrokes
+* are written to the process, so prompts (e.g. npm's "Ok to proceed?") work.
+*
+* Sessions live in `sessions`, which outlives this server instance, so when the
+* server restarts itself after a config file appears the PTY keeps running and a
+* reconnecting client (same `sessionId`) re-attaches and replays the gap.
+*
+* The trust boundary mirrors the step-execute route: the client can only ask to
+* run a step that already exists server-side.
 */
-function registerTerminalRoute(app, upgradeWebSocket, rootPath) {
+function registerTerminalRoute(app, upgradeWebSocket, rootPath, sessions) {
 	app.get("/api/terminal", upgradeWebSocket((c) => {
 		const taskId = c.req.query("taskId");
 		const stepId = c.req.query("stepId");
-		let child;
-		const start = (ws, cols, rows) => {
-			if (child) return;
-			const command = taskId && stepId ? resolveTerminalCommand(taskId, stepId) : null;
-			if (!command) {
-				send(ws, {
-					type: "error",
-					message: "Unknown or non-runnable setup step."
-				});
-				ws.close();
-				return;
-			}
-			child = pty.spawn(SHELL, shellCommandArgs(command), {
-				name: "xterm-color",
-				cols: cols || 80,
-				rows: rows || 24,
-				cwd: rootPath,
-				env: process.env
-			});
-			child.onData((data) => send(ws, {
-				type: "data",
-				data
-			}));
-			child.onExit(({ exitCode }) => {
-				send(ws, {
-					type: "exit",
-					code: exitCode
-				});
-				ws.close();
-			});
-		};
+		const sessionId = c.req.query("sessionId") ?? `${taskId}:${stepId}`;
+		let session;
+		let leaving = false;
 		return {
+			onOpen(_evt, ws) {
+				const existing = sessions.get(sessionId);
+				if (existing) {
+					session = existing;
+					existing.attach(ws);
+				}
+			},
 			onMessage(evt, ws) {
 				let msg;
 				try {
@@ -514,20 +739,38 @@ function registerTerminalRoute(app, upgradeWebSocket, rootPath) {
 					return;
 				}
 				switch (msg.type) {
-					case "start":
-						start(ws, msg.cols, msg.rows);
+					case "start": {
+						if (session) return;
+						const command = taskId && stepId ? resolveTerminalCommand(taskId, stepId) : null;
+						if (!command) {
+							sendError(ws, "Unknown or non-runnable setup step.");
+							ws.close();
+							return;
+						}
+						session = sessions.create(sessionId, {
+							command,
+							cols: msg.cols,
+							rows: msg.rows,
+							cwd: rootPath,
+							env: process.env
+						});
+						session.attach(ws);
 						break;
+					}
 					case "input":
-						child?.write(msg.data);
+						session?.write(msg.data);
 						break;
 					case "resize":
-						child?.resize(msg.cols || 80, msg.rows || 24);
+						session?.resize(msg.cols || 80, msg.rows || 24);
+						break;
+					case "detach":
+						leaving = true;
+						session?.kill();
 						break;
 				}
 			},
 			onClose() {
-				child?.kill();
-				child = void 0;
+				if (!leaving) session?.detach();
 			}
 		};
 	}));
@@ -535,7 +778,7 @@ function registerTerminalRoute(app, upgradeWebSocket, rootPath) {
 //#endregion
 //#region src/server/index.ts
 async function startServer(options) {
-	const { promptProviders, traceProviders, port, rootPath, hasConfig } = options;
+	const { promptProviders, traceProviders, port, rootPath, hasConfig, terminalSessions } = options;
 	const promptProviderMap = new Map(promptProviders.map((p) => [p.id, p]));
 	const traceProviderMap = new Map(traceProviders.map((p) => [p.id, p]));
 	const promptRegistry = new PromptRegistry();
@@ -562,9 +805,13 @@ async function startServer(options) {
 		rootPath,
 		hasConfig,
 		tracer,
-		defaultTraceProviderId
+		defaultTraceProviderId,
+		setupTasks: {
+			resolve: resolveSetupTasks,
+			executeStep: executeSetupStep
+		}
 	});
-	registerTerminalRoute(app, upgradeWebSocket, rootPath);
+	registerTerminalRoute(app, upgradeWebSocket, rootPath, terminalSessions);
 	const clientRoot = fileURLToPath(new URL("../client/", import.meta.url));
 	app.get("*", serveStatic({ root: clientRoot }));
 	for (const [providerId, provider] of promptProviderMap) if (provider.watch) provider.watch(async (event) => {
@@ -600,6 +847,7 @@ async function startServer(options) {
 		});
 	});
 	const close = () => new Promise((resolve, reject) => {
+		for (const ws of wss.clients) ws.close();
 		if ("closeAllConnections" in server) server.closeAllConnections();
 		server.close((err) => err ? reject(err) : resolve());
 	});
@@ -823,14 +1071,15 @@ function applyDotenv(rootDir) {
 		if (err?.code !== "ENOENT") console.warn(`Warning: failed to load .env from ${envPath}:`, err.message);
 	}
 }
-function startConfiguredServer(rootDir, config, hasConfig, port) {
+function startConfiguredServer(rootDir, config, hasConfig, port, terminalSessions) {
 	if (config.useDotenv !== false) applyDotenv(rootDir);
 	return startServer({
 		promptProviders: config.promptProviders ?? [],
 		traceProviders: config.traceProviders ?? [new MemoryTraceProvider()],
 		port,
 		rootPath: rootDir,
-		hasConfig
+		hasConfig,
+		terminalSessions
 	});
 }
 async function main() {
@@ -848,11 +1097,12 @@ async function main() {
 	const maybeOpen = (url) => {
 		if (!process.env.EVALUTION_NO_OPEN) openBrowser(url);
 	};
+	const terminalSessions = new TerminalSessionRegistry();
 	if (hasConfig) {
-		maybeOpen((await startConfiguredServer(rootDir, await loadConfig(rootDir), true, port)).url);
+		maybeOpen((await startConfiguredServer(rootDir, await loadConfig(rootDir), true, port, terminalSessions)).url);
 		return;
 	}
-	let server = await startConfiguredServer(rootDir, {}, false, port);
+	let server = await startConfiguredServer(rootDir, {}, false, port, terminalSessions);
 	maybeOpen(server.url);
 	console.log(`👀 No config found; watching ${path.join(rootDir, ".evalution", "config.ts")} for creation...`);
 	const stopWatching = watchForConfigCreation(rootDir, async () => {
@@ -860,7 +1110,7 @@ async function main() {
 		console.log("⚙️ Config loaded; restarting server...");
 		stopWatching();
 		await server.close();
-		server = await startConfiguredServer(rootDir, config, true, port);
+		server = await startConfiguredServer(rootDir, config, true, port, terminalSessions);
 	});
 }
 main().catch((error) => {