@reticlehq/server 3.1.0 → 3.3.0

package/docs/usage.md

@@ -84,7 +84,7 @@ Who benefits most: anyone shipping **dashboards, internal tools, SaaS apps**. Be
 
 ### `reticle_session { action: "list" }`
 
-List connected tabs. → `{ sessions: [{ sessionId, url, title, lastSeenMs, hidden, focused, throttled }] }`. `lastSeenMs` is the silence since the tab last reported (not time-since-connect); `throttled` is `true` when the tab is hidden or has gone quiet, and a throttled tab silently no-ops timers/rAF/pointer.
+List connected tabs. → `{ sessions: [{ sessionId, url, title, lastSeenMs, hidden, focused, throttled }] }`. `lastSeenMs` is the silence since the tab last reported (not time-since-connect); `throttled` is `true` when the tab is hidden **or** has merely gone quiet, and the two are not the same finding: a hidden tab clamps timers/rAF/pointer so an action can land on a page that never advances, while a quiet-but-visible tab is usually still driveable. The accompanying `recommendation` says which case you are in; treat `throttled` as a reason to read it, not as a reason to lease.
 
 ### `reticle_look { action: "page" }`
 
@@ -200,7 +200,7 @@ Verify a predicate; optionally wait for it.
 - **args:** `predicate`, `timeout_ms?` (0 = evaluate once), `since?`, `intent?`, `sessionId?`.
 - Same `since` default as `reticle_assert { action: "wait" }`: scoped to your last act so a stale buffered event can't fake a pass; override with an explicit `since`.
 - **returns:** `{ verified, because, pass, evidence, contradictions?, coverage?, failureReason?, session, warning? }`. On failure includes a **near-miss** (e.g. "found the dialog but not visible", or "no button named 'Submit'; saw: Cancel"). The `session` block `{ lastSeenMs, throttled, focused }` reports tab health on every assert; when throttled a `warning` is attached so you never assert against a tab that is silently no-oping.
