gen-queue: a capped job queue for paid generation work

A WordPress job queue for plugins that call a paid generation API in bulk. It has a daily spend cap that defaults to nothing running, a kill switch, retries and per-attempt cost records.

gen-queue is a WordPress plugin that runs paid generation work on behalf of other plugins. It is for plugin developers who call a paid API in bulk and for the site operators who have to pay for it. The code is at https://github.com/IndianOpinion/gen-queue, licensed MIT, and version v0.1.0 was released on 15 November 2026.

It holds no prompts and calls no provider. Another plugin registers a handler, enqueues jobs and reports what each call cost. We wrote it from scratch from an idea, with no third-party plugin as a starting point. It has not run on a live site.

The 47 utilities in this series were specified, built, reviewed and released between 11 and 19 November 2026 by language-model coding agents working under the editor’s direction, in five roles: a spec writer, a spec reviewer, a builder that saw only the spec, an independent code reviewer and a releaser. The editor made the rulings on every open question.

The problem

Plugins that call a paid API in bulk each write the same loop, and each gets the same things wrong. The PRD lists them:

  • Work is selected but not claimed, so an overlapping backfill pays for the same item twice.
  • A runner cannot tell “another runner holds the lock” from “the queue is empty”, so a long drain stops early.
  • A fatal error mid-request leaves the row looking untried, so the next run pays again, and again.
  • A daily cap is read once at the start of a run, so concurrent runners overshoot it.
  • An empty account balance is treated as one job’s failure, so every job burns its retries on the same account error.

gen-queue does that loop once. The plugin that generates things writes only a handler.

What it does

  • Stores jobs durably, with a JSON payload, priority, expiry and an optional idempotency key.
  • Runs them from WP-Cron or from WP-CLI, safely at the same time.
  • Stops at a daily spend cap and at a kill switch, both global and per job type.
  • Retries with full-jitter exponential backoff, and separates retryable, permanent and account errors.
  • Cools a resource key (for example a model name) after repeated failures, and holds a whole account group after an account error.
  • Records the cost of every attempt and shows jobs, spend, cooling keys and holds on a status page under Tools.
  • Offers a soft integration with spend-meter.

How it works

There are three tables: jobs, attempts (one row per run of a handler, with its cost and local day) and a small lock table. Settings and breaker state are options. Every database call goes through a storage interface with a $wpdb implementation and an in-memory double for tests.

A runner is a WP-Cron tick or wp gen-queue run. Both use Runner::run(). The steps per job are:

  1. Read the switch, pause list, cap and today’s spend straight from the database, past any object cache.
  2. Select up to 25 candidates in order: priority descending, then run_after, then id.
  3. Under a short claim lock, check the global cap, the type cap, the gen_queue_can_run filter and spend-meter, then claim the job with one conditional UPDATE that only matches a row still queued.
  4. Count the attempt and write its row before the handler runs.
  5. Run the handler, then close the attempt with a single update keyed by the job’s lease token.

A job may run when spent today plus reserved plus its estimate is at most the cap. Money is held as integer nanos. Costs count on the site’s local day on which the attempt started. If a worker dies, its lease expires, the next runner closes the attempt as abandoned and retries the job. A late result from the dead worker is discarded, but its cost is kept.

A handler looks like this, taken from the README:

add_action('gen_queue_register_types', function (): void {
    gen_queue_register_type('my-plugin.summary', 'my_summary_handler', [
        'resource_key'  => 'my-provider/small-model',
        'group'         => 'my-provider',
        'cost_estimate' => '0.01',
        'timeout'       => 60,
    ]);
});

gen_queue_enqueue('my-plugin.summary', ['post_id' => 42], ['idempotency_key' => 'summary-42']);

Guard rails

  • No cap means nothing runs. An unset cap is not unlimited. A cap of 0 also runs nothing. This holds on every entry point, and a spend-meter that has no cap does not stand in for it.
  • The constant GEN_QUEUE_DISABLED forces the queue off, and the kill switch option cannot turn it back on.
  • A deliberate stop (switch, pause, cap, cooldown) never consumes an attempt.
  • Expiry is suspended while the switch is off, so a pause keeps its backlog.
  • Any exception that is not one of the queue’s own fails the job at once and stores only the class name, not the message. Retrying a handler bug could repeat a paid call.
  • Stored error text is redacted (bearer tokens, URL credentials, names ending in key, token or secret) and cut to 500 bytes.
  • Admin actions need a capability and a nonce. Payloads are hidden on the status page by default.
  • The queue never publishes. Handlers write drafts, pending comments or suggestions for an editor to accept.
  • A failed schema check blocks running until a reinstall verifies the columns.

What review changed

The independent code review found and fixed these before the merge:

  • Stale candidates could win a claim. A job that another runner had just failed into backoff, or whose key had just started cooling, could still be claimed. The claim now re-reads the cooldown and hold under the lock and requires the same attempts and run_after in the UPDATE.
  • Cooldown and hold state was updated with no lock, so two runners failing on one provider could lose a count. It now goes through a lock row.
  • The account hold is now written before the job is requeued, so no runner claims a held group’s job in between.
  • An idle WP-Cron tick cost 26 queries against a budget of 6. An idle fast path brought it to 5, asserted by an integration test.

Limits and what is next

  • No REST API in 0.1.0. Use wp gen-queue status --format=json.
  • One queue and one cap per site. On multisite each site has its own.
  • First in, first out within a priority. There is no newest-first order; give new work a higher priority.
  • PHP cannot stop a handler that overruns its timeout. Its lease expires and another runner may retry the job.
  • No price table. The handler reports each call’s cost.
  • Two runners failing on one key at the same instant may count one failure, not two, if the lock row cannot be had in time.

This is v0.1.0 and there are no open issues. Tests: 155 unit tests against a WordPress stub layer, and 10 integration tests against MySQL 8.0 on a throwaway server, including four runner processes draining one queue with every job run once. Static analysis and code style checks passed. CI has not yet run on GitHub: the workflow commit stayed local because the token lacked the workflow scope.

Install

It needs PHP 8.1 or later, WordPress 6.4 or later, and MySQL 5.7+ or MariaDB 10.4+. It has no runtime dependencies.

The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/gen-queue.

composer require indianopinion/gen-queue
wp gen-queue cap 2.50
wp gen-queue run --until-empty

It can also be copied into wp-content/plugins/, or into wp-content/mu-plugins/ with the loader in examples/.

All 47 utilities · gen-queue on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.