costguard

CostGuard

A brake pedal for model spend.

Dashboards show what an agent already spent. CostGuard enforces a budget
while there is still time for it to matter.

What it does

• Metering. post_api_request records every API call from the
  provider's own usage block: exact input/output tokens, accumulated per
  session and per day, under <HERMES_HOME>/costguard/usage.json.
  Dollar figures are estimates computed only for models in the price
  table (built-in reference list prices, overridable in settings);
  unknown models are metered in tokens with cost honestly left unknown.
• Estimated fallback, labelled. Some OpenAI-compatible endpoints
  report no usage block when streaming. For those calls CostGuard falls
  back to Hermes' own request-size approximation (pre_api_request)
  plus a chars/4 output estimate, and the call is flagged
  estimated_calls in every total, never silently presented as exact,
  and never priced.
• Warning. pre_llm_call tells the agent when it crosses the
  warning ratio (default 80%) of any configured budget, and states
  plainly when a budget is already exhausted.
• The brake. pre_tool_call: once any configured budget is
  exceeded, tool calls are blocked with a budget message (CostGuard's
  own status tool stays available). Runaway spend in practice is tool
  loops, each iteration another API call, and the brake stops the loop.

One honest limit: the brake cannot cancel the reply already being
generated when a budget trips; it stops the work that reply tries to
do next. With no budget configured, CostGuard only meters and reports;
it never blocks.

Configuration

plugins:
  entries:
    costguard:
      settings:
        session_token_budget: 200000      # 0 or absent = off
        daily_token_budget: 1000000
        session_cost_budget_usd: 2.00
        daily_cost_budget_usd: 10.00
        warn_ratio: 0.8
        prices:                            # USD per 1M tokens, overrides
          my-model: { input: 1.0, output: 2.0 }

Inspect with /cost, the costguard_status tool, or
hermes costguard usage. Budget breaches are also appended to
<HERMES_HOME>/costguard/events.jsonl.

Disclosure

CostGuard observes API request/response metadata (token usage, model,
session id) and tool call names in sessions of profiles where it is
enabled. It stores only aggregate counters locally, makes no network
calls, and starts no processes. Metering errors never break the agent
loop. Declared capabilities in plugin.yaml match the registered hooks
and tool exactly.

Verification

• hermes plugins validate: passed, security scan safe.
• hermes plugins doctor: OK, 1 tool and 4 hooks registered under the
  real runtime contracts.
• Unit tests cover exact metering math, price lookup (exact, prefix,
  override, unknown), the estimated fallback, warning thresholds, and
  the brake (blocks over budget, allows under budget, exempts its own
  status tool, never blocks with no budget configured).
• Live session test: with a small session token budget configured
  against an endpoint that reports no streamed usage, the estimated
  metering accumulated across calls and the brake blocked further tool
  calls once the budget was exceeded.

README from the reviewed commit 967e2b7; it updates when the author re-pins.