@reticlehq/server 3.5.0 → 3.6.0

package/docs/quickstart.mdx

@@ -5,7 +5,7 @@ description: Install Reticle, connect your coding agent, and get a real verdict
 icon: rocket
 ---
 
-**Run the installer once, then run `reticle connect --project "My App"` in your project.** Reticle embeds a dev-only SDK in your running app, signs you in through browser approval when needed, and syncs your checks to the project you name.
+**Run the installer once, then ask your agent to verify something in your app; its first Reticle call wires the app (the same thing `reticle init` does, which you can also run yourself).** Reticle embeds a dev-only SDK in your running app and proves a browser session connected. No account needed. Add `reticle connect` later if you want a cloud dashboard.
 
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
@@ -53,19 +53,26 @@ npm install -g @reticlehq/server
 npx @reticlehq/server setup mcp
 ```
 
-## Step 2. Connect this project
+## Step 2. Wire this project
 
 In your project directory, before opening your coding agent:
 
 ```bash
-npx @reticlehq/server connect --project "My App"
+RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server init
 ```
 
-This installs the SDK, wires your app, starts the dev server, and checks that a browser session connected. It then opens browser sign-in approval if needed, links this folder to the named cloud project, and sends existing local history. Approve the short code shown in the browser and terminal; the command resumes by itself. A saved sign-in is reused after the cloud accepts it. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools.
+This installs the dev-only SDK, wires your build config, starts the dev server, and checks that a browser session connected. Nothing from your project leaves your machine. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools. The `RETICLE_INSTALL_SOURCE` prefix is optional and only tells us which page you installed from. It is idempotent: run it twice and the second run reports what was already done rather than doing it again.
 
-Step 1 is once per machine. This step is once per project.
+Step 1 is once per machine. This step is once per project. **Skipping it is the most common reason Reticle "does nothing":** the agent has the tools, but there is no app on the other end for them to see.
 
-Want local-only verification without an account? Run `reticle init` in this step instead. You can run `reticle connect` later to sync your history.
+Want a cloud dashboard too? Run `npx @reticlehq/server connect --project "My App"` instead of, or after, `init`. It does everything `init` does, then opens browser sign-in approval, links this folder to the named cloud project, and sends existing local history. Approve the short code shown in the browser and terminal; the command resumes by itself.
+
+<Note>
+  **Skipped this step?** Ask your agent to verify something in the app. Its first `reticle_session`
+  call finds a project that has never connected, runs `init` there itself, and lists every file it
+  changed under `wired`. Asked about something unrelated, it offers to wire the app instead of doing
+  it. This works in Claude Code, Codex, Cursor and other MCP agents.
+</Note>
 
 Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
 
@@ -218,7 +225,7 @@ Read what that actually proves:
 
 ## What "verified" can say
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card title="yes" icon="circle-check">
     The consequence you named actually happened, and the evidence is attached.
   </Card>
@@ -228,6 +235,9 @@ Read what that actually proves:
   <Card title="unknown" icon="circle-question">
     Reticle drove the app and could not tell. **This is not a pass.** Report it as unknown.
   </Card>
+  <Card title="no-fault" icon="circle-minus">
+    Nothing was declared to prove, so nothing was checked. **Not a pass either:** add an `until`.
+  </Card>
 </CardGroup>
 
 That third state is the one that matters. Most tools have two outcomes and quietly file "I couldn't tell" under "fine". A verification layer that cannot admit uncertainty is just a very confident random number generator.

package/docs/telemetry.md

@@ -48,7 +48,7 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 
 **Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception: a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](https://github.com/reticlehq/reticle/blob/main/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` (the text being typed into your app, which on a login form is a password) is **never** in that allowlist.
 
-`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`).
+`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`). It also carries how the in-page HUD was used: presses per control (`hudControls`, by the control's name from a closed list Reticle defines, a toggle as `name:on` / `name:off`), how long the HUD sat as a bubble, collapsed or open and on which page (`hudViewMs`, `hudPanelMs`), which rail slides were shown (`hudSlides`), and the order of those presses and views, cut at 60 (`hudJourney`). Control names, never anything typed or shown on the page.
 
 It also carries a snapshot of the **machine's** state (our own process's memory, free and total system RAM, load average and CPU count), taken at shutdown and again on any crash. This is what separates "your machine ran out of memory" from "Reticle has a bug", which otherwise produce identical-looking failures. No hostname, no username, no paths, no process list.
 

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

