Update agent to only calculate xpath when caching is enabled

[tkattkat]

why

currently, we calculate the xpath for agent actions, even when the user is not using caching, this is wasteful and should only be done when caching is enabled

what changed

we now verify caching is enabled. if it is, we calculate an xpath for the action. if it is not, we do not

test plan

---

Summary by cubic

Make agent tools collect XPath only when caching (agent replay) is enabled. This reduces overhead in non-cached runs while preserving deterministic replay when cache is used.

• Refactors
  • Gate XPath collection behind v3.isAgentReplayActive in click, type, clickAndHold, dragAndDrop, and fillFormVision.
  • Record agent replay steps only when caching is active.
  • Pass returnXpath: shouldCollectXpath to page actions to avoid unnecessary computation.

^{Written for commit 6fd7cc5. Summary will update automatically on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 6fd7cc5

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

[cubic-dev-ai]

No issues found across 6 files

[greptile-apps]

Greptile Summary

• Optimizes agent tool performance by making XPath calculation conditional on caching status to reduce unnecessary computational overhead
• Gates XPath collection and agent replay step recording behind v3.isAgentReplayActive() check in click, type, and clickAndHold tools
• Passes returnXpath: shouldCollectXpath flag to page actions to avoid unnecessary XPath computation when agent replay/caching is not active

Important Files Changed

Filename	Overview
packages/core/lib/v3/agent/tools/click.ts	Conditionally requests XPath only when agent replay is active to optimize performance
packages/core/lib/v3/agent/tools/type.ts	Gates XPath collection and replay recording behind caching check to reduce overhead
packages/core/lib/v3/agent/tools/clickAndHold.ts	Optimizes by only calculating XPath when agent caching is enabled

Confidence score: 5/5

• This PR is safe to merge with minimal risk as it's a straightforward performance optimization
• Score reflects well-contained changes that only affect conditional XPath collection without modifying core functionality
• No files require special attention as the changes are isolated optimizations with consistent implementation patterns

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent as "Agent (v3.agent)"
    participant Tool as "Agent Tool (click/type/etc)"
    participant V3 as "V3 Instance"
    participant Page as "Page"
    participant Cache as "AgentCache"

    User->>Agent: "execute('click on button')"
    Agent->>Tool: "execute tool with coordinates"
    Tool->>V3: "isAgentReplayActive()"
    V3->>Tool: "return caching enabled status"
    
    alt Caching is enabled
        Tool->>Page: "click(x, y, { returnXpath: true })"
        Page->>Tool: "return xpath"
        Tool->>V3: "recordAgentReplayStep(action)"
        V3->>Cache: "store replay step"
    else Caching is disabled
        Tool->>Page: "click(x, y, { returnXpath: false })"
        Page->>Tool: "return null (no xpath)"
        Note over Tool: "Skip recording step"
    end
    
    Tool->>Agent: "return action result"
    Agent->>User: "return execution result"

Loading