@unotest/web 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -1,5 +1,425 @@
 # Changelog
 
+## [0.43.0] - 2026-09-27
+
+### Minor Changes
+
+- 6fc8140: A run on an environment no longer inherits a host from the base `.env`
+
+  Environment files layer: `unotest/.env` first, then the `unotest/.env.<name>`
+  overlay an active environment selects, the later file winning. That is the
+  right rule for a password or a user name, and the wrong one for a host. A
+  project whose base file points `API_BASE_CHAT` at production, and whose
+  `dev` overlay does not mention it, ran `--env dev` and sent its API calls to
+  production. Nothing in the output said so: the reply reported the `dev`
+  environment, and the requests went elsewhere.
+
+  From this release a variable that becomes a HOST has to come from the active
+  environment's overlay, or from the process environment. Three variables count
+  as hosts: `APP_BASE_URL`, which every relative `goto` resolves against; the
+  name passed as `apiCall(..., {base: "NAME"})`; and a variable used as the URL
+  in `goto(NAME)`. When the value still comes from the base file, the run is
+  refused before the browser starts, and `lint`, `run_test` and `explore_start`
+  refuse identically — with a message that names the variable, both files, and
+  the two ways forward. Every other variable layers exactly as before.
+
+  A base value that really is meant for every environment is declared once, in
+  `unotest.config.{js,mjs,ts}`:
+
+  ```js
+  export default { env: { shared: ["API_BASE_CHAT"] } };
+  ```
+
+  A value the process environment supplies — a shell variable, or the values a
+  box injects into a run — is never affected by this rule: it is a value
+  somebody stated for this run, not one silently inherited from a file the
+  overlay was supposed to replace.
+
+  Migration: a suite that runs with `--env <name>` and keeps its host in the
+  base file will now refuse, naming the variable. Either add the variable to
+  the overlay, which is what most projects meant, or list its name under
+  `env: { shared: [...] }`. A suite that never uses `--env` is unaffected.
+
+- 703185f: A run held at its failure has a screenshot, and the tools answer while it stands
+
+  A run paused on a failure left nothing on disk: no failure bundle, no
+  screenshot, and `get_failure_screenshot` replied "failure bundle not
+  found". The frame only appeared once the run was over — which is the one
+  moment it is least useful, because the browser has closed and the page
+  that broke is gone. Meanwhile the run was sitting right there, still
+  showing it.
+
+  The bundle is now written at the pause, from that page, so
+  `list_failures`, `get_failure_screenshot`, `get_failure_a11y` and the
+  rest answer on the first call. Each record carries `runState`: `paused`
+  while the run is still held — the browser shows the failure, and a
+  resumed run that fails again elsewhere re-takes the frame at the new
+  failure — then `finished` or `aborted` once the run is over. The frame
+  of a finished run stays the one taken at the failure: resuming continues
+  with the next statement, so the page moves on while the verdict does
+  not, and re-taking it at the end would show a page the failure never
+  happened on.
+
+  Also fixed: aborting a run while it was paused left its process alive
+  until the 30-minute inspection TTL expired. The run now ends when it is
+  aborted.
+
+- 7006895: Spending and deleting wait for a person
+
+  A key of a customer account — an agent's key, a signed-in machine's, and a CI
+  key issued before this release — can no longer rent a box, delete one or
+  switch the Picker on by itself. The cloud records what was asked for and answers with a
+  request instead; somebody approves or declines it in the cabinet, on the
+  Approvals tab, and only a signed-in browser can — not the key that asked, and
+  not the link in the email about it. Nothing is created and nothing is charged
+  until that happens.
+
+  For the CLI this is a wait, not a failure. `box create`, `box destroy` and
+  `box picker on` print where to answer and how long the request lives, then
+  carry on with what the cloud finally did and print exactly what they would
+  have printed anyway. Ten minutes with no answer is exit code 75 — nothing was
+  created and nothing was charged, run the command again. A decline is exit code 2. `--yes` does not skip it: the flag says the terminal need not ask, not that
+  the account need not.
+
+  Only the CI key of an operator account, one that unotest runs itself, acts
+  with nobody watching. A pipeline that rents or deletes boxes with a
+  customer's key now waits for somebody to press Approve, or has to rent its
+  box ahead of time.
+
+- 4582091: `box create` with a short balance points to the dashboard instead of starting a top-up
+
+  The cloud's API for agents has no top-up: credit is added by a person, by
+  card, under "Add credit" on the dashboard's home page. `box create` used to
+  start a payment from the terminal when the balance did not cover the first
+  hour, against an endpoint the service does not have, so on the real cloud it
+  failed with a 404.
+
+  Now it stops before renting anything and says what is short: the first hour's
+  price, the balance and the amount missing, and the dashboard page to add it
+  on. It exits 75 — nothing created, nothing charged — and is run again once the
+  credit is there. A key that cannot read the balance (the one `login` issues
+  cannot) gets the price and the page, and no invented shortfall. `--json`
+  prints `{ "needs": "top-up", "firstHourCents", "balanceCents",
+"missingCents", "currency", "url" }`, with `null` for a figure the key may not
+  read.
+
+  The `cloud_box_create` MCP tool answers the same case as
+  `{ state: "top-up-needed" }` with the same figures, instead of an error.
+
+  Migration: the `--topup <eur>` flag of `box create` is removed — top-up moved
+  to the dashboard. A script that passes it is refused with the usage and exit
+  2; drop the flag, and add credit on the dashboard's home page before renting.
+
+- dae29a2: The cloud account as commands and as MCP tools: `box list`, `box logs`, `approvals`, and nine `cloud_*` tools
+
+  An agent could read a box it had been pointed at and nothing more: which
+  boxes the account had, renting one and deleting one lived in a terminal, and
+  the list of boxes appeared only inside an error message. The account is now
+  reachable from both sides through one implementation, so a box reads the same
+  whether a person or an agent asked.
+
+  New commands:
+
+  - `box list` — every box on the account with its state, version and projects.
+    `--json` prints the same objects the `cloud_boxes_list` tool returns.
+  - `box logs [name] [--bootstrap|--updater]` — the end of a box's own log,
+    without logging in to it. A box sends it on its next five-minute check, so
+    the first call says it has been asked and when to run again, with exit 0.
+  - `approvals [id]` — what is waiting for a person on this account, or what
+    became of one request. Answering stays in the cabinet: a terminal holding
+    the key cannot approve its own request.
+
+  New MCP tools, outside the `core` toolset: `cloud_boxes_list`,
+  `cloud_box_status`, `cloud_box_create`, `cloud_box_destroy`,
+  `cloud_box_access`, `cloud_box_update`, `cloud_box_logs`, `cloud_balance`,
+  `cloud_approval_wait`. `cloud_box_access` writes the fresh pair into the
+  project the way `box access` does and answers with the names it wrote, never
+  the values. They answer states an agent can act on instead of
+  errors: `not-logged-in` with the command that fixes it, `approval-pending`
+  with the request to wait on, `insufficient-scope`, and `declined`,
+  `expired` or `still-waiting` from the wait.
+
+  While a rent or a delete waits for approval, the terminal now names it in the
+  words the cabinet and the email use — `Rent a box "acme", size s (€0.09 per
+hour)` — and prints a line when it is approved, not only when it is declined.
+  The sentences live in `@unotest/protocol` (`approvalActionText`,
+  `approvalPrice`), shared by every surface that shows a request.
+
+  `unotest-web --help` and `box --help` list the new commands, say which
+  commands wait for approval, and give one table of exit codes. `box <command>
+--help` now prints that command's own flags wherever `--help` sits on the
+  line, and `approvals` refuses an option it does not know with exit 2.
+
+  Compatibility: every call to the cloud now carries an `X-Unotest-Client`
+  header. The cloud refuses a call that would wait for approval when the header
+  is missing — an older CLI could not read the request it would be handed — with
+  `426 client-too-old` and a message to update. Update `@unotest/web` before
+  renting or deleting boxes with any key of a customer account, a CI key
+  included.
+
+- ba32d73: A config key the package does not know is refused, with the key you probably meant
+
+  `chanel: "chrome"` used to be dropped in silence: the run went ahead on
+  the default channel, printed `1 passed` and exited 0, so the one setting
+  you changed was the one setting that did not apply. Every section of
+  `unotest/unotest.config.*` is now checked by name, before the browser
+  starts:
+
+  ```
+  e2e: config validation failed:
+    unknown key "chanel" — did you mean "channel"?
+    retry: unknown key "cuont" — did you mean "count"?
+  ```
+
+  A key nothing is close to gets the other answer, because it usually
+  comes from a config written for a newer release than the installed
+  package:
+
+  ```
+    unknown key "telemetryEndpoint" — not a config key; check your
+    @unotest/web version if it comes from a newer release
+  ```
+
+  The config `unotest-web init` writes no longer offers a `viewer` section:
+  the viewer's port has always come from `UNOTEST_VIEWER_PORT`, and the
+  section was a suggestion the schema never had. A config generated by an
+  earlier version needs that block removed.
+
+  **Migration.** A config that carries a key this version does not know
+  now fails instead of running: fix the spelling, remove the key, or
+  install the release the key belongs to. Nothing else about the config
+  changes — every known field keeps its name, its default and its merge
+  behaviour, and a partially written section is still merged with the
+  defaults key by key.
+
+- fb12602: A step that takes minutes no longer disappears into the client's background
+
+  Waiting on a slow page — a chat answer that takes four minutes to come
+  back, a report that builds itself — used to be a call your agent never got
+  an answer to: MCP clients stop waiting at about two minutes and carry on,
+  and whatever the step replied after that was lost. The way round it was to
+  cut every wait to under a hundred seconds and repeat the step.
+
+  Now a step still running after 90 seconds answers `{ status: "accepted",
+taskId }` and keeps going: same timeout, same recording into the session.
+  Collect it with the new `explore_step_result({ taskId })` — `running`,
+  `done` with the reply the step would have given, or `failed`. A batch of
+  steps goes to the background as one task, for one id. The `durationMs` of
+  a collected step is the whole step, from its start — there is no threshold
+  to add back by hand.
+
+  While a step is out there, the browser context says so instead of being
+  damaged: another step, `explore_stop` and `close_context` answer `busy`
+  and name the task to wait for, and `explore_state` lists what is pending.
+
+- 82d5920: Signing in to a box with one environment opens its viewer straight away
+
+  A box configured with a single environment used to answer a sign-in with a
+  screen holding one option and a button. There was nothing to choose, so the
+  screen only stood between you and the viewer behind it.
+
+  Now that sign-in lands in the viewer. The **Environments** screen still
+  appears whenever it has something to say — more than one environment to pick
+  from, a box that has not been sent a test suite yet, or a licence in its
+  grace period, whose warning lives there.
+
+  So that skipping the screen does not hide what it carried, the viewer's
+  session menu now offers **box pages**: one link back to the box's own
+  pages — environments, read tokens, and administration for those who have
+  it. It appears when the box tells the viewer where they are, so a viewer
+  and a box on different versions simply do without it.
+
+- 3aee366: take_wheel now points the session at the run it takes the wheel of
+
+  An agent debugging a paused run would call `take_wheel`, take a
+  screenshot, and get a picture of a completely different stand — whatever
+  page the session had been recording on before. Nothing was wrong with the
+  screenshot: the wheel only ever took the control token, while the browser
+  stayed where it was, and the reply said `ok` either way.
+
+  `take_wheel` now also attaches this session to the run's browser, so the
+  next screenshot, snapshot or step reads the page being debugged. Every
+  `explore_step` reply carries `context` — `{kind: "run", runtimeId}` or
+  `{kind: "own"}` — so the source of a frame is stated rather than guessed.
+  A session has exactly one browser: `take_wheel` and
+  `attach_debug_session` point it at a run, `explore_start` and
+  `new_context` at your own, and `explorationId` chooses recording and
+  where a file is filed, never which browser a step runs on.
+  `release_wheel` hands the token back and deliberately leaves the browser
+  on the run.
+
+  Behaviour change for anything parsing the reply: `take_wheel` no longer
+  always answers `ok`. When it cannot join the browser it answers
+  `recording_open` (a live recording would be dropped — nothing is changed,
+  not even the wheel), `no_browser` (the run has not published one yet) or
+  `no_page`, each naming what to do next.
+
+- 9034092: Opening a box's viewer while a suite is being installed no longer looks like a failure
+
+  Sending a new suite to a box replaces that environment's viewer, and for the
+  second or two that takes, anyone holding the page open got a bare `502` — the
+  status that tells a browser nothing and tells a script the box is broken.
+
+  The box now says, while it is happening, that it is replacing that viewer. A
+  browser gets a short page that comes back by itself once the new viewer
+  answers; an agent reading the box with a token gets `503` with `Retry-After`
+  and `unavailable`, which is the box's existing word for "wait and ask again".
+
+  A viewer that stopped for any other reason answers the same way but promises
+  nothing, and the page does not reload itself: nobody is bringing it back, and
+  saying otherwise would be worse than saying nothing.
+
+### Patch Changes
+
+- b41b02e: A cloud that will not show the price list is quoted as such, not as free
+
+  `box create` and `box picker on` quote the hourly price inside the
+  question they ask. When the cloud refused the price list, the question was
+  asked with no price in it at all — and silence there reads as "this is
+  free", with no way for the reader to learn that a price exists and they
+  were not shown it.
+
+  A refusal for want of a permission now says so: `price not visible to this
+key: it needs billing:read`. On a current cloud the list is under `read`,
+  which every key from `login` carries — so this is what an OLDER cloud says
+  to a newer client, which is exactly when a client must not go quiet about
+  money. Every other reason stays silent, because a cloud older still has no
+  price list at all and a command must not fail for want of a courtesy.
+
+- 3e7e3fc: API keys carry permissions
+
+  A key used to be all or nothing: any live key could do everything the API
+  offers. Now every key carries a list of permissions — see the boxes, manage
+  them, read the balance — and every route states the one it needs. A key
+  without it gets `insufficient-scope`, which is a 403 and not a 401: the
+  credential is good, so signing in again would change nothing.
+
+  Where the list comes from depends on the key. In the cabinet you tick the
+  permissions when issuing a key for an agent. Signing a machine in asks for
+  enough to see your boxes and work with them, never your money, and the
+  approval page in the browser lets you narrow that before you approve — the
+  key then has exactly what was left ticked. `login` and `whoami` print what
+  the key may do.
+
+  Keys that already exist keep the permissions they had, with one exception:
+  spending money and deleting with nobody watching. Only the CI key of an
+  operator account, one that unotest runs itself, may do that. A CI key a
+  customer holds from before this release works like an agent's key: renting,
+  deleting and switching the Picker on wait for a person to approve.
+
+  One visible change for a key that cannot read the balance: `whoami` says so
+  on the balance line instead of failing, and signing in with such a key is
+  still recognised as being signed in.
+
+- 8353232: A rental the account cannot pay is refused before anybody is asked to approve it
+
+  A key that may not spend by itself used to get an approval request for a box
+  even when the balance could not cover the first hour: a person was asked to
+  approve it, and the rental then failed at their yes. The money is now checked
+  first, and such a create is answered `402 insufficient-balance` with nothing
+  recorded and nobody written to. The check at approval stays — a balance can
+  move while a request waits — and a request that fails there says so in words:
+  the price of the hour and where to add credit.
+
+  Every `insufficient-balance` carries `topupUrl`, the dashboard page where a
+  person adds credit. A key that may read the account's money also gets
+  `firstHourCents`, `balanceCents`, `missingCents` and `currency`; any other
+  key gets no figures.
+
+  `box create` prints the cloud's own figures and link when the refusal carries
+  them, instead of counting them again.
+
+- 2006bf9: A refused config says which field is wrong, and `channel` takes the same words everywhere
+
+  Any bad value in `unotest/unotest.config.mjs` used to come back as one
+  line — `config validation failed` — with no field, no value and no list of
+  what would have been accepted, though all three were known. Now the
+  refusal names them:
+
+  ```
+  config validation failed:
+    channel: expected one of "chrome" / "msedge" / "chrome-beta" / "chromium" / "bundled" / null, got "bundeld"
+    defaultTimeoutMs: expected number, got string
+  ```
+
+  And `channel: "bundled"` is accepted. `UNOTEST_BROWSER_CHANNEL` has always
+  taken that word — the `.env` template says the variable merely overrides
+  `channel` — while the config refused it. Both inputs now share one
+  vocabulary, and `bundled` means what it has always meant: Playwright's own
+  Chromium, the default.
+
+- e7cdab7: An empty id is refused instead of quietly changing what a tool does
+
+  `explore_step` and `explore_steps` treated `explorationId: ""` as "run
+  this without recording": the step went through, the reply said it had
+  succeeded, and nothing reached the session log. The agent found out at
+  `explore_stop`, with an empty recording and the work already done. The
+  same held for `explore_record`, and for `runtimeId: ""` in the debugger
+  tools, where an empty value silently meant "the session you attached to".
+
+  An empty id is now an input error naming the field, exactly as the
+  neighbouring tools have always answered. Leaving the key out is still how
+  you ask for the ad-hoc mode — absence is the mode, emptiness is a typo.
+
+- a3f89ee: The MCP server reports the version it actually is
+
+  `initialize` answered `serverInfo` with a hard-coded `0.1.0` whatever
+  version of the package was running, while `--version` printed the real
+  number. An editor showed the wrong version in its server list, and nobody
+  checking a session could tell a server started from npm apart from one
+  started out of a working copy.
+
+  Both surfaces now read the package's own manifest through one helper, so
+  they cannot drift apart again. A manifest that cannot be read is an error
+  naming the fault, not a silent `0.0.0` — an invented version reads as a
+  real answer in a protocol reply and in a support transcript.
+
+- f1f3fb1: Existing boxes install the five-minute update check themselves, and report a finished update in the tick that applied it
+
+  A box rented before the five-minute check existed only had the hourly timer:
+  pressing **Update** in the cabinet could take up to an hour and a half to
+  reach it. The updater now installs that pair of systemd units itself when the
+  box does not have them — exactly those two, only when the file is absent, and
+  never replacing a unit an operator edited.
+
+  A finished update is also reported in the tick that applied it, instead of in
+  the next one, so the cabinet card and `box status` stop showing "updating" for
+  a box that is already done.
+
+  **Both start working with the update after this one.** The move onto this
+  version is still carried out by the updater a box runs today: it arrives on
+  the hourly timer — up to an hour and a half — and that first "applied" still
+  comes with the next hourly tick. From there on the new updater is in charge,
+  a pressed **Update** lands within minutes, and the cabinet shows it as done as
+  soon as it is.
+
+- 74a1f9d: The viewer finishes writing its run index before it exits
+
+  On boot, and whenever a run finishes or the environment switches, the viewer
+  rebuilds the derived index it serves history from. Those writes are
+  deliberately not waited for while the server runs — a history months deep
+  must not hold the UI back — but they were not waited for on the way down
+  either. Stopping the viewer returned while files were still landing under the
+  run directory: a directory the caller believed had been released kept growing
+  for a fraction of a second, and anything that removed or archived it right
+  after the viewer stopped could fail or capture a half-written index.
+
+  Shutdown now waits for the index writes that are still in flight, so a
+  stopped viewer is a viewer that has finished writing. A rebuild that takes
+  longer makes the stop take longer, which is the honest cost of not leaving
+  half a file behind.
+
+- Updated dependencies [6fc8140]
+- Updated dependencies [4582091]
+- Updated dependencies [dae29a2]
+- Updated dependencies [82d5920]
+- Updated dependencies [74a1f9d]
+  - @unotest/core@0.43.0
+  - @unotest/protocol@0.43.0
+  - @unotest/viewer@0.43.0
+  - @unotest/dsl@0.43.0
+  - @unotest/grounder-client@0.43.0
+
 ## [0.42.0] - 2026-09-24
 
 ### Minor Changes
