cayu.testing.CayuApp

Part of cayu.testing.base. Read the Python API overview and install the required extra.

from cayu.testing import CayuApp

Application runtime for registered agents, providers, and session state.

init (method)

CayuApp.__init__(*, config: CayuConfig | None=None, session_store: SessionStore | None=None, resource_access_policy: ResourceAccessPolicy | None=None, task_store: TaskStore | None=None, knowledge_store: KnowledgeStore | None=None, knowledge_access_scope: KnowledgeAccessScope | None=None, knowledge_review_namespace: str | None=None, knowledge_review_labels: dict[str, str] | None=None, dispatcher: Dispatcher | None=None, budget_policy: BudgetPolicy | None=None, budget_store: BudgetStore | None=None, budget_ledger: BudgetLedger | None=None, budget_binding_receiver: BudgetBindingReceiver | None=None, enable_common_root_budget_binding: bool=False, event_watcher_store: EventWatcherStore | None=None, runtime_hooks: Iterable[RuntimeHook] | None=None, loop_policies: Iterable[LoopPolicy] | None=None, mcp_manifest_policy: McpManifestPolicy | None=None, human_review_policy: HumanReviewPolicy | None=None, session_message_access_policy: SessionMessageAccessPolicy | None=None, collaboration_store: CollaborationStore | None=None, collaboration: CollaborationRegistration | None=None, collaboration_requests: RequestRegistration | None=None, session_exports: SessionExportRegistration | None=None, context_view_extensions: Iterable[ContextViewExtensionRegistration] | None=None, tool_result_projection_policy: ToolResultProjectionPolicy | None=None, execution_profile_policy: ExecutionProfilePolicy | None=None, completion_verifier_profile_policy: CompletionVerifierProfilePolicy | None=None, browser_control: BrowserControlConfig | None=None, egress_authority_adoption_handler: EgressAuthorityAdoptionHandler | None=None, context_counting: ContextCountingConfig | None=None, request_footprint: RequestFootprintConfig | None=None, event_sinks: Iterable[EventSink] | None=None, enable_logging: bool=True, runtime_timing: RuntimeTimingConfig | None=None, timing_sinks: Iterable[RuntimeTimingSink] | None=None, secret_redactor: SecretRedactor | None=None, public_authority_alias_keyring: PublicAuthorityAliasKeyring | None=None, session_closure_stores: Iterable[SessionClosureStore] | None=None, clock: Callable[[], datetime] | None=None, session_execution: SessionExecutionConfig | None=None, model_policy: ModelPolicy | None=None, owned_resources: Iterable[SupportsAsyncClose]=()) -> None

accept_collaboration_request (method)

async CayuApp.accept_collaboration_request(request: CollaborationRequest, *, context: MandateAccessContext) -> RequestReceipt

Retain a question/contribution; never launch an agent or session.

inspect_collaboration_request (method)

async CayuApp.inspect_collaboration_request(expected: RequestCommand, *, context: MandateAccessContext) -> RequestSnapshot | None

lookup_collaboration_request (method)

async CayuApp.lookup_collaboration_request(expected: RequestCommand | RequestControlCommand, *, context: MandateAccessContext) -> ExactLookup[RequestReceipt | RequestControlReceipt]

control_collaboration_request (method)

async CayuApp.control_collaboration_request(request: RequestControl, *, context: MandateAccessContext) -> RequestControlReceipt

drain_collaboration_requests (method)

async CayuApp.drain_collaboration_requests(*, timeout_s: float | None=None) -> None

Stop this application’s collaboration work and wait for what it started.

The collaboration store stays open: other applications sharing it are unaffected, and its owner closes it. This waits for every operation still pending on the store, up to timeout_s (by default this application’s observation bound); work still running raises CollaborationUnavailable.

admit_collaboration_request (method)

async CayuApp.admit_collaboration_request(command: RequestAdmissionCommand, *, context: MandateAccessContext) -> RequestAdmissionReceipt

Record a trusted receiving-owner admission decision; never launch work.

plan_collaboration_request (method)

async CayuApp.plan_collaboration_request(request: RequestPlanningRequest, *, context: MandateAccessContext) -> RequestPlanningRecord

Explicitly retain and prepare a registered decision without launching work.

lookup_collaboration_plan (method)

async CayuApp.lookup_collaboration_plan(expected: RequestPlanningRequest, *, context: MandateAccessContext) -> ExactLookup[RequestPlanningRecord]

Compare complete retained planning intent under current read authority.

reconcile_collaboration_plan (method)

async CayuApp.reconcile_collaboration_plan(expected: RequestPlanningRequest, *, context: MandateAccessContext) -> RequestPlanningRecord

Make one bounded recovery pass using only the retained operation keys.

control_collaboration_plan (method)

async CayuApp.control_collaboration_plan(command: RequestPlanningControl, *, context: MandateAccessContext) -> RequestPlanningRecord

Fence exact local preparation under current administrative authority.

list_pending_collaboration_plans (method)

async CayuApp.list_pending_collaboration_plans(*, context: MandateAccessContext, after: RequestPlanningCursor | None=None, limit: int=32) -> RequestPlanningPage

Discover durable plans under scope-wide maintenance read authority.

record_collaboration_progress (method)

async CayuApp.record_collaboration_progress(command: RequestProgressCommand, *, context: MandateAccessContext) -> RequestProgressReceipt

prepare_recipient_admission (method)

async CayuApp.prepare_recipient_admission(creation: RecipientSessionCreationRequest, *, context: CollaborationAccessContext) -> PreparedRecipientAdmission

Read an inert FRESH child’s proposal; admission separately authenticates it.

prepare_recipient_creation (method)

async CayuApp.prepare_recipient_creation(creation: RecipientSessionCreationRequest, *, context: CollaborationAccessContext) -> FreshRecipientPreparation

Freeze an inert FRESH proposal without creating a session or permit.

prepare_recipient_continuation (method)

async CayuApp.prepare_recipient_continuation(request: RecipientContinuationRequest, *, context: CollaborationAccessContext) -> PreparedRecipientAdmission

Propose one exact completed boundary; never append input or acquire a writer.

prepare_recipient_fork (method)

async CayuApp.prepare_recipient_fork(creation: RecipientSessionCreationRequest, source: ContextViewSelectionRequest, *, source_participant: ParticipantRef, context: CollaborationAccessContext, deadline_at_ms: int) -> ForkRecipientPreparation

Freeze base preflight and exact historical selection without effects.

collaboration_admission_reader (method)

CayuApp.collaboration_admission_reader() -> RequestAdmissionReader

Return this application’s authenticated exact historical admission reader.

recover_collaboration_admission (method)

async CayuApp.recover_collaboration_admission(expected: RequestSnapshot, *, context: MandateAccessContext) -> ExactLookup[RequestAdmissionReceipt]

Recover exact admission from a discovered request, without granting execution.

prepare_producer_output (method)

async CayuApp.prepare_producer_output(proposal: ProducerOutputProposal, execution: ParticipantSessionExecutionRequest, *, context: MandateAccessContext) -> ProducerOutputRegistration

Derive an inert producer command from exact admitted native preparation.

register_producer_output (method)

async CayuApp.register_producer_output(command: ProducerOutputRegistration, execution: ParticipantSessionExecutionRequest, *, context: MandateAccessContext) -> ProducerOutputRecord

Retain exact producer responsibility; registration never dispatches work.

lookup_producer_registration (method)

async CayuApp.lookup_producer_registration(expected: ProducerOutputRegistration | ProducerOutputRecovery, *, context: CollaborationAccessContext) -> ExactLookup[ProducerOutputRegistration]

Read authenticated historical registration, not new execution authority.

pending_producer_outputs (method)

async CayuApp.pending_producer_outputs(participant: ParticipantRef, *, context: CollaborationAccessContext, after: int=0, limit: int=32) -> ProducerPendingPage

Discover bounded unsettled responsibility, including closed requests.

inspect_producer_output (method)

