@reticlehq/server 2.7.0 → 2.9.0

package/docs/tools-query.mdx

@@ -0,0 +1,126 @@
+---
+title: reticle_query
+description: Find elements by Testing-Library semantics. Role, text, label, placeholder, testid, alt, or React component, including inside open shadow roots.
+icon: magnifying-glass
+---
+
+`reticle_query` answers "where is the thing I mean?" without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.
+
+## Example
+
+```json
+{ "by": "role", "value": "button", "limit": 6 }
+```
+
+Real response from a running app, with four of the six elements trimmed out for length:
+
+```json
+{
+  "count": 7,
+  "elements": [
+    {
+      "ref": "e118",
+      "role": "button",
+      "name": "Overview",
+      "visible": true,
+      "source": "src/components/Sidebar.tsx:41",
+      "states": ["present", "visible", "enabled"]
+    },
+    {
+      "ref": "e120",
+      "role": "button",
+      "name": "Compose",
+      "visible": true,
+      "source": "src/components/Sidebar.tsx:41",
+      "states": ["present", "visible", "enabled"]
+    }
+  ],
+  "total": 7,
+  "truncated": true,
+  "cost": { "bytes": 944, "tokens": 236 }
+}
+```
+
+Seven buttons, each with a `ref` to act on and a source file to open, for 236 tokens.
+
+## Arguments
+
+| Argument     | What it does                                                               |
+| ------------ | -------------------------------------------------------------------------- |
+| `by`         | `role` · `text` · `label` · `placeholder` · `testid` · `alt` · `component` |
+| `value`      | The query value for that strategy                                          |
+| `name`       | Accessible-name filter. Narrows a broad `role` query                       |
+| `scope`      | CSS selector or ref, to search inside a subtree                            |
+| `limit`      | Cap the descriptors returned. Cuts tokens hard on broad queries            |
+| `count_only` | Return just `{ count }`, around 30x smaller                                |
+| `attrs`      | Extra attributes per match, e.g. `['href']` to inventory links             |
+| `self`       | Return the `scope` element itself instead of searching inside it           |
+
+Every argument also has a predicate spelling, so `{ "role": "button" }` works as shorthand for `{ "by": "role", "value": "button" }`.
+
+## Use `count_only` when you only need a number
+
+"Are there still three rows?" does not require three row descriptors:
+
+```json
+{ "by": "testid", "value": "login-submit", "count_only": true }
+```
+
+```json
+{ "count": 1, "cost": { "bytes": 11, "tokens": 3 } }
+```
+
+Three tokens. Note that `total` is not emitted on this path, because `count` already is the total.
+
+## A zero-match result tells you what _is_ there
+
+```json
+{ "by": "testid", "value": "compose-prompt" }
+```
+
+```json
+{
+  "count": 0,
+  "elements": [],
+  "hint": {
+    "route": "/hostile",
+    "knownEmptyState": true,
+    "presentTestids": [
+      "brand",
+      "nav-overview",
+      "nav-deployments",
+      "nav-compose",
+      "nav-diagnostics",
+      "nav-hostile",
+      "session-pill",
+      "cmdk-open",
+      "sign-out",
+      "hostile-view",
+      "hostile-ticker",
+      "hostile-feed-count"
+    ],
+    "presentRegions": [
+      { "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] },
+      { "role": "banner", "childCount": 0, "sample": [] }
+    ]
+  },
+  "cost": { "bytes": 402, "tokens": 101 }
+}
+```
+
+The testid existed, on another route. `hint.route` says where you actually are, `presentTestids` says what is on this page instead, and `presentRegions` distinguishes an empty list from a missing one. All of it without paying for a snapshot.
+
+## Reading the response
+
+`ref` is the handle for every other tool: `act`, `inspect`, `state`. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element.
+
+`source` appears when `@reticlehq/react` is installed. Note that both sidebar buttons above report `Sidebar.tsx:41`, and so do the three trimmed out of the example. That is the line where the component renders all five in a loop, which is exactly the line you want to edit.
+
+`truncated: true` with `total: 7` means `limit` cut the list, not that Reticle ran out of room. Neither field is emitted when nothing was cut, so their absence is itself the signal that you are looking at every match.
+
+`states` distinguishes `present` from `visible` from `enabled`. An element can be all three and still be covered by a modal. [`reticle_inspect`](/tools-inspect) reports `occluded` for that.
+
+<Tip>
+  Query by `testid` when you can. Role and text queries survive refactors well; testids survive
+  redesigns, translations, and the day someone rewrites your button labels for the marketing team.
+</Tip>

