rea-agents 2.4.0 → 3.0.0

package/dist/domain/javascriptRuntimeReconciliationParsing.js

@@ -1,8 +1,11 @@
 import { createHash } from "node:crypto";
+import { isAbsolute, relative } from "node:path";
 import canonicalize from "canonicalize";
 import { z } from "zod";
-import { browserAllowedOriginsSchema, browserEndpointSchema, webPageInspectionSchema, } from "./browserObservation.js";
+import { browserAllowedOriginsSchema, browserEndpointSchema, browserOriginSchema, webPageInspectionSchema, } from "./browserObservation.js";
+import { classifyBrowserCompleteness, } from "./browserCompleteness.js";
 import { electronFileRootsSchema, electronPageInspectionSchema, } from "./electronObservation.js";
+import { javascriptRuntimeObservationSchema, javascriptRuntimeKindSchema, } from "./javascriptRuntimeObservation.js";
 import { parseEvidence } from "./evidence.js";
 import { javascriptApplicationAnalysisResultSchema, } from "./javascriptApplicationAnalysis.js";
 import { compareCodePoints, } from "./javascriptApplicationGraph.js";
@@ -109,8 +112,123 @@ const parseRuntimeCapture = (input) => {
             scriptsCompleteWithinScope: scriptsComplete(inspection.completeness),
         };
     }
-    throw new TypeError("Runtime reconciliation requires inspect_web_page or inspect_electron_page Evidence");
+    if (evidence.operation === "observe_javascript_runtime") {
+        assertEvidenceIdentity(evidence, {
+            operation: "observe_javascript_runtime",
+            predicate: "rea.javascript-runtime-observation/v1",
+            providerId: "rea-v8-inspector",
+            providerName: "REA passive Node/Electron V8 Inspector provider",
+            providerVersion: "1",
+            authority: "external-service",
+            confidence: "observed",
+        });
+        const result = javascriptRuntimeObservationSchema.parse(evidence.normalized_result);
+        assertV8RuntimeParameters(evidence, result);
+        const inspection = normalizeV8Inspection(result);
+        return {
+            kind: "v8-inspector",
+            evidence,
+            inspection,
+            captureSha256: digestCanonical(result),
+            scriptsCompleteWithinScope: false,
+        };
+    }
+    throw new TypeError("Runtime reconciliation requires inspect_web_page, inspect_electron_page, or observe_javascript_runtime Evidence");
+};
+const assertV8RuntimeParameters = (evidence, result) => {
+    const parameters = z
+        .object({
+        inspector_endpoint: browserEndpointSchema,
+        allowed_file_roots: z
+            .array(z.string().min(1).max(16_384).refine(isAbsolute))
+            .max(32),
+        allowed_origins: z.array(browserOriginSchema).max(32),
+        target_id: z.string().trim().min(1).max(256),
+        runtime_kind: javascriptRuntimeKindSchema,
+    })
+        .passthrough()
+        .parse(evidence.parameters);
+    if (parameters.target_id !== result.target.target_id ||
+        parameters.runtime_kind !== result.target.runtime_kind)
+        throw new TypeError("Runtime Evidence target or declared role disagrees with its result");
+    for (const location of [
+        result.target.location,
+        ...result.scripts.items.map(({ location }) => location),
+    ])
+        if ((location.kind === "file" &&
+            !parameters.allowed_file_roots.some((root) => isWithinRoot(root, location.file_path))) ||
+            (location.kind === "url" &&
+                !parameters.allowed_origins.includes(location.origin)) ||
+            (location.kind === "builtin" && !location.specifier.startsWith("node:")))
+            throw new TypeError("Runtime Evidence contains a location outside its recorded scope");
+};
+const isWithinRoot = (root, path) => {
+    const remainder = relative(root, path);
+    return (remainder === "" || (!remainder.startsWith("..") && !isAbsolute(remainder)));
+};
+const normalizeV8Inspection = (result) => ({
+    target: {
+        target_id: result.target.target_id,
+        type: result.target.protocol_type,
+        title: result.target.runtime_kind,
+        attached: result.target.attached,
+        ...runtimeLocation(result.target.location),
+    },
+    frames: [],
+    scripts: {
+        items: result.scripts.items.map((script) => ({
+            script_key: script.script_key,
+            frame_id: script.execution_context_key,
+            ...runtimeLocation(script.location),
+            cdp_hash: script.cdp_hash ?? "",
+            length: script.length,
+            is_module: script.is_module,
+            language: null,
+            source: {
+                included: false,
+                reason: "V8 Inspector source capture is outside passive authority.",
+            },
+        })),
+    },
+    workers: [],
+    completeness: classifyBrowserCompleteness({
+        policyFilteredSections: new Set(excludedV8Scripts(result) > 0 ? ["scripts"] : []),
+        attachLimitedSections: new Set([
+            "frames",
+            "scripts",
+            "script_sources",
+            "workers",
+        ]),
+        truncatedSections: new Set(result.capture.truncated ? ["scripts"] : []),
+        unavailableSections: new Set(["frames", "script_sources", "workers"]),
+        excluded: excludedV8Scripts(result) === 0
+            ? []
+            : [
+                {
+                    section: "scripts",
+                    reason: "out_of_target_scope",
+                    count: excludedV8Scripts(result),
+                },
+            ],
+        droppedEvents: {
+            scripts: result.capture.events_dropped,
+            network_requests: 0,
+            console_events: 0,
+            websocket_connections: 0,
+            websocket_frames: 0,
+            webmcp_tools: 0,
+            timeline_events: 0,
+        },
+    }),
+});
+const runtimeLocation = (location) => {
+    if (location.kind === "file")
+        return { file_path: location.file_path };
+    if (location.kind === "url")
+        return { url: location.sanitized_url };
+    return { url: location.specifier };
 };
