agents 0.24.0 → 0.25.0

package/dist/{connector-CptFKzRh.js → connector-58XDGvc3.js}

@@ -2,8 +2,48 @@ import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _ass
 import { t as _classPrivateMethodInitSpec } from "./classPrivateMethodInitSpec-qMjJ6sHQ.js";
 import { CodemodeConnector } from "@cloudflare/codemode";
 import { Validator } from "@cfworker/json-schema";
-//#region src/browser/cdp-session.ts
+//#region src/browser/connector-validation.ts
+function formatToolValidationError(connector, tool, errors) {
+	const specific = errors.filter((error) => error.keyword !== "properties");
+	return `Invalid arguments for ${connector}.${tool}${(specific.length > 0 ? specific : errors).map((error) => {
+		const location = error.instanceLocation.replace(/^#\/?/, "").replaceAll("~1", "/").replaceAll("~0", "~").replaceAll("/", ".");
+		return `${location ? ` at ${location}` : ""}: ${error.error}`;
+	}).join(";")}`;
+}
+/**
+* Validate a connector tool's arguments against its input schema before it
+* runs, so the model gets a precise error instead of a failure deep inside
+* browser work. An omitted argument counts as `{}`: argumentless tools are
+* documented as `cdp.spec()`.
+*/
+function validateConnectorArgs(connector, name, tool) {
+	if (!tool.inputSchema) return tool;
+	const schema = tool.inputSchema;
+	const validator = new Validator(schema, "7", false);
+	return {
+		...tool,
+		execute: async (args, ctx) => {
+			const input = args === void 0 ? {} : args;
+			const result = validator.validate(input);
+			if (!result.valid) throw new Error(formatToolValidationError(connector, name, result.errors));
+			return await tool.execute(input, ctx);
+		}
+	};
+}
+//#endregion
+//#region src/browser/cdp-connection.ts
 const DEFAULT_TIMEOUT_MS = 1e4;
+/** JSON-RPC's "method not found" code, which Chrome also uses for CDP. */
+const CDP_METHOD_NOT_FOUND = -32601;
+/** The browser answered a command with a JSON-RPC error. */
+var CdpProtocolError = class extends Error {
+	constructor(method, code, message) {
+		super(`CDP error ${code ?? "unknown"}: ${message} for ${method}`);
+		this.name = "CdpProtocolError";
+		this.code = code;
+		this.method = method;
+	}
+};
 const MAX_DEBUG_ENTRIES = 400;
 var _socket$1 = /* @__PURE__ */ new WeakMap();
 var _nextId = /* @__PURE__ */ new WeakMap();
@@ -11,42 +51,56 @@ var _pending = /* @__PURE__ */ new WeakMap();
 var _debugLog = /* @__PURE__ */ new WeakMap();
 var _defaultTimeoutMs = /* @__PURE__ */ new WeakMap();
 var _dispose = /* @__PURE__ */ new WeakMap();
-var _CdpSession_brand = /* @__PURE__ */ new WeakSet();
+var _disposed = /* @__PURE__ */ new WeakMap();
+var _onActivity = /* @__PURE__ */ new WeakMap();
+var _CdpConnection_brand = /* @__PURE__ */ new WeakSet();
 /**
-* A CDP session over an open WebSocket. Manages command correlation,
-* timeouts, target sessions, and a debug event ring buffer.
+* One Chrome DevTools Protocol connection over an open WebSocket. Manages
+* command correlation, timeouts, per-tab CDP sessions, and a debug event
+* ring buffer.
 *
 * Used host-side (not in the sandbox) — the sandbox calls into this
 * via DynamicWorkerExecutor's ToolDispatcher RPC.
 */
