rea-agents 2.3.0 → 2.5.0

package/dist/browser/CdpCaptureStorageFingerprints.js

@@ -0,0 +1,328 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { CdpConnection } from "./CdpConnection.js";
+import { optionalCdpCommand } from "./CdpOptionalCommand.js";
+import { recordValue, recordsValue, stringValue } from "./CdpCaptureValues.js";
+const MAX_CACHE_BODY_BYTES = 64 * 1_024;
+/** Capture stable hashes of approved storage content without returning values. */
+export const captureStorageFingerprints = async ({ context, origin, local, session, indexedDbNames, caches, limitations, }) => {
+    const state = {
+        items: [],
+        maximum: context.input.limits.max_storage_keys,
+        complete: local.complete && session.complete,
+        truncated: false,
+    };
+    const run = { context, limitations, state };
+    addStorageItems(state, "local_storage", local.items);
+    addStorageItems(state, "session_storage", session.items);
+    await addCookies(run, origin);
+    await addIndexedDb(run, origin, indexedDbNames);
+    await addCaches(run, caches);
+    state.items.sort((left, right) => compareCodePoints(`${left.scope}:${left.identity_sha256}`, `${right.scope}:${right.identity_sha256}`));
+    return {
+        items: state.items,
+        complete: state.complete &&
+            !state.truncated &&
+            state.items.every(({ complete }) => complete),
+        truncated: state.truncated,
+    };
+};
+const addStorageItems = (state, scope, items) => {
+    for (const item of items)
+        addFingerprint(state, {
+            scope,
+            identity: item.key,
+            value: item.value,
+            complete: true,
+        });
+};
+const addCookies = async (run, origin) => {
+    const raw = await optionalCdpCommand(run.context, "Network.getCookies", { urls: [origin] }, run.limitations);
+    if (raw === undefined) {
+        run.state.complete = false;
+        return;
+    }
+    const cookieValues = recordValue(raw)?.cookies;
+    if (!Array.isArray(cookieValues)) {
+        run.state.complete = false;
+        return;
+    }
+    const cookies = recordsValue(cookieValues);
+    if (cookies.length !== cookieValues.length)
+        run.state.complete = false;
+    for (const cookie of cookies) {
+        const name = stringValue(cookie.name);
+        const value = stringValue(cookie.value);
+        const domain = stringValue(cookie.domain);
+        const path = stringValue(cookie.path);
+        if (name === undefined ||
+            value === undefined ||
+            domain === undefined ||
+            path === undefined) {
+            run.state.complete = false;
+            continue;
+        }
+        addFingerprint(run.state, {
+            scope: "cookie",
+            identity: {
+                domain,
+                path,
+                name,
+                partition_key: cookie.partitionKey ?? null,
+            },
+            value,
+            complete: true,
+        });
+    }
+};
+const addIndexedDb = async (run, origin, names) => {
+    for (const databaseName of names) {
+        if (run.state.items.length >= run.state.maximum) {
+            run.state.truncated = true;
+            return;
+        }
+        const raw = await optionalCdpCommand(run.context, "IndexedDB.requestDatabase", { securityOrigin: origin, databaseName }, run.limitations);
+        const database = recordValue(recordValue(raw)?.databaseWithObjectStores);
+        if (raw === undefined || database === undefined) {
+            run.state.complete = false;
+            continue;
+        }
+        if (stringValue(database.name) !== databaseName) {
+            run.state.complete = false;
+            continue;
+        }
+        if (!Array.isArray(database.objectStores)) {
+            run.state.complete = false;
+            continue;
+        }
+        const stores = recordsValue(database.objectStores);
+        if (stores.length !== database.objectStores.length)
+            run.state.complete = false;
+        addFingerprint(run.state, {
+            scope: "indexed_db_schema",
+            identity: databaseName,
+            value: stores.map(indexedDbStoreSchema),
+            complete: indexedDbSchemaComplete(stores),
+        });
+        for (const store of stores) {
+            const objectStoreName = stringValue(store.name);
+            if (objectStoreName === undefined) {
+                run.state.complete = false;
+                continue;
+            }
+            await addIndexedDbRecords(run, {
+                origin,
+                databaseName,
+                objectStoreName,
+            });
+        }
+    }
+};
+const indexedDbStoreSchema = (store) => ({
+    name: stringValue(store.name) ?? null,
+    key_path: stableValue(store.keyPath),
+    auto_increment: store.autoIncrement === true,
+    indexes: recordsValue(store.indexes).map((index) => ({
+        name: stringValue(index.name) ?? null,
+        key_path: stableValue(index.keyPath),
+        unique: index.unique === true,
+        multi_entry: index.multiEntry === true,
+    })),
+});
+const indexedDbSchemaComplete = (stores) => stores.every((store) => stringValue(store.name) !== undefined &&
+    stableValueComplete(store.keyPath) &&
+    typeof store.autoIncrement === "boolean" &&
+    Array.isArray(store.indexes) &&
+    recordsValue(store.indexes).length === store.indexes.length &&
+    recordsValue(store.indexes).every((index) => stringValue(index.name) !== undefined &&
+        stableValueComplete(index.keyPath) &&
+        typeof index.unique === "boolean" &&
+        typeof index.multiEntry === "boolean"));
+const addIndexedDbRecords = async (run, input) => {
+    const remaining = run.state.maximum - run.state.items.length;
+    if (remaining <= 0) {
+        run.state.truncated = true;
+        return;
+    }
+    const raw = await optionalCdpCommand(run.context, "IndexedDB.requestData", {
+        securityOrigin: input.origin,
+        databaseName: input.databaseName,
+        objectStoreName: input.objectStoreName,
+        indexName: "",
+        skipCount: 0,
+        pageSize: remaining,
+    }, run.limitations);
+    const result = recordValue(raw);
+    if (raw === undefined || result === undefined) {
+        run.state.complete = false;
+        return;
+    }
+    if (!Array.isArray(result.objectStoreDataEntries) ||
+        typeof result.hasMore !== "boolean") {
+        run.state.complete = false;
+        return;
+    }
+    const entries = recordsValue(result.objectStoreDataEntries);
+    if (entries.length !== result.objectStoreDataEntries.length)
+        run.state.complete = false;
+    for (const entry of entries) {
+        const key = stableValue(entry.key);
+        const primaryKey = stableValue(entry.primaryKey);
+        const value = stableValue(entry.value);
+        addFingerprint(run.state, {
+            scope: "indexed_db_record",
+            identity: {
+                database: input.databaseName,
+                store: input.objectStoreName,
+                key,
+                primaryKey,
+            },
+            value,
+            complete: remoteObjectComplete(entry.value),
+        });
+    }
+    if (result.hasMore === true || entries.length > remaining)
+        run.state.truncated = true;
+};
+const addCaches = async (run, caches) => {
+    for (const cache of caches) {
+        const remaining = run.state.maximum - run.state.items.length;
+        if (remaining <= 0) {
+            run.state.truncated = true;
+            return;
+        }
+        const raw = await optionalCdpCommand(run.context, "CacheStorage.requestEntries", { cacheId: cache.id, skipCount: 0, pageSize: remaining }, run.limitations);
+        const result = recordValue(raw);
+        if (raw === undefined || result === undefined) {
+            run.state.complete = false;
+            continue;
+        }
+        if (!Array.isArray(result.cacheDataEntries) ||
+            typeof result.returnCount !== "number") {
+            run.state.complete = false;
+            continue;
+        }
+        const entries = recordsValue(result.cacheDataEntries);
+        if (entries.length !== result.cacheDataEntries.length)
+            run.state.complete = false;
+        for (const entry of entries)
+            await addCacheEntry(run, cache, entry);
+        if (result.returnCount > entries.length)
+            run.state.truncated = true;
+    }
+};
+const addCacheEntry = async (run, cache, entry) => {
+    const requestURL = stringValue(entry.requestURL);
+    const requestMethod = stringValue(entry.requestMethod);
+    if (requestURL === undefined || requestMethod === undefined) {
+        run.state.complete = false;
+        return;
+    }
+    if (!Array.isArray(entry.requestHeaders)) {
+        run.state.complete = false;
+        return;
+    }
+    const headerRecords = recordsValue(entry.requestHeaders);
+    const requestHeaders = headerRecords.flatMap((header) => {
+        const name = stringValue(header.name);
+        const value = stringValue(header.value);
+        return name === undefined || value === undefined ? [] : [{ name, value }];
+    });
+    if (headerRecords.length !== entry.requestHeaders.length ||
+        requestHeaders.length !== headerRecords.length) {
+        run.state.complete = false;
+        return;
+    }
+    const raw = await optionalCdpCommand(run.context, "CacheStorage.requestCachedResponse", { cacheId: cache.id, requestURL, requestHeaders }, run.limitations);
+    const body = stringValue(recordValue(recordValue(raw)?.response)?.body);
+    const decoded = body === undefined ? null : decodeBase64(body);
+    const complete = decoded !== null && decoded.byteLength <= MAX_CACHE_BODY_BYTES;
+    if (!complete)
+        run.state.complete = false;
+    addFingerprint(run.state, {
+        scope: "cache_entry",
+        identity: { cache: cache.name, requestURL, requestMethod, requestHeaders },
+        value: decoded ?? undefined,
+        complete,
+    });
+};
+const addFingerprint = (state, input) => {
+    if (state.items.length >= state.maximum) {
+        state.truncated = true;
+        return;
+    }
+    state.items.push({
+        scope: input.scope,
+        identity_sha256: digest(input.identity),
+        value_sha256: input.value === undefined ? null : digest(input.value),
+        complete: input.complete &&
+            stableValueComplete(input.identity) &&
+            stableValueComplete(input.value),
+    });
+};
+const digest = (value) => createHash("sha256").update(encodedValue(value)).digest("hex");
+const encodedValue = (value) => {
+    if (value instanceof Uint8Array)
+        return value;
+    const encoded = canonicalize(stableValue(value));
+    if (encoded === undefined)
+        throw new TypeError("Expected canonical JSON");
+    return encoded;
+};
+const stableValue = (value, depth = 0) => {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean")
+        return value;
+    if (depth >= 8)
+        return "<depth-limit>";
+    if (Array.isArray(value))
+        return value.slice(0, 64).map((item) => stableValue(item, depth + 1));
+    const record = recordValue(value);
+    if (record === undefined)
+        return String(value);
+    return Object.fromEntries(Object.entries(record)
+        .filter(([key]) => key !== "objectId" && key !== "customPreview")
+        .sort(([left], [right]) => compareCodePoints(left, right))
+        .slice(0, 64)
+        .map(([key, item]) => [key, stableValue(item, depth + 1)]));
+};
+const stableValueComplete = (value, depth = 0) => {
+    if (value instanceof Uint8Array)
+        return true;
+    if (value === null ||
+        value === undefined ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean")
+        return true;
+    if (depth >= 8)
+        return false;
+    if (Array.isArray(value))
+        return (value.length <= 64 &&
+            value.every((item) => stableValueComplete(item, depth + 1)));
+    const record = recordValue(value);
+    if (record === undefined)
+        return false;
+    const entries = Object.entries(record).filter(([key]) => key !== "objectId" && key !== "customPreview");
+    return (entries.length <= 64 &&
+        entries.every(([, item]) => stableValueComplete(item, depth + 1)));
+};
+const remoteObjectComplete = (value) => {
+    const record = recordValue(value);
+    if (record === undefined)
+        return true;
+    return (record.objectId === undefined &&
+        record.preview === undefined &&
+        record.customPreview === undefined &&
+        (record.type !== "object" || record.value !== undefined) &&
+        stableValueComplete(record));
+};
+const decodeBase64 = (value) => {
+    if (value.length % 4 !== 0 ||
+        !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value))
+        return null;
+    return Buffer.from(value, "base64");
+};
+const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/browser/CdpEndpoint.js

