ptywright 0.2.0 → 0.3.0

package/README.md

@@ -107,7 +107,7 @@ bunx ptywright@latest pty validate tests/cassettes/codex.pty.json
 bunx ptywright@latest pty inspect tests/cassettes/codex.pty.json
 ```
 
-External projects do not need to depend on aitty. Use the structural
+External projects do not need a ptywright-specific PTY wrapper. Use the structural
 `wrapPtyLike` API for `node-pty`/`bun-pty` style objects:
 
 ```ts
@@ -308,9 +308,10 @@ Recording artifacts are best for failure diagnosis or manual review; prefer `sna
 
 ## Browser Agent Regression
 
-The new destructive path is browser-first: ptywright can launch an agent through
-`@aitty/cli`, drive the browser-hosted wterm DOM with Playwright, and persist a
-replayable run artifact plus terminal/DOM snapshots.
+The browser-first path is integration-agnostic: ptywright launches any command
+that prints a browser URL, drives the terminal DOM with Playwright, and persists
+a replayable run artifact plus terminal/DOM snapshots. The browser page must
+expose the terminal root as `[data-terminal-root]`.
 
 ```bash
 # First run records snapshots, screenshots, replay metadata, and report.
@@ -379,9 +380,39 @@ Artifacts are split intentionally:
 - `tests/agent-snapshots/<name>/` contains stable terminal/DOM baselines.
 - `--update-snapshots` is the explicit update path for intentional UI changes.
 
-`launch.mode=aitty` runs `aitty exec --launch print -- <agent>`. By default
-ptywright resolves the sibling `../aitty/packages/cli/dist/cli.js`; set
-`PTYWRIGHT_AITTY_CLI` or `launch.aitty.command` to override it.
+`launch.mode=command` is the recommended integration contract. `command` and
+`args` are spawned directly, and ptywright reads the first URL printed to stdout
+or stderr. Use `waitForUrlMs` to tune startup timeouts and `urlRegex` when the
+URL is embedded in structured output. Set `launch.agentFlavor` explicitly when
+the command is a wrapper, so mask presets still match the underlying agent.
+
+`launch.mode=url` skips process launch and points ptywright at an already
+running browser terminal.
+
+A wrapper integration is just a normal command that prints its browser URL:
+
+```json
+{
+  "name": "codex_browser_replay",
+  "launch": {
+    "mode": "command",
+    "agentFlavor": "codex",
+    "command": "node_modules/.bin/browser-terminal-launcher",
+    "args": [
+      "--replay",
+      "test/recordings/codex-yolo.pty.json",
+      "--speed",
+      "0",
+      "--print-url"
+    ],
+    "waitForUrlMs": 15000
+  },
+  "steps": [
+    { "type": "waitForStableDom" },
+    { "type": "snapshot", "name": "codex", "targets": ["terminal", "dom"] }
+  ]
+}
+```
 
 Set `launch.agentFlavor` to `codex`, `claude`, `droid`, or `generic` to opt
 into built-in mask presets for timestamps, generated ids, model names, token

package/dist/agent.mjs

@@ -1,2 +1,2 @@
-import { a as runAgentSpecPath, i as runAgentSpec, n as printAittyLaunchPlan, r as replayAgentRecordPath, t as defaultSpecNameForPath } from "./runner-DzZlFrt1.mjs";
-export { defaultSpecNameForPath, printAittyLaunchPlan, replayAgentRecordPath, runAgentSpec, runAgentSpecPath };
+import { a as runAgentSpecPath, i as runAgentSpec, n as printAgentLaunchPlan, r as replayAgentRecordPath, t as defaultSpecNameForPath } from "./runner-zi0nItvB.mjs";
+export { defaultSpecNameForPath, printAgentLaunchPlan, replayAgentRecordPath, runAgentSpec, runAgentSpecPath };

