[fix]: refresh agent cache on action failure

[seanmcguire12]

why

• when the agent is replaying cached actions and an xpath (from the cache) does not resolve, the agent will heal and reprocess the page
• however, the cached entry is not getting updated with the "healed" selector

what changed

• added logic so agent cache replays detect when deterministic actions self-heal and immediately rewrite the cache entry with the updated selectors/timestamps, preventing perpetual failures on corrupted entries

test plan

• added agent-cache-self-heal.spec.ts end-to-end test that runs an agent with a real cacheDir, corrupts a cached selector, reruns the workflow, and asserts the cache file now contains the healed XPath

---

Summary by cubic

Fixes agent cache not refreshing after self-heal, so healed selectors are saved and future replays don’t keep failing. Addresses Linear STG-1106.

• Bug Fixes
  • Detect updated actions during replay (act/fillForm) and update the cache entry when actions change.
  • Persist refreshed steps and timestamp via refreshAgentCacheEntry.
  • Add e2e test and CI job to verify a corrupted selector is healed and the cache file is rewritten.

^{Written for commit 9634d84. Summary will update automatically on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 9634d84

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[seanmcguire12]

@greptileai

[greptile-apps]

Greptile Summary

Fixed agent cache not refreshing after self-heal, preventing perpetual replay failures on corrupted selectors.

• Core Fix: Modified replayAgentCacheEntry to track when deterministic actions change during replay (lines 506-529)
• Change Detection: Implemented haveActionsChanged to compare original vs healed actions across selector, description, method, and arguments (lines 720-751)
• Cache Refresh: Added refreshAgentCacheEntry to persist healed selectors and update timestamps (lines 753-787)
• Return Type Updates: Changed replay methods to return updated steps instead of void, enabling change tracking
• Test Coverage: Comprehensive e2e test validates the full flow by corrupting a selector and verifying it gets healed and persisted

The implementation correctly integrates with the existing self-heal mechanism in ActHandler.takeDeterministicAction, which already handles selector failures by re-processing the page with fresh snapshots. This PR bridges the gap by detecting when that healing occurs during cache replay and immediately updating the cache file.

Confidence Score: 4/5

• This PR is safe to merge with minor considerations
• The implementation is well-designed and thoroughly tested with an e2e test that validates the core functionality. The change detection logic is comprehensive, comparing all relevant action properties. The code integrates cleanly with existing self-heal mechanisms. Score is 4/5 due to the inherent complexity of cache invalidation logic and the fact that shallow equality checks on arguments assume they remain strings (which they do per the type definition, but this could be a maintenance concern if the type evolves)
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/tests/agent-cache-self-heal.spec.ts	Well-structured e2e test that validates cache self-healing by corrupting a selector and verifying it gets updated after replay
packages/core/lib/v3/cache/AgentCache.ts	Core fix that detects when deterministic actions self-heal during replay and refreshes cache entries with updated selectors. Implementation is thorough with proper change detection and logging

Sequence Diagram

sequenceDiagram
    participant Agent
    participant AgentCache
    participant ActHandler
    participant Page

    Note over Agent,AgentCache: Cache Replay Flow with Self-Heal

    Agent->>AgentCache: tryReplay(context)
    AgentCache->>AgentCache: Load cached entry from disk
    
    loop For each cached step
        AgentCache->>AgentCache: executeAgentReplayStep(step)
        
        alt Step type is "act" or "fillForm"
            AgentCache->>ActHandler: takeDeterministicAction(cachedAction)
            ActHandler->>Page: Try to execute with cached selector
            
            alt Cached selector works
                Page-->>ActHandler: Success
                ActHandler-->>AgentCache: result.success=true, actions=[original]
                Note over AgentCache: No change detected
            else Cached selector fails (e.g., xpath=/yeee)
                Page-->>ActHandler: Error (selector not found)
                
                Note over ActHandler: Self-heal mode activated
                ActHandler->>Page: captureHybridSnapshot()
                Page-->>ActHandler: Fresh DOM snapshot
                ActHandler->>ActHandler: getActionFromLLM(fresh snapshot)
                ActHandler->>Page: Execute with healed selector
                Page-->>ActHandler: Success
                ActHandler-->>AgentCache: result.success=true, actions=[healed]
                Note over AgentCache: Change detected!
            end
            
            AgentCache->>AgentCache: haveActionsChanged(original, updated)
            alt Actions changed
                AgentCache->>AgentCache: Mark stepsChanged=true
                AgentCache->>AgentCache: Store updated step
            end
        else Other step types
            AgentCache->>Page: Execute step (goto, scroll, wait, etc.)
            Note over AgentCache: No action tracking needed
        end
    end
    
    alt stepsChanged == true
        AgentCache->>AgentCache: refreshAgentCacheEntry(updatedSteps)
        AgentCache->>AgentCache: Write updated cache to disk
        Note over AgentCache: Cache now contains healed selectors
    end
    
    AgentCache-->>Agent: Return result with cacheHit=true

Loading

[cubic-dev-ai]

No issues found across 4 files

[miguelg719]

first time I see this shorthand