cayu.environments.factory

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.

`copy_environment_factory_request`

from cayu.environments import copy_environment_factory_request

copy_environment_factory_request(request: EnvironmentFactoryRequest) -> EnvironmentFactoryRequest

Release source · Runtime guarantees · Capability guides

`copy_environment_factory_result`

from cayu.environments import copy_environment_factory_result

copy_environment_factory_result(result: EnvironmentFactoryResult) -> EnvironmentFactoryResult

Release source · Runtime guarantees · Capability guides

`DEFAULT_ENVIRONMENT_FACTORY_RELEASE_TIMEOUT_SECONDS`

from cayu.environments import DEFAULT_ENVIRONMENT_FACTORY_RELEASE_TIMEOUT_SECONDS

DEFAULT_ENVIRONMENT_FACTORY_RELEASE_TIMEOUT_SECONDS = 15.0

Release source · Runtime guarantees · Capability guides

`ENVIRONMENT_ALLOCATION_INTENT_SCHEMA_VERSION`

from cayu.environments import ENVIRONMENT_ALLOCATION_INTENT_SCHEMA_VERSION

ENVIRONMENT_ALLOCATION_INTENT_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`EnvironmentAllocationContext`

from cayu.environments import EnvironmentAllocationContext

Runtime-owned durable coordinator passed to recoverable factories.

Bases: ABC.

intent (property)

EnvironmentAllocationContext.intent() -> EnvironmentAllocationIntent

Return the current detached allocation intent.

state (property)

EnvironmentAllocationContext.state() -> EnvironmentAllocationState

Return the last reconciled durable state.

dispatch_precluded (property)

EnvironmentAllocationContext.dispatch_precluded() -> bool

Whether cleanup atomically fenced a prepared, never-dispatched intent.

acknowledged_reconnect_metadata (property)

EnvironmentAllocationContext.acknowledged_reconnect_metadata() -> dict[str, Any] | None

Return detached provider acknowledgement, when known.

prepare (method)

async EnvironmentAllocationContext.prepare(provider_metadata: Mapping[str, Any]) -> EnvironmentAllocationIntent

Persist the final intent before provider dispatch.

mark_dispatched (method)

async EnvironmentAllocationContext.mark_dispatched() -> None

Fence recovery before the irreversible provider call.

acknowledge (method)

async EnvironmentAllocationContext.acknowledge(reconnect_metadata: Mapping[str, Any]) -> None

Persist the exact provider result before returning it.

mark_reaping (method)

async EnvironmentAllocationContext.mark_reaping() -> bool

Fence cleanup against publication; false means publication already won.

mark_reaped (method)

async EnvironmentAllocationContext.mark_reaped() -> None

Record positively completed cleanup after the durable cleanup fence.

Release source · Runtime guarantees · Capability guides

`EnvironmentAllocationIntent`

from cayu.environments import EnvironmentAllocationIntent

Portable identity prepared before one remote provider mutation.

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
`allocation_id`	`str`	`required`
`provider`	`str`	`required`
`adapter_generation`	`str`	`required`
`session_id`	`str`	`required`
`environment_name`	`str`	`required`
`requested_operation`	`EnvironmentFactoryOperation`	`required`
`provider_metadata`	`dict[str, Any]`	`field(default_factory=dict)`
`schema_version`	`int`	`ENVIRONMENT_ALLOCATION_INTENT_SCHEMA_VERSION`

scope (property)

EnvironmentAllocationIntent.scope() -> EnvironmentAllocationScope

with_provider_metadata (method)

EnvironmentAllocationIntent.with_provider_metadata(provider_metadata: Mapping[str, Any]) -> EnvironmentAllocationIntent

to_payload (method)

EnvironmentAllocationIntent.to_payload() -> dict[str, Any]

from_payload (method)

EnvironmentAllocationIntent.from_payload(payload: Mapping[str, Any]) -> EnvironmentAllocationIntent

Release source · Runtime guarantees · Capability guides

`EnvironmentAllocationScope`

from cayu.environments import EnvironmentAllocationScope

Stable provider and adapter generation that own one allocation.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`provider`	`str`	`required`
`adapter_generation`	`str`	`required`

Release source · Runtime guarantees · Capability guides

`EnvironmentAllocationState`

from cayu.environments import EnvironmentAllocationState

