Any WordPress feature that calls a paid model has the same three needs. It needs a place for work to wait, so a burst of saves does not become a burst of bills. It needs something to ask before it spends, and something to tell after. And it needs its prompt somewhere an editor can change it without a code change. We built each of those as its own plugin: gen-queue, spend-meter and prompt-library. Underneath them sits llm-json-php, the plain PHP client that actually makes a call and turns the answer into a validated array.
Each piece answers a different question, and a site may want only one answer: a ledger without a queue, or versioned prompts with no automation at all.
So each plugin is complete on its own, and none requires another. They talk only through WordPress filters and actions. A consumer plugin, such as tldr-block, detects each one at run time and keeps its own fallback for when it is missing: its own daily cap, its own kill switch, its own WP-Cron event, its own built-in prompt text. Removing a service plugin must never stop the consumer, and must never let it spend without a limit.
gen-queue calls no provider. spend-meter makes no outbound HTTP request. prompt-library calls nothing outside its own test runner. The model call belongs to the consumer, usually through llm-json-php.
spend-meter is a ledger, a price table, daily and monthly caps and a kill switch, shared by every plugin on the site. Its whole public face is a filter and two actions.
Before a call, the consumer applies spend_meter_pre_spend with null as the value and an intent array as the argument. The intent has four required keys: purpose (a slug for what the call is for), caller (the plugin slug), provider and model. Optional keys include est_input_tokens, max_output_tokens and dry_run. Prompt text never goes in.
If the filter returns null, no meter is installed. When spend-meter is absent, nothing is hooked and WordPress hands back the default untouched. The consumer then falls back to its own guards.
If the meter is present, the filter returns a decision array with every key always present: allowed, reason, message, reservation_id, estimate, remaining and api. The rule for the caller is short. If allowed is not exactly true, do not make the call. Never parse message; it is for logs.
The reason codes in contract 1 are ok, kill_switch, kill_switch_purpose, invalid_request, unpriced_model, the six cap codes from cap_purpose_day to cap_network_month, ledger_unavailable, denied_by_filter and decision_filter_error. New codes may arrive in a minor version, so any code a caller does not know is a deny.
A site can add its own rules through the spend_meter_decision filter, but only to deny. An attempt to turn a deny into an allow is ignored and logged.
An allowed check that is not a dry run writes a reserved row holding the estimate, and only then sums the window totals. Two processes racing near a cap each see the other’s reservation. Both may be denied; neither overshoots. A false deny costs one retried call. An overshoot costs money.
A decision that carries a reservation_id must be followed by exactly one of two things. Either the call happened, and the consumer fires spend_meter_record, or it decided not to call, and it fires spend_meter_release with the id. An unsettled reservation stops counting after its lifetime (15 minutes by default); a late record still settles it.
spend_meter_record takes one call array per attempt, billed or not. A retry is a new attempt: it carries the same reservation_id and gets its own linked row. The status is one of ok, error_billed or error_unbilled. A 200 response with a broken body is still error_billed, because the provider charged for it. provider_cost is the billed cost in integer nanos (one billionth of the currency unit), and when the provider reports it, it wins over the table price. Recording never throws into the caller.
spend-meter ships no prices. Its example price file holds placeholders that fail validation on purpose, so it cannot be imported unread. A model with no row in the operator’s own table is unpriced, and unpriced models are denied with unpriced_model unless the operator turns on “Allow unpriced models”. So every call is denied straight after install. A stale or guessed default price would make the ledger wrong without any warning.
The plugin defines SPEND_METER_API, an integer, when its file loads. It is 1 in 0.1.0, and every decision carries the same number in api. It rises by one on any breaking change, before or after 1.0.0: a renamed hook, a removed reason code, a new required key. A caller built for contract 1 checks for exactly 1 and treats anything lower as absent.
gen-queue is a job queue for paid generation work. A consumer registers a job type with a handler on gen_queue_register_types, enqueues jobs, and reports what each call cost through $ctx->addCost(). gen-queue never publishes anything.
The first rule is that nothing runs until a daily cap is set. A cap of 0 runs nothing either. There is no default cap, for the same reason spend-meter has no default price.
Claims are atomic. A runner takes one of a fixed number of worker slot rows, or stops with busy, which it never confuses with empty. Under a short claim lock it reads the switch, the cap and today’s spend fresh from the database, checks the type cap, the gen_queue_can_run veto filter and spend-meter, then claims the job with one conditional UPDATE ... SET status = 'running', attempts = attempts + 1 ... WHERE id = ? AND status = 'queued'. Two runners cannot both win it. The locks are rows with an owner and an expiry, not MySQL named locks, so a dead process frees them.
The attempt row is written before the handler runs. A fatal error in the handler therefore cannot leave a job that looks untried and gets paid for again and again.
Handlers signal outcomes with exceptions. RetryableException retries with full-jitter backoff and counts towards the resource’s cooldown. PermanentException fails at once. AccountException requeues without using an attempt and holds the whole group, because an empty account balance is not one job’s fault, and treating it as one would burn every job’s retries. After two consecutive retryable failures on a resource key (a provider and model), that key cools for ten minutes by default, and jobs on other keys keep running.
When spend-meter is present, gen-queue asks it before each job with a dry-run intent built from the type’s meter option, and forwards costs that the handler did not mark as already metered. A null answer or allowed: true lets the job run, kill_switch stops the runner, anything else keeps the job waiting. gen-queue’s own cap still applies whatever the meter says.
prompt-library stores each template as a private post type, with the draft in post meta so that no content filter or kses pass touches the text. Placeholders are {{ name }}, with declared, typed variables and no logic.
Publishing validates the draft and writes an immutable numbered version with the author, the time, a required note and a SHA-256 content hash. Versions are rows in the plugin’s own table, not WordPress revisions, which sites limit or switch off.
Each template has a live pointer. A consumer asks for live or pins a number. “Make live” on an older version is the rollback. Every pointer move writes a history row with who, when, from, to and why, and the history row is written before the pointer moves, so a failed history write leaves the live version where it was. latest is an alias resolved at render time to the highest number and is never stored.
A consumer can declare the variables it supplies with promptlib_register_consumer(), and ship its own default template with promptlib_register_default(), which is installed as version 1 only if the slug is free.
tldr-block writes a short post summary for an editor to approve. Its integration code lives in src/Integrations/, one class per service. This is its spend-meter bridge, trimmed:
final class SpendMeter
{
public const CONTRACT = 1;
public const PRE_SPEND_FILTER = 'spend_meter_pre_spend';
public const PURPOSE = 'tldr-block.summary';
public const CALLER = 'tldr-block';
public static function present(): bool
{
return defined('SPEND_METER_API') && constant('SPEND_METER_API') === self::CONTRACT;
}
public static function preSpend(string $provider, string $model, int $estInputTokens = 0, int $maxOutputTokens = 0): ?array
{
if (!self::present()) {
return null;
}
$intent = [
'purpose' => self::PURPOSE,
'caller' => self::CALLER,
'provider' => self::slug($provider),
'model' => self::model($model),
];
// ... optional token estimates ...
try {
$d = apply_filters(self::PRE_SPEND_FILTER, null, $intent);
} catch (\Throwable $e) {
Logger::log('warning', 'spend-meter error, treated as absent', ['error' => $e->getMessage()], 'spend_meter');
return null;
}
if ($d === null) {
return null;
}
// ... an unusable answer is also treated as absent ...
$rid = $d['reservation_id'] ?? null;
return [
'allowed' => $d['allowed'] === true,
'reason' => is_string($d['reason'] ?? null) && $d['reason'] !== '' ? $d['reason'] : 'spend_meter',
'reservation_id' => is_string($rid) && $rid !== '' ? $rid : null,
];
}
}
Its gen-queue bridge uses the soft enqueue filter, so it never calls a gen-queue function that might not exist:
$id = apply_filters(self::ENQUEUE_FILTER, null, self::JOB_TYPE, ['post_id' => $postId, 'token' => $token], [
'idempotency_key' => 'post:' . $postId . ':' . $token,
'run_after' => $runAfter,
'group' => self::GROUP,
'max_attempts' => 1,
'source' => 'tldr-block',
]);
A null or a WP_Error there means the plugin schedules its own WP-Cron event instead. The handler reports cost with $ctx->addCost($cost, ['metered' => SpendMeter::present()]), so gen-queue’s cap sees the spend but does not forward a second ledger row for a call spend-meter already recorded. The prompt goes through the promptlib_render filter; null means the built-in text. Each integration is optional, and each fallback still caps spend.
These plugins, like all 47 of our utilities, 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 separate 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 builder seeing only the spec is a good rule for catching gaps in a spec. It had a cost here. More than half of the consumer plugins were first written against guessed hook names and guessed argument shapes, not the contracts the three services actually released. Those integrations never ran. Nothing failed loudly: a filter nobody listens to returns its default, and for spend-meter the default is null, which correctly means “no meter”. A guessed hook name and a missing plugin look identical from the caller’s side.
Review caught it by checking each consumer’s hook names against the released 0.1.0 contracts (What an independent code review caught lists the other classes of defect it found). One consumer built a RetryableException with the wrong constructor arguments, which would have thrown a TypeError on the first retry. One sent pre-spend intents without a model, which spend-meter denies. One left jobs orphaned when gen-queue parked them. Each was aligned to the real filter names, the real intent keys, one call array per attempt, and one record or release per reservation.
Two things changed as a result. The contract is now written out in the service plugin’s README (hooks, keys, reason codes) and in the consumer’s README or its integration class, naming the contract version it was built against: featured-from-prompt and comment-draft-replies state “contract SPEND_METER_API 1″ in their READMEs, and tldr-block states it in the class above. And the version is an integer that a caller compares for equality. A consumer that sees a number it was not built for treats the meter as absent and uses its own caps, rather than guessing what the new contract means.
wp gen-queue status --format=json, wp spend-meter status). prompt-library does have a capability-checked REST namespace for its editor and test runner.promptlib_api_version() returns the string 1.0.