oimwiodev/chrome-use
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(tabs): t<N> prefix for tab ids; --label for named tabs; drop --tab peek flag (#1250)

Browse Source 
* fix(tabs): preserve refs across --tab peek and cover outer-tab-closed path

Follow-up to #1249 so `--tab <id>` is actually useful for agents:

- Save and restore the outer tab's `ref_map`, `iframe_sessions`, and
  `active_frame_id` across a scoped command instead of clearing them.
  `snapshot` → `--tab N <cmd>` → `click @e1` now keeps the outer tab's
  refs intact. Scoped commands still see a clean slate so outer refs
  can't resolve against the scoped tab's DOM.
- Close the coverage gap the Vercel review bot flagged on #1249: the
  previous `e2e_tab_scoped_command_handles_outer_tab_closed` test used
  `tab_close`, which is in the scoped-dispatch exclusion list, so it
  never exercised the restore-skip branch it claimed to test. Renamed
  to `e2e_tab_close_with_tab_id_closes_active_tab` with an honest
  docstring, and added `e2e_tab_scoped_command_outer_tab_closed_mid_dispatch`
  that actually hits the branch via `window.opener.close()` on a
  script-opened intermediate tab.
- Add `e2e_tab_scoped_command_isolates_refs_from_outer_tab` pinning
  that outer refs don't bleed into the scoped tab's DOM resolution.
- Rewrite `e2e_tab_scoped_command_clears_state_on_switch` as
  `e2e_tab_scoped_command_preserves_outer_tab_state`, verifying the
  restored @e1 still clicks end-to-end.
- Update the 52 `--help` entries for `--tab <id>` to describe peek /
  restore semantics instead of a vague "Target specific tab ID".
- Update README, docs site, config schema, and the agent-facing
  skills reference with working examples (refs survive the peek) and
  a "when to use \`--tab <id>\` vs \`tab <id>\`" guide so agents pick
  the right flag for their workflow.

* fix(tabs): use t<N> prefix for tab ids, add --label for named tabs

Follow-on to the tab work in #1249 and the prior commit, redesigning the
tab handle surface before release since nothing ships these features yet.

## Why

Incrementing integer tab ids (`1`, `2`, `3`) look indistinguishable from
positional indices in command output, LLM-generated scripts, and docs. In
the common single-agent case where position and id coincide, readers have
no visual cue for which mental model they're using. Positional indices
silently shift when unrelated tabs open/close, so misreading a handle as
an index is a correctness hazard.

## Changes

**Tab ids are now `t1`, `t2`, `t3` (strings).** Bare integer `tabId`
values are rejected with a teaching message rather than silently accepted.
The `t` prefix matches the `@e1` element-ref convention and makes ids
unmistakably non-positional at a glance.

**Labels.** Tabs can be created with a user-assigned label (e.g. `docs`,
`app`) via `tab new --label <name> [url]`. Labels are interchangeable
with `t<N>` ids everywhere a tab ref is accepted. They're never
auto-generated, never rewritten on navigation, and must be unique within
a session.

**Dashboard fix.** `packages/dashboard/src/types.ts` declared
`TabInfo.index: number` but the daemon has been sending `tabId` (not
`index`) since #892, making `tab.index` `undefined` and breaking the
dashboard's close/switch buttons silently. Updated the TS types and
usages to consume `tabId` (string) and optional `label`, restoring the
dashboard's tab interactions.

## Surface

- `cli/src/native/browser.rs`: `TabRef::parse` / `format_tab_id` /
  `is_valid_label` / `PageInfo.label` / `BrowserManager::resolve_tab_ref`
  / `BrowserManager::has_label`. `tab_new` gains an optional label
  argument with duplicate rejection. All JSON responses use the string
  form and include the label.
- `cli/src/native/actions.rs`: scoped-command pre-dispatch and
  `handle_tab_{switch,close,new}` parse string refs and resolve to
  stable ids.
- `cli/src/{flags,commands,main,output}.rs`: `--tab` / config `tab`
  are `String`; `tab` subcommand accepts `t<N>` or a label and supports
  `tab new --label <name> [url]`. All 52 `--help` entries updated.
- `agent-browser.schema.json`: `tab` property type is now `string` with
  a pattern matching `t<N>` or label form.
- `packages/dashboard`: `TabInfo.tabId: string` / `label?: string | null`;
  `closeTabAtom`/`switchTabAtom` take `tabRef: string`; component props
  updated.
- Docs: README, docs site (`commands/` and `configuration/`), and the
  agent-facing skills reference rewritten with the new examples.

## Tests

- Added `TabRef::parse` / `format_tab_id` / `is_valid_label` unit tests
  pinning the bare-integer rejection, the teaching error, label rules,
  and round-tripping.
- Added `test_tab_switch_by_id` / `_by_label` / `test_tab_new_with_label`
  / `_with_label_and_url` / `_with_url_then_label` in `commands.rs`;
  rewrote `test_tab_unknown_subcommand_errors` since labels make
  `tab select` a legitimate ref.
- Added `e2e_tab_new_with_label_can_be_switched_and_peeked`,
  `e2e_tab_new_with_duplicate_label_errors`,
  `e2e_tab_scoped_command_rejects_bare_integer`.
- Migrated every existing tab e2e test (and one unit test) from
  integer `tabId` to the string form.

`cargo fmt`, `cargo clippy -- -D warnings`, all 30 non-ignored tab unit
tests, all 13 tab e2e tests, and `tsc --noEmit` on the dashboard all
pass.

* refactor(tabs): drop --tab scoped peek flag; keep t<N> ids and labels

After fleshing out `--tab <id|label>` in the previous commits (scoped
pre/post-dispatch save/restore, ref preservation, outer-tab-closed edge
case, full e2e coverage), the machinery-to-value ratio makes the feature
hard to justify. Nixing it now while nothing has shipped.

## Why

- Every new daemon feature touching per-tab state has to reason about
  scoped-dispatch interleaving. `ScopedRestore`, pre/post-dispatch hooks,
  and the exclusion list add ongoing maintenance tax.
- Three separate PRs (#892, #1249, and this one pre-nix) were needed to
  reach "works correctly." That's a smell.
- `tab <id|label>` switch + labels already cover the legible multi-tab
  workflow case.
- `--tab` vs `tab <id>` have opposite lifecycle semantics but look
  identical, teaching every agent two things where one would do.
- "Non-disruptive peek" isn't actually race-free: the daemon does swap
  active tab during execution, so a concurrent client between pre- and
  post-dispatch sees the scoped tab as active.
- Ref-based interaction with scoped tabs never worked ergonomically —
  refs are per-tab, so `--tab N click @e1` requires `@e1` to already be
  on tab N, which means a prior switch, which negates the peek.
- Adding a feature back is easy; removing shipped API is hard.

If per-tab caching (`HashMap<tab_id, RefMap>`) lands later, `--tab` can
be reintroduced essentially for free. That's the right time.

## Removed

- `--tab <id|label>` global flag (`cli/src/flags.rs`, `cli/src/main.rs`,
  all 52 `--help` entries in `cli/src/output.rs`).
- `tab` property in `agent-browser.schema.json` and the config-options
  row in `docs/src/app/configuration/page.mdx`.
- `ScopedRestore` struct, pre/post-dispatch save/restore in
  `execute_command` (`cli/src/native/actions.rs`).
- `impl Default for RefMap` in `cli/src/native/element.rs` (only added
  for `mem::take` in the scoped machinery).
- `e2e_tab_global_targeting`, `_snapshot`, `_snapshot_non_contiguous`,
  `e2e_tab_scoped_command_preserves_outer_tab_state`,
  `_isolates_refs_from_outer_tab`, `_restores_active_tab`,
  `_outer_tab_closed_mid_dispatch`. 590 lines.
- The "When to use `--tab` vs `tab <id|label>`" sections in README,
  docs site, and skills reference.

## Kept

- Stable tab ids (`t1`, `t2`, `t3`) with bare-integer rejection.
- User-assigned labels (`tab new --label docs [url]`), with duplicate
  rejection and interchangeable use everywhere a tab ref is accepted.
- `BrowserManager::{active_tab_id, has_tab_id, resolve_tab_ref, has_label}`
  accessors (still used by the remaining tab handlers).
- `TabRef::parse`, `format_tab_id`, `is_valid_label` and their unit
  tests.
- Dashboard TS fix (`TabInfo.tabId` + `label`).
- `e2e_tab_close_with_tab_id_closes_active_tab` (renamed docstring to
  drop the gone exclusion-list reference).
- `e2e_tab_new_with_label_can_be_switched_and_closed` (rewrite of the
  previous `_and_peeked` test — now exercises only switch and close).
- `e2e_tab_switch_rejects_bare_integer` (rewrite targeting the
  `tab_switch` daemon handler rather than the removed scoped path).

net: -900 lines across 12 files. `cargo fmt`, `cargo clippy -D warnings`,
all 25 non-ignored tab unit tests, all 6 tab e2e tests, and
`tsc --noEmit` on the dashboard all pass.
This commit is contained in:
Chris Tate
2026-04-16 14:33:43 -05:00
committed by GitHub
parent c201623710
commit 585d93a02b
15 changed files with 709 additions and 673 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cli/src/output.rs
+45 -75
View File
@@ -407,10 +407,8 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
// Tabs
if let Some(tabs) = data.get("tabs").and_then(|v| v.as_array()) {
for tab in tabs {
let tab_id = tab
.get("tabId")
.and_then(|v| v.as_i64())
.unwrap_or_default();
let tab_id = tab.get("tabId").and_then(|v| v.as_str()).unwrap_or("?");
let tab_label = tab.get("label").and_then(|v| v.as_str());
let title = tab
.get("title")
.and_then(|v| v.as_str())
@@ -422,13 +420,17 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
} else {
" ".to_string()
};
println!("{} [{}] {} - {}", marker, tab_id, title, url);
if let Some(label) = tab_label {
println!("{} [{}] {} {} - {}", marker, tab_id, label, title, url);
} else {
println!("{} [{}] {} - {}", marker, tab_id, title, url);
}
}
return;
}
// Tab switch
if action == Some("tab_switch") {
if let Some(tab_id) = data.get("tabId").and_then(|v| v.as_i64()) {
if let Some(tab_id) = data.get("tabId").and_then(|v| v.as_str()) {
if let Some(url) = data.get("url").and_then(|v| v.as_str()) {
println!(
"{} Switched to tab [{}] ({})",
@@ -447,19 +449,31 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
}
}
// New tab/window
if let Some(tab_id) = data.get("tabId").and_then(|v| v.as_i64()) {
if let Some(tab_id) = data.get("tabId").and_then(|v| v.as_str()) {
if let Some(total) = data.get("total").and_then(|v| v.as_i64()) {
let label = match action {
let label_noun = match action {
Some("window_new") => "Window opened",
_ => "Tab opened",
};
println!(
"{} {} [{}] ({} total)",
color::success_indicator(),
label,
tab_id,
total
);
let tab_label = data.get("label").and_then(|v| v.as_str());
if let Some(lbl) = tab_label {
println!(
"{} {} [{}] {} ({} total)",
color::success_indicator(),
label_noun,
tab_id,
lbl,
total
);
} else {
println!(
"{} {} [{}] ({} total)",
color::success_indicator(),
label_noun,
tab_id,
total
);
}
return;
}
}
@@ -604,7 +618,7 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
if data.get("closed").is_some() {
let label = match action {
Some("tab_close") => {
if let Some(closed_id) = data.get("tabId").and_then(|v| v.as_i64()) {
if let Some(closed_id) = data.get("tabId").and_then(|v| v.as_str()) {
println!("{} Tab [{}] closed", color::success_indicator(), closed_id);
return;
}
@@ -1057,7 +1071,6 @@ Aliases: goto, navigate
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
--headers <json> Set HTTP headers (scoped to this origin)
--headed Show browser window
@@ -1081,7 +1094,6 @@ the browser's back button.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser back
@@ -1099,7 +1111,6 @@ the browser's forward button.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser forward
@@ -1117,7 +1128,6 @@ the browser's reload button.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser reload
@@ -1141,7 +1151,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser click "#submit-button"
@@ -1163,7 +1172,6 @@ or triggering double-click handlers.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser dblclick "#editable-text"
@@ -1182,7 +1190,6 @@ This replaces any existing content in the field.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser fill "#email" "user@example.com"
@@ -1202,7 +1209,6 @@ Unlike fill, this does not clear existing content first.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser type "#search" "hello"
@@ -1226,7 +1232,6 @@ triggering hover states or dropdown menus.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser hover "#dropdown-trigger"
@@ -1244,7 +1249,6 @@ Sets keyboard focus to the specified element.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser focus "#input-field"
@@ -1262,7 +1266,6 @@ Checks a checkbox element. If already checked, no action is taken.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser check "#terms-checkbox"
@@ -1280,7 +1283,6 @@ Unchecks a checkbox element. If already unchecked, no action is taken.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser uncheck "#newsletter-opt-in"
@@ -1298,7 +1300,6 @@ Selects one or more options in a <select> dropdown by value.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser select "#country" "US"
@@ -1317,7 +1318,6 @@ Drags an element from source to target location.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser drag "#draggable" "#drop-zone"
@@ -1335,7 +1335,6 @@ Uploads one or more files to a file input element.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser upload "#file-input" ./document.pdf
@@ -1357,7 +1356,6 @@ Arguments:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser download "#download-btn" ./file.pdf
@@ -1389,7 +1387,6 @@ Modifiers (combine with +):
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser press Enter
@@ -1411,7 +1408,6 @@ Useful for holding modifier keys.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser keydown Shift
@@ -1429,7 +1425,6 @@ Releases a key that was pressed with keydown.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser keyup Shift
@@ -1458,7 +1453,6 @@ directly — it already operates on the current focus.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser keyboard type "Hello, World!"
@@ -1493,7 +1487,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser scroll
@@ -1516,7 +1509,6 @@ Aliases: scrollinto
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser scrollintoview "#footer"
@@ -1554,7 +1546,6 @@ Wait for text to disappear:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser wait "#loading-spinner"
@@ -1596,7 +1587,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser screenshot
@@ -1620,7 +1610,6 @@ Saves the current page as a PDF file.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser pdf ./page.pdf
@@ -1649,7 +1638,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser snapshot
@@ -1676,7 +1664,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser eval "document.title"
@@ -1709,7 +1696,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser close
@@ -1761,7 +1747,6 @@ Subcommands:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser get text @e1
@@ -1794,7 +1779,6 @@ Subcommands:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser is visible "#modal"
@@ -1834,7 +1818,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser find role button click --name Submit
@@ -1865,7 +1848,6 @@ Subcommands:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser mouse move 100 200
@@ -1899,7 +1881,6 @@ Settings:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser set viewport 1920 1080
@@ -1940,7 +1921,6 @@ Subcommands:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser network route "**/api/*" --abort
@@ -1978,7 +1958,6 @@ Operations:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser storage local
@@ -2018,7 +1997,6 @@ for the current page URL.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
# Simple cookie for current page
@@ -2051,27 +2029,34 @@ agent-browser tab - Manage browser tabs
Usage: agent-browser tab [operation] [args]
Manage browser tabs in the current window.
Manage browser tabs in the current window. Stable tab ids look like `t1`,
`t2`, `t3`. An id is never reused within a session, so scripts can keep
referring to the same tab across commands. Optional user-assigned labels
(e.g. `docs`, `app`) are interchangeable with ids everywhere a tab ref is
accepted.
Operations:
list List all tabs with tab IDs (default)
new [url] Open new tab
close [id] Close tab by ID (current if no ID)
<id> Switch to tab by ID
list List open tabs with their ids and labels (default)
new [url] Open a new tab
new --label <name> [url] Open a new tab with a label like `docs` or `app`
close [t<N>|label] Close a tab (current if no ref given)
<t<N>|label> Switch to a tab by id or label
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser tab
agent-browser tab list
agent-browser tab new
agent-browser tab new https://example.com
agent-browser tab 2
agent-browser tab new --label docs https://docs.example.com
agent-browser tab t2
agent-browser tab docs
agent-browser tab close
agent-browser tab close 1
agent-browser tab close t1
agent-browser tab close docs
"##
}
@@ -2090,7 +2075,6 @@ Operations:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser window new
@@ -2113,7 +2097,6 @@ Arguments:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser frame "#embed-iframe"
@@ -2201,7 +2184,6 @@ Operations:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser dialog accept
@@ -2227,7 +2209,6 @@ Operations:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser trace start
@@ -2259,7 +2240,6 @@ Start Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
# Basic profiling
@@ -2299,7 +2279,6 @@ Operations:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
# Record from current page (preserves login state)
@@ -2332,7 +2311,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser console
@@ -2353,7 +2331,6 @@ Options:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser errors
@@ -2373,7 +2350,6 @@ Visually highlights an element on the page for debugging.
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser highlight "#target-element"
@@ -2399,7 +2375,6 @@ Operations:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser clipboard read
@@ -2439,7 +2414,6 @@ State Encryption:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser state save ./auth-state.json
@@ -2472,7 +2446,6 @@ Environment:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser session
@@ -2570,7 +2543,6 @@ Supported URL formats:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
# Connect to local Chrome with remote debugging
@@ -2732,7 +2704,6 @@ URL Diff:
Global Options:
--json Output as JSON
--session <name> Use specific session
--tab <id> Target specific tab ID
Examples:
agent-browser diff snapshot
@@ -3027,7 +2998,6 @@ Authentication:
Options:
--session <name> Isolated session (or AGENT_BROWSER_SESSION env)
--tab <id> Target specific tab ID for the command
--executable-path <path> Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH)
--extension <path> Load browser extensions (repeatable)
--args <args> Browser launch args, comma or newline separated (or AGENT_BROWSER_ARGS)