rea-agents 4.1.0 → 5.0.0

package/dist/hopper/HopperProviderCapabilities.js

@@ -0,0 +1,73 @@
+/** Public identity committed by every Hopper-backed observation. */
+export const HOPPER_PROVIDER_IDENTITY = Object.freeze({
+    id: "hopper",
+    name: "Hopper Disassembler",
+    version: null,
+});
+/** Analyst operations implemented by REA's private Hopper bridge. */
+export const HOPPER_OPERATIONS = Object.freeze([
+    "address_name",
+    "comment",
+    "current_address",
+    "current_procedure",
+    "current_document",
+    "goto_address",
+    "inline_comment",
+    "list_bookmarks",
+    "list_documents",
+    "list_names",
+    "list_procedures",
+    "list_segments",
+    "list_strings",
+    "next_address",
+    "prev_address",
+    "procedure_address",
+    "procedure_assembly",
+    "procedure_callees",
+    "procedure_callers",
+    "procedure_info",
+    "read_function_instructions",
+    "read_bytes",
+    "address_to_file_offset",
+    "procedure_references",
+    "procedure_pseudo_code",
+    "resolve_containing_procedure",
+    "search_procedures",
+    "search_strings",
+    "set_address_name",
+    "set_addresses_names",
+    "set_bookmark",
+    "set_comment",
+    "set_current_document",
+    "set_inline_comment",
+    "unset_bookmark",
+    "xrefs",
+    "analyze_function",
+]);
+const MUTATING_OPERATIONS = new Set([
+    "set_address_name",
+    "set_addresses_names",
+    "set_bookmark",
+    "set_comment",
+    "set_inline_comment",
+    "unset_bookmark",
+]);
+/** Source-owned capabilities without acquiring or probing a Hopper session. */
+export const CAPABILITIES = Object.freeze(HOPPER_OPERATIONS.map((operation) => Object.freeze({
+    provider: HOPPER_PROVIDER_IDENTITY,
+    operation,
+    available: true,
+    reason: null,
+    effects: Object.freeze({
+        mutatesArtifact: MUTATING_OPERATIONS.has(operation),
+        launchesProcess: true,
+        mayShowUi: true,
+        mayAccessNetwork: false,
+        mayWriteFilesystem: MUTATING_OPERATIONS.has(operation),
+        changesPermissions: false,
+        requiresRoot: false,
+    }),
+    limitations: Object.freeze([
+        "Results depend on Hopper's completed static analysis.",
+    ]),
+})));

package/dist/hopper/HopperResponseStream.js

