rea-agents 2.0.0 → 2.1.0

package/dist/domain/reconstructionVerificationSchemas.js

@@ -70,6 +70,14 @@ export const reconstructionSpecificationSchema = z
 /** Bounded reconstruction-verification input. */
 export const reconstructionVerificationInputSchema = z.strictObject({
     specification: reconstructionSpecificationSchema,
+    coverage: z
+        .strictObject({
+        workspace_id: z.string().regex(/^rcw_[a-f0-9]{64}$/u),
+        revision: z.number().int().min(1),
+        revision_sha256: digestSchema,
+        boundary_id: z.string().min(1).max(200),
+    })
+        .optional(),
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(100).default(100),
     unknown_registry_approved: z.literal(true).optional(),

package/dist/domain/runtimeCharacterization.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const stableIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._:/-]{0,199}$/u);
+const runtimeIdentitySchema = z.strictObject({
+    family: z.string().trim().min(1).max(100),
+    provider_id: stableIdSchema,
+    executable_path: z.string().min(1).max(4_096),
+    executable_sha256: digestSchema,
+    version: z.string().trim().min(1).max(500),
+    profile_sha256: digestSchema,
+});
+const artifactIdentitySchema = z.strictObject({
+    path: z.string().min(1).max(4_096),
+    sha256: digestSchema,
+    byte_length: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+});
+const callableIdentitySchema = z.strictObject({
+    callable_id: stableIdSchema,
+    module_id: stableIdSchema,
+    export_name: z.string().min(1).max(1_000),
+    semantic_evidence_id: z
+        .string()
+        .regex(/^ev_[a-f0-9]{64}$/u)
+        .nullable(),
+    selector_sha256: digestSchema,
+});
+export const runtimeCharacterizationPlanSchema = z.strictObject({
+    schema_version: z.literal(1),
+    plan_sha256: digestSchema,
+    preparation_sha256: digestSchema,
+    artifact: artifactIdentitySchema,
+    runtime: runtimeIdentitySchema,
+    callable: callableIdentitySchema,
+    working_directory: z.string().min(1).max(4_096),
+    isolated_home: z.string().min(1).max(4_096),
+    expected_effect: z.enum(["pure", "bounded-effects", "observation-only"]),
+    allowed_boundaries: z.array(stableIdSchema).max(1_000),
+    limits: z.strictObject({
+        max_calls: z.number().int().min(1).max(10_000),
+        max_processes: z.number().int().min(0).max(1_000),
+        max_files: z.number().int().min(0).max(100_000),
+        max_bytes: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+        max_handles: z.number().int().min(0).max(100_000),
+        timeout_ms: z.number().int().min(1).max(300_000),
+        idle_timeout_ms: z.number().int().min(1).max(300_000),
+    }),
+    determinism: z.strictObject({
+        clock: z.enum(["fixed", "real"]),
+        randomness: z.enum(["seeded", "system"]),
+        identifiers: z.enum(["deterministic", "runtime"]),
+        seed: z.number().int().min(0).max(0xffff_ffff),
+    }),
+    authority: z.strictObject({
+        preparation_approved: z.literal(true),
+        execution_approved: z.literal(false),
+        network: z.enum(["none", "loopback"]),
+        provider_owned_process_only: z.literal(true),
+    }),
+});
+/** Commit a provider-neutral preparation plan; execution requires a later approval. */
+export const createRuntimeCharacterizationPlan = (input) => {
+    const parsed = runtimeCharacterizationPlanSchema
+        .omit({ plan_sha256: true })
+        .parse(input);
+    return runtimeCharacterizationPlanSchema.parse({
+        ...parsed,
+        plan_sha256: digest(parsed),
+    });
+};
+/** Parse a characterization plan and reject altered commitments. */
+export const parseRuntimeCharacterizationPlan = (input) => {
+    const parsed = runtimeCharacterizationPlanSchema.parse(input);
+    const { plan_sha256: planSha256, ...semantic } = parsed;
+    if (planSha256 !== digest(semantic))
+        throw new TypeError("Runtime characterization plan digest is invalid");
+    return parsed;
+};
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Runtime characterization plan is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};

