rea-agents 1.6.0 → 2.0.0

package/dist/ghidra/GhidraProvider.js

@@ -0,0 +1,366 @@
+import { fileURLToPath } from "node:url";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { ENHANCED_TOOL_CONTRACTS, OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { GhidraClient } from "./GhidraClient.js";
+import { GHIDRA_ANALYSIS_TIMEOUT_SECONDS, GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS, GHIDRA_DECOMPILE_TIMEOUT_SECONDS, GHIDRA_MAX_LINE_BYTES, GHIDRA_REQUEST_TIMEOUT_MS, GHIDRA_STARTUP_TIMEOUT_MS, } from "./GhidraDefaults.js";
+import { GHIDRA_FUNCTION_OPERATIONS, isGhidraFunctionOperation, parseGhidraFunctionInput, parseGhidraFunctionResult, } from "./GhidraFunctionValues.js";
+import { GHIDRA_INVENTORY_OPERATIONS, isGhidraInventoryOperation, parseGhidraInventoryInput, parseGhidraInventoryResult, } from "./GhidraInventoryValues.js";
+import { ghidraInstallationDiagnostics, inspectGhidraInstallation, } from "./GhidraInstallation.js";
+import { GhidraHeadlessLauncher } from "./GhidraLauncher.js";
+import { resolveGhidraAnalysisProfile } from "./GhidraAnalysisProfile.js";
+/** Public identity committed by every Ghidra-backed observation. */
+export const GHIDRA_PROVIDER_IDENTITY = Object.freeze({
+    id: "ghidra",
+    name: "Ghidra",
+    version: null,
+});
+const providerContractByName = new Map([...OFFICIAL_TOOL_CONTRACTS, ...ENHANCED_TOOL_CONTRACTS].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;
+}));
+const PAGINATED_OPERATIONS = new Set([
+    "list_names",
+    "list_procedures",
+    "list_strings",
+    "search_procedures",
+    "search_strings",
+    "procedure_references",
+    "analyze_function",
+]);
+const SEARCH_OPERATIONS = new Set([
+    "search_procedures",
+    "search_strings",
+]);
+const DECOMPILE_OPERATIONS = new Set([
+    "procedure_pseudo_code",
+    "analyze_function",
+]);
+const healthLimitations = Object.freeze([
+    "The session serves operations only after default Ghidra auto-analysis completes; an analysis timeout fails the open instead of exposing partial results.",
+    "The imported Program and temporary project are ephemeral, read-only to REA, and deleted on close.",
+]);
+const limitationsFor = (operation) => {
+    const common = [
+        ...healthLimitations,
+        "Default-space addresses use lowercase 0x-prefixed hexadecimal; other address spaces use <percent-encoded-space>:0x<hex>.",
+    ];
+    switch (operation) {
+        case "list_documents":
+            return [
+                ...common,
+                "A headless Ghidra session contains exactly one imported Program, unlike Hopper's multi-document GUI session.",
+            ];
+        case "list_names":
+            return [
+                ...common,
+                "The symbol inventory includes memory and external symbols, including dynamic symbols, but excludes variable and no-address namespace records.",
+            ];
+        case "list_procedures":
+        case "procedure_address":
+            return [
+                ...common,
+                "External functions and local thunks are distinct; procedure metadata identifies both and preserves a thunk target when Ghidra resolves one.",
+            ];
+        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.",
+                "Returned values are bounded to 1,024 Unicode code points and mark value_truncated instead of silently crossing the wire budget.",
+            ];
+        case "list_segments":
+            return [
+                ...common,
+                "Memory-block end addresses are exclusive; permissions come from Ghidra MemoryBlock flags rather than inference from section names.",
+            ];
+        case "search_procedures":
+        case "search_strings":
+            return [
+                ...common,
+                "Literal search enforces 1,000,000 cumulative work units; regex mode also accepts only a conservative finite Java-regex subset with 10,000 static paths and 4,096 UTF-16 code units per candidate.",
+            ];
+        case "procedure_pseudo_code":
+            return [
+                ...common,
+                "Pseudocode is Ghidra decompiler output, not original source and not text-equivalent to Hopper output; each decompile has a 30-second native deadline.",
+                "External functions and functions without an analyzable body return null; other decompiler failures remain explicit.",
+            ];
+        case "procedure_assembly":
+            return [
+                ...common,
+                "Assembly is Ghidra Listing text and fails rather than silently truncating when the 100,000-instruction or 1 MiB wire bound is exceeded.",
+            ];
+        case "procedure_callers":
+        case "procedure_callees":
+            return [
+                ...common,
+                "Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals.",
+            ];
+        case "xrefs":
+            return [
+                ...common,
+                "The direct address list projects exact Ghidra references to one address but does not expose their kinds; procedure_references and analyze_function preserve available kind metadata.",
+                "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
+            ];
+        case "procedure_references":
+            return [
+                ...common,
+                "Reference kinds are direct Ghidra ReferenceManager observations; unresolved computed flows without a target are absent and remain unknown.",
+                "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
+                "Instruction scans stop at max_instructions; a truncated scan reports an unknown total and no false continuation.",
+            ];
+        case "analyze_function":
+            return [
+                ...common,
+                "The dossier combines Ghidra FunctionManager, Listing, ReferenceManager, BasicBlockModel, and decompiler observations; provider-specific pseudocode and assembly are not cross-provider text invariants.",
+                "Resolved reference metadata identifies computed, indirect, external, call, jump, and data edges; unresolved targetless flows remain unknown, and function classifications distinguish thunks and externals.",
+                "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
+                "The Java bridge serializes one function request per Program through a bounded 32-request queue and applies a 30-second native decompilation deadline.",
+            ];
+        default:
+            return common;
+    }
+};
+const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((contract) => Object.freeze({
+    provider: GHIDRA_PROVIDER_IDENTITY,
+    operation: contract.name,
+    inputContractVersion: 1,
+    outputContractVersion: 1,
+    available: true,
+    reason: null,
+    pagination: PAGINATED_OPERATIONS.has(contract.name)
+        ? "offset"
+        : "none",
+    exhaustive: !PAGINATED_OPERATIONS.has(contract.name),
+    effects: Object.freeze({
+        mutatesArtifact: false,
+        launchesProcess: true,
+        mayShowUi: false,
+        mayAccessNetwork: false,
+        mayWriteFilesystem: true,
+        changesPermissions: false,
+        requiresRoot: false,
+    }),
+    limits: Object.freeze({
+        maxResults: PAGINATED_OPERATIONS.has(contract.name)
+            ? SEARCH_OPERATIONS.has(contract.name)
+                ? 100
+                : 500
+            : null,
+        maxPayloadBytes: GHIDRA_MAX_LINE_BYTES,
+        timeoutMs: DECOMPILE_OPERATIONS.has(contract.name)
+            ? GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS
+            : GHIDRA_REQUEST_TIMEOUT_MS,
+    }),
+    limitations: Object.freeze(limitationsFor(contract.name)),
+})));
+const SUPPORTED_ARCHITECTURES = new Set(["x86", "x86_64", "arm", "arm64"]);
+const SUPPORTED_FORMATS = new Set(["elf", "pe", "mach-o"]);
+/** Linux Ghidra candidate backed by an isolated read-only headless import. */
+export class GhidraProvider {
+    config;
+    logger;
+    installationHost;
+    clientFactory;
+    #installation;
+    constructor(config, logger, installationHost, clientFactory = (options) => new GhidraClient(options)) {
+        this.config = config;
+        this.logger = logger;
+        this.installationHost = installationHost;
+        this.clientFactory = clientFactory;
+    }
+    identity() {
+        return GHIDRA_PROVIDER_IDENTITY;
+    }
+    capabilities() {
+        return CAPABILITIES;
+    }
+    inspectAvailability() {
+        const installation = this.#inspectInstallation();
+        const diagnostics = ghidraInstallationDiagnostics(installation);
+        return installation.available
+            ? {
+                status: "available",
+                code: null,
+                reason: null,
+                diagnostics,
+            }
+            : {
+                status: "unavailable",
+                code: installation.rejectionCode ?? "not_configured",
+                reason: installation.reason ?? "Ghidra installation is not available.",
+                diagnostics,
+            };
+    }
+    inspectTargetSupport(target) {
+        const diagnostics = {
+            target_kind: target.kind,
+            target_format: target.format,
+            architecture: target.architecture ?? null,
+        };
+        if (target.kind !== "executable")
+            return {
+                status: "unsupported",
+                code: "target_kind_unsupported",
+                reason: `Ghidra v1 imports executable targets, not ${target.kind} targets.`,
+                diagnostics,
+            };
+        if (!SUPPORTED_FORMATS.has(target.format))
+            return {
+                status: "unsupported",
+                code: "target_format_unsupported",
+                reason: `Ghidra v1 does not import ${target.format} through this adapter.`,
+                diagnostics,
+            };
+        if (target.architecture === undefined ||
+            !SUPPORTED_ARCHITECTURES.has(target.architecture))
+            return {
+                status: "unsupported",
+                code: "architecture_unsupported",
+                reason: "Ghidra v1 requires a concrete x86, x86_64, arm, or arm64 target architecture.",
+                diagnostics,
+            };
+        return {
+            status: "supported",
+            code: null,
+            reason: null,
+            diagnostics,
+        };
+    }
+    resolveAnalysisProfile(target, options) {
+        return resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, this.#inspectInstallation(), options?.signal);
+    }
+    createClient(target, profile) {
+        const installation = this.#inspectInstallation();
+        const prerequisites = ghidraClientPrerequisites(target, profile, installation);
+        if (!prerequisites.ok)
+            return unavailableClient(prerequisites.error);
+        const committedProfile = prerequisites.value.profile;
+        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)),
+            }),
+            targetPath: target.path,
+            providerVersion: prerequisites.value.providerVersion,
+            profileDigest: committedProfile.digest,
+            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,
+                    }));
+                }
+                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 }),
+                    ...(DECOMPILE_OPERATIONS.has(operation)
+                        ? { timeoutMs: GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS }
+                        : {}),
+                });
+                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),
+                }));
+            },
+            close: () => client.close(),
+        };
+    }
+    #inspectInstallation() {
+        const options = {
+            ...(this.config.ghidraInstallDir === undefined
+                ? {}
+                : { installDir: this.config.ghidraInstallDir }),
+            ...(this.config.ghidraJavaHome === undefined
+                ? {}
+                : { javaHome: this.config.ghidraJavaHome }),
+            ...(this.installationHost?.platform === undefined
+                ? {}
+                : { platform: this.installationHost.platform }),
+            ...(this.installationHost?.architecture === undefined
+                ? {}
+                : { architecture: this.installationHost.architecture }),
+        };
+        this.#installation ??=
+            this.installationHost === undefined
+                ? inspectGhidraInstallation(options)
+                : inspectGhidraInstallation(options, this.installationHost);
+        return this.#installation;
+    }
+}
+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.available ||
+        installation.analyzeHeadlessPath === null ||
+        installation.providerVersion === null)
+        return err(new ProviderAdapterError("ghidra", "health", {
+            diagnostics: ghidraInstallationDiagnostics(installation),
+        }));
+    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 ??
+            (failure.kind === "analysis_timeout"
+                ? GHIDRA_ANALYSIS_TIMEOUT_SECONDS * 1_000
+                : GHIDRA_STARTUP_TIMEOUT_MS));
+    if (failure.kind === "remote" && failure.remoteCode === "decompile_timeout")
+        return new AnalysisTimeoutError(operation, GHIDRA_DECOMPILE_TIMEOUT_SECONDS * 1_000);
+    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

