Skip to content

cayu.tasks.worker

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.

complete_managed_task

Section titled “complete_managed_task”
from cayu.tasks import complete_managed_task

Complete a managed worker task against its latest acknowledged lease.

async complete_managed_task(task_store: TaskStore, task: Task, worker_id: str, result: dict[str, Any]) -> Task

Release source · Runtime guarantees · Capability guides

fail_managed_task

Section titled “fail_managed_task”
from cayu.tasks import fail_managed_task

Fail a managed worker task against its latest acknowledged lease.

async fail_managed_task(task_store: TaskStore, task: Task, worker_id: str, error: dict[str, Any]) -> Task

Release source · Runtime guarantees · Capability guides

run_task_worker

Section titled “run_task_worker”
from cayu.tasks import run_task_worker

Claim and handle durable tasks until stopped; return the number handled.

For each claimed task, handler(app, task, worker_id) is awaited while the task lease is heartbeated in the background. The handler typically builds a RunRequest(task_id=task.id, task_worker_id=worker_id, task_lease_expires_at=task.lease_expires_at, ...) and awaits app.run(...) so the runtime completes/fails the task. If that run ends at a durable interrupted boundary, return TaskHandlerOutcome.SESSION_INTERRUPTED so the helper validates the session and releases only the task’s worker lease.

  • query scopes which tasks this worker claims (e.g. by type / assigned agent).
  • lease_seconds is the claim lease; the lease is re-extended at ~1/3 of it.
  • poll_interval_s is the bounded dispatch-latency objective when idle.
  • minimum_idle_delay_s / maximum_idle_delay_s bound adaptive polling.
  • idle_backoff_multiplier and idle_jitter_ratio control empty-claim backoff without changing the dispatch-latency bound.
  • reclaim periodically returns expired leases from dead workers to pending.
  • reclaim_every_s controls that cadence independently of task claims.
  • recover_interrupted_handoffs owns bounded recovery of expired attached task workers. Elect one such scanner for each shared task store.
  • interrupted_handoff_recovery_every_s controls the scanner’s exhausted rescan cadence independently of claim and expired-lease polling.
  • recovered_interrupted_task_handler makes this worker available to claim and continue receipt-backed workerless tasks. This execution capacity is independent of expired-owner scanner election.
  • continuation_poll_interval_s bounds rediscovery latency after an empty continuation scan. It defaults to poll_interval_s.
  • stop is an asyncio.Event for graceful shutdown.
  • max_tasks bounds the loop (useful for tests and one-shot drains).
async run_task_worker(app: CayuApp, task_store: TaskStore, handler: TaskHandler, *, worker_id: str, query: TaskQuery | None=None, lease_seconds: int=300, poll_interval_s: float=1.0, metrics: DurableWorkerMetrics | None=None, minimum_idle_delay_s: float | None=None, maximum_idle_delay_s: float | None=None, idle_backoff_multiplier: float=2.0, idle_jitter_ratio: float=0.1, reclaim: bool=True, reclaim_every_s: float=60.0, recover_interrupted_handoffs: bool=True, interrupted_handoff_recovery_every_s: float=_INTERRUPTED_HANDOFF_RECOVERY_RESCAN_SECONDS, recovered_interrupted_task_handler: RecoveredInterruptedTaskHandler | None=None, continuation_poll_interval_s: float | None=None, stop: asyncio.Event | None=None, max_tasks: int | None=None) -> int

Release source · Runtime guarantees · Capability guides

TaskHandlerOutcome

Section titled “TaskHandlerOutcome”
from cayu.tasks import TaskHandlerOutcome

Explicit non-terminal outcomes supported by run_task_worker.

Bases: 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
SESSION_INTERRUPTED class attribute 'session_interrupted'

Release source · Runtime guarantees · Capability guides