cayu.runtime definitions

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.

ContinuationDiscoveryPage

from cayu.collaboration import ContinuationDiscoveryPage

Decorators: @dataclass(frozen=True, slots=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
items	tuple[ContinuationRecovery, ...]	required
next_cursor	str | None	required

Release source · Runtime guarantees · Capability guides

ContinuationRecovery

from cayu.collaboration import ContinuationRecovery

Bases: ContractValue.

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
session	ParticipantSessionReference	required
registration_key	Identifier	required
ticket_key	StrictStr	Field(pattern='^session-continuation:[0-9a-f]{64}$')
preparation_digest	StrictStr	Field(pattern='^[0-9a-f]{64}$')

bounded_input (method)

ContinuationRecovery.bounded_input(value: object) -> Any

immutable_fields (method)

ContinuationRecovery.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

CostAccountingCursor

from cayu import CostAccountingCursor

Bind a refresh to the exact scope, price book, and prior window membership.

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
scope_digest	str	required
pricing_digest	str	required
generation	StrictInt	Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
signature	str	''
since	datetime | None	None
until	datetime | None	None

Release source · Runtime guarantees · Capability guides

CostAccountingOutputTooLarge

from cayu import CostAccountingOutputTooLarge

Requested detailed output exceeds the caller’s explicit byte bound.

Bases: ValueError.

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

Release source · Runtime guarantees · Capability guides

CostAccountingSnapshot

from cayu import CostAccountingSnapshot

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
through_sequence	StrictInt	Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)
totals	SessionCostTotals	required
session_totals	tuple[SessionCostTotals, ...]	()
details	SessionCostSummary | None	None
session_details	tuple[SessionCostSummary, ...]	()
durable_totals	SessionCostTotals | None	None
cursor	CostAccountingCursor | None	None

Release source · Runtime guarantees · Capability guides

DurableWorkerMetrics

from cayu import DurableWorkerMetrics

Bounded, process-local metrics shared by one worker cohort.

init (method)

DurableWorkerMetrics.__init__(*, configured_handler_capacity: int=1) -> None

snapshot (method)

DurableWorkerMetrics.snapshot(*, active_pollers: int | None=None) -> DurableWorkerMetricsSnapshot

handler_started (method)

DurableWorkerMetrics.handler_started() -> None

handler_finished (method)

DurableWorkerMetrics.handler_finished() -> None

claim_completed (method)

DurableWorkerMetrics.claim_completed(*, claimed: bool) -> None

claim_failed (method)

DurableWorkerMetrics.claim_failed(*, store_failure: bool) -> None

claim_cancelled (method)

DurableWorkerMetrics.claim_cancelled() -> None

wake_hint_received (method)

DurableWorkerMetrics.wake_hint_received() -> None

wake_hint_accepted (method)

DurableWorkerMetrics.wake_hint_accepted() -> None

wake_hint_ignored (method)

DurableWorkerMetrics.wake_hint_ignored() -> None

wake_hint_followed_by_successful_claim (method)

DurableWorkerMetrics.wake_hint_followed_by_successful_claim() -> None

wake_hint (method)

DurableWorkerMetrics.wake_hint(*, accepted: bool) -> None

Record one externally classified hint for API compatibility.

fallback_poll (method)

DurableWorkerMetrics.fallback_poll() -> None

maintenance (method)

DurableWorkerMetrics.maintenance(*, reclaim: bool=False, recovery: bool=False) -> None

store_failure (method)

DurableWorkerMetrics.store_failure() -> None

hint_to_claim_latency (method)

DurableWorkerMetrics.hint_to_claim_latency(seconds: float) -> None

admission_to_claim_latency (method)

DurableWorkerMetrics.admission_to_claim_latency(seconds: float) -> None

idle_backoff (method)

DurableWorkerMetrics.idle_backoff(seconds: float) -> None

active_pollers (method)

DurableWorkerMetrics.active_pollers(count: int) -> None

Release source · Runtime guarantees · Capability guides

DurableWorkerMetricsSnapshot

from cayu import DurableWorkerMetricsSnapshot

