cayu.environments.bindings

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.

`BoundWorkspace`

from cayu.environments import BoundWorkspace

Result of binding a workspace to a runner for one session.

path names where the workspace is visible from the runner’s point of view, when the binding has such a path. metadata carries binding-owned state such as mount ids, sandbox refs, branch names, or sync tokens. snapshot identifies the concrete workspace version bound for the session when the binding backend can provide one. state_key is runtime-private and is not included in binding event payloads.

Decorators: @dataclass(frozen=True).

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
`workspace`	`Workspace \| None`	`None`
`source_workspace`	`Workspace \| None`	`None`
`runner`	`Runner \| None`	`None`
`path`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`field(default_factory=dict)`
`snapshot`	`WorkspaceSnapshot \| None`	`None`
`state_key`	`str \| None`	`field(default=None, repr=False, compare=False)`

Release source · Runtime guarantees · Capability guides

`copy_bound_workspace`

from cayu.environments import copy_bound_workspace

Return a defensive copy of binding result metadata.

copy_bound_workspace(bound: BoundWorkspace) -> BoundWorkspace

Release source · Runtime guarantees · Capability guides

`copy_workspace_snapshot`

from cayu.environments import copy_workspace_snapshot

Return a defensive copy of a workspace snapshot.

copy_workspace_snapshot(snapshot: WorkspaceSnapshot | None) -> WorkspaceSnapshot | None

Release source · Runtime guarantees · Capability guides

`DeterministicWorkspaceBinding`

from cayu.environments import DeterministicWorkspaceBinding

Backend-neutral revision observer for conformance and simple workspaces.

Bases: NativeBinding.

bind (method)