-- **`intent` declares what the change was FOR, inline.** Pass a sentence in your own words and it lands in `.reticle/intent.json`, the same git-checked ledger `reticle_intent` writes, before the verdict is drawn; a green verdict then marks it proved and names itself as the proof. Pass the **id** of an intent you already declared instead, to point several verdicts at one statement rather than restating it. `reticle_act_and_wait` takes the same argument. Omit it and nothing is written.
+- **`intent` declares what the change was FOR, inline.** Pass a sentence in your own words and it lands in `.reticle/intent/` (one directory per subject, a flow's name being its subject), the same git-checked ledger `reticle_intent` writes, before the verdict is drawn; a green verdict then marks it proved and names itself as the proof. Pass the **id** of an intent you already declared instead, to point several verdicts at one statement rather than restating it. `reticle_act_and_wait` takes the same argument. Omit it and nothing is written.
 - **Read `verified`, not `pass`.** `pass` says the predicate held; `verified` says whether that means anything. It is `"no"` when a channel contradicts the assertion (a failed write under a green screen, a batch whose body reports per-item failures, a request still in flight), and `"unknown"` when the outcome could not be known yet: a `202 Accepted` that has not reconciled, or a write whose response body was never recorded. `because` names the deciding evidence in one sentence.
 
 ### `reticle_reconcile`

package/docs/what-is-recorded.md

@@ -0,0 +1,62 @@
+---
+title: What is recorded
+description: What Reticle keeps on your machine, what is redacted, and what it takes for any of it to leave.
+---
+
+Reticle drives your app and reads what it did. That means it holds real content from real pages, so this page says exactly what it keeps, where it keeps it, and what it takes to make any of it leave.
+
+If you read one line: **a verdict is entirely local and needs no account.** Nothing is sent anywhere until you run `reticle login` and `reticle link`. Without them there is nowhere for anything to go.
+
+## On your machine
+
+Everything lands in `.reticle/` in your project, and it is yours. Three kinds of thing:
+
+|  | what it is | what is in it |
+| --- | --- | --- |
+| **runs** | a verdict and its evidence | what was claimed, whether it held, the request or state change that decided it, and the `file:line` of the element driven |
+| **flows** | a journey you drove, saved so it can be replayed | the steps, the anchors they resolve by, and the values that were typed |
+| **memory** | what this project has learned across sessions | intents you declared, envelopes of normal behaviour, notes about anchors that drift |
+
+`.reticle/` splits into a part meant for git and a part meant to stay local. Flows are the part worth committing: a saved flow is a regression test. Evidence is the part that is not.
+
+## What is redacted, and what is not
+
+**Credential-shaped fields are redacted when a flow is saved.** A value typed into a field whose name looks like a secret is replaced with `<redacted: supply at replay>`, and replay reads the real value from `RETICLE_SECRET_<FIELD>` at run time. It keys off the field's name across every anchor kind (a testid, an accessible name, a signal), so an app without test ids is covered too.
+
+**It is name-based, and that is the limit worth knowing.** It redacts a password. It does not redact a customer's name typed into a search box, because nothing about that field says "secret". A flow records the journey you actually drove.
+
+So: **drive staging.** Not because the risk is large, but because it is real and avoiding it is free.
+
+Network bodies are **not** captured by default. Page content that reaches a verdict is the element text and attributes the assertion needed, not a copy of the DOM.
+
+## What leaves, only if you ask
+
+`reticle login` signs this machine in. `reticle link` binds one repo to one cloud project. Until both have happened, `reticle push` has nothing to talk to and the sync path is a no-op. The code calls this the no-phone-home default.
+
+Once linked, you choose what syncs:
+
+```bash
+npx @reticlehq/server config --runs on|off --flows on|off --memory on|off
+```
+
+## Telemetry, which is separate from all of the above
+
+The CLI sends anonymous usage events: event names and a random installation id. No code, no page content, no URLs from your app. It is how we know which parts of the product are reached at all.
+
+```bash
+RETICLE_TELEMETRY=0          # this shell
+DO_NOT_TRACK=1               # the convention, honoured
+npx @reticlehq/server telemetry disable   # this machine, permanently
+```
+
+Feedback is the only free text that ever leaves, it is never collected passively, and `RETICLE_FEEDBACK=0` disables it.
+
+## What `init` writes to your project
+
+Run it with `--dry-run` and it prints the whole plan without writing anything:
+
+```bash
+npx @reticlehq/server init --dry-run
+```
+
+`--app <dir>` picks which app in a monorepo. `--no-mcp` skips registering the MCP server with your agents and skips the agent rule files with it. `--files-only` writes the files and stops, without booting your dev server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,11 +23,11 @@
     "ws": "^8.21.3",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/browser": "3.1.0",
-    "@reticlehq/core": "3.1.0",
+    "@reticlehq/engine": "3.3.0",
+    "@reticlehq/browser": "3.3.0",
+    "@reticlehq/init": "3.3.0",
     "open-verification": "1.0.0",
-    "@reticlehq/engine": "3.1.0",
-    "@reticlehq/init": "3.1.0"
+    "@reticlehq/core": "3.3.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",

package/dist/judgement/outcome/predicate-to-expect.d.ts

@@ -1,44 +0,0 @@
-/**
- * The assertion the agent MADE, in the shape a saved flow can keep.
- *
- * `reticle_act_and_wait { until }` is how agents assert — nearly every asserting call in a day of telemetry
- * carried an `until`. `compileActStep` recorded only the ACTION, so a flow saved after an asserted
- * drive came back graded `assertion-free`: "performs actions but asserts no observable consequence —
- * it will pass even if the feature is broken." The agent had already said what success meant;
- * Reticle discarded it and then warned the agent that the flow asserts nothing.
- *
- * That is the regression-suite story failing at its last step. "Record once, verify forever" is only
- * worth anything if the recorded flow can go RED, and locally 32 of 39 saved flows cannot.
- *
- * The inverse of `successToPredicate`. Only the kinds FlowExpect can express are carried: `settled`
- * is a wait rather than a claim, and `animation`/`anyOf`/`not` have no representation at all (`route` gained one — see its case below).
- * Inventing one would write an assertion into the file that the agent never made, which is worse
- * than recording none — a flow that asserts something nobody chose is a false green with extra steps.
- */
-import type { FlowExpect } from '@reticlehq/core';
-import type { Predicate } from '@reticlehq/engine/question/predicate/predicate.js';
-export declare function predicateToExpect(predicate: Predicate): FlowExpect | undefined;
-/**
- * The subset a REPLAY actually enforces.
- *
- * The rule has never changed: never write an assertion into a flow file that nothing evaluates. A
- * flow reporting `grade: "asserted"` while its assertion is read by no one is a false green, in the
- * feature whose entire purpose is preventing them.
- *
- * What changed is the SET. This kept only `element.testid` and `state`, because for a long time
- * those were the only kinds replay checked — and the note here said lifting it "requires replay to
- * evaluate them per step". Replay now does exactly that: `assertStepExpect` compiles every
- * remaining kind through `successToPredicate` and waits on it. The condition was met and the filter
- * was not updated, so the two drifted.
- *
- * That drift had a cost, and it fell on the agent. `reticle_act_and_wait { until }` IS the agent
- * saying what success means, and `net` is overwhelmingly what it says. Every one of those was
- * discarded at capture, so an agent-recorded flow reached disk assertion-free BY CONSTRUCTION and
- * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
- * completing all the way to a run that could never be a pass. Found by driving it.
- *
- * The list below is exactly what `successToPredicate` reads, including an element located by
- * role or name. A testid is also asserted directly against the DOM by the step runner. Anything
- * it cannot compile is still dropped.
- */
-export declare function enforcedOnReplay(expect: FlowExpect | undefined): FlowExpect | undefined;

package/dist/judgement/outcome/predicate-to-expect.js

@@ -1,148 +0,0 @@
-import { PredicateKind } from '@reticlehq/core';
-/** Merge two partial expectations; later keys win only where the earlier one said nothing. */
-function merge(into, from) {
-    return { ...from, ...into };
-}
-export function predicateToExpect(predicate) {
-    switch (predicate.kind) {
-        case PredicateKind.SIGNAL: {
-            if (predicate.name === undefined)
-                return undefined;
-            const signal = { signal: predicate.name };
-            if (predicate.dataMatches !== undefined)
-                signal.signalData = predicate.dataMatches;
-            if (predicate.count !== undefined)
-                signal.signalCount = predicate.count;
-            return signal;
-        }
-        case PredicateKind.ROUTE: {
-            // Carried, not invented: the agent said "until the route is X" in so many words. The kinds
-            // below this comment's twin in the header — animation, anyOf, not — stay refused because
-            // there the file would gain a claim nobody made.
-            const route = {};
-            if (predicate.pathname !== undefined)
-                route.pathname = predicate.pathname;
-            if (predicate.contains !== undefined)
-                route.contains = predicate.contains;
-            return 0 === Object.keys(route).length ? undefined : { route };
-        }
-        case PredicateKind.NET: {
-            const net = {};
-            if (predicate.method !== undefined)
-                net.method = predicate.method;
-            if (predicate.urlContains !== undefined)
-                net.urlContains = predicate.urlContains;
-            if (predicate.status !== undefined)
-                net.status = predicate.status;
-            if (predicate.count !== undefined)
-                net.count = predicate.count;
-            return 0 === Object.keys(net).length ? undefined : { net };
-        }
-        case PredicateKind.CONSOLE: {
-            // `contains` has no representation in FlowExpect.console (core keeps `level` and `absent`
-            // and nothing else). Copying the rest through anyway would record an assertion the agent
-            // never made: {console, level:'warn', contains:'no-op', absent:true} would save "no warn
-            // entries at all", a false red on any unrelated warning, and in the presence direction it
-            // saves a strictly weaker claim than the one chosen. This file's own rule applies: record
-            // nothing rather than something different, so the flow stays assertion-free there instead.
-            if (predicate.contains !== undefined)
-                return undefined;
-            const console_ = {};
-            if (predicate.level !== undefined)
-                console_.level = predicate.level;
-            if (predicate.absent !== undefined)
-                console_.absent = predicate.absent;
-            return 0 === Object.keys(console_).length ? undefined : { console: console_ };
-        }
-        case PredicateKind.ELEMENT: {
-            const element = {};
-            if (predicate.query.testid !== undefined)
-                element.testid = predicate.query.testid;
-            if (predicate.query.role !== undefined)
-                element.role = predicate.query.role;
-            if (predicate.query.name !== undefined)
-                element.name = predicate.query.name;
-            return 0 === Object.keys(element).length ? undefined : { element };
-        }
-        case PredicateKind.STATE: {
-            const state = { path: predicate.path };
-            if (predicate.store !== undefined)
-                state.store = predicate.store;
-            if (predicate.equals !== undefined)
-                state.equals = predicate.equals;
-            return { state };
-        }
-        case PredicateKind.ALL_OF: {
-            // `settled` members drop out on their own by returning undefined.
-            let combined;
-            for (const part of predicate.predicates) {
-                const expect = predicateToExpect(part);
-                if (expect === undefined)
-                    continue;
-                combined = combined === undefined ? expect : merge(combined, expect);
-            }
-            return combined;
-        }
-        default:
-            // settled | route | animation | anyOf | not — nothing FlowExpect can say honestly.
-            return undefined;
-    }
-}
-/**
- * The subset a REPLAY actually enforces.
- *
- * The rule has never changed: never write an assertion into a flow file that nothing evaluates. A
- * flow reporting `grade: "asserted"` while its assertion is read by no one is a false green, in the
- * feature whose entire purpose is preventing them.
- *
- * What changed is the SET. This kept only `element.testid` and `state`, because for a long time
- * those were the only kinds replay checked — and the note here said lifting it "requires replay to
- * evaluate them per step". Replay now does exactly that: `assertStepExpect` compiles every
- * remaining kind through `successToPredicate` and waits on it. The condition was met and the filter
- * was not updated, so the two drifted.
- *
- * That drift had a cost, and it fell on the agent. `reticle_act_and_wait { until }` IS the agent
- * saying what success means, and `net` is overwhelmingly what it says. Every one of those was
- * discarded at capture, so an agent-recorded flow reached disk assertion-free BY CONSTRUCTION and
- * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
- * completing all the way to a run that could never be a pass. Found by driving it.
- *
- * The list below is exactly what `successToPredicate` reads, including an element located by
- * role or name. A testid is also asserted directly against the DOM by the step runner. Anything
- * it cannot compile is still dropped.
- */
-export function enforcedOnReplay(expect) {
-    if (expect === undefined)
-        return undefined;
-    const kept = {};
-    // The step runner asserts a testid against the live DOM before the predicate engine. Role and
-    // name are not that path: successToPredicate compiles them, and dropping them here made a
-    // recorded `until` by button name vanish so the saved flow could not go red.
-    const element = expect.element;
-    if (undefined !== element &&
-        (undefined !== element.testid || undefined !== element.role || undefined !== element.name)) {
-        kept.element = element;
-    }
-    // Everything `successToPredicate` can compile. Replay evaluates EVERY kind of expect through it
-    // (see assertStepExpect); this list is what that function actually reads.
-    if (expect.state !== undefined)
-        kept.state = expect.state;
-    if (expect.signal !== undefined)
-        kept.signal = expect.signal;
-    if (expect.signalData !== undefined)
-        kept.signalData = expect.signalData;
-    if (expect.signalCount !== undefined)
-        kept.signalCount = expect.signalCount;
-    if (expect.net !== undefined)
-        kept.net = expect.net;
-    if (expect.console !== undefined)
-        kept.console = expect.console;
-    // `route` joined the list the day FlowExpect gained the field. This filter and
-    // `successToPredicate` are two allowlists for one question — "can replay check this?" — and the
-    // note above records them drifting once already. They drifted again here, in the same direction,
-    // within an hour: the field was added, the mapping was added, and a route assertion still reached
-    // disk as nothing because THIS list had not heard of it. Found by driving, not by a test.
-    if (expect.route !== undefined)
-        kept.route = expect.route;
-    return 0 === Object.keys(kept).length ? undefined : kept;
-}