rea-agents 6.3.0 → 6.5.0

package/dist/javascript/sourceMaps/TraceSourceMap.js

@@ -3,6 +3,8 @@ import { createRequire } from "node:module";
 import { getHeapStatistics } from "node:v8";
 import { AnyMap, TraceMap, decodedMappings, } from "@jridgewell/trace-mapping";
 import { z } from "zod";
+import { javaScriptRuntime } from "../../domain/runtimeVersion.js";
+import { javaScriptWorkerMemoryLimitBytes } from "../../process/JavaScriptWorkerMemoryLimit.js";
 import { webSourceOffset } from "../../domain/webSourcePosition.js";
 import { webSourceMapReportSchema, WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
 import { inspectSourceMap, SourceMapFormatFailure, } from "./SourceMapFormat.js";
@@ -10,13 +12,28 @@ import { decodeValidatedSourceMapLeaves, isBeforeSourceMapLeafStop, } from "./De
 /** Decode with the pinned upstream codec; preserve every equal-position candidate. */
 export const traceSourceMap = (text, url, position) => {
     const inspected = inspectSourceMap(text);
-    const map = new AnyMap(inspected.jsonText, url);
     const decodedLeaves = decodeValidatedSourceMapLeaves(inspected.leaves, url);
     for (const { leaf, rows } of decodedLeaves)
         for (const [line, row] of rows.entries())
             for (const segment of row)
                 if (!isBeforeSourceMapLeafStop(leaf, line, segment[0]))
                     throw new SourceMapFormatFailure("format", "Embedded source-map mappings overlap the following section boundary.");
+    let map;
+    if (inspected.format === "regular") {
+        const decoded = decodedLeaves[0];
+        if (decoded === undefined)
+            throw new SourceMapFormatFailure("format", "Regular source map has no validated leaf.");
+        map = decoded.map;
+    }
+    else {
+        map = new AnyMap({
+            version: 3,
+            sections: decodedLeaves.map(({ leaf, map: sectionMap }) => ({
+                offset: leaf.offset,
+                map: sectionMap,
+            })),
+        }, url);
+    }
     const rows = inspected.format === "regular"
         ? (decodedLeaves[0]?.rows ?? [])
         : decodedMappings(map);
@@ -38,15 +55,26 @@ export const traceSourceMap = (text, url, position) => {
     const version = z
         .object({ version: z.string().min(1) })
         .parse(metadata).version;
+    const runtime = javaScriptRuntime(process.versions);
     return webSourceMapReportSchema.parse({
         source_map_sha256: createHash("sha256").update(text).digest("hex"),
         url_context: url,
         engine: { id: "jridgewell-trace-mapping", version },
-        runtime: {
-            id: "node-v8",
-            version: process.version,
-            v8_heap_limit_bytes: getHeapStatistics().heap_size_limit,
-        },
+        // Bun reports V8-shaped heap statistics but ignores the codec's heap flags.
+        // Its launcher applies the same runtime policy, and the parent verifies it.
+        runtime: runtime.id === "node"
+            ? {
+                id: "node-v8",
+                version: process.version,
+                v8_heap_limit_bytes: getHeapStatistics().heap_size_limit,
+            }
+            : {
+                id: "bun",
+                version: runtime.version,
+                node_compatibility_version: runtime.nodeCompatibilityVersion,
+                v8_heap_limit_bytes: null,
+                process_memory_limit_bytes: javaScriptWorkerMemoryLimitBytes(WEB_SOURCE_MAP_LIMITS.codecHeapMiB),
+            },
         format: inspected.format,
         reported_file: inspected.reportedFile,
         lookup: {

package/dist/jeb/JebMcpConnection.js

@@ -0,0 +1,186 @@
+import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AnalysisCancelledError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+const toolResultSchema = z.object({
+    isError: z.boolean().optional(),
+    structuredContent: z.record(z.string(), z.unknown()).optional(),
+    content: z
+        .array(z.object({ type: z.string(), text: z.string().optional() }).passthrough())
+        .default([]),
+});
+/** Decode a JEB MCP tool result without inventing an empty observation. */
+export const decodeJebToolResult = (input) => {
+    const result = toolResultSchema.parse(input);
+    const blocks = result.content.flatMap((block) => block.type === "text" && block.text !== undefined ? [block.text] : []);
+    let decoded;
+    if (result.structuredContent !== undefined) {
+        decoded = jsonValueSchema.parse(result.structuredContent);
+    }
+    else {
+        if (blocks.length !== 1)
+            throw new AnalysisProtocolError("JEB MCP omitted a single structured or text result; unsupported content cannot establish an empty observation.");
+        const text = blocks[0] ?? "null";
+        try {
+            decoded = jsonValueSchema.parse(JSON.parse(text));
+        }
+        catch {
+            decoded = text;
+        }
+    }
+    if (result.isError === true && !isJebFailureEnvelope(decoded))
+        throw new AnalysisProtocolError(`JEB MCP tool failed: ${blocks[0] ?? "error-marked result without a JEB failure envelope"}`, { cause: decoded });
+    return decoded;
+};
+const isJebFailureEnvelope = (value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    value.success === false;
+/** Serve JEB requests from a running engine client over streamable HTTP. */
+export const createStreamableHttpJebMcpConnection = (endpoint) => {
+    let state;
+    let closing;
+    let closed = false;
+    const waitForCaller = (promise, signal) => {
+        if (signal?.aborted === true)
+            return Promise.reject(new AnalysisCancelledError("jeb_mcp"));
+        if (signal === undefined)
+            return promise;
+        return new Promise((resolve, reject) => {
+            const abort = () => {
+                signal.removeEventListener("abort", abort);
+                reject(new AnalysisCancelledError("jeb_mcp"));
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            void promise.then((value) => {
+                signal.removeEventListener("abort", abort);
+                resolve(value);
+            }, (cause) => {
+                signal.removeEventListener("abort", abort);
+                reject(cause);
+            });
+        });
+    };
+    const dispose = async (owner) => {
+        if (owner.disposal !== undefined)
+            return owner.disposal;
+        const cleanup = (async () => {
+            const settled = await Promise.allSettled([
+                owner.client.close(),
+                owner.transport.close(),
+            ]);
+            const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (failures.length > 0)
+                throw new AggregateError(failures, "JEB MCP connection cleanup failed");
+            if (state === owner)
+                state = undefined;
+        })();
+        owner.disposal = cleanup;
+        try {
+            await cleanup;
+        }
+        catch (cause) {
+            owner.disposal = undefined;
+            throw cause;
+        }
+    };
+    const connect = async (signal) => {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError("jeb_mcp");
+        if (closing !== undefined)
+            await closing;
+        if (closed) {
+            if (state !== undefined)
+                await dispose(state);
+            throw new AnalysisProtocolError("JEB MCP connection is closed");
+        }
+        if (state?.tools !== undefined && state.disposal === undefined)
+            return state.tools;
+        if (state?.acquisition !== undefined)
+            return waitForCaller(state.acquisition, signal);
+        if (state !== undefined) {
+            await dispose(state);
+            if (state !== undefined || closing !== undefined)
+                return connect(signal);
+        }
+        const owner = {
+            client: new Client({
+                name: "rea-jeb",
+                version: "0.0.0",
+            }),
+            transport: new StreamableHTTPClientTransport(endpoint, {
+                requestInit: { redirect: "error" },
+            }),
+            signal: new AbortController(),
+            tools: undefined,
+            acquisition: undefined,
+            disposal: undefined,
+        };
+        state = owner;
+        const acquisition = (async () => {
+            try {
+                await owner.client.connect(owner.transport, {
+                    signal: owner.signal.signal,
+                });
+                const listing = await owner.client.listTools({}, { signal: owner.signal.signal });
+                const tools = listing.tools.map((tool) => tool.name);
+                owner.tools = tools;
+                return tools;
+            }
+            catch (cause) {
+                owner.signal.abort(cause);
+                try {
+                    await dispose(owner);
+                }
+                catch (cleanupCause) {
+                    throw new AggregateError([cause, cleanupCause], "JEB MCP connection acquisition and cleanup failed", { cause });
+                }
+                throw cause;
+            }
+        })();
+        owner.acquisition = acquisition;
+        void acquisition.then(() => {
+            if (owner.acquisition === acquisition)
+                owner.acquisition = undefined;
+        }, () => {
+            if (owner.acquisition === acquisition)
+                owner.acquisition = undefined;
+        });
+        return waitForCaller(acquisition, signal);
+    };
+    return {
+        connect,
+        async call(name, args, signal) {
+            await connect(signal);
+            const owner = state;
+            if (owner === undefined || owner.tools === undefined)
+                throw new AnalysisProtocolError("JEB MCP client failed to connect");
+            const result = await owner.client.callTool({ name, arguments: args }, signal === undefined ? {} : { signal });
+            return decodeJebToolResult(result);
+        },
+        async close() {
+            closed = true;
+            if (closing !== undefined)
+                return closing;
+            const operation = (async () => {
+                const owner = state;
+                if (owner === undefined)
+                    return;
+                owner.tools = undefined;
+                owner.signal.abort();
+                if (owner.acquisition !== undefined)
+                    await owner.acquisition.catch(() => undefined);
+                if (state === owner)
+                    await dispose(owner);
+            })();
+            closing = operation;
+            try {
+                await operation;
+            }
+            finally {
+                if (closing === operation)
+                    closing = undefined;
+            }
+        },
+    };
+};

package/dist/jeb/JebMcpEndpoint.js

@@ -0,0 +1,45 @@
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+import { urlDeclaresQueryOrFragment } from "../domain/urlComponents.js";
+/** Default JEB MCP endpoint documented by the engine's headless client. */
+export const DEFAULT_JEB_MCP_ENDPOINT = "http://127.0.0.1:8425/mcp";
+/**
+ * Normalize the caller-selected JEB MCP endpoint.
+ *
+ * Only the scheme, host, and port select the engine; credentials, paths with
+ * segments beyond the MCP route, queries, and fragments are rejected rather
+ * than silently dropped.
+ */
+export const parseJebMcpEndpoint = (value) => {
+    const raw = value === undefined || value.length === 0 ? null : value;
+    let url;
+    try {
+        url = new URL(raw ?? DEFAULT_JEB_MCP_ENDPOINT);
+    }
+    catch {
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "Expected an absolute http(s) URL",
+        }));
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "Only http and https JEB MCP endpoints are supported",
+        }));
+    if (url.hostname !== "127.0.0.1" && url.hostname !== "[::1]")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "JEB MCP endpoint must use a literal loopback host (127.0.0.1 or ::1)",
+        }));
+    if (url.username !== "" || url.password !== "")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "Embedding credentials in the JEB MCP endpoint is not supported; configure authentication with the engine",
+        }));
+    if (url.pathname !== "/mcp" && url.pathname !== "/mcp/")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "JEB MCP endpoint must use the /mcp route",
+        }));
+    if (urlDeclaresQueryOrFragment(url))
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "JEB MCP endpoint query strings and fragments are not supported",
+        }));
+    return ok(url);
+};