async CayuApp.inspect_producer_output(expected: ProducerOutputRegistration | ProducerOutputRecovery, *, context: CollaborationAccessContext) -> ExactLookup[ProducerOutputInspection]

Inspect exact source evidence without implying execution or delivery.

lookup_producer_completion (method)

async CayuApp.lookup_producer_completion(expected: ProducerOutputRegistration | ProducerOutputRecovery, *, context: CollaborationAccessContext) -> ExactLookup[ProducerCompletionRecord]

Read exact retained completion references; do not disclose output content.

retain_producer_completion (method)

async CayuApp.retain_producer_completion(command: ProducerOutputRegistration, *, context: CollaborationAccessContext) -> ProducerCompletionRecord

Retain authenticated native completion without restarting production.

settle_producer_output (method)

async CayuApp.settle_producer_output(command: ProducerOutputRegistration, *, context: CollaborationAccessContext) -> ProducerCleanupFinalized

Release and settle only after exact output, effect and accounting evidence.

reclaim_producer_cleanup (method)

async CayuApp.reclaim_producer_cleanup(namespace: NamespaceRef, *, context: CollaborationAccessContext, limit: int=32) -> ProducerCleanupReclamation

Drain bounded native cleanup receipts after positive source-history retirement.

reconcile_producer_delivery (method)

async CayuApp.reconcile_producer_delivery(recovery: ProducerDeliveryRecovery, *, context: CollaborationAccessContext, exclude: bool=False) -> ProducerDeliveryStatus

Read an exact receiving outcome or request its authenticated exclusion.

retire_producer_export (method)

async CayuApp.retire_producer_export(command: ProducerOutputRegistration, destination: OperationRef, *, context: CollaborationAccessContext) -> ProducerExportCleanupStatus

Retire an export after request closure or authenticated delivery exclusion.

service_producer_disposition (method)

async CayuApp.service_producer_disposition(command: ProducerOutputRegistration, *, context: CollaborationAccessContext) -> ProducerDispositionStatus

Service retained closure using the producer’s frozen stop scope.

execute_producer_output (method)

async CayuApp.execute_producer_output(command: ProducerOutputRegistration, execution: ParticipantSessionExecutionRequest, *, context: CollaborationAccessContext, producer_context: MandateAccessContext) -> AsyncGenerator[Event, None]

Execute a registered producer through current native admission exactly once.

export_producer_output (method)

async CayuApp.export_producer_output(command: ProducerOutputRegistration, destination: OperationRef, *, context: SessionExportAccessContext) -> ProducerExportRecord

Service one retained output export with current disclosure authorization.

record_producer_progress (method)

async CayuApp.record_producer_progress(command: ProducerOutputRegistration, occurrence: ProducerProgressOccurrence, *, context: MandateAccessContext) -> RequestProgressReceipt

Publish an exact content-free native milestone, not execution authority.

publish_producer_outcome (method)

async CayuApp.publish_producer_outcome(command: ProducerOutputRegistration, *, destination: OperationRef | None=None, context: SessionExportAccessContext) -> RequestOutcomeReceipt

Elect the retained answer/failure; do not imply delivery or quiescence.

deliver_producer_output (method)

async CayuApp.deliver_producer_output(command: ProducerOutputRegistration, destination: OperationRef, *, context: SessionExportAccessContext, prepare_only: bool=False) -> ProducerDeliveryRecord

Prepare or service one exact peer append; never imply provider exposure.

lookup_collaboration_admission (method)

async CayuApp.lookup_collaboration_admission(expected: RequestAdmissionCommand, *, context: MandateAccessContext) -> ExactLookup[RequestAdmissionReceipt]

Read exact historical admission evidence without renewing execution authority.

publish_collaboration_outcome (method)

async CayuApp.publish_collaboration_outcome(command: RequestOutcomeCommand, *, context: MandateAccessContext) -> RequestOutcomeReceipt

register_collaboration_observation (method)

async CayuApp.register_collaboration_observation(expected: RequestCommand, observation: RequestObservation, *, context: MandateAccessContext) -> RequestObservationReceipt

read_collaboration_observation (method)

async CayuApp.read_collaboration_observation(expected: RequestCommand, observation: RequestObservation, *, context: MandateAccessContext) -> RequestObservationPage

register_collaboration_wait (method)

async CayuApp.register_collaboration_wait(wait: CollaborationWait, *, context: MandateAccessContext) -> WaitSnapshot

list_collaboration_waits (method)

async CayuApp.list_collaboration_waits(*, context: CollaborationAccessContext, cursor: WaitDiscoveryCursor | None=None, limit: int=32) -> WaitDiscoveryPage

Discover retained wait identities; a page is neither a claim nor quiescence.

list_participant_sessions (method)

async CayuApp.list_participant_sessions(participant: ParticipantRef, *, context: CollaborationAccessContext, cursor: ParticipantSessionCursor | None=None, limit: int=32) -> tuple[tuple[ParticipantSessionReference, ...], ParticipantSessionCursor | None]

Discover exact creation identities, not execution grants or global quiescence.

list_session_continuations (method)

async CayuApp.list_session_continuations(session: ParticipantSessionReference, *, context: CollaborationAccessContext, after: str | None=None, limit: int=32) -> ContinuationDiscoveryPage

Discover native continuation identities within one authenticated incarnation.

recover_session_continuation (method)

async CayuApp.recover_session_continuation(expected: ContinuationRecovery, *, context: CollaborationAccessContext) -> ContinuationRecord

Reconstruct an exact retained continuation; this does not authorize servicing.

recover_collaboration_wait (method)

async CayuApp.recover_collaboration_wait(expected: WaitRecovery, *, context: MandateAccessContext) -> ExactLookup[CollaborationWait]

Read the exact original wait under current source authorization; never dispatch.

observe_collaboration_wait (method)

async CayuApp.observe_collaboration_wait(wait: CollaborationWait, *, context: MandateAccessContext) -> WaitSnapshot

inspect_collaboration_wait (method)

async CayuApp.inspect_collaboration_wait(wait: CollaborationWait, *, context: MandateAccessContext) -> WaitSnapshot | None

lookup_collaboration_wait (method)

async CayuApp.lookup_collaboration_wait(wait: CollaborationWait, *, context: MandateAccessContext) -> ExactLookup[WaitRegistration]

cancel_collaboration_wait (method)

async CayuApp.cancel_collaboration_wait(wait: CollaborationWait, *, context: MandateAccessContext, expired: bool=False) -> WaitSnapshot

deliver_collaboration_wait (method)

async CayuApp.deliver_collaboration_wait(wait: CollaborationWait, *, context: MandateAccessContext, continuation_owner) -> WaitSnapshot

exclude_collaboration_wait (method)

async CayuApp.exclude_collaboration_wait(wait: CollaborationWait, *, context: MandateAccessContext, continuation_owner, invocation) -> WaitSnapshot

collaboration_wait_latch_receiver (method)

CayuApp.collaboration_wait_latch_receiver()

Return the durable receiver used by session-bound wait delivery.

list_due_collaboration_requests (method)

async CayuApp.list_due_collaboration_requests(*, context: MandateAccessContext, cursor: RequestDueCursor | None=None, limit: int=32) -> RequestDuePage

Inspect retained responsibilities without claiming or dispatching work.

initialize_session_exports (method)

async CayuApp.initialize_session_exports(session_id: str, *, context: SessionExportAccessContext) -> SessionExportNamespace

export_session (method)

async CayuApp.export_session(request: SessionExportRequest, *, context: SessionExportAccessContext, invocation: ToolContext | None=None) -> SessionExportReceipt

lookup_session_export (method)

async CayuApp.lookup_session_export(request: SessionExportRequest, *, context: SessionExportAccessContext) -> ExactLookup[SessionExportReceipt]

read_session_export (method)

async CayuApp.read_session_export(request: SessionExportRequest, *, context: SessionExportAccessContext) -> dict[str, Any]

open_clarification (method)

