Meter usage and charge for it in a QiForge plugin

Write a Workers runtime plugin that meters every model call a person's turns make, sends the usage to your billing service, and refuses turns while the person cannot pay.

Use this recipe when people's use of your oracle has to be paid for: a credits balance, a quota or a suspension. You write one plugin that records what each turn cost, sends that usage to your billing service, and refuses the person's next turns while that service says they cannot pay. The refusal reaches the person on the Portal, in Matrix rooms and on WhatsApp with a link to top up.

The hooks are on the Cloudflare Workers runtime only. Every hook and type used here is described in Metering and turn-gating hooks.

Before you start

You need:

  • An oracle on @ixo/oracle-runtime-workers 0.58.0 or later. Earlier versions do not have these hooks.
  • A billing service that accepts usage events and can answer "this person cannot pay". The plugin below only queues events; sending them is yours to write.
  • For Portal clients: @ixo/oracles-client-sdk 1.10.0 or later. Earlier versions treat a refused 403 as a credential failure and ask the person to sign in again.

Steps

Refuse turns while the person is blocked

gateTurn runs before every turn, on every entry. Read one row from ctx.kv and refuse while a block is in force. ctx.kv idle times slide on every read, so store the block's absolute end time as the value.

import {
  OraclePlugin,
  type PluginManifest,
  type TurnGateContext,
  type TurnGateResult,
} from '@ixo/oracle-runtime-workers';

const NS = 'meter';

export class MeterPlugin extends OraclePlugin {
  readonly name = 'meter';
  readonly version = '1.0.0';
  readonly manifest: PluginManifest = {
    title: 'Meter',
    summary: 'Meters model usage and refuses turns over budget.',
    whenToUse: [],
    visibility: 'silent',
    stability: 'stable',
    category: 'core',
  };

  // A failing gate refuses (503 turn_gate_unavailable) instead of
  // letting unpaid turns through. 300 ms is enough for one kv read.
  override readonly turnGate = { onFailure: 'closed' as const, timeoutMs: 300 };

  override async gateTurn(ctx: TurnGateContext): Promise<TurnGateResult> {
    const until = await ctx.kv?.get(NS, 'blockedUntil');
    if (typeof until === 'number' && until > Date.now())
      return {
        refuse: {
          status: 402,
          code: 'credits_exhausted',
          // Plain text, complete on its own, no URL: every surface shows it.
          message: 'You are out of credits. Top up to continue.',
          // The link goes in `action`: https, label at most 40 characters.
          details: {
            action: { label: 'Top up', url: 'https://<your-top-up-page>' },
          },
        },
      };
    return { allow: true };
  }
}

Choose onFailure deliberately. 'closed' refuses every turn when the gate fails, which protects you from unpaid usage but stops everyone if your storage read fails. 'open' (the default) lets turns run when the gate fails.

To let a blocked person keep chatting on their own model provider, answer { allow: true, platformModels: 'deny' } instead of refusing when the turn would run on their provider (the request names a byo: model, or names none and await ctx.hasByoCredentials() is true). Nothing of that turn then runs on your oracle's model key. See Allow a turn on the person's own provider only.

Record one usage event per turn

onTurnUsage gets every model call of a turn attempt once the attempt has ended. Charge only calls with paidBy: 'platform': a paidBy: 'user' call ran on the person's own provider, and they pay that provider themselves. Build the event's id from the call ids, so a resend can never charge twice.

import type { RuntimeContext, TurnModelUsage } from '@ixo/oracle-runtime-workers';

// inside MeterPlugin
override async onTurnUsage(usage: TurnModelUsage, ctx: RuntimeContext): Promise<void> {
  const charged = usage.calls.filter((c) => c.paidBy === 'platform');
  if (charged.length === 0) return;
  const event = {
    id: `${usage.runId}:${charged.map((c) => c.callId).join(',')}`,
    usd: usage.platformCostUsd,
    unpriced: usage.unpricedPlatformCalls,
  };
  await ctx.kv?.update(NS, 'pending', (queue) => [
    ...(Array.isArray(queue) ? queue : []),
    event,
  ]);
}

platformCostUsd sums only the provider-reported costs. Calls counted in unpricedPlatformCalls have tokens but no cost (for example Nebius models, or a call cut off mid-stream with usageEstimated: true). Price those from the model's list price, for example with the runtime's fetchOpenRouterPrices, or charge them as 0 and say so.

Calls made outside a turn (a group room's summary, channel routing before a run exists) reach onModelCall only. Meter them there and leave in-turn calls to onTurnUsage, so each call is counted once.

Send the events and set the block

Send the queued events to your billing service off the reply's path: the hooks already run in the background, and ctx.background(promise) keeps a send alive after the hook returns. Authenticate as the oracle with ctx.ucan.mintSelfSignedInvocation, and pass the person's delegation, ctx.user.ucanDelegation.raw, if your service charges the person who granted it.

When your service answers that the person cannot pay, write blockedUntil (now plus how long to wait before asking again) to ctx.kv. The gate from step 1 then refuses their next turn.

When a send fails, keep the event and retry later. Call ctx.requestWake(<retry time in epoch ms>) and resend in onWake(ctx), so the retry does not wait for the person's next message. A wake fires once: ask again for the next one, with backoff.

Verify it worked

  1. Write a blockedUntil row in the future for a test account, or let your billing service block it.
  2. Send that account a message from the Portal. The send fails with status 402, your code and refused: true (see Errors), and the client does not ask the person to sign in again.
  3. Send a message from the account's Matrix room. One notice arrives in the thread with your message and the action as a link. A second message within 10 minutes gets no notice.
  4. In the worker's logs, each refusal has one [turn-gate] refused line with the plugin, trigger, request id, status and code.
  5. Clear the row and send again. The turn runs, and your billing service receives one event for it.

Troubleshooting

Every turn is refused with 503 turn_gate_unavailable. The gate failed with onFailure: 'closed': it threw, returned something invalid, or took longer than timeoutMs. Look for the [turn-gate] warning with failure in the logs. A refusal with an invalid status, message or code, or details over 4 KiB, counts as invalid.

The refusal arrives without the link. details.action was dropped: the URL is not https: or the label is longer than 40 characters. The runtime logs a [turn-gate] line with dropped.

The Portal asks the person to sign in again on a refusal. The client is older than @ixo/oracles-client-sdk 1.10.0, or it renews credentials on every 403. A client must not renew on an answer that carries refused: true.

WhatsApp users get no reply when they are blocked. The person's IXO Channels gateway must handle turn_refused. A gateway that does not reads a 402 or 503 as the oracle being unavailable and a 403 as an authorization failure, and the person never sees the message.

A turn was charged twice, or not at all. Meter in-turn calls from onTurnUsage only and out-of-turn calls from onModelCall only, and keep each event's id the same across resends. An attempt the object stops in the middle (a deploy, an eviction) gets no onTurnUsage; its calls reached onModelCall only.