Content-free operational measurements for one worker cohort.

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
configured_handler_capacity	int	required
active_handlers	int	required
maximum_active_handlers	int	required
active_pollers	int	required
maximum_active_pollers	int	required
claim_attempts	int	required
empty_claims	int	required
successful_claims	int	required
failed_claims	int	required
cancelled_claims	int	required
wake_hints_received	int	required
wake_hints_accepted	int	required
wake_hints_ignored	int	required
wake_hints_followed_by_successful_claims	int	required
fallback_poll_activations	int	required
reclaim_operations	int	required
recovery_operations	int	required
store_failures	int	required
hint_to_claim_latency_samples	int	required
hint_to_claim_latency_total_s	float	required
hint_to_claim_latency_max_s	float	required
admission_to_claim_latency_samples	int	required
admission_to_claim_latency_total_s	float	required
admission_to_claim_latency_max_s	float	required
current_idle_backoff_s	float	required
maximum_idle_backoff_s	float	required

Release source · Runtime guarantees · Capability guides

EnvironmentCapacityError

from cayu import EnvironmentCapacityError

Raised before provisioning when process-local lifecycle capacity is full.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

InvocationContext

from cayu.runtime import InvocationContext

One immutable live authority bundle for an invocation.

Registered collaborators are retained by identity. The context is an in-process value and intentionally has no serialization API.

init (method)

InvocationContext.__init__(*, active_profile: ActiveInvocationExecutionProfile, binding: InvocationBinding, registered_agent: runtime_records.RegisteredAgentState, registered_provider: runtime_records.RegisteredProvider, registered_environment: runtime_records.RegisteredEnvironment | None, runtime_hooks: tuple[runtime_records.RegisteredRuntimeHook, ...], loop_policies: tuple[LoopPolicy, ...], request_loop_policies: tuple[LoopPolicy, ...], budget_policy: BudgetPolicy | None, tool_capability_ceiling: ToolCapabilityCeiling, targeted_tool_grants: tuple[PreparedTargetedToolGrant, ...]=(), _recovery_claim_id: str | None=None, _validated_profile: ExecutionProfileIdentity | None=None, _authority_token: object=None, _work_attempt: WorkAttemptInvocationAuthority | None=None) -> None

require_runtime_authority (method)

InvocationContext.require_runtime_authority() -> None

Revalidate the runtime seal without granting authority to copied fields.

profile (property)

InvocationContext.profile() -> ExecutionProfileIdentity

Return the sole validated profile object owned by this context.

active_profile (property)

InvocationContext.active_profile() -> ActiveInvocationExecutionProfile

binding (property)

InvocationContext.binding() -> InvocationBinding

registered_agent (property)

InvocationContext.registered_agent() -> runtime_records.RegisteredAgentState

registered_provider (property)

InvocationContext.registered_provider() -> runtime_records.RegisteredProvider

registered_environment (property)

InvocationContext.registered_environment() -> runtime_records.RegisteredEnvironment | None

runtime_hooks (property)

InvocationContext.runtime_hooks() -> tuple[runtime_records.RegisteredRuntimeHook, ...]

loop_policies (property)

InvocationContext.loop_policies() -> tuple[LoopPolicy, ...]

request_loop_policies (property)

InvocationContext.request_loop_policies() -> tuple[LoopPolicy, ...]

budget_policy (property)

InvocationContext.budget_policy() -> BudgetPolicy | None

tool_capability_ceiling (property)

InvocationContext.tool_capability_ceiling() -> ToolCapabilityCeiling

targeted_tool_grants (property)

InvocationContext.targeted_tool_grants() -> tuple[PreparedTargetedToolGrant, ...]

recovery_claim_id (property)

InvocationContext.recovery_claim_id() -> str | None

Return runtime-authenticated terminal-recovery ownership, if any.

work_attempt (property)

InvocationContext.work_attempt() -> WorkAttemptInvocationAuthority | None

Return the runtime-only task owner, never caller-supplied metadata.

with_admitted_session (method)

InvocationContext.with_admitted_session(session: Session) -> InvocationContext

Attach the durable admission result without replacing live authority.

with_registered_environment (method)

InvocationContext.with_registered_environment(registered_environment: runtime_records.RegisteredEnvironment, *, validated_profile: ExecutionProfileIdentity) -> InvocationContext

Transfer one post-admission materialized environment into the context.

with_rebound_session (method)

InvocationContext.with_rebound_session(session: Session, *, active_profile: ActiveInvocationExecutionProfile) -> InvocationContext

