release: 3.21.0

[stainless-app]

Automated Release PR

3.21.0 (2026-05-09)

Full Changelog: v3.20.0...v3.21.0

Features

• [feat]: add ignoreSelectors to observe() (77be2c2)

Bug Fixes

• client: add missing f-string prefix in file type error message (fb40f50)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

[cubic-dev-ai]

1 issue found across 7 files

Confidence score: 2/5

• High-confidence, high-severity concern: src/stagehand/types/session_observe_params.py appears to be Stainless-generated code that was directly modified outside src/stagehand/_custom, which is a strong regression/maintenance risk.
• This lowers merge confidence because codegen runs can overwrite the new public field, causing behavior drift or lost functionality after regeneration.
• Safer path is to move the customization into the supported custom layer before merging; as written, this does not look like a stable long-term change.
• Pay close attention to src/stagehand/types/session_observe_params.py - direct edits to generated SDK code are likely to be overwritten and break expected extension patterns.

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_observe_params.py">

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

Directly modified a Stainless-generated SDK file outside src/stagehand/_custom by adding a new public field/import instead of using the allowed custom-code wrapper or hook pattern.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client as Python SDK Client
    participant API as Stagehand REST API
    participant Session as Session Resource
    participant Observe as observe() Endpoint
    participant LLM as LLM/Model Provider

    Note over Client,LLM: observe() with ignoreSelectors

    Client->>Session: sessions.observe(instruction, options)
    Session->>Session: Validate & build params
    Note over Session: NEW: include ignore_selectors from options

    Session->>Observe: POST /sessions/observe
    Note over Session,Observe: body includes: ignoreSelectors: ["nav", ".cookie-banner"]

    alt ignoreSelectors provided
        Observe->>LLM: analyze(page, instruction, ignoreSelectors)
        LLM->>LLM: Skip elements matching selectors
        LLM-->>Observe: Filtered element observations
    else no ignoreSelectors
        Observe->>LLM: analyze(page, instruction)
        LLM-->>Observe: All relevant element observations
    end

    Observe-->>Session: Observation results (filtered)
    Session-->>Client: Return observable elements
    Client->>Client: Process filtered results

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

P1: Custom agent: Prevent direct modifications to stainless codegen'd code outside of src/stagehand/_custom

Directly modified a Stainless-generated SDK file outside src/stagehand/_custom by adding a new public field/import instead of using the allowed custom-code wrapper or hook pattern.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/stagehand/types/session_observe_params.py, line 8:

<comment>Directly modified a Stainless-generated SDK file outside src/stagehand/_custom by adding a new public field/import instead of using the allowed custom-code wrapper or hook pattern.</comment>

<file context>
@@ -5,6 +5,7 @@
 from typing import Dict, Union, Optional
 from typing_extensions import Literal, Required, Annotated, TypeAlias, TypedDict
 
+from .._types import SequenceNotStr
 from .._utils import PropertyInfo
 from .model_config_param import ModelConfigParam
</file context>

[stainless-app]

🧪 Testing

To try out this version of the SDK:

pip install 'https://pkg.stainless.com/s/stagehand-python/fb40f50c2fb3337be84a3f973b8a27a8f53fbfae/stagehand-3.20.0-py3-none-any.whl'

Expires at: Mon, 08 Jun 2026 02:04:14 GMT
Updated at: Sat, 09 May 2026 02:04:14 GMT