- harnesses/hermes.py: Hermes adapter reading state.db (session_model_usage cumulative counters) for authoritative session totals plus the plugin's JSONL ledger for per-turn breakdowns; Hermes's disjoint CanonicalUsage buckets are folded into the tool's inclusive (Vibe-style) contract - integration/hermes/plugin: Hermes plugin (plugin.yaml + register(ctx)) wiring pre_llm_call (turn labels), post_api_request + post_auxiliary_call (per-call ledger, queue + drainer, no hook-path I/O), post_llm_call (cost line after every interactive CLI turn; silent for subagents/cron/one-shot) - integration/hermes/install.py: standalone idempotent installer (validates the home, copies the plugin + pricing.json, runs hermes plugins enable); also wired as agent-cost-estimator --integrate hermes / --rm-integrate hermes - pricing: plugin-local pricing.json first (stdlib-only reader), then the package table, then default rates - tests: 22 new (52 total) covering adapter, plugin, installer - docs: SPEC.md 1.1.0 (sections 5.2.1, 7.3), SKILL.md, wiki entity Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
5.2 KiB
name, version, description
| name | version | description |
|---|---|---|
| agent-cost-estimator | 0.1.0 | Estimate USD cost of AI agent sessions; run "agent-cost-estimator --skill" for usage. |
agent-cost-estimator
Report token usage and an estimated USD cost for an AI agent
session, read from the harness's local logs. Ships with the
vibe (Mistral Vibe) and hermes (Hermes Agent) harnesses;
other harnesses plug in as adapters.
Run agent-cost-estimator --skill at any time to re-read these
instructions. Everything below assumes the installed
agent-cost-estimator command; in-tree, use
python -m agent_cost_estimator from the project folder
instead.
Quick answers
agent-cost-estimator
-> mistral:model | session:$X | turn:$Y
(provider:model, whole session cost, latest turn cost; USD, 2 decimals)
agent-cost-estimator -s -> 2.1148 (bare session cost)
agent-cost-estimator -t -> 2.4979 (bare latest-turn cost)
agent-cost-estimator -d -> full report table
agent-cost-estimator --json -> one JSON object, all numbers
agent-cost-estimator --harness hermes
-> same outputs for a Hermes Agent session (state.db)
agent-cost-estimator --integrate mistral -> install Vibe hooks
agent-cost-estimator --integrate hermes -> install the Hermes plugin
The default line answers "what does this session cost and what
did the last turn cost". -s/-t print bare numbers for
scripting; -d shows the table with token counts, pricing
source, and caveats; --json is the full machine-readable
report (tokens, cost breakdown, per-turn list, pricing).
Use --integrate mistral to set up Vibe CLI hooks automatically
on any machine (hook script, configuration, bash allowlist).
Use --integrate hermes to install the Hermes Agent plugin: it
copies the plugin into <hermes-home>/plugins/, enables it, and
after a Hermes restart prints -- provider:model | session:$X | turn:$Y after every assistant turn, mirroring the Vibe hook.
--rm-integrate hermes removes it.
What to trust
- Session-wide token totals come from the harness's cumulative
counter (vibe:
projection-state.json; hermes: thesession_model_usagetable instate.db), which survives log rotation. - Call counts and per-turn breakdowns come from journal files
(vibe) or the plugin's usage ledger (hermes:
<home>/plugin-data/agent-cost-estimator/usage/*.jsonl), which the harness may outlive: they cover only what is on disk. The latest turn is always there, so-tis safe. For hermes, the ledger only exists once the plugin is installed; without it, per-turn reads are zero. - All costs are estimates at the configured rates, never billed figures. Tell the user that, and point them at their provider's console (Mistral: admin.mistral.ai/subscription) for authoritative spend.
Selecting what to measure
--harness NAME adapter to read (default: vibe; also:
hermes; list: --list-harnesses)
--session-id ID|PATH a specific session id or directory
--home PATH the harness's data root (default: harness-specific,
vibe: $VIBE_HOME or ~/.vibe;
hermes: $HERMES_HOME or ~/.hermes)
With no --session-id, the most recently active session is
picked (vibe: newest journal file; hermes: newest
last_activity_at in state.db). To inspect another session, pass
its id or path.
Pricing
Prices live in a JSON table, USD per million tokens, keyed by
model with a default fallback. Lookup order: the session's
model name, its alias, then default.
--pricing FILE use a custom pricing table
--model KEY force the lookup key
--input-price P --cached-input-price P --output-price P
override for one run
--update-pricing [--dry-run] persist the overrides
(requires --pricing or the bundled file)
To store real rates once: run
agent-cost-estimator --model <model> --input-price P --cached-input-price P --output-price P --update-pricing.
Later runs then price correctly without flags.
Reading output correctly
turn:/-tis the latest turn, priced at the same rates. While a turn is still running, it counts only what has been flushed to the journal so far (an under-estimate).- Cached input is clamped to input tokens; fresh input is
input - cached. - With
--update-pricing, the report still prints normally after the stderr confirmation line; parse stdout only.
Extending for other harnesses
A harness adapter subclasses
agent_cost_estimator.harnesses.base.HarnessAdapter and
implements resolve_session_dir, read_meta, and
collect_usage, then registers through the
agent_cost_estimator.harnesses entry-point group:
[project.entry-points."agent_cost_estimator.harnesses"]
mytool = "my_package.adapters:MyToolHarness"
Library use: from agent_cost_estimator import available_harnesses, get_harness, compute_cost, load_pricing.
Errors
Exit code 1 with error: ... on stderr: unknown session, no
sessions under the home, unknown --harness, or a missing or
invalid pricing file. --skill and --list-harnesses never
touch session data and always work.