rea-agents 4.0.0 → 4.1.0

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: "4.0.0", // x-release-please-version
-    serverSdkVersion: "2.0.0",
-    clientSdkVersion: "2.0.0",
-    coreSdkVersion: "2.0.0",
-    skillVersion: "24",
+    version: "4.1.0", // x-release-please-version
+    serverSdkVersion: "2.3.1",
+    clientSdkVersion: "2.3.1",
+    coreSdkVersion: "2.3.1",
+    skillVersion: "26",
 };

package/dist/ghidra/GhidraAnalysisProfile.js

@@ -1,5 +1,7 @@
 import { createAnalysisProfile } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError, ProviderAdapterError, } from "../domain/errors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
 /** Resolve version-bound, deterministic semantics before Ghidra imports a target. */
 export const resolveGhidraAnalysisProfile = (target, identity, installation, signal) => {
@@ -11,6 +13,8 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
         return Promise.resolve(err(new ProviderAdapterError(identity.id, "resolve_analysis_profile")));
     const provider = { ...identity, version: installation.providerVersion };
     const dosMz = target.format === "dos-mz";
+    const dosCom = target.format === "dos-com";
+    const dos = dosMz || dosCom;
     return Promise.resolve(ok({
         profile: createAnalysisProfile(provider, {
             target_kind: target.kind,
@@ -19,24 +23,49 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
             available_architectures: [
                 ...(target.availableArchitectures ?? []),
             ].sort(),
-            import_mode: "ephemeral-read-only",
+            import_mode: "ephemeral-source-immutable",
+            annotation_policy: "atomic-function-entry-metadata-v1",
+            load_image_observations: "source-mappings-entry-context-v2",
             function_body_evidence: "complete-inclusive-ranges-v1",
+            ...(dos
+                ? {
+                    load_image_evidence: dosCom
+                        ? "independent-com-mapping-context-v1"
+                        : "independent-mz-mapping-relocations-v1",
+                }
+                : {}),
             jump_table_evidence: "typed-case-default-blocks-v1",
             decompiler_jump_loads: true,
-            loader: dosMz ? "MzLoader" : "auto-from-header",
-            language_id: dosMz ? "x86:LE:16:Real Mode" : "auto-from-header",
-            compiler_spec_id: dosMz ? "default" : "auto-default",
-            ...(dosMz
+            loader: dosMz
+                ? "MzLoader"
+                : dosCom
+                    ? "BinaryLoader"
+                    : "auto-from-header",
+            language_id: dos ? "x86:LE:16:Real Mode" : "auto-from-header",
+            compiler_spec_id: dos ? "default" : "auto-default",
+            ...(dos
                 ? {
                     load_segment: "0x1000",
                     address_coordinates: "linear-byte-offset",
                 }
                 : {}),
+            ...(dosCom
+                ? {
+                    entry_offset: "0x100",
+                    register_context: {
+                        CS: "0x1000",
+                        DS: "0x1000",
+                        ES: "0x1000",
+                        SS: "0x1000",
+                    },
+                    entry_seed: "external-entry-and-function-before-analysis-v1",
+                }
+                : {}),
             analyzer_preset: "ghidra-default",
         }),
         compatibility: {
-            languageId: dosMz ? "x86:LE:16:Real Mode" : "auto",
-            compilerSpecId: dosMz ? "default" : "auto",
+            languageId: dos ? "x86:LE:16:Real Mode" : "auto",
+            compilerSpecId: dos ? "default" : "auto",
         },
     }));
 };

package/dist/ghidra/GhidraClient.js

@@ -16,12 +16,13 @@ import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
 import { bindGhidraSessionFailure, GhidraSessionError, } from "./GhidraSessionError.js";
 import { isGhidraShutdownAcknowledgement, parseGhidraSessionInfo, } from "./GhidraSessionValues.js";
 import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
+import { readFile } from "node:fs/promises";
 import { connectGhidraSocket } from "./GhidraSocketConnection.js";
 import { GhidraWire } from "./GhidraClientWire.js";
 import { completeGhidraStartupHandshake } from "./GhidraClientStartup.js";
 const SHUTDOWN_TIMEOUT_MS = 10_000;
 const SESSION_ROOT = tmpdir();
-/** Owns one authenticated, private, read-only Ghidra headless session. */
+/** Owns an authenticated private Ghidra session with transport-bound mutation authority. */
 export class GhidraClient {
     #options;
     #logger;
@@ -32,7 +33,10 @@ export class GhidraClient {
     #process;
     #runtimeRoot;
     #snapshotPath;
+    #targetAdmission;
     #token;
+    // Retain authentication identities for diagnostics from late request settlement.
+    #authenticationTokens = new Set();
     #runId;
     #lineage = new ProviderRunLineage();
     #nextId = 1;
@@ -42,7 +46,7 @@ export class GhidraClient {
     #startupController;
     #startPromise;
     #closePromise;
-    #failure = bindGhidraSessionFailure(() => this.#diagnostics());
+    #failure = bindGhidraSessionFailure(() => this.#diagnostics(), (value) => this.#redactAuthentication(value));
     #wire;
     #requestQueue;
     #responseRouter = new GhidraResponseRouter({
@@ -68,6 +72,7 @@ export class GhidraClient {
         this.#options = {
             ...options,
             startupTimeoutMs: options.startupTimeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS,
+            platform: options.platform ?? process.platform,
             transport: options.transport ?? "unix-socket",
         };
         this.#logger = options.logger ?? silentLogger;
@@ -108,7 +113,10 @@ export class GhidraClient {
             signal?.removeEventListener("abort", onAbort);
             if (!result.ok)
                 reset();
-        }, reset);
+        }, (cause) => {
+            this.#logger.debug({ error: cause instanceof Error ? cause.message : String(cause) }, "Ghidra startup promise rejected during bookkeeping");
+            reset();
+        });
         return started;
     }
     /** Revalidate live bridge, provider, run, and profile metadata. */
