@reticlehq/server 2.7.0 → 2.9.0

package/docs/tools-act-and-wait.mdx

@@ -0,0 +1,173 @@
+---
+title: reticle_act_and_wait
+description: Act on an element and wait for a named consequence in one call. This is the tool that produces a verdict, and the one you should reach for by default.
+icon: circle-check
+---
+
+`reticle_act_and_wait` performs one action on an element and waits for a named consequence, returning a verdict in the same call. Reach for it whenever an action is supposed to cause something: it is one of only two Reticle tools that produce a verdict, the other being [`reticle_assert`](/tools-assert).
+
+This is the tool Reticle exists for. It does the act, observe and assert steps in one round trip, and it makes you name the expected consequence **before** the action runs.
+
+That ordering is not a convenience. An agent that acts first and then decides what counts as success will always find something that counts. Naming the consequence up front is the difference between a check and a rationalisation.
+
+## Example
+
+```json
+{
+  "ref": "e105",
+  "action": "click",
+  "until": { "kind": "net", "method": "POST" }
+}
+```
+
+Real response. The `initiatorStack`, `storageDiffs` and per-event trace detail are trimmed out for length; nothing else is changed:
+
+```json
+{
+  "verified": "yes",
+  "verifiedReason": "proved",
+  "because": "assertion held at presence grade over a clean capture with no channel disagreeing",
+  "effect": {
+    "ok": true,
+    "ref": "e105",
+    "action": "click",
+    "dispatched": true,
+    "settled": true,
+    "settleReason": null,
+    "testid": "login-submit",
+    "component": "Login",
+    "role": "button",
+    "name": "Sign in",
+    "effect": { "focusMoved": "e104->null", "domMutatedWithin": 8, "appeared": "Signing in…" },
+    "source": { "file": "src/components/Login.tsx", "line": 81, "column": 8 }
+  },
+  "verdict": {
+    "pass": true,
+    "evidence": {
+      "id": "n2",
+      "method": "POST",
+      "url": "http://localhost:8787/api/login",
+      "status": 200,
+      "ok": true,
+      "durationMs": 4,
+      "initiator": "fetch",
+      "statusText": "OK",
+      "contentType": "application/json; charset=utf-8",
+      "responseSize": 67,
+      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
+      "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}"
+    }
+  },
+  "trace": {
+    "window_ms": 31,
+    "summary": {
+      "total": 21,
+      "network": 1,
+      "domAdded": 0,
+      "domRemoved": 1,
+      "domChanged": 6,
+      "routeChanges": 0,
+      "consoleErrors": 0,
+      "animations": 0,
+      "signals": 1
+    }
+  },
+  "summary": {
+    "net": { "total": 1, "errors": 0 },
+    "consoleErrors": 0,
+    "statePathsChanged": ["app"],
+    "storageKeysChanged": ["reticle.bench.authToken", "reticle.bench.sessionId"],
+    "stateDiffs": [
+      { "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}", "atMs": 44403 }
+    ],
+    "signals": ["auth:granted"],
+    "layoutShift": 0.016486682891845704,
+    "longTasks": 0
+  },
+  "honesty": {
+    "grade": "presence",
+    "attribution": "window",
+    "coverage": { "pct": 100, "partial": false },
+    "integrity": { "clean": true, "issues": [] }
+  },
+  "since": 44395
+}
+```
+
+`trace` is a digest of what the app did in the window. When the counts are not enough, pass the top-level `since` cursor to [`reticle_observe`](/tools-observe) for the per-event timeline.
+
+## The predicate grammar
+
+`until` takes `{ kind, ...fields }`. The kinds:
+
+| Kind                      | Asserts                                                        |
+| ------------------------- | -------------------------------------------------------------- |
+| `signal`                  | The app fired a named signal, the strongest evidence available |
+| `state`                   | A store path reached a value                                   |
+| `net`                     | A request matched; `count` asserts an **exact** number         |
+| `route`                   | The route **changed**                                          |
+| `element`                 | An element appeared; `absent: true` asserts it went away       |
+| `text`                    | Text appeared or, with `absent`, disappeared                   |
+| `console`                 | Something logged; `absent: true` asserts a clean console       |
+| `animation`               | An animation ran or finished                                   |
+| `settled`                 | The page went quiet                                            |
+| `allOf` / `anyOf` / `not` | Combine the above                                              |
+
+### Predicates that catch real bugs
+
+```json
+{ "until": { "kind": "net", "method": "POST", "count": 1 } }
+```
+
+Exactly one request. Double-submit fails this at two, and no screenshot will ever tell you.
+
+```json
+{ "until": { "kind": "console", "absent": true } }
+```
+
+The action completed **and** logged nothing. "It worked but threw a warning" stops passing.
+
+```json
+{ "until": { "kind": "signal", "name": "deploy:created" } }
+```
+
+The app itself declared success. This is the highest grade of evidence, and it requires [instrumenting your app](/instrumentation). Which is the main reason to bother.
+
+## Reading `verified`
+
+<CardGroup cols={3}>
+  <Card title="yes" icon="circle-check">
+    The named consequence happened, with evidence attached.
+  </Card>
+  <Card title="no" icon="circle-xmark">
+    It did not. A finding, with a source pointer.
+  </Card>
+  <Card title="unknown" icon="circle-question">
+    Reticle could not tell. **Not a pass.** Report it as unknown.
+  </Card>
+</CardGroup>
+
+## The `honesty` block
+
+`grade` is how strong the evidence was. A fired signal outranks an element appearing. `coverage.partial: true` means Reticle did not observe the whole window. `integrity.clean: false` means something interfered with the capture and the verdict deserves less trust.
+
+A verification tool that cannot describe the quality of its own evidence is asking you to take its word for it, which is precisely the problem we started with.
+
+## Arguments
+
+| Argument | What it does |
+| --- | --- |
+| `ref`, `action`, `args` | As [`reticle_act`](/tools-act) |
+| `until` | The predicate to wait for. Omit it to wait for the page to settle |
+| `predicate` | Alias for `until`, the name `assert` and `wait_for` use |
+| `timeout_ms` | Maximum wait, defaulting to 4000. `0` evaluates the predicate once, no wait |
+| `refuseWhenThrottled` | Throw rather than act on a throttled tab |
+
+Omitting `until` waits for network and DOM idle, which is the deterministic replacement for a fixed sleep. To assert a consequence **and** settle, combine them:
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [{ "kind": "signal", "name": "deploy:created" }, { "kind": "settled" }]
+}
+```

package/docs/tools-act-sequence.mdx

@@ -0,0 +1,137 @@
+---
+title: reticle_act_sequence
+description: Run several actions in order in one round trip. Fill, fill, submit. Instead of paying a full turn for each step.
+icon: layer-group
+---
+
+`reticle_act_sequence` runs several actions in order in a single round trip. Reach for it whenever a journey needs more than one step, such as fill, fill, submit, and then prove the outcome once with [`reticle_act_and_wait`](/tools-act-and-wait), because a sequence itself produces no verdict.
+
+A login is three actions. Driving it one call at a time costs three round trips and three turns of context. `reticle_act_sequence` does it in one.
+
+This tool exists because of a measured problem: agents were driving forms one call at a time, over and over. Those repeats were not retries. The calls succeeded and got repeated, because the batching tool was not advertised and so nobody knew it was there.
+
+## Example
+
+```json
+{
+  "steps": [
+    { "ref": "e603", "action": "fill", "args": { "value": "admin@reticle.dev" } },
+    { "ref": "e604", "action": "fill", "args": { "value": "correct-horse-battery-staple" } },
+    { "ref": "e605", "action": "click" }
+  ]
+}
+```
+
+Real response. Each `effects[]` entry also carries `targetMatched`, `visible`, `enabled`, `defaultPrevented`, `occluded`, `occludedBy` and `scrolledIntoView`, and each `steps[]` entry also carries `dispatched`, `settled`, `settleReason`, `component`, `role` and `name`. Those are trimmed here for length:
+
+```json
+{
+  "since": 3915,
+  "dispatched": true,
+  "result": {
+    "ok": true,
+    "count": 3,
+    "effects": [
+      {
+        "dispatched": true,
+        "focusMoved": "null->e603",
+        "valueChanged": false,
+        "domMutatedWithin": 0
+      },
+      {
+        "dispatched": true,
+        "focusMoved": "e603->e604",
+        "valueChanged": true,
+        "domMutatedWithin": 9
+      },
+      {
+        "dispatched": true,
+        "focusMoved": "e604->null",
+        "domMutatedWithin": 15,
+        "appeared": "Signing in… | Invalid email or password | Sign in"
+      }
+    ],
+    "steps": [
+      {
+        "ref": "e603",
+        "action": "fill",
+        "testid": "login-email",
+        "source": { "file": "src/components/Login.tsx", "line": 48 }
+      },
+      {
+        "ref": "e604",
+        "action": "fill",
+        "testid": "login-password",
+        "source": { "file": "src/components/Login.tsx", "line": 59 }
+      },
+      {
+        "ref": "e605",
+        "action": "click",
+        "testid": "login-submit",
+        "source": { "file": "src/components/Login.tsx", "line": 81 }
+      }
+    ]
+  }
+}
+```
+
+## Read that response again
+
+`ok: true`. `count: 3`. Every step dispatched. And the login **failed**, look at `appeared`:
+
+```
+"appeared": "Signing in… | Invalid email or password | Sign in"
+```
+
+That password was wrong. The app rejected it. And this tool still reported `ok: true`, correctly, because `ok` means _the three actions were dispatched_, which they were.
+
+<Warning>
+  This is the whole reason `act` and `act_sequence` do not produce verdicts. `ok: true` is a
+  statement about the input, not about the outcome. Follow a sequence with
+  [`reticle_act_and_wait`](/tools-act-and-wait) on the final step, or with an
+  [`reticle_assert`](/tools-assert), or you have proved nothing.
+</Warning>
+
+The honest pattern is: batch the setup, prove the outcome.
+
+```json
+{
+  "steps": [
+    { "ref": "e603", "action": "fill", "args": { "value": "admin@reticle.dev" } },
+    { "ref": "e604", "action": "fill", "args": { "value": "correct-password" } }
+  ]
+}
+```
+
+then
+
+```json
+{ "ref": "e605", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
+```
+
+which returns the verdict the sequence could not:
+
+```json
+{
+  "verified": "yes",
+  "verifiedReason": "proved",
+  "because": "assertion held at signal grade over a clean capture with no channel disagreeing",
+  "verdict": {
+    "pass": true,
+    "evidence": { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } }
+  },
+  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
+}
+```
+
+Two calls instead of four, and the last one returns a verdict. Note `grade: "signal"`, the strongest Reticle awards, because the app said so itself.
+
+## What each step reports
+
+Every step comes back with the same `effect` fields as [`reticle_act`](/tools-act): `valueChanged`, `focusMoved`, `domMutatedWithin`, `occluded`. Plus its `testid`, `component` and `source`. When a sequence goes wrong, that per-step detail tells you which step, and which line of which file.
+
+<Note>
+  Steps run in order and do not stop on a soft failure, because "the field rejected the value" is
+  not an exception. It's a result you need to see. Read `effects[]` rather than assuming `ok: true`
+  means all three did what you wanted.
+</Note>

package/docs/tools-act.mdx

@@ -0,0 +1,95 @@
+---
+title: reticle_act
+description: Perform an action without checking the result. Useful for setup steps, and dangerous as a final step, because ok means dispatched, not worked.
+icon: hand-pointer
+---
+
+`reticle_act` clicks, fills, types, selects, drags. It does exactly one thing and makes exactly one promise: the event was dispatched.
+
+<Warning>
+  `reticle_act` **proves nothing**. If the action is supposed to cause something, use
+  [`reticle_act_and_wait`](/tools-act-and-wait) and get the verdict in the same call. A drive that
+  ends on `reticle_act` has no result.
+</Warning>
+
+## Example
+
+```json
+{ "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
+```
+
+Real response:
+
+```json
+{
+  "since": 27544,
+  "inputMode": "synthetic",
+  "inputModeReason": "not-a-pointer-action",
+  "dispatched": true,
+  "settled": true,
+  "settleReason": null,
+  "result": {
+    "ok": true,
+    "ref": "e104",
+    "action": "fill",
+    "dispatched": true,
+    "settled": true,
+    "settleReason": null,
+    "testid": "login-password",
+    "component": "Login",
+    "role": "textbox",
+    "name": "Password",
+    "effect": {
+      "focusMoved": "null->e104",
+      "valueChanged": true,
+      "domMutatedWithin": 9
+    },
+    "source": { "file": "src/components/Login.tsx", "line": 59, "column": 8 }
+  }
+}
+```
+
+<Note>
+  The `effect` block only lists what is worth knowing. Fields sitting at their uninformative default
+  are **omitted**, so a clean action collapses to its consequence. An absent `dispatched`,
+  `targetMatched`, `visible` or `enabled` means `true`; an absent `occluded`, `scrolledIntoView`,
+  `valueChanged` or `defaultPrevented` means `false`; an absent `focusMoved` or `occludedBy` means
+  `null`. Do not read a missing field as a failure.
+</Note>
+
+## Actions
+
+`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag` · `webmcp`
+
+| Action           | Arguments                                                       |
+| ---------------- | --------------------------------------------------------------- |
+| `fill`, `select` | `{ value }`                                                     |
+| `type`, `press`  | `{ text }`. For `press`, the key _name_, e.g. `Escape` or `Tab` |
+| `drag`           | `{ toRef }`. The ref to drop onto                               |
+| `upload`         | file arguments                                                  |
+
+## Reading the effect block
+
+This is where `act` earns its place even though it proves nothing.
+
+- **`valueChanged: true`**. The field actually took the value. `false` on a `fill` usually means the input is controlled and rejected it, or it's readonly.
+- **`focusMoved: "null->e104"`**, focus went where you expected.
+- **`domMutatedWithin: 9`**, something re-rendered within 9ms. A `fill` that mutates nothing often means no handler is attached.
+- **`defaultPrevented`**. A handler called `preventDefault()`, which is why your form didn't submit.
+- **`occluded` / `occludedBy`**. The click landed on something else. This is the answer to at least half of all "the button doesn't work" reports.
+
+## `settled: false` is not a failure
+
+`settled: true` with `settleReason: null`, as above, means a real frame flushed before Reticle stopped watching. `settled: false` with `settleReason: "timeout"` means the page was still busy. On a `fill` that's normal and uninteresting. On a click you expected to complete something, it's a hint that you wanted `act_and_wait` with an explicit `until`. A settle timeout never fails the tool.
+
+## `inputMode` tells you how real the input was
+
+`synthetic` means Reticle dispatched events programmatically. `real` means native CDP input, available under `reticle drive`. Synthetic input is fine for the overwhelming majority of apps; a few drag-and-drop and pointer-gesture libraries only respond to the real thing.
+
+`inputModeReason` explains any choice Reticle made on your behalf, so it is never silent. `not-a-pointer-action` above means a `fill` has no pointer path to take, not that real input was unavailable. Clicks default to the occlusion-honest synthetic path even when CDP is configured; pass `args.native: true` to force a trusted native click for file pickers and clipboard access.
+
+<Warning>
+  When the tab is backgrounded, synthetic timers and pointer gestures can silently no-op. Every
+  response carries a `warning` when the tab is throttled. Pass `refuseWhenThrottled: true` to make
+  Reticle throw instead of pretending it acted.
+</Warning>

package/docs/tools-assert.mdx

@@ -0,0 +1,129 @@
+---
+title: reticle_assert
+description: Evaluate a predicate against what the app actually did, and get a verdict. Including a clear explanation when it fails.
+icon: gavel
+---
+
+`reticle_assert` evaluates a predicate against what the app actually did and returns a verdict: `verified` plus `pass`, evidence when it holds, and `expected` versus `observed` when it does not. Reach for it when you want a verdict on something you did not just cause, or on several actions at once.
+
+It is the second of the two tools that produce a verdict, the other being [`reticle_act_and_wait`](/tools-act-and-wait). It takes the same predicate grammar and evaluates it against what already happened.
+
+## A real failure
+
+Failures are more instructive than passes, so here is one. I asserted a route change to `/` on a page that was already at `/`:
+
+```json
+{ "predicate": { "kind": "route", "pathname": "/" } }
+```
+
+```json
+{
+  "verified": "no",
+  "verifiedReason": "assertion_failed",
+  "because": "the declared consequence did not hold",
+  "pass": false,
+  "failureReason": "no route change observed",
+  "observed": "no route change in the window",
+  "expected": "a route change to /",
+  "assertion": "route.changed",
+  "source": "src/components/Login.tsx:81",
+  "buffer": {
+    "held": 536,
+    "dropped": 11,
+    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
+  }
+}
+```
+
+<Note>
+  The route predicate's field is `pathname`. `path` is accepted as an alias and rewritten, but
+  `pathname` is what the published schema declares, so it is the one to write.
+</Note>
+
+<Warning>
+  Read `assertion: "route.changed"` carefully. The `route` predicate asserts that the route
+  **changed**, not that it currently equals a value. Asserting the route you are already on will
+  always fail. This catches people out, and the response says so in `expected` rather than leaving
+  you to work it out.
+</Warning>
+
+Note also `expected` and `observed` side by side. A verdict that says only "failed" makes you go digging; this one tells you what it wanted, what it saw, and where in your source the relevant element lives.
+
+## A failure that names the real value
+
+The same shape on a store read, which is the strongest kind of failure you can get, because it quotes the app's own data back at you:
+
+```json
+{
+  "predicate": { "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
+}
+```
+
+```json
+{
+  "verified": "no",
+  "verifiedReason": "assertion_failed",
+  "because": "the declared consequence did not hold",
+  "pass": false,
+  "failureReason": "state 'deployments.0.status' is \"queued\", expected \"live\"",
+  "observed": "deployments.0.status = \"queued\"",
+  "expected": "deployments.0.status = \"live\"",
+  "assertion": "state.equals",
+  "evidence": { "store": "app", "path": "deployments.0.status", "value": "queued" },
+  "source": "src/components/Login.tsx:81"
+}
+```
+
+## A pass can still come with a warning
+
+A presence-only predicate passes and tells you not to trust it much:
+
+```json
+{
+  "verified": "yes",
+  "pass": true,
+  "evidence": [
+    {
+      "ref": "e606",
+      "role": "alert",
+      "name": "Invalid email or password",
+      "visible": true,
+      "source": "src/components/Login.tsx:72",
+      "states": ["present", "visible", "enabled"]
+    }
+  ],
+  "advice": "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked."
+}
+```
+
+## Arguments
+
+| Argument                 | What it does                                                      |
+| ------------------------ | ----------------------------------------------------------------- |
+| `predicate` (or `until`) | `{ kind, ...fields }`. See the [predicate reference](/predicates) |
+| `timeout_ms`             | If above zero, wait this long before failing. Default `0`         |
+| `since`                  | Cursor from a prior act. Scope to events after that action        |
+
+## Scope it with `since`
+
+By default an assertion already counts only events since your last act, so a signal buffered before the action cannot fake a pass. Pass `since` when you want to set that window explicitly: to scope to one particular earlier action, or to widen it deliberately across several.
+
+```json
+{ "predicate": { "kind": "net", "method": "POST" }, "since": 44395 }
+```
+
+The cursor comes from the preceding `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause.
+
+## When to use assert over act_and_wait
+
+Use [`reticle_act_and_wait`](/tools-act-and-wait) when you are performing the action. Use `reticle_assert` when:
+
+- you are checking a precondition before acting;
+- the state was reached by several actions and you want one verdict over the lot;
+- you want to assert something extra about an action you already ran, using its `since` cursor.
+
+<Note>
+  `verified: "unknown"` means Reticle could not tell. It is not a pass, and it is not a failure, it
+  is a statement that the evidence was insufficient. Report it as unknown rather than rounding it in
+  either direction.
+</Note>

package/docs/tools-console.mdx

@@ -0,0 +1,63 @@
+---
+title: reticle_console
+description: The console log, filtered by level, and an empty result that tells you it is a real reading rather than a missing one.
+icon: terminal
+---
+
+`reticle_console` returns the app's console log, filtered by level, and tells you whether an empty result is a real reading or a missing one. Reach for it as the fast triage read after something goes wrong, and assert `{ "kind": "console", "absent": true }` when you want a clean console to be part of the pass.
+
+```json
+{ "limit": 3 }
+```
+
+Real response from a page with a clean console:
+
+```json
+{
+  "logs": [],
+  "buffer": {
+    "held": 535,
+    "dropped": 10,
+    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
+  },
+  "observed": true,
+  "note": "no console lines; the observation ran and found none, which is a result, not a missing reading",
+  "cost": { "bytes": 338, "tokens": 85 }
+}
+```
+
+## The empty result is the interesting one
+
+An empty array is ambiguous in almost every tool that returns one. Did nothing happen, or did the observation not run? Reticle answers both:
+
+- **`observed: true`** with that `note`. The observation ran and genuinely found nothing. You may treat a clean console as a fact.
+- **`buffer.dropped: 10`**, older events were evicted. If you are asking about something from a while ago, the honest answer is "not in what I still have", not "it didn't happen".
+
+Read both fields together. `observed: true` with a non-zero `dropped` count means _recently_ clean, which is usually what you wanted but is not the same as _always_ clean.
+
+## Arguments
+
+| Argument          | What it does                                         |
+| ----------------- | ---------------------------------------------------- |
+| `level`           | `log` · `warn` · `error` · `info`                    |
+| `limit`           | Most recent N. Older matches are dropped and counted |
+| `actionId`        | Only lines attributed to one action                  |
+| `since` / `until` | Cursors from a prior act                             |
+
+## The check worth making by default
+
+Plenty of features "work" while quietly throwing. Assert the clean console as part of the action rather than checking afterwards:
+
+```json
+{ "ref": "e605", "action": "click", "until": { "kind": "console", "absent": true } }
+```
+
+That fails if the click succeeds _and_ logs an error, which is exactly the case a human reviewer tends to wave through.
+
+<Tip>
+  `level: "error"` is the fast triage read. If it comes back empty with `observed: true`, stop
+  looking at the console and go look at [`reticle_network`](/tools-network) or
+  [`reticle_state`](/tools-state) instead. That is a real capture from this fixture:
+  `{"logs":[],"observed":true,"cost":{"bytes":337,"tokens":85}}`, eighty-five tokens to rule out a
+  whole class of bug.
+</Tip>