rea-agents 1.7.0 → 2.1.0

package/dist/cliApplicationCommands.js

@@ -0,0 +1,176 @@
+import { Cli, z } from "incur";
+import { compareApplicationVersionsEvidence, traceApplicationFeatureEvidence, } from "./application/JavaScriptApplicationWorkflowService.js";
+import { runControlledReplay } from "./application/JavaScriptReplayService.js";
+import { executeNodeCharacterization, prepareNodeCharacterization, } from "./application/NodeRuntimeCharacterizationService.js";
+import { commitReconstructionCoverage, queryReconstructionCoverage, reconstructionCoverageCommitInputSchema, reconstructionCoverageQueryInputSchema, } from "./application/ReconstructionCoverageService.js";
+import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, } from "./application/DeferredFileAuthorization.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { parseCliJsonInput } from "./cliJsonInput.js";
+import { logCliCommand } from "./cliLogging.js";
+import { AnalysisInputError, projectAnalysisError, } from "./domain/errors.js";
+import { parseConfig } from "./config.js";
+import { LinuxJavaScriptReplayRunner } from "./replay/LinuxJavaScriptReplayRunner.js";
+import { SystemJavaScriptReplayHost } from "./replay/SystemJavaScriptReplayHost.js";
+/** Register CLI equivalents of provider-neutral application graph workflows. */
+export const registerApplicationCommands = (cli, logger) => {
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.traceApplicationFeature,
+        description: "Trace a typed seed through authenticated application Evidence JSON",
+        workflow: traceApplicationFeatureEvidence,
+    });
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.compareApplicationVersions,
+        description: "Compare two authenticated JavaScript Application Graph versions",
+        workflow: compareApplicationVersionsEvidence,
+    });
+    cli.command(CLI_COMMANDS.runControlledReplay, {
+        description: "Plan or execute an approved extracted-module replay in the Linux sandbox",
+        args: z.object({
+            inputJson: z.string().describe("Inline replay JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.runControlledReplay, async () => {
+            const input = await parseCliJsonInput(args.inputJson, CLI_COMMANDS.runControlledReplay);
+            if (!input.ok)
+                return input.error;
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return projectAnalysisError(config.error);
+            const authority = await loadConfiguredPermissionAuthority(config.value);
+            if (!authority.ok)
+                return projectAnalysisError(authority.error);
+            const result = await runControlledReplay({
+                policy: config.value.javascriptReplayPolicy,
+                host: new SystemJavaScriptReplayHost(),
+                runner: new LinuxJavaScriptReplayRunner(),
+                authority: authority.value,
+            }, input.value);
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        }),
+    });
+    registerAuthorizedJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.prepareNodeCharacterization,
+        description: "Prepare one exact Node/JavaScript characterization without execution",
+        workflow: (config, authority, input) => prepareNodeCharacterization(replayDependencies(config, authority), input),
+    });
+    registerAuthorizedJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.executeNodeCharacterization,
+        description: "Execute one separately approved exact Node/JavaScript characterization",
+        workflow: (config, authority, input) => executeNodeCharacterization(replayDependencies(config, authority), input),
+    });
+    registerCoverageCommands(cli, logger);
+};
+const registerAuthorizedJsonCommand = ({ cli, logger, name, description, workflow, }) => {
+    cli.command(name, {
+        description,
+        args: z.object({
+            inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, name, async () => {
+            const input = await parseCliJsonInput(args.inputJson, name);
+            if (!input.ok)
+                return input.error;
+            const configured = await configuredAuthority();
+            if (!configured.ok)
+                return configured.error;
+            const result = await workflow(configured.config, configured.authority, input.value);
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        }),
+    });
+};
+const registerCoverageCommands = (cli, logger) => {
+    registerAuthorizedJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.commitReconstructionCoverage,
+        description: "Commit one canonical reconstruction coverage workspace revision",
+        workflow: async (config, authority, input) => {
+            const parsed = reconstructionCoverageCommitInputSchema.safeParse(input);
+            if (!parsed.success)
+                return {
+                    ok: false,
+                    error: new AnalysisInputError(CLI_COMMANDS.commitReconstructionCoverage, { cause: parsed.error }),
+                };
+            const authorization = await authorizeFileReadWithDeferredWrite(authority, {
+                path: parsed.data.workspace_path,
+                readCapability: "investigation_workspace_read",
+                writeCapability: "investigation_workspace_write",
+                operation: CLI_COMMANDS.commitReconstructionCoverage,
+            });
+            if (!authorization.ok)
+                return authorization;
+            const write = await authorization.value.authorizeWrite();
+            if (!write.ok)
+                return write;
+            return commitReconstructionCoverage(parsed.data, config.evidenceFilePolicy);
+        },
+    });
+    registerAuthorizedJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.queryReconstructionCoverage,
+        description: "Evaluate one fail-closed reconstruction coverage boundary",
+        workflow: async (config, authority, input) => {
+            const parsed = reconstructionCoverageQueryInputSchema.safeParse(input);
+            if (!parsed.success)
+                return {
+                    ok: false,
+                    error: new AnalysisInputError(CLI_COMMANDS.queryReconstructionCoverage, { cause: parsed.error }),
+                };
+            const authorized = await authorizeRootPermission(authority, {
+                capability: "investigation_workspace_read",
+                roots: [parsed.data.workspace_path],
+                access: "read",
+                operation: CLI_COMMANDS.queryReconstructionCoverage,
+            });
+            if (!authorized.ok)
+                return authorized;
+            return queryReconstructionCoverage(parsed.data, config.evidenceFilePolicy, Date.now());
+        },
+    });
+};
+const configuredAuthority = async () => {
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        return { ok: false, error: projectAnalysisError(config.error) };
+    const authority = await loadConfiguredPermissionAuthority(config.value);
+    return authority.ok
+        ? { ok: true, config: config.value, authority: authority.value }
+        : { ok: false, error: projectAnalysisError(authority.error) };
+};
+const replayDependencies = (config, authority) => ({
+    policy: config.javascriptReplayPolicy,
+    host: new SystemJavaScriptReplayHost(),
+    runner: new LinuxJavaScriptReplayRunner(),
+    authority,
+});
+const registerJsonCommand = ({ cli, logger, name, description, workflow, }) => {
+    cli.command(name, {
+        description,
+        args: z.object({
+            inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, name, async () => {
+            const input = await parseCliJsonInput(args.inputJson, name);
+            if (!input.ok)
+                return input.error;
+            const result = workflow(input.value);
+            return result.ok
+                ? result.value
+                : {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(result.error instanceof AnalysisInputError
+                        ? result.error
+                        : new AnalysisInputError(name)),
+                };
+        }),
+    });
+};

package/dist/cliBrowserAdvancedCommands.js

@@ -10,8 +10,11 @@ import { discoverWebMcpToolsInputSchema } from "./domain/webMcpDiscovery.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, } from "./domain/webScreenshot.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 const scopeOptions = {
-    allowedOrigins: z.array(z.string().min(1)).optional(),
-    approved: z.boolean().default(false),
+    allowedOrigins: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Exact origins to observe; defaults to REA_BROWSER_ALLOWED_ORIGINS_JSON"),
+    approved: z.boolean().default(false).describe("Approve passive observation"),
 };
 /** Register WebMCP, capture-diff, and screenshot CLI equivalents. */
 export const registerAdvancedBrowserCommands = (cli, logger) => {
@@ -23,19 +26,47 @@ export const registerAdvancedBrowserCommands = (cli, logger) => {
 const registerWebMcp = (cli, logger) => {
     cli.command(CLI_COMMANDS.discoverWebMcpTools, {
         description: "Passively discover page-declared WebMCP tools",
-        args: z.object({ endpoint: z.string(), targetId: z.string() }),
+        args: z.object({
+            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            targetId: z.string().describe("Target ID from list-browser-targets"),
+        }),
         options: z.object({
             ...scopeOptions,
-            observationMs: z.number().int().min(0).max(10_000).default(100),
-            maxTools: z.number().int().min(1).max(5_000).default(500),
+            observationMs: z
+                .number()
+                .int()
+                .min(0)
+                .max(10_000)
+                .default(100)
+                .describe("Observation duration in milliseconds"),
+            maxTools: z
+                .number()
+                .int()
+                .min(1)
+                .max(5_000)
+                .default(500)
+                .describe("Maximum page-declared WebMCP tools to return"),
             maxSchemaBytes: z
                 .number()
                 .int()
                 .min(1)
                 .max(1_024 * 1_024)
-                .default(256 * 1_024),
-            maxSchemaNodes: z.number().int().min(1).max(100_000).default(5_000),
-            maxSchemaDepth: z.number().int().min(1).max(100).default(20),
+                .default(256 * 1_024)
+                .describe("Maximum serialized size of one declared tool schema"),
+            maxSchemaNodes: z
+                .number()
+                .int()
+                .min(1)
+                .max(100_000)
+                .default(5_000)
+                .describe("Maximum nodes in one declared tool schema"),
+            maxSchemaDepth: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Maximum nesting depth in one declared tool schema"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "discover-webmcp-tools", async () => {
             const context = await browserContext();
@@ -62,9 +93,18 @@ const registerWebMcp = (cli, logger) => {
 const registerCaptureDiff = (cli, logger) => {
     cli.command(CLI_COMMANDS.compareWebCaptures, {
         description: "Compare two normalized web capture JSON values",
-        args: z.object({ beforeJson: z.string(), afterJson: z.string() }),
+        args: z.object({
+            beforeJson: z.string().describe("Earlier normalized web capture JSON"),
+            afterJson: z.string().describe("Later normalized web capture JSON"),
+        }),
         options: z.object({
-            maxChanges: z.number().int().min(1).max(20_000).default(2_000),
+            maxChanges: z
+                .number()
+                .int()
+                .min(1)
+                .max(20_000)
+                .default(2_000)
+                .describe("Maximum normalized changes to return"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "compare-web-captures", async () => {
             const before = parseJson(args.beforeJson);
@@ -84,16 +124,23 @@ const registerCaptureDiff = (cli, logger) => {
 const registerScreenshot = (cli, logger) => {
     cli.command(CLI_COMMANDS.captureWebScreenshot, {
         description: "Capture an explicitly approved visible page viewport",
-        args: z.object({ endpoint: z.string(), targetId: z.string() }),
+        args: z.object({
+            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            targetId: z.string().describe("Target ID from list-browser-targets"),
+        }),
         options: z.object({
             ...scopeOptions,
-            screenshotApproved: z.boolean().default(false),
+            screenshotApproved: z
+                .boolean()
+                .default(false)
+                .describe("Approve capturing the visible page viewport"),
             maximumImageBytes: z
                 .number()
                 .int()
                 .min(1)
                 .max(8 * 1_024 * 1_024)
-                .default(4 * 1_024 * 1_024),
+                .default(4 * 1_024 * 1_024)
+                .describe("Maximum captured PNG size"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "capture-web-screenshot", async () => {
             const context = await browserContext();
@@ -117,15 +164,25 @@ const registerScreenshot = (cli, logger) => {
 const registerScreenshotDiff = (cli, logger) => {
     cli.command(CLI_COMMANDS.compareWebScreenshots, {
         description: "Compare two self-verifying PNG artifact JSON values",
-        args: z.object({ beforeJson: z.string(), afterJson: z.string() }),
+        args: z.object({
+            beforeJson: z.string().describe("Earlier screenshot artifact JSON"),
+            afterJson: z.string().describe("Later screenshot artifact JSON"),
+        }),
         options: z.object({
-            channelThreshold: z.number().int().min(0).max(255).default(0),
+            channelThreshold: z
+                .number()
+                .int()
+                .min(0)
+                .max(255)
+                .default(0)
+                .describe("Per-channel difference threshold for changed pixels"),
             maximumPixels: z
                 .number()
                 .int()
                 .min(1)
                 .max(32_000_000)
-                .default(16_000_000),
+                .default(16_000_000)
+                .describe("Maximum decoded pixels per screenshot"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "compare-web-screenshots", async () => {
             const parsed = compareWebScreenshotsInputSchema.safeParse({

package/dist/cliBrowserCommands.js

@@ -9,6 +9,7 @@ import { analyzeWebBundleInputSchema } from "./domain/webBundleAnalysis.js";
 import { observeWebSessionInputSchema } from "./domain/browserSession.js";
 import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { browserPageInspectionOptions } from "./cliObservationOptions.js";
 const browserScopeOptions = {
     allowedOrigins: z
         .array(z.string().min(1))
@@ -16,6 +17,14 @@ const browserScopeOptions = {
         .describe("Exact origins to observe; defaults to REA_BROWSER_ALLOWED_ORIGINS_JSON"),
     approved: z.boolean().default(false).describe("Approve passive observation"),
 };
+const boundedCount = (subject, maximum, fallback, minimum = 1) => z
+    .number()
+    .int()
+    .min(minimum)
+    .max(maximum)
+    .default(fallback)
+    .describe(`Maximum ${subject}`);
+const boundedBytes = (subject, maximum, fallback) => boundedCount(`${subject} in bytes`, maximum, fallback);
 /** Register CLI equivalents of the passive browser MCP tools. */
 export const registerBrowserCommands = (cli, logger) => {
     registerTargetList(cli, logger);
@@ -31,8 +40,13 @@ const registerTargetList = (cli, logger) => {
         }),
         options: z.object({
             ...browserScopeOptions,
-            offset: z.number().int().min(0).default(0),
-            limit: z.number().int().min(1).max(200).default(100),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .default(0)
+                .describe("Zero-based browser-target offset"),
+            limit: boundedCount("browser targets to return", 200, 100),
         }),
         run: ({ args, options }) => logCliCommand(logger, "list-browser-targets", async () => {
             const context = await browserContext();
@@ -59,91 +73,7 @@ const registerPageInspection = (cli, logger) => {
             endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
-        options: z.object({
-            ...browserScopeOptions,
-            observationMs: z.number().int().min(0).max(10_000).default(500),
-            includeAccessibilityText: z.boolean().default(false),
-            includeConsoleText: z.boolean().default(false),
-            consoleTextApproved: z.boolean().default(false),
-            includeJsonBodyShapes: z.boolean().default(false),
-            jsonBodySchemaApproved: z.boolean().default(false),
-            includeWebsocketShapes: z.boolean().default(false),
-            websocketShapeApproved: z.boolean().default(false),
-            includeScriptSources: z.boolean().default(false),
-            includeStorageKeys: z.boolean().default(false),
-            maxFrames: z.number().int().min(1).max(1_000).default(200),
-            maxDomNodes: z.number().int().min(1).max(10_000).default(2_000),
-            maxAxNodes: z.number().int().min(1).max(10_000).default(2_000),
-            maxAxTextFieldBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(16 * 1_024)
-                .default(1_024),
-            maxTotalAxTextBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(1_024 * 1_024)
-                .default(64 * 1_024),
-            maxScripts: z.number().int().min(1).max(1_000).default(200),
-            maxResources: z.number().int().min(1).max(10_000).default(2_000),
-            maxWorkers: z.number().int().min(1).max(5_000).default(500),
-            maxStorageKeys: z.number().int().min(1).max(10_000).default(1_000),
-            maxScriptSourceBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(4 * 1_024 * 1_024)
-                .default(1_024 * 1_024),
-            maxTotalScriptSourceBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(16 * 1_024 * 1_024)
-                .default(4 * 1_024 * 1_024),
-            maxNetworkEvents: z.number().int().min(1).max(10_000).default(1_000),
-            maxConsoleEvents: z.number().int().min(1).max(2_000).default(200),
-            maxConsoleTextFieldBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(16 * 1_024)
-                .default(1_024),
-            maxTotalConsoleTextBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(1_024 * 1_024)
-                .default(64 * 1_024),
-            maxJsonBodyBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(4 * 1_024 * 1_024)
-                .default(1_024 * 1_024),
-            maxTotalJsonBodyBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(16 * 1_024 * 1_024)
-                .default(4 * 1_024 * 1_024),
-            maxJsonShapeNodes: z.number().int().min(1).max(100_000).default(5_000),
-            maxJsonShapeDepth: z.number().int().min(1).max(100).default(20),
-            maxWebsocketEvents: z.number().int().min(1).max(5_000).default(500),
-            maxWebsocketShapeBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(1_024 * 1_024)
-                .default(64 * 1_024),
-            maxTotalWebsocketShapeBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(16 * 1_024 * 1_024)
-                .default(1_024 * 1_024),
-        }),
+        options: browserPageInspectionOptions,
         run: ({ args, options }) => logCliCommand(logger, "inspect-web-page", async () => {
             const context = await browserContext();
             if (!context.ok)
@@ -204,32 +134,26 @@ const registerBundleAnalysis = (cli, logger) => {
         }),
         options: z.object({
             ...browserScopeOptions,
-            sourceCaptureApproved: z.boolean().default(false),
-            observationMs: z.number().int().min(0).max(10_000).default(500),
-            fetchSourceMaps: z.boolean().default(false),
-            sourceMapFetchApproved: z.boolean().default(false),
-            maxFindings: z.number().int().min(1).max(10_000).default(1_000),
-            maxAstNodes: z.number().int().min(1).max(2_000_000).default(250_000),
-            maxSourceMaps: z.number().int().min(1).max(1_000).default(100),
-            maxSourceMapBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(16 * 1_024 * 1_024)
-                .default(4 * 1_024 * 1_024),
-            maxTotalSourceMapBytes: z
-                .number()
-                .int()
-                .min(1)
-                .max(64 * 1_024 * 1_024)
-                .default(16 * 1_024 * 1_024),
-            maxSourceMapMappings: z
-                .number()
-                .int()
-                .min(1)
-                .max(100_000)
-                .default(10_000),
-            maxOriginalSources: z.number().int().min(1).max(20_000).default(2_000),
+            sourceCaptureApproved: z
+                .boolean()
+                .default(false)
+                .describe("Approve capturing bounded script source text"),
+            observationMs: boundedCount("observation duration in milliseconds", 10_000, 500, 0),
+            fetchSourceMaps: z
+                .boolean()
+                .default(false)
+                .describe("Fetch source maps referenced by captured scripts"),
+            sourceMapFetchApproved: z
+                .boolean()
+                .default(false)
+                .describe("Approve fetching referenced source maps from allowed origins"),
+            maxFindings: boundedCount("static-analysis findings", 10_000, 1_000),
+            maxAstNodes: boundedCount("JavaScript AST nodes", 2_000_000, 250_000),
+            maxSourceMaps: boundedCount("source maps", 1_000, 100),
+            maxSourceMapBytes: boundedBytes("one source map", 16 * 1_024 * 1_024, 4 * 1_024 * 1_024),
+            maxTotalSourceMapBytes: boundedBytes("total source maps", 64 * 1_024 * 1_024, 16 * 1_024 * 1_024),
+            maxSourceMapMappings: boundedCount("decoded source-map mappings", 100_000, 10_000),
+            maxOriginalSources: boundedCount("original source files", 20_000, 2_000),
         }),
         run: ({ args, options }) => logCliCommand(logger, "analyze-web-bundle", async () => {
             const context = await browserContext();
@@ -271,8 +195,8 @@ const registerObservationSession = (cli, logger) => {
         }),
         options: z.object({
             ...browserScopeOptions,
-            observationMs: z.number().int().min(1).max(60_000).default(10_000),
-            maxTimelineEvents: z.number().int().min(1).max(20_000).default(2_000),
+            observationMs: boundedCount("observation duration in milliseconds", 60_000, 10_000),
+            maxTimelineEvents: boundedCount("timeline events", 20_000, 2_000),
         }),
         run: ({ args, options }) => logCliCommand(logger, "observe-web-session", async () => {
             const context = await browserContext();

package/dist/cliCommandNames.js

@@ -16,6 +16,14 @@ export const CLI_COMMANDS = Object.freeze({
     importReferenceSource: "import-reference-source",
     inventoryArtifact: "inventory-artifact",
     extractArtifact: "extract-artifact",
+    inspectManagedArtifact: "inspect-managed-artifact",
+    inspectManagedMembers: "inspect-managed-members",
+    inspectManagedNativeBoundaries: "inspect-managed-native-boundaries",
+    compareManagedMembers: "compare-managed-members",
+    verifyManagedNativeBoundaries: "verify-managed-native-boundaries",
+    importManagedReconstruction: "import-managed-reconstruction",
+    planManagedRuntimeCorrelation: "plan-managed-runtime-correlation",
+    projectManagedApplicationGraph: "project-managed-application-graph",
     inspectMacho: "inspect-macho",
     inspectSignature: "inspect-signature",
     listArchitectures: "list-architectures",
@@ -38,6 +46,15 @@ export const CLI_COMMANDS = Object.freeze({
     compareWebScreenshots: "compare-web-screenshots",
     listElectronTargets: "list-electron-targets",
     inspectElectronPage: "inspect-electron-page",
+    analyzeJavaScriptApplication: "analyze-javascript-application",
+    reconcileJavaScriptRuntime: "reconcile-javascript-runtime",
+    traceApplicationFeature: "trace-application-feature",
+    compareApplicationVersions: "compare-application-versions",
+    runControlledReplay: "run-controlled-replay",
+    prepareNodeCharacterization: "prepare-node-characterization",
+    executeNodeCharacterization: "execute-node-characterization",
+    commitReconstructionCoverage: "commit-reconstruction-coverage",
+    queryReconstructionCoverage: "query-reconstruction-coverage",
 });
 /** Ordered primary CLI inventory; aliases are intentionally excluded. */
 export const CLI_COMMAND_NAMES = Object.freeze(Object.values(CLI_COMMANDS));