Durable progress of one remote allocation intent.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`UNPREPARED`	`class attribute`	`'unprepared'`
`PREPARED`	`class attribute`	`'prepared'`
`DISPATCHED`	`class attribute`	`'dispatched'`
`ACKNOWLEDGED`	`class attribute`	`'acknowledged'`
`REAPING`	`class attribute`	`'reaping'`
`REAPED`	`class attribute`	`'reaped'`

Release source · Runtime guarantees · Capability guides

`EnvironmentAllocationUnsupportedError`

from cayu.environments import EnvironmentAllocationUnsupportedError

Raised before provider mutation when crash-safe allocation is unavailable.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`EnvironmentFactory`

from cayu.environments import EnvironmentFactory

Creates or attaches a concrete environment for a session.

Bases: ABC.

secret_resolution_scope (property)

EnvironmentFactory.secret_resolution_scope() -> Literal['static', 'dynamic']

Declare the immutable secret capability of every CREATE/RECONNECT result.

Static factories must never expose a vault or credential proxy. Runtime snapshots this declaration at registration, fingerprints it for recovery, and rejects violating results before binding or tool dispatch. Undeclared factories remain dynamic, even when one result has no secret resolvers.

execution_profile_identity (property)

EnvironmentFactory.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

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

egress_authority_identity (property)

EnvironmentFactory.egress_authority_identity() -> EgressAuthorityIdentity | None

Return the immutable egress authority proposed for future invocations.

execution_admission_candidate (method)

EnvironmentFactory.execution_admission_candidate(request: EnvironmentFactoryRequest) -> ExecutionAdmissionCandidate | None

Return explicit pre-create evidence without allocating resources.

The default deliberately makes no capability claim. Implementations must keep this hook side-effect free because Cayu calls it before create.

construction_admission_candidate (method)

EnvironmentFactory.construction_admission_candidate() -> ExecutionAdmissionCandidate | None

Return side-effect-free configured capability evidence at app setup.

execution_environment_authority (method)

EnvironmentFactory.execution_environment_authority() -> ExecutionEnvironmentAuthority | None

Return the exact security boundary every materialized runner preserves.

workload_authority (method)

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

Return configured authority for a workload every result must preserve.

configured_artifact_store (property)

EnvironmentFactory.configured_artifact_store() -> ArtifactStore | None

Return the stable artifact store exposed by every factory result.

allocation_scope (method)

EnvironmentFactory.allocation_scope(request: EnvironmentFactoryRequest) -> EnvironmentAllocationScope | None

Declare one crash-recoverable remote allocation boundary.

Returning None means the factory does not allocate a process-external resource through this seam. Implementations that return a scope must also override create_recoverable; Cayu will never fall back to create after accepting a recoverable scope.

create_recoverable (method)

async EnvironmentFactory.create_recoverable(request: EnvironmentFactoryRequest, allocation: EnvironmentAllocationContext) -> EnvironmentFactoryResult

Create or recover exactly one intent-owned remote allocation.

reap_allocation (method)

async EnvironmentFactory.reap_allocation(request: EnvironmentFactoryRequest, allocation: EnvironmentAllocationContext) -> None

Reap abandoned setup without allocating, binding, or running guest work.

Validate the exact intent and adapter scope before taking the durable cleanup fence. Record REAPED only after disposal and dependent reference release are positively complete. Ambiguity must retain retryable ownership. Wrappers forwarding a recoverable factory must forward this hook too.

recover_finalization_disposal (method)

async EnvironmentFactory.recover_finalization_disposal(request: EnvironmentFactoryRequest, state: dict[str, Any]) -> None

Idempotently dispose an allocation whose publication durably finished.

This cleanup-only hook must validate the exact reconnect identity and disposal state, tolerate an already absent allocation, and never create a replacement or access/publish guest output. Factory wrappers must forward this hook when forwarding a factory that supports disposal.

is_allocation_disposed (method)

async EnvironmentFactory.is_allocation_disposed(request: EnvironmentFactoryRequest) -> bool

Positively attest terminal disposal of the exact reconnect allocation.

Called for a new invocation after a completed or failed session, after profile admission. When the environment’s workspace checkpoint policy opts into allocation_replacement="restore", it is also called before reconnecting an interrupted or recovering session; a proof there authorizes a replacement allocation plus checkpoint restore. Return True only with durable provider ownership evidence; absence or uncertainty is not proof. Do not dispose, reconnect, or create resources here. The default preserves exact-allocation reconnect. Wrappers must forward this hook to preserve this capability.

