feat: add use_touch and release 3.23.0

[miguelg719]

Summary

• expose use_touch on synchronous and asynchronous session start methods
• serialize the Python option as the server-side useTouch field
• forward the option through the custom bound-session wrappers
• bump the Python SDK and release metadata to 3.23.0

The server-side change was released from browserbase/stagehand#2711.

Verification

• uv run pytest tests/test_sessions_create_helper.py (2 passed)
• ./scripts/lint
• uv build (produced the 3.23.0 wheel and source distribution)

Release

After merging, publish a GitHub release tagged v3.23.0; the Publish PyPI workflow will publish the artifacts.

[cubic-dev-ai]

1 issue found across 5 files

Confidence score: 3/5

• src/stagehand/types/session_start_params.py directly modifies Stainless-generated code outside src/stagehand/_custom, so regeneration may overwrite the change or create drift from the supported customization path; move the customization into src/stagehand/_custom before merging.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/stagehand/types/session_start_params.py">

<violation number="1" location="src/stagehand/types/session_start_params.py:37">
P1: Custom agent: **Prevent direct modifications to stainless codegen'd code outside of src/stagehand/_custom**

This directly modifies Stainless-generated code outside `src/stagehand/_custom/` without the required custom-code wrapper. Move the type change into the permitted custom/upstream OpenAPI generation path and regenerate the client instead of adding `use_touch` here.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant App as Python Application
    participant SyncSDK as Stagehand (Sync)
    participant AsyncSDK as AsyncStagehand (Async)
    participant SessionRes as sessions.start()
    participant CustomWrap as _sync_start / _async_start
    participant Client as HTTP Client
    participant Server as Stagehand API Server

    Note over App,Server: NEW: use_touch session option flow

    alt Sync path
        App->>SyncSDK: sessions.start(model_name, use_touch=True)
        SyncSDK->>CustomWrap: _sync_start(model_name, use_touch=True)
    else Async path
        App->>AsyncSDK: sessions.start(model_name, use_touch=True)
        AsyncSDK->>CustomWrap: _async_start(model_name, use_touch=True)
    end

    CustomWrap->>CustomWrap: Build params dict with<br/>use_touch field
    CustomWrap->>SessionRes: start(model_name=..., use_touch=True, ...)

    Note over SessionRes: Serializes use_touch as<br/>"useTouch" (alias in SessionStartParams)

    SessionRes->>Client: POST /v1/sessions/start<br/>JSON body includes "useTouch": true
    Client->>Server: API request with useTouch flag

    alt Success (200)
        Server-->>Client: BoundSession response
        Client-->>SessionRes: Session object
        SessionRes-->>CustomWrap: Bound session
        CustomWrap-->>SyncSDK/AsyncSDK: Bound session
        SyncSDK/AsyncSDK-->>App: session (with navigate, act, etc.)
    else Failure (4xx/5xx)
        Server-->>Client: Error response
        Client-->>SessionRes: Raise error
        SessionRes-->>CustomWrap: Exception
        CustomWrap-->>SyncSDK/AsyncSDK: Exception
        SyncSDK/AsyncSDK-->>App: Exception raised
    end

Loading

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

Re-trigger cubic</sub>