package/docs/tools-session-and-feedback.mdx

@@ -0,0 +1,112 @@
+---
+title: reticle_session and reticle_feedback
+description: Hand the session back to the human, end it cleanly, and tell the maintainers when Reticle got something wrong.
+icon: comments
+---
+
+`reticle_session` manages the boundary between the agent and the human watching: hand control back, end the session, narrate what you are doing, and drain the bugs they pinned on elements. `reticle_feedback` is how you tell the Reticle maintainers that Reticle itself got something wrong. Neither tool touches your app, and neither produces a verdict.
+
+## reticle_session
+
+The presenter panel in your app shows a live transcript of what the agent is doing. It reads "live" until the agent says otherwise. So an agent that wanders off without a word leaves a panel claiming work is in progress forever.
+
+| Action     | What it does                                                             |
+| ---------- | ------------------------------------------------------------------------ |
+| `yield`    | Hand control back between turns. `mode: "waiting"` or `"ask"`. Revivable |
+| `end`      | The task is done. Frees the session; revives on the next action          |
+| `tune`     | Adjust session behaviour, such as `idleEndMs`, the idle-end window       |
+| `resume`   | Clear a pause the human applied                                          |
+| `messages` | Drain the human-to-agent inbox                                           |
+| `review`   | List, and with `resolve`, retire the mistakes a human pinned to elements |
+| `narrate`  | State your intent on the presenter panel, with an optional `level`       |
+
+```json
+{ "action": "yield", "mode": "waiting" }
+```
+
+`review` returns a real reading rather than a silent empty:
+
+```json
+{ "marks": [], "pendingCount": 0 }
+```
+
+Reticle nudges you about all of this. Every response on a long-running session carries a reminder:
+
+```json
+"session_age_warning": "Session s223e0fad-e012-43f9-a23d-6d585470c90d has been open for 21 minutes. If your task is complete, call reticle_session{action:\"end\"} now."
+```
+
+And each lease carries the rule in the payload itself:
+
+```json
+"session_lease": {
+  "IMPORTANT": "When you stop driving, call reticle_session {action:\"yield\", mode:\"waiting\"|\"ask\"}. The panel reads \"live\" until you do."
+}
+```
+
+<Tip>
+  `yield` when you are pausing and might come back. `end` when you are finished. Both revive on your
+  next action, so neither is destructive. The difference is what the human watching the panel is
+  told.
+</Tip>
+
+## reticle_feedback
+
+Reticle is built for agents, which creates an unusual problem: the primary user's experience vanishes the moment its context does. If an agent hits a gap and works around it silently, nobody ever learns the gap existed.
+
+```json
+{
+  "kind": "bug",
+  "text": "What I called, what I expected, what I got, and why Reticle is at fault.",
+  "currentApproach": "How I am working around it today.",
+  "impact": "What measurably improves if this is fixed."
+}
+```
+
+| `kind`            | Use it when                                                |
+| ----------------- | ---------------------------------------------------------- |
+| `bug`             | A tool returned a wrong or broken result                   |
+| `gap`             | Reticle could not observe something you needed at all      |
+| `ambiguity`       | The check ran but you could not tell what the answer meant |
+| `feature_request` | You wished a capability existed                            |
+| `improvement`     | It works, but costs too many calls                         |
+
+### It will tell you when it cannot send
+
+Feedback is not fire-and-forget, and it does not pretend to succeed:
+
+```json
+{
+  "sent": false,
+  "accepted": false,
+  "reason": "this is a Reticle source checkout, where telemetry is disabled by design, so feedback has nowhere to go. Open an issue at https://github.com/reticlehq/reticle/issues instead, or run from the app you are verifying.",
+  "redacted": [],
+  "context": {
+    "stack": "react",
+    "client": "claude-code",
+    "runtime": "web",
+    "engine": "blink",
+    "driver": "cdp",
+    "mcpScope": "user"
+  },
+  "note": "NOT accepted (see reason). Tell the human what you found so it is not lost."
+}
+```
+
+`redacted` names anything stripped from your report before it left the machine, so you can see what was and was not sent. `context` is the environment attached automatically, which is why a useful report costs one call and no boilerplate.
+
+That is a real response, captured while writing these docs. The instruction in `note` is the important part: when the report cannot be delivered, say so in your answer to the human rather than letting the finding evaporate.
+
+### From the shell, when the tools are unreachable
+
+The setup that failed to finish is exactly the setup that most needs reporting, and in that state the MCP tools do not exist:
+
+```bash
+npx @reticlehq/server feedback --agent --kind gap "reticle init finished but no session ever connected"
+```
+
+<Note>
+  Report defects in **Reticle**. A bug you find in the app under test is Reticle working correctly,
+  and belongs in your answer to the user. Not in a bug report to us. We get a surprising number of
+  those, and each one is quietly a compliment.
+</Note>

