rea-agents 6.2.0 → 6.3.0

package/dist/process/capture/FilesystemSnapshot.js

@@ -13,6 +13,23 @@ const hasSameFileState = (before, after) => before.dev === after.dev &&
     before.size === after.size &&
     before.mtimeMs === after.mtimeMs &&
     before.ctimeMs === after.ctimeMs;
+const fileUnavailableSystemCode = (cause) => {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return undefined;
+    const code = cause.code;
+    return typeof code === "string" &&
+        [
+            "EACCES",
+            "EISDIR",
+            "ELOOP",
+            "ENOTDIR",
+            "ENOENT",
+            "EPERM",
+            "ESTALE",
+        ].includes(code)
+        ? code
+        : undefined;
+};
 const lstatIfPresent = async (path) => {
     try {
         return await lstat(path);
@@ -26,15 +43,33 @@ const lstatIfPresent = async (path) => {
 /** Hash a file only when its opened descriptor still matches the captured path state. */
 export const hashFile = async (path, expected, maxBytes, signal) => {
     signal?.throwIfAborted();
-    const handle = await open(path, fsConstants.O_RDONLY |
-        (fsConstants.O_NOFOLLOW ?? 0) |
-        (fsConstants.O_NONBLOCK ?? 0));
+    let handle;
+    try {
+        handle = await open(path, fsConstants.O_RDONLY |
+            (fsConstants.O_NOFOLLOW ?? 0) |
+            (fsConstants.O_NONBLOCK ?? 0));
+    }
+    catch (cause) {
+        signal?.throwIfAborted();
+        const systemCode = fileUnavailableSystemCode(cause);
+        if (systemCode === undefined)
+            throw cause;
+        return {
+            state: "omitted",
+            reason: "file_unavailable",
+            system_code: systemCode,
+        };
+    }
     try {
         signal?.throwIfAborted();
         const stats = await handle.stat();
         signal?.throwIfAborted();
         if (!hasSameFileState(expected, stats) || stats.size > maxBytes)
-            return null;
+            return {
+                state: "omitted",
+                reason: "file_changed_or_short_read",
+                system_code: null,
+            };
         const hash = createHash("sha256");
         const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes));
         let position = 0;
@@ -42,15 +77,34 @@ export const hashFile = async (path, expected, maxBytes, signal) => {
             signal?.throwIfAborted();
             const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, stats.size - position), position);
             if (bytesRead === 0)
-                return null;
+                return {
+                    state: "omitted",
+                    reason: "file_changed_or_short_read",
+                    system_code: null,
+                };
             hash.update(buffer.subarray(0, bytesRead));
             position += bytesRead;
         }
         const after = await handle.stat();
         signal?.throwIfAborted();
         if (!hasSameFileState(stats, after))
-            return null;
-        return hash.digest("hex");
+            return {
+                state: "omitted",
+                reason: "file_changed_or_short_read",
+                system_code: null,
+            };
+        return { state: "hashed", sha256: hash.digest("hex") };
+    }
+    catch (cause) {
+        signal?.throwIfAborted();
+        const systemCode = fileUnavailableSystemCode(cause);
+        if (systemCode === undefined)
+            throw cause;
+        return {
+            state: "omitted",
+            reason: "file_unavailable",
+            system_code: systemCode,
+        };
     }
     finally {
         await handle.close();
@@ -98,20 +152,36 @@ export const snapshotRoots = async (scenario, signal) => {
             return true;
         }
         if (stats.isFile()) {
-            const sha256 = remainingBytes >= stats.size
-                ? await hashFile(path, stats, remainingBytes, signal)
-                : null;
-            remainingBytes -= sha256 === null ? 0 : stats.size;
-            if (sha256 === null) {
-                truncated = true;
-                hashOmissions.push({
+            let sha256 = null;
+            let omission;
+            if (remainingBytes < stats.size) {
+                omission = {
                     path: `${rootAlias}:${relativePath}`,
                     size_bytes: stats.size,
                     remaining_budget_bytes: remainingBytes,
-                    reason: remainingBytes < stats.size
-                        ? "file_bytes_budget"
-                        : "file_changed_or_short_read",
-                });
+                    reason: "file_bytes_budget",
+                    system_code: null,
+                };
+            }
+            else {
+                const outcome = await hashFile(path, stats, remainingBytes, signal);
+                if (outcome.state === "hashed") {
+                    sha256 = outcome.sha256;
+                    remainingBytes -= stats.size;
+                }
+                else {
+                    omission = {
+                        path: `${rootAlias}:${relativePath}`,
+                        size_bytes: stats.size,
+                        remaining_budget_bytes: remainingBytes,
+                        reason: outcome.reason,
+                        system_code: outcome.system_code,
+                    };
+                }
+            }
+            if (omission !== undefined) {
+                truncated = true;
+                hashOmissions.push(omission);
             }
             entries.push({
                 path: `${rootAlias}:${relativePath}`,

package/dist/process/capture/ProcessCaptureLifecycle.js

@@ -43,10 +43,7 @@ export const createProcessCaptureObservationBuffer = (options) => ({
     filesystem_snapshots: {
         before: {
             state: "available",
-            value: {
-                files: options.before.files,
-                truncated: options.before.truncated,
-            },
+            value: options.before,
         },
         after: {
             state: "unavailable",
@@ -97,8 +94,9 @@ export const buildCaptureResult = (options) => {
     const filesystemObservationUnknown = "No filesystem observation paths were selected; filesystem effects remain unknown.";
     const hasFilesystemObservations = options.scenario.filesystem_observation_paths.length > 0;
     const filesystemEffects = classifyFilesystemEffects(options.before, options.after);
-    const hasUnknownFilesystemEffects = filesystemEffects.some(({ status }) => status === "unknown");
-    const incompleteFilesystemUnknown = "Path absence in incomplete enumeration or below an unfollowed symbolic link remains unknown.";
+    const filesystemUnknowns = [
+        ...new Set(filesystemEffects.flatMap((effect) => effect.status === "unknown" ? [effect.reason] : [])),
+    ];
     return {
         manifest: options.manifest,
         normalization: options.scenario.normalization,
@@ -119,12 +117,8 @@ export const buildCaptureResult = (options) => {
         files_before: options.before.files,
         files_after: options.after.files,
         filesystem_effects: filesystemEffects,
-        truncated: options.truncationDetails === undefined
-            ? options.truncated
-            : hasCaptureTruncation(options.truncationDetails),
-        ...(options.truncationDetails === undefined
-            ? {}
-            : { truncation_details: options.truncationDetails }),
+        truncated: hasCaptureTruncation(options.truncationDetails),
+        truncation_details: options.truncationDetails,
         limitations: [
             "The executable digest is a prelaunch file sample; matching path metadata immediately after spawn does not prove an atomic operating-system image binding.",
             "Process trees are sampled and may omit short-lived descendants.",
@@ -134,10 +128,8 @@ export const buildCaptureResult = (options) => {
             "Filesystem observations are before/after snapshots, not syscall traces.",
             "Inherited host environment variables are not recorded and may affect results.",
             ...(!hasFilesystemObservations ? [filesystemObservationUnknown] : []),
-            ...(hasUnknownFilesystemEffects ? [incompleteFilesystemUnknown] : []),
-            ...(options.truncationDetails === undefined
-                ? []
-                : captureCoverageUnknowns(options.truncationDetails).map(({ reason }) => reason)),
+            ...filesystemUnknowns,
+            ...captureCoverageUnknowns(options.truncationDetails).map(({ reason }) => reason),
             ...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
         ],
         residual_unknowns: [
@@ -165,20 +157,14 @@ export const buildCaptureResult = (options) => {
                     },
                 ]
                 : []),
-            ...(hasUnknownFilesystemEffects
-                ? [
-                    {
-                        scope: "filesystem",
-                        reason: incompleteFilesystemUnknown,
-                    },
-                ]
-                : []),
+            ...filesystemUnknowns.map((reason) => ({
+                scope: "filesystem",
+                reason,
+            })),
             ...(hasSensitiveScriptedInput
                 ? [{ scope: "interaction", reason: sensitiveInputUnknown }]
                 : []),
-            ...(options.truncationDetails === undefined
-                ? []
-                : captureCoverageUnknowns(options.truncationDetails).filter(({ scope }) => scope !== "terminal")),
+            ...captureCoverageUnknowns(options.truncationDetails).filter(({ scope }) => scope !== "terminal"),
         ],
     };
 };

package/dist/process/capture/ProcessFilesystemEffects.js

@@ -13,7 +13,7 @@ const unobservedAbsenceReason = (path, phase, completeRoots, filesByPath) => {
     }
     return undefined;
 };
-/** Classify effects only when a snapshot establishes the missing path's absence. */
+/** Classify effects only from observed path absence, metadata, and content hashes. */
 export const classifyFilesystemEffects = (before, after) => {
     const beforeByPath = new Map(before.files.map((file) => [file.path, file]));
     const afterByPath = new Map(after.files.map((file) => [file.path, file]));
@@ -54,11 +54,26 @@ export const classifyFilesystemEffects = (before, after) => {
                 before: beforeFile,
                 after: null,
             };
+        const metadataChanged = beforeFile.type !== afterFile.type ||
+            beforeFile.mode !== afterFile.mode ||
+            beforeFile.size !== afterFile.size ||
+            beforeFile.symlink_target !== afterFile.symlink_target;
+        if (!metadataChanged &&
+            beforeFile.type === "file" &&
+            afterFile.type === "file" &&
+            (beforeFile.sha256 === null || afterFile.sha256 === null))
+            return {
+                path,
+                status: "unknown",
+                before: beforeFile,
+                after: afterFile,
+                reason: "A file content hash is unavailable in at least one snapshot; matching metadata does not establish unchanged contents.",
+            };
         return {
             path,
-            status: JSON.stringify(beforeFile) === JSON.stringify(afterFile)
-                ? "unchanged"
-                : "modified",
+            status: metadataChanged || beforeFile.sha256 !== afterFile.sha256
+                ? "modified"
+                : "unchanged",
             before: beforeFile,
             after: afterFile,
         };

package/dist/process/capture/ProcessHarness.js

@@ -220,7 +220,7 @@ const completeCapture = async (options) => {
         ...options.observationBuffer.filesystem_snapshots,
         after: {
             state: "available",
-            value: { files: after.files, truncated: after.truncated },
+            value: after,
         },
     };
     options.recordEvent("filesystem_checkpoints", 1);
@@ -267,31 +267,19 @@ const completeCapture = async (options) => {
         throw cause;
     }
     options.observationBuffer.manifest = { state: "available", value: manifest };
-    const truncated = options.initiallyTruncated ||
-        after.truncated ||
-        runtime.rawTerminalRetention().observed_frames >
-            runtime.rawTerminalRetention().retained_frames ||
-        checkpoints.some(({ truncated: partial }) => partial) ||
-        samplingPartial ||
-        runtime.renderer.truncated();
     return buildCaptureResult({
         frames: options.frames,
         exit: { ...options.exit, reason },
         samples: options.samples,
         before: options.before,
         after,
-        truncated,
-        ...(options.before.coverage === undefined || after.coverage === undefined
-            ? {}
-            : {
-                truncationDetails: {
-                    raw_terminal: runtime.rawTerminalRetention(),
-                    rendered_terminal: runtime.renderer.retention(),
-                    filesystem_before: options.before.coverage,
-                    filesystem_after: after.coverage,
-                    process: sampling.coverage,
-                },
-            }),
+        truncationDetails: {
+            raw_terminal: runtime.rawTerminalRetention(),
+            rendered_terminal: runtime.renderer.retention(),
+            filesystem_before: options.before.coverage,
+            filesystem_after: after.coverage,
+            process: sampling.coverage,
+        },
         scenario,
         rootPid: runtime.terminal.pid,
         samplingPartial,
@@ -377,7 +365,6 @@ const runProcessScenario = async (scenario, signal, hostEnvironment = process.en
             samples,
             interactions,
             exit,
-            initiallyTruncated: before.truncated,
             eventJournal,
             observationBuffer: observations,
             recordEvent,

package/dist/server/analysisAdmission.js

@@ -0,0 +1,8 @@
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+/** Run against the source's explicit owner, admitting session-scoped work. */
+export const withAdmittedAnalysis = (source) => source.kind === "session"
+    ? (operationName, signal, operation) => source.session.withAdmittedAnalysis(operationName, signal, operation)
+    : async (operationName, signal, operation) => signal?.aborted === true
+        ? err(new AnalysisCancelledError(operationName))
+        : ok(await operation(source.analysis));

package/dist/server/createServer.js

@@ -39,11 +39,13 @@ import { registerAndroidTools } from "./registerAndroidTools.js";
 import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
 import { createAndroidAnalysisProvider } from "../composition/android.js";
 import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
-import { registerNativeTools } from "./registerNativeTools.js";
+import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";
+import { registerEvidenceTools } from "./registerEvidenceTools.js";
 import { registerOfficialTools } from "./registerOfficialTools.js";
 import { registerGuidedPrompts } from "./registerPrompts.js";
 import { registerSessionTools } from "./registerSessionTools.js";
 import { sessionAvailabilityPolicy } from "./sessionAvailabilityPolicy.js";
+import { withAdmittedAnalysis, } from "./analysisAdmission.js";
 const TARGET_FREE_INSTRUCTIONS = "REA provides reverse-engineering tools for local artifacts, native binaries, managed code, browser pages, and runtimes. Use the tool that directly answers the question; discover targets or inspect inventory only when needed. Tool results include inline Evidence and report their coverage and limitations.";
 const ACTIVE_TARGET_INSTRUCTIONS = "REA analyzes the active reverse-engineering target. Use the analysis tool that answers the question directly. Search or list symbols when discovery is needed; analyze_function provides a function dossier, and focused procedure tools return individual facets.";
 const installSessionToolAvailability = (session, options, environment) => {
@@ -93,7 +95,9 @@ const createMcpServer = (session, delivery) => new EvidenceMcpServer({
  * 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 = {}) => {
+export const createServer = (source, options = {}) => {
+    const session = source.kind === "session" ? source.session : undefined;
+    const analysis = source.kind === "session" ? source.session : source.analysis;
     const environment = snapshotEnvironment(options.environment ?? process.env);
     const delivery = selectToolResultDelivery(environment, options.delivery);
     const selectedOptions = { ...options, environment, delivery };
@@ -106,7 +110,6 @@ export const createServer = (analysis, session, options = {}) => {
     const { evidenceById, activeTarget, recordEvidence, recordEvidenceWithUnknown, } = createSessionRecorders(server, session);
     const toolContext = {
         server,
-        analysis,
         session,
         options: selectedOptions,
         environment,
@@ -115,6 +118,7 @@ export const createServer = (analysis, session, options = {}) => {
         activeTarget,
         recordEvidence,
         recordEvidenceWithUnknown,
+        withAdmittedAnalysis: withAdmittedAnalysis(source),
     };
     registerBinaryAnalysisTools(toolContext);
     const previousOnclose = server.server.onclose;
@@ -176,18 +180,12 @@ const createSessionRecorders = (server, session) => ({
     activeTarget: session === undefined ? undefined : () => session.activeTarget(),
     recordEvidence: session === undefined
         ? undefined
-        : (evidence) => {
-            const recorded = session.recordEvidence(evidence);
-            return recorded;
-        },
+        : (evidence) => session.recordEvidence(evidence),
     recordEvidenceWithUnknown: session === undefined
         ? undefined
-        : (evidence, input) => {
-            const recorded = session.recordEvidenceWithUnknown(evidence, input);
-            return recorded;
-        },
+        : (evidence, input) => session.recordEvidenceWithUnknown(evidence, input),
 });
-const registerBinaryAnalysisTools = ({ server, analysis, session, logger, activeTarget, recordEvidence, recordEvidenceWithUnknown, }) => {
+const registerBinaryAnalysisTools = ({ server, session, logger, activeTarget, recordEvidence, recordEvidenceWithUnknown, withAdmittedAnalysis, }) => {
     const recordUnknown = session === undefined
         ? undefined
         : (input) => session.recordUnknown(input);
@@ -196,9 +194,10 @@ const registerBinaryAnalysisTools = ({ server, analysis, session, logger, active
         activeTarget,
         recordEvidence,
         recordUnknown,
+        withAdmittedAnalysis,
     };
-    registerOfficialTools(server, analysis, analysisOptions);
-    registerEnhancedTools(server, analysis, {
+    registerOfficialTools(server, analysisOptions);
+    registerEnhancedTools(server, {
         ...analysisOptions,
         analysisProfile: session === undefined ? undefined : () => session.analysisProfile(),
         allowsSnapshotReplay: session === undefined
@@ -208,15 +207,15 @@ const registerBinaryAnalysisTools = ({ server, analysis, session, logger, active
             ? undefined
             : (input) => session.recordWorkflowSnapshot(input),
     });
-    const evidenceOptions = { logger, activeTarget, recordEvidence };
-    registerNativeTools(server, analysis, evidenceOptions);
-    registerArtifactTools(server, analysis, {
-        ...evidenceOptions,
-    });
-    registerManagedTools(server, analysis, {
-        ...evidenceOptions,
-        session,
-    });
+    const evidenceOptions = {
+        logger,
+        activeTarget,
+        recordEvidence,
+        withAdmittedAnalysis,
+    };
+    registerEvidenceTools(server, NATIVE_TOOL_CONTRACTS, evidenceOptions);
+    registerArtifactTools(server, evidenceOptions);
+    registerManagedTools(server, evidenceOptions);
     if (session !== undefined)
         registerManagedWorkflowTools(server, {
             logger,

package/dist/server/registerApplicationTools/compareExportShapes.js

@@ -24,7 +24,8 @@ export const registerCompareJavaScriptExportShapesTool = (server, options) => {
         if (!recorded.ok)
             return server.delivery.toCallToolResult(recorded, contract);
         const comparison = javaScriptExportShapeComparisonResultSchema.parse(result.value.normalized_result);
-        const unknown = comparison.summary.unknown > 0;
+        const unknown = comparison.summary.unknown > 0 ||
+            comparison.coverage.status !== "complete-within-inputs";
         return recordResult({ ...options, delivery: server.delivery }, contract, result.value, unknown ? "javascript-export-shape" : undefined);
     });
 };

package/dist/server/registerApplicationTools/helpers.js

@@ -6,11 +6,12 @@ export const recordResult = (options, contract, evidence, unknownKind) => {
     return options.delivery.toEvidenceToolResult(evidence, contract, recorded);
 };
 const unknownRegistration = (evidence, kind) => ({
-    question: kind === "application-version-comparison"
+    // Scope unknown identity to the comparison while keeping exact replays stable.
+    question: `${kind === "application-version-comparison"
         ? "Which application entities remain unmatched or ambiguous across these versions?"
         : kind === "source-to-bundle-comparison"
             ? "Which historical source files remain unmatched or ambiguously mapped to the shipped bundle?"
-            : "Which selected JavaScript export return shapes remain dynamic, incomplete, or ambiguously paired?",
+            : "Which selected JavaScript export return shapes remain dynamic, incomplete, or ambiguously paired?"} (comparison ${evidence.evidence_id})`,
     severity: "medium",
     domain: kind,
     supporting_evidence_ids: [evidence.evidence_id],

package/dist/server/registerArtifactTools.js

@@ -2,8 +2,8 @@ import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
 import { registerEvidenceTools } from "./registerEvidenceTools.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
 /** Register deterministic artifact inventory and safe extraction operations. */
-export const registerArtifactTools = (server, analysis, options) => {
-    registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, {
+export const registerArtifactTools = (server, options) => {
+    registerEvidenceTools(server, ARTIFACT_TOOL_CONTRACTS, {
         ...options,
         sourceEvidence: (operation, result) => operation === "inspect_artifact"
             ? artifactInspectionResultSchema

package/dist/server/registerCloseLifecycleTool.js

@@ -9,15 +9,17 @@ export const registerCloseLifecycleTool = ({ server, session, logger, closeContr
         const progress = mcpProgressReporter(context);
         const snapshotPath = input.snapshot_path;
         if (snapshotPath === undefined) {
+            // Enqueue the lifecycle transition before awaiting progress transport so
+            // a later open request cannot overtake this close.
+            const closing = logToolExecution(logger, closeContract.name, () => session.close({ progress }));
             await reportLifecycleStart(progress, closeContract.name);
-            const closed = await logToolExecution(logger, closeContract.name, () => session.close({ progress }));
+            const closed = await closing;
             await reportLifecycleEnd(progress, closeContract.name, closed.ok);
             return server.delivery.toCallToolResult(closed, closeContract);
         }
+        const closing = logToolExecution(logger, closeContract.name, () => session.closeWithSnapshot(snapshotPath, input.overwrite, { progress }));
         await reportLifecycleStart(progress, closeContract.name, "saving snapshot; closing provider");
-        const closed = await logToolExecution(logger, closeContract.name, () => session.closeWithSnapshot(snapshotPath, input.overwrite, {
-            progress,
-        }));
+        const closed = await closing;
         await reportLifecycleEnd(progress, closeContract.name, closed.ok);
         return server.delivery.toCallToolResult(closed.ok ? ok({ ...closed.value }) : closed, closeContract);
     });