package/dist/jeb/JebProvider.js

@@ -0,0 +1,297 @@
+import { z } from "zod";
+import { createAnalysisExecution } from "../application/AnalysisProvider.js";
+import { jebResultSchemas } from "../domain/jeb/jebAnalysis.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisProtocolError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { err, ok } from "../domain/result.js";
+import { parseJebMcpEndpoint, DEFAULT_JEB_MCP_ENDPOINT, } from "./JebMcpEndpoint.js";
+import { createStreamableHttpJebMcpConnection, } from "./JebMcpConnection.js";
+export const JEB_PROVIDER_IDENTITY = {
+    id: "jeb",
+    name: "JEB",
+    version: null,
+};
+/** JEB's tool envelope: success with typed fields, or a message-only failure. */
+const failure = z
+    .object({
+    success: z.literal(false),
+    message: z.string().optional(),
+    error: z
+        .object({
+        code: z.string().optional(),
+        message: z.string().optional(),
+        recovery_tool: z.string().optional(),
+    })
+        .optional(),
+})
+    .passthrough();
+const clientInformation = z
+    .object({
+    success: z.literal(true),
+    version: z.string().optional(),
+    gui_client: z.boolean().optional(),
+    startup_ts: z.number().int().nonnegative().optional(),
+    message: z.string().nullish(),
+})
+    .passthrough();
+const unitEntry = z.object({ unit_path: z.string(), unit_type: z.string() });
+const openProject = z
+    .object({
+    success: z.literal(true),
+    name: z.string().nullish(),
+    creation_datetime: z.string().nullish(),
+    input_files: z.array(z.object({
+        file_name: z.string(),
+        file_size: z.number().int().nonnegative(),
+        contents_sha256_hash: z.string(),
+    })),
+    units: z.array(unitEntry),
+})
+    .passthrough();
+const listUnits = z
+    .object({ success: z.literal(true), units: z.array(unitEntry) })
+    .passthrough();
+const decompiledItem = z
+    .object({ success: z.literal(true), text: z.string() })
+    .passthrough();
+const refusalReason = (payload, fallback) => {
+    const parsed = failure.safeParse(payload);
+    if (!parsed.success)
+        return fallback;
+    const envelope = parsed.data;
+    const reason = envelope.error?.message ?? envelope.message ?? envelope.error?.code;
+    if (reason !== undefined && reason.length > 0)
+        return reason;
+    return fallback;
+};
+/** Serve REA's JEB operations from a running engine client over MCP. */
+export class JebProvider {
+    #connection;
+    #endpoint;
+    #identity = JEB_PROVIDER_IDENTITY;
+    #guiClient = null;
+    constructor(options = {}) {
+        const environment = options.environment ?? {};
+        const endpoint = parseJebMcpEndpoint(environment.REA_JEB_MCP_URL);
+        if (!endpoint.ok)
+            throw endpoint.error;
+        this.#endpoint = endpoint.value;
+        this.#connection = (options.connectionFactory ??
+            ((url) => createStreamableHttpJebMcpConnection(url)))(this.#endpoint);
+    }
+    async inspectAvailability(signal) {
+        try {
+            await this.#refreshClientInformation(signal);
+            return {
+                status: "available",
+                code: null,
+                reason: null,
+                diagnostics: {
+                    endpoint: this.#endpoint.toString(),
+                    engine_version: this.#identity.version,
+                },
+            };
+        }
+        catch (cause) {
+            if (signal?.aborted === true)
+                throw cause;
+            return {
+                status: "unavailable",
+                code: "not_configured",
+                reason: cause instanceof Error
+                    ? cause.message
+                    : "The JEB MCP endpoint did not respond",
+                diagnostics: { endpoint: this.#endpoint.toString() },
+            };
+        }
+    }
+    async close() {
+        await this.#connection.close();
+    }
+    async execute(request, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError(request.operation));
+        try {
+            const execution = await this.#dispatch(request, options?.signal);
+            if (options?.signal?.aborted)
+                return err(new AnalysisCancelledError(request.operation));
+            if (execution.ok)
+                this.#identity = {
+                    ...this.#identity,
+                    version: execution.value.provider.version,
+                };
+            return execution;
+        }
+        catch (cause) {
+            if (options?.signal?.aborted)
+                return err(new AnalysisCancelledError(request.operation, { cause }));
+            return err(this.#providerFailure(request.operation, cause));
+        }
+    }
+    async #dispatch(request, signal) {
+        const cancelled = (operation) => {
+            if (signal?.aborted === true)
+                throw new AnalysisCancelledError(operation);
+        };
+        switch (request.operation) {
+            case "inspect_jeb_client": {
+                cancelled(request.operation);
+                return this.#inspectClient(signal);
+            }
+            case "open_jeb_project": {
+                cancelled(request.operation);
+                return this.#openProject(request, signal);
+            }
+            case "list_jeb_units": {
+                cancelled(request.operation);
+                return this.#listUnits(request, signal);
+            }
+            case "decompile_jeb_item": {
+                cancelled(request.operation);
+                return this.#decompileItem(request, signal);
+            }
+        }
+    }
+    async #engine(signal) {
+        await this.#requireClientInformation(signal);
+        return {
+            name: "jeb",
+            version: this.#identity.version,
+            endpoint: this.#endpoint.toString(),
+            gui_client: this.#guiClient,
+        };
+    }
+    async #requireClientInformation(signal) {
+        if (this.#identity.version !== null)
+            return;
+        await this.#refreshClientInformation(signal);
+    }
+    async #refreshClientInformation(signal) {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError("inspect_jeb_client");
+        const payload = await this.#connection.call("get_client_information", {}, signal);
+        const information = clientInformation.parse(this.#requireSuccess(payload, "inspect_jeb_client"));
+        this.#identity = {
+            ...this.#identity,
+            version: information.version ?? null,
+        };
+        this.#guiClient = information.gui_client ?? null;
+    }
+    async #inspectClient(signal) {
+        const payload = await this.#connection.call("get_client_information", {}, signal);
+        const information = clientInformation.parse(this.#requireSuccess(payload, "inspect_jeb_client"));
+        this.#identity = {
+            ...this.#identity,
+            version: information.version ?? null,
+        };
+        this.#guiClient = information.gui_client ?? null;
+        const result = jebResultSchemas.inspect_jeb_client.parse({
+            engine: {
+                name: "jeb",
+                version: information.version ?? null,
+                endpoint: this.#endpoint.toString(),
+                gui_client: information.gui_client ?? null,
+            },
+            startup_ts: information.startup_ts ?? null,
+            message: information.message ?? null,
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: information.version === undefined
+                ? ["The engine did not report its version."]
+                : [],
+        }));
+    }
+    async #openProject(request, signal) {
+        const payload = await this.#connection.call("open_project", {
+            file_path: request.input.path,
+        }, signal);
+        const opened = openProject.parse(this.#requireSuccess(payload, request.operation));
+        const engine = await this.#engine(signal);
+        const result = jebResultSchemas.open_jeb_project.parse({
+            engine,
+            project_name: opened.name ?? null,
+            creation_datetime: opened.creation_datetime ?? null,
+            input_files: opened.input_files,
+            units: opened.units,
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: [
+                "JEB resolves and analyzes the artifact on the engine host; REA did not open the target itself.",
+            ],
+        }));
+    }
+    async #listUnits(request, signal) {
+        const { count, index, filter, parent_unit_path } = request.input;
+        const payload = await this.#connection.call("list_units", {
+            count,
+            index,
+            ...(filter === undefined ? {} : { filter }),
+            ...(parent_unit_path === undefined ? {} : { parent_unit_path }),
+        }, signal);
+        const listed = listUnits.parse(this.#requireSuccess(payload, request.operation));
+        const units = listed.units;
+        const engine = await this.#engine(signal);
+        const result = jebResultSchemas.list_jeb_units.parse({
+            engine,
+            filter: filter ?? null,
+            parent_unit_path: parent_unit_path ?? null,
+            index,
+            count,
+            units,
+            coverage: units.length < count ? "complete" : "partial",
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: [
+                "The engine caps unit pages at 100; a full page means more units may exist.",
+            ],
+        }));
+    }
+    async #decompileItem(request, signal) {
+        const { item_address, item_kind, unit_path } = request.input;
+        const payload = await this.#connection.call("decompile_code_item", {
+            item_address,
+            item_kind,
+            ...(unit_path === undefined ? {} : { unit_path }),
+        }, signal);
+        const decompiled = decompiledItem.parse(this.#requireSuccess(payload, request.operation));
+        const engine = await this.#engine(signal);
+        const result = jebResultSchemas.decompile_jeb_item.parse({
+            engine,
+            unit_path: unit_path ?? null,
+            item_address,
+            item_kind,
+            text: decompiled.text,
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: unit_path === undefined
+                ? [
+                    "The engine selected the project's first code unit implicitly; the effective unit identity is unknown.",
+                ]
+                : [],
+        }));
+    }
+    #requireSuccess(payload, operation) {
+        if (typeof payload !== "object" || payload === null)
+            throw new AnalysisProtocolError("JEB MCP returned a non-object envelope; no observation can be established");
+        const success = payload.success;
+        if (success === false)
+            throw new AnalysisUnsupportedTargetError(operation, this.#endpoint.toString(), refusalReason(payload, "The engine refused the request"));
+        if (success !== true)
+            throw new AnalysisProtocolError("JEB MCP omitted its success field; no observation can be established");
+        return payload;
+    }
+    #providerFailure(operation, cause) {
+        if (cause instanceof AnalysisError)
+            return cause;
+        if (cause instanceof z.ZodError)
+            return new AnalysisProtocolError("JEB omitted or malformed required observation fields", { cause });
+        return new AnalysisCapabilityUnavailableError("jeb", operation, cause instanceof Error ? cause.message : String(cause), {
+            cause: cause instanceof Error ? cause : undefined,
+            userMessage: `Start a JEB client serving MCP (default ${DEFAULT_JEB_MCP_ENDPOINT}) or set REA_JEB_MCP_URL to the running endpoint.`,
+        });
+    }
+}

