Package net.thevpc.naru.api.agent

Interface NaruSessionUsageListener

public interface NaruSessionUsageListener

Notified when a provider reports something the core has no opinion about: how many tokens a call cost, and what the provider's own rate limits currently are.

This is a seam, not a feature. The core cannot decide what a token is worth or whether a session is over budget — that is a policy choice, and it lives in an extension (naru-budget is the one that ships today). What the core owes an extension is that the raw numbers are announced exactly once per call, without every observer having to poll or wrap the provider itself.

A listener that throws is ignored: metering must never be able to fail a model call. Listeners are held per session and are not persisted.

Method Summary

Modifier and Type	Method	Description
void	onModelCall(NaruModelKey model, long promptTokens, long completionTokens, long cacheWriteTokens, long cacheReadTokens, NDuration duration)	A model call returned.
void	onProviderRateLimits(NaruProviderRateLimitInfo info)	A provider volunteered its current rate-limit state.

Method Details

onModelCall

void onModelCall(NaruModelKey model,
 long promptTokens,
 long completionTokens,
 long cacheWriteTokens,
 long cacheReadTokens,
 NDuration duration)

A model call returned. Token counts are whatever the provider reported, which for a provider that does not do cache accounting is -1 rather than 0; consumers decide how to treat an unreported count.

Parameters:

duration - wall-clock time of the call, for latency reporting

onProviderRateLimits

void onProviderRateLimits(NaruProviderRateLimitInfo info)

A provider volunteered its current rate-limit state. Providers that do not send this simply never trigger the callback.