allow act cache hit when variable values change #1408

seanmcguire12 · 2025-12-12T22:42:49Z

why

what changed

test plan

Summary by cubic

Allow act() cache hits even when variable values change by caching on variable keys and resolving values at execution time. Addresses STG-1065.

Bug Fixes
- Cache key now uses sorted variableKeys, not variable values; entries store variableKeys.
- Cache hit requires matching variable keys and provided values; logs a miss when values are missing.
- Variables are passed into action execution and resolved at runtime; cached actions keep placeholder arguments.
- Updated types to make variables optional and include variableKeys; write cache entries with variableKeys.

^{Written for commit 590fc8b. Summary will update automatically on new commits.}

changeset-bot · 2025-12-12T22:42:52Z

🦋 Changeset detected

Latest commit: 590fc8b

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 · 2025-12-12T22:51:01Z

@greptileai

greptile-apps · 2025-12-12T22:53:25Z

Greptile Overview

Greptile Summary

This PR enables act() cache hits even when variable values change by caching on variable keys instead of values and resolving values at execution time.

Key changes:

Cache key generation now uses sorted variable keys (variableKeys) instead of variable values, allowing cache hits when the same variables are used with different values
Variable substitution moved from getActionFromLLM to takeDeterministicAction, so cached actions store placeholder arguments (e.g., %username%) that are resolved at runtime
Added validation in cache replay to ensure all required variable keys are present with values before attempting replay
Updated types to reflect variableKeys as the stored cache property instead of full variable values

This is a well-structured change that improves cache efficiency for parameterized actions without compromising correctness.

Confidence Score: 5/5

This PR is safe to merge - it's a well-designed improvement to cache efficiency with proper validation.
The changes are logically sound and consistent. Variable keys are properly sorted before storage and comparison. The validation logic correctly ensures variable values are present before replay. The variable substitution is correctly deferred to execution time while preserving placeholder arguments in the cache.
No files require special attention.

Important Files Changed

File Analysis

Filename	Score	Overview
.changeset/fruity-badgers-sort.md	5/5	Standard changeset file documenting a patch release for allowing act() cache hits when variable values change.
packages/core/lib/v3/cache/ActCache.ts	5/5	Core cache changes: cache key now uses sorted variableKeys instead of values, adds validation for variable keys matching and value presence during replay, passes variables to action execution for runtime substitution.
packages/core/lib/v3/handlers/actHandler.ts	5/5	Deferred variable substitution: moved from getActionFromLLM to takeDeterministicAction; actions now store placeholder arguments in cache, resolved at execution time.
packages/core/lib/v3/types/private/cache.ts	5/5	Type updates: ActCacheContext now has variableKeys array (required) and variables (optional); CachedActEntry stores variableKeys instead of variable values.
packages/core/lib/v3/v3.ts	5/5	Pass variables to takeDeterministicAction for runtime substitution when acting on observe results.

Sequence Diagram

sequenceDiagram
    participant User
    participant V3
    participant ActCache
    participant ActHandler

    User->>V3: act("click %button%", {variables: {button: "submit"}})
    V3->>ActCache: prepareContext(instruction, page, variables)
    ActCache->>ActCache: Build cache key from instruction + URL + sorted variableKeys
    ActCache-->>V3: ActCacheContext {variableKeys: ["button"], variables: {button: "submit"}}
    
    V3->>ActCache: tryReplay(context, page)
    ActCache->>ActCache: Read cache entry
    ActCache->>ActCache: Validate variableKeys match
    ActCache->>ActCache: Validate all variable values present
    
    alt Cache Hit
        ActCache->>ActHandler: takeDeterministicAction(action, page, ..., variables)
        ActHandler->>ActHandler: substituteVariablesInArguments(%button% -> "submit")
        ActHandler->>ActHandler: Execute action with resolved args
        ActHandler-->>ActCache: ActResult
        ActCache-->>V3: Cached ActResult (with placeholder args preserved)
    else Cache Miss
        V3->>ActHandler: act(instruction, variables)
        ActHandler->>ActHandler: getActionFromLLM (returns placeholders)
        ActHandler->>ActHandler: takeDeterministicAction (resolves at execution)
        ActHandler-->>V3: ActResult
        V3->>ActCache: store(context, result)
        Note over ActCache: Stores variableKeys, not values
    end
    
    V3-->>User: ActResult

greptile-apps

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

cubic-dev-ai

No issues found across 5 files

@tkattkat

allow act cache hit when variable values change

282a03c

rm unused variables param in getActionFromLLM()

590fc8b

greptile-apps bot reviewed Dec 12, 2025

View reviewed changes

seanmcguire12 marked this pull request as ready for review December 16, 2025 00:19

greptile-apps bot reviewed Dec 16, 2025

View reviewed changes

cubic-dev-ai bot reviewed Dec 16, 2025

View reviewed changes

tkattkat approved these changes Dec 16, 2025

View reviewed changes

seanmcguire12 merged commit e822f5a into main Dec 16, 2025
20 checks passed

This was referenced Dec 16, 2025

Version Packages #1414

Merged

Version Packages CloudEngineHub/stagehand#1

Open

Version Packages kenchikuliu/stagehand#1

Open

Version Packages shaneholloman/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

allow act cache hit when variable values change #1408

allow act cache hit when variable values change #1408

Uh oh!

seanmcguire12 commented Dec 12, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Dec 12, 2025 •

edited

Loading

Uh oh!

seanmcguire12 commented Dec 12, 2025

Uh oh!

greptile-apps bot commented Dec 12, 2025 •

edited

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

greptile-apps bot left a comment

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

allow act cache hit when variable values change #1408

allow act cache hit when variable values change #1408

Uh oh!

Conversation

seanmcguire12 commented Dec 12, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Uh oh!

changeset-bot bot commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

seanmcguire12 commented Dec 12, 2025

Uh oh!

greptile-apps bot commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Overview

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seanmcguire12 commented Dec 12, 2025 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Dec 12, 2025 •

edited

Loading

greptile-apps bot commented Dec 12, 2025 •

edited

Loading