@modelprofile.com/flexharness-agent 8.2.0 → 8.4.0

package/dist_ts_agent/index.d.ts

@@ -4,12 +4,15 @@ 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';
+export type { IAgentRetryEvent, TAgentRetryReason } from './smartagent.retry.js';
 export * from './tool.contracts.js';
 export * from './tool.persistence.js';
 export * from './tool.adapter.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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDekQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQy9ELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzdELE9BQU8sRUFDTCw2QkFBNkIsRUFDN0IsOEJBQThCLEVBQzlCLGtDQUFrQyxFQUNsQyxnQ0FBZ0MsRUFDaEMseUJBQXlCLEdBQzFCLE1BQU0sOEJBQThCLENBQUM7QUFDdEMsT0FBTyxFQUNMLGdCQUFnQixFQUNoQixrQkFBa0IsRUFDbEIsMEJBQTBCLEdBQzNCLE1BQU0sd0JBQXdCLENBQUM7QUFDaEMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3BFLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEdBQ3JCLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUNMLDRCQUE0QixFQUM1Qix1QkFBdUIsRUFDdkIsbUJBQW1CLEVBQ25CLDJCQUEyQixFQUMzQiw0QkFBNEIsR0FDN0IsTUFBTSw2QkFBNkIsQ0FBQztBQXNGckMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsT0FBTyxFQUFFLElBQUksRUFBRSxVQUFVLEVBQUUsV0FBVyxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBQ25ELE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEIsT0FBTyxFQUFFLG1CQUFtQixFQUFvQyxNQUFNLHVCQUF1QixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDekQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQy9ELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzdELE9BQU8sRUFDTCw2QkFBNkIsRUFDN0IsOEJBQThCLEVBQzlCLGtDQUFrQyxFQUNsQyxnQ0FBZ0MsRUFDaEMseUJBQXlCLEdBQzFCLE1BQU0sOEJBQThCLENBQUM7QUFDdEMsT0FBTyxFQUNMLGdCQUFnQixFQUNoQixrQkFBa0IsRUFDbEIsMEJBQTBCLEdBQzNCLE1BQU0sd0JBQXdCLENBQUM7QUFDaEMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3BFLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXBFLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEdBQ3JCLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUNMLDRCQUE0QixFQUM1Qix1QkFBdUIsRUFDdkIsbUJBQW1CLEVBQ25CLDJCQUEyQixFQUMzQiw0QkFBNEIsR0FDN0IsTUFBTSw2QkFBNkIsQ0FBQztBQTRGckMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsT0FBTyxFQUFFLElBQUksRUFBRSxVQUFVLEVBQUUsV0FBVyxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBQ25ELE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEIsT0FBTyxFQUFFLG1CQUFtQixFQUFvQyxNQUFNLHVCQUF1QixDQUFDIn0=

package/dist_ts_agent/plugins.d.ts

@@ -1,8 +1,8 @@
 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';
-import { applySmartAiCacheProviderOptions, createSmartAiCachingMiddleware, jsonSchema, resolveSmartAiCacheProvider, tool } from '@modelprofile.com/flexharness-models';
-export { applySmartAiCacheProviderOptions, createSmartAiCachingMiddleware, resolveSmartAiCacheProvider, tool, jsonSchema, };
+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';
 export type { IToolExecutionContext, IToolJobState, } from './tool.contracts.js';
 import { z } from 'zod';

package/dist_ts_agent/plugins.js

@@ -2,9 +2,9 @@
 import { streamText, generateText, stepCountIs, wrapLanguageModel } from 'ai';
 export { streamText, generateText, stepCountIs, wrapLanguageModel };
 // model contracts and AI SDK