package/docs/tools-sessions.mdx

@@ -0,0 +1,94 @@
+---
+title: reticle_sessions
+description: List every connected browser tab, with the health fields that tell you whether it can actually be driven.
+icon: list-check
+---
+
+`reticle_sessions` lists every browser tab currently connected to the Reticle daemon, with the health fields that decide whether it can actually be driven. Reach for it first when a tool says no session is connected, and after every [`reticle_navigate`](/tools-navigate) that came back `confirmed: false`.
+
+```json
+{}
+```
+
+Real response from a healthy session:
+
+```json
+{
+  "sessions": [
+    {
+      "sessionId": "sba6117a6-24ec-494d-8c2c-e2958cff2e7f",
+      "url": "http://localhost:4310/",
+      "title": "Reticle · Mission Control",
+      "adapters": ["react"],
+      "hasCapabilities": true,
+      "hidden": false,
+      "lastSeenMs": 155,
+      "throttled": false,
+      "focused": true,
+      "attachment": { "connectedSinceMs": 18654, "outages": 0 },
+      "realInputAvailable": false,
+      "leased": false
+    }
+  ]
+}
+```
+
+A backgrounded tab adds a `recommendation` telling you what to do about it, and `attachment` grows a `lastOutage` once the connection has dropped at least once:
+
+```json
+{
+  "hidden": false,
+  "throttled": true,
+  "attachment": {
+    "connectedSinceMs": 1217047,
+    "outages": 3,
+    "lastOutage": { "startedMs": 1786818483776, "durationMs": 967 }
+  },
+  "recommendation": "tab hidden/throttled and may be un-focusable from here; refocus it, or run `reticle drive <url>` for a guaranteed scriptable context"
+}
+```
+
+## When nothing is connected
+
+An empty list is not silent. It comes back with a `why` that separates the two causes, and refuses to guess between them:
+
+```json
+{
+  "sessions": [],
+  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans, so the dev server may not be running. That scan is narrow though: a server on any other port is invisible to it, so if the app IS running, ask for its URL rather than assuming it is down, and open it with `reticle open <url>`. (2) There is no `.reticle.json` in the directory this daemon is running in. That is the file `reticle init` writes, so the app may carry no Reticle SDK."
+}
+```
+
+That string is trimmed. The full text also lists the exact ports it scanned and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory, so you should check the app's own directory before re-running `init`.
+
+## The fields that decide whether driving will work
+
+| Field | Why it matters |
+| --- | --- |
+| `throttled` | The browser is deprioritising a background tab. Synthetic timers and pointer gestures may silently no-op |
+| `hidden` / `focused` | Why it's throttled, and what to do about it |
+| `hasCapabilities` | Whether the app registered testids, signals and stores. `false` means [`reticle_state`](/tools-state) has nothing to read |
+| `adapters` | `["react"]` means you get component names and source pointers |
+| `realInputAvailable` | `true` when native CDP input is available, under `reticle drive` |
+| `outages` | How often the connection has dropped. Non-zero is worth investigating |
+
+<Warning>
+  `throttled: true` is the most common cause of "the click did nothing". Focus the tab, or drive a
+  dedicated context. It is not your app being broken. It is the browser saving battery on a tab
+  nobody is looking at.
+</Warning>
+
+## Confirm after navigating
+
+[`reticle_navigate`](/tools-navigate) can only report that a navigation was dispatched. `sessions` is how you confirm one arrived: a session at the new URL means the page loaded **and** is instrumented. No session means one of those two is false, and you find out now rather than after three confusing failures.
+
+## Scoping
+
+You rarely need to pass `sessionId` to other tools. Reticle scopes to your project, prefers the active tab, and refuses rather than guesses when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
+
+Pass it explicitly when you genuinely mean one specific tab, such as when testing two apps at once.
+
+<Note>
+Sessions accumulate. A stale entry pointing at a dev server you have since restarted will sit there
+looking plausible. `reticle_session { action: "end" }` clears one out.
+</Note>

