@modelprofile.com/flexharness-agent 8.2.0 → 8.4.0

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,
@@ -50,6 +52,8 @@ import {
   isAgentEventStoreV2,
   validateAgentEventSnapshotV2,
 } from './smartagent.persistence.js';
+import { MAX_RETRY_ATTEMPTS, planModelCallRetry } from './smartagent.retry.js';
+import { AgentModelCallUsageRecorder } from './smartagent.usage.js';
 import type {
   IAgentEventArchive,
   IAgentEventArchiveV2,
@@ -64,11 +68,6 @@ import {
   type IAgentGenerationTransaction,
 } from './smartagent.transactions.js';
 
-const RETRY_INITIAL_DELAY = 2000;
-const RETRY_BACKOFF_FACTOR = 2;
-const RETRY_MAX_DELAY = 30_000;
-const MAX_RETRY_ATTEMPTS = 8;
-
 const isTransactionalControlEvent = (event: TAgentEvent): boolean =>
   event.type === 'generation-begun'
   || event.type === 'generation-execution-started'
@@ -139,27 +138,6 @@ interface IGenerationLeaseCleanupOwnership {
 
 const sessionHydrations = new WeakMap<IAgentSessionOptions, TAgentEventSnapshot | undefined>();
 
-const retryDelay = (attempt: number, headers?: Record<string, string>): number => {
-  if (headers) {
-    const milliseconds = headers['retry-after-ms'];
-    if (milliseconds) {
-      const parsed = Number.parseFloat(milliseconds);
-      if (!Number.isNaN(parsed)) return parsed;
-    }
-    const retryAfter = headers['retry-after'];
-    if (retryAfter) {
-      const seconds = Number.parseFloat(retryAfter);
-      if (!Number.isNaN(seconds)) return Math.ceil(seconds * 1000);
-      const dateDelay = Date.parse(retryAfter) - Date.now();
-      if (!Number.isNaN(dateDelay) && dateDelay > 0) return Math.ceil(dateDelay);
-    }
-  }
-  return Math.min(
-    RETRY_INITIAL_DELAY * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1),
-    RETRY_MAX_DELAY,
-  );
-};
-
 const sleep = async (milliseconds: number, signal?: AbortSignal): Promise<void> =>
   new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -246,17 +224,6 @@ const waitWithAbort = <TValue>(
   });
 };
 
-const isRetryableError = (error: unknown): boolean => {
-  const candidate = error as { status?: number; statusCode?: number };
-  const status = candidate?.status ?? candidate?.statusCode;
-  if (status === 429 || status === 529 || status === 503) return true;
-  if (!(error instanceof Error)) return false;
-  const message = error.message.toLowerCase();
-  return message.includes('rate limit')
-    || message.includes('overloaded')
-    || message.includes('too many requests');
-};
-
 const isContextOverflow = (error: unknown): boolean => {
   if (!(error instanceof Error)) return false;
   const message = error.message.toLowerCase();
@@ -556,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 {
@@ -1201,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();
@@ -1235,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) {
@@ -1297,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]);
   }
@@ -1365,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;
@@ -1742,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]);
@@ -1848,11 +1840,27 @@ export class AgentSessionEngine implements IAgentSession {
 
       let stepCount = 0;
       let attempt = 0;
+      let retriedMs = 0;
       let contextOverflowRetries = 0;
       let totalInput = 0;
       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>();
@@ -1927,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 (
@@ -2169,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);
               }
@@ -2192,6 +2202,7 @@ export class AgentSessionEngine implements IAgentSession {
               );
               await this.flushPersistence();
               attempt = 0;
+              retriedMs = 0;
               contextOverflowRetries = 0;
             },
           });
@@ -2200,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();
 
@@ -2227,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) {
@@ -2249,17 +2264,30 @@ export class AgentSessionEngine implements IAgentSession {
             stepCount++;
           }
 
-          if (isRetryableError(effectiveError) && attempt < MAX_RETRY_ATTEMPTS && stepCount < maxSteps) {
-            attempt++;
-            const errorWithHeaders = effectiveError as {
-              responseHeaders?: Record<string, string>;
-              headers?: Record<string, string>;
-            };
-            await sleep(
-              retryDelay(attempt, errorWithHeaders.responseHeaders ?? errorWithHeaders.headers),
-              combinedAbort.signal,
-            );
-            continue;
+          const retry = stepCount < maxSteps
+            ? planModelCallRetry(effectiveError, {
+                attempt,
+                retriedMs,
+                provider: runtime.model.provider,
+                now: Date.now(),
+              })
+            : { action: 'not-retryable' as const };
+          switch (retry.action) {
+            case 'fail':
+              throw retry.error;
+            case 'retry':
+              attempt++;
+              retriedMs += retry.delayMs;
+              this.options.onRetry?.({
+                attempt,
+                maxAttempts: MAX_RETRY_ATTEMPTS,
+                delayMs: retry.delayMs,
+                reason: retry.reason,
+              });
+              await sleep(retry.delayMs, combinedAbort.signal);
+              continue;
+            case 'not-retryable':
+              break;
           }
 
           if (isContextOverflow(effectiveError)) {
@@ -2273,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,
@@ -110,6 +117,7 @@ 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/ts_agent/plugins.ts

@@ -5,6 +5,7 @@ export { streamText, generateText, stepCountIs, wrapLanguageModel };
 
 export type {
   AssistantModelMessage,
+  LanguageModelUsage,
   ModelMessage,
   StepResult,
   SystemModelMessage,
@@ -18,15 +19,25 @@ export type {
 // model contracts and AI SDK
 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,

package/ts_agent/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.
 

package/ts_agent/runner.ts

@@ -37,4 +37,11 @@ export function runAgent(options: IAgentRunOptions): Promise<IAgentRunResult> {
   return runAgentWithSession(options, (sessionOptions) => RunnerSession.create(sessionOptions));
 }
 
-export type { IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';
+export type {
+  IAgentRunOptions,
+  IAgentRunResult,
+  IAgentUsage,
+  TAgentModelCallUnreportedReason,
+  TAgentModelCallUsage,
+  TAgentModelCallUsageEvent,
+} from './smartagent.interfaces.js';

package/ts_agent/runtime.run.ts

@@ -51,6 +51,8 @@ export async function runAgentWithSession(
     onToolCallStart: options.onToolCallStart,
     onToolCallUpdate: options.onToolCallUpdate,
     onToolCallFinish: options.onToolCallFinish,
+    onRetry: options.onRetry,
+    onUsage: options.onUsage,
     onToolCall: options.onToolCall,
     onToolResult: options.onToolResult,
     onContextOverflow: options.onContextOverflow,

package/ts_agent/smartagent.interfaces.ts

@@ -17,6 +17,7 @@ import type {
   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 {}
@@ -53,8 +54,69 @@ export type TAgentToolCallFinishEvent =
       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 {
@@ -68,6 +130,12 @@ export type TAgentContextBuilder = (
 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 = (
@@ -150,6 +218,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. */
@@ -300,14 +380,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[];
 }