package/dist/bin/ptywright.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { t as main } from "../cli-DIUx2w6X.mjs";
+import { t as main } from "../cli-CfvlbRoZ.mjs";
 //#region src/bin/ptywright.ts
 await main();
 //#endregion

package/dist/{cli-DIUx2w6X.mjs → cli-CfvlbRoZ.mjs}

@@ -1,6 +1,6 @@
 import { c as createDefaultPtyAdapter, l as resolvePtyBackend } from "./runner-zApMYWZx.mjs";
-import { a as readScriptManifestPath, c as resolveScriptManifestPath, d as resolveScriptRunSummaryPath, f as runScriptPath, i as findScriptSummaryManifest, l as validateScriptManifest, n as runAllScripts, o as relocateScriptManifestCommands, s as resolveManifestPrimaryPath$1, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-VHuEWWj_.mjs";
-import { C as isAgentManifestLike, E as writeAgentManifestPath, S as agentManifestPath, T as validateAgentManifestFiles, _ as normalizeAgentFlowSpec, a as runAgentSpecPath, b as launchAittyBrowserSession, c as agentRunModeSchema, d as readAgentRunRecordPath, f as writeAgentRunRecordPath, g as readAgentCassettePath, h as isAgentCassetteLike, l as formatAgentArgv, m as createAgentTemplateSpec, o as loadAgentSpec, p as formatArgv, r as replayAgentRecordPath, s as AGENT_RUN_RECORD_SCHEMA_URL, u as isAgentRunRecordLike, v as sanitizeArtifactName, w as readAgentManifestPath, x as AGENT_MANIFEST_FILE_NAME, y as launchAgentBrowser } from "./runner-DzZlFrt1.mjs";
+import { a as readScriptManifestPath, c as resolveScriptManifestPath, d as resolveScriptRunSummaryPath, f as runScriptPath, i as findScriptSummaryManifest, l as validateScriptManifest, n as runAllScripts, o as relocateScriptManifestCommands, s as resolveManifestPrimaryPath$1, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-BC3yo-dq.mjs";
+import { C as isAgentManifestLike, E as writeAgentManifestPath, S as agentManifestPath, T as validateAgentManifestFiles, _ as readAgentCassettePath, a as runAgentSpecPath, b as launchAgentBrowser, c as agentRunModeSchema, d as readAgentRunRecordPath, f as writeAgentRunRecordPath, g as isAgentCassetteLike, h as resolveAgentLaunchTarget, l as formatAgentArgv, m as createAgentTemplateSpec, o as loadAgentSpec, p as formatArgv, r as replayAgentRecordPath, s as AGENT_RUN_RECORD_SCHEMA_URL, u as isAgentRunRecordLike, v as normalizeAgentFlowSpec, w as readAgentManifestPath, x as AGENT_MANIFEST_FILE_NAME, y as sanitizeArtifactName } from "./runner-zi0nItvB.mjs";
 import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-Cpkh_O9B.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -2135,13 +2135,11 @@ async function recordAgentSpecPath(specPath, options) {
 async function recordAgentSpec(input, options) {
 	const spec = normalizeAgentFlowSpec(input);
 	const rootDir = options.rootDir ? resolve(process.cwd(), options.rootDir) : process.cwd();
-	const launchMode = spec.launch.mode ?? (spec.launch.url ? "url" : "aitty");
 	const outPath = isAbsolute(options.outPath) ? options.outPath : resolve(process.cwd(), options.outPath);
 	const durationMs = options.durationMs ?? 3e4;
 	const steps = [];
 	let browser = null;
-	const session = launchMode === "aitty" ? await launchAittyBrowserSession(spec.launch, { rootDir }) : null;
-	const url = launchMode === "url" ? spec.launch.url : session.url;
+	const launchTarget = await resolveAgentLaunchTarget(spec.launch, { rootDir });
 	try {
 		browser = await launchAgentBrowser({ headless: options.headless ?? false });
 		const viewport = spec.viewports?.[0] ?? {
@@ -2160,7 +2158,7 @@ async function recordAgentSpec(input, options) {
 		});
 		const page = await context.newPage();
 		await installRecorderHooks(page);
-		await page.goto(url, {
+		await page.goto(launchTarget.url, {
 			waitUntil: "domcontentloaded",
 			timeout: spec.defaults?.timeoutMs ?? 3e4
 		});
@@ -2198,19 +2196,19 @@ async function recordAgentSpec(input, options) {
 			ok: true,
 			outPath,
 			stepCount: recorded.steps.length,
-			url
+			url: launchTarget.url
 		};
 	} catch (error) {
 		return {
 			ok: false,
 			outPath,
 			stepCount: steps.length,
-			url,
+			url: launchTarget.url,
 			error: error instanceof Error ? error.message : String(error)
 		};
 	} finally {
 		await browser?.close();
-		await session?.close();
+		await launchTarget.session?.close();
 	}
 }
 async function installRecorderHooks(page) {

package/dist/cli.mjs

@@ -1,2 +1,2 @@
-import { t as main } from "./cli-DIUx2w6X.mjs";
+import { t as main } from "./cli-CfvlbRoZ.mjs";
 export { main };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as createPtywrightServer } from "./server-VHuEWWj_.mjs";
+import { t as createPtywrightServer } from "./server-BC3yo-dq.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 //#region src/index.ts
 const { server, sessions } = createPtywrightServer();

package/dist/mcp.mjs

@@ -1,2 +1,2 @@
-import { t as createPtywrightServer } from "./server-VHuEWWj_.mjs";
+import { t as createPtywrightServer } from "./server-BC3yo-dq.mjs";
 export { createPtywrightServer };

package/dist/{runner-DzZlFrt1.mjs → runner-zi0nItvB.mjs}

@@ -1,11 +1,11 @@
 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 { 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";
+import { spawn } from "node:child_process";
 //#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";
@@ -171,134 +171,6 @@ function formatZodIssues$1(error) {
 	}).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;
@@ -391,8 +263,14 @@ const agentViewportSchema = z.object({
 	isMobile: z.boolean().optional(),
 	hasTouch: z.boolean().optional()
 });
+const agentLaunchModeSchema = z.enum(["command", "url"]);
+function inferAgentLaunchMode(value) {
+	if (value.mode) return value.mode;
+	if (value.url) return "url";
+	return "command";
+}
 const agentLaunchSchema = z.object({
-	mode: z.enum(["aitty", "url"]).optional(),
+	mode: agentLaunchModeSchema.optional(),
 	agentFlavor: z.enum([
 		"codex",
 		"claude",
@@ -404,33 +282,17 @@ const agentLaunchSchema = z.object({
 	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");
+	urlRegex: z.string().min(1).optional(),
+	waitForUrlMs: z.number().int().positive().optional()
+}).strict().superRefine((value, ctx) => {
+	const mode = inferAgentLaunchMode(value);
 	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({
+	if (mode === "command" && !value.command) ctx.addIssue({
 		code: z.ZodIssueCode.custom,
-		message: "launch.command is required when launch.mode is 'aitty'"
+		message: "launch.command is required when launch.mode is 'command'"
 	});
 });
 const waitForTextStepSchema = z.object({
@@ -528,6 +390,9 @@ function normalizeAgentFlowSpec(input) {
 		viewports: spec.viewports?.length ? spec.viewports : [...DEFAULT_AGENT_VIEWPORTS]
 	};
 }
+function resolveAgentLaunchMode(launch) {
+	return inferAgentLaunchMode(launch);
+}
 //#endregion
 //#region src/agent/cassette.ts
 const AGENT_CASSETTE_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-cassette.schema.json";
@@ -759,6 +624,127 @@ function escapeHtml$1(input) {
 	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 //#endregion
+//#region src/agent/command_launch.ts
+const DEFAULT_URL_REGEX = /https?:\/\/[^\s"'<>]+/;
+function buildCommandLaunchCommand(launch, options = {}) {
+	if (!launch.command) throw new Error("launch.command is required when launch.mode is 'command'");
+	const rootDir = options.rootDir ?? process.cwd();
+	const cwd = launch.cwd ? resolve(rootDir, launch.cwd) : rootDir;
+	return {
+		file: launch.command,
+		args: launch.args ?? [],
+		cwd,
+		env: {
+			...options.env ?? process.env,
+			...launch.env
+		},
+		label: launch.command,
+		urlRegex: launch.urlRegex,
+		waitForUrlMs: launch.waitForUrlMs
+	};
+}
+async function launchBrowserSessionFromCommand(command) {
+	const timeoutMs = command.waitForUrlMs ?? 15e3;
+	const child = spawn(command.file, command.args, {
+		cwd: command.cwd,
+		env: command.env,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	const stdoutChunks = [];
+	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 ${command.label ?? command.file} session URL\nstdout=${stdoutChunks.join("").trim()}\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 readUrl = () => {
+				const found = extractUrlFromOutput(`${stdoutChunks.join("")}\n${stderrChunks.join("")}`, command.urlRegex);
+				if (found) finish(found);
+			};
+			const onStdout = (chunk) => {
+				stdoutChunks.push(chunk.toString("utf8"));
+				readUrl();
+			};
+			const onStderr = (chunk) => {
+				stderrChunks.push(chunk.toString("utf8"));
+				readUrl();
+			};
+			const onError = (error) => finish(error);
+			const onExit = (code, signal) => {
+				finish(/* @__PURE__ */ new Error(`${command.label ?? command.file} exited before printing a session URL (code=${code ?? "null"} signal=${signal ?? "null"})\nstdout=${stdoutChunks.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 extractUrlFromOutput(output, regexSource) {
+	if (!regexSource) return output.match(DEFAULT_URL_REGEX)?.[0] ?? null;
+	const match = output.match(new RegExp(regexSource, "m"));
+	return match?.[1] ?? match?.[0] ?? null;
+}
+function formatBrowserLaunchCommand(command) {
+	return [command.file, ...command.args].join(" ");
+}
+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/launch.ts
+function buildAgentLaunchCommand(launch, options = {}) {
+	if (resolveAgentLaunchMode(launch) === "url") return null;
+	return buildCommandLaunchCommand(launch, options);
+}
+async function resolveAgentLaunchTarget(launch, options = {}) {
+	const mode = resolveAgentLaunchMode(launch);
+	if (mode === "url") return {
+		mode,
+		url: launch.url,
+		session: null
+	};
+	const session = await launchBrowserSessionFromCommand(buildCommandLaunchCommand(launch, options));
+	return {
+		mode,
+		url: session.url,
+		session
+	};
+}
+function formatAgentLaunchCommand(launch) {
+	const command = buildAgentLaunchCommand(launch);
+	return command ? formatBrowserLaunchCommand(command) : "launch.mode=url";
+}
+//#endregion
 //#region src/agent/presets.ts
 const COMMON_AGENT_MASKS = [
 	{
@@ -849,19 +835,15 @@ function createAgentTemplateSpec(flavor) {
 		artifactsDir: `.tmp/agent/${name}`,
 		snapshotDir: `tests/agent-snapshots/${name}`,
 		launch: {
-			mode: "aitty",
+			mode: "command",
 			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
-			}
+			command: "your-browser-terminal-launcher",
+			args: [
+				"--agent",
+				command,
+				"--print-url"
+			],
+			waitForUrlMs: 15e3
 		},
 		viewports: DEFAULT_VIEWPORTS.map((viewport) => ({ ...viewport })),
 		defaults: {
@@ -1412,9 +1394,7 @@ async function runAgentSpec(input, options = {}) {
 }
 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 launchTarget = await resolveAgentLaunchTarget(spec.launch, { rootDir });
 	const context = await browser.newContext({
 		viewport: {
 			width: viewport.width,
@@ -1440,7 +1420,7 @@ async function runViewport(args) {
 		nextReplayPhase: 0
 	};
 	try {
-		await page.goto(url, {
+		await page.goto(launchTarget.url, {
 			waitUntil: "domcontentloaded",
 			timeout: spec.defaults?.timeoutMs ?? 3e4
 		});
@@ -1482,7 +1462,7 @@ async function runViewport(args) {
 		}
 	} finally {
 		await withTimeout(context.close().catch(() => void 0), 5e3);
-		await session?.close();
+		await launchTarget.session?.close();
 	}
 }
 async function replayAgentCassette(cassette, cassettePath, options) {
@@ -1884,14 +1864,11 @@ function formatStepLabel(step) {
 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 printAgentLaunchPlan(input) {
+	return formatAgentLaunchCommand(normalizeAgentFlowSpec(input).launch);
 }
 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 };
+export { isAgentManifestLike as C, writeAgentManifestPath as E, agentManifestPath as S, validateAgentManifestFiles as T, readAgentCassettePath as _, runAgentSpecPath as a, launchAgentBrowser as b, agentRunModeSchema as c, readAgentRunRecordPath as d, writeAgentRunRecordPath as f, isAgentCassetteLike as g, resolveAgentLaunchTarget as h, runAgentSpec as i, formatAgentArgv as l, createAgentTemplateSpec as m, printAgentLaunchPlan as n, loadAgentSpec as o, formatArgv as p, replayAgentRecordPath as r, AGENT_RUN_RECORD_SCHEMA_URL as s, defaultSpecNameForPath as t, isAgentRunRecordLike as u, normalizeAgentFlowSpec as v, readAgentManifestPath as w, AGENT_MANIFEST_FILE_NAME as x, sanitizeArtifactName as y };

package/dist/{server-VHuEWWj_.mjs → server-BC3yo-dq.mjs}

@@ -2081,7 +2081,7 @@ function joinPosix(a, b) {
 }
 //#endregion
 //#region package.json
-var version = "0.2.0";
+var version = "0.3.0";
 //#endregion
 //#region src/mcp/server.ts
 const textMaskRuleSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ptywright",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Terminal/TUI automation driver over PTY + xterm, exposed as MCP tools",
   "keywords": [
     "agent",

package/schemas/ptywright-agent.schema.json

@@ -14,31 +14,15 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "mode": { "type": "string", "enum": ["aitty", "url"] },
+        "mode": { "type": "string", "enum": ["command", "url"] },
         "agentFlavor": { "type": "string", "enum": ["codex", "claude", "droid", "generic"] },
         "command": { "type": "string", "minLength": 1 },
         "args": { "type": "array", "items": { "type": "string" } },
         "cwd": { "type": "string" },
         "env": { "type": "object", "additionalProperties": { "type": "string" } },
         "url": { "type": "string" },
-        "aitty": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "command": { "type": "string", "minLength": 1 },
-            "args": { "type": "array", "items": { "type": "string" } },
-            "project": { "type": "string", "minLength": 1 },
-            "label": { "type": "string", "minLength": 1 },
-            "title": { "type": "string", "minLength": 1 },
-            "subtitle": { "type": "string", "minLength": 1 },
-            "theme": { "type": "string", "enum": ["dark", "light", "auto"] },
-            "fontSize": { "type": "integer", "minimum": 11, "maximum": 24 },
-            "screenMode": { "type": "string", "enum": ["termvision"] },
-            "port": { "type": "integer", "minimum": 0, "maximum": 65535 },
-            "host": { "type": "string", "minLength": 1 },
-            "waitForUrlMs": { "type": "integer", "minimum": 1 }
-          }
-        }
+        "urlRegex": { "type": "string", "minLength": 1 },
+        "waitForUrlMs": { "type": "integer", "minimum": 1 }
       }
     },
     "viewports": {