ptywright 0.1.0 → 0.2.0

package/dist/runner-DzZlFrt1.mjs

@@ -0,0 +1,1897 @@
+import { z } from "zod";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chromium } from "playwright";
+import { createServer } from "node:http";
+//#region src/agent/manifest.ts
+const AGENT_MANIFEST_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-manifest.schema.json";
+const AGENT_MANIFEST_FILE_NAME = "ptywright-agent.manifest.json";
+const agentManifestKindSchema = z.enum([
+	"run",
+	"replay-suite",
+	"check",
+	"promote"
+]);
+const agentManifestFileKindSchema = z.enum([
+	"flow",
+	"cassette",
+	"run-record",
+	"replay-summary",
+	"check-summary",
+	"promote-summary",
+	"report",
+	"terminal",
+	"dom",
+	"screenshot",
+	"diff"
+]);
+const agentManifestCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const agentManifestValidationStageSchema = z.object({
+	name: z.string().min(1),
+	ok: z.boolean(),
+	totalCount: z.number().int().nonnegative(),
+	failureCount: z.number().int().nonnegative()
+}).strict();
+const agentManifestValidationSchema = z.object({
+	ok: z.boolean(),
+	stages: z.array(agentManifestValidationStageSchema)
+}).strict().superRefine((validation, ctx) => {
+	const ok = validation.stages.every((stage) => stage.ok && stage.failureCount === 0);
+	if (validation.ok !== ok) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["ok"],
+		message: "validation ok must match validation stages"
+	});
+});
+const agentManifestFileSchema = z.object({
+	path: z.string().min(1),
+	kind: agentManifestFileKindSchema,
+	role: z.string().min(1).optional(),
+	ok: z.boolean().optional(),
+	bytes: z.number().int().nonnegative(),
+	sha256: z.string().regex(/^[a-f0-9]{64}$/)
+}).strict();
+const agentManifestSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	kind: agentManifestKindSchema,
+	ok: z.boolean(),
+	generatedAt: z.string().min(1),
+	rootDir: z.string().min(1),
+	primaryPath: z.string().min(1),
+	commands: z.record(agentManifestCommandSchema),
+	validation: agentManifestValidationSchema.optional(),
+	files: z.array(agentManifestFileSchema)
+}).strict().superRefine((manifest, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const file of manifest.files) {
+		if (seen.has(file.path)) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ["files"],
+			message: `duplicate manifest file path: ${file.path}`
+		});
+		seen.add(file.path);
+	}
+});
+function agentManifestPath(rootDir) {
+	return join(rootDir, AGENT_MANIFEST_FILE_NAME);
+}
+function createAgentManifest(options) {
+	return normalizeAgentManifest({
+		$schema: AGENT_MANIFEST_SCHEMA_URL,
+		version: 1,
+		kind: options.kind,
+		ok: options.ok,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		rootDir: options.rootDir,
+		primaryPath: options.primaryPath,
+		commands: options.commands,
+		validation: options.validation,
+		files: collectManifestFiles(options.files, options.rootDir)
+	});
+}
+function readAgentManifestPath(path) {
+	return normalizeAgentManifest(JSON.parse(readFileSync(path, "utf8")));
+}
+function writeAgentManifestPath(path, options) {
+	const manifest = createAgentManifest(options);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+	return manifest;
+}
+function normalizeAgentManifest(input) {
+	try {
+		const parsed = agentManifestSchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-manifest.schema.json"
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid agent manifest: ${formatZodIssues$1(error)}`);
+		throw error;
+	}
+}
+function validateAgentManifestFiles(manifest, manifestPath) {
+	const failures = [];
+	const baseDir = manifestPath ? dirname(resolve(process.cwd(), manifestPath)) : resolve(process.cwd(), manifest.rootDir);
+	for (const file of manifest.files) {
+		let current = null;
+		try {
+			current = readManifestFile(file, baseDir);
+		} catch (error) {
+			failures.push(`${file.path}: ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		if (current.bytes !== file.bytes) failures.push(`${file.path}: bytes ${current.bytes} !== ${file.bytes}`);
+		if (current.sha256 !== file.sha256) failures.push(`${file.path}: sha256 ${current.sha256} !== ${file.sha256}`);
+	}
+	if (failures.length > 0) throw new Error(`invalid agent manifest files: ${failures.join("; ")}`);
+}
+function isAgentManifestLike(input) {
+	return typeof input === "object" && input !== null && input.version === 1 && typeof input.kind === "string" && Array.isArray(input.files) && typeof input.commands === "object";
+}
+function collectManifestFiles(files, rootDir) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	const rootAbs = resolve(process.cwd(), rootDir);
+	for (const file of files) {
+		if (!file.path || seen.has(file.path)) continue;
+		seen.add(file.path);
+		try {
+			out.push(readManifestFile(file, rootAbs, { portableRoot: true }));
+		} catch {}
+	}
+	return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+function readManifestFile(file, baseDir, options = {}) {
+	if (!file.path) throw new Error("missing file path");
+	const absPath = isAbsolute(file.path) ? file.path : resolve(options.portableRoot ? process.cwd() : baseDir, file.path);
+	if (!statSync(absPath).isFile()) throw new Error("not a file");
+	const bytes = readFileSync(absPath);
+	return {
+		path: options.portableRoot ? portableManifestPath(absPath, baseDir) : file.path,
+		kind: file.kind,
+		role: file.role,
+		ok: file.ok,
+		bytes: bytes.byteLength,
+		sha256: createHash("sha256").update(bytes).digest("hex")
+	};
+}
+function portableManifestPath(absPath, rootAbs) {
+	const rel = relative(rootAbs, absPath);
+	if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
+	return absPath;
+}
+function formatZodIssues$1(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/agent/aitty.ts
+function buildAittyExecCommand(launch, options = {}) {
+	if (!launch.command) throw new Error("launch.command is required for aitty mode");
+	const rootDir = options.rootDir ?? process.cwd();
+	const cwd = launch.cwd ? resolve(rootDir, launch.cwd) : rootDir;
+	const aitty = launch.aitty ?? {};
+	const cli = resolveAittyCliCommand(aitty.command, rootDir, options.env ?? process.env);
+	const args = [
+		...cli.args,
+		"exec",
+		"--launch",
+		"print"
+	];
+	pushOption(args, "--cwd", cwd);
+	pushOption(args, "--host", aitty.host);
+	pushOption(args, "--port", aitty.port);
+	pushOption(args, "--project", aitty.project);
+	pushOption(args, "--label", aitty.label);
+	pushOption(args, "--title", aitty.title);
+	pushOption(args, "--subtitle", aitty.subtitle);
+	pushOption(args, "--theme", aitty.theme && aitty.theme !== "auto" ? aitty.theme : void 0);
+	pushOption(args, "--font-size", aitty.fontSize);
+	pushOption(args, "--experimental-screen-mode", aitty.screenMode);
+	args.push("--", launch.command, ...launch.args ?? []);
+	return {
+		file: cli.file,
+		args,
+		cwd,
+		env: {
+			...options.env ?? process.env,
+			...launch.env
+		}
+	};
+}
+async function launchAittyBrowserSession(launch, options = {}) {
+	const command = buildAittyExecCommand(launch, options);
+	const timeoutMs = launch.aitty?.waitForUrlMs ?? 15e3;
+	const child = spawn(command.file, command.args, {
+		cwd: command.cwd,
+		env: command.env,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	const chunks = [];
+	const stderrChunks = [];
+	return {
+		url: await new Promise((resolveUrl, reject) => {
+			let settled = false;
+			const timer = setTimeout(() => {
+				finish(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for aitty session URL\nstderr=${stderrChunks.join("").trim()}`));
+			}, timeoutMs);
+			const finish = (result) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				child.stdout.off("data", onStdout);
+				child.stderr.off("data", onStderr);
+				child.off("error", onError);
+				child.off("exit", onExit);
+				if (result instanceof Error) reject(result);
+				else resolveUrl(result);
+			};
+			const onStdout = (chunk) => {
+				const text = chunk.toString("utf8");
+				chunks.push(text);
+				const found = extractAittyUrlFromOutput(chunks.join(""));
+				if (found) finish(found);
+			};
+			const onStderr = (chunk) => {
+				stderrChunks.push(chunk.toString("utf8"));
+			};
+			const onError = (error) => finish(error);
+			const onExit = (code, signal) => {
+				finish(/* @__PURE__ */ new Error(`aitty exited before printing a session URL (code=${code ?? "null"} signal=${signal ?? "null"})\nstdout=${chunks.join("").trim()}\nstderr=${stderrChunks.join("").trim()}`));
+			};
+			child.stdout.on("data", onStdout);
+			child.stderr.on("data", onStderr);
+			child.once("error", onError);
+			child.once("exit", onExit);
+		}),
+		process: child,
+		close: () => closeChild(child)
+	};
+}
+function extractAittyUrlFromOutput(output) {
+	return output.match(/https?:\/\/[^\s"'<>]+/)?.[0] ?? null;
+}
+function resolveAittyCliCommand(explicitCommand, rootDir, env) {
+	if (explicitCommand) return {
+		file: explicitCommand,
+		args: []
+	};
+	if (env.PTYWRIGHT_AITTY_CLI) return {
+		file: env.PTYWRIGHT_AITTY_CLI,
+		args: []
+	};
+	const siblingDist = resolve(rootDir, "../aitty/packages/cli/dist/cli.js");
+	if (existsSync(siblingDist)) return {
+		file: "node",
+		args: [siblingDist]
+	};
+	return {
+		file: "aitty",
+		args: []
+	};
+}
+function pushOption(args, name, value) {
+	if (value === void 0 || value === "") return;
+	args.push(name, String(value));
+}
+async function closeChild(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	await new Promise((resolveClose) => {
+		const timer = setTimeout(() => {
+			if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+			resolveClose();
+		}, 2e3);
+		child.once("exit", () => {
+			clearTimeout(timer);
+			resolveClose();
+		});
+		child.kill("SIGTERM");
+	});
+}
+//#endregion
+//#region src/agent/browser.ts
+async function launchAgentBrowser(args) {
+	let lastError;
+	for (let attempt = 0; attempt < 5; attempt += 1) try {
+		const browser = await chromium.launch({ headless: args.headless });
+		await verifyBrowserLaunch(browser);
+		return browser;
+	} catch (error) {
+		lastError = error;
+		if (!isTransientBrowserLaunchError(error) || attempt === 4) throw error;
+		await new Promise((resolveRetry) => setTimeout(resolveRetry, 250 * (attempt + 1)));
+	}
+	throw lastError;
+}
+async function verifyBrowserLaunch(browser) {
+	const context = await browser.newContext();
+	try {
+		const page = await context.newPage();
+		await page.goto("data:text/html,<title>ptywright</title>", { waitUntil: "load" });
+		await page.close();
+	} catch (error) {
+		await browser.close();
+		throw error;
+	} finally {
+		await context.close().catch(() => void 0);
+	}
+}
+function isTransientBrowserLaunchError(error) {
+	const fields = errorFields(error);
+	return fields.message.includes("Failed to connect") || fields.message.includes("Target page, context or browser has been closed") || fields.message.includes("browserType.launch") || fields.code === "ENOENT" || fields.code === "ECONNREFUSED" || fields.syscall === "connect";
+}
+function errorFields(error) {
+	const record = typeof error === "object" && error !== null ? error : {};
+	return {
+		message: error instanceof Error ? error.message : String(error),
+		code: typeof record.code === "string" ? record.code : "",
+		syscall: typeof record.syscall === "string" ? record.syscall : ""
+	};
+}
+//#endregion
+//#region src/agent/normalize.ts
+function applyAgentMasks(input, rules = []) {
+	let out = input;
+	for (const rule of rules) {
+		const flags = rule.flags ?? "g";
+		const regex = new RegExp(rule.regex, flags.includes("g") ? flags : `${flags}g`);
+		const replacement = rule.replacement ?? "<masked>";
+		out = out.replace(regex, (match) => {
+			if (!rule.preserveLength) return replacement;
+			if (replacement.length === match.length) return replacement;
+			if (replacement.length > match.length) return replacement.slice(0, match.length);
+			return replacement + "*".repeat(match.length - replacement.length);
+		});
+	}
+	return out;
+}
+function normalizeTerminalText(input, rules = []) {
+	const lines = applyAgentMasks(input.replace(/\r\n?/g, "\n"), rules).split("\n").map((line) => line.trimEnd());
+	while (lines[0]?.trim() === "") lines.shift();
+	while (lines.at(-1)?.trim() === "") lines.pop();
+	return lines.join("\n");
+}
+function normalizeDomSnapshot(input, rules = []) {
+	return applyAgentMasks(input.replace(/\sdata-v-[a-z0-9-]+="[^"]*"/g, "").replace(/\sstyle="[^"]*--term-(?:cell-width|row-height):[^"]*"/g, "").replace(/\s+/g, " ").replace(/>\s+</g, "><").replace(/<div class="[^"]*\bterm-row\b[^"]*\bterm-scrollback-row\b[^"]*"[^>]*><span[^>]*><\/span><\/div>/g, "").trim(), rules);
+}
+function sanitizeArtifactName(input) {
+	return input.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "artifact";
+}
+function shortHash(input) {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i += 1) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	return hash.toString(16).padStart(8, "0");
+}
+//#endregion
+//#region src/agent/schema.ts
+const agentTextMaskRuleSchema = z.object({
+	regex: z.string().min(1),
+	flags: z.string().optional(),
+	replacement: z.string().optional(),
+	preserveLength: z.boolean().optional()
+});
+const agentViewportSchema = z.object({
+	name: z.string().min(1),
+	width: z.number().int().positive(),
+	height: z.number().int().positive(),
+	deviceScaleFactor: z.number().positive().optional(),
+	isMobile: z.boolean().optional(),
+	hasTouch: z.boolean().optional()
+});
+const agentLaunchSchema = z.object({
+	mode: z.enum(["aitty", "url"]).optional(),
+	agentFlavor: z.enum([
+		"codex",
+		"claude",
+		"droid",
+		"generic"
+	]).optional(),
+	command: z.string().min(1).optional(),
+	args: z.array(z.string()).optional(),
+	cwd: z.string().optional(),
+	env: z.record(z.string()).optional(),
+	url: z.string().url().optional(),
+	aitty: z.object({
+		command: z.string().min(1).optional(),
+		args: z.array(z.string()).optional(),
+		project: z.string().min(1).optional(),
+		label: z.string().min(1).optional(),
+		title: z.string().min(1).optional(),
+		subtitle: z.string().min(1).optional(),
+		theme: z.enum([
+			"dark",
+			"light",
+			"auto"
+		]).optional(),
+		fontSize: z.number().int().min(11).max(24).optional(),
+		screenMode: z.enum(["termvision"]).optional(),
+		port: z.number().int().min(0).max(65535).optional(),
+		host: z.string().min(1).optional(),
+		waitForUrlMs: z.number().int().positive().optional()
+	}).optional()
+}).superRefine((value, ctx) => {
+	const mode = value.mode ?? (value.url ? "url" : "aitty");
+	if (mode === "url" && !value.url) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "launch.url is required when launch.mode is 'url'"
+	});
+	if (mode === "aitty" && !value.command) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "launch.command is required when launch.mode is 'aitty'"
+	});
+});
+const waitForTextStepSchema = z.object({
+	type: z.literal("waitForText"),
+	text: z.string().optional(),
+	regex: z.string().optional(),
+	timeoutMs: z.number().int().positive().optional()
+}).superRefine((value, ctx) => {
+	if (!value.text && !value.regex) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "waitForText requires text or regex"
+	});
+});
+const typeTextStepSchema = z.object({
+	type: z.literal("typeText"),
+	text: z.string(),
+	enter: z.boolean().optional(),
+	delayMs: z.number().int().nonnegative().optional()
+});
+const pressKeyStepSchema = z.object({
+	type: z.literal("pressKey"),
+	key: z.string().min(1)
+});
+const clickStepSchema = z.object({
+	type: z.literal("click"),
+	selector: z.string().min(1).optional(),
+	text: z.string().min(1).optional(),
+	x: z.number().int().nonnegative().optional(),
+	y: z.number().int().nonnegative().optional()
+}).superRefine((value, ctx) => {
+	if (!value.selector && !value.text && (value.x === void 0 || value.y === void 0)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "click requires selector, text, or x/y coordinates"
+	});
+});
+const waitForStableDomStepSchema = z.object({
+	type: z.literal("waitForStableDom"),
+	timeoutMs: z.number().int().positive().optional(),
+	quietMs: z.number().int().positive().optional(),
+	intervalMs: z.number().int().positive().optional()
+});
+const snapshotStepSchema = z.object({
+	type: z.literal("snapshot"),
+	name: z.string().min(1),
+	compare: z.boolean().optional(),
+	targets: z.array(z.enum([
+		"terminal",
+		"dom",
+		"screenshot"
+	])).optional(),
+	fullPage: z.boolean().optional()
+});
+const markStepSchema = z.object({
+	type: z.literal("mark"),
+	label: z.string().optional()
+});
+const sleepStepSchema = z.object({
+	type: z.literal("sleep"),
+	ms: z.number().int().nonnegative()
+});
+const agentFlowStepSchema = z.union([
+	waitForTextStepSchema,
+	typeTextStepSchema,
+	pressKeyStepSchema,
+	clickStepSchema,
+	waitForStableDomStepSchema,
+	snapshotStepSchema,
+	markStepSchema,
+	sleepStepSchema
+]);
+const agentFlowSpecSchema = z.object({
+	name: z.string().min(1).optional(),
+	artifactsDir: z.string().optional(),
+	snapshotDir: z.string().optional(),
+	launch: agentLaunchSchema,
+	viewports: z.array(agentViewportSchema).min(1).optional(),
+	defaults: z.object({
+		timeoutMs: z.number().int().positive().optional(),
+		mask: z.array(agentTextMaskRuleSchema).optional(),
+		screenshot: z.boolean().optional()
+	}).optional(),
+	steps: z.array(agentFlowStepSchema).min(1)
+});
+const DEFAULT_AGENT_VIEWPORTS = [{
+	name: "desktop-1440",
+	width: 1440,
+	height: 960,
+	deviceScaleFactor: 1
+}];
+function normalizeAgentFlowSpec(input) {
+	const spec = agentFlowSpecSchema.parse(input);
+	return {
+		...spec,
+		name: spec.name ?? "agent-flow",
+		viewports: spec.viewports?.length ? spec.viewports : [...DEFAULT_AGENT_VIEWPORTS]
+	};
+}
+//#endregion
+//#region src/agent/cassette.ts
+const AGENT_CASSETTE_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-cassette.schema.json";
+const agentCassetteFrameSchema = z.object({
+	viewport: agentViewportSchema,
+	phase: z.number().int().nonnegative(),
+	stepIndex: z.number().int().nonnegative().nullable(),
+	stepType: z.string().min(1),
+	terminalText: z.string(),
+	terminalHash: z.string().min(1),
+	dom: z.string(),
+	domHash: z.string().min(1),
+	capturedAt: z.string().min(1)
+});
+const agentCassetteSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	name: z.string().min(1),
+	createdAt: z.string().min(1),
+	spec: agentFlowSpecSchema.optional(),
+	frames: z.array(agentCassetteFrameSchema).min(1)
+});
+function createAgentCassette(name, spec) {
+	return {
+		$schema: AGENT_CASSETTE_SCHEMA_URL,
+		version: 1,
+		name,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		spec: normalizeAgentFlowSpec(spec),
+		frames: []
+	};
+}
+function normalizeAgentCassette(input, fallbackSpec) {
+	const parsed = agentCassetteSchema.parse(input);
+	const specInput = parsed.spec ?? fallbackSpec;
+	if (!specInput) throw new Error("invalid agent cassette: missing spec");
+	validateCassetteFrameHashes(parsed.frames);
+	return {
+		...parsed,
+		$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-cassette.schema.json",
+		spec: normalizeAgentFlowSpec(specInput)
+	};
+}
+function validateCassetteFrameHashes(frames) {
+	for (const frame of frames) {
+		if (shortHash(frame.terminalText) !== frame.terminalHash) throw new Error(`invalid agent cassette: terminal hash mismatch viewport=${frame.viewport.name} phase=${frame.phase}`);
+		if (shortHash(frame.dom) !== frame.domHash) throw new Error(`invalid agent cassette: dom hash mismatch viewport=${frame.viewport.name} phase=${frame.phase}`);
+	}
+}
+function readAgentCassettePath(path, fallbackSpec) {
+	return normalizeAgentCassette(JSON.parse(readFileSync(path, "utf8")), fallbackSpec);
+}
+function isAgentCassetteLike(input) {
+	return typeof input === "object" && input !== null && input.version === 1 && Array.isArray(input.frames);
+}
+function upsertAgentCassetteFrame(cassette, frame) {
+	const next = {
+		...frame,
+		terminalHash: shortHash(frame.terminalText),
+		domHash: shortHash(frame.dom)
+	};
+	const index = cassette.frames.findIndex((candidate) => candidate.viewport.name === next.viewport.name && candidate.phase === next.phase);
+	if (index >= 0) {
+		cassette.frames[index] = next;
+		return;
+	}
+	cassette.frames.push(next);
+}
+async function startAgentCassetteServer(cassette) {
+	const sockets = /* @__PURE__ */ new Set();
+	const server = createServer((request, response) => {
+		if (request.url === "/health") {
+			response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+			response.end("ok");
+			return;
+		}
+		response.writeHead(200, {
+			"cache-control": "no-store",
+			"content-type": "text/html; charset=utf-8"
+		});
+		response.end(renderCassetteHtml(cassette));
+	});
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.once("close", () => {
+			sockets.delete(socket);
+		});
+	});
+	await new Promise((resolveListen, rejectListen) => {
+		const onError = (error) => {
+			server.off("listening", onListening);
+			rejectListen(error);
+		};
+		const onListening = () => {
+			server.off("error", onError);
+			resolveListen();
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen(0, "127.0.0.1");
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") {
+		await closeServer(server);
+		throw new Error("failed to bind cassette replay server");
+	}
+	return {
+		url: `http://127.0.0.1:${address.port}/`,
+		close: () => closeServer(server, sockets)
+	};
+}
+function renderCassetteHtml(cassette) {
+	const framesJson = JSON.stringify(cassette.frames).replace(/</g, "\\u003c");
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml$1(cassette.name)} cassette replay</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        background: #101418;
+        color: #eef3f8;
+        font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      }
+      body {
+        margin: 0;
+        background: #101418;
+      }
+      [data-terminal-root] {
+        min-height: 100vh;
+        outline: none;
+      }
+      .term-grid {
+        white-space: pre;
+      }
+      .term-row {
+        min-height: 1em;
+      }
+    </style>
+  </head>
+  <body>
+    <div data-terminal-root tabindex="0"></div>
+    <script>
+      const frames = ${framesJson};
+      const root = document.querySelector("[data-terminal-root]");
+      let phase = 0;
+
+      function viewportScore(frame) {
+        const viewport = frame.viewport || {};
+        return Math.abs((viewport.width || window.innerWidth) - window.innerWidth) +
+          Math.abs((viewport.height || window.innerHeight) - window.innerHeight);
+      }
+
+      function chooseFrame() {
+        const eligible = frames
+          .filter((frame) => Number(frame.phase || 0) <= phase)
+          .sort((a, b) => {
+            const phaseDelta = Number(b.phase || 0) - Number(a.phase || 0);
+            if (phaseDelta !== 0) return phaseDelta;
+            return viewportScore(a) - viewportScore(b);
+          });
+        return eligible[0] || frames.slice().sort((a, b) => viewportScore(a) - viewportScore(b))[0];
+      }
+
+      function renderText(text) {
+        const grid = document.createElement("div");
+        grid.className = "term-grid";
+        for (const line of String(text || "").split("\\n")) {
+          const row = document.createElement("div");
+          row.className = "term-row";
+          const span = document.createElement("span");
+          span.textContent = line;
+          row.appendChild(span);
+          grid.appendChild(row);
+        }
+        root.replaceChildren(grid);
+      }
+
+      function render() {
+        const frame = chooseFrame();
+        if (!frame) {
+          renderText("");
+          return;
+        }
+        if (frame.dom) {
+          root.innerHTML = frame.dom;
+        } else {
+          renderText(frame.terminalText || "");
+        }
+        root.dataset.replayPhase = String(phase);
+      }
+
+      window.__ptywrightReplaySetPhase = (nextPhase) => {
+        const parsed = Number(nextPhase);
+        phase = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : phase;
+        render();
+      };
+
+      window.addEventListener("resize", render);
+      root.addEventListener("focus", render);
+      root.focus();
+      render();
+    <\/script>
+  </body>
+</html>`;
+}
+async function closeServer(server, sockets) {
+	const serverWithConnectionClosers = server;
+	serverWithConnectionClosers.closeIdleConnections?.();
+	await new Promise((resolveClose, rejectClose) => {
+		const forceCloseTimer = setTimeout(() => {
+			serverWithConnectionClosers.closeAllConnections?.();
+			for (const socket of sockets) socket.destroy();
+		}, 500);
+		const finishTimer = setTimeout(() => {
+			resolveClose();
+		}, 2e3);
+		server.close((error) => {
+			clearTimeout(forceCloseTimer);
+			clearTimeout(finishTimer);
+			if (error) rejectClose(error);
+			else resolveClose();
+		});
+	});
+}
+function escapeHtml$1(input) {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+//#endregion
+//#region src/agent/presets.ts
+const COMMON_AGENT_MASKS = [
+	{
+		regex: "\\b\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:?\\d{2})?\\b",
+		replacement: "<timestamp>"
+	},
+	{
+		regex: "\\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\b",
+		flags: "gi",
+		replacement: "<uuid>"
+	},
+	{
+		regex: "\\b(?:req|run|msg|chatcmpl|call|toolu|session)_[A-Za-z0-9_-]{8,}\\b",
+		replacement: "<id>"
+	},
+	{
+		regex: "\\b(?:[0-9a-f]{7,40})\\b",
+		flags: "gi",
+		replacement: "<hex>"
+	},
+	{
+		regex: "\\$\\d+(?:\\.\\d{2,6})?\\b",
+		replacement: "$<amount>"
+	},
+	{
+		regex: "\\b(?:\\d+\\.\\d+|\\d+)\\s*(?:s|ms|tokens?|tok)\\b",
+		flags: "gi",
+		replacement: "<metric>"
+	}
+];
+const FLAVOR_MASKS = {
+	codex: [{
+		regex: "\\b(?:gpt|o)[A-Za-z0-9._:-]+\\b",
+		flags: "gi",
+		replacement: "<model>"
+	}, {
+		regex: "\\b(?:context|tokens?)\\s*[:=]\\s*[0-9,]+\\b",
+		flags: "gi",
+		replacement: "<token-count>"
+	}],
+	claude: [{
+		regex: "\\bclaude-[A-Za-z0-9._-]+\\b",
+		flags: "gi",
+		replacement: "<model>"
+	}, {
+		regex: "\\b(?:Opus|Sonnet|Haiku)\\s+[0-9.]+\\b",
+		flags: "gi",
+		replacement: "<model>"
+	}],
+	droid: [{
+		regex: "\\bdroidx?-[A-Za-z0-9._-]+\\b",
+		flags: "gi",
+		replacement: "<droid-id>"
+	}],
+	generic: []
+};
+const DEFAULT_VIEWPORTS = [{
+	name: "desktop",
+	width: 1280,
+	height: 820
+}, {
+	name: "mobile",
+	width: 390,
+	height: 844,
+	isMobile: true,
+	hasTouch: true
+}];
+function resolveAgentFlavor(spec) {
+	const explicit = spec.launch.agentFlavor;
+	if (explicit) return explicit;
+	const command = spec.launch.command?.split(/[\\/]/).at(-1)?.toLowerCase() ?? "";
+	if (command === "codex" || command.startsWith("codex-")) return "codex";
+	if (command === "claude" || command === "claude-code" || command.startsWith("claude-")) return "claude";
+	if (command === "droid" || command === "droidx" || command.startsWith("droid")) return "droid";
+	return "generic";
+}
+function getAgentMaskPreset(flavor) {
+	return [...COMMON_AGENT_MASKS, ...FLAVOR_MASKS[flavor]];
+}
+function resolveAgentMasks(spec) {
+	return [...getAgentMaskPreset(resolveAgentFlavor(spec)), ...spec.defaults?.mask ?? []];
+}
+function createAgentTemplateSpec(flavor) {
+	const command = flavor === "droid" ? "droidx" : flavor === "generic" ? "agent" : flavor;
+	const name = flavor === "generic" ? "agent_browser_smoke" : `${flavor}_browser_smoke`;
+	return {
+		name,
+		artifactsDir: `.tmp/agent/${name}`,
+		snapshotDir: `tests/agent-snapshots/${name}`,
+		launch: {
+			mode: "aitty",
+			agentFlavor: flavor,
+			command,
+			args: [],
+			aitty: {
+				project: "ptywright",
+				label: command,
+				title: `${command} browser smoke`,
+				subtitle: "browser-hosted terminal agent regression",
+				theme: "light",
+				fontSize: 14,
+				waitForUrlMs: 15e3
+			}
+		},
+		viewports: DEFAULT_VIEWPORTS.map((viewport) => ({ ...viewport })),
+		defaults: {
+			timeoutMs: 45e3,
+			screenshot: true
+		},
+		steps: [{
+			type: "waitForStableDom",
+			timeoutMs: 45e3,
+			quietMs: 600,
+			intervalMs: 150
+		}, {
+			type: "snapshot",
+			name: "launch",
+			targets: [
+				"terminal",
+				"dom",
+				"screenshot"
+			]
+		}]
+	};
+}
+//#endregion
+//#region src/common/argv.ts
+function formatArgv(argv) {
+	return argv.map(formatArg).join(" ");
+}
+function formatArg(arg) {
+	if (/^[A-Za-z0-9_./:=@+-]+$/.test(arg)) return arg;
+	return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+//#endregion
+//#region src/agent/run_record.ts
+const AGENT_RUN_RECORD_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-run.schema.json";
+const agentRunModeSchema = z.enum(["live", "replay"]);
+const agentRecordedStepSchema = z.object({
+	index: z.number().int().nonnegative(),
+	type: z.string().min(1),
+	label: z.string(),
+	durationMs: z.number().int().nonnegative(),
+	ok: z.boolean(),
+	error: z.string().optional()
+}).strict();
+const agentRunArtifactSchema = z.object({
+	name: z.string().min(1),
+	viewport: z.string().min(1),
+	kind: z.enum([
+		"terminal",
+		"dom",
+		"screenshot"
+	]),
+	path: z.string().min(1),
+	baselinePath: z.string().min(1).optional(),
+	diffPath: z.string().min(1).optional(),
+	hash: z.string().min(1).optional(),
+	ok: z.boolean(),
+	error: z.string().optional()
+}).strict();
+const agentCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const agentRunRecordCommandsSchema = z.object({
+	replay: agentCommandSchema,
+	updateSnapshots: agentCommandSchema
+}).strict();
+const agentRunRecordSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	name: z.string().min(1),
+	ok: z.boolean(),
+	startedAt: z.string().min(1),
+	durationMs: z.number().int().nonnegative(),
+	mode: agentRunModeSchema,
+	spec: agentFlowSpecSchema.optional(),
+	flowPath: z.string().min(1).optional(),
+	artifactsDir: z.string().min(1),
+	snapshotDir: z.string().min(1),
+	reportPath: z.string().min(1),
+	cassettePath: z.string().min(1).optional(),
+	cassetteFrameCount: z.number().int().nonnegative(),
+	replayCommand: z.string().min(1),
+	commands: agentRunRecordCommandsSchema,
+	steps: z.array(agentRecordedStepSchema),
+	artifacts: z.array(agentRunArtifactSchema),
+	errors: z.array(z.string())
+}).strict().superRefine((record, ctx) => {
+	if (!record.cassettePath && !record.flowPath && !record.spec) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "agent run record requires cassettePath, flowPath, or spec"
+	});
+	const replayCommand = formatArgv(record.commands.replay.argv);
+	if (record.replayCommand !== replayCommand) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["replayCommand"],
+		message: "replayCommand must match commands.replay.argv"
+	});
+	if (!isReplayArgv(record.commands.replay.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"replay",
+			"argv"
+		],
+		message: "replay argv must be a ptywright agent replay command"
+	});
+	const expectedUpdateSnapshots = [...record.commands.replay.argv, "--update-snapshots"];
+	if (!sameArgv(record.commands.updateSnapshots.argv, expectedUpdateSnapshots)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"updateSnapshots",
+			"argv"
+		],
+		message: "updateSnapshots argv must extend commands.replay.argv"
+	});
+});
+function normalizeAgentRunRecord(input) {
+	try {
+		const parsed = agentRunRecordSchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-run.schema.json",
+			spec: parsed.spec ? normalizeAgentFlowSpec(parsed.spec) : void 0
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid agent run record: ${formatZodIssues(error)}`);
+		throw error;
+	}
+}
+function formatAgentArgv(argv) {
+	return formatArgv(argv);
+}
+function sameArgv(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function isReplayArgv(argv) {
+	return argv.length >= 4 && argv[0] === "ptywright" && argv[1] === "agent" && argv[2] === "replay";
+}
+function readAgentRunRecordPath(path) {
+	return normalizeAgentRunRecord(JSON.parse(readFileSync(path, "utf8")));
+}
+function writeAgentRunRecordPath(path, record) {
+	const normalized = normalizeAgentRunRecord({
+		...record,
+		$schema: record.$schema ?? "https://ptywright.local/schemas/ptywright-agent-run.schema.json"
+	});
+	writeFileSync(path, JSON.stringify(normalized, null, 2) + "\n", "utf8");
+}
+function isAgentRunRecordLike(input) {
+	if (typeof input !== "object" || input === null) return false;
+	const candidate = input;
+	return candidate.version === 1 && ("cassettePath" in candidate || "flowPath" in candidate || "spec" in candidate);
+}
+function formatZodIssues(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/agent/report.ts
+function writeAgentReport(path, result) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, renderAgentReportHtml(result), "utf8");
+}
+function renderAgentReportHtml(result) {
+	const artifacts = result.artifacts.map((artifact) => renderArtifactRow(artifact, result.artifactsDir, result.reportPath)).join("\n");
+	const viewportTabs = result.viewports.map((viewport) => `<span class="pill">${escapeHtml(viewport.name)} ${viewport.width}x${viewport.height}</span>`).join("");
+	const status = result.ok ? "passed" : "failed";
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(`${result.name} terminal-agent report`)}</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: oklch(97.5% 0.008 210);
+        --ink: oklch(19% 0.018 230);
+        --muted: oklch(48% 0.02 230);
+        --line: oklch(86% 0.018 230);
+        --panel: oklch(99% 0.006 210);
+        --good: oklch(55% 0.15 155);
+        --bad: oklch(58% 0.19 25);
+        --focus: oklch(55% 0.14 235);
+        font-family:
+          ui-sans-serif,
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          "Segoe UI",
+          sans-serif;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        background: var(--bg);
+        color: var(--ink);
+      }
+      main {
+        display: grid;
+        gap: 24px;
+        width: min(1180px, calc(100vw - 32px));
+        margin: 0 auto;
+        padding: 32px 0 48px;
+      }
+      header {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto;
+        gap: 20px;
+        align-items: start;
+        border-bottom: 1px solid var(--line);
+        padding-bottom: 24px;
+      }
+      h1 {
+        margin: 0;
+        font-size: 28px;
+        line-height: 1.15;
+        letter-spacing: 0;
+      }
+      h2 {
+        margin: 0;
+        font-size: 18px;
+        line-height: 1.25;
+      }
+      .meta {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin-top: 12px;
+      }
+      .pill,
+      .status {
+        display: inline-flex;
+        min-height: 32px;
+        align-items: center;
+        border: 1px solid var(--line);
+        border-radius: 999px;
+        padding: 0 12px;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .status {
+        border-color: ${result.ok ? "color-mix(in oklch, var(--good) 42%, var(--line))" : "color-mix(in oklch, var(--bad) 44%, var(--line))"};
+        color: ${result.ok ? "var(--good)" : "var(--bad)"};
+        font-weight: 700;
+      }
+      .panel {
+        display: grid;
+        gap: 16px;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        background: var(--panel);
+        padding: 18px;
+      }
+      .summary {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+        gap: 12px;
+      }
+      .metric {
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 14px;
+        background: color-mix(in oklch, var(--panel) 82%, var(--bg));
+      }
+      .metric strong {
+        display: block;
+        font-size: 24px;
+        line-height: 1.1;
+      }
+      .metric span {
+        display: block;
+        margin-top: 4px;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .artifacts {
+        display: grid;
+        gap: 10px;
+      }
+      .artifact {
+        display: grid;
+        grid-template-columns: 120px minmax(0, 1fr) auto;
+        gap: 14px;
+        align-items: center;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 12px;
+        background: var(--panel);
+      }
+      .artifact a {
+        color: var(--focus);
+        font-weight: 700;
+        text-decoration: none;
+      }
+      .artifact code,
+      pre {
+        font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      }
+      .artifact code {
+        color: var(--muted);
+        overflow-wrap: anywhere;
+      }
+      .badge {
+        justify-self: start;
+        border-radius: 999px;
+        padding: 5px 9px;
+        background: color-mix(in oklch, var(--line) 52%, transparent);
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+      }
+      .badge.fail {
+        background: color-mix(in oklch, var(--bad) 12%, var(--panel));
+        color: var(--bad);
+      }
+      .badge.pass {
+        background: color-mix(in oklch, var(--good) 12%, var(--panel));
+        color: var(--good);
+      }
+      .commands {
+        display: grid;
+        gap: 10px;
+      }
+      .command {
+        display: grid;
+        gap: 5px;
+      }
+      .command span {
+        color: var(--muted);
+        font-size: 13px;
+        font-weight: 700;
+      }
+      pre {
+        overflow: auto;
+        margin: 0;
+        border-radius: 8px;
+        background: oklch(20% 0.015 230);
+        color: oklch(92% 0.012 230);
+        padding: 14px;
+        line-height: 1.5;
+      }
+      @media (max-width: 720px) {
+        main {
+          width: min(100vw - 20px, 1180px);
+          padding-top: 18px;
+        }
+        header,
+        .artifact {
+          grid-template-columns: 1fr;
+        }
+        .status {
+          justify-self: start;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <div>
+          <h1>${escapeHtml(result.name)}</h1>
+          <div class="meta">
+            <span class="status">${status}</span>
+            <span class="pill">${escapeHtml(result.mode)}</span>
+            <span class="pill">${escapeHtml(result.agentFlavor)}</span>
+            ${viewportTabs}
+            <span class="pill">${escapeHtml(new Date(result.startedAt).toISOString())}</span>
+          </div>
+        </div>
+      </header>
+
+      <section class="summary">
+        <div class="metric"><strong>${result.steps.length}</strong><span>Recorded steps</span></div>
+        <div class="metric"><strong>${result.artifacts.length}</strong><span>Snapshot artifacts</span></div>
+        <div class="metric"><strong>${result.cassetteFrameCount}</strong><span>Cassette frames</span></div>
+        <div class="metric"><strong>${result.durationMs}ms</strong><span>Wall time</span></div>
+      </section>
+
+      <section class="panel">
+        <h2>Commands</h2>
+        <div class="commands">
+          ${renderCommandBlock("replay", result.commands.replay.argv)}
+          ${renderCommandBlock("update snapshots", result.commands.updateSnapshots.argv)}
+          ${renderCommandBlock("inspect commands", [
+		"ptywright",
+		"agent",
+		"commands",
+		result.recordPath,
+		"--json"
+	])}
+        </div>
+        <p><code>${escapeHtml(result.replaySourceCassettePath ?? result.cassettePath)}</code></p>
+      </section>
+
+      <section class="panel">
+        <h2>Terminal Agent Artifacts</h2>
+        <div class="artifacts">
+          ${artifacts || "<p>No artifacts were captured.</p>"}
+        </div>
+      </section>
+    </main>
+  </body>
+</html>`;
+}
+function renderCommandBlock(label, argv) {
+	return `<div class="command">
+    <span>${escapeHtml(label)}</span>
+    <pre>${escapeHtml(formatAgentArgv(argv))}</pre>
+  </div>`;
+}
+function renderArtifactRow(artifact, artifactsDir, reportPath) {
+	const state = artifact.ok ? "pass" : "fail";
+	const href = relativeHref(reportPath, artifact.path, artifactsDir);
+	const baselineHref = artifact.baselinePath ? relativeHref(reportPath, artifact.baselinePath, artifactsDir) : "";
+	const diffHref = artifact.diffPath ? relativeHref(reportPath, artifact.diffPath, artifactsDir) : "";
+	return `<article class="artifact">
+    <span class="badge ${state}">${state}</span>
+    <div>
+      ${artifact.kind === "screenshot" && artifact.path ? `<a href="${escapeAttribute(href)}">open image</a>` : `<a href="${escapeAttribute(href)}">${escapeHtml(artifact.kind)}</a>`}
+      <div><code>${escapeHtml(artifact.viewport)} / ${escapeHtml(artifact.name)}</code></div>
+      ${baselineHref ? `<div><code>baseline ${escapeHtml(baselineHref)}</code></div>` : ""}
+      ${diffHref ? `<div><a href="${escapeAttribute(diffHref)}">diff</a></div>` : ""}
+      ${artifact.error ? `<div><code>${escapeHtml(artifact.error)}</code></div>` : ""}
+    </div>
+    <code>${escapeHtml(artifact.hash ?? "")}</code>
+  </article>`;
+}
+function relativeHref(_reportPath, targetPath, artifactsDir) {
+	if (targetPath.startsWith(artifactsDir)) return targetPath.slice(artifactsDir.length).replace(/^\/+/, "");
+	return targetPath;
+}
+function escapeHtml(input) {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeAttribute(input) {
+	return escapeHtml(input).replace(/'/g, "&#39;");
+}
+//#endregion
+//#region src/agent/spec_loader.ts
+async function loadAgentSpec(specPath) {
+	const resolved = resolve(process.cwd(), specPath);
+	if (resolved.endsWith(".json")) return {
+		spec: normalizeAgentFlowSpec(JSON.parse(readFileSync(resolved, "utf8"))),
+		path: resolved
+	};
+	const mod = await import(`${pathToFileURL(resolved).href}?t=${Date.now()}`);
+	return {
+		spec: normalizeAgentFlowSpec(mod.default ?? mod.spec),
+		path: resolved
+	};
+}
+//#endregion
+//#region src/agent/runner.ts
+async function runAgentSpecPath(specPath, options = {}) {
+	return runAgentSpec((await loadAgentSpec(specPath)).spec, options);
+}
+async function replayAgentRecordPath(recordPath, options = {}) {
+	const raw = JSON.parse(readFileSync(recordPath, "utf8"));
+	if (isAgentCassetteLike(raw)) return replayAgentCassette(normalizeAgentCassette(raw), recordPath, options);
+	const record = readAgentRunRecordPath(recordPath);
+	if (record.cassettePath) {
+		const cassettePath = isAbsolute(record.cassettePath) ? record.cassettePath : resolve(dirname(recordPath), record.cassettePath);
+		return replayAgentCassette(readAgentCassettePath(cassettePath, record.spec), cassettePath, {
+			...options,
+			artifactsDir: options.artifactsDir ?? join(dirname(recordPath), "replay")
+		});
+	}
+	if (record.spec) return runAgentSpec(record.spec, options);
+	if (!record.flowPath) throw new Error(`invalid agent run record: missing replay source in ${recordPath}`);
+	return runAgentSpecPath(isAbsolute(record.flowPath) ? record.flowPath : resolve(dirname(recordPath), record.flowPath), options);
+}
+async function runAgentSpec(input, options = {}) {
+	const startedAt = Date.now();
+	const rootDir = options.rootDir ? resolve(process.cwd(), options.rootDir) : process.cwd();
+	const spec = normalizeAgentFlowSpec(input);
+	const name = sanitizeArtifactName(spec.name ?? "agent-flow");
+	const artifactsDir = resolve(rootDir, options.artifactsDir ?? spec.artifactsDir ?? join(".tmp", "agent", name));
+	const snapshotDir = resolve(rootDir, spec.snapshotDir ?? join("snapshots", name));
+	const reportPath = join(artifactsDir, "index.html");
+	const recordPath = join(artifactsDir, `${name}.agent-run.json`);
+	const flowPath = join(artifactsDir, `${name}.flow.json`);
+	const cassettePath = join(artifactsDir, `${name}.cassette.json`);
+	const updateSnapshots = options.updateSnapshots ?? envTruthy(process.env.UPDATE_SNAPSHOTS);
+	const cassette = options.replayCassette ?? createAgentCassette(name, spec);
+	mkdirSync(artifactsDir, { recursive: true });
+	mkdirSync(snapshotDir, { recursive: true });
+	const replayArgv = [
+		"ptywright",
+		"agent",
+		"replay",
+		relative(process.cwd(), recordPath)
+	];
+	const result = {
+		ok: true,
+		name,
+		mode: options.replayCassette ? "replay" : "live",
+		startedAt,
+		durationMs: 0,
+		artifactsDir,
+		snapshotDir,
+		reportPath,
+		recordPath,
+		flowPath,
+		cassettePath,
+		replaySourceCassettePath: options.replaySourceCassettePath,
+		replayCommand: formatAgentArgv(replayArgv),
+		commands: {
+			replay: { argv: replayArgv },
+			updateSnapshots: { argv: [...replayArgv, "--update-snapshots"] }
+		},
+		agentFlavor: resolveAgentFlavor(spec),
+		viewports: spec.viewports ?? [],
+		cassetteFrameCount: cassette.frames.length,
+		steps: [],
+		artifacts: [],
+		errors: []
+	};
+	writeFileSync(flowPath, JSON.stringify(spec, null, 2) + "\n", "utf8");
+	let browser = null;
+	try {
+		browser = await launchAgentBrowser({ headless: options.headless ?? true });
+		for (const viewport of spec.viewports ?? []) await runViewport({
+			browser,
+			spec,
+			viewport,
+			rootDir,
+			artifactsDir,
+			snapshotDir,
+			updateSnapshots,
+			recordCassette: !options.replayCassette,
+			cassette,
+			result
+		});
+	} catch (error) {
+		result.ok = false;
+		result.errors.push(error instanceof Error ? error.message : String(error));
+	} finally {
+		await closeBrowserSafely(browser);
+		result.durationMs = Date.now() - startedAt;
+		if (options.replaySourceCassettePath) writeFileSync(cassettePath, readFileSync(options.replaySourceCassettePath, "utf8"), "utf8");
+		else writeFileSync(cassettePath, JSON.stringify(cassette, null, 2) + "\n", "utf8");
+		result.cassetteFrameCount = cassette.frames.length;
+		writeRunRecord(result, spec);
+		writeAgentReport(reportPath, result);
+		writeRunManifest(result);
+	}
+	return result;
+}
+async function runViewport(args) {
+	const { browser, spec, viewport, rootDir, artifactsDir, snapshotDir, updateSnapshots, recordCassette, cassette, result } = args;
+	const launchMode = spec.launch.mode ?? (spec.launch.url ? "url" : "aitty");
+	const session = launchMode === "aitty" ? await launchAittyBrowserSession(spec.launch, { rootDir }) : null;
+	const url = launchMode === "url" ? spec.launch.url : session.url;
+	const context = await browser.newContext({
+		viewport: {
+			width: viewport.width,
+			height: viewport.height
+		},
+		deviceScaleFactor: viewport.deviceScaleFactor,
+		isMobile: viewport.isMobile,
+		hasTouch: viewport.hasTouch
+	});
+	const page = await context.newPage();
+	const ctx = {
+		spec,
+		viewport,
+		page,
+		artifactsDir,
+		snapshotDir,
+		updateSnapshots,
+		recordCassette,
+		masks: resolveAgentMasks(spec),
+		artifacts: result.artifacts,
+		replay: Boolean(args.cassette && !args.recordCassette),
+		cassette,
+		nextReplayPhase: 0
+	};
+	try {
+		await page.goto(url, {
+			waitUntil: "domcontentloaded",
+			timeout: spec.defaults?.timeoutMs ?? 3e4
+		});
+		await waitForTerminalRoot(page, spec.defaults?.timeoutMs ?? 3e4);
+		await captureCassetteFrame(ctx, {
+			stepIndex: null,
+			stepType: "initial"
+		});
+		for (let i = 0; i < spec.steps.length; i += 1) {
+			const step = spec.steps[i];
+			const started = Date.now();
+			try {
+				await runStep(ctx, step);
+				result.steps.push({
+					index: i,
+					type: step.type,
+					label: formatStepLabel(step),
+					durationMs: Date.now() - started,
+					ok: true
+				});
+				await captureCassetteFrame(ctx, {
+					stepIndex: i,
+					stepType: step.type
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				result.ok = false;
+				result.errors.push(`${viewport.name} step ${i + 1} ${step.type}: ${message}`);
+				result.steps.push({
+					index: i,
+					type: step.type,
+					label: formatStepLabel(step),
+					durationMs: Date.now() - started,
+					ok: false,
+					error: message
+				});
+				break;
+			}
+		}
+	} finally {
+		await withTimeout(context.close().catch(() => void 0), 5e3);
+		await session?.close();
+	}
+}
+async function replayAgentCassette(cassette, cassettePath, options) {
+	const server = await startAgentCassetteServer(cassette);
+	try {
+		const replaySpec = structuredClone(cassette.spec);
+		const replayCassette = structuredClone(cassette);
+		return await runAgentSpec({
+			...replaySpec,
+			launch: {
+				mode: "url",
+				url: server.url,
+				agentFlavor: replaySpec.launch.agentFlavor
+			}
+		}, {
+			...options,
+			artifactsDir: options.artifactsDir ?? join(dirname(cassettePath), "replay"),
+			replayCassette,
+			replaySourceCassettePath: cassettePath
+		});
+	} finally {
+		await server.close();
+	}
+}
+async function closeBrowserSafely(browser) {
+	if (!browser) return;
+	await withTimeout(browser.close().catch(() => void 0), 5e3);
+}
+async function withTimeout(promise, timeoutMs) {
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((resolveTimeout) => {
+			timer = setTimeout(resolveTimeout, timeoutMs);
+		})]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+async function runStep(ctx, step) {
+	const timeout = ctx.spec.defaults?.timeoutMs ?? 3e4;
+	if (step.type === "waitForText") {
+		await waitForTerminalText(ctx.page, {
+			text: step.text,
+			regex: step.regex,
+			timeoutMs: step.timeoutMs ?? timeout
+		});
+		return;
+	}
+	if (step.type === "typeText") {
+		await advanceReplayPhase(ctx);
+		if (!ctx.replay) {
+			await ctx.page.locator("[data-terminal-root]").first().click({ timeout });
+			await ctx.page.keyboard.type(step.text, { delay: step.delayMs });
+			if (step.enter) await ctx.page.keyboard.press("Enter");
+		}
+		return;
+	}
+	if (step.type === "pressKey") {
+		await advanceReplayPhase(ctx);
+		if (!ctx.replay) await ctx.page.keyboard.press(step.key);
+		return;
+	}
+	if (step.type === "click") {
+		await advanceReplayPhase(ctx);
+		if (ctx.replay) return;
+		if (step.selector) {
+			await ctx.page.locator(step.selector).first().click({ timeout });
+			return;
+		}
+		if (step.text) {
+			await ctx.page.getByText(step.text, { exact: false }).first().click({ timeout });
+			return;
+		}
+		await ctx.page.mouse.click(step.x, step.y);
+		return;
+	}
+	if (step.type === "waitForStableDom") {
+		await waitForStableDom(ctx.page, {
+			timeoutMs: step.timeoutMs ?? timeout,
+			quietMs: step.quietMs ?? 350,
+			intervalMs: step.intervalMs ?? 100
+		});
+		return;
+	}
+	if (step.type === "snapshot") {
+		await captureSnapshotStep(ctx, step);
+		return;
+	}
+	if (step.type === "sleep") {
+		if (!ctx.replay) await new Promise((resolveSleep) => setTimeout(resolveSleep, step.ms));
+		return;
+	}
+	if (step.type === "mark") return;
+}
+async function captureCassetteFrame(ctx, frame) {
+	if (!ctx.cassette || !ctx.recordCassette) return;
+	const phase = ctx.nextReplayPhase;
+	upsertAgentCassetteFrame(ctx.cassette, {
+		viewport: ctx.viewport,
+		phase,
+		stepIndex: frame.stepIndex,
+		stepType: frame.stepType,
+		terminalText: normalizeTerminalText(await readTerminalText(ctx.page), ctx.masks),
+		dom: normalizeDomSnapshot(await readTerminalDom(ctx.page), ctx.masks),
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+async function advanceReplayPhase(ctx) {
+	if (!ctx.replay) {
+		ctx.nextReplayPhase += 1;
+		return;
+	}
+	ctx.nextReplayPhase += 1;
+	await ctx.page.evaluate((phase) => {
+		window.__ptywrightReplaySetPhase?.(phase);
+	}, ctx.nextReplayPhase);
+}
+async function captureSnapshotStep(ctx, step) {
+	const targets = step.targets ?? [
+		"terminal",
+		"dom",
+		...ctx.spec.defaults?.screenshot ? ["screenshot"] : []
+	];
+	const base = `${sanitizeArtifactName(ctx.viewport.name)}.${sanitizeArtifactName(step.name)}`;
+	for (const target of targets) {
+		if (target === "terminal") {
+			const text = normalizeTerminalText(await readTerminalText(ctx.page), ctx.masks);
+			await writeComparableArtifact(ctx, {
+				name: step.name,
+				kind: "terminal",
+				relativePath: `${base}.terminal.txt`,
+				baselineRelativePath: `${base}.terminal.snap.txt`,
+				diffRelativePath: `${base}.terminal.diff.txt`,
+				content: text + "\n",
+				compare: step.compare ?? true
+			});
+			continue;
+		}
+		if (target === "dom") {
+			const dom = normalizeDomSnapshot(await readTerminalDom(ctx.page), ctx.masks);
+			await writeComparableArtifact(ctx, {
+				name: step.name,
+				kind: "dom",
+				relativePath: `${base}.dom.html`,
+				baselineRelativePath: `${base}.dom.snap.html`,
+				diffRelativePath: `${base}.dom.diff.txt`,
+				content: dom + "\n",
+				compare: step.compare ?? true
+			});
+			continue;
+		}
+		const screenshotPath = join(ctx.artifactsDir, `${base}.png`);
+		await ctx.page.screenshot({
+			path: screenshotPath,
+			fullPage: step.fullPage ?? false
+		});
+		ctx.artifacts.push({
+			name: step.name,
+			viewport: ctx.viewport.name,
+			kind: "screenshot",
+			path: screenshotPath,
+			ok: true
+		});
+	}
+}
+async function writeComparableArtifact(ctx, artifact) {
+	const artifactPath = join(ctx.artifactsDir, artifact.relativePath);
+	const baselinePath = join(ctx.snapshotDir, artifact.baselineRelativePath);
+	const diffPath = join(ctx.artifactsDir, artifact.diffRelativePath);
+	const hash = shortHash(artifact.content);
+	writeFileSync(artifactPath, artifact.content, "utf8");
+	if (!artifact.compare) {
+		ctx.artifacts.push({
+			name: artifact.name,
+			viewport: ctx.viewport.name,
+			kind: artifact.kind,
+			path: artifactPath,
+			baselinePath,
+			hash,
+			ok: true
+		});
+		return;
+	}
+	if (ctx.updateSnapshots) {
+		mkdirSync(dirname(baselinePath), { recursive: true });
+		writeFileSync(baselinePath, artifact.content, "utf8");
+		ctx.artifacts.push({
+			name: artifact.name,
+			viewport: ctx.viewport.name,
+			kind: artifact.kind,
+			path: artifactPath,
+			baselinePath,
+			hash,
+			ok: true
+		});
+		return;
+	}
+	let baseline = null;
+	try {
+		baseline = readFileSync(baselinePath, "utf8");
+	} catch {
+		const message = `missing snapshot ${baselinePath}; rerun with --update-snapshots`;
+		ctx.artifacts.push({
+			name: artifact.name,
+			viewport: ctx.viewport.name,
+			kind: artifact.kind,
+			path: artifactPath,
+			baselinePath,
+			hash,
+			ok: false,
+			error: message
+		});
+		throw new Error(message);
+	}
+	if (baseline !== artifact.content) {
+		const message = `snapshot mismatch ${baselinePath}; rerun with --update-snapshots if intentional`;
+		writeFileSync(diffPath, renderSnapshotDiff(baseline, artifact.content), "utf8");
+		ctx.artifacts.push({
+			name: artifact.name,
+			viewport: ctx.viewport.name,
+			kind: artifact.kind,
+			path: artifactPath,
+			baselinePath,
+			diffPath,
+			hash,
+			ok: false,
+			error: message
+		});
+		throw new Error(message);
+	}
+	ctx.artifacts.push({
+		name: artifact.name,
+		viewport: ctx.viewport.name,
+		kind: artifact.kind,
+		path: artifactPath,
+		baselinePath,
+		hash,
+		ok: true
+	});
+}
+function renderSnapshotDiff(expected, received) {
+	const expectedLines = expected.split("\n");
+	const receivedLines = received.split("\n");
+	const max = Math.max(expectedLines.length, receivedLines.length);
+	const out = ["--- expected", "+++ received"];
+	for (let i = 0; i < max; i += 1) {
+		const before = expectedLines[i];
+		const after = receivedLines[i];
+		if (before === after) {
+			if (before !== void 0) out.push(`  ${before}`);
+			continue;
+		}
+		if (before !== void 0) out.push(`- ${before}`);
+		if (after !== void 0) out.push(`+ ${after}`);
+	}
+	return out.join("\n") + "\n";
+}
+async function waitForTerminalRoot(page, timeoutMs) {
+	await page.locator("[data-terminal-root]").first().waitFor({
+		state: "attached",
+		timeout: timeoutMs
+	});
+}
+async function waitForTerminalText(page, args) {
+	const started = Date.now();
+	const matcher = args.regex ? new RegExp(args.regex) : null;
+	while (Date.now() - started < args.timeoutMs) {
+		const text = await readTerminalText(page);
+		if (args.text && text.includes(args.text)) return;
+		if (matcher?.test(text)) return;
+		await new Promise((resolvePoll) => setTimeout(resolvePoll, 100));
+	}
+	throw new Error(`timed out waiting for terminal text ${args.text ?? args.regex ?? ""}`);
+}
+async function waitForStableDom(page, args) {
+	const started = Date.now();
+	let last = "";
+	let stableSince = Date.now();
+	while (Date.now() - started < args.timeoutMs) {
+		const current = await readTerminalDomIfPresent(page);
+		if (current === null) {
+			await new Promise((resolvePoll) => setTimeout(resolvePoll, args.intervalMs));
+			continue;
+		}
+		if (current !== last) {
+			last = current;
+			stableSince = Date.now();
+		} else if (Date.now() - stableSince >= args.quietMs) return;
+		await new Promise((resolvePoll) => setTimeout(resolvePoll, args.intervalMs));
+	}
+	throw new Error(`timed out waiting for stable terminal DOM`);
+}
+async function readTerminalText(page) {
+	const text = await page.evaluate(() => {
+		const node = document.querySelector("[data-terminal-root]");
+		if (!node) return null;
+		const rows = Array.from(node.querySelectorAll(".term-grid .term-row"));
+		if (rows.length > 0) return rows.map((row) => row.textContent ?? "").join("\n");
+		return node.textContent ?? "";
+	});
+	if (text === null) throw new Error("terminal root is not attached");
+	return text;
+}
+async function readTerminalDom(page) {
+	const dom = await readTerminalDomIfPresent(page);
+	if (dom === null) throw new Error("terminal root is not attached");
+	return dom;
+}
+async function readTerminalDomIfPresent(page) {
+	return page.evaluate(() => document.querySelector("[data-terminal-root]")?.innerHTML ?? null);
+}
+function writeRunRecord(result, spec) {
+	const record = {
+		$schema: AGENT_RUN_RECORD_SCHEMA_URL,
+		version: 1,
+		name: result.name,
+		ok: result.ok,
+		startedAt: new Date(result.startedAt).toISOString(),
+		durationMs: result.durationMs,
+		mode: result.mode,
+		spec,
+		flowPath: relative(dirname(result.recordPath), result.flowPath),
+		artifactsDir: result.artifactsDir,
+		snapshotDir: result.snapshotDir,
+		reportPath: result.reportPath,
+		cassettePath: relative(dirname(result.recordPath), result.cassettePath),
+		cassetteFrameCount: result.cassetteFrameCount,
+		replayCommand: result.replayCommand,
+		commands: result.commands,
+		steps: result.steps,
+		artifacts: result.artifacts,
+		errors: result.errors
+	};
+	writeAgentRunRecordPath(result.recordPath, record);
+}
+function writeRunManifest(result) {
+	writeAgentManifestPath(agentManifestPath(result.artifactsDir), {
+		kind: "run",
+		ok: result.ok,
+		rootDir: result.artifactsDir,
+		primaryPath: result.recordPath,
+		commands: result.commands,
+		validation: {
+			ok: result.ok,
+			stages: [{
+				name: "run",
+				ok: result.ok,
+				totalCount: result.artifacts.length,
+				failureCount: result.artifacts.filter((artifact) => !artifact.ok).length
+			}]
+		},
+		files: [
+			{
+				path: result.flowPath,
+				kind: "flow",
+				role: "flow"
+			},
+			{
+				path: result.cassettePath,
+				kind: "cassette",
+				role: "cassette"
+			},
+			{
+				path: result.recordPath,
+				kind: "run-record",
+				role: "record",
+				ok: result.ok
+			},
+			{
+				path: result.reportPath,
+				kind: "report",
+				role: "report",
+				ok: result.ok
+			},
+			...result.artifacts.flatMap((artifact) => [{
+				path: artifact.path,
+				kind: artifact.kind,
+				role: "artifact",
+				ok: artifact.ok
+			}, {
+				path: artifact.diffPath,
+				kind: "diff",
+				role: "diff",
+				ok: artifact.ok
+			}])
+		]
+	});
+}
+function formatStepLabel(step) {
+	if (step.type === "snapshot") return `snapshot ${step.name}`;
+	if (step.type === "waitForText") return `wait ${step.text ?? step.regex ?? ""}`;
+	if (step.type === "typeText") return `type ${step.text.slice(0, 24)}`;
+	if (step.type === "pressKey") return `press ${step.key}`;
+	if (step.type === "click") return `click ${step.selector ?? step.text ?? `${step.x},${step.y}`}`;
+	if (step.type === "mark") return `mark ${step.label ?? ""}`;
+	if (step.type === "sleep") return `sleep ${step.ms}ms`;
+	return step.type;
+}
+function envTruthy(value) {
+	return value === "1" || value === "true" || value === "yes";
+}
+function printAittyLaunchPlan(input) {
+	const spec = normalizeAgentFlowSpec(input);
+	if ((spec.launch.mode ?? "aitty") !== "aitty") return "launch.mode=url";
+	const command = buildAittyExecCommand(spec.launch);
+	return [command.file, ...command.args].join(" ");
+}
+function defaultSpecNameForPath(path) {
+	return sanitizeArtifactName(basename(path, extname(path)));
+}
+//#endregion
+export { isAgentManifestLike as C, writeAgentManifestPath as E, agentManifestPath as S, validateAgentManifestFiles as T, normalizeAgentFlowSpec as _, runAgentSpecPath as a, launchAittyBrowserSession as b, agentRunModeSchema as c, readAgentRunRecordPath as d, writeAgentRunRecordPath as f, readAgentCassettePath as g, isAgentCassetteLike as h, runAgentSpec as i, formatAgentArgv as l, createAgentTemplateSpec as m, printAittyLaunchPlan as n, loadAgentSpec as o, formatArgv as p, replayAgentRecordPath as r, AGENT_RUN_RECORD_SCHEMA_URL as s, defaultSpecNameForPath as t, isAgentRunRecordLike as u, sanitizeArtifactName as v, readAgentManifestPath as w, AGENT_MANIFEST_FILE_NAME as x, launchAgentBrowser as y };