rea-agents 1.6.0 → 2.0.0

package/dist/application/DirectAnalysis.js

@@ -13,20 +13,19 @@ import { snapshotEvidenceForQuery, snapshotMatchesTarget, } from "../domain/anal
 import { err, ok } from "../domain/result.js";
 import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
 import { authorizeFileReadWithDeferredWrite, } from "./DeferredFileAuthorization.js";
-const WORKFLOW_PROVIDER = {
-    id: "rea-workflow",
-    name: "REA composed investigation workflow",
-    version: "1",
-};
+import { REA_WORKFLOW_PROVIDER, workflowAnalysisProfile, } from "./InvestigationProviders.js";
 /**
- * Open one binary, execute one tool, and always release the bridge session.
+ * Open one binary, execute one tool, and always release provider resources.
  * Unlike MCP mode, every CLI invocation is intentionally isolated and does not
- * retain a target or bridge resources for a subsequent command.
+ * retain a target or provider client for a subsequent command.
  */
 export const runDirectAnalysis = async (path, tool, arguments_, options = {}) => withProcessCancellation(options.signal, (signal) => runAnalysis(path, tool, arguments_, {
     logger: options.logger ?? silentLogger,
     snapshotPath: options.snapshotPath,
     signal,
+    ...(options.providerId === undefined
+        ? {}
+        : { providerId: options.providerId }),
     ...(options.permissionAuthority === undefined
         ? {}
         : { permissionAuthority: options.permissionAuthority }),
@@ -37,7 +36,7 @@ export const runProviderAnalysis = async (path, tool, arguments_, logger = silen
     snapshotPath: undefined,
     signal: operationSignal,
 }));
-/** Describe configured providers without opening a target or launching Hopper. */
+/** Describe configured providers without opening a target or starting one. */
 export const runSessionStatus = async (logger = silentLogger) => {
     const config = parseConfig(process.env);
     if (!config.ok)
@@ -135,30 +134,44 @@ const runAnalysis = async (path, tool, arguments_, options) => {
     });
     if (!authorization.ok)
         return cliError(authorization.error);
-    const unavailable = snapshotUnavailable(snapshotPath, config.value.hopperLoaderArgs);
-    if (unavailable !== undefined)
-        return cliError(unavailable);
     const session = createBinarySession(config.value, logger);
     try {
         const prepared = await prepareSnapshot({
             path,
-            tool,
-            arguments: arguments_,
             snapshotPath,
             policy: config.value.analysisSnapshotFilePolicy,
-            provider: replayProviderFor(session, tool),
         });
         if (!prepared.ok)
             return cliError(prepared.error);
-        if (prepared.value.evidence !== undefined)
-            return prepared.value.evidence;
-        const writable = await authorizeDeferredWrite(authorization.value);
-        if (!writable.ok)
-            return cliError(writable.error);
         const { snapshot } = prepared.value;
-        const opened = await session.open(path, snapshot === undefined ? { signal } : { signal, snapshot });
+        const opened = await session.open(path, {
+            signal,
+            ...(snapshot === undefined ? {} : { snapshot }),
+            ...(options.providerId === undefined
+                ? {}
+                : { providerId: options.providerId }),
+        });
         if (!opened.ok)
             return cliError(opened.error);
+        const evidenceProfile = analysisProfileForEvidence(session, tool);
+        const bindingProfile = session.analysisProfile();
+        if (snapshot !== undefined &&
+            evidenceProfile !== undefined &&
+            bindingProfile !== undefined) {
+            const cached = snapshotEvidenceForQuery(snapshot, {
+                target: opened.value,
+                bindingProfile,
+                operation: tool,
+                parameters: arguments_,
+                provider: replayProviderFor(session, tool),
+                evidenceProfile,
+            });
+            if (cached !== undefined)
+                return cached;
+        }
+        const writable = await authorizeDeferredWrite(authorization.value);
+        if (!writable.ok)
+            return cliError(writable.error);
         let output;
         let evidence;
         if (tool === "binary_overview" ||
@@ -170,10 +183,13 @@ const runAnalysis = async (path, tool, arguments_, options) => {
             else {
                 evidence = createEvidence(opened.value, tool === "analyze_function"
                     ? session.providerIdentity(tool)
-                    : WORKFLOW_PROVIDER, {
+                    : REA_WORKFLOW_PROVIDER, {
                     operation: tool,
                     parameters: arguments_,
                     result: result.value,
+                    ...(evidenceProfile === undefined
+                        ? {}
+                        : { analysisProfile: evidenceProfile }),
                     confidence: "derived",
                     limitations: ["Derived by an REA composed workflow."],
                 });
@@ -189,6 +205,9 @@ const runAnalysis = async (path, tool, arguments_, options) => {
                     operation: tool,
                     parameters: arguments_,
                     result: result.value.result,
+                    ...(result.value.analysisProfile === undefined
+                        ? {}
+                        : { analysisProfile: result.value.analysisProfile }),
                     rawResult: result.value.rawResult,
                     limitations: result.value.limitations,
                     locations: result.value.locations,
@@ -226,7 +245,7 @@ const withProcessCancellation = async (suppliedSignal, operation) => {
     }
 };
 const prepareSnapshot = async (options) => {
-    const { path, tool, arguments: arguments_, snapshotPath, policy, provider, } = options;
+    const { path, snapshotPath, policy } = options;
     if (snapshotPath === undefined || !(await fileExists(snapshotPath)))
         return ok({});
     const loaded = await readAnalysisSnapshot(snapshotPath, policy);
@@ -237,22 +256,17 @@ const prepareSnapshot = async (options) => {
         return target;
     if (!snapshotMatchesTarget(loaded.value.target, target.value))
         return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
-    const evidence = snapshotEvidenceForQuery(loaded.value, {
-        target: target.value,
-        operation: tool,
-        parameters: arguments_,
-        provider,
-    });
-    return ok(evidence === undefined
-        ? { snapshot: loaded.value }
-        : { snapshot: loaded.value, evidence });
+    return ok({ snapshot: loaded.value });
 };
-const snapshotUnavailable = (snapshotPath, loaderArgs) => snapshotPath !== undefined && loaderArgs.length > 0
-    ? new EvidenceIntegrityError("Analysis snapshots are unavailable with custom Hopper loader arguments")
-    : undefined;
 const replayProviderFor = (session, tool) => tool === "binary_overview" || tool === "trace_feature"
-    ? WORKFLOW_PROVIDER
+    ? REA_WORKFLOW_PROVIDER
     : session.providerIdentity(tool);
+const analysisProfileForEvidence = (session, tool) => {
+    if (tool !== "binary_overview" && tool !== "trace_feature")
+        return session.analysisProfile(tool);
+    const upstream = session.analysisProfile();
+    return upstream === undefined ? undefined : workflowAnalysisProfile(upstream);
+};
 const fileExists = async (path) => {
     try {
         await access(path);

package/dist/application/Doctor.js

@@ -65,6 +65,10 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             remediation: unsupportedHopperRemediation(host.configuredHopperPath === hopperPath),
             classification: "config_drift",
         }));
+    const providerInspections = await inspectDoctorProviders(host, checks);
+    const javascriptReplayCheck = await host.javascriptReplayCheck?.();
+    if (javascriptReplayCheck !== undefined)
+        checks.push(javascriptReplayCheck);
     if (host.platform === "linux" && hopperPath !== undefined)
         checks.push(check("hopper-demo-runtime", await host.linuxDemoRuntimeReady(), undefined, {
             remediation: "Rerun rea setup to install the Xvfb, xauth, Python, X11, and XTEST packages required for Linux demo sessions.",
@@ -76,7 +80,33 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             classification: "config_drift",
         }));
     const installationPaths = (await host.installationPaths?.()) ?? [];
-    const installedSkillVersion = await host.installedSkillVersion?.();
+    const observedSkillIdentity = await host.installedSkillIdentity?.();
+    const legacySkillVersion = observedSkillIdentity === undefined
+        ? await host.installedSkillVersion?.()
+        : undefined;
+    const installedSkillIdentity = observedSkillIdentity ??
+        (legacySkillVersion === undefined
+            ? undefined
+            : {
+                version: legacySkillVersion,
+                toolCount: null,
+                catalogDigest: null,
+            });
+    const installedSkillVersion = installedSkillIdentity?.version ?? undefined;
+    const skillAligned = installedSkillIdentity?.version === PRODUCT_IDENTITY.skillVersion &&
+        installedSkillIdentity.toolCount === CATALOG_IDENTITY.counts.mcp_tools &&
+        installedSkillIdentity.catalogDigest ===
+            CATALOG_IDENTITY.digests.combined_sha256;
+    if (!skillAligned)
+        checks.push({
+            name: "skill:identity",
+            ok: false,
+            classification: "config_drift",
+            detail: installedSkillIdentity === undefined
+                ? "Installed REA skill identity is missing."
+                : "Installed REA skill identity is stale.",
+            remediation: "Run rea setup to update the installed REA skill.",
+        });
     const registrations = (await host.clientRegistrations?.()) ?? [];
     for (const registration of registrations)
         if (registration.state !== "aligned")
@@ -89,8 +119,16 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
                     "Run rea setup, then restart the affected client.",
             });
     return {
-        healthy: checks.every(({ ok }) => ok),
+        healthy: doctorHealthy(checks, {
+            hopperAvailable: hopperPath !== undefined &&
+                checks
+                    .filter(({ name }) => name.startsWith("hopper"))
+                    .every(({ ok }) => ok),
+            hopperConfigured: host.configuredHopperPath !== undefined,
+            providerInspections,
+        }),
         ...(hopperPath === undefined ? {} : { hopperPath }),
+        ...(providerInspections === undefined ? {} : { providerInspections }),
         checks,
         identity: {
             cli_package_version: PRODUCT_IDENTITY.packageVersion,
@@ -111,13 +149,14 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             },
             skill: {
                 installed_version: installedSkillVersion ?? null,
-                state: installedSkillVersion === undefined
-                    ? "unknown"
-                    : installedSkillVersion === PRODUCT_IDENTITY.skillVersion
+                installed_tool_count: installedSkillIdentity?.toolCount ?? null,
+                installed_catalog_digest: installedSkillIdentity?.catalogDigest ?? null,
+                state: installedSkillIdentity === undefined
+                    ? "missing"
+                    : skillAligned
                         ? "aligned"
                         : "stale",
-                remediation: installedSkillVersion === undefined ||
-                    installedSkillVersion === PRODUCT_IDENTITY.skillVersion
+                remediation: skillAligned
                     ? null
                     : "Run rea setup to update the installed REA skill.",
             },
@@ -129,7 +168,7 @@ const unsupportedHopperRemediation = (configured) => configured
     ? "Unset or update HOPPER_LAUNCHER_PATH, install the Hopper build supported by this REA release, or update REA."
     : "Install the Hopper build supported by this REA release, or update REA for a newer Hopper build.";
 /** Create diagnostics backed by the current process and host commands. */
-export const systemDoctorHost = () => ({
+export const systemDoctorHost = (options = {}) => ({
     platform: process.platform,
     nodeVersion: process.versions.node,
     ...(process.env.HOPPER_LAUNCHER_PATH === undefined
@@ -208,6 +247,12 @@ export const systemDoctorHost = () => ({
         }
         return paths;
     },
+    ...(options.providerInspections === undefined
+        ? {}
+        : { providerInspections: options.providerInspections }),
+    ...(options.javascriptReplayCheck === undefined
+        ? {}
+        : { javascriptReplayCheck: options.javascriptReplayCheck }),
     async installationPaths() {
         try {
             const command = process.platform === "win32" ? "where" : "which";
@@ -227,6 +272,23 @@ export const systemDoctorHost = () => ({
             return undefined;
         }
     },
+    async installedSkillIdentity() {
+        try {
+            const content = await readFile(join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"), "utf8");
+            const version = /^\s{2}version:\s*"([^"]+)"\s*$/mu.exec(content)?.[1] ?? null;
+            const countText = /^\s{2}tool_count:\s*(\d+)\s*$/mu.exec(content)?.[1];
+            const catalogDigest = /^\s{2}catalog_digest:\s*"([a-f0-9]{64})"\s*$/mu.exec(content)?.[1] ??
+                null;
+            return {
+                version,
+                toolCount: countText === undefined ? null : Number.parseInt(countText, 10),
+                catalogDigest,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    },
     clientRegistrations: () => readClientRegistrationStatuses(homedir()),
 });
 const parseMajor = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
@@ -243,3 +305,43 @@ const check = (name, ok, detail, failure) => ({
     ...(detail === undefined ? {} : { detail }),
     ...(ok ? {} : { remediation: failure.remediation }),
 });
+const providerDoctorChecks = (inspection) => inspection.checks.map((candidate) => ({
+    name: candidate.name === "configuration"
+        ? inspection.id
+        : `${inspection.id}-${candidate.name}`,
+    ok: candidate.ok,
+    classification: candidate.ok ? "healthy" : candidate.classification,
+    detail: candidate.detail,
+    ...(candidate.remediation === null
+        ? {}
+        : { remediation: candidate.remediation }),
+}));
+const inspectDoctorProviders = async (host, checks) => {
+    const inspections = await host.providerInspections?.();
+    if (inspections === undefined)
+        return undefined;
+    for (const inspection of inspections)
+        checks.push(...providerDoctorChecks(inspection));
+    return inspections;
+};
+const doctorHealthy = (checks, providers) => {
+    if (providers.providerInspections === undefined)
+        return checks.every(({ ok }) => ok);
+    const providerChecks = checks.filter(({ name }) => name.startsWith("hopper") ||
+        providers.providerInspections?.some((inspection) => providerCheckName(inspection.id, name)) === true);
+    const coreHealthy = checks
+        .filter((candidate) => !providerChecks.includes(candidate))
+        .every(({ ok }) => ok);
+    const configuredProvidersHealthy = providerChecks
+        .filter(({ name }) => {
+        if (name.startsWith("hopper"))
+            return providers.hopperConfigured;
+        return providers.providerInspections?.some((inspection) => inspection.configured && providerCheckName(inspection.id, name));
+    })
+        .every(({ ok }) => ok);
+    return (coreHealthy &&
+        configuredProvidersHealthy &&
+        (providers.hopperAvailable ||
+            providers.providerInspections.some(({ available }) => available)));
+};
+const providerCheckName = (providerId, name) => name === providerId || name.startsWith(`${providerId}-`);

package/dist/application/ElectronBoundaryAnalysis.js

@@ -0,0 +1,96 @@
+import { resolveArtifactPath } from "./JavaScriptArtifactGraphContext.js";
+/** Flatten all per-file IPC facts into deterministic application records. */
+export const collectElectronIpcRecords = (analysis) => analysis.files
+    .flatMap(({ file, javascript }) => (javascript?.electron.ipc ?? []).map((finding) => ({
+    key: ipcRecordKey(file.path, finding),
+    file,
+    finding,
+})))
+    .sort((left, right) => compareCodePoints(left.key, right.key));
+/** Match only exact literal channels and retain ambiguous matches separately. */
+export const classifyElectronIpcPairings = (records) => {
+    const handlers = records.filter(isMainHandler);
+    return records.filter(isPairableRendererTransmission).map((transmission) => {
+        const candidates = transmission.finding.channel === null
+            ? []
+            : handlers.filter((handler) => handler.finding.channel === transmission.finding.channel &&
+                compatibleIpcModes(transmission.finding, handler.finding));
+        return {
+            transmission,
+            candidates,
+            status: candidates.length === 1
+                ? "paired"
+                : candidates.length > 1
+                    ? "ambiguous"
+                    : "unpaired",
+        };
+    });
+};
+/** Return only pairings supported by one unique literal main handler. */
+export const unambiguousElectronIpcPairings = (records) => classifyElectronIpcPairings(records).flatMap((state) => {
+    const handler = state.candidates[0];
+    return state.status === "paired" && handler !== undefined
+        ? [{ transmission: state.transmission, handler }]
+        : [];
+});
+/** Summarize static Electron findings without treating gaps as absence. */
+export const summarizeElectronBoundaries = (analysis) => {
+    const files = new Map(analysis.files.map(({ file }) => [file.path, file]));
+    const javascript = analysis.files.flatMap(({ javascript: value }) => value === null ? [] : [value]);
+    const windows = javascript.flatMap(({ electron }) => electron.browser_windows);
+    const bridges = javascript.flatMap(({ electron }) => electron.context_bridge_apis);
+    const validations = javascript.flatMap(({ electron }) => electron.sender_validations);
+    const utilities = analysis.files.flatMap(({ file, javascript: value }) => (value?.electron.utility_processes ?? []).map((finding) => ({
+        file,
+        finding,
+    })));
+    const nativeBindings = analysis.files.flatMap(({ file, javascript: value }) => (value?.electron.native_addon_bindings ?? []).map((finding) => ({
+        file,
+        finding,
+    })));
+    const ipc = collectElectronIpcRecords(analysis);
+    const pairing = classifyElectronIpcPairings(ipc);
+    const literalChannels = new Set(ipc.flatMap(({ finding }) => finding.channel === null ? [] : [finding.channel]));
+    return {
+        browser_windows: windows.length,
+        explicit_web_preferences: windows.reduce((count, window) => count + window.web_preferences.length, 0),
+        preload_entrypoints: windows.filter(({ preload_path: path }) => path !== null).length,
+        context_bridge_apis: bridges.length,
+        exposed_api_members: bridges.reduce((count, bridge) => count + bridge.members.length, 0),
+        ipc: {
+            operations: ipc.length,
+            literal_channels: literalChannels.size,
+            dynamic_channel_operations: ipc.filter(({ finding }) => finding.channel === null).length,
+            renderer_transmissions: ipc.filter(isRendererTransmission).length,
+            renderer_listeners: ipc.filter(({ finding }) => finding.side === "renderer" && finding.mode === "listen").length,
+            main_handlers: ipc.filter(isMainHandler).length,
+            paired_renderer_transmissions: pairing.filter(({ status }) => status === "paired").length,
+            ambiguous_renderer_transmissions: pairing.filter(({ status }) => status === "ambiguous").length,
+            unpaired_literal_renderer_transmissions: pairing.filter(({ status, transmission }) => status === "unpaired" && transmission.finding.channel !== null).length,
+        },
+        sender_validation_observations: validations.length,
+        utility_processes: utilities.length,
+        resolved_utility_entrypoints: utilities.filter(({ file, finding }) => resolvesToFile(file, finding.module_path, files)).length,
+        native_addon_bindings: nativeBindings.length,
+        resolved_native_addon_bindings: nativeBindings.filter(({ file, finding }) => resolvesToFile(file, finding.specifier, files, "native-addon")).length,
+    };
+};
+const compatibleIpcModes = (transmission, handler) => transmission.mode === "invoke"
+    ? handler.mode === "handle"
+    : transmission.operation === "send-to-host"
+        ? false
+        : transmission.mode === "send" && handler.mode === "listen";
+const isRendererTransmission = ({ finding }) => finding.side === "renderer" &&
+    (finding.mode === "send" || finding.mode === "invoke");
+const isPairableRendererTransmission = (record) => isRendererTransmission(record) && record.finding.operation !== "send-to-host";
+const isMainHandler = ({ finding }) => finding.side === "main" &&
+    (finding.mode === "listen" || finding.mode === "handle");
+const resolvesToFile = (file, specifier, files, kind) => {
+    if (specifier === null)
+        return false;
+    const resolved = resolveArtifactPath(specifier, file.path, files);
+    return (resolved !== null &&
+        (kind === undefined || files.get(resolved)?.kind === kind));
+};
+const ipcRecordKey = (path, finding) => `${path}\0${String(finding.location.start.line)}:${String(finding.location.start.column)}\0${finding.side}\0${finding.operation}`;
+const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/application/ElectronBoundaryGraph.js

@@ -0,0 +1,9 @@
+import { addElectronIpcBoundaries } from "./ElectronBoundaryGraphIpc.js";
+import { addElectronNativeBoundaries } from "./ElectronBoundaryGraphNative.js";
+import { addElectronWindowBoundaries } from "./ElectronBoundaryGraphWindows.js";
+/** Add every static Electron process and security-boundary fact to the JAG. */
+export const addElectronBoundaries = (context) => {
+    addElectronWindowBoundaries(context);
+    addElectronIpcBoundaries(context);
+    addElectronNativeBoundaries(context);
+};

package/dist/application/ElectronBoundaryGraphContext.js

@@ -0,0 +1,62 @@
+import { sha256Text } from "../domain/javascriptStaticAnalysisHelpers.js";
+import { astObservationEvidence, staticInferenceEvidence, } from "./JavaScriptArtifactGraphEvidence.js";
+/** Resolve the file or recovered bundle module that owns one finding. */
+export const electronFindingSourceNode = (context, file, moduleKey) => moduleKey === null
+    ? (context.assetNodes.get(file.path) ?? context.fileNodes.get(file.path))
+    : context.moduleNodes.get(`${file.path}\0${moduleKey}`);
+/** Observation-scoped identity shared safely across different artifact files. */
+export const electronObservationIdentity = (context, scope, key) => ({
+    strategy: "observation-fingerprint",
+    stability: "observation-only",
+    observation_sha256: sha256Text(`${context.snapshot.manifest.root_sha256}\0${scope}\0${key}`),
+    scope: scope.slice(0, 4_096),
+});
+/** Add a direct AST syntax relationship. */
+export const addElectronAstEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        properties: input.properties,
+        evidence: astObservationEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: input.operation,
+            coverage: input.coverage,
+            ...(input.limitations === undefined
+                ? {}
+                : { limitations: input.limitations }),
+        }),
+    });
+};
+/** Add an Electron relationship that static syntax suggests but cannot prove. */
+export const addElectronInferenceEdge = (context, input) => {
+    context.accumulator.addEdge({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        properties: input.properties,
+        evidence: staticInferenceEvidence({
+            sha256: input.file.sha256,
+            path: input.file.path,
+            range: input.range,
+            operation: input.operation,
+            coverage: input.coverage,
+            ...(input.confidence === undefined
+                ? {}
+                : { confidence: input.confidence }),
+            ...(input.limitations === undefined
+                ? {}
+                : { limitations: input.limitations }),
+        }),
+    });
+};
+/** Deterministic source-range key for artifact-local graph identities. */
+export const electronRangeKey = (range) => `${String(range.start.line)}:${String(range.start.column)}-${String(range.end.line)}:${String(range.end.column)}`;
+/** Test exact source-range containment without assuming runtime reachability. */
+export const electronRangeContains = (outer, inner) => comparePoint(outer.start, inner.start) <= 0 &&
+    comparePoint(outer.end, inner.end) >= 0;
+const comparePoint = (left, right) => left.line === right.line
+    ? left.column - right.column
+    : left.line - right.line;