@reticlehq/server 2.14.0 → 3.2.0

package/dist/input/network-mock-tools.js

@@ -1,124 +0,0 @@
-import { z } from 'zod';
-import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
-import { ReticleTool } from '../tools/tool-names.js';
-import { sessionIdShape } from '../tools/tool-kit.js';
-import { delayMsSchema, httpStatusSchema } from '../tools/numeric-bounds.js';
-import { asString } from '../tools/tools-helpers.js';
-function mockProvider(deps) {
-    const p = deps.realInput;
-    return p !== undefined && 'function' === typeof p.setMocks ? p : undefined;
-}
-const ruleShape = z.object({
-    urlContains: z
-        .string()
-        .min(1)
-        .describe('Substring the request URL must contain, e.g. "/api/pay".'),
-    method: z.string().optional().describe('Optional method filter (GET/POST/…), case-insensitive.'),
-    status: httpStatusSchema.optional().describe('Fulfill with this HTTP status (default 200).'),
-    body: z.string().optional().describe('Response body to fulfill with.'),
-    contentType: z.string().optional().describe('Response content type (default application/json).'),
-    delayMs: delayMsSchema.optional().describe('Delay (ms) before fulfilling — simulate a slow API.'),
-    abort: z
-        .boolean()
-        .optional()
-        .describe('Simulate a network failure (offline) instead of a response.'),
-});
-/**
- * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
- *
- * THROWS on a malformed rule rather than falling back to `[]`, because `[]` is not a neutral value
- * here — it is the documented way to clear every active mock. A rule with a wrong field name used to
- * produce exactly the call that turns mocking OFF, and the handler then reported `applied: true`
- * with `count: 0`. For a tool whose entire job is forcing an error state, that means the agent
- * checks the app's failure handling against the real backend, sees the happy path, and reports that
- * the error state works.
- *
- * Same rule as the action arguments: an argument that could not be understood is refused by name,
- * never reinterpreted into a destructive default. A valueless `fill` used to wipe the field and
- * report ok; it throws now, for this reason.
- *
- * `undefined` and `[]` still mean "clear" — those are deliberate, documented requests, not failures
- * to parse.
- */
-export function toRules(value) {
-    if (value === undefined)
-        return [];
-    const parsed = z.array(ruleShape).safeParse(value);
-    if (!parsed.success) {
-        const problem = parsed.error.issues
-            .map((i) => `${0 === i.path.length ? 'mocks' : `mocks.${i.path.join('.')}`}: ${i.message}`)
-            .join('; ');
-        throw new Error(`reticle_network_mock could not read \`mocks\` (${problem}). Nothing was applied and mocking ` +
-            'was left unchanged — an unreadable rule is NOT treated as a request to clear. A rule is ' +
-            '{ urlContains, method?, status?, body?, contentType?, delayMs?, abort? }; pass `clear: true` ' +
-            'or an empty array if you meant to turn mocking off.');
-    }
-    return parsed.data.map((r) => {
-        const rule = { urlContains: r.urlContains };
-        if (r.method !== undefined)
-            rule.method = r.method;
-        if (r.status !== undefined)
-            rule.status = r.status;
-        if (r.body !== undefined)
-            rule.body = r.body;
-        if (r.contentType !== undefined)
-            rule.contentType = r.contentType;
-        if (r.delayMs !== undefined)
-            rule.delayMs = r.delayMs;
-        if (r.abort !== undefined)
-            rule.abort = r.abort;
-        return rule;
-    });
-}
-export const NETWORK_MOCK_TOOLS = [
-    {
-        name: ReticleTool.NETWORK_MOCK,
-        description: 'Stub or intercept network requests on a driven page (`reticle drive` / RETICLE_CDP_URL) or a ' +
-            'leased Playwright tab (`reticle_lease acquire`): return a 500, force offline (abort), or delay ' +
-            'a response — so you can deterministically test error and edge states without touching the ' +
-            'backend ("verify the app handles a failed payment"). Pass `mocks` (first matching rule wins); ' +
-            'pass an empty array or `clear: true` to turn mocking off.',
-        inputSchema: {
-            // The rule fields each carry their own `.describe()` on `ruleShape`, but the params
-            // view reads only the top-level description of each entry, so those are flattened
-            // away before an agent sees them. Naming the shape here is what keeps the tool
-            // callable from its own description instead of by guessing and failing first.
-            mocks: z
-                .array(ruleShape)
-                .optional()
-                .describe('Interception rules, first match wins: { urlContains, method?, status?, body?, contentType?, delayMs?, abort? }. Omit or pass [] to clear.'),
-            clear: z.boolean().optional().describe('Clear all active mocks (same as mocks: []).'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            applied: z.boolean(),
-            count: z.number(),
-            ok: z.boolean().optional(),
-            reason: z.string().optional(),
-            recommendation: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
-            const rules = true === args['clear'] ? [] : toRules(args['mocks']);
-            const provider = mockProvider(deps);
-            if (provider !== undefined) {
-                const applied = await provider.setMocks(session.url, rules);
-                if (applied)
-                    return { applied: true, count: rules.length };
-            }
-            // A lease is a Playwright-owned page — CDP intercept was always there, this tool just had no
-            // route to it. Tried after the driven provider: when both exist, drive is the page the caller
-            // means, and a lease is the fallback rather than a competitor.
-            const leased = await deps.pool?.setMocksLease(session.id, rules);
-            if (true === leased)
-                return { applied: true, count: rules.length };
-            return {
-                applied: false,
-                count: 0,
-                ok: false,
-                reason: CDP_NO_PROVIDER_REASON,
-                recommendation: CDP_NO_PROVIDER_RECOMMENDATION,
-            };
-        },
-    },
-];

package/dist/input/network-mock.js

@@ -1,61 +0,0 @@
-const DEFAULT_STATUS = 200;
-const DEFAULT_CONTENT_TYPE = 'application/json';
-/**
- * Decide the outcome for a request from the active rules. Pure: no IO, no clock. The first rule
- * whose url-substring (and optional method) matches wins; no match → continue (let it hit the network).
- */
-export function matchMock(rules, req) {
-    for (const rule of rules) {
-        if (!req.url.includes(rule.urlContains))
-            continue;
-        if (rule.method !== undefined && rule.method.toUpperCase() !== req.method.toUpperCase())
-            continue;
-        if (true === rule.abort)
-            return { kind: 'abort' };
-        const outcome = {
-            kind: 'fulfill',
-            status: rule.status ?? DEFAULT_STATUS,
-            contentType: rule.contentType ?? DEFAULT_CONTENT_TYPE,
-        };
-        if (rule.body !== undefined)
-            outcome.body = rule.body;
-        if (rule.delayMs !== undefined)
-            outcome.delayMs = rule.delayMs;
-        return outcome;
-    }
-    return { kind: 'continue' };
-}
-/** Apply a matched outcome to a Playwright Route. Exported so the route handler is testable in isolation. */
-export async function applyOutcome(route, outcome, sleep) {
-    if ('continue' === outcome.kind) {
-        await route.continue();
-        return;
-    }
-    if ('abort' === outcome.kind) {
-        await route.abort('failed');
-        return;
-    }
-    if (outcome.delayMs !== undefined && outcome.delayMs > 0)
-        await sleep(outcome.delayMs);
-    await route.fulfill({
-        status: outcome.status ?? DEFAULT_STATUS,
-        contentType: outcome.contentType ?? DEFAULT_CONTENT_TYPE,
-        body: outcome.body ?? '',
-    });
-}
-const realSleep = (ms) => new Promise((res) => setTimeout(res, ms));
-/**
- * Install (or replace) the network-mock handler on a driven page. Clears any prior Reticle route first,
- * so calling with a new rule set is idempotent and calling with [] turns mocking off. The handler
- * consults matchMock per request and fulfills/aborts/continues accordingly.
- */
-export async function installNetworkMocks(page, rules, sleep = realSleep) {
-    await page.unroute('**/*').catch(() => undefined);
-    if (0 === rules.length)
-        return;
-    await page.route('**/*', (route) => {
-        const req = route.request();
-        const outcome = matchMock(rules, { url: req.url(), method: req.method() });
-        void applyOutcome(route, outcome, sleep);
-    });
-}

package/dist/input/real-input.d.ts

@@ -1,222 +0,0 @@
-/**
- * Optional CDP/Playwright real-input mode.
- *
- * Synthetic `dispatchEvent` cannot drive native hover/pointer state (an onMouseEnter never
- * fires, hit-testing never runs). When a CDP endpoint is configured, this module connects a
- * Playwright `Browser` over CDP and drives REAL pointer/keyboard input against the element box
- * the SDK resolves (viewport CSS px from getBoundingClientRect).
- *
- * Node-only. Playwright is loaded via DYNAMIC `import('playwright')` so non-CDP users never
- * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
- */
-import type { Browser, Page } from 'playwright';
-import { ActionType, DriveErrorCode } from '@reticlehq/core';
-import { type MockRule } from './network-mock.js';
-import { type NetworkDetail } from './network-detail.js';
-/** Viewport CSS-px box as returned by the INSPECT command (getBoundingClientRect). */
-export interface ElementBox {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/** Args forwarded from reticle_act (fill value, type text, drag drop-target box). */
-export interface RealInputArgs {
-    value?: string;
-    text?: string;
-    /** For drag: the resolved box of the drop-target ref (toRef). */
-    toBox?: ElementBox;
-    steps?: number;
-}
-interface RealInputResult {
-    /** True if a native gesture was actually driven. */
-    performed: boolean;
-    /** Center used, for diagnostics/tests. */
-    center: {
-        cx: number;
-        cy: number;
-    };
-}
-/** Options for a page screenshot — full-page scroll capture and/or a clip box. */
-export interface ScreenshotOpts {
-    fullPage?: boolean;
-    /** Restrict the capture to one element/region (viewport CSS px). */
-    clip?: ElementBox;
-}
-/** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
-export interface RealInputProvider {
-    /** Whether a Playwright Page currently matches this SDK session URL. */
-    isAvailableFor(sessionUrl: string): Promise<boolean>;
-    /** Drive a native gesture for `action` at the element `box`. */
-    perform(sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
-    /**
-     * Capture a PNG of the correlated page, or undefined if no page matches. Optional
-     * so the visual layer stays opt-in — a provider that cannot screenshot simply omits it.
-     */
-    screenshot?(sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
-    /**
-     * Install (or replace, or with [] clear) network-mock rules on the correlated page — stub a 500,
-     * force offline, delay a response — for deterministic error/edge-state testing. Returns true when
-     * a page matched and the rules were applied, false when no driven page matches this session.
-     * Optional: a provider with no owned browser simply omits it.
-     */
-    setMocks?(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
-    /**
-     * Pin the correlated page's viewport to fixed pixel dimensions so a screenshot baseline is
-     * reproducible across machines (the missing piece of CI-stable visual regression, alongside masks
-     * and the frozen clock). Returns true when a page matched, false otherwise. Optional.
-     */
-    setViewport?(sessionUrl: string, size: {
-        width: number;
-        height: number;
-    }): Promise<boolean>;
-}
-/**
- * Optional lifecycle a provider that OWNS a browser implements (`reticle drive`). The
- * reticle_act routing still depends only on `RealInputProvider`; the server uses these to boot/tear-down.
- */
-export interface OwnedRealInputProvider extends RealInputProvider {
-    /** Launch + navigate the owned browser. Must reject (never hang) on failure. */
-    navigate(): Promise<void>;
-    /** Close the owned browser. Idempotent. */
-    dispose(): Promise<void>;
-}
-/** Structured, code-tagged failure so callers branch on cause, not message text. */
-export declare class DriveError extends Error {
-    readonly code: DriveErrorCode;
-    constructor(code: DriveErrorCode, message: string);
-}
-/** Center of a viewport box in CSS px. Pure — unit-tested directly. */
-export declare function boxCenter(box: ElementBox): {
-    cx: number;
-    cy: number;
-};
-/**
- * Which actions are driven by native pointer input. fill/type stay synthetic unless a
- * provider explicitly runs them.
- */
-export declare function isPointerAction(action: ActionType): boolean;
-type SleepFn = (ms: number) => Promise<void>;
-type ConnectFn = (url: string) => Promise<Browser>;
-/**
- * Shared gesture executor: drive a native gesture on an already-resolved Page. Used by both the
- * CDP-attached and the launched (drive) providers so the pointer logic lives in one place.
- */
-export declare function performGesture(page: Page, action: ActionType, box: ElementBox, args: RealInputArgs, sleep: SleepFn): Promise<RealInputResult>;
-/**
- * Capture a PNG from a Playwright page. Shared by the CDP + launched providers so the
- * screenshot path lives in one place (mirrors performGesture). Returns the raw PNG bytes.
- */
-export declare function capturePage(page: Page, opts: ScreenshotOpts): Promise<Uint8Array>;
-interface CdpProviderOptions {
-    cdpUrl: string;
-    /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
-    sleep?: SleepFn;
-    /** Injected connector so unit tests can stub Playwright without import. */
-    connect?: ConnectFn;
-    /**
-     * Sink for CDP-authoritative network detail. Optional, so the capture stays opt-in.
-     *
-     * This used to exist only on the LAUNCHED provider, which gated wire-level network visibility on
-     * whether Reticle happened to open the browser. That is the wrong axis: owning the browser says
-     * nothing about being able to see its network, and both providers speak CDP. The authoritative
-     * request body is the one thing an in-page fetch wrapper structurally cannot get.
-     */
-    onNetworkDetail?: (detail: NetworkDetail) => void;
-}
-/** CDP-backed real-input provider. Lazily connects on first availability check / perform. */
-export declare class CdpRealInputProvider implements RealInputProvider {
-    #private;
-    constructor(options: CdpProviderOptions);
-    isAvailableFor(sessionUrl: string): Promise<boolean>;
-    perform(sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
-    /** PNG of the correlated page, or undefined if none matches. */
-    screenshot(sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
-    /** Apply network-mock rules to the correlated page; false when no driven page matches. */
-    setMocks(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
-    /** Pin the correlated page's viewport to fixed dimensions; false when no driven page matches. */
-    setViewport(sessionUrl: string, size: {
-        width: number;
-        height: number;
-    }): Promise<boolean>;
-    /** Best-effort cleanup; idempotent. */
-    dispose(): Promise<void>;
-}
-/** Injected launcher so unit tests stub Playwright without import. */
-export type LaunchFn = (headless: boolean) => Promise<Browser>;
-/**
- * Force a driven page's already-loaded SDK to connect to our loopback bridge with a pairing token,
- * overriding the app's own (often localhost-only) reticle.connect — so a hosted preview verifies with
- * no app redeploy. connect is a no-op once connected, so re-invoking it is safe.
- */
-export interface InjectConnectOptions {
-    token: string;
-    url: string;
-}
-export interface LaunchedProviderOptions {
-    driveUrl: string;
-    headless: boolean;
-    /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
-    sleep?: SleepFn;
-    /** Injected launcher so unit tests can stub Playwright; defaults to dynamic import('playwright'). */
-    launch?: LaunchFn;
-    /** When set, re-invoke the page's reticle.connect with these after load (drive-a-hosted-preview). */
-    injectConnect?: InjectConnectOptions;
-    /** Path to a Playwright storageState JSON (cookies/localStorage) — starts the page authenticated. */
-    storageState?: string;
-    /**
-     * Sink for CDP-authoritative network detail. When set, every driven-page response is captured
-     * as a NET_DETAIL and handed here — the daemon routes it onto the driven session's journal so the
-     * inside-app view never loses fidelity to the outside-in view. Omitted → no network detail captured.
-     */
-    onNetworkDetail?: (detail: NetworkDetail) => void;
-}
-/** The only place the dynamic value import of Playwright lives for the launched (drive) path. */
-export declare const launchedChromium: LaunchFn;
-/**
- * Launches and OWNS a Playwright Chromium, navigates it to `driveUrl`, then drives native
- * input on that page. Headless-capable so @reticlehq/test / CI can run hover/drag unattended.
- */
-export declare class LaunchedRealInputProvider implements OwnedRealInputProvider {
-    #private;
-    constructor(options: LaunchedProviderOptions);
-    navigate(): Promise<void>;
-    isAvailableFor(sessionUrl: string): Promise<boolean>;
-    perform(_sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
-    /** PNG of the owned page, or undefined before navigate / after dispose. */
-    screenshot(_sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
-    /**
-     * Pin the owned page's viewport; false before navigate / after dispose.
-     *
-     * `CdpRealInputProvider` has had this since it shipped and THIS provider did not, so
-     * `reticle_viewport` refused with `no-cdp-provider` under `reticle drive` — while recommending
-     * `reticle drive` as the fix. Same for `setMocks` below. A driven browser was attached and taking
-     * screenshots the whole time; only these two methods were missing.
-     */
-    setViewport(_sessionUrl: string, size: {
-        width: number;
-        height: number;
-    }): Promise<boolean>;
-    /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
-    setMocks(_sessionUrl: string, rules: MockRule[]): Promise<boolean>;
-    /** Close the owned browser once. Idempotent and safe before navigate. */
-    dispose(): Promise<void>;
-}
-/** Drop hash/query so a page whose URL drifted by fragment still correlates to the session. */
-/**
- * Correlate a session URL to one driven page, or refuse.
- *
- * Exact match first, query string included — that is the only fully reliable signal. The stripped
- * fallback exists for a real case (an app pushState's to /overview, so the page's URL no longer
- * equals the session's) but it is only sound when UNAMBIGUOUS.
- *
- * Returning the first loose match was a false-green generator: the benchmark fixture selects a bug
- * purely by query string, so two pages differing only there stripped to the same key, and a visual
- * diff happily compared the wrong page to itself and reported "0.00% changed, matched" for pixels
- * that demonstrably differed. Ambiguity now yields undefined, which callers already surface as
- * "no driven page" rather than as a passing comparison.
- */
-export declare function selectPage<T extends {
-    url(): string;
-}>(pages: readonly T[], sessionUrl: string): T | undefined;
-export {};