rea-agents 6.2.0 → 6.4.0

package/dist/jeb/JebMcpConnection.js

@@ -0,0 +1,179 @@
+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] : []);
+    if (result.structuredContent !== undefined) {
+        // isError envelopes carry JEB's {success:false, message} refusal semantics;
+        // decode them so the provider can preserve the engine's own reason.
+        return jsonValueSchema.parse(result.structuredContent);
+    }
+    if (blocks.length !== 1)
+        throw new AnalysisProtocolError("JEB MCP omitted a single structured or text result; unsupported content cannot establish an empty observation.");
+    try {
+        return jsonValueSchema.parse(JSON.parse(blocks[0] ?? "null"));
+    }
+    catch {
+        if (result.isError === true)
+            throw new AnalysisProtocolError(`JEB MCP tool failed: ${blocks[0] ?? "unexplained engine failure"}`);
+        return blocks[0] ?? null;
+    }
+};
+/** 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,40 @@
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.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.search !== "" || url.hash !== "")
+        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,299 @@
+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(),
+    }))
+        .optional(),
+    units: z.array(unitEntry).optional(),
+})
+    .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/main/shutdown.js

@@ -3,24 +3,51 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { MCP_SHUTDOWN_FAILED } from "./messages.js";
 export const createShutdown = (input) => {
     const { handle, session, dependencies, serverLogger } = input;
-    let shutdownPromise;
+    let shutdownAttempt;
+    const cleanupOwners = [
+        { close: () => handle.close(), closed: false },
+        ...(input.closeAndroid === undefined
+            ? []
+            : [{ close: input.closeAndroid, closed: false }]),
+        {
+            close: async () => {
+                const closed = await session.close({ retainProviderDocuments: true });
+                if (!closed.ok)
+                    throw closed.error;
+            },
+            closed: false,
+        },
+    ];
+    let shutdownUnregistered = false;
     let unregisterShutdown = () => undefined;
     const shutdown = async () => {
-        shutdownPromise ??= (async () => {
-            unregisterShutdown();
-            const results = await Promise.allSettled([
-                handle.close(),
-                input.closeAndroid?.(),
-                session.close({ retainProviderDocuments: true }).then((closed) => {
-                    if (!closed.ok)
-                        throw closed.error;
-                }),
-            ]);
+        if (shutdownAttempt !== undefined)
+            return shutdownAttempt;
+        const pending = cleanupOwners.filter(({ closed }) => !closed);
+        const attempt = (async () => {
+            const results = await Promise.allSettled(pending.map(async (owner) => {
+                await owner.close();
+                owner.closed = true;
+            }));
+            const failures = [];
             for (const result of results)
                 if (result.status === "rejected")
-                    throw result.reason;
+                    failures.push(result.reason);
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, "Multiple MCP cleanup operations failed");
+            if (!shutdownUnregistered) {
+                unregisterShutdown();
+                shutdownUnregistered = true;
+            }
         })();
-        return shutdownPromise;
+        shutdownAttempt = attempt;
+        void attempt.catch(() => {
+            if (shutdownAttempt === attempt)
+                shutdownAttempt = undefined;
+        });
+        return attempt;
     };
     const requestShutdown = () => {
         shutdown().catch((cause) => {
@@ -35,24 +62,41 @@ export const createShutdown = (input) => {
     unregisterShutdown = dependencies.registerShutdown(requestShutdown);
     return { shutdown, request: requestShutdown };
 };
-const describeShutdownFailure = (cause) => {
-    if (cause instanceof AnalysisError)
-        return { analysis_error: projectAnalysisError(cause) };
-    if (cause instanceof Error) {
-        const code = "code" in cause ? cause.code : undefined;
-        return {
-            name: cause.name,
-            message: cause.message,
-            ...(typeof code === "string" ||
-                (typeof code === "number" && Number.isFinite(code))
-                ? { code }
-                : {}),
-        };
+const describeShutdownFailure = (cause) => describeShutdownFailureNode(cause, new WeakSet());
+const describeShutdownFailureNode = (cause, active) => {
+    if (typeof cause === "object" && cause !== null) {
+        if (active.has(cause))
+            return { type: "cyclic_error" };
+        active.add(cause);
+    }
+    try {
+        if (cause instanceof AnalysisError)
+            return { analysis_error: projectAnalysisError(cause) };
+        if (cause instanceof Error) {
+            const code = "code" in cause ? cause.code : undefined;
+            return {
+                name: cause.name,
+                message: cause.message,
+                ...(typeof code === "string" ||
+                    (typeof code === "number" && Number.isFinite(code))
+                    ? { code }
+                    : {}),
+                ...(cause instanceof AggregateError
+                    ? {
+                        errors: cause.errors.map((error) => describeShutdownFailureNode(error, active)),
+                    }
+                    : {}),
+            };
+        }
+        if (cause === null ||
+            typeof cause === "string" ||
+            typeof cause === "boolean" ||
+            (typeof cause === "number" && Number.isFinite(cause)))
+            return { type: cause === null ? "null" : typeof cause, value: cause };
+        return { type: typeof cause };
+    }
+    finally {
+        if (typeof cause === "object" && cause !== null)
+            active.delete(cause);
     }
-    if (cause === null ||
-        typeof cause === "string" ||
-        typeof cause === "boolean" ||
-        (typeof cause === "number" && Number.isFinite(cause)))
-        return { type: cause === null ? "null" : typeof cause, value: cause };
-    return { type: typeof cause };
 };

package/dist/main/transport.js

@@ -29,7 +29,7 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
             // The SDK can discard a discovery probe and construct a replacement server.
             const android = createAndroidAnalysisProvider(serverContext.environment);
             androidProviders.push(android);
-            return (dependencies.createServer ?? createServer)(session, session, {
+            return (dependencies.createServer ?? createServer)({ kind: "session", session }, {
                 logger: serverContext.logger,
                 environment: serverContext.environment,
                 delivery: serverContext.delivery,