@onkernel/cua-agent 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,5 +1,752 @@
+import { Agent, AgentHarness } from "@earendil-works/pi-agent-core";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
+import { CUA_NAVIGATION_TOOL_NAME, createCuaNavigationToolDefinition, getCuaEnvApiKey, normalizeGotoUrl, resolveCuaRuntimeSpec, streamSimple } from "@onkernel/cua-ai";
+import sharp from "sharp";
 export * from "@earendil-works/pi-agent-core";
-export { createCuaComputerTools } from "./tools";
-export { SUPPORTED_CUA_EXECUTOR_TOOL_NAMES } from "./tools";
-export { CuaAgent, CuaHarness } from "./agent";
-//# sourceMappingURL=index.js.map
+//#region src/translator/keys.ts
+const KERNEL_MODIFIER_KEYSYMS = [
+	"Control_L",
+	"Alt_L",
+	"Shift_L",
+	"Super_L"
+];
+const KEY_ALIASES = {
+	alt: "Alt_L",
+	alt_l: "Alt_L",
+	altleft: "Alt_L",
+	backspace: "BackSpace",
+	backquote: "grave",
+	backslash: "backslash",
+	bracketleft: "bracketleft",
+	bracketright: "bracketright",
+	capslock: "Caps_Lock",
+	cmd: "Super_L",
+	comma: "comma",
+	command: "Super_L",
+	control: "Control_L",
+	control_l: "Control_L",
+	controlleft: "Control_L",
+	ctrl: "Control_L",
+	delete: "Delete",
+	down: "Down",
+	end: "End",
+	enter: "Return",
+	equal: "equal",
+	esc: "Escape",
+	escape: "Escape",
+	home: "Home",
+	insert: "Insert",
+	kp_enter: "Return",
+	left: "Left",
+	meta: "Super_L",
+	minus: "minus",
+	numlock: "Num_Lock",
+	option: "Alt_L",
+	pagedown: "Next",
+	page_down: "Next",
+	pageup: "Prior",
+	page_up: "Prior",
+	pause: "Pause",
+	period: "period",
+	plus: "plus",
+	print: "Print",
+	printscreen: "Print",
+	quote: "apostrophe",
+	return: "Return",
+	right: "Right",
+	scrolllock: "Scroll_Lock",
+	semicolon: "semicolon",
+	shift: "Shift_L",
+	shift_l: "Shift_L",
+	shiftleft: "Shift_L",
+	slash: "slash",
+	space: "space",
+	super: "Super_L",
+	super_l: "Super_L",
+	tab: "Tab",
+	up: "Up",
+	...Object.fromEntries(Array.from({ length: 12 }, (_, i) => [`f${i + 1}`, `F${i + 1}`])),
+	...Object.fromEntries(Array.from({ length: 10 }, (_, i) => [`numpad${i}`, String(i)])),
+	numpadadd: "plus",
+	numpaddecimal: "period",
+	numpaddivide: "slash",
+	numpadmultiply: "asterisk",
+	numpadsubtract: "minus"
+};
+const PRINTABLE_KEY_ALIASES = {
+	"*": "asterisk",
+	"+": "plus",
+	",": "comma",
+	"-": "minus",
+	".": "period",
+	"/": "slash",
+	";": "semicolon",
+	"=": "equal",
+	"[": "bracketleft",
+	"\\": "backslash",
+	"]": "bracketright",
+	"`": "grave",
+	"'": "apostrophe"
+};
+const KERNEL_MODIFIER_KEYSYM_SET = new Set(KERNEL_MODIFIER_KEYSYMS);
+function normalizeKernelKey(value) {
+	const trimmed = value.trim();
+	if (PRINTABLE_KEY_ALIASES[trimmed]) return PRINTABLE_KEY_ALIASES[trimmed];
+	const alias = KEY_ALIASES[trimmed.replace(/[-\s]/g, "_").toLowerCase()];
+	if (alias) return alias;
+	if (/^arrow/i.test(trimmed)) return normalizeKernelKey(trimmed.slice(5));
+	if (trimmed.length === 1 && trimmed >= "A" && trimmed <= "Z") return trimmed.toLowerCase();
+	return trimmed;
+}
+function normalizeKernelKeyCombo(value) {
+	return value.split("+").map((part) => normalizeKernelKey(part)).filter(Boolean);
+}
+function isKernelModifierKey(key) {
+	return KERNEL_MODIFIER_KEYSYM_SET.has(key);
+}
+//#endregion
+//#region src/translator/translator.ts
+var InternalComputerTranslator = class {
+	sessionId;
+	client;
+	coordinateSystem;
+	screenshotSpec;
+	viewport;
+	constructor(opts) {
+		this.sessionId = opts.browser.session_id;
+		this.client = opts.client;
+		this.coordinateSystem = opts.coordinateSystem ?? { type: "pixel" };
+		this.screenshotSpec = opts.screenshot;
+		this.viewport = opts.browser.viewport ?? {
+			width: 1920,
+			height: 1080
+		};
+	}
+	async screenshotRaw() {
+		return (await this.screenshot()).data;
+	}
+	async screenshot() {
+		const response = await this.client.browsers.computer.captureScreenshot(this.sessionId, {});
+		let data = Buffer.from(await response.arrayBuffer());
+		let mimeType = "image/png";
+		const transform = this.screenshotSpec?.transform;
+		if (transform) {
+			let pipeline = sharp(data).resize(transform.width, transform.height, { fit: "fill" });
+			if (transform.format === "webp") {
+				pipeline = pipeline.webp({ quality: transform.quality });
+				mimeType = "image/webp";
+			} else if (transform.format === "jpeg") {
+				pipeline = pipeline.jpeg({ quality: transform.quality });
+				mimeType = "image/jpeg";
+			} else {
+				pipeline = pipeline.png();
+				mimeType = "image/png";
+			}
+			data = await pipeline.toBuffer();
+		}
+		return {
+			data,
+			mimeType
+		};
+	}
+	async currentUrl() {
+		await this.runKernelBatch([keypress(["Control", "l"]), keypress(["Control", "c"])]);
+		return ((await this.client.browsers.computer.readClipboard(this.sessionId)).text ?? "").trim();
+	}
+	async currentMousePosition() {
+		const pos = await this.client.browsers.computer.getMousePosition(this.sessionId);
+		return {
+			x: toInt(pos.x),
+			y: toInt(pos.y)
+		};
+	}
+	async executeBatch(actions) {
+		const result = { readResults: [] };
+		const pending = [];
+		const flush = async () => {
+			if (pending.length === 0) return;
+			await this.runKernelBatch(pending.splice(0));
+		};
+		for (let i = 0; i < actions.length; i++) {
+			const action = actions[i];
+			const type = typeof action.type === "string" ? action.type : "";
+			if (type === "screenshot") {
+				await flush();
+				result.readResults.push({
+					type: "screenshot",
+					...await this.screenshot()
+				});
+				continue;
+			}
+			if (type === "url") {
+				await flush();
+				result.readResults.push({
+					type: "url",
+					url: await this.currentUrl()
+				});
+				continue;
+			}
+			if (type === "cursor_position") {
+				await flush();
+				const pos = await this.currentMousePosition();
+				result.readResults.push({
+					type: "cursor_position",
+					...pos
+				});
+				continue;
+			}
+			if (type === "goto") {
+				const url = normalizeGotoUrl(action.url) ?? "";
+				pending.push(keypress(["Control", "l"]), {
+					type: "type_text",
+					type_text: { text: url }
+				}, keypress(["Enter"]));
+				continue;
+			}
+			if (type === "back") {
+				pending.push(keypress(["Alt", "Left"]));
+				continue;
+			}
+			if (type === "forward") {
+				pending.push(keypress(["Alt", "Right"]));
+				continue;
+			}
+			pending.push(toSdkAction(type, action, this.coordinateSystem, this.viewport));
+		}
+		await flush();
+		return result;
+	}
+	async runKernelBatch(actions) {
+		await this.client.browsers.computer.batch(this.sessionId, { actions });
+	}
+};
+function toSdkAction(type, action, coordinateSystem, viewport) {
+	switch (type) {
+		case "click": {
+			const clickHoldKeys = readHoldKeys(action.hold_keys);
+			const point = toViewportPoint(action, coordinateSystem, viewport);
+			return {
+				type: "click_mouse",
+				click_mouse: {
+					x: point.x,
+					y: point.y,
+					button: clickMouseButtonOr(action.button, "left"),
+					...clickHoldKeys.length > 0 ? { hold_keys: clickHoldKeys } : {}
+				}
+			};
+		}
+		case "double_click": {
+			const doubleClickHoldKeys = readHoldKeys(action.hold_keys);
+			const point = toViewportPoint(action, coordinateSystem, viewport);
+			return {
+				type: "click_mouse",
+				click_mouse: {
+					x: point.x,
+					y: point.y,
+					num_clicks: 2,
+					...doubleClickHoldKeys.length > 0 ? { hold_keys: doubleClickHoldKeys } : {}
+				}
+			};
+		}
+		case "mouse_down":
+		case "mouse_up": {
+			const mouseHoldKeys = readHoldKeys(action.hold_keys);
+			const point = toViewportPoint(action, coordinateSystem, viewport);
+			return {
+				type: "click_mouse",
+				click_mouse: {
+					x: point.x,
+					y: point.y,
+					button: clickMouseButtonOr(action.button, "left"),
+					click_type: type === "mouse_down" ? "down" : "up",
+					...mouseHoldKeys.length > 0 ? { hold_keys: mouseHoldKeys } : {}
+				}
+			};
+		}
+		case "type": return {
+			type: "type_text",
+			type_text: { text: typeof action.text === "string" ? action.text : "" }
+		};
+		case "keypress": return keypress(toStringArray(action.keys), action.duration);
+		case "scroll": {
+			const scrollHoldKeys = readHoldKeys(action.hold_keys);
+			const point = toViewportPoint(action, coordinateSystem, viewport);
+			return {
+				type: "scroll",
+				scroll: {
+					x: point.x,
+					y: point.y,
+					delta_x: toInt(action.scroll_x),
+					delta_y: toInt(action.scroll_y),
+					...scrollHoldKeys.length > 0 ? { hold_keys: scrollHoldKeys } : {}
+				}
+			};
+		}
+		case "move": {
+			const moveHoldKeys = readHoldKeys(action.hold_keys);
+			const point = toViewportPoint(action, coordinateSystem, viewport);
+			return {
+				type: "move_mouse",
+				move_mouse: {
+					x: point.x,
+					y: point.y,
+					...moveHoldKeys.length > 0 ? { hold_keys: moveHoldKeys } : {}
+				}
+			};
+		}
+		case "drag": {
+			const dragHoldKeys = readHoldKeys(action.hold_keys);
+			return {
+				type: "drag_mouse",
+				drag_mouse: {
+					path: toPath(action.path, coordinateSystem, viewport),
+					button: dragMouseButtonOr(action.button, "left"),
+					...dragHoldKeys.length > 0 ? { hold_keys: dragHoldKeys } : {}
+				}
+			};
+		}
+		case "wait": return {
+			type: "sleep",
+			sleep: { duration_ms: typeof action.ms === "number" ? Math.trunc(action.ms) : 1e3 }
+		};
+		default: throw new Error(`unknown computer action type: ${type}`);
+	}
+}
+function toInt(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return Math.trunc(value);
+	if (typeof value === "string" && value.trim()) {
+		const n = Number(value);
+		if (Number.isFinite(n)) return Math.trunc(n);
+	}
+	return 0;
+}
+function stringOr(value, fallback) {
+	return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function clickMouseButtonOr(value, fallback) {
+	const candidate = stringOr(value, fallback);
+	if (candidate === "left" || candidate === "right" || candidate === "middle" || candidate === "back" || candidate === "forward") return candidate;
+	return fallback;
+}
+function dragMouseButtonOr(value, fallback) {
+	const candidate = stringOr(value, fallback);
+	if (candidate === "left" || candidate === "right" || candidate === "middle") return candidate;
+	return fallback;
+}
+function toStringArray(value) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function readHoldKeys(value) {
+	return toStringArray(value).map(normalizeKernelKey);
+}
+function keypress(keys, duration = void 0) {
+	const translated = keys.flatMap(normalizeKernelKeyCombo);
+	const pressedKeys = translated.filter((key) => !isKernelModifierKey(key));
+	const holdKeys = pressedKeys.length > 0 ? translated.filter(isKernelModifierKey) : translated.slice(0, -1);
+	return {
+		type: "press_key",
+		press_key: {
+			keys: pressedKeys.length > 0 ? pressedKeys : translated.slice(-1),
+			...holdKeys.length > 0 ? { hold_keys: holdKeys } : {},
+			...typeof duration === "number" && Number.isFinite(duration) && duration > 0 ? { duration: Math.trunc(duration) } : {}
+		}
+	};
+}
+function toPath(value, coordinateSystem = { type: "pixel" }, viewport = {
+	width: 1920,
+	height: 1080
+}) {
+	if (!Array.isArray(value)) return [];
+	return value.map((point) => toPathPoint(point, coordinateSystem, viewport));
+}
+function toPathPoint(value, coordinateSystem, viewport) {
+	if (Array.isArray(value)) {
+		const point = transformPoint(toInt(value[0]), toInt(value[1]), coordinateSystem, viewport);
+		return [point.x, point.y];
+	}
+	if (value && typeof value === "object") {
+		const point = value;
+		const transformed = transformPoint(toInt(point.x), toInt(point.y), coordinateSystem, viewport);
+		return [transformed.x, transformed.y];
+	}
+	return [0, 0];
+}
+function toViewportPoint(action, coordinateSystem, viewport) {
+	return transformPoint(toInt(action.x), toInt(action.y), coordinateSystem, viewport);
+}
+function transformPoint(x, y, coordinateSystem, viewport) {
+	if (coordinateSystem.type === "pixel") return {
+		x,
+		y
+	};
+	const [min, max] = coordinateSystem.range;
+	const scale = max - min;
+	if (scale <= 0) return {
+		x,
+		y
+	};
+	return {
+		x: clamp(Math.round((x - min) / scale * viewport.width), 0, viewport.width - 1),
+		y: clamp(Math.round((y - min) / scale * viewport.height), 0, viewport.height - 1)
+	};
+}
+function clamp(value, min, max) {
+	return Math.max(min, Math.min(max, value));
+}
+//#endregion
+//#region src/tools.ts
+function createCuaComputerTools(args) {
+	const translator = new InternalComputerTranslator(args);
+	return withNavigationTool(args).map((executor) => createExecutorTool(executor, translator));
+}
+function withNavigationTool(args) {
+	const executors = [...args.toolExecutors];
+	const existing = new Set(executors.map((executor) => executor.definition.name));
+	if (args.computerUseExtra && !existing.has(CUA_NAVIGATION_TOOL_NAME)) {
+		const definition = createCuaNavigationToolDefinition();
+		executors.push({
+			kind: "navigation",
+			definition
+		});
+	}
+	return executors;
+}
+function createExecutorTool(executor, translator) {
+	const { definition } = executor;
+	if (isNavigationExecutor(executor)) return {
+		name: definition.name,
+		label: definition.name,
+		description: definition.description,
+		parameters: definition.parameters,
+		async execute(_toolCallId, params) {
+			return executeNavigationTool(translator, asNavigationInput(params));
+		}
+	};
+	return {
+		name: definition.name,
+		label: definition.name,
+		description: definition.description,
+		parameters: definition.parameters,
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			return executeBatchTool(translator, { actions: executor.toActions(params) });
+		}
+	};
+}
+function isNavigationExecutor(executor) {
+	return "kind" in executor && executor.kind === "navigation";
+}
+async function executeBatchTool(translator, params) {
+	const content = [];
+	const readResults = [];
+	try {
+		const result = await translator.executeBatch(params.actions);
+		for (const read of result.readResults) if (read.type === "url") {
+			readResults.push({
+				type: "url",
+				url: read.url
+			});
+			content.push({
+				type: "text",
+				text: `url(): ${read.url}`
+			});
+		} else if (read.type === "cursor_position") {
+			readResults.push({
+				type: "cursor_position",
+				x: read.x,
+				y: read.y
+			});
+			content.push({
+				type: "text",
+				text: `cursor_position(): ${read.x},${read.y}`
+			});
+		} else {
+			readResults.push({
+				type: "screenshot",
+				bytes: read.data.length
+			});
+			content.push({
+				type: "image",
+				data: read.data.toString("base64"),
+				mimeType: read.mimeType
+			});
+		}
+		if (content.length === 0) {
+			const screenshot = await translator.screenshot();
+			readResults.push({
+				type: "screenshot",
+				bytes: screenshot.data.length
+			});
+			content.push({
+				type: "image",
+				data: screenshot.data.toString("base64"),
+				mimeType: screenshot.mimeType
+			});
+		}
+	} catch (err) {
+		throw new Error(`Actions failed: ${errorMessage(err)}`, { cause: err });
+	}
+	return {
+		content,
+		details: {
+			statusText: "Actions executed successfully.",
+			readResults
+		}
+	};
+}
+async function executeNavigationTool(translator, params) {
+	const action = params.action;
+	try {
+		let statusText = `${action} executed successfully.`;
+		let url;
+		if (action === "url") {
+			url = await translator.currentUrl();
+			statusText = `Current URL: ${url}`;
+		} else await translator.executeBatch([{
+			type: action,
+			url: params.url
+		}]);
+		const screenshot = await translator.screenshot();
+		return {
+			content: [{
+				type: "text",
+				text: statusText
+			}, {
+				type: "image",
+				data: screenshot.data.toString("base64"),
+				mimeType: screenshot.mimeType
+			}],
+			details: {
+				action,
+				statusText,
+				...url ? { url } : {}
+			}
+		};
+	} catch (err) {
+		throw new Error(`${action} failed: ${errorMessage(err)}`, { cause: err });
+	}
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+function asNavigationInput(value) {
+	if (value && typeof value === "object" && typeof value.action === "string") return value;
+	throw new Error("invalid computer_use_extra parameters");
+}
+//#endregion
+//#region src/agent.ts
+/**
+* Holds the CUA-specific pieces that have to change when a model changes:
+* the resolved runtime spec, the browser translator built for that spec, and
+* the tools/prompt/payload hooks derived from it. Caller-owned `extraTools`
+* are appended after the CUA defaults.
+*/
+var CuaRuntimeController = class {
+	options;
+	runtimeSpec;
+	translator;
+	constructor(options) {
+		this.options = options;
+		this.runtimeSpec = resolveCuaRuntimeSpec(options.model);
+		this.translator = this.createTranslator();
+	}
+	get model() {
+		return this.runtimeSpec.model;
+	}
+	get systemPrompt() {
+		return this.runtimeSpec.defaultSystemPrompt;
+	}
+	setModel(model) {
+		this.runtimeSpec = resolveCuaRuntimeSpec(model);
+		this.translator = this.createTranslator();
+	}
+	tools() {
+		return [...createCuaComputerTools({
+			browser: this.options.browser,
+			client: this.options.client,
+			toolExecutors: this.runtimeSpec.toolExecutors,
+			coordinateSystem: this.runtimeSpec.coordinateSystem,
+			screenshot: this.runtimeSpec.screenshot,
+			computerUseExtra: this.options.computerUseExtra
+		}), ...this.options.extraTools ?? []];
+	}
+	onPayload() {
+		const runtimeSpec = this.runtimeSpec;
+		return composeOnPayload(runtimeSpec.onPayload ? async (payload, model) => runtimeSpec.onPayload?.(payload, model, {
+			keepToolNames: this.keepToolNames(),
+			getScreenshot: () => this.translator.screenshot()
+		}) : void 0, this.options.onPayload);
+	}
+	keepToolNames() {
+		return [...(this.options.extraTools ?? []).map((tool) => tool.name), ...this.options.computerUseExtra ? [CUA_NAVIGATION_TOOL_NAME] : []];
+	}
+	createTranslator() {
+		return new InternalComputerTranslator({
+			browser: this.options.browser,
+			client: this.options.client,
+			coordinateSystem: this.runtimeSpec.coordinateSystem,
+			screenshot: this.runtimeSpec.screenshot
+		});
+	}
+};
+/** Harness auth default following the documented CUA env-var convention. */
+async function getCuaEnvApiKeyAndHeaders(model) {
+	const apiKey = getCuaEnvApiKey(model.provider);
+	return apiKey ? { apiKey } : void 0;
+}
+/**
+* Pi `Agent` configured for Kernel browser computer use.
+*
+* Use this class when you want direct access to the lower-level pi agent state,
+* queues, event stream, and `state.model` mutation model. It resolves CUA model
+* refs, installs provider-appropriate CUA tools by default, and keeps those
+* defaults in sync when `agent.state.model` changes.
+*/
+var CuaAgent = class extends Agent {
+	runtime;
+	ownsSystemPrompt;
+	stateProxy;
+	constructor(options) {
+		const { browser, client, initialState, onPayload, streamFn, prepareNextTurn, extraTools, computerUseExtra, ...agentOptions } = options;
+		const runtime = new CuaRuntimeController({
+			browser,
+			client,
+			model: initialState.model,
+			extraTools,
+			computerUseExtra,
+			onPayload
+		});
+		const wrappedStreamFn = (model, context, streamOptions) => {
+			const optionsWithCuaRuntime = {
+				...streamOptions,
+				onPayload: runtime.onPayload(),
+				keepToolNames: runtime.keepToolNames()
+			};
+			return (streamFn ?? streamSimple)(model, context, optionsWithCuaRuntime);
+		};
+		super({
+			...agentOptions,
+			getApiKey: agentOptions.getApiKey ?? getCuaEnvApiKey,
+			streamFn: wrappedStreamFn,
+			initialState: {
+				...initialState,
+				model: runtime.model,
+				tools: runtime.tools(),
+				systemPrompt: initialState.systemPrompt ?? runtime.systemPrompt
+			}
+		});
+		this.runtime = runtime;
+		this.ownsSystemPrompt = initialState.systemPrompt === void 0;
+		/**
+		* pi calls `prepareNextTurn` between provider requests. Wrapping it lets CUA
+		* honor any user-provided turn update while also refreshing provider-specific
+		* defaults if that update changes the model.
+		*/
+		this.prepareNextTurn = async (signal) => {
+			const update = await prepareNextTurn?.(signal);
+			if (update?.model) this.applyRuntime(update.model);
+			const state = super.state;
+			const context = update?.context ?? {
+				systemPrompt: state.systemPrompt,
+				messages: state.messages.slice(),
+				tools: state.tools.slice()
+			};
+			return {
+				...update,
+				model: state.model,
+				context: {
+					...context,
+					systemPrompt: this.ownsSystemPrompt ? state.systemPrompt : context.systemPrompt,
+					tools: state.tools.slice()
+				}
+			};
+		};
+	}
+	/**
+	* Return a state proxy so `agent.state.model = "provider:model"` can behave
+	* like pi's normal mutable state while also re-resolving CUA tools, prompt,
+	* and payload hooks for the selected provider.
+	*/
+	get state() {
+		if (!this.stateProxy) this.stateProxy = new Proxy(super.state, { set: (target, prop, value, receiver) => {
+			if (prop === "model") {
+				this.applyRuntime(value);
+				return true;
+			}
+			return Reflect.set(target, prop, value, receiver);
+		} });
+		return this.stateProxy;
+	}
+	applyRuntime(model) {
+		this.runtime.setModel(model);
+		const state = super.state;
+		state.model = this.runtime.model;
+		state.tools = this.runtime.tools();
+		if (this.ownsSystemPrompt) state.systemPrompt = this.runtime.systemPrompt;
+	}
+};
+/**
+* Pi `AgentHarness` configured for Kernel browser computer use.
+*
+* Use this class when you want pi's higher-level harness APIs for sessions,
+* resources, prompt templates, queue events, compaction, and model selection.
+* It installs provider CUA tools by default and keeps CUA-owned runtime
+* defaults in sync through `setModel()`.
+*/
+var CuaAgentHarness = class extends AgentHarness {
+	runtime;
+	requestedActiveToolNames;
+	constructor(options) {
+		const { browser, client, model, extraTools, computerUseExtra, systemPrompt, getApiKeyAndHeaders, onPayload, activeToolNames, ...harnessOptions } = options;
+		const runtime = new CuaRuntimeController({
+			browser,
+			client,
+			model,
+			extraTools,
+			computerUseExtra,
+			onPayload
+		});
+		const resolvedTools = runtime.tools();
+		super({
+			...harnessOptions,
+			model: runtime.model,
+			tools: resolvedTools,
+			systemPrompt: systemPrompt ?? (() => runtime.systemPrompt),
+			getApiKeyAndHeaders: getApiKeyAndHeaders ?? getCuaEnvApiKeyAndHeaders,
+			activeToolNames: activeToolNames ?? resolvedTools.map((tool) => tool.name)
+		});
+		this.runtime = runtime;
+		this.requestedActiveToolNames = activeToolNames;
+		this.on("before_provider_payload", async ({ model, payload }) => {
+			const onPayload = this.runtime.onPayload();
+			if (!onPayload) return { payload };
+			return { payload: await onPayload(payload, model) ?? payload };
+		});
+	}
+	/**
+	* Mirror pi `AgentHarness.setModel()` while accepting CUA model refs.
+	*
+	* The override refreshes CUA-owned tools before delegating to pi so the
+	* harness snapshot and session model-change entry are written with the
+	* concrete model selected by `@onkernel/cua-ai`.
+	*/
+	async setModel(model) {
+		this.runtime.setModel(model);
+		const tools = this.runtime.tools();
+		await super.setTools(tools, this.requestedActiveToolNames ?? tools.map((tool) => tool.name));
+		await super.setModel(this.runtime.model);
+	}
+	async setActiveTools(toolNames) {
+		await super.setActiveTools(toolNames);
+		this.requestedActiveToolNames = [...toolNames];
+	}
+};
+function composeOnPayload(first, second) {
+	if (!first) return second;
+	if (!second) return first;
+	return async (payload, modelRef) => {
+		return second(await first(payload, modelRef) ?? payload, modelRef);
+	};
+}
+//#endregion
+export { CuaAgent, CuaAgentHarness, NodeExecutionEnv, createCuaComputerTools };