@@ -0,0 +1,98 @@
+import { performance } from "node:perf_hooks";
+import { err } from "../domain/result.js";
+/** Bounded FIFO that admits one Ghidra Program request at a time. */
+export class GhidraRequestQueue {
+    maximum;
+    execute;
+    failure;
+    #queue = [];
+    #active = false;
+    #size = 0;
+    constructor(maximum, execute, failure) {
+        this.maximum = maximum;
+        this.execute = execute;
+        this.failure = failure;
+    }
+    /** Queue one request, counting queue wait against its declared deadline. */
+    run(method, parameters, options) {
+        if (options.signal?.aborted === true)
+            return Promise.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
+        if (options.timeoutMs <= 0)
+            return Promise.resolve(err(this.failure("timeout", "Ghidra request deadline elapsed", options.timeoutMs)));
+        if (this.#size >= this.maximum)
+            return Promise.resolve(err(this.failure("protocol", `Ghidra serial request queue reached its ${String(this.maximum)}-request limit`)));
+        this.#size += 1;
+        return new Promise((resolve) => {
+            let entry;
+            const onAbort = options.signal === undefined
+                ? undefined
+                : () => this.#rejectQueued(entry, err(this.failure("cancelled", "Ghidra request was cancelled")));
+            const timer = setTimeout(() => this.#rejectQueued(entry, err(this.failure("timeout", "Ghidra request deadline elapsed in the serial queue", options.timeoutMs))), options.timeoutMs);
+            entry = {
+                method,
+                parameters,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs,
+                deadline: performance.now() + options.timeoutMs,
+                resolve,
+                timer,
+                onAbort,
+            };
+            this.#queue.push(entry);
+            if (onAbort !== undefined)
+                options.signal?.addEventListener("abort", onAbort, { once: true });
+            this.#drain();
+        });
+    }
+    /** Fail requests that have not crossed the socket during session cleanup. */
+    failQueued(failure) {
+        for (const entry of this.#queue.splice(0)) {
+            this.#release(entry);
+            this.#size -= 1;
+            entry.resolve(err(failure));
+        }
+    }
+    #drain() {
+        if (this.#active)
+            return;
+        const entry = this.#queue.shift();
+        if (entry === undefined)
+            return;
+        this.#release(entry);
+        const remaining = entry.deadline - performance.now();
+        if (entry.signal?.aborted === true || remaining <= 0) {
+            this.#size -= 1;
+            entry.resolve(err(entry.signal?.aborted === true
+                ? this.failure("cancelled", "Ghidra request was cancelled")
+                : this.failure("timeout", "Ghidra request deadline elapsed in the serial queue", entry.timeoutMs)));
+            this.#drain();
+            return;
+        }
+        this.#active = true;
+        void this.execute(entry.method, entry.parameters, {
+            ...(entry.signal === undefined ? {} : { signal: entry.signal }),
+            timeoutMs: remaining,
+        })
+            .then(entry.resolve)
+            .catch(() => entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly"))))
+            .finally(() => {
+            this.#active = false;
+            this.#size -= 1;
+            this.#drain();
+        });
+    }
+    #rejectQueued(entry, result) {
+        const index = this.#queue.indexOf(entry);
+        if (index < 0)
+            return;
+        this.#queue.splice(index, 1);
+        this.#release(entry);
+        this.#size -= 1;
+        entry.resolve(result);
+    }
+    #release(entry) {
+        clearTimeout(entry.timer);
+        if (entry.signal !== undefined && entry.onAbort !== undefined)
+            entry.signal.removeEventListener("abort", entry.onAbort);
+    }
+}

package/dist/ghidra/GhidraResponseBuffer.js

@@ -0,0 +1,31 @@
+/** Splits fragmented UTF-8 socket data while enforcing a byte limit per line. */
+export class GhidraResponseBuffer {
+    #options;
+    #buffer = "";
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Consume one decoded socket chunk. */
+    push(chunk) {
+        this.#buffer += chunk;
+        let newline = this.#buffer.indexOf("\n");
+        while (newline >= 0) {
+            const encodedLine = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (Buffer.byteLength(encodedLine) > this.#options.maxLineBytes) {
+                this.#options.onFailure("Ghidra response exceeded the maximum line size");
+                return;
+            }
+            const line = encodedLine.trim();
+            if (line.length > 0)
+                this.#options.onLine(line);
+            newline = this.#buffer.indexOf("\n");
+        }
+        if (Buffer.byteLength(this.#buffer) > this.#options.maxLineBytes)
+            this.#options.onFailure("Ghidra response exceeded the maximum line size");
+    }
+    /** Drop any incomplete line when a session closes. */
+    reset() {
+        this.#buffer = "";
+    }
+}

package/dist/ghidra/GhidraResponseRouter.js

@@ -0,0 +1,24 @@
+import { err } from "../domain/result.js";
+import { ghidraResponseResult, parseGhidraResponseLine } from "./protocol.js";
+/** Routes validated response IDs without giving the wire protocol client state. */
+export class GhidraResponseRouter {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Parse and settle one complete response line. */
+    route(line) {
+        const parsed = parseGhidraResponseLine(line);
+        if (!parsed.ok) {
+            this.#options.protocolFailure(parsed.error.message, parsed.error);
+            return;
+        }
+        if (!this.#options.pending.has(parsed.value.id)) {
+            if (parsed.value.id >= this.#options.nextId())
+                this.#options.protocolFailure("Ghidra returned an unknown response id");
+            return;
+        }
+        const result = ghidraResponseResult(parsed.value);
+        this.#options.pending.settle(parsed.value.id, result.ok ? result : err(this.#options.remoteFailure(result.error)));
+    }
+}

package/dist/ghidra/GhidraSessionError.js

@@ -0,0 +1,39 @@
+/** Provider-owned failure with bounded, token-redacted local diagnostics. */
+export class GhidraSessionError extends Error {
+    kind;
+    diagnostics;
+    timeoutMs;
+    remoteCode;
+    constructor(kind, message, diagnostics = {}, options = {}) {
+        super(message, options);
+        this.kind = kind;
+        this.name = "GhidraSessionError";
+        this.diagnostics = structuredClone(diagnostics);
+        this.timeoutMs = options.timeoutMs;
+        this.remoteCode = options.remoteCode;
+    }
+}
+/** Build a session failure while preserving bounded remote failure metadata. */
+const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kind, failure.message, failure.remoteCode === undefined
+    ? failure.diagnostics
+    : {
+        ...failure.diagnostics,
+        remote_code: failure.remoteCode,
+        remote_message: failure.message,
+    }, {
+    ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+    ...(failure.timeoutMs === undefined
+        ? {}
+        : { timeoutMs: failure.timeoutMs }),
+    ...(failure.remoteCode === undefined
+        ? {}
+        : { remoteCode: failure.remoteCode }),
+});
+/** Bind session-failure construction to a live, token-redacted diagnostic view. */
+export const bindGhidraSessionFailure = (diagnostics) => (kind, message, cause, options = {}) => createGhidraSessionError({
+    kind,
+    message,
+    diagnostics: diagnostics(),
+    ...(cause === undefined ? {} : { cause }),
+    ...options,
+});

package/dist/ghidra/GhidraSessionValues.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { err, ok } from "../domain/result.js";
+import { GHIDRA_BRIDGE_VERSION } from "./GhidraDefaults.js";
+import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
+import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
+/** Exact methods proved by the bridge handshake after auto-analysis. */
+export const GHIDRA_SESSION_CAPABILITIES = [
+    "ping",
+    "shutdown",
+    ...GHIDRA_INVENTORY_OPERATIONS,
+    ...GHIDRA_FUNCTION_OPERATIONS,
+];
+const capabilitySchema = z.enum(GHIDRA_SESSION_CAPABILITIES);
+const sessionInfoSchema = z
+    .object({
+    name: z.literal("REA Ghidra bridge"),
+    bridge_version: z.literal(GHIDRA_BRIDGE_VERSION),
+    run_id: z.string().uuid(),
+    profile_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+    provider: z
+        .object({
+        id: z.literal("ghidra"),
+        version: z.string().min(1),
+    })
+        .strict(),
+    read_only: z.literal(true),
+    analysis_complete: z.boolean(),
+    analysis_timed_out: z.boolean(),
+    capabilities: z
+        .array(capabilitySchema)
+        .length(GHIDRA_SESSION_CAPABILITIES.length),
+    target: z
+        .object({
+        name: z.string().min(1),
+        language_id: z.string().min(1),
+        compiler_spec_id: z.string().min(1),
+        image_base: z.string().regex(/^0x[0-9a-f]+$/u),
+        default_address_space: z.string().min(1),
+    })
+        .strict(),
+})
+    .strict();
+/** Require exact run, provider, and profile identity from the Java bridge. */
+export const parseGhidraSessionInfo = (value, expected) => {
+    const parsed = sessionInfoSchema.safeParse(value);
+    if (!parsed.success ||
+        parsed.data.run_id !== expected.runId ||
+        parsed.data.provider.version !== expected.providerVersion ||
+        parsed.data.profile_digest !== expected.profileDigest ||
+        new Set(parsed.data.capabilities).size !==
+            GHIDRA_SESSION_CAPABILITIES.length ||
+        GHIDRA_SESSION_CAPABILITIES.some((capability) => !parsed.data.capabilities.includes(capability)) ||
+        parsed.data.analysis_complete === parsed.data.analysis_timed_out)
+        return err(new Error("Ghidra bridge handshake identity is invalid"));
+    return ok(parsed.data);
+};
+/** Require acknowledgement that the private bridge loop has ended. */
+export const isGhidraShutdownAcknowledgement = (value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    value.shutdown === true &&
+    value.project_ephemeral === true;

package/dist/ghidra/GhidraSocketConnection.js

@@ -0,0 +1,46 @@
+import { createConnection } from "node:net";
+import { err, ok } from "../domain/result.js";
+import { GhidraSessionError } from "./GhidraSessionError.js";
+/** Attach decoded bridge listeners and return an idempotent detach callback. */
+export const attachGhidraSocket = (socket, handlers) => {
+    socket.setEncoding("utf8");
+    socket.on("data", handlers.data);
+    socket.on("error", handlers.error);
+    socket.on("close", handlers.close);
+    return () => {
+        socket.off("data", handlers.data);
+        socket.off("error", handlers.error);
+        socket.off("close", handlers.close);
+    };
+};
+/** Open one abort-aware Ghidra Unix-socket connection attempt. */
+export const connectGhidraSocketOnce = (socketPath, signal) => new Promise((resolve) => {
+    const socket = createConnection(socketPath);
+    const detach = () => {
+        socket.off("connect", onConnect);
+        socket.off("error", onError);
+        signal.removeEventListener("abort", onAbort);
+    };
+    const onConnect = () => {
+        detach();
+        resolve(ok(socket));
+    };
+    const onError = (cause) => {
+        detach();
+        socket.destroy();
+        resolve(err(new GhidraSessionError("start", "Ghidra bridge connection failed", {
+            socket_path: socketPath,
+            error: cause.message,
+        })));
+    };
+    const onAbort = () => {
+        detach();
+        socket.destroy();
+        resolve(err(new GhidraSessionError("cancelled", "Ghidra bridge connection was cancelled", { socket_path: socketPath })));
+    };
+    socket.once("connect", onConnect);
+    socket.once("error", onError);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+});