Upgrade to Agentium 4.5

Agentium 4.5 keeps cost accounting in @agentium/core. Set cost: true and read result.costs, or keep an existing shared CostTracker. Use asynchronous tracker queries for history. This release changes the accounting read path and token meanings described below. Install matching versions of the Agentium packages your application uses:

npm install @agentium/core@4.5.0

Read the v4 migration first if you are upgrading from 3.x.

Change the cost read path

Earlier releases often used tracker.getSummary().totalCost as a final bill. That estimate could treat a missing model price as zero. It could also add reasoning tokens to output tokens that already included them. Enable accounting once and read result.costs after each run. Agentium handles the writes needed for the run snapshot.

import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-6.1-sol"),
  cost: true,
});

const result = await agent.run("Explain the result.");
console.log(result.costs);
await agent.close();

Set OPENAI_API_KEY before running this example. It makes a paid provider request. For an existing shared tracker, keep costTracker: tracker; the run result exposes the same cost snapshot. Use tracker.queryCosts() for history queries across runs or sessions.

Field	Meaning
`knownSubtotal`	Exact decimal amount for priced charges
`total`	Exact decimal amount when complete; otherwise `null`
`pricingStatus`	`complete`, `partial`, or `unpriced`
`unpricedCount`	Number of charges that lack enough usage, context, or price data
`asOf`	Time of the query snapshot
`finality`	Whether the selected accounting records are final or provisional

Do not replace null with zero. A known subtotal is not the final total. Background work can add later observations; read a new snapshot after the work and accounting writes have settled.

Correct the token meaning

Canonical input contains ordinary input, cache reads, and cache writes. Canonical output includes reasoning. Providers report these categories differently, so normalization runs before price calculation.

Example	Correct result
19 input; 16 output, including 9 reasoning	35 tokens; one output charge
15,000 inclusive input; 12,000 cache reads; 2,000 cache writes	1,000 ordinary input; price all three input categories separately
Anthropic ordinary input 1,000; reads 12,000; writes 2,000	15,000 canonical input
Cache writes split between 5 minutes and 1 hour	Price the two buckets; do not also charge their total

Reasoning and modality details are not automatically extra billable tokens. A text/audio split or cache split must form a valid partition before separate rates apply.

Replace unscoped price assumptions

CostTracker({ pricing }) configures only the legacy synchronous projection. It does not override canonical Agent accounting. Move those overrides to CostTracker({ catalog }). Use a versioned catalog for canonical accounting. A rule identifies the billing provider, model or resource, API, meter, unit, currency, and applicable context. Custom deployments and gateways need their own explicit mapping.

Supply separate rates for ordinary input, cache read, cache write, and output.
Use the actual returned service tier. A request for Fast can use a different tier.
Treat Pro mode as reported model work. Do not apply a universal Pro multiplier.
Apply context bands, cache duration, regional rates, and account terms only where the provider defines them.
Retain the rule snapshot with the charge. A catalog update does not rewrite historical assessments.

See cost accounting for a complete custom tariff and the charges workflow.

Review storage and budgets

The default store is local memory. Choose an accounting store when costs must survive a restart. The general session StorageDriver does not supply the transaction contract required for shared budget reservations. Threshold budgets check recorded spend. Accepted requests can finish after the threshold is crossed. Reservation budgets need a conservative bound and an atomic accounting backend. Neither mode guarantees the provider’s final invoice. Zero is a real limit. Warning mode continues execution. Unknown cost remains visible and follows the configured unknown-cost policy. Read budget controls before changing a production policy.

Update event consumers

Use canonical usage and assessment events when you need call evidence and pricing completeness. Deduplicate stable IDs and use the selected assessment revision. The legacy cost.tracked event remains a replacement run total for complete known costs. Do not sum each replacement or add it to canonical attempt charges. Parent and child summaries can describe the same underlying work.

Keep legacy methods bounded

track() remains a synchronous compatibility method. getEntries() and getSummary() can read that local legacy projection. Once a tracker receives canonical accounting records, those two read methods throw IncompleteCostError. Use queryUsage() and queryCosts() for Agent accounting. This prevents a legacy projection from displaying zero while the ledger contains spend. Persisted summaries from earlier releases do not contain the evidence needed to reconstruct missing attempts, cache writes, service tiers, or rule snapshots. Keep them labelled as historical estimates. Do not invent those fields during migration.

Reference

Package APIs

Type guides

Upgrades

Architecture and tooling

Upgrade to Agentium 4.5

Change the cost read path

Correct the token meaning

Replace unscoped price assumptions

Review storage and budgets

Update event consumers

Keep legacy methods bounded

​Change the cost read path

​Correct the token meaning

​Replace unscoped price assumptions

​Review storage and budgets

​Update event consumers

​Keep legacy methods bounded

Change the cost read path

Correct the token meaning

Replace unscoped price assumptions

Review storage and budgets

Update event consumers

Keep legacy methods bounded