why

Stagehand’s Google CUA integration was ignoring clear_before_typing for type_text_at actions in the Python client.
As a result, when Gemini tried to overwrite input fields (e.g. email search fields), text kept getting appended instead of replaced, even when the model explicitly set clear_before_typing=True.
The TypeScript client already behaves correctly; this PR brings the Python client in line with that behavior.

what changed

• Added clear_before_typing: Optional[bool] = False to [TypeAction] in [stagehand/types/agent.py] so the flag is representable in the Python action model.
• Updated [GoogleCUAClient] ([stagehand/agent/google_cua.py]) to:
  • Read clear_before_typing from Gemini type_text_at tool call args.
  • Default clear_before_typing to True when not provided, matching the TS client’s behavior.
• Updated [CUAHandler.perform_action] ([stagehand/handlers/cua_handler.py]) for action_type == "type":
  • When coordinates are provided and clear_before_typing=True, perform a triple-click at (x, y) to select all existing text, then type the new text so it replaces the selection.
  • When coordinates are provided and clear_before_typing=False, keep the existing behavior: single click then type (append).
  • When no coordinates are provided but clear_before_typing=True, fall back to Meta+a / Control+a + Backspace before typing.
• Added unit tests in [tests/unit/handlers/test_cua_handler.py] to cover:
  • Single-click vs triple-click paths based on clear_before_typing.
  • Keyboard-shortcut fallback when no coordinates.
  • press_enter_after interaction with clear_before_typing.
  • [TypeAction] model defaults and clear_before_typing field behavior.

test plan

• Unit tests:
  • pytest tests/unit/handlers/test_cua_handler.py -v
• Manual verification (optional but performed while developing the fix):
  • Run attached python test_clear_typing.py to:
    • Open a local browser with a simple HTML form.
    • Confirm that:
      • With clear_before_typing=False, text is appended to the pre-filled field.
      • With clear_before_typing=True, the field is cleared (via triple-click select-all) and only the new text remains, consistently across multiple attempts.
        test_clear_typing.py

Summary by cubic

Fixes the Python Google CUA client so type_text_at honors clear_before_typing, matching TS behavior and preventing accidental text appends. Defaults to clearing before typing for Gemini tool calls and adds reliable field clearing.

• Bug Fixes
  • Added clear_before_typing to TypeAction (default False for backward compatibility).
  • Mapped Gemini type_text_at to default clear_before_typing=True in google_cua.py.
  • In CUAHandler:
    • With coords + clear: triple-click to select all, then type.
    • With coords + no clear: single-click, then type.
    • No coords + clear: use Meta/Control+a + Backspace before typing.
  • Added unit tests for click paths, keyboard fallback, press_enter_after, and model defaults.

Written for commit 1801c1f. Summary will update automatically on new commits.