rea-agents 1.6.0 → 1.7.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,7 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             remediation: unsupportedHopperRemediation(host.configuredHopperPath === hopperPath),
             classification: "config_drift",
         }));
+    const providerInspections = await inspectDoctorProviders(host, checks);
     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.",
@@ -89,8 +90,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,
@@ -129,7 +138,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 +217,9 @@ export const systemDoctorHost = () => ({
         }
         return paths;
     },
+    ...(options.providerInspections === undefined
+        ? {}
+        : { providerInspections: options.providerInspections }),
     async installationPaths() {
         try {
             const command = process.platform === "win32" ? "where" : "which";
@@ -243,3 +255,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/EnhancedTools.js

@@ -4,7 +4,7 @@ import { addressDistance, parseDocuments, parseFunctionDossier, parseAddressedPa
 import { err, ok } from "../domain/result.js";
 import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, discoverSwiftClasses, } from "../domain/symbolAnalysis.js";
 /**
- * Composes official Hopper operations into bounded reverse-engineering tools.
+ * Composes direct provider operations into bounded reverse-engineering tools.
  * Inputs are parsed again at this application boundary even though MCP normally
  * validates them, allowing direct callers to use the same service safely.
  */

package/dist/application/InvestigationProviders.js

@@ -1,3 +1,14 @@
+import { createAnalysisProfile, } from "../domain/analysisProfile.js";
+/** Provider identity for deterministic composed analysis workflows. */
+export const REA_WORKFLOW_PROVIDER = {
+    id: "rea-workflow",
+    name: "REA composed investigation workflow",
+    version: "1",
+};
+/** Commit a workflow result to the exact upstream deep-analysis profile. */
+export const workflowAnalysisProfile = (upstream) => createAnalysisProfile(REA_WORKFLOW_PROVIDER, 1, {
+    upstream_analysis_profile: upstream,
+});
 /** Provider identity for deterministic artifact inventories. */
 export const ARTIFACT_GRAPH_PROVIDER = {
     id: "rea-artifact-graph",

package/dist/application/JavaScriptArtifactAnalysis.js

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import { analyzeJavaScriptStaticSource } from "../domain/javascriptStaticAnalysis.js";
+/** Analyze selected text files under one shared AST, finding, module, and time budget. */
+export const analyzeJavaScriptArtifactFiles = (fileSet, input, now) => {
+    const state = emptyArtifactAnalysis();
+    const context = {
+        state,
+        input,
+        deadline: now() + input.limits.max_parse_milliseconds,
+        now,
+    };
+    for (const file of fileSet.files)
+        analyzeArtifactFile(file, context);
+    return finalizeArtifactAnalysis(state, input);
+};
+const finalizeArtifactAnalysis = (state, input) => {
+    const omittedHtmlFindings = Math.max(0, state.htmlScripts.length + state.findings - input.limits.max_findings);
+    const findings = Math.min(input.limits.max_findings, state.findings + state.htmlScripts.length);
+    const sourceMapTruncations = state.sourceMaps.filter(({ status }) => status === "truncated").length;
+    const truncatedScopes = state.truncatedScopes +
+        sourceMapTruncations +
+        (omittedHtmlFindings > 0 ? 1 : 0);
+    return {
+        files: state.files,
+        packages: state.packages,
+        html_scripts: state.htmlScripts.slice(0, input.limits.max_findings),
+        source_maps: state.sourceMaps,
+        visited_ast_nodes: state.visitedNodes,
+        findings,
+        modules: state.modules,
+        parse_failures: state.parseFailures,
+        truncated_scopes: truncatedScopes,
+        limitations: [
+            "JavaScript and HTML were parsed as inert text; bundle bootstrap code was never executed.",
+            "Static paths and relationships may remain unresolved when expressions are dynamic or obfuscated.",
+            ...(input.source_map_read_approved
+                ? []
+                : [
+                    "Source maps were inventoried but their contents were not read without separate approval.",
+                ]),
+            ...(truncatedScopes === 0
+                ? []
+                : ["One or more static-analysis scopes reached an approved bound."]),
+        ],
+    };
+};
+const analyzeArtifactFile = (file, context) => {
+    const { state, input } = context;
+    if (file.kind === "package-json")
+        state.packages.push(parsePackage(file));
+    if (file.kind === "html" && file.text.included)
+        state.htmlScripts.push(...parseHtmlScripts(file.path, file.text.value, Math.max(0, input.limits.max_findings - state.findings)));
+    if (file.kind === "source-map")
+        addSourceMap(file, context);
+    if (file.kind !== "javascript" || !file.text.included) {
+        state.files.push({ file, javascript: null });
+        return;
+    }
+    const remainingNodes = input.limits.max_ast_nodes - state.visitedNodes;
+    const remainingFindings = input.limits.max_findings - state.findings;
+    const remainingModules = input.limits.max_modules - state.modules;
+    if (remainingNodes <= 0 ||
+        remainingFindings <= 0 ||
+        remainingModules <= 0 ||
+        context.now() > context.deadline) {
+        state.files.push({ file, javascript: null });
+        state.truncatedScopes += 1;
+        return;
+    }
+    const analysis = analyzeJavaScriptStaticSource(file.text.value, {
+        maxAstNodes: remainingNodes,
+        maxFindings: remainingFindings,
+        maxModules: remainingModules,
+        deadline: context.deadline,
+        now: context.now,
+    });
+    state.files.push({ file, javascript: analysis });
+    state.visitedNodes += analysis.visited_ast_nodes;
+    state.findings += findingCount(analysis);
+    state.modules += analysis.bundler_registrations.reduce((count, registration) => count + registration.modules.length, 0);
+    if (analysis.parse_status === "failed")
+        state.parseFailures += 1;
+    if (analysis.parse_status === "truncated")
+        state.truncatedScopes += 1;
+};
+const addSourceMap = (file, context) => {
+    const sourceMap = parseSourceMap(file, {
+        deadline: context.deadline,
+        now: context.now,
+        maximumSources: Math.max(0, context.input.limits.max_source_map_sources -
+            context.state.sourceMapSources),
+    });
+    context.state.sourceMaps.push(sourceMap);
+    context.state.sourceMapSources += sourceMap.sources.length;
+};
+const emptyArtifactAnalysis = () => ({
+    files: [],
+    packages: [],
+    htmlScripts: [],
+    sourceMaps: [],
+    visitedNodes: 0,
+    findings: 0,
+    modules: 0,
+    parseFailures: 0,
+    truncatedScopes: 0,
+    sourceMapSources: 0,
+});
+const parsePackage = (file) => {
+    if (!file.text.included)
+        return unavailablePackage(file, "Package metadata text was unavailable.");
+    let value;
+    try {
+        value = JSON.parse(file.text.value);
+    }
+    catch {
+        return invalidPackage(file, "package.json is not valid JSON.");
+    }
+    if (!isRecord(value))
+        return invalidPackage(file, "package.json root is not an object.");
+    return {
+        path: file.path,
+        sha256: file.sha256,
+        status: "included",
+        name: boundedString(value.name),
+        version: boundedString(value.version),
+        main: boundedString(value.main),
+        renderer: boundedString(value.renderer) ??
+            boundedString(value.browser) ??
+            boundedString(value.module),
+        limitation: null,
+    };
+};
+const invalidPackage = (file, limitation) => ({
+    ...unavailablePackage(file, limitation),
+    status: "invalid",
+});
+const unavailablePackage = (file, limitation) => ({
+    path: file.path,
+    sha256: file.sha256,
+    status: "unavailable",
+    name: null,
+    version: null,
+    main: null,
+    renderer: null,
+    limitation,
+});
+const parseHtmlScripts = (path, text, maximum) => {
+    const scripts = [];
+    const pattern = /<script\b[^>]*\bsrc\s*=\s*(["'])([^"']+)\1[^>]*>/giu;
+    for (const match of text.matchAll(pattern)) {
+        const script = match[2]?.slice(0, 4_096);
+        if (script === undefined || scripts.length >= maximum)
+            break;
+        const start = match.index;
+        scripts.push({
+            html_path: path,
+            script_path: script,
+            location: rangeForOffsets(text, start, start + match[0].length),
+        });
+    }
+    return scripts;
+};
+const parseSourceMap = (file, context) => {
+    if (!file.text.included)
+        return unavailableSourceMap(file);
+    if (context.now() > context.deadline)
+        return truncatedSourceMap(file, null, "Parse deadline reached before source-map decoding.");
+    let value;
+    try {
+        value = JSON.parse(file.text.value);
+    }
+    catch {
+        return invalidSourceMap(file, "Source map is not valid JSON.");
+    }
+    if (context.now() > context.deadline)
+        return truncatedSourceMap(file, null, "Parse deadline elapsed during source-map decoding.");
+    const maps = flattenSourceMaps(value, 10_000);
+    if (maps === undefined)
+        return invalidSourceMap(file, "Source map is not a bounded version 3 map.");
+    return collectSourceMapOriginals(file, maps, context);
+};
+const collectSourceMapOriginals = (file, maps, context) => {
+    const sources = [];
+    let total = 0;
+    for (const map of maps) {
+        const names = map.sources;
+        if (!Array.isArray(names))
+            return invalidSourceMap(file, "Source map has no sources array.");
+        const contents = Array.isArray(map.sourcesContent)
+            ? map.sourcesContent
+            : [];
+        const root = typeof map.sourceRoot === "string" ? map.sourceRoot : "";
+        for (const [index, raw] of names.entries()) {
+            if (total % 1_024 === 0 && context.now() > context.deadline)
+                return {
+                    path: file.path,
+                    sha256: file.sha256,
+                    status: "truncated",
+                    sources,
+                    omitted_sources: null,
+                    limitation: "Parse deadline elapsed during source-map traversal.",
+                };
+            if (typeof raw !== "string")
+                return invalidSourceMap(file, "Source map contains a non-string source name.");
+            total += 1;
+            if (sources.length >= context.maximumSources)
+                continue;
+            const content = typeof contents[index] === "string" ? contents[index] : null;
+            sources.push({
+                source: resolveSourceName(root, raw),
+                content,
+                content_sha256: content === null ? null : sha256(content),
+            });
+        }
+    }
+    const omitted = total - sources.length;
+    return {
+        path: file.path,
+        sha256: file.sha256,
+        status: omitted === 0 ? "included" : "truncated",
+        sources,
+        omitted_sources: omitted,
+        limitation: omitted === 0
+            ? null
+            : "Original-source inventory reached the approved source-map limit.",
+    };
+};
+const unavailableSourceMap = (file) => {
+    if (file.text.included)
+        throw new TypeError("Expected unavailable source-map text");
+    const notApproved = file.text.reason === "not-approved";
+    return {
+        path: file.path,
+        sha256: file.sha256,
+        status: notApproved ? "not-approved" : "invalid",
+        sources: [],
+        omitted_sources: 0,
+        limitation: notApproved
+            ? "Source-map content requires separate approval."
+            : "Source-map text was unavailable within approved limits.",
+    };
+};
+const flattenSourceMaps = (root, maximum) => {
+    if (!isRecord(root) || root.version !== 3)
+        return undefined;
+    const maps = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const map = pending.pop();
+        if (map === undefined || map.version !== 3)
+            return undefined;
+        if (Array.isArray(map.sections)) {
+            if (pending.length + maps.length + map.sections.length > maximum)
+                return undefined;
+            for (const section of map.sections) {
+                if (!isRecord(section) || !isRecord(section.map))
+                    return undefined;
+                pending.push(section.map);
+            }
+        }
+        else
+            maps.push(map);
+    }
+    return maps;
+};
+const truncatedSourceMap = (file, omitted, limitation) => ({
+    path: file.path,
+    sha256: file.sha256,
+    status: "truncated",
+    sources: [],
+    omitted_sources: omitted,
+    limitation,
+});
+const invalidSourceMap = (file, limitation) => ({
+    path: file.path,
+    sha256: file.sha256,
+    status: "invalid",
+    sources: [],
+    omitted_sources: 0,
+    limitation,
+});
+const findingCount = (analysis) => analysis.references.length +
+    analysis.endpoints.length +
+    analysis.storage.length +
+    analysis.role_paths.length +
+    analysis.source_map_urls.length +
+    analysis.bundler_registrations.length;
+const rangeForOffsets = (text, start, end) => ({
+    start: pointForOffset(text, start),
+    end: pointForOffset(text, end),
+});
+const pointForOffset = (text, offset) => {
+    const lines = text.slice(0, offset).split("\n");
+    return { line: lines.length, column: lines.at(-1)?.length ?? 0 };
+};
+const resolveSourceName = (root, source) => `${root}${root !== "" && !root.endsWith("/") ? "/" : ""}${source}`.slice(0, 4_096);
+const boundedString = (value) => typeof value === "string" && value.length > 0 ? value.slice(0, 4_096) : null;
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/application/JavaScriptArtifactAnalysisTypes.js

@@ -0,0 +1 @@
+export {};