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.

fix(cua-driver): name current snapshots on a token-only refusal, and refuse a bare row a re-read orphaned (#6259)

injaneity0cdcec94bc99
diff --git a/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.md b/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.md
index 41f39f8314..90434cc913 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.md
@@ -53,7 +53,7 @@ The accessibility model may lag or disagree with rendered state: Electron text s
## Act once
-Use the `element_token` `<snapshot_id>:N` for row `[N]` of the latest snapshot of the intended window, for example `"s0000002a:11"`. A bare `"11"` is accepted only together with `window_id` and then means row 11 of that window's current snapshot. Do not mix a row number from one read with the `snapshot_id` of another. A later snapshot can invalidate a pending action, including when another agent observes the same window.
+Use the `element_token` `<snapshot_id>:N` for row `[N]` of the latest snapshot of the intended window, for example `"s0000002a:11"`. A bare `"11"` is accepted only together with `window_id`, and only while the current snapshot is the one your read printed: as soon as that window is read again the number no longer says which read it came from, and the call is refused with `stale_bare_row` naming the current token for that row. It is never re-pointed at whatever element now sits at row 11. Do not mix a row number from one read with the `snapshot_id` of another. A later snapshot can invalidate a pending action, including when another agent observes the same window.
Example CLI window action, with IDs and token replaced from the preceding response:
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/element_token.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/element_token.rs
index 14c630bd0d..2a27c48d53 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/element_token.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/element_token.rs
@@ -63,38 +63,143 @@ impl<T> ResolvedElement<T> {
pub const STALE_TOKEN_WITHOUT_PID: &str =
"element_token is stale or unknown; call get_window_state again to refresh";
-/// The refusal for [`STALE_TOKEN_WITHOUT_PID`]: `stale_element_token`, with
-/// the hint that a current token names its own pid.
-pub fn stale_token_without_pid() -> ToolResult {
- ToolResult::error(format!(
- "{STALE_TOKEN_WITHOUT_PID} (a current token names its own pid)."
- ))
- .with_structured(serde_json::json!({
+/// A snapshot a refusal names as current, so the caller can tell whether it
+/// already holds a newer one instead of re-reading blind.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CurrentSnapshot {
+ pub snapshot_id: String,
+ pub window_id: u64,
+}
+
+/// `current snapshots for pid 7: s0000002a (window 100)` — the phrase every
+/// stale refusal shares, so both refusal shapes name the same thing the same
+/// way.
+pub fn current_snapshots_phrase(pid: i32, current: &[CurrentSnapshot]) -> String {
+ if current.is_empty() {
+ return format!("current snapshots for pid {pid}: none");
+ }
+ format!(
+ "current snapshots for pid {pid}: {}",
+ current
+ .iter()
+ .map(|snapshot| format!("{} (window {})", snapshot.snapshot_id, snapshot.window_id))
+ .collect::<Vec<_>>()
+ .join(", ")
+ )
+}
+
+/// `current_snapshots` as structured content: the same array both refusal
+/// shapes carry, so a client reads one field whichever path refused.
+pub fn current_snapshots_json(current: &[CurrentSnapshot]) -> serde_json::Value {
+ serde_json::Value::Array(
+ current
+ .iter()
+ .map(|snapshot| {
+ serde_json::json!({
+ "snapshot_id": snapshot.snapshot_id,
+ "window_id": snapshot.window_id,
+ })
+ })
+ .collect(),
+ )
+}
+
+/// What a call's `element_token` could be attributed to.
+#[derive(Clone, Debug, Default)]
+pub struct TokenOwner {
+ /// The process the token's snapshot was minted for, current or retired.
+ pub pid: Option<i32>,
+ /// The process's current snapshots, when `pid` is known.
+ pub current: Vec<CurrentSnapshot>,
+ /// Whether the token still names a snapshot the runtime holds. A token for
+ /// a retired snapshot can be attributed to its process but must not be
+ /// acted on, so the call is refused rather than handed a pid.
+ pub live: bool,
+}
+
+/// The refusal for [`STALE_TOKEN_WITHOUT_PID`]: `stale_element_token`, naming
+/// the current snapshots whenever the token can be attributed to a process.
+///
+/// A refusal is the caller's chance to recover without a blind re-read, so the
+/// token-only path reports the same `current_snapshots` the pid-carrying
+/// refusal does. When the token cannot be attributed to any process — it was
+/// never minted here, or it is malformed — nothing is invented: the message
+/// says so instead.
+pub fn stale_token_without_pid(owner: TokenOwner) -> ToolResult {
+ let message = match (owner.pid, owner.current.is_empty()) {
+ (Some(pid), false) => format!(
+ "{STALE_TOKEN_WITHOUT_PID} (a current token names its own pid); {}",
+ current_snapshots_phrase(pid, &owner.current)
+ ),
+ (Some(pid), true) => format!(
+ "{STALE_TOKEN_WITHOUT_PID}; pid {pid} has no current snapshot. Call get_window_state \
+ for the window you mean, then use the element_token it prints."
+ ),
+ (None, _) => format!(
+ "{STALE_TOKEN_WITHOUT_PID}. This token cannot be attributed to a pid: this runtime \
+ never minted it, or the snapshot it names has been gone long enough that the \
+ process is no longer known."
+ ),
+ };
+ let mut structured = serde_json::json!({
"status": "refused",
- "refusal": { "code": "stale_element_token", "message": STALE_TOKEN_WITHOUT_PID },
- }))
+ "refusal": { "code": "stale_element_token", "message": message },
+ });
+ if let Some(pid) = owner.pid {
+ structured["pid"] = pid.into();
+ structured["current_snapshots"] = current_snapshots_json(&owner.current);
+ }
+ ToolResult::error(message).with_structured(structured)
+}
+
+/// [`stale_token_without_pid`] for a caller that cannot attribute the token at
+/// all (no snapshot store in reach).
+pub fn stale_token_unattributed() -> ToolResult {
+ stale_token_without_pid(TokenOwner::default())
}
/// Fill a missing `pid` from the call's `element_token`. A token names its
/// snapshot, and so its window and process, so a token-only call needs no
/// pid. An explicit `pid` wins and a call without a token is left as is (the
/// tool reports its own missing-pid error). A token whose snapshot is gone
-/// is refused as `stale_element_token` rather than as a missing pid.
+/// is refused as `stale_element_token` rather than as a missing pid, and that
+/// refusal names the current snapshots of the process the token belonged to.
pub fn fill_pid_from_token(
args: &mut serde_json::Value,
- pid_for_token: impl FnOnce(&serde_json::Value) -> Option<i32>,
+ owner_for_token: impl FnOnce(&serde_json::Value) -> TokenOwner,
) -> Result<(), ToolResult> {
let present = |key: &str| args.get(key).is_some_and(|value| !value.is_null());
if present("pid") || !present("element_token") {
return Ok(());
}
- let pid = pid_for_token(args).ok_or_else(stale_token_without_pid)?;
+ let owner = owner_for_token(args);
+ // Fail closed: only a token naming a snapshot the runtime still holds may
+ // be turned into a pid, so a stale token never reaches a tool that would
+ // act on it. The refusal still names what is current for that process.
+ let Some(pid) = owner.pid.filter(|_| owner.live) else {
+ return Err(stale_token_without_pid(owner));
+ };
if let Some(object) = args.as_object_mut() {
object.insert("pid".to_owned(), pid.into());
}
Ok(())
}
+/// [`fill_pid_from_token`] for a caller whose resolver reports only a pid.
+pub fn fill_pid_from_token_with(
+ args: &mut serde_json::Value,
+ pid_for_token: impl FnOnce(&serde_json::Value) -> Option<i32>,
+) -> Result<(), ToolResult> {
+ fill_pid_from_token(args, |args| {
+ let pid = pid_for_token(args);
+ TokenOwner {
+ pid,
+ current: Vec::new(),
+ live: pid.is_some(),
+ }
+ })
+}
+
pub(crate) fn refusal(code: &str, message: String) -> ToolResult {
ToolResult::error(message.clone()).with_structured(serde_json::json!({
"status": "refused", "refusal": { "code": code, "message": message }
@@ -108,7 +213,12 @@ mod tests {
#[test]
fn fill_pid_from_token_resolves_only_token_only_calls() {
let mut token_only = serde_json::json!({ "element_token": "s00000001:2" });
- fill_pid_from_token(&mut token_only, |_| Some(42)).unwrap();
+ fill_pid_from_token(&mut token_only, |_| TokenOwner {
+ pid: Some(42),
+ current: Vec::new(),
+ live: true,
+ })
+ .unwrap();
assert_eq!(token_only["pid"], 42);
let mut explicit = serde_json::json!({ "pid": 7, "element_token": "s00000001:2" });
@@ -120,7 +230,7 @@ mod tests {
assert!(no_token.get("pid").is_none());
let mut stale = serde_json::json!({ "pid": null, "element_token": "s00000009:0" });
- let refused = fill_pid_from_token(&mut stale, |_| None).unwrap_err();
+ let refused = fill_pid_from_token(&mut stale, |_| TokenOwner::default()).unwrap_err();
let structured = refused.structured_content.unwrap();
assert_eq!(structured["refusal"]["code"], "stale_element_token");
}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs
index 944f54e8dc..513a0dec88 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs
@@ -1,10 +1,10 @@
use crate::element_token::{
- format_snapshot_id, parse_token, refusal, token_for, ResolvedElement, LRU_CAP_PER_PID,
- STALE_TOKEN_ERROR,
+ current_snapshots_json, current_snapshots_phrase, format_snapshot_id, parse_token, refusal,
+ token_for, CurrentSnapshot, ResolvedElement, TokenOwner, LRU_CAP_PER_PID, STALE_TOKEN_ERROR,
};
use crate::protocol::ToolResult;
use std::any::Any;
-use std::collections::HashMap;
+use std::collections::{HashMap, VecDeque};
use std::sync::{Arc, Mutex, OnceLock, Weak};
/// Reserved dispatch argument marking window-relative pixels as native
@@ -139,31 +139,19 @@ fn screenshot_context_refusal(
}))
}
-fn stale_token_refusal<S>(pid: i32, lane: &[Snapshot<S>]) -> ToolResult {
- let current: Vec<_> = lane
- .iter()
- .map(|snapshot| (format_snapshot_id(snapshot.id), snapshot.window_id))
- .collect();
- let message = match current.as_slice() {
- [] => format!("{STALE_TOKEN_ERROR}; pid {pid} has no current snapshot"),
- current => format!(
- "{STALE_TOKEN_ERROR}; current snapshots for pid {pid}: {}",
- current
- .iter()
- .map(|(snapshot_id, window_id)| format!("{snapshot_id} (window {window_id})"))
- .collect::<Vec<_>>()
- .join(", ")
- ),
+fn stale_token_refusal(pid: i32, current: &[CurrentSnapshot]) -> ToolResult {
+ let message = if current.is_empty() {
+ format!("{STALE_TOKEN_ERROR}; pid {pid} has no current snapshot")
+ } else {
+ format!(
+ "{STALE_TOKEN_ERROR}; {}",
+ current_snapshots_phrase(pid, current)
+ )
};
ToolResult::error(message.clone()).with_structured(serde_json::json!({
"status": "refused",
"refusal": { "code": "stale_element_token", "message": message },
- "current_snapshots": current
- .iter()
- .map(|(snapshot_id, window_id)| {
- serde_json::json!({ "snapshot_id": snapshot_id, "window_id": window_id })
- })
- .collect::<Vec<_>>(),
+ "current_snapshots": current_snapshots_json(current),
}))
}
@@ -181,46 +169,144 @@ fn zoom_context_refusal(pid: i32, window_id: Option<u64>) -> ToolResult {
}))
}
-/// The snapshot a bare row number refers to: the current snapshot of the
-/// named window, or the process's only snapshot when no window is named.
-fn row_snapshot<S: SnapshotPayload>(
+/// Why a bare row number did not resolve to exactly one read.
+enum RowMiss<'a, S> {
+ /// No snapshot of the window (and no single snapshot of the process).
+ NoSnapshot,
+ /// This caller has read the window again since, so the row no longer names
+ /// the read it was printed in.
+ Reread(&'a Snapshot<S>),
+ /// This caller has not read the window in this session, so no read of
+ /// theirs is behind the row.
+ NotRead(&'a Snapshot<S>),
+ /// This caller read the window once, but a later read (theirs or another
+ /// caller's) replaced the snapshot that printed the row.
+ Replaced(&'a Snapshot<S>),
+ /// Several windows, none named.
+ Ambiguous,
+}
+
+/// Why a bare row number could not be attributed to a read of this caller's.
+impl<S> RowMiss<'_, S> {
+ fn as_str(&self) -> &'static str {
+ match self {
+ Self::NoSnapshot => "no_current_snapshot",
+ Self::Reread(_) => "stale_bare_row",
+ Self::NotRead(_) => "unattributed_bare_row",
+ Self::Replaced(_) => "stale_bare_row",
+ Self::Ambiguous => "ambiguous_window",
+ }
+ }
+
+ fn snapshot(&self) -> Option<&Snapshot<S>> {
+ match self {
+ Self::Reread(snapshot) | Self::NotRead(snapshot) | Self::Replaced(snapshot) => {
+ Some(snapshot)
+ }
+ Self::NoSnapshot | Self::Ambiguous => None,
+ }
+ }
+}
+
+/// The snapshot a bare row number refers to: the snapshot this caller's single
+/// read of the window printed, which must still be the window's current one.
+///
+/// A bare row number carries no snapshot id, so the only read it can honestly
+/// name is one the caller made and that nothing has since replaced. Every other
+/// case is refused, because the alternative is acting on whatever element now
+/// occupies that row — a different element, reported as a success. The caller
+/// recovers by passing the full `s<id>:<row>` token it needs to be exact.
+fn row_snapshot<'a, S: SnapshotPayload>(
pid: i32,
- lane: &[Snapshot<S>],
+ lane: &'a [Snapshot<S>],
+ reads: &HashMap<(String, i32, u64), ReadRecord>,
+ session: &str,
window_id: Option<u64>,
- row: usize,
-) -> Result<&Snapshot<S>, ToolResult> {
- let found = match window_id {
- Some(window_id) => lane.iter().find(|snapshot| snapshot.window_id == window_id),
- None => match lane {
- [only] => Some(only),
- _ => None,
- },
+) -> Result<&'a Snapshot<S>, RowMiss<'a, S>> {
+ let attribution = |snapshot: &'a Snapshot<S>| {
+ match reads.get(&(session.to_owned(), pid, snapshot.window_id)) {
+ // One read, and it printed the snapshot that is current now: the
+ // row can only be a row of that read.
+ Some(read) if read.reads == 1 && read.snapshot_id == snapshot.id => Ok(snapshot),
+ // Read more than once: rows from the earlier read are gone.
+ Some(read) if read.reads > 1 => Err(RowMiss::Reread(snapshot)),
+ // One read, but a later one replaced its snapshot.
+ Some(_) => Err(RowMiss::Replaced(snapshot)),
+ None => Err(RowMiss::NotRead(snapshot)),
+ }
};
- found.ok_or_else(|| {
- let current = lane
+ match window_id {
+ Some(window_id) => lane
.iter()
- .map(|snapshot| {
- format!(
- "\"{}\" (window {})",
- token_for(snapshot.id, row),
- snapshot.window_id
- )
- })
- .collect::<Vec<_>>();
- let message = if current.is_empty() {
+ .find(|snapshot| snapshot.window_id == window_id)
+ .map_or(Err(RowMiss::NoSnapshot), attribution),
+ None => match lane {
+ [only] => attribution(only),
+ [] => Err(RowMiss::NoSnapshot),
+ _ => Err(RowMiss::Ambiguous),
+ },
+ }
+}
+
+/// The refusal for a bare row number that cannot name exactly one read.
+fn row_refusal<S: SnapshotPayload>(
+ pid: i32,
+ row: usize,
+ lane: &[Snapshot<S>],
+ miss: RowMiss<'_, S>,
+) -> ToolResult {
+ let reason = miss.as_str();
+ let window = miss.snapshot().map(|snapshot| snapshot.window_id);
+ let message = match (&miss, window) {
+ (RowMiss::Reread(snapshot) | RowMiss::Replaced(snapshot), Some(window)) => {
+ let token = token_for(snapshot.id, row);
format!(
- "element_token \"{row}\" is a row number, and pid {pid} has no current \
- snapshot. Call get_window_state, then pass \"<snapshot_id>:{row}\"."
+ "element_token \"{row}\" is a bare row number, and it no longer names the \
+ read it was printed in: window {window} has been read again since, and \
+ rows belong to the read that printed them. Acting on it would mean acting \
+ on whatever element now sits at row [{row}], which may not be the element \
+ you selected. Pass the full token from the read you mean (\"{token}\" is \
+ row [{row}] of the current snapshot), or re-read and use a row the new \
+ tree prints."
)
- } else {
- format!(
- "element_token \"{row}\" is a row number, not a token. Pass the full token, \
+ }
+ (RowMiss::NotRead(snapshot), Some(window)) => format!(
+ "element_token \"{row}\" is a bare row number, and this session has not read \
+ window {window}: a row number names a row of a read you made, and there is none \
+ behind it. Pass the full token from the read you mean (\"{}\" is row [{row}] of \
+ the current snapshot), or call get_window_state and use a row it prints.",
+ token_for(snapshot.id, row)
+ ),
+ (RowMiss::Ambiguous, _) => format!(
+ "element_token \"{row}\" is a row number, not a token. Pass the full token, \
<snapshot_id>:{row}: {}; or add window_id.",
- current.join(", ")
- )
- };
- refusal("invalid_element_token", message)
- })
+ lane.iter()
+ .map(|snapshot| format!(
+ "\"{}\" (window {})",
+ token_for(snapshot.id, row),
+ snapshot.window_id
+ ))
+ .collect::<Vec<_>>()
+ .join(", ")
+ ),
+ _ => format!(
+ "element_token \"{row}\" is a row number, and pid {pid} has no current \
+ snapshot. Call get_window_state, then pass \"<snapshot_id>:{row}\"."
+ ),
+ };
+ let mut error = ToolResult::error(message.clone()).with_structured(serde_json::json!({
+ "status": "refused",
+ "refusal": { "code": "invalid_element_token", "message": message },
+ "code": "invalid_element_token",
+ "reason": reason,
+ "pid": pid,
+ "window_id": window,
+ }));
+ if let (Some(snapshot), Some(structured)) = (miss.snapshot(), error.structured_content.as_mut())
+ {
+ structured["current_snapshot"] = format_snapshot_id(snapshot.id).into();
+ }
+ error
}
fn invalid_token_refusal<S>(token: &str, lane: &[Snapshot<S>]) -> ToolResult {
@@ -257,16 +343,99 @@ fn out_of_range_refusal<S: SnapshotPayload>(snapshot: &Snapshot<S>, row: usize)
)
}
+/// How many retired snapshot ids a runtime remembers, so a refusal for a token
+/// whose snapshot is gone can still name the process (and so the current
+/// snapshots) it belonged to.
+const RETIRED_MEMORY: usize = 256;
+
+/// What one caller's reads of one window looked like.
+#[derive(Clone, Copy, Debug)]
+struct ReadRecord {
+ /// The snapshot the caller's most recent read of the window printed.
+ snapshot_id: u32,
+ /// How many reads of the window printed rows for this caller.
+ reads: u32,
+}
+
+/// Everything one runtime remembers about published snapshots.
+struct SnapshotState<S> {
+ lanes: HashMap<i32, Vec<Snapshot<S>>>,
+ /// Element reads a caller has made of a window: `(session, pid, window)`
+ /// -> how many reads printed rows. A bare row number names a read only
+ /// while its caller has read that window exactly once, because a second
+ /// read can put a different element at the same row. The count outlives
+ /// eviction, so the caller's *second* read is what stops a row from the
+ /// first being re-pointed.
+ reads: HashMap<(String, i32, u64), ReadRecord>,
+ /// Recently retired snapshot ids with the pid that minted them, oldest
+ /// first. This is what lets a token-only call learn whose snapshots
+ /// replaced the one it named.
+ retired: VecDeque<(u32, i32)>,
+}
+
+impl<S> SnapshotState<S> {
+ fn new() -> Self {
+ Self {
+ lanes: HashMap::new(),
+ reads: HashMap::new(),
+ retired: VecDeque::new(),
+ }
+ }
+
+ fn lane(&self, pid: i32) -> &[Snapshot<S>] {
+ self.lanes.get(&pid).map(Vec::as_slice).unwrap_or_default()
+ }
+
+ fn remember_retired(&mut self, pid: i32, ids: impl IntoIterator<Item = u32>) {
+ for id in ids {
+ if self.retired.len() == RETIRED_MEMORY {
+ self.retired.pop_front();
+ }
+ self.retired.push_back((id, pid));
+ }
+ }
+
+ /// The current snapshots of `pid`, in the shape every stale refusal reports.
+ fn current_snapshots(&self, pid: i32) -> Vec<CurrentSnapshot> {
+ self.lane(pid)
+ .iter()
+ .map(|snapshot| CurrentSnapshot {
+ snapshot_id: format_snapshot_id(snapshot.id),
+ window_id: snapshot.window_id,
+ })
+ .collect()
+ }
+
+ /// The pid a snapshot id was minted for, while that snapshot is current.
+ fn pid_of_current(&self, snapshot_id: u32) -> Option<i32> {
+ self.lanes
+ .iter()
+ .find(|(_, lane)| lane.iter().any(|snapshot| snapshot.id == snapshot_id))
+ .map(|(pid, _)| *pid)
+ }
+
+ /// The pid a snapshot id was minted for, including ids retired earlier.
+ fn pid_of(&self, snapshot_id: u32) -> Option<i32> {
+ self.pid_of_current(snapshot_id).or_else(|| {
+ self.retired
+ .iter()
+ .rev()
+ .find(|(id, _)| *id == snapshot_id)
+ .map(|(_, pid)| *pid)
+ })
+ }
+}
+
pub struct SnapshotStore<S: SnapshotPayload> {
runtime_scope: String,
- inner: Mutex<HashMap<i32, Vec<Snapshot<S>>>>,
+ inner: Mutex<SnapshotState<S>>,
}
impl<S: SnapshotPayload> SnapshotStore<S> {
pub fn new() -> Self {
Self {
runtime_scope: current_runtime_scope(),
- inner: Mutex::new(HashMap::new()),
+ inner: Mutex::new(SnapshotState::new()),
}
}
@@ -350,6 +519,7 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
return None;
}
let snapshot = inner
+ .lanes
.get_mut(&pid)?
.iter_mut()
.find(|snapshot| snapshot.window_id == window_id)
@@ -397,41 +567,63 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
if session.is_some_and(crate::session::is_session_ended) {
return None;
}
- let lane = inner.entry(pid).or_default();
- let mut retired = Vec::new();
- if let Some(position) = lane.iter().position(|entry| entry.window_id == window_id) {
- retired.push(lane.remove(position));
- }
- // A new screenshot brings its own frame. A tree-only read keeps the
- // replaced snapshot's frame while the window keeps its size.
- let (scale, frame_size) = match (screenshot_scale, window_size) {
- (Some(scale), size) => (Some(scale), size),
- (None, Some(now)) => retired
- .first()
- .filter(|previous| previous.screenshot_owner.as_deref() == session)
- .and_then(|previous| {
- let then = previous.screenshot_window_size?;
- let same = (then.0 - now.0).abs() < 0.5 && (then.1 - now.1).abs() < 0.5;
- same.then_some((previous.screenshot_scale?, then))
- })
- .map_or((None, None), |(scale, size)| (Some(scale), Some(size))),
- (None, None) => (None, None),
+ // The new snapshot replaces the window's current one, so the lane
+ // borrow has to end before the bookkeeping below.
+ let (id, retired_here) = {
+ let lane = inner.lanes.entry(pid).or_default();
+ let mut retired = Vec::new();
+ if let Some(position) = lane.iter().position(|entry| entry.window_id == window_id) {
+ retired.push(lane.remove(position));
+ }
+ // A new screenshot brings its own frame. A tree-only read keeps
+ // the replaced snapshot's frame while the window keeps its size.
+ let (scale, frame_size) = match (screenshot_scale, window_size) {
+ (Some(scale), size) => (Some(scale), size),
+ (None, Some(now)) => retired
+ .first()
+ .filter(|previous| previous.screenshot_owner.as_deref() == session)
+ .and_then(|previous| {
+ let then = previous.screenshot_window_size?;
+ let same = (then.0 - now.0).abs() < 0.5 && (then.1 - now.1).abs() < 0.5;
+ same.then_some((previous.screenshot_scale?, then))
+ })
+ .map_or((None, None), |(scale, size)| (Some(scale), Some(size))),
+ (None, None) => (None, None),
+ };
+ if lane.len() == LRU_CAP_PER_PID {
+ retired.push(lane.remove(0));
+ }
+ let id = crate::element_token::mint_snapshot_id();
+ lane.push(Snapshot {
+ id,
+ window_id,
+ screenshot_owner: session.map(str::to_owned),
+ screenshot_scale: scale,
+ screenshot_window_size: frame_size,
+ zoom: None,
+ semantic,
+ payload,
+ });
+ (id, retired)
};
- if lane.len() == LRU_CAP_PER_PID {
- retired.push(lane.remove(0));
+ let invalidated: Vec<u32> = retired_here.iter().map(|snapshot| snapshot.id).collect();
+ inner.remember_retired(pid, invalidated.iter().copied());
+ // Only a read that printed rows can leave a bare row number
+ // behind, so only those count. A screenshot-only capture mints no
+ // rows, and a screenshot-only refresh keeps the snapshot (and so
+ // its rows) in place without publishing at all.
+ if semantic {
+ let read = inner
+ .reads
+ .entry((session.unwrap_or_default().to_owned(), pid, window_id))
+ .or_insert(ReadRecord {
+ snapshot_id: id,
+ reads: 0,
+ });
+ read.snapshot_id = id;
+ read.reads = read.reads.saturating_add(1);
}
- let id = crate::element_token::mint_snapshot_id();
- lane.push(Snapshot {
- id,
- window_id,
- screenshot_owner: session.map(str::to_owned),
- screenshot_scale: scale,
- screenshot_window_size: frame_size,
- zoom: None,
- semantic,
- payload,
- });
- (id, retired)
+ (id, retired_here)
};
let invalidated = retired.iter().map(|snapshot| snapshot.id).collect();
drop(retired);
@@ -448,7 +640,7 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
session: Option<&str>,
) -> Result<ScreenshotContext, ToolResult> {
let inner = self.inner.lock().unwrap();
- let lane = inner.get(&pid).map(Vec::as_slice).unwrap_or_default();
+ let lane = inner.lane(pid);
match window_id {
Some(window_id) => {
let snapshot = lane
@@ -524,7 +716,7 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
.map(|context| (pid, context));
}
let inner = self.inner.lock().unwrap();
- let mut matches = inner.iter().filter_map(|(pid, lane)| {
+ let mut matches = inner.lanes.iter().filter_map(|(pid, lane)| {
let snapshot = lane
.iter()
.find(|snapshot| snapshot.window_id == window_id)?;
@@ -548,6 +740,7 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
) -> Result<(), ToolResult> {
let mut inner = self.inner.lock().unwrap();
let snapshot = inner
+ .lanes
.get_mut(&pid)
.and_then(|lane| {
lane.iter_mut()
@@ -567,6 +760,7 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
) -> Result<ZoomContext, ToolResult> {
let inner = self.inner.lock().unwrap();
let mut zooms = inner
+ .lanes
.get(&pid)
.into_iter()
.flatten()
@@ -585,14 +779,19 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
let retired = {
let mut inner = self.inner.lock().unwrap();
let mut retired = Vec::new();
- for lane in inner.values_mut() {
+ let mut retired_ids: Vec<(i32, u32)> = Vec::new();
+ for (pid, lane) in inner.lanes.iter_mut() {
let (owned, kept) = std::mem::take(lane)
.into_iter()
.partition(|snapshot| snapshot.screenshot_owner.as_deref() == Some(session));
*lane = kept;
+ retired_ids.extend(owned.iter().map(|snapshot| (*pid, snapshot.id)));
retired.extend::<Vec<_>>(owned);
}
- inner.retain(|_, lane| !lane.is_empty());
+ inner.lanes.retain(|_, lane| !lane.is_empty());
+ for (pid, id) in retired_ids {
+ inner.remember_retired(pid, [id]);
+ }
retired
};
let count = retired.len();
@@ -604,6 +803,7 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
self.inner
.lock()
.unwrap()
+ .lanes
.get(&pid)?
.iter()
.find(|entry| entry.id == snapshot_id)
@@ -615,6 +815,7 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
self.inner
.lock()
.unwrap()
+ .lanes
.get(&pid)
.is_some_and(|lane| lane.iter().any(|entry| entry.window_id == window_id))
}
@@ -622,10 +823,15 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
/// Whether an accessibility/semantic snapshot has been published for the
/// window. Screenshot-only previews deliberately do not satisfy this.
pub fn contains_semantic_window(&self, pid: i32, window_id: u64) -> bool {
- self.inner.lock().unwrap().get(&pid).is_some_and(|lane| {
- lane.iter()
- .any(|entry| entry.window_id == window_id && entry.semantic)
- })
+ self.inner
+ .lock()
+ .unwrap()
+ .lanes
+ .get(&pid)
+ .is_some_and(|lane| {
+ lane.iter()
+ .any(|entry| entry.window_id == window_id && entry.semantic)
+ })
}
/// The pid an `element_token` was minted for, found without the caller
@@ -636,12 +842,34 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
pub fn pid_for_token(&self, args: &serde_json::Value) -> Option<i32> {
let token = args.get("element_token")?.as_str()?;
let (snapshot_id, _) = parse_token(token)?;
- self.inner
- .lock()
- .unwrap()
- .iter()
- .find(|(_, lane)| lane.iter().any(|snapshot| snapshot.id == snapshot_id))
- .map(|(pid, _)| *pid)
+ self.inner.lock().unwrap().pid_of_current(snapshot_id)
+ }
+
+ /// Who a call's `element_token` belonged to, and that process's current
+ /// snapshots, for the refusal [`crate::element_token::fill_pid_from_token`]
+ /// reports when the token is gone.
+ ///
+ /// The pid is looked up for retired snapshots too, so a token one read
+ /// behind still names the process and the refusal can say what replaced it.
+ /// A token this runtime never minted — or one whose retirement has aged out
+ /// of [`RETIRED_MEMORY`] — is reported as unattributed rather than guessed.
+ pub fn token_owner(&self, args: &serde_json::Value) -> TokenOwner {
+ let Some((snapshot_id, _)) = args
+ .get("element_token")
+ .and_then(serde_json::Value::as_str)
+ .and_then(parse_token)
+ else {
+ return TokenOwner::default();
+ };
+ let inner = self.inner.lock().unwrap();
+ let Some(pid) = inner.pid_of(snapshot_id) else {
+ return TokenOwner::default();
+ };
+ TokenOwner {
+ pid: Some(pid),
+ current: inner.current_snapshots(pid),
+ live: inner.pid_of_current(snapshot_id).is_some(),
+ }
}
pub fn resolve(
@@ -657,19 +885,32 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
};
let window_arg = args["window_id"].as_u64();
let inner = self.inner.lock().unwrap();
- let lane = inner.get(&pid).map(Vec::as_slice).unwrap_or_default();
+ let lane = inner.lane(pid);
let (snapshot, element_index) = match parse_token(token) {
Some((snapshot_id, element_index)) => {
let Some(snapshot) = lane.iter().find(|snapshot| snapshot.id == snapshot_id) else {
- return Err(stale_token_refusal(pid, lane));
+ return Err(stale_token_refusal(pid, &inner.current_snapshots(pid)));
};
(snapshot, element_index)
}
// A bare row number ("11") is the `[11]` of a markdown read. It
- // names a row of the window's current snapshot, the one a fresh
- // read just printed, so resolve it there when the window is known.
+ // carries no snapshot id, so it names a read only while that read
+ // is still the window's only one; a re-read retires the tree the
+ // number came from and the number is refused rather than re-pointed
+ // at whatever row [11] now holds.
None => match token.trim().parse::<usize>() {
- Ok(row) => (row_snapshot(pid, lane, window_arg, row)?, row),
+ Ok(row) => match row_snapshot(
+ pid,
+ lane,
+ &inner.reads,
+ args.get("_session_id")
+ .and_then(serde_json::Value::as_str)
+ .unwrap_or_default(),
+ window_arg,
+ ) {
+ Ok(snapshot) => (snapshot, row),
+ Err(miss) => return Err(row_refusal(pid, row, lane, miss)),
+ },
Err(_) => return Err(invalid_token_refusal(token, lane)),
},
};
@@ -693,16 +934,27 @@ impl<S: SnapshotPayload> SnapshotStore<S> {
pub fn remove(&self, pid: i32, window_id: u64) -> Option<u32> {
let retired = {
let mut inner = self.inner.lock().unwrap();
- inner.get_mut(&pid).and_then(|lane| {
+ let removed = inner.lanes.get_mut(&pid).and_then(|lane| {
let position = lane.iter().position(|entry| entry.window_id == window_id)?;
Some(lane.remove(position))
- })
+ });
+ let id = removed.as_ref().map(|snapshot| snapshot.id);
+ if let Some(id) = id {
+ inner.remember_retired(pid, [id]);
+ }
+ removed
};
retired.map(|snapshot| snapshot.id)
}
pub fn clear(&self) -> usize {
- let retired = std::mem::take(&mut *self.inner.lock().unwrap());
+ let retired = {
+ let mut inner = self.inner.lock().unwrap();
+ let lanes = std::mem::take(&mut inner.lanes);
+ inner.reads.clear();
+ inner.retired.clear();
+ lanes
+ };
let count = retired.len();
drop(retired);
count
@@ -908,6 +1160,105 @@ mod tests {
);
}
+ /// R4. A refusal is supposed to tell the caller what *is* current so it can
+ /// recover without a blind re-read. The token-only path (a call carrying
+ /// `element_token` and no `pid`, which `fill_pid_from_token` resolves before
+ /// dispatch) used to answer only "stale or unknown", naming nothing.
+ ///
+ /// This is the TLA+ finding replayed against the real store: read, read,
+ /// act with the token from the first read and no pid.
+ #[test]
+ fn the_token_only_refusal_names_the_current_snapshots() {
+ let cache = SnapshotStore::new();
+ let first = cache.publish(10, 100, Payload(vec![1, 2, 3]));
+ let current = cache.publish(10, 100, Payload(vec![4, 5, 6])).to_owned();
+ assert_ne!(first, current);
+
+ let mut token_only = serde_json::json!({ "element_token": token_for(first, 0) });
+ let refusal = crate::element_token::fill_pid_from_token(&mut token_only, |args| {
+ cache.token_owner(args)
+ })
+ .expect_err("a token whose snapshot is gone must be refused");
+
+ let structured = refusal.structured_content.clone().unwrap();
+ assert_eq!(structured["refusal"]["code"], "stale_element_token");
+ // The pid the token belonged to, and what is current for it.
+ assert_eq!(structured["pid"], 10);
+ assert_eq!(
+ structured["current_snapshots"],
+ serde_json::json!([{
+ "snapshot_id": format_snapshot_id(current),
+ "window_id": 100,
+ }])
+ );
+
+ let text = crate::snapshot_test_support::text(&refusal);
+ assert!(
+ text.contains(&format_snapshot_id(current)),
+ "the message must name the current snapshot: {text}"
+ );
+ assert!(text.contains("current snapshots for pid 10"), "{text}");
+
+ // Both refusal shapes now report the same field.
+ let with_pid = token_refusal(&cache, 10, &token_for(first, 0));
+ assert_eq!(
+ structured["current_snapshots"], with_pid["current_snapshots"],
+ "the token-only refusal reports what the pid-carrying refusal reports"
+ );
+ }
+
+ /// A token this runtime never minted cannot be attributed, and the refusal
+ /// says that rather than inventing a snapshot.
+ #[test]
+ fn an_unattributable_token_is_refused_without_inventing_a_snapshot() {
+ let cache = SnapshotStore::new();
+ cache.publish(10, 100, Payload(vec![1, 2, 3]));
+
+ let mut unknown = serde_json::json!({ "element_token": token_for(0xdead_beef, 0) });
+ let refusal =
+ crate::element_token::fill_pid_from_token(&mut unknown, |args| cache.token_owner(args))
+ .expect_err("an unknown token is refused");
+ let structured = refusal.structured_content.clone().unwrap();
+ assert_eq!(structured["refusal"]["code"], "stale_element_token");
+ assert!(
+ structured.get("current_snapshots").is_none(),
+ "no attribution, no snapshot claim: {structured}"
+ );
+ let text = crate::snapshot_test_support::text(&refusal);
+ assert!(text.contains("cannot be attributed to a pid"), "{text}");
+ assert!(
+ !text.contains(&format_snapshot_id(1)) && !text.contains("window 100"),
+ "an unattributed refusal must not name another process's snapshot: {text}"
+ );
+ }
+
+ /// Attribution survives retirement, so a token one read behind still says
+ /// whose snapshots replaced it — but a token retired by `clear` is gone.
+ #[test]
+ fn a_retired_snapshot_still_attributes_its_token() {
+ let cache = SnapshotStore::new();
+ let first = cache.publish(7, 42, Payload(vec![1]));
+ cache.remove(7, 42);
+ let owner = cache.token_owner(&serde_json::json!({ "element_token": token_for(first, 0) }));
+ assert_eq!(owner.pid, Some(7));
+ assert!(owner.current.is_empty(), "the lane was removed");
+ assert!(!owner.live, "a removed snapshot is not live");
+
+ let mut args = serde_json::json!({ "element_token": token_for(first, 0) });
+ let refusal =
+ crate::element_token::fill_pid_from_token(&mut args, |args| cache.token_owner(args))
+ .expect_err("the snapshot is gone");
+ let text = crate::snapshot_test_support::text(&refusal);
+ assert!(
+ text.contains("pid 7 has no current snapshot"),
+ "a known pid with nothing current says so: {text}"
+ );
+ assert_eq!(
+ refusal.structured_content.unwrap()["current_snapshots"],
+ serde_json::json!([])
+ );
+ }
+
#[test]
fn stale_token_names_the_current_snapshots() {
let cache = SnapshotStore::new();
@@ -1239,6 +1590,180 @@ mod tests {
assert!(text.contains("use <snapshot_id>:<row>"), "{text}");
}
+ /// R3. A bare row number carries no snapshot id, so it names a read only
+ /// while it is still the only read of that window the caller made. Acting
+ /// with a row remembered from an earlier read must not silently act on
+ /// whatever element now sits at that row.
+ ///
+ /// This is the TLA+ finding replayed against the real store: read (row [1]
+ /// = 20), read again (row [1] = 88), act "1". Before the fix that acted on
+ /// 88 and reported success.
+ #[test]
+ fn a_bare_row_number_does_not_re_point_at_a_newer_snapshot() {
+ let cache = SnapshotStore::new();
+ let first = cache.publish(10, 100, Payload(vec![10, 20, 30]));
+ // The row the model read, and the element it saw there.
+ let seen = match cache
+ .resolve(
+ 10,
+ &serde_json::json!({ "element_token": token_for(first, 1) }),
+ )
+ .unwrap()
+ {
+ ResolvedElement::Element { element, .. } => element,
+ ResolvedElement::None => panic!("row [1] exists"),
+ };
+ assert_eq!(seen, 20);
+
+ let second = cache.publish(10, 100, Payload(vec![99, 88, 77]));
+ assert_ne!(first, second);
+ let bare = serde_json::json!({ "pid": 10, "window_id": 100, "element_token": "1" });
+ let refused = cache
+ .resolve(10, &bare)
+ .expect_err("a bare row from a retired read must be refused, not re-pointed");
+ let text = crate::snapshot_test_support::text(&refused);
+ assert!(
+ text.contains("no longer names the read it was printed in"),
+ "the refusal must say the row is stale: {text}"
+ );
+ assert!(
+ text.contains(&token_for(second, 1)),
+ "the refusal must name the current token for that row: {text}"
+ );
+ assert!(
+ !text.contains("row [1] = ") && !text.contains("clicked"),
+ "the refusal must not describe an action: {text}"
+ );
+ let structured = refused.structured_content.unwrap();
+ assert_eq!(structured["refusal"]["code"], "invalid_element_token");
+ assert_eq!(structured["reason"], "stale_bare_row");
+ assert_eq!(structured["current_snapshot"], format_snapshot_id(second));
+ assert_eq!(structured["window_id"], 100);
+
+ // The full token from the read the caller meant still resolves — the
+ // fix refuses the ambiguous form, it does not break element addressing.
+ assert!(matches!(
+ cache
+ .resolve(
+ 10,
+ &serde_json::json!({ "element_token": token_for(second, 1) })
+ )
+ .unwrap(),
+ ResolvedElement::Element { element: 88, .. }
+ ));
+ }
+
+ /// The same protection for a *different* caller re-reading the window: the
+ /// row is not theirs to re-point either.
+ #[test]
+ fn another_sessions_read_retires_a_bare_row_number() {
+ let cache = SnapshotStore::new();
+ let first = cache
+ .publish_for_session(10, 100, Payload(vec![1, 2]), Some("mine"), None)
+ .unwrap()
+ .0;
+ cache
+ .publish_for_session(10, 100, Payload(vec![7, 8]), Some("theirs"), None)
+ .unwrap();
+
+ let refused = cache
+ .resolve(
+ 10,
+ &serde_json::json!({
+ "window_id": 100,
+ "element_token": "0",
+ "_session_id": "mine",
+ }),
+ )
+ .expect_err("a row printed by a replaced snapshot must be refused");
+ let structured = refused.structured_content.unwrap();
+ assert_eq!(structured["reason"], "stale_bare_row");
+ assert_ne!(structured["current_snapshot"], format_snapshot_id(first));
+
+ // A caller's own second read spends the convenience too: the number
+ // still cannot say which of its two reads printed it.
+ cache
+ .publish_for_session(10, 100, Payload(vec![5, 6]), Some("mine"), None)
+ .unwrap();
+ let refused = cache
+ .resolve(
+ 10,
+ &serde_json::json!({
+ "window_id": 100,
+ "element_token": "1",
+ "_session_id": "mine",
+ }),
+ )
+ .expect_err("two reads, one ambiguous number");
+ assert_eq!(
+ refused.structured_content.unwrap()["reason"],
+ "stale_bare_row"
+ );
+
+ // A window this caller has read once is unambiguous.
+ cache
+ .publish_for_session(10, 101, Payload(vec![3, 4]), Some("mine"), None)
+ .unwrap();
+ assert!(matches!(
+ cache
+ .resolve(
+ 10,
+ &serde_json::json!({
+ "window_id": 101,
+ "element_token": "1",
+ "_session_id": "mine",
+ }),
+ )
+ .unwrap(),
+ ResolvedElement::Element { element: 4, .. }
+ ));
+ }
+
+ /// A bare row number from a caller that has read nothing this session has
+ /// no read behind it, and the refusal says so instead of guessing.
+ #[test]
+ fn a_bare_row_number_without_a_read_of_your_own_is_refused() {
+ let cache = SnapshotStore::new();
+ let current = cache
+ .publish_for_session(10, 100, Payload(vec![1, 2]), Some("theirs"), None)
+ .unwrap()
+ .0;
+ let refused = cache
+ .resolve(
+ 10,
+ &serde_json::json!({
+ "window_id": 100,
+ "element_token": "1",
+ "_session_id": "someone-else",
+ }),
+ )
+ .expect_err("no read of mine, no row of mine");
+ let text = crate::snapshot_test_support::text(&refused);
+ assert!(text.contains("has not read"), "{text}");
+ assert!(text.contains(&token_for(current, 1)), "{text}");
+ assert_eq!(
+ refused.structured_content.unwrap()["reason"],
+ "unattributed_bare_row"
+ );
+ }
+
+ /// The convenience still works where it is unambiguous: one read, still
+ /// current, for the caller that made it.
+ #[test]
+ fn a_bare_row_number_resolves_after_the_callers_only_read() {
+ let cache = SnapshotStore::new();
+ cache.publish(10, 100, Payload(vec![10, 20, 30]));
+ assert!(matches!(
+ cache
+ .resolve(
+ 10,
+ &serde_json::json!({ "window_id": 100, "element_token": "1" }),
+ )
+ .unwrap(),
+ ResolvedElement::Element { element: 20, .. }
+ ));
+ }
+
#[test]
fn out_of_range_row_explains_that_rows_belong_to_one_read() {
let cache = SnapshotStore::new();
@@ -1532,7 +2057,7 @@ mod tests {
);
assert_eq!(cache.retire_session_screenshots("ending"), 1);
assert_eq!(drops.load(Ordering::SeqCst), 1);
- assert!(cache.inner.lock().unwrap().is_empty());
+ assert!(cache.inner.lock().unwrap().lanes.is_empty());
}
#[test]
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rs
index 3d2839c520..2da68ec6f3 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rs
@@ -7,6 +7,7 @@ use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use serde_json::Value;
+use crate::element_token::TokenOwner;
use crate::protocol::ToolResult;
use crate::tool::{ProtectedResourceOwnership, Tool, ToolDef};
@@ -69,9 +70,10 @@ pub type PidFallbackWindowResolver = Arc<dyn Fn(i64) -> Option<u64> + Send + Syn
/// `(pid, snapshot handle)` -> the window that snapshot was taken of.
pub type SnapshotWindowResolver = Arc<dyn Fn(i64, &str) -> Option<u64> + Send + Sync + 'static>;
-/// Call arguments -> the pid their `element_token` was minted for (see
-/// `SnapshotStore::pid_for_token`). `None` when the token is unknown.
-pub type TokenPidResolver = Arc<dyn Fn(&Value) -> Option<i32> + Send + Sync + 'static>;
+/// Call arguments -> who their `element_token` belonged to, and that process's
+/// current snapshots (see `SnapshotStore::token_owner`), so a stale refusal can
+/// name what is current instead of only saying the token is stale.
+pub type TokenPidResolver = Arc<dyn Fn(&Value) -> TokenOwner + Send + Sync + 'static>;
/// Desktop-frame `x`/`y` of an action, when the call carries them.
fn desktop_frame_point(args: &Value) -> Option<(f64, f64)> {
@@ -563,7 +565,12 @@ mod tests {
Arc::new(|_| panic!("a token target must not enumerate windows")),
)
.with_token_pid_resolver(Arc::new(|args| {
- (args["element_token"] == "s00000001:2").then_some(42)
+ let live = args["element_token"] == "s00000001:2";
+ TokenOwner {
+ pid: live.then_some(42),
+ current: Vec::new(),
+ live,
+ }
}));
let result = guard
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs
index 165c593687..d9dbcc070a 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs
@@ -278,7 +278,7 @@ fn pid_window_guarded<T: Tool + 'static>(
/// The pid an `element_token` was minted for, so a token-only action (no
/// `pid`) reaches its tool with the pid the token carries.
fn token_pid_resolver(state: Arc<ToolState>) -> cua_driver_core::window_target::TokenPidResolver {
- Arc::new(move |args| state.snapshots.pid_for_token(args))
+ Arc::new(move |args| state.snapshots.token_owner(args))
}
/// The window a `snapshot_id` was published for (the element cache lane of
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs
index c0753b186f..bc6a36c05b 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs
@@ -940,7 +940,11 @@ pub(super) fn target_pid(
.get("element_token")
.is_some_and(|token| !token.is_null())
{
- return Err(cua_driver_core::element_token::stale_token_without_pid());
+ // The token is gone, but a recently retired snapshot still says whose
+ // it was, so the refusal can name what is current for that process.
+ return Err(cua_driver_core::element_token::stale_token_without_pid(
+ state.snapshots.token_owner(args),
+ ));
}
Err(cua_driver_core::protocol::ToolResult::error(
"Missing required integer field: pid. Pass pid, or pass an element_token from the \
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
index 62cefc5726..946914ee56 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
@@ -540,7 +540,7 @@ fn pid_window_guarded<T: Tool + 'static>(
/// The pid an `element_token` was minted for, so a token-only action (no
/// `pid`) reaches its tool with the pid the token carries.
fn token_pid_resolver(state: Arc<ToolState>) -> cua_driver_core::window_target::TokenPidResolver {
- Arc::new(move |args| state.snapshots.pid_for_token(args))
+ Arc::new(move |args| state.snapshots.token_owner(args))
}
/// Cursor sentinel for a direct platform call without lifecycle metadata.
diff --git a/scripts/ci/cua-driver-live-smoke/smoke.py b/scripts/ci/cua-driver-live-smoke/smoke.py
index f9c5476506..96df725b42 100644
--- a/scripts/ci/cua-driver-live-smoke/smoke.py
+++ b/scripts/ci/cua-driver-live-smoke/smoke.py
@@ -126,9 +126,11 @@ class Call:
class Smoke:
- def __init__(self, mcp, out):
+ def __init__(self, mcp, out, open_session=None):
self.mcp = mcp
self.out = out
+ # Opens another initialized MCP session (its own session id) on the daemon.
+ self.open_session = open_session
self.results = []
self.calls = []
self.pid = None
@@ -409,7 +411,8 @@ def run_checks(smoke):
display_only_check(smoke)
# 7b. Lean-read ergonomics from the v035 bench: since:"latest", a bare row
- # number as element_token, run_steps observe:true, zoom x/y/width/height.
+ # number as element_token (one read only), run_steps observe:true,
+ # zoom x/y/width/height.
lean_read_ergonomics_check(smoke)
# 7c. The pre-0.35 name run_actions still runs, unlisted, with a note.
@@ -559,24 +562,58 @@ def display_only_check(smoke):
)
+def bare_row_problems(smoke):
+ """A bare row number names a read only while it is its caller's only read
+ of the window. This session has read the window many times, so a fresh
+ session reads once and acts on a bare row (must land), then reads again
+ and the same bare row must be refused as stale_bare_row, not re-pointed."""
+ problems = []
+ fresh = Smoke(smoke.open_session(), smoke.out)
+ fresh.pid, fresh.window_id = smoke.pid, smoke.window_id
+ try:
+ state = fresh.read()
+ before = count_value(tree(state))
+ increment = find_row(tree(state), BUTTON, "Increment")
+ args = {"pid": fresh.pid, "window_id": fresh.window_id, "element_token": str(increment)}
+ click = fresh.call("click", args)
+ after = fresh.wait_for_text(f"Count: {(before or 0) + 1}")
+ if click.is_error:
+ problems.append(f"bare row after one read: click {json.dumps(args)} -> {click.first_line()}")
+ elif f"Count: {(before or 0) + 1}" not in tree(after):
+ problems.append(f"bare row click after one read ok but the count did not move from {before}")
+ # wait_for_text read the window again: the number no longer names one read.
+ stale = fresh.call("click", args)
+ reason = stale.structured.get("reason")
+ if not stale.is_error or reason != "stale_bare_row":
+ problems.append(
+ f"bare row after a re-read: click {json.dumps(args)} -> is_error={stale.is_error}, "
+ f"reason {reason!r}: {stale.first_line()}"
+ )
+ finally:
+ smoke.calls.extend(fresh.calls)
+ fresh.mcp.close()
+ return problems
+
+
def lean_read_ergonomics_check(smoke):
check = "since:latest, bare row token, run_steps observe:true, zoom x/y/width/height, scroll dy"
- problems = []
+ problems = bare_row_problems(smoke)
smoke.read()
latest = smoke.read(since="latest")
if latest.structured.get("since_status") not in ("diff", "no_change"):
problems.append(f"since=latest gave since_status={latest.structured.get('since_status')!r}")
+ # This session has read the window many times, so act by the full token.
state = smoke.read()
before = count_value(tree(state))
increment = find_row(tree(state), BUTTON, "Increment")
- row_args = {"pid": smoke.pid, "window_id": smoke.window_id, "element_token": str(increment)}
+ row_args = {"pid": smoke.pid, "window_id": smoke.window_id, "element_token": token(state, increment)}
click = smoke.call("click", row_args)
after = smoke.wait_for_text(f"Count: {(before or 0) + 1}")
if click.is_error:
problems.append(f"click {json.dumps(row_args)} -> {click.first_line()}")
elif f"Count: {(before or 0) + 1}" not in tree(after):
- problems.append(f"bare row click ok but the count did not move from {before}")
+ problems.append(f"full-token click ok but the count did not move from {before}")
increment = find_row(tree(after), BUTTON, "Increment")
batch = smoke.call("run_steps", {
@@ -606,7 +643,8 @@ def lean_read_ergonomics_check(smoke):
"; ".join(problems)
or f"scroll dy:'3' -> {'ok' if not scrolled.is_error else scrolled.first_line()}; "
f"since=latest -> {latest.structured.get('since_status')}; click element_token "
- f"{str(increment)!r} + window_id -> Count moved; observe:true -> "
+ f"{row_args['element_token']!r} + window_id -> Count moved; a bare row lands after one "
+ f"read and is refused as stale_bare_row after a re-read; observe:true -> "
f"{observed.get('since_status')}; zoom x/y/width/height -> "
f"{'ok' if not zoom.is_error else zoom.first_line()}",
)
@@ -812,15 +850,22 @@ def main():
daemon = start_daemon(driver, socket, env, daemon_log)
fixture = None
- mcp = Mcp(driver, socket, env, mcp_log)
- smoke = Smoke(mcp, out)
- platform_name = "Windows (WinForms)" if WINDOWS else "Linux Xvfb (GTK3)"
- try:
+
+ def open_session():
+ mcp = Mcp(driver, socket, env, mcp_log)
init = mcp.request("initialize", {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "live-smoke", "version": "1"}})
if "error" in init:
+ mcp.close()
raise RuntimeError(f"initialize failed: {init['error']}")
mcp.proc.stdin.write(json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}) + "\n")
mcp.proc.stdin.flush()
+ return mcp
+
+ mcp = None
+ smoke = Smoke(None, out, open_session)
+ platform_name = "Windows (WinForms)" if WINDOWS else "Linux Xvfb (GTK3)"
+ try:
+ mcp = smoke.mcp = open_session()
version = smoke.call("get_config", {})
print("driver config:", version.text[:800], flush=True)
@@ -833,7 +878,8 @@ def main():
smoke.record("smoke harness", "fail", f"{type(error).__name__}: {error}")
finally:
write_reports(smoke, out, platform_name)
- mcp.close()
+ if mcp is not None:
+ mcp.close()
for proc in (fixture, daemon):
if proc is not None and proc.poll() is None:
proc.terminate()