Files
nvaldez 48e9242f8f feat: token line gains +N per-turn increments; whole-number token format
display.format_token_count now rounds half-up to whole numbers with
tier rollover (999999 -> "1M", never "1000k"; 275860 -> "276k").
display.format_token_line renders '-- I:<s>+<t> O:<s>+<t> C:<s>+<t>':
the +N suffixes come from new last_turn token fields in the report
(CLI --json raw counts + token_display last_turn_* keys; Hermes
plugin passes its in-memory turn bucket), render +0 on zero
increments, and fail soft when absent - every display path (CLI,
--display-lines, GUI, Vibe hooks, Hermes plugin) changes together
per the display-parity rule. Docs and tests updated; 125 pass.
MINOR bump to 0.8.0.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-10 21:06:52 +01:00

4.0 KiB

agent-cost-estimator

Report token usage and estimated USD cost of an AI agent session, parsed from the harness's local logs. Ships with a Mistral Vibe adapter; other AI harnesses plug in through the adapter interface.

The result is a local estimate priced from pricing.json. The authoritative monthly usage is your provider's console (for Mistral: admin.mistral.ai/subscription).

Install

pip install .        # from this directory
# or run in place:
python -m agent_cost_estimator --help

Usage

agent-cost-estimator                        # cost line + token line (see below)
agent-cost-estimator -d                     # the full report table
agent-cost-estimator -s                     # session cost only, e.g. 2.1148
agent-cost-estimator -t                     # latest turn cost only
agent-cost-estimator -d --turns             # table plus per-turn breakdown
agent-cost-estimator --session-id 5732da2a  # a specific session id or path
agent-cost-estimator --json                 # machine-readable output
agent-cost-estimator --display-lines        # the hook/relay display format (same as default)
agent-cost-estimator --list-harnesses       # available adapters
agent-cost-estimator --integrate            # install Vibe hooks automatically

With no output flag the tool prints two lines: the cost line (provider:model, session and latest turn cost) and the token counts. Each token field is <session total>+<latest turn> at whole numbers with k/M/B/T suffixes (+0 when the turn added nothing):

mistral:mistral-medium | session:$3.40 | turn:$0.92
-- I:276k+1k O:2k+900 C:250k+25k

-d/--details prints the full table including formatted token counts; -s/--session and -t/--turn print one bare number each, for scripting.

Use --integrate to automatically set up Vibe CLI hooks:

agent-cost-estimator --integrate

This installs the hook script and configuration, and adds agent-cost-estimator to Vibe's bash allowlist. The turn cost is the most recent turn in the journal window.

Prices come from the bundled agent_cost_estimator/pricing.json, keyed by model (with a default fallback). Bring your own table:

agent-cost-estimator --pricing my-prices.json

Or persist overrides into the pricing table (the built-in one, or the file passed with --pricing):

agent-cost-estimator --model zai-glm-5-3 \
    --input-price 1.2 --cached-input-price 0.12 --output-price 6.0 \
    --update-pricing          # add --dry-run to preview

pricing.json format

{
  "currency": "USD",
  "models": {
    "default":     {"input_price": 1.5, "cached_input_price": 0.15, "output_price": 7.5},
    "zai-glm-5-3": {"input_price": 1.5, "cached_input_price": 0.15, "output_price": 7.5}
  }
}

Prices are USD per million tokens. Lookup order: session's model name, then its alias, then default. On the command line, --input-price, --cached-input-price, and --output-price override the table for that run.

Adding a harness

A harness adapter is a subclass of agent_cost_estimator.harnesses.base.HarnessAdapter implementing three read-only methods:

  • resolve_session_dir(session_arg, home) - find the session directory (or the most recently active one when the argument is None)
  • read_meta(session_dir) - return a SessionMeta (title, model_name, alias)
  • collect_usage(session_dir) - return a SessionUsage (input/cached/output tokens, call count, per-turn list)

Set name, home_env_var, and home_dir_name so --home and the session lookup have a sane default root. Register the adapter either by adding it to BUILTIN_HARNESSES (in-tree) or by exposing it through the agent_cost_estimator.harnesses entry-point group from your own package:

[project.entry-points."agent_cost_estimator.harnesses"]
mytool = "my_package.adapters:MyToolHarness"

Built-ins always win a name clash; a broken plugin is skipped with a warning.

Development

python -m pytest tests/

Standard library only; no runtime dependencies.