rea-agents 2.4.0 → 3.0.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: "2.4.0", // x-release-please-version
-    serverSdkVersion: "2.0.0-beta.4",
-    clientSdkVersion: "2.0.0-beta.4",
-    coreSdkVersion: "2.0.0-beta.4",
+    version: "3.0.0", // x-release-please-version
+    serverSdkVersion: "2.0.0",
+    clientSdkVersion: "2.0.0",
+    coreSdkVersion: "2.0.0",
     skillVersion: "23",
 };

package/dist/ghidra/GhidraDefaults.js

@@ -17,4 +17,4 @@ 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 = 4;
+export const GHIDRA_BRIDGE_VERSION = 6;

package/dist/ghidra/GhidraFunctionValues.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
-import { functionDossierSchema, } from "../domain/hopperValues.js";
+import { functionInstructionWindowSchema, functionDossierSchema, } from "../domain/hopperValues.js";
 import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
+import { nativeApiBoundarySchema } from "../domain/nativeApiBoundary.js";
 import { err, ok } from "../domain/result.js";
 import { ghidraBoundedIdentifierSchema, ghidraCanonicalAddressSchema, } from "./GhidraInventoryValues.js";
 /** Read-only function operations admitted by the Ghidra adapter. */
@@ -12,6 +13,7 @@ export const GHIDRA_FUNCTION_OPERATIONS = [
     "procedure_callers",
     "procedure_info",
     "procedure_pseudo_code",
+    "read_function_instructions",
     "procedure_references",
     "xrefs",
 ];
@@ -66,6 +68,13 @@ const inputSchemas = {
     procedure_callers: z.object(directProcedure).strict(),
     procedure_info: z.object(directProcedure).strict(),
     procedure_pseudo_code: z.object(directProcedure).strict(),
+    read_function_instructions: z
+        .object({
+        ...directProcedure,
+        offset: z.number().int().min(0).max(100_000).default(0),
+        limit: z.number().int().min(1).max(500).default(64),
+    })
+        .strict(),
     procedure_references: z
         .object({
         ...directProcedure,
@@ -183,7 +192,32 @@ const procedureInfo = z
     classification,
 })
     .strict();
-const ghidraFunctionDossier = functionDossierSchema.superRefine((value, context) => {
+const ghidraNativeApiBoundary = nativeApiBoundarySchema.superRefine((value, context) => {
+    if (!value.available)
+        return;
+    if (value.provenance !== "ghidra-high-function")
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra native API observations require HighFunction provenance",
+        });
+    const addresses = value.jump_tables.flatMap((table) => [
+        table.dispatch_address,
+        ...table.data_sources.map(({ address }) => address),
+        ...table.mappings.flatMap(({ target_address, data_addresses }) => [
+            target_address,
+            ...data_addresses,
+        ]),
+    ]);
+    if (addresses.some((address) => !ghidraCanonicalAddressSchema.safeParse(address).success))
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra native API observation contains a non-canonical address",
+        });
+});
+const ghidraFunctionDossier = functionDossierSchema
+    .extend({ native_api: ghidraNativeApiBoundary })
+    .strict()
+    .superRefine((value, context) => {
     const addresses = [
         value.procedure.address,
         ...value.comments.items.map(({ address }) => address),
@@ -235,6 +269,9 @@ const ghidraFunctionDossier = functionDossierSchema.superRefine((value, context)
             message: "Ghidra dossier omitted required uncertainty limitations",
         });
 });
