diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5f78a6a..c7bc99a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,12 +1,14 @@ name: CI on: push: - branches-ignore: - - 'generated' - - 'codegen/**' - - 'integrated/**' - - 'stl-preview-head/**' - - 'stl-preview-base/**' + branches: + - '**' + - '!integrated/**' + - '!stl-preview-head/**' + - '!stl-preview-base/**' + - '!generated' + - '!codegen/**' + - 'codegen/stl/**' pull_request: branches-ignore: - 'stl-preview-head/**' diff --git a/.release-please-manifest.json b/.release-please-manifest.json index fe87cd9..cc51f6f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.43.0" + ".": "0.44.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index ae22a71..ad84265 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 103 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-bda5e58fa0bbd08761f27a1e0edbc602c44141ac9483bf6c96d52b7f4d10d9a7.yml -openapi_spec_hash: 10833b36358e8cda023e5bb0abeab0ba +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-17e50cf93d8052ff655c160fc0f156621d9029b041526d4e2e3317b13f80822f.yml +openapi_spec_hash: f7dadc8d93e77983936eb18a8080ce15 config_hash: cff4d43372b6fa66b64e2d4150f6aa76 diff --git a/CHANGELOG.md b/CHANGELOG.md index 3cf8970..97a948e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,28 @@ # Changelog +## 0.44.0 (2026-03-17) + +Full Changelog: [v0.43.0...v0.44.0](https://github.com/kernel/kernel-python-sdk/compare/v0.43.0...v0.44.0) + +### Features + +* Add GPU viewport presets and GPU encoder defaults ([0735b45](https://github.com/kernel/kernel-python-sdk/commit/0735b45fc92950cef3afea92a879712ea0ebdf0f)) +* Adds description to OAS spec for docs about delta_x, delta_y ([9841aac](https://github.com/kernel/kernel-python-sdk/commit/9841aac21588beb0c6a22baf5c5b0bf8e8cdd024)) +* Drop headless GPU support and disable pooling ([cda8f94](https://github.com/kernel/kernel-python-sdk/commit/cda8f94f6cebabc3b3b6f95aff765816255a9270)) +* expose smooth drag mouse movement via public API ([c6f6862](https://github.com/kernel/kernel-python-sdk/commit/c6f6862d03620bb218a99c85431e384c5c8e5e4c)) +* Rename hardware acceleration UI/docs wording to GPU acceleration ([9ee4d0c](https://github.com/kernel/kernel-python-sdk/commit/9ee4d0c080da7f649a3bde63640593f33d5d0f6b)) + + +### Bug Fixes + +* **deps:** bump minimum typing-extensions version ([fd55947](https://github.com/kernel/kernel-python-sdk/commit/fd55947f1776b43cca804622d0c771ebe99ead60)) +* **pydantic:** do not pass `by_alias` unless set ([a815a82](https://github.com/kernel/kernel-python-sdk/commit/a815a8237cce2098b2f5d6a8ad5def400d418fbb)) + + +### Chores + +* **internal:** tweak CI branches ([8781c7d](https://github.com/kernel/kernel-python-sdk/commit/8781c7d9aa8759e487e5d86cbb82bfb7eb3d314e)) + ## 0.43.0 (2026-03-10) Full Changelog: [v0.42.1...v0.43.0](https://github.com/kernel/kernel-python-sdk/compare/v0.42.1...v0.43.0) diff --git a/pyproject.toml b/pyproject.toml index 021d31e..62ca833 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "kernel" -version = "0.43.0" +version = "0.44.0" description = "The official Python library for the kernel API" dynamic = ["readme"] license = "Apache-2.0" @@ -11,7 +11,7 @@ authors = [ dependencies = [ "httpx>=0.23.0, <1", "pydantic>=1.9.0, <3", - "typing-extensions>=4.10, <5", + "typing-extensions>=4.14, <5", "anyio>=3.5.0, <5", "distro>=1.7.0, <2", "sniffio", diff --git a/src/kernel/_compat.py b/src/kernel/_compat.py index 786ff42..e6690a4 100644 --- a/src/kernel/_compat.py +++ b/src/kernel/_compat.py @@ -2,7 +2,7 @@ from typing import TYPE_CHECKING, Any, Union, Generic, TypeVar, Callable, cast, overload from datetime import date, datetime -from typing_extensions import Self, Literal +from typing_extensions import Self, Literal, TypedDict import pydantic from pydantic.fields import FieldInfo @@ -131,6 +131,10 @@ def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str: return model.model_dump_json(indent=indent) +class _ModelDumpKwargs(TypedDict, total=False): + by_alias: bool + + def model_dump( model: pydantic.BaseModel, *, @@ -142,6 +146,9 @@ def model_dump( by_alias: bool | None = None, ) -> dict[str, Any]: if (not PYDANTIC_V1) or hasattr(model, "model_dump"): + kwargs: _ModelDumpKwargs = {} + if by_alias is not None: + kwargs["by_alias"] = by_alias return model.model_dump( mode=mode, exclude=exclude, @@ -149,7 +156,7 @@ def model_dump( exclude_defaults=exclude_defaults, # warnings are not supported in Pydantic v1 warnings=True if PYDANTIC_V1 else warnings, - by_alias=by_alias, + **kwargs, ) return cast( "dict[str, Any]", diff --git a/src/kernel/_version.py b/src/kernel/_version.py index 068f52c..2c4ce41 100644 --- a/src/kernel/_version.py +++ b/src/kernel/_version.py @@ -1,4 +1,4 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. __title__ = "kernel" -__version__ = "0.43.0" # x-release-please-version +__version__ = "0.44.0" # x-release-please-version diff --git a/src/kernel/resources/browser_pools.py b/src/kernel/resources/browser_pools.py index a5b6e59..ea45cd1 100644 --- a/src/kernel/resources/browser_pools.py +++ b/src/kernel/resources/browser_pools.py @@ -110,9 +110,13 @@ def create( are destroyed. Defaults to 600 seconds if not specified viewport: Initial browser window size in pixels with optional refresh rate. If omitted, - image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted, - but the following configurations are known-good and fully tested: 2560x1440@10, - 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep @@ -242,9 +246,13 @@ def update( are destroyed. Defaults to 600 seconds if not specified viewport: Initial browser window size in pixels with optional refresh rate. If omitted, - image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted, - but the following configurations are known-good and fully tested: 2560x1440@10, - 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep @@ -550,9 +558,13 @@ async def create( are destroyed. Defaults to 600 seconds if not specified viewport: Initial browser window size in pixels with optional refresh rate. If omitted, - image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted, - but the following configurations are known-good and fully tested: 2560x1440@10, - 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep @@ -682,9 +694,13 @@ async def update( are destroyed. Defaults to 600 seconds if not specified viewport: Initial browser window size in pixels with optional refresh rate. If omitted, - image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted, - but the following configurations are known-good and fully tested: 2560x1440@10, - 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep diff --git a/src/kernel/resources/browsers/browsers.py b/src/kernel/resources/browsers/browsers.py index 235da23..1d1ce22 100644 --- a/src/kernel/resources/browsers/browsers.py +++ b/src/kernel/resources/browsers/browsers.py @@ -166,8 +166,8 @@ def create( Args: extensions: List of browser extensions to load into the session. Provide each by id or name. - gpu: If true, launches a hardware-accelerated browser with GPU rendering. Requires - Start-Up or Enterprise plan. + gpu: If true, enables GPU acceleration for the browser session. Requires Start-Up or + Enterprise plan and headless=false. headless: If true, launches the browser using a headless image (no VNC/GUI). Defaults to false. @@ -196,9 +196,13 @@ def create( see is +/- 5 seconds around the specified value. viewport: Initial browser window size in pixels with optional refresh rate. If omitted, - image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted, - but the following configurations are known-good and fully tested: 2560x1440@10, - 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep @@ -593,8 +597,8 @@ async def create( Args: extensions: List of browser extensions to load into the session. Provide each by id or name. - gpu: If true, launches a hardware-accelerated browser with GPU rendering. Requires - Start-Up or Enterprise plan. + gpu: If true, enables GPU acceleration for the browser session. Requires Start-Up or + Enterprise plan and headless=false. headless: If true, launches the browser using a headless image (no VNC/GUI). Defaults to false. @@ -623,9 +627,13 @@ async def create( see is +/- 5 seconds around the specified value. viewport: Initial browser window size in pixels with optional refresh rate. If omitted, - image defaults apply (1920x1080@25). Arbitrary viewport dimensions are accepted, - but the following configurations are known-good and fully tested: 2560x1440@10, - 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep diff --git a/src/kernel/resources/browsers/computer.py b/src/kernel/resources/browsers/computer.py index 1357c1e..116a703 100644 --- a/src/kernel/resources/browsers/computer.py +++ b/src/kernel/resources/browsers/computer.py @@ -213,7 +213,9 @@ def drag_mouse( path: Iterable[Iterable[int]], button: Literal["left", "middle", "right"] | Omit = omit, delay: int | Omit = omit, + duration_ms: int | Omit = omit, hold_keys: SequenceNotStr[str] | Omit = omit, + smooth: bool | Omit = omit, step_delay_ms: int | Omit = omit, steps_per_segment: int | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. @@ -234,8 +236,14 @@ def drag_mouse( delay: Delay in milliseconds between button down and starting to move along the path. + duration_ms: Target total duration in milliseconds for the entire drag movement when + smooth=true. Omit for automatic timing based on total path length. + hold_keys: Modifier keys to hold during the drag + smooth: Use human-like Bezier curves between path waypoints instead of linear + interpolation. When true, steps_per_segment and step_delay_ms are ignored. + step_delay_ms: Delay in milliseconds between relative steps while dragging (not the initial delay). @@ -259,7 +267,9 @@ def drag_mouse( "path": path, "button": button, "delay": delay, + "duration_ms": duration_ms, "hold_keys": hold_keys, + "smooth": smooth, "step_delay_ms": step_delay_ms, "steps_per_segment": steps_per_segment, }, @@ -476,9 +486,11 @@ def scroll( y: Y coordinate at which to perform the scroll - delta_x: Horizontal scroll amount. Positive scrolls right, negative scrolls left. + delta_x: Horizontal scroll amount in xdotool "wheel units." Positive scrolls right, + negative scrolls left. - delta_y: Vertical scroll amount. Positive scrolls down, negative scrolls up. + delta_y: Vertical scroll amount in xdotool "wheel units." Positive scrolls down, negative + scrolls up. hold_keys: Modifier keys to hold during the scroll @@ -804,7 +816,9 @@ async def drag_mouse( path: Iterable[Iterable[int]], button: Literal["left", "middle", "right"] | Omit = omit, delay: int | Omit = omit, + duration_ms: int | Omit = omit, hold_keys: SequenceNotStr[str] | Omit = omit, + smooth: bool | Omit = omit, step_delay_ms: int | Omit = omit, steps_per_segment: int | Omit = omit, # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs. @@ -825,8 +839,14 @@ async def drag_mouse( delay: Delay in milliseconds between button down and starting to move along the path. + duration_ms: Target total duration in milliseconds for the entire drag movement when + smooth=true. Omit for automatic timing based on total path length. + hold_keys: Modifier keys to hold during the drag + smooth: Use human-like Bezier curves between path waypoints instead of linear + interpolation. When true, steps_per_segment and step_delay_ms are ignored. + step_delay_ms: Delay in milliseconds between relative steps while dragging (not the initial delay). @@ -850,7 +870,9 @@ async def drag_mouse( "path": path, "button": button, "delay": delay, + "duration_ms": duration_ms, "hold_keys": hold_keys, + "smooth": smooth, "step_delay_ms": step_delay_ms, "steps_per_segment": steps_per_segment, }, @@ -1067,9 +1089,11 @@ async def scroll( y: Y coordinate at which to perform the scroll - delta_x: Horizontal scroll amount. Positive scrolls right, negative scrolls left. + delta_x: Horizontal scroll amount in xdotool "wheel units." Positive scrolls right, + negative scrolls left. - delta_y: Vertical scroll amount. Positive scrolls down, negative scrolls up. + delta_y: Vertical scroll amount in xdotool "wheel units." Positive scrolls down, negative + scrolls up. hold_keys: Modifier keys to hold during the scroll diff --git a/src/kernel/types/browser_create_params.py b/src/kernel/types/browser_create_params.py index 6df2463..2827b1d 100644 --- a/src/kernel/types/browser_create_params.py +++ b/src/kernel/types/browser_create_params.py @@ -21,9 +21,9 @@ class BrowserCreateParams(TypedDict, total=False): """ gpu: bool - """If true, launches a hardware-accelerated browser with GPU rendering. + """If true, enables GPU acceleration for the browser session. - Requires Start-Up or Enterprise plan. + Requires Start-Up or Enterprise plan and headless=false. """ headless: bool @@ -73,13 +73,17 @@ class BrowserCreateParams(TypedDict, total=False): """ viewport: BrowserViewport - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_create_response.py b/src/kernel/types/browser_create_response.py index bbfd9a2..d59a3d0 100644 --- a/src/kernel/types/browser_create_response.py +++ b/src/kernel/types/browser_create_response.py @@ -45,7 +45,10 @@ class BrowserCreateResponse(BaseModel): """When the browser session was soft-deleted. Only present for deleted sessions.""" gpu: Optional[bool] = None - """Whether the browser session has hardware-accelerated GPU rendering.""" + """ + Whether GPU acceleration is enabled for the browser session (only supported for + headful sessions). + """ kiosk_mode: Optional[bool] = None """Whether the browser session is running in kiosk mode.""" @@ -66,13 +69,17 @@ class BrowserCreateResponse(BaseModel): """Session usage metrics.""" viewport: Optional[BrowserViewport] = None - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_list_response.py b/src/kernel/types/browser_list_response.py index 915df11..708caa9 100644 --- a/src/kernel/types/browser_list_response.py +++ b/src/kernel/types/browser_list_response.py @@ -45,7 +45,10 @@ class BrowserListResponse(BaseModel): """When the browser session was soft-deleted. Only present for deleted sessions.""" gpu: Optional[bool] = None - """Whether the browser session has hardware-accelerated GPU rendering.""" + """ + Whether GPU acceleration is enabled for the browser session (only supported for + headful sessions). + """ kiosk_mode: Optional[bool] = None """Whether the browser session is running in kiosk mode.""" @@ -66,13 +69,17 @@ class BrowserListResponse(BaseModel): """Session usage metrics.""" viewport: Optional[BrowserViewport] = None - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_pool.py b/src/kernel/types/browser_pool.py index fc4e0f1..c6286ac 100644 --- a/src/kernel/types/browser_pool.py +++ b/src/kernel/types/browser_pool.py @@ -68,15 +68,19 @@ class BrowserPoolConfig(BaseModel): """ viewport: Optional[BrowserViewport] = None - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_pool_acquire_response.py b/src/kernel/types/browser_pool_acquire_response.py index 373274c..5ab52b5 100644 --- a/src/kernel/types/browser_pool_acquire_response.py +++ b/src/kernel/types/browser_pool_acquire_response.py @@ -45,7 +45,10 @@ class BrowserPoolAcquireResponse(BaseModel): """When the browser session was soft-deleted. Only present for deleted sessions.""" gpu: Optional[bool] = None - """Whether the browser session has hardware-accelerated GPU rendering.""" + """ + Whether GPU acceleration is enabled for the browser session (only supported for + headful sessions). + """ kiosk_mode: Optional[bool] = None """Whether the browser session is running in kiosk mode.""" @@ -66,13 +69,17 @@ class BrowserPoolAcquireResponse(BaseModel): """Session usage metrics.""" viewport: Optional[BrowserViewport] = None - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_pool_create_params.py b/src/kernel/types/browser_pool_create_params.py index 78268a5..63ef712 100644 --- a/src/kernel/types/browser_pool_create_params.py +++ b/src/kernel/types/browser_pool_create_params.py @@ -67,13 +67,17 @@ class BrowserPoolCreateParams(TypedDict, total=False): """ viewport: BrowserViewport - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_pool_update_params.py b/src/kernel/types/browser_pool_update_params.py index 74b76a6..d1f003b 100644 --- a/src/kernel/types/browser_pool_update_params.py +++ b/src/kernel/types/browser_pool_update_params.py @@ -73,13 +73,17 @@ class BrowserPoolUpdateParams(TypedDict, total=False): """ viewport: BrowserViewport - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_retrieve_response.py b/src/kernel/types/browser_retrieve_response.py index 76fc6ce..221eab5 100644 --- a/src/kernel/types/browser_retrieve_response.py +++ b/src/kernel/types/browser_retrieve_response.py @@ -45,7 +45,10 @@ class BrowserRetrieveResponse(BaseModel): """When the browser session was soft-deleted. Only present for deleted sessions.""" gpu: Optional[bool] = None - """Whether the browser session has hardware-accelerated GPU rendering.""" + """ + Whether GPU acceleration is enabled for the browser session (only supported for + headful sessions). + """ kiosk_mode: Optional[bool] = None """Whether the browser session is running in kiosk mode.""" @@ -66,13 +69,17 @@ class BrowserRetrieveResponse(BaseModel): """Session usage metrics.""" viewport: Optional[BrowserViewport] = None - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browser_update_response.py b/src/kernel/types/browser_update_response.py index fdf4fb5..c8a85c3 100644 --- a/src/kernel/types/browser_update_response.py +++ b/src/kernel/types/browser_update_response.py @@ -45,7 +45,10 @@ class BrowserUpdateResponse(BaseModel): """When the browser session was soft-deleted. Only present for deleted sessions.""" gpu: Optional[bool] = None - """Whether the browser session has hardware-accelerated GPU rendering.""" + """ + Whether GPU acceleration is enabled for the browser session (only supported for + headful sessions). + """ kiosk_mode: Optional[bool] = None """Whether the browser session is running in kiosk mode.""" @@ -66,13 +69,17 @@ class BrowserUpdateResponse(BaseModel): """Session usage metrics.""" viewport: Optional[BrowserViewport] = None - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/browsers/computer_batch_params.py b/src/kernel/types/browsers/computer_batch_params.py index 9aca724..7fc6abb 100644 --- a/src/kernel/types/browsers/computer_batch_params.py +++ b/src/kernel/types/browsers/computer_batch_params.py @@ -59,9 +59,21 @@ class ActionDragMouse(TypedDict, total=False): delay: int """Delay in milliseconds between button down and starting to move along the path.""" + duration_ms: int + """ + Target total duration in milliseconds for the entire drag movement when + smooth=true. Omit for automatic timing based on total path length. + """ + hold_keys: SequenceNotStr[str] """Modifier keys to hold during the drag""" + smooth: bool + """ + Use human-like Bezier curves between path waypoints instead of linear + interpolation. When true, steps_per_segment and step_delay_ms are ignored. + """ + step_delay_ms: int """ Delay in milliseconds between relative steps while dragging (not the initial @@ -119,10 +131,16 @@ class ActionScroll(TypedDict, total=False): """Y coordinate at which to perform the scroll""" delta_x: int - """Horizontal scroll amount. Positive scrolls right, negative scrolls left.""" + """ + Horizontal scroll amount in xdotool "wheel units." Positive scrolls right, + negative scrolls left. + """ delta_y: int - """Vertical scroll amount. Positive scrolls down, negative scrolls up.""" + """ + Vertical scroll amount in xdotool "wheel units." Positive scrolls down, negative + scrolls up. + """ hold_keys: SequenceNotStr[str] """Modifier keys to hold during the scroll""" diff --git a/src/kernel/types/browsers/computer_drag_mouse_params.py b/src/kernel/types/browsers/computer_drag_mouse_params.py index fb03b4b..c0dd4c8 100644 --- a/src/kernel/types/browsers/computer_drag_mouse_params.py +++ b/src/kernel/types/browsers/computer_drag_mouse_params.py @@ -23,9 +23,21 @@ class ComputerDragMouseParams(TypedDict, total=False): delay: int """Delay in milliseconds between button down and starting to move along the path.""" + duration_ms: int + """ + Target total duration in milliseconds for the entire drag movement when + smooth=true. Omit for automatic timing based on total path length. + """ + hold_keys: SequenceNotStr[str] """Modifier keys to hold during the drag""" + smooth: bool + """ + Use human-like Bezier curves between path waypoints instead of linear + interpolation. When true, steps_per_segment and step_delay_ms are ignored. + """ + step_delay_ms: int """ Delay in milliseconds between relative steps while dragging (not the initial diff --git a/src/kernel/types/browsers/computer_scroll_params.py b/src/kernel/types/browsers/computer_scroll_params.py index 110cb30..3af38af 100644 --- a/src/kernel/types/browsers/computer_scroll_params.py +++ b/src/kernel/types/browsers/computer_scroll_params.py @@ -17,10 +17,16 @@ class ComputerScrollParams(TypedDict, total=False): """Y coordinate at which to perform the scroll""" delta_x: int - """Horizontal scroll amount. Positive scrolls right, negative scrolls left.""" + """ + Horizontal scroll amount in xdotool "wheel units." Positive scrolls right, + negative scrolls left. + """ delta_y: int - """Vertical scroll amount. Positive scrolls down, negative scrolls up.""" + """ + Vertical scroll amount in xdotool "wheel units." Positive scrolls down, negative + scrolls up. + """ hold_keys: SequenceNotStr[str] """Modifier keys to hold during the scroll""" diff --git a/src/kernel/types/invocation_list_browsers_response.py b/src/kernel/types/invocation_list_browsers_response.py index 673615b..a0fed9a 100644 --- a/src/kernel/types/invocation_list_browsers_response.py +++ b/src/kernel/types/invocation_list_browsers_response.py @@ -45,7 +45,10 @@ class Browser(BaseModel): """When the browser session was soft-deleted. Only present for deleted sessions.""" gpu: Optional[bool] = None - """Whether the browser session has hardware-accelerated GPU rendering.""" + """ + Whether GPU acceleration is enabled for the browser session (only supported for + headful sessions). + """ kiosk_mode: Optional[bool] = None """Whether the browser session is running in kiosk mode.""" @@ -66,15 +69,19 @@ class Browser(BaseModel): """Session usage metrics.""" viewport: Optional[BrowserViewport] = None - """Initial browser window size in pixels with optional refresh rate. - - If omitted, image defaults apply (1920x1080@25). Arbitrary viewport dimensions - are accepted, but the following configurations are known-good and fully tested: - 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, - 1200x800@60. Viewports outside this list may exhibit unstable live view or - recording behavior. If refresh_rate is not provided, it will be automatically - determined based on the resolution (higher resolutions use lower refresh rates - to keep bandwidth reasonable). + """ + Initial browser window size in pixels with optional refresh rate. If omitted, + image defaults apply (1920x1080@25). For GPU images, the default is + 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, + 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended + presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, + 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. + Viewports outside this list may exhibit unstable live view or recording + behavior. If refresh_rate is not provided, it will be automatically determined + based on the resolution (higher resolutions use lower refresh rates to keep + bandwidth reasonable). """ diff --git a/src/kernel/types/shared/browser_viewport.py b/src/kernel/types/shared/browser_viewport.py index dacac1f..c53505b 100644 --- a/src/kernel/types/shared/browser_viewport.py +++ b/src/kernel/types/shared/browser_viewport.py @@ -8,11 +8,15 @@ class BrowserViewport(BaseModel): - """Initial browser window size in pixels with optional refresh rate. - + """ + Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). - Arbitrary viewport dimensions are accepted, but the following configurations are known-good and fully tested: + For GPU images, the default is 1920x1080@60. + Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable). diff --git a/src/kernel/types/shared_params/browser_viewport.py b/src/kernel/types/shared_params/browser_viewport.py index f98ece8..2290f93 100644 --- a/src/kernel/types/shared_params/browser_viewport.py +++ b/src/kernel/types/shared_params/browser_viewport.py @@ -8,11 +8,15 @@ class BrowserViewport(TypedDict, total=False): - """Initial browser window size in pixels with optional refresh rate. - + """ + Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). - Arbitrary viewport dimensions are accepted, but the following configurations are known-good and fully tested: + For GPU images, the default is 1920x1080@60. + Arbitrary viewport dimensions and refresh rates are accepted. + Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. + For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: + 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable). diff --git a/tests/api_resources/browsers/test_computer.py b/tests/api_resources/browsers/test_computer.py index 09960bf..31974d5 100644 --- a/tests/api_resources/browsers/test_computer.py +++ b/tests/api_resources/browsers/test_computer.py @@ -224,7 +224,9 @@ def test_method_drag_mouse_with_all_params(self, client: Kernel) -> None: path=[[0, 0], [0, 0]], button="left", delay=0, + duration_ms=50, hold_keys=["string"], + smooth=True, step_delay_ms=0, steps_per_segment=1, ) @@ -887,7 +889,9 @@ async def test_method_drag_mouse_with_all_params(self, async_client: AsyncKernel path=[[0, 0], [0, 0]], button="left", delay=0, + duration_ms=50, hold_keys=["string"], + smooth=True, step_delay_ms=0, steps_per_segment=1, )