@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/annotations/capture.js

@@ -0,0 +1,308 @@
+// The terminal's capture surface for page notes (PROP-0017, PROP-0018). A front end captures in
+// one target at a time:
+// - `web`: a visible browser window the person browses in, separate from the agent's browser;
+// - `cdp`: the windows of a desktop app started with a DevTools port (an Electron app, say);
+// - `bridge`: app windows that loaded the page bridge script (a macOS web view has no DevTools port).
+// The person selects text, clicks an element, or inspects with the popover; the front end pulls
+// what they did through the page helper.
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { readBrowserConfig } from "../browser/config.js";
+import { NetworkPolicy } from "../browser/network.js";
+import { BrowserSession, fileName, launchBrowser } from "../browser/session.js";
+import { NotesBridge } from "./bridge.js";
+import { evaluateIsolated } from "./isolated.js";
+import { pageCall, pageReply } from "./pageScript.js";
+import { validateUrl } from "./store.js";
+const IDLE_MS = 60 * 60_000;
+const LOOPBACK = /^(?:https?|wss?):\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/;
+const connectApp = async (endpoint) => {
+    const { chromium } = await import('playwright-core');
+    return chromium.connectOverCDP(endpoint);
+};
+/** An app's own windows over its DevTools port. Nothing is routed or opened, and the app is never closed. */
+class CdpTarget {
+    browser;
+    app;
+    kind = 'cdp';
+    ids = new WeakMap();
+    nextId = 1;
+    current = null;
+    constructor(browser, app) {
+        this.browser = browser;
+        this.app = app;
+    }
+    pages() {
+        return this.browser.contexts().flatMap((context) => context.pages()).filter((page) => !/^(?:devtools|chrome-extension):/.test(page.url()));
+    }
+    id(page) {
+        let id = this.ids.get(page);
+        if (!id) {
+            id = `w${this.nextId++}`;
+            this.ids.set(page, id);
+        }
+        return id;
+    }
+    page() {
+        const pages = this.pages();
+        if (this.current && pages.includes(this.current))
+            return this.current;
+        this.current = pages[0] ?? null;
+        if (!this.current)
+            throw new Error('The app has no open window.');
+        return this.current;
+    }
+    async evaluate(operation) {
+        return evaluateIsolated(this.page(), pageCall(operation));
+    }
+    async windows() {
+        const current = this.pages().length ? this.page() : null;
+        return Promise.all(this.pages().map(async (page) => ({ id: this.id(page), url: page.url(), title: await page.title().catch(() => ''), current: page === current })));
+    }
+    select(id) {
+        const page = this.pages().find((candidate) => this.ids.get(candidate) === id);
+        if (!page)
+            throw new Error(`There is no app window ${id}.`);
+        this.current = page;
+        void page.bringToFront().catch(() => undefined);
+    }
+    async close() {
+        // Disconnects; an app we attached to keeps running.
+        await this.browser.close().catch(() => undefined);
+    }
+}
+/** Windows that loaded the page bridge script. Every answer is page data the page could forge. */
+class BridgeTarget {
+    bridge;
+    app;
+    kind = 'bridge';
+    current = null;
+    constructor(bridge, app) {
+        this.bridge = bridge;
+        this.app = app;
+    }
+    window() {
+        const windows = this.bridge.list();
+        if (this.current && windows.some((window) => window.id === this.current))
+            return this.current;
+        this.current = windows.sort((left, right) => right.lastSeen - left.lastSeen)[0]?.id ?? null;
+        if (!this.current)
+            throw new Error('No app window has connected to the page bridge yet. Load the bridge script in the app and reload it.');
+        return this.current;
+    }
+    async evaluate(operation) {
+        return { reply: await this.bridge.call(this.window(), operation), trusted: false };
+    }
+    async windows() {
+        const current = this.bridge.list().length ? this.window() : null;
+        return this.bridge.list().map((window) => ({ id: window.id, url: window.url, title: window.title, current: window.id === current }));
+    }
+    select(id) {
+        if (!this.bridge.list().some((window) => window.id === id))
+            throw new Error(`There is no app window ${id}.`);
+        this.current = id;
+    }
+    async close() { }
+}
+/** The visible browser window, with the helper in an isolated world. */
+class WebTarget {
+    session;
+    kind = 'web';
+    app = null;
+    constructor(session) {
+        this.session = session;
+    }
+    evaluate(operation) {
+        return this.session.run(async () => evaluateIsolated((await this.session.tab()).page, pageCall(operation)));
+    }
+    async windows() {
+        if (!this.session.started)
+            return [];
+        return Promise.all(this.session.list().map(async (tab) => ({ id: tab.id, url: tab.url, title: await (await this.session.tab(tab.id)).page.title().catch(() => ''), current: tab.current })));
+    }
+    select(id) {
+        void this.session.select(id).page.bringToFront().catch(() => undefined);
+    }
+    close() {
+        return this.session.close();
+    }
+}
+export class AnnotationCapture {
+    options;
+    targets = new Map();
+    inspecting = new Map();
+    network;
+    bridge;
+    constructor(options) {
+        this.options = options;
+        this.network = options.network ?? new NetworkPolicy(() => readBrowserConfig(options.stateDir));
+        this.bridge = options.bridge ?? new NotesBridge({ stateDir: options.stateDir });
+    }
+    web(key) {
+        const existing = this.targets.get(key);
+        if (existing instanceof WebTarget)
+            return existing;
+        const session = new BrowserSession({
+            key: `notes-${key}`,
+            profileDir: join(this.options.stateDir, 'browser', 'profiles', 'person'),
+            downloadsDir: join(this.options.stateDir, 'browser', 'downloads', fileName(`notes-${key}`)),
+            // Always a window the person can see and select in.
+            config: () => ({ ...readBrowserConfig(this.options.stateDir), headed: true }),
+            network: this.network,
+            launch: this.options.launch ?? launchBrowser,
+            idleMs: IDLE_MS,
+            onIdle: () => void this.release(key)
+        });
+        const target = new WebTarget(session);
+        this.targets.set(key, target);
+        return target;
+    }
+    target(key) {
+        return this.targets.get(key) ?? this.web(key);
+    }
+    async replace(key, target) {
+        const old = this.targets.get(key);
+        this.targets.set(key, target);
+        this.inspecting.delete(key);
+        if (old && old !== target)
+            await old.close().catch(() => undefined);
+    }
+    async call(key, operation) {
+        return pageReply((await this.target(key).evaluate(operation)).reply);
+    }
+    /** What `key` captures in now. */
+    describe(key) {
+        const target = this.targets.get(key);
+        return { kind: target?.kind ?? 'web', app: target?.app ?? null, inspecting: this.inspecting.has(key) };
+    }
+    /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
+    async attach(key, spec) {
+        if (spec.kind === 'web') {
+            if (this.targets.get(key)?.kind !== 'web')
+                await this.replace(key, this.web(key));
+            return { kind: 'web', app: null, windows: await this.target(key).windows() };
+        }
+        if (spec.kind === 'cdp') {
+            if (typeof spec.endpoint !== 'string' || !LOOPBACK.test(spec.endpoint))
+                throw new Error('An app\'s DevTools address must be on this computer, such as http://127.0.0.1:9229.');
+            const browser = await (this.options.connect ?? connectApp)(spec.endpoint);
+            const name = spec.name?.trim() || `App at ${new URL(spec.endpoint).host}`;
+            const target = new CdpTarget(browser, { kind: 'cdp', name: name.slice(0, 200) });
+            await this.replace(key, target);
+            return { kind: 'cdp', app: target.app, windows: await target.windows() };
+        }
+        if (spec.kind === 'bridge') {
+            const bridge = await this.bridge.start();
+            const target = new BridgeTarget(this.bridge, { kind: 'bridge', name: (spec.name?.trim() || 'App window').slice(0, 200) });
+            await this.replace(key, target);
+            return { kind: 'bridge', app: target.app, windows: await target.windows(), bridge };
+        }
+        throw new Error('A capture target is web, cdp or bridge.');
+    }
+    windows(key) {
+        return this.target(key).windows();
+    }
+    /** Switches to another window or tab of the target; an inspector there starts again. */
+    async selectWindow(key, id) {
+        const inspecting = this.inspecting.has(key);
+        if (inspecting)
+            await this.stopInspect(key).catch(() => undefined);
+        this.target(key).select(id);
+        if (inspecting)
+            await this.inspect(key);
+    }
+    /** Shows the capture window, at `url` when given. Captures in the browser again if an app was attached. */
+    async open(key, url) {
+        if (this.targets.get(key) && this.targets.get(key).kind !== 'web')
+            await this.replace(key, this.web(key));
+        const { session } = this.web(key);
+        return session.run(async () => {
+            const tab = await session.tab();
+            if (url) {
+                const address = validateUrl(url);
+                const refusal = await this.network.refusal(address);
+                if (refusal)
+                    throw new Error(refusal);
+                await tab.page.goto(address, { waitUntil: 'domcontentloaded' });
+            }
+            await tab.page.bringToFront().catch(() => undefined);
+            return { url: tab.page.url(), title: await tab.page.title().catch(() => '') };
+        });
+    }
+    identity(key) {
+        return this.call(key, { operation: 'identity' });
+    }
+    /** Starts listening for the person's selection or click. Returns the id `capture` takes. */
+    async begin(key, kind) {
+        this.inspecting.delete(key);
+        const captureId = randomUUID();
+        await this.call(key, { operation: 'begin', kind, captureId });
+        return { captureId };
+    }
+    /** What the person selected, or null when nothing is selected yet. */
+    capture(key, captureId) {
+        return this.call(key, { operation: 'capture', captureId });
+    }
+    async cancel(key, captureId) {
+        if (!this.targets.has(key))
+            return;
+        await this.call(key, { operation: 'cancel', ...(captureId ? { captureId } : {}) });
+    }
+    /** Turns on the inspector in the current window: hover outlines, a click opens the comment popover. */
+    async inspect(key) {
+        const captureId = randomUUID();
+        await this.call(key, { operation: 'begin', kind: 'inspect', captureId });
+        const identity = await this.identity(key).catch(() => null);
+        this.inspecting.set(key, { captureId, documentId: identity?.documentId ?? null });
+        return { captureId };
+    }
+    async stopInspect(key) {
+        const state = this.inspecting.get(key);
+        this.inspecting.delete(key);
+        if (state && this.targets.has(key))
+            await this.call(key, { operation: 'cancel', captureId: state.captureId }).catch(() => undefined);
+    }
+    /**
+     * The next comment the person submitted, if any. A new document (a reload, a link) loses the
+     * inspector; it is turned on again there, so the person can keep going.
+     */
+    async next(key) {
+        const target = this.target(key);
+        const state = this.inspecting.get(key);
+        if (!state)
+            throw new Error('The inspector is off.');
+        const { reply, trusted } = await target.evaluate({ operation: 'next', captureId: state.captureId });
+        const value = pageReply(reply);
+        if (!value.active && this.inspecting.get(key) === state && value.documentId !== state.documentId) {
+            await target.evaluate({ operation: 'begin', kind: 'inspect', captureId: state.captureId });
+            state.documentId = value.documentId;
+            return { ...value, active: true, result: null, trusted, app: target.app };
+        }
+        if (!value.active)
+            this.inspecting.delete(key);
+        return { ...value, trusted, app: target.app };
+    }
+    async toast(key, text) {
+        await this.call(key, { operation: 'toast', text: text.slice(0, 200) });
+    }
+    /** Opens the note's page when another one is showing, then scrolls to and marks its target. */
+    async reveal(key, url, target) {
+        const current = this.targets.get(key);
+        if (!current || current.kind === 'web') {
+            const shown = current?.session.started ? await this.identity(key).catch(() => null) : null;
+            if (shown?.url !== url)
+                await this.open(key, url);
+        }
+        return this.call(key, { operation: 'reveal', target });
+    }
+    async release(key) {
+        const target = this.targets.get(key);
+        this.targets.delete(key);
+        this.inspecting.delete(key);
+        await target?.close();
+    }
+    async close() {
+        await Promise.all([...this.targets.keys()].map((key) => this.release(key)));
+        await this.bridge.close();
+    }
+}