@@ -818,7 +1238,7 @@ picker on` fetches this project's own access and writes the three grounder
 
   That screen named one command:
 
-            npx @unotest/web bundle push --run --env ENVIRONMENT
+              npx @unotest/web bundle push --run --env ENVIRONMENT
 
   In a project that has just been created, the command refuses with `no box
 address` before it does anything: the project holds neither the box's address
@@ -827,8 +1247,8 @@ address` before it does anything: the project holds neither the box's address
 
   The screen now names both steps, in the order they have to happen:
 
-            npx @unotest/web box access larch
-            npx @unotest/web bundle push --run --env ENVIRONMENT
+              npx @unotest/web box access larch
+              npx @unotest/web bundle push --run --env ENVIRONMENT
 
   The box's own name is filled in when its licence carries one. `box access`
   with no name refuses, and its refusal offers to create a box — to somebody who

package/README.md

@@ -152,15 +152,47 @@ npx @unotest/web box create   # rents a box named after the project, size S
 boxes — and keeps the key in `~/.config/unotest/credentials.json`
 (mode 0600). `box create` creates the box with the environments the
 suite already runs locally (each `unotest/.env.<name>` and its
-`APP_BASE_URL`), asks for a top-up when the balance is short (it prints
-the Checkout link and waits for the payment), waits for the box, writes
+`APP_BASE_URL`), waits for the box, writes
 `UNOTEST_BOX_URL` to `unotest/.env` and the push and read tokens to
 `unotest/.secrets`, pushes the suite and prints the viewer's address.
 The tokens live thirty days; `bundle push` and `box …` re-mint them
 through the cloud when a box says they have expired, and `box access`
