cayu.environments.deferred

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.

DeferredMaterialization

from cayu.environments import DeferredMaterialization

Shared single-flight state behind one deferred runner and binding.

materialize(mode) is factory-owned and returns the exact runner plus the real binding to run against it. It must reuse the factory’s ordinary creation path so admission and isolation evidence match an eager start. dispose_unmaterialized removes a resource a crashed process created but never bound; it runs at finalization when this process never materialized.

init (method)

DeferredMaterialization.__init__(materialize: MaterializeCallable, *, default_cwd: str, placeholder_workspace: Callable[[Runner], Workspace | None] | None=None, configured_candidate: Callable[[ExecutionRequirements], ExecutionAdmissionCandidate | None] | None=None, environment_authority: ExecutionEnvironmentAuthority | None=None, dispose_unmaterialized: Callable[[], Awaitable[None]] | None=None, isolation: str='unknown') -> None

is_materialized (property)

DeferredMaterialization.is_materialized() -> bool

materialized_runner (property)

DeferredMaterialization.materialized_runner() -> Runner | None

The live runner once created, even before its first-use bind.

attach_observer (method)

DeferredMaterialization.attach_observer(observer: MaterializationObserver | None) -> None

Receive started/completed/failed notifications (runtime-owned).

attach_admission (method)

DeferredMaterialization.attach_admission(admission: MaterializationAdmission | None) -> None

Run the runtime’s live admission on the new runner before it is used.

A refusal raises; the runner is closed and the triggering call fails.

materialize (method)

async DeferredMaterialization.materialize(mode: MaterializationMode='use') -> Runner

Return the materialized runner, creating and binding it once.

Release source · Runtime guarantees · Capability guides

DeferredRunner

from cayu.environments import DeferredRunner

A runner that materializes on first command execution.

Command, workspace and admission calls that need a live target materialize once and then delegate to the exact runner the factory created. Admission for requirements that only need declared evidence is answered from the factory’s configured candidate, so session start dispatches nothing. Requirements that need live evidence (declared executables) materialize eagerly at session start, exactly like an eager environment.

Bases: Runner.

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
isolation	str	'unknown'
default_cwd	str	'/'
system_execution_mode	RunnerSystemExecutionMode	'shared'

workload_authority (method)

DeferredRunner.workload_authority(name: str) -> RunnerWorkloadAuthority | None

Return runner-owned authority for an exact provisioned workload.

execution_environment_authority (method)

DeferredRunner.execution_environment_authority() -> ExecutionEnvironmentAuthority

output_secret_values_present (method)

DeferredRunner.output_secret_values_present() -> bool | None

browser_control_endpoint_reachable (method)

DeferredRunner.browser_control_endpoint_reachable(endpoint: str) -> bool | None

Report whether the guest can dial a browser control or recording endpoint.

None makes no declaration: reachability then rests on deployment configuration, as with Docker’s colocated control-server alias. A runner whose guest has a fixed, verified control path returns False for every endpoint outside it, so no control credential is sent there.

browser_recording_supported (method)

DeferredRunner.browser_recording_supported() -> bool

Declare that this runner captures and finalizes browser recordings.

execution_profile_identity (property)

DeferredRunner.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

preflight_exec (method)

DeferredRunner.preflight_exec(command: ExecCommand, **kwargs: Any) -> None

exec (method)

async DeferredRunner.exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

exec_redacted (method)

async DeferredRunner.exec_redacted(command: ExecCommand, **kwargs: Any) -> ExecResult

exec_system (method)

async DeferredRunner.exec_system(command: ExecCommand, **kwargs: Any) -> ExecResult

close (method)

async DeferredRunner.close() -> None

await_pending_command_settlement (method)

async DeferredRunner.await_pending_command_settlement() -> bool

refresh_execution_admission (method)

async DeferredRunner.refresh_execution_admission() -> None

execution_admission_candidate (method)

DeferredRunner.execution_admission_candidate() -> ExecutionAdmissionCandidate | None

collect_execution_admission_candidate (method)

async DeferredRunner.collect_execution_admission_candidate() -> ExecutionAdmissionCandidate | None

Collect final evidence after lifecycle-owned mutating setup completes.

The default adapts existing side-effect-free snapshot implementations. Runners whose evidence depends on live external state override this hook and complete or positively transfer settlement ownership for every dispatched probe before returning or raising for any reason.