Carry the same live authority through one authenticated epoch rebind.

with_queued_interaction (method)

InvocationContext.with_queued_interaction(session: Session, *, active_profile: ActiveInvocationExecutionProfile) -> InvocationContext

Transfer this exact same-epoch authority to an atomically started turn.

without_recovery_claim (method)

InvocationContext.without_recovery_claim() -> InvocationContext

Drop a settled recovery claim while preserving invocation authority.

Release source · Runtime guarantees · Capability guides

ModelCompletionManualRecoveryRequired

from cayu import ModelCompletionManualRecoveryRequired

A model dispatch cannot be reconstructed safely without operator input.

Bases: RuntimeError.

init (method)

ModelCompletionManualRecoveryRequired.__init__(message: str) -> None

Release source · Runtime guarantees · Capability guides

ProducerCleanupReclamation

from cayu.collaboration import ProducerCleanupReclamation

Bases: ContractValue.

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
retirement	ProducerCleanupRetirement	required
removed	StrictInt	Field(ge=0, le=32)
remaining	StrictBool	required

bounded_input (method)

ProducerCleanupReclamation.bounded_input(value: object) -> Any

immutable_fields (method)

ProducerCleanupReclamation.immutable_fields() -> ContractValue

Release source · Runtime guarantees · Capability guides

ProducerCleanupRetirement

from cayu.collaboration import ProducerCleanupRetirement

Bases: ContractValue.

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
receiver	ObjectRef	required
namespace	NamespaceRef	required

bounded_input (method)

ProducerCleanupRetirement.bounded_input(value: object) -> Any

immutable_fields (method)

ProducerCleanupRetirement.immutable_fields() -> ContractValue

coherent (method)

ProducerCleanupRetirement.coherent()

Release source · Runtime guarantees · Capability guides

SessionContinuationOwner

from cayu.runtime import SessionContinuationOwner

Owner-level receiving service, not a wait arbiter or automatic worker.

init (method)

SessionContinuationOwner.__init__(*, store: SessionStore, owner: OwnerRef, receiver: ContinuationLatchReceiver, receiver_capability: CapabilityDescriptor, redactor: SecretRedactor, temporary_permits: TemporaryServicePermitAuthority | None=None, track: Callable[[asyncio.Task[Any]], None] | None=None) -> None

latch (method)

async SessionContinuationOwner.latch(candidate: ContinuationLatch) -> ContinuationRecord

prepare (method)

async SessionContinuationOwner.prepare(intent: ContinuationWait, *, invocation: InvocationContext) -> ContinuationRecord

Retain ticket and registration intent while the actual writer is active.

recover_writer (method)

async SessionContinuationOwner.recover_writer(candidate: ContinuationTicket, *, invocation: InvocationContext) -> ContinuationRecord

Attach an ARMING external ticket to the exact native recovery claim.

park_recovered (method)

async SessionContinuationOwner.park_recovered(candidate: ContinuationTicket, *, invocation: InvocationContext) -> ContinuationRecord

Park after the recovered runtime reaches its complete whole-turn boundary.

park (method)

async SessionContinuationOwner.park(candidate: ContinuationTicket, *, invocation: InvocationContext) -> ContinuationRecord

Acknowledge parking without releasing or replacing the session writer.

retire (method)

async SessionContinuationOwner.retire(candidate: ContinuationRetirement, *, invocation: InvocationContext | None=None) -> ContinuationRecord

Retire with writer authority, or exclude an overtaken unconsumed wait.

Registered owners may recover supersession without retaining an old in-process invocation. The store must prove writer advancement atomically. This never authorizes admission or settlement of an in-flight consumption.

exclude (method)

async SessionContinuationOwner.exclude(candidate: ContinuationRetirement, *, invocation: InvocationContext) -> ContinuationRecord

Record an exact destination refusal without dispatching admission.

retire_released (method)

async SessionContinuationOwner.retire_released(candidate: ContinuationReleasedRetirement) -> ContinuationRecord

Retire only through native release and acknowledged service evidence.

admit (method)

async SessionContinuationOwner.admit(candidate: ContinuationConsumption, command: AdmitInvocationCommand, *, invocation: InvocationContext) -> tuple[InvocationMutationResult, ContinuationRecord]

prepare_temporary_admission (method)

