agent-plugin-usage / Exports / UsagePlugin

Class: UsagePlugin

Tracks token usage, request counts, and costs across agent executions.

Supports memory, file, remote, and silent storage strategies. When trackCosts is enabled, per-model cost rates are applied automatically. Periodic aggregation can be enabled via aggregateStats.

Lifecycle hooks used: AbstractPlugin.onModuleEvent | onModuleEvent

See

IUsageStorage - storage backend contract
IUsagePluginOptions - configuration options

Example

const plugin = new UsagePlugin({
  strategy: 'memory',
  trackCosts: true,
  costRates: { 'gpt-4': { input: 0.03, output: 0.06 } },
});
await plugin.recordUsage({ provider: 'openai', model: 'gpt-4', ... });

Hierarchy

AbstractPlugin<IUsagePluginOptions, IUsagePluginStats>
↳ UsagePlugin

Constructors

constructor

Properties

Methods

Constructors

constructor

• new UsagePlugin(options): UsagePlugin

Parameters

Name	Type
`options`	`IUsagePluginOptions`

Returns

UsagePlugin

Overrides

AbstractPlugin<IUsagePluginOptions, IUsagePluginStats>.constructor

Defined in

agent-plugin-usage/src/usage-plugin.ts:73

Properties

enabled

• enabled: boolean

Inherited from

AbstractPlugin.enabled

Defined in

agent-core/dist/node/index.d.ts:1049

priority

• priority: number

Inherited from

AbstractPlugin.priority

Defined in

agent-core/dist/node/index.d.ts:1051

name

• name: string = 'UsagePlugin'

Overrides

AbstractPlugin.name

Defined in

agent-plugin-usage/src/usage-plugin.ts:65

version

• version: string = '1.0.0'

Overrides

AbstractPlugin.version

Defined in

agent-plugin-usage/src/usage-plugin.ts:66

Methods

initialize

▸ initialize(options?): Promise<void>

Parameters

Name	Type
`options?`	`IUsagePluginOptions`

Returns

Promise<void>

Inherited from

AbstractPlugin.initialize

Defined in

agent-core/dist/node/index.d.ts:1063

subscribeToModuleEvents

▸ subscribeToModuleEvents(eventEmitter): Promise<void>

Parameters

Name	Type
`eventEmitter`	`IEventEmitterPlugin`

Returns

Promise<void>

Inherited from

AbstractPlugin.subscribeToModuleEvents

Defined in

agent-core/dist/node/index.d.ts:1064

unsubscribeFromModuleEvents

▸ unsubscribeFromModuleEvents(eventEmitter): Promise<void>

Parameters

Name	Type
`eventEmitter`	`IEventEmitterPlugin`

Returns

Promise<void>

Inherited from

AbstractPlugin.unsubscribeFromModuleEvents

Defined in

agent-core/dist/node/index.d.ts:1065

dispose

▸ dispose(): Promise<void>

Returns

Promise<void>

Inherited from

AbstractPlugin.dispose

Defined in

agent-core/dist/node/index.d.ts:1066

enable

▸ enable(): void

Returns

void

Inherited from

AbstractPlugin.enable

Defined in

agent-core/dist/node/index.d.ts:1067

disable

▸ disable(): void

Returns

void

Inherited from

AbstractPlugin.disable

Defined in

agent-core/dist/node/index.d.ts:1068

isEnabled

▸ isEnabled(): boolean

Returns

boolean

Inherited from

AbstractPlugin.isEnabled

Defined in

agent-core/dist/node/index.d.ts:1069

getConfig

▸ getConfig(): IPluginConfig

Returns

IPluginConfig

Inherited from

AbstractPlugin.getConfig

Defined in

agent-core/dist/node/index.d.ts:1070

updateConfig

▸ updateConfig(_config): void

Parameters

Name	Type
`_config`	`IPluginConfig`

Returns

void

Inherited from

AbstractPlugin.updateConfig

Defined in

agent-core/dist/node/index.d.ts:1071

getData

▸ getData(): IPluginData

Returns

IPluginData

Inherited from

AbstractPlugin.getData

Defined in

agent-core/dist/node/index.d.ts:1072

clearData

▸ clearData(): void

Returns

void

Inherited from

AbstractPlugin.clearData

Defined in

agent-core/dist/node/index.d.ts:1073

getStatus

▸ getStatus(): Object

Returns

Object

