rea-agents 2.1.0 → 2.3.0

package/dist/hopper/LinuxPrivateDisplayProbe.js

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+import { hopperStartupExitCode, } from "../domain/hopperStartupFailure.js";
+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
+import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js";
+const PYTHON_PATH = "/usr/bin/python3";
+const UNSHARE_PATH = "/usr/bin/unshare";
+const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
+const PROBE_OUTPUT_LIMIT_BYTES = 64 * 1024;
+/** Probe the exact Xvfb boundary and select the least-privileged viable strategy. */
+export const selectLinuxPrivateDisplayStrategy = async (options) => {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const runner = options.runProbe ?? runLinuxPrivateDisplayProbe;
+    const direct = await evaluatedProbe("direct", options, timeoutMs, runner);
+    if (direct.ok)
+        return direct;
+    if (direct.diagnostic.failure_code !== "x11_socket_directory_unusable")
+        return unavailable(direct.diagnostic);
+    const isolated = await evaluatedProbe("user-mount-namespace", options, timeoutMs, runner);
+    if (!isolated.ok)
+        return unavailable({
+            ...direct.diagnostic,
+            strategy: "unavailable",
+            reason: "namespace_unavailable",
+            fallback_reason: isolated.diagnostic.reason,
+            effective_socket_directory_mode: isolated.diagnostic.effective_socket_directory_mode,
+            effective_mount_read_only: isolated.diagnostic.effective_mount_read_only,
+            xvfb_stderr_bytes: isolated.diagnostic.xvfb_stderr_bytes,
+            xvfb_stderr_truncated: isolated.diagnostic.xvfb_stderr_truncated,
+        });
+    return {
+        ok: true,
+        strategy: "user-mount-namespace",
+        diagnostic: {
+            ...isolated.diagnostic,
+            socket_directory_mode: direct.diagnostic.socket_directory_mode,
+            mount_read_only: direct.diagnostic.mount_read_only,
+            fallback_reason: null,
+        },
+    };
+};
+/** Run one helper probe in an owned process group with a hard output bound. */
+export const runLinuxPrivateDisplayProbe = async (strategy, options) => {
+    if (options.signal?.aborted === true)
+        return emptyProcessResult({ cancelled: true });
+    const command = privateDisplayProbeCommand(options.helperPath, strategy);
+    let started;
+    try {
+        started = await spawnOwnedProviderProcess({
+            command: command.command,
+            arguments: command.arguments,
+            runId: randomUUID(),
+            expectedCommand: null,
+        });
+    }
+    catch {
+        return emptyProcessResult();
+    }
+    const launch = {
+        process: started.process,
+        ownsProcessLifetime: true,
+        cleanup: () => cleanupOwnedProcessGroup(started.ownership),
+    };
+    const supervisor = new ProviderProcessSupervisor(launch, {
+        maxOutputBytesPerStream: PROBE_OUTPUT_LIMIT_BYTES,
+    });
+    const outcome = await waitForProbeExit(supervisor, options.timeoutMs, options.signal);
+    let cleanupIncomplete = false;
+    if (outcome !== "exit") {
+        const stopped = await supervisor.stop();
+        cleanupIncomplete = stopped.status === "incomplete";
+    }
+    else
+        supervisor.dispose();
+    const snapshot = supervisor.snapshot();
+    return {
+        exitCode: snapshot.exitCode,
+        stderr: snapshot.stderr.text,
+        stderrBytes: snapshot.stderr.bytes,
+        stderrTruncated: snapshot.stderr.truncated,
+        timedOut: outcome === "timeout",
+        cancelled: outcome === "cancelled",
+        cleanupIncomplete,
+    };
+};
+const privateDisplayProbeCommand = (helperPath, strategy) => strategy === "direct"
+    ? {
+        command: PYTHON_PATH,
+        arguments: [helperPath, "--probe", "--strategy", "direct"],
+    }
+    : {
+        command: UNSHARE_PATH,
+        arguments: [
+            "--user",
+            "--map-root-user",
+            "--mount",
+            "--propagation",
+            "private",
+            PYTHON_PATH,
+            helperPath,
+            "--probe",
+            "--strategy",
+            "user-mount-namespace",
+            "--mount-private-x11",
+        ],
+    };
+const evaluatedProbe = async (strategy, options, timeoutMs, runner) => {
+    let processResult;
+    try {
+        processResult = await runner(strategy, {
+            helperPath: options.helperPath,
+            timeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+    }
+    catch {
+        return {
+            ok: false,
+            diagnostic: syntheticDiagnostic(strategy, "probe_failed"),
+        };
+    }
+    if (processResult.cancelled)
+        return {
+            ok: false,
+            diagnostic: syntheticDiagnostic(strategy, "cancelled"),
+        };
+    if (processResult.timedOut)
+        return {
+            ok: false,
+            diagnostic: syntheticDiagnostic(strategy, "probe_timeout"),
+        };
+    if (processResult.cleanupIncomplete)
+        return {
+            ok: false,
+            diagnostic: syntheticDiagnostic(strategy, "cleanup_incomplete"),
+        };
+    const parsed = parseLinuxPrivateDisplayDiagnostic(processResult.stderr, processResult.stderrTruncated);
+    if (!parsed.ok)
+        return {
+            ok: false,
+            diagnostic: syntheticDiagnostic(strategy, parsed.reason),
+        };
+    const diagnostic = parsed.value;
+    if (diagnostic.strategy !== strategy ||
+        diagnostic.operation !== "probe" ||
+        !exitMatchesDiagnostic(processResult.exitCode, diagnostic))
+        return {
+            ok: false,
+            diagnostic: syntheticDiagnostic(strategy, "diagnostic_malformed"),
+        };
+    return diagnostic.status === "ready"
+        ? { ok: true, strategy, diagnostic }
+        : { ok: false, diagnostic };
+};
+const exitMatchesDiagnostic = (exitCode, diagnostic) => diagnostic.status === "ready"
+    ? exitCode === 0
+    : diagnostic.failure_code !== null &&
+        hopperStartupExitCode(diagnostic.failure_code) === exitCode;
+const syntheticDiagnostic = (strategy, reason, failureCode = "private_display_unavailable") => ({
+    schema_version: 1,
+    component: "hopper_private_display",
+    operation: "probe",
+    status: "error",
+    failure_code: failureCode,
+    reason,
+    socket_directory: "/tmp/.X11-unix",
+    socket_directory_mode: null,
+    mount_read_only: null,
+    effective_socket_directory_mode: null,
+    effective_mount_read_only: null,
+    wsl: false,
+    strategy,
+    fallback_reason: null,
+    xvfb_stderr_bytes: 0,
+    xvfb_stderr_truncated: false,
+});
+const unavailable = (diagnostic) => ({
+    ok: false,
+    strategy: "unavailable",
+    exitCode: diagnostic.failure_code === null
+        ? 70
+        : (hopperStartupExitCode(diagnostic.failure_code) ?? 70),
+    diagnostic: { ...diagnostic, strategy: "unavailable" },
+});
+const emptyProcessResult = (overrides = {}) => ({
+    exitCode: undefined,
+    stderr: "",
+    stderrBytes: 0,
+    stderrTruncated: false,
+    timedOut: false,
+    cancelled: false,
+    cleanupIncomplete: false,
+    ...overrides,
+});
+const waitForProbeExit = async (supervisor, timeoutMs, signal) => {
+    if (signal?.aborted === true)
+        return "cancelled";
+    let releaseAbort;
+    const aborted = new Promise((resolve) => {
+        if (signal === undefined)
+            return;
+        const listener = () => resolve("cancelled");
+        signal.addEventListener("abort", listener, { once: true });
+        releaseAbort = () => signal.removeEventListener("abort", listener);
+    });
+    try {
+        return await Promise.race([
+            supervisor
+                .waitForExit(Math.max(1, timeoutMs))
+                .then((exited) => (exited ? "exit" : "timeout")),
+            aborted,
+        ]);
+    }
+    finally {
+        releaseAbort?.();
+    }
+};

package/dist/identity.js

@@ -7,9 +7,10 @@ export const PRODUCT_IDENTITY = {
     displayName: "REA",
     packageName: PACKAGE_METADATA.name,
     packageSpecifier: `${PACKAGE_METADATA.name}@latest`,
+    registrationPackageSpecifier: `${PACKAGE_METADATA.name}@${PACKAGE_METADATA.version}`,
     packageVersion: PACKAGE_METADATA.version,
     cliBinary: "rea",
-    mcpCommand: `npx -y ${PACKAGE_METADATA.name}@latest mcp`,
+    mcpCommand: `npx -y ${PACKAGE_METADATA.name}@${PACKAGE_METADATA.version} mcp`,
     mcpServerKey: "rea",
     skillName: "reverse-engineer-anything",
     skillVersion: PACKAGE_METADATA.skillVersion,

package/dist/main/transport.js

@@ -24,6 +24,8 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
                         .enabled,
                     evidenceFileRoots: serverContext.runtimeState.currentConfig.evidenceFilePolicy
                         .roots.length,
+                    investigationInputRoots: serverContext.runtimeState.currentConfig.investigationInputRoots
+                        .length,
                     browserObservationEnabled: serverContext.runtimeState.currentConfig
                         .browserObservationEnabled &&
                         serverContext.runtimeState.currentConfig.browserCdpEndpoints

package/dist/mcpDoctor.js

@@ -0,0 +1,310 @@
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { Formatter } from "incur";
+import { resolve } from "node:path";
+import { CATALOG_IDENTITY, MCP_RESOURCE_CATALOG, MCP_RESOURCE_TEMPLATE_CATALOG, } from "./catalogIdentity.js";
+import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
+import { PRODUCT_IDENTITY } from "./identity.js";
+const DEFAULT_DEADLINE_MS = 20_000;
+const STDERR_LIMIT_BYTES = 64 * 1_024;
+const OUTPUT_FORMATS = ["toon", "json", "yaml", "md", "jsonl"];
+/** Diagnose the actual production stdio adapter with one bounded SDK session. */
+export const runProductionMcpDoctor = async (options) => {
+    const deadline = Date.now() + (options.deadlineMs ?? DEFAULT_DEADLINE_MS);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("Production MCP doctor deadline expired")), Math.max(1, deadline - Date.now()));
+    const stderr = boundedStderr();
+    const transport = new TrackedStdioClientTransport({
+        command: options.command,
+        args: [...options.args],
+        cwd: options.cwd,
+        env: targetFreeEnvironment(options.environment),
+        stderr: "pipe",
+    });
+    transport.stderr?.on("data", stderr.append);
+    const client = new Client({ name: "rea-mcp-doctor", version: "1" });
+    try {
+        await client.connect(transport, requestOptions(deadline, controller.signal));
+        return {
+            ...(await inspectProductionMcpSession(client, deadline, controller.signal)),
+            diagnostics: stderr.value(),
+        };
+    }
+    catch (cause) {
+        return {
+            healthy: false,
+            adapter: "production-stdio",
+            server: null,
+            inventory: null,
+            identity: null,
+            request_flow: { tool: "binary_session", ok: false },
+            checks: [
+                {
+                    name: "transport",
+                    ok: false,
+                    detail: errorMessage(cause),
+                },
+            ],
+            diagnostics: stderr.value(),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        await closeMcpChild(client, transport);
+    }
+};
+const inspectProductionMcpSession = async (client, deadline, signal) => {
+    const request = requestOptions(deadline, signal);
+    const [tools, prompts, resources, templates, identity, requestFlow] = await Promise.all([
+        client.listTools(undefined, request),
+        client.listPrompts(undefined, request),
+        client.listResources(undefined, request),
+        client.listResourceTemplates(undefined, request),
+        client.readResource({ uri: "rea://server/identity" }, request),
+        client.callTool({ name: "binary_session", arguments: {} }, request),
+    ]);
+    const inventory = {
+        tools: compareInventory(CATALOG_IDENTITY.tools.map(({ name }) => name), tools.tools.map(({ name }) => name)),
+        prompts: compareInventory(PROMPT_CONTRACTS.map(({ name }) => name), prompts.prompts.map(({ name }) => name)),
+        resources: compareInventory(MCP_RESOURCE_CATALOG.map(({ name }) => name), resources.resources.map(({ name }) => name)),
+        resource_templates: compareInventory(MCP_RESOURCE_TEMPLATE_CATALOG.map(({ name }) => name), templates.resourceTemplates.map(({ name }) => name)),
+    };
+    const observedIdentity = parseIdentityResource(identity.contents);
+    const serverVersion = client.getServerVersion();
+    const protocolVersion = client.getNegotiatedProtocolVersion();
+    const checks = [
+        {
+            name: "initialize",
+            ok: serverVersion?.name === PRODUCT_IDENTITY.mcpServerKey &&
+                serverVersion.version === PRODUCT_IDENTITY.packageVersion &&
+                protocolVersion !== undefined,
+            detail: `${serverVersion?.name ?? "unknown"}@${serverVersion?.version ?? "unknown"}; protocol=${protocolVersion ?? "unknown"}`,
+        },
+        ...Object.entries(inventory).map(([name, comparison]) => inventoryCheck(name, comparison)),
+        {
+            name: "server-identity",
+            ok: observedIdentity.packageVersion === PRODUCT_IDENTITY.packageVersion &&
+                observedIdentity.catalogDigest ===
+                    CATALOG_IDENTITY.digests.combined_sha256,
+            detail: `package=${observedIdentity.packageVersion ?? "missing"}; catalog=${observedIdentity.catalogDigest ?? "missing"}`,
+        },
+        {
+            name: "request-flow",
+            ok: requestFlow.isError !== true,
+            detail: "binary_session target-free request",
+        },
+    ];
+    return {
+        healthy: checks.every(({ ok }) => ok),
+        adapter: "production-stdio",
+        server: {
+            name: serverVersion?.name ?? null,
+            version: serverVersion?.version ?? null,
+            protocol_version: protocolVersion ?? null,
+        },
+        inventory,
+        identity: {
+            expected_package_version: PRODUCT_IDENTITY.packageVersion,
+            observed_package_version: observedIdentity.packageVersion,
+            expected_catalog_digest: CATALOG_IDENTITY.digests.combined_sha256,
+            observed_catalog_digest: observedIdentity.catalogDigest,
+        },
+        request_flow: {
+            tool: "binary_session",
+            ok: requestFlow.isError !== true,
+        },
+        checks,
+    };
+};
+/**
+ * Dispatcher entry for `rea mcp doctor`, kept separate from Incur MCP setup.
+ * @public
+ */
+export const runProductionMcpDoctorCli = async (arguments_, input) => {
+    const parsed = parseOutputArguments(arguments_);
+    if (!parsed.ok)
+        return {
+            output: `${Formatter.format({ code: "VALIDATION_ERROR", message: parsed.message }, parsed.format)}\n`,
+            exitCode: 1,
+        };
+    const result = await runProductionMcpDoctor({
+        command: process.execPath,
+        args: [resolve(input.dispatcherPath), "mcp"],
+        cwd: input.packageRoot,
+        environment: process.env,
+    });
+    return {
+        output: `${Formatter.format(result, parsed.format)}\n`,
+        exitCode: result.healthy ? 0 : 1,
+    };
+};
+/** Compare exact names while retaining actionable mismatch locations. */
+export const compareInventory = (expectedNames, observedNames) => {
+    const expected = new Set(expectedNames);
+    const observed = new Set(observedNames);
+    return {
+        expected: expectedNames.length,
+        observed: observedNames.length,
+        missing: [...expected].filter((name) => !observed.has(name)).sort(),
+        unexpected: [...observed].filter((name) => !expected.has(name)).sort(),
+        duplicates: [...observed]
+            .filter((name) => observedNames.filter((candidate) => candidate === name).length > 1)
+            .sort(),
+    };
+};
+const inventoryCheck = (name, comparison) => ({
+    name: `inventory:${name}`,
+    ok: comparison.expected === comparison.observed &&
+        comparison.missing.length === 0 &&
+        comparison.unexpected.length === 0 &&
+        comparison.duplicates.length === 0,
+    detail: `expected=${String(comparison.expected)} observed=${String(comparison.observed)} missing=${comparison.missing.join(",") || "none"} unexpected=${comparison.unexpected.join(",") || "none"} duplicates=${comparison.duplicates.join(",") || "none"}`,
+});
+const parseIdentityResource = (contents) => {
+    const first = contents.find((candidate) => isRecord(candidate) && typeof candidate.text === "string");
+    if (!isRecord(first) || typeof first.text !== "string")
+        return { packageVersion: null, catalogDigest: null };
+    try {
+        const identity = JSON.parse(first.text);
+        if (!isRecord(identity))
+            return { packageVersion: null, catalogDigest: null };
+        const packageIdentity = identity.package;
+        const catalog = identity.catalog;
+        const digests = isRecord(catalog) ? catalog.digests : undefined;
+        return {
+            packageVersion: isRecord(packageIdentity) && typeof packageIdentity.version === "string"
+                ? packageIdentity.version
+                : null,
+            catalogDigest: isRecord(digests) && typeof digests.combined_sha256 === "string"
+                ? digests.combined_sha256
+                : null,
+        };
+    }
+    catch {
+        return { packageVersion: null, catalogDigest: null };
+    }
+};
+const parseOutputArguments = (arguments_) => {
+    let format = "toon";
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const argument = arguments_[index];
+        if (argument === "--json") {
+            format = "json";
+            continue;
+        }
+        const inline = argument?.startsWith("--format=")
+            ? argument.slice("--format=".length)
+            : undefined;
+        if (argument === "--format" || inline !== undefined) {
+            const candidate = inline ?? arguments_[index + 1];
+            if (inline === undefined)
+                index += 1;
+            if (!isOutputFormat(candidate))
+                return {
+                    ok: false,
+                    format,
+                    message: `Invalid output format: ${candidate ?? "missing"}`,
+                };
+            format = candidate;
+            continue;
+        }
+        if (argument === "--full-output")
+            continue;
+        return {
+            ok: false,
+            format,
+            message: `Unknown mcp doctor option: ${argument ?? "missing"}`,
+        };
+    }
+    return { ok: true, format };
+};
+const isOutputFormat = (value) => OUTPUT_FORMATS.some((candidate) => candidate === value);
+const requestOptions = (deadline, signal) => ({
+    signal,
+    timeout: Math.max(1, deadline - Date.now()),
+});
+const targetFreeEnvironment = (environment) => {
+    const result = Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+    for (const name of [
+        "HOPPER_TARGET_PATH",
+        "HOPPER_TARGET_KIND",
+        "HOPPER_LOADER_ARGS_JSON",
+    ])
+        delete result[name];
+    return result;
+};
+const boundedStderr = () => {
+    let text = "";
+    let bytes = 0;
+    let truncated = false;
+    return {
+        append(chunk) {
+            const buffer = Buffer.isBuffer(chunk)
+                ? chunk
+                : Buffer.from(String(chunk), "utf8");
+            bytes += buffer.byteLength;
+            const retained = Buffer.byteLength(text, "utf8");
+            if (retained < STDERR_LIMIT_BYTES)
+                text += buffer
+                    .subarray(0, STDERR_LIMIT_BYTES - retained)
+                    .toString("utf8");
+            if (bytes > STDERR_LIMIT_BYTES)
+                truncated = true;
+        },
+        value: () => ({
+            stderr: text,
+            stderr_bytes: bytes,
+            stderr_truncated: truncated,
+        }),
+    };
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+class TrackedStdioClientTransport extends StdioClientTransport {
+    spawnedPid = null;
+    async start() {
+        await super.start();
+        this.spawnedPid = this.pid;
+    }
+}
+const closeMcpChild = async (client, transport) => {
+    const pid = transport.spawnedPid ?? transport.pid;
+    await Promise.allSettled([client.close()]);
+    await Promise.allSettled([transport.close()]);
+    if (pid === null || !(await processExists(pid)))
+        return;
+    await terminateProcess(pid, "SIGTERM");
+    if (await waitForProcessExit(pid, 1_000))
+        return;
+    await terminateProcess(pid, "SIGKILL");
+    await waitForProcessExit(pid, 1_000);
+};
+const terminateProcess = async (pid, signal) => {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && "code" in cause && cause.code === "ESRCH"))
+            throw cause;
+    }
+};
+const waitForProcessExit = async (pid, timeoutMs) => {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if (!(await processExists(pid)))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    } while (Date.now() < deadline);
+    return !(await processExists(pid));
+};
+const processExists = async (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ESRCH")
+            return false;
+        throw cause;
+    }
+};