async DeterministicWorkspaceBinding.bind(workspace: Workspace | None, runner: Runner | None, *, session_id: str, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> BoundWorkspace

finalize (method)

async DeterministicWorkspaceBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

observe_revision (method)

async DeterministicWorkspaceBinding.observe_revision(bound: BoundWorkspace) -> WorkspaceRevisionObservation

input_capability (method)

DeterministicWorkspaceBinding.input_capability() -> ImmutableInputAdapterCapability

Describe how this binding exposes environment input bytes.

observe_writer_isolation (method)

DeterministicWorkspaceBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

Report inspectable writer-isolation evidence for one mutation window.

The compatibility default is deliberately unknown. Serial tool dispatch, a process-local lock, or a stable workspace identity does not prove that users, sibling processes, or background services cannot mutate the same resource.

abandon (method)

DeterministicWorkspaceBinding.abandon(bound: BoundWorkspace) -> bool

Release process-local retry state when finalization will not run again.

Most bindings do not retain retry state, so the compatibility default is a validated no-op. Stateful bindings should override this method and release only state owned by bound. Return False only when the binding must retain its lifecycle owner for a later cleanup attempt.

init (method)

DeterministicWorkspaceBinding.__init__(*, default_path: str | None=None, observation_limits: WorkspaceRevisionObservationLimits | None=None) -> None

Release source · Runtime guarantees · Capability guides

`GitRepositoryBinding`

from cayu.environments import GitRepositoryBinding

Ensure a workspace contains a checked-out Git repository.

The binding creates or updates the repository before the model sees the workspace. It records commit/dirty metadata, but it never commits, pushes, or creates pull requests; those remain explicit app/tool workflows.

fetch_refspecs fetches refs the default clone/fetch does not — most commonly a pull-request head, which lives under refs/pull/N/head and is not covered by the default refs/heads/* refspec. To review PR #123, pass fetch_refspecs=["+refs/pull/123/head:refs/heads/pr-123"] together with ref="pr-123".

Bases: WorkspaceBinding.

bind (method)

async GitRepositoryBinding.bind(workspace: Workspace | None, runner: Runner | None, *, session_id: str, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> BoundWorkspace

finalize (method)

async GitRepositoryBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

observe_revision (method)

async GitRepositoryBinding.observe_revision(bound: BoundWorkspace) -> WorkspaceRevisionObservation

Observe Git HEAD, branch, index, and worktree state without mutating Git.

input_capability (method)

GitRepositoryBinding.input_capability() -> ImmutableInputAdapterCapability

Describe how this binding exposes environment input bytes.

observe_writer_isolation (method)

GitRepositoryBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

Report inspectable writer-isolation evidence for one mutation window.

abandon (method)

GitRepositoryBinding.abandon(bound: BoundWorkspace) -> bool

Release process-local retry state when finalization will not run again.

init (method)

GitRepositoryBinding.__init__(*, repo_url: str, ref: str | None=None, remote_name: str='origin', path: str | None=None, git_executable: str='git', fetch: bool=True, fetch_refspecs: list[str] | None=None, require_clean: bool=True, verify_remote_url: bool=True, timeout_s: int | None=120, output_limit_bytes: int=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES, observation_limits: WorkspaceRevisionObservationLimits | None=None) -> None

Release source · Runtime guarantees · Capability guides

`NativeBinding`

from cayu.environments import NativeBinding

Binding for backends where workspace and runner already share state.

The configured workspace and runner are passed through unchanged. Runner- specific bindings can later expose richer mount/copy behavior without changing the environment contract.

Bases: WorkspaceBinding.

bind (method)

async NativeBinding.bind(workspace: Workspace | None, runner: Runner | None, *, session_id: str, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> BoundWorkspace

finalize (method)

async NativeBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

observe_revision (method)

async NativeBinding.observe_revision(bound: BoundWorkspace) -> WorkspaceRevisionObservation

Observe bounded workspace state when this binding supports it.

The compatibility default is an explicit unsupported result. It must not reinterpret per-file optimistic revision tokens or binding snapshots as restorable workspace revisions.

input_capability (method)

NativeBinding.input_capability() -> ImmutableInputAdapterCapability

Describe how this binding exposes environment input bytes.

observe_writer_isolation (method)

NativeBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

Report inspectable writer-isolation evidence for one mutation window.

abandon (method)

NativeBinding.abandon(bound: BoundWorkspace) -> bool

Release process-local retry state when finalization will not run again.

init (method)

NativeBinding.__init__(*, default_path: str | None=None) -> None

Release source · Runtime guarantees · Capability guides

`NoWorkspaceBinding`

from cayu.environments import NoWorkspaceBinding

Binding for agents that intentionally expose no workspace to the runner.

Bases: WorkspaceBinding.

bind (method)

async NoWorkspaceBinding.bind(workspace: Workspace | None, runner: Runner | None, *, session_id: str, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> BoundWorkspace

finalize (method)

async NoWorkspaceBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

observe_revision (method)

async NoWorkspaceBinding.observe_revision(bound: BoundWorkspace) -> WorkspaceRevisionObservation

Observe bounded workspace state when this binding supports it.

The compatibility default is an explicit unsupported result. It must not reinterpret per-file optimistic revision tokens or binding snapshots as restorable workspace revisions.

input_capability (method)

NoWorkspaceBinding.input_capability() -> ImmutableInputAdapterCapability

observe_writer_isolation (method)

NoWorkspaceBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

Report inspectable writer-isolation evidence for one mutation window.

abandon (method)

NoWorkspaceBinding.abandon(bound: BoundWorkspace) -> bool

Release process-local retry state when finalization will not run again.

Release source · Runtime guarantees · Capability guides

`SyncBinding`

from cayu.environments import SyncBinding

Copy a durable workspace into a bound workspace and sync changes back.

workspace passed to bind is the durable source. target_workspace or target_workspace_plan_factory identifies the workspace visible to tools during the run, typically a sandbox filesystem wrapper. A factory must only resolve a stable, quiescent target identity. Setup that mutates the target is returned as SyncTargetWorkspacePlan.provision so it runs after ownership admission. External allocation remains owned by the surrounding environment factory lifecycle; constructing a wrapper for an already-owned target is identity resolution rather than provisioning. The target workspace should be dedicated to this binding because the default clean policy deletes files in the target before copying source files in. Every active generation process-locally owns both source and target by their authoritative Workspace.resource_key values. Concurrent binds through the same or different SyncBinding instances are rejected when either resource would overlap in any source or target role.

File copies use one bulk tar transfer per direction when either workspace implements the explicit BoundedTarReader or TarWriter capability (RunnerWorkspace implements both). Bounded generic transfers are staged before destination writes. max_total_bytes bounds logical file bytes, while max_archive_bytes independently bounds raw tar bytes; pass None for a limit to opt out of that per-transfer bound. The aggregate staging_capacity remains authoritative for every transfer. Per-bind state is keyed by an opaque owner generation. Both resources remain reserved until that exact generation finalizes successfully or is explicitly abandoned; elapsed time is not evidence that a live binding released them. Direct callers whose lifecycle will not invoke finalize must call abandon with the matching bound workspace. Runtime-managed completed outcomes persist a bounded private copy of the generation state before finalization so incomplete-session recovery can reconnect the same target and retry revision-aware copy-back without repeating bind or workload work.

Bases: WorkspaceBinding.

bind (method)

async SyncBinding.bind(workspace: Workspace | None, runner: Runner | None, *, session_id: str, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> BoundWorkspace

finalize (method)

async SyncBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

observe_revision (method)

async SyncBinding.observe_revision(bound: BoundWorkspace) -> WorkspaceRevisionObservation

Observe bounded workspace state when this binding supports it.

The compatibility default is an explicit unsupported result. It must not reinterpret per-file optimistic revision tokens or binding snapshots as restorable workspace revisions.

input_capability (method)

SyncBinding.input_capability() -> ImmutableInputAdapterCapability

observe_writer_isolation (method)

SyncBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

Report inspectable writer-isolation evidence for one mutation window.

abandon (method)

SyncBinding.abandon(bound: BoundWorkspace) -> bool

Drop in-process bind state for a bind whose finalize will never run.

Lifecycle owners that skip finalize (crash recovery, cancelled sessions) should call this so per-bind state and resource ownership do not leak.

init (method)

SyncBinding.__init__(*, target_workspace: Workspace | None=None, target_workspace_plan_factory: SyncTargetWorkspacePlanFactory | None=None, target_workspace_factory: Callable[[SyncBindingContext], object] | None=None, path: str | None=None, pattern: str='**/*', max_files: int=10000, max_file_bytes: int | None=None, max_total_bytes: int | None=DEFAULT_SYNC_MAX_TOTAL_BYTES, max_archive_bytes: int | None=DEFAULT_SYNC_MAX_ARCHIVE_BYTES, clean_target: SyncTargetCleanPolicy='always', sync_back: SyncBackPolicy='always', delete_missing: bool=True, source_conflict_policy: SyncSourceConflictPolicy='overwrite', preserve_git_modes: bool=False, staging_capacity: SyncBindingStagingCapacity | None=None) -> None

staging_snapshot (method)

SyncBinding.staging_snapshot() -> SyncBindingStagingSnapshot

Return content-free process-local staging capacity state.

Release source · Runtime guarantees · Capability guides

`SyncBindingContext`

from cayu.environments import SyncBindingContext

Context passed to a SyncBinding target workspace factory.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`source_workspace`	`Workspace`	`required`
`runner`	`Runner \| None`	`None`
`session_id`	`str \| None`	`None`
`agent_name`	`str \| None`	`None`
`environment_name`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`field(default_factory=dict)`

Release source · Runtime guarantees · Capability guides

`SyncBindingSourceConflictError`

from cayu.environments import SyncBindingSourceConflictError

Copy-back refused because the durable source changed concurrently.

Bases: RuntimeError.

init (method)

SyncBindingSourceConflictError.__init__(path: str, *, applied_paths: tuple[str, ...]=()) -> None

Release source · Runtime guarantees · Capability guides

`SyncTargetWorkspacePlan`

from cayu.environments import SyncTargetWorkspacePlan

A resolved target identity plus setup that runs after ownership admission.

workspace must already expose its stable, quiescent resource identity. provision may attach, clean, or otherwise mutate that target and is invoked only after the source and target resource keys are owned by the binding generation. Allocation and failed-bind cleanup remain owned by the surrounding environment factory lifecycle. Constructing the in-process workspace wrapper needed to identify an already-owned target is allowed.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`workspace`	`Workspace`	`required`
`provision`	`SyncTargetWorkspaceProvisioner \| None`	`None`

Release source · Runtime guarantees · Capability guides

`WorkspaceBinding`

from cayu.environments import WorkspaceBinding

Bridge between durable workspace storage and runner execution.

bind makes a workspace available to a runner for one session. finalize is called when the session lifecycle ends, so implementations can sync, persist, discard, or unmount according to the session outcome.

Bases: ABC.

bind (method)

async WorkspaceBinding.bind(workspace: Workspace | None, runner: Runner | None, *, session_id: str, agent_name: str | None=None, environment_name: str | None=None, metadata: dict[str, Any] | None=None) -> BoundWorkspace

Make the workspace available to the runner.

finalize (method)

async WorkspaceBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

Clean up or persist the binding after the session ends.

observe_revision (method)

async WorkspaceBinding.observe_revision(bound: BoundWorkspace) -> WorkspaceRevisionObservation

Observe bounded workspace state when this binding supports it.

The compatibility default is an explicit unsupported result. It must not reinterpret per-file optimistic revision tokens or binding snapshots as restorable workspace revisions.

input_capability (method)

WorkspaceBinding.input_capability() -> ImmutableInputAdapterCapability

Describe how this binding exposes environment input bytes.

observe_writer_isolation (method)

WorkspaceBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

Report inspectable writer-isolation evidence for one mutation window.

abandon (method)

WorkspaceBinding.abandon(bound: BoundWorkspace) -> bool

Release process-local retry state when finalization will not run again.

Release source · Runtime guarantees · Capability guides

`WorkspaceSnapshot`

from cayu.environments import WorkspaceSnapshot

Serializable identity for a concrete workspace version.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`snapshot_id`	`str`	`required`
`workspace_id`	`str \| None`	`None`
`version`	`str \| None`	`None`
`source`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`field(default_factory=dict)`

Release source · Runtime guarantees · Capability guides