cayu.tasks.dispatch

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

copy_dispatch_handle

from cayu.tasks import copy_dispatch_handle

copy_dispatch_handle(handle: DispatchHandle) -> DispatchHandle

Release source · Runtime guarantees · Capability guides

copy_dispatch_request

from cayu.tasks import copy_dispatch_request

copy_dispatch_request(request: DispatchRequest) -> DispatchRequest

Release source · Runtime guarantees · Capability guides

Dispatcher

from cayu.tasks import Dispatcher

Execution backend for dispatched session work.

Bases: ABC.

submit (method)

async Dispatcher.submit(runtime: DispatchRuntime, request: DispatchRequest) -> DispatchHandle

Submit dispatched session work and return a handle.

Release source · Runtime guarantees · Capability guides

DispatchHandle

from cayu.tasks import DispatchHandle

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
dispatch_id	str	required
session_id	str	required
backend	str	required
status	DispatchStatus	DispatchStatus.SUBMITTED
task_id	str | None	None
metadata	dict[str, Any]	Field(default_factory=dict)

copy_handle_metadata (method)

DispatchHandle.copy_handle_metadata(value: dict[str, Any]) -> dict[str, Any]

validate_optional_nonblank_strings (method)

DispatchHandle.validate_optional_nonblank_strings(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

DispatchRequest

from cayu.tasks import DispatchRequest

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
session_id	str	required
messages	list[Message]	required
dispatch_id	str	Field(default_factory=lambda: str(uuid4()))
task_id	str | None	None
target	ModelTarget | None	None
failover	ModelFailoverPolicy | None	Field(default=None, exclude_if=lambda value: value is None)
tool_capability_ceiling	ToolCapabilityCeiling | None	None
tool_grants	tuple[TargetedToolGrant, ...]	()
profile_adoption	ExecutionProfileAdoptionIntent | None	None
metadata	dict[str, Any]	Field(default_factory=dict)
max_steps	StrictInt	Field(default=DEFAULT_MAX_STEPS, ge=1, le=MAX_STEPS)
limits	RunLimits	Field(default_factory=RunLimits)
budget_limits	tuple[BudgetLimit, ...]	Field(default_factory=tuple)
retry_policy	RetryPolicy | None	None
structured_output	StructuredOutputSpec | None	None
thinking	ThinkingConfig | None	None
loop_policies	SkipJsonSchema[tuple[LoopPolicy, ...]]	Field(default_factory=tuple, exclude=True)

copy_failover (method)

DispatchRequest.copy_failover(value: object) -> ModelFailoverPolicy | None

copy_messages (method)

DispatchRequest.copy_messages(value)

copy_request_metadata (method)

DispatchRequest.copy_request_metadata(value: dict[str, Any]) -> dict[str, Any]

copy_structured_output (method)

DispatchRequest.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_tool_capability_ceiling (method)

DispatchRequest.copy_tool_capability_ceiling(value: object) -> ToolCapabilityCeiling | None

copy_tool_grants (method)

DispatchRequest.copy_tool_grants(value: object) -> tuple[TargetedToolGrant, ...]

copy_profile_adoption (method)

DispatchRequest.copy_profile_adoption(value: object) -> ExecutionProfileAdoptionIntent | None

copy_budget_limits (method)

DispatchRequest.copy_budget_limits(value) -> tuple[BudgetLimit, ...]

copy_limits (method)

DispatchRequest.copy_limits(value: RunLimits) -> RunLimits

copy_loop_policies (method)

DispatchRequest.copy_loop_policies(value) -> tuple[LoopPolicy, ...]

validate_optional_nonblank_strings (method)

DispatchRequest.validate_optional_nonblank_strings(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

DispatchRuntime

from cayu.tasks import DispatchRuntime

Bases: Protocol.

dispatch_inline (method)

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

Run dispatched work inline and stream runtime events.

Release source · Runtime guarantees · Capability guides

DispatchStatus

from cayu.tasks import DispatchStatus

Bases: StrEnum.

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
SUBMITTED	class attribute	'submitted'
RUNNING	class attribute	'running'
COMPLETED	class attribute	'completed'
FAILED	class attribute	'failed'
INTERRUPTED	class attribute	'interrupted'
CANCELLED	class attribute	'cancelled'

Release source · Runtime guarantees · Capability guides

InlineDispatcher

from cayu.tasks import InlineDispatcher

Runs dispatched session work immediately in the current process.

Bases: Dispatcher.

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
backend	class attribute	'inline'

submit (method)

async InlineDispatcher.submit(runtime: DispatchRuntime, request: DispatchRequest) -> DispatchHandle

Release source · Runtime guarantees · Capability guides

TaskStoreDispatcher

from cayu.tasks import TaskStoreDispatcher

Queue-backed dispatcher that persists work as claimable tasks in a TaskStore.

submit freezes the target session’s runtime-owned execution profile and enqueues the resulting envelope as a PENDING task instead of running it. A worker application claims that task (atomically — PostgresTaskStore uses FOR UPDATE SKIP LOCKED), validates the recorded profile, and enters the ordinary resume engine through the built-in queued-dispatch boundary. A bare custom DispatchRuntime does not provide that authority boundary; producers and workers must use a compatible CayuApp runtime. The dispatcher works with any TaskStore tier: InMemoryTaskStore (single process), SQLiteTaskStore (single node), or PostgresTaskStore (a distributed worker pool). Callers interact through DispatchHandle/ DispatchStatus; the backing Task id is surfaced as metadata["queue_task_id"] for observability.

Bases: Dispatcher.

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
backend	class attribute	'task_store'

submit (method)

async TaskStoreDispatcher.submit(runtime: DispatchRuntime, request: DispatchRequest) -> DispatchHandle

init (method)

TaskStoreDispatcher.__init__(task_store: TaskStore, *, task_type: str=DEFAULT_DISPATCH_TASK_TYPE, lease_seconds: int=300, recover_stalled_sessions_after_seconds: int | None=None) -> None

task_type (property)

TaskStoreDispatcher.task_type() -> str

Return the durable queue namespace used by this dispatcher.

prepared_subagent_task_type (property)

TaskStoreDispatcher.prepared_subagent_task_type() -> str

Return the versioned queue namespace reserved for prepared children.

invocation_control_task_type (property)

TaskStoreDispatcher.invocation_control_task_type() -> str

Return the versioned namespace for expanded resume controls.

exact_fork_task_type (property)

TaskStoreDispatcher.exact_fork_task_type() -> str

Return the versioned namespace for exact-fork child dispatches.

task_store (property)

TaskStoreDispatcher.task_store() -> TaskStore

Return the exact task store that owns this dispatcher’s leases.

process_next (method)

async TaskStoreDispatcher.process_next(runtime: DispatchRuntime, *, worker_id: str) -> DispatchHandle | None

Claim and run one queued dispatch.

Returns None if the queue is empty, or if the claimed task’s payload was malformed (in which case the task is failed before returning). Direct callers reconcile pending terminal receipts by default. run_worker suppresses that duplicate entrance in its task-local context because its independently elected periodic role owns that cadence.

run_worker (method)

async TaskStoreDispatcher.run_worker(runtime: DispatchRuntime, *, worker_id: str, stop: asyncio.Event, 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, reconcile_terminal_receipts: bool=True, reconciliation_every_s: float=60.0, reclaim_expired_leases: bool=True, reclaim_every_s: float=60.0) -> None

Claim and run with bounded adaptive demand and independent maintenance.

Release source · Runtime guarantees · Capability guides