rea-agents 1.3.0 → 1.4.0

package/dist/hopper/BridgeLauncher.js

@@ -30,11 +30,13 @@ export class HopperApplicationLauncher {
     }
     async launch(session, options = {}) {
         const bootstrapPath = `${session.directory}/bootstrap.py`;
+        const ownsProcessLifetime = usesLinuxDemo(this.options);
         const source = [
             `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
             `REA_TOKEN = ${JSON.stringify(session.token)}`,
             `REA_RUN_ID = ${JSON.stringify(session.runId)}`,
             `REA_TARGET_PATH = ${JSON.stringify(this.options.targetPath)}`,
+            `REA_OWNS_PROCESS_LIFETIME = ${ownsProcessLifetime ? "True" : "False"}`,
             `exec(compile(open(${JSON.stringify(this.options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(this.options.bridgeScriptPath)}, 'exec'))`,
             "",
         ].join("\n");
@@ -88,6 +90,7 @@ export class HopperApplicationLauncher {
             return ok({
                 process: child,
                 ownsProcessLifetime: true,
+                shutdownByCleanup: ownsProcessLifetime,
                 cleanup: () => cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, ownershipCommand)),
             });
         }
@@ -97,9 +100,7 @@ export class HopperApplicationLauncher {
     }
 }
 const linuxDemoLaunch = (options, session, hopperArgs) => {
-    if (process.platform !== "linux" ||
-        basename(options.launcherPath) !== "Hopper" ||
-        options.demoHelperPath === undefined)
+    if (!usesLinuxDemo(options) || options.demoHelperPath === undefined)
         return undefined;
     return {
         command: "/usr/bin/python3",
@@ -116,6 +117,9 @@ const linuxDemoLaunch = (options, session, hopperArgs) => {
         ],
     };
 };
+const usesLinuxDemo = (options) => process.platform === "linux" &&
+    basename(options.launcherPath) === "Hopper" &&
+    options.demoHelperPath !== undefined;
 const spawnLauncher = async (command, args, runId) => {
     const child = spawn(command, args, {
         stdio: ["ignore", "ignore", "pipe"],

package/dist/hopper/HopperClient.js

@@ -107,16 +107,30 @@ export class HopperClient {
         this.#closing = true;
         try {
             const socket = this.#socket;
+            let cleanupAttempted = false;
             if (socket !== undefined && !socket.destroyed) {
                 const shutdown = await this.#request("shutdown", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }).catch(() => err(new HopperProcessError(null)));
-                if (!shutdown.ok || !isShutdownAcknowledgement(shutdown.value))
+                if (shutdown.ok &&
+                    isCleanupRequired(shutdown.value) &&
+                    this.#launch?.shutdownByCleanup === true &&
+                    this.#launch.cleanup !== undefined) {
+                    cleanupAttempted = true;
+                    const cleanup = await this.#launch.cleanup();
+                    if (!cleanup.cleaned) {
+                        await this.#fallbackDocumentShutdown();
+                        const retried = await this.#launch.cleanup();
+                        if (!retried.cleaned)
+                            this.#logger.warn({ reason: retried.reason }, "Owned launcher cleanup failed closed");
+                    }
+                }
+                else if (!shutdown.ok || !isShutdownAcknowledgement(shutdown.value))
                     this.#logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown was not confirmed");
             }
             this.#failAll(new HopperProcessError(null));
             socket?.destroy();
             this.#socket = undefined;
             if (this.#launch?.ownsProcessLifetime === true) {
-                if (this.#launch.cleanup !== undefined) {
+                if (this.#launch.cleanup !== undefined && !cleanupAttempted) {
                     const cleanup = await this.#launch.cleanup();
                     if (!cleanup.cleaned)
                         this.#logger.warn({ reason: cleanup.reason }, "Owned launcher cleanup failed closed");
@@ -137,6 +151,11 @@ export class HopperClient {
             this.#closePromise = undefined;
         }
     }
+    async #fallbackDocumentShutdown() {
+        const fallback = await this.#request("shutdown_document", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }).catch(() => err(new HopperProcessError(null)));
+        if (!fallback.ok || !isShutdownAcknowledgement(fallback.value))
+            this.#logger.warn({ status: fallback.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown fallback was not confirmed");
+    }
     async #connect(socketPath, signal) {
         const deadline = Date.now() + this.#options.startupTimeoutMs;
         while (Date.now() < deadline) {
@@ -319,12 +338,20 @@ const connectOnce = async (socketPath) => new Promise((resolve) => {
         resolve(err(new HopperStartError({ cause })));
     });
 });
-const isShutdownAcknowledgement = (value) => typeof value === "object" &&
+const isShutdownAcknowledgement = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    if (value.shutdown !== true)
+        return false;
+    if (value.analysis_stopped === true && value.document_closed === true)
+        return true;
+    return false;
+};
+const isCleanupRequired = (value) => typeof value === "object" &&
     value !== null &&
     !Array.isArray(value) &&
     value.shutdown === true &&
-    value.analysis_stopped === true &&
-    value.document_closed === true;
+    value.cleanup_required === true;
 const parseServerInfo = (value, expectedRunId) => {
     if (typeof value === "object" &&
         value !== null &&

package/dist/identity.js

@@ -5,12 +5,19 @@
  */
 export const PRODUCT_IDENTITY = {
     displayName: "REA",
-    packageName: "rea-agents",
-    packageVersion: "1.1.0",
+    packageName: PACKAGE_METADATA.name,
+    packageVersion: PACKAGE_METADATA.version,
     cliBinary: "rea",
     mcpCommand: "npx -y rea-agents mcp",
     mcpServerKey: "rea",
     skillName: "rea-analysis",
-    skillVersion: "10",
+    skillVersion: PACKAGE_METADATA.skillVersion,
     configFileName: "rea.json",
 };
+/** Exact SDK package identities, distinct from negotiated protocol version. */
+export const SDK_IDENTITY = {
+    server: PACKAGE_METADATA.serverSdkVersion,
+    client_test: PACKAGE_METADATA.clientSdkVersion,
+    core: PACKAGE_METADATA.coreSdkVersion,
+};
+import { PACKAGE_METADATA } from "./generatedPackageMetadata.js";

package/dist/logger.js

@@ -5,7 +5,7 @@ const logLevelSchema = z
     .default("info");
 /** Parse the optional REA_LOG_LEVEL environment variable. */
 export const parseLogLevel = (value) => logLevelSchema.parse(value);
-/** Create a JSON logger whose destination cannot corrupt MCP stdout frames. */
+/** Create a JSON logger on stderr so protocol and CLI result stdout stay valid. */
 export const createLogger = (mode, level) => pino({
     level,
     base: { application: "rea", mode },
@@ -22,6 +22,6 @@ export const createLogger = (mode, level) => pino({
         ],
         censor: "[Redacted]",
     },
-}, pino.destination({ dest: mode === "mcp" ? 2 : 1, sync: false }));
+}, pino.destination({ dest: 2, sync: false }));
 /** Logger used by embedders that have not opted into process output. */
 export const silentLogger = pino({ level: "silent" });

package/dist/main.js

@@ -7,6 +7,8 @@ import { createBinarySession } from "./application/runtime.js";
 import { createServer } from "./server/createServer.js";
 import { createLogger } from "./logger.js";
 import { projectAnalysisError } from "./domain/errors.js";
+import { readProjectPermissionStore } from "./application/ProjectPermissionStore.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 const MCP_CONNECTION_LOST = "REA lost its MCP client connection. Restart REA from your MCP client.";
 const MCP_CONNECTION_START_FAILED = "REA could not start its MCP connection. Restart REA from your MCP client; run `rea doctor` if it fails again.";
 const MCP_SHUTDOWN_FAILED = "REA could not close cleanly. End the REA process before starting it again.";
@@ -24,6 +26,10 @@ const runtimeDependencies = () => ({
         process.stdin.once("end", handler);
         process.stdin.once("close", handler);
     },
+    registerReload: (handler) => {
+        process.on("SIGHUP", handler);
+        return () => process.off("SIGHUP", handler);
+    },
 });
 /**
  * Start the long-lived MCP adapter and install idempotent shutdown handlers.
@@ -38,6 +44,11 @@ export const run = async (dependencies = runtimeDependencies()) => {
     }
     const logger = createLogger("mcp", config.value.logLevel);
     const serverLogger = logger.child({ layer: "server" });
+    const permissionAuthority = await loadConfiguredPermissionAuthority(config.value);
+    if (!permissionAuthority.ok) {
+        dependencies.writeStderr(`${projectAnalysisError(permissionAuthority.error).message}\n`);
+        return 1;
+    }
     const session = createBinarySession(config.value, logger);
     if (config.value.hopperTargetPath !== undefined) {
         const opened = await session.open(config.value.hopperTargetPath, {
@@ -50,15 +61,44 @@ export const run = async (dependencies = runtimeDependencies()) => {
             return 1;
         }
     }
+    let currentConfig = config.value;
+    const runtimeProcessPolicy = {
+        ...config.value.processExecutionPolicy,
+        executableRoots: [...config.value.processExecutionPolicy.executableRoots],
+        workingRoots: [...config.value.processExecutionPolicy.workingRoots],
+        allowedEnvironment: [
+            ...config.value.processExecutionPolicy.allowedEnvironment,
+        ],
+    };
+    const runtimeEvidencePolicy = {
+        ...config.value.evidenceFilePolicy,
+        roots: [...config.value.evidenceFilePolicy.roots],
+    };
+    const runtimeSnapshotPolicy = {
+        ...config.value.analysisSnapshotFilePolicy,
+        roots: [...config.value.analysisSnapshotFilePolicy.roots],
+    };
+    const runtimeInvestigationRoots = [...config.value.investigationInputRoots];
+    const liveServers = new Set();
     let handle;
     try {
-        handle = dependencies.serve(() => createServer(session, session, {
-            logger,
-            processPolicy: config.value.processExecutionPolicy,
-            evidenceFilePolicy: config.value.evidenceFilePolicy,
-            investigationInputRoots: config.value.investigationInputRoots,
-            analysisSnapshotFilePolicy: config.value.analysisSnapshotFilePolicy,
-        }), {
+        handle = dependencies.serve(() => {
+            const server = createServer(session, session, {
+                logger,
+                processPolicy: runtimeProcessPolicy,
+                evidenceFilePolicy: runtimeEvidencePolicy,
+                investigationInputRoots: runtimeInvestigationRoots,
+                analysisSnapshotFilePolicy: runtimeSnapshotPolicy,
+                permissionAuthority: permissionAuthority.value,
+                artifactIntegrityContinueEnabled: () => currentConfig.artifactIntegrityContinueEnabled,
+                availabilityPolicy: () => ({
+                    processCaptureEnabled: currentConfig.processExecutionPolicy.enabled,
+                    evidenceFileRoots: currentConfig.evidenceFilePolicy.roots.length,
+                }),
+            });
+            liveServers.add(server);
+            return server;
+        }, {
             onerror: () => {
                 serverLogger.error(MCP_CONNECTION_LOST);
                 dependencies.writeStderr(`${MCP_CONNECTION_LOST}\n`);
@@ -71,11 +111,59 @@ export const run = async (dependencies = runtimeDependencies()) => {
         dependencies.writeStderr(`${MCP_CONNECTION_START_FAILED}\n`);
         return 1;
     }
+    const unregisterReload = dependencies.registerReload?.(() => {
+        void (async () => {
+            const refreshed = parseConfig(dependencies.env);
+            if (!refreshed.ok) {
+                serverLogger.error("Reloaded permission policy is invalid");
+                return;
+            }
+            const reloaded = await permissionAuthority.value.reload(refreshed.value.permissionCeilings);
+            if (!reloaded.ok) {
+                serverLogger.error("Reloaded permission ceiling could not be applied");
+                return;
+            }
+            const administrators = await permissionAuthority.value.replaceAdministratorGrants(refreshed.value.administratorPermissionGrants);
+            if (!administrators.ok) {
+                serverLogger.error("Reloaded administrator grants could not be applied");
+                return;
+            }
+            if (refreshed.value.permissionProjectRoot !== undefined &&
+                refreshed.value.permissionProjectStore !== undefined) {
+                const project = await readProjectPermissionStore(refreshed.value.permissionProjectStore, refreshed.value.permissionProjectRoot);
+                if (!project.ok) {
+                    serverLogger.error("Reloaded project grants could not be read");
+                    return;
+                }
+                const projects = await permissionAuthority.value.replaceProjectGrants(project.value?.grants ?? []);
+                if (!projects.ok) {
+                    serverLogger.error("Reloaded project grants could not be applied");
+                    return;
+                }
+            }
+            else {
+                const projects = await permissionAuthority.value.replaceProjectGrants([]);
+                if (!projects.ok) {
+                    serverLogger.error("Reloaded project grants could not be cleared");
+                    return;
+                }
+            }
+            currentConfig = refreshed.value;
+            Object.assign(runtimeProcessPolicy, refreshed.value.processExecutionPolicy);
+            Object.assign(runtimeEvidencePolicy, refreshed.value.evidenceFilePolicy);
+            Object.assign(runtimeSnapshotPolicy, refreshed.value.analysisSnapshotFilePolicy);
+            runtimeInvestigationRoots.splice(0, runtimeInvestigationRoots.length, ...refreshed.value.investigationInputRoots);
+            for (const server of liveServers)
+                server.sendToolListChanged();
+        })();
+    }) ?? (() => undefined);
     let shutdownPromise;
     const shutdown = () => {
         shutdownPromise ??= (async () => {
+            unregisterReload();
             await handle.close();
             await session.close();
+            permissionAuthority.value.clearSessionGrants();
         })();
         return shutdownPromise;
     };

package/dist/server/createServer.js

@@ -7,24 +7,63 @@ import { registerNativeTools } from "./registerNativeTools.js";
 import { registerArtifactTools } from "./registerArtifactTools.js";
 import { silentLogger } from "../logger.js";
 import { registerGuidedPrompts } from "./registerPrompts.js";
+import { registerEvidenceResources } from "./registerEvidenceResources.js";
+import { createServerIdentity } from "../serverIdentity.js";
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
  * fixed-target seam used by focused tests and embedders.
  */
 export const createServer = (analysis, session, options = {}) => {
+    const startedAt = new Date().toISOString();
     const logger = options.logger ?? silentLogger;
-    const server = new McpServer({ name: PRODUCT_IDENTITY.mcpServerKey, version: "0.1.0" }, {
-        capabilities: { tools: {} },
+    const server = new McpServer({
+        name: PRODUCT_IDENTITY.mcpServerKey,
+        version: PRODUCT_IDENTITY.packageVersion,
+    }, {
+        capabilities: {
+            tools: { listChanged: true },
+            resources: { listChanged: true },
+        },
         instructions: session === undefined
             ? "Reverse-engineering tools for an active analysis target. Start with binary_overview."
             : "Reverse-engineering tools for configured analysis providers. Open a target with open_binary, then start with binary_overview.",
     });
+    session?.onAvailabilityChanged?.(() => server.sendToolListChanged());
+    server.registerResource("server-identity", "rea://server/identity", {
+        title: "REA server identity",
+        description: "Live package, SDK, protocol, and catalog identity.",
+        mimeType: "application/json",
+    }, (uri) => {
+        const client = server.server.getClientVersion();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(createServerIdentity({
+                        startedAt,
+                        ...(client === undefined ? {} : { client }),
+                        ...(server.server.getNegotiatedProtocolVersion() === undefined
+                            ? {}
+                            : {
+                                protocolVersion: server.server.getNegotiatedProtocolVersion(),
+                            }),
+                    }), null, 2),
+                },
+            ],
+        };
+    });
     const toolLogger = logger.child({ layer: "server" });
     const activeTarget = session === undefined ? undefined : () => session.activeTarget();
     const recordEvidence = session === undefined
         ? undefined
-        : (evidence) => session.recordEvidence(evidence);
+        : (evidence) => {
+            const recorded = session.recordEvidence(evidence);
+            if (recorded.ok && recorded.value === "added")
+                server.sendResourceListChanged();
+            return recorded;
+        };
     registerOfficialTools(server, analysis, {
         logger: toolLogger,
         activeTarget,
@@ -50,9 +89,17 @@ export const createServer = (analysis, session, options = {}) => {
         logger: toolLogger,
         activeTarget,
         recordEvidence,
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
     });
     registerGuidedPrompts(server, analysis, session);
-    if (session !== undefined)
-        registerSessionTools(server, session, toolLogger, options);
+    if (session !== undefined) {
+        registerEvidenceResources(server, session);
+        registerSessionTools(server, session, toolLogger, {
+            ...options,
+            startedAt,
+        });
+    }
     return server;
 };

package/dist/server/mcpProgress.js

@@ -0,0 +1,23 @@
+import { createProgressReporter, silentProgressReporter, } from "../application/ProgressReporter.js";
+/** Adapt the request's negotiated MCP progress token to application progress. */
+export const mcpProgressReporter = (context) => {
+    const token = context.mcpReq._meta?.progressToken;
+    if (token === undefined)
+        return silentProgressReporter;
+    return createProgressReporter(async (update) => {
+        try {
+            await context.mcpReq.notify({
+                method: "notifications/progress",
+                params: {
+                    progressToken: token,
+                    progress: update.completed,
+                    ...(update.total === null ? {} : { total: update.total }),
+                    message: `${update.phase}: ${update.message}`,
+                },
+            });
+        }
+        catch {
+            // Progress is observational; transport failure cannot change tool truth.
+        }
+    }, { minimumIntervalMs: 100 });
+};

package/dist/server/registerArtifactComparisonTool.js

@@ -6,9 +6,10 @@ import { resolveSessionEvidence } from "./sessionEvidence.js";
 import { ARTIFACT_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
 import { toCallToolResult } from "./toolResult.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runDerivedOperation } from "./runDerivedOperation.js";
 /** Register Evidence-backed deterministic artifact comparison. */
 export const registerArtifactComparisonTool = (server, session, contract) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
         const parsed = artifactComparisonInputSchema.parse(input);
         const left = resolveSessionEvidence(session, parsed.left);
         if (!left.ok)
@@ -16,7 +17,10 @@ export const registerArtifactComparisonTool = (server, session, contract) => {
         const right = resolveSessionEvidence(session, parsed.right);
         if (!right.ok)
             return toCallToolResult(right, contract);
-        const comparison = compareArtifacts(left.value, right.value, parsed.offset, parsed.limit);
+        const computed = await runDerivedOperation(context, contract.name, () => compareArtifacts(left.value, right.value, parsed.offset, parsed.limit));
+        if (!computed.ok)
+            return toCallToolResult(computed, contract);
+        const comparison = computed.value;
         const leftEvidenceIds = evidenceIds(parsed.left);
         const rightEvidenceIds = evidenceIds(parsed.right);
         const evidence = createEvidence(undefined, ARTIFACT_COMPARISON_PROVIDER, {

package/dist/server/registerBundleComparisonTool.js

@@ -7,9 +7,10 @@ import { BUNDLE_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
 import { toCallToolResult } from "./toolResult.js";
 import { isSessionEvidence } from "./sessionEvidence.js";
 import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { runDerivedOperation } from "./runDerivedOperation.js";
 /** Register canonical Evidence bundle comparison. */
 export const registerBundleComparisonTool = (server, session, contract) => {
-    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
         const parsed = bundleComparisonInputSchema.parse(input);
         const sourceIds = [
             ...new Set([
@@ -24,7 +25,10 @@ export const registerBundleComparisonTool = (server, session, contract) => {
             .unknowns.map(({ revision_digest: digest }) => digest));
         if ([...parsed.left.unknowns, ...parsed.right.unknowns].some(({ revision_digest: digest }) => !ownedUnknownDigests.has(digest)))
             return toCallToolResult(err(new EvidenceIntegrityError("Bundle comparison input unknown history is not present in this session")), contract);
-        const comparison = compareBundles(parsed.left, parsed.right, parsed.record_pairs, parsed.offset, parsed.limit);
+        const computed = await runDerivedOperation(context, contract.name, () => compareBundles(parsed.left, parsed.right, parsed.record_pairs, parsed.offset, parsed.limit));
+        if (!computed.ok)
+            return toCallToolResult(computed, contract);
+        const comparison = computed.value;
         const evidence = createEvidence(undefined, BUNDLE_COMPARISON_PROVIDER, {
             predicateType: "rea.bundle-comparison/v1",
             operation: contract.name,

package/dist/server/registerEnhancedTools.js

@@ -7,6 +7,7 @@ import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
 import { UnknownRegistryError } from "../domain/errors.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
 const WORKFLOW_PROVIDER = {
     id: "rea-workflow",
     name: "REA composed investigation workflow",
@@ -32,9 +33,23 @@ const registerEnhancedTool = (server, services, contract, registration) => {
         outputSchema: contract.outputSchema,
         annotations: contract.annotations,
     }, async (input, context) => {
+        const progress = mcpProgressReporter(context);
+        await progress.report({
+            phase: name,
+            completed: 0,
+            total: 1,
+            message: "started",
+        });
         const parsedInput = jsonObjectSchema.parse(enhancedInputSchemas[name].parse(input));
         const parameters = { ...parsedInput };
         const result = await logToolExecution(registration.logger, name, () => services.execute(name, input, context.mcpReq.signal));
+        await progress.report({
+            phase: name,
+            completed: 1,
+            total: 1,
+            message: result.ok ? "completed" : "failed",
+            terminal: true,
+        });
         if (result.ok) {
             const evidence = createEvidence(registration.activeTarget?.(), WORKFLOW_PROVIDER, {
                 operation: name,
@@ -57,7 +72,9 @@ const registerEnhancedTool = (server, services, contract, registration) => {
             });
             if (!unknowns.ok)
                 return toCallToolResult(unknowns, contract);
-            return toCallToolResult({ ok: true, value: evidence }, contract);
+            return toCallToolResult({ ok: true, value: evidence }, contract, {
+                evidenceResourcesAvailable: recorded !== undefined,
+            });
         }
         return toCallToolResult(result, contract);
     });