rea-agents 2.4.0 → 3.0.0

package/dist/browser/V8InspectorProvider.js

@@ -0,0 +1,267 @@
+import { javascriptRuntimeObservationSchema, javascriptRuntimeTargetListSchema, } from "../domain/javascriptRuntimeObservation.js";
+import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { boundedText, numberValue, recordValue, stringValue, delayWithCancellation, } from "./CdpCaptureValues.js";
+import { CdpConnection } from "./CdpConnection.js";
+import { authorizeRuntimeLocation, canonicalRuntimeRoots, } from "./JavaScriptRuntimeScope.js";
+import { createInspectorExclusionCounts, describeInspectorTargetLimitations, finalizeInspectorCapture, } from "./V8InspectorCaptureProjection.js";
+import { discoverV8Inspector, } from "./V8InspectorEndpoint.js";
+/** Public identity committed by passive V8 Inspector observations. */
+export const V8_INSPECTOR_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-v8-inspector",
+    name: "REA passive Node/Electron V8 Inspector provider",
+    version: "1",
+});
+/** Attach-only provider; sends only Runtime.enable and Debugger.enable. */
+export class V8InspectorProvider {
+    identity() {
+        return V8_INSPECTOR_PROVIDER_IDENTITY;
+    }
+    async listTargets(input, options = {}) {
+        try {
+            const roots = await canonicalRuntimeRoots(input.allowed_file_roots);
+            const discovery = await discoverV8Inspector(input.inspector_endpoint, "list_javascript_runtime_targets", options.signal);
+            const allowed = [];
+            const excluded = createInspectorExclusionCounts();
+            for (const target of discovery.targets) {
+                const decision = await authorizeRuntimeLocation(target.url, roots, input.allowed_origins);
+                if (!decision.allowed) {
+                    excluded[decision.reason] += 1;
+                    continue;
+                }
+                if (decision.location.kind === "builtin") {
+                    excluded.unsupported_location += 1;
+                    continue;
+                }
+                allowed.push({ ...target, location: decision.location });
+            }
+            allowed.sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+            const items = allowed
+                .slice(input.offset, input.offset + input.limit)
+                .map(projectTarget);
+            const nextOffset = input.offset + items.length;
+            return ok(javascriptRuntimeTargetListSchema.parse({
+                schema_version: 1,
+                runtime: discovery.runtime,
+                targets: {
+                    items,
+                    offset: input.offset,
+                    limit: input.limit,
+                    total: allowed.length,
+                    next_offset: nextOffset < allowed.length ? nextOffset : null,
+                    has_more: nextOffset < allowed.length,
+                },
+                excluded: { ...excluded, unconnectable: 0 },
+                limitations: describeInspectorTargetLimitations(),
+            }));
+        }
+        catch (cause) {
+            return err(providerError(cause, "list_javascript_runtime_targets"));
+        }
+    }
+    async observe(input, options = {}) {
+        let connection;
+        try {
+            const roots = await canonicalRuntimeRoots(input.allowed_file_roots);
+            const discovery = await discoverV8Inspector(input.inspector_endpoint, "observe_javascript_runtime", options.signal);
+            const target = await authorizedTarget(discovery.targets, input, roots);
+            assertRuntimeKind(target, input.runtime_kind);
+            connection = await CdpConnection.connect(target.webSocketUrl, "observe_javascript_runtime", options.signal);
+            const state = emptyCaptureState();
+            const removeListener = connection.onEvent((event) => ingestEvent(event, input, state));
+            try {
+                await connection.send("Runtime.enable", {}, undefined, options.signal);
+                await connection.send("Debugger.enable", {}, undefined, options.signal);
+                await waitForCapture(connection, input.observation_ms, options.signal);
+            }
+            finally {
+                removeListener();
+            }
+            const result = await finalizeInspectorCapture({
+                input,
+                runtime: discovery.runtime,
+                target,
+                roots,
+                state,
+            });
+            return ok(javascriptRuntimeObservationSchema.parse(result));
+        }
+        catch (cause) {
+            return err(providerError(cause, "observe_javascript_runtime"));
+        }
+        finally {
+            await connection?.close();
+        }
+    }
+}
+const projectTarget = (target) => ({
+    target_id: target.id,
+    protocol_type: target.type,
+    attached: target.attached,
+    location: target.location,
+});
+const authorizedTarget = async (targets, input, roots) => {
+    const target = targets.find(({ id }) => id === input.target_id);
+    if (target === undefined)
+        throw new BrowserObservationError("observe_javascript_runtime", "target_not_found");
+    const decision = await authorizeRuntimeLocation(target.url, roots, input.allowed_origins);
+    if (target.attached ||
+        !decision.allowed ||
+        decision.location.kind === "builtin")
+        throw new BrowserObservationError("observe_javascript_runtime", "target_not_allowed");
+    return { ...target, location: decision.location };
+};
+const assertRuntimeKind = (target, kind) => {
+    const accepted = kind === "electron-preload" || kind === "electron-renderer"
+        ? target.type === "page"
+        : target.type === "node";
+    if (!accepted)
+        throw new BrowserObservationError("observe_javascript_runtime", "target_not_allowed");
+};
+const emptyCaptureState = () => ({
+    scripts: [],
+    contexts: new Map(),
+    eventsObserved: 0,
+    eventsRetained: 0,
+    eventsDropped: 0,
+    metadataBytes: 0,
+    scriptsObserved: 0,
+    invalidScripts: 0,
+    truncated: false,
+    truncationReasons: new Set(),
+});
+const ingestEvent = (event, input, state) => {
+    if (event.method !== "Debugger.scriptParsed" &&
+        event.method !== "Debugger.scriptFailedToParse" &&
+        event.method !== "Runtime.executionContextCreated" &&
+        event.method !== "Runtime.executionContextDestroyed" &&
+        event.method !== "Runtime.executionContextsCleared")
+        return;
+    state.eventsObserved += 1;
+    if (state.eventsObserved > input.limits.max_events) {
+        drop(state, "max_events");
+        return;
+    }
+    if (event.method === "Debugger.scriptParsed") {
+        ingestScript(event, input, state);
+        return;
+    }
+    if (event.method === "Debugger.scriptFailedToParse") {
+        state.invalidScripts += 1;
+        retainEvent(state, 0, input);
+        return;
+    }
+    ingestContext(event, input, state);
+};
+const ingestScript = (event, input, state) => {
+    state.scriptsObserved += 1;
+    const value = recordValue(event.params);
+    const rawUrl = stringValue(value?.url);
+    if (rawUrl === undefined ||
+        rawUrl === "" ||
+        Buffer.byteLength(rawUrl) > input.limits.max_location_bytes) {
+        state.invalidScripts += 1;
+        retainEvent(state, 0, input);
+        return;
+    }
+    if (state.scripts.length >= input.limits.max_scripts) {
+        drop(state, "max_scripts");
+        return;
+    }
+    const draft = {
+        rawUrl,
+        executionContextKey: contextKey(value?.executionContextId),
+        cdpHash: boundedText(value?.hash, 512),
+        length: nonnegativeInteger(value?.length),
+        isModule: value?.isModule === true,
+    };
+    const bytes = metadataBytes(draft);
+    if (!retainEvent(state, bytes, input))
+        return;
+    state.scripts.push(draft);
+};
+const ingestContext = (event, input, state) => {
+    if (event.method === "Runtime.executionContextsCleared") {
+        for (const context of state.contexts.values())
+            context.state = "cleared";
+        retainEvent(state, 0, input);
+        return;
+    }
+    const parameters = recordValue(event.params);
+    const runtimeContext = event.method === "Runtime.executionContextCreated"
+        ? recordValue(parameters?.context)
+        : parameters;
+    const key = contextKey(event.method === "Runtime.executionContextCreated"
+        ? runtimeContext?.id
+        : runtimeContext?.executionContextId);
+    if (key === null) {
+        retainEvent(state, 0, input);
+        return;
+    }
+    if (state.contexts.size >= input.limits.max_execution_contexts &&
+        !state.contexts.has(key)) {
+        drop(state, "max_execution_contexts");
+        return;
+    }
+    const origin = event.method === "Runtime.executionContextCreated"
+        ? boundedText(runtimeContext?.origin, 4_096)
+        : null;
+    const draft = {
+        contextKey: key,
+        state: event.method === "Runtime.executionContextCreated"
+            ? "created"
+            : "destroyed",
+        origin: origin !== null && input.allowed_origins.includes(origin) ? origin : null,
+    };
+    const bytes = metadataBytes(draft);
+    if (!retainEvent(state, bytes, input))
+        return;
+    state.contexts.set(key, draft);
+};
+const retainEvent = (state, bytes, input) => {
+    if (state.metadataBytes + bytes > input.limits.max_total_metadata_bytes) {
+        drop(state, "max_total_metadata_bytes");
+        return false;
+    }
+    state.metadataBytes += bytes;
+    state.eventsRetained += 1;
+    return true;
+};
+const drop = (state, reason) => {
+    state.eventsDropped += 1;
+    state.truncated = true;
+    state.truncationReasons.add(reason);
+};
+const waitForCapture = async (connection, observationMs, signal) => {
+    let removeDisconnect = () => undefined;
+    const disconnected = new Promise((_resolve, reject) => {
+        removeDisconnect = connection.onDisconnect(() => reject(new BrowserObservationError("observe_javascript_runtime", "disconnected")));
+    });
+    try {
+        await Promise.race([
+            delayWithCancellation(observationMs, "observe_javascript_runtime", signal),
+            disconnected,
+        ]);
+    }
+    finally {
+        removeDisconnect();
+    }
+};
+const metadataBytes = (value) => Buffer.byteLength(JSON.stringify(value));
+const nonnegativeInteger = (value) => {
+    const parsed = numberValue(value);
+    return parsed === undefined ? 0 : Math.max(0, Math.trunc(parsed));
+};
+const contextKey = (value) => {
+    const identifier = numberValue(value);
+    return identifier !== undefined && Number.isSafeInteger(identifier)
+        ? String(identifier)
+        : null;
+};
+const providerError = (cause, operation) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    return new ProviderAdapterError(V8_INSPECTOR_PROVIDER_IDENTITY.id, operation, {
+        cause,
+    });
+};

