rea-agents 6.5.0 → 6.7.0

package/dist/jeb/JebMcpConnection.js

@@ -1,7 +1,21 @@
-import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { DEFAULT_REQUEST_TIMEOUT_MSEC, } from "@modelcontextprotocol/client";
 import { z } from "zod";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { AnalysisCancelledError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+import { JebMcpConnectionOwner, JebMcpAcquisitionCleanupFailure, JebMcpPhysicalFailure, } from "./JebMcpConnectionOwner.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { SharedStartupAttempt } from "../process/SharedStartupAttempt.js";
+import { err, ok } from "../domain/result.js";
+import { JebMcpDeadline } from "./JebMcpDeadline.js";
+/** Upstream protocol names for the operations REA exposes. */
+export const JEB_ENGINE_TOOLS = {
+    inspect_jeb_client: "get_client_information",
+    open_jeb_project: "open_project",
+    list_jeb_units: "list_units",
+    decompile_jeb_item: "decompile_code_item",
+};
+const RELEVANT_ENGINE_TOOLS = new Set(Object.values(JEB_ENGINE_TOOLS));
 const toolResultSchema = z.object({
     isError: z.boolean().optional(),
     structuredContent: z.record(z.string(), z.unknown()).optional(),
@@ -37,56 +51,39 @@ const isJebFailureEnvelope = (value) => typeof value === "object" &&
     !Array.isArray(value) &&
     value.success === false;
 /** Serve JEB requests from a running engine client over streamable HTTP. */
-export const createStreamableHttpJebMcpConnection = (endpoint) => {
+export const createStreamableHttpJebMcpConnection = (endpoint, timeouts) => {
+    const discoveryTimeoutMs = timeouts?.discoveryTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
+    const requestTimeoutMs = timeouts?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
     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 waitForAcquisition = async (owner, attempt, signal) => {
+        const waited = await attempt.wait(signal);
+        // Once acquisition failed, its final cleanup belongs to every attached
+        // caller. A later abort cannot replace that already captured outcome.
+        const outcome = waited.status === "cancelled"
+            ? owner.acquisitionFailure === undefined
+                ? undefined
+                : await attempt.promise
+            : waited.value;
+        if (outcome !== undefined && !outcome.ok)
+            throw outcome.error;
+        if (outcome === undefined || signal?.aborted === true)
+            throw new AnalysisCancelledError("jeb_mcp_catalog", {
+                cause: signal?.reason,
             });
-        });
+        return outcome.value;
     };
     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;
-        }
+        await owner.close();
+        if (state === owner)
+            state = undefined;
     };
     const connect = async (signal) => {
         if (signal?.aborted === true)
-            throw new AnalysisCancelledError("jeb_mcp");
+            throw new AnalysisCancelledError("jeb_mcp_catalog", {
+                cause: signal.reason,
+            });
         if (closing !== undefined)
             await closing;
         if (closed) {
@@ -94,68 +91,103 @@ export const createStreamableHttpJebMcpConnection = (endpoint) => {
                 await dispose(state);
             throw new AnalysisProtocolError("JEB MCP connection is closed");
         }
-        if (state?.tools !== undefined && state.disposal === undefined)
+        if (state?.tools !== undefined && !state.disposing)
             return state.tools;
         if (state?.acquisition !== undefined)
-            return waitForCaller(state.acquisition, signal);
+            return waitForAcquisition(state, 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,
-        };
+        const owner = new JebMcpConnectionOwner(endpoint);
         state = owner;
-        const acquisition = (async () => {
+        const acquisition = new SharedStartupAttempt(async (startupSignal) => {
+            const deadline = new JebMcpDeadline(discoveryTimeoutMs, startupSignal);
             try {
                 await owner.client.connect(owner.transport, {
-                    signal: owner.signal.signal,
+                    signal: deadline.signal,
                 });
-                const listing = await owner.client.listTools({}, { signal: owner.signal.signal });
-                const tools = listing.tools.map((tool) => tool.name);
+                const tools = await readToolNames(owner.client, deadline.signal);
+                deadline.signal.throwIfAborted();
                 owner.tools = tools;
-                return tools;
+                return ok(tools);
             }
             catch (cause) {
-                owner.signal.abort(cause);
+                const failure = physicalFailure("catalog", deadline.failure("jeb_mcp_catalog", cause));
+                owner.acquisitionFailure = { cause: failure };
+                owner.signal.abort(failure);
                 try {
                     await dispose(owner);
                 }
                 catch (cleanupCause) {
-                    throw new AggregateError([cause, cleanupCause], "JEB MCP connection acquisition and cleanup failed", { cause });
+                    if (!(cleanupCause instanceof ProviderCleanupError))
+                        throw cleanupCause;
+                    return err(new JebMcpAcquisitionCleanupFailure(failure, cleanupCause));
                 }
-                throw cause;
+                return err(failure);
+            }
+            finally {
+                deadline.dispose();
             }
-        })();
+        }, owner.signal.signal);
         owner.acquisition = acquisition;
-        void acquisition.then(() => {
+        void acquisition.promise.then(() => {
             if (owner.acquisition === acquisition)
                 owner.acquisition = undefined;
         }, () => {
             if (owner.acquisition === acquisition)
                 owner.acquisition = undefined;
         });
-        return waitForCaller(acquisition, signal);
+        return waitForAcquisition(owner, acquisition, signal);
     };
     return {
         connect,
+        async listTools(signal) {
+            const existing = state?.tools !== undefined;
+            // Initial acquisition owns its deadline and cleanup. A second timer
+            // could detach this waiter before that owner has disposed a failed client.
+            const tools = await connect(signal);
+            if (!existing)
+                return tools;
+            const owner = state;
+            if (owner === undefined)
+                throw new AnalysisProtocolError("JEB MCP client failed to connect");
+            const discoverySignal = signal === undefined
+                ? owner.signal.signal
+                : AbortSignal.any([signal, owner.signal.signal]);
+            const deadline = new JebMcpDeadline(discoveryTimeoutMs, discoverySignal);
+            try {
+                const refreshed = await readToolNames(owner.client, deadline.signal);
+                owner.tools = refreshed;
+                return refreshed;
+            }
+            catch (cause) {
+                throw physicalFailure("catalog", deadline.failure("jeb_mcp_catalog", cause));
+            }
+            finally {
+                deadline.dispose();
+            }
+        },
         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 });
+            const requestSignal = signal === undefined
+                ? owner.signal.signal
+                : AbortSignal.any([signal, owner.signal.signal]);
+            const deadline = new JebMcpDeadline(requestTimeoutMs, requestSignal);
+            let result;
+            try {
+                result = await owner.client.callTool({ name, arguments: args }, { timeout: deadline.remainingMs(), signal: deadline.signal });
+            }
+            catch (cause) {
+                throw physicalFailure("tool", deadline.failure(name, cause));
+            }
+            finally {
+                deadline.dispose();
+            }
             return decodeJebToolResult(result);
         },
         async close() {
@@ -169,7 +201,7 @@ export const createStreamableHttpJebMcpConnection = (endpoint) => {
                 owner.tools = undefined;
                 owner.signal.abort();
                 if (owner.acquisition !== undefined)
-                    await owner.acquisition.catch(() => undefined);
+                    await owner.acquisition.promise.catch(() => undefined);
                 if (state === owner)
                     await dispose(owner);
             })();
@@ -184,3 +216,30 @@ export const createStreamableHttpJebMcpConnection = (endpoint) => {
         },
     };
 };
