@xingular/harness 1.0.0 → 1.1.1

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;