+const excludedV8Scripts = (result) => Object.values(result.scripts.excluded).reduce((total, count) => total + count, 0);
 const assertRuntimeParameters = (evidence, expected) => {
     const common = {
         target_id: z.string().trim().min(1).max(256),

package/dist/domain/javascriptRuntimeReconciliationResult.js

@@ -45,9 +45,9 @@ const captureSummaries = (captures, runtime) => captures.map((capture) => {
         kind: capture.kind,
         target_node_id: targetNode.node_id,
         target_key: capture.inspection.target.target_id,
-        target_location: capture.kind === "browser"
-            ? capture.inspection.target.url.slice(0, 4_096)
-            : capture.inspection.target.file_path.slice(0, 4_096),
+        target_location: ("url" in capture.inspection.target
+            ? capture.inspection.target.url
+            : capture.inspection.target.file_path).slice(0, 4_096),
         frames: capture.inspection.frames.length,
         scripts: capture.inspection.scripts.items.length,
         workers: capture.inspection.workers.length,

package/dist/domain/javascriptRuntimeReconciliationRuntime.js

@@ -197,7 +197,7 @@ const runtimeEvidence = (capture, input) => ({
         name: capture.evidence.provider.id,
         version: capture.evidence.provider.version ??
             (capture.kind === "browser" ? "2" : "1"),
-        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        operation: capture.evidence.operation,
         executable_sha256: null,
     },
     coverage: runtimeSectionCoverage(capture, input.section),
@@ -260,7 +260,7 @@ const runtimeRelationshipEvidence = (capture, entity) => ({
         name: capture.evidence.provider.id,
         version: capture.evidence.provider.version ??
             (capture.kind === "browser" ? "2" : "1"),
-        operation: capture.kind === "browser" ? "inspect_web_page" : "inspect_electron_page",
+        operation: capture.evidence.operation,
         executable_sha256: null,
     },
     coverage: runtimeSectionCoverage(capture, entity.section),

package/dist/domain/javascriptRuntimeReconciliationSchemas.js

@@ -133,7 +133,7 @@ const layerSummarySchema = z.strictObject({
 const captureSummarySchema = z.strictObject({
     evidence_id: evidenceIdSchema,
     capture_sha256: digestSchema,
-    kind: z.enum(["browser", "electron"]),
+    kind: z.enum(["browser", "electron", "v8-inspector"]),
     target_node_id: nodeIdSchema,
     target_key: boundedTextSchema,
     target_location: boundedTextSchema,

package/dist/domain/javascriptSemanticAnalysis.js

@@ -1,26 +1,22 @@
-import { parse } from "@babel/parser";
 import * as t from "@babel/types";
 import { DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS, failedJavaScriptSemanticIr, } from "./javascriptSemanticIr.js";
 import { collectSemanticModuleLink, collectSemanticCallable, collectSemanticReferences, immutableSemanticBindings, immutableSemanticScopes, reachSemanticLimit, semanticModuleOrigin, semanticStaticPropertyName, } from "./javascriptSemanticProjection.js";
 import { currentSemanticScope, resolveSemanticBindingFromScope, semanticScopeId, semanticVariableScope, } from "./javascriptSemanticState.js";
 import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
 import { collectSemanticReturns, resolveSemanticModuleCallables, } from "./javascriptSemanticReturns.js";
-import { collectJavaScriptSemanticCalls } from "./javascriptSemanticCalls.js";
+import { collectJavaScriptDerivedSemantics } from "./javascriptSemanticDerivedAnalysis.js";
 import { compareCodePoints, propertyName, range, } from "./javascriptStaticAnalysisHelpers.js";
+import { parseJavaScriptSource, } from "./javascriptSourceParser.js";
 /** Recover bounded lexical bindings, aliases, constants, and module links. */
 export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
+    const file = parseJavaScriptSource(source);
+    return file === null
+        ? failedJavaScriptSemanticIr()
+        : analyzeParsedJavaScriptSemantics(file, inputLimits);
+};
+/** Recover semantics from an already parsed JavaScript artifact. */
+export const analyzeParsedJavaScriptSemantics = (file, inputLimits = {}) => {
     const limits = { ...DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS, ...inputLimits };
-    let file;
-    try {
-        file = parse(source, {
-            sourceType: "unambiguous",
-            errorRecovery: true,
-            plugins: ["jsx", "typescript"],
-        });
-    }
-    catch {
-        return failedJavaScriptSemanticIr();
-    }
     const state = createState(file.program, limits);
     collectDefinitions(file.program, state);
     const references = collectSemanticReferences(file.program, state);
@@ -28,16 +24,16 @@ export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
     const bindings = immutableSemanticBindings(state);
     const callables = collectSemanticReturns(file.program, state, parserPartial);
     const moduleLinks = resolveSemanticModuleCallables(state, callables);
-    const calls = collectJavaScriptSemanticCalls(file.program, state, callables);
+    const derived = collectJavaScriptDerivedSemantics(file.program, state, callables, parserPartial);
     return {
         schema: "JavaScriptSemanticIR",
-        schemaVersion: 3,
+        schemaVersion: 4,
         scopes: immutableSemanticScopes(state),
         bindings,
         callables,
         references,
         moduleLinks,
-        ...calls,
+        ...derived,
         coverage: {
             status: state.limitsReached.size > 0
                 ? "truncated"
@@ -59,6 +55,7 @@ export const analyzeJavaScriptSemantics = (source, inputLimits = {}) => {
             "Values and aliases were recovered from inert syntax only; no JavaScript was executed.",
             "Return sites include only direct callable returns; nested callable returns remain separate.",
             "Local call, argument, return, and closure relations are static candidates and do not prove runtime invocation.",
+            "Promise ownership covers explicit unshadowed Promise construction, static factories, aggregation, chaining, and await syntax only.",
             "Cross-function mutation and dynamic property resolution remain unknown.",
         ],
     };

package/dist/domain/javascriptSemanticAsyncEffects.js

@@ -0,0 +1,253 @@
+import * as t from "@babel/types";
+import { reachSemanticLimit, semanticCallableIdForNode, semanticStaticPropertyName, } from "./javascriptSemanticProjection.js";
+import { resolveSemanticBindingState, semanticResolutionBlocked, } from "./javascriptSemanticState.js";
+import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { range } from "./javascriptStaticAnalysisHelpers.js";
+const EVENT_REGISTER_METHODS = [
+    "on",
+    "once",
+    "addListener",
+    "prependListener",
+    "prependOnceListener",
+];
+const EVENT_REMOVE_METHODS = [
+    "off",
+    "removeListener",
+    "removeAllListeners",
+];
+const EVENT_METHODS = [
+    ...EVENT_REGISTER_METHODS,
+    ...EVENT_REMOVE_METHODS,
+    "emit",
+];
+const TIMER_SCHEDULE_METHODS = [
+    "setTimeout",
+    "setInterval",
+    "setImmediate",
+];
+const TIMER_CANCEL_METHODS = [
+    "clearTimeout",
+    "clearInterval",
+    "clearImmediate",
+];
+/** Recover explicit EventEmitter and Node timer candidates from inert syntax. */
+export const collectJavaScriptSemanticAsyncEffects = (program, state, callables) => {
+    const events = [];
+    const timers = [];
+    const callableIds = new Set(callables.map(({ callableId }) => callableId));
+    const callableStack = [];
+    traverseJavaScriptAst(program, {
+        enter: (node, parent) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && callableIds.has(callableId))
+                callableStack.push(callableId);
+            if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
+                return;
+            const ownerCallableId = callableStack.at(-1) ?? null;
+            collectEvent(node, ownerCallableId, state, events);
+            collectTimer({ node, parent, ownerCallableId, state, output: timers });
+        },
+        exit: (node) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && callableStack.at(-1) === callableId)
+                callableStack.pop();
+        },
+    });
+    return {
+        eventOperations: events,
+        timerOperations: resolveTimers(timers),
+    };
+};
+const collectEvent = (node, ownerCallableId, state, output) => {
+    const member = memberCallee(node);
+    if (member === null)
+        return;
+    const method = EVENT_METHODS.find((candidate) => candidate ===
+        semanticStaticPropertyName(member.property, member.computed));
+    if (method === undefined)
+        return;
+    const kind = eventKind(method);
+    if (output.length >= state.limits.maxEventOperations) {
+        reachSemanticLimit(state, "maxEventOperations");
+        return;
+    }
+    const eventArgument = node.arguments[0];
+    const listenerArgument = node.arguments[1];
+    const emitter = emitterIdentity(member.object, state);
+    const eventName = literalString(eventArgument);
+    output.push({
+        eventId: `event:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
+        kind,
+        method,
+        location: range(node),
+        ownerCallableId,
+        emitterKey: emitter.key,
+        emitterBindingId: emitter.bindingId,
+        eventName,
+        listenerBindingId: bindingId(listenerArgument, state),
+        listenerLocation: t.isNode(listenerArgument)
+            ? range(listenerArgument)
+            : null,
+        resolution: eventName === null
+            ? "unresolved"
+            : emitter.complete
+                ? "complete"
+                : "partial",
+    });
+};
+const eventKind = (method) => {
+    if (EVENT_REGISTER_METHODS.some((candidate) => candidate === method))
+        return "register";
+    if (EVENT_REMOVE_METHODS.some((candidate) => candidate === method))
+        return "remove";
+    return "dispatch";
+};
+const emitterIdentity = (node, state) => {
+    if (t.isIdentifier(node)) {
+        const binding = resolveSemanticBindingState(state, node, node.name);
+        if (binding !== undefined)
+            return {
+                key: `binding:${binding.bindingId}`,
+                bindingId: binding.bindingId,
+                complete: true,
+            };
+        return {
+            key: `global:${node.name}`,
+            bindingId: null,
+            complete: !semanticResolutionBlocked(state, node, node.name),
+        };
+    }
+    if (t.isThisExpression(node))
+        return { key: "this", bindingId: null, complete: true };
+    return {
+        key: `expression:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
+        bindingId: null,
+        complete: false,
+    };
+};
+const collectTimer = (input) => {
+    const { node, parent, ownerCallableId, state, output } = input;
+    const method = timerMethod(node.callee, state);
+    if (method === null)
+        return;
+    if (output.length >= state.limits.maxTimerOperations) {
+        reachSemanticLimit(state, "maxTimerOperations");
+        return;
+    }
+    const kind = TIMER_SCHEDULE_METHODS.some((candidate) => candidate === method)
+        ? "schedule"
+        : "cancel";
+    output.push({
+        node,
+        method,
+        kind,
+        ownerCallableId,
+        handleBindingId: kind === "schedule"
+            ? assignedBindingId(parent, node, state)
+            : bindingId(node.arguments[0], state),
+    });
+};
+const resolveTimers = (candidates) => {
+    const schedulesByBinding = new Map();
+    for (const candidate of candidates) {
+        if (candidate.kind !== "schedule" || candidate.handleBindingId === null)
+            continue;
+        const existing = schedulesByBinding.get(candidate.handleBindingId) ?? [];
+        existing.push(candidate);
+        schedulesByBinding.set(candidate.handleBindingId, existing);
+    }
+    return candidates.map((candidate) => {
+        const linked = candidate.kind === "cancel" && candidate.handleBindingId !== null
+            ? (schedulesByBinding.get(candidate.handleBindingId) ?? [])
+            : [];
+        return {
+            timerId: timerId(candidate),
+            kind: candidate.kind,
+            method: candidate.method,
+            location: range(candidate.node),
+            ownerCallableId: candidate.ownerCallableId,
+            handleBindingId: candidate.handleBindingId,
+            linkedTimerId: linked.length === 1 && linked[0] !== undefined
+                ? timerId(linked[0])
+                : null,
+            delayMilliseconds: timerDelay(candidate),
+            resolution: candidate.kind === "schedule"
+                ? "complete"
+                : linked.length === 1
+                    ? "complete"
+                    : linked.length > 1
+                        ? "partial"
+                        : "unresolved",
+        };
+    });
+};
+const timerMethod = (callee, state) => {
+    if (t.isIdentifier(callee)) {
+        const binding = resolveSemanticBindingState(state, callee, callee.name);
+        if (binding === undefined) {
+            const method = admittedTimerMethod(callee.name);
+            if (method === null)
+                return null;
+            return semanticResolutionBlocked(state, callee, callee.name)
+                ? null
+                : method;
+        }
+        return timerMethodFromBinding(binding);
+    }
+    if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee))
+        return null;
+    const method = admittedTimerMethod(semanticStaticPropertyName(callee.property, callee.computed));
+    return method !== null &&
+        t.isIdentifier(callee.object) &&
+        timerNamespaceBinding(resolveSemanticBindingState(state, callee.object, callee.object.name))
+        ? method
+        : null;
+};
+const admittedTimerMethod = (value) => [...TIMER_SCHEDULE_METHODS, ...TIMER_CANCEL_METHODS].find((candidate) => candidate === value) ?? null;
+const timerMethodFromBinding = (binding) => {
+    for (const { specifier, importedPath } of binding.directOrigins) {
+        if (!timerModule(specifier))
+            continue;
+        const method = admittedTimerMethod(importedPath.at(-1) ?? "");
+        if (method !== null)
+            return method;
+    }
+    return null;
+};
+const timerNamespaceBinding = (binding) => binding?.directOrigins.some(({ specifier, importedPath }) => timerModule(specifier) && importedPath.length === 0) ?? false;
+const timerModule = (specifier) => specifier === "timers" || specifier === "node:timers";
+const assignedBindingId = (parent, node, state) => {
+    const identifier = t.isVariableDeclarator(parent) &&
+        parent.init === node &&
+        t.isIdentifier(parent.id)
+        ? parent.id
+        : t.isAssignmentExpression(parent) &&
+            parent.right === node &&
+            t.isIdentifier(parent.left)
+            ? parent.left
+            : null;
+    return identifier === null
+        ? null
+        : (resolveSemanticBindingState(state, identifier, identifier.name)
+            ?.bindingId ?? null);
+};
+const bindingId = (node, state) => t.isIdentifier(node)
+    ? (resolveSemanticBindingState(state, node, node.name)?.bindingId ?? null)
+    : null;
+const literalString = (node) => {
+    if (t.isStringLiteral(node))
+        return node.value;
+    if (t.isTemplateLiteral(node) && node.expressions.length === 0)
+        return node.quasis[0]?.value.cooked ?? node.quasis[0]?.value.raw ?? null;
+    return null;
+};
+const timerDelay = (candidate) => {
+    if (candidate.kind !== "schedule" || candidate.method === "setImmediate")
+        return null;
+    const delay = candidate.node.arguments[1];
+    return t.isNumericLiteral(delay) ? delay.value : null;
+};
+const timerId = (candidate) => `timer:${candidate.kind}:${String(candidate.node.start ?? -1)}:${String(candidate.node.end ?? -1)}`;
+const memberCallee = (node) => t.isMemberExpression(node.callee) || t.isOptionalMemberExpression(node.callee)
+    ? node.callee
+    : null;