Huey

Requires Huey 2.4+ and <3, Python 3.10+. See the compatibility matrix for the full pin string.

Install

pip install z4j-huey

What it captures

Huey exposes signals:

Huey signal	z4j event
`SIGNAL_ENQUEUED`	`task_sent`
`SIGNAL_EXECUTING`	`task_started`
`SIGNAL_COMPLETE`	`task_succeeded`
`SIGNAL_ERROR`	`task_failed`
`SIGNAL_RETRYING`	`task_retry`
`SIGNAL_CANCELED`	`task_cancelled`
`SIGNAL_EXPIRED`	`task_expired`

Actions

Verb	How
`retry`	`huey.enqueue(original_task_function, *args)` - re-enqueues with same payload
`cancel`	`huey.revoke_by_id(task_id)`
`purge_queue`	`huey.flush()`

Periodic tasks

Huey’s @huey.periodic_task(crontab(...)) decorators are code - they can only be discovered by scanning decorated functions at agent start. z4j surfaces them as read-only schedules in the dashboard.

To pause a periodic task at runtime:

@huey.periodic_task(crontab(minute="0"))
def send_nightly_digest():
    ...

You can flip send_nightly_digest.disable() / enable() - but this is process-local, not cluster-global. z4j reports the state per-agent.

Sqlite / in-memory huey

Single-process setups (SQLite huey, MemoryHuey) work but each process has its own queue. The dashboard reflects this.

Caveats

Huey’s result expiry defaults to 7 days. If you look up an older task, you may get ResultTimeout - z4j renders this as “result expired” rather than lost.
No chord/group primitives.

See scheduler: huey-periodic.