Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(cua-driver): publish isolated browser session lifetime in browser_prepare (#5183)

injaneitybf6ac21d2d3c
diff --git a/docs/content/docs/cua-driver/guides/browsers.mdx b/docs/content/docs/cua-driver/guides/browsers.mdx
index 47b9826e9f..96c5aaea44 100644
--- a/docs/content/docs/cua-driver/guides/browsers.mdx
+++ b/docs/content/docs/cua-driver/guides/browsers.mdx
@@ -93,6 +93,18 @@ deleted when the session ends; use `{"mode": "isolated_named", "name": "research
to keep it. Do not pass remote-debugging flags through `launch_app`: they are
refused.
+The result's optional `lifecycle` object describes how long the browser
+process lives: `owner` is `session`, `idle_expires_in_seconds` is how long the
+session may stay idle after this call before it and the browser end,
+`process_ends_with_session` is `true`, and
+`profile_persists_after_session` is `true` only for `isolated_named`. The
+value is advisory, not a lease. `get_session` reports the remaining time later
+but does not keep the browser alive, and explicit `end_session`, disconnect,
+revocation, or shutdown ends the browser earlier. A named profile keeps its
+files, not the process or its open pages. Attachments to an existing profile
+or endpoint the driver did not launch, and sessions already ending, have no
+`lifecycle`.
+
## Attach to a logged-in profile
Use an existing Chrome or Edge profile only when the task needs its signed-in
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
index 8ff533d7cc..4e58b0b3cc 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
@@ -77,7 +77,7 @@ Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
## `browser_prepare`
-Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {"kind":"existing_profile"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.
+Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {"kind":"existing_profile"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.
Effect: destructive. Platforms: macOS, Linux, Windows.
diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
index fedfb1a582..85166d4d40 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
@@ -159,6 +159,18 @@ or terminates an existing personal profile. The result returns a
`prepared_pid`; list that process's windows and bind the new `(pid,
window_id)`.
+The result's optional `lifecycle` object describes how long the browser
+process lives: `owner` is `session`, `idle_expires_in_seconds` is how long the
+session may stay idle after this call before it and the browser end,
+`process_ends_with_session` is `true`, and
+`profile_persists_after_session` is `true` only for `isolated_named`. The
+value is advisory, not a lease. `get_session` reports the remaining time later
+but does not keep the browser alive, and explicit `end_session`, disconnect,
+revocation, or shutdown ends the browser earlier. A named profile keeps its
+files, not the process or its open pages. Attachments to an existing profile
+or endpoint the driver did not launch, and sessions already ending, have no
+`lifecycle`.
+
### Existing profile
Attaching to an authenticated profile requires explicit trusted launch or host
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
index be1b121829..dbb2fe6535 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
@@ -17,7 +17,10 @@ use crate::tool_args::ArgsExt;
use super::cdp_ws::CdpConnection;
use super::download::BrowserDownloadTool;
use super::engine::{BrowserEngine, BrowserTabScreenshot};
-use super::platform::{BrowserVisualActionKind, PrepareProfile, PrepareRequest, PrepareStrategy};
+use super::platform::{
+ BrowserVisualActionKind, PrepareAction, PrepareProfile, PrepareProfileMode, PrepareRequest,
+ PrepareStrategy,
+};
use super::pointer::BrowserPointerTool;
use super::refusal::{BrowserRefusal, BrowserRefusalCode};
use super::session_schema as schema_session;
@@ -642,7 +645,11 @@ impl BrowserPrepareTool {
background_unavailable unless delivery_mode is \"foreground\" (the app that \
was in front is brought back afterwards) or the browser window is on another \
Space than the user's, where it attaches in the background while the driver \
- reverts the browser's own brief activations."
+ reverts the browser's own brief activations. A driver-owned isolated launch \
+ result carries an advisory lifecycle object: the browser process ends with the \
+ calling session after idle_expires_in_seconds without session activity, an \
+ isolated_named profile persists after the session and an isolated_new profile \
+ does not, and explicit end, disconnect, revocation or shutdown end it earlier."
.into(),
input_schema: json!({
"type": "object",
@@ -747,11 +754,17 @@ impl Tool for BrowserPrepareTool {
Err(error) => error,
};
}
+ let profile_mode = profile.as_ref().map(|profile| profile.mode);
+ let transport_session = args.opt_str("_transport_session_id");
+ let owner_transport = transport_session
+ .clone()
+ .filter(|owner| !owner.is_empty())
+ .unwrap_or_else(|| session.clone());
let request = PrepareRequest {
pid,
window_id: args.opt_u64("window_id"),
- session,
- transport_session: args.opt_str("_transport_session_id"),
+ session: session.clone(),
+ transport_session,
strategy,
profile,
allow_launch,
@@ -760,7 +773,10 @@ impl Tool for BrowserPrepareTool {
match self.engine.prepare_browser(request).await {
Ok(outcome) => {
let prepared = outcome.endpoint.is_some();
- ToolResult::text(format!(
+ let lifecycle = profile_mode
+ .filter(|_| outcome.action == PrepareAction::LaunchedIsolatedBrowser)
+ .and_then(|mode| isolated_session_lifecycle(&session, &owner_transport, mode));
+ let text = format!(
"browser_prepare: {} — {}",
if prepared {
"endpoint available"
@@ -768,8 +784,8 @@ impl Tool for BrowserPrepareTool {
"no endpoint"
},
outcome.message
- ))
- .with_structured(json!({
+ );
+ let mut structured = json!({
"status": "ok",
"prepared": prepared,
"action": outcome.action,
@@ -779,7 +795,11 @@ impl Tool for BrowserPrepareTool {
"prepared_pid": outcome.prepared_pid,
"side_effects": outcome.side_effects,
"attachment": outcome.attachment,
- }))
+ });
+ if let Some(lifecycle) = lifecycle {
+ structured["lifecycle"] = lifecycle;
+ }
+ ToolResult::text(text).with_structured(structured)
}
Err(refusal) if refusal.code == BrowserRefusalCode::BackgroundUnavailable => {
let reason = refusal
@@ -804,6 +824,25 @@ impl Tool for BrowserPrepareTool {
}
}
+fn isolated_session_lifecycle(
+ session: &str,
+ owner_transport: &str,
+ mode: PrepareProfileMode,
+) -> Option<Value> {
+ let snapshot = crate::session::session_snapshot(
+ session,
+ owner_transport,
+ crate::session::DEFAULT_SESSION_IDLE_TTL,
+ )
+ .filter(|snapshot| !snapshot.ending)?;
+ Some(json!({
+ "owner": "session",
+ "idle_expires_in_seconds": snapshot.idle_ttl.as_secs(),
+ "process_ends_with_session": true,
+ "profile_persists_after_session": mode == PrepareProfileMode::IsolatedNamed,
+ }))
+}
+
// ── browser_navigate ─────────────────────────────────────────────────────────
pub struct BrowserNavigateTool {
@@ -2596,7 +2635,9 @@ impl Tool for BrowserSetInputFilesTool {
#[cfg(test)]
mod tests {
use super::*;
- use crate::browser::platform::{BrowserPlatform, PrepareOutcome, PrepareRequest};
+ use crate::browser::platform::{
+ BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest,
+ };
use crate::browser::types::{
BrowserClassification, BrowserEngineFamily, BrowserProduct, NativeWindowInfo,
OwnedEndpoint, ProcessFingerprint,
@@ -2605,7 +2646,31 @@ mod tests {
/// Minimal adapter: pid 1 is a CDP-capable browser with no endpoint
/// (setup required); pid 2 is not a browser; pid 3 is Safari-like
/// (browser, no CDP). Prepare requires consent.
- struct MockPlatform;
+ #[derive(Default)]
+ struct MockPlatform {
+ devtools: Option<std::net::TcpListener>,
+ launch_delay: std::time::Duration,
+ }
+
+ impl MockPlatform {
+ fn devtools_endpoint(&self, pid: i64) -> Option<OwnedEndpoint> {
+ use crate::browser::types::{
+ EndpointOwnershipMethod, EndpointOwnershipProof, EndpointTransport,
+ };
+ let port = self.devtools.as_ref()?.local_addr().unwrap().port();
+ Some(OwnedEndpoint {
+ ws_url: format!("ws://127.0.0.1:{port}/devtools/browser/mock"),
+ http_port: Some(port),
+ transport: EndpointTransport::DevToolsActivePort,
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::DevtoolsActivePortsFile,
+ owner_pid: pid,
+ listener_pid: None,
+ detail: None,
+ },
+ })
+ }
+ }
#[async_trait]
impl BrowserPlatform for MockPlatform {
@@ -2687,9 +2752,9 @@ mod tests {
async fn discover_owned_endpoint(
&self,
- _pid: i64,
+ pid: i64,
) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
- Ok(None)
+ Ok(self.devtools_endpoint(pid))
}
async fn process_fingerprint(
@@ -2705,17 +2770,125 @@ mod tests {
async fn prepare_endpoint(
&self,
- _request: PrepareRequest,
+ request: PrepareRequest,
) -> Result<PrepareOutcome, BrowserRefusal> {
- Err(BrowserRefusal::new(
- BrowserRefusalCode::BrowserRequiresSetup,
- "mock endpoint needs acting setup",
- ))
+ let pid = request.pid.expect("prepare_endpoint receives a pid");
+ let endpoint = self.devtools_endpoint(pid).ok_or_else(|| {
+ BrowserRefusal::new(
+ BrowserRefusalCode::BrowserRequiresSetup,
+ "mock endpoint needs acting setup",
+ )
+ })?;
+ Ok(PrepareOutcome {
+ action: PrepareAction::AlreadyPrepared,
+ endpoint: Some(endpoint),
+ message: "mock endpoint already exists".into(),
+ prepared_pid: Some(pid),
+ side_effects: Default::default(),
+ attachment: None,
+ })
+ }
+
+ fn isolated_browser_executable(&self) -> Result<String, BrowserRefusal> {
+ match self.devtools {
+ Some(_) => Ok("sleep".into()),
+ None => Err(BrowserRefusal::new(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ "mock has no isolated browser executable",
+ )),
+ }
+ }
+
+ fn spawn_isolated_browser(
+ &self,
+ _command: std::process::Command,
+ profile: &std::path::Path,
+ ) -> Result<Box<dyn crate::browser::platform::IsolatedBrowserProcess>, BrowserRefusal>
+ {
+ std::thread::sleep(self.launch_delay);
+ let port = self.devtools.as_ref().unwrap().local_addr().unwrap().port();
+ std::fs::write(
+ profile.join("DevToolsActivePort"),
+ format!("{port}\n/devtools/browser/mock\n"),
+ )
+ .unwrap();
+ let mut stand_in = std::process::Command::new("sleep");
+ stand_in.arg("30");
+ #[cfg(unix)]
+ std::os::unix::process::CommandExt::process_group(&mut stand_in, 0);
+ Ok(Box::new(stand_in.spawn().unwrap()))
}
}
fn engine() -> Arc<BrowserEngine> {
- BrowserEngine::new(Arc::new(MockPlatform))
+ BrowserEngine::new(Arc::new(MockPlatform::default()))
+ }
+
+ fn launching_engine() -> Arc<BrowserEngine> {
+ slow_launching_engine(std::time::Duration::ZERO)
+ }
+
+ fn slow_launching_engine(launch_delay: std::time::Duration) -> Arc<BrowserEngine> {
+ static PROFILE_ROOT: std::sync::Once = std::sync::Once::new();
+ PROFILE_ROOT.call_once(|| {
+ std::env::set_var(
+ "CUA_DRIVER_BROWSER_PROFILE_ROOT",
+ std::env::temp_dir().join("cua-browser-tools-profiles"),
+ )
+ });
+ BrowserEngine::new(Arc::new(MockPlatform {
+ devtools: Some(std::net::TcpListener::bind("127.0.0.1:0").unwrap()),
+ launch_delay,
+ }))
+ }
+
+ fn start_lifecycle_session(idle_ttl: Option<std::time::Duration>) -> (String, String) {
+ use crate::session::{SessionClientKind, SessionTransport};
+ let session = format!("browser-lifecycle-{}", uuid::Uuid::new_v4());
+ let owner = format!("browser-lifecycle-owner-{}", uuid::Uuid::new_v4());
+ match idle_ttl {
+ Some(ttl) => crate::session::activate_session_with_ttl(
+ &session,
+ None,
+ &owner,
+ false,
+ SessionTransport::McpStdio,
+ SessionClientKind::Mcp,
+ ttl,
+ ),
+ None => crate::session::activate_session(
+ &session,
+ None,
+ &owner,
+ false,
+ SessionTransport::McpStdio,
+ SessionClientKind::Mcp,
+ ),
+ }
+ .unwrap();
+ (session, owner)
+ }
+
+ async fn prepare_isolated(
+ engine: &Arc<BrowserEngine>,
+ session: &str,
+ owner: &str,
+ profile: Value,
+ ) -> Value {
+ let result = BrowserPrepareTool::new(engine.clone())
+ .invoke(json!({
+ "allow_launch": true,
+ "profile": profile,
+ "session": session,
+ "_transport_session_id": owner
+ }))
+ .await;
+ let structured = structured(&result).clone();
+ assert_eq!(
+ structured["action"], "launched_isolated_browser",
+ "{structured}"
+ );
+ structured
}
fn structured(result: &ToolResult) -> &Value {
@@ -3064,6 +3237,124 @@ mod tests {
);
}
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn isolated_new_publishes_the_session_effective_idle_ttl() {
+ let engine = launching_engine();
+ for (idle_ttl, expected) in [
+ (None, crate::session::DEFAULT_SESSION_IDLE_TTL.as_secs()),
+ (Some(std::time::Duration::from_secs(1234)), 1234),
+ ] {
+ let (session, owner) = start_lifecycle_session(idle_ttl);
+ let prepared =
+ prepare_isolated(&engine, &session, &owner, json!({ "mode": "isolated_new" }))
+ .await;
+ assert_eq!(
+ prepared["lifecycle"],
+ json!({
+ "owner": "session",
+ "idle_expires_in_seconds": expected,
+ "process_ends_with_session": true,
+ "profile_persists_after_session": false
+ })
+ );
+ crate::session::end_session(&session);
+ }
+ }
+
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn preparation_longer_than_the_idle_ttl_still_publishes_the_ttl() {
+ let engine = slow_launching_engine(std::time::Duration::from_millis(2100));
+ let (session, owner) = start_lifecycle_session(Some(std::time::Duration::from_secs(1)));
+ let prepared =
+ prepare_isolated(&engine, &session, &owner, json!({ "mode": "isolated_new" })).await;
+ assert_eq!(prepared["lifecycle"]["idle_expires_in_seconds"], 1);
+ crate::session::end_session(&session);
+ }
+
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn ending_session_gets_no_lifecycle() {
+ use crate::session::{SessionClientKind, SessionTransport};
+ let engine = launching_engine();
+ let (session, owner) = start_lifecycle_session(None);
+ let live =
+ prepare_isolated(&engine, &session, &owner, json!({ "mode": "isolated_new" })).await;
+ assert_eq!(live["lifecycle"]["owner"], "session", "{live}");
+ let guard = crate::session::begin_session_dispatch(
+ &session,
+ None,
+ &owner,
+ false,
+ SessionTransport::McpStdio,
+ SessionClientKind::Mcp,
+ )
+ .unwrap();
+ assert!(crate::session::end_session_for_owner(&session, &owner));
+ let prepared =
+ prepare_isolated(&engine, &session, &owner, json!({ "mode": "isolated_new" })).await;
+ assert!(prepared.get("lifecycle").is_none(), "{prepared}");
+ drop(guard);
+ }
+
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn isolated_named_profile_persists_after_session() {
+ let engine = launching_engine();
+ let (session, owner) = start_lifecycle_session(None);
+ let name = format!("lifecycle-{}", uuid::Uuid::new_v4().simple());
+ let prepared = prepare_isolated(
+ &engine,
+ &session,
+ &owner,
+ json!({ "mode": "isolated_named", "name": name }),
+ )
+ .await;
+ assert_eq!(
+ prepared["lifecycle"]["profile_persists_after_session"],
+ true
+ );
+ assert_eq!(prepared["lifecycle"]["process_ends_with_session"], true);
+ crate::session::end_session(&session);
+ let root = std::env::var_os("CUA_DRIVER_BROWSER_PROFILE_ROOT").unwrap();
+ std::fs::remove_dir_all(std::path::Path::new(&root).join(name)).unwrap();
+ }
+
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn lifecycle_requires_a_driver_launch_owned_by_a_visible_session() {
+ let engine = launching_engine();
+ let (session, owner) = start_lifecycle_session(None);
+ let discovered = BrowserPrepareTool::new(engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "allow_launch": true,
+ "profile": { "mode": "isolated_new" },
+ "session": session,
+ "_transport_session_id": owner
+ }))
+ .await;
+ let discovered = structured(&discovered);
+ assert_eq!(discovered["action"], "already_prepared");
+ assert!(discovered.get("lifecycle").is_none(), "{discovered}");
+
+ let foreign_owner = format!("browser-lifecycle-foreign-{}", uuid::Uuid::new_v4());
+ let foreign = prepare_isolated(
+ &engine,
+ &session,
+ &foreign_owner,
+ json!({ "mode": "isolated_new" }),
+ )
+ .await;
+ assert!(foreign.get("lifecycle").is_none(), "{foreign}");
+
+ let owned =
+ prepare_isolated(&engine, &session, &owner, json!({ "mode": "isolated_new" })).await;
+ assert_eq!(owned["lifecycle"]["owner"], "session");
+ crate::session::end_session(&session);
+ }
+
#[tokio::test]
async fn mutations_on_unknown_targets_refuse_binding_stale() {
let e = engine();
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/session.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/session.rs
index 7f2c43cd22..7acb98101f 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/session.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/session.rs
@@ -369,6 +369,7 @@ pub struct LifecycleSessionSnapshot {
pub ending: bool,
pub started_for: Duration,
pub idle: Duration,
+ pub idle_ttl: Duration,
pub expires_in: Duration,
}
@@ -727,6 +728,7 @@ pub fn session_snapshot(
ending: record.pending_end.is_some(),
started_for: record.started_at.elapsed(),
idle,
+ idle_ttl: ttl,
expires_in: ttl.saturating_sub(idle),
})
}
@@ -817,6 +819,7 @@ pub fn list_session_snapshots_with_prefix(
.into_iter()
.map(|(_, runtime_id, record)| {
let idle = session_idle_duration(&runtime_id).unwrap_or_default();
+ let idle_ttl = record.idle_ttl.unwrap_or(ttl);
LifecycleSessionSnapshot {
runtime_id,
public_label: record.public_label,
@@ -827,7 +830,8 @@ pub fn list_session_snapshots_with_prefix(
ending: record.pending_end.is_some(),
started_for: record.started_at.elapsed(),
idle,
- expires_in: record.idle_ttl.unwrap_or(ttl).saturating_sub(idle),
+ idle_ttl,
+ expires_in: idle_ttl.saturating_sub(idle),
}
})
.collect()
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
index d0fdf9321e..a3a86d8420 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
@@ -2447,7 +2447,7 @@
"read_only": true
},
{
- "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.",
+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.",
"destructive": true,
"idempotent": false,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
index 212bf676ce..a3d853284e 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
@@ -2094,7 +2094,7 @@
"read_only": true
},
{
- "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.",
+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.",
"destructive": true,
"idempotent": false,
"input_schema": {
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
index 2b0b9407d0..be2432fd00 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
@@ -2142,7 +2142,7 @@
"read_only": true
},
{
- "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.",
+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier.",
"destructive": true,
"idempotent": false,
"input_schema": {