improve cua key mapping logic

[tkattkat]

why

Currently we have a handful of keys that fail to be used, and redundant logic around key handling. It is now consolidated to one location, and properly handles the failing keys
part of STG-587

what changed

consolidated key handling for CUA agents to one util

test plan

tested locally

[changeset-bot]

🦋 Changeset detected

Latest commit: 3319506

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

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

[greptile-apps]

Greptile Summary

This PR consolidates key mapping logic for Computer Use Agent (CUA) interactions by extracting duplicate key handling code into a centralized utility function. The changes include:

1. New centralized utility: Creates lib/agent/utils/cuaKeyMapping.ts with a mapKeyToPlaywright() function that provides comprehensive key mapping from various formats (Anthropic CUA, OpenAI CUA) to Playwright-compatible key names

2. Code deduplication: Removes ~40-45 lines of inline key mapping logic from both agentHandler.ts and AnthropicCUAClient.ts, replacing hardcoded if-else chains with calls to the centralized utility

3. File reorganization: Moves imageCompressionUtils.ts to lib/agent/utils/imageCompression.ts to group utilities together in a dedicated utils directory

4. Enhanced key support: The new utility provides more comprehensive key mapping including cross-platform variations (e.g., macOS 'COMMAND' vs Windows 'CTRL', 'OPTION' -> 'Alt') and multiple naming conventions for the same keys

The consolidation improves maintainability by centralizing key mapping logic that was previously scattered across multiple files with slightly different implementations. This ensures consistent key handling across all CUA providers and makes it easier to add support for new key mappings in the future. The change fits into the broader Stagehand architecture by creating reusable utilities that can be shared between different agent client implementations (Anthropic, OpenAI, etc.).

Confidence score: 5/5

• This PR is very safe to merge - it's a straightforward refactoring that consolidates duplicate code without changing functionality
• The changes are well-structured, maintain backward compatibility, and improve code organization through proper utility extraction
• All files look correct with proper imports and the key mapping logic appears comprehensive and well-tested

_{4 files reviewed, no comments}

_{Edit Code Review Bot Settings | Greptile}

[stagehand-parity-bot]

🔄 Feature Parity Issue Created

An issue has been automatically created in the Python SDK repository to track parity implementation:
browserbase/stagehand-python#164