package/dist/sdk/annotations/delivery.d.ts

@@ -0,0 +1,72 @@
+import type { Bus } from "../core/bus.js";
+import * as store from "./store.js";
+export interface TerminalSender {
+    has(sessionId: string): boolean;
+    send(input: {
+        sessionId: string;
+        text: string;
+    }): Promise<{
+        runId: string;
+    }>;
+}
+export type SendResult = {
+    state: 'sent';
+    runId: string;
+    ids: string[];
+} | {
+    state: 'busy';
+    ids: string[];
+} | {
+    state: 'host';
+    text: string;
+    ids: string[];
+} | {
+    state: 'empty';
+    ids: [];
+};
+export type NoteAction = 'save' | 'queue' | 'send';
+export interface NoteDeliveryOptions {
+    root: () => string;
+    bus: Bus;
+    terminals: () => TerminalSender | null;
+}
+export declare class NoteDeliveries {
+    private readonly options;
+    private readonly sending;
+    constructor(options: NoteDeliveryOptions);
+    private changed;
+    queue(id: string, expectedVersion: number | undefined, sessionId: string, options?: {
+        autoSend?: boolean;
+        confirm?: boolean;
+    }): store.Note;
+    dequeue(id: string, expectedVersion: number | undefined): store.Note;
+    /**
+     * Creates a note and acts on it in one step: what the popover's three buttons do. `trusted` is
+     * false when the comment came from a script the page could reach; a send then waits in the queue
+     * for the person to confirm it.
+     */
+    createAndAct(input: store.NoteInput, action: NoteAction, sessionId: string | null, trusted: boolean): Promise<{
+        note: store.Note;
+        send: SendResult | null;
+    }>;
+    /** The person confirms a note the page could have forged; it is then sent with the next send. */
+    confirm(id: string, expectedVersion: number | undefined): store.Note;
+    /** The instruction for the session's queued notes (or the given ones), for a host that runs it itself. */
+    compose(sessionId: string, ids?: string[] | null): {
+        text: string;
+        ids: string[];
+    };
+    /** A host started `runId` with composed notes. */
+    delivered(ids: string[], sessionId: string, runId: string): store.Note[];
+    /** Sends the session's queued notes (or the given ones) as one run. */
+    send(sessionId: string, filter?: {
+        ids?: string[] | null;
+        auto?: boolean;
+    }): Promise<SendResult>;
+    /** A run of the session ended: notes waiting for it to be idle go out now. */
+    runEnded(sessionId: string | null | undefined): Promise<void>;
+    markFixed(id: string, caller: {
+        sessionId?: string | null;
+        agentId?: string | null;
+    }, summary: string): store.Note;
+}

