feat: add Valkey cache configuration to client and session start

[edlng]

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 (browserbase/stagehand#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.

^{Written for commit e4bbc4d. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 8 files

Confidence score: 3/5

• src/stagehand/types/__init__.py appears to add a re-export directly in stainless-generated code, which can be overwritten on the next codegen run and silently drop ValkeyCacheOptions from the public surface, causing import breakages after regeneration. Move this change into src/stagehand/_custom (with the required custom-code annotation/path) before merging so the export is preserved across codegen updates.

Architecture diagram

sequenceDiagram
    participant User as User Code
    participant Client as Stagehand/AsyncStagehand Client
    participant SEA as SeaServerManager
    participant Sessions as Sessions Resource
    participant Backend as Remote API Backend
    participant Valkey as Valkey Cache

    Note over User,Valkey: NEW: Valkey cache configuration flow

    User->>Client: Stagehand(valkey_host="...", valkey_port=...)
    Client->>Client: Store Valkey params as instance vars
    alt remote mode (server != "local")
        Client->>Client: Warn: client-level Valkey params ignored in remote mode
        Note over Client: User should pass valkey_cache to sessions.start()
    end

    alt local mode (server == "local")
        Client->>SEA: configure_client_base_url(server="local")
        SEA->>SEA: Build SeaServerConfig with Valkey fields
        SEA->>SEA: _build_process_env()
        SEA->>SEA: Set env vars VALKEY_HOST, VALKEY_PORT, VALKEY_TLS, VALKEY_PASSWORD, VALKEY_USERNAME, CACHE_TTL, VALKEY_KEY_PREFIX
        alt password set without TLS on non-local host
            SEA->>User: Warning: "Credentials sent in cleartext"
        end
        SEA->>Valkey: Connect to Valkey cache via env vars
        Note over SEA: Requires @valkey/valkey-glide addon
    end

    User->>Client: with_options(valkey_host="new.host", valkey_cache_ttl=900)
    Client->>Client: Copy instance with overridden Valkey params

    User->>Sessions: sessions.start(valkey_cache={"host": "...", "port": 6380, ...})
    Sessions->>Backend: POST /sessions/start with valkeyCache (camelCase)
    Note over Sessions,Backend: Remote mode: Valkey config sent in request body
    Backend-->>Sessions: Session started with Valkey cache
    Sessions-->>User: Session object

    alt local mode session start
        User->>Client: sessions.start() (no valkey_cache)
        Client->>SEA: Use existing Valkey env vars
        SEA-->>Client: Session with cache enabled
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>