rea-agents 6.4.0 → 6.5.0

package/dist/application/CapabilityInventory.js

@@ -1,12 +1,18 @@
 import { z } from "zod";
-import { providerCapability, } from "../contracts/toolOutputSchemaPrimitives.js";
+import { sqliteDatabaseCapability } from "./sqlite/SqliteDatabaseCapability.js";
+import { expandProviderCapabilities, providerCapabilitySet, toolAvailabilityInventory, TOOL_ANNOTATION_NAMES, TOOL_EFFECT_NAMES, } from "../contracts/toolOutputSchemaPrimitives.js";
+import { isMachOFormat } from "../domain/binaryTargetTypes.js";
 import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { FRIDA_TOOL_CONTRACTS } from "../contracts/fridaToolContracts.js";
 import { clientRequirementsFor, NO_CLIENT_FEATURES, } from "./CapabilityClientRequirements.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 const statusSchema = z.object({
     open: z.boolean(),
     kind: z.enum(["executable", "database", "archive", "artifact"]).optional(),
     format: z.string().optional(),
-    capabilities: z.array(providerCapability),
+    capabilities: z
+        .array(providerCapabilitySet)
+        .transform(expandProviderCapabilities),
 });
 const ENHANCED_REQUIREMENTS = {
     trace_native_values: ["analyze_function", "resolve_native_call_targets"],
@@ -23,16 +29,15 @@ const ENHANCED_REQUIREMENTS = {
     analyze_swift_types: ["list_procedures"],
     find_xrefs_to_name: ["list_names", "xrefs"],
     binary_overview: [
-        "list_segments",
-        "list_documents",
+        ["current_document", "list_documents"],
         "list_procedures",
         "list_strings",
     ],
     analyze_function: ["analyze_function"],
     inspect_native_api: ["analyze_function"],
     trace_feature: [
-        "list_strings",
-        "list_procedures",
+        "search_strings",
+        "search_procedures",
         "xrefs",
         "resolve_containing_procedure",
     ],
@@ -44,8 +49,10 @@ const ACTIVE_TARGET_KINDS = new Set([
     "native-provider",
     "artifact-provider",
 ]);
+const FRIDA_OPERATION_NAMES = new Set(FRIDA_TOOL_CONTRACTS.map(({ name }) => name));
 /** Native contracts defined only for an active Mach-O executable. */
 const MACHO_TARGET_OPERATIONS = new Set([
+    "inspect_signature",
     "inspect_macho",
     "list_architectures",
     "observe_native_calls",
@@ -120,7 +127,48 @@ export const buildCapabilityInventory = (sessionStatus, policy, clientFeatures =
                 reason: availability.reason,
                 remediation: availability.remediation,
             };
-    }).sort((left, right) => left.name.localeCompare(right.name));
+    }).sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
+};
+const EMPTY_CLIENT_REQUIREMENTS = {
+    required: [],
+    optional: [],
+    missing_required: [],
+    missing_optional: [],
+};
+/** Compact repeated metadata while retaining every operation's current availability inline. */
+export const compactToolAvailability = (availability) => {
+    const clientRequirements = availability[0]?.client_requirements ?? EMPTY_CLIENT_REQUIREMENTS;
+    const groups = new Map();
+    for (const entry of availability) {
+        const effects = TOOL_EFFECT_NAMES.filter((name) => entry.effects[name]);
+        const annotations = TOOL_ANNOTATION_NAMES.filter((name) => entry.annotations[name]);
+        const groupFacts = {
+            surface: entry.surface,
+            effects,
+            annotations,
+            available: entry.available,
+            reason: entry.reason,
+            remediation: entry.remediation,
+            ...(entry.default_mode_available === undefined
+                ? {}
+                : { default_mode_available: entry.default_mode_available }),
+            ...(entry.modes === undefined ? {} : { modes: [...entry.modes] }),
+            ...(JSON.stringify(entry.client_requirements) ===
+                JSON.stringify(clientRequirements)
+                ? {}
+                : { client_requirements: entry.client_requirements }),
+        };
+        const key = JSON.stringify(groupFacts);
+        const existing = groups.get(key);
+        if (existing)
+            existing.names.push(entry.name);
+        else
+            groups.set(key, { ...groupFacts, names: [entry.name] });
+    }
+    return toolAvailabilityInventory.parse({
+        client_requirements: clientRequirements,
+        groups: [...groups.values()],
+    });
 };
 const availabilityFor = (context) => {
     // These built-in workflows accept a caller-selected endpoint; they do not load the optional passive provider.
@@ -161,6 +209,8 @@ const optionalProviderFailureFor = ({ name, kind, policy, }) => {
         return failures?.electronObservation;
     if (kind === "runtime-provider")
         return failures?.javascriptRuntimeObservation;
+    if (FRIDA_OPERATION_NAMES.has(name))
+        return failures?.fridaInstrumentation;
     return undefined;
 };
 const javascriptApplicationAvailability = ({ name, }) => {
@@ -171,6 +221,19 @@ const javascriptApplicationAvailability = ({ name, }) => {
         : null;
 };
 const workflowAvailabilityFor = ({ name, kind, policy, }) => {
+    if (name === "inspect_go_binary" ||
+        name === "inspect_rust_binary" ||
+        name === "inspect_electron_fuses")
+        return { reason: "available", remediation: null };
+    if (name === "inspect_sqlite_database") {
+        const capability = sqliteDatabaseCapability(process.versions.node);
+        return capability.available
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_unavailable",
+                remediation: capability.reason,
+            };
+    }
     if (name === "trace_web_module_imports")
         return {
             reason: "available",
@@ -212,6 +275,27 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
                 reason: "provider_missing",
                 remediation: "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.",
             };
+    if (name === "inspect_packet_capture" || name === "inspect_packet_fields")
+        return policy.packetCaptureEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: "On Linux, supply TShark 4.x via absolute REA_TSHARK_COMMAND and util-linux prlimit (REA_TSHARK_PRLIMIT_COMMAND, default /usr/bin/prlimit). No active binary target or hardware is required; the tool is checked at execution.",
+            };
+    if (name === "decode_signal_recording" || name === "inspect_signal_decoders")
+        return policy.signalRecordingEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: "On Linux, supply sigrok-cli 0.7.2 via absolute REA_SIGROK_COMMAND and util-linux prlimit (REA_SIGROK_PRLIMIT_COMMAND, default /usr/bin/prlimit). No active binary target or hardware is required; the tool is checked at execution.",
+            };
+    if (name === "inspect_wasm_artifact")
+        return policy.wasmArtifactEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: "Supply WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY. No active binary target is required; tools are checked at execution.",
+            };
     if (name === "inspect_pe_resources")
         return { reason: "available", remediation: null };
     if (name === "inspect_evm_interface")
