rea-agents 1.7.0 → 2.1.0

package/dist/browser/CdpPageCapture.js

@@ -1,11 +1,13 @@
 import { BrowserObservationError, } from "../domain/errors.js";
-import { reconcileCapturedWebScript, stableWebResources, stableWebScriptKey, } from "../domain/webInventory.js";
+import { stableWebResources } from "../domain/webInventory.js";
 import { CdpConnection } from "./CdpConnection.js";
 import { CdpCaptureEvents } from "./CdpCaptureEvents.js";
 import { captureStorage } from "./CdpCaptureStorage.js";
 import { optionalCdpCommand } from "./CdpOptionalCommand.js";
 import { captureAccessibility, captureDom, captureFrames, captureResources, mainFrameUrl, } from "./CdpCaptureDocuments.js";
-import { allowedSanitizedUrl, delayWithCancellation, isHttpUrl, recordValue, recordsValue, requiredRecord, sourceExcluded, sourceResult, stringValue, } from "./CdpCaptureValues.js";
+import { allowedSanitizedUrl, delayWithCancellation, isHttpUrl, } from "./CdpCaptureValues.js";
+import { captureScripts } from "./CdpPageCaptureScripts.js";
+import { captureWorkers } from "./CdpPageCaptureWorkers.js";
 /** Capture and normalize one attached page without evaluating page JavaScript. */
 export const capturePage = async (context) => {
     const allowedOrigins = new Set(context.input.allowed_origins);
@@ -59,8 +61,14 @@ const captureAuthorizedPage = async (state) => {
     const accessibility = await accessibilityForFrames(state, frames);
     if (accessibility.total > accessibility.nodes.length)
         state.events.completeness.truncate("accessibility");
-    const scripts = await captureScripts(context, state.events, resourceCapture.items, resources);
-    const workerCapture = await captureWorkers(state, new Set(frames.map((frame) => frame.frame_id)));
+    const scripts = await captureScripts({
+        context,
+        events: state.events,
+        rawResources: resourceCapture.items,
+        resources,
+        frameIds: new Set(frames.map((frame) => frame.frame_id)),
+    });
+    const workerCapture = await captureWorkers({ context, allowedOrigins, limitations, events: state.events }, new Set(frames.map((frame) => frame.frame_id)));
     if (workerCapture.total > workerCapture.items.length)
         state.events.completeness.truncate("workers");
     const storageCapture = await captureStorage(context, frames[0]?.origin ?? new URL(attachedUrl).origin, limitations);
@@ -220,86 +228,6 @@ const accessibilityForFrames = async (state, frames) => {
         events.completeness.truncate("accessibility");
     return capture;
 };
-const captureScripts = async (context, events, rawResources, resources) => {
-    let totalSourceBytes = 0;
-    const drafts = [];
-    for (const script of events.scripts.values()) {
-        let source = sourceExcluded("source capture was not approved");
-        if (context.input.include_script_sources) {
-            if (script.length > context.input.limits.max_script_source_bytes) {
-                source = sourceExcluded("declared script length exceeds per-script limit");
-                events.completeness.truncate("script_sources");
-            }
-            else if (totalSourceBytes + script.length >
-                context.input.limits.max_total_script_source_bytes) {
-                source = sourceExcluded("total script source limit reached");
-                events.completeness.truncate("script_sources");
-            }
-            else {
-                const result = requiredRecord(await context.connection.send("Debugger.getScriptSource", { scriptId: script.scriptId }, context.sessionId, context.signal));
-                const content = stringValue(result.scriptSource) ?? "";
-                const bytes = Buffer.byteLength(content);
-                if (bytes > context.input.limits.max_script_source_bytes ||
-                    totalSourceBytes + bytes >
-                        context.input.limits.max_total_script_source_bytes) {
-                    source = sourceExcluded("actual source exceeds configured byte limits");
-                    events.completeness.truncate("script_sources");
-                }
-                else {
-                    source = sourceResult(content);
-                    totalSourceBytes += bytes;
-                }
-            }
-        }
-        const inventoryScript = {
-            url: script.url,
-            cdp_hash: script.hash,
-            length: script.length,
-            is_module: script.isModule,
-            language: script.language,
-            source_map_url: script.sourceMapUrl,
-        };
-        drafts.push({
-            item: {
-                ...inventoryScript,
-                origin: script.origin,
-                resource_reconciliation: reconcileCapturedWebScript({ ...inventoryScript, rawUrl: script.rawUrl }, rawResources, resources),
-                source,
-            },
-            sourceMapRawUrl: script.sourceMapRawUrl,
-        });
-    }
-    if (!context.input.include_script_sources)
-        events.completeness.exclude("script_sources", "not_approved", events.scripts.size);
-    const keyed = drafts.map((draft) => ({
-        ...draft,
-        base: stableWebScriptKey(draft.item),
-    }));
-    keyed.sort((left, right) => left.base.localeCompare(right.base) ||
-        sourceDigest(left.item.source).localeCompare(sourceDigest(right.item.source)));
-    const totals = new Map();
-    for (const { base } of keyed)
-        totals.set(base, (totals.get(base) ?? 0) + 1);
-    const seen = new Map();
-    const sourceMapRequests = [];
-    const items = keyed.map(({ base, item, sourceMapRawUrl }) => {
-        const occurrence = (seen.get(base) ?? 0) + 1;
-        seen.set(base, occurrence);
-        const scriptKey = totals.get(base) === 1 ? base : `${base}_${String(occurrence)}`;
-        if (item.source_map_url !== null && sourceMapRawUrl !== null)
-            sourceMapRequests.push({
-                scriptKey,
-                declaredUrl: item.source_map_url,
-                fetchUrl: sourceMapRawUrl,
-            });
-        return { script_key: scriptKey, ...item };
-    });
-    return {
-        inventory: { total: events.scripts.size, items },
-        sourceMapRequests,
-    };
-};
-const sourceDigest = (source) => (source.included ? source.artifact.sha256 : source.reason);
 const publicResource = ({ rawUrl: _rawUrl, ...resource }) => resource;
 const deduplicatedAgentHints = (hints) => {
     const seen = new Set();
@@ -311,51 +239,6 @@ const deduplicatedAgentHints = (hints) => {
         return true;
     });
 };
-const captureWorkers = async (state, frameIds) => {
-    const { context, allowedOrigins, limitations, events } = state;
-    const completeness = events.completeness;
-    const result = await optionalCdpCommand({ ...context, sessionId: undefined }, "Target.getTargets", {}, limitations);
-    const items = [];
-    let total = 0;
-    if (result === undefined)
-        completeness.unavailable("workers");
-    for (const target of recordsValue(recordValue(result)?.targetInfos)) {
-        const type = stringValue(target.type) ?? "";
-        const url = allowedSanitizedUrl(target.url, allowedOrigins);
-        const relatedToPage = stringValue(target.openerId) === context.target.id ||
-            (stringValue(target.parentFrameId) !== undefined &&
-                frameIds.has(stringValue(target.parentFrameId) ?? ""));
-        if (!type.includes("worker"))
-            continue;
-        if (!relatedToPage) {
-            completeness.exclude("workers", "out_of_target_scope");
-            continue;
-        }
-        if (url === undefined) {
-            const rawUrl = stringValue(target.url);
-            completeness.exclude("workers", rawUrl === undefined || rawUrl === ""
-                ? "unattributed_origin"
-                : isHttpUrl(rawUrl)
-                    ? "disallowed_origin"
-                    : "unsupported_url");
-            continue;
-        }
-        total += 1;
-        if (items.length >= context.input.limits.max_workers)
-            continue;
-        items.push({
-            target_id: (stringValue(target.targetId) ?? "").slice(0, 256),
-            type: type.slice(0, 100),
-            url: url.url,
-            origin: url.origin,
-            attached: target.attached === true,
-        });
-    }
-    return {
-        total,
-        items,
-    };
-};
 const normalizedTarget = (target, currentUrl, allowedOrigins) => {
     const url = allowedSanitizedUrl(currentUrl, allowedOrigins);
     return {

package/dist/browser/CdpPageCaptureScripts.js

@@ -0,0 +1,97 @@
+import { reconcileCapturedWebScript, stableWebScriptKey, } from "../domain/webInventory.js";
+import { requiredRecord, sourceExcluded, sourceResult, stringValue, } from "./CdpCaptureValues.js";
+export const captureScripts = async (options) => {
+    const { context, events, rawResources, resources, frameIds } = options;
+    const state = {
+        context,
+        events,
+        frameIds,
+        rawResources,
+        resources,
+        totalSourceBytes: 0,
+    };
+    const drafts = [];
+    for (const script of events.scripts.values())
+        drafts.push(await buildScriptDraft(script, state));
+    if (!context.input.include_script_sources)
+        events.completeness.exclude("script_sources", "not_approved", events.scripts.size);
+    return keyAndBuildInventory(drafts, events.scripts.size);
+};
+const buildScriptDraft = async (script, state) => {
+    let source = state
+        .context.input.include_script_sources
+        ? await captureScriptSource(script, state)
+        : sourceExcluded("source capture was not approved");
+    const inventoryScript = {
+        frame_id: state.events.frameForScript(script, state.frameIds),
+        url: script.url,
+        cdp_hash: script.hash,
+        length: script.length,
+        is_module: script.isModule,
+        language: script.language,
+        source_map_url: script.sourceMapUrl,
+    };
+    return {
+        item: {
+            ...inventoryScript,
+            origin: script.origin,
+            resource_reconciliation: reconcileCapturedWebScript({ ...inventoryScript, rawUrl: script.rawUrl }, state.rawResources, state.resources),
+            source,
+        },
+        sourceMapRawUrl: script.sourceMapRawUrl,
+    };
+};
+const captureScriptSource = async (script, state) => {
+    const { context, events } = state;
+    if (script.length > context.input.limits.max_script_source_bytes) {
+        events.completeness.truncate("script_sources");
+        return sourceExcluded("declared script length exceeds per-script limit");
+    }
+    if (state.totalSourceBytes + script.length >
+        context.input.limits.max_total_script_source_bytes) {
+        events.completeness.truncate("script_sources");
+        return sourceExcluded("total script source limit reached");
+    }
+    const result = requiredRecord(await context.connection.send("Debugger.getScriptSource", { scriptId: script.scriptId }, context.sessionId, context.signal));
+    const content = stringValue(result.scriptSource) ?? "";
+    const bytes = Buffer.byteLength(content);
+    if (bytes > context.input.limits.max_script_source_bytes ||
+        state.totalSourceBytes + bytes >
+            context.input.limits.max_total_script_source_bytes) {
+        events.completeness.truncate("script_sources");
+        return sourceExcluded("actual source exceeds configured byte limits");
+    }
+    state.totalSourceBytes += bytes;
+    return sourceResult(content);
+};
+const keyAndBuildInventory = (drafts, scriptCount) => {
+    const keyed = drafts.map((draft) => ({
+        ...draft,
+        base: stableWebScriptKey(draft.item),
+    }));
+    keyed.sort((left, right) => left.base.localeCompare(right.base) ||
+        sourceDigest(left.item.source).localeCompare(sourceDigest(right.item.source)) ||
+        (left.item.frame_id ?? "").localeCompare(right.item.frame_id ?? ""));
+    const totals = new Map();
+    for (const { base } of keyed)
+        totals.set(base, (totals.get(base) ?? 0) + 1);
+    const seen = new Map();
+    const sourceMapRequests = [];
+    const items = keyed.map(({ base, item, sourceMapRawUrl }) => {
+        const occurrence = (seen.get(base) ?? 0) + 1;
+        seen.set(base, occurrence);
+        const scriptKey = totals.get(base) === 1 ? base : `${base}_${String(occurrence)}`;
+        if (item.source_map_url !== null && sourceMapRawUrl !== null)
+            sourceMapRequests.push({
+                scriptKey,
+                declaredUrl: item.source_map_url,
+                fetchUrl: sourceMapRawUrl,
+            });
+        return { script_key: scriptKey, ...item };
+    });
+    return {
+        inventory: { total: scriptCount, items },
+        sourceMapRequests,
+    };
+};
+const sourceDigest = (source) => (source.included ? source.artifact.sha256 : source.reason);

package/dist/browser/CdpPageCaptureWorkers.js

@@ -0,0 +1,46 @@
+import { allowedSanitizedUrl, boundedText, isHttpUrl, recordValue, recordsValue, stringValue, } from "./CdpCaptureValues.js";
+import { optionalCdpCommand } from "./CdpOptionalCommand.js";
+export const captureWorkers = async (input, frameIds) => {
+    const { context, allowedOrigins, limitations, events } = input;
+    const completeness = events.completeness;
+    const result = await optionalCdpCommand({ ...context, sessionId: undefined }, "Target.getTargets", {}, limitations);
+    const items = [];
+    let total = 0;
+    if (result === undefined)
+        completeness.unavailable("workers");
+    for (const target of recordsValue(recordValue(result)?.targetInfos)) {
+        const type = stringValue(target.type) ?? "";
+        const url = allowedSanitizedUrl(target.url, allowedOrigins);
+        const relatedToPage = stringValue(target.openerId) === context.target.id ||
+            (stringValue(target.parentFrameId) !== undefined &&
+                frameIds.has(stringValue(target.parentFrameId) ?? ""));
+        if (!type.includes("worker"))
+            continue;
+        if (!relatedToPage) {
+            completeness.exclude("workers", "out_of_target_scope");
+            continue;
+        }
+        if (url === undefined) {
+            const rawUrl = stringValue(target.url);
+            completeness.exclude("workers", rawUrl === undefined || rawUrl === ""
+                ? "unattributed_origin"
+                : isHttpUrl(rawUrl)
+                    ? "disallowed_origin"
+                    : "unsupported_url");
+            continue;
+        }
+        total += 1;
+        if (items.length >= context.input.limits.max_workers)
+            continue;
+        items.push({
+            target_id: (stringValue(target.targetId) ?? "").slice(0, 256),
+            type: type.slice(0, 100),
+            url: url.url,
+            origin: url.origin,
+            attached: target.attached === true,
+            opener_target_id: boundedText(target.openerId, 256) ?? null,
+            parent_frame_id: boundedText(target.parentFrameId, 256) ?? null,
+        });
+    }
+    return { total, items };
+};

package/dist/browser/CdpWebMcpDiscovery.js

@@ -35,7 +35,13 @@ export const discoverWebMcp = async (context) => {
             return;
         if (ingestFrameScopeEvent(event, frameScope))
             return;
-        ingestWebMcpEvent(event, context.input, frameUrls, tools, completeness);
+        ingestWebMcpEvent({
+            event,
+            input: context.input,
+            frames: frameUrls,
+            tools,
+            completeness,
+        });
     });
     await context.progress?.report({
         phase: "browser_observation",
@@ -53,7 +59,14 @@ export const discoverWebMcp = async (context) => {
             // CDP sends the enable response before the required toolsAdded replay.
             await delayWithCancellation(Math.max(context.input.observation_ms, 25), "discover_webmcp_tools", context.signal);
         await assertStableAuthorizedFrame(context, initialUrl, origins);
-        return result(context, frameTree, tools, completeness, limitations, available);
+        return buildWebMcpResult({
+            context,
+            frameTree,
+            tools,
+            completeness,
+            limitations,
+            available,
+        });
     }
     finally {
         removeListener();
@@ -70,18 +83,27 @@ const ingestFrameScopeEvent = (event, state) => {
     const params = recordValue(event.params);
     if (params === undefined)
         return false;
-    if (event.method === "Page.frameDetached") {
-        const frameId = stringValue(params.frameId);
-        if (frameId === undefined || frameId.length > 256)
-            state.completeness.exclude("webmcp_tools", "invalid_protocol_value");
-        else
-            removeFrame(frameId, state.frames, state.tools);
+    switch (event.method) {
+        case "Page.frameDetached":
+            return handleFrameDetached(params, state);
+        case "Page.frameNavigated":
+            return handleFrameUpdate(recordValue(params.frame), state);
+        case "Page.navigatedWithinDocument":
+            return handleFrameUpdate(params, state);
+        default:
+            return false;
+    }
+};
+const handleFrameDetached = (params, state) => {
+    const frameId = stringValue(params.frameId);
+    if (frameId === undefined || frameId.length > 256) {
+        state.completeness.exclude("webmcp_tools", "invalid_protocol_value");
         return true;
     }
-    const frame = event.method === "Page.frameNavigated" ? recordValue(params.frame) : params;
-    if (event.method !== "Page.frameNavigated" &&
-        event.method !== "Page.navigatedWithinDocument")
-        return false;
+    removeFrame(frameId, state.frames, state.tools);
+    return true;
+};
+const handleFrameUpdate = (frame, state) => {
     const frameId = stringValue(frame?.id) ?? stringValue(frame?.frameId);
     if (frameId === undefined || frameId.length > 256) {
         state.completeness.exclude("webmcp_tools", "invalid_protocol_value");
@@ -128,7 +150,8 @@ const assertStableAuthorizedFrame = async (context, initialUrl, origins) => {
     if (finalUrl !== initialUrl)
         throw new BrowserObservationError("inspect_web_page", "target_changed");
 };
-const ingestWebMcpEvent = (event, input, frames, tools, completeness) => {
+const ingestWebMcpEvent = (options) => {
+    const { event, input, frames, tools, completeness } = options;
     const params = recordValue(event.params);
     if (params === undefined)
         return;
@@ -214,7 +237,8 @@ const registrationSource = (stack, allowedOrigins) => {
             column: integerOrNull(frame.columnNumber),
         };
 };
-const result = (context, frameTree, tools, completeness, limitations, available) => {
+const buildWebMcpResult = (options) => {
+    const { context, frameTree, tools, completeness, limitations, available } = options;
     const targetUrl = mainFrameUrl(frameTree) ?? context.target.url;
     const sanitized = allowedSanitizedUrl(targetUrl, new Set(context.input.allowed_origins));
     return {

package/dist/browser/PngVisualDiff.js

@@ -128,7 +128,13 @@ const unfilter = (raw, width, height, channels) => {
             const upperLeft = row > 0 && column >= channels
                 ? (decoded[outputOffset + column - rowBytes - channels] ?? 0)
                 : 0;
-            decoded[outputOffset + column] = applyFilter(filter, source, left, above, upperLeft);
+            decoded[outputOffset + column] = applyFilter({
+                filter,
+                source,
+                left,
+                above,
+                upperLeft,
+            });
         }
     }
     if (channels === 4)
@@ -142,7 +148,8 @@ const unfilter = (raw, width, height, channels) => {
     }
     return rgba;
 };
-const applyFilter = (filter, source, left, above, upperLeft) => {
+const applyFilter = (options) => {
+    const { filter, source, left, above, upperLeft } = options;
     switch (filter) {
         case 0:
             return source;

package/dist/catalogIdentity.js

@@ -7,8 +7,10 @@ import { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
 export { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
 const toolCatalog = TOOL_CONTRACTS.map((contract) => ({
     name: contract.name,
+    title: contract.title,
     surface: contract.kind,
     description: contract.description,
+    effects: { ...contract.effects },
     annotations: contract.annotations,
     input_schema: z.toJSONSchema(contract.inputSchema, {
         unrepresentable: "any",
@@ -51,6 +53,10 @@ const resourceTemplateCatalog = [
         name: "investigation-workspace-revision",
         uri_template: "rea://workspace/{workspaceId}/revision/{revision}",
     },
+    {
+        name: "reconstruction-coverage-revision",
+        uri_template: "rea://reconstruction-coverage/{workspaceId}/revision/{revision}",
+    },
 ];
 const digest = (value) => {
     const encoded = canonicalize(value);
@@ -79,9 +85,10 @@ export const CATALOG_IDENTITY = {
             resource_templates: resourceTemplateCatalog,
         }),
     },
-    tools: toolCatalog.map(({ name, surface, annotations }) => ({
+    tools: toolCatalog.map(({ name, surface, effects, annotations }) => ({
         name,
         surface,
+        effects,
         annotations: {
             read_only: annotations.readOnlyHint ?? false,
             destructive: annotations.destructiveHint ?? false,

package/dist/cli/artifactCommands.js

@@ -0,0 +1,82 @@
+import { z } from "incur";
+import { runProviderAnalysis } from "../application/DirectAnalysis.js";
+import { logCliCommand } from "../cliLogging.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+export const registerArtifactCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inventoryArtifact, {
+        description: "Build a bounded deterministic artifact graph",
+        args: z.object({
+            path: z.string().describe("Application or package path"),
+        }),
+        options: z.object({
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .default(0)
+                .describe("Zero-based offset for graph nodes, occurrences, and edges"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .default(100)
+                .describe("Maximum nodes, occurrences, and edges per result section"),
+            integrityPolicy: z
+                .enum(["fail", "record-and-continue"])
+                .default("fail")
+                .describe("Behavior when declared artifact integrity does not match"),
+            integrityContinueApproved: z
+                .boolean()
+                .default(false)
+                .describe("Approve continuing after recorded integrity mismatches"),
+            maxIntegrityMismatches: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(10)
+                .describe("Maximum integrity mismatches to record before stopping"),
+            nativeMountApproved: z
+                .boolean()
+                .default(false)
+                .describe("Approve read-only native mounting when required"),
+        }),
+        alias: {
+            integrityPolicy: "integrity-policy",
+            integrityContinueApproved: "integrity-continue-approved",
+            maxIntegrityMismatches: "max-integrity-mismatches",
+            nativeMountApproved: "native-mount-approved",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "inventory-artifact", () => runProviderAnalysis(args.path, "inventory_artifact", {
+            node_offset: options.offset,
+            node_limit: options.limit,
+            occurrence_offset: options.offset,
+            occurrence_limit: options.limit,
+            edge_offset: options.offset,
+            edge_limit: options.limit,
+            integrity_policy: options.integrityPolicy,
+            integrity_continue_approved: options.integrityContinueApproved,
+            max_integrity_mismatches: options.maxIntegrityMismatches,
+            native_mount_approved: options.nativeMountApproved,
+        }, logger)),
+    });
+    cli.command(CLI_COMMANDS.extractArtifact, {
+        description: "Extract explicitly selected artifact occurrences safely",
+        args: z.object({
+            path: z.string().describe("Application or package path"),
+            outputRoot: z.string().describe("Absent absolute output root"),
+            occurrenceIds: z
+                .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
+                .min(1)
+                .max(500)
+                .describe("Exact artifact occurrence IDs selected for extraction"),
+        }),
+        alias: { outputRoot: "output-root", occurrenceIds: "occurrence-ids" },
+        run: ({ args }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
+            approved: true,
+            output_root: args.outputRoot,
+            occurrence_ids: args.occurrenceIds,
+        }, logger)),
+    });
+};