rea-agents 0.3.0 → 0.4.0

package/dist/application/BinarySession.js

@@ -1,7 +1,17 @@
 import { parseBinaryTarget } from "../domain/binaryTarget.js";
-import { HopperCancelledError, NoBinaryOpenError, } from "../domain/errors.js";
+import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, EvidenceLimitError, AnalysisCancelledError, NoBinaryOpenError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
+import { createEvidence } from "../domain/evidence.js";
 import { EvidenceLedger } from "./EvidenceLedger.js";
+import { UnknownRegistryError } from "../domain/errors.js";
+import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+const REGISTRY_PROVIDER = {
+    id: "rea-unknown-registry",
+    name: "REA residual unknown registry",
+    version: "1",
+};
+const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
  *
@@ -17,7 +27,11 @@ export class BinarySession {
     #calls = new Set();
     #createClient;
     #providerIdentity;
-    #evidence = new EvidenceLedger({ maxRecords: 10_000 });
+    #capabilities;
+    #evidence = new EvidenceLedger({
+        maxRecords: 10_000,
+        maxBytes: 64 * 1024 * 1024,
+    });
     constructor(provider) {
         this.provider = provider;
         this.#createClient =
@@ -28,14 +42,45 @@ export class BinarySession {
             typeof provider === "function"
                 ? { id: "unidentified", name: "Unidentified provider", version: null }
                 : provider.identity();
+        this.#capabilities =
+            typeof provider === "function"
+                ? undefined
+                : new Map(provider
+                    .capabilities()
+                    .map((descriptor) => [descriptor.operation, descriptor]));
     }
     /** Identify the provider producing evidence for this session. */
-    providerIdentity() {
+    providerIdentity(operation) {
+        if (operation !== undefined) {
+            const exact = this.#capabilities?.get(operation)?.provider;
+            if (exact !== undefined)
+                return exact;
+            if (enhancedToolNameSchema.safeParse(operation).success) {
+                const providers = new Map();
+                for (const descriptor of this.#capabilities?.values() ?? [])
+                    if (descriptor.available &&
+                        OFFICIAL_OPERATIONS.has(descriptor.operation))
+                        providers.set(descriptor.provider.id, descriptor.provider);
+                if (providers.size === 1) {
+                    const provider = providers.values().next().value;
+                    if (provider !== undefined)
+                        return provider;
+                }
+            }
+        }
         return this.#providerIdentity;
     }
     /** Add one successful public observation to the session ledger. */
     recordEvidence(evidence) {
-        this.#evidence.record(evidence);
+        return this.#evidence.record(evidence);
+    }
+    /** Check that comparison input Evidence is already session-owned. */
+    hasEvidence(evidenceId) {
+        return this.#evidence.has(evidenceId);
+    }
+    /** Read one detached session-owned Evidence record by semantic ID. */
+    evidenceById(evidenceId) {
+        return this.#evidence.get(evidenceId);
     }
     /** Return a deterministic snapshot without clearing session evidence. */
     exportEvidenceBundle() {
@@ -45,6 +90,42 @@ export class BinarySession {
     importEvidenceBundle(bundle) {
         return this.#evidence.import(bundle);
     }
+    /** Create an approved residual unknown and immutable mutation evidence. */
+    recordUnknown(input) {
+        const evidence = unknownMutationEvidence(this.#active?.target, input);
+        return this.#evidence.recordUnknown(input, evidence);
+    }
+    /** Atomically record derived Evidence and its approved residual unknown. */
+    recordEvidenceWithUnknown(evidence, input) {
+        return this.#evidence.recordWithUnknown(evidence, input, unknownMutationEvidence(undefined, input));
+    }
+    /** Update one unknown using compare-and-swap revision semantics. */
+    updateUnknown(input) {
+        const evidence = createEvidence(this.#active?.target, REGISTRY_PROVIDER, {
+            predicateType: "rea.residual-unknown-mutation/v1",
+            operation: "update_unknown",
+            parameters: {
+                unknown_id: input.unknown_id,
+                expected_revision: input.expected_revision,
+            },
+            result: { action: "update", status: input.status },
+            confidence: "derived",
+            authority: "analyst-inference",
+            evidenceLinks: unknownEvidenceLinks(input),
+            limitations: [
+                "Registry mutation evidence records analyst intent, not proof of the answer.",
+            ],
+        });
+        return this.#evidence.updateUnknown(input, evidence);
+    }
+    /** Query stable current residual-unknown heads. */
+    listUnknowns(filters = {}) {
+        return this.#evidence.listUnknowns(filters);
+    }
+    /** Check whether current head is a bundle-valid resolved state. */
+    verifyUnknownResolution(unknownId) {
+        return this.#evidence.verifyUnknownResolution(unknownId);
+    }
     /**
      * Open or switch targets after draining calls against the current target.
      * Returns the switch failure even if best-effort restoration also fails.
@@ -52,12 +133,12 @@ export class BinarySession {
     open(path, options = {}) {
         return this.#serialize(async () => {
             if (isAborted(options.signal))
-                return err(new HopperCancelledError());
+                return err(new AnalysisCancelledError("open_binary"));
             const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
             if (!parsed.ok)
                 return parsed;
             if (isAborted(options.signal))
-                return err(new HopperCancelledError());
+                return err(new AnalysisCancelledError("open_binary"));
             if (this.#active?.target.path === parsed.value.path)
                 return ok(parsed.value);
             await this.#drainCalls();
@@ -74,7 +155,7 @@ export class BinarySession {
             if (isAborted(options.signal)) {
                 await client.close();
                 await this.#restore(previous);
-                return err(new HopperCancelledError());
+                return err(new AnalysisCancelledError("open_binary"));
             }
             this.#active = { target: parsed.value, client };
             return ok(parsed.value);
@@ -94,10 +175,45 @@ export class BinarySession {
     /** Describe the active binary session. */
     status() {
         const target = this.#active?.target;
+        const provider = {
+            id: this.#providerIdentity.id,
+            name: this.#providerIdentity.name,
+            version: this.#providerIdentity.version,
+        };
+        const capabilities = this.#capabilities === undefined
+            ? []
+            : [...this.#capabilities.values()]
+                .sort((left, right) => left.operation.localeCompare(right.operation))
+                .map((descriptor) => ({
+                operation: descriptor.operation,
+                available: descriptor.available,
+                reason: descriptor.reason,
+                input_contract_version: descriptor.inputContractVersion,
+                output_contract_version: descriptor.outputContractVersion,
+                pagination: descriptor.pagination,
+                exhaustive: descriptor.exhaustive,
+                effects: {
+                    mutates_artifact: descriptor.effects.mutatesArtifact,
+                    launches_process: descriptor.effects.launchesProcess,
+                    may_show_ui: descriptor.effects.mayShowUi,
+                    may_access_network: descriptor.effects.mayAccessNetwork,
+                    may_write_filesystem: descriptor.effects.mayWriteFilesystem,
+                    changes_permissions: descriptor.effects.changesPermissions,
+                    requires_root: descriptor.effects.requiresRoot,
+                },
+                limits: {
+                    max_results: descriptor.limits.maxResults,
+                    max_payload_bytes: descriptor.limits.maxPayloadBytes,
+                    timeout_ms: descriptor.limits.timeoutMs,
+                },
+                limitations: [...descriptor.limitations],
+            }));
         return target === undefined
-            ? { open: false }
+            ? { open: false, provider, capabilities }
             : {
                 open: true,
+                provider,
+                capabilities,
                 path: target.path,
                 sha256: target.sha256,
                 format: target.format,
@@ -115,9 +231,12 @@ export class BinarySession {
      * entering until the transition has settled.
      */
     async execute(name, arguments_, options) {
-        const transitioned = await this.#waitForTransition(options?.signal);
+        const transitioned = await this.#waitForTransition(name, options?.signal);
         if (!transitioned.ok)
             return transitioned;
+        const capability = this.#capabilities?.get(name);
+        if (this.#capabilities !== undefined && capability?.available !== true)
+            return err(new AnalysisCapabilityUnavailableError(this.#providerIdentity.id, name, capability?.reason ?? "operation is not declared by this provider"));
         const active = this.#active;
         if (active === undefined)
             return err(new NoBinaryOpenError());
@@ -148,26 +267,57 @@ export class BinarySession {
         else
             await client.close();
     }
-    async #waitForTransition(signal) {
+    async #waitForTransition(operation, signal) {
         if (signal?.aborted === true)
-            return err(new HopperCancelledError());
+            return err(new AnalysisCancelledError(operation));
         if (signal === undefined) {
             await this.#transition;
             return ok(undefined);
         }
         return new Promise((resolve) => {
             const onAbort = () => {
-                resolve(err(new HopperCancelledError()));
+                resolve(err(new AnalysisCancelledError(operation)));
             };
             signal.addEventListener("abort", onAbort, { once: true });
             this.#transition.then(() => {
                 signal.removeEventListener("abort", onAbort);
-                resolve(signal.aborted ? err(new HopperCancelledError()) : ok(undefined));
+                resolve(signal.aborted
+                    ? err(new AnalysisCancelledError(operation))
+                    : ok(undefined));
             }, () => {
                 signal.removeEventListener("abort", onAbort);
-                resolve(signal.aborted ? err(new HopperCancelledError()) : ok(undefined));
+                resolve(signal.aborted
+                    ? err(new AnalysisCancelledError(operation))
+                    : ok(undefined));
             });
         });
     }
 }
+const unknownMutationEvidence = (target, input) => createEvidence(target, REGISTRY_PROVIDER, {
+    predicateType: "rea.residual-unknown-mutation/v1",
+    operation: "record_unknown",
+    parameters: {
+        domain: input.domain,
+        severity: input.severity,
+    },
+    result: {
+        action: "record",
+        question: input.question,
+        required_authority: input.required_authority,
+        required_confidence: input.required_confidence,
+    },
+    confidence: "derived",
+    authority: "analyst-inference",
+    evidenceLinks: unknownEvidenceLinks(input),
+    limitations: [
+        "Registry mutation evidence records analyst intent, not proof of the answer.",
+    ],
+});
+const unknownEvidenceLinks = (input) => [
+    ...input.supporting_evidence_ids,
+    ...input.contradicting_evidence_ids,
+    ...("resolution" in input && input.resolution !== null
+        ? input.resolution.evidence_ids
+        : []),
+].filter((id, index, values) => values.indexOf(id) === index);
 const isAborted = (signal) => signal?.aborted === true;

package/dist/application/CompositeProvider.js

@@ -0,0 +1,73 @@
+import { ProviderSelectionError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+const compositeIdentity = (providers) => ({
+    id: `composite:${providers
+        .map((provider) => provider.identity().id)
+        .sort()
+        .join("+")}`,
+    name: "REA composite analysis provider",
+    version: null,
+});
+/** Deterministically route disjoint operations without eagerly starting children. */
+export class CompositeProvider {
+    providers;
+    #identity;
+    #capabilities;
+    #providerByOperation;
+    constructor(providers) {
+        this.providers = providers;
+        if (providers.length === 0)
+            throw new RangeError("CompositeProvider requires at least one provider");
+        this.#identity = Object.freeze(compositeIdentity(providers));
+        const routes = new Map();
+        const capabilities = [];
+        for (const provider of providers) {
+            for (const descriptor of provider.capabilities()) {
+                if (routes.has(descriptor.operation))
+                    throw new TypeError(`Multiple providers declare operation ${descriptor.operation}`);
+                routes.set(descriptor.operation, provider);
+                capabilities.push(descriptor);
+            }
+        }
+        this.#providerByOperation = routes;
+        this.#capabilities = Object.freeze(capabilities.sort((left, right) => left.operation.localeCompare(right.operation) ||
+            left.provider.id.localeCompare(right.provider.id)));
+    }
+    identity() {
+        return this.#identity;
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    createClient(target) {
+        const clients = new Map();
+        const clientFor = (provider) => {
+            const existing = clients.get(provider);
+            if (existing !== undefined)
+                return existing;
+            const created = provider.createClient(target);
+            clients.set(provider, created);
+            return created;
+        };
+        return {
+            execute: (operation, parameters, options) => {
+                if (operation === "health")
+                    return Promise.resolve(ok({
+                        result: null,
+                        rawResult: null,
+                        provider: this.#identity,
+                        limitations: [],
+                        locations: [],
+                        subject: null,
+                    }));
+                const provider = this.#providerByOperation.get(operation);
+                return provider === undefined
+                    ? Promise.resolve(err(new ProviderSelectionError(operation)))
+                    : clientFor(provider).execute(operation, parameters, options);
+            },
+            close: async () => {
+                await Promise.allSettled([...clients.values()].map(async (client) => client.close()));
+            },
+        };
+    }
+}

package/dist/application/DirectAnalysis.js

@@ -1,13 +1,22 @@
 import { parseConfig } from "../config.js";
+import { EnhancedTools } from "./EnhancedTools.js";
 import { createBinarySession } from "./runtime.js";
 import { silentLogger } from "../logger.js";
 import { createEvidence } from "../domain/evidence.js";
+const WORKFLOW_PROVIDER = {
+    id: "rea-workflow",
+    name: "REA composed investigation workflow",
+    version: "1",
+};
 /**
  * Open one binary, execute one tool, and always release the bridge session.
  * Unlike MCP mode, every CLI invocation is intentionally isolated and does not
  * retain a target or bridge resources for a subsequent command.
  */
-export const runDirectAnalysis = async (path, tool, arguments_, logger = silentLogger) => {
+export const runDirectAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, logger);
+/** Execute one provider-native semantic operation with atomic provenance. */
+export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, logger);
+const runAnalysis = async (path, tool, arguments_, logger) => {
     const config = parseConfig(process.env);
     if (!config.ok)
         return { error: config.error._tag, message: config.error.message };
@@ -16,12 +25,27 @@ export const runDirectAnalysis = async (path, tool, arguments_, logger = silentL
         const opened = await session.open(path);
         if (!opened.ok)
             return { error: opened.error._tag, message: opened.error.message };
+        if (tool === "binary_overview") {
+            const result = await new EnhancedTools(session).execute(tool, arguments_);
+            return result.ok
+                ? createEvidence(opened.value, WORKFLOW_PROVIDER, {
+                    operation: tool,
+                    parameters: arguments_,
+                    result: result.value,
+                    confidence: "derived",
+                    limitations: ["Derived by an REA composed workflow."],
+                })
+                : { error: result.error._tag, message: result.error.message };
+        }
         const result = await session.execute(tool, arguments_);
         return result.ok
-            ? createEvidence(opened.value, session.providerIdentity(), {
+            ? createEvidence(result.value.subject ?? opened.value, result.value.provider, {
                 operation: tool,
                 parameters: arguments_,
-                result: result.value,
+                result: result.value.result,
+                rawResult: result.value.rawResult,
+                limitations: result.value.limitations,
+                locations: result.value.locations,
             })
             : { error: result.error._tag, message: result.error.message };
     }

package/dist/application/Doctor.js

@@ -7,8 +7,10 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { probeHomebrew } from "./homebrew.js";
+import { linuxHopperLauncherPath, linuxSharedLibrariesAvailable, readLinuxDistribution, } from "./LinuxHopper.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_HOPPER = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
+const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
 /**
  * Check requirements and an optional target without mutating the host.
  * Every failed check includes remediation suitable for either the one-shot CLI
@@ -17,13 +19,27 @@ const DEFAULT_HOPPER = "/Applications/Hopper Disassembler.app/Contents/MacOS/hop
 export const runDoctor = async (target, host = systemDoctorHost()) => {
     const checks = [];
     const nodeMajor = parseMajor(host.nodeVersion);
-    checks.push(check("node", nodeMajor >= 22, host.nodeVersion, "Install Node.js 22 or newer."));
+    checks.push(check("node", nodeMajor >= 24, host.nodeVersion, {
+        remediation: "Install Node.js 24.18 or newer.",
+        classification: "missing_dependency",
+    }));
     const macosVersion = host.platform === "darwin" ? await host.macosVersion() : undefined;
     const macosMajor = macosVersion === undefined ? 0 : parseMajor(macosVersion);
-    checks.push(check("macos", host.platform === "darwin" && macosMajor >= 12, macosVersion ?? host.platform, "Hopper requires macOS 12 or newer."));
+    const linuxDistribution = host.platform === "linux" ? await host.linuxDistribution() : undefined;
+    const supportedHost = (host.platform === "darwin" && macosMajor >= 12) ||
+        (host.platform === "linux" && linuxDistribution?.supported === true);
+    checks.push(check("host", supportedHost, macosVersion ??
+        (linuxDistribution === undefined
+            ? host.platform
+            : `${linuxDistribution.id} ${linuxDistribution.versionId ?? "unknown"}`), {
+        remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.",
+        classification: "unsupported_host",
+    }));
     const candidates = [
         host.configuredHopperPath,
         DEFAULT_HOPPER,
+        SYSTEM_LINUX_HOPPER,
+        linuxHopperLauncherPath(homedir()),
         ...(await host.manualHopperPaths()),
         await host.brewHopperPath(),
     ].filter((value) => value !== undefined);
@@ -33,9 +49,15 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             hopperPath = candidate;
             break;
         }
-    checks.push(check("hopper", hopperPath !== undefined, hopperPath, "Install Hopper with: brew install --cask hopper-disassembler, or set HOPPER_LAUNCHER_PATH."));
+    checks.push(check("hopper", hopperPath !== undefined, hopperPath, {
+        remediation: "Run rea setup --yes to install Hopper, or set HOPPER_LAUNCHER_PATH.",
+        classification: "missing_analysis_engine",
+    }));
     if (target !== undefined)
-        checks.push(check("target", await host.validTarget(target), target, "Supply a readable local app or program path."));
+        checks.push(check("target", await host.validTarget(target), target, {
+            remediation: "Supply a readable local app or program path.",
+            classification: "config_drift",
+        }));
     return {
         healthy: checks.every(({ ok }) => ok),
         ...(hopperPath === undefined ? {} : { hopperPath }),
@@ -57,12 +79,18 @@ export const systemDoctorHost = () => ({
             return undefined;
         }
     },
+    linuxDistribution: readLinuxDistribution,
     async validTarget(path) {
         return (await parseBinaryTarget(path)).ok;
     },
     async executable(path) {
         try {
             await access(path, constants.X_OK);
+            if (process.platform === "linux") {
+                const linked = await execFileAsync("ldd", [path]);
+                if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
+                    return false;
+            }
             return true;
         }
         catch {
@@ -102,9 +130,10 @@ export const systemDoctorHost = () => ({
     },
 });
 const parseMajor = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
-const check = (name, ok, detail, remediation) => ({
+const check = (name, ok, detail, failure) => ({
     name,
     ok,
+    classification: ok ? "healthy" : failure.classification,
     ...(detail === undefined ? {} : { detail }),
-    ...(ok ? {} : { remediation }),
+    ...(ok ? {} : { remediation: failure.remediation }),
 });

package/dist/application/EnhancedTools.js

@@ -1,5 +1,5 @@
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
-import { AnalysisProtocolError } from "../domain/errors.js";
+import { AnalysisInputError, AnalysisOutputError, } from "../domain/errors.js";
 import { parseDocuments, parseFunctionDossier, parseAddressedPage, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
 import { err, ok } from "../domain/result.js";
 import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, discoverSwiftClasses, } from "../domain/symbolAnalysis.js";
@@ -282,10 +282,10 @@ export class EnhancedTools {
             if (!xrefs.ok)
                 return xrefs;
             if (!Array.isArray(xrefs.value))
-                return err(new AnalysisProtocolError("xrefs returned a non-array result"));
+                return err(new AnalysisOutputError("xrefs", "provider returned a non-array result"));
             for (const source of xrefs.value) {
                 if (typeof source !== "string")
-                    return err(new AnalysisProtocolError("xrefs returned a non-address value"));
+                    return err(new AnalysisOutputError("xrefs", "provider returned a non-address value"));
                 if (operations >= operationBudget) {
                     residual.add("Containing-procedure resolution stopped at the operation budget.");
                     break;
@@ -331,16 +331,17 @@ export class EnhancedTools {
                 return ok(entries);
             }
             if (page.value.nextOffset <= offset) {
-                return err(new AnalysisProtocolError(`${tool} returned a non-advancing pagination offset`));
+                return err(new AnalysisOutputError(tool, "provider returned a non-advancing pagination offset"));
             }
             offset = page.value.nextOffset;
         }
     }
-    #call(name, arguments_, signal) {
-        return this.analysis.execute(name, arguments_, signal === undefined ? {} : { signal });
+    async #call(name, arguments_, signal) {
+        const execution = await this.analysis.execute(name, arguments_, signal === undefined ? {} : { signal });
+        return execution.ok ? ok(execution.value.result) : execution;
     }
 }
-const invalidInput = (name, cause) => Promise.resolve(err(new AnalysisProtocolError(`Invalid ${name} input after MCP validation`, {
+const invalidInput = (name, cause) => Promise.resolve(err(new AnalysisInputError(name, {
     cause,
 })));
 const resolveAddress = (value) => {

package/dist/application/EvidenceBundleCommands.js

@@ -0,0 +1,29 @@
+import { err, ok } from "../domain/result.js";
+import { EvidenceLedger } from "./EvidenceLedger.js";
+import { readEvidenceBundle, writeEvidenceBundle, } from "./EvidenceBundleFiles.js";
+/** Validate and merge one bundle using the same bounded ledger as MCP. */
+export const importEvidenceBundleCommand = async (path, policy) => {
+    const loaded = await readEvidenceBundle(path, policy);
+    if (!loaded.ok)
+        return loaded;
+    const ledger = createLedger();
+    const imported = ledger.import(loaded.value);
+    return imported.ok
+        ? ok({ imported: imported.value, total: ledger.export().records.length })
+        : imported;
+};
+/** Validate a source bundle and atomically export canonical bytes. */
+export const exportEvidenceBundleCommand = async (sourcePath, outputPath, overwrite, policy) => {
+    const loaded = await readEvidenceBundle(sourcePath, policy);
+    if (!loaded.ok)
+        return loaded;
+    return projectWrite(loaded.value, await writeEvidenceBundle(loaded.value, outputPath, overwrite, policy));
+};
+const createLedger = () => new EvidenceLedger({ maxRecords: 10_000, maxBytes: 64 * 1024 * 1024 });
+const projectWrite = (bundle, written) => written.ok
+    ? ok({
+        path: written.value.path,
+        bytes: written.value.bytes,
+        records: bundle.records.length,
+    })
+    : err(written.error);