@@ -245,10 +329,17 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
             : {
                 reason: policy.androidAnalysisAvailability?.code === "unsupported_host"
                     ? "unsupported_host"
-                    : "provider_missing",
+                    : policy.androidAnalysisAvailability?.code ===
+                        "runtime_unavailable"
+                        ? "provider_unavailable"
+                        : "provider_missing",
                 remediation: policy.androidAnalysisAvailability?.reason ??
                     "Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide a full JDK on Linux, macOS, or Windows x64 with its matching bundled native controls.",
             };
+    if (kind === "adb-provider")
+        return ownerProbeAvailability(policy.adbAnalysisAvailability, "Set REA_ADB_PATH to a caller-supplied adb executable or make adb available on PATH. This checks the client version only; device and serial availability depend on the request.");
+    if (kind === "apktool-provider")
+        return ownerProbeAvailability(policy.apktoolAnalysisAvailability, "Set REA_APKTOOL_COMMAND to a caller-supplied Apktool executable or make Apktool 2.7.0 or newer available on PATH.");
     if (kind === "jeb-provider")
         return policy.jebAnalysisAvailability?.status === "available"
             ? { reason: "available", remediation: null }
@@ -267,6 +358,8 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
         };
     if (kind === "application")
         return { reason: "available", remediation: null };
