fix: add variable substitution to keys step during cache replay

[a7med3liamin]

• Check the documentation for relevant information
• Search existing issues to avoid duplicates

Fixes #1776

Problem

The keys tool has no variable substitution in either the live execution or cache replay paths. When the agent uses %variableName% tokens with the keys tool, the literal token string gets typed instead of the resolved value.

Fix

This PR combines two fixes into one:

1. Live execution (original fix by @trillville from #1777)

• Accept variables parameter in keysTool (matching typeTool)
• Call substituteVariables() before page.type() in the method === "type" branch
• Pass variables to keysTool in createAgentTools
• Update schema description to advertise available variables to the LLM
• Return original token in result to avoid exposing sensitive values to LLM

2. Cache replay (new fix)

• Import substituteVariables in AgentCache.ts
• Pass variables through to replayAgentKeysStep
• Call substituteVariables(text, variables) before page.type() in the replay path

Without fix #2, cached keys steps with method="type" replay by typing literal %variableName% tokens even when variables are provided, since replayAgentKeysStep had no access to the variables map.

Credit

The live execution fix (part 1) is from @trillville's work in #1777/#1813. We merged it here with the cache replay fix per @pirate's request to consolidate into a single PR.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[changeset-bot]

🦋 Changeset detected

Latest commit: 2149aa2

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

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	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

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Cache as AgentCache
    participant Vars as variables.js
    participant Ctx as V3Context
    participant Page as Playwright Page
    
    Note over Cache,Page: Replay cached "keys" step (method: "type")

    Cache->>Cache: Identify "keys" step type
    Cache->>Cache: CHANGED: replayAgentKeysStep(step, ctx, variables)
    
    Cache->>Ctx: awaitActivePage()
    Ctx-->>Cache: page instance

    alt method === "type"
        Cache->>Vars: NEW: substituteVariables(text, variables)
        Vars-->>Cache: resolvedText (e.g. "2023-01-01")
        
        loop times (default 1)
            Cache->>Page: CHANGED: page.type(resolvedText, { delay: 100 })
        end
    else method === "press"
        loop times (default 1)
            Cache->>Page: page.keyboard.press(keys)
        end
    end

    Cache-->>Cache: Return step completion

Loading

[pirate]

sorry for the trouble can you actually merge your two PRs into a single unified pr / this PR. then I will claim it.

Our github workflow is a little clunky right now because we have to "claim" external contributor PRs in order to run CI, so it's easier to do fewer PRs that have more changes all in one.

[a7med3liamin]

No worries at all @pirate.

Done, merged @trillville's live execution fix from #1777 into this PR alongside the cache replay fix.

[github-actions]

This PR was approved by @pirate and mirrored to #1983. All further discussion should happen on that PR.

[github-actions]

The mirrored PR #1983 has been merged into main. This original external contributor PR will stay closed as completed.