rea-agents 4.0.1 → 5.0.0

package/dist/ghidra/GhidraProvider.js

@@ -1,20 +1,17 @@
-import { fileURLToPath } from "node:url";
-import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, ProviderAdapterError, } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
+import {} from "../application/AnalysisProvider.js";
+import { createAnalysisProfile, } from "../domain/analysisProfile.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
+import { ok } from "../domain/result.js";
 import { GhidraClient } from "./GhidraClient.js";
-import { GHIDRA_STARTUP_TIMEOUT_MS } from "./GhidraDefaults.js";
-import { isGhidraFunctionOperation, parseGhidraFunctionInput, parseGhidraFunctionResult, } from "./GhidraFunctionValues.js";
-import { isGhidraInventoryOperation, parseGhidraInventoryInput, parseGhidraInventoryResult, } from "./GhidraInventoryValues.js";
 import { ghidraInstallationDiagnostics, inspectGhidraInstallation, } from "./GhidraInstallation.js";
-import { GhidraHeadlessLauncher } from "./GhidraLauncher.js";
 import { resolveGhidraAnalysisProfile } from "./GhidraAnalysisProfile.js";
-import { CAPABILITIES, WINDOWS_P0_CAPABILITIES, GHIDRA_PROVIDER_IDENTITY, GHIDRA_PROVIDER_TOOL_CONTRACTS, healthLimitations, windowsP0Limitations, limitationsFor, } from "./GhidraProviderCapabilities.js";
-import { WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON, hasWindowsNativeAuthority, windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
-export { GHIDRA_PROVIDER_IDENTITY, GHIDRA_PROVIDER_TOOL_CONTRACTS };
+import { resolveGhidraExtensions } from "./extensions/GhidraExtensions.js";
+import { CAPABILITIES, windowsP0Capabilities, GHIDRA_PROVIDER_IDENTITY, GHIDRA_OPERATIONS, } from "./GhidraProviderCapabilities.js";
+import { createGhidraProviderClient, } from "./GhidraProviderClient.js";
+import { windowsNativeAuthorityUnavailableReason, hasWindowsNativeAuthority, windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
+export { GHIDRA_PROVIDER_IDENTITY, GHIDRA_OPERATIONS };
 const SUPPORTED_ARCHITECTURES = new Set(["x86", "x86_64", "arm", "arm64"]);
-/** Ghidra candidate backed by an isolated read-only headless import. */
+/** Ghidra candidate backed by an isolated ephemeral headless import. */
 export class GhidraProvider {
     config;
     logger;
@@ -32,7 +29,7 @@ export class GhidraProvider {
     }
     capabilities() {
         return (this.installationHost?.platform ?? process.platform) === "win32"
-            ? WINDOWS_P0_CAPABILITIES
+            ? windowsP0Capabilities()
             : CAPABILITIES;
     }
     inspectAvailability() {
@@ -44,7 +41,7 @@ export class GhidraProvider {
             return {
                 status: "unavailable",
                 code: "unsupported_host",
-                reason: WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON,
+                reason: windowsNativeAuthorityUnavailableReason(installation.platform),
                 diagnostics: {
                     ...diagnostics,
                     windows_security: jsonObjectSchema.parse(windowsNativeCapabilities(installation.platform)),
@@ -71,6 +68,9 @@ export class GhidraProvider {
             target_kind: target.kind,
             target_format: target.format,
             architecture: target.architecture ?? null,
+            available_architectures: target.kind === "executable"
+                ? [...target.availableArchitectures]
+                : null,
             executable_role: target.executableRole ?? null,
             managed: target.managed ?? null,
         };
@@ -83,6 +83,13 @@ export class GhidraProvider {
             };
         if (hostPlatform === "win32")
             return inspectWindowsP0TargetSupport(target, diagnostics);
+        if (target.format === "mach-o" && target.availableArchitectures.length > 1)
+            return {
+                status: "unsupported",
+                code: "architecture_unsupported",
+                reason: "Ghidra v1 cannot enforce the selected architecture when importing a universal Mach-O; analyze a thinned Mach-O slice instead.",
+                diagnostics,
+            };
         if (!SUPPORTED_ARCHITECTURES.has(target.architecture))
             return {
                 status: "unsupported",
@@ -97,104 +104,34 @@ export class GhidraProvider {
             diagnostics,
         };
     }
-    resolveAnalysisProfile(target, options) {
-        return resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, this.#inspectInstallation(), options?.signal);
-    }
-    createClient(target, profile, context) {
+    async resolveAnalysisProfile(target, options) {
         const installation = this.#inspectInstallation();
-        const prerequisites = ghidraClientPrerequisites(target, profile, installation);
-        if (!prerequisites.ok)
-            return unavailableClient(prerequisites.error);
-        const committedProfile = prerequisites.value.profile;
-        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.",
-            ]
-            : [];
-        const providerLimitations = installation.platform === "win32"
-            ? windowsP0Limitations
-            : installation.platform === "darwin"
-                ? [
-                    "macOS sessions require a matching executable Ghidra native decompiler; REA checks for it but does not build native components or change Gatekeeper quarantine state.",
-                ]
-                : [];
-        const client = this.clientFactory({
-            launcher: new GhidraHeadlessLauncher({
-                analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
-                ...(this.config.ghidraJavaHome === undefined
-                    ? {}
-                    : { javaHome: this.config.ghidraJavaHome }),
-                bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
-                ...(target.format === "dos-mz" ? { dosMz: true } : {}),
-                platform: installation.platform,
+        const resolved = await resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, installation, options?.signal);
+        if (!resolved.ok || resolved.value.profile === null)
+            return resolved;
+        const extensions = await resolveGhidraExtensions(this.config, target, installation.platform, options?.signal);
+        if (!extensions.ok)
+            return extensions;
+        if (extensions.value.length === 0)
+            return resolved;
+        return ok({
+            ...resolved.value,
+            profile: createAnalysisProfile(resolved.value.profile.provider, {
+                ...resolved.value.profile.parameters,
+                analysis_extensions: jsonValueSchema.parse(extensions.value),
             }),
-            targetPath: target.path,
-            targetSha256: target.sha256,
-            transport: installation.platform === "win32"
-                ? "authenticated-loopback-tcp"
-                : "unix-socket",
-            providerVersion: prerequisites.value.providerVersion,
-            profileDigest: committedProfile.digest,
-            ...(target.format === "dos-mz"
-                ? {
-                    expectedLanguageId: "x86:LE:16:Real Mode",
-                    expectedCompilerSpecId: "default",
-                }
-                : {}),
-            ...(context === undefined ? {} : { runId: context.runId }),
-            logger: this.logger.child({ layer: "ghidra-bridge" }),
         });
-        return {
-            execute: async (operation, parameters, options) => {
-                if (operation !== "health" &&
-                    !isGhidraInventoryOperation(operation) &&
-                    !isGhidraFunctionOperation(operation))
-                    return err(new AnalysisCapabilityUnavailableError(GHIDRA_PROVIDER_IDENTITY.id, operation, "The Ghidra adapter does not declare this operation."));
-                if (operation === "health") {
-                    const started = await client.start(options?.signal);
-                    if (!started.ok)
-                        return err(projectSessionError(operation, started.error));
-                    return ok(createAnalysisExecution(started.value, committedProfile.provider, {
-                        analysisProfile: committedProfile,
-                        limitations: [
-                            ...healthLimitations,
-                            ...providerLimitations,
-                            ...targetLimitations,
-                        ],
-                    }));
-                }
-                const input = isGhidraFunctionOperation(operation)
-                    ? parseGhidraFunctionInput(operation, parameters)
-                    : parseGhidraInventoryInput(operation, parameters);
-                if (!input.ok)
-                    return input;
-                const called = await client.callTool(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
-                if (!called.ok)
-                    return err(projectSessionError(operation, called.error));
-                const result = isGhidraFunctionOperation(operation)
-                    ? parseGhidraFunctionResult(operation, called.value)
-                    : parseGhidraInventoryResult(operation, called.value);
-                if (!result.ok)
-                    return result;
-                return ok(createAnalysisExecution(result.value, committedProfile.provider, {
-                    rawResult: called.value,
-                    analysisProfile: committedProfile,
-                    limitations: [
-                        ...limitationsFor(operation),
-                        ...providerLimitations,
-                        ...targetLimitations,
-                    ],
-                }));
-            },
-            runtimeLineageSnapshots: () => {
-                const observation = client.runtimeLineage?.() ?? null;
-                return observation === null
-                    ? []
-                    : [{ provider: committedProfile.provider, observation }];
-            },
-            close: () => client.close(),
-        };
+    }
+    createClient(target, profile, context) {
+        return createGhidraProviderClient({
+            config: this.config,
+            logger: this.logger,
+            clientFactory: this.clientFactory,
+            target,
+            ...(profile === undefined ? {} : { profile }),
+            ...(context === undefined ? {} : { context }),
+            installation: this.#inspectInstallation(),
+        });
     }
     #inspectInstallation() {
         const options = {
@@ -254,42 +191,3 @@ const inspectWindowsP0TargetSupport = (target, diagnostics) => {
         diagnostics,
     };
 };
-const ghidraClientPrerequisites = (target, profile, installation) => {
-    if (target.kind !== "executable")
-        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", `Ghidra cannot import ${target.kind} targets through this adapter.`));
-    if (installation.status === "unavailable")
-        return err(new ProviderAdapterError("ghidra", "health", {
-            diagnostics: ghidraInstallationDiagnostics(installation),
-        }));
-    if (installation.platform === "win32" &&
-        !hasWindowsNativeAuthority(installation.platform))
-        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON));
-    if (profile === undefined || profile.provider.id !== "ghidra")
-        return err(new ProviderAdapterError("ghidra", "health"));
-    return ok({
-        analyzeHeadlessPath: installation.analyzeHeadlessPath,
-        providerVersion: installation.providerVersion,
-        profile,
-    });
-};
-const unavailableClient = (failure) => ({
-    execute: () => Promise.resolve(err(failure)),
-    close: () => Promise.resolve(),
-});
-const projectSessionError = (operation, failure) => {
-    if (failure.kind === "cancelled")
-        return new AnalysisCancelledError(operation);
-    if (failure.kind === "timeout" || failure.kind === "analysis_timeout")
-        return new AnalysisTimeoutError(operation, failure.timeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS);
-    if (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled")
-        return new AnalysisCancelledError(operation);
-    if (failure.kind === "remote" &&
-        ["invalid_request", "not_found", "ambiguous"].includes(failure.remoteCode ?? ""))
-        return new AnalysisInputError(operation, { cause: failure });
-    if (failure.kind === "remote" && failure.remoteCode === "method_unavailable")
-        return new AnalysisCapabilityUnavailableError("ghidra", operation, failure.message);
-    return new ProviderAdapterError("ghidra", operation, {
-        cause: failure,
-        diagnostics: failure.diagnostics,
-    });
-};

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -1,5 +1,4 @@
-import { WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON } from "../process/WindowsAuthority.js";
-import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
+import { hasWindowsNativeAuthority, windowsNativeAuthorityUnavailableReason, } from "../process/WindowsAuthority.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
 /** Public identity committed by every Ghidra-backed observation. */
@@ -8,24 +7,21 @@ export const GHIDRA_PROVIDER_IDENTITY = Object.freeze({
     name: "Ghidra",
     version: null,
 });
-const providerContractByName = new Map(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy" || kind === "enhanced").map((contract) => [contract.name, contract]));
-/** Provider-neutral read-only contracts implemented by the Ghidra adapter. */
-export const GHIDRA_PROVIDER_TOOL_CONTRACTS = Object.freeze([...GHIDRA_INVENTORY_OPERATIONS, ...GHIDRA_FUNCTION_OPERATIONS].map((operation) => {
-    const contract = providerContractByName.get(operation);
-    if (contract === undefined)
-        throw new TypeError(`Missing provider-neutral contract for ${operation}`);
-    return contract;
-}));
+/** Analyst operations implemented by the Ghidra inventory and function adapters. */
+export const GHIDRA_OPERATIONS = Object.freeze([
+    ...GHIDRA_INVENTORY_OPERATIONS,
+    ...GHIDRA_FUNCTION_OPERATIONS,
+]);
 /** Health limitations shared by every Ghidra-backed capability. */
 export const healthLimitations = Object.freeze([
     "The session serves operations only after Ghidra reports default auto-analysis complete; incomplete analysis does not expose partial results.",
-    "The imported Program and temporary project are ephemeral, read-only to REA, and deleted on close.",
+    "The imported Program and temporary project are ephemeral and deleted on close. Annotation operations edit session database metadata; original executable bytes are never written.",
 ]);
 /** Additional limitations applied to the experimental Windows x64 P0 boundary. */
 export const windowsP0Limitations = Object.freeze([
     "Windows Ghidra P0 accepts approved native x86-64 PE applications only; DLL, 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 P0 is not admitted until a native authority proves Job Object ownership, private DACL enforcement, and reparse-safe path admission; bounded taskkill cleanup and chmod(0700) do not prove those controls.",
+    "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.",
 ]);
 /** Limitation text for one admitted operation, including the common base. */
 export const limitationsFor = (operation) => {
@@ -34,6 +30,27 @@ export const limitationsFor = (operation) => {
         "Default-space addresses use lowercase 0x-prefixed hexadecimal; other address spaces use <percent-encoded-space>:0x<hex>.",
     ];
     switch (operation) {
+        case "annotate_native_function":
+            return [
+                ...common,
+                "Names use Ghidra USER_DEFINED source. Name writes preserve the existing namespace; readback uses the fully qualified name. Regular comments map to PRE and inline comments to EOL at the exact function entry. Changes commit together after readback and refreshed analysis; failure rolls them all back.",
+                "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 "inspect_native_load_image":
+            return [
+                ...common,
+                "Independent verification supports DOS MZ and explicitly selected COM, including measured COM entry context. Measured source mappings use inclusive end addresses and complete region digests; no target execution or project mutation occurs.",
+            ];
+        case "read_bytes":
+            return [
+                ...common,
+                "Bytes reflect Ghidra's initialized memory, including loader fixups. Reads stop at an unmapped or uninitialized byte and report completeness explicitly.",
+            ];
+        case "address_to_file_offset":
+            return [
+                ...common,
+                "Offsets come from Ghidra source-byte mappings, not virtual-address arithmetic. Uninitialized memory, missing mappings and ambiguous mappings fail explicitly.",
+            ];
         case "list_documents":
             return [
                 ...common,
@@ -111,17 +128,14 @@ export const limitationsFor = (operation) => {
     }
 };
 /** Provider-neutral capabilities advertised by every non-Windows Ghidra session. */
-export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((contract) => {
-    const operation = contract.analysisOperation;
-    if (operation === null)
-        throw new TypeError(`Missing analysis operation for ${contract.name}`);
+export const CAPABILITIES = Object.freeze(GHIDRA_OPERATIONS.map((operation) => {
     return Object.freeze({
         provider: GHIDRA_PROVIDER_IDENTITY,
         operation,
         available: true,
         reason: null,
         effects: Object.freeze({
-            mutatesArtifact: false,
+            mutatesArtifact: operation === "annotate_native_function",
             launchesProcess: true,
             mayShowUi: false,
             mayAccessNetwork: false,
@@ -129,17 +143,33 @@ export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((co
             changesPermissions: false,
             requiresRoot: false,
         }),
-        limitations: Object.freeze(limitationsFor(contract.name)),
+        limitations: Object.freeze(limitationsFor(operation)),
     });
 }));
 /** Capabilities advertised for the experimental Windows x64 P0 boundary. */
-export const WINDOWS_P0_CAPABILITIES = Object.freeze(CAPABILITIES.map((capability) => Object.freeze({
-    ...capability,
-    available: false,
-    reason: WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON,
-    availabilityCode: "unsupported_host",
-    limitations: Object.freeze([
-        ...capability.limitations,
-        ...windowsP0Limitations,
-    ]),
-})));
+export const windowsP0Capabilities = () => {
+    const available = hasWindowsNativeAuthority("win32");
+    return Object.freeze(CAPABILITIES.map((capability) => {
+        const limitations = Object.freeze([
+            ...capability.limitations,
+            ...windowsP0Limitations,
+        ]);
+        if (capability.effects.mutatesArtifact)
+            return Object.freeze({
+                ...capability,
+                available: false,
+                reason: "Windows Ghidra P0 does not admit database mutation.",
+                availabilityCode: "unsupported_host",
+                limitations,
+            });
+        return available
+            ? Object.freeze({ ...capability, limitations })
+            : Object.freeze({
+                ...capability,
+                available: false,
+                reason: windowsNativeAuthorityUnavailableReason("win32"),
+                availabilityCode: "unsupported_host",
+                limitations,
+            });
+    }));
+};

package/dist/ghidra/GhidraProviderClient.js

@@ -0,0 +1,209 @@
+import { fileURLToPath } from "node:url";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import {} from "../domain/analysisErrorBase.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { GhidraClient } from "./GhidraClient.js";
+import { GHIDRA_STARTUP_TIMEOUT_MS } from "./GhidraDefaults.js";
+import { isGhidraFunctionOperation, parseGhidraFunctionInput, parseGhidraFunctionResult, } from "./GhidraFunctionValues.js";
+import { isGhidraInventoryOperation, parseGhidraInventoryInput, parseGhidraInventoryResult, } from "./GhidraInventoryValues.js";
+import { ghidraInstallationDiagnostics, } from "./GhidraInstallation.js";
+import { unverifiedGhidraBuildLimitation } from "./GhidraInstallationPolicy.js";
+import { GhidraHeadlessLauncher } from "./GhidraLauncher.js";
+import { attestGhidraNativeLoadImage } from "./GhidraLoadImageAttest.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";
+/** Build one AnalysisClient for an admitted Ghidra target and profile. */
+export const createGhidraProviderClient = (input) => {
+    const { config, logger, clientFactory, target, context, installation } = input;
+    const prerequisites = ghidraClientPrerequisites(target, input.profile, installation);
+    if (!prerequisites.ok)
+        return unavailableClient(prerequisites.error);
+    const committedProfile = prerequisites.value.profile;
+    const extensionProfile = ghidraExtensionSchema
+        .array()
+        .safeParse(committedProfile.parameters.analysis_extensions ?? []);
+    if (!extensionProfile.success ||
+        (config.ghidraNativeAotJar !== undefined &&
+            extensionProfile.data.length === 0))
+        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+            diagnostics: {
+                reason: "Resolve the configured Ghidra extensions into an analysis profile before opening the session.",
+            },
+        }));
+    const extensions = extensionProfile.data;
+    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.",
+        ]
+        : [];
+    const providerLimitations = installation.platform === "win32"
+        ? windowsP0Limitations
+        : installation.platform === "darwin"
+            ? [
+                "macOS sessions require a matching executable Ghidra native decompiler; REA checks for it but does not build native components or change Gatekeeper quarantine state.",
+            ]
+            : [];
+    const client = clientFactory({
+        platform: installation.platform,
+        launcher: new GhidraHeadlessLauncher({
+            analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
+            ...(config.ghidraJavaHome === undefined
+                ? {}
+                : { javaHome: config.ghidraJavaHome }),
+            bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
+            ...(target.format === "dos-mz" ? { dosMz: true } : {}),
+            ...(target.format === "dos-com" ? { dosCom: true } : {}),
+            platform: installation.platform,
+            ...(extensions.length === 0 ? {} : { analysisExtensions: extensions }),
+        }),
+        targetPath: installation.platform === "win32"
+            ? (target.sourcePath ?? target.path)
+            : target.path,
+        targetSha256: target.sha256,
+        transport: installation.platform === "win32"
+            ? "authenticated-loopback-tcp"
+            : "unix-socket",
+        providerVersion: prerequisites.value.providerVersion,
+        profileDigest: committedProfile.digest,
+        ...(["dos-mz", "dos-com"].includes(target.format)
+            ? {
+                expectedLanguageId: "x86:LE:16:Real Mode",
+                expectedCompilerSpecId: "default",
+            }
+            : {}),
+        ...(context === undefined ? {} : { runId: context.runId }),
+        logger: logger.child({ layer: "ghidra-bridge" }),
+    });
+    const checkExtensions = async (operation, info) => {
+        extensionFailure = ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation);
+        if (extensionFailure === undefined)
+            return undefined;
+        await client.close();
+        return extensionFailure;
+    };
+    const releaseLimitation = unverifiedGhidraBuildLimitation(prerequisites.value.providerVersion);
+    const sessionLimitations = [
+        ...providerLimitations,
+        ...targetLimitations,
+        ...ghidraExtensionLimitations(extensions),
+        ...(releaseLimitation === undefined ? [] : [releaseLimitation]),
+    ];
+    return {
+        execute: async (operation, parameters, options) => {
+            if (extensionFailure !== undefined)
+                return err(extensionFailure);
+            if (operation !== "health" &&
+                !isGhidraInventoryOperation(operation) &&
+                !isGhidraFunctionOperation(operation))
+                return err(new AnalysisCapabilityUnavailableError(GHIDRA_PROVIDER_IDENTITY.id, operation, "The Ghidra adapter does not declare this operation."));
+            if (operation === "health") {
+                const started = await client.start(options?.signal);
+                if (!started.ok)
+                    return err(projectSessionError(operation, started.error));
+                const failed = await checkExtensions(operation, started.value);
+                if (failed !== undefined)
+                    return err(failed);
+                return ok(createAnalysisExecution(started.value, committedProfile.provider, {
+                    analysisProfile: committedProfile,
+                    limitations: [...healthLimitations, ...sessionLimitations],
+                }));
+            }
+            const input = isGhidraFunctionOperation(operation)
+                ? parseGhidraFunctionInput(operation, parameters)
+                : parseGhidraInventoryInput(operation, parameters);
+            if (!input.ok)
+                return input;
+            if (extensions.length > 0) {
+                const started = await client.start(options?.signal);
+                if (!started.ok)
+                    return err(projectSessionError(operation, started.error));
+                const failed = await checkExtensions(operation, started.value);
+                if (failed !== undefined)
+                    return err(failed);
+            }
+            const called = await client.callTool(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
+            if (!called.ok)
+                return err(projectSessionError(operation, called.error));
+            const result = isGhidraFunctionOperation(operation)
+                ? parseGhidraFunctionResult(operation, called.value)
+                : parseGhidraInventoryResult(operation, called.value);
+            if (!result.ok)
+                return result;
+            let normalized = result.value;
+            if (operation === "inspect_native_load_image") {
+                const attested = await attestGhidraNativeLoadImage(target, operation, result.value, client, (failure) => projectSessionError(operation, failure));
+                if (!attested.ok)
+                    return attested;
+                normalized = attested.value;
+            }
+            return ok(createAnalysisExecution(normalized, committedProfile.provider, {
+                rawResult: called.value,
+                analysisProfile: committedProfile,
+                limitations: [...limitationsFor(operation), ...sessionLimitations],
+            }));
+        },
+        runtimeLineageSnapshots: () => {
+            const observation = client.runtimeLineage?.() ?? null;
+            return observation === null
+                ? []
+                : [{ provider: committedProfile.provider, observation }];
+        },
+        close: () => client.close(),
+    };
+};
+const ghidraClientPrerequisites = (target, profile, installation) => {
+    if (target.kind !== "executable")
+        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", `Ghidra cannot import ${target.kind} targets through this adapter.`));
+    if (installation.status === "unavailable")
+        return err(new ProviderAdapterError("ghidra", "health", {
+            diagnostics: ghidraInstallationDiagnostics(installation),
+        }));
+    if (installation.platform === "win32" &&
+        !hasWindowsNativeAuthority(installation.platform))
+        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", windowsNativeAuthorityUnavailableReason(installation.platform)));
+    if (profile === undefined || profile.provider.id !== "ghidra")
+        return err(new ProviderAdapterError("ghidra", "health"));
+    return ok({
+        analyzeHeadlessPath: installation.analyzeHeadlessPath,
+        providerVersion: installation.providerVersion,
+        profile,
+    });
+};
+const unavailableClient = (failure) => ({
+    execute: () => Promise.resolve(err(failure)),
+    close: () => Promise.resolve(),
+});
+const projectSessionError = (operation, failure) => {
+    if (operation === "annotate_native_function" &&
+        failure.kind === "remote" &&
+        failure.remoteCode === "invalid_function_name")
+        return new AnalysisInputError(operation, { cause: failure }, [
+            { path: ["name"], reason: "invalid_value", message: failure.message },
+        ]);
+    if (failure.kind === "cancelled")
+        return new AnalysisCancelledError(operation);
+    if (failure.kind === "timeout" || failure.kind === "analysis_timeout")
+        return new AnalysisTimeoutError(operation, failure.timeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS);
+    if (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled")
+        return new AnalysisCancelledError(operation);
+    if (failure.kind === "remote" &&
+        ["invalid_request", "not_found", "ambiguous"].includes(failure.remoteCode ?? ""))
+        return new AnalysisInputError(operation, { cause: failure });
+    if (failure.kind === "remote" && failure.remoteCode === "method_unavailable")
+        return new AnalysisCapabilityUnavailableError("ghidra", operation, failure.message);
+    return new ProviderAdapterError("ghidra", operation, {
+        cause: failure,
+        diagnostics: failure.diagnostics,
+    });
+};

package/dist/ghidra/GhidraRequestQueue.js

@@ -88,9 +88,9 @@ export class GhidraRequestQueue {
             executionSettled = true;
             entry.resolve(result);
         })
-            .catch(() => {
+            .catch((cause) => {
             executionSettled = true;
-            entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly")));
+            entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly", cause)));
         })
             .finally(() => {
             if (entry.signal !== undefined && onAbort !== undefined)

package/dist/ghidra/GhidraResponseBuffer.js

@@ -2,12 +2,17 @@
 export class GhidraResponseBuffer {
     #options;
     #buffer = "";
+    #fragments = [];
     constructor(options) {
         this.#options = options;
     }
     /** Consume one decoded socket chunk. */
     push(chunk) {
-        this.#buffer += chunk;
+        this.#fragments.push(chunk);
+        if (!chunk.includes("\n"))
+            return;
+        this.#buffer += this.#fragments.join("");
+        this.#fragments = [];
         let newline = this.#buffer.indexOf("\n");
         while (newline >= 0) {
             const encodedLine = this.#buffer.slice(0, newline);
@@ -21,5 +26,6 @@ export class GhidraResponseBuffer {
     /** Drop any incomplete line when a session closes. */
     reset() {
         this.#buffer = "";
+        this.#fragments = [];
     }
 }