@onkernel/cua-cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,1758 @@
+#!/usr/bin/env node
+import { a as createKernelClient, i as captureScreenshot, n as listSupportedModels, o as provisionBrowser, r as resolveCuaModelRef, s as resolveProfileId, t as DEFAULT_CUA_MODEL_REF } from "./harness-models-GT8Ke1vt.js";
+import { stderr, stdout } from "node:process";
+import { parseArgs } from "node:util";
+import { CuaAgentHarness, InMemorySessionRepo, JsonlSessionRepo, NodeExecutionEnv, formatSkillsForSystemPrompt, loadSkills } from "@onkernel/cua-agent";
+import { getCuaEnvApiKey, getCuaModel, parseCuaModelRef, requireCuaEnvApiKey, resolveCuaRuntimeSpec } from "@onkernel/cua-ai";
+import { mkdir, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { createCodingTools } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+//#region src/action/prompts.ts
+function buildPrompt(req) {
+	switch (req.action) {
+		case "click":
+			if (!req.target) throw new Error("click action requires a target description");
+			return clickPrompt(req.target);
+		case "type":
+			if (!req.target) throw new Error("type action requires a target description");
+			if (!req.text) throw new Error("type action requires text to type");
+			return typePrompt(req.target, req.text);
+		case "open": {
+			const url = req.text || req.target;
+			if (!url) throw new Error("open action requires a URL");
+			return openPrompt(url);
+		}
+		case "press":
+			if (!req.keys || req.keys.length === 0) throw new Error("press action requires at least one key");
+			return pressPrompt(req.keys);
+		case "observe":
+			if (req.text) return observeWithQuestionPrompt(req.text);
+			return observePrompt();
+		case "url": return urlPrompt();
+		case "do": {
+			const instruction = req.text || req.target;
+			if (!instruction) throw new Error("do action requires an instruction");
+			return instruction;
+		}
+		case "screenshot": throw new Error("screenshot action does not use a prompt");
+	}
+}
+function clickPrompt(target) {
+	return `Look at the current screen. Locate and click the element that best matches this description: ${JSON.stringify(target)}.
+Perform exactly ONE click on the best matching element, then stop.
+If no matching element is visible on screen, respond with the text: NOT_FOUND: followed by a brief explanation.
+Do not perform any other actions.`;
+}
+function typePrompt(target, text) {
+	return `Look at the current screen. Locate the input/text field that best matches this description: ${JSON.stringify(target)}.
+Click on it to focus it, then type exactly this text: ${JSON.stringify(text)}
+Perform only the click and type actions, then stop.
+If no matching element is visible on screen, respond with the text: NOT_FOUND: followed by a brief explanation.
+Do not perform any other actions.`;
+}
+function openPrompt(url) {
+	return `Navigate the browser to this URL: ${url}
+Use the goto action. Perform only this navigation, then stop.`;
+}
+function pressPrompt(keys) {
+	return `Press the following key(s): ${keys.join("+")}
+Perform exactly this key press, then stop. Do not perform any other actions.`;
+}
+function observePrompt() {
+	return `Look at the current screen and describe what you see. Be concise and factual.
+Do NOT perform any actions. Only observe and describe.`;
+}
+function observeWithQuestionPrompt(question) {
+	return `Look at the current screen and answer this question: ${JSON.stringify(question)}
+Be concise and factual. Do NOT perform any actions. Only observe and respond.`;
+}
+function urlPrompt() {
+	return `Report the current page URL. Use the url action to read it. Do not perform any other actions.`;
+}
+//#endregion
+//#region src/action/result.ts
+/**
+* Build a structured ActionResult from the agent's final assistant text
+* and any action events captured during the run.
+*/
+function parseResult(action, textOutput, actionEvents, elapsedMs, toolError) {
+	const trimmed = textOutput.trim();
+	const result = {
+		action,
+		status: "ok",
+		elapsedMs,
+		timestamp: Date.now()
+	};
+	if (toolError && toolError.trim().length > 0) {
+		result.status = "error";
+		result.text = toolError.trim();
+		return result;
+	}
+	if (trimmed.startsWith("NOT_FOUND:")) {
+		result.status = "not_found";
+		result.text = trimmed.slice(10).trim();
+		return result;
+	}
+	for (let i = actionEvents.length - 1; i >= 0; i--) {
+		const ev = actionEvents[i];
+		if (ev.x !== void 0 && ev.y !== void 0 && (ev.actionType === "click" || ev.actionType === "double_click" || ev.actionType === "click_mouse" || ev.actionType === "left_click" || ev.actionType === "right_click" || ev.actionType === "middle_click" || ev.actionType === "triple_click" || ev.actionType === "click_at")) {
+			result.coordinates = [ev.x, ev.y];
+			break;
+		}
+	}
+	switch (action) {
+		case "observe":
+			result.text = trimmed;
+			break;
+		case "url": {
+			const url = extractFirstUrl(trimmed);
+			if (url) result.url = url;
+			else if (trimmed) {
+				result.status = "error";
+				result.text = trimmed;
+			}
+			break;
+		}
+		default: break;
+	}
+	return result;
+}
+function extractFirstUrl(text) {
+	const matches = text.match(/(?:https?:\/\/\S+|about:blank|file:\/\/\S+|chrome:\/\/\S+|chrome-extension:\/\/\S+|edge:\/\/\S+|brave:\/\/\S+)/gi);
+	if (!matches || matches.length === 0) return void 0;
+	return matches[matches.length - 1].replace(/[),.;!?]+$/, "");
+}
+function formatCompact(r) {
+	switch (r.status) {
+		case "not_found": return r.text ? `not_found ${r.text}` : "not_found";
+		case "error": return r.text ? `error ${r.text}` : "error";
+		case "timeout": return "timeout";
+	}
+	switch (r.action) {
+		case "click":
+			if (r.coordinates) return `ok clicked (${r.coordinates[0]}, ${r.coordinates[1]})`;
+			return "ok clicked";
+		case "type": return "ok typed";
+		case "open": return "ok";
+		case "press": return "ok pressed";
+		case "observe": return r.text ?? "";
+		case "url": return r.url ?? r.text ?? "";
+		case "screenshot": return "ok";
+		case "do": return r.text ?? "ok";
+		default: return "ok";
+	}
+}
+function exitCodeFor(r) {
+	switch (r.status) {
+		case "ok": return 0;
+		case "not_found": return 1;
+		default: return 2;
+	}
+}
+//#endregion
+//#region src/action/harness-runner.ts
+/**
+* Run a single action subcommand against an existing harness + browser and
+* return the parsed result plus exit code. The `screenshot` action is
+* model-free — it captures directly through the SDK. All other actions
+* drive the harness for at most `maxTurns` turns.
+*/
+async function runAction(req, opts, screenshot) {
+	const startedAt = Date.now();
+	if (req.action === "screenshot") {
+		const out = screenshot ?? { out: "screenshot.png" };
+		const png = await captureScreenshot(opts.browserHandle.client, opts.browserHandle.browser.session_id);
+		if (!png) {
+			const result = {
+				action: "screenshot",
+				status: "error",
+				text: "failed to capture screenshot",
+				elapsedMs: Date.now() - startedAt,
+				timestamp: Date.now()
+			};
+			return {
+				result,
+				exitCode: exitCodeFor(result)
+			};
+		}
+		if (out.out === "-") stdout.write(png);
+		else await writeFile(out.out, png);
+		const result = parseResult("screenshot", "", [], Date.now() - startedAt);
+		result.text = out.out === "-" ? "(stdout)" : out.out;
+		return {
+			result,
+			exitCode: 0
+		};
+	}
+	const prompt = buildPrompt(req);
+	const maxTurns = req.maxTurns ?? opts.maxTurns ?? 3;
+	const events = [];
+	let assistantText = "";
+	let turns = 0;
+	let aborted = false;
+	let lastToolError;
+	let lastToolErrorDetail;
+	const unsubscribe = opts.harness.subscribe((event) => {
+		switch (event.type) {
+			case "tool_execution_start":
+				collectActionEvent(event.toolName, event.args, events);
+				return;
+			case "tool_execution_end":
+				if (event.isError) {
+					const { text, detail } = inspectToolError(event.result);
+					lastToolError = text ?? "tool execution failed";
+					lastToolErrorDetail = detail;
+				}
+				return;
+			case "message_update":
+				if (event.assistantMessageEvent.type === "text_delta") assistantText += event.assistantMessageEvent.delta;
+				return;
+			case "turn_end":
+				turns += 1;
+				if (turns >= maxTurns && !aborted) {
+					aborted = true;
+					opts.harness.abort();
+				}
+				return;
+			default: return;
+		}
+	});
+	let runError;
+	let assistant;
+	try {
+		const images = await maybeInitialScreenshot$1(opts);
+		assistant = await opts.harness.prompt(prompt, images ? { images } : void 0);
+		if (assistant.stopReason === "error") runError = new Error(assistant.errorMessage ?? "agent stopped with error");
+	} catch (err) {
+		runError = err instanceof Error ? err : new Error(String(err));
+	} finally {
+		unsubscribe();
+	}
+	const elapsed = Date.now() - startedAt;
+	if (runError) {
+		const result = {
+			action: req.action,
+			status: "error",
+			text: runError.message,
+			elapsedMs: elapsed,
+			timestamp: Date.now()
+		};
+		return {
+			result,
+			exitCode: exitCodeFor(result)
+		};
+	}
+	if (!assistantText.trim() && assistant) assistantText = textFromAssistant(assistant);
+	const toolError = lastToolErrorDetail ?? lastToolError;
+	const result = parseResult(req.action, assistantText, events, elapsed, toolError);
+	return {
+		result,
+		exitCode: exitCodeFor(result)
+	};
+}
+async function maybeInitialScreenshot$1(opts) {
+	if (opts.skipInitialScreenshot) return void 0;
+	if (await sessionHasPriorTurn$1(opts.session)) return void 0;
+	const png = await captureScreenshot(opts.browserHandle.client, opts.browserHandle.browser.session_id);
+	if (!png) return void 0;
+	return [{
+		type: "image",
+		data: png.toString("base64"),
+		mimeType: "image/png"
+	}];
+}
+async function sessionHasPriorTurn$1(session) {
+	const entries = await session.getBranch();
+	for (const entry of entries) if (entry.type === "message" && (entry.message.role === "user" || entry.message.role === "assistant")) return true;
+	return false;
+}
+function textFromAssistant(message) {
+	const parts = [];
+	for (const block of message.content) if (block && block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	return parts.join("");
+}
+/**
+* Collect click coordinates from canonical CUA tool calls. The harness
+* dispatches batched calls via `computer_batch` (args: { actions: [...] })
+* and single-action calls via per-action tools (args: cua action without
+* the `type` field, which we recover from the tool name).
+*/
+function collectActionEvent(toolName, args, events) {
+	if (toolName === "computer_batch") {
+		const actions = args.actions;
+		if (Array.isArray(actions)) {
+			for (const action of actions) if (action && typeof action === "object") addClickEvent(action.type, action.x, action.y, events);
+		}
+		return;
+	}
+	if (args && typeof args === "object") {
+		const x = args.x;
+		const y = args.y;
+		addClickEvent(toolName, x, y, events);
+	}
+}
+function addClickEvent(type, x, y, events) {
+	if (typeof type !== "string") return;
+	if (type !== "click" && type !== "double_click") return;
+	if (typeof x !== "number" || typeof y !== "number") return;
+	events.push({
+		actionType: type,
+		x,
+		y
+	});
+}
+function inspectToolError(result) {
+	if (!result || typeof result !== "object") return {};
+	const detailsError = result.details?.error;
+	const detail = typeof detailsError === "string" ? detailsError.trim() : void 0;
+	const content = result.content;
+	if (!Array.isArray(content)) return { detail };
+	const parts = [];
+	for (const block of content) if (block && typeof block === "object" && block.type === "text") {
+		const text = block.text;
+		if (typeof text === "string" && text.trim().length > 0) parts.push(text.trim());
+	}
+	return {
+		text: parts.length > 0 ? parts.join("\n") : void 0,
+		detail
+	};
+}
+/** Print a compact result line and return its exit code. */
+function emitCompact(res) {
+	const text = formatCompact(res.result);
+	if (text) stdout.write(`${text}\n`);
+	if (res.exitCode !== 0 && !text.startsWith("error") && res.result.status === "error") stderr.write(`error ${res.result.text ?? ""}\n`);
+	return res.exitCode;
+}
+//#endregion
+//#region src/harness.ts
+/**
+* Build a `CuaAgentHarness` wired with cua-cli's defaults: pi `NodeExecutionEnv`,
+* caller-supplied jsonl `Session`, pi-coding-agent's `createCodingTools` as
+* `extraTools`, env-var API-key resolution (via cua-ai conventions), and a
+* `systemPrompt` that composes the runtime spec's default prompt with the
+* formatted skill block.
+*/
+function buildCuaHarness(opts) {
+	const skills = opts.skills ?? [];
+	const extraTools = opts.extraTools ?? createCodingTools(opts.cwd);
+	const model = opts.modelBaseUrl ? {
+		...getCuaModel(opts.model),
+		baseUrl: opts.modelBaseUrl
+	} : opts.model;
+	return new CuaAgentHarness({
+		env: new NodeExecutionEnv({ cwd: opts.cwd }),
+		session: opts.session,
+		model,
+		browser: opts.browser,
+		client: opts.client,
+		extraTools,
+		resources: { skills },
+		thinkingLevel: opts.thinkingLevel,
+		systemPrompt: ({ model: activeModel, resources }) => {
+			return composeSystemPrompt(resolveCuaRuntimeSpec(activeModel).defaultSystemPrompt, resources.skills ?? []);
+		},
+		getApiKeyAndHeaders: opts.getApiKeyAndHeaders ?? (async (resolvedModel) => {
+			const apiKey = getCuaEnvApiKey(resolvedModel.provider);
+			return apiKey ? { apiKey } : void 0;
+		})
+	});
+}
+function composeSystemPrompt(base, skills) {
+	const skillBlock = formatSkillsForSystemPrompt(skills).trim();
+	if (!skillBlock) return base;
+	return `${base.trim()}\n\n${skillBlock}\n`;
+}
+//#endregion
+//#region src/harness-named-sessions.ts
+const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+function namedSessionsDir() {
+	const xdg = process.env.XDG_DATA_HOME;
+	if (xdg) return join(xdg, "cua", "named-sessions");
+	return join(homedir(), ".local", "share", "cua", "named-sessions");
+}
+function sessionFilePath(name) {
+	return join(namedSessionsDir(), `${name}.json`);
+}
+function validateSlug(name) {
+	if (!SLUG_PATTERN.test(name)) throw new Error(`invalid session name "${name}": must match ${SLUG_PATTERN} (lowercase a-z, 0-9, hyphens; 1-63 chars; cannot start with a hyphen)`);
+}
+async function fileExists(path) {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readNamedSession(name) {
+	const path = sessionFilePath(name);
+	if (!await fileExists(path)) return void 0;
+	const raw = await readFile(path, "utf8");
+	return JSON.parse(raw);
+}
+async function writeNamedSession(meta) {
+	validateSlug(meta.name);
+	const path = sessionFilePath(meta.name);
+	await mkdir(namedSessionsDir(), { recursive: true });
+	await writeFile(path, JSON.stringify(meta, null, 2) + "\n", { mode: 384 });
+	return path;
+}
+async function deleteNamedSession(name) {
+	const path = sessionFilePath(name);
+	if (!await fileExists(path)) return false;
+	await unlink(path);
+	return true;
+}
+async function listNamedSessions() {
+	const dir = namedSessionsDir();
+	if (!await fileExists(dir)) return [];
+	const entries = await readdir(dir);
+	const out = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".json")) continue;
+		try {
+			const raw = await readFile(join(dir, entry), "utf8");
+			out.push(JSON.parse(raw));
+		} catch {}
+	}
+	out.sort((a, b) => b.created_at - a.created_at);
+	return out;
+}
+/** Provision a fresh Kernel browser and persist a named-session metadata file. */
+async function startNamedSession(opts) {
+	validateSlug(opts.name);
+	const existing = await readNamedSession(opts.name);
+	if (existing) throw new Error(`named session "${opts.name}" already exists (kernel_session_id=${existing.kernel_session_id}). Run \`cua session stop ${opts.name}\` first.`);
+	const client = createKernelClient(opts.apiKey, opts.baseUrl);
+	const timeoutSeconds = opts.browserTimeoutSeconds && opts.browserTimeoutSeconds > 0 ? opts.browserTimeoutSeconds : 300;
+	let profileId;
+	if (opts.profileSelector && opts.profileSelector.trim()) profileId = await resolveProfileId(client, opts.profileSelector);
+	const params = {
+		stealth: true,
+		timeout_seconds: timeoutSeconds
+	};
+	if (profileId) params.profile = {
+		id: profileId,
+		save_changes: opts.saveProfileChanges ?? false
+	};
+	const browser = await client.browsers.create(params);
+	const meta = {
+		name: opts.name,
+		kernel_session_id: browser.session_id,
+		live_url: browser.browser_live_view_url,
+		profile_id: profileId,
+		created_at: Date.now()
+	};
+	return {
+		meta,
+		metadataPath: await writeNamedSession(meta),
+		client,
+		browser
+	};
+}
+/**
+* Attach to a previously-started named session. Performs a liveness check
+* via `client.browsers.retrieve` so the caller can fail fast when the
+* server-side session has timed out or been deleted.
+*/
+async function attachNamedSession(opts) {
+	const meta = await readNamedSession(opts.name);
+	if (!meta) throw new Error(`unknown named session "${opts.name}". Run \`cua session list\` to see available sessions, or \`cua session start ${opts.name}\` to create one.`);
+	const client = createKernelClient(opts.apiKey, opts.baseUrl);
+	let browser;
+	try {
+		browser = await client.browsers.retrieve(meta.kernel_session_id);
+	} catch (err) {
+		if (err.status === 404) throw new Error(`named session "${opts.name}" is no longer alive on Kernel (browser timed out or was deleted). Run \`cua session stop ${opts.name} && cua session start ${opts.name}\` to provision a fresh one.`);
+		throw new Error(`liveness check for named session "${opts.name}" failed: ${err.message}`, { cause: err });
+	}
+	if (browser.deleted_at) throw new Error(`named session "${opts.name}" is no longer alive on Kernel (browser timed out or was deleted). Run \`cua session stop ${opts.name} && cua session start ${opts.name}\` to provision a fresh one.`);
+	return {
+		meta,
+		client,
+		browser
+	};
+}
+/** Tear down a named session: delete the Kernel browser and remove the metadata file. */
+async function stopNamedSession(opts) {
+	const meta = await readNamedSession(opts.name);
+	if (!meta) return {
+		existed: false,
+		kernelDeleted: false
+	};
+	const client = createKernelClient(opts.apiKey, opts.baseUrl);
+	let kernelDeleted = false;
+	try {
+		await client.browsers.deleteByID(meta.kernel_session_id);
+		kernelDeleted = true;
+	} catch (err) {
+		if (err.status !== 404) throw new Error(`failed to delete Kernel browser ${meta.kernel_session_id} for named session "${opts.name}": ${err.message}`, { cause: err });
+	}
+	await deleteNamedSession(opts.name);
+	return {
+		existed: true,
+		kernelDeleted
+	};
+}
+/** Update the persisted `transcript_path` on a named session. */
+async function recordTranscriptPath(name, transcriptPath) {
+	const meta = await readNamedSession(name);
+	if (!meta) return;
+	if (meta.transcript_path === transcriptPath) return;
+	meta.transcript_path = transcriptPath;
+	await writeNamedSession(meta);
+}
+function shortKernelId(id) {
+	return id.length > 10 ? `${id.slice(0, 8)}…` : id;
+}
+function formatRelativeAge(createdAt) {
+	const diff = Date.now() - createdAt;
+	const sec = Math.max(0, Math.floor(diff / 1e3));
+	if (sec < 60) return `${sec}s`;
+	const min = Math.floor(sec / 60);
+	if (min < 60) return `${min}m`;
+	const hr = Math.floor(min / 60);
+	if (hr < 24) return `${hr}h`;
+	return `${Math.floor(hr / 24)}d`;
+}
+//#endregion
+//#region src/harness-sessions.ts
+/**
+* Resolve the default sessions directory: `$XDG_DATA_HOME/cua/sessions`
+* (or `~/.local/share/cua/sessions`).
+*/
+function defaultSessionsRoot() {
+	const xdg = process.env.XDG_DATA_HOME;
+	if (xdg) return join(xdg, "cua", "sessions");
+	return join(homedir(), ".local", "share", "cua", "sessions");
+}
+/** Build a `JsonlSessionRepo` rooted at the resolved sessions directory. */
+function createSessionRepo(sessionsRoot) {
+	const root = sessionsRoot ?? defaultSessionsRoot();
+	return new JsonlSessionRepo({
+		fs: new NodeExecutionEnv({ cwd: process.cwd() }),
+		sessionsRoot: root
+	});
+}
+/** List sessions for a cwd; legacy / malformed files are skipped. */
+async function listSessionsForCwd(repo, cwd) {
+	return await repo.list({ cwd });
+}
+/**
+* Find the most recent session metadata for cwd. The pi `JsonlSessionRepo`
+* already orders by `createdAt` descending, but legacy `-c` semantics
+* resumed by last *modified* time so a session that was reopened and
+* appended to comes back first. We stat each file and prefer the newest
+* mtime; results that fail to stat fall back to `createdAt`.
+*/
+async function findLatestSession(repo, cwd) {
+	const sessions = await listSessionsForCwd(repo, cwd);
+	if (sessions.length === 0) return void 0;
+	const ranked = await Promise.all(sessions.map(async (meta) => {
+		try {
+			return {
+				meta,
+				mtime: (await stat(meta.path)).mtimeMs
+			};
+		} catch {
+			return {
+				meta,
+				mtime: NaN
+			};
+		}
+	}));
+	ranked.sort((a, b) => {
+		const am = Number.isFinite(a.mtime) ? a.mtime : -Infinity;
+		const bm = Number.isFinite(b.mtime) ? b.mtime : -Infinity;
+		if (am !== bm) return bm - am;
+		return b.meta.createdAt.localeCompare(a.meta.createdAt);
+	});
+	return ranked[0]?.meta;
+}
+/**
+* Resolve a `--session <ref>` argument. Accepts:
+*   - an absolute or relative path to an existing session file
+*   - `latest` for the most recent session for cwd
+*   - any other string as a prefix matched against session ids
+*/
+async function resolveSessionRef(repo, cwd, ref) {
+	const trimmed = ref.trim();
+	if (!trimmed) throw new Error("session reference is empty");
+	if (trimmed.includes("/") || trimmed.endsWith(".jsonl")) {
+		const absolute = isAbsolute(trimmed) ? trimmed : resolve(cwd, trimmed);
+		const direct = await readMetadataFromFile(absolute);
+		if (direct) return direct;
+		const match = (await repo.list()).find((m) => m.path === absolute);
+		if (match) return match;
+		throw new Error(`no session at "${trimmed}"`);
+	}
+	if (trimmed === "latest") {
+		const latest = await findLatestSession(repo, cwd);
+		if (!latest) throw new Error("no sessions found");
+		return latest;
+	}
+	const matches = (await listSessionsForCwd(repo, cwd)).filter((s) => s.id.startsWith(trimmed));
+	if (matches.length === 0) throw new Error(`no session matches "${trimmed}"`);
+	if (matches.length > 1) throw new Error(`ambiguous session prefix "${trimmed}" (${matches.length} matches)`);
+	return matches[0];
+}
+/**
+* Load the header line of a jsonl session file from disk and return its
+* metadata, or undefined when the file is missing/empty/legacy. Used to
+* resolve `--session <path>` and named transcript_path entries that may
+* have been created from a different cwd (so the repo's per-cwd listing
+* wouldn't see them).
+*/
+async function readMetadataFromFile(absolutePath) {
+	try {
+		const firstLine = (await readFile(absolutePath, "utf8")).split("\n", 1)[0]?.trim();
+		if (!firstLine) return void 0;
+		const header = JSON.parse(firstLine);
+		if (header.type !== "session") return void 0;
+		if (typeof header.id !== "string" || typeof header.timestamp !== "string" || typeof header.cwd !== "string") return;
+		return {
+			id: header.id,
+			createdAt: header.timestamp,
+			cwd: header.cwd,
+			path: absolutePath,
+			...typeof header.parentSession === "string" ? { parentSessionPath: header.parentSession } : {}
+		};
+	} catch {
+		return;
+	}
+}
+/** Open (resume) a session by metadata. */
+function openSession(repo, metadata) {
+	return repo.open(metadata);
+}
+/** Create a brand-new session for cwd. */
+function createSession(repo, cwd) {
+	return repo.create({ cwd });
+}
+/** Custom entry type used to record the Kernel browser the session ran against. */
+const CUA_BROWSER_ENTRY = "cua-browser";
+/** Append a browser-metadata custom entry to the session. */
+async function appendBrowserEntry(session, data) {
+	try {
+		await session.appendCustomEntry(CUA_BROWSER_ENTRY, data);
+	} catch {}
+}
+//#endregion
+//#region src/harness-skills.ts
+/**
+* Discover skills following the cross-agent `~/.agents/skills/` standard.
+*
+* Discovery order: explicit `--skill` paths, then `~/.agents/skills/`,
+* then `<cwd>/.agents/skills/`. Missing paths are skipped silently.
+*/
+async function discoverCuaSkills(opts) {
+	if (opts.disabled) return {
+		skills: [],
+		sources: [],
+		diagnostics: []
+	};
+	const extras = (opts.extraPaths ?? []).filter((p) => p && p.trim().length > 0);
+	const userAgentsDir = join(homedir(), ".agents", "skills");
+	const projectAgentsDir = join(opts.cwd, ".agents", "skills");
+	const sources = [
+		...extras,
+		userAgentsDir,
+		projectAgentsDir
+	].filter((p) => existsSync(p));
+	if (sources.length === 0) return {
+		skills: [],
+		sources: [],
+		diagnostics: []
+	};
+	const result = await loadSkills(opts.env, sources);
+	return {
+		skills: result.skills,
+		sources,
+		diagnostics: result.diagnostics
+	};
+}
+/**
+* Resolve a `/skill:<name>` invocation. Returns the matched skill (so the
+* caller can use `harness.skill(name)`) plus any remainder text the user
+* typed after the skill name, which the caller can append as an additional
+* instruction.
+*/
+function parseSkillInvocation(text, skills) {
+	const match = text.trim().match(/^\/skill:([A-Za-z0-9_\-.]+)\s*(.*)$/);
+	if (!match) return void 0;
+	const [, name, rest] = match;
+	return {
+		skill: skills.find((s) => s.name === name),
+		remainder: (rest ?? "").trim()
+	};
+}
+/**
+* Subscribe to a harness and emit one JSON object per line for downstream
+* tooling. The event schema mirrors the legacy `output/jsonl.ts`: only the
+* source of each field changes.
+*/
+function attachHarnessJsonlSink(opts) {
+	const write = opts.write ?? ((line) => process.stdout.write(line + "\n"));
+	const emit = (obj) => {
+		try {
+			write(JSON.stringify(obj));
+		} catch {
+			write(JSON.stringify({
+				type: "error",
+				code: "serialize_failed",
+				message: "could not serialize event",
+				ts: Date.now()
+			}));
+		}
+	};
+	emit({
+		type: "session_created",
+		schema_version: 1,
+		model: opts.modelRef,
+		provider: opts.provider,
+		ts: Date.now()
+	});
+	emit({
+		type: "browser_created",
+		browser_session_id: opts.browser.session_id,
+		live_url: opts.browser.browser_live_view_url,
+		...opts.profileId ? { profile_id: opts.profileId } : {},
+		ts: Date.now()
+	});
+	let turn = 0;
+	const includeDeltas = opts.includeDeltas === true;
+	const includeImages = opts.includeImages === true;
+	return opts.harness.subscribe((event) => {
+		switch (event.type) {
+			case "turn_start":
+				turn += 1;
+				return;
+			case "turn_end":
+				emit({
+					type: "turn_done",
+					turn,
+					ts: Date.now()
+				});
+				return;
+			case "agent_end":
+				emit({
+					type: "run_complete",
+					turns: turn,
+					ts: Date.now()
+				});
+				return;
+			case "message_end": {
+				const msg = event.message;
+				if (msg.role === "user") emit({
+					type: "user_message",
+					text: textOf(msg.content),
+					ts: Date.now()
+				});
+				else if (msg.role === "assistant") {
+					const text = textOf(msg.content);
+					if (text) emit({
+						type: "assistant_text_done",
+						text,
+						ts: Date.now()
+					});
+				}
+				return;
+			}
+			case "message_update":
+				if (!includeDeltas) return;
+				if (event.assistantMessageEvent.type === "text_delta") emit({
+					type: "assistant_text_delta",
+					delta: event.assistantMessageEvent.delta,
+					ts: Date.now()
+				});
+				return;
+			case "tool_execution_start":
+				emit({
+					type: "tool_call",
+					tool_name: event.toolName,
+					call_id: event.toolCallId,
+					args: event.args,
+					ts: Date.now()
+				});
+				return;
+			case "tool_execution_end": {
+				const result = event.result;
+				const ok = !event.isError;
+				let contentText;
+				let screenshotBytes;
+				const screenshotsB64 = [];
+				if (result?.content) {
+					const textParts = [];
+					for (const c of result.content) {
+						if (c?.type === "text" && typeof c.text === "string") textParts.push(c.text);
+						if (c?.type === "image" && typeof c.data === "string") {
+							const len = c.data.length;
+							screenshotBytes = (screenshotBytes ?? 0) + len;
+							if (includeImages) screenshotsB64.push(c.data);
+						}
+					}
+					contentText = textParts.join("\n").trim() || void 0;
+				}
+				emit({
+					type: "tool_result",
+					tool_name: event.toolName,
+					call_id: event.toolCallId,
+					ok,
+					content_text: contentText,
+					screenshot_bytes: screenshotBytes,
+					...includeImages && screenshotsB64.length ? { screenshots_b64: screenshotsB64 } : {},
+					details: result?.details,
+					ts: Date.now()
+				});
+				return;
+			}
+			default: return;
+		}
+	});
+}
+function textOf(content) {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts = [];
+	for (const c of content) if (c && typeof c === "object" && c.type === "text" && typeof c.text === "string") parts.push(c.text);
+	return parts.join("\n");
+}
+//#endregion
+//#region src/print.ts
+/**
+* Run a single prompt through the harness and stream output to stdout
+* (text mode) or as jsonl events. Returns the process exit code (0 ok,
+* 1 on failure).
+*/
+async function runPrint(opts) {
+	const jsonlMode = opts.jsonlMode === true;
+	let unsubscribeJsonl;
+	if (jsonlMode) unsubscribeJsonl = attachHarnessJsonlSink({
+		harness: opts.harness,
+		browser: opts.browserHandle.browser,
+		profileId: opts.browserHandle.profileId,
+		modelRef: opts.modelRef,
+		provider: opts.provider,
+		includeDeltas: opts.jsonlIncludeDeltas,
+		includeImages: opts.jsonlIncludeImages
+	});
+	const unsubscribeText = opts.harness.subscribe((event) => {
+		if (jsonlMode) return;
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			stdout.write(event.assistantMessageEvent.delta);
+			return;
+		}
+		if (opts.verbose && event.type === "tool_execution_start") stderr.write(`\n[cua] tool ${event.toolName} ${JSON.stringify(event.args)}\n`);
+		if (opts.verbose && event.type === "tool_execution_end") stderr.write(`[cua] tool ${event.toolName} done\n`);
+	});
+	let exitCode = 0;
+	try {
+		const invocation = parseSkillInvocation(opts.prompt, opts.skills ?? []);
+		let assistant;
+		if (invocation?.skill) {
+			if (opts.verbose) stderr.write(`[cua] expanded /skill:${invocation.skill.name}\n`);
+			assistant = await opts.harness.skill(invocation.skill.name, invocation.remainder || void 0);
+		} else {
+			const images = await maybeInitialScreenshot(opts);
+			assistant = await opts.harness.prompt(opts.prompt, images ? { images } : void 0);
+		}
+		if (assistant.stopReason === "error" || assistant.stopReason === "aborted") throw new Error(assistant.errorMessage ?? `agent stopped with ${assistant.stopReason}`);
+		if (!jsonlMode) stdout.write("\n");
+	} catch (err) {
+		if (jsonlMode) stdout.write(JSON.stringify({
+			type: "error",
+			code: "run_failed",
+			message: err.message,
+			ts: Date.now()
+		}) + "\n");
+		else stderr.write(`\n[cua] error: ${err.message}\n`);
+		exitCode = 1;
+	} finally {
+		unsubscribeText();
+		unsubscribeJsonl?.();
+	}
+	return exitCode;
+}
+async function maybeInitialScreenshot(opts) {
+	if (opts.skipInitialScreenshot) return void 0;
+	if (await sessionHasPriorTurn(opts.session)) return void 0;
+	const png = await captureScreenshot(opts.browserHandle.client, opts.browserHandle.browser.session_id);
+	if (!png) return void 0;
+	return [{
+		type: "image",
+		data: png.toString("base64"),
+		mimeType: "image/png"
+	}];
+}
+async function sessionHasPriorTurn(session) {
+	const entries = await session.getBranch();
+	for (const entry of entries) if (entry.type === "message" && (entry.message.role === "user" || entry.message.role === "assistant")) return true;
+	return false;
+}
+//#endregion
+//#region src/cli-harness.ts
+const MODELS_HELP = `cua models — list supported -m/--model values
+
+Usage:
+  cua models
+  cua models -p openai
+  cua models --provider anthropic
+  cua models --json
+
+Options:
+  -p, --provider <id>  Filter by provider: openai | anthropic | google | gemini | tzafon | yutori
+      --json           Output JSON
+  -h, --help           Show this help
+`;
+function parseModelsArgs(argv) {
+	const parsed = parseArgs({
+		args: argv,
+		options: {
+			provider: {
+				type: "string",
+				short: "p"
+			},
+			json: {
+				type: "boolean",
+				default: false
+			},
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			}
+		},
+		allowPositionals: true,
+		strict: true
+	});
+	const positionalProvider = parsed.positionals[0];
+	if (parsed.positionals.length > 1) throw new Error(`unexpected arguments: ${parsed.positionals.slice(1).join(" ")}`);
+	return {
+		provider: parsed.values.provider ?? positionalProvider,
+		json: !!parsed.values.json,
+		help: !!parsed.values.help
+	};
+}
+/** `cua models` subcommand backed by cua-ai's `listCuaModels()`. */
+async function runModelsSubcommand(argv) {
+	let flags;
+	try {
+		flags = parseModelsArgs(argv);
+	} catch (err) {
+		stderr.write(`${err.message}\n\n${MODELS_HELP}`);
+		return 2;
+	}
+	if (flags.help) {
+		stdout.write(MODELS_HELP);
+		return 0;
+	}
+	let models;
+	try {
+		models = listSupportedModels(flags.provider);
+	} catch (err) {
+		stderr.write(`${err.message}\n`);
+		return 2;
+	}
+	if (flags.json) {
+		stdout.write(`${JSON.stringify(models, null, 2)}\n`);
+		return 0;
+	}
+	stdout.write(formatModelsTable(models));
+	return 0;
+}
+function formatModelsTable(models) {
+	const rows = models.map((entry) => ({
+		ref: entry.ref,
+		provider: entry.provider,
+		model: entry.model,
+		default: entry.ref === "openai:gpt-5.5" ? "yes" : "",
+		name: entry.name
+	}));
+	const headers = {
+		ref: "REF",
+		provider: "PROVIDER",
+		model: "MODEL",
+		default: "DEFAULT",
+		name: "NAME"
+	};
+	const widths = {
+		ref: columnWidth(headers.ref, rows.map((r) => r.ref)),
+		provider: columnWidth(headers.provider, rows.map((r) => r.provider)),
+		model: columnWidth(headers.model, rows.map((r) => r.model)),
+		default: columnWidth(headers.default, rows.map((r) => r.default)),
+		name: columnWidth(headers.name, rows.map((r) => r.name))
+	};
+	const lines = [[
+		headers.ref.padEnd(widths.ref),
+		headers.provider.padEnd(widths.provider),
+		headers.model.padEnd(widths.model),
+		headers.default.padEnd(widths.default),
+		headers.name
+	].join("  "), [
+		"-".repeat(widths.ref),
+		"-".repeat(widths.provider),
+		"-".repeat(widths.model),
+		"-".repeat(widths.default),
+		"-".repeat(widths.name)
+	].join("  ")];
+	for (const row of rows) lines.push([
+		row.ref.padEnd(widths.ref),
+		row.provider.padEnd(widths.provider),
+		row.model.padEnd(widths.model),
+		row.default.padEnd(widths.default),
+		row.name
+	].join("  "));
+	return `${lines.join("\n")}\n`;
+}
+function columnWidth(header, values) {
+	return Math.max(header.length, ...values.map((value) => value.length));
+}
+function requireKernelApiKey() {
+	const apiKey = process.env.KERNEL_API_KEY?.trim();
+	if (!apiKey) throw new Error("missing Kernel API key (set KERNEL_API_KEY)");
+	return {
+		apiKey,
+		baseUrl: process.env.KERNEL_BASE_URL?.trim() || void 0
+	};
+}
+function resolveAuth(flags) {
+	const { apiKey, baseUrl } = requireKernelApiKey();
+	const modelRef = resolveCuaModelRef(flags.model);
+	const { provider } = parseCuaModelRef(modelRef);
+	requireCuaEnvApiKey(provider);
+	return {
+		kernelApiKey: apiKey,
+		kernelBaseUrl: baseUrl,
+		modelRef
+	};
+}
+async function provisionForFlags(flags, auth) {
+	if (flags.namedSession) {
+		const { client, browser, meta } = await attachNamedSession({
+			name: flags.namedSession,
+			apiKey: auth.kernelApiKey,
+			baseUrl: auth.kernelBaseUrl
+		});
+		if (flags.verbose) {
+			stderr.write(`[cua] attached named session "${meta.name}" (browser=${browser.session_id})\n`);
+			if (browser.browser_live_view_url) stderr.write(`[cua] live view=${browser.browser_live_view_url}\n`);
+		}
+		return {
+			handle: {
+				client,
+				browser,
+				profileId: meta.profile_id,
+				async close() {}
+			},
+			named: meta
+		};
+	}
+	if (flags.verbose) stderr.write("[cua] provisioning Kernel browser...\n");
+	const handle = await provisionBrowser({
+		apiKey: auth.kernelApiKey,
+		baseUrl: auth.kernelBaseUrl,
+		timeoutSeconds: flags.browserTimeout,
+		profileSelector: flags.browserProfile,
+		saveChanges: flags.profileSaveChanges
+	});
+	if (flags.verbose) {
+		stderr.write(`[cua] browser session=${handle.browser.session_id}\n`);
+		if (handle.browser.browser_live_view_url) stderr.write(`[cua] live view=${handle.browser.browser_live_view_url}\n`);
+	}
+	return { handle };
+}
+async function resolveSession(repo, cwd, flags, namedMeta) {
+	if (flags.noSession) return void 0;
+	if (flags.sessionRef) {
+		const metadata = await resolveSessionRef(repo, cwd, flags.sessionRef);
+		return {
+			session: await openSession(repo, metadata),
+			transcriptPath: metadata.path,
+			resumed: true
+		};
+	}
+	if (flags.continueLatest) {
+		const latest = await findLatestSession(repo, cwd);
+		if (!latest) {
+			stderr.write("[cua] no previous session for this cwd; starting fresh\n");
+			const fresh = await createSession(repo, cwd);
+			return {
+				session: fresh,
+				transcriptPath: (await fresh.getMetadata()).path,
+				resumed: false
+			};
+		}
+		return {
+			session: await openSession(repo, latest),
+			transcriptPath: latest.path,
+			resumed: true
+		};
+	}
+	if (flags.resumePicker) {
+		const sessions = await listSessionsForCwd(repo, cwd);
+		if (sessions.length === 0) {
+			stderr.write("[cua] no previous sessions for this cwd; starting fresh\n");
+			const fresh = await createSession(repo, cwd);
+			return {
+				session: fresh,
+				transcriptPath: (await fresh.getMetadata()).path,
+				resumed: false
+			};
+		}
+		const picked = await pickSession(sessions);
+		if (!picked) {
+			const fresh = await createSession(repo, cwd);
+			return {
+				session: fresh,
+				transcriptPath: (await fresh.getMetadata()).path,
+				resumed: false
+			};
+		}
+		return {
+			session: await openSession(repo, picked),
+			transcriptPath: picked.path,
+			resumed: true
+		};
+	}
+	if (namedMeta?.transcript_path) {
+		const direct = await readMetadataFromFile(namedMeta.transcript_path);
+		if (direct) return {
+			session: await openSession(repo, direct),
+			transcriptPath: direct.path,
+			resumed: true
+		};
+	}
+	const fresh = await createSession(repo, cwd);
+	return {
+		session: fresh,
+		transcriptPath: (await fresh.getMetadata()).path,
+		resumed: false
+	};
+}
+async function pickSession(sessions) {
+	const sorted = [...sessions].sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+	stderr.write("\nResume which session?\n");
+	const limit = Math.min(sorted.length, 20);
+	for (let i = 0; i < limit; i++) {
+		const s = sorted[i];
+		stderr.write(`  [${i + 1}] ${s.id.slice(0, 8)} · ${s.createdAt}\n`);
+	}
+	if (sorted.length > limit) stderr.write(`  (${sorted.length - limit} more not shown; use --session <prefix> to select directly)\n`);
+	const { createInterface } = await import("node:readline/promises");
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		const answer = (await rl.question("Pick a number (or blank to skip): ")).trim();
+		if (!answer) return void 0;
+		const n = Number(answer);
+		if (!Number.isFinite(n) || n < 1 || n > limit) {
+			stderr.write("[cua] invalid selection; starting fresh\n");
+			return;
+		}
+		return sorted[n - 1];
+	} finally {
+		rl.close();
+	}
+}
+async function setupHarnessRuntime(flags, opts = {}) {
+	const auth = resolveAuth(flags);
+	const cwd = process.cwd();
+	const { skills } = await discoverCuaSkills({
+		cwd,
+		env: new NodeExecutionEnv({ cwd }),
+		extraPaths: flags.skillPaths,
+		disabled: flags.noSkills
+	});
+	const provisioned = await provisionForFlags(flags, auth);
+	const repo = createSessionRepo(flags.sessionDir);
+	const resolved = opts.skipDiskSession === true && !hasExplicitSessionFlag(flags) ? void 0 : await resolveSession(repo, cwd, flags, provisioned.named);
+	let inMemorySession;
+	if (!resolved) inMemorySession = await new InMemorySessionRepo().create();
+	const session = resolved?.session ?? inMemorySession;
+	const { provider } = parseCuaModelRef(auth.modelRef);
+	if (resolved) {
+		await appendBrowserEntry(session, {
+			sessionId: provisioned.handle.browser.session_id,
+			liveUrl: provisioned.handle.browser.browser_live_view_url,
+			profileId: provisioned.handle.profileId,
+			createdAt: Date.now()
+		});
+		if (provisioned.named) await recordTranscriptPath(provisioned.named.name, resolved.transcriptPath);
+		if (flags.verbose) {
+			stderr.write(`[cua] session=${resolved.transcriptPath}\n`);
+			if (resolved.resumed) stderr.write("[cua] resumed prior session into fresh browser\n");
+		}
+	}
+	const thinkingLevel = mapThinkingLevel(flags.thinking);
+	const baseUrlOverride = providerBaseUrlOverride(provider);
+	const harness = buildCuaHarness({
+		cwd,
+		client: provisioned.handle.client,
+		browser: provisioned.handle.browser,
+		session,
+		model: auth.modelRef,
+		skills,
+		thinkingLevel,
+		modelBaseUrl: baseUrlOverride
+	});
+	return {
+		handle: provisioned.handle,
+		resolved,
+		session,
+		skills,
+		harness,
+		provider,
+		modelRef: auth.modelRef
+	};
+}
+function hasExplicitSessionFlag(flags) {
+	return !!flags.sessionRef || flags.continueLatest || flags.resumePicker || !!flags.namedSession;
+}
+function providerBaseUrlOverride(provider) {
+	const envName = `${provider.toUpperCase()}_BASE_URL`;
+	const value = process.env[envName]?.trim();
+	return value && value.length > 0 ? value : void 0;
+}
+function mapThinkingLevel(raw) {
+	switch ((raw ?? "low").trim().toLowerCase()) {
+		case "off":
+		case "none": return "off";
+		case "minimal": return "minimal";
+		case "medium": return "medium";
+		case "high": return "high";
+		case "xhigh": return "xhigh";
+		case "low":
+		case "": return "low";
+		default: throw new Error(`invalid --thinking value "${raw}"; expected one of: off | minimal | low | medium | high | xhigh`);
+	}
+}
+/** Run a single prompt through the new harness wiring (`--print`). */
+async function runPrintCommand(prompt, flags) {
+	const runtime = await setupHarnessRuntime(flags);
+	const jsonlMode = (flags.output ?? "text").toLowerCase() === "jsonl";
+	try {
+		return await runPrint({
+			harness: runtime.harness,
+			browserHandle: runtime.handle,
+			session: runtime.session,
+			modelRef: runtime.modelRef,
+			provider: runtime.provider,
+			prompt,
+			skills: runtime.skills,
+			skipInitialScreenshot: runtime.resolved?.resumed === true,
+			verbose: flags.verbose,
+			jsonlMode,
+			jsonlIncludeDeltas: flags.jsonlIncludeDeltas,
+			jsonlIncludeImages: flags.jsonlIncludeImages
+		});
+	} finally {
+		try {
+			await runtime.handle.close();
+		} catch (err) {
+			stderr.write(`[cua] cleanup warning: ${err.message}\n`);
+		}
+	}
+}
+/** Run the interactive TUI through the new harness wiring. */
+async function runInteractiveCommand(initialPrompt, flags) {
+	const runtime = await setupHarnessRuntime(flags);
+	const { runInteractive } = await import("./main-Bphx_zOj.js");
+	try {
+		return await runInteractive({
+			cwd: process.cwd(),
+			harness: runtime.harness,
+			browserHandle: runtime.handle,
+			session: runtime.session,
+			skills: runtime.skills,
+			modelRef: runtime.modelRef,
+			provider: runtime.provider,
+			initialPrompt: initialPrompt || void 0,
+			imageProtocol: flags.imageProtocol,
+			debugTui: flags.debugTui,
+			resumed: runtime.resolved?.resumed === true,
+			transcriptPath: runtime.resolved?.transcriptPath,
+			skipInitialScreenshot: runtime.resolved?.resumed === true
+		});
+	} finally {
+		try {
+			await runtime.handle.close();
+		} catch (err) {
+			stderr.write(`[cua] cleanup warning: ${err.message}\n`);
+		}
+	}
+}
+/** Run a one-shot action subcommand through the new harness wiring. */
+async function runActionCommand(action, rest, flags) {
+	const runtime = await setupHarnessRuntime(flags, { skipDiskSession: true });
+	const req = buildActionRequest(action, rest);
+	if (flags.maxSteps !== void 0) req.maxTurns = flags.maxSteps;
+	const screenshotOut = flags.out ? { out: flags.out } : action === "screenshot" ? { out: "screenshot.png" } : void 0;
+	try {
+		return emitCompact(await runAction(req, {
+			harness: runtime.harness,
+			browserHandle: runtime.handle,
+			session: runtime.session,
+			skipInitialScreenshot: runtime.resolved?.resumed === true
+		}, screenshotOut));
+	} finally {
+		try {
+			await runtime.handle.close();
+		} catch (err) {
+			stderr.write(`[cua] cleanup warning: ${err.message}\n`);
+		}
+	}
+}
+function buildActionRequest(action, rest) {
+	switch (action) {
+		case "open": return {
+			action,
+			text: rest[0]
+		};
+		case "click": return {
+			action,
+			target: rest.join(" ")
+		};
+		case "type": return {
+			action,
+			target: rest[0],
+			text: rest[1]
+		};
+		case "press": return {
+			action,
+			keys: rest
+		};
+		case "observe": return {
+			action,
+			text: rest.join(" ")
+		};
+		case "url": return { action };
+		case "screenshot": return { action };
+		case "do": return {
+			action,
+			text: rest.join(" ")
+		};
+	}
+}
+/** Named-session subcommand handlers wired to the new SDK-backed implementation. */
+async function runSessionSubcommand(args, flags) {
+	const sub = args[0];
+	if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+		stdout.write(`${sessionHelp()}\n`);
+		return 0;
+	}
+	const auth = resolveAuthOrFail();
+	switch (sub) {
+		case "start": {
+			const name = (args[1] ?? "").trim() || generateSessionSlug();
+			validateSlug(name);
+			const { meta, metadataPath, browser } = await startNamedSession({
+				name,
+				apiKey: auth.kernelApiKey,
+				baseUrl: auth.kernelBaseUrl,
+				browserTimeoutSeconds: flags.browserTimeout,
+				profileSelector: flags.browserProfile,
+				saveProfileChanges: flags.profileSaveChanges
+			});
+			stdout.write(`name=${meta.name}\n`);
+			stdout.write(`kernel_session_id=${browser.session_id}\n`);
+			if (browser.browser_live_view_url) stdout.write(`live_url=${browser.browser_live_view_url}\n`);
+			stdout.write(`metadata=${metadataPath}\n`);
+			stdout.write(`\nUse: cua -s ${meta.name} <subcommand>...\n`);
+			return 0;
+		}
+		case "stop": {
+			const name = (args[1] ?? "").trim();
+			if (!name) {
+				stderr.write("usage: cua session stop <name>\n");
+				return 2;
+			}
+			validateSlug(name);
+			const result = await stopNamedSession({
+				name,
+				apiKey: auth.kernelApiKey,
+				baseUrl: auth.kernelBaseUrl
+			});
+			if (!result.existed) {
+				stderr.write(`no named session "${name}"\n`);
+				return 1;
+			}
+			stdout.write(result.kernelDeleted ? `stopped ${name} (kernel browser deleted)\n` : `stopped ${name} (kernel browser was already gone)\n`);
+			return 0;
+		}
+		case "list": {
+			const sessions = await listNamedSessions();
+			if (sessions.length === 0) {
+				stdout.write("(no named sessions; run `cua session start [name]`)\n");
+				return 0;
+			}
+			const header = [
+				"NAME",
+				"KERNEL_ID",
+				"AGE",
+				"LIVE_URL"
+			].join("	");
+			stdout.write(`${header}\n`);
+			for (const s of sessions) stdout.write([
+				s.name,
+				shortKernelId(s.kernel_session_id),
+				formatRelativeAge(s.created_at),
+				s.live_url ?? "-"
+			].join("	") + "\n");
+			return 0;
+		}
+		case "show": {
+			const name = (args[1] ?? "").trim();
+			if (!name) {
+				stderr.write("usage: cua session show <name>\n");
+				return 2;
+			}
+			validateSlug(name);
+			const meta = (await listNamedSessions()).find((s) => s.name === name);
+			if (!meta) {
+				stderr.write(`no named session "${name}"\n`);
+				return 1;
+			}
+			stdout.write(`${JSON.stringify(meta, null, 2)}\n`);
+			return 0;
+		}
+		default:
+			stderr.write(`unknown session subcommand: ${sub}\n${sessionHelp()}\n`);
+			return 2;
+	}
+}
+function resolveAuthOrFail() {
+	const { apiKey, baseUrl } = requireKernelApiKey();
+	return {
+		kernelApiKey: apiKey,
+		kernelBaseUrl: baseUrl
+	};
+}
+function generateSessionSlug() {
+	const adjectives = [
+		"calm",
+		"brisk",
+		"swift",
+		"quiet",
+		"bright",
+		"sharp"
+	];
+	const nouns = [
+		"fox",
+		"owl",
+		"lynx",
+		"hawk",
+		"wolf",
+		"moth"
+	];
+	return `${adjectives[Math.floor(Math.random() * adjectives.length)] ?? "calm"}-${nouns[Math.floor(Math.random() * nouns.length)] ?? "fox"}-${Date.now().toString(36).slice(-4)}`;
+}
+function sessionHelp() {
+	return [
+		"cua session start [name]   Start a new named browser session.",
+		"cua session stop  <name>   Tear down a named session.",
+		"cua session list           List existing named sessions.",
+		"cua session show  <name>   Print full metadata for a named session.",
+		"",
+		"Use `-s <name>` on any other command to reuse the named session's",
+		"browser (e.g. `cua -s login open https://...`)."
+	].join("\n");
+}
+//#endregion
+//#region src/cli.ts
+const HELP = `cua — Kernel-cloud-browser computer-use agent
+
+Usage:
+  cua [options] [prompt...]
+  cua --print "go to news.ycombinator.com and summarize"
+  cua open <url>
+  cua click "<description>"
+  cua type "<target>" "<text>"
+  cua press <key> [key...]
+  cua observe ["<question>"]
+  cua url
+  cua screenshot [--out file|-]
+  cua do "<instruction>"
+  cua models [-p provider]
+  cua session start [name] | stop <name> | list | show <name>
+
+Options:
+  -p, --print                    Run a single prompt and exit
+  -m, --model <ref>              Model ref (default: ${DEFAULT_CUA_MODEL_REF})
+                                 Accepts \`provider:model\` refs or bare ids that
+                                 match exactly one entry in \`cua models\`.
+                                 Recommended:
+                                   openai:    openai:gpt-5.5
+                                   anthropic: anthropic:claude-opus-4-7
+                                   google:    google:gemini-3-flash-preview
+                                   tzafon:    tzafon:tzafon.northstar-cua-fast
+                                   yutori:    yutori:n1.5-latest
+      --thinking <level>         Thinking level: off | minimal | low | medium | high | xhigh
+                                 (default: low; applies to providers that support it)
+      --profile <name|id>        Kernel browser profile to load
+      --profile-no-save-changes  Do not persist changes back to the profile
+      --browser-timeout <s>      Browser inactivity timeout in seconds (default 300)
+      --max-steps <n>            Max turns for action subcommands (default 3)
+      --out <file|->             Output file for screenshot subcommand
+  -o, --output <fmt>             Output format for --print: text (default) | jsonl
+      --jsonl-include-deltas     Include assistant_text_delta events (default off)
+      --jsonl-include-images     Include base64 screenshots (default off, only sizes)
+      --image-protocol <p>       Force terminal image protocol: \`kitty\` | \`iterm2\` | \`none\` | \`auto\`
+                                 (Ghostty / WezTerm are auto-detected as \`kitty\`.)
+                                 Also via CUA_IMAGE_PROTOCOL env var.
+  -s, --session-name <name>      Reuse a named browser session (see \`cua session start\`)
+  -c, --continue                 Resume the most recent session for cwd (fresh browser)
+  -r, --resume                   Pick a previous session to resume from a list
+      --session <ref>            Resume a specific session: path | partial id | latest
+      --session-dir <dir>        Override the sessions directory
+      --no-session               Don't persist this session to disk
+      --skill <path>             Load a skill file or directory (repeatable).
+                                 Defaults: ~/.agents/skills/, <cwd>/.agents/skills/
+  -ns, --no-skills               Disable skill discovery entirely
+      --debug-tui                Enable TUI render diagnostics for manual repros
+  -v, --verbose                  Verbose progress output to stderr
+  -h, --help                     Show this help
+
+Environment:
+  KERNEL_API_KEY        Kernel API key (required)
+  OPENAI_API_KEY        OpenAI API key (required when -m openai:…)
+  ANTHROPIC_API_KEY     Anthropic API key (required when -m anthropic:…)
+  GOOGLE_API_KEY        Google API key (required when -m google:…)
+  GEMINI_API_KEY        Alias for GOOGLE_API_KEY
+  TZAFON_API_KEY        Tzafon API key (required when -m tzafon:…)
+  YUTORI_API_KEY        Yutori API key (required when -m yutori:…)
+  KERNEL_BASE_URL       Override Kernel base URL
+  OPENAI_BASE_URL       Override OpenAI base URL
+  ANTHROPIC_BASE_URL    Override Anthropic base URL
+  GOOGLE_BASE_URL       Override Google base URL
+  TZAFON_BASE_URL       Override Tzafon base URL
+  YUTORI_BASE_URL       Override Yutori base URL
+  XDG_DATA_HOME         Sessions are stored under \$XDG_DATA_HOME/cua/sessions
+                        (defaults to ~/.local/share/cua/sessions)
+  CUA_IMAGE_PROTOCOL    Force inline image protocol (\`kitty\`|\`iterm2\`|\`none\`|\`auto\`)
+`;
+function parseCliArgs(argv) {
+	const preprocessed = argv.map((arg) => arg === "-ns" ? "--no-skills" : arg);
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: preprocessed,
+			options: {
+				help: {
+					type: "boolean",
+					short: "h",
+					default: false
+				},
+				print: {
+					type: "boolean",
+					short: "p",
+					default: false
+				},
+				verbose: {
+					type: "boolean",
+					short: "v",
+					default: false
+				},
+				model: {
+					type: "string",
+					short: "m"
+				},
+				thinking: { type: "string" },
+				profile: { type: "string" },
+				"profile-no-save-changes": {
+					type: "boolean",
+					default: false
+				},
+				"browser-timeout": { type: "string" },
+				"max-steps": { type: "string" },
+				out: { type: "string" },
+				"image-protocol": { type: "string" },
+				"session-name": {
+					type: "string",
+					short: "s"
+				},
+				continue: {
+					type: "boolean",
+					short: "c",
+					default: false
+				},
+				resume: {
+					type: "boolean",
+					short: "r",
+					default: false
+				},
+				session: { type: "string" },
+				"session-dir": { type: "string" },
+				"no-session": {
+					type: "boolean",
+					default: false
+				},
+				skill: {
+					type: "string",
+					multiple: true,
+					default: []
+				},
+				"no-skills": {
+					type: "boolean",
+					default: false
+				},
+				"debug-tui": {
+					type: "boolean",
+					default: false
+				},
+				output: {
+					type: "string",
+					short: "o"
+				},
+				"jsonl-include-deltas": {
+					type: "boolean",
+					default: false
+				},
+				"jsonl-include-images": {
+					type: "boolean",
+					default: false
+				}
+			},
+			allowPositionals: true,
+			strict: true
+		});
+	} catch (err) {
+		throw new Error(`invalid arguments: ${err.message}`);
+	}
+	const browserTimeoutRaw = parsed.values["browser-timeout"];
+	const browserTimeout = browserTimeoutRaw ? Number(browserTimeoutRaw) : void 0;
+	const maxStepsRaw = parsed.values["max-steps"];
+	const maxSteps = maxStepsRaw ? Number(maxStepsRaw) : void 0;
+	const thinkingRaw = parsed.values.thinking;
+	if (thinkingRaw !== void 0) {
+		if (!new Set([
+			"off",
+			"none",
+			"minimal",
+			"low",
+			"medium",
+			"high",
+			"xhigh"
+		]).has(thinkingRaw.trim().toLowerCase())) throw new Error(`invalid --thinking value "${thinkingRaw}"; expected one of: off | minimal | low | medium | high | xhigh`);
+	}
+	return {
+		help: !!parsed.values.help,
+		print: !!parsed.values.print,
+		verbose: !!parsed.values.verbose,
+		profileSaveChanges: !parsed.values["profile-no-save-changes"],
+		continueLatest: !!parsed.values.continue,
+		resumePicker: !!parsed.values.resume,
+		noSession: !!parsed.values["no-session"],
+		noSkills: !!parsed.values["no-skills"],
+		debugTui: !!parsed.values["debug-tui"],
+		model: parsed.values.model,
+		thinking: parsed.values.thinking,
+		browserProfile: parsed.values.profile,
+		browserTimeout: Number.isFinite(browserTimeout) ? browserTimeout : void 0,
+		maxSteps: Number.isFinite(maxSteps) ? maxSteps : void 0,
+		out: parsed.values.out,
+		imageProtocol: parsed.values["image-protocol"],
+		namedSession: parsed.values["session-name"],
+		sessionRef: parsed.values.session,
+		sessionDir: parsed.values["session-dir"],
+		skillPaths: (parsed.values.skill ?? []).filter((p) => p && p.trim().length > 0),
+		output: parsed.values.output,
+		jsonlIncludeDeltas: !!parsed.values["jsonl-include-deltas"],
+		jsonlIncludeImages: !!parsed.values["jsonl-include-images"],
+		positionals: parsed.positionals
+	};
+}
+function toHarnessFlags(flags) {
+	return {
+		verbose: flags.verbose,
+		profileSaveChanges: flags.profileSaveChanges,
+		continueLatest: flags.continueLatest,
+		resumePicker: flags.resumePicker,
+		noSession: flags.noSession,
+		noSkills: flags.noSkills,
+		debugTui: flags.debugTui,
+		jsonlIncludeDeltas: flags.jsonlIncludeDeltas,
+		jsonlIncludeImages: flags.jsonlIncludeImages,
+		model: flags.model,
+		thinking: flags.thinking,
+		browserProfile: flags.browserProfile,
+		browserTimeout: flags.browserTimeout,
+		maxSteps: flags.maxSteps,
+		out: flags.out,
+		output: flags.output,
+		imageProtocol: flags.imageProtocol,
+		namedSession: flags.namedSession,
+		sessionRef: flags.sessionRef,
+		sessionDir: flags.sessionDir,
+		skillPaths: flags.skillPaths
+	};
+}
+const SUBCOMMANDS = new Set([
+	"open",
+	"click",
+	"type",
+	"press",
+	"observe",
+	"url",
+	"screenshot",
+	"do"
+]);
+async function main(argv) {
+	if (argv[0] === "models") return await runModelsSubcommand(argv.slice(1));
+	let flags;
+	try {
+		flags = parseCliArgs(argv);
+	} catch (err) {
+		stderr.write(`${err.message}\n\n${HELP}`);
+		return 2;
+	}
+	if (flags.help) {
+		stdout.write(HELP);
+		return 0;
+	}
+	const positionals = flags.positionals;
+	const first = positionals[0];
+	if (first === "session") try {
+		return await runSessionSubcommand(positionals.slice(1), toHarnessFlags(flags));
+	} catch (err) {
+		stderr.write(`session error: ${err.message}\n`);
+		return 2;
+	}
+	if (first && SUBCOMMANDS.has(first)) try {
+		return await runActionCommand(first, positionals.slice(1), toHarnessFlags(flags));
+	} catch (err) {
+		stderr.write(`error: ${err.message}\n`);
+		return 2;
+	}
+	const prompt = positionals.join(" ").trim();
+	if (flags.print) {
+		if (!prompt) {
+			stderr.write("error: --print requires a prompt\n");
+			return 2;
+		}
+		try {
+			return await runPrintCommand(prompt, toHarnessFlags(flags));
+		} catch (err) {
+			stderr.write(`error: ${err.message}\n`);
+			return 1;
+		}
+	}
+	try {
+		return await runInteractiveCommand(prompt, toHarnessFlags(flags));
+	} catch (err) {
+		stderr.write(`error: ${err.message}\n`);
+		return 1;
+	}
+}
+main(process.argv.slice(2)).then((code) => {
+	process.exit(code);
+}, (err) => {
+	stderr.write(`fatal: ${err.message}\n`);
+	process.exit(1);
+});
+//#endregion
+export { main };