rea-agents 6.3.0 → 6.5.0

package/dist/cli/apktoolCommands.js

@@ -0,0 +1,52 @@
+import { z } from "incur";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";
+import { createApktoolResourceAnalysisProvider } from "../composition/apktool.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { apktoolInputSchemas, } from "../domain/apktool/apktoolResourceAnalysis.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Expose the same explicit Apktool requests through one-shot CLI commands. */
+export const registerApktoolCommands = (cli, logger, environment, provider = createApktoolResourceAnalysisProvider(environment)) => {
+    const service = new ApktoolResourceAnalysisService(provider);
+    const execute = (name, operation, input) => withCommandCancellation((signal) => logCliCommand(logger, name, async () => {
+        const result = await service.execute(operation, input, { signal });
+        try {
+            await provider.close();
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return projectAnalysisError(cause);
+            throw cause;
+        }
+        return result.ok ? result.value : projectAnalysisError(result.error);
+    }));
+    cli.command(CLI_COMMANDS.inspectApktoolClient, {
+        description: "Inspect the caller-selected apktool launcher without decoding anything",
+        args: z.object({}),
+        run: () => execute(CLI_COMMANDS.inspectApktoolClient, "inspect_apktool_client", {}),
+    });
+    cli.command(CLI_COMMANDS.decodeAndroidResources, {
+        description: "Decode one APK's manifest, metadata, and string resources with apktool",
+        args: z.object({
+            path: z.string().min(1).describe("Local APK file to decode"),
+        }),
+        // The locale grammar and the string-projection default belong to the
+        // apktool input owner. Read them from that schema rather than restating a
+        // narrower locale pattern, which refused the owner's own advertised
+        // `b+zh+Hans+CN` form at the CLI boundary.
+        options: z.object({
+            locale: apktoolInputSchemas.decode_android_resources.shape.locale,
+            strings: z
+                .boolean()
+                .default(apktoolInputSchemas.decode_android_resources.shape.include_strings.parse(undefined))
+                .describe("Include string resources; use --no-strings to skip projecting them"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.decodeAndroidResources, "decode_android_resources", {
+            path: args.path,
+            include_strings: options.strings,
+            ...(options.locale === undefined ? {} : { locale: options.locale }),
+        }),
+    });
+};

package/dist/cli/applicationCommands.js

@@ -1,18 +1,12 @@
 import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
 import { Cli, z } from "incur";
-import { projectAndroidApplicationEvidence } from "../application/android/AndroidApplicationService.js";
-import { projectAppleApplicationEvidence } from "../application/apple/AppleApplicationService.js";
-import { compareApplicationVersionsEvidenceValidated, compareJavaScriptExportShapesEvidenceValidated, compareSourceToBundleEvidenceValidated, traceApplicationFeatureEvidenceValidated, } from "../application/javascript/JavaScriptApplicationWorkflowService.js";
-import { traceJavaScriptSemanticsEvidenceValidated } from "../application/javascript/JavaScriptSemanticTraceService.js";
-import { evaluateReconstructionCoverage } from "../application/ReconstructionCoverageService.js";
-import { buildReconstructionObligationLedgerEvidenceValidated } from "../application/ReconstructionObligationLedgerService.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { logCliCommand } from "../cliLogging.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
-import {} from "../domain/analysisErrorBase.js";
 import { androidApplicationProjectionInputSchema } from "../domain/android/androidApplication.js";
 import { appleApplicationProjectionInputSchema } from "../domain/apple/appleApplication.js";
+import { harmonyApplicationProjectionInputSchema } from "../domain/harmony/harmonyApplication.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { traceApplicationFeatureInputSchema } from "../domain/javascript/javascriptFeatureTraceSchemas.js";
 import { traceJavaScriptSemanticsInputSchema } from "../domain/javascript/javascriptSemanticTraceSchemas.js";
@@ -29,7 +23,10 @@ export const registerApplicationCommands = (cli, logger) => {
         name: CLI_COMMANDS.traceApplicationFeature,
         description: "Trace a typed seed through authenticated application Evidence JSON",
         inputSchema: traceApplicationFeatureInputSchema,
-        workflow: traceApplicationFeatureEvidenceValidated,
+        workflow: async (input) => {
+            const { traceApplicationFeatureEvidenceValidated } = await import("../application/javascript/JavaScriptApplicationWorkflowService.js");
+            return traceApplicationFeatureEvidenceValidated(input);
+        },
     });
     registerJsonCommand({
         cli,
@@ -37,7 +34,10 @@ export const registerApplicationCommands = (cli, logger) => {
         name: CLI_COMMANDS.traceJavaScriptSemantics,
         description: "Trace bounded static semantic relations through authenticated application Evidence",
         inputSchema: traceJavaScriptSemanticsInputSchema,
-        workflow: traceJavaScriptSemanticsEvidenceValidated,
+        workflow: async (input) => {
+            const { traceJavaScriptSemanticsEvidenceValidated } = await import("../application/javascript/JavaScriptSemanticTraceService.js");
+            return traceJavaScriptSemanticsEvidenceValidated(input);
+        },
     });
     registerJsonCommand({
         cli,
@@ -45,7 +45,10 @@ export const registerApplicationCommands = (cli, logger) => {
         name: CLI_COMMANDS.compareApplicationVersions,
         description: "Compare two authenticated JavaScript Application Graph versions",
         inputSchema: compareApplicationVersionsInputSchema,
-        workflow: compareApplicationVersionsEvidenceValidated,
+        workflow: async (input) => {
+            const { compareApplicationVersionsEvidenceValidated } = await import("../application/javascript/JavaScriptApplicationWorkflowService.js");
+            return compareApplicationVersionsEvidenceValidated(input);
+        },
     });
     registerJsonCommand({
         cli,
@@ -53,7 +56,10 @@ export const registerApplicationCommands = (cli, logger) => {
         name: CLI_COMMANDS.compareSourceToBundle,
         description: "Compare committed historical source with authenticated application Evidence",
         inputSchema: compareSourceToBundleInputSchema,
-        workflow: compareSourceToBundleEvidenceValidated,
+        workflow: async (input) => {
+            const { compareSourceToBundleEvidenceValidated } = await import("../application/javascript/JavaScriptApplicationWorkflowService.js");
+            return compareSourceToBundleEvidenceValidated(input);
+        },
     });
     registerJsonCommand({
         cli,
@@ -61,7 +67,10 @@ export const registerApplicationCommands = (cli, logger) => {
         name: CLI_COMMANDS.compareJavaScriptExportShapes,
         description: "Compare exact static JavaScript export return shapes without execution",
         inputSchema: compareJavaScriptExportShapesInputSchema,
-        workflow: compareJavaScriptExportShapesEvidenceValidated,
+        workflow: async (input) => {
+            const { compareJavaScriptExportShapesEvidenceValidated } = await import("../application/javascript/JavaScriptApplicationWorkflowService.js");
+            return compareJavaScriptExportShapesEvidenceValidated(input);
+        },
     });
     registerObligationLedgerCommand(cli, logger);
     registerCoverageCommand(cli, logger);
@@ -71,7 +80,8 @@ export const registerApplicationCommands = (cli, logger) => {
         name: CLI_COMMANDS.projectAndroidApplicationGraph,
         description: "Project authenticated APK inventory Evidence into an Android application graph",
         inputSchema: androidApplicationProjectionInputSchema,
-        workflow: (input) => {
+        workflow: async (input) => {
+            const { projectAndroidApplicationEvidence } = await import("../application/android/AndroidApplicationService.js");
             const result = projectAndroidApplicationEvidence(input);
             return result.ok
                 ? { ok: true, value: jsonValueSchema.parse(result.value) }
@@ -84,13 +94,28 @@ export const registerApplicationCommands = (cli, logger) => {
         name: CLI_COMMANDS.projectAppleApplicationGraph,
         description: "Project authenticated IPA or macOS app inventory Evidence into an Apple application graph",
         inputSchema: appleApplicationProjectionInputSchema,
-        workflow: (input) => {
+        workflow: async (input) => {
+            const { projectAppleApplicationEvidence } = await import("../application/apple/AppleApplicationService.js");
             const result = projectAppleApplicationEvidence(input);
             return result.ok
                 ? { ok: true, value: jsonValueSchema.parse(result.value) }
                 : result;
         },
     });
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.projectHarmonyApplicationGraph,
+        description: "Project authenticated HarmonyOS HAP, HSP, or App Pack inventory Evidence into an application graph",
+        inputSchema: harmonyApplicationProjectionInputSchema,
+        workflow: async (input) => {
+            const { projectHarmonyApplicationEvidence } = await import("../application/harmony/HarmonyApplicationService.js");
+            const result = projectHarmonyApplicationEvidence(input);
+            return result.ok
+                ? { ok: true, value: jsonValueSchema.parse(result.value) }
+                : result;
+        },
+    });
 };
 const registerObligationLedgerCommand = (cli, logger) => registerJsonCommand({
     cli,
@@ -98,7 +123,8 @@ const registerObligationLedgerCommand = (cli, logger) => registerJsonCommand({
     name: CLI_COMMANDS.buildReconstructionObligationLedger,
     description: "Generate a deterministic Evidence-backed reconstruction obligation ledger page",
     inputSchema: reconstructionObligationLedgerInputSchema,
-    workflow: (input) => {
+    workflow: async (input) => {
+        const { buildReconstructionObligationLedgerEvidenceValidated } = await import("../application/ReconstructionObligationLedgerService.js");
         const result = buildReconstructionObligationLedgerEvidenceValidated(input);
         return result.ok
             ? { ok: true, value: jsonValueSchema.parse(result.value) }
@@ -111,7 +137,8 @@ const registerCoverageCommand = (cli, logger) => registerJsonCommand({
     name: CLI_COMMANDS.evaluateReconstructionCoverage,
     description: "Evaluate inline fail-closed reconstruction coverage",
     inputSchema: reconstructionCoverageEvaluationInputSchema,
-    workflow: (input) => {
+    workflow: async (input) => {
+        const { evaluateReconstructionCoverage } = await import("../application/ReconstructionCoverageService.js");
         const result = evaluateReconstructionCoverage(input);
         return result.ok
             ? { ok: true, value: jsonValueSchema.parse(result.value) }
@@ -134,7 +161,7 @@ const registerJsonCommand = ({ cli, logger, name, description, inputSchema, work
                     error: "Application workflow failed",
                     ...projectAnalysisError(analysisInputErrorFromIssues(name, parsed.error.issues, input.value)),
                 };
-            const result = workflow(parsed.data);
+            const result = await workflow(parsed.data);
             return result.ok
                 ? result.value
                 : {

package/dist/cli/artifactCommands.js

@@ -84,7 +84,6 @@ const registerAssetCatalogCommand = (cli, logger, runProviderAnalysis) => {
                 .default(1_000)
                 .describe("Maximum records to return"),
         }),
-        alias: {},
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.inspectAssetCatalog, () => runProviderAnalysis(args.path, "inspect_asset_catalog", { offset: options.offset, limit: options.limit }, logger)),
     });
 };
@@ -117,11 +116,6 @@ const registerInterfaceBuilderCommand = (cli, logger, runProviderAnalysis) => {
                 .default(40_000)
                 .describe("Maximum decoded connections"),
         }),
-        alias: {
-            maxDocuments: "max-documents",
-            maxObjects: "max-objects",
-            maxConnections: "max-connections",
-        },
         run: ({ args, options }) => logCliCommand(logger, "decode-interface-builder", () => runProviderAnalysis(args.path, "decode_interface_builder", {
             max_documents: options.maxDocuments,
             max_objects: options.maxObjects,
@@ -135,8 +129,14 @@ const registerExtractionCommand = (cli, logger, runProviderAnalysis) => {
         args: z.object({
             path: z.string().describe("Application or package path"),
         }),
-        options: z.object({}),
-        run: ({ args }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
+        options: z.object({
+            integrityPolicy: z
+                .enum(["fail", "record-and-continue"])
+                .default("fail")
+                .describe("Behavior when declared artifact integrity does not match"),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
+            integrity_policy: options.integrityPolicy,
             output_root: createArtifactExtractionDestination(),
         }, logger)),
     });
@@ -145,7 +145,7 @@ const registerInspectionCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectArtifact, {
         description: "Inspect one artifact and return all available observations and next probes",
         args: z.object({
-            path: z.string().describe("Application or package path"),
+            path: z.string().min(1).describe("Application or package path"),
         }),
         options: z.object({
             integrityPolicy: z
@@ -153,9 +153,6 @@ const registerInspectionCommand = (cli, logger, runProviderAnalysis) => {
                 .default("fail")
                 .describe("Behavior when declared artifact integrity does not match"),
         }),
-        alias: {
-            integrityPolicy: "integrity-policy",
-        },
         run: ({ args, options }) => logCliCommand(logger, "inspect-artifact", () => runProviderAnalysis(args.path, "inspect_artifact", {
             integrity_policy: options.integrityPolicy,
         }, logger)),

package/dist/cli/binaryDiagnosticsCommands.js

@@ -1,12 +1,30 @@
 import { z } from "incur";
 import { resolve } from "node:path";
-import { createRecordedCrashService, createBinaryLayoutService, } from "../composition/binaryDiagnostics.js";
+import { createRecordedCrashService, createBinaryLayoutService, createPeResourcesService, } from "../composition/binaryDiagnostics.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { withCommandCancellation } from "./commandCancellation.js";
+import { inspectPeResourcesInputSchema } from "../domain/native/peResources.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
 /** Inspect operator-selected files through the same shared workflow as MCP. */
 export const registerBinaryDiagnosticsCommands = (cli, logger, environment) => {
+    cli.command(CLI_COMMANDS.inspectPeResources, {
+        description: "Inspect PE resource identities, payload ranges, hashes and icon-group relationships",
+        args: z.object({ path: z.string().describe("Local PE32/PE32+ image") }),
+        options: z.object({
+            maxFileBytes: inspectPeResourcesInputSchema.shape.max_file_bytes,
+            maxEntries: inspectPeResourcesInputSchema.shape.max_entries,
+        }),
+        run: ({ args, options }) => withCommandCancellation(async (signal) => {
+            const pe = createPeResourcesService();
+            return await logCliCommand(logger, CLI_COMMANDS.inspectPeResources, async () => finishAnalysisCommand(() => pe.inspect({
+                path: resolve(args.path),
+                max_file_bytes: options.maxFileBytes,
+                max_entries: options.maxEntries,
+            }, { signal }), pe, "rea-pe-resources", "inspect_pe_resources"));
+        }),
+    });
     const service = createBinaryLayoutService(environment);
     cli.command(CLI_COMMANDS.inspectBinaryLayout, {
         description: "Inspect binary file/linked layout without executing the selected object",
@@ -14,14 +32,18 @@ export const registerBinaryDiagnosticsCommands = (cli, logger, environment) => {
             path: z.string().describe("Local ELF binary or relocatable object"),
         }),
         run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectBinaryLayout, async () => {
-            const result = await service.inspect({ path: resolve(args.path) }, { signal });
+            const result = await service.inspectAndClose({ path: resolve(args.path) }, { signal });
             return result.ok ? result.value : projectAnalysisError(result.error);
         })),
     });
     const recorded = createRecordedCrashService(environment);
     cli.command(CLI_COMMANDS.inspectRecordedCrash, {
         description: "Inspect supplied core registers/signals and optional debugger mapping evidence",
-        args: z.object({ path: z.string().describe("Local Linux amd64 ELF core") }),
+        args: z.object({
+            path: z
+                .string()
+                .describe("Local Linux ELF64 amd64 or AArch64 little-endian core"),
+        }),
         options: z.object({
             debuggerContext: z
                 .boolean()
@@ -29,7 +51,7 @@ export const registerBinaryDiagnosticsCommands = (cli, logger, environment) => {
                 .describe("Add BYO core-only GDB/pwndbg mapping candidates"),
         }),
         run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectRecordedCrash, async () => {
-            const result = await recorded.inspect({
+            const result = await recorded.inspectAndClose({
                 path: resolve(args.path),
                 include_debugger_context: options.debuggerContext,
             }, { signal });

package/dist/cli/browserAdvancedCommands.js

@@ -5,11 +5,15 @@ import { captureWebScreenshot, compareWebCaptureEvidence, compareWebScreenshotEv
 import { CdpBrowserProvider } from "../browser/CdpBrowserProvider.js";
 import { logCliCommand } from "../cliLogging.js";
 import { AnalysisInputError, } from "../domain/analysisErrorCore.js";
-import { browserCaptureComparisonInputSchema } from "../domain/browserCaptureComparison.js";
+import { compareBrowserScenariosInputSchema } from "../domain/browserScenarioDiffValues.js";
+import { browserScenarioCaptureSchema } from "../domain/browserScenarioCapture.js";
+import { compareWebCapturesInputSchema } from "../domain/webCaptureDiffSchemas.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { discoverWebMcpToolsInputSchema } from "../domain/webMcpDiscovery.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, } from "../domain/webScreenshot.js";
-import { safeParseJson } from "../domain/safeJson.js";
+import { parseCliJsonInput } from "../cliJsonInput.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { withCommandCancellation } from "./commandCancellation.js";
 /** Register WebMCP, capture-diff, and screenshot CLI equivalents. */
 export const registerAdvancedBrowserCommands = (cli, logger) => {
     registerWebMcp(cli, logger);
@@ -21,7 +25,9 @@ const registerWebMcp = (cli, logger) => {
     cli.command(CLI_COMMANDS.discoverWebMcpTools, {
         description: "Passively discover page-declared WebMCP tools",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
         options: z.object({
@@ -33,63 +39,62 @@ const registerWebMcp = (cli, logger) => {
                 .default(100)
                 .describe("Observation duration in milliseconds"),
         }),
-        run: ({ args, options }) => logCliCommand(logger, "discover-webmcp-tools", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "discover-webmcp-tools", async () => {
             const context = browserContext();
-            const parsed = discoverWebMcpToolsInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
                 target_id: args.targetId,
                 observation_ms: options.observationMs,
-            });
+            };
+            const parsed = discoverWebMcpToolsInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("discover_webmcp_tools");
-            const result = await discoverWebMcpTools(context.provider, parsed.data);
+                return inputError("discover_webmcp_tools", projectInputIssues(parsed.error.issues, input));
+            const result = await discoverWebMcpTools(context.provider, parsed.data, { signal });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };
 const registerCaptureDiff = (cli, logger) => {
     cli.command(CLI_COMMANDS.compareWebCaptures, {
         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"),
+            beforeJson: z
+                .string()
+                .describe("Earlier normalized web capture JSON or JSON file path"),
+            afterJson: z
+                .string()
+                .describe("Later normalized web capture JSON or JSON file path"),
         }),
         options: z.object({
             normalizationJson: z
                 .string()
                 .default('{"rules":[]}')
-                .describe("Recorded literal normalization policy for browser scenarios"),
+                .describe("Recorded literal normalization policy JSON or JSON file path for browser scenarios"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "compare-web-captures", async () => {
-            const before = safeParseJson(args.beforeJson);
-            const after = safeParseJson(args.afterJson);
-            const normalization = safeParseJson(options.normalizationJson);
-            if (!before.ok)
-                return inputError("compare_web_captures", [
-                    invalidJsonIssue("before"),
-                ]);
-            if (!after.ok)
-                return inputError("compare_web_captures", [
-                    invalidJsonIssue("after"),
-                ]);
-            if (!normalization.ok)
-                return inputError("compare_web_captures", [
-                    invalidJsonIssue("normalization"),
-                ]);
-            const scenarioComparison = browserCaptureComparisonInputSchema.safeParse({
-                before_scenario: before.value,
-                after_scenario: after.value,
-                normalization: normalization.value,
+            const inputs = await parseJsonArguments("compare_web_captures", {
+                before: args.beforeJson,
+                after: args.afterJson,
+                normalization: options.normalizationJson,
             });
-            const parsed = scenarioComparison.success
-                ? scenarioComparison
-                : browserCaptureComparisonInputSchema.safeParse({
-                    before: before.value,
-                    after: after.value,
-                });
+            if (!inputs.ok)
+                return inputs.error;
+            const { before, after, normalization } = inputs.value;
+            // Passive snapshots own the inspection wrapper. Otherwise recognize
+            // scenario-owned fields even when the scenario manifest is missing.
+            const scenarioInput = [before, after].some((capture) => typeof capture === "object" &&
+                capture !== null &&
+                !("inspection" in capture) &&
+                Object.keys(browserScenarioCaptureSchema.shape).some((field) => field in capture));
+            const input = scenarioInput
+                ? { before_scenario: before, after_scenario: after, normalization }
+                : { before, after };
+            const parsed = scenarioInput
+                ? compareBrowserScenariosInputSchema.safeParse(input)
+                : compareWebCapturesInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("compare_web_captures");
+                return inputError("compare_web_captures", projectInputIssues(parsed.error.issues, input));
             const result = await compareWebCaptureEvidence(new CdpBrowserProvider(), parsed.data);
             return result.ok ? result.value : browserCliError(result.error);
         }),
@@ -99,32 +104,39 @@ const registerScreenshot = (cli, logger) => {
     cli.command(CLI_COMMANDS.captureWebScreenshot, {
         description: "Capture one visible page viewport within the supplied origin scope",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
         options: z.object({
             ...browserScopeOptions,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "capture-web-screenshot", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "capture-web-screenshot", async () => {
             const context = browserContext();
-            const parsed = captureWebScreenshotInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
                 target_id: args.targetId,
-            });
+            };
+            const parsed = captureWebScreenshotInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("capture_web_screenshot");
-            const result = await captureWebScreenshot(context.provider, parsed.data);
+                return inputError("capture_web_screenshot", projectInputIssues(parsed.error.issues, input));
+            const result = await captureWebScreenshot(context.provider, parsed.data, { signal });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };
 const registerScreenshotDiff = (cli, logger) => {
     cli.command(CLI_COMMANDS.compareWebScreenshots, {
         description: "Compare two self-verifying PNG artifact JSON values",
         args: z.object({
-            beforeJson: z.string().describe("Earlier screenshot artifact JSON"),
-            afterJson: z.string().describe("Later screenshot artifact JSON"),
+            beforeJson: z
+                .string()
+                .describe("Earlier screenshot artifact JSON or JSON file path"),
+            afterJson: z
+                .string()
+                .describe("Later screenshot artifact JSON or JSON file path"),
         }),
         options: z.object({
             channelThreshold: z
@@ -136,22 +148,52 @@ const registerScreenshotDiff = (cli, logger) => {
                 .describe("Per-channel difference threshold for changed pixels"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "compare-web-screenshots", async () => {
-            const parsed = compareWebScreenshotsInputSchema.safeParse({
-                before: parseJson(args.beforeJson),
-                after: parseJson(args.afterJson),
-                channel_threshold: options.channelThreshold,
+            const operation = "compare_web_screenshots";
+            const inputs = await parseJsonArguments(operation, {
+                before: args.beforeJson,
+                after: args.afterJson,
             });
+            if (!inputs.ok)
+                return inputs.error;
+            const { before, after } = inputs.value;
+            const input = {
+                before,
+                after,
+                channel_threshold: options.channelThreshold,
+            };
+            const parsed = compareWebScreenshotsInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("compare_web_screenshots");
+                return browserCliError(new AnalysisInputError(operation, { cause: parsed.error }, projectInputIssues(parsed.error.issues, input)));
             const result = await compareWebScreenshotEvidence(new CdpBrowserProvider(), parsed.data);
             return result.ok ? result.value : browserCliError(result.error);
         }),
     });
 };
-const parseJson = (value) => {
-    const parsed = safeParseJson(value);
-    return parsed.ok ? parsed.value : undefined;
+/**
+ * Parse each named inline JSON argument or local JSON file, like other
+ * JSON-input commands. Screenshot artifacts and scenario captures embed PNG
+ * bytes that can exceed the host's command-line length limit.
+ */
+const parseJsonArguments = async (operation, fields) => {
+    const values = {};
+    for (const [field, value] of Object.entries(fields)) {
+        const parsed = await parseCliJsonInput(value, operation);
+        if (!parsed.ok)
+            return isFileInputFailure(parsed.error)
+                ? parsed
+                : {
+                    ok: false,
+                    error: inputError(operation, [invalidJsonIssue(field)]),
+                };
+        values[field] = parsed.value;
+    }
+    return { ok: true, value: values };
 };
+/** File read and decode failures name the selected path; inline JSON does not. */
+const isFileInputFailure = (error) => typeof error === "object" &&
+    error !== null &&
+    !Array.isArray(error) &&
+    "input_path" in error;
 const invalidJsonIssue = (field) => ({
     path: [field],
     reason: "invalid_format",