Files
agent-cost-estimator/agent_cost_estimator/skill/SKILL.md
T
nvaldez 9cc95dc793 feat: add Hermes Agent support (harness adapter, plugin, installer)
- 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>
2026-10-25 16:57:40 +01:00

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: the session_model_usage table in state.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 -t is 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: / -t is 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.