-import { applySmartAiCacheProviderOptions, createSmartAiCachingMiddleware, jsonSchema, resolveSmartAiCacheProvider, tool, } from '@modelprofile.com/flexharness-models';
-export { applySmartAiCacheProviderOptions, createSmartAiCachingMiddleware, resolveSmartAiCacheProvider, tool, jsonSchema, };
+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, };
 // zod
 import { z } from 'zod';
 export { z };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2FnZW50L3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYztBQUNkLE9BQU8sRUFBRSxVQUFVLEVBQUUsWUFBWSxFQUFFLFdBQVcsRUFBRSxpQkFBaUIsRUFBRSxNQUFNLElBQUksQ0FBQztBQUU5RSxPQUFPLEVBQUUsVUFBVSxFQUFFLFlBQVksRUFBRSxXQUFXLEVBQUUsaUJBQWlCLEVBQUUsQ0FBQztBQWNwRSw2QkFBNkI7QUFDN0IsT0FBTyxFQUNMLGdDQUFnQyxFQUNoQyw4QkFBOEIsRUFDOUIsVUFBVSxFQUNWLDJCQUEyQixFQUMzQixJQUFJLEdBQ0wsTUFBTSxzQ0FBc0MsQ0FBQztBQUU5QyxPQUFPLEVBQ0wsZ0NBQWdDLEVBQ2hDLDhCQUE4QixFQUM5QiwyQkFBMkIsRUFDM0IsSUFBSSxFQUNKLFVBQVUsR0FDWCxDQUFDO0FBZ0JGLE1BQU07QUFDTixPQUFPLEVBQUUsQ0FBQyxFQUFFLE1BQU0sS0FBSyxDQUFDO0FBRXhCLE9BQU8sRUFBRSxDQUFDLEVBQUUsQ0FBQyJ9
+//# 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