async CayuApp.open_clarification(command: ClarificationOpenCommand, *, source: SessionExportRequest, context: SessionExportAccessContext) -> ClarificationOpenReceipt

Publish one exact question; never launch or implicitly deliver service.

prepare_clarification_delivery (method)

async CayuApp.prepare_clarification_delivery(intent: ClarificationDeliveryIntent, *, context: SessionExportAccessContext) -> ClarificationDeliveryReceipt

Retain an exact inert delivery intent without attempting peer append.

deliver_clarification (method)

async CayuApp.deliver_clarification(intent: ClarificationDeliveryIntent, *, context: SessionExportAccessContext) -> ClarificationDeliveryReceipt

Deliver through the peer owner without starting a service or exposing a model.

service_clarification (method)

async CayuApp.service_clarification(request: ClarificationServiceRequest, *, context: SessionExportAccessContext, delivery_context: SessionExportAccessContext | None=None) -> ClarificationServiceReceipt

Explicitly service an authenticated question on its existing recipient.

reconcile_clarification_service (method)

async CayuApp.reconcile_clarification_service(request: ClarificationServiceRequest | ClarificationServiceRecovery, *, context: CollaborationAccessContext) -> ClarificationServiceReceipt

Reconcile exact receiving evidence without granting disclosure or execution.

list_due_clarification_questions (method)

async CayuApp.list_due_clarification_questions(*, context: CollaborationAccessContext, cursor: ClarificationDueCursor | None=None, limit: int=32) -> ClarificationDueQuestionPage

Discover content-free due identities using the native owner’s clock.

expire_clarification_question (method)

async CayuApp.expire_clarification_question(request: ClarificationExpiryRequest, *, context: CollaborationAccessContext) -> ClarificationExpiryReceipt

Expire an exact due question; pending service and delivery remain owned.

list_pending_clarification_deliveries (method)

async CayuApp.list_pending_clarification_deliveries(*, context: CollaborationAccessContext, cursor: ClarificationDueCursor | None=None, limit: int=32) -> ClarificationPendingDeliveryPage

Discover content-free exact delivery identities for administrative recovery.

reconcile_clarification_delivery (method)

async CayuApp.reconcile_clarification_delivery(recovery: ClarificationDeliveryRecovery, *, context: CollaborationAccessContext) -> ClarificationDeliveryReceipt

Read exact receiving evidence; never append, disclose payloads or infer exclusion.

list_pending_clarification_services (method)

async CayuApp.list_pending_clarification_services(*, context: CollaborationAccessContext, cursor: ClarificationDueCursor | None=None, limit: int=32) -> ClarificationPendingServicePage

Discover bounded maintenance identities, never peer payloads or dispatch grants.

exclude_clarification_delivery (method)

async CayuApp.exclude_clarification_delivery(recovery: ClarificationDeliveryRecovery, *, context: CollaborationAccessContext) -> ClarificationDeliveryReceipt

Fence an exact prepared delivery under independent registered cleanup authority.

inspect_clarification_services (method)

async CayuApp.inspect_clarification_services(ticket: ContinuationTicket, *, context: CollaborationAccessContext, cursor: ClarificationDueCursor | None=None, limit: int=32) -> ClarificationServiceInspectionPage

Inspect bounded native ticket history, including unregistered preparations.

exclude_clarification_service (method)

async CayuApp.exclude_clarification_service(request: ClarificationServiceRequest | ClarificationServiceRecovery, *, context: CollaborationAccessContext) -> ClarificationServiceReceipt

Explicitly fence exact unadmitted service; never infer exclusion from interruption.

reply_to_clarification (method)

async CayuApp.reply_to_clarification(request: ClarificationReplyRequest, *, context: SessionExportAccessContext) -> ClarificationReplyAcceptance

Elect a source-authenticated service reply without dispatch or delivery.

close_clarification (method)

async CayuApp.close_clarification(command: ClarificationCloseCommand, *, context: MandateAccessContext) -> ClarificationCloseReceipt

Close a question, without cancelling or settling underlying service work.

inspect_clarification (method)

async CayuApp.inspect_clarification(expected: ClarificationOpenCommand, *, context: MandateAccessContext) -> ExactLookup[ClarificationQuestionState]

Inspect current question state under exact historical request authority.

lookup_clarification (method)

async CayuApp.lookup_clarification(expected: ClarificationOpenCommand | ClarificationCloseCommand, *, context: MandateAccessContext) -> ExactLookup[ClarificationOpenReceipt | ClarificationCloseReceipt]

Read exact historical question metadata without renewing authority.

inspect_clarification_source (method)

async CayuApp.inspect_clarification_source(request: SessionExportRequest, *, sender: ParticipantRef, audience: ParticipantRef, context: SessionExportAccessContext, expected: ClarificationSource | None=None) -> ClarificationSource

Resolve exact source evidence under current export authorization.

The immutable result contains identities and commitments, not text or private provider state. It cannot authorize later question publication, delivery or exposure; those operations acquire their own current guards.

settle_session_export (method)

async CayuApp.settle_session_export(request: SessionExportSettlementRequest, *, context: SessionExportAccessContext) -> SessionExportSettlementReceipt

reconcile_session_export (method)

async CayuApp.reconcile_session_export(request: SessionExportRequest, *, context: SessionExportAccessContext) -> SessionExportReconciliation

Settle published admission or exclude a retained unpublished preparation.

drain_browser_control (method)

async CayuApp.drain_browser_control(*, timeout_s: float=5.0) -> bool

Stop browser-control issuance and settle its guest channels and publications.

Returns True when browser control is not configured. When a Cayu server hosts browser control, the server drains it before the application.

drain_session_operations (method)

async CayuApp.drain_session_operations(*, timeout_s: float=10.0) -> bool

Wait for session store writes that outlived the call that started them.

A store write that exceeds its bounded wait is cancelled and kept until it settles, a provider-operation reconciliation runs past the model step that started it, a terminal-finalization claim heartbeat no task accepted may still be renewing after it was stopped, a task worker cancelled mid-renewal leaves its lease write running, and a local execution attempt’s supervisor wait or settlement write can outlive its caller. This waits for that work without cancelling it, and returns False if any is still running. A cancelled write is not reported: its caller already received a timeout and either reconciles it from durable state or treats it as best-effort. A reconciliation or final session accounting that fails, or a late provider cancellation that fails, raises RuntimeError naming the failure types, or an ExceptionGroup of them, once. A drain cancelled before it reports consumes no failure.

drain_event_watchers (method)

async CayuApp.drain_event_watchers(*, timeout_s: float=10.0) -> bool

Wait for event watcher deliveries still running after their caller left.

When a run_event_watchers() call is cancelled, its delivery keeps its lease until the handler settles and then records the outcome; a synchronous handler runs until it returns. This waits for that work without cancelling it, and returns False if any is still running. A delivery whose outcome could not be recorded raises RuntimeError naming its status, once, including one a cancelled run_event_watchers() call had collected but never returned; a later drain or shutdown attempt does not report it again.

drain_verified_completions (method)

async CayuApp.drain_verified_completions(*, timeout_s: float=10.0) -> bool

Wait for completion verification and result resolution still running.

A verifier or resolver can outlive the call that started it, for example after its execution timeout or a caller’s cancellation, together with its claim heartbeat and final settlement. This waits for that work without cancelling it, and returns False if any is still running. Work that finished unsuccessfully has its failure raised by one drain or shutdown attempt only, and stays retained for the exact retry. Work that a verified task worker holds is reported by that worker instead.

drain_session_exports (method)

async CayuApp.drain_session_exports(*, timeout_s: float | None=None) -> None

Seal new export work and wait, up to timeout_s, for retained owners.

initialize_collaboration (method)

async CayuApp.initialize_collaboration() -> CollaborationInitialization

Explicitly provision or recover the exact registered collaboration owner.

inspect_collaboration_namespace (method)

async CayuApp.inspect_collaboration_namespace(*, context: CollaborationAccessContext) -> NamespaceInspection