+const readToolNames = async (client, signal) => {
+    const names = new Set();
+    let cursor;
+    do {
+        signal.throwIfAborted();
+        // listTools without a cursor aggregates and caches every page in SDK v2.
+        // This owner needs single pages to bound retained names and the whole walk.
+        const page = await client.request({
+            method: "tools/list",
+            ...(cursor === undefined ? {} : { params: { cursor } }),
+        }, { signal });
+        for (const tool of page.tools)
+            if (RELEVANT_ENGINE_TOOLS.has(tool.name))
+                names.add(tool.name);
+        const next = page.nextCursor;
+        if (next !== undefined && next === cursor)
+            throw new AnalysisProtocolError("JEB MCP repeated a tool catalog cursor");
+        signal.throwIfAborted();
+        if (names.size === RELEVANT_ENGINE_TOOLS.size)
+            return [...names];
+        cursor = next;
+    } while (cursor !== undefined);
+    return [...names];
+};
+const physicalFailure = (phase, cause) => cause instanceof AnalysisError
+    ? cause
+    : new JebMcpPhysicalFailure(phase, cause);

package/dist/jeb/JebMcpConnectionOwner.js

@@ -0,0 +1,116 @@
+import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { SharedStartupAttempt } from "../process/SharedStartupAttempt.js";
+/** Physical SDK failure captured before any subsequent resource cleanup. */
+export class JebMcpPhysicalFailure extends Error {
+    phase;
+    cause;
+    constructor(phase, cause) {
+        super(`JEB MCP ${phase} failed`, { cause });
+        this.phase = phase;
+        this.cause = cause;
+        this.name = "JebMcpPhysicalFailure";
+    }
+}
+/** Acquisition failed while its exact connection still has pending cleanup. */
+export class JebMcpAcquisitionCleanupFailure extends ProviderCleanupError {
+    primaryFailure;
+    cleanupFailure;
+    constructor(primaryFailure, cleanupFailure) {
+        super("jeb", cleanupFailure.cleanupResources, {
+            reason: "JEB MCP acquisition and cleanup failed",
+        }, {
+            operation: "jeb_mcp_catalog",
+            cause: new AggregateError([primaryFailure, cleanupFailure], "JEB MCP acquisition and cleanup failed", { cause: primaryFailure }),
+        });
+        this.primaryFailure = primaryFailure;
+        this.cleanupFailure = cleanupFailure;
+        this.bindCleanupDependencies([cleanupFailure]).bindCleanupResourceOwner(cleanupFailure);
+    }
+}
+/** One SDK client owns its attached transport; failed cleanup retains both identities. */
+export class JebMcpConnectionOwner {
+    client = new Client({ name: "rea-jeb", version: "0.0.0" });
+    transport;
+    signal = new AbortController();
+    tools;
+    acquisition;
+    acquisitionFailure;
+    #clientResource;
+    #transportResource;
+    #lease;
+    #clientClosed = false;
+    #transportClosed = false;
+    #disposal;
+    constructor(endpoint) {
+        this.transport = new StreamableHTTPClientTransport(endpoint, {
+            requestInit: { redirect: "error" },
+        });
+        this.#clientResource = `${endpoint} (JEB MCP client)`;
+        this.#transportResource = `${endpoint} (JEB MCP transport)`;
+        this.#lease = new AnalysisCleanupLease(() => this.#dispose(), [this.#clientResource, this.#transportResource]);
+    }
+    get disposing() {
+        return this.#disposal !== undefined;
+    }
+    get cleanupResources() {
+        return [
+            ...(this.#clientClosed ? [] : [this.#clientResource]),
+            ...(this.#transportClosed ? [] : [this.#transportResource]),
+        ];
+    }
+    close() {
+        return this.#lease.release();
+    }
+    async #dispose() {
+        if (this.#disposal !== undefined)
+            return this.#disposal;
+        const disposal = this.#closeResources();
+        this.#disposal = disposal;
+        try {
+            await disposal;
+        }
+        catch (cause) {
+            this.#disposal = undefined;
+            throw cause;
+        }
+    }
+    async #closeResources() {
+        const failures = [];
+        if (!this.#clientClosed) {
+            const attached = this.client.transport === this.transport;
+            try {
+                await this.client.close();
+                this.#clientClosed = true;
+                // SDK 2.3.1 awaits its attached transport's close before resolving.
+                if (attached)
+                    this.#transportClosed = true;
+            }
+            catch (cause) {
+                failures.push(cause);
+            }
+        }
+        if (!this.#transportClosed) {
+            try {
+                await this.transport.close();
+                this.#transportClosed = true;
+            }
+            catch (cause) {
+                failures.push(cause);
+            }
+        }
+        if (failures.length === 0)
+            return;
+        const failure = new ProviderCleanupError("jeb", this.cleanupResources, {
+            reason: failures
+                .map((cause) => cause instanceof Error ? cause.message : String(cause))
+                .join("; "),
+        }, {
+            operation: "close_jeb_connection",
+            cause: new AggregateError(failures, "JEB MCP connection cleanup failed"),
+        }).bindCleanupResourceOwner(this);
+        this.#lease.bindCleanupError(failure);
+        throw failure;
+    }
+}

package/dist/jeb/JebMcpDeadline.js

@@ -0,0 +1,46 @@
+import { SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
+import { AnalysisCancelledError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+/** SDK 2.3.1 preserves an SdkError abort reason by identity. */
+export class JebMcpDeadline {
+    timeoutMs;
+    #deadline;
+    #controller = new AbortController();
+    #interruption = new SdkError(SdkErrorCode.RequestTimeout, "JEB MCP interrupted");
+    #onAbort = () => this.#controller.abort(this.#interruption);
+    constructor(timeoutMs, signal) {
+        this.timeoutMs = timeoutMs;
+        this.#deadline = new ProviderStartupDeadline(timeoutMs, signal);
+        if (this.#deadline.signal.aborted)
+            this.#onAbort();
+        else
+            this.#deadline.signal.addEventListener("abort", this.#onAbort, {
+                once: true,
+            });
+    }
+    get signal() {
+        return this.#controller.signal;
+    }
+    remainingMs() {
+        return this.#deadline.remainingMs();
+    }
+    /** Classify only the rejection produced by this deadline's exact abort. */
+    failure(operation, cause) {
+        if (cause === this.#interruption) {
+            return this.#deadline.interruption === "timeout"
+                ? new AnalysisTimeoutError(operation, this.timeoutMs, {
+                    cause: this.#deadline.signal.reason,
+                })
+                : new AnalysisCancelledError(operation, {
+                    cause: this.#deadline.signal.reason,
+                });
+        }
+        if (cause instanceof SdkError && cause.code === SdkErrorCode.RequestTimeout)
+            return new AnalysisTimeoutError(operation, this.timeoutMs, { cause });
+        return cause;
+    }
+    dispose() {
+        this.#deadline.signal.removeEventListener("abort", this.#onAbort);
+        this.#deadline.dispose();
+    }
+}