* feat(desktop): add the @e2e-dev/desktop engine on agent-desktop
A desktop engine for native and Electron apps, built on agent-desktop
(vercel-labs, Apache-2.0), which reads and drives apps through the OS
accessibility tree. macOS is the tested platform; this is rollout phase 1
of the ENG-1352 proposal.
- The engine downloads the pinned agent-desktop 1.3.1 release in prepare
and checks its SHA-256; the npm package is not a dependency because its
postinstall would fail check:install-scripts.
- Fill text reaches agent-desktop on stdin, never in its arguments.
Screenshots are cropped to the window and paint every secure field black,
and are withheld when a secure field has no bounds or the snapshot was
partial.
- Node ids stay stable across observations, so the agent gets diffs.
- The engine quits only the process it launched, checked by its process
instance.
- apps/desktop-testbed holds an AppKit sign-in form with deterministic and
agentic suites.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): accept the remaining budget in the fill arguments
The timeout agent-desktop gets is what is left of the operation's
deadline, so it can be a millisecond under the full budget on a slow
runner.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): report field values whole and keep a typed-into field's id
locate answers single-node reads, which the contract says carry the whole
value; the harness cuts what the agent sees. An unnamed field's identity no
longer includes its value, so typing into it is a change, not a remove and
an add. An image is projected as the contract role image, which both
locator spellings resolve to.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): withhold a capture with a border instead of masking it in place
A capture within four pixels of the window was taken as the window, so a
two-pixel border shifted every mask. Only a pixel of rounding is accepted
now, any other capture is cropped to its opaque box, and each mask reaches
two pixels past its field.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): give a read exactly its budget
The 500 ms floor exists so a click that landed is not reported as cut off;
a read has no such reason and now stops at the operation's deadline.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): keep agent-desktop out of the replay cache and report install failures
E2E_CACHE_DIR names the replay cache, which a project may commit, so the
binary goes to the OS cache directory only, found from the run's
environment. A network or tar failure in prepare is now
AGENT_DESKTOP_INSTALL_FAILED, as the docs say.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): offer doubleTap only with headed, and say what app.open and settle do
agent-desktop double-clicks with the real pointer only, so doubleTap is
declared with headed: true and sent with --headed. The docs said app.open()
quits the app if it runs; it quits only the copy the engine launched. settle
is a fixed wait, not a check that the UI is still.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): drive only the launched process, and keep ids and the select ladder honest
- Every read and scoped command goes to a window of the process the engine
launched; before app.open() or after the app quit, the engine reads and
drives nothing, so a developer's own copy is never touched.
- With appPath, the launched executable must come from that bundle; another
copy registered under the same bundle id fails the open.
- quit keeps the process as the engine's own until it is known to be gone,
so a failed lookup is reported and dispose tries again.
- Node identities are scoped to their window and retired once gone or
ambiguous, so neither a twin nor another window's control inherits an id.
- The select ladder passes the label after --, reports a stale ref as
NODE_STALE, and stops once any command of a way reached the app.
- A press on a control that refuses focus is refused unless it holds focus.
- A root swipe after a restart reads the window again.
- app.open() waits at most 30 s for a readable window, reports any other
read failure as it is, and is cancelled with its operation.
- A screenshot is withheld when the window read after the capture differs
in its secure fields.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): read placeholders, mixed checkboxes, and depth-cut trees as agent-desktop reports them
- A placeholder comes from agent-desktop's own placeholder field; the hint
is kept as an attribute of its own.
- A mixed checkbox reports no checked state, so check() and uncheck() always
reach the control instead of returning early.
- A node that counts children it did not list (the depth limit) marks the
tree as cut short, so a screenshot from it is withheld.
- Siblings that share a developer id (AppKit menu items) tell themselves
apart by name and keep their ids; a status with a developer id keeps its
id while its text changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): launch an appPath by path and keep every process a launch started
- An appPath bundle is opened by its path (open -n), and the new process
running from it is taken as the engine's own; launching by bundle id let
LaunchServices pick another copy with the same id.
- A launch that failed after the app started still leaves the engine owning
the new process, so the end of the attempt quits it.
- A window is the engine's only when its process instance matches too, so a
later process given the same pid is never read or driven.
- An app list that is incomplete keeps the process the engine's, to quit
again in dispose.
- A point action finds the window where it is now, so it works right after
app.open() and after the window moved.
- A type or fill after a clear that changed the field fails as
ACTION_MAY_HAVE_COMMITTED, never as a retryable stale ref.
- A screen larger than the binding cap keeps every node it just read.
- The launch wait is 10 s, and each read in it gets what is left of it.
- A bundle id that names no app says so, instead of asking for app.open().
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): refuse an archive with the wrong SHA-256 and cache nothing
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(desktop): say app.open brings the app forward, and that only macOS is tested
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): never take another copy as the launched one, and aim point actions at their window
- A launch agent-desktop refused takes no process as its own, and a copy is
attributed to a launch by id only against a whole app list from before it,
so cleanup never kills the developer's copy.
- A launch whose outcome is unknown is kept pending and settled by the next
quit under its own budget, so a timed-out launch still has its app quit.
- A point action goes to the window it was observed in, wherever it is now,
refuses a point outside that window, and brings it forward before the
physical click.
- In the select ladder, ELEMENT_NOT_FOUND from select (no such option) goes
on to the next way; from a command on the list itself it is NODE_STALE.
- A root swipe scrolls the window as it is now.
- With both appPath and bundleId, the appPath build is launched and its
bundle id must match.
- An open that runs out of its own budget is OPERATION_TIMEOUT; only the full
launch wait reports an unreadable window.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop-testbed): check the saved screenshot for the password field's mask
The test checked only that the file was a PNG, which an unmasked capture
also is. It now decodes the image and requires the solid black bar the
password field's mask paints.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(desktop): say which app launches when appPath and bundleId are both set
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): report a read agent-desktop timed out as OPERATION_TIMEOUT
TIMEOUT was NOT_ACTIONABLE for reads as well as inputs, so a snapshot that
ran out of time skipped the launch wait's timeout handling.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): tell the launched process apart by a token, and measure points in their window
- Every launch passes a one-time token in the app's environment
(launch --env, open --env), and a process is the engine's own only when
ps -E shows that token. Guessing from the app list before and after a
launch could take, and kill, a copy the developer or another worker
started at the same time.
- A launch whose outcome is unknown is settled by the next quit, which looks
for the token for up to 3 s and reports a failure when it finds none.
- A point is measured in the window of the newest screen observe or locate
handed out, and sent unrounded, so it never lands past the window's edge.
- check and uncheck always go to agent-desktop, which reads the live state.
- One window's node ids stay while another window is read.
- The launch wait's commands share its deadline.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): pin option and app validation and the headed-only actions
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop-testbed): measure the password mask at the capture's scale
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): keep identities from colliding, and never drop a secure node
- A node identity is a tagged tuple, so a developer id and a name can never
spell another control's identity (`shared` + `Edit:` against `shared:Edit`),
which let one control take another's binding.
- A secure node is never dropped as a wrapper, so its bounds are masked.
- A binding records the window its node was read in.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): press keys only into a focused control, type keystrokes, and check the launched process's token
- A press on a control needs its focus to succeed and to hold, and goes into
the control's own window; before, a refused focus sent the key to
whatever window had focus.
- The keyboard capability is declared with headed only and types with
--headed: without physical input agent-desktop sets the text, and the
contract asks for keystrokes the app's handlers see.
- The process agent-desktop reports for a launch must carry the launch's
token; a launcher that handed over to a copy already running (a Linux
desktop file) fails the open and never drives or quits that copy.
- A select that finds no such option never falls through to set-value,
which would type the label in as free text; a menu left open after a
missing option is reported as a changed app.
- A read tries the launched app's windows in turn, past a panel
accessibility cannot read.
- No app bundle is opened once the operation's budget is spent.
- doctor fails an appPath with no Contents/Info.plist.
- The unused latest-screen field is gone.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop-testbed): require a mask the size of the password field, not one black row
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(desktop): ship a NOTICE like every other published package
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(desktop): say typing into whatever has focus needs headed
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): withhold masks with no area, and give controls their title as text
- A secure field whose box has no area masks nothing, so the screenshot is
withheld.
- A control reports its title as its text, as on a device, so
textContent() reads a button's title; an input's name is a label, so it
gets none.
- A binding keeps its node's box, to find a look-alike again.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): find a pressed look-alike by its place, keep unresolved launches, and test on the host's ps
- A press checks focus on the control found again by role and box, since a
look-alike has a new id in every read; the key is resolved before focus
moves, and a node read in no window is refused.
- An environment that cannot be read (a macOS system app under SIP, a
failed lookup) is no evidence: agent-desktop's report of the process it
launched stands, so system apps open again and are quit at the end.
- A pending launch stays until it is claimed or a whole wait finds none.
- A window row is the engine's only with the launched process instance.
- A screenshot finds secure fields in whole reads of the window, even with
interactive snapshots, which leave out a secure node with no action.
- A menu read in part never reports an option missing.
- The unit tests read process environments the host's way (ps -E or
/proc), so they pass on the Linux CI runner, and remove the fake's
scenario directories.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): dispose every surface a test creates, so no state directory is left behind
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(desktop): drop Electron, so the engine targets native apps only
Electron apps are out of scope for this engine. Remove the paths that
existed only for them: the headed type fallback for a field the
accessibility API cannot set (Electron on Linux), and the expand and
menu-click steps of the select ladder (Electron on Windows and macOS).
A select now tries `select`, then sets the value of a list that takes
none (WinForms), and reports an option `select` cannot find as missing.
The Electron snapshot fixtures go too; the wrapper and shared-id tests
use the AppKit sign-in form and an inline AppKit menu. Docs, the
README, package metadata, and the skill now say native apps.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(desktop): match the workspace's vitest 5.1.1
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* fix(desktop): apply the review of #1953
macOS only. prepare and init refuse any other OS: on Windows and Linux
some actions need physical input and GTK's password field is not
reported as secure, so masking would fail open. A config with a desktop
target still loads elsewhere.
The app under test and agent-desktop get only HOME, USER, LOGNAME,
SHELL, PATH, TMPDIR, LANG, LC_*, and __CF_USER_TEXT_ENCODING of the
run's environment, so secrets, model keys, and CI tokens never reach
them. `open` and NSWorkspace both handed the caller's whole environment
to the app.
The app launches in the background (`open -g`, `launch` without
`--activate`) unless headed, so typing at the Mac no longer lands in it.
An app that shows no window after 2 s is brought forward once.
Every launch passes -ApplePersistenceIgnoreState YES.
An appPath app whose environment cannot be read (a system app, a build
signed with `restrict`) is now claimed as the single new copy that was
not running before the launch, instead of polling until the test timed
out and leaving the app running. A launch reported for a copy that ran
before it is refused. An open that finds no process fails within 10 s.
select no longer falls back to set-value, which could type a missing
option into an editable combo box. press sends a key only when the
control's window is the app's key window, and finds the control again by
its stable id. locate fails on a truncated read with no match instead of
proving absence. The reads a screenshot's mask takes hand out no ids.
The window's own Close, Minimize, Zoom, and Full Screen buttons are left
out of the tree. desktop.useWindow() picks the window screen reads.
Stale state directories of killed workers are swept at init. The cached
agent-desktop is reused only when a verified unpack stamped it and its
executable and helper are intact. doctor says the permission checks need
the first run. A pending launch whose lookup timed out stays pending.
Tests: the screenshot-moved test now uses the window the fake lists, and
a steady capture is checked to succeed. Each fix has a test that fails
without it (checked by mutation). The testbed checks the password
field's own box is black and the field beside it is not, and
test:desktop-testbed builds the app.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): keep launches pending after open, and fix four review gaps
A fresh-context review of f0d1bb69f found these, each now with a test:
- openBundle: a failure after `open` ran (a list-apps error, or the
budget running out while looking) was read as "nothing was sent", so
the copy `open` started was never quit. Any failure after `open` is
now ACTION_MAY_HAVE_COMMITTED and leaves the launch pending.
- An app that quits right after launch now fails the open at once,
before the engine brings its bundle forward, which would have started
a copy the engine does not own.
- A node inside a look-alike container is no longer marked stable: its
id is built on its parent's, which is new in every snapshot, so press
finds it by place again.
- Only a title-bar-sized button (at most 20 points) with a window
control's name is left out; an app's own Close button stays.
- A window chosen with desktop.useWindow() that closed is now
INVALID_STATE, not an empty screen a negative assertion would pass on.
- The release cache is swapped by rename instead of deleted first, and
doctor checks the stamped copy, not only that the file exists.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): send keys and close select menus in the background, and quit apps killed workers left
Found in live runs on an unlocked Mac:
- A key press never reached an app in the background: agent-desktop
sends a key to a named window only while that window is active, and
answered STALE_REF, which the harness retried until the step timed out.
The key now goes to the process by its app name, once the engine saw
its copy is the only one with that name; with another copy running,
press fails at once with NOT_ACTIONABLE and says to use headed.
- selectOption of a missing option on a pop-up button opened its menu,
waited out the whole action budget, and left the menu open. select now
waits at most 3 s; a menu it left open is closed with Escape and the
option reported missing (NOT_ACTIONABLE), the list unchanged.
- A worker that was killed left its app running. Each worker records
the app it launched and its token; the next run's sweep quits that app
while its environment still shows the token.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): sweep a state directory whose launch record was cut short
A worker killed while writing app.json left half a JSON record. The sweep
parsed it inside the promise's success handler, so the SyntaxError escaped
and every later init failed on the same stale directory. A record that does
not parse now names no process and the directory still goes, and the record
is written to a side file and renamed into place.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): keep the state directory when dispose could not quit the app
dispose removed the state directory even when its quit failed, and app.json
went with it, so the next run's sweep had no pid and token to quit the
leaked app by. The directory now stays while the engine still owns a process
it could not quit; the owner file names a worker that is gone by then, so the
sweep removes the directory after it quits the app.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): claim a copy with no readable token only from whole app lists
Two paths took a process as the launch's own on evidence an incomplete app
list cannot give, and the engine later kills what it owns:
- launch by bundle id accepted agent-desktop's reported pid when its
environment could not be read and the list before the launch was partial,
so a copy already running could not be ruled out;
- claim() took the single new unreadable copy from a list after the launch
that left copies out, where a second new one could hide.
The first now refuses the launch and leaves the process alone. The second
reports that it cannot tell; quit keeps the launch pending as it does for a
lookup that ran out of time.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): give a background key only what is left of its budget
sendKey built its command options once, so the key sent by the app's name,
after a refused window press and a list of the apps, still carried the budget
the operation had at its start and could run past the deadline. The options
are now built for each command from the time left.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): keep a select whose menu was left open as possibly committed
After a select that may have reached the app, closing a menu the app had
open was taken as proof that the option was missing and nothing was chosen,
and reported as NOT_ACTIONABLE. An open menu shows neither: it does not say
which control opened it. The failure now stays ACTION_MAY_HAVE_COMMITTED,
naming the option the list may lack, after the menu is closed. A failure to
close the menu (Escape refused while another copy runs) no longer replaces
the select's own error.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): measure a point from the window useWindow() chose
performAt measured a point from the window the last read used. After
desktop.useWindow() picked another window, the next tapAt still brought the
old window forward and clicked there. Choosing a window, or going back to the
focused one, now drops that window, so the next point action measures from
the window in use.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): read no empty screen from an app that cannot be read
capture() skipped every window it could not snapshot and returned no screen,
so observe showed an empty window and locate found nothing. While the screen
is locked, or after the app crashed, not.toBeVisible() then passed. Opus
reproduced it against the testbed app on a locked Mac.
Now:
- listed windows none of which could be read are a retryable NODE_STALE,
so a locator reads again until its deadline;
- a chosen window whose snapshot says it is gone is INVALID_STATE, like
one missing from the list;
- an app whose process is gone is INVALID_STATE.
An app with no window at all still reads as an empty screen. The launch's
readiness wait treats the new errors as a window not readable yet.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): count no matches in a window read in part
locate() refused a partial read only when nothing matched, and then with a
non-retryable ENGINE_FAILURE. One visible match in a read cut short still
counted as exactly one, though a second could sit in the part left out, so
a strict action or toHaveCount(1) could pass on it. And a locator for a
control not there yet failed at once instead of polling.
A partial read is now a retryable NODE_STALE whatever it matched, so the
locator reads again until its deadline. The docs say so for a window deeper
than the 24 levels a snapshot reads.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(desktop): correct getByText on buttons, and macOS-only metadata
- The desktop page said getByText cannot find a button by its title. The
projection gives a button its title as text too, so it can; getByRole is
what limits a match to the button.
- The package keywords listed windows and linux, which the engine refuses.
- CONTRIBUTING said a contract change bumps both engines; there are three.
- @e2e-dev/desktop moves to its alphabetical place in the docs package.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): cover the appPath launch and a successful install
Every surface test launched by bundle id, so a change to the open -g -n
arguments, the claim of the copy carrying the token, or its quit would not
fail a test; and the binary tests covered only failed installs.
- An appPath test puts a fake open first on PATH: it records its arguments
and starts a process with the variable --env names, which the engine
claims, reads, and quits.
- An install test serves an archive of its own through a digests table
installPinned now takes (the pinned one by default), installs it twice
at once, and checks the stamp, that nothing is left beside the entry, and
that a third install fetches nothing.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): find the app's running copies the way agent-desktop launches it
runningCopies() and claim() listed every app and kept the ones whose
bundle id or name equalled the target exactly. agent-desktop reports the
localized name (Calculator is 계산기 on a Korean Mac) and matches a launch
target in any case, so a copy the launch could hand over to was left out of
the list before it. A copy whose environment cannot be read was then taken
as the launch's own and killed at the end of the test; and a copy a launch
of unknown outcome started was never found, and left running.
Both now ask list-apps --app <target>, which matches the way the launch and
quit() do, and count every process it returns.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): stop the fake apps before removing the list of them
afterEach ran cleanupFakes() first, which deletes the file fake.spawned()
reads, so the processes a test left running were never killed and stayed
for their 60 s timer. They are now killed first; no stand-in process is left
after the suite.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): report an open LaunchServices refused as starting nothing
openBundle wrapped every failure of open as ACTION_MAY_HAVE_COMMITTED, so a
bundle LaunchServices refused (a missing executable, a bad signature) left the
launch pending. The end of the attempt then looked for its process for 3 s
and failed a second time, telling the user to quit an app that never
started. The error also quoted the whole open command line.
An open that exits with an error, or cannot run, is now ENGINE_FAILURE with
open's own message, and nothing is left to look for. Only an open the budget
or a cancellation stopped stays possibly committed. The appPath tests share
a helper that puts a stand-in open on PATH.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): record the launch token before the launch, and sweep by it
app.json was written only once the launch's process id was known. A worker
killed during the launch (which can wait up to 10 s for its process), or a
launch whose process was never found, left no record, and dispose then
deleted the state directory too. The next run could not find the app.
The record now holds the launch token and is written before anything is
sent. dispose keeps it while a launch is pending, as it does for an app that
would not quit. The sweep quits every process whose environment carries the
token, found by listing the processes, so it needs no process id and
cannot reach a process that took one over.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): act on no node read outside the window useWindow() chose
useWindow() changed the window every read used but kept the nodes read
before, so an action on a ref from the old window still reached its control
after a test chose another. Such a ref is now NODE_STALE, which the harness
answers by locating the node again in the window in use.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): read no empty screen from an app whose process id was reused
With no window of the launched process listed, capture() checked only that
its process id was alive. Once the app quits, macOS can give that id to
another process, so the read showed an empty screen and a negative assertion
could pass. The app list must now show the same process instance; a list
that left copies out is a retryable NODE_STALE.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): make doctor check an appPath bundle the way init does
doctor passed any bundle with a Contents/Info.plist, while init also needs a
CFBundleIdentifier in it, equal to app.bundleId when that is set. A bundle
doctor passed could then fail init, and a plist with no bundle id failed init
with plutil's raw error. Both now use one check, which reports a missing or
mismatched bundle id as the problem.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): never move another install's verified release out of the cache
download() checked whether the cache entry was usable and, if not, moved it
aside before renaming its own unpack in. Two installs that both found no
usable entry could interleave: the second moved aside the release the first
had just put in place, and a worker starting between its two renames found
no executable. The unpack is now renamed into place first. A rename onto an
existing entry fails, and then the entry is used if it checks out, and moved
aside only if it does not.
The race has no deterministic test; a new test covers replacing a damaged
entry, the path this reorders.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(desktop): say when two desktop targets share a run, and what reads empty
- The workers line said two desktop targets can run at the same time
while telling headed runs to set workers: 1, which is what stops them.
It now says they do, and why headed runs set workers: 1.
- The Reading row and capture()'s comment said a window is never read as
an empty screen, but an app with no window open still is, on purpose.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(desktop-testbed): pin ai to the version every other workspace uses
The testbed pinned ai 7.0.173 while the rest of the repo pins 7.0.177, which
put a second copy of ai and its gateway and provider packages in the
lockfile.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): report an open cancelled mid-launch as CANCELLED
An abort while open ran, or while the engine looked for the process it
started, came out as ACTION_MAY_HAVE_COMMITTED, where every other path of
the engine reports CANCELLED. It is now CANCELLED; the launch stays pending
as before, so the end of the attempt still looks for the app.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): settle a pending launch by its last lookup and by its token
quit() dropped a pending launch, and dispose its record, once any lookup in
its wait had a whole answer. Two cases lost an app that was still starting:
- an early complete list with no match, followed by partial ones that could
hide the app once it registered;
- a process carrying the launch's token that the app list did not show yet.
Now only the wait's last answer counts; a lookup that ran out of time is no
answer. Before giving up, quit looks for processes carrying the token and
quits them. The launch stays pending, and its record kept, unless the last
answer was whole and found nothing.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): run launches and quits of one surface one at a time
Two overlapping app.open() calls could both quit, then both launch, writing
into the one process id and launch record the engine keeps; they even shared
the app.json.partial file. The end of the attempt then quit only one copy.
restart, closeApp, endAttempt, and dispose now wait for the launch or quit
running before them. restart's budget counts from the call, so the wait is
part of it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): measure a headed click from where the window is after focus
performAt read the window's bounds, brought the window forward, and clicked
at the bounds read before. A window that moved as it came forward (onto
another space, out from under the menu bar) took the click somewhere else,
possibly another app. The window is now read again after focus-window, and
the point is checked against and measured from its bounds then.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): repair a damaged cache entry under a lock
12c8f64d0 renamed a fresh unpack into place first, which keeps a run from
moving aside a release another run just installed only when there was no
entry. Two runs that both found an entry damaged could still interleave: the
second moved aside the copy the first had just put in place. Its commit
message and comment claimed more than that.
Replacing an entry now holds a lock directory that names its owner's process
id, and checks the entry again under it. A lock whose owner is gone, or that
got no owner and is 10 s old, is taken over; one held for 60 s fails the
install with AGENT_DESKTOP_INSTALL_FAILED.
Tests repair one damaged entry from three runs at once and take over a lock a
dead process left. The interleaving itself has no deterministic test.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): refuse getByPlaceholder, which macOS gives nothing to match
agent-desktop's macOS adapter reports no placeholder for a field; AppKit
folds it into the accessible name of a field with no label. A placeholder
query therefore matched nothing, and not.toBeVisible() or toHaveCount(0) on
it passed with the field on screen. locate() now refuses any expression that
uses a placeholder query with UNSUPPORTED_CAPABILITY, naming getByRole as
the way to find the field, and the docs say so.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(desktop): let desktop({ maxDepth }) set how deep a read goes
A read cut short at the fixed 24-level depth makes every locator on that
window read again until its timeout, since a match could sit below it. An
app nested deeper could not be tested with locators at all. maxDepth, from
1 to 255 (agent-desktop's limit), defaults to 24 and raises it; the partial
read error names the option.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): accept the verified cache copy a run published mid-repair, and keep a launch record when its process lookup fails
A run that finds no cache entry publishes without the lock, so it can fill the gap a locked repair makes between its two renames; the repair then failed with ENOTEMPTY although the cache held a verified release. The repair now accepts a usable copy there.
A failed process listing was read as an empty one, so the stale-worker sweep deleted the record that names the app a killed worker left running. The listing now reports failure apart from none found: the sweep keeps the owner and launch records (removing only the cached field text beside them), and an attempt's quit keeps its pending launch and retries.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* fix(desktop): publish the agent-desktop cache without a lock, keeping a verified winner
The fast path renamed a fresh unpack into place without the lock that the
repair of a damaged entry held. A run that published while a repair had
moved the damaged entry aside made the repair's own rename fail with
ENOTEMPTY, though the cache now held a checked release (seen on the Node
22.22.3 and Node 26 CI jobs). The lock's stale-owner takeover could also
remove a lock another waiter had just taken.
Every run publishes a copy of the same checked release, so the lock is
gone: a rename that collides with an entry accepts it once it is checked,
a damaged entry is moved aside by one rename that only one run wins, and a
whole copy moved aside by a run that saw the entry damaged earlier goes
back. Two tests hold one run at each of those points while another installs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): show a whole cache entry without the right stamp is downloaded again
The stamp test's entry had no executable or macOS helper, so it was
downloaded again even with the stamp check removed. The entry now has
both, and a missing stamp and one for another release each force a
download.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): take a launched process as the engine's own only by its launch token
When no environment could be read, a launch took the one new copy of the
app as its own, and a cleanup after an uncertain launch could quit it.
Being new does not show this launch started it: a copy the developer
opened at the same moment is new too, and was killed in a scripted probe.
A copy is now claimed only when it carries the launch token. agent-desktop's
launch, which reports the process it started, still stands for an app
launched by bundleId. An appPath to a bundle whose environment macOS hides
(an Apple platform app, a build signed with the restrict flag) is refused
by init and doctor, which name the bundleId to use instead, so open never
starts a copy the engine could not find again.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): keep a launch record until cleanup confirms its process is gone
A process lookup that failed read as an empty list: the sweep then
deleted a killed worker's launch record, and the next sweep left the app
running though the lookup worked again. The record held only the token,
so a process the worker had identified, whose environment cannot be read,
could not be found by a later run. A dispose whose quit failed kept the
whole state directory, with the text agent-desktop keeps of the fields.
A failed lookup is now no answer: the pending quit fails and keeps the
launch, and the sweep keeps the record. A kill waits for the process to
exit before the record goes. Once a process is shown to be the launch's,
the record also names its id and start time, so a later run quits it
without reading its environment, and never a later process given that id.
Dispose and the sweep keep only the owner file and the record, and remove
the field text.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): never bring a background app forward to ask it for a window
An app launched in the background that showed no window for 2 s was
brought forward with a second open by path, bundle id, or name. That open
did not name the process the engine launched, so LaunchServices could
bring another copy forward, and it took the keyboard the guide promised
to leave alone.
The background launch now stays in the background. An app that opens no
window there fails the open with a message that it needs
desktop({ headed: true }), whose launch brings the app it starts forward.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): send a key only to the launched process's window, never by app name
agent-desktop refuses a key for a named window that is not active, which
an app in the background never is. The engine then sent the key by the
app's name once a list of the apps showed its copy alone, even a list
agent-desktop marked incomplete. The name does not pin the process, so a
copy that started between the list and the key could get it.
The fallback is gone: a refused key fails as NOT_ACTIONABLE, and nothing
is sent. Since a key then reaches an app in the background only by chance,
press joins the actions only headed offers, so a locator press without
headed fails as unsupported before it moves focus.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(desktop): never retry a press whose focus already moved
A locator press focuses the control, reads its window to check the
control kept focus, then sends the key. A stale read after the focus was
retryable, so the locator ran the whole press again and focused the
control a second time, which an app's focus handler sees. A retryable
failure after the focus is now ACTION_MAY_HAVE_COMMITTED; one before it
stays retryable.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(desktop): show a select that may have reached the app stays possibly committed
Removing the delivery check from the select's ELEMENT_NOT_FOUND mapping
left every select test green. A select whose failure agent-desktop marks
delivered_unverified must stay ACTION_MAY_HAVE_COMMITTED, not "no option".
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(cli): show step keys under the summary and view the screen and app log
The --step and screen.pause() prompt now lists its keys below the live
summary, as --watch does, and the held step row uses a pause glyph.
Press s for the screen's accessibility tree or l for the attempt's app
log. Both open in a scrolling viewer on the alternate screen. The app log
is read from the worker during the hold through a new logs-request and
logs-reply message pair.
The mode without a terminal keeps its text.
* feat(cli): stop the terminal's Duration row while a step is held
The list reporter's Duration row counted wall time, so it kept ticking at
a --step prompt or a screen.pause(). The scheduler now reports when the
first hold opens and the last closes through a run-hold event, and the
row excludes that time, live and in the final summary.
report.json and the reports built from it keep wall time.
* feat(report): add run.durationMs without held time
The report only had the run's start and finish timestamps, so a run that
waited at a --step prompt or a screen.pause() looked as long as the wait.
run.durationMs is the run's duration with held time left out. The
terminal's final Duration row prints the same value. Markdown, the GitHub
comment, the HTML report, and telemetry read it in place of the timestamp
difference. startedAt and finishedAt still record wall time.
A simplification review also removed a few flags and options from the
step viewer and the hold path, and the docs keep each new fact in one
place.
* docs: trim the step viewer changeset and docs
The changeset is down to two sentences. The docs no longer say where the
keys are, since the terminal sample shows it, and the json reporter
section matches main again.
* fix(cli): print the viewer's text before the prompt is repainted
On p, the viewer closed first, so the live window was repainted and then
erased again for the printed text. That left a blank frame. The text is
now queued before the viewer closes, and the window is repainted once.
* fix(cli): number the step prompt by its trace position
The app log view numbered its lines by the recorder's step index, which
counts nested steps, while the prompt counted held steps only. A line
logged inside a nested step could show a different number than the
prompt.
The worker now sends each held step's position in the trace, so the
prompt, the app log view, and the trace page use one number.
The viewer's try blocks are removed too. Nothing received their rethrows,
and the guarded calls don't throw.
* fix(cli): count held time only while every running worker is held
With several workers, a screen.pause() in one test took the time other
tests spent running out of the run's duration. A run could read shorter
than one of its tests. An interval now counts as held only while every
running worker is held. The time limit keeps its rule.
Also from review:
- A routing state an older installed copy made is upgraded in place,
so claimProcessOutput() no longer throws.
- The viewer holds writes only for terminal streams.
- Ctrl-Z closes the viewer and suspends.
- A failed screen read can be retried during the same hold.
- p is ignored while a read is pending.
- The app log view shows plain text, not Markdown code spans.
- The viewer's help row starts with q, and its headings use the
redacted title and target.
* test(cli): cover an older dispatcher installed on the streams
The upgrade test seeded a state with no dispatchers. This one installs
an older copy's dispatchers first, then checks that writes are held
while the viewer is open.
The comment on that branch loses its FIXME prefix. It describes what the
code does.
Adds French as a translation language beside ja and zh, with the style guide, glossary, navigation labels, and the minimum set: Get started and Platforms.
Co-authored-by: Kacper Kapuściak <kapusciak.k@gmail.com>
A docs PR was sized by its English lines plus every translation of them, so a 10-line edit mirrored into two languages got size:M. docs/<language>/** no longer counts.
The language list moves to scripts/docs-languages.ts, shared by the size label and both docs checks. An existing label's description is now updated to match what is counted.
* docs: add a Next.js guide page
One page takes a Next.js developer from `e2e init` to CI: `next dev`
locally and `next start` on the build in CI from one config, the port,
`reuseExisting`, and the Next.js problems (`allowedDevOrigins` on
127.0.0.1, the route announcer that `getByRole('alert')` also matches, a
webpack watcher that reads `.e2e/`), plus the `create-next-app` starter
and the Vercel template. The hydration accordion moves here from web.mdx;
web, cache, and example-projects link to the page, with ja and zh
translations, and the e2e skill's setup reference carries the same
guidance.
Refs ENG-1378
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: move the Next.js page into a Frameworks group
Next.js is not a platform like web, mobile, or desktop, so the page moves
to docs/frameworks/nextjs.mdx under a new Frameworks navigation group. The
web page no longer points at it from the app URL paragraph.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
A coverage check in the pnpm check chain and its own step in spec.yml's check job: every web slug keeps its tests/<slug>.e2e.ts twin, and every mobile scenario its tests-agent entry outside the documented Control Inventory exclusion. Both catalogs parse in either quote style; a catalog that parses to no scenarios fails the check, a `slug:` or `name:` property the parser cannot read (a template literal, a bare identifier) fails it too, and a commented-out `name:` no longer counts as an entry, so a format change or a disabled entry cannot pass the check by hiding a scenario. The web agentic side stays unchecked on purpose: Refs #1777 leaves that part to the issue. file-round-trip gains the twin test the check was missing, opening the page in beforeEach, asserting the input resets after a rejected upload, and covering the voucher that then verifies.
Co-authored-by: Donny/강동윤 <kdy.1997.dev@gmail.com>
* docs: add Hindi as a translation language
Adds hi beside ja and zh in the translation and anchor checks, and keeps
docs/hi out of the npm package, Context7, and the skill wording test.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): add the style guide, glossary, and navigation labels
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): translate the getting-started and platform pages
Translates the minimum set from #1890: index, quickstart, core-concepts,
agentic-vs-deterministic, coding-agents, mcp-server, ci, web, and mobile.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): fix wording and term consistency from review
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): apply the back-translation and Apple terminology review
Fixes the meaning errors a blind back-translation found, such as "similar"
for "matching" and "equal to" for "up to" on the mobile page. Writes the
remaining English words in Devanagari, and follows Apple's Hindi spelling
for accessibility, account, and keyboard keys. Uses इजाज़त for permission
and एक्शन for action, and records both in the glossary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): fix agreement and ambiguous clauses from the Sol re-check
Splits sentences where a clause could attach to the wrong noun, such as
the location in the assertion inputs and the checked state of a hidden
checkbox. Restores the Cursor update line to the Cursor commands only.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): use तालमेल बिठाना for the agent adapting on the landing page
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): follow main's removal of the run_tests MCP tool
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(hi): unify reference, action, and state, and rewrap long lines
Uses रेफ़रेंस for "reference" everywhere, as most links already did, and
records स्थिति (app state in prose) beside स्टेट (stored or device state).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Kacper Kapuściak <kapusciak.k@gmail.com>
* docs(pt-BR): translate the minimum set
Add the Brazilian Portuguese locale with the Get started and Platforms
pages (index, quickstart, core-concepts, agentic-vs-deterministic,
coding-agents, mcp-server, ci, web, mobile), navigation labels, and a
README with the style guide and glossary.
Register `pt-BR` in the translation and anchor checks, the build and
skill-test exclusions, and context7.json, next to ja, zh, cs, and es.
List it in AGENTS.md and the authoring-docs skill, whose checklist now
says "every docs/<language>/ folder" so the next language needs no edit
there.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(pt-BR): state the timing order and what docs:check covers
The ci page now says untimed files run first, then the rest longest
first. The README says docs:check compares page outline and code, and
only checks that each tab and group has a label.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Claude Code loads .mcp.json from a plugin's root even when the manifest names none, so the file goes and Codex and Cursor read the server from mcp.json, the Agent Plugins file Copilot already uses. plugins:check fails if .mcp.json comes back.
* docs(es): translate the getting-started and platform pages
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): follow the worker fixture change in mobile and accept feminine bloqueada
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): fix agreement and meaning slips, restore main's translation policy
The earlier patch to scripts/check-docs-translations.ts and the
authoring-docs skill was made against an older main and reverted the
best-effort policy; both now carry only the es registration.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): follow the best-effort translation policy in the README
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(es): say what docs:check detects
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs: list the Spanish translation in AGENTS.md
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-authored-by: Kacper Kapuściak <kapusciak.k@gmail.com>
* docs(cz): translate the minimum set
Add the Czech locale with the Get started and Platforms pages,
navigation labels, and a README with the style guide and glossary.
Register `cz` in the translation checks and exclusions like `zh`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cz): fix three translations flagged in review
- web: the run fails with APP_ALREADY_RUNNING, not the server
- coding-agents: `init` registers the server, not the other way round
- quickstart: rephrase the config options intro
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cz): address review: no en dash, current README rules, mobile install
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(cs): use the language code cs instead of the country code cz
Czech is `cs` in ISO 639-1 and BCP 47, which browsers send and `lang` and
`hreflang` expect. The code is also the URL, so rename before launch.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
English stays current in every change; the Japanese and Chinese
translations may lag behind, since no contributor can be expected to
update a language they don't speak. check-docs-translations.ts now warns
on outline, code, and navigation label drift instead of failing, and
fails only on what needs no language to fix.
Refs ENG-1385
* docs: add Simplified Chinese as a translation language
Adds zh beside ja in the translation and anchor checks, and keeps docs/zh
out of the npm package, Context7, and the skill wording test.
* docs(zh): add the style guide, glossary, navigation labels, quickstart and overview
* docs(zh): translate all documentation pages
* docs(zh): keep error categories in English, align setup test, blocked, and schema terms
* ci(docs): check the japanese docs against deepl
Each changed section of a docs/ja page is translated back into English and compared with the English page's section, and compared with DeepL's own Japanese for the English, both with chrF. A section far from DeepL in both directions, left in English, or missing a glossary term DeepL used gets a warning on its heading and a row in the job summary. Sections pair by position, which check-docs-translations.ts guarantees. The glossary in docs/ja/README.md is uploaded as a DeepL glossary.
* ci(docs): review every section when the deepl check itself changes
* ci(docs): check only changed sections, report deepl usage and every score
* ci(docs): flag below 0.25 and skip the review when deepl's quota is used up
* ci(docs): fall back to gpt-6-luna on the ai gateway when deepl's quota runs out
* ci(docs): keep the fallback model private to deepl-review
* ci(docs): ask the model again after an answer that is not json
* docs(scripts): say the reference, not deepl, now that a model can translate
* docs: add the Japanese translation
Adds docs/ja/, a Japanese page for every English docs page at the same
path, with the tab and group labels in docs/ja/navigation.json. The site
serves them at /docs/ja and gives each translated anchor its English id by
position, so check-docs-translations.ts keeps every translation's outline
equal to its English page's. The npm package keeps shipping only the
English pages.
* docs: check translated code blocks, keep docs/ja out of Context7 and the skill wording test
* docs(ja): sync with the English pages' latest changes (test.skipIf, tool schemas, star link)
* docs(ja): start with the quickstart page only
* docs(ja): translate getting-started and platform guides
* docs(ja): translate all documentation pages
Manage local Moli CDP browsers through the web engine's BrowserProvider API.
Each worker gets an available loopback port, layout and resource loading,
startup cancellation, and process cleanup when its lease ends.
Wire the testbed, documentation, consumer skill, build and test commands,
and a patch changeset for @e2e-dev/moli.
Keep process-group shutdown active after an executable wrapper exits,
and surface process-inspection failures in the provider tests.
Verified locally:
- pnpm check
- 16 Moli provider unit tests
- Testbed on two workers: 16 passed, 1 expected skip; both browsers released
- Empty and whitespace CDP URLs use managed browsers; padded URLs attach
without stopping the existing server
- MCP login, secret fill, assertions, and screenshot
- Packed packages installed, typechecked, and run in an isolated project
Adds a generated plugin.json and mcp.json at the plugin root, strips
metadata.openclaw from the plugin's skill copies, and drops the
out-of-directory link in create-verification-skill, so the plugin passes
awesome-copilot's external plugin intake.
* docs(ci): rename the Vercel page to Vercel previews
* docs(ci): move the Vercel previews page to /ci/vercel-previews
* docs(ci): capitalize Vercel Previews
* docs(ci): drop the redirect, the page is not shipped
`@e2e-dev/web` and `@e2e-dev/mobile` declare `e2e` an optional peer, but
their main entry imported it statically to build `test`. A program on
`@e2e-dev/core` alone that wrote `import { web } from '@e2e-dev/web'`
failed with ERR_MODULE_NOT_FOUND before any of its code ran.
The main entry now requires `e2e` only when it resolves. Without it, the
engine factory works and `test`, `describe`, and the hooks throw
RUNNER_NOT_INSTALLED when called. It uses createRequire, not a top-level
await, so a CommonJS file can still require() the entry.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* refactor: move e2e's core into @e2e-dev/core, and engines peer on it
The engine contract, locators, agent, replay cache, secrets, and the
session half of a worker move from packages/e2e to packages/core, the new
@e2e-dev/core package, at the same paths. e2e depends on it at its exact
version (a changesets fixed group) and reaches its modules through
@e2e-dev/core/lib/*, which is not public API; e2e/engine and e2e/agent
re-export it. @e2e-dev/web and @e2e-dev/mobile peer on @e2e-dev/core and
import the contract from @e2e-dev/core/engine. Install smoke checks that one
copy of @e2e-dev/core is installed.
Most of this diff is git mv and import specifiers rewritten to
@e2e-dev/core/lib/<path>; no behavior changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* ci: build and pack @e2e-dev/core where e2e is built or packed alone
The Bun job built e2e before the @e2e-dev/core it compiles against, and the
examples nightly installs e2e from a tarball whose exact @e2e-dev/core is
not on npm; it now packs @e2e-dev/core and overrides it in each example.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(engines): name @e2e-dev/core/engine as the contract's source
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(e2e): list @e2e-dev/core beside an engine in init and upgrade
Engines peer on @e2e-dev/core. Yarn installs no peer the project does
not list, and under Plug'n'Play the engine then fails to load.
- init adds @e2e-dev/core with any engine
- upgrade adds a required @e2e-dev peer the project lacks, and keeps a
package e2e depends on at the version e2e names
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
* feat(mobile): export agent-device from @e2e-dev/mobile/agent-device
Custom tools that extend the mobile engine with agent-device calls have
to import `agent-device` directly. pnpm does not resolve that import
from a transitive dependency, so the project installs agent-device
itself and has to keep it at the exact version @e2e-dev/mobile pins,
because two versions do not share one daemon.
The new subpath re-exports what a tool commonly needs from the engine's
copy: `createAgentDeviceClient`, the error helpers (`AppError`,
`isAgentDeviceError`, `normalizeAgentDeviceError`), `centerOfRect`, and
the types for the client, snapshots, screenshots, targets, gestures,
text entry, alerts, and waits. `ensureDaemon` and `startAgentDevice`
stay out because the engine owns the daemon.
The install smoke imports the subpath from a fresh pnpm project with no
agent-device dependency and checks there is one agent-device install.
The e2e skill tells agents to use this import instead of adding
agent-device.
* docs(mobile): mark @e2e-dev/mobile/agent-device unstable, point tests to unstable_raw
A client built with `createAgentDeviceClient` does not get the engine's
daemon, lease, or per-worker session name, so the docs no longer say it
drives the engine's session. Tests use `device.unstable_raw.client`.
The subpath is agent-device's API at the pinned version, so it is
labeled unstable like `unstable_raw`.
* chore(mobile): shorten the agent-device subpath comments
* feat(mobile): give custom tools the running device session
A custom tool had no way to reach the engine's agent-device client, and
a client built from `createAgentDeviceClient` misses the engine's
daemon, lease, and per-worker session. `deviceSession(...engines)` on
`@e2e-dev/mobile/tools` returns the running attempt's `DeviceSession`,
the object a test reads from `device.unstable_raw`, using the lookup
`mobileTools` already had.
From review: `@e2e-dev/mobile/agent-device` drops the client factory and
keeps the types and error helpers. The skill line is scoped to these
imports, and the stale Limrun peer line is fixed. The export-map test
checks every entry's paths, the install smoke stops reading the `.pnpm`
layout, and the docs keep one full description in the reference.
* fix(mobile): spread the device selection in the deviceSession example
The docs example called `settings.update` without the session's
`selection`, unlike every engine call, so it could miss the worker's
device before an app is open. Also restores `createDeviceFixture`'s
JSDoc and tests the several-attempts refusal of `deviceSession`.
* refactor(mobile): keep raw sessions behind a neutral unstable API
* fix(mobile): type the unstable raw session client
---------
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
* docs(examples): add the GitLab CI/CD example
Let the registry list examples on gitlab.com: the schema accepts GitLab
projects and folders, official examples may live in the e2e_inc group, and
the checks pin, compare, and fetch GitLab URLs. A partner example stays on
GitHub, under its author.github.
* docs(examples): say partner examples live on GitHub in the contributing guide
* docs: retire sidebar page icons
The docs sidebar no longer shows icons. Drop icon: from every page's frontmatter, delete the grey silhouettes in docs/images/icons/, and make check-docs-logos fail on any frontmatter icon instead of requiring one on vendor pages. Card logos stay required. The authoring-docs skill trades its Page icons section for a short Vendor logos one.
* docs: require a migrate overview card for each migration guide
* docs: match only top-level icon keys in check-docs-logos
* docs(migrate): show the TesterArmy logo in the sidebar and add its card
The sidebar icon was the dithered black mark, which the site's grey
silhouette filter smeared into a blob at 16 px. Use TesterArmy's favicon
instead: grey shades in the sidebar, brand colors on the new card in the
migrate overview.
* docs(skills): exempt the TesterArmy icon in the authoring-docs checklist
* feat(examples): add 26 community examples, pinned to a commit, with an optional readme
* docs(examples): allow an example without a README in what we look for