inspect_collaboration_retirement (method)

async CayuApp.inspect_collaboration_retirement(namespace: NamespaceRef, *, context: CollaborationAccessContext) -> NamespaceRetirementEvidence | None

seal_collaboration_namespace (method)

async CayuApp.seal_collaboration_namespace(request: NamespaceSeal, *, context: CollaborationAccessContext) -> LifecycleReceipt

rotate_collaboration_namespace (method)

async CayuApp.rotate_collaboration_namespace(request: NamespaceRotate, *, context: CollaborationAccessContext) -> LifecycleReceipt

retire_collaboration_namespace (method)

async CayuApp.retire_collaboration_namespace(request: NamespaceRetire, *, context: CollaborationAccessContext) -> LifecycleReceipt

prune_collaboration_namespace (method)

async CayuApp.prune_collaboration_namespace(request: NamespacePrune, *, context: CollaborationAccessContext) -> LifecycleReceipt

lookup_collaboration_lifecycle_operation (method)

async CayuApp.lookup_collaboration_lifecycle_operation(expected: LifecycleCommand, *, context: CollaborationAccessContext) -> ExactLookup[LifecycleReceipt]

change_participant_lifecycle (method)

async CayuApp.change_participant_lifecycle(request: ParticipantLifecycleChange, *, context: CollaborationAccessContext) -> LifecycleReceipt

list_participant_obligations (method)

async CayuApp.list_participant_obligations(participant: ParticipantRef, *, context: CollaborationAccessContext, cursor: ParticipantObligationCursor | None=None, pending_only: bool=True, limit: int=32) -> ParticipantObligationPage

create_participant (method)

async CayuApp.create_participant(request: ParticipantCreate, *, context: CollaborationAccessContext) -> ParticipantReceipt

create_participant_session (method)

async CayuApp.create_participant_session(creation: ParticipantSessionCreationRequest, *, participant: ParticipantRef, context: CollaborationAccessContext) -> tuple[Session, ParticipantSessionCreationReceipt]

create_recipient_session (method)

async CayuApp.create_recipient_session(creation: RecipientSessionCreationRequest, *, context: CollaborationAccessContext, resource_owner: LocalArtifactResourceOwner | None=None, preparation: FreshRecipientPreparation | ForkRecipientCreationPreparation | ResourceRecipientCreationPreparation | None=None) -> tuple[Session, RecipientSessionCreationReceipt]

Create one inert recipient child from fresh or exact retained material.

The existing participant-session store remains the atomic identity and transcript owner. This boundary only prepares authenticated historical input and records recipient-specific provenance in its creation key. It never executes the prepared request.

settle_recipient_resource_handoff (method)

async CayuApp.settle_recipient_resource_handoff(receipt: RecipientSessionCreationReceipt, *, resource_owner: LocalArtifactResourceOwner, source_owners: tuple[LocalArtifactResourceOwner, ...], context: CollaborationAccessContext) -> None

Release source pins only after durable recipient commitment.

reconcile_recipient_resource_handoff (method)

async CayuApp.reconcile_recipient_resource_handoff(creation: RecipientSessionCreationRequest, *, resource_owner: LocalArtifactResourceOwner, source_owners: tuple[LocalArtifactResourceOwner, ...], context: CollaborationAccessContext) -> RecipientSessionCreationReceipt

Recover handoff ownership when the caller lost the child receipt.

lookup_recipient_session (method)

async CayuApp.lookup_recipient_session(creation: RecipientSessionCreationRequest, *, context: CollaborationAccessContext, resource_owner: LocalArtifactResourceOwner | None=None) -> tuple[Session, RecipientSessionCreationReceipt] | None

Recover an exact recipient creation without rereading source state.

execute_participant_session (method)

async CayuApp.execute_participant_session(execution: ParticipantSessionExecutionRequest, *, participant: ParticipantRef, context: CollaborationAccessContext) -> AsyncIterator[Event]

Activate an inert participant root through authenticated durable admission.

execute_participant_session_to_wait (method)

async CayuApp.execute_participant_session_to_wait(execution: ParticipantSessionExecutionRequest, wait: CollaborationWait, *, participant: ParticipantRef, context: CollaborationAccessContext, wait_context: MandateAccessContext) -> AsyncIterator[Event]

Execute an authenticated inert root to an explicit whole-turn wait.

Request targets are authenticated by the registered wait owner. Only the engine’s admitted context creates the delivery ticket; this entrance does not create a recipient or automatically service a clarification.

exclude_participant_session_wait (method)

async CayuApp.exclude_participant_session_wait(execution: ParticipantSessionExecutionRequest, wait: CollaborationWait, *, participant: ParticipantRef, context: CollaborationAccessContext, wait_context: MandateAccessContext) -> ParticipantSessionWaitExclusionReceipt

Exclude released, unfinished wait preparation without restarting execution.

configure_participant (method)

async CayuApp.configure_participant(request: ParticipantConfigure, *, context: CollaborationAccessContext) -> ParticipantReceipt

change_participant_alias (method)

async CayuApp.change_participant_alias(request: ParticipantAliasChange, *, context: CollaborationAccessContext) -> ParticipantReceipt

inspect_participant (method)

async CayuApp.inspect_participant(participant: ParticipantRef, *, context: CollaborationAccessContext) -> ParticipantInspection

resolve_participant_alias (method)

async CayuApp.resolve_participant_alias(alias: str, *, context: CollaborationAccessContext) -> ParticipantAlias | None

discover_participants (method)

async CayuApp.discover_participants(*, context: CollaborationAccessContext, cursor: ParticipantCursor | None=None, limit: int=32) -> ParticipantPage

list_participant_events (method)

async CayuApp.list_participant_events(*, context: CollaborationAccessContext, cursor: ParticipantEventCursor | None=None, limit: int=32) -> ParticipantEventPage

lookup_participant_operation (method)

async CayuApp.lookup_participant_operation(expected: ExpectedOperation[ParticipantIntent], *, context: CollaborationAccessContext) -> ExactLookup[ParticipantReceipt]

context_view_extensions (property)

CayuApp.context_view_extensions() -> tuple[ContextViewExtensionRegistration, ...]

Return detached application registrations for historical projections.

project_context_view_extensions (method)

CayuApp.project_context_view_extensions(source: ContextViewProjectionSource)

Return the all-or-nothing detached extension projection for a view.

publish_completed_context_view (method)

async CayuApp.publish_completed_context_view(request: ContextViewPublicationRequest, *, participant: ParticipantRef, context: CollaborationAccessContext, resource_owner: LocalArtifactResourceOwner | None=None) -> ContextViewManifest

Publish an immutable view from authoritative completed-turn evidence.

transition_context_view_ownership (method)

async CayuApp.transition_context_view_ownership(request: ContextViewOwnershipRequest, *, participant: ParticipantRef, destination_participant: ParticipantRef | None=None, context: CollaborationAccessContext)

Apply one authenticated, replay-safe context-view ownership transition.

select_context_view (method)

async CayuApp.select_context_view(request: ContextViewSelectionRequest, *, participant: ParticipantRef, context: CollaborationAccessContext)

read_context_view (method)

async CayuApp.read_context_view(view_id: str, *, source_session_id: str, participant: ParticipantRef, context: CollaborationAccessContext) -> ContextViewReadback

read_context_view_lifecycle_events (method)

async CayuApp.read_context_view_lifecycle_events(view_id: str, *, source_session_id: str, participant: ParticipantRef, context: CollaborationAccessContext, limit: int=256)

budget_policy (method)

CayuApp.budget_policy(value: BudgetPolicy | None) -> None

Install a complete, validated app budget-policy replacement.

resolve_budget_binding (method)

async CayuApp.resolve_budget_binding(*, request: object) -> BudgetBinding

Resolve a trusted common-root binding for a bound operation.

Public request values are never treated as authority. Applications must register a receiver that resolves and authenticates the binding.

redact_json (method)

CayuApp.redact_json(value: Any) -> Any

