cayu.tools.browser_session

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`BROWSER_SESSION_PROTOCOL_VERSION`

from cayu.tools import BROWSER_SESSION_PROTOCOL_VERSION

BROWSER_SESSION_PROTOCOL_VERSION = PINNED_BROWSER_SESSION_WORKLOAD.protocol_version

Release source · Runtime guarantees · Capability guides

`BROWSER_SESSION_WORKER_VERSION`

from cayu.tools import BROWSER_SESSION_WORKER_VERSION

BROWSER_SESSION_WORKER_VERSION = PINNED_BROWSER_SESSION_WORKLOAD.worker_version

Release source · Runtime guarantees · Capability guides

`BrowserPageRefusal`

from cayu.tools import BrowserPageRefusal

One bounded popup refusal emitted by an operation.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`page_id`	`str`	`Field(min_length=1, max_length=_MAX_BROWSER_ID_LENGTH)`
`opener_page_id`	`str`	`Field(min_length=1, max_length=_MAX_BROWSER_ID_LENGTH)`
`reason`	`Literal['capacity_refused', 'destination_denied', 'operation_refused', 'policy_denied']`	`required`

validate_page_id (method)

BrowserPageRefusal.validate_page_id(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`BrowserPageSetDelta`

from cayu.tools import BrowserPageSetDelta

Bounded page identities changed by one browser operation.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`created_page_ids`	`tuple[str, ...]`	`Field(default=(), max_length=MAX_BROWSER_SESSION_MAX_PAGES)`
`admitted_page_ids`	`tuple[str, ...]`	`Field(default=(), max_length=MAX_BROWSER_SESSION_MAX_PAGES)`
`closed_page_ids`	`tuple[str, ...]`	`Field(default=(), max_length=MAX_BROWSER_SESSION_MAX_PAGES)`
`crashed_page_ids`	`tuple[str, ...]`	`Field(default=(), max_length=MAX_BROWSER_SESSION_MAX_PAGES)`
`refused`	`tuple[BrowserPageRefusal, ...]`	`Field(default=(), max_length=MAX_BROWSER_SESSION_MAX_PAGE_CREATIONS_PER_OPERATION)`

validate_page_ids (method)

BrowserPageSetDelta.validate_page_ids(values: tuple[str, ...], info) -> tuple[str, ...]

validate_refusals (method)

BrowserPageSetDelta.validate_refusals() -> BrowserPageSetDelta

Release source · Runtime guarantees · Capability guides

`BrowserPageSetState`

from cayu.tools import BrowserPageSetState

Complete bounded page registry returned by the live browser allocation.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`session_id`	`str`	`Field(min_length=1, max_length=_MAX_BROWSER_ID_LENGTH)`
`active_page_id`	`str \| None`	`Field(default=None, max_length=_MAX_BROWSER_ID_LENGTH)`
`pages`	`tuple[BrowserPageSummary, ...]`	`Field(max_length=MAX_BROWSER_SESSION_MAX_TOTAL_PAGE_CREATIONS)`
`total_page_creations`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`total_operations`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`total_observations`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`total_refs`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`total_requests`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`total_artifacts`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`cleanup_operation_count`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`

validate_browser_identity (method)

BrowserPageSetState.validate_browser_identity(value: str | None, info) -> str | None

validate_registry (method)

BrowserPageSetState.validate_registry() -> BrowserPageSetState

Release source · Runtime guarantees · Capability guides

`BrowserPageSummary`

from cayu.tools import BrowserPageSummary

Bounded safe state for one Cayu-owned page identity.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`page_id`	`str`	`Field(min_length=1, max_length=_MAX_BROWSER_ID_LENGTH)`
`lifecycle`	`Literal['provisional', 'admitted', 'active', 'background', 'closing', 'closed', 'crashed', 'uncertain']`	`required`
`creation_epoch`	`int`	`Field(ge=1, le=_MAX_PAGE_COUNTER)`
`control_epoch`	`int`	`Field(ge=1, le=_MAX_PAGE_COUNTER)`
`opener_page_id`	`str \| None`	`Field(default=None, max_length=_MAX_BROWSER_ID_LENGTH)`
`creating_operation_id_sha256`	`str \| None`	`Field(default=None, min_length=64, max_length=64)`
`revision`	`str \| None`	`Field(default=None, max_length=_MAX_BROWSER_ID_LENGTH)`
`url`	`str \| None`	`Field(default=None, max_length=MAX_WEB_FETCH_URL_LENGTH)`
`title`	`str \| None`	`None`
`load_state`	`Literal['loaded', 'loading', 'failed', 'unknown']`	`'unknown'`
`access_state`	`Literal['available', 'blocked', 'unknown']`	`'unknown'`
`last_observation_revision`	`str \| None`	`Field(default=None, max_length=_MAX_BROWSER_ID_LENGTH)`
`last_operation_id_sha256`	`str \| None`	`Field(default=None, min_length=64, max_length=64)`
`terminal_reason`	`str \| None`	`Field(default=None, max_length=_MAX_PAGE_REASON_BYTES)`
`operation_count`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`observation_count`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`ref_count`	`int`	`Field(ge=0, le=MAX_BROWSER_SESSION_MAX_TOTAL_REFS)`
`request_count`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`
`artifact_count`	`int`	`Field(ge=0, le=_MAX_PAGE_COUNTER)`

validate_page_identity (method)

BrowserPageSummary.validate_page_identity(value: str | None, info) -> str | None

validate_operation_digest (method)

BrowserPageSummary.validate_operation_digest(value: str | None, info) -> str | None

validate_page_url (method)

BrowserPageSummary.validate_page_url(value: str | None) -> str | None

validate_page_title (method)

BrowserPageSummary.validate_page_title(value: str | None) -> str | None

validate_terminal_reason (method)

BrowserPageSummary.validate_terminal_reason(value: str | None) -> str | None

validate_lifecycle (method)

BrowserPageSummary.validate_lifecycle() -> BrowserPageSummary

Release source · Runtime guarantees · Capability guides

`BrowserPopupPolicy`

from cayu.tools import BrowserPopupPolicy

Application-owned popup admission policy for one browser page set.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`mode`	`Literal['deny', 'same_origin', 'destination_policy']`	`'deny'`
`allowed_operations`	`tuple[Literal['click', 'fill', 'select', 'press', 'wait', 'click_visual_target', 'click_visual_point'], ...]`	`()`
`allowed_opener_origins`	`tuple[str, ...]`	`Field(default=(), max_length=_MAX_POPUP_POLICY_ORIGINS)`
`allowed_destination_origins`	`tuple[str, ...]`	`Field(default=(), max_length=_MAX_POPUP_POLICY_ORIGINS)`

validate_origins (method)

BrowserPopupPolicy.validate_origins(values: tuple[str, ...], info) -> tuple[str, ...]

validate_policy (method)

BrowserPopupPolicy.validate_policy() -> BrowserPopupPolicy

Release source · Runtime guarantees · Capability guides

`BrowserSessionTool`

from cayu.tools import BrowserSessionTool

One closed stateful browser interface backed by an admitted runner.

Bases: Tool.

init (method)

BrowserSessionTool.__init__(*, max_snapshot_bytes: int=DEFAULT_BROWSER_SESSION_MAX_SNAPSHOT_BYTES, max_dom_nodes: int=DEFAULT_BROWSER_SESSION_MAX_DOM_NODES, max_refs: int=DEFAULT_BROWSER_SESSION_MAX_REFS, max_artifact_bytes: int=DEFAULT_BROWSER_SESSION_MAX_ARTIFACT_BYTES, max_page_width: int=DEFAULT_BROWSER_SESSION_MAX_PAGE_WIDTH, max_page_height: int=DEFAULT_BROWSER_SESSION_MAX_PAGE_HEIGHT, max_page_pixels: int=DEFAULT_BROWSER_SESSION_MAX_PAGE_PIXELS, max_wait_ms: int=DEFAULT_BROWSER_SESSION_MAX_WAIT_MS, idle_timeout_seconds: int=DEFAULT_BROWSER_SESSION_IDLE_TIMEOUT_SECONDS, max_redirects: int=DEFAULT_BROWSER_SESSION_MAX_REDIRECTS, max_requests: int=DEFAULT_BROWSER_SESSION_MAX_REQUESTS, max_response_bytes: int=DEFAULT_BROWSER_SESSION_MAX_RESPONSE_BYTES, max_parent_sessions: int=DEFAULT_BROWSER_SESSION_MAX_PARENT_SESSIONS, max_sessions: int=DEFAULT_BROWSER_SESSION_MAX_SESSIONS, max_operations: int=DEFAULT_BROWSER_SESSION_MAX_OPERATIONS, multi_page: bool=False, popup_policy: BrowserPopupPolicy | Mapping[str, Any] | None=None, max_pages: int | None=None, max_provisional_pages: int | None=None, max_page_creations_per_operation: int | None=None, max_total_page_creations: int | None=None, max_background_lifetime_seconds: int | None=None, max_operations_per_page: int | None=None, max_observations_per_page: int | None=None, max_total_observations: int=DEFAULT_BROWSER_SESSION_MAX_TOTAL_OBSERVATIONS, max_refs_per_page: int | None=None, max_total_refs: int=DEFAULT_BROWSER_SESSION_MAX_TOTAL_REFS, max_total_requests: int=DEFAULT_BROWSER_SESSION_MAX_TOTAL_REQUESTS, max_artifacts_per_page: int | None=None, max_total_artifacts: int=DEFAULT_BROWSER_SESSION_MAX_TOTAL_ARTIFACTS, max_page_cleanup_operations: int=DEFAULT_BROWSER_SESSION_MAX_PAGE_CLEANUP_OPERATIONS, max_scroll_repeats: int=DEFAULT_BROWSER_SESSION_MAX_SCROLL_REPEATS, max_upload_files: int=DEFAULT_BROWSER_SESSION_MAX_UPLOAD_FILES, max_upload_file_bytes: int=DEFAULT_BROWSER_SESSION_MAX_UPLOAD_FILE_BYTES, max_upload_total_bytes: int=DEFAULT_BROWSER_SESSION_MAX_UPLOAD_TOTAL_BYTES, max_upload_filename_bytes: int=DEFAULT_BROWSER_SESSION_MAX_UPLOAD_FILENAME_BYTES, max_upload_materialization_ms: int=DEFAULT_BROWSER_SESSION_MAX_UPLOAD_MATERIALIZATION_MS, allowed_upload_content_types: Sequence[str]=DEFAULT_BROWSER_SESSION_UPLOAD_CONTENT_TYPES, allowed_upload_taint_labels: Sequence[str]=(), expected_runner_candidate: str | None=None, expected_environment_authority: ExecutionEnvironmentAuthority | None=None, expected_workload_authority: RunnerWorkloadAuthority=PINNED_BROWSER_SESSION_WORKLOAD, expected_artifact_store_id: str | None=None, browser_profile: BrowserProfileBinding | None=None, visual_policy: BrowserVisualPolicy | dict[str, Any] | None=None, recording: BrowserRecordingConfig | None=None, spec: ToolSpec | None=None, _backend: BrowserSessionBackend | None=None) -> None

name (property)

BrowserSessionTool.name() -> str

execution_profile_identity (property)

BrowserSessionTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

BrowserSessionTool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

BrowserSessionTool.description() -> str

schema (property)

BrowserSessionTool.schema() -> dict[str, Any]

run (method)

async BrowserSessionTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

browser_profile (property)

BrowserSessionTool.browser_profile() -> BrowserProfileBinding | None

Return the application-selected immutable profile binding.

reconcile_durable_tool_call (method)

async BrowserSessionTool.reconcile_durable_tool_call(*, parent_session_id: str, parent_run_epoch: int, execution_profile_fingerprint: str | None, environment_name: str | None, environment_allocation_fingerprint: str | None, model_step_id: str, model_attempt_id: str, tool_round_id: str, tool_call_id: str, idempotency_key: str, arguments: dict[str, Any], started: bool, load_operation: Callable[[str], Awaitable[dict[str, Any] | None]], recovery_authority: DurableToolRecoveryAuthority | None=None) -> DurableToolRecoveryEvidence | None

Reconcile browser evidence without dispatching or replaying an action.

Release source · Runtime guarantees · Capability guides