Name	Type
`name`	`string`
`version`	`string`
`enabled`	`boolean`
`initialized`	`boolean`
`category`	`PluginCategory`
`priority`	`number`
`subscribedEventsCount`	`number`
`hasEventEmitter`	`boolean`

Inherited from

AbstractPlugin.getStatus

Defined in

agent-core/dist/node/index.d.ts:1074

getStats

▸ getStats(): IUsagePluginStats

Returns

IUsagePluginStats

Inherited from

AbstractPlugin.getStats

Defined in

agent-core/dist/node/index.d.ts:1084

beforeRun

▸ beforeRun(input, options?): Promise<void>

Parameters

Name	Type
`input`	`string`
`options?`	`IRunOptions`

Returns

Promise<void>

Inherited from

AbstractPlugin.beforeRun

Defined in

agent-core/dist/node/index.d.ts:1087

afterRun

▸ afterRun(input, response, options?): Promise<void>

Parameters

Name	Type
`input`	`string`
`response`	`string`
`options?`	`IRunOptions`

Returns

Promise<void>

Inherited from

AbstractPlugin.afterRun

Defined in

agent-core/dist/node/index.d.ts:1088

beforeExecution

▸ beforeExecution(context): Promise<void>

Parameters

Name	Type
`context`	`IPluginExecutionContext`

Returns

Promise<void>

Inherited from

AbstractPlugin.beforeExecution

Defined in

agent-core/dist/node/index.d.ts:1089

afterExecution

▸ afterExecution(context, result): Promise<void>

Parameters

Name	Type
`context`	`IPluginExecutionContext`
`result`	`IPluginExecutionResult`

Returns

Promise<void>

Inherited from

AbstractPlugin.afterExecution

Defined in

agent-core/dist/node/index.d.ts:1090

beforeConversation

▸ beforeConversation(context): Promise<void>

Parameters

Name	Type
`context`	`IPluginExecutionContext`

Returns

Promise<void>

Inherited from

AbstractPlugin.beforeConversation

Defined in

agent-core/dist/node/index.d.ts:1091

afterConversation

▸ afterConversation(context, result): Promise<void>

Parameters

Name	Type
`context`	`IPluginExecutionContext`
`result`	`IPluginExecutionResult`

Returns

Promise<void>

Inherited from

AbstractPlugin.afterConversation

Defined in

agent-core/dist/node/index.d.ts:1092

beforeToolCall

▸ beforeToolCall(toolName, parameters): Promise<void>

Parameters

Name	Type
`toolName`	`string`
`parameters`	`TToolParameters`

Returns

Promise<void>

Inherited from

AbstractPlugin.beforeToolCall

Defined in

agent-core/dist/node/index.d.ts:1093

beforeToolExecution

▸ beforeToolExecution(context, toolData): Promise<void>

Parameters

Name	Type
`context`	`IPluginExecutionContext`
`toolData`	`IToolExecutionContext`

Returns

Promise<void>

Inherited from

AbstractPlugin.beforeToolExecution

Defined in

agent-core/dist/node/index.d.ts:1094

afterToolCall

▸ afterToolCall(toolName, parameters, result): Promise<void>

Parameters

Name	Type
`toolName`	`string`
`parameters`	`TToolParameters`
`result`	`IToolExecutionResult`

Returns

Promise<void>

Inherited from

AbstractPlugin.afterToolCall

Defined in

agent-core/dist/node/index.d.ts:1095

afterToolExecution

▸ afterToolExecution(context, toolResults): Promise<void>

Parameters

Name	Type
`context`	`IPluginExecutionContext`
`toolResults`	`IPluginExecutionResult`

Returns

Promise<void>

Inherited from

AbstractPlugin.afterToolExecution

Defined in

agent-core/dist/node/index.d.ts:1096

beforeProviderCall

▸ beforeProviderCall(messages): Promise<void>

Parameters

Name	Type
`messages`	`TUniversalMessage`[]

Returns

Promise<void>

Inherited from

AbstractPlugin.beforeProviderCall

Defined in

agent-core/dist/node/index.d.ts:1097

afterProviderCall

▸ afterProviderCall(messages, response): Promise<void>

Parameters

Name	Type
`messages`	`TUniversalMessage`[]
`response`	`TUniversalMessage`

Returns

Promise<void>

Inherited from

AbstractPlugin.afterProviderCall

Defined in

agent-core/dist/node/index.d.ts:1098

onStreamingChunk

▸ onStreamingChunk(chunk): Promise<void>

Parameters

Name	Type
`chunk`	`TUniversalMessage`

Returns

Promise<void>

Inherited from

