rea-agents 1.6.0 → 2.0.0

package/dist/application/Setup.js

@@ -1,4 +1,5 @@
 import { access, copyFile, mkdir, readFile, rm, writeFile, } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { z } from "zod";
@@ -7,7 +8,7 @@ import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
-import { runDoctor, systemDoctorHost } from "./Doctor.js";
+import { runDoctor, systemDoctorHost, } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 import { installMacHopper } from "./MacHopper.js";
 import { configureDetectedClients } from "./SetupClients.js";
@@ -36,12 +37,14 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         doctor: await host.doctor(),
         remediation,
     });
-    const unsupported = await hostRemediation(host);
+    const unsupported = await hostRemediation(host, options.installHopper);
     if (unsupported !== undefined)
         return fail(unsupported);
     let hopperPath = await host.hopperPath();
-    const discovery = await discoverSetupActions(host, hopperPath);
-    const { detectedClients, installHopper, installSkill } = discovery;
+    let providerEnvironment = await initialProviderEnvironment(host, hopperPath);
+    const discovery = await discoverSetupActions(host, providerEnvironment, options.installHopper);
+    const { installHopper, installSkill } = discovery;
+    let { detectedClients } = discovery;
     plannedActions = discovery.plannedActions;
     let approved = options.approved || plannedActions.length === 0;
     let interactiveApproval = false;
@@ -59,7 +62,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             remediation: "Review the setup plan, then rerun interactively or with --yes.",
         };
     if (installHopper && (interactiveApproval || options.installHopper)) {
-        const installed = await host.installHopper();
+        const installed = await host.installHopper(options.installHopper);
         if (installed.status === "failed")
             return {
                 status: "needs_human",
@@ -71,12 +74,17 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
                 remediation: installed.remediation,
             };
         hopperPath = installed.launcherPath;
+        providerEnvironment = {
+            ...providerEnvironment,
+            HOPPER_LAUNCHER_PATH: installed.launcherPath,
+        };
         appliedActions.push("installed_hopper");
+        detectedClients = await filterClientsNeedingConfigure(host, detectedClients, providerEnvironment, registrationCommand());
     }
     const clientFailure = await configureDetectedClients({
         host,
         detectedClients,
-        hopperPath,
+        providerEnvironment,
         command: registrationCommand(),
         clients,
         appliedActions,
@@ -101,12 +109,14 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         ...(remediation === undefined ? {} : { remediation }),
     };
 };