package/dist/catalogIdentity.js

@@ -29,7 +29,7 @@ const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
 /** Canonical fixed resources exposed by every target-free MCP session. */
 export const MCP_RESOURCE_CATALOG = [
     { name: "server-identity", uri: "rea://server/identity" },
-    { name: "active-residual-unknowns", uri: "rea://unknowns/active" },
+    { name: "analysis-snapshot", uri: "rea://snapshot/current" },
 ];
 /** Canonical resource templates exposed by every target-free MCP session. */
 export const MCP_RESOURCE_TEMPLATE_CATALOG = [
@@ -40,8 +40,8 @@ export const MCP_RESOURCE_TEMPLATE_CATALOG = [
     },
     { name: "residual-unknown", uri_template: "rea://unknown/{unknownId}" },
     {
-        name: "analysis-snapshot",
-        uri_template: "rea://snapshot/{snapshotDigest}",
+        name: "evidence-bundle",
+        uri_template: "rea://evidence-bundle/{bundleDigest}",
     },
     {
         name: "artifact-page",
@@ -59,6 +59,14 @@ export const MCP_RESOURCE_TEMPLATE_CATALOG = [
         name: "reconstruction-coverage-revision",
         uri_template: "rea://reconstruction-coverage/{workspaceId}/revision/{revision}",
     },
+    {
+        name: "reconstruction-obligation-ledger-page",
+        uri_template: "rea://evidence/{evidenceId}/reconstruction-obligation-ledger",
+    },
+    {
+        name: "reconstruction-readiness-report",
+        uri_template: "rea://evidence/{evidenceId}/reconstruction-readiness-report",
+    },
     {
         name: "javascript-application-graph-page",
         uri_template: "rea://evidence/{evidenceId}/application-graph/{collection}/offset/{offset}/limit/{limit}",

package/dist/cli/artifactCommands.js

@@ -3,6 +3,11 @@ import { runProviderAnalysis } from "../application/DirectAnalysis.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 export const registerArtifactCommands = (cli, logger) => {
+    registerInventoryCommand(cli, logger);
+    registerInspectionCommand(cli, logger);
+    registerExtractionCommand(cli, logger);
+};
+const registerInventoryCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.inventoryArtifact, {
         description: "Build a bounded deterministic artifact graph",
         args: z.object({
@@ -61,22 +66,58 @@ export const registerArtifactCommands = (cli, logger) => {
             native_mount_approved: options.nativeMountApproved,
         }, logger)),
     });
+};
+const registerExtractionCommand = (cli, 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"),
+        }),
+        options: z.object({
             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", {
+        alias: { occurrenceIds: "occurrence-ids" },
+        run: ({ args, options }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
             approved: true,
             output_root: args.outputRoot,
-            occurrence_ids: args.occurrenceIds,
+            occurrence_ids: options.occurrenceIds,
+        }, logger)),
+    });
+};
+const registerInspectionCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectArtifact, {
+        description: "Inspect one artifact with bounded observations and explicit next probes",
+        args: z.object({
+            path: z.string().describe("Application or package path"),
+        }),
+        options: z.object({
+            maxObservations: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .default(100)
+                .describe("Maximum retained observations"),
+            maxRelationships: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .default(100)
+                .describe("Maximum retained derived relationships"),
+        }),
+        alias: {
+            maxObservations: "max-observations",
+            maxRelationships: "max-relationships",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "inspect-artifact", () => runProviderAnalysis(args.path, "inspect_artifact", {
+            max_observations: options.maxObservations,
+            max_relationships: options.maxRelationships,
         }, logger)),
     });
 };