AbstractPlugin.onStreamingChunk

Defined in

agent-core/dist/node/index.d.ts:1099

onError

▸ onError(error, context?): Promise<void>

Parameters

Name	Type
`error`	`Error`
`context?`	`IPluginErrorContext`

Returns

Promise<void>

Inherited from

AbstractPlugin.onError

Defined in

agent-core/dist/node/index.d.ts:1100

onMessageAdded

▸ onMessageAdded(message): Promise<void>

Parameters

Name	Type
`message`	`TUniversalMessage`

Returns

Promise<void>

Inherited from

AbstractPlugin.onMessageAdded

Defined in

agent-core/dist/node/index.d.ts:1101

onModuleEvent

▸ onModuleEvent(eventName, eventData): Promise<void>

Records usage statistics from module lifecycle events (completion and error events). Duration-bearing events are recorded with zero token counts as module events do not involve LLM calls.

Parameters

Name	Type
`eventName`	`TEventName`
`eventData`	`IEventEmitterEventData`

Returns

Promise<void>

Overrides

AbstractPlugin.onModuleEvent

Defined in

agent-plugin-usage/src/usage-plugin.ts:99

recordUsage

▸ recordUsage(usage): Promise<void>

Records a usage entry, calculating cost if cost tracking is enabled and a rate is configured for the model.

Parameters

Name	Type
`usage`	`Omit`<`IUsageStats`, `"timestamp"` \| `"cost"`>

Returns

Promise<void>

Throws

PluginError if the storage write fails

Defined in

agent-plugin-usage/src/usage-plugin.ts:152

getUsageStats

▸ getUsageStats(conversationId?, timeRange?): Promise<IUsageStats[]>

Retrieves usage entries, optionally filtered by conversation and time range.

Parameters

Name	Type
`conversationId?`	`string`
`timeRange?`	`Object`
`timeRange.start`	`Date`
`timeRange.end`	`Date`

Returns

Promise<IUsageStats[]>

Throws

PluginError if the storage read fails

Defined in

agent-plugin-usage/src/usage-plugin.ts:184

getAggregatedStats

▸ getAggregatedStats(timeRange?): Promise<IAggregatedUsageStats>

Returns aggregated totals (requests, tokens, cost, success rate) across all recorded usage entries within the optional time range.

Parameters

Name	Type
`timeRange?`	`Object`
`timeRange.start`	`Date`
`timeRange.end`	`Date`

Returns

Promise<IAggregatedUsageStats>

Throws

PluginError if the storage aggregation fails

Defined in

agent-plugin-usage/src/usage-plugin.ts:206

clearStats

▸ clearStats(): Promise<void>

Returns

Promise<void>

Defined in

agent-plugin-usage/src/usage-plugin.ts:219

flush

▸ flush(): Promise<void>

Returns

Promise<void>

Defined in

agent-plugin-usage/src/usage-plugin.ts:230

destroy

▸ destroy(): Promise<void>

Stops the aggregation timer and closes the underlying storage.

Returns

Promise<void>

Defined in

agent-plugin-usage/src/usage-plugin.ts:243

Class: UsagePlugin ​

Hierarchy ​

Table of contents ​

Constructors ​

Properties ​

Methods ​

Constructors ​

constructor ​

Parameters ​

Returns ​

Overrides ​

Defined in ​

Properties ​

enabled ​

Inherited from ​

Defined in ​

category ​

Inherited from ​

Defined in ​

priority ​

Inherited from ​

Defined in ​

name ​

Overrides ​

Defined in ​

version ​

Overrides ​

Defined in ​

Methods ​

initialize ​

Parameters ​

Returns ​

Inherited from ​

Defined in ​

subscribeToModuleEvents ​

Parameters ​

Returns ​

Inherited from ​

Defined in ​

unsubscribeFromModuleEvents ​

Parameters ​

Returns ​

Inherited from ​

Defined in ​

dispose ​

Returns ​

Inherited from ​

Defined in ​

Class: UsagePlugin

Hierarchy

Table of contents

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns

Overrides

Defined in

Properties

enabled

Inherited from

Defined in

category

Inherited from

Defined in

priority

Inherited from

Defined in

name

Overrides

Defined in

version

Overrides

Defined in

Methods

initialize

Parameters

Returns

Inherited from

Defined in

subscribeToModuleEvents

Parameters

Returns

Inherited from

Defined in

unsubscribeFromModuleEvents

Parameters

Returns

Inherited from

Defined in

dispose

Returns

Inherited from

Defined in