deferred_materialization (property)

EnvironmentFactory.deferred_materialization() -> bool

Whether results defer runner creation to first use.

A deferred factory returns an environment built from a cayu.environments.deferred.DeferredMaterialization: session start binds nothing, and the first runner use creates and binds the runner. Manifests and cayu inspect report this declaration.

release_deferred_materialization (method)

async EnvironmentFactory.release_deferred_materialization(request: EnvironmentFactoryRequest) -> bool

Remove a resource a crashed run materialized for this exact allocation.

Called by recover_incomplete_session with RECONNECT authority for a recovered session that has no pending completion finalization, so the resource holds no output the runtime still has to publish. The session keeps its allocation and materializes again on its next use. Return whether a resource was removed. Absence is not an error. The default manages nothing.

release_idle_resources (method)

async EnvironmentFactory.release_idle_resources() -> None

Trim factory-held idle resources, such as warm spares.

Called by CayuApp.drain_environment_cleanups, which applications may also call while idle. A later session may create such resources again. It must never touch a resource a session owns. The default holds nothing.

close_idle_resources (method)

async EnvironmentFactory.close_idle_resources() -> None

Release factory-held idle resources for good, at application shutdown.

Called by CayuApp.close_idle_environment_resources (the server calls it after its shutdown drain). Afterwards the factory creates no new idle resources, and sessions that still materialize must work without them (for example by starting cold). The default trims like release_idle_resources.

create (method)

async EnvironmentFactory.create(request: EnvironmentFactoryRequest) -> EnvironmentFactoryResult

Return a concrete environment for the requested session.

Release source · Runtime guarantees · Capability guides

`EnvironmentFactoryOperation`

from cayu.environments import EnvironmentFactoryOperation

Whether a factory must allocate a new environment or reconnect one.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`CREATE`	`class attribute`	`'create'`
`RECONNECT`	`class attribute`	`'reconnect'`

Release source · Runtime guarantees · Capability guides

`EnvironmentFactoryRelease`

from cayu.environments import EnvironmentFactoryRelease

EnvironmentFactoryRelease = Callable[[EnvironmentFactoryReleaseAction], Awaitable[None]]

Release source · Runtime guarantees · Capability guides

`EnvironmentFactoryReleaseAction`

from cayu.environments import EnvironmentFactoryReleaseAction

How an unadopted factory result must release its live resources.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`DISCARD`	`class attribute`	`'discard'`
`PRESERVE`	`class attribute`	`'preserve'`

Release source · Runtime guarantees · Capability guides

`EnvironmentFactoryRequest`

from cayu.environments import EnvironmentFactoryRequest

Durable session context used to create or attach an environment.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`session_id`	`str`	`required`
`agent_name`	`str`	`required`
`environment_name`	`str`	`required`
`parent_session_id`	`str \| None`	`None`
`causal_budget_id`	`str \| None`	`None`
`labels`	`dict[str, str]`	`field(default_factory=dict)`
`metadata`	`dict[str, Any]`	`field(default_factory=dict)`
`reconnect_metadata`	`dict[str, Any]`	`field(default_factory=dict)`
`operation`	`EnvironmentFactoryOperation`	`EnvironmentFactoryOperation.CREATE`
`execution_requirements`	`ExecutionRequirements`	`field(default_factory=ExecutionRequirements.trusted)`
`execution_profile_fingerprint`	`str \| None`	`None`
`interaction_id`	`str \| None`	`None`
`replacement_predecessor`	`dict[str, Any]`	`field(default_factory=dict)`

Release source · Runtime guarantees · Capability guides

`EnvironmentFactoryResult`

from cayu.environments import EnvironmentFactoryResult

Concrete environment and pre-adoption release contract for a session.

release owns factory-created resources until workspace binding succeeds. After successful binding, the binding owns the adopted environment lifecycle.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`environment`	`Environment`	`required`
`metadata`	`dict[str, Any]`	`field(default_factory=dict)`
`reconnect_metadata`	`dict[str, Any]`	`field(default_factory=dict)`
`release`	`EnvironmentFactoryRelease \| None`	`None`
`release_timeout_s`	`float`	`DEFAULT_ENVIRONMENT_FACTORY_RELEASE_TIMEOUT_SECONDS`

Release source · Runtime guarantees · Capability guides