@@ -128,6 +136,17 @@ export class GhidraClient {
             return started;
         return this.#requestQueue.run(operation, parameters, options.signal === undefined ? {} : { signal: options.signal });
     }
+    /** Read the private immutable source for independent import verification. */
+    async readTargetSnapshot() {
+        if (this.#snapshotPath === undefined)
+            return err(this.#failure("protocol", "Ghidra target snapshot is unavailable before startup or after close"));
+        try {
+            return ok(await readFile(this.#snapshotPath));
+        }
+        catch (cause) {
+            return err(this.#failure("protocol", "Ghidra target snapshot could not be read for load-image verification", cause));
+        }
+    }
     /** Stop the owned process group and remove all project/runtime artifacts. */
     close() {
         return this.#requestClose(false);
@@ -171,6 +190,7 @@ export class GhidraClient {
             this.#runtimeRoot = await PrivateRuntimeRoot.create({
                 parent: SESSION_ROOT,
                 prefix: "rea-ghidra-",
+                platform: this.#options.platform,
             });
         }
         catch (cause) {
@@ -185,10 +205,13 @@ export class GhidraClient {
                 : "bridge-endpoint.json"),
         };
         try {
-            const snapshot = await createGhidraTargetSnapshot(this.#options.targetPath, this.#runtimeRoot.path, this.#options.targetSha256);
+            const snapshot = await createGhidraTargetSnapshot(this.#options.targetPath, this.#runtimeRoot.path, this.#options.targetSha256, { signal: deadline.signal, platform: this.#options.platform });
             this.#snapshotPath = snapshot.path;
+            this.#targetAdmission = snapshot.admission;
         }
         catch (cause) {
+            if (deadline.signal.aborted)
+                return this.#startupInterrupted(deadline);
             const failure = this.#failure("start", "Ghidra target snapshot failed admission", cause);
             await this.#cleanup();
             return err(failure);
@@ -196,6 +219,7 @@ export class GhidraClient {
         if (deadline.signal.aborted)
             return this.#startupInterrupted(deadline);
         this.#token = randomBytes(32).toString("hex");
+        this.#authenticationTokens.add(this.#token);
         this.#lineage.reset();
         this.#runId = this.#options.runId ?? randomUUID();
         const launched = await this.#options.launcher
@@ -270,9 +294,13 @@ export class GhidraClient {
             return err(this.#failure("protocol", "Ghidra run identity is missing"));
         const parsed = parseGhidraSessionInfo(value, {
             runId,
+            expectedReadOnly: this.#options.transport === "authenticated-loopback-tcp",
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
             targetSha256: this.#options.targetSha256,
+            ...(this.#targetAdmission === undefined
+                ? {}
+                : { targetAdmission: this.#targetAdmission }),
             ...(this.#options.expectedLanguageId === undefined
                 ? {}
                 : { expectedLanguageId: this.#options.expectedLanguageId }),
@@ -286,6 +314,7 @@ export class GhidraClient {
     }
     async #close(starting, controller, forceStop) {
         try {
+            // best-effort cleanup: a rejected startup must not mask close/cleanup.
             await starting?.catch(() => undefined);
             await this.#cleanup(forceStop);
         }
@@ -306,9 +335,18 @@ export class GhidraClient {
             if (!forceStop && socket !== undefined && !socket.destroyed) {
                 const shutdown = await this.#wire
                     .request("shutdown", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS })
-                    .catch(() => err(this.#failure("process", "Ghidra shutdown request failed")));
+                    .catch((cause) => err(this.#failure("process", "Ghidra shutdown request failed", cause)));
                 if (!shutdown.ok || !isGhidraShutdownAcknowledgement(shutdown.value))
-                    this.#logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Ghidra bridge shutdown was not confirmed");
+                    this.#logger.warn({
+                        status: shutdown.ok ? "invalid-acknowledgement" : "failed",
+                        ...(shutdown.ok
+                            ? {}
+                            : {
+                                kind: shutdown.error.kind,
+                                message: shutdown.error.message,
+                                diagnostics: shutdown.error.diagnostics,
+                            }),
+                    }, "Ghidra bridge shutdown was not confirmed");
             }
             this.#failAll(this.#failure("process", "Ghidra session closed"));
             this.#detachSocket?.();
@@ -355,6 +393,11 @@ export class GhidraClient {
             this.#closing = false;
         }
     }
+    #redactAuthentication(value) {
+        for (const token of this.#authenticationTokens)
+            value = value.replaceAll(token, "[REDACTED]");
+        return value;
+    }
     #onProcessDiagnostic(event) {
         if (event.type === "output") {
             this.#options.onDiagnostic?.({
@@ -402,6 +445,9 @@ export class GhidraClient {
         return createGhidraDiagnostics({
             targetPath: this.#options.targetPath,
             targetSha256: this.#options.targetSha256,
+            ...(this.#targetAdmission === undefined
+                ? {}
+                : { targetAdmission: this.#targetAdmission }),
             transport: this.#options.transport,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,

package/dist/ghidra/GhidraDiagnostics.js

@@ -11,6 +11,9 @@ export const createGhidraDiagnostics = (options) => {
     return {
         target_path: options.targetPath,
         target_sha256: options.targetSha256,
+        ...(options.targetAdmission === undefined
+            ? {}
+            : { target_admission: options.targetAdmission }),
         transport: options.transport,
         provider_version: options.providerVersion,
         profile_digest: options.profileDigest,

package/dist/ghidra/GhidraDoctor.js

@@ -1,18 +1,42 @@
+import { hasWindowsNativeAuthority, windowsNativeAuthorityUnavailableReason, } from "../process/WindowsAuthority.js";
 import { inspectGhidraInstallation, } from "./GhidraInstallation.js";
-/** Project adapter-owned installation facts into the generic doctor contract. */
-export const projectGhidraDoctorInspection = (inspection) => ({
-    id: "ghidra",
-    configured: inspection.installDir !== null,
-    available: inspection.status === "available",
-    providerVersion: inspection.providerVersion,
-    registrationEnvironment: inspection.status === "available"
-        ? {
-            GHIDRA_INSTALL_DIR: inspection.installDir,
-            JAVA_HOME: inspection.javaHome,
-        }
-        : {},
-    checks: selectedChecks(inspection).map((check) => projectCheck(check, inspection.installDir !== null)),
-});
+/** Project installation and runtime-authority facts into the doctor contract. */
+export const projectGhidraDoctorInspection = (inspection) => {
+    const windowsAuthorityUnavailable = inspection.status === "available" &&
+        inspection.platform === "win32" &&
+        !hasWindowsNativeAuthority(inspection.platform);
+    return {
+        id: "ghidra",
+        configured: inspection.installDir !== null,
+        available: inspection.status === "available" && !windowsAuthorityUnavailable,
+        providerVersion: inspection.providerVersion,
+        registrationEnvironment: inspection.status === "available"
+            ? {
+                GHIDRA_INSTALL_DIR: inspection.installDir,
+                JAVA_HOME: inspection.javaHome,
+            }
+            : {},
+        checks: [
+            ...selectedChecks(inspection).map((check) => projectCheck(check, inspection.installDir !== null)),
+            ...(inspection.status === "available" && inspection.platform === "win32"
+                ? [
+                    {
+                        name: "native_authority",
+                        ok: !windowsAuthorityUnavailable,
+                        code: windowsAuthorityUnavailable ? "unsupported_host" : null,
+                        detail: windowsAuthorityUnavailable
+                            ? windowsNativeAuthorityUnavailableReason(inspection.platform)
+                            : "Verified Windows native Job Object, private DACL, and reparse-safe handle controls; local NTFS only.",
+                        remediation: windowsAuthorityUnavailable
+                            ? "Use the matching Windows x64 REA package with its bundled native addon and a writable local NTFS temporary directory. The native failure above identifies the failed constraint; Ghidra installation or registration changes cannot enable a missing native backend."
+                            : null,
+                        classification: "unsupported_host",
+                    },
+                ]
+                : []),
+        ],
+    };
+};
 /** Inspect the process-configured BYO Ghidra installation for `rea doctor`. */
 export const inspectSystemGhidraProvider = () => Promise.resolve(projectGhidraDoctorInspection(inspectGhidraInstallation({
     ...(process.env.GHIDRA_INSTALL_DIR === undefined

package/dist/ghidra/GhidraFunctionValues.js

@@ -1,15 +1,17 @@
 import { z } from "zod";
+import { nativeFunctionAnnotationsInputSchema, nativeFunctionAnnotationsSchema, } from "../domain/nativeFunctionAnnotations.js";
 import { nativeDataTypeSchema } from "../domain/nativeDataType.js";
 import { nativeInstructionSchema, nativeCallTargetsSchema, } from "../domain/nativeInstruction.js";
-import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
+import { AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { functionBodyEntryAgrees, functionInstructionWindowSchema, functionDossierSchema, } from "../domain/hopperValues.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
 import { nativeApiBoundarySchema } from "../domain/nativeApiBoundary.js";
 import { nativeValueFlowSchema } from "../domain/nativeValueFlow.js";
 import { err, ok } from "../domain/result.js";
 import { ghidraIdentifierSchema, ghidraCanonicalAddressSchema, ghidraFunctionClassificationSchema as classification, ghidraFunctionBodySchema as ghidraFunctionBody, ghidraProcedureIdentitySchema as procedureIdentity, } from "./GhidraInventoryValues.js";
-/** Read-only function operations admitted by the Ghidra adapter. */
+/** Function analysis and annotation operations admitted by the Ghidra adapter. */
 export const GHIDRA_FUNCTION_OPERATIONS = [
+    "annotate_native_function",
     "inspect_native_data_type",
     "inspect_native_instruction",
     "resolve_native_call_targets",
@@ -30,6 +32,7 @@ const document = ghidraIdentifierSchema.nullable().default(null);
 const procedure = ghidraIdentifierSchema;
 const directProcedure = { document, procedure };
 const inputSchemas = {
+    annotate_native_function: nativeFunctionAnnotationsInputSchema,
     inspect_native_data_type: z
         .object({
         document,
@@ -265,6 +268,9 @@ const ghidraFunctionInstructionWindow = functionInstructionWindowSchema
     .extend({ procedure: procedureIdentity })
     .strict();
 const resultSchemas = {
+    annotate_native_function: nativeFunctionAnnotationsSchema.safeExtend({
+        dossier: ghidraFunctionDossier,
+    }),
     analyze_function: ghidraFunctionDossier,
     procedure_assembly: z.string(),
     procedure_callees: z.array(ghidraCanonicalAddressSchema),
@@ -282,7 +288,7 @@ const resultSchemas = {
 export const parseGhidraFunctionResult = (operation, value) => {
     const parsed = resultSchemas[operation].safeParse(value);
     return parsed.success
-        ? ok(parsed.data)
+        ? ok(jsonValueSchema.parse(parsed.data))
         : err(new AnalysisOutputError(operation, "Ghidra bridge output did not match the function-analysis contract", { cause: parsed.error }));
 };
 const referenceAddresses = (edge) => [

package/dist/ghidra/GhidraInstallation.js

@@ -245,7 +245,9 @@ const systemGhidraInstallationHost = () => ({
         try {
             return readFileSync(path, "utf8");
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: optional install probing; unreadable means unknown.
+            void cause;
             return undefined;
         }
     },
@@ -254,12 +256,14 @@ const systemGhidraInstallationHost = () => ({
             accessSync(path, constants.X_OK);
             return true;
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: optional executable probing; failure means missing.
+            void cause;
             return false;
         }
     },
     probeJava(command, environment) {
-        const observed = spawnSync(command, ["-XshowSettings:properties", "-version"], {
+        const observed = spawnSync(command, ["-XX:-UsePerfData", "-XshowSettings:properties", "-version"], {
             encoding: "utf8",
             env: environment,
             timeout: 5_000,
@@ -290,7 +294,9 @@ const executablePath = (path) => {
         accessSync(path, constants.X_OK);
         return true;
     }
-    catch {
+    catch (cause) {
+        // best-effort cleanup: optional executable probing; failure means missing.
+        void cause;
         return false;
     }
 };

package/dist/ghidra/GhidraInventoryValues.js

@@ -1,9 +1,14 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
+import { nativeLoadImageObservationSchema } from "../domain/nativeLoadImage.js";
+import { AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { functionBodySchema, functionBodyEntryAgrees, } from "../domain/hopperValues.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 /** Read-only direct inventory operations admitted by the Ghidra adapter. */
 export const GHIDRA_INVENTORY_OPERATIONS = [
+    "inspect_native_load_image",
+    "read_bytes",
+    "address_to_file_offset",
     "address_name",
     "list_documents",
     "list_names",
@@ -30,6 +35,16 @@ const searchInput = {
     document,
 };
 const inputSchemas = {
+    inspect_native_load_image: z.strictObject({}),
+    read_bytes: z.strictObject({
+        document,
+        address: explicitAddress,
+        length: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).default(256),
+    }),
+    address_to_file_offset: z.strictObject({
+        document,
+        address: explicitAddress,
+    }),
     address_name: z.object({ document, address: explicitAddress }).strict(),
     list_documents: z.object({}).strict(),
     list_names: z.object({ document, address: filteredAddress }).strict(),
@@ -173,6 +188,28 @@ const containingProcedure = z.discriminatedUnion("found", [
         .strict(),
 ]);
 const resultSchemas = {
+    inspect_native_load_image: nativeLoadImageObservationSchema,
+    read_bytes: z
+        .strictObject({
+        address: canonicalAddress,
+        requested_bytes: z.number().int().min(1),
+        returned_bytes: z.number().int().min(0),
+        bytes_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/u),
+        complete: z.boolean(),
+    })
+        .superRefine((value, context) => {
+        if (value.returned_bytes * 2 !== value.bytes_hex.length ||
+            value.returned_bytes > value.requested_bytes ||
+            value.complete !== (value.returned_bytes === value.requested_bytes))
+            context.addIssue({
+                code: "custom",
+                message: "Read-byte length and completeness disagree",
+            });
+    }),
+    address_to_file_offset: z.strictObject({
+        address: canonicalAddress,
+        file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    }),
     address_name: z.string().nullable(),
     list_documents: z.array(z.string().min(1)).length(1),
     list_names: z.array(symbolItem),
@@ -188,6 +225,6 @@ const resultSchemas = {
 export const parseGhidraInventoryResult = (operation, value) => {
     const parsed = resultSchemas[operation].safeParse(value);
     return parsed.success
-        ? ok(parsed.data)
+        ? ok(jsonValueSchema.parse(parsed.data))
         : err(new AnalysisOutputError(operation, "Ghidra bridge output did not match the inventory contract", { cause: parsed.error }));
 };