-var CdpSession = class {
-	constructor(socket, defaultTimeoutMs = DEFAULT_TIMEOUT_MS, dispose, sessionId) {
-		_classPrivateMethodInitSpec(this, _CdpSession_brand);
+var CdpConnection = class {
+	constructor(socket, optionsOrTimeoutMs, onClose, sessionId) {
+		_classPrivateMethodInitSpec(this, _CdpConnection_brand);
 		_classPrivateFieldInitSpec(this, _socket$1, void 0);
 		_classPrivateFieldInitSpec(this, _nextId, 1);
 		_classPrivateFieldInitSpec(this, _pending, /* @__PURE__ */ new Map());
 		_classPrivateFieldInitSpec(this, _debugLog, []);
 		_classPrivateFieldInitSpec(this, _defaultTimeoutMs, void 0);
 		_classPrivateFieldInitSpec(this, _dispose, void 0);
+		_classPrivateFieldInitSpec(this, _disposed, false);
+		_classPrivateFieldInitSpec(this, _onActivity, void 0);
+		const options = typeof optionsOrTimeoutMs === "object" ? optionsOrTimeoutMs : {
+			timeoutMs: optionsOrTimeoutMs,
+			onClose,
+			sessionId
+		};
 		_classPrivateFieldSet2(_socket$1, this, socket);
-		_classPrivateFieldSet2(_defaultTimeoutMs, this, defaultTimeoutMs);
-		_classPrivateFieldSet2(_dispose, this, dispose);
-		this.sessionId = sessionId;
-		socket.addEventListener("message", (event) => _assertClassBrand(_CdpSession_brand, this, _handleMessage).call(this, event));
+		_classPrivateFieldSet2(_defaultTimeoutMs, this, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		_classPrivateFieldSet2(_dispose, this, options.onClose);
+		this.sessionId = options.sessionId;
+		_classPrivateFieldSet2(_onActivity, this, options.onActivity);
+		socket.addEventListener("message", (event) => _assertClassBrand(_CdpConnection_brand, this, _handleMessage).call(this, event));
 		socket.addEventListener("error", () => {
-			_assertClassBrand(_CdpSession_brand, this, _rejectAll).call(this, /* @__PURE__ */ new Error("CDP socket error"));
+			_assertClassBrand(_CdpConnection_brand, this, _rejectAll).call(this, /* @__PURE__ */ new Error("CDP socket error"));
+			_assertClassBrand(_CdpConnection_brand, this, _runDispose).call(this);
 		});
 		socket.addEventListener("close", () => {
-			_assertClassBrand(_CdpSession_brand, this, _rejectAll).call(this, /* @__PURE__ */ new Error("CDP connection closed"));
+			_assertClassBrand(_CdpConnection_brand, this, _rejectAll).call(this, /* @__PURE__ */ new Error("CDP connection closed"));
+			_assertClassBrand(_CdpConnection_brand, this, _runDispose).call(this);
 		});
 	}
 	send(method, params, options = {}) {
 		var _this$nextId, _this$nextId2;
+		_classPrivateFieldGet2(_onActivity, this)?.call(this);
 		const id = (_classPrivateFieldSet2(_nextId, this, (_this$nextId = _classPrivateFieldGet2(_nextId, this), _this$nextId2 = _this$nextId++, _this$nextId)), _this$nextId2);
 		const timeoutMs = options.timeoutMs ?? _classPrivateFieldGet2(_defaultTimeoutMs, this);
 		const sessionId = typeof options.sessionId === "string" && options.sessionId.length > 0 ? options.sessionId : void 0;
 		const domain = typeof method === "string" ? method.split(".")[0] : "";
-		if (!sessionId && domain && !["Browser", "Target"].includes(domain)) _assertClassBrand(_CdpSession_brand, this, _recordDebug).call(this, "warning", {
+		if (!sessionId && domain && !["Browser", "Target"].includes(domain)) _assertClassBrand(_CdpConnection_brand, this, _recordDebug).call(this, "warning", {
 			id,
 			method,
 			reason: "target-scoped method sent without sessionId"
@@ -66,18 +120,27 @@ var CdpSession = class {
 				startedAt
 			});
 		});
-		_assertClassBrand(_CdpSession_brand, this, _recordDebug).call(this, "send", {
+		_assertClassBrand(_CdpConnection_brand, this, _recordDebug).call(this, "send", {
 			id,
 			method,
 			sessionId,
 			timeoutMs
 		});
-		_classPrivateFieldGet2(_socket$1, this).send(JSON.stringify({
-			id,
-			method,
-			params,
-			sessionId
-		}));
+		try {
+			_classPrivateFieldGet2(_socket$1, this).send(JSON.stringify({
+				id,
+				method,
+				params,
+				sessionId
+			}));
+		} catch (error) {
+			const pending = _classPrivateFieldGet2(_pending, this).get(id);
+			if (pending) {
+				clearTimeout(pending.timeoutId);
+				_classPrivateFieldGet2(_pending, this).delete(id);
+				pending.reject(error instanceof Error ? error : new Error(String(error)));
+			}
+		}
 		return result;
 	}
 	async attachToTarget(targetId, options = {}) {
@@ -87,7 +150,7 @@ var CdpSession = class {
 			flatten: true
 		}, { timeoutMs: options.timeoutMs }))?.sessionId ?? "";
 		if (!sessionId) throw new Error(`Target.attachToTarget did not return a sessionId for target ${targetId}`);
-		_assertClassBrand(_CdpSession_brand, this, _recordDebug).call(this, "attach", {
+		_assertClassBrand(_CdpConnection_brand, this, _recordDebug).call(this, "attach", {
 			targetId,
 			sessionId
 		});
@@ -101,16 +164,25 @@ var CdpSession = class {
 		_classPrivateFieldSet2(_debugLog, this, []);
 	}
 	disconnect() {
-		_assertClassBrand(_CdpSession_brand, this, _rejectAll).call(this, /* @__PURE__ */ new Error("CDP session disconnected"));
+		_assertClassBrand(_CdpConnection_brand, this, _rejectAll).call(this, /* @__PURE__ */ new Error("CDP session disconnected"));
 		try {
 			_classPrivateFieldGet2(_socket$1, this).close(1e3, "Done");
 		} catch {}
 	}
 	close() {
 		this.disconnect();
-		_classPrivateFieldGet2(_dispose, this)?.call(this);
+		_assertClassBrand(_CdpConnection_brand, this, _runDispose).call(this);
 	}
 };
+/**
+* Run the dispose callback exactly once, on the first terminal event —
+* an explicit {@link close}, peer closure, or a socket error.
+*/
+function _runDispose() {
+	if (_classPrivateFieldGet2(_disposed, this)) return;
+	_classPrivateFieldSet2(_disposed, this, true);
+	_classPrivateFieldGet2(_dispose, this)?.call(this);
+}
 function _rejectAll(error) {
 	for (const [id, pending] of _classPrivateFieldGet2(_pending, this).entries()) {
 		clearTimeout(pending.timeoutId);
@@ -126,7 +198,7 @@ function _handleMessage(event) {
 	} catch {
 		return;
 	}
-	_assertClassBrand(_CdpSession_brand, this, _recordDebug).call(this, "receive", {
+	_assertClassBrand(_CdpConnection_brand, this, _recordDebug).call(this, "receive", {
 		id: payload.id,
 		method: payload.method,
 		sessionId: payload.sessionId,
@@ -139,9 +211,7 @@ function _handleMessage(event) {
 	_classPrivateFieldGet2(_pending, this).delete(payload.id);
 	if (payload.error) {
 		const err = payload.error;
-		const code = err.code ?? "unknown";
-		const message = err.message ?? "CDP error";
-		pending.reject(/* @__PURE__ */ new Error(`CDP error ${code}: ${message} for ${pending.method}`));
+		pending.reject(new CdpProtocolError(pending.method, typeof err.code === "number" ? err.code : void 0, err.message ?? "CDP error"));
 		return;
 	}
 	pending.resolve(payload.result);
@@ -191,8 +261,10 @@ async function connectUrl(baseUrl, options) {
 	const ws = wsResponse.webSocket;
 	if (!ws) throw new Error(`Failed to establish CDP WebSocket at ${fetchUrl} (status ${wsResponse.status})`);
 	ws.accept();
-	return new CdpSession(ws, options?.timeoutMs);
+	return new CdpConnection(ws, { timeoutMs: options?.timeoutMs });
 }
+/** @deprecated Renamed to {@link CdpConnection}. */
+const CdpSession = CdpConnection;
 //#endregion
 //#region src/browser/browser-run.ts
 var BrowserRenderingError = class extends Error {
@@ -202,6 +274,13 @@ var BrowserRenderingError = class extends Error {
 		this.name = "BrowserRenderingError";
 	}
 };
+/**
+* Whether an error means the platform session is gone: Browser Run uses 404
+* for unknown ids and 410 after `keep_alive` expiry.
+*/
+function isMissingBrowserSession$1(error) {
+	return error instanceof BrowserRenderingError && (error.status === 404 || error.status === 410);
+}
 function browserSessionEndpoint(sessionId, options) {
 	const path = sessionId ? `/v1/devtools/browser/${sessionId}` : "/v1/devtools/browser";
 	const url = new URL(`https://localhost${path}`);
@@ -222,7 +301,11 @@ async function parseBrowserSessionInfo(response) {
 	};
 }
 async function createBrowserSession(browser, options) {
-	const response = await browser.fetch(browserSessionEndpoint(void 0, options), { method: "POST" });
+	const response = await browser.fetch(browserSessionEndpoint(void 0, options), {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(options?.guardrails ? { guardrails: options.guardrails } : {})
+	});
 	if (!response.ok) throw new BrowserRenderingError(`Failed to create Browser Rendering session: ${response.status}`, response.status);
 	return parseBrowserSessionInfo(response);
 }
@@ -241,28 +324,33 @@ async function deleteBrowserSession(browser, sessionId) {
 */
 async function connectBrowser(browser, options) {
 	const normalizedOptions = typeof options === "number" ? { timeoutMs: options } : options ?? {};
-	const isKitesurf = normalizedOptions.browser === "kitesurf";
-	if (isKitesurf && (normalizedOptions.keepAliveMs || normalizedOptions.includeTargets || normalizedOptions.recording)) throw new Error("Kitesurf does not support keepAliveMs, includeTargets, or recording");
-	const response = await browser.fetch(browserSessionEndpoint(void 0, {
-		keepAliveMs: isKitesurf ? void 0 : normalizedOptions.keepAliveMs,
+	if (normalizedOptions.browser === "kitesurf") {
+		const smuggled = normalizedOptions;
+		if (smuggled.keepAliveMs || smuggled.includeTargets || smuggled.recording) throw new Error("Kitesurf does not support keepAliveMs, includeTargets, or recording");
+	}
+	const response = await browser.fetch(browserSessionEndpoint(void 0, normalizedOptions.browser === "kitesurf" ? { browser: "kitesurf" } : {
+		keepAliveMs: normalizedOptions.keepAliveMs,
 		includeTargets: normalizedOptions.includeTargets,
-		recording: normalizedOptions.recording,
-		browser: normalizedOptions.browser
+		recording: normalizedOptions.recording
 	}), { headers: { Upgrade: "websocket" } });
 	const ws = response.webSocket;
 	if (!ws) throw new Error("Browser Rendering binding did not return a WebSocket. Ensure the 'browser' binding is configured in wrangler.jsonc.");
 	if (normalizedOptions.browser === "kitesurf") {
 		ws.accept();
-		return new CdpSession(ws, normalizedOptions.timeoutMs);
+		return new CdpConnection(ws, { timeoutMs: normalizedOptions.timeoutMs });
 	}
 	const sessionId = response.headers.get("cf-browser-session-id");
 	if (!sessionId) throw new Error("Browser Rendering binding did not include a session ID when opening the CDP WebSocket");
 	ws.accept();
-	return new CdpSession(ws, normalizedOptions.timeoutMs, () => {
-		deleteBrowserSession(browser, sessionId).catch((error) => {
-			console.warn(`[agents/browser] Failed to delete one-shot Browser Run session ${sessionId}`, error);
-		});
-	}, sessionId);
+	return new CdpConnection(ws, {
+		timeoutMs: normalizedOptions.timeoutMs,
+		onClose: () => {
+			deleteBrowserSession(browser, sessionId).catch((error) => {
+				console.warn(`[agents/browser] Failed to delete one-shot Browser Run session ${sessionId}`, error);
+			});
+		},
+		sessionId
+	});
 }
 /**
 * Fetch a Browser Run [session recording](https://developers.cloudflare.com/browser-run/features/session-recording/)
@@ -284,14 +372,18 @@ async function getBrowserRecording(options) {
 	const payload = await response.json();
 	return "result" in payload && payload.result ? payload.result : payload;
 }
-/**
-* Connect to an existing Browser Rendering session without deleting it on close.
-*/
-async function connectBrowserSession(browser, sessionId, timeoutMs) {
-	const ws = (await browser.fetch(browserSessionEndpoint(sessionId), { headers: { Upgrade: "websocket" } })).webSocket;
-	if (!ws) throw new Error(`Browser Rendering binding did not return a WebSocket for session ${sessionId}`);
+async function connectBrowserSession(browser, sessionId, options) {
+	const normalized = typeof options === "number" ? { timeoutMs: options } : options ?? {};
+	const response = await browser.fetch(browserSessionEndpoint(sessionId), { headers: { Upgrade: "websocket" } });
+	const ws = response.webSocket;
+	if (!ws) throw new BrowserRenderingError(`Browser Rendering binding did not return a WebSocket for session ${sessionId} (${response.status})`, response.status);
 	ws.accept();
-	return new CdpSession(ws, timeoutMs, void 0, sessionId);
+	return new CdpConnection(ws, {
+		timeoutMs: normalized.timeoutMs,
+		onClose: normalized.onClose,
+		sessionId,
+		onActivity: normalized.onActivity
+	});
 }
 //#endregion
 //#region src/browser/quick-actions.ts
@@ -375,29 +467,110 @@ function browserPdf(browser, input) {
 	return quickActionBinary(browser, "pdf", input);
 }
 //#endregion
+//#region src/browser/live-view.ts
+/**
+* Browser Run mints `devtoolsFrontendUrl`s (the Live View links) that are
+* valid for ~5 minutes. We surface the window so callers can decide how long
+* a shared link is good for before re-listing targets.
+*/
+const LIVE_VIEW_URL_TTL_MS = 300 * 1e3;
+/**
+* Rewrite the hosted Live View UI's `mode` query param (`tab` | `devtools`).
+* The raw `devtoolsFrontendUrl` is returned unchanged when no mode is asked
+* for or the URL can't be parsed.
+*/
+function applyLiveViewMode(rawUrl, mode) {
+	if (!mode) return rawUrl;
+	try {
+		const url = new URL(rawUrl);
+		url.searchParams.set("mode", mode === "devtools" ? "devtools" : "tab");
+		return url.toString();
+	} catch {
+		return rawUrl;
+	}
+}
+/**
+* Project a fresh target listing into Live View links — one per tab that has
+* a `devtoolsFrontendUrl`. Pure; the caller supplies just-listed targets.
+*/
+function createLiveView(sessionId, targets, mode) {
+	return {
+		sessionId,
+		targets: targets.filter((target) => target.devtoolsFrontendUrl).map((target) => ({
+			targetId: target.id,
+			url: applyLiveViewMode(target.devtoolsFrontendUrl, mode),
+			pageUrl: target.url,
+			title: target.title,
+			type: target.type
+		})),
+		expiresInMs: LIVE_VIEW_URL_TTL_MS
+	};
+}
+//#endregion
 //#region src/browser/spec.ts
 const MISSING_BROWSER_CONFIG = "Either 'browser' (Fetcher binding) or 'cdpUrl' must be provided";
 const urlSpecCache = /* @__PURE__ */ new Map();
 const bindingSpecCache = /* @__PURE__ */ new WeakMap();
 const CACHE_TTL_MS = 300 * 1e3;
+/** Qualify a same-domain `$ref` (`"FrameId"` → `"Page.FrameId"`). */
+function qualifyRef(domain, ref) {
+	if (ref === void 0) return void 0;
+	return ref.includes(".") ? ref : `${domain}.${ref}`;
+}
+function normalizeItems(domain, items) {
+	if (!items) return void 0;
+	return {
+		type: items.type,
+		$ref: qualifyRef(domain, items.$ref),
+		enum: items.enum
+	};
+}
+function normalizeFields(domain, fields) {
+	return (fields ?? []).map((field) => ({
+		name: field.name,
+		description: field.description,
+		optional: field.optional,
+		experimental: field.experimental,
+		deprecated: field.deprecated,
+		type: field.type,
+		$ref: qualifyRef(domain, field.$ref),
+		enum: field.enum,
+		items: normalizeItems(domain, field.items)
+	}));
+}
 function normalizeCdpSpec(spec) {
-	return { domains: (spec.domains ?? []).map((domain) => ({
-		name: domain.domain,
-		description: domain.description,
-		commands: (domain.commands ?? []).map((command) => ({
+	return { domains: (spec.domains ?? []).map(({ domain, ...raw }) => ({
+		name: domain,
+		description: raw.description,
+		experimental: raw.experimental,
+		deprecated: raw.deprecated,
+		commands: (raw.commands ?? []).map((command) => ({
 			name: command.name,
-			method: `${domain.domain}.${command.name}`,
-			description: command.description
+			method: `${domain}.${command.name}`,
+			description: command.description,
+			experimental: command.experimental,
+			deprecated: command.deprecated,
+			parameters: normalizeFields(domain, command.parameters),
+			returns: normalizeFields(domain, command.returns)
 		})),
-		events: (domain.events ?? []).map((event) => ({
+		events: (raw.events ?? []).map((event) => ({
 			name: event.name,
-			event: `${domain.domain}.${event.name}`,
-			description: event.description
+			event: `${domain}.${event.name}`,
+			description: event.description,
+			experimental: event.experimental,
+			deprecated: event.deprecated,
+			parameters: normalizeFields(domain, event.parameters)
 		})),
-		types: (domain.types ?? []).map((type) => ({
+		types: (raw.types ?? []).map((type) => ({
 			id: type.id,
-			name: `${domain.domain}.${type.id}`,
-			description: type.description
+			name: `${domain}.${type.id}`,
+			description: type.description,
+			experimental: type.experimental,
+			deprecated: type.deprecated,
+			type: type.type,
+			enum: type.enum,
+			properties: normalizeFields(domain, type.properties),
+			items: normalizeItems(domain, type.items)
 		}))
 	})) };
 }
@@ -423,6 +596,13 @@ async function fetchCdpSpecFromUrl(cdpBaseUrl, headers) {
 		return await response.json();
 	});
 }
+async function fetchCdpSpecFromSession(browser, sessionId) {
+	return getCachedSpec(bindingSpecCache, browser, async () => {
+		const response = await browser.fetch(`https://localhost/v1/devtools/browser/${sessionId}/json/protocol`);
+		if (!response.ok) throw new Error(`Failed to fetch CDP spec from Browser Rendering: ${response.status}`);
+		return await response.json();
+	});
+}
 async function fetchCdpSpecFromBrowser(browser) {
 	return getCachedSpec(bindingSpecCache, browser, async () => {
 		const createResponse = await browser.fetch("https://localhost/v1/devtools/browser", { method: "POST" });
@@ -443,11 +623,12 @@ async function fetchCdpSpecFromBrowser(browser) {
 /** Load the (cached) searchable CDP spec for a browser source. */
 async function loadCdpSpec(source) {
 	if (source.cdpUrl) return fetchCdpSpecFromUrl(source.cdpUrl, source.cdpHeaders);
+	if (source.browser && source.sessionId) return fetchCdpSpecFromSession(source.browser, source.sessionId);
 	if (source.browser) return fetchCdpSpecFromBrowser(source.browser);
 	throw new Error(MISSING_BROWSER_CONFIG);
 }
 //#endregion
-//#region src/browser/session-manager.ts
+//#region src/browser/session-store.ts
 var _DurableBrowserSessionStore_brand = /* @__PURE__ */ new WeakSet();
 var DurableBrowserSessionStore = class {
 	constructor(storage) {
@@ -524,37 +705,9 @@ const DEFAULT_EXEC_SWEEP_IDLE_MS = 1440 * 60 * 1e3;
 * keep an active or recently-resumed execution out of sweep range.
 */
 const EXEC_TOUCH_INTERVAL_MS = 60 * 1e3;
-/**
-* Browser Run mints `devtoolsFrontendUrl`s (the Live View links) that are
-* valid for ~5 minutes. We surface the window so callers can decide how long
-* a shared link is good for before re-listing targets.
-*/
-const LIVE_VIEW_URL_TTL_MS = 300 * 1e3;
 function isMissingBrowserSession(error) {
 	return error instanceof BrowserRenderingError && (error.status === 404 || error.status === 410);
 }
-function formatToolValidationError(connector, tool, errors) {
-	const specific = errors.filter((error) => error.keyword !== "properties");
-	return `Invalid arguments for ${connector}.${tool}${(specific.length > 0 ? specific : errors).map((error) => {
-		const location = error.instanceLocation.replace(/^#\/?/, "").replaceAll("~1", "/").replaceAll("~0", "~").replaceAll("/", ".");
-		return `${location ? ` at ${location}` : ""}: ${error.error}`;
-	}).join(";")}`;
-}
-/**
-* Rewrite the hosted Live View UI's `mode` query param (`tab` | `devtools`).
-* The raw `devtoolsFrontendUrl` is returned unchanged when no mode is asked
-* for or the URL can't be parsed.
-*/
-function applyLiveViewMode(rawUrl, mode) {
-	if (!mode) return rawUrl;
-	try {
-		const url = new URL(rawUrl);
-		url.searchParams.set("mode", mode === "devtools" ? "devtools" : "tab");
-		return url.toString();
-	} catch {
-		return rawUrl;
-	}
-}
 /**
 * `cdp.attachToTarget` returns `{ sessionId: "target:<targetId>" }` — a stable
 * handle instead of the raw CDP session id. (The object shape mirrors the real
@@ -617,25 +770,14 @@ var BrowserConnector = class extends CodemodeConnector {
 			"If a command fails or times out, check cdp.getDebugLog() for recent protocol traffic."
 		];
 		if (_assertClassBrand(_BrowserConnector_brand, this, _isKitesurf).call(this)) lines.push("Kitesurf implements a subset of CDP and does not expose protocol discovery.", "Kitesurf is scoped to this connection. Complete the whole browser task in one execution and do not pause for approval: the browser cannot reconnect when execution resumes.", "Kitesurf Page.navigate may resolve before layout and paint. Before a screenshot: call Page.enable; navigate; poll Runtime.evaluate with returnByValue: true until result.value reports document.readyState === 'complete' and non-empty body text; then wait 1000ms before Page.captureScreenshot. Do not capture if readiness fails.");
-		else lines.push("Use cdp.spec() to discover commands, events, and types when unsure.", "When a step needs a human (login, MFA, CAPTCHA, sensitive input), call cdp.getLiveViewUrl() to get a link they can open to control the browser live — surface it, then make an approval-gated call so the run pauses until they're done.");
+		else lines.push("Use cdp.spec() to look up commands, their parameters, events, and types when unsure.", "When a step needs a human (login, MFA, CAPTCHA, sensitive input), call cdp.getLiveViewUrl() to get a link they can open to control the browser live — surface it, then make an approval-gated call so the run pauses until they're done.");
 		if (mode === "one-shot") lines.push("The browser session lasts for this execution only and is closed when it ends.");
 		else if (mode === "reuse") lines.push("The browser session is shared and persists across executions — tabs and state you leave behind will still be there next time.");
 		else lines.push("The browser session is one-shot by default. If browser state must persist after this execution (e.g. a logged-in page), call cdp.startSession() to keep it alive for later executions.");
 		return lines.join("\n");
 	}
 	tool(name, tool) {
-		if (!tool.inputSchema) return tool;
-		const schema = tool.inputSchema;
-		const validator = new Validator(schema, "7", false);
-		return {
-			...tool,
-			execute: async (args, ctx) => {
-				const input = args === void 0 ? {} : args;
-				const result = validator.validate(input);
-				if (!result.valid) throw new Error(formatToolValidationError(this.name(), name, result.errors));
-				return await tool.execute(input, ctx);
-			}
-		};
+		return validateConnectorArgs(this.name(), name, tool);
 	}
 	tools() {
 		const tools = {
@@ -674,7 +816,7 @@ var BrowserConnector = class extends CodemodeConnector {
 							timeoutMs
 						});
 					} catch (err) {
-						if (err instanceof Error && /-32601|wasn't found/.test(err.message)) {
+						if (err instanceof CdpProtocolError && err.code === -32601) {
 							if (await _assertClassBrand(_BrowserConnector_brand, this, _isSpecEvent).call(this, method)) throw new Error(`${err.message}. '${method}' is a CDP *event*, not a command — it cannot be called via cdp.send. To wait for page state, poll instead (e.g. Runtime.evaluate of document.readyState until "complete").`);
 							if (!sessionId) throw new Error(`${err.message}. Page-scoped commands need a sessionId: const { sessionId } = await cdp.attachToTarget({ targetId }); then pass sessionId to cdp.send.`);
 						}
@@ -711,7 +853,7 @@ var BrowserConnector = class extends CodemodeConnector {
 				}
 			},
 			spec: {
-				description: "Return the searchable Chrome DevTools Protocol spec: domains with their commands, events, and types. Use it to discover method names and capabilities.",
+				description: "Return the searchable Chrome DevTools Protocol spec: domains with their commands (parameters and returns), events, and types. Use it to find a method and exactly how to call it.",
 				replay: "reexecute",
 				inputSchema: {
 					type: "object",
@@ -919,18 +1061,7 @@ var BrowserConnector = class extends CodemodeConnector {
 	async liveView(options) {
 		const info = await this.sessionInfo();
 		if (!info) return void 0;
-		const targets = (info.targets ?? []).filter((target) => target.devtoolsFrontendUrl).map((target) => ({
-			targetId: target.id,
-			url: applyLiveViewMode(target.devtoolsFrontendUrl, options?.mode),
-			pageUrl: target.url,
-			title: target.title,
-			type: target.type
-		}));
-		return {
-			sessionId: info.sessionId,
-			targets,
-			expiresInMs: LIVE_VIEW_URL_TTL_MS
-		};
+		return createLiveView(info.sessionId, info.targets ?? [], options?.mode);
 	}
 	/** Close the shared (reuse/promoted) session, if one exists. */
 	async closeSession() {
@@ -1158,7 +1289,7 @@ async function _socketInner(executionId) {
 	const cached = _classPrivateFieldGet2(_sockets, this).get(executionId);
 	if (cached?.browserSessionId === stored.sessionId) return cached.session;
 	if (cached) _assertClassBrand(_BrowserConnector_brand, this, _dropSocket).call(this, executionId);
-	const session = await connectBrowserSession(browser, stored.sessionId, _classPrivateFieldGet2(_options, this).timeout);
+	const session = await connectBrowserSession(browser, stored.sessionId, { timeoutMs: _classPrivateFieldGet2(_options, this).timeout });
 	_classPrivateFieldGet2(_sockets, this).set(executionId, {
 		session,
 		browserSessionId: stored.sessionId,
@@ -1404,6 +1535,6 @@ async function _closeStoredSession(key) {
 	if (stored) await deleteBrowserSession(browser, stored.sessionId);
 }
 //#endregion
-export { connectUrl as C, CdpSession as S, connectBrowserSession as _, loadCdpSpec as a, getBrowserRecording as b, browserLinks as c, browserScrape as d, browserScreenshot as f, connectBrowser as g, BrowserRenderingError as h, DurableBrowserSessionStore as i, browserMarkdown as l, runQuickAction as m, DEFAULT_EXEC_SWEEP_IDLE_MS as n, browserContent as o, browserSnapshot as p, DEFAULT_SWEEP_IDLE_MS as r, browserExtract as s, BrowserConnector as t, browserPdf as u, createBrowserSession as v, listBrowserTargets as x, deleteBrowserSession as y };
+export { listBrowserTargets as C, CdpSession as D, CdpProtocolError as E, connectUrl as O, isMissingBrowserSession$1 as S, CdpConnection as T, connectBrowser as _, loadCdpSpec as a, deleteBrowserSession as b, browserExtract as c, browserPdf as d, browserScrape as f, BrowserRenderingError as g, runQuickAction as h, DurableBrowserSessionStore as i, validateConnectorArgs as k, browserLinks as l, browserSnapshot as m, DEFAULT_EXEC_SWEEP_IDLE_MS as n, createLiveView as o, browserScreenshot as p, DEFAULT_SWEEP_IDLE_MS as r, browserContent as s, BrowserConnector as t, browserMarkdown as u, connectBrowserSession as v, CDP_METHOD_NOT_FOUND as w, getBrowserRecording as x, createBrowserSession as y };
 
-//# sourceMappingURL=connector-CptFKzRh.js.map
+//# sourceMappingURL=connector-58XDGvc3.js.map