rea-agents 6.2.0 → 6.4.0

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -1,6 +1,7 @@
 import { hasWindowsNativeAuthority, windowsNativeAuthorityUnavailableReason, } from "../process/WindowsAuthority.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
+import { GHIDRA_MUTATING_OPERATIONS } from "./GhidraSessionValues.js";
 /** Public identity committed by every Ghidra-backed observation. */
 export const GHIDRA_PROVIDER_IDENTITY = Object.freeze({
     id: "ghidra",
@@ -20,10 +21,12 @@ export const healthLimitations = Object.freeze([
 ]);
 /** Additional limitations applied to the experimental Windows x64 P0 boundary. */
 export const windowsP0Limitations = Object.freeze([
-    "Windows Ghidra P0 accepts approved native x86 and x86-64 PE applications only; DLL, managed, hostile, sensitive, and mutable-path targets are unsupported.",
+    "Windows Ghidra P0 accepts approved native x86 and x86-64 PE applications and DLLs; managed, hostile, sensitive, and mutable-path targets are unsupported.",
     "The Windows bridge uses authenticated IPv4 loopback because Node path-based IPC does not expose Java AF_UNIX sockets; the endpoint file contains no bearer token.",
     "Windows sessions require the matching packaged Windows x64 native addon, local NTFS targets and runtimes, and Windows 10 or later. Native handles enforce path admission, private DACLs, and Job Object ownership automatically.",
 ]);
+const stringInventoryLimitation = "Only Ghidra-defined string Data is observed; packed or undefined string bytes may be absent. Completeness applies to that inventory, and an empty search does not establish that text is absent from the artifact. If an address is known, use read_bytes and xrefs to inspect bytes and references.";
+const searchLimitation = "Regex mode uses Java Pattern semantics. Matcher or compiler stack exhaustion returns a resource constraint without closing the session; literal mode avoids regex recursion and returns complete matching values.";
 /** Limitation text for one admitted operation, including the common base. */
 export const limitationsFor = (operation) => {
     const common = [
@@ -38,6 +41,14 @@ export const limitationsFor = (operation) => {
                 "Annotation text rejects NUL and unpaired Unicode surrogates before mutation, with the field and UTF-16 index in the error. Supported Unicode and line endings are preserved.",
                 "Metadata edits invalidate immutable analysis snapshots and are discarded on close. CLI returns the updated dossier before session cleanup; this is not a saved Ghidra project.",
             ];
+        case "set_address_name":
+        case "set_addresses_names":
+            return [
+                ...common,
+                "Names use Ghidra USER_DEFINED source. A local function entry renames that function; any other mapped address receives a new or renamed primary label. Existing symbols retain their namespace and accept leaf names or qualified names within that namespace; qualified readback can be reused without adding namespace prefixes. Readback compares the primary symbol name.",
+                "set_addresses_names applies each address in its own transaction and reports per-address success; invalid names, unmapped addresses, and readback mismatches roll back only that address.",
+                "Metadata edits invalidate immutable analysis snapshots and are discarded on close; this is not a saved Ghidra project.",
+            ];
         case "inspect_native_load_image":
             return [
                 ...common,
@@ -72,7 +83,8 @@ export const limitationsFor = (operation) => {
         case "list_strings":
             return [
                 ...common,
-                "Only Ghidra-defined string Data is observed; charset is reported, while a non-missing terminator cannot distinguish a present terminator from a fixed or Pascal layout.",
+                stringInventoryLimitation,
+                "Charset is reported, while a non-missing terminator cannot distinguish a present terminator from a fixed or Pascal layout.",
             ];
         case "resolve_containing_procedure":
             return [
@@ -85,11 +97,9 @@ export const limitationsFor = (operation) => {
                 "Memory-block end addresses are exclusive; permissions come from Ghidra MemoryBlock flags rather than inference from section names.",
             ];
         case "search_procedures":
+            return [...common, searchLimitation];
         case "search_strings":
-            return [
-                ...common,
-                "Regex mode uses Java Pattern semantics. Matcher or compiler stack exhaustion returns a resource constraint without closing the session; literal mode avoids regex recursion and returns complete matching values.",
-            ];
+            return [...common, stringInventoryLimitation, searchLimitation];
         case "procedure_pseudo_code":
             return [
                 ...common,
@@ -148,12 +158,12 @@ export const CAPABILITIES = Object.freeze(GHIDRA_OPERATIONS.map((operation) => {
         reason: null,
         // Project writes are private import machinery. Analysis reads are bound
         // to the artifact/profile; session annotations disable snapshot replay.
-        ...(operation === "annotate_native_function" ||
+        ...(GHIDRA_MUTATING_OPERATIONS.has(operation) ||
             operation === "list_documents"
             ? {}
             : { cachePolicy: "snapshot" }),
         effects: Object.freeze({
-            mutatesArtifact: operation === "annotate_native_function",
+            mutatesArtifact: GHIDRA_MUTATING_OPERATIONS.has(operation),
             launchesProcess: true,
             mayShowUi: false,
             mayAccessNetwork: false,

package/dist/ghidra/GhidraProviderClient.js

@@ -1,8 +1,11 @@
-import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { fileURLToPath } from "node:url";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { ghidraSeedCommitmentSchema, ghidraSeedFailure, ghidraSeedLimitations, } from "./GhidraAnalysisSeeds.js";
+import { ghidraProfileLanguageOverride, sameGhidraLanguageOverride, } from "./GhidraAnalysisProfile.js";
 import { AnalysisCancelledError, AnalysisArtifactChangedError, AnalysisAccessDeniedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { GhidraClient } from "./GhidraClient.js";
@@ -12,10 +15,159 @@ import { ghidraInstallationDiagnostics, } from "./GhidraInstallation.js";
 import { unverifiedGhidraBuildLimitation } from "./GhidraInstallationPolicy.js";
 import { GhidraHeadlessLauncher } from "./GhidraLauncher.js";
 import { attestGhidraNativeLoadImage } from "./GhidraLoadImageAttest.js";
+import { NATIVE_AOT_MAX_REPORT_BYTES, NATIVE_AOT_MAX_SOURCE_BYTES, nativeAotSnapshotOverCapacity, parseNativeAotPe, } from "../domain/native/nativeAotPe.js";
+import { ABORTED, waitForAbortable, } from "../application/binary/AbortablePromise.js";
+import { nativeLoadImageObservationSchema } from "../domain/native/nativeLoadImage.js";
 import { GHIDRA_PROVIDER_IDENTITY, healthLimitations, windowsP0Limitations, limitationsFor, } from "./GhidraProviderCapabilities.js";
 import { ghidraExtensionFailure } from "./extensions/GhidraExtensionFailures.js";
 import { ghidraExtensionSchema, validateGhidraExtensionProfile, ghidraExtensionLimitations, } from "./extensions/GhidraExtensions.js";
 import { windowsNativeAuthorityUnavailableReason, hasWindowsNativeAuthority, } from "../process/WindowsAuthority.js";
+/** Own one session's captured PE snapshot and immutable NativeAOT derivation. */
+const createNativeAotSnapshotOwner = (input) => {
+    const { client, target, startupTimeoutMs } = input;
+    const controller = new AbortController();
+    let identity;
+    let result;
+    let pending;
+    let closed = false;
+    let identityConflict = false;
+    let identityConflictObservation;
+    const identityError = (operation, reason, observedBase, observations) => new ProviderAdapterError("ghidra", operation, {
+        diagnostics: {
+            reason,
+            artifact_sha256: target.sha256,
+            bound_image_base: identity === undefined
+                ? null
+                : `0x${identity.slice(target.sha256.length + 1)}`,
+            observed_image_base: observedBase,
+            measured_observation: observations,
+            conflicting_image_base: identityConflictObservation?.imageBase ?? null,
+            conflicting_observation: identityConflictObservation?.observations ?? null,
+        },
+    });
+    const identityConflictFailure = (operation, observedBase, observations) => {
+        return err(identityError(operation, "The Ghidra session reported conflicting loaded image bases; reopen the analysis session to establish a new identity.", observedBase, observations));
+    };
+    const derive = async (imageBase, operation, callerSignal, observations) => {
+        if (callerSignal?.aborted || closed)
+            return err(new AnalysisCancelledError(operation));
+        if (identityConflict)
+            return identityConflictFailure(operation, imageBase, observations);
+        if (controller.signal.aborted)
+            return err(new AnalysisCancelledError(operation));
+        let normalizedBase;
+        try {
+            normalizedBase = BigInt(imageBase).toString(16);
+        }
+        catch (cause) {
+            return err(new ProviderAdapterError("ghidra", operation, {
+                diagnostics: {
+                    reason: "Ghidra returned an invalid loaded image base for NativeAOT identity binding.",
+                    artifact_sha256: target.sha256,
+                    observed_image_base: imageBase,
+                    measured_observation: observations,
+                },
+                cause,
+            }));
+        }
+        const key = `${target.sha256}:${normalizedBase}`;
+        if (identity !== undefined && identity !== key) {
+            identityConflict = true;
+            identityConflictObservation = { imageBase, observations };
+            result = undefined;
+            controller.abort();
+            return err(identityError(operation, "The Ghidra session reported a different loaded image base after NativeAOT metadata was bound to its captured snapshot; reopen the analysis session to establish a new identity.", imageBase, observations));
+        }
+        identity ??= key;
+        if (result !== undefined) {
+            const settled = await waitForAbortable(Promise.resolve(ok(result)), callerSignal);
+            if (closed)
+                return err(new AnalysisCancelledError(operation));
+            if (identityConflict)
+                return identityConflictFailure(operation, imageBase, observations);
+            if (controller.signal.aborted)
+                return err(new AnalysisCancelledError(operation));
+            return settled === ABORTED
+                ? err(new AnalysisCancelledError(operation))
+                : settled;
+        }
+        if (pending !== undefined && pending.identity !== key)
+            return err(identityError(operation, "A NativeAOT snapshot derivation is already bound to a different loaded image base.", imageBase, observations));
+        if (pending === undefined) {
+            const promise = (async () => {
+                try {
+                    if (client.readTargetSnapshot === undefined)
+                        return err(new ProviderAdapterError("ghidra", operation, {
+                            diagnostics: {
+                                reason: "The Ghidra client does not expose its immutable target snapshot for NativeAOT metadata inspection.",
+                            },
+                        }));
+                    const snapshot = await client.readTargetSnapshot(NATIVE_AOT_MAX_SOURCE_BYTES, controller.signal);
+                    if (!snapshot.ok)
+                        return err(projectSessionError(operation, snapshot.error, startupTimeoutMs));
+                    if (closed)
+                        return err(new AnalysisCancelledError(operation));
+                    if (identityConflict)
+                        return identityConflictFailure(operation, imageBase, observations);
+                    if (controller.signal.aborted)
+                        return err(new AnalysisCancelledError(operation));
+                    const parsed = snapshot.value.kind === "over-capacity"
+                        ? {
+                            summary: nativeAotSnapshotOverCapacity(target.sha256, snapshot.value.sourceBytesAtLeast, NATIVE_AOT_MAX_REPORT_BYTES),
+                            readTypeDetail: () => undefined,
+                        }
+                        : parseNativeAotPe(snapshot.value.bytes, target.sha256, NATIVE_AOT_MAX_REPORT_BYTES, imageBase);
+                    if (closed)
+                        return err(new AnalysisCancelledError(operation));
+                    if (identityConflict)
+                        return identityConflictFailure(operation, imageBase, observations);
+                    if (controller.signal.aborted)
+                        return err(new AnalysisCancelledError(operation));
+                    return ok(parsed);
+                }
+                catch (cause) {
+                    return err(new ProviderAdapterError("ghidra", operation, {
+                        diagnostics: {
+                            reason: cause instanceof Error
+                                ? cause.message
+                                : "NativeAOT metadata could not be derived from the captured target snapshot.",
+                        },
+                        cause,
+                    }));
+                }
+            })();
+            const current = { identity: key, promise };
+            pending = current;
+            void promise.then((settled) => {
+                if (pending !== current)
+                    return;
+                pending = undefined;
+                if (settled.ok && !closed && !identityConflict)
+                    result = settled.value;
+            });
+        }
+        const settled = await waitForAbortable(pending.promise, callerSignal);
+        if (closed)
+            return err(new AnalysisCancelledError(operation));
+        if (identityConflict)
+            return identityConflictFailure(operation, imageBase, observations);
+        if (controller.signal.aborted)
+            return err(new AnalysisCancelledError(operation));
+        return settled === ABORTED
+            ? err(new AnalysisCancelledError(operation))
+            : settled;
+    };
+    return {
+        derive,
+        readTypeDetail: (address) => result?.readTypeDetail(address, NATIVE_AOT_MAX_REPORT_BYTES),
+        close: () => {
+            closed = true;
+            controller.abort();
+            result = undefined;
+            pending = undefined;
+        },
+    };
+};
 /** Build one AnalysisClient for an admitted Ghidra target and profile. */
 export const createGhidraProviderClient = (input) => {
     const { config, logger, clientFactory, target, context, installation } = input;
@@ -35,18 +187,43 @@ export const createGhidraProviderClient = (input) => {
             },
         }));
     const extensions = extensionProfile.data;
+    const seedProfile = ghidraSeedCommitmentSchema
+        .optional()
+        .safeParse(committedProfile.parameters.analysis_seeds);
+    if (!seedProfile.success ||
+        (config.ghidraSeedFile === undefined) !== (seedProfile.data === undefined))
+        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+            diagnostics: {
+                reason: "Resolve REA_GHIDRA_SEED_FILE into an analysis profile before opening the session.",
+            },
+        }));
+    const seeds = seedProfile.data;
+    const languageOverride = ghidraProfileLanguageOverride(committedProfile.parameters);
+    if (!sameGhidraLanguageOverride(languageOverride, config.ghidraLanguageOverride))
+        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+            diagnostics: {
+                reason: "The committed analysis profile and REA_GHIDRA_LANGUAGE_ID/REA_GHIDRA_COMPILER_SPEC_ID differ; reopen the target to resolve a new profile.",
+            },
+        }));
     const invalidProfile = validateGhidraExtensionProfile(extensions, config, target, installation.platform);
     if (invalidProfile !== null)
         return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: { reason: invalidProfile },
         }));
     let extensionFailure;
-    const targetLimitations = target.format === "dos-mz"
-        ? [
-            "DOS MZ uses 16-bit x86 real mode with the Ghidra load segment 0x1000. Returned addresses are linear byte coordinates; they do not identify a unique segment:offset alias.",
-            "Static DOS analysis does not emulate BIOS, DOS interrupts, device ports, or self-modifying unpacking code. Packed targets require a separately identified unpacked artifact for original-program analysis; appended overlays are not the initialized load module.",
-        ]
-        : [];
+    // Replaced by the reported outcome once the session handshake is checked.
+    const seedLimitations = [...ghidraSeedLimitations(seeds)];
+    const targetLimitations = [
+        ...(target.format === "dos-mz"
+            ? [
+                "DOS MZ uses 16-bit x86 real mode with the Ghidra load segment 0x1000. Returned addresses are linear byte coordinates; they do not identify a unique segment:offset alias.",
+                "Static DOS analysis does not emulate BIOS, DOS interrupts, device ports, or self-modifying unpacking code. Packed targets require a separately identified unpacked artifact for original-program analysis; appended overlays are not the initialized load module.",
+            ]
+            : []),
+        ...(target.kind === "executable" && target.architecture === "mips"
+            ? (target.mips.limitations ?? [])
+            : []),
+    ];
     const providerLimitations = installation.platform === "win32"
         ? windowsP0Limitations
         : installation.platform === "darwin"
@@ -64,6 +241,8 @@ export const createGhidraProviderClient = (input) => {
             bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
             ...(target.format === "dos-mz" ? { dosMz: true } : {}),
             ...(target.format === "dos-com" ? { dosCom: true } : {}),
+            ...(languageOverride === undefined ? {} : { languageOverride }),
+            ...(seeds === undefined ? {} : { analysisSeeds: seeds }),
             platform: installation.platform,
             ...(extensions.length === 0 ? {} : { analysisExtensions: extensions }),
         }),
@@ -81,12 +260,22 @@ export const createGhidraProviderClient = (input) => {
                 expectedLanguageId: "x86:LE:16:Real Mode",
                 expectedCompilerSpecId: "default",
             }
-            : {}),
+            : languageOverride === undefined
+                ? {}
+                : {
+                    expectedLanguageId: languageOverride.languageId,
+                    ...(languageOverride.compilerSpecId === undefined
+                        ? {}
+                        : { expectedCompilerSpecId: languageOverride.compilerSpecId }),
+                }),
         ...(context === undefined ? {} : { runId: context.runId }),
         logger: logger.child({ layer: "ghidra-bridge" }),
     });
     const checkExtensions = async (operation, info) => {
-        extensionFailure = ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation);
+        extensionFailure =
+            ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation) ?? ghidraSeedFailure(seeds, info.analysis_seeds, operation);
+        if (extensionFailure === undefined && info.analysis_seeds !== undefined)
+            seedLimitations.splice(0, seedLimitations.length, ...ghidraSeedLimitations(seeds, info.analysis_seeds));
         if (extensionFailure === undefined)
             return undefined;
         const closed = await client.close();
