docs · how it works

Metering agents you don’t control#

Islam Magdy, creator of Hekma · 7 September 2026, rewritten 17 November 2026

A snapshot from September 2026. This essay describes Hekma as it stood on 7 September 2026, when it was still called Ktesio and did one job: run an agent like a service, with a supervisor, a meter and a budget. Hekma is now becoming a control plane for agent workloads: every supervised agent becomes a Run, Policies set limits across many Runs and warn by default, and control on the model wire is planned.

The reasoning still holds; the mechanics have changed and keep changing. For how Hekma is built today, read Architecture; for what ships, Status and roadmap. Commands use today’s hekma; in September it was kt.

A long-running AI agent is a process that spends money every time it wakes up. One that loops, retries or gets stuck in a tool cycle can add thousands of lines to next month’s invoice before anyone looks. By agent I mean a program you run for yourself that calls a model on your behalf, such as a personal agent or a coding agent.

What is new is how casually we run them. A service gets a supervisor, a restart policy, logs you can read after it dies, and a metric somebody is paged on. An agent gets a terminal window and a shell script. Nobody can stop it cleanly, nobody knows what it consumed in the last hour, and the first accurate accounting arrives weeks later on a bill.

I built Hekma to run agents with the discipline I expect from services: start them, stop them, pause them, and know what they cost while they run, not after. The lifecycle half is unglamorous supervision work. This essay is about the metering half: where the meter goes, why it goes there, and what it missed when I wrote this.

The honour system#

The first design everyone reaches for, me included, is to let the agent say what it spent. The SDK exposes a usage callback, the framework logs a usage line, the agent prints a summary at the end of a run, and you call the sum a ledger.

Hekma supported this. An adapter can declare its metering self-reported, and the agent then prints a KTESIO_USAGE line on its stdout with a sequence number and its input and output token counts. The sequence number lets the engine recognise a replayed line and refuse to count it twice.

I would not build a cost policy on it, for four reasons:

  • Agents crash mid-run. The summary that would have carried the count is exactly the line that never gets written.
  • Agents retry silently. The provider returns an error, the client library retries three times, and the usage callback fires once, for the response that finally came back.
  • Agents call tools outside the reporting loop. A tool that summarises a document through its own model client is invisible to the outer callback.
  • Third-party adapters report whatever they choose. One agent I evaluated while freezing the adapter contract turns missing usage into zero instead of saying it does not know. Zero looks like a number. It is not one.

Add these up and self-reported metering is an honour system. That is fine for an agent you wrote, running code you can read. It is a strange foundation for a budget whose job is to stop a process you do not control from spending money you have not approved.

Put the meter on the wire#

Everything Hekma does about cost rests on one claim: cost governance cannot depend on the agent’s cooperation. The number a budget acts on has to come from a boundary the agent cannot bypass, cannot forget to update, and cannot round down to zero.

The electricity meter is the right picture. The utility does not ask the appliance how much it drew. The meter sits on the wire, between the appliance and the supply, and counts what actually passed. A broken appliance, a lying appliance and a well-behaved appliance are metered the same way, because the meter never asked their opinion. And if you want to stop the appliance, you cut the wire, from the meter’s side.

For an agent, the wire is its model traffic. Every token a provider bills for crosses an HTTP connection to that provider. If the engine sits on that connection, it can count what crossed without a single line of cooperation from the agent.

How Hekma did it in September#

Every agent declares where its numbers come from. An agent is registered through an adapter manifest, and the manifest must name a metering source. There is no none: an adapter without one is rejected at registration, before any state is written.

For engine-observed, the engine runs the meter itself. When the agent starts, the engine opens a listener on 127.0.0.1, on a port it picks, and refuses any address that is not loopback. It hands the agent that address through a reserved config key, metering.base_url, which the adapter maps into whatever the agent reads for its provider endpoint, typically OPENAI_BASE_URL. The operator points metering.upstream_base_url at the real provider. The agent believes it is talking to its provider. It is talking to the meter.

The listener is a transparent proxy. It forwards the method, path, query and headers as they are, including the agent’s own Authorization header, so the agent’s key goes upstream untouched, and it relays the status, headers and body back unchanged. If the provider cannot be reached, the agent gets a plain 502. On the way back the proxy reads the body once, takes usage.prompt_tokens and usage.completion_tokens, and puts those two integers on a queue. Nothing else leaves the proxy: no body, header, URL or key reaches a log, an error or a ledger row, and a test with a sentinel key proves it.

Both sources end in one ledger. The supervisor drains the queue every 250 milliseconds and hands each count to ingest_usage, the one function allowed to write the usage ledger: an append-only table in the engine’s SQLite database, one committed transaction per event. Each row carries the agent, the run, both token counts, the metering source, a timestamp and a sequence number, under a unique index, so a replayed event changes nothing. A run spans one start of the process to its end. Per-run totals cover that span, and cumulative totals sum every row the agent ever wrote.

Budgets are ordinary config keys, and you can change them while the agent runs:

hekma agent config set my-agent budget.tokens.cumulative 500000
hekma agent config set my-agent budget.breach_action pause
hekma agent config set my-agent cost.rate.input 3.00
hekma agent config set my-agent cost.rate.output 15.00
hekma agent config set my-agent budget.dollars.cumulative 10.00

