rea-agents 1.6.0 → 2.0.0

package/bridge/hopper_bridge.py

@@ -106,7 +106,11 @@ def _procedure_name(procedure):
 
 
 def _procedure_identity(procedure):
-    return {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure)}
+    return {
+        "address": _hex(procedure.getEntryPoint()),
+        "name": _procedure_name(procedure),
+        "classification": None,
+    }
 
 
 def _procedure_locals(procedure):
@@ -609,7 +613,7 @@ def _analyze_function(document, params):
     def collection(name, items, scan_limited=False):
         return _bounded(items, _collection_offset(params, name), limit, None, scan_limited)
     return {
-        "procedure": {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure), "signature": procedure.signatureString(), "locals": _procedure_locals(procedure)},
+        "procedure": {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure), "classification": None, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure)},
         "pseudocode": {"text": pseudo_text, "total_chars": len(pseudo), "returned_chars": len(pseudo_text), "truncated": pseudo_next < len(pseudo), "next_offset": pseudo_next if pseudo_next < len(pseudo) else None},
         "assembly": _bounded(assembly_lines, assembly_offset, max_instructions),
         "comments": collection("comments", comments, instruction_scan_truncated),
@@ -620,6 +624,12 @@ def _analyze_function(document, params):
         "referenced_names": collection("referenced_names", referenced_names, instruction_scan_truncated),
         "basic_blocks": collection("basic_blocks", blocks),
         "instruction_scan": {"scanned": len(addresses), "truncated": instruction_scan_truncated},
+        "limitations": [
+            "Hopper's public Python API does not classify reference kinds.",
+            "Hopper's public Python API does not expose equivalent external or thunk classification in this dossier.",
+            "Unresolved indirect calls without reported target addresses are not represented as call edges.",
+            "Pseudocode and assembly are provider-specific representations, not original source.",
+        ],
     }
 
 
@@ -766,7 +776,7 @@ def _dispatch(method, params):
         if method == "procedure_info":
             blocks = list(procedure.basicBlockIterator())
             length = sum(max(0, block.getEndingAddress() - block.getStartingAddress()) for block in blocks)
-            return {"name": _procedure_name(procedure), "entrypoint": _hex(procedure.getEntryPoint()), "basicblock_count": procedure.getBasicBlockCount(), "length": length, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure)}
+            return {"name": _procedure_name(procedure), "entrypoint": _hex(procedure.getEntryPoint()), "basicblock_count": procedure.getBasicBlockCount(), "length": length, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure), "classification": None}
     if method == "set_address_name":
         address = _address(document, params.get("address"))
         result = document.setNameAtAddress(address, params["name"])

package/dist/application/AbortablePromise.js

