Wrap your model call once, then hand the wrapped version to your agent.

from tokenops import tokenops_run
from tokenops.capabilities import wrap_complete
from tokenops.framework import Halt
from tokenops.providers import complete

GOVERNANCE = {"governance": {
    "budgets": [{"id": "run_llm_cap", "limit_micros": 2_000_000, "dimension": "trace"}],
    "policies": {"cost_budget": {"budget": "run_llm_cap"},
                 "pre_call_worst_case": {"budget": "run_llm_cap"}},
}}

with tokenops_run(config=GOVERNANCE, service="my-agent", intent="research",
                  provider="openai", model="gpt-4o") as bound:
    governed = wrap_complete(
        bound.governor, bound.controls, bound.attr,
        provider="openai", model="gpt-4o",
        dispatch=complete, service="my-agent",
    )
    try:
        agent.run(..., complete_fn=governed)   # <-- pass `governed`, not `complete`
    except Halt as stopped:
        print(f"run stopped: {stopped}")

Pass governed to your agent instead of complete; nothing else changes. wrap_complete checks the budget before each call and raises Halt when the run is out. With a control plane, replace config=GOVERNANCE with client=ControlPlaneClient.from_env() (from tokenops.repositories import ControlPlaneClient); the budget then lives in the plane and is shared across processes.

Three pieces share one artifact, the run, which is a Chronicle trace (trace_id):

flowchart LR
    subgraph PLANE["Control plane"]
        CFG[("governance config<br/>budgets · policies")]
        LEDGER[("ledger<br/>spend · in-flight · halt")]
    end

    subgraph AGENTS["Agent processes"]
        E["Entry agent<br/>tokenops_run"] -->|"traceparent"| D["Downstream agents<br/>tokenops_run"]
        E & D -->|"wrap_complete + governor hook"| G["Governor<br/>pre_call → detect → decide → apply"]
    end

    CFG -->|"GET /v1/governance/{agent} (ETag)"| G
    G -->|"precheck (reads)"| LEDGER
    G -->|"events:batch (spend, complete) · admit / halt (sync)"| LEDGER

See docs/architecture.md. Chronicle is accepted at REALM (Research on Agent Language Models), a workshop at EMNLP 2026.

There is no local ledger fallback. With a plane configured every process shares one budget; without one, pass config= and the ledger lives in the process.

Only src/tokenops/ is the installable package. Demos and benches stay under examples/.

src/tokenops/              # installable package
├── framework/             # in-process machinery: ledger, policies, pricing, governor (no network)
├── capabilities/          # tokenops_run, wrap_complete, the Chronicle hook
├── interfaces/            # instrument_app, HTTP error mapping
├── control/               # deprecated import shims (removed in 2.0)
├── repositories/          # the control-plane client and the background ledger writer
├── providers/             # OpenAI / Anthropic complete dispatch
└── config/                # packaged default governance
examples/                  # A2A agent stacks (being rewritten)
docs/                      # architecture, policies, ADRs, migration
tests/                     # unit, contract and end-to-end (real control plane)

• Onboarding: prerequisites, minimum integration, FAQ, current limits
• Migrating from 0.4
• Architecture - trace attribution - halt
• Policies: one page per policy - decisions
• Examples - comparison