-does it on demand. `box status` and `box destroy` do what they say;
-`whoami` and `logout` complete the set. In CI, export
-`UNOTEST_CLOUD_TOKEN` instead of signing in.
+does it on demand. `box list` shows every box on the account, `box status`
+one of them, and `box logs` the end of a box's own log without logging in to
+it; `box destroy` does what it says, and `whoami` and `logout` complete the
+set. In CI, export `UNOTEST_CLOUD_TOKEN` instead of signing in.
+
+Credit is added in the cabinet, by card, under "Add credit" on its home page
+— never from the terminal. When the balance does not cover a new box's first
+hour, `box create` says how much is missing (as far as the key may read the
+balance) and where to add it, and exits 75 with nothing created and nothing
+charged; run it again once the credit is there.
+
+Anything that spends money or cannot be undone — creating a box, deleting
+one, switching the Picker on — **waits for a person** unless the key is a CI
+key. The CLI prints where to approve it and how long the request lives, waits
+there, and then carries on exactly as if the call had gone straight through.
+Nobody answers in ten minutes: exit code 75, nothing created and nothing
+charged, run the command again. Somebody declines: exit code 2. `--yes` does
+not change any of this — the flag says the terminal need not ask, not that
+the account need not.
+`approvals` lists what is waiting, and `approvals <id>` says what became of
+one.
+
+An agent does the same through the MCP server's `cloud_*` tools — listing,
+renting, deleting, logs, the balance — with the same key and the same rules:
+a rent or a delete comes back as a request to wait on, and
+`cloud_approval_wait` waits for the person's answer.
+
+A key carries **permissions**. `login` asks for enough to see the
+account's boxes and work with them, never its money, and the approval
+page in the browser is where you can narrow that further; `login` and
+`whoami` print what the key ended up with. A key that may not read the
+balance is still a working key — `whoami` says the balance is not
+visible to it instead of failing — and a call it may not make comes
+back as `insufficient-scope`, which no amount of signing in again will
+change. Keys for an agent are issued in the cabinet, with the
+permissions ticked there.
 
 The **Picker** — grounding intent locators on the box's grounder — comes
 with the box today: it lists at €0.05–€0.13 an hour depending on size,