@unotest/grounder-client 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,179 @@
 # Changelog
 
+## [0.35.0] - 2026-09-15
+
+### Minor Changes
+
+- 86da16e: A remote grounder can now say "this account has spent its month", and a client
+  can tell that apart from a bad token.
+
+  A grounder running on an external model provider meters what each account
+  costs and stops at a ceiling. At the ceiling the two routes that call a model —
+  indexing a page and resolving an intent — answer HTTP **402** with
+  `grounder-budget-exhausted`. Money, not permission: the token is perfectly
+  good, nothing is re-minted over this, and a client that treats it as an auth
+  failure would retry forever. The body carries no amount and nothing about any
+  other account; the figure is an estimate of a bill we do not issue, and a
+  customer would rightly check it against the provider's own.
+
+  What a ceiling stops is **writing** tests, not running them, and every text
+  about it says so: only the MCP server asks the grounder — `ground_element`,
+  and an intent locator inside `explore_step` / `find_element`. A scenario
+  carries the locator it was written with, so suites, their runs on a box and
+  the viewer are untouched by a cap.
+
+  `ErrorResponse.code` names it, and gains `revocation-list-unavailable` at the
+  same time: a grounder has been answering with that code since signed tokens
+  arrived, and the union never learned about it — a client written from the type
+  could not discriminate a refusal it was already receiving. `retryAfterSeconds`
+  joins the shape for it, matching the `Retry-After` header that was already
+  being sent.
+
+  Nothing changes for a grounder running on our own GPU: nothing is metered
+  there, so nothing can be refused for money.
+
+- 7ffa4ae: `box picker on|off`: the Picker, switched on a box you already have
+
+  The Picker is an hourly surcharge on top of the box, and until now it could
+  only be chosen when the box was rented — with `box create --picker`, a flag
+  most people met for the first time in `--help`.
+
+  - **`unotest-web box picker on|off [name]`** switches it on a live box, with
+    no re-creating and no re-pushing. `on` mints the box's tokens the way
+    `box access` does and writes the Picker's three keys —
+    `UNOTEST_GROUNDER_MODE=remote` and `UNOTEST_GROUNDER_REMOTE_URL` into
+    `unotest/.env`, `UNOTEST_GROUNDER_REMOTE_TOKEN` into `unotest/.secrets`.
+    `off` clears the three again, but only when they name that box's grounder:
+    a project pointing at a grounder of its own, or at another box's, keeps it
+    and is told so. Either way the charge follows at the next hourly tick,
+    because a started hour is charged at the rate it started with.
+  - **`box create` asks** about the Picker on a terminal when `--picker` was not
+    given, quoting the hourly surcharge from the cloud's own price list rather
+    than a number kept in the CLI. `--yes`, `--json` and a run with no terminal
+    answer no without asking.
+  - **`box status`** says whether the Picker is on.
+  - **`run_test` offers it once.** A project that has a box but grounds intents
+    nowhere remote gets `pickerSuggestion` (`{state: "no-picker", next, why}`)
+    after the first run that passes — exactly once per MCP server session, on
+    the same terms as `boxSuggestion`, and never both: with no box there is
+    nothing to put a Picker on.
+  - **A refusal for money reads as one.** A remote grounder answering
+    `grounder-budget-exhausted` (HTTP 402) means the account's estimated spend
+    for the month has reached its ceiling, not that the token went bad: nothing
+    is re-minted over it, and the CLI and MCP replies name both ways out — top
+    up the balance, or `box picker off` to stop the Picker and ground locally
+    again. No amount is quoted: the figure estimates a bill we do not issue.
+
+## [0.34.0] - 2026-09-07
+
+### Patch Changes
+
+- c6b91bb: From `init` to a paid box without copying a token: `login`, `box create`,
+  and the tokens that keep themselves fresh.
+
+  Three new commands sign this machine in to unotest cloud — the account
+  that rents boxes — and rent one:
+
+  - `login` runs the device flow (RFC 8628): it prints a link and a code,
+    opens the browser when there is one, and waits for the approval. The
+    key is kept in `~/.config/unotest/credentials.json` (mode 0600,
+    `XDG_CONFIG_HOME` honoured) and is never printed, not even with
+    `--json`. `UNOTEST_CLOUD_TOKEN` in the environment wins over the file,
+    which is how a CI job signs in. `logout` revokes the key on the server
+    when the cloud can be reached and removes it locally always; `whoami`
+    says who, where the key came from, and the balance (exit 77 when not
+    signed in).
+  - `box create [name] [--size s|m|l] [--topup <eur>]` creates a box named
+    after the project (its package name, as a slug), with the environments
+    the project runs locally (`unotest/.env` and every `unotest/.env.<name>`,
+    their `APP_BASE_URL` or the config's `baseUrl` as the target). When the
+    balance will not cover the first hour it prints a Stripe Checkout link,
+    opens it when it can, and waits for the payment. Then it waits for the
+    box, mints its cloud-signed push and read tokens, writes
+    `UNOTEST_BOX_URL` to `unotest/.env` and `UNOTEST_BOX_TOKEN` +
+    `UNOTEST_BOX_READ_TOKEN` to `unotest/.secrets` (through the same
+    structure-preserving writer the viewer's Variables panel uses, with
+    `.gitignore` guarded the way `init` guards it), pushes the suite —
+    retrying with backoff while a fresh box has no revocation list yet —
+    and prints the viewer's address. Exit codes for an agent driving it
+    without a terminal: 75 the payment was not confirmed in time (nothing
+    created, nothing charged), 76 the terms of service are not accepted
+    (a person must, in a browser), 77 not signed in. No prompt is ever
+    shown without a TTY.
+    `--picker` rents the box with the Picker; `UNOTEST_GROUNDER_MODE=remote`
+    and `UNOTEST_GROUNDER_REMOTE_URL` then go to `unotest/.env` and
+    `UNOTEST_GROUNDER_REMOTE_TOKEN` to `unotest/.secrets` — the names the MCP
+    server reads — so intents ground on the box with no further setup. A
+    box without the Picker leaves those keys alone. The last line of
+    `create` is the next step: the complete `bundle push --run --env …
+--collection …` when the project has exactly one environment and one
+    collection, the viewer's address plus the command with placeholders
+    otherwise.
+  - `box access [name]` re-mints the pair and rewrites the two files;
+    `box status` and `box destroy` (asks on a terminal, `--yes` elsewhere)
+    are thin wrappers. The name defaults to the box `UNOTEST_BOX_URL`
+    points at (`acme.box.unotest.com` → `acme`).
+
+  Cloud-signed box tokens live thirty days. When a box answers that one
+  has expired, `bundle push` and the `box …` read commands re-mint the
+  pair through the cloud and retry once, provided a cloud login is at
+  hand; without one they say to run `login && box access`. The box a
+  re-mint is for is the one the project points at, named from its address
+  or, when the address spells no name (a stand behind an IP), by the same
+  default `create` used — so a lab box re-mints like any other. A `--box`
+  naming somewhere else is said to be somewhere else rather than blamed on
+  a missing login. A box that has
+  not yet received its revocation list is told apart from a real refusal
+  and retried; a token the box calls revoked is never re-minted quietly.
+  `bundle push` now also reads the push token from `unotest/.secrets`,
+  where `box create` puts it (then `unotest/.env`, for suites set up by
+  hand), so nothing has to be exported after the setup.
+
+  The MCP server knows the state too. While the project points at no box,
+  `box_envs`, `box_runs`, `box_run` and the other box tools answer
+  `{state: "no-box", next, why}` instead of an error, and `run_test`
+  carries the same `boxSuggestion` exactly once per server — after the
+  first local run that passes — so an agent offers the box at the moment
+  it is worth something and never nags. The box tools re-mint an expired
+  cloud-signed read token the way the CLI does, through the composition
+  root, and `unotest/.secrets` is read on every call: a pair written by
+  `box create` while the server runs is used by the next call. On a
+  Picker box, `ground_element` (and intent locators) whose picker token
+  the grounder refuses re-mint it once through the cloud and hand the new
+  token to the running client; a refusal that cannot be mended answers
+  `{state: "picker-token-refused", next: "npx @unotest/web box access",
+why}`, and a grounder that has not read its revocation list yet answers
+  `{state: "retry-shortly", retryAfterSeconds}`. Box tokens are checked
+  before the network: cloud-signed ones by their whole shape (`unos_…`), a
+  push token in the read variable (and the reverse) is named as the wrong
+  kind, anything else as not a token.
+
+  A renewal the cloud itself refuses is its own answer, not the cloud's.
+  When a box or the grounder says a cloud-signed token is stale and the
+  `/access` call that would replace it is refused in turn — no such box,
+  the box not ready, too many live pairs, the cloud unreachable — every
+  surface says that the credentials could not be renewed and keeps the
+  cloud's refusal as the cause. The CLI prints one line and exits with the
+  code that refusal earns; the grounding tools answer
+  `{state: "picker-token-refused", next, why}` as before, so an intent is
+  never answered with a sentence about boxes.
+
+  `init` ends with one line saying how to run the suite on a box; the
+  "mint a read token in the guard" advice in the box commands' refusals
+  now points at `login` and `box access` instead. `UNOTEST_CLOUD_URL`
+  points the CLI at a stand or a fake cloud; nobody sets it otherwise.
+
+  `@unotest/protocol`: `replaceEnvVar` (an in-place value replacement the
+  new upsert builds on), `BOX_PUSH_TOKEN_PREFIX` / `BOX_SIGNED_TOKEN_PREFIX`
+  / `BOX_SIGNED_TOKEN`, and `UNOTEST_BOX_URL`, `UNOTEST_GROUNDER_MODE`,
+  `UNOTEST_GROUNDER_REMOTE_URL` listed among the runner-config keys so they
+  file under the Runner section of `unotest/.env`.
+
+  `@unotest/grounder-client`: `GrounderHttpClientOptions.token` may be a
+  function yielding the current bearer; `GrounderRemoteError` carries the
+  grounder's `retryAfterSeconds`, and the error codes gain
+  `revocation-list-unavailable`.
+
 ## [0.33.0] - 2026-09-06
 
 ## [0.32.0] - 2026-09-05

package/dist/index.d.ts

@@ -138,8 +138,20 @@ interface ResolveResponse extends GroundLines {
 }
 interface ErrorResponse {
     error: string;
-    /** Machine code for control flow. `no-index` → client must re-`/index`. */
-    code?: "no-index" | "unauthorized" | "bad-request" | "internal";
+    /** Machine code for control flow. `no-index` → client must re-`/index`;
+     *  `unauthorized` → the bearer was refused, whatever the reason (one
+     *  body for all of them, so nothing here is an oracle) — in remote
+     *  mode that is a cloud-signed picker token to re-mint;
+     *  `revocation-list-unavailable` → the server cannot judge any token
+     *  yet, retry after `retryAfterSeconds`;
+     *  `grounder-budget-exhausted` → the account's estimated spend for the
+     *  month has reached its ceiling. Answered with **402**, never 401: the
+     *  token is perfectly good, and re-minting it changes nothing. Carries no
+     *  amount and nothing about any other account — the number is not one we
+     *  own, and the customer would check it against their provider's bill. */
+    code?: "no-index" | "unauthorized" | "revocation-list-unavailable" | "grounder-budget-exhausted" | "bad-request" | "internal";
+    /** With `revocation-list-unavailable`: how long to wait. */
+    retryAfterSeconds?: number;
 }
 declare const ROUTES: {
     readonly index: "/index";
@@ -151,11 +163,17 @@ declare const ROUTES: {
 declare class GrounderRemoteError extends Error {
     readonly status: number;
     readonly code: ErrorResponse["code"] | undefined;
-    constructor(message: string, status: number, code: ErrorResponse["code"] | undefined);
+    /** Only with `revocation-list-unavailable`. */
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, status: number, code: ErrorResponse["code"] | undefined, 
+    /** Only with `revocation-list-unavailable`. */
+    retryAfterSeconds?: number | undefined);
 }
 interface GrounderHttpClientOptions {
     baseUrl: string;
-    token: string;
+    /** The bearer, or a function that yields the CURRENT one — for a
+     *  long-lived client whose token is re-minted while it runs. */
+    token: string | (() => string);
     /** Override the generated session id (tests). */
     sessionId?: string;
     /** Injected fetch (tests). Defaults to global fetch. */

package/dist/index.js

@@ -47,14 +47,16 @@ var ROUTES = {
 // src/http-client.ts
 import { randomUUID } from "crypto";
 var GrounderRemoteError = class extends Error {
-  constructor(message, status, code) {
+  constructor(message, status, code, retryAfterSeconds) {
     super(message);
     this.status = status;
     this.code = code;
+    this.retryAfterSeconds = retryAfterSeconds;
     this.name = "GrounderRemoteError";
   }
   status;
   code;
+  retryAfterSeconds;
 };
 var GrounderHttpClient = class {
   sessionId;
@@ -63,7 +65,7 @@ var GrounderHttpClient = class {
   fetchImpl;
   constructor(opts) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    this.token = opts.token;
+    this.token = typeof opts.token === "function" ? opts.token : () => opts.token;
     this.sessionId = opts.sessionId ?? randomUUID();
     this.fetchImpl = opts.fetchImpl ?? fetch;
   }
@@ -83,7 +85,7 @@ var GrounderHttpClient = class {
         method: "POST",
         headers: {
           "content-type": "application/json",
-          authorization: `Bearer ${this.token}`,
+          authorization: `Bearer ${this.token()}`,
           [SESSION_HEADER]: this.sessionId
         },
         body: JSON.stringify(body)
@@ -97,7 +99,12 @@ var GrounderHttpClient = class {
     }
     const json = await res.json().catch(() => ({}));
     if (!res.ok) {
-      throw new GrounderRemoteError(json.error ?? `${path} \u2192 ${res.status}`, res.status, json.code);
+      throw new GrounderRemoteError(
+        json.error ?? `${path} \u2192 ${res.status}`,
+        res.status,
+        json.code,
+        typeof json.retryAfterSeconds === "number" ? json.retryAfterSeconds : void 0
+      );
     }
     return json;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/grounder-client",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Client contract for the unotest semantic UI grounder: typed intent/resolution types, the injectable DOM walker (RawCapture), the content hash, and the HTTP client + wire protocol of the grounding service. The grounding engine itself is a private service; this package is everything a consumer needs to capture a page and talk to it.",
   "license": "MIT",
   "publishConfig": {