Return a JSON-compatible value with configured secret values redacted.

redact_uppercase_text (method)

CayuApp.redact_uppercase_text(value: str) -> str

Redact text after the same uppercase normalization used by authorities.

inspect_session_closure (method)

async CayuApp.inspect_session_closure(session_id: str, *, policy: SessionClosurePolicy | None=None)

Inspect all explicitly configured Cayu-owned closure stores.

erase_session_closure (method)

async CayuApp.erase_session_closure(session_id: str, *, policy: SessionClosurePolicy | None=None, expected_plan_id: str | None=None) -> SessionClosureReport

Perform a bounded, dependent-first session closure.

validate_session_closure (method)

async CayuApp.validate_session_closure(session_id: str, *, policy: SessionClosurePolicy | None=None)

Validate closure admission before any external cleanup begins.

export_session_closure (method)

async CayuApp.export_session_closure(session_id: str, *, policy: SessionClosurePolicy | None=None, allow_partial: bool=False) -> SessionClosureExport

Export bounded closure records, requiring opt-in for incomplete diagnostics.

stream_redacted_bytes (method)

CayuApp.stream_redacted_bytes(*, max_retained_bytes: int | None=None) -> SecretRedactionStream

Create a chunk-safe redaction stream for application exposure boundaries.

redact_utf8_head (method)

CayuApp.redact_utf8_head(value: bytes, *, max_bytes: int, source_complete: bool) -> tuple[str, bool]

Project a bounded UTF-8 prefix through the application secret registry.

project_event_record_for_exposure (method)

CayuApp.project_event_record_for_exposure(record: EventRecord) -> EventRecord

Project a caller-supplied record without granting persisted authority.

project_session_id_for_exposure (method)

CayuApp.project_session_id_for_exposure(value: str) -> str

Project private session authority to one stable public identifier.

project_causal_budget_id_for_exposure (method)

CayuApp.project_causal_budget_id_for_exposure(value: str, *, session_ids: Iterable[str]) -> str

Project session authority or redact an opaque causal-budget label.

project_interaction_id_for_exposure (method)

CayuApp.project_interaction_id_for_exposure(value: str, *, session_id: str) -> str

Project private interaction authority to one stable public identifier.

redact_exception_diagnostic (method)

CayuApp.redact_exception_diagnostic(error: BaseException, *, empty_message: str, nonportable_message: str) -> ExceptionDiagnostic

Snapshot a dispatch diagnostic with workload secrets removed before bounding.

redact_dispatch_request (method)

CayuApp.redact_dispatch_request(request: DispatchRequest) -> DispatchRequest

Return a durable dispatch request scrubbed with this app’s redactor.

describe (method)

CayuApp.describe(*, project_root: str | Path | None=None) -> AppManifest

Return this application’s deterministic public manifest.

Description is structural only: it never invokes providers, tools, environment factories, stores, workers, watchers, or recovery paths.

lifecycle_state (property)

CayuApp.lifecycle_state() -> ApplicationLifecycleState

open, closing once sealed, or closed after a settled shutdown.

shutdown_outcome (property)

CayuApp.shutdown_outcome() -> ApplicationShutdownOutcome | None

The outcome of the most recent shutdown attempt, if any.

seal_admissions (method)

CayuApp.seal_admissions() -> None

Refuse new runs, recoveries, dispatches and other execution entrances.

Idempotent and never reopened. Operations already admitted keep running, as do reads, inspections, cleanup and the drains. aclose seals first.

aclose (method)

async CayuApp.aclose(*, timeout_s: float=DEFAULT_APPLICATION_SHUTDOWN_TIMEOUT_SECONDS) -> ApplicationShutdownOutcome

Seal admissions and drain every subsystem under one shared deadline.

Returns the outcome; it never raises merely because work is unfinished. A settled outcome is final. After an incomplete or failed outcome a later call runs another attempt. Caller-supplied stores and providers stay open; only owned_resources are closed, and only once everything settled.

aenter (method)

async CayuApp.__aenter__() -> Self

aexit (method)

async CayuApp.__aexit__(*_exc_info: object) -> None

drain_background_interruptions (method)

async CayuApp.drain_background_interruptions(*, timeout_s: float=10.0) -> bool

provider_operation_cancellation_status (method)

CayuApp.provider_operation_cancellation_status() -> ProviderOperationCancellationLifecycleSnapshot

Return content-free process-local provider-cancellation ownership state.

seal_provider_operation_cancellations (method)

CayuApp.seal_provider_operation_cancellations() -> None

Reject new cancellation owners and request cancellation from active owners.

drain_provider_operation_cancellations (method)

async CayuApp.drain_provider_operation_cancellations(*, timeout_s: float=10.0) -> bool

Seal and boundedly drain every Runtime-owned provider cancellation.

Also waits, without cancelling, for claim renewal writes that outlived their lease. It does not stop or wait for claim heartbeats, which an operation may still need; aclose() stops those once nothing runs.

recovery_cleanup_status (method)

CayuApp.recovery_cleanup_status() -> RecoveryCleanupSupervisorSnapshot

Return content-free process-local cleanup supervision state.

session_recovery_cleanup_status (method)

CayuApp.session_recovery_cleanup_status(*, session_id: str, session_instance_id: str, run_epoch: int) -> RecoveryCleanupSessionSnapshot

Inspect exact local run cleanup; this does not authorize recovery or prove settlement.

drain_session_recovery_cleanups (method)

async CayuApp.drain_session_recovery_cleanups(owner: RecoveryCleanupOwner, *, timeout_s: float=10.0) -> bool

Await only an observed local owner. New work and remote effects remain independent.

tool_terminal_publication_status (method)

CayuApp.tool_terminal_publication_status() -> ToolTerminalPublicationMetricsSnapshot

Return content-free staged-terminal backlog and fairness measurements.

drain_recovery_cleanups (method)

async CayuApp.drain_recovery_cleanups(*, timeout_s: float=10.0) -> bool

Wait boundedly for recovery cleanup, stopped execution-presence writes, recovery claim renewals that outlived their heartbeat, and artifact reads and tool-effect reconciliation lookups whose caller stopped waiting.

drain_environment_cleanups (method)

async CayuApp.drain_environment_cleanups(*, timeout_s: float=10.0) -> bool

Settle this process’s retained cleanup without cancelling live mutations.

Also waits for tool-result projections that outlived their timeout and artifact writes whose caller stopped waiting, which may still write into an environment’s artifact store, for abandoned secret resolutions, which may still use its vault or credential proxy, and for isolated tool process cleanups, retrying failed ones once.

This is not a durable allocation census. After restart, use recover_incomplete_session (including for terminal sessions) to reconcile pending allocation intents before treating cleanup as closed.

close_idle_environment_resources (method)

async CayuApp.close_idle_environment_resources(*, timeout_s: float=10.0) -> bool

Close factory-held idle resources, such as warm spares, at shutdown.

drain_environment_cleanups only trims them, so an application may drain while idle and keep using its factories. Call this once the application stops serving; afterwards factories create no new idle resources and sessions that still run start cold. Application shutdown calls it after its environment drain. Returns whether every factory released cleanly within timeout_s; a release still running then is not cancelled, and a later call waits for it.

seal_knowledge_publications (method)

CayuApp.seal_knowledge_publications() -> None

Refuse this application’s new knowledge publications before shutdown drains.

Registered knowledge tools may be shared with other applications, so they stay open; close a tool with its own aclose when it is retired.

drain_knowledge_publications (method)

async CayuApp.drain_knowledge_publications(*, timeout_s: float=10.0) -> bool

Seal, then wait for publications this application started through its tools.

discard_parked_egress_allocations (method)

async CayuApp.discard_parked_egress_allocations(session_id: str, *, timeout_s: float=10.0) -> bool

Discard parked external allocations before abandoning one session.

resume_pending_interruption_cascades (method)

async CayuApp.resume_pending_interruption_cascades(*, interrupting_inactive_for_seconds: int | None=None) -> int