package/dist/domain/webBundleAnalyzer.js

@@ -1,7 +1,5 @@
-import { parse } from "@babel/parser";
-import * as t from "@babel/types";
-import { sanitizeBrowserUrl } from "./browserObservation.js";
-import { webBundleAnalysisSchema, } from "./webBundleAnalysis.js";
+import { analyzeScript, emptyAccumulator, isIncludedScript, } from "./webBundleAnalyzerInspection.js";
+import { buildWebBundleAnalysis } from "./webBundleAnalyzerResult.js";
 /** Analyze captured, explicitly approved JavaScript source without execution. */
 export const analyzeCapturedWebBundle = (inspection, input, sourceMaps = {
     status: "not_requested",
@@ -15,409 +13,5 @@ export const analyzeCapturedWebBundle = (inspection, input, sourceMaps = {
     const sourceScripts = inspection.scripts.items.filter(isIncludedScript);
     for (const script of sourceScripts)
         analyzeScript(script, input, accumulator);
-    const unavailable = inspection.scripts.items
-        .filter((script) => !script.source.included)
-        .map(({ script_key }) => script_key);
-    const sourceMapIncomplete = sourceMaps.status === "partial" || sourceMaps.status === "unavailable";
-    const partial = accumulator.parseFailures > 0 ||
-        unavailable.length > 0 ||
-        sourceMapIncomplete;
-    const truncated = accumulator.astLimitReached ||
-        accumulator.droppedFindings > 0 ||
-        sourceMaps.status === "truncated";
-    return webBundleAnalysisSchema.parse({
-        schema_version: 1,
-        capture: {
-            target_url: inspection.target.url,
-            scripts_observed: inspection.scripts.total,
-            scripts_analyzed: sourceScripts.length,
-            source_artifacts: sourceScripts.map((script) => {
-                if (!script.source.included)
-                    throw new TypeError("Filtered source changed");
-                const { text: _text, ...artifact } = script.source.artifact;
-                return { ...artifact, text_available: true };
-            }),
-        },
-        observations: {
-            chunks: {
-                nodes: sourceScripts.map((script) => {
-                    if (!script.source.included)
-                        throw new TypeError("Filtered source changed");
-                    return {
-                        script_key: script.script_key,
-                        url: script.url,
-                        artifact_sha256: script.source.artifact.sha256,
-                        bytes: script.source.artifact.bytes,
-                    };
-                }),
-                edges: accumulator.edges,
-            },
-            routes: accumulator.routes,
-            endpoints: accumulator.endpoints,
-            webmcp_declarations: accumulator.webMcp,
-            source_maps: sourceMaps,
-        },
-        inferences: accumulator.inferences,
-        unknowns: [
-            ...(unavailable.length === 0
-                ? []
-                : [
-                    {
-                        dimension: "script_source",
-                        reason: "Source artifact was not captured within approved limits",
-                        affected_script_keys: unavailable,
-                    },
-                ]),
-            ...(accumulator.parseFailures === 0
-                ? []
-                : [
-                    {
-                        dimension: "javascript_ast",
-                        reason: "One or more source artifacts could not be parsed",
-                        affected_script_keys: sourceScripts.map(({ script_key }) => script_key),
-                    },
-                ]),
-            ...(sourceMaps.status === "not_requested" ||
-                sourceMaps.status === "included"
-                ? []
-                : [
-                    {
-                        dimension: "source_maps",
-                        reason: sourceMaps.status === "truncated"
-                            ? "Source-map evidence was truncated by approved limits"
-                            : "One or more requested source maps were unavailable or incomplete",
-                        affected_script_keys: [
-                            ...new Set([
-                                ...sourceMaps.items
-                                    .filter(({ status }) => status !== "included")
-                                    .map(({ script_key }) => script_key),
-                                ...sourceMaps.dropped_script_keys,
-                            ]),
-                        ].sort(),
-                    },
-                ]),
-        ],
-        completeness: {
-            status: truncated
-                ? "truncated"
-                : partial
-                    ? "partial"
-                    : "complete_within_limits",
-            parsed_scripts: accumulator.parsedScripts,
-            parse_failures: accumulator.parseFailures,
-            visited_ast_nodes: accumulator.visitedNodes,
-            dropped_findings: accumulator.droppedFindings,
-        },
-        limitations: [
-            "Static bundle findings are observations or bounded inferences; REA does not execute captured JavaScript.",
-            "String-built routes and endpoints, encrypted configuration, and server-side behavior may remain unknown.",
-            "Page-declared WebMCP metadata is untrusted and is never registered or invoked as an REA tool.",
-        ],
-    });
+    return buildWebBundleAnalysis(inspection, sourceScripts, sourceMaps, accumulator);
 };
-const analyzeScript = (script, input, accumulator) => {
-    let file;
-    try {
-        file = parse(script.source.artifact.text, {
-            sourceType: "unambiguous",
-            errorRecovery: true,
-            plugins: ["jsx", "typescript"],
-        });
-    }
-    catch {
-        accumulator.parseFailures += 1;
-        return;
-    }
-    accumulator.parsedScripts += 1;
-    detectVendorFingerprints(script, accumulator, input.analysis_limits.max_findings);
-    t.traverseFast(file, (node) => {
-        accumulator.visitedNodes += 1;
-        if (accumulator.visitedNodes > input.analysis_limits.max_ast_nodes) {
-            accumulator.astLimitReached = true;
-            return t.traverseFast.stop;
-        }
-        inspectNode(script, node, accumulator, input.analysis_limits.max_findings);
-        return undefined;
-    });
-};
-const inspectNode = (script, node, accumulator, maximumFindings) => {
-    if ((t.isImportDeclaration(node) || t.isExportAllDeclaration(node)) &&
-        node.source !== undefined)
-        addEdge(script, node.source.value, "static_import", node, accumulator, maximumFindings);
-    else if (t.isExportNamedDeclaration(node) && node.source != null)
-        addEdge(script, node.source.value, "static_import", node, accumulator, maximumFindings);
-    else if (t.isImportExpression(node) && t.isStringLiteral(node.source))
-        addEdge(script, node.source.value, "dynamic_import", node, accumulator, maximumFindings);
-    if (t.isObjectProperty(node))
-        inspectRouteProperty(script, node, accumulator, maximumFindings);
-    if (t.isCallExpression(node) || t.isNewExpression(node))
-        inspectCall(script, node, accumulator, maximumFindings);
-};
-const inspectCall = (script, node, accumulator, maximumFindings) => {
-    const name = calleeName(node.callee);
-    const first = stringArgument(node.arguments[0]);
-    if ((name === "require" || name.endsWith(".require")) && first !== undefined)
-        addEdge(script, first, "require", node, accumulator, maximumFindings);
-    if ((name === "importScripts" || name.endsWith(".importScripts")) &&
-        first !== undefined)
-        addEdge(script, first, "worker_import", node, accumulator, maximumFindings);
-    if (routeCallNames.some((candidate) => name === candidate || name.endsWith(`.${candidate}`))) {
-        if (first !== undefined)
-            addFinding(accumulator.routes, script, first, `call:${name}`, node, accumulator, maximumFindings);
-        addRouteFrameworkInference(script, name, node, accumulator, maximumFindings);
-    }
-    const endpoint = endpointArgument(name, node.arguments);
-    if (endpoint !== undefined)
-        addFinding(accumulator.endpoints, script, endpoint, `call:${name}`, node, accumulator, maximumFindings);
-    if (name.endsWith("modelContext.registerTool") ||
-        name === "modelContext.registerTool")
-        addWebMcpDeclaration(script, node, accumulator, maximumFindings);
-};
-const inspectRouteProperty = (script, node, accumulator, maximumFindings) => {
-    const key = propertyName(node.key);
-    if ((key === "path" || key === "route") && t.isStringLiteral(node.value))
-        addFinding(accumulator.routes, script, node.value.value, `property:${key}`, node, accumulator, maximumFindings);
-};
-const addEdge = (script, specifier, kind, node, accumulator, maximumFindings) => {
-    const bounded = specifier.slice(0, 4_096);
-    const key = `edge\0${script.script_key}\0${kind}\0${bounded}`;
-    addBounded(accumulator, key, maximumFindings, () => accumulator.edges.push({
-        from_script_key: script.script_key,
-        kind,
-        specifier: bounded,
-        resolved_url: resolveSpecifier(bounded, script.url),
-        location: location(script.script_key, node),
-    }));
-};
-const addFinding = (collection, script, rawValue, mechanism, node, accumulator, maximumFindings) => {
-    const value = sanitizeCandidate(rawValue);
-    const key = `finding\0${mechanism}\0${script.script_key}\0${value}`;
-    addBounded(accumulator, key, maximumFindings, () => collection.push({
-        value,
-        mechanism,
-        location: location(script.script_key, node),
-    }));
-};
-const addWebMcpDeclaration = (script, node, accumulator, maximumFindings) => {
-    const declaration = node.arguments[0];
-    if (!t.isObjectExpression(declaration))
-        return;
-    const name = objectString(declaration, "name");
-    const description = objectString(declaration, "description");
-    const schema = objectValue(declaration, "inputSchema") ??
-        objectValue(declaration, "input_schema");
-    const declaredProperties = t.isObjectExpression(schema)
-        ? objectValue(schema, "properties")
-        : undefined;
-    const propertyObject = t.isObjectExpression(declaredProperties)
-        ? declaredProperties
-        : schema;
-    const schemaPropertyNames = t.isObjectExpression(propertyObject)
-        ? propertyObject.properties.flatMap((property) => t.isObjectProperty(property)
-            ? [propertyName(property.key)].filter(Boolean)
-            : [])
-        : [];
-    const key = `webmcp\0${script.script_key}\0${name ?? ""}\0${schemaPropertyNames.join("\0")}`;
-    addBounded(accumulator, key, maximumFindings, () => accumulator.webMcp.push({
-        name: name?.slice(0, 256) ?? null,
-        description: description?.slice(0, 2_048) ?? null,
-        schema_property_names: [...new Set(schemaPropertyNames)]
-            .sort()
-            .slice(0, 256),
-        trust: "page-declared-untrusted",
-        location: location(script.script_key, node),
-    }));
-};
-const detectVendorFingerprints = (script, accumulator, maximumFindings) => {
-    const text = script.source.artifact.text;
-    for (const detector of vendorDetectors) {
-        if (!detector.patterns.some((pattern) => text.includes(pattern)))
-            continue;
-        const key = `vendor\0${script.script_key}\0${detector.value}`;
-        addBounded(accumulator, key, maximumFindings, () => accumulator.inferences.push({
-            kind: detector.kind,
-            value: detector.value,
-            confidence: detector.confidence,
-            basis: [basis(script, detector.detector)],
-        }));
-    }
-};
-const addRouteFrameworkInference = (script, name, node, accumulator, maximumFindings) => {
-    const value = name.endsWith("useRoutes") || name.endsWith("createBrowserRouter")
-        ? "React Router-compatible route API"
-        : "Generic route registration API";
-    const key = `route-framework\0${script.script_key}\0${value}`;
-    addBounded(accumulator, key, maximumFindings, () => accumulator.inferences.push({
-        kind: "route_framework",
-        value,
-        confidence: "medium",
-        basis: [{ ...basis(script, `call:${name}`), ...locationFields(node) }],
-    }));
-};
-const addBounded = (accumulator, key, maximum, add) => {
-    if (accumulator.seen.has(key))
-        return;
-    const findings = accumulator.edges.length +
-        accumulator.routes.length +
-        accumulator.endpoints.length +
-        accumulator.webMcp.length +
-        accumulator.inferences.length;
-    if (findings >= maximum) {
-        accumulator.droppedFindings += 1;
-        return;
-    }
-    accumulator.seen.add(key);
-    add();
-};
-const endpointArgument = (name, args) => {
-    if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket")
-        return stringArgument(args[0]);
-    if (name.endsWith(".open") && stringArgument(args[1]) !== undefined)
-        return stringArgument(args[1]);
-    if (["get", "post", "put", "patch", "delete", "request"].some((method) => name === method || name.endsWith(`.${method}`)))
-        return stringArgument(args[0]);
-    return undefined;
-};
-const calleeName = (callee) => {
-    if (t.isIdentifier(callee))
-        return callee.name;
-    if (t.isImport(callee))
-        return "import";
-    if (t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)) {
-        const object = t.isExpression(callee.object)
-            ? calleeName(callee.object)
-            : "";
-        const property = propertyName(callee.property);
-        return object === "" ? property : `${object}.${property}`;
-    }
-    return "";
-};
-const stringArgument = (value) => (t.isStringLiteral(value) ? value.value : undefined);
-const propertyName = (value) => {
-    if (t.isIdentifier(value))
-        return value.name;
-    if (t.isStringLiteral(value))
-        return value.value;
-    return "";
-};
-const objectValue = (object, name) => {
-    for (const property of object.properties)
-        if (t.isObjectProperty(property) && propertyName(property.key) === name)
-            return property.value;
-    return undefined;
-};
-const objectString = (object, name) => {
-    const value = objectValue(object, name);
-    return t.isStringLiteral(value) ? value.value : undefined;
-};
-const resolveSpecifier = (specifier, base) => {
-    try {
-        const resolved = new URL(specifier, base);
-        if (resolved.protocol !== "http:" && resolved.protocol !== "https:")
-            return null;
-        return sanitizeBrowserUrl(resolved.href).url;
-    }
-    catch {
-        return null;
-    }
-};
-const sanitizeCandidate = (value) => {
-    const bounded = value.slice(0, 4_096);
-    try {
-        const parsed = new URL(bounded, "https://rea.invalid");
-        const sanitized = sanitizeBrowserUrl(parsed.href).url;
-        return parsed.origin === "https://rea.invalid"
-            ? sanitized.replace("https://rea.invalid", "")
-            : sanitized;
-    }
-    catch {
-        return bounded.split("#", 1)[0]?.split("?", 1)[0] ?? "";
-    }
-};
-const location = (scriptKey, node) => ({
-    script_key: scriptKey,
-    ...locationFields(node),
-});
-const locationFields = (node) => ({
-    line: node.loc?.start.line ?? null,
-    column: node.loc?.start.column ?? null,
-});
-const basis = (script, detector) => ({
-    script_key: script.script_key,
-    artifact_sha256: script.source.artifact.sha256,
-    line: null,
-    column: null,
-    detector,
-});
-const emptyAccumulator = () => ({
-    edges: [],
-    routes: [],
-    endpoints: [],
-    webMcp: [],
-    inferences: [],
-    seen: new Set(),
-    visitedNodes: 0,
-    parsedScripts: 0,
-    parseFailures: 0,
-    droppedFindings: 0,
-    astLimitReached: false,
-});
-const isIncludedScript = (script) => script.source.included;
-const routeCallNames = [
-    "route",
-    "addRoute",
-    "useRoutes",
-    "createBrowserRouter",
-    "createHashRouter",
-];
-const vendorDetectors = [
-    {
-        value: "webpack",
-        detector: "webpack-runtime",
-        patterns: ["__webpack_require__"],
-        confidence: "high",
-        kind: "bundle_runtime",
-    },
-    {
-        value: "Vite",
-        detector: "vite-runtime",
-        patterns: ["__vite__", "import.meta.hot"],
-        confidence: "medium",
-        kind: "bundle_runtime",
-    },
-    {
-        value: "React",
-        detector: "react-runtime",
-        patterns: ["__REACT_DEVTOOLS_GLOBAL_HOOK__", "React.createElement"],
-        confidence: "medium",
-        kind: "vendor_fingerprint",
-    },
-    {
-        value: "Vue",
-        detector: "vue-runtime",
-        patterns: ["__VUE__", "createApp("],
-        confidence: "medium",
-        kind: "vendor_fingerprint",
-    },
-    {
-        value: "Next.js",
-        detector: "next-runtime",
-        patterns: ["__NEXT_DATA__", "/_next/"],
-        confidence: "high",
-        kind: "vendor_fingerprint",
-    },
-    {
-        value: "Angular",
-        detector: "angular-runtime",
-        patterns: ["ɵɵdefineComponent"],
-        confidence: "high",
-        kind: "vendor_fingerprint",
-    },
-    {
-        value: "Svelte",
-        detector: "svelte-runtime",
-        patterns: ["svelte/internal"],
-        confidence: "medium",
-        kind: "vendor_fingerprint",
-    },
-];

package/dist/domain/webBundleAnalyzerAst.js

@@ -0,0 +1,77 @@
+import * as t from "@babel/types";
+import { sanitizeBrowserUrl } from "./browserObservation.js";
+/** Name of a call/new callee from its AST node. */
+export const calleeName = (callee) => {
+    if (t.isIdentifier(callee))
+        return callee.name;
+    if (t.isImport(callee))
+        return "import";
+    if (t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)) {
+        const object = t.isExpression(callee.object)
+            ? calleeName(callee.object)
+            : "";
+        const property = propertyName(callee.property);
+        return object === "" ? property : `${object}.${property}`;
+    }
+    return "";
+};
+export const stringArgument = (value) => (t.isStringLiteral(value) ? value.value : undefined);
+export const propertyName = (value) => {
+    if (t.isIdentifier(value))
+        return value.name;
+    if (t.isStringLiteral(value))
+        return value.value;
+    return "";
+};
+export const objectValue = (object, name) => {
+    for (const property of object.properties)
+        if (t.isObjectProperty(property) && propertyName(property.key) === name)
+            return property.value;
+    return undefined;
+};
+export const objectString = (object, name) => {
+    const value = objectValue(object, name);
+    return t.isStringLiteral(value) ? value.value : undefined;
+};
+export const resolveSpecifier = (specifier, base) => {
+    try {
+        const resolved = new URL(specifier, base);
+        if (resolved.protocol !== "http:" && resolved.protocol !== "https:")
+            return null;
+        return sanitizeBrowserUrl(resolved.href).url;
+    }
+    catch {
+        return null;
+    }
+};
+export const sanitizeCandidate = (value) => {
+    const bounded = value.slice(0, 4_096);
+    try {
+        const parsed = new URL(bounded, "https://rea.invalid");
+        const sanitized = sanitizeBrowserUrl(parsed.href).url;
+        return parsed.origin === "https://rea.invalid"
+            ? sanitized.replace("https://rea.invalid", "")
+            : sanitized;
+    }
+    catch {
+        return bounded.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+    }
+};
+export const location = (scriptKey, node) => ({
+    script_key: scriptKey,
+    ...locationFields(node),
+});
+export const locationFields = (node) => ({
+    line: node.loc?.start.line ?? null,
+    column: node.loc?.start.column ?? null,
+});
+/** Pick the endpoint argument for common network-call patterns. */
+export const endpointArgument = (name, args) => {
+    if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket")
+        return stringArgument(args[0]);
+    if (name.endsWith(".open") && stringArgument(args[1]) !== undefined)
+        return stringArgument(args[1]);
+    if (["get", "post", "put", "patch", "delete", "request"].some((method) => name === method || name.endsWith(`.${method}`)))
+        return stringArgument(args[0]);
+    return undefined;
+};