package/dist/cli/coreAnalysisCommands.js

@@ -9,6 +9,8 @@ import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnal
 export const registerCoreAnalysisCommands = (cli, logger) => {
     registerCoreCommands(cli, logger);
     registerFunctionCommand(cli, logger);
+    registerNativeApiCommand(cli, logger);
+    registerInstructionsCommand(cli, logger);
     registerSearchCommand(cli, logger);
     registerXrefsCommand(cli, logger);
     registerTraceCommand(cli, logger);
@@ -212,6 +214,82 @@ const registerFunctionCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider))),
     });
 };
+const registerNativeApiCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectNativeApi, {
+        description: "Reconstruct one native function API boundary with evidence",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure name or address"),
+        }),
+        options: z.object({
+            maxPseudocodeChars: z
+                .number()
+                .int()
+                .min(1)
+                .max(100_000)
+                .default(20_000)
+                .describe("Maximum pseudocode characters to inspect"),
+            maxInstructions: z
+                .number()
+                .int()
+                .min(1)
+                .max(5_000)
+                .default(500)
+                .describe("Maximum assembly instructions to inspect"),
+            snapshot: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Load and update a local analysis snapshot"),
+            provider: providerSelectionOption,
+        }),
+        alias: {
+            maxPseudocodeChars: "max-pseudocode-chars",
+            maxInstructions: "max-instructions",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "inspect-native-api", () => runDirectAnalysis(args.path, "inspect_native_api", {
+            procedure: args.address,
+            max_pseudocode_chars: options.maxPseudocodeChars,
+            max_instructions: options.maxInstructions,
+        }, directAnalysisOptions(logger, options.snapshot, options.provider))),
+    });
+};
+const registerInstructionsCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.instructions, {
+        description: "Read one bounded raw-instruction window without decompiling",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure name or address"),
+        }),
+        options: z.object({
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .max(100_000)
+                .default(0)
+                .describe("Zero-based instruction offset"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .default(64)
+                .describe("Maximum raw instructions to return"),
+            snapshot: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Load and update a local analysis snapshot"),
+            provider: providerSelectionOption,
+        }),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.instructions, () => runDirectAnalysis(args.path, "read_function_instructions", {
+            procedure: args.address,
+            offset: options.offset,
+            limit: options.limit,
+        }, directAnalysisOptions(logger, options.snapshot, options.provider))),
+    });
+};
 const registerSearchCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.search, {
         description: "Search bounded analyzed strings or procedure names",

package/dist/cli.js

@@ -13,7 +13,9 @@ import { registerProcessCommands } from "./cliProcessCommands.js";
 import { registerPolicyCommands } from "./cliPolicyCommands.js";
 import { registerBrowserCommands } from "./cliBrowserCommands.js";
 import { registerAdvancedBrowserCommands } from "./cliBrowserAdvancedCommands.js";
+import { registerBrowserScenarioCommands } from "./cliBrowserScenarioCommands.js";
 import { registerElectronCommands } from "./cliElectronCommands.js";
+import { registerJavaScriptRuntimeObservationCommands } from "./cliJavaScriptRuntimeCommands.js";
 import { registerApplicationCommands } from "./cliApplicationCommands.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
@@ -52,7 +54,9 @@ export const createCli = () => {
     registerPolicyCommands(cli, logger);
     registerBrowserCommands(cli, logger);
     registerAdvancedBrowserCommands(cli, logger);
+    registerBrowserScenarioCommands(cli, logger);
     registerElectronCommands(cli, logger);
+    registerJavaScriptRuntimeObservationCommands(cli, logger);
     registerApplicationCommands(cli, logger);
     return cli;
 };

package/dist/cliApplicationCommands.js

@@ -1,11 +1,13 @@
 import { Cli, z } from "incur";
-import { compareApplicationVersionsEvidenceValidated, compareJavaScriptExportShapesEvidenceValidated, traceApplicationFeatureEvidenceValidated, } from "./application/JavaScriptApplicationWorkflowService.js";
+import { compareApplicationVersionsEvidenceValidated, compareJavaScriptExportShapesEvidenceValidated, compareSourceToBundleEvidenceValidated, traceApplicationFeatureEvidenceValidated, } from "./application/JavaScriptApplicationWorkflowService.js";
 import { traceJavaScriptSemanticsEvidenceValidated } from "./application/JavaScriptSemanticTraceService.js";
-import { resolveCompareApplicationVersionsRequest, resolveCompareJavaScriptExportShapesRequest, resolveTraceApplicationFeatureRequest, resolveTraceJavaScriptSemanticsRequest, } from "./application/ApplicationWorkflowEvidenceResolver.js";
+import { resolveCompareApplicationVersionsRequest, resolveCompareJavaScriptExportShapesRequest, resolveCompareSourceToBundleRequest, resolveTraceApplicationFeatureRequest, resolveTraceJavaScriptSemanticsRequest, } from "./application/ApplicationWorkflowEvidenceResolver.js";
 import { readEvidenceBundle } from "./application/EvidenceBundleFiles.js";
 import { runControlledReplay } from "./application/JavaScriptReplayService.js";
 import { executeNodeCharacterization, prepareNodeCharacterization, } from "./application/NodeRuntimeCharacterizationService.js";
 import { commitReconstructionCoverage, queryReconstructionCoverage, reconstructionCoverageCommitInputSchema, reconstructionCoverageQueryInputSchema, } from "./application/ReconstructionCoverageService.js";
+import { buildReconstructionObligationLedgerEvidenceValidated, resolveReconstructionObligationLedgerRequest, } from "./application/ReconstructionObligationLedgerService.js";
+import { evaluateReconstructionReadinessValidated, resolveReconstructionReadinessRequest, } from "./application/ReconstructionReadinessService.js";
 import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, } from "./application/DeferredFileAuthorization.js";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