@@ -24,10 +24,10 @@ const endpointTargetSchema = z.object({
 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);
+    const versionInput = await readBoundedCdpJson(new URL("/json/version", endpoint), MAX_VERSION_BYTES, operation, signal);
+    const targetsInput = await readBoundedCdpJson(new URL("/json/list", endpoint), MAX_TARGET_LIST_BYTES, operation, signal);
+    const version = parseCdpEndpointValue(endpointVersionSchema, versionInput, operation);
+    const targets = parseCdpEndpointValue(endpointTargetsSchema, targetsInput, operation);
     return {
         webSocket: safeCdpWebSocketEndpoint(endpoint, version.webSocketDebuggerUrl, operation),
         version: {
@@ -110,7 +110,8 @@ const availableCdpTargetWebSocket = (discovery, target) => {
         ? discovery.webSocket
         : undefined;
 };
-const parseEndpointValue = (schema, input, operation) => {
+/** Parse one CDP discovery value through its exact boundary schema. */
+export const parseCdpEndpointValue = (schema, input, operation) => {
     const parsed = schema.safeParse(input);
     if (!parsed.success)
         throw new BrowserObservationError(operation, "invalid_endpoint_response", {
@@ -173,7 +174,8 @@ const targetWebSocket = (endpoint, target, operation) => {
         return {};
     }
 };
-const readJson = async (url, maximumBytes, operation, signal) => await new Promise((resolve, reject) => {
+/** Read one bounded loopback CDP discovery document without redirects. */
+export const readBoundedCdpJson = async (url, maximumBytes, operation, signal) => await new Promise((resolve, reject) => {
     if (signal?.aborted === true) {
         reject(new AnalysisCancelledError(operation));
         return;

package/dist/browser/CdpPageCapture.js

@@ -226,6 +226,8 @@ const accessibilityForFrames = async (state, frames) => {
         events.completeness.exclude("accessibility", "not_approved", capture.textCapture.excluded_fields);
     if (capture.textCapture.status === "truncated")
         events.completeness.truncate("accessibility");
+    if (capture.treeIncomplete)
+        events.completeness.truncate("accessibility");
     return capture;
 };
 const publicResource = ({ rawUrl: _rawUrl, ...resource }) => resource;

package/dist/browser/JavaScriptRuntimeScope.js

@@ -0,0 +1,38 @@
+import { browserOriginSchema, sanitizeBrowserUrl, } from "../domain/browserObservation.js";
+import { authorizedElectronFile, canonicalElectronRoots, } from "./ElectronFileScope.js";
+/** Canonicalize exact filesystem scopes before Inspector attachment. */
+export const canonicalRuntimeRoots = canonicalElectronRoots;
+/** Authorize one protocol URL without retaining an out-of-scope value. */
+export const authorizeRuntimeLocation = async (value, roots, origins) => {
+    if (value.startsWith("node:") && value.length <= 4_096)
+        return {
+            allowed: true,
+            location: { kind: "builtin", specifier: value },
+        };
+    if (value.startsWith("file:")) {
+        const filePath = await authorizedElectronFile(value, roots);
+        return filePath === undefined
+            ? { allowed: false, reason: "outside_file_roots" }
+            : { allowed: true, location: { kind: "file", file_path: filePath } };
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { allowed: false, reason: "unsupported_location" };
+    }
+    if (!["http:", "https:"].includes(url.protocol))
+        return { allowed: false, reason: "unsupported_location" };
+    const parsedOrigin = browserOriginSchema.safeParse(url.origin);
+    if (!parsedOrigin.success || !origins.includes(parsedOrigin.data))
+        return { allowed: false, reason: "outside_origins" };
+    return {
+        allowed: true,
+        location: {
+            kind: "url",
+            origin: parsedOrigin.data,
+            sanitized_url: sanitizeBrowserUrl(value).url,
+        },
+    };
+};

package/dist/browser/PlaywrightBrowserScenarioProvider.js

@@ -0,0 +1,253 @@
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { browserScenarioCaptureSchema, browserScenarioCompletenessSchema, browserScenarioStepSchema, browserStepArtifactsSchema, } from "../domain/browserScenarioCapture.js";
+import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { BrowserScenarioCaptureBudget } from "./PlaywrightScenarioArtifacts.js";
+import { PlaywrightScenarioSessionFactory } from "./PlaywrightScenarioSession.js";
+const OPERATION = "capture_browser_scenario";
+export const PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-playwright-browser-scenario",
+    name: "REA Playwright browser scenario capture provider",
+    version: "1",
+});
+const requestedForStep = (scenario, stepIndex) => new Set([
+    ...scenario.capture.after_each_step,
+    ...(stepIndex === scenario.actions.length ? scenario.capture.at_end : []),
+]);
+const unavailableArtifacts = (requested, reason) => {
+    const state = (kind) => requested.has(kind)
+        ? { state: "missing", reason }
+        : { state: "not_requested" };
+    return browserStepArtifactsSchema.parse({
+        screenshot: state("screenshot"),
+        dom: state("dom"),
+        accessibility: state("accessibility"),
+        url: state("url"),
+        history: state("history"),
+        storage: state("storage"),
+    });
+};
+const stepCompleteness = (artifacts, status) => {
+    const missing = Object.entries(artifacts)
+        .filter(([, state]) => state.state === "missing")
+        .map(([section]) => section);
+    const truncated = Object.entries(artifacts)
+        .filter(([, state]) => state.state === "truncated")
+        .map(([section]) => section);
+    if (status !== "completed")
+        missing.push("action");
+    const condition = truncated.length > 0
+        ? "truncated"
+        : missing.length > 0
+            ? "incomplete"
+            : "complete";
+    return browserScenarioCompletenessSchema.parse({
+        status: condition,
+        equality_eligible: condition === "complete",
+        missing_sections: [...new Set(missing)].sort(),
+        truncated_sections: [...new Set(truncated)].sort(),
+    });
+};
+const createStep = (input) => browserScenarioStepSchema.parse({
+    step_index: input.stepIndex,
+    step_id: input.stepId,
+    action: input.action,
+    status: input.status,
+    elapsed_ms: input.elapsedMs,
+    before_url: sanitizeBrowserUrl(input.beforeUrl),
+    after_url: sanitizeBrowserUrl(input.afterUrl),
+    error: input.error,
+    event_sequence_start: input.eventStart,
+    event_sequence_end: input.eventEnd,
+    artifacts: input.artifacts,
+    completeness: stepCompleteness(input.artifacts, input.status),
+});
+const initialStep = async (input) => {
+    const { session, scenario, budget, elapsedMs, maximumTimeoutMs, signal } = input;
+    const artifacts = await session.capture(requestedForStep(scenario, 0), budget, maximumTimeoutMs, signal);
+    return createStep({
+        stepIndex: 0,
+        stepId: "scenario_start",
+        action: "goto_start",
+        status: "completed",
+        elapsedMs,
+        beforeUrl: session.initialUrl,
+        afterUrl: session.currentUrl(),
+        error: null,
+        eventStart: 1,
+        eventEnd: session.lastEventSequence(),
+        artifacts,
+    });
+};
+const executeStep = async (input) => {
+    const { session, scenario, budget, action, stepIndex, startedAt, priorFailure, signal, } = input;
+    const beforeUrl = session.currentUrl();
+    const eventStart = session.nextEventSequence();
+    const requested = requestedForStep(scenario, stepIndex);
+    if (priorFailure)
+        return createStep({
+            stepIndex,
+            stepId: action.step_id,
+            action: action.action,
+            status: "cancelled",
+            elapsedMs: 0,
+            beforeUrl,
+            afterUrl: beforeUrl,
+            error: "not executed after an earlier action failure",
+            eventStart,
+            eventEnd: session.lastEventSequence(),
+            artifacts: unavailableArtifacts(requested, "action was not executed after an earlier failure"),
+        });
+    const actionStartedAt = Date.now();
+    session.setStep(stepIndex);
+    const requestCancelled = () => signal?.aborted === true;
+    let status = "completed";
+    let error = null;
+    if (requestCancelled()) {
+        status = "cancelled";
+        error = "scenario request cancelled";
+    }
+    else {
+        try {
+            const elapsed = Date.now() - startedAt;
+            const remaining = scenario.limits.max_duration_ms - elapsed;
+            if (remaining <= 0)
+                throw new Error("Scenario duration limit reached");
+            await session.perform(action, remaining, signal);
+        }
+        catch (cause) {
+            status = requestCancelled() ? "cancelled" : "failed";
+            error = session.redactError(cause);
+        }
+    }
+    const remaining = scenario.limits.max_duration_ms - (Date.now() - startedAt);
+    const artifacts = status === "cancelled" || remaining <= 0
+        ? unavailableArtifacts(requested, status === "cancelled"
+            ? "scenario request cancelled"
+            : "scenario duration limit reached")
+        : await session.capture(requested, budget, remaining, signal);
+    return createStep({
+        stepIndex,
+        stepId: action.step_id,
+        action: action.action,
+        status,
+        elapsedMs: Date.now() - actionStartedAt,
+        beforeUrl,
+        afterUrl: session.currentUrl(),
+        error,
+        eventStart,
+        eventEnd: session.lastEventSequence(),
+        artifacts,
+    });
+};
+const globalCompleteness = (scenario, session, steps) => {
+    const missing = steps.flatMap(({ completeness }) => completeness.missing_sections);
+    const truncated = steps.flatMap(({ completeness }) => completeness.truncated_sections);
+    truncated.push(...session.eventTruncationSections());
+    if (session.mode === "connect")
+        missing.push("events");
+    const status = truncated.length > 0
+        ? "truncated"
+        : missing.length > 0
+            ? "incomplete"
+            : "complete";
+    return browserScenarioCompletenessSchema.parse({
+        status,
+        equality_eligible: status === "complete",
+        missing_sections: [...new Set(missing)].sort(),
+        truncated_sections: [...new Set(truncated)].sort(),
+    });
+};
+const runScenario = async (factory, scenario, options) => {
+    if (options.signal?.aborted === true)
+        throw new BrowserObservationError(OPERATION, "cancelled");
+    const startedAt = Date.now();
+    const budget = new BrowserScenarioCaptureBudget(scenario.limits.max_screenshots, scenario.limits.max_total_metadata_bytes);
+    const session = await factory.open(scenario, {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        budget,
+        deadlineAt: startedAt + scenario.limits.max_duration_ms,
+    });
+    const steps = [];
+    let cleanup;
+    try {
+        steps.push(await initialStep({
+            session,
+            scenario,
+            budget,
+            elapsedMs: Date.now() - startedAt,
+            maximumTimeoutMs: scenario.limits.max_duration_ms - (Date.now() - startedAt),
+            signal: options.signal,
+        }));
+        let failed = false;
+        for (const [offset, action] of scenario.actions.entries()) {
+            const step = await executeStep({
+                session,
+                scenario,
+                budget,
+                action,
+                stepIndex: offset + 1,
+                startedAt,
+                priorFailure: failed,
+                signal: options.signal,
+            });
+            steps.push(step);
+            failed ||= step.status !== "completed";
+        }
+    }
+    finally {
+        cleanup = await session.close();
+    }
+    const events = session.events();
+    const completeness = globalCompleteness(scenario, session, steps);
+    return browserScenarioCaptureSchema.parse({
+        schema_version: 1,
+        browser: {
+            mode: session.mode,
+            process_ownership: session.processOwnership,
+            cleanup,
+            product: session.product,
+            version: session.version,
+        },
+        scenario: {
+            start_origin: new URL(scenario.start_url.url).origin,
+            allowed_origins: scenario.allowed_origins,
+            action_count: scenario.actions.length,
+            secret_references: scenario.secrets.map(({ secret_id: id }) => id).sort(),
+        },
+        duration_ms: Date.now() - startedAt,
+        steps,
+        events,
+        completeness,
+        limitations: [
+            "Event sequence records provider receipt order; simultaneous browser causality is not inferred.",
+            "Response bodies are not retained.",
+            "Storage values are hashed only after declared-secret redaction.",
+            ...(session.mode === "connect"
+                ? [
+                    "CDP attachment cannot recover pre-attach events or guarantee launch-time context options.",
+                ]
+                : []),
+        ],
+    });
+};
+/** Controlled Playwright/CDP scenario driver with exact process ownership. */
+export class PlaywrightBrowserScenarioProvider {
+    factory;
+    constructor(factory = new PlaywrightScenarioSessionFactory()) {
+        this.factory = factory;
+    }
+    identity() {
+        return PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY;
+    }
+    async captureScenario(scenario, options = {}) {
+        try {
+            return ok(await runScenario(this.factory, scenario, options));
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return err(cause);
+            return err(new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause }));
+        }
+    }
+}