async SessionContinuationOwner.prepare_temporary_admission(candidate: TemporaryServiceIntent, command: AdmitInvocationCommand, *, invocation: InvocationContext) -> tuple[InvocationMutationResult, TemporaryServiceRecord]

Join runtime preparation to durable registration, then native admission.

No public caller may supply this invocation authority. The configured clarification coordinator must configure current source disclosure authorization on the permit owner’s admission guard. That guard belongs to the durable registration task, not its cancellable observer.

admit_temporary (method)

async SessionContinuationOwner.admit_temporary(candidate: TemporaryServiceAdmission, command: AdmitInvocationCommand, *, invocation: InvocationContext, wait_for_settlement: bool=False) -> tuple[InvocationMutationResult, TemporaryServiceRecord]

Consume a registered permit after ordinary runtime preparation gates.

This is not a public caller receipt entrance. Both the runtime context and the foreign durable permit must authenticate the complete command.

exclude_temporary (method)

async SessionContinuationOwner.exclude_temporary(candidate: TemporaryServicePreparation) -> TemporaryServiceRecord

Fence a prepared native operation before settling foreign responsibility.

This is an explicit coordinator decision, never an inference from timeout or cancellation. The native compare-and-publication races admission under the same session transaction; admitted work cannot take this transition.

reconcile_temporary (method)

async SessionContinuationOwner.reconcile_temporary(candidate: TemporaryServiceAdmission) -> TemporaryServiceRecord

Reconcile native return before discharging the foreign obligation.

If the foreign acknowledgement is lost, the source’s exact returned record remains available to the registered settlement reader. Neither missing admission nor caller cancellation is an exclusion witness.

service_temporary (method)

async SessionContinuationOwner.service_temporary(app: CayuApp, request: ResumeRequest, candidate: TemporaryServiceIntent, *, participant_context: CollaborationAccessContext, delivery: Callable[[InvocationContext], Awaitable[None]] | None=None, wait_for_settlement: bool=False) -> TemporaryServiceRecord

Explicit internal service, with durable reconciliation before dispatch.

The registered clarification coordinator configures the permit owner’s admission guard to retain current source disclosure through registration. The guard ends before provider serialization acquires its own disclosure authority; holding a non-reentrant policy guard around this entire call would deadlock. This is not an independently authorized SDK entrance. Cancelling observation does not prove the owned service stopped.

service (method)

async SessionContinuationOwner.service(app: CayuApp, request: ResumeRequest, candidate: ContinuationService, *, participant_context: CollaborationAccessContext | None=None) -> ContinuationRecord

Observe normal resume or exact reconciliation with a bounded waiter.

reconcile_admission (method)

async SessionContinuationOwner.reconcile_admission(candidate: ContinuationConsumption) -> ContinuationRecord

Settle a retained handoff only from positive typed admission evidence.

drain (method)

async SessionContinuationOwner.drain() -> None

Release source · Runtime guarantees · Capability guides

TaskGroupInvocationSettlementPending

from cayu.tasks import TaskGroupInvocationSettlementPending

Retain settlement and await its retry() to publish owner return.

Retry never executes the invocation again. Process loss before publication deliberately leaves the durable barrier fenced.

Bases: RuntimeError.

init (method)

TaskGroupInvocationSettlementPending.__init__(settlement: _InvocationSettlement) -> None

Release source · Runtime guarantees · Capability guides

UsageAccountingSnapshot

from cayu import UsageAccountingSnapshot

Exact usage through a store-owned sequence boundary, without source events.

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
through_sequence	StrictInt	Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)
generation	StrictInt	Field(default=0, ge=0, le=MAX_DURABLE_JSON_INTEGER)
summary	SessionUsageSummary	required
session_summaries	tuple[SessionUsageSummary, ...]	()
provider_summaries	tuple[UsageIdentitySummary, ...]	()
model_summaries	tuple[UsageIdentitySummary, ...]	()

Release source · Runtime guarantees · Capability guides

UsageIdentitySummary

from cayu import UsageIdentitySummary

Requested identity breakdown, including its distinct session membership.

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
provider_name	str | None	required
model	str | None	required
session_ids	tuple[str, ...]	required
model_steps	StrictInt	Field(ge=0)
usage	AggregateUsageMetrics	required

Release source · Runtime guarantees · Capability guides