feat: add Valkey cache configuration to client and session start

ED
5mo ago
+675-0

Summary

Adds first-class Valkey cache configuration across the Python SDK. Users can now pass connection details (host, port, TLS, auth, TTL, key prefix) either at the client level (propagated as env vars to the local SEA server) or per-session via a valkey_cache param on sessions.start().

Note: This PR depends on the Valkey implementation (https://github.com/browserbase/stagehand/pull/2264) being merged first in stagehand.

Issue

N/A

Changes

  • src/stagehand/_client.py - Added 7 Valkey-related instance variables and constructor/with_options params to both Stagehand and AsyncStagehand
  • src/stagehand/_custom/sea_server.py - Extended SeaServerConfig, _HasLocalModeState protocol, LocalModeKwargs, _build_process_env (env var propagation), configure_client_base_url, and copy_local_mode_kwargs with Valkey fields. Also warns when credentials are sent without TLS on non-local hosts, and when client-level Valkey params are used in remote mode.
  • src/stagehand/_custom/session.py - Threaded valkey_cache param through _sync_start and _async_start
  • src/stagehand/resources/sessions.py - Added valkey_cache param to SessionsResource.start() and AsyncSessionsResource.start() with docstrings and body serialization
  • src/stagehand/types/session_start_params.py - New ValkeyCacheOptions TypedDict (host required, port/tls/password/username/cache_ttl/key_prefix optional) with camelCase aliases, plus valkey_cache field on SessionStartParams
  • src/stagehand/types/__init__.py - Re-export ValkeyCacheOptions
  • tests/api_resources/test_sessions.py - Added valkey_cache dict to existing sync/async session start tests
  • tests/test_valkey_cache.py - New test file covering SeaServerConfig defaults, env var propagation, client constructor params, with_options preserve/override, TypedDict shape, signature inspection, falsy-but-valid values (port=0, ttl=0), and empty string edge cases

Tests

tests/test_valkey_cache.py covers the full surface: dataclass fields, env var generation, client param acceptance, with_options behavior, type exports, method signatures, edge cases for falsy values, and the remote-mode warning. Existing test_sessions.py tests updated to exercise the new param in the session start call.

Blockers / Future work

  • Depends on the Valkey caching implementation landing in the upstream stagehand repo first

Additional context

The local SEA binary and server receives Valkey config as environment variables (VALKEY_HOST, VALKEY_PORT, VALKEY_TLS, VALKEY_PASSWORD, VALKEY_USERNAME, CACHE_TTL, VALKEY_KEY_PREFIX). For remote mode, the valkeyCache object is sent in the session start request body. No new runtime dependencies added.

Summary by cubic

Adds first-class Valkey cache support to the Python SDK. Configure Valkey at the client level (local SEA via env vars) or per session with valkey_cache for remote requests, with safety warnings and updated docs/tests.

  • New Features

    • Client: new params valkey_host, valkey_port, valkey_tls, valkey_password, valkey_username, valkey_cache_ttl, valkey_key_prefix; propagated to the local SEA as VALKEY_* and CACHE_TTL.
    • Sessions: sessions.start() accepts valkey_cache (host required; port/tls/password/username/cache_ttl/key_prefix optional), serialized with camelCase keys and documented in the method docstring.
    • Types: added and re-exported ValkeyCacheOptions in stagehand.types.
    • Safety: warns if client-level Valkey params are set in remote mode (ignored) and if a password is used without TLS on non-local hosts.

  • Migration

    • Local mode: pass Valkey params on Stagehand/AsyncStagehand (or via .with_options()); the SEA binary must be built with @valkey/valkey-glide for caching to activate.
    • Remote mode: pass valkey_cache to sessions.start().
    • Notes: port=0 and cache_ttl=0 are allowed; empty strings are sent as provided; prefer TLS when sending credentials.
    • Requires the Valkey caching implementation in the upstream stagehand server to be available.