+    if (kind === "pcap-provider" || kind === "flutter-provider")
+        return { reason: "available", remediation: null };
     const electron = electronProviderAvailability(name, kind, policy);
     if (electron !== null)
         return electron;
@@ -281,6 +374,20 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
         return { reason: "available", remediation: null };
     return null;
 };
+const ownerProbeAvailability = (observation, missingRemediation) => {
+    if (observation === undefined)
+        return { reason: "provider_missing", remediation: missingRemediation };
+    if (observation.status === "available")
+        return { reason: "available", remediation: null };
+    return {
+        reason: observation.code === "unsupported_host"
+            ? "unsupported_host"
+            : observation.code === "not_configured"
+                ? "provider_missing"
+                : "provider_unavailable",
+        remediation: observation.reason,
+    };
+};
 const electronProviderAvailability = (name, kind, policy) => {
     if (kind !== "electron-provider")
         return null;
@@ -330,6 +437,8 @@ const hostAvailability = ({ descriptors, kind, name, }) => {
         : null;
 };
 const targetAvailability = ({ name, kind, targetKind, targetFormat, targetOpen, }) => {
+    if (FRIDA_OPERATION_NAMES.has(name))
+        return null;
     if (!targetOpen && ACTIVE_TARGET_KINDS.has(kind))
         return {
             reason: "target_required",
@@ -345,7 +454,7 @@ const targetAvailability = ({ name, kind, targetKind, targetFormat, targetOpen,
         };
     if (targetOpen &&
         MACHO_TARGET_OPERATIONS.has(name) &&
-        (targetKind !== "executable" || targetFormat !== "mach-o"))
+        (targetKind !== "executable" || !isMachOFormat(targetFormat)))
         return {
             reason: "target_unsupported",
             remediation: "Call open_binary with a Mach-O executable or an app bundle whose main executable is Mach-O.",
@@ -383,22 +492,52 @@ const composedAvailability = (name, descriptors) => {
     return composedAvailabilityFor(requirements, descriptors);
 };
 const composedAvailabilityFor = (requirements, descriptors) => {
-    const missing = requirements.find((operation) => !descriptors.has(operation));
-    if (missing !== undefined)
-        return {
-            reason: "provider_missing",
-            remediation: `Configure a provider for required operation ${missing}.`,
-        };
-    const unavailable = requirements
-        .map((operation) => descriptors.get(operation))
-        .find((descriptor) => descriptor?.available === false);
-    if (unavailable !== undefined)
-        return {
-            reason: unavailable.availability_code === "unsupported_host"
-                ? "unsupported_host"
-                : "provider_unavailable",
-            remediation: unavailable.reason ?? "Choose another target or configured provider.",
-        };
+    for (const requirement of requirements) {
+        if (typeof requirement === "string") {
+            if (!descriptors.has(requirement))
+                return {
+                    reason: "provider_missing",
+                    remediation: `Configure a provider for required operation ${requirement}.`,
+                };
+        }
+        else {
+            const declared = requirement.some((operation) => descriptors.has(operation));
+            if (!declared)
+                return {
+                    reason: "provider_missing",
+                    remediation: `Configure a provider for one of: ${requirement.join(", ")}.`,
+                };
+        }
+    }
+    for (const requirement of requirements) {
+        if (typeof requirement === "string") {
+            const descriptor = descriptors.get(requirement);
+            if (descriptor?.available === false)
+                return {
+                    reason: descriptor.availability_code === "unsupported_host"
+                        ? "unsupported_host"
+                        : "provider_unavailable",
+                    remediation: descriptor.reason ??
+                        "Choose another target or configured provider.",
+                };
+        }
+        else {
+            const anyAvailable = requirement.some((operation) => descriptors.get(operation)?.available === true);
+            if (!anyAvailable) {
+                const unavailable = requirement
+                    .map((operation) => descriptors.get(operation))
+                    .find((descriptor) => descriptor?.available === false);
+                if (unavailable !== undefined)
+                    return {
+                        reason: unavailable.availability_code === "unsupported_host"
+                            ? "unsupported_host"
+                            : "provider_unavailable",
+                        remediation: unavailable.reason ??
+                            "Choose another target or configured provider.",
+                    };
+            }
+        }
+    }
     return { reason: "available", remediation: null };
 };
 const navigationContextAvailability = (descriptors) => {
@@ -447,13 +586,14 @@ const navigationContextAvailability = (descriptors) => {
     };
     if (availableMode !== undefined)
         return { ...facts, reason: "available", remediation: null };
+    const missingOperations = [
+        ...new Set(modes.flatMap((mode) => mode.missing_operations)),
+    ];
     return {
         ...facts,
         reason: failure?.reason ?? "provider_missing",
         remediation: specificFailureRemediation ??
-            `Configure a provider for one of: ${modes
-                .flatMap((mode) => mode.missing_operations)
-                .join(", ")}.`,
+            `Configure a provider for one of: ${missingOperations.join(", ")}.`,
     };
 };
 const navigationFailurePriority = (reason) => {

package/dist/application/ClaudeDesktopConfigLocation.js

@@ -0,0 +1,152 @@
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { err, ok } from "../domain/result.js";
+import { windowsAppDataRoots, } from "./MsixPackageStorage.js";
+const CONFIG_FILE = "claude_desktop_config.json";
+/** Private files compared at most when looking for a redirected AppData view. */
+const PROCESS_VIEW_PROBES = 8;
+/**
+ * Claude Desktop's MSIX package family: package name `Claude` and the
+ * publisher ID Windows derives from `CN="Anthropic, PBC", O="Anthropic, PBC",
+ * L=San Francisco, S=California, C=US, …`.
+ */
+export const CLAUDE_DESKTOP_PACKAGE_FAMILY = "Claude_pzs8sxrjxfjjc";
+/** `Claude_` plus a 13-character Crockford base32 MSIX publisher ID. */
+const CLAUDE_PACKAGE_FAMILY = /^Claude_[0-9a-hjkmnp-tv-z]{13}$/iu;
+const systemFileSystem = {
+    readdir: (path) => readdirSync(path),
+    lstat: (path) => lstatSync(path),
+    realpath: (path) => realpathSync.native(path),
+};
+/**
+ * Resolve the `claude_desktop_config.json` that Windows Claude Desktop reads.
+ * Without its MSIX package storage, that is the AppData file. With it, the
+ * package reads its private copy when one exists and the AppData file
+ * otherwise; a new registration goes to the private copy. A `Claude_*`
+ * package from another publisher leaves the reader unknown.
+ */
+export const resolveWindowsClaudeDesktopLocation = (home, env, fileSystem = systemFileSystem) => {
+    const roots = windowsAppDataRoots(home, env);
+    const appDataDirectory = join(roots.roaming, "Claude");
+    const appDataConfigPath = join(appDataDirectory, CONFIG_FILE);
+    const packagesDirectory = join(roots.local, "Packages");
+    let families;
+    try {
+        families = fileSystem
+            .readdir(packagesDirectory)
+            .filter((name) => CLAUDE_PACKAGE_FAMILY.test(name));
+    }
+    catch (cause) {
+        if (!isMissing(cause))
+            return err({
+                path: packagesDirectory,
+                message: `MSIX package storage ${packagesDirectory} could not be inspected, so REA cannot establish whether Claude Desktop reads ${appDataConfigPath} or a package-private copy: ${errorMessage(cause)}. Repair access to that directory, then rerun.`,
+            });
+        families = [];
+    }
+    const foreign = families.filter((name) => name.toLowerCase() !== CLAUDE_DESKTOP_PACKAGE_FAMILY.toLowerCase());
+    if (foreign.length > 0)
+        return err({
+            path: join(packagesDirectory, foreign[0] ?? ""),
+            message: `MSIX package storage ${foreign.map((name) => join(packagesDirectory, name)).join(", ")} uses Claude Desktop's package name with an unrecognized publisher (Claude Desktop is ${CLAUDE_DESKTOP_PACKAGE_FAMILY}). REA cannot establish which ${CONFIG_FILE} that package reads and does not fall back to ${appDataConfigPath}. Remove the unrecognized package, or register REA in the configuration it reads.`,
+        });
+    const family = families[0];
+    if (family === undefined)
+        return ok({ configPath: appDataConfigPath, markerPath: appDataDirectory });
+    const container = join(packagesDirectory, family);
+    const privateDirectory = join(container, "LocalCache", "Roaming", "Claude");
+    const privateConfigPath = join(privateDirectory, CONFIG_FILE);
+    const privateCopy = present(fileSystem, privateConfigPath);
+    if (!privateCopy.ok)
+        return privateCopy;
+    const appDataCopy = privateCopy.value
+        ? ok(false)
+        : present(fileSystem, appDataConfigPath);
+    if (!appDataCopy.ok)
+        return appDataCopy;
+    return ok({
+        configPath: privateCopy.value || !appDataCopy.value
+            ? privateConfigPath
+            : appDataConfigPath,
+        markerPath: container,
+        msixPackage: {
+            packageFamilyName: family,
+            privateConfigPath,
+            appDataConfigPath,
+            virtualizedRoots: [roots.roaming, roots.local],
+            processView: processView(fileSystem, privateDirectory, appDataDirectory, privateCopy.value),
+        },
+    });
+};
+/**
+ * A process the package started sees the package's private files at their
+ * AppData paths; any other process sees the real AppData files or nothing.
+ * Claude Desktop saves its user data there while it runs, so the
+ * configuration, or any other private file, can show which view this is.
+ */
+const processView = (fileSystem, privateDirectory, appDataDirectory, privateConfig) => {
+    let probes;
+    try {
+        probes = privateConfig
+            ? [CONFIG_FILE]
+            : fileSystem
+                .readdir(privateDirectory)
+                .filter((name) => {
+                try {
+                    return fileSystem.lstat(join(privateDirectory, name)).isFile();
+                }
+                catch (cause) {
+                    // A candidate may vanish or become unreadable while listed.
+                    void cause;
+                    return false;
+                }
+            })
+                .slice(0, PROCESS_VIEW_PROBES);
+    }
+    catch (cause) {
+        // No private file can be listed, so no view can be compared.
+        void cause;
+        return "unknown";
+    }
+    let view = "unknown";
+    for (const name of probes) {
+        let privateTarget;
+        try {
+            privateTarget = fileSystem.realpath(join(privateDirectory, name));
+        }
+        catch (cause) {
+            // A private file that vanished cannot be compared; try another.
+            void cause;
+            continue;
+        }
+        try {
+            if (fileSystem.realpath(join(appDataDirectory, name)) === privateTarget)
+                return "redirected";
+            view = "direct";
+        }
+        catch (cause) {
+            if (!isMissing(cause))
+                return "unknown";
+            view = "direct";
+        }
+    }
+    return view;
+};
+const present = (fileSystem, path) => {
+    try {
+        fileSystem.lstat(path);
+        return ok(true);
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return ok(false);
+        return err({
+            path,
+            message: `${path} could not be inspected, so REA cannot establish which ${CONFIG_FILE} Claude Desktop's MSIX package reads: ${errorMessage(cause)}. Repair access to that path, then rerun.`,
+        });
+    }
+};
+const isMissing = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    (cause.code === "ENOENT" || cause.code === "ENOTDIR");
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);