rea-agents 5.0.0 → 6.0.0

package/dist/domain/evidence.js

@@ -155,7 +155,7 @@ export const createEvidence = (target, provider, observation) => {
     const subject = target === undefined
         ? null
         : {
-            name: target.path.split("/").at(-1) ?? target.path,
+            name: target.path.split("/").at(-1) || "artifact",
             digest: { sha256: target.sha256 },
             format: target.format,
             architecture: target.architecture ?? null,
@@ -187,20 +187,32 @@ export const createEvidence = (target, provider, observation) => {
         environment: observation.environment ?? null,
         limitations: [
             ...(target === undefined
-                ? ["Artifact identity is unavailable for this observation."]
+                ? [
+                    observation.subjectUnavailableReason ??
+                        "Artifact identity is unavailable for this observation.",
+                ]
                 : []),
             ...(observation.limitations ?? []),
         ],
         locations: [...(observation.locations ?? [])],
         evidence_links: [...(observation.evidenceLinks ?? [])],
     };
-    const normalized = evidenceRecordSchema.parse({
+    // Select the known envelope before parsing. A union otherwise traverses and
+    // clones a legacy result for the profiled branch before rejecting its absent
+    // profile and trying the legacy branch.
+    const schema = observation.analysisProfile === undefined
+        ? evidenceBaseSchema
+        : profiledEvidenceSchema;
+    const normalized = schema.parse({
         ...semantic,
         evidence_id: `ev_${"0".repeat(64)}`,
         subject,
     });
-    return parseEvidence({
+    // The envelope has already been parsed into an independent snapshot. Only
+    // its derived identifier changes here; parsing again clones the full payload
+    // and recomputes the same digest while the previous snapshot is still live.
+    return {
         ...normalized,
         evidence_id: computeEvidenceId(normalized),
-    });
+    };
 };

package/dist/domain/evm/evmInterface.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+const byteOffset = z.number().int().nonnegative();
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
+/** Select the carrier representation explicitly; no RPC or deployed-contract lookup is implied. */
+export const inspectEvmInterfaceInputSchema = z.strictObject({
+    path: z
+        .string()
+        .min(1)
+        .describe("Absolute path to caller-selected local bytecode carrier"),
+    encoding: z
+        .enum(["raw", "hex"])
+        .describe("Raw bytes or UTF-8 hex with optional 0x prefix and outer ASCII whitespace"),
+});
+/** Recovered interface candidates are inferences, independently of observed byte identity. */
+export const evmInterfaceSchema = z
+    .strictObject({
+    artifact: z.strictObject({
+        path: z.string().min(1),
+        sha256,
+        bytes: byteOffset,
+        encoding: z.enum(["raw", "hex"]),
+    }),
+    bytecode: z.strictObject({
+        sha256,
+        bytes: byteOffset,
+        hex: z.string().regex(/^(?:[0-9a-f]{2})*$/),
+        digest_algorithm: z.literal("sha256"),
+        kind: z.literal("unknown"),
+        deployment_authenticity: z.literal("unknown"),
+        hardfork: z.literal("unknown"),
+    }),
+    evidence_kind: z.literal("inferred"),
+    functions: z.array(z.strictObject({
+        selector: z.string().regex(/^0x[0-9a-f]{8}$/),
+        bytecode_offset: byteOffset,
+        dispatch: z.enum(["abi", "fallback"]),
+        inferred_arguments: z.string().nullable(),
+        inferred_state_mutability: z.string().nullable(),
+    })),
+    discovery_completeness: z.literal("unknown"),
+    runtime_execution: z.literal("not-performed"),
+    diagnostics: z.strictObject({
+        stdout: z.string(),
+        stderr: z.string(),
+        truncated: z.boolean(),
+    }),
+    limitations: z.array(z.string()),
+})
+    .superRefine((value, context) => {
+    if (value.bytecode.hex.length !== value.bytecode.bytes * 2)
+        context.addIssue({
+            code: "custom",
+            path: ["bytecode"],
+            message: "Selected byte count does not match the bytecode hex representation.",
+        });
+    for (const [index, fn] of value.functions.entries())
+        if (fn.bytecode_offset >= value.bytecode.bytes)
+            context.addIssue({
+                code: "custom",
+                path: ["functions", index, "bytecode_offset"],
+                message: "Inferred body offset lies outside the selected bytecode.",
+            });
+});

package/dist/domain/explicitSensitiveFailure.js

@@ -0,0 +1,92 @@
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, } from "./analysisErrorCore.js";
+import { redactExplicitText } from "./explicitSensitiveValues.js";
+import { ProviderAdapterError } from "./providerAdapterError.js";
+import { ProviderCleanupError } from "./providerCleanupError.js";
+/** Keep a real JSON-pointer ancestor when a property identity is explicitly excluded. */
+export const redactExplicitPointer = (pointer, values) => {
+    let parent = "";
+    for (const segment of pointer.split("/").slice(1)) {
+        const decoded = segment.replaceAll("~1", "/").replaceAll("~0", "~");
+        const child = `${parent}/${segment}`;
+        if (values.some((literal) => decoded.includes(literal) || child.includes(literal)))
+            return parent;
+        parent = child;
+    }
+    return parent;
+};
+/** Exclude explicit literals from common acquisition/decoder failures, preserving typed diagnostics. */
+export const redactExplicitFailure = (error, values) => {
+    if (values.length === 0)
+        return error;
+    const text = (value) => redactExplicitText(value, values);
+    const path = (parts, ordinaryNames) => {
+        const retained = [];
+        for (const part of parts) {
+            if (typeof part !== "string") {
+                retained.push(part);
+            }
+            else if (!ordinaryNames && part.startsWith("/")) {
+                const pointer = redactExplicitPointer(part, values);
+                retained.push(pointer);
+                if (pointer !== part)
+                    break;
+            }
+            else {
+                if (values.some((literal) => part.includes(literal)))
+                    break;
+                retained.push(part);
+            }
+        }
+        return retained;
+    };
+    const diagnostics = (value) => Object.fromEntries(Object.entries(value)
+        .filter(([key]) => !values.some((literal) => key.includes(literal)))
+        .map(([key, item]) => [key, visit(item)]));
+    const visit = (value) => {
+        if (typeof value === "string")
+            return text(value);
+        if (Array.isArray(value))
+            return value.map(visit);
+        if (typeof value === "object" && value !== null)
+            return diagnostics(value);
+        return value;
+    };
+    if (error instanceof AnalysisAccessDeniedError)
+        return new AnalysisAccessDeniedError(error.operation, text(error.path), error.systemCode, { cause: error });
+    if (error instanceof AnalysisArtifactChangedError)
+        return new AnalysisArtifactChangedError(error.operation, text(error.path), text(error.reason), { cause: error });
+    if (error instanceof AnalysisInputError)
+        return new AnalysisInputError(error.operation, { cause: error }, error.issues.map((issue) => ({
+            ...issue,
+            // Unknown-argument paths contain literal field names, including names
+            // beginning with '/'; they are not producer JSON-pointer coordinates.
+            path: path(issue.path, issue.reason === "unknown_argument"),
+            ...(issue.message === undefined
+                ? {}
+                : { message: text(issue.message) }),
+            ...(issue.expected === undefined
+                ? {}
+                : { expected: visit(issue.expected) }),
+        })));
+    if (error instanceof AnalysisOutputError)
+        return new AnalysisOutputError(error.operation, text(error.reason), {
+            cause: error,
+        });
+    if (error instanceof AnalysisCapabilityUnavailableError)
+        return new AnalysisCapabilityUnavailableError(error.providerId, error.operation, text(error.reason), {
+            cause: error,
+            ...(error.userMessage === undefined
+                ? {}
+                : { userMessage: text(error.userMessage) }),
+        });
+    if (error instanceof ProviderCleanupError)
+        return new ProviderCleanupError(error.providerId, error.cleanupResources.map(text), diagnostics(error.diagnostics ?? {}), { operation: error.operation, cause: error });
+    if (error instanceof ProviderAdapterError)
+        return new ProviderAdapterError(error.providerId, error.operation, {
+            cause: error,
+            ...(error.diagnostics === undefined
+                ? {}
+                : { diagnostics: diagnostics(error.diagnostics) }),
+        });
+    return error;
+};

package/dist/domain/explicitSensitiveValues.js

@@ -0,0 +1,10 @@
+/** Replace caller-declared literal text values without guessing sensitivity from names. */
+export const redactExplicitText = (value, sensitiveValues) => {
+    const literals = [...new Set(sensitiveValues)].filter((literal) => literal !== "");
+    const replacement = ["[REDACTED]", "…", ""].find((candidate) => literals.every((literal) => !candidate.includes(literal))) ?? "";
+    let result = value;
+    for (const literal of literals.sort((left, right) => right.length - left.length))
+        result = result.replaceAll(literal, replacement);
+    // Replacement boundaries can form another declaration; exclude that text.
+    return literals.some((literal) => result.includes(literal)) ? "" : result;
+};

package/dist/domain/firmware/firmwareAnalysis.js

@@ -1,10 +1,17 @@
 import { z } from "zod";
 import { digestSchema } from "../digests.js";
 import { jsonValueSchema } from "../jsonValue.js";
+import { isAbsoluteLocalPath } from "../localPath.js";
 const bytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
 const range = z.strictObject({ offset: bytes, length: bytes.positive() });
 const target = {
-    path: z.string().min(1).describe("Local firmware file; never executed"),
+    path: z
+        .string()
+        .min(1)
+        .refine(isAbsoluteLocalPath, {
+        message: "path must be an absolute local filesystem path (for example /tmp/firmware.bin or C:\\firmware\\firmware.bin)",
+    })
+        .describe("Absolute local firmware file; never executed. Relative paths are rejected."),
 };
 /** Explicit firmware inspection and extraction intent, independent of engines. */
 export const firmwareInputSchemas = {

package/dist/domain/javascript/electronActiveObservation.js

@@ -1,5 +1,8 @@
 import { z } from "zod";
-const pathInputSchema = z.string().trim().min(1);
+import { isAbsoluteLocalPath } from "../localPath.js";
+const pathInputSchema = z.string().trim().min(1).refine(isAbsoluteLocalPath, {
+    message: "Electron executable, application, and root paths must be absolute local filesystem paths (for example /Applications/Electron.app/Contents/MacOS/Electron)",
+});
 const absolutePathSchema = z
     .string()
     .min(1)
@@ -52,9 +55,11 @@ const actionSchema = z.discriminatedUnion("kind", [
 ]);
 /** Input for one explicit, provider-owned Electron runtime experiment. */
 export const electronActiveObservationInputSchema = z.strictObject({
-    executable_path: pathInputSchema,
-    application_path: pathInputSchema,
-    application_root: pathInputSchema.optional(),
+    executable_path: pathInputSchema.describe("Absolute local filesystem path for the Electron executable; relative paths are rejected."),
+    application_path: pathInputSchema.describe("Absolute local filesystem path for the Electron application; relative paths are rejected."),
+    application_root: pathInputSchema
+        .optional()
+        .describe("Absolute local filesystem root for application-relative paths; omit to derive it from the application path. Relative paths are rejected."),
     args: z.array(z.string()).default([]),
     actions: z.array(actionSchema).default([]),
 });

package/dist/domain/javascript/htmlArtifactReferences.js

@@ -0,0 +1,40 @@
+import { defaultTreeAdapter, parse, } from "parse5";
+/** Extract inert HTML script references and the first document base href. */
+export const htmlArtifactReferences = (text) => {
+    const pending = [
+        parse(text, { sourceCodeLocationInfo: true }),
+    ];
+    const scripts = [];
+    let baseHref = null;
+    while (pending.length > 0) {
+        const node = pending.pop();
+        if (node === undefined)
+            continue;
+        if (defaultTreeAdapter.isElementNode(node) &&
+            node.namespaceURI === "http://www.w3.org/1999/xhtml") {
+            if (node.tagName === "base" && baseHref === null) {
+                const href = node.attrs.find(({ name }) => name === "href");
+                if (href !== undefined)
+                    baseHref = href.value;
+            }
+            if (node.tagName === "script") {
+                const src = node.attrs.find(({ name }) => name === "src");
+                const location = node.sourceCodeLocation?.startTag;
+                if (src !== undefined && src.value !== "" && location !== undefined) {
+                    scripts.push({
+                        scriptPath: src.value,
+                        startOffset: location.startOffset,
+                        endOffset: location.endOffset,
+                    });
+                }
+            }
+        }
+        // Template content belongs to a separate inert document fragment. Only
+        // traverse the actual document children, without recursion on deep input.
+        if ("childNodes" in node) {
+            for (const child of node.childNodes.toReversed())
+                pending.push(child);
+        }
+    }
+    return { baseHref, scripts };
+};

package/dist/domain/javascript/javascriptExportShapeComparison.js

@@ -1,8 +1,8 @@
-import { uniqueSorted } from "../canonicalOrdering.js";
-import { digestExportShapeValue } from "./javascriptExportShapeComparisonIdentity.js";
+import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
+import { canonicalExportShapeValue, digestExportShapeValue, } from "./javascriptExportShapeComparisonIdentity.js";
 import { javaScriptExportShapeComparisonResultSchema, } from "./javascriptExportShapeComparisonSchemas.js";
 import { retainJavaScriptExportShapes, selectJavaScriptExport, } from "./javascriptExportShapeSelection.js";
-import { buildJavaScriptExportShapeChanges, compareJavaScriptExportShapeChanges, hasPartialJavaScriptExportPropertyCoverage, pairJavaScriptExportShapeVariants, } from "./javascriptExportShapeVariants.js";
+import { buildJavaScriptExportShapeChanges, hasPartialJavaScriptExportPropertyCoverage, pairJavaScriptExportShapeVariants, } from "./javascriptExportShapeVariants.js";
 /** Compare exact selected export return shapes without executing JavaScript. */
 export const compareJavaScriptExportShapes = (input) => {
     const left = selectJavaScriptExport(input.left);
@@ -11,14 +11,14 @@ export const compareJavaScriptExportShapes = (input) => {
     const rightRetained = retainJavaScriptExportShapes(right);
     const pairing = pairJavaScriptExportShapeVariants(leftRetained.shapes, rightRetained.shapes);
     const evidenceLinks = evidencePair(input.left.evidenceId, input.right.evidenceId);
-    const allChanges = buildJavaScriptExportShapeChanges({
+    const allChanges = sortChanges(buildJavaScriptExportShapeChanges({
         leftSelection: left,
         rightSelection: right,
         pairing,
         leftShapes: leftRetained.shapes,
         rightShapes: rightRetained.shapes,
         evidenceLinks,
-    }).sort(compareJavaScriptExportShapeChanges);
+    }));
     const changes = allChanges;
     const omittedChanges = 0;
     const coverage = comparisonCoverage({
@@ -46,6 +46,22 @@ export const compareJavaScriptExportShapes = (input) => {
         comparison_id: `jesc_${digestExportShapeValue(semantic)}`,
     });
 };
+const sortChanges = (changes) => changes
+    .map((change, index) => ({
+    change,
+    index,
+    sortKey: canonicalExportShapeValue({
+        discriminant: change.discriminant,
+        path: change.path,
+        status: change.status,
+        left_source_range: change.left_source_range,
+        right_source_range: change.right_source_range,
+        change_id: change.change_id,
+    }),
+}))
+    .sort((left, right) => compareCodePoints(left.sortKey, right.sortKey) ||
+    left.index - right.index)
+    .map(({ change }) => change);
 const comparisonCoverage = (context) => {
     const leftSource = context.left.projection?.return_shape_coverage;
     const rightSource = context.right.projection?.return_shape_coverage;

package/dist/domain/javascript/javascriptExportShapeVariants.js

@@ -61,8 +61,6 @@ export const buildJavaScriptExportShapeChanges = (input) => {
     });
     return [...paired, ...unpairedLeft, ...unpairedRight];
 };
-/** Sort changes by semantic content rather than traversal order. */
-export const compareJavaScriptExportShapeChanges = (left, right) => compareCodePoints(canonicalExportShapeValue(changeSortKey(left)), canonicalExportShapeValue(changeSortKey(right)));
 /** Report whether any retained shape lacks complete property coverage. */
 export const hasPartialJavaScriptExportPropertyCoverage = (shapes) => shapes.some((shape) => shape.property_coverage.some(({ status }) => status === "partial"));
 const discriminantOccurrences = (shapes) => {
@@ -270,14 +268,6 @@ const changeWithId = (semantic) => ({
     ...semantic,
     change_id: `jesc_change_${digestExportShapeValue(semantic)}`,
 });
-const changeSortKey = (change) => ({
-    discriminant: change.discriminant,
-    path: change.path,
-    status: change.status,
-    left_source_range: change.left_source_range,
-    right_source_range: change.right_source_range,
-    change_id: change.change_id,
-});
 const literalValue = (field) => field.state === "literal" && isPrimitive(field.value)
     ? { found: true, value: field.value }
     : { found: false };

package/dist/domain/javascript/javascriptSemanticGraph.js

@@ -11,7 +11,8 @@ const normalizeEvidence = (evidence) => ({
     limitations: uniqueSorted(evidence.limitations),
     evidence_ids: uniqueSorted(evidence.evidence_ids),
 });
-const nodeId = (node) => `jsrg_node_${canonicalDigest({ kind: node.kind, identity: node.identity }, "JavaScript semantic graph")}`;
+/** Derive a semantic node ID from its kind and exact artifact identity. */
+export const javaScriptSemanticNodeId = (node) => `jsrg_node_${canonicalDigest({ kind: node.kind, identity: node.identity }, "JavaScript semantic graph")}`;
 /** Normalize one semantic entity and derive its artifact-version identifier. */
 export const createJavaScriptSemanticGraphNode = (input) => {
     const parsed = javaScriptSemanticNodeInputSchema.parse(input);
@@ -26,7 +27,7 @@ export const createJavaScriptSemanticGraphNode = (input) => {
     };
     return javaScriptSemanticNodeSchema.parse({
         ...semantic,
-        node_id: nodeId(semantic),
+        node_id: javaScriptSemanticNodeId(semantic),
     });
 };
 /** Normalize one semantic relationship and derive its exact identifier. */
@@ -157,7 +158,7 @@ const checkCanonicalOrder = (graph, context) => {
 };
 const checkNodes = (graph, nodes, context) => {
     for (const [index, node] of graph.nodes.entries()) {
-        if (node.node_id !== nodeId(node))
+        if (node.node_id !== javaScriptSemanticNodeId(node))
             context.addIssue({
                 code: "custom",
                 path: ["nodes", index, "node_id"],
@@ -295,7 +296,7 @@ const checkFingerprints = (graph, nodes, context) => {
             });
     }
 };
-const checkGraph = (graph, context) => {
+const checkGraphContent = (graph, context) => {
     checkCanonicalOrder(graph, context);
     const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
     checkNodes(graph, nodes, context);
@@ -311,6 +312,9 @@ const checkGraph = (graph, context) => {
             path: ["limitations"],
             message: "Non-complete graph coverage requires a limitation",
         });
+};
+const checkGraph = (graph, context) => {
+    checkGraphContent(graph, context);
     const { graph_id: identifier, ...semantic } = graph;
     if (identifier !==
         "jsrg_" + canonicalDigest(semantic, "JavaScript semantic graph"))
@@ -344,8 +348,20 @@ export const createJavaScriptSemanticGraph = (input) => {
         },
         limitations: uniqueSorted(parsed.limitations),
     };
-    return javaScriptSemanticGraphSchema.parse({
+    // The input schema already cloned and validated every field. Validate the
+    // normalized relationships in place, then derive the only added field. The
+    // public schema still verifies arbitrary records and their commitments.
+    const record = {
         ...semantic,
         graph_id: `jsrg_${canonicalDigest(semantic, "JavaScript semantic graph")}`,
+    };
+    const issues = [];
+    checkGraphContent(record, {
+        addIssue: (issue) => {
+            issues.push(issue);
+        },
     });
+    if (issues.length > 0)
+        throw new z.ZodError(issues);
+    return record;
 };

package/dist/domain/jsonValue.js

@@ -1,5 +1,9 @@
 import { z } from "zod";
 /** JSON-safe value shared by domain, application, and adapter boundaries. */
 export const jsonValueSchema = z.json();
+// Every JSON value satisfies `{}`. Advertise that instead of Zod's
+// self-referential `$defs` projection, which MCP clients and model APIs that
+// reject recursive JSON Schemas refuse. Runtime parsing still admits only JSON.
+jsonValueSchema._zod.toJSONSchema = () => ({});
 /** JSON object boundary for caller-visible parameter maps. */
 export const jsonObjectSchema = z.record(z.string(), jsonValueSchema);

package/dist/domain/localPath.js

@@ -1,4 +1,6 @@
 import { isAbsolute, relative, sep } from "node:path";
+/** True when the value is an absolute filesystem path on the host platform. */
+export const isAbsoluteLocalPath = (value) => isAbsolute(value);
 /** Test lexical containment on the host platform; callers must resolve symlinks first. */
 export const isPathWithinRoot = (root, path) => {
     const value = relative(root, path);