-const discoverSetupActions = async (host, hopperPath) => {
+const discoverSetupActions = async (host, providerEnvironment, forceHopperInstall) => {
     const initialDoctor = await host.doctor();
     const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
         (name === "hopper-demo-runtime" ||
             (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
-    const installHopper = hopperPath === undefined || linuxHopperRepairNeeded;
+    const installHopper = forceHopperInstall ||
+        Object.keys(providerEnvironment).length === 0 ||
+        linuxHopperRepairNeeded;
     const [detectedClients, installSkill] = await Promise.all([
         host.detectedClients(),
         host.skillNeedsInstall(),
@@ -114,8 +124,8 @@ const discoverSetupActions = async (host, hopperPath) => {
     const command = registrationCommand();
     const clients = installHopper
         ? detectedClients
-        : await filterClientsNeedingConfigure(host, detectedClients, hopperPath, command);
-    const plannedActions = setupPlan(host.platform, installHopper, installSkill, clients);
+        : await filterClientsNeedingConfigure(host, detectedClients, providerEnvironment, command);
+    const plannedActions = setupPlan(host.platform, installHopper, installSkill, clients, providerEnvironment);
     return {
         installHopper,
         installSkill,
@@ -123,10 +133,14 @@ const discoverSetupActions = async (host, hopperPath) => {
         plannedActions,
     };
 };
-const filterClientsNeedingConfigure = async (host, detectedClients, hopperPath, command) => {
-    const needs = await Promise.all(detectedClients.map((client) => host.clientNeedsConfigure(client, hopperPath, command)));
+const filterClientsNeedingConfigure = async (host, detectedClients, providerEnvironment, command) => {
+    const needs = await Promise.all(detectedClients.map((client) => host.clientNeedsConfigure(client, providerEnvironment, command)));
     return detectedClients.filter((_, index) => needs[index]);
 };
+const initialProviderEnvironment = async (host, hopperPath) => ({
+    ...(await host.providerEnvironment?.()),
+    ...(hopperPath === undefined ? {} : { HOPPER_LAUNCHER_PATH: hopperPath }),
+});
 const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) => {
     if (platform === "darwin" && installedHopper)
         return "Open Hopper, choose its demo mode or activate a license, then rerun rea doctor --json.";
@@ -136,7 +150,7 @@ const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) =
         ? "Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis."
         : "Run rea doctor and apply each reported remediation.";
 };
-const hostRemediation = async (host) => {
+const hostRemediation = async (host, forceHopperInstall) => {
     if (host.platform !== "darwin" && host.platform !== "linux")
         return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
     if (!supportsNodeVersion(host.nodeVersion))
@@ -147,34 +161,47 @@ const hostRemediation = async (host) => {
             ? "Upgrade to macOS 12 or newer."
             : undefined;
     }
-    return (await host.linuxDistribution())?.supported === true
-        ? undefined
-        : "REA supports Hopper on Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.";
+    if ((await host.linuxDistribution())?.supported === true)
+        return undefined;
+    const providerEnvironment = await host.providerEnvironment?.();
+    if (!forceHopperInstall &&
+        providerEnvironment !== undefined &&
+        Object.keys(providerEnvironment).length > 0)
+        return undefined;
+    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux; configure an existing supported provider instead.";
 };
 /** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
-const systemSetupHost = () => {
-    const doctorHost = systemDoctorHost();
+export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
     return {
         platform: process.platform,
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
         hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
-        installHopper: async () => {
+        providerEnvironment: async () => {
+            const diagnosis = await runDoctor(undefined, doctorHost);
+            return {
+                ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
+                ...(diagnosis.hopperPath === undefined
+                    ? {}
+                    : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
+            };
+        },
+        installHopper: async (replaceExisting) => {
             const result = process.platform === "linux"
                 ? await installLinuxHopper()
-                : await installMacHopper();
+                : await installMacHopper({ replaceExisting });
             if (result.status === "installed")
                 return result;
             return setupInstallFailure(result.reason);
         },
         detectedClients: () => detectClients(homedir()),
-        configureClient: (client, hopperPath, command) => client.format === "unsupported"
+        configureClient: (client, providerEnvironment, command) => client.format === "unsupported"
             ? Promise.resolve({ status: "skipped" })
             : client.format === "toml"
-                ? configureTomlClient(client, hopperPath, command)
-                : configureJsonClient(client, hopperPath, command),
-        clientNeedsConfigure: (client, hopperPath, command) => clientConfigurationAligned(client, hopperPath, command).then((aligned) => !aligned),
+                ? configureTomlClient(client, providerEnvironment, command)
+                : configureJsonClient(client, providerEnvironment, command),
+        clientNeedsConfigure: (client, providerEnvironment, command) => clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
         skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
         installSkill: () => installCanonicalSkill(homedir()),
         doctor: () => runDoctor(undefined, doctorHost),
@@ -189,7 +216,7 @@ export const detectClients = async (home) => {
     return detected;
 };
 /** Back up, atomically update, and semantically read back one JSON MCP configuration. */
-export const configureJsonClient = async (client, hopperPath, command = [
+export const configureJsonClient = async (client, environment = {}, command = [
     "npx",
     "-y",
     PRODUCT_IDENTITY.packageName,
@@ -215,25 +242,15 @@ export const configureJsonClient = async (client, hopperPath, command = [
     catch {
         return { status: "failed", reason: "readback" };
     }
-    const desired = {
-        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
-        args: command.slice(1),
-        ...(hopperPath === undefined
-            ? {}
-            : { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
-    };
+    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
     if (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
         JSON.stringify(desired))
         return { status: "unchanged" };
     let backupPath;
     if (original !== undefined) {
         backupPath = `${client.configPath}.rea.backup`;
-        try {
-            await copyFile(transactionPath, backupPath);
-        }
-        catch {
+        if (!(await preserveConfigBackup(transactionPath, backupPath)))
             return { status: "failed", reason: "backup" };
-        }
     }
     document.mcpServers = {
         ...servers,
@@ -268,7 +285,7 @@ export const configureJsonClient = async (client, hopperPath, command = [
     };
 };
 /** Back up, atomically update, and semantically read back Codex TOML configuration. */
-export const configureTomlClient = async (client, hopperPath, command = [
+export const configureTomlClient = async (client, environment = {}, command = [
     "npx",
     "-y",
     PRODUCT_IDENTITY.packageName,
@@ -294,24 +311,14 @@ export const configureTomlClient = async (client, hopperPath, command = [
     catch {
         return { status: "failed", reason: "readback" };
     }
-    const desired = {
-        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
-        args: command.slice(1),
-        ...(hopperPath === undefined
-            ? {}
-            : { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
-    };
+    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
     if (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
         JSON.stringify(desired))
         return { status: "unchanged" };
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
-    try {
-        if (backupPath !== undefined)
-            await copyFile(transactionPath, backupPath);
-    }
-    catch {
+    if (backupPath !== undefined &&
+        !(await preserveConfigBackup(transactionPath, backupPath)))
         return { status: "failed", reason: "backup" };
-    }
     document.mcp_servers = {
         ...servers,
         [PRODUCT_IDENTITY.mcpServerKey]: desired,
@@ -345,6 +352,15 @@ const exists = async (path) => {
         return false;
     }
 };
+const preserveConfigBackup = async (source, destination) => {
+    try {
+        await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+        return true;
+    }
+    catch (cause) {
+        return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+    }
+};
 const objectSchema = z.record(z.string(), z.unknown());
 const parseOptionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
 const parseObject = (text) => objectSchema.parse(JSON.parse(text));
@@ -360,15 +376,16 @@ const restoreConfig = async (path, original) => {
         // The backup remains available for the remediation reported by setup.
     }
 };
-const clientConfigurationDesired = (hopperPath, command) => ({
-    command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
-    args: command.slice(1),
-    ...(hopperPath === undefined
-        ? {}
-        : { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
-});
-const clientConfigurationAligned = async (client, hopperPath, command) => {
-    const desired = clientConfigurationDesired(hopperPath, command);
+const clientConfigurationDesired = (providerEnvironment, command) => {
+    const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
+    return {
+        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
+        args: command.slice(1),
+        ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
+    };
+};
+const clientConfigurationAligned = async (client, providerEnvironment, command) => {
+    const desired = clientConfigurationDesired(providerEnvironment, command);
     try {
         const original = await readFile(client.configPath, "utf8");
         if (client.format === "toml") {
@@ -386,3 +403,10 @@ const clientConfigurationAligned = async (client, hopperPath, command) => {
         return false;
     }
 };
+const normalizeProviderEnvironment = (environment) => typeof environment === "string"
+    ? { HOPPER_LAUNCHER_PATH: environment }
+    : environment;
+const providerRegistrationEnvironment = (inspections) => Object.fromEntries(inspections
+    .filter(({ available }) => available)
+    .flatMap(({ registrationEnvironment }) => Object.entries(registrationEnvironment))
+    .sort(([left], [right]) => left.localeCompare(right)));

package/dist/application/SetupClients.js

@@ -11,7 +11,7 @@ const failedConfigurationMessage = (reason) => {
 export const configureDetectedClients = async (options) => {
     let failure;
     for (const client of options.detectedClients) {
-        const result = await options.host.configureClient(client, options.hopperPath, options.command);
+        const result = await options.host.configureClient(client, options.providerEnvironment, options.command);
         options.clients[client.name] = result;
         if (result.status === "failed")
             failure ??= failedConfigurationMessage(result.reason);

package/dist/application/SetupPlan.js

@@ -1,5 +1,5 @@
 /** Build the complete setup mutation plan before approval. */
-export const setupPlan = (platform, installHopper, installSkill, clients) => [
+export const setupPlan = (platform, installHopper, installSkill, clients, providerEnvironment) => [
     ...(installHopper
         ? [
             {
@@ -19,7 +19,7 @@ export const setupPlan = (platform, installHopper, installSkill, clients) => [
         .map((client) => ({
         kind: "configure_client",
         target: client.configPath,
-        detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
+        detail: clientConfigurationDetail(client.name, providerEnvironment),
         external: false,
     })),
     ...(installSkill
@@ -33,3 +33,10 @@ export const setupPlan = (platform, installHopper, installSkill, clients) => [
         ]
         : []),
 ];
+const clientConfigurationDetail = (client, environment) => {
+    const entries = Object.entries(environment)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, value]) => `${name}=${value}`);
+    const suffix = entries.length === 0 ? "" : ` Environment: ${entries.join(", ")}.`;
+    return `Add the REA MCP registration for ${client}; preserve unrelated configuration.${suffix}`;
+};

package/dist/application/SupportedClients.js

@@ -1,41 +1,65 @@
 import { join } from "node:path";
-/** Describe every client location that setup, doctor, or uninstall may inspect. */
-export const supportedClients = (home) => [
+/** Stable product metadata used to derive setup discovery and documentation. */
+export const SUPPORTED_CLIENT_DEFINITIONS = [
     {
         name: "claude_code",
-        configPath: join(home, ".claude.json"),
-        markerPath: join(home, ".claude"),
+        displayName: "Claude Code",
+        configPath: [".claude.json"],
+        markerPath: [".claude"],
+        format: "json",
     },
     {
         name: "claude_desktop",
-        configPath: join(home, "Library/Application Support/Claude/claude_desktop_config.json"),
-        markerPath: join(home, "Library/Application Support/Claude"),
+        displayName: "Claude Desktop",
+        configPath: [
+            "Library",
+            "Application Support",
+            "Claude",
+            "claude_desktop_config.json",
+        ],
+        markerPath: ["Library", "Application Support", "Claude"],
+        format: "json",
     },
     {
         name: "codex",
-        configPath: join(home, ".codex/config.toml"),
-        markerPath: join(home, ".codex"),
+        displayName: "Codex",
+        configPath: [".codex", "config.toml"],
+        markerPath: [".codex"],
         format: "toml",
     },
     {
         name: "cursor",
-        configPath: join(home, ".cursor/mcp.json"),
-        markerPath: join(home, ".cursor"),
+        displayName: "Cursor",
+        configPath: [".cursor", "mcp.json"],
+        markerPath: [".cursor"],
+        format: "json",
     },
     {
         name: "gemini_cli",
-        configPath: join(home, ".gemini/settings.json"),
-        markerPath: join(home, ".gemini"),
+        displayName: "Gemini CLI",
+        configPath: [".gemini", "settings.json"],
+        markerPath: [".gemini"],
+        format: "json",
     },
     {
         name: "windsurf",
-        configPath: join(home, ".codeium/windsurf/mcp_config.json"),
-        markerPath: join(home, ".codeium/windsurf"),
+        displayName: "Windsurf",
+        configPath: [".codeium", "windsurf", "mcp_config.json"],
+        markerPath: [".codeium", "windsurf"],
+        format: "json",
     },
     {
         name: "devin",
-        configPath: join(home, ".devin"),
-        markerPath: join(home, ".devin"),
+        displayName: "Devin",
+        configPath: [".devin"],
+        markerPath: [".devin"],
         format: "unsupported",
     },
 ];
+/** Describe every client location that setup, doctor, or uninstall may inspect. */
+export const supportedClients = (home) => SUPPORTED_CLIENT_DEFINITIONS.map((definition) => ({
+    name: definition.name,
+    configPath: join(home, ...definition.configPath),
+    markerPath: join(home, ...definition.markerPath),
+    format: definition.format,
+}));

package/dist/application/Upgrade.js

@@ -112,7 +112,7 @@ const inferUnixGlobalPrefix = (packageRoot) => {
 };
 const runCommand = (command, arguments_, output) => new Promise((resolveResult) => {
     const child = spawn(command, [...arguments_], {
-        stdio: output === "human" ? "inherit" : ["inherit", process.stderr, "inherit"],
+        stdio: output === "human" ? "inherit" : ["inherit", "ignore", "inherit"],
     });
     child.once("error", () => resolveResult(false));
     child.once("exit", (code) => resolveResult(code === 0));

package/dist/application/runtime.js

@@ -1,18 +1,23 @@
 import { BinarySession } from "./BinarySession.js";
 import { HopperProvider } from "../hopper/HopperProvider.js";
+import { GhidraProvider } from "../ghidra/GhidraProvider.js";
 import { NativeMacOSProvider } from "../native/NativeMacOSProvider.js";
 import { ArtifactProvider } from "../artifacts/ArtifactProvider.js";
-import { CompositeProvider } from "./CompositeProvider.js";
+import { ManagedStaticProvider } from "../dotnet/ManagedStaticProvider.js";
 import { silentLogger } from "../logger.js";
+import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
+import { SessionProviderRouter } from "./SessionProviderRouter.js";
 /**
  * Compose the target-switching runtime shared directly by CLI and MCP adapters.
- * This is the sole production wiring point for Hopper so neither adapter shells
- * out to the other and both retain identical loader and bridge semantics.
+ * This is the sole production wiring point, so both adapters share identical
+ * provider selection, profile, lifecycle, and Evidence semantics.
  */
 export const createBinarySession = (config, logger = silentLogger) => {
-    return new BinarySession(new CompositeProvider([
+    const hopper = new HopperProvider(config, logger);
+    const ghidra = new GhidraProvider(config, logger);
+    return new BinarySession(SessionProviderRouter.selectable(new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider), [
         new ArtifactProvider(config.artifactNativeMountEnabled, config.artifactIntegrityContinueEnabled),
         new NativeMacOSProvider(),
-        new HopperProvider(config, logger),
-    ]), { snapshotsEnabled: config.hopperLoaderArgs.length === 0 });
+        new ManagedStaticProvider(),
+    ]));
 };

package/dist/artifacts/AsarArtifactReader.js

@@ -15,13 +15,25 @@ export class AsarArtifactReader {
         this.path = path;
     }
     async *entries(signal) {
-        const paths = listPackage(this.path, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
+        let paths;
+        try {
+            paths = listPackage(this.path, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
+        }
+        catch (cause) {
+            throw asarFailure(this.path, "inventory", cause);
+        }
         for (const listed of paths) {
             abortIfNeeded(signal);
             const path = listed.replace(/^\/+|\/+$/gu, "");
             if (path.length === 0)
                 continue;
-            const metadata = statFile(this.path, path, false);
+            let metadata;
+            try {
+                metadata = statFile(this.path, path, false);
+            }
+            catch (cause) {
+                throw asarFailure(this.path, `stat ${path}`, cause);
+            }
             const kind = "files" in metadata
                 ? "directory"
                 : "link" in metadata
@@ -54,7 +66,12 @@ export class AsarArtifactReader {
         abortIfNeeded(signal);
         if (entry.kind !== "file")
             return Promise.reject(new ArtifactReaderFailure("format", "ASAR entry is not a regular file"));
-        return Promise.resolve(Readable.from(extractFile(this.path, entry.adapterKey, false)));
+        try {
+            return Promise.resolve(Readable.from(extractFile(this.path, entry.adapterKey, false)));
+        }
+        catch (cause) {
+            return Promise.reject(asarFailure(this.path, `read ${entry.path}`, cause));
+        }
     }
     close() {
         return Promise.resolve();
@@ -67,3 +84,6 @@ const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
 };
+const asarFailure = (path, operation, cause) => cause instanceof ArtifactReaderFailure
+    ? cause
+    : new ArtifactReaderFailure("format", `Malformed or unreadable ASAR during ${operation}: ${path}`, { cause });

package/dist/browser/CdpBrowserProvider.js

@@ -15,11 +15,13 @@ import { observeCdpSession } from "./CdpObservationSession.js";
 import { discoverWebMcp } from "./CdpWebMcpDiscovery.js";
 import { captureCdpScreenshot } from "./CdpScreenshot.js";
 import { comparePngScreenshots } from "./PngVisualDiff.js";
-const IDENTITY = {
+/** Public identity committed by passive browser observations. */
+export const CDP_BROWSER_PROVIDER_IDENTITY = Object.freeze({
     id: "rea-cdp-browser",
     name: "REA Chrome DevTools Protocol observation provider",
     version: "2",
-};
+});
+const IDENTITY = CDP_BROWSER_PROVIDER_IDENTITY;
 const CLEANUP_DOMAINS = ["Network", "Debugger", "Runtime", "Page"];
 /** Passive, origin-scoped browser observation through a user-owned CDP endpoint. */
 export class CdpBrowserProvider {

package/dist/browser/CdpCaptureEvents.js

@@ -8,6 +8,7 @@ export class CdpCaptureEvents {
     input;
     allowedOrigins;
     scripts = new Map();
+    executionContextFrames = new Map();
     network = new Map();
     allowedWebSockets = new Set();
     console = [];
@@ -36,6 +37,7 @@ export class CdpCaptureEvents {
         this.originViolation = false;
         this.navigationDuringCapture = false;
         this.scripts.clear();
+        this.executionContextFrames.clear();
         this.network.clear();
         this.allowedWebSockets.clear();
         this.console.length = 0;
@@ -62,6 +64,15 @@ export class CdpCaptureEvents {
         if (params === undefined)
             return;
         switch (event.method) {
+            case "Runtime.executionContextCreated":
+                this.#executionContext(params);
+                break;
+            case "Runtime.executionContextDestroyed":
+                this.#destroyExecutionContext(params);
+                break;
+            case "Runtime.executionContextsCleared":
+                this.executionContextFrames.clear();
+                break;
             case "Debugger.scriptParsed":
                 this.#script(params);
                 break;
@@ -91,6 +102,37 @@ export class CdpCaptureEvents {
                 break;
         }
     }
+    /** Resolve a transient execution context to one already authorized frame. */
+    frameForScript(script, allowedFrameIds) {
+        if (script.executionContextKey === null)
+            return null;
+        const frameId = this.executionContextFrames.get(script.executionContextKey);
+        return frameId !== undefined && allowedFrameIds.has(frameId)
+            ? frameId
+            : null;
+    }
+    #executionContext(params) {
+        const context = recordValue(params.context);
+        const identifier = numberValue(context?.id);
+        const frameId = stringValue(recordValue(context?.auxData)?.frameId);
+        if (identifier === undefined ||
+            !Number.isSafeInteger(identifier) ||
+            frameId === undefined ||
+            frameId.length > 256)
+            return;
+        const key = String(identifier);
+        if (this.executionContextFrames.size >= this.input.limits.max_scripts &&
+            !this.executionContextFrames.has(key)) {
+            this.completeness.truncate("scripts");
+            return;
+        }
+        this.executionContextFrames.set(key, frameId);
+    }
+    #destroyExecutionContext(params) {
+        const key = executionContextKey(params.executionContextId);
+        if (key !== null)
+            this.executionContextFrames.delete(key);
+    }
     #script(params) {
         const scriptId = stringValue(params.scriptId);
         const rawUrl = stringValue(params.url) ?? "";
@@ -120,6 +162,7 @@ export class CdpCaptureEvents {
             language: boundedText(params.scriptLanguage, 100),
             sourceMapUrl: sourceMap.sanitized,
             sourceMapRawUrl: sourceMap.raw,
+            executionContextKey: executionContextKey(params.executionContextId),
         });
     }
     #sourceMap(value, scriptUrl) {
@@ -501,6 +544,12 @@ const integerOrNull = (value) => {
     const number = numberValue(value);
     return number === undefined ? null : Math.max(0, Math.trunc(number));
 };
+const executionContextKey = (value) => {
+    const identifier = numberValue(value);
+    return identifier !== undefined && Number.isSafeInteger(identifier)
+        ? String(identifier)
+        : null;
+};
 const isJsonContentType = (headers) => {
     if (headers === undefined)
         return false;