@@ -10,15 +10,15 @@ icon: comments
 
 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`       |
+| 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: `idleEndMs`, the idle-end window, or `hud`: `hidden`, `shown`, `removed` (until reload), or a corner (`top-left`, `top-right`, `bottom-left`, `bottom-right`) when the HUD covers a control you must test |
+| `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" }

package/docs/usage.md

@@ -415,7 +415,7 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 | `select` | `{ value }` | `<select>` option |
 | `check` / `uncheck` | n/a | checkbox/radio |
 | `submit` | n/a | submits the element's `<form>` |
-| `press` | `{ key, modifiers? }` | keydown/up (default `Enter`); `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts |
+| `press` | `{ key, modifiers?, holdMs?, keys?, code? }` | keydown/up (default `Enter`); `modifiers`: an array of `Meta` / `Control` / `Shift` / `Alt` for Cmd+K-style shortcuts. With a `ref` the key is dispatched AT that element; with NO ref it is a document key (Escape, Tab, a shortcut) and goes through the real keyboard, so it can actually move focus. `holdMs` keeps the key DOWN for that long (hold-to-confirm, hold-to-reveal). `keys` holds several keys together, pressed in order and released in reverse, and `code` names the physical key: both stay on the in-page dispatcher, which is the only path that can express them |
 | `scrollIntoView` | n/a |  |
 | `upload` | `{ name, content?, type? }` | sets a file on `<input type=file>` |
 | `drag` | `{ toRef }` | pointer-based drag (dnd-kit / rbd) + HTML5 DnD |
@@ -816,7 +816,7 @@ A session starts on the agent's first activity and must reliably end even when t
 - **Agent kills the Reticle server process** (so no push can arrive) → the SDK self-ends the session after it can't reach the bridge for `BRIDGE_LOST_MS` (~15s), showing "lost connection to Reticle."
 - **Slow-but-alive agent** → if it goes quiet long enough to auto-end and then acts again, the session **revives** automatically (an explicit `reticle_session {action:"end"}` stays terminal).
 
-Tune the idle window with `reticle_session({ action: "tune", idleEndMs })`; it updates both the browser timer and the server reaper. The human keeps the panel (with Copy/Export of the run) after any end.
+Tune the idle window with `reticle_session({ action: "tune", idleEndMs })`; it updates both the browser timer and the server reaper. When the HUD covers a control you have to test, `reticle_session({ action: "tune", hud: "top-left" })` moves it (any corner), and `hud: "hidden"`, `"shown"` or `"removed"` (until the page reloads) take it out of the way; the call fails rather than pretending if the page could not apply it. The human keeps the panel (with Copy/Export of the run) after any end.
 
 ### `reticle_session {action:"narrate"}`: show the agent's intent
 
@@ -1053,6 +1053,9 @@ When `inputMode` is `"synthetic"` and the target has hover/enter handlers, the r
 | `provider-declined` / `provider-error` | the CDP provider declined or threw (the latter also sets `warning`) |
 | `not-a-pointer-action` | `fill`/`type`/etc. are always synthetic by design |
 | `synthetic-click-preferred` | a `click`/`dblclick` ran the occlusion-honest synthetic path by default; pass `args:{ native:true }` to force a trusted native click |
+| `synthetic-element-press-preferred` | the `press` named a `ref`/`target`, so it stayed synthetic on purpose: dispatching AT that element reaches it exactly, while a real keyboard sends the key to whatever holds focus. A `press` with NO ref is a document key (Escape, Tab, a modifier shortcut) and does run through the real keyboard when one is configured |
+| `synthetic-multi-key-press-preferred` | the `press` named `keys`: several keys held down **together**, pressed in order and released in reverse. Only the in-page dispatcher implements that sequence; a real keyboard chord cannot express it |
+| `synthetic-key-code-press-preferred` | the `press` named an explicit `code`, which the real driver cannot send: it presses by KEY name, so `{ text: "z", code: "KeyY" }` would strike a different key than the one asked for |
 
 (No `inputModeReason` is set when real input simply isn't configured; synthetic is the expected default there.)
 

package/docs/what-is-recorded.md

@@ -15,7 +15,7 @@ Everything lands in `.reticle/` in your project, and it is yours. Three kinds of
 | --- | --- | --- |
 | **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 |
+| **memory** | what this project has learned across sessions | intents you declared, envelopes of normal behaviour, notes about anchors that drift, the coverage ledger (`coverage.json`), the notes people pinned in the HUD (`notes.json`), and the user's latest request as the agent relayed it (`request.json`, local only) |
 
 `.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.
 
