@treeport/treeport 0.5.0 → 0.7.0

package/dist/node/cli/index.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
-import { A as treeportVersion, C as disableTailscaleRemote, D as resolvePackagePath, E as resolveLocalApiUrl, M as parseDurationMs, N as TERMINAL_CAPTURE_MAX_LINES, O as runDoctor, S as daemonUp, T as readDaemonLogs, _ as serviceStatus, b as daemonHealth, ct as parseEventsSnapshot, d as serviceDisable, f as serviceDoctorCheck, g as serviceStart, h as serviceRun, k as tailscaleRemoteStatus, l as readServiceLogs, lt as parseProductEvent, m as serviceInstalled, p as serviceEnable, s as runLocalUpdate, st as webPanelInputSchema, t as LocalUpdateError, u as serviceApply, ut as SOCKET_IO_PATH, v as serviceStop, w as enableTailscaleRemote, x as daemonStatus, y as daemonDown } from "../../update-BW-a6Bd-.js";
+import { Ct as projectsResponseSchema, Dt as terminalCaptureResponseSchema, G as treeportRpcClientLayer, Gt as webPanelDefinitionsResponseSchema, K as TreeportRpcs, Lt as treeContextResponseSchema, Nt as terminalResponseSchema, Ot as terminalObservationResponseSchema, Pt as terminatedTerminalsResponseSchema, St as projectResponseSchema, Tt as removePreviewResponseSchema, U as decodeUnknownOrNull, V as webPanelInputSchema, _t as packageOperationResponseSchema, bt as packageReloadResponseSchema, dt as openBrowserPanelResponseSchema, et as browserAgentResponseSchema, ft as openWebPanelResponseSchema, gt as packageListingResponseSchema, mt as operationResponseSchema, nt as browserInstallStatusSchema, o as apiErrorBodySchema, t as TERMINAL_CAPTURE_MAX_LINES, tt as browserInstallResponseSchema, ut as okResponseSchema, vt as packageOperationsResponseSchema, yt as packageProjectResponseSchema } from "../../dist-BsLn2Gbc.js";
+import { A as tailscaleRemoteStatus, C as daemonUp, D as resolveLocalApiUrl, E as readDaemonLogs, N as parseDurationMs, O as resolvePackagePath, S as daemonStatus, T as enableTailscaleRemote, _ as serviceStart, b as daemonDown, c as runLocalUpdate, d as serviceApply, f as serviceDisable, g as serviceRun, h as serviceInstalled, j as treeportVersion, k as runDoctor, m as serviceEnable, p as serviceDoctorCheck, r as formatLocalUpdateError, t as LocalUpdateError, u as readServiceLogs, v as serviceStatus, w as disableTailscaleRemote, x as daemonHealth, y as serviceStop } from "../../update-UYS2lMdD.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Command, CommanderError } from "commander";
-import { io } from "socket.io-client";
+import { RpcClient } from "@effect/rpc";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Stream from "effect/Stream";
 import { spawn } from "node:child_process";
 //#region src/cli/args.ts
 function extractJsonOutput(args) {
@@ -145,7 +149,7 @@ async function ensureServiceDaemon() {
 		pid: state.pid
 	};
 }