@@ -95,12 +284,20 @@ export const createGhidraProviderClient = (input) => {
             : analysisErrorWithCleanupFailure(extensionFailure, closed.error, operation);
     };
     const releaseLimitation = unverifiedGhidraBuildLimitation(prerequisites.value.providerVersion);
-    const sessionLimitations = [
+    const sessionLimitations = () => [
         ...providerLimitations,
         ...targetLimitations,
         ...ghidraExtensionLimitations(extensions),
+        ...seedLimitations,
         ...(releaseLimitation === undefined ? [] : [releaseLimitation]),
     ];
+    const nativeAotOwner = target.format === "pe"
+        ? createNativeAotSnapshotOwner({
+            client,
+            target,
+            startupTimeoutMs: config.ghidraStartupTimeoutMs,
+        })
+        : undefined;
     return {
         execute: async (operation, parameters, options) => {
             if (extensionFailure !== undefined)
@@ -118,7 +315,7 @@ export const createGhidraProviderClient = (input) => {
                     return err(failed);
                 return ok(createAnalysisExecution(started.value, committedProfile.provider, {
                     analysisProfile: committedProfile,
-                    limitations: [...healthLimitations, ...sessionLimitations],
+                    limitations: [...healthLimitations, ...sessionLimitations()],
                 }));
             }
             const input = isGhidraFunctionOperation(operation)
@@ -126,7 +323,7 @@ export const createGhidraProviderClient = (input) => {
                 : parseGhidraInventoryInput(operation, parameters);
             if (!input.ok)
                 return input;
-            if (extensions.length > 0) {
+            if (extensions.length > 0 || seeds !== undefined) {
                 const started = await client.start(options?.signal);
                 if (!started.ok)
                     return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
@@ -137,14 +334,71 @@ export const createGhidraProviderClient = (input) => {
             const called = await client.callTool(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
             if (!called.ok)
                 return err(projectSessionError(operation, called.error, config.ghidraStartupTimeoutMs));
-            const result = isGhidraFunctionOperation(operation)
-                ? parseGhidraFunctionResult(operation, called.value)
-                : parseGhidraInventoryResult(operation, called.value);
-            if (!result.ok)
-                return result;
-            let normalized = result.value;
+            let normalized;
+            let observationLimitations = [];
+            if (isGhidraFunctionOperation(operation)) {
+                const result = parseGhidraFunctionResult(operation, called.value);
+                if (!result.ok)
+                    return result;
+                normalized = result.value.value;
+                observationLimitations = result.value.limitations;
+            }
+            else {
+                const result = parseGhidraInventoryResult(operation, called.value);
+                if (!result.ok)
+                    return result;
+                normalized = result.value;
+            }
+            if (operation === "inspect_native_data_type") {
+                const address = input.value.address;
+                if (typeof address === "string") {
+                    if (target.format === "pe" && nativeAotOwner !== undefined) {
+                        const started = await client.start(options?.signal);
+                        if (!started.ok)
+                            return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
+                        const derived = await nativeAotOwner.derive(started.value.target.image_base, operation, options?.signal, normalized);
+                        if (!derived.ok)
+                            return derived;
+                    }
+                    let metadata;
+                    metadata = nativeAotOwner?.readTypeDetail(address);
+                    if (metadata !== undefined &&
+                        normalized !== null &&
+                        typeof normalized === "object" &&
+                        !Array.isArray(normalized)) {
+                        const nativeResult = normalized;
+                        if (nativeResult.metadata_recovery === undefined)
+                            normalized = jsonValueSchema.parse({
+                                ...nativeResult,
+                                metadata_recovery: metadata,
+                            });
+                    }
+                }
+            }
             if (operation === "inspect_native_load_image") {
-                const attested = await attestGhidraNativeLoadImage(target, operation, result.value, client, (failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs));
+                let derived;
+                if (target.format === "pe") {
+                    const observations = nativeLoadImageObservationSchema.parse(normalized);
+                    if (nativeAotOwner === undefined)
+                        return err(new ProviderAdapterError("ghidra", operation, {
+                            diagnostics: {
+                                reason: "The admitted PE session has no read-only NativeAOT snapshot owner.",
+                            },
+                        }));
+                    const result = await nativeAotOwner.derive(observations.image_base, operation, options?.signal, normalized);
+                    if (!result.ok)
+                        return result;
+                    derived = result.value;
+                }
+                const attested = await attestGhidraNativeLoadImage({
+                    target,
+                    operation,
+                    measured: normalized,
+                    client,
+                    mapSessionError: (failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs),
+                    nativeAotResult: derived,
+                    signal: options?.signal,
+                });
                 if (!attested.ok)
                     return attested;
                 normalized = attested.value;
@@ -152,7 +406,11 @@ export const createGhidraProviderClient = (input) => {
             return ok(createAnalysisExecution(normalized, committedProfile.provider, {
                 rawResult: called.value,
                 analysisProfile: committedProfile,
-                limitations: [...limitationsFor(operation), ...sessionLimitations],
+                limitations: [
+                    ...limitationsFor(operation),
+                    ...observationLimitations,
+                    ...sessionLimitations(),
+                ],
             }));
         },
         runtimeLineageSnapshots: () => {
@@ -161,7 +419,10 @@ export const createGhidraProviderClient = (input) => {
                 ? []
                 : [{ provider: committedProfile.provider, observation }];
         },
-        close: () => client.close(),
+        close: async () => {
+            nativeAotOwner?.close();
+            return client.close();
+        },
     };
 };
 const ghidraClientPrerequisites = (target, profile, installation) => {

package/dist/ghidra/GhidraSessionValues.js

@@ -1,6 +1,7 @@
+import { ghidraSeedReportSchema } from "./GhidraAnalysisSeeds.js";
 import { z } from "zod";
 import { err, ok } from "../domain/result.js";
-import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
+import { GHIDRA_INVENTORY_OPERATIONS, GHIDRA_NAMING_OPERATIONS, } from "./GhidraInventoryValues.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 import { ghidraExtensionResultSchema } from "./extensions/GhidraExtensions.js";
 /** Exact methods proved by the bridge handshake after auto-analysis. */
@@ -10,6 +11,11 @@ export const GHIDRA_SESSION_CAPABILITIES = [
     ...GHIDRA_INVENTORY_OPERATIONS,
     ...GHIDRA_FUNCTION_OPERATIONS,
 ];
+/** Methods that edit the session database; read-only bridges omit them. */
+export const GHIDRA_MUTATING_OPERATIONS = new Set([
+    "annotate_native_function",
+    ...GHIDRA_NAMING_OPERATIONS,
+]);
 const capabilitySchema = z.enum(GHIDRA_SESSION_CAPABILITIES);
 const sessionInfoSchema = z
     .object({
@@ -26,6 +32,7 @@ const sessionInfoSchema = z
     analysis_complete: z.boolean(),
     analysis_timed_out: z.boolean(),
     analysis_extensions: z.array(ghidraExtensionResultSchema).optional(),
+    analysis_seeds: ghidraSeedReportSchema.optional(),
     capabilities: z.array(capabilitySchema),
     target: z
         .object({
@@ -43,7 +50,7 @@ const sessionInfoSchema = z
 export const parseGhidraSessionInfo = (value, expected) => {
     const parsed = sessionInfoSchema.safeParse(value);
     const readOnly = expected.expectedReadOnly ?? false;
-    const expectedCapabilities = GHIDRA_SESSION_CAPABILITIES.filter((capability) => !readOnly || capability !== "annotate_native_function");
+    const expectedCapabilities = GHIDRA_SESSION_CAPABILITIES.filter((capability) => !readOnly || !GHIDRA_MUTATING_OPERATIONS.has(capability));
     if (!parsed.success ||
         parsed.data.run_id !== expected.runId ||
         parsed.data.read_only !== readOnly ||

package/dist/hopper/HopperAnalysisProfile.js

@@ -77,6 +77,8 @@ export const hopperLoaderArgsForTarget = (target, machoContainer) => {
     if (target.kind !== "executable")
         return err(new ProviderAdapterError("hopper", "resolve_analysis_profile"));
     const architecture = target.architecture;
+    if (architecture === "mips")
+        return err(new AnalysisCapabilityUnavailableError("hopper", "resolve_analysis_profile", "REA's Hopper adapter does not admit MIPS targets. Select a verified Ghidra MIPS profile instead."));
     const flag = hopperArchitectureFlag(architecture);
     switch (target.format) {
         case "mach-o":

package/dist/hopper/HopperCleanup.js

@@ -160,7 +160,7 @@ const stopProcess = async (input, state) => {
     }
     input.logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
     if (stopped.status !== "incomplete") {
-        if (input.resources.launch?.shutdownMode === "process-cleanup" &&
+        if (input.resources.launch?.providerLifetime === "launcher-process" &&
             stopped.status !== "not-owned")
             input.resources.shutdownConfirmed = true;
         state.processStopped = true;

package/dist/hopper/HopperClient.js

@@ -3,7 +3,7 @@ import { access } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
-import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperStartError, HopperTimeoutError, } from "../domain/hopperErrors.js";
 import {} from "../domain/analysisErrorBase.js";
@@ -13,6 +13,7 @@ import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { redactCapturedTransportCredential } from "../process/ProviderDiagnosticRedaction.js";
 import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { hopperOperationStage } from "./HopperOperationStage.js";
@@ -23,6 +24,8 @@ import { hopperLauncherFailureDiagnostic } from "./HopperProcessDiagnostic.js";
 import { HopperRequestQueue, } from "./HopperRequestQueue.js";
 import { HopperResponseStream } from "./HopperResponseStream.js";
 import { responseResult, } from "./protocol.js";
+/** Aggregate in-memory retention budget for this provider's launcher output. */
+export const HOPPER_PROCESS_DIAGNOSTIC_BYTES = 8 * 1024 * 1024;
 const SHUTDOWN_TIMEOUT_MS = 30_000;
 const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
 /**
@@ -434,14 +437,19 @@ export class HopperClient {
         const token = this.#token;
         if (snapshot === undefined)
             return undefined;
-        const redact = (text) => token === undefined
-            ? text
-            : text.replaceAll(token, "[redacted transport credential]");
         return {
             exit_code: snapshot.exitCode ?? null,
             signal: snapshot.signal ?? null,
-            stdout: { ...snapshot.stdout, text: redact(snapshot.stdout.text) },
-            stderr: { ...snapshot.stderr, text: redact(snapshot.stderr.text) },
+            stdout: {
+                text: redactCapturedTransportCredential(snapshot.stdout, token, "[redacted transport credential]"),
+                bytes: snapshot.stdout.observedBytes,
+                retained_bytes: snapshot.stdout.bytes,
+            },
+            stderr: {
+                text: redactCapturedTransportCredential(snapshot.stderr, token, "[redacted transport credential]"),
+                bytes: snapshot.stderr.observedBytes,
+                retained_bytes: snapshot.stderr.bytes,
+            },
             output_closed: outputClosed,
             diagnostic_truncated: snapshot.diagnosticTruncated === true,
         };
@@ -524,6 +532,7 @@ export class HopperClient {
     }
     #attachLauncher(launch) {
         this.#resources.processSupervisor = new ProviderProcessSupervisor(launch, {
+            maxDiagnosticBytes: HOPPER_PROCESS_DIAGNOSTIC_BYTES,
             onDiagnostic: (event) => this.#onLauncherDiagnostic(launch, event),
         });
     }

package/dist/hopper/HopperMachOImage.js

@@ -21,6 +21,8 @@ export const resolveHopperMachOImage = async (target, signal) => {
     const invalid = (reason, cause) => err(new BinaryTargetError(target.path, reason, cause === undefined ? undefined : { cause }));
     if (signal?.aborted)
         return err(new AnalysisCancelledError("open_binary"));
+    if (target.format !== "mach-o")
+        return invalid("Hopper FAT64 image preparation requires a Mach-O target");
     let file;
     try {
         file = await open(target.path, "r");

package/dist/hopper/HopperProvider.js

@@ -1,6 +1,6 @@
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { fileURLToPath } from "node:url";
-import { accessSync, constants } from "node:fs";
+import { accessSync, constants, statSync } from "node:fs";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
@@ -49,6 +49,9 @@ export class HopperProvider {
             };
         try {
             accessSync(this.config.hopperLauncherPath, constants.X_OK);
+            // A searchable directory, such as an .app bundle, also passes X_OK.
+            if (!statSync(this.config.hopperLauncherPath).isFile())
+                throw new TypeError("Hopper launcher is not a regular file");
             return {
                 status: "available",
                 code: null,
@@ -87,6 +90,13 @@ export class HopperProvider {
                 reason: null,
                 diagnostics,
             };
+        if (target.architecture === "mips")
+            return {
+                status: "unsupported",
+                code: "architecture_unsupported",
+                reason: "REA's Hopper adapter does not admit MIPS targets.",
+                diagnostics,
+            };
         if (target.format === "dos-mz" || target.format === "dos-com")
             return {
                 status: "unsupported",
@@ -183,7 +193,8 @@ export class HopperProvider {
                     ? {
                         ok: true,
                         value: createAnalysisExecution(mapped.value, executionProvider, {
-                            rawResult: result.value,
+                            // Only the file-offset mapping differs from Hopper's reply.
+                            rawResult: mapped === result ? null : result.value,
                             ...(profile === undefined ? {} : { analysisProfile: profile }),
                             limitations: [
                                 ...(preparedImage === undefined