get_startup_recovery_status (method)

async CayuApp.get_startup_recovery_status() -> StartupRecoveryResult

Return the latest process-local sweep with safe exposed session identities.

interruption_cascade_status (method)

async CayuApp.interruption_cascade_status(session_id: str) -> str

inspect_targeted_tool_grants (method)

async CayuApp.inspect_targeted_tool_grants(session_id: str, *, interaction_id: str | None=None, limit: int=TARGETED_TOOL_GRANT_INSPECTION_MAX_RECORDS) -> tuple[TargetedToolGrantInspection, ...]

Return bounded grant state through authenticated public aliases.

require_human_review_resolution_authority (method)

async CayuApp.require_human_review_resolution_authority(session_id: str, reference: HumanReviewReference | None) -> None

Check decision permission independently of inspection and receipt replay.

get_human_attention_state (method)

async CayuApp.get_human_attention_state(reference: HumanAttentionReference) -> HumanAttentionObservation

Read exact attention state; notification acknowledgement cannot resume work.

SDK callers must independently authorize access to the referenced session. Unavailable reads or missing terminal evidence never imply resolution.

inspect_human_review (method)

async CayuApp.inspect_human_review(session_id: str, *, context: HumanReviewContext) -> HumanReviewView

Inspect protected review content without executing or claiming work.

Direct SDK callers are trusted to supply verified recipient provenance. The configured policy must authorize the exact session and tenant.

inspect_tool_discovery_view (method)

async CayuApp.inspect_tool_discovery_view(session_id: str, *, limit: int=TOOL_DISCOVERY_INSPECTION_MAX_GRANTS) -> ToolDiscoveryViewInspection

Return the current bounded view without refs, schemas, or query evidence.

register_agent (method)

CayuApp.register_agent(spec: AgentSpec, *, tools: Iterable[Tool] | None=None, tool_effect_reconcilers: Mapping[str, ToolEffectReconciliationRegistration] | None=None, mcp_toolsets: Iterable[McpToolset] | None=None, hosted_tools: Iterable[OpenAIWebSearch] | None=None, context_policy: ContextPolicy | None=None, context_overflow_policy: ContextPolicy | None=None, child_session_context: ChildSessionContextContributor | None=None, tool_exposure_policy: ToolExposurePolicy | None=None, targeted_tool_mode: TargetedToolMode | str | None=None, tool_discovery_mode: ToolDiscoveryMode | str | None=None, tool_policy: ToolPolicy | None=None, runtime_hooks: Iterable[RuntimeHook] | None=None, loop_policies: Iterable[LoopPolicy] | None=None, execution_requirements: ExecutionRequirements | None=None) -> AgentSpec

refresh_mcp_toolset (method)

async CayuApp.refresh_mcp_toolset(toolset: McpToolset) -> McpToolsetRefreshResult

Re-list and atomically publish one explicitly registered MCP source.

register_completion_verifier (method)

CayuApp.register_completion_verifier(reference: CompletionVerifierRef, verifier: DeterministicCompletionVerifier) -> CompletionVerifierRef

Register one deterministic verifier under its complete durable identity.

register_completion_result_resolver (method)

CayuApp.register_completion_result_resolver(reference: CompletionResultResolverRef, resolver: CompletionResultResolver) -> CompletionResultResolverRef

Register one result resolver under its complete durable identity.

register_provider (method)

CayuApp.register_provider(provider: ModelProvider, *, default: bool=False, model_patterns: Iterable[str] | None=None) -> ModelProvider

register_environment (method)

CayuApp.register_environment(environment: Environment, *, default: bool=False) -> Environment

register_environment_factory (method)

CayuApp.register_environment_factory(spec: EnvironmentSpec, factory: EnvironmentFactory, *, artifact_store: ArtifactStore | None=None, default: bool=False) -> EnvironmentFactory

get_agent (method)

CayuApp.get_agent(name: str) -> runtime_records.RegisteredAgent

resolve_run_model_target (method)

CayuApp.resolve_run_model_target(request: RunRequest) -> ModelTarget

Resolve initial provider/model routing without preparing runtime state.

start_model_policy (method)

async CayuApp.start_model_policy() -> None

Start explicitly configured policy workers before admitting defaulted runs.

stop_model_policy (method)

async CayuApp.stop_model_policy() -> None

Stop policy workers; application-owned channels and stores remain open.

model_policy_lifespan (method)

async CayuApp.model_policy_lifespan()

Own policy workers without replacing an application’s primary failure.

inspect_run_execution_profile (method)

async CayuApp.inspect_run_execution_profile(request: RunRequest) -> str

Return the exact initial profile fingerprint without admitting a session.

The inspection performs the ordinary bounded, read-only run preflights but creates no session and dispatches no provider, tool, hook, or environment factory work. Applications can bind product authority to the returned fingerprint before exposing an advanced execution surface.

inspect_effective_run_configuration (method)

async CayuApp.inspect_effective_run_configuration(request: RunRequest) -> EffectiveRunConfiguration

Return redacted effective run controls and their durable profile identity.

Inspection performs the ordinary bounded, read-only initial-run preflight. It creates no session and dispatches no provider, tool, hook, or environment factory work.

current_prompt_anatomy_sha256 (method)

async CayuApp.current_prompt_anatomy_sha256(*, agent_name: str, environment_name: str | None) -> str

Return a content-free digest of the prompt the current body would install.

list_agents (method)

CayuApp.list_agents() -> tuple[str, ...]

Return the names of all registered agents, sorted.

list_providers (method)

CayuApp.list_providers() -> tuple[str, ...]

Return the names of all registered providers, sorted.

list_environments (method)

CayuApp.list_environments() -> tuple[str, ...]

Return the names of all registered environments (concrete or factory), sorted.

has_registered_artifact_store (method)

CayuApp.has_registered_artifact_store() -> bool

Return whether any registered environment exposes artifact storage.

The registration paths maintain this value, so the check is constant-time and does not copy registration metadata or materialize environment factories.

artifact_store_registration_count (method)

CayuApp.artifact_store_registration_count() -> int

Return the exact registration count without projecting store identities.

artifact_store_registration_fingerprints (method)

CayuApp.artifact_store_registration_fingerprints(*, limit: int) -> tuple[tuple[str, ...], int]

Return a bounded snapshot of opaque store identities and the exact count.

Fingerprints are fixed-size SHA-256 correlations of the store identities accepted at registration. They let protected diagnostics correlate shared registrations without returning a local path or application-defined id.

list_environment_registrations (method)

CayuApp.list_environment_registrations() -> tuple[runtime_records.RegisteredEnvironment, ...]

Return registered environment metadata without materializing factories.

get_provider (method)

CayuApp.get_provider(name: str | None=None) -> ModelProvider

get_environment (method)

CayuApp.get_environment(name: str | None=None) -> runtime_records.RegisteredEnvironment

get_environment_factory (method)

CayuApp.get_environment_factory(name: str | None=None) -> EnvironmentFactory

attach_file (method)

async CayuApp.attach_file(content: bytes, *, filename: str, kind: FileAttachmentKind | str, content_type: str | None=None, environment_name: str | None=None, scope: ArtifactScope=ArtifactScope.SESSION, session_id: str | None=None, agent_name: str | None=None, metadata: dict[str, Any] | None=None) -> FilePart

Save a file to the artifact store and return a user-prompt FilePart referencing it.

Attach the returned part to a user Message alongside text; the runtime inlines the file into the provider request on the turn it is attached (and re-enforces the per-file/per-request limits). kind is "image" (jpeg/png/gif/webp) or "document" (pdf). For a session-scoped attachment, pass the same session_id you will use in the RunRequest.

The bytes are parsed to confirm they are a valid image/PDF whose detected format matches the declared/inferred content type before being stored, which requires the optional file dependencies (cayu[files]); without them this raises. The (default or named) environment registration must expose an artifact store. For a factory-backed environment, pass the durable store to register_environment_factory(..., artifact_store=...); attach_file uses that stable handle without materializing a session environment.

