rea-agents 1.3.0 → 1.4.0

package/dist/server/registerSessionStatusTool.js

@@ -1,11 +1,52 @@
-import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { binarySessionInputSchema, SESSION_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
 import { toCallToolResult } from "./toolResult.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { createServerIdentity } from "../serverIdentity.js";
+import { buildCapabilityInventory } from "../application/CapabilityInventory.js";
 /** Register the read-only provider and target status operation. */
-export const registerSessionStatusTool = (server, session, contract) => {
+export const registerSessionStatusTool = (server, session, contract, startedAt, availabilityPolicy) => {
     server.registerTool(contract.name, {
         description: contract.description,
         inputSchema: contract.inputSchema,
         outputSchema: contract.outputSchema,
         annotations: contract.annotations,
-    }, () => toCallToolResult({ ok: true, value: session.status() }, contract));
+    }, (input) => {
+        const parsed = binarySessionInputSchema.parse(input);
+        const client = server.server.getClientVersion();
+        const clientCapabilities = server.server.getClientCapabilities();
+        const status = session.status();
+        return toCallToolResult({
+            ok: true,
+            value: {
+                ...jsonObjectSchema.parse(status),
+                tool_availability: buildCapabilityInventory(status, availabilityPolicy()),
+                client_features: {
+                    elicitation_form: clientCapabilities?.elicitation?.form !== undefined,
+                    elicitation_url: clientCapabilities?.elicitation?.url !== undefined,
+                    roots: clientCapabilities?.roots !== undefined,
+                    sampling: clientCapabilities?.sampling !== undefined,
+                },
+                server_identity: createServerIdentity({
+                    startedAt,
+                    expected: {
+                        ...(parsed.expected_package_version === undefined
+                            ? {}
+                            : { package_version: parsed.expected_package_version }),
+                        ...(parsed.expected_catalog_digest === undefined
+                            ? {}
+                            : { catalog_digest: parsed.expected_catalog_digest }),
+                        ...(parsed.expected_server_path === undefined
+                            ? {}
+                            : { server_path: parsed.expected_server_path }),
+                    },
+                    ...(client === undefined ? {} : { client }),
+                    ...(server.server.getNegotiatedProtocolVersion() === undefined
+                        ? {}
+                        : {
+                            protocolVersion: server.server.getNegotiatedProtocolVersion(),
+                        }),
+                }),
+            },
+        }, contract);
+    });
 };

package/dist/server/registerSessionTools.js

@@ -2,13 +2,13 @@ import { z } from "zod";
 import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
-import { ok } from "../domain/result.js";
+import { err, ok } from "../domain/result.js";
 import { processScenarioSchema } from "../domain/processCapture.js";
 import { captureProcessScenario } from "../application/ProcessHarness.js";
 import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
 import { readEvidenceBundle, writeEvidenceBundle, } from "../application/EvidenceBundleFiles.js";
 import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "../application/AnalysisSnapshotFiles.js";
-import { UnknownRegistryError } from "../domain/errors.js";
+import { AnalysisProtocolError, PermissionRequiredError, UnknownRegistryError, } from "../domain/errors.js";
 import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, } from "./sessionToolPolicies.js";
 import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js";
 import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
@@ -18,6 +18,16 @@ import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js"
 import { registerInvestigationTools } from "./registerInvestigationTools.js";
 import { closeBinaryInputSchema, openBinaryInputSchema, } from "../contracts/sessionLifecycleInputs.js";
 import { registerSessionStatusTool } from "./registerSessionStatusTool.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+const permissionFailure = (failure) => {
+    if (failure.ok)
+        return err(new AnalysisProtocolError("Expected a denied permission"));
+    return err(failure.error instanceof PermissionRequiredError
+        ? failure.error
+        : new AnalysisProtocolError(failure.error.message, {
+            cause: failure.error,
+        }));
+};
 const recordProcessResidualUnknowns = (session, scenario, evidence, residuals) => {
     if (scenario.unknown_registry_approved !== true)
         return ok(null);
@@ -47,7 +57,7 @@ const recordProcessResidualUnknowns = (session, scenario, evidence, residuals) =
     }
     return ok(null);
 };