@@ -27,7 +27,7 @@ Everything lands in `.reticle/` in your project, and it is yours. Three kinds of
 
 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.
+Network bodies are **not** captured by default. When you turn body capture on (`captureNetworkBodies: true`, or `VITE_RETICLE_CAPTURE_BODIES=1`), redaction runs **before each body is kept**. Built-in rules mask keys such as `password`, `apiKey` and `authorization`, selected token keys, and high-confidence secret shapes such as JWTs and `sk_live_…` keys. Other credential values can remain under names or in formats those rules do not recognize; add app-specific field names with `redact.keys` and use staging. 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
 
@@ -39,6 +39,14 @@ Once linked, you choose what syncs:
 npx @reticlehq/server config --runs on|off --flows on|off --memory on|off
 ```
 
+`--memory` covers the coverage ledger and the HUD notes as well, and the notes are the words people typed. The user's request (`request.json`, the prompt the agent relayed, redacted) goes to the platform with the runs from a linked project, so the dashboard can show what each run was for; `"shareRequests": false` in `.reticle.json` keeps it on the machine. An unlinked project sends it nowhere, and it is kept out of git either way.
+
+The Harness runs on the platform, so the platform sees what it drives: each step's result goes there so it can choose the next one. A secret field is sent by name only; its value is typed in on your machine.
+
+**Your apps, for the platform's chat.** While a project is linked, the daemon tells the platform every ten seconds, with or without an app open, which apps on this machine have Reticle connected, so the chat can list them and you can pick one instead of typing an address. For each app it sends: a key made from a hash of this machine and the project's folder (the folder path itself never leaves), the project's name (its package name, else its folder's name), the address the app is open at with Reticle's own query parameters removed, the page title, what it is built with (`react`, `vite`, `electron`, …), this machine's name, the Reticle version, and what this daemon can do for the platform. The platform keeps the last report for each app until the project is deleted. Its answer can ask this machine to open one of those apps again, or show you a short notice (for example, to update Reticle), which appears in the daemon's log and on the HUD.
+
+**Drives asked for from the platform's chat.** When someone in your workspace asks the chat to drive one of your apps, the daemon drives it here, on your machine: in the tab you have open, or in a browser of its own, headless or in a window, as the chat asked. It only opens addresses on this machine or apps already open here. On a recent platform, the platform decides each step: it sends Reticle tool calls from a fixed list (reading the page, acting on it, asserting, recording and replaying flows), the daemon runs them in that one tab, and sends back what each returned, which includes what the page showed. On an older platform, the daemon drives and sends back each step's result and how the drive ended. Either way the platform keeps the drive as a check you can open in Runs. Unless the request said not to record, the daemon also sends a picture of the tab it is driving, a JPEG about once a second, so the chat can show the drive live and replay it afterwards. Pictures are kept with that check (at most a few minutes' worth per drive) and deleted with the project. A tab the daemon opened, headless or in a window, can be pictured, with Reticle's own panel left out; so can the window `reticle drive` opened, which is pictured as you see it, panel included. A tab in your own browser sends steps only. Unlinking the project stops all of it.
+
 ## 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.
@@ -49,7 +57,9 @@ 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.
+Telemetry carries no free text. Free text leaves in three ways, each one something you chose: a feedback report (never collected passively; `RETICLE_FEEDBACK=0` disables it), HUD notes on a linked project with `--memory on`, and the user's request from a linked project unless `"shareRequests": false`.
+
+The daemon also fetches a small public file, `https://reticle.sh/hud/notices.v1.json`, for the notices in the HUD's rail. The request carries nothing about you or your project. `RETICLE_TELEMETRY=0` or `DO_NOT_TRACK=1` stops it, and `RETICLE_HUD_NOTICES_URL` points it elsewhere.
 
 ## What `init` writes to your project
 

package/docs/what-is-reticle.mdx

@@ -31,7 +31,9 @@ Reticle sits next to several familiar categories, and it works alongside each of
 
 **Monitoring.** Reticle runs against environments you control (a dev server, a staging or preview deployment) and replays saved flows in CI. The SDK refuses to connect in a production build, so it complements an APM or error tracker rather than watching live traffic.
 