config (property)

CayuApp.config() -> CayuConfig

Return the immutable effective application configuration.

run (method)

async CayuApp.run(request: RunRequest) -> AsyncIterator[Event]

replay_session (method)

async CayuApp.replay_session(request: RuntimeReplayRequest) -> RuntimeReplayReport

Re-drive one promoted trajectory against this app without live effects.

admit_work_attempt (method)

async CayuApp.admit_work_attempt(request: RunRequest | ResumeRequest, *, execution: WorkAttemptExecutionRequest) -> WorkAttemptAdmission

Durably admit an initial or rejected/continue contracted attempt.

Admission starts and profiles the exact interaction but deliberately dispatches no provider, tool, hook, or mutating environment work. The automatic verified-work worker consumes this authority separately.

renew_work_attempt_claim (method)

async CayuApp.renew_work_attempt_claim(request: WorkAttemptClaimRenewalRequest) -> WorkAttemptAdmission

Renew the exact live execution generation owned by this process.

recover_work_attempt (method)

async CayuApp.recover_work_attempt(request: WorkAttemptRecoveryRequest) -> WorkAttemptAdmission

Replace an expired generation after positive session quiescence.

submit_work_attempt_proposal (method)

async CayuApp.submit_work_attempt_proposal(request: WorkAttemptProposalRequest) -> CompletionProposal

Publish one proposal under the exact live attempt execution claim.

access (method)

async CayuApp.access(subject: str)

Bind a subject already authenticated by trusted application code.

resume (method)