package/dist/sdk/annotations/delivery.js

@@ -0,0 +1,130 @@
+import { HarnessError, invalid } from "../core/errors.js";
+import { compose, MAX_SEND } from "./queue.js";
+import * as store from "./store.js";
+export class NoteDeliveries {
+    options;
+    sending = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    changed(sessionId, ids) {
+        this.options.bus.emit({ type: 'annotations.changed', sessionId, ids });
+    }
+    queue(id, expectedVersion, sessionId, options = {}) {
+        const note = store.queue(this.options.root(), id, expectedVersion, sessionId, options);
+        this.changed(sessionId, [id]);
+        return note;
+    }
+    dequeue(id, expectedVersion) {
+        const note = store.dequeue(this.options.root(), id, expectedVersion);
+        this.changed(null, [id]);
+        return note;
+    }
+    /**
+     * Creates a note and acts on it in one step: what the popover's three buttons do. `trusted` is
+     * false when the comment came from a script the page could reach; a send then waits in the queue
+     * for the person to confirm it.
+     */
+    async createAndAct(input, action, sessionId, trusted) {
+        if (!['save', 'queue', 'send'].includes(action))
+            throw invalid('action is save, queue or send.');
+        if (action !== 'save' && !sessionId)
+            throw invalid('Queueing or sending a note needs a session.');
+        const root = this.options.root();
+        let note = store.create(root, input);
+        if (action === 'save') {
+            this.changed(null, [note.id]);
+            return { note, send: null };
+        }
+        const deliveryOptions = {
+            ...(action === 'send' ? { autoSend: true } : {}),
+            ...(!trusted ? { confirm: true } : {})
+        };
+        note = store.queue(root, note.id, undefined, sessionId, deliveryOptions);
+        this.changed(sessionId, [note.id]);
+        if (action === 'queue' || !trusted)
+            return { note, send: null };
+        const send = await this.send(sessionId, { ids: [note.id] });
+        return { note: store.read(root, note.id), send };
+    }
+    /** The person confirms a note the page could have forged; it is then sent with the next send. */
+    confirm(id, expectedVersion) {
+        const root = this.options.root();
+        const note = store.read(root, id);
+        if (note.delivery?.state !== 'queued')
+            throw invalid('This note is not waiting to be sent.');
+        const confirmed = store.queue(root, id, expectedVersion, note.delivery.sessionId, { autoSend: note.delivery.autoSend === true, confirmed: true });
+        this.changed(confirmed.delivery.sessionId, [id]);
+        return confirmed;
+    }
+    /** The instruction for the session's queued notes (or the given ones), for a host that runs it itself. */
+    compose(sessionId, ids) {
+        const waiting = store.queued(this.options.root(), sessionId, { ids: ids ?? null });
+        if (ids != null && waiting.some((note) => note.delivery?.confirm))
+            throw invalid('Confirm page-origin notes before composing them.');
+        const notes = waiting.filter((note) => note.delivery?.confirm !== true).slice(0, MAX_SEND);
+        if (!notes.length)
+            throw invalid('No confirmed notes are waiting for this session.');
+        return { text: compose(notes), ids: notes.map((note) => note.id) };
+    }
+    /** A host started `runId` with composed notes. */
+    delivered(ids, sessionId, runId) {
+        const sent = store.markSent(this.options.root(), ids, sessionId, runId);
+        this.changed(sessionId, ids);
+        return sent;
+    }
+    /** Sends the session's queued notes (or the given ones) as one run. */
+    async send(sessionId, filter = {}) {
+        const root = this.options.root();
+        const waiting = store.queued(root, sessionId, { ids: filter.ids ?? null, auto: filter.auto === true });
+        if (filter.ids != null && waiting.some((note) => note.delivery?.confirm))
+            throw invalid('Confirm page-origin notes before sending them.');
+        const notes = waiting.filter((note) => note.delivery?.confirm !== true).slice(0, MAX_SEND);
+        if (!notes.length)
+            return { state: 'empty', ids: [] };
+        const ids = notes.map((note) => note.id);
+        const terminals = this.options.terminals();
+        if (!terminals?.has(sessionId)) {
+            // A host's session: the host starts the run and reports it with `delivered`.
+            if (filter.auto)
+                this.options.bus.emit({ type: 'annotations.ready', sessionId, ids });
+            return { state: 'host', text: compose(notes), ids };
+        }
+        if (this.sending.has(sessionId))
+            return { state: 'busy', ids };
+        this.sending.add(sessionId);
+        try {
+            const { runId } = await terminals.send({ sessionId, text: compose(notes) });
+            store.markSent(root, ids, sessionId, runId);
+            this.changed(sessionId, ids);
+            return { state: 'sent', runId, ids };
+        }
+        catch (error) {
+            if (error instanceof HarnessError && error.code === 'session_busy') {
+                // Send it when the run ends.
+                for (const note of notes)
+                    if (!note.delivery?.autoSend)
+                        store.queue(root, note.id, undefined, sessionId, { autoSend: true });
+                this.changed(sessionId, ids);
+                return { state: 'busy', ids };
+            }
+            throw error;
+        }
+        finally {
+            this.sending.delete(sessionId);
+        }
+    }
+    /** A run of the session ended: notes waiting for it to be idle go out now. */
+    async runEnded(sessionId) {
+        if (!sessionId)
+            return;
+        if (!store.queued(this.options.root(), sessionId, { auto: true }).length)
+            return;
+        await this.send(sessionId, { auto: true });
+    }
+    markFixed(id, caller, summary) {
+        const note = store.markFixed(this.options.root(), id, caller, summary);
+        this.changed(note.delivery?.sessionId ?? null, [id]);
+        return note;
+    }
+}

