rea-agents 1.6.0 → 2.0.0

package/dist/dotnet/ManagedStaticProvider.js

@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
+import { MANAGED_TOOL_CONTRACTS, managedArtifactInputSchema, managedMemberInputSchema, managedNativeBoundaryInputSchema, } from "../contracts/managedToolContracts.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, EvidenceIntegrityError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { inspectManagedArtifactBytes } from "./ManagedArtifactInspector.js";
+import { inspectManagedMembersBytes } from "./ManagedMemberInspector.js";
+import { inspectManagedNativeBoundariesBytes } from "./ManagedNativeBoundaryInspector.js";
+const IDENTITY = Object.freeze(MANAGED_STATIC_PROVIDER);
+/** Execution-free managed PE/CLI auxiliary provider. */
+export class ManagedStaticProvider {
+    #capabilities = Object.freeze(MANAGED_TOOL_CONTRACTS.map((contract) => Object.freeze({
+        provider: IDENTITY,
+        operation: contract.name,
+        inputContractVersion: 1,
+        outputContractVersion: 1,
+        available: true,
+        reason: null,
+        pagination: "offset",
+        exhaustive: false,
+        effects: Object.freeze({
+            mutatesArtifact: false,
+            launchesProcess: false,
+            mayShowUi: false,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: false,
+            changesPermissions: false,
+            requiresRoot: false,
+        }),
+        limits: Object.freeze({
+            maxResults: 500,
+            maxPayloadBytes: 4 * 1024 * 1024,
+            timeoutMs: null,
+        }),
+        limitations: limitationsFor(contract.name),
+    })));
+    identity() {
+        return IDENTITY;
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    createClient(target) {
+        return new ManagedStaticClient(target);
+    }
+}
+class ManagedStaticClient {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+    async execute(operation, parameters, options) {
+        if (operation === "health")
+            return ok(createAnalysisExecution(null, IDENTITY));
+        if (!isManagedOperation(operation))
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by the managed static provider."));
+        if (this.target.format !== "pe")
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Managed static triage requires a PE target; observed ${this.target.format}.`));
+        try {
+            if (options?.signal?.aborted === true)
+                return err(new AnalysisCancelledError(operation));
+            const maxFileBytes = maxRequestedFileBytes(operation, parameters);
+            const metadata = await stat(this.target.path);
+            if (metadata.size > maxFileBytes)
+                return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Artifact size ${String(metadata.size)} exceeds max_file_bytes ${String(maxFileBytes)}.`));
+            const bytes = await readFile(this.target.path, options?.signal === undefined ? undefined : { signal: options.signal });
+            if (bytes.length > maxFileBytes)
+                return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Artifact grew beyond max_file_bytes ${String(maxFileBytes)} while it was read.`));
+            const observedDigest = createHash("sha256").update(bytes).digest("hex");
+            if (observedDigest !== this.target.sha256)
+                return err(new EvidenceIntegrityError(`Managed artifact digest changed after open: expected ${this.target.sha256}, observed ${observedDigest} at ${this.target.path}`));
+            const result = inspectManagedOperation(operation, parameters, bytes, this.target);
+            return ok(createAnalysisExecution(result, IDENTITY, {
+                rawResult: null,
+                limitations: result.limitations,
+                subject: this.target,
+                locations: managedLocations(result),
+            }));
+        }
+        catch (cause) {
+            if (options?.signal?.aborted === true)
+                return err(new AnalysisCancelledError(operation));
+            return err(new ProviderAdapterError(IDENTITY.id, operation, { cause }));
+        }
+    }
+    close() {
+        return Promise.resolve();
+    }
+}
+const isManagedOperation = (operation) => MANAGED_TOOL_CONTRACTS.some(({ name }) => name === operation);
+const limitationsFor = (operation) => Object.freeze(operation === "inspect_managed_artifact"
+    ? [
+        "This capability inventories PE/CLI identity only; inspect_managed_members admits bounded metadata members, signatures, and CIL anchors.",
+        "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+    ]
+    : operation === "inspect_managed_native_boundaries"
+        ? [
+            "This capability inventories managed declarations for native boundaries only; native exports, thunks, and addresses require separate native-provider evidence.",
+            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+        ]
+        : [
+            "This capability decodes bounded PE/CLI metadata members, signatures, and file-backed method bodies; decompiled C# and cross-build matching are separate future contracts.",
+            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+        ]);
+const maxRequestedFileBytes = (operation, parameters) => {
+    if (operation === "inspect_managed_artifact")
+        return managedArtifactInputSchema.parse(parameters).max_file_bytes;
+    if (operation === "inspect_managed_native_boundaries")
+        return managedNativeBoundaryInputSchema.parse(parameters).max_file_bytes;
+    return managedMemberInputSchema.parse(parameters).max_file_bytes;
+};
+const inspectManagedOperation = (operation, parameters, bytes, target) => {
+    if (operation === "inspect_managed_artifact") {
+        const input = managedArtifactInputSchema.parse(parameters);
+        return inspectManagedArtifactBytes(bytes, target, {
+            referenceOffset: input.reference_offset,
+            referenceLimit: input.reference_limit,
+            resourceOffset: input.resource_offset,
+            resourceLimit: input.resource_limit,
+            attributeOffset: input.attribute_offset,
+            attributeLimit: input.attribute_limit,
+            maxMetadataBytes: input.max_metadata_bytes,
+            maxTableRows: input.max_table_rows,
+            maxHeapItemBytes: input.max_heap_item_bytes,
+        });
+    }
+    if (operation === "inspect_managed_native_boundaries") {
+        const input = managedNativeBoundaryInputSchema.parse(parameters);
+        return inspectManagedNativeBoundariesBytes(bytes, target, {
+            moduleRefOffset: input.module_ref_offset,
+            moduleRefLimit: input.module_ref_limit,
+            importOffset: input.import_offset,
+            importLimit: input.import_limit,
+            implementationOffset: input.implementation_offset,
+            implementationLimit: input.implementation_limit,
+            maxMetadataBytes: input.max_metadata_bytes,
+            maxTableRows: input.max_table_rows,
+            maxHeapItemBytes: input.max_heap_item_bytes,
+        });
+    }
+    const input = managedMemberInputSchema.parse(parameters);
+    return inspectManagedMembersBytes(bytes, target, {
+        typeOffset: input.type_offset,
+        typeLimit: input.type_limit,
+        methodOffset: input.method_offset,
+        methodLimit: input.method_limit,
+        fieldOffset: input.field_offset,
+        fieldLimit: input.field_limit,
+        memberRefOffset: input.member_ref_offset,
+        memberRefLimit: input.member_ref_limit,
+        edgeOffset: input.edge_offset,
+        edgeLimit: input.edge_limit,
+        instructionAnchorLimit: input.instruction_anchor_limit,
+        maxMetadataBytes: input.max_metadata_bytes,
+        maxTableRows: input.max_table_rows,
+        maxHeapItemBytes: input.max_heap_item_bytes,
+        maxMethodBodyBytes: input.max_method_body_bytes,
+        maxMethodInstructions: input.max_method_instructions,
+    });
+};
+const managedLocations = (result) => {
+    if ("pe" in result) {
+        if (result.pe.cli === null)
+            return [{ kind: "file-offset", offset: 0 }];
+        return [
+            {
+                kind: "file-offset-range",
+                start: result.pe.cli.header_offset,
+                end: result.pe.cli.header_offset + result.pe.cli.header_size,
+            },
+            ...[result.module, result.assembly]
+                .filter((value) => value !== null)
+                .map((value) => ({
+                kind: "file-offset",
+                offset: value.row_offset,
+            })),
+        ];
+    }
+    if ("methods" in result)
+        return [
+            ...(result.module === null
+                ? [{ kind: "file-offset", offset: 0 }]
+                : [{ kind: "file-offset", offset: result.module.row_offset }]),
+            ...result.methods.items
+                .filter((method) => method.body.file_offset !== null)
+                .slice(0, 8)
+                .map((method) => ({
+                kind: "file-offset",
+                offset: method.body.file_offset ?? 0,
+            })),
+        ];
+    return [
+        ...(result.module === null
+            ? [{ kind: "file-offset", offset: 0 }]
+            : [{ kind: "file-offset", offset: result.module.row_offset }]),
+        ...result.pinvoke_imports.items.slice(0, 8).map((mapping) => ({
+            kind: "file-offset",
+            offset: mapping.row_offset,
+        })),
+    ];
+};

package/dist/generatedPackageMetadata.js

@@ -1,9 +1,9 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "1.6.0",
+    version: "2.0.0",
     serverSdkVersion: "2.0.0-beta.4",
     clientSdkVersion: "2.0.0-beta.4",
     coreSdkVersion: "2.0.0-beta.4",
-    skillVersion: "14",
+    skillVersion: "20",
 };

package/dist/ghidra/GhidraAnalysisProfile.js

@@ -0,0 +1,37 @@
+import { createAnalysisProfile } from "../domain/analysisProfile.js";
+import { AnalysisCancelledError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { GHIDRA_ANALYSIS_TIMEOUT_SECONDS, GHIDRA_MAX_CPU, GHIDRA_MAX_HEAP, } from "./GhidraDefaults.js";
+/** Resolve version-bound, deterministic semantics before Ghidra imports a target. */
+export const resolveGhidraAnalysisProfile = (target, identity, installation, signal) => {
+    if (signal?.aborted === true)
+        return Promise.resolve(err(new AnalysisCancelledError("open_binary")));
+    if (target.kind !== "executable")
+        return Promise.resolve(ok({ profile: null, compatibility: {} }));
+    const version = installation.providerVersion;
+    if (!installation.available || version === null)
+        return Promise.resolve(err(new ProviderAdapterError(identity.id, "resolve_analysis_profile")));
+    const provider = { ...identity, version };
+    return Promise.resolve(ok({
+        profile: createAnalysisProfile(provider, 1, {
+            target_kind: target.kind,
+            target_format: target.format,
+            architecture: target.architecture ?? null,
+            available_architectures: [
+                ...(target.availableArchitectures ?? []),
+            ].sort(),
+            import_mode: "ephemeral-read-only",
+            loader: "auto-from-header",
+            language_id: "auto-from-header",
+            compiler_spec_id: "auto-default",
+            analyzer_preset: "ghidra-default",
+            analysis_timeout_seconds: GHIDRA_ANALYSIS_TIMEOUT_SECONDS,
+            max_cpu: GHIDRA_MAX_CPU,
+            max_heap: GHIDRA_MAX_HEAP,
+        }),
+        compatibility: {
+            languageId: "auto",
+            compilerSpecId: "auto",
+        },
+    }));
+};

package/dist/ghidra/GhidraClient.js

@@ -0,0 +1,400 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { err, ok } from "../domain/result.js";
+import { silentLogger } from "../logger.js";
+import { PendingOperations } from "../process/PendingOperations.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
+import { GHIDRA_MAX_LINE_BYTES, GHIDRA_MAX_QUEUED_REQUESTS, GHIDRA_REQUEST_TIMEOUT_MS, GHIDRA_STARTUP_TIMEOUT_MS, } from "./GhidraDefaults.js";
+import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
+import { GhidraResponseBuffer } from "./GhidraResponseBuffer.js";
+import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
+import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
+import { bindGhidraSessionFailure, GhidraSessionError, } from "./GhidraSessionError.js";
+import { isGhidraShutdownAcknowledgement, parseGhidraSessionInfo, } from "./GhidraSessionValues.js";
+import { attachGhidraSocket, connectGhidraSocketOnce, } from "./GhidraSocketConnection.js";
+const SHUTDOWN_TIMEOUT_MS = 10_000;
+const SESSION_ROOT = "/tmp";
+/** Owns one authenticated, private, read-only Ghidra headless session. */
+export class GhidraClient {
+    #options;
+    #pending = new PendingOperations();
+    #logger;
+    #socket;
+    #detachSocket;
+    #launch;
+    #process;
+    #runtimeRoot;
+    #token;
+    #runId;
+    #nextId = 1;
+    #closing = false;
+    #processSnapshot;
+    #lastDiagnostics = {};
+    #startupController;
+    #startPromise;
+    #closePromise;
+    #failure = bindGhidraSessionFailure(() => this.#diagnostics());
+    #requestQueue;
+    #responseRouter = new GhidraResponseRouter({
+        pending: this.#pending,
+        nextId: () => this.#nextId,
+        remoteFailure: (failure) => this.#failure("remote", failure.message, failure, {
+            remoteCode: failure.code,
+        }),
+        protocolFailure: (message, cause) => this.#abortProtocol(message, cause),
+    });
+    #responseBuffer = new GhidraResponseBuffer({
+        maxLineBytes: GHIDRA_MAX_LINE_BYTES,
+        onLine: (line) => this.#responseRouter.route(line),
+        onFailure: (message) => this.#abortProtocol(message),
+    });
+    #onSocketData = (chunk) => this.#responseBuffer.push(chunk);
+    #onSocketError = () => {
+        this.#failAll(this.#failure("process", "Ghidra bridge socket failed"));
+    };
+    #onSocketClose = () => {
+        if (!this.#closing)
+            this.#failAll(this.#failure("process", "Ghidra bridge socket closed"));
+    };
+    constructor(options) {
+        this.#logger = options.logger ?? silentLogger;
+        this.#options = {
+            ...options,
+            requestTimeoutMs: options.requestTimeoutMs ?? GHIDRA_REQUEST_TIMEOUT_MS,
+            startupTimeoutMs: options.startupTimeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS,
+        };
+        this.#requestQueue = new GhidraRequestQueue(GHIDRA_MAX_QUEUED_REQUESTS, (method, parameters, requestOptions) => this.#request(method, parameters, requestOptions), (kind, message, timeoutMs) => this.#failure(kind, message, undefined, timeoutMs === undefined ? {} : { timeoutMs }));
+    }
+    /** Launch Ghidra once and require its exact post-analysis handshake. */
+    start(signal) {
+        if (this.#closePromise !== undefined)
+            return this.#closePromise.then(() => this.start(signal));
+        if (this.#startPromise !== undefined)
+            return this.#startPromise;
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(signal?.reason);
+        if (signal?.aborted === true)
+            onAbort();
+        else
+            signal?.addEventListener("abort", onAbort, { once: true });
+        const started = this.#start(controller.signal);
+        this.#startupController = controller;
+        this.#startPromise = started;
+        const reset = () => {
+            signal?.removeEventListener("abort", onAbort);
+            if (this.#startPromise === started) {
+                this.#startPromise = undefined;
+                if (this.#startupController === controller)
+                    this.#startupController = undefined;
+            }
+        };
+        void started.then((result) => {
+            signal?.removeEventListener("abort", onAbort);
+            if (!result.ok)
+                reset();
+        }, reset);
+        return started;
+    }
+    /** Revalidate live bridge, provider, run, and profile metadata. */
+    async ping(options = {}) {
+        const started = await this.start(options.signal);
+        if (!started.ok)
+            return started;
+        const result = await this.#request("ping", {}, options);
+        if (!result.ok)
+            return result;
+        return this.#parseSessionInfo(result.value);
+    }
+    /** Execute one admitted operation through the bounded per-Program queue. */
+    async callTool(operation, parameters, options = {}) {
+        const started = await this.start(options.signal);
+        if (!started.ok)
+            return started;
+        return this.#requestQueue.run(operation, parameters, {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            timeoutMs: options.timeoutMs ?? this.#options.requestTimeoutMs,
+        });
+    }
+    /** Stop the owned process group and remove all project/runtime artifacts. */
+    close() {
+        const starting = this.#startPromise;
+        const controller = this.#startupController;
+        controller?.abort();
+        this.#closePromise ??= Promise.resolve().then(() => this.#close(starting, controller));
+        return this.#closePromise;
+    }
+    /** Latest bounded local diagnostics, with bearer material redacted. */
+    diagnostics() {
+        return structuredClone(this.#diagnostics());
+    }
+    async #start(signal) {
+        if (signal.aborted)
+            return err(this.#failure("cancelled", "Ghidra startup was cancelled"));
+        if (this.#socket !== undefined || this.#runtimeRoot !== undefined)
+            return err(this.#failure("protocol", "Ghidra client is already started"));
+        const deadline = new ProviderStartupDeadline(this.#options.startupTimeoutMs, signal);
+        try {
+            return await this.#startWithin(deadline);
+        }
+        finally {
+            deadline.dispose();
+        }
+    }
+    async #startWithin(deadline) {
+        try {
+            this.#runtimeRoot = await PrivateRuntimeRoot.create({
+                parent: SESSION_ROOT,
+                prefix: "rea-ghidra-",
+            });
+        }
+        catch (cause) {
+            return err(this.#failure("start", "Ghidra runtime root creation failed", cause));
+        }
+        if (deadline.signal.aborted)
+            return this.#startupInterrupted(deadline);
+        const socketPath = join(this.#runtimeRoot.path, "bridge.sock");
+        this.#token = randomBytes(32).toString("hex");
+        this.#runId = randomUUID();
+        const launched = await this.#options.launcher
+            .launch({
+            runtimeRoot: this.#runtimeRoot.path,
+            socketPath,
+            token: this.#token,
+            runId: this.#runId,
+            targetPath: this.#options.targetPath,
+            providerVersion: this.#options.providerVersion,
+            profileDigest: this.#options.profileDigest,
+        }, { signal: deadline.signal })
+            .catch((cause) => err(this.#failure("start", "Ghidra launcher failed", cause)));
+        if (!launched.ok) {
+            const failure = deadline.signal.aborted
+                ? this.#interruptionFailure(deadline)
+                : launched.error instanceof GhidraSessionError
+                    ? launched.error
+                    : this.#failure("start", launched.error.message, launched.error);
+            await this.#cleanup();
+            return err(failure);
+        }
+        this.#launch = launched.value;
+        this.#process = new ProviderProcessSupervisor(launched.value, {
+            onDiagnostic: (event) => this.#onProcessDiagnostic(event),
+        });
+        const connected = await this.#connect(socketPath, deadline);
+        if (!connected.ok) {
+            const failure = connected.error;
+            await this.#cleanup();
+            return err(failure);
+        }
+        const ping = await this.#request("ping", {}, {
+            signal: deadline.signal,
+            timeoutMs: deadline.remainingMs(),
+        });
+        if (!ping.ok) {
+            const failure = deadline.signal.aborted
+                ? this.#interruptionFailure(deadline)
+                : ping.error;
+            await this.#cleanup();
+            return err(failure);
+        }
+        const parsed = this.#parseSessionInfo(ping.value);
+        if (!parsed.ok || parsed.value.analysis_timed_out) {
+            const failure = parsed.ok
+                ? this.#failure("analysis_timeout", "Ghidra auto-analysis reached its per-file deadline")
+                : parsed.error;
+            await this.#cleanup();
+            return err(failure);
+        }
+        return parsed;
+    }
+    async #connect(socketPath, deadline) {
+        while (deadline.remainingMs() > 0) {
+            if (deadline.signal.aborted)
+                return err(this.#interruptionFailure(deadline));
+            if (this.#closing)
+                return err(this.#failure("cancelled", "Ghidra startup was closed"));
+            if (this.#processSnapshot?.exitCode !== undefined)
+                return err(this.#failure("process", "Ghidra exited before bridge startup"));
+            try {
+                await access(socketPath);
+            }
+            catch {
+                if ((await deadline.wait(50)) === "aborted")
+                    return err(this.#interruptionFailure(deadline));
+                continue;
+            }
+            const connected = await connectGhidraSocketOnce(socketPath, deadline.signal);
+            if (connected.ok) {
+                this.#socket = connected.value;
+                this.#detachSocket = attachGhidraSocket(connected.value, {
+                    data: this.#onSocketData,
+                    error: this.#onSocketError,
+                    close: this.#onSocketClose,
+                });
+                return ok(undefined);
+            }
+            if ((await deadline.wait(50)) === "aborted")
+                return err(this.#interruptionFailure(deadline));
+        }
+        return err(this.#failure("timeout", "Ghidra startup deadline elapsed", undefined, {
+            timeoutMs: this.#options.startupTimeoutMs,
+        }));
+    }
+    async #request(method, params, options) {
+        const socket = this.#socket;
+        const token = this.#token;
+        if (socket === undefined || socket.destroyed || token === undefined)
+            return err(this.#failure("process", "Ghidra bridge is unavailable"));
+        if (options.signal?.aborted === true)
+            return err(this.#failure("cancelled", "Ghidra request was cancelled"));
+        const id = this.#nextId++;
+        const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs;
+        if (timeoutMs <= 0)
+            return err(this.#failure("timeout", "Ghidra request deadline elapsed", undefined, {
+                timeoutMs,
+            }));
+        const response = this.#pending.wait(id, {
+            timeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            timeoutValue: () => err(this.#failure("timeout", "Ghidra bridge request timed out", undefined, { timeoutMs })),
+            cancelledValue: () => err(this.#failure("cancelled", "Ghidra request was cancelled")),
+        });
+        socket.write(`${JSON.stringify({ id, token, method, params })}\n`, (cause) => {
+            if (cause !== undefined && cause !== null)
+                this.#pending.settle(id, err(this.#failure("process", "Ghidra bridge write failed", cause)));
+        });
+        const result = await response;
+        this.#logger[result.ok ? "debug" : "warn"]({ method, status: result.ok ? "ok" : "error" }, "Ghidra bridge request completed");
+        return result;
+    }
+    #parseSessionInfo(value) {
+        const runId = this.#runId;
+        if (runId === undefined)
+            return err(this.#failure("protocol", "Ghidra run identity is missing"));
+        const parsed = parseGhidraSessionInfo(value, {
+            runId,
+            providerVersion: this.#options.providerVersion,
+            profileDigest: this.#options.profileDigest,
+        });
+        if (parsed.ok)
+            return parsed;
+        return err(this.#failure("protocol", "Ghidra bridge handshake is invalid", parsed.error));
+    }
+    async #close(starting, controller) {
+        try {
+            await starting?.catch(() => undefined);
+            await this.#cleanup();
+        }
+        finally {
+            if (this.#startPromise === starting)
+                this.#startPromise = undefined;
+            if (this.#startupController === controller)
+                this.#startupController = undefined;
+            this.#closePromise = undefined;
+        }
+    }
+    async #cleanup() {
+        this.#closing = true;
+        try {
+            this.#requestQueue.failQueued(this.#failure("process", "Ghidra session closed"));
+            const socket = this.#socket;
+            if (socket !== undefined && !socket.destroyed) {
+                const shutdown = await this.#request("shutdown", {}, {
+                    timeoutMs: SHUTDOWN_TIMEOUT_MS,
+                }).catch(() => err(this.#failure("process", "Ghidra shutdown request failed")));
+                if (!shutdown.ok || !isGhidraShutdownAcknowledgement(shutdown.value))
+                    this.#logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Ghidra bridge shutdown was not confirmed");
+            }
+            this.#failAll(this.#failure("process", "Ghidra session closed"));
+            this.#detachSocket?.();
+            this.#detachSocket = undefined;
+            socket?.destroy();
+            this.#socket = undefined;
+            if (this.#process !== undefined) {
+                await this.#process.waitForExit(500);
+                this.#processSnapshot = this.#process.snapshot();
+                const stopped = await this.#process.stop();
+                this.#processSnapshot = this.#process.snapshot();
+                if (stopped.status === "incomplete") {
+                    this.#options.onDiagnostic?.({
+                        type: "cleanup-incomplete",
+                        reason: stopped.reason,
+                    });
+                    this.#logger.warn({ reason: stopped.reason }, "Ghidra process cleanup failed closed");
+                }
+            }
+            this.#lastDiagnostics = this.#diagnostics();
+            this.#process = undefined;
+            this.#launch = undefined;
+            const runtimeRoot = this.#runtimeRoot;
+            this.#runtimeRoot = undefined;
+            await runtimeRoot?.close();
+            this.#token = undefined;
+            this.#runId = undefined;
+            this.#responseBuffer.reset();
+        }
+        finally {
+            this.#closing = false;
+        }
+    }
+    #onProcessDiagnostic(event) {
+        if (event.type === "output") {
+            this.#options.onDiagnostic?.({
+                type: "launcher-output",
+                stream: event.stream,
+                bytes: event.bytes,
+                totalBytes: event.totalBytes,
+                truncated: event.truncated,
+            });
+            return;
+        }
+        if (event.type === "error") {
+            this.#logger.warn({ message: event.message }, "Ghidra process emitted an error");
+            return;
+        }
+        this.#processSnapshot = event.snapshot;
+        this.#options.onDiagnostic?.({
+            type: "launcher-exit",
+            code: event.code,
+            signal: event.signal,
+        });
+        if (!this.#closing)
+            this.#failAll(this.#failure("process", "Ghidra process exited"));
+    }
+    #abortProtocol(message, cause) {
+        this.#failAll(this.#failure("protocol", message, cause));
+        this.#socket?.destroy();
+    }
+    #failAll(error) {
+        this.#pending.failAll(() => err(error));
+    }
+    async #startupInterrupted(deadline) {
+        const failure = this.#interruptionFailure(deadline);
+        await this.#cleanup();
+        return err(failure);
+    }
+    #interruptionFailure(deadline) {
+        return deadline.cancelled
+            ? this.#failure("cancelled", "Ghidra startup was cancelled")
+            : this.#failure("timeout", "Ghidra startup deadline elapsed", undefined, {
+                timeoutMs: deadline.timeoutMs,
+            });
+    }
+    #diagnostics() {
+        const snapshot = this.#process?.snapshot() ?? this.#processSnapshot;
+        return createGhidraDiagnostics({
+            targetPath: this.#options.targetPath,
+            providerVersion: this.#options.providerVersion,
+            profileDigest: this.#options.profileDigest,
+            ...(this.#runtimeRoot === undefined
+                ? {}
+                : { runtimeRoot: this.#runtimeRoot.path }),
+            ...(this.#launch === undefined ? {} : { launch: this.#launch }),
+            ...(snapshot === undefined ? {} : { snapshot }),
+            ...(this.#token === undefined ? {} : { token: this.#token }),
+            previous: this.#lastDiagnostics,
+        });
+    }
+}

package/dist/ghidra/GhidraClientTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/ghidra/GhidraDefaults.js

@@ -0,0 +1,20 @@
+/** Maximum wall-clock analysis time passed to Ghidra for one imported file. */
+export const GHIDRA_ANALYSIS_TIMEOUT_SECONDS = 300;
+/** Maximum CPU cores made available to one headless analysis. */
+export const GHIDRA_MAX_CPU = 2;
+/** Explicit JVM heap ceiling for one headless provider process. */
+export const GHIDRA_MAX_HEAP = "2G";
+/** Absolute import, analysis, bridge, and health startup deadline. */
+export const GHIDRA_STARTUP_TIMEOUT_MS = 330_000;
+/** Default bounded wait for one established bridge request. */
+export const GHIDRA_REQUEST_TIMEOUT_MS = 10_000;
+/** Per-function ceiling passed to Ghidra's native decompiler process. */
+export const GHIDRA_DECOMPILE_TIMEOUT_SECONDS = 30;
+/** Socket deadline leaves bounded time to project a native decompiler timeout. */
+export const GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS = 35_000;
+/** Maximum active plus queued calls for one serial headless Program. */
+export const GHIDRA_MAX_QUEUED_REQUESTS = 32;
+/** Maximum encoded response line accepted from the Java bridge. */
+export const GHIDRA_MAX_LINE_BYTES = 1024 * 1024;
+/** Version of REA's Java bridge handshake and request protocol. */
+export const GHIDRA_BRIDGE_VERSION = 3;