async CayuApp.resume(request: ResumeRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

compact_session (method)

async CayuApp.compact_session(request: CompactSessionRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

enqueue_session_message (method)

async CayuApp.enqueue_session_message(request: EnqueueSessionMessageRequest, *, context: SessionMessageAccessContext | None=None) -> EnqueueSessionMessageResult

Queue steering; scoped/provenance admission requires trusted context.

append_peer_content (method)

async CayuApp.append_peer_content(request: PeerContentAppendRequest, *, context: CollaborationAccessContext) -> PeerContentReceipt

Append one authenticated peer occurrence to a participant session.

The application facade intentionally remains thin: durable append-key replay/conflict and target-incarnation fencing belong to SessionStore. A collaboration access context is mandatory so ordinary unauthenticated callers cannot turn a matching payload into peer authority.

read_peer_content (method)

async CayuApp.read_peer_content(append_key: PeerAppendKey, *, context: CollaborationAccessContext, expected: PeerContentAppendRequest | None=None) -> PeerContentReceipt | None

Read only the exact durable peer append receipt.

service_pending_peer_content (method)

async CayuApp.service_pending_peer_content(session_id: str, *, context: CollaborationAccessContext) -> tuple[PeerContentReceipt, ...]

Service durable pending work with fresh authority, without starting a model.

exclude_peer_content (method)

async CayuApp.exclude_peer_content(request: PeerContentAppendRequest, *, reason: str, context: CollaborationAccessContext) -> PeerContentReceipt

Record a definitive, authenticated non-delivery outcome.

expose_peer_content (method)

async CayuApp.expose_peer_content(request: PeerContentExposureRequest, *, context: CollaborationAccessContext) -> PeerContentExposureReceipt

Reject caller-authored settlement; model-attempt owners settle exposure.

inspect_session_messages (method)

async CayuApp.inspect_session_messages(query: SessionMessageQuery, *, context: SessionMessageAccessContext) -> SessionMessageInspection

Inspect protected queue content without claiming or executing work.

apply_session_message_action (method)

async CayuApp.apply_session_message_action(request: SessionMessageActionRequest, *, context: SessionMessageAccessContext) -> SessionMessageActionResult

Withdraw/quarantine an exact record under application-owned authority.

snapshot_session_message_source (method)

async CayuApp.snapshot_session_message_source(session_id: str, *, context: SessionMessageAccessContext, include_transcript_digest: bool=False, include_checkpoint_digest: bool=False) -> SessionMessageSource

Authorize a source before reading its protected transcript/checkpoint.

stop_after_current_tool_round (method)

async CayuApp.stop_after_current_tool_round(request: StopAfterCurrentToolRoundRequest) -> SessionSteeringReceipt

Accept a durable cooperative stop without cancelling the current round.

interrupt_session (method)

async CayuApp.interrupt_session(request: InterruptSessionRequest) -> AsyncIterator[Event]

recover_incomplete_session (method)

async CayuApp.recover_incomplete_session(request: IncompleteSessionRecoveryRequest, *, context: CollaborationAccessContext | None=None) -> IncompleteSessionRecoveryResult

plan_recovery (method)

async CayuApp.plan_recovery(request: RecoveryPlanRequest) -> RecoveryPlan

Build a bounded, read-only recovery plan for this registered app.

execute_recovery (method)

async CayuApp.execute_recovery(request: RecoveryExecutionRequest) -> RecoveryReceipt

Execute exact recovery-plan decisions with durable per-session receipts.

recover_model_completion_stage (method)

async CayuApp.recover_model_completion_stage(request: ModelCompletionManualRecoveryRequest) -> ModelCompletionManualRecoveryResult

Settle ambiguous provider work and linked budgets under runtime ownership.

inspect_session_execution (method)

async CayuApp.inspect_session_execution(session_id: str) -> SessionExecutionState

Inspect durable execution presence without renewing or claiming any authority.

get_persisted_event_side_effect_health (method)

async CayuApp.get_persisted_event_side_effect_health() -> PersistedEventSideEffectHealth

Read the store-wide durable fan-out snapshot; never emit or retry events.

inspect_recent_tool_round_timing (method)

async CayuApp.inspect_recent_tool_round_timing(session_id: str, *, limit: int=20) -> tuple[ToolRoundTiming, ...]

Read the bounded, process-local recent round timings; never touch a store.

inspect_recent_model_step_preparation_timing (method)

async CayuApp.inspect_recent_model_step_preparation_timing(session_id: str, *, limit: int=20) -> tuple[ModelStepPreparationTiming, ...]

runtime_timing_status (method)

CayuApp.runtime_timing_status() -> RuntimeTimingStatus

flush_runtime_timing (method)

async CayuApp.flush_runtime_timing() -> None

Wait for bounded best-effort timing deliveries; adds no durable writes.

close_runtime_timing (method)

async CayuApp.close_runtime_timing() -> None

Stop timing delivery at shutdown after one flush bounded by the sink timeout.

Undelivered records are counted as dropped. OpenTelemetry records still waiting for their session or tool span are exported under the best known parent. Later records start a new delivery worker on the running event loop.

query_persisted_event_side_effect_deliveries (method)

async CayuApp.query_persisted_event_side_effect_deliveries(query: PersistedEventSideEffectQuery) -> PersistedEventSideEffectPage

Inspect bounded, sanitized delivery records without acquiring ownership.

recover_persisted_event_side_effects (method)

async CayuApp.recover_persisted_event_side_effects(*, limit: int=1000) -> list[Event]

Retry committed event fan-out that was not acknowledged before a crash.

Delivery is at-least-once and returns only events whose configured budget and sink side effects completed during this sweep. Failed and dead-lettered deliveries remain inspectable through session_store.

recover_incomplete_sessions (method)

async CayuApp.recover_incomplete_sessions(request: IncompleteSessionsRecoveryRequest) -> IncompleteSessionsRecoveryPage

Sweep one bounded page of requested states, fault-isolated.

results contains one result per repaired or otherwise reportable session. inspected_session_count includes healthy terminal rows omitted from those results. When next_cursor is present, pass it in a new request with the same statuses, inactivity boundary, reason, and metadata to continue without rescanning earlier candidates.

A session whose agent is not registered in this process is reported as SKIPPED_UNREGISTERED_AGENT; an unexpected per-session failure is reported as FAILED with the error in message — neither aborts the sweep, so one bad row cannot strand every healthy session. A FAILED entry’s previous_status comes from the sweep’s listing snapshot; its status is the current stored status when the session can still be reloaded (a failed recovery may have progressed it), falling back to the snapshot when it cannot. Session listing failures and cancellation still raise. Every invocation inspects at most request.inspection_limit rows, using at most ten store keyset pages of at most 1,000 rows each. Terminal sessions are inspected through bounded event queries. They are repaired only when their current run lacks matching terminal evidence or retains incomplete recovery state. Healthy terminal inspection candidates are omitted from the result and do not consume request.limit.

dispatch (method)

async CayuApp.dispatch(request: DispatchRequest) -> DispatchHandle

session_invocation_for_dispatch (method)

async CayuApp.session_invocation_for_dispatch(session_id: str) -> SessionInvocationBinding

Return immutable private provenance for a trusted dispatcher boundary.

dispatch_inline (method)

async CayuApp.dispatch_inline(request: DispatchRequest) -> AsyncIterator[Event]

verify_completion_proposal (method)

async CayuApp.verify_completion_proposal(request: CompletionVerifierExecutionRequest) -> CompletionDecision

Run the registered deterministic verifier and persist its decision.

apply_completion_decision (method)

async CayuApp.apply_completion_decision(request: CompletionDecisionApplicationRequest) -> Task

Apply or exactly replay one durable verifier decision.

resolve_completion_result (method)

async CayuApp.resolve_completion_result(request: CompletionResultResolutionRequest) -> Task

Resolve and exactly apply the accepted result for one durable decision.

create_work_contract (method)

async CayuApp.create_work_contract(request: WorkContractDraft) -> WorkContract

load_work_contract (method)

async CayuApp.load_work_contract(reference: WorkContractRef) -> WorkContract | None

create_task (method)

async CayuApp.create_task(request: TaskCreate) -> Task

create_task_group (method)

async CayuApp.create_task_group(request: TaskGroupCreate) -> TaskGroupCreationReceipt

Atomically create a graph and a completion policy over selected members.

load_task_group (method)

async CayuApp.load_task_group(group_id: str) -> TaskGroupSnapshot | None

Inspect a durable group decision without implying member quiescence.

reconcile_task_group (method)

async CayuApp.reconcile_task_group(group_id: str) -> TaskGroupSnapshot

Advance the durable barrier without overriding a timeout latch.

resolve_task_group_quiescence (method)

async CayuApp.resolve_task_group_quiescence(request: TaskGroupQuiescenceResolution) -> TaskGroupSnapshot

Release timed-out group work only from positive exact settlement evidence.

list_task_group_events (method)

async CayuApp.list_task_group_events(group_id: str, *, after_sequence: int=0, limit: int=100) -> list[TaskGroupEvent]

Read ordered group evidence from the task store.

create_task_graph (method)

async CayuApp.create_task_graph(request: TaskGraphCreate) -> TaskGraphCreationReceipt

Atomically submit a bounded self-contained graph through the Python SDK.

load_task_graph (method)

async CayuApp.load_task_graph(graph_id: str) -> TaskGraphSnapshot | None

Inspect current graph state and retained terminal member evidence.

list_task_graph_events (method)

async CayuApp.list_task_graph_events(graph_id: str, *, after_sequence: int=0, limit: int=100) -> list[TaskGraphEvent]

Read a bounded page of task-store-owned graph events.

reschedule_task (method)

async CayuApp.reschedule_task(request: TaskRescheduleRequest) -> TaskScheduleReceipt

Replace an unadmitted one-shot schedule at its exact durable revision.

list_task_schedule_events (method)

async CayuApp.list_task_schedule_events(task_id: str, *, after_sequence: int=0, limit: int=100) -> list[TaskScheduleEvent]

Inspect a bounded, sequence-ordered page of durable scheduling decisions.

cancel_scheduled_task (method)

async CayuApp.cancel_scheduled_task(request: TaskScheduleCancelRequest) -> TaskScheduleReceipt

Request exact schedule cancellation while preserving live execution ownership.

pause_task (method)

async CayuApp.pause_task(task_id: str, *, reason: str | None=None, payload: dict[str, Any] | None=None) -> Task

block_task (method)

async CayuApp.block_task(task_id: str, *, reason: str | None=None, payload: dict[str, Any] | None=None) -> Task

mark_task_needs_attention (method)

async CayuApp.mark_task_needs_attention(task_id: str, *, reason: str | None=None, payload: dict[str, Any] | None=None) -> Task

resume_task (method)

async CayuApp.resume_task(task_id: str) -> Task

get_session_usage (method)

async CayuApp.get_session_usage(session_id: str) -> SessionUsageSummary

get_causal_budget_usage (method)

async CayuApp.get_causal_budget_usage(causal_budget_id: str) -> CausalBudgetUsageSummary

run_event_watchers (method)

async CayuApp.run_event_watchers(watchers: Iterable[EventWatcher], *, limit: int=100) -> list[EventWatcherRunResult]

Deliver ordered durable events under renewable, fenced watcher leases.

get_session_cost (method)

async CayuApp.get_session_cost(session_id: str, pricing: PriceBook, *, currency: str='USD') -> SessionCostSummary

get_causal_budget_cost (method)

async CayuApp.get_causal_budget_cost(causal_budget_id: str, pricing: PriceBook, *, currency: str='USD') -> CausalBudgetCostSummary

emit_hook_event (method)

async CayuApp.emit_hook_event(*, session_id: str, event_type: str, payload: dict[str, Any] | None=None) -> Event

fork_session (method)

async CayuApp.fork_session(request: ForkSessionRequest) -> AsyncIterator[Event]

snapshot_fork_source (method)

async CayuApp.snapshot_fork_source(source_session_id: str) -> ForkSourceSnapshot

Return exact public authority for one currently safe fork source.

resolve_user_input (method)

async CayuApp.resolve_user_input(response: UserInputResponse, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

recover_user_input (method)

async CayuApp.recover_user_input(request: UserInputRecoveryRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

resolve_tool_approval (method)

async CayuApp.resolve_tool_approval(request: ToolApprovalRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

resolve_provider_operation (method)

async CayuApp.resolve_provider_operation(request: ProviderOperationResolutionRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

Resolve unavailable provider work by explicit fallback retry or failure.

recover_tool_approval (method)

async CayuApp.recover_tool_approval(request: ToolApprovalRecoveryRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

inspect_tool_effect (method)

async CayuApp.inspect_tool_effect(session_id: str, *, tool_round_id: str, tool_call_id: str) -> ToolEffectReconciliationTarget

Inspect an external call without claiming work or validating a receipt.

Use round/call identifiers from public events. The snapshot may become stale; submission never refreshes its versions or grants retry authority.

reconcile_tool_effect (method)

async CayuApp.reconcile_tool_effect(request: ToolEffectReconciliationRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

Validate external evidence and continue an existing uncertain tool call.

recover_tool_round (method)

async CayuApp.recover_tool_round(request: ToolRoundRecoveryRequest, *, context: CollaborationAccessContext | None=None) -> AsyncIterator[Event]

scoped_event_emitter (method)

CayuApp.scoped_event_emitter(*, event_types: Iterable[EventType | str]) -> Callable[[Event], Awaitable[Event]]

Return an out-of-band emitter constrained to specific event types.

emit_event (method)

async CayuApp.emit_event(event: Event) -> Event

Publish an event to the session store and all sinks.

Low-level seam for runtime-owned out-of-band session events. Prefer scoped_event_emitter when handing an emitter to a component. Redaction is applied by the sinks; callers must not place raw secrets in the payload.

emit_events (method)

async CayuApp.emit_events(session_id: str, events: list[Event]) -> list[Event]

Persist events for one session and fan them out to runtime sinks.

Restricted to the workflow. and custom. namespaces: runtime event namespaces encode Cayu-owned lifecycle and accounting evidence, so application callers must not forge them even though every accepted batch uses the same durable budget/sink handoff.

Release source · Runtime guarantees · Capability guides