-const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, }) => {
+const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, permissionAuthority, }) => {
     server.registerTool(captureContract.name, {
         description: captureContract.description,
         inputSchema: captureContract.inputSchema,
@@ -55,7 +65,37 @@ const registerProcessTools = ({ server, session, logger, processPolicy, captureC
         annotations: captureContract.annotations,
     }, async (input, context) => {
         const scenario = processScenarioSchema.parse(input);
+        if (permissionAuthority !== undefined) {
+            const authorized = await permissionAuthority.authorize({
+                capability: "process_capture",
+                roots: [scenario.working_directory, ...scenario.filesystem_roots],
+                executables: [scenario.executable],
+                environment_names: [
+                    ...Object.keys(scenario.environment),
+                    ...scenario.inherit_environment,
+                ],
+                network: scenario.network_access === "host" ? "external" : "none",
+                mount: false,
+                operation_identity: `capture_process_scenario:${scenario.executable}`,
+            }, "read");
+            if (!authorized.ok)
+                return toCallToolResult(permissionFailure(authorized), captureContract);
+        }
+        const progress = mcpProgressReporter(context);
+        await progress.report({
+            phase: captureContract.name,
+            completed: 0,
+            total: 1,
+            message: "started",
+        });
         const captured = await logToolExecution(logger, captureContract.name, () => captureProcessScenario(scenario, processPolicy, context.mcpReq.signal));
+        await progress.report({
+            phase: captureContract.name,
+            completed: 1,
+            total: 1,
+            message: captured.ok ? "completed" : "failed",
+            terminal: true,
+        });
         if (!captured.ok)
             return toCallToolResult(captured, captureContract);
         const evidence = createProcessCaptureEvidence(scenario, captured.value);
@@ -68,7 +108,7 @@ const registerProcessTools = ({ server, session, logger, processPolicy, captureC
         return toCallToolResult(ok(evidence), captureContract);
     });
 };
-const registerEvidenceTools = ({ server, session, exportContract, importContract, filePolicy, }) => {
+const registerEvidenceTools = ({ server, session, exportContract, importContract, filePolicy, permissionAuthority, }) => {
     server.registerTool(exportContract.name, {
         description: exportContract.description,
         inputSchema: exportContract.inputSchema,
@@ -84,6 +124,19 @@ const registerEvidenceTools = ({ server, session, exportContract, importContract
         const bundle = session.exportEvidenceBundle();
         if (parsed.path === undefined)
             return toCallToolResult(ok(bundle), exportContract);
+        if (permissionAuthority !== undefined) {
+            const authorized = await permissionAuthority.authorize({
+                capability: "evidence_write",
+                roots: [parsed.path],
+                executables: [],
+                environment_names: [],
+                network: "none",
+                mount: false,
+                operation_identity: `export_evidence:${parsed.path}`,
+            }, "write");
+            if (!authorized.ok)
+                return toCallToolResult(permissionFailure(authorized), exportContract);
+        }
         const written = await writeEvidenceBundle(bundle, parsed.path, parsed.overwrite, filePolicy);
         return written.ok
             ? toCallToolResult(ok({
@@ -100,6 +153,19 @@ const registerEvidenceTools = ({ server, session, exportContract, importContract
         annotations: importContract.annotations,
     }, async (input) => {
         const path = z.object({ path: z.string().min(1) }).parse(input).path;
+        if (permissionAuthority !== undefined) {
+            const authorized = await permissionAuthority.authorize({
+                capability: "evidence_read",
+                roots: [path],
+                executables: [],
+                environment_names: [],
+                network: "none",
+                mount: false,
+                operation_identity: `import_evidence:${path}`,
+            }, "read");
+            if (!authorized.ok)
+                return toCallToolResult(permissionFailure(authorized), importContract);
+        }
         const loaded = await readEvidenceBundle(path, filePolicy);
         if (!loaded.ok)
             return toCallToolResult(loaded, importContract);
@@ -166,7 +232,7 @@ const registerUnknownTools = ({ server, session, contracts: [listContract, recor
         return toCallToolResult(session.verifyUnknownResolution(unknownId), verifyContract);
     });
 };
-const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFilePolicy, }) => {
+const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFilePolicy, startedAt, availabilityPolicy, permissionAuthority, }) => {
     const [openContract, closeContract, statusContract] = contracts;
     server.registerTool(openContract.name, {
         description: openContract.description,
@@ -177,6 +243,19 @@ const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFi
         const parsed = openBinaryInputSchema.parse(input);
         let snapshot;
         if (parsed.snapshot_path !== undefined) {
+            if (permissionAuthority !== undefined) {
+                const authorized = await permissionAuthority.authorize({
+                    capability: "snapshot_read",
+                    roots: [parsed.snapshot_path],
+                    executables: [],
+                    environment_names: [],
+                    network: "none",
+                    mount: false,
+                    operation_identity: `open_binary:snapshot:${parsed.snapshot_path}`,
+                }, "read");
+                if (!authorized.ok)
+                    return toCallToolResult(permissionFailure(authorized), openContract);
+            }
             const loaded = await readAnalysisSnapshot(parsed.snapshot_path, snapshotFilePolicy);
             if (!loaded.ok)
                 return toCallToolResult(loaded, openContract);
@@ -186,6 +265,8 @@ const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFi
             signal: context.mcpReq.signal,
             ...(snapshot === undefined ? {} : { snapshot }),
         }));
+        if (opened.ok)
+            server.sendToolListChanged();
         return opened.ok
             ? toCallToolResult({
                 ok: true,
@@ -208,6 +289,19 @@ const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFi
     }, async (input) => {
         const parsed = closeBinaryInputSchema.parse(input);
         if (parsed.snapshot_path !== undefined) {
+            if (permissionAuthority !== undefined) {
+                const authorized = await permissionAuthority.authorize({
+                    capability: "snapshot_write",
+                    roots: [parsed.snapshot_path],
+                    executables: [],
+                    environment_names: [],
+                    network: "none",
+                    mount: false,
+                    operation_identity: `close_binary:snapshot:${parsed.snapshot_path}`,
+                }, "write");
+                if (!authorized.ok)
+                    return toCallToolResult(permissionFailure(authorized), closeContract);
+            }
             const snapshot = session.exportAnalysisSnapshot();
             if (!snapshot.ok)
                 return toCallToolResult(snapshot, closeContract);
@@ -215,6 +309,8 @@ const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFi
             if (!written.ok)
                 return toCallToolResult(written, closeContract);
             const closed = await logToolExecution(logger, closeContract.name, () => session.close());
+            if (closed.ok)
+                server.sendToolListChanged();
             return closed.ok
                 ? toCallToolResult(ok({
                     path: written.value.path,
@@ -223,9 +319,12 @@ const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFi
                 }), closeContract)
                 : toCallToolResult(closed, closeContract);
         }
-        return toCallToolResult(await logToolExecution(logger, closeContract.name, () => session.close()), closeContract);
+        const closed = await logToolExecution(logger, closeContract.name, () => session.close());
+        if (closed.ok)
+            server.sendToolListChanged();
+        return toCallToolResult(closed, closeContract);
     });
-    registerSessionStatusTool(server, session, statusContract);
+    registerSessionStatusTool(server, session, statusContract, startedAt, availabilityPolicy);
 };
 export const registerSessionTools = (server, session, logger, options = {}) => {
     const processPolicy = options.processPolicy ?? DENY_PROCESS_POLICY;
@@ -238,6 +337,15 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         logger,
         contracts: [openContract, closeContract, statusContract],
         snapshotFilePolicy: analysisSnapshotFilePolicy,
+        startedAt: options.startedAt ?? new Date().toISOString(),
+        availabilityPolicy: options.availabilityPolicy ??
+            (() => ({
+                processCaptureEnabled: processPolicy.enabled,
+                evidenceFileRoots: evidenceFilePolicy.roots.length,
+            })),
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
     });
     registerEvidenceTools({
         server,
@@ -245,6 +353,9 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         exportContract,
         importContract,
         filePolicy: evidenceFilePolicy,
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
     });
     registerProcessTools({
         server,
@@ -252,6 +363,9 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         logger,
         processPolicy,
         captureContract,
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
     });
     registerProcessComparisonTool(server, session, compareContract);
     registerArtifactComparisonTool(server, session, compareArtifactsContract);
@@ -266,6 +380,14 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
     registerInvestigationTools(server, session, investigationContracts, {
         evidenceFiles: evidenceFilePolicy,
         inputRoots: options.investigationInputRoots ?? [],
+        ...(options.artifactIntegrityContinueEnabled === undefined
+            ? {}
+            : {
+                integrityContinueEnabled: options.artifactIntegrityContinueEnabled,
+            }),
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
     });
     registerUnknownTools({
         server,

package/dist/server/runDerivedOperation.js

@@ -0,0 +1,35 @@
+import { setImmediate } from "node:timers/promises";
+import { AnalysisCancelledError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+/** Run synchronous derived work with transport yields and a publication guard. */
+export const runDerivedOperation = async (context, operation, compute) => {
+    const progress = mcpProgressReporter(context);
+    await progress.report({
+        phase: "prepare",
+        completed: 0,
+        total: 2,
+        message: `Preparing ${operation}`,
+    });
+    await setImmediate();
+    if (context.mcpReq.signal.aborted)
+        return err(new AnalysisCancelledError(operation));
+    const value = compute();
+    await progress.report({
+        phase: "compute",
+        completed: 1,
+        total: 2,
+        message: `Computed ${operation}`,
+    });
+    await setImmediate();
+    if (context.mcpReq.signal.aborted)
+        return err(new AnalysisCancelledError(operation));
+    await progress.report({
+        phase: "complete",
+        completed: 2,
+        total: 2,
+        message: `Completed ${operation}`,
+        terminal: true,
+    });
+    return ok(value);
+};

package/dist/server/toolResult.js

@@ -4,7 +4,9 @@ import { AnalysisOutputError, projectAnalysisError, } from "../domain/errors.js"
  * Error tags and safe messages remain visible while underlying causes, process
  * output, and other potentially sensitive details stay private.
  */
-export const toCallToolResult = (result, contract) => result.ok ? successResult(result.value, contract) : errorResult(result.error);
+export const toCallToolResult = (result, contract, options = {}) => result.ok
+    ? successResult(result.value, contract, options)
+    : errorResult(result.error);
 const errorResult = (error) => {
     const projected = projectAnalysisError(error);
     return {
@@ -18,7 +20,7 @@ const errorResult = (error) => {
         isError: true,
     };
 };
-const successResult = (value, contract) => {
+const successResult = (value, contract, options) => {
     const candidate = contract.kind === "session" ? { result: value } : value;
     const parsed = contract.outputSchema.safeParse(candidate);
     if (!parsed.success) {
@@ -36,10 +38,32 @@ const successResult = (value, contract) => {
         };
     }
     return {
-        content: [{ type: "text", text: formatValue(value) }],
+        content: [
+            { type: "text", text: formatValue(value) },
+            ...evidenceResourceLinks(value, contract.kind === "session" ||
+                options.evidenceResourcesAvailable === true),
+        ],
         structuredContent: candidate,
     };
 };
+const evidenceResourceLinks = (value, available) => {
+    if (!available ||
+        typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        typeof value.evidence_id !== "string" ||
+        !/^ev_[a-f0-9]{64}$/u.test(value.evidence_id))
+        return [];
+    return [
+        {
+            type: "resource_link",
+            uri: `rea://evidence/${value.evidence_id}`,
+            name: value.evidence_id,
+            description: "Session-owned Evidence v2 record",
+            mimeType: "application/json",
+        },
+    ];
+};
 const formatValue = (value) => {
     if (value === null)
         return "OK";

package/dist/serverIdentity.js

@@ -0,0 +1,70 @@
+import { dirname, basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CATALOG_IDENTITY } from "./catalogIdentity.js";
+import { PRODUCT_IDENTITY, SDK_IDENTITY } from "./identity.js";
+const packageRoot = () => {
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    return basename(moduleDirectory) === "src" &&
+        basename(dirname(moduleDirectory)) === "dist"
+        ? resolve(moduleDirectory, "../..")
+        : resolve(moduleDirectory, "..");
+};
+/** Build one runtime identity without claiming alignment from absent observations. */
+export const createServerIdentity = (input) => {
+    const serverPath = resolve(process.argv[1] ?? "unknown");
+    const reasons = [];
+    if (input.expected?.package_version !== undefined &&
+        input.expected.package_version !== PRODUCT_IDENTITY.packageVersion)
+        reasons.push("package_version_mismatch");
+    if (input.expected?.catalog_digest !== undefined &&
+        input.expected.catalog_digest !== CATALOG_IDENTITY.digests.combined_sha256)
+        reasons.push("catalog_digest_mismatch");
+    if (input.expected?.server_path !== undefined &&
+        resolve(input.expected.server_path) !== serverPath)
+        reasons.push("registration_path_mismatch");
+    const observedExpectation = input.expected !== undefined &&
+        Object.values(input.expected).some((value) => value !== undefined);
+    return {
+        package: {
+            name: PRODUCT_IDENTITY.packageName,
+            version: PRODUCT_IDENTITY.packageVersion,
+            root_path: packageRoot(),
+            build_commit: process.env.REA_BUILD_COMMIT ?? null,
+        },
+        server: {
+            name: PRODUCT_IDENTITY.mcpServerKey,
+            version: PRODUCT_IDENTITY.packageVersion,
+            started_at: input.startedAt,
+            command_path: serverPath,
+        },
+        sdk: SDK_IDENTITY,
+        negotiated_protocol_version: input.protocolVersion ?? null,
+        client: input.client === undefined
+            ? null
+            : { name: input.client.name, version: input.client.version },
+        skill: {
+            name: PRODUCT_IDENTITY.skillName,
+            expected_version: PRODUCT_IDENTITY.skillVersion,
+        },
+        catalog: CATALOG_IDENTITY,
+        protocol_features: {
+            progress: true,
+            cancellation: true,
+            evidence_resources: true,
+            elicitation: false,
+        },
+        alignment: {
+            state: reasons.length > 0
+                ? "mcp_server_restart_required"
+                : observedExpectation
+                    ? "aligned"
+                    : "unknown",
+            reasons,
+            remediation: reasons.length > 0
+                ? "Restart the registered MCP server/client, then compare identity again."
+                : observedExpectation
+                    ? null
+                    : "Supply expected package, catalog, or registration identity to compare the live server.",
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -49,6 +49,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "prebuild": "node scripts/generate-package-metadata.mjs",
     "build": "tsc -p tsconfig.build.json",
     "check": "npm run typecheck && npm run lint && npm run format:check && npm test",
     "format": "prettier --write .",
@@ -76,7 +77,8 @@
     "verify:package": "npm run build && node scripts/verify-package.mjs",
     "verify:published": "node scripts/verify-published-package.mjs",
     "config:print": "node scripts/print-mcp-config.mjs",
-    "docs:generate": "typedoc",
+    "docs:generate": "npm run build && typedoc && node scripts/generate-error-schema.mjs",
+    "docs:error-schema": "npm run build && node scripts/generate-error-schema.mjs",
     "prepack": "npm run build",
     "prepare": "husky",
     "rebuild:native": "node scripts/rebuild-native.mjs"
@@ -89,7 +91,7 @@
     "@babel/parser": "8.0.4",
     "@babel/types": "8.0.4",
     "@electron/asar": "4.2.0",
-    "@modelcontextprotocol/server": "2.0.0-beta.3",
+    "@modelcontextprotocol/server": "2.0.0-beta.4",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
     "@zip.js/zip.js": "2.8.26",
@@ -110,7 +112,7 @@
   },
   "devDependencies": {
     "@fast-check/vitest": "0.4.1",
-    "@modelcontextprotocol/client": "2.0.0-beta.3",
+    "@modelcontextprotocol/client": "2.0.0-beta.4",
     "@types/node": "24.10.1",
     "@types/write-file-atomic": "4.0.3",
     "@types/ws": "8.18.1",