feat(core,web): add default read-write strategy and fix xpath cache default (#1270)

This commit includes two important changes:

1. Add 'read-write' as default cache strategy:
   - Updated CacheConfig type to support 'read-write' strategy
   - Changed default strategy from undefined to 'read-write'
   - Added unit test for explicit 'read-write' configuration

2. Fix xpath cache default behavior (orderSensitive):
   - Changed default orderSensitive from true to false in cacheFeatureForRect
   - Ensures generated xpaths use normalize-space() for text-based matching
   - This makes cached xpaths more stable across DOM changes

   Before: /html/body/div[1]/h1[1]
   After:  /html/body/div[1]/h1[normalize-space()="Example Domain"]

   - Added comprehensive unit test to prevent regression

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: quanru

packages/core/src/agent/agent.ts

@@ -1079,7 +1079,9 @@ export class Agent<
           );
         }
         const id = config.id;
-        const isReadOnly = config.strategy === 'read-only';
+        // Default strategy is 'read-write'
+        const strategy = config.strategy ?? 'read-write';
+        const isReadOnly = strategy === 'read-only';
 
         return {
           id,

packages/core/src/types.ts

@@ -580,9 +580,7 @@ export type WebUIContext = UIContext<WebElementInfo>;
  * Agent
  */
 
-export type CacheConfig =
-  | { strategy: 'read-only'; id: string }
-  | { strategy?: undefined; id: string };
+export type CacheConfig = { strategy?: 'read-only' | 'read-write'; id: string };
 
 export type Cache =
   | false // No read, no write

packages/web-integration/src/puppeteer/base-page.ts

@@ -207,7 +207,7 @@ export class Page<
     };
 
     try {
-      const orderSensitive = opt?._orderSensitive ?? true;
+      const orderSensitive = opt?._orderSensitive ?? false;
       const xpaths = await this.getXpathsByPoint(center, orderSensitive);
       const sanitized = sanitizeXpaths(xpaths);
       if (!sanitized.length) {

packages/web-integration/tests/ai/web/puppeteer/cache-functionality.test.ts

@@ -23,6 +23,7 @@ describe('Cache Configuration Tests', () => {
     const agent = new PuppeteerAgent(originPage, {
       cache: {
         id: 'cache-functionality-test',
+        strategy: 'read-write',
       },
       testId: 'explicit-cache-test-001',
     });

packages/web-integration/tests/unit-test/agent.test.ts

@@ -435,7 +435,7 @@ describe('PageAgent cache configuration', () => {
       }).toThrow('cache configuration requires an explicit id');
     });
 
-    it('should handle cache: { id: "custom-id" }', () => {
+    it('should handle cache: { id: "custom-id" } with default read-write strategy', () => {
       const agent = new PageAgent(mockPage, {
         cache: { id: 'custom-cache-id' },
         modelConfig: () => mockedModelConfigFnResult,
@@ -447,6 +447,21 @@ describe('PageAgent cache configuration', () => {
       expect(agent.taskCache?.cacheId).toBe('custom-cache-id');
     });
 
+    it('should handle cache: { strategy: "read-write", id: "custom-id" }', () => {
+      const agent = new PageAgent(mockPage, {
+        cache: {
+          strategy: 'read-write',
+          id: 'custom-readwrite-cache',
+        },
+        modelConfig: () => mockedModelConfigFnResult,
+      });
+
+      expect(agent.taskCache).toBeDefined();
+      expect(agent.taskCache?.isCacheResultUsed).toBe(true);
+      expect(agent.taskCache?.readOnlyMode).toBe(false);
+      expect(agent.taskCache?.cacheId).toBe('custom-readwrite-cache');
+    });
+
     it('should handle cache: { strategy: "read-only", id: "custom-id" }', () => {
       const agent = new PageAgent(mockPage, {
         cache: {

packages/web-integration/tests/unit-test/web-extractor.test.ts

@@ -386,6 +386,83 @@ describe(
 
         await reset();
       });
+
+      it('cacheFeatureForRect should default to order-insensitive (normalize-space) mode', async () => {
+        const { page, reset } = await launchPage(`http://127.0.0.1:${port}`, {
+          viewport: {
+            width: 1080,
+            height: 3000,
+            deviceScaleFactor: 1,
+          },
+        });
+
+        // Target a button element with text content
+        // Use coordinates that will hit an actual element with text
+        const rect = {
+          left: 100,
+          top: 400,
+          width: 100,
+          height: 40,
+        };
+
+        // Call cacheFeatureForRect without opt parameter (should default to orderSensitive=false)
+        const cacheFeature = await page.cacheFeatureForRect?.(rect);
+
+        expect(cacheFeature).toBeDefined();
+        const xpaths = (cacheFeature as any)?.xpaths as string[] | undefined;
+        expect(xpaths).toBeDefined();
+        expect(xpaths?.length).toBeGreaterThan(0);
+
+        const xpath = xpaths?.[0];
+        expect(xpath).toMatch(/^\/html/);
+
+        // Verify with explicit orderSensitive=false
+        const cacheFeatureInsensitive = await page.cacheFeatureForRect?.(rect, {
+          _orderSensitive: false,
+        });
+
+        const xpathsInsensitive = (cacheFeatureInsensitive as any)
+          ?.xpaths as string[];
+        const xpathInsensitive = xpathsInsensitive?.[0];
+
+        // Default behavior should match explicit orderSensitive=false
+        expect(xpath).toBe(xpathInsensitive);
+
+        // Verify that orderSensitive=true produces different (index-based) xpath
+        const cacheFeatureSensitive = await page.cacheFeatureForRect?.(rect, {
+          _orderSensitive: true,
+        });
+
+        const xpathsSensitive = (cacheFeatureSensitive as any)
+          ?.xpaths as string[];
+        const xpathSensitive = xpathsSensitive?.[0];
+
+        // Skip special elements like body
+        if (
+          xpathSensitive &&
+          xpathSensitive !== '/html/body' &&
+          xpathSensitive !== '/html'
+        ) {
+          // Order-sensitive xpath should:
+          // 1. Either use index format like [1], [2] at the end
+          // 2. Or NOT use normalize-space (for better distinction)
+          const isIndexBased = /\[\d+\]/.test(xpathSensitive);
+          const hasNormalizeSpace =
+            xpathSensitive.includes('normalize-space()');
+
+          // For order-insensitive (default), leaf elements with text should prefer normalize-space
+          // For order-sensitive, it should use index-based format
+          if (xpath !== xpathSensitive) {
+            // They should be different
+            expect(xpath).not.toBe(xpathSensitive);
+
+            // Order-sensitive should either use index or not use normalize-space
+            expect(isIndexBased || !hasNormalizeSpace).toBe(true);
+          }
+        }
+
+        await reset();
+      });
     });
   },
 );