The check runs where the usage commits#

Where enforcement runs matters most to me. Immediately after a new row commits, in the same call, ingest_usage re-reads the budget from config, reads the per-run and cumulative totals it has just committed, and compares them. Tokens are checked first, per run before cumulative, and reaching the ceiling counts as a breach. Then, if a rate is set, the dollar cap is checked the same way. On a breach the supervisor first writes a breach event to a durable log, then acts: pause, stop or warn. Pause is the default, and each limit fires once in a run.

The obvious alternative deserves a fair hearing. A separate watcher that reads the ledger every second and pauses anything over its ceiling is simpler, and it keeps ingestion fast and dumb. I rejected it because it leaves a window, between “usage recorded” and “budget checked”, in which the total is over the line and nobody has acted. Putting the check inside the commit path closes that window by construction. The price is a config read and two comparisons on every event. I will pay that.

Money is an estimate, and says so#

Money gets the same suspicion. Rates are dollars per million tokens, stored as whole micro-dollars, never floats. Each row is priced at the rate in force when it committed, so changing a rate never rewrites history. Every dollar figure Hekma prints comes out of one module and carries the label estimated, and a CI check fails the build if any other module formats a dollar.

In September, hekma agent usage my-agent --json printed the ledger’s view of an agent like this:

{
  "schema_version": 2,
  "instance": "my-agent",
  "usage": {
    "cumulative_input_tokens": 1200,
    "cumulative_output_tokens": 3400,
    "current_run_input_tokens": 120,
    "current_run_output_tokens": 340,
    "cumulative_dollars": 54600,
    "current_run_dollars": 5460,
    "estimate_label": "estimated"
  }
}

At the rates above, 1,200 input tokens and 3,400 output tokens come to 1,200 × $3 plus 3,400 × $15 per million: 54,600 micro-dollars, about five and a half cents. The token totals are the ledger’s sums exactly, the same numbers hekma agent list and hekma agent show print. With no rate set, the dollar fields are absent, not 0.

What the meter could not see#

A meter is only as good as the wire it sits on, and in September the wire had gaps. I would rather list them than have you find them on an invoice.

  • Traffic that never reached the meter. The proxy saw only what the agent sent to the injected address. If the adapter mapped metering.base_url nowhere, if the agent ignored the environment variable, or if it called a second endpoint, an embeddings API or a tool with its own model client, none of that was metered and nothing warned you. The totals simply stayed low, and a low total looks like good behaviour.
  • HTTPS providers. The upstream had to be plain http://. An https:// upstream was refused at start, with a message that said so. I shipped without a TLS stack to keep the dependency tree small, so metering a hosted provider needed a local hop that spoke plain HTTP to Hekma and TLS to the provider.
  • Streaming. Only whole JSON responses were parsed. A streamed completion was relayed faithfully and not metered at all. Neither was a response with no usage object, a malformed one, or one from a provider whose usage format was not OpenAI’s: the call succeeded and the ledger missed it.
  • Anything but two token counts. Cached input, reasoning tokens and provider pricing tiers were not modelled, so the dollar figure was an estimate from one flat rate per direction, and it would not match the provider’s invoice.
  • Requests already in flight. Enforcement acted on committed rows. Between the response that crossed the ceiling and the pause, the agent could have more requests on their way, and those reached the provider. A budget was a ceiling on what the ledger had seen, not a fence around what the agent could spend.
  • A pause the agent could ignore. A pause was only as strong as the adapter’s declaration. guaranteed on Unix stopped the whole process group with a signal; best-effort recorded the state change and sent nothing to the process, which could keep running. And warn recorded the breach and did nothing else.
  • Isolation. Binding to loopback kept the agent’s traffic and key off the network by accident. It was not a sandbox: an Agent Home kept agents’ files and processes apart, nothing stronger.
  • A meter that died with the command. The listener lived only as long as the process holding the engine. A plain hekma agent start supervised the agent for that command’s lifetime. If a later command adopted a surviving agent, the agent’s endpoint still pointed at a dead port, and its model calls failed until you stopped and started it. That failed loud, never wrong, but it was a gap, and the long-running host that would close it was still on the roadmap.

So an observed agent’s numbers were numbers it could not have faked, and they were a lower bound on what it spent.

What changed, and what did not#

Several of those gaps have closed. By Hekma 0.11.0 the proxy reaches HTTPS providers, meters streamed chat completions, counts cached tokens and reads Anthropic’s usage format as well as OpenAI’s. The code, source-available in September, has been open source under Apache-2.0 since 0.9.0. A long-running host, and a block action that refuses further model calls at the meter once a budget is crossed, are on the main branch (Unreleased: after 0.11.0). Release notes lists what each release changed, and What is not counted lists what the ledger still misses.

The larger change is what Hekma is for. In September the goal fitted in one sentence: run agents like services, with a supervisor, a ledger you did not ask them to fill in, and a ceiling that pauses them before the invoice does. Hekma is now growing into a control plane for agent workloads, and one of its rules turns that last clause round: as Policies land, a breach will signal loudly by default instead of stopping work, and pausing or stopping becomes your explicit choice.

What has not changed is where the meter sits. It is still on the wire, where the agent cannot argue with it.