The three mechanisms (see the main README) know neither the agent, the harness
nor the task domain. Everything specific to those enters through a few small interfaces in the
standard-library-only package tokeneconomizer:
tokeneconomizer.traceis the one place a saved session log is read (load_trajectory,call_cwds,tool_usage,parse_catalog), with one module per agent's format. A new agent needs a reader here and nothing else.tokeneconomizer.ledgerandtokeneconomizer.pricingare the one definition of cost. Mechanisms record their per-task overhead (in the plugin, a session counts as one task); the plugin's session ledger and the experiments' aggregation read it back through the same modules, so recorded and reported cost cannot drift.tokeneconomizer.domain.DomainAdapteris the interface to the task domain: reading a session, the tools pruning protects or excludes, a trajectory's loop signals, the task text for the optional judge, and the micro-skill vocabulary. A new domain is a new adapter, with no change to a mechanism. The plugin's adapter istokeneconomizer.plugin.adapter.LiveAdapter; the benchmark adapters (SWE-Bench, Web-Bench, CredData, ReposVul) are inexperiments/te_bench/adapters/.tokeneconomizer.stage.Stageis the set of hooks a mechanism offers whoever runs it:before_task,build_tools,run_kwargsandafter_task.
Two callers run the stages, and the mechanisms import neither:
- The plugin (
tokeneconomizer.plugin) runs them inside a person's sessions through each agent's hooks:PrefixStageandToolingStageover each finished session, and the loop guard (loopguard.TurnGuard) one tool call at a time. What happens at each hook, and what was verified on each agent, is inPLUGIN.md. - The experiments (
experiments/te_bench) run them over benchmark task streams: theEconomizerfacade wires the three stages around one adapter, andte_bench.runner.AgentRunneris the interface to a task-execution harness (Docker, an agent CLI, a grader), withexperiments/te_harnessas the implementation the paper used. The benchmark-only controllers --SpiralStage, the streamedNudgeGuardand the Codex finalize policy -- live there too. Seeexperiments/README.md.
tests/test_plugin_package.py pins both boundaries: the mechanisms never import
tokeneconomizer.plugin, and nothing under tokeneconomizer/ imports experiments/.