@@ -3,11 +3,16 @@ import { parseBridgeMessageLine, } from "./protocol.js";
 export class HopperResponseStream {
     options;
     #buffer = "";
+    #fragments = [];
     constructor(options) {
         this.options = options;
     }
     push(chunk) {
-        this.#buffer += chunk;
+        this.#fragments.push(chunk);
+        if (!chunk.includes("\n"))
+            return;
+        this.#buffer += this.#fragments.join("");
+        this.#fragments = [];
         let newline = this.#buffer.indexOf("\n");
         while (newline >= 0) {
             const line = this.#buffer.slice(0, newline).trim();
@@ -19,6 +24,7 @@ export class HopperResponseStream {
     }
     reset() {
         this.#buffer = "";
+        this.#fragments = [];
     }
     #acceptLine(line) {
         const parsed = parseBridgeMessageLine(line);

package/dist/hopper/LinuxPrivateDisplayProbe.js

@@ -62,7 +62,7 @@ export const runLinuxPrivateDisplayProbe = async (strategy, options) => {
         cleanup: () => cleanupOwnedProcessGroup(started.ownership),
     };
     const supervisor = new ProviderProcessSupervisor(launch);
-    const outcome = await waitForProbeExit(supervisor, options.timeoutMs, options.signal);
+    const outcome = await waitForProbeOutputClose(supervisor, options.timeoutMs, options.signal);
     let cleanupIncomplete = false;
     if (outcome !== "exit") {
         const stopped = await supervisor.stop();
@@ -191,7 +191,7 @@ const emptyProcessResult = (outcome) => ({
     stderrBytes: 0,
     cleanupIncomplete: false,
 });
-const waitForProbeExit = async (supervisor, timeoutMs, signal) => {
+const waitForProbeOutputClose = async (supervisor, timeoutMs, signal) => {
     if (signal?.aborted === true)
         return "cancelled";
     let releaseAbort;
@@ -205,8 +205,8 @@ const waitForProbeExit = async (supervisor, timeoutMs, signal) => {
     try {
         return await Promise.race([
             supervisor
-                .waitForExit(Math.max(1, timeoutMs))
-                .then((exited) => (exited ? "exit" : "timeout")),
+                .waitForOutputClose(Math.max(1, timeoutMs))
+                .then((closed) => (closed ? "exit" : "timeout")),
             aborted,
         ]);
     }

package/dist/ida/IdaProviderCapabilities.js

@@ -1,4 +1,3 @@
-import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 /** This version identifies REA's adapter, not IDA or the upstream Python package. */
 export const IDA_PROVIDER_IDENTITY = Object.freeze({
     id: "ida",
@@ -6,7 +5,7 @@ export const IDA_PROVIDER_IDENTITY = Object.freeze({
     version: "1",
 });
 /** Read-only analyst outcomes supported by both upstream compatibility profiles. */
-export const IDA_OPERATIONS = [
+export const IDA_OPERATIONS = Object.freeze([
     "list_procedures",
     "search_procedures",
     "list_strings",
@@ -19,7 +18,7 @@ export const IDA_OPERATIONS = [
     "read_function_instructions",
     "xrefs",
     "analyze_function",
-];
+]);
 /** Shared limitations of observations from an externally mutable analysis database. */
 export const IDA_LIMITATIONS = Object.freeze([
     "Provider version identifies the REA IDA adapter. IDA engine and upstream distribution versions are unknown unless separately observed; MCP serverInfo is reported independently.",
@@ -29,15 +28,8 @@ export const IDA_LIMITATIONS = Object.freeze([
     "Headless workers are released through the upstream database lifecycle. Abrupt termination of REA, its proxy, or the supervisor cannot prove worker cleanup; inspect upstream inventory after an interrupted process.",
     "Complete function body ranges, typed references, unresolved indirect calls, referenced data, and basic blocks are unavailable in this adapter. Empty unsupported dossier facets are unknown, not observed absence.",
 ]);
-/** Existing REA contracts implemented by the adapter; no upstream tools are exposed directly. */
-export const IDA_PROVIDER_TOOL_CONTRACTS = Object.freeze(IDA_OPERATIONS.map((operation) => {
-    const contract = GENERATED_MCP_TOOL_CATALOG.find(({ name }) => name === operation);
-    if (contract === undefined)
-        throw new TypeError(`Missing contract for ${operation}`);
-    return { ...contract, name: operation };
-}));
 /** Advertise live observations and configured lifecycle effects truthfully. */
-export const idaCapabilities = (mode, stdio) => IDA_PROVIDER_TOOL_CONTRACTS.map(({ name: operation }) => ({
+export const idaCapabilities = (mode, stdio) => IDA_OPERATIONS.map((operation) => ({
     provider: IDA_PROVIDER_IDENTITY,
     operation,
     ...(mode === "headless" && operation === "procedure_callers"

package/dist/ida/IdaSessionClient.js

@@ -63,6 +63,7 @@ export class IdaSessionClient {
     #startup;
     #closed = false;
     #closing = false;
+    #closePromise;
     #workspace;
     #database;
     #openAttempted = false;
@@ -253,6 +254,17 @@ export class IdaSessionClient {
         return this.#metadata;
     }
     async closeWithOutcome() {
+        if (this.#closePromise !== undefined)
+            return this.#closePromise;
+        const closing = this.#closeOnce();
+        const shared = closing.finally(() => {
+            if (this.#closePromise === shared)
+                this.#closePromise = undefined;
+        });
+        this.#closePromise = shared;
+        return shared;
+    }
+    async #closeOnce() {
         this.#closing = true;
         await this.#tail;
         if (this.#closed)

package/dist/{browser → inspector}/JavaScriptRuntimeScope.js

@@ -1,6 +1,17 @@
 import { pathToFileURL } from "node:url";
 import { browserOriginSchema, sanitizeBrowserUrl, } from "../domain/browserObservation.js";
-import { authorizedElectronFile } from "./ElectronFileScope.js";
+import { authorizedElectronFile } from "../browser/ElectronFileScope.js";
+/**
+ * Wire bucket for inspector script exclusions. The V8 observation schemas
+ * fix the `unsupported_location` key, so every canonical denial reason maps
+ * onto it; the reason itself stays available on the decision for logs and
+ * limitations text.
+ */
+export const inspectorExclusionKey = (reason) => {
+    // Every canonical denial collapses onto the fixed V8 wire bucket.
+    void reason;
+    return "unsupported_location";
+};
 /** Resolve a protocol location exposed by the explicitly selected Inspector endpoint. */
 export const authorizeRuntimeLocation = async (value) => {
     if (value.startsWith("node:") && value.length > 0)
@@ -11,7 +22,7 @@ export const authorizeRuntimeLocation = async (value) => {
     if (value.startsWith("file:")) {
         const filePath = await authorizedElectronFile(value);
         return filePath === undefined
-            ? { allowed: false, reason: "unsupported_location" }
+            ? { allowed: false, reason: "not_approved" }
             : { allowed: true, location: { kind: "file", file_path: filePath } };
     }
     let url;
@@ -21,13 +32,13 @@ export const authorizeRuntimeLocation = async (value) => {
     catch (cause) {
         // Non-URL input is outside the authorized runtime scope.
         void cause;
-        return { allowed: false, reason: "unsupported_location" };
+        return { allowed: false, reason: "unsupported_url" };
     }
     if (!["http:", "https:"].includes(url.protocol))
-        return { allowed: false, reason: "unsupported_location" };
+        return { allowed: false, reason: "unsupported_url" };
     const parsedOrigin = browserOriginSchema.safeParse(url.origin);
     if (!parsedOrigin.success)
-        return { allowed: false, reason: "unsupported_location" };
+        return { allowed: false, reason: "unsupported_url" };
     return {
         allowed: true,
         location: {

package/dist/{browser → inspector}/V8InspectorCaptureProjection.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { authorizeRuntimeLocation } from "./JavaScriptRuntimeScope.js";
+import { authorizeRuntimeLocation, inspectorExclusionKey, } from "./JavaScriptRuntimeScope.js";
 /** Empty durable-location exclusion counters. */
 export const createInspectorExclusionCounts = () => ({
     unsupported_location: 0,
@@ -13,18 +13,56 @@ export const describeInspectorTargetLimitations = () => [
     "Every target exposed by the selected Inspector endpoint is eligible for observation; target IDs and locations are not authenticated as operating-system process identity.",
     "No runtime graph depth is traversed because passive Inspector events do not establish require/import caller edges.",
 ];
+const LOCATION_AUTHORIZATION_WORKERS = 8;
 /** Canonically authorize, deduplicate, and sort one bounded raw capture. */
-export const finalizeInspectorCapture = async ({ input, runtime, target, state, }) => {
+export const finalizeInspectorCapture = async ({ input, runtime, target, state, authorizeLocation = authorizeRuntimeLocation, }) => {
     const exclusions = createInspectorExclusionCounts();
     const scripts = new Map();
+    const draftsByUrl = new Map();
     for (const draft of state.scripts) {
-        const decision = await authorizeRuntimeLocation(draft.rawUrl);
-        if (!decision.allowed) {
-            exclusions[decision.reason] += 1;
-            continue;
+        const drafts = draftsByUrl.get(draft.rawUrl) ?? [];
+        drafts.push(draft);
+        draftsByUrl.set(draft.rawUrl, drafts);
+    }
+    const groups = [...draftsByUrl];
+    const authorizedGroups = new Array(groups.length);
+    let nextGroup = 0;
+    let stopScheduling = false;
+    const worker = async () => {
+        try {
+            for (;;) {
+                if (stopScheduling)
+                    return;
+                const index = nextGroup;
+                nextGroup += 1;
+                const group = groups[index];
+                if (group === undefined)
+                    return;
+                const [rawUrl, drafts] = group;
+                authorizedGroups[index] = {
+                    drafts,
+                    decision: await authorizeLocation(rawUrl),
+                };
+            }
+        }
+        catch (cause) {
+            stopScheduling = true;
+            throw cause;
+        }
+    };
+    const workerResults = await Promise.allSettled(Array.from({ length: Math.min(LOCATION_AUTHORIZATION_WORKERS, groups.length) }, worker));
+    const failedWorker = workerResults.find((result) => result.status === "rejected");
+    if (failedWorker?.status === "rejected")
+        throw failedWorker.reason;
+    for (const { drafts, decision } of authorizedGroups) {
+        for (const draft of drafts) {
+            if (!decision.allowed) {
+                exclusions[inspectorExclusionKey(decision.reason)] += 1;
+                continue;
+            }
+            const script = scriptFromDraft(draft, decision.location);
+            scripts.set(script.script_key, script);
         }
-        const script = scriptFromDraft(draft, decision.location);
-        scripts.set(script.script_key, script);
     }
     const items = [...scripts.values()].sort((left, right) => left.script_key < right.script_key
         ? -1

package/dist/{browser → inspector}/V8InspectorEndpoint.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import {} from "../domain/browserObservationErrors.js";
-import { parseCdpEndpointValue, readCdpJson } from "./CdpEndpoint.js";
+import { parseCdpEndpointValue, readCdpJson } from "../browser/CdpEndpoint.js";
 const versionSchema = z
     .object({
     Browser: z.string().min(1),

package/dist/{browser → inspector}/V8InspectorProvider.js

@@ -1,20 +1,17 @@
-import { javascriptRuntimeObservationSchema, javascriptRuntimeTargetListSchema, } from "../domain/javascriptRuntimeObservation.js";
+import { javascriptRuntimeObservationSchema, javascriptRuntimeTargetListSchema, } from "../domain/javascript/javascriptRuntimeObservation.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/browserObservationErrors.js";
 import { err, ok } from "../domain/result.js";
-import { numberValue, recordValue, stringValue, delayWithCancellation, } from "./CdpCaptureValues.js";
-import { CdpConnection } from "./CdpConnection.js";
-import { authorizeRuntimeTargetLocation } from "./JavaScriptRuntimeScope.js";
+import { numberValue, recordValue, cdpStringValue, delayWithCancellation, } from "../browser/CdpCaptureValues.js";
+import { CdpConnection } from "../browser/CdpConnection.js";
+import { authorizeRuntimeTargetLocation, inspectorExclusionKey, } from "./JavaScriptRuntimeScope.js";
 import { createInspectorExclusionCounts, describeInspectorTargetLimitations, finalizeInspectorCapture, } from "./V8InspectorCaptureProjection.js";
 import { discoverV8Inspector, } from "./V8InspectorEndpoint.js";
 /** Public identity committed by passive V8 Inspector observations. */
-export const V8_INSPECTOR_PROVIDER_IDENTITY = Object.freeze({
-    id: "rea-v8-inspector",
-    name: "REA passive Node/Electron V8 Inspector provider",
-    version: "1",
-});
+export { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
+import { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
 /** Attach-only provider; sends only Runtime.enable and Debugger.enable. */
 export class V8InspectorProvider {
     identity() {
@@ -31,7 +28,7 @@ export class V8InspectorProvider {
                     product: discovery.runtime.product,
                 });
                 if (!decision.allowed) {
-                    excluded[decision.reason] += 1;
+                    excluded[inspectorExclusionKey(decision.reason)] += 1;
                     continue;
                 }
                 if (decision.location.kind === "builtin") {
@@ -196,7 +193,7 @@ const ingestEvent = (event, input, state) => {
 const ingestScript = (event, input, state) => {
     state.scriptsObserved += 1;
     const value = recordValue(event.params);
-    const rawUrl = stringValue(value?.url);
+    const rawUrl = cdpStringValue(value?.url);
     if (rawUrl === undefined || rawUrl === "") {
         state.invalidScripts += 1;
         retainEvent(state, 0);
@@ -205,7 +202,7 @@ const ingestScript = (event, input, state) => {
     const draft = {
         rawUrl,
         executionContextKey: contextKey(value?.executionContextId),
-        cdpHash: stringValue(value?.hash) ?? null,
+        cdpHash: cdpStringValue(value?.hash) ?? null,
         length: nonnegativeInteger(value?.length),
         isModule: value?.isModule === true,
     };
@@ -232,7 +229,7 @@ const ingestContext = (event, input, state) => {
         return;
     }
     const origin = event.method === "Runtime.executionContextCreated"
-        ? (stringValue(runtimeContext?.origin) ?? null)
+        ? (cdpStringValue(runtimeContext?.origin) ?? null)
         : null;
     const draft = {
         contextKey: key,

package/dist/inspector/providerIdentity.js

@@ -0,0 +1,6 @@
+/** Identity available without loading the V8InspectorProvider implementation. */
+export const V8_INSPECTOR_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-v8-inspector",
+    name: "REA passive Node/Electron V8 Inspector provider",
+    version: "1",
+});

package/dist/javascript/recovery/RecoveryFiles.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { TextDecoder } from "node:util";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+const OPERATION = "recover_javascript_sources";
+/** Fingerprint exact selected or derived bytes. */
+export const recoveryDigest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Read a stable regular file without retaining bytes during engine fingerprinting. */
+const scanRecoveryFile = async (path, maximum, consume, signal) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const hash = createHash("sha256");
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > maximum)
+            throw new AnalysisOutputError(OPERATION, `Expected a regular file no larger than ${String(maximum)} bytes: ${path}`);
+        let bytes = 0;
+        for await (const raw of handle.createReadStream({ autoClose: false })) {
+            checkRecoveryCancellation(signal);
+            const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+            bytes += chunk.length;
+            if (bytes > maximum)
+                throw new AnalysisOutputError(OPERATION, `File exceeds ${String(maximum)} bytes: ${path}`);
+            hash.update(chunk);
+            consume(chunk);
+        }
+        const after = await handle.stat();
+        const current = await lstat(path);
+        if (before.dev !== current.dev ||
+            before.ino !== current.ino ||
+            before.size !== bytes ||
+            before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs ||
+            before.size !== after.size)
+            throw new AnalysisOutputError(OPERATION, `File identity changed while reading: ${path}`);
+        return { sha256: hash.digest("hex"), bytes };
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Fingerprint a regular file incrementally with bounded memory. */
+export const fingerprintRecoveryFile = async (path, maximum, signal) => scanRecoveryFile(path, maximum, () => { }, signal);
+/** Read only a regular file through one handle with a bounded, stable identity. */
+export const readRecoveryFile = async (path, maximum, signal) => {
+    const chunks = [];
+    const result = await scanRecoveryFile(path, maximum, (chunk) => chunks.push(chunk), signal);
+    return Buffer.concat(chunks, result.bytes);
+};
+/** Snapshot one caller-selected UTF-8 script before invoking the engine. */
+export const snapshotRecoveryInput = async (path, snapshotPath, signal) => {
+    if (!isAbsolute(path))
+        throw recoveryInputFailure("path", "Select an absolute JavaScript file path");
+    let bytes;
+    try {
+        bytes = await readRecoveryFile(path, RECOVERY_LIMITS.inputBytes, signal);
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisCancelledError)
+            throw cause;
+        throw recoveryInputFailure("path", `Cannot snapshot UTF-8 JavaScript input ${path}: ${recoveryFailureMessage(cause)}`, cause);
+    }
+    await writeFile(snapshotPath, bytes, { flag: "wx", mode: 0o600 });
+    return {
+        path,
+        snapshot_path: snapshotPath,
+        sha256: recoveryDigest(bytes),
+        bytes: bytes.length,
+    };
+};
+/** Inventory staging without following symlinks or publishing special files. */
+export const inventoryRecoveryFiles = async (root, signal) => {
+    const files = [];
+    let bytes = 0;
+    let entries = 0;
+    const visit = async (directory, prefix) => {
+        const metadata = await lstat(directory);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink())
+            throw new AnalysisOutputError(OPERATION, `Unsafe staging directory: ${directory}`);
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            checkRecoveryCancellation(signal);
+            entries++;
+            const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            const path = join(directory, entry.name);
+            const info = await lstat(path);
+            if (entries > RECOVERY_LIMITS.outputEntries)
+                throw new AnalysisOutputError(OPERATION, "Recovery staging exceeds the 10000-entry resource limit");
+            if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()))
+                throw new AnalysisOutputError(OPERATION, `Recovery produced a symlink or special file: ${relativePath}`);
+            if (info.isDirectory())
+                await visit(path, relativePath);
+            else {
+                bytes += info.size;
+                if (bytes > RECOVERY_LIMITS.outputBytes)
+                    throw new AnalysisOutputError(OPERATION, "Recovery staging exceeds the 128 MiB resource limit");
+                files.push({ relativePath, path, bytes: info.size });
+            }
+        }
+    };
+    await visit(root, "");
+    return files;
+};
+/** Preserve actionable caller constraints in the ordinary error algebra. */
+export const recoveryInputFailure = (field, message, cause) => new AnalysisInputError(OPERATION, { cause }, [
+    { path: [field], reason: "invalid_value", message },
+]);
+/** Convert one caught boundary cause into diagnostic text without masking its type. */
+export const recoveryFailureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Cancellation remains distinct from malformed source or provider output. */
+export const checkRecoveryCancellation = (signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError(OPERATION);
+};
+/** Keep both tool invocations within one operation's execution budget. */
+export const checkRecoveryDeadline = (deadline, signal) => {
+    checkRecoveryCancellation(signal);
+    if (Date.now() >= deadline)
+        throw new AnalysisTimeoutError(OPERATION, RECOVERY_LIMITS.timeoutMs);
+};

package/dist/javascript/recovery/WakaruCommand.js

@@ -0,0 +1,116 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../process/ProviderProcess.js";
+import { checkRecoveryDeadline, inventoryRecoveryFiles, fingerprintRecoveryFile, recoveryFailureMessage, } from "./RecoveryFiles.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+const OPERATION = "recover_javascript_sources";
+/** Resolve and fingerprint explicitly configured tools; acquire nothing at startup. */
+export const resolveWakaruCommand = async (environment) => {
+    const configured = environment.REA_WAKARU_COMMAND;
+    if (process.platform !== "linux" ||
+        process.arch !== "x64" ||
+        configured === undefined ||
+        !isAbsolute(configured))
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA");
+    try {
+        const command = await realpath(configured);
+        await access(command, constants.R_OK | constants.X_OK);
+        const fingerprint = await fingerprintRecoveryFile(command, RECOVERY_LIMITS.outputBytes);
+        const limiter = environment.REA_JAVASCRIPT_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+        if (!isAbsolute(limiter))
+            throw new TypeError("REA_JAVASCRIPT_PRLIMIT_COMMAND must be absolute");
+        await access(limiter, constants.X_OK);
+        return { command, limiter, ...fingerprint };
+    }
+    catch (cause) {
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`, { cause });
+    }
+};
+/** Run one bounded command and verify cleanup before consuming its output. */
+export const runWakaruCommand = async (context) => {
+    checkRecoveryDeadline(context.deadline, context.signal);
+    const runId = `rea-wakaru-${randomUUID()}`;
+    const spawned = await (context.launcher ?? spawnOwnedProviderProcess)({
+        command: context.limiter,
+        arguments: [
+            `--as=${String(RECOVERY_LIMITS.addressSpaceBytes)}`,
+            `--fsize=${String(RECOVERY_LIMITS.outputBytes)}`,
+            "--core=0",
+            "--cpu=120",
+            "--",
+            context.command,
+            ...context.arguments,
+        ],
+        expectedCommand: null,
+        runId,
+        cwd: context.cwd,
+        hostEnvironment: context.environment,
+        env: { TMPDIR: context.cwd, RAYON_NUM_THREADS: "1", NO_COLOR: "1" },
+    }).catch((cause) => {
+        throw new ProviderAdapterError("wakaru", OPERATION, {
+            cause,
+            diagnostics: {
+                reason: "Failed to launch configured Wakaru through util-linux prlimit",
+                command: context.command,
+                detail: recoveryFailureMessage(cause),
+            },
+        });
+    });
+    let oversized = false;
+    const supervisor = new ProviderProcessSupervisor({
+        ...spawned,
+        ownsProcessLifetime: true,
+        cleanup: spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
+    }, {
+        onDiagnostic: (event) => {
+            if (event.type === "output" &&
+                event.totalBytes > RECOVERY_LIMITS.reportBytes)
+                oversized = true;
+        },
+    });
+    let failure;
+    try {
+        while (!(await supervisor.waitForOutputClose(100))) {
+            checkRecoveryDeadline(context.deadline, context.signal);
+            if (oversized)
+                throw new AnalysisOutputError(OPERATION, "Wakaru diagnostic stream exceeds 8 MiB");
+            if (context.staging !== undefined)
+                await inventoryRecoveryFiles(context.staging, context.signal);
+        }
+        checkRecoveryDeadline(context.deadline, context.signal);
+        if (oversized)
+            throw new AnalysisOutputError(OPERATION, "Wakaru diagnostic stream exceeds 8 MiB");
+    }
+    catch (cause) {
+        failure = cause;
+    }
+    const stopped = await supervisor.stop();
+    const snapshot = supervisor.snapshot();
+    supervisor.dispose();
+    if (stopped.status === "incomplete")
+        throw new ProviderCleanupError("wakaru", [runId, context.cwd], {
+            reason: stopped.reason,
+            previous_error: failure instanceof Error ? failure.message : null,
+            exit_code: snapshot.exitCode ?? null,
+            signal: snapshot.signal ?? null,
+        });
+    if (failure !== undefined)
+        throw failure;
+    if (context.signal?.aborted === true)
+        throw new AnalysisCancelledError(OPERATION);
+    return {
+        exit_code: snapshot.exitCode ?? null,
+        signal: snapshot.signal ?? null,
+        stdout: snapshot.stdout.text,
+        stderr: snapshot.stderr.text,
+        command: context.command,
+        arguments: [...context.arguments],
+        resource_limiter: context.limiter,
+    };
+};