@reticlehq/server 3.8.0 → 3.8.2

package/dist/memory/journal/self-observation.js

@@ -46,6 +46,7 @@ const NET_TYPES = new Set([
     EventType.NET_REQUEST,
     EventType.NET_PENDING,
     EventType.NET_DETAIL,
+    EventType.NET_RESPONSE_BODY,
     EventType.NET_STREAM,
 ]);
 /** A base for parsing relative URLs. Never dereferenced — only the path is read. */
@@ -60,8 +61,9 @@ function pathOf(url) {
 }
 /** True when this event is the page fetching Reticle's own code rather than doing anything. */
 export function isSelfObservation(event) {
-    if (!NET_TYPES.has(event.type))
+    if (!NET_TYPES.has(event.type)) {
         return false;
+    }
     const path = pathOf(urlForMatch(event.data));
     return path.includes(SCOPE_PATH) || path.includes(SCOPE_FLATTENED);
 }

package/dist/memory/journal/session-journal.js

@@ -49,8 +49,9 @@ const CACHE_COMPACT_AT = 1024;
  * bound is used in and silently disable it, which is the one failure mode a bound must not have.
  */
 function boundedOption(value, fallback, name) {
-    if (value === undefined)
+    if (value === undefined) {
         return fallback;
+    }
     if (!Number.isSafeInteger(value) || value <= 0) {
         throw new Error(`refusing a journal ${name} that is not a positive whole number: ${String(value)}`);
     }
@@ -184,11 +185,13 @@ export class SessionJournal {
      * already on disk is deleted, and the loss is at the end where it can be declared.
      */
     async appendEvents(events) {
-        if (0 === events.length)
+        if (0 === events.length) {
             return;
+        }
         // Durable, not a field: see #writeLoss. A closed ledger is closed for a one-event batch too.
-        if ((await this.#closureReport()) !== undefined)
+        if ((await this.#closureReport()) !== undefined) {
             return;
+        }
         await this.#ensureDir();
         const path = journalEventsPath(this.#root, this.#sessionId);
         const written = await this.#eventBytesOnDisk(path);
@@ -221,8 +224,9 @@ export class SessionJournal {
      */
     async #eventBytesOnDisk(path) {
         const known = this.#eventBytes;
-        if (known !== undefined)
+        if (known !== undefined) {
             return known;
+        }
         let size;
         try {
             size = (await this.#fs.stat(path)).size;
@@ -235,8 +239,9 @@ export class SessionJournal {
             // by exactly the conditions most likely to accompany a failing disk. Thrown before anything is
             // appended; `JournalRecorder` swallows sink errors, so a live session is never taken down by
             // one.
-            if (!this.#fs.isNotFound(error))
+            if (!this.#fs.isNotFound(error)) {
                 throw error;
+            }
             size = 0;
         }
         this.#eventBytes = size;
@@ -252,16 +257,18 @@ export class SessionJournal {
      * necessarily the ceiling that closed the file.
      */
     async #closureReport() {
-        if (this.#lossLoaded)
+        if (this.#lossLoaded) {
             return this.#writeLoss;
+        }
         let text;
         try {
             text = await this.#fs.readFile(journalClosedPath(this.#root, this.#sessionId));
         }
         catch (error) {
             // Same rule as the size read above, and for the same reason: only ENOENT is "never closed".
-            if (!this.#fs.isNotFound(error))
+            if (!this.#fs.isNotFound(error)) {
                 throw error;
+            }
             this.#lossLoaded = true;
             return undefined;
         }
@@ -371,8 +378,9 @@ export class SessionJournal {
             await this.#fs.appendFile(path, text);
         }
         catch (error) {
-            if (!this.#fs.isNotFound(error))
+            if (!this.#fs.isNotFound(error)) {
                 throw error;
+            }
             this.#dirEnsured = false;
             await this.#ensureDir();
             await this.#fs.appendFile(path, text);
@@ -390,8 +398,9 @@ export class SessionJournal {
                 chunk = await readFrom(path, this.#eventBytesConsumed, this.#maxReadBytes);
             }
             catch (error) {
-                if (this.#fs.isNotFound(error))
+                if (this.#fs.isNotFound(error)) {
                     return this.#liveEvents();
+                }
                 throw error;
             }
             // Shrink guard: if the file is smaller than what we consumed, the offset is meaningless — reset
@@ -408,8 +417,9 @@ export class SessionJournal {
             const from = chunk.from ?? this.#eventBytesConsumed;
             const skipped = Math.max(0, from - this.#eventBytesConsumed);
             this.#ingestTail(chunk.text);
-            if (skipped > 0)
+            if (skipped > 0) {
                 this.#noteCut(skipped);
+            }
             // Resume at the end of the last COMPLETE line, counted forward over the bytes that actually
             // ARRIVED. Not from `chunk.size`: that is the file's end as `fstat` reported it, and a read
             // truncated or cut short returns less — a cursor there would skip every unread byte, silently
@@ -424,8 +434,9 @@ export class SessionJournal {
             text = await this.#fs.readFile(path);
         }
         catch (error) {
-            if (this.#fs.isNotFound(error))
+            if (this.#fs.isNotFound(error)) {
                 return this.#liveEvents();
+            }
             throw error;
         }
         // Fallback (whole-file) path: #eventCharsConsumed is a UTF-16 offset into the whole text. Shrink
@@ -467,11 +478,13 @@ export class SessionJournal {
      */
     #ingestTail(tail) {
         const end = tail.lastIndexOf('\n') + 1;
-        if (0 === end)
-            return; // no complete line yet
+        if (0 === end) {
+            return;
+        } // no complete line yet
         for (const line of tail.slice(0, end).split('\n')) {
-            if (0 === line.length)
+            if (0 === line.length) {
                 continue;
+            }
             let parsed;
             try {
                 parsed = JSON.parse(line);
@@ -515,8 +528,9 @@ export class SessionJournal {
             this.#droppedBytes += cost;
             this.#droppedEvents += 1;
             // Exact, unlike a byte cut: this record was parsed, so the millisecond it was lost at is known.
-            if (victim !== undefined)
+            if (victim !== undefined) {
                 this.#lostThroughT = Math.max(this.#lostThroughT, victim.t);
+            }
             // Release the payload now. Waiting for slot compaction keeps evicted snapshots strongly
             // reachable, so a short returned list alone would not bound retained evidence in memory.
             this.#eventCache[this.#cacheHead] = undefined;
@@ -545,8 +559,9 @@ export class SessionJournal {
      * is what carries this to a verdict.
      */
     readLoss() {
-        if (0 === this.#droppedBytes && 0 === this.#droppedEvents)
+        if (0 === this.#droppedBytes && 0 === this.#droppedEvents) {
             return undefined;
+        }
         const bounded = Number.isFinite(this.#lostThroughT);
         return {
             droppedBytes: this.#droppedBytes,
@@ -568,8 +583,9 @@ export class SessionJournal {
         return this.#readLines(journalActionsPath(this.#root, this.#sessionId), JournalActionSchema);
     }
     async #ensureDir() {
-        if (this.#dirEnsured)
+        if (this.#dirEnsured) {
             return;
+        }
         await this.#fs.mkdir(sessionDirPath(this.#root, this.#sessionId));
         this.#dirEnsured = true;
     }
@@ -579,14 +595,16 @@ export class SessionJournal {
             text = await this.#fs.readFile(path);
         }
         catch (error) {
-            if (this.#fs.isNotFound(error))
+            if (this.#fs.isNotFound(error)) {
                 return [];
+            }
             throw error;
         }
         const out = [];
         for (const line of text.split('\n')) {
-            if (0 === line.length)
+            if (0 === line.length) {
                 continue;
+            }
             let parsed;
             try {
                 parsed = JSON.parse(line);
@@ -596,8 +614,9 @@ export class SessionJournal {
             }
             const result = schema.safeParse(parsed);
             // Validated at this boundary; ZodTypeAny widens `.data` to any, so re-narrow to the schema output.
-            if (result.success)
+            if (result.success) {
                 out.push(result.data);
+            }
         }
         return out;
     }

package/dist/portal/input/drive-error.d.ts

@@ -0,0 +1,6 @@
+import type { DriveErrorCode } from '@reticlehq/core';
+/** 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);
+}

package/dist/portal/input/drive-error.js

@@ -0,0 +1,9 @@
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export class DriveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DriveError';
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { Page } from 'playwright';
+import { InputModeReason } from '@reticlehq/core';
+import type { RealInputArgs } from './real-input.js';
+type SleepFn = (ms: number) => Promise<void>;
+/**
+ * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
+ * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
+ * cannot read the same args differently.
+ *
+ * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
+ * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
+ * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
+ * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
+ * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
+ * nothing now has a reason to try it.
+ */
+export declare function pressViaKeyboard(page: Page, args: RealInputArgs, sleep: SleepFn, now: () => number): Promise<number>;
+/**
+ * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
+ *
+ * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
+ * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
+ * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
+ * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
+ * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
+ * routed to the synthetic path by the caller, which reports the reason rather than pretending a
+ * different gesture happened.
+ *
+ * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
+ * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
+ * should name that, not the generic "you passed a ref".
+ */
+export declare function unspellablePressReason(ref: string, args: Record<string, unknown>): InputModeReason | undefined;
+export {};

package/dist/portal/input/real-input-press.js

@@ -0,0 +1,150 @@
+import { clampHoldMs, DriveErrorCode, explicitCodeFromArgs, InputModeReason, pressKeyFromArgs, pressKeysFromArgs, pressModifiersFromArgs, } from '@reticlehq/core';
+import { DriveError } from './drive-error.js';
+/**
+ * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
+ * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
+ * cannot read the same args differently.
+ *
+ * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
+ * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
+ * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
+ * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
+ * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
+ * nothing now has a reason to try it.
+ */
+export async function pressViaKeyboard(page, args, sleep, now) {
+    const key = pressKeyFromArgs(args);
+    const modifiers = pressModifiersFromArgs(args);
+    const chord = 0 < modifiers.length ? `${modifiers.join('+')}+${key}` : key;
+    const holdMs = clampHoldMs(args.holdMs);
+    if (0 === holdMs) {
+        // `press` DOES take a chord string ("Control+k"), so the tap path needs no splitting.
+        await page.keyboard.press(chord);
+        return 0;
+    }
+    /*
+     * `down`/`up` take ONE key each, unlike `press`: `down('Control+k')` throws
+     * `Unknown key: "Control+k"` — measured on a real Chromium, not assumed. The chord string the
+     * tap path uses therefore cannot express a hold, so the chord is split here: modifiers down in
+     * chord order, the key last, and released in reverse (key first, modifiers reversed), which is
+     * what a hand does and what an app's keyup bookkeeping expects.
+     *
+     * Without the split a held shortcut threw before a single key moved, the caller fell back to
+     * the synthetic path, and a real hold was impossible for any press with modifiers — the exact
+     * gesture `holdMs` exists for.
+     *
+     * ## Why every key that went down is tracked, and every exit path cleans up
+     *
+     * The down calls are the ones that MOVE the keyboard, and they can fail partway: `Control` goes
+     * down, the key after it rejects, and the driver's copy of `Control` is still held. That path
+     * used to fall straight to the caller's synthetic replay — which presses the same chord again on
+     * a keyboard that is already holding a modifier. Tracking what actually went down is what makes
+     * the cleanup below able to release the right keys, and only those: releasing a key that never
+     * went down is its own lie, and it would turn a clean failure into an unnecessary refusal.
+     */
+    const pressed = [];
+    const pressDown = async (k) => {
+        await page.keyboard.down(k);
+        pressed.push(k);
+    };
+    try {
+        for (const modifier of modifiers) {
+            await pressDown(modifier);
+        }
+        await pressDown(key);
+    }
+    catch (error) {
+        // The chord is PARTIALLY down. Release what is held before reporting the failure; if that
+        // cannot be proved, `releaseKeys` throws RELEASE_FAILED and the caller refuses the replay —
+        // the same rule as a failed release on the ordinary path, for the same reason. Only when the
+        // cleanup DOES succeed is the original error safe to hand back.
+        await releaseKeys(page, pressed);
+        throw error;
+    }
+    const startedAt = now();
+    try {
+        await sleep(holdMs);
+    }
+    catch (error) {
+        // The wait failed, and the caller is about to run the synthetic path — which presses this SAME
+        // key a second time. If the driver's copy stays down, a held modifier then colours every later
+        // action for the rest of the run. Best-effort on purpose: whatever went wrong with the wait is
+        // the error worth reporting. A cleanup that cannot be proved is the exception — that one is a
+        // stuck key, and it must reach the caller as a refusal rather than be swallowed.
+        try {
+            await releaseKeys(page, pressed);
+        }
+        catch {
+            throw new DriveError(DriveErrorCode.RELEASE_FAILED, 'the wait failed and the keys it pressed could not be released, so they may still be held');
+        }
+        throw error;
+    }
+    // NOT best-effort: on the ordinary path a failed release is a real failure the caller must hear
+    // about, and swallowing it would report a press whose key is still down.
+    await releaseKeys(page, pressed);
+    return now() - startedAt;
+}
+/**
+ * Release the given keys, in reverse press order, and report a failure as one that leaves the
+ * keyboard UNKNOWN rather than as an ordinary provider error.
+ *
+ * Every release is attempted even after one fails: a stuck `Control` is worse than a stuck letter,
+ * so a failure on one key must not skip the rest. The first failure is what is thrown, since it is
+ * the one that happened first, and it is wrapped in `DriveError` so the caller can tell "this
+ * gesture failed" from "this gesture may have left a key down" — the difference between a safe
+ * synthetic replay and an unsafe one.
+ */
+async function releaseKeys(page, pressed) {
+    let failure;
+    for (const k of [...pressed].reverse()) {
+        try {
+            await page.keyboard.up(k);
+        }
+        catch (error) {
+            failure ??= error;
+        }
+    }
+    if (failure !== undefined) {
+        throw new DriveError(DriveErrorCode.RELEASE_FAILED, `the key was pressed but could not be released, so it may still be held: ${describeFailure(failure)}`);
+    }
+}
+/**
+ * A thrown value as a line a reader can act on.
+ *
+ * Not `String(error)`: a non-Error thrown value (a rejected plain object, an SDK that throws a
+ * record) stringifies to `[object Object]`, which names nothing and hides the one fact the message
+ * exists to carry. Anything that is neither an Error nor a string says so rather than pretending.
+ */
+function describeFailure(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return 'string' === typeof error ? error : 'an unknown error';
+}
+/**
+ * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
+ *
+ * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
+ * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
+ * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
+ * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
+ * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
+ * routed to the synthetic path by the caller, which reports the reason rather than pretending a
+ * different gesture happened.
+ *
+ * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
+ * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
+ * should name that, not the generic "you passed a ref".
+ */
+export function unspellablePressReason(ref, args) {
+    if (0 < pressKeysFromArgs(args).length) {
+        return InputModeReason.SYNTHETIC_MULTI_KEY_PRESS_PREFERRED;
+    }
+    if (explicitCodeFromArgs(args) !== undefined) {
+        return InputModeReason.SYNTHETIC_KEY_CODE_PRESS_PREFERRED;
+    }
+    if (0 < ref.length) {
+        return InputModeReason.SYNTHETIC_ELEMENT_PRESS_PREFERRED;
+    }
+    return undefined;
+}

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

@@ -11,7 +11,8 @@
  */
 import { type ScriptCoverage } from './js-coverage.js';
 import type { Browser, Page } from 'playwright';
-import { ActionType, DriveErrorCode, InputMode, InputModeReason } from '@reticlehq/core';
+import { DriveError } from './drive-error.js';
+import { ActionType, InputMode } 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). */
@@ -34,6 +35,8 @@ export type RealInputArgs = {
     key?: string;
     /** For press: modifier names (Meta/Control/Shift/Alt; aliases like `cmd` accepted). */
     modifiers?: string[];
+    /** For click: which mouse button to press (left, middle or right). Absent means left. */
+    button?: string;
     /**
      * For press: several keys held down TOGETHER, pressed in order and released in reverse. Read but
      * never forwarded — a chord with a non-modifier key has no `page.keyboard.press` spelling, so the
@@ -152,11 +155,8 @@ export interface OwnedRealInputProvider extends RealInputProvider {
     /** 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);
-}
+export { DriveError };
+export { unspellablePressReason } from './real-input-press.js';
 /** Center of a viewport box in CSS px. Pure — unit-tested directly. */
 export declare function boxCenter(box: ElementBox): {
     cx: number;
@@ -174,22 +174,6 @@ export declare function isPointerAction(action: ActionType): boolean;
 export declare function isRealInputAction(action: ActionType): boolean;
 type SleepFn = (ms: number) => Promise<void>;
 type ConnectFn = (url: string) => Promise<Browser>;
-/**
- * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
- *
- * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
- * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
- * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
- * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
- * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
- * routed to the synthetic path by the caller, which reports the reason rather than pretending a
- * different gesture happened.
- *
- * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
- * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
- * should name that, not the generic "you passed a ref".
- */
-export declare function unspellablePressReason(ref: string, args: Record<string, unknown>): InputModeReason | undefined;
 /**
  * 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.
@@ -342,4 +326,3 @@ export declare class LaunchedRealInputProvider implements OwnedRealInputProvider
 export declare function selectPage<T extends {
     url(): string;
 }>(pages: readonly T[], sessionUrl: string): T | undefined;
-export {};