package/dist/logger.js

@@ -1,10 +1,23 @@
 import pino, {} from "pino";
 import { z } from "zod";
+import { ConfigurationError } from "./domain/configurationErrors.js";
+import { err, ok } from "./domain/result.js";
 const logLevelSchema = z
     .enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
     .default("info");
 /** Parse the optional REA_LOG_LEVEL environment variable. */
-export const parseLogLevel = (value) => logLevelSchema.parse(value);
+export const parseLogLevel = (value) => {
+    const parsed = logLevelSchema.safeParse(value);
+    if (parsed.success)
+        return ok(parsed.data);
+    return err(new ConfigurationError("Invalid REA environment configuration", {
+        cause: parsed.error,
+        settings: parsed.error.issues.map(({ message }) => ({
+            setting: "REA_LOG_LEVEL",
+            constraint: message,
+        })),
+    }));
+};
 /** Create a JSON logger on stderr so protocol and CLI result stdout stay valid. */
 export const createLogger = (mode, level) => pino({
     level,

package/dist/main/shutdown.js

@@ -9,6 +9,9 @@ export const createShutdown = (input) => {
         ...(input.closeAndroid === undefined
             ? []
             : [{ close: input.closeAndroid, closed: false }]),
+        ...(input.closeOptionalProviders === undefined
+            ? []
+            : [{ close: input.closeOptionalProviders, closed: false }]),
         {
             close: async () => {
                 const closed = await session.close({ retainProviderDocuments: true });