@@ -0,0 +1,25 @@
+/** Sentinel returned when an abort signal wins an asynchronous race. */
+export const ABORTED = Symbol("aborted");
+/**
+ * Await a promise without depending on the producer to observe cancellation.
+ * The producer still receives its signal separately and remains responsible for
+ * releasing any resources that it owns.
+ */
+export const waitForAbortable = async (pending, signal) => {
+    if (signal === undefined)
+        return pending;
+    if (signal.aborted)
+        return ABORTED;
+    let onAbort;
+    const cancelled = new Promise((resolve) => {
+        onAbort = () => resolve(ABORTED);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([pending, cancelled]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener("abort", onAbort);
+    }
+};

package/dist/application/AnalysisProvider.js

@@ -6,6 +6,9 @@ export const createAnalysisExecution = (result, provider, options = {}) => ({
         ? jsonValueSchema.parse(result)
         : jsonValueSchema.parse(options.rawResult),
     provider,
+    ...(options.analysisProfile === undefined
+        ? {}
+        : { analysisProfile: structuredClone(options.analysisProfile) }),
     limitations: [...(options.limitations ?? [])],
     locations: [...(options.locations ?? [])],
     subject: options.subject ?? null,

package/dist/application/AnalysisProviderEvaluation.js

@@ -0,0 +1,60 @@
+import { analysisProfileSchema, } from "../domain/analysisProfile.js";
+import { AnalysisCancelledError } from "../domain/errors.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
+/** Resolve and validate one provider profile without starting its client. */
+export const evaluateAnalysisProviderCandidate = async (candidate, status, target, signal) => {
+    if (signalIsAborted(signal))
+        return err(new AnalysisCancelledError("open_binary"));
+    let resolved;
+    try {
+        const resolution = await waitForAbortable(candidate.resolveAnalysisProfile(target, signal === undefined ? undefined : { signal }), signal);
+        if (resolution === ABORTED)
+            return err(new AnalysisCancelledError("open_binary"));
+        resolved = resolution;
+    }
+    catch {
+        return ok(rejectedProfile(candidate, status, "Provider profile resolution threw"));
+    }
+    if (signalIsAborted(signal))
+        return err(new AnalysisCancelledError("open_binary"));
+    if (!resolved.ok && resolved.error instanceof AnalysisCancelledError)
+        return err(resolved.error);
+    if (!resolved.ok)
+        return ok(rejectedProfile(candidate, status, resolved.error.message, {
+            error_tag: resolved.error._tag,
+        }));
+    try {
+        if (resolved.value.profile === null)
+            return ok(rejectedProfile(candidate, status, "Provider version or analysis profile could not be resolved"));
+        const profile = analysisProfileSchema.parse(resolved.value.profile);
+        const compatibility = jsonObjectSchema.parse(resolved.value.compatibility);
+        const identity = candidate.identity();
+        if (profile.provider.id !== identity.id ||
+            profile.provider.name !== identity.name ||
+            (identity.version !== null &&
+                profile.provider.version !== identity.version))
+            return ok(rejectedProfile(candidate, status, "Resolved analysis profile has mismatched provider identity"));
+        return ok({ candidate, status, profile, compatibility });
+    }
+    catch {
+        return ok(rejectedProfile(candidate, status, "Provider returned an invalid analysis profile"));
+    }
+};
+const signalIsAborted = (signal) => signal?.aborted === true;
+const rejectedProfile = (candidate, status, reason, diagnostics = {}) => ({
+    candidate,
+    status: {
+        ...status,
+        availability: {
+            status: "unavailable",
+            code: "version_unresolved",
+            reason,
+            diagnostics: jsonObjectSchema.parse({
+                ...status.availability.diagnostics,
+                ...diagnostics,
+            }),
+        },
+    },
+});

package/dist/application/AnalysisProviderRegistry.js

@@ -0,0 +1,228 @@
+import { analysisProviderIdSchema, analysisProviderSelectorSchema, } from "../contracts/providerSelection.js";
+import { AnalysisCancelledError, ProviderSelectionError, } from "../domain/errors.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { evaluateAnalysisProviderCandidate, } from "./AnalysisProviderEvaluation.js";
+/**
+ * Discover and select overlapping deep providers without starting their clients.
+ * Registration order never affects selection or caller-visible output.
+ */
+export class AnalysisProviderRegistry {
+    #providers;
+    #byId;
+    #declaredOperations;
+    #defaultSelector;
+    constructor(providers, defaultSelector = "auto") {
+        this.#defaultSelector =
+            analysisProviderSelectorSchema.parse(defaultSelector);
+        const byId = new Map();
+        const declaredOperations = new Set();
+        for (const provider of providers) {
+            const identity = provider.identity();
+            if (!analysisProviderIdSchema.safeParse(identity.id).success)
+                throw new TypeError(`Invalid analysis provider ID: ${identity.id}`);
+            if (byId.has(identity.id))
+                throw new TypeError(`Duplicate analysis provider ID: ${identity.id}`);
+            const providerOperations = new Set();
+            for (const capability of provider.capabilities()) {
+                if (capability.provider.id !== identity.id ||
+                    capability.provider.name !== identity.name ||
+                    capability.provider.version !== identity.version)
+                    throw new TypeError(`Provider ${identity.id} published mismatched capability provenance for ${capability.operation}`);
+                if (providerOperations.has(capability.operation))
+                    throw new TypeError(`Provider ${identity.id} declares operation ${capability.operation} more than once`);
+                providerOperations.add(capability.operation);
+                declaredOperations.add(capability.operation);
+            }
+            byId.set(identity.id, provider);
+        }
+        this.#providers = Object.freeze([...providers].sort((left, right) => left.identity().id.localeCompare(right.identity().id)));
+        this.#byId = byId;
+        this.#declaredOperations = Object.freeze([...declaredOperations].sort((left, right) => left.localeCompare(right)));
+    }
+    /** Return the configured default without interpreting it as priority. */
+    defaultSelector() {
+        return this.#defaultSelector;
+    }
+    /** List configured candidate identities in canonical provider-ID order. */
+    identities() {
+        return this.#providers.map((provider) => structuredClone(provider.identity()));
+    }
+    /** List the unique deep-operation declarations without probing candidates. */
+    declaredOperations() {
+        return [...this.#declaredOperations];
+    }
+    /** Discover candidates for status without resolving profiles or starting clients. */
+    candidates(target) {
+        return this.#providers.map((provider) => candidateStatus(provider, target));
+    }
+    /** Select one whole deep-operation family for a parsed target. */
+    async select(target, requestedSelector, options = {}) {
+        if (signalIsAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const parsedRequest = requestedSelector === undefined
+            ? undefined
+            : analysisProviderSelectorSchema.safeParse(requestedSelector);
+        if (parsedRequest !== undefined && !parsedRequest.success)
+            return err(selectionError("invalid_options", typeof requestedSelector === "string"
+                ? requestedSelector
+                : "<invalid>", this.candidates(target)));
+        const request = parsedRequest?.data;
+        const selector = request ?? this.#defaultSelector;
+        const baseline = this.candidates(target);
+        if (signalIsAborted(options.signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        if (request === undefined &&
+            selector !== "auto" &&
+            baseline.length > 0 &&
+            baseline.every(({ targetSupport }) => targetSupport.status === "unsupported"))
+            return ok({
+                requestedProviderId: selector,
+                binding: null,
+                candidates: baseline,
+            });
+        if (selector !== "auto")
+            return this.#selectConcrete({ target, baseline, signal: options.signal }, selector, request === undefined ? "environment" : "request");
+        return this.#selectAutomatically({
+            target,
+            baseline,
+            signal: options.signal,
+        });
+    }
+    /** Explain why a deep operation is unavailable on an unbound target. */
+    unboundOperationError(operation, selection) {
+        const reason = selection.candidates.length > 0 &&
+            selection.candidates.every(({ targetSupport }) => targetSupport.status === "unsupported")
+            ? "target_unsupported"
+            : "provider_unavailable";
+        return selectionError(reason, selection.requestedProviderId, selection.candidates, operation);
+    }
+    async #selectConcrete(context, providerId, source) {
+        const { baseline, signal, target } = context;
+        const provider = this.#byId.get(providerId);
+        if (provider === undefined)
+            return err(selectionError("unknown_provider", providerId, baseline));
+        const initial = baseline.find(({ provider: identity }) => identity.id === providerId);
+        if (initial === undefined)
+            throw new TypeError("Registered provider is absent from discovery output");
+        if (initial.targetSupport.status !== "supported")
+            return err(selectionError("target_unsupported", providerId, baseline));
+        if (initial.availability.status === "unavailable")
+            return err(selectionError("provider_unavailable", providerId, baseline));
+        const evaluation = await evaluateAnalysisProviderCandidate(provider, initial, target, signal);
+        if (!evaluation.ok)
+            return evaluation;
+        const evaluated = evaluation.value;
+        const statuses = replaceCandidate(baseline, evaluated.status);
+        if (evaluated.profile === undefined ||
+            evaluated.compatibility === undefined)
+            return err(selectionError("provider_unavailable", providerId, statuses));
+        return ok(selectedResult(providerId, source, {
+            ...evaluated,
+            profile: evaluated.profile,
+            compatibility: evaluated.compatibility,
+        }, statuses));
+    }
+    async #selectAutomatically(context) {
+        const { baseline, signal, target } = context;
+        const results = await Promise.all(this.#providers.map(async (provider) => {
+            const status = baseline.find(({ provider: identity }) => identity.id === provider.identity().id);
+            if (status === undefined)
+                throw new TypeError("Registered provider is absent from discovery output");
+            return status.availability.status === "available" &&
+                status.targetSupport.status === "supported"
+                ? evaluateAnalysisProviderCandidate(provider, status, target, signal)
+                : ok({
+                    candidate: provider,
+                    status,
+                });
+        }));
+        const cancelled = results.find((result) => !result.ok);
+        if (cancelled !== undefined && !cancelled.ok)
+            return cancelled;
+        const evaluations = results.map((result) => {
+            if (!result.ok)
+                throw new TypeError("Cancelled candidate evaluation disappeared");
+            return result.value;
+        });
+        const statuses = evaluations.map(({ status }) => status);
+        const usable = evaluations.filter((evaluation) => evaluation.profile !== undefined &&
+            evaluation.compatibility !== undefined);
+        if (usable.length === 0)
+            return ok({
+                requestedProviderId: "auto",
+                binding: null,
+                candidates: statuses,
+            });
+        if (usable.length > 1)
+            return err(selectionError("ambiguous", "auto", statuses));
+        const selected = usable[0];
+        if (selected === undefined)
+            throw new TypeError("Usable provider selection disappeared");
+        return ok(selectedResult("auto", "auto-single-candidate", selected, statuses));
+    }
+}
+const candidateStatus = (provider, target) => ({
+    provider: structuredClone(provider.identity()),
+    availability: cloneAvailability(provider.inspectAvailability()),
+    targetSupport: target === undefined
+        ? {
+            status: "unknown",
+            code: null,
+            reason: "No target is open.",
+            diagnostics: {},
+        }
+        : cloneTargetSupport(provider.inspectTargetSupport(target)),
+    selected: false,
+    capabilities: provider
+        .capabilities()
+        .map((capability) => structuredClone(capability)),
+});
+const signalIsAborted = (signal) => signal?.aborted === true;
+const selectedResult = (requestedProviderId, source, evaluated, statuses) => {
+    const selectedStatus = {
+        ...evaluated.status,
+        provider: structuredClone(evaluated.profile.provider),
+        selected: true,
+    };
+    return {
+        requestedProviderId,
+        binding: {
+            provider: evaluated.candidate,
+            identity: structuredClone(evaluated.profile.provider),
+            selectionSource: source,
+            profile: structuredClone(evaluated.profile),
+            compatibility: structuredClone(evaluated.compatibility),
+        },
+        candidates: replaceCandidate(statuses, selectedStatus),
+    };
+};
+const replaceCandidate = (statuses, replacement) => statuses.map((status) => status.provider.id === replacement.provider.id ? replacement : status);
+const selectionError = (reason, requestedProviderId, candidates, operation = "open_binary") => new ProviderSelectionError({
+    operation,
+    reason,
+    requestedProviderId,
+    candidateIds: candidates.map(({ provider }) => provider.id),
+    rejections: candidateRejections(candidates),
+});
+const candidateRejections = (candidates) => candidates.flatMap((candidate) => [
+    ...(candidate.availability.status === "unavailable"
+        ? [candidate.availability]
+        : []),
+    ...(candidate.targetSupport.status === "unsupported"
+        ? [candidate.targetSupport]
+        : []),
+].map((rejection) => ({
+    providerId: candidate.provider.id,
+    code: rejection.code,
+    reason: rejection.reason,
+    diagnostics: structuredClone(rejection.diagnostics),
+})));
+const cloneAvailability = (availability) => ({
+    ...availability,
+    diagnostics: jsonObjectSchema.parse(availability.diagnostics),
+});
+const cloneTargetSupport = (support) => ({
+    ...support,
+    diagnostics: jsonObjectSchema.parse(support.diagnostics),
+});

package/dist/application/AnalysisSnapshotCache.js

@@ -1,6 +1,6 @@
 import { EvidenceIntegrityError, NoBinaryOpenError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
-import { analysisQueryId, createAnalysisSnapshotEntry, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 const STATEFUL_OPERATIONS = new Set([
     "health",
@@ -35,24 +35,32 @@ export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATE
 export class AnalysisSnapshotCache {
     #entries = new Map();
     #target;
-    /** Whether staged entries belong to the supplied binary. */
-    matches(target) {
-        return (this.#target === undefined || snapshotMatchesTarget(this.#target, target));
+    #binding;
+    /** Whether staged entries belong to the supplied target and profile. */
+    matches(target, profile) {
+        return ((this.#target === undefined && this.#binding === undefined) ||
+            (this.#target !== undefined &&
+                this.#binding !== undefined &&
+                profile !== undefined &&
+                snapshotMatchesTarget(this.#target, target) &&
+                snapshotMatchesProfile(this.#binding, profile)));
     }
-    /** Replace cache state when the active binary identity changes. */
-    select(target) {
-        if (!this.matches(target))
+    /** Replace cache state when the target or selected profile changes. */
+    select(target, profile) {
+        if (!this.matches(target, profile))
             this.#entries.clear();
         this.#target = snapshotTarget(target);
+        this.#binding = snapshotBinding(profile);
     }
     /** Merge already-validated entries and return the new-entry count. */
     stage(snapshot) {
-        if (this.#target !== undefined &&
-            (this.#target.sha256 !== snapshot.target.sha256 ||
-                this.#target.format !== snapshot.target.format ||
-                this.#target.architecture !== snapshot.target.architecture))
+        if ((this.#target !== undefined &&
+            JSON.stringify(this.#target) !== JSON.stringify(snapshot.target)) ||
+            (this.#binding !== undefined &&
+                !snapshotMatchesProfile(this.#binding, snapshot.binding.analysis_profile)))
             this.#entries.clear();
         this.#target = structuredClone(snapshot.target);
+        this.#binding = structuredClone(snapshot.binding);
         let imported = 0;
         for (const entry of snapshot.entries) {
             if (!this.#entries.has(entry.query_id))
@@ -62,20 +70,23 @@ export class AnalysisSnapshotCache {
         return imported;
     }
     /** Build a complete snapshot for an active target. */
-    export(target, evidenceBundle) {
-        if (target === undefined)
+    export(target, profile, evidenceBundle) {
+        if (target === undefined || profile === undefined)
             return err(new NoBinaryOpenError());
         return ok({
-            snapshot_version: 1,
+            snapshot_version: 2,
             target: snapshotTarget(target),
+            binding: snapshotBinding(profile),
             entries: this.entries(),
             evidence_bundle: structuredClone(evidenceBundle),
         });
     }
     /** Validate target identity, merge evidence atomically, then stage entries. */
     import(snapshot, active, mergeEvidence) {
-        if (active !== undefined && !snapshotMatchesTarget(snapshot.target, active))
-            return err(new EvidenceIntegrityError("Analysis snapshot target does not match the active binary"));
+        if (active !== undefined &&
+            (!snapshotMatchesTarget(snapshot.target, active.target) ||
+                !snapshotMatchesProfile(snapshot.binding, active.profile)))
+            return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the active binary"));
         const importedEvidence = mergeEvidence(snapshot.evidence_bundle);
         return importedEvidence.ok ? ok(this.stage(snapshot)) : importedEvidence;
     }
@@ -86,8 +97,8 @@ export class AnalysisSnapshotCache {
             .map((entry) => structuredClone(entry));
     }
     /** Replay an exact provider-specific query, marking its cached provenance. */
-    lookup(target, operation, parameters, provider) {
-        const queryId = analysisQueryId(snapshotTarget(target), operation, parameters, provider);
+    lookup(target, profile, operation, parameters) {
+        const queryId = analysisQueryId(snapshotTarget(target), snapshotBinding(profile), operation, parameters);
         const cached = this.#entries.get(queryId);
         if (cached === undefined)
             return undefined;
@@ -96,6 +107,7 @@ export class AnalysisSnapshotCache {
             result: cached.execution.result,
             rawResult: cached.execution.raw_result,
             provider: cached.execution.provider,
+            analysisProfile: structuredClone(profile),
             limitations: [
                 ...cached.execution.limitations,
                 "Loaded from a local REA analysis snapshot; this call did not re-run the provider.",
@@ -118,16 +130,24 @@ export class AnalysisSnapshotCache {
         });
     }
     /** Record one successful immutable call unless the cache is full. */
-    record(target, operation, parameters, execution) {
+    record(input) {
+        const { target, profile, operation, parameters, execution } = input;
         if (this.#entries.size >= 10_000)
             return;
-        this.select(target);
-        const entry = createAnalysisSnapshotEntry(snapshotTarget(target), operation, parameters, execution);
+        this.select(target, profile);
+        const entry = createAnalysisSnapshotEntry({
+            target: snapshotTarget(target),
+            binding: snapshotBinding(profile),
+            operation,
+            parameters,
+            execution,
+        });
         this.#entries.set(entry.query_id, entry);
     }
     /** Forget all target-bound entries. */
     clear() {
         this.#entries.clear();
         this.#target = undefined;
+        this.#binding = undefined;
     }
 }

package/dist/application/AnalysisSnapshotFiles.js

@@ -11,9 +11,7 @@ export const readAnalysisSnapshot = async (path, policy) => {
         return ok(parseAnalysisSnapshot(loaded.value));
     }
     catch (cause) {
-        return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
-            cause,
-        }));
+        return err(new EvidenceIntegrityError(snapshotValidationMessage(cause), { cause }));
     }
 };
 /** Atomically write a deterministic analysis snapshot inside an approved root. */
@@ -23,9 +21,10 @@ export const writeAnalysisSnapshot = async (snapshot, path, overwrite, policy) =
         encoded = serializeAnalysisSnapshot(snapshot);
     }
     catch (cause) {
-        return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
-            cause,
-        }));
+        return err(new EvidenceIntegrityError(snapshotValidationMessage(cause), { cause }));
     }
     return writeBoundedText(encoded, path, overwrite, policy);
 };
+const snapshotValidationMessage = (cause) => cause instanceof TypeError
+    ? cause.message
+    : "Analysis snapshot validation failed";