rea-agents 1.3.0 → 1.5.0

package/dist/browser/CdpConnection.js

@@ -0,0 +1,218 @@
+import WebSocket, {} from "ws";
+import { AnalysisCancelledError, AnalysisError, AnalysisTimeoutError, BrowserObservationError, } from "../domain/errors.js";
+const CONNECT_TIMEOUT_MS = 5_000;
+const COMMAND_TIMEOUT_MS = 5_000;
+const MAX_PAYLOAD_BYTES = 16 * 1_024 * 1_024;
+const MAX_PENDING_COMMANDS = 128;
+/** Correlated, bounded JSON-RPC transport for a browser-level CDP socket. */
+export class CdpConnection {
+    socket;
+    #pending = new Map();
+    #listeners = new Set();
+    #nextId = 1;
+    #closed = false;
+    #protocolFailed = false;
+    constructor(socket) {
+        this.socket = socket;
+        socket.on("message", (data) => this.#receive(data));
+        socket.on("close", () => this.#failPending("disconnected"));
+        socket.on("error", () => this.#failPending("disconnected"));
+    }
+    /** Connect to one already-validated loopback browser WebSocket. */
+    static async connect(url, signal) {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError("inspect_web_page");
+        const socket = new WebSocket(url, {
+            handshakeTimeout: CONNECT_TIMEOUT_MS,
+            maxPayload: MAX_PAYLOAD_BYTES,
+            perMessageDeflate: false,
+        });
+        await waitForOpen(socket, signal);
+        return new CdpConnection(socket);
+    }
+    /** Subscribe to validated CDP event envelopes. */
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /** Execute one bounded command, optionally within a flat target session. */
+    async send(method, params = {}, sessionId, signal) {
+        if (this.#protocolFailed)
+            throw new BrowserObservationError("inspect_web_page", "protocol_error");
+        if (this.#closed || this.socket.readyState !== WebSocket.OPEN)
+            throw new BrowserObservationError("inspect_web_page", "disconnected");
+        if (this.#pending.size >= MAX_PENDING_COMMANDS)
+            throw new BrowserObservationError("inspect_web_page", "payload_limit");
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError("inspect_web_page");
+        const id = this.#nextId;
+        this.#nextId += 1;
+        return await new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const pending = this.#pending.get(id);
+                if (pending === undefined)
+                    return;
+                clearTimeout(pending.timer);
+                pending.removeAbort();
+                this.#pending.delete(id);
+                reject(new AnalysisCancelledError("inspect_web_page"));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                this.#pending.delete(id);
+                reject(new AnalysisTimeoutError("inspect_web_page", COMMAND_TIMEOUT_MS));
+            }, COMMAND_TIMEOUT_MS);
+            this.#pending.set(id, {
+                resolve,
+                reject,
+                timer,
+                removeAbort: () => signal?.removeEventListener("abort", onAbort),
+            });
+            this.socket.send(JSON.stringify({
+                id,
+                method,
+                params,
+                ...(sessionId ? { sessionId } : {}),
+            }), (error) => {
+                if (error === undefined || error === null)
+                    return;
+                const pending = this.#pending.get(id);
+                if (pending === undefined)
+                    return;
+                this.#complete(id, pending);
+                reject(new BrowserObservationError("inspect_web_page", "disconnected", {
+                    cause: error,
+                }));
+            });
+        });
+    }
+    /** Close only REA's socket; never close the browser or selected page. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#failPending("disconnected");
+        if (this.socket.readyState === WebSocket.CLOSED)
+            return;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.socket.terminate();
+                resolve();
+            }, 1_000);
+            this.socket.once("close", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            this.socket.close();
+        });
+    }
+    #receive(data) {
+        let message;
+        try {
+            message = JSON.parse(rawText(data));
+        }
+        catch {
+            this.#failPending("protocol_error");
+            return;
+        }
+        if (!isRecord(message)) {
+            this.#failPending("protocol_error");
+            return;
+        }
+        if ("id" in message) {
+            if (typeof message.id !== "number" ||
+                !Number.isSafeInteger(message.id) ||
+                message.id < 1) {
+                this.#failPending("protocol_error");
+                return;
+            }
+            this.#receiveResponse(message, message.id);
+            return;
+        }
+        if (typeof message.method !== "string" ||
+            message.method.length === 0 ||
+            ("params" in message && !isRecord(message.params)) ||
+            ("sessionId" in message && typeof message.sessionId !== "string")) {
+            this.#failPending("protocol_error");
+            return;
+        }
+        const event = {
+            method: message.method,
+            params: "params" in message ? message.params : {},
+            ...(typeof message.sessionId === "string"
+                ? { sessionId: message.sessionId }
+                : {}),
+        };
+        for (const listener of this.#listeners)
+            listener(event);
+    }
+    #receiveResponse(message, id) {
+        const pending = this.#pending.get(id);
+        if (pending === undefined)
+            return;
+        this.#complete(id, pending);
+        if ("error" in message) {
+            pending.reject(new BrowserObservationError("inspect_web_page", "protocol_error"));
+            return;
+        }
+        pending.resolve("result" in message ? message.result : {});
+    }
+    #complete(id, pending) {
+        clearTimeout(pending.timer);
+        pending.removeAbort();
+        this.#pending.delete(id);
+    }
+    #failPending(reason) {
+        if (reason === "disconnected")
+            this.#closed = true;
+        else
+            this.#protocolFailed = true;
+        for (const [id, pending] of this.#pending) {
+            this.#complete(id, pending);
+            pending.reject(new BrowserObservationError("inspect_web_page", reason));
+        }
+    }
+}
+const rawText = (data) => Array.isArray(data)
+    ? Buffer.concat(data).toString("utf8")
+    : Buffer.isBuffer(data)
+        ? data.toString("utf8")
+        : Buffer.from(data).toString("utf8");
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const waitForOpen = async (socket, signal) => await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+        cleanup();
+        terminateSocket(socket);
+        reject(new AnalysisTimeoutError("inspect_web_page", CONNECT_TIMEOUT_MS));
+    }, CONNECT_TIMEOUT_MS);
+    const onOpen = () => {
+        cleanup();
+        resolve();
+    };
+    const onFailure = (cause) => {
+        cleanup();
+        reject(signal?.aborted === true
+            ? new AnalysisCancelledError("inspect_web_page")
+            : new BrowserObservationError("inspect_web_page", "endpoint_unreachable", { cause }));
+    };
+    const onAbort = () => {
+        terminateSocket(socket);
+        onFailure(new AnalysisCancelledError("inspect_web_page"));
+    };
+    const cleanup = () => {
+        clearTimeout(timer);
+        socket.off("open", onOpen);
+        socket.off("error", onFailure);
+        signal?.removeEventListener("abort", onAbort);
+    };
+    socket.once("open", onOpen);
+    socket.once("error", onFailure);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted === true)
+        onAbort();
+});
+const terminateSocket = (socket) => {
+    socket.once("error", () => undefined);
+    socket.terminate();
+};

package/dist/browser/CdpEndpoint.js

@@ -0,0 +1,114 @@
+import { request } from "node:http";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisError, AnalysisTimeoutError, BrowserObservationError, } from "../domain/errors.js";
+const HTTP_TIMEOUT_MS = 5_000;
+const MAX_VERSION_BYTES = 64 * 1_024;
+const MAX_TARGET_LIST_BYTES = 2 * 1_024 * 1_024;
+const endpointVersionSchema = z.object({
+    Browser: z.string().min(1).max(1_024),
+    "Protocol-Version": z.string().min(1).max(100),
+    "User-Agent": z.string().max(16_384),
+    "V8-Version": z.string().max(1_024),
+    "WebKit-Version": z.string().max(1_024),
+    webSocketDebuggerUrl: z.string().min(1).max(2_048),
+});
+const endpointTargetSchema = z.object({
+    id: z.string().min(1).max(256),
+    type: z.string().min(1).max(100),
+    title: z.string().max(16_384).default(""),
+    url: z.string().max(65_536),
+    attached: z.boolean().default(false),
+});
+const endpointTargetsSchema = z.array(endpointTargetSchema).max(1_000);
+/** Read bounded CDP discovery endpoints without following redirects. */
+export const discoverCdpEndpoint = async (endpoint, operation, signal) => {
+    const versionInput = await readJson(new URL("/json/version", endpoint), MAX_VERSION_BYTES, operation, signal);
+    const targetsInput = await readJson(new URL("/json/list", endpoint), MAX_TARGET_LIST_BYTES, operation, signal);
+    const version = parseEndpointValue(endpointVersionSchema, versionInput, operation);
+    const targets = parseEndpointValue(endpointTargetsSchema, targetsInput, operation);
+    return {
+        browserWebSocketUrl: safeBrowserWebSocketUrl(endpoint, version.webSocketDebuggerUrl, operation),
+        version: {
+            product: version.Browser,
+            protocol_version: version["Protocol-Version"],
+            revision: version["WebKit-Version"],
+            user_agent: version["User-Agent"],
+            js_version: version["V8-Version"],
+        },
+        targets,
+    };
+};
+const parseEndpointValue = (schema, input, operation) => {
+    const parsed = schema.safeParse(input);
+    if (!parsed.success)
+        throw new BrowserObservationError(operation, "invalid_endpoint_response", {
+            cause: parsed.error,
+        });
+    return parsed.data;
+};
+const safeBrowserWebSocketUrl = (endpoint, reported, operation) => {
+    let parsed;
+    try {
+        parsed = new URL(reported);
+    }
+    catch (cause) {
+        throw new BrowserObservationError(operation, "invalid_endpoint_response", {
+            cause,
+        });
+    }
+    const trustedEndpoint = new URL(endpoint);
+    if (parsed.protocol !== "ws:" ||
+        parsed.port !== trustedEndpoint.port ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        parsed.search !== "" ||
+        parsed.hash !== "" ||
+        !parsed.pathname.startsWith("/devtools/browser/"))
+        throw new BrowserObservationError(operation, "invalid_endpoint_response");
+    parsed.hostname = trustedEndpoint.hostname;
+    return parsed.href;
+};
+const readJson = async (url, maximumBytes, operation, signal) => await new Promise((resolve, reject) => {
+    if (signal?.aborted === true) {
+        reject(new AnalysisCancelledError(operation));
+        return;
+    }
+    const request_ = request(url, { method: "GET", signal, headers: { Accept: "application/json" } }, (response) => {
+        if (response.statusCode !== 200) {
+            response.resume();
+            reject(new BrowserObservationError(operation, "invalid_endpoint_response"));
+            return;
+        }
+        const chunks = [];
+        let bytes = 0;
+        response.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > maximumBytes) {
+                response.destroy(new BrowserObservationError(operation, "payload_limit"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        response.on("end", () => {
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch (cause) {
+                reject(new BrowserObservationError(operation, "invalid_endpoint_response", { cause }));
+            }
+        });
+        response.on("error", (cause) => reject(endpointFailure(cause, operation, signal)));
+    });
+    request_.setTimeout(HTTP_TIMEOUT_MS, () => request_.destroy(new AnalysisTimeoutError(operation, HTTP_TIMEOUT_MS)));
+    request_.on("error", (cause) => reject(endpointFailure(cause, operation, signal)));
+    request_.end();
+});
+const endpointFailure = (cause, operation, signal) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (signal?.aborted === true)
+        return new AnalysisCancelledError(operation);
+    return new BrowserObservationError(operation, "endpoint_unreachable", {
+        cause,
+    });
+};

package/dist/browser/CdpOptionalCommand.js

@@ -0,0 +1,15 @@
+import { BrowserObservationError } from "../domain/errors.js";
+import { CdpConnection } from "./CdpConnection.js";
+/** Execute an optional CDP method while preserving transport and cancellation failures. */
+export const optionalCdpCommand = async (context, method, parameters, limitations) => {
+    try {
+        return await context.connection.send(method, parameters, context.sessionId, context.signal);
+    }
+    catch (cause) {
+        if (!(cause instanceof BrowserObservationError) ||
+            cause.reason !== "protocol_error")
+            throw cause;
+        limitations.push(`${method} was unavailable from this browser target.`);
+        return undefined;
+    }
+};

package/dist/browser/CdpPageCapture.js

@@ -0,0 +1,273 @@
+import { BrowserObservationError } from "../domain/errors.js";
+import { CdpConnection } from "./CdpConnection.js";
+import { CdpCaptureEvents } from "./CdpCaptureEvents.js";
+import { captureStorage } from "./CdpCaptureStorage.js";
+import { optionalCdpCommand } from "./CdpOptionalCommand.js";
+import { captureAccessibility, captureDom, captureFrames, captureResources, mainFrameUrl, } from "./CdpCaptureDocuments.js";
+import { allowedSanitizedUrl, delayWithCancellation, isHttpUrl, recordValue, recordsValue, requiredRecord, sourceExcluded, sourceResult, stringValue, } from "./CdpCaptureValues.js";
+/** Capture and normalize one attached page without evaluating page JavaScript. */
+export const capturePage = async (context) => {
+    const allowedOrigins = new Set(context.input.allowed_origins);
+    const events = new CdpCaptureEvents(context.input, allowedOrigins);
+    const removeListener = context.connection.onEvent((event) => {
+        if (event.sessionId !== context.sessionId)
+            return;
+        events.ingest(event);
+    });
+    const state = {
+        context,
+        events,
+        allowedOrigins,
+        limitations: [
+            "Observation starts when REA attaches; prior network and console activity is unavailable.",
+            "Network headers, request bodies, response bodies, cookies, storage values, console values, and WebSocket payloads are not retained.",
+            "Source maps are reported only as declarative URLs and are not fetched.",
+            "URL-less scripts and console events without an allowed source URL are excluded because their origin cannot be proven.",
+        ],
+        truncatedSections: new Set(),
+        startedAt: new Date().toISOString(),
+    };
+    try {
+        return await captureAuthorizedPage(state);
+    }
+    finally {
+        removeListener();
+    }
+};
+const captureAuthorizedPage = async (state) => {
+    const { context, allowedOrigins, limitations, truncatedSections } = state;
+    const { connection, sessionId, input, signal } = context;
+    await authorizeObservationWindow(state);
+    const frameResult = await authorizedFrameTree(context, allowedOrigins);
+    const attachedUrl = mainFrameUrl(frameResult) ?? "";
+    const frameCapture = captureFrames(frameResult, allowedOrigins, input.limits.max_frames);
+    const frames = frameCapture.items;
+    if (frameCapture.total > frames.length)
+        truncatedSections.add("frames");
+    const captureFrame = frames[0];
+    if (captureFrame === undefined)
+        throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+    state.events.beginFinalCapture(captureFrame.frame_id);
+    const resourceCapture = captureResources(await connection.send("Page.getResourceTree", {}, sessionId, signal), allowedOrigins, input.limits.max_resources);
+    if (resourceCapture.total > resourceCapture.items.length)
+        truncatedSections.add("resources");
+    const dom = await capturePageDom(state);
+    if (dom.total > dom.nodes.length)
+        truncatedSections.add("dom");
+    const accessibility = await accessibilityForFrames(context, frames, limitations);
+    if (accessibility.total > accessibility.nodes.length)
+        truncatedSections.add("accessibility");
+    const scripts = await captureScripts(context, state.events, truncatedSections);
+    const workerCapture = await captureWorkers(context, allowedOrigins, new Set(frames.map((frame) => frame.frame_id)), limitations);
+    if (workerCapture.total > workerCapture.items.length)
+        truncatedSections.add("workers");
+    const storageCapture = await captureStorage(context, frames[0]?.origin ?? new URL(attachedUrl).origin, limitations);
+    if (storageCapture.truncated)
+        truncatedSections.add("storage_keys");
+    if (state.events.dropped > 0)
+        truncatedSections.add("events");
+    const completedFrameResult = await authorizedFrameTree(context, allowedOrigins);
+    const completedUrl = mainFrameUrl(completedFrameResult) ?? "";
+    if (state.events.originViolation)
+        throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+    if (state.events.navigationDuringCapture || completedUrl !== attachedUrl)
+        throw new BrowserObservationError("inspect_web_page", "target_changed");
+    await report(context.progress, 3, "Normalizing browser evidence");
+    return normalizedInspection(state, {
+        attachedUrl,
+        frames,
+        dom,
+        accessibility,
+        scripts,
+        resources: resourceCapture.items,
+        workers: workerCapture.items,
+        storage: storageCapture.value,
+    });
+};
+const authorizeObservationWindow = async (state) => {
+    const { context, allowedOrigins, events } = state;
+    const { connection, sessionId, signal } = context;
+    await report(context.progress, 1, "Enabling passive CDP domains");
+    await connection.send("Page.enable", {}, sessionId, signal);
+    const initialFrameResult = await authorizedFrameTree(context, allowedOrigins);
+    const mainFrame = captureFrames(initialFrameResult, allowedOrigins, 1)
+        .items[0];
+    if (mainFrame === undefined)
+        throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+    events.beginAuthorizedFrame(mainFrame.frame_id);
+    await enableObservationDomains(connection, sessionId, signal);
+    await report(context.progress, 2, "Observing page events");
+    await delayWithCancellation(context.input.observation_ms, signal);
+    if (events.originViolation)
+        throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+};
+const capturePageDom = async (state) => {
+    const { context, allowedOrigins } = state;
+    const result = await context.connection.send("DOMSnapshot.captureSnapshot", {
+        computedStyles: [],
+        includePaintOrder: false,
+        includeDOMRects: false,
+    }, context.sessionId, context.signal);
+    return captureDom(result, allowedOrigins, context.input);
+};
+const normalizedInspection = (state, captured) => ({
+    schema_version: 1,
+    browser: state.context.discovery.version,
+    target: normalizedTarget(state.context.target, captured.attachedUrl, state.allowedOrigins),
+    capture_window: {
+        started_at: state.startedAt,
+        ended_at: new Date().toISOString(),
+        observation_ms: state.context.input.observation_ms,
+    },
+    completeness: {
+        status: state.truncatedSections.size === 0 ? "complete" : "truncated",
+        truncated_sections: [...state.truncatedSections].sort(),
+        dropped_events: state.events.dropped,
+    },
+    frames: [...captured.frames],
+    dom: { total_nodes: captured.dom.total, nodes: [...captured.dom.nodes] },
+    accessibility: {
+        total_nodes: captured.accessibility.total,
+        nodes: [...captured.accessibility.nodes],
+    },
+    scripts: captured.scripts,
+    resources: [...captured.resources],
+    network: {
+        requests: [...state.events.network.values()],
+        websocket_events: [...state.events.websockets],
+        coverage_started_at: state.startedAt,
+        prior_activity_available: false,
+    },
+    console: {
+        events: [...state.events.console],
+        coverage_started_at: state.startedAt,
+        prior_activity_available: false,
+    },
+    workers: [...captured.workers],
+    storage: captured.storage,
+    limitations: state.limitations,
+});
+const authorizedFrameTree = async (context, allowedOrigins) => {
+    for (let attempt = 0; attempt < 80; attempt += 1) {
+        const result = await context.connection.send("Page.getFrameTree", {}, context.sessionId, context.signal);
+        const currentUrl = mainFrameUrl(result);
+        if (allowedSanitizedUrl(currentUrl, allowedOrigins) !== undefined)
+            return result;
+        if (isHttpUrl(currentUrl))
+            throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+        await delayWithCancellation(25, context.signal);
+    }
+    throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+};
+const enableObservationDomains = async (connection, sessionId, signal) => {
+    await connection.send("Runtime.enable", {}, sessionId, signal);
+    await connection.send("Debugger.enable", { maxScriptsCacheSize: 4 * 1_024 * 1_024 }, sessionId, signal);
+    await connection.send("Network.enable", {
+        maxTotalBufferSize: 4 * 1_024 * 1_024,
+        maxResourceBufferSize: 1_024 * 1_024,
+    }, sessionId, signal);
+};
+const accessibilityForFrames = async (context, frames, limitations) => {
+    const nodes = [];
+    let total = 0;
+    for (const frame of frames) {
+        const result = await optionalCdpCommand(context, "Accessibility.getFullAXTree", { depth: 32, frameId: frame.frame_id }, limitations);
+        if (result === undefined)
+            continue;
+        const capture = captureAccessibility([result], Math.max(0, context.input.limits.max_ax_nodes - nodes.length));
+        total += capture.total;
+        nodes.push(...capture.nodes);
+    }
+    return { total, nodes };
+};
+const captureScripts = async (context, events, truncatedSections) => {
+    let totalSourceBytes = 0;
+    const items = [];
+    for (const script of events.scripts.values()) {
+        let source = sourceExcluded("source capture was not approved");
+        if (context.input.include_script_sources) {
+            if (script.length > context.input.limits.max_script_source_bytes) {
+                source = sourceExcluded("declared script length exceeds per-script limit");
+                truncatedSections.add("script_sources");
+            }
+            else if (totalSourceBytes + script.length >
+                context.input.limits.max_total_script_source_bytes) {
+                source = sourceExcluded("total script source limit reached");
+                truncatedSections.add("script_sources");
+            }
+            else {
+                const result = requiredRecord(await context.connection.send("Debugger.getScriptSource", { scriptId: script.scriptId }, context.sessionId, context.signal));
+                const content = stringValue(result.scriptSource) ?? "";
+                const bytes = Buffer.byteLength(content);
+                if (bytes > context.input.limits.max_script_source_bytes ||
+                    totalSourceBytes + bytes >
+                        context.input.limits.max_total_script_source_bytes) {
+                    source = sourceExcluded("actual source exceeds configured byte limits");
+                    truncatedSections.add("script_sources");
+                }
+                else {
+                    source = sourceResult(content);
+                    totalSourceBytes += bytes;
+                }
+            }
+        }
+        items.push({
+            script_id: script.scriptId,
+            url: script.url,
+            origin: script.origin,
+            cdp_hash: script.hash,
+            length: script.length,
+            is_module: script.isModule,
+            language: script.language,
+            source_map_url: script.sourceMapUrl,
+            source,
+        });
+    }
+    return { total: events.scripts.size, items };
+};
+const captureWorkers = async (context, allowedOrigins, frameIds, limitations) => {
+    const result = await optionalCdpCommand({ ...context, sessionId: undefined }, "Target.getTargets", {}, limitations);
+    const items = [];
+    let total = 0;
+    for (const target of recordsValue(recordValue(result)?.targetInfos)) {
+        const type = stringValue(target.type) ?? "";
+        const url = allowedSanitizedUrl(target.url, allowedOrigins);
+        const relatedToPage = stringValue(target.openerId) === context.target.id ||
+            (stringValue(target.parentFrameId) !== undefined &&
+                frameIds.has(stringValue(target.parentFrameId) ?? ""));
+        if (!type.includes("worker") || url === undefined || !relatedToPage)
+            continue;
+        total += 1;
+        if (items.length >= context.input.limits.max_workers)
+            continue;
+        items.push({
+            target_id: (stringValue(target.targetId) ?? "").slice(0, 256),
+            type: type.slice(0, 100),
+            url: url.url,
+            origin: url.origin,
+            attached: target.attached === true,
+        });
+    }
+    return {
+        total,
+        items,
+    };
+};
+const normalizedTarget = (target, currentUrl, allowedOrigins) => {
+    const url = allowedSanitizedUrl(currentUrl, allowedOrigins);
+    return {
+        target_id: target.id,
+        type: target.type,
+        title: target.title.slice(0, 16_384),
+        url: url?.url ?? "[unsupported-url]",
+        origin: url?.origin ?? "",
+        attached: target.attached,
+    };
+};
+const report = async (progress, completed, message) => await progress?.report({
+    phase: "browser_observation",
+    completed,
+    total: 3,
+    message,
+    ...(completed === 3 ? { terminal: true } : {}),
+});