-async function request(pathname, options = {}) {
+async function request(pathname, schema, options = {}) {
 	const controller = new AbortController();
 	const externalSignal = options.signal;
 	const abort = () => controller.abort();
@@ -163,10 +167,12 @@ async function request(pathname, options = {}) {
 		});
 		const body = await response.json().catch(() => ({}));
 		if (!response.ok) {
-			const error = body.error;
-			throw new CliError(error?.message || `HTTP ${response.status}`, 5, error?.code || "API_ERROR", error?.details);
+			const failure = decodeUnknownOrNull(apiErrorBodySchema, body);
+			throw new CliError(failure?.error.message || `HTTP ${response.status}`, 5, failure?.error.code || "API_ERROR", failure?.error.details);
 		}
-		return body;
+		const decoded = decodeUnknownOrNull(schema, body);
+		if (decoded === null) throw new CliError(`Treeport daemon returned an invalid response for ${pathname}`, 3, "DAEMON_PROTOCOL_ERROR", { pathname });
+		return decoded;
 	} catch (error) {
 		if (error instanceof CliError) throw error;
 		throw new CliError(`Cannot reach Treeport daemon at ${apiUrl}: ${error instanceof Error ? error.message : String(error)}`, 3, "DAEMON_UNREACHABLE");
@@ -176,19 +182,19 @@ async function request(pathname, options = {}) {
 	}
 }
 async function createWorktree(projectId, input) {
-	let operation = (await request(`/api/projects/${encodeURIComponent(projectId)}/worktree-operations`, {
+	let operation = (await request(`/api/projects/${encodeURIComponent(projectId)}/worktree-operations`, operationResponseSchema, {
 		method: "POST",
 		body: JSON.stringify(input)
 	})).operation;
 	while (operation.status === "pending" || operation.status === "running") {
 		await new Promise((resolve) => setTimeout(resolve, 100));
-		operation = (await request(`/api/operations/${encodeURIComponent(operation.id)}`)).operation;
+		operation = (await request(`/api/operations/${encodeURIComponent(operation.id)}`, operationResponseSchema)).operation;
 	}
 	if (operation.status === "failed") throw new CliError(operation.error ?? "Tree creation failed", 5, "WORKTREE_CREATION_FAILED");
 	if (operation.kind !== "create") throw new CliError("Tree creation returned an unexpected operation kind", 5, "INVALID_OPERATION_RESULT");
 	const worktreeId = operation.result?.worktreeId ?? operation.worktreeId;
 	if (!worktreeId) throw new CliError("Completed tree creation did not identify its tree", 5, "INVALID_OPERATION_RESULT");
-	const worktree = (await request(`/api/projects/${encodeURIComponent(projectId)}`)).project.worktrees.find((item) => item.id === worktreeId);
+	const worktree = (await request(`/api/projects/${encodeURIComponent(projectId)}`, projectResponseSchema)).project.worktrees.find((item) => item.id === worktreeId);
 	if (!worktree) throw new CliError(`Created tree ${worktreeId} was not found`, 5, "INVALID_OPERATION_RESULT");
 	const terminalId = operation.result?.terminalId ?? null;
 	return {
@@ -211,7 +217,7 @@ async function canonical(value) {
 	return fs.realpath(resolved).catch(() => resolved);
 }
 async function projects() {
-	return (await request("/api/projects")).projects;
+	return (await request("/api/projects", projectsResponseSchema)).projects;
 }
 function pathContains(candidate, parent) {
 	const relative = path.relative(parent, candidate);
@@ -239,7 +245,7 @@ async function packageSource(value) {
 	return value;
 }
 async function localPackageProjectId() {
-	return (await request(`/api/packages/project?${new URLSearchParams({ path: await canonical(workingDirectory) }).toString()}`)).project.id;
+	return (await request(`/api/packages/project?${new URLSearchParams({ path: await canonical(workingDirectory) }).toString()}`, packageProjectResponseSchema)).project.id;
 }
 async function resolveWorktree(identifier) {
 	const all = (await projects()).flatMap((project) => project.worktrees);
@@ -263,12 +269,12 @@ function parseWebPanelInput(value) {
 	} catch (error) {
 		throw new CliError(`--input must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`, 2);
 	}
-	const validated = webPanelInputSchema.safeParse(parsed);
-	if (!validated.success) throw new CliError("--input must contain a JSON object", 2);
-	return validated.data;
+	const validated = decodeUnknownOrNull(webPanelInputSchema, parsed);
+	if (!validated) throw new CliError("--input must contain a JSON object", 2);
+	return validated;
 }
 async function webPanelDefinition(worktreeId, identifier) {
-	const definitions = (await request(`/api/worktrees/${encodeURIComponent(worktreeId)}/web-panel-definitions`)).definitions;
+	const definitions = (await request(`/api/worktrees/${encodeURIComponent(worktreeId)}/web-panel-definitions`, webPanelDefinitionsResponseSchema)).definitions;
 	const exact = definitions.find((definition) => definition.id === identifier);
 	if (exact) return exact;
 	const matches = definitions.filter((definition) => decodeURIComponent(definition.id.split(":").at(-1) ?? "") === identifier);
@@ -285,7 +291,37 @@ async function webPanelLaunchCwd(worktree) {
 	});
 	return path.relative(worktreeRoot, cwd) || ".";
 }
-function webPanelUrl(worktree, panelId) {
+async function resolveBrowserPanel(panelId) {
+	const candidates = (await projects()).flatMap((project) => project.worktrees.flatMap((worktree) => worktree.panels.filter((panel) => panel.kind === "browser").map((panel) => ({
+		panel,
+		worktree
+	}))));
+	if (panelId) {
+		const match = candidates.find((candidate) => candidate.panel.id === panelId);
+		if (!match) throw new CliError(`Browser ${panelId} was not found`, 5);
+		return match;
+	}
+	const worktree = await resolveWorktree(".");
+	const matches = candidates.filter((candidate) => candidate.worktree.id === worktree.id);
+	if (matches.length === 1) return matches[0];
+	if (matches.length === 0) throw new CliError(`No Browser is open in worktree ${worktree.name}`, 5, "BROWSER_PANEL_NOT_FOUND");
+	throw new CliError(`More than one Browser is open in worktree ${worktree.name}; specify --panel`, 5, "BROWSER_PANEL_AMBIGUOUS", { panelIds: matches.map((candidate) => candidate.panel.id) });
+}
+async function runBrowserAgentCommand(command, args, panelId) {
+	const { panel } = await resolveBrowserPanel(panelId);
+	const result = await request(`/api/panels/${encodeURIComponent(panel.id)}/browser-agent`, browserAgentResponseSchema, {
+		method: "POST",
+		body: JSON.stringify({
+			command,
+			args
+		})
+	});
+	return {
+		panelId: panel.id,
+		output: result.output
+	};
+}
+function panelUrl(worktree, panelId) {
 	const target = new URL(apiUrl);
 	target.pathname = `/projects/${encodeURIComponent(worktree.projectId)}/worktrees/${encodeURIComponent(worktree.id)}/panels/${encodeURIComponent(panelId)}`;
 	target.search = "";
@@ -315,7 +351,7 @@ function parseDuration(value) {
 	}
 }
 async function inspectTerminal(terminalId, signal) {
-	return request(`/api/terminals/${encodeURIComponent(terminalId)}`, signal ? { signal } : {});
+	return request(`/api/terminals/${encodeURIComponent(terminalId)}`, terminalObservationResponseSchema, signal ? { signal } : {});
 }
 async function waitForTerminal(terminalId, condition, timeoutMs) {
 	let observation = null;
@@ -347,16 +383,9 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 		if (condition === "bell") bellBaseline = observation.metadata.bell?.sequence ?? 0;
 		const immediate = matched((/* @__PURE__ */ new Date()).toISOString());
 		if (immediate) return immediate;
-		events = io(`${apiUrl}/events`, {
-			path: SOCKET_IO_PATH,
-			transports: ["websocket"],
-			forceNew: true,
-			autoConnect: false,
-			reconnection: false,
-			retries: 0
-		});
 		return await new Promise((resolve, reject) => {
 			let settled = false;
+			let connected = false;
 			let queue = Promise.resolve();
 			const finish = (result) => {
 				if (!settled) {
@@ -374,16 +403,15 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 				queue = queue.then(task);
 				queue.catch(fail);
 			};
-			controller.signal.addEventListener("abort", () => fail(/* @__PURE__ */ new Error("Terminal wait cancelled")), { once: true });
-			events.on("snapshot", (value) => enqueue(async () => {
-				const snapshot = parseEventsSnapshot(value);
-				if (!snapshot || !observation) throw new CliError("Treeport daemon sent an invalid event snapshot", 3, "DAEMON_PROTOCOL_ERROR");
-				const metadata = snapshot.terminalMetadata.find((item) => item.terminalId === terminalId);
+			const snapshot = async (value) => {
+				if (!observation) throw new CliError("Treeport daemon sent an invalid event snapshot", 3, "DAEMON_PROTOCOL_ERROR");
+				connected = true;
+				const metadata = value.terminalMetadata.find((item) => item.terminalId === terminalId);
 				if (metadata) observation = {
 					...observation,
 					metadata
 				};
-				const snapshotMatch = matched(snapshot.at);
+				const snapshotMatch = matched(value.at);
 				if (snapshotMatch) {
 					finish(snapshotMatch);
 					return;
@@ -392,10 +420,8 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 				if (cancellation) throw new Error("Terminal wait cancelled");
 				const refreshedMatch = matched((/* @__PURE__ */ new Date()).toISOString());
 				if (refreshedMatch) finish(refreshedMatch);
-			}));
-			events.on("product_event", (value) => enqueue(async () => {
-				const event = parseProductEvent(value);
-				if (!event) throw new CliError("Treeport daemon sent an invalid product event", 3, "DAEMON_PROTOCOL_ERROR");
+			};
+			const productEvent = async (event) => {
 				if (event.type !== "terminal.metadata" && event.type !== "terminal.updated" && event.type !== "terminal.removed") return;
 				if (event.data.terminalId !== terminalId) return;
 				if (event.type === "terminal.removed") throw new CliError(`Terminal ${terminalId} was removed while waiting`, 5, "TERMINAL_REMOVED", {
@@ -415,10 +441,15 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 				}
 				const result = matched(event.at);
 				if (result) finish(result);
-			}));
-			events.on("connect_error", (error) => fail(new CliError(`Cannot reach Treeport daemon at ${apiUrl}: ${error.message}`, 3, "DAEMON_UNREACHABLE")));
-			events.on("disconnect", () => fail(new CliError("Treeport daemon event channel disconnected before the condition was observed", 3, "DAEMON_DISCONNECTED")));
-			events.connect();
+			};
+			controller.signal.addEventListener("abort", () => fail(/* @__PURE__ */ new Error("Terminal wait cancelled")), { once: true });
+			const program = Effect.scoped(Effect.gen(function* () {
+				yield* (yield* RpcClient.make(TreeportRpcs)).WatchProjectEvents({ protocol: 3 }).pipe(Stream.runForEach((item) => Effect.sync(() => {
+					if (item._tag === "Snapshot") enqueue(() => snapshot(item.snapshot));
+					else enqueue(() => productEvent(item.event));
+				})));
+			})).pipe(Effect.provide(treeportRpcClientLayer(`${apiUrl}/api/rpc`)), Effect.onExit(() => Effect.sync(() => fail(connected ? new CliError("Treeport daemon event channel disconnected before the condition was observed", 3, "DAEMON_DISCONNECTED") : new CliError(`Cannot reach Treeport daemon at ${apiUrl}`, 3, "DAEMON_UNREACHABLE")))));
+			events = Effect.runFork(program);
 		});
 	} catch (error) {
 		if (cancellation === "timeout") throw new CliError(`Timed out waiting for terminal ${terminalId} to reach ${condition}`, 4, "WAIT_TIMEOUT", {
@@ -434,20 +465,16 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 		if (timeout) clearTimeout(timeout);
 		process.off("SIGINT", interrupt);
 		controller.abort();
-		events?.removeAllListeners();
-		events?.disconnect();
+		if (events) Effect.runFork(Fiber.interrupt(events));
 	}
 }
 function print(value, human) {
 	writeStdout(`${jsonOutput ? JSON.stringify(value) : human ? human() : JSON.stringify(value, null, 2)}\n`);
 }
-const agentGuidance = `AI agents:
-  If you're an AI agent, use \`treeport skills\` to see the usage guide.
-`;
 async function main(args) {
 	const argv = args[0] === "spawn" || args[0] === "terminal" && args[1] === "create" ? commandArgv(args) : void 0;
 	let parserError = "";
-	const program = new Command().name("treeport").usage("[options] [folder] [command]").description("Manage Treeport projects, trees, and terminals.").argument("[folder]", "folder or folder inside a Git repository to open").option("--json", "emit machine-readable JSON").addHelpText("beforeAll", agentGuidance).configureOutput({
+	const program = new Command().name("treeport").usage("[options] [folder] [command]").description("Manage Treeport projects, trees, and terminals.").argument("[folder]", "folder or folder inside a Git repository to open").option("--json", "emit machine-readable JSON").configureOutput({
 		writeOut: writeStdout,
 		writeErr: (value) => {
 			parserError += value;
@@ -471,7 +498,7 @@ async function main(args) {
 			if (!await daemonHealth(apiUrl)) throw new CliError(`Cannot reach the externally managed Treeport daemon at ${apiUrl}. Start it through the process that owns its lifecycle and retry.`, 3, "DAEMON_UNREACHABLE");
 		} else if (lifecycle === "service") await ensureServiceDaemon();
 		else await daemonUp({});
-		const registered = await request("/api/projects", {
+		const registered = await request("/api/projects", projectResponseSchema, {
 			method: "POST",
 			body: JSON.stringify({ path: canonicalFolder })
 		});
@@ -484,7 +511,7 @@ async function main(args) {
 		target.pathname = `/projects/${encodeURIComponent(registered.project.id)}/worktrees/${encodeURIComponent(targetWorktree.id)}`;
 		target.search = "";
 		target.hash = "";
-		const opened = contextTerminalId ? await request(`/api/worktrees/${encodeURIComponent(targetWorktree.id)}/open`, {
+		const opened = contextTerminalId ? await request(`/api/worktrees/${encodeURIComponent(targetWorktree.id)}/open`, okResponseSchema, {
 			method: "POST",
 			body: JSON.stringify({ sourceTerminalId: contextTerminalId })
 		}).then(() => ({ client: "current" })) : await openWorkspace(target.href).catch((error) => {
@@ -521,13 +548,13 @@ async function main(args) {
 		if (options.foreground) return;
 		print(result, () => `Treeport is running\n${result.apiUrl}`);
 	});
-	const stopCommand = program.command("stop").description("Stop the local daemon and preserve terminal sessions").option("--terminate-terminals", "terminate every Treeport-owned tmux server").option("--force", "confirm termination of all terminals").option("--json", "emit machine-readable JSON");
+	const stopCommand = program.command("stop").description("Stop the local daemon and preserve terminal sessions").option("--terminate-terminals", "terminate every Treeport-owned terminal process").option("--force", "confirm termination of all terminals").option("--json", "emit machine-readable JSON");
 	stopCommand.action(async () => {
 		const lifecycle = await resolveDaemonLifecycle();
 		if (lifecycle === "external") throw new CliError("Cannot run `treeport stop` because the daemon lifecycle is externally managed. Control the process that started Treeport instead.", 5, "DAEMON_LIFECYCLE_EXTERNAL");
 		const options = stopCommand.opts();
 		if (options.terminateTerminals && !options.force) throw new CliError("Re-run with --terminate-terminals --force to confirm termination of every terminal.", 2);
-		if (options.terminateTerminals) await request("/api/admin/terminate-terminals", { method: "POST" });
+		if (options.terminateTerminals) await request("/api/admin/terminate-terminals", terminatedTerminalsResponseSchema, { method: "POST" });
 		if (lifecycle === "service") {
 			const result = await serviceStop();
 			print(result, () => formatServiceStatus(result.status));
@@ -662,7 +689,7 @@ async function main(args) {
 			...!terminalId ? [`${contextPrefix}_TERMINAL_ID`] : []
 		];
 		if (missing.length) throw new CliError(`Incomplete Treeport context; missing ${missing.join(", ")}`, 5, "TREEPORT_CONTEXT_INCOMPLETE", { missing });
-		const project = (await request(`/api/projects/${encodeURIComponent(projectId)}`)).project;
+		const project = (await request(`/api/projects/${encodeURIComponent(projectId)}`, projectResponseSchema)).project;
 		const worktree = project.worktrees.find((candidate) => candidate.id === worktreeId);
 		if (!worktree) throw new CliError("Treeport context tree does not belong to the current project", 5, "TREEPORT_CONTEXT_INVALID", {
 			projectId,
@@ -673,6 +700,7 @@ async function main(args) {
 			worktreeId,
 			terminalId
 		});
+		const treeContext = (await request(`/api/worktrees/${encodeURIComponent(worktree.id)}/context`, treeContextResponseSchema)).context;
 		const context = {
 			managed: true,
 			apiUrl,
@@ -695,7 +723,8 @@ async function main(args) {
 				head: worktree.head,
 				branch: worktree.branch,
 				detached: worktree.detached,
-				kind: worktree.kind
+				kind: worktree.kind,
+				context: treeContext
 			},
 			terminal: {
 				id: terminal.id,
@@ -705,14 +734,114 @@ async function main(args) {
 				exitCode: terminal.exitCode
 			}
 		};
-		print(context, () => `Treeport context\n\nProject:  ${context.project.name} (${context.project.id})\nTree:     ${context.worktree.name} (${context.worktree.id})\nPath:     ${context.worktree.path}\nTerminal: ${context.terminal.name} (${context.terminal.id}) — ${context.terminal.status}\nAPI:      ${context.apiUrl}\nLifecycle: ${context.daemonLifecycle === "external" ? "externally managed" : context.daemonLifecycle === "service" ? "managed by the OS service" : "managed by Treeport"}`);
+		print(context, () => {
+			const entries = Object.entries(context.worktree.context);
+			const treeContextText = entries.length === 0 ? "—" : entries.map(([key, value]) => {
+				const [first = "", ...rest] = [...value].map((character) => {
+					const code = character.charCodeAt(0);
+					return code !== 10 && (code <= 31 || code >= 127 && code <= 159) ? `\\u${code.toString(16).padStart(4, "0")}` : character;
+				}).join("").split("\n");
+				return `  ${key}: ${first}${rest.length > 0 ? `\n${rest.map((line) => `    ${line}`).join("\n")}` : ""}`;
+			}).join("\n");
+			return `Treeport context\n\nProject:  ${context.project.name} (${context.project.id})\nTree:     ${context.worktree.name} (${context.worktree.id})\nPath:     ${context.worktree.path}\nContext:\n${treeContextText}\nTerminal: ${context.terminal.name} (${context.terminal.id}) — ${context.terminal.status}\nAPI:      ${context.apiUrl}\nLifecycle: ${context.daemonLifecycle === "external" ? "externally managed" : context.daemonLifecycle === "service" ? "managed by the OS service" : "managed by Treeport"}`;
+		});
+	});
+	const browserCommand = program.command("browser").description("Manage Browser and its hosted Chromium");
+	browserCommand.action(() => {
+		writeStdout(browserCommand.helpInformation());
 	});
+	const browserOpenCommand = browserCommand.command("open").description("Open Browser and request client navigation").argument("[url]", "absolute HTTP or HTTPS URL").requiredOption("--worktree <id-or-path-or-dot>", "owning tree").option("--json", "emit machine-readable JSON");
+	browserOpenCommand.action(async (url) => {
+		const worktree = await resolveWorktree(browserOpenCommand.opts().worktree);
+		const body = {
+			url,
+			sourceTerminalId: contextWorktreeId === worktree.id ? contextTerminalId ?? null : null
+		};
+		const result = await request(`/api/worktrees/${encodeURIComponent(worktree.id)}/browser-panels`, openBrowserPanelResponseSchema, {
+			method: "POST",
+			body: JSON.stringify(body)
+		});
+		const output = {
+			...result,
+			url: panelUrl(worktree, result.panel.id)
+		};
+		print(output, () => `Opened ${result.panel.title} (${result.panel.id})\n${output.url}`);
+	});
+	browserCommand.command("install").description("Install the Chromium build used by Browser").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await request("/api/browser/install", browserInstallResponseSchema, { method: "POST" });
+		print(result, () => result.message);
+	});
+	browserCommand.command("status").description("Show hosted browser installation status").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await request("/api/browser/status", browserInstallStatusSchema);
+		print(result, () => `${result.installed ? "Chromium is installed" : "Chromium is not installed"}\nLaunch ready: ${result.launchReady ? "yes" : "no"}\nPlaywright: ${result.playwrightVersion}\nBrowser: ${result.channel} ${result.browserRevision}\nExecutable: ${result.executablePath}${result.launchError ? `\nLaunch error: ${result.launchError}` : ""}`);
+	});
+	browserCommand.command("remove").description("Remove Treeport's hosted Chromium build").option("--json", "emit machine-readable JSON").action(async () => {
+		await request("/api/browser/install", okResponseSchema, { method: "DELETE" });
+		print({ removed: true }, () => "Removed Treeport hosted Chromium");
+	});
+	browserCommand.command("list").description("List open Browser sessions").option("--json", "emit machine-readable JSON").action(async () => {
+		const panels = (await projects()).flatMap((project) => project.worktrees.flatMap((worktree) => worktree.panels.filter((panel) => panel.kind === "browser").map((panel) => ({
+			panelId: panel.id,
+			title: panel.title,
+			worktreeId: worktree.id,
+			worktree: worktree.name,
+			projectId: project.id,
+			project: project.name
+		}))));
+		print(panels, () => panels.length ? panels.map((panel) => `${panel.panelId}\t${panel.project} / ${panel.worktree}\t${panel.title}`).join("\n") : "Browser is not open.");
+	});
+	const printAgentResult = async (command, args, panelId) => {
+		const result = await runBrowserAgentCommand(command, args, panelId);
+		print(result, () => result.output);
+	};
+	const browserSnapshotCommand = browserCommand.command("snapshot").description("Capture an accessibility snapshot of the hosted page").option("--panel <panel-id>", "Browser ID").option("--json", "emit machine-readable JSON");
+	browserSnapshotCommand.action(async () => printAgentResult("snapshot", [], browserSnapshotCommand.opts().panel));
+	const browserClickCommand = browserCommand.command("click").description("Click an element from the latest browser snapshot").argument("<target>", "Playwright element reference or selector").option("--panel <panel-id>", "Browser ID").option("--json", "emit machine-readable JSON");
+	browserClickCommand.action(async (target) => printAgentResult("click", [target], browserClickCommand.opts().panel));
+	const browserFillCommand = browserCommand.command("fill").description("Fill an editable element from the latest browser snapshot").argument("<target>", "Playwright element reference or selector").argument("<text>", "text to enter").option("--panel <panel-id>", "Browser ID").option("--json", "emit machine-readable JSON");
+	browserFillCommand.action(async (target, text) => printAgentResult("fill", [target, text], browserFillCommand.opts().panel));
+	const browserPressCommand = browserCommand.command("press").description("Press a key in the hosted page").argument("<key>", "Playwright key name").option("--panel <panel-id>", "Browser ID").option("--json", "emit machine-readable JSON");
+	browserPressCommand.action(async (key) => printAgentResult("press", [key], browserPressCommand.opts().panel));
+	const browserGotoCommand = browserCommand.command("goto").description("Navigate the hosted page").argument("<url>", "absolute HTTP or HTTPS URL").option("--panel <panel-id>", "Browser ID").option("--json", "emit machine-readable JSON");
+	browserGotoCommand.action(async (url) => printAgentResult("goto", [url], browserGotoCommand.opts().panel));
+	const browserConsoleCommand = browserCommand.command("console").description("List page console messages").argument("[level]", "minimum console level").option("--panel <panel-id>", "Browser ID").option("--json", "emit machine-readable JSON");
+	browserConsoleCommand.action(async (level) => printAgentResult("console", level ? [level] : [], browserConsoleCommand.opts().panel));
+	for (const [name, description, agentName] of [
+		[
+			"back",
+			"Go back in the hosted page",
+			"go-back"
+		],
+		[
+			"forward",
+			"Go forward in the hosted page",
+			"go-forward"
+		],
+		[
+			"reload",
+			"Reload the hosted page",
+			"reload"
+		],
+		[
+			"network",
+			"List page network requests",
+			"requests"
+		],
+		[
+			"screenshot",
+			"Capture a screenshot of the hosted page",
+			"screenshot"
+		]
+	]) {
+		const command = browserCommand.command(name).description(description).option("--panel <panel-id>", "Browser ID").option("--json", "emit machine-readable JSON");
+		command.action(async () => printAgentResult(agentName, [], command.opts().panel));
+	}
 	const installCommand = program.command("install").description("Install and configure a Treeport package").argument("<source>", "npm: source or local directory").option("-l, --local", "configure the registered project containing the current directory").option("--json", "emit machine-readable JSON");
 	installCommand.action(async (source) => {
 		const options = installCommand.opts();
 		const body = { source: await packageSource(source) };
 		if (options.local) body.projectId = await localPackageProjectId();
-		const result = (await request("/api/packages/install", {
+		const result = (await request("/api/packages/install", packageOperationResponseSchema, {
 			method: "POST",
 			body: JSON.stringify(body)
 		})).result;
@@ -723,14 +852,14 @@ async function main(args) {
 		const options = removePackageCommand.opts();
 		const body = { source: await packageSource(source) };
 		if (options.local) body.projectId = await localPackageProjectId();
-		const result = (await request("/api/packages/remove", {
+		const result = (await request("/api/packages/remove", packageOperationResponseSchema, {
 			method: "POST",
 			body: JSON.stringify(body)
 		})).result;
 		print(result, () => `Removed ${result.source}`);
 	});
 	program.command("list").description("List configured Treeport packages").option("--json", "emit machine-readable JSON").action(async () => {
-		const result = await request("/api/packages");
+		const result = await request("/api/packages", packageListingResponseSchema);
 		print(result, () => {
 			const lines = result.packages.map((pkg) => {
 				return `${pkg.scope === "global" ? "global" : `project:${pkg.projectName ?? pkg.projectId}`}\t${pkg.source}\t${pkg.resources.webPanels} web panels, ${pkg.resources.terminalPresets} terminal presets`;
@@ -748,7 +877,7 @@ async function main(args) {
 			const selfUpdateOptions = { environment: cliEnvironment };
 			if (!jsonOutput) selfUpdateOptions.progress = (message) => writeStderr(`${message}\n`);
 			const result = await runLocalUpdate(selfUpdateOptions).catch((error) => {
-				if (error instanceof LocalUpdateError) throw new CliError(error.message, error.exitCode, error.code, error.details);
+				if (error instanceof LocalUpdateError) throw new CliError(jsonOutput ? error.message : formatLocalUpdateError(error.message, error.details), error.exitCode, error.code, error.details);
 				throw error;
 			});
 			print(result, () => {
@@ -757,7 +886,7 @@ async function main(args) {
 			});
 			return;
 		}
-		const results = (await request("/api/packages/update", {
+		const results = (await request("/api/packages/update", packageOperationsResponseSchema, {
 			method: "POST",
 			body: JSON.stringify(source ? { source: await packageSource(source) } : {})
 		})).results;
@@ -766,7 +895,7 @@ async function main(args) {
 	const reloadCommand = program.command("reload").description("Reload package settings and resources without restarting").option("-l, --local", "reload only the registered project containing the current directory").option("--json", "emit machine-readable JSON");
 	reloadCommand.action(async () => {
 		const options = reloadCommand.opts();
-		const result = await request("/api/packages/reload", {
+		const result = await request("/api/packages/reload", packageReloadResponseSchema, {
 			method: "POST",
 			body: JSON.stringify(options.local ? { projectId: await localPackageProjectId() } : {})
 		});
@@ -779,7 +908,7 @@ async function main(args) {
 		throw new CliError(projectCommand.helpInformation(), 2);
 	});
 	projectCommand.command("add").description("Register a folder or Git repository").argument("<path>", "folder path").option("--json", "emit machine-readable JSON").action(async (repository) => {
-		const body = await request("/api/projects", {
+		const body = await request("/api/projects", projectResponseSchema, {
 			method: "POST",
 			body: JSON.stringify({ path: await canonical(repository) })
 		});
@@ -812,25 +941,46 @@ async function main(args) {
 		const result = await createWorktree(project.id, request);
 		print(result, () => `Created tree ${result.worktree.name} (${result.worktree.id})\n${result.worktree.path}${result.setupError ? `\nSetup error: ${result.setupError}` : ""}`);
 	});
-	const worktreeRemoveCommand = worktreeCommand.command("remove").description("Remove a linked tree").argument("<id-or-path-or-dot>", "Tree to remove").option("--force", "confirm destructive removal warnings").option("--json", "emit machine-readable JSON");
+	const worktreeRemoveCommand = worktreeCommand.command("remove").description("Remove a linked tree").argument("<id-or-path-or-dot>", "Tree to remove").option("--force", "confirm destructive removal warnings").option("--skip-cleanup", "remove without configured project cleanup").option("--json", "emit machine-readable JSON");
 	worktreeRemoveCommand.action(async (identifier) => {
-		const { force: confirmed } = worktreeRemoveCommand.opts();
+		const { force: confirmed, skipCleanup: requestedSkipCleanup } = worktreeRemoveCommand.opts();
 		const worktree = await resolveWorktree(identifier);
-		const preview = (await request(`/api/worktrees/${worktree.id}/remove-preview`)).preview;
+		const preview = (await request(`/api/worktrees/${worktree.id}/remove-preview`, removePreviewResponseSchema)).preview;
 		if (!preview.eligible) throw new CliError(preview.reasons.join("\n"), 5);
 		if (preview.warnings.length && !confirmed) throw new CliError(`${preview.warnings.join("\n")}\nRe-run with --force to confirm removal.`, 5);
-		let operation = (await request(`/api/worktrees/${worktree.id}/remove`, {
+		const skipCleanup = Boolean(requestedSkipCleanup) && preview.cleanup.commands.length > 0;
+		if (skipCleanup && !confirmed) throw new CliError("Skipping project cleanup can leave project resources behind.\nRe-run with --force --skip-cleanup to confirm removal.", 5);
+		let operation = (await request(`/api/worktrees/${worktree.id}/remove`, operationResponseSchema, {
 			method: "POST",
 			body: JSON.stringify({
 				confirmationToken: preview.confirmationToken,
-				confirmDestructive: preview.warnings.length > 0
+				confirmDestructive: preview.warnings.length > 0 || skipCleanup,
+				skipCleanup
 			})
 		})).operation;
+		const displayedCleanupCommands = /* @__PURE__ */ new Set();
+		const displayFinishedCleanup = () => {
+			if (jsonOutput || operation.kind !== "remove") return;
+			operation.request.cleanupCommands.commands.forEach((command, index) => {
+				if (displayedCleanupCommands.has(index) || command.status !== "completed" && command.status !== "failed") return;
+				displayedCleanupCommands.add(index);
+				const lines = [`Cleanup: ${command.name}${command.status === "failed" ? " (failed)" : ""}`];
+				if (command.stdout) lines.push(command.stdout.replace(/\n$/u, ""));
+				if (command.stderr) lines.push(command.stderr.replace(/\n$/u, ""));
+				if (command.outputTruncated) lines.push("Cleanup output was truncated.");
+				writeStdout(`${lines.join("\n")}\n`);
+			});
+		};
+		displayFinishedCleanup();
 		while (operation.status === "pending" || operation.status === "running") {
 			await new Promise((resolve) => setTimeout(resolve, 100));
-			operation = (await request(`/api/operations/${encodeURIComponent(operation.id)}`)).operation;
+			operation = (await request(`/api/operations/${encodeURIComponent(operation.id)}`, operationResponseSchema)).operation;
+			displayFinishedCleanup();
+		}
+		if (operation.status === "failed") {
+			const cleanup = operation.kind === "remove" ? operation.request.cleanupCommands.commands.find((command) => command.status === "failed") : null;
+			throw new CliError(operation.error ?? "Tree removal failed; Git kept the tree.", 5, "WORKTREE_REMOVAL_FAILED", cleanup ?? void 0);
 		}
-		if (operation.status === "failed") throw new CliError(operation.error ?? "Tree removal failed", 5, "WORKTREE_REMOVAL_FAILED");
 		if (operation.kind !== "remove" || !operation.result) throw new CliError("Tree removal returned an unexpected operation result", 5, "INVALID_OPERATION_RESULT");
 		print(operation.result, () => {
 			const warning = operation.result?.cleanup.warning;
@@ -846,7 +996,7 @@ async function main(args) {
 		const options = webPanelOpenCommand.opts();
 		const worktree = await resolveWorktree(options.worktree);
 		const definition = await webPanelDefinition(worktree.id, identifier);
-		const result = await request(`/api/worktrees/${encodeURIComponent(worktree.id)}/panels/open`, {
+		const result = await request(`/api/worktrees/${encodeURIComponent(worktree.id)}/panels/open`, openWebPanelResponseSchema, {
 			method: "POST",
 			body: JSON.stringify({
 				definitionId: definition.id,
@@ -858,7 +1008,7 @@ async function main(args) {
 		});
 		const output = {
 			...result,
-			url: webPanelUrl(worktree, result.panel.id)
+			url: panelUrl(worktree, result.panel.id)
 		};
 		print(output, () => `${result.reused ? "Reused" : "Opened"} ${result.panel.title} (${result.panel.id})\n${output.url}`);
 	});
@@ -878,7 +1028,7 @@ async function main(args) {
 		const worktree = await resolveWorktree(options.worktree);
 		const body = { name: options.name };
 		if (argv) body.argv = argv;
-		const result = await request(`/api/worktrees/${worktree.id}/terminals`, {
+		const result = await request(`/api/worktrees/${worktree.id}/terminals`, terminalResponseSchema, {
 			method: "POST",
 			body: JSON.stringify(body)
 		});
@@ -898,7 +1048,7 @@ async function main(args) {
 		const { lines: rawLines } = terminalCaptureCommand.opts();
 		const lines = rawLines === void 0 ? 200 : parseCaptureLines(rawLines);
 		const terminalId = resolveTerminalId(identifier);
-		const capture = await request(`/api/terminals/${encodeURIComponent(terminalId)}/capture?lines=${lines}`);
+		const capture = await request(`/api/terminals/${encodeURIComponent(terminalId)}/capture?lines=${lines}`, terminalCaptureResponseSchema);
 		if (jsonOutput) print(capture);
 		else {
 			writeStdout(capture.content);
@@ -918,7 +1068,7 @@ async function main(args) {
 		print(result, () => `${result.terminal.name} (${result.terminal.id}) reached ${result.condition} at ${result.observedAt}`);
 	});
 	terminalCommand.command("delete").description("Delete a terminal").argument("<terminal-id>", "terminal to delete").option("--json", "emit machine-readable JSON").action(async (terminalId) => {
-		await request(`/api/terminals/${terminalId}`, { method: "DELETE" });
+		await request(`/api/terminals/${terminalId}`, okResponseSchema, { method: "DELETE" });
 		print({
 			ok: true,
 			terminalId
@@ -969,11 +1119,14 @@ async function runCliApplication(options) {
 	} catch (error) {
 		const cliError = error instanceof CliError ? error : new CliError(error instanceof Error ? error.message : String(error), 1);
 		if (jsonOutput) {
-			const body = { error: {
+			const body = { error: cliError.details === void 0 ? {
 				code: cliError.code,
 				message: cliError.message
+			} : {
+				code: cliError.code,
+				message: cliError.message,
+				details: cliError.details
 			} };
-			if (cliError.details !== void 0) body.error.details = cliError.details;
 			writeStderr(`${JSON.stringify(body)}\n`);
 		} else writeStderr(`${cliError.message}\n`);
 		requestedExitCode = cliError.exitCode;