[FEAT] Drain priority + task-type routing for multi-source billing (x-ref tokentelemetry#45)

[ddiall]

Context: tokentelemetry#45 uncovers provider billing nuances around drain-priority that affect enforcement:

Anthropic (3-tier, no spillover):

• Subscription limits → interactive claude, Cowork (separate, no spillover)
• Agent SDK credit ($20/mo Pro) → claude -p, SDK, GitHub Actions (drains first)
• Usage credits / API key → pay-as-you-go (drains after SDK credit)

OpenAI/Codex (2-tier, OAuth covers both):

• ChatGPT subscription OAuth → Codex CLI (interactive) + codex app-server (programmatic)

Gap in hermes-telemetry: Current budget model has single cost bucket → can't enforce per-bucket limits or route by task-type (interactive|programmatic).

Ask: Credit bucket model with drain_priority + task_type_routing so pre_tool_call gate can enforce per-bucket limits respecting drain order.

See tokentelemetry#45 comment for full details and possible collab opportunity there: VasiHemanth/tokentelemetry#45 (comment)
See also broader discussion on external power-cost config for local/subscription models: VasiHemanth/tokentelemetry#49

[nujovich]

Thanks for the detailed writeup, @ddiall — the Anthropic side is accurate. Since June 15 the subscription pool (interactive claude / Claude Code / Cowork) and the Agent SDK credit (claude -p, SDK, Actions — drains first, then usage credits at API rates) are genuinely separate with no spillover, so a single cost bucket can't represent that correctly. No argument on the premise.

What I want to scope before committing to a bucket model: hermes-telemetry runs in the request path of an agent that routes through OpenRouter, which is a single pay-as-you-go account — effectively one bucket. The multi-source drain model (subscription / SDK credit / usage credits) is native to first-party subscription-billed setups (Claude Code on Pro/Max, Codex on ChatGPT OAuth), which is exactly where passive, log-reading dashboards operate. In a Hermes deployment I don't yet see where multiple drainable buckets coexist.

So two questions:

• What provider/auth config are you running where Hermes drains more than one bucket — e.g. Hermes authenticated against a Claude subscription rather than an OpenRouter key? A concrete repro would help a lot.
• Is the task_type split (interactive|programmatic) the part you care about most? That one maps cleanly onto Hermes today (interactive session vs cron/headless) even with a single billing bucket, and could be a smaller first step.

Where I do think this lands well is enforcement. A passive dashboard can show you drained the $20 SDK credit; it can't stop the next cron from spilling into usage credits. If we model buckets with drain_priority, the pre_tool_call gate can enforce per-bucket soft/hard limits respecting drain order — which complements the observability side rather than duplicating it.

Happy to sketch a budget.yaml schema (buckets + drain_priority + task_type_routing) once we pin down the first real multi-bucket scenario. Cross-linking tokentelemetry#45 for context.

[ddiall]

Hi Nadia — I cannot give you a detailed repro at the moment, but I do have multiple API key providers and a couple of subscriptions... My goal is to optimise resource/quota utilisation and keep costs under control while operating a fleet of agents 24/7 via Kanban orchestration & Cron automation to receive work from the outside world (e.g. GitHub issues/PRs and other inboxes). I'm busy trying to put this use case together and prototype it over the next few weeks.

[ddiall]

Re: task type, it currently boils down to /claude-code skill that caters for two operating modes:

• Mode 1: Print Mode (-p) — Non-Interactive (preferred for most tasks)
• Mode 2: Interactive PTY via tmux — Multi-Turn Sessions (e.g. debugging work)

One hypothesis I want to test relative to Anthropic's post June 15th policy is to use Mode 2 to continue working even if SDK credits for claude -p are exhausted and I have no ANTHROPIC_API_KEY (or simply $0 balance).

[nujovich]

Hi Nadia — I cannot give you a detailed repro at the moment, but I do have multiple API key providers and a couple of subscriptions... My goal is to optimise resource/quota utilisation and keep costs under control while operating a fleet of agents 24/7 via Kanban orchestration & Cron automation to receive work from the outside world (e.g. GitHub issues/PRs and other inboxes). I'm busy trying to put this use case together and prototype it over the next few weeks.

This is exactly the use case I wanted to pin down — thanks. A 24/7 fleet across multiple API-key providers + subscriptions, orchestrated by Kanban/Cron, is a genuine multi-bucket setup, not the single-OpenRouter-bucket case I'd been picturing. And the Mode 1 / Mode 2 mapping is the key insight: claude -p drains the Agent SDK credit, interactive PTY drains the subscription pool, and since those don't spill over, switching modes is effectively manual drain-routing. Using Mode 2 to keep working once the SDK credit is exhausted (no API key / $0 balance) is a neat exploit of the no-spillover rule.

A few things to get right before building:

1. Where the bucket state is observable — and it depends on topology. hermes-telemetry observes Hermes's request path (post_api_request): it sees provider/model/tokens, but not which credit tier a call drained. Anthropic doesn't expose per-bucket balances over the API either, so "SDK credit exhausted" isn't directly queryable. Importantly, the answer splits in two:

• Case A — Hermes-native calls (Hermes authenticated directly against a provider): post_api_request does see provider/model/tokens, you infer the bucket from task_type, and exhaustion arrives as an HTTP error. Current hooks are enough here.
• Case B — your Claude Code fleet: the workers are claude -p / PTY subprocesses that make their own calls to Anthropic. Those don't pass through Hermes's API client, so post_api_request sees nothing — not even tokens. For per-worker accounting the only path is ingesting the workers' session logs (~/.claude/), and the exhaustion signal isn't a 429 my HTTP client sees — it's the -p exit code / stderr.

So a minimal first step on the current hooks delivers Case A, but covering the fleet means adding a log parser — which is squarely tokentelemetry's territory. That's either a concrete reason to reuse/collaborate on their parser, or scope I'd rather name up front than drift into. Which topology are you running — do you expect hermes-telemetry to track the workers' spend (needs a log parser) or Hermes's own spend (hooks suffice)? That single answer decides whether this is a hooks feature or a parser feature.

One thing your analysis nails: a reactive failover is consistent with the current hard-gate, which already blocks at the next boundary rather than mid-call. So this doesn't need a new enforcement primitive — just a new signal ("bucket X exhausted") feeding the gate you already have. Caveat on that signal: a 429 is semantically rate-limiting, not credit exhaustion. If you trigger failover on a raw 429 you'll flip to Mode 2 on a transient limit that just needed a retry. Post-June-15 the exhaustion case surfaces as a specific billing/quota error, not a generic 429 — the trigger has to tell "rate-limited → retry" apart from "credit exhausted → failover."

2. Separation of concerns. Flipping a worker from -p to a tmux PTY is an orchestration decision (the /claude-code skill / your Kanban layer). I'd keep hermes-telemetry's job to track per bucket and emit the breach signal at the boundary, and let the orchestrator act on it. Does that boundary work, or were you picturing the plugin doing the routing itself?

On the model: I wouldn't hardcode Anthropic's three tiers. Closer to what you need is a generalized {provider × auth-type} → bucket map with arbitrary drain_priority, so your mix of API-key providers + subscriptions all fits. task_type (interactive|programmatic) becomes the per-call routing key into that map.

Minimal first step (Case A, no parser dependency): task_type tagging per call + per-bucket cost tracking with drain_priority ordering in budget.yaml, surfaced in /budget. Observable today; the failover layer builds on top once we settle the signal question above.

What's the provider mix you'd want modeled first? That'll tell me whether to start with the Anthropic subscription+SDK pair or go straight for a broader multi-provider table.

[ddiall]

So a minimal first step on the current hooks delivers Case A, but covering the fleet means adding a log parser — which is squarely tokentelemetry's territory. That's either a concrete reason to reuse/collaborate on their parser, or scope I'd rather name up front than drift into.

You hit the nail right on the head... I intuitively knew there had to be an overlap between the two, but couldn't "put my finger on it" until I read your reply. Quite sure I'll be running both and it'd be good if they play nice with each other where useful/necessary (cf. tokentelemetry#74).

Which topology are you running — do you expect hermes-telemetry to track the workers' spend (needs a log parser) or Hermes's own spend (hooks suffice)? That single answer decides whether this is a hooks feature or a parser feature.

The challenge here is tracking workers that, despite being orchestrated via Kanban feature, run in a harness that Hermes cannot observe directly* because vendors do not expose API. If this scenario aligns with your vision & roadmap, then why not? Otherwise, I can live with a "split brain" in terms of telemetry. My implementation is still in progress, so cannot bring you battle-tested scenarios just yet — I'm simply imagining the pain point.

(*) One possible workaround could be for Hermes to interact with the TUI of the target worker, e.g. start claude then /usage and scrape the screen... However I suspect this might be kinda brittle, dunno!

I'd keep hermes-telemetry's job to track per bucket and emit the breach signal at the boundary, and let the orchestrator act on it. Does that boundary work, or were you picturing the plugin doing the routing itself?

I haven't thought things through that far TBH, but agree with your principle for separation of concerns.

I wouldn't hardcode Anthropic's three tiers. Closer to what you need is a generalized {provider × auth-type} → bucket map with arbitrary drain_priority, so your mix of API-key providers + subscriptions all fits. task_type (interactive|programmatic) becomes the per-call routing key into that map.

If it helps, I wasn't planning on mixing monthly/annual subscriptions with pay-as-you-go API keys from the same vendor, just to avoid complications in my own head. I'll consolidate on a handful of subscription (5 max) and use Nous/OpenRouter for topping up API credits for what's necessary even if those are models from the same providers I have subs with — see below.

What's the provider mix you'd want modeled first? That'll tell me whether to start with the Anthropic subscription+SDK pair or go straight for a broader multi-provider table.

This is what I have, see what's easier and more practical on your end:

• Subscriptions — Codex, Claude Code, OpenCode Go; also considering Command Code (great offers, plus taste ;-) and Nous Research (free tier** at the moment).
• API keys — DeepSeek (primary) plus OpenRouter (fallback + model variety); the rest have no more funds: Google (has a free tier), Anthropic and OpenAI.
• Local LLM — planning hybrid model routing (unfortunately my GPU stopped working)

(**) Nemotron 3 Ultra is a BEAST — it's a 550B MoE frontier-intelligence open model built for long-running agents, available for FREE via Nous/OpenRouter until June 18th (see announcement).

[nujovich]

Perfect — running both and having them play nice is exactly the right framing, and #74 is a good anchor for where the seam sits.

Scope for v1 — naming the split-brain up front. I'll draw the line exactly where observability does:

• In scope (Case A, hooks-only): the API-key PAYG path that actually flows through Hermes — DeepSeek as primary, OpenRouter as fallback/top-up. post_api_request already sees provider/model/tokens here, so per-bucket tracking with drain_priority is buildable on the current hooks, no parser.
• Out of scope (Case B): the subscription harnesses — Codex, Claude Code, OpenCode Go, Command Code. Those run in harnesses Hermes can't observe, so accounting them needs log ingestion, which is squarely tokentelemetry's lane. I'd rather hermes-telemetry coordinate on that seam than grow a parallel parser — the natural interop point with fix(dashboard): honor explicit UTC viewer timezone without zoneinfo #74. Split-brain accepted, and named on purpose.

On the TUI-scraping workaround (claude → /usage → screen-scrape): I'd pass on it. You already sense it's brittle and I agree — it couples us to each worker's UI and breaks on any layout change. Better to let the orchestration layer own that visibility.

Your consolidation decision simplifies the model a lot, by the way: since you're not mixing a vendor's subscription with its own PAYG keys, each vendor collapses to a single bucket type. That kills the messy intra-vendor spillover case — {provider × auth-type} → bucket stays a flat map, and task_type is just the routing key into it.

So the concrete v1 shape: task_type tagging per call + per-bucket cost tracking with drain_priority ordering in budget.yaml, surfaced in /budget — scoped to the Hermes-observable PAYG path. The breach-signal-into-the-existing-gate piece layers on top once we settle the trigger question (the post-June-15 billing/quota error, not a raw 429).

Quick follow-up on the NVIDIA side, since you flagged Nemotron 3 Ultra — tracked in #12: the free promo (nvidia/nemotron-3-ultra:free on Nous Portal, June 4–18) is already handled — the :free tag resolves to $0 through the existing zero-cost fallback, so no pricing work needed for the promo window. Paid NIM-direct pricing isn't in yet; that's what #12's manual seed entries are for. I'm not chasing a live NIM pricing API for it, though: NIM bills against credits/account tier rather than a uniform public per-token list, so there's nothing clean to auto-sync against — the seed table is the durable answer, not a stopgap (closing out the Phase 2 idea in #12 on that basis).

No timeline promise from me yet — your setup's still in progress, and I'd rather shape this against a real running fleet than build the routing on spec. Once you've got something live (even partial), drop the actual session/error shapes here and we'll tune from there.

[nujovich]

@ddiall , I got v1 clear enough now for you to confirm and start building. Keeping it short.

The piece that'll actually help you: a free→paid alert.
Since cost is resolved per call (:free → $0, paid model → real price), the plugin can warn you the moment a run jumps from free to paid models: "⚠️ heads up, this call is now hitting a paid model (<model>, ~$X)". It's exactly the nasty autonomous-cron case: you were running free on owl-alpha / nemotron :free, the fallback bumps you to a paid one, and you start spending with nobody watching. With the Nemotron free window closing on the 18th, this gets very concrete in the next few days. Ships as a notification in v1; an opt-in "free-only, block if it goes paid" mode is a natural follow-up.

task_type — where it comes from (since you were after this):
I derive it from platform, which comes in on_session_start and whose enum includes "cron". So: cron → programmatic, cli → interactive, gateway (telegram/discord) tagged as themselves. Real, served by the hook, nothing invented. The job_id is recoverable too by parsing the session_id (cron_{job_id}_{ts}). It's a grouping tag for /stats and /budget, not a gate input.

Concrete v1 (confirm me):

• independent per-bucket cost tracking in budget.yaml, buckets discovered straight from the post_api_request stream (everything that flows through Hermes's gateway; harnesses like Codex CLI stay out because they never fire the hook → that's tokentelemetry's lane via fix(dashboard): honor explicit UTC viewer timezone without zoneinfo #74).
• task_type derived from platform.
• free→paid alert.
• all surfaced in /budget.
• enforcement = block tools + pause cron on breach (it doesn't kill the in-flight call, that's not possible). The fine trigger (real billing error vs. transient 429) I'll leave to tune against your fleet once it's running.

If that works for you, I'll start. And once you've got something live, drop the real session/error shapes here and we'll tune the trigger.