Run workers

A named worker is an async function with two required positional arguments, (app, stop). The CLI constructs the app once and supplies an asyncio.Event for cooperative shutdown.

[tool.cayu.workers]
dispatch = "workers:run_dispatch"

This complete entrypoint assumes the factory configured a TaskStoreDispatcher:

import os
import socket

from cayu import CayuApp, TaskStoreDispatcher


async def run_dispatch(app: CayuApp, stop) -> None:
    if not isinstance(app.dispatcher, TaskStoreDispatcher):
        raise RuntimeError("Configure a TaskStoreDispatcher in the factory")
    await app.dispatcher.run_worker(
        app, worker_id=f"{socket.gethostname()}-{os.getpid()}", stop=stop
    )

cayu worker dispatch --shutdown-grace-seconds 45

Choose the loop

The dispatcher continues existing sessions. run_task_worker claims fresh tasks and calls your handler; the handler owns the domain-specific request and terminal result. Use tasks and workflows to choose between them.

The CLI does not infer a task query, handler or recovery policy. It performs no implicit incomplete-session recovery. Configure recovery explicitly and inspect pending approvals/input before attempting continuation.

Add processes

On supported POSIX hosts, --processes N runs independent interpreters and app graphs. Use the same durable stores and unique worker IDs. In-memory stores remain separate. Limits inside an entrypoint apply per process; an entrypoint that starts the same unclaimed request will do so in every process.

SIGINT/SIGTERM request cooperative shutdown. Grace exhaustion is a bounded process boundary, and a failed child stops siblings. Workers are not automatically restarted by this CLI. Reference: worker flags.