@reticlehq/server 2.7.0 → 2.9.0

package/docs/tools-tools-and-run.mdx

@@ -0,0 +1,156 @@
+---
+title: reticle_tools and reticle_run
+description: Discover the tools that are not advertised, load their argument grammar on demand, and invoke any of them by name.
+icon: boxes-stacked
+---
+
+`reticle_tools` lists every Reticle tool and, on request, returns the full argument grammar for the ones you name. `reticle_run` then invokes any of them. Reach for the pair whenever you need a capability that is not in the default advertised surface, which is most of what Reticle can do.
+
+Reticle ships 46 tools plus these two meta-tools. On the default profile your agent is shown 17 of them plus the meta pair, so 29 sit in the cold tail. These two are how it reaches those 29 without paying for their schemas on every turn.
+
+`reticle_tools` discovers. `reticle_run` invokes. Together they cost two tool definitions instead of twenty-nine.
+
+## Discovering what exists
+
+```json
+{}
+```
+
+Returns every tool with a one-line summary. A sample of what lives in the cold tail:
+
+| Tool                    | What it does                                                           |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `reticle_capabilities`  | The app's advertised testable surface, testids, signals, stores, flows |
+| `reticle_flow_verify`   | Replay every saved flow, return one consolidated suite verdict         |
+| `reticle_screenshot`    | Pixel screenshot of the driven page, saved as a visual baseline        |
+| `reticle_visual_diff`   | Perceptually diff the live page against that baseline                  |
+| `reticle_network_mock`  | Force a 500, go offline, or delay a response                           |
+| `reticle_viewport`      | Pin the viewport so screenshots are reproducible across machines       |
+| `reticle_crawl`         | Click every reachable control and report anomalies, with no script     |
+| `reticle_clock`         | Freeze time or fast-forward timers, toasts, debounces, auto-dismiss    |
+| `reticle_storage`       | localStorage, sessionStorage and readable cookies                      |
+| `reticle_coverage`      | Which controls you have driven this session, and which you have not    |
+| `reticle_verify_change` | Give it the files you edited; it replays the flows that cover them     |
+| `reticle_reconcile`     | Compare what the API returned against what the page actually renders   |
+| `reticle_scroll_to`     | Find a row in a virtualised list that has not rendered yet             |
+
+The response also tells you which surface is active:
+
+```json
+{
+  "profile": {
+    "active": "all",
+    "source": "RETICLE_ADVERTISE_ALL_TOOLS set in the DAEMON's environment at startup",
+    "note": "The profile is read once at daemon startup: change RETICLE_TOOL_PROFILE and restart the daemon, or it has no effect. Under this profile every unadvertised tool is reachable through reticle_run; under `full` there are no meta-tools because every tool is advertised directly."
+  },
+  "next": "Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }."
+}
+```
+
+That capture is from a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1`. On a default daemon, `active` reads `default` and names the environment variable as unset.
+
+<Warning>
+  "Read once at daemon startup" is doing real work in that sentence. Setting the environment
+  variable in a shell where a daemon is already running changes nothing, and the resulting "I set it
+  and nothing happened" is very hard to debug from the outside.
+</Warning>
+
+## Loading argument grammar
+
+Summaries are enough to choose a tool, not to call one. Load the full parameters for the ones you want:
+
+```json
+{ "names": ["reticle_network_mock", "reticle_clock"] }
+```
+
+Each named tool comes back with its full description and a `params` array of `{ name, required, description }`. This is the point of the design. Schemas arrive when they are needed, rather than on every turn forever.
+
+<Warning>
+  Do this rather than guessing. `reticle_run` refuses an unknown parameter instead of running the
+  call, and hands you the real parameter list so the retry is one turn rather than three:
+
+```json
+{
+  "error": "unknown parameter for reticle_flow_save: name",
+  "tool": "reticle_flow_save",
+  "params": [
+    { "name": "flow", "required": false, "description": "Alias for `flowName`." },
+    { "name": "flowName", "required": true, "description": "Name for the flow file." }
+  ],
+  "hint": "fix the arguments and call reticle_run again"
+}
+```
+
+The full `error` string continues: _"NOT applied, so any result would be an answer to a different question."_
+
+</Warning>
+
+## Invoking
+
+```json
+{ "tool": "reticle_capabilities" }
+```
+
+Real response from an instrumented app, trimmed:
+
+```json
+{
+  "testids": [
+    "nav-overview",
+    "nav-deployments",
+    "login-email",
+    "login-password",
+    "login-submit",
+    "deploy-table",
+    "new-deploy",
+    "deploy-submit",
+    "…"
+  ],
+  "signals": [
+    "nav:changed",
+    "auth:granted",
+    "auth:denied",
+    "deploy:created",
+    "deploy:shipped",
+    "modal:opened",
+    "toast:shown",
+    "…"
+  ],
+  "stores": ["app"],
+  "flows": [
+    {
+      "name": "ship-a-deploy",
+      "steps": ["nav-deployments", "new-deploy", "deploy-name", "deploy-submit"]
+    },
+    { "name": "generate-a-script", "steps": ["nav-compose", "compose-prompt", "compose-generate"] },
+    { "name": "find-old-deploy", "steps": ["nav-deployments", "scroll-to row-3600"] }
+  ],
+  "source": "live"
+}
+```
+
+The full response on this fixture carries 49 testids and 16 signals. `source: "live"` means it was read from the running app; pass `{ "fromDisk": true }` to read the git-checked `.reticle/contract.json` instead, which works with no browser attached at all.
+
+## Start here, not with a snapshot
+
+That `reticle_capabilities` output is the single best first call on an unfamiliar app. It is the app telling you what it considers testable: the elements worth driving, the signals that mean success, and the flows somebody already thought were important.
+
+Compared with snapshotting the page and guessing from element names, it is both cheaper and more truthful. `auth:granted` is what the app means by "logged in", and no amount of looking at the DOM will tell you that.
+
+```json
+{
+  "tool": "reticle_network_mock",
+  "args": { "mocks": [{ "urlContains": "/api/deploys", "status": 500 }] }
+}
+```
+
+```json
+{ "applied": true, "count": 1 }
+```
+
+Then drive the flow and see whether your error state actually works. Most do not, which is the point. `{ "clear": true }` turns it off and answers `{ "applied": true, "count": 0 }`.
+
+<Note>
+  `reticle_run` returns whatever the invoked tool returns, unchanged. It is a transport, not a
+  wrapper. So a tool that produces a verdict still produces one through `run`.
+</Note>

package/docs/tools-wait-for.mdx

@@ -0,0 +1,85 @@
+---
+title: reticle_wait_for
+description: Block until a predicate holds. Or return immediately if it is already true in the recent buffer.
+icon: hourglass
+---
+
+`reticle_wait_for` blocks until a predicate holds, or returns straight away if it is already satisfied in the recent event buffer. Reach for it when you are waiting on something you did not cause. It reads and waits; it does not produce a verdict, so finish with [`reticle_assert`](/tools-assert).
+
+It takes the same predicate grammar as [`reticle_act_and_wait`](/tools-act-and-wait), without the action. Use it when the thing you are waiting for was triggered by something other than your own click. A timer, a websocket push, a background refresh.
+
+## Example
+
+```json
+{
+  "predicate": { "kind": "text", "contains": "Invalid email or password" },
+  "timeout_ms": 3000
+}
+```
+
+Real response:
+
+```json
+{
+  "pass": true,
+  "evidence": [
+    {
+      "ref": "e606",
+      "role": "alert",
+      "name": "Invalid email or password",
+      "visible": true,
+      "source": "src/components/Login.tsx:72",
+      "states": ["present", "visible", "enabled"]
+    }
+  ]
+}
+```
+
+The evidence is the element itself, with the file and line that rendered it.
+
+<Note>
+  A `text` predicate matches **presence** by default, so an element that is in the DOM but hidden
+  satisfies it and comes back with `visible: false` and `states: ["present", "hidden", "enabled"]`.
+  If you need it on screen, say so: `{ "kind": "text", "contains": "…", "visible": true }`.
+</Note>
+
+The field is `contains`. `value` and `text` are accepted as aliases and rewritten to it, but `contains` is what the published schema declares.
+
+## It checks the buffer first
+
+`wait_for` does not always wait. If the predicate is already satisfied in the recent event buffer, it returns immediately. This means you can act, then wait, without racing. The event that happened while you were composing the second call is not lost.
+
+## Arguments
+
+| Argument                 | What it does                                                      |
+| ------------------------ | ----------------------------------------------------------------- |
+| `predicate` (or `until`) | `{ kind, ...fields }`, see the [predicate reference](/predicates) |
+| `timeout_ms`             | Maximum wait. Default 4000                                        |
+| `since`                  | Cursor from a prior act, to widen or narrow the window explicitly |
+
+By default the wait only counts events since your last act, so a signal that fired before the action cannot satisfy it. A miss returns a near-miss diagnosis rather than a bare `false`:
+
+```json
+{
+  "pass": false,
+  "failureReason": "no element matched {\"text\":\"Deployments\"}",
+  "observed": "no matching element on the page",
+  "expected": "an element matching {\"text\":\"Deployments\"}",
+  "assertion": "element.present",
+  "evidence": { "presentTestids": ["login-email", "login-password", "login-submit"] }
+}
+```
+
+`presentTestids` there is the answer to the real question. The text was missing because the app had logged out, not because the render was slow.
+
+## Prefer `act_and_wait` when you caused it
+
+If your own action is supposed to trigger the thing, put the predicate in the action:
+
+```json
+{ "ref": "e605", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
+```
+
+One call instead of two, no gap for an event to slip through, and, the part that actually matters, the expectation is recorded _before_ the action rather than chosen after it.
+
+Save `wait_for` for consequences you did not cause.

package/docs/troubleshooting.mdx

@@ -0,0 +1,263 @@
+---
+title: 'Troubleshooting: it worked on my tab'
+sidebarTitle: Troubleshooting
+description: Nothing connected, the click did nothing, the verdict says unknown. The failures people actually hit, and the diagnostic for each.
+icon: stethoscope
+---
+
+**Run `npx @reticlehq/server doctor` first.** It checks Chromium, the daemon, the port and the connected sessions in one command, and it names the problem in most cases. If `sessions` reads zero, your app is not reaching the bridge, and a port mismatch is the usual reason.
+
+Reticle is a verification layer that runs a dev-only SDK inside your running web app. Two halves have to be working: your agent needs the MCP server registered, and your app needs the SDK connected to the local daemon. Almost every failure below is one of those two halves being absent.
+
+Most of these were hit while writing these docs. The diagnostics quoted are real output.
+
+## Start here
+
+```bash
+npx @reticlehq/server doctor
+```
+
+```
+reticle doctor
+  node         v22.14.0
+  chromium     ✓ installed
+  daemon       ✓ running on :4400 (pid 24735, v<the version you have>)
+  sessions     ✓ 1 page connected
+  bridge port  4400  (your app must dial THIS port, not your dev-server port)
+  daemon log   /Users/you/.reticle/daemon-4400.log
+  tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
+```
+
+One command, the whole setup. If this is clean and things still fail, the problem is in the app rather than the wiring.
+
+The `sessions` line is the one to read first. Zero connected pages is a failing check, not a footnote, because it is the state a setup most often stalls in: everything installed, the daemon up, and nothing having dialled in. When it is zero, `doctor` prints the same diagnosis described below underneath the checklist, so you do not have to call a tool to see it.
+
+## "No browser session connected"
+
+By far the most common. Reticle's own diagnostic is unusually good here. It tells you whether the wiring was ever correct:
+
+```json
+{
+  "sessionCount": 0,
+  "why": "no browser session connected, but one WAS connected to this daemon earlier, so the wiring is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen the app (or run `reticle open`), or reload the tab. You do not have to wait for the human: reticle_lease {action:\"acquire\", url} opens a browser Reticle drives itself, and returns a sessionId you can use immediately (reach it with reticle_run {tool:\"reticle_lease\"} if it is not advertised directly; release it when you finish). Then call reticle_sessions again."
+}
+```
+
+Read the `why`. If it says one **was** connected earlier, stop debugging your config and just reopen the tab. If it says nothing ever connected, the wiring itself is wrong, so work through the list below.
+
+If nothing ever connected:
+
+- Is the app running, and open in a browser? If nothing is serving it, see [Who starts the dev server](#who-starts-the-dev-server): this is the agent's job, not a question to put to you.
+- Is `reticle.connect()` actually executing? Check the dev guard is true.
+- **Port mismatch.** This is the big one.
+
+### Who starts the dev server
+
+**The agent does.** If no dev server is listening, the agent reads your project's own dev script out of `package.json`, runs it in the background, tells you in one line that it is running and how to stop it, and carries on. It used to be told the opposite, "Reticle never starts the dev server for you, that's your job", and agents obeyed it exactly: they read the rule, declined to start anything, and ended the turn with nothing verified.
+
+The daemon still does not do it, on purpose. A build process started by a long-lived background daemon is invisible to whoever's machine it is running on, was never consented to, cannot easily be stopped, and orphans when the daemon exits. It would also mean a piece of standing infrastructure runs arbitrary `package.json` scripts. An agent already has shell access in your repo, already runs install and build commands, and runs inside a host that asks you before it does. A dev server the agent starts is in the transcript, attributable to a step you approved, and stoppable.
+
+The agent does not have to work out the command. When `reticle_sessions` comes back with nothing connected, it carries a `next_action` naming which of four cases this is and, where one applies, the literal command and port: start the dev server, run `reticle init`, open the app, or reopen a tab that went away. The command is read from this project's own scripts, so a project with no recognisable dev script gets no command rather than a guess.
+
+The guards, which apply wherever this instruction appears:
+
+1. **Never start a second one.** If something is already listening on the app's port, it is adopted.
+2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, the agent says so and stops rather than inventing one.
+3. **Never kill anything**: not a dev server, not a daemon, not a port holder, including one it started.
+4. **Background it, and say so.** You must know a server is running and how to stop it. A dev server you do not know about is the same failure one step later.
+5. **The permission prompt is your agent host's.** Nothing in Reticle bypasses or auto-approves it, and you can always decline.
+
+The corollary matters as much: if a dev server IS already running and nothing connects, the cause is the SDK not loading in the page. An agent that answers this state by asking you to start a server you are already running has ended the conversation with nothing fixed. Work the checklist above instead.
+
+### The port mismatch
+
+Your app dials a port; the daemon listens on one. When they disagree, the app runs perfectly and silently never connects. The browser console says so:
+
+```
+[Reticle] this page could not open a websocket to ws://localhost:4460/reticle. 3 attempts, all
+failed. That is everything the page can see: from inside the browser it cannot tell a daemon that
+is not there from one it is not allowed to reach, so this is not evidence about the daemon. What
+answers it: run `npx @reticlehq/server status` to see whether one is listening and on which port.
+If your app runs in a container, devcontainer or WSL, the daemon is on a different host, so set
+the URL explicitly (Vite: VITE_RETICLE_WS_URL, or reticle.connect({ url })). An https page cannot
+open a ws:// socket at all. Still retrying…
+```
+
+That message names the exact address it tried. Compare its port with `bridge port` from `doctor` and set whichever is wrong:
+
+```bash
+VITE_RETICLE_WS_URL=ws://localhost:4400/reticle pnpm dev
+```
+
+<Warning>
+  The bridge port is **not** your dev-server port. A dev server on 4312 and a daemon on 4400 is
+  normal and correct.
+</Warning>
+
+## The click did nothing
+
+Check whether the tab is throttled. Every response tells you:
+
+```json
+"warning": "tab throttled; timer/rAF/pointer gestures may silently no-op; refocus before driving"
+```
+
+A backgrounded browser tab has its timers suppressed. Synthetic pointer gestures and timers can silently no-op, so an action reports success and nothing happens.
+
+Three fixes, in order of preference:
+
+1. **Drive a lease**. A context Reticle owns, never backgrounded:
+
+   ```json
+   { "tool": "reticle_lease", "args": { "action": "acquire", "url": "http://localhost:4312/" } }
+   ```
+
+   Release it when you finish: `{ "action": "release", "sessionId": "lease-…" }`.
+
+2. **Focus the tab.**
+3. **Fail loudly** instead of pretending. Pass `refuseWhenThrottled: true` to your action.
+
+If the tab is fine, check `occluded` on the element. A click that lands on a modal overlay is the other half of "the button doesn't work":
+
+```json
+{ "occluded": true, "occludedBy": "div.modal-backdrop" }
+```
+
+## "ref no longer resolves to an element"
+
+```
+That ref is stale: refs are invalidated whenever the DOM re-renders, so any action that navigated,
+opened a modal, re-sorted a list or changed the page invalidates every ref taken before it.
+Reticle refuses here rather than clicking whatever now occupies that slot.
+```
+
+This is Reticle protecting you, not failing. Re-query for a fresh ref.
+
+Better: use `reticle_act_and_wait { until }` for actions that change the page, so the next ref is taken after things settle.
+
+<Warning>
+  Refs never survive a full navigation. A new document means new refs, the same button was `e5`
+  before a navigation and `e103` after.
+</Warning>
+
+## The verdict says `unknown`
+
+`verified: "unknown"` means Reticle drove the app and could not tell. It is **not** a pass.
+
+The usual cause is a throttled tab: throttling suppresses the quiescence detection used to decide the page has settled, so even a successful action can come back unsettled. Drive a lease and try again.
+
+If it persists on an unthrottled context, that is worth reporting. Reticle's own response says so:
+
+```json
+"feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An unknown verdict is our defect, not yours"
+```
+
+## A negative result you are not sure about
+
+Before concluding "no request fired", read the buffer note:
+
+```json
+"buffer": { "held": 15, "dropped": 529, "note": "…a negative result here may be a false negative; the evidence may have expired…" }
+```
+
+"Nothing found" and "I no longer have what you asked about" are different answers. Grade sooner, or widen the buffer.
+
+## The agent cannot find an element
+
+- `reticle_snapshot { mode: "interactive" }` shows everything actionable.
+- Add a `data-testid` for a stable handle.
+- Narrow with `scope`. A CSS selector or a ref.
+
+## Assertions are flaky on async UIs
+
+- Use `timeout_ms` on `assert` and `wait_for`.
+- Pass the `since` cursor from `reticle_act` so only post-action events count. Without it, an assertion can pass on an event from two clicks ago.
+
+## `reticle_state` returns nothing
+
+`storeNames` empty means no store was registered. `reticle_state` reads what your app registered in `src/reticle-dev.ts`.
+
+<Warning>
+Pass the **store**, not `() => store.getState()`. The getter form is read-only and silently produces
+empty `stateDiffs`. Which reads as "nothing changed" and means "I was never watching".
+</Warning>
+
+## Source file is not resolving on React 19
+
+React 19 dropped `_debugSource`. Wire up `@reticlehq/babel-plugin`. Or just use `@reticlehq/vite-plugin` or `@reticlehq/next`, which both include it. Without it you get component identity but no `file:line`.
+
+## `ERESOLVE` installing next to a prerelease
+
+`@reticlehq/next` declares `peer next >=13` and `@reticlehq/react` declares `peer react >=18`. On a Next canary or React RC, npm refuses. See [the prerelease notes](/getting-started#installing-alongside-a-nextjs-or-react-prerelease).
+
+## Restarting things
+
+```bash
+npx @reticlehq/server stop     # clean daemon shutdown, no pkill needed
+npx @reticlehq/server status   # confirm it came back
+```
+
+<Warning>
+  Do not kill port 4400 with `lsof -ti tcp:4400 | xargs kill -9`. That matches the MCP proxy as well
+  as the daemon and takes your agent's connection down with it. Use `reticle stop`, or at minimum
+  `lsof -sTCP:LISTEN`.
+</Warning>
+
+## Sessions piling up
+
+Stale sessions pointing at dev servers you restarted an hour ago look completely plausible in a list, and one of them will get picked.
+
+```json
+{ "action": "end" }
+```
+
+`reticle_session { action: "end" }` when you are done, `{ action: "yield" }` when pausing. Both revive on your next action.
+
+## Frequently asked questions
+
+<AccordionGroup>
+  <Accordion title="Why does reticle_sessions return nothing when my app is clearly running?">
+    Your app running is not the same as your app being connected. The SDK has to dial the daemon's
+    bridge port over a WebSocket. If `npx @reticlehq/server doctor` shows the daemon up and
+    `sessions` at zero, either `reticle.connect()` never executed (check the dev guard is actually
+    true) or the app dialled the wrong port. The browser console names the exact address it tried.
+  </Accordion>
+
+<Accordion title="Which port should my app dial?">
+  The bridge port, which defaults to `4400`. It is **not** your dev-server port. A dev server on
+  4312 and a daemon on 4400 is the normal, correct arrangement. `doctor` prints the bridge port
+  under `bridge port`.
+</Accordion>
+
+<Accordion title="I restarted my agent and the reticle tools still are not there.">
+  If you registered the MCP server while the agent was running, restart the agent process itself:
+  quit and reopen Claude Code, reload the window in Cursor, or press Start in `.vscode/mcp.json` in
+  VS Code. `/mcp` only manages servers that were already loaded, so it cannot discover a new one. If
+  the tools are still missing, run `claude mcp list` and check `reticle` is present.
+</Accordion>
+
+<Accordion title="Does a verdict of unknown mean the test failed?">
+  No, and it does not mean it passed either. `verified: "unknown"` means Reticle drove the app and
+  could not tell what happened, usually because the page never settled inside the observation
+  window. Report it as unknown. If you hit one on an unthrottled context and believe it is wrong,
+  that is a Reticle defect worth sending with `reticle_feedback`.
+</Accordion>
+
+<Accordion title="Is it safe to kill port 4400 to restart things?">
+  No. `lsof -ti tcp:4400 | xargs kill -9` matches your agent's MCP proxy as well as the daemon and
+  takes the connection down with it. Use `npx @reticlehq/server stop`, or at minimum add
+  `-sTCP:LISTEN` so only the listener matches.
+</Accordion>
+
+  <Accordion title="Why does my agent click a button and nothing happens?">
+    Check the response for a `warning` about a throttled tab. A backgrounded browser tab has its
+    timers suppressed, so synthetic pointer gestures can silently no-op while the action still
+    reports success. Drive a lease instead, which is a context Reticle owns and never backgrounds.
+    If the tab is fine, check `occluded` on the element: a click landing on a modal overlay looks
+    identical from the outside.
+  </Accordion>
+</AccordionGroup>
+
+<Card title="Still stuck?" icon="comments" href="/tools-session-and-feedback">
+  `reticle feedback --agent` works even when nothing is installed and the daemon will not start.
+</Card>