@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/version/sdk-fix.js

@@ -0,0 +1,127 @@
+/**
+ * The project-aware SDK remedy for version skew (#618).
+ *
+ * `sdkFix` in version-skew.ts is the no-project fallback: it names `@reticlehq/browser` and npm,
+ * because those answers are never actively wrong. When a project directory IS in hand, name the
+ * packages actually in package.json and the manager the lockfile implies.
+ *
+ * Does not import `init/`. The library path must never reach the installer
+ * (`library-path-boundary.test.ts`); `reticleDepsOf` lives in `update/` for that reason, and the
+ * lockfile → manager map is the same evidence `detectPackageManager` reads, kept here so a HELLO
+ * does not load the install plan.
+ */
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { reticleDepsOf } from '../../memory/project/reticle-deps.js';
+/** Lockfile / marker → manager, same evidence `init/detect.ts` uses. */
+export const PackageManagerName = {
+    PNPM: 'pnpm',
+    YARN: 'yarn',
+    BUN: 'bun',
+    NPM: 'npm',
+};
+/** Same package a Vue/Nuxt install gets — never the React kit. */
+const FRAMEWORK_NEUTRAL_SDK = '@reticlehq/browser';
+const PACKAGE_JSON = 'package.json';
+const NODE_MODULES = 'node_modules';
+const LOCKFILE_NAMES = ['pnpm-lock.yaml', 'yarn.lock', 'bun.lockb', 'bun.lock'];
+/** Markers each manager leaves inside `node_modules` — stronger than an uncommitted lockfile. */
+const NODE_MODULES_MARKERS = [
+    ['.modules.yaml', PackageManagerName.PNPM],
+    ['.yarn-state.yml', PackageManagerName.YARN],
+    ['.package-lock.json', PackageManagerName.NPM],
+];
+const INSTALL_FLAGS = {
+    [PackageManagerName.PNPM]: ['add', '-D'],
+    [PackageManagerName.YARN]: ['add', '-D'],
+    [PackageManagerName.BUN]: ['add', '-d'],
+    [PackageManagerName.NPM]: ['i', '-D'],
+};
+function packagesFor(ctx) {
+    if (ctx?.packages !== undefined && 0 !== ctx.packages.length)
+        return ctx.packages;
+    return [FRAMEWORK_NEUTRAL_SDK];
+}
+function managerOf(lockfiles, nodeModulesMarkers) {
+    if (lockfiles.has('pnpm-lock.yaml'))
+        return PackageManagerName.PNPM;
+    if (lockfiles.has('yarn.lock'))
+        return PackageManagerName.YARN;
+    if (lockfiles.has('bun.lockb') || lockfiles.has('bun.lock'))
+        return PackageManagerName.BUN;
+    for (const [name, pm] of NODE_MODULES_MARKERS) {
+        if (nodeModulesMarkers.has(name))
+            return pm;
+    }
+    return PackageManagerName.NPM;
+}
+function installLine(pm, pkgs) {
+    return `${pm} ${[...INSTALL_FLAGS[pm], ...pkgs].join(' ')}`;
+}
+function restartClause() {
+    return ('or run `reticle update`, then restart their dev server so the page reloads with it. The ' +
+        'restart is not optional: a bundler keeps serving the pre-bundled copy it already has, so an ' +
+        'upgrade can look applied — matching versions in `npm ls` — while the page runs the old module.');
+}
+/**
+ * The one sentence telling the human how to bring the page's SDK in line with this daemon.
+ *
+ * No context → the framework-neutral sensor and npm, never the React kit. Packages from
+ * package.json win when present. When the project has none of ours yet, the sensor is named
+ * rather than `@reticlehq/react` — that is the Vue/Nuxt failure.
+ */
+export function resolveSdkFix(daemonVersion, ctx) {
+    const pm = ctx?.packageManager ?? PackageManagerName.NPM;
+    const pinned = packagesFor(ctx).map((name) => `${name}@${daemonVersion}`);
+    return `Tell the human to install the matching SDK (\`${installLine(pm, pinned)}\`) ${restartClause()}`;
+}
+/**
+ * Read the context `resolveSdkFix` needs off a parsed manifest and the lockfiles/markers present.
+ *
+ * Undefined when there is no manifest to interpret — the caller then uses the no-project fallback.
+ * Pure: no filesystem.
+ */
+export function sdkFixContextOf(pkgJson, lockfiles, nodeModulesMarkers = new Set()) {
+    if ('object' !== typeof pkgJson || null === pkgJson)
+        return undefined;
+    return {
+        packages: reticleDepsOf(pkgJson),
+        packageManager: managerOf(lockfiles, nodeModulesMarkers),
+    };
+}
+/** Reads a file, or undefined if it is not there / not readable. */
+function readTextFile(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseJson(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function present(directory, names, read, extra = '') {
+    const found = new Set();
+    for (const name of names) {
+        if (read(join(directory, extra, name)) !== undefined)
+            found.add(name);
+    }
+    return found;
+}
+/**
+ * The remedy for the project in `directory`, or the no-project fallback when it cannot be read.
+ *
+ * `read` is injected so the decision is testable without a filesystem; the daemon uses the default.
+ */
+export function sdkFixForDirectory(daemonVersion, directory, read = readTextFile) {
+    const ctx = sdkFixContextOf(parseJson(read(join(directory, PACKAGE_JSON))), present(directory, LOCKFILE_NAMES, read), present(directory, NODE_MODULES_MARKERS.map(([name]) => name), read, NODE_MODULES));
+    return resolveSdkFix(daemonVersion, ctx);
+}

package/dist/command/version/version-nudge.js

@@ -0,0 +1,61 @@
+/**
+ * Getting skew in front of the AGENT, on whatever tool it happens to be calling.
+ *
+ * Every check built before this reported into a place nobody looks: SDK skew landed in
+ * `reticle_sessions.versionSkew`, which an agent driving a flow never calls, and daemon skew went to
+ * a CLI log line no agent reads. So an agent could work an entire session against a mismatched pair,
+ * watch tools behave oddly, and never be told the one fact that explains it.
+ *
+ * This is the delivery channel — the same one the update nudge uses, for the same reason: an
+ * out-of-date install is worth mentioning whatever the agent is doing. It rides out on the next tool
+ * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
+ * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
+ */
+import { EnvelopeKey } from '../../surface/tools/tool-kit.js';
+/** Pending per pair — the SDK and the daemon are different upgrades and each is worth saying once. */
+const pending = new Map();
+/** The last message delivered for each pair, so the same skew is never repeated. */
+const delivered = new Map();
+/**
+ * Record a skew for delivery. Re-arms only when the message DIFFERS from the one already delivered:
+ * a second tab on a third version is news; the same tab reconnecting is not.
+ */
+export function noteVersionSkew(pair, action) {
+    if (delivered.get(pair) === action)
+        return;
+    pending.set(pair, action);
+}
+/** The next undelivered skew, once. */
+export function takeVersionSkew() {
+    for (const [pair, action] of pending) {
+        pending.delete(pair);
+        delivered.set(pair, action);
+        return { pair, action };
+    }
+    return undefined;
+}
+/**
+ * Splice pending skew onto a tool-error payload.
+ *
+ * Successful calls already carry `version_skew` via `runTool`. Thrown errors never reached that
+ * splice — they became a Playwright string plus `FEEDBACK_ASK`, so a caller debugs a CDP timeout
+ * instead of the mismatched pair that caused it (#618). When the error was unrecognized, the
+ * feedback ask is replaced: the skew IS the next move, and inviting a bug report about it is
+ * backwards. A recognized recovery is kept; the envelope still rides along.
+ */
+export function takeVersionSkewOnto(payload) {
+    const skew = takeVersionSkew();
+    if (skew === undefined)
+        return payload;
+    const { feedback, ...rest } = payload;
+    return {
+        ...rest,
+        ...(feedback !== undefined && rest.recovery === undefined ? { recovery: skew.action } : {}),
+        [EnvelopeKey.VERSION_SKEW]: skew,
+    };
+}
+/** Tests only — drop the module state so each case starts clean. */
+export function resetVersionSkew() {
+    pending.clear();
+    delivered.clear();
+}

package/dist/command/version/version-skew.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Does this peer speak our contract? The daemon is the only thing that asks.
+ *
+ * Reticle is three separately-installed pieces — the SDK in the page, this daemon, and the MCP
+ * server the agent spawns — upgraded independently and therefore drifting constantly. Each pair
+ * fails the same silent way: `protocolVersion` still matches, the connection succeeds, and only
+ * BEHAVIOUR disagrees — a bare `-32000`, with nothing on either side naming a version.
+ *
+ * Two decisions shape this file.
+ *
+ * The daemon is the SINGLE judge. Every piece announces itself at a connect it already makes — the
+ * SDK in HELLO, the CLI and the MCP server over /status — and comparing happens here, once. Three
+ * independent pairwise checks would be three copies to keep in step and three separate complaints
+ * about one upgrade; a table in one place can say what is actually true: which pieces disagree, and
+ * which one is behind.
+ *
+ * The signal is the CONTRACT FINGERPRINT, not the version. Version equality is wrong in both
+ * directions: it fires on a patch release where nothing on the wire changed — so every release
+ * makes every un-upgraded app cry wolf, and the warning becomes noise — and it cannot fire at all for two
+ * different BUILDS of one version number, which is exactly what a stale daemon and a cached npx
+ * install are. The fingerprint is derived from core's wire vocabulary, so it moves when a name on
+ * the wire changes and stays put when internals do. Versions still ride along, because they are what
+ * a human acts on.
+ */
+/** Which pair disagreed. Named so the nudge can report each independently. */
+export declare const SkewPair: {
+    /** The SDK in the page vs this daemon. */
+    readonly SDK: "sdk";
+    /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
+    readonly DAEMON: "daemon";
+};
+export type SkewPair = (typeof SkewPair)[keyof typeof SkewPair];
+/** What a piece says about itself when it connects. */
+export interface PeerIdentity {
+    /** Human-readable subject for the message: "the page", "the daemon on this port". */
+    what: string;
+    /** Package version, when the peer supplied one. Undefined on a hand-wired connect. */
+    version: string | undefined;
+    /** Contract fingerprint. Undefined means the peer predates the field — itself evidence of age. */
+    contract: string | undefined;
+    /**
+     * The vocabulary this peer actually speaks, when it says so.
+     *
+     * Present, this is compared name by name: a peer declaring a subset is compatible. Absent, the
+     * fingerprint is all there is and the comparison stays a fingerprint match, which is what an
+     * SDK that predates `contractParts` relies on.
+     */
+    contractParts?: ContractParts | undefined;
+    /** What the human runs to bring this piece into line. */
+    fix: string;
+}
+/** The names one side of a connection speaks. */
+export interface ContractParts {
+    readonly commands: readonly string[];
+    readonly events: readonly string[];
+    readonly actions: readonly string[];
+}
+/** Everything a build knows about itself. */
+interface SelfIdentity {
+    version: string;
+    contract: string;
+    contractParts?: ContractParts | undefined;
+}
+/**
+ * The one sentence to tell the agent, or undefined when the pair agrees.
+ *
+ * Silent when the fingerprints MATCH, whatever the versions say — that is the point: a patch bump
+ * that changed no wire name is not skew, and warning about it is how a real warning gets ignored.
+ *
+ * When BOTH sides say which names they speak, the comparison is structural instead: a peer that
+ * declares a subset of what we know is compatible and silent, however different the fingerprints
+ * are. That is the only relationship a third-party implementation will ever have with us, and under
+ * a hash comparison it was reported as skewed on every call, forever, with a fix that would not have
+ * fixed anything.
+ *
+ * A peer with no fingerprint is treated as skewed ONLY when its version also differs from ours: the
+ * field is absent exactly on builds that predate it, so "no fingerprint AND a different version" is
+ * a build provably older than this daemon. With neither signal there is nothing to go on, and
+ * inventing a warning would be as dishonest as staying silent about a real one.
+ */
+export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): string | undefined;
+/**
+ * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
+ *
+ * Names the framework-neutral sensor and plain npm, because those are the answers that are never
+ * actively wrong. When a project directory IS available, `resolveSdkFix` / `sdkFixForDirectory`
+ * in sdk-fix.ts read the real packages and package manager — this used to hardcode
+ * `@reticlehq/react` and told Vue projects to install a React package (#618).
+ */
+export declare function sdkFix(daemonVersion: string): string;
+/**
+ * The fix line for another Reticle process that disagrees with the daemon it attached to.
+ *
+ * Branches on DIRECTION, which the old unconditional `reticle stop` did not (#618). Restarting the
+ * daemon converges the pair only when the daemon is the OLDER half. When the daemon is newer — the
+ * common case, because the MCP registration is deliberately unpinned and so resolves fresh while a
+ * long-lived daemon does not — `reticle stop` starts another newer daemon and leaves the same two
+ * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
+ * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
+ *
+ * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
+ * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
+ * and the advice depends on which piece is behind, not on who noticed.
+ */
+export declare function daemonFix(daemonVersion: string | undefined, agentVersion: string | undefined): string;
+/** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
+export declare function isPlaywrightClosedError(error: unknown): boolean;
+/**
+ * Replace a closed-target throw with the session's skew sentence when we already know the pair is
+ * mismatched. Undefined when there is no skew to name, or the throw is something else.
+ */
+export declare function rewriteClosedAsSkew(error: unknown, skew: string | undefined): Error | undefined;
+export {};

package/dist/command/version/version-skew.js

@@ -0,0 +1,192 @@
+/**
+ * Does this peer speak our contract? The daemon is the only thing that asks.
+ *
+ * Reticle is three separately-installed pieces — the SDK in the page, this daemon, and the MCP
+ * server the agent spawns — upgraded independently and therefore drifting constantly. Each pair
+ * fails the same silent way: `protocolVersion` still matches, the connection succeeds, and only
+ * BEHAVIOUR disagrees — a bare `-32000`, with nothing on either side naming a version.
+ *
+ * Two decisions shape this file.
+ *
+ * The daemon is the SINGLE judge. Every piece announces itself at a connect it already makes — the
+ * SDK in HELLO, the CLI and the MCP server over /status — and comparing happens here, once. Three
+ * independent pairwise checks would be three copies to keep in step and three separate complaints
+ * about one upgrade; a table in one place can say what is actually true: which pieces disagree, and
+ * which one is behind.
+ *
+ * The signal is the CONTRACT FINGERPRINT, not the version. Version equality is wrong in both
+ * directions: it fires on a patch release where nothing on the wire changed — so every release
+ * makes every un-upgraded app cry wolf, and the warning becomes noise — and it cannot fire at all for two
+ * different BUILDS of one version number, which is exactly what a stale daemon and a cached npx
+ * install are. The fingerprint is derived from core's wire vocabulary, so it moves when a name on
+ * the wire changes and stays put when internals do. Versions still ride along, because they are what
+ * a human acts on.
+ */
+import { resolveSdkFix } from './sdk-fix.js';
+/** Which pair disagreed. Named so the nudge can report each independently. */
+export const SkewPair = {
+    /** The SDK in the page vs this daemon. */
+    SDK: 'sdk',
+    /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
+    DAEMON: 'daemon',
+};
+/**
+ * Names the peer speaks that we have never heard of.
+ *
+ * This is the whole structural comparison, and the asymmetry is deliberate. A peer speaking FEWER
+ * names than us is implementing part of the contract, which is the correct thing for anything that
+ * is not a browser to do -- there is no touch equivalent of a console error. A peer speaking a name
+ * we do not know was built against a contract this daemon does not have, and that is a genuine
+ * mismatch: one of us is stale, and tools will behave in ways neither side reports.
+ */
+function namesWeDoNotKnow(peer, self) {
+    const unknown = [
+        ...peer.commands.filter((name) => !self.commands.includes(name)),
+        ...peer.events.filter((name) => !self.events.includes(name)),
+        ...peer.actions.filter((name) => !self.actions.includes(name)),
+    ];
+    return [...new Set(unknown)].sort();
+}
+function versionPhrase(peer, self) {
+    return peer.version === undefined
+        ? `${peer.what} is on an unknown version; this daemon is ${self.version}`
+        : `${peer.what} is ${peer.version}; this daemon is ${self.version}`;
+}
+/**
+ * The one sentence to tell the agent, or undefined when the pair agrees.
+ *
+ * Silent when the fingerprints MATCH, whatever the versions say — that is the point: a patch bump
+ * that changed no wire name is not skew, and warning about it is how a real warning gets ignored.
+ *
+ * When BOTH sides say which names they speak, the comparison is structural instead: a peer that
+ * declares a subset of what we know is compatible and silent, however different the fingerprints
+ * are. That is the only relationship a third-party implementation will ever have with us, and under
+ * a hash comparison it was reported as skewed on every call, forever, with a fix that would not have
+ * fixed anything.
+ *
+ * A peer with no fingerprint is treated as skewed ONLY when its version also differs from ours: the
+ * field is absent exactly on builds that predate it, so "no fingerprint AND a different version" is
+ * a build provably older than this daemon. With neither signal there is nothing to go on, and
+ * inventing a warning would be as dishonest as staying silent about a real one.
+ */
+export function describeSkew(peer, self) {
+    if (peer.contract !== undefined && peer.contract === self.contract)
+        return undefined;
+    // Both sides said which names they speak, so compare the names rather than a hash over them.
+    if (peer.contractParts !== undefined && self.contractParts !== undefined) {
+        const unknown = namesWeDoNotKnow(peer.contractParts, self.contractParts);
+        if (0 === unknown.length)
+            return undefined;
+        return (`version skew: ${versionPhrase(peer, self)}, and ${peer.what} speaks names this daemon does ` +
+            `not know (${unknown.join(', ')}) — so it was built against a newer contract than this one. ` +
+            `Tools will behave in ways neither side reports. ${peer.fix}`);
+    }
+    if (peer.contract === undefined) {
+        if (peer.version === undefined || peer.version === self.version)
+            return undefined;
+        return (`version skew: ${versionPhrase(peer, self)}, and it is too old to report which wire contract ` +
+            `it speaks. They connect anyway and then disagree about behaviour, which usually surfaces as ` +
+            `a bare -32000 with nothing naming a version. ${peer.fix}`);
+    }
+    /*
+     * A fingerprint alone cannot tell an ADDITION from a RENAME, so this sentence must not claim it can.
+     *
+     * It used to end "so this is a real mismatch, not a harmless patch difference. Tools will behave in
+     * ways neither side reports." Both halves are assertions the evidence does not support: the hash is
+     * a hash. `CONTRACT_PARTS` exists so the branch above can say something stronger when the peer is
+     * new enough to list what it speaks — and a peer that reaches HERE is, by definition, one that
+     * predates that list.
+     *
+     * Which is exactly the 2.x page meeting a 3.x daemon. This release added `scroll`, `tap` and `zoom`
+     * to the actions, and nothing else the page needs; every upgrading user with a pinned SDK would
+     * have been told their tools were misbehaving, about a change that breaks nothing.
+     */
+    return (`version skew: ${versionPhrase(peer, self)}, and they were built against different wire ` +
+        `contracts (${peer.contract} vs ${self.contract}). ${peer.what} is too old to say WHICH names ` +
+        `it speaks, so this cannot tell an added name — which breaks nothing — from a renamed one, ` +
+        `which breaks the call that uses it. Update it and the question goes away. ${peer.fix}`);
+}
+/**
+ * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
+ *
+ * Names the framework-neutral sensor and plain npm, because those are the answers that are never
+ * actively wrong. When a project directory IS available, `resolveSdkFix` / `sdkFixForDirectory`
+ * in sdk-fix.ts read the real packages and package manager — this used to hardcode
+ * `@reticlehq/react` and told Vue projects to install a React package (#618).
+ */
+export function sdkFix(daemonVersion) {
+    return resolveSdkFix(daemonVersion);
+}
+/**
+ * Compare two of our own version strings. Numeric dotted compare, prerelease tags ignored: both
+ * sides are Reticle package versions, so this never sees a range or build metadata. Undefined when
+ * either side does not parse, so the caller can decline to guess a direction.
+ */
+function compareVersions(a, b) {
+    const parts = (v) => {
+        const head = v.split('-')[0];
+        if (head === undefined)
+            return undefined;
+        const nums = head.split('.').map((n) => parseInt(n, 10));
+        return nums.some(isNaN) ? undefined : nums;
+    };
+    if (a === undefined)
+        return undefined;
+    const left = parts(a);
+    const right = parts(b);
+    if (left === undefined || right === undefined)
+        return undefined;
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (0 !== diff)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * The fix line for another Reticle process that disagrees with the daemon it attached to.
+ *
+ * Branches on DIRECTION, which the old unconditional `reticle stop` did not (#618). Restarting the
+ * daemon converges the pair only when the daemon is the OLDER half. When the daemon is newer — the
+ * common case, because the MCP registration is deliberately unpinned and so resolves fresh while a
+ * long-lived daemon does not — `reticle stop` starts another newer daemon and leaves the same two
+ * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
+ * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
+ *
+ * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
+ * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
+ * and the advice depends on which piece is behind, not on who noticed.
+ */
+export function daemonFix(daemonVersion, agentVersion) {
+    const order = agentVersion === undefined ? undefined : compareVersions(daemonVersion, agentVersion);
+    if (order !== undefined && order > 0) {
+        return ('The daemon is NEWER than this process, so `reticle stop` will not converge them — it would ' +
+            'replace it with another newer daemon and leave the same mismatch. Tell the human to restart ' +
+            'the agent so it spawns a current MCP server (or update the package it spawns), then retry.');
+    }
+    return ('A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
+        '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
+        'it (other agents on that daemon will need to reconnect).');
+}
+/**
+ * Playwright wording when a CDP call cannot bind to the page.
+ *
+ * Under SDK/daemon version skew this text is a LIE: the page is still connected (DOM tools work),
+ * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
+ * (#688). Matched only so we can replace it with the skew sentence already on the session.
+ */
+const PLAYWRIGHT_CLOSED_ERROR = /target (?:page|context|browser) has been closed|browser has been closed|browser has disconnected/i;
+/** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
+export function isPlaywrightClosedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return PLAYWRIGHT_CLOSED_ERROR.test(message);
+}
+/**
+ * Replace a closed-target throw with the session's skew sentence when we already know the pair is
+ * mismatched. Undefined when there is no skew to name, or the throw is something else.
+ */
+export function rewriteClosedAsSkew(error, skew) {
+    if (skew === undefined || !isPlaywrightClosedError(error))
+        return undefined;
+    return new Error(skew);
+}

package/dist/features/crawl/crawl-tools.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
+ * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —
+ * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
+ */
+export declare const CRAWL_TOOLS: ToolDef[];

package/dist/features/crawl/crawl-tools.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { projectForRoot } from '../../memory/project/project-for-root.js';
+import { ReticleTool } from '@reticlehq/core';
+import { asNumber, asString } from '@reticlehq/core';
+import { stepCountSchema, timeoutMsSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { crawl } from './crawl.js';
+import { routeFromUrl, routesFromEvents } from '../../memory/project/learned-routes.js';
+const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
+ * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —
+ * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
+ */
+export const CRAWL_TOOLS = [
+    {
+        name: ReticleTool.CRAWL,
+        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script. Two classes: single-channel faults (console errors, failed requests ≥400, DEAD controls that dispatched but did nothing) and CONTRADICTIONS — two channels disagreeing about the same click, e.g. the UI advanced while its write failed, a success signal fired over a failed request, a write succeeded and nothing changed, the same write fired twice, or the UI moved on over an in-flight request. Contradictions are the false greens a human cannot see, because a human watches one channel (the screen) and it looks correct. DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
+        inputSchema: {
+            maxSteps: stepCountSchema
+                .optional()
+                .describe('Maximum number of controls to click. Default: 25.'),
+            settleMs: timeoutMsSchema
+                .optional()
+                .describe('Milliseconds to wait after each click for the app to react. Default: 500.'),
+            scope: z
+                .string()
+                .optional()
+                .describe('CSS selector or element ref to restrict crawling to a subtree.'),
+            confirmDangerous: z
+                .boolean()
+                .optional()
+                .describe('Set true to allow controls classified as destructive. Default false; those controls are blocked by the browser.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+        },
+        // An UNDECLARED field is stripped from structuredContent, so a schema-aware client never sees it
+        // even though the handler returns it. Everything crawl produces has to be listed here or it is
+        // silently lost — which is how the source pointer and the visited list were being dropped.
+        outputSchema: {
+            interactiveFound: z.number(),
+            stepsRun: z.number(),
+            // Present only when nothing was clicked, saying WHICH zero this is — an empty page, a step
+            // budget of zero, or controls found and none driven. A bare zero was unactionable.
+            note: z.string().optional(),
+            anomalies: z.array(z.object({
+                kind: z.string(),
+                ref: z.string(),
+                desc: z.string(),
+                detail: z.string().optional(),
+                source: z
+                    .string()
+                    .optional()
+                    .describe('Where the fault is written, as `file:line`; console errors prefer their own stack and fall back to the clicked control.'),
+            })),
+            counts: z.record(z.number()),
+            visited: z.array(z.string()).describe('The controls actually clicked, in order.'),
+            coverageNote: z
+                .string()
+                .optional()
+                .describe('Present only when the page exceeded one snapshot, so controls past the cap were never listed. When present, a zero-anomaly result does NOT mean the app is clean.'),
+            truncated: z.boolean(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = session.elapsed();
+            const initialRoute = routeFromUrl(session.url);
+            const maxSteps = asNumber(args['maxSteps']);
+            const settleMs = asNumber(args['settleMs']);
+            const scope = asString(args['scope']);
+            const opts = {
+                ...(maxSteps !== undefined ? { maxSteps } : {}),
+                ...(settleMs !== undefined ? { settleMs } : {}),
+                ...(scope !== undefined ? { scope } : {}),
+                ...(true === args['confirmDangerous'] ? { confirmDangerous: true } : {}),
+            };
+            const report = await crawl(session, opts, nodeSleep);
+            const routes = [
+                ...(initialRoute === undefined ? [] : [initialRoute]),
+                ...routesFromEvents(session.eventsSince(since)),
+            ];
+            if (routes.length > 0)
+                await projectForRoot(deps, sessionRoot(deps, session.id)).recordRoutes(routes);
+            return report;
+        },
+    },
+];