@modelprofile.com/flexharness 8.3.0 → 8.4.0

package/dist_ts/interfaces.d.ts

@@ -17,6 +17,12 @@ export type TFlexAgentToolCallFinishEvent = Parameters<NonNullable<TFlexAgentSes
 /** A usage or rate limit a model provider reported; `resetsAt` is in epoch milliseconds. */
 export type TFlexModelLimit = plugins.IModelLimitInfo;
 export type TFlexRetryReason = plugins.TAgentRetryReason;
+/**
+ * The usage outcome of one model call: `reported` with the provider's `usage` and
+ * `responseModelId`, or `unreported` with a `reason` (`aborted`, `failed` or `missing`).
+ * Every call carries `provider` and `requestedModelId`; key usage caps on those two.
+ */
+export type TFlexModelCallUsage = plugins.TAgentModelCallUsage;
 export interface IFlexTextPromptPart {
     type: 'text';
     text: string;
@@ -95,6 +101,11 @@ export interface IFlexMessage {
     completedAt?: string;
     parts: TFlexMessagePart[];
     model?: IFlexModelIdentity;
+    /**
+     * On a terminal assistant message: the usage the provider reported for the run's model calls.
+     * For a failed or cancelled run it is a lower bound when a `model.usage` event of the run was
+     * `unreported`.
+     */
     usage?: IFlexUsage;
     error?: string;
     /** The model limit that failed this run, next to its error. */
@@ -356,6 +367,7 @@ export interface IFlexTerminalProjection {
     userMessage: IFlexMessage;
     assistantMessage: IFlexMessage;
     model?: IFlexModelIdentity;
+    /** The usage the provider reported for the run's model calls, whatever the status. */
     usage?: IFlexUsage;
     finishReason?: string;
     steps?: number;
@@ -933,6 +945,17 @@ export interface IFlexRunRetryingEvent extends IFlexEventBase {
     readonly delayMs: number;
     readonly reason: TFlexRetryReason;
 }
+/**
+ * The usage outcome of one model call of a session, emitted once per call whatever the run's
+ * outcome. `source: 'generation'` is a model step of the run `runId`. `source: 'compaction'` is a
+ * model call of a context compaction the context compactor reported; `runId` names the run whose
+ * context overflow caused it and is absent for `compactSession()` and event retention.
+ */
+export type TFlexModelUsageEvent = IFlexEventBase & {
+    readonly type: 'model.usage';
+    readonly runId?: string;
+    readonly source: 'generation' | 'compaction';
+} & Readonly<TFlexModelCallUsage>;
 export interface IFlexPromptQueueEvent extends IFlexEventBase {
     readonly type: 'prompt.queued' | 'prompt.started' | 'prompt.running' | 'prompt.finished';
     readonly queueId: string;
@@ -951,6 +974,6 @@ export interface IFlexErrorInfo {
     /** Set when a model usage or rate limit caused the error. */
     limit?: TFlexModelLimit;
 }
-export type TFlexHarnessEvent = IFlexSessionCreatedEvent | IFlexSessionUpdatedEvent | IFlexSessionDeletedEvent | IFlexRunStartedEvent | IFlexMessageChangedEvent | TFlexPartEvent | IFlexPermissionRequestedEvent | IFlexPermissionResolvedEvent | IFlexRunFinishedEvent | IFlexRunRetryingEvent | IFlexPromptQueueEvent | IFlexSessionHistoryChangedEvent;
+export type TFlexHarnessEvent = IFlexSessionCreatedEvent | IFlexSessionUpdatedEvent | IFlexSessionDeletedEvent | IFlexRunStartedEvent | IFlexMessageChangedEvent | TFlexPartEvent | IFlexPermissionRequestedEvent | IFlexPermissionResolvedEvent | IFlexRunFinishedEvent | IFlexRunRetryingEvent | TFlexModelUsageEvent | IFlexPromptQueueEvent | IFlexSessionHistoryChangedEvent;
 export type TFlexHarnessEventListener = (event: TFlexHarnessEvent) => void;
 export {};

package/dist_ts/interfaces.js

@@ -27,4 +27,4 @@ export const FLEX_REVERSION_MAX_AFFECTED_WORKSPACES = 64;
 export const FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES = 512;
 export const FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES = 2048;
 export const FLEX_REVERSION_REASON_CODE_MAX_BYTES = 128;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2ludGVyZmFjZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBdWtCQSxNQUFNLENBQUMsTUFBTSxzQ0FBc0MsR0FBRyxDQUFVLENBQUM7QUFDakUsTUFBTSxDQUFDLE1BQU0sb0NBQW9DLEdBQUcsR0FBRyxDQUFDO0FBQ3hELE1BQU0sQ0FBQyxNQUFNLDBDQUEwQyxHQUFHLElBQUksQ0FBQztBQStCL0QsTUFBTSxDQUFDLE1BQU0sOEJBQThCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUMxRCxZQUFZLEVBQUUsQ0FBQyxHQUFHLElBQUk7SUFDdEIsa0JBQWtCLEVBQUUsR0FBRyxHQUFHLElBQUk7SUFDOUIsbUJBQW1CLEVBQUUsQ0FBQyxHQUFHLElBQUk7SUFDN0IsY0FBYyxFQUFFLEdBQUc7SUFDbkIsUUFBUSxFQUFFLEdBQUc7SUFDYixhQUFhLEVBQUUsSUFBSTtJQUNuQixnQkFBZ0IsRUFBRSxJQUFJLEdBQUcsSUFBSTtDQUM5QixDQUFDLENBQUM7QUErTEgsTUFBTSxDQUFDLE1BQU0sNkJBQTZCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUN6RCxpQkFBaUIsRUFBRSxHQUFHO0lBQ3RCLFdBQVcsRUFBRSxHQUFHO0lBQ2hCLGlCQUFpQixFQUFFLElBQUk7SUFDdkIsMkJBQTJCLEVBQUUsSUFBSTtDQUNsQyxDQUFDLENBQUM7QUFFSCxNQUFNLENBQUMsTUFBTSw2QkFBNkIsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ3pELGlCQUFpQixFQUFFLElBQUk7SUFDdkIsV0FBVyxFQUFFLElBQUk7SUFDakIsaUJBQWlCLEVBQUUsTUFBTTtJQUN6QiwyQkFBMkIsRUFBRSxNQUFNO0NBQ3BDLENBQUMsQ0FBQztBQUVILE1BQU0sQ0FBQyxNQUFNLGtDQUFrQyxHQUFHLEdBQUcsR0FBRyxJQUFJLENBQUM7QUFDN0QsTUFBTSxDQUFDLE1BQU0sc0NBQXNDLEdBQUcsRUFBRSxDQUFDO0FBQ3pELE1BQU0sQ0FBQyxNQUFNLHFDQUFxQyxHQUFHLEdBQUcsQ0FBQztBQUN6RCxNQUFNLENBQUMsTUFBTSx3Q0FBd0MsR0FBRyxJQUFJLENBQUM7QUFDN0QsTUFBTSxDQUFDLE1BQU0sb0NBQW9DLEdBQUcsR0FBRyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2ludGVyZmFjZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBbWxCQSxNQUFNLENBQUMsTUFBTSxzQ0FBc0MsR0FBRyxDQUFVLENBQUM7QUFDakUsTUFBTSxDQUFDLE1BQU0sb0NBQW9DLEdBQUcsR0FBRyxDQUFDO0FBQ3hELE1BQU0sQ0FBQyxNQUFNLDBDQUEwQyxHQUFHLElBQUksQ0FBQztBQStCL0QsTUFBTSxDQUFDLE1BQU0sOEJBQThCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUMxRCxZQUFZLEVBQUUsQ0FBQyxHQUFHLElBQUk7SUFDdEIsa0JBQWtCLEVBQUUsR0FBRyxHQUFHLElBQUk7SUFDOUIsbUJBQW1CLEVBQUUsQ0FBQyxHQUFHLElBQUk7SUFDN0IsY0FBYyxFQUFFLEdBQUc7SUFDbkIsUUFBUSxFQUFFLEdBQUc7SUFDYixhQUFhLEVBQUUsSUFBSTtJQUNuQixnQkFBZ0IsRUFBRSxJQUFJLEdBQUcsSUFBSTtDQUM5QixDQUFDLENBQUM7QUErTEgsTUFBTSxDQUFDLE1BQU0sNkJBQTZCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUN6RCxpQkFBaUIsRUFBRSxHQUFHO0lBQ3RCLFdBQVcsRUFBRSxHQUFHO0lBQ2hCLGlCQUFpQixFQUFFLElBQUk7SUFDdkIsMkJBQTJCLEVBQUUsSUFBSTtDQUNsQyxDQUFDLENBQUM7QUFFSCxNQUFNLENBQUMsTUFBTSw2QkFBNkIsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ3pELGlCQUFpQixFQUFFLElBQUk7SUFDdkIsV0FBVyxFQUFFLElBQUk7SUFDakIsaUJBQWlCLEVBQUUsTUFBTTtJQUN6QiwyQkFBMkIsRUFBRSxNQUFNO0NBQ3BDLENBQUMsQ0FBQztBQUVILE1BQU0sQ0FBQyxNQUFNLGtDQUFrQyxHQUFHLEdBQUcsR0FBRyxJQUFJLENBQUM7QUFDN0QsTUFBTSxDQUFDLE1BQU0sc0NBQXNDLEdBQUcsRUFBRSxDQUFDO0FBQ3pELE1BQU0sQ0FBQyxNQUFNLHFDQUFxQyxHQUFHLEdBQUcsQ0FBQztBQUN6RCxNQUFNLENBQUMsTUFBTSx3Q0FBd0MsR0FBRyxJQUFJLENBQUM7QUFDN0QsTUFBTSxDQUFDLE1BQU0sb0NBQW9DLEdBQUcsR0FBRyxDQUFDIn0=

package/dist_ts/plugins.d.ts

@@ -5,7 +5,7 @@ import * as path from 'node:path';
 export { AsyncLocalStorage, crypto, fs, path };
 import { AgentEventStoreConflictError, AgentSession, buildModelMessages, ToolJobStoreConflictError, createAgentEvent, filterModelVisibleAgentEvents, getAgentGenerationTransactions, modelMessagesToAgentEvents, tool, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, z } from '@modelprofile.com/flexharness-agent';
 export { AgentEventStoreConflictError, AgentSession, buildModelMessages, ToolJobStoreConflictError, createAgentEvent, filterModelVisibleAgentEvents, getAgentGenerationTransactions, modelMessagesToAgentEvents, tool, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, z, };
-export type { IAgentEventArchiveV2, IAgentContextCompactionOptions, IAgentEventSnapshotV2, IAgentEventStoreV2, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentRetryEvent, IAgentRunResult, IAgentSession, IAgentSessionOptions, IAgentToolCallUpdateEvent, IAgentRuntimeEventPayload, IGenerationBegunEvent, IGenerationExecutionCompletedEvent, IGenerationExecutionStartedEvent, IGenerationOutcomeEvent, IToolExecutionContext, IToolExecutionIntentEvent, IToolJobSnapshot, IToolJobState, IToolJobStore, TAgentContextBuilder, TAgentContextCompactor, TAgentEvent, TAgentGenerationOutcome, TAgentRetryReason, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from '@modelprofile.com/flexharness-agent';
+export type { IAgentEventArchiveV2, IAgentContextCompactionOptions, IAgentEventSnapshotV2, IAgentEventStoreV2, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentRetryEvent, IAgentRunResult, IAgentSession, IAgentSessionOptions, IAgentToolCallUpdateEvent, IAgentRuntimeEventPayload, IGenerationBegunEvent, IGenerationExecutionCompletedEvent, IGenerationExecutionStartedEvent, IGenerationOutcomeEvent, IToolExecutionContext, IToolExecutionIntentEvent, IToolJobSnapshot, IToolJobState, IToolJobStore, TAgentContextBuilder, TAgentContextCompactor, TAgentEvent, TAgentGenerationOutcome, TAgentModelCallUsage, TAgentModelCallUsageEvent, TAgentRetryReason, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from '@modelprofile.com/flexharness-agent';
 import { isModelLimitError, isModelLimitInfo } from '@modelprofile.com/flexharness-models';
 export { isModelLimitError, isModelLimitInfo };
 export type { IModelLimitInfo } from '@modelprofile.com/flexharness-models';

package/dist_ts/plugins.js

@@ -9,4 +9,4 @@ import { AgentEventStoreConflictError, AgentSession, buildModelMessages, ToolJob
 export { AgentEventStoreConflictError, AgentSession, buildModelMessages, ToolJobStoreConflictError, createAgentEvent, filterModelVisibleAgentEvents, getAgentGenerationTransactions, modelMessagesToAgentEvents, tool, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, z, };
 import { isModelLimitError, isModelLimitInfo } from '@modelprofile.com/flexharness-models';
 export { isModelLimitError, isModelLimitInfo };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ3JELE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDdkMsT0FBTyxLQUFLLElBQUksTUFBTSxXQUFXLENBQUM7QUFFbEMsT0FBTyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsSUFBSSxFQUFFLENBQUM7QUFFL0Msb0JBQW9CO0FBQ3BCLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDZCQUE2QixFQUM3Qiw4QkFBOEIsRUFDOUIsMEJBQTBCLEVBQzFCLElBQUksRUFDSiwyQkFBMkIsRUFDM0IsNEJBQTRCLEVBQzVCLENBQUMsR0FDRixNQUFNLHFDQUFxQyxDQUFDO0FBRTdDLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDZCQUE2QixFQUM3Qiw4QkFBOEIsRUFDOUIsMEJBQTBCLEVBQzFCLElBQUksRUFDSiwyQkFBMkIsRUFDM0IsNEJBQTRCLEVBQzVCLENBQUMsR0FDRixDQUFDO0FBaUNGLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBRTNGLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxnQkFBZ0IsRUFBRSxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ3JELE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDdkMsT0FBTyxLQUFLLElBQUksTUFBTSxXQUFXLENBQUM7QUFFbEMsT0FBTyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsSUFBSSxFQUFFLENBQUM7QUFFL0Msb0JBQW9CO0FBQ3BCLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDZCQUE2QixFQUM3Qiw4QkFBOEIsRUFDOUIsMEJBQTBCLEVBQzFCLElBQUksRUFDSiwyQkFBMkIsRUFDM0IsNEJBQTRCLEVBQzVCLENBQUMsR0FDRixNQUFNLHFDQUFxQyxDQUFDO0FBRTdDLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDZCQUE2QixFQUM3Qiw4QkFBOEIsRUFDOUIsMEJBQTBCLEVBQzFCLElBQUksRUFDSiwyQkFBMkIsRUFDM0IsNEJBQTRCLEVBQzVCLENBQUMsR0FDRixDQUFDO0FBbUNGLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBRTNGLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxnQkFBZ0IsRUFBRSxDQUFDIn0=

package/dist_ts_compaction/plugins.d.ts

@@ -1,4 +1,7 @@
-import { generateText } from 'ai';
-export { generateText };
+import { generateText, wrapLanguageModel } from 'ai';
+export { generateText, wrapLanguageModel };
 export type { ModelMessage } from 'ai';
 export type { TSmartAiLanguageModel } from '@modelprofile.com/flexharness-models';
+import { AgentModelCallUsageRecorder } from '@modelprofile.com/flexharness-agent';
+export { AgentModelCallUsageRecorder };
+export type { TAgentModelCallUsageReporter } from '@modelprofile.com/flexharness-agent';

package/dist_ts_compaction/plugins.js

@@ -1,3 +1,5 @@
-import { generateText } from 'ai';
-export { generateText };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2NvbXBhY3Rpb24vcGx1Z2lucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBRWxDLE9BQU8sRUFBRSxZQUFZLEVBQUUsQ0FBQyJ9
+import { generateText, wrapLanguageModel } from 'ai';
+export { generateText, wrapLanguageModel };
+import { AgentModelCallUsageRecorder } from '@modelprofile.com/flexharness-agent';
+export { AgentModelCallUsageRecorder };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2NvbXBhY3Rpb24vcGx1Z2lucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsWUFBWSxFQUFFLGlCQUFpQixFQUFFLE1BQU0sSUFBSSxDQUFDO0FBRXJELE9BQU8sRUFBRSxZQUFZLEVBQUUsaUJBQWlCLEVBQUUsQ0FBQztBQUszQyxPQUFPLEVBQUUsMkJBQTJCLEVBQUUsTUFBTSxxQ0FBcUMsQ0FBQztBQUVsRixPQUFPLEVBQUUsMkJBQTJCLEVBQUUsQ0FBQyJ9

package/dist_ts_compaction/smartagent.compaction.d.ts

@@ -1,6 +1,13 @@
 import * as plugins from './plugins.js';
 export interface ICompactMessagesOptions {
     abortSignal?: AbortSignal;
+    /**
+     * Receives the usage of every model call the compaction makes, once per call: `reported` with the
+     * provider's usage, or `unreported` for a call that failed or was aborted, retried attempts
+     * included. A context compactor passes its own options through, so the calls reach the session's
+     * `onUsage`. Must not throw.
+     */
+    reportUsage?: plugins.TAgentModelCallUsageReporter;
 }
 /**
  * Compacts a message history into a summary.
@@ -8,7 +15,7 @@ export interface ICompactMessagesOptions {
  *
  * @param model    The same model used by runAgent, or a cheaper small model
  * @param messages The full message history that overflowed
- * @param options  Invocation options, including cancellation
+ * @param options  Invocation options, including cancellation and usage reporting
  * @returns A minimal ModelMessage[] containing the summary as context
  */
 export declare function compactMessages(model: plugins.TSmartAiLanguageModel, messages: plugins.ModelMessage[], options?: ICompactMessagesOptions): Promise<plugins.ModelMessage[]>;

package/dist_ts_compaction/smartagent.compaction.js

@@ -26,24 +26,66 @@ When constructing the summary, try to stick to this template:
  *
  * @param model    The same model used by runAgent, or a cheaper small model
  * @param messages The full message history that overflowed
- * @param options  Invocation options, including cancellation
+ * @param options  Invocation options, including cancellation and usage reporting
  * @returns A minimal ModelMessage[] containing the summary as context
  */
 export async function compactMessages(model, messages, options = {}) {
-    const result = await plugins.generateText({
+    const prompt = [
+        ...messages,
+        { role: 'user', content: COMPACTION_PROMPT },
+    ];
+    const reportUsage = options.reportUsage;
+    if (!reportUsage) {
+        const result = await plugins.generateText({
+            model,
+            abortSignal: options.abortSignal,
+            allowSystemInMessages: true,
+            messages: prompt,
+        });
+        return summaryMessages(result.text);
+    }
+    const modelCalls = new plugins.AgentModelCallUsageRecorder(model, reportUsage);
+    // Each attempt, retries included, is one model call: it starts in the middleware, which also
+    // settles an attempt that throws; a call whose response arrives ends in onLanguageModelCallEnd.
+    const observedModel = plugins.wrapLanguageModel({
         model,
-        abortSignal: options.abortSignal,
-        allowSystemInMessages: true,
-        messages: [
-            ...messages,
-            { role: 'user', content: COMPACTION_PROMPT },
-        ],
+        middleware: {
+            wrapGenerate: async ({ doGenerate, params }) => {
+                modelCalls.start();
+                try {
+                    return await doGenerate();
+                }
+                catch (error) {
+                    modelCalls.settle(params.abortSignal?.aborted ? 'aborted' : 'failed');
+                    throw error;
+                }
+            },
+        },
     });
+    try {
+        const result = await plugins.generateText({
+            model: observedModel,
+            abortSignal: options.abortSignal,
+            allowSystemInMessages: true,
+            messages: prompt,
+            onLanguageModelCallEnd: ({ modelId, usage }) => {
+                modelCalls.end(modelId, usage);
+            },
+        });
+        modelCalls.settle('missing');
+        return summaryMessages(result.text);
+    }
+    catch (error) {
+        modelCalls.settle(options.abortSignal?.aborted ? 'aborted' : 'failed');
+        throw error;
+    }
+}
+function summaryMessages(summary) {
     return [
         {
             role: 'user',
-            content: `[Previous conversation summary]\n\n${result.text}\n\n[End of summary. Continue from here.]`,
+            content: `[Previous conversation summary]\n\n${summary}\n\n[End of summary. Continue from here.]`,
         },
     ];
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5jb21wYWN0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfY29tcGFjdGlvbi9zbWFydGFnZW50LmNvbXBhY3Rpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFFeEMsTUFBTSxpQkFBaUIsR0FBRzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7SUFvQnRCLENBQUM7QUFNTDs7Ozs7Ozs7R0FRRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsZUFBZSxDQUNuQyxLQUFvQyxFQUNwQyxRQUFnQyxFQUNoQyxVQUFtQyxFQUFFO0lBRXJDLE1BQU0sTUFBTSxHQUFHLE1BQU0sT0FBTyxDQUFDLFlBQVksQ0FBQztRQUN4QyxLQUFLO1FBQ0wsV0FBVyxFQUFFLE9BQU8sQ0FBQyxXQUFXO1FBQ2hDLHFCQUFxQixFQUFFLElBQUk7UUFDM0IsUUFBUSxFQUFFO1lBQ1IsR0FBRyxRQUFRO1lBQ1gsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLE9BQU8sRUFBRSxpQkFBaUIsRUFBRTtTQUM3QztLQUNGLENBQUMsQ0FBQztJQUVILE9BQU87UUFDTDtZQUNFLElBQUksRUFBRSxNQUFNO1lBQ1osT0FBTyxFQUFFLHNDQUFzQyxNQUFNLENBQUMsSUFBSSwyQ0FBMkM7U0FDdEc7S0FDRixDQUFDO0FBQ0osQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5jb21wYWN0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfY29tcGFjdGlvbi9zbWFydGFnZW50LmNvbXBhY3Rpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFFeEMsTUFBTSxpQkFBaUIsR0FBRzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7SUFvQnRCLENBQUM7QUFhTDs7Ozs7Ozs7R0FRRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsZUFBZSxDQUNuQyxLQUFvQyxFQUNwQyxRQUFnQyxFQUNoQyxVQUFtQyxFQUFFO0lBRXJDLE1BQU0sTUFBTSxHQUEyQjtRQUNyQyxHQUFHLFFBQVE7UUFDWCxFQUFFLElBQUksRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLGlCQUFpQixFQUFFO0tBQzdDLENBQUM7SUFDRixNQUFNLFdBQVcsR0FBRyxPQUFPLENBQUMsV0FBVyxDQUFDO0lBQ3hDLElBQUksQ0FBQyxXQUFXLEVBQUUsQ0FBQztRQUNqQixNQUFNLE1BQU0sR0FBRyxNQUFNLE9BQU8sQ0FBQyxZQUFZLENBQUM7WUFDeEMsS0FBSztZQUNMLFdBQVcsRUFBRSxPQUFPLENBQUMsV0FBVztZQUNoQyxxQkFBcUIsRUFBRSxJQUFJO1lBQzNCLFFBQVEsRUFBRSxNQUFNO1NBQ2pCLENBQUMsQ0FBQztRQUNILE9BQU8sZUFBZSxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUN0QyxDQUFDO0lBQ0QsTUFBTSxVQUFVLEdBQUcsSUFBSSxPQUFPLENBQUMsMkJBQTJCLENBQUMsS0FBSyxFQUFFLFdBQVcsQ0FBQyxDQUFDO0lBQy9FLDZGQUE2RjtJQUM3RixnR0FBZ0c7SUFDaEcsTUFBTSxhQUFhLEdBQUcsT0FBTyxDQUFDLGlCQUFpQixDQUFDO1FBQzlDLEtBQUs7UUFDTCxVQUFVLEVBQUU7WUFDVixZQUFZLEVBQUUsS0FBSyxFQUFFLEVBQUUsVUFBVSxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUU7Z0JBQzdDLFVBQVUsQ0FBQyxLQUFLLEVBQUUsQ0FBQztnQkFDbkIsSUFBSSxDQUFDO29CQUNILE9BQU8sTUFBTSxVQUFVLEVBQUUsQ0FBQztnQkFDNUIsQ0FBQztnQkFBQyxPQUFPLEtBQUssRUFBRSxDQUFDO29CQUNmLFVBQVUsQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLFdBQVcsRUFBRSxPQUFPLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsUUFBUSxDQUFDLENBQUM7b0JBQ3RFLE1BQU0sS0FBSyxDQUFDO2dCQUNkLENBQUM7WUFDSCxDQUFDO1NBQ0Y7S0FDRixDQUFDLENBQUM7SUFDSCxJQUFJLENBQUM7UUFDSCxNQUFNLE1BQU0sR0FBRyxNQUFNLE9BQU8sQ0FBQyxZQUFZLENBQUM7WUFDeEMsS0FBSyxFQUFFLGFBQWE7WUFDcEIsV0FBVyxFQUFFLE9BQU8sQ0FBQyxXQUFXO1lBQ2hDLHFCQUFxQixFQUFFLElBQUk7WUFDM0IsUUFBUSxFQUFFLE1BQU07WUFDaEIsc0JBQXNCLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxLQUFLLEVBQUUsRUFBRSxFQUFFO2dCQUM3QyxVQUFVLENBQUMsR0FBRyxDQUFDLE9BQU8sRUFBRSxLQUFLLENBQUMsQ0FBQztZQUNqQyxDQUFDO1NBQ0YsQ0FBQyxDQUFDO1FBQ0gsVUFBVSxDQUFDLE1BQU0sQ0FBQyxTQUFTLENBQUMsQ0FBQztRQUM3QixPQUFPLGVBQWUsQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLENBQUM7SUFDdEMsQ0FBQztJQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7UUFDZixVQUFVLENBQUMsTUFBTSxDQUFDLE9BQU8sQ0FBQyxXQUFXLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQ3ZFLE1BQU0sS0FBSyxDQUFDO0lBQ2QsQ0FBQztBQUNILENBQUM7QUFFRCxTQUFTLGVBQWUsQ0FBQyxPQUFlO0lBQ3RDLE9BQU87UUFDTDtZQUNFLElBQUksRUFBRSxNQUFNO1lBQ1osT0FBTyxFQUFFLHNDQUFzQyxPQUFPLDJDQUEyQztTQUNsRztLQUNGLENBQUM7QUFDSixDQUFDIn0=

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "type": "module",
   "description": "Managed agent sessions with tools, MCP, chat, OCR, documents and browser control through focused subpath imports.",
   "main": "./dist_ts/index.js",
@@ -62,8 +62,8 @@
     }
   },
   "dependencies": {
-    "@modelprofile.com/flexharness-agent": "8.3.0",
-    "@modelprofile.com/flexharness-models": "8.3.0",
+    "@modelprofile.com/flexharness-agent": "8.4.0",
+    "@modelprofile.com/flexharness-models": "8.4.0",
     "@push.rocks/smartrequest": "^5.0.1",
     "ai": "^7.0.79",
     "zod": "^4.4.1"

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '8.3.0',
+  version: '8.4.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }

package/ts/classes.flexharness.ts

@@ -99,6 +99,7 @@ import type {
   IFlexUndoSessionResult,
   IFlexUpdateSessionOptions,
   IFlexUpdateProjectTaskInput,
+  IFlexUsage,
   IJsonObject,
   TFlexAgentToolCallUpdateEvent,
   TFlexAgentToolCallFinishEvent,
@@ -337,6 +338,8 @@ interface IActiveRun {
   callbackParts: TFlexMessagePart[];
   partTextUtf8Bytes: Map<string, number>;
   callbacksClosed: boolean;
+  /** The usage the provider reported for the run's model calls so far. */
+  usage: IFlexUsage;
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
   trustedToolExecutionErrors: Map<string, Error>;
@@ -3396,6 +3399,13 @@ export class FlexHarness<TScope = unknown> {
       callbackParts: [],
       partTextUtf8Bytes: new Map(),
       callbacksClosed: false,
+      usage: {
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+      },
       reasoningPartIds: new Map(),
       toolPartIds: new Map(),
       trustedToolExecutionErrors: new Map(),
@@ -3957,6 +3967,8 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<IFlexPromptResult> {
     let generated = false;
     try {
+      // The transactional generation settles only after its model calls are reported, so
+      // `run.usage` is complete once it settles, also for a cancelled run.
       const rawResult = await generation;
       generated = true;
       if (run.callbackError) throw run.callbackError;
@@ -5686,6 +5698,7 @@ export class FlexHarness<TScope = unknown> {
       }
       assistantMessage.usage = cloneSerializable(result.usage);
     } else {
+      assistantMessage.usage = cloneSerializable(run.usage);
       const message = truncateUtf8(error?.message ?? externalErrorFallback.message, maxTransferMetadataBytes);
       const limit = error instanceof FlexHarnessExternalError ? error.limit : undefined;
       for (const failedMessage of [userMessage, assistantMessage]) {
@@ -5705,7 +5718,7 @@ export class FlexHarness<TScope = unknown> {
             finishReason: result.finishReason,
             steps: result.steps,
           }
-        : {}),
+        : { usage: cloneSerializable(run.usage) }),
     };
   }
 
@@ -7051,6 +7064,50 @@ export class FlexHarness<TScope = unknown> {
     });
   }
 
+  /**
+   * Emits the usage of every model call and adds reported usage to its run. A run executes a
+   * transactional generation, and `AgentSession.generate()` settles a transactional generation only
+   * after it has reported each of its model calls, also when it is aborted. `executeRun()` awaits
+   * that settlement before it builds the terminal, so the run is still active for each of its
+   * events: they all reach `run.usage` and precede its `run.finished`. The events bypass the
+   * callback limits and a failed callback: their number is bounded by the run's model calls, and
+   * the usage of a run that exhausted its callback budget or failed in a callback must not be lost.
+   */
+  private onModelCallUsage(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    event: plugins.TAgentModelCallUsageEvent,
+  ): void {
+    const { source, generationId, ...call } = event;
+    const sessionId = stored.session.sessionId;
+    const activeRun = state.activeRuns.get(sessionId);
+    const run = generationId !== undefined && activeRun?.runId === generationId ? activeRun : undefined;
+    let scopeId = run?.scopeId;
+    if (scopeId === undefined) {
+      const ambientContext = this.compactorInvocationContext.getStore();
+      const invocationContext = ambientContext
+        ? this.deferredCompactorContexts.get(ambientContext) ?? ambientContext
+        : undefined;
+      if (
+        !invocationContext
+        || invocationContext.storageKey !== state.storageKey
+        || invocationContext.sessionId !== sessionId
+      ) {
+        throw new Error('Model call usage is missing its exact FlexHarness invocation context.');
+      }
+      scopeId = invocationContext.scopeId;
+    }
+    if (run && call.status === 'reported') {
+      for (const key of Object.keys(run.usage) as (keyof IFlexUsage)[]) run.usage[key] += call.usage[key];
+    }
+    this.emitEvent(scopeId, stored.session, {
+      type: 'model.usage',
+      ...(generationId === undefined ? {} : { runId: generationId }),
+      source,
+      ...call,
+    });
+  }
+
   private callbackRun(state: IStorageState, sessionId: string): IActiveRun | undefined {
     const run = state.activeRuns.get(sessionId);
     return !run || run.callbacksClosed || run.callbackError ? undefined : run;
@@ -8261,6 +8318,7 @@ export class FlexHarness<TScope = unknown> {
         onToolCallUpdate: (event) => this.onToolUpdate(state, sessionId, event),
         onToolCallFinish: (event) => this.onToolFinish(state, sessionId, event),
         onRetry: (event) => this.onRetry(state, sessionId, event),
+        onUsage: (event) => this.onModelCallUsage(state, stored, event),
       };
       stored.agentSession = await this.withCompactorContext(
         compactorContext,
@@ -8516,7 +8574,11 @@ export class FlexHarness<TScope = unknown> {
       const message = status === 'cancelled' ? repairCancellationMessage : externalErrorFallback.message;
       userMessage.error = message;
       assistantMessage.error = message;
-      delete assistantMessage.usage;
+      if (stage?.usage) {
+        assistantMessage.usage = cloneSerializable(stage.usage);
+      } else {
+        delete assistantMessage.usage;
+      }
     }
     return {
       runId,
@@ -8524,7 +8586,7 @@ export class FlexHarness<TScope = unknown> {
       userMessage,
       assistantMessage,
       ...(status === 'completed' && stage?.model ? { model: stage.model } : {}),
-      ...(status === 'completed' && stage?.usage ? { usage: stage.usage } : {}),
+      ...(stage?.usage ? { usage: stage.usage } : {}),
       ...(status === 'completed' && stage?.finishReason ? { finishReason: stage.finishReason } : {}),
       ...(status === 'completed' && stage?.steps !== undefined ? { steps: stage.steps } : {}),
     };

package/ts/interfaces.ts

@@ -25,6 +25,12 @@ export type TFlexAgentToolCallFinishEvent = Parameters<
 /** A usage or rate limit a model provider reported; `resetsAt` is in epoch milliseconds. */
 export type TFlexModelLimit = plugins.IModelLimitInfo;
 export type TFlexRetryReason = plugins.TAgentRetryReason;
+/**
+ * The usage outcome of one model call: `reported` with the provider's `usage` and
+ * `responseModelId`, or `unreported` with a `reason` (`aborted`, `failed` or `missing`).
+ * Every call carries `provider` and `requestedModelId`; key usage caps on those two.
+ */
+export type TFlexModelCallUsage = plugins.TAgentModelCallUsage;
 
 export interface IFlexTextPromptPart {
   type: 'text';
@@ -126,6 +132,11 @@ export interface IFlexMessage {
   completedAt?: string;
   parts: TFlexMessagePart[];
   model?: IFlexModelIdentity;
+  /**
+   * On a terminal assistant message: the usage the provider reported for the run's model calls.
+   * For a failed or cancelled run it is a lower bound when a `model.usage` event of the run was
+   * `unreported`.
+   */
   usage?: IFlexUsage;
   error?: string;
   /** The model limit that failed this run, next to its error. */
@@ -464,6 +475,7 @@ export interface IFlexTerminalProjection {
   userMessage: IFlexMessage;
   assistantMessage: IFlexMessage;
   model?: IFlexModelIdentity;
+  /** The usage the provider reported for the run's model calls, whatever the status. */
   usage?: IFlexUsage;
   finishReason?: string;
   steps?: number;
@@ -1244,6 +1256,18 @@ export interface IFlexRunRetryingEvent extends IFlexEventBase {
   readonly reason: TFlexRetryReason;
 }
 
+/**
+ * The usage outcome of one model call of a session, emitted once per call whatever the run's
+ * outcome. `source: 'generation'` is a model step of the run `runId`. `source: 'compaction'` is a
+ * model call of a context compaction the context compactor reported; `runId` names the run whose
+ * context overflow caused it and is absent for `compactSession()` and event retention.
+ */
+export type TFlexModelUsageEvent = IFlexEventBase & {
+  readonly type: 'model.usage';
+  readonly runId?: string;
+  readonly source: 'generation' | 'compaction';
+} & Readonly<TFlexModelCallUsage>;
+
 export interface IFlexPromptQueueEvent extends IFlexEventBase {
   readonly type: 'prompt.queued' | 'prompt.started' | 'prompt.running' | 'prompt.finished';
   readonly queueId: string;
@@ -1276,6 +1300,7 @@ export type TFlexHarnessEvent =
   | IFlexPermissionResolvedEvent
   | IFlexRunFinishedEvent
   | IFlexRunRetryingEvent
+  | TFlexModelUsageEvent
   | IFlexPromptQueueEvent
   | IFlexSessionHistoryChangedEvent;
 

package/ts/plugins.ts

@@ -63,6 +63,8 @@ export type {
   TAgentContextCompactor,
   TAgentEvent,
   TAgentGenerationOutcome,
+  TAgentModelCallUsage,
+  TAgentModelCallUsageEvent,
   TAgentRetryReason,
   TAgentToolCallFinishEvent,
   TAgentToolExecutionReconciliationOptions,

package/ts_compaction/plugins.ts

@@ -1,6 +1,12 @@
-import { generateText } from 'ai';
+import { generateText, wrapLanguageModel } from 'ai';
 
-export { generateText };
+export { generateText, wrapLanguageModel };
 
 export type { ModelMessage } from 'ai';
 export type { TSmartAiLanguageModel } from '@modelprofile.com/flexharness-models';
+
+import { AgentModelCallUsageRecorder } from '@modelprofile.com/flexharness-agent';
+
+export { AgentModelCallUsageRecorder };
+
+export type { TAgentModelCallUsageReporter } from '@modelprofile.com/flexharness-agent';

package/ts_compaction/smartagent.compaction.ts

@@ -24,6 +24,13 @@ When constructing the summary, try to stick to this template:
 
 export interface ICompactMessagesOptions {
   abortSignal?: AbortSignal;
+  /**
+   * Receives the usage of every model call the compaction makes, once per call: `reported` with the
+   * provider's usage, or `unreported` for a call that failed or was aborted, retried attempts
+   * included. A context compactor passes its own options through, so the calls reach the session's
+   * `onUsage`. Must not throw.
+   */
+  reportUsage?: plugins.TAgentModelCallUsageReporter;
 }
 
 /**
@@ -32,7 +39,7 @@ export interface ICompactMessagesOptions {
  *
  * @param model    The same model used by runAgent, or a cheaper small model
  * @param messages The full message history that overflowed
- * @param options  Invocation options, including cancellation
+ * @param options  Invocation options, including cancellation and usage reporting
  * @returns A minimal ModelMessage[] containing the summary as context
  */
 export async function compactMessages(
@@ -40,20 +47,60 @@ export async function compactMessages(
   messages: plugins.ModelMessage[],
   options: ICompactMessagesOptions = {},
 ): Promise<plugins.ModelMessage[]> {
-  const result = await plugins.generateText({
+  const prompt: plugins.ModelMessage[] = [
+    ...messages,
+    { role: 'user', content: COMPACTION_PROMPT },
+  ];
+  const reportUsage = options.reportUsage;
+  if (!reportUsage) {
+    const result = await plugins.generateText({
+      model,
+      abortSignal: options.abortSignal,
+      allowSystemInMessages: true,
+      messages: prompt,
+    });
+    return summaryMessages(result.text);
+  }
+  const modelCalls = new plugins.AgentModelCallUsageRecorder(model, reportUsage);
+  // Each attempt, retries included, is one model call: it starts in the middleware, which also
+  // settles an attempt that throws; a call whose response arrives ends in onLanguageModelCallEnd.
+  const observedModel = plugins.wrapLanguageModel({
     model,
-    abortSignal: options.abortSignal,
-    allowSystemInMessages: true,
-    messages: [
-      ...messages,
-      { role: 'user', content: COMPACTION_PROMPT },
-    ],
+    middleware: {
+      wrapGenerate: async ({ doGenerate, params }) => {
+        modelCalls.start();
+        try {
+          return await doGenerate();
+        } catch (error) {
+          modelCalls.settle(params.abortSignal?.aborted ? 'aborted' : 'failed');
+          throw error;
+        }
+      },
+    },
   });
+  try {
+    const result = await plugins.generateText({
+      model: observedModel,
+      abortSignal: options.abortSignal,
+      allowSystemInMessages: true,
+      messages: prompt,
+      onLanguageModelCallEnd: ({ modelId, usage }) => {
+        modelCalls.end(modelId, usage);
+      },
+    });
+    modelCalls.settle('missing');
+    return summaryMessages(result.text);
+  } catch (error) {
+    modelCalls.settle(options.abortSignal?.aborted ? 'aborted' : 'failed');
+    throw error;
+  }
+}
 
+function summaryMessages(summary: string): plugins.ModelMessage[] {
   return [
     {
       role: 'user',
-      content: `[Previous conversation summary]\n\n${result.text}\n\n[End of summary. Continue from here.]`,
+      content: `[Previous conversation summary]\n\n${summary}\n\n[End of summary. Continue from here.]`,
     },
   ];
 }