fix(core): update cache when validation fails after DOM changes

[quanru]

Summary

Fixes a bug where cached xpath entries are not updated when they become invalid due to DOM changes, causing subsequent executions to repeatedly fail.

Problem

When page DOM structure changes (e.g., elements are moved or removed), the cached xpath becomes invalid. Previously:

1. Cache validation (rectMatchesCacheFeature) fails
2. AI re-locates the element successfully with new xpath
3. Cache is NOT updated (bug)
4. Next execution repeats the same failure

This created a loop where users had to manually delete cache files to fix the issue.

Root Cause

In packages/core/src/agent/task-builder.ts:506, the cache write condition included:

!locateCacheAlreadyExists

This check was designed to avoid redundant cache writes for plan hit scenarios (when LLM provides bbox), but it incorrectly blocked cache updates when:

• Cache record exists but validation failed (cache is stale)
• AI successfully re-located the element with new xpath

Solution

Modified the cache write condition to:

(!isPlanHit || !locateCacheAlreadyExists)

This change:

• ✅ Allows cache updates when validation fails (fixes the bug)
• ✅ Preserves the original optimization (no redundant writes for plan hit)
• ✅ Maintains backward compatibility

Changes

Core Logic

• File: packages/core/src/agent/task-builder.ts
• Line: 506
• Change: Modified condition from !locateCacheAlreadyExists to (!isPlanHit || !locateCacheAlreadyExists)
• Comment: Updated to reflect new logic

Tests

• File: packages/core/tests/unit-test/bbox-locate-cache.test.ts
• Added new test suite: "cache invalidation and update"
• Test case 1: Cache update when xpath becomes invalid after DOM changes
• Test case 2: Cache update for non-plan-hit scenarios with validation failure

Test Results

✅ All tests pass (275 tests, 0 failures)

Test Files  20 passed (20)
Tests       275 passed | 5 skipped (280)

Behavior Change

Before Fix

1st run: AI locate → Cache written (xpath1)
DOM changes: Element moved/removed
2nd run: Cache validation fails → AI re-locates → ❌ Cache NOT updated
3rd run: Cache validation fails → AI re-locates → ❌ Cache NOT updated
... (infinite loop)

After Fix

1st run: AI locate → Cache written (xpath1)
DOM changes: Element moved/removed
2nd run: Cache validation fails → AI re-locates → ✅ Cache updated (xpath2)
3rd run: ✅ Cache hit succeeds (uses xpath2)

Impact

• User Experience: System now has self-healing capability - no manual cache file deletion needed
• Performance: Reduces AI calls after cache becomes invalid (2nd run onwards uses cache)
• Compatibility: Fully backward compatible, no breaking changes

Related Issue

Reported by user: Cache not updated after DOM structure changes (from 4 grade options to 1 grade option), causing persistent failures despite AI successfully re-locating elements.

[netlify]

✅ Deploy Preview for midscene ready!

Name	Link
🔨 Latest commit	af69312
🔍 Latest deploy log	https://app.netlify.com/projects/midscene/deploys/695dd19303d2e3000832d9b8
😎 Deploy Preview	https://deploy-preview-1729--midscene.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.