execution_admission_candidate_for (method)

DeferredRunner.execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate | None

execution_admission_observer (method)

DeferredRunner.execution_admission_observer(requirements: ExecutionRequirements) -> RunnerExecutionAdmissionObserver

collect_execution_admission_candidate_for (method)

async DeferredRunner.collect_execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate | None

Collect final request-bound evidence under lifecycle ownership.

Requirements are input, never proof. Implementations must isolate concurrent requirement sets and settle or positively transfer every dispatched probe under the same contract as the ordinary collector.

resource_key (property)

DeferredRunner.resource_key() -> tuple[object, ...] | None

is_closed (property)

DeferredRunner.is_closed() -> bool

Whether terminal runner finalization has completed.

lifecycle_state (property)

DeferredRunner.lifecycle_state() -> RunnerLifecycleState

Observe execution eligibility without exposing provider internals.

workspace_capability (method)

DeferredRunner.workspace_capability(capability_type)

binary_stream_capability (method)

DeferredRunner.binary_stream_capability() -> RunnerBinaryStreamCapability | None

reopen_exec (method)

DeferredRunner.reopen_exec() -> None

Clear an intentional execution fence on an otherwise-open runner.

This is not recovery authority for inconclusive command cleanup. Poisoned instances cannot be reopened, including after a late cleanup acknowledgement; a new independently verified allocation owner is needed.

resolve_cwd (method)

DeferredRunner.resolve_cwd(cwd: str | None=None) -> str

aenter (method)

async DeferredRunner.__aenter__() -> Self

aexit (method)

async DeferredRunner.__aexit__(exc_type: Any, exc_val: Any, exc_tb: Any) -> bool

init (method)

DeferredRunner.__init__(state: DeferredMaterialization, *, default_cwd: str, configured_candidate: Callable[[ExecutionRequirements], ExecutionAdmissionCandidate | None] | None, environment_authority: ExecutionEnvironmentAuthority | None, isolation: str) -> None

materialization (property)

DeferredRunner.materialization() -> DeferredMaterialization

exec_stream (method)

async DeferredRunner.exec_stream(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: BinaryIO | None=None, stdout: BinaryIO | None=None, stdout_limit_bytes: int | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

Release source · Runtime guarantees · Capability guides

DeferredWorkspaceBinding

from cayu.environments import DeferredWorkspaceBinding

Bind nothing at session start; run the real binding at materialization.

Finalization, recovery and abandonment delegate to the real binding once the environment materialized, and are no-ops (apart from disposing an unbound resource left by a crashed process) when it never did.

Bases: WorkspaceBinding.

bind (method)

async DeferredWorkspaceBinding.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 DeferredWorkspaceBinding.finalize(bound: BoundWorkspace, *, outcome: str | None=None, metadata: dict[str, Any] | None=None) -> WorkspaceSnapshot | None

observe_revision (method)

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

Observe the materialized workspace under this binding’s identity.

The runtime registered this binding, with the session-start placeholder workspace, so it expects that identity. The real binding’s observation describes the same workspace once materialized and is re-stamped with it. Before materialization nothing exists to observe: unsupported.

input_capability (method)

DeferredWorkspaceBinding.input_capability() -> ImmutableInputAdapterCapability

Describe how this binding exposes environment input bytes.

observe_writer_isolation (method)

DeferredWorkspaceBinding.observe_writer_isolation(bound: BoundWorkspace) -> WorkspaceWriterIsolationEvidence

abandon (method)

DeferredWorkspaceBinding.abandon(bound: BoundWorkspace) -> bool

init (method)

DeferredWorkspaceBinding.__init__(state: DeferredMaterialization) -> None

materialization (property)

DeferredWorkspaceBinding.materialization() -> DeferredMaterialization

Release source · Runtime guarantees · Capability guides

EnvironmentMaterializationError

from cayu.environments import EnvironmentMaterializationError

A deferred environment could not be created, admitted or bound.

The triggering tool call fails with this error; the session stays usable and a later runner use attempts materialization again.

Bases: RunnerUnavailableError.

init (method)

EnvironmentMaterializationError.__init__(message: str, *, reason: str) -> None

Release source · Runtime guarantees · Capability guides