+const ghidraFunctionInstructionWindow = functionInstructionWindowSchema
+    .extend({ procedure: procedureIdentity })
+    .strict();
 const resultSchemas = {
     analyze_function: ghidraFunctionDossier,
     procedure_assembly: z.string(),
@@ -242,6 +279,7 @@ const resultSchemas = {
     procedure_callers: z.array(ghidraCanonicalAddressSchema),
     procedure_info: procedureInfo,
     procedure_pseudo_code: z.string().nullable(),
+    read_function_instructions: ghidraFunctionInstructionWindow,
     procedure_references: procedureReferences,
     xrefs: z.array(ghidraCanonicalAddressSchema),
 };

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -1,4 +1,4 @@
-import { ENHANCED_TOOL_CONTRACTS, OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 import { GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS, GHIDRA_MAX_LINE_BYTES, GHIDRA_REQUEST_TIMEOUT_MS, } from "./GhidraDefaults.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
@@ -8,10 +8,7 @@ export const GHIDRA_PROVIDER_IDENTITY = Object.freeze({
     name: "Ghidra",
     version: null,
 });
-const providerContractByName = new Map([...OFFICIAL_TOOL_CONTRACTS, ...ENHANCED_TOOL_CONTRACTS].map((contract) => [
-    contract.name,
-    contract,
-]));
+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);
@@ -26,6 +23,7 @@ const PAGINATED_OPERATIONS = new Set([
     "search_procedures",
     "search_strings",
     "procedure_references",
+    "read_function_instructions",
     "analyze_function",
 ]);
 const SEARCH_OPERATIONS = new Set([
@@ -93,6 +91,12 @@ export const limitationsFor = (operation) => {
                 "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 "read_function_instructions":
+            return [
+                ...common,
+                "This bounded fast path reads only the requested function instruction window and does not invoke the decompiler or whole-program string/name inventories.",
+                "Instruction text is Ghidra-specific and does not claim textual equivalence with Hopper output.",
+            ];
         case "procedure_assembly":
             return [
                 ...common,
@@ -130,39 +134,44 @@ 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) => 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)),
-})));
+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}`);
+    return Object.freeze({
+        provider: GHIDRA_PROVIDER_IDENTITY,
+        operation,
+        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)),
+    });
+}));
 /** Capabilities advertised for the experimental Windows x64 P0 boundary. */
 export const WINDOWS_P0_CAPABILITIES = Object.freeze(CAPABILITIES.map((capability) => Object.freeze({
     ...capability,

package/dist/hopper/HopperCleanup.js

@@ -0,0 +1,158 @@
+import { HopperProcessError } from "../domain/errors.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { createOwnedHopperShutdownDiagnostic, providerCleanupFailure, } from "./HopperDiagnostics.js";
+import { isHopperCleanupRequired, isHopperShutdownAcknowledgement, } from "./HopperSessionValues.js";
+/** Close Hopper phases and retain every resource whose cleanup is unverified. */
+export const cleanupHopperSession = async (input) => {
+    const state = {
+        issues: [],
+        resources: new Set(),
+        cleanupResult: undefined,
+        shutdownConfirmed: false,
+        ownedProcessStopped: false,
+    };
+    await report(input.progress, 0, "requesting Hopper document shutdown");
+    await requestShutdown(input, state);
+    await report(input.progress, 0.35, "releasing Hopper bridge transport");
+    input.releaseTransport(input.socket);
+    await stopProcess(input, state);
+    recordUnconfirmedDocument(input, state);
+    await report(input.progress, 0.75, "removing Hopper private runtime files");
+    await closeRuntimeRoot(input.runtimeRoot, state);
+    return cleanupOutcome(input, state);
+};
+const requestShutdown = async (input, state) => {
+    if (input.socket === undefined ||
+        input.socket.destroyed ||
+        input.activeRequest !== null) {
+        if (input.activeRequest !== null)
+            input.logger.warn({
+                method: input.activeRequest.operation,
+                callerState: input.activeRequest.callerState,
+            }, "Hopper shutdown skipped because a bridge operation remained active");
+        return;
+    }
+    const shutdown = await input
+        .request("shutdown")
+        .catch(() => err(new HopperProcessError(null)));
+    if (shutdown.ok &&
+        isHopperCleanupRequired(shutdown.value) &&
+        input.launch?.shutdownByCleanup === true &&
+        input.launch.cleanup !== undefined) {
+        state.cleanupResult = await input.launch
+            .cleanup()
+            .catch(providerCleanupFailure);
+        if (!state.cleanupResult.cleaned) {
+            state.shutdownConfirmed = await fallbackDocumentShutdown(input);
+            state.cleanupResult = await input.launch
+                .cleanup()
+                .catch(providerCleanupFailure);
+        }
+    }
+    else if (shutdown.ok) {
+        state.shutdownConfirmed = isHopperShutdownAcknowledgement(shutdown.value);
+    }
+    if (!shutdown.ok ||
+        (!state.shutdownConfirmed && state.cleanupResult === undefined))
+        input.logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown was not confirmed");
+};
+const fallbackDocumentShutdown = async (input) => {
+    const fallback = await input
+        .request("shutdown_document")
+        .catch(() => err(new HopperProcessError(null)));
+    const confirmed = fallback.ok && isHopperShutdownAcknowledgement(fallback.value);
+    if (!confirmed)
+        input.logger.warn({ status: fallback.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown fallback was not confirmed");
+    return confirmed;
+};
+const stopProcess = async (input, state) => {
+    const supervisor = input.processSupervisor;
+    if (supervisor === undefined)
+        return;
+    const stopped = await supervisor.stop(state.cleanupResult === undefined
+        ? {}
+        : { cleanupResult: state.cleanupResult });
+    const diagnostic = createOwnedHopperShutdownDiagnostic(supervisor.launch, stopped, state.cleanupResult);
+    try {
+        input.onDiagnostic?.(diagnostic);
+    }
+    catch {
+        // Diagnostic consumers cannot change the already-observed cleanup result.
+    }
+    input.logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
+    if (stopped.status !== "incomplete") {
+        state.ownedProcessStopped = stopped.status !== "not-owned";
+        return;
+    }
+    const processGroupId = supervisor.launch.ownership?.processGroupId;
+    const resource = processGroupId === undefined
+        ? "hopper-process"
+        : `process-group:${String(processGroupId)}`;
+    state.resources.add(resource);
+    state.issues.push({ resource, reason: stopped.reason });
+    input.logger.warn({ reason: stopped.reason }, "Owned launcher cleanup failed closed");
+};
+const recordUnconfirmedDocument = (input, state) => {
+    if ((input.socket === undefined && input.launch === undefined) ||
+        state.shutdownConfirmed ||
+        state.ownedProcessStopped)
+        return;
+    state.resources.add("hopper-document");
+    state.issues.push({
+        resource: "hopper-document",
+        reason: input.activeRequest === null
+            ? "authenticated shutdown acknowledgement was not observed"
+            : `bridge operation ${input.activeRequest.operation} remained active after caller ${input.activeRequest.callerState}`,
+    });
+};
+const closeRuntimeRoot = async (runtimeRoot, state) => {
+    try {
+        await runtimeRoot?.close();
+    }
+    catch (cause) {
+        const resource = runtimeRoot?.path ?? "hopper-runtime-root";
+        state.resources.add(resource);
+        state.issues.push({
+            resource,
+            reason: cause instanceof Error
+                ? cause.message
+                : "private runtime root cleanup failed",
+        });
+    }
+};
+const cleanupOutcome = (input, state) => {
+    if (state.issues.length === 0)
+        return ok(null);
+    return err(new ProviderCleanupError("hopper", [...state.resources], {
+        issues: cleanupIssueDetails(state.issues),
+        ...(input.runtimeRoot === undefined
+            ? {}
+            : { runtime_root: input.runtimeRoot.path }),
+        ...(input.activeRequest === null
+            ? {}
+            : { active_request: activityDetails(input.activeRequest) }),
+    }));
+};
+const cleanupIssueDetails = (issues) => issues.map((issue) => ({
+    resource: issue.resource,
+    reason: issue.reason,
+}));
+const activityDetails = (activity) => ({
+    request_id: activity.requestId,
+    operation: activity.operation,
+    elapsed_ms: activity.elapsedMs,
+    timeout_ms: activity.timeoutMs,
+    caller_state: activity.callerState,
+    queued_requests: activity.queuedRequests,
+});
+const report = async (progress, completed, message) => {
+    await progress
+        ?.report({
+        phase: "hopper_cleanup",
+        completed,
+        total: 1,
+        message,
+    })
+        .catch(() => undefined);
+};