@@ -41,6 +43,14 @@ export const registerApplicationCommands = (cli, logger) => {
         resolveInput: resolveCompareApplicationVersionsRequest,
         workflow: compareApplicationVersionsEvidenceValidated,
     });
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.compareSourceToBundle,
+        description: "Compare committed historical source with authenticated application Evidence",
+        resolveInput: resolveCompareSourceToBundleRequest,
+        workflow: compareSourceToBundleEvidenceValidated,
+    });
     registerJsonCommand({
         cli,
         logger,
@@ -87,8 +97,26 @@ export const registerApplicationCommands = (cli, logger) => {
         description: "Execute one separately approved exact Node/JavaScript characterization",
         workflow: (config, authority, input) => executeNodeCharacterization(replayDependencies(config, authority), input),
     });
+    registerObligationLedgerCommand(cli, logger);
+    registerReadinessCommand(cli, logger);
     registerCoverageCommands(cli, logger);
 };
+const registerObligationLedgerCommand = (cli, logger) => registerJsonCommand({
+    cli,
+    logger,
+    name: CLI_COMMANDS.buildReconstructionObligationLedger,
+    description: "Generate a deterministic Evidence-backed reconstruction obligation ledger page",
+    resolveInput: resolveReconstructionObligationLedgerRequest,
+    workflow: buildReconstructionObligationLedgerEvidenceValidated,
+});
+const registerReadinessCommand = (cli, logger) => registerJsonCommand({
+    cli,
+    logger,
+    name: CLI_COMMANDS.evaluateReconstructionReadiness,
+    description: "Evaluate a complete Evidence-backed reconstruction readiness journey",
+    resolveInput: resolveReconstructionReadinessRequest,
+    workflow: evaluateReconstructionReadinessValidated,
+});
 const registerAuthorizedJsonCommand = ({ cli, logger, name, description, workflow, }) => {
     cli.command(name, {
         description,

package/dist/cliBrowserAdvancedCommands.js

@@ -5,7 +5,7 @@ import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
 import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
-import { compareWebCapturesInputSchema } from "./domain/webCaptureDiff.js";
+import { browserCaptureComparisonInputSchema } from "./domain/browserCaptureComparison.js";
 import { discoverWebMcpToolsInputSchema } from "./domain/webMcpDiscovery.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, } from "./domain/webScreenshot.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
@@ -92,7 +92,7 @@ const registerWebMcp = (cli, logger) => {
 };
 const registerCaptureDiff = (cli, logger) => {
     cli.command(CLI_COMMANDS.compareWebCaptures, {
-        description: "Compare two normalized web capture JSON values",
+        description: "Compare two normalized passive captures or recorded browser scenarios",
         args: z.object({
             beforeJson: z.string().describe("Earlier normalized web capture JSON"),
             afterJson: z.string().describe("Later normalized web capture JSON"),
@@ -105,15 +105,27 @@ const registerCaptureDiff = (cli, logger) => {
                 .max(20_000)
                 .default(2_000)
                 .describe("Maximum normalized changes to return"),
+            normalizationJson: z
+                .string()
+                .default('{"rules":[]}')
+                .describe("Recorded literal normalization policy for browser scenarios"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "compare-web-captures", async () => {
             const before = parseJson(args.beforeJson);
             const after = parseJson(args.afterJson);
-            const parsed = compareWebCapturesInputSchema.safeParse({
-                before,
-                after,
+            const scenarioComparison = browserCaptureComparisonInputSchema.safeParse({
+                before_scenario: before,
+                after_scenario: after,
+                normalization: parseJson(options.normalizationJson),
                 max_changes: options.maxChanges,
             });
+            const parsed = scenarioComparison.success
+                ? scenarioComparison
+                : browserCaptureComparisonInputSchema.safeParse({
+                    before,
+                    after,
+                    max_changes: options.maxChanges,
+                });
             if (!parsed.success)
                 return inputError("compare_web_captures");
             const result = await compareWebCaptureEvidence(new CdpBrowserProvider(), parsed.data);

package/dist/cliBrowserCommands.js

@@ -93,6 +93,7 @@ const registerPageInspection = (cli, logger) => {
                 websocket_shape_approved: options.websocketShapeApproved,
                 include_script_sources: options.includeScriptSources,
                 include_storage_keys: options.includeStorageKeys,
+                include_storage_fingerprints: options.includeStorageFingerprints,
                 limits: {
                     max_frames: options.maxFrames,
                     max_dom_nodes: options.maxDomNodes,

package/dist/cliBrowserScenarioCommands.js

@@ -0,0 +1,43 @@
+import { Cli } from "incur";
+import { z } from "zod";
+import { captureBrowserScenario } from "./application/BrowserScenarioCaptureService.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { PlaywrightBrowserScenarioProvider } from "./browser/PlaywrightBrowserScenarioProvider.js";
+import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { parseCliJsonInput } from "./cliJsonInput.js";
+import { logCliCommand } from "./cliLogging.js";
+import { parseConfig } from "./config.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { browserScenarioSchema } from "./domain/browserScenario.js";
+const OPERATION = "capture_browser_scenario";
+/** Register the one-shot controlled browser scenario command. */
+export const registerBrowserScenarioCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.captureBrowserScenario, {
+        description: "Run one approved, bounded Playwright browser scenario and return Evidence",
+        args: z.object({
+            inputJson: z
+                .string()
+                .describe("Inline browser scenario JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.captureBrowserScenario, async () => {
+            const input = await parseCliJsonInput(args.inputJson, OPERATION);
+            if (!input.ok)
+                return input.error;
+            const scenario = browserScenarioSchema.safeParse(input.value);
+            if (!scenario.success)
+                return cliError(new AnalysisInputError(OPERATION));
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return cliError(config.error);
+            const authority = await loadConfiguredPermissionAuthority(config.value);
+            if (!authority.ok)
+                return cliError(authority.error);
+            const result = await captureBrowserScenario(new PlaywrightBrowserScenarioProvider(), authority.value, scenario.data);
+            return result.ok ? result.value : cliError(result.error);
+        }),
+    });
+};
+const cliError = (error) => ({
+    error: "Browser scenario capture failed",
+    ...projectAnalysisError(error),
+});