package/dist/sdk/annotations/inspect.d.ts

@@ -0,0 +1,10 @@
+import type { AnnotationCapture, InspectState } from "./capture.js";
+import type { NoteDeliveries, SendResult } from "./delivery.js";
+import type { Note } from "./store.js";
+export interface InspectStep extends Omit<InspectState, 'result'> {
+    note: Note | null;
+    send: SendResult | null;
+    /** What the person was told in the page. */
+    message: string | null;
+}
+export declare function inspectStep(capture: AnnotationCapture, notes: NoteDeliveries, key: string, sessionId: string | null, surface: string): Promise<InspectStep>;

package/dist/sdk/annotations/inspect.js

@@ -0,0 +1,33 @@
+// One step of the inspector loop (PROP-0018), shared by the terminal and a host: read the next
+// comment from the capture target, keep it as a note, act on the button the person pressed, and
+// tell them in the page what happened. Whether a send goes straight to the agent depends on where
+// the comment came from, never on what the page or a client claims.
+import { now } from "../core/fs.js";
+function message(action, note, send, sessionId) {
+    if (action === 'save' || !sessionId)
+        return 'Annotation saved';
+    if (action === 'queue')
+        return 'Added to the agent\'s queue';
+    if (note.delivery?.confirm)
+        return 'Queued — confirm sending it in the panel';
+    if (send?.state === 'sent')
+        return 'Sent to the agent';
+    if (send?.state === 'busy')
+        return 'Queued — it goes to the agent when it finishes';
+    return 'Sending to the agent';
+}
+export async function inspectStep(capture, notes, key, sessionId, surface) {
+    const state = await capture.next(key);
+    const { result, ...rest } = state;
+    if (!result)
+        return { ...rest, note: null, send: null, message: null };
+    const action = sessionId ? result.action : 'save';
+    const { note, send } = await notes.createAndAct({
+        source: { url: result.url, title: result.title, capturedAt: now(), surface, representationHint: result.documentId, ...(state.app ? { app: state.app } : {}) },
+        target: result.target,
+        body: result.body
+    }, action, sessionId, state.trusted);
+    const text = message(action, note, send, sessionId);
+    await capture.toast(key, text).catch(() => undefined);
+    return { ...rest, note, send, message: text };
+}