package/docs/tools-snapshot.mdx

@@ -0,0 +1,129 @@
+---
+title: reticle_snapshot
+description: A semantic accessibility snapshot of the page or a subtree, in three sizes. From the full tree down to a 25-token route check.
+icon: camera
+---
+
+`reticle_snapshot` is how an agent gets its bearings. It returns the page as semantic structure, not pixels and not raw HTML, and it comes in three sizes so you can pay for only what you need.
+
+## Three modes, three prices
+
+| Mode          | Returns                               | Real cost on one page |
+| ------------- | ------------------------------------- | --------------------- |
+| `status`      | Route and title only                  | **25 tokens**         |
+| `interactive` | Only clickable and focusable elements | **65 tokens**         |
+| `full`        | Every element                         | Depends on the page   |
+
+### `status`. the cheapest possible check
+
+```json
+{ "mode": "status" }
+```
+
+```json
+{
+  "tree": "",
+  "nodes": 0,
+  "truncated": false,
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 98, "tokens": 25 }
+}
+```
+
+Ninety-eight bytes to answer "where am I?". Use it after a navigation instead of re-reading the page.
+
+### `interactive`. the default working view
+
+```json
+{ "mode": "interactive" }
+```
+
+```json
+{
+  "tree": "- textbox \"Email\" (ref=e303) [value=\"admin@reticle.dev\"]\n- textbox \"Password\" (ref=e304) [value=\"[REDACTED]\"]\n- button \"Sign in\" (ref=e305)",
+  "nodes": 3,
+  "truncated": false,
+  "status": { "route": "/deployments", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 260, "tokens": 65 }
+}
+```
+
+Everything you can act on, with a `ref` for each, for 65 tokens. Note the password arrives `[REDACTED]` without anyone configuring it.
+
+## Arguments
+
+| Argument | What it does                                                                 |
+| -------- | ---------------------------------------------------------------------------- |
+| `mode`   | `full` · `interactive` · `status`                                            |
+| `scope`  | CSS selector or ref, to snapshot one subtree                                 |
+| `diff`   | Return only what changed since your last snapshot of the same scope and mode |
+
+## `diff` is how you keep a long session cheap
+
+```json
+{ "mode": "interactive", "diff": true }
+```
+
+When nothing moved since your last look of the same scope and mode, that costs 20 tokens and says so:
+
+```json
+{
+  "mode": "unchanged",
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 79, "tokens": 20 }
+}
+```
+
+When something did move, you get only what changed. This is the same call after a login replaced the form with the app shell:
+
+```json
+{
+  "mode": "delta",
+  "delta": {
+    "added": [
+      "- button \"Overview\" (ref=e17)",
+      "- button \"Deployments40\" (ref=e18)",
+      "- button \"Compose\" (ref=e19)",
+      "- button \"Diagnostics\" (ref=e20)",
+      "- button \"Hostile\" (ref=e21)",
+      "- button \"Search or jump to…⌘K\" (ref=e22)",
+      "- button \"Sign out\" (ref=e23)"
+    ],
+    "removed": [
+      "- textbox \"Email\" (ref=e4) [value=\"admin@reticle.dev\"]",
+      "- textbox \"Password\" (ref=e5) [value=\"[REDACTED]\"]",
+      "- button \"Sign in\" (ref=e3)"
+    ],
+    "addedCount": 7,
+    "removedCount": 3
+  },
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 545, "tokens": 137 }
+}
+```
+
+A route change resets it: the next call after one returns a full snapshot rather than a delta against a page that no longer exists.
+
+<Tip>
+  Reach for [`reticle_query`](/tools-query) instead when you already know what you're looking for.
+  Snapshot is for orientation; query is for retrieval, and it's almost always cheaper.
+</Tip>
+
+## Refs change across documents
+
+Refs are stable while the element is in the DOM. A full navigation builds a new document, so refs are re-issued. Across the captures on this page the same "Sign in" button was `e105`, then `e305`, then `e3`, because each reload built a new document. Snapshot after navigating; don't reuse refs across one.
+
+Reticle refuses a stale ref rather than clicking whatever now occupies that slot:
+
+```json
+{
+  "error": "ref 'e303' no longer resolves to an element",
+  "recovery": "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. Call reticle_query again for a fresh ref and retry the action."
+}
+```
+
+<Note>
+  That `recovery` string is trimmed. The full text also recommends
+  [`reticle_act_and_wait`](/tools-act-and-wait) with `until`, so the next ref is taken after the
+  page settles.
+</Note>

