[Claimed browserbase#1978] fix: add variable substitution to keys step during cache replay (browserbase#1983)

Mirrored from external contributor PR browserbase#1978 after approval by @pirate.

Original author: @a7med3liamin
Original PR: browserbase#1978
Approved source head SHA: `2149aa265a04dc37154d5a84411f3ab4d1045897`

@a7med3liamin, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.

## Original description
- [x] Check the [documentation](https://docs.stagehand.dev/) for
relevant information
- [x] Search existing
[issues](https://github.com/browserbase/stagehand/issues) to avoid
duplicates

Fixes browserbase#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 browserbase#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
browserbase#1777/browserbase#1813. We merged it here with the cache replay fix per @pirate's
request to consolidate into a single PR.

<!-- external-contributor-pr:owned source-pr=1978
source-sha=2149aa265a04dc37154d5a84411f3ab4d1045897 claimer=pirate -->

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add variable substitution to the `keys` tool for both live execution and
cache replay so `%variableName%` tokens are resolved before typing. This
fixes cases where literal tokens were typed and brings parity with the
`type` tool.

- **Bug Fixes**
- Pass `variables` into `keys` and call `substituteVariables()` before
`page.type()`; update the input schema to list available variables.
- In cache replay, forward `variables` to `replayAgentKeysStep` and
substitute before typing to avoid replaying literal tokens.
- Record and return the original tokenized value (not the resolved
value) to avoid leaking sensitive data.

<sup>Written for commit abb3905.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1983">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Ahmed Ali <a7med3liamin@gmail.com>
Co-authored-by: trillville <trillville@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>

Author: 5 people

.changeset/keys-cache-replay-variables.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add variable substitution to the keys tool in both live execution and cache replay paths. When keys steps with `method="type"` contain `%variableName%` tokens, they are now resolved against the provided variables. This brings the keys tool to parity with the type tool's variable handling.

packages/core/lib/v3/agent/tools/index.ts

@@ -168,7 +168,7 @@ export function createAgentTools(v3: V3, options?: V3AgentToolOptions) {
     fillForm: fillFormTool(v3, executionModel, variables, toolTimeout),
     fillFormVision: fillFormVisionTool(v3, provider, variables),
     goto: gotoTool(v3),
-    keys: keysTool(v3),
+    keys: keysTool(v3, variables),
     navback: navBackTool(v3),
     screenshot: screenshotTool(v3),
     scroll: mode === "hybrid" ? scrollVisionTool(v3, provider) : scrollTool(v3),

packages/core/lib/v3/agent/tools/keys.ts

@@ -1,21 +1,24 @@
 import { tool } from "ai";
 import { z } from "zod";
 import type { V3 } from "../../v3.js";
+import type { Variables } from "../../types/public/agent.js";
+import { substituteVariables } from "../utils/variables.js";
 
-export const keysTool = (v3: V3) =>
-  tool({
+export const keysTool = (v3: V3, variables?: Variables) => {
+  const hasVariables = variables && Object.keys(variables).length > 0;
+  const valueDescription = hasVariables
+    ? `The text to type, or the key/combo to press (Enter, Tab, Cmd+A). Use %variableName% to substitute a variable value. Available: ${Object.keys(variables).join(", ")}`
+    : "The text to type, or the key/combo to press (Enter, Tab, Cmd+A)";
+
+  return tool({
     description: `Send keyboard input to the page without targeting a specific element. Unlike the type tool which clicks then types into coordinates, this sends keystrokes directly to wherever focus currently is.
 
 Use method="type" to enter text into the currently focused element. Preferred when: input is already focused, text needs to flow across multiple fields (e.g., verification codes)
 
 Use method="press" for navigation keys (Enter, Tab, Escape, Backspace, arrows) and keyboard shortcuts (Cmd+A, Ctrl+C, Shift+Tab).`,
     inputSchema: z.object({
       method: z.enum(["press", "type"]),
-      value: z
-        .string()
-        .describe(
-          "The text to type, or the key/combo to press (Enter, Tab, Cmd+A)",
-        ),
+      value: z.string().describe(valueDescription),
       repeat: z.number().optional(),
     }),
     execute: async ({ method, value, repeat }) => {
@@ -36,14 +39,17 @@ Use method="press" for navigation keys (Enter, Tab, Escape, Backspace, arrows) a
         const times = Math.max(1, repeat ?? 1);
 
         if (method === "type") {
+          // Substitute any %variableName% tokens in the value
+          const actualValue = substituteVariables(value, variables);
           for (let i = 0; i < times; i++) {
-            await page.type(value, { delay: 100 });
+            await page.type(actualValue, { delay: 100 });
           }
           v3.recordAgentReplayStep({
             type: "keys",
             instruction: `type "${value}"`,
             playwrightArguments: { method, text: value, times },
           });
+          // Return original value (with %variableName% tokens) to avoid exposing sensitive values to LLM
           return { success: true, method, value, times };
         }
 
@@ -65,3 +71,4 @@ Use method="press" for navigation keys (Enter, Tab, Escape, Backspace, arrows) a
       }
     },
   });
+};

packages/core/lib/v3/cache/AgentCache.ts

@@ -34,6 +34,7 @@ import {
   safeGetPageUrl,
   waitForCachedSelector,
 } from "./utils.js";
+import { substituteVariables } from "../agent/utils/variables.js";
 
 const SENSITIVE_CONFIG_KEYS = new Set(["apikey", "api_key", "api-key"]);
 
@@ -660,7 +661,11 @@ export class AgentCache {
         await this.replayAgentNavBackStep(step as AgentReplayNavBackStep, ctx);
         return step;
       case "keys":
-        await this.replayAgentKeysStep(step as AgentReplayKeysStep, ctx);
+        await this.replayAgentKeysStep(
+          step as AgentReplayKeysStep,
+          ctx,
+          variables,
+        );
         return step;
       case "done":
       case "extract":
@@ -811,14 +816,16 @@ export class AgentCache {
   private async replayAgentKeysStep(
     step: AgentReplayKeysStep,
     ctx: V3Context,
+    variables?: Record<string, string>,
   ): Promise<void> {
     const page = await ctx.awaitActivePage();
     const { method, text, keys, times } = step.playwrightArguments;
     const repeatCount = Math.max(1, times ?? 1);
 
     if (method === "type" && text) {
+      const resolvedText = substituteVariables(text, variables);
       for (let i = 0; i < repeatCount; i++) {
-        await page.type(text, { delay: 100 });
+        await page.type(resolvedText, { delay: 100 });
       }
     } else if (method === "press" && keys) {
       for (let i = 0; i < repeatCount; i++) {