Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 184 additions & 5 deletions libs/cua-driver/rust/crates/cua-driver-core/src/page.rs
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,27 @@ pub trait PageBackend: Send + Sync {
javascript: &str,
) -> anyhow::Result<String>;

/// Evaluate `javascript` against an explicitly selected CDP page.
///
/// Backends that do not expose per-page CDP routing keep their legacy
/// behavior only when no explicit target was requested. A supplied port
/// or URL hint must never be silently ignored.
async fn execute_javascript_targeted(
&self,
pid: i32,
window_id: u32,
javascript: &str,
cdp_port: Option<u16>,
target_url_contains: Option<&str>,
) -> anyhow::Result<String> {
if cdp_port.is_some() || target_url_contains.is_some() {
anyhow::bail!(
"targeted execute_javascript is not implemented on this platform's page backend"
);
Comment on lines +88 to +91

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Implement cdp_port for non-macOS execute_javascript

On Windows and Linux, PageTool is registered with WindowsPageBackend/LinuxPageBackend, and those impls still only implement execute_javascript while their CDP paths read CUA_DRIVER_CDP_PORT. Because the new dispatcher always calls execute_javascript_targeted and this default bails whenever cdp_port is present, a call using the newly advertised execute_javascript cdp_port never reaches those CDP fallbacks; it fails with “not implemented” even though the platform can evaluate JS via CDP. Please either override this method in those backends to consume cdp_port or avoid advertising/accepting the option there.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 35fa5658. The shared cua_driver_core::cdp helper now supports unique case-insensitive URL targeting, and both Windows and Linux override execute_javascript_targeted to consume explicit cdp_port / target_url_contains. Calls without explicit targeting still use the existing bookmark/env behavior.

Validation:

  • core CDP selection tests: 2/2
  • core page tests: 3/3
  • macOS CDP tests: 6/6
  • macOS release check: passed
  • cargo check -p platform-windows --target x86_64-pc-windows-gnu: passed
  • cargo check -p platform-linux: passed in a clean Debian bookworm / Rust 1.92 container with X11/Wayland build dependencies.

The local macOS-to-Linux cross-check was initially blocked before our code by missing pkg-config sysroot; the native Linux container check above covers the actual backend.

}
self.execute_javascript(pid, window_id, javascript).await
}

