@reticlehq/server 2.0.0

package/dist/tools/act-tools.js

@@ -0,0 +1,327 @@
+/**
+ * Action tools — reticle_act, reticle_act_sequence, reticle_act_and_wait — plus the native-input machinery
+ * (asBox / tryRealInput). Split out of tools.ts to keep that file under the line cap; assembled back
+ * into the tool list there via ...ACT_TOOLS.
+ */
+import { z } from 'zod';
+import { compileActStep, compileSequenceStep } from '../flows/replay.js';
+import { ActionType, ActionWarning, DANGEROUS_ACTION_CONFIRM_ARG, InputMode, InputModeReason, ReticleCommand, isDangerousActionText, } from '@reticlehq/core';
+import { isPointerAction } from '../input/real-input.js';
+import { leanActResult } from './act-view.js';
+import { ReticleTool } from './tool-names.js';
+import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
+import { evaluatePredicate, waitForPredicate, PredicateSchema } from '../events/predicate.js';
+import { healthEnvelope, refuseIfThrottled } from '../session/session-health.js';
+import { pausedShortCircuit, withControl } from '../session/control-envelope.js';
+import { asString, asNumber, asRecord } from './tools-helpers.js';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
+function asBox(value) {
+    const b = asRecord(asRecord(value)['box']);
+    const x = asNumber(b['x']);
+    const y = asNumber(b['y']);
+    const w = asNumber(b['width']);
+    const h = asNumber(b['height']);
+    if (x === undefined || y === undefined || w === undefined || h === undefined)
+        return undefined;
+    if (w <= 0 || h <= 0)
+        return undefined; // zero-area (display:none) ⇒ native click would miss
+    return { x, y, width: w, height: h };
+}
+/** Synthetic outcome with a diagnostic reason (provider configured but native input skipped). */
+function synthetic(reason) {
+    return reason === undefined
+        ? { result: undefined, settled: false }
+        : { result: undefined, settled: false, reason };
+}
+/**
+ * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
+ * `reason` when a provider is configured) whenever the synthetic path should run — no matching
+ * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
+ * flagged with `fellBack`. `result` is defined only on a real success.
+ */
+async function tryRealInput(deps, session, ref, action, args) {
+    const provider = deps.realInput;
+    if (provider === undefined)
+        return synthetic(); // real input not configured — no diagnostic
+    if (!isPointerAction(action))
+        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
+    const inner = asRecord(args['args']);
+    // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
+    // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
+    // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
+    // isTrusted-gated handlers). hover/drag genuinely need native pointer state, so they stay real.
+    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && inner['native'] !== true) {
+        return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
+    }
+    if (!(await provider.isAvailableFor(session.url)))
+        return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    const confirmed = inner[DANGEROUS_ACTION_CONFIRM_ARG] === true;
+    const dangerousDescriptorText = (value) => {
+        const descriptor = asRecord(value);
+        return [
+            asString(descriptor['name']) ?? '',
+            asString(descriptor['text']) ?? '',
+            asString(descriptor['value']) ?? '',
+            asString(descriptor['href']) ?? '',
+            asString(descriptor['formAction']) ?? '',
+            asString(descriptor['formText']) ?? '',
+        ].join(' ');
+    };
+    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) &&
+        !confirmed &&
+        isDangerousActionText(dangerousDescriptorText(inspected))) {
+        throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+    }
+    const box = asBox(inspected);
+    if (box === undefined)
+        return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+    let toBox;
+    if (action === ActionType.DRAG) {
+        const toRef = asString(inner['toRef']);
+        if (toRef === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        const targetInspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
+            ref: toRef,
+        });
+        if (!confirmed &&
+            isDangerousActionText(`${dangerousDescriptorText(inspected)} ${dangerousDescriptorText(targetInspected)}`)) {
+            throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
+        }
+        toBox = asBox(targetInspected);
+        if (toBox === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+    }
+    const performArgs = {};
+    const value = asString(inner['value']);
+    if (value !== undefined)
+        performArgs.value = value;
+    const text = asString(inner['text']);
+    if (text !== undefined)
+        performArgs.text = text;
+    if (toBox !== undefined)
+        performArgs.toBox = toBox;
+    try {
+        const performed = await provider.perform(session.url, action, box, performArgs);
+        if (!performed.performed)
+            return synthetic(InputModeReason.PROVIDER_DECLINED);
+        return { result: { performed: true, center: performed.center, action }, settled: true };
+    }
+    catch {
+        return {
+            result: undefined,
+            settled: false,
+            fellBack: true,
+            reason: InputModeReason.PROVIDER_ERROR,
+        };
+    }
+}
+export const ACT_TOOLS = [
+    {
+        name: ReticleTool.ACT,
+        description: 'Execute one action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Returns immediately with a `since` cursor — observe the reaction with reticle_observe. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
+        inputSchema: {
+            ref: z.string().describe("Element ref from reticle_snapshot or reticle_query (e.g. 'e42')."),
+            action: z
+                .string()
+                .describe('Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView'),
+            args: z
+                .record(z.unknown())
+                .optional()
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click, { confirmDangerous: true } to allow a potentially destructive control.'),
+            refuseWhenThrottled: z
+                .boolean()
+                .optional()
+                .describe('Throw instead of silently sending synthetic events when the tab is throttled/backgrounded. Default: false (synthetic events are still sent).'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            since: z
+                .number()
+                .describe('Cursor — pass to reticle_observe/reticle_wait_for/reticle_assert to scope reaction queries to this act.'),
+            dispatched: z.boolean(),
+            settled: z.boolean().nullable(),
+            inputMode: z.string(),
+            result: z.unknown().optional(),
+            session: z
+                .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
+                .optional(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            // Live-control: refuse to drive the page while the human has paused us (before any work).
+            const paused = pausedShortCircuit(session);
+            if (paused !== undefined)
+                return paused;
+            refuseIfThrottled(session, args['refuseWhenThrottled']);
+            const since = session.elapsed();
+            session.markActCursor(since); // honesty: wait_for/assert default their floor to this cursor
+            const ref = asString(args['ref']) ?? '';
+            const action = asString(args['action']) ?? '';
+            // drive native pointer input when a provider is available; otherwise fall back.
+            const real = await tryRealInput(deps, session, ref, action, args);
+            if (real.result !== undefined) {
+                if (deps.recordings.active().length > 0) {
+                    deps.recordings.capture(compileActStep(args, real.result));
+                }
+                return withControl(session, {
+                    since,
+                    inputMode: InputMode.REAL,
+                    dispatched: true,
+                    settled: real.settled,
+                    settleReason: null,
+                    result: leanActResult(real.result),
+                    ...healthEnvelope(session),
+                });
+            }
+            const result = await session.command(ReticleCommand.ACT, {
+                ref: args['ref'],
+                action: args['action'],
+                args: args['args'] ?? {},
+            });
+            if (!result.ok)
+                throw new Error(result.error ?? 'act failed');
+            if (deps.recordings.active().length > 0) {
+                deps.recordings.capture(compileActStep(args, result.result));
+            }
+            // lift dispatch/settle status to the envelope (a settle timeout is NOT a failure).
+            const r = asRecord(result.result);
+            return withControl(session, {
+                since,
+                inputMode: InputMode.SYNTHETIC,
+                // #2: never a silent real→synthetic fallback — say WHY (unless real input isn't configured).
+                ...(real.reason !== undefined ? { inputModeReason: real.reason } : {}),
+                dispatched: r['dispatched'] ?? true,
+                settled: r['settled'] ?? null,
+                settleReason: r['settleReason'] ?? null,
+                result: leanActResult(result.result),
+                ...(real.fellBack === true ? { warning: ActionWarning.REAL_INPUT_FELL_BACK } : {}),
+                ...healthEnvelope(session),
+            });
+        },
+    },
+    {
+        name: ReticleTool.ACT_SEQUENCE,
+        description: 'Run multiple actions in order (fill -> fill -> submit) in one round-trip. Returns per-step effects[] (see reticle_act).',
+        inputSchema: {
+            steps: z
+                .array(z.record(z.unknown()))
+                .describe('Ordered list of { ref, action, args? } objects. Each step is equivalent to one reticle_act call; put confirmDangerous:true in a destructive step args object.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            since: z.number(),
+            dispatched: z.boolean(),
+            result: z.unknown().optional(),
+            session: z
+                .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
+                .optional(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            // Live-control: refuse to drive the page while the human has paused us (before any work).
+            const paused = pausedShortCircuit(session);
+            if (paused !== undefined)
+                return paused;
+            const since = session.elapsed();
+            session.markActCursor(since); // honesty: a later wait_for/assert floors at this cursor
+            const result = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: args['steps'] });
+            if (!result.ok)
+                throw new Error(result.error ?? 'act_sequence failed');
+            if (deps.recordings.active().length > 0) {
+                deps.recordings.capture(compileSequenceStep(args, result.result));
+            }
+            const r = asRecord(result.result); // per-step settle status lives in result.steps[]
+            return withControl(session, {
+                since,
+                dispatched: r['count'] !== undefined,
+                result: leanActResult(result.result),
+                ...healthEnvelope(session),
+            });
+        },
+    },
+    {
+        name: ReticleTool.ACT_AND_WAIT,
+        description: 'Act on a ref, then wait for a predicate to hold — one hop for the act->observe->assert loop. ' +
+            'Omit `until` to wait for the page to settle (network + DOM idle) — use this instead of a fixed sleep. ' +
+            'Returns { effect } (the action result), { verdict } (predicate pass/evidence/near-miss), ' +
+            '{ trace } (a digest — window_ms + summary counts of what the app did), and { since } (the act ' +
+            'cursor; pass it to reticle_observe for the full per-event timeline when the counts are not enough). ' +
+            'timeout_ms 0 evaluates the predicate once without waiting.',
+        inputSchema: {
+            ref: z.string().describe('Element ref from reticle_snapshot or reticle_query.'),
+            action: z
+                .string()
+                .describe('Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView'),
+            args: z
+                .record(z.unknown())
+                .optional()
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { confirmDangerous: true } for a potentially destructive control.'),
+            until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as reticle_assert). OMIT to wait for the page to SETTLE — network + DOM idle — the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
+            timeout_ms: z
+                .number()
+                .optional()
+                .describe('Maximum wait time in milliseconds. 0 = evaluate once without waiting. Default: 4000.'),
+            refuseWhenThrottled: z
+                .boolean()
+                .optional()
+                .describe('Throw if the tab is throttled. Default: false.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            effect: z
+                .unknown()
+                .describe('The reticle_act result (dispatched, settled, inputMode, etc.).'),
+            verdict: z.object({
+                pass: z.boolean(),
+                evidence: z.unknown().optional(),
+                failureReason: z.string().optional(),
+            }),
+            trace: z
+                .unknown()
+                .describe('Reaction digest: { window_ms, summary } of what the app did (DOM/network/route/console/signal counts). The full per-event timeline is one reticle_observe { since } away.'),
+            since: z
+                .number()
+                .describe('Cursor for this act — pass to reticle_observe/reticle_assert for the full timeline.'),
+            session: z
+                .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
+                .optional(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            // Live-control: refuse to drive the page (no act, no predicate eval) while paused.
+            const paused = pausedShortCircuit(session);
+            if (paused !== undefined)
+                return paused;
+            refuseIfThrottled(session, args['refuseWhenThrottled']);
+            // Omitting `until` waits for the page to settle (idle) — the deterministic default vs a sleep.
+            const until = args['until'] !== undefined
+                ? PredicateSchema.parse(args['until'])
+                : { kind: 'settled' };
+            const timeout = asNumber(args['timeout_ms']) ?? 4000;
+            const since = session.elapsed();
+            session.markActCursor(since);
+            const actResult = await session.command(ReticleCommand.ACT, {
+                ref: args['ref'],
+                action: args['action'],
+                args: args['args'] ?? {},
+            });
+            if (!actResult.ok)
+                throw new Error(actResult.error ?? 'act failed');
+            // Honesty: floor the predicate at this act's cursor so a stale buffered event can't satisfy it.
+            const verdict = timeout > 0
+                ? await waitForPredicate(session, until, timeout, since)
+                : await evaluatePredicate(session, until, since);
+            const trace = summarizeReaction(buildReactionReport(session.eventsSince(since), session.elapsed() - since));
+            return withControl(session, {
+                effect: leanActResult(actResult.result),
+                verdict,
+                trace,
+                since,
+                ...healthEnvelope(session),
+            });
+        },
+    },
+];
+//# sourceMappingURL=act-tools.js.map

package/dist/tools/act-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"act-tools.js","sourceRoot":"","sources":["../../src/tools/act-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/act-view.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Display-only leaning of an act result's `effect` block. The post-action effect carries the
+ * consequence signal (domMutatedWithin, a non-null focusMoved, …) plus many fields that are
+ * almost always at a non-informative default. We drop a field ONLY when it equals its
+ * uninformative default, so absence always means "the boring value" and no real signal is lost:
+ *
+ *   - success defaults — `dispatched`/`targetMatched`/`visible`/`enabled` are `true` on a clean
+ *     action; only their `false` (action missed, hit a hidden/disabled element) carries signal;
+ *   - `false` defaults — `occluded`/`scrolledIntoView`/`defaultPrevented`/`valueChanged`;
+ *   - `null` defaults — `occludedBy`/`focusMoved` (no overlay / no focus change).
+ *
+ * A clean click therefore collapses to its consequence alone (e.g. `{ domMutatedWithin: 8 }`),
+ * matching the leanness of a bare browser-driver click. This runs at the serialization boundary;
+ * internal settle/predicate logic has already consumed the full effect, so trimming the returned
+ * copy is safe.
+ */
+/** Return a copy of an act command result with its `effect` block leaned. Non-objects pass through. */
+export declare function leanActResult(result: unknown): unknown;
+//# sourceMappingURL=act-view.d.ts.map

package/dist/tools/act-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act-view.d.ts","sourceRoot":"","sources":["../../src/tools/act-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoBH,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAMtD"}

package/dist/tools/act-view.js

@@ -0,0 +1,46 @@
+/**
+ * Display-only leaning of an act result's `effect` block. The post-action effect carries the
+ * consequence signal (domMutatedWithin, a non-null focusMoved, …) plus many fields that are
+ * almost always at a non-informative default. We drop a field ONLY when it equals its
+ * uninformative default, so absence always means "the boring value" and no real signal is lost:
+ *
+ *   - success defaults — `dispatched`/`targetMatched`/`visible`/`enabled` are `true` on a clean
+ *     action; only their `false` (action missed, hit a hidden/disabled element) carries signal;
+ *   - `false` defaults — `occluded`/`scrolledIntoView`/`defaultPrevented`/`valueChanged`;
+ *   - `null` defaults — `occludedBy`/`focusMoved` (no overlay / no focus change).
+ *
+ * A clean click therefore collapses to its consequence alone (e.g. `{ domMutatedWithin: 8 }`),
+ * matching the leanness of a bare browser-driver click. This runs at the serialization boundary;
+ * internal settle/predicate logic has already consumed the full effect, so trimming the returned
+ * copy is safe.
+ */
+/** Effect keys whose `true` value is the uninformative success default (a `false` carries signal). */
+const TRUE_NOISE = new Set(['dispatched', 'targetMatched', 'visible', 'enabled']);
+/** Effect keys whose `false` value carries no signal (a `true` does, so it is kept). */
+const FALSE_NOISE = new Set(['occluded', 'scrolledIntoView', 'defaultPrevented', 'valueChanged']);
+/** Effect keys whose `null` value carries no signal (a non-null does, so it is kept). */
+const NULL_NOISE = new Set(['occludedBy', 'focusMoved']);
+function leanEffect(effect) {
+    const out = {};
+    for (const [k, v] of Object.entries(effect)) {
+        if (TRUE_NOISE.has(k) && v === true)
+            continue;
+        if (FALSE_NOISE.has(k) && v === false)
+            continue;
+        if (NULL_NOISE.has(k) && v === null)
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/** Return a copy of an act command result with its `effect` block leaned. Non-objects pass through. */
+export function leanActResult(result) {
+    if (result === null || typeof result !== 'object')
+        return result;
+    const r = result;
+    const effect = r['effect'];
+    if (effect === null || typeof effect !== 'object')
+        return result;
+    return { ...r, effect: leanEffect(effect) };
+}
+//# sourceMappingURL=act-view.js.map

package/dist/tools/act-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"act-view.js","sourceRoot":"","sources":["../../src/tools/act-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,sGAAsG;AACtG,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;AAClF,wFAAwF;AACxF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,cAAc,CAAC,CAAC,CAAC;AAClG,yFAAyF;AACzF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAEzD,SAAS,UAAU,CAAC,MAA+B;IACjD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI;YAAE,SAAS;QAC9C,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,KAAK;YAAE,SAAS;QAChD,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI;YAAE,SAAS;QAC9C,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IACjE,MAAM,CAAC,GAAG,MAAiC,CAAC;IAC5C,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC3B,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IACjE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAiC,CAAC,EAAE,CAAC;AACzE,CAAC"}

package/dist/tools/assert-grade.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Grade a single assertion predicate as a CONSEQUENCE or a mere PRESENCE check — the same distinction
+ * classifyFlowAssertions applies to saved flows, now applied to ad-hoc reticle_assert calls.
+ *
+ * Why (grounded, same sources as flow-classify): a test that only checks an element is present is
+ * weak — a locator healed to the wrong element, or a stale render, can satisfy it while the feature
+ * is broken (Fowler, *Assertion-Free Testing*; Dodds, *Make Your Test Fail*). A signal/net assertion
+ * verifies an observable consequence a wrong element cannot fake. When an agent asserts only
+ * presence, we pass the verdict but nudge it toward a consequence — the success-oracle thesis.
+ *
+ * Pure: no IO, no clock.
+ */
+import type { Predicate } from '../events/predicate.js';
+export declare const PRESENCE_ONLY_ADVICE = "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion \u2014 or allOf it with one \u2014 so green means the feature actually worked.";
+/**
+ * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
+ * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something
+ * other than presence (route/console/settled), is not flagged.
+ */
+export declare function isPresenceOnlyAssertion(predicate: Predicate): boolean;
+//# sourceMappingURL=assert-grade.d.ts.map

package/dist/tools/assert-grade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-grade.d.ts","sourceRoot":"","sources":["../../src/tools/assert-grade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,eAAO,MAAM,oBAAoB,mTACuQ,CAAC;AAuCzS;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAGrE"}

package/dist/tools/assert-grade.js

@@ -0,0 +1,52 @@
+/**
+ * Grade a single assertion predicate as a CONSEQUENCE or a mere PRESENCE check — the same distinction
+ * classifyFlowAssertions applies to saved flows, now applied to ad-hoc reticle_assert calls.
+ *
+ * Why (grounded, same sources as flow-classify): a test that only checks an element is present is
+ * weak — a locator healed to the wrong element, or a stale render, can satisfy it while the feature
+ * is broken (Fowler, *Assertion-Free Testing*; Dodds, *Make Your Test Fail*). A signal/net assertion
+ * verifies an observable consequence a wrong element cannot fake. When an agent asserts only
+ * presence, we pass the verdict but nudge it toward a consequence — the success-oracle thesis.
+ *
+ * Pure: no IO, no clock.
+ */
+export const PRESENCE_ONLY_ADVICE = 'This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion — or allOf it with one — so green means the feature actually worked.';
+function walk(predicate) {
+    switch (predicate.kind) {
+        case 'signal':
+        case 'net':
+        case 'state':
+            // A state assertion verifies the app's own source of truth changed — a consequence a wrong
+            // element or stale render cannot fake (the strongest form of the success-oracle).
+            return { consequence: true, presence: false };
+        case 'element':
+        case 'text':
+            return { consequence: false, presence: true };
+        case 'route':
+        case 'console':
+        case 'animation':
+        case 'settled':
+            // Observable but not the weak presence pattern we nudge — neither flags the advice.
+            return { consequence: false, presence: false };
+        case 'allOf':
+        case 'anyOf': {
+            const subs = predicate.predicates.map(walk);
+            return {
+                consequence: subs.some((s) => s.consequence),
+                presence: subs.some((s) => s.presence),
+            };
+        }
+        case 'not':
+            return walk(predicate.predicate);
+    }
+}
+/**
+ * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
+ * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something
+ * other than presence (route/console/settled), is not flagged.
+ */
+export function isPresenceOnlyAssertion(predicate) {
+    const kinds = walk(predicate);
+    return kinds.presence && !kinds.consequence;
+}
+//# sourceMappingURL=assert-grade.js.map

package/dist/tools/assert-grade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-grade.js","sourceRoot":"","sources":["../../src/tools/assert-grade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,sSAAsS,CAAC;AASzS,SAAS,IAAI,CAAC,SAAoB;IAChC,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,QAAQ,CAAC;QACd,KAAK,KAAK,CAAC;QACX,KAAK,OAAO;YACV,2FAA2F;YAC3F,kFAAkF;YAClF,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QAChD,KAAK,SAAS,CAAC;QACf,KAAK,MAAM;YACT,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAChD,KAAK,OAAO,CAAC;QACb,KAAK,SAAS,CAAC;QACf,KAAK,WAAW,CAAC;QACjB,KAAK,SAAS;YACZ,oFAAoF;YACpF,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QACjD,KAAK,OAAO,CAAC;QACb,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC5C,OAAO;gBACL,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;gBAC5C,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;aACvC,CAAC;QACJ,CAAC;QACD,KAAK,KAAK;YACR,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAoB;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;AAC9C,CAAC"}

package/dist/tools/browser-tools.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDef } from './tools.js';
+export declare const BROWSER_TOOLS: ToolDef[];
+//# sourceMappingURL=browser-tools.d.ts.map

package/dist/tools/browser-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-tools.d.ts","sourceRoot":"","sources":["../../src/tools/browser-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,aAAa,EAAE,OAAO,EAmDlC,CAAC"}

package/dist/tools/browser-tools.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { ReticleCommand } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { asString } from './tools-helpers.js';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+export const BROWSER_TOOLS = [
+    {
+        name: ReticleTool.NAVIGATE,
+        description: 'Navigate the connected browser tab to a URL. The SDK reconnects automatically after the page loads. Use reticle_sessions to confirm the new tab is connected before acting.',
+        inputSchema: {
+            url: z.string().describe('The URL to navigate to.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            url: z.string().optional(),
+            reason: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const url = asString(args['url']);
+            if (url === undefined || url.length === 0)
+                return { ok: false, reason: 'url required' };
+            const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
+            return {
+                ok: result.ok === true,
+                ...(typeof result.url === 'string' ? { url: result.url } : {}),
+                ...(typeof result.reason === 'string' ? { reason: result.reason } : {}),
+            };
+        },
+    },
+    {
+        name: ReticleTool.REFRESH,
+        description: 'Reload the connected browser tab. Pass { hard: true } to bypass the browser cache (equivalent to Cmd+Shift+R). The SDK reconnects automatically after the reload.',
+        inputSchema: {
+            hard: z
+                .boolean()
+                .optional()
+                .describe('Set true to bypass the browser cache. Default: false (normal reload).'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            ok: z.boolean(),
+        },
+        handler: async (deps, args) => {
+            await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
+                hard: args['hard'] === true,
+            });
+            return { ok: true };
+        },
+    },
+];
+//# sourceMappingURL=browser-tools.js.map

package/dist/tools/browser-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-tools.js","sourceRoot":"","sources":["../../src/tools/browser-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/D,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC;QACE,IAAI,EAAE,WAAW,CAAC,QAAQ;QAC1B,WAAW,EACT,6KAA6K;QAC/K,WAAW,EAAE;YACX,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;YACnD,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;YACf,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC9B;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAClC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;YACxF,MAAM,MAAM,GAAG,CAAC,MAAM,cAAc,CAClC,IAAI,EACJ,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAC3B,cAAc,CAAC,QAAQ,EACvB,EAAE,GAAG,EAAE,CACR,CAAsD,CAAC;YACxD,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE,KAAK,IAAI;gBACtB,GAAG,CAAC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9D,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE,CAAC;QACJ,CAAC;KACF;IACD;QACE,IAAI,EAAE,WAAW,CAAC,OAAO;QACzB,WAAW,EACT,mKAAmK;QACrK,WAAW,EAAE;YACX,IAAI,EAAE,CAAC;iBACJ,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CAAC,uEAAuE,CAAC;YACpF,GAAG,cAAc;SAClB;QACD,YAAY,EAAE;YACZ,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;SAChB;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5B,MAAM,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE;gBAC9E,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI;aAC5B,CAAC,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACtB,CAAC;KACF;CACF,CAAC"}

package/dist/tools/contract-tools.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDef } from './tools.js';
+/**
+ * The capability-contract tools. `reticle_capabilities` reads the live session, or the
+ * git-checked `.reticle/contract.json` when `{ fromDisk:true }`; `reticle_contract_save` persists the
+ * live registry to that file (pretty-printed, stable key order — diffable in PRs).
+ */
+export declare const CONTRACT_TOOLS: ToolDef[];
+//# sourceMappingURL=contract-tools.d.ts.map

package/dist/tools/contract-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-tools.d.ts","sourceRoot":"","sources":["../../src/tools/contract-tools.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,EA+DnC,CAAC"}