@@ -38,6 +38,8 @@ export async function runAgentWithSession(options, createSession) {
         onToolCallStart: options.onToolCallStart,
         onToolCallUpdate: options.onToolCallUpdate,
         onToolCallFinish: options.onToolCallFinish,
+        onRetry: options.onRetry,
+        onUsage: options.onUsage,
         onToolCall: options.onToolCall,
         onToolResult: options.onToolResult,
         onContextOverflow: options.onContextOverflow,
@@ -91,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

@@ -1,6 +1,7 @@
 import type { ISmartAiCacheOptions, ToolSet, ModelMessage, TSmartAiLanguageModel, ProviderOptions, IToolExecutionContext, IToolJobState, TSmartAiCacheRetention, TSmartAiCacheSetting } from './plugins.js';
 import type { IAgentRuntimeEventPayload, IToolExecutionIntentEvent, TAgentEvent, TAgentGenerationOutcome, TAgentToolResultOutput } from './smartagent.events.js';
 import type { TAgentEventArchive, TAgentEventStore } from './smartagent.persistence.js';
+import type { IAgentRetryEvent } from './smartagent.retry.js';
 export type { ProviderOptions };
 export interface IAgentCacheOptions extends ISmartAiCacheOptions {
 }
@@ -32,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[];
@@ -42,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 {
@@ -113,6 +176,18 @@ export interface IAgentSessionOptions {
     onToolCallUpdate?: (event: IAgentToolCallUpdateEvent) => void;
     /** Called when a tool call finishes, with its stable AI SDK call id and success state. */
     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. */
@@ -226,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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXNOQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUF5SEQsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXNTQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUFzSEQsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=

package/dist_ts_agent/smartagent.retry.d.ts

@@ -0,0 +1,39 @@
+export type TAgentRetryReason = 'rate_limit' | 'overloaded' | 'unavailable';
+/** A failed model call the session engine retries after `delayMs`. */
+export interface IAgentRetryEvent {
+    /** One-based number of this retry within the current model call. */
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    reason: TAgentRetryReason;
+}
+export type TAgentRetryDecision = {
+    action: 'retry';
+    delayMs: number;
+    reason: TAgentRetryReason;
+} | {
+    action: 'fail';
+    error: unknown;
+} | {
+    action: 'not-retryable';
+};
+export interface IAgentRetryState {
+    /** Retries already made for the current model call. */
+    attempt: number;
+    /** Retry delay already spent on the current model call. */
+    retriedMs: number;
+    /** Provider id used when an untyped rate limit has to fail with a typed limit error. */
+    provider: string;
+    now: number;
+}
+export declare const MAX_RETRY_ATTEMPTS = 8;
+/** The longest provider-requested delay honoured; the AI SDK uses the same bound. */
+export declare const MAX_RETRY_AFTER_MS = 60000;
+/** The total delay one model call may spend retrying, equal to the full default backoff. */
+export declare const MAX_RETRY_WINDOW_MS = 150000;
+/**
+ * Decides whether a failed model call is retried. Usage limits never are; transient limits wait for
+ * the provider's delay up to MAX_RETRY_AFTER_MS, but never less than the backoff, and all retries of
+ * one call stay within MAX_RETRY_ATTEMPTS and MAX_RETRY_WINDOW_MS.
+ */
+export declare function planModelCallRetry(error: unknown, state: IAgentRetryState): TAgentRetryDecision;

package/dist_ts_agent/smartagent.retry.js

@@ -0,0 +1,67 @@
+import * as plugins from './plugins.js';
+export const MAX_RETRY_ATTEMPTS = 8;
+/** The longest provider-requested delay honoured; the AI SDK uses the same bound. */
+export const MAX_RETRY_AFTER_MS = 60_000;
+/** The total delay one model call may spend retrying, equal to the full default backoff. */
+export const MAX_RETRY_WINDOW_MS = 150_000;
+const RETRY_INITIAL_DELAY_MS = 2000;
+const RETRY_BACKOFF_FACTOR = 2;
+const RETRY_BACKOFF_MAX_DELAY_MS = 30_000;
+function backoffDelayMs(attempt) {
+    return Math.min(RETRY_INITIAL_DELAY_MS * RETRY_BACKOFF_FACTOR ** (attempt - 1), RETRY_BACKOFF_MAX_DELAY_MS);
+}
+function untypedRetryReason(error) {
+    const candidate = error;
+    const status = candidate?.status ?? candidate?.statusCode;
+    const message = error instanceof Error ? error.message.toLowerCase() : '';
+    if (status === 429 || message.includes('rate limit') || message.includes('too many requests')) {
+        return 'rate_limit';
+    }
+    if (status === 529 || message.includes('overloaded'))
+        return 'overloaded';
+    if (status === 503)
+        return 'unavailable';
+    return undefined;
+}
+function readRetrySignal(error, now) {
+    if (plugins.isModelLimitError(error)) {
+        const { retryAfterMs, resetsAt } = error.limit;
+        const requestedDelayMs = retryAfterMs ?? (resetsAt === undefined ? undefined : Math.max(0, resetsAt - now));
+        return { reason: 'rate_limit', ...(requestedDelayMs === undefined ? {} : { requestedDelayMs }) };
+    }
+    const reason = untypedRetryReason(error);
+    if (reason === undefined)
+        return undefined;
+    const failure = error;
+    const requestedDelayMs = plugins.readRetryAfterMs(failure.responseHeaders ?? failure.headers, now);
+    return { reason, ...(requestedDelayMs === undefined ? {} : { requestedDelayMs }) };
+}
+/** The error a rate limit fails with when its retry time lies beyond the retry bounds. */
+function overdueLimitError(error, signal, state) {
+    if (plugins.isModelLimitError(error) || signal.reason !== 'rate_limit' || signal.requestedDelayMs === undefined) {
+        return error;
+    }
+    const limit = plugins.createModelLimitInfo({ kind: 'rate_limit', provider: state.provider, retryAfterMs: signal.requestedDelayMs }, state.now);
+    // an empty or overlong provider id cannot describe a limit, so the provider's own error stays
+    return plugins.isModelLimitInfo(limit) ? new plugins.ModelLimitError(limit, { cause: error }) : error;
+}
+/**
+ * Decides whether a failed model call is retried. Usage limits never are; transient limits wait for
+ * the provider's delay up to MAX_RETRY_AFTER_MS, but never less than the backoff, and all retries of
+ * one call stay within MAX_RETRY_ATTEMPTS and MAX_RETRY_WINDOW_MS.
+ */
+export function planModelCallRetry(error, state) {
+    if (plugins.isModelLimitError(error) && error.limit.kind === 'usage_limit')
+        return { action: 'fail', error };
+    const signal = readRetrySignal(error, state.now);
+    if (signal === undefined)
+        return { action: 'not-retryable' };
+    if (state.attempt >= MAX_RETRY_ATTEMPTS)
+        return { action: 'fail', error };
+    const delayMs = Math.max(backoffDelayMs(state.attempt + 1), signal.requestedDelayMs ?? 0);
+    if (delayMs > MAX_RETRY_AFTER_MS || state.retriedMs + delayMs > MAX_RETRY_WINDOW_MS) {
+        return { action: 'fail', error: overdueLimitError(error, signal, state) };
+    }
+    return { action: 'retry', delayMs, reason: signal.reason };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5yZXRyeS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2FnZW50L3NtYXJ0YWdlbnQucmV0cnkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUE0QnhDLE1BQU0sQ0FBQyxNQUFNLGtCQUFrQixHQUFHLENBQUMsQ0FBQztBQUNwQyxxRkFBcUY7QUFDckYsTUFBTSxDQUFDLE1BQU0sa0JBQWtCLEdBQUcsTUFBTSxDQUFDO0FBQ3pDLDRGQUE0RjtBQUM1RixNQUFNLENBQUMsTUFBTSxtQkFBbUIsR0FBRyxPQUFPLENBQUM7QUFFM0MsTUFBTSxzQkFBc0IsR0FBRyxJQUFJLENBQUM7QUFDcEMsTUFBTSxvQkFBb0IsR0FBRyxDQUFDLENBQUM7QUFDL0IsTUFBTSwwQkFBMEIsR0FBRyxNQUFNLENBQUM7QUFPMUMsU0FBUyxjQUFjLENBQUMsT0FBZTtJQUNyQyxPQUFPLElBQUksQ0FBQyxHQUFHLENBQUMsc0JBQXNCLEdBQUcsb0JBQW9CLElBQUksQ0FBQyxPQUFPLEdBQUcsQ0FBQyxDQUFDLEVBQUUsMEJBQTBCLENBQUMsQ0FBQztBQUM5RyxDQUFDO0FBRUQsU0FBUyxrQkFBa0IsQ0FBQyxLQUFjO0lBQ3hDLE1BQU0sU0FBUyxHQUFHLEtBQTZELENBQUM7SUFDaEYsTUFBTSxNQUFNLEdBQUcsU0FBUyxFQUFFLE1BQU0sSUFBSSxTQUFTLEVBQUUsVUFBVSxDQUFDO0lBQzFELE1BQU0sT0FBTyxHQUFHLEtBQUssWUFBWSxLQUFLLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsV0FBVyxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztJQUMxRSxJQUFJLE1BQU0sS0FBSyxHQUFHLElBQUksT0FBTyxDQUFDLFFBQVEsQ0FBQyxZQUFZLENBQUMsSUFBSSxPQUFPLENBQUMsUUFBUSxDQUFDLG1CQUFtQixDQUFDLEVBQUUsQ0FBQztRQUM5RixPQUFP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

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.2.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.2.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
@@ -153,9 +153,69 @@ Pass these callbacks to `runAgent` or `AgentSession.create()`:
 | `onToolCallStart(event)` | `toolCallId`, `toolName`, `input`. |
 | `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.
@@ -242,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.
@@ -268,7 +328,7 @@ For generation-scoped resources, `generate({ prepare })` accepts a callback that
 
 Model transports, tools and resource callbacks must observe their supplied abort signals. Background jobs have separate lifecycles; closing a session does not automatically terminate them. Cleanup failures are observable. `closeCleanupCompleted` reports whether the session has released its retryable cleanup ownership.
 
-The runtime retries recognized transient provider failures with backoff and preserves completed tool results during a generation's retry sequence. A ledger reuses an already observed execution for the same tool-call identity. Applications still need their own idempotency and recovery rules for external side effects.
+The runtime retries a model call that failed with a rate limit (429), an overloaded provider (529) or an unavailable one (503) at most 8 times, waiting for the provider's `retry-after` delay but at least the backoff that doubles from 2 s to 30 s. A requested delay beyond 60 s, or one that would take the call's retries past 150 s in total, fails the generation: a rate limit (429) as a `ModelLimitError` of kind `rate_limit` carrying that retry time, a 503 or 529 with the provider error. A `ModelLimitError` of kind `usage_limit`, which the provider adapters raise for a spent quota, is never retried. Completed tool results are preserved during a generation's retry sequence. A ledger reuses an already observed execution for the same tool-call identity. Applications still need their own idempotency and recovery rules for external side effects.
 
 `maxSteps` defaults to `20` and limits completed model steps per generation. Prompt-cache handling defaults to `cache: 'auto'`; use `cache: false` to disable the runtime's cache defaults, or pass an explicit cache policy and a stable `sessionId` for supported provider affinity.