/// Whether this backend can execute JS at all. False → the tool short-
/// circuits with a "not supported here" error; true → the backend may
/// still return an error at call time (e.g. CDP port not reachable).
Expand Down Expand Up @@ -251,11 +272,13 @@ fn def() -> &'static ToolDef {
},
"cdp_port": {
"type": "integer",
"description": "Optional, for insert_text/type_keystrokes only: use this exact CDP port instead of auto-discovering one from pid. Needed when the port was opened via the browser's own remote-debugging toggle rather than a launch-time flag, since that path may not answer the auto-discovery probe."
"minimum": 1,
"maximum": 65535,
"description": "Optional, for execute_javascript/insert_text/type_keystrokes: use this exact CDP port instead of auto-discovering one from pid. Needed when the port was opened via the browser's own remote-debugging toggle rather than a launch-time flag, since that path may not answer the auto-discovery probe."
},
"target_url_contains": {
"type": "string",
"description": "Optional, for insert_text/type_keystrokes only: pick the browser tab whose URL contains this substring instead of whichever tab is found first. Use this on a multi-tab browser — there's no built-in link between window_id and which tab a CDP call reaches."
"description": "Optional, for execute_javascript/insert_text/type_keystrokes: require exactly one browser tab whose URL contains this substring. Use this on a multi-tab browser — there's no built-in link between window_id and which tab a CDP call reaches."
},
"javascript": {
"type": "string",
Expand Down Expand Up @@ -374,7 +397,23 @@ impl Tool for PageTool {
Some(v) => v.to_owned(),
None => return ToolResult::error("Missing required parameter: javascript"),
};
match self.backend.execute_javascript(pid, window_id, &js).await {
let cdp_port = match optional_cdp_port(&args) {
Ok(value) => value,
Err(error) => return ToolResult::error(error),
};
let target_url_contains =
args.get("target_url_contains").and_then(|v| v.as_str());
match self
.backend
.execute_javascript_targeted(
pid,
window_id,
&js,
cdp_port,
target_url_contains,
)
.await
{
Ok(result) => ToolResult::text(result),
Err(e) => ToolResult::error(format!("{e}")),
}
Expand Down Expand Up @@ -420,7 +459,10 @@ impl Tool for PageTool {
Some(v) => v.to_owned(),
None => return ToolResult::error("Missing required parameter: text"),
};
let cdp_port = args.get("cdp_port").and_then(|v| v.as_u64()).map(|v| v as u16);
let cdp_port = match optional_cdp_port(&args) {
Ok(value) => value,
Err(error) => return ToolResult::error(error),
};
let target_url_contains = args.get("target_url_contains").and_then(|v| v.as_str());
match self.backend.insert_text(pid, window_id, &text, cdp_port, target_url_contains).await {
Ok(msg) => ToolResult::text(msg),
Expand All @@ -433,7 +475,10 @@ impl Tool for PageTool {
Some(v) => v.to_owned(),
None => return ToolResult::error("Missing required parameter: text"),
};
let cdp_port = args.get("cdp_port").and_then(|v| v.as_u64()).map(|v| v as u16);
let cdp_port = match optional_cdp_port(&args) {
Ok(value) => value,
Err(error) => return ToolResult::error(error),
};
let target_url_contains = args.get("target_url_contains").and_then(|v| v.as_str());
match self.backend.type_keystrokes(pid, window_id, &text, cdp_port, target_url_contains).await {
Ok(msg) => ToolResult::text(msg),
Expand Down Expand Up @@ -470,3 +515,137 @@ impl Tool for PageTool {
}
}
}

fn optional_cdp_port(args: &Value) -> Result<Option<u16>, String> {
let Some(value) = args.get("cdp_port") else {
return Ok(None);
};
let raw = value
.as_u64()
.ok_or_else(|| "Invalid parameter: cdp_port must be an integer from 1 to 65535".to_owned())?;
let port = u16::try_from(raw)
.ok()
.filter(|port| *port > 0)
.ok_or_else(|| format!("Invalid parameter: cdp_port {raw} outside 1..=65535"))?;
Ok(Some(port))
}

#[cfg(test)]
mod tests {
use super::*;
use std::sync::Mutex;

type TargetedCall = (i32, u32, String, Option<u16>, Option<String>);

#[derive(Default)]
struct RecordingBackend {
targeted: Mutex<Option<TargetedCall>>,
}

#[async_trait]
impl PageBackend for RecordingBackend {
async fn get_text(&self, _pid: i32, _window_id: u32) -> anyhow::Result<String> {
Ok(String::new())
}

async fn query_dom(
&self,
_pid: i32,
_window_id: u32,
_css_selector: &str,
_attributes: &[String],
) -> anyhow::Result<String> {
Ok(String::new())
}

async fn execute_javascript(
&self,
_pid: i32,
_window_id: u32,
_javascript: &str,
) -> anyhow::Result<String> {
anyhow::bail!("untargeted execute must not be used")
}

async fn execute_javascript_targeted(
&self,
pid: i32,
window_id: u32,
javascript: &str,
cdp_port: Option<u16>,
target_url_contains: Option<&str>,
) -> anyhow::Result<String> {
*self.targeted.lock().unwrap() = Some((
pid,
window_id,
javascript.to_owned(),
cdp_port,
target_url_contains.map(str::to_owned),
));
Ok("targeted".to_owned())
}
}

#[tokio::test]
async fn execute_javascript_forwards_explicit_page_target() {
let backend = Arc::new(RecordingBackend::default());
let tool = PageTool::new(backend.clone());

let result = tool
.invoke(serde_json::json!({
"pid": 42,
"window_id": 7,
"action": "execute_javascript",
"javascript": "document.title",
"cdp_port": 9333,
"target_url_contains": "#window-b"
}))
.await;

assert!(result.is_error.is_none());
assert_eq!(
*backend.targeted.lock().unwrap(),
Some((
42,
7,
"document.title".to_owned(),
Some(9333),
Some("#window-b".to_owned()),
))
);
}

#[test]
fn schema_advertises_targeted_execute_javascript() {
let schema = &def().input_schema["properties"];
assert_eq!(schema["cdp_port"]["minimum"], 1);
assert_eq!(schema["cdp_port"]["maximum"], 65535);
assert!(schema["cdp_port"]["description"]
.as_str()
.unwrap()
.contains("execute_javascript"));
assert!(schema["target_url_contains"]["description"]
.as_str()
.unwrap()
.contains("exactly one"));
}

#[tokio::test]
async fn rejects_out_of_range_cdp_port_before_dispatch() {
let backend = Arc::new(RecordingBackend::default());
let tool = PageTool::new(backend.clone());

let result = tool
.invoke(serde_json::json!({
"pid": 42,
"window_id": 7,
"action": "execute_javascript",
"javascript": "document.title",
"cdp_port": 65536
}))
.await;

assert_eq!(result.is_error, Some(true));
assert!(backend.targeted.lock().unwrap().is_none());
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,18 @@ impl CdpClient {
/// "Allow remote debugging?" confirmation the Chrome-toggle path does,
/// so there's no reason to route it through `CdpSessionCache`.
pub async fn evaluate(javascript: &str, port: u16) -> anyhow::Result<String> {
let mut session = CdpSession::connect(port, None).await?;
Self::evaluate_targeted(javascript, port, None).await
}

/// Evaluate JavaScript against the unique page target selected by
/// `target_url_contains`. An explicit hint never falls back to another
/// page when it is absent or ambiguous.
pub async fn evaluate_targeted(
javascript: &str,
port: u16,
target_url_contains: Option<&str>,
) -> anyhow::Result<String> {
let mut session = CdpSession::connect(port, target_url_contains).await?;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reuse the CDP session for targeted evaluation

When execute_javascript is called with an explicit cdp_port for Chrome's in-browser remote-debugging toggle, this creates a new WebSocket for every evaluation. The CdpSessionCache in this same module exists because that endpoint prompts on each new connection, and insert_text/type_keystrokes already reuse it; targeted execute_javascript will therefore reprompt or stall automation on repeated calls instead of reusing the approved session.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5c2b402d. Explicit targeted execute_javascript now goes through the existing ToolState.cdp_sessions cache, with the same stale-session eviction and one retry used by insert_text / type_keystrokes. The original untargeted Electron inspector path remains one-shot.

I added targeted_evaluate_reuses_browser_websocket, backed by a local fake CDP browser endpoint. Two targeted evaluations perform one HTTP discovery probe and share exactly one browser WebSocket connection while reattaching on that socket. The full macOS CDP test set is now 5/5 and the release check passes.

let obj = tokio::time::timeout(
Duration::from_secs(10),
session.call("Runtime.evaluate", serde_json::json!({
Expand Down Expand Up @@ -419,24 +430,77 @@ async fn ws_url_for_page_target(port: u16, target_url_contains: Option<&str>) ->
Ok((ws_url, target_url))
}

/// Pick the page target whose `url` contains `hint` (case-insensitive), or
/// fall back to the first page in `pages` if no hint is given or nothing
/// matches. Shared by both discovery paths (classic `/json` and
/// Pick the unique page target whose `url` contains `hint`
/// (case-insensitive), or the first page when no hint is given. Explicit
/// hints fail closed when zero or multiple pages match. Shared by both
/// discovery paths (classic `/json` and
/// `Target.getTargets`) since a browser with more than one tab open is
/// otherwise picked non-deterministically — CDP target ids carry no
/// relationship to the caller's `window_id`.
fn pick_target<'a>(pages: &[&'a serde_json::Value], hint: Option<&str>) -> Option<&'a serde_json::Value> {
if let Some(hint) = hint {
let hint_lower = hint.to_ascii_lowercase();
if let Some(t) = pages.iter().find(|t| {
t.get("url")
.and_then(|v| v.as_str())
.is_some_and(|url| url.to_ascii_lowercase().contains(&hint_lower))
}) {
return Some(t);
match hint {
None => pages.first().copied(),
Some(hint) => {
let hint_lower = hint.to_ascii_lowercase();
let mut matches = pages.iter().copied().filter(|target| {
target
.get("url")
.and_then(|value| value.as_str())
.is_some_and(|url| url.to_ascii_lowercase().contains(&hint_lower))
});
let target = matches.next()?;
if matches.next().is_some() {
return None;
}
Some(target)
}
}
pages.first().copied()
}

#[cfg(test)]
mod tests {
use super::pick_target;

fn pages() -> Vec<serde_json::Value> {
vec![
serde_json::json!({ "type": "page", "url": "app://fixture/#window-a" }),
serde_json::json!({ "type": "page", "url": "app://fixture/#window-b" }),
]
}

#[test]
fn explicit_target_hint_selects_one_page() {
let pages = pages();
let refs = pages.iter().collect::<Vec<_>>();
assert_eq!(
pick_target(&refs, Some("#WINDOW-B")).and_then(|target| target["url"].as_str()),
Some("app://fixture/#window-b")
);
}

#[test]
fn explicit_target_hint_never_falls_back() {
let pages = pages();
let refs = pages.iter().collect::<Vec<_>>();
assert!(pick_target(&refs, Some("#missing")).is_none());
}

#[test]
fn ambiguous_target_hint_fails_closed() {
let pages = pages();
let refs = pages.iter().collect::<Vec<_>>();
assert!(pick_target(&refs, Some("app://fixture/")).is_none());
}

#[test]
fn omitted_target_hint_keeps_legacy_first_page_behavior() {
let pages = pages();
let refs = pages.iter().collect::<Vec<_>>();
assert_eq!(
pick_target(&refs, None).and_then(|target| target["url"].as_str()),
Some("app://fixture/#window-a")
);
}
}

fn parse_cdp_result(obj: &serde_json::Value) -> anyhow::Result<String> {
Expand Down
15 changes: 15 additions & 0 deletions libs/cua-driver/rust/crates/platform-macos/src/tools/page.rs
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,21 @@ impl PageBackend for MacOsPageBackend {
execute_js(javascript, &bundle_id, pid, window_id).await
}

async fn execute_javascript_targeted(
&self,
pid: i32,
window_id: u32,
javascript: &str,
cdp_port: Option<u16>,
target_url_contains: Option<&str>,
) -> anyhow::Result<String> {
if cdp_port.is_none() && target_url_contains.is_none() {
return self.execute_javascript(pid, window_id, javascript).await;
}
let port = resolve_cdp_port(pid, cdp_port, "execute_javascript").await?;
CdpClient::evaluate_targeted(javascript, port, target_url_contains).await
}

async fn click_element(
&self,
pid: i32,
Expand Down