rea-agents 3.1.0 → 3.2.1

package/dist/domain/artifactInventoryEvidence.js

@@ -2,35 +2,42 @@ import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { artifactInventoryResultSchema, } from "./artifactGraph.js";
 import { parseEvidence } from "./evidence.js";
-/** Parse, merge, and verify a bounded set of inventory Evidence pages. */
+import { artifactInspectionResultSchema } from "./artifactInspection.js";
+/** Parse, merge, and verify inventory Evidence pages. */
 export const parseArtifactInventoryEvidence = (input) => assembleInventorySet((Array.isArray(input) ? input : [input]).map((value) => {
     const evidence = parseEvidence(value);
-    if (evidence.operation !== "inventory_artifact")
-        throw new TypeError("Artifact comparison requires inventory_artifact Evidence");
-    const inventory = artifactInventoryResultSchema.parse(evidence.normalized_result);
-    if (evidence.subject === null ||
-        evidence.subject.digest.sha256 !== inventory.manifest.root_sha256 ||
-        evidence.subject.format !== inventory.manifest.root_format)
+    const inventoryEvidence = evidence.operation === "inventory_artifact"
+        ? evidence
+        : evidence.operation === "inspect_artifact"
+            ? artifactInspectionResultSchema.parse(evidence.normalized_result)
+                .substeps[0]?.evidence
+            : undefined;
+    if (inventoryEvidence === undefined)
+        throw new TypeError("Artifact comparison requires inspect_artifact Evidence");
+    const inventory = artifactInventoryResultSchema.parse(inventoryEvidence.normalized_result);
+    if (inventoryEvidence.subject === null ||
+        inventoryEvidence.subject.digest.sha256 !==
+            inventory.manifest.root_sha256 ||
+        inventoryEvidence.subject.format !== inventory.manifest.root_format)
         throw new TypeError("Artifact inventory Evidence subject does not match its root digest");
     validateInventoryPage(inventory);
     return { evidence, inventory };
 }));
 const validateInventoryPage = (inventory) => {
-    assertUnique(inventory.nodes.items.map(({ artifact_id: id }) => id), "node ID");
-    assertUnique(inventory.occurrences.items.map(({ occurrence_id: id }) => id), "occurrence ID");
-    assertUnique(inventory.occurrences.items.map(({ logical_path: path }) => path), "logical path");
-    assertUnique(inventory.edges.items.map(({ edge_id: id }) => id), "edge ID");
-    for (const node of inventory.nodes.items)
-        if (node.artifact_id !==
-            `art_${digestCanonical({ schema_version: 1, sha256: node.sha256 })}`)
+    assertUnique(inventory.nodes.map(({ artifact_id: id }) => id), "node ID");
+    assertUnique(inventory.occurrences.map(({ occurrence_id: id }) => id), "occurrence ID");
+    assertUnique(inventory.occurrences.map(({ logical_path: path }) => path), "logical path");
+    assertUnique(inventory.edges.map(({ edge_id: id }) => id), "edge ID");
+    for (const node of inventory.nodes)
+        if (node.artifact_id !== `art_${digestCanonical({ sha256: node.sha256 })}`)
             throw new TypeError("Artifact node ID is not content-addressed");
 };
 const assembleInventorySet = (pages) => {
-    if (pages.length === 0 || pages.length > 100)
-        throw new TypeError("Artifact comparison requires 1 to 100 Evidence pages");
+    if (pages.length === 0)
+        throw new TypeError("Artifact inventory requires Evidence pages");
     const first = pages[0];
     if (first === undefined)
-        throw new TypeError("Artifact comparison requires Evidence pages");
+        throw new TypeError("Artifact inventory requires Evidence pages");
     const manifestJson = canonicalJson(first.inventory.manifest);
     const nodes = new Map();
     const occurrences = new Map();
@@ -42,13 +49,13 @@ const assembleInventorySet = (pages) => {
         if (canonicalJson(page.inventory.integrity_contradictions) !==
             canonicalJson(first.inventory.integrity_contradictions))
             throw new TypeError("Artifact inventory pages do not share integrity contradictions");
-        for (const node of page.inventory.nodes.items)
+        for (const node of page.inventory.nodes)
             mergeExact(nodes, node.artifact_id, node, "node");
-        for (const occurrence of page.inventory.occurrences.items) {
+        for (const occurrence of page.inventory.occurrences) {
             mergeExact(occurrences, occurrence.occurrence_id, occurrence, "occurrence");
             mergeExact(paths, occurrence.logical_path, occurrence, "logical path");
         }
-        for (const edge of page.inventory.edges.items)
+        for (const edge of page.inventory.edges)
             mergeExact(edges, edge.edge_id, edge, "edge");
     }
     const inventory = orderedInventory(first.inventory, pages, {
@@ -110,7 +117,6 @@ const validateCompleteInventory = (inventory) => {
     if (graphSha256 !== inventory.manifest.graph_sha256)
         throw new TypeError("Artifact graph commitment does not match its members");
     const manifestId = `agm_${digestCanonical({
-        schema_version: 1,
         root_artifact_id: inventory.manifest.root_artifact_id,
         graph_sha256: graphSha256,
     })}`;

package/dist/domain/binaryTarget.js

@@ -1,224 +1,4 @@
-import { constants } from "node:fs";
-import { createHash } from "node:crypto";
-import { access, open, readFile, realpath, stat, } from "node:fs/promises";
-import { execFile } from "node:child_process";
-import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { promisify } from "node:util";
-import { BinaryTargetError } from "./errors.js";
 import { err, ok } from "./result.js";
-import { zipPackageFormatForPath } from "./zipPackageFormat.js";
-const execFileAsync = promisify(execFile);
-/**
- * Resolve and classify a readable local target before a provider is selected.
- * FAT Mach-O inputs select only a host-compatible architecture so setup remains
- * non-interactive; unsupported or ambiguous inputs are returned as typed errors.
- */
-export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitecture = process.arch, targetKind) => {
-    const candidate = isAbsolute(input) ? input : resolve(cwd, input);
-    try {
-        await access(candidate, constants.R_OK);
-        const canonical = await realpath(candidate);
-        const resolved = await resolveAppBundle(canonical);
-        if (!resolved.ok)
-            return err(resolved.error);
-        const path = resolved.value;
-        const handle = await open(path, "r");
-        try {
-            if (!(await handle.stat()).isFile())
-                return err(new BinaryTargetError(path, "target is not a regular file"));
-            if (targetKind === "database" ||
-                (targetKind === undefined && path.toLowerCase().endsWith(".hop")))
-                return ok({
-                    path,
-                    sourcePath: canonical,
-                    sha256: await sha256Handle(handle),
-                    kind: "database",
-                    format: "analysis-database",
-                });
-            const artifactFormat = await detectArtifactFormat(path, handle);
-            if (artifactFormat !== undefined) {
-                const identity = {
-                    path,
-                    sourcePath: canonical,
-                    sha256: await sha256Handle(handle),
-                };
-                return isArchiveFormat(artifactFormat)
-                    ? ok({ ...identity, kind: "archive", format: artifactFormat })
-                    : ok({ ...identity, kind: "artifact", format: artifactFormat });
-            }
-            const detected = await readExecutableMetadata(handle, hostArchitecture);
-            if (!detected.ok)
-                return err(new BinaryTargetError(path, detected.error));
-            return ok({
-                path,
-                sourcePath: canonical,
-                sha256: await sha256Handle(handle),
-                kind: "executable",
-                ...detected.value,
-            });
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    catch (cause) {
-        return err(new BinaryTargetError(candidate, "path is not readable", { cause }));
-    }
-};
-const detectArtifactFormat = async (path, handle) => {
-    const lower = path.toLowerCase();
-    const magic = Buffer.alloc(8);
-    const observed = await handle.read(magic, 0, magic.length, 0);
-    if (observed.bytesRead >= 4 &&
-        magic[0] === 0x50 &&
-        magic[1] === 0x4b &&
-        [0x03, 0x05, 0x07].includes(magic[2] ?? -1) &&
-        [0x04, 0x06, 0x08].includes(magic[3] ?? -1)) {
-        return zipPackageFormatForPath(lower) ?? "zip";
-    }
-    const named = namedArtifactFormat(lower);
-    if (named !== undefined)
-        return named;
-    if (lower.endsWith(".pkg") &&
-        observed.bytesRead >= 4 &&
-        magic.subarray(0, 4).toString("ascii") === "xar!")
-        return "pkg";
-    if (lower.endsWith(".dmg")) {
-        const size = (await handle.stat()).size;
-        if (size >= 512) {
-            const trailer = Buffer.alloc(4);
-            const read = await handle.read(trailer, 0, trailer.length, size - 512);
-            if (read.bytesRead === 4 && trailer.toString("ascii") === "koly")
-                return "dmg";
-        }
-    }
-    return undefined;
-};
-const namedArtifactFormat = (lowerPath) => {
-    if (lowerPath.endsWith(".asar"))
-        return "asar";
-    if (lowerPath.endsWith(".plist"))
-        return "plist";
-    if (lowerPath.endsWith(".map"))
-        return "source-map";
-    return /\.(?:m?js|cjs)$/u.test(lowerPath) ? "javascript" : undefined;
-};
-const isArchiveFormat = (format) => ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(format);
-const sha256Handle = async (handle) => {
-    const hash = createHash("sha256");
-    const chunk = Buffer.allocUnsafe(64 * 1024);
-    let position = 0;
-    while (true) {
-        const observed = await handle.read(chunk, 0, chunk.length, position);
-        if (observed.bytesRead === 0)
-            break;
-        hash.update(chunk.subarray(0, observed.bytesRead));
-        position += observed.bytesRead;
-    }
-    return hash.digest("hex");
-};
-const resolveAppBundle = async (path) => {
-    const metadata = await stat(path);
-    if (!metadata.isDirectory())
-        return ok(path);
-    if (extname(path).toLowerCase() !== ".app")
-        return err(new BinaryTargetError(path, "target is not an app or file"));
-    const plistPath = join(path, "Contents", "Info.plist");
-    let name;
-    try {
-        const plist = await readFile(plistPath);
-        name =
-            plist.subarray(0, 6).toString("ascii") === "bplist"
-                ? await readBinaryPlistExecutable(plistPath)
-                : parseXmlPlistExecutable(plist.toString("utf8"));
-    }
-    catch (cause) {
-        return err(new BinaryTargetError(path, "app has no readable CFBundleExecutable", {
-            cause,
-        }));
-    }
-    if (!isSafeExecutableName(name))
-        return err(new BinaryTargetError(path, "app has an unsafe CFBundleExecutable"));
-    const programs = join(path, "Contents", "MacOS");
-    const executable = join(programs, name);
-    try {
-        const [canonicalPrograms, canonicalExecutable] = await Promise.all([
-            realpath(programs),
-            realpath(executable),
-        ]);
-        const location = relative(canonicalPrograms, canonicalExecutable);
-        if (location === ".." ||
-            location.startsWith(`..${sep}`) ||
-            isAbsolute(location))
-            return err(new BinaryTargetError(path, "app program file leaves Contents/MacOS"));
-        return ok(canonicalExecutable);
-    }
-    catch (cause) {
-        return err(new BinaryTargetError(path, "app program file is missing", { cause }));
-    }
-};
-const parseXmlPlistExecutable = (plist) => {
-    const match = /<key>\s*CFBundleExecutable\s*<\/key>\s*<string>([^<]+)<\/string>/u.exec(plist);
-    if (match?.[1] === undefined)
-        throw new Error("CFBundleExecutable is missing");
-    return decodeXml(match[1].trim());
-};
-const readBinaryPlistExecutable = async (plistPath) => (await execFileAsync("/usr/bin/plutil", [
-    "-extract",
-    "CFBundleExecutable",
-    "raw",
-    "-o",
-    "-",
-    plistPath,
-])).stdout.trim();
-const isSafeExecutableName = (name) => name.length > 0 &&
-    name !== "." &&
-    name !== ".." &&
-    !name.includes("\0") &&
-    !/[/\\]/u.test(name);
-const decodeXml = (value) => value
-    .replaceAll("&amp;", "&")
-    .replaceAll("&lt;", "<")
-    .replaceAll("&gt;", ">")
-    .replaceAll("&quot;", '"')
-    .replaceAll("&apos;", "'");
-const readExecutableMetadata = async (handle, hostArchitecture) => {
-    const prefix = Buffer.alloc(4096);
-    const prefixRead = await handle.read(prefix, 0, prefix.length, 0);
-    const bytes = prefix.subarray(0, prefixRead.bytesRead);
-    if (bytes.length >= 64 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
-        const offset = bytes.readUInt32LE(0x3c);
-        return readPeMetadata(handle, offset);
-    }
-    if (bytes.length >= 8) {
-        const magic = bytes.readUInt32BE(0);
-        if ([0xcafebabf, 0xbfbafeca].includes(magic)) {
-            const little = magic === 0xbfbafeca;
-            const count = little ? bytes.readUInt32LE(4) : bytes.readUInt32BE(4);
-            const required = 8 + count * 32;
-            if (count <= 128 && required > bytes.length) {
-                const header = Buffer.alloc(required);
-                const headerRead = await handle.read(header, 0, header.length, 0);
-                return parseExecutableHeader(header.subarray(0, headerRead.bytesRead), hostArchitecture);
-            }
-        }
-    }
-    return parseExecutableHeader(bytes, hostArchitecture);
-};
-const readPeMetadata = async (handle, offset) => {
-    const fileHeader = Buffer.alloc(24);
-    const fileHeaderRead = await handle.read(fileHeader, 0, fileHeader.length, offset);
-    if (fileHeaderRead.bytesRead !== fileHeader.length)
-        return err("invalid or truncated PE header");
-    const optionalHeaderSize = fileHeader.readUInt16LE(20);
-    if (optionalHeaderSize > 4096)
-        return err("invalid PE optional header size");
-    const record = Buffer.alloc(24 + optionalHeaderSize);
-    const recordRead = await handle.read(record, 0, record.length, offset);
-    return recordRead.bytesRead === record.length
-        ? parsePeRecord(record)
-        : err("invalid or truncated PE header");
-};
 /**
  * Parse supported executable headers without I/O. The caller supplies the host
  * architecture used for deterministic FAT Mach-O slice selection.
@@ -310,7 +90,8 @@ const parsePe = (bytes) => {
         return err("invalid or truncated PE header");
     return parsePeRecord(bytes.subarray(offset));
 };
-const parsePeRecord = (record) => {
+/** Parse a bounded PE signature, COFF record, and optional header without I/O. */
+export const parsePeRecord = (record) => {
     if (record.length < 24 ||
         record.toString("binary", 0, 4) !== "PE\u0000\u0000")
         return err("invalid or truncated PE header");

package/dist/domain/browserCaptureComparison.js

@@ -1,27 +1,42 @@
 import { z } from "zod";
 import { browserScenarioDiffSchema, compareBrowserScenarios, compareBrowserScenariosInputSchema, } from "./browserScenarioDiff.js";
 import { compareWebCaptures, captureSnapshotSchema, webCaptureDiffSchema, } from "./webCaptureDiff.js";
-const maxChangesSchema = z
-    .number()
-    .int()
-    .min(1)
-    .max(20_000)
-    .default(2_000)
-    .describe("Maximum normalized change records to retain.");
-/** Top-level MCP shape for exactly one complete passive or scenario pair. */
-export const browserCaptureComparisonInputSchema = z.union([
-    z.strictObject({
-        before: captureSnapshotSchema.describe("Earlier passive web-page capture."),
-        after: captureSnapshotSchema.describe("Later passive web-page capture."),
-        max_changes: maxChangesSchema,
-    }),
-    z.strictObject({
-        before_scenario: compareBrowserScenariosInputSchema.shape.before_scenario.describe("Earlier browser scenario capture."),
-        after_scenario: compareBrowserScenariosInputSchema.shape.after_scenario.describe("Later browser scenario capture."),
-        normalization: compareBrowserScenariosInputSchema.shape.normalization.describe("Exact-literal normalization policy."),
-        max_changes: maxChangesSchema,
-    }),
-]);
+/** Caller-visible object schema for passive and scenario capture comparisons. */
+export const browserCaptureComparisonInputSchema = z
+    .strictObject({
+    before: captureSnapshotSchema
+        .optional()
+        .describe("Earlier passive web-page capture."),
+    after: captureSnapshotSchema
+        .optional()
+        .describe("Later passive web-page capture."),
+    before_scenario: compareBrowserScenariosInputSchema.shape.before_scenario
+        .optional()
+        .describe("Earlier browser scenario capture."),
+    after_scenario: compareBrowserScenariosInputSchema.shape.after_scenario
+        .optional()
+        .describe("Later browser scenario capture."),
+    normalization: compareBrowserScenariosInputSchema.shape.normalization
+        .unwrap()
+        .optional()
+        .describe("Exact-literal normalization policy."),
+})
+    .superRefine((input, context) => {
+    const passive = input.before !== undefined && input.after !== undefined;
+    const scenario = input.before_scenario !== undefined && input.after_scenario !== undefined;
+    const passiveFieldsPresent = input.before !== undefined || input.after !== undefined;
+    const scenarioFieldsPresent = input.before_scenario !== undefined ||
+        input.after_scenario !== undefined ||
+        input.normalization !== undefined;
+    if (passive && !scenarioFieldsPresent)
+        return;
+    if (scenario && !passiveFieldsPresent)
+        return;
+    context.addIssue({
+        code: "custom",
+        message: "Provide before and after passive captures, or before_scenario, after_scenario, and normalization; do not mix comparison types.",
+    });
+});
 /** Result from passive page or browser scenario comparison. */
 export const browserCaptureComparisonSchema = z.union([
     browserScenarioDiffSchema,
@@ -29,6 +44,14 @@ export const browserCaptureComparisonSchema = z.union([
 ]);
 /** Dispatch a parsed capture comparison to its pure domain comparator. */
 export const compareBrowserCaptures = (input) => isScenarioComparison(input)
-    ? compareBrowserScenarios(input)
-    : compareWebCaptures(input);
-const isScenarioComparison = (input) => "before_scenario" in input;
+    ? compareBrowserScenarios({
+        ...input,
+        normalization: input.normalization ?? { rules: [] },
+    })
+    : compareWebCaptures(toPassiveComparison(input));
+const isScenarioComparison = (input) => input.before_scenario !== undefined && input.after_scenario !== undefined;
+const toPassiveComparison = (input) => {
+    if (input.before === undefined || input.after === undefined)
+        throw new Error("Validated passive comparison is missing a capture");
+    return { before: input.before, after: input.after };
+};