cayu.events
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.
from cayu.events import EventAppend-only runtime event.
Events are the common language between terminal output, dashboard views, persistent sessions, webhooks, and hosted-platform adapters.
Bases: BaseModel.
Fields and attributes
Section titled “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 |
|---|---|---|
type |
EventType | str |
required |
session_id |
str |
required |
interaction_id |
str | None |
None |
id |
str |
Field(default_factory=lambda: str(uuid4()), max_length=EVENT_ID_MAX_CHARS) |
timestamp |
datetime |
Field(default_factory=lambda: datetime.now(UTC)) |
agent_name |
str | None |
None |
environment_name |
str | None |
None |
workflow_name |
str | None |
None |
tool_name |
str | None |
None |
payload |
dict[str, Any] |
Field(default_factory=dict) |
model_post_init (method)
Section titled “model_post_init (method)”Event.model_post_init(__context: Any) -> Nonevalidate_durable_envelope (method)
Section titled “validate_durable_envelope (method)”Event.validate_durable_envelope() -> Eventcopy_payload (method)
Section titled “copy_payload (method)”Event.copy_payload(value: dict[str, Any]) -> dict[str, Any]validate_nonblank_ids (method)
Section titled “validate_nonblank_ids (method)”Event.validate_nonblank_ids(value: str, info) -> strvalidate_optional_nonblank_names (method)
Section titled “validate_optional_nonblank_names (method)”Event.validate_optional_nonblank_names(value: str | None, info) -> str | Nonevalidate_type (method)
Section titled “validate_type (method)”Event.validate_type(value: EventType | str) -> EventType | strRelease source · Runtime guarantees · Capability guides
EVENT_ID_MAX_CHARS
Section titled “EVENT_ID_MAX_CHARS”from cayu.events import EVENT_ID_MAX_CHARSEVENT_ID_MAX_CHARS = 512Release source · Runtime guarantees · Capability guides
EventType
Section titled “EventType”from cayu.events import EventTypeBases: StrEnum.
Fields and attributes
Section titled “Fields and attributes”Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.
| Name | Type | Default |
|---|---|---|
WORKSPACE_CHECKPOINT_UPDATED |
class attribute |
'workspace.checkpoint.updated' |
SERVER_MUTATION_ACCEPTED |
class attribute |
'server.mutation.accepted' |
RECOVERY_PLAN_ITEM_EXECUTED |
class attribute |
'recovery.plan.item.executed' |
SESSION_STARTED |
class attribute |
'session.started' |
SESSION_RESUMED |
class attribute |
'session.resumed' |
SESSION_COMPLETED |
class attribute |
'session.completed' |
SESSION_FAILED |
class attribute |
'session.failed' |
SESSION_INTERRUPTED |
class attribute |
'session.interrupted' |
SESSION_DELEGATED_ACTION_UPDATED |
class attribute |
'session.delegated_action.updated' |
SESSION_INTERRUPTION_CASCADE_RETRY_REQUESTED |
class attribute |
'session.interruption_cascade_retry_requested' |
SESSION_INTERRUPTION_CASCADE_COMPLETED |
class attribute |
'session.interruption_cascade_completed' |
SESSION_INTERRUPTION_CASCADE_FAILED |
class attribute |
'session.interruption_cascade_failed' |
SESSION_AWAITING_USER_INPUT |
class attribute |
'session.awaiting_user_input' |
SESSION_CHECKPOINTED |
class attribute |
'session.checkpointed' |
SESSION_FORKED |
class attribute |
'session.forked' |
SESSION_EXPORT_PUBLISHED |
class attribute |
'session.export.published' |
SESSION_EXPORT_RELEASED |
class attribute |
'session.export.released' |
SESSION_EXPORT_RETIRED |
class attribute |
'session.export.retired' |
SESSION_LIMIT_REACHED |
class attribute |
'session.limit_reached' |
SESSION_MESSAGE_QUEUED |
class attribute |
'session.message.queued' |
SESSION_MESSAGE_DELIVERED |
class attribute |
'session.message.delivered' |
SESSION_MESSAGE_WITHDRAWN |
class attribute |
'session.message.withdrawn' |
SESSION_MESSAGE_QUARANTINED |
class attribute |
'session.message.quarantined' |
SESSION_MESSAGE_STALE |
class attribute |
'session.message.stale' |
SESSION_MESSAGE_EXPIRED |
class attribute |
'session.message.expired' |
SESSION_MODEL_SWITCHED |
class attribute |
'session.model.switched' |
SESSION_EXECUTION_PROFILE_DECIDED |
class attribute |
'session.execution_profile.decided' |
SESSION_EXECUTION_PROFILE_REJECTED |
class attribute |
'session.execution_profile.rejected' |
SESSION_RUN_FENCED |
class attribute |
'session.run_fenced' |
TURN_COMPLETED |
class attribute |
'turn.completed' |
INTERACTION_STARTED |
class attribute |
'interaction.started' |
INTERACTION_RESUMED |
class attribute |
'interaction.resumed' |
INTERACTION_PAUSED |
class attribute |
'interaction.paused' |
INTERACTION_COMPLETED |
class attribute |
'interaction.completed' |
INTERACTION_FAILED |
class attribute |
'interaction.failed' |
INTERACTION_INTERRUPTED |
class attribute |
'interaction.interrupted' |
BUDGET_CHECKED |
class attribute |
'budget.checked' |
BUDGET_LIMIT_REACHED |
class attribute |
'budget.limit_reached' |
BUDGET_RESERVED |
class attribute |
'budget.reserved' |
BUDGET_RECONCILED |
class attribute |
'budget.reconciled' |
BUDGET_RESERVATION_FAILED |
class attribute |
'budget.reservation_failed' |
BUDGET_RESERVATION_RELEASED |
class attribute |
'budget.reservation_released' |
CREDENTIAL_PROXY_CHECKED |
class attribute |
'credential.proxy.checked' |
CREDENTIAL_MODE_SELECTED |
class attribute |
'credential.mode.selected' |
EGRESS_GRANT_MINTED |
class attribute |
'egress.grant.minted' |
EGRESS_GRANT_REVOKED |
class attribute |
'egress.grant.revoked' |
EGRESS_REQUEST_AUTHORIZED |
class attribute |
'egress.request.authorized' |
EGRESS_REQUEST_DENIED |
class attribute |
'egress.request.denied' |
EGRESS_AUTHORITY_REQUESTED |
class attribute |
'egress.authority.requested' |
EGRESS_AUTHORITY_AUTHORIZED |
class attribute |
'egress.authority.authorized' |
EGRESS_AUTHORITY_INSTALLING |
class attribute |
'egress.authority.installing' |
EGRESS_AUTHORITY_ACTIVATED |
class attribute |
'egress.authority.activated' |
EGRESS_AUTHORITY_REFUSED |
class attribute |
'egress.authority.refused' |
EGRESS_AUTHORITY_AMBIGUOUS |
class attribute |
'egress.authority.ambiguous' |
MCP_MANIFEST_CHECKED |
class attribute |
'mcp.manifest.checked' |
MCP_MANIFEST_BLOCKED |
class attribute |
'mcp.manifest.blocked' |
TASK_CREATED |
class attribute |
'task.created' |
TASK_STARTED |
class attribute |
'task.started' |
TASK_COMPLETED |
class attribute |
'task.completed' |
TASK_FAILED |
class attribute |
'task.failed' |
TASK_CANCELLED |
class attribute |
'task.cancelled' |
TASK_INTERRUPTED_HANDOFF |
class attribute |
'task.interrupted_handoff' |
TASK_COMPLETION_RESULT_RESOLVED |
class attribute |
'task.completion_result.resolved' |
MODEL_STARTED |
class attribute |
'model.started' |
MODEL_TEXT_DELTA |
class attribute |
'model.text.delta' |
MODEL_THINKING_DELTA |
class attribute |
'model.thinking.delta' |
MODEL_HOSTED_TOOL_CALL |
class attribute |
'model.hosted_tool_call' |
MODEL_CITATION |
class attribute |
'model.citation' |
MODEL_COMPLETED |
class attribute |
'model.completed' |
MODEL_AUXILIARY_ATTEMPT_STARTED |
class attribute |
'model.auxiliary.attempt_started' |
MODEL_AUXILIARY_ATTEMPT_SETTLED |
class attribute |
'model.auxiliary.attempt_settled' |
MODEL_ERROR |
class attribute |
'model.error' |
MODEL_HTTP_CLEANUP |
class attribute |
'model.http_cleanup' |
MODEL_RETRY |
class attribute |
'model.retry' |
MODEL_ATTEMPT_DISCARDED |
class attribute |
'model.attempt_discarded' |
MODEL_FAILOVER_SELECTED |
class attribute |
'model.failover.selected' |
MODEL_FAILOVER_EXHAUSTED |
class attribute |
'model.failover.exhausted' |
PROVIDER_OPERATION_STARTING |
class attribute |
'provider.operation.starting' |
PROVIDER_OPERATION_STARTED |
class attribute |
'provider.operation.started' |
PROVIDER_OPERATION_PROGRESS |
class attribute |
'provider.operation.progress' |
PROVIDER_OPERATION_CANCEL_REQUESTED |
class attribute |
'provider.operation.cancel_requested' |
PROVIDER_OPERATION_CANCEL_RESOLVED |
class attribute |
'provider.operation.cancel_resolved' |
PROVIDER_OPERATION_RECONNECT_SCHEDULED |
class attribute |
'provider.operation.reconnect_scheduled' |
PROVIDER_OPERATION_RECONNECT_STARTED |
class attribute |
'provider.operation.reconnect_started' |
PROVIDER_OPERATION_RECOVERY_REQUIRED |
class attribute |
'provider.operation.recovery_required' |
PROVIDER_OPERATION_RESOLVED |
class attribute |
'provider.operation.resolved' |
PROVIDER_OPERATION_RECONCILED |
class attribute |
'provider.operation.reconciled' |
REQUEST_FOOTPRINT_RECORDED |
class attribute |
'request.footprint.recorded' |
TOOL_EXPOSURE_RECORDED |
class attribute |
'tool.exposure.recorded' |
TARGETED_TOOL_GRANT_ISSUED |
class attribute |
'tool.grant.issued' |
TARGETED_TOOL_GRANT_REUSED |
class attribute |
'tool.grant.reused' |
TARGETED_TOOL_GRANT_RECONSTRUCTED |
class attribute |
'tool.grant.reconstructed' |
TARGETED_TOOL_GRANT_EXPIRED |
class attribute |
'tool.grant.expired' |
TARGETED_TOOL_GRANT_REVOKED |
class attribute |
'tool.grant.revoked' |
TARGETED_TOOL_GRANT_FORK_RESET |
class attribute |
'tool.grant.fork_reset' |
TARGETED_TOOL_REFERENCE_CONSUMED |
class attribute |
'tool.reference.consumed' |
TARGETED_TOOL_REFERENCE_REJOINED |
class attribute |
'tool.reference.rejoined' |
TARGETED_TOOL_REFERENCE_REJECTED |
class attribute |
'tool.reference.rejected' |
STRUCTURED_OUTPUT_VALIDATED |
class attribute |
'structured_output.validated' |
STRUCTURED_OUTPUT_VALIDATING |
class attribute |
'structured_output.validating' |
STRUCTURED_OUTPUT_FAILED |
class attribute |
'structured_output.failed' |
STRUCTURED_OUTPUT_RETRY |
class attribute |
'structured_output.retry' |
CONTEXT_COMPACTION_STARTED |
class attribute |
'context.compaction.started' |
CONTEXT_COMPACTION_COMPLETED |
class attribute |
'context.compaction.completed' |
CONTEXT_COMPACTION_FAILED |
class attribute |
'context.compaction.failed' |
CONTEXT_COUNTED |
class attribute |
'context.counted' |
CONTEXT_COUNT_FAILED |
class attribute |
'context.count.failed' |
CONTEXT_COUNT_RECONCILED |
class attribute |
'context.count.reconciled' |
CONTEXT_PRESSURE_ESTIMATED |
class attribute |
'context.pressure.estimated' |
CONTEXT_PRESSURE_RECONCILED |
class attribute |
'context.pressure.reconciled' |
CONTEXT_OVERFLOW_DETECTED |
class attribute |
'context.overflow.detected' |
CONTEXT_OVERFLOW_RECOVERING |
class attribute |
'context.overflow.recovering' |
CONTEXT_OVERFLOW_FAILED |
class attribute |
'context.overflow.failed' |
AUTOMATIC_RECALL_STARTED |
class attribute |
'memory.recall.started' |
AUTOMATIC_RECALL_COMPLETED |
class attribute |
'memory.recall.completed' |
AUTOMATIC_RECALL_FAILED |
class attribute |
'memory.recall.failed' |
AUTOMATIC_RECALL_ADMITTED |
class attribute |
'memory.recall.admitted' |
ENVIRONMENT_BINDING_STARTED |
class attribute |
'environment.binding.started' |
ENVIRONMENT_BINDING_COMPLETED |
class attribute |
'environment.binding.completed' |
ENVIRONMENT_BINDING_FAILED |
class attribute |
'environment.binding.failed' |
ENVIRONMENT_BINDING_FINALIZE_STARTED |
class attribute |
'environment.binding.finalize_started' |
ENVIRONMENT_BINDING_FINALIZE_COMPLETED |
class attribute |
'environment.binding.finalize_completed' |
ENVIRONMENT_BINDING_FINALIZE_FAILED |
class attribute |
'environment.binding.finalize_failed' |
ENVIRONMENT_FACTORY_STARTED |
class attribute |
'environment.factory.started' |
ENVIRONMENT_FACTORY_COMPLETED |
class attribute |
'environment.factory.completed' |
ENVIRONMENT_FACTORY_FAILED |
class attribute |
'environment.factory.failed' |
ENVIRONMENT_LIFECYCLE_PROGRESS |
class attribute |
'environment.lifecycle.progress' |
ENVIRONMENT_LIFECYCLE_TRANSITION |
class attribute |
'environment.lifecycle.transition' |
ENVIRONMENT_DEFERRED |
class attribute |
'environment.deferred' |
ENVIRONMENT_MATERIALIZATION_STARTED |
class attribute |
'environment.materialization.started' |
ENVIRONMENT_MATERIALIZATION_COMPLETED |
class attribute |
'environment.materialization.completed' |
ENVIRONMENT_MATERIALIZATION_FAILED |
class attribute |
'environment.materialization.failed' |
WORKSPACE_REVISION_OBSERVED |
class attribute |
'workspace.revision.observed' |
WORKSPACE_MUTATION_RECORDED |
class attribute |
'workspace.mutation.recorded' |
WORKSPACE_OBSERVATION_FINALIZED |
class attribute |
'workspace.observation.finalized' |
HOOK_STARTED |
class attribute |
'hook.started' |
HOOK_COMPLETED |
class attribute |
'hook.completed' |
HOOK_FAILED |
class attribute |
'hook.failed' |
TOOL_CALL_STARTED |
class attribute |
'tool.call.started' |
TOOL_CALL_COMPLETED |
class attribute |
'tool.call.completed' |
TOOL_CALL_FAILED |
class attribute |
'tool.call.failed' |
TOOL_EFFECT_RECONCILIATION_OBSERVED |
class attribute |
'tool.effect.reconciliation.observed' |
TOOL_EFFECT_OUTCOME_UNKNOWN |
class attribute |
'tool.effect.outcome_unknown' |
TOOL_EFFECT_CLEANUP_OBSERVED |
class attribute |
'tool.effect.cleanup.observed' |
TOOL_EFFECT_RECONCILIATION_STARTED |
class attribute |
'tool.effect.reconciliation.started' |
TOOL_EFFECT_RECONCILIATION_CONFLICT |
class attribute |
'tool.effect.reconciliation.conflict' |
TOOL_EFFECT_RECEIPT_VALIDATED |
class attribute |
'tool.effect.receipt.validated' |
TOOL_CALL_BLOCKED |
class attribute |
'tool.call.blocked' |
TOOL_CALL_APPROVAL_REQUESTED |
class attribute |
'tool.call.approval_requested' |
TOOL_CALL_APPROVED |
class attribute |
'tool.call.approved' |
TOOL_CALL_APPROVAL_DENIED |
class attribute |
'tool.call.approval_denied' |
TOOL_CALL_APPROVAL_EXPIRED |
class attribute |
'tool.call.approval_expired' |
WORKFLOW_STARTED |
class attribute |
'workflow.started' |
WORKFLOW_STEP_STARTED |
class attribute |
'workflow.step.started' |
WORKFLOW_STEP_COMPLETED |
class attribute |
'workflow.step.completed' |
WORKFLOW_COMPLETED |
class attribute |
'workflow.completed' |
MEMORY_SEARCH |
class attribute |
'memory.search' |
RUNNER_EXEC_STARTED |
class attribute |
'runner.exec.started' |
RUNNER_EXEC_COMPLETED |
class attribute |
'runner.exec.completed' |
RUNTIME_SINK_FAILED |
class attribute |
'runtime.sink.failed' |
RUNTIME_INTERACTION_TRANSITION_ACKNOWLEDGEMENT_FAILED |
class attribute |
'runtime.interaction_transition.acknowledgement_failed' |