@modelprofile.com/flexharness-agent 8.3.0 → 8.4.0

package/dist_ts_agent/index.d.ts

@@ -4,9 +4,11 @@ export { buildModelMessages } from './smartagent.context.js';
 export { filterModelVisibleAgentEvents, getAgentGenerationTransactions, getOpenAgentGenerationTransactions, getUncertainToolExecutionIntents, isTransactionalGeneration, } from './smartagent.transactions.js';
 export { createAgentEvent, createAgentEventId, modelMessagesToAgentEvents, } from './smartagent.events.js';
 export { ToolRegistry } from './smartagent.classes.toolregistry.js';
+export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
+export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
 export { AgentGenerationLeaseCleanupError, ContextOverflowError, } from './smartagent.interfaces.js';
 export { AgentEventStoreConflictError, InMemoryAgentEventStore, isAgentEventStoreV2, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, } from './smartagent.persistence.js';
-export type { IAgentCacheOptions, IAgentContextOverflowInvocationOptions, IAgentContextBuildOptions, IAgentContextCompactionOptions, IAgentCompactOptions, IAgentEventRetentionOptions, IAgentBeginGenerationOptions, IAgentGenerateOptions, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentGenerationPreparationContext, IAgentRunOptions, IAgentRunResult, IAgentSession, IAgentSessionAbortOptions, IAgentSessionChange, IAgentSessionOptions, IAgentScheduleGenerateOptions, IAgentToolCallRecord, IAgentToolCallStartEvent, IAgentToolCallUpdateEvent, ProviderOptions, TAgentCacheRetention, TAgentCacheSetting, TAgentPrompt, TAgentContextBuilder, TAgentContextCompactor, TAgentGenerationPrepare, TAgentSessionChangeListener, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from './smartagent.interfaces.js';
+export type { IAgentCacheOptions, IAgentContextOverflowInvocationOptions, IAgentContextBuildOptions, IAgentContextCompactionOptions, IAgentCompactOptions, IAgentEventRetentionOptions, IAgentBeginGenerationOptions, IAgentGenerateOptions, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentGenerationPreparationContext, IAgentRunOptions, IAgentRunResult, IAgentSession, IAgentSessionAbortOptions, IAgentSessionChange, IAgentSessionOptions, IAgentScheduleGenerateOptions, IAgentToolCallRecord, IAgentToolCallStartEvent, IAgentToolCallUpdateEvent, IAgentUsage, ProviderOptions, TAgentCacheRetention, TAgentCacheSetting, TAgentPrompt, TAgentContextBuilder, TAgentContextCompactor, TAgentGenerationPrepare, TAgentModelCallUnreportedReason, TAgentModelCallUsage, TAgentModelCallUsageEvent, TAgentModelCallUsageReporter, TAgentSessionChangeListener, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from './smartagent.interfaces.js';
 export type { IAgentEventArchive, IAgentEventArchiveV2, IAgentEventSnapshot, IAgentEventSnapshotV2, IAgentEventStore, IAgentEventStoreV2, TAgentEventArchive, TAgentEventSnapshot, TAgentEventStore, } from './smartagent.persistence.js';
 export type { IAgentEventBase, IAgentRuntimeEventPayload, IArchivedAgentGenerationTransaction, IAssistantMessageEvent, IContextCompactionEvent, IGenerationBegunEvent, IGenerationExecutionCompletedEvent, IGenerationExecutionStartedEvent, IGenerationOutcomeEvent, IModelMessageEvent, IModelMessagesToEventsOptions, IModelMessageEventIdentityCoordinates, IRuntimeEvent, ISystemMessageEvent, IToolCallEvent, IToolExecutionIntentEvent, IToolExecutionReconciliationEvent, IToolResultEvent, IUserMessageEvent, TAgentAssistantMessage, TAgentConversationEvent, TAgentControlEvent, TAgentEvent, TAgentEventInput, TAgentSystemMessage, TAgentGenerationOutcome, TAgentToolCallPart, TAgentToolMessage, TAgentToolResultOutput, TAgentToolResultPart, TAgentUserMessage, TModelMessageEmittedEventKind, TModelMessageEventIdentityFactory, TToolExecutionReconciliation, } from './smartagent.events.js';
 export type { IAgentGenerationTransaction, TAgentGenerationTransactionState, } from './smartagent.transactions.js';

package/dist_ts_agent/index.js

@@ -4,6 +4,7 @@ export { buildModelMessages } from './smartagent.context.js';
 export { filterModelVisibleAgentEvents, getAgentGenerationTransactions, getOpenAgentGenerationTransactions, getUncertainToolExecutionIntents, isTransactionalGeneration, } from './smartagent.transactions.js';
 export { createAgentEvent, createAgentEventId, modelMessagesToAgentEvents, } from './smartagent.events.js';
 export { ToolRegistry } from './smartagent.classes.toolregistry.js';
+export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
 export { AgentGenerationLeaseCleanupError, ContextOverflowError, } from './smartagent.interfaces.js';
 export { AgentEventStoreConflictError, InMemoryAgentEventStore, isAgentEventStoreV2, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, } from './smartagent.persistence.js';
 export * from './tool.contracts.js';
@@ -12,4 +13,4 @@ export * from './tool.adapter.js';
 export { tool, jsonSchema, stepCountIs } from 'ai';
 export { z } from 'zod';
 export { FileAgentEventStore } from './persistence.file.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDekQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQy9ELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzdELE9BQU8sRUFDTCw2QkFBNkIsRUFDN0IsOEJBQThCLEVBQzlCLGtDQUFrQyxFQUNsQyxnQ0FBZ0MsRUFDaEMseUJBQXlCLEdBQzFCLE1BQU0sOEJBQThCLENBQUM7QUFDdEMsT0FBTyxFQUNMLGdCQUFnQixFQUNoQixrQkFBa0IsRUFDbEIsMEJBQTBCLEdBQzNCLE1BQU0sd0JBQXdCLENBQUM7QUFDaEMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3BFLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEdBQ3JCLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUNMLDRCQUE0QixFQUM1Qix1QkFBdUIsRUFDdkIsbUJBQW1CLEVBQ25CLDJCQUEyQixFQUMzQiw0QkFBNEIsR0FDN0IsTUFBTSw2QkFBNkIsQ0FBQztBQXVGckMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsT0FBTyxFQUFFLElBQUksRUFBRSxVQUFVLEVBQUUsV0FBVyxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBQ25ELE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEIsT0FBTyxFQUFFLG1CQUFtQixFQUFvQyxNQUFNLHVCQUF1QixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDekQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQy9ELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzdELE9BQU8sRUFDTCw2QkFBNkIsRUFDN0IsOEJBQThCLEVBQzlCLGtDQUFrQyxFQUNsQyxnQ0FBZ0MsRUFDaEMseUJBQXlCLEdBQzFCLE1BQU0sOEJBQThCLENBQUM7QUFDdEMsT0FBTyxFQUNMLGdCQUFnQixFQUNoQixrQkFBa0IsRUFDbEIsMEJBQTBCLEdBQzNCLE1BQU0sd0JBQXdCLENBQUM7QUFDaEMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3BFLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXBFLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEdBQ3JCLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUNMLDRCQUE0QixFQUM1Qix1QkFBdUIsRUFDdkIsbUJBQW1CLEVBQ25CLDJCQUEyQixFQUMzQiw0QkFBNEIsR0FDN0IsTUFBTSw2QkFBNkIsQ0FBQztBQTRGckMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsT0FBTyxFQUFFLElBQUksRUFBRSxVQUFVLEVBQUUsV0FBVyxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBQ25ELE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEIsT0FBTyxFQUFFLG1CQUFtQixFQUFvQyxNQUFNLHVCQUF1QixDQUFDIn0=

package/dist_ts_agent/plugins.d.ts

@@ -1,6 +1,6 @@
 import { streamText, generateText, stepCountIs, wrapLanguageModel } from 'ai';
 export { streamText, generateText, stepCountIs, wrapLanguageModel };
-export type { AssistantModelMessage, ModelMessage, StepResult, SystemModelMessage, ToolSet, ToolModelMessage, ToolExecutionOptions, StreamTextResult, UserModelMessage, } from 'ai';
+export type { AssistantModelMessage, LanguageModelUsage, ModelMessage, StepResult, SystemModelMessage, ToolSet, ToolModelMessage, ToolExecutionOptions, StreamTextResult, UserModelMessage, } from 'ai';
 import { applySmartAiCacheProviderOptions, createModelLimitInfo, createSmartAiCachingMiddleware, isModelLimitError, isModelLimitInfo, jsonSchema, ModelLimitError, readRetryAfterMs, resolveSmartAiCacheProvider, tool } from '@modelprofile.com/flexharness-models';
 export { applySmartAiCacheProviderOptions, createModelLimitInfo, createSmartAiCachingMiddleware, isModelLimitError, isModelLimitInfo, ModelLimitError, readRetryAfterMs, resolveSmartAiCacheProvider, tool, jsonSchema, };
 export type { ISmartAiCacheOptions, TSmartAiLanguageModel, TSmartAiCacheRetention, TSmartAiCacheSetting, TSmartAiProviderOptions as ProviderOptions, } from '@modelprofile.com/flexharness-models';

package/dist_ts_agent/plugins.js

@@ -7,4 +7,4 @@ export { applySmartAiCacheProviderOptions, createModelLimitInfo, createSmartAiCa
 // zod
 import { z } from 'zod';
 export { z };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2FnZW50L3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYztBQUNkLE9BQU8sRUFBRSxVQUFVLEVBQUUsWUFBWSxFQUFFLFdBQVcsRUFBRSxpQkFBaUIsRUFBRSxNQUFNLElBQUksQ0FBQztBQUU5RSxPQUFPLEVBQUUsVUFBVSxFQUFFLFlBQVksRUFBRSxXQUFXLEVBQUUsaUJBQWlCLEVBQUUsQ0FBQztBQWNwRSw2QkFBNkI7QUFDN0IsT0FBTyxFQUNMLGdDQUFnQyxFQUNoQyxvQkFBb0IsRUFDcEIsOEJBQThCLEVBQzlCLGlCQUFpQixFQUNqQixnQkFBZ0IsRUFDaEIsVUFBVSxFQUNWLGVBQWUsRUFDZixnQkFBZ0IsRUFDaEIsMkJBQTJCLEVBQzNCLElBQUksR0FDTCxNQUFNLHNDQUFzQyxDQUFDO0FBRTlDLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEVBQ3BCLDhCQUE4QixFQUM5QixpQkFBaUIsRUFDakIsZ0JBQWdCLEVBQ2hCLGVBQWUsRUFDZixnQkFBZ0IsRUFDaEIsMkJBQTJCLEVBQzNCLElBQUksRUFDSixVQUFVLEdBQ1gsQ0FBQztBQWdCRixNQUFNO0FBQ04sT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4QixPQUFPLEVBQUUsQ0FBQyxFQUFFLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2FnZW50L3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYztBQUNkLE9BQU8sRUFBRSxVQUFVLEVBQUUsWUFBWSxFQUFFLFdBQVcsRUFBRSxpQkFBaUIsRUFBRSxNQUFNLElBQUksQ0FBQztBQUU5RSxPQUFPLEVBQUUsVUFBVSxFQUFFLFlBQVksRUFBRSxXQUFXLEVBQUUsaUJBQWlCLEVBQUUsQ0FBQztBQWVwRSw2QkFBNkI7QUFDN0IsT0FBTyxFQUNMLGdDQUFnQyxFQUNoQyxvQkFBb0IsRUFDcEIsOEJBQThCLEVBQzlCLGlCQUFpQixFQUNqQixnQkFBZ0IsRUFDaEIsVUFBVSxFQUNWLGVBQWUsRUFDZixnQkFBZ0IsRUFDaEIsMkJBQTJCLEVBQzNCLElBQUksR0FDTCxNQUFNLHNDQUFzQyxDQUFDO0FBRTlDLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEVBQ3BCLDhCQUE4QixFQUM5QixpQkFBaUIsRUFDakIsZ0JBQWdCLEVBQ2hCLGVBQWUsRUFDZixnQkFBZ0IsRUFDaEIsMkJBQTJCLEVBQzNCLElBQUksRUFDSixVQUFVLEdBQ1gsQ0FBQztBQWdCRixNQUFNO0FBQ04sT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4QixPQUFPLEVBQUUsQ0FBQyxFQUFFLENBQUMifQ==

package/dist_ts_agent/runner.d.ts

@@ -1,4 +1,4 @@
 import type { IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';
 /** Run in Node or a secure browser context, with internally owned cleanup. */
 export declare function runAgent(options: IAgentRunOptions): Promise<IAgentRunResult>;
-export type { IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';
+export type { IAgentRunOptions, IAgentRunResult, IAgentUsage, TAgentModelCallUnreportedReason, TAgentModelCallUsage, TAgentModelCallUsageEvent, } from './smartagent.interfaces.js';

package/dist_ts_agent/runtime.run.js

@@ -39,6 +39,7 @@ export async function runAgentWithSession(options, createSession) {
         onToolCallUpdate: options.onToolCallUpdate,
         onToolCallFinish: options.onToolCallFinish,
         onRetry: options.onRetry,
+        onUsage: options.onUsage,
         onToolCall: options.onToolCall,
         onToolResult: options.onToolResult,
         onContextOverflow: options.onContextOverflow,
@@ -92,4 +93,4 @@ export async function runAgentWithSession(options, createSession) {
         await session.close();
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5ydW4uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9ydW50aW1lLnJ1bi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFPQSxNQUFNLGNBQWMsR0FBRyxDQUNyQixNQUE4QixFQUM5QixNQUF1QyxFQUNqQyxFQUFFO0lBQ1IsTUFBTSxPQUFPLEdBQUcsSUFBSSxHQUFHLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDLE1BQU0sRUFBRSxLQUFLLEVBQUUsRUFBRSxDQUFDLENBQUMsTUFBTSxDQUFDLFVBQVUsRUFBRSxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDbkYsS0FBSyxNQUFNLE1BQU0sSUFBSSxNQUFNLEVBQUUsQ0FBQztRQUM1QixNQUFNLGFBQWEsR0FBRyxPQUFPLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUNyRCxJQUFJLGFBQWEsS0FBSyxTQUFTLEVBQUUsQ0FBQztZQUNoQyxNQUFNLENBQUMsSUFBSSxDQUFDLEVBQUUsR0FBRyxNQUFNLEVBQUUsQ0FBQyxDQUFDO1lBQzNCLE9BQU8sQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLFVBQVUsRUFBRSxNQUFNLENBQUMsTUFBTSxHQUFHLENBQUMsQ0FBQyxDQUFDO1FBQ3BELENBQUM7YUFBTSxDQUFDO1lBQ04sTUFBTSxDQUFDLGFBQWEsQ0FBQyxHQUFHLEVBQUUsR0FBRyxNQUFNLENBQUMsYUFBYSxDQUFDLEVBQUUsR0FBRyxNQUFNLEVBQUUsQ0FBQztRQUNsRSxDQUFDO0lBQ0gsQ0FBQztBQUNILENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxLQUFLLFVBQVUsbUJBQW1CLENBQ3ZDLE9BQXlCLEVBQ3pCLGFBQXdFO0lBRXhFLE1BQU0sT0FBTyxHQUFHLE1BQU0sYUFBYSxDQUFDO1FBQ2xDLEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSztRQUNwQixNQUFNLEVBQUUsT0FBTyxDQUFDLE1BQU07UUFDdEIsS0FBSyxF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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5ydW4uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9ydW50aW1lLnJ1bi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFPQSxNQUFNLGNBQWMsR0FBRyxDQUNyQixNQUE4QixFQUM5QixNQUF1QyxFQUNqQyxFQUFFO0lBQ1IsTUFBTSxPQUFPLEdBQUcsSUFBSSxHQUFHLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDLE1BQU0sRUFBRSxLQUFLLEVBQUUsRUFBRSxDQUFDLENBQUMsTUFBTSxDQUFDLFVBQVUsRUFBRSxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDbkYsS0FBSyxNQUFNLE1BQU0sSUFBSSxNQUFNLEVBQUUsQ0FBQztRQUM1QixNQUFNLGFBQWEsR0FBRyxPQUFPLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUNyRCxJQUFJLGFBQWEsS0FBSyxTQUFTLEVBQUUsQ0FBQztZQUNoQyxNQUFNLENBQUMsSUFBSSxDQUFDLEVBQUUsR0FBRyxNQUFNLEVBQUUsQ0FBQyxDQUFDO1lBQzNCLE9BQU8sQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLFVBQVUsRUFBRSxNQUFNLENBQUMsTUFBTSxHQUFHLENBQUMsQ0FBQyxDQUFDO1FBQ3BELENBQUM7YUFBTSxDQUFDO1lBQ04sTUFBTSxDQUFDLGFBQWEsQ0FBQyxHQUFHLEVBQUUsR0FBRyxNQUFNLENBQUMsYUFBYSxDQUFDLEVBQUUsR0FBRyxNQUFNLEVBQUUsQ0FBQztRQUNsRSxDQUFDO0lBQ0gsQ0FBQztBQUNILENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxLQUFLLFVBQVUsbUJBQW1CLENBQ3ZDLE9BQXlCLEVBQ3pCLGFBQXdFO0lBRXhFLE1BQU0sT0FBTyxHQUFHLE1BQU0sYUFBYSxDQUFDO1FBQ2xDLEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSztRQUNwQixNQUFNLEVBQUUsT0FBTyxDQUFDLE1BQU07UUFDdEIsS0FBSyxF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

package/dist_ts_agent/smartagent.interfaces.d.ts

@@ -33,8 +33,64 @@ export type TAgentToolCallFinishEvent = (IAgentToolCallStartEvent & {
     success: false;
     error: string;
 });
+/** Token usage of model calls. A count a provider leaves out counts as zero. */
+export interface IAgentUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+interface IAgentModelCallIdentity {
+    /** The provider of the model that was called, as the language model names it. */
+    provider: string;
+    /**
+     * The model id the call was made with: the language model's `modelId`. Every call carries it,
+     * whatever its outcome, so key usage caps on `provider` and `requestedModelId`.
+     */
+    requestedModelId: string;
+}
+/** Why a model call ended without the provider reporting its usage. */
+export type TAgentModelCallUnreportedReason = 'aborted' | 'failed' | 'missing';
+/**
+ * The usage outcome of one model call, as the component that made the call reports it.
+ * `reported`: the provider reported the call's usage. `responseModelId` is the model id the
+ * provider's response named, or `requestedModelId` when the response named none.
+ * `unreported`: the call ended before the provider reported its usage: `aborted` (the call was
+ * aborted), `failed` (the call or its response failed) or `missing` (the response carried no usage).
+ * The provider may still have consumed tokens for it; their number is unknown.
+ */
+export type TAgentModelCallUsage = (IAgentModelCallIdentity & {
+    status: 'reported';
+    responseModelId: string;
+    usage: IAgentUsage;
+}) | (IAgentModelCallIdentity & {
+    status: 'unreported';
+    reason: TAgentModelCallUnreportedReason;
+});
+/** Receives the usage outcome of each model call. Must not throw. */
+export type TAgentModelCallUsageReporter = (call: TAgentModelCallUsage) => void;
+/**
+ * The usage outcome of one model call of a session, reported once per call through `onUsage`.
+ * `source: 'generation'`: a model step of the generation `generationId`.
+ * `source: 'compaction'`: a model call of a context compaction. `generationId` names the generation
+ * whose context overflow caused it; it is absent for `compact()` and event retention.
+ */
+export type TAgentModelCallUsageEvent = TAgentModelCallUsage & ({
+    source: 'generation';
+    generationId: string;
+} | {
+    source: 'compaction';
+    generationId?: string;
+});
 export interface IAgentContextOverflowInvocationOptions {
     abortSignal?: AbortSignal;
+    /**
+     * Reports the usage of each model call the handler makes, into the session's `onUsage` as
+     * `source: 'compaction'`. The session always supplies it. Report every call before the returned
+     * promise settles, including calls that fail or are aborted.
+     */
+    reportUsage?: TAgentModelCallUsageReporter;
 }
 export interface IAgentContextBuildOptions {
     events: readonly TAgentEvent[];
@@ -43,6 +99,12 @@ export type TAgentContextBuilder = (options: IAgentContextBuildOptions) => Model
 export interface IAgentContextCompactionOptions {
     abortSignal?: AbortSignal;
     reason: 'context-overflow' | 'retention' | 'manual';
+    /**
+     * Reports the usage of each model call the compactor makes, into the session's `onUsage` as
+     * `source: 'compaction'`. The session always supplies it. Report every call before the returned
+     * promise settles, including calls that fail or are aborted.
+     */
+    reportUsage?: TAgentModelCallUsageReporter;
 }
 export type TAgentContextCompactor = (messages: ModelMessage[], events: readonly TAgentEvent[], options: IAgentContextCompactionOptions) => Promise<ModelMessage[]>;
 export interface IAgentEventRetentionOptions {
@@ -116,6 +178,16 @@ export interface IAgentSessionOptions {
     onToolCallFinish?: (event: TAgentToolCallFinishEvent) => void;
     /** Called before the engine waits to retry a rate-limited or unavailable model call. */
     onRetry?: (event: IAgentRetryEvent) => void;
+    /**
+     * Called once for every model call of the session, as soon as its usage is known: when the
+     * provider reports it, or when the call ends without it. This covers the generation's model
+     * steps, the model call of `compactMessages()` when a compactor passes it `reportUsage`, and every
+     * call a `contextCompactor` or `onContextOverflow` handler reports through `reportUsage`. The
+     * reported calls of a generation, including those of a compaction its context overflow caused,
+     * sum to the generation's `usage` when it returns. Must not throw; an error it throws is reported
+     * like a session listener error and does not change the generation's outcome.
+     */
+    onUsage?: (event: TAgentModelCallUsageEvent) => void;
     /** @deprecated Use onToolCallStart instead. */
     onToolCall?: (toolName: string, input: unknown) => void;
     /** @deprecated Use onToolCallFinish instead. */
@@ -229,14 +301,11 @@ export interface IAgentRunResult {
     steps: number;
     /** Finish reason from the final step */
     finishReason: string;
-    /** Accumulated token usage across all steps */
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-        cacheReadTokens: number;
-        cacheWriteTokens: number;
-    };
+    /**
+     * Token usage the provider reported for every model call of the run: its model steps, retried
+     * calls included, and the calls of a compaction its context overflow caused that were reported
+     */
+    usage: IAgentUsage;
     /** Tool calls observed during the run, including inputs and outputs/errors when available */
     toolCalls: IAgentToolCallRecord[];
 }

package/dist_ts_agent/smartagent.interfaces.js

@@ -21,4 +21,4 @@ export class ContextOverflowError extends Error {
         this.name = 'ContextOverflowError';
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXlOQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUF5SEQsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXNTQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUFzSEQsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=

package/dist_ts_agent/smartagent.usage.d.ts

@@ -0,0 +1,25 @@
+import type { LanguageModelUsage } from './plugins.js';
+import type { TAgentModelCallUnreportedReason, TAgentModelCallUsageReporter } from './smartagent.interfaces.js';
+/** The identity of the language model whose calls a recorder follows. */
+export interface IAgentModelCallUsageRecorderModel {
+    readonly provider: string;
+    readonly modelId: string;
+}
+/**
+ * Follows the calls of one language model and reports each call's usage exactly once.
+ * Call `start()` when a model call begins, `end()` when its provider reports usage, and `settle()`
+ * when the call ends otherwise. A call that is still open when the next one starts ended without
+ * usage and is reported as `unreported` with reason `missing`.
+ */
+export declare class AgentModelCallUsageRecorder {
+    private readonly model;
+    private readonly report;
+    private open;
+    constructor(model: IAgentModelCallUsageRecorderModel, report: TAgentModelCallUsageReporter);
+    /** A model call begins. */
+    start(): void;
+    /** The provider reported the usage of the current call. A count it leaves out counts as zero. */
+    end(responseModelId: string, providerUsage: LanguageModelUsage): void;
+    /** The current call ended without usage. Does nothing when no call is open. */
+    settle(reason: TAgentModelCallUnreportedReason): void;
+}

package/dist_ts_agent/smartagent.usage.js

@@ -0,0 +1,53 @@
+/**
+ * Follows the calls of one language model and reports each call's usage exactly once.
+ * Call `start()` when a model call begins, `end()` when its provider reports usage, and `settle()`
+ * when the call ends otherwise. A call that is still open when the next one starts ended without
+ * usage and is reported as `unreported` with reason `missing`.
+ */
+export class AgentModelCallUsageRecorder {
+    model;
+    report;
+    open = false;
+    constructor(model, report) {
+        this.model = model;
+        this.report = report;
+    }
+    /** A model call begins. */
+    start() {
+        this.settle('missing');
+        this.open = true;
+    }
+    /** The provider reported the usage of the current call. A count it leaves out counts as zero. */
+    end(responseModelId, providerUsage) {
+        this.open = false;
+        const inputTokens = providerUsage.inputTokens ?? 0;
+        const outputTokens = providerUsage.outputTokens ?? 0;
+        const usage = {
+            inputTokens,
+            outputTokens,
+            totalTokens: inputTokens + outputTokens,
+            cacheReadTokens: providerUsage.inputTokenDetails.cacheReadTokens ?? 0,
+            cacheWriteTokens: providerUsage.inputTokenDetails.cacheWriteTokens ?? 0,
+        };
+        this.report({
+            status: 'reported',
+            provider: this.model.provider,
+            requestedModelId: this.model.modelId,
+            responseModelId,
+            usage,
+        });
+    }
+    /** The current call ended without usage. Does nothing when no call is open. */
+    settle(reason) {
+        if (!this.open)
+            return;
+        this.open = false;
+        this.report({
+            status: 'unreported',
+            provider: this.model.provider,
+            requestedModelId: this.model.modelId,
+            reason,
+        });
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC51c2FnZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2FnZW50L3NtYXJ0YWdlbnQudXNhZ2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBYUE7Ozs7O0dBS0c7QUFDSCxNQUFNLE9BQU8sMkJBQTJCO0lBSW5CO0lBQ0E7SUFKWCxJQUFJLEdBQUcsS0FBSyxDQUFDO0lBRXJCLFlBQ21CLEtBQXdDLEVBQ3hDLE1BQW9DO1FBRHBDLFVBQUssR0FBTCxLQUFLLENBQW1DO1FBQ3hDLFdBQU0sR0FBTixNQUFNLENBQThCO0lBQ3BELENBQUM7SUFFSiwyQkFBMkI7SUFDcEIsS0FBSztRQUNWLElBQUksQ0FBQyxNQUFNLENBQUMsU0FBUyxDQUFDLENBQUM7UUFDdkIsSUFBSSxDQUFDLElBQUksR0FBRyxJQUFJLENBQUM7SUFDbkIsQ0FBQztJQUVELGlHQUFpRztJQUMxRixHQUFHLENBQUMsZUFBdUIsRUFBRSxhQUFpQztRQUNuRSxJQUFJLENBQUMsSUFBSSxHQUFHLEtBQUssQ0FBQztRQUNsQixNQUFNLFdBQVcsR0FBRyxhQUFhLENBQUMsV0FBVyxJQUFJLENBQUMsQ0FBQztRQUNuRCxNQUFNLFlBQVksR0FBRyxhQUFhLENBQUMsWUFBWSxJQUFJLENBQUMsQ0FBQztRQUNyRCxNQUFNLEtBQUssR0FBZ0I7WUFDekIsV0FBVztZQUNYLFlBQVk7WUFDWixXQUFXLEVBQUUsV0FBVyxHQUFHLFlBQVk7WUFDdkMsZUFBZSxFQUFFLGFBQWEsQ0FBQyxpQkFBaUIsQ0FBQyxlQUFlLElBQUksQ0FBQztZQUNyRSxnQkFBZ0IsRUFBRSxhQUFhLENBQUMsaUJBQWlCLENBQUMsZ0JBQWdCLElBQUksQ0FBQztTQUN4RSxDQUFDO1FBQ0YsSUFBSSxDQUFDLE1BQU0sQ0FBQztZQUNWLE1BQU0sRUFBRSxVQUFVO1lBQ2xCLFFBQVEsRUFBRSxJQUFJLENBQUMsS0FBSyxDQUFDLFFBQVE7WUFDN0IsZ0JBQWdCLEVBQUUsSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPO1lBQ3BDLGVBQWU7WUFDZixLQUFLO1NBQ04sQ0FBQyxDQUFDO0lBQ0wsQ0FBQztJQUVELCtFQUErRTtJQUN4RSxNQUFNLENBQUMsTUFBdUM7UUFDbkQsSUFBSSxDQUFDLElBQUksQ0FBQyxJQUFJO1lBQUUsT0FBTztRQUN2QixJQUFJLENBQUMsSUFBSSxHQUFHLEtBQUssQ0FBQztRQUNsQixJQUFJLENBQUMsTUFBTSxDQUFDO1lBQ1YsTUFBTSxFQUFFLFlBQVk7WUFDcEIsUUFBUSxFQUFFLElBQUksQ0FBQyxLQUFLLENBQUMsUUFBUTtZQUM3QixnQkFBZ0IsRUFBRSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU87WUFDcEMsTUFBTTtTQUNQLENBQUMsQ0FBQztJQUNMLENBQUM7Q0FDRiJ9

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness-agent",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "type": "module",
   "description": "Standalone event-driven agent runtime with generation transactions, context and tool execution contracts.",
   "main": "./dist_ts_agent/index.js",
@@ -18,7 +18,7 @@
     }
   },
   "dependencies": {
-    "@modelprofile.com/flexharness-models": "8.3.0",
+    "@modelprofile.com/flexharness-models": "8.4.0",
     "ai": "^7.0.79",
     "zod": "^4.4.1",
     "@noble/hashes": "^2.4.0",

package/readme.md

@@ -88,7 +88,7 @@ The following Node examples reuse `setup` and, where needed, `tools` from the qu
 | `messages` | Current AI SDK message history after projection or compaction. Pass it into another run to continue. |
 | `steps` | Completed model steps, including steps from validation-triggered attempts. A step can call several tools. |
 | `finishReason` | The model's final finish reason; inspect this together with application validation. |
-| `usage` | Input, output and total tokens, plus cache-read and cache-write tokens. |
+| `usage` | Input, output and total tokens, plus cache-read and cache-write tokens, summed over every model call of the run the provider reported: its model steps, retried calls included, and the reported calls of a compaction its context overflow caused. |
 | `toolCalls` | Tool-call IDs, names and inputs, with available outputs or errors. |
 
 ```typescript
@@ -154,9 +154,68 @@ Pass these callbacks to `runAgent` or `AgentSession.create()`:
 | `onToolCallUpdate(event)` | The call identity and a transient streamed `output`. |
 | `onToolCallFinish(event)` | The call identity plus either `success: true, output` or `success: false, error`. |
 | `onRetry(event)` | Before each wait to retry a model call: `attempt`, `maxAttempts`, `delayMs` and `reason` (`rate_limit`, `overloaded`, `unavailable`). |
+| `onUsage(event)` | Once per model call, as soon as its usage is known; see [Count the usage of every run](#count-the-usage-of-every-run). |
 
 Tool updates are transient; the finish callback carries the authoritative final output. Use `subscribe()` for committed session changes (`committed`, `updated`, `archived`), and retain its returned unsubscribe function. Session listeners are delivered in order per listener, have bounded queues and timeouts, and are removed on failure. Streaming callbacks and session-change listeners serve different purposes.
 
+## Count the usage of every run
+
+A run that throws or is aborted has used tokens too, and its promise carries no result. `onUsage` reports each model call once, as soon as its usage is known, whatever the run's outcome. Sum it to count a run's usage:
+
+```typescript
+import type { IAgentUsage } from '@modelprofile.com/flexharness-agent';
+
+const used: IAgentUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+let usageComplete = true;
+try {
+  await runAgent({
+    ...setup,
+    tools,
+    prompt: 'Convert 10 km to miles.',
+    abort: AbortSignal.timeout(60_000),
+    onUsage: (event) => {
+      if (event.status === 'unreported') {
+        usageComplete = false;
+        return;
+      }
+      for (const key of Object.keys(used) as (keyof IAgentUsage)[]) used[key] += event.usage[key];
+    },
+  });
+} finally {
+  console.log(used, usageComplete ? 'complete' : 'lower bound');
+}
+```
+
+| Event field | Meaning |
+| --- | --- |
+| `source` | `generation`: a model step of the generation. `compaction`: a model call of a context compaction. |
+| `generationId` | The generation the call belongs to. A compaction carries the generation whose context overflow caused it; a compaction by `compact()` or event retention has none. |
+| `provider`, `requestedModelId` | The model the call was made with: the language model's `provider` and `modelId`. Every event carries both, whatever its status, so key usage caps on them. |
+| `status: 'reported'`, `usage`, `responseModelId` | The provider reported the call's usage. A count the provider leaves out is zero. `responseModelId` is the model id the provider's response named (a provider may answer with a dated model version), or `requestedModelId` when it named none. |
+| `status: 'unreported'`, `reason` | The call ended before the provider reported its usage: `aborted` (the call was aborted), `failed` (the call or its response failed) or `missing` (the response carried no usage). The provider may still have consumed tokens for it; their number is unknown. |
+
+When a run returns, its reported calls sum to `result.usage`; count one or the other, not both. A call is reported when the provider's response ends, before its tool calls run, so a run aborted during a tool call still reports the call that requested it. Retried calls and validation retries are included. `onUsage` must not throw; an error it throws is reported like a session listener error and does not change the run's outcome. `runAgent` delivers every event of the run before its promise settles. `AgentSession.create()` accepts the same callback for every generation and compaction of the session; `generate()` and `scheduleGenerate()` without a `transaction` reject as soon as their abort signal fires and may report the interrupted call afterwards; `close()` waits for that report. With a `transaction`, they settle only after every call of the generation has been reported.
+
+### What is counted
+
+- Every model step of a generation, whatever its outcome, including retried calls and validation retries.
+- The model calls of a context compaction, when the compactor reports them. `contextCompactor` and `onContextOverflow` receive `reportUsage` in their options; it reports into `onUsage` with `source: 'compaction'`. `compactMessages()` from `@modelprofile.com/flexharness/compaction` reports each attempt of its model call when it receives `reportUsage`, so pass the handler's options through:
+
+  ```typescript
+  import { compactMessages } from '@modelprofile.com/flexharness/compaction';
+
+  const session = await AgentSession.create({
+    ...setup,
+    contextCompactor: (messages, _events, options) => compactMessages(setup.model, messages, options),
+    onContextOverflow: (messages, options) => compactMessages(setup.model, messages, options),
+    onUsage: (event) => console.log(event),
+  });
+  ```
+
+  A handler that makes its own model calls reports each one through `reportUsage` before its promise settles, a call that fails or is aborted as `unreported`. `AgentModelCallUsageRecorder` does the bookkeeping for one language model: call `start()` when a call begins, `end(responseModelId, usage)` with the AI SDK's `onLanguageModelCallEnd` values, and `settle(reason)` when a call ends otherwise.
+
+Not counted: model calls a handler makes without reporting them through `reportUsage`, and model calls outside the session, such as tools that call models themselves. Report those in your own accounting.
+
 ## Validate an answer and request corrections
 
 `validateCompletion` returns `void` to accept a result or a string to add a corrective user message and generate again. `maxValidationRetries` defaults to `0`: a failed validation throws unless retries are configured.
@@ -243,9 +302,9 @@ Use an application-owned durable adapter for persistent sessions. Its `save(sess
 ### Bound model context and active events
 
 - `contextBuilder({ events })` controls the model-message projection.
-- `contextCompactor(messages, events, { reason, abortSignal })` returns replacement model messages. Provide it to use `session.compact()` or automatic event retention.
+- `contextCompactor(messages, events, { reason, abortSignal, reportUsage })` returns replacement model messages. Provide it to use `session.compact()` or automatic event retention. Report the usage of its model calls through `reportUsage`; see [What is counted](#what-is-counted).
 - `eventRetention: { maxEvents }` triggers compaction and archival when the active event count exceeds the threshold. It also requires an event store with `archive()` support.
-- Context overflow invokes the configured compactor, or the `onContextOverflow` handler. Without either, generation throws `ContextOverflowError`. `maxContextOverflowRetries` defaults to `3`.
+- Context overflow invokes the configured compactor, or the `onContextOverflow(messages, { abortSignal, reportUsage })` handler. Without either, generation throws `ContextOverflowError`. `maxContextOverflowRetries` defaults to `3`.
 - Open transactions and uncertain tool intents constrain when compaction and archival can proceed. Resolve them before manual compaction.
 
 Compaction changes the active model context; archival moves covered events out of the active event set. Implement archive retention in your chosen store when you need a complete audit history.

package/ts_agent/classes.sessionengine.ts

@@ -42,6 +42,8 @@ import {
   type TAgentSessionChangeListener,
   type TAgentCacheSetting,
   type TAgentGenerationPrepare,
+  type TAgentModelCallUsageEvent,
+  type TAgentModelCallUsageReporter,
   type TAgentPrompt,
   type TAgentToolCallFinishEvent,
   type TAgentToolExecutionReconciliationOptions,
@@ -51,6 +53,7 @@ import {
   validateAgentEventSnapshotV2,
 } from './smartagent.persistence.js';
 import { MAX_RETRY_ATTEMPTS, planModelCallRetry } from './smartagent.retry.js';
+import { AgentModelCallUsageRecorder } from './smartagent.usage.js';
 import type {
   IAgentEventArchive,
   IAgentEventArchiveV2,
@@ -520,6 +523,19 @@ export class AgentSessionEngine implements IAgentSession {
     this.platform.reportListenerError(error);
   }
 
+  private reportModelCallUsage(event: TAgentModelCallUsageEvent): void {
+    try {
+      this.options.onUsage?.(event);
+    } catch (error) {
+      this.reportListenerError(error);
+    }
+  }
+
+  /** Reports the calls of a compaction that no generation caused: compact() and event retention. */
+  private readonly reportSessionCompactionUsage: TAgentModelCallUsageReporter = (call) => {
+    this.reportModelCallUsage({ ...call, source: 'compaction' });
+  };
+
   private queueNotification(change: IAgentSessionChange, durability: Promise<void>): void {
     const dispatch = (async () => {
       try {
@@ -1165,6 +1181,7 @@ export class AgentSessionEngine implements IAgentSession {
 
   private async performCompaction(
     reason: 'context-overflow' | 'retention' | 'manual',
+    reportUsage: TAgentModelCallUsageReporter,
     abortSignal?: AbortSignal,
   ): Promise<IContextCompactionEvent | undefined> {
     abortSignal?.throwIfAborted();
@@ -1199,11 +1216,15 @@ export class AgentSessionEngine implements IAgentSession {
     const messages = this.buildContext(visibleCoveredEvents);
     const replacementMessages = this.options.contextCompactor
       ? await this.invokeGenerationCallback(
-          () => this.options.contextCompactor!(messages, visibleCoveredEvents, { abortSignal, reason }),
+          () => this.options.contextCompactor!(
+            messages,
+            visibleCoveredEvents,
+            { abortSignal, reason, reportUsage },
+          ),
         )
       : reason === 'context-overflow' && this.options.onContextOverflow
         ? await this.invokeGenerationCallback(
-            () => this.options.onContextOverflow!(messages, { abortSignal }),
+            () => this.options.onContextOverflow!(messages, { abortSignal, reportUsage }),
           )
         : undefined;
     if (!replacementMessages) {
@@ -1261,7 +1282,11 @@ export class AgentSessionEngine implements IAgentSession {
     const combinedAbort = combineAbortSignals([options.abort, this.sessionAbortController.signal]);
     const operation = this.queueExclusive(async () => {
       combinedAbort.signal.throwIfAborted();
-      await this.performCompaction(options.reason ?? 'manual', combinedAbort.signal);
+      await this.performCompaction(
+        options.reason ?? 'manual',
+        this.reportSessionCompactionUsage,
+        combinedAbort.signal,
+      );
     }).finally(combinedAbort.cleanup);
     return waitWithAbort(operation, [options.abort, this.sessionAbortController.signal]);
   }
@@ -1329,6 +1354,7 @@ export class AgentSessionEngine implements IAgentSession {
     while (this.events.length > retention.maxEvents) {
       const compaction = await this.performCompaction(
         'retention',
+        this.reportSessionCompactionUsage,
         this.sessionAbortController.signal,
       );
       if (!compaction) return;
@@ -1706,6 +1732,8 @@ export class AgentSessionEngine implements IAgentSession {
       return this.generateLocked(options);
     });
     this.generationQueue = run.then(() => undefined, () => undefined);
+    // A transactional generation is not raced against its abort signal: it settles when its
+    // execution has ended, after each of its model calls was reported through `onUsage`.
     return options.transaction
       ? run
       : waitWithAbort(run, [options.abort, this.sessionAbortController.signal]);
@@ -1818,6 +1846,21 @@ export class AgentSessionEngine implements IAgentSession {
       let totalOutput = 0;
       let totalCacheRead = 0;
       let totalCacheWrite = 0;
+      const recordModelCallUsage = (event: TAgentModelCallUsageEvent): void => {
+        if (event.status === 'reported') {
+          totalInput += event.usage.inputTokens;
+          totalOutput += event.usage.outputTokens;
+          totalCacheRead += event.usage.cacheReadTokens;
+          totalCacheWrite += event.usage.cacheWriteTokens;
+        }
+        this.reportModelCallUsage(event);
+      };
+      const modelCalls = new AgentModelCallUsageRecorder(
+        runtime.model,
+        (call) => recordModelCallUsage({ ...call, source: 'generation', generationId }),
+      );
+      const reportCompactionUsage: TAgentModelCallUsageReporter = (call) =>
+        recordModelCallUsage({ ...call, source: 'compaction', generationId });
       let currentInferenceId: string | undefined;
       let latestInferenceVisibleIds = new Set(this.events.map((event) => event.id));
       const completedInferenceIds = new Set<string>();
@@ -1892,6 +1935,12 @@ export class AgentSessionEngine implements IAgentSession {
             onError: ({ error }) => {
               streamError = error;
             },
+            onLanguageModelCallStart: () => {
+              modelCalls.start();
+            },
+            onLanguageModelCallEnd: ({ modelId, usage }) => {
+              modelCalls.end(modelId, usage);
+            },
             repairToolCall: async ({ toolCall, tools: availableTools, error }) => {
               const lowerName = toolCall.toolName.toLowerCase();
               if (
@@ -2134,10 +2183,6 @@ export class AgentSessionEngine implements IAgentSession {
                 completedInferenceIds.add(currentInferenceId);
                 stepCount++;
               }
-              totalInput += step.usage.inputTokens ?? 0;
-              totalOutput += step.usage.outputTokens ?? 0;
-              totalCacheRead += step.usage.inputTokenDetails.cacheReadTokens ?? 0;
-              totalCacheWrite += step.usage.inputTokenDetails.cacheWriteTokens ?? 0;
               for (const toolCall of step.toolCalls) {
                 recordToolCall(toolCalls, toolCallIndexes, toolCall);
               }
@@ -2166,6 +2211,9 @@ export class AgentSessionEngine implements IAgentSession {
           const finishReason = await result.finishReason;
           await result.response;
           if (streamError) throw streamError;
+          // A stream whose call was aborted can end without an error; its call was aborted, not
+          // answered without usage.
+          modelCalls.settle(combinedAbort.signal.aborted ? 'aborted' : 'missing');
           flushReasoning();
           await this.flushPersistence();
 
@@ -2193,6 +2241,7 @@ export class AgentSessionEngine implements IAgentSession {
           completedResult = generationResult;
           return generationResult;
         } catch (error) {
+          modelCalls.settle(combinedAbort.signal.aborted ? 'aborted' : 'failed');
           flushReasoning();
           const effectiveError = streamError ?? error;
           if (combinedAbort.signal.aborted) {
@@ -2252,7 +2301,11 @@ export class AgentSessionEngine implements IAgentSession {
             }
             combinedAbort.signal.throwIfAborted();
             contextOverflowRetries++;
-            await this.performCompaction('context-overflow', combinedAbort.signal);
+            await this.performCompaction(
+              'context-overflow',
+              reportCompactionUsage,
+              combinedAbort.signal,
+            );
             continue;
           }
           throw effectiveError;

package/ts_agent/index.ts

@@ -14,6 +14,8 @@ export {
   modelMessagesToAgentEvents,
 } from './smartagent.events.js';
 export { ToolRegistry } from './smartagent.classes.toolregistry.js';
+export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
+export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
 export {
   AgentGenerationLeaseCleanupError,
   ContextOverflowError,
@@ -48,6 +50,7 @@ export type {
   IAgentToolCallRecord,
   IAgentToolCallStartEvent,
   IAgentToolCallUpdateEvent,
+  IAgentUsage,
   ProviderOptions,
   TAgentCacheRetention,
   TAgentCacheSetting,
@@ -55,6 +58,10 @@ export type {
   TAgentContextBuilder,
   TAgentContextCompactor,
   TAgentGenerationPrepare,
+  TAgentModelCallUnreportedReason,
+  TAgentModelCallUsage,
+  TAgentModelCallUsageEvent,
+  TAgentModelCallUsageReporter,
   TAgentSessionChangeListener,
   TAgentToolCallFinishEvent,
   TAgentToolExecutionReconciliationOptions,

package/ts_agent/plugins.ts

@@ -5,6 +5,7 @@ export { streamText, generateText, stepCountIs, wrapLanguageModel };
 
 export type {
   AssistantModelMessage,
+  LanguageModelUsage,
   ModelMessage,
   StepResult,
   SystemModelMessage,