package/dist/sdk/annotations/isolated.d.ts

@@ -0,0 +1,6 @@
+import type { Page } from 'playwright-core';
+/** Evaluates `expression` (which yields a JSON string) and says whether the page could have reached it. */
+export declare function evaluateIsolated(page: Page, expression: string): Promise<{
+    reply: unknown;
+    trusted: boolean;
+}>;

package/dist/sdk/annotations/isolated.js

@@ -0,0 +1,51 @@
+const WORLD = 'harness-page-notes';
+const worlds = new WeakMap();
+const watched = new WeakSet();
+async function createWorld(page) {
+    const cdp = await page.context().newCDPSession(page);
+    const { frameTree } = await cdp.send('Page.getFrameTree');
+    const { executionContextId } = await cdp.send('Page.createIsolatedWorld', { frameId: frameTree.frame.id, worldName: WORLD, grantUniveralAccess: false });
+    const world = { cdp, contextId: executionContextId };
+    worlds.set(page, world);
+    if (!watched.has(page)) {
+        watched.add(page);
+        // A new document destroys the world; the next call makes another.
+        page.on('framenavigated', (frame) => {
+            if (frame !== page.mainFrame())
+                return;
+            const old = worlds.get(page);
+            worlds.delete(page);
+            void old?.cdp.detach().catch(() => undefined);
+        });
+    }
+    return world;
+}
+/** Evaluates `expression` (which yields a JSON string) and says whether the page could have reached it. */
+export async function evaluateIsolated(page, expression) {
+    if (typeof page.context !== 'function' || typeof page.context().newCDPSession !== 'function') {
+        return { reply: await page.evaluate(expression), trusted: false };
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let world = worlds.get(page) ?? null;
+        try {
+            world ??= await createWorld(page);
+            const evaluated = await world.cdp.send('Runtime.evaluate', { expression, contextId: world.contextId, returnByValue: true, awaitPromise: false });
+            if (evaluated.exceptionDetails)
+                throw new Error(evaluated.exceptionDetails.text || 'The page helper failed.');
+            return { reply: evaluated.result?.value, trusted: true };
+        }
+        catch (error) {
+            lastError = error;
+            worlds.delete(page);
+            void world?.cdp.detach().catch(() => undefined);
+            // A context that went away with a navigation is made again once; anything else falls back.
+            if (attempt === 0 && /context|target closed|detached/i.test(String(error)))
+                continue;
+            break;
+        }
+    }
+    if (/closed/i.test(String(lastError)))
+        throw lastError;
+    return { reply: await page.evaluate(expression), trusted: false };
+}

package/dist/sdk/annotations/pageScript.d.ts

@@ -0,0 +1,28 @@
+/** The helper's source. `__ARGS__` is replaced with one JSON operation; the expression evaluates to a JSON string. */
+export declare const PAGE_SCRIPT: string;
+export type PageOperation = {
+    operation: 'identity';
+} | {
+    operation: 'begin';
+    kind: 'text' | 'element' | 'inspect';
+    captureId: string;
+} | {
+    operation: 'capture';
+    captureId: string;
+} | {
+    operation: 'next';
+    captureId: string;
+} | {
+    operation: 'toast';
+    text: string;
+} | {
+    operation: 'cancel';
+    captureId?: string;
+} | {
+    operation: 'resolve' | 'reveal';
+    target: unknown;
+};
+/** The expression to evaluate in the page for one operation. */
+export declare function pageCall(operation: PageOperation): string;
+/** Reads the helper's reply, throwing its error. */
+export declare function pageReply<T>(reply: unknown): T;