package/docs/tools-state.mdx

@@ -0,0 +1,104 @@
+---
+title: reticle_state
+description: Read live framework state directly from the running app. What it believes, not just what it rendered, without the app broadcasting anything.
+icon: database
+---
+
+`reticle_state` reads live framework state straight out of the running app, without the app broadcasting anything. Reach for it when the DOM looks right and you want to know whether the application actually accepted the change, which is where false greens live.
+
+The DOM tells you what the app _drew_. `reticle_state` tells you what it _believes_. The gap between those two is where false greens live: a row appears in the table, the store never changed, and a reload makes the row vanish.
+
+## Example
+
+```json
+{ "depth": 2 }
+```
+
+Real response:
+
+```json
+{
+  "found": true,
+  "value": {
+    "stores": {
+      "__reticle_renders": "{…1 keys}",
+      "app": "{…30 keys}",
+      "queries": "{…0 keys}"
+    },
+    "storeNames": ["__reticle_renders", "app", "queries"]
+  },
+  "storeNames": ["__reticle_renders", "app", "queries"]
+}
+```
+
+`depth: 2` collapsed the contents to size markers: `{…30 keys}` rather than thirty keys of JSON. On a large store this is the difference between a cheap look and a very expensive one.
+
+## Arguments
+
+| Argument | What it does                                                 |
+| -------- | ------------------------------------------------------------ |
+| `store`  | A registered store name, e.g. `app`                          |
+| `path`   | Dot-path into a store, e.g. `cart.items.0.qty`               |
+| `depth`  | Collapse anything deeper than N levels to a size marker      |
+| `ref`    | Best-effort read of the nearest React component's hook state |
+
+Drill in once you know what you want:
+
+```json
+{ "store": "app", "path": "auth" }
+```
+
+```json
+{
+  "store": "app",
+  "path": "auth",
+  "found": true,
+  "value": { "email": "admin@reticle.dev" },
+  "storeNames": ["__reticle_renders", "app", "queries"]
+}
+```
+
+A wrong `path` comes back `{ "found": false, "availableKeys": [...] }` rather than an empty value, so a typo is diagnosable instead of looking like an empty store.
+
+<Warning>
+  `reticle_state` asks the page and waits. On a backgrounded tab the page may never answer, and you
+  get `"command 'state_read' timed out after 8000ms"` with a recovery note pointing at
+  [`reticle_sessions`](/tools-sessions). That is a fact about the tab, not a Reticle failure. Bring
+  it to the front, or drive your own browser.
+</Warning>
+
+## You have to register stores first
+
+`reticle_state` reads what your app registered in `src/reticle-dev.ts`. With nothing registered, `storeNames` comes back empty and this tool has nothing to say.
+
+```ts
+registerCapabilities({
+  stores: [{ name: 'app', store: appStore }],
+});
+```
+
+<Warning>
+Pass the **store**, not `() => store.getState()`. The store form wires `subscribe` too, so every
+mutation emits a state diff. The getter form is read-only and silently produces empty diffs, which
+looks like "nothing changed" and is really "I was never watching".
+</Warning>
+
+That distinction is the single most common instrumentation mistake, and its failure mode is a verdict that passes when it should not.
+
+## Why this is the strongest evidence you have
+
+A `POST` returning `200` proves the server was reachable. A row in the DOM proves React rendered something. Neither proves your application accepted the change.
+
+State does. When [`reticle_act_and_wait`](/quickstart) reports
+
+```json
+"stateDiffs": [
+  { "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}", "atMs": 44403 }
+]
+```
+
+that is the app itself saying the login took. A mock that returns `200` without touching state gets caught right there, and nowhere else.
+
+<Card title="Instrument your app" icon="wrench" href="/instrumentation">
+  Registering one store for your most important flow is the highest-value line you can write.
+</Card>