-**Your agent.** Reticle has no model of its own for the verify loop. It gives the agent you already use a way to see the running app. Your agent, your model, your keys. (`explore` can drive a journey for you with a model inside the daemon; see [Autodrive](/autodrive).)
+**Not an accessibility auditor.** `reticle_look { action: "page" }` addresses elements by role and name, which is not the same as auditing contrast, focus order, or screen reader behaviour. Use a dedicated accessibility tool for that.
+
+**Your agent.** Reticle has no model of its own for the verify loop. It gives the agent you already use a way to see the running app. Your agent, your model, your keys. (On a linked project, `explore` has the Reticle Harness drive a journey for you on the Reticle platform; see [Autodrive](/autodrive).)
 
 **The verdict.** A verdict of `unknown` means Reticle drove the app and could not tell. It is deliberately not rounded up to a pass.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,15 +19,15 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "ws": "^8.21.3",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/browser": "3.5.0",
-    "@reticlehq/engine": "3.5.0",
-    "@reticlehq/core": "3.5.0",
+    "@reticlehq/browser": "3.6.0",
+    "@reticlehq/core": "3.6.0",
+    "@reticlehq/engine": "3.6.0",
     "open-verification": "1.0.0",
-    "@reticlehq/init": "3.5.0"
+    "@reticlehq/init": "3.6.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -64,13 +64,9 @@
     "cli"
   ],
   "reticle": {
-    "changelog": "Reticle writes and tightens your regression flows for you: every drive is recorded automatically and replays with no model in the loop. The agent now sees nine tools instead of seventeen, `init` stops at a connected app and proving a flow is a separate first run, and Windows is supported. Upgrading from 2.x: see MIGRATION.md.",
+    "changelog": "Drive your localhost app from the Reticle platform's chat: the daemon of a linked project drives it on your machine, the chat shows it live and keeps it as a check with a replay. The Harness now runs only on the platform, on every plan, and plans, replays and learns each app. A page on SDK 3.1-3.4 is no longer version-skewed, a pressed key sends its keyCode, and a screenshot never carries another tab's pixels. Upgrading from 3.5: see MIGRATION.md.",
     "breakingChanges": [
-      "The default MCP surface is the merged nine. reticle_snapshot/query/inspect/state -> reticle_look { action }, reticle_network/console -> reticle_observe { action }, reticle_sessions/feedback -> reticle_session { action }, reticle_wait_for -> reticle_assert { action: \"wait\" }, reticle_act_sequence -> reticle_act { steps }. Old names redirect when CALLED, but an allowedTools allowlist or an MCP permission rule naming one refuses first -- update those by hand.",
-      "Twelve tools are unreachable on the default surface and have NO redirect: reticle_capabilities, reticle_clock, reticle_context, reticle_flow_replay, reticle_flow_save, reticle_intent, reticle_network_mock, reticle_record, reticle_run, reticle_screenshot, reticle_storage, reticle_visual_diff. The default surface ships no reticle_run hatch. Start the daemon with RETICLE_ADVERTISE_ALL_TOOLS=1 (read once at startup) and call them by name. Saved flows still replay via reticle_verify { action: \"flows\" }.",
-      "`reticle init` no longer drives: it ends at a connected session. --flow, --no-drive and --drive-model now exit non-zero, each naming its replacement. Prove a flow with reticle_verify { action: \"explore\", persona: \"<who does what>\" }, or npx @reticlehq/server verify <url> --explore --persona \"...\". init's exit code now means \"nothing connected\" rather than \"no verdict\". --files-only is unchanged.",
-      "@reticlehq/server now requires Node >=20.11 (was >=20.0.0).",
-      "@reticlehq/server, @reticlehq/init and @reticlehq/test declare license FSL-1.1-ALv2 instead of \"SEE LICENSE IN LICENSE\". The terms are identical; add the SPDX id to a licence allowlist."
+      "reticle_verify { action: \"explore\" } and reticle verify --explore no longer drive on a model key of your own. The Harness decides on the Reticle platform and needs a linked project (npx @reticlehq/server connect); every plan includes Harness credits. ANTHROPIC_API_KEY, OPENAI_API_KEY and JEV_API_KEY are no longer read for driving, RETICLE_HARNESS_DRIVER and RETICLE_HARNESS_MODEL are ignored, and the explore tool's `driver` argument is removed. A secret field's value comes from RETICLE_SECRET_<FIELD> on your machine."
     ]
   },
   "publishConfig": {

package/dist/features/harness/driver.d.ts

@@ -1,50 +0,0 @@
-/**
- * The model binding: the one file in the harness that knows there is a network.
- *
- * Everything about the loop lives in harness.ts against the `ModelDriver` interface, so this file is
- * a translation layer and nothing else. That split is not tidiness — it is what lets the loop be
- * tested against a scripted model with no API key, on every run of the unit gate.
- *
- * It speaks the Messages API over `fetch` rather than through a vendor SDK. The loop is ours (the
- * harness owns the step budget and has to record every call even when a run is cut short), so an SDK
- * would contribute one HTTP POST and a dependency — and this package's dependency list is short on
- * purpose.
- */
-import type { ModelDriver } from './harness.js';
-/**
- * The default driver model.
- *
- * Deliberately not the largest model available. The harness is not reasoning about business logic; it
- * is exploring an interface and stating consequences, and the verdict is produced by the engine
- * reading what it drove. If finding defects required a frontier model HERE, the engine would not be
- * doing its job — so the model tier is also a standing test of the design.
- */
-export declare const DEFAULT_HARNESS_MODEL = "claude-sonnet-5";
-export declare const DEFAULT_HARNESS_BASE_URL = "https://api.anthropic.com";
-/** The one call this file makes. Injected so a test can drive the translation with no network. */
-export type HarnessFetch = (url: string, init: {
-    method: string;
-    headers: Record<string, string>;
-    body: string;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    text(): Promise<string>;
-}>;
-export interface HarnessDriverOptions {
-    apiKey: string;
-    model?: string;
-    baseUrl?: string;
-    /** Injected for tests. Defaults to the platform `fetch`. */
-    fetch?: HarnessFetch;
-}
-/**
- * Read the harness's configuration out of the environment.
- *
- * Returns `undefined` when there is no key, which is the ONLY thing that decides whether the harness
- * is available. Stated as a read rather than a throw because "you have not configured this" is a
- * routine answer a caller offers a way out of, not a failure.
- */
-export declare function harnessOptionsFromEnv(env: Record<string, string | undefined>): HarnessDriverOptions | undefined;
-/** Build a driver backed by the Messages API. */
-export declare function harnessDriver(options: HarnessDriverOptions): ModelDriver;

package/dist/features/harness/driver.js

@@ -1,236 +0,0 @@
-/**
- * The model binding: the one file in the harness that knows there is a network.
- *
- * Everything about the loop lives in harness.ts against the `ModelDriver` interface, so this file is
- * a translation layer and nothing else. That split is not tidiness — it is what lets the loop be
- * tested against a scripted model with no API key, on every run of the unit gate.
- *
- * It speaks the Messages API over `fetch` rather than through a vendor SDK. The loop is ours (the
- * harness owns the step budget and has to record every call even when a run is cut short), so an SDK
- * would contribute one HTTP POST and a dependency — and this package's dependency list is short on
- * purpose.
- */
-import { z } from 'zod';
-import { ReticleEnv, platformCredentialFrom } from '@reticlehq/core';
-/**
- * The default driver model.
- *
- * Deliberately not the largest model available. The harness is not reasoning about business logic; it
- * is exploring an interface and stating consequences, and the verdict is produced by the engine
- * reading what it drove. If finding defects required a frontier model HERE, the engine would not be
- * doing its job — so the model tier is also a standing test of the design.
- */
-export const DEFAULT_HARNESS_MODEL = 'claude-sonnet-5';
-export const DEFAULT_HARNESS_BASE_URL = 'https://api.anthropic.com';
-/** Output cap per turn. A driving turn is a sentence and a tool call, never an essay. */
-const MAX_TOKENS = 4096;
-const ANTHROPIC_VERSION = '2023-06-01';
-const MESSAGES_PATH = '/v1/messages';
-/**
- * How much of one tool result the model is allowed to see.
- *
- * A snapshot of a dense page or a network window on a busy app is far larger than anything the model
- * needs to choose its next click, and a handful of them will fill a context window that then has to
- * be paid for on every subsequent turn. Truncation is announced in the payload rather than silent,
- * because a model that cannot tell it was given a partial reading will reason about it as a complete
- * one — and the tools already have cheaper lenses (`count_only`, `interactive`, `diff`) for exactly
- * this. The full result is in the journal either way; nothing is lost from the record.
- */
-const MAX_RESULT_CHARS = 8000;
-/** The cache breakpoint marker. One object, because it is the same fact in three places. */
-const CACHE_BREAKPOINT = { type: 'ephemeral' };
-/** What one turn of the wire looks like, narrowed at the boundary rather than trusted. */
-const TextBlock = z.object({ type: z.literal('text'), text: z.string() });
-const ToolUseBlock = z.object({
-    type: z.literal('tool_use'),
-    id: z.string(),
-    name: z.string(),
-    input: z.unknown(),
-});
-const OtherBlock = z.object({ type: z.string() }).passthrough();
-const MessageResponse = z.object({
-    content: z.array(z.union([TextBlock, ToolUseBlock, OtherBlock])).default([]),
-    usage: z
-        .object({
-        input_tokens: z.number().default(0),
-        output_tokens: z.number().default(0),
-        cache_read_input_tokens: z.number().nullish(),
-        cache_creation_input_tokens: z.number().nullish(),
-    })
-        .default({ input_tokens: 0, output_tokens: 0 }),
-});
-/**
- * Read the harness's configuration out of the environment.
- *
- * Returns `undefined` when there is no key, which is the ONLY thing that decides whether the harness
- * is available. Stated as a read rather than a throw because "you have not configured this" is a
- * routine answer a caller offers a way out of, not a failure.
- */
-export function harnessOptionsFromEnv(env) {
-    const model = env[ReticleEnv.HARNESS_MODEL];
-    const baseUrl = env[ReticleEnv.HARNESS_BASE_URL];
-    const withOptions = (apiKey, fallbackUrl) => {
-        const url = baseUrl === undefined || 0 === baseUrl.length ? fallbackUrl : baseUrl;
-        return {
-            apiKey,
-            ...(model === undefined || 0 === model.length ? {} : { model }),
-            ...(url === undefined || 0 === url.length ? {} : { baseUrl: url }),
-        };
-    };
-    const apiKey = env[ReticleEnv.HARNESS_KEY];
-    if (apiKey !== undefined && 0 < apiKey.length)
-        return withOptions(apiKey);
-    /**
-     * The platform key, against the platform.
-     *
-     * Reticle's own service answers the Messages API at `/v1/messages` and forwards with ITS provider
-     * key, so a user who has run `reticle link` can drive with a frontier model having never held an
-     * Anthropic key at all. Without this they would be told to set `ANTHROPIC_API_KEY` to a value
-     * beginning `rk_live_` — which works, and reads like a mistake, and is the sort of instruction
-     * people correct on the way past and then cannot explain why nothing runs.
-     *
-     * An explicit `ANTHROPIC_API_KEY` still wins: someone who exported one meant it.
-     */
-    const cloud = platformCredentialFrom(env);
-    if (cloud === undefined)
-        return undefined;
-    return withOptions(cloud.apiKey, cloud.url);
-}
-/** Build a driver backed by the Messages API. */
-export function harnessDriver(options) {
-    const model = options.model ?? DEFAULT_HARNESS_MODEL;
-    const baseUrl = options.baseUrl ?? DEFAULT_HARNESS_BASE_URL;
-    const call = options.fetch ?? ((url, init) => fetch(url, init));
-    return {
-        async turn({ system, tools, history }) {
-            const response = await call(`${baseUrl}${MESSAGES_PATH}`, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    'x-api-key': options.apiKey,
-                    'anthropic-version': ANTHROPIC_VERSION,
-                },
-                body: JSON.stringify({
-                    model,
-                    max_tokens: MAX_TOKENS,
-                    system: [
-                        {
-                            type: 'text',
-                            text: system,
-                            // The system prompt and the tool list are byte-identical on every turn of a drive, and
-                            // a drive is dozens of turns. Caching the prefix is most of the cost of driving an app.
-                            cache_control: CACHE_BREAKPOINT,
-                        },
-                    ],
-                    tools: tools.map(toWireTool),
-                    messages: withConversationCache(history.map(toWireMessage)),
-                }),
-            });
-            const body = await response.text();
-            if (!response.ok) {
-                // Thrown, not returned: the loop calls a model that will not answer a BROKEN drive, and a
-                // broken drive is never reported as clean. Swallowing this would be a verdict about an app
-                // nobody drove.
-                throw new Error(`the model refused the request (HTTP ${String(response.status)}): ${body}`);
-            }
-            const parsed = MessageResponse.parse(JSON.parse(body));
-            const text = parsed.content
-                .filter((block) => 'text' === block.type)
-                .map((block) => block.text)
-                .join('\n');
-            const calls = parsed.content
-                .filter((block) => 'tool_use' === block.type)
-                .map((block) => ({
-                id: block.id,
-                name: block.name,
-                args: isRecord(block.input) ? block.input : {},
-            }));
-            return {
-                text,
-                calls,
-                usage: {
-                    input: parsed.usage.input_tokens,
-                    output: parsed.usage.output_tokens,
-                    // Reported so a missed cache is VISIBLE. A breakpoint that silently stops matching costs
-                    // full price and looks exactly like one that is working from every other angle.
-                    cacheRead: parsed.usage.cache_read_input_tokens ?? 0,
-                    cacheWrite: parsed.usage.cache_creation_input_tokens ?? 0,
-                },
-            };
-        },
-    };
-}
-/**
- * Cache the conversation so far, so the next turn does not pay to re-read it.
- *
- * The API is stateless: every turn re-sends the whole conversation, and a drive is dozens of turns.
- * The system prompt and the tool list are already cached from the first turn — but those are the half
- * that does not grow. The messages are the half that does, and without a breakpoint every byte of
- * them is processed again at full price on every single turn.
- *
- * ONE breakpoint, on the last content block of the most-recently-appended turn. Next turn, this
- * entire conversation is the request's prefix, so it is read at roughly a tenth of the input price
- * rather than processed again. Earlier entries stay valid read points, so the saving accrues as the
- * conversation grows — which is exactly the shape of the cost.
- *
- * Not several breakpoints: four is the hard limit per request and the system block already spends
- * one. More here would buy nothing, because the lookup from a later breakpoint already finds the
- * earlier turn's entry as its prefix.
- *
- * The one thing that would break it is a single turn adding more than twenty content blocks — the
- * lookback window is twenty, and a breakpoint that cannot see the previous entry silently misses. A
- * turn here is one text block, N tool_use blocks and N tool_result blocks, so it would take ten
- * parallel calls in one turn to reach that. Worth knowing; not worth a second breakpoint until it
- * happens, and the cache-read count in `usage` is where it would show up.
- */
-function withConversationCache(messages) {
-    const last = messages[messages.length - 1];
-    if (last === undefined)
-        return [...messages];
-    const content = last.content.map((block, index) => index === last.content.length - 1 ? { ...block, cache_control: CACHE_BREAKPOINT } : block);
-    return [...messages.slice(0, -1), { ...last, content }];
-}
-function toWireTool(tool) {
-    return {
-        name: tool.name,
-        description: tool.description,
-        input_schema: tool.inputSchema,
-    };
-}
-function toWireMessage(entry) {
-    if ('user' === entry.role) {
-        // A text BLOCK rather than a bare string: only a block can carry a cache breakpoint, and the
-        // opening message is the one that would otherwise be a string. It changes the billing and
-        // nothing the model reads.
-        return { role: 'user', content: [{ type: 'text', text: entry.text }] };
-    }
-    if ('assistant' === entry.role) {
-        const blocks = [];
-        if (entry.text.length > 0)
-            blocks.push({ type: 'text', text: entry.text });
-        for (const call of entry.calls) {
-            blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.args });
-        }
-        return { role: 'assistant', content: blocks };
-    }
-    // Every outcome goes back in ONE user message. Splitting tool results across messages teaches the
-    // model to stop asking for calls in parallel, which is most of what makes a drive fast.
-    return {
-        role: 'user',
-        content: entry.outcomes.map((outcome) => ({
-            type: 'tool_result',
-            tool_use_id: outcome.id,
-            content: truncate(JSON.stringify(outcome.result ?? null)),
-            is_error: outcome.isError,
-        })),
-    };
-}
-function truncate(text) {
-    if (text.length <= MAX_RESULT_CHARS)
-        return text;
-    const dropped = String(text.length - MAX_RESULT_CHARS);
-    return `${text.slice(0, MAX_RESULT_CHARS)}\n…[truncated ${dropped} characters — ask for a narrower lens (count_only, interactive, diff, or a path) if you need the rest]`;
-}
-function